From c04052e4dfeb8cd6abd84d7c9009bae81f4b8686 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 17 Apr 2019 14:06:30 +0200 Subject: nls: Update 'de' translation of the manual. --- doc/guix.de.texi | 8194 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 4802 insertions(+), 3392 deletions(-) (limited to 'doc/guix.de.texi') diff --git a/doc/guix.de.texi b/doc/guix.de.texi index 83dae0d3ec..419d40379e 100644 --- a/doc/guix.de.texi +++ b/doc/guix.de.texi @@ -32,9 +32,9 @@ 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, +2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, +2019 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 @@ -46,7 +46,7 @@ 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 +Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019 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 @@ -114,10 +114,10 @@ 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 +Dieses Handbuch ist auch auf Englisch (siehe @ref{Top,,, guix, GNU Guix +Reference Manual}) und Französisch verfügbar (siehe @ref{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. @@ -126,7 +126,7 @@ Project} herzlich willkommen. * Installation:: Guix installieren. * Systeminstallation:: Das ganze Betriebssystem installieren. * Paketverwaltung:: Pakete installieren, aktualisieren usw. -* Development:: Guix-aided software development. +* Entwicklung:: Von Guix unterstützte Softwareentwicklung. * Programmierschnittstelle:: Guix in Scheme verwenden. * Zubehör:: Befehle zur Paketverwaltung. * Systemkonfiguration:: Das Betriebssystem konfigurieren. @@ -153,8 +153,8 @@ Einführung -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. +* Auf Guix-Art Software verwalten:: Was Guix besonders macht. +* GNU-Distribution:: Die Pakete und Werkzeuge. Installation @@ -163,7 +163,7 @@ 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 Testkatalog laufen lassen:: Guix testen. * Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons einrichtet. * Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. @@ -189,10 +189,20 @@ Systeminstallation * 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. +* Geführte grafische Installation:: Leichte grafische Installation. +* Manuelle Installation:: Manuelle Installation für Zauberer. +* Nach der Systeminstallation:: Wenn die Installation erfolgreich war. +* Guix in einer VM installieren:: Ein »Guix System«-Spielplatz. * Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. +Manuelle Installation + + + +* Tastaturbelegung und Netzwerkanbindung und Partitionierung:: Erstes + Einrichten. +* Fortfahren mit der Installation:: Installieren. + Paketverwaltung @@ -223,7 +233,7 @@ Substitute * Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären Blob trauen? -Development +Entwicklung @@ -258,12 +268,12 @@ Zubehör * 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 +* Aufruf von guix hash:: Den kryptografischen 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 size:: Plattenplatzverbrauch profilieren. * Aufruf von guix graph:: Den Paketgraphen visualisieren. * Aufruf von guix publish:: Substitute teilen. * Aufruf von guix challenge:: Die Substitut-Server anfechten. @@ -294,6 +304,7 @@ Systemkonfiguration * Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. * Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. * Benutzerkonten:: Benutzerkonten festlegen. +* Tastaturbelegung:: Wie das System Tastendrücke interpretiert. * Locales:: Sprache und kulturelle Konventionen. * Dienste:: Systemdienste festlegen. * Setuid-Programme:: Mit Administratorrechten startende Programme. @@ -302,7 +313,8 @@ Systemkonfiguration * 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. +* Guix in einer VM starten:: Wie man »Guix System« in einer virtuellen + Maschine startet. * Dienste definieren:: Neue Dienstdefinitionen hinzufügen. Dienste @@ -354,59 +366,67 @@ Dienste definieren @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. +GNU Guix@footnote{»Guix« wird wie »geeks« ausgesprochen, also als »ɡiːks« in +der Notation des Internationalen Phonetischen Alphabets (IPA).} ist ein +Werkzeug zur Verwaltung von Softwarepaketen für das GNU-System und eine +Distribution desselbigen GNU-Systems. Guix macht es @emph{nicht} mit +besonderen Berechtigungen ausgestatteten, »unprivilegierten« Nutzern leicht, +Softwarepakete zu installieren, zu aktualisieren oder zu entfernen, zu einem +vorherigen Satz von Paketen zurückzuwechseln, Pakete aus ihrem Quellcode +heraus zu erstellen und hilft allgemein bei der Erzeugung und Wartung von +Software-Umgebungen. @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}. +@cindex GuixSD, was jetzt Guix System heißt +@cindex Guix System Distribution, welche jetzt Guix System heißt +Sie können GNU@tie{}Guix auf ein bestehendes GNU/Linux-System aufsetzen, wo +es die bereits verfügbaren Werkzeuge ergänzt, ohne zu stören (siehe +@ref{Installation}), oder Sie können es als eine eigenständige +Betriebssystem-Distribution namens @dfn{Guix@tie{}System} +verwenden@footnote{Der Name @dfn{Guix@tie{}System} wird auf englische Weise +ausgesprochen. Früher hatten wir »Guix System« als »Guix System +Distribution« bezeichnet und mit »GuixSD« abgekürzt. Wir denken mittlerweile +aber, dass es sinnvoller ist, alles unter der Fahne von Guix zu gruppieren, +weil schließlich »Guix System« auch über den Befehl @command{guix system} +verfügbar ist, selbst wenn Sie Guix auf einer fremden Distribution +benutzen!}. Siehe @ref{GNU-Distribution}. @menu -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. +* Auf Guix-Art Software verwalten:: Was Guix besonders macht. +* GNU-Distribution:: Die Pakete und Werkzeuge. @end menu -@node Managing Software the Guix Way -@section Managing Software the Guix Way +@node Auf Guix-Art Software verwalten +@section Auf Guix-Art Software verwalten @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}). +Guix bietet eine befehlszeilenbasierte Paketverwaltungsschnittstelle (siehe +@ref{Aufruf von guix package}), Werkzeuge als Hilfestellung bei der +Software-Entwicklung (siehe @ref{Entwicklung}), Befehlszeilenwerkzeuge für +fortgeschrittenere Nutzung (siehe @ref{Zubehör}) sowie Schnittstellen zur +Programmierung in Scheme (siehe @ref{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}). +von Nutzern verantwortlich (siehe @ref{Den Daemon einrichten}) und für das +Herunterladen vorerstellter Binärdateien aus autorisierten Quellen (siehe +@ref{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}). +eigenen Paketdefinitionen schreiben (siehe @ref{Pakete definieren}) und sie +als unabhängige Paketmodule verfügbar machen (siehe @ref{Paketmodule}). Es ist auch @emph{anpassbar}: Nutzer können spezialisierte +Paketdefinitionen aus bestehenden @emph{ableiten}, auch von der Befehlszeile +(siehe @ref{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 +Paketverwaltung}, zu der Nix schon die Pionierarbeit geleistet hat (siehe +@ref{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 @@ -422,36 +442,37 @@ dies zu erreichen, laufen Erstellungsprozesse in isolieren Umgebungen @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 +Store} bezeichnet wird (siehe @ref{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}). +und -rücksetzungen, Installation von Paketen als einfacher Nutzer sowie +Garbage Collection für Pakete (siehe @ref{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. +Mit Guix kommt eine Distribution des GNU-Systems, die nur aus freier +Software@footnote{Die Bezeichnung »frei« steht hier für die +@url{http://www.gnu.org/philosophy/free-sw.html,Freiheiten, die Nutzern der +Software geboten werden}.} besteht. Die Distribution kann für sich allein +installiert werden (siehe @ref{Systeminstallation}), aber Guix kann auch +auf einem bestehenden GNU/Linux-System installiert werden. Wenn wir die +Anwendungsfälle unterscheiden möchten, bezeichnen wir die alleinstehende +Distribution als »Guix@tie{}System« (mit englischer Aussprache). 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}): +einsehen, oder indem Sie @command{guix package} ausführen (siehe +@ref{Aufruf von guix package}): @example guix package --list-available @@ -480,7 +501,7 @@ ARMv7-A-Architektur mit »hard float«, Thumb-2 und NEON, für die EABI @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! +@ref{Mitwirken} steht, wie Sie dabei helfen können! @item mips64el-linux 64-Bit-MIPS-Prozessoren, little-endian, insbesondere die Loongson-Reihe, @@ -488,22 +509,24 @@ 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. +Mit Guix@tie{}System @emph{deklarieren} Sie alle Aspekte der +Betriebssystemkonfiguration und Guix kümmert sich darum, die Konfiguration +auf transaktionsbasierte, reproduzierbare und zustandslose Weise zu +instanziieren (siehe @ref{Systemkonfiguration}). Guix System benutzt den +Kernel Linux-libre, das Shepherd-Initialisierungssystem (siehe +@ref{Einführung,,, shepherd, The GNU Shepherd Manual}), die wohlbekannten +GNU-Werkzeuge mit der zugehörigen Werkzeugkette sowie die grafische Umgebung +und Systemdienste Ihrer Wahl. -Guix System is available on all the above platforms except -@code{mips64el-linux}. +Guix System ist auf allen oben genannten Plattformen außer +@code{mips64el-linux} verfügbar. @noindent Informationen, wie auf andere Architekturen oder Kernels portiert werden -kann, finden Sie im Abschnitt @pxref{Portierung}. +kann, finden Sie im Abschnitt @ref{Portierung}. Diese Distribution aufzubauen basiert auf Kooperation, und Sie sind herzlich -eingeladen, dabei mitzumachen! Im Abschnitt @xref{Mitwirken} stehen +eingeladen, dabei mitzumachen! Im Abschnitt @ref{Mitwirken} stehen weitere Informationen, wie Sie uns helfen können. @@ -514,37 +537,40 @@ weitere Informationen, wie Sie uns helfen können. @cindex Guix installieren @quotation Anmerkung -We recommend the use of this +Wir empfehlen, dieses @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. +Shell-basierte Installationsskript} zu benutzen, um Guix auf ein bestehendes +GNU/Linux-System zu installieren — im Folgenden als @dfn{Fremddistribution} +bezeichnet.@footnote{Dieser Abschnitt bezieht sich auf die Installation des +Paketverwaltungswerkzeugs, das auf ein bestehendes GNU/Linux-System +aufsetzend installiert werden kann. Wenn Sie stattdessen das vollständige +GNU-Betriebssystem installieren möchten, lesen Sie @ref{Systeminstallation}.} Das Skript automatisiert das Herunterladen, das Installieren +und die anfängliche Konfiguration von Guix. Es sollte als der +Administratornutzer »root« ausgeführt werden. @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. +Wenn es auf einer Fremddistribution installiert wird, ergänzt GNU@tie{}Guix +die verfügbaren Werkzeuge, ohne dass sie sich gegenseitig stören. Guix’ +Daten befinden sich ausschließlich in zwei Verzeichnissen, üblicherweise +@file{/gnu/store} und @file{/var/guix}; andere Dateien auf Ihrem System wie +@file{/etc} bleiben unberührt. Sobald es installiert ist, kann Guix durch Ausführen von @command{guix pull} -aktualisiert werden (@pxref{Aufruf von guix pull}). +aktualisiert werden (siehe @ref{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. +Sollten Sie es vorziehen, die Installationsschritte manuell durchzuführen, +oder falls Sie Anpassungen daran vornehmen möchten, könnten sich die +folgenden Unterabschnitte als nützlich erweisen. Diese beschreiben die +Software-Voraussetzungen von Guix und wie man es manuell installiert, so +dass man es benutzen kann. @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 Testkatalog laufen lassen:: Guix testen. * Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons einrichtet. * Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. @@ -608,7 +634,7 @@ ausführen. Danach führen Sie als @code{root}-Nutzer aus: # mv var/guix /var/ && mv gnu / @end example -Dadurch wird @file{/gnu/store} (@pxref{Der Store}) und @file{/var/guix} +Dadurch wird @file{/gnu/store} (siehe @ref{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). @@ -625,7 +651,7 @@ 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}): +@command{guix pull} es aktualisieren kann (siehe @ref{Aufruf von guix pull}): @example # mkdir -p ~root/.config/guix @@ -643,7 +669,7 @@ Umgebungsvariable zu ergänzen: @item Erzeugen Sie Nutzergruppe und Nutzerkonten für die Erstellungs-Benutzer wie -folgt (@pxref{Einrichten der Erstellungsumgebung}). +folgt (siehe @ref{Einrichten der Erstellungsumgebung}). @item Führen Sie den Daemon aus, und lassen Sie ihn automatisch bei jedem @@ -703,14 +729,15 @@ verfügbar zu machen: 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). +@command{info guix.de} dieses Handbuch öffnen (siehe @ref{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: +Um Substitute von @code{@value{SUBSTITUTE-SERVER}} oder einem Spiegelserver +davon zu benutzen (siehe @ref{Substitute}), müssen sie erst autorisiert +werden: @example # guix archive --authorize < \ @@ -719,7 +746,7 @@ mirrors (@pxref{Substitute}), authorize them: @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}. +ihre Guix-Umgebung genutzt werden kann, siehe @ref{Anwendungen einrichten}. @end enumerate Voilà, die Installation ist fertig! @@ -745,14 +772,14 @@ make guix-binary.@var{System}.tar.xz @end example @noindent -...@: which, in turn, runs: +…@: was wiederum dies ausführt: @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 +Siehe @ref{Aufruf von guix pack} für weitere Informationen zu diesem praktischen Werkzeug. @node Voraussetzungen @@ -765,19 +792,19 @@ GNU-Software und wird hier nicht beschrieben. Bitte lesen Sie die Dateien erfahren. @cindex Offizielle Webpräsenz -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. +GNU Guix kann von seiner Webpräsenz unter +@url{http://www.gnu.org/software/guix/} heruntergeladen werden. GNU Guix hat folgende Pakete als Abhängigkeiten: @itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; +@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}), +@uref{http://gnutls.org/, GnuTLS}, im Speziellen dessen Anbindungen für +Guile (siehe @ref{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, @@ -785,7 +812,7 @@ Version 0.1.0 oder neuer, @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 @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 @@ -795,7 +822,7 @@ 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 +Unterstützung für das Auslagern von Erstellungen (siehe @ref{Auslagern des Daemons einrichten}) und @command{guix copy} (siehe @ref{Aufruf von guix copy}) hängt von @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, Version 0.10.2 oder neuer, ab. @@ -819,10 +846,10 @@ 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 +(siehe @ref{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}). +Ihren Store verfälschen (siehe @ref{Der Store}). @cindex Nix, Kompatibilität Wenn eine funktionierende Installation of @url{http://nixos.org/nix/, the @@ -834,15 +861,15 @@ 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 +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 +@node Den Testkatalog laufen lassen +@section Den Testkatalog laufen lassen @cindex Testkatalog Nachdem @command{configure} und @code{make} erfolgreich durchgelaufen sind, @@ -882,12 +909,13 @@ make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" 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}). +von Guix an sowie die Versionsnummern der Abhängigkeiten (siehe +@ref{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: +Guix wird auch mit einem Testkatalog für das ganze System ausgeliefert, der +vollständige Instanzen des »Guix System«-Betriebssystems testet. Er kann nur +auf Systemen benutzt werden, auf denen Guix bereits installiert ist, mit +folgendem Befehl: @example make check-system @@ -906,7 +934,7 @@ 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 +(siehe @ref{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 @@ -964,8 +992,8 @@ 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}). +Funktionalität, da Erstellungen als reine Funktionen angesehen werden (siehe +@ref{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}): @@ -986,12 +1014,12 @@ erzeugt werden (mit Bash-Syntax und den Befehlen von @code{shadow}): @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} vorgegeben werden kann (siehe @ref{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}). +haben, mit @code{-G guixbuild,kvm} statt @code{-G guixbuild} (siehe +@ref{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 @@ -1041,20 +1069,20 @@ Eintrag für den Benutzer @file{nobody}, 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. +Sie können beeinflussen, in welchem Verzeichnis der Daemon Verzeichnisbäume +zur Erstellung 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}). +Ableitungen mit fester Ausgabe (siehe @ref{Ableitungen}) oder für Substitute +(siehe @ref{Substitute}). Wenn Sie Guix als ein Benutzer ohne erweiterte Rechte installieren, ist es dennoch möglich, @command{guix-daemon} auszuführen, sofern Sie @@ -1071,20 +1099,20 @@ Funktionen aufzufassen. @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 +Wenn erwünscht, kann der Erstellungs-Daemon Ableitungserstellungen auf +andere Maschinen @dfn{auslagern}, 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. +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: @@ -1117,9 +1145,9 @@ 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. +(siehe @ref{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 @@ -1128,10 +1156,10 @@ Erstellungen auslagern darf. Die wichtigen Felder sind: @table @code @item name -Der Hostname (d.h. der Rechnername) der entfernten Maschine. +Der Hostname (d.h.@: der Rechnername) der entfernten Maschine. @item system -Der Systemtyp der entfernten Maschine — z.B. @code{"x86_64-linux"}. +Der Systemtyp der entfernten Maschine — z.B.@: @code{"x86_64-linux"}. @item user Das Benutzerkonto, mit dem eine Verbindung zur entfernten Maschine über SSH @@ -1156,8 +1184,8 @@ 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}): +OpenSSH-Format umgewandelt werden durch @command{lsh-export-key} (siehe +@ref{Converting keys,,, lsh, LSH Manual}): @example $ lsh-export-key --openssh < /etc/lsh/host-key.pub @@ -1214,8 +1242,8 @@ 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: +Der Befehl @code{guix} muss sich im Suchpfad der Erstellungsmaschinen +befinden. Um dies nachzuprüfen, können Sie Folgendes ausführen: @example ssh build-machine guix repl --version @@ -1226,7 +1254,7 @@ 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}): +(siehe @ref{Aufruf von guix archive}): @example # guix archive --generate-key @@ -1294,11 +1322,12 @@ diesen Befehl auf dem Hauptknoten aus: @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. +Guix enthält eine SELinux-Richtliniendatei (»Policy«) unter +@file{etc/guix-daemon.cil}, die auf einem System installiert werden kann, +auf dem SELinux aktiviert ist, damit Guix-Dateien gekennzeichnet sind und um +das erwartete Verhalten des Daemons anzugeben. Da Guix System keine +Grundrichtlinie (»Base Policy«) für SELinux bietet, kann diese Richtlinie +für den Daemon auf Guix System nicht benutzt werden. @subsubsection Installieren der SELinux-Policy @cindex SELinux, Policy installieren @@ -1396,7 +1425,7 @@ verfügbar ist, etc. Normalerweise wird er so als Administratornutzer @end example @noindent -Details, wie Sie ihn einrichten, finden Sie im Abschnitt @pxref{Den Daemon einrichten}. +Details, wie Sie ihn einrichten, finden Sie im Abschnitt @ref{Den Daemon einrichten}. @cindex chroot @cindex Container, Erstellungsumgebung @@ -1407,13 +1436,13 @@ 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 +Ableitung (siehe @ref{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}). +reproduzierbare Erstellungen zu garantieren (siehe @ref{Funktionalitäten}). Wenn der Daemon im Auftrag des Nutzers eine Erstellung durchführt, erzeugt er ein Erstellungsverzeichnis, entweder in @file{/tmp} oder im Verzeichnis, @@ -1424,50 +1453,51 @@ läuft, allerdings trägt es im Container stattdessen immer den Namen 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} angegeben hat (siehe @ref{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 +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}. +unter @ref{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}). +auszuführen (siehe @ref{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}). +erstellten Binärdateien erlaubt ist (siehe @ref{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}). +@code{set-build-options} (siehe @ref{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. +@var{URLs} als standardmäßige, leerzeichengetrennte Liste der Quell-URLs für +Substitute benutzen. Wenn diese Befehlszeilenoption @emph{nicht} angegeben +wird, wird @indicateurl{https://@value{SUBSTITUTE-SERVER}} verwendet. 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}). +(siehe @ref{Substitute}). @cindex Build-Hook @item --no-build-hook -Den »@dfn{Build-Hook}« nicht benutzen. +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}). +können Erstellungen an andere Maschinen ausgelagert werden (siehe +@ref{Auslagern des Daemons einrichten}). @item --cache-failures Fehler bei der Erstellung zwischenspeichern. Normalerweise werden nur @@ -1477,7 +1507,7 @@ 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}. +Fehlschläge. Siehe @ref{Aufruf von guix gc}. @item --cores=@var{n} @itemx -c @var{n} @@ -1486,7 +1516,7 @@ 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}). +@command{guix build} (siehe @ref{Aufruf von guix build}). Dadurch wird die Umgebungsvariable @code{NIX_BUILD_CORES} im Erstellungsprozess definiert, welcher sie benutzen kann, um intern parallele @@ -1497,7 +1527,8 @@ Ausführungen zuzulassen — zum Beispiel durch Nutzung von @code{make @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. +lokal durchgeführt, stattdessen lagert der Daemon sie nur aus (siehe +@ref{Auslagern des Daemons einrichten}) oder sie schlagen einfach fehl. @item --max-silent-time=@var{Sekunden} Wenn der Erstellungs- oder Substitutionsprozess länger als @@ -1508,7 +1539,7 @@ 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}}). +(siehe @ref{Gemeinsame Erstellungsoptionen, @code{--max-silent-time}}). @item --timeout=@var{Sekunden} Entsprechend wird hier der Erstellungs- oder Substitutionsprozess @@ -1518,13 +1549,13 @@ abgebrochen und als Fehlschlag gemeldet, wenn er mehr als 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}}). +Clients können einen anderen Wert verwenden lassen (siehe @ref{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}). +anderen Wert verwenden lassen können (siehe @ref{Aufruf von guix build}). Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich unterscheidenden Ausgaben im Store unter dem Namen @@ -1537,7 +1568,7 @@ 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}). +(siehe @ref{Aufruf von guix build}). @item --chroot-directory=@var{Verzeichnis} Füge das @var{Verzeichnis} zum chroot von Erstellungen hinzu. @@ -1587,14 +1618,14 @@ Ableitungen behalten muss (»yes«) oder nicht (»no«). 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. +Müllsammlerwurzel aus erreichbar sind. Siehe den Abschnitt @ref{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 +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. @@ -1630,8 +1661,8 @@ erkannt wurde, wie zum Beispiel @code{x86_64-linux}. 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: +(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 @@ -1655,16 +1686,16 @@ 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} festlegen (siehe @ref{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. +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 @@ -1677,14 +1708,14 @@ Verbindungen auf dem Unix-Socket, der sich unter @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. +Läuft Guix aufgesetzt auf einer GNU/Linux-Distribution außer Guix System — +einer sogenannten @dfn{Fremddistribution} —, so sind ein paar zusätzliche +Schritte bei der Einrichtung nötig. Hier finden Sie manche davon. @subsection Locales @anchor{locales-and-locpath} -@cindex locales, when not on Guix System +@cindex Locales, nicht auf Guix System @vindex LOCPATH @vindex GUIX_LOCPATH Über Guix installierte Pakete benutzen nicht die Daten zu Regions- und @@ -1703,7 +1734,7 @@ 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 +@code{LOCPATH} (siehe @ref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference Manual}). Es gibt jedoch zwei wichtige Unterschiede: @enumerate @@ -1715,7 +1746,7 @@ 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 +@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. @@ -1735,13 +1766,13 @@ 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 +(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}). +darstellt: Hostnamensauflösung, Benutzerkonten und weiteres (siehe @ref{Name Service Switch,,, libc, The GNU C Library Reference Manual}). @cindex Network Information Service (NIS) @cindex NIS (Network Information Service) @@ -1752,8 +1783,8 @@ 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}). +sich an diese Einstellungen (siehe @ref{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 @@ -1786,15 +1817,15 @@ Laden von Schriftarten und für die Darstellung im X11-Client. Im Paket @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 +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: +(siehe @ref{Pakete mit mehreren Ausgaben.}). Zum Beispiel installiert +folgender Befehl Schriftarten für chinesische Sprachen: @example guix package -i font-adobe-source-han-sans:cn @@ -1804,7 +1835,7 @@ guix package -i font-adobe-source-han-sans:cn Ä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: +angegeben wird, z.B.@: so: @example -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 @@ -1843,7 +1874,7 @@ 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 +wissen, wo sie Zertifikate finden. Unter @ref{X.509-Zertifikate} stehen genaue Informationen. @subsection Emacs-Pakete @@ -1857,14 +1888,14 @@ 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}). +benutzen. Das Emacs-Paketsystem organisiert die Dateistruktur ähnlich (siehe +@ref{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 +@code{--no-site-file} starten (siehe @ref{Init File,,, emacs, The GNU Emacs Manual}). @subsection GCC-Toolchain @@ -1880,11 +1911,15 @@ 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}. +Der Zweck des Wrappers ist, die an den Binder übergebenen +Befehlszeilenoptionen mit @code{-L} und @code{-l} zu überprüfen und jeweils +passende Argumente mit @code{-rpath} anzufügen, womit dann der echte Binder +aufgerufen wird. Standardmäßig weigert sich der Binder-Wrapper, mit +Bibliotheken außerhalb des Stores zu binden, um »Reinheit« zu +gewährleisten. Das kann aber stören, wenn man die Toolchain benutzt, um mit +lokalen Bibliotheken zu binden. Um Referenzen auf Bibliotheken außerhalb des +Stores zu erlauben, müssen Sie die Umgebungsvariable +@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} setzen. @c TODO What else? @@ -1892,11 +1927,12 @@ wrapper to refuse to link against libraries not in the store by setting the @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}. +@cindex Installieren von Guix System +@cindex Guix System, Installation +Dieser Abschnitt beschreibt, wie Sie »Guix System« auf einer Maschine +installieren. Guix kann auch als Paketverwaltungswerkzeug ein bestehendes +GNU/Linux-System ergänzen, mehr dazu finden Sie im Abschnitt +@ref{Installation}. @ifinfo @quotation Anmerkung @@ -1904,9 +1940,9 @@ package manager, can also be installed on top of a running GNU/Linux system, @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. +»Enter« genannt) auf folgender Verknüpfung drücken: @ref{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. @@ -1919,66 +1955,53 @@ aus, um dieses Handbuch offen zu lassen. * 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. +* Geführte grafische Installation:: Leichte grafische Installation. +* Manuelle Installation:: Manuelle Installation für Zauberer. +* Nach der Systeminstallation:: Wenn die Installation erfolgreich war. +* Guix in einer VM installieren:: Ein »Guix System«-Spielplatz. * 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}). +We consider Guix System to be ready for a wide range of ``desktop'' and +server use cases. The reliability guarantees it provides---transactional +upgrades and rollbacks, reproducibility---make it a solid foundation. -Bevor Sie mit der Installation fortfahren, beachten Sie die folgenden -merklichen Einschränkungen der Version @value{VERSION}: +Nevertheless, before you proceed with the installation, be aware of the +following noteworthy limitations applicable to 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 +Immer mehr Systemdienste sind verfügbar (siehe @ref{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. +GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop-Dienste}), as well as a number of X11 window managers. However, KDE is +currently missing. @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}. +More than a disclaimer, this is an invitation to report issues (and success +stories!), and to join us in improving it. @xref{Mitwirken}, for more +info. @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 Hardwareunterstützung von Guix System +GNU@tie{}Guix legt den Fokus darauf, die Freiheit des Nutzers auf seinem +Rechner zu respektieren. Es baut auf Linux-libre als Kernel auf, wodurch nur +Hardware unterstützt wird, für die Treiber und Firmware existieren, die +freie Software sind. Heutzutage wird ein großer Teil der handelsüblichen +Hardware von GNU/Linux-libre unterstützt — von Tastaturen bis hin zu +Grafikkarten, Scannern und Ethernet-Adaptern. Leider gibt es noch Bereiche, +wo die Hardwareanbieter ihren Nutzern die Kontrolle über ihren eigenen +Rechner verweigern. Solche Hardware wird von Guix System nicht unterstützt. @cindex WLAN, Hardware-Unterstützung One of the main areas where free drivers or firmware are lacking is WiFi @@ -1987,7 +2010,7 @@ devices. WiFi devices known to work include those using Atheros chips 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, +System, as part of @code{%base-firmware} (@pxref{»operating-system«-Referenz, @code{firmware}}). @cindex RYF, Respects Your Freedom @@ -2008,7 +2031,7 @@ unterstützt werden. @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} +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-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: @@ -2026,8 +2049,8 @@ 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 +$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{System}.iso.xz.sig +$ gpg --verify guix-system-install-@value{VERSION}.@var{System}.iso.xz.sig @end example Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen @@ -2057,7 +2080,7 @@ durch: Entpacken Sie das Abbild mit dem @command{xz}-Befehl: @example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz +xz -d guix-system-install-@value{VERSION}.@var{System}.iso.xz @end example @item @@ -2066,7 +2089,7 @@ 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 +dd if=guix-system-install-@value{VERSION}.@var{System}.iso of=/dev/sdX sync @end example @@ -2083,7 +2106,7 @@ Um das Abbild auf eine DVD zu kopieren, führen Sie diese Schritte durch: Entpacken Sie das Abbild mit dem @command{xz}-Befehl: @example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz +xz -d guix-system-install-@value{VERSION}.@var{System}.iso.xz @end example @item @@ -2092,7 +2115,7 @@ 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 +growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{System}.iso @end example Der Zugriff auf @file{/dev/srX} setzt in der Regel Administratorrechte @@ -2102,32 +2125,35 @@ voraus. @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. +USB-Stick oder der DVD hochfahren (»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). +Lesen Sie den Abschnitt @ref{Guix in einer VM installieren}, wenn Sie Guix System +stattdessen in einer virtuellen Maschine (VM) installieren möchten. @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. +Wenn Sie Ihren Rechner gebootet haben, können Sie sich vom grafischen +Installationsprogramm durch den Installationsvorgang führen lassen, was den +Einstieg leicht macht (siehe @ref{Geführte grafische Installation}). Alternativ können Sie sich auch für einen »manuellen« +Installationsvorgang entscheiden, wenn Sie bereits mit GNU/Linux vertraut +sind und mehr Kontrolle haben möchten, als sie das grafische +Installationsprogramm bietet (siehe @ref{Manuelle Installation}). + +Das grafische Installationsprogramm steht Ihnen auf TTY1 zur Verfügung. Auf +den TTYs 3 bis 6 können Sie vor sich eine Eingabeaufforderung für den +Administratornutzer »root« sehen, nachdem Sie @kbd{strg-alt-f3}, +@kbd{strg-alt-f4} usw.@: gedrückt haben. TTY2 zeigt Ihnen dieses Handbuch, +das Sie über die Tastenkombination @kbd{strg-alt-f2} erreichen. In dieser +Dokumentation können Sie mit den Steuerungsbefehlen Ihres Info-Betrachters +blättern (siehe @ref{Top,,, info-stnd, Stand-alone GNU Info}). Auf dem +Installationssystem läuft der GPM-Maus-Daemon, wodurch Sie Text mit der +linken Maustaste markieren und ihn mit der mittleren Maustaste einfügen +können. @quotation Anmerkung Für die Installation benötigen Sie Zugang zum Internet, damit fehlende @@ -2136,12 +2162,79 @@ 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}). +@node Geführte grafische Installation +@section Geführte grafische Installation + +Das grafische Installationsprogramm ist mit einer textbasierten +Benutzeroberfläche ausgestattet. Es kann Sie mit Dialogfeldern durch die +Schritte führen, mit denen Sie GNU@tie{}Guix System installieren. + +Die ersten Dialogfelder ermöglichen es Ihnen, das System aufzusetzen, wie +Sie es bei der Installation benutzen: Sie können die Sprache und +Tastaturbelegung festlegen und die Netzwerkanbindung einrichten, die während +der Installation benutzt wird. Das folgende Bild zeigt den Dialog zur +Einrichtung der Netzwerkanbindung. + +@image{images/installer-network,5in,, Netzwerkanbindung einrichten mit dem +grafischen Installationsprogramm} + +Mit den danach kommenden Schritten können Sie Ihre Festplatte +partitionieren, wie im folgenden Bild gezeigt, und auswählen, ob Ihre +Dateisysteme verschlüsselt werden sollen oder nicht. Sie können Ihren +Rechnernamen und das Administratorpasswort (das »root«-Passwort) festlegen +und ein Benutzerkonto einrichten, und noch mehr. -@subsection Tastaturbelegung +@image{images/installer-partitions,5in,, Partitionieren mit dem grafischen +Installationsprogramm} + +Beachten Sie, dass Sie mit dem Installationsprogramm jederzeit den aktuellen +Installationsschritt verlassen und zu einem vorherigen Schritt zurückkehren +können, wie Sie im folgenden Bild sehen können. + +@image{images/installer-resume,5in,, Mit einem Installationsschritt +fortfahren} + +Sobald Sie fertig sind, erzeugt das Installationsprogramm eine +Betriebssystemkonfiguration und zeigt sie an (siehe @ref{Das Konfigurationssystem nutzen}). Zu diesem Zeitpunkt können Sie auf »OK« drücken und +die Installation wird losgehen. Ist sie erfolgreich, können Sie neu starten +und Ihr neues System genießen. Siehe @ref{Nach der Systeminstallation} für +Informationen, wie es weitergeht! + + +@node Manuelle Installation +@section Manuelle Installation + +Dieser Abschnitt beschreibt, wie Sie GNU@tie{}Guix System auf manuelle Weise +auf Ihrer Maschine installieren. Diese Alternative setzt voraus, dass Sie +bereits mit GNU/Linux, der Shell und üblichen Administrationswerkzeugen +vertraut sind. Wenn Sie glauben, dass das nichts für Sie ist, dann möchten +Sie vielleicht das geführte grafische Installationsprogramm benutzen (siehe +@ref{Geführte grafische Installation}). + +Das Installationssystem macht Eingabeaufforderungen auf den TTYs 3 bis 6 +zugänglich, auf denen Sie als Administratornutzer Befehle eingeben können; +Sie erreichen diese, indem Sie die Tastenkombinationen @kbd{strg-alt-f3}, +@kbd{strg-alt-f4} und so weiter benutzen. Es enthält viele übliche +Werkzeuge, mit denen Sie diese Aufgabe bewältigen können. Da es sich auch um +ein vollständiges »Guix System«-System handelt, können Sie aber auch andere +Pakete mit dem Befehl @command{guix package} nachinstallieren, wenn Sie sie +brauchen (siehe @ref{Aufruf von guix package}). + +@menu +* Tastaturbelegung und Netzwerkanbindung und Partitionierung:: Erstes + Einrichten. +* Fortfahren mit der Installation:: Installieren. +@end menu + +@node Tastaturbelegung und Netzwerkanbindung und Partitionierung +@subsection Tastaturbelegung, Netzwerkanbindung und Partitionierung + +Bevor Sie das System installieren können, wollen Sie vielleicht die +Tastaturbelegung ändern, eine Netzwerkverbindung herstellen und die +Zielfestplatte partitionieren. Dieser Abschnitt wird Sie durch diese +Schritte führen. + +@subsubsection Tastaturbelegung @cindex Tastaturbelegung Das Installationsabbild verwendet die US-amerikanische @@ -2158,7 +2251,7 @@ Schauen Sie sich an, welche Dateien im Verzeichnis verfügbarer Tastaturbelegungen zu sehen. Wenn Sie mehr Informationen brauchen, führen Sie @command{man loadkeys} aus. -@subsection Netzwerkkonfiguration +@subsubsection Netzwerkkonfiguration Führen Sie folgenden Befehl aus, um zu sehen, wie Ihre Netzwerkschnittstellen benannt sind: @@ -2261,14 +2354,14 @@ Vergewissern Sie sich vorher, dass Sie entweder ein Passwort mit Authentifizierung über öffentliche Schlüssel eingerichtet haben, bevor Sie sich anmelden. -@subsection Plattenpartitionierung +@subsubsection 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 +finden, einschließlich (siehe @ref{Overview,,, parted, GNU Parted User +Manual}), @command{fdisk} und @command{cfdisk}. Starten Sie eines davon und partitionieren Sie Ihre Festplatte oder sonstigen Massenspeicher: @example @@ -2278,16 +2371,17 @@ cfdisk Wenn Ihre Platte mit einer »GUID Partition Table« (GPT) formatiert ist, und Sie vorhaben, die BIOS-basierte Variante des GRUB-Bootloaders zu installieren (was der Vorgabe entspricht), stellen Sie sicher, dass eine -Partition als BIOS-Boot-Partition ausgewiesen ist (@pxref{BIOS +Partition als BIOS-Boot-Partition ausgewiesen ist (siehe @ref{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}: +Falls Sie stattdessen einen EFI-basierten GRUB installieren möchten, muss +auf der Platte eine FAT32-formatierte @dfn{EFI-Systempartition} (ESP) +vorhanden sein. Diese Partition kann unter dem Pfad @file{/boot/efi} +eingebunden (»gemountet«) werden und die @code{esp}-Flag der Partition muss +gesetzt sein. Dazu würden Sie beispielsweise in @command{parted} eintippen: @example parted /dev/sda set 1 esp on @@ -2302,16 +2396,17 @@ installieren möchten: Wenn bei Ihnen das Verzeichnis 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 +wird. Siehe @ref{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: +Sobald Sie die Platte fertig partitioniert haben, auf die Sie installieren +möchten, müssen Sie ein Dateisystem auf Ihrer oder Ihren für Guix System +vorgesehenen Partition(en) erzeugen@footnote{Derzeit unterstützt Guix System +nur die Dateisystemtypen ext4 und btrfs. Insbesondere funktioniert +Guix-Code, der Dateisystem-UUIDs und -Labels ausliest, nur auf diesen +Dateisystemtypen.}. Wenn Sie eine ESP brauchen und dafür die Partition +@file{/dev/sda1} vorgesehen haben, müssen Sie diesen Befehl ausführen: @example mkfs.fat -F32 /dev/sda1 @@ -2319,7 +2414,7 @@ mkfs.fat -F32 /dev/sda1 Geben Sie Ihren Dateisystemen auch besser eine Bezeichnung (»Label«), damit Sie sie zuverlässig wiedererkennen und später in den -@code{file-system}-Deklarationen darauf Bezug nehmen können (@pxref{Dateisysteme}). Dazu benutzen Sie typischerweise die Befehlszeilenoption +@code{file-system}-Deklarationen darauf Bezug nehmen können (siehe @ref{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 @@ -2354,13 +2449,14 @@ des künftigen Wurzeldateisystems ist): 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. +Binden Sie auch alle anderen Dateisysteme ein, die Sie auf dem Zielsystem +benutzen möchten, mit Einhängepunkten relativ zu diesem Pfad. Wenn Sie sich +zum Beispiel für einen Einhängepunkt @file{/boot/efi} für die +EFI-Systempartition entschieden haben, binden Sie sie jetzt als +@file{/mnt/boot/efi} ein, damit @code{guix system init} sie später findet. Wenn Sie zudem auch vorhaben, eine oder mehrere Swap-Partitionen zu benutzen -(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference +(siehe @ref{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: @@ -2373,8 +2469,8 @@ swapon /dev/sda3 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 +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}.}: @@ -2393,7 +2489,7 @@ 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 +@subsection Fortfahren mit der Installation Wenn die Partitionen des Installationsziels bereit sind und dessen Wurzeldateisystem unter @file{/mnt} eingebunden wurde, kann es losgehen mit @@ -2403,7 +2499,7 @@ der Installation. Führen Sie zuerst aus: herd start cow-store /mnt @end example -Dadurch wird @file{/gnu/store} copy-on-write, d.h. dorthin von Guix +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 @@ -2415,7 +2511,7 @@ 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 +empfehlen, dass Sie GNU nano benutzen (siehe @ref{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 @@ -2424,8 +2520,8 @@ 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 +Der Abschnitt @ref{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 @@ -2442,13 +2538,16 @@ 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. +Ihre @code{bootloader-configuration}-Form muss sich auf dasjenige Ziel +beziehen, auf das Sie GRUB installieren möchten. Sie sollte genau dann +@code{grub-bootloader} nennen, wenn Sie GRUB im alten BIOS-Modus +installieren, und für neuere UEFI-Systeme sollten Sie +@code{grub-efi-bootloader} nennen. Bei Altsystemen bezeichnet das +@code{target}-Feld ein Gerät wie @code{/dev/sda}, bei UEFI-Systemen +bezeichnet es den Pfad zu einer eingebundenen EFI-Partition wie +@code{/boot/efi}; stellen Sie sicher, dass die ESP tatsächlich dort +eingebunden ist und ein @code{file-system}-Eintrag dafür in Ihrer +Konfiguration festgelegt wurde. @item Dateisystembezeichnungen müssen mit den jeweiligen @code{device}-Feldern in @@ -2458,7 +2557,7 @@ 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}). +@code{mapped-devices}-Feld genannt werden (siehe @ref{Zugeordnete Geräte}). @end itemize Wenn Sie damit fertig sind, Ihre Konfigurationsdatei vorzubereiten, können @@ -2474,20 +2573,26 @@ guix system init /mnt/etc/config.scm /mnt 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. +Abschnitt @ref{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}). +Passwort, und Passwörter der anderen Nutzer müssen Sie später setzen, indem +Sie den Befehl @command{passwd} als @code{root} ausführen, außer Ihre +Konfiguration enthält schon Passwörter (siehe @ref{user-account-password, +user account passwords}). Siehe @ref{Nach der Systeminstallation} für +Informationen, wie es weiter geht! + -@cindex upgrading Guix System -From then on, you can update the system whenever you want by running, say: +@node Nach der Systeminstallation +@section Nach der Systeminstallation + +Sie haben es geschafft: Sie haben Guix System erfolgreich gebootet! Von +jetzt an können Sie Guix System aktualisieren, wann Sie möchten, indem Sie +zum Beispiel das hier ausführen: @example guix pull @@ -2495,38 +2600,44 @@ 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}). +Dadurch wird eine neue Systemgeneration aus den neuesten Paketen und +Diensten erstellt (siehe @ref{Aufruf von guix system}). Wir empfehlen, diese +Schritte regelmäßig zu wiederholen, damit Ihr System die aktuellen +Sicherheitsaktualisierungen benutzt (siehe @ref{Sicherheitsaktualisierungen}). @c See . @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{}}. +@cindex sudo, Wirkung auf @command{guix pull} +Beachten Sie, dass bei Nutzung von @command{sudo guix} der +@command{guix}-Befehl des aktiven Benutzers ausgeführt wird und @emph{nicht} +der des Administratornutzers »root«, weil @command{sudo} die +Umgebungsvariable @code{PATH} unverändert lässt. Um ausdrücklich das +@command{guix}-Programm des Administrators aufzurufen, müssen Sie +@command{sudo -i guix @dots{}} eintippen. @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. +Besuchen Sie uns auf @code{#guix} auf dem Freenode-IRC-Netzwerk oder auf der +Mailing-Liste @file{guix-devel@@gnu.org}, um uns Rückmeldung zu geben! + -@node Installing Guix in a VM -@section Installing Guix in a Virtual Machine +@node Guix in einer VM installieren +@section Guix in einer virtuellen Maschine installieren -@cindex virtual machine, Guix System installation +@cindex virtuelle Maschine, Guix System installieren @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. +Wenn Sie Guix System auf einer virtuellen Maschine (VM) oder einem »Virtual +Private Server« (VPS) statt auf Ihrer echten Maschine installieren möchten, +ist dieser Abschnitt hier richtig für Sie. -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a -disk image, follow these steps: +Um eine virtuelle Maschine für @uref{http://qemu.org/,QEMU} aufzusetzen, mit +der Sie Guix System in ein »Disk-Image« installieren können (also in eine +Datei mit einem Abbild eines Plattenspeichers), gehen Sie so vor: @enumerate @item -First, retrieve and decompress the Guix system installation image as -described previously (@pxref{Installation von USB-Stick oder DVD}). +Zunächst laden Sie das Installationsabbild des Guix-Systems wie zuvor +beschrieben herunter und entpacken es (siehe @ref{Installation von USB-Stick oder DVD}). @item Legen Sie nun ein Disk-Image an, das das System nach der Installation @@ -2547,7 +2658,7 @@ 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=guix-system-install-@value{VERSION}.@var{System}.iso \ -drive file=guixsd.img @end example @@ -2562,11 +2673,12 @@ 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}. +Sie der Anleitung im Abschnitt @ref{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. +Wurde die Installation abgeschlossen, können Sie das System starten, das +sich nun als Abbild in der Datei @file{guixsd.img} befindet. Der Abschnitt +@ref{Guix in einer VM starten} erklärt, wie Sie das tun können. @node Ein Abbild zur Installation erstellen @section Ein Abbild zur Installation erstellen @@ -2611,11 +2723,11 @@ 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): +beschriebenen Befehlszeilen-Benutzerschnittstellen (siehe @ref{Aufruf von guix package, @code{guix package}}) können Sie auch mit der +Emacs-Guix-Schnittstelle (siehe @ref{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 @@ -2654,11 +2766,11 @@ Zum Beispiel installiert @code{alice} GCC 4.7.2. Dadurch zeigt dann @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. +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 +verwalten (siehe @ref{Aufruf von guix package}). Es arbeitet auf dem eigenen Profil jedes Nutzers und kann @emph{mit normalen Benutzerrechten} ausgeführt werden. @@ -2671,24 +2783,25 @@ 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}). +Zudem kann jede Pakettransaktion @emph{zurückgesetzt} werden +(Rollback). Wird also zum Beispiel durch eine Aktualisierung eine neue +Version eines Pakets installiert, die einen schwerwiegenden Fehler zur Folge +hat, können Nutzer ihr Profil einfach auf die vorherige Profilinstanz +zurücksetzen, von der sie wissen, dass sie gut lief. Ebenso unterliegt bei +Guix auch die globale Systemkonfiguration transaktionellen Aktualisierungen +und Rücksetzungen (siehe @ref{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 +nachweislich nicht mehr referenziert werden (siehe @ref{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 +wie er in der Einleitung beschrieben wurde (siehe @ref{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, @@ -2697,34 +2810,33 @@ 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}). +durchgeführt wird (siehe @ref{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 +andernfalls erstellt Guix das Paket lokal aus seinem Quellcode (siehe +@ref{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}). +Substitute @emph{anfechten} (siehe @ref{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}). +Profil installieren zu müssen (siehe @ref{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. +Guix selbst »in der Zeit zu reisen« (siehe @ref{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} @@ -2737,7 +2849,7 @@ 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: +(siehe @ref{Funktionalitäten}). Die Syntax ist: @example guix package @var{Optionen} @@ -2758,18 +2870,18 @@ guix package -r lua -i guile guile-cairo @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}}). +(siehe @ref{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. +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 +hinzuzufügen (siehe @ref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}), damit in neu erzeugten Shells alle Umgebungsvariablen richtig definiert werden: @@ -2780,7 +2892,7 @@ source "$HOME/.guix-profile/etc/profile" 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 +die @file{$HOME/.guix-profile} zeigt (siehe @ref{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} @@ -2806,14 +2918,13 @@ und einer Versionsnummer, wie @code{guile@@1.8.8} oder auch nur 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}). +@code{binutils@@2.22:lib} (siehe @ref{Pakete mit mehreren Ausgaben.}). Pakete mit zugehörigem Namen (und optional der Version) werden +unter den Modulen der GNU-Distribution gesucht (siehe @ref{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, +Paket installiert werden (im Abschnitt @ref{package-propagated-inputs, @code{propagated-inputs} in @code{package} objects} sind weitere Informationen über propagierte Eingaben in Paketdefinitionen zu finden). @@ -2848,7 +2959,7 @@ Ausgabe eines Pakets mit mehreren Ausgaben gewünscht ist. 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}): +(siehe @ref{Pakete definieren}): @example @verbatiminclude package-hello.scm @@ -2857,7 +2968,7 @@ Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten 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}). +Erstellungsumgebungen aufgebaut werden können (siehe @ref{Aufruf von guix environment}). @item --remove=@var{Paket} @dots{} @itemx -r @var{Paket} @dots{} @@ -2879,7 +2990,7 @@ 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}). +@command{guix pull} ausführen (siehe @ref{Aufruf von guix pull}). @item --do-not-upgrade[=@var{Regexp} @dots{}] In Verbindung mit der Befehlszeilenoption @code{--upgrade}, führe @@ -2936,8 +3047,8 @@ auflösen, zum Beispiel so: @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. +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. @@ -2947,8 +3058,8 @@ 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. +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} @@ -2976,9 +3087,9 @@ 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 +Bibliotheken befinden (siehe @ref{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. @@ -3038,10 +3149,11 @@ Verfügbarkeit von Paketen nachzulesen: @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}). +Führt alle verfügbaren Pakete auf, deren Name, Zusammenfassung oder +Beschreibung zum regulären Ausdruck @var{Regexp} passt, ohne Groß- und +Kleinschreibung zu unterscheiden und sortiert nach ihrer Relevanz. Alle +Metadaten passender Pakete werden im @code{recutils}-Format geliefert (siehe +@ref{Top, GNU recutils databases,, recutils, GNU recutils manual}). So können bestimmte Felder mit dem Befehl @command{recsel} extrahiert werden, zum Beispiel: @@ -3089,7 +3201,7 @@ 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 +kryptografische Bibliotheken, filtert Haskell-, Perl-, Python- und Ruby-Bibliotheken heraus und gibt Namen und Zusammenfassung passender Pakete aus: @@ -3099,13 +3211,14 @@ $ guix package -s crypto -s library | \ @end example @noindent -@xref{Selection Expressions,,, recutils, GNU recutils manual} enthält -weitere Informationen über @dfn{Auswahlausdrücke} mit @code{recsel -e}. +Siehe @ref{Selection Expressions,,, recutils, GNU recutils manual}, es +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}). +@code{recutils}-Format (siehe @ref{Top, GNU recutils databases,, recutils, +GNU recutils manual}). @example $ guix package --show=python | recsel -p name,version @@ -3137,20 +3250,20 @@ 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 +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 +Systems verfügbar sind (siehe @ref{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. +(siehe @ref{Pakete mit mehreren Ausgaben.}) und die Stelle im Quellcode, an +der das Paket definiert ist. @item --list-generations[=@var{Muster}] @itemx -l [@var{Muster}] @@ -3162,7 +3275,8 @@ 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. +Zeichenkette, welcher Teil des Pakets installiert ist (siehe @ref{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: @@ -3212,13 +3326,13 @@ 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 +starten vermag, auch alle gemeinsamen Erstellungsoptionen (siehe @ref{Gemeinsame Erstellungsoptionen}) verwenden. Auch Paketumwandlungsoptionen wie +@option{--with-source} sind möglich (siehe @ref{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}). +(siehe @ref{Pakete definieren}). @node Substitute @section Substitute @@ -3233,7 +3347,7 @@ 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 +ist (siehe @ref{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. @@ -3253,14 +3367,16 @@ einer Ableitungserstellung ist, kann auch er als Substitut verfügbar sein. @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}). +Der Server @code{@value{SUBSTITUTE-SERVER}} ist die Fassade für eine +offizielle »Build-Farm«, ein Erstellungswerk, das kontinuierlich Guix-Pakete +für einige Prozessorarchitekturen erstellt und sie als Substitute zur +Verfügung stellt. Dies ist die standardmäßige Quelle von Substituten; durch +Übergeben der Befehlszeilenoption @option{--substitute-urls} an entweder den +@command{guix-daemon} (siehe @ref{daemon-substitute-urls,, @code{guix-daemon +--substitute-urls}}) oder Client-Werkzeuge wie @command{guix package} (siehe +@ref{client-substitute-urls,, die Befehlszeilenoption +@option{--substitute-urls} beim Client}) kann eine abweichende Einstellung +benutzt werden. Substitut-URLs können entweder HTTP oder HTTPS sein. HTTPS wird empfohlen, weil die Kommunikation verschlüsselt ist; umgekehrt kann bei HTTP die @@ -3269,13 +3385,12 @@ 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. +Sie die Guix-System-Distribution verwenden (siehe @ref{GNU-Distribution}). Auf Fremddistributionen sind sie allerdings standardmäßig +ausgeschaltet, solange Sie sie nicht ausdrücklich in einem der empfohlenen +Installationsschritte erlaubt haben (siehe @ref{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 @@ -3284,28 +3399,32 @@ anderen Substitutsserver zu erlauben. @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: +Um es Guix zu gestatten, Substitute von @code{@value{SUBSTITUTE-SERVER}} +oder einem Spiegelserver davon herunterzuladen, müssen Sie den zugehörigen +öffentlichen Schlüssel zur Access Control List (ACL, +Zugriffssteuerungsliste) für Archivimporte hinzufügen, mit Hilfe des Befehls +@command{guix archive} (siehe @ref{Aufruf von guix archive}). Dies impliziert, +dass Sie darauf vertrauen, dass @code{@value{SUBSTITUTE-SERVER}} nicht +kompromittiert wurde und echte Substitute liefert. + +Der öffentliche Schlüssel für @code{@value{SUBSTITUTE-SERVER}} wird zusammen +mit Guix installiert, in das Verzeichnis +@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, wobei @var{prefix} das bei +der Installation angegebene Präfix von Guix ist. Wenn Sie Guix aus seinem +Quellcode heraus installieren, sollten Sie sichergehen, dass Sie die +GPG-Signatur (auch »Beglaubigung« genannt) von +@file{guix-@value{VERSION}.tar.gz} prüfen, worin sich dieser öffentliche +Schlüssel befindet. Dann können Sie so etwas wie hier ausführen: @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}. +Genauso enthält die Datei @file{hydra.gnu.org.pub} den öffentlichen +Schlüssel für eine unabhängige Build-Farm, die auch vom Guix-Projekt +betrieben wird. Sie ist unter @indicateurl{https://mirror.hydra.gnu.org} +erreichbar ist. @end quotation Sobald es eingerichtet wurde, sollte sich die Ausgabe eines Befehls wie @@ -3335,15 +3454,16 @@ $ guix build emacs --dry-run @end example @noindent -This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are -usable and will be downloaded, when possible, for future builds. +Das zeigt an, dass Substitute von @code{@value{SUBSTITUTE-SERVER}} nutzbar +sind und für zukünftige Erstellungen heruntergeladen werden, wann immer es +möglich ist. @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 +@code{--no-substitutes} übergeben (siehe @ref{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 @@ -3405,7 +3525,7 @@ 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 +@code{--fallback} übergeben wurde (siehe @ref{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 @@ -3417,39 +3537,41 @@ 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. +können Sie den Befehl @command{guix weather} benutzen (siehe @ref{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}). +Derzeit hängt die Kontrolle jedes Individuums über seine Rechner von +Institutionen, Unternehmen und solchen Gruppierungen ab, die über genug +Macht und Entschlusskraft verfügen, die Rechnerinfrastruktur zu sabotieren +und ihre Schwachstellen auszunutzen. Auch wenn es bequem ist, Substitute von +@code{@value{SUBSTITUTE-SERVER}} zu benutzen, ermuntern wir Nutzer, auch +selbst Erstellungen durchzuführen oder gar ihre eigene Build-Farm zu +betreiben, damit @code{@value{SUBSTITUTE-SERVER}} ein weniger interessantes +Ziel wird. Eine Art, uns zu helfen, ist, die von Ihnen erstellte Software +mit dem Befehl @command{guix publish} zu veröffentlichen, damit andere eine +größere Auswahl haben, von welchem Server sie Substitute beziehen möchten +(siehe @ref{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 +Erstellungen zu maximieren (siehe @ref{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 (siehe @ref{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}}). +nachgebaut werden (siehe @ref{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 +diskutieren möchten, kommen Sie auf unsere Mailing-Liste @email{guix-devel@@gnu.org}. @node Pakete mit mehreren Ausgaben. @@ -3459,14 +3581,14 @@ diskuttieren möchten, kommen Sie auf unsere Mailing-Liste @cindex Paketausgaben @cindex Ausgaben -Oft haben in Guix definierte Pakete eine einzige @dfn{Ausgabe} — d.h. aus +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 +Libraries«), statischen Bibliotheken (»Static Libraries«), Dokumentation für Info sowie andere zusätzliche Dateien. Manchmal ist es besser, die verschiedenen Arten von Dateien, die aus einem @@ -3498,16 +3620,16 @@ 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}). +(siehe @ref{Aufruf von guix size}). @command{guix graph} kann auch helfen +(siehe @ref{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}). +Fehlerbehandlung (siehe @ref{Dateien zur Fehlersuche installieren}). Die Ausgaben +eines Pakets stehen in der dritten Spalte der Anzeige von @command{guix +package --list-available} (siehe @ref{Aufruf von guix package}). @node Aufruf von guix gc @@ -3532,12 +3654,14 @@ 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}). +Beispiel mit @command{guix build --root} festgelegt werden (siehe +@ref{Aufruf von guix build}). Der Befehl @command{guix gc --list-roots} listet +sie auf. 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}). +dazu @code{guix package --delete-generations} aus (siehe @ref{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 @@ -3548,12 +3672,14 @@ Verfügung haben, benutzen Sie einfach: 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. +Es ist völlig sicher, dafür eine nicht interaktive, regelmäßige +Auftragsausführung vorzugeben (siehe @ref{Geplante Auftragsausführung} für eine +Erklärung, wie man das tun kann). @command{guix gc} ohne +Befehlszeilenargumente auszuführen, lässt so viel Müll wie möglich sammeln, +aber das ist oft nicht, was man will, denn so muss man unter Umständen +Software erneut erstellen oder erneut herunterladen, weil der Müllsammler +sie als »tot« ansieht, sie aber zur Erstellung anderer Software wieder +gebraucht wird — das trifft zum Beispiel auf die Compiler-Toolchain zu. Der Befehl @command{guix gc} hat drei Arbeitsmodi: Er kann benutzt werden, um als Müllsammler tote Dateien zu entfernen (das Standardverhalten), um @@ -3565,14 +3691,14 @@ 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. +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, +@code{MiB} für Mebibytes und @code{GB} für Gigabytes (siehe @ref{Block size, size specifications,, coreutils, GNU Coreutils}). Wird kein @var{Minimum} angegeben, sammelt der Müllsammler allen Müll. @@ -3586,8 +3712,24 @@ 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-generations[=@var{Dauer}] +@itemx -d [@var{Dauer}] +Bevor der Müllsammelvorgang beginnt, werden hiermit alle Generationen von +allen Benutzerprofilen gelöscht, die älter sind als die angegebene +@var{Dauer}; wird es als Administratornutzer »root« ausgeführt, geschieht +dies mit den Profilen @emph{von allen Benutzern}. + +Zum Beispiel löscht der folgende Befehl alle Generationen Ihrer Profile, die +älter als zwei Monate sind (ausgenommen die momentanen Generationen), und +schmeißt dann den Müllsammler an, um Platz freizuräumen, bis mindestens 10 +GiB verfügbar sind: + +@example +guix gc -d 2m -F 10G +@end example + @item --delete -@itemx -d +@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. @@ -3597,9 +3739,14 @@ 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} gestartet wurde (siehe @ref{Aufruf des guix-daemon, @option{--cache-failures}}). +@item --list-roots +Die Müllsammlerwurzeln auflisten, die dem Nutzer gehören. Wird der Befehl +als Administratornutzer ausgeführt, werden @emph{alle} Müllsammlerwurzeln +aufgelistet. + @item --clear-failures Die angegebenen Store-Objekte aus dem Zwischenspeicher für fehlgeschlagene Erstellungen entfernen. @@ -3634,15 +3781,15 @@ 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 +Der Abschnitt @ref{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 +@ref{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}). +(siehe @ref{Ableitungen}). Zum Beispiel liefert dieser Befehl: @@ -3687,11 +3834,11 @@ der Befehl viel Zeit brauchen, besonders auf Systemen mit langsamer Platte. @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}). +selbige herunterlädt (siehe @ref{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 (siehe @ref{Aufruf von guix build}). @item --optimize @cindex Deduplizieren @@ -3700,7 +3847,7 @@ 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} (siehe @ref{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. @@ -3739,8 +3886,8 @@ 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}): +Sie auch wirklich das neueste Guix und sein Info-Handbuch sehen (siehe +@ref{Dokumentation}): @example export PATH="$HOME/.config/guix/current/bin:$PATH" @@ -3783,8 +3930,8 @@ 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 +Profil, das von @command{guix package} erzeugt wurde (siehe @ref{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 @@ -3801,9 +3948,9 @@ aufgerufen, aber er versteht auch folgende Befehlszeilenoptionen: @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. +Download code for the @code{guix} channel from the specified @var{url}, at +the given @var{commit} (a valid Git commit ID represented as a hexadecimal +string), or @var{branch}. @cindex @file{channels.scm}, Konfigurationsdatei @cindex Konfigurationsdatei für Kanäle @@ -3816,14 +3963,14 @@ die Option @option{--channels} angeben (siehe unten). 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. +wird. Siehe @ref{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}). +--list-generations} (siehe @ref{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 @@ -3841,7 +3988,7 @@ 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 +erstellen — z.B.@: @code{i686-linux} — statt für die Art von System, das die Erstellung durchführt. @item --verbose @@ -3856,10 +4003,10 @@ Befehlszeilenoption ist nur für Guix-Entwickler von Nutzen. 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. +sollen. Im Abschnitt @ref{Kanäle} finden Sie nähere Informationen. Außerdem unterstützt @command{guix pull} alle gemeinsamen -Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}). +Erstellungsoptionen (siehe @ref{Gemeinsame Erstellungsoptionen}). @node Kanäle @section Kanäle @@ -3870,7 +4017,7 @@ Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}). @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 +von @command{guix pull} aktualisieren (siehe @ref{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 @@ -3911,9 +4058,9 @@ 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 +mit diesen Paketdefinitionen schreiben (siehe @ref{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 @@ -3927,8 +4074,8 @@ 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 +die Pakete nicht besser zum eigentlichen Guix-Projekt beisteuern (siehe +@ref{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. @@ -3957,9 +4104,10 @@ 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): +Um einen Kanal zu benutzen, tragen Sie ihn in +@code{~/.config/guix/channels.scm} ein, damit @command{guix pull} diesen +Kanal @emph{zusätzlich} zu den standardmäßigen Guix-Kanälen als Paketquelle +verwendet: @vindex %default-channels @lisp @@ -3971,13 +4119,14 @@ channel(s): @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: +Beachten Sie, dass der obige Schnipsel (wie immer!)@: Scheme-Code ist; mit +@code{cons} fügen wir einen Kanal zur Liste der Kanäle hinzu, an die die +Variable @code{%default-channels} gebunden ist (siehe @ref{Pairs, +@code{cons} and lists,, guile, GNU Guile Reference Manual}). Mit diesem +Dateiinhalt wird @command{guix pull} nun nicht mehr nur Guix, sondern auch +die Paketmodule aus Ihrem Repository erstellen. Das Ergebnis in +@file{~/.config/guix/current} ist so die Vereinigung von Guix und Ihren +eigenen Paketmodulen. @example $ guix pull --list-generations @@ -4003,49 +4152,52 @@ 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}). +Um einen Kanal zu erzeugen, müssen Sie ein Git-Repository mit Ihren eigenen +Paketmodulen erzeugen und den Zugriff darauf ermöglichen. Das Repository +kann beliebigen Inhalt haben, aber wenn es ein nützlicher Kanal sein soll, +muss es Guile-Module enthalten, die Pakete exportieren. Sobald Sie anfangen, +einen Kanal zu benutzen, verhält sich Guix, als wäre das Wurzelverzeichnis +des Git-Repositorys des Kanals in Guiles Ladepfad enthalten (siehe @ref{Load +Paths,,, guile, GNU Guile Reference Manual}). Wenn Ihr Kanal also zum +Beispiel eine Datei als @file{my-packages/my-tools.scm} enthält, die ein +Guile-Modul definiert, dann wird das Modul unter dem Namen +@code{(my-packages my-tools)} verfügbar sein und Sie werden es wie jedes +andere Modul benutzen können (siehe @ref{Module,,, guile, GNU Guile +Reference Manual}). -@cindex dependencies, channels -@cindex meta-data, channels -@subsection Declaring Channel Dependencies +@cindex Abhängigkeiten, bei Kanälen +@cindex Metadaten, bei Kanälen +@subsection Kanalabhängigkeiten deklarieren -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. +Kanalautoren können auch beschließen, die Paketsammlung von anderen Kanälen +zu erweitern. Dazu können sie in einer Metadatendatei @file{.guix-channel} +deklarieren, dass ihr Kanal von anderen Kanälen abhängt. Diese Datei muss im +Wurzelverzeichnis des Kanal-Repositorys platziert werden. -The meta-data file should contain a simple S-expression like this: +Die Metadatendatei sollte einen einfachen S-Ausdruck wie diesen enthalten: @lisp (channel (version 0) (dependencies (channel - (name some-collection) - (url "https://example.org/first-collection.git")) + (name irgendeine-sammlung) + (url "https://example.org/erste-sammlung.git")) (channel - (name some-other-collection) - (url "https://example.org/second-collection.git") + (name eine-andere-sammlung) + (url "https://example.org/zweite-sammlung.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. +Im Beispiel oben wird deklariert, dass dieser Kanal von zwei anderen Kanälen +abhängt, die beide automatisch geladen werden. Die vom Kanal angebotenen +Module werden in einer Umgebung kompiliert, in der die Module all dieser +deklarierten Kanäle verfügbar sind. -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. +Um Verlässlichkeit und Wartbarkeit zu gewährleisten, sollen Sie darauf +verzichten, eine Abhängigkeit von Kanälen herzustellen, die Sie nicht +kontrollieren, außerdem sollten Sie sich auf eine möglichst kleine Anzahl +von Abhängigkeiten beschränken. @subsection Guix nachbilden @@ -4071,7 +4223,7 @@ diese Commits »festgesetzt« ist. @end lisp Der Befehl @command{guix describe --format=channels} kann diese Kanalliste -sogar direkt erzeugen (@pxref{Aufruf von guix describe}). +sogar direkt erzeugen (siehe @ref{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 @@ -4084,7 +4236,7 @@ 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 +@ref{Untergeordnete} beschreibt eine weitere Möglichkeit, diese Superkräfte zu nutzen. @node Untergeordnete @@ -4106,23 +4258,25 @@ 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 +Guix-Prozess, der über eine REPL (siehe @ref{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 +In Kombination mit Kanälen (siehe @ref{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: +ein Manifest für @code{guix package --manifest} schreiben (siehe +@ref{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) @@ -4208,21 +4362,21 @@ Liefert wahr, wenn das @var{obj} ein Untergeordneter ist. @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 +»package« für Pakete (siehe @ref{»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 +dateiartige Objekt in G-Ausdrücken verwendet werden (siehe +@ref{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. +benutzt wird (siehe @ref{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 @@ -4242,7 +4396,7 @@ 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}): +(siehe @ref{Kanäle}): @example $ guix describe @@ -4256,7 +4410,7 @@ Generation 10 Sep 03 2018 17:32:44 (current) 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 +aktuelle Generation (siehe @ref{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 @@ -4279,7 +4433,7 @@ $ guix describe -f channels 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 +installiert wird (siehe @ref{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 @@ -4300,7 +4454,7 @@ 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}), +werden können (siehe @ref{Aufruf von guix pull}), @item json @cindex JSON generiert eine Liste von Kanalspezifikationen im JSON-Format, @@ -4327,7 +4481,7 @@ Store-Objekte von einer Maschine in den Store einer anderen Maschine @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}. +@ref{Aufruf von guix pack}. @end quotation @cindex Store-Objekte exportieren @@ -4339,7 +4493,7 @@ 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 +Paketspezifikationen wie bei @command{guix package} (siehe @ref{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}: @@ -4349,8 +4503,8 @@ guix archive --export git:gui /gnu/store/...-emacs-24.3 > groß.nar 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}). +kann durch die gemeinsamen Erstellungsoptionen gesteuert werden (siehe +@ref{Gemeinsame Erstellungsoptionen}). Um das @code{emacs}-Paket auf eine über SSH verbundene Maschine zu übertragen, würde man dies ausführen: @@ -4375,8 +4529,8 @@ Jedoch sollten Sie in beiden Beispielen beachten, dass alles, was zu 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}). +also, was Sie in diesem Fall wahrscheinlich eher benutzen wollten (siehe +@ref{Aufruf von guix copy}). @cindex Nar, Archivformat @cindex Normalisiertes Archiv (Nar) @@ -4394,10 +4548,10 @@ 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. +digitalen Signatur, auch Beglaubigung genannt. 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: @@ -4442,14 +4596,14 @@ 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{genkey} an (siehe @ref{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 +»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} @@ -4462,12 +4616,12 @@ S-Ausdrücke} und ist als eine Access Control List für die @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} +geliefert wird (siehe @ref{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}: +Zum Beispiel entpackt folgender Befehl das Substitut für Emacs, wie es von +@code{@value{SUBSTITUTE-SERVER}} geliefert wird, nach @file{/tmp/emacs}: @example $ wget -O - \ @@ -4489,19 +4643,20 @@ unter Umständen nicht vertraut wird. @c ********************************************************************* -@node Development -@chapter Development +@node Entwicklung +@chapter Entwicklung -@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. +@cindex Softwareentwicklung +Wenn Sie ein Software-Entwickler sind, gibt Ihnen Guix Werkzeuge an die +Hand, die Sie für hilfreich erachten dürften — ganz unabhängig davon, in +welcher Sprache Sie entwickeln. Darum soll es in diesem Kapitel gehen. -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. +Der Befehl @command{guix environment} stellt eine bequeme Möglichkeit dar, +wie Sie eine @dfn{Entwicklungsumgebung} aufsetzen können, in der all die +Abhängigkeiten und Werkzeuge enthalten sind, die Sie brauchen, wenn Sie an +Ihrem Lieblingssoftwarepaket arbeiten. Der Befehl @command{guix pack} macht +es Ihnen möglich, @dfn{Anwendungsbündel} zu erstellen, die leicht an Nutzer +verteilt werden können, die kein Guix benutzen. @menu * Aufruf von guix environment:: Entwicklungsumgebungen einrichten. @@ -4549,16 +4704,16 @@ 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}. +»source« geladen wird. Siehe @ref{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}): +@file{.bashrc} festzulegen (siehe @ref{Bash Startup Files,,, bash, The GNU +Bash Reference Manual}): @example if [ -n "$GUIX_ENVIRONMENT" ] @@ -4568,7 +4723,7 @@ fi @end example @noindent -...@: or to browse the profile: +…@: oder um ihr Profil durchzusehen: @example $ ls "$GUIX_ENVIRONMENT/bin" @@ -4616,13 +4771,14 @@ umfasst: 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: +Manchmal ist es wünschenswert, die Umgebung so viel wie möglich zu +isolieren, um maximale Reinheit und Reproduzierbarkeit zu +bekommen. Insbesondere ist es wünschenswert, den Zugriff auf @file{/usr/bin} +und andere Systemressourcen aus der Entwicklungsumgebung heraus zu +verhindern, wenn man Guix auf einer fremden Wirtsdistribution benutzt, die +nicht Guix System ist. Zum Beispiel startet der folgende Befehl eine +Guile-REPL in einer isolierten Umgebung, einem sogenannten »Container«, in +der nur der Store und das aktuelle Arbeitsverzeichnis eingebunden sind: @example guix environment --ad-hoc --container guile -- guile @@ -4636,8 +4792,8 @@ Die Befehlszeilenoption @code{--container} funktioniert nur mit Linux-libre Im Folgenden werden die verfügbaren Befehlszeilenoptionen zusammengefasst. @table @code -@item --root=@var{file} -@itemx -r @var{file} +@item --root=@var{Datei} +@itemx -r @var{Datei} @cindex persistente Umgebung @cindex Müllsammlerwurzel, für Umgebungen Die @var{Datei} zu einer symbolischen Verknüpfung auf das Profil dieser @@ -4649,7 +4805,7 @@ Das ist nützlich, um seine Umgebung vor dem Müllsammler zu schützen und sie 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. +Sie vielleicht Pakete neu erstellen oder neu herunterladen. @ref{Aufruf von guix gc} hat mehr Informationen über Müllsammlerwurzeln. @item --expression=@var{Ausdruck} @itemx -e @var{Ausdruck} @@ -4671,7 +4827,7 @@ Wenn man dies ausführt: guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' @end example -starts a shell with all the base system packages available. +bekommt man eine Shell, in der alle Basis-Pakete verfügbar sind. Die obigen Befehle benutzen nur die Standard-Ausgabe des jeweiligen Pakets. Um andere Ausgaben auszuwählen, können zweielementige Tupel @@ -4687,7 +4843,7 @@ 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}): +(siehe @ref{Pakete definieren}): @example @verbatiminclude environment-gdb.scm @@ -4699,8 +4855,8 @@ 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. +@command{guix package} (siehe @ref{profile-manifest, @option{--manifest}}) +und benutzt auch dieselben Manifestdateien. @item --ad-hoc Alle angegebenen Pakete in der resultierenden Umgebung einschließen, als @@ -4720,8 +4876,8 @@ 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.}). +eine bestimmte Ausgabe auszuwählen — z.B.@: wird mit @code{glib:bin} die +Ausgabe @code{bin} von @code{glib} gewählt (siehe @ref{Pakete mit mehreren Ausgaben.}). Diese Befehlszeilenoption kann mit dem standardmäßigen Verhalten von @command{guix environment} verbunden werden. Pakete, die vor @code{--ad-hoc} @@ -4731,35 +4887,36 @@ 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. +Bestehende Umgebungsvariable deaktivieren, wenn die neue Umgebung erzeugt +wird, mit Ausnahme der mit @option{--preserve} angegebenen Variablen (siehe +unten). Dies bewirkt, dass eine Umgebung erzeugt wird, in der die Suchpfade +nur Paketeingaben nennen und sonst nichts. -@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. +@item --preserve=@var{Regexp} +@itemx -E @var{Regexp} +Wenn das hier zusammen mit @option{--pure} angegeben wird, bleiben die zum +regulären Ausdruck @var{Regexp} passenden Umgebungsvariablen erhalten — mit +anderen Worten werden sie auf eine »weiße Liste« von Umgebungsvariablen +gesetzt, die erhalten bleiben müssen. Diese Befehlszeilenoption kann +mehrmals wiederholt werden. @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.) +In diesem Beispiel wird @command{mpirun} in einem Kontext ausgeführt, in dem +die einzig definierten Umgebungsvariablen @code{PATH} und solche sind, deren +Name mit @code{SLURM} beginnt, sowie die üblichen besonders »kostbaren« +Variablen (@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}. +Versuchen, für das angegebene @var{System} zu erstellen — z.B.@: +@code{i686-linux}. @item --container @itemx -C @@ -4770,9 +4927,12 @@ 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. +Datei @file{/etc/passwd}. + +Der erzeugte Prozess läuft außerhalb des Containers als der momentane +Nutzer. Innerhalb des Containers hat er dieselbe UID und GID wie der +momentane Nutzer, außer die Befehlszeilenoption @option{--user} wird +übergeben (siehe unten). @item --network @itemx -N @@ -4805,8 +4965,9 @@ Bei isolierten Umgebungen (»Containern«) wird der Benutzername 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. +die Umgebung übernommen. Des Weiteren sind UID und GID innerhalb der +isolierten Umgebung auf 1000 gesetzt. @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 @@ -4857,9 +5018,10 @@ 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}). +@command{guix environment} unterstützt auch alle gemeinsamen +Erstellungsoptionen, die von @command{guix build} unterstützt werden (siehe +@ref{Gemeinsame Erstellungsoptionen}), und die Paketumwandlungsoptionen (siehe +@ref{Paketumwandlungsoptionen}). @node Aufruf von guix pack @section @command{guix pack} aufrufen @@ -4872,7 +5034,7 @@ 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 +Abschnitte @ref{Aufruf von guix copy}, @ref{Aufruf von guix publish} und @ref{Aufruf von guix archive} werfen. @end quotation @@ -4904,7 +5066,7 @@ Als Ergebnis erhalten Sie einen Tarball mit einem Verzeichnis 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}). +Installation von Guix erzeugt (siehe @ref{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, @@ -4979,7 +5141,7 @@ 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. +Docker Image Specification}, d.h.@: der Spezifikation für Docker-Abbilder. @item squashfs Generiert ein SquashFS-Abbild, das alle angegebenen Binärdateien und @@ -4987,20 +5149,33 @@ symbolischen Verknüpfungen enthält, sowie leere Einhängepunkte für virtuelle Dateisysteme wie procfs. @end table +@cindex pfad-agnostische Binärdateien @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: +von dort ausgeführt werden können. + +Wenn diese Befehlszeilenoption einmal übergeben wird, funktionieren die +erzeugten Binärdateien nur dann, wenn @dfn{Benutzernamensräume} des +Linux-Kernels unterstützt werden. Wenn sie @emph{zweimal}@footnote{Es gibt +einen Trick, wie Sie sich das merken können: @code{-RR}, womit +PRoot-Unterstützung hinzugefügt wird, kann man sich als Abkürzung für +»Rundum Relocatable« oder englisch »Really Relocatable« vorstellen. Ist das +nicht prima?} übergeben wird, laufen die Binärdateien notfalls mit PRoot, +wenn keine Benutzernamensräume zur Verfügung stehen, funktionieren also +ziemlich überall — siehe unten für die Auswirkungen. + +Zum Beispiel können Sie ein Bash enthalltendes Bündel erzeugen mit: @example -guix pack -R -S /meine-bin=bin bash +guix pack -RR -S /mybin=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: +…@: Sie können dieses dann auf eine Maschine ohne Guix kopieren und als +normaler Nutzer aus Ihrem Persönlichen Verzeichnis (auch »Home«-Verzeichnis +genannt) dann ausführen mit: @example tar xf pack.tar.gz @@ -5014,22 +5189,35 @@ 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. +@quotation Anmerkung +Wenn die Voreinstellung verwendet wird, funktionieren pfad-agnostische +Binärdateien 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 diese Funktionalität noch nicht unterstützt und +manche Distributionen von GNU/Linux schalten sie ab. + +Um pfad-agnostische Binärdateien zu erzeugen, die auch ohne +Benutzernamensräume funktionieren, können Sie die Befehlszeilenoption +@option{--relocatable} oder @option{-R} @emph{zweimal} angeben. In diesem +Fall werden die Binärdateien zuerst überprüfen, ob Benutzernamensräume +unterstützt werden, und sonst notfalls PRoot benutzen, um das Programm +auszuführen, wenn Benutzernamensräume nicht unterstützt werden. + +Das Programm @uref{https://proot-me.github.io/, PRoot} bietet auch +Unterstützung für Dateisystemvirtualisierung, indem der Systemaufruf +@code{ptrace} auf das laufende Programm angewendet wird. Dieser Ansatz +funktioniert auch ohne besondere Kernel-Unterstützung, aber das Programm +braucht mehr Zeit, um selbst Systemaufrufe durchzuführen. +@end quotation @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, +in @command{guix build} (siehe @ref{Zusätzliche Erstellungsoptionen, @code{--expression} in @command{guix build}}). @item --manifest=@var{Datei} @@ -5038,25 +5226,25 @@ 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. +@command{guix package} (siehe @ref{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 +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, +gültiges GNU-Tripel wie z.B.@: @code{"mips64el-linux-gnu"} sein (siehe +@ref{Specifying target triplets, GNU configuration triplets,, autoconf, Autoconf}). @item --compression=@var{Werkzeug} @@ -5080,21 +5268,23 @@ 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. +Provenienzinformationen für die auf der Befehlszeile übergebenen Pakete +speichern. Zu den Provenienzinformationen gehören die URL und der Commit +jedes benutzten Kanals (siehe @ref{Kanäle}). + +Provenienzinformationen werden in der Datei +@file{/gnu/store/@dots{}-profile/manifest} im Bündel zusammen mit den +üblichen Paketmetadaten abgespeichert — also Name und Version jedes Pakets, +welche Eingaben dabei propagiert werden und so weiter. Die Informationen +nützen den Empfängern des Bündels, weil sie dann wissen, woraus das Bündel +(angeblich) besteht. + +Der Vorgabe nach wird diese Befehlszeilenoption @emph{nicht} verwendet, weil +Provenienzinformationen genau wie Zeitstempel nichts zum Erstellungsprozess +beitragen. Mit anderen Worten gibt es unendlich viele Kanal-URLs und +Commit-IDs, aus denen dasselbe Bündel stammen könnte. Wenn solche »stillen« +Metadaten Teil des Ausgabe sind, dann wird also die bitweise +Reproduzierbarkeit von Quellcode zu Binärdateien eingeschränkt. @item --localstatedir @itemx --profile-name=@var{Name} @@ -5104,15 +5294,15 @@ aufnehmen, speziell auch das Profil @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. +@file{/var/guix} enthält die Store-Datenbank (siehe @ref{Der Store}) sowie +die Müllsammlerwurzeln (siehe @ref{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}). +umfassende binäre Tarball von Guix (siehe @ref{Aus Binärdatei installieren}). @item --bootstrap Mit den Bootstrap-Binärdateien das Bündel erstellen. Diese Option ist nur @@ -5120,8 +5310,8 @@ 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}). +Erstellungsoptionen (siehe @ref{Gemeinsame Erstellungsoptionen}) und alle +Paketumwandlungsoptionen (siehe @ref{Paketumwandlungsoptionen}). @c ********************************************************************* @@ -5172,16 +5362,17 @@ Dieses Kapitel beschreibt der Reihe nach all diese Programmierschnittstellen @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{} object (@pxref{Pakete definieren}). +Aus Programmierersicht werden die Paketdefinitionen der GNU-Distribution als +Guile-Module in Namensräumen wie @code{(gnu packages @dots{})} sichtbar +gemacht@footnote{Beachten Sie, dass Pakete unter dem Modulnamensraum +@code{(gnu packages @dots{})} nicht notwendigerweise auch »GNU-Pakete« +sind. Dieses Schema für die Benennung von Modulen folgt lediglich den +üblichen Guile-Konventionen: @code{gnu} bedeutet, dass die Module als Teil +des GNU-Systems ausgeliefert werden, und @code{packages} gruppiert Module +mit Paketdefinitionen.} (siehe @ref{Module, Guile modules,, guile, GNU +Guile Reference Manual}). Zum Beispiel exportiert das Modul @code{(gnu +packages emacs)} eine Variable namens @code{emacs}, die an ein +@code{}-Objekt gebunden ist (@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 @@ -5269,28 +5460,28 @@ GNU Hello so aus: 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{}-Objekt, was an sich nur ein Verbund -(Record) ist (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference +(Record) ist (siehe @ref{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}). +@code{guix import} verwenden (siehe @ref{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}). +automatisch von den Befehlszeilenwerkzeugen gefunden (siehe @ref{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{}-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 +@code{}-Objekt, was den Paketursprung angibt (siehe @ref{»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 @@ -5300,8 +5491,8 @@ 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}). +base32-Darstellung mit Hilfe der Befehle @code{guix download} (siehe +@ref{Aufruf von guix download}) und @code{guix hash} (siehe @ref{Aufruf von guix hash}). @cindex Patches Wenn nötig kann in der @code{origin}-Form auch ein @code{patches}-Feld @@ -5312,14 +5503,14 @@ 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 +erstellt werden soll (siehe @ref{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 +mitgegeben werden sollen (siehe @ref{Erstellungssysteme}). In diesem Fall interpretiert @var{gnu-build-system} diese als Auftrag, @file{configure} mit der Befehlszeilenoption @code{--enable-silent-rules} auszuführen. @@ -5330,24 +5521,24 @@ der Befehlszeilenoption @code{--enable-silent-rules} auszuführen. 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}). +synonym mit @code{quote}. @ref{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} (siehe +@ref{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}). +Scheme-@dfn{Schlüsselwort} (siehe @ref{Keywords,,, guile, GNU Guile +Reference Manual}) und @code{#:configure-flags} ist ein Schlüsselwort, um +eine Befehlszeilenoption an das Erstellungssystem mitzugeben (siehe +@ref{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{}-Objekt als Variablenwert gebunden. +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{}-Objekt als Variablenwert gebunden. @cindex Backquote (Quasimaskierung) @findex ` @@ -5362,12 +5553,13 @@ 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}). +diese Liste einzufügen (siehe @ref{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}). +@var{gnu-build-system} dafür, dass diese vorhanden sein müssen (siehe +@ref{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 @@ -5375,41 +5567,43 @@ Erstellungsprozesses schlicht nicht verfügbar sein, woraus ein Erstellungsfehler resultieren kann. @end itemize -Siehe @xref{»package«-Referenz} für eine umfassende Beschreibung aller +Siehe @ref{»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. +(siehe @ref{Aufruf von guix build}) und dabei jegliche Erstellungsfehler, auf +die Sie stoßen, beseitigen (siehe @ref{Fehlschläge beim Erstellen untersuchen}). Sie +können den Befehl @command{guix edit} benutzen, um leicht zur +Paketdefinition zurückzuspringen (siehe @ref{Aufruf von guix edit}). Unter +@ref{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 +Zuletzt finden Sie unter @ref{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}). +Befehl @command{guix refresh} teilweise automatisieren können (siehe +@ref{Aufruf von guix refresh}). Hinter den Kulissen wird die einem @code{}-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}). +@code{build-derivations} umgesetzt werden (siehe @ref{Der Store}). @deffn {Scheme-Prozedur} package-derivation @var{Store} @var{Paket} [@var{System}] Das @code{}-Objekt zum @var{Paket} für das angegebene -@var{System} liefern (@pxref{Ableitungen}). +@var{System} liefern (siehe @ref{Ableitungen}). Als @var{Paket} muss ein gültiges @code{}-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 +— 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}). +Operationen auf dem Store durchführt (siehe @ref{Der Store}). @end deffn @noindent @@ -5423,8 +5617,8 @@ ein anderes System cross-erstellt. @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 +Ziel-Hardware und das zugehörige Betriebssystem beschreibt, wie z.B.@: +@code{"mips64el-linux-gnu"} (siehe @ref{Configuration Names, GNU configuration triplets,, configure, GNU Configure and Build System}). @end deffn @@ -5466,8 +5660,31 @@ Betrachten Sie dieses Beispiel: 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}}). +genau, was auch die Befehlszeilenoption @option{--with-input} tut (siehe +@ref{Paketumwandlungsoptionen, @option{--with-input}}). + +The following variant of @code{package-input-rewriting} can match packages +to be replaced by name rather than by identity. + +@deffn {Scheme-Prozedur} package-input-rewriting/spec @var{Ersetzungen} +Return a procedure that, given a package, applies the given +@var{replacements} to all the package graph (excluding implicit inputs). +@var{replacements} is a list of spec/procedures pair; each spec is a package +specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure +takes a matching package and returns a replacement for that package. +@end deffn + +The example above could be rewritten this way: + +@example +(define libressl-statt-openssl + ;; Rekursiv alle Pakete namens "openssl" durch LibreSSL ersetzen. + (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) +@end example + +The key difference here is that, this time, packages are matched by spec and +not by identity. In other words, any package in the graph that is called +@code{openssl} will be replaced. Eine allgemeiner anwendbare Prozedur, um den Abhängigkeitsgraphen eines Pakets umzuschreiben, ist @code{package-mapping}. Sie unterstützt beliebige @@ -5491,7 +5708,7 @@ findet kein rekursiver Abstieg in dessen Abhängigkeiten statt. @subsection @code{package}-Referenz Dieser Abschnitt fasst alle in @code{package}-Deklarationen zur Verfügung -stehenden Optionen zusammen (@pxref{Pakete definieren}). +stehenden Optionen zusammen (siehe @ref{Pakete definieren}). @deftp {Datentyp} package Dieser Datentyp steht für ein Paketrezept. @@ -5506,13 +5723,14 @@ 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}}). +Internet heruntergeladene Datei steht (siehe @ref{»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 (siehe @ref{G-Ausdrücke, @code{local-file}}). @item @code{build-system} -Das Erstellungssystem, mit dem das Paket erstellt werden soll (@pxref{Erstellungssysteme}). +Das Erstellungssystem, mit dem das Paket erstellt werden soll (siehe +@ref{Erstellungssysteme}). @item @code{arguments} (Vorgabe: @code{'()}) Die Argumente, die an das Erstellungssystem übergeben werden sollen. Dies @@ -5528,7 +5746,7 @@ 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 +(siehe @ref{Pakete mit mehreren Ausgaben.} für mehr Informationen zu Paketausgaben). Im folgenden Beispiel etwa werden drei Eingaben festgelegt: @example @@ -5549,13 +5767,13 @@ der erstellenden Maschine (@emph{build}) erstellt. 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}). +Auflistung sind (siehe @ref{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 +@ref{package-cmd-propagated-inputs, @command{guix package}} für Informationen darüber, wie @command{guix package} mit propagierten Eingaben umgeht). @@ -5572,13 +5790,9 @@ 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 +@ref{Pakete mit mehreren Ausgaben.} beschreibt übliche Nutzungen zusätzlicher Ausgaben. @item @code{native-search-paths} (Vorgabe: @code{'()}) @@ -5590,7 +5804,7 @@ 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. +@ref{Sicherheitsaktualisierungen, grafts} wird dies erklärt. @item @code{synopsis} Eine einzeilige Beschreibung des Pakets. @@ -5621,12 +5835,33 @@ dieses Feld nicht automatisch berichtigt wird. @end table @end deftp +@deffn {Scheme Syntax} this-package +When used in the @emph{lexical scope} of a package field definition, this +identifier resolves to the package being defined. + +The example below shows how to add a package as a native input of itself +when cross-compiling: + +@example +(package + (name "guile") + ;; ... + + ;; When cross-compiled, Guile, for example, depends on + ;; a native version of itself. Add it here. + (native-inputs (if (%current-target-system) + `(("self" ,this-package)) + '()))) +@end example + +It is an error to refer to @code{this-package} outside a package definition. +@end deffn @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}). +@code{origin}-Deklarationen zur Verfügung stehen (siehe @ref{Pakete definieren}). @deftp {Datentyp} origin Mit diesem Datentyp wird ein Ursprung, von dem Quellcode geladen werden @@ -5643,7 +5878,7 @@ eine Liste solcher URLs. @item @code{method} Eine Prozedur, die die URI verwertet. -Beispiele sind unter Anderem: +Beispiele sind unter anderem: @table @asis @item @var{url-fetch} aus @code{(guix download)} @@ -5669,8 +5904,8 @@ 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}). +Diese Informationen liefert Ihnen der Befehl @code{guix download} (siehe +@ref{Aufruf von guix download}) oder @code{guix hash} (siehe @ref{Aufruf von guix hash}). @item @code{file-name} (Vorgabe: @code{#f}) Der Dateiname, unter dem der Quellcode abgespeichert werden sollte. Wenn er @@ -5681,8 +5916,8 @@ 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 +Eine Liste von Dateinamen, Ursprüngen oder dateiähnlichen Objekten (siehe +@ref{G-Ausdrücke, file-like objects}) mit Patches, welche auf den Quellcode anzuwenden sind. Die Liste von Patches kann nicht von Parametern der Erstellung @@ -5690,8 +5925,8 @@ 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 +Ein im Quellcode-Verzeichnis auszuführender G-Ausdruck (siehe +@ref{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")}) @@ -5718,7 +5953,7 @@ Welches Guile-Paket für den Patch-Prozess benutzt werden sollte. Bei @cindex Erstellungssystem Jede Paketdefinition legt ein @dfn{Erstellungssystem} (»build system«) sowie -dessen Argumente fest (@pxref{Pakete definieren}). Das +dessen Argumente fest (siehe @ref{Pakete definieren}). Das @code{build-system}-Feld steht für die Erstellungsprozedur des Pakets sowie für weitere implizite Eingaben für die Erstellungsprozedur. @@ -5733,16 +5968,17 @@ Intern funktionieren Erstellungssysteme, indem erst Paketobjekte zu 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}). +Zwischendarstellung wird dann zur eigentlichen Ableitung kompiliert (siehe +@ref{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}). +(siehe @ref{Pakete definieren}). Sie sind in der Regel +Schlüsselwort-Argumente (siehe @ref{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 +(siehe @ref{Ableitungen}). Das häufigste Erstellungssystem ist @var{gnu-build-system}, was die übliche Erstellungsprozedur für GNU-Pakete und viele andere Pakete darstellt. Es @@ -5750,8 +5986,8 @@ 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}). +desselben (siehe @ref{Configuration, configuration and makefile +conventions,, standards, GNU Coding Standards}). @cindex Erstellungsphasen Kurz gefasst werden Pakete, die es benutzen, konfiguriert, erstellt und @@ -5775,8 +6011,8 @@ Store-Dateipfade beziehen. Zum Beispiel könnte @code{#!/bin/sh} zu @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. +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 @@ -5800,7 +6036,8 @@ 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}). +@code{debug}-Ausgabe kopieren, falls diese verfügbar ist (siehe +@ref{Dateien zur Fehlersuche installieren}). @end table @vindex %standard-phases @@ -5910,8 +6147,8 @@ 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}. +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 @@ -6038,21 +6275,23 @@ 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 +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. +@defvr {Scheme-Variable} dune-build-system +Diese Variable wird vom Modul @code{(guix build-system dune)} +exportiert. Sie unterstützt es, Pakete mit @uref{https://dune.build/, Dune} +zu erstellen, einem Erstellungswerkzeug für die Programmiersprache OCaml, +und ist als Erweiterung des unten beschriebenen OCaml-Erstellungssystems +@code{ocaml-build-system} implementiert. Als solche können auch die +Parameter @code{#:ocaml} und @code{#:findlib} an dieses Erstellungssystem +übergeben werden. -It automatically adds the @code{dune} package to the set of inputs. Which -package is used can be specified with the @code{#:dune} parameter. +Das Erstellungssystem fügt automatisch das Paket @code{dune} zu den Eingaben +hinzu. Welches Paket benutzt wird, kann mit dem Parameter @code{#:dune} +geändert werden. 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 @@ -6061,6 +6300,11 @@ 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}. + +The @code{#:package} parameter can be passed to specify a package name, +which is useful when a package contains multiple packages and you want to +build only one of them. This is equivalent to passing the @code{-p} +argument to @code{dune}. @end defvr @defvr {Scheme-Variable} go-build-system @@ -6081,11 +6325,11 @@ 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. +Pakete, die Go-Bibliotheken zur Verfügung stellen, sollten ihren Quellcode +auch in die Erstellungsausgabe installieren. 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 @@ -6128,10 +6372,10 @@ Beide Phasen finden nach der @code{install}-Phase statt. 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. +wird Scheme-Code mit @command{guild compile} kompiliert (siehe +@ref{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}. @@ -6211,7 +6455,7 @@ zeigt auf @file{lib/ocaml/site-lib/stubslibs} und dorthin sollten @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 +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{}}. @@ -6266,6 +6510,23 @@ Paketeingaben enthält. Tests werden nach der Installation mit der R-Funktion @code{tools::testInstalledPackage} ausgeführt. @end defvr +@defvr {Scheme-Variable} rakudo-build-system +This variable is exported by @code{(guix build-system rakudo)} It implements +the build procedure used by @uref{https://rakudo.org/, Rakudo} for +@uref{https://perl6.org/, Perl6} packages. It installs the package to +@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the +binaries, library files and the resources, as well as wrap the files under +the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the +@code{tests?} parameter. + +Which rakudo package is used can be specified with @code{rakudo}. Which +perl6-tap-harness package used for the tests can be specified with +@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} +parameter. Which perl6-zef package used for tests and installing can be +specified with @code{#:zef} or removed by passing @code{#f} to the +@code{with-zef?} parameter. +@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«) @@ -6370,8 +6631,8 @@ festgelegt werden, was als Vorgabewert @code{ldc} benutzt. @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}). +Paketsystems von Emacs selbst implementiert (siehe @ref{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 @@ -6382,11 +6643,12 @@ gelöscht. Jedes Paket wird in sein eigenes Verzeichnis unter @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. +Diese Variable wird vom Modul @code{(guix build-system font)} +exportiert. Mit ihr steht eine Installationsprozedur für Schriftarten-Pakete +zur Verfügung für vom Anbieter vorkompilierte TrueType-, OpenType- und +andere Schriftartendateien, die nur an die richtige Stelle kopiert werden +müssen. Dieses Erstellungssystem kopiert die Schriftartendateien an den +Konventionen folgende Orte im Ausgabeverzeichnis. @end defvr @defvr {Scheme-Variable} meson-build-system @@ -6456,6 +6718,33 @@ durchlaufen. Wenn sie gebraucht wird, kann sie mit dem Parameter @end table @end defvr +@defvr {Scheme Variable} linux-module-build-system +@var{linux-module-build-system} allows building Linux kernel modules. + +@cindex Erstellungsphasen +This build system is an extension of @var{gnu-build-system}, but with the +following phases changed: + +@table @code + +@item configure +This phase configures the environment so that the Linux kernel's Makefile +can be used to build the external kernel module. + +@item build +This phase uses the Linux kernel's Makefile in order to build the external +kernel module. + +@item install +This phase uses the Linux kernel's Makefile in order to install the external +kernel module. +@end table + +It is possible and useful to specify the Linux kernel to use for building +the module (in the "arguments" form of a package using the +linux-module-build-system, use the key #:linux to specify it). +@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 @@ -6466,7 +6755,7 @@ 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} (siehe @ref{Ableitungen, @code{build-expression->derivation}}). @end defvr @@ -6490,7 +6779,7 @@ 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, +zugegriffen (siehe @ref{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). @@ -6499,11 +6788,11 @@ entfernter Prozeduraufruf (englisch »Remote Procedure Call« oder kurz RPC). 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}). +dahin (siehe @ref{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. +Siehe @ref{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 @@ -6543,23 +6832,23 @@ guix://master.guix.example.org:1234 Diese Konfiguration ist für lokale Netzwerke wie etwa in Rechen-Clustern geeignet, wo sich nur vertrauenswürdige Knoten mit dem Erstellungs-Daemon -z.B. unter @code{master.guix.example.org} verbinden können. +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}}). +benutzt werden, damit er auf TCP-Verbindungen lauscht (siehe @ref{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: +(siehe @ref{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}). +OpenSSH-Client-Konfigurationsdateien (siehe @ref{Aufruf von guix copy}). @end table In Zukunft könnten weitere URI-Schemata unterstützt werden. @@ -6569,8 +6858,8 @@ In Zukunft könnten weitere URI-Schemata unterstützt werden. @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}). +uns jegliche Probleme oder Vorschläge, die Sie haben könnten (siehe +@ref{Mitwirken}). @end quotation @end defvr @@ -6607,8 +6896,9 @@ 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}). +Ein @code{&store-protocol-error}-Fehlerzustand wird ausgelöst, wenn der +@var{Pfad} nicht mit dem Store-Verzeichnis als Präfix beginnt +(@file{/gnu/store}). @end deffn @deffn {Scheme-Prozedur} add-text-to-store @var{Server} @var{Name} @var{Text} [@var{Referenzen}] @@ -6626,7 +6916,7 @@ Erstellung. 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}). +auf den Store zugreift, bequemer gearbeitet werden kann (siehe @ref{Die Store-Monade}). @c FIXME @i{Dieser Abschnitt ist im Moment noch unvollständig.} @@ -6645,15 +6935,15 @@ 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.) +@cindex Erstellungszeitabhängigkeiten +@cindex Abhängigkeiten zur Erstellungszeit +Die Eingaben der Ableitung, also Abhängigkeiten zur Zeit ihrer Erstellung, +die entweder andere Ableitungen oder einfache Dateien im Store sind (wie +Patches, Erstellungsskripts usw.). @item -Das System, wofür mit der Ableitung erstellt wird, also ihr Ziel — -z.B. @code{x86_64-linux}. +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 @@ -6671,27 +6961,28 @@ 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}). +niedergeschriebenen Erstellungsaktionen durchgeführt werden (siehe @ref{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. +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. +@cindex Laufzeitabhängigkeiten +@cindex Abhängigkeiten, zur Laufzeit +Den Ausgaben von Ableitungen — d.h.@: Erstellungergebnissen — ist eine Liste +von @dfn{Referenzen} zugeordnet, die auch der entfernte Prozeduraufruf +@code{references} oder der Befehl @command{guix gc --references} liefert +(siehe @ref{Aufruf von guix gc}). Referenzen sind die Menge der +Laufzeitabhängigkeiten von Erstellungsergebnissen. Referenzen sind eine +Teilmenge der Eingaben von Ableitungen; die Teilmenge wird automatisch +ermittelt, indem der Erstellungsdaemon alle Dateien unter den Ausgaben nach +Referenzen durchsucht. Das Modul @code{(guix derivations)} stellt eine Repräsentation von Ableitungen als Scheme-Objekte zur Verfügung, zusammen mit Prozeduren, um @@ -6708,9 +6999,9 @@ Methode, eine Ableitung zu erzeugen, ist mit der Prozedur @code{derivation}: 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 +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. @@ -6734,14 +7025,14 @@ ist. So ein Leck kann zum Beispiel benutzt werden, um Variable wie 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 +das Auslagern deklariert, der besser lokal erstellt werden sollte (siehe +@ref{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. +Ableitung keine Substitute benutzt werden sollen (siehe +@ref{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 @@ -6772,7 +7063,7 @@ 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}. +Abschnitt @ref{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 @@ -6793,8 +7084,8 @@ 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))}. +@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 @@ -6897,7 +7188,7 @@ gelieferte monadische Wert wurde mit @code{mlet} statt einem einfachen 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}): +werden (siehe @ref{G-Ausdrücke}): @example (define (sh-symlink) @@ -6999,7 +7290,8 @@ 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}). +@code{let} (siehe @ref{Local Bindings,,, guile, GNU Guile Reference +Manual}). @end deffn @deffn {Scheme-System} mbegin @var{Monade} @var{mAusdruck} ... @@ -7159,7 +7451,7 @@ Zielsystem bezeichnendes Tripel zum Cross-Kompilieren benutzt. @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}). +und @code{package-cross-derivation} (siehe @ref{Pakete definieren}). @end deffn @@ -7170,10 +7462,10 @@ und @code{package-cross-derivation} (@pxref{Pakete definieren}). @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 +erzeugen (siehe @ref{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}). +sogenannten Container) aus (siehe @ref{Aufruf des guix-daemon}). @cindex Schichten von Code Wenig überraschend ist, dass wir diese Erstellungsaktionen gerne in Scheme @@ -7185,7 +7477,7 @@ an Hop geprägt. Oleg Kiselyov, der aufschlussreiche 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 +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. @@ -7203,7 +7495,7 @@ S-Ausdrücken, die zu Erstellungsausdrücken angepasst wurden. G-Ausdrücke 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{unquote-splicing} vergleichbar sind (siehe @ref{Expression Syntax, @code{quasiquote},, guile, GNU Guile Reference Manual}). Es gibt aber auch erhebliche Unterschiede: @@ -7230,7 +7522,7 @@ 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 +anderem referenziert werden (siehe unten @code{local-file} und @code{plain-file}). Zur Veranschaulichung dieser Idee soll uns dieses Beispiel eines G-Ausdrucks @@ -7363,7 +7655,7 @@ kann eine oder mehrere der folgenden Formen enthalten: 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}. +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. @@ -7378,7 +7670,7 @@ eingefügt. @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.}). +@var{Objekt} mehrere Ausgaben generiert (siehe @ref{Pakete mit mehreren Ausgaben.}). @item #+@var{Objekt} @itemx #+@var{Objekt}:@var{Ausgabe} @@ -7456,7 +7748,8 @@ Liefert @code{#t}, wenn das @var{Objekt} ein G-Ausdruck ist. G-Ausdrücke sind dazu gedacht, auf die Platte geschrieben zu werden, entweder als Code, der eine Ableitung erstellt, oder als einfache Dateien im -Store. Die monadischen Prozeduren unten ermöglichen Ihnen das (@pxref{Die Store-Monade}, wenn Sie mehr Informationen über Monaden suchen). +Store. Die monadischen Prozeduren unten ermöglichen Ihnen das (siehe +@ref{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] @@ -7479,12 +7772,12 @@ bezeichnete Pakete benutzt. 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 +@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"}. +@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. @@ -7518,8 +7811,8 @@ 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}). +Die anderen Argumente verhalten sich wie bei @code{derivation} (siehe +@ref{Ableitungen}). @end deffn @cindex dateiartige Objekte @@ -7563,7 +7856,7 @@ 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}}). +@code{interned-file} (siehe @ref{Die Store-Monade, @code{interned-file}}). @end deffn @deffn {Scheme-Prozedur} plain-file @var{Name} @var{Inhalt} @@ -7601,7 +7894,7 @@ Folgendes Beispiel erstellt ein Skript, das einfach nur den Befehl "ls")) @end example -Lässt man es durch den Store »laufen« (siehe @pxref{Die Store-Monade, +Lässt man es durch den Store »laufen« (siehe @ref{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: @@ -7774,12 +8067,13 @@ zum Beispiel ein @code{}. @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: +Der Befehl @command{guix repl} startet eine Guile-REPL (@dfn{Read-Eval-Print +Loop}, kurz REPL, deutsch Lese-Auswerten-Schreiben-Schleife) zur +interaktiven Programmierung (siehe @ref{Using Guile Interactively,,, guile, +GNU Guile Reference Manual}). Im Vergleich dazu, einfach den Befehl +@command{guile} aufzurufen, garantiert @command{guix repl}, dass alle +Guix-Module und deren Abhängigkeiten im Suchpfad verfügbar sind. Sie können +die REPL so benutzen: @example $ guix repl @@ -7789,37 +8083,40 @@ $1 = # @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. +@command{guix repl} implementiert zusätzlich ein einfaches maschinenlesbares +Protokoll für die REPL, das von @code{(guix inferior)} benutzt wird, um mit +@dfn{Untergeordneten} zu interagieren, also mit getrennten Prozessen einer +womöglich anderen Version von 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: +@item --type=@var{Typ} +@itemx -t @var{Typ} +Startet eine REPL des angegebenen @var{Typ}s, der einer der Folgenden sein +darf: @table @code @item guile -This is default, and it spawns a standard full-featured Guile REPL. +Die Voreinstellung, mit der eine normale, voll funktionsfähige Guile-REPL +gestartet wird. @item machine -Spawn a REPL that uses the machine-readable protocol. This is the protocol -that the @code{(guix inferior)} module speaks. +Startet eine REPL, die ein maschinenlesbares Protokoll benutzt. Dieses +Protokoll wird vom Modul @code{(guix inferior)} gesprochen. @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: +Der Vorgabe nach würde @command{guix repl} von der Standardeingabe lesen und +auf die Standardausgabe schreiben. Wird diese Befehlszeilenoption angegeben, +lauscht die REPL stattdessen auf dem @var{Endpunkt} auf Verbindungen. Hier +sind Beispiele gültiger Befehlszeilenoptionen: @table @code @item --listen=tcp:37146 -Accept connections on localhost on port 37146. +Verbindungen mit dem »localhost« auf Port 37146 akzeptieren. @item --listen=unix:/tmp/socket -Accept connections on the Unix-domain socket @file{/tmp/socket}. +Verbindungen zum Unix-Socket @file{/tmp/socket} akzeptieren. @end table @end table @@ -7838,12 +8135,12 @@ Befehle. * 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 +* Aufruf von guix hash:: Den kryptografischen 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 size:: Plattenplatzverbrauch profilieren. * Aufruf von guix graph:: Den Paketgraphen visualisieren. * Aufruf von guix publish:: Substitute teilen. * Aufruf von guix challenge:: Die Substitut-Server anfechten. @@ -7862,9 +8159,9 @@ Befehle. 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. +eine solche Installation bewirkt der Befehl @command{guix package} (siehe +@ref{Aufruf von guix package}). @command{guix build} wird also hauptsächlich +von Entwicklern der Distribution benutzt. Die allgemeine Syntax lautet: @@ -7892,7 +8189,7 @@ 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}). +Version) in den Modulen der GNU-Distribution gesucht (siehe @ref{Paketmodule}). Alternativ kann die Befehlszeilenoption @code{--expression} benutzt werden, um einen Scheme-Ausdruck anzugeben, der zu einem Paket ausgewertet wird; @@ -7924,8 +8221,8 @@ archive}, gemeinsam. Das sind folgende: @item --load-path=@var{Verzeichnis} @itemx -L @var{Verzeichnis} -Das @var{Verzeichnis} vorne an den Suchpfad für Paketmodule anfügen -(@pxref{Paketmodule}). +Das @var{Verzeichnis} vorne an den Suchpfad für Paketmodule anfügen (siehe +@ref{Paketmodule}). Damit können Nutzer dafür sorgen, dass ihre eigenen selbstdefinierten Pakete für die Befehlszeilenwerkzeuge sichtbar sind. @@ -7936,12 +8233,13 @@ 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} +nach Fehlern in Erstellungen. Der Abschnitt @ref{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}). +entfernten Daemon über eine @code{guix://}-URI verwendet wurde (siehe +@ref{Der Store, the @code{GUIX_DAEMON_SOCKET} variable}). @item --keep-going @itemx -k @@ -7959,17 +8257,17 @@ 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}). +»Fallback« lokal selbst erstellen (siehe @ref{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}). +verwenden (siehe @ref{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}). +signiert worden sind (siehe @ref{Substitute}). Wenn als @var{urls} eine leere Zeichenkette angegeben wurde, verhält es sich, als wären Substitute abgeschaltet. @@ -7977,12 +8275,12 @@ 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}). +erstellten Binärdateien erlaubt ist (siehe @ref{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. +Abschnitt @ref{Sicherheitsaktualisierungen} hat weitere Informationen zu Veredelungen. @item --rounds=@var{n} Jede Ableitung @var{n}-mal nacheinander erstellen und einen Fehler melden, @@ -7993,17 +8291,17 @@ 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. +Abschnitt @ref{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 +z.B.@: indem Sie eines oder mehrere der Erstellungsergebnisse @code{guix +archive --export} auslagern (siehe @ref{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 +(siehe @ref{Auslagern des Daemons einrichten}). Somit wird lokal erstellt, statt Erstellungen auf entfernte Maschinen auszulagern. @item --max-silent-time=@var{Sekunden} @@ -8011,24 +8309,27 @@ 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}}). +Standardmäßig wird die Einstellung für den Daemon benutzt (siehe +@ref{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}}). +Standardmäßig wird die Einstellung für den Daemon benutzt (siehe +@ref{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} +@cindex Ausführlichkeit der Befehlszeilenwerkzeuge +@cindex Erstellungsprotokolle, Ausführlichkeit +@item -v @var{Stufe} @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. +Die angegebene Ausführlichkeitsstufe verwenden. Als @var{Stufe} muss eine +ganze Zahl angegeben werden. Wird 0 gewählt, wird keine Ausgabe zur +Fehlersuche angezeigt, 1 bedeutet eine knappe Ausgabe und 2 lässt alle +Erstellungsprotokollausgaben auf die Standardfehlerausgabe schreiben. @item --cores=@var{n} @itemx -c @var{n} @@ -8039,14 +8340,15 @@ 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 +@ref{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. +@item --debug=@var{Stufe} +Ein Protokoll zur Fehlersuche ausgeben, das vom Erstellungsdaemon kommt. Als +@var{Stufe} muss eine ganze Zahl zwischen 0 und 5 angegeben werden; höhere +Zahlen stehen für ausführlichere Ausgaben. Stufe 4 oder höher zu wählen, +kann bei der Suche nach Fehlern, wie der Erstellungs-Daemon eingerichtet +ist, helfen. @end table @@ -8085,7 +8387,7 @@ auch @command{guix package} unterstützen, sind @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}). +von Paketvarianten einzutippen (siehe @ref{Pakete definieren}). @table @code @@ -8095,11 +8397,11 @@ von Paketvarianten einzutippen (@pxref{Pakete definieren}). 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}). +download} (siehe @ref{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 +@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. @@ -8150,7 +8452,7 @@ Die Ersetzung ist rekursiv und umfassend. In diesem Beispiel würde nicht nur @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} (siehe @ref{Pakete definieren, @code{package-input-rewriting}}). @item --with-graft=@var{Paket}=@var{Ersatz} @@ -8158,7 +8460,7 @@ 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 +@dfn{veredelt} werden. Im Abschnitt @ref{Sicherheitsaktualisierungen} finden Sie weitere Informationen über Veredelungen. Zum Beispiel veredelt folgender Befehl Wget und alle Abhängigkeiten davon @@ -8178,24 +8480,24 @@ 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 +@item --with-git-url=@var{Paket}=@var{URL} +@cindex Git, den neuesten Commit benutzen @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. +Build @var{package} from the latest commit of the @code{master} branch of +the Git repository at @var{url}. 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: +For example, the following command builds the NumPy Python library against +the latest commit of the master branch of Python itself: @example -guix build --with-branch=guile-sqlite3=master cuirass +guix build python-numpy \ + --with-git-url=python=https://github.com/python/cpython @end example +This option can also be combined with @code{--with-branch} or +@code{--with-commit} (see below). + @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 @@ -8207,7 +8509,23 @@ 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} +@item --with-branch=@var{Paket}=@var{Branch} +Build @var{package} from the latest commit of @var{branch}. If the +@code{source} field of @var{package} is 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}. Otherwise you have to use +@code{--with-git-url} to specify the URL of the Git repository. + +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 + +@item --with-commit=@var{Paket}=@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. @@ -8223,19 +8541,19 @@ Die unten aufgeführten Befehlszeilenoptionen funktionieren nur mit @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. +Schweigend erstellen, ohne das Erstellungsprotokoll anzuzeigen — dies ist +äquivalent zu @code{--verbosity=0}. Nach Abschluss der Erstellung ist das +Protokoll in @file{/var} (oder einem entsprechenden Ort) einsehbar und kann +jederzeit mit der Befehlszeilenoption @option{--log-file} gefunden werden. @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}). +Code in der @var{Datei} ausgewertet wird (siehe @ref{G-Ausdrücke, +file-like objects}). -Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen -(@pxref{Pakete definieren}): +Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen (siehe +@ref{Pakete definieren}): @example @verbatiminclude package-hello.scm @@ -8243,63 +8561,68 @@ Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen @item --expression=@var{Ausdruck} @itemx -e @var{Ausdruck} -Build the package or derivation @var{expr} evaluates to. +Das Paket oder die Ableitung erstellen, zu der der @var{Ausdruck} +ausgewertet wird. -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. +Zum Beispiel kann der @var{Ausdruck} @code{(@@ (gnu packages guile) +guile-1.8)} sein, was diese bestimmte Variante der Version 1.8 von Guile +eindeutig bezeichnet. -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}). +Alternativ kann der @var{Ausdruck} ein G-Ausdruck sein. In diesem Fall wird +er als Erstellungsprogramm an @code{gexp->derivation} übergeben (siehe +@ref{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}. +Zudem kann der @var{Ausdruck} eine monadische Prozedur mit null Argumenten +bezeichnen (siehe @ref{Die Store-Monade}). Die Prozedur muss eine Ableitung +als monadischen Wert zurückliefern, die dann durch @code{run-with-store} +laufen gelassen wird. @item --source @itemx -S -Build the source derivations of the packages, rather than the packages -themselves. +Die Quellcode-Ableitung der Pakete statt die Pakete selbst erstellen. -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. +Zum Beispiel liefert @code{guix build -S gcc} etwas in der Art von +@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, also den Tarball mit dem +GCC-Quellcode. -The returned source tarball is the result of applying any patches and code -snippets specified in the package @code{origin} (@pxref{Pakete definieren}). +Der gelieferte Quell-Tarball ist das Ergebnis davon, alle Patches und +Code-Schnipsel aufzuspielen, die im @code{origin}-Objekt des Pakets +festgelegt wurden (siehe @ref{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: +Den Quellcode für @var{Paket-oder-Ableitung} und alle Abhängigkeiten davon +rekursiv herunterladen und zurückliefern. Dies ist eine praktische Methode, +eine lokale Kopie des gesamten Quellcodes zu beziehen, der nötig ist, um die +Pakete zu erstellen, damit Sie diese später auch ohne Netzwerkzugang +erstellen lassen können. Es handelt sich um eine Erweiterung der +Befehlszeilenoption @code{--source}, die jeden der folgenden Argumentwerte +akzeptiert: @table @code @item package -This value causes the @code{--sources} option to behave in the same way as -the @code{--source} option. +Mit diesem Wert verhält sich die Befehlszeilenoption @code{--sources} auf +genau die gleiche Weise wie die Befehlszeilenoption @code{--source}. @item all -Build the source derivations of all packages, including any source that -might be listed as @code{inputs}. This is the default value. +Erstellt die Quellcode-Ableitungen aller Pakete einschließlich allen +Quellcodes, der als Teil der Eingaben im @code{inputs}-Feld aufgelistet +ist. Dies ist der vorgegebene Wert, wenn sonst keiner angegeben wird. @example $ guix build --sources tzdata -The following derivations will be built: +Folgende Ableitungen werden erstellt: /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. +Die Quellcode-Ableitungen aller Pakete sowie aller transitiven Eingaben der +Pakete erstellen. Damit kann z.B.@: Paket-Quellcode vorab heruntergeladen +und später offline erstellt werden. @example $ guix build --sources=transitive tzdata -The following derivations will be built: +Folgende Ableitungen werden erstellt: /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 @@ -8314,54 +8637,55 @@ The following derivations will be built: @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 +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. +Die Befehlszeilenoption @code{--system} dient der @emph{nativen} +Kompilierung (nicht zu verwechseln mit Cross-Kompilierung). Siehe +@code{--target} unten für Informationen zur Cross-Kompilierung. @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. +Ein Beispiel sind Linux-basierte Systeme, die verschiedene Persönlichkeiten +emulieren können. Zum Beispiel können Sie @code{--system=i686-linux} auf +einem @code{x86_64-linux}-System oder @code{--system=armhf-linux} auf einem +@code{aarch64-linux}-System angeben, um Pakete in einer vollständigen +32-Bit-Umgebung zu erstellen. @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. +Das Erstellen für ein @code{armhf-linux}-System ist ungeprüft auf allen +@code{aarch64-linux}-Maschinen aktiviert, obwohl bestimmte aarch64-Chipsätze +diese Funktionalität nicht unterstützen, darunter auch 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. +Ebenso können Sie, wenn transparente Emulation mit QEMU und +@code{binfmt_misc} aktiviert sind (siehe @ref{Virtualisierungsdienste, +@code{qemu-binfmt-service-type}}), für jedes System Erstellungen +durchführen, für das ein QEMU-@code{binfmt_misc}-Handler installiert ist. -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. +Erstellungen für ein anderes System, das nicht dem System der Maschine, die +Sie benutzen, entspricht, können auch auf eine entfernte Maschine mit der +richtigen Architektur ausgelagert werden. Siehe @ref{Auslagern des Daemons einrichten} +für mehr Informationen über das Auslagern. @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, +gültiges GNU-Tripel wie z.B.@: @code{"mips64el-linux-gnu"} sein (siehe +@ref{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. +@cindex Determinismus, Überprüfung +@cindex Reproduzierbarkeit, Überprüfung +@var{Paket-oder-Ableitung} erneut erstellen, wenn diese bereits im Store +verfügbar ist, und einen Fehler melden, wenn die Erstellungsergebnisse nicht +Bit für Bit identisch sind. -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. +Mit diesem Mechanismus können Sie überprüfen, ob zuvor installierte +Substitute unverfälscht sind (siehe @ref{Substitute}) oder auch ob das +Erstellungsergebnis eines Pakets deterministisch ist. Siehe @ref{Aufruf von guix challenge} für mehr Hintergrundinformationen und Werkzeuge. Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich unterscheidenden Ausgaben im Store unter dem Namen @@ -8369,36 +8693,40 @@ unterscheidenden Ausgaben im Store unter dem Namen beiden Ergebnissen leicht erkannt werden. @item --repair -@cindex repairing store items +@cindex Reparieren von Store-Objekten @cindex Datenbeschädigung, Behebung -Attempt to repair the specified store items, if they are corrupt, by -re-downloading or rebuilding them. +Versuchen, die angegebenen Store-Objekte zu reparieren, wenn sie beschädigt +sind, indem sie neu heruntergeladen oder neu erstellt werden. -This operation is not atomic and thus restricted to @code{root}. +Diese Operation ist nicht atomar und nur der Administratornutzer @code{root} +kann sie verwenden. @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. +Liefert die Ableitungspfade und @emph{nicht} die Ausgabepfade für die +angegebenen Pakete. + +@item --root=@var{Datei} +@itemx -r @var{Datei} +@cindex GC-Wurzeln, Hinzufügen +@cindex Müllsammlerwurzeln, Hinzufügen +Die @var{Datei} zu einer symbolischen Verknüpfung auf das Ergebnis machen +und als Müllsammlerwurzel registrieren. + +Dadurch wird das Ergebnis dieses Aufrufs von @command{guix build} vor dem +Müllsammler geschützt, bis die @var{Datei} gelöscht wird. Wird diese +Befehlszeilenoption @emph{nicht} angegeben, können Erstellungsergebnisse vom +Müllsammler geholt werden, sobald die Erstellung abgeschlossen ist. Siehe +@ref{Aufruf von guix gc} für mehr Informationen zu Müllsammlerwurzeln. @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. +@cindex Erstellungsprotokolle, Zugriff +Liefert die Dateinamen oder URLs der Erstellungsprotokolle für das +angegebene @var{Paket-oder-Ableitung} oder meldet einen Fehler, falls +Protokolldateien fehlen. -This works regardless of how packages or derivations are specified. For -instance, the following invocations are equivalent: +Dies funktioniert, egal wie die Pakete oder Ableitungen angegeben +werden. Zum Beispiel sind folgende Aufrufe alle äquivalent: @example guix build --log-file `guix build -d guile` @@ -8407,40 +8735,47 @@ 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}.) +Wenn ein Protokoll lokal nicht verfügbar ist und sofern +@code{--no-substitutes} nicht übergeben wurde, sucht der Befehl nach einem +entsprechenden Protokoll auf einem der Substitutserver (die mit +@code{--substitute-urls} angegeben werden können). -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: +Stellen Sie sich zum Beispiel vor, sie wollten das Erstellungsprotokoll von +GDB auf einem MIPS-System sehen, benutzen aber selbst eine +@code{x86_64}-Maschine: @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! +So haben Sie umsonst Zugriff auf eine riesige Bibliothek von +Erstellungsprotokollen! @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. +@cindex Erstellungsfehler, Fehlersuche +Wenn Sie ein neues Paket definieren (siehe @ref{Pakete definieren}), werden +Sie sich vermutlich einige Zeit mit der Fehlersuche beschäftigen und die +Erstellung so lange anpassen, bis sie funktioniert. Dazu müssen Sie die +Erstellungsbefehle selbst in einer Umgebung benutzen, die der, die der +Erstellungsdaemon aufbaut, so ähnlich wie möglich ist. -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}}). +Das Erste, was Sie dafür tun müssen, ist die Befehlszeilenoption +@option{--keep-failed} oder @option{-K} von @command{guix build} +einzusetzen, wodurch Verzeichnisbäume fehlgeschlagener Erstellungen in +@file{/tmp} oder dem von Ihnen als @code{TMPDIR} ausgewiesenen Verzeichnis +erhalten und nicht gelöscht werden (siehe @ref{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: +Im Anschluss können Sie mit @command{cd} in die Verzeichnisse dieses +fehlgeschlagenen Erstellungsbaums wechseln und mit @command{source} dessen +@file{environment-variables}-Datei laden, die alle +Umgebungsvariablendefinitionen enthält, die zum Zeitpunkt des Fehlschlags +der Erstellung galten. Sagen wir, Sie suchen Fehler in einem Paket +@code{foo}, dann würde eine typische Sitzung so aussehen: @example $ guix build foo -K @@ -8450,17 +8785,18 @@ $ 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. +Nun können Sie Befehle (fast) so aufrufen, als wären Sie der Daemon, und +Fehlerursachen in Ihrem Erstellungsprozess ermitteln. -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}). +Manchmal passiert es, dass zum Beispiel die Tests eines Pakets erfolgreich +sind, wenn Sie sie manuell aufrufen, aber scheitern, wenn der Daemon sie +ausführt. Das kann passieren, weil der Daemon Erstellungen in isolierten +Umgebungen (»Containern«) durchführt, wo, anders als in der obigen Umgebung, +kein Netzwerkzugang möglich ist, @file{/bin/sh} nicht exisiert usw.@: (siehe +@ref{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: +In solchen Fällen müssen Sie den Erstellungsprozess womöglich aus einer zu +der des Daemons ähnlichen isolierten Umgebung heraus ausprobieren: @example $ guix build -K foo @@ -8471,162 +8807,176 @@ $ guix environment --no-grafts -C foo --ad-hoc strace gdb [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). +Hierbei erzeugt @command{guix environment -C} eine isolierte Umgebung und +öffnet darin eine Shell (siehe @ref{Aufruf von guix environment}). Der Teil +mit @command{--ad-hoc strace gdb} fügt die Befehle @command{strace} und +@command{gdb} zur isolierten Umgebung hinzu, die Sie gut gebrauchen könnten, +während Sie Fehler suchen. Wegen der Befehlszeilenoption +@option{--no-grafts} bekommen Sie haargenau dieselbe Umgebung ohne veredelte +Pakete (siehe @ref{Sicherheitsaktualisierungen} für mehr Informationen zu +Veredelungen). -To get closer to a container like that used by the build daemon, we can -remove @file{/bin/sh}: +Um der isolierten Umgebung des Erstellungsdaemons noch näher zu kommen, +können wir @file{/bin/sh} entfernen: @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}.) +(Keine Sorge, das ist harmlos: All dies passiert nur in der zuvor von +@command{guix environment} erzeugten Wegwerf-Umgebung.) -The @command{strace} command is probably not in the search path, but we can -run: +Der Befehl @command{strace} befindet sich wahrscheinlich nicht in Ihrem +Suchpfad, aber wir können ihn so benutzen: @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. +Auf diese Weise haben Sie nicht nur die Umgebungsvariablen, die der Daemon +benutzt, nachgebildet, sondern lassen auch den Erstellungsprozess in einer +isolierten Umgebung ähnlich der des Daemons laufen. @node Aufruf von guix edit -@section Invoking @command{guix edit} +@section @command{guix edit} aufrufen @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: +@cindex Paketdefinition, Bearbeiten +So viele Pakete, so viele Quelldateien! Der Befehl @command{guix edit} +erleichtert das Leben von sowohl Nutzern als auch Paketentwicklern, indem er +Ihren Editor anweist, die Quelldatei mit der Definition des jeweiligen +Pakets zu bearbeiten. Zum Beispiel startet dies: @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. +das mit der Umgebungsvariablen @code{VISUAL} ode @code{EDITOR} angegebene +Programm und lässt es das Rezept von GCC@tie{}4.9.3 und von Vim anzeigen. -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. +Wenn Sie ein Git-Checkout von Guix benutzen (siehe @ref{Erstellung aus dem Git}) +oder Ihre eigenen Pakete im @code{GUIX_PACKAGE_PATH} erstellt haben (siehe +@ref{Paketmodule}), werden Sie damit die Paketrezepte auch bearbeiten +können. Andernfalls werden Sie zumindest in die Lage versetzt, die nur +lesbaren Rezepte für sich im Moment im Store befindliche Pakete zu +untersuchen. @node Aufruf von guix download -@section Invoking @command{guix download} +@section @command{guix download} aufrufen @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: +@cindex Paketquellcode herunterladen +Wenn Entwickler einer Paketdefinition selbige schreiben, müssen diese +normalerweise einen Quellcode-Tarball herunterladen, seinen SHA256-Hash als +Prüfsumme berechnen und diese in der Paketdefinition eintragen (siehe +@ref{Pakete definieren}). Das Werkzeug @command{guix download} hilft bei +dieser Aufgabe: Damit wird eine Datei von der angegebenen URI +heruntergeladen, in den Store eingelagert und sowohl ihr Dateiname im Store +als auch ihr SHA256-Hash als Prüfsumme angezeigt. + +Dadurch, dass die heruntergeladene Datei in den Store eingefügt wird, wird +Bandbreite gespart: Wenn der Entwickler schließlich versucht, das neu +definierte Paket mit @command{guix build} zu erstellen, muss der +Quell-Tarball nicht erneut heruntergeladen werden, weil er sich bereits im +Store befindet. Es ist auch eine bequeme Methode, Dateien temporär +aufzubewahren, die letztlich irgendwann gelöscht werden (siehe @ref{Aufruf von guix gc}). + +Der Befehl @command{guix download} unterstützt dieselben URIs, die in +Paketdefinitionen verwendet werden. Insbesondere unterstützt er +@code{mirror://}-URIs. @code{https}-URIs (HTTP über TLS) werden unterstützt, +@emph{vorausgesetzt} die Guile-Anbindungen für GnuTLS sind in der Umgebung +des Benutzers verfügbar; wenn nicht, wird ein Fehler gemeldet. Siehe +@ref{Guile Preparations, how to install the GnuTLS bindings for Guile,, +gnutls-guile, GnuTLS-Guile}, hat mehr Informationen. + +Mit @command{guix download} werden HTTPS-Serverzertifikate verifiziert, +indem die Zertifikate der X.509-Autoritäten in das durch die +Umgebungsvariable @code{SSL_CERT_DIR} bezeichnete Verzeichnis +heruntergeladen werden (siehe @ref{X.509-Zertifikate}), außer +@option{--no-check-certificate} wird benutzt. + +Folgende Befehlszeilenoptionen stehen zur Verfügung: @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 --format=@var{Format} +@itemx -f @var{Format} +Die Hash-Prüfsumme im angegebenen @var{Format} ausgeben. Für weitere +Informationen, was gültige Werte für das @var{Format} sind, siehe +@ref{Aufruf von guix hash}. @item --no-check-certificate -Do not validate the X.509 certificates of HTTPS servers. +X.509-Zertifikate von HTTPS-Servern @emph{nicht} validieren. -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. +Wenn Sie diese Befehlszeilenoption benutzen, haben Sie @emph{keinerlei +Garantie}, dass Sie tatsächlich mit dem authentischen Server, der für die +angegebene URL verantwortlich ist, kommunizieren. Das macht Sie anfällig +gegen sogenannte »Man-in-the-Middle«-Angriffe. -@item --output=@var{file} -@itemx -o @var{file} -Save the downloaded file to @var{file} instead of adding it to the store. +@item --output=@var{Datei} +@itemx -o @var{Datei} +Die heruntergeladene Datei @emph{nicht} in den Store, sondern in die +angegebene @var{Datei} abspeichern. @end table @node Aufruf von guix hash -@section Invoking @command{guix hash} +@section @command{guix hash} aufrufen @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}). +Der Befehl @command{guix hash} berechnet den SHA256-Hash einer Datei. Er ist +primär ein Werkzeug, dass es bequemer macht, etwas zur Distribution +beizusteuern: Damit wird die kryptografische Hash-Prüfsumme berechnet, die +bei der Definition eines Pakets benutzt werden kann (siehe @ref{Pakete definieren}). Die allgemeine Syntax lautet: @example -guix hash @var{option} @var{file} +guix hash @var{Option} @var{Datei} @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: +Wird als @var{Datei} ein Bindestrich @code{-} angegeben, berechnet +@command{guix hash} den Hash der von der Standardeingabe gelesenen +Daten. @command{guix hash} unterstützt die folgenden Optionen: @table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. +@item --format=@var{Format} +@itemx -f @var{Format} +Gibt die Prüfsumme im angegebenen @var{Format} aus. -Supported formats: @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} and @code{hexadecimal} can be used as well). +Unterstützte Formate: @code{nix-base32}, @code{base32}, @code{base16} +(@code{hex} und @code{hexadecimal} können auch benutzt werden). -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. +Wird keine Befehlszeilenoption @option{--format} angegeben, wird +@command{guix hash} die Prüfsumme im @code{nix-base32}-Format +ausgeben. Diese Darstellung wird bei der Definition von Paketen benutzt. @item --recursive @itemx -r -Compute the hash on @var{file} recursively. +Die Prüfsumme der @var{Datei} rekursiv berechnen. @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}). +In diesem Fall wird die Prüfsumme eines Archivs berechnet, das die +@var{Datei} enthält, und auch ihre Kinder, wenn es sich um ein Verzeichnis +handelt. Einige der Metadaten der @var{Datei} sind Teil dieses Archivs. Zum +Beispiel unterscheidet sich die berechnete Prüfsumme, wenn die @var{Datei} +eine reguläre Datei ist, je nachdem, ob die @var{Datei} ausführbar ist oder +nicht. Metadaten wie der Zeitstempel haben keinen Einfluss auf die Prüfsumme +(siehe @ref{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.) +Wenn dies zusammen mit der Befehlszeilenoption @option{--recursive} +angegeben wird, werden Verzeichnisse zur Versionskontrolle (@file{.bzr}, +@file{.git}, @file{.hg}, etc.)@: vom Archiv ausgenommen. @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}): +Zum Beispiel würden Sie auf diese Art die Prüfsumme eines Git-Checkouts +berechnen, was nützlich ist, wenn Sie die Prüfsumme für die Methode +@code{git-fetch} benutzen (siehe @ref{»origin«-Referenz}): @example $ git clone http://example.org/foo.git @@ -8636,64 +8986,70 @@ $ guix hash -rx . @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}). +@section @command{guix import} aufrufen + +@cindex Pakete importieren +@cindex Paketimport +@cindex Pakete an Guix anpassen +@cindex @command{guix import} aufrufen +Der Befehl @command{guix import} ist für Leute hilfreich, die ein Paket +gerne mit so wenig Arbeit wie möglich zur Distribution hinzufügen würden — +ein legitimer Anspruch. Der Befehl kennt ein paar Sammlungen, aus denen mit +ihm Paketmetadaten »importiert« werden können. Das Ergebnis ist eine +Paketdefinition oder eine Vorlage dafür in dem uns bekannten Format (siehe +@ref{Pakete definieren}). Die allgemeine Syntax lautet: @example -guix import @var{importer} @var{options}@dots{} +guix import @var{Importer} @var{Optionen}@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: +Der @var{Importer} gibt die Quelle an, aus der Paketmetadaten importiert +werden, und die @var{Optionen} geben eine Paketbezeichnung und andere vom +@var{Importer} abhängige Daten an. Derzeit sind folgende »Importer« +verfügbar: @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. +Metadaten für das angegebene GNU-Paket importieren. Damit wird eine Vorlage +für die neueste Version dieses GNU-Pakets zur Verfügung gestellt, +einschließlich der Prüfsumme seines Quellcode-Tarballs, seiner kanonischen +Zusammenfassung und seiner Beschreibung. -Additional information such as the package dependencies and its license -needs to be figured out manually. +Zusätzliche Informationen wie Paketabhängigkeiten und seine Lizenz müssen +noch manuell ermittelt werden. -For example, the following command returns a package definition for +Zum Beispiel liefert der folgende Befehl eine Paketdefinition für GNU@tie{}Hello: @example guix import gnu hello @end example -Specific command-line options are: +Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur +Verfügung: @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, +@item --key-download=@var{Richtlinie} +Die Richtlinie zum Umgang mit fehlenden OpenPGP-Schlüsseln beim Verifizieren +der Paketsignatur (auch »Beglaubigung« genannt) festlegen, wie bei +@code{guix refresh}. Siehe @ref{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. +Metadaten aus dem @uref{https://pypi.python.org/, Python Package Index} +importieren. Informationen stammen aus der JSON-formatierten Beschreibung, +die unter @code{pypi.python.org} verfügbar ist, und enthalten meistens alle +relevanten Informationen einschließlich der Abhängigkeiten des Pakets. Für +maximale Effizienz wird empfohlen, das Hilfsprogramm @command{unzip} zu +installieren, damit der Importer »Python Wheels« entpacken und daraus Daten +beziehen kann. -The command below imports metadata for the @code{itsdangerous} Python -package: +Der folgende Befehl importiert Metadaten für das Python-Paket namens +@code{itsdangerous}: @example guix import pypi itsdangerous @@ -8702,22 +9058,25 @@ guix import pypi itsdangerous @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. +Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in +Guix noch nicht gibt. @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. +Metadaten von @uref{https://rubygems.org/, RubyGems} +importieren. Informationen kommen aus der JSON-formatierten Beschreibung, +die auf @code{rubygems.org} verfügbar ist, und enthält die relevantesten +Informationen einschließlich der Laufzeitabhängigkeiten. Dies hat aber auch +Schattenseiten — die Metadaten unterscheiden nicht zwischen +Zusammenfassungen und Beschreibungen, daher wird dieselbe Zeichenkette für +beides eingesetzt. Zudem fehlen Informationen zu nicht in Ruby geschriebenen +Abhängigkeiten, die benötigt werden, um native Erweiterungen zu in Ruby +geschriebenem Code zu erstellen. Diese herauszufinden bleibt dem +Paketentwickler überlassen. -The command below imports metadata for the @code{rails} Ruby package: +Der folgende Befehl importiert Metadaten aus dem Ruby-Paket @code{rails}. @example guix import gem rails @@ -8726,23 +9085,24 @@ guix import gem rails @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. +Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in +Guix noch nicht gibt. @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. +Importiert Metadaten von @uref{https://www.metacpan.org/, +MetaCPAN}. Informationen werden aus den JSON-formatierten Metadaten +genommen, die über die @uref{https://fastapi.metacpan.org/, +Programmierschnittstelle (»API«) von MetaCPAN} angeboten werden, und +enthalten die relevantesten Informationen wie zum Beispiel +Modulabhängigkeiten. Lizenzinformationen sollten genau nachgeprüft +werden. Wenn Perl im Store verfügbar ist, wird das Werkzeug @code{corelist} +benutzt, um Kernmodule in der Abhängigkeitsliste wegzulassen. -The command command below imports metadata for the @code{Acme::Boolean} Perl -module: +Folgender Befehl importiert Metadaten für das Perl-Modul +@code{Acme::Boolean}: @example guix import cpan Acme::Boolean @@ -8751,31 +9111,35 @@ guix import cpan Acme::Boolean @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}. +Metadaten aus dem @uref{https://cran.r-project.org/, CRAN} importieren, der +zentralen Sammlung für die @uref{http://r-project.org, statistische und +grafische Umgebung GNU@tie{}R}. -Information is extracted from the @code{DESCRIPTION} file of the package. +Informationen werden aus der Datei namens @code{DESCRIPTION} des Pakets +extrahiert. -The command command below imports metadata for the @code{Cairo} R package: +Der folgende Befehl importiert Metadaten für das @code{Cairo}-R-Paket: @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. +Wird zudem @code{--recursive} angegeben, wird der Importer den +Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für all die Pakete erzeugen, die noch nicht +Teil von Guix sind. -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. +Wird @code{--archive=bioconductor} angegeben, werden Metadaten vom +@uref{https://www.bioconductor.org/, Bioconductor} importiert, einer +Sammlung von R-Paketen zur Analyse und zum Verständnis von großen Mengen +genetischer Daten in der Bioinformatik. -Information is extracted from the @code{DESCRIPTION} file of a package -published on the web interface of the Bioconductor SVN repository. +Informationen werden aus der @code{DESCRIPTION}-Datei im Paket extrahiert, +das auf der Weboberfläche des Bioconductor-SVN-Repositorys veröffentlicht +wurde. -The command below imports metadata for the @code{GenomicRanges} R package: +Der folgende Befehl importiert Metadaten für das R-Paket +@code{GenomicRanges}: @example guix import cran --archive=bioconductor GenomicRanges @@ -8784,38 +9148,39 @@ guix import cran --archive=bioconductor GenomicRanges @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}. +Metadaten aus @uref{http://www.ctan.org/, CTAN}, dem umfassenden +TeX-Archivnetzwerk, herunterladen, was für TeX-Pakete benutzt wird, die Teil +der @uref{https://www.tug.org/texlive/, TeX-Live-Distribution} sind. -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. +Informationen über das Paket werden über die von CTAN angebotene +XML-Programmierschnittstelle bezogen, wohingegen der Quellcode aus dem +SVN-Repository des TeX-Live-Projekts heruntergeladen wird. Das wird so +gemacht, weil CTAN keine versionierten Archive vorhält. -The command command below imports metadata for the @code{fontspec} TeX -package: +Der folgende Befehl importiert Metadaten für das TeX-Paket @code{fontspec}: @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. +Wenn @code{--archive=VERZEICHNIS} angegeben wird, wird der Quellcode +@emph{nicht} aus dem Unterverzeichnis @file{latex} des +@file{texmf-dist/source}-Baums im SVN-Repository von TeX Live +heruntergeladen, sondern aus dem angegebenen Schwesterverzeichnis im selben +Wurzelverzeichnis. -The command below imports metadata for the @code{ifxetex} package from CTAN -while fetching the sources from the directory @file{texmf/source/generic}: +Der folgende Befehl importiert Metadaten für das Paket @code{ifxetex} aus +CTAN und lädt die Quelldateien aus dem Verzeichnis +@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: +@cindex JSON, Import +Paketmetadaten aus einer lokalen JSON-Datei importieren. Betrachten Sie +folgende Beispiel-Paketdefinition im JSON-Format: @example @{ @@ -8831,13 +9196,13 @@ example package definition in JSON format: @} @end example -The field names are the same as for the @code{} 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}. +Die Felder sind genauso benannt wie bei einem @code{}-Verbundstyp +(siehe @ref{Pakete definieren}). Referenzen zu anderen Paketen stehen darin +als JSON-Liste von mit Anführungszeichen quotierten Zeichenketten wie +@code{guile} oder @code{guile@@2.0}. -The importer also supports a more explicit source definition using the -common fields for @code{} records: +Der Importer unterstützt auch eine ausdrücklichere Definition der +Quelldateien mit den üblichen Feldern eines @code{}-Verbunds: @example @{ @@ -8853,37 +9218,38 @@ common fields for @code{} records: @} @end example -The command below reads metadata from the JSON file @code{hello.json} and -outputs a package expression: +Der folgende Befehl liest Metadaten aus der JSON-Datei @code{hello.json} und +gibt einen Paketausdruck aus: @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. +Metadaten aus einer lokalen Kopie des Quellcodes der +@uref{http://nixos.org/nixpkgs/, Nixpkgs-Distribution} +importieren@footnote{Dazu wird der Befehl @command{nix-instantiate} von +@uref{http://nixos.org/nix/, Nix} verwendet.}. Paketdefinitionen in Nixpkgs +werden typischerweise in einer Mischung aus der Sprache von Nix und aus +Bash-Code geschrieben. Dieser Befehl wird nur die abstrakte Paketstruktur, +die in der Nix-Sprache geschrieben ist, importieren. Dazu gehören +normalerweise alle grundlegenden Felder einer Paketdefinition. -When importing a GNU package, the synopsis and descriptions are replaced by -their canonical upstream variant. +Beim Importieren eines GNU-Pakets werden Zusammenfassung und Beschreibung +stattdessen durch deren kanonische Variante bei GNU ersetzt. -Usually, you will first need to do: +Normalerweise würden Sie zunächst dies ausführen: @example export NIX_REMOTE=daemon @end example @noindent -so that @command{nix-instantiate} does not try to open the Nix database. +damit @command{nix-instantiate} nicht versucht, die Nix-Datenbank zu öffnen. -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): +Zum Beispiel importiert der Befehl unten die Paketdefinition von LibreOffice +(genauer gesagt importiert er die Definition des an das Attribut +@code{libreoffice} auf oberster Ebene gebundenen Pakets): @example guix import nix ~/path/to/nixpkgs libreoffice @@ -8891,47 +9257,50 @@ guix import nix ~/path/to/nixpkgs libreoffice @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. +Metadaten aus @uref{https://hackage.haskell.org/, Hackage}, dem zentralen +Paketarchiv der Haskell-Gemeinde, importieren. Informationen werden aus +Cabal-Dateien ausgelesen. Darin sind alle relevanten Informationen +einschließlich der Paketabhängigkeiten enthalten. -Specific command-line options are: +Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur +Verfügung: @table @code @item --stdin @itemx -s -Read a Cabal file from standard input. +Eine Cabal-Datei von der Standardeingabe lesen. @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. +Keine Abhängigkeiten übernehmen, die nur von Testkatalogen benötigt werden. +@item --cabal-environment=@var{Aliste} +@itemx -e @var{Aliste} +@var{Aliste} muss eine assoziative Liste der Scheme-Programmiersprache sein, +die die Umgebung definiert, in der bedingte Ausdrücke von Cabal ausgewertet +werden. Dabei werden folgende Schlüssel akzeptiert: @code{os}, @code{arch}, +@code{impl} und eine Zeichenkette, die dem Namen einer Option (einer »Flag«) +entspricht. Der mit einer »Flag« assoziierte Wert muss entweder das Symbol +@code{true} oder @code{false} sein. Der anderen Schlüsseln zugeordnete Wert +muss mit der Definition des Cabal-Dateiformats konform sein. Der vorgegebene +Wert zu den Schlüsseln @code{os}, @code{arch} and @code{impl} ist jeweils +@samp{linux}, @samp{x86_64} bzw. @samp{ghc}. @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. +Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in +Guix noch nicht gibt. @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}: +Der folgende Befehl importiert Metadaten für die neuste Version des +Haskell-@code{HTTP}-Pakets, ohne Testabhängigkeiten zu übernehmen und bei +Übergabe von @code{false} als Wert der Flag @samp{network-uri}: @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: +Eine ganz bestimmte Paketversion kann optional ausgewählt werden, indem man +nach dem Paketnamen anschließend ein At-Zeichen und eine Versionsnummer +angibt wie in folgendem Beispiel: @example guix import hackage mtl@@2.1.3.1 @@ -8939,31 +9308,36 @@ guix import hackage mtl@@2.1.3.1 @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: +Der @code{stackage}-Importer ist ein Wrapper um den +@code{hackage}-Importer. Er nimmt einen Paketnamen und schaut dafür die +Paketversion nach, die Teil einer @uref{https://www.stackage.org, +Stackage}-Veröffentlichung mit Langzeitunterstützung (englisch »Long-Term +Support«, kurz LTS) ist, deren Metadaten er dann mit dem +@code{hackage}-Importer bezieht. Beachten Sie, dass es Ihre Aufgabe ist, +eine LTS-Veröffentlichung auszuwählen, die mit dem von Guix benutzten +GHC-Compiler kompatibel ist. + +Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur +Verfügung: @table @code @item --no-test-dependencies @itemx -t -Do not include dependencies required only by the test suites. -@item --lts-version=@var{version} +Keine Abhängigkeiten übernehmen, die nur von Testkatalogen benötigt werden. +@item --lts-version=@var{Version} @itemx -l @var{Version} -@var{version} is the desired LTS release version. If omitted the latest -release is used. +@var{Version} ist die gewünschte Version der LTS-Veröffentlichung. Wird +keine angegeben, wird die neueste benutzt. @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. +Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in +Guix noch nicht gibt. @end table -The command below imports metadata for the @code{HTTP} Haskell package -included in the LTS Stackage release version 7.18: +Der folgende Befehl importiert Metadaten für dasjenige +@code{HTTP}-Haskell-Paket, das in der LTS-Stackage-Veröffentlichung mit +Version 7.18 vorkommt: @example guix import stackage --lts-version=7.18 HTTP @@ -8971,67 +9345,67 @@ guix import stackage --lts-version=7.18 HTTP @item elpa @cindex elpa -Import metadata from an Emacs Lisp Package Archive (ELPA) package repository -(@pxref{Packages,,, emacs, The GNU Emacs Manual}). +Metadaten aus der Paketsammlung »Emacs Lisp Package Archive« (ELPA) +importieren (siehe @ref{Packages,,, emacs, The GNU Emacs Manual}). -Specific command-line options are: +Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur +Verfügung: @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: +@item --archive=@var{Repo} +@itemx -a @var{Repo} +Mit @var{Repo} wird die Archiv-Sammlung (ein »Repository«) bezeichnet, von +dem die Informationen bezogen werden sollen. Derzeit sind die unterstützten +Repositorys und ihre Bezeichnungen folgende: @itemize - @item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} -identifier. This is the default. +@uref{http://elpa.gnu.org/packages, GNU}, bezeichnet mit @code{gnu}. Dies +ist die Vorgabe. -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}). +Pakete aus @code{elpa.gnu.org} wurden mit einem der Schlüssel im +GnuPG-Schlüsselbund in @file{share/emacs/25.1/etc/package-keyring.gpg} (oder +einem ähnlichen Pfad) des @code{emacs}-Pakets signiert (siehe @ref{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. +@uref{http://stable.melpa.org/packages, MELPA-Stable}, bezeichnet mit +@code{melpa-stable}. @item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} -identifier. +@uref{http://melpa.org/packages, MELPA}, bezeichnet mit @code{melpa}. @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. +Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv +durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in +Guix noch nicht gibt. @end table @item crate @cindex crate -Import metadata from the crates.io Rust package repository +Metadaten aus der Paketsammlung crates.io für Rust importieren @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. +Metadaten aus der Paketsammlung @uref{https://opam.ocaml.org/, OPAM} der +OCaml-Gemeinde importieren. @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}). +@command{guix import} verfügt über eine modulare Code-Struktur. Mehr +Importer für andere Paketformate zu haben, wäre nützlich, und Ihre Hilfe ist +hierbei gerne gesehen (siehe @ref{Mitwirken}). @node Aufruf von guix refresh -@section Invoking @command{guix refresh} +@section @command{guix refresh} aufrufen @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: +Die Zielgruppe des Befehls @command{guix refresh} zum Auffrischen von +Paketen sind in erster Linie Entwickler der GNU-Software-Distribution. Nach +Vorgabe werden damit alle Pakete in der Distribution gemeldet, die nicht der +neuesten Version des Anbieters entsprechen, indem Sie dies ausführen: @example $ guix refresh @@ -9039,8 +9413,9 @@ gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18. 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: +Alternativ können die zu betrachtenden Pakete dabei angegeben werden, was +zur Ausgabe einer Warnung führt, wenn es für Pakete kein +Aktualisierungsprogramm gibt: @example $ guix refresh coreutils guile guile-ssh @@ -9048,13 +9423,15 @@ 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! +@command{guix refresh} durchsucht die Paketsammlung beim Anbieter jedes +Pakets und bestimmt, was die höchste Versionsnummer ist, zu der es dort eine +Veröffentlichung gibt. Zum Befehl gehören Aktualisierungsprogramme, mit +denen bestimmte Typen von Paketen automatisch aktualisiert werden können: +GNU-Pakete, ELPA-Pakete usw.@: — siehe die Dokumentation von @option{--type} +unten. Es gibt jedoch auch viele Pakete, für die noch keine Methode +enthalten ist, um das Vorhandensein einer neuen Veröffentlichung zu +prüfen. Der Mechanismus ist aber erweiterbar, also können Sie gerne mit uns +in Kontakt treten, wenn Sie eine neue Methode hinzufügen möchten! @table @code @@ -9073,10 +9450,11 @@ gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version @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: +Manchmal unterscheidet sich der vom Anbieter benutzte Name von dem +Paketnamen, der in Guix verwendet wird, so dass @command{guix refresh} etwas +Unterstützung braucht. Die meisten Aktualisierungsprogramme folgen der +Eigenschaft @code{upstream-name} in Paketdefinitionen, die diese +Unterstützung bieten kann. @example (define-public network-manager @@ -9086,18 +9464,20 @@ that effect: (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. +Wenn @code{--update} übergeben wird, werden die Quelldateien der +Distribution verändert, so dass für diese Paketrezepte die aktuelle Version +und die aktuelle Hash-Prüfsumme des Quellcode-Tarballs eingetragen wird +(siehe @ref{Pakete definieren}). Dazu werden der neueste Quellcode-Tarball +jedes Pakets sowie die jeweils zugehörige OpenPGP-Signatur heruntergeladen; +mit Letzterer wird der heruntergeladene Tarball gegen seine Signatur mit +@command{gpg} authentifiziert und schließlich dessen Hash berechnet. Wenn +der öffentliche Schlüssel, mit dem der Tarball signiert wurde, im +Schlüsselbund des Benutzers fehlt, wird versucht, ihn automatisch von einem +Schlüssel-Server zu holen; wenn das klappt, wird der Schlüssel zum +Schlüsselbund des Benutzers hinzugefügt, ansonsten meldet @command{guix +refresh} einen Fehler. -The following options are supported: +Die folgenden Befehlszeilenoptionen werden unterstützt: @table @code @@ -9105,88 +9485,99 @@ The following options are supported: @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: +Dies ist nützlich, um genau ein bestimmtes Paket zu referenzieren, wie in +diesem Beispiel: @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.) +Dieser Befehls listet auf, was alles von der »endgültigen« Erstellung von +libc abhängt (praktisch alle Pakete). @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}): +Die Quelldateien der Distribution (die Paketrezepte) werden direkt »in +place« verändert. Normalerweise führen Sie dies aus einem Checkout des +Guix-Quellbaums heraus aus (siehe @ref{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. +Siehe @ref{Pakete definieren} für mehr Informationen zu Paketdefinitionen. -@item --select=[@var{subset}] -@itemx -s @var{subset} -Select all the packages in @var{subset}, one of @code{core} or -@code{non-core}. +@item --select=[@var{Teilmenge}] +@itemx -s @var{Teilmenge} +Wählt alle Pakete aus der @var{Teilmenge} aus, die entweder @code{core} oder +@code{non-core} sein muss. -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. +Die @code{core}-Teilmenge bezieht sich auf alle Pakete, die den Kern der +Distribution ausmachen, d.h.@: Pakete, aus denen heraus »alles andere« +erstellt wird. Dazu gehören GCC, libc, Binutils, Bash und so weiter. In der +Regel ist die Folge einer Änderung an einem dieser Pakete in der +Distribution, dass alle anderen neu erstellt werden müssen. Daher sind +solche Änderungen unangenehm für Nutzer, weil sie einiges an Erstellungszeit +oder Bandbreite investieren müssen, um die Aktualisierung abzuschließen. -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. +Die @code{non-core}-Teilmenge bezieht sich auf die übrigen Pakete. Sie wird +typischerweise dann benutzt, wenn eine Aktualisierung der Kernpakete zu +viele Umstände machen würde. @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: +Wählt alle Pakete im in der @var{Datei} stehenden Manifest aus. Das ist +nützlich, um zu überprüfen, welche Pakete aus dem Manifest des Nutzers +aktualisiert werden können. + +@item --type=@var{Aktualisierungsprogramm} +@itemx -t @var{Aktualisierungsprogramm} +Nur solche Pakete auswählen, die vom angegebenen +@var{Aktualisierungsprogramm} behandelt werden. Es darf auch eine +kommagetrennte Liste mehrerer Aktualisierungsprogramme angegeben werden. Zur +Zeit kann als @var{Aktualisierungsprogramm} eines der folgenden angegeben +werden: @table @code @item gnu -the updater for GNU packages; +Aktualisierungsprogramm für GNU-Pakete, @item gnome -the updater for GNOME packages; +Aktualisierungsprogramm für GNOME-Pakete, @item kde -the updater for KDE packages; +Aktualisierungsprogramm für KDE-Pakete, @item xorg -the updater for X.org packages; +Aktualisierungsprogramm für X.org-Pakete, @item kernel.org -the updater for packages hosted on kernel.org; +Aktualisierungsprogramm auf kernel.org angebotener Pakete, @item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; +Aktualisierungsprogramm für @uref{http://elpa.gnu.org/, ELPA-Pakete}, @item cran -the updater for @uref{https://cran.r-project.org/, CRAN} packages; +Aktualisierungsprogramm für @uref{https://cran.r-project.org/, CRAN-Pakete}, @item bioconductor -the updater for @uref{https://www.bioconductor.org/, Bioconductor} R -packages; +Aktualisierungsprogramm für R-Pakete vom +@uref{https://www.bioconductor.org/, Bioconductor}, @item cpan -the updater for @uref{http://www.cpan.org/, CPAN} packages; +Aktualisierungsprogramm für @uref{http://www.cpan.org/, CPAN-Pakete}, @item pypi -the updater for @uref{https://pypi.python.org, PyPI} packages. +Aktualisierungsprogramm für @uref{https://pypi.python.org, PyPI-Pakete}, @item gem -the updater for @uref{https://rubygems.org, RubyGems} packages. +Aktualisierungsprogramm für @uref{https://rubygems.org, RubyGems-Pakete}. @item github -the updater for @uref{https://github.com, GitHub} packages. +Aktualisierungsprogramm für @uref{https://github.com, GitHub-Pakete}. @item hackage -the updater for @uref{https://hackage.haskell.org, Hackage} packages. +Aktualisierungsprogramm für @uref{https://hackage.haskell.org, +Hackage-Pakete}. @item stackage -the updater for @uref{https://www.stackage.org, Stackage} packages. +Aktualisierungsprogramm für @uref{https://www.stackage.org, +Stackage-Pakete}. @item crate -the updater for @uref{https://crates.io, Crates} packages. +Aktualisierungsprogramm für @uref{https://crates.io, Crates-Pakete}. +@item launchpad +Aktualisierungsprogramm für @uref{https://launchpad.net, Launchpad}. @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: +Zum Beispiel prüft folgender Befehl nur auf mögliche Aktualisierungen von +auf @code{elpa.gnu.org} angebotenen Emacs-Paketen und von CRAN-Paketen: @example $ guix refresh --type=elpa,cran @@ -9196,45 +9587,50 @@ gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11 @end table -In addition, @command{guix refresh} can be passed one or more package names, -as in this example: +An @command{guix refresh} können auch ein oder mehrere Paketnamen übergeben +werden wie in diesem Beispiel: @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. +Der Befehl oben aktualisiert speziell das @code{emacs}- und das +@code{idutils}-Paket. Eine Befehlszeilenoption @code{--select} hätte dann +keine Wirkung. -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: +Wenn Sie sich fragen, ob ein Paket aktualisiert werden sollte oder nicht, +kann es helfen, sich anzuschauen, welche Pakete von der Aktualisierung +betroffen wären und auf Kompatibilität hin geprüft werden sollten. Dazu kann +die folgende Befehlszeilenoption zusammen mit einem oder mehreren Paketnamen +an @command{guix refresh} übergeben werden: @table @code @item --list-updaters @itemx -L -List available updaters and exit (see @option{--type} above.) +Eine Liste verfügbarer Aktualisierungsprogramme anzeigen und terminieren +(siehe @option{--type} oben). -For each updater, display the fraction of packages it covers; at the end, -display the fraction of packages covered by all these updaters. +Für jedes Aktualisierungsprogramm den Anteil der davon betroffenen Pakete +anzeigen; zum Schluss wird der Gesamtanteil von irgendeinem +Aktualisierungsprogramm betroffener Pakete angezeigt. @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. +Auflisten, welche abhängigen Pakete auf oberster Ebene neu erstellt werden +müssten, wenn eines oder mehrere Pakete aktualisiert würden. -@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. +Siehe @ref{Aufruf von guix graph, den @code{reverse-package}-Typ von +@command{guix graph}} für Informationen dazu, wie Sie die Liste der +Abhängigen eines Pakets visualisieren können. @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. +Bedenken Sie, dass die Befehlszeilenoption @code{--list-dependent} das +Ausmaß der nach einer Aktualisierungen benötigten Neuerstellungen nur +@emph{annähert}. Es könnten auch unter Umständen mehr Neuerstellungen +anfallen. @example $ guix refresh --list-dependent flex @@ -9242,13 +9638,14 @@ Building the following 120 packages would ensure 213 dependent packages are rebu 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. +Der oben stehende Befehl gibt einen Satz von Paketen aus, die Sie erstellen +wollen könnten, um die Kompatibilität einer Aktualisierung des +@code{flex}-Pakets beurteilen zu können. @table @code @item --list-transitive -List all the packages which one or more packages depend upon. +Die Pakete auflisten, von denen eines oder mehrere Pakete abhängen. @example $ guix refresh --list-transitive flex @@ -9258,110 +9655,123 @@ bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.3 @end table -The command above lists a set of packages which, when changed, would cause -@code{flex} to be rebuilt. +Der oben stehende Befehl gibt einen Satz von Paketen aus, die, wenn sie +geändert würden, eine Neuerstellung des @code{flex}-Pakets auslösen würden. -The following options can be used to customize GnuPG operation: +Mit den folgenden Befehlszeilenoptionen können Sie das Verhalten von GnuPG +anpassen: @table @code -@item --gpg=@var{command} -Use @var{command} as the GnuPG 2.x command. @var{command} is searched for -in @code{$PATH}. +@item --gpg=@var{Befehl} +Den @var{Befehl} als GnuPG-2.x-Befehl einsetzen. Der @var{Befehl} wird im +@code{$PATH} gesucht. @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). +Die @var{Datei} als Schlüsselbund mit Anbieterschlüsseln verwenden. Die +@var{Datei} muss im @dfn{Keybox-Format} vorliegen. Keybox-Dateien haben +normalerweise einen Namen, der auf @file{.kbx} endet. Sie können mit Hilfe +von GNU@tie{}Privacy Guard (GPG) bearbeitet werden (siehe @ref{kbxutil, +@command{kbxutil},, gnupg, Using the GNU Privacy Guard} für Informationen +über ein Werkzeug zum Bearbeiten von Keybox-Dateien). -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.) +Wenn diese Befehlszeilenoption nicht angegeben wird, benutzt @command{guix +refresh} die Keybox-Datei @file{~/.config/guix/upstream/trustedkeys.kbx} als +Schlüsselbund für Signierschlüssel von Anbietern. OpenPGP-Signaturen werden +mit Schlüsseln aus diesem Schlüsselbund überprüft; fehlende Schlüssel werden +auch in diesen Schlüsselbund heruntergeladen (siehe @option{--key-download} +unten). -You can export keys from your default GPG keyring into a keybox file using -commands like this one: +Sie können Schlüssel aus Ihrem normalerweise benutzten GPG-Schlüsselbund in +eine Keybox-Datei exportieren, indem Sie Befehle wie diesen benutzen: @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: +Ebenso können Sie wie folgt Schlüssel in eine bestimmte Keybox-Datei +herunterladen: @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. +Siehe @ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the +GNU Privacy Guard} für mehr Informationen zur Befehlszeilenoption +@option{--keyring} von GPG. -@item --key-download=@var{policy} -Handle missing OpenPGP keys according to @var{policy}, which may be one of: +@item --key-download=@var{Richtlinie} +Fehlende OpenPGP-Schlüssel gemäß dieser @var{Richtlinie} behandeln, für die +eine der Folgenden angegeben werden kann: @table @code @item always -Always download missing OpenPGP keys from the key server, and add them to -the user's GnuPG keyring. +Immer fehlende OpenPGP-Schlüssel herunterladen und zum GnuPG-Schlüsselbund +des Nutzers hinzufügen. @item never -Never try to download missing OpenPGP keys. Instead just bail out. +Niemals fehlende OpenPGP-Schlüssel herunterladen, sondern einfach abbrechen. @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. +Ist ein Paket mit einem unbekannten OpenPGP-Schlüssel signiert, wird der +Nutzer gefragt, ob der Schlüssel heruntergeladen werden soll oder +nicht. Dies entspricht dem vorgegebenen Verhalten. @end table -@item --key-server=@var{host} -Use @var{host} as the OpenPGP key server when importing a public key. +@item --key-server=@var{Host} +Den mit @var{Host} bezeichneten Rechner als Schlüsselserver für OpenPGP +benutzen, wenn ein öffentlicher Schlüssel importiert wird. @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. +Das @code{github}-Aktualisierungsprogramm benutzt die +@uref{https://developer.github.com/v3/, GitHub-Programmierschnittstelle} +(die »Github-API«), um Informationen über neue Veröffentlichungen +einzuholen. Geschieht dies oft, z.B.@: beim Auffrischen aller Pakete, so +wird GitHub irgendwann aufhören, weitere API-Anfragen zu +beantworten. Normalerweise sind 60 API-Anfragen pro Stunde erlaubt, für eine +vollständige Auffrischung aller GitHub-Pakete in Guix werden aber mehr +benötigt. Wenn Sie sich bei GitHub mit Ihrem eigenen API-Token +authentisieren, gelten weniger einschränkende Grenzwerte. Um einen API-Token +zu benutzen, setzen Sie die Umgebungsvariable @code{GUIX_GITHUB_TOKEN} auf +einen von @uref{https://github.com/settings/tokens} oder anderweitig +bezogenen API-Token. @node Aufruf von guix lint -@section Invoking @command{guix lint} +@section @command{guix lint} aufrufen @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): +@cindex Pakete, auf Fehler prüfen +Den Befehl @command{guix lint} gibt es, um Paketentwicklern beim Vermeiden +häufiger Fehler und bei der Einhaltung eines konsistenten Code-Stils zu +helfen. Er führt eine Reihe von Prüfungen auf einer angegebenen Menge von +Paketen durch, um in deren Definition häufige Fehler aufzuspüren. Zu den +verfügbaren @dfn{Prüfern} gehören (siehe @code{--list-checkers} für eine +vollständige Liste): @table @code @item synopsis @itemx description -Validate certain typographical and stylistic rules about package -descriptions and synopses. +Überprüfen, ob bestimmte typografische und stilistische Regeln in +Paketbeschreibungen und -zusammenfassungen eingehalten wurden. @item inputs-should-be-native -Identify inputs that should most likely be native inputs. +Eingaben identifizieren, die wahrscheinlich native Eingaben sein sollten. @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}). +Die URLs für die Felder @code{home-page} und @code{source} anrufen und nicht +erreichbare URLs melden. Wenn passend, wird eine @code{mirror://}-URL +vorgeschlagen. Wenn die Quell-URL auf eine GitHub-URL weiterleitet, wird +eine Empfehlung ausgegeben, direkt letztere zu verwenden. Es wird geprüft, +dass der Quell-Dateiname aussagekräftig ist, dass er also z.B.@: nicht nur +aus einer Versionsnummer besteht oder als »git-checkout« angegeben wurde, +ohne dass ein @code{Dateiname} deklariert wurde (siehe @ref{»origin«-Referenz}). @item source-unstable-tarball Parse the @code{source} URL to determine if a tarball from GitHub is @@ -9369,13 +9779,15 @@ autogenerated or if it is a release tarball. Unfortunately GitHub's autogenerated tarballs are sometimes regenerated. @item cve -@cindex security vulnerabilities +@cindex Sicherheitslücken @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}. +Bekannte Sicherheitslücken melden, die in den Datenbanken der »Common +Vulnerabilities and Exposures« (CVE) aus diesem und dem letzten Jahr +vorkommen, @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, wie sie von der +US-amerikanischen NIST veröffentlicht werden}. -To view information about a particular vulnerability, visit pages such as: +Um Informationen über eine bestimmte Sicherheitslücke angezeigt zu bekommen, +besuchen Sie Webseiten wie: @itemize @item @@ -9385,87 +9797,90 @@ To view information about a particular vulnerability, visit pages such as: @end itemize @noindent -where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g., +wobei Sie statt @code{CVE-YYYY-ABCD} die CVE-Kennnummer angeben — z.B.@: @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: +Paketentwickler können in ihren Paketrezepten den Namen und die Version des +Pakets in der @uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration +(CPE)} angeben, falls sich diese von dem in Guix benutzten Namen und der +Version unterscheiden, zum Beispiel so: @example (package (name "grub") ;; @dots{} - ;; CPE calls this package "grub2". + ;; CPE bezeichnet das Paket als "grub2". (properties '((cpe-name . "grub2") (cpe-version . "2.3"))) @end example @c See . -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: +Manche Einträge in der CVE-Datenbank geben die Version des Pakets nicht an, +auf das sie sich beziehen, und würden daher bis in alle Ewigkeit Warnungen +auslösen. Paketentwickler, die CVE-Warnmeldungen gefunden und geprüft haben, +dass diese ignoriert werden können, können sie wie in diesem Beispiel +deklarieren: @example (package (name "t1lib") ;; @dots{} - ;; These CVEs no longer apply and can be safely ignored. + ;; Diese CVEs treffen nicht mehr zu und können bedenkenlos ignoriert + ;; werden. (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. +@item Formatierung +Offensichtliche Fehler bei der Formatierung von Quellcode melden, z.B.@: +Leerraum-Zeichen am Zeilenende oder Nutzung von Tabulatorzeichen. @end table Die allgemeine Syntax lautet: @example -guix lint @var{options} @var{package}@dots{} +guix lint @var{Optionen} @var{Pakete}@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: +Wird kein Paket auf der Befehlszeile angegeben, dann werden alle Pakete +geprüft, die es gibt. Als @var{Optionen} können null oder mehr der folgenden +Befehlszeilenoptionen übergeben werden: @table @code @item --list-checkers @itemx -l -List and describe all the available checkers that will be run on packages -and exit. +Alle verfügbaren Prüfer für die Pakete auflisten und beschreiben. @item --checkers @itemx -c -Only enable the checkers specified in a comma-separated list using the names -returned by @code{--list-checkers}. +Nur die Prüfer aktivieren, die hiernach in einer kommagetrennten Liste aus +von @code{--list-checkers} aufgeführten Prüfern vorkommen. @end table @node Aufruf von guix size -@section Invoking @command{guix size} +@section @command{guix size} aufrufen -@cindex size -@cindex package size +@cindex Größe +@cindex Paketgröße @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. +Der Befehl @command{guix size} hilft Paketentwicklern dabei, den +Plattenplatzverbrauch von Paketen zu profilieren. Es ist leicht, die +Auswirkungen zu unterschätzen, die das Hinzufügen zusätzlicher +Abhängigkeiten zu einem Paket hat oder die das Verwenden einer einzelnen +Ausgabe für ein leicht aufteilbares Paket ausmacht (siehe @ref{Pakete mit mehreren Ausgaben.}). Das sind typische Probleme, auf die @command{guix size} +aufmerksam machen kann. -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: +Dem Befehl können eine oder mehrere Paketspezifikationen wie @code{gcc@@4.8} +oder @code{guile:debug} übergeben werden, oder ein Dateiname im +Store. Betrachten Sie dieses Beispiel: @example $ guix size coreutils -store item total self +Store-Objekt Gesamt Selbst /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% @@ -9474,270 +9889,303 @@ store item total self /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 +Gesamt: 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: +Die hier aufgelisteten Store-Objekte bilden den @dfn{transitiven Abschluss} +der Coreutils — d.h.@: die Coreutils und all ihre Abhängigkeiten und deren +Abhängigkeiten, rekursiv —, wie sie hiervon angezeigt würden: dag.pdf @end example -The output looks like this: +Die Ausgabe sieht so aus: -@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils} +@image{images/coreutils-graph,2in,,Abhängigkeitsgraph der GNU Coreutils} -Nice little graph, no? +Ein netter, kleiner Graph, oder? -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: +Aber es gibt mehr als eine Art von Graph! Der Graph oben ist kurz und knapp: +Es ist der Graph der Paketobjekte, ohne implizite Eingaben wie GCC, libc, +grep und so weiter. Oft möchte man einen knappen Graphen sehen, aber +manchmal will man auch mehr Details sehen. @command{guix graph} unterstützt +mehrere Typen von Graphen; Sie können den Detailgrad auswählen. @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. +Der vorgegebene Typ aus dem Beispiel oben. Er zeigt den DAG der Paketobjekte +ohne implizite Abhängigkeiten. Er ist knapp, filtert aber viele Details +heraus. @item reverse-package -This shows the @emph{reverse} DAG of packages. For example: +Dies zeigt den @emph{umgekehrten} DAG der Pakete. Zum Beispiel: @example guix graph --type=reverse-package ocaml @end example -...@: yields the graph of packages that depend on OCaml. +...@: yields the graph of packages that @emph{explicitly} depend on OCaml +(if you are also interested in cases where OCaml is an implicit dependency, +see @code{reverse-bag} below.) -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, +Beachten Sie, dass für Kernpakete damit gigantische Graphen entstehen +können. Wenn Sie nur die Anzahl der Pakete wissen wollen, die von einem +gegebenen Paket abhängen, benutzen Sie @command{guix refresh +--list-dependent} (siehe @ref{Aufruf von guix refresh, @option{--list-dependent}}). @item bag-emerged -This is the package DAG, @emph{including} implicit inputs. +Dies ist der Paket-DAG @emph{einschließlich} impliziter Eingaben. -For instance, the following command: +Zum Beispiel liefert der folgende Befehl: @example guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf @end example -...@: yields this bigger graph: +…@: diesen größeren Graphen: -@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU -Coreutils} +@image{images/coreutils-bag-graph,,5in,Detaillierter Abhängigkeitsgraph der +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}}). +Am unteren Rand des Graphen sehen wir alle impliziten Eingaben des +@var{gnu-build-system} (siehe @ref{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. +Beachten Sie dabei aber, dass auch hier die Abhängigkeiten dieser impliziten +Eingaben — d.h.@: die @dfn{Bootstrap-Abhängigkeiten} (siehe +@ref{Bootstrapping}) — nicht gezeigt werden, damit der Graph knapper bleibt. @item bag -Similar to @code{bag-emerged}, but this time including all the bootstrap -dependencies. +Ähnlich wie @code{bag-emerged}, aber diesmal mit allen +Bootstrap-Abhängigkeiten. @item bag-with-origins -Similar to @code{bag}, but also showing origins and their dependencies. +Ähnlich wie @code{bag}, aber auch mit den Ursprüngen und deren +Abhängigkeiten. + +@item reverse-bag +This shows the @emph{reverse} DAG of packages. Unlike +@code{reverse-package}, it also takes implicit dependencies into account. +For example: + +@example +guix graph -t reverse-bag dune +@end example + +@noindent +...@: yields the graph of all packages that depend on Dune, directly or +indirectly. Since Dune is an @emph{implicit} dependency of many packages +@i{via} @code{dune-build-system}, this shows a large number of packages, +whereas @code{reverse-package} would show very few if any. @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. +Diese Darstellung ist am detailliertesten: Sie zeigt den DAG der Ableitungen +(siehe @ref{Ableitungen}) und der einfachen Store-Objekte. Verglichen mit +obiger Darstellung sieht man viele zusätzliche Knoten einschließlich +Erstellungs-Skripts, Patches, Guile-Module usw. -For this type of graph, it is also possible to pass a @file{.drv} file name -instead of a package name, as in: +Für diesen Typ Graph kann auch der Name einer @file{.drv}-Datei anstelle +eines Paketnamens angegeben werden, etwa so: @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: +Dies ist der Graph der @dfn{Paketmodule} (siehe @ref{Paketmodule}). Zum +Beispiel zeigt der folgende Befehl den Graph für das Paketmodul an, das das +@code{guile}-Paket definiert: @example -guix graph -t module guile | dot -Tpdf > module-graph.pdf +guix graph -t module guile | dot -Tpdf > modul-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}: +Alle oben genannten Typen entsprechen @emph{Abhängigkeiten zur +Erstellungszeit}. Der folgende Graphtyp repräsentiert die +@emph{Abhängigkeiten zur Laufzeit}: @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}). +Dies ist der Graph der @dfn{Referenzen} einer Paketausgabe, wie +@command{guix gc --references} sie liefert (siehe @ref{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. +Wenn die angegebene Paketausgabe im Store nicht verfügbar ist, versucht +@command{guix graph}, die Abhängigkeitsinformationen aus Substituten zu +holen. -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!): +Hierbei können Sie auch einen Store-Dateinamen statt eines Paketnamens +angeben. Zum Beispiel generiert der Befehl unten den Referenzgraphen Ihres +Profils (der sehr groß werden kann!): @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}). +Dies ist der Graph der ein Store-Objekt @dfn{referenzierenden} Objekte, wie +@command{guix gc --referrers} sie liefern würde (siehe @ref{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. +Er basiert ausschließlich auf lokalen Informationen aus Ihrem Store. Nehmen +wir zum Beispiel an, dass das aktuelle Inkscape in 10 Profilen verfügbar +ist, dann wird @command{guix graph -t referrers inkscape} einen Graph +zeigen, der bei Inkscape gewurzelt ist und Kanten zu diesen 10 Profilen hat. -It can help determine what is preventing a store item from being garbage -collected. +Ein solcher Graph kann dabei helfen, herauszufinden, weshalb ein +Store-Objekt nicht vom Müllsammler abgeholt werden kann. @end table -The available options are the following: +Folgendes sind die verfügbaren Befehlszeilenoptionen: @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 --type=@var{Typ} +@itemx -t @var{Typ} +Eine Graph-Ausgabe dieses @var{Typ}s generieren. Dieser @var{Typ} muss einer +der oben genannten Werte sein. @item --list-types -List the supported graph types. +Die unterstützten Graph-Typen auflisten. -@item --backend=@var{backend} -@itemx -b @var{backend} -Produce a graph using the selected @var{backend}. +@item --backend=@var{Backend} +@itemx -b @var{Backend} +Einen Graph mit Hilfe des ausgewählten @var{Backend}s generieren. @item --list-backends -List the supported graph backends. +Die unterstützten Graph-Backends auflisten. -Currently, the available backends are Graphviz and d3.js. +Derzeit sind die verfügbaren Backends Graphviz und 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: +Dies ist nützlich, um genau ein bestimmtes Paket zu referenzieren, wie in +diesem Beispiel: @example guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' @@ -9745,11 +10193,11 @@ guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' @item --system=@var{System} @itemx -s @var{System} -Display the graph for @var{system}---e.g., @code{i686-linux}. +Den Graphen für das @var{System} anzeigen — z.B.@: @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. +Der Abhängigkeitsgraph ist größtenteils von der Systemarchitektur +unabhängig, aber ein paar architekturabhängige Teile können Ihnen mit dieser +Befehlszeilenoption visualisiert werden. @end table @@ -9760,17 +10208,18 @@ visualize. @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}). +Substitutserver einsetzen können (siehe @ref{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. +Wenn @command{guix publish} ausgeführt wird, wird dadurch ein HTTP-Server +gestartet, so dass jeder mit Netzwerkzugang davon Substitute beziehen +kann. Das bedeutet, dass jede Maschine, auf der Guix läuft, auch als +Build-Farm fungieren kann, weil die HTTP-Schnittstelle mit Hydra, der +Software, mit der die offizielle Build-Farm @code{@value{SUBSTITUTE-SERVER}} +betrieben wird, kompatibel ist. 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 +@ref{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 @@ -9778,7 +10227,7 @@ 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}). +--generate-key} ausführen (siehe @ref{Aufruf von guix archive}). Die allgemeine Syntax lautet: @@ -9793,7 +10242,7 @@ ein HTTP-Server gestartet, der auf Port 8080 lauscht: guix publish @end example -Sobald ein Server zum Veröffentlichen autorisiert wurde (@pxref{Aufruf von guix archive}), kann der Daemon davon Substitute herunterladen: +Sobald ein Server zum Veröffentlichen autorisiert wurde (siehe @ref{Aufruf von guix archive}), kann der Daemon davon Substitute herunterladen: @example guix-daemon --substitute-urls=http://example.org:8080 @@ -9807,15 +10256,15 @@ 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}). +überprüfen, was so ein Server anbietet (siehe @ref{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}): +eingetragen sind (siehe @ref{»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 @ref{Aufruf von guix hash}): @example http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i @@ -9834,14 +10283,14 @@ http://example.org/log/gwspk@dots{}-guile-2.2.3 @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 +komprimiert abspeichert, wie es voreingestellt ist (siehe @ref{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: +Folgende Befehlszeilenoptionen stehen zur Verfügung: @table @code @item --port=@var{Port} @@ -9856,7 +10305,7 @@ 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 +hinausgehenden Berechtigungen ablegen — d.h.@: sobald der Server-Socket geöffnet und der Signierschlüssel gelesen wurde. @item --compression[=@var{Stufe}] @@ -9897,7 +10346,7 @@ 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, +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 @@ -9931,8 +10380,8 @@ 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}). +Den @var{Pfad} als Präfix für die URLs von »nar«-Dateien benutzen (siehe +@ref{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 @@ -9948,21 +10397,22 @@ 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 +von @command{guix archive --generate-key} erzeugt wird (siehe @ref{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. +Einen Guile-REPL-Server (siehe @ref{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}}). +@command{guix publish} auf einem »Guix System«-System zu aktivieren ist ein +Einzeiler: Instanziieren Sie einfach einen +@code{guix-publish-service-type}-Dienst im @code{services}-Feld Ihres +@code{operating-system}-Objekts zur Betriebssystemdeklaration (siehe +@ref{guix-publish-service-type, @code{guix-publish-service-type}}). Falls Sie Guix aber auf einer »Fremddistribution« laufen lassen, folgen Sie folgenden Anweisungen: @@ -9991,79 +10441,86 @@ Ihre Distribution verwendet. @end itemize @node Aufruf von guix challenge -@section Invoking @command{guix challenge} +@section @command{guix challenge} aufrufen @cindex Reproduzierbare Erstellungen -@cindex verifiable builds +@cindex verifizierbare Erstellungen @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: +@cindex Anfechten +Entsprechen die von diesem Server gelieferten Binärdateien tatsächlich dem +Quellcode, aus dem sie angeblich erzeugt wurden? Ist ein +Paketerstellungsprozess deterministisch? Diese Fragen versucht @command{guix +challenge} zu beantworten. + +Die erste Frage ist offensichtlich wichtig: Bevor man einen Substitutserver +benutzt (siehe @ref{Substitute}), @emph{verifiziert} man besser, dass er +die richtigen Binärdateien liefert, d.h.@: man @emph{fechtet sie an}. Die +letzte Frage macht die erste möglich: Wenn Paketerstellungen deterministisch +sind, müssten voneinander unabhängige Erstellungen genau dasselbe Ergebnis +liefern, Bit für Bit; wenn ein Server mit einer anderen Binärdatei als der +lokal erstellten Binärdatei antwortet, ist diese entweder beschädigt oder +bösartig. + +Wir wissen, dass die in @file{/gnu/store}-Dateinamen auftauchende +Hash-Prüfsumme der Hash aller Eingaben des Prozesses ist, mit dem die Datei +oder das Verzeichnis erstellt wurde — Compiler, Bibliotheken, +Erstellungsskripts und so weiter (siehe @ref{Einführung}). Wenn wir von +deterministischen Erstellungen ausgehen, sollte ein Store-Dateiname also auf +genau eine Erstellungsausgabe abgebildet werden. Mit @command{guix +challenge} prüft man, ob es tatsächlich eine eindeutige Abbildung gibt, +indem die Erstellungsausgaben mehrerer unabhängiger Erstellungen jedes +angegebenen Store-Objekts verglichen werden. + +Die Ausgabe des Befehls sieht so aus: @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 +Liste der Substitute von »https://@value{SUBSTITUTE-SERVER}« wird aktualisiert … 100.0% +Liste der Substitute von »https://guix.example.org« wird aktualisiert … 100.0% +Inhalt von /gnu/store/@dots{}-openssl-1.0.2d verschieden: + lokale Prüfsumme: 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 +Inhalt von /gnu/store/@dots{}-git-2.5.0 verschieden: + lokale Prüfsumme: 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 +Inhalt von /gnu/store/@dots{}-pius-2.1.1 verschieden: + lokale Prüfsumme: 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 +6,406 Store-Objekte wurden analysiert: + — 4,749 (74.1%) waren identisch + — 525 (8.2%) unterscheiden sich + — 1,132 (17.7%) blieben ergebnislos @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}): +In diesem Beispiel wird mit @command{guix challenge} zuerst die Menge lokal +erstellter Ableitungen im Store ermittelt — im Gegensatz zu von einem +Substitserver heruntergeladenen Store-Objekten — und dann werden alle +Substitutserver angefragt. Diejenigen Store-Objekte, bei denen der Server +ein anderes Ergebnis berechnet hat als die lokale Erstellung, werden +gemeldet. + +@cindex Nichtdeterminismus, in Paketerstellungen +Nehmen wir zum Beispiel an, @code{guix.example.org} gibt uns immer eine +verschiedene Antwort, aber @code{@value{SUBSTITUTE-SERVER}} stimmt mit +lokalen Erstellungen überein, @emph{außer} im Fall von Git. Das könnte ein +Hinweis sein, dass der Erstellungsprozess von Git nichtdeterministisch ist; +das bedeutet, seine Ausgabe variiert abhängig von verschiedenen Umständen, +die Guix nicht vollends kontrollieren kann, obwohl es Pakete in isolierten +Umgebungen erstellt (siehe @ref{Funktionalitäten}). Zu den häufigsten Quellen von +Nichtdeterminismus gehören das Einsetzen von Zeitstempeln innerhalb der +Erstellungsgebnisse, das Einsetzen von Zufallszahlen und von Auflistungen +eines Verzeichnisinhalts sortiert nach der Inode-Nummer. Siehe +@uref{https://reproducible-builds.org/docs/} für mehr Informationen. + +Um herauszufinden, was mit dieser Git-Binärdatei nicht stimmt, können wir so +etwas machen (siehe @ref{Aufruf von guix archive}): @example $ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ @@ -10071,269 +10528,288 @@ $ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ $ 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. +Dieser Befehl zeigt die Unterschiede zwischen den Dateien, die sich aus der +lokalen Erstellung ergeben, und den Dateien, die sich aus der Erstellung auf +@code{@value{SUBSTITUTE-SERVER}} ergeben (siehe @ref{Overview, Comparing and +Merging Files,, diffutils, Comparing and Merging Files}). Der Befehl +@command{diff} funktioniert großartig für Textdateien. Wenn sich +Binärdateien unterscheiden, ist @uref{https://diffoscope.org/, Diffoscope} +die bessere Wahl: Es ist ein hilfreiches Werkzeug, das Unterschiede in allen +Arten von Dateien visualisiert. -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. +Sobald Sie mit dieser Arbeit fertig sind, können Sie erkennen, ob die +Unterschiede aufgrund eines nichtdeterministischen Erstellungsprozesses oder +wegen einem bösartigen Server zustande kommen. Wir geben uns Mühe, Quellen +von Nichtdeterminismus in Paketen zu entfernen, damit Substitute leichter +verifiziert werden können, aber natürlich ist an diesem Prozess nicht nur +Guix, sondern ein großer Teil der Freie-Software-Gemeinschaft beteiligt. In +der Zwischenzeit ist @command{guix challenge} eines der Werkzeuge, die das +Problem anzugehen helfen. -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: +Wenn Sie ein Paket für Guix schreiben, ermutigen wir Sie, zu überprüfen, ob +@code{@value{SUBSTITUTE-SERVER}} und andere Substitutserver dasselbe +Erstellungsergebnis bekommen, das Sie bekommen haben. Das geht so: @example -$ guix challenge @var{package} +$ guix challenge @var{Paket} @end example @noindent -where @var{package} is a package specification such as @code{guile@@2.0} or -@code{glibc:debug}. +Dabei wird mit @var{Paket} eine Paketspezifikation wie @code{guile@@2.0} +oder @code{glibc:debug} bezeichnet. Die allgemeine Syntax lautet: @example -guix challenge @var{options} [@var{packages}@dots{}] +guix challenge @var{Optionen} [@var{Pakete}@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.) +Wird ein Unterschied zwischen der Hash-Prüfsumme des lokal erstellten +Objekts und dem vom Server gelieferten Substitut festgestellt, oder zwischen +den Substituten von unterschiedlichen Servern, dann wird der Befehl dies wie +im obigen Beispiel anzeigen und mit dem Exit-Code 2 terminieren (andere +Exit-Codes außer null stehen für andere Arten von Fehlern). -The one option that matters is: +Die eine, wichtige Befehlszeilenoption ist: @table @code @item --substitute-urls=@var{URLs} -Consider @var{urls} the whitespace-separated list of substitute source URLs -to compare to. +Die @var{URLs} als durch Leerraumzeichen getrennte Liste von +Substitut-Quell-URLs benutzen. mit denen verglichen wird. @item --verbose @itemx -v -Show details about matches (identical contents) in addition to information -about mismatches. +Details auch zu Übereinstimmungen (deren Inhalt identisch ist) ausgeben, +zusätzlich zu Informationen über Unterschiede. @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} \ +@section @command{guix copy} aufrufen + +@cindex Kopieren, von Store-Objekten, über SSH +@cindex SSH, Kopieren von Store-Objekten +@cindex Store-Objekte zwischen Maschinen teilen +@cindex Übertragen von Store-Objekten zwischen Maschinen +Der Befehl @command{guix copy} kopiert Objekte aus dem Store einer Maschine +in den Store einer anderen Maschine mittels einer Secure-Shell-Verbindung +(kurz SSH-Verbindung)@footnote{Dieser Befehl steht nur dann zur Verfügung, +wenn Guile-SSH gefunden werden kann. Siehe @ref{Voraussetzungen} für +Details.}. Zum Beispiel kopiert der folgende Befehl das Paket +@code{coreutils}, das Profil des Benutzers und all deren Abhängigkeiten auf +den anderen @var{Rechner}, dazu meldet sich Guix als @var{Benutzer} an: + +@example +guix copy --to=@var{Benutzer}@@@var{Rechner} \ 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. +Wenn manche der zu kopierenden Objekte schon auf dem anderen @var{Rechner} +vorliegen, werden sie tatsächlich @emph{nicht} übertragen. -The command below retrieves @code{libreoffice} and @code{gimp} from -@var{host}, assuming they are available there: +Der folgende Befehl bezieht @code{libreoffice} und @code{gimp} von dem +@var{Rechner}, vorausgesetzt sie sind dort verfügbar: @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. +Die SSH-Verbindung wird mit dem Guile-SSH-Client hergestellt, der mit +OpenSSH kompatibel ist: Er berücksichtigt @file{~/.ssh/known_hosts} und +@file{~/.ssh/config} und verwendet den SSH-Agenten zur Authentifizierung. -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. +Der Schlüssel, mit dem gesendete Objekte signiert sind, muss von der +entfernten Maschine akzeptiert werden. Ebenso muss der Schlüssel, mit dem +die Objekte signiert sind, die Sie von der entfernten Maschine empfangen, in +Ihrer Datei @file{/etc/guix/acl} eingetragen sein, damit Ihr Daemon sie +akzeptiert. Siehe @ref{Aufruf von guix archive} für mehr Informationen über +die Authentifizierung von Store-Objekten. Die allgemeine Syntax lautet: @example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} +guix copy [--to=@var{Spezifikation}|--from=@var{Spezifikation}] @var{Objekte}@dots{} @end example -You must always specify one of the following options: +Sie müssen immer eine der folgenden Befehlszeilenoptionen angeben: @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 +@item --to=@var{Spezifikation} +@itemx --from=@var{Spezifikation} +Gibt den Rechner (den »Host«) an, an den oder von dem gesendet +bzw. empfangen wird. Die @var{Spezifikation} muss eine SSH-Spezifikation +sein wie @code{example.org}, @code{charlie@@example.org} oder @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}. +Die @var{Objekte} können entweder Paketnamen wie @code{gimp} oder +Store-Objekte wie @file{/gnu/store/@dots{}-idutils-4.6} sein. -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}). +Wenn ein zu sendendes Paket mit Namen angegeben wird, wird es erst erstellt, +falls es nicht im Store vorliegt, außer @option{--dry-run} wurde angegeben +wurde. Alle gemeinsamen Erstellungsoptionen werden unterstützt (siehe +@ref{Gemeinsame Erstellungsoptionen}). @node Aufruf von guix container -@section Invoking @command{guix container} +@section @command{guix container} aufrufen @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. +Dieses Werkzeug ist noch experimentell, Stand Version @value{VERSION}. Die +Schnittstelle wird sich in Zukunft grundlegend verändern. @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. +Der Zweck von @command{guix container} ist, in einer isolierten Umgebung +(gemeinhin als »Container« bezeichnet) laufende Prozesse zu manipulieren, +die typischerweise durch die Befehle @command{guix environment} (siehe +@ref{Aufruf von guix environment}) und @command{guix system container} (siehe +@ref{Aufruf von guix system}) erzeugt werden. Die allgemeine Syntax lautet: @example -guix container @var{action} @var{options}@dots{} +guix container @var{Aktion} @var{Optionen}@dots{} @end example -@var{action} specifies the operation to perform with a container, and -@var{options} specifies the context-specific arguments for the action. +Mit @var{Aktion} wird die Operation angegeben, die in der isolierten +Umgebung durchgeführt werden soll, und mit @var{Optionen} werden die +kontextabhängigen Argumente an die Aktion angegeben. -The following actions are available: +Folgende Aktionen sind verfügbar: @table @code @item exec -Execute a command within the context of a running container. +Führt einen Befehl im Kontext der laufenden isolierten Umgebung aus. -The syntax is: +Die Syntax ist: @example -guix container exec @var{pid} @var{program} @var{arguments}@dots{} +guix container exec @var{PID} @var{Programm} @var{Argumente}@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}. +@var{PID} gibt die Prozess-ID der laufenden isolierten Umgebung an. Als +@var{Programm} muss eine ausführbare Datei im Wurzeldateisystem der +isolierten Umgebung angegeben werden. Die @var{Argumente} sind die +zusätzlichen Befehlszeilenoptionen, die an das @var{Programm} übergeben +werden. -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: +Der folgende Befehl startet eine interaktive Anmelde-Shell innerhalb einer +isolierten Guix-Systemumgebung, gestartet durch @command{guix system +container}, dessen Prozess-ID 9001 ist: @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. +Beachten Sie, dass die @var{PID} nicht der Elternprozess der isolierten +Umgebung sein darf, sondern PID 1 in der isolierten Umgebung oder einer +seiner Kindprozesse sein muss. @end table @node Aufruf von guix weather -@section Invoking @command{guix weather} +@section @command{guix weather} aufrufen -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}). +Manchmal werden Sie schlecht gelaunt sein, weil es zu wenige Substitute gibt +und die Pakete bei Ihnen selbst erstellt werden müssen (siehe +@ref{Substitute}). Der Befehl @command{guix weather} zeigt einen Bericht +über die Verfügbarkeit von Substituten auf den angegebenen Servern an, damit +Sie sich eine Vorstellung davon machen können, wie es heute um Ihre Laune +bestellt sein wird. Manchmal bekommt man als Nutzer so hilfreiche +Informationen, aber in erster Linie nützt der Befehl den Leuten, die +@command{guix publish} benutzen (siehe @ref{Aufruf von guix publish}). -@cindex statistics, for substitutes -@cindex availability of substitutes -@cindex substitute availability -@cindex weather, substitute availability -Here's a sample run: +@cindex Statistik, für Substitute +@cindex Verfügbarkeit von Substituten +@cindex Substitutverfügbarkeit +@cindex Wetter, Substitutverfügbarkeit +Hier ist ein Beispiel für einen Aufruf davon: @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.. +5.872 Paketableitungen für x86_64-linux berechnen … +Nach 6.128 Store-Objekten von https://guix.example.org suchen … 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. + 43,4% Substitute verfügbar (2.658 von 6.128) + 7.032,5 MiB an Nars (komprimiert) + 19.824,2 MiB auf der Platte (unkomprimiert) + 0,030 Sekunden pro Anfrage (182,9 Sekunden insgesamt) + 33,5 Anfragen pro Sekunde + + 9,8% (342 von 3.470) der fehlenden Objekte sind in der Warteschlange + Mindestens 867 Erstellungen in der Warteschlange + x86_64-linux: 518 (59,7%) + i686-linux: 221 (25,5%) + aarch64-linux: 128 (14,8%) + Erstellungsgeschwindigkeit: 23,41 Erstellungen pro Stunde + x86_64-linux: 11,16 Erstellungen pro Stunde + i686-linux: 6,03 Erstellungen pro Stunde + aarch64-linux: 6,41 Erstellungen pro Stunde +@end example + +@cindex Kontinuierliche Integration, Statistik +Wie Sie sehen können, wird der Anteil unter allen Paketen angezeigt, für die +auf dem Server Substitute verfügbar sind — unabhängig davon, ob Substitute +aktiviert sind, und unabhängig davon, ob der signierende Schlüssel des +Servers autorisiert ist. Es wird auch über die Größe der komprimierten +Archive (die »Nars«) berichtet, die vom Server angeboten werden, sowie über +die Größe, die die zugehörigen Store-Objekte im Store belegen würden (unter +der Annahme, dass Deduplizierung abgeschaltet ist) und über den Durchsatz +des Servers. Der zweite Teil sind Statistiken zur Kontinuierlichen +Integration (englisch »Continuous Integration«, kurz CI), wenn der Server +dies unterstützt. Des Weiteren kann @command{guix weather}, wenn es mit der +Befehlszeilenoption @option{--coverage} aufgerufen wird, »wichtige« +Paketsubstitute, die auf dem Server fehlen, auflisten (siehe unten). + +Dazu werden mit @command{guix weather} Anfragen über HTTP(S) zu Metadaten +(@dfn{Narinfos}) für alle relevanten Store-Objekte gestellt. Wie +@command{guix challenge} werden die Signaturen auf den Substituten +ignoriert, was harmlos ist, weil der Befehl nur Statistiken sammelt und +keine Substitute installieren kann. + +Neben anderen Dingen ist es möglich, bestimmte Systemtypen und bestimmte +Paketmengen anzufragen. Die verfügbaren Befehlszeilenoptionen sind folgende: @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. +@var{URLs} ist eine leerzeichengetrennte Liste anzufragender +Substitutserver-URLs. Wird diese Befehlszeilenoption weggelassen, wird die +vorgegebene Menge an Substitutservern angefragt. @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. +Substitute für das @var{System} anfragen — z.B.@: für +@code{aarch64-linux}. Diese Befehlszeilenoption kann mehrmals angegeben +werden, wodurch @command{guix weather} die Substitute für mehrere +Systemtypen anfragt. @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: +Anstatt die Substitute für alle Pakete anzufragen, werden nur die in der +@var{Datei} angegebenen Pakete erfragt. Die @var{Datei} muss ein +@dfn{Manifest} enthalten, wie bei der Befehlszeilenoption @code{-m} von +@command{guix package} (siehe @ref{Aufruf von guix package}). + +@item --coverage[=@var{Anzahl}] +@itemx -c [@var{Anzahl}] +Einen Bericht über die Substitutabdeckung für Pakete ausgeben, d.h.@: Pakete +mit mindestens @var{Anzahl}-vielen Abhängigen (voreingestellt mindestens +null) anzeigen, für die keine Substitute verfügbar sind. Die abhängigen +Pakete werden selbst nicht aufgeführt: Wenn @var{b} von @var{a} abhängt und +Substitute für @var{a} fehlen, wird nur @var{a} aufgeführt, obwohl dann in +der Regel auch die Substitute für @var{b} fehlen. Das Ergebnis sieht so aus: @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% +8.983 Paketableitungen für x86_64-linux berechnen … +Nach 9.343 Store-Objekten von https://ci.guix.de.info suchen … +Liste der Substitute von »https://ci.guix.de.info« wird aktualisiert … 100.0% https://ci.guix.de.info - 64.7% substitutes available (6,047 out of 9,343) + 64.7% Substitute verfügbar (6.047 von 9.343) @dots{} -2502 packages are missing from 'https://ci.guix.de.info' for 'x86_64-linux', among which: +2502 Pakete fehlen auf »https://ci.guix.de.info« für »x86_64-linux«, darunter sind: 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 @@ -10352,13 +10828,14 @@ simply fail to build. @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: +Der Befehl @command{guix processes} kann sich für Entwickler und +Systemadministratoren als nützlich erweisen, besonders auf Maschinen mit +mehreren Nutzern und auf Build-Farms. Damit werden die aktuellen Sitzungen +(also Verbindungen zum Daemon) sowie Informationen über die beteiligten +Prozesse aufgelistet@footnote{Entfernte Sitzungen, wenn +@command{guix-daemon} mit @option{--listen} unter Angabe eines TCP-Endpunkts +gestartet wurde, werden @emph{nicht} aufgelistet.}. Hier ist ein Beispiel +für die davon gelieferten Informationen: @example $ sudo guix processes @@ -10381,23 +10858,25 @@ 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. +In diesem Beispiel sehen wir, dass @command{guix-daemon} drei Clients hat: +@command{guix environment}, @command{guix publish} und das Werkzeug Cuirass +zur Kontinuierlichen Integration. Deren Prozesskennung (PID) ist jeweils im +@code{ClientPID}-Feld zu sehen. Das Feld @code{SessionPID} zeigt die PID des +@command{guix-daemon}-Unterprozesses dieser bestimmten Sitzung. -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}). +Das Feld @code{LockHeld} zeigt an, welche Store-Objekte derzeit durch die +Sitzung gesperrt sind, d.h.@: welche Store-Objekte zur Zeit erstellt oder +substituiert werden (das @code{LockHeld}-Feld wird nicht angezeigt, wenn +@command{guix processes} nicht als Administratornutzer root ausgeführt +wird). Letztlich sehen wir am @code{ChildProcess}-Feld oben, dass diese drei +Erstellungen hier ausgelagert (englisch »offloaded«) werden (siehe +@ref{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: +Die Ausgabe ist im Recutils-Format, damit wir den praktischen +@command{recsel}-Befehl benutzen können, um uns interessierende Sitzungen +auszuwählen (siehe @ref{Selection Expressions,,, recutils, GNU recutils +manual}). Zum Beispiel zeigt dieser Befehl die Befehlszeile und PID des +Clients an, der die Erstellung des Perl-Pakets ausgelöst hat: @example $ sudo guix processes | \ @@ -10411,11 +10890,11 @@ ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} @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 +Die »Guix System«-Distribution 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. @@ -10423,7 +10902,7 @@ Benutzerkonten. Sie alle werden an derselben Stelle deklariert. So eine 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 +aktualisierte System nicht richtig funktioniert (siehe @ref{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 @@ -10441,6 +10920,7 @@ Systemdienste zu unterstützen. * Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. * Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. * Benutzerkonten:: Benutzerkonten festlegen. +* Tastaturbelegung:: Wie das System Tastendrücke interpretiert. * Locales:: Sprache und kulturelle Konventionen. * Dienste:: Systemdienste festlegen. * Setuid-Programme:: Mit Administratorrechten startende Programme. @@ -10449,7 +10929,8 @@ Systemdienste zu unterstützen. * 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. +* Guix in einer VM starten:: Wie man »Guix System« in einer virtuellen + Maschine startet. * Dienste definieren:: Neue Dienstdefinitionen hinzufügen. @end menu @@ -10458,7 +10939,7 @@ Systemdienste zu unterstützen. 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 +dem Befehl @command{guix system} übergeben (siehe @ref{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: @@ -10473,7 +10954,7 @@ 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 +erläutert (siehe @ref{»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. @@ -10496,24 +10977,23 @@ Fall sollte das @code{bootloader}-Feld in etwa so aussehen: (target "/boot/efi")) @end example -Siehe den Abschnitt @xref{Bootloader-Konfiguration} für weitere -Informationen zu den verfügbaren Konfigurationsoptionen. +Siehe den Abschnitt @ref{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 +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 +nutzereigenen Profilen (siehe @ref{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: +@code{(gnu packages screen)} genommen wird (siehe @ref{Paketmodule}). Die Syntax @code{(list package output)} kann benutzt werden, um +eine bestimmte Ausgabe eines Pakets auszuwählen: @lisp (use-modules (gnu packages)) @@ -10549,24 +11029,26 @@ Name-Versions-Paar zu Grunde liegende Paket liefert: @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}). +Das Feld @code{services} listet @dfn{Systemdienste} auf, die zur Verfügung +stehen sollen, wenn das System startet (siehe @ref{Dienste}). Die +@code{operating-system}-Deklaration oben legt fest, dass wir neben den +grundlegenden Basis-Diensten auch wollen, dass der +OpenSSH-Secure-Shell-Daemon auf Port 2222 lauscht (siehe @ref{Netzwerkdienste, @code{openssh-service-type}}). Intern sorgt der +@code{openssh-service-type} dafür, dass @code{sshd} mit den richtigen +Befehlszeilenoptionen aufgerufen wird, je nach Systemkonfiguration werden +auch für dessen Betrieb nötige Konfigurationsdateien erstellt (siehe +@ref{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 +(siehe @ref{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}}), +modifizieren möchten (siehe @ref{Basisdienste, @code{%base-services}}), schreiben Sie das Folgende in Ihre Betriebssystemdeklaration: @lisp @@ -10587,7 +11069,7 @@ schreiben Sie das Folgende in Ihre Betriebssystemdeklaration: (services %my-services)) @end lisp -Dadurch ändert sich die Konfiguration — d.h. die Dienst-Parameter — der +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, @@ -10621,14 +11103,14 @@ 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, +Im Abschnitt @ref{Desktop-Dienste} finden Sie eine genaue Liste der unter +@var{%desktop-services} angebotenen Dienste. Der Abschnitt @ref{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 +(siehe @ref{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. @@ -10643,7 +11125,7 @@ Diensten von @var{%desktop-services} außer dem Avahi-Dienst. 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}). +und macht sie zum voreingestellten GRUB-Boot-Eintrag (siehe @ref{Aufruf von guix system}). Der normale Weg, die Systemkonfiguration nachträglich zu ändern, ist, die Datei zu aktualisieren und @command{guix system reconfigure} erneut @@ -10658,7 +11140,7 @@ 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 +womit Sie alte Generationen beim Starten 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, @@ -10667,40 +11149,40 @@ das System mit den Befehlen @command{guix system roll-back} und 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 +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}). +Generationen überschreibt (siehe @ref{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}): +instanziiert (siehe @ref{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}). +erstellt wird (siehe @ref{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! +Diese Prozedur wird vom Modul @code{(gnu system)} angeboten. Zusammen mit +@code{(gnu services)} (siehe @ref{Dienste}) deckt dieses Modul den Kern von +»Guix System« ab. Schauen Sie es sich mal an! @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}). +@code{operating-system}-Deklarationen zur Verfügung stehen (siehe @ref{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}). +einzelne Nutzer bezieht (siehe @ref{Das Konfigurationssystem nutzen}). @table @asis @item @code{kernel} (Vorgabe: @var{linux-libre}) @@ -10711,23 +11193,46 @@ 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")}. +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}. +wird. Siehe @ref{Bootloader-Konfiguration}. + +@item @code{label} +This is the label (a string) as it appears in the bootloader's menu entry. +The default label includes the kernel name and version. + +@item @code{keyboard-layout} (Vorgabe: @code{#f}) +Dieses Feld gibt an, welche Tastaturbelegung auf der Konsole benutzt werden +soll. Es kann entweder auf @code{#f} gesetzt sein, damit die voreingestellte +Tastaturbelegung benutzt wird (in der Regel ist diese »US English«), oder +ein @code{}-Verbundsobjekt sein. + +Diese Tastaturbelegung wird benutzt, sobald der Kernel gebootet wurde. Diese +Tastaturbelegung wird zum Beispiel auch verwendet, wenn Sie eine Passphrase +eintippen, falls sich Ihr Wurzeldateisystem auf einem mit +@code{luks-device-mapping} zugeordneten Gerät befindet (siehe @ref{Zugeordnete Geräte}). + +@quotation Anmerkung +Damit wird @emph{nicht} angegeben, welche Tastaturbelegung der Bootloader +benutzt, und auch nicht, welche der grafische Display-Server +verwendet. Siehe @ref{Bootloader-Konfiguration} für Informationen darüber, +wie Sie die Tastaturbelegung des Bootloaders angeben können. Siehe @ref{X Window} für Informationen darüber, wie Sie die Tastaturbelegung angeben +können, die das X-Fenstersystem verwendet. +@end quotation @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}. +Verfügung stehen sollen. Siehe @ref{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}. +brauchen. Siehe @ref{Initiale RAM-Disk}. @item @code{firmware} (Vorgabe: @var{%base-firmware}) @cindex Firmware @@ -10736,37 +11241,37 @@ 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. +@code{ath9k} und @code{b43-open}). Siehe den Abschnitt @ref{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}. +Ein dateiartiges Objekt (siehe @ref{G-Ausdrücke, file-like objects}), das +für @file{/etc/hosts} benutzt werden soll (siehe @ref{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}. +Eine Liste zugeordneter Geräte (»mapped devices«). Siehe @ref{Zugeordnete Geräte}. @item @code{file-systems} -Eine Liste von Dateisystemen. Siehe @xref{Dateisysteme}. +Eine Liste von Dateisystemen. Siehe @ref{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 +»Swap-Speicher« genutzte Dateien identifizieren (siehe @ref{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}. +@ref{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}. +Liste der Benutzerkonten und Benutzergruppen. Siehe @ref{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 @@ -10774,8 +11279,8 @@ aufgeführt wird, wird automatisch für den Administrator ein @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 +Objekt (siehe @ref{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: @@ -10798,55 +11303,61 @@ 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}). +Werkzeuge (»non-core«) stattdessen in Nutzerprofile zu installieren (siehe +@ref{Aufruf von guix package}). @item @code{timezone} -Eine Zeichenkette, die die Zeitzone bezeichnet, wie -z.B. @code{"Europe/Berlin"}. +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. +Der Name der als Voreinstellung zu verwendenden Locale (siehe @ref{Locale +Names,,, libc, The GNU C Library Reference Manual}). Siehe @ref{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}. +laufenden System benutzt werden können. Siehe @ref{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, +@ref{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{}-Objekt. Siehe @xref{Name Service Switch}, für +@code{}-Objekt. Siehe @ref{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}. +repräsentieren. Siehe @ref{Dienste}. + +@cindex essenzielle Dienste +@item @code{essential-services} (Vorgabe: …) +The list of ``essential services''---i.e., things like instances of +@code{system-service-type} and @code{host-name-service-type} (@pxref{Service-Referenz}), which are derived from the operating system definition itself. +As a user you should @emph{never} need to touch this field. @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. +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}. +bezeichnen. Siehe @ref{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}}). +(siehe @ref{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 @@ -10855,13 +11366,34 @@ Mitglieder der Benutzergruppe @code{wheel} den @code{sudo}-Befehl verwenden dürfen. @end table + +@deffn {Scheme Syntax} this-operating-system +When used in the @emph{lexical scope} of an operating system field +definition, this identifier resolves to the operating system being defined. + +The example below shows how to refer to the operating system being defined +in the definition of the @code{label} field: + +@example +(use-modules (gnu) (guix)) + +(operating-system + ;; ... + (label (package-full-name + (operating-system-kernel this-operating-system)))) +@end example + +It is an error to refer to @code{this-operating-system} outside an operating +system definition. +@end deffn + @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-systems}-Feld der Betriebssystemdeklaration (siehe @ref{Das Konfigurationssystem nutzen}). Jedes Dateisystem wird mit der @code{file-system}-Form deklariert, etwa so: @example @@ -10880,12 +11412,12 @@ folgende Komponenten auf: @table @asis @item @code{type} -Eine Zeichenkette, die den Typ des Dateisystems spezifiziert, -z.B. @code{"ext4"}. +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. +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 @@ -10918,7 +11450,7 @@ 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 +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: @@ -10930,14 +11462,14 @@ hier: (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 +Wenn die Quelle eines Dateisystems ein zugeordnetes Gerät (siehe @ref{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}, +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). @@ -10978,7 +11510,7 @@ Betrachten Sie zum Beispiel eine Hierarchie von Einbindungen: 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}). +abhängt, zum Beispiel zur Verschlüsselung einer Partition (siehe @ref{Zugeordnete Geräte}). @end table @end deftp @@ -10995,21 +11527,21 @@ jeden Fall mindestens diese enthalten. @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 +(siehe @ref{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, +zwischen Prozessen teilen zu können (siehe @ref{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 +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. @@ -11044,7 +11576,7 @@ 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 +@dfn{Übersetzer}-Mechanismus (siehe @ref{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 @@ -11093,8 +11625,8 @@ Linux-Kernel-Modul @code{dm-crypt} vorausgesetzt. @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 +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 @@ -11105,7 +11637,7 @@ Das folgende Beispiel gibt eine Zuordnung von @file{/dev/sda3} auf @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}). +@code{file-system}-Deklaration benutzt werden (siehe @ref{Dateisysteme}). @example (mapped-device @@ -11115,7 +11647,7 @@ einem Standardmechanismus zur Plattenverschlüsselung. Das Gerät @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 +Sie auch die LUKS-UUID (@dfn{unique identifier}, d.h.@: den eindeutigen Bezeichner) des Quellgeräts auf der Befehlszeile ermitteln: @example @@ -11137,7 +11669,7 @@ 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}. +@ref{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: @@ -11150,10 +11682,10 @@ Ein RAID-Gerät als Verbund der Partitionen @file{/dev/sda1} und @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. +@code{file-system}-Deklaration dienen (siehe @ref{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 @@ -11223,15 +11755,15 @@ 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}). +als Shell dienen soll (siehe @ref{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. +auf grafischen Anmeldebildschirmen nicht aufgeführt. @anchor{user-account-password} -@cindex password, for user accounts +@cindex Passwort, für Benutzerkonten @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 @@ -11239,14 +11771,13 @@ 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: +Wenn Sie aber @emph{doch} ein anfängliches Passwort für ein Konto +voreinstellen möchten, muss dieses Feld hier das verschlüsselte Passwort als +Zeichenkette enthalten. Sie können dazu die Prozedur @code{crypt} benutzen. @example (user-account (name "charlie") - (home-directory "/home/charlie") (group "users") ;; Specify a SHA-512-hashed initial password. @@ -11259,9 +11790,10 @@ The hash of this initial password will be available in a file in 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. +Siehe @ref{Passphrase Storage,,, libc, The GNU C Library Reference Manual} +für weitere Informationen über Passwortverschlüsselung und +@ref{Encryption,,, guile, GNU Guile Reference Manual} für Informationen über +die Prozedur @code{crypt} in Guile. @end table @end deftp @@ -11317,29 +11849,162 @@ dazugehört. Es ist ein Sonderfall und wird automatisch erzeugt, egal ob es spezifiziert wurde oder nicht. @end defvr +@node Tastaturbelegung +@section Tastaturbelegung + +@cindex Tastaturbelegung +@cindex Keymap +To specify what each key of your keyboard does, you need to tell the +operating system what @dfn{keyboard layout} you want to use. The default, +when nothing is specified, is the US English QWERTY layout for 105-key PC +keyboards. However, German speakers will usually prefer the German QWERTZ +layout, French speakers will want the AZERTY layout, and so on; hackers +might prefer Dvorak or bépo, and they might even want to further customize +the effect of some of the keys. This section explains how to get that done. + +@cindex Tastaturbelegung, Definition +There are three components that will want to know about your keyboard +layout: + +@itemize +@item +The @emph{bootloader} may want to know what keyboard layout you want to use +(@pxref{Bootloader-Konfiguration, @code{keyboard-layout}}). This is useful +if you want, for instance, to make sure that you can type the passphrase of +your encrypted root partition using the right layout. + +@item +The @emph{operating system kernel}, Linux, will need that so that the +console is properly configured (@pxref{»operating-system«-Referenz, +@code{keyboard-layout}}). + +@item +The @emph{graphical display server}, usually Xorg, also has its own idea of +the keyboard layout (@pxref{X Window, @code{keyboard-layout}}). +@end itemize + +Guix allows you to configure all three separately but, fortunately, it +allows you to share the same keyboard layout for all three components. + +@cindex XKB, Tastaturbelegungen +Keyboard layouts are represented by records created by the +@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following +the X Keyboard extension (XKB), each layout has four attributes: a name +(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), +an optional variant name, an optional keyboard model name, and a possibly +empty list of additional options. In most cases the layout name is all you +care about. Here are a few example: + +@example +;; The German QWERTZ layout. Here we assume a standard +;; "pc105" keyboard model. +(keyboard-layout "de") + +;; The bépo variant of the French layout. +(keyboard-layout "fr" "bepo") + +;; The Catalan layout. +(keyboard-layout "es" "cat") + +;; The Latin American Spanish layout. In addition, the +;; "Caps Lock" key is used as an additional "Ctrl" key, +;; and the "Menu" key is used as a "Compose" key to enter +;; accented letters. +(keyboard-layout "latam" + #:options '("ctrl:nocaps" "compose:menu")) + +;; The Russian layout for a ThinkPad keyboard. +(keyboard-layout "ru" #:model "thinkpad") + +;; The "US international" layout, which is the US layout plus +;; dead keys to enter accented characters. This is for an +;; Apple MacBook keyboard. +(keyboard-layout "us" "intl" #:model "macbook78") +@end example + +See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} +package for a complete list of supported layouts, variants, and models. + +@cindex Tastaturbelegung, Konfiguration +Let's say you want your system to use the Turkish keyboard layout throughout +your system---bootloader, console, and Xorg. Here's what your system +configuration would look like: + +@findex set-xorg-configuration +@lisp +;; Using the Turkish layout for the bootloader, the console, +;; and for Xorg. + +(operating-system + ;; ... + (keyboard-layout (keyboard-layout "tr")) ;for the console + (bootloader (bootloader-configuration + (bootloader grub-efi-bootloader) + (target "/boot/efi") + (keyboard-layout keyboard-layout))) ;for GRUB + (services (cons (set-xorg-configuration + (xorg-configuration ;for Xorg + (keyboard-layout keyboard-layout))) + %desktop-services))) +@end lisp + +In the example above, for GRUB and for Xorg, we just refer to the +@code{keyboard-layout} field defined above, but we could just as well refer +to a different layout. The @code{set-xorg-configuration} procedure +communicates the desired Xorg configuration to the graphical log-in manager, +by default GDM. + +We've discussed how to specify the @emph{default} keyboard layout of your +system when it starts, but you can also adjust it at run time: + +@itemize +@item +If you're using GNOME, its settings panel has a ``Region & Language'' entry +where you can select one or more keyboard layouts. + +@item +Under Xorg, the @command{setxkbmap} command (from the same-named package) +allows you to change the current layout. For example, this is how you would +change the layout to US Dvorak: + +@example +setxkbmap us dvorak +@end example + +@item +The @code{loadkeys} command changes the keyboard layout in effect in the +Linux console. However, note that @code{loadkeys} does @emph{not} use the +XKB keyboard layout categorization described above. The command below loads +the French bépo layout: + +@example +loadkeys fr-bepo +@end example +@end itemize + @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 +und Region auf der Welt fest (siehe @ref{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 +Form @code{@var{Sprache}_@var{Gebiet}.@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}}). +@code{operating-system}-Deklaration verwenden (siehe @ref{»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 +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. @@ -11366,8 +12031,8 @@ 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}). +überschrieben werden durch die Umgebungsvariable @code{LOCPATH} (siehe +@ref{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. @@ -11378,15 +12043,15 @@ 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 +Der Name der Locale. Siehe @ref{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. +Der Name der Quelle der Locale. Typischerweise ist das der Teil +@code{@var{Sprache}_@var{Gebiet}} des Locale-Namens. @item @code{charset} (Vorgabe: @code{"UTF-8"}) -Der »Zeichensatz« oder das »Code set«, d.h. die Kodierung dieser Locale, +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}. @@ -11401,7 +12066,7 @@ 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 +Teil des Namens, der nach dem Punkt steht (siehe @ref{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. @@ -11412,9 +12077,9 @@ Manual}). Zum Beispiel ist @code{uk_UA.utf8} enthalten, dagegen ist etwa @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 +Kompilieren von Locale-Deklarationen verwendet werden sollen (siehe +@ref{»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 @@ -11430,14 +12095,14 @@ meisten, aber nicht alle, Locale-Daten von libc 2.21 lesen (Daten zu 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. +Das »Problem« mit Guix ist, dass Nutzer viel Freiheit genießen: Sie können +wählen, ob und wann sie die Software in ihren Profilen aktualisieren und +benutzen vielleicht eine andere libc-Version als sie der Systemadministrator +benutzt hat, um die systemweiten Locale-Daten zu erstellen. 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, +@var{GUIX_LOCPATH} entsprechend definieren (siehe @ref{locales-and-locpath, @code{GUIX_LOCPATH} und Locale-Pakete}). Trotzdem ist es am besten, wenn die systemweiten Locale-Daten unter @@ -11466,16 +12131,18 @@ für libc 2.21 als auch die aktuelle Version von libc in @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. +@dfn{Systemdienste} und ihrer Konfiguration (siehe @ref{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: +Guix hat eine weit gefasste Definition, was ein »Dienst« ist (siehe +@ref{Dienstkompositionen}), aber viele Dienste sind solche, die von +GNU@tie{}Shepherd verwaltet werden (siehe @ref{Shepherd-Dienste}). Auf +einem laufenden System kann der @command{herd}-Befehl benutzt werden, um +verfügbare Dienste aufzulisten, ihren Status anzuzeigen, sie zu starten und +zu stoppen oder andere angebotene Operationen durchzuführen (siehe @ref{Jump +Start,,, shepherd, The GNU Shepherd Manual}). Zum Beispiel: @example # herd status @@ -11526,6 +12193,7 @@ den Diensten im Kern des Systems (»core services«) * Telefondienste:: Telefoniedienste. * Überwachungsdienste:: Dienste zur Systemüberwachung. * Kerberos-Dienste:: Kerberos-Dienste. +* LDAP-Dienste:: LDAP-Dienste. * Web-Dienste:: Web-Server. * Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt. * DNS-Dienste:: DNS-Daemons. @@ -11549,7 +12217,7 @@ 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 +System vorzufinden erwartet (siehe @ref{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. @@ -11592,7 +12260,7 @@ möchten, können Sie den Wert ändern auf: 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 +(siehe @ref{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 @@ -11618,7 +12286,7 @@ als @var{Name} festlegt. @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{}-Objekt, das unter Anderem die beim Anmelden +@code{}-Objekt, das unter anderem die beim Anmelden angezeigte Mitteilung des Tages (englisch »Message of the Day«) festlegt. @end deffn @@ -11641,7 +12309,7 @@ angelegt wurde. @deffn {Scheme-Prozedur} mingetty-service @var{Konfiguration} Liefert einen Dienst, der mingetty nach den Vorgaben der @var{Konfiguration} -ausführt, einem @code{}-Objekt, das unter Anderem +ausführt, einem @code{}-Objekt, das unter anderem die Konsole (das »tty«) festlegt, auf der mingetty laufen soll. @end deffn @@ -11652,8 +12320,8 @@ 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"}. +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 @@ -11680,7 +12348,7 @@ Welches Mingetty-Paket benutzt werden soll. @deffn {Scheme-Prozedur} agetty-service @var{Konfiguration} Liefert einen Dienst, um agetty entsprechend der @var{Konfiguration} auszuführen, welche ein @code{}-Objekt sein muss, das -unter Anderem festlegt, auf welchem tty es laufen soll. +unter anderem festlegt, auf welchem tty es laufen soll. @end deffn @deftp {Datentyp} agetty-configuration @@ -11692,7 +12360,7 @@ die Handbuchseite @code{agetty(8)} für mehr Informationen. @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 +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. @@ -11704,8 +12372,9 @@ 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. +In beiden Fällen wird agetty nichts an den anderen Einstellungen für +serielle Geräte verändern (Baud-Rate etc.), in der Hoffnung, dass Linux sie +auf die korrekten Werte festgelegt hat. @item @code{baud-rate} (Vorgabe: @code{#f}) Eine Zeichenkette, die aus einer kommagetrennten Liste von einer oder @@ -11725,7 +12394,7 @@ 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 +Steht dies auf @code{#t}, werden die Cflags des Terminals (d.h.@: dessen Steuermodi) nicht zurückgesetzt. @item @code{host} (Vorgabe: @code{#f}) @@ -11749,7 +12418,7 @@ Ist dies auf @code{#t} gesetzt, wird der Inhalt der Datei @file{/etc/issue} @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 +allem anderen gesendet wird. Es kann benutzt werden, um ein Modem zu initialisieren. @item @code{no-clear?} (Vorgabe: @code{#f}) @@ -11877,7 +12546,7 @@ müssen hier als eine Liste von Zeichenketten angegeben werden. Liefert einen Dienst, um @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} entsprechend der @var{Konfiguration} auszuführen. Diese ist ein -@code{}-Objekt, das unter Anderem angibt, auf welchem +@code{}-Objekt, das unter anderem angibt, auf welchem tty es ausgeführt werden soll. @end deffn @@ -11888,7 +12557,7 @@ 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"}. +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 @@ -11916,7 +12585,7 @@ Das Kmscon-Paket, das benutzt werden soll. @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{}-Objekt sein. Siehe @xref{Name Service Switch} für ein Beispiel. +diese muss ein @code{}-Objekt sein. Siehe @ref{Name Service Switch} für ein Beispiel. Der Einfachheit halber bietet der Shepherd-Dienst für nscd die folgenden Aktionen an: @@ -11958,7 +12627,7 @@ Daemon (kurz »nscd«). @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})}. +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 @@ -11989,8 +12658,8 @@ Parametern definiert. 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}). +entsprechende NSS-Datenbank bezeichnet wird (siehe @ref{NSS Basics,,, libc, +The GNU C Library Reference Manual}). @item @code{positive-time-to-live} @itemx @code{negative-time-to-live} (Vorgabe: @code{20}) @@ -12057,21 +12726,21 @@ Die zu benutzende syslog-Konfigurationsdatei. Liefert einen Dienst, der einen syslog-Daemon entsprechend der @var{Konfiguration} ausführt. -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, für weitere +Siehe @ref{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. +@command{guix-daemon} ausführt (siehe @ref{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. +Guix. Siehe @ref{Aufruf des guix-daemon} für weitere Informationen. @table @asis @item @code{guix} (Vorgabe: @var{guix}) @@ -12085,15 +12754,16 @@ 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}). +Ob die unter @code{authorized-keys} aufgelisteten Substitutschlüssel +autorisiert werden sollen — vorgegeben ist, den von +@code{@value{SUBSTITUTE-SERVER}} zu autorisieren (siehe @ref{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}). +Die Liste der Dateien mit autorisierten Schlüsseln, d.h.@: eine Liste von +Zeichenketten als G-Ausdrücke (siehe @ref{Aufruf von guix archive}). Der +vorgegebene Inhalt ist der Schlüssel von @code{@value{SUBSTITUTE-SERVER}} +(siehe @ref{Substitute}). @item @code{use-substitutes?} (Vorgabe: @code{#t}) Ob Substitute benutzt werden sollen. @@ -12259,35 +12929,11 @@ 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 +@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. @@ -12304,7 +12950,7 @@ Repräsentiert die Konfiguration von GPM. @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, +Datei @file{/dev/input/mice} zu lauschen. Siehe @ref{Command Line,,, gpm, gpm manual} für weitere Informationen. @item @code{gpm} (Vorgabe: @code{gpm}) @@ -12315,12 +12961,12 @@ Das GPM-Paket, was benutzt werden soll. @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, +Dies ist der Diensttyp für @command{guix publish} (siehe @ref{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 +archive --generate-key} erzeugtes Schlüsselpaar zum Signieren enthält (siehe +@ref{Aufruf von guix archive}). Falls nicht, wird der Dienst beim Starten fehlschlagen. @end deffn @@ -12349,27 +12995,27 @@ 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. +@ref{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 +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 +soll. Siehe @ref{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. +wie es Prozessoren gibt. Siehe @ref{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. +zwischengespeichert werden dürfen. Siehe @ref{Aufruf von guix publish, +@option{--ttl}} für mehr Informationen. @end table @end deftp @@ -12419,28 +13065,31 @@ Echtzeit-Audio-Systeme verwendet. @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}). +@cindex Planen von Aufträgen +Das Modul @code{(gnu services mcron)} enthält eine Schnittstelle zu +GNU@tie{}mcron, einem Daemon, der gemäß einem vorher festgelegten Zeitplan +Aufträge (sogenannte »Jobs«) ausführt (siehe @ref{Top,,, mcron, +GNU@tie{}mcron}). GNU@tie{}mcron ist ähnlich zum traditionellen +@command{cron}-Daemon aus Unix; der größte Unterschied ist, dass mcron in +Guile Scheme implementiert ist, wodurch einem viel Flexibilität bei der +Spezifikation von Aufträgen und ihren Aktionen offen steht. + +Das folgende Beispiel definiert ein Betriebssystem, das täglich die Befehle +@command{updatedb} (siehe @ref{Invoking updatedb,,, find, Finding Files}) +und @command{guix gc} (siehe @ref{Aufruf von guix gc}) ausführt sowie den +Befehl @command{mkid} im Namen eines »unprivilegierten« Nutzers ohne +besondere Berechtigungen laufen lässt (siehe @ref{mkid invocation,,, +idutils, ID Database Utilities}). Zum Anlegen von Auftragsdefinitionen +benutzt es G-Ausdrücke, die dann an mcron übergeben werden (siehe +@ref{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. + ;; 'updatedb' jeden Tag um 3 Uhr morgens ausführen. Hier schreiben wir + ;; die vom Auftrag durchzuführende Aktion als eine Scheme-Prozedur. #~(job '(next-hour '(3)) (lambda () (execl (string-append #$findutils "/bin/updatedb") @@ -12448,14 +13097,15 @@ job definitions that are passed to mcron (@pxref{G-Ausdrücke}). "--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 + ;; Jeden Tag 5 Minuten nach Mitternacht Müll sammeln gehen. + ;; Die Aktions des Auftrags ist ein Shell-Befehl. + #~(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. + ;; Die Index-Datenbank des Benutzers "charlie" um 12:15 Uhr und + ;; 19:15 Uhr aktualisieren. Dies wird aus seinem Persönlichen + ;; Ordner heraus ausgeführt. #~(job '(next-minute-from (next-hour '(12 19)) '(15)) (string-append #$idutils "/bin/mkid src") #:user "charlie")) @@ -12470,9 +13120,9 @@ job definitions that are passed to mcron (@pxref{G-Ausdrücke}). %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. +Siehe @ref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron} +für weitere Informationen zu mcron-Auftragsspezifikationen. Nun folgt die +Referenz des mcron-Dienstes. On a running system, you can use the @code{schedule} action of the service to visualize the mcron jobs that will be executed next: @@ -13484,7 +14134,7 @@ from accessing Facebook. The @code{(gnu services avahi)} provides the following definition. -@defvr {Scheme Variable} avahi-service-type +@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/}). @@ -13498,20 +14148,20 @@ 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. +@deftp {Datentyp} avahi-configuration +Dieser Datentyp repräsentiert die Konfiguration von Avahi. @table @asis -@item @code{host-name} (default: @code{#f}) +@item @code{host-name} (Vorgabe: @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}) +@item @code{publish?} (Vorgabe: @code{#t}) When true, allow host names and services to be published (broadcast) over the network. -@item @code{publish-workstation?} (default: @code{#t}) +@item @code{publish-workstation?} (Vorgabe: @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: @@ -13520,14 +14170,14 @@ your local network, you can run: avahi-browse _workstation._tcp @end example -@item @code{wide-area?} (default: @code{#f}) +@item @code{wide-area?} (Vorgabe: @code{#f}) When true, DNS-SD over unicast DNS is enabled. -@item @code{ipv4?} (default: @code{#t}) -@itemx @code{ipv6?} (default: @code{#t}) +@item @code{ipv4?} (Vorgabe: @code{#t}) +@itemx @code{ipv6?} (Vorgabe: @code{#t}) These fields determine whether to use IPv4/IPv6 sockets. -@item @code{domains-to-browse} (default: @code{'()}) +@item @code{domains-to-browse} (Vorgabe: @code{'()}) This is a list of domains to browse. @end table @end deftp @@ -13558,7 +14208,13 @@ Package object of the Open vSwitch. 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. +@dfn{login manager}, by default the GNOME Display Manager (GDM). + +@cindex GDM +@cindex GNOME, login manager +GDM of course allows users to log in into window managers and desktop +environments other than GNOME; for those using GNOME, GDM is required for +features such as automatic screen locking. @cindex window manager To use X11, you must install at least one @dfn{window manager}---for example @@ -13566,23 +14222,60 @@ 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. +@defvr {Scheme-Variable} gdm-service-type +This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME +Desktop Manager} (GDM), a program that manages graphical display servers and +handles graphical user logins. Its value must be a @code{gdm-configuration} +(see below.) @cindex session types (X11) @cindex X11 session types -SLiM looks for @dfn{session types} described by the @file{.desktop} files in +GDM 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. +choose a session from the log-in screen. Packages such as @code{gnome}, +@code{xfce}, and @code{i3} 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 {Datentyp} gdm-configuration +@table @asis +@item @code{auto-login?} (default: @code{#f}) +@itemx @code{default-user} (Vorgabe: @code{#f}) +When @code{auto-login?} is false, GDM presents a log-in screen. + +When @code{auto-login?} is true, GDM logs in directly as +@code{default-user}. + +@item @code{gnome-shell-assets} (Vorgabe: …) +List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. + +@item @code{xorg-configuration} (Vorgabe: @code{(xorg-configuration)}) +Xorg-Server für grafische Oberflächen konfigurieren. + +@item @code{xsession} (Vorgabe: @code{(xinitrc)}) +Script to run before starting a X session. + +@item @code{dbus-daemon} (Vorgabe: @code{dbus-daemon-wrapper}) +File name of the @code{dbus-daemon} executable. + +@item @code{gdm} (Vorgabe: @code{gdm}) +Das GDM-Paket, was benutzt werden soll. +@end table +@end deftp + +@defvr {Scheme Variable} slim-service-type +This is the type for the SLiM graphical login manager for X11. + +Like GDM, SLiM looks for session types described by @file{.desktop} files +and allows users to choose a session from the log-in screen using @kbd{F1}. +It also honors @file{~/.xsession} files. +@end defvr + @deftp {Data Type} slim-configuration Data type representing the configuration of @code{slim-service-type}. @@ -13615,8 +14308,8 @@ 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{xorg-configuration} (Vorgabe: @code{(xorg-configuration)}) +Xorg-Server für grafische Oberflächen konfigurieren. @item @code{xauth} (default: @code{xauth}) The XAuth package to use. @@ -13691,8 +14384,8 @@ 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{xorg-configuration} (Vorgabe: @code{(xorg-configuration)}) +Xorg-Server für grafische Oberflächen konfigurieren. @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")}) Path to xauth. @@ -13715,9 +14408,6 @@ 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. @@ -13743,104 +14433,82 @@ type @code{}. @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}. +@cindex Xorg, Konfiguration +@deftp {Datentyp} xorg-configuration +This data type represents the configuration of the Xorg graphical display +server. Note that there is not Xorg service; instead, the X server is +started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the +configuration of these display managers aggregates an +@code{xorg-configuration} record. -Usually the X server is started by a login manager. -@end deffn +@table @asis +@item @code{modules} (Vorgabe: @code{%default-xorg-modules}) +This is a list of @dfn{module packages} loaded by the Xorg server---e.g., +@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. + +@item @code{fonts} (Vorgabe: @code{%default-xorg-fonts}) +This is a list of font directories to add to the server's @dfn{font path}. + +@item @code{drivers} (Vorgabe: @code{'()}) +This 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")}. + +@item @code{resolutions} (Vorgabe: @code{'()}) +When @code{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))}. + +@cindex Tastaturbelegung, für Xorg +@cindex keymap, for Xorg +@item @code{keyboard-layout} (Vorgabe: @code{#f}) +If this is @code{#f}, Xorg uses the default keyboard layout---usually US +English (``qwerty'') for a 105-key PC keyboard. + +Otherwise this must be a @code{keyboard-layout} object specifying the +keyboard layout in use when Xorg is running. @xref{Tastaturbelegung}, for +more information on how to specify the keyboard layout. + +@item @code{extra-config} (Vorgabe: @code{'()}) +This 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. + +@item @code{server} (Vorgabe: @code{xorg-server}) +This is the package providing the Xorg server. + +@item @code{server-arguments} (Vorgabe: @code{%default-xorg-server-arguments}) +This is the list of command-line arguments to pass to the X server. The +default is @code{-nolisten tcp}. +@end table +@end deftp -@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: +@deffn {Scheme-Prozedur} set-xorg-configuration @var{Konfiguration} @ + [@var{login-manager-service-type}] Tell the log-in manager (of type +@var{login-manager-service-type}) to use @var{config}, an + record. -@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 +Since the Xorg configuration is embedded in the log-in manager's +configuration---e.g., @code{gdm-configuration}---this procedure provides a +shorthand to set the Xorg configuration. +@end deffn -@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. +@deffn {Scheme-Prozedur} xorg-start-command [@var{Konfiguration}] +Return a @code{startx} script in which the modules, fonts, etc. specified in +@var{config}, are available. The result should be used in place of +@code{startx}. -@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}. +Usually the X server is started by a login manager. +@end deffn -@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))}. +@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: -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 +@lisp +(screen-locker-service xlockmore "xlock") +@end lisp makes the good ol' XlockMore usable. @end deffn @@ -13850,9 +14518,10 @@ makes the good ol' XlockMore usable. @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: +Das Modul @code{(gnu services cups)} stellt eine Guix-Dienstdefinition für +den CUPS-Druckdienst zur Verfügung. Wenn Sie Druckerunterstützung zu einem +Guix-System hinzufügen möchten, dann fügen Sie einen +@code{cups-service}-Dienst in die Betriebssystemdefinition ein. @deffn {Scheme Variable} cups-service-type The service type for the CUPS print server. Its value should be a valid @@ -14683,7 +15352,7 @@ 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. +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 @@ -14694,7 +15363,7 @@ 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 +@code{gdm-service-type}}), 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 @@ -14707,19 +15376,19 @@ name service switch service configured to be able to use @code{nss-mdns} 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, +Additionally, the @code{gnome-desktop-service-type}, +@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 +Additionally, adding a service made by @code{gnome-desktop-service-type} +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 @@ -14732,44 +15401,69 @@ 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 +to use the @code{sddm-service} instead of GDM as 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. + +@defvr {Scheme-Variable} gnome-desktop-service-type +Dies ist der Typ des Dienstes, der die @uref{https://www.gnome.org, +GNOME}-Arbeitsumgebung bereitstellt. Sein Wert ist ein +@code{gnome-desktop-configuration}-Objekt (siehe unten). + +This service adds the @code{gnome} package to the system profile, and +extends polkit with the actions from @code{gnome-settings-daemon}. +@end defvr -@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 +@deftp {Datentyp} gnome-desktop-configuration +Configuration record for the GNOME desktop environment. + +@table @asis +@item @code{gnome} (Vorgabe: @code{gnome}) +Welches GNOME-Paket benutzt werden soll. +@end table +@end deftp + +@defvr {Scheme-Variable} xfce-desktop-service-type +Der Typ des Dienstes, um die @uref{Xfce, https://xfce.org/}-Arbeitsumgebung +auszuführen. Sein Wert ist ein @code{xfce-desktop-configuration}-Objekt +(siehe unten). + +This 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 +@end defvr + +@deftp {Datentyp} xfce-desktop-configuration +Verbundstyp für Einstellungen zur Xfce-Arbeitsumgebung. + +@table @asis +@item @code{xfce} (Vorgabe: @code{xfce}) +Das Xfce-Paket, was benutzt werden soll. +@end table +@end deftp -@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.) +@deffn {Scheme-Variable} mate-desktop-service-type +Dies ist der Typ des Dienstes, um die @uref{https://mate-desktop.org/, +MATE-Arbeitsumgebung} auszuführen. Sein Wert ist ein +@code{mate-desktop-configuration}-Objekt (siehe unten). 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. +@deftp {Datentyp} mate-desktop-configuration +Verbundstyp für die Einstellungen der MATE-Arbeitsumgebung. @table @asis -@item @code{mate} (default @code{mate}) -The MATE package to use. +@item @code{mate} (Vorgabe: @code{mate}) +Das MATE-Paket, was benutzt werden soll. @end table @end deftp -@deffn {Scheme Variable} enlightenment-desktop-service-type +@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 @@ -14781,9 +15475,9 @@ Das Enlightenment-Paket, was benutzt werden soll. @end table @end deftp -Because the GNOME, XFCE and MATE desktop services pull in so many packages, +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 +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}: @@ -14793,8 +15487,8 @@ default. To add GNOME, XFCE or MATE, just @code{cons} them onto (operating-system ... ;; cons* adds items to the list given as its last argument. - (services (cons* (gnome-desktop-service) - (xfce-desktop-service) + (services (cons* (service gnome-desktop-service-type) + (service xfce-desktop-service) %desktop-services)) ...) @end example @@ -14914,7 +15608,7 @@ granted the capability to suspend the system if the user is logged in locally. @end deffn -@defvr {Scheme Variable} upower-service-type +@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. @@ -14923,52 +15617,52 @@ 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. +@deftp {Datentyp} upower-configuration +Repräsentiert die Konfiguration von UPower. @table @asis -@item @code{upower} (default: @var{upower}) +@item @code{upower} (Vorgabe: @var{upower}) Package to use for @code{upower}. -@item @code{watts-up-pro?} (default: @code{#f}) +@item @code{watts-up-pro?} (Vorgabe: @code{#f}) Enable the Watts Up Pro device. -@item @code{poll-batteries?} (default: @code{#t}) +@item @code{poll-batteries?} (Vorgabe: @code{#t}) Enable polling the kernel for battery level changes. -@item @code{ignore-lid?} (default: @code{#f}) +@item @code{ignore-lid?} (Vorgabe: @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}) +@item @code{use-percentage-for-policy?} (Vorgabe: @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}) +@item @code{percentage-low} (Vorgabe: @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}) +@item @code{percentage-critical} (Vorgabe: @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}) +@item @code{percentage-action} (Vorgabe: @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}) +@item @code{time-low} (Vorgabe: @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}) +@item @code{time-critical} (Vorgabe: @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}) +@item @code{time-action} (Vorgabe: @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}) +@item @code{critical-power-action} (Vorgabe: @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?}). @@ -15156,9 +15850,9 @@ extension, a user can configure the postgresql-service as in this example: (use-package-modules databases geo) (operating-system - ... - ;; postgresql is required to run `psql' but postgis is not required for - ;; proper operation. + … + ;; postgresql wird benötigt, um »psql« auszuführen, aber postgis ist + ;; für den Betrieb nicht unbedingt notwendig. (packages (cons* postgresql %base-packages)) (services (cons* @@ -16642,6 +17336,36 @@ above example, there doesn't need to be a @code{postmaster} entry in the @code{postmaster} mail to @code{bob} (which subsequently would deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). +@subsubheading GNU Mailutils IMAP4 Daemon +@cindex GNU Mailutils IMAP4 Daemon + +@deffn {Scheme-Variable} imap4d-service-type +This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, +mailutils, GNU Mailutils Manual}), whose value should be an +@code{imap4d-configuration} object as in this example: + +@example +(service imap4d-service-type + (imap4d-configuration + (config-file (local-file "imap4d.conf")))) +@end example +@end deffn + +@deftp {Datentyp} imap4d-configuration +Datentyp, der die Konfiguration von @command{imap4d} repräsentiert. + +@table @asis +@item @code{package} (Vorgabe: @code{mailutils}) +The package that provides @command{imap4d}. + +@item @code{config-file} (Vorgabe: @code{%default-imap4d-config-file}) +File-like object of the configuration file to use, by default it will listen +on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU +Mailutils Manual}, for details. + +@end table +@end deftp + @node Kurznachrichtendienste @subsection Kurznachrichtendienste @@ -16899,8 +17623,8 @@ information about using the hashed backend. See also @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"}. +the Prosody service. See @url{https://prosody.im/doc/logging}. Defaults to +@samp{"*syslog"}. @end deftypevr @deftypevr {@code{prosody-configuration} parameter} file-name pidfile @@ -17123,30 +17847,30 @@ Configuration snippet added as-is to the BitlBee configuration file. @end table @end deftp -@subsubheading Quassel Service +@subsubheading Quassel-Dienst @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 +@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 +@deftp {Datentyp} 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{quassel} (Vorgabe: @code{quassel}) +Das zu verwendende Quassel-Paket. -@item @code{interface} (default: @code{"::,0.0.0.0"}) -@item @code{port} (default: @code{4242}) +@item @code{interface} (Vorgabe: @code{"::,0.0.0.0"}) +@item @code{port} (Vorgabe: @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"}) +@item @code{loglevel} (Vorgabe: @code{"Info"}) The level of logging desired. Accepted values are Debug, Info, Warning and Error. @end table @@ -17544,7 +18268,7 @@ Bind the web interface to the specified address. @end table @end deftp -@subsubheading Zabbix server +@subsubheading Zabbix-Server @cindex zabbix zabbix-server Zabbix provides monitoring metrics, among others network utilization, CPU load and disk space consumption: @@ -17565,7 +18289,7 @@ load and disk space consumption: Available @code{zabbix-server-configuration} fields are: @deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server -The zabbix-server package. +Das zabbix-server-Paket. @end deftypevr @@ -17584,21 +18308,21 @@ Defaults to @samp{"zabbix"}. @end deftypevr @deftypevr {@code{zabbix-server-configuration} parameter} string db-host -Database host name. +Rechnername der Datenbank. Defaults to @samp{"127.0.0.1"}. @end deftypevr @deftypevr {@code{zabbix-server-configuration} parameter} string db-name -Database name. +Datenbankname. Defaults to @samp{"zabbix"}. @end deftypevr @deftypevr {@code{zabbix-server-configuration} parameter} string db-user -Database user. +Benutzerkonto der Datenbank. Defaults to @samp{"zabbix"}. @@ -17613,7 +18337,7 @@ Defaults to @samp{""}. @end deftypevr @deftypevr {@code{zabbix-server-configuration} parameter} number db-port -Database port. +Datenbank-Portnummer. Defaults to @samp{5432}. @@ -17646,7 +18370,7 @@ Defaults to @samp{"/var/log/zabbix/server.log"}. @end deftypevr @deftypevr {@code{zabbix-server-configuration} parameter} string pid-file -Name of PID file. +Name der PID-Datei. Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}. @@ -17694,7 +18418,7 @@ Zabbix agent gathers information for Zabbix server. Available @code{zabbix-agent-configuration} fields are: @deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent -The zabbix-agent package. +Das zabbix-agent-Paket. @end deftypevr @@ -17747,7 +18471,7 @@ Defaults to @samp{"/var/log/zabbix/agent.log"}. @end deftypevr @deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file -Name of PID file. +Name der PID-Datei. Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}. @@ -17803,28 +18527,28 @@ NGINX configuration. @end deftypevr @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host -Database host name. +Rechnername der Datenbank. Defaults to @samp{"localhost"}. @end deftypevr @deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port -Database port. +Datenbank-Portnummer. Defaults to @samp{5432}. @end deftypevr @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name -Database name. +Datenbankname. Defaults to @samp{"zabbix"}. @end deftypevr @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user -Database user. +Benutzerkonto der Datenbank. Defaults to @samp{"zabbix"}. @@ -17985,23 +18709,497 @@ authenticate. @end deftp +@node LDAP-Dienste +@subsection LDAP-Dienste +@cindex LDAP +@cindex nslcd, LDAP service + +The @code{(gnu services authentication)} module provides the +@code{nslcd-service-type}, which can be used to authenticate against an LDAP +server. In addition to configuring the service itself, you may want to add +@code{ldap} as a name service to the Name Service Switch. @xref{Name Service Switch} for detailed information. + +Here is a simple operating system declaration with a default configuration +of the @code{nslcd-service-type} and a Name Service Switch configuration +that consults the @code{ldap} name service last: + +@example +(use-service-modules authentication) +(use-modules (gnu system nss)) +... +(operating-system + ... + (services + (cons* + (service nslcd-service-type) + (service dhcp-client-service-type) + %base-services)) + (name-service-switch + (let ((services (list (name-service (name "db")) + (name-service (name "files")) + (name-service (name "ldap"))))) + (name-service-switch + (inherit %mdns-host-lookup-nss) + (password services) + (shadow services) + (group services) + (netgroup services) + (gshadow services))))) +@end example + +@c %start of generated documentation for nslcd-configuration + +Available @code{nslcd-configuration} fields are: + +@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd +Das @code{nss-pam-ldapd}-Paket, was benutzt werden soll. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads +The number of threads to start that can handle requests and perform LDAP +queries. Each thread opens a separate connection to the LDAP server. The +default is to start 5 threads. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string uid +This specifies the user id with which the daemon should be run. + +Defaults to @samp{"nslcd"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string gid +This specifies the group id with which the daemon should be run. + +Defaults to @samp{"nslcd"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} log-option log +This option controls the way logging is done via a list containing SCHEME +and LEVEL. The SCHEME argument may either be the symbols "none" or +"syslog", or an absolute file name. The LEVEL argument is optional and +specifies the log level. The log level may be one of the following symbols: +"crit", "error", "warning", "notice", "info" or "debug". All messages with +the specified log level or higher are logged. + +Defaults to @samp{("/var/log/nslcd" info)}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list uri +The list of LDAP server URIs. Normally, only the first server will be used +with the following servers as fall-back. + +Defaults to @samp{("ldap://localhost:389/")}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version +The version of the LDAP protocol to use. The default is to use the maximum +version supported by the LDAP library. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn +Specifies the distinguished name with which to bind to the directory server +for lookups. The default is to bind anonymously. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw +Specifies the credentials with which to bind. This option is only +applicable when used with binddn. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn +Specifies the distinguished name to use when the root user tries to modify a +user's password using the PAM module. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw +Specifies the credentials with which to bind if the root user tries to +change a user's password. This option is only applicable when used with +rootpwmoddn + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech +Specifies the SASL mechanism to be used when performing SASL authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm +Specifies the SASL realm to be used when performing SASL authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid +Specifies the authentication identity to be used when performing SASL +authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid +Specifies the authorization identity to be used when performing SASL +authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? +Determines whether the LDAP server host name should be canonicalised. If +this is enabled the LDAP library will do a reverse host name lookup. By +default, it is left up to the LDAP library whether this check is performed +or not. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname +Set the name for the GSS-API Kerberos credentials cache. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string base +Basis für die Verzeichnissuche. + +Vorgegeben ist @samp{"dc=example,dc=com"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} scope-option scope +Specifies the search scope (subtree, onelevel, base or children). The +default scope is subtree; base scope is almost never useful for name service +lookups; children scope is not supported on all servers. + +Defaults to @samp{(subtree)}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref +Specifies the policy for dereferencing aliases. The default policy is to +never dereference aliases. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals +Specifies whether automatic referral chasing should be enabled. The default +behaviour is to chase referrals. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps +This option allows for custom attributes to be looked up instead of the +default RFC 2307 attributes. It is a list of maps, each consisting of the +name of a map, the RFC 2307 attribute to match and the query expression for +the attribute as it is available in the directory. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters +A list of filters consisting of the name of a map to which the filter +applies and an LDAP search filter expression. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit +Specifies the time limit in seconds to use when connecting to the directory +server. The default value is 10 seconds. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit +Specifies the time limit (in seconds) to wait for a response from the LDAP +server. A value of zero, which is the default, is to wait indefinitely for +searches to be completed. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit +Specifies the period if inactivity (in seconds) after which the con‐ nection +to the LDAP server will be closed. The default is not to time out +connections. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime +Specifies the number of seconds to sleep when connecting to all LDAP servers +fails. By default one second is waited between the first failure and the +first retry. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime +Specifies the time after which the LDAP server is considered to be +permanently unavailable. Once this time is reached retries will be done +only once per this time period. The default value is 10 seconds. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl +Specifies whether to use SSL/TLS or not (the default is not to). If +'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert +Specifies what checks to perform on a server-supplied certificate. The +meaning of the values is described in the ldap.conf(5) manual page. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir +Specifies the directory containing X.509 certificates for peer authen‐ +tication. This parameter is ignored when using GnuTLS. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile +Specifies the path to the X.509 certificate for peer authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile +Specifies the path to an entropy source. This parameter is ignored when +using GnuTLS. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers +Specifies the ciphers to use for TLS as a string. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert +Specifies the path to the file containing the local certificate for client +TLS authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key +Specifies the path to the file containing the private key for client TLS +authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize +Set this to a number greater than 0 to request paged results from the LDAP +server in accordance with RFC2696. The default (0) is to not request paged +results. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers +This option prevents group membership lookups through LDAP for the specified +users. Alternatively, the value 'all-local may be used. With that value +nslcd builds a full list of non-LDAP users on startup. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid +This option ensures that LDAP users with a numeric user id lower than the +specified value are ignored. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset +This option specifies an offset that is added to all LDAP numeric user ids. +This can be used to avoid user id collisions with local users. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset +This option specifies an offset that is added to all LDAP numeric group +ids. This can be used to avoid user id collisions with local groups. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups +If this option is set, the member attribute of a group may point to another +group. Members of nested groups are also returned in the higher level group +and parent groups are returned when finding groups for a specific user. The +default is not to perform extra searches for nested groups. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers +If this option is set, the group member list is not retrieved when looking +up groups. Lookups for finding which groups a user belongs to will remain +functional so the user will likely still get the correct groups assigned on +login. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration +If this option is set, functions which cause all user/group entries to be +loaded from the directory will not succeed in doing so. This can +dramatically reduce LDAP server load in situations where there are a great +number of users and/or groups. This option is not recommended for most +configurations. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames +This option can be used to specify how user and group names are verified +within the system. This pattern is used to check all user and group names +that are requested and returned from LDAP. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase +This specifies whether or not to perform searches using case-insensitive +matching. Enabling this could open up the system to authorization bypass +vulnerabilities and introduce nscd cache poisoning vulnerabilities which +allow denial of service. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy +This option specifies whether password policy controls are requested and +handled from the LDAP server when performing user authentication. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search +By default nslcd performs an LDAP search with the user's credentials after +BIND (authentication) to ensure that the BIND operation was successful. The +default search is a simple check to see if the user's DN exists. A search +filter can be specified that will be used instead. It should return at +least one entry. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search +This option allows flexible fine tuning of the authorisation check that +should be performed. The search filter specified is executed and if any +entries match, access is granted, otherwise access is denied. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message +If this option is set password modification using pam_ldap will be denied +and the specified message will be presented to the user instead. The +message can be used to direct the user to an alternative means of changing +their password. + +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list pam-services +List of pam service names for which LDAP authentication should suffice. + +Defaults to @samp{()}. + +@end deftypevr + +@c %end of generated documentation for nslcd-configuration + + @node Web-Dienste @subsection Web-Dienste -@cindex web -@cindex www +@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. +Das Modul @code{(gnu services web)} stellt den Apache-HTTP-Server, den +nginx-Webserver und auch einen fastcgi-Wrapperdienst bereit. -@subsubheading Apache HTTP Server +@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. +@deffn {Scheme-Variable} httpd-service-type +Diensttyp für den @uref{https://httpd.apache.org/,Apache-HTTP-Server} +(@dfn{httpd}). Der Wert dieses Diensttyps ist ein +@code{httpd-configuration}-Verbund. -A simple example configuration is given below. +Es folgt ein einfaches Beispiel der Konfiguration. @example (service httpd-service-type @@ -18012,8 +19210,8 @@ A simple example configuration is given below. (document-root "/srv/http/www.example.com"))))) @end example -Other services can also extend the @code{httpd-service-type} to add to the -configuration. +Andere Dienste können den @code{httpd-service-type} auch erweitern, um etwas +zur Konfiguration hinzuzufügen. @example (simple-service 'my-extra-server httpd-service-type @@ -18026,58 +19224,61 @@ configuration. @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. +Nun folgt eine Beschreibung der Verbundstypen @code{httpd-configuration}, +@code{httpd-module}, @code{httpd-config-file} und @code{httpd-virtualhost}. -@deffn {Data Type} httpd-configuration -This data type represents the configuration for the httpd service. +@deffn {Datentyp} httpd-configuration +Dieser Datentyp repräsentiert die Konfiguration des httpd-Dienstes. @table @asis -@item @code{package} (default: @code{httpd}) -The httpd package to use. +@item @code{package} (Vorgabe: @code{httpd}) +Das zu benutzende httpd-Paket. -@item @code{pid-file} (default: @code{"/var/run/httpd"}) -The pid file used by the shepherd-service. +@item @code{pid-file} (Vorgabe: @code{"/var/run/httpd"}) +Die vom Shepherd-Dienst benutzte PID-Datei. -@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. +@item @code{config} (Vorgabe: @code{(httpd-config-file)}) +Die vom httpd-Dienst zu benutzende Konfigurationsdatei. Vorgegeben ist ein +@code{httpd-config-file}-Verbundsobjekt, aber als Wert kann auch ein anderer +G-Ausdruck benutzt werden, der eine Datei erzeugt, zum Beispiel ein +@code{plain-file}. Es kann auch eine Datei außerhalb des Stores mit einer +Zeichenkette angegeben werden. @end table @end deffn -@deffn {Data Type} httpd-module -This data type represents a module for the httpd service. +@deffn {Datentyp} httpd-module +Dieser Datentyp steht für ein Modul des httpd-Dienstes. @table @asis @item @code{name} -The name of the module. +Der Name des Moduls. @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")}. +Die Datei, in der das Modul steht. Sie kann relativ zum benutzten +httpd-Paket oder als absoluter Pfad einer Datei oder als ein G-Ausdruck für +eine Datei im Store angegeben werden, zum Beispiel @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. +@defvr {Scheme-Variable} %default-httpd-modules +Eine vorgegebene Liste von @code{httpd-module}-Objekten. @end defvr -@deffn {Data Type} httpd-config-file -This data type represents a configuration file for the httpd service. +@deffn {Datentyp} httpd-config-file +Dieser Datentyp repräsentiert eine Konfigurationsdatei für den httpd-Dienst. @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. +@item @code{modules} (Vorgabe: @code{%default-httpd-modules}) +Welche Module geladen werden sollen. Zusätzliche Module können hier +eingetragen werden oder durch eine zusätzliche Konfigurationsangabe geladen +werden. -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}: +Um zum Beispiel Anfragen nach PHP-Dateien zu behandeln, können Sie das Modul +@code{mod_proxy_fcgi} von Apache zusammen mit @code{php-fpm-service-type} +benutzen: @example (service httpd-service-type @@ -18102,54 +19303,64 @@ For example, in order to handle requests for PHP files, you can use Apache’s (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-root} (Vorgabe: @code{httpd}) +Die @code{ServerRoot} in der Konfigurationsdatei, vorgegeben ist das +httpd-Paket. Direktiven wie @code{Include} und @code{LoadModule} werden +relativ zur ServerRoot interpretiert. -@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. +@item @code{server-name} (Vorgabe: @code{#f}) +Der @code{ServerName} in der Konfigurationsdatei, mit dem das Anfrageschema +(Request Scheme), der Rechnername (Hostname) und Port angegeben wird, mit +denen sich der Server identifiziert. -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}. +Es muss nicht als Teil der Server-Konfiguration festgelegt werden, sondern +kann auch in virtuellen Rechnern (Virtual Hosts) festgelegt +werden. Vorgegeben ist @code{#f}, wodurch kein @code{ServerName} festgelegt +wird. -@item @code{document-root} (default: @code{"/srv/http"}) -The @code{DocumentRoot} from which files will be served. +@item @code{document-root} (Vorgabe: @code{"/srv/http"}) +Das @code{DocumentRoot}-Verzeichnis, in dem sich die Dateien befinden, die +man vom Server abrufen kann. -@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{listen} (Vorgabe: @code{'("80")}) +Die Liste der Werte für die @code{Listen}-Direktive in der +Konfigurationsdatei. Als Wert sollte eine Liste von Zeichenketten angegeben +werden, die jeweils die Portnummer, auf der gelauscht wird, und optional +auch die zu benutzende IP-Adresse und das Protokoll angeben. -@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{pid-file} (Vorgabe: @code{"/var/run/httpd"}) +Hiermit wird die PID-Datei als @code{PidFile}-Direktive angegeben. Der Wert +sollte mit der @code{pid-file}-Datei in der @code{httpd-configuration} +übereinstimmen, damit der Shepherd-Dienst richtig konfiguriert ist. -@item @code{error-log} (default: @code{"/var/log/httpd/error_log"}) -The @code{ErrorLog} to which the server will log errors. +@item @code{error-log} (Vorgabe: @code{"/var/log/httpd/error_log"}) +Der Ort, an den der Server mit der @code{ErrorLog}-Direktive +Fehlerprotokolle schreibt. -@item @code{user} (default: @code{"httpd"}) -The @code{User} which the server will answer requests as. +@item @code{user} (Vorgabe: @code{"httpd"}) +Der Benutzer, als der der Server durch die @code{User}-Direktive Anfragen +beantwortet. -@item @code{group} (default: @code{"httpd"}) -The @code{Group} which the server will answer requests as. +@item @code{group} (Vorgabe: @code{"httpd"}) +Die Gruppe, mit der der Server durch die @code{Group}-Direktive Anfragen +beantwortet. -@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. +@item @code{extra-config} (Vorgabe: @code{(list "TypesConfig etc/httpd/mime.types")}) +Eine flache Liste von Zeichenketten und G-Ausdrücken, die am Ende der +Konfigurationsdatei hinzugefügt werden. -Any values which the service is extended with will be appended to this list. +Alle Werte, mit denen dieser Dienst erweitert wird, werden an die Liste +angehängt. @end table @end deffn -@deffn {Data Type} httpd-virtualhost -This data type represents a virtualhost configuration block for the httpd -service. +@deffn {Datentyp} httpd-virtualhost +Dieser Datentyp repräsentiert einen Konfigurationsblock für einen virtuellen +Rechner (Virtual Host) des httpd-Dienstes. -These should be added to the extra-config for the httpd-service. +Sie sollten zur zusätzlichen Konfiguration extra-config des httpd-Dienstes +hinzugefügt werden. @example (simple-service 'my-extra-server httpd-service-type @@ -18163,22 +19374,22 @@ These should be added to the extra-config for the httpd-service. @table @asis @item @code{addresses-and-ports} -The addresses and ports for the @code{VirtualHost} directive. +Adressen und Ports für die @code{VirtualHost}-Direktive. @item @code{contents} -The contents of the @code{VirtualHost} directive, this should be a list of -strings and G-expressions. +Der Inhalt der @code{VirtualHost}-Direktive. Er sollte als Liste von +Zeichenketten und G-Ausdrücken angegeben werden. @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{} record. +@deffn {Scheme-Variable} nginx-service-type +Diensttyp für den @uref{https://nginx.org/,NGinx}-Webserver. Der Wert des +Dienstes ist ein @code{}-Verbundsobjekt. -A simple example configuration is given below. +Es folgt ein einfaches Beispiel der Konfiguration. @example (service nginx-service-type @@ -18189,9 +19400,9 @@ A simple example configuration is given below. (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: +Außer durch direktes Hinzufügen von Server-Blöcken zur Dienstkonfiguration +kann der Dienst auch durch andere Dienste erweitert werden, um Server-Blöcke +hinzuzufügen, wie man im folgenden Beispiel sieht: @example (simple-service 'my-extra-server nginx-service-type @@ -18201,37 +19412,42 @@ this example: @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. +Beim Starten hat @command{nginx} seine Konfigurationsdatei noch nicht +gelesen und benutzt eine vorgegebene Datei, um Fehlermeldungen zu +protokollieren. Wenn er seine Konfigurationsdatei nicht laden kann, landen +Fehlermeldungen also dort. Nachdem die Konfigurationsdatei geladen ist, +werden Fehlerprotokolle nach Voreinstellung in die Datei geschrieben, die in +der Konfiguration angegeben ist. In unserem Fall können Sie Fehlermeldungen +beim Starten in @file{/var/run/nginx/logs/error.log} finden und nachdem die +Konfiguration eingelesen wurde, finden Sie sie in +@file{/var/log/nginx/error.log}. Letzterer Ort kann mit der +Konfigurationsoption @var{log-directory} geändert werden. + +@deffn {Datentyp} nginx-configuration +Dieser Datentyp repräsentiert die Konfiguration von NGinx. Ein Teil der +Konfiguration kann hierüber und über die anderen zu Ihrer Verfügung +stehenden Verbundstypen geschehen, alternativ können Sie eine +Konfigurationsdatei mitgeben. @table @asis -@item @code{nginx} (default: @code{nginx}) -The nginx package to use. +@item @code{nginx} (Vorgabe: @code{nginx}) +Das zu benutzende nginx-Paket. -@item @code{log-directory} (default: @code{"/var/log/nginx"}) -The directory to which NGinx will write log files. +@item @code{log-directory} (Vorgabe: @code{"/var/log/nginx"}) +In welches Verzeichnis NGinx Protokolldateien schreiben wird. -@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{run-directory} (Vorgabe: @code{"/var/run/nginx"}) +In welchem Verzeichnis NGinx eine PID-Datei anlegen und temporäre Dateien +ablegen wird. -@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{}. +@item @code{server-blocks} (Vorgabe: @code{'()}) +Eine Liste von @dfn{Server-Blöcken}, die in der erzeugten +Konfigurationsdatei stehen sollen. Die Elemente davon sollten den Typ +@code{} haben. -The following example would setup NGinx to serve @code{www.example.com} from -the @code{/srv/http/www.example.com} directory, without using HTTPS. +Im folgenden Beispiel wäre NGinx so eingerichtet, dass Anfragen an +@code{www.example.com} mit Dateien aus dem Verzeichnis +@code{/srv/http/www.example.com} beantwortet werden, ohne HTTPS zu benutzen. @example (service nginx-service-type (nginx-configuration @@ -18241,15 +19457,17 @@ the @code{/srv/http/www.example.com} directory, without using HTTPS. (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{}. +@item @code{upstream-blocks} (Vorgabe: @code{'()}) +Eine Liste von @dfn{Upstream-Blöcken}, die in der erzeugten +Konfigurationsdatei stehen sollen. Ihre Elemente sollten den Typ +@code{} haben. -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{} -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. +Upstreams als @code{upstream-blocks} zu konfigurieren, kann hilfreich sein, +wenn es mit @code{locations} in @code{} +verbunden wird. Das folgende Beispiel erzeugt eine Server-Konfiguration mit +einer Location-Konfiguration, bei der Anfragen als Proxy entsprechend einer +Upstream-Konfiguration weitergeleitet werden, wodurch zwei Server diese +beantworten können. @example (service @@ -18272,133 +19490,146 @@ configuration, which will handle requests with two servers. @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. +Wenn eine Konfigurationsdatei als @var{file} angegeben wird, dann wird diese +benutzt und @emph{keine} Konfigurationsdatei anhand der angegebenen +@code{log-directory}, @code{run-directory}, @code{server-blocks} und +@code{upstream-blocks} erzeugt. Trotzdem sollten diese Argumente bei einer +richtigen Konfiguration mit denen in der Datei @var{file} übereinstimmen, +damit die Verzeichnisse bei Aktivierung des Dienstes erzeugt werden. + +Das kann nützlich sein, wenn Sie schon eine bestehende Konfigurationsdatei +haben oder das, was Sie brauchen, nicht mit anderen Teilen eines +nginx-configuration-Verbundsobjekts umgesetzt werden kann. + +@item @code{server-names-hash-bucket-size} (Vorgabe: @code{#f}) +Größe der Behälter (englisch »Buckets«) für die Hashtabelle der Servernamen; +vorgegeben ist @code{#f}, wodurch die Größe der Cache-Lines des Prozessors +verwendet wird. -@item @code{server-names-hash-bucket-max-size} (default: @code{#f}) -Maximum bucket size for the server names hash tables. +@item @code{server-names-hash-bucket-max-size} (Vorgabe: @code{#f}) +Maximale Behältergröße für die Hashtabelle der Servernamen. @item @code{extra-content} (Vorgabe: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. +Zusätzlicher Inhalt des @code{http}-Blocks. Er sollte eine Zeichenkette oder +ein zeichenkettenwertiger G-Ausdruck. @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: +@deftp {Datentyp} nginx-server-configuration +Der Datentyp, der die Konfiguration eines nginx-Serverblocks +repräsentiert. Dieser Typ hat die folgenden Parameter: @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: +@item @code{listen} (Vorgabe: @code{'("80" "443 ssl")}) +Jede @code{listen}-Direktive legt Adresse und Port für eine IP fest oder +gibt einen Unix-Socket an, auf dem der Server Anfragen beantwortet. Es +können entweder sowohl Adresse als auch Port oder nur die Adresse oder nur +der Port angegeben werden. Als Adresse kann auch ein Rechnername +(»Hostname«) angegeben werden, zum Beispiel: @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{server-name} (Vorgabe: @code{(list 'default)}) +Eine Liste von Servernamen, die dieser Server repräsentiert. @code{'default} +repräsentiert den voreingestellten Server, der für Verbindungen verwendet +wird, die zu keinem anderen Server passen. -@item @code{root} (default: @code{"/srv/http"}) -Root of the website nginx will serve. +@item @code{root} (Vorgabe: @code{"/srv/http"}) +Wurzelverzeichnis der Webpräsenz, die über nginx abgerufen werden kann. -@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{locations} (Vorgabe: @code{'()}) +Eine Liste von @dfn{nginx-location-configuration}- oder +@dfn{nginx-named-location-configuration}-Verbundsobjekten, die innerhalb des +Serverblocks benutzt werden. -@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{index} (Vorgabe: @code{(list "index.html")}) +Index-Dateien, mit denen Anfragen nach einem Verzeichnis beantwortet +werden. Wenn @emph{keine} davon gefunden wird, antwortet Nginx mit der Liste +der Dateien im Verzeichnis. -@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{try-files} (Vorgabe: @code{'()}) +Eine Liste der Dateien, bei denen in der angegebenen Reihenfolge geprüft +wird, ob sie existieren. @code{nginx} beantwortet die Anfrage mit der ersten +Datei, die es findet. -@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} (Vorgabe: @code{#f}) +Wo das Zertifikat für sichere Verbindungen gespeichert ist. Sie sollten es +auf @code{#f} setzen, wenn Sie kein Zertifikat haben oder kein HTTPS +benutzen möchten. -@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{ssl-certificate-key} (Vorgabe: @code{#f}) +Wo der private Schlüssel für sichere Verbindungen gespeichert ist. Sie +sollten ihn auf @code{#f} setzen, wenn Sie keinen Schlüssel haben oder kein +HTTPS benutzen möchten. -@item @code{server-tokens?} (default: @code{#f}) -Whether the server should add its configuration to response. +@item @code{server-tokens?} (Vorgabe: @code{#f}) +Ob der Server Informationen über seine Konfiguration bei Antworten beilegen +soll. -@item @code{raw-content} (default: @code{'()}) -A list of raw lines added to the server block. +@item @code{raw-content} (Vorgabe: @code{'()}) +Eine Liste von Zeilen, die unverändert in den Serverblock eingefügt werden. @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: +@deftp {Datentyp} nginx-upstream-configuration +Der Datentyp, der die Konfiguration eines nginx-@code{upstream}-Blocks +repräsentiert. Dieser Typ hat folgende Parameter: @table @asis @item @code{name} -Name for this group of servers. +Der Name dieser Servergruppe. @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. +Gibt die Adressen der Server in der Gruppe an. Die Adresse kann als +IP-Adresse (z.B.@: @samp{127.0.0.1}), Domänenname (z.B.@: +@samp{backend1.example.com}) oder als Pfad eines Unix-Sockets mit dem +vorangestellten Präfix @samp{unix:} angegeben werden. Wenn Adressen eine +IP-Adresse oder einen Domänennamen benutzen, ist der voreingestellte Port +80, aber ein abweichender Port kann auch explizit angegeben werden. @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: +@deftp {Datentyp} nginx-location-configuration +Der Datentyp, der die Konfiguration eines nginx-@code{location}-Blocks +angibt. Der Typ hat die folgenden Parameter: @table @asis @item @code{uri} -URI which this location block matches. +Die URI, die auf diesen Block passt. @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;")}. +Der Rumpf des location-Blocks, der als eine Liste von Zeichenketten +angegeben werden muss. Er kann viele Konfigurationsdirektiven enthalten, zum +Beispiel können Anfragen an eine Upstream-Servergruppe weitergeleitet +werden, die mit einem @code{nginx-upstream-configuration}-Block angegeben +wurde, indem diese Direktive im Rumpf angegeben wird: @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: +@deftp {Datentyp} nginx-named-location-configuration +Der Datentyp repräsentiert die Konfiguration eines mit Namen versehenen +nginx-location-Blocks (»Named Location Block«). Ein mit Namen versehener +location-Block wird zur Umleitung von Anfragen benutzt und nicht für die +normale Anfrageverarbeitung. Dieser Typ hat die folgenden Parameter: @table @asis @item @code{name} -Name to identify this location block. +Der Name, mit dem dieser location-Block identifiziert wird. @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. +Siehe @ref{nginx-location-configuration body}, weil der Rumpf (»Body«) eines +mit Namen versehenen location-Blocks wie ein +@code{nginx-location-configuration body} benutzt werden kann. Eine +Einschränkung ist, dass der Rumpf eines mit Namen versehenen location-Blocks +keine location-Blöcke enthalten kann. @end table @end deftp @@ -18503,8 +19734,8 @@ 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: +Der Datentyp, der die Konfiguration des @code{fcgiwrap}-Dienstes +repräsentiert. Dieser Typ hat die folgenden Parameter: @table @asis @item @code{package} (default: @code{fcgiwrap}) The fcgiwrap package to use. @@ -18597,7 +19828,7 @@ 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}) +@item @code{timezone} (Vorgabe: @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 @@ -18674,7 +19905,7 @@ 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 @ +@deffn {Scheme-Prozedur} 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}. @@ -20162,42 +21393,42 @@ 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20205,7 +21436,7 @@ Defaults to @samp{disabled}. 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20213,35 +21444,35 @@ Defaults to @samp{disabled}. 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20271,7 +21502,7 @@ Defaults to @samp{#f}. 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20309,14 +21540,14 @@ Same as @code{disk-apm-bat} but on BAT mode. Hard disk spin down timeout. One value has to be specified for each declared hard disk. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20324,7 +21555,7 @@ Defaults to @samp{disabled}. 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20346,21 +21577,21 @@ Defaults to @samp{"min_power"}. @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist Exclude specified SATA host devices for link power management. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20515,7 +21746,7 @@ Defaults to @samp{#t}. @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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20535,7 +21766,7 @@ Defaults to @samp{#t}. @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist Exclude specified devices from USB autosuspend. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20550,14 +21781,14 @@ Defaults to @samp{#t}. 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}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? Enable USB autosuspend before shutdown. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -20635,6 +21866,15 @@ The directory to scan for music files. @item @code{playlist-dir} (default: @code{"~/.mpd/playlists"}) The directory to store playlists. +@item @code{db-file} (Vorgabe: @code{"~/.mpd/tag_cache"}) +Der Ort, an dem die Musikdatenbank gespeichert wird. + +@item @code{state-file} (Vorgabe: @code{"~/.mpd/state"}) +The location of the file that stores current MPD's state. + +@item @code{sticker-file} (Vorgabe: @code{"~/.mpd/sticker.sql"}) +Der Ort, an dem die Sticker-Datenbank gespeichert wird. + @item @code{port} (default: @code{"6600"}) The port to run mpd on. @@ -21367,7 +22607,7 @@ 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")))) + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")))) @end example In this example, we enable transparent emulation for the ARM and aarch64 @@ -22327,7 +23567,7 @@ Defaults to @samp{""}. A flag which can be used to disable the global setting @code{enable-commit-graph?}. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22335,7 +23575,7 @@ Defaults to @samp{disabled}. A flag which can be used to disable the global setting @code{enable-log-filecount?}. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22343,7 +23583,7 @@ Defaults to @samp{disabled}. A flag which can be used to disable the global setting @code{enable-log-linecount?}. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22351,7 +23591,7 @@ Defaults to @samp{disabled}. Flag which, when set to @code{#t}, will make cgit display remote branches in the summary and refs views. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22359,7 +23599,7 @@ Defaults to @samp{disabled}. A flag which can be used to override the global setting @code{enable-subject-links?}. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22367,7 +23607,7 @@ Defaults to @samp{disabled}. A flag which can be used to override the global setting @code{enable-html-serving?}. -Defaults to @samp{disabled}. +Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). @end deftypevr @@ -22644,8 +23884,8 @@ The port to bind the server to. @cindex fingerprint @subsubheading Fingerabdrucklese-Dienst -The @code{(gnu services fingerprint)} module provides a DBus service to read -and identify fingerprints via a fingerprint sensor. +The @code{(gnu services authentication)} 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 @@ -22746,6 +23986,34 @@ daemon that enables sharing the clipboard with a vm and setting the guest display resolution when the graphical console window resizes. @end deffn +@cindex inputattach +@subsubheading inputattach-Dienst + +@cindex tablet input, for Xorg +@cindex touchscreen input, for Xorg +The @uref{https://linuxwacom.github.io/, inputattach} service allows you to +use input devices such as Wacom tablets, touchscreens, or joysticks with the +Xorg display server. + +@deffn {Scheme-Variable} inputattach-service-type +Type of a service that runs @command{inputattach} on a device and dispatches +events from it. +@end deffn + +@deftp {Datentyp} inputattach-configuration +@table @asis +@item @code{device-type} (Vorgabe: @code{"wacom"}) +The type of device to connect to. Run @command{inputattach --help}, from +the @code{inputattach} package, to see the list of supported device types. + +@item @code{device} (Vorgabe: @code{"/dev/ttyS0"}) +The device file to connect to the device. + +@item @code{log-file} (Vorgabe: @code{#f}) +If true, this must be the name of a file to log messages to. +@end table +@end deftp + @subsection Dictionary Services @cindex dictionary The @code{(gnu services dict)} module provides the following service: @@ -22845,11 +24113,12 @@ The following is an example @code{dicod-service} configuration. @end example @cindex Docker -@subsubheading Docker Service +@subsubheading Docker-Dienst -The @code{(gnu services docker)} module provides the following service. +Das Modul @code{(gnu services docker)} stellt den folgenden Dienst zur +Verfügung. -@defvr {Scheme Variable} docker-service-type +@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 @@ -22857,17 +24126,17 @@ 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. +@deftp {Datentyp} docker-configuration +Dies ist der Datentyp, der die Konfiguration von Docker und Containerd +repräsentiert. @table @asis -@item @code{package} (default: @code{docker}) -The Docker package to use. +@item @code{package} (Vorgabe: @code{docker}) +Das Docker-Paket, was benutzt werden soll. -@item @code{containerd} (default: @var{containerd}) -The Containerd package to use. +@item @code{containerd} (Vorgabe: @var{containerd}) +Das Containerd-Paket, was benutzt werden soll. @end table @end deftp @@ -22875,46 +24144,51 @@ The Containerd package to use. @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}): +@cindex setuid-Programme +Manche Programme müssen mit Administratorrechten (also den Berechtigungen +des »root«-Benutzers) ausgeführt werden, selbst wenn Nutzer ohne besondere +Berechtigungen sie starten. Ein bekanntes Beispiel ist das Programm +@command{passwd}, womit Nutzer ihr Passwort ändern können, wozu das Programm +auf die Dateien @file{/etc/passwd} und @file{/etc/shadow} zugreifen muss — +was normalerweise nur der »root«-Nutzer darf, aus offensichtlichen Gründen +der Informationssicherheit. Deswegen sind diese ausführbaren Programmdateien +@dfn{setuid-root}, d.h.@: sie laufen immer mit den Administratorrechten des +root-Nutzers, egal wer sie startet (siehe @ref{How Change Persona,,, libc, +The GNU C Library Reference Manual} für mehr Informationen über den +setuid-Mechanismus). + +Der Store selbst kann @emph{keine} setuid-Programme enthalten: Das wäre eine +Sicherheitslücke, weil dann jeder Nutzer auf dem System Ableitungen +schreiben könnte, die in den Store solche Dateien einfügen würden (siehe +@ref{Der Store}). Wir benutzen also einen anderen Mechanismus: Statt auf den +ausführbaren Dateien im Store selbst deren setuid-Bit zu setzen, lassen wir +den Systemadministrator @emph{deklarieren}, welche Programme mit setuid-root +gestartet werden. + +Das Feld @code{setuid-programs} einer @code{operating-system}-Deklaration +enthält eine Liste von G-Ausdrücken, die die Namen der Programme angeben, +die setuid-root sein sollen (siehe @ref{Das Konfigurationssystem nutzen}). Zum Beispiel kann das Programm @command{passwd}, was Teil des +Shadow-Pakets ist, durch diesen G-Ausdruck bezeichnet werden (siehe +@ref{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. +Eine vorgegebene Menge von setuid-Programmen wird durch die Variable +@code{%setuid-programs} aus dem Modul @code{(gnu system)} definiert. -@defvr {Scheme Variable} %setuid-programs -A list of G-expressions denoting common programs that are setuid-root. +@defvr {Scheme-Variable} %setuid-programs +Eine Liste von G-Ausdrücken, die übliche Programme angeben, die setuid-root +sein müssen. -The list includes commands such as @command{passwd}, @command{ping}, -@command{su}, and @command{sudo}. +Die Liste enthält Befehle wie @command{passwd}, @command{ping}, @command{su} +und @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. +Intern erzeugt Guix die eigentlichen setuid-Programme im Verzeichnis +@file{/run/setuid-programs}, wenn das System aktiviert wird. Die Dateien in +diesem Verzeichnis verweisen auf die »echten« Binärdateien im Store. @node X.509-Zertifikate @section X.509-Zertifikate @@ -22935,15 +24209,15 @@ 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. +@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. +In Guix müssen Sie dazu ein Paket, das Zertifikate enthält, in das +@code{packages}-Feld der @code{operating-system}-Deklaration des +Betriebssystems hinzufügen (siehe @ref{»operating-system«-Referenz}). Guix +liefert ein solches Paket mit, @code{nss-certs}, was als Teil von Mozillas +»Network Security Services« angeboten wird. Beachten Sie, dass es @emph{nicht} zu den @var{%base-packages} gehört, Sie es also ausdrücklich hinzufügen müssen. Das Verzeichnis @@ -22987,89 +24261,98 @@ Umgebungsvariablen vielleicht in deren Dokumentation nachschlagen. @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}}). +Das Modul @code{(gnu system nss)} enthält Anbindungen für die Konfiguration +des @dfn{Name Service Switch} (NSS) der libc (siehe @ref{NSS Configuration +File,,, libc, The GNU C Library Reference Manual}). Kurz gesagt ist der NSS +ein Mechanismus, mit dem die libc um neue »Namens«-Auflösungsmethoden für +Systemdatenbanken erweitert werden kann; dazu gehören Rechnernamen (auch +bekannt als »Host«-Namen), Dienstnamen, Benutzerkonten und mehr (siehe +@ref{Name Service Switch, System Databases and Name Service Switch,, libc, +The GNU C Library Reference Manual}). + +Die NSS-Konfiguration legt für jede Systemdatenbank fest, mit welcher +Methode der Name nachgeschlagen (»aufgelöst«) werden kann und welche +Methoden zusammenhängen — z.B.@: unter welchen Umständen der NSS es mit der +nächsten Methode auf seiner Liste versuchen sollte. Die NSS-Konfiguration +wird im Feld @code{name-service-switch} von +@code{operating-system}-Deklarationen angegeben (siehe @ref{»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}: +@cindex .local, Rechnernamensauflösung +Zum Beispiel konfigurieren die folgenden Deklarationen den NSS so, dass er +das @uref{http://0pointer.de/lennart/projects/nss-mdns/, +@code{nss-mdns}-Backend} benutzt, wodurch er auf @code{.local} endende +Rechnernamen über Multicast-DNS (mDNS) auflöst: @example (name-service-switch - (hosts (list %files ;first, check /etc/hosts + (hosts (list %files ;zuerst in /etc/hosts nachschlagen - ;; If the above did not succeed, try - ;; with 'mdns_minimal'. + ;; Wenn das keinen Erfolg hatte, es + ;; mit 'mdns_minimal' versuchen. (name-service (name "mdns_minimal") - ;; 'mdns_minimal' is authoritative for - ;; '.local'. When it returns "not found", - ;; no need to try the next methods. + ;; 'mdns_minimal' ist die Autorität für + ;; '.local'. Gibt es not-found ("nicht + ;; gefunden") zurück, müssen wir die + ;; nächsten Methoden gar nicht erst + ;; versuchen. (reaction (lookup-specification (not-found => return)))) - ;; Then fall back to DNS. + ;; Ansonsten benutzen wir DNS. (name-service (name "dns")) - ;; Finally, try with the "full" 'mdns'. + ;; Ein letzter Versuch mit dem + ;; "vollständigen" '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. +Keine Sorge: Die Variable @code{%mdns-host-lookup-nss} (siehe unten) enthält +diese Konfiguration bereits. Statt das alles selst einzutippen, können Sie +sie benutzen, wenn alles, was Sie möchten, eine funktionierende +Namensauflösung für @code{.local}-Rechner ist. -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}}). +Beachten Sie dabei, dass es zusätzlich zum Festlegen des +@code{name-service-switch} in der @code{operating-system}-Deklaration auch +erforderlich ist, den @code{avahi-service-type} zu benutzen (siehe +@ref{Netzwerkdienste, @code{avahi-service-type}}). Es genügt auch, wenn +Sie die @var{%desktop-services} benutzen, weil er darin enthalten ist (siehe +@ref{Desktop-Dienste}). Dadurch wird @code{nss-mdns} für den Name Service +Cache Daemon nutzbar (siehe @ref{Basisdienste, @code{nscd-service}}). -For convenience, the following variables provide typical NSS configurations. +Um sich eine lange Konfiguration zu ersparen, können Sie auch einfach die +folgenden Variablen für typische NSS-Konfigurationen benutzen. -@defvr {Scheme Variable} %default-nss -This is the default name service switch configuration, a -@code{name-service-switch} object. +@defvr {Scheme-Variable} %default-nss +Die vorgegebene Konfiguration des Name Service Switch als ein +@code{name-service-switch}-Objekt. @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}. +@defvr {Scheme-Variable} %mdns-host-lookup-nss +Die Name-Service-Switch-Konfiguration mit Unterstützung für +Rechnernamensauflösung über »Multicast DNS« (mDNS) für auf @code{.local} +endende Rechnernamen. @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}. +Im Folgenden finden Sie eine Referenz, wie eine +Name-Service-Switch-Konfiguration aussehen muss. Sie hat eine direkte +Entsprechung zum Konfigurationsdateiformat der C-Bibliothek, lesen Sie +weitere Informationen also bitte im Handbuch der C-Bibliothek nach (siehe +@ref{NSS Configuration File,,, libc, The GNU C Library Reference +Manual}). Gegenüber dem Konfigurationsdateiformat des libc-NSS bekommen Sie +mit unserer Syntax nicht nur ein warm umklammerndes Gefühl, sondern auch +eine statische Analyse: Wenn Sie Syntax- und Schreibfehler machen, werden +Sie darüber benachrichtigt, sobald Sie @command{guix system} aufrufen. -@deftp {Data Type} name-service-switch +@deftp {Datentyp} 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. +Der Datentyp, der die Konfiguration des Name Service Switch (NSS) der libc +repräsentiert. Jedes im Folgenden aufgeführte Feld repräsentiert eine der +unterstützten Systemdatenbanken. @table @code @item aliases @@ -23085,30 +24368,31 @@ system databases. @itemx rpc @itemx services @itemx shadow -The system databases handled by the NSS. Each of these fields must be a -list of @code{} objects (see below). +Das sind die Systemdatenbanken, um die sich NSS kümmern kann. Jedes dieser +Felder muss eine Liste aus @code{}-Objekten sein (siehe +unten). @end table @end deftp -@deftp {Data Type} name-service +@deftp {Datentyp} name-service -This is the data type representing an actual name service and the associated -lookup action. +Der einen eigentlichen Namensdienst repräsentierende Datentyp zusammen mit +der zugehörigen Auflösungsaktion. @table @code @item name -A string denoting the name service (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). +Eine Zeichenkette, die den Namensdienst bezeichnet (siehe @ref{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}}). +Beachten Sie, dass hier aufgeführte Namensdienste für den nscd sichtbar sein +müssen. Dazu übergeben Sie im Argument @code{#:name-services} des +@code{nscd-service} die Liste der Pakete, die die entsprechenden +Namensdienste anbieten (siehe @ref{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: +Eine mit Hilfe des Makros @code{lookup-specification} angegebene Aktion +(siehe @ref{Actions in the NSS configuration,,, libc, The GNU C Library +Reference Manual}). Zum Beispiel: @example (lookup-specification (unavailable => continue) @@ -23122,19 +24406,20 @@ Reference Manual}). For example: @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: +Um ihn zu initialisieren (zu »bootstrappen«), wird für den Kernel +Linux-Libre eine @dfn{initiale RAM-Disk} angegeben (kurz @dfn{initrd}). Eine +initrd enthält ein temporäres Wurzeldateisystem sowie ein Skript zur +Initialisierung. Letzteres ist dafür zuständig, das echte Wurzeldateisystem +einzubinden und alle Kernel-Module zu laden, die dafür nötig sein könnten. + +Mit dem Feld @code{initrd-modules} einer @code{operating-system}-Deklaration +können Sie angeben, welche Kernel-Module für Linux-libre in der initrd +verfügbar sein müssen. Insbesondere müssen hier die Module aufgeführt +werden, um die Festplatte zu betreiben, auf der sich Ihre Wurzelpartition +befindet — allerdings sollte der vorgegebene Wert der @code{initrd-modules} +in dem meisten Fällen genügen. Wenn Sie aber zum Beispiel das Kernel-Modul +@code{megaraid_sas} zusätzlich zu den vorgegebenen Modulen brauchen, um auf +Ihr Wurzeldateisystem zugreifen zu können, würden Sie das so schreiben: @example (operating-system @@ -23142,314 +24427,370 @@ default modules to be able to access your root file system, you would write: (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. +@defvr {Scheme-Variable} %base-initrd-modules +Der Vorgabewert für die Liste der Kernel-Module, die in der initrd enthalten +sein sollen. @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. +Wenn Sie noch systemnähere Anpassungen durchführen wollen, können Sie im +Feld @code{initrd} einer @code{operating-system}-Deklaration angeben, was +für eine Art von initrd Sie benutzen möchten. Das Modul @code{(gnu system +linux-initrd)} enthält drei Arten, eine initrd zu erstellen: die abstrakte +Prozedur @code{base-initrd} und die systemnahen Prozeduren @code{raw-initrd} +und @code{expression->initrd}. -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: +Mit der Prozedur @code{base-initrd} sollten Sie die häufigsten +Anwendungszwecke abdecken können. Wenn Sie zum Beispiel ein paar +Kernel-Module zur Boot-Zeit laden lassen möchten, können Sie das +@code{initrd}-Feld auf diese Art definieren: @example (initrd (lambda (file-systems . rest) - ;; Create a standard initrd but set up networking - ;; with the parameters QEMU expects by default. + ;; Eine gewöhnliche initrd, aber das Netzwerk wird + ;; mit den Parametern initialisiert, die QEMU + ;; standardmäßig erwartet. (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. +Die Prozedur @code{base-initrd} kann auch mit üblichen Anwendungszwecken +umgehen, um das System als QEMU-Gastsystem zu betreiben oder als ein +»Live«-System ohne ein dauerhaft gespeichertes Wurzeldateisystem. -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. +Die Prozedur @code{base-initrd} baut auf der Prozedur @code{raw-initrd} +auf. Anders als @code{base-initrd} hat @code{raw-initrd} keinerlei +Zusatzfunktionalitäten: Es wird kein Versuch unternommen, für die initrd +notwendige Kernel-Module und Pakete automatisch +hinzuzunehmen. @code{raw-initrd} kann zum Beispiel benutzt werden, wenn ein +Nutzer eine eigene Konfiguration des Linux-Kernels verwendet und die +Standard-Kernel-Module, die mit @code{base-initrd} hinzugenommen würden, +nicht verfügbar sind. -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: +Die initiale RAM-Disk, wie sie von @code{base-initrd} oder @code{raw-initrd} +erzeugt wird, richtet sich nach verschiedenen Optionen, die auf der +Kernel-Befehlszeile übergeben werden (also über GRUBs @code{linux}-Befehl +oder die @code{-append}-Befehlszeilenoption von QEMU). Erwähnt werden +sollten: @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. +Die initiale RAM-Disk eine Datei @var{boot}, in der ein Scheme-Programm +steht, laden lassen, nachdem das Wurzeldateisystem eingebunden wurde. -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. +Guix übergibt mit dieser Befehlszeilenoption die Kontrolle an ein +Boot-Programm, das die Dienstaktivierungsprogramme ausführt und anschließend +den GNU@tie{}Shepherd startet, das Initialisierungssystem (»init«-System) +von Guix 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 --root=@var{Wurzel} +Das mit @var{Wurzel} bezeichnete Dateisystem als Wurzeldateisystem +einbinden. @var{Wurzel} kann ein Geratename wie @code{/dev/sda1}, eine +Dateisystembezeichnung (d.h.@: ein Dateisystem-»Label«) oder eine +Dateisystem-UUID sein. @item --system=@var{System} -Have @file{/run/booted-system} and @file{/run/current-system} point to -@var{system}. +@file{/run/booted-system} und @file{/run/current-system} auf das +@var{System} zeigen lassen. -@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 modprobe.blacklist=@var{Module}@dots{} +@cindex Kernel-Module, Sperrliste +@cindex Sperrliste, von Kernel-Modulen +Die initiale RAM-Disk sowie den Befehl @command{modprobe} (aus dem +kmod-Paket) anweisen, das Laden der angegebenen @var{Module} zu +verweigern. Als @var{Module} muss eine kommagetrennte Liste von +Kernel-Modul-Namen angegeben werden — z.B.@: @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. +Eine Lese-Auswerten-Schreiben-Schleife (englisch »Read-Eval-Print Loop«, +kurz REPL) von der initialen RAM-Disk starten, bevor diese die Kernel-Module +zu laden versucht und das Wurzeldateisystem einbindet. Unsere +Marketingabteilung nennt das @dfn{boot-to-Guile}. Der Schemer in Ihnen wird +das lieben. Siehe @ref{Using Guile Interactively,,, guile, GNU Guile +Reference Manual} für mehr Informationen über die REPL von Guile. @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. +Jetzt wo Sie wissen, was für Funktionalitäten eine durch @code{base-initrd} +und @code{raw-initrd} erzeugte initiale RAM-Disk so haben kann, möchten Sie +vielleicht auch wissen, wie man Sie benutzt und weiter anpasst: @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. +@deffn {Scheme-Prozedur} raw-initrd @var{Dateisysteme} @ + [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ +[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] +Liefert eine Ableitung, die eine rohe (»raw«) initrd +erstellt. @var{Dateisysteme} bezeichnet eine Liste von durch die initrd +einzubindenden Dateisystemen, unter Umständen zusätzlich zum auf der +Kernel-Befehlszeile mit @code{--root} angegebenen +Wurzeldateisystem. @var{linux-modules} ist eine Liste von Kernel-Modulen, +die zur Boot-Zeit geladen werden sollen. @var{mapped-devices} ist eine Liste +von Gerätezuordnungen, die hergestellt sein müssen, bevor die unter +@var{file-systems} aufgeführten Dateisysteme eingebunden werden (siehe +@ref{Zugeordnete Geräte}). @var{helper-packages} ist eine Liste von Paketen, die +in die initrd kopiert werden. Darunter kann @code{e2fsck/static} oder andere +Pakete aufgeführt werden, mit denen durch die initrd das Wurzeldateisystem +auf Fehler hin geprüft werden kann. + +When true, @var{keyboard-layout} is a @code{} record +denoting the desired console keyboard layout. This is done before +@var{mapped-devices} are set up and before @var{file-systems} are mounted +such that, should the user need to enter a passphrase or use the REPL, this +happens using the intended keyboard layout. + +Wenn @var{qemu-networking?} wahr ist, wird eine Netzwerkverbindung mit den +Standard-QEMU-Parametern hergestellt. Wenn @var{virtio?} wahr ist, werden +zusätzliche Kernel-Module geladen, damit die initrd als ein QEMU-Gast +paravirtualisierte Ein-/Ausgabetreiber benutzen kann. + +Wenn @var{volatile-root?} wahr ist, ist Schreiben auf das Wurzeldateisystem +möglich, aber Änderungen daran bleiben nicht erhalten. @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 +@deffn {Scheme-Prozedur} base-initrd @var{Dateisysteme} @ + [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] +[#:volatile-root? #f] @ [#:linux-modules '()] Liefert eine allgemein +anwendbare, generische initrd als dateiartiges Objekt mit den Kernel-Modulen +aus @var{linux}. Die @var{file-systems} sind eine Liste von durch die initrd +einzubindenden Dateisystemen, unter Umständen zusätzlich zum +Wurzeldateisystem, das auf der Kernel-Befehlszeile mit @code{--root} +angegeben wurde. Die @var{mapped-devices} sind eine Liste von +Gerätezuordnungen, die hergestellt sein müssen, bevor die @var{file-systems} +eingebunden werden. + +When true, @var{keyboard-layout} is a @code{} record +denoting the desired console keyboard layout. This is done before +@var{mapped-devices} are set up and before @var{file-systems} are mounted +such that, should the user need to enter a passphrase or use the REPL, this +happens using the intended keyboard layout. + +@var{qemu-networking?} und @var{volatile-root?} verhalten sich wie bei @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. +In die initrd werden automatisch alle Kernel-Module eingefügt, die für die +unter @var{file-systems} angegebenen Dateisysteme und die angegebenen +Optionen nötig sind. Zusätzliche Kernel-Module können unter den +@var{linux-modules} aufgeführt werden. Diese werden zur initrd hinzugefügt +und zur Boot-Zeit in der Reihenfolge geladen, in der sie angegeben wurden. @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. +Selbstverständlich betten die hier erzeugten und benutzten initrds ein +statisch gebundenes Guile ein und das Initialisierungsprogramm ist ein +Guile-Programm. Dadurch haben wir viel Flexibilität. Die Prozedur +@code{expression->initrd} erstellt eine solche initrd für ein an sie +übergebenes Programm. + +@deffn {Scheme-Prozedur} expression->initrd @var{G-Ausdruck} @ + [#:guile %guile-static-stripped] [#:name "guile-initrd"] Liefert eine +Linux-initrd (d.h.@: ein gzip-komprimiertes cpio-Archiv) als dateiartiges +Objekt, in dem @var{guile} enthalten ist, womit der @var{G-Ausdruck} nach +dem Booten ausgewertet wird. Alle vom @var{G-Ausdruck} referenzierten +Ableitungen werden automatisch in die initrd kopiert. @end deffn @node Bootloader-Konfiguration @section Bootloader-Konfiguration @cindex bootloader -@cindex boot loader +@cindex Bootloader -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. +Das Betriebssystem unterstützt mehrere Bootloader. Der gewünschte Bootloader +wird mit der @code{bootloader-configuration}-Deklaration konfiguriert. Alle +Felder dieser Struktur sind für alle Bootloader gleich außer dem einen Feld +@code{bootloader}, das angibt, welcher Bootloader konfiguriert und +installiert werden soll. -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. +Manche der Bootloader setzen nicht alle Felder einer +@code{bootloader-configuration} um. Zum Beispiel ignoriert der +extlinux-Bootloader das @code{theme}-Feld, weil er keine eigenen Themen +unterstützt. -@deftp {Data Type} bootloader-configuration -The type of a bootloader configuration declaration. +@deftp {Datentyp} bootloader-configuration +Der Typ der Deklaration einer Bootloader-Konfiguration. @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. +@cindex EFI, Bootloader +@cindex UEFI, Bootloader +@cindex BIOS, Bootloader +Der zu benutzende Bootloader als ein @code{bootloader}-Objekt. Zur Zeit +werden @code{grub-bootloader}, @code{grub-efi-bootloader}, +@code{extlinux-bootloader} und @code{u-boot-bootloader} unterstützt. @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. +@code{grub-efi-bootloader} macht es möglich, auf modernen Systemen mit +@dfn{Unified Extensible Firmware Interface} (UEFI) zu booten. Sie sollten +das hier benutzen, wenn im Installationsabbild ein Verzeichnis +@file{/sys/firmware/efi} vorhanden ist, wenn Sie davon auf Ihrem System +booten. @vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. +Mit @code{grub-bootloader} können Sie vor allem auf Intel-basierten +Maschinen im alten »Legacy«-BIOS-Modus booten. -@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}. +@cindex ARM, Bootloader +@cindex AArch64, Bootloader +Verfügbare Bootloader werden in den Modulen @code{(gnu bootloader @dots{})} +beschrieben. Insbesondere enthält @code{(gnu bootloader u-boot)} +Definitionen für eine Vielzahl von ARM- und AArch64-Systemen, die den +@uref{http://www.denx.de/wiki/U-Boot/, U-Boot-Bootloader} benutzen. @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 +Eine Zeichenkette, die angibt, auf welches Ziel der Bootloader installiert +werden soll. + +Was das bedeutet, hängt vom jeweiligen Bootloader ab. Für +@code{grub-bootloader} sollte hier zum Beispiel ein Gerätename angegeben +werden, der vom @command{installer}-Befehl des Bootloaders verstanden wird, +etwa @code{/dev/sda} oder @code{(hd0)} (siehe @ref{Invoking grub-install,,, +grub, GNU GRUB Manual}). Für @code{grub-efi-bootloader} sollte der +Einhängepunkt des EFI-Dateisystems angegeben werden, in der Regel +@file{/boot/efi}. + +@item @code{menu-entries} (Vorgabe: @code{()}) +Eine möglicherweise leere Liste von @code{menu-entry}-Objekten (siehe +unten), die für Menüeinträge stehen, die im Bootloader-Menü auftauchen +sollen, zusätzlich zum aktuellen Systemeintrag und dem auf vorherige +Systemgenerationen verweisenden Eintrag. + +@item @code{default-entry} (Vorgabe: @code{0}) +Die Position des standardmäßig ausgewählten Bootmenü-Eintrags. An Position 0 +steht der Eintrag der aktuellen Systemgeneration. + +@item @code{timeout} (Vorgabe: @code{5}) +Wieviele Sekunden lang im Menü auf eine Tastatureingabe gewartet wird, bevor +gebootet wird. 0 steht für sofortiges Booten, für -1 wird ohne +Zeitbeschränkung gewartet. + +@cindex Tastaturbelegung, beim Bootloader +@item @code{keyboard-layout} (Vorgabe: @code{#f}) +Wenn dies auf @code{#f} gesetzt ist, verwendet das Menü des Bootloaders +(falls vorhanden) die Vorgabe-Tastaturbelegung, normalerweise +US@tie{}English (»qwerty«). + +Andernfalls muss es ein @code{keyboard-layout}-Objekt sein (siehe +@ref{Tastaturbelegung}). + +@quotation Anmerkung +Dieses Feld wird derzeit von Bootloadern außer @code{grub} und +@code{grub-efi} ignoriert. +@end quotation + +@item @code{theme} (Vorgabe: @var{#f}) +Ein Objekt für das im Bootloader anzuzeigende Thema. Wird kein Thema +angegeben, benutzen manche Bootloader vielleicht ein voreingestelltes Thema; +GRUB zumindest macht es so. + +@item @code{terminal-outputs} (Vorgabe: @code{'gfxterm}) +Die Ausgabeterminals, die für das Boot-Menü des Bootloaders benutzt werden, +als eine Liste von Symbolen. GRUB akzeptiert hier diese Werte: +@code{console}, @code{serial}, @code{serial_@{0–3@}}, @code{gfxterm}, +@code{vga_text}, @code{mda_text}, @code{morse} und @code{pkmodem}. Dieses +Feld entspricht der GRUB-Variablen @code{GRUB_TERMINAL_OUTPUT} (siehe +@ref{Simple configuration,,, grub,GNU GRUB manual}). + +@item @code{terminal-inputs} (Vorgabe: @code{'()}) +Die Eingabeterminals, die für das Boot-Menü des Bootloaders benutzt werden, +als eine Liste von Symbolen. GRUB verwendet hier das zur Laufzeit bestimmte +Standardterminal. GRUB akzeptiert sonst diese Werte: @code{console}, +@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard} und +@code{usb_keyboard}. Dieses Feld entspricht der GRUB-Variablen +@code{GRUB_TERMINAL_INPUT} (siehe @ref{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-unit} (Vorgabe: @code{#f}) +Die serielle Einheit, die der Bootloader benutzt, als eine ganze Zahl +zwischen 0 und 3, einschließlich. Für GRUB wird sie automatisch zur Laufzeit +ausgewählt; derzeit wählt GRUB die 0 aus, die COM1 entspricht (siehe +@ref{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}). +@item @code{serial-speed} (Vorgabe: @code{#f}) +Die Geschwindigkeit der seriellen Schnittstelle als eine ganze Zahl. GRUB +bestimmt den Wert standardmäßig zur Laufzeit; derzeit wählt GRUB +9600@tie{}bps (siehe @ref{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: +@cindex Dual-Boot +@cindex Bootmenü +Sollten Sie zusätzliche Bootmenü-Einträge über das oben beschriebene +@code{menu-entries}-Feld hinzufügen möchten, müssen Sie diese mit der +@code{menu-entry}-Form erzeugen. Stellen Sie sich zum Beispiel vor, Sie +wollten noch eine andere Distribution booten können (schwer vorstellbar!), +dann könnten Sie einen Menüeintrag wie den Folgenden definieren: @example (menu-entry - (label "The Other Distro") + (label "Die _andere_ Distribution") (linux "/boot/old/vmlinux-2.6.32") (linux-arguments '("root=/dev/sda2")) (initrd "/boot/old/initrd")) @end example -Details below. +Details finden Sie unten. -@deftp {Data Type} menu-entry -The type of an entry in the bootloader menu. +@deftp {Datentyp} menu-entry +Der Typ eines Eintrags im Bootloadermenü. @table @asis @item @code{label} -The label to show in the menu---e.g., @code{"GNU"}. +Die Beschriftung, die im Menü gezeigt werden soll — z.B.@: @code{"GNU"}. @item @code{linux} -The Linux kernel image to boot, for example: +Das Linux-Kernel-Abbild, was gebootet werden soll, zum Beispiel: @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: +Für GRUB kann hier auch ein Gerät ausdrücklich zum Dateipfad angegeben +werden, unter Verwendung von GRUBs Konventionen zur Gerätebenennung (siehe +@ref{Naming convention,,, grub, GNU GRUB manual}), zum Beispiel: @example "(hd0,msdos1)/boot/vmlinuz" @end example -If the device is specified explicitly as above, then the @code{device} field -is ignored entirely. +Wenn das Gerät auf diese Weise ausdrücklich angegeben wird, wird das +@code{device}-Feld gänzlich ignoriert. -@item @code{linux-arguments} (default: @code{()}) -The list of extra Linux kernel command-line arguments---e.g., +@item @code{linux-arguments} (Vorgabe: @code{()}) +Die Liste zusätzlicher Linux-Kernel-Befehlszeilenargumente — z.B.@: @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}. +Ein G-Ausdruck oder eine Zeichenkette, die den Dateinamen der initialen +RAM-Disk angibt, die benutzt werden soll (siehe @ref{G-Ausdrücke}). +@item @code{device} (Vorgabe: @code{#f}) +Das Gerät, auf dem Kernel und initrd zu finden sind — d.h.@: bei GRUB die +Wurzel (@dfn{root}) dieses Menüeintrags (siehe @ref{root,,, grub, GNU GRUB +manual}). + +Dies kann eine Dateisystembezeichnung (als Zeichenkette), eine +Dateisystem-UUID (als Bytevektor, siehe @ref{Dateisysteme}) oder @code{#f} +sein, im letzten Fall wird der Bootloader auf dem Gerät suchen, das die vom +@code{linux}-Feld benannte Datei enthält (siehe @ref{search,,, grub, GNU +GRUB manual}). Ein vom Betriebssystem vergebener Gerätename wie +@file{/dev/sda1} ist aber @emph{nicht} erlaubt. @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 +For 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. +Das vorgegebene GRUB-Thema, das vom Betriebssystem benutzt wird, wenn kein +@code{theme}-Feld im @code{bootloader-configuration}-Verbundsobjekt +angegeben wurde. -It comes with a fancy background image displaying the GNU and Guix logos. +Es wird von einem feschen Hintergrundbild begleitet, das die Logos von GNU +und Guix zeigt. @end defvr @@ -23505,27 +24846,28 @@ relevance: 2 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 +filtern (siehe @ref{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 +Das in der @var{Datei} beschriebene Betriebssystem erstellen, aktivieren und +zu ihm wechseln@footnote{Diese Aktion (und die dazu ähnlichen Aktionen +@code{switch-generation} und @code{roll-back}) sind nur auf Systemen +nutzbar, auf denen »Guix System« bereits läuft.}. + +Dieser Befehl setzt die in der @var{Datei} festgelegte Konfiguration +vollständig um: Benutzerkonten, Systemdienste, die Liste globaler Pakete, +setuid-Programme und so weiter. Der Befehl startet die in der @var{Datei} +angegebenen Systemdienste, die aktuell nicht laufen; bei aktuell laufenden +Diensten wird sichergestellt, dass sie aktualisiert werden, sobald sie das +nächste Mal angehalten wurden (z.B.@: durch @code{herd stop X} oder @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}). +package} (siehe @ref{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 @@ -23538,9 +24880,10 @@ notwendig wird. @c The paragraph below refers to the problem discussed at @c . 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. +@command{guix system reconfigure} zum ersten Mal aufrufen (siehe +@ref{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 @@ -23600,30 +24943,33 @@ 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''). +@cindex Löschen von Systemgenerationen +@cindex Platz sparen +Systemgenerationen löschen, wodurch diese zu Kandidaten für den Müllsammler +werden (siehe @ref{Aufruf von guix gc} für Informationen, wie Sie den +»Müllsammler« laufen lassen). -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: +Es funktioniert auf die gleiche Weise wie @command{guix package +--delete-generations} (siehe @ref{Aufruf von guix package, +@code{--delete-generations}}). Wenn keine Argumente angegeben werden, werden +alle Systemgenerationen außer der aktuellen gelöscht: @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: +Sie können auch eine Auswahl treffen, welche Generationen Sie löschen +möchten. Das folgende Beispiel hat die Löschung aller Systemgenerationen zur +Folge, die älter als zwei Monate sind: @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. +Wenn Sie diesen Befehl ausführen, wird automatisch der Bootloader mit einer +aktualisierten Liste von Menüeinträgen neu erstellt — z.B.@: werden im +Untermenü für die »alten Generationen« in GRUB die gelöschten Generationen +nicht mehr aufgeführt. @item build Die Ableitung des Betriebssystems erstellen, einschließlich aller @@ -23631,9 +24977,9 @@ 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: +In das angegebene Verzeichnis alle Dateien einfügen, um das in der +@var{Datei} angegebene Betriebssystem starten zu können. Dies ist nützlich +bei erstmaligen Installationen von »Guix System«. Zum Beispiel: @example guix system init my-os-config.scm /mnt @@ -23643,7 +24989,7 @@ 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}, +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} @@ -23654,20 +25000,23 @@ wurde übergeben. @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). +Eine virtuelle Maschine (VM) erstellen, die das in der @var{Datei} +deklarierte Betriebssystem enthält, und ein Skript liefern, das diese +virtuelle Maschine startet. @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}). +Die Aktion @code{vm} sowie solche, die weiter unten genannt werden, können +KVM-Unterstützung im Kernel Linux-libre ausnutzen. Insbesondere sollte, wenn +die Maschine Hardware-Virtualisierung unterstützt, das entsprechende +KVM-Kernelmodul geladen sein und das Gerät @file{/dev/kvm} muss dann +existieren und dem Benutzer und den Erstellungsbenutzern des Daemons müssen +Berechtigungen zum Lesen und Schreiben darauf gegeben werden (siehe +@ref{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: +An das Skript übergebene Argumente werden an QEMU weitergereicht, wie Sie am +folgenden Beispiel sehen können. Damit würde eine Netzwerkverbindung +aktiviert und 1@tie{}GiB an RAM für die emulierte Maschine angefragt: @example $ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user @@ -23722,9 +25071,10 @@ 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{vm-image} anfordern, ist das gelieferte Disk-Image im +qcow2-Format, was vom QEMU-Emulator effizient benutzt werden kann. Im +Abschnitt @ref{Guix in einer VM starten} finden Sie mehr Informationen, wie Sie +das Disk-Image in einer virtuellen Maschine laufen lassen. Wenn Sie ein @code{disk-image} anfordern, wird ein rohes Disk-Image hergestellt; es kann zum Beispiel auf einen USB-Stick kopiert @@ -23744,19 +25094,20 @@ 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)" +image_id="$(docker load < guix-system-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}. +Dieser Befehl startet einen neuen Docker-Container aus dem angegebenen +Abbild. Damit wird das Guix-System auf die normale Weise hochgefahren, +d.h.@: zunächst werden alle Dienste gestartet, die Sie in der Konfiguration +des Betriebssystems angegeben haben. Je nachdem, was Sie im Docker-Container +ausführen, kann es nötig sein, dass Sie ihn mit weitergehenden +Berechtigungen ausstatten. Wenn Sie zum Beispiel Software mit Guix innerhalb +des Docker-Containers erstellen wollen, müssen Sie an @code{docker run} die +Befehlszeilenoption @option{--privileged} übergeben. @item container Liefert ein Skript, um das in der @var{Datei} deklarierte Betriebssystem in @@ -23772,7 +25123,7 @@ 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 +Wie bei der Aktion @code{vm} (siehe @ref{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: @@ -23788,21 +25139,22 @@ Diese Befehlszeilenoption funktioniert nur mit Linux-libre 3.19 oder neuer. @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: +aufgeführt werden (siehe @ref{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}). +Als Konfiguration des Betriebssystems das »operating-system« betrachten, zu +dem der @var{Ausdruck} ausgewertet wird. Dies ist eine Alternative dazu, die +Konfiguration in einer Datei festzulegen. Hiermit wird auch das +Installationsabbild des Guix-Systems erstellt, siehe @ref{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}). +build} (siehe @ref{Aufruf von guix build}). @item --derivation @itemx -d @@ -23810,7 +25162,7 @@ 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} +@itemx -t @var{Typ} Für die Aktion @code{disk-image} wird hiermit ein Dateisystem des angegebenen @var{Typ}s im Abbild bzw. Disk-Image erzeugt. @@ -23827,17 +25179,17 @@ für das Brennen auf CDs und DVDs geeignet ist. 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 +Einheit als Suffix versehen werden (siehe @ref{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 --root=@var{Datei} +@itemx -r @var{Datei} +Die @var{Datei} zu einer symbolischen Verknüpfung auf das Ergebnis machen +und als Müllsammlerwurzel registrieren. @item --skip-checks Die Konfiguration @emph{nicht} vor der Installation zur Sicherheit auf @@ -23847,14 +25199,14 @@ 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 +erwähnten Dateisysteme tatsächlich existieren (siehe @ref{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 +im @code{initrd-modules}-Feld aufgeführt sind (siehe @ref{Initiale RAM-Disk}). Mit dieser Befehlszeilenoption werden diese Tests allesamt übersprungen. @cindex on-error -@cindex on-error strategy -@cindex error strategy +@cindex on-error-Strategie +@cindex Fehlerstrategie @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: @@ -23874,15 +25226,15 @@ 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. +inspizieren. Siehe @ref{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: +Sobald Sie Ihre Guix-Installation erstellt, konfiguriert, neu konfiguriert +und nochmals neu konfiguriert haben, finden Sie es vielleicht hilfreich, +sich die auf der Platte verfügbaren — und im Bootmenü des Bootloaders +auswählbaren — Systemgenerationen auflisten zu lassen: @table @code @@ -23890,7 +25242,7 @@ boot menu: 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}). +(siehe @ref{Aufruf von guix package}). Optional kann ein Muster angegeben werden, was dieselbe Syntax wie @command{guix package --list-generations} benutzt, um damit die Liste @@ -23913,7 +25265,7 @@ voneinander abhängen: @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 +Betriebssystems ausgeben (siehe @ref{Dienstkompositionen} für mehr Informationen zu Diensterweiterungen). Der Befehl: @@ -23929,28 +25281,30 @@ angezeigt wird. @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. +definierten Betriebssystems ausgeben. Siehe @ref{Shepherd-Dienste} für mehr +Informationen sowie einen Beispielgraphen. @end table -@node Running Guix in a VM -@section Running Guix in a Virtual Machine +@node Guix in einer VM starten +@section Guix in einer virtuellen Maschine betreiben @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. +Um Guix in einer virtuellen Maschine (VM) auszuführen, können Sie entweder +das vorerstellte Guix-VM-Abbild benutzen, das auf +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{System}.xz} +angeboten wird, oder Ihr eigenes Abbild erstellen, indem Sie @command{guix +system vm-image} benutzen (siehe @ref{Aufruf von guix system}). Das Abbild +wird im qcow2-Format zurückgeliefert, das der @uref{http://qemu.org/, +QEMU-Emulator} effizient benutzen kann. @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: +Wenn Sie Ihr eigenes Abbild erstellen haben lassen, müssen Sie es aus dem +Store herauskopieren (siehe @ref{Der Store}) und sich darauf +Schreibberechtigung geben, um die Kopie benutzen zu können. Wenn Sie QEMU +aufrufen, müssen Sie einen Systememulator angeben, der für Ihre +Hardware-Plattform passend ist. Hier ist ein minimaler QEMU-Aufruf, der das +Ergebnis von @command{guix system vm-image} auf x86_64-Hardware bootet: @example $ qemu-system-x86_64 \ @@ -23958,84 +25312,99 @@ $ qemu-system-x86_64 \ -enable-kvm -m 256 /tmp/qemu-image @end example -Here is what each of these options means: +Die Bedeutung jeder dieser Befehlszeilenoptionen ist folgende: @table @code @item qemu-system-x86_64 -This specifies the hardware platform to emulate. This should match the -host. +Hiermit wird die zu emulierende Hardware-Plattform angegeben. Sie sollte zum +Wirtsrechner passen. @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. +Den als Nutzer ausgeführten Netzwerkstapel (»User-Mode Network Stack«) ohne +besondere Berechtigungen benutzen. Mit dieser Art von Netzwerkanbindung kann +das Gast-Betriebssystem eine Verbindung zum Wirt aufbauen, aber nicht +andersherum. Es ist die einfachste Art, das Gast-Betriebssystem mit dem +Internet zu verbinden. @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}. +Sie müssen ein Modell einer zu emulierenden Netzwerkschnittstelle +angeben. Wenn Sie keine Netzwerkkarte (englisch »Network Interface Card«, +kurz NIC) erzeugen lassen, wird das Booten fehlschlagen. Falls Ihre +Hardware-Plattform x86_64 ist, können Sie eine Liste verfügbarer NIC-Modelle +einsehen, indem Sie @command{qemu-system-x86_64 -net nic,model=help} +ausführen. @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. +Wenn Ihr System über Erweiterungen zur Hardware-Virtualisierung verfügt, +beschleunigt es die Dinge, wenn Sie die Virtualisierungsunterstützung »KVM« +des Linux-Kernels benutzen lassen. @item -m 256 -RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB, -which may be insufficient for some operations. +Die Menge an Arbeitsspeicher (RAM), die dem Gastbetriebssystem zur Verfügung +stehen soll, in Mebibytes. Vorgegeben wären 128@tie{}MiB, was für einige +Operationen zu wenig sein könnte. @item /tmp/qemu-image -The file name of the qcow2 image. +Der Dateiname des qcow2-Abbilds. @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}. +Das voreingestellte @command{run-vm.sh}-Skript, das durch einen Aufruf von +@command{guix system vm} erzeugt wird, fügt keine Befehlszeilenoption +@command{-net user} an. Um innerhalb der virtuellen Maschine Netzwerkzugang +zu haben, fügen Sie den @code{(dhcp-client-service)} zu Ihrer +Systemdefinition hinzu und starten Sie die VM mit @command{`guix system vm +config.scm` -net user}. Erwähnt werden sollte der Nachteil, dass bei +Verwendung von @command{-net user} zur Netzanbindung der +@command{ping}-Befehl @emph{nicht} funktionieren wird, weil dieser das +ICMP-Protokoll braucht. Sie werden also einen anderen Befehl benutzen +müssen, um auszuprobieren, ob Sie mit dem Netzwerk verbunden sind, zum +Beispiel @command{guix download}. -@subsection Connecting Through SSH +@subsection Verbinden über 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 +Um SSH in der virtuellen Maschine zu aktivieren, müssen Sie einen SSH-Server +wie den @code{(dropbear-service)} oder den @code{(lsh-service)} zu ihr +hinzufügen. Der @code{(lsh-service}) kann derzeit nicht ohne +Benutzerinteraktion starten, weil der Benutzer erst ein paar Zeichen +eintippen muss, um den Zufallsgenerator zu initialisieren. Des Weiteren +müssen Sie den SSH-Port für das Wirtssystem freigeben (standardmäßig hat er +die Portnummer 22). Das geht zum Beispiel so: @example `guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 @end example -To connect to the VM you can run +Um sich mit der virtuellen Maschine zu verbinden, benutzen Sie diesen +Befehl: @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. +Mit @command{-p} wird @command{ssh} der Port mitgeteilt, über den eine +Verbindung hergestellt werden soll. @command{-o +UserKnownHostsFile=/dev/null} verhindert, dass @command{ssh} sich bei jeder +Modifikation Ihrer @command{config.scm}-Datei beschwert, ein anderer +bekannter Rechner sei erwartet worden, und @command{-o +StrictHostKeyChecking=no} verhindert, dass Sie die Verbindung zu unbekannten +Rechnern jedes Mal bestätigen müssen, wenn Sie sich verbinden. -@subsection Using @command{virt-viewer} with Spice +@subsection @command{virt-viewer} mit Spice benutzen -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. +Eine Alternative zur grafischen Schnittstelle des standardmäßigen +@command{qemu} ist, sich mit Hilfe des @command{remote-viewer} aus dem Paket +@command{virt-viewer} zu verbinden. Um eine Verbindung herzustellen, +übergeben Sie die Befehlszeilenoption @command{-spice +port=5930,disable-ticketing} an @command{qemu}. Siehe den vorherigen +Abschnitt für weitere Informationen, wie Sie das übergeben. -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}: +Spice macht es auch möglich, ein paar nette Hilfestellungen zu benutzen, zum +Beispiel können Sie Ihren Zwischenspeicher zum Kopieren und Einfügen (Ihr +»Clipboard«) mit Ihrer virtuellen Maschine teilen. Um das zu aktivieren, +werden Sie die folgenden Befehlszeilennoptionen zusätzlich an @command{qemu} +übergeben müssen: @example -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 @@ -24044,14 +25413,15 @@ your VM. To enable that you'll also have to pass the following flags to name=com.redhat.spice.0 @end example -You'll also need to add the @pxref{Verschiedene Dienste, Spice service}. +Sie werden auch den @ref{Verschiedene Dienste, Spice-Dienst} hinzufügen +müssen. @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? +Der vorhergehende Abschnitt präsentiert die verfügbaren Dienste und wie man +sie in einer @code{operating-system}-Deklaration kombiniert. Aber wie +definieren wir solche Dienste eigentlich? Und was ist überhaupt ein Dienst? @menu * Dienstkompositionen:: Wie Dienste zusammengestellt werden. @@ -24064,62 +25434,67 @@ in the first place? And what is a service anyway? @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. +@cindex Daemons +Wir definieren hier einen @dfn{Dienst} (englisch »Service«) als, grob +gesagt, etwas, das die Funktionalität des Betriebssystems erweitert. Oft ist +ein Dienst ein Prozess — ein sogenannter @dfn{Daemon} —, der beim Hochfahren +des Systems gestartet wird: ein Secure-Shell-Server, ein Web-Server, der +Guix-Erstellungsdaemon usw. Manchmal ist ein Dienst ein Daemon, dessen +Ausführung von einem anderen Daemon ausgelöst wird — zum Beispiel wird ein +FTP-Server von @command{inetd} gestartet oder ein D-Bus-Dienst durch +@command{dbus-daemon} aktiviert. Manchmal entspricht ein Dienst aber auch +keinem Daemon. Zum Beispiel nimmt sich der Benutzerkonten-Dienst (»account +service«) die Benutzerkonten und sorgt dafür, dass sie existieren, wenn das +System läuft. Der »udev«-Dienst sammelt die Regeln zur Geräteverwaltung an +und macht diese für den eudev-Daemon verfügbar. Der @file{/etc}-Dienst fügt +Dateien in das Verzeichnis @file{/etc} des Systems ein. + +@cindex Diensterweiterungen +Dienste des Guix-Systems werden durch @dfn{Erweiterungen} (»Extensions«) +miteinander verbunden. Zum Beispiel @emph{erweitert} der Secure-Shell-Dienst +den Shepherd — Shepherd ist das Initialisierungssystem (auch »init«-System +genannt), was als PID@tie{}1 läuft —, indem es ihm die Befehlszeilen zum +Starten und Stoppen des Secure-Shell-Daemons übergibt (siehe @ref{Netzwerkdienste, @code{openssh-service-type}}). Der UPower-Dienst erweitert den +D-Bus-Dienst, indem es ihm seine @file{.service}-Spezifikation übergibt, und +erweitert den udev-Dienst, indem es ihm Geräteverwaltungsregeln übergibt +(siehe @ref{Desktop-Dienste, @code{upower-service}}). Der +Guix-Daemon-Dienst erweitert den Shepherd, indem er ihm die Befehlszeilen +zum Starten und Stoppen des Daemons übergibt, und er erweitert den +Benutzerkontendienst (»account service«), indem er ihm eine Liste der +benötigten Erstellungsbenutzerkonten übergibt (siehe @ref{Basisdienste}). + +Alles in allem bilden Dienste und ihre »Erweitert«-Relationen einen +gerichteten azyklischen Graphen (englisch »Directed Acyclic Graph«, kurz +DAG). Wenn wir Dienste als Kästen und Erweiterungen als Pfeile darstellen, +könnte ein typisches System so etwas hier anbieten: + +@image{images/service-graph,,5in,Typischer Diensterweiterungsgraph} + +@cindex Systemdienst +Ganz unten sehen wir den @dfn{Systemdienst}, der das Verzeichnis erzeugt, in +dem alles zum Ausführen und Hochfahren enthalten ist, so wie es der Befehl +@command{guix system build} liefert. Siehe @ref{Service-Referenz}, um mehr +über die anderen hier gezeigten Diensttypen zu erfahren. Beim +@ref{system-extension-graph, Befehl @command{guix system extension-graph}} +finden Sie Informationen darüber, wie Sie diese Darstellung für eine +Betriebssystemdefinition Ihrer Wahl generieren lassen. + +@cindex Diensttypen +Technisch funktioniert es so, dass Entwickler @dfn{Diensttypen} definieren +können, um diese Beziehungen auszudrücken. Im System kann es beliebig viele +Dienste zu jedem Typ geben — zum Beispiel können auf einem System zwei +Instanzen des GNU-Secure-Shell-Servers (lsh) laufen, mit zwei Instanzen des +Diensttyps @code{lsh-service-type} mit je unterschiedlichen Parametern. + +Der folgende Abschnitt beschreibt die Programmierschnittstelle für +Diensttypen und Dienste. @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}): +Ein @dfn{Diensttyp} (»service type«) ist ein Knoten im oben beschriebenen +ungerichteten azyklischen Graphen (DAG). Fangen wir an mit einem einfachen +Beispiel: dem Diensttyp für den Guix-Erstellungsdaemon (siehe @ref{Aufruf des guix-daemon}): @example (define guix-service-type @@ -24133,44 +25508,47 @@ with a simple example, the service type for the Guix build daemon @end example @noindent -It defines three things: +Damit sind drei Dinge definiert: @enumerate @item -A name, whose sole purpose is to make inspection and debugging easier. +Ein Name, der nur dazu da ist, dass man leichter die Abläufe verstehen und +Fehler suchen kann. @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. +Eine Liste von @dfn{Diensterweiterungen} (»service extensions«). Jede +Erweiterung gibt den Ziel-Diensttyp an sowie eine Prozedur, die für gegebene +Parameter für den Dienst eine Liste von Objekten zurückliefert, um den +Dienst dieses Typs zu erweitern. -Every service type has at least one service extension. The only exception -is the @dfn{boot service type}, which is the ultimate service. +Jeder Diensttyp benutzt mindestens eine Diensterweiterung. Die einzige +Ausnahme ist der @dfn{boot service type}, der die Grundlage aller Dienste +ist. @item -Optionally, a default value for instances of this type. +Optional kann ein Vorgabewert für Instanzen dieses Typs angegeben werden. @end enumerate -In this example, @var{guix-service-type} extends three services: +In this example, @code{guix-service-type} extends three services: -@table @var +@table @code @item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd service +The @code{guix-shepherd-service} procedure defines how the Shepherd service is extended. Namely, it returns a @code{} 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 +This extension for this service is computed by @code{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 +Here @code{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: +Ein Dienst dieses Typs wird dann so instanziiert: @example (service guix-service-type @@ -24179,22 +25557,22 @@ A service of this type is instantiated like this: (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: +Das zweite Argument an die @code{service}-Form ist ein Wert, der die +Parameter dieser bestimmten Dienstinstanz repräsentiert. Siehe +@ref{guix-configuration-type, @code{guix-configuration}} für Informationen +über den @code{guix-configuration}-Datentyp. Wird kein Wert angegeben, wird +die Vorgabe verwendet, die im @code{guix-service-type} angegeben wurde: @example (service guix-service-type) @end example -@var{guix-service-type} is quite simple because it extends other services +@code{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: +Der Diensttyp eines @emph{erweiterbaren} Dienstes sieht ungefähr so aus: @example (define udev-service-type @@ -24203,107 +25581,114 @@ The service type for an @emph{extensible} service looks like this: (list (service-extension shepherd-root-service-type udev-shepherd-service))) - (compose concatenate) ;concatenate the list of rules - (extend (lambda (config rules) + (compose concatenate) ;Liste der Regeln zusammenfügen + (extend (lambda (config rules) ;Konfiguration und Regeln (match config (($ udev initial-rules) (udev-configuration - (udev udev) ;the udev package to use + (udev udev) ;zu benutzendes udev-Paket (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: +@code{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. +Die Prozedur, um die Liste der jeweiligen Erweiterungen für den Dienst +dieses Typs zu einem Objekt zusammenzustellen (zu »komponieren«, englisch +@dfn{compose}). -Services can extend the udev service by passing it lists of rules; we -compose those extensions simply by concatenating them. +Dienste können den udev-Dienst erweitern, indem sie eine Liste von Regeln +(»Rules«) an ihn übergeben; wir komponieren mehrere solche Erweiterungen, +indem wir die Listen einfach zusammenfügen. @item extend -This procedure defines how the value of the service is @dfn{extended} with -the composition of the extensions. +Diese Prozedur definiert, wie der Wert des Dienstes um die Komposition mit +Erweiterungen erweitert (»extended«) werden kann. -Udev extensions are composed into a list of rules, but the udev service -value is itself a @code{} record. So here, we extend -that record by appending the list of rules it contains to the list of -contributed rules. +Udev-Erweiterungen werden zu einer einzigen Liste von Regeln komponiert, +aber der Wert des udev-Dienstes ist ein +@code{}-Verbundsobjekt. Deshalb erweitern wir diesen +Verbund, indem wir die Liste der von Erweiterungen beigetragenen Regeln an +die im Verbund gespeicherte Liste der Regeln anhängen. @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}). +Diese Zeichenkette gibt einen Überblick über den Systemtyp. Die Zeichenkette +darf mit Texinfo ausgezeichnet werden (siehe @ref{Overview,,, texinfo, GNU +Texinfo}). Der Befehl @command{guix system search} durchsucht diese +Zeichenketten und zeigt sie an (siehe @ref{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} +@code{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. +Sind Sie noch da? Der nächste Abschnitt gibt Ihnen eine Referenz der +Programmierschnittstelle für Dienste. @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. +Wir haben bereits einen Überblick über Diensttypen gesehen (siehe +@ref{Diensttypen und Dienste}). Dieser Abschnitt hier stellt eine +Referenz dar, wie Dienste und Diensttypen manipuliert werden können. Diese +Schnittstelle wird vom Modul @code{(gnu services)} angeboten. -@deffn {Scheme Procedure} service @var{type} [@var{value}] -Return a new service of @var{type}, a @code{} object (see -below.) @var{value} can be any object; it represents the parameters of this -particular service instance. +@deffn {Scheme-Prozedur} service @var{Typ} [@var{Wert}] +Liefert einen neuen Dienst des angegebenen @var{Typ}s. Der @var{Typ} muss +als @code{}-Objekt angegeben werden (siehe unten). Als +@var{Wert} kann ein beliebiges Objekt angegeben werden, das die Parameter +dieser bestimmten Instanz dieses Dienstes repräsentiert. -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. +Wenn kein @var{Wert} angegeben wird, wird der vom @var{Typ} festgelegte +Vorgabewert verwendet; verfügt der @var{Typ} über keinen Vorgabewert, dann +wird ein Fehler gemeldet. -For instance, this: +Zum Beispiel bewirken Sie hiermit: @example (service openssh-service-type) @end example @noindent -is equivalent to this: +dasselbe wie mit: @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. +In beiden Fällen ist das Ergebnis eine Instanz von +@code{openssh-service-type} mit der vorgegebenen Konfiguration. @end deffn -@deffn {Scheme Procedure} service? @var{obj} -Return true if @var{obj} is a service. +@deffn {Scheme-Prozedur} service? @var{Objekt} +Liefert wahr zurück, wenn das @var{Objekt} ein Dienst ist. @end deffn -@deffn {Scheme Procedure} service-kind @var{service} -Return the type of @var{service}---i.e., a @code{} object. +@deffn {Scheme-Prozedur} service-kind @var{Dienst} +Liefert den Typ des @var{Dienst}es — d.h.@: ein +@code{}-Objekt. @end deffn -@deffn {Scheme Procedure} service-value @var{service} -Return the value associated with @var{service}. It represents its -parameters. +@deffn {Scheme-Prozedur} service-value @var{Dienst} +Liefert den Wert, der mit dem @var{Dienst} assoziiert wurde. Er +repräsentiert die Parameter des @var{Dienst}es. @end deffn -Here is an example of how a service is created and manipulated: +Hier ist ein Beispiel, wie ein Dienst erzeugt und manipuliert werden kann: @example (define s (service nginx-service-type (nginx-configuration (nginx nginx) - (log-directory log-directory) - (run-directory run-directory) - (file config-file)))) + (log-directory log-Verzeichnis) + (run-directory run-Verzeichnis) + (file config-Datei)))) (service? s) @result{} #t @@ -24313,7 +25698,7 @@ Here is an example of how a service is created and manipulated: @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} +parameters of some of the services of a list such as @code{%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, @@ -24332,7 +25717,7 @@ angegebenen Klauseln an. Jede Klausel hat die Form: 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 +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. @@ -24345,72 +25730,79 @@ 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. +Siehe @ref{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. +Als Nächstes ist die Programmierschnittstelle für Diensttypen an der +Reihe. Sie ist etwas, was Sie kennen werden wollen, wenn Sie neue +Dienstdefinitionen schreiben, aber wenn Sie nur Ihre +@code{operating-system}-Deklaration anpassen möchten, brauchen Sie diese +Schnittstelle wahrscheinlich nicht. -@deftp {Data Type} service-type -@cindex service type -This is the representation of a @dfn{service type} (@pxref{Diensttypen und Dienste}). +@deftp {Datentyp} service-type +@cindex Diensttyp +Die Repräsentation eines @dfn{Diensttypen} (siehe @ref{Diensttypen und Dienste}). @table @asis @item @code{name} -This is a symbol, used only to simplify inspection and debugging. +Dieses Symbol wird nur verwendet, um die Abläufe im System anzuzeigen und +die Fehlersuche zu erleichtern. @item @code{extensions} -A non-empty list of @code{} 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. +Eine nicht-leere Liste von @code{}-Objekten (siehe +unten). + +@item @code{compose} (Vorgabe: @code{#f}) +Wenn es auf @code{#f} gesetzt ist, dann definiert der Diensttyp Dienste, die +nicht erweitert werden können — d.h.@: diese Dienste erhalten ihren Wert +nicht von anderen Diensten. + +Andernfalls muss es eine Prozedur sein, die ein einziges Argument +entgegennimmt. Die Prozedur wird durch @code{fold-services} aufgerufen und +ihr wird die Liste von aus den Erweiterungen angesammelten Werten +übergeben. Sie gibt daraufhin einen einzelnen Wert zurück. + +@item @code{extend} (Vorgabe: @code{#f}) +Ist dies auf @code{#f} gesetzt, dann können Dienste dieses Typs nicht +erweitert werden. + +Andernfalls muss es eine zwei Argumente nehmende Prozedur sein, die von +@code{fold-services} mit dem anfänglichen Wert für den Dienst als erstes +Argument und dem durch Anwendung von @code{compose} gelieferten Wert als +zweites Argument aufgerufen wird. Als Ergebnis muss ein Wert geliefert +werden, der einen zulässigen neuen Parameterwert für die Dienstinstanz +darstellt. @end table -@xref{Diensttypen und Dienste}, for examples. +Siehe den Abschnitt @ref{Diensttypen und Dienste} für Beispiele. @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. +@deffn {Scheme-Prozedur} service-extension @var{Zieltyp} @ + @var{Berechner} Liefert eine neue Erweiterung für den Dienst mit dem +@var{Zieltyp}. Als @var{Berechner} muss eine Prozedur angegeben werden, die +ein einzelnes Argument nimmt: @code{fold-services} ruft sie auf und übergibt +an sie den Wert des erweiternden Dienstes, sie muss dafür einen zulässigen +Wert für den @var{Zieltyp} liefern. @end deffn -@deffn {Scheme Procedure} service-extension? @var{obj} -Return true if @var{obj} is a service extension. +@deffn {Scheme-Prozedur} service-extension? @var{Objekt} +Liefert wahr zurück, wenn das @var{Objekt} eine Diensterweiterung ist. @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. +Manchmal wollen Sie vielleicht einfach nur einen bestehenden Dienst +erweitern. Dazu müssten Sie einen neuen Diensttyp definieren und die +Erweiterung definieren, für die Sie sich interessieren, was ganz schön +wortreich werden kann. Mit der Prozedur @code{simple-service} können Sie es +kürzer fassen. -@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. +@deffn {Scheme-Prozedur} simple-service @var{Name} @var{Zieltyp} @var{Wert} +Liefert einen Dienst, der den Dienst mit dem @var{Zieltyp} um den @var{Wert} +erweitert. Dazu wird ein Diensttyp mit dem @var{Name}n für den einmaligen +Gebrauch erzeugt, den der zurückgelieferte Dienst instanziiert. -For example, this extends mcron (@pxref{Geplante Auftragsausführung}) with an -additional job: +Zum Beispiel kann mcron (siehe @ref{Geplante Auftragsausführung}) so um einen +zusätzlichen Auftrag erweitert werden: @example (simple-service 'my-mcron-job mcron-service-type @@ -24418,198 +25810,213 @@ additional job: @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. +Den Kern dieses abstrakten Modells für Dienste bildet die Prozedur +@code{fold-services}, die für das »Kompilieren« einer Liste von Diensten hin +zu einem einzelnen Verzeichnis verantwortlich ist, in welchem alles +enthalten ist, was Sie zum Booten und Hochfahren des Systems brauchen — +d.h.@: das Verzeichnis, das der Befehl @command{guix system build} anzeigt +(siehe @ref{Aufruf von guix system}). Einfach ausgedrückt propagiert +@code{fold-services} Diensterweiterungen durch den Dienstgraphen nach unten +und aktualisiert dabei in jedem Knoten des Graphen dessen Parameter, bis nur +noch der Wurzelknoten übrig bleibt. + +@deffn {Scheme-Prozedur} fold-services @var{Dienste} @ + [#:target-type @var{system-service-type}] Faltet die @var{Dienste} wie die +funktionale Prozedur @code{fold} zu einem einzigen zusammen, indem ihre +Erweiterungen nach unten propagiert werden, bis eine Wurzel vom +@var{target-type} als Diensttyp erreicht wird; dieser so angepasste +Wurzeldienst wird zurückgeliefert. @end deffn -Lastly, the @code{(gnu services)} module also defines several essential -service types, some of which are listed below. +Als Letztes definiert das Modul @code{(gnu services)} noch mehrere +essenzielle Diensttypen, von denen manche im Folgenden aufgelistet sind: -@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. +@defvr {Scheme-Variable} system-service-type +Die Wurzel des Dienstgraphen. Davon wird das Systemverzeichnis erzeugt, wie +es vom Befehl @command{guix system build} zurückgeliefert wird. @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. +@defvr {Scheme-Variable} boot-service-type +Der Typ des »Boot-Dienstes«, der das @dfn{Boot-Skript} erzeugt. Das +Boot-Skript ist das, was beim Booten durch die initiale RAM-Disk ausgeführt +wird. @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: +@defvr {Scheme-Variable} etc-service-type +Der Typ des @file{/etc}-Dienstes. Dieser Dienst wird benutzt, um im +@file{/etc}-Verzeichnis Dateien zu platzieren. Er kann erweitert werden, +indem man Name-/Datei-Tupel an ihn übergibt wie in diesem Beispiel: @example -(list `("issue" ,(plain-file "issue" "Welcome!\n"))) +(list `("issue" ,(plain-file "issue" "Willkommen!\n"))) @end example -In this example, the effect would be to add an @file{/etc/issue} file -pointing to the given file. +Dieses Beispiel würde bewirken, dass eine Datei @file{/etc/issue} auf die +angegebene Datei verweist. @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}). +@defvr {Scheme-Variable} setuid-program-service-type +Der Typ des Dienstes für setuid-Programme, der eine Liste von ausführbaren +Dateien ansammelt, die jeweils als G-Ausdrücke übergeben werden und dann zur +Menge der setuid-gesetzten Programme auf dem System hinzugefügt werden +(siehe @ref{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. +@defvr {Scheme-Variable} profile-service-type +Der Typ des Dienstes zum Einfügen von Dateien ins @dfn{Systemprofil} — +d.h.@: die Programme unter @file{/run/current-system/profile}. Andere +Dienste können ihn erweitern, indem sie ihm Listen von ins Systemprofil zu +installierenden Paketen übergeben. @end defvr @node Shepherd-Dienste @subsection Shepherd-Dienste -@cindex shepherd services +@cindex Shepherd-Dienste @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 +@cindex init-System +Das Modul @code{(gnu services shepherd)} gibt eine Methode an, mit der +Dienste definiert werden können, die von GNU@tie{}Shepherd verwaltet werden, +was das Initialisierungssystem (das »init«-System) ist — es ist der erste +Prozess, der gestartet wird, wenn das System gebootet wird, auch bekannt als +PID@tie{}1 (siehe @ref{Einführung,,, shepherd, The GNU Shepherd Manual}). + +Dienste unter dem Shepherd können voneinander abhängen. Zum Beispiel kann es +sein, dass der SSH-Daemon erst gestartet werden darf, nachdem der +Syslog-Daemon gestartet wurde, welcher wiederum erst gestartet werden kann, +sobald alle Dateisysteme eingebunden wurden. Das einfache Betriebssystem, +dessen Definition wir zuvor gesehen haben (siehe @ref{Das Konfigurationssystem nutzen}), ergibt folgenden Dienstgraphen: + +@image{images/shepherd-graph,,5in,Typischer Shepherd-Dienstgraph} + +Sie können so einen Graphen tatsächlich für jedes Betriebssystem erzeugen +lassen, indem Sie den Befehl @command{guix system shepherd-graph} benutzen +(siehe @ref{system-shepherd-graph, @command{guix system shepherd-graph}}). + +The @code{%shepherd-root-service} is a service object representing +PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by passing it lists of @code{} objects. -@deftp {Data Type} shepherd-service -The data type representing a service managed by the Shepherd. +@deftp {Datentyp} shepherd-service +Der Datentyp, der einen von Shepherd verwalteten Dienst repräsentiert. @table @asis @item @code{provision} -This is a list of symbols denoting what the service provides. +Diese Liste von Symbolen gibt an, was vom Dienst angeboten wird. -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. +Das bedeutet, es sind die Namen, die an @command{herd start}, @command{herd +status} und ähnliche Befehle übergeben werden können (siehe @ref{Invoking +herd,,, shepherd, The GNU Shepherd Manual}). Siehe @ref{Slots of services, +the @code{provides} slot,, shepherd, The GNU Shepherd Manual} für Details. -@item @code{requirements} (default: @code{'()}) -List of symbols denoting the Shepherd services this one depends on. +@item @code{requirements} (Vorgabe: @code{'()}) +Eine Liste von Symbolen, die angegeben, von welchen anderen +Shepherd-Diensten dieser hier abhängt. -@item @code{respawn?} (default: @code{#t}) -Whether to restart the service when it stops, for instance when the -underlying process dies. +@item @code{respawn?} (Vorgabe: @code{#t}) +Ob der Dienst neu gestartet werden soll, nachdem er gestoppt wurde, zum +Beispiel wenn der ihm zu Grunde liegende Prozess terminiert wird. @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}). +@itemx @code{stop} (Vorgabe: @code{#~(const #f)}) +Die Felder @code{start} und @code{stop} beziehen sich auf Shepherds +Funktionen zum Starten und Stoppen von Prozessen (siehe @ref{Service De- and +Constructors,,, shepherd, The GNU Shepherd Manual}). Sie enthalten +G-Ausdrücke, die in eine Shepherd-Konfigurationdatei umgeschrieben werden +(siehe @ref{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: +Dies ist eine Liste von @code{shepherd-action}-Objekten (siehe unten), die +vom Dienst zusätzlich unterstützte @dfn{Aktionen} neben den Standardaktionen +@code{start} und @code{stop} angeben. Hier aufgeführte Aktionen werden als +@command{herd}-Unterbefehle verfügbar gemacht: @example -herd @var{action} @var{service} [@var{arguments}@dots{}] +herd @var{Aktion} @var{Dienst} [@var{Argumente}@dots{}] @end example @item @code{Dokumentation} -A documentation string, as shown when running: +Eine Zeichenkette zur Dokumentation, die angezeigt wird, wenn man dies +ausführt: @example -herd doc @var{service-name} +herd doc @var{Dienstname} @end example -where @var{service-name} is one of the symbols in @var{provision} +where @var{service-name} is one of the symbols in @code{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. +@item @code{modules} (default: @code{%default-modules}) +Dies ist die Liste der Module, die in den Sichtbarkeitsbereich geladen sein +müssen, wenn @code{start} und @code{stop} ausgewertet werden. @end table @end deftp @deftp {Datentyp} shepherd-action -This is the data type that defines additional actions implemented by a -Shepherd service (see above). +Dieser Datentyp definiert zusätzliche Aktionen, die ein Shepherd-Dienst +implementiert (siehe oben). @table @code @item name Die Aktion bezeichnendes Symbol. @item Dokumentation -This is a documentation string for the action. It can be viewed by running: +Diese Zeichenkette ist die Dokumentation für die Aktion. Sie können sie +sehen, wenn Sie dies ausführen: @example -herd doc @var{service} action @var{action} +herd doc @var{Dienst} action @var{Aktion} @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}). +Dies sollte ein G-Ausdruck sein, der zu einer mindestens ein Argument +nehmenden Prozedur ausgewertet wird. Das Argument ist der »running«-Wert des +Dienstes (siehe @ref{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: +Das folgende Beispiel definiert eine Aktion namens @code{sag-hallo}, die den +Benutzer freundlich begrüßt: @example (shepherd-action - (name 'say-hello) - (documentation "Say hi!") + (name 'sag-hallo) + (documentation "Sag Hallo!") (procedure #~(lambda (running . args) - (format #t "Hello, friend! arguments: ~s\n" + (format #t "Hallo, Freund! Argumente: ~s\n" args) #t))) @end example -Assuming this action is added to the @code{example} service, then you can -do: +Wenn wir annehmen, dass wir die Aktion zum Dienst @code{beispiel} +hinzufügen, können Sie Folgendes ausführen: @example -# herd say-hello example -Hello, friend! arguments: () -# herd say-hello example a b c -Hello, friend! arguments: ("a" "b" "c") +# herd sag-hallo beispiel +Hallo, Freund! Argumente: () +# herd sag-hallo beispiel a b c +Hallo, Freund! Argumente: ("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. +Wie Sie sehen können, ist das eine sehr ausgeklügelte Art, Hallo zu +sagen. Siehe @ref{Service Convenience,,, shepherd, The GNU Shepherd Manual} +für mehr Informationen zu Aktionen. @end deftp -@defvr {Scheme Variable} shepherd-root-service-type -The service type for the Shepherd ``root service''---i.e., PID@tie{}1. +@defvr {Scheme-Variable} shepherd-root-service-type +Der Diensttyp für den Shepherd-»Wurzeldienst« — also für 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{}. +Dieser Diensttyp stellt das Ziel für Diensterweiterungen dar, die +Shepherd-Dienste erzeugen sollen (siehe @ref{Diensttypen und Dienste} für +ein Beispiel). Jede Erweiterung muss eine Liste von +@code{}-Objekten übergeben. @end defvr -@defvr {Scheme Variable} %shepherd-root-service -This service represents PID@tie{}1. +@defvr {Scheme-Variable} %shepherd-root-service +Dieser Dienst repräsentiert PID@tie{}1. @end defvr @@ -24742,7 +26149,7 @@ check whether a package has a @code{debug} output, use @command{guix package @chapter Sicherheitsaktualisierungen @cindex security updates -@cindex security vulnerabilities +@cindex Sicherheitslücken 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 @@ -24786,7 +26193,7 @@ 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 +@code{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: @@ -24800,15 +26207,15 @@ pointing to the package containing the bug fix: 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. +is installed is automatically ``rewritten'' to refer to @code{bash-fixed} +instead of @code{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) +package it replaces (@code{bash-fixed} and @code{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 @@ -25084,28 +26491,31 @@ generated binaries could be broken for some reason. @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. +Guix baut auf dem @uref{http://nixos.org/nix/, Nix-Paketverwaltungsprogramm} +auf, das von Eelco Dolstra entworfen und entwickelt wurde, mit Beiträgen von +anderen Leuten (siehe die Datei @file{nix/AUTHORS} in Guix). Nix hat für die +funktionale Paketverwaltung die Pionierarbeit geleistet und noch nie +dagewesene Funktionalitäten vorangetrieben wie transaktionsbasierte +Paketaktualisierungen und die Rücksetzbarkeit selbiger, eigene Paketprofile +für jeden Nutzer und referenziell transparente Erstellungsprozesse. Ohne +diese Arbeit gäbe es Guix nicht. -The Nix-based software distributions, Nixpkgs and NixOS, have also been an -inspiration for Guix. +Die Nix-basierten Software-Distributionen Nixpkgs und NixOS waren auch eine +Inspiration für 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! +GNU@tie{}Guix ist selbst das Produkt kollektiver Arbeit mit Beiträgen durch +eine Vielzahl von Leuten. Siehe die Datei @file{AUTHORS} in Guix für mehr +Informationen, wer diese wunderbaren Menschen sind. In der Datei +@file{THANKS} finden Sie eine Liste der Leute, die uns geholfen haben, indem +Sie Fehler gemeldet, sich um unsere Infrastruktur gekümmert, künstlerische +Arbeit und schön gestaltete Themen beigesteuert, Vorschläge gemacht und noch +vieles mehr getan haben — vielen Dank! @c ********************************************************************* @node GNU-Lizenz für freie Dokumentation @appendix GNU-Lizenz für freie Dokumentation -@cindex license, GNU Free Documentation License +@cindex Lizenz, GNU-Lizenz für freie Dokumentation @include fdl-1.3.texi @c ********************************************************************* -- cgit v1.2.3 From 9ca5ff882e2ac4eaab02eb0fde545bd784af478b Mon Sep 17 00:00:00 2001 From: Miguel Ángel Arruga Vivas Date: Tue, 23 Apr 2019 11:30:32 +0200 Subject: bootstrap: Break automake dependency on generated files. * bootstrap: Generate stub files for the manual translations whose generated files are not included in the VCS. * doc/contributing.de.texi: Remove file. * doc/contributing.es.texi: Remove file. * doc/contributing.fr.texi: Remove file. * doc/contributing.zh_CN.texi: Remove file. * doc/guix.de.texi: Remove file. * doc/guix.es.texi: Remove file. * doc/guix.fr.texi: Remove file. * doc/guix.zh_CN.texi: Remove file. * .gitignore: Add them. Signed-off-by: Julien Lepiller --- .gitignore | 2 + bootstrap | 14 + doc/contributing.de.texi | 1055 -- doc/contributing.es.texi | 1016 -- doc/contributing.fr.texi | 1007 -- doc/contributing.zh_CN.texi | 897 -- doc/guix.de.texi | 26536 ------------------------------------------ doc/guix.es.texi | 26015 ----------------------------------------- doc/guix.fr.texi | 26504 ----------------------------------------- doc/guix.zh_CN.texi | 25352 ---------------------------------------- 10 files changed, 16 insertions(+), 108382 deletions(-) delete mode 100644 doc/contributing.de.texi delete mode 100644 doc/contributing.es.texi delete mode 100644 doc/contributing.fr.texi delete mode 100644 doc/contributing.zh_CN.texi delete mode 100644 doc/guix.de.texi delete mode 100644 doc/guix.es.texi delete mode 100644 doc/guix.fr.texi delete mode 100644 doc/guix.zh_CN.texi (limited to 'doc/guix.de.texi') diff --git a/.gitignore b/.gitignore index 2ffb438219..93d2ec9801 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ /configure /doc/*.1 /doc/.dirstamp +/doc/contributing.*.texi /doc/guix.*.aux /doc/guix.*.cp /doc/guix.*.cps @@ -43,6 +44,7 @@ /doc/guix.*.tp /doc/guix.*.vr /doc/guix.*.vrs +/doc/guix.*.texi /doc/guix.aux /doc/guix.cp /doc/guix.cps diff --git a/bootstrap b/bootstrap index cb774bc737..c0b5af7677 100755 --- a/bootstrap +++ b/bootstrap @@ -2,4 +2,18 @@ # Create the build system. set -e -x + +# Generate stubs for translations. +langs=`find po/doc -type f -name '*.po' \ + | sed -e 's,guix-manual\.,,' \ + | xargs -n 1 -I{} basename {} .po` +for lang in ${langs}; do + if [ ! -e "doc/guix.${lang}.texi" ]; then + echo "@setfilename guix.${lang}.info" > "doc/guix.${lang}.texi" + echo "@include version-${lang}.texi" >> "doc/guix.${lang}.texi" + # Ensure .po file is newer. + touch "po/doc/guix-manual.${lang}.po" + fi +done + exec autoreconf -vfi diff --git a/doc/contributing.de.texi b/doc/contributing.de.texi deleted file mode 100644 index 6a999baece..0000000000 --- a/doc/contributing.de.texi +++ /dev/null @@ -1,1055 +0,0 @@ -@node Mitwirken -@chapter Mitwirken - -Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um -es wachsen zu lassen! Bitte kontaktieren Sie uns auf -@email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir -freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich -für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der -Erstellung von Paketen (siehe @ref{Paketrichtlinien}). - -@cindex Verhaltensregeln, für Mitwirkende -@cindex Verhaltenskodex für Mitwirkende -Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung -bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten -kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für -Mitwirkende«, der von @url{http://contributor-covenant.org/} übernommen -wurde. Eine übersetzte Fassung finden Sie auf -@url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct} -sowie eine mitgelieferte, englische Fassung in der Datei -@file{CODE-OF-CONDUCT} im Quellbaum. - -Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der -Online-Kommunikation ihre echten Namen preisgeben. Sie können einen -beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden. - -@menu -* Erstellung aus dem Git:: Das Neueste und Beste. -* Guix vor der Installation ausführen:: Hacker-Tricks. -* Perfekt eingerichtet:: Die richtigen Werkzeuge. -* Paketrichtlinien:: Die Distribution wachsen lassen. -* Code-Stil:: Wie Mitwirkende hygienisch arbeiten. -* Einreichen von Patches:: Teilen Sie Ihre Arbeit. -@end menu - -@node Erstellung aus dem Git -@section Erstellung aus dem Git - -Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die -neueste Version aus dem Git-Softwarebestand verwenden: - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den -Installationsanweisungen genannten Paketen weitere nötig (siehe -@ref{Voraussetzungen}). - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}. -@end itemize - -Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist -natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in -der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um -an Guix zu arbeiten: - -@example -guix environment guix -@end example - -In @ref{Aufruf von guix environment} finden Sie weitere Informationen zu -diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc} -hinzugefügt werden: - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -Führen Sie @command{./bootstrap} aus, um die Infrastruktur des -Erstellungssystems mit Autoconf und Automake zu erzeugen. Möglicherweise -erhalten Sie eine Fehlermeldung wie diese: - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden -konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass -@file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile -bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake -in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht -nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden -Befehl aufrufen: - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -In @ref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie -weitere Informationen. - -Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf, -@code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei -@var{Verzeichnis} der von Ihrer aktuellen Installation verwendete -@code{localstatedir}-Wert ist (weitere Informationen siehe @ref{Der Store}). - -Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen -(siehe @ref{Den Testkatalog laufen lassen}). Falls etwas fehlschlägt, werfen Sie -einen Blick auf die Installationsanweisungen (siehe @ref{Installation}) oder -senden Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}. - - -@node Guix vor der Installation ausführen -@section Guix vor der Installation ausführen - -Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im -lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie -tatsächlich zu installieren. So können Sie zwischen Ihrem -Endnutzer-»Straßenanzug« und Ihrem »Faschingskostüm« unterscheiden. - -Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt -werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie -sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix -verfügbar sind (siehe @ref{Erstellung aus dem Git}) und darin einfach vor jeden -Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env} -befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo -es durch @command{./configure} erzeugt wird), zum Beispiel so@footnote{Die -Befehlszeilenoption @option{-E} von @command{sudo} stellt sicher, dass -@code{GUILE_LOAD_PATH} richtig gesetzt wird, damit @command{guix-daemon} und -die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden -können.}: - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt: - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex Lese-Auswerten-Schreiben-Schleife -@dots{} und auf einer REPL (siehe @ref{Using Guile Interactively,,, guile, -Guile Reference Manual}): - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define snakes - (fold-packages - (lambda (package lst) - (if (string-prefix? "python" - (package-name package)) - (cons package lst) - lst)) - '())) -scheme@@(guile-user)> (length snakes) -$1 = 361 -@end example - -Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die -nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und -@env{GUILE_LOAD_PATH}. - -Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum -@emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische -Verknüpfung @file{~/.config/guix/current} (siehe @ref{Aufruf von guix pull}). Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen -@command{git pull} benutzen. - - -@node Perfekt eingerichtet -@section Perfekt eingerichtet - -Um perfekt für das Hacken an Guix eingerichtet zu sein, brauchen Sie an sich -dasselbe wie um perfekt für das Hacken mit Guile (siehe @ref{Using Guile in -Emacs,,, guile, Guile Reference Manual}). Zunächst brauchen Sie mehr als ein -Textverarbeitungsprogramm, Sie brauchen -@url{http://www.gnu.org/software/emacs, Emacs} zusammen mit den vom -wunderbaren @url{http://nongnu.org/geiser/, Geiser} verliehenen Kräften. Um -diese zu installieren, können Sie Folgendes ausführen: - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs -heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu -Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie -kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition -zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr (siehe -@ref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen -Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die -Quelldateien in Ihrem Checkout gefunden werden. - -@lisp -;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten -Scheme-Modus. Aber Sie dürfen auch -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es -bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so -zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken -oder den nachfolgenden S-Ausdruck verwerfen, etc. - -@cindex Code-Schnipsel -@cindex Vorlagen -@cindex Tipparbeit sparen -Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und -Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können -mit @url{http://joaotavora.github.io/yasnippet/, YASnippet} zusammen benutzt -werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln -umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer -@var{yas-snippet-dirs}-Variablen in Emacs hinzufügen. - -@lisp -;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit} -voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine -Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB} -eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines -Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um -eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie -@code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der -Homepage-URI eines Pakets auf HTTPS einzufügen. - -Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie -@code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch -die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter -umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere -Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst -wieder weiter umgeschrieben werden kann. - - -@node Paketrichtlinien -@section Paketrichtlinien - -@cindex Pakete definieren -Die GNU-Distribution ist noch sehr jung und einige Ihrer Lieblingspakete -könnten noch fehlen. Dieser Abschnitt beschreibt, wie Sie dabei helfen -können, die Distribution wachsen zu lassen. - -Pakete mit freier Software werden normalerweise in Form von @dfn{Tarballs -mit dem Quellcode} angeboten — typischerweise in -@file{tar.gz}-Archivdateien, in denen alle Quelldateien enthalten sind. Ein -Paket zur Distribution hinzuzufügen, bedeutet also zweierlei Dinge: Zum -einen fügt man ein @dfn{Rezept} ein, das beschreibt, wie das Paket erstellt -werden kann, einschließlich einer Liste von anderen Paketen, die für diese -Erstellung gebraucht werden, zum anderen fügt man @dfn{Paketmetadaten} zum -Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen. - -In Guix sind all diese Informationen ein Teil der -@dfn{Paketdefinitionen}. In Paketdefinitionen hat man eine abstrahierte, -hochsprachliche Sicht auf das Paket. Sie werden in der Syntax der -Scheme-Programmiersprache verfasst; tatsächlich definieren wir für jedes -Paket eine Variable und binden diese an dessen Definition, um die Variable -anschließend aus einem Modul heraus zu exportieren (siehe @ref{Paketmodule}). Allerdings ist @emph{kein} tiefgehendes Wissen über Scheme -erforderlich, um Pakete zu erstellen. Mehr Informationen über -Paketdefinitionen finden Sie im Abschnitt @ref{Pakete definieren}. - -Eine fertige Paketdefinition kann, nachdem sie in eine Datei im -Quell-Verzeichnisbaum von Guix eingesetzt wurde, mit Hilfe des Befehls -@command{guix build} getestet werden (siehe @ref{Aufruf von guix build}). Wenn -das Paket zum Beispiel den Namen @code{gnew} trägt, können Sie folgenden -Befehl aus dem Erstellungs-Verzeichnisbaum von Guix heraus ausführen (siehe -@ref{Guix vor der Installation ausführen}): - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Wenn Sie @code{--keep-failed} benutzen, ist es leichter, fehlgeschlagene -Erstellungen zu untersuchen, weil dann der Verzeichnisbaum der -fehlgeschlagenen Erstellung zugänglich bleibt. Eine andere nützliche -Befehlszeilenoption bei der Fehlersuche ist @code{--log-file}, womit das -Erstellungsprotokoll eingesehen werden kann. - -Wenn der @command{guix}-Befehl das Paket nicht erkennt, kann es daran -liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine -@code{define-public}-Klausel fehlt, die die Paketvariable exportiert. Um das -herauszufinden, können Sie das Modul aus Guile heraus laden, um mehr -Informationen über den tatsächlichen Fehler zu bekommen: - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte -einen Patch (siehe @ref{Einreichen von Patches}). Wenn Sie dabei Hilfe brauchen -sollten, helfen wir gerne. Ab dem Zeitpunkt, zu dem der Patch als Commit ins -Guix-Repository eingepflegt wurde, wird das neue Paket automatisch durch -@url{http://hydra.gnu.org/jobset/gnu/master, unser System zur -Kontinuierlichen Integration} auf allen unterstützten Plattformen erstellt. - -@cindex Substituierer -Benutzern steht die neue Paketdefinition zur Verfügung, nachdem sie das -nächste Mal @command{guix pull} ausgeführt haben (siehe @ref{Aufruf von guix pull}). Wenn @code{@value{SUBSTITUTE-SERVER}} selbst damit fertig ist, das -Paket zu erstellen, werden bei der Installation automatisch Binärdateien von -dort heruntergeladen (siehe @ref{Substitute}). Menschliches Eingreifen muss -nur stattfinden, um den Patch zu überprüfen und anzuwenden. - - -@menu -* Software-Freiheit:: Was in die Distribution aufgenommen werden - darf. -* Paketbenennung:: Was macht einen Namen aus? -* Versionsnummern:: Wenn der Name noch nicht genug ist. -* Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige - Paket zu finden. -* Python-Module:: Ein Touch britischer Comedy. -* Perl-Module:: Kleine Perlen. -* Java-Pakete:: Kaffeepause. -* Schriftarten:: Schriften verschriftlicht. -@end menu - -@node Software-Freiheit -@subsection Software-Freiheit - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex freie Software -Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der -Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist @dfn{freie Software}, was -bedeutet, dass Benutzer die -@url{http://www.gnu.org/philosophy/free-sw.de.html,vier wesentlichen -Freiheiten} haben: das Programm auszuführen, es zu untersuchen, das Programm -in Form seines Quellcodes anzupassen und exakte Kopien ebenso wie -modifizierte Versionen davon an andere weiterzugeben. Die Pakete, die Sie in -der GNU-Distribution finden, stellen ausschließlich solche Software zur -Verfügung, die Ihnen diese vier Freiheiten gewährt. - -Außerdem befolgt die GNU-Distribution die -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.de.html,Richtlinien -für freie Systemverteilungen}. Unter anderem werden unfreie Firmware sowie -Empfehlungen von unfreier Software abgelehnt und Möglichkeiten zum Umgang -mit Markenzeichen und Patenten werden diskutiert. - -Ansonsten freier Paketquellcode von manchen Anbietern enthält einen kleinen -und optionalen Teil, der diese Richtlinien verletzt. Zum Beispiel kann -dieser Teil selbst unfreier Code sein. Wenn das vorkommt, wird der sie -verletzende Teil mit angemessenen Patches oder Code-Schnipseln innerhalb der -@code{origin}-Form des Pakets entfernt (siehe @ref{Pakete definieren}). Dadurch liefert Ihnen @code{guix build --source} nur den -»befreiten« Quellcode und nicht den unmodifizierten Quellcode des Anbieters. - - -@node Paketbenennung -@subsection Paketbenennung - -@cindex Paketname -Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es -den Namen der @emph{Scheme-Variablen}, der direkt nach @code{define-public} -im Code steht. Mit diesem Namen kann das Paket im Scheme-Code nutzbar -gemacht und zum Beispiel als Eingabe eines anderen Pakets benannt -werden. Zum anderen gibt es die Zeichenkette im @code{name}-Feld einer -Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie -@command{guix package} und @command{guix build} benutzt. - -Meistens sind die beiden identisch und ergeben sich aus einer Umwandlung des -vom Anbieter verwendeten Projektnamens in Kleinbuchstaben, bei der -Unterstriche durch Bindestriche ersetzt werden. Zum Beispiel wird GNUnet -unter dem Paketnamen @code{gnunet} angeboten und SDL_net als @code{sdl-net}. - -An Bibliothekspakete hängen wir vorne kein @code{lib} als Präfix an, solange -es nicht Teil des offiziellen Projektnamens ist. Beachten Sie aber die -Abschnitte @ref{Python-Module} und @ref{Perl-Module}, in denen -Sonderregeln für Module der Programmiersprachen Python und Perl beschrieben -sind. - -Auch Pakete mit Schriftarten werden anders behandelt, siehe @ref{Schriftarten}. - - -@node Versionsnummern -@subsection Versionsnummern - -@cindex Paketversion -Normalerweise stellen wir nur für die neueste Version eines -Freie-Software-Projekts ein Paket bereit. Manchmal gibt es allerdings Fälle -wie zum Beispiel untereinander inkompatible Bibliotheksversionen, so dass -zwei (oder mehr) Versionen desselben Pakets angeboten werden müssen. In -diesem Fall müssen wir verschiedene Scheme-Variablennamen benutzen. Wir -benutzen dann für die neueste Version den Namen, wie er im Abschnitt -@ref{Paketbenennung} festgelegt wird, und geben vorherigen Versionen -denselben Namen mit einem zusätzlichen Suffix aus @code{-} gefolgt vom -kürzesten Präfix der Versionsnummer, mit dem noch immer zwei Versionen -unterschieden werden können. - -Der Name innerhalb der Paketdefinition ist hingegen derselbe für alle -Versionen eines Pakets und enthält keine Versionsnummer. - -Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie -folgt geschrieben werden: - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See , -@c for a discussion of what follows. -@cindex Versionsnummer, bei Snapshots aus Versionskontrolle -Gelegentlich fügen wir auch Pakete für Snapshots aus dem -Versionskontrollsystem des Anbieters statt formaler Veröffentlichungen zur -Distribution hinzu. Das sollte die Ausnahme bleiben, weil die Entwickler -selbst klarstellen sollten, welche Version als die stabile Veröffentlichung -gelten sollte, ab und zu ist es jedoch notwendig. Was also sollten wir dann -im @code{version}-Feld eintragen? - -Offensichtlich muss der Bezeichner des Commits, den wir als Snapshot aus dem -Versionskontrollsystem nehmen, in der Versionszeichenkette zu erkennen sein, -aber wir müssen auch sicherstellen, dass die Version monoton steigend ist, -damit @command{guix package --upgrade} feststellen kann, welche Version die -neuere ist. Weil Commit-Bezeichner, insbesondere bei Git, nicht monoton -steigen, müssen wir eine Revisionsnummer hinzufügen, die wir jedes Mal -erhöhen, wenn wir das Paket auf einen neueren Snapshot aktualisieren. Die -sich ergebende Versionszeichenkette sieht dann so aus: - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- Commit-ID beim Anbieter - | | - | `--- Revisionsnummer des Guix-Pakets - | -die neueste Version, die der Anbieter veröffentlicht hat -@end example - -Es ist eine gute Idee, die Commit-Bezeichner im @code{version}-Feld auf, -sagen wir, 7 Ziffern zu beschränken. Das sieht besser aus (angenommen, das -sollte hier eine Rolle spielen) und vermeidet Probleme, die mit der -maximalen Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Am -besten benutzt man jedoch den vollständigen Commit-Bezeichner in -@code{origin}s, um Mehrdeutigkeiten zu vermeiden. Eine typische -Paketdefinition könnte so aussehen: - -@example -(define mein-paket - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Guix-Paketrevision - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/mein-paket.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Zusammenfassungen und Beschreibungen -@subsection Zusammenfassungen und Beschreibungen - -@cindex Paketbeschreibung -@cindex Paketzusammenfassung -Wie wir bereits gesehen haben, enthält jedes Paket in GNU@tie{}Guix eine (im -Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine -Beschreibung (englisch: Description; siehe @ref{Pakete definieren}). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden -mit @command{guix package --search} durchsucht und stellen eine -entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob -das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler Acht -geben, was sie dort eintragen. - -Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht -mit einem Punkt enden. Sie dürfen nicht mit den Artikeln »a« oder »the« -beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum -Beispiel sollte »File-frobbing tool« gegenüber »A tool that frobs files« -vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim -Paket handelt — z.B.@: »Core GNU utilities (file, text, shell)« —, oder -aussagen, wofür es benutzt wird — z.B.@: ist die Zusammenfassung für -GNU@tie{}grep »Print lines matching a pattern«. - -Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen -Sinn ergeben muss. Zum Beispiel würde »Manipulate alignments in the SAM -format« vielleicht von einem erfahrenen Forscher in der Bioinformatik -verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig -hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es -ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine -Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier -würden sich die Nutzer mit »Manipulate nucleotide sequence alignments« -hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach -sie suchen. - -Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie -vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor -eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie »world-leading« -(»weltweit führend«), »industrial-strength« (»industrietauglich«) und -»next-generation« (»der nächsten Generation«) ebenso wie Superlative wie -»the most advanced« (»das fortgeschrittenste«) — davon haben Nutzer nichts, -wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen -Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und -Funktionalitäten zu erwähnen. - -@cindex Texinfo-Auszeichnungen, in Paketbeschreibungen -Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das -bedeutet, Text kann Verzierungen wie @code{@@code} oder @code{@@dfn}, -Auflistungen oder Hyperlinks enthalten (siehe @ref{Overview,,, texinfo, GNU -Texinfo}). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte -Zeichen wie @samp{@@} und geschweifte Klammern schreiben, weil es sich dabei -um die grundlegenden Sonderzeichen in Texinfo handelt (siehe @ref{Special -Characters,,, texinfo, GNU Texinfo}). Benutzungsschnittstellen wie -@command{guix package --show} kümmern sich darum, solche Auszeichnungen -angemessen darzustellen. - -Zusammenfassungen und Beschreibungen werden von Freiwilligen -@uref{http://translationproject.org/domain/guix-packages.html, beim -Translation Project} übersetzt, damit so viele Nutzer wie möglich sie in -ihrer Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie -in der von der aktuell eingestellten Locale festgelegten Sprache durchsucht -und angezeigt werden. - -Damit @command{xgettext} sie als übersetzbare Zeichenketten extrahieren -kann, @emph{müssen} Zusammenfassungen und Beschreibungen einfache -Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten -nicht mit Prozeduren wie @code{string-append} oder @code{format} -konstruieren können: - -@lisp -(package - ;; @dots{} - (synopsis "This is translatable") - (description (string-append "This is " "*not*" " translatable."))) -@end lisp - -Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso -mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren, -weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den -Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese -sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel -einfügen (siehe @ref{xgettext Invocation,,, gettext, GNU Gettext}): - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Python-Module -@subsection Python-Module - -@cindex python -Zur Zeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils -über die Scheme-Variablen mit den Namen @code{python-2} und @code{python} -zur Verfügung, entsprechend der Erklärungen im Abschnitt @ref{Versionsnummern}. Um Verwirrungen und Namenskollisionen mit anderen -Programmiersprachen zu vermeiden, erscheint es als wünschenswert, dass der -Name eines Pakets für ein Python-Modul auch das Wort @code{python} enthält. - -Manche Module sind nur mit einer Version von Python kompatibel, andere mit -beiden. Wenn das Paket Foo nur mit Python 3 kompiliert werden kann, geben -wir ihm den Namen @code{python-foo}, wenn es nur mit Python 2 kompilierbar -ist, wählen wir den Namen @code{python2-foo}. Ist es mit beiden Versionen -kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen. - -Wenn ein Projekt bereits das Wort @code{python} im Namen hat, lassen wir es -weg; zum Beispiel ist das Modul python-dateutil unter den Namen -@code{python-dateutil} und @code{python2-dateutil} verfügbar. Wenn der -Projektname mit @code{py} beginnt (z.B.@: @code{pytz}), behalten wir ihn bei -und stellen das oben beschriebene Präfix voran. - -@subsubsection Abhängigkeiten angeben -@cindex Eingaben, für Python-Pakete - -Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und -mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des -Paketquellcodes: in der Datei @file{setup.py}, in @file{requirements.txt} -oder in @file{tox.ini}. - -Wenn Sie ein Rezept für ein Python-Paket schreiben, lautet Ihr Auftrag, -diese Abhängigkeiten auf angemessene Arten von »Eingaben« abzubilden (siehe -@ref{»package«-Referenz, inputs}). Obwohl der @code{pypi}-Importer hier -normalerweise eine gute Arbeit leistet (siehe @ref{Aufruf von guix import}), -könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo -welche Abhängigkeit eingeordnet werden sollte. - -@itemize - -@item -Derzeit ist unser Python-2-Paket so geschrieben, dass es @code{setuptools} -und @code{pip} installiert, wie es auch in den Vorgaben zu Python 3.4 -gemacht wird. Sie müssen also keines der beiden als Eingabe angeben. Wenn -Sie es doch tun, wird @command{guix lint} Sie darauf mit einer Warnung -aufmerksam machen. - -@item -Python-Abhängigkeiten, die zur Laufzeit gebraucht werden, stehen im -@code{propagated-inputs}-Feld. Solche werden typischerweise mit dem -Schlüsselwort @code{install_requires} in @file{setup.py} oder in der Datei -@file{requirements.txt} definiert. - -@item -Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B.@: jene, -die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py} -aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in -@code{tests_require} —, stehen in @code{native-inputs}. Die Begründung ist, -dass (1) sie nicht propagiert werden müssen, weil sie zur Laufzeit nicht -gebraucht werden, und (2) wir beim Cross-Kompilieren die »native« Eingabe -des Wirtssystems wollen. - -Beispiele sind die Testrahmen @code{pytest}, @code{mock} und -@code{nose}. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit -benötigt wird, muss es doch in @code{propagated-inputs} stehen. - -@item -Alles, was nicht in die bisher genannten Kategorien fällt, steht in -@code{inputs}, zum Beispiel Programme oder C-Bibliotheken, die zur -Erstellung von Python-Paketen mit enthaltenen C-Erweiterungen gebraucht -werden. - -@item -Wenn ein Python-Paket optionale Abhängigkeiten hat (@code{extras_require}), -ist es Ihnen überlassen, sie hinzuzufügen oder nicht hinzuzufügen, je -nachdem wie es um deren Verhältnis von Nützlichkeit zu anderen Nachteilen -steht (siehe @ref{Einreichen von Patches, @command{guix size}}). - -@end itemize - - -@node Perl-Module -@subsection Perl-Module - -@cindex perl -Eigenständige Perl-Programme bekommen einen Namen wie jedes andere Paket, -unter Nutzung des Namens beim Anbieter in Kleinbuchstaben. Für Perl-Pakete, -die eine einzelne Klasse enthalten, ersetzen wir alle Vorkommen von -@code{::} durch Striche und hängen davor das Präfix @code{perl-} an. Die -Klasse @code{XML::Parser} wird also zu @code{perl-xml-parser}. Module, die -mehrere Klassen beinhalten, behalten ihren Namen beim Anbieter, in -Kleinbuchstaben gesetzt, und auch an sie wird vorne das Präfix @code{perl-} -angehängt. Es gibt die Tendenz, solche Module mit dem Wort @code{perl} -irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes -weggelassen. Zum Beispiel wird aus @code{libwww-perl} bei uns -@code{perl-libwww}. - - -@node Java-Pakete -@subsection Java-Pakete - -@cindex java -Eigenständige Java-Programme werden wie jedes andere Paket benannt, d.h.@: -mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter. - -Um Verwirrungen und Namenskollisionen mit anderen Programmiersprachen zu -vermeiden, ist es wünschenswert, dass dem Namem eines Pakets zu einem -Java-Paket das Präfix @code{java-} vorangestellt wird. Wenn ein Projekt -bereits das Wort @code{java} im Namen trägt, lassen wir es weg; zum Beispiel -befindet sich das Java-Paket @code{ngsjava} in einem Paket namens -@code{java-ngs}. - -Bei Java-Paketen, die eine einzelne Klasse oder eine kleine -Klassenhierarchie enthalten, benutzen wir den Klassennamen in -Kleinbuchstaben und ersetzen dabei alle Vorkommen von @code{.} durch Striche -und setzen das Präfix @code{java-} davor. Die Klasse -@code{apache.commons.cli} wird also zum Paket -@code{java-apache-commons-cli}. - - -@node Schriftarten -@subsection Schriftarten - -@cindex Schriftarten -Wenn Schriftarten in der Regel nicht von Nutzern zur Textbearbeitung -installiert werden oder als Teil eines größeren Software-Pakets mitgeliefert -werden, gelten dafür die allgemeinen Paketrichtlinien für Software. Zum -Beispiel trifft das auf als Teil des X.Org-Systems ausgelieferte -Schriftarten zu, oder auf Schriftarten, die ein Teil von TeX Live sind. - -Damit es Nutzer leichter haben, nach Schriftarten zu suchen, konstruieren -wir die Namen von anderen Paketen, die nur Schriftarten enthalten, nach dem -folgenden Schema, egal was der Paketname beim Anbieter ist. - -Der Name eines Pakets, das nur eine Schriftfamilie enthält, beginnt mit -@code{font-}. Darauf folgt der Name des Schriftenherstellers und ein Strich -@code{-}, sofern bekannt ist, wer der Schriftenhersteller ist, und dann der -Name der Schriftfamilie, in dem Leerzeichen durch Striche ersetzt werden -(und wie immer mit Großbuchstaben statt Kleinbuchstaben). Zum Beispiel -befindet sich die von SIL hergestellte Gentium-Schriftfamilie im Paket mit -dem Namen @code{font-sil-gentium}. - -Wenn ein Paket mehrere Schriftfamilien enthält, wird der Name der Sammlung -anstelle des Schriftfamiliennamens benutzt. Zum Beispiel umfassen die -Liberation-Schriftarten drei Familien: Liberation Sans, Liberation Serif und -Liberation Mono. Man könnte sie getrennt voneinander mit den Namen -@code{font-liberation-sans} und so weiter in Pakete einteilen, da sie aber -unter einem gemeinsamen Namen angeboten werden, packen wir sie lieber -zusammen in ein Paket mit dem Namen @code{font-liberation}. - -Für den Fall, dass mehrere Formate derselben Schriftfamilie oder -Schriftartensammlung in separate Pakete kommen, wird ein Kurzname für das -Format mit einem Strich vorne zum Paketnamen hinzugefügt. Wir benutzen -@code{-ttf} für TrueType-Schriftarten, @code{-otf} für OpenType-Schriftarten -und @code{-type1} für PostScript-Typ-1-Schriftarten. - - -@node Code-Stil -@section Code-Stil - -Im Allgemeinen folgt unser Code den GNU Coding Standards (siehe @ref{Top,,, -standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu -sagen haben, folgen hier einige zusätzliche Regeln. - -@menu -* Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen. -* Module:: Wo Sie Ihren Code unterbringen. -* Datentypen und Mustervergleich:: Implementierung von Datenstrukturen. -* Formatierung von Code:: Schreibkonventionen. -@end menu - -@node Programmierparadigmen -@subsection Programmierparadigmen - -Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine -Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die -grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur -@code{memoize}. - -@node Module -@subsection Module - -Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum -@code{(guix build @dots{})} leben. Sie dürfen auf keine anderen Guix- oder -GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges« -Modul ein erstellungsseitiges Modul benutzt. - -Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum -@code{(gnu @dots{})} und nicht in @code{(guix @dots{})} stehen. - -@node Datentypen und Mustervergleich -@subsection Datentypen und Mustervergleich - -Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu -benutzen, und diese dann »händisch« zu durchlaufen mit @code{car}, -@code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen -Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu -lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern -ist. - -Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit -@code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er -das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen, -besonders mit Listen. - -@node Formatierung von Code -@subsection Formatierung von Code - -@cindex Formatierung von Code -@cindex Code-Stil -Beim Schreiben von Scheme-Code halten wir uns an die üblichen -Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das, -dass wir uns an @url{http://mumble.net/~campbell/scheme/style.txt, -Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses -Dokument auch die Konventionen beschreibt, die im Code von Guile -hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben, -also lesen Sie es bitte. - -Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das -@code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese -sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch -benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens -@code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und -hervorhebt (siehe @ref{Entwicklung,,, emacs-guix, The Emacs-Guix Reference -Manual}). - -@cindex Einrückung, Code- -@cindex Formatierung, Code- -Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor -diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können -Sie auch Folgendes ausführen: - -@example -./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket} -@end example - -@noindent -Dadurch wird die Definition von @var{Paket} in -@file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im -Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen, -lassen Sie das zweite Argument weg: - -@example -./etc/indent-code.el gnu/services/@var{Datei}.scm -@end example - -@cindex Vim, zum Editieren von Scheme-Code -Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set -autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während -Sie ihn schreiben. Außerdem könnte Ihnen -@uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden. - -Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen -Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten -Prozeduren im Namensraum @code{(guix build @dots{})} aufgeweicht werden. - -Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter -haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als -vier Parameter entgegennehmen. - - -@node Einreichen von Patches -@section Einreichen von Patches - -Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git -durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht -unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die -mittels @code{git format-patch} erstellt und an die Mailingliste -@email{guix-patches@@gnu.org} geschickt werden. - -Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist -unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick -über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete -Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine -Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden -kann, wobei @var{NNN} für die Folgenummer steht (siehe @ref{Senden einer Patch-Reihe}). - -Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe @ref{Change -Logs,,, standards, GNU Coding Standards}); dazu finden Sie Beispiele unter -den bisherigen Commits. - -Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder -verändert, gehen Sie bitte diese Prüfliste durch: - -@enumerate -@item -Wenn die Autoren der verpackten Software eine kryptografische Signatur -bzw. Beglaubigung für den Tarball der Veröffentlichung anbieten, so machen -Sie sich bitte die Mühe, die Echtheit des Archivs zu überprüfen. Für eine -abgetrennte GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg ---verify} tun. - -@item -Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für -das Paket zu verfassen. Unter @ref{Zusammenfassungen und Beschreibungen} finden Sie -dazu einige Richtlinien. - -@item -Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder -geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe -@ref{Aufruf von guix lint}). - -@item -Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, -indem Sie @code{guix build @var{Paket}} ausführen. - -@item -Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten -Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware -für diese Plattformen haben, empfehlen wir, den -@code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu -aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste -(»services«) in Ihrer @code{operating-system}-Konfiguration ein: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) - (guix-support? #t))) -@end example - -Rekonfigurieren Sie anschließend Ihr System. - -Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die -Befehlszeilenoption @code{--system} angeben. Um zum Beispiel das Paket -»hello« für die Architekturen armhf, aarch64 oder mips64 erstellen zu -lassen, würden Sie jeweils die folgenden Befehle angeben: -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex gebündelt -Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird, -die bereits in separaten Paketen zur Verfügung steht. - -Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um -Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir -jedoch sicherstellen, dass solche Pakete die schon in der Distribution -verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der -Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt -und gespeichert) als auch der Distribution die Möglichkeit gegeben, -ergänzende Änderungen durchzuführen, um beispielsweise -Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort -einzuspielen, die aber das gesamte System betreffen — gebündelt -mitgelieferte Kopien würden dies verhindern. - -@item -Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe -@ref{Aufruf von guix size}). Dadurch können Sie Referenzen auf andere Pakete -finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu -entscheiden, ob das Paket aufgespalten werden sollte (siehe @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet -werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere -vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie -stattdessen @code{texlive-tiny} oder @code{texlive-union}. - -@item -Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls -vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh ---list-dependent @var{Paket}} hilft Ihnen dabei (siehe @ref{Aufruf von guix refresh}). - -@c See . -@cindex Branching-Strategie -@cindex Neuerstellungs-Zeitplan -Je nachdem, wieviele abhängige Pakete es gibt, und entsprechend wieviele -Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches -statt, nach ungefähr diesen Regeln: - -@table @asis -@item 300 abhängige Pakete oder weniger -@code{master}-Branch (störfreie Änderungen). - -@item zwischen 300 und 1200 abhängige Pakete -@code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle -3 Wochen mit @code{master} zusammengeführt. Themenbezogene Änderungen -(z.B.@: eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf -einem eigenen Branch umgesetzt werden (wie @code{gnome-updates}). - -@item mehr als 1200 abhängige Pakete -@code{core-updates}-Branch (kann auch größere und womöglich andere Software -beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in -@code{master} alle 2,5 Monate oder so gemerget. -@end table - -All diese Branches werden kontinuierlich -@uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} erstellt -und in @code{master} gemerget, sobald alles erfolgreich erstellt worden -ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, -und zudem das Zeitfenster, während dessen noch keine vorerstellten -Binärdateien verfügbar sind, verkürzen. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich} -angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender -@code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder -IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden -sollte. - -@item -@cindex Determinismus, von Erstellungsprozessen -@cindex Reproduzierbare Erstellungen, Überprüfung -Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen -Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe -Ergebnis wie Ihre Erstellung hat, Bit für Bit. - -Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male -hintereinander auf Ihrer Maschine erstellen (siehe @ref{Aufruf von guix build}): - -@example -guix build --rounds=2 mein-paket -@end example - -Dies reicht aus, um eine ganze Klasse häufiger Ursachen von -Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder -zufallsgenerierte Ausgaben im Ergebnis der Erstellung. - -Eine weitere Möglichkeit ist, @command{guix challenge} (siehe @ref{Aufruf von guix challenge}) zu benutzen. Sie können es ausführen, sobald ein Paket -commitet und von @code{@value{SUBSTITUTE-SERVER}} erstellt wurde, um zu -sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser: -Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen -Sie @command{guix publish} aus. Da sich die entfernte Erstellungsmaschine -wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme -durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum -Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem -Betriebssystem-Kernel — zum Beispiel, indem @code{uname} oder -@file{/proc}-Dateien verwendet werden. - -@item -Beim Schreiben von Dokumentation achten Sie bitte auf eine -geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie -@uref{https://en.wikipedia.org/wiki/Singular_they, »they«@comma{} -»their«@comma{} »them« im Singular} und so weiter. - -@item -Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger -Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen -erschwert und bremst das Durchsehen Ihres Patches. - -Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer -Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version -zusammen mit Fehlerbehebungen für das Paket. - -@item -Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich -wollen Sie dies automatisch tun lassen durch das Skript -@command{etc/indent-code.el} (siehe @ref{Formatierung von Code}). - -@item -Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe -@ref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine -automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer -identisch von einer Generation auf die nächste, daher ist es in diesem Fall -besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie -@emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht -wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr. - -@end enumerate - -Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch -an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den -Befehl @command{git send-email} benutzen (siehe @ref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten, -entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu -angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie -Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich -nicht mehr funktionieren. - -Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem -Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden. - -@unnumberedsubsec Senden einer Patch-Reihe -@anchor{Senden einer Patch-Reihe} -@cindex Patch-Reihe -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -Wenn Sie eine Patch-Reihe senden (z.B.@: mit @code{git send-email}), -schicken Sie bitte als Erstes eine Nachricht an -@email{guix-patches@@gnu.org} und dann nachfolgende Patches an -@email{@var{NNN}@@debbugs.gnu.org}, um sicherzustellen, dass sie zusammen -bearbeitet werden. Siehe @uref{https://debbugs.gnu.org/Advanced.html, die -Debbugs-Dokumentation} für weitere Informationen. diff --git a/doc/contributing.es.texi b/doc/contributing.es.texi deleted file mode 100644 index 05299173b6..0000000000 --- a/doc/contributing.es.texi +++ /dev/null @@ -1,1016 +0,0 @@ -@node Contribuir -@chapter Contribuir - -Este proyecto es un esfuerzo colaborativo, y ¡necesitamos su ayuda para que -crezca! Por favor, contacte con nosotras en @email{guix-devel@@gnu.org} y en -@code{#guix} en la red IRC Freenode. Estamos abiertas a ideas, informes de -errores, parches y cualquier cosa que pueda ser de ayuda para el -proyecto. Especialmente se agradece ayuda en empaquetamiento -(@pxref{Guías de empaquetamiento}). - -@cindex código de conducta, de contribuidoras -@cindex acuerdo de contribución -Queremos proporcionar un entorno cálido, amistoso y libre de acoso, para que -cualquiera pueda contribuir al máximo de sus capacidades. Para este fin -nuestro proyecto usa un ``Acuerdo de Contribución'', que fue adaptado de -@url{http://contributor-coventant.org}. Se puede encontrar una versión local -en el fichero @file{CODE-OF-CONDUCT} del árbol de fuentes. - -Las contribuidoras no están obligadas a usar su nombre legal en los parches -ni en la comunicación on-line; pueden usar cualquier nombre o seudónimo de -su elección. - -@menu -* Construcción desde Git:: Lo último y mejor. -* Ejecución de Guix antes de estar instalado:: Trucos de hacker. -* La configuración perfecta:: Las herramientas adecuadas. -* Guías de empaquetamiento:: Crecimiento de la distribución. -* Estilo de codificación:: Higiene de la contribuidora. -* Envío de parches:: Comparta su trabajo. -@end menu - -@node Construcción desde Git -@section Construcción desde Git - -Si quiere picar en el mismo Guix se recomienda usar la última versión del -repositorio Git: - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -Cuando se compila Guix de una copia de trabajo local (checkout), se -requieren los siguientes paquetes, además de los mencionados en las -instrucciones de instalación (@pxref{Requisitos}). - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (opcional)}. -@end itemize - -El modo más fácil de preparar un entorno de desarrollo para Guix es, por -supuesto, ¡usando Guix! Las siguientes órdenes inician un nuevo intérprete -donde todas las dependencias y las variables de entorno apropiadas están -listas para picar código en Guix: - -@example -guix environment guix -@end example - -@xref{Invocación de guix environment}, para más información sobre esa orden. Se -pueden añadir dependencias adicionales con la opción @option{--ad-hoc}: - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -Ejecute @command{./bootstrap} para generar la infraestructura del sistema de -construcción usando Autoconf y Automake. Si obtiene un error como este: - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -probablemente significa que Autoconf no pudo encontrar el fichero pkg.m4, -que proporciona pkg-config. Asegurese de que @file{pkg.m4} está -disponible. Lo mismo aplica para el conjunto de macros @file{guile.m4} que -proporciona Guile. Por ejemplo, si ha instalado Automake en -@file{/usr/local}, no va a buscar ficheros @file{.m4} en -@file{/usr/share}. En ese caso tiene que ejecutar la siguiente orden: - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -@xref{Macro Search Path,,, automake, The GNU Automake Manual} para más -información. - -Entonces, ejecute @command{./configure} como siempre. Asegurese de pasar -@code{--localstatedir=@var{directorio}}, donde @var{directorio} es el valor -de @code{localstatedir} usado por su instalación actual (@pxref{El almacén}, -para información sobre esto). - -Finalmente, tiene que ejecutar @code{make check} para iniciar las pruebas -(@pxref{Ejecución de la batería de pruebas}). Si algo falla, eche un vistazo a las -instrucciones de instalación (@pxref{Instalación}) o envíe un mensaje---en -Inglés---a la @email{guix-devel@@gnu.org, lista de correo}. - - -@node Ejecución de Guix antes de estar instalado -@section Ejecución de Guix antes de estar instalado - -Para mantener un entorno de trabajo estable, encontrará útil probar los -cambios hechos en su copia de trabajo local sin instalarlos realmente. De -esa manera, puede distinguir entre su sombrero de ``usuaria final'' y el -traje de ``harapos''. - -Para dicho fin, todas las herramientas de línea de órdenes pueden ser usadas -incluso si no ha ejecutado @code{make install}. Para hacerlo, primero -necesita tener un entorno con todas las dependencias disponibles -(@pxref{Construcción desde Git}), y entonces añada al inicio de cada orden -@command{./pre-inst-env} (el guión @file{pre-inst-env} se encuentra en la -raíz del árbol de compilación de Guix, como en@footnote{La opción -@option{-E} a @command{sudo} asegura que @code{GUILE_LOAD_PATH} contiene la -información correcta para que @command{guix-daemon} y las herramientas que -usa puedan encontrar los módulos Guile que necesitan.}: - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -De manera similar, para una sesión de Guile que use los módulos Guix: - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex entorno interactivo -@dots{} y para un entorno interactivo (REPL) (@pxref{Using Guile -Interactively,,, guile, Guile Reference Manual}): - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define serpientes - (fold-packages - (lambda (paquete lst) - (if (string-prefix? "python" - (package-name paquete)) - (cons paquete lst) - lst)) - '())) -scheme@@(guile-user)> (length serpientes) -$1 = 361 -@end example - -El guión @command{pre-inst-env} fija todas las variables de entorno -necesarias para permitir esto, incluyendo @env{PATH} y -@env{GUILE_LOAD_PATH}. - -Fíjese que la orden @command{./pre-inst-env guix pull} @emph{no} actualiza -el árbol de fuentes local; simplemente actualiza el enlace -@file{~/.config/guix/latest} (@pxref{Invocación de guix pull}). Ejecute -@command{git pull} si quiere actualizar su árbol de fuentes local. - - -@node La configuración perfecta -@section La configuración perfecta - -La configuración perfecta para hackear en Guix es básicamente la -configuración perfecta para hacerlo en Guile (@pxref{Using Guile in Emacs,,, -guile, Guile Reference Manual}). Primero, necesita más que un editor, -necesita @url{http://www.gnu.org/software/emacs, Emacs}, empoderado por el -maravilloso @url{http://nongnu.org/geiser, Geiser}. Para configurarlo, -ejecute: - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser permite desarrollo incremental e interactivo dentro de Emacs: -compilación y evaluación de código dentro de los buffers, acceso a -documentación en línea (docstrings), completado dependiente del contexto, -@kbd{M-.} para saltar a la definición de un objeto, una consola interactiva -(REPL) para probar su código, y más (@pxref{Introducción,,, geiser, Geiser -User Manual}). Para desarrollar Guix adecuadamente, asegúrese de aumentar la -ruta de carga de Guile (load-path) para que encuentre los ficheros fuente de -su copia de trabajo: - -@lisp -;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -Para realmente editar el código, Emacs tiene un modo limpio para -Scheme. Pero además de eso, no debe perderse -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Provee de facilidades -para operar directamente en el árbol sintáctico como elevar una expresión S -o recubrirla, embeber o expulsar la siguiente expresión S, etc. - -@cindex fragmentos de código -@cindex plantillas -@cindex reducir la verborrea -También proporcionamos plantillas para los mensajes de revisión de git -comunes y definiciones de paquetes en el directorio -@file{etc/snippets}. Estas plantillas pueden ser usadas con -@url{http://joaotavora.github.io/yasnippet, YASnippet} para expandir -mnemotécnicos a fragmentos interactivos de texto. Puedes querer añadir el -directorio de fragmentos a la variable @var{yas-snippet-dirs} en Emacs. - -@lisp -;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -Los fragmentos de mensajes de la revisión dependen de -@url{https://magit.vc/, Magit} para mostrar los ficheros preparados. En la -edición del mensaje de la revisión teclee @code{add} seguido de @kbd{TAB} -(el tabulador) para insertar la plantilla del mensaje de la revisión de -adición de un paquete; teclee @code{update} seguido de @kbd{TAB} para -insertar una plantilla de actualización de un paquete; teclee @code{https} -seguido de @kbd{TAB} para insertar una plantilla para cambiar la URI de la -página de un paquete a HTTPS. - -El fragmento principal para @code{scheme-mode} es activado al teclear -@code{package...} seguido de @kbd{TAB}. Este fragmento también inserta el -lanzador @code{origin...} que puede ser expandido de nuevo. El fragmento -@code{origin} puede a su vez insertar otros identificadores de lanzado -terminando en @code{...}, que pueden ser expandidos de nuevo. - - -@node Guías de empaquetamiento -@section Guías de empaquetamiento - -@cindex paquetes, creación -La distribución GNU es reciente y puede no disponer de alguno de sus -paquetes favoritos. Esta sección describe cómo puede ayudar a hacer crecer -la distribución. - -Los paquetes de software libre habitualmente se distribuyen en forma de -@dfn{archivadores de código fuente}---típicamente ficheros @file{tar.gz} que -contienen todos los ficheros fuente. Añadir un paquete a la distribución -significa esencialmente dos cosas: añadir una @dfn{receta} que describe cómo -construir el paquete, la que incluye una lista de otros paquetes necesarios -para la construcción, y añadir @dfn{metadatos del paquete} junto a dicha -receta, como la descripción y la información de licencias. - -En Guix toda esta información está contenida en @dfn{definiciones de -paquete}. Las definiciones de paquete proporcionan una vista de alto nivel -del paquete. Son escritas usando la sintaxis del lenguaje de programación -Scheme; de hecho, definimos una variable por cada paquete enlazada a su -definición y exportamos esa variable desde un módulo (@pxref{Módulos de paquetes}). No obstante, un conocimiento profundo de Scheme @emph{no} es un -pre-requisito para la creación de paquetes. Para más información obre las -definiciones de paquetes, @pxref{Definición de paquetes}. - -Una vez que una definición de paquete está en su lugar, almacenada en un -fichero del árbol de fuentes de Guix, puede probarse usando la orden -@command{guix build} (@pxref{Invocación de guix build}). Por ejemplo, asumiendo -que el nuevo paquete se llama @code{gnuevo}, puede ejecutar esta orden desde -el árbol de construcción de Guix (@pxref{Ejecución de Guix antes de estar instalado}): - -@example -./pre-inst-env guix build gnuevo --keep-failed -@end example - -El uso de @code{--keep-failed} facilita la depuración de errores de -construcción ya que proporciona acceso al árbol de la construcción -fallida. Otra opción útil de línea de órdenes para la depuración es -@code{--log-file}, para acceder al log de construcción. - -Si el paquete resulta desconocido para la orden @command{guix}, puede ser -que el fichero fuente contenga un error de sintaxis, o no tenga una cláusula -@code{define-public} para exportar la variable del paquete. Para encontrar -el problema puede cargar el módulo desde Guile para obtener más información -sobre el error real: - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnuevo))' -@end example - -Una vez que se construya correctamente su paquete, por favor, envíenos un -parche (@pxref{Envío de parches}). En cualquier caso, si necesita ayuda -también estaremos felices de ayudarle. Una vez el parche se haya incorporado -al repositorio de Guix, el nuevo paquete se construye automáticamente en las -plataformas disponibles por @url{http://hydra.gnu.org/jobset/gnu/master, -nuestro sistema de integración continua}. - -@cindex servidor de sustituciones -Las usuarias pueden obtener la nueva definición de paquete ejecutando -simplemente @command{guix pull} (@pxref{Invocación de guix pull}). Cuando -@code{@value{SUBSTITUTE-SERVER}} ha terminado de construir el paquete, la -instalación del paquete descarga automáticamente los binarios desde allí -(@pxref{Sustituciones}). El único lugar donde la intervención humana es -necesaria es en la revisión y aplicación del parche. - - -@menu -* Libertad del software:: Qué puede entrar en la distribución. -* Nombrado de paquetes:: ¿Qué hay en un nombre? -* Versiones numéricas:: Cuando el nombre no es suficiente. -* Sinopsis y descripciones:: Ayudar a las usuarias a encontrar el paquete - adecuado. -* Módulos Python:: Un toque de comedia británica. -* Módulos Perl:: Pequeñas perlas. -* Paquetes Java:: La parada del café. -* Tipografías:: Amor por las letras. -@end menu - -@node Libertad del software -@subsection Libertad del software - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex software libre -El sistema operativo GNU se ha desarrollado para que las usuarias puedan -ejercitar su libertad de computación. GNU es @dfn{software libre}, lo que -significa ue las usuarias tienen las -@url{http://www.gnu.org/philosophy/free-sw.html,cuatro libertades -esenciales}: para ejecutar el programa, para estudiar y modificar el -programa en la forma de código fuente, para redistribuir copias exactas y -para distribuir versiones modificadas. Los paquetes encontrados en la -distribución GNU proporcionan únicamente software que permite estas cuatro -libertades. - -Además, la distribución GNU sigue las -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,directrices -de distribución de software libre}. Entre otras cosas, estas directrices -rechazan firmware no-libre, recomendaciones de software no-libre y el -tratamiento de formas de tratar con marcas registradas y patentes. - -Algunos paquetes originales, que serían de otra manera software libre, -contienen un subconjunto pequeño y opcional que viola estas directrices, por -ejemplo debido a que ese subconjunto sea en sí código no-libre. Cuando esto -sucede, las partes indeseadas son eliminadas con parches o fragmentos de -código en la forma @code{origin} del paquete (@pxref{Definición de paquetes}). De -este modo, @code{guix build --source} devuelve las fuentes ``liberadas'' en -vez de la versión original de las fuentes. - - -@node Nombrado de paquetes -@subsection Nombrado de paquetes - -@cindex nombre de paquete -Un paquete tiene realmente dos nombres asociados con él: Primero, el nombre -de la @emph{variable Scheme} asociada, que aparece después de -@code{define-public}. A través de este nombre, el paquete está disponible en -código Scheme, por ejemplo como entrada de otro paquete. Segundo, la cadena -en el campo @code{name} de la definición de paquete. Este nombre se usa por -las órdenes de gestión de paquetes como @command{guix package} y -@command{guix build}. - -Ambos normalmente son iguales y corresponden a la conversión a minúsculas -del nombre de proyecto elegido por sus creadoras, con los guiones bajos -sustituidos por guiones. Por ejemplo, GNUnet está disponible como -@code{gnunet}, y SDL_net como @code{sdl-net}. - -No añadimos prefijos @code{lib} para paquetes de bibliotecas, a menos que -sean parte del nombre oficial del proyecto. Pero vea @ref{Módulos Python} y -@ref{Módulos Perl} para reglas especiales que conciernen a los módulos de -los lenguajes Python y Perl. - -Los nombres de paquetes de tipografías se manejan de forma diferente, -@pxref{Tipografías}. - - -@node Versiones numéricas -@subsection Versiones numéricas - -@cindex versión de paquete -Normalmente empaquetamos únicamente la última versión de un proyecto dado de -software libre. Pero a veces, por ejemplo para versiones de bibliotecas -incompatibles, se necesitan dos (o más) versiones del mismo paquete. Estas -necesitan nombres diferentes para las variables Scheme. Usamos el nombre -como se define en @ref{Nombrado de paquetes} para la versión más reciente; las -versiones previas usan el mismo nombre, añadiendo un @code{-} y el prefijo -menor del número de versión que permite distinguir las dos versiones. - -El nombre dentro de la definición de paquete es el mismo para todas las -versiones de un paquete y no contiene ningún número de versión. - -Por ejemplo, las versiones 2.24.20 y 3.9.12 de GTK+ pueden empaquetarse como -sigue: - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -Si también deseásemos GTK+3.8.2, se empaquetaría como -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See , -@c for a discussion of what follows. -@cindex número de versión, para revisiones de VCS -De manera ocasional, empaquetamos instantáneas del sistema de control de -versiones (VCS) de las desarrolladoras originales en vez de publicaciones -formales. Esto debería permanecer como algo excepcional, ya que son las -desarrolladoras originales quienes deben clarificar cual es la entrega -estable. No obstante, a veces es necesario. Por tanto, ¿qué deberíamos poner -en el campo @code{version}? - -Claramente, tenemos que hacer visible el identificador de la revisión en el -VCS en la cadena de versión, pero tamién debemos asegurarnos que la cadena -de versión incrementa monotónicamente de manera que @command{guix package ---upgrade} pueda determinar qué versión es más moderna. Ya que los -identificadores de revisión, notablemente en Git, no incrementan -monotónicamente, añadimos un número de revisión que se incrementa cada vez -que actualizamos a una nueva instantánea. La versión que resulta debería ser -así: - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- ID de revisión original - | | - | `--- revisión del paquete Guix - | -última versión de publicación -@end example - -Es una buena idea recortar los identificadores de revisión en el campo -@code{version} a, digamos, 7 dígitos. Esto evita una molestia estética -(asumiendo que la estética tiene importancia aquí) así como problemas -relacionados con los límites del sistema operativo como la longitud máxima -de una cadena de ejecución #! (127 bytes en el núcleo Linux). Es mejor usar -el identificador de revisión completo en @code{origin}, no obstante, para -evitar ambigüedades. Una definición típica de paquete sería así: - -@example -(define mi-paquete - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Revisión Guix del paquete - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/mi-paquete.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Sinopsis y descripciones -@subsection Sinopsis y descripciones - -@cindex descripción de paquete -@cindex sinopsis de paquete -Como hemos visto previamente, cada paquete en GNU@tie{}Guix incluye una -sinopsis y una descripción (@pxref{Definición de paquetes}). Las sinopsis y -descripciones son importantes: son en lo que @command{guix package --search} -busca, y una pieza crucial de información para ayudar a las usuarias a -determinar si un paquete dado cubre sus necesidades. Consecuentemente, las -empaquetadoras deben prestar atención a qué se incluye en ellas. - -Las sinopsis deben empezar con mayúscula y no deben terminar con punto. No -deben empezar con un artículo que habitualmente no aporta nada; por ejemplo, -se prefiere ``Herramienta para chiribizar'' sobre ``Una herramienta que -chiribiza ficheros''. La sinopsis debe decir qué es el paquete---por -ejemplo, ``Utilidades básicas GNU (ficheros, texto, shell)''---o para qué se -usa---por ejemplo, la sinopsis de GNU@tie{}grep es ``Imprime líneas que -aceptadas por un patrón''. - -Tenga en cuenta que las sinopsis deben tener un claro significado para una -audiencia muy amplia. Por ejemplo, ``Manipula la alineación en el formato -SAM'' puede tener sentido para una investigadora de bioinformática con -experiencia, pero puede ser de poca ayuda o incluso llevar a confusión a una -audiencia no-especializada. Es una buena idea proporcionar una sinopsis que -da una idea del dominio de aplicación del paquete. En ese ejemplo, esto -podría ser algo como ``Manipula la alineación de secuencias de -nucleótidos'', lo que esperablemente proporciona a la usuaria una mejor idea -sobre si esto es lo que está buscando. - -Las descripciones deben tener entre cinco y diez líneas. Use frases -completas, y evite usar acrónimos sin introducirlos previamente. Por favor -evite frases comerciales como ``líder mundial'', ``de potencia industrial'' -y ``siguiente generación'', y evite superlativos como ``el más -avanzado''---no son útiles para las usuarias que buscan un paquete e incluso -pueden sonar sospechosas. En vez de eso, intente ceñirse a los hechos, -mencionando casos de uso y características. - -@cindex marcado Texinfo, en descripciones de paquetes -Las descripciones pueden incluir marcado Texinfo, lo que es útil para -introducir ornamentos como @code{@@code} o @code{@@dfn}, listas de puntos o -enlaces (@pxref{Overview,,, texinfo, GNU Texinfo}). Por consiguiente, debe -ser cuidadosa cuando use algunos caracteres, por ejemplo @samp{@@} y llaves, -que son los caracteres especiales básicos en Texinfo (@pxref{Special -Characters,,, texinfo, GNU Texinfo}). Las interfaces de usuaria como -@command{guix package --show} se encargan de su correcta visualización. - -Las sinopsis y descripciones son traducidas por voluntarias -@uref{http://translationproject.org/domain/guix-packages.html, en -Translation Project} para que todas las usuarias posibles puedan leerlas en -su lengua nativa. Las interfaces de usuaria las buscan y las muestran en el -idioma especificado por la localización actual. - -Para permitir a @command{xgettext} extraerlas como cadenas traducibles, las -sinopsis y descripciones @emph{deben ser cadenas literales}. Esto significa -que no puede usar @code{string-append} o @code{format} para construir estas -cadenas: - -@lisp -(package - ;; @dots{} - (synopsis "Esto es traducible") - (description (string-append "Esto " "*no*" " es traducible."))) -@end lisp - -La traducción requiere mucho trabajo, por lo que, como empaquetadora, le -rogamos que ponga incluso más atención a sus sinopsis y descripciones ya que -cada cambio puede suponer trabajo adicional para las traductoras. Para -ayudarlas, es posible hacer recomendaciones o instrucciones insertando -comentarios especiales como este (@pxref{xgettext Invocation,,, gettext, GNU -Gettext}): - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Módulos Python -@subsection Módulos Python - -@cindex python -Actualmente empaquetamos Python 2 y Python 3, bajo los nombres de variable -Scheme @code{python-2} y @code{python} como se explica en @ref{Versiones numéricas}. Para evitar confusiones y conflictos de nombres con otros -lenguajes de programación, parece deseable que el nombre de paquete para un -módulo Python contenga la palabra @code{python}. - -Algunos módulos son compatibles únicamente con una versión de Python, otros -con ambas. Si el paquete Foo compila sólo con Python 3, lo llamamos -@code{python-foo}; si compila sólo con Python 2, lo llamamos -@code{python2-foo}. Si es compatible con ambas versiones, creamos dos -paquetes con los nombres correspondientes. - -Si un proyecto ya contiene la palabra @code{python}, la eliminamos; por -ejemplo, el módulo python-dateutil se empaqueta con los nombres -@code{python-dateutil} y @code{python2-dateutil}. Si el nombre del proyecto -empieza con @code{py} (por ejemplo @code{pytz}), este se mantiene y el -prefijo es el especificado anteriormente.. - -@subsubsection Especificación de dependencias -@cindex entradas, para paquetes Python - -La información de dependencias para paquetes Python está disponible -habitualmente en el árbol de fuentes, con varios grados de precisión: en el -fichero @file{setup.py}, en @file{requirements.txt} o en @file{tox.ini}. - -Su misión, cuando escriba una receta para un paquete Python, es asociar -estas dependencias con el tipo apropiado de ``entrada'' (@pxref{Referencia de ``package'', inputs}). Aunque el importador de @code{pypi} normalmente hace un -buen trabajo (@pxref{Invocación de guix import}), puede querer comprobar la -siguiente lista para determinar qué dependencia va dónde. - -@itemize - -@item -Actualmente empaquetamos con @code{setuptools} y @code{pip} instalados como -Python 3.4 tiene por defecto. Por tanto no necesita especificar ninguno de -ellos como entrada. @command{guix lint} le avisará si lo hace. - -@item -Las dependencias Python requeridas en tiempo de ejecución van en -@code{propagated-inputs}. Típicamente están definidas con la palabra clave -@code{install_requires} en @file{setup.py}, o en el fichero -@file{requirements.txt}. - -@item -Los paquetes Python requeridos únicamente durante la construcción---por -ejemplo, aquellos listados con la palabra clave @code{setup_requires} en -@file{setup.py}---o únicamente para pruebas---por ejemplo, aquellos en -@code{tests_require}---van en @code{native-inputs}. La razón es que (1) no -necesitan ser propagados ya que no se requieren en tiempo de ejecución, y -(2) en un entorno de compilación cruzada lo que necesitamos es la entrada -``nativa''. - -Ejemplos son las bibliotecas de pruebas @code{pytest}, @code{mock} y -@code{nose}. Por supuesto, si alguno de estos paquetes también se necesita -en tiempo de ejecución, necesita ir en @code{propagated-inputs}. - -@item -Todo lo que no caiga en las categorías anteriores va a @code{inputs}, por -ejemplo programas o bibliotecas C requeridas para construir los paquetes -Python que contienen extensiones C. - -@item -Si un paquete Python tiene dependencias opcionales (@code{extras_require}), -queda en su mano decidir si las añade o no, en base a la relación -utilidad/sobrecarga (@pxref{Envío de parches, @command{guix size}}). - -@end itemize - - -@node Módulos Perl -@subsection Módulos Perl - -@cindex perl -Los programas ejecutables Perl se nombran como cualquier otro paquete, -mediante el uso del nombre oficial en minúsculas. Para paquetes Perl que -contienen una única clase, usamos el nombre en minúsculas de la clase, -substituyendo todas las ocurrencias de @code{::} por guiones y agregando el -prefijo @code{perl-}. Por tanto la clase @code{XML::Parser} se convierte en -@code{perl-xml-parser}. Los módulos que contienen varias clases mantienen su -nombre oficial en minúsculas y también se agrega @code{perl-} al -inicio. Dichos módulos tienden a tener la palabra @code{perl} en alguna -parte de su nombre, la cual se elimina en favor del prefijo. Por ejemplo, -@code{libwww-perl} se convierte en @code{perl-libwww}. - - -@node Paquetes Java -@subsection Paquetes Java - -@cindex java -Los programas Java ejecutables se nombran como cualquier otro paquete, -mediante el uso del nombre oficial en minúsculas. - -Para evitar confusión y colisiones de nombres con otros lenguajes de -programación, es deseable que el nombre del paquete para un paquete Java -contenga el prefijo @code{java-}. Si el proyecto ya tiene la palabra -@code{java}, eliminamos esta; por ejemplo, el paquete @code{ngsjaga} se -empaqueta bajo el nombre @code{java-ngs}. - -Para los paquetes Java que contienen una clase única o una jerarquía -pequeña, usamos el nombre de clase en minúsculas, substituyendo todas las -ocurrencias de @code{.} por guiones y agregando el prefijo @code{java-}. Por -tanto la clase @code{apache.commons.cli} se convierte en el paquete -@code{java-apache-commons-cli}. - - -@node Tipografías -@subsection Tipografías - -@cindex tipografías -Para tipografías que no se instalan generalmente por una usuaria para -propósitos tipográficos, o que se distribuyen como parte de un paquete de -software más grande, seguimos las reglas generales de empaquetamiento de -software; por ejemplo, esto aplica a las tipografías distribuidas como parte -del sistema X.Org o las tipografías que son parte de TeX Live. - -Para facilitar a las usuarias la búsqueda de tipografías, los nombres para -otros paquetes que contienen únicamente tipografías se construyen como -sigue, independientemente del nombre de paquete oficial. - -El nombre de un paquete que contiene únicamente una familia tipográfica -comienza con @code{font-}; seguido por el nombre de la tipografía y un guión -si la tipografía es conocida, y el nombre de la familia tipográfica, donde -los espacios se sustituyen por guiones (y como es habitual, todas las letras -mayúsculas se transforman a minúsculas). Por ejemplo, la familia de -tipografías Gentium de SIL se empaqueta bajo el nombre de -@code{font-sil-gentium}. - -Para un paquete que contenga varias familias tipográficas, el nombre de la -colección se usa en vez del nombre de la familia tipográfica. Por ejemplo, -las tipografías Liberation consisten en tres familias: Liberation Sans, -Liberation Serif y Liberation Mono. Estas se podrían empaquetar por separado -bajo los nombres @code{font-liberation-sans}, etcétera; pero como se -distribuyen de forma conjunta bajo un nombre común, preferimos empaquetarlas -conjuntamente como @code{font-liberation}. - -En el caso de que varios formatos de la misma familia o colección -tipográfica se empaqueten de forma separada, una forma corta del formato, -precedida por un guión, se añade al nombre del paquete. Usamos @code{-ttf} -para tipografías TrueType, @code{-otf} para tipografías OpenType y -@code{-type1} para tipografías Tipo 1 PostScript. - - -@node Estilo de codificación -@section Estilo de codificación - -En general nuestro código sigue los Estándares de codificación GNU -(@pxref{Top,,, standards, GNU Coding Standards}). No obstante, no dicen -mucho de Scheme, así que aquí están algunas reglas adicionales. - -@menu -* Paradigma de programación:: Cómo componer sus elementos. -* Módulos:: ¿Dónde almacenar su código? -* Tipos de datos y reconocimiento de patrones:: Implementación de - estructuras de datos. -* Formato del código:: Convenciones de escritura. -@end menu - -@node Paradigma de programación -@subsection Paradigma de programación - -El código scheme en Guix está escrito en un estilo puramente funcional. Una -excepción es el código que incluye entrada/salida, y procedimientos que -implementan conceptos de bajo nivel, como el procedimiento @code{memoize}. - -@node Módulos -@subsection Módulos - -Los módulos Guile que están destinados a ser usados en el lado del -constructor deben encontrarse en el espacio de nombres @code{(guix build -@dots{})}. No deben hacer referencia a otros módulos Guix o GNU. No -obstante, no hay problema en usar un módulo del lado del constructor en un -módulo ``del lado del cliente''. - -Los módulos que tratan con el sistema GNU más amplio deben estar en el -espacio de nombres @code{(gnu @dots{})} en vez de en @code{(guix @dots{})}. - -@node Tipos de datos y reconocimiento de patrones -@subsection Tipos de datos y reconocimiento de patrones - -La tendencia en el Lisp clásico es usar listas para representar todo, y -recorrerlas ``a mano'' usando @code{car}, @code{cdr}, @code{cadr} y -compañía. Hay varios problemas con este estilo, notablemente el hecho de que -es difícil de leer, propenso a errores y una carga para informes adecuados -de errores de tipado. - -El código de Guix debe definir tipos de datos apropiados (por ejemplo, -mediante el uso @code{define-record-type*}) en vez de abusar de las -listas. Además debe usarse el reconocimiento de patrones, vía el módulo de -Guile @code{(ice-9 match)}, especialmente cuando se analizan listas. - -@node Formato del código -@subsection Formato del código - -@cindex dar formato al código -@cindex estilo de codificación -Cuando escribimos código Scheme, seguimos la sabiduría común entre las -programadoras Scheme. En general, seguimos las -@url{http://mumble.net/~campbell/scheme/style.txt, Reglas de estilo Lisp de -Riastradh}. Este documento resulta que también describe las convenciones más -usadas en el código Guile. Está lleno de ideas y bien escrito, así que -recomendamos encarecidamente su lectura. - -Algunas formas especiales introducidas en Guix, como el macro -@code{substitute*} tienen reglas de indentación especiales. Estas están -definidas en el fichero @file{.dir-locals.el}, el cual Emacs usa -automáticamente. Fíjese que además Emacs-Guix proporciona el modo -@code{guix-devel-mode} que indenta y resalta adecuadamente el código de Guix -(@pxref{Desarrollo,,, emacs-guix, The Emacs-Guix Reference Manual}). - -@cindex indentación, de código -@cindex formato, de código -Si no usa Emacs, por favor asegúrese de que su editor conoce esas -reglas. Para indentar automáticamente una definición de paquete también -puede ejecutar: - -@example -./etc/indent-code.el gnu/packages/@var{fichero}.scm @var{paquete} -@end example - -@noindent -Esto indenta automáticamente la definición de @var{paquete} en -@file{gnu/packages/@var{fichero}.scm} ejecutando Emacs en modo de -procesamiento de lotes. Para indentar un fichero completo, omita el segundo -parámetro: - -@example -./etc/indent-code.el gnu/services/@var{fichero}.scm -@end example - -@cindex Vim, edición de código Scheme -Si está editando código con Vim, le recomendamos ejecutar @code{:set -autoindent} para que el código se indente automáticamente mientras -escribe. Adicionalmente, -@uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} puede ayudar a manejar todos estos paréntesis. - -Requerimos que todos los procedimientos del nivel superior tengan una cadena -de documentación. Este requisito puede relajarse para procedimientos simples -privados en el espacio de nombres @code{(guix build @dots{})} no obstante. - -Los procedimientos no deben tener más de cuatro parámetros posicionales. Use -parámetros con palabras clave para procedimientos que toman más de cuatro -parámetros. - - -@node Envío de parches -@section Envío de parches - -El desarrollo se lleva a cabo usando el sistema de control de versiones -distribuido Git. Por lo tanto, no es estrictamente necesario el acceso al -repositorio. Son bienvenidas las contribuciones en forma de parches como los -producidos por @code{git format-patch} enviadas a la lista de correo -@email{guix-patches@@gnu.org}. - -Esta lista de correo está respaldada por una instancia de Debbugs accesible -en @uref{https://bugs.gnu.org/guix-patches}, la cual nos permite mantener el -seguimiento de los envíos. A cada mensaje enviado a esa lista de correo se -le asigna un número de seguimiento; la gente puede realizar aportaciones -sobre el tema mediante el envío de correos electrónicos a -@code{@var{NNN}@@debbugs.gnu.org}, donde @var{NNN} es el número de -seguimiento (@pxref{Envío de una serie de parches}). - -Le rogamos que escriba los mensajes de revisiones en formato ChangeLog -(@pxref{Change Logs,,, standards, GNU Coding Standards}); puede comprobar la -historia de revisiones en busca de ejemplos. - -Antes de enviar un parche que añade o modifica una definición de un paquete, -por favor recorra esta lista de comprobaciones: - -@enumerate -@item -Si las autoras del paquete software proporcionan una firma criptográfica -para el archivo de la versión, haga un esfuerzo para verificar la -autenticidad del archivo. Para un fichero de firma GPG separado esto puede -hacerse con la orden @code{gpg --verify}. - -@item -Dedique algún tiempo a proporcionar una sinopsis y descripción adecuadas -para el paquete. @xref{Sinopsis y descripciones}, para algunas directrices. - -@item -Ejecute @code{guix lint @var{paquete}}, donde @var{paquete} es el nombre del -paquete nuevo o modificado, y corrija cualquier error del que informe -(@pxref{Invocación de guix lint}). - -@item -Asegurese de que el paquete compile en su plataforma, usando @code{guix -build @var{package}}. - -@item -También le recomendamos que pruebe a construir el paquete en otras -plataformas disponibles. Como puede no disponer de acceso a dichas -plataformas hardware físicamente, le recomendamos el uso de -@code{qemu-binfmt-service-type} para emularlas. Para activarlo, añada el -siguiente servicio a la lista de servicios en su configuración -@code{operating-system}: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) - (guix-support? #t))) -@end example - -Una vez hecho esto, reconfigure su sistema. - -Enotonces podrá construir paquetes para diferentes plataformas mediante la -opción @code{--system}. Por ejemplo, para la construcción del paquete -"hello" para las arquitecturas armhf, aarch64 o mips64 ejecutaría las -siguientes órdenes, respectivamente: -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex empaquetamientos -Asegurese de que el paquete no usa copias empaquetadas de software ya -disponible como paquetes separados. - -A veces, paquetes incluyen copias embebidas del código fuente de sus -dependencias para conveniencia de las usuarias. No obstante, como -distribución, queremos asegurar que dichos paquetes efectivamente usan la -copia que ya tenemos en la distribución si hay ya una. Esto mejora el uso de -recursos (la dependencia es construida y almacenada una sola vez), y permite -a la distribución hacer cambios transversales como aplicar actualizaciones -de seguridad para un software dado en un único lugar y que afecte a todo el -sistema---algo que esas copias embebidas impiden. - -@item -Eche un vistazo al perfil mostrado por @command{guix size} (@pxref{Invocación de guix size}). Esto le permitirá darse cuenta de referencias a otros paquetes -retenidas involuntariamente. También puede ayudar a determinar si se debe -dividir el paquete (@pxref{Paquetes con múltiples salidas}), y qué -dependencias opcionales deben usarse. En particular, evite añadir -@code{texlive} como una dependencia: debido a su tamaño extremo, use -@code{texlive-tiny} o @code{texlive-union}. - -@item -Para cambios importantes, compruebe que los paquetes dependientes (si -aplica) no se ven afectados por el cambio; @code{guix refresh ---list-dependent @var{package}} le ayudará a hacerlo (@pxref{Invocación de guix refresh}). - -@c See . -@cindex estrategia de ramas -@cindex estrategia de planificación de reconstrucciones -En base al número de paquetes dependientes y, por tanto, del tamaño de la -reconstrucción inducida, los revisiones van a ramas separadas, según estas -líneas: - -@table @asis -@item 300 paquetes dependientes o menos -rama @code{master} (cambios no disruptivos). - -@item entre 300 y 1.200 paquetes dependientes -rama @code{staging} (cambios no disruptivos). Esta rama está pensada para -ser incorporada en @code{master} cada 3 semanas más o menos. Ramas temáticas -(por ejemplo, una actualización de la pila de GNOME) pueden ir en una rama -específica (digamos, @code{gnome-updates}). - -@item más de 1.200 paquetes dependientes -rama @code{core-updates} (puede incluir cambios mayores y potencialmente -disruptivos). Esta rama está pensada para ser incluida en @code{master} cada -2,5 más o menos. -@end table - -Todas estas ramas son @uref{https://hydra.gnu.org/project/gnu, seguidas por -nuestra granja de construcción} e incluidas en @code{master} una vez todo se -ha construido satisfactoriamente. Esto nos permite corregir errores antes de -que afecten a usuarias, y reducir la ventana durante la cual los binarios -preconstruidos no están disponibles. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Generalmente, ramas distintas a @code{master} se consideran -@emph{congeladas} si ha habido una evaluación reciente, o hay una rama -@code{-next} correspondiente. Por favor, pregunte en la lista de correo o en -IRC si no está segura de dónde colocar un parche. - -@item -@cindex determinismo, del proceso de construcción -@cindex construcciones reproducibles, comprobar -Compruebe si el proceso de construcción de un paquete es determinista. Esto -significa típicamente comprobar si una construcción independiente del -paquete ofrece exactamente el mismo resultado que usted obtuvo, bit a bit. - -Una forma simple de hacerlo es construyendo el mismo paquete varias veces -seguidas en su máquina (@pxref{Invocación de guix build}): - -@example -guix build --rounds=2 mi-paquete -@end example - -Esto es suficiente una clase común de problemas de no-determinismo, como las -marcas de tiempo o salida generada aleatoriamente en el resultado de la -construcción. - -Otra opción es el uso de @command{guix challenge} (@pxref{Invocación de guix challenge}). Puede ejecutarse una vez la revisión del paquete haya sido -publicada y construida por @code{@value{SUBSTITUTE-SERVER}} para comprobar -si obtuvo el mismo resultado que usted. Mejor aún: encuentre otra máquina -que pueda construirla y ejecute @command{guix publish}. Ya que la máquina -remota es probablemente diferente a la suya, puede encontrar problemas de -no-determinismo relacionados con el hardware---por ejemplo, el uso de un -conjunto de instrucciones extendido diferente---o con el núcleo del sistema -operativo---por ejemplo, dependencias en @code{uname} o ficheros -@file{/proc}. - -@item -Cuando escriba documentación, por favor use construcciones neutrales de -género para referirse a la gente@footnote{NdT: En esta traducción se ha -optado por usar el femenino para referirse a @emph{personas}, ya que es el -género gramatical de dicha palabra. Aunque las construcciones impersonales -pueden adoptarse en la mayoría de casos, también pueden llegar a ser muy -artificiales en otros usos del castellano; en ocasiones son directamente -imposibles. Algunas construcciones que proponen la neutralidad de género -dificultan la lecura automática (-x), o bien dificultan la corrección -automática (-e), o bien aumentan significativamente la redundancia y reducen -del mismo modo la velocidad en la lectura (-as/os, -as y -os). No obstante, -la adopción del genero neutro heredado del latín, el que en castellano se ha -unido con el masculino, como construcción neutral de género se considera -inaceptable, ya que sería equivalente al ``it'' en inglés, nada más lejos de -la intención de las autoras originales del texto.}, como -@uref{https://en.wikipedia.org/wiki/Singular_they, singular ``they''@comma{} -``their''@comma{} ``them''} y demás. - -@item -Compruebe que su parche contiene únicamente un conjunto relacionado de -cambios. Agrupando cambios sin relación dificulta y ralentiza la revisión. - -Ejemplos de cambios sin relación incluyen la adición de varios paquetes, o -una actualización de un paquete junto a correcciones a ese paquete. - -@item -Por favor, siga nuestras reglas de formato de código, posiblemente -ejecutando el guión @command{etc/indent-code.el} para que lo haga -automáticamente por usted (@pxref{Formato del código}). - -@item -Cuando sea posible, use espejos en la URL de las fuentes (@pxref{Invocación de guix download}). Use URL fiables, no generadas. Por ejemplo, los archivos de -GitHub no son necesariamente idénticos de una generación a la siguiente, así -que en este caso es normalmente mejor clonar el repositorio. No use el campo -@command{name} en la URL: no es muy útil y si el nombre cambia, la URL -probablemente estará mal. - -@end enumerate - -Cuando publique un parche a la lista de correo, use @samp{[PATCH] @dots{}} -como el asunto. Puede usar su cliente de correo o la orden @command{git -send-email} (@pxref{Envío de una serie de parches}). Preferimos recibir los parches -en texto plano, ya sea en línea o como adjuntos MIME. Se le recomienda que -preste atención por si su cliente de correo cambia algo como los saltos de -línea o la indentación, lo que podría potencialmente romper los parches. - -Cuando un error es resuelto, por favor cierre el hilo enviando un correo a -@email{@var{NNN}-done@@debbugs.gnu.org}. - -@unnumberedsubsec Envío de una serie de parches -@anchor{Envío de una serie de parches} -@cindex series de parches -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -Cuando envíe una serie de parches (por ejemplo, usando @code{git -send-email}), por favor mande primero un mensaje a -@email{guix-patches@@gnu.org}, y después mande los parches siguientes a -@email{@var{NNN}@@debbugs.gnu.org} para asegurarse de que se mantienen -juntos. Véase @uref{https://debbugs.gnu.org/Advanced.html, la documentación -de Debbugs} para más información. diff --git a/doc/contributing.fr.texi b/doc/contributing.fr.texi deleted file mode 100644 index ab9c17e373..0000000000 --- a/doc/contributing.fr.texi +++ /dev/null @@ -1,1007 +0,0 @@ -@node Contribuer -@chapter Contribuer - -Ce projet est un effort coopératif et nous avons besoin de votre aide pour -le faire grandir ! Contactez-nous sur @email{guix-devel@@gnu.org} et -@code{#guix} sur le réseau IRC Freenode. Nous accueillons les idées, les -rapports de bogues, les correctifs et tout ce qui pourrait aider le projet. -Nous apprécions particulièrement toute aide sur la création de paquets -(@pxref{Consignes d'empaquetage}). - -@cindex code de conduite, des contributeurs -@cindex convention de contribution -Nous souhaitons fournir un environnement chaleureux, amical et sans -harcèlement pour que tout le monde puisse contribuer au mieux de ses -capacités. Pour cela notre projet a une « Convention de contribution » -adaptée de @url{http://contributor-covenant.org/}. Vous pouvez trouver une -version locale dans le fichier @file{CODE-OF-CONDUCT} dans l'arborescence -des sources. - -Les contributeurs n'ont pas besoin d'utiliser leur nom légal dans leurs -correctifs et leurs communications en ligne ; ils peuvent utiliser n'importe -quel nom ou pseudonyme de leur choix. - -@menu -* Construire depuis Git:: Toujours le plus récent. -* Lancer Guix avant qu'il ne soit installé:: Astuces pour les hackers. -* La configuration parfaite:: Les bons outils. -* Consignes d'empaquetage:: Faire grandir la distribution. -* Style de code:: Hygiène du contributeur. -* Envoyer des correctifs:: Partager votre travail. -@end menu - -@node Construire depuis Git -@section Construire depuis Git - -Si vous souhaitez travailler sur Guix lui-même, il est recommandé d'utiliser -la dernière version du dépôt Git : - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -Lors de la construction de Guix depuis un extrait, les paquets suivants sont -requis en plus de ceux mentionnés dans les instructions d'installation -(@pxref{Prérequis}). - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (facultatif)}. -@end itemize - -La manière la plus simple de configurer un environnement de développement -pour Guix est, bien sûr, d'utiliser Guix ! La commande suivante démarre un -nouveau shell où toutes les dépendances et les variables d'environnements -appropriées sont configurés pour travailler sur Guix : - -@example -guix environment guix -@end example - -@xref{Invoquer guix environment}, pour plus d'information sur cette -commande. On peut ajouter des dépendances supplémentaires avec -@option{--ad-hoc} : - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -Lancez @command{./bootstrap} pour générer l'infrastructure du système de -construction avec Autoconf et Automake. Si vous avez une erreur comme : - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -cela signifie probablement qu'Autoconf n'a pas pu trouver @file{pkg.m4} qui -est fournit par pkg-config. Assurez-vous que @file{pkg.m4} est disponible. -C'est aussi vrai pour l'ensemble de macros de @file{guile.m4} fournies par -Guile. Par exemple, si vous avez installé Automake dans @file{/usr/local}, -il ne cherchera pas les fichiers @file{.m4} dans @file{/usr/share}. Dans ce -case vous devez invoquer la commande suivante : - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -@xref{Macro Search Path,,, automake, The GNU Automake Manual}, pour plus -d'information. - -Ensuite, lancez @command{./configure} comme d'habitude. Assurez-vous de -passer @code{--localstatedir=@var{directory}} où @var{directory} est la -valeur @code{localstatedir} utilisée par votre installation actuelle -(@pxref{Le dépôt} pour plus d'informations à ce propos). - -Finalement, vous devez invoquer @code{make check} pour lancer les tests -(@pxref{Lancer la suite de tests}). Si quelque chose échoue, jetez un œil -aux instructions d'installation (@pxref{Installation}) ou envoyez un message -à la liste @email{guix-devel@@gnu.org}. - - -@node Lancer Guix avant qu'il ne soit installé -@section Lancer Guix avant qu'il ne soit installé - -Pour garder un environnement de travail sain, il est utile de tester les -changement localement sans les installer pour de vrai. Pour pouvoir -distinguer votre rôle « d'utilisateur final » de celui parfois haut en -couleur de « développeur ». - -Pour cela, tous les outils en ligne de commande sont utilisables même sans -avoir lancé @code{make install}. Pour cela, vous devez d'abord avoir un -environnement avec toutes les dépendances disponibles (@pxref{Construire depuis Git}), puis préfixer chaque commande par @command{./pre-inst-env} (le script -@file{pre-inst-env} se trouve dans le répertoire de plus haut niveau de -l'arborescence des sources de Guix ; il est généré par -@command{./configure}) comme cela@footnote{L'option @option{-E} de -@command{sudo} garantie que @code{GUILE_LOAD_PATH} est bien paramétré pour -@command{guix-daemon} et pour que les outils qu'il utilise puissent trouver -les modules Guile dont ils ont besoin.} : - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -De même, pour une session Guile qui utilise les modules Guix : - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex read-eval-print loop -@dots{} et pour un REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}) - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define snakes - (fold-packages - (lambda (package lst) - (if (string-prefix? "python" - (package-name package)) - (cons package lst) - lst)) - '())) -scheme@@(guile-user)> (length snakes) -$1 = 361 -@end example - -Le script @command{pre-inst-env} paramètre toutes les variables -d'environnement nécessaires, dont @env{PATH} et @env{GUILE_LOAD_PATH}. - -Remarquez que @command{./pre-inst-env guix pull} ne met @emph{pas} à jour -l'arborescence des sources locale ; cela met seulement à jour le lien -symbolique de @file{~/.config/guix/current} (@pxref{Invoquer guix pull}). -Lancez @command{git pull} à la place si vous voulez mettre à jour votre -arborescence des source locale. - - -@node La configuration parfaite -@section La configuration parfaite - -La configuration parfaite pour travailler sur Guix est simplement la -configuration parfaite pour travailler en Guile (@pxref{Using Guile in -Emacs,,, guile, Guile Reference Manual}). Tout d'abord, vous avez besoin de -mieux qu'un éditeur de texte, vous avez besoin de -@url{http://www.gnu.org/software/emacs, Emacs}, amélioré par le superbe -@url{http://nongnu.org/geiser/, Geiser}. Pour paramétrer cela, lancez : - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser permet le développement interactif et incrémental depuis Emacs : la -compilation du code et son évaluation depuis les buffers, l'accès à la -documentation en ligne (docstrings), la complétion sensible au contexte, -@kbd{M-.} pour sauter à la définition d'un objet, un REPL pour tester votre -code, et bien plus (@pxref{Introduction,,, geiser, Geiser User Manual}). -Pour travailler confortablement sur Guix, assurez-vous de modifier le chemin -de chargement de Guile pour qu'il trouve les fichiers source de votre dépôt -: - -@lisp -;; @r{Si l'extrait est dans ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -Pour effectivement éditer le code, Emacs a déjà un très bon mode Scheme. -Mais en plus de ça, vous ne devez pas rater -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Il fournit des -fonctionnalités pour opérer directement sur l'arbre de syntaxe, comme -relever une s-expression ou l'envelopper, absorber ou rejeter la -s-expression suivante, etc. - -@cindex extraits de code -@cindex modèles -@cindex réduire la quantité de code commun -Nous fournissons aussi des modèles pour les messages de commit git communs -et les définitions de paquets dans le répertoire @file{etc/snippets}. Ces -modèles s'utilisent avec @url{http://joaotavora.github.io/yasnippet/, -YASnippet} pour développer des chaînes courtes de déclenchement en extraits -de texte interactifs. Vous pouvez ajouter le répertoire des modèles dans la -variables @var{yas-snippet-dirs} d'Emacs. - -@lisp -;; @r{Si l'extrait est dans ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -Les extraits de messages de commit dépendent de @url{https://magit.vc/, -Magit} pour afficher les fichiers sélectionnés. Lors de la modification -d'un message de commit, tapez @code{add} suivi de @kbd{TAB} pour insérer un -modèle de message de commit pour ajouter un paquet ; tapez @code{update} -suivi de @kbd{TAB} pour insérer un modèle pour la mise à jour d'un paquet ; -tapez @code{https} suivi de @kbd{TAB} pour insérer un modèle pour le -changement à HTTPS de l'URI de la page d'accueil. - -L'extrait principal pour @code{scheme-mode} est lancé en tapant -@code{package…} suivi par @kbd{TAB}. Cet extrait insère aussi la chaîne de -déclenchement @code{origin…}, qui peut aussi être étendue. L'extrait -@code{origin} lui-même peut aussi insérer des chaînes de déclenchement qui -finissent sur @code{…}, qui peuvent aussi être étendues. - - -@node Consignes d'empaquetage -@section Consignes d'empaquetage - -@cindex paquets, création -La distribution GNU est jeune et vos paquets préférés peuvent manquer. -Cette section décrit comment vous pouvez aider à agrandir la distribution. - -Les paquets de logiciels libres sont habituellement distribués sous forme -@dfn{d'archives de sources} — typiquement des fichiers @file{.tar.gz} -contenant tous les fichiers sources. Ajouter un paquet à la distribution -signifie essentiellement deux choses : ajouter une @dfn{recette} qui décrit -comment construire le paquet, avec une liste d'autres paquets requis pour le -construire, et ajouter des @dfn{métadonnées de paquet} avec la recette, -comme une description et une licence. - -Dans Guix, toutes ces informations sont incorporées dans les -@dfn{définitions de paquets}. Les définitions de paquets fournissent une -vue de haut-niveau du paquet. Elles sont écrites avec la syntaxe du langage -de programmation Scheme ; en fait, pour chaque paquet nous définissons une -variable liée à la définition et exportons cette variable à partir d'un -module (@pxref{Modules de paquets}). Cependant, il n'est @emph{pas} nécessaire -d'avoir une connaissance approfondie du Scheme pour créer des paquets. Pour -plus d'informations sur les définitions des paquets, @pxref{Définition des paquets}. - -Une fois une définition de paquet en place, stocké dans un fichier de -l'arborescence des sources de Guix, il peut être testé avec la commande -@command{guix build} (@pxref{Invoquer guix build}). Par exemple, en -supposant que le nouveau paquet s'appelle @code{gnew}, vous pouvez lancer -cette commande depuis l'arborescence de construction de Guix (@pxref{Lancer Guix avant qu'il ne soit installé}) : - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Utiliser @code{--keep-failed} rend facile le débogage des échecs car il -fournit l'accès à l'arborescence de construction qui a échouée. Une autre -sous-commande utile pour le débogage est @code{--log-file}, pour accéder au -journal de construction. - -Si le paquet n'est pas connu de la commande @command{guix}, il se peut que -le fichier source ait une erreur de syntaxe, ou qu'il manque une clause -@code{define-public} pour exporter la variable du paquet. Pour comprendre -cela, vous pouvez charger le module depuis Guile pour avoir plus -d'informations sur la véritable erreur : - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Une fois que votre paquet est correctement construit, envoyez-nous un -correctif (@pxref{Contribuer}). Enfin, si vous avez besoin d'aide, nous -serrons ravis de vous aider. Une fois que le correctif soumis est committé -dans le dépôt Guix, le nouveau paquet est automatiquement construit sur les -plate-formes supportées par @url{http://hydra.gnu.org/jobset/gnu/master, -notre système d'intégration continue}. - -@cindex substitution -On peut obtenir la nouvelle définition du paquet simplement en lançant -@command{guix pull} (@pxref{Invoquer guix pull}). Lorsque -@code{@value{SUBSTITUTE-SERVER}} a fini de construire le paquet, -l'installation du paquet y télécharge automatiquement les binaires -(@pxref{Substituts}). La seule intervention humaine requise est pendant la -revue et l'application du correctif. - - -@menu -* Liberté logiciel:: Ce que la distribution peut contenir. -* Conventions de nommage:: Qu'est-ce qu'un bon nom ? -* Numéros de version:: Lorsque le nom n'est pas suffisant. -* Synopsis et descriptions:: Aider les utilisateurs à trouver le bon - paquet. -* Modules python:: Un peu de comédie anglaise. -* Modules perl:: Petites perles. -* Paquets java:: Pause café. -* Polices de caractères:: À fond les fontes. -@end menu - -@node Liberté logiciel -@subsection Liberté logiciel - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex logiciel libre -Le système d'exploitation GNU a été développé pour que les utilisateurs -puissent utiliser leur ordinateur en toute liberté. GNU est un -@dfn{logiciel libre}, ce qui signifie que les utilisateur ont les -@url{http://www.gnu.org/philosophy/free-sw.fr.html,quatre libertés -essentielles} : exécuter le programmer, étudier et modifier le programme -sous sa forme source, redistribuer des copies exactes et distribuer les -versions modifiées. Les paquets qui se trouvent dans la distribution GNU ne -fournissent que des logiciels qui respectent ces quatre libertés. - -En plus, la distribution GNU suit les -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,recommandations -pour les distributions systèmes libres}. Entre autres choses, ces -recommandations rejettent les microgiciels non libres, les recommandations -de logiciels non libres et discute des façon de gérer les marques et les -brevets. - -Certaines sources amont autrement parfaitement libres contiennent une petite -partie facultative qui viole les recommandations ci-dessus, par exemple car -cette partie est du code non-libre. Lorsque cela arrive, les éléments en -question sont supprimés avec des correctifs ou des bouts de codes appropriés -dans la forme @code{origin} du paquet (@pxref{Définition des paquets}). De cette -manière, @code{guix build --source} renvoie la source « libérée » plutôt que -la source amont sans modification. - - -@node Conventions de nommage -@subsection Conventions de nommage - -@cindex nom du paquet -Un paquet a en fait deux noms qui lui sont associés : d'abord il y a le nom -de la @emph{variable Scheme}, celui qui suit @code{define-public}. Par ce -nom, le paquet peut se faire connaître par le code Scheme, par exemple comme -entrée d'un autre paquet. Deuxièmement, il y a la chaîne dans le champ -@code{name} d'une définition de paquet. Ce nom est utilisé par les -commandes de gestion des paquets comme @command{guix package} et -@command{guix build}. - -Les deux sont habituellement les mêmes et correspondent à la conversion en -minuscule du nom du projet choisi en amont, où les underscores sont -remplacés par des tirets. Par exemple, GNUnet est disponible en tant que -@code{gnunet} et SDL_net en tant que @code{sdl-net}. - -Nous n'ajoutons pas de préfixe @code{lib} au bibliothèques de paquets, à -moins qu'il ne fasse partie du nom officiel du projet. Mais @pxref{Modules python} et @ref{Modules perl} pour des règles spéciales concernant les -modules pour les langages Python et Perl. - -Les noms de paquets de polices sont gérés différemment, @pxref{Polices de caractères}. - - -@node Numéros de version -@subsection Numéros de version - -@cindex version du paquet -Nous n'incluons en général que la dernière version d'un projet de logiciel -libre donné. Mais parfois, par exemple pour des versions incompatibles de -bibliothèques, deux (ou plus) versions du même paquet sont requises. Elles -ont besoin d'un nom de variable Scheme différent. Nous utilisons le nom -défini dans @ref{Conventions de nommage} pour la version la plus récente ; les -versions précédentes utilisent le même nom, suffixé par @code{-} et le plus -petit préfixe du numéro de version qui permet de distinguer deux versions. - -Le nom dans la définition du paquet est le même pour toutes les versions -d'un paquet et ne contient pas de numéro de version. - -Par exemple, les version 2.24.20 et 3.9.12 de GTK+ peuvent être inclus de -cette manière : - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -Si nous voulons aussi GTK+ 3.8.2, cela serait inclus de cette manière : -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See , -@c for a discussion of what follows. -@cindex numéro de version, pour les instantanés des systèmes de contrôle de version -Parfois, nous incluons des paquets provenant d'instantanés de systèmes de -contrôle de version (VCS) au lieu de versions publiées formellement. Cela -devrait rester exceptionnel, car c'est le rôle des développeurs amont de -spécifier quel est la version stable. Cependant, c'est parfois nécessaire. -Donc, que faut-il mettre dans le champ @code{version} ? - -Clairement, nous devons rendre l'identifiant de commit de l'instantané du -VCS visible dans la version, mais nous devons aussi nous assurer que la -version augmente de manière monotone pour que @command{guix package ---upgrade} puisse déterminer quelle version est la plus récente. Comme les -identifiants de commits, notamment avec Git, n'augmentent pas, nous ajoutons -un numéro de révision qui nous augmentons à chaque fois que nous mettons à -jour vers un nouvel instantané. La chaîne qui en résulte ressemble à cela : - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- ID du commit en amont - | | - | `--- révision du paquet Guix - | -dernière version en amont -@end example - -C'est une bonne idée de tronquer les identifiants dans le champ -@code{version} à disons 7 caractères. Cela évite un problème esthétique (en -supposant que l'esthétique ait un rôle à jouer ici) et des problèmes avec -les limites de l'OS comme la longueur maximale d'un shebang (127 octets pour -le noyau Linux). Il vaut mieux utilise l'identifiant de commit complet dans -@code{origin} cependant, pour éviter les ambiguïtés. Une définition de -paquet peut ressembler à ceci : - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;révision du paquet Guix - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/my-package.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Synopsis et descriptions -@subsection Synopsis et descriptions - -@cindex description du paquet -@cindex résumé du paquet -Comme nous l'avons vu avant, chaque paquet dans GNU@tie{}Guix contient un -résumé et une description (@pxref{Définition des paquets}). Les résumés et les -descriptions sont importants : ce sont eux que recherche @command{guix -package --search}, et c'est une source d'informations cruciale pour aider -les utilisateurs à déterminer si un paquet donner correspond à leurs -besoins. En conséquence, les mainteneurs doivent prêter attention à leur -contenu. - -Les résumés doivent commencer par une lettre capitale et ne doit pas finir -par un point. Ils ne doivent pas commencer par « a » ou « the » (« un » ou -« le/la »), ce qui n'apporte généralement rien ; par exemple, préférez « -File-frobbing tool » (« Outil de frobage de fichier ») à « A tool that frobs -file » (« Un outil qui frobe les fichiers »). Le résumé devrait dire ce que -le paquet est — p.@: ex.@: « Utilitaire du cœur de GNU (fichier, text, -shell) » — ou ce à quoi il sert — p.@: ex.@: le résumé de grep est « Affiche -des lignes correspondant à un motif ». - -Gardez à l'esprit que le résumé doit avoir un sens pour une large audience. -Par exemple « Manipulation d'alignements au format SAM » peut avoir du sens -pour un bioinformaticien chevronné, mais n'aidera pas ou pourra perdre une -audience de non-spécialistes. C'est une bonne idée de créer un résumé qui -donne une idée du domaine d'application du paquet. Dans cet exemple, cela -donnerait « Manipulation d'alignements de séquences de nucléotides », ce qui -devrait donner une meilleure idée à l'utilisateur pour savoir si c'est ce -qu'il recherche. - -Les descriptions devraient faire entre cinq et dix lignes. Utilisez des -phrases complètes, et évitez d'utiliser des acronymes sans les introduire -d'abord. Évitez les phrases marketings comme « world-leading », « -industrial-strength » et « next-generation » et évitez les superlatifs comme -« the most advanced » — ils ne sont pas utiles pour les utilisateurs qui -cherchent un paquet et semblent même un peu suspects. À la place, essayez -d'être factuels, en mentionnant les cas d'utilisation et les -fonctionnalités. - -@cindex balisage texinfo, dans les descriptions de paquets -Les descriptions peuvent inclure du balisage Texinfo, ce qui est utile pour -introduire des ornements comme @code{@@code} ou @code{@@dfn}, des listes à -points ou des hyperliens (@pxref{Overview,,, texinfo, GNU Texinfo}). -Cependant soyez prudents lorsque vous utilisez certains symboles, par -exemple @samp{@@} et les accolades qui sont les caractères spéciaux de base -en Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). Les -interfaces utilisateurs comme @command{guix package --show} prennent en -charge le rendu. - -Les résumés et les descriptions sont traduits par des volontaires -@uref{http://translationproject.org/domain/guix-packages.html, sur le projet -de traduction} pour que le plus d'utilisateurs possible puissent les lire -dans leur langue natale. Les interfaces utilisateurs les recherchent et les -affichent dans la langue spécifiée par le paramètre de régionalisation -actuel. - -Pour permettre à @command{xgettext} de les extraire comme des chaînes -traduisibles, les résumés et les descriptions @emph{doivent être des chaînes -litérales}. Cela signifie que vous ne pouvez pas utiliser -@code{string-append} ou @code{format} pour construire ces chaînes : - -@lisp -(package - ;; @dots{} - (synopsis "Ceci est traduisible") - (description (string-append "Ceci n'est " "*pas*" " traduisible."))) -@end lisp - -La traduction demande beaucoup de travail, donc en tant que packageur, -faîtes encore plus attention à vos résumés et descriptions car chaque -changement peut demander d'autant plus de travail de la part des -traducteurs. Pour les aider, il est possible de donner des recommandations -ou des instructions qu'ils pourront voir en insérant des commentaires -spéciaux comme ceci (@pxref{xgettext Invocation,,, gettext, GNU Gettext}) : - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Modules python -@subsection Modules python - -@cindex python -Nous incluons actuellement Python 2 et Python 3, sous les noms de variables -Scheme @code{python-2} et @code{python} comme expliqué dans @ref{Numéros de version}. Pour éviter la confusion et les problèmes de noms avec d'autres -langages de programmation, il semble désirable que le nom d'un paquet pour -un module Python contienne le mot @code{python}. - -Certains modules ne sont compatibles qu'avec une version de Python, d'autres -avec les deux. Si le paquet Foo ne compile qu'avec Ptyhon 3, on le nomme -@code{python-foo} ; s'il ne compile qu'avec Python 2, on le nome -@code{python2-foo}. S'il est compatible avec les deux versions, nous créons -deux paquets avec les noms correspondant. - -Si un projet contient déjà le mot @code{python}, on l'enlève, par exemple le -module python-dateutil est packagé sous les noms @code{python-dateutil} et -@code{python2-dateutil}. Si le nom du projet commence par @code{py} (p.@: -ex.@: @code{pytz}), on le garde et on le préfixe comme décrit ci-dessus. - -@subsubsection Spécifier les dépendances -@cindex entrées, pour les paquets Python - -Les informations de dépendances pour les paquets Python se trouvent -généralement dans l'arborescence des source du paquet, avec plus ou moins de -précision : dans le fichier @file{setup.py}, dans @file{requirements.txt} ou -dans @file{tox.ini}. - -Votre mission, lorsque vous écrivez une recette pour un paquet Python, est -de faire correspondre ces dépendances au bon type « d'entrée » -(@pxref{Référence des paquets, inputs}). Bien que l'importeur @code{pypi} fasse -du bon boulot (@pxref{Invoquer guix import}), vous devriez vérifier la liste -suivant pour déterminer où va telle dépendance. - -@itemize - -@item -Nous empaquetons Python 2 avec @code{setuptools} et @code{pip} installé -comme Python 3.4 par défaut. Ainsi, vous n'avez pas à spécifié ces -entrées. @command{guix lint} vous avertira si vous faîtes cela. - -@item -Les dépendances Python requises à l'exécutions vont dans -@code{propagated-inputs}. Elles sont typiquement définies dans le mot-clef -@code{install_requires} dans @file{setup.py} ou dans le fichier -@file{requirements.txt}. - -@item -Les paquets Python requis uniquement à la construction — p.@: ex.@: ceux -listés dans le mot-clef @code{setup_requires} de @file{setup.py} — ou -seulement pour les tests — p.@: ex.@: ceux dans @code{tests_require} — vont -dans @code{native-inputs}. La raison est qu'ils n'ont pas besoin d'être -propagés car ils ne sont pas requis à l'exécution et dans le cas d'une -compilation croisée, c'est l'entrée « native » qu'il nous faut. - -Les cadriciels de tests @code{pytest}, @code{mock} et @code{nose} sont des -exemples. Bien sûr si l'un de ces paquets est aussi requis à l'exécution, -il doit aller dans @code{propagated-inputs}. - -@item -Tout ce qui ne tombe pas dans les catégories précédentes va dans -@code{inputs}, par exemple des programmes pour des bibliothèques C requises -pour construire des paquets Python avec des extensions C. - -@item -Si un paquet Python a des dépendances facultatives (@code{extras_require}), -c'est à vous de décider de les ajouter ou non, en fonction du ratio entre -utilité et complexité (@pxref{Envoyer des correctifs, @command{guix size}}). - -@end itemize - - -@node Modules perl -@subsection Modules perl - -@cindex perl -Les programmes Perl utiles en soit sont nommés comme les autres paquets, -avec le nom amont en minuscule. Pour les paquets Perl contenant une seule -classe, nous utilisons le nom de la classe en minuscule, en remplaçant les -occurrences de @code{::} par des tirets et en préfixant le tout par -@code{perl-}. Donc la classe @code{XML::Parser} devient -@code{perl-xml-parser}. Les modules contenant plusieurs classes gardent -leur nom amont en minuscule et sont aussi préfixés par @code{perl-}. Ces -modules tendent à avoir le mot @code{perl} quelque part dans leur nom, que -nous supprimons en faveur du préfixe. Par exemple, @code{libwww-perl} -devient @code{perl-libwww}. - - -@node Paquets java -@subsection Paquets java - -@cindex java -Le programmes Java utiles en soit sont nommés comme les autres paquets, avec -le nom amont en minuscule. - -Pour éviter les confusions et les problèmes de nom avec d'autres langages de -programmation, il est désirable que le nom d'un paquet Java soit préfixé par -@code{java-}. Si un projet contient déjà le mot @code{java}, nous le -supprimons, par exemple le paquet @code{ngsjava} est empaqueté sous le nom -@code{java-ngs}. - -Pour les paquets java contenant une seul classe ou une petite hiérarchie de -classes, nous utilisons le nom de la classe en minuscule, en remplaçant les -occurrences de @code{.} par des tirets et en préfixant le tout par -@code{java-}. Donc la classe @code{apache.commons.cli} devient -@code{java-apache-commons-cli}. - - -@node Polices de caractères -@subsection Polices de caractères - -@cindex polices -Pour les polices qui n esont en général par installées par un utilisateurs -pour du traitement de texte, ou qui sont distribuées en tant que partie d'un -paquet logiciel plus gros, nous nous appuyons sur les règles générales pour -les logiciels ; par exemple, cela s'applique aux polices livrées avec le -système X.Org ou les polices qui font partie de TeX Live. - -Pour rendre plus facile la recherche par l'utilisateur, les noms des autres -paquets contenant seulement des polices sont construits ainsi, -indépendamment du nom du paquet en amont. - -Le nom d'un paquet contenant une unique famille de polices commence par -@code{font-} ; il est suivi du nom du fondeur et d'un tiret @code{-} si le -fondeur est connu, et du nom de la police, dont les espaces sont remplacés -par des tirets (et comme d'habitude, toutes les lettres majuscules sont -transformées en minuscules). Par exemple, la famille de polices Gentium de -SIL est empaqueté sous le nom @code{font-sil-gentium}. - -Pour un paquet contenant plusieurs familles de polices, le nom de la -collection est utilisée à la place du nom de la famille. Par exemple les -polices Liberation consistent en trois familles, Liberation Sans, Liberation -Serif et Liberation Mono. Elles pourraient être empaquetées séparément sous -les noms @code{font-liberation-sans} etc, mais comme elles sont distribuées -ensemble sous un nom commun, nous préférons les empaqueter ensemble en tant -que @code{font-liberation}. - -Dans le cas où plusieurs formats de la même famille ou collection sont -empaquetés séparément, une forme courte du format, préfixé d'un tiret est -ajouté au nom du paquet. Nous utilisont @code{-ttf} pour les polices -TrueType, @code{-otf} pour les polices OpenType et @code{-type1} pour les -polices Type 1 de PostScript. - - -@node Style de code -@section Style de code - -En général notre code suit le Standard de Code GNU (@pxref{Top,,, standards, -GNU Coding Standards}). Cependant, il ne parle pas beaucoup de Scheme, donc -voici quelques règles supplémentaires. - -@menu -* Paradigme de programmation:: Comment composer vos éléments. -* Modules:: Où stocker votre code ? -* Types de données et reconnaissance de motif:: Implémenter des - structures de données. -* Formatage du code:: Conventions d'écriture. -@end menu - -@node Paradigme de programmation -@subsection Paradigme de programmation - -Le code Scheme dans Guix est écrit dans un style purement fonctionnel. Le -code qui s'occupe des entrées-sorties est une exception ainsi que les -procédures qui implémentent des concepts bas-niveau comme la procédure -@code{memoize}. - -@node Modules -@subsection Modules - -Les modules Guile qui sont sensés être utilisés du côté de la construction -doivent se trouver dans l'espace de nom @code{(guix build @dots{})}. Ils ne -doivent pas se référer à d'autres modules Guix ou GNU@. Cependant il est -correct pour un module « côté hôte » de dépendre d'un module coté -construction. - -Les modules qui s'occupent du système GNU général devraient se trouver dans -l'espace de nom @code{(gnu @dots{})} plutôt que @code{(guix @dots{})}. - -@node Types de données et reconnaissance de motif -@subsection Types de données et reconnaissance de motif - -La tendance en Lisp classique est d'utiliser des listes pour tout -représenter et de naviguer dedans « à la main ( avec @code{car}, @code{cdr}, -@code{cadr} et compagnie. Il y a plusieurs problèmes avec ce style, -notamment le fait qu'il soit dur à lire, source d'erreur et un obstacle aux -rapports d'erreur bien typés. - -Le code de Guix devrait définir des types de données appropriées (par -exemple, avec @code{define-record-type*}) plutôt que d'abuser des listes. -En plus, il devrait utiliser la recherche de motifs, via le module Guile -@code{(ice-9 match)}, surtout pour rechercher dans des listes. - -@node Formatage du code -@subsection Formatage du code - -@cindex formater le code -@cindex style de code -Lorsque nous écrivons du code Scheme, nous suivons la sagesse commune aux -programmeurs Scheme. En général, nous suivons les -@url{http://mumble.net/~campbell/scheme/style.txt, règles de style de -Riastradh}. Ce document décrit aussi les conventions utilisées dans le code -de Guile. Il est bien pensé et bien écrit, alors n'hésitez pas à le lire. - -Certaines formes spéciales introduites dans Guix comme la macro -@code{substitute*} ont des règles d'indentation spécifiques. Elles sont -définies dans le fichier @file{.dir-locals.el} qu'Emacs utilise -automatiquement. Remarquez aussi qu'Emacs-Guix fournit le mode -@code{guix-devel-mode} qui indente et colore le code Guix correctement -(@pxref{Développement,,, emacs-guix, The Emacs-Guix Reference Manual}). - -@cindex indentation, du code -@cindex formatage, du code -Si vous n'utilisez pas Emacs, assurez-vous que votre éditeur connaisse ces -règles. Pour indenter automatiquement une définition de paquet, vous pouvez -aussi lancer : - -@example -./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} -@end example - -@noindent -Cela indente automatiquement la définition de @var{package} dans -@file{gnu/packages/@var{file}.scm} en lançant Emacs en mode commande. Pour -indenter un fichier complet, n'indiquez pas de second argument : - -@example -./etc/indent-code.el gnu/services/@var{file}.scm -@end example - -@cindex Vim, édition de code Scheme -Si vous éditez du code avec Vim, nous recommandons de lancer @code{:set -autoindent} pour que votre code soit automatiquement indenté au moment où -vous l'entrez. En plus, -@uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} peut vous aider à gérer toutes ces parenthèses. - -Nous demandons que toutes les procédure de premier niveau contiennent une -chaîne de documentation. Ce prérequis peut être relâché pour les procédures -privées simples dans l'espace de nom @code{(guix build @dots{})} cependant. - -Les procédures ne devraient pas avoir plus de quatre paramètres -positionnés. Utilisez des paramètres par mot-clefs pour les procédures qui -prennent plus de quatre paramètres. - - -@node Envoyer des correctifs -@section Envoyer des correctifs - -Le développement se fait avec le système de contrôle de version Git. Ainsi, -l'accès au dépôt n'est pas strictement nécessaire. Nous accueillons les -contributions sous forme de correctifs produits par @code{git format-patch} -envoyés sur la liste de diffusion @email{guix-patches@@gnu.org}. - -Cette liste de diffusion est gérée par une instance Debbugs accessible à -l'adresse @uref{https://bugs.gnu.org/guix-patches}, qui nous permet de -suivre les soumissions. Chaque message envoyé à cette liste se voit -attribuer un numéro de suivi ; les gens peuvent ensuite répondre à cette -soumission en envoyant un courriel à @code{@var{NNN}@@debbugs.gnu.org}, où -@var{NNN} est le numéro de suivi (@pxref{Envoyer une série de correctifs}). - -Veuillez écrire les messages de commit dans le format ChangeLog -(@pxref{Change Logs,,, standards, GNU Coding Standards}) ; vous pouvez -regarder l'historique des commits pour trouver des exemples. - -Avant de soumettre un correctif qui ajoute ou modifie la définition d'un -paquet, veuillez vérifier cette check-list : - -@enumerate -@item -Si les auteurs du paquet logiciel fournissent une signature cryptographique -pour l'archive, faîtes un effort pour vérifier l'authenticité de l'archive. -Pour un fichier de signature GPG détaché, cela se fait avec la commande -@code{gpg --verify}. - -@item -Prenez un peu de temps pour fournir un synopsis et une description adéquats -pour le paquet. Voir @xref{Synopsis et descriptions} pour quelques lignes -directrices. - -@item -Lancez @code{guix lint @var{paquet}}, où @var{paquet} est le nom du nouveau -paquet ou du paquet modifié, et corrigez les erreurs qu'il rapporte -(@pxref{Invoquer guix lint}). - -@item -Assurez-vous que le paquet se construise sur votre plate-forme avec -@code{guix build @var{paquet}}. - -@item -Nous vous recommandons aussi d'essayer de construire le paquet sur les -autres plate-formes prises en charge. Comme vous n'avez pas forcément accès -aux plate-formes matérielles, nous vous recommandons d'utiliser le -@code{qemu-binfmt-service-type} pour les émuler. Pour cela, ajoutez le -service suivant à la liste des services dans votre configuration de système -d'exploitation : - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) - (guix-support? #t))) -@end example - -Puis reconfigurez votre système. - -Vous pourrez ensuite construire les paquets pour différentes plate-formes en -spécifiant l'option @code{--system}. Par exemple pour construire le paquet -« hello » pour les architectures armhf, aarch64 ou mips64, vous devrez -lancer les commandes suivantes, respectivement : -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex construction groupée -Assurez-vous que le paquet n'utilise pas de copie groupée d'un logiciel déjà -disponible dans un paquet séparé. - -Parfois, les paquets incluent des copie du code source de leurs dépendances -pour le confort de leurs utilisateurs. Cependant, en tant que distribution, -nous voulons nous assurer que ces paquets utilisent bien les copient que -nous avons déjà dans la distribution si elles existent. Cela améliore -l'utilisation des ressources (la dépendance n'est construite et stockée -qu'une seule fois) et permet à la distribution de faire des changements -transversaux comme appliquer des correctifs de sécurité pour un paquet donné -depuis un unique emplacement et qu'ils affectent tout le système, ce -qu'empêchent les copies groupées. - -@item -Regardez le profil rapporté par @command{guix size} (@pxref{Invoquer guix size}). Cela vous permettra de remarquer des références à d'autres paquets -qui ont été retenus sans que vous vous y attendiez. Il peut aussi aider à -déterminer s'il faut découper le paquet (@pxref{Des paquets avec plusieurs -résultats}) et quelles dépendances facultatives utiliser. En particulier, -évitez d'ajouter @code{texlive} en dépendance : à cause de sa taille -extrême, utilisez @code{texlive-tiny} ou @code{texlive-union} à la place. - -@item -Pour les changements important, vérifiez que les paquets qui en dépendent -(s'ils existent) ne sont pas affectés par le changement ; @code{guix refresh ---list-dependant @var{paquet}} vous aidera (@pxref{Invoquer guix refresh}). - -@c See . -@cindex stratégie de branche -@cindex stratégie de planification des reconstructions -Suivant le nombre de paquets dépendants et donc le nombre de reconstruction -induites, les commits vont vers des branches différentes, suivant ces -principes : - -@table @asis -@item 300 paquets dépendants ou moins -branche @code{master} (changements non-disruptifs). - -@item entre 300 et 1 200 paquets dépendants -branche @code{staging} (changements non-disruptifs). Cette branche devrait -être fusionnées dans @code{master} tous les 3 semaines. Les changements par -thèmes (par exemple une mise à jour de la pile GNOME) peuvent aller dans une -branche spécifique (disons, @code{gnome-updates}). - -@item plus de 1 200 paquets dépendants -branche @code{core-updates} (peut inclure des changements majeurs et -potentiellement disruptifs). Cette branche devrait être fusionnée dans -@code{master} tous les 2,5 mois environ. -@end table - -Toutes ces branches sont @uref{https://hydra.gnu.org/project/gnu, gérées par -notre ferme de construction} et fusionnées dans @code{master} une fois que -tout a été construit correctement. Cela nous permet de corriger des -problèmes avant qu'ils n'atteignent les utilisateurs et réduit la fenêtre -pendant laquelle les binaires pré-construits ne sont pas disponibles. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Généralement les autres branches que @code{master} sont considérées comme -@emph{gelées} s'il y a eu une évaluation récente ou qu'il y a une branche -@code{-next} correspondante. Demandez sur la liste de diffusion ou sur IRC -si vous n'êtes pas sûr de savoir où pousser votre correctif. - -@item -@cindex déterminisme, du processus de construction -@cindex construction reproductibles, vérification -Vérifiez si le processus de construction du paquet est déterministe. Cela -signifie typiquement vérifier qu'une construction indépendante du paquet -renvoie exactement le même résultat que vous avez obtenu, bit à bit. - -Une manière simple de le faire est de reconstruire le paquet plusieurs fois -à la suite sur votre machine (@pxref{Invoquer guix build}) : - -@example -guix build --rounds=2 mon-paquet -@end example - -Cela est suffisant pour trouver une classe de non-déterminisme commune, -comme l'horodatage ou des sorties générées aléatoirement dans le résultat de -la construction. - -Une autre option consiste à utiliser @command{guix challenge} -(@pxref{Invoquer guix challenge}). Vous pouvez lancer la commande une fois -que les paquets ont été committés et construits par -@code{@value{SUBSTITUTE-SERVER}} pour vérifier s'il obtient le même résultat -que vous. Mieux encore : trouvez une autre machine qui peut le construire -et lancez @command{guix publish}. Puisque la machine distante est sûrement -différente de la vôtre, cela peut trouver des problèmes de non-déterminisme -liés au matériel — par exemple utiliser une extension du jeu d'instruction — -ou du noyau du système d'exploitation — par exemple se reposer sur -@code{uname} ou les fichiers de @file{/proc}. - -@item -Lorsque vous écrivez de la documentation, utilisez une formulation au genre -neutre lorsque vous vous référez à des personnes, comme le -@uref{https://fr.wikipedia.org/wiki/They_singulier, ``they''@comma{} -``their''@comma{} ``them'' singulier} (en anglais). - -@item -Vérifiez que votre correctif contienne seulement un ensemble de changements -liés. Grouper des changements non liés ensemble rend la revue plus -difficile et plus lente. - -Ajouter plusieurs paquet ou une mise à jour d'un paquet avec des corrections -dans ce paquet sont des exemples de changements sans rapport. - -@item -Suivez nos règles de formatage de code, éventuellement en lançant le script -@command{et/indent-code.el} pour le faire automatiquement (@pxref{Formatage -du code}). - -@item -Si possible, utilisez des miroirs dans l'URL des sources (@pxref{Invoquer guix download}). Utilisez des URL stable, pas des URL générées. Par -exemple, les archives GitHub ne sont pas nécessairement identiques d'une -génération à la suivante, donc il vaut mieux dans ce cas cloner le dépôt. -N'utilisez pas le champ @command{name} dans l'URL : ce n'est pas très utile -et si le nom change, l'URL sera probablement erronée. - -@end enumerate - -Lorsque vous envoyez un correctif à la liste de diffusion, utilisez -@samp{[PATCH] @dots{}} comme sujet. Vous pouvez utiliser votre client de -courriel ou la commande @command{git send-email} (@pxref{Envoyer une série -de correctifs}). Nous préférons recevoir des correctifs en texte brut, soit -en ligne, soit en pièce-jointe MIME@. Nous vous conseillons de faire -attention si votre client de courriel change par exemple les retours à la -ligne ou l'indentation, ce qui peut casser les correctifs. - -Lorsqu'un bogue est résolu, veuillez fermer le fil en envoyant un courriel à -@email{@var{NNN}-done@@debbugs.gnu.org}. - -@unnumberedsubsec Envoyer une série de correctifs -@anchor{Envoyer une série de correctifs} -@cindex série de correctifs -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -Lorsque vous envoyez une série de correctifs (p.@@:: ex.@: avec @code{git -send-email}), envoyez d'abord une premier message à -@email{guix-patches@@gnu.org} puis envoyez le reste des correctifs à -@email{@var{NNN}@@debbugs.gnu.org} pour vous assurer qu'ils seront groupés -ensemble. Voyez @uref{https://debbugs.gnu.org/Advanced.html, la -documentation de Debbugs} pour plus d'informations. diff --git a/doc/contributing.zh_CN.texi b/doc/contributing.zh_CN.texi deleted file mode 100644 index ba8a824cad..0000000000 --- a/doc/contributing.zh_CN.texi +++ /dev/null @@ -1,897 +0,0 @@ -@node 贡献 -@chapter 贡献 - -这个项目是大家合作的成果，我们需要你的帮助以更好地发展。请通过 -@email{guix-devel@@gnu.org} 和 Freenode IRC 上的 @code{#guix} 联系我们。我们欢迎 -您的想法、bug反馈、补丁，以及任何可能对项目有帮助的贡献。我们特别欢迎帮助我们打 -包（@pxref{打包指导}）。 - -@cindex 行为准则和贡献者 -@cindex 贡献者契约 -我们希望提供一个温暖、友好，并且没有骚扰的的环境，这样每个人都能尽最大努力贡献。 -为了这个目的，我们的项目遵循“贡献者契约”，这个契约是根据 -@url{http://contributor-covenant.org/}制定的。你可以在源代码目录里的 -@file{CODE-OF-CONDUCT}文件里找到一份本地版。 - -贡献者在提交补丁和网上交流时不需要使用法律认可的名字。他们可以使用任何名字或者假 -名。 - -@menu -* 从Git编译:: 最新的并且最好的. -* 在安装之前运行Guix:: 黑客技巧。 -* 完美的配置:: 正确的工具。 -* 打包指导:: Growing the distribution. -* 代码风格:: 开发者的卫生情况 -* 提交补丁:: 分享你的工作。 -@end menu - -@node 从Git编译 -@section 从Git编译 - -如果你想折腾Guix本身，建议使用Git仓库里最新的版本： - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -当从Git检出构建Guix时，除安装指导（@pxref{Requirements}）里提及的软件包之外还需 -要这些包。 - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man （可选）}。 -@end itemize - -设置Guix开发环境的最简单的方式当然是使用Guix！下面这些命令启动一个shell，所有的 -依赖和环境变量都为折腾Guix设置好了： - -@example -guix environment guix -@end example - -这个命令更多的信息请参考@xref{Invoking guix environment}。额外的依赖可以通过 -@option{--ad-hoc}选项添加： - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -运行 @command{./bootstrap} 以使用Autoconf和Automake生成编译系统的基础框架。如果 -你的得到这样的错误： - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -它可能意味着Autoconf无法找到由pkg-config提供的@file{pkg.m4}。请确保@file{pkg.m4} -可用。由Guile提供的@file{guile.m4}宏也类似。假如你的Automake安装在 -@file{/usr/local}，那么它不会从@file{/usr/share}里寻找@file{.m4}文件。这种情况下， -你必须执行下面这个命令： - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -参考@xref{Macro Search Path,,, automake, The GNU Automake Manual}. - -然后，像正常一样运行@command{./configure}。确保提供 -@code{--localstatedir=@var{directory}}参数，@var{directory}是你当前系统的 -@code{localstatedir}的值。（@pxref{The Store}） - -最后，用@code{make check}执行测试（@pxref{Running the Test Suite}）。如果遇到任 -何错误，请参考“安装指导”（@pxref{Installation}）或者给 -@email{guix-devel@@gnu.org, 邮件列表}发邮件。 - - -@node 在安装之前运行Guix -@section 在安装之前运行Guix - -为了保持一个合适的工作环境，你会发现在你的本地代码树里测试修改而不用安装它们会很 -有用。TODO: So that you can distinguish between your ``end-user'' hat and your -``motley'' costume. - -这样，即使你没有运行@code{make install}，所有的命令行工具都可以使用。为此，你先 -要有一个包含全部依赖的环境（@pxref{从Git编译}），然后，为所有的命令添加 -前缀@command{./pre-inst-env}（@file{pre-inst-env}脚本在Guix编译树的最顶层，它由 -@command{./configure}生成），如@footnote{@command{sudo}命令的@option{-E}参数 -确保@code{GUILE_LOAD_PATH}被正确设置，从而@command{guix-daemon}和它使用的工具可 -以找到它们需要的Guile模块。}： - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -类似的，对于使用Guix模块的Guile会话： - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex read-eval-print loop -@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}): - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define snakes - (fold-packages - (lambda (package lst) - (if (string-prefix? "python" - (package-name package)) - (cons package lst) - lst)) - '())) -scheme@@(guile-user)> (length snakes) -$1 = 361 -@end example - -@command{pre-inst-env}脚本设置为此好了所有必要的的环境变量，包括@env{PATH}和 -@env{GUILE_LOAD_PATH}。 - -@command{./pre-inst-env guix pull} @emph{不} 会更新本地源代码树，它只更新符号链 -接@file{~/.config/guix/current} (@pxref{Invoking guix pull})。如果你想更新本地源 -代码树，请运行@command{git pull}。 - - -@node 完美的配置 -@section 完美的配置 - -折腾Guix的完美配置也是折腾Guile的完美配置@pxref{Using Guile in Emacs,,, guile, -Guile Reference Manual})。首先，你需要的不仅是一个编辑器，你需要 -@url{http://www.gnu.org/software/emacs, Emacs}，以及美妙的 -@url{http://nongnu.org/geiser/, Geiser}。为此，请运行： - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser允许在Emacs里进行交互式的、增长式的开发：buffer里的代码补全和执行，获取一 -行的文档（docstrings），上下文敏感的补全，@kbd{M-.}跳转到对象定义，测试代码的 -REPL，及更多（@pxref{Introduction,,, geiser, Geiser User Manual}）。为了方便的 -Guix开发，请确保修改Guile的加载路径（load path）以使其能从你的项目里找到源代码文 -件。 - -@lisp -;; @r{假设Guix项目在 ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -真正编辑代码时别忘了Emacs自带了方便的Scheme模式。而且，一定不要错过 -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}。它提供了直接操作语法树的 -的功能，例如，用S-表达式替换父节点，为S-表达式添加、删除前后的括号，删除后面的S- -表达式，等等。 - -@cindex 代码片段 -@cindex 模板 -@cindex reducing boilerplate -在@file{etc/snippets}文件夹里，我们还为普通的git commit信息和软件包定义提供模板。 -这些模板可以通过@url{http://joaotavora.github.io/yasnippet/, YASnippet}使用，它 -可以把短的触发字符串扩展成交互式的文字片段。你可能希望将这个文件夹添加到Emacs的 -@var{yas-snippet-dirs}变量里。 - -@lisp -;; @r{假设Guix项目在 ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -commit信息片段显示staged文件需要依赖@url{https://magit.vc/, Magit}。编辑commit信 -息时，输入@code{add}，然后按@kbd{TAB}就可以插入一段用于新增软件包的模板；输入 -@code{update}，然后按@kbd{TAB}可以插入一段更新软件包的模板；输入@code{https}然后 -按@kbd{TAB}可以插入一段修改主页URI为HTTPS的模板。 - -@code{scheme-mode}最重要的模板可以通过输入@code{package...}，然后按@kbd{TAB}触发。 -这个片段还插入了触发字符串@code{origin...}，以进一步展开。@code{origin}片段更进 -一步的可能插入其它以@code{...}结尾的触发字符串，它们可以被继续展开。 - - -@node 打包指导 -@section 打包指导 - -@cindex 软件包, 创建 -这个GNU发行版正在开发的早期阶段，可能缺少一些你喜欢的软件。这个章节介绍你可以怎 -样帮助这个发行版成长。 - -自由软件通常以@dfn{源代码包}的形式分发，通常是包含完整代码的@file{tar.gz}包。添 -加软件包到这个发行版意味着两件事：添加描述如何编译包的@dfn{配方}和一系列依赖软件， -以及添加配方之外的@dfn{软件包元数据}，如一段文字描述和证书信息。 - -在Guix里所有这些信息都包含在@dfn{软件包定义}里。软件包定义提供了软件包的高层视角。 -它们使用Scheme编程语言编写，事实上，对每个软件包我们都定义一个绑定到软件包定义的 -的变量，并且从模块（@pxref{Package Modules}）中导出那个变量。然而，深入的Scheme -知识@emph{不}是创建软件包的前提条件。若要了解软件包的更多信息，@pxref{Defining -Packages}。 - -一旦软件包定义准备好了，并且包存在Guix代码树的一个文件里，你可以用@command{guix -build} (@pxref{Invoking guix build})命令测试它。假设这个新软件包的名字叫做 -@code{gnew}，你可以在Guix编译树里运行这个命令(@pxref{在安装之前运行Guix})： - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -使用@code{--keep-failed}参数会保留失败的编译树，这可以使调试编译错误更容易。 -@code{--log-file}也是一个调试时很有用的参数，它可以用来访问编译日志。 - -如果@command{guix}命令找不到这个软件包，那可能是因为源文件包含语法错误，或者缺少 -导出软件包的@code{define-public}语句。为了查找错误，你可以用Guile导入这个模块以 -了解这个错误的详情： - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -一旦你的软件包可以正确编译，请给我们发送补丁（@pxref{提交补丁}）。当然， -如果你需要帮助，我们也会很乐意帮助你。一旦补丁被提交到Guix仓库里，这个新的软件包 -会被自动地在支持的平台上编译@url{http://hydra.gnu.org/jobset/gnu/master, our -continuous integration system}。 - -@cindex substituter -用户可以通过运行@command{guix pull}命令获取最新的软件包定义（@pxref{Invoking -guix pull}）。当@code{@value{SUBSTITUTE-SERVER}}编译好这些软件包之后，安装这些软 -件包时会自动从服务器（@pxref{Substitutes}）上下载编译好的二进制包。唯一需要人工 -干预的地方是评审和应用代码补丁。 - - -@menu -* 软件自由:: 什么可以进入这个发行版。 -* 软件包命名:: 名字里包含什么？ -* 版本号:: 当名字不够时 -* 简介和描述:: 帮助用户寻找合适的软件包 -* Python模块:: 接触英式的喜剧 -* Perl模块:: 小珍珠。 -* Java包:: 喝咖啡休息。 -* 字体:: 字体的乐趣。 -@end menu - -@node 软件自由 -@subsection 软件自由 - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex 自由软件 -开发GNU操作系统是为了用户拥有计算的自由。GNU是@dfn{自由软件}，这意味着它有 -@url{http://www.gnu.org/philosophy/free-sw.html,四项重要的自由}：运行程序的自由， -以源代码形式学习和修改程序的自由，原样重新分发副本的自由，和分发修改后的版本的自 -由。GNU发行版里包含的软件包只提供遵守这四项自由的软件。 - -此外，GNU发行版遵循 -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,自由软 -件发行版准则}。这些准则拒绝非自由的固件和对非自由软件的推荐，并讨论解决商标和专 -利的方法。 - -某些上游的软件包源代码包含一小部分违反上述准则的可选的子集，比如这个子集本身就是 -非自由代码。这时，这些讨厌的代码需要用合适的补丁或者软件包定义（@pxref{Defining -Packages}）里的@code{origin}里的代码片段移除。这样，@code{guix build --source}就 -可以返回自由的源代码而不是未经修改的上游源代码。 - - -@node 软件包命名 -@subsection 软件包命名 - -@cindex 软件包名字 -一个软件包事实上有两个名字：第一个是@emph{Scheme变量}的名字，即用 -@code{define-public}定义的名字。通过这个名字，软件包可以被Scheme代码找到，如用作 -其它软件包的输入。第二个名字是软件包定义里的@code{name}属性的字符串值。这个名字 -用于软件包管理命令，如：@command{guix package}，@command{guix build} - -两个名字通常是相同的，常是上游项目名字转成小写字母并把下划线替换成连字符的结果。 -比如，GNUnet转成@code{gnunet}，SDL_net转成@code{sdl-net}。 - -我们不给库软件包添加@code{lib}前缀，除非它是项目官方名字的一部分。但是 -@pxref{Python模块}和@ref{Perl模块}有关于Python和Perl语言的特殊规则。 - -字体软件包的名字处理起来不同，@pxref{字体}. - - -@node 版本号 -@subsection 版本号 - -@cindex 软件包版本 -我们通常只为每个自由软件的最新版本打包。但是有时候，比如对于版本不兼容的库，需要 -有同一个软件包的两个或更多版本。它们需要使用不同的Scheme变量名。我们为最新的版本 -使用@ref{软件包命名}里规定的名字，旧的版本使用加上后缀的名字，后缀是@code{-} -和可以区分开版本号的版本号的最小前缀。 - -软件包定义里的名字对于同一个软件包的所有版本都是相同的，并且不含有版本号。 - -例如，GTK+的2.24.20和3.9.12两个版本可以这样打包： - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -如果我们还需要GTK+ 3.8.2，就这样打包 -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See , -@c for a discussion of what follows. -@cindex 用于版本控制快照的版本号 -有时候，我们为软件包上游的版本控制系统（VCS）的快照而不是正式发布版打包。这是特 -殊情况，因为决定哪个是稳定版的权力应该属于上游开发者。然而，有时候这是必须的。那 -么，我们该如何决定写在@code{version}里的版本号呢？ - -显然，我们需要让VCS快照的commit ID在版本号中体现出来，但是我们也需要确保版本号单 -调递增，以便@command{guix package --upgrade}决定哪个版本号更新。由于commit ID， -尤其是Git的commit ID，不是单调递增的，我们添加一个每次升级快照时都手动增长的 -revision数字。最后的版本号字符串看起来是这样： - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- 上游的commit ID - | | - | `--- Guix软件包的revision - | -最新的上游版本号 -@end example - -把@code{版本号}里的commit ID截短，比如只取7个数字，是一个好主意。它避免了美学上 -的烦恼（假设美学在这里很重要），以及操作系统限制引起的问题（比如Linux内核的127字 -节）。尽管如此，在@code{origin}里最好使用完整的commit ID，以避免混淆。 - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Guix软件包的revision - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/my-package.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node 简介和描述 -@subsection 简介和描述 - -@cindex 软件包描述 -@cindex 软件包简介 -我们已经看到，GNU@tie{}Guix里的每个软件包都包含一个简介（synopsis）和一个描述 -（description）（@pxref{Defining Packages}）。简介和描述很重要：它们是 -@command{guix package --search}搜索的信息，并且是帮助用户决定一个软件包是否符合 -自己需求的重要信息。因此，打包的人应该关注怎样写它们的内容。 - -简介必须以大写字母开头，并且不能以句号结尾。它们不能以 ``a'' 或者 ``the'' 等没有 -意义的词开头。例如 ``File-frobbing tool'' 要比 ``A tool that frobs files'' 更好。 -简介需要说明软件包是什么－－如 ``Core GNU utilities (file, text, shell)''，或者 -它的用途－－如 GNU@tie{}grep 的简介是 ``Print lines matching a pattern''。 - -Keep in mind that the synopsis must be meaningful for a very wide audience. -For example, ``Manipulate alignments in the SAM format'' might make sense -for a seasoned bioinformatics researcher, but might be fairly unhelpful or -even misleading to a non-specialized audience. It is a good idea to come up -with a synopsis that gives an idea of the application domain of the -package. In this example, this might give something like ``Manipulate -nucleotide sequence alignments'', which hopefully gives the user a better -idea of whether this is what they are looking for. - -Descriptions should take between five and ten lines. Use full sentences, -and avoid using acronyms without first introducing them. Please avoid -marketing phrases such as ``world-leading'', ``industrial-strength'', and -``next-generation'', and avoid superlatives like ``the most -advanced''---they are not helpful to users looking for a package and may -even sound suspicious. Instead, try to be factual, mentioning use cases and -features. - -@cindex Texinfo markup, in package descriptions -Descriptions can include Texinfo markup, which is useful to introduce -ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks -(@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful -when using some characters for example @samp{@@} and curly braces which are -the basic special characters in Texinfo (@pxref{Special Characters,,, -texinfo, GNU Texinfo}). User interfaces such as @command{guix package ---show} take care of rendering it appropriately. - -Synopses and descriptions are translated by volunteers -@uref{http://translationproject.org/domain/guix-packages.html, at the -Translation Project} so that as many users as possible can read them in -their native language. User interfaces search them and display them in the -language specified by the current locale. - -To allow @command{xgettext} to extract them as translatable strings, -synopses and descriptions @emph{must be literal strings}. This means that -you cannot use @code{string-append} or @code{format} to construct these -strings: - -@lisp -(package - ;; @dots{} - (synopsis "This is translatable") - (description (string-append "This is " "*not*" " translatable."))) -@end lisp - -Translation is a lot of work so, as a packager, please pay even more -attention to your synopses and descriptions as every change may entail -additional work for translators. In order to help them, it is possible to -make recommendations or instructions visible to them by inserting special -comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}): - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Python模块 -@subsection Python模块 - -@cindex python -We currently package Python 2 and Python 3, under the Scheme variable names -@code{python-2} and @code{python} as explained in @ref{版本号}. To -avoid confusion and naming clashes with other programming languages, it -seems desirable that the name of a package for a Python module contains the -word @code{python}. - -Some modules are compatible with only one version of Python, others with -both. If the package Foo compiles only with Python 3, we name it -@code{python-foo}; if it compiles only with Python 2, we name it -@code{python2-foo}. If it is compatible with both versions, we create two -packages with the corresponding names. - -If a project already contains the word @code{python}, we drop this; for -instance, the module python-dateutil is packaged under the names -@code{python-dateutil} and @code{python2-dateutil}. If the project name -starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as -described above. - -@subsubsection Specifying Dependencies -@cindex inputs, for Python packages - -Dependency information for Python packages is usually available in the -package source tree, with varying degrees of accuracy: in the -@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. - -Your mission, when writing a recipe for a Python package, is to map these -dependencies to the appropriate type of ``input'' (@pxref{package Reference, -inputs}). Although the @code{pypi} importer normally does a good job -(@pxref{Invoking guix import}), you may want to check the following check -list to determine which dependency goes where. - -@itemize - -@item -We currently package Python 2 with @code{setuptools} and @code{pip} -installed like Python 3.4 has per default. Thus you don't need to specify -either of these as an input. @command{guix lint} will warn you if you do. - -@item -Python dependencies required at run time go into @code{propagated-inputs}. -They are typically defined with the @code{install_requires} keyword in -@file{setup.py}, or in the @file{requirements.txt} file. - -@item -Python packages required only at build time---e.g., those listed with the -@code{setup_requires} keyword in @file{setup.py}---or only for -testing---e.g., those in @code{tests_require}---go into -@code{native-inputs}. The rationale is that (1) they do not need to be -propagated because they are not needed at run time, and (2) in a -cross-compilation context, it's the ``native'' input that we'd want. - -Examples are the @code{pytest}, @code{mock}, and @code{nose} test -frameworks. Of course if any of these packages is also required at -run-time, it needs to go to @code{propagated-inputs}. - -@item -Anything that does not fall in the previous categories goes to -@code{inputs}, for example programs or C libraries required for building -Python packages containing C extensions. - -@item -If a Python package has optional dependencies (@code{extras_require}), it is -up to you to decide whether to add them or not, based on their -usefulness/overhead ratio (@pxref{提交补丁, @command{guix size}}). - -@end itemize - - -@node Perl模块 -@subsection Perl模块 - -@cindex perl -Perl programs standing for themselves are named as any other package, using -the lowercase upstream name. For Perl packages containing a single class, -we use the lowercase class name, replace all occurrences of @code{::} by -dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser} -becomes @code{perl-xml-parser}. Modules containing several classes keep -their lowercase upstream name and are also prepended by @code{perl-}. Such -modules tend to have the word @code{perl} somewhere in their name, which -gets dropped in favor of the prefix. For instance, @code{libwww-perl} -becomes @code{perl-libwww}. - - -@node Java包 -@subsection Java包 - -@cindex java -Java programs standing for themselves are named as any other package, using -the lowercase upstream name. - -To avoid confusion and naming clashes with other programming languages, it -is desirable that the name of a package for a Java package is prefixed with -@code{java-}. If a project already contains the word @code{java}, we drop -this; for instance, the package @code{ngsjava} is packaged under the name -@code{java-ngs}. - -For Java packages containing a single class or a small class hierarchy, we -use the lowercase class name, replace all occurrences of @code{.} by dashes -and prepend the prefix @code{java-}. So the class @code{apache.commons.cli} -becomes package @code{java-apache-commons-cli}. - - -@node 字体 -@subsection 字体 - -@cindex fonts -For fonts that are in general not installed by a user for typesetting -purposes, or that are distributed as part of a larger software package, we -rely on the general packaging rules for software; for instance, this applies -to the fonts delivered as part of the X.Org system or fonts that are part of -TeX Live. - -To make it easier for a user to search for fonts, names for other packages -containing only fonts are constructed as follows, independently of the -upstream package name. - -The name of a package containing only one font family starts with -@code{font-}; it is followed by the foundry name and a dash @code{-} if the -foundry is known, and the font family name, in which spaces are replaced by -dashes (and as usual, all upper case letters are transformed to lower -case). For example, the Gentium font family by SIL is packaged under the -name @code{font-sil-gentium}. - -For a package containing several font families, the name of the collection -is used in the place of the font family name. For instance, the Liberation -fonts consist of three families, Liberation Sans, Liberation Serif and -Liberation Mono. These could be packaged separately under the names -@code{font-liberation-sans} and so on; but as they are distributed together -under a common name, we prefer to package them together as -@code{font-liberation}. - -In the case where several formats of the same font family or font collection -are packaged separately, a short form of the format, prepended by a dash, is -added to the package name. We use @code{-ttf} for TrueType fonts, -@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 -fonts. - - -@node 代码风格 -@section 代码风格 - -In general our code follows the GNU Coding Standards (@pxref{Top,,, -standards, GNU Coding Standards}). However, they do not say much about -Scheme, so here are some additional rules. - -@menu -* Programming Paradigm:: How to compose your elements. -* Modules:: Where to store your code? -* Data Types and Pattern Matching:: Implementing data structures. -* Formatting Code:: Writing conventions. -@end menu - -@node Programming Paradigm -@subsection Programming Paradigm - -Scheme code in Guix is written in a purely functional style. One exception -is code that involves input/output, and procedures that implement low-level -concepts, such as the @code{memoize} procedure. - -@node Modules -@subsection Modules - -Guile modules that are meant to be used on the builder side must live in the -@code{(guix build @dots{})} name space. They must not refer to other Guix -or GNU modules. However, it is OK for a ``host-side'' module to use a -build-side module. - -Modules that deal with the broader GNU system should be in the @code{(gnu -@dots{})} name space rather than @code{(guix @dots{})}. - -@node Data Types and Pattern Matching -@subsection Data Types and Pattern Matching - -The tendency in classical Lisp is to use lists to represent everything, and -then to browse them ``by hand'' using @code{car}, @code{cdr}, @code{cadr}, -and co. There are several problems with that style, notably the fact that -it is hard to read, error-prone, and a hindrance to proper type error -reports. - -Guix code should define appropriate data types (for instance, using -@code{define-record-type*}) rather than abuse lists. In addition, it should -use pattern matching, via Guile’s @code{(ice-9 match)} module, especially -when matching lists. - -@node Formatting Code -@subsection Formatting Code - -@cindex formatting code -@cindex coding style -When writing Scheme code, we follow common wisdom among Scheme programmers. -In general, we follow the @url{http://mumble.net/~campbell/scheme/style.txt, -Riastradh's Lisp Style Rules}. This document happens to describe the -conventions mostly used in Guile’s code too. It is very thoughtful and well -written, so please do read it. - -Some special forms introduced in Guix, such as the @code{substitute*} macro, -have special indentation rules. These are defined in the -@file{.dir-locals.el} file, which Emacs automatically uses. Also note that -Emacs-Guix provides @code{guix-devel-mode} mode that indents and highlights -Guix code properly (@pxref{Development,,, emacs-guix, The Emacs-Guix -Reference Manual}). - -@cindex indentation, of code -@cindex formatting, of code -If you do not use Emacs, please make sure to let your editor knows these -rules. To automatically indent a package definition, you can also run: - -@example -./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} -@end example - -@noindent -This automatically indents the definition of @var{package} in -@file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To -indent a whole file, omit the second argument: - -@example -./etc/indent-code.el gnu/services/@var{file}.scm -@end example - -@cindex Vim, Scheme code editing -If you are editing code with Vim, we recommend that you run @code{:set -autoindent} so that your code is automatically indented as you type. -Additionally, @uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} may help you deal with all these parentheses. - -We require all top-level procedures to carry a docstring. This requirement -can be relaxed for simple private procedures in the @code{(guix build -@dots{})} name space, though. - -Procedures should not have more than four positional parameters. Use -keyword parameters for procedures that take more than four parameters. - - -@node 提交补丁 -@section 提交补丁 - -Development is done using the Git distributed version control system. Thus, -access to the repository is not strictly necessary. We welcome -contributions in the form of patches as produced by @code{git format-patch} -sent to the @email{guix-patches@@gnu.org} mailing list. - -This mailing list is backed by a Debbugs instance accessible at -@uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track of -submissions. Each message sent to that mailing list gets a new tracking -number assigned; people can then follow up on the submission by sending -email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking -number (@pxref{Sending a Patch Series}). - -Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, -standards, GNU Coding Standards}); you can check the commit history for -examples. - -Before submitting a patch that adds or modifies a package definition, please -run through this check list: - -@enumerate -@item -If the authors of the packaged software provide a cryptographic signature -for the release tarball, make an effort to verify the authenticity of the -archive. For a detached GPG signature file this would be done with the -@code{gpg --verify} command. - -@item -Take some time to provide an adequate synopsis and description for the -package. @xref{简介和描述}, for some guidelines. - -@item -Run @code{guix lint @var{package}}, where @var{package} is the name of the -new or modified package, and fix any errors it reports (@pxref{Invoking guix -lint}). - -@item -Make sure the package builds on your platform, using @code{guix build -@var{package}}. - -@item -We recommend you also try building the package on other supported -platforms. As you may not have access to actual hardware platforms, we -recommend using the @code{qemu-binfmt-service-type} to emulate them. In -order to enable it, add the following service to the list of services in -your @code{operating-system} configuration: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) - (guix-support? #t))) -@end example - -Then reconfigure your system. - -You can then build packages for different platforms by specifying the -@code{--system} option. For example, to build the "hello" package for the -armhf, aarch64, or mips64 architectures, you would run the following -commands, respectively: -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex bundling -Make sure the package does not use bundled copies of software already -available as separate packages. - -Sometimes, packages include copies of the source code of their dependencies -as a convenience for users. However, as a distribution, we want to make -sure that such packages end up using the copy we already have in the -distribution, if there is one. This improves resource usage (the dependency -is built and stored only once), and allows the distribution to make -transverse changes such as applying security updates for a given software -package in a single place and have them affect the whole system---something -that bundled copies prevent. - -@item -Take a look at the profile reported by @command{guix size} (@pxref{Invoking -guix size}). This will allow you to notice references to other packages -unwillingly retained. It may also help determine whether to split the -package (@pxref{Packages with Multiple Outputs}), and which optional -dependencies should be used. In particular, avoid adding @code{texlive} as -a dependency: because of its extreme size, use @code{texlive-tiny} or -@code{texlive-union} instead. - -@item -For important changes, check that dependent package (if applicable) are not -affected by the change; @code{guix refresh --list-dependent @var{package}} -will help you do that (@pxref{Invoking guix refresh}). - -@c See . -@cindex branching strategy -@cindex rebuild scheduling strategy -Depending on the number of dependent packages and thus the amount of -rebuilding induced, commits go to different branches, along these lines: - -@table @asis -@item 300 dependent packages or less -@code{master} branch (non-disruptive changes). - -@item between 300 and 1,200 dependent packages -@code{staging} branch (non-disruptive changes). This branch is intended to -be merged in @code{master} every 3 weeks or so. Topical changes (e.g., an -update of the GNOME stack) can instead go to a specific branch (say, -@code{gnome-updates}). - -@item more than 1,200 dependent packages -@code{core-updates} branch (may include major and potentially disruptive -changes). This branch is intended to be merged in @code{master} every 2.5 -months or so. -@end table - -All these branches are @uref{https://hydra.gnu.org/project/gnu, tracked by -our build farm} and merged into @code{master} once everything has been -successfully built. This allows us to fix issues before they hit users, and -to reduce the window during which pre-built binaries are not available. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Generally, branches other than @code{master} are considered @emph{frozen} if -there has been a recent evaluation, or there is a corresponding @code{-next} -branch. Please ask on the mailing list or IRC if unsure where to place a -patch. - -@item -@cindex determinism, of build processes -@cindex reproducible builds, checking -Check whether the package's build process is deterministic. This typically -means checking whether an independent build of the package yields the exact -same result that you obtained, bit for bit. - -A simple way to do that is by building the same package several times in a -row on your machine (@pxref{Invoking guix build}): - -@example -guix build --rounds=2 my-package -@end example - -This is enough to catch a class of common non-determinism issues, such as -timestamps or randomly-generated output in the build result. - -Another option is to use @command{guix challenge} (@pxref{Invoking guix -challenge}). You may run it once the package has been committed and built -by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same -result as you did. Better yet: Find another machine that can build it and -run @command{guix publish}. Since the remote build machine is likely -different from yours, this can catch non-determinism issues related to the -hardware---e.g., use of different instruction set extensions---or to the -operating system kernel---e.g., reliance on @code{uname} or @file{/proc} -files. - -@item -When writing documentation, please use gender-neutral wording when referring -to people, such as @uref{https://en.wikipedia.org/wiki/Singular_they, -singular ``they''@comma{} ``their''@comma{} ``them''}, and so forth. - -@item -Verify that your patch contains only one set of related changes. Bundling -unrelated changes together makes reviewing harder and slower. - -Examples of unrelated changes include the addition of several packages, or a -package update along with fixes to that package. - -@item -Please follow our code formatting rules, possibly running the -@command{etc/indent-code.el} script to do that automatically for you -(@pxref{Formatting Code}). - -@item -When possible, use mirrors in the source URL (@pxref{Invoking guix -download}). Use reliable URLs, not generated ones. For instance, GitHub -archives are not necessarily identical from one generation to the next, so -in this case it's often better to clone the repository. Don't use the -@command{name} field in the URL: it is not very useful and if the name -changes, the URL will probably be wrong. - -@end enumerate - -When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a -subject. You may use your email client or the @command{git send-email} -command (@pxref{Sending a Patch Series}). We prefer to get patches in plain -text messages, either inline or as MIME attachments. You are advised to pay -attention if your email client changes anything like line breaks or -indentation which could potentially break the patches. - -When a bug is resolved, please close the thread by sending an email to -@email{@var{NNN}-done@@debbugs.gnu.org}. - -@unnumberedsubsec Sending a Patch Series -@anchor{Sending a Patch Series} -@cindex patch series -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -When sending a patch series (e.g., using @code{git send-email}), please -first send one message to @email{guix-patches@@gnu.org}, and then send -subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they -are kept together. See @uref{https://debbugs.gnu.org/Advanced.html, the -Debbugs documentation} for more information. diff --git a/doc/guix.de.texi b/doc/guix.de.texi deleted file mode 100644 index 419d40379e..0000000000 --- a/doc/guix.de.texi +++ /dev/null @@ -1,26536 +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, -2019 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, 2019 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 (siehe @ref{Top,,, guix, GNU Guix -Reference Manual}) und Französisch verfügbar (siehe @ref{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. -* Entwicklung:: Von Guix unterstützte Softwareentwicklung. -* 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 - - - -* Auf Guix-Art Software verwalten:: Was Guix besonders macht. -* GNU-Distribution:: Die Pakete und Werkzeuge. - -Installation - - - -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Den Testkatalog 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. -* Geführte grafische Installation:: Leichte grafische Installation. -* Manuelle Installation:: Manuelle Installation für Zauberer. -* Nach der Systeminstallation:: Wenn die Installation erfolgreich war. -* Guix in einer VM installieren:: Ein »Guix System«-Spielplatz. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. - -Manuelle Installation - - - -* Tastaturbelegung und Netzwerkanbindung und Partitionierung:: Erstes - Einrichten. -* Fortfahren mit der Installation:: Installieren. - -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? - -Entwicklung - - - -* 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 kryptografischen 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:: Plattenplatzverbrauch 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. -* Tastaturbelegung:: Wie das System Tastendrücke interpretiert. -* 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. -* Guix in einer VM starten:: Wie man »Guix System« in einer virtuellen - Maschine startet. -* 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« wird wie »geeks« ausgesprochen, also als »ɡiːks« in -der Notation des Internationalen Phonetischen Alphabets (IPA).} ist ein -Werkzeug zur Verwaltung von Softwarepaketen für das GNU-System und eine -Distribution desselbigen GNU-Systems. Guix macht es @emph{nicht} mit -besonderen Berechtigungen ausgestatteten, »unprivilegierten« Nutzern leicht, -Softwarepakete zu installieren, zu aktualisieren oder zu entfernen, zu einem -vorherigen Satz von Paketen zurückzuwechseln, Pakete aus ihrem Quellcode -heraus zu erstellen und hilft allgemein bei der Erzeugung und Wartung von -Software-Umgebungen. - -@cindex Guix System -@cindex GuixSD, was jetzt Guix System heißt -@cindex Guix System Distribution, welche jetzt Guix System heißt -Sie können GNU@tie{}Guix auf ein bestehendes GNU/Linux-System aufsetzen, wo -es die bereits verfügbaren Werkzeuge ergänzt, ohne zu stören (siehe -@ref{Installation}), oder Sie können es als eine eigenständige -Betriebssystem-Distribution namens @dfn{Guix@tie{}System} -verwenden@footnote{Der Name @dfn{Guix@tie{}System} wird auf englische Weise -ausgesprochen. Früher hatten wir »Guix System« als »Guix System -Distribution« bezeichnet und mit »GuixSD« abgekürzt. Wir denken mittlerweile -aber, dass es sinnvoller ist, alles unter der Fahne von Guix zu gruppieren, -weil schließlich »Guix System« auch über den Befehl @command{guix system} -verfügbar ist, selbst wenn Sie Guix auf einer fremden Distribution -benutzen!}. Siehe @ref{GNU-Distribution}. - -@menu -* Auf Guix-Art Software verwalten:: Was Guix besonders macht. -* GNU-Distribution:: Die Pakete und Werkzeuge. -@end menu - -@node Auf Guix-Art Software verwalten -@section Auf Guix-Art Software verwalten - -@cindex Benutzeroberflächen -Guix bietet eine befehlszeilenbasierte Paketverwaltungsschnittstelle (siehe -@ref{Aufruf von guix package}), Werkzeuge als Hilfestellung bei der -Software-Entwicklung (siehe @ref{Entwicklung}), Befehlszeilenwerkzeuge für -fortgeschrittenere Nutzung (siehe @ref{Zubehör}) sowie Schnittstellen zur -Programmierung in Scheme (siehe @ref{Programmierschnittstelle}). -@cindex Erstellungs-Daemon -Der @dfn{Erstellungs-Daemon} ist für das Erstellen von Paketen im Auftrag -von Nutzern verantwortlich (siehe @ref{Den Daemon einrichten}) und für das -Herunterladen vorerstellter Binärdateien aus autorisierten Quellen (siehe -@ref{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 (siehe @ref{Pakete definieren}) und sie -als unabhängige Paketmodule verfügbar machen (siehe @ref{Paketmodule}). Es ist auch @emph{anpassbar}: Nutzer können spezialisierte -Paketdefinitionen aus bestehenden @emph{ableiten}, auch von der Befehlszeile -(siehe @ref{Paketumwandlungsoptionen}). - -@cindex funktionale Paketverwaltung -@cindex Isolierung -Intern implementiert Guix die Disziplin der @dfn{funktionalen -Paketverwaltung}, zu der Nix schon die Pionierarbeit geleistet hat (siehe -@ref{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 (siehe @ref{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ücksetzungen, Installation von Paketen als einfacher Nutzer sowie -Garbage Collection für Pakete (siehe @ref{Funktionalitäten}). - - -@node GNU-Distribution -@section GNU-Distribution - -@cindex Guix System -Mit Guix kommt eine Distribution des GNU-Systems, die nur aus freier -Software@footnote{Die Bezeichnung »frei« steht hier für die -@url{http://www.gnu.org/philosophy/free-sw.html,Freiheiten, die Nutzern der -Software geboten werden}.} besteht. Die Distribution kann für sich allein -installiert werden (siehe @ref{Systeminstallation}), aber Guix kann auch -auf einem bestehenden GNU/Linux-System installiert werden. Wenn wir die -Anwendungsfälle unterscheiden möchten, bezeichnen wir die alleinstehende -Distribution als »Guix@tie{}System« (mit englischer Aussprache). - -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 (siehe -@ref{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 -@ref{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 - -Mit Guix@tie{}System @emph{deklarieren} Sie alle Aspekte der -Betriebssystemkonfiguration und Guix kümmert sich darum, die Konfiguration -auf transaktionsbasierte, reproduzierbare und zustandslose Weise zu -instanziieren (siehe @ref{Systemkonfiguration}). Guix System benutzt den -Kernel Linux-libre, das Shepherd-Initialisierungssystem (siehe -@ref{Einführung,,, shepherd, The GNU Shepherd Manual}), die wohlbekannten -GNU-Werkzeuge mit der zugehörigen Werkzeugkette sowie die grafische Umgebung -und Systemdienste Ihrer Wahl. - -Guix System ist auf allen oben genannten Plattformen außer -@code{mips64el-linux} verfügbar. - -@noindent -Informationen, wie auf andere Architekturen oder Kernels portiert werden -kann, finden Sie im Abschnitt @ref{Portierung}. - -Diese Distribution aufzubauen basiert auf Kooperation, und Sie sind herzlich -eingeladen, dabei mitzumachen! Im Abschnitt @ref{Mitwirken} stehen -weitere Informationen, wie Sie uns helfen können. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex Guix installieren - -@quotation Anmerkung -Wir empfehlen, dieses -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -Shell-basierte Installationsskript} zu benutzen, um Guix auf ein bestehendes -GNU/Linux-System zu installieren — im Folgenden als @dfn{Fremddistribution} -bezeichnet.@footnote{Dieser Abschnitt bezieht sich auf die Installation des -Paketverwaltungswerkzeugs, das auf ein bestehendes GNU/Linux-System -aufsetzend installiert werden kann. Wenn Sie stattdessen das vollständige -GNU-Betriebssystem installieren möchten, lesen Sie @ref{Systeminstallation}.} Das Skript automatisiert das Herunterladen, das Installieren -und die anfängliche Konfiguration von Guix. Es sollte als der -Administratornutzer »root« ausgeführt werden. -@end quotation - -@cindex Fremddistribution -@cindex Verzeichnisse auf einer Fremddistribution -Wenn es auf einer Fremddistribution installiert wird, ergänzt GNU@tie{}Guix -die verfügbaren Werkzeuge, ohne dass sie sich gegenseitig stören. Guix’ -Daten befinden sich ausschließlich in zwei Verzeichnissen, üblicherweise -@file{/gnu/store} und @file{/var/guix}; andere Dateien auf Ihrem System wie -@file{/etc} bleiben unberührt. - -Sobald es installiert ist, kann Guix durch Ausführen von @command{guix pull} -aktualisiert werden (siehe @ref{Aufruf von guix pull}). - -Sollten Sie es vorziehen, die Installationsschritte manuell durchzuführen, -oder falls Sie Anpassungen daran vornehmen möchten, könnten sich die -folgenden Unterabschnitte als nützlich erweisen. Diese beschreiben die -Software-Voraussetzungen von Guix und wie man es manuell installiert, so -dass man es benutzen kann. - -@menu -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Den Testkatalog 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} (siehe @ref{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 (siehe @ref{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 (siehe @ref{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.de} dieses Handbuch öffnen (siehe @ref{Other Info -Directories,,, texinfo, GNU Texinfo} hat weitere Details, wie Sie den -Info-Suchpfad ändern können). - -@item -@cindex Substitute, deren Autorisierung -Um Substitute von @code{@value{SUBSTITUTE-SERVER}} oder einem Spiegelserver -davon zu benutzen (siehe @ref{Substitute}), müssen sie erst autorisiert -werden: - -@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 @ref{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 -…@: was wiederum dies ausführt: - -@example -guix pack -s @var{System} --localstatedir \ - --profile-name=current-guix guix -@end example - -Siehe @ref{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 kann von seiner Webpräsenz unter -@url{http://www.gnu.org/software/guix/} heruntergeladen werden. - -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 Anbindungen für -Guile (siehe @ref{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 (siehe @ref{Auslagern des Daemons einrichten}) und @command{guix copy} (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 Den Testkatalog laufen lassen -@section Den Testkatalog 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 (siehe -@ref{Voraussetzungen}). - -Guix wird auch mit einem Testkatalog für das ganze System ausgeliefert, der -vollständige Instanzen des »Guix System«-Betriebssystems testet. Er kann nur -auf Systemen benutzt werden, auf denen Guix bereits installiert ist, mit -folgendem Befehl: - -@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 -(siehe @ref{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 (siehe -@ref{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 (siehe @ref{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} (siehe -@ref{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 Verzeichnisbäume -zur Erstellung 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 (siehe @ref{Ableitungen}) oder für Substitute -(siehe @ref{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 auf -andere Maschinen @dfn{auslagern}, 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 -(siehe @ref{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} (siehe -@ref{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 - -Der Befehl @code{guix} muss sich im Suchpfad der Erstellungsmaschinen -befinden. Um dies nachzuprüfen, können Sie Folgendes ausführen: - -@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 -(siehe @ref{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 enthält eine SELinux-Richtliniendatei (»Policy«) unter -@file{etc/guix-daemon.cil}, die auf einem System installiert werden kann, -auf dem SELinux aktiviert ist, damit Guix-Dateien gekennzeichnet sind und um -das erwartete Verhalten des Daemons anzugeben. Da Guix System keine -Grundrichtlinie (»Base Policy«) für SELinux bietet, kann diese Richtlinie -für den Daemon auf Guix System nicht benutzt werden. - -@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 @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 @ref{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 (siehe @ref{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 (siehe @ref{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} (siehe @ref{Der Store}). - -@item --substitute-urls=@var{URLs} -@anchor{daemon-substitute-urls} -@var{URLs} als standardmäßige, leerzeichengetrennte Liste der Quell-URLs für -Substitute benutzen. Wenn diese Befehlszeilenoption @emph{nicht} angegeben -wird, wird @indicateurl{https://@value{SUBSTITUTE-SERVER}} verwendet. - -Das hat zur Folge, dass Substitute von den @var{URLs} heruntergeladen werden -können, solange sie mit einer Signatur versehen sind, der vertraut wird -(siehe @ref{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 (siehe -@ref{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. Siehe @ref{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} (siehe @ref{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 (siehe -@ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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} -(siehe @ref{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 @ref{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 (siehe @ref{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 -Läuft Guix aufgesetzt auf einer GNU/Linux-Distribution außer Guix System — -einer sogenannten @dfn{Fremddistribution} —, so sind ein paar zusätzliche -Schritte bei der Einrichtung nötig. Hier finden Sie manche davon. - -@subsection Locales - -@anchor{locales-and-locpath} -@cindex Locales, nicht auf 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} (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -(siehe @ref{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 . -@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. Unter @ref{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 (siehe -@ref{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 (siehe @ref{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. - -Der Zweck des Wrappers ist, die an den Binder übergebenen -Befehlszeilenoptionen mit @code{-L} und @code{-l} zu überprüfen und jeweils -passende Argumente mit @code{-rpath} anzufügen, womit dann der echte Binder -aufgerufen wird. Standardmäßig weigert sich der Binder-Wrapper, mit -Bibliotheken außerhalb des Stores zu binden, um »Reinheit« zu -gewährleisten. Das kann aber stören, wenn man die Toolchain benutzt, um mit -lokalen Bibliotheken zu binden. Um Referenzen auf Bibliotheken außerhalb des -Stores zu erlauben, müssen Sie die Umgebungsvariable -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} setzen. - -@c TODO What else? - -@c ********************************************************************* -@node Systeminstallation -@chapter Systeminstallation - -@cindex Installieren von Guix System -@cindex Guix System, Installation -Dieser Abschnitt beschreibt, wie Sie »Guix System« auf einer Maschine -installieren. Guix kann auch als Paketverwaltungswerkzeug ein bestehendes -GNU/Linux-System ergänzen, mehr dazu finden Sie im Abschnitt -@ref{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: @ref{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. -* Geführte grafische Installation:: Leichte grafische Installation. -* Manuelle Installation:: Manuelle Installation für Zauberer. -* Nach der Systeminstallation:: Wenn die Installation erfolgreich war. -* Guix in einer VM installieren:: Ein »Guix System«-Spielplatz. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. -@end menu - -@node Einschränkungen -@section Einschränkungen - -We consider Guix System to be ready for a wide range of ``desktop'' and -server use cases. The reliability guarantees it provides---transactional -upgrades and rollbacks, reproducibility---make it a solid foundation. - -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -Der Logical Volume Manager (LVM) wird nicht unterstützt. - -@item -Immer mehr Systemdienste sind verfügbar (siehe @ref{Dienste}), aber manche -könnten noch fehlen. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop-Dienste}), as well as a number of X11 window managers. However, KDE is -currently missing. -@end itemize - -More than a disclaimer, this is an invitation to report issues (and success -stories!), and to join us in improving it. @xref{Mitwirken}, for more -info. - - -@node Hardware-Überlegungen -@section Hardware-Überlegungen - -@cindex Hardwareunterstützung von Guix System -GNU@tie{}Guix legt den Fokus darauf, die Freiheit des Nutzers auf seinem -Rechner zu respektieren. Es baut auf Linux-libre als Kernel auf, wodurch nur -Hardware unterstützt wird, für die Treiber und Firmware existieren, die -freie Software sind. Heutzutage wird ein großer Teil der handelsüblichen -Hardware von GNU/Linux-libre unterstützt — von Tastaturen bis hin zu -Grafikkarten, Scannern und Ethernet-Adaptern. Leider gibt es noch Bereiche, -wo die Hardwareanbieter ihren Nutzern die Kontrolle über ihren eigenen -Rechner verweigern. Solche Hardware wird von Guix System nicht unterstützt. - -@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 @code{%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/guix-system-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/guix-system-install-@value{VERSION}.@var{System}.iso.xz.sig -$ gpg --verify guix-system-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 guix-system-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=guix-system-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 guix-system-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=guix-system-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 hochfahren (»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. - -Lesen Sie den Abschnitt @ref{Guix in einer VM installieren}, wenn Sie Guix System -stattdessen in einer virtuellen Maschine (VM) installieren möchten. - - -@node Vor der Installation -@section Vor der Installation - -Wenn Sie Ihren Rechner gebootet haben, können Sie sich vom grafischen -Installationsprogramm durch den Installationsvorgang führen lassen, was den -Einstieg leicht macht (siehe @ref{Geführte grafische Installation}). Alternativ können Sie sich auch für einen »manuellen« -Installationsvorgang entscheiden, wenn Sie bereits mit GNU/Linux vertraut -sind und mehr Kontrolle haben möchten, als sie das grafische -Installationsprogramm bietet (siehe @ref{Manuelle Installation}). - -Das grafische Installationsprogramm steht Ihnen auf TTY1 zur Verfügung. Auf -den TTYs 3 bis 6 können Sie vor sich eine Eingabeaufforderung für den -Administratornutzer »root« sehen, nachdem Sie @kbd{strg-alt-f3}, -@kbd{strg-alt-f4} usw.@: gedrückt haben. TTY2 zeigt Ihnen dieses Handbuch, -das Sie über die Tastenkombination @kbd{strg-alt-f2} erreichen. In dieser -Dokumentation können Sie mit den Steuerungsbefehlen Ihres Info-Betrachters -blättern (siehe @ref{Top,,, info-stnd, Stand-alone GNU Info}). Auf dem -Installationssystem läuft der GPM-Maus-Daemon, wodurch Sie Text mit der -linken Maustaste markieren und ihn mit der mittleren Maustaste einfügen -können. - -@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 - -@node Geführte grafische Installation -@section Geführte grafische Installation - -Das grafische Installationsprogramm ist mit einer textbasierten -Benutzeroberfläche ausgestattet. Es kann Sie mit Dialogfeldern durch die -Schritte führen, mit denen Sie GNU@tie{}Guix System installieren. - -Die ersten Dialogfelder ermöglichen es Ihnen, das System aufzusetzen, wie -Sie es bei der Installation benutzen: Sie können die Sprache und -Tastaturbelegung festlegen und die Netzwerkanbindung einrichten, die während -der Installation benutzt wird. Das folgende Bild zeigt den Dialog zur -Einrichtung der Netzwerkanbindung. - -@image{images/installer-network,5in,, Netzwerkanbindung einrichten mit dem -grafischen Installationsprogramm} - -Mit den danach kommenden Schritten können Sie Ihre Festplatte -partitionieren, wie im folgenden Bild gezeigt, und auswählen, ob Ihre -Dateisysteme verschlüsselt werden sollen oder nicht. Sie können Ihren -Rechnernamen und das Administratorpasswort (das »root«-Passwort) festlegen -und ein Benutzerkonto einrichten, und noch mehr. - -@image{images/installer-partitions,5in,, Partitionieren mit dem grafischen -Installationsprogramm} - -Beachten Sie, dass Sie mit dem Installationsprogramm jederzeit den aktuellen -Installationsschritt verlassen und zu einem vorherigen Schritt zurückkehren -können, wie Sie im folgenden Bild sehen können. - -@image{images/installer-resume,5in,, Mit einem Installationsschritt -fortfahren} - -Sobald Sie fertig sind, erzeugt das Installationsprogramm eine -Betriebssystemkonfiguration und zeigt sie an (siehe @ref{Das Konfigurationssystem nutzen}). Zu diesem Zeitpunkt können Sie auf »OK« drücken und -die Installation wird losgehen. Ist sie erfolgreich, können Sie neu starten -und Ihr neues System genießen. Siehe @ref{Nach der Systeminstallation} für -Informationen, wie es weitergeht! - - -@node Manuelle Installation -@section Manuelle Installation - -Dieser Abschnitt beschreibt, wie Sie GNU@tie{}Guix System auf manuelle Weise -auf Ihrer Maschine installieren. Diese Alternative setzt voraus, dass Sie -bereits mit GNU/Linux, der Shell und üblichen Administrationswerkzeugen -vertraut sind. Wenn Sie glauben, dass das nichts für Sie ist, dann möchten -Sie vielleicht das geführte grafische Installationsprogramm benutzen (siehe -@ref{Geführte grafische Installation}). - -Das Installationssystem macht Eingabeaufforderungen auf den TTYs 3 bis 6 -zugänglich, auf denen Sie als Administratornutzer Befehle eingeben können; -Sie erreichen diese, indem Sie die Tastenkombinationen @kbd{strg-alt-f3}, -@kbd{strg-alt-f4} und so weiter benutzen. Es enthält viele übliche -Werkzeuge, mit denen Sie diese Aufgabe bewältigen können. Da es sich auch um -ein vollständiges »Guix System«-System handelt, können Sie aber auch andere -Pakete mit dem Befehl @command{guix package} nachinstallieren, wenn Sie sie -brauchen (siehe @ref{Aufruf von guix package}). - -@menu -* Tastaturbelegung und Netzwerkanbindung und Partitionierung:: Erstes - Einrichten. -* Fortfahren mit der Installation:: Installieren. -@end menu - -@node Tastaturbelegung und Netzwerkanbindung und Partitionierung -@subsection Tastaturbelegung, Netzwerkanbindung und Partitionierung - -Bevor Sie das System installieren können, wollen Sie vielleicht die -Tastaturbelegung ändern, eine Netzwerkverbindung herstellen und die -Zielfestplatte partitionieren. Dieser Abschnitt wird Sie durch diese -Schritte führen. - -@subsubsection 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. - -@subsubsection 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. - -@subsubsection 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 (siehe @ref{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 (siehe @ref{BIOS -installation,,, grub, GNU GRUB manual}). - -@cindex EFI, Installation -@cindex UEFI, Installation -@cindex ESP, EFI-Systempartition -Falls Sie stattdessen einen EFI-basierten GRUB installieren möchten, muss -auf der Platte eine FAT32-formatierte @dfn{EFI-Systempartition} (ESP) -vorhanden sein. Diese Partition kann unter dem Pfad @file{/boot/efi} -eingebunden (»gemountet«) werden und die @code{esp}-Flag der Partition muss -gesetzt sein. Dazu würden Sie beispielsweise in @command{parted} eintippen: - -@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 @ref{Bootloader-Konfiguration}, wenn Sie mehr Informationen -über Bootloader brauchen. -@end quotation - -Sobald Sie die Platte fertig partitioniert haben, auf die Sie installieren -möchten, müssen Sie ein Dateisystem auf Ihrer oder Ihren für Guix System -vorgesehenen Partition(en) erzeugen@footnote{Derzeit unterstützt Guix System -nur die Dateisystemtypen ext4 und btrfs. Insbesondere funktioniert -Guix-Code, der Dateisystem-UUIDs und -Labels ausliest, nur auf diesen -Dateisystemtypen.}. Wenn Sie eine ESP brauchen und dafür die Partition -@file{/dev/sda1} vorgesehen haben, müssen Sie diesen Befehl ausführen: - -@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 (siehe @ref{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 - -Binden Sie auch alle anderen Dateisysteme ein, die Sie auf dem Zielsystem -benutzen möchten, mit Einhängepunkten relativ zu diesem Pfad. Wenn Sie sich -zum Beispiel für einen Einhängepunkt @file{/boot/efi} für die -EFI-Systempartition entschieden haben, binden Sie sie jetzt als -@file{/mnt/boot/efi} ein, damit @code{guix system init} sie später findet. - -Wenn Sie zudem auch vorhaben, eine oder mehrere Swap-Partitionen zu benutzen -(siehe @ref{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 -@subsection 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 (siehe @ref{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 @ref{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 -Ihre @code{bootloader-configuration}-Form muss sich auf dasjenige Ziel -beziehen, auf das Sie GRUB installieren möchten. Sie sollte genau dann -@code{grub-bootloader} nennen, wenn Sie GRUB im alten BIOS-Modus -installieren, und für neuere UEFI-Systeme sollten Sie -@code{grub-efi-bootloader} nennen. Bei Altsystemen bezeichnet das -@code{target}-Feld ein Gerät wie @code{/dev/sda}, bei UEFI-Systemen -bezeichnet es den Pfad zu einer eingebundenen EFI-Partition wie -@code{/boot/efi}; stellen Sie sicher, dass die ESP tatsächlich dort -eingebunden ist und ein @code{file-system}-Eintrag dafür in Ihrer -Konfiguration festgelegt wurde. - -@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 (siehe @ref{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 @ref{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 später setzen, indem -Sie den Befehl @command{passwd} als @code{root} ausführen, außer Ihre -Konfiguration enthält schon Passwörter (siehe @ref{user-account-password, -user account passwords}). Siehe @ref{Nach der Systeminstallation} für -Informationen, wie es weiter geht! - - -@node Nach der Systeminstallation -@section Nach der Systeminstallation - -Sie haben es geschafft: Sie haben Guix System erfolgreich gebootet! Von -jetzt an können Sie Guix System aktualisieren, wann Sie möchten, indem Sie -zum Beispiel das hier ausführen: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -Dadurch wird eine neue Systemgeneration aus den neuesten Paketen und -Diensten erstellt (siehe @ref{Aufruf von guix system}). Wir empfehlen, diese -Schritte regelmäßig zu wiederholen, damit Ihr System die aktuellen -Sicherheitsaktualisierungen benutzt (siehe @ref{Sicherheitsaktualisierungen}). - -@c See . -@quotation Anmerkung -@cindex sudo, Wirkung auf @command{guix pull} -Beachten Sie, dass bei Nutzung von @command{sudo guix} der -@command{guix}-Befehl des aktiven Benutzers ausgeführt wird und @emph{nicht} -der des Administratornutzers »root«, weil @command{sudo} die -Umgebungsvariable @code{PATH} unverändert lässt. Um ausdrücklich das -@command{guix}-Programm des Administrators aufzurufen, müssen Sie -@command{sudo -i guix @dots{}} eintippen. -@end quotation - -Besuchen Sie uns auf @code{#guix} auf dem Freenode-IRC-Netzwerk oder auf der -Mailing-Liste @file{guix-devel@@gnu.org}, um uns Rückmeldung zu geben! - - -@node Guix in einer VM installieren -@section Guix in einer virtuellen Maschine installieren - -@cindex virtuelle Maschine, Guix System installieren -@cindex Virtual Private Server (VPS) -@cindex VPS (Virtual Private Server) -Wenn Sie Guix System auf einer virtuellen Maschine (VM) oder einem »Virtual -Private Server« (VPS) statt auf Ihrer echten Maschine installieren möchten, -ist dieser Abschnitt hier richtig für Sie. - -Um eine virtuelle Maschine für @uref{http://qemu.org/,QEMU} aufzusetzen, mit -der Sie Guix System in ein »Disk-Image« installieren können (also in eine -Datei mit einem Abbild eines Plattenspeichers), gehen Sie so vor: - -@enumerate -@item -Zunächst laden Sie das Installationsabbild des Guix-Systems wie zuvor -beschrieben herunter und entpacken es (siehe @ref{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=guix-system-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 @ref{Vor der Installation}. -@end enumerate - -Wurde die Installation abgeschlossen, können Sie das System starten, das -sich nun als Abbild in der Datei @file{guixsd.img} befindet. Der Abschnitt -@ref{Guix in einer VM starten} erklärt, wie Sie das tun können. - -@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 (siehe @ref{Aufruf von guix package, @code{guix package}}) können Sie auch mit der -Emacs-Guix-Schnittstelle (siehe @ref{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 (siehe @ref{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. - -Zudem kann jede Pakettransaktion @emph{zurückgesetzt} werden -(Rollback). Wird also zum Beispiel durch eine Aktualisierung eine neue -Version eines Pakets installiert, die einen schwerwiegenden Fehler zur Folge -hat, können Nutzer ihr Profil einfach auf die vorherige Profilinstanz -zurücksetzen, von der sie wissen, dass sie gut lief. Ebenso unterliegt bei -Guix auch die globale Systemkonfiguration transaktionellen Aktualisierungen -und Rücksetzungen (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe -@ref{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} (siehe @ref{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 (siehe @ref{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« (siehe @ref{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 -(siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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} (siehe @ref{Pakete mit mehreren Ausgaben.}). Pakete mit zugehörigem Namen (und optional der Version) werden -unter den Modulen der GNU-Distribution gesucht (siehe @ref{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 @ref{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{}-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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -Führt alle verfügbaren Pakete auf, deren Name, Zusammenfassung oder -Beschreibung zum regulären Ausdruck @var{Regexp} passt, ohne Groß- und -Kleinschreibung zu unterscheiden und sortiert nach ihrer Relevanz. Alle -Metadaten passender Pakete werden im @code{recutils}-Format geliefert (siehe -@ref{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 '\' -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 -kryptografische 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 -Siehe @ref{Selection Expressions,,, recutils, GNU recutils manual}, es -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 (siehe @ref{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 (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{Gemeinsame Erstellungsoptionen}) verwenden. Auch Paketumwandlungsoptionen wie -@option{--with-source} sind möglich (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 -Der Server @code{@value{SUBSTITUTE-SERVER}} ist die Fassade für eine -offizielle »Build-Farm«, ein Erstellungswerk, das kontinuierlich Guix-Pakete -für einige Prozessorarchitekturen erstellt und sie als Substitute zur -Verfügung stellt. Dies ist die standardmäßige Quelle von Substituten; durch -Übergeben der Befehlszeilenoption @option{--substitute-urls} an entweder den -@command{guix-daemon} (siehe @ref{daemon-substitute-urls,, @code{guix-daemon ---substitute-urls}}) oder Client-Werkzeuge wie @command{guix package} (siehe -@ref{client-substitute-urls,, die Befehlszeilenoption -@option{--substitute-urls} beim Client}) kann eine abweichende Einstellung -benutzt werden. - -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 (siehe @ref{GNU-Distribution}). Auf Fremddistributionen sind sie allerdings standardmäßig -ausgeschaltet, solange Sie sie nicht ausdrücklich in einem der empfohlenen -Installationsschritte erlaubt haben (siehe @ref{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 -Um es Guix zu gestatten, Substitute von @code{@value{SUBSTITUTE-SERVER}} -oder einem Spiegelserver davon herunterzuladen, müssen Sie den zugehörigen -öffentlichen Schlüssel zur Access Control List (ACL, -Zugriffssteuerungsliste) für Archivimporte hinzufügen, mit Hilfe des Befehls -@command{guix archive} (siehe @ref{Aufruf von guix archive}). Dies impliziert, -dass Sie darauf vertrauen, dass @code{@value{SUBSTITUTE-SERVER}} nicht -kompromittiert wurde und echte Substitute liefert. - -Der öffentliche Schlüssel für @code{@value{SUBSTITUTE-SERVER}} wird zusammen -mit Guix installiert, in das Verzeichnis -@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, wobei @var{prefix} das bei -der Installation angegebene Präfix von Guix ist. Wenn Sie Guix aus seinem -Quellcode heraus installieren, sollten Sie sichergehen, dass Sie die -GPG-Signatur (auch »Beglaubigung« genannt) von -@file{guix-@value{VERSION}.tar.gz} prüfen, worin sich dieser öffentliche -Schlüssel befindet. Dann können Sie so etwas wie hier ausführen: - -@example -# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Anmerkung -Genauso enthält die Datei @file{hydra.gnu.org.pub} den öffentlichen -Schlüssel für eine unabhängige Build-Farm, die auch vom Guix-Projekt -betrieben wird. Sie ist unter @indicateurl{https://mirror.hydra.gnu.org} -erreichbar ist. -@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 -Das zeigt an, dass Substitute von @code{@value{SUBSTITUTE-SERVER}} nutzbar -sind und für zukünftige Erstellungen heruntergeladen werden, wann immer es -möglich ist. - -@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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -Derzeit hängt die Kontrolle jedes Individuums über seine Rechner von -Institutionen, Unternehmen und solchen Gruppierungen ab, die über genug -Macht und Entschlusskraft verfügen, die Rechnerinfrastruktur zu sabotieren -und ihre Schwachstellen auszunutzen. Auch wenn es bequem ist, Substitute von -@code{@value{SUBSTITUTE-SERVER}} zu benutzen, ermuntern wir Nutzer, auch -selbst Erstellungen durchzuführen oder gar ihre eigene Build-Farm zu -betreiben, damit @code{@value{SUBSTITUTE-SERVER}} ein weniger interessantes -Ziel wird. Eine Art, uns zu helfen, ist, die von Ihnen erstellte Software -mit dem Befehl @command{guix publish} zu veröffentlichen, damit andere eine -größere Auswahl haben, von welchem Server sie Substitute beziehen möchten -(siehe @ref{Aufruf von guix publish}). - -Guix hat die richtigen Grundlagen, um die Reproduzierbarkeit von -Erstellungen zu maximieren (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -diskutieren 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«), statischen 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 -(siehe @ref{Aufruf von guix size}). @command{guix graph} kann auch helfen -(siehe @ref{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 (siehe @ref{Dateien zur Fehlersuche installieren}). Die Ausgaben -eines Pakets stehen in der dritten Spalte der Anzeige von @command{guix -package --list-available} (siehe @ref{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 (siehe -@ref{Aufruf von guix build}). Der Befehl @command{guix gc --list-roots} listet -sie auf. - -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 (siehe @ref{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 - -Es ist völlig sicher, dafür eine nicht interaktive, regelmäßige -Auftragsausführung vorzugeben (siehe @ref{Geplante Auftragsausführung} für eine -Erklärung, wie man das tun kann). @command{guix gc} ohne -Befehlszeilenargumente auszuführen, lässt so viel Müll wie möglich sammeln, -aber das ist oft nicht, was man will, denn so muss man unter Umständen -Software erneut erstellen oder erneut herunterladen, weil der Müllsammler -sie als »tot« ansieht, sie aber zur Erstellung anderer Software wieder -gebraucht wird — das trifft zum Beispiel auf die Compiler-Toolchain zu. - -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 (siehe @ref{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-generations[=@var{Dauer}] -@itemx -d [@var{Dauer}] -Bevor der Müllsammelvorgang beginnt, werden hiermit alle Generationen von -allen Benutzerprofilen gelöscht, die älter sind als die angegebene -@var{Dauer}; wird es als Administratornutzer »root« ausgeführt, geschieht -dies mit den Profilen @emph{von allen Benutzern}. - -Zum Beispiel löscht der folgende Befehl alle Generationen Ihrer Profile, die -älter als zwei Monate sind (ausgenommen die momentanen Generationen), und -schmeißt dann den Müllsammler an, um Platz freizuräumen, bis mindestens 10 -GiB verfügbar sind: - -@example -guix gc -d 2m -F 10G -@end example - -@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 (siehe @ref{Aufruf des guix-daemon, -@option{--cache-failures}}). - -@item --list-roots -Die Müllsammlerwurzeln auflisten, die dem Nutzer gehören. Wird der Befehl -als Administratornutzer ausgeführt, werden @emph{alle} Müllsammlerwurzeln -aufgelistet. - -@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 @ref{Aufruf von guix size} erklärt ein Werkzeug, um den -Speicherbedarf des Abschlusses eines Elements zu ermitteln. Siehe -@ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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} (siehe @ref{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 (siehe -@ref{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 (siehe @ref{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} -Download code for the @code{guix} channel from the specified @var{url}, at -the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@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 @ref{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} (siehe @ref{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 @ref{Kanäle} finden Sie nähere Informationen. - -Außerdem unterstützt @command{guix pull} alle gemeinsamen -Erstellungsoptionen (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 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 (siehe -@ref{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 - -Um einen Kanal zu benutzen, tragen Sie ihn in -@code{~/.config/guix/channels.scm} ein, damit @command{guix pull} diesen -Kanal @emph{zusätzlich} zu den standardmäßigen Guix-Kanälen als Paketquelle -verwendet: - -@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 -Beachten Sie, dass der obige Schnipsel (wie immer!)@: Scheme-Code ist; mit -@code{cons} fügen wir einen Kanal zur Liste der Kanäle hinzu, an die die -Variable @code{%default-channels} gebunden ist (siehe @ref{Pairs, -@code{cons} and lists,, guile, GNU Guile Reference Manual}). Mit diesem -Dateiinhalt wird @command{guix pull} nun nicht mehr nur Guix, sondern auch -die Paketmodule aus Ihrem Repository erstellen. Das Ergebnis in -@file{~/.config/guix/current} ist so die Vereinigung von Guix und Ihren -eigenen Paketmodulen. - -@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. - -Um einen Kanal zu erzeugen, müssen Sie ein Git-Repository mit Ihren eigenen -Paketmodulen erzeugen und den Zugriff darauf ermöglichen. Das Repository -kann beliebigen Inhalt haben, aber wenn es ein nützlicher Kanal sein soll, -muss es Guile-Module enthalten, die Pakete exportieren. Sobald Sie anfangen, -einen Kanal zu benutzen, verhält sich Guix, als wäre das Wurzelverzeichnis -des Git-Repositorys des Kanals in Guiles Ladepfad enthalten (siehe @ref{Load -Paths,,, guile, GNU Guile Reference Manual}). Wenn Ihr Kanal also zum -Beispiel eine Datei als @file{my-packages/my-tools.scm} enthält, die ein -Guile-Modul definiert, dann wird das Modul unter dem Namen -@code{(my-packages my-tools)} verfügbar sein und Sie werden es wie jedes -andere Modul benutzen können (siehe @ref{Module,,, guile, GNU Guile -Reference Manual}). - -@cindex Abhängigkeiten, bei Kanälen -@cindex Metadaten, bei Kanälen -@subsection Kanalabhängigkeiten deklarieren - -Kanalautoren können auch beschließen, die Paketsammlung von anderen Kanälen -zu erweitern. Dazu können sie in einer Metadatendatei @file{.guix-channel} -deklarieren, dass ihr Kanal von anderen Kanälen abhängt. Diese Datei muss im -Wurzelverzeichnis des Kanal-Repositorys platziert werden. - -Die Metadatendatei sollte einen einfachen S-Ausdruck wie diesen enthalten: - -@lisp -(channel - (version 0) - (dependencies - (channel - (name irgendeine-sammlung) - (url "https://example.org/erste-sammlung.git")) - (channel - (name eine-andere-sammlung) - (url "https://example.org/zweite-sammlung.git") - (branch "testing")))) -@end lisp - -Im Beispiel oben wird deklariert, dass dieser Kanal von zwei anderen Kanälen -abhängt, die beide automatisch geladen werden. Die vom Kanal angebotenen -Module werden in einer Umgebung kompiliert, in der die Module all dieser -deklarierten Kanäle verfügbar sind. - -Um Verlässlichkeit und Wartbarkeit zu gewährleisten, sollen Sie darauf -verzichten, eine Abhängigkeit von Kanälen herzustellen, die Sie nicht -kontrollieren, außerdem sollten Sie sich auf eine möglichst kleine Anzahl -von Abhängigkeiten beschränken. - -@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 (siehe @ref{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 -@ref{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 (siehe @ref{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 (siehe @ref{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 (siehe -@ref{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 (siehe @ref{»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 (siehe -@ref{G-Ausdrücke}). Sie werden auch transparent wie reguläre Pakete von -der Prozedur @code{packages->manifest} behandelt, welche oft in Manifesten -benutzt wird (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -@ref{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} (siehe @ref{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 (siehe -@ref{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 (siehe -@ref{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, auch Beglaubigung genannt. 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 (siehe @ref{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 (siehe @ref{Substitute}) und ins @var{Verzeichnis} -entpacken. Dies ist eine systemnahe Operation, die man nur selten direkt -benutzt; siehe unten. - -Zum Beispiel entpackt folgender Befehl das Substitut für Emacs, wie es von -@code{@value{SUBSTITUTE-SERVER}} geliefert wird, nach @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 Entwicklung -@chapter Entwicklung - -@cindex Softwareentwicklung -Wenn Sie ein Software-Entwickler sind, gibt Ihnen Guix Werkzeuge an die -Hand, die Sie für hilfreich erachten dürften — ganz unabhängig davon, in -welcher Sprache Sie entwickeln. Darum soll es in diesem Kapitel gehen. - -Der Befehl @command{guix environment} stellt eine bequeme Möglichkeit dar, -wie Sie eine @dfn{Entwicklungsumgebung} aufsetzen können, in der all die -Abhängigkeiten und Werkzeuge enthalten sind, die Sie brauchen, wenn Sie an -Ihrem Lieblingssoftwarepaket arbeiten. Der Befehl @command{guix pack} macht -es Ihnen möglich, @dfn{Anwendungsbündel} zu erstellen, die leicht an Nutzer -verteilt werden können, die kein Guix benutzen. - -@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. Siehe @ref{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 (siehe @ref{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 -…@: oder um ihr Profil durchzusehen: - -@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 - -Manchmal ist es wünschenswert, die Umgebung so viel wie möglich zu -isolieren, um maximale Reinheit und Reproduzierbarkeit zu -bekommen. Insbesondere ist es wünschenswert, den Zugriff auf @file{/usr/bin} -und andere Systemressourcen aus der Entwicklungsumgebung heraus zu -verhindern, wenn man Guix auf einer fremden Wirtsdistribution benutzt, die -nicht Guix System ist. Zum Beispiel startet der folgende Befehl eine -Guile-REPL in einer isolierten Umgebung, einem sogenannten »Container«, in -der nur der Store und das aktuelle Arbeitsverzeichnis eingebunden sind: - -@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{Datei} -@itemx -r @var{Datei} -@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. @ref{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 - -bekommt man eine Shell, in der alle Basis-Pakete verfügbar sind. - -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 -(siehe @ref{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} (siehe @ref{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 (siehe @ref{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 -Bestehende Umgebungsvariable deaktivieren, wenn die neue Umgebung erzeugt -wird, mit Ausnahme der mit @option{--preserve} angegebenen Variablen (siehe -unten). Dies bewirkt, dass eine Umgebung erzeugt wird, in der die Suchpfade -nur Paketeingaben nennen und sonst nichts. - -@item --preserve=@var{Regexp} -@itemx -E @var{Regexp} -Wenn das hier zusammen mit @option{--pure} angegeben wird, bleiben die zum -regulären Ausdruck @var{Regexp} passenden Umgebungsvariablen erhalten — mit -anderen Worten werden sie auf eine »weiße Liste« von Umgebungsvariablen -gesetzt, die erhalten bleiben müssen. Diese Befehlszeilenoption kann -mehrmals wiederholt werden. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -In diesem Beispiel wird @command{mpirun} in einem Kontext ausgeführt, in dem -die einzig definierten Umgebungsvariablen @code{PATH} und solche sind, deren -Name mit @code{SLURM} beginnt, sowie die üblichen besonders »kostbaren« -Variablen (@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. Innerhalb des Containers hat er dieselbe UID und GID wie der -momentane Nutzer, außer die Befehlszeilenoption @option{--user} wird -übergeben (siehe unten). - -@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. Des Weiteren sind UID und GID innerhalb der -isolierten Umgebung auf 1000 gesetzt. @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} unterstützt auch alle gemeinsamen -Erstellungsoptionen, die von @command{guix build} unterstützt werden (siehe -@ref{Gemeinsame Erstellungsoptionen}), und die Paketumwandlungsoptionen (siehe -@ref{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 @ref{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 (siehe @ref{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 - -@cindex pfad-agnostische Binärdateien -@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. - -Wenn diese Befehlszeilenoption einmal übergeben wird, funktionieren die -erzeugten Binärdateien nur dann, wenn @dfn{Benutzernamensräume} des -Linux-Kernels unterstützt werden. Wenn sie @emph{zweimal}@footnote{Es gibt -einen Trick, wie Sie sich das merken können: @code{-RR}, womit -PRoot-Unterstützung hinzugefügt wird, kann man sich als Abkürzung für -»Rundum Relocatable« oder englisch »Really Relocatable« vorstellen. Ist das -nicht prima?} übergeben wird, laufen die Binärdateien notfalls mit PRoot, -wenn keine Benutzernamensräume zur Verfügung stehen, funktionieren also -ziemlich überall — siehe unten für die Auswirkungen. - -Zum Beispiel können Sie ein Bash enthalltendes Bündel erzeugen mit: - -@example -guix pack -RR -S /mybin=bin bash -@end example - -@noindent -…@: Sie können dieses dann auf eine Maschine ohne Guix kopieren und als -normaler Nutzer aus Ihrem Persönlichen Verzeichnis (auch »Home«-Verzeichnis -genannt) dann ausführen mit: - -@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. - -@quotation Anmerkung -Wenn die Voreinstellung verwendet wird, funktionieren pfad-agnostische -Binärdateien 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 diese Funktionalität noch nicht unterstützt und -manche Distributionen von GNU/Linux schalten sie ab. - -Um pfad-agnostische Binärdateien zu erzeugen, die auch ohne -Benutzernamensräume funktionieren, können Sie die Befehlszeilenoption -@option{--relocatable} oder @option{-R} @emph{zweimal} angeben. In diesem -Fall werden die Binärdateien zuerst überprüfen, ob Benutzernamensräume -unterstützt werden, und sonst notfalls PRoot benutzen, um das Programm -auszuführen, wenn Benutzernamensräume nicht unterstützt werden. - -Das Programm @uref{https://proot-me.github.io/, PRoot} bietet auch -Unterstützung für Dateisystemvirtualisierung, indem der Systemaufruf -@code{ptrace} auf das laufende Programm angewendet wird. Dieser Ansatz -funktioniert auch ohne besondere Kernel-Unterstützung, aber das Programm -braucht mehr Zeit, um selbst Systemaufrufe durchzuführen. -@end quotation - -@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} (siehe @ref{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} (siehe @ref{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 (siehe -@ref{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 -Provenienzinformationen für die auf der Befehlszeile übergebenen Pakete -speichern. Zu den Provenienzinformationen gehören die URL und der Commit -jedes benutzten Kanals (siehe @ref{Kanäle}). - -Provenienzinformationen werden in der Datei -@file{/gnu/store/@dots{}-profile/manifest} im Bündel zusammen mit den -üblichen Paketmetadaten abgespeichert — also Name und Version jedes Pakets, -welche Eingaben dabei propagiert werden und so weiter. Die Informationen -nützen den Empfängern des Bündels, weil sie dann wissen, woraus das Bündel -(angeblich) besteht. - -Der Vorgabe nach wird diese Befehlszeilenoption @emph{nicht} verwendet, weil -Provenienzinformationen genau wie Zeitstempel nichts zum Erstellungsprozess -beitragen. Mit anderen Worten gibt es unendlich viele Kanal-URLs und -Commit-IDs, aus denen dasselbe Bündel stammen könnte. Wenn solche »stillen« -Metadaten Teil des Ausgabe sind, dann wird also die bitweise -Reproduzierbarkeit von Quellcode zu Binärdateien eingeschränkt. - -@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 (siehe @ref{Der Store}) sowie -die Müllsammlerwurzeln (siehe @ref{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 (siehe @ref{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 (siehe @ref{Gemeinsame Erstellungsoptionen}) und alle -Paketumwandlungsoptionen (siehe @ref{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 - -Aus Programmierersicht werden die Paketdefinitionen der GNU-Distribution als -Guile-Module in Namensräumen wie @code{(gnu packages @dots{})} sichtbar -gemacht@footnote{Beachten Sie, dass Pakete unter dem Modulnamensraum -@code{(gnu packages @dots{})} nicht notwendigerweise auch »GNU-Pakete« -sind. Dieses Schema für die Benennung von Modulen folgt lediglich den -üblichen Guile-Konventionen: @code{gnu} bedeutet, dass die Module als Teil -des GNU-Systems ausgeliefert werden, und @code{packages} gruppiert Module -mit Paketdefinitionen.} (siehe @ref{Module, Guile modules,, guile, GNU -Guile Reference Manual}). Zum Beispiel exportiert das Modul @code{(gnu -packages emacs)} eine Variable namens @code{emacs}, die an ein -@code{}-Objekt gebunden ist (@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{}-Objekt, was an sich nur ein Verbund -(Record) ist (siehe @ref{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 (siehe @ref{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 (siehe @ref{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{}-Objekt, was den Paketursprung angibt (siehe @ref{»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} (siehe -@ref{Aufruf von guix download}) und @code{guix hash} (siehe @ref{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 (siehe @ref{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 (siehe @ref{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}. @ref{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} (siehe -@ref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -Ein Doppelkreuz gefolgt von einem Doppelpunkt (@code{#:}) definiert ein -Scheme-@dfn{Schlüsselwort} (siehe @ref{Keywords,,, guile, GNU Guile -Reference Manual}) und @code{#:configure-flags} ist ein Schlüsselwort, um -eine Befehlszeilenoption an das Erstellungssystem mitzugeben (siehe -@ref{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{}-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 (siehe @ref{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 (siehe -@ref{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 @ref{»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 -(siehe @ref{Aufruf von guix build}) und dabei jegliche Erstellungsfehler, auf -die Sie stoßen, beseitigen (siehe @ref{Fehlschläge beim Erstellen untersuchen}). Sie -können den Befehl @command{guix edit} benutzen, um leicht zur -Paketdefinition zurückzuspringen (siehe @ref{Aufruf von guix edit}). Unter -@ref{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 @ref{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 (siehe -@ref{Aufruf von guix refresh}). - -Hinter den Kulissen wird die einem @code{}-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 (siehe @ref{Der Store}). - -@deffn {Scheme-Prozedur} package-derivation @var{Store} @var{Paket} [@var{System}] -Das @code{}-Objekt zum @var{Paket} für das angegebene -@var{System} liefern (siehe @ref{Ableitungen}). - -Als @var{Paket} muss ein gültiges @code{}-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 (siehe @ref{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{}-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"} (siehe @ref{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 (siehe -@ref{Paketumwandlungsoptionen, @option{--with-input}}). - -The following variant of @code{package-input-rewriting} can match packages -to be replaced by name rather than by identity. - -@deffn {Scheme-Prozedur} package-input-rewriting/spec @var{Ersetzungen} -Return a procedure that, given a package, applies the given -@var{replacements} to all the package graph (excluding implicit inputs). -@var{replacements} is a list of spec/procedures pair; each spec is a package -specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure -takes a matching package and returns a replacement for that package. -@end deffn - -The example above could be rewritten this way: - -@example -(define libressl-statt-openssl - ;; Rekursiv alle Pakete namens "openssl" durch LibreSSL ersetzen. - (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example - -The key difference here is that, this time, packages are matched by spec and -not by identity. In other words, any package in the graph that is called -@code{openssl} will be replaced. - -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 (siehe @ref{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 (siehe @ref{»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 (siehe @ref{G-Ausdrücke, @code{local-file}}). - -@item @code{build-system} -Das Erstellungssystem, mit dem das Paket erstellt werden soll (siehe -@ref{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 @ref{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 (siehe @ref{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 -@ref{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{outputs} (Vorgabe: @code{'("out")}) -Die Liste der Benennungen der Ausgaben des Pakets. Der Abschnitt -@ref{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 -@ref{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 - -@deffn {Scheme Syntax} this-package -When used in the @emph{lexical scope} of a package field definition, this -identifier resolves to the package being defined. - -The example below shows how to add a package as a native input of itself -when cross-compiling: - -@example -(package - (name "guile") - ;; ... - - ;; When cross-compiled, Guile, for example, depends on - ;; a native version of itself. Add it here. - (native-inputs (if (%current-target-system) - `(("self" ,this-package)) - '()))) -@end example - -It is an error to refer to @code{this-package} outside a package definition. -@end deffn - -@node »origin«-Referenz -@subsection @code{origin}-Referenz - -Dieser Abschnitt fasst alle Optionen zusammen, die in -@code{origin}-Deklarationen zur Verfügung stehen (siehe @ref{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} (siehe -@ref{Aufruf von guix download}) oder @code{guix hash} (siehe @ref{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 (siehe -@ref{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 (siehe -@ref{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 (siehe @ref{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{}-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 (siehe -@ref{Ableitungen}). - -Erstellungssysteme akzeptieren optional eine Liste von @dfn{Argumenten}. In -Paketdefinitionen werden diese über das @code{arguments}-Feld übergeben -(siehe @ref{Pakete definieren}). Sie sind in der Regel -Schlüsselwort-Argumente (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe -@ref{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{}-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{-tests.asd}, @code{-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 -Diese Variable wird vom Modul @code{(guix build-system dune)} -exportiert. Sie unterstützt es, Pakete mit @uref{https://dune.build/, Dune} -zu erstellen, einem Erstellungswerkzeug für die Programmiersprache OCaml, -und ist als Erweiterung des unten beschriebenen OCaml-Erstellungssystems -@code{ocaml-build-system} implementiert. Als solche können auch die -Parameter @code{#:ocaml} und @code{#:findlib} an dieses Erstellungssystem -übergeben werden. - -Das Erstellungssystem fügt automatisch das Paket @code{dune} zu den Eingaben -hinzu. Welches Paket benutzt wird, kann mit dem Parameter @code{#:dune} -geändert werden. - -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}. - -The @code{#:package} parameter can be passed to specify a package name, -which is useful when a package contains multiple packages and you want to -build only one of them. This is equivalent to passing the @code{-p} -argument to @code{dune}. -@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 ihren Quellcode -auch in die Erstellungsausgabe installieren. 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 (siehe -@ref{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} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It implements -the build procedure used by @uref{https://rakudo.org/, Rakudo} for -@uref{https://perl6.org/, Perl6} packages. It installs the package to -@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the -binaries, library files and the resources, as well as wrap the files under -the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the -@code{tests?} parameter. - -Which rakudo package is used can be specified with @code{rakudo}. Which -perl6-tap-harness package used for the tests can be specified with -@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} -parameter. Which perl6-zef package used for tests and installing can be -specified with @code{#:zef} or removed by passing @code{#f} to the -@code{with-zef?} parameter. -@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 (siehe @ref{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 -Diese Variable wird vom Modul @code{(guix build-system font)} -exportiert. Mit ihr steht eine Installationsprozedur für Schriftarten-Pakete -zur Verfügung für vom Anbieter vorkompilierte TrueType-, OpenType- und -andere Schriftartendateien, die nur an die richtige Stelle kopiert werden -müssen. Dieses Erstellungssystem kopiert die Schriftartendateien an den -Konventionen folgende Orte im Ausgabeverzeichnis. -@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 - -@defvr {Scheme Variable} linux-module-build-system -@var{linux-module-build-system} allows building Linux kernel modules. - -@cindex Erstellungsphasen -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed: - -@table @code - -@item configure -This phase configures the environment so that the Linux kernel's Makefile -can be used to build the external kernel module. - -@item build -This phase uses the Linux kernel's Makefile in order to build the external -kernel module. - -@item install -This phase uses the Linux kernel's Makefile in order to install the external -kernel module. -@end table - -It is possible and useful to specify the Linux kernel to use for building -the module (in the "arguments" form of a package using the -linux-module-build-system, use the key #:linux to specify it). -@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} (siehe @ref{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 (siehe @ref{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 (siehe @ref{Einführung}). - -Siehe @ref{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 (siehe @ref{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 -(siehe @ref{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 (siehe @ref{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 (siehe -@ref{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). - -Ein @code{&store-protocol-error}-Fehlerzustand wird ausgelöst, wenn der -@var{Pfad} nicht mit dem Store-Verzeichnis als Präfix beginnt -(@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{}-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 (siehe @ref{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 Erstellungszeitabhängigkeiten -@cindex Abhängigkeiten zur Erstellungszeit -Die Eingaben der Ableitung, also Abhängigkeiten zur Zeit ihrer Erstellung, -die entweder andere Ableitungen oder einfache Dateien im Store sind (wie -Patches, Erstellungsskripts usw.). - -@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 (siehe @ref{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 Laufzeitabhängigkeiten -@cindex Abhängigkeiten, zur Laufzeit -Den Ausgaben von Ableitungen — d.h.@: Erstellungergebnissen — ist eine Liste -von @dfn{Referenzen} zugeordnet, die auch der entfernte Prozeduraufruf -@code{references} oder der Befehl @command{guix gc --references} liefert -(siehe @ref{Aufruf von guix gc}). Referenzen sind die Menge der -Laufzeitabhängigkeiten von Erstellungsergebnissen. Referenzen sind eine -Teilmenge der Eingaben von Ableitungen; die Teilmenge wird automatisch -ermittelt, indem der Erstellungsdaemon alle Dateien unter den Ausgaben nach -Referenzen durchsucht. - -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{}-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 (siehe -@ref{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 (siehe -@ref{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{} # /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 @ref{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{} # @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 @ref{G-Ausdrücke}): - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c -@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 = # @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 = # @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} (siehe @ref{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} (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe -@ref{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} (siehe -@ref{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} (siehe @ref{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 @ref{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{}, 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{}. -@end deffn - -@node Aufruf von guix repl -@section @command{guix repl} aufrufen - -@cindex REPL (Lese-Auswerten-Schreiben-Schleife) -Der Befehl @command{guix repl} startet eine Guile-REPL (@dfn{Read-Eval-Print -Loop}, kurz REPL, deutsch Lese-Auswerten-Schreiben-Schleife) zur -interaktiven Programmierung (siehe @ref{Using Guile Interactively,,, guile, -GNU Guile Reference Manual}). Im Vergleich dazu, einfach den Befehl -@command{guile} aufzurufen, garantiert @command{guix repl}, dass alle -Guix-Module und deren Abhängigkeiten im Suchpfad verfügbar sind. Sie können -die REPL so benutzen: - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = # -@end example - -@cindex Untergeordnete -@command{guix repl} implementiert zusätzlich ein einfaches maschinenlesbares -Protokoll für die REPL, das von @code{(guix inferior)} benutzt wird, um mit -@dfn{Untergeordneten} zu interagieren, also mit getrennten Prozessen einer -womöglich anderen Version von Guix. - -Folgende @var{Optionen} gibt es: - -@table @code -@item --type=@var{Typ} -@itemx -t @var{Typ} -Startet eine REPL des angegebenen @var{Typ}s, der einer der Folgenden sein -darf: - -@table @code -@item guile -Die Voreinstellung, mit der eine normale, voll funktionsfähige Guile-REPL -gestartet wird. -@item machine -Startet eine REPL, die ein maschinenlesbares Protokoll benutzt. Dieses -Protokoll wird vom Modul @code{(guix inferior)} gesprochen. -@end table - -@item --listen=@var{Endpunkt} -Der Vorgabe nach würde @command{guix repl} von der Standardeingabe lesen und -auf die Standardausgabe schreiben. Wird diese Befehlszeilenoption angegeben, -lauscht die REPL stattdessen auf dem @var{Endpunkt} auf Verbindungen. Hier -sind Beispiele gültiger Befehlszeilenoptionen: - -@table @code -@item --listen=tcp:37146 -Verbindungen mit dem »localhost« auf Port 37146 akzeptieren. - -@item --listen=unix:/tmp/socket -Verbindungen zum Unix-Socket @file{/tmp/socket} akzeptieren. -@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 kryptografischen 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:: Plattenplatzverbrauch 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} (siehe -@ref{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 (siehe @ref{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 (siehe -@ref{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 @ref{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 (siehe -@ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{Substitute}). - -@item --no-grafts -Pakete nicht »veredeln« (engl. »graft«). Praktisch heißt das, dass als -Veredelungen verfügbare Paketaktualisierungen nicht angewandt werden. Der -Abschnitt @ref{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 @ref{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 (siehe @ref{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 -(siehe @ref{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 (siehe -@ref{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 (siehe -@ref{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 Ausführlichkeit der Befehlszeilenwerkzeuge -@cindex Erstellungsprotokolle, Ausführlichkeit -@item -v @var{Stufe} -@itemx --verbosity=@var{Stufe} -Die angegebene Ausführlichkeitsstufe verwenden. Als @var{Stufe} muss eine -ganze Zahl angegeben werden. Wird 0 gewählt, wird keine Ausgabe zur -Fehlersuche angezeigt, 1 bedeutet eine knappe Ausgabe und 2 lässt alle -Erstellungsprotokollausgaben auf die Standardfehlerausgabe schreiben. - -@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 -@ref{Aufruf des guix-daemon, @code{--max-jobs}} finden Sie Details zu dieser -Option und der äquivalenten Option des @command{guix-daemon}. - -@item --debug=@var{Stufe} -Ein Protokoll zur Fehlersuche ausgeben, das vom Erstellungsdaemon kommt. Als -@var{Stufe} muss eine ganze Zahl zwischen 0 und 5 angegeben werden; höhere -Zahlen stehen für ausführlichere Ausgaben. Stufe 4 oder höher zu wählen, -kann bei der Suche nach Fehlern, wie der Erstellungs-Daemon eingerichtet -ist, helfen. - -@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 (siehe @ref{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} (siehe @ref{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} (siehe @ref{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 @ref{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-git-url=@var{Paket}=@var{URL} -@cindex Git, den neuesten Commit benutzen -@cindex latest commit, building -Build @var{package} from the latest commit of the @code{master} branch of -the Git repository at @var{url}. Git sub-modules of the repository are -fetched, recursively. - -For example, the following command builds the NumPy Python library against -the latest commit of the master branch of Python itself: - -@example -guix build python-numpy \ - --with-git-url=python=https://github.com/python/cpython -@end example - -This option can also be combined with @code{--with-branch} or -@code{--with-commit} (see below). - -@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-branch=@var{Paket}=@var{Branch} -Build @var{package} from the latest commit of @var{branch}. If the -@code{source} field of @var{package} is 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}. Otherwise you have to use -@code{--with-git-url} to specify the URL of the Git repository. - -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 - -@item --with-commit=@var{Paket}=@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 -Schweigend erstellen, ohne das Erstellungsprotokoll anzuzeigen — dies ist -äquivalent zu @code{--verbosity=0}. Nach Abschluss der Erstellung ist das -Protokoll in @file{/var} (oder einem entsprechenden Ort) einsehbar und kann -jederzeit mit der Befehlszeilenoption @option{--log-file} gefunden werden. - -@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 (siehe @ref{G-Ausdrücke, -file-like objects}). - -Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen (siehe -@ref{Pakete definieren}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Das Paket oder die Ableitung erstellen, zu der der @var{Ausdruck} -ausgewertet wird. - -Zum Beispiel kann der @var{Ausdruck} @code{(@@ (gnu packages guile) -guile-1.8)} sein, was diese bestimmte Variante der Version 1.8 von Guile -eindeutig bezeichnet. - -Alternativ kann der @var{Ausdruck} ein G-Ausdruck sein. In diesem Fall wird -er als Erstellungsprogramm an @code{gexp->derivation} übergeben (siehe -@ref{G-Ausdrücke}). - -Zudem kann der @var{Ausdruck} eine monadische Prozedur mit null Argumenten -bezeichnen (siehe @ref{Die Store-Monade}). Die Prozedur muss eine Ableitung -als monadischen Wert zurückliefern, die dann durch @code{run-with-store} -laufen gelassen wird. - -@item --source -@itemx -S -Die Quellcode-Ableitung der Pakete statt die Pakete selbst erstellen. - -Zum Beispiel liefert @code{guix build -S gcc} etwas in der Art von -@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, also den Tarball mit dem -GCC-Quellcode. - -Der gelieferte Quell-Tarball ist das Ergebnis davon, alle Patches und -Code-Schnipsel aufzuspielen, die im @code{origin}-Objekt des Pakets -festgelegt wurden (siehe @ref{Pakete definieren}). - -@item --sources -Den Quellcode für @var{Paket-oder-Ableitung} und alle Abhängigkeiten davon -rekursiv herunterladen und zurückliefern. Dies ist eine praktische Methode, -eine lokale Kopie des gesamten Quellcodes zu beziehen, der nötig ist, um die -Pakete zu erstellen, damit Sie diese später auch ohne Netzwerkzugang -erstellen lassen können. Es handelt sich um eine Erweiterung der -Befehlszeilenoption @code{--source}, die jeden der folgenden Argumentwerte -akzeptiert: - -@table @code -@item package -Mit diesem Wert verhält sich die Befehlszeilenoption @code{--sources} auf -genau die gleiche Weise wie die Befehlszeilenoption @code{--source}. - -@item all -Erstellt die Quellcode-Ableitungen aller Pakete einschließlich allen -Quellcodes, der als Teil der Eingaben im @code{inputs}-Feld aufgelistet -ist. Dies ist der vorgegebene Wert, wenn sonst keiner angegeben wird. - -@example -$ guix build --sources tzdata -Folgende Ableitungen werden erstellt: - /gnu/store/@dots{}-tzdata2015b.tar.gz.drv - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv -@end example - -@item transitive -Die Quellcode-Ableitungen aller Pakete sowie aller transitiven Eingaben der -Pakete erstellen. Damit kann z.B.@: Paket-Quellcode vorab heruntergeladen -und später offline erstellt werden. - -@example -$ guix build --sources=transitive tzdata -Folgende Ableitungen werden erstellt: - /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 -Die Befehlszeilenoption @code{--system} dient der @emph{nativen} -Kompilierung (nicht zu verwechseln mit Cross-Kompilierung). Siehe -@code{--target} unten für Informationen zur Cross-Kompilierung. -@end quotation - -Ein Beispiel sind Linux-basierte Systeme, die verschiedene Persönlichkeiten -emulieren können. Zum Beispiel können Sie @code{--system=i686-linux} auf -einem @code{x86_64-linux}-System oder @code{--system=armhf-linux} auf einem -@code{aarch64-linux}-System angeben, um Pakete in einer vollständigen -32-Bit-Umgebung zu erstellen. - -@quotation Anmerkung -Das Erstellen für ein @code{armhf-linux}-System ist ungeprüft auf allen -@code{aarch64-linux}-Maschinen aktiviert, obwohl bestimmte aarch64-Chipsätze -diese Funktionalität nicht unterstützen, darunter auch ThunderX. -@end quotation - -Ebenso können Sie, wenn transparente Emulation mit QEMU und -@code{binfmt_misc} aktiviert sind (siehe @ref{Virtualisierungsdienste, -@code{qemu-binfmt-service-type}}), für jedes System Erstellungen -durchführen, für das ein QEMU-@code{binfmt_misc}-Handler installiert ist. - -Erstellungen für ein anderes System, das nicht dem System der Maschine, die -Sie benutzen, entspricht, können auch auf eine entfernte Maschine mit der -richtigen Architektur ausgelagert werden. Siehe @ref{Auslagern des Daemons einrichten} -für mehr Informationen über das Auslagern. - -@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 (siehe -@ref{Specifying target triplets, GNU configuration triplets,, autoconf, -Autoconf}). - -@anchor{build-check} -@item --check -@cindex Determinismus, Überprüfung -@cindex Reproduzierbarkeit, Überprüfung -@var{Paket-oder-Ableitung} erneut erstellen, wenn diese bereits im Store -verfügbar ist, und einen Fehler melden, wenn die Erstellungsergebnisse nicht -Bit für Bit identisch sind. - -Mit diesem Mechanismus können Sie überprüfen, ob zuvor installierte -Substitute unverfälscht sind (siehe @ref{Substitute}) oder auch ob das -Erstellungsergebnis eines Pakets deterministisch ist. Siehe @ref{Aufruf von guix challenge} für mehr Hintergrundinformationen und Werkzeuge. - -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 Reparieren von Store-Objekten -@cindex Datenbeschädigung, Behebung -Versuchen, die angegebenen Store-Objekte zu reparieren, wenn sie beschädigt -sind, indem sie neu heruntergeladen oder neu erstellt werden. - -Diese Operation ist nicht atomar und nur der Administratornutzer @code{root} -kann sie verwenden. - -@item --derivations -@itemx -d -Liefert die Ableitungspfade und @emph{nicht} die Ausgabepfade für die -angegebenen Pakete. - -@item --root=@var{Datei} -@itemx -r @var{Datei} -@cindex GC-Wurzeln, Hinzufügen -@cindex Müllsammlerwurzeln, Hinzufügen -Die @var{Datei} zu einer symbolischen Verknüpfung auf das Ergebnis machen -und als Müllsammlerwurzel registrieren. - -Dadurch wird das Ergebnis dieses Aufrufs von @command{guix build} vor dem -Müllsammler geschützt, bis die @var{Datei} gelöscht wird. Wird diese -Befehlszeilenoption @emph{nicht} angegeben, können Erstellungsergebnisse vom -Müllsammler geholt werden, sobald die Erstellung abgeschlossen ist. Siehe -@ref{Aufruf von guix gc} für mehr Informationen zu Müllsammlerwurzeln. - -@item --log-file -@cindex Erstellungsprotokolle, Zugriff -Liefert die Dateinamen oder URLs der Erstellungsprotokolle für das -angegebene @var{Paket-oder-Ableitung} oder meldet einen Fehler, falls -Protokolldateien fehlen. - -Dies funktioniert, egal wie die Pakete oder Ableitungen angegeben -werden. Zum Beispiel sind folgende Aufrufe alle äquivalent: - -@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 - -Wenn ein Protokoll lokal nicht verfügbar ist und sofern -@code{--no-substitutes} nicht übergeben wurde, sucht der Befehl nach einem -entsprechenden Protokoll auf einem der Substitutserver (die mit -@code{--substitute-urls} angegeben werden können). - -Stellen Sie sich zum Beispiel vor, sie wollten das Erstellungsprotokoll von -GDB auf einem MIPS-System sehen, benutzen aber selbst eine -@code{x86_64}-Maschine: - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -So haben Sie umsonst Zugriff auf eine riesige Bibliothek von -Erstellungsprotokollen! -@end table - -@node Fehlschläge beim Erstellen untersuchen -@subsection Fehlschläge beim Erstellen untersuchen - -@cindex Erstellungsfehler, Fehlersuche -Wenn Sie ein neues Paket definieren (siehe @ref{Pakete definieren}), werden -Sie sich vermutlich einige Zeit mit der Fehlersuche beschäftigen und die -Erstellung so lange anpassen, bis sie funktioniert. Dazu müssen Sie die -Erstellungsbefehle selbst in einer Umgebung benutzen, die der, die der -Erstellungsdaemon aufbaut, so ähnlich wie möglich ist. - -Das Erste, was Sie dafür tun müssen, ist die Befehlszeilenoption -@option{--keep-failed} oder @option{-K} von @command{guix build} -einzusetzen, wodurch Verzeichnisbäume fehlgeschlagener Erstellungen in -@file{/tmp} oder dem von Ihnen als @code{TMPDIR} ausgewiesenen Verzeichnis -erhalten und nicht gelöscht werden (siehe @ref{Aufruf von guix build, -@code{--keep-failed}}). - -Im Anschluss können Sie mit @command{cd} in die Verzeichnisse dieses -fehlgeschlagenen Erstellungsbaums wechseln und mit @command{source} dessen -@file{environment-variables}-Datei laden, die alle -Umgebungsvariablendefinitionen enthält, die zum Zeitpunkt des Fehlschlags -der Erstellung galten. Sagen wir, Sie suchen Fehler in einem Paket -@code{foo}, dann würde eine typische Sitzung so aussehen: - -@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 - -Nun können Sie Befehle (fast) so aufrufen, als wären Sie der Daemon, und -Fehlerursachen in Ihrem Erstellungsprozess ermitteln. - -Manchmal passiert es, dass zum Beispiel die Tests eines Pakets erfolgreich -sind, wenn Sie sie manuell aufrufen, aber scheitern, wenn der Daemon sie -ausführt. Das kann passieren, weil der Daemon Erstellungen in isolierten -Umgebungen (»Containern«) durchführt, wo, anders als in der obigen Umgebung, -kein Netzwerkzugang möglich ist, @file{/bin/sh} nicht exisiert usw.@: (siehe -@ref{Einrichten der Erstellungsumgebung}). - -In solchen Fällen müssen Sie den Erstellungsprozess womöglich aus einer zu -der des Daemons ähnlichen isolierten Umgebung heraus ausprobieren: - -@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 - -Hierbei erzeugt @command{guix environment -C} eine isolierte Umgebung und -öffnet darin eine Shell (siehe @ref{Aufruf von guix environment}). Der Teil -mit @command{--ad-hoc strace gdb} fügt die Befehle @command{strace} und -@command{gdb} zur isolierten Umgebung hinzu, die Sie gut gebrauchen könnten, -während Sie Fehler suchen. Wegen der Befehlszeilenoption -@option{--no-grafts} bekommen Sie haargenau dieselbe Umgebung ohne veredelte -Pakete (siehe @ref{Sicherheitsaktualisierungen} für mehr Informationen zu -Veredelungen). - -Um der isolierten Umgebung des Erstellungsdaemons noch näher zu kommen, -können wir @file{/bin/sh} entfernen: - -@example -[env]# rm /bin/sh -@end example - -(Keine Sorge, das ist harmlos: All dies passiert nur in der zuvor von -@command{guix environment} erzeugten Wegwerf-Umgebung.) - -Der Befehl @command{strace} befindet sich wahrscheinlich nicht in Ihrem -Suchpfad, aber wir können ihn so benutzen: - -@example -[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check -@end example - -Auf diese Weise haben Sie nicht nur die Umgebungsvariablen, die der Daemon -benutzt, nachgebildet, sondern lassen auch den Erstellungsprozess in einer -isolierten Umgebung ähnlich der des Daemons laufen. - - -@node Aufruf von guix edit -@section @command{guix edit} aufrufen - -@cindex @command{guix edit} -@cindex Paketdefinition, Bearbeiten -So viele Pakete, so viele Quelldateien! Der Befehl @command{guix edit} -erleichtert das Leben von sowohl Nutzern als auch Paketentwicklern, indem er -Ihren Editor anweist, die Quelldatei mit der Definition des jeweiligen -Pakets zu bearbeiten. Zum Beispiel startet dies: - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -das mit der Umgebungsvariablen @code{VISUAL} ode @code{EDITOR} angegebene -Programm und lässt es das Rezept von GCC@tie{}4.9.3 und von Vim anzeigen. - -Wenn Sie ein Git-Checkout von Guix benutzen (siehe @ref{Erstellung aus dem Git}) -oder Ihre eigenen Pakete im @code{GUIX_PACKAGE_PATH} erstellt haben (siehe -@ref{Paketmodule}), werden Sie damit die Paketrezepte auch bearbeiten -können. Andernfalls werden Sie zumindest in die Lage versetzt, die nur -lesbaren Rezepte für sich im Moment im Store befindliche Pakete zu -untersuchen. - - -@node Aufruf von guix download -@section @command{guix download} aufrufen - -@cindex @command{guix download} -@cindex Paketquellcode herunterladen -Wenn Entwickler einer Paketdefinition selbige schreiben, müssen diese -normalerweise einen Quellcode-Tarball herunterladen, seinen SHA256-Hash als -Prüfsumme berechnen und diese in der Paketdefinition eintragen (siehe -@ref{Pakete definieren}). Das Werkzeug @command{guix download} hilft bei -dieser Aufgabe: Damit wird eine Datei von der angegebenen URI -heruntergeladen, in den Store eingelagert und sowohl ihr Dateiname im Store -als auch ihr SHA256-Hash als Prüfsumme angezeigt. - -Dadurch, dass die heruntergeladene Datei in den Store eingefügt wird, wird -Bandbreite gespart: Wenn der Entwickler schließlich versucht, das neu -definierte Paket mit @command{guix build} zu erstellen, muss der -Quell-Tarball nicht erneut heruntergeladen werden, weil er sich bereits im -Store befindet. Es ist auch eine bequeme Methode, Dateien temporär -aufzubewahren, die letztlich irgendwann gelöscht werden (siehe @ref{Aufruf von guix gc}). - -Der Befehl @command{guix download} unterstützt dieselben URIs, die in -Paketdefinitionen verwendet werden. Insbesondere unterstützt er -@code{mirror://}-URIs. @code{https}-URIs (HTTP über TLS) werden unterstützt, -@emph{vorausgesetzt} die Guile-Anbindungen für GnuTLS sind in der Umgebung -des Benutzers verfügbar; wenn nicht, wird ein Fehler gemeldet. Siehe -@ref{Guile Preparations, how to install the GnuTLS bindings for Guile,, -gnutls-guile, GnuTLS-Guile}, hat mehr Informationen. - -Mit @command{guix download} werden HTTPS-Serverzertifikate verifiziert, -indem die Zertifikate der X.509-Autoritäten in das durch die -Umgebungsvariable @code{SSL_CERT_DIR} bezeichnete Verzeichnis -heruntergeladen werden (siehe @ref{X.509-Zertifikate}), außer -@option{--no-check-certificate} wird benutzt. - -Folgende Befehlszeilenoptionen stehen zur Verfügung: - -@table @code -@item --format=@var{Format} -@itemx -f @var{Format} -Die Hash-Prüfsumme im angegebenen @var{Format} ausgeben. Für weitere -Informationen, was gültige Werte für das @var{Format} sind, siehe -@ref{Aufruf von guix hash}. - -@item --no-check-certificate -X.509-Zertifikate von HTTPS-Servern @emph{nicht} validieren. - -Wenn Sie diese Befehlszeilenoption benutzen, haben Sie @emph{keinerlei -Garantie}, dass Sie tatsächlich mit dem authentischen Server, der für die -angegebene URL verantwortlich ist, kommunizieren. Das macht Sie anfällig -gegen sogenannte »Man-in-the-Middle«-Angriffe. - -@item --output=@var{Datei} -@itemx -o @var{Datei} -Die heruntergeladene Datei @emph{nicht} in den Store, sondern in die -angegebene @var{Datei} abspeichern. -@end table - -@node Aufruf von guix hash -@section @command{guix hash} aufrufen - -@cindex @command{guix hash} -Der Befehl @command{guix hash} berechnet den SHA256-Hash einer Datei. Er ist -primär ein Werkzeug, dass es bequemer macht, etwas zur Distribution -beizusteuern: Damit wird die kryptografische Hash-Prüfsumme berechnet, die -bei der Definition eines Pakets benutzt werden kann (siehe @ref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix hash @var{Option} @var{Datei} -@end example - -Wird als @var{Datei} ein Bindestrich @code{-} angegeben, berechnet -@command{guix hash} den Hash der von der Standardeingabe gelesenen -Daten. @command{guix hash} unterstützt die folgenden Optionen: - -@table @code - -@item --format=@var{Format} -@itemx -f @var{Format} -Gibt die Prüfsumme im angegebenen @var{Format} aus. - -Unterstützte Formate: @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} und @code{hexadecimal} können auch benutzt werden). - -Wird keine Befehlszeilenoption @option{--format} angegeben, wird -@command{guix hash} die Prüfsumme im @code{nix-base32}-Format -ausgeben. Diese Darstellung wird bei der Definition von Paketen benutzt. - -@item --recursive -@itemx -r -Die Prüfsumme der @var{Datei} rekursiv berechnen. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -In diesem Fall wird die Prüfsumme eines Archivs berechnet, das die -@var{Datei} enthält, und auch ihre Kinder, wenn es sich um ein Verzeichnis -handelt. Einige der Metadaten der @var{Datei} sind Teil dieses Archivs. Zum -Beispiel unterscheidet sich die berechnete Prüfsumme, wenn die @var{Datei} -eine reguläre Datei ist, je nachdem, ob die @var{Datei} ausführbar ist oder -nicht. Metadaten wie der Zeitstempel haben keinen Einfluss auf die Prüfsumme -(siehe @ref{Aufruf von guix archive}). - -@item --exclude-vcs -@itemx -x -Wenn dies zusammen mit der Befehlszeilenoption @option{--recursive} -angegeben wird, werden Verzeichnisse zur Versionskontrolle (@file{.bzr}, -@file{.git}, @file{.hg}, etc.)@: vom Archiv ausgenommen. - -@vindex git-fetch -Zum Beispiel würden Sie auf diese Art die Prüfsumme eines Git-Checkouts -berechnen, was nützlich ist, wenn Sie die Prüfsumme für die Methode -@code{git-fetch} benutzen (siehe @ref{»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 @command{guix import} aufrufen - -@cindex Pakete importieren -@cindex Paketimport -@cindex Pakete an Guix anpassen -@cindex @command{guix import} aufrufen -Der Befehl @command{guix import} ist für Leute hilfreich, die ein Paket -gerne mit so wenig Arbeit wie möglich zur Distribution hinzufügen würden — -ein legitimer Anspruch. Der Befehl kennt ein paar Sammlungen, aus denen mit -ihm Paketmetadaten »importiert« werden können. Das Ergebnis ist eine -Paketdefinition oder eine Vorlage dafür in dem uns bekannten Format (siehe -@ref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix import @var{Importer} @var{Optionen}@dots{} -@end example - -Der @var{Importer} gibt die Quelle an, aus der Paketmetadaten importiert -werden, und die @var{Optionen} geben eine Paketbezeichnung und andere vom -@var{Importer} abhängige Daten an. Derzeit sind folgende »Importer« -verfügbar: - -@table @code -@item gnu -Metadaten für das angegebene GNU-Paket importieren. Damit wird eine Vorlage -für die neueste Version dieses GNU-Pakets zur Verfügung gestellt, -einschließlich der Prüfsumme seines Quellcode-Tarballs, seiner kanonischen -Zusammenfassung und seiner Beschreibung. - -Zusätzliche Informationen wie Paketabhängigkeiten und seine Lizenz müssen -noch manuell ermittelt werden. - -Zum Beispiel liefert der folgende Befehl eine Paketdefinition für -GNU@tie{}Hello: - -@example -guix import gnu hello -@end example - -Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur -Verfügung: - -@table @code -@item --key-download=@var{Richtlinie} -Die Richtlinie zum Umgang mit fehlenden OpenPGP-Schlüsseln beim Verifizieren -der Paketsignatur (auch »Beglaubigung« genannt) festlegen, wie bei -@code{guix refresh}. Siehe @ref{Aufruf von guix refresh, -@code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Metadaten aus dem @uref{https://pypi.python.org/, Python Package Index} -importieren. Informationen stammen aus der JSON-formatierten Beschreibung, -die unter @code{pypi.python.org} verfügbar ist, und enthalten meistens alle -relevanten Informationen einschließlich der Abhängigkeiten des Pakets. Für -maximale Effizienz wird empfohlen, das Hilfsprogramm @command{unzip} zu -installieren, damit der Importer »Python Wheels« entpacken und daraus Daten -beziehen kann. - -Der folgende Befehl importiert Metadaten für das Python-Paket namens -@code{itsdangerous}: - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -r -Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in -Guix noch nicht gibt. -@end table - -@item gem -@cindex gem -Metadaten von @uref{https://rubygems.org/, RubyGems} -importieren. Informationen kommen aus der JSON-formatierten Beschreibung, -die auf @code{rubygems.org} verfügbar ist, und enthält die relevantesten -Informationen einschließlich der Laufzeitabhängigkeiten. Dies hat aber auch -Schattenseiten — die Metadaten unterscheiden nicht zwischen -Zusammenfassungen und Beschreibungen, daher wird dieselbe Zeichenkette für -beides eingesetzt. Zudem fehlen Informationen zu nicht in Ruby geschriebenen -Abhängigkeiten, die benötigt werden, um native Erweiterungen zu in Ruby -geschriebenem Code zu erstellen. Diese herauszufinden bleibt dem -Paketentwickler überlassen. - -Der folgende Befehl importiert Metadaten aus dem Ruby-Paket @code{rails}. - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -r -Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in -Guix noch nicht gibt. -@end table - -@item cpan -@cindex CPAN -Importiert Metadaten von @uref{https://www.metacpan.org/, -MetaCPAN}. Informationen werden aus den JSON-formatierten Metadaten -genommen, die über die @uref{https://fastapi.metacpan.org/, -Programmierschnittstelle (»API«) von MetaCPAN} angeboten werden, und -enthalten die relevantesten Informationen wie zum Beispiel -Modulabhängigkeiten. Lizenzinformationen sollten genau nachgeprüft -werden. Wenn Perl im Store verfügbar ist, wird das Werkzeug @code{corelist} -benutzt, um Kernmodule in der Abhängigkeitsliste wegzulassen. - -Folgender Befehl importiert Metadaten für das Perl-Modul -@code{Acme::Boolean}: - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -Metadaten aus dem @uref{https://cran.r-project.org/, CRAN} importieren, der -zentralen Sammlung für die @uref{http://r-project.org, statistische und -grafische Umgebung GNU@tie{}R}. - -Informationen werden aus der Datei namens @code{DESCRIPTION} des Pakets -extrahiert. - -Der folgende Befehl importiert Metadaten für das @code{Cairo}-R-Paket: - -@example -guix import cran Cairo -@end example - -Wird zudem @code{--recursive} angegeben, wird der Importer den -Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für all die Pakete erzeugen, die noch nicht -Teil von Guix sind. - -Wird @code{--archive=bioconductor} angegeben, werden Metadaten vom -@uref{https://www.bioconductor.org/, Bioconductor} importiert, einer -Sammlung von R-Paketen zur Analyse und zum Verständnis von großen Mengen -genetischer Daten in der Bioinformatik. - -Informationen werden aus der @code{DESCRIPTION}-Datei im Paket extrahiert, -das auf der Weboberfläche des Bioconductor-SVN-Repositorys veröffentlicht -wurde. - -Der folgende Befehl importiert Metadaten für das R-Paket -@code{GenomicRanges}: - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex TeX Live -@cindex CTAN -Metadaten aus @uref{http://www.ctan.org/, CTAN}, dem umfassenden -TeX-Archivnetzwerk, herunterladen, was für TeX-Pakete benutzt wird, die Teil -der @uref{https://www.tug.org/texlive/, TeX-Live-Distribution} sind. - -Informationen über das Paket werden über die von CTAN angebotene -XML-Programmierschnittstelle bezogen, wohingegen der Quellcode aus dem -SVN-Repository des TeX-Live-Projekts heruntergeladen wird. Das wird so -gemacht, weil CTAN keine versionierten Archive vorhält. - -Der folgende Befehl importiert Metadaten für das TeX-Paket @code{fontspec}: - -@example -guix import texlive fontspec -@end example - -Wenn @code{--archive=VERZEICHNIS} angegeben wird, wird der Quellcode -@emph{nicht} aus dem Unterverzeichnis @file{latex} des -@file{texmf-dist/source}-Baums im SVN-Repository von TeX Live -heruntergeladen, sondern aus dem angegebenen Schwesterverzeichnis im selben -Wurzelverzeichnis. - -Der folgende Befehl importiert Metadaten für das Paket @code{ifxetex} aus -CTAN und lädt die Quelldateien aus dem Verzeichnis -@file{texmf/source/generic}: - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, Import -Paketmetadaten aus einer lokalen JSON-Datei importieren. Betrachten Sie -folgende Beispiel-Paketdefinition im 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 - -Die Felder sind genauso benannt wie bei einem @code{}-Verbundstyp -(siehe @ref{Pakete definieren}). Referenzen zu anderen Paketen stehen darin -als JSON-Liste von mit Anführungszeichen quotierten Zeichenketten wie -@code{guile} oder @code{guile@@2.0}. - -Der Importer unterstützt auch eine ausdrücklichere Definition der -Quelldateien mit den üblichen Feldern eines @code{}-Verbunds: - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -Der folgende Befehl liest Metadaten aus der JSON-Datei @code{hello.json} und -gibt einen Paketausdruck aus: - -@example -guix import json hello.json -@end example - -@item nix -Metadaten aus einer lokalen Kopie des Quellcodes der -@uref{http://nixos.org/nixpkgs/, Nixpkgs-Distribution} -importieren@footnote{Dazu wird der Befehl @command{nix-instantiate} von -@uref{http://nixos.org/nix/, Nix} verwendet.}. Paketdefinitionen in Nixpkgs -werden typischerweise in einer Mischung aus der Sprache von Nix und aus -Bash-Code geschrieben. Dieser Befehl wird nur die abstrakte Paketstruktur, -die in der Nix-Sprache geschrieben ist, importieren. Dazu gehören -normalerweise alle grundlegenden Felder einer Paketdefinition. - -Beim Importieren eines GNU-Pakets werden Zusammenfassung und Beschreibung -stattdessen durch deren kanonische Variante bei GNU ersetzt. - -Normalerweise würden Sie zunächst dies ausführen: - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -damit @command{nix-instantiate} nicht versucht, die Nix-Datenbank zu öffnen. - -Zum Beispiel importiert der Befehl unten die Paketdefinition von LibreOffice -(genauer gesagt importiert er die Definition des an das Attribut -@code{libreoffice} auf oberster Ebene gebundenen Pakets): - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Metadaten aus @uref{https://hackage.haskell.org/, Hackage}, dem zentralen -Paketarchiv der Haskell-Gemeinde, importieren. Informationen werden aus -Cabal-Dateien ausgelesen. Darin sind alle relevanten Informationen -einschließlich der Paketabhängigkeiten enthalten. - -Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur -Verfügung: - -@table @code -@item --stdin -@itemx -s -Eine Cabal-Datei von der Standardeingabe lesen. -@item --no-test-dependencies -@itemx -t -Keine Abhängigkeiten übernehmen, die nur von Testkatalogen benötigt werden. -@item --cabal-environment=@var{Aliste} -@itemx -e @var{Aliste} -@var{Aliste} muss eine assoziative Liste der Scheme-Programmiersprache sein, -die die Umgebung definiert, in der bedingte Ausdrücke von Cabal ausgewertet -werden. Dabei werden folgende Schlüssel akzeptiert: @code{os}, @code{arch}, -@code{impl} und eine Zeichenkette, die dem Namen einer Option (einer »Flag«) -entspricht. Der mit einer »Flag« assoziierte Wert muss entweder das Symbol -@code{true} oder @code{false} sein. Der anderen Schlüsseln zugeordnete Wert -muss mit der Definition des Cabal-Dateiformats konform sein. Der vorgegebene -Wert zu den Schlüsseln @code{os}, @code{arch} and @code{impl} ist jeweils -@samp{linux}, @samp{x86_64} bzw. @samp{ghc}. -@item --recursive -@itemx -r -Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in -Guix noch nicht gibt. -@end table - -Der folgende Befehl importiert Metadaten für die neuste Version des -Haskell-@code{HTTP}-Pakets, ohne Testabhängigkeiten zu übernehmen und bei -Übergabe von @code{false} als Wert der Flag @samp{network-uri}: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -Eine ganz bestimmte Paketversion kann optional ausgewählt werden, indem man -nach dem Paketnamen anschließend ein At-Zeichen und eine Versionsnummer -angibt wie in folgendem Beispiel: - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -Der @code{stackage}-Importer ist ein Wrapper um den -@code{hackage}-Importer. Er nimmt einen Paketnamen und schaut dafür die -Paketversion nach, die Teil einer @uref{https://www.stackage.org, -Stackage}-Veröffentlichung mit Langzeitunterstützung (englisch »Long-Term -Support«, kurz LTS) ist, deren Metadaten er dann mit dem -@code{hackage}-Importer bezieht. Beachten Sie, dass es Ihre Aufgabe ist, -eine LTS-Veröffentlichung auszuwählen, die mit dem von Guix benutzten -GHC-Compiler kompatibel ist. - -Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur -Verfügung: - -@table @code -@item --no-test-dependencies -@itemx -t -Keine Abhängigkeiten übernehmen, die nur von Testkatalogen benötigt werden. -@item --lts-version=@var{Version} -@itemx -l @var{Version} -@var{Version} ist die gewünschte Version der LTS-Veröffentlichung. Wird -keine angegeben, wird die neueste benutzt. -@item --recursive -@itemx -r -Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in -Guix noch nicht gibt. -@end table - -Der folgende Befehl importiert Metadaten für dasjenige -@code{HTTP}-Haskell-Paket, das in der LTS-Stackage-Veröffentlichung mit -Version 7.18 vorkommt: - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Metadaten aus der Paketsammlung »Emacs Lisp Package Archive« (ELPA) -importieren (siehe @ref{Packages,,, emacs, The GNU Emacs Manual}). - -Speziell für diesen Importer stehen noch folgende Befehlszeilenoptionen zur -Verfügung: - -@table @code -@item --archive=@var{Repo} -@itemx -a @var{Repo} -Mit @var{Repo} wird die Archiv-Sammlung (ein »Repository«) bezeichnet, von -dem die Informationen bezogen werden sollen. Derzeit sind die unterstützten -Repositorys und ihre Bezeichnungen folgende: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, bezeichnet mit @code{gnu}. Dies -ist die Vorgabe. - -Pakete aus @code{elpa.gnu.org} wurden mit einem der Schlüssel im -GnuPG-Schlüsselbund in @file{share/emacs/25.1/etc/package-keyring.gpg} (oder -einem ähnlichen Pfad) des @code{emacs}-Pakets signiert (siehe @ref{Package -Installation, ELPA package signatures,, emacs, The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, bezeichnet mit -@code{melpa-stable}. - -@item -@uref{http://melpa.org/packages, MELPA}, bezeichnet mit @code{melpa}. -@end itemize - -@item --recursive -@itemx -r -Den Abhängigkeitsgraphen des angegebenen Pakets beim Anbieter rekursiv -durchlaufen und Paketausdrücke für alle solchen Pakete erzeugen, die es in -Guix noch nicht gibt. -@end table - -@item crate -@cindex crate -Metadaten aus der Paketsammlung crates.io für Rust importieren -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Metadaten aus der Paketsammlung @uref{https://opam.ocaml.org/, OPAM} der -OCaml-Gemeinde importieren. -@end table - -@command{guix import} verfügt über eine modulare Code-Struktur. Mehr -Importer für andere Paketformate zu haben, wäre nützlich, und Ihre Hilfe ist -hierbei gerne gesehen (siehe @ref{Mitwirken}). - -@node Aufruf von guix refresh -@section @command{guix refresh} aufrufen - -@cindex @command{guix refresh} -Die Zielgruppe des Befehls @command{guix refresh} zum Auffrischen von -Paketen sind in erster Linie Entwickler der GNU-Software-Distribution. Nach -Vorgabe werden damit alle Pakete in der Distribution gemeldet, die nicht der -neuesten Version des Anbieters entsprechen, indem Sie dies ausführen: - -@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 - -Alternativ können die zu betrachtenden Pakete dabei angegeben werden, was -zur Ausgabe einer Warnung führt, wenn es für Pakete kein -Aktualisierungsprogramm gibt: - -@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} durchsucht die Paketsammlung beim Anbieter jedes -Pakets und bestimmt, was die höchste Versionsnummer ist, zu der es dort eine -Veröffentlichung gibt. Zum Befehl gehören Aktualisierungsprogramme, mit -denen bestimmte Typen von Paketen automatisch aktualisiert werden können: -GNU-Pakete, ELPA-Pakete usw.@: — siehe die Dokumentation von @option{--type} -unten. Es gibt jedoch auch viele Pakete, für die noch keine Methode -enthalten ist, um das Vorhandensein einer neuen Veröffentlichung zu -prüfen. Der Mechanismus ist aber erweiterbar, also können Sie gerne mit uns -in Kontakt treten, wenn Sie eine neue Methode hinzufügen möchten! - -@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 - -Manchmal unterscheidet sich der vom Anbieter benutzte Name von dem -Paketnamen, der in Guix verwendet wird, so dass @command{guix refresh} etwas -Unterstützung braucht. Die meisten Aktualisierungsprogramme folgen der -Eigenschaft @code{upstream-name} in Paketdefinitionen, die diese -Unterstützung bieten kann. - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -Wenn @code{--update} übergeben wird, werden die Quelldateien der -Distribution verändert, so dass für diese Paketrezepte die aktuelle Version -und die aktuelle Hash-Prüfsumme des Quellcode-Tarballs eingetragen wird -(siehe @ref{Pakete definieren}). Dazu werden der neueste Quellcode-Tarball -jedes Pakets sowie die jeweils zugehörige OpenPGP-Signatur heruntergeladen; -mit Letzterer wird der heruntergeladene Tarball gegen seine Signatur mit -@command{gpg} authentifiziert und schließlich dessen Hash berechnet. Wenn -der öffentliche Schlüssel, mit dem der Tarball signiert wurde, im -Schlüsselbund des Benutzers fehlt, wird versucht, ihn automatisch von einem -Schlüssel-Server zu holen; wenn das klappt, wird der Schlüssel zum -Schlüsselbund des Benutzers hinzugefügt, ansonsten meldet @command{guix -refresh} einen Fehler. - -Die folgenden Befehlszeilenoptionen werden unterstützt: - -@table @code - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -Dies ist nützlich, um genau ein bestimmtes Paket zu referenzieren, wie in -diesem Beispiel: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -Dieser Befehls listet auf, was alles von der »endgültigen« Erstellung von -libc abhängt (praktisch alle Pakete). - -@item --update -@itemx -u -Die Quelldateien der Distribution (die Paketrezepte) werden direkt »in -place« verändert. Normalerweise führen Sie dies aus einem Checkout des -Guix-Quellbaums heraus aus (siehe @ref{Guix vor der Installation ausführen}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -Siehe @ref{Pakete definieren} für mehr Informationen zu Paketdefinitionen. - -@item --select=[@var{Teilmenge}] -@itemx -s @var{Teilmenge} -Wählt alle Pakete aus der @var{Teilmenge} aus, die entweder @code{core} oder -@code{non-core} sein muss. - -Die @code{core}-Teilmenge bezieht sich auf alle Pakete, die den Kern der -Distribution ausmachen, d.h.@: Pakete, aus denen heraus »alles andere« -erstellt wird. Dazu gehören GCC, libc, Binutils, Bash und so weiter. In der -Regel ist die Folge einer Änderung an einem dieser Pakete in der -Distribution, dass alle anderen neu erstellt werden müssen. Daher sind -solche Änderungen unangenehm für Nutzer, weil sie einiges an Erstellungszeit -oder Bandbreite investieren müssen, um die Aktualisierung abzuschließen. - -Die @code{non-core}-Teilmenge bezieht sich auf die übrigen Pakete. Sie wird -typischerweise dann benutzt, wenn eine Aktualisierung der Kernpakete zu -viele Umstände machen würde. - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Wählt alle Pakete im in der @var{Datei} stehenden Manifest aus. Das ist -nützlich, um zu überprüfen, welche Pakete aus dem Manifest des Nutzers -aktualisiert werden können. - -@item --type=@var{Aktualisierungsprogramm} -@itemx -t @var{Aktualisierungsprogramm} -Nur solche Pakete auswählen, die vom angegebenen -@var{Aktualisierungsprogramm} behandelt werden. Es darf auch eine -kommagetrennte Liste mehrerer Aktualisierungsprogramme angegeben werden. Zur -Zeit kann als @var{Aktualisierungsprogramm} eines der folgenden angegeben -werden: - -@table @code -@item gnu -Aktualisierungsprogramm für GNU-Pakete, -@item gnome -Aktualisierungsprogramm für GNOME-Pakete, -@item kde -Aktualisierungsprogramm für KDE-Pakete, -@item xorg -Aktualisierungsprogramm für X.org-Pakete, -@item kernel.org -Aktualisierungsprogramm auf kernel.org angebotener Pakete, -@item elpa -Aktualisierungsprogramm für @uref{http://elpa.gnu.org/, ELPA-Pakete}, -@item cran -Aktualisierungsprogramm für @uref{https://cran.r-project.org/, CRAN-Pakete}, -@item bioconductor -Aktualisierungsprogramm für R-Pakete vom -@uref{https://www.bioconductor.org/, Bioconductor}, -@item cpan -Aktualisierungsprogramm für @uref{http://www.cpan.org/, CPAN-Pakete}, -@item pypi -Aktualisierungsprogramm für @uref{https://pypi.python.org, PyPI-Pakete}, -@item gem -Aktualisierungsprogramm für @uref{https://rubygems.org, RubyGems-Pakete}. -@item github -Aktualisierungsprogramm für @uref{https://github.com, GitHub-Pakete}. -@item hackage -Aktualisierungsprogramm für @uref{https://hackage.haskell.org, -Hackage-Pakete}. -@item stackage -Aktualisierungsprogramm für @uref{https://www.stackage.org, -Stackage-Pakete}. -@item crate -Aktualisierungsprogramm für @uref{https://crates.io, Crates-Pakete}. -@item launchpad -Aktualisierungsprogramm für @uref{https://launchpad.net, Launchpad}. -@end table - -Zum Beispiel prüft folgender Befehl nur auf mögliche Aktualisierungen von -auf @code{elpa.gnu.org} angebotenen Emacs-Paketen und von CRAN-Paketen: - -@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 - -An @command{guix refresh} können auch ein oder mehrere Paketnamen übergeben -werden wie in diesem Beispiel: - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -Der Befehl oben aktualisiert speziell das @code{emacs}- und das -@code{idutils}-Paket. Eine Befehlszeilenoption @code{--select} hätte dann -keine Wirkung. - -Wenn Sie sich fragen, ob ein Paket aktualisiert werden sollte oder nicht, -kann es helfen, sich anzuschauen, welche Pakete von der Aktualisierung -betroffen wären und auf Kompatibilität hin geprüft werden sollten. Dazu kann -die folgende Befehlszeilenoption zusammen mit einem oder mehreren Paketnamen -an @command{guix refresh} übergeben werden: - -@table @code - -@item --list-updaters -@itemx -L -Eine Liste verfügbarer Aktualisierungsprogramme anzeigen und terminieren -(siehe @option{--type} oben). - -Für jedes Aktualisierungsprogramm den Anteil der davon betroffenen Pakete -anzeigen; zum Schluss wird der Gesamtanteil von irgendeinem -Aktualisierungsprogramm betroffener Pakete angezeigt. - -@item --list-dependent -@itemx -l -Auflisten, welche abhängigen Pakete auf oberster Ebene neu erstellt werden -müssten, wenn eines oder mehrere Pakete aktualisiert würden. - -Siehe @ref{Aufruf von guix graph, den @code{reverse-package}-Typ von -@command{guix graph}} für Informationen dazu, wie Sie die Liste der -Abhängigen eines Pakets visualisieren können. - -@end table - -Bedenken Sie, dass die Befehlszeilenoption @code{--list-dependent} das -Ausmaß der nach einer Aktualisierungen benötigten Neuerstellungen nur -@emph{annähert}. Es könnten auch unter Umständen mehr Neuerstellungen -anfallen. - -@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 - -Der oben stehende Befehl gibt einen Satz von Paketen aus, die Sie erstellen -wollen könnten, um die Kompatibilität einer Aktualisierung des -@code{flex}-Pakets beurteilen zu können. - -@table @code - -@item --list-transitive -Die Pakete auflisten, von denen eines oder mehrere Pakete abhängen. - -@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 - -Der oben stehende Befehl gibt einen Satz von Paketen aus, die, wenn sie -geändert würden, eine Neuerstellung des @code{flex}-Pakets auslösen würden. - -Mit den folgenden Befehlszeilenoptionen können Sie das Verhalten von GnuPG -anpassen: - -@table @code - -@item --gpg=@var{Befehl} -Den @var{Befehl} als GnuPG-2.x-Befehl einsetzen. Der @var{Befehl} wird im -@code{$PATH} gesucht. - -@item --keyring=@var{Datei} -Die @var{Datei} als Schlüsselbund mit Anbieterschlüsseln verwenden. Die -@var{Datei} muss im @dfn{Keybox-Format} vorliegen. Keybox-Dateien haben -normalerweise einen Namen, der auf @file{.kbx} endet. Sie können mit Hilfe -von GNU@tie{}Privacy Guard (GPG) bearbeitet werden (siehe @ref{kbxutil, -@command{kbxutil},, gnupg, Using the GNU Privacy Guard} für Informationen -über ein Werkzeug zum Bearbeiten von Keybox-Dateien). - -Wenn diese Befehlszeilenoption nicht angegeben wird, benutzt @command{guix -refresh} die Keybox-Datei @file{~/.config/guix/upstream/trustedkeys.kbx} als -Schlüsselbund für Signierschlüssel von Anbietern. OpenPGP-Signaturen werden -mit Schlüsseln aus diesem Schlüsselbund überprüft; fehlende Schlüssel werden -auch in diesen Schlüsselbund heruntergeladen (siehe @option{--key-download} -unten). - -Sie können Schlüssel aus Ihrem normalerweise benutzten GPG-Schlüsselbund in -eine Keybox-Datei exportieren, indem Sie Befehle wie diesen benutzen: - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx -@end example - -Ebenso können Sie wie folgt Schlüssel in eine bestimmte Keybox-Datei -herunterladen: - -@example -gpg --no-default-keyring --keyring mykeyring.kbx \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -Siehe @ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the -GNU Privacy Guard} für mehr Informationen zur Befehlszeilenoption -@option{--keyring} von GPG. - -@item --key-download=@var{Richtlinie} -Fehlende OpenPGP-Schlüssel gemäß dieser @var{Richtlinie} behandeln, für die -eine der Folgenden angegeben werden kann: - -@table @code -@item always -Immer fehlende OpenPGP-Schlüssel herunterladen und zum GnuPG-Schlüsselbund -des Nutzers hinzufügen. - -@item never -Niemals fehlende OpenPGP-Schlüssel herunterladen, sondern einfach abbrechen. - -@item interactive -Ist ein Paket mit einem unbekannten OpenPGP-Schlüssel signiert, wird der -Nutzer gefragt, ob der Schlüssel heruntergeladen werden soll oder -nicht. Dies entspricht dem vorgegebenen Verhalten. -@end table - -@item --key-server=@var{Host} -Den mit @var{Host} bezeichneten Rechner als Schlüsselserver für OpenPGP -benutzen, wenn ein öffentlicher Schlüssel importiert wird. - -@end table - -Das @code{github}-Aktualisierungsprogramm benutzt die -@uref{https://developer.github.com/v3/, GitHub-Programmierschnittstelle} -(die »Github-API«), um Informationen über neue Veröffentlichungen -einzuholen. Geschieht dies oft, z.B.@: beim Auffrischen aller Pakete, so -wird GitHub irgendwann aufhören, weitere API-Anfragen zu -beantworten. Normalerweise sind 60 API-Anfragen pro Stunde erlaubt, für eine -vollständige Auffrischung aller GitHub-Pakete in Guix werden aber mehr -benötigt. Wenn Sie sich bei GitHub mit Ihrem eigenen API-Token -authentisieren, gelten weniger einschränkende Grenzwerte. Um einen API-Token -zu benutzen, setzen Sie die Umgebungsvariable @code{GUIX_GITHUB_TOKEN} auf -einen von @uref{https://github.com/settings/tokens} oder anderweitig -bezogenen API-Token. - - -@node Aufruf von guix lint -@section @command{guix lint} aufrufen - -@cindex @command{guix lint} -@cindex Pakete, auf Fehler prüfen -Den Befehl @command{guix lint} gibt es, um Paketentwicklern beim Vermeiden -häufiger Fehler und bei der Einhaltung eines konsistenten Code-Stils zu -helfen. Er führt eine Reihe von Prüfungen auf einer angegebenen Menge von -Paketen durch, um in deren Definition häufige Fehler aufzuspüren. Zu den -verfügbaren @dfn{Prüfern} gehören (siehe @code{--list-checkers} für eine -vollständige Liste): - -@table @code -@item synopsis -@itemx description -Überprüfen, ob bestimmte typografische und stilistische Regeln in -Paketbeschreibungen und -zusammenfassungen eingehalten wurden. - -@item inputs-should-be-native -Eingaben identifizieren, die wahrscheinlich native Eingaben sein sollten. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Die URLs für die Felder @code{home-page} und @code{source} anrufen und nicht -erreichbare URLs melden. Wenn passend, wird eine @code{mirror://}-URL -vorgeschlagen. Wenn die Quell-URL auf eine GitHub-URL weiterleitet, wird -eine Empfehlung ausgegeben, direkt letztere zu verwenden. Es wird geprüft, -dass der Quell-Dateiname aussagekräftig ist, dass er also z.B.@: nicht nur -aus einer Versionsnummer besteht oder als »git-checkout« angegeben wurde, -ohne dass ein @code{Dateiname} deklariert wurde (siehe @ref{»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 Sicherheitslücken -@cindex CVE, Common Vulnerabilities and Exposures -Bekannte Sicherheitslücken melden, die in den Datenbanken der »Common -Vulnerabilities and Exposures« (CVE) aus diesem und dem letzten Jahr -vorkommen, @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, wie sie von der -US-amerikanischen NIST veröffentlicht werden}. - -Um Informationen über eine bestimmte Sicherheitslücke angezeigt zu bekommen, -besuchen Sie Webseiten wie: - -@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 -wobei Sie statt @code{CVE-YYYY-ABCD} die CVE-Kennnummer angeben — z.B.@: -@code{CVE-2015-7554}. - -Paketentwickler können in ihren Paketrezepten den Namen und die Version des -Pakets in der @uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration -(CPE)} angeben, falls sich diese von dem in Guix benutzten Namen und der -Version unterscheiden, zum Beispiel so: - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE bezeichnet das Paket als "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See . -Manche Einträge in der CVE-Datenbank geben die Version des Pakets nicht an, -auf das sie sich beziehen, und würden daher bis in alle Ewigkeit Warnungen -auslösen. Paketentwickler, die CVE-Warnmeldungen gefunden und geprüft haben, -dass diese ignoriert werden können, können sie wie in diesem Beispiel -deklarieren: - -@example -(package - (name "t1lib") - ;; @dots{} - ;; Diese CVEs treffen nicht mehr zu und können bedenkenlos ignoriert - ;; werden. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item Formatierung -Offensichtliche Fehler bei der Formatierung von Quellcode melden, z.B.@: -Leerraum-Zeichen am Zeilenende oder Nutzung von Tabulatorzeichen. -@end table - -Die allgemeine Syntax lautet: - -@example -guix lint @var{Optionen} @var{Pakete}@dots{} -@end example - -Wird kein Paket auf der Befehlszeile angegeben, dann werden alle Pakete -geprüft, die es gibt. Als @var{Optionen} können null oder mehr der folgenden -Befehlszeilenoptionen übergeben werden: - -@table @code -@item --list-checkers -@itemx -l -Alle verfügbaren Prüfer für die Pakete auflisten und beschreiben. - -@item --checkers -@itemx -c -Nur die Prüfer aktivieren, die hiernach in einer kommagetrennten Liste aus -von @code{--list-checkers} aufgeführten Prüfern vorkommen. - -@end table - -@node Aufruf von guix size -@section @command{guix size} aufrufen - -@cindex Größe -@cindex Paketgröße -@cindex Abschluss -@cindex @command{guix size} -Der Befehl @command{guix size} hilft Paketentwicklern dabei, den -Plattenplatzverbrauch von Paketen zu profilieren. Es ist leicht, die -Auswirkungen zu unterschätzen, die das Hinzufügen zusätzlicher -Abhängigkeiten zu einem Paket hat oder die das Verwenden einer einzelnen -Ausgabe für ein leicht aufteilbares Paket ausmacht (siehe @ref{Pakete mit mehreren Ausgaben.}). Das sind typische Probleme, auf die @command{guix size} -aufmerksam machen kann. - -Dem Befehl können eine oder mehrere Paketspezifikationen wie @code{gcc@@4.8} -oder @code{guile:debug} übergeben werden, oder ein Dateiname im -Store. Betrachten Sie dieses Beispiel: - -@example -$ guix size coreutils -Store-Objekt Gesamt Selbst -/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% -Gesamt: 78.9 MiB -@end example - -@cindex Abschluss -Die hier aufgelisteten Store-Objekte bilden den @dfn{transitiven Abschluss} -der Coreutils — d.h.@: die Coreutils und all ihre Abhängigkeiten und deren -Abhängigkeiten, rekursiv —, wie sie hiervon angezeigt würden: dag.pdf -@end example - -Die Ausgabe sieht so aus: - -@image{images/coreutils-graph,2in,,Abhängigkeitsgraph der GNU Coreutils} - -Ein netter, kleiner Graph, oder? - -Aber es gibt mehr als eine Art von Graph! Der Graph oben ist kurz und knapp: -Es ist der Graph der Paketobjekte, ohne implizite Eingaben wie GCC, libc, -grep und so weiter. Oft möchte man einen knappen Graphen sehen, aber -manchmal will man auch mehr Details sehen. @command{guix graph} unterstützt -mehrere Typen von Graphen; Sie können den Detailgrad auswählen. - -@table @code -@item package -Der vorgegebene Typ aus dem Beispiel oben. Er zeigt den DAG der Paketobjekte -ohne implizite Abhängigkeiten. Er ist knapp, filtert aber viele Details -heraus. - -@item reverse-package -Dies zeigt den @emph{umgekehrten} DAG der Pakete. Zum Beispiel: - -@example -guix graph --type=reverse-package ocaml -@end example - -...@: yields the graph of packages that @emph{explicitly} depend on OCaml -(if you are also interested in cases where OCaml is an implicit dependency, -see @code{reverse-bag} below.) - -Beachten Sie, dass für Kernpakete damit gigantische Graphen entstehen -können. Wenn Sie nur die Anzahl der Pakete wissen wollen, die von einem -gegebenen Paket abhängen, benutzen Sie @command{guix refresh ---list-dependent} (siehe @ref{Aufruf von guix refresh, -@option{--list-dependent}}). - -@item bag-emerged -Dies ist der Paket-DAG @emph{einschließlich} impliziter Eingaben. - -Zum Beispiel liefert der folgende Befehl: - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf -@end example - -…@: diesen größeren Graphen: - -@image{images/coreutils-bag-graph,,5in,Detaillierter Abhängigkeitsgraph der -GNU Coreutils} - -Am unteren Rand des Graphen sehen wir alle impliziten Eingaben des -@var{gnu-build-system} (siehe @ref{Erstellungssysteme, @code{gnu-build-system}}). - -Beachten Sie dabei aber, dass auch hier die Abhängigkeiten dieser impliziten -Eingaben — d.h.@: die @dfn{Bootstrap-Abhängigkeiten} (siehe -@ref{Bootstrapping}) — nicht gezeigt werden, damit der Graph knapper bleibt. - -@item bag -Ähnlich wie @code{bag-emerged}, aber diesmal mit allen -Bootstrap-Abhängigkeiten. - -@item bag-with-origins -Ähnlich wie @code{bag}, aber auch mit den Ursprüngen und deren -Abhängigkeiten. - -@item reverse-bag -This shows the @emph{reverse} DAG of packages. Unlike -@code{reverse-package}, it also takes implicit dependencies into account. -For example: - -@example -guix graph -t reverse-bag dune -@end example - -@noindent -...@: yields the graph of all packages that depend on Dune, directly or -indirectly. Since Dune is an @emph{implicit} dependency of many packages -@i{via} @code{dune-build-system}, this shows a large number of packages, -whereas @code{reverse-package} would show very few if any. - -@item Ableitung -Diese Darstellung ist am detailliertesten: Sie zeigt den DAG der Ableitungen -(siehe @ref{Ableitungen}) und der einfachen Store-Objekte. Verglichen mit -obiger Darstellung sieht man viele zusätzliche Knoten einschließlich -Erstellungs-Skripts, Patches, Guile-Module usw. - -Für diesen Typ Graph kann auch der Name einer @file{.drv}-Datei anstelle -eines Paketnamens angegeben werden, etwa so: - -@example -guix graph -t derivation `guix system build -d my-config.scm` -@end example - -@item module -Dies ist der Graph der @dfn{Paketmodule} (siehe @ref{Paketmodule}). Zum -Beispiel zeigt der folgende Befehl den Graph für das Paketmodul an, das das -@code{guile}-Paket definiert: - -@example -guix graph -t module guile | dot -Tpdf > modul-graph.pdf -@end example -@end table - -Alle oben genannten Typen entsprechen @emph{Abhängigkeiten zur -Erstellungszeit}. Der folgende Graphtyp repräsentiert die -@emph{Abhängigkeiten zur Laufzeit}: - -@table @code -@item references -Dies ist der Graph der @dfn{Referenzen} einer Paketausgabe, wie -@command{guix gc --references} sie liefert (siehe @ref{Aufruf von guix gc}). - -Wenn die angegebene Paketausgabe im Store nicht verfügbar ist, versucht -@command{guix graph}, die Abhängigkeitsinformationen aus Substituten zu -holen. - -Hierbei können Sie auch einen Store-Dateinamen statt eines Paketnamens -angeben. Zum Beispiel generiert der Befehl unten den Referenzgraphen Ihres -Profils (der sehr groß werden kann!): - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -Dies ist der Graph der ein Store-Objekt @dfn{referenzierenden} Objekte, wie -@command{guix gc --referrers} sie liefern würde (siehe @ref{Aufruf von guix gc}). - -Er basiert ausschließlich auf lokalen Informationen aus Ihrem Store. Nehmen -wir zum Beispiel an, dass das aktuelle Inkscape in 10 Profilen verfügbar -ist, dann wird @command{guix graph -t referrers inkscape} einen Graph -zeigen, der bei Inkscape gewurzelt ist und Kanten zu diesen 10 Profilen hat. - -Ein solcher Graph kann dabei helfen, herauszufinden, weshalb ein -Store-Objekt nicht vom Müllsammler abgeholt werden kann. - -@end table - -Folgendes sind die verfügbaren Befehlszeilenoptionen: - -@table @option -@item --type=@var{Typ} -@itemx -t @var{Typ} -Eine Graph-Ausgabe dieses @var{Typ}s generieren. Dieser @var{Typ} muss einer -der oben genannten Werte sein. - -@item --list-types -Die unterstützten Graph-Typen auflisten. - -@item --backend=@var{Backend} -@itemx -b @var{Backend} -Einen Graph mit Hilfe des ausgewählten @var{Backend}s generieren. - -@item --list-backends -Die unterstützten Graph-Backends auflisten. - -Derzeit sind die verfügbaren Backends Graphviz und d3.js. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -Dies ist nützlich, um genau ein bestimmtes Paket zu referenzieren, wie in -diesem Beispiel: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{System} -@itemx -s @var{System} -Den Graphen für das @var{System} anzeigen — z.B.@: @code{i686-linux}. - -Der Abhängigkeitsgraph ist größtenteils von der Systemarchitektur -unabhängig, aber ein paar architekturabhängige Teile können Ihnen mit dieser -Befehlszeilenoption visualisiert werden. -@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 (siehe @ref{Substitute}). - -Wenn @command{guix publish} ausgeführt wird, wird dadurch ein HTTP-Server -gestartet, so dass jeder mit Netzwerkzugang davon Substitute beziehen -kann. Das bedeutet, dass jede Maschine, auf der Guix läuft, auch als -Build-Farm fungieren kann, weil die HTTP-Schnittstelle mit Hydra, der -Software, mit der die offizielle Build-Farm @code{@value{SUBSTITUTE-SERVER}} -betrieben wird, kompatibel ist. - -Um Sicherheit zu gewährleisten, wird jedes Substitut signiert, so dass -Empfänger dessen Authentizität und Integrität nachprüfen können (siehe -@ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{Aufruf von guix weather}). - -Als Bonus dient @command{guix publish} auch als inhaltsadressierbarer -Spiegelserver für Quelldateien, die in @code{origin}-Verbundsobjekten -eingetragen sind (siehe @ref{»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 @ref{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 (siehe @ref{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. - -Folgende Befehlszeilenoptionen stehen zur Verfügung: - -@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 (siehe -@ref{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 (siehe @ref{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 (siehe @ref{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 - -@command{guix publish} auf einem »Guix System«-System zu aktivieren ist ein -Einzeiler: Instanziieren Sie einfach einen -@code{guix-publish-service-type}-Dienst im @code{services}-Feld Ihres -@code{operating-system}-Objekts zur Betriebssystemdeklaration (siehe -@ref{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 @command{guix challenge} aufrufen - -@cindex Reproduzierbare Erstellungen -@cindex verifizierbare Erstellungen -@cindex @command{guix challenge} -@cindex Anfechten -Entsprechen die von diesem Server gelieferten Binärdateien tatsächlich dem -Quellcode, aus dem sie angeblich erzeugt wurden? Ist ein -Paketerstellungsprozess deterministisch? Diese Fragen versucht @command{guix -challenge} zu beantworten. - -Die erste Frage ist offensichtlich wichtig: Bevor man einen Substitutserver -benutzt (siehe @ref{Substitute}), @emph{verifiziert} man besser, dass er -die richtigen Binärdateien liefert, d.h.@: man @emph{fechtet sie an}. Die -letzte Frage macht die erste möglich: Wenn Paketerstellungen deterministisch -sind, müssten voneinander unabhängige Erstellungen genau dasselbe Ergebnis -liefern, Bit für Bit; wenn ein Server mit einer anderen Binärdatei als der -lokal erstellten Binärdatei antwortet, ist diese entweder beschädigt oder -bösartig. - -Wir wissen, dass die in @file{/gnu/store}-Dateinamen auftauchende -Hash-Prüfsumme der Hash aller Eingaben des Prozesses ist, mit dem die Datei -oder das Verzeichnis erstellt wurde — Compiler, Bibliotheken, -Erstellungsskripts und so weiter (siehe @ref{Einführung}). Wenn wir von -deterministischen Erstellungen ausgehen, sollte ein Store-Dateiname also auf -genau eine Erstellungsausgabe abgebildet werden. Mit @command{guix -challenge} prüft man, ob es tatsächlich eine eindeutige Abbildung gibt, -indem die Erstellungsausgaben mehrerer unabhängiger Erstellungen jedes -angegebenen Store-Objekts verglichen werden. - -Die Ausgabe des Befehls sieht so aus: - -@smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" -Liste der Substitute von »https://@value{SUBSTITUTE-SERVER}« wird aktualisiert … 100.0% -Liste der Substitute von »https://guix.example.org« wird aktualisiert … 100.0% -Inhalt von /gnu/store/@dots{}-openssl-1.0.2d verschieden: - lokale Prüfsumme: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim -Inhalt von /gnu/store/@dots{}-git-2.5.0 verschieden: - lokale Prüfsumme: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 -Inhalt von /gnu/store/@dots{}-pius-2.1.1 verschieden: - lokale Prüfsumme: 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-Objekte wurden analysiert: - — 4,749 (74.1%) waren identisch - — 525 (8.2%) unterscheiden sich - — 1,132 (17.7%) blieben ergebnislos -@end smallexample - -@noindent -In diesem Beispiel wird mit @command{guix challenge} zuerst die Menge lokal -erstellter Ableitungen im Store ermittelt — im Gegensatz zu von einem -Substitserver heruntergeladenen Store-Objekten — und dann werden alle -Substitutserver angefragt. Diejenigen Store-Objekte, bei denen der Server -ein anderes Ergebnis berechnet hat als die lokale Erstellung, werden -gemeldet. - -@cindex Nichtdeterminismus, in Paketerstellungen -Nehmen wir zum Beispiel an, @code{guix.example.org} gibt uns immer eine -verschiedene Antwort, aber @code{@value{SUBSTITUTE-SERVER}} stimmt mit -lokalen Erstellungen überein, @emph{außer} im Fall von Git. Das könnte ein -Hinweis sein, dass der Erstellungsprozess von Git nichtdeterministisch ist; -das bedeutet, seine Ausgabe variiert abhängig von verschiedenen Umständen, -die Guix nicht vollends kontrollieren kann, obwohl es Pakete in isolierten -Umgebungen erstellt (siehe @ref{Funktionalitäten}). Zu den häufigsten Quellen von -Nichtdeterminismus gehören das Einsetzen von Zeitstempeln innerhalb der -Erstellungsgebnisse, das Einsetzen von Zufallszahlen und von Auflistungen -eines Verzeichnisinhalts sortiert nach der Inode-Nummer. Siehe -@uref{https://reproducible-builds.org/docs/} für mehr Informationen. - -Um herauszufinden, was mit dieser Git-Binärdatei nicht stimmt, können wir so -etwas machen (siehe @ref{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 - -Dieser Befehl zeigt die Unterschiede zwischen den Dateien, die sich aus der -lokalen Erstellung ergeben, und den Dateien, die sich aus der Erstellung auf -@code{@value{SUBSTITUTE-SERVER}} ergeben (siehe @ref{Overview, Comparing and -Merging Files,, diffutils, Comparing and Merging Files}). Der Befehl -@command{diff} funktioniert großartig für Textdateien. Wenn sich -Binärdateien unterscheiden, ist @uref{https://diffoscope.org/, Diffoscope} -die bessere Wahl: Es ist ein hilfreiches Werkzeug, das Unterschiede in allen -Arten von Dateien visualisiert. - -Sobald Sie mit dieser Arbeit fertig sind, können Sie erkennen, ob die -Unterschiede aufgrund eines nichtdeterministischen Erstellungsprozesses oder -wegen einem bösartigen Server zustande kommen. Wir geben uns Mühe, Quellen -von Nichtdeterminismus in Paketen zu entfernen, damit Substitute leichter -verifiziert werden können, aber natürlich ist an diesem Prozess nicht nur -Guix, sondern ein großer Teil der Freie-Software-Gemeinschaft beteiligt. In -der Zwischenzeit ist @command{guix challenge} eines der Werkzeuge, die das -Problem anzugehen helfen. - -Wenn Sie ein Paket für Guix schreiben, ermutigen wir Sie, zu überprüfen, ob -@code{@value{SUBSTITUTE-SERVER}} und andere Substitutserver dasselbe -Erstellungsergebnis bekommen, das Sie bekommen haben. Das geht so: - -@example -$ guix challenge @var{Paket} -@end example - -@noindent -Dabei wird mit @var{Paket} eine Paketspezifikation wie @code{guile@@2.0} -oder @code{glibc:debug} bezeichnet. - -Die allgemeine Syntax lautet: - -@example -guix challenge @var{Optionen} [@var{Pakete}@dots{}] -@end example - -Wird ein Unterschied zwischen der Hash-Prüfsumme des lokal erstellten -Objekts und dem vom Server gelieferten Substitut festgestellt, oder zwischen -den Substituten von unterschiedlichen Servern, dann wird der Befehl dies wie -im obigen Beispiel anzeigen und mit dem Exit-Code 2 terminieren (andere -Exit-Codes außer null stehen für andere Arten von Fehlern). - -Die eine, wichtige Befehlszeilenoption ist: - -@table @code - -@item --substitute-urls=@var{URLs} -Die @var{URLs} als durch Leerraumzeichen getrennte Liste von -Substitut-Quell-URLs benutzen. mit denen verglichen wird. - -@item --verbose -@itemx -v -Details auch zu Übereinstimmungen (deren Inhalt identisch ist) ausgeben, -zusätzlich zu Informationen über Unterschiede. - -@end table - -@node Aufruf von guix copy -@section @command{guix copy} aufrufen - -@cindex Kopieren, von Store-Objekten, über SSH -@cindex SSH, Kopieren von Store-Objekten -@cindex Store-Objekte zwischen Maschinen teilen -@cindex Übertragen von Store-Objekten zwischen Maschinen -Der Befehl @command{guix copy} kopiert Objekte aus dem Store einer Maschine -in den Store einer anderen Maschine mittels einer Secure-Shell-Verbindung -(kurz SSH-Verbindung)@footnote{Dieser Befehl steht nur dann zur Verfügung, -wenn Guile-SSH gefunden werden kann. Siehe @ref{Voraussetzungen} für -Details.}. Zum Beispiel kopiert der folgende Befehl das Paket -@code{coreutils}, das Profil des Benutzers und all deren Abhängigkeiten auf -den anderen @var{Rechner}, dazu meldet sich Guix als @var{Benutzer} an: - -@example -guix copy --to=@var{Benutzer}@@@var{Rechner} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -Wenn manche der zu kopierenden Objekte schon auf dem anderen @var{Rechner} -vorliegen, werden sie tatsächlich @emph{nicht} übertragen. - -Der folgende Befehl bezieht @code{libreoffice} und @code{gimp} von dem -@var{Rechner}, vorausgesetzt sie sind dort verfügbar: - -@example -guix copy --from=@var{host} libreoffice gimp -@end example - -Die SSH-Verbindung wird mit dem Guile-SSH-Client hergestellt, der mit -OpenSSH kompatibel ist: Er berücksichtigt @file{~/.ssh/known_hosts} und -@file{~/.ssh/config} und verwendet den SSH-Agenten zur Authentifizierung. - -Der Schlüssel, mit dem gesendete Objekte signiert sind, muss von der -entfernten Maschine akzeptiert werden. Ebenso muss der Schlüssel, mit dem -die Objekte signiert sind, die Sie von der entfernten Maschine empfangen, in -Ihrer Datei @file{/etc/guix/acl} eingetragen sein, damit Ihr Daemon sie -akzeptiert. Siehe @ref{Aufruf von guix archive} für mehr Informationen über -die Authentifizierung von Store-Objekten. - -Die allgemeine Syntax lautet: - -@example -guix copy [--to=@var{Spezifikation}|--from=@var{Spezifikation}] @var{Objekte}@dots{} -@end example - -Sie müssen immer eine der folgenden Befehlszeilenoptionen angeben: - -@table @code -@item --to=@var{Spezifikation} -@itemx --from=@var{Spezifikation} -Gibt den Rechner (den »Host«) an, an den oder von dem gesendet -bzw. empfangen wird. Die @var{Spezifikation} muss eine SSH-Spezifikation -sein wie @code{example.org}, @code{charlie@@example.org} oder -@code{charlie@@example.org:2222}. -@end table - -Die @var{Objekte} können entweder Paketnamen wie @code{gimp} oder -Store-Objekte wie @file{/gnu/store/@dots{}-idutils-4.6} sein. - -Wenn ein zu sendendes Paket mit Namen angegeben wird, wird es erst erstellt, -falls es nicht im Store vorliegt, außer @option{--dry-run} wurde angegeben -wurde. Alle gemeinsamen Erstellungsoptionen werden unterstützt (siehe -@ref{Gemeinsame Erstellungsoptionen}). - - -@node Aufruf von guix container -@section @command{guix container} aufrufen -@cindex container -@cindex @command{guix container} -@quotation Anmerkung -Dieses Werkzeug ist noch experimentell, Stand Version @value{VERSION}. Die -Schnittstelle wird sich in Zukunft grundlegend verändern. -@end quotation - -Der Zweck von @command{guix container} ist, in einer isolierten Umgebung -(gemeinhin als »Container« bezeichnet) laufende Prozesse zu manipulieren, -die typischerweise durch die Befehle @command{guix environment} (siehe -@ref{Aufruf von guix environment}) und @command{guix system container} (siehe -@ref{Aufruf von guix system}) erzeugt werden. - -Die allgemeine Syntax lautet: - -@example -guix container @var{Aktion} @var{Optionen}@dots{} -@end example - -Mit @var{Aktion} wird die Operation angegeben, die in der isolierten -Umgebung durchgeführt werden soll, und mit @var{Optionen} werden die -kontextabhängigen Argumente an die Aktion angegeben. - -Folgende Aktionen sind verfügbar: - -@table @code -@item exec -Führt einen Befehl im Kontext der laufenden isolierten Umgebung aus. - -Die Syntax ist: - -@example -guix container exec @var{PID} @var{Programm} @var{Argumente}@dots{} -@end example - -@var{PID} gibt die Prozess-ID der laufenden isolierten Umgebung an. Als -@var{Programm} muss eine ausführbare Datei im Wurzeldateisystem der -isolierten Umgebung angegeben werden. Die @var{Argumente} sind die -zusätzlichen Befehlszeilenoptionen, die an das @var{Programm} übergeben -werden. - -Der folgende Befehl startet eine interaktive Anmelde-Shell innerhalb einer -isolierten Guix-Systemumgebung, gestartet durch @command{guix system -container}, dessen Prozess-ID 9001 ist: - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Beachten Sie, dass die @var{PID} nicht der Elternprozess der isolierten -Umgebung sein darf, sondern PID 1 in der isolierten Umgebung oder einer -seiner Kindprozesse sein muss. - -@end table - -@node Aufruf von guix weather -@section @command{guix weather} aufrufen - -Manchmal werden Sie schlecht gelaunt sein, weil es zu wenige Substitute gibt -und die Pakete bei Ihnen selbst erstellt werden müssen (siehe -@ref{Substitute}). Der Befehl @command{guix weather} zeigt einen Bericht -über die Verfügbarkeit von Substituten auf den angegebenen Servern an, damit -Sie sich eine Vorstellung davon machen können, wie es heute um Ihre Laune -bestellt sein wird. Manchmal bekommt man als Nutzer so hilfreiche -Informationen, aber in erster Linie nützt der Befehl den Leuten, die -@command{guix publish} benutzen (siehe @ref{Aufruf von guix publish}). - -@cindex Statistik, für Substitute -@cindex Verfügbarkeit von Substituten -@cindex Substitutverfügbarkeit -@cindex Wetter, Substitutverfügbarkeit -Hier ist ein Beispiel für einen Aufruf davon: - -@example -$ guix weather --substitute-urls=https://guix.example.org -5.872 Paketableitungen für x86_64-linux berechnen … -Nach 6.128 Store-Objekten von https://guix.example.org suchen … -updating list of substitutes from 'https://guix.example.org'... 100.0% -https://guix.example.org - 43,4% Substitute verfügbar (2.658 von 6.128) - 7.032,5 MiB an Nars (komprimiert) - 19.824,2 MiB auf der Platte (unkomprimiert) - 0,030 Sekunden pro Anfrage (182,9 Sekunden insgesamt) - 33,5 Anfragen pro Sekunde - - 9,8% (342 von 3.470) der fehlenden Objekte sind in der Warteschlange - Mindestens 867 Erstellungen in der Warteschlange - x86_64-linux: 518 (59,7%) - i686-linux: 221 (25,5%) - aarch64-linux: 128 (14,8%) - Erstellungsgeschwindigkeit: 23,41 Erstellungen pro Stunde - x86_64-linux: 11,16 Erstellungen pro Stunde - i686-linux: 6,03 Erstellungen pro Stunde - aarch64-linux: 6,41 Erstellungen pro Stunde -@end example - -@cindex Kontinuierliche Integration, Statistik -Wie Sie sehen können, wird der Anteil unter allen Paketen angezeigt, für die -auf dem Server Substitute verfügbar sind — unabhängig davon, ob Substitute -aktiviert sind, und unabhängig davon, ob der signierende Schlüssel des -Servers autorisiert ist. Es wird auch über die Größe der komprimierten -Archive (die »Nars«) berichtet, die vom Server angeboten werden, sowie über -die Größe, die die zugehörigen Store-Objekte im Store belegen würden (unter -der Annahme, dass Deduplizierung abgeschaltet ist) und über den Durchsatz -des Servers. Der zweite Teil sind Statistiken zur Kontinuierlichen -Integration (englisch »Continuous Integration«, kurz CI), wenn der Server -dies unterstützt. Des Weiteren kann @command{guix weather}, wenn es mit der -Befehlszeilenoption @option{--coverage} aufgerufen wird, »wichtige« -Paketsubstitute, die auf dem Server fehlen, auflisten (siehe unten). - -Dazu werden mit @command{guix weather} Anfragen über HTTP(S) zu Metadaten -(@dfn{Narinfos}) für alle relevanten Store-Objekte gestellt. Wie -@command{guix challenge} werden die Signaturen auf den Substituten -ignoriert, was harmlos ist, weil der Befehl nur Statistiken sammelt und -keine Substitute installieren kann. - -Neben anderen Dingen ist es möglich, bestimmte Systemtypen und bestimmte -Paketmengen anzufragen. Die verfügbaren Befehlszeilenoptionen sind folgende: - -@table @code -@item --substitute-urls=@var{URLs} -@var{URLs} ist eine leerzeichengetrennte Liste anzufragender -Substitutserver-URLs. Wird diese Befehlszeilenoption weggelassen, wird die -vorgegebene Menge an Substitutservern angefragt. - -@item --system=@var{System} -@itemx -s @var{System} -Substitute für das @var{System} anfragen — z.B.@: für -@code{aarch64-linux}. Diese Befehlszeilenoption kann mehrmals angegeben -werden, wodurch @command{guix weather} die Substitute für mehrere -Systemtypen anfragt. - -@item --manifest=@var{Datei} -Anstatt die Substitute für alle Pakete anzufragen, werden nur die in der -@var{Datei} angegebenen Pakete erfragt. Die @var{Datei} muss ein -@dfn{Manifest} enthalten, wie bei der Befehlszeilenoption @code{-m} von -@command{guix package} (siehe @ref{Aufruf von guix package}). - -@item --coverage[=@var{Anzahl}] -@itemx -c [@var{Anzahl}] -Einen Bericht über die Substitutabdeckung für Pakete ausgeben, d.h.@: Pakete -mit mindestens @var{Anzahl}-vielen Abhängigen (voreingestellt mindestens -null) anzeigen, für die keine Substitute verfügbar sind. Die abhängigen -Pakete werden selbst nicht aufgeführt: Wenn @var{b} von @var{a} abhängt und -Substitute für @var{a} fehlen, wird nur @var{a} aufgeführt, obwohl dann in -der Regel auch die Substitute für @var{b} fehlen. Das Ergebnis sieht so aus: - -@example -$ guix weather --substitute-urls=https://ci.guix.de.info -c 10 -8.983 Paketableitungen für x86_64-linux berechnen … -Nach 9.343 Store-Objekten von https://ci.guix.de.info suchen … -Liste der Substitute von »https://ci.guix.de.info« wird aktualisiert … 100.0% -https://ci.guix.de.info - 64.7% Substitute verfügbar (6.047 von 9.343) -@dots{} -2502 Pakete fehlen auf »https://ci.guix.de.info« für »x86_64-linux«, darunter sind: - 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 - -Der Befehl @command{guix processes} kann sich für Entwickler und -Systemadministratoren als nützlich erweisen, besonders auf Maschinen mit -mehreren Nutzern und auf Build-Farms. Damit werden die aktuellen Sitzungen -(also Verbindungen zum Daemon) sowie Informationen über die beteiligten -Prozesse aufgelistet@footnote{Entfernte Sitzungen, wenn -@command{guix-daemon} mit @option{--listen} unter Angabe eines TCP-Endpunkts -gestartet wurde, werden @emph{nicht} aufgelistet.}. Hier ist ein Beispiel -für die davon gelieferten Informationen: - -@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 diesem Beispiel sehen wir, dass @command{guix-daemon} drei Clients hat: -@command{guix environment}, @command{guix publish} und das Werkzeug Cuirass -zur Kontinuierlichen Integration. Deren Prozesskennung (PID) ist jeweils im -@code{ClientPID}-Feld zu sehen. Das Feld @code{SessionPID} zeigt die PID des -@command{guix-daemon}-Unterprozesses dieser bestimmten Sitzung. - -Das Feld @code{LockHeld} zeigt an, welche Store-Objekte derzeit durch die -Sitzung gesperrt sind, d.h.@: welche Store-Objekte zur Zeit erstellt oder -substituiert werden (das @code{LockHeld}-Feld wird nicht angezeigt, wenn -@command{guix processes} nicht als Administratornutzer root ausgeführt -wird). Letztlich sehen wir am @code{ChildProcess}-Feld oben, dass diese drei -Erstellungen hier ausgelagert (englisch »offloaded«) werden (siehe -@ref{Auslagern des Daemons einrichten}). - -Die Ausgabe ist im Recutils-Format, damit wir den praktischen -@command{recsel}-Befehl benutzen können, um uns interessierende Sitzungen -auszuwählen (siehe @ref{Selection Expressions,,, recutils, GNU recutils -manual}). Zum Beispiel zeigt dieser Befehl die Befehlszeile und PID des -Clients an, der die Erstellung des Perl-Pakets ausgelöst hat: - -@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 System«-Distribution 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 (siehe @ref{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. -* Tastaturbelegung:: Wie das System Tastendrücke interpretiert. -* 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. -* Guix in einer VM starten:: Wie man »Guix System« in einer virtuellen - Maschine startet. -* 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 (siehe @ref{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 (siehe @ref{»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 @ref{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 (siehe @ref{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 (siehe @ref{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 -Das Feld @code{services} listet @dfn{Systemdienste} auf, die zur Verfügung -stehen sollen, wenn das System startet (siehe @ref{Dienste}). Die -@code{operating-system}-Deklaration oben legt fest, dass wir neben den -grundlegenden Basis-Diensten auch wollen, dass der -OpenSSH-Secure-Shell-Daemon auf Port 2222 lauscht (siehe @ref{Netzwerkdienste, @code{openssh-service-type}}). Intern sorgt der -@code{openssh-service-type} dafür, dass @code{sshd} mit den richtigen -Befehlszeilenoptionen aufgerufen wird, je nach Systemkonfiguration werden -auch für dessen Betrieb nötige Konfigurationsdateien erstellt (siehe -@ref{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} -(siehe @ref{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 (siehe @ref{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 @ref{Desktop-Dienste} finden Sie eine genaue Liste der unter -@var{%desktop-services} angebotenen Dienste. Der Abschnitt @ref{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 -(siehe @ref{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 (siehe @ref{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 Starten 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 (siehe @ref{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 (siehe @ref{Die Store-Monade}): - -@deffn {Monadische Prozedur} operating-system-derivation os -Liefert eine Ableitung, mit der ein @code{operating-system}-Objekt @var{os} -erstellt wird (siehe @ref{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 - -Diese Prozedur wird vom Modul @code{(gnu system)} angeboten. Zusammen mit -@code{(gnu services)} (siehe @ref{Dienste}) deckt dieses Modul den Kern von -»Guix System« ab. Schauen Sie es sich mal an! - - -@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 (siehe @ref{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 (siehe @ref{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 @ref{Bootloader-Konfiguration}. - -@item @code{label} -This is the label (a string) as it appears in the bootloader's menu entry. -The default label includes the kernel name and version. - -@item @code{keyboard-layout} (Vorgabe: @code{#f}) -Dieses Feld gibt an, welche Tastaturbelegung auf der Konsole benutzt werden -soll. Es kann entweder auf @code{#f} gesetzt sein, damit die voreingestellte -Tastaturbelegung benutzt wird (in der Regel ist diese »US English«), oder -ein @code{}-Verbundsobjekt sein. - -Diese Tastaturbelegung wird benutzt, sobald der Kernel gebootet wurde. Diese -Tastaturbelegung wird zum Beispiel auch verwendet, wenn Sie eine Passphrase -eintippen, falls sich Ihr Wurzeldateisystem auf einem mit -@code{luks-device-mapping} zugeordneten Gerät befindet (siehe @ref{Zugeordnete Geräte}). - -@quotation Anmerkung -Damit wird @emph{nicht} angegeben, welche Tastaturbelegung der Bootloader -benutzt, und auch nicht, welche der grafische Display-Server -verwendet. Siehe @ref{Bootloader-Konfiguration} für Informationen darüber, -wie Sie die Tastaturbelegung des Bootloaders angeben können. Siehe @ref{X Window} für Informationen darüber, wie Sie die Tastaturbelegung angeben -können, die das X-Fenstersystem verwendet. -@end quotation - -@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. Siehe @ref{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 @ref{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 @ref{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 (siehe @ref{G-Ausdrücke, file-like objects}), das -für @file{/etc/hosts} benutzt werden soll (siehe @ref{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 @ref{Zugeordnete Geräte}. - -@item @code{file-systems} -Eine Liste von Dateisystemen. Siehe @ref{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 (siehe @ref{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 -@ref{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 @ref{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 (siehe @ref{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 (siehe -@ref{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 (siehe @ref{Locale -Names,,, libc, The GNU C Library Reference Manual}). Siehe @ref{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 @ref{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 -@ref{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{}-Objekt. Siehe @ref{Name Service Switch} für -Details. - -@item @code{services} (Vorgabe: @var{%base-services}) -Eine Liste von »service«-Objekten, die die Systemdienste -repräsentieren. Siehe @ref{Dienste}. - -@cindex essenzielle Dienste -@item @code{essential-services} (Vorgabe: …) -The list of ``essential services''---i.e., things like instances of -@code{system-service-type} and @code{host-name-service-type} (@pxref{Service-Referenz}), which are derived from the operating system definition itself. -As a user you should @emph{never} need to touch this field. - -@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 @ref{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 -(siehe @ref{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 - -@deffn {Scheme Syntax} this-operating-system -When used in the @emph{lexical scope} of an operating system field -definition, this identifier resolves to the operating system being defined. - -The example below shows how to refer to the operating system being defined -in the definition of the @code{label} field: - -@example -(use-modules (gnu) (guix)) - -(operating-system - ;; ... - (label (package-full-name - (operating-system-kernel this-operating-system)))) -@end example - -It is an error to refer to @code{this-operating-system} outside an operating -system definition. -@end deffn - -@end deftp - -@node Dateisysteme -@section Dateisysteme - -Die Liste der Dateisysteme, die eingebunden werden sollen, steht im -@code{file-systems}-Feld der Betriebssystemdeklaration (siehe @ref{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 (siehe @ref{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{}- oder -@code{}-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 (siehe @ref{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} -(siehe @ref{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 (siehe @ref{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 (siehe @ref{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 (siehe @ref{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 -@ref{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 (siehe @ref{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 (siehe @ref{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 grafischen Anmeldebildschirmen nicht aufgeführt. - -@anchor{user-account-password} -@cindex Passwort, für Benutzerkonten -@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. - -Wenn Sie aber @emph{doch} ein anfängliches Passwort für ein Konto -voreinstellen möchten, muss dieses Feld hier das verschlüsselte Passwort als -Zeichenkette enthalten. Sie können dazu die Prozedur @code{crypt} benutzen. - -@example -(user-account - (name "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 - -Siehe @ref{Passphrase Storage,,, libc, The GNU C Library Reference Manual} -für weitere Informationen über Passwortverschlüsselung und -@ref{Encryption,,, guile, GNU Guile Reference Manual} für Informationen über -die Prozedur @code{crypt} in Guile. - -@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 Tastaturbelegung -@section Tastaturbelegung - -@cindex Tastaturbelegung -@cindex Keymap -To specify what each key of your keyboard does, you need to tell the -operating system what @dfn{keyboard layout} you want to use. The default, -when nothing is specified, is the US English QWERTY layout for 105-key PC -keyboards. However, German speakers will usually prefer the German QWERTZ -layout, French speakers will want the AZERTY layout, and so on; hackers -might prefer Dvorak or bépo, and they might even want to further customize -the effect of some of the keys. This section explains how to get that done. - -@cindex Tastaturbelegung, Definition -There are three components that will want to know about your keyboard -layout: - -@itemize -@item -The @emph{bootloader} may want to know what keyboard layout you want to use -(@pxref{Bootloader-Konfiguration, @code{keyboard-layout}}). This is useful -if you want, for instance, to make sure that you can type the passphrase of -your encrypted root partition using the right layout. - -@item -The @emph{operating system kernel}, Linux, will need that so that the -console is properly configured (@pxref{»operating-system«-Referenz, -@code{keyboard-layout}}). - -@item -The @emph{graphical display server}, usually Xorg, also has its own idea of -the keyboard layout (@pxref{X Window, @code{keyboard-layout}}). -@end itemize - -Guix allows you to configure all three separately but, fortunately, it -allows you to share the same keyboard layout for all three components. - -@cindex XKB, Tastaturbelegungen -Keyboard layouts are represented by records created by the -@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following -the X Keyboard extension (XKB), each layout has four attributes: a name -(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), -an optional variant name, an optional keyboard model name, and a possibly -empty list of additional options. In most cases the layout name is all you -care about. Here are a few example: - -@example -;; The German QWERTZ layout. Here we assume a standard -;; "pc105" keyboard model. -(keyboard-layout "de") - -;; The bépo variant of the French layout. -(keyboard-layout "fr" "bepo") - -;; The Catalan layout. -(keyboard-layout "es" "cat") - -;; The Latin American Spanish layout. In addition, the -;; "Caps Lock" key is used as an additional "Ctrl" key, -;; and the "Menu" key is used as a "Compose" key to enter -;; accented letters. -(keyboard-layout "latam" - #:options '("ctrl:nocaps" "compose:menu")) - -;; The Russian layout for a ThinkPad keyboard. -(keyboard-layout "ru" #:model "thinkpad") - -;; The "US international" layout, which is the US layout plus -;; dead keys to enter accented characters. This is for an -;; Apple MacBook keyboard. -(keyboard-layout "us" "intl" #:model "macbook78") -@end example - -See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} -package for a complete list of supported layouts, variants, and models. - -@cindex Tastaturbelegung, Konfiguration -Let's say you want your system to use the Turkish keyboard layout throughout -your system---bootloader, console, and Xorg. Here's what your system -configuration would look like: - -@findex set-xorg-configuration -@lisp -;; Using the Turkish layout for the bootloader, the console, -;; and for Xorg. - -(operating-system - ;; ... - (keyboard-layout (keyboard-layout "tr")) ;for the console - (bootloader (bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi") - (keyboard-layout keyboard-layout))) ;for GRUB - (services (cons (set-xorg-configuration - (xorg-configuration ;for Xorg - (keyboard-layout keyboard-layout))) - %desktop-services))) -@end lisp - -In the example above, for GRUB and for Xorg, we just refer to the -@code{keyboard-layout} field defined above, but we could just as well refer -to a different layout. The @code{set-xorg-configuration} procedure -communicates the desired Xorg configuration to the graphical log-in manager, -by default GDM. - -We've discussed how to specify the @emph{default} keyboard layout of your -system when it starts, but you can also adjust it at run time: - -@itemize -@item -If you're using GNOME, its settings panel has a ``Region & Language'' entry -where you can select one or more keyboard layouts. - -@item -Under Xorg, the @command{setxkbmap} command (from the same-named package) -allows you to change the current layout. For example, this is how you would -change the layout to US Dvorak: - -@example -setxkbmap us dvorak -@end example - -@item -The @code{loadkeys} command changes the keyboard layout in effect in the -Linux console. However, note that @code{loadkeys} does @emph{not} use the -XKB keyboard layout categorization described above. The command below loads -the French bépo layout: - -@example -loadkeys fr-bepo -@end example -@end itemize - -@node Locales -@section Locales - -@cindex Locale -Eine @dfn{Locale} legt die kulturellen Konventionen einer bestimmten Sprache -und Region auf der Welt fest (siehe @ref{Locales,,, libc, The GNU C Library -Reference Manual}). Jede Locale hat einen Namen, der typischerweise von der -Form @code{@var{Sprache}_@var{Gebiet}.@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 (siehe @ref{»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} (siehe -@ref{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 @ref{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 -@code{@var{Sprache}_@var{Gebiet}} 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 (siehe @ref{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 (siehe -@ref{»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 -@c and . -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. - -Das »Problem« mit Guix ist, dass Nutzer viel Freiheit genießen: Sie können -wählen, ob und wann sie die Software in ihren Profilen aktualisieren und -benutzen vielleicht eine andere libc-Version als sie der Systemadministrator -benutzt hat, um die systemweiten Locale-Daten zu erstellen. - -Glücklicherweise können »unprivilegierte« Nutzer ohne zusätzliche -Berechtigungen dann zumindest ihre eigenen Locale-Daten installieren und -@var{GUIX_LOCPATH} entsprechend definieren (siehe @ref{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 (siehe @ref{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 hat eine weit gefasste Definition, was ein »Dienst« ist (siehe -@ref{Dienstkompositionen}), aber viele Dienste sind solche, die von -GNU@tie{}Shepherd verwaltet werden (siehe @ref{Shepherd-Dienste}). Auf -einem laufenden System kann der @command{herd}-Befehl benutzt werden, um -verfügbare Dienste aufzulisten, ihren Status anzuzeigen, sie zu starten und -zu stoppen oder andere angebotene Operationen durchzuführen (siehe @ref{Jump -Start,,, shepherd, The GNU Shepherd Manual}). Zum Beispiel: - -@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. -* LDAP-Dienste:: LDAP-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 @ref{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 -(siehe @ref{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{}-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{}-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{}-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 beiden Fällen wird agetty nichts an den anderen Einstellungen für -serielle Geräte verändern (Baud-Rate etc.), in der Hoffnung, dass Linux sie -auf die korrekten Werte festgelegt hat. - -@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{}-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{}-Objekt sein. Siehe @ref{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{} (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{}-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 (siehe @ref{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{}-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. - -Siehe @ref{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 (siehe @ref{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 @ref{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 -Ob die unter @code{authorized-keys} aufgelisteten Substitutschlüssel -autorisiert werden sollen — vorgegeben ist, den von -@code{@value{SUBSTITUTE-SERVER}} zu autorisieren (siehe @ref{Substitute}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (Vorgabe: @var{%default-authorized-guix-keys}) -Die Liste der Dateien mit autorisierten Schlüsseln, d.h.@: eine Liste von -Zeichenketten als G-Ausdrücke (siehe @ref{Aufruf von guix archive}). Der -vorgegebene Inhalt ist der Schlüssel von @code{@value{SUBSTITUTE-SERVER}} -(siehe @ref{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 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 @ref{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} (siehe @ref{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 (siehe -@ref{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 -@ref{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 @ref{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 @ref{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 @ref{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 Planen von Aufträgen -Das Modul @code{(gnu services mcron)} enthält eine Schnittstelle zu -GNU@tie{}mcron, einem Daemon, der gemäß einem vorher festgelegten Zeitplan -Aufträge (sogenannte »Jobs«) ausführt (siehe @ref{Top,,, mcron, -GNU@tie{}mcron}). GNU@tie{}mcron ist ähnlich zum traditionellen -@command{cron}-Daemon aus Unix; der größte Unterschied ist, dass mcron in -Guile Scheme implementiert ist, wodurch einem viel Flexibilität bei der -Spezifikation von Aufträgen und ihren Aktionen offen steht. - -Das folgende Beispiel definiert ein Betriebssystem, das täglich die Befehle -@command{updatedb} (siehe @ref{Invoking updatedb,,, find, Finding Files}) -und @command{guix gc} (siehe @ref{Aufruf von guix gc}) ausführt sowie den -Befehl @command{mkid} im Namen eines »unprivilegierten« Nutzers ohne -besondere Berechtigungen laufen lässt (siehe @ref{mkid invocation,,, -idutils, ID Database Utilities}). Zum Anlegen von Auftragsdefinitionen -benutzt es G-Ausdrücke, die dann an mcron übergeben werden (siehe -@ref{G-Ausdrücke}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define updatedb-job - ;; 'updatedb' jeden Tag um 3 Uhr morgens ausführen. Hier schreiben wir - ;; die vom Auftrag durchzuführende Aktion als eine Scheme-Prozedur. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define garbage-collector-job - ;; Jeden Tag 5 Minuten nach Mitternacht Müll sammeln gehen. - ;; Die Aktions des Auftrags ist ein Shell-Befehl. - #~(job "5 0 * * *" ;Vixie-cron-Syntax - "guix gc -F 1G")) - -(define idutils-job - ;; Die Index-Datenbank des Benutzers "charlie" um 12:15 Uhr und - ;; 19:15 Uhr aktualisieren. Dies wird aus seinem Persönlichen - ;; Ordner heraus ausgeführt. - #~(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 - -Siehe @ref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron} -für weitere Informationen zu mcron-Auftragsspezifikationen. Nun folgt die -Referenz des mcron-Dienstes. - -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{}. 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 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{} 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{} 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{} 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{} -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 {Datentyp} avahi-configuration -Dieser Datentyp repräsentiert die Konfiguration von Avahi. - -@table @asis - -@item @code{host-name} (Vorgabe: @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?} (Vorgabe: @code{#t}) -When true, allow host names and services to be published (broadcast) over -the network. - -@item @code{publish-workstation?} (Vorgabe: @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?} (Vorgabe: @code{#f}) -When true, DNS-SD over unicast DNS is enabled. - -@item @code{ipv4?} (Vorgabe: @code{#t}) -@itemx @code{ipv6?} (Vorgabe: @code{#t}) -These fields determine whether to use IPv4/IPv6 sockets. - -@item @code{domains-to-browse} (Vorgabe: @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 the GNOME Display Manager (GDM). - -@cindex GDM -@cindex GNOME, login manager -GDM of course allows users to log in into window managers and desktop -environments other than GNOME; for those using GNOME, GDM is required for -features such as automatic screen locking. - -@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} gdm-service-type -This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME -Desktop Manager} (GDM), a program that manages graphical display servers and -handles graphical user logins. Its value must be a @code{gdm-configuration} -(see below.) - -@cindex session types (X11) -@cindex X11 session types -GDM 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. Packages such as @code{gnome}, -@code{xfce}, and @code{i3} 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 {Datentyp} gdm-configuration -@table @asis -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (Vorgabe: @code{#f}) -When @code{auto-login?} is false, GDM presents a log-in screen. - -When @code{auto-login?} is true, GDM logs in directly as -@code{default-user}. - -@item @code{gnome-shell-assets} (Vorgabe: …) -List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. - -@item @code{xorg-configuration} (Vorgabe: @code{(xorg-configuration)}) -Xorg-Server für grafische Oberflächen konfigurieren. - -@item @code{xsession} (Vorgabe: @code{(xinitrc)}) -Script to run before starting a X session. - -@item @code{dbus-daemon} (Vorgabe: @code{dbus-daemon-wrapper}) -File name of the @code{dbus-daemon} executable. - -@item @code{gdm} (Vorgabe: @code{gdm}) -Das GDM-Paket, was benutzt werden soll. -@end table -@end deftp - -@defvr {Scheme Variable} slim-service-type -This is the type for the SLiM graphical login manager for X11. - -Like GDM, SLiM looks for session types described by @file{.desktop} files -and allows users to choose a session from the log-in screen using @kbd{F1}. -It also honors @file{~/.xsession} files. -@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{xorg-configuration} (Vorgabe: @code{(xorg-configuration)}) -Xorg-Server für grafische Oberflächen konfigurieren. - -@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-configuration} (Vorgabe: @code{(xorg-configuration)}) -Xorg-Server für grafische Oberflächen konfigurieren. - -@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{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{}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@cindex Xorg, Konfiguration -@deftp {Datentyp} xorg-configuration -This data type represents the configuration of the Xorg graphical display -server. Note that there is not Xorg service; instead, the X server is -started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the -configuration of these display managers aggregates an -@code{xorg-configuration} record. - -@table @asis -@item @code{modules} (Vorgabe: @code{%default-xorg-modules}) -This is a list of @dfn{module packages} loaded by the Xorg server---e.g., -@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. - -@item @code{fonts} (Vorgabe: @code{%default-xorg-fonts}) -This is a list of font directories to add to the server's @dfn{font path}. - -@item @code{drivers} (Vorgabe: @code{'()}) -This 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")}. - -@item @code{resolutions} (Vorgabe: @code{'()}) -When @code{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))}. - -@cindex Tastaturbelegung, für Xorg -@cindex keymap, for Xorg -@item @code{keyboard-layout} (Vorgabe: @code{#f}) -If this is @code{#f}, Xorg uses the default keyboard layout---usually US -English (``qwerty'') for a 105-key PC keyboard. - -Otherwise this must be a @code{keyboard-layout} object specifying the -keyboard layout in use when Xorg is running. @xref{Tastaturbelegung}, for -more information on how to specify the keyboard layout. - -@item @code{extra-config} (Vorgabe: @code{'()}) -This 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. - -@item @code{server} (Vorgabe: @code{xorg-server}) -This is the package providing the Xorg server. - -@item @code{server-arguments} (Vorgabe: @code{%default-xorg-server-arguments}) -This is the list of command-line arguments to pass to the X server. The -default is @code{-nolisten tcp}. -@end table -@end deftp - -@deffn {Scheme-Prozedur} set-xorg-configuration @var{Konfiguration} @ - [@var{login-manager-service-type}] Tell the log-in manager (of type -@var{login-manager-service-type}) to use @var{config}, an - record. - -Since the Xorg configuration is embedded in the log-in manager's -configuration---e.g., @code{gdm-configuration}---this procedure provides a -shorthand to set the Xorg configuration. -@end deffn - -@deffn {Scheme-Prozedur} xorg-start-command [@var{Konfiguration}] -Return a @code{startx} script in which the modules, fonts, etc. specified in -@var{config}, are available. The result should be used in place of -@code{startx}. - -Usually the X server is started by a login manager. -@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 -Das Modul @code{(gnu services cups)} stellt eine Guix-Dienstdefinition für -den CUPS-Druckdienst zur Verfügung. Wenn Sie Druckerunterstützung zu einem -Guix-System hinzufügen möchten, dann fügen Sie einen -@code{cups-service}-Dienst in die Betriebssystemdefinition ein. - -@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{gdm-service-type}}), 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-type}, -@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-type} -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 GDM as 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. - -@defvr {Scheme-Variable} gnome-desktop-service-type -Dies ist der Typ des Dienstes, der die @uref{https://www.gnome.org, -GNOME}-Arbeitsumgebung bereitstellt. Sein Wert ist ein -@code{gnome-desktop-configuration}-Objekt (siehe unten). - -This service adds the @code{gnome} package to the system profile, and -extends polkit with the actions from @code{gnome-settings-daemon}. -@end defvr - -@deftp {Datentyp} gnome-desktop-configuration -Configuration record for the GNOME desktop environment. - -@table @asis -@item @code{gnome} (Vorgabe: @code{gnome}) -Welches GNOME-Paket benutzt werden soll. -@end table -@end deftp - -@defvr {Scheme-Variable} xfce-desktop-service-type -Der Typ des Dienstes, um die @uref{Xfce, https://xfce.org/}-Arbeitsumgebung -auszuführen. Sein Wert ist ein @code{xfce-desktop-configuration}-Objekt -(siehe unten). - -This 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 defvr - -@deftp {Datentyp} xfce-desktop-configuration -Verbundstyp für Einstellungen zur Xfce-Arbeitsumgebung. - -@table @asis -@item @code{xfce} (Vorgabe: @code{xfce}) -Das Xfce-Paket, was benutzt werden soll. -@end table -@end deftp - -@deffn {Scheme-Variable} mate-desktop-service-type -Dies ist der Typ des Dienstes, um die @uref{https://mate-desktop.org/, -MATE-Arbeitsumgebung} auszuführen. Sein Wert ist ein -@code{mate-desktop-configuration}-Objekt (siehe unten). - -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 {Datentyp} mate-desktop-configuration -Verbundstyp für die Einstellungen der MATE-Arbeitsumgebung. - -@table @asis -@item @code{mate} (Vorgabe: @code{mate}) -Das MATE-Paket, was benutzt werden soll. -@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* (service gnome-desktop-service-type) - (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 {Datentyp} upower-configuration -Repräsentiert die Konfiguration von UPower. - -@table @asis - -@item @code{upower} (Vorgabe: @var{upower}) -Package to use for @code{upower}. - -@item @code{watts-up-pro?} (Vorgabe: @code{#f}) -Enable the Watts Up Pro device. - -@item @code{poll-batteries?} (Vorgabe: @code{#t}) -Enable polling the kernel for battery level changes. - -@item @code{ignore-lid?} (Vorgabe: @code{#f}) -Ignore the lid state, this can be useful if it's incorrect on a device. - -@item @code{use-percentage-for-policy?} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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} (Vorgabe: @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: -# . -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 wird benötigt, um »psql« auszuführen, aber postgis ist - ;; für den Betrieb nicht unbedingt notwendig. - (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{} 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. . 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 . 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. . -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. . 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. . 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}. -. 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 .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. . 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{" 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 -(' 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{} 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 -Das zabbix-server-Paket. - -@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 -Rechnername der Datenbank. - -Defaults to @samp{"127.0.0.1"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-name -Datenbankname. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-user -Benutzerkonto der Datenbank. - -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 -Datenbank-Portnummer. - -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 der PID-Datei. - -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 -Das zabbix-agent-Paket. - -@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 der PID-Datei. - -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 -Rechnername der Datenbank. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port -Datenbank-Portnummer. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name -Datenbankname. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user -Benutzerkonto der Datenbank. - -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 LDAP-Dienste -@subsection LDAP-Dienste -@cindex LDAP -@cindex nslcd, LDAP service - -The @code{(gnu services authentication)} module provides the -@code{nslcd-service-type}, which can be used to authenticate against an LDAP -server. In addition to configuring the service itself, you may want to add -@code{ldap} as a name service to the Name Service Switch. @xref{Name Service Switch} for detailed information. - -Here is a simple operating system declaration with a default configuration -of the @code{nslcd-service-type} and a Name Service Switch configuration -that consults the @code{ldap} name service last: - -@example -(use-service-modules authentication) -(use-modules (gnu system nss)) -... -(operating-system - ... - (services - (cons* - (service nslcd-service-type) - (service dhcp-client-service-type) - %base-services)) - (name-service-switch - (let ((services (list (name-service (name "db")) - (name-service (name "files")) - (name-service (name "ldap"))))) - (name-service-switch - (inherit %mdns-host-lookup-nss) - (password services) - (shadow services) - (group services) - (netgroup services) - (gshadow services))))) -@end example - -@c %start of generated documentation for nslcd-configuration - -Available @code{nslcd-configuration} fields are: - -@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd -Das @code{nss-pam-ldapd}-Paket, was benutzt werden soll. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads -The number of threads to start that can handle requests and perform LDAP -queries. Each thread opens a separate connection to the LDAP server. The -default is to start 5 threads. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string uid -This specifies the user id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string gid -This specifies the group id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} log-option log -This option controls the way logging is done via a list containing SCHEME -and LEVEL. The SCHEME argument may either be the symbols "none" or -"syslog", or an absolute file name. The LEVEL argument is optional and -specifies the log level. The log level may be one of the following symbols: -"crit", "error", "warning", "notice", "info" or "debug". All messages with -the specified log level or higher are logged. - -Defaults to @samp{("/var/log/nslcd" info)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list uri -The list of LDAP server URIs. Normally, only the first server will be used -with the following servers as fall-back. - -Defaults to @samp{("ldap://localhost:389/")}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version -The version of the LDAP protocol to use. The default is to use the maximum -version supported by the LDAP library. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn -Specifies the distinguished name with which to bind to the directory server -for lookups. The default is to bind anonymously. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw -Specifies the credentials with which to bind. This option is only -applicable when used with binddn. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn -Specifies the distinguished name to use when the root user tries to modify a -user's password using the PAM module. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw -Specifies the credentials with which to bind if the root user tries to -change a user's password. This option is only applicable when used with -rootpwmoddn - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech -Specifies the SASL mechanism to be used when performing SASL authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm -Specifies the SASL realm to be used when performing SASL authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid -Specifies the authentication identity to be used when performing SASL -authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid -Specifies the authorization identity to be used when performing SASL -authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? -Determines whether the LDAP server host name should be canonicalised. If -this is enabled the LDAP library will do a reverse host name lookup. By -default, it is left up to the LDAP library whether this check is performed -or not. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname -Set the name for the GSS-API Kerberos credentials cache. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string base -Basis für die Verzeichnissuche. - -Vorgegeben ist @samp{"dc=example,dc=com"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} scope-option scope -Specifies the search scope (subtree, onelevel, base or children). The -default scope is subtree; base scope is almost never useful for name service -lookups; children scope is not supported on all servers. - -Defaults to @samp{(subtree)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref -Specifies the policy for dereferencing aliases. The default policy is to -never dereference aliases. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals -Specifies whether automatic referral chasing should be enabled. The default -behaviour is to chase referrals. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps -This option allows for custom attributes to be looked up instead of the -default RFC 2307 attributes. It is a list of maps, each consisting of the -name of a map, the RFC 2307 attribute to match and the query expression for -the attribute as it is available in the directory. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters -A list of filters consisting of the name of a map to which the filter -applies and an LDAP search filter expression. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit -Specifies the time limit in seconds to use when connecting to the directory -server. The default value is 10 seconds. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit -Specifies the time limit (in seconds) to wait for a response from the LDAP -server. A value of zero, which is the default, is to wait indefinitely for -searches to be completed. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit -Specifies the period if inactivity (in seconds) after which the con‐ nection -to the LDAP server will be closed. The default is not to time out -connections. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime -Specifies the number of seconds to sleep when connecting to all LDAP servers -fails. By default one second is waited between the first failure and the -first retry. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime -Specifies the time after which the LDAP server is considered to be -permanently unavailable. Once this time is reached retries will be done -only once per this time period. The default value is 10 seconds. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl -Specifies whether to use SSL/TLS or not (the default is not to). If -'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert -Specifies what checks to perform on a server-supplied certificate. The -meaning of the values is described in the ldap.conf(5) manual page. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir -Specifies the directory containing X.509 certificates for peer authen‐ -tication. This parameter is ignored when using GnuTLS. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile -Specifies the path to the X.509 certificate for peer authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile -Specifies the path to an entropy source. This parameter is ignored when -using GnuTLS. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers -Specifies the ciphers to use for TLS as a string. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert -Specifies the path to the file containing the local certificate for client -TLS authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key -Specifies the path to the file containing the private key for client TLS -authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize -Set this to a number greater than 0 to request paged results from the LDAP -server in accordance with RFC2696. The default (0) is to not request paged -results. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers -This option prevents group membership lookups through LDAP for the specified -users. Alternatively, the value 'all-local may be used. With that value -nslcd builds a full list of non-LDAP users on startup. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid -This option ensures that LDAP users with a numeric user id lower than the -specified value are ignored. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset -This option specifies an offset that is added to all LDAP numeric user ids. -This can be used to avoid user id collisions with local users. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset -This option specifies an offset that is added to all LDAP numeric group -ids. This can be used to avoid user id collisions with local groups. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups -If this option is set, the member attribute of a group may point to another -group. Members of nested groups are also returned in the higher level group -and parent groups are returned when finding groups for a specific user. The -default is not to perform extra searches for nested groups. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers -If this option is set, the group member list is not retrieved when looking -up groups. Lookups for finding which groups a user belongs to will remain -functional so the user will likely still get the correct groups assigned on -login. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration -If this option is set, functions which cause all user/group entries to be -loaded from the directory will not succeed in doing so. This can -dramatically reduce LDAP server load in situations where there are a great -number of users and/or groups. This option is not recommended for most -configurations. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames -This option can be used to specify how user and group names are verified -within the system. This pattern is used to check all user and group names -that are requested and returned from LDAP. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase -This specifies whether or not to perform searches using case-insensitive -matching. Enabling this could open up the system to authorization bypass -vulnerabilities and introduce nscd cache poisoning vulnerabilities which -allow denial of service. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy -This option specifies whether password policy controls are requested and -handled from the LDAP server when performing user authentication. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search -By default nslcd performs an LDAP search with the user's credentials after -BIND (authentication) to ensure that the BIND operation was successful. The -default search is a simple check to see if the user's DN exists. A search -filter can be specified that will be used instead. It should return at -least one entry. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search -This option allows flexible fine tuning of the authorisation check that -should be performed. The search filter specified is executed and if any -entries match, access is granted, otherwise access is denied. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message -If this option is set password modification using pam_ldap will be denied -and the specified message will be presented to the user instead. The -message can be used to direct the user to an alternative means of changing -their password. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list pam-services -List of pam service names for which LDAP authentication should suffice. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of generated documentation for nslcd-configuration - - -@node Web-Dienste -@subsection Web-Dienste - -@cindex Web -@cindex WWW -@cindex HTTP -Das Modul @code{(gnu services web)} stellt den Apache-HTTP-Server, den -nginx-Webserver und auch einen fastcgi-Wrapperdienst bereit. - -@subsubheading Apache-HTTP-Server - -@deffn {Scheme-Variable} httpd-service-type -Diensttyp für den @uref{https://httpd.apache.org/,Apache-HTTP-Server} -(@dfn{httpd}). Der Wert dieses Diensttyps ist ein -@code{httpd-configuration}-Verbund. - -Es folgt ein einfaches Beispiel der Konfiguration. - -@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 - -Andere Dienste können den @code{httpd-service-type} auch erweitern, um etwas -zur Konfiguration hinzuzufügen. - -@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 - -Nun folgt eine Beschreibung der Verbundstypen @code{httpd-configuration}, -@code{httpd-module}, @code{httpd-config-file} und @code{httpd-virtualhost}. - -@deffn {Datentyp} httpd-configuration -Dieser Datentyp repräsentiert die Konfiguration des httpd-Dienstes. - -@table @asis -@item @code{package} (Vorgabe: @code{httpd}) -Das zu benutzende httpd-Paket. - -@item @code{pid-file} (Vorgabe: @code{"/var/run/httpd"}) -Die vom Shepherd-Dienst benutzte PID-Datei. - -@item @code{config} (Vorgabe: @code{(httpd-config-file)}) -Die vom httpd-Dienst zu benutzende Konfigurationsdatei. Vorgegeben ist ein -@code{httpd-config-file}-Verbundsobjekt, aber als Wert kann auch ein anderer -G-Ausdruck benutzt werden, der eine Datei erzeugt, zum Beispiel ein -@code{plain-file}. Es kann auch eine Datei außerhalb des Stores mit einer -Zeichenkette angegeben werden. - -@end table -@end deffn - -@deffn {Datentyp} httpd-module -Dieser Datentyp steht für ein Modul des httpd-Dienstes. - -@table @asis -@item @code{name} -Der Name des Moduls. - -@item @code{file} -Die Datei, in der das Modul steht. Sie kann relativ zum benutzten -httpd-Paket oder als absoluter Pfad einer Datei oder als ein G-Ausdruck für -eine Datei im Store angegeben werden, zum Beispiel @code{(file-append -mod-wsgi "/modules/mod_wsgi.so")}. - -@end table -@end deffn - -@defvr {Scheme-Variable} %default-httpd-modules -Eine vorgegebene Liste von @code{httpd-module}-Objekten. -@end defvr - -@deffn {Datentyp} httpd-config-file -Dieser Datentyp repräsentiert eine Konfigurationsdatei für den httpd-Dienst. - -@table @asis -@item @code{modules} (Vorgabe: @code{%default-httpd-modules}) -Welche Module geladen werden sollen. Zusätzliche Module können hier -eingetragen werden oder durch eine zusätzliche Konfigurationsangabe geladen -werden. - -Um zum Beispiel Anfragen nach PHP-Dateien zu behandeln, können Sie das Modul -@code{mod_proxy_fcgi} von Apache zusammen mit @code{php-fpm-service-type} -benutzen: - -@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 "\ - - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (Vorgabe: @code{httpd}) -Die @code{ServerRoot} in der Konfigurationsdatei, vorgegeben ist das -httpd-Paket. Direktiven wie @code{Include} und @code{LoadModule} werden -relativ zur ServerRoot interpretiert. - -@item @code{server-name} (Vorgabe: @code{#f}) -Der @code{ServerName} in der Konfigurationsdatei, mit dem das Anfrageschema -(Request Scheme), der Rechnername (Hostname) und Port angegeben wird, mit -denen sich der Server identifiziert. - -Es muss nicht als Teil der Server-Konfiguration festgelegt werden, sondern -kann auch in virtuellen Rechnern (Virtual Hosts) festgelegt -werden. Vorgegeben ist @code{#f}, wodurch kein @code{ServerName} festgelegt -wird. - -@item @code{document-root} (Vorgabe: @code{"/srv/http"}) -Das @code{DocumentRoot}-Verzeichnis, in dem sich die Dateien befinden, die -man vom Server abrufen kann. - -@item @code{listen} (Vorgabe: @code{'("80")}) -Die Liste der Werte für die @code{Listen}-Direktive in der -Konfigurationsdatei. Als Wert sollte eine Liste von Zeichenketten angegeben -werden, die jeweils die Portnummer, auf der gelauscht wird, und optional -auch die zu benutzende IP-Adresse und das Protokoll angeben. - -@item @code{pid-file} (Vorgabe: @code{"/var/run/httpd"}) -Hiermit wird die PID-Datei als @code{PidFile}-Direktive angegeben. Der Wert -sollte mit der @code{pid-file}-Datei in der @code{httpd-configuration} -übereinstimmen, damit der Shepherd-Dienst richtig konfiguriert ist. - -@item @code{error-log} (Vorgabe: @code{"/var/log/httpd/error_log"}) -Der Ort, an den der Server mit der @code{ErrorLog}-Direktive -Fehlerprotokolle schreibt. - -@item @code{user} (Vorgabe: @code{"httpd"}) -Der Benutzer, als der der Server durch die @code{User}-Direktive Anfragen -beantwortet. - -@item @code{group} (Vorgabe: @code{"httpd"}) -Die Gruppe, mit der der Server durch die @code{Group}-Direktive Anfragen -beantwortet. - -@item @code{extra-config} (Vorgabe: @code{(list "TypesConfig etc/httpd/mime.types")}) -Eine flache Liste von Zeichenketten und G-Ausdrücken, die am Ende der -Konfigurationsdatei hinzugefügt werden. - -Alle Werte, mit denen dieser Dienst erweitert wird, werden an die Liste -angehängt. - -@end table -@end deffn - -@deffn {Datentyp} httpd-virtualhost -Dieser Datentyp repräsentiert einen Konfigurationsblock für einen virtuellen -Rechner (Virtual Host) des httpd-Dienstes. - -Sie sollten zur zusätzlichen Konfiguration extra-config des httpd-Dienstes -hinzugefügt werden. - -@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} -Adressen und Ports für die @code{VirtualHost}-Direktive. - -@item @code{contents} -Der Inhalt der @code{VirtualHost}-Direktive. Er sollte als Liste von -Zeichenketten und G-Ausdrücken angegeben werden. - -@end table -@end deffn - -@subsubheading NGINX - -@deffn {Scheme-Variable} nginx-service-type -Diensttyp für den @uref{https://nginx.org/,NGinx}-Webserver. Der Wert des -Dienstes ist ein @code{}-Verbundsobjekt. - -Es folgt ein einfaches Beispiel der Konfiguration. - -@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 - -Außer durch direktes Hinzufügen von Server-Blöcken zur Dienstkonfiguration -kann der Dienst auch durch andere Dienste erweitert werden, um Server-Blöcke -hinzuzufügen, wie man im folgenden Beispiel sieht: - -@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 - -Beim Starten hat @command{nginx} seine Konfigurationsdatei noch nicht -gelesen und benutzt eine vorgegebene Datei, um Fehlermeldungen zu -protokollieren. Wenn er seine Konfigurationsdatei nicht laden kann, landen -Fehlermeldungen also dort. Nachdem die Konfigurationsdatei geladen ist, -werden Fehlerprotokolle nach Voreinstellung in die Datei geschrieben, die in -der Konfiguration angegeben ist. In unserem Fall können Sie Fehlermeldungen -beim Starten in @file{/var/run/nginx/logs/error.log} finden und nachdem die -Konfiguration eingelesen wurde, finden Sie sie in -@file{/var/log/nginx/error.log}. Letzterer Ort kann mit der -Konfigurationsoption @var{log-directory} geändert werden. - -@deffn {Datentyp} nginx-configuration -Dieser Datentyp repräsentiert die Konfiguration von NGinx. Ein Teil der -Konfiguration kann hierüber und über die anderen zu Ihrer Verfügung -stehenden Verbundstypen geschehen, alternativ können Sie eine -Konfigurationsdatei mitgeben. - -@table @asis -@item @code{nginx} (Vorgabe: @code{nginx}) -Das zu benutzende nginx-Paket. - -@item @code{log-directory} (Vorgabe: @code{"/var/log/nginx"}) -In welches Verzeichnis NGinx Protokolldateien schreiben wird. - -@item @code{run-directory} (Vorgabe: @code{"/var/run/nginx"}) -In welchem Verzeichnis NGinx eine PID-Datei anlegen und temporäre Dateien -ablegen wird. - -@item @code{server-blocks} (Vorgabe: @code{'()}) -Eine Liste von @dfn{Server-Blöcken}, die in der erzeugten -Konfigurationsdatei stehen sollen. Die Elemente davon sollten den Typ -@code{} haben. - -Im folgenden Beispiel wäre NGinx so eingerichtet, dass Anfragen an -@code{www.example.com} mit Dateien aus dem Verzeichnis -@code{/srv/http/www.example.com} beantwortet werden, ohne HTTPS zu benutzen. -@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} (Vorgabe: @code{'()}) -Eine Liste von @dfn{Upstream-Blöcken}, die in der erzeugten -Konfigurationsdatei stehen sollen. Ihre Elemente sollten den Typ -@code{} haben. - -Upstreams als @code{upstream-blocks} zu konfigurieren, kann hilfreich sein, -wenn es mit @code{locations} in @code{} -verbunden wird. Das folgende Beispiel erzeugt eine Server-Konfiguration mit -einer Location-Konfiguration, bei der Anfragen als Proxy entsprechend einer -Upstream-Konfiguration weitergeleitet werden, wodurch zwei Server diese -beantworten können. - -@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}) -Wenn eine Konfigurationsdatei als @var{file} angegeben wird, dann wird diese -benutzt und @emph{keine} Konfigurationsdatei anhand der angegebenen -@code{log-directory}, @code{run-directory}, @code{server-blocks} und -@code{upstream-blocks} erzeugt. Trotzdem sollten diese Argumente bei einer -richtigen Konfiguration mit denen in der Datei @var{file} übereinstimmen, -damit die Verzeichnisse bei Aktivierung des Dienstes erzeugt werden. - -Das kann nützlich sein, wenn Sie schon eine bestehende Konfigurationsdatei -haben oder das, was Sie brauchen, nicht mit anderen Teilen eines -nginx-configuration-Verbundsobjekts umgesetzt werden kann. - -@item @code{server-names-hash-bucket-size} (Vorgabe: @code{#f}) -Größe der Behälter (englisch »Buckets«) für die Hashtabelle der Servernamen; -vorgegeben ist @code{#f}, wodurch die Größe der Cache-Lines des Prozessors -verwendet wird. - -@item @code{server-names-hash-bucket-max-size} (Vorgabe: @code{#f}) -Maximale Behältergröße für die Hashtabelle der Servernamen. - -@item @code{extra-content} (Vorgabe: @code{""}) -Zusätzlicher Inhalt des @code{http}-Blocks. Er sollte eine Zeichenkette oder -ein zeichenkettenwertiger G-Ausdruck. - -@end table -@end deffn - -@deftp {Datentyp} nginx-server-configuration -Der Datentyp, der die Konfiguration eines nginx-Serverblocks -repräsentiert. Dieser Typ hat die folgenden Parameter: - -@table @asis -@item @code{listen} (Vorgabe: @code{'("80" "443 ssl")}) -Jede @code{listen}-Direktive legt Adresse und Port für eine IP fest oder -gibt einen Unix-Socket an, auf dem der Server Anfragen beantwortet. Es -können entweder sowohl Adresse als auch Port oder nur die Adresse oder nur -der Port angegeben werden. Als Adresse kann auch ein Rechnername -(»Hostname«) angegeben werden, zum Beispiel: - -@example -'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") -@end example - -@item @code{server-name} (Vorgabe: @code{(list 'default)}) -Eine Liste von Servernamen, die dieser Server repräsentiert. @code{'default} -repräsentiert den voreingestellten Server, der für Verbindungen verwendet -wird, die zu keinem anderen Server passen. - -@item @code{root} (Vorgabe: @code{"/srv/http"}) -Wurzelverzeichnis der Webpräsenz, die über nginx abgerufen werden kann. - -@item @code{locations} (Vorgabe: @code{'()}) -Eine Liste von @dfn{nginx-location-configuration}- oder -@dfn{nginx-named-location-configuration}-Verbundsobjekten, die innerhalb des -Serverblocks benutzt werden. - -@item @code{index} (Vorgabe: @code{(list "index.html")}) -Index-Dateien, mit denen Anfragen nach einem Verzeichnis beantwortet -werden. Wenn @emph{keine} davon gefunden wird, antwortet Nginx mit der Liste -der Dateien im Verzeichnis. - -@item @code{try-files} (Vorgabe: @code{'()}) -Eine Liste der Dateien, bei denen in der angegebenen Reihenfolge geprüft -wird, ob sie existieren. @code{nginx} beantwortet die Anfrage mit der ersten -Datei, die es findet. - -@item @code{ssl-certificate} (Vorgabe: @code{#f}) -Wo das Zertifikat für sichere Verbindungen gespeichert ist. Sie sollten es -auf @code{#f} setzen, wenn Sie kein Zertifikat haben oder kein HTTPS -benutzen möchten. - -@item @code{ssl-certificate-key} (Vorgabe: @code{#f}) -Wo der private Schlüssel für sichere Verbindungen gespeichert ist. Sie -sollten ihn auf @code{#f} setzen, wenn Sie keinen Schlüssel haben oder kein -HTTPS benutzen möchten. - -@item @code{server-tokens?} (Vorgabe: @code{#f}) -Ob der Server Informationen über seine Konfiguration bei Antworten beilegen -soll. - -@item @code{raw-content} (Vorgabe: @code{'()}) -Eine Liste von Zeilen, die unverändert in den Serverblock eingefügt werden. - -@end table -@end deftp - -@deftp {Datentyp} nginx-upstream-configuration -Der Datentyp, der die Konfiguration eines nginx-@code{upstream}-Blocks -repräsentiert. Dieser Typ hat folgende Parameter: - -@table @asis -@item @code{name} -Der Name dieser Servergruppe. - -@item @code{servers} -Gibt die Adressen der Server in der Gruppe an. Die Adresse kann als -IP-Adresse (z.B.@: @samp{127.0.0.1}), Domänenname (z.B.@: -@samp{backend1.example.com}) oder als Pfad eines Unix-Sockets mit dem -vorangestellten Präfix @samp{unix:} angegeben werden. Wenn Adressen eine -IP-Adresse oder einen Domänennamen benutzen, ist der voreingestellte Port -80, aber ein abweichender Port kann auch explizit angegeben werden. - -@end table -@end deftp - -@deftp {Datentyp} nginx-location-configuration -Der Datentyp, der die Konfiguration eines nginx-@code{location}-Blocks -angibt. Der Typ hat die folgenden Parameter: - -@table @asis -@item @code{uri} -Die URI, die auf diesen Block passt. - -@anchor{nginx-location-configuration body} -@item @code{body} -Der Rumpf des location-Blocks, der als eine Liste von Zeichenketten -angegeben werden muss. Er kann viele Konfigurationsdirektiven enthalten, zum -Beispiel können Anfragen an eine Upstream-Servergruppe weitergeleitet -werden, die mit einem @code{nginx-upstream-configuration}-Block angegeben -wurde, indem diese Direktive im Rumpf angegeben wird: @samp{(list -"proxy_pass http://upstream-name;")}. - -@end table -@end deftp - -@deftp {Datentyp} nginx-named-location-configuration -Der Datentyp repräsentiert die Konfiguration eines mit Namen versehenen -nginx-location-Blocks (»Named Location Block«). Ein mit Namen versehener -location-Block wird zur Umleitung von Anfragen benutzt und nicht für die -normale Anfrageverarbeitung. Dieser Typ hat die folgenden Parameter: - -@table @asis -@item @code{name} -Der Name, mit dem dieser location-Block identifiziert wird. - -@item @code{body} -Siehe @ref{nginx-location-configuration body}, weil der Rumpf (»Body«) eines -mit Namen versehenen location-Blocks wie ein -@code{nginx-location-configuration body} benutzt werden kann. Eine -Einschränkung ist, dass der Rumpf eines mit Namen versehenen location-Blocks -keine location-Blöcke enthalten kann. - -@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 -Der Datentyp, der die Konfiguration des @code{fcgiwrap}-Dienstes -repräsentiert. Dieser Typ hat die folgenden Parameter: -@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{} -@item @code{} -@item @code{} -@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} (Vorgabe: @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-Prozedur} 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{@@}. - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac? -Enable CPU turbo boost feature on AC mode. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat? -Same as @code{cpu-boost-on-ac?} on BAT mode. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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"}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? -Enable USB autosuspend before shutdown. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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{db-file} (Vorgabe: @code{"~/.mpd/tag_cache"}) -Der Ort, an dem die Musikdatenbank gespeichert wird. - -@item @code{state-file} (Vorgabe: @code{"~/.mpd/state"}) -The location of the file that stores current MPD's state. - -@item @code{sticker-file} (Vorgabe: @code{"~/.mpd/sticker.sql"}) -Der Ort, an dem die Sticker-Datenbank gespeichert wird. - -@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 "}. - -@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" "mips64el")))) -@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{} 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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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?}. - -Der Vorgabewert ist @samp{disabled} (d.h.@: deaktiviert). - -@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 authentication)} 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 - -@cindex inputattach -@subsubheading inputattach-Dienst - -@cindex tablet input, for Xorg -@cindex touchscreen input, for Xorg -The @uref{https://linuxwacom.github.io/, inputattach} service allows you to -use input devices such as Wacom tablets, touchscreens, or joysticks with the -Xorg display server. - -@deffn {Scheme-Variable} inputattach-service-type -Type of a service that runs @command{inputattach} on a device and dispatches -events from it. -@end deffn - -@deftp {Datentyp} inputattach-configuration -@table @asis -@item @code{device-type} (Vorgabe: @code{"wacom"}) -The type of device to connect to. Run @command{inputattach --help}, from -the @code{inputattach} package, to see the list of supported device types. - -@item @code{device} (Vorgabe: @code{"/dev/ttyS0"}) -The device file to connect to the device. - -@item @code{log-file} (Vorgabe: @code{#f}) -If true, this must be the name of a file to log messages to. -@end table -@end deftp - -@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{} 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{} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{} 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{} 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{} 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-Dienst - -Das Modul @code{(gnu services docker)} stellt den folgenden Dienst zur -Verfügung. - -@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 {Datentyp} docker-configuration -Dies ist der Datentyp, der die Konfiguration von Docker und Containerd -repräsentiert. - -@table @asis - -@item @code{package} (Vorgabe: @code{docker}) -Das Docker-Paket, was benutzt werden soll. - -@item @code{containerd} (Vorgabe: @var{containerd}) -Das Containerd-Paket, was benutzt werden soll. - -@end table -@end deftp - -@node Setuid-Programme -@section Setuid-Programme - -@cindex setuid-Programme -Manche Programme müssen mit Administratorrechten (also den Berechtigungen -des »root«-Benutzers) ausgeführt werden, selbst wenn Nutzer ohne besondere -Berechtigungen sie starten. Ein bekanntes Beispiel ist das Programm -@command{passwd}, womit Nutzer ihr Passwort ändern können, wozu das Programm -auf die Dateien @file{/etc/passwd} und @file{/etc/shadow} zugreifen muss — -was normalerweise nur der »root«-Nutzer darf, aus offensichtlichen Gründen -der Informationssicherheit. Deswegen sind diese ausführbaren Programmdateien -@dfn{setuid-root}, d.h.@: sie laufen immer mit den Administratorrechten des -root-Nutzers, egal wer sie startet (siehe @ref{How Change Persona,,, libc, -The GNU C Library Reference Manual} für mehr Informationen über den -setuid-Mechanismus). - -Der Store selbst kann @emph{keine} setuid-Programme enthalten: Das wäre eine -Sicherheitslücke, weil dann jeder Nutzer auf dem System Ableitungen -schreiben könnte, die in den Store solche Dateien einfügen würden (siehe -@ref{Der Store}). Wir benutzen also einen anderen Mechanismus: Statt auf den -ausführbaren Dateien im Store selbst deren setuid-Bit zu setzen, lassen wir -den Systemadministrator @emph{deklarieren}, welche Programme mit setuid-root -gestartet werden. - -Das Feld @code{setuid-programs} einer @code{operating-system}-Deklaration -enthält eine Liste von G-Ausdrücken, die die Namen der Programme angeben, -die setuid-root sein sollen (siehe @ref{Das Konfigurationssystem nutzen}). Zum Beispiel kann das Programm @command{passwd}, was Teil des -Shadow-Pakets ist, durch diesen G-Ausdruck bezeichnet werden (siehe -@ref{G-Ausdrücke}): - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -Eine vorgegebene Menge von setuid-Programmen wird durch die Variable -@code{%setuid-programs} aus dem Modul @code{(gnu system)} definiert. - -@defvr {Scheme-Variable} %setuid-programs -Eine Liste von G-Ausdrücken, die übliche Programme angeben, die setuid-root -sein müssen. - -Die Liste enthält Befehle wie @command{passwd}, @command{ping}, @command{su} -und @command{sudo}. -@end defvr - -Intern erzeugt Guix die eigentlichen setuid-Programme im Verzeichnis -@file{/run/setuid-programs}, wenn das System aktiviert wird. Die Dateien in -diesem Verzeichnis verweisen auf die »echten« Binärdateien im 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 müssen Sie dazu ein Paket, das Zertifikate enthält, in das -@code{packages}-Feld der @code{operating-system}-Deklaration des -Betriebssystems hinzufügen (siehe @ref{»operating-system«-Referenz}). Guix -liefert ein solches Paket mit, @code{nss-certs}, was als Teil von Mozillas -»Network Security Services« angeboten wird. - -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 -Das Modul @code{(gnu system nss)} enthält Anbindungen für die Konfiguration -des @dfn{Name Service Switch} (NSS) der libc (siehe @ref{NSS Configuration -File,,, libc, The GNU C Library Reference Manual}). Kurz gesagt ist der NSS -ein Mechanismus, mit dem die libc um neue »Namens«-Auflösungsmethoden für -Systemdatenbanken erweitert werden kann; dazu gehören Rechnernamen (auch -bekannt als »Host«-Namen), Dienstnamen, Benutzerkonten und mehr (siehe -@ref{Name Service Switch, System Databases and Name Service Switch,, libc, -The GNU C Library Reference Manual}). - -Die NSS-Konfiguration legt für jede Systemdatenbank fest, mit welcher -Methode der Name nachgeschlagen (»aufgelöst«) werden kann und welche -Methoden zusammenhängen — z.B.@: unter welchen Umständen der NSS es mit der -nächsten Methode auf seiner Liste versuchen sollte. Die NSS-Konfiguration -wird im Feld @code{name-service-switch} von -@code{operating-system}-Deklarationen angegeben (siehe @ref{»operating-system«-Referenz, @code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, Rechnernamensauflösung -Zum Beispiel konfigurieren die folgenden Deklarationen den NSS so, dass er -das @uref{http://0pointer.de/lennart/projects/nss-mdns/, -@code{nss-mdns}-Backend} benutzt, wodurch er auf @code{.local} endende -Rechnernamen über Multicast-DNS (mDNS) auflöst: - -@example -(name-service-switch - (hosts (list %files ;zuerst in /etc/hosts nachschlagen - - ;; Wenn das keinen Erfolg hatte, es - ;; mit 'mdns_minimal' versuchen. - (name-service - (name "mdns_minimal") - - ;; 'mdns_minimal' ist die Autorität für - ;; '.local'. Gibt es not-found ("nicht - ;; gefunden") zurück, müssen wir die - ;; nächsten Methoden gar nicht erst - ;; versuchen. - (reaction (lookup-specification - (not-found => return)))) - - ;; Ansonsten benutzen wir DNS. - (name-service - (name "dns")) - - ;; Ein letzter Versuch mit dem - ;; "vollständigen" 'mdns'. - (name-service - (name "mdns"))))) -@end example - -Keine Sorge: Die Variable @code{%mdns-host-lookup-nss} (siehe unten) enthält -diese Konfiguration bereits. Statt das alles selst einzutippen, können Sie -sie benutzen, wenn alles, was Sie möchten, eine funktionierende -Namensauflösung für @code{.local}-Rechner ist. - -Beachten Sie dabei, dass es zusätzlich zum Festlegen des -@code{name-service-switch} in der @code{operating-system}-Deklaration auch -erforderlich ist, den @code{avahi-service-type} zu benutzen (siehe -@ref{Netzwerkdienste, @code{avahi-service-type}}). Es genügt auch, wenn -Sie die @var{%desktop-services} benutzen, weil er darin enthalten ist (siehe -@ref{Desktop-Dienste}). Dadurch wird @code{nss-mdns} für den Name Service -Cache Daemon nutzbar (siehe @ref{Basisdienste, @code{nscd-service}}). - -Um sich eine lange Konfiguration zu ersparen, können Sie auch einfach die -folgenden Variablen für typische NSS-Konfigurationen benutzen. - -@defvr {Scheme-Variable} %default-nss -Die vorgegebene Konfiguration des Name Service Switch als ein -@code{name-service-switch}-Objekt. -@end defvr - -@defvr {Scheme-Variable} %mdns-host-lookup-nss -Die Name-Service-Switch-Konfiguration mit Unterstützung für -Rechnernamensauflösung über »Multicast DNS« (mDNS) für auf @code{.local} -endende Rechnernamen. -@end defvr - -Im Folgenden finden Sie eine Referenz, wie eine -Name-Service-Switch-Konfiguration aussehen muss. Sie hat eine direkte -Entsprechung zum Konfigurationsdateiformat der C-Bibliothek, lesen Sie -weitere Informationen also bitte im Handbuch der C-Bibliothek nach (siehe -@ref{NSS Configuration File,,, libc, The GNU C Library Reference -Manual}). Gegenüber dem Konfigurationsdateiformat des libc-NSS bekommen Sie -mit unserer Syntax nicht nur ein warm umklammerndes Gefühl, sondern auch -eine statische Analyse: Wenn Sie Syntax- und Schreibfehler machen, werden -Sie darüber benachrichtigt, sobald Sie @command{guix system} aufrufen. - -@deftp {Datentyp} name-service-switch - -Der Datentyp, der die Konfiguration des Name Service Switch (NSS) der libc -repräsentiert. Jedes im Folgenden aufgeführte Feld repräsentiert eine der -unterstützten Systemdatenbanken. - -@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 -Das sind die Systemdatenbanken, um die sich NSS kümmern kann. Jedes dieser -Felder muss eine Liste aus @code{}-Objekten sein (siehe -unten). -@end table -@end deftp - -@deftp {Datentyp} name-service - -Der einen eigentlichen Namensdienst repräsentierende Datentyp zusammen mit -der zugehörigen Auflösungsaktion. - -@table @code -@item name -Eine Zeichenkette, die den Namensdienst bezeichnet (siehe @ref{Services in -the NSS configuration,,, libc, The GNU C Library Reference Manual}). - -Beachten Sie, dass hier aufgeführte Namensdienste für den nscd sichtbar sein -müssen. Dazu übergeben Sie im Argument @code{#:name-services} des -@code{nscd-service} die Liste der Pakete, die die entsprechenden -Namensdienste anbieten (siehe @ref{Basisdienste, @code{nscd-service}}). - -@item reaction -Eine mit Hilfe des Makros @code{lookup-specification} angegebene Aktion -(siehe @ref{Actions in the NSS configuration,,, libc, The GNU C Library -Reference Manual}). Zum Beispiel: - -@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 -Um ihn zu initialisieren (zu »bootstrappen«), wird für den Kernel -Linux-Libre eine @dfn{initiale RAM-Disk} angegeben (kurz @dfn{initrd}). Eine -initrd enthält ein temporäres Wurzeldateisystem sowie ein Skript zur -Initialisierung. Letzteres ist dafür zuständig, das echte Wurzeldateisystem -einzubinden und alle Kernel-Module zu laden, die dafür nötig sein könnten. - -Mit dem Feld @code{initrd-modules} einer @code{operating-system}-Deklaration -können Sie angeben, welche Kernel-Module für Linux-libre in der initrd -verfügbar sein müssen. Insbesondere müssen hier die Module aufgeführt -werden, um die Festplatte zu betreiben, auf der sich Ihre Wurzelpartition -befindet — allerdings sollte der vorgegebene Wert der @code{initrd-modules} -in dem meisten Fällen genügen. Wenn Sie aber zum Beispiel das Kernel-Modul -@code{megaraid_sas} zusätzlich zu den vorgegebenen Modulen brauchen, um auf -Ihr Wurzeldateisystem zugreifen zu können, würden Sie das so schreiben: - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Scheme-Variable} %base-initrd-modules -Der Vorgabewert für die Liste der Kernel-Module, die in der initrd enthalten -sein sollen. -@end defvr - -Wenn Sie noch systemnähere Anpassungen durchführen wollen, können Sie im -Feld @code{initrd} einer @code{operating-system}-Deklaration angeben, was -für eine Art von initrd Sie benutzen möchten. Das Modul @code{(gnu system -linux-initrd)} enthält drei Arten, eine initrd zu erstellen: die abstrakte -Prozedur @code{base-initrd} und die systemnahen Prozeduren @code{raw-initrd} -und @code{expression->initrd}. - -Mit der Prozedur @code{base-initrd} sollten Sie die häufigsten -Anwendungszwecke abdecken können. Wenn Sie zum Beispiel ein paar -Kernel-Module zur Boot-Zeit laden lassen möchten, können Sie das -@code{initrd}-Feld auf diese Art definieren: - -@example -(initrd (lambda (file-systems . rest) - ;; Eine gewöhnliche initrd, aber das Netzwerk wird - ;; mit den Parametern initialisiert, die QEMU - ;; standardmäßig erwartet. - (apply base-initrd file-systems - #:qemu-networking? #t - rest))) -@end example - -Die Prozedur @code{base-initrd} kann auch mit üblichen Anwendungszwecken -umgehen, um das System als QEMU-Gastsystem zu betreiben oder als ein -»Live«-System ohne ein dauerhaft gespeichertes Wurzeldateisystem. - -Die Prozedur @code{base-initrd} baut auf der Prozedur @code{raw-initrd} -auf. Anders als @code{base-initrd} hat @code{raw-initrd} keinerlei -Zusatzfunktionalitäten: Es wird kein Versuch unternommen, für die initrd -notwendige Kernel-Module und Pakete automatisch -hinzuzunehmen. @code{raw-initrd} kann zum Beispiel benutzt werden, wenn ein -Nutzer eine eigene Konfiguration des Linux-Kernels verwendet und die -Standard-Kernel-Module, die mit @code{base-initrd} hinzugenommen würden, -nicht verfügbar sind. - -Die initiale RAM-Disk, wie sie von @code{base-initrd} oder @code{raw-initrd} -erzeugt wird, richtet sich nach verschiedenen Optionen, die auf der -Kernel-Befehlszeile übergeben werden (also über GRUBs @code{linux}-Befehl -oder die @code{-append}-Befehlszeilenoption von QEMU). Erwähnt werden -sollten: - -@table @code -@item --load=@var{boot} -Die initiale RAM-Disk eine Datei @var{boot}, in der ein Scheme-Programm -steht, laden lassen, nachdem das Wurzeldateisystem eingebunden wurde. - -Guix übergibt mit dieser Befehlszeilenoption die Kontrolle an ein -Boot-Programm, das die Dienstaktivierungsprogramme ausführt und anschließend -den GNU@tie{}Shepherd startet, das Initialisierungssystem (»init«-System) -von Guix System. - -@item --root=@var{Wurzel} -Das mit @var{Wurzel} bezeichnete Dateisystem als Wurzeldateisystem -einbinden. @var{Wurzel} kann ein Geratename wie @code{/dev/sda1}, eine -Dateisystembezeichnung (d.h.@: ein Dateisystem-»Label«) oder eine -Dateisystem-UUID sein. - -@item --system=@var{System} -@file{/run/booted-system} und @file{/run/current-system} auf das -@var{System} zeigen lassen. - -@item modprobe.blacklist=@var{Module}@dots{} -@cindex Kernel-Module, Sperrliste -@cindex Sperrliste, von Kernel-Modulen -Die initiale RAM-Disk sowie den Befehl @command{modprobe} (aus dem -kmod-Paket) anweisen, das Laden der angegebenen @var{Module} zu -verweigern. Als @var{Module} muss eine kommagetrennte Liste von -Kernel-Modul-Namen angegeben werden — z.B.@: @code{usbkbd,9pnet}. - -@item --repl -Eine Lese-Auswerten-Schreiben-Schleife (englisch »Read-Eval-Print Loop«, -kurz REPL) von der initialen RAM-Disk starten, bevor diese die Kernel-Module -zu laden versucht und das Wurzeldateisystem einbindet. Unsere -Marketingabteilung nennt das @dfn{boot-to-Guile}. Der Schemer in Ihnen wird -das lieben. Siehe @ref{Using Guile Interactively,,, guile, GNU Guile -Reference Manual} für mehr Informationen über die REPL von Guile. - -@end table - -Jetzt wo Sie wissen, was für Funktionalitäten eine durch @code{base-initrd} -und @code{raw-initrd} erzeugte initiale RAM-Disk so haben kann, möchten Sie -vielleicht auch wissen, wie man Sie benutzt und weiter anpasst: - -@cindex initrd -@cindex initiale RAM-Disk -@deffn {Scheme-Prozedur} raw-initrd @var{Dateisysteme} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ -[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] -Liefert eine Ableitung, die eine rohe (»raw«) initrd -erstellt. @var{Dateisysteme} bezeichnet eine Liste von durch die initrd -einzubindenden Dateisystemen, unter Umständen zusätzlich zum auf der -Kernel-Befehlszeile mit @code{--root} angegebenen -Wurzeldateisystem. @var{linux-modules} ist eine Liste von Kernel-Modulen, -die zur Boot-Zeit geladen werden sollen. @var{mapped-devices} ist eine Liste -von Gerätezuordnungen, die hergestellt sein müssen, bevor die unter -@var{file-systems} aufgeführten Dateisysteme eingebunden werden (siehe -@ref{Zugeordnete Geräte}). @var{helper-packages} ist eine Liste von Paketen, die -in die initrd kopiert werden. Darunter kann @code{e2fsck/static} oder andere -Pakete aufgeführt werden, mit denen durch die initrd das Wurzeldateisystem -auf Fehler hin geprüft werden kann. - -When true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -Wenn @var{qemu-networking?} wahr ist, wird eine Netzwerkverbindung mit den -Standard-QEMU-Parametern hergestellt. Wenn @var{virtio?} wahr ist, werden -zusätzliche Kernel-Module geladen, damit die initrd als ein QEMU-Gast -paravirtualisierte Ein-/Ausgabetreiber benutzen kann. - -Wenn @var{volatile-root?} wahr ist, ist Schreiben auf das Wurzeldateisystem -möglich, aber Änderungen daran bleiben nicht erhalten. -@end deffn - -@deffn {Scheme-Prozedur} base-initrd @var{Dateisysteme} @ - [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] -[#:volatile-root? #f] @ [#:linux-modules '()] Liefert eine allgemein -anwendbare, generische initrd als dateiartiges Objekt mit den Kernel-Modulen -aus @var{linux}. Die @var{file-systems} sind eine Liste von durch die initrd -einzubindenden Dateisystemen, unter Umständen zusätzlich zum -Wurzeldateisystem, das auf der Kernel-Befehlszeile mit @code{--root} -angegeben wurde. Die @var{mapped-devices} sind eine Liste von -Gerätezuordnungen, die hergestellt sein müssen, bevor die @var{file-systems} -eingebunden werden. - -When true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -@var{qemu-networking?} und @var{volatile-root?} verhalten sich wie bei -@code{raw-initrd}. - -In die initrd werden automatisch alle Kernel-Module eingefügt, die für die -unter @var{file-systems} angegebenen Dateisysteme und die angegebenen -Optionen nötig sind. Zusätzliche Kernel-Module können unter den -@var{linux-modules} aufgeführt werden. Diese werden zur initrd hinzugefügt -und zur Boot-Zeit in der Reihenfolge geladen, in der sie angegeben wurden. -@end deffn - -Selbstverständlich betten die hier erzeugten und benutzten initrds ein -statisch gebundenes Guile ein und das Initialisierungsprogramm ist ein -Guile-Programm. Dadurch haben wir viel Flexibilität. Die Prozedur -@code{expression->initrd} erstellt eine solche initrd für ein an sie -übergebenes Programm. - -@deffn {Scheme-Prozedur} expression->initrd @var{G-Ausdruck} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] Liefert eine -Linux-initrd (d.h.@: ein gzip-komprimiertes cpio-Archiv) als dateiartiges -Objekt, in dem @var{guile} enthalten ist, womit der @var{G-Ausdruck} nach -dem Booten ausgewertet wird. Alle vom @var{G-Ausdruck} referenzierten -Ableitungen werden automatisch in die initrd kopiert. -@end deffn - -@node Bootloader-Konfiguration -@section Bootloader-Konfiguration - -@cindex bootloader -@cindex Bootloader - -Das Betriebssystem unterstützt mehrere Bootloader. Der gewünschte Bootloader -wird mit der @code{bootloader-configuration}-Deklaration konfiguriert. Alle -Felder dieser Struktur sind für alle Bootloader gleich außer dem einen Feld -@code{bootloader}, das angibt, welcher Bootloader konfiguriert und -installiert werden soll. - -Manche der Bootloader setzen nicht alle Felder einer -@code{bootloader-configuration} um. Zum Beispiel ignoriert der -extlinux-Bootloader das @code{theme}-Feld, weil er keine eigenen Themen -unterstützt. - -@deftp {Datentyp} bootloader-configuration -Der Typ der Deklaration einer Bootloader-Konfiguration. - -@table @asis - -@item @code{bootloader} -@cindex EFI, Bootloader -@cindex UEFI, Bootloader -@cindex BIOS, Bootloader -Der zu benutzende Bootloader als ein @code{bootloader}-Objekt. Zur Zeit -werden @code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} und @code{u-boot-bootloader} unterstützt. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} macht es möglich, auf modernen Systemen mit -@dfn{Unified Extensible Firmware Interface} (UEFI) zu booten. Sie sollten -das hier benutzen, wenn im Installationsabbild ein Verzeichnis -@file{/sys/firmware/efi} vorhanden ist, wenn Sie davon auf Ihrem System -booten. - -@vindex grub-bootloader -Mit @code{grub-bootloader} können Sie vor allem auf Intel-basierten -Maschinen im alten »Legacy«-BIOS-Modus booten. - -@cindex ARM, Bootloader -@cindex AArch64, Bootloader -Verfügbare Bootloader werden in den Modulen @code{(gnu bootloader @dots{})} -beschrieben. Insbesondere enthält @code{(gnu bootloader u-boot)} -Definitionen für eine Vielzahl von ARM- und AArch64-Systemen, die den -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot-Bootloader} benutzen. - -@item @code{target} -Eine Zeichenkette, die angibt, auf welches Ziel der Bootloader installiert -werden soll. - -Was das bedeutet, hängt vom jeweiligen Bootloader ab. Für -@code{grub-bootloader} sollte hier zum Beispiel ein Gerätename angegeben -werden, der vom @command{installer}-Befehl des Bootloaders verstanden wird, -etwa @code{/dev/sda} oder @code{(hd0)} (siehe @ref{Invoking grub-install,,, -grub, GNU GRUB Manual}). Für @code{grub-efi-bootloader} sollte der -Einhängepunkt des EFI-Dateisystems angegeben werden, in der Regel -@file{/boot/efi}. - -@item @code{menu-entries} (Vorgabe: @code{()}) -Eine möglicherweise leere Liste von @code{menu-entry}-Objekten (siehe -unten), die für Menüeinträge stehen, die im Bootloader-Menü auftauchen -sollen, zusätzlich zum aktuellen Systemeintrag und dem auf vorherige -Systemgenerationen verweisenden Eintrag. - -@item @code{default-entry} (Vorgabe: @code{0}) -Die Position des standardmäßig ausgewählten Bootmenü-Eintrags. An Position 0 -steht der Eintrag der aktuellen Systemgeneration. - -@item @code{timeout} (Vorgabe: @code{5}) -Wieviele Sekunden lang im Menü auf eine Tastatureingabe gewartet wird, bevor -gebootet wird. 0 steht für sofortiges Booten, für -1 wird ohne -Zeitbeschränkung gewartet. - -@cindex Tastaturbelegung, beim Bootloader -@item @code{keyboard-layout} (Vorgabe: @code{#f}) -Wenn dies auf @code{#f} gesetzt ist, verwendet das Menü des Bootloaders -(falls vorhanden) die Vorgabe-Tastaturbelegung, normalerweise -US@tie{}English (»qwerty«). - -Andernfalls muss es ein @code{keyboard-layout}-Objekt sein (siehe -@ref{Tastaturbelegung}). - -@quotation Anmerkung -Dieses Feld wird derzeit von Bootloadern außer @code{grub} und -@code{grub-efi} ignoriert. -@end quotation - -@item @code{theme} (Vorgabe: @var{#f}) -Ein Objekt für das im Bootloader anzuzeigende Thema. Wird kein Thema -angegeben, benutzen manche Bootloader vielleicht ein voreingestelltes Thema; -GRUB zumindest macht es so. - -@item @code{terminal-outputs} (Vorgabe: @code{'gfxterm}) -Die Ausgabeterminals, die für das Boot-Menü des Bootloaders benutzt werden, -als eine Liste von Symbolen. GRUB akzeptiert hier diese Werte: -@code{console}, @code{serial}, @code{serial_@{0–3@}}, @code{gfxterm}, -@code{vga_text}, @code{mda_text}, @code{morse} und @code{pkmodem}. Dieses -Feld entspricht der GRUB-Variablen @code{GRUB_TERMINAL_OUTPUT} (siehe -@ref{Simple configuration,,, grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (Vorgabe: @code{'()}) -Die Eingabeterminals, die für das Boot-Menü des Bootloaders benutzt werden, -als eine Liste von Symbolen. GRUB verwendet hier das zur Laufzeit bestimmte -Standardterminal. GRUB akzeptiert sonst diese Werte: @code{console}, -@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard} und -@code{usb_keyboard}. Dieses Feld entspricht der GRUB-Variablen -@code{GRUB_TERMINAL_INPUT} (siehe @ref{Simple configuration,,, grub,GNU GRUB -manual}). - -@item @code{serial-unit} (Vorgabe: @code{#f}) -Die serielle Einheit, die der Bootloader benutzt, als eine ganze Zahl -zwischen 0 und 3, einschließlich. Für GRUB wird sie automatisch zur Laufzeit -ausgewählt; derzeit wählt GRUB die 0 aus, die COM1 entspricht (siehe -@ref{Serial terminal,,, grub,GNU GRUB manual}). - -@item @code{serial-speed} (Vorgabe: @code{#f}) -Die Geschwindigkeit der seriellen Schnittstelle als eine ganze Zahl. GRUB -bestimmt den Wert standardmäßig zur Laufzeit; derzeit wählt GRUB -9600@tie{}bps (siehe @ref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex Dual-Boot -@cindex Bootmenü -Sollten Sie zusätzliche Bootmenü-Einträge über das oben beschriebene -@code{menu-entries}-Feld hinzufügen möchten, müssen Sie diese mit der -@code{menu-entry}-Form erzeugen. Stellen Sie sich zum Beispiel vor, Sie -wollten noch eine andere Distribution booten können (schwer vorstellbar!), -dann könnten Sie einen Menüeintrag wie den Folgenden definieren: - -@example -(menu-entry - (label "Die _andere_ Distribution") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Details finden Sie unten. - -@deftp {Datentyp} menu-entry -Der Typ eines Eintrags im Bootloadermenü. - -@table @asis - -@item @code{label} -Die Beschriftung, die im Menü gezeigt werden soll — z.B.@: @code{"GNU"}. - -@item @code{linux} -Das Linux-Kernel-Abbild, was gebootet werden soll, zum Beispiel: - -@example -(file-append linux-libre "/bzImage") -@end example - -Für GRUB kann hier auch ein Gerät ausdrücklich zum Dateipfad angegeben -werden, unter Verwendung von GRUBs Konventionen zur Gerätebenennung (siehe -@ref{Naming convention,,, grub, GNU GRUB manual}), zum Beispiel: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -Wenn das Gerät auf diese Weise ausdrücklich angegeben wird, wird das -@code{device}-Feld gänzlich ignoriert. - -@item @code{linux-arguments} (Vorgabe: @code{()}) -Die Liste zusätzlicher Linux-Kernel-Befehlszeilenargumente — z.B.@: -@code{("console=ttyS0")}. - -@item @code{initrd} -Ein G-Ausdruck oder eine Zeichenkette, die den Dateinamen der initialen -RAM-Disk angibt, die benutzt werden soll (siehe @ref{G-Ausdrücke}). -@item @code{device} (Vorgabe: @code{#f}) -Das Gerät, auf dem Kernel und initrd zu finden sind — d.h.@: bei GRUB die -Wurzel (@dfn{root}) dieses Menüeintrags (siehe @ref{root,,, grub, GNU GRUB -manual}). - -Dies kann eine Dateisystembezeichnung (als Zeichenkette), eine -Dateisystem-UUID (als Bytevektor, siehe @ref{Dateisysteme}) oder @code{#f} -sein, im letzten Fall wird der Bootloader auf dem Gerät suchen, das die vom -@code{linux}-Feld benannte Datei enthält (siehe @ref{search,,, grub, GNU -GRUB manual}). Ein vom Betriebssystem vergebener Gerätename wie -@file{/dev/sda1} ist aber @emph{nicht} erlaubt. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -For 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 -Das vorgegebene GRUB-Thema, das vom Betriebssystem benutzt wird, wenn kein -@code{theme}-Feld im @code{bootloader-configuration}-Verbundsobjekt -angegeben wurde. - -Es wird von einem feschen Hintergrundbild begleitet, das die Logos von GNU -und Guix zeigt. -@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 (siehe @ref{Top, GNU recutils databases,, recutils, GNU recutils -manual}). - -@item reconfigure -Das in der @var{Datei} beschriebene Betriebssystem erstellen, aktivieren und -zu ihm wechseln@footnote{Diese Aktion (und die dazu ähnlichen Aktionen -@code{switch-generation} und @code{roll-back}) sind nur auf Systemen -nutzbar, auf denen »Guix System« bereits läuft.}. - -Dieser Befehl setzt die in der @var{Datei} festgelegte Konfiguration -vollständig um: Benutzerkonten, Systemdienste, die Liste globaler Pakete, -setuid-Programme und so weiter. Der Befehl startet die in der @var{Datei} -angegebenen Systemdienste, die aktuell nicht laufen; bei aktuell laufenden -Diensten wird sichergestellt, dass sie aktualisiert werden, sobald sie das -nächste Mal angehalten wurden (z.B.@: durch @code{herd stop X} oder -@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} (siehe @ref{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 . -Es ist sehr zu empfehlen, @command{guix pull} einmal auszuführen, bevor Sie -@command{guix system reconfigure} zum ersten Mal aufrufen (siehe -@ref{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 Löschen von Systemgenerationen -@cindex Platz sparen -Systemgenerationen löschen, wodurch diese zu Kandidaten für den Müllsammler -werden (siehe @ref{Aufruf von guix gc} für Informationen, wie Sie den -»Müllsammler« laufen lassen). - -Es funktioniert auf die gleiche Weise wie @command{guix package ---delete-generations} (siehe @ref{Aufruf von guix package, -@code{--delete-generations}}). Wenn keine Argumente angegeben werden, werden -alle Systemgenerationen außer der aktuellen gelöscht: - -@example -guix system delete-generations -@end example - -Sie können auch eine Auswahl treffen, welche Generationen Sie löschen -möchten. Das folgende Beispiel hat die Löschung aller Systemgenerationen zur -Folge, die älter als zwei Monate sind: - -@example -guix system delete-generations 2m -@end example - -Wenn Sie diesen Befehl ausführen, wird automatisch der Bootloader mit einer -aktualisierten Liste von Menüeinträgen neu erstellt — z.B.@: werden im -Untermenü für die »alten Generationen« in GRUB die gelöschten Generationen -nicht mehr aufgeführt. - -@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 -In das angegebene Verzeichnis alle Dateien einfügen, um das in der -@var{Datei} angegebene Betriebssystem starten zu können. Dies ist nützlich -bei erstmaligen Installationen von »Guix System«. Zum Beispiel: - -@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} -Eine virtuelle Maschine (VM) erstellen, die das in der @var{Datei} -deklarierte Betriebssystem enthält, und ein Skript liefern, das diese -virtuelle Maschine startet. - -@quotation Anmerkung -Die Aktion @code{vm} sowie solche, die weiter unten genannt werden, können -KVM-Unterstützung im Kernel Linux-libre ausnutzen. Insbesondere sollte, wenn -die Maschine Hardware-Virtualisierung unterstützt, das entsprechende -KVM-Kernelmodul geladen sein und das Gerät @file{/dev/kvm} muss dann -existieren und dem Benutzer und den Erstellungsbenutzern des Daemons müssen -Berechtigungen zum Lesen und Schreiben darauf gegeben werden (siehe -@ref{Einrichten der Erstellungsumgebung}). -@end quotation - -An das Skript übergebene Argumente werden an QEMU weitergereicht, wie Sie am -folgenden Beispiel sehen können. Damit würde eine Netzwerkverbindung -aktiviert und 1@tie{}GiB an RAM für die emulierte Maschine angefragt: - -@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. - -Wenn Sie ein @code{vm-image} anfordern, ist das gelieferte Disk-Image im -qcow2-Format, was vom QEMU-Emulator effizient benutzt werden kann. Im -Abschnitt @ref{Guix in einer VM starten} finden Sie mehr Informationen, wie Sie -das Disk-Image in einer virtuellen Maschine laufen lassen. - -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 < guix-system-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 - -Dieser Befehl startet einen neuen Docker-Container aus dem angegebenen -Abbild. Damit wird das Guix-System auf die normale Weise hochgefahren, -d.h.@: zunächst werden alle Dienste gestartet, die Sie in der Konfiguration -des Betriebssystems angegeben haben. Je nachdem, was Sie im Docker-Container -ausführen, kann es nötig sein, dass Sie ihn mit weitergehenden -Berechtigungen ausstatten. Wenn Sie zum Beispiel Software mit Guix innerhalb -des Docker-Containers erstellen wollen, müssen Sie an @code{docker run} die -Befehlszeilenoption @option{--privileged} übergeben. - -@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} (siehe @ref{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 @ref{Gemeinsame Erstellungsoptionen}). Des Weiteren kann als -@var{Optionen} Folgendes angegeben werden: - -@table @option -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Konfiguration des Betriebssystems das »operating-system« betrachten, zu -dem der @var{Ausdruck} ausgewertet wird. Dies ist eine Alternative dazu, die -Konfiguration in einer Datei festzulegen. Hiermit wird auch das -Installationsabbild des Guix-Systems erstellt, siehe @ref{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} (siehe @ref{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{Typ} -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 @ref{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{Datei} -@itemx -r @var{Datei} -Die @var{Datei} zu einer symbolischen Verknüpfung auf das Ergebnis machen -und als Müllsammlerwurzel registrieren. - -@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 (siehe @ref{Dateisysteme}) und -dass alle Linux-Kernelmodule, die beim Booten benötigt werden könnten, auch -im @code{initrd-modules}-Feld aufgeführt sind (siehe @ref{Initiale RAM-Disk}). Mit dieser Befehlszeilenoption werden diese Tests allesamt -übersprungen. - -@cindex on-error -@cindex on-error-Strategie -@cindex Fehlerstrategie -@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 @ref{Debug Commands,,, guile, GNU Guile Reference Manual} -für eine Liste verfügbarer Befehle zur Fehlersuche. -@end table -@end table - -Sobald Sie Ihre Guix-Installation erstellt, konfiguriert, neu konfiguriert -und nochmals neu konfiguriert haben, finden Sie es vielleicht hilfreich, -sich die auf der Platte verfügbaren — und im Bootmenü des Bootloaders -auswählbaren — Systemgenerationen auflisten zu lassen: - -@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} -(siehe @ref{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 (siehe @ref{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 @ref{Shepherd-Dienste} für mehr -Informationen sowie einen Beispielgraphen. - -@end table - -@node Guix in einer VM starten -@section Guix in einer virtuellen Maschine betreiben - -@cindex virtuelle Maschine -Um Guix in einer virtuellen Maschine (VM) auszuführen, können Sie entweder -das vorerstellte Guix-VM-Abbild benutzen, das auf -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{System}.xz} -angeboten wird, oder Ihr eigenes Abbild erstellen, indem Sie @command{guix -system vm-image} benutzen (siehe @ref{Aufruf von guix system}). Das Abbild -wird im qcow2-Format zurückgeliefert, das der @uref{http://qemu.org/, -QEMU-Emulator} effizient benutzen kann. - -@cindex QEMU -Wenn Sie Ihr eigenes Abbild erstellen haben lassen, müssen Sie es aus dem -Store herauskopieren (siehe @ref{Der Store}) und sich darauf -Schreibberechtigung geben, um die Kopie benutzen zu können. Wenn Sie QEMU -aufrufen, müssen Sie einen Systememulator angeben, der für Ihre -Hardware-Plattform passend ist. Hier ist ein minimaler QEMU-Aufruf, der das -Ergebnis von @command{guix system vm-image} auf x86_64-Hardware bootet: - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image -@end example - -Die Bedeutung jeder dieser Befehlszeilenoptionen ist folgende: - -@table @code -@item qemu-system-x86_64 -Hiermit wird die zu emulierende Hardware-Plattform angegeben. Sie sollte zum -Wirtsrechner passen. - -@item -net user -Den als Nutzer ausgeführten Netzwerkstapel (»User-Mode Network Stack«) ohne -besondere Berechtigungen benutzen. Mit dieser Art von Netzwerkanbindung kann -das Gast-Betriebssystem eine Verbindung zum Wirt aufbauen, aber nicht -andersherum. Es ist die einfachste Art, das Gast-Betriebssystem mit dem -Internet zu verbinden. - -@item -net nic,model=virtio -Sie müssen ein Modell einer zu emulierenden Netzwerkschnittstelle -angeben. Wenn Sie keine Netzwerkkarte (englisch »Network Interface Card«, -kurz NIC) erzeugen lassen, wird das Booten fehlschlagen. Falls Ihre -Hardware-Plattform x86_64 ist, können Sie eine Liste verfügbarer NIC-Modelle -einsehen, indem Sie @command{qemu-system-x86_64 -net nic,model=help} -ausführen. - -@item -enable-kvm -Wenn Ihr System über Erweiterungen zur Hardware-Virtualisierung verfügt, -beschleunigt es die Dinge, wenn Sie die Virtualisierungsunterstützung »KVM« -des Linux-Kernels benutzen lassen. - -@item -m 256 -Die Menge an Arbeitsspeicher (RAM), die dem Gastbetriebssystem zur Verfügung -stehen soll, in Mebibytes. Vorgegeben wären 128@tie{}MiB, was für einige -Operationen zu wenig sein könnte. - -@item /tmp/qemu-image -Der Dateiname des qcow2-Abbilds. -@end table - -Das voreingestellte @command{run-vm.sh}-Skript, das durch einen Aufruf von -@command{guix system vm} erzeugt wird, fügt keine Befehlszeilenoption -@command{-net user} an. Um innerhalb der virtuellen Maschine Netzwerkzugang -zu haben, fügen Sie den @code{(dhcp-client-service)} zu Ihrer -Systemdefinition hinzu und starten Sie die VM mit @command{`guix system vm -config.scm` -net user}. Erwähnt werden sollte der Nachteil, dass bei -Verwendung von @command{-net user} zur Netzanbindung der -@command{ping}-Befehl @emph{nicht} funktionieren wird, weil dieser das -ICMP-Protokoll braucht. Sie werden also einen anderen Befehl benutzen -müssen, um auszuprobieren, ob Sie mit dem Netzwerk verbunden sind, zum -Beispiel @command{guix download}. - -@subsection Verbinden über SSH - -@cindex SSH -@cindex SSH server -Um SSH in der virtuellen Maschine zu aktivieren, müssen Sie einen SSH-Server -wie den @code{(dropbear-service)} oder den @code{(lsh-service)} zu ihr -hinzufügen. Der @code{(lsh-service}) kann derzeit nicht ohne -Benutzerinteraktion starten, weil der Benutzer erst ein paar Zeichen -eintippen muss, um den Zufallsgenerator zu initialisieren. Des Weiteren -müssen Sie den SSH-Port für das Wirtssystem freigeben (standardmäßig hat er -die Portnummer 22). Das geht zum Beispiel so: - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -Um sich mit der virtuellen Maschine zu verbinden, benutzen Sie diesen -Befehl: - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -Mit @command{-p} wird @command{ssh} der Port mitgeteilt, über den eine -Verbindung hergestellt werden soll. @command{-o -UserKnownHostsFile=/dev/null} verhindert, dass @command{ssh} sich bei jeder -Modifikation Ihrer @command{config.scm}-Datei beschwert, ein anderer -bekannter Rechner sei erwartet worden, und @command{-o -StrictHostKeyChecking=no} verhindert, dass Sie die Verbindung zu unbekannten -Rechnern jedes Mal bestätigen müssen, wenn Sie sich verbinden. - -@subsection @command{virt-viewer} mit Spice benutzen - -Eine Alternative zur grafischen Schnittstelle des standardmäßigen -@command{qemu} ist, sich mit Hilfe des @command{remote-viewer} aus dem Paket -@command{virt-viewer} zu verbinden. Um eine Verbindung herzustellen, -übergeben Sie die Befehlszeilenoption @command{-spice -port=5930,disable-ticketing} an @command{qemu}. Siehe den vorherigen -Abschnitt für weitere Informationen, wie Sie das übergeben. - -Spice macht es auch möglich, ein paar nette Hilfestellungen zu benutzen, zum -Beispiel können Sie Ihren Zwischenspeicher zum Kopieren und Einfügen (Ihr -»Clipboard«) mit Ihrer virtuellen Maschine teilen. Um das zu aktivieren, -werden Sie die folgenden Befehlszeilennoptionen zusätzlich an @command{qemu} -übergeben müssen: - -@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 - -Sie werden auch den @ref{Verschiedene Dienste, Spice-Dienst} hinzufügen -müssen. - -@node Dienste definieren -@section Dienste definieren - -Der vorhergehende Abschnitt präsentiert die verfügbaren Dienste und wie man -sie in einer @code{operating-system}-Deklaration kombiniert. Aber wie -definieren wir solche Dienste eigentlich? Und was ist überhaupt ein Dienst? - -@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 -Wir definieren hier einen @dfn{Dienst} (englisch »Service«) als, grob -gesagt, etwas, das die Funktionalität des Betriebssystems erweitert. Oft ist -ein Dienst ein Prozess — ein sogenannter @dfn{Daemon} —, der beim Hochfahren -des Systems gestartet wird: ein Secure-Shell-Server, ein Web-Server, der -Guix-Erstellungsdaemon usw. Manchmal ist ein Dienst ein Daemon, dessen -Ausführung von einem anderen Daemon ausgelöst wird — zum Beispiel wird ein -FTP-Server von @command{inetd} gestartet oder ein D-Bus-Dienst durch -@command{dbus-daemon} aktiviert. Manchmal entspricht ein Dienst aber auch -keinem Daemon. Zum Beispiel nimmt sich der Benutzerkonten-Dienst (»account -service«) die Benutzerkonten und sorgt dafür, dass sie existieren, wenn das -System läuft. Der »udev«-Dienst sammelt die Regeln zur Geräteverwaltung an -und macht diese für den eudev-Daemon verfügbar. Der @file{/etc}-Dienst fügt -Dateien in das Verzeichnis @file{/etc} des Systems ein. - -@cindex Diensterweiterungen -Dienste des Guix-Systems werden durch @dfn{Erweiterungen} (»Extensions«) -miteinander verbunden. Zum Beispiel @emph{erweitert} der Secure-Shell-Dienst -den Shepherd — Shepherd ist das Initialisierungssystem (auch »init«-System -genannt), was als PID@tie{}1 läuft —, indem es ihm die Befehlszeilen zum -Starten und Stoppen des Secure-Shell-Daemons übergibt (siehe @ref{Netzwerkdienste, @code{openssh-service-type}}). Der UPower-Dienst erweitert den -D-Bus-Dienst, indem es ihm seine @file{.service}-Spezifikation übergibt, und -erweitert den udev-Dienst, indem es ihm Geräteverwaltungsregeln übergibt -(siehe @ref{Desktop-Dienste, @code{upower-service}}). Der -Guix-Daemon-Dienst erweitert den Shepherd, indem er ihm die Befehlszeilen -zum Starten und Stoppen des Daemons übergibt, und er erweitert den -Benutzerkontendienst (»account service«), indem er ihm eine Liste der -benötigten Erstellungsbenutzerkonten übergibt (siehe @ref{Basisdienste}). - -Alles in allem bilden Dienste und ihre »Erweitert«-Relationen einen -gerichteten azyklischen Graphen (englisch »Directed Acyclic Graph«, kurz -DAG). Wenn wir Dienste als Kästen und Erweiterungen als Pfeile darstellen, -könnte ein typisches System so etwas hier anbieten: - -@image{images/service-graph,,5in,Typischer Diensterweiterungsgraph} - -@cindex Systemdienst -Ganz unten sehen wir den @dfn{Systemdienst}, der das Verzeichnis erzeugt, in -dem alles zum Ausführen und Hochfahren enthalten ist, so wie es der Befehl -@command{guix system build} liefert. Siehe @ref{Service-Referenz}, um mehr -über die anderen hier gezeigten Diensttypen zu erfahren. Beim -@ref{system-extension-graph, Befehl @command{guix system extension-graph}} -finden Sie Informationen darüber, wie Sie diese Darstellung für eine -Betriebssystemdefinition Ihrer Wahl generieren lassen. - -@cindex Diensttypen -Technisch funktioniert es so, dass Entwickler @dfn{Diensttypen} definieren -können, um diese Beziehungen auszudrücken. Im System kann es beliebig viele -Dienste zu jedem Typ geben — zum Beispiel können auf einem System zwei -Instanzen des GNU-Secure-Shell-Servers (lsh) laufen, mit zwei Instanzen des -Diensttyps @code{lsh-service-type} mit je unterschiedlichen Parametern. - -Der folgende Abschnitt beschreibt die Programmierschnittstelle für -Diensttypen und Dienste. - -@node Diensttypen und Dienste -@subsection Diensttypen und Dienste - -Ein @dfn{Diensttyp} (»service type«) ist ein Knoten im oben beschriebenen -ungerichteten azyklischen Graphen (DAG). Fangen wir an mit einem einfachen -Beispiel: dem Diensttyp für den Guix-Erstellungsdaemon (siehe @ref{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 -Damit sind drei Dinge definiert: - -@enumerate -@item -Ein Name, der nur dazu da ist, dass man leichter die Abläufe verstehen und -Fehler suchen kann. - -@item -Eine Liste von @dfn{Diensterweiterungen} (»service extensions«). Jede -Erweiterung gibt den Ziel-Diensttyp an sowie eine Prozedur, die für gegebene -Parameter für den Dienst eine Liste von Objekten zurückliefert, um den -Dienst dieses Typs zu erweitern. - -Jeder Diensttyp benutzt mindestens eine Diensterweiterung. Die einzige -Ausnahme ist der @dfn{boot service type}, der die Grundlage aller Dienste -ist. - -@item -Optional kann ein Vorgabewert für Instanzen dieses Typs angegeben werden. -@end enumerate - -In this example, @code{guix-service-type} extends three services: - -@table @code -@item shepherd-root-service-type -The @code{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{} 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 @code{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 @code{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 - -Ein Dienst dieses Typs wird dann so instanziiert: - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -Das zweite Argument an die @code{service}-Form ist ein Wert, der die -Parameter dieser bestimmten Dienstinstanz repräsentiert. Siehe -@ref{guix-configuration-type, @code{guix-configuration}} für Informationen -über den @code{guix-configuration}-Datentyp. Wird kein Wert angegeben, wird -die Vorgabe verwendet, die im @code{guix-service-type} angegeben wurde: - -@example -(service guix-service-type) -@end example - -@code{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -Der Diensttyp eines @emph{erweiterbaren} Dienstes sieht ungefähr so aus: - -@example -(define udev-service-type - (service-type (name 'udev) - (extensions - (list (service-extension shepherd-root-service-type - udev-shepherd-service))) - - (compose concatenate) ;Liste der Regeln zusammenfügen - (extend (lambda (config rules) ;Konfiguration und Regeln - (match config - (($ udev initial-rules) - (udev-configuration - (udev udev) ;zu benutzendes udev-Paket - (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 -@code{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -Die Prozedur, um die Liste der jeweiligen Erweiterungen für den Dienst -dieses Typs zu einem Objekt zusammenzustellen (zu »komponieren«, englisch -@dfn{compose}). - -Dienste können den udev-Dienst erweitern, indem sie eine Liste von Regeln -(»Rules«) an ihn übergeben; wir komponieren mehrere solche Erweiterungen, -indem wir die Listen einfach zusammenfügen. - -@item extend -Diese Prozedur definiert, wie der Wert des Dienstes um die Komposition mit -Erweiterungen erweitert (»extended«) werden kann. - -Udev-Erweiterungen werden zu einer einzigen Liste von Regeln komponiert, -aber der Wert des udev-Dienstes ist ein -@code{}-Verbundsobjekt. Deshalb erweitern wir diesen -Verbund, indem wir die Liste der von Erweiterungen beigetragenen Regeln an -die im Verbund gespeicherte Liste der Regeln anhängen. - -@item description -Diese Zeichenkette gibt einen Überblick über den Systemtyp. Die Zeichenkette -darf mit Texinfo ausgezeichnet werden (siehe @ref{Overview,,, texinfo, GNU -Texinfo}). Der Befehl @command{guix system search} durchsucht diese -Zeichenketten und zeigt sie an (siehe @ref{Aufruf von guix system}). -@end table - -There can be only one instance of an extensible service type such as -@code{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -Sind Sie noch da? Der nächste Abschnitt gibt Ihnen eine Referenz der -Programmierschnittstelle für Dienste. - -@node Service-Referenz -@subsection Service-Referenz - -Wir haben bereits einen Überblick über Diensttypen gesehen (siehe -@ref{Diensttypen und Dienste}). Dieser Abschnitt hier stellt eine -Referenz dar, wie Dienste und Diensttypen manipuliert werden können. Diese -Schnittstelle wird vom Modul @code{(gnu services)} angeboten. - -@deffn {Scheme-Prozedur} service @var{Typ} [@var{Wert}] -Liefert einen neuen Dienst des angegebenen @var{Typ}s. Der @var{Typ} muss -als @code{}-Objekt angegeben werden (siehe unten). Als -@var{Wert} kann ein beliebiges Objekt angegeben werden, das die Parameter -dieser bestimmten Instanz dieses Dienstes repräsentiert. - -Wenn kein @var{Wert} angegeben wird, wird der vom @var{Typ} festgelegte -Vorgabewert verwendet; verfügt der @var{Typ} über keinen Vorgabewert, dann -wird ein Fehler gemeldet. - -Zum Beispiel bewirken Sie hiermit: - -@example -(service openssh-service-type) -@end example - -@noindent -dasselbe wie mit: - -@example -(service openssh-service-type - (openssh-configuration)) -@end example - -In beiden Fällen ist das Ergebnis eine Instanz von -@code{openssh-service-type} mit der vorgegebenen Konfiguration. -@end deffn - -@deffn {Scheme-Prozedur} service? @var{Objekt} -Liefert wahr zurück, wenn das @var{Objekt} ein Dienst ist. -@end deffn - -@deffn {Scheme-Prozedur} service-kind @var{Dienst} -Liefert den Typ des @var{Dienst}es — d.h.@: ein -@code{}-Objekt. -@end deffn - -@deffn {Scheme-Prozedur} service-value @var{Dienst} -Liefert den Wert, der mit dem @var{Dienst} assoziiert wurde. Er -repräsentiert die Parameter des @var{Dienst}es. -@end deffn - -Hier ist ein Beispiel, wie ein Dienst erzeugt und manipuliert werden kann: - -@example -(define s - (service nginx-service-type - (nginx-configuration - (nginx nginx) - (log-directory log-Verzeichnis) - (run-directory run-Verzeichnis) - (file config-Datei)))) - -(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 @code{%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 @ref{Das Konfigurationssystem nutzen} für ein Anwendungsbeispiel. - -@end deffn - -Als Nächstes ist die Programmierschnittstelle für Diensttypen an der -Reihe. Sie ist etwas, was Sie kennen werden wollen, wenn Sie neue -Dienstdefinitionen schreiben, aber wenn Sie nur Ihre -@code{operating-system}-Deklaration anpassen möchten, brauchen Sie diese -Schnittstelle wahrscheinlich nicht. - -@deftp {Datentyp} service-type -@cindex Diensttyp -Die Repräsentation eines @dfn{Diensttypen} (siehe @ref{Diensttypen und Dienste}). - -@table @asis -@item @code{name} -Dieses Symbol wird nur verwendet, um die Abläufe im System anzuzeigen und -die Fehlersuche zu erleichtern. - -@item @code{extensions} -Eine nicht-leere Liste von @code{}-Objekten (siehe -unten). - -@item @code{compose} (Vorgabe: @code{#f}) -Wenn es auf @code{#f} gesetzt ist, dann definiert der Diensttyp Dienste, die -nicht erweitert werden können — d.h.@: diese Dienste erhalten ihren Wert -nicht von anderen Diensten. - -Andernfalls muss es eine Prozedur sein, die ein einziges Argument -entgegennimmt. Die Prozedur wird durch @code{fold-services} aufgerufen und -ihr wird die Liste von aus den Erweiterungen angesammelten Werten -übergeben. Sie gibt daraufhin einen einzelnen Wert zurück. - -@item @code{extend} (Vorgabe: @code{#f}) -Ist dies auf @code{#f} gesetzt, dann können Dienste dieses Typs nicht -erweitert werden. - -Andernfalls muss es eine zwei Argumente nehmende Prozedur sein, die von -@code{fold-services} mit dem anfänglichen Wert für den Dienst als erstes -Argument und dem durch Anwendung von @code{compose} gelieferten Wert als -zweites Argument aufgerufen wird. Als Ergebnis muss ein Wert geliefert -werden, der einen zulässigen neuen Parameterwert für die Dienstinstanz -darstellt. -@end table - -Siehe den Abschnitt @ref{Diensttypen und Dienste} für Beispiele. -@end deftp - -@deffn {Scheme-Prozedur} service-extension @var{Zieltyp} @ - @var{Berechner} Liefert eine neue Erweiterung für den Dienst mit dem -@var{Zieltyp}. Als @var{Berechner} muss eine Prozedur angegeben werden, die -ein einzelnes Argument nimmt: @code{fold-services} ruft sie auf und übergibt -an sie den Wert des erweiternden Dienstes, sie muss dafür einen zulässigen -Wert für den @var{Zieltyp} liefern. -@end deffn - -@deffn {Scheme-Prozedur} service-extension? @var{Objekt} -Liefert wahr zurück, wenn das @var{Objekt} eine Diensterweiterung ist. -@end deffn - -Manchmal wollen Sie vielleicht einfach nur einen bestehenden Dienst -erweitern. Dazu müssten Sie einen neuen Diensttyp definieren und die -Erweiterung definieren, für die Sie sich interessieren, was ganz schön -wortreich werden kann. Mit der Prozedur @code{simple-service} können Sie es -kürzer fassen. - -@deffn {Scheme-Prozedur} simple-service @var{Name} @var{Zieltyp} @var{Wert} -Liefert einen Dienst, der den Dienst mit dem @var{Zieltyp} um den @var{Wert} -erweitert. Dazu wird ein Diensttyp mit dem @var{Name}n für den einmaligen -Gebrauch erzeugt, den der zurückgelieferte Dienst instanziiert. - -Zum Beispiel kann mcron (siehe @ref{Geplante Auftragsausführung}) so um einen -zusätzlichen Auftrag erweitert werden: - -@example -(simple-service 'my-mcron-job mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -Den Kern dieses abstrakten Modells für Dienste bildet die Prozedur -@code{fold-services}, die für das »Kompilieren« einer Liste von Diensten hin -zu einem einzelnen Verzeichnis verantwortlich ist, in welchem alles -enthalten ist, was Sie zum Booten und Hochfahren des Systems brauchen — -d.h.@: das Verzeichnis, das der Befehl @command{guix system build} anzeigt -(siehe @ref{Aufruf von guix system}). Einfach ausgedrückt propagiert -@code{fold-services} Diensterweiterungen durch den Dienstgraphen nach unten -und aktualisiert dabei in jedem Knoten des Graphen dessen Parameter, bis nur -noch der Wurzelknoten übrig bleibt. - -@deffn {Scheme-Prozedur} fold-services @var{Dienste} @ - [#:target-type @var{system-service-type}] Faltet die @var{Dienste} wie die -funktionale Prozedur @code{fold} zu einem einzigen zusammen, indem ihre -Erweiterungen nach unten propagiert werden, bis eine Wurzel vom -@var{target-type} als Diensttyp erreicht wird; dieser so angepasste -Wurzeldienst wird zurückgeliefert. -@end deffn - -Als Letztes definiert das Modul @code{(gnu services)} noch mehrere -essenzielle Diensttypen, von denen manche im Folgenden aufgelistet sind: - -@defvr {Scheme-Variable} system-service-type -Die Wurzel des Dienstgraphen. Davon wird das Systemverzeichnis erzeugt, wie -es vom Befehl @command{guix system build} zurückgeliefert wird. -@end defvr - -@defvr {Scheme-Variable} boot-service-type -Der Typ des »Boot-Dienstes«, der das @dfn{Boot-Skript} erzeugt. Das -Boot-Skript ist das, was beim Booten durch die initiale RAM-Disk ausgeführt -wird. -@end defvr - -@defvr {Scheme-Variable} etc-service-type -Der Typ des @file{/etc}-Dienstes. Dieser Dienst wird benutzt, um im -@file{/etc}-Verzeichnis Dateien zu platzieren. Er kann erweitert werden, -indem man Name-/Datei-Tupel an ihn übergibt wie in diesem Beispiel: - -@example -(list `("issue" ,(plain-file "issue" "Willkommen!\n"))) -@end example - -Dieses Beispiel würde bewirken, dass eine Datei @file{/etc/issue} auf die -angegebene Datei verweist. -@end defvr - -@defvr {Scheme-Variable} setuid-program-service-type -Der Typ des Dienstes für setuid-Programme, der eine Liste von ausführbaren -Dateien ansammelt, die jeweils als G-Ausdrücke übergeben werden und dann zur -Menge der setuid-gesetzten Programme auf dem System hinzugefügt werden -(siehe @ref{Setuid-Programme}). -@end defvr - -@defvr {Scheme-Variable} profile-service-type -Der Typ des Dienstes zum Einfügen von Dateien ins @dfn{Systemprofil} — -d.h.@: die Programme unter @file{/run/current-system/profile}. Andere -Dienste können ihn erweitern, indem sie ihm Listen von ins Systemprofil zu -installierenden Paketen übergeben. -@end defvr - - -@node Shepherd-Dienste -@subsection Shepherd-Dienste - -@cindex Shepherd-Dienste -@cindex PID 1 -@cindex init-System -Das Modul @code{(gnu services shepherd)} gibt eine Methode an, mit der -Dienste definiert werden können, die von GNU@tie{}Shepherd verwaltet werden, -was das Initialisierungssystem (das »init«-System) ist — es ist der erste -Prozess, der gestartet wird, wenn das System gebootet wird, auch bekannt als -PID@tie{}1 (siehe @ref{Einführung,,, shepherd, The GNU Shepherd Manual}). - -Dienste unter dem Shepherd können voneinander abhängen. Zum Beispiel kann es -sein, dass der SSH-Daemon erst gestartet werden darf, nachdem der -Syslog-Daemon gestartet wurde, welcher wiederum erst gestartet werden kann, -sobald alle Dateisysteme eingebunden wurden. Das einfache Betriebssystem, -dessen Definition wir zuvor gesehen haben (siehe @ref{Das Konfigurationssystem nutzen}), ergibt folgenden Dienstgraphen: - -@image{images/shepherd-graph,,5in,Typischer Shepherd-Dienstgraph} - -Sie können so einen Graphen tatsächlich für jedes Betriebssystem erzeugen -lassen, indem Sie den Befehl @command{guix system shepherd-graph} benutzen -(siehe @ref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @code{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by -passing it lists of @code{} objects. - -@deftp {Datentyp} shepherd-service -Der Datentyp, der einen von Shepherd verwalteten Dienst repräsentiert. - -@table @asis -@item @code{provision} -Diese Liste von Symbolen gibt an, was vom Dienst angeboten wird. - -Das bedeutet, es sind die Namen, die an @command{herd start}, @command{herd -status} und ähnliche Befehle übergeben werden können (siehe @ref{Invoking -herd,,, shepherd, The GNU Shepherd Manual}). Siehe @ref{Slots of services, -the @code{provides} slot,, shepherd, The GNU Shepherd Manual} für Details. - -@item @code{requirements} (Vorgabe: @code{'()}) -Eine Liste von Symbolen, die angegeben, von welchen anderen -Shepherd-Diensten dieser hier abhängt. - -@item @code{respawn?} (Vorgabe: @code{#t}) -Ob der Dienst neu gestartet werden soll, nachdem er gestoppt wurde, zum -Beispiel wenn der ihm zu Grunde liegende Prozess terminiert wird. - -@item @code{start} -@itemx @code{stop} (Vorgabe: @code{#~(const #f)}) -Die Felder @code{start} und @code{stop} beziehen sich auf Shepherds -Funktionen zum Starten und Stoppen von Prozessen (siehe @ref{Service De- and -Constructors,,, shepherd, The GNU Shepherd Manual}). Sie enthalten -G-Ausdrücke, die in eine Shepherd-Konfigurationdatei umgeschrieben werden -(siehe @ref{G-Ausdrücke}). - -@item @code{actions} (Vorgabe: @code{'()}) -@cindex Aktionen, bei Shepherd-Diensten -Dies ist eine Liste von @code{shepherd-action}-Objekten (siehe unten), die -vom Dienst zusätzlich unterstützte @dfn{Aktionen} neben den Standardaktionen -@code{start} und @code{stop} angeben. Hier aufgeführte Aktionen werden als -@command{herd}-Unterbefehle verfügbar gemacht: - -@example -herd @var{Aktion} @var{Dienst} [@var{Argumente}@dots{}] -@end example - -@item @code{Dokumentation} -Eine Zeichenkette zur Dokumentation, die angezeigt wird, wenn man dies -ausführt: - -@example -herd doc @var{Dienstname} -@end example - -where @var{service-name} is one of the symbols in @code{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @code{%default-modules}) -Dies ist die Liste der Module, die in den Sichtbarkeitsbereich geladen sein -müssen, wenn @code{start} und @code{stop} ausgewertet werden. - -@end table -@end deftp - -@deftp {Datentyp} shepherd-action -Dieser Datentyp definiert zusätzliche Aktionen, die ein Shepherd-Dienst -implementiert (siehe oben). - -@table @code -@item name -Die Aktion bezeichnendes Symbol. - -@item Dokumentation -Diese Zeichenkette ist die Dokumentation für die Aktion. Sie können sie -sehen, wenn Sie dies ausführen: - -@example -herd doc @var{Dienst} action @var{Aktion} -@end example - -@item procedure -Dies sollte ein G-Ausdruck sein, der zu einer mindestens ein Argument -nehmenden Prozedur ausgewertet wird. Das Argument ist der »running«-Wert des -Dienstes (siehe @ref{Slots of services,,, shepherd, The GNU Shepherd -Manual}). -@end table - -Das folgende Beispiel definiert eine Aktion namens @code{sag-hallo}, die den -Benutzer freundlich begrüßt: - -@example -(shepherd-action - (name 'sag-hallo) - (documentation "Sag Hallo!") - (procedure #~(lambda (running . args) - (format #t "Hallo, Freund! Argumente: ~s\n" - args) - #t))) -@end example - -Wenn wir annehmen, dass wir die Aktion zum Dienst @code{beispiel} -hinzufügen, können Sie Folgendes ausführen: - -@example -# herd sag-hallo beispiel -Hallo, Freund! Argumente: () -# herd sag-hallo beispiel a b c -Hallo, Freund! Argumente: ("a" "b" "c") -@end example - -Wie Sie sehen können, ist das eine sehr ausgeklügelte Art, Hallo zu -sagen. Siehe @ref{Service Convenience,,, shepherd, The GNU Shepherd Manual} -für mehr Informationen zu Aktionen. -@end deftp - -@defvr {Scheme-Variable} shepherd-root-service-type -Der Diensttyp für den Shepherd-»Wurzeldienst« — also für PID@tie{}1. - -Dieser Diensttyp stellt das Ziel für Diensterweiterungen dar, die -Shepherd-Dienste erzeugen sollen (siehe @ref{Diensttypen und Dienste} für -ein Beispiel). Jede Erweiterung muss eine Liste von -@code{}-Objekten übergeben. -@end defvr - -@defvr {Scheme-Variable} %shepherd-root-service -Dieser Dienst repräsentiert 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 Sicherheitslücken -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 -@code{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 @code{bash-fixed} -instead of @code{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 (@code{bash-fixed} and @code{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 . -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 baut auf dem @uref{http://nixos.org/nix/, Nix-Paketverwaltungsprogramm} -auf, das von Eelco Dolstra entworfen und entwickelt wurde, mit Beiträgen von -anderen Leuten (siehe die Datei @file{nix/AUTHORS} in Guix). Nix hat für die -funktionale Paketverwaltung die Pionierarbeit geleistet und noch nie -dagewesene Funktionalitäten vorangetrieben wie transaktionsbasierte -Paketaktualisierungen und die Rücksetzbarkeit selbiger, eigene Paketprofile -für jeden Nutzer und referenziell transparente Erstellungsprozesse. Ohne -diese Arbeit gäbe es Guix nicht. - -Die Nix-basierten Software-Distributionen Nixpkgs und NixOS waren auch eine -Inspiration für Guix. - -GNU@tie{}Guix ist selbst das Produkt kollektiver Arbeit mit Beiträgen durch -eine Vielzahl von Leuten. Siehe die Datei @file{AUTHORS} in Guix für mehr -Informationen, wer diese wunderbaren Menschen sind. In der Datei -@file{THANKS} finden Sie eine Liste der Leute, die uns geholfen haben, indem -Sie Fehler gemeldet, sich um unsere Infrastruktur gekümmert, künstlerische -Arbeit und schön gestaltete Themen beigesteuert, Vorschläge gemacht und noch -vieles mehr getan haben — vielen Dank! - - -@c ********************************************************************* -@node GNU-Lizenz für freie Dokumentation -@appendix GNU-Lizenz für freie Dokumentation -@cindex Lizenz, GNU-Lizenz für freie Dokumentation -@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: diff --git a/doc/guix.es.texi b/doc/guix.es.texi deleted file mode 100644 index ece6073f99..0000000000 --- a/doc/guix.es.texi +++ /dev/null @@ -1,26015 +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.es.info -@documentencoding UTF-8 -@documentlanguage es -@frenchspacing on -@settitle Manual de referencia de GNU Guix -@c %**end of header - -@include version-es.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.es.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, -2019 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, 2019 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@* Copyright @copyright{} 2019 Miguel Ángel Arruga Vivas -(traducción)@* - -Se garantiza el permiso de copia, distribución y/o modificación de este -documento bajo los términos de la licencia de documentación libre de GNU -(GNU Free Documentation License), versión 1.3 o cualquier versión posterior -publicada por la Free Software Foundation; sin secciones invariantes, sin -textos de cubierta delantera ni trasera. Una copia de la licencia está -incluida en la sección titulada ``GNU Free Documentation License''. -@end copying - -@dircategory Administración del sistema -@direntry -* Guix: (guix.es). Gestión del software instalado y la - configuración del sistema. -* guix package: (guix.es)Llamar a guix package. Instalación, borrado y - actualización de paquetes. -* guix gc: (guix.es)Llamar a guix gc. Reclamar espacio de disco sin usar. -* guix pull: (guix.es)Llamar a guix pull. Actualización de la lista - disponible de paquetes. -* guix system: (guix.es)Llamar a guix system. Gestión de la configuración - del sistema operativo. -@end direntry - -@dircategory Desarrollo de software -@direntry -* guix environment: (guix.es)Llamar a guix environment. Construcción de - entornos de - desarrollo con - Guix. -* guix build: (guix.es)Llamar a guix build. Construcción de paquetes. -* guix pack: (guix.es)Llamar a guix pack. Creación de empaquetados - binarios. -@end direntry - -@titlepage -@title Manual de referencia de GNU Guix -@subtitle Uso del gestor de paquetes funcional GNU Guix. -@author Las desarrolladoras de GNU Guix - -@page -@vskip 0pt plus 1filll -Edición @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -Este documento describe GNU Guix versión @value{VERSION}, una herramienta -funcional de gestión de paquetes escrita para el sistema GNU. - -@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. -Este manual también está disponible en Inglés (@pxref{Top,,, guix, GNU Guix -Reference Manual}), en Francés (@pxref{Top,,, guix.fr, Manuel de référence -de GNU Guix}) y Alemán (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU -Guix}). Si quiere traducirlo a su lengua nativa, considere unirse a -@uref{https://translationproject.org/domain/guix-manual.html, Translation -Project}. - -@menu -* Introducción:: ¿Qué es esto de Guix? -* Instalación:: Instalar Guix. -* Instalación del sistema:: Instalar el sistema operativo completo. -* Gestión de paquetes:: Instalación de paquetes, actualización, etc. -* Desarrollo:: Desarrollo de software asistido por Guix -* Interfaz programática:: Uso de Guix en Scheme. -* Utilidades:: Órdenes de gestión de paquetes. -* Configuración del sistema:: Configurar el sistema operativo. -* Documentación:: Navegar por los manuales de usuaria del - software. -* Instalación de ficheros de depuración:: Alimentación del depurador. -* Actualizaciones de seguridad:: Desplegar correcciones de seguridad - rápidamente. -* Lanzamiento inicial:: GNU/Linux construido de cero. -* Transportar:: Adaptación para otra plataforma o núcleo. -* Contribuir:: ¡Se necesita su ayuda! - -* Reconocimientos:: ¡Gracias! -* Licencia de documentación libre GNU:: La licencia de este manual. -* Índice de conceptos:: Conceptos. -* Índice programático:: Tipos de datos, funciones y variables. - -@detailmenu - --- La lista detallada de nodos --- - - - -Introducción - - - -* La forma de gestión de software de Guix:: Qué es especial. -* Distribución GNU:: Los paquetes y herramientas. - -Instalación - - - -* Instalación binaria:: ¡Poner Guix en funcionamiento en nada de - tiempo! -* Requisitos:: Software necesario para construir y ejecutar - Guix. -* Ejecución de la batería de pruebas:: Probar Guix. -* Preparación del daemon:: Preparar el entorno del daemon de - construcción. -* Invocación de guix-daemon:: Ejecutar el daemon de construcción. -* Configuración de la aplicación:: Configuración específica de la - aplicación. - -Preparación del daemon - - - -* Configuración del entorno de construcción:: Preparar el entorno aislado - de construcción. -* Configuración de delegación del daemon:: Delegar construcciones a - máquinas remotas. -* Soporte de SELinux:: Uso de una política SELinux para el daemon. - -Instalación del sistema - - - -* Limitaciones:: Qué puede esperar. -* Consideraciones sobre el hardware:: Hardware soportado. -* Instalación desde memoria USB y DVD:: Preparar el medio de instalación. -* Preparación para la instalación:: Red, particionado, etc. -* Instalación gráfica guiada:: Instalación gráfica fácil. -* Instalación manual:: Instalación manual para artistas del teclado. -* Tras la instalación del sistema:: Cuando la instalación ha finalizado - satisfactoriamente. -* Instalación de Guix en una máquina virtual:: El patio de recreo del - sistema Guix. -* Construcción de la imagen de instalación:: Cómo esto llega a ser. - -Instalación manual - - - -* Distribución de teclado y red y particionado:: Configuración inicial. -* Procedimiento de instalación:: Instalación. - -Gestión de paquetes - - - -* Características:: Cómo Guix dará brillo a su vida. -* Invocación de guix package:: Instalación de paquetes, borrado, etc. -* Sustituciones:: Descargar binarios pre-construidos. -* Paquetes con múltiples salidas:: Un único paquete de fuentes, - múltiples salidas. -* Invocación de guix gc:: Ejecutar el recolector de basura. -* Invocación de guix pull:: Obtener la última versión de Guix y la - distribución. -* Canales:: Personalizar el recolector de basura. -* Inferiores:: Interactuar con otra revisión de Guix. -* Invocación de guix describe:: Muestra información acerca de su - revisión de Guix. -* Invocación de guix archive:: Exportar e importar ficheros del almacén. - -Sustituciones - - - -* Servidor oficial de sustituciones.:: Una fuente particular de - sustituciones. -* Autorización de servidores de sustituciones:: Cómo habilitar o - deshabilitar - sustituciones. -* Verificación de sustituciones:: Cómo verifica las sustituciones Guix. -* Configuración de la pasarela.:: Cómo obtener sustituciones a través de - una pasarela. -* Fallos en las sustituciones:: Qué pasa cuando una sustitución falla. -* Sobre la confianza en binarios:: ¿Cómo puede usted confiar en esa masa - informe de datos binarios? - -Desarrollo - - - -* Invocación de guix environment:: Configurar entornos de desarrollo. -* Invocación de guix pack:: Creación de empaquetados de software. - -Interfaz programática - - - -* Módulos de paquetes:: Paquetes bajo el punto de vista del - programador. -* Definición de paquetes:: Definir nuevos paquetes. -* Sistemas de construcción:: Especificar como se construyen los paquetes. -* El almacén:: Manipular el almacén de paquetes. -* Derivaciones:: Interfaz de bajo nivel de las derivaciones de - los paquetes. -* La mónada del almacén:: Interfaz puramente funcional del almacén. -* Expresiones-G:: Manipular expresiones de construcción. -* Invocación de guix repl:: Enredar con Guix interactivamente. - -Definición de paquetes - - - -* Referencia de ``package'':: El tipo de datos de los paquetes. -* Referencia de ``origin'':: El tipo de datos de orígenes. - -Utilidades - - - -* Invocación de guix build:: Construir paquetes desde la línea de - órdenes. -* Invocación de guix edit:: Editar las definiciones de paquetes. -* Invocación de guix download:: Descargar un fichero e imprimir su hash. -* Invocación de guix hash:: Calcular el hash criptográfico de un fichero. -* Invocación de guix import:: Importar definiciones de paquetes. -* Invocación de guix refresh:: Actualizar definiciones de paquetes. -* Invocación de guix lint:: Encontrar errores en definiciones de paquetes. -* Invocación de guix size:: Perfilar el uso del disco. -* Invocación de guix graph:: Visualizar el grafo de paquetes. -* Invocación de guix publish:: Compartir sustituciones. -* Invocación de guix challenge:: Poner a prueba servidores de - sustituciones. -* Invocación de guix copy:: Copiar a y desde un almacén remoto. -* Invocación de guix container:: Aislamiento de procesos. -* Invocación de guix weather:: Comprobar la disponibilidad de - sustituciones. -* Invocación de guix processes:: Enumerar los procesos cliente. - -Invocación de @command{guix build} - - - -* Opciones comunes de construcción:: Opciones de construcción para la - mayoría de órdenes. -* Opciones de transformación de paquetes:: Crear variantes de paquetes. -* Opciones de construcción adicionales:: Opciones específicas de 'guix - build'. -* Depuración de fallos de construcción:: Experiencia de empaquetamiento - en la vida real. - -Configuración del sistema - - - -* Uso de la configuración del sistema:: Personalizar su sistema GNU. -* Referencia de ``operating-system'':: Detalle de las declaraciones de - sistema operativo. -* Sistemas de ficheros:: Configurar el montaje de sistemas de ficheros. -* Dispositivos traducidos:: Procesamiento extra de dispositivos de bloques. -* Cuentas de usuaria:: Especificar las cuentas de usuaria. -* Distribución de teclado:: Cómo interpreta el sistema las pulsaciones - del teclado. -* Localizaciones:: Configuración de idioma y convenciones - culturales. -* Servicios:: Especificar los servicios del sistema. -* Programas con setuid:: Programas que se ejecutan con privilegios de - root. -* Certificados X.509:: Verificar servidores HTTPS. -* Selector de servicios de nombres:: Configurar el selector de servicios de - nombres de libc. -* Disco en RAM inicial:: Arranque de Linux-Libre. -* Configuración del gestor de arranque:: Configurar el gestor de arranque. -* Invocación de guix system:: Instanciar una configuración del sistema. -* Ejecutar Guix en una máquina virtual:: Cómo ejecutar el sistema Guix en - una máquina virtual. -* Definición de servicios:: Añadir nuevas definiciones de servicios. - -Servicios - - - -* Servicios base:: Servicios esenciales del sistema. -* Ejecución de tareas programadas:: El servicio mcron. -* Rotación de logs:: El servicio rottlog. -* Servicios de red:: Configuración de red, daemon SSH, etc. -* Sistema X Window:: Interfaz gráfica. -* Servicios de impresión:: Soporte de impresoras locales y remotas. -* Servicios de escritorio:: D-Bus y servicios de escritorio. -* Servicios de sonido:: Servicios de ALSA y Pulseaudio. -* Servicios de bases de datos:: Bases de datos SQL, almacenes de - clave-valor, etc. -* Servicios de correo:: IMAP, POP3, SMTP y todo eso. -* Servicios de mensajería:: Servicios de mensajería. -* Servicios de telefonía:: Servicios de telefonía. -* Servicios de monitorización:: Servicios de monitorización. -* Servicios Kerberos:: Servicios Kerberos. -* Servicios Web:: Servidores Web. -* Servicios de certificados:: Certificados TLS via Let's Encrypt. -* Servicios DNS:: Demonios DNS. -* Servicios VPN:: Demonios VPN. -* Sistema de ficheros en red:: Servicios relacionados con NFS. -* Integración continua:: El servicio Cuirass. -* Servicios de gestión de energía:: Extender la vida de la batería. -* Servicios de audio:: El MPD. -* Servicios de virtualización:: Servicios de virtualización. -* Servicios de control de versiones:: Proporcionar acceso remoto a - repositorios Git. -* Servicios de juegos:: Servidores de juegos. -* Servicios misceláneos:: Otros servicios. - -Definición de servicios - - - -* Composición de servicios:: El modelo para la composición de servicios. -* Tipos de servicios y servicios:: Tipos y servicios -* Referencia de servicios:: Referencia de la API. -* Servicios de Shepherd:: Un tipo de servicio particular. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Introducción -@chapter Introducción - -@cindex propósito -GNU Guix@footnote{``Guix'' se pronuncia tal y como se escribe en castellano, -``gi:ks'' en el alfabeto fonético internacional (IPA).} es una herramienta -de gestión de paquetes y una distribucion del sistema GNU. Guix facilita a -usuarias sin privilegios la instalación, actualización o borrado de paquetes -de software, la vuelta a un conjunto de paquetes previo atómicamente, la -construcción de paquetes desde las fuentes, y ayuda de forma general en la -creación y mantenimiento de entornos software. - -@cindex Sistema Guix -@cindex GuixSD, ahora sistema Guix -@cindex Distribución de Sistema Guix, ahora sistema Guix -Puede instalar GNU@tie{}Guix sobre un sistema GNU/Linux existente, donde -complementará las herramientas disponibles sin interferencias -(@pxref{Instalación}), o puede usarse como un sistema operativo en sí -mismo, el @dfn{sistema@tie{}Guix}@footnote{Solíamos referirnos al sistema -Guix como ``Distribución de sistema Guix'' o ``GuixSD''. Ahora consideramos -que tiene más sentido agrupar todo bajo la etiqueta ``Guix'' ya que, después -de todo, el sistema Guix está inmediatamente disponible a través de la orden -@command{guix system}, ¡incluso cuando usa una distribución distinta por -debajo!}. @xref{Distribución GNU}. - -@menu -* La forma de gestión de software de Guix:: Qué es especial. -* Distribución GNU:: Los paquetes y herramientas. -@end menu - -@node La forma de gestión de software de Guix -@section La forma de gestión de software de Guix - -@cindex interfaces de usuaria -Guix proporciona una interfaz de gestión de paquetes de línea de ordenes -(@pxref{Gestión de paquetes}), un conjunto de utilidades de línea de órdenes -(@pxref{Utilidades}), así como interfaces programáticas Scheme -(@pxref{Interfaz programática}). -@cindex daemon de construcción -Su @dfn{daemon de construcción} es responsable de la construcción de -paquetes en delegación de las usuarias (@pxref{Preparación del daemon}) y de -la descarga de binarios preconstruidos de fuentes autorizadas -(@pxref{Sustituciones}) - -@cindex extensibilidad de la distribución -@cindex personalización, de paquetes -Guix incluye definiciones de paquetes para muchos paquetes GNU y no-GNU, -todos los cuales @uref{https://www.gnu.org/philosophy/free-sw.html, respetan -la libertad de computación de la usuaria}. Es @emph{extensible}: las -usuarias pueden escribir sus propias definiciones de paquetes -(@pxref{Definición de paquetes}) y hacerlas disponibles como módulos -independientes de paquetes (@pxref{Módulos de paquetes}). También es -@emph{personalizable}: las usuarias pueden @emph{derivar} definiciones de -paquetes especializadas de las existentes, inclusive desde la línea de -órdenes (@pxref{Opciones de transformación de paquetes}). - -@cindex gestión de paquetes funcional -@cindex aislamiento -En su implementación, Guix utiliza la disciplina de @dfn{gestión de paquetes -funcional} en la que Nix fue pionero (@pxref{Reconocimientos}). En Guix, el -proceso de construcción e instalación es visto como una @emph{función}, en -el sentido matemático. Dicha función toma entradas, como los guiones de -construcción, un compilador, unas bibliotecas y devuelve el paquete -instalado. Como función pura, su resultado únicamente depende de sus -entradas---por ejemplo, no puede hacer referencia a software o guiones que -no fuesen pasados explícitamente como entrada. Una función de construcción -siempre produce el mismo resultado cuando se le proporciona un conjunto de -entradas dado. No puede modificar el entorno del sistema que la ejecuta de -ninguna forma; por ejemplo, no puede crear, modificar o borrar archivos -fuera de sus directorios de construcción e instalación. Esto se consigue -ejecutando los procesos de construcción en entornos aislados (o -@dfn{contenedores}), donde únicamente sus entradas explícitas son visibles. - -@cindex almacén -El resultado de las funciones de construcción de paquetes es @dfn{almacenado -en la caché} en el sistema de ficheros, en un directorio especial llamado -@dfn{el almacén} (@pxref{El almacén}). Cada paquete se instala en un -directorio propio en el almacén---por defecto, bajo @file{/gnu/store}. El -nombre del directorio contiene el hash de todas las entradas usadas para -construir el paquete; por tanto, cambiar una entrada resulta en un nombre de -directorio distinto. - -Esta aproximación es el cimiento de las avanzadas características de Guix: -capacidad para la actualización transaccional y vuelta-atrás de paquetes, -instalación en el ámbito de la usuaria y recolección de basura de paquetes -(@pxref{Características}). - - -@node Distribución GNU -@section Distribución GNU - -@cindex Sistema Guix -Guix viene con una distribución del sistema GNU consistente en su totalidad -de software libre@footnote{El término ``libre'' aquí se refiere a la -@url{http://www.gnu.org/philosophy/free-sw.html,libertad proporcionada a las -usuarias de dicho software}.}. La distribución puede instalarse -independientemente (@pxref{Instalación del sistema}), pero también es posible -instalar Guix como un gestor de paquetes sobre un sistema GNU/Linux -existente (@pxref{Instalación}). Para distinguir entre las dos opciones, -nos referimos a la distribución independiente como el sistema@tie{}Guix. - -La distribución proporciona paquetes principales de GNU como GNU libc, GCC y -Binutils, así como muchas aplicaciones GNU y no-GNU. La lista completa de -paquetes disponibles puede navegarse -@url{http://www.gnu.org/software/guix/packages,en línea} o ejecutando -@command{guix package} (@pxref{Invocación de guix package}): - -@example -guix package --list-available -@end example - -Nuestro objetivo es proporcionar una distribución práctica con 100% software -libre basada en Linux y otras variantes de GNU, con un enfoque en la -promoción y la alta integración de componentes GNU, y un énfasis en -programas y herramientas que ayuden a las usuarias a ejercitar esa libertad. - -Actualmente hay paquetes disponibles para las siguientes plataformas: - -@table @code - -@item x86_64-linux -arquitectura @code{x86_64} de Intel/AMD, núcleo Linux-Libre; - -@item i686-linux -arquitectura de 32-bits Intel (IA32), núcleo Linux-Libre; - -@item armhf-linux -arquitectura ARMv7-A con coma flotante hardware, Thumb-2 y NEON, usando la -interfaz binaria de aplicaciones (ABI) EABI con coma flotante hardware, y el -núcleo Linux-Libre. - -@item aarch64-linux -procesadores de 64-bits ARMv8 little-endian, núcleo Linux-Libre. Está -actualmente en una fase experimental, con soporte -limitado. @xref{Contribuir}, para cómo ayudar. - -@item mips64el-linux -procesadores MIPS 64-bits little-endian, específicamente las series -Loongson, n32 ABI, y núcleo Linux-Libre. - -@end table - -Con el sistema@tie{}Guix, @emph{declara} todos los aspectos de la -configuración del sistema y Guix se hace cargo de instanciar la -configuración de manera transaccional, reproducible y sin estado global -(@pxref{Configuración del sistema}). El sistema Guix usa el núcleo Linux-libre, -el sistema de inicialización Shepherd (@pxref{Introducción,,, shepherd, The -GNU Shepherd Manual}), las conocidas utilidades y herramientas de -compilación GNU, así como el entorno gráfico o servicios del sistema de su -elección. - -El sistema Guix está disponible en todas las plataformas previas excepto -@code{mips64el-linux}. - -@noindent -Para información sobre el transporte a otras arquitecturas o núcleos, -@pxref{Transportar}. - -La construcción de esta distribución es un esfuerzo cooperativo, ¡y esta -invitada a unirse! @xref{Contribuir}, para información sobre cómo puede -ayudar. - - -@c ********************************************************************* -@node Instalación -@chapter Instalación - -@cindex instalar Guix - -@quotation Nota -Recomendamos el uso de este @uref{https://git.savannah.gnu.org/cgit/guix." -"git/plain/etc/guix-install.sh, guión de shell de instalación} para instalar -Guix sobre un sistema GNU/Linux en ejecución, de aquí en adelante referido -como una @dfn{distribución distinta}.@footnote{Esta sección está dedicada a -la instalación del gestor de paquetes, que puede realizarse sobre un sistema -GNU/Linux ya en ejecución. Si, en vez de eso, desdea instalar el sistema -operativo GNU completo, @pxref{Instalación del sistema}.} El guión automatiza la -descarga, instalación y configuración inicial de Guix. Debe ejecutarse como -la usuaria de administración root. -@end quotation - -@cindex distribución distinta -@cindex directorios relacionados con una distribución distinta -Cuando está instalado sobre una distribución distinta, GNU@tie{}Guix -complementa las herramientas disponibles sin interferencias. Sus datos -radican exclusivamente en dos directorios, normalmente @file{/gnu/store} y -@file{/var/guix}; otros ficheros en su sistema, como @file{/etc}, permanecen -intactos. - -Una vez instalado, Guix puede ser actualizado ejecutando @command{guix pull} -(@pxref{Invocación de guix pull}. - -Si prefiere realizar los pasos de instalación manualmente o desea -personalizarlos, puede encontrar útiles las siguientes -instrucciones. Describen los requisitos de software de Guix, así como su -instalación manual y la preparación para su uso. - -@menu -* Instalación binaria:: ¡Poner Guix en funcionamiento en nada de - tiempo! -* Requisitos:: Software necesario para construir y ejecutar - Guix. -* Ejecución de la batería de pruebas:: Probar Guix. -* Preparación del daemon:: Preparar el entorno del daemon de - construcción. -* Invocación de guix-daemon:: Ejecutar el daemon de construcción. -* Configuración de la aplicación:: Configuración específica de la - aplicación. -@end menu - -@node Instalación binaria -@section Instalación binaria - -@cindex instalar Guix desde binarios -@cindex guión del instalador -Esta sección describe cómo instalar Guix en un sistema arbitrario desde un -archivador autocontenido que proporciona los binarios para Guix y todas sus -dependencias. Esto es normalmente más rápido que una instalación desde las -fuentes, la cual es descrita en las siguientes secciones. El único requisito -es tener GNU@tie{}tar y Xz. - -La instalación consiste más o menos en los siguientes pasos: - -@enumerate -@item -@cindex descargar el binario de Guix -Descargue el archivador con los binarios de -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{sistema}.tar.xz}, -donde @var{sistema} es @code{x86_64-linux} para una máquina @code{x86_64} -que ejecute el núcleo Linux, etcétera. - -@c The following is somewhat duplicated in ``System Installation''. -Asegurese de descargar el fichero @file{.sig} asociado y de verificar la -autenticidad del archivador con él, más o menos así: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{sistema}.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.@var{sistema}.tar.xz.sig -@end example - -Si la orden falla porque no dispone de la clave pública necesaria, entonces -ejecute esta otra orden para importarla: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -y vuelva a ejecutar la orden @code{gpg --verify}. - -@item -Ahora necesita convertirse en la usuaria @code{root}. Dependiendo de su -distribución, puede que tenga que ejecutar @code{su -} o @code{sudo --i}. Como @code{root}, ejecute: - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{sistema}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -Esto crea @file{/gnu/store} (@pxref{El almacén}) y @file{/var/guix}. El -último contiene un perfil listo para usar para @code{root} (vea el siguiente -paso). - -@emph{No} extraiga el archivador en un sistema Guix ya funcionando ya que -sobreescribiría sus propios ficheros esenciales. - -La opción @code{--warning=no-timestamp} asegura que GNU@tie{}tar no emite -avisos sobre ``marcas de tiempo imposibles'' (dichos avisos eran emitidos -por GNU@tie{}tar 1.26 y anteriores; las versiones recientes están -bien). Parten del hecho de que todos los ficheros en el archivador tienen su -tiempo de modificación fijado a cero (que significa el 1 de enero de -1970). Esto es hecho voluntariamente para asegurarse de que el contenido del -archivador es independiente de su fecha de creación, haciendolo por tanto -reproducible. - -@item -Ponga disponible el perfil en @file{~root/.config/guix/current}, que es -donde @command{guix pull} instalará las actualizaciones (@pxref{Invocación de guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Cargue @file{etc/profile} para aumentar @code{PATH} y otras variables de -entorno relevantes: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Cree el grupo y las cuentas de usuaria para las usuarias de construcción -como se explica a continuación (@pxref{Configuración del entorno de construcción}). - -@item -Ejecute el daemon, y configurelo para iniciarse automáticamente al arranque. - -Si su distribución anfitriona usa el sistema de inicio systemd, puede -conseguirlo con estas órdenes: - -@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 - -Si su distribución anfitriona usa el sistema de inicio Upstart: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -En otro caso, todavía puede iniciar el daemon manualmente con: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Haga accesible la orden @command{guix} a otras usuarias de la máquina, por -ejemplo con: - -@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 también una buena idea poner disponible la versión Info de este manual -ahí: - -@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 - -De este modo, asumiendo que @file{/usr/local/share/info} está en la ruta de -búsqueda, ejecutar @command{info guix.es} abrirá este manual (@pxref{Other -Info Directories,,, texinfo, GNU Texinfo}, para más detalles sobre cómo -cambiar la ruta de búsqueda de Info). - -@item -@cindex sustituciones, autorización de las mismas -Para usar sustituciones de @code{@value{SUBSTITUTE-SERVER}} o uno de sus -espejos (@pxref{Sustituciones}), debe autorizarlas: - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@item -Cada usuaria puede necesitar dar algunos pasos adicionales para prepar su -entorno de Guix para el uso, @pxref{Configuración de la aplicación}. -@end enumerate - -Voilà, ¡la instalación está completa! - -Puede confirmar que Guix está funcionando instalando un paquete de ejemplo -en su perfil de root: - -@example -# guix package -i hello -@end example - -El paquete @code{guix} debe permanecer disponible en el perfil de -@code{root}, o podría verse sujeto a la recolección de basura---en cuyo caso -se encontraría seriamente lastrada por la falta de la orden -@command{guix}. En otras palabras, no borre @code{guix} ejecutando -@code{guix package -r guix}. - -El archivador de la instalación binaria puede ser (re)producido y verificado -simplemente ejecutando la siguiente orden en el árbol de fuentes de Guix: - -@example -make guix-binary.@var{sistema}.tar.xz -@end example - -@noindent -...@: que a su vez ejecuta: - -@example -guix pack -s @var{sistema} --localstatedir \ - --profile-name=current-guix guix -@end example - -@xref{Invocación de guix pack}, para más información sobre esta útil herramienta. - -@node Requisitos -@section Requisitos - -Esta sección enumera los requisitos para construir Guix desde las -fuentes. El procedimiento de construcción de Guix es el mismo que el de otro -software GNU, y no está cubierto aquí. Por favor, eche un vistazo a los -ficheros @file{README} y @file{INSTALL} en el árbol de fuentes de Guix para -obtener detalles adicionales. - -@cindex página web oficial -GNU Guix está disponible para descarga desde su página web en -@url{http://www.gnu.org/software/guix/}. - -GNU Guix depende de los siguientes paquetes: - -@itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, versión 2.2.x; -@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, versión -0.1.0 o posterior; -@item -@uref{http://gnutls.org/, GnuTLS}, específicamente su API 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}, -versión 0.1.0 o posterior; -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, de agosto de 2017 -o posterior; -@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 - -Las siguientes dependencias son opcionales: - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Las características de delegación de construcciones (@pxref{Configuración de delegación del daemon}) y de @command{guix copy} (@pxref{Invocación de guix copy}) dependen de -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, versión -0.10.2 o posterior. - -@item -Cuando @url{http://www.bzip.org, libbz2} está disponible, @command{guix -daemon} puede usarla para comprimir los log de construcción. -@end itemize - -A menos que se pasase @code{--disable-daemon} a @command{configure}, los -siguientes paquetes también son necesarios: - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}; -@item @url{http://sqlite.org, SQLite 3}; -@item @url{http://gcc.gnu.org, g++ de GCC} con soporte para el -estándar C++11 -@end itemize - -@cindex directorio de estado -Cuando se configura Guix en un sistema que ya tiene una instalación de Guix, -asegurese de especificar el mismo directorio de estado que el de la -instalación existente usando la opción @code{--localstatedir} al guión -@command{configure} (@pxref{Directory Variables, @code{localstatedir},, -standards, GNU Coding Standards}). El guión @command{configure} le proteje -ante una mala configuración no deseada de @var{localstatedir} de modo que no -pueda corromper inadvertidamente su almacén (@pxref{El almacén}). - -@cindex Nix, compatibilidad -Cuando está disponible una instalación en funcionamiento del -@url{http://nixos.org/nix/, gestor de paquetes Nix}, puede a su vez -configurar Guix con @code{--disable-daemon}. En ese caso, Nix reemplaza las -tres dependencias anteriores. - -Guix es compatible con Nix, así que es posible compartir el mismo almacén -entre ambos. Para hacerlo debe pasar a @command{configure} no solo el mismo -valor de @code{--with-store-dir}, sino también el mismo valor de -@code{--localstatedir}. El último es esencial debido a que especifica la -base de datos donde se encuentran almacenados los metadatos del almacén, -entre otras cosas. Los valores predeterminados para Nix son -@code{--with-store-dir=/nix/store} y @code{--localstatedir=/nix/var}. Fíjese -que no se requiere @code{--disable-daemon} si su objetivo es compartir el -almacén con Nix. - -@node Ejecución de la batería de pruebas -@section Ejecución de la batería de pruebas - -@cindex batería de pruebas -Después de una ejecución exitosa de @command{configure} y @code{make}, es -una buena idea ejecutar la batería de pruebas. Puede ayudar a encontrar -problemas con la configuración o el entorno, o errores en el mismo Guix---e -informar de fallos en las pruebas es realmente una buena forma de ayudar a -mejorar el software. Para ejecutar la batería de pruebas, teclee: - -@example -make check -@end example - -Los casos de prueba pueden ejecutarse en paralelo: puede usar la opción -@code{-j} de GNU@tie{}make para acelerar las cosas. La primera ejecución -puede tomar algunos minutos en una máquina reciente; las siguientes -ejecuciones serán más rápidas puesto que el almacén creado para las pruebas -ya tendrá varias cosas en la caché. - -Tambien es posible ejecutar un subconjunto de las pruebas definiendo la -variable de makefile @code{TESTS} como en el ejemplo: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -Por defecto, los resultados de las pruebas se muestran a nivel de -fichero. Para ver los detalles de cada caso de prueba individual, es posible -definir la variable de makefile @code{SCM_LOG_DRIVER_FLAGS} como en el -ejemplo: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -En caso de fallo, le rogamos que envíe un correo a @email{bug-guix@@gnu.org} -y adjunte el fichero @file{test-suite.log}. Por favor, especifique la -versión de Guix usada así como los números de versión de las dependencias -(@pxref{Requisitos}) en su mensaje. - -Guix también viene como una batería de pruebas del sistema completo que -prueban instancias completas del sistema Guix. Se puede ejecutar únicamente -en sistemas donde Guix ya está instalado, usando: - -@example -make check-system -@end example - -@noindent -o, de nuevo, definiendo @code{TESTS} para seleccionar un subconjunto de las -pruebas a ejecutar: - -@example -make check-system TESTS="basic mcron" -@end example - -Estas pruebas de sistema están definidas en los módulos @code{(gnu tests -@dots{})}. Funcionan ejecutando el sistema operativo con una instrumentación -ligera en una máquina virtual (VM). Pueden ser computacionalmente intensivas -o bastante baratas, dependiendo de si hay sustituciones disponibles para sus -dependencias (@pxref{Sustituciones}). Algunas requieren mucho espacio de -almacenamiento para alojar las imágenes de la máquina virtual. - -De nuevo, en caso de fallos en las pruebas, le rogamos que envíe a -@email{bug-guix@@gnu.org} todos los detalles. - -@node Preparación del daemon -@section Preparación del daemon - -@cindex daemon -Operaciones como la construcción de un paquete o la ejecución del recolector -de basura son realizadas por un proceso especializado, el @dfn{daemon de -construcción}, en delegación de sus clientes. Únicamente el daemon puede -acceder al almacén y su base de datos asociada. Por tanto, cualquier -operación que manipula el almacén se realiza a través del daemon. Por -ejemplo, las herramientas de línea de órdenes como @command{guix package} y -@command{guix build} se comunican con el daemon (@i{via} llamadas a -procedimientos remotos) para indicarle qué hacer. - -Las siguientes secciones explican cómo preparar el entorno del daemon de -construcción. Véase tambien @ref{Sustituciones}, para información sobre cómo -permitir al daemon descargar binarios pre-construidos. - -@menu -* Configuración del entorno de construcción:: Preparar el entorno aislado - de construcción. -* Configuración de delegación del daemon:: Delegar construcciones a - máquinas remotas. -* Soporte de SELinux:: Uso de una política SELinux para el daemon. -@end menu - -@node Configuración del entorno de construcción -@subsection Configuración del entorno de construcción - -@cindex entorno de construcción -En una configuración multiusuaria estándar, Guix y su daemon---el programa -@command{guix-daemon}---son instalados por la administradora del sistema; -@file{/gnu/store} pertenece a @code{root} y @command{guix-daemon} se ejecuta -como @code{root}. Usuarias sin privilegios pueden usar las herramientas de -Guix para construir paquetes o acceder al almacén de otro modo, y el daemon -lo hará en delegación suya, asegurando que el almacén permanece en un estado -consistente, y permitiendo compartir entre usuarias los paquetes -construidos. - -@cindex usuarias de construcción -Mientras que @command{guix-daemon} se ejecuta como @code{root}, puede que no -desee que los procesos de construcción de paquetes se ejecuten como -@code{root} también, por razones de seguridad obvias. Para evitarlo, una -reserva especial de @dfn{usuarias de construcción} debe ser creada para ser -usada por los procesos de construcción iniciados por el daemon. Estas -usuarias de construcción no necesitan tener un shell ni un directorio home: -simplemente serán usadas cuando el daemon se deshaga de los privilegios de -@code{root} en los procesos de construcción. Tener varias de dichas usuarias -permite al daemon lanzar distintos procesos de construcción bajo UID -separados, lo que garantiza que no interferirán entre ellos---una -característica esencial ya que las construcciones se caracterizan como -funciones puras (@pxref{Introducción}). - -En un sistema GNU/Linux, una reserva de usuarias de construcción puede ser -creada así (usando la sintaxis de Bash y las órdenes de @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 "Usuaria de construcción Guix $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -El número de usuarias de construcción determina cuantos trabajos de -construcción se pueden ejecutar en paralelo, especificado por la opción -@option{--max-jobs} (@pxref{Invocación de guix-daemon, -@option{--max-jobs}}). Para usar @command{guix system vm} y las órdenes -relacionadas, puede necesitar añadir las usuarias de construcción al grupo -@code{kvm} para que puedan acceder a @file{/dev/kvm}, usando @code{-G -guixbuild,kvm} en vez de @code{-G guixbuild} (@pxref{Invocación de guix system}). - -El programa @code{guix-daemon} puede ser ejecutado entonces como @code{root} -con la siguiente orden@footnote{Si su máquina usa el sistema de inicio -systemd, copiando el fichero -@file{@var{prefix}/lib/systemd/system/guix-daemon.service} en -@file{/etc/systemd/system} asegurará que @command{guix-daemon} se arranca -automáticamente. De igual modo, si su máquina usa el sistema de inicio -Upstart, copie el fichero -@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} en -@file{/etc/init}.}: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -De este modo, el daemon inicia los procesos de construcción en un -``chroot'', bajo una de las usuarias @code{guixbuilder}. En GNU/Linux, por -defecto, el entorno ``chroot'' contiene únicamente: - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -un directorio @code{/dev} mínimo, creado en su mayor parte -independientemente del @code{/dev} del sistema anfitrión@footnote{``En su -mayor parte'', porque mientras el conjunto de ficheros que aparecen en -@code{/dev} es fijo, la mayor parte de estos ficheros solo pueden ser -creados si el sistema anfitrión los tiene.} - -@item -el directorio @code{/proc}; únicamente muestra los procesos del contenedor -ya que se usa un espacio de nombres de PID separado. - -@item -@file{/etc/passwd} con una entrada para la usuaria actual y una entrada para -la usuaria @file{nobody}; - -@item -@file{/etc/groups} con una entrada para el grupo de la usuaria; - -@item -@file{/etc/hosts} con una entrada que asocia @code{localhost} a -@code{127.0.0.1}; - -@item -un directorio @file{/tmp} con permisos de escritura. -@end itemize - -Puede influir en el directorio que el daemon utiliza para almacenar los -árboles de construcción @i{via} la variable de entorno @code{TMPDIR}. No -obstante, el árbol de construcción en el ``chroot'' siempre se llama -@file{/tmp/guix-build-@var{nombre}.drv-0}, donde @var{nombre} es el nombre -de la derivación---por ejemplo, @code{coreutils-8.24}. De este modo, el -valor de @code{TMPDIR} no se escapa a los entornos de construcción, lo que -evita discrepancias en caso de que los procesos de construcción capturen el -nombre de su árbol de construcción. - -@vindex http_proxy -El daemon también respeta la variable de entorno @code{http_proxy} para las -descargas HTTP que realiza, sea para derivaciones de salida fija -(@pxref{Derivaciones}) o para sustituciones (@pxref{Sustituciones}). - -Si está instalando Guix como una usuaria sin privilegios, es posible todavía -ejecutar @command{guix-daemon} siempre que pase @code{--disable-chroot}. No -obstante, los procesos de construcción no estarán aislados entre sí ni del -resto del sistema. Por tanto, los procesos de construcción pueden interferir -entre ellos y pueden acceder a programas, bibliotecas y otros ficheros -disponibles en el sistema---haciendo mucho más difícil verlos como funciones -@emph{puras}. - - -@node Configuración de delegación del daemon -@subsection Uso de la facilidad de descarga de trabajo - -@cindex delegando trabajo -@cindex hook de construcción -Cuando así se desee, el daemon de construcción puede @dfn{delegar} -construcciones de derivación a otras máquinas ejecutando Guix, usando el -@dfn{hook de construcción} @code{offload}@footnote{Esta característica está -únicamente disponible cuando -@uref{https://github.com/artyom-potsov/guile-ssh, Guile-SSH} está -presente.}. Cuando dicha característica es activada, una lista de máquinas -de construcción especificadas por la usuaria es leída de -@file{/etc/guix/machines.scm}; cada vez que se solicita una construcción, -por ejemplo via @code{guix build}, el daemon intenta delegarla a una de las -máquinas que satisfaga las condiciones de la derivación, en particular su -tipo de sistema---por ejemplo, @file{x86_64-linux}. Los prerrequisitos -restantes para la construcción son copiados por SSH a la máquina objetivo, -la cual procede con la construcción; con un resultado satisfactorio la(s) -salida(s) de la construcción son copiadas de vuelta a la máquina inicial. - -El fichero @file{/etc/guix/machines.scm} normalmente tiene un contenido de -este estilo: - -@example -(list (build-machine - (name "ochentayseis.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "rober") - (speed 2.)) ;¡increíblemente rápida! - - (build-machine - (name "mimips.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alicia") - (private-key - (string-append (getenv "HOME") - "/.ssh/identidad-para-guix")))) -@end example - -@noindent -En el ejemplo anterior se especifica una lista de dos máquinas de -construcción, una para la arquitectura @code{x86_64} y otra para la -arquitectura @code{mips64el}. - -De hecho, este fichero es---¡sin sorpresa ninguna!---un fichero Scheme que -se evalúa cuando el hook @code{offload} se inicia. El valor que devuelve -debe ser una lista de objetos @code{build-machine}. Mientras que este -ejemplo muestra una lista fija de máquinas de construcción, una puede -imaginarse, digamos, el uso de DNS-SD para devolver una lista de máquinas de -construcción potenciales descubierta en la red local (@pxref{Introducción, -Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme Programs}). El tipo -de datos @code{build-machine} se detalla a continuación. - -@deftp {Tipo de datos} build-machine -Este tipo de datos representa las máquinas de construcción a las cuales el -daemon puede delegar construcciones. Los campos importantes son: - -@table @code - -@item name -El nombre de red de la máquina remota. - -@item system -El sistema de la máquina remota---por ejemplo, @code{"x86_64-linux"}. - -@item user -La cuenta de usuaria a usar cuando se conecte a la máquina remota por -SSH. Tenga en cuenta que el par de claves SSH @emph{no} debe estar protegido -por contraseña, para permitir ingresos al sistema no interactivos. - -@item host-key -Este campo debe contener la @dfn{clave pública de la máquina} de SSH en -formato OpenSSH. Es usado para autentificar la máquina cuando nos conectamos -a ella. Es una cadena larga más o menos así: - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL recordatorio@@example.org -@end example - -Si la máquina está ejecutando el daemon OpenSSH, @command{sshd}, la clave -pública de la máquina puede encontrarse en un fichero como -@file{/etc/ssh/ssh_host_ed25519_key.pub}. - -Si la máquina está ejecutando el daemon SSH GNU@tie{}lsh, @command{lshd}, la -clave de la máquina está en @file{/etc/lsh/host-key.pub} o un fichero -similar. Puede convertirse a formato OpenSSH usando @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 - -Ciertos número de campos opcionales pueden ser especificados: - -@table @asis - -@item @code{port} (predeterminado: @code{22}) -Número de puerto del servidor SSH en la máquina. - -@item @code{private-key} (predeterminada: @file{~root/.ssh/id_rsa}) -El fichero de clave privada SSH usado para conectarse a la máquina, en -formato OpenSSH. Esta clave no debe estar protegida con una contraseña. - -Tenga en cuenta que el valor predeterminado es la clave privada @emph{de la -cuenta de root}. Asegurese de que existe si usa el valor predeterminado. - -@item @code{compression} (predeterminado: @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (predeterminado: @code{3}) -Los métodos de compresión y nivel de compresión a nivel SSH solicitados. - -Tenga en cuenta que la delegación de carga depende de la compresión SSH para -reducir el ancho de banda usado cuando se transfieren ficheros hacia y desde -máquinas de construcción. - -@item @code{daemon-socket} (predeterminado: @code{"/var/guix/daemon-socket/socket"}) -Nombre de fichero del socket de dominio Unix en el que @command{guix-daemon} -escucha en esa máquina. - -@item @code{parallel-builds} (predeterminadas: @code{1}) -El número de construcciones que pueden ejecutarse en paralelo en la máquina. - -@item @code{speed} (predeterminado: @code{1.0}) -Un ``factor de velocidad relativa''. El planificador de delegaciones tenderá -a preferir máquinas con un factor de velocidad mayor. - -@item @code{features} (predeterminadas: @code{'()}) -Una lista de cadenas denotando las características específicas permitidas -por la máquina. Un ejemplo es @code{"kvm"} para máquinas que tienen los -módulos KVM de Linux y las correspondientes características hardware. Las -derivaciones pueden solicitar las características por nombre, y entonces se -planificarán en las máquinas adecuadas. - -@end table -@end deftp - -El ejecutable @code{guix} debe estar en la ruta de búsqueda de las máquinas -de construcción. Puede comprobar si es el caso ejecutando: - -@example -ssh build-machine guix repl --version -@end example - -Hay una última cosa por hacer una vez @file{machines.scm} está en su -lugar. Como se ha explicado anteriormente, cuando se delega, los ficheros se -transfieren en ambas direcciones entre los almacenes de las máquinas. Para -que esto funcione, primero debe generar un par de claves en cada máquina -para permitir al daemon exportar los archivos firmados de ficheros en el -almacén (@pxref{Invocación de guix archive}): - -@example -# guix archive --generate-key -@end example - -@noindent -Cada máquina de construcción debe autorizar a la clave de la máquina maestra -para que acepte elementos del almacén que reciba de la maestra: - -@example -# guix archive --authorize < clave-publica-maestra.txt -@end example - -@noindent -Del mismo podo, la máquina maestra debe autorizar la clave de cada máquina -de construcción. - -Todo este lío con claves está ahí para expresar las mutuas relaciones de -confianza entre pares de la máquina maestra y las máquinas de -construcción. Concretamente, cuando la maestra recibe ficheros de una -máquina de construcción (y @i{vice versa}), su daemon de construcción puede -asegurarse de que son genuinos, no han sido modificados, y que están -firmados por una clave autorizada. - -@cindex prueba de delegación -Para comprobar si su configuración es operacional, ejecute esta orden en el -nodo maestro: - -@example -# guix offload test -@end example - -Esto intentará conectar con cada una de las máquinas de construcción -especificadas en @file{/etc/guix/machines.scm}, comprobará que GUile y los -módulos Guix están disponibles en cada máquina, intentará exportar a la -máquina e importar de ella, e informará de cualquier error en el proceso. - -Si quiere probar un fichero de máquinas diferente, simplemente especifiquelo -en la línea de órdenes: - -@example -# guix offload test otras-maquinas.scm -@end example - -Por último, puede probar un subconjunto de máquinas cuyos nombres coincidan -con una expresión regular así: - -@example -# guix offload test maquinas.scm '\.gnu\.org$' -@end example - -@cindex estado de delegación -Para mostrar la carga actual de todas las máquinas de construcción, ejecute -esta orden en el nodo principal: - -@example -# guix offload status -@end example - - -@node Soporte de SELinux -@subsection Soporte de SELinux - -@cindex SELinux, política del daemon -@cindex control de acceso mandatorio, SELinux -@cindex seguridad, guix-daemon -Guix incluye un fichero de política SELinux en @file{etc/guix-daemon.cil} -que puede ser instalado en un sistema donde SELinux está activado, para -etiquetar los ficheros Guix y especificar el comportamiento esperado del -daemon. Ya que el sistema Guix no proporciona una política base de SELinux, -la política del daemon no puede usarse en el sistema Guix. - -@subsubsection Instalación de la política de SELinux -@cindex SELinux, instalación de la política -Para instalar la política ejecute esta orden como root: - -@example -semodule -i etc/guix-daemon.cil -@end example - -Una vez hecho, vuelva a etiquetar el sistema de ficheros con -@code{restorecon} o con un mecanismo distinto que proporcione su sistema. - -Una vez la política está instalada, el sistema de ficheros ha sido -re-etiquetado, y el daemon ha sido reiniciado, debería ejecutarse en el -contexto @code{guix_daemon_t}. Puede confirmarlo con la siguiente orden: - -@example -ps -Zax | grep guix-daemon -@end example - -Monitorice los ficheros de log de SELinux mientras ejecuta una orden como -@code{guix build hello} para convencerse que SELinux permite todas las -operaciones necesarias. - -@subsubsection Limitaciones -@cindex SELinux, limitaciones - -Esta política no es perfecta. Aquí está una lista de limitaciones o -comportamientos extraños que deben ser considerados al desplegar la política -SELinux provista para el daemon Guix. - -@enumerate -@item -@code{guix_daemon_socket_t} no se usa realmente. Ninguna de las operaciones -del socket implica contextos que tengan algo que ver con -@code{guix_daemon_socket_t}. No hace daño tener esta etiqueta sin usar, pero -sería preferible definir reglas del socket únicamente para esta etiqueta. - -@item -@code{guix gc} no puede acceder enlaces arbitrarios a los perfiles. Por -diseño, la etiqueta del fichero del destino de un enlace simbólico es -independiente de la etiqueta de fichero del fichero en sí. Aunque todos los -perfiles bajo $localstatedir se etiquetan, los enlaces para estos perfiles -heredan la etiqueta del directorio en el que están. Para enlaces en el -directorio de la usuaria esto será @code{user_home_t}. Pero para los enlaces -del directorio de root, o @file{/tmp}, o del directorio del servidor HTTP, -etc., esto no funcionará. @code{guix gc} se verá incapacitado para leer y -seguir dichos enlaces. - -@item -La característica del daemon de esperar conexiones TCP puede que no funcione -más. Esto puede requerir reglas extra, ya que SELinux trata los sockets de -red de forma diferente a los ficheros. - -@item -Actualmente todos los ficheros con un nombre coincidente con la expresión -regular @code{/gnu/store.+-(gux-.+|profile)/bin/guix-daemon} tienen asignada -la etiqueta @code{guix_daemon_exec_t}; esto significa que @emph{cualquier} -fichero con ese nombre en cualquier perfil tendrá permitida la ejecución en -el dominio @code{guix_daemon_t}. Esto no es ideal. Una atacante podría -construir un paquete que proporcione este ejecutable y convencer a la -usuaria para instalarlo y ejecutarlo, lo que lo eleva al dominio -@code{guix_daemon_t}. Llegadas a este punto, SELinux no puede prevenir que -acceda a los ficheros permitidos para los procesos en dicho dominio. - -Podríamos generar una política mucho más restrictiva en tiempo de -instalación, de modo que solo el nombre @emph{exacto} del fichero del -ejecutable de @code{guix-daemon} actualmente instalado sea marcado como -@code{guix_daemon_exec_t}, en vez de usar una expresión regular amplia. La -desventaja es que root tendría que instalar o actualizar la política en -tiempo de instalación cada vez que se actualizase el paquete de Guix que -proporcione el ejecutable de @code{guix-daemon} realmente en ejecución. -@end enumerate - -@node Invocación de guix-daemon -@section Invocación de @command{guix-daemon} - -El programa @command{guix-daemon} implementa toda la funcionalidad para -acceder al almacén. Esto incluye iniciar procesos de construcción, ejecutar -el recolector de basura, comprobar la disponibilidad de un resultado de -construcción, etc. Normalmente se ejecuta como @code{root} así: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -Para detalles obre como configurarlo, @pxref{Preparación del daemon}. - -@cindex chroot -@cindex contenedor, entorno de construcción -@cindex entorno de construcción -@cindex construcciones reproducibles -Por defecto, @command{guix-daemon} inicia los procesos de construcción bajo -distintos UIDs, tomados del grupo de construcción especificado con -@code{--build-users-group}. Además, cada proceso de construcción se ejecuta -en un entorno ``chroot'' que únicamente contiene el subconjunto del almacén -del que depende el proceso de construcción, como especifica su derivación -(@pxref{Interfaz programática, derivación}), más un conjunto específico de -directorios del sistema. Por defecto, estos directorios contienen -@file{/dev} y @file{/dev/pts}. Es más, sobre GNU/Linux, el entorno de -construcción es un @dfn{contenedor}: además de tener su propio árbol del -sistema de ficheros, tiene un espacio de nombres de montado separado, su -propio espacio de nombres de PID, de red, etc. Esto ayuda a obtener -construcciones reproducibles (@pxref{Características}). - -Cuando el daemon realiza una construcción en delegación de la usuaria, crea -un directorio de construcción bajo @file{/tmp} o bajo el directorio -especificado por su variable de entorno @code{TMPDIR}. Este directorio se -comparte con el contenedor durante toda la construcción, aunque dentro del -contenedor el árbol de construcción siempre se llama -@file{/tmp/guix-build-@var{nombre}.drv-0}. - -El directorio de construcción se borra automáticamente una vez completado el -proceso, a menos que la construcción fallase y se especificase en el cliente -@option{--keep-failed} (@pxref{Invocación de guix build, -@option{--keep-failed}}). - -El daemon espera conexiones y lanza un subproceso por sesión iniciada por -cada cliente (una de las sub-órdenes de @command{guix}). La orden -@command{guix processes} le permite tener una visión general de la actividad -de su sistema mostrando clientes y sesiones activas. @xref{Invocación de guix processes}, para más información. - -Se aceptan las siguientes opciones de línea de ordenes: - -@table @code -@item --build-users-group=@var{grupo} -Toma las usuarias de @var{grupo} para ejecutar los procesos de construcción -(@pxref{Preparación del daemon, build users}). - -@item --no-substitutes -@cindex sustituciones -No usa sustituciones para la construcción de productos. Esto es, siempre -realiza las construcciones localmente en vez de permitir la descarga de -binarios pre-construidos (@pxref{Sustituciones}). - -Cuando el daemon se ejecuta con @code{--no-substitutes}, los clientes aún -pueden activar explícitamente las sustituciones @i{via} la llamada de -procedimiento remoto @code{set-build-options} (@pxref{El almacén}). - -@item --substitute-urls=@var{urls} -@anchor{daemon-substitute-urls} -Considera @var{urls} la lista separada por espacios predeterminada de URLs -de sustituciones de fuentes. Cuando se omite esta opción, se usa -@indicateurl{https://@value{SUBSTITUTE-SERVER}}. - -Esto significa que las sustituciones puede ser descargadas de @var{urls}, -mientras estén firmadas por una firma de confianza (@pxref{Sustituciones}). - -@cindex hook de construcción -@item --no-build-hook -No usa el @dfn{hook de construcción}. - -El hook de construcción es un programa auxiliar que el daemon puede lanzar y -al cual envía las peticiones de construcción. Este mecanismo se utiliza para -delegar construcciones a otras máquinas (@pxref{Configuración de delegación del daemon}). - -@item --cache-failures -Almacena en la caché los fallos de construcción. Por defecto, únicamente las -construcciones satisfactorias son almacenadas en la caché. - -Cuando se usa esta opción, @command{guix gc --list-failures} puede usarse -para consultar el conjunto de elementos del almacén marcados como fallidos; -@command{guix gc --clear-failures} borra los elementos del almacén del -conjunto de fallos existentes en la caché. @xref{Invocación de guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -Usa @var{n} núcleos de la CPU para construir cada derivación; @code{0} -significa tantos como haya disponibles. - -El valor predeterminado es @code{0}, pero puede ser sobreescrito por los -clientes, como la opción @code{--cores} de @command{guix build} -(@pxref{Invocación de guix build}). - -El efecto es definir la variable de entorno @code{NIX_BUILD_CORES} en el -proceso de construcción, el cual puede usarla para explotar el paralelismo -interno---por ejemplo, ejecutando @code{make -j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Permite como máximo @var{n} trabajos de construcción en paralelo. El valor -predeterminado es @code{1}. Fijarlo a @code{0} significa que ninguna -construcción se realizará localmente; en vez de eso, el daemon delegará las -construcciones (@pxref{Configuración de delegación del daemon}), o simplemente fallará. - -@item --max-silent-time=@var{segundos} -Cuando la construcción o sustitución permanece en silencio más de -@var{segundos}, la finaliza e informa de un fallo de construcción. - -El valor predeterminado es @code{0}, que deshabilita el plazo. - -El valor especificado aquí puede ser sobreescrito por clientes -(@pxref{Opciones comunes de construcción, @code{--max-silent-time}}). - -@item --timeout=@var{segundos} -Del mismo modo, cuando el proceso de construcción o sustitución dura más de -@var{segundos}, lo termina e informa un fallo de construcción. - -El valor predeterminado es @code{0}, que deshabilita el plazo. - -El valor especificado aquí puede ser sobreescrito por los clientes -(@pxref{Opciones comunes de construcción, @code{--timeout}}). - -@item --rounds=@var{N} -Construye cada derivación @var{n} veces seguidas, y lanza un error si los -resultados de las construcciones consecutivas no son idénticos -bit-a-bit. Fíjese que esta configuración puede ser sobreescrita por clientes -como @command{guix build} (@pxref{Invocación de guix build}). - -Cuando se usa conjuntamente con @option{--keep-failed}, la salida que -difiere se mantiene en el almacén, bajo -@file{/gnu/store/@dots{}-check}. Esto hace fácil buscar diferencias entre -los dos resultados. - -@item --debug -Produce salida de depuración. - -Esto es útil para depurar problemas en el arranque del daemon, pero entonces -puede ser cambiado el comportamiento por los clientes, por ejemplo la opción -@code{--verbosity} de @command{guix build} (@pxref{Invocación de guix build}). - -@item --chroot-directory=@var{dir} -Añade @var{dir} al chroot de construcción. - -Hacer esto puede cambiar el resultado del proceso de construcción---por -ejemplo si usa dependencias opcionales, que se encuentren en @var{dir}, -cuando están disponibles, y no de otra forma. Por esa razón, no se -recomienda hacerlo. En vez de eso, asegurese que cada derivación declara -todas las entradas que necesita. - -@item --disable-chroot -Deshabilita las construcciones en un chroot. - -No se recomienda el uso de esta opción ya que, de nuevo, podría permitir a -los procesos de construcción ganar acceso a dependencias no declaradas. Es -necesario, no obstante, cuando @command{guix-daemon} se ejecuta bajo una -cuenta de usuaria sin privilegios. - -@item --log-compression=@var{tipo} -Comprime los logs de construcción de acuerdo a @var{tipo}, que puede ser -@code{gzip}, @code{bzip2} o @code{none}. - -A menos que se use @code{--lose-logs}, todos los log de construcción se -mantienen en @var{localstatedir}. Para ahorrar espacio, el daemon -automáticamente los comprime con bzip2 por defecto. - -@item --disable-deduplication -@cindex deduplicación -Deshabilita la ``deduplicación'' automática en el almacén. - -Por defecto, los ficheros se añaden al almacén ``deduplicados'' -automáticamente: si un nuevo fichero añadido es idéntico a otro que ya se -encuentra en el almacén, el daemon introduce el nuevo fichero como un enlace -duro al otro fichero. Esto puede reducir notablemente el uso del disco, a -expensas de una carga de entrada/salida ligeramente incrementada al -finalizar un proceso de construcción. Esta opción deshabilita esta -optimización. - -@item --gc-keep-outputs[=yes|no] -Determina si el recolector de basura (GC) debe mantener salidas de las -derivaciones vias. - -@cindex GC, raíces del recolector de basura -@cindex raíces del recolector de basura -Cuando se usa ``yes'', el recolector de basura mantendrá las salidas de -cualquier derivación viva disponible en el almacén---los ficheros -@code{.drv}. El valor predeterminado es ``no'', lo que significa que las -salidas de las derivaciones se mantienen únicamente si son alcanzables desde -alguna raíz del recolector de basura. @xref{Invocación de guix gc}, para más -información sobre las raices del recolector de basura. - -@item --gc-keep-derivations[=yes|no] -Determina si el recolector de basura (GC) debe mantener derivaciones -correspondientes a salidas vivas. - -Cuando se usa ``yes'', como es el caso predeterminado, el recolector de -basura mantiene derivaciones---es decir, ficheros @code{.drv}---mientras al -menos una de sus salidas está viva. Esto permite a las usuarias seguir la -pista de los orígenes de los elementos en el almacén. El uso de ``no'' aquí -ahorra un poco de espacio en disco. - -De este modo, usar @code{--gc-keep-derivations} con valor ``yes'' provoca -que la vitalidad fluya de salidas a derivaciones, y usar -@code{--gc-keep-outputs} con valor ``yes'' provoca que la vitalidad fluya de -derivaciones a salidas. Cuando ambas tienen valor ``yes'', el efecto es -mantener todos los prerrequisitos de construcción (las fuentes, el -compilador, las bibliotecas y otras herramientas de tiempo de construcción) -de los objetos vivos del almacén, independientemente de que esos -prerrequisitos sean alcanzables desde una raíz del recolector de -basura. Esto es conveniente para desarrolladoras ya que ahorra -reconstrucciones o descargas. - -@item --impersonate-linux-2.6 -En sistemas basados en Linux, suplanta a Linux 2.6. Esto significa que la -llamada del sistema @code{uname} del kernel indicará 2.6 como el número de -publicación. - -Esto puede ser útil para construir programas que (habitualmente de forma -incorrecta) dependen en el número de versión del núcleo. - -@item --lose-logs -No guarda logs de construcción. Por defecto se almacenan bajo -@code{@var{localstatedir}/guix/log}. - -@item --system=@var{sistema} -Asume @var{sistema} como el tipo actual de sistema. Por defecto es el par de -arquitectura/núcleo encontrado durante la configuración, como -@code{x86_64-linux}. - -@item --listen=@var{destino} -Escucha conexiones en @var{destino}. @var{destino} se interpreta como el -nombre del fichero del socket de dominio Unix si comienza on @code{/} (barra -a la derecha). En otro caso, @var{destino} se interpreta como un nombre de -máquina o un nombre de máquina y puerto a escuchar. Aquí van unos pocos -ejemplos: - -@table @code -@item --listen=/gnu/var/daemon -Escucha por conexiones en el socket de dominio Unix @file{/gnu/var/daemon}, -creandolo si es necesario. - -@item --listen=localhost -@cindex daemon, acceso remoto -@cindex acceso remoto al daemon -@cindex daemon, configuración en cluster -@cindex daemon, configuración en cluster -Escucha conexiones TCP en la interfaz de red correspondiente a -@code{localhost}, en el puerto 44146. - -@item --listen=128.0.0.42:1234 -Escucha conexiones TCP en la interfaz de red correspondiente a -@code{128.0.0.42}, en el puerto 1234. -@end table - -Esta opción puede repetirse múltiples veces, en cuyo caso -@command{guix-daemon} acepta conexiones en todos los destinos -especificados. Las usuarias pueden indicar a los clientes a qué destino -conectarse fijando la variable de entorno @code{GUIX_DAEMON_SOCKET} -(@pxref{El almacén, @code{GUIX_DAEMON_SOCKET}}). - -@quotation Nota -El protocolo del daemon @code{no está autentificado ni cifrado}. El uso de -@code{--listen=@var{dirección}} es aceptable en redes locales, como -clusters, donde únicamente los nodos de confianza pueden conectarse al -daemon de construcción. En otros casos donde el acceso remoto al daemon es -necesario, recomendamos usar sockets de dominio Unix junto a SSH. -@end quotation - -Cuando se omite @code{--listen}, @command{guix-daemon} escucha conexiones en -el socket de dominio Unix que se encuentra en -@file{@var{localstatedir}/guix/daemon-socket/socket}. -@end table - - -@node Configuración de la aplicación -@section Configuración de la aplicación - -@cindex distribución distinta -Cuando se usa Guix sobre una distribución GNU/Linux distinta al sistema -Guix---una @dfn{distribución distinta}---unos pocos pasos adicionales son -necesarios para tener todo preparado. Aquí están algunos de ellos. - -@subsection Localizaciones - -@anchor{locales-and-locpath} -@cindex localizaciones, cuando no se está en el sistema Guix -@vindex LOCPATH -@vindex GUIX_LOCPATH -Los paquetes instalados @i{via} Guix no usarán los datos de localización del -sistema anfitrión. En vez de eso, debe primero instalar uno de los paquetes -de localización disponibles con Guix y después definir la variable de -entorno @code{GUIX_LOCPATH}: - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Fíjese que el paquete @code{glibc-locales} contiene datos para todas las -localizaciones que ofrece GNU@tie{}libc y pesa alrededor de -110@tie{}MiB. Alternativamente, @code{glibc-utf8-locales} es más pequeño -pero limitado a localizaciones UTF-8. - -La variable @code{GUIX_LOCPATH} juega un rol similar a @code{LOCPATH} -(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference -Manual}). No obstante, hay dos diferencias importantes: - -@enumerate -@item -@code{GUIX_LOCPATH} es respetada únicamente por la libc dentro de Guix, y no -por la libc que proporcionan las distribuciones distintas. Por tanto, usar -@code{GUIX_LOCPATH} le permite asegurarse de que los programas de la -distribución distinta no cargarán datos de localización incompatibles. - -@item -libc añade un sufijo a cada entrada de @code{GUIX_LOCPATH} con @code{/X.Y}, -donde @code{X.Y} es la versión de libc---por ejemplo, @code{2.22}. Esto -significa que, en caso que su perfil Guix contenga una mezcla de programas -enlazados contra diferentes versiones de libc, cada versión de libc -únicamente intentará cargar datos de localización en el formato correcto. -@end enumerate - -Esto es importante porque el formato de datos de localización usado por -diferentes versiones de libc puede ser incompatible. - -@subsection Selector de servicios de nombres - -@cindex selector de servicios de nombres, glibc -@cindex NSS (selector de servicios de nombres), glibc -@cindex ncsd (daemon de caché del servicio de nombres) -@cindex daemon de caché del servicio de nombres (ncsd) -Cuando se usa Guix en una distribución distinta, @emph{recomendamos -encarecidamente} que el sistema ejecute el @dfn{daemon de caché del servicio -de nombres} de la biblioteca de C de GNU, @command{ncsd}, que debe escuchar -en el socket @file{/var/run/nscd/socket}. En caso de no hacerlo, las -aplicaciones instaladas con Guix pueden fallar al buscar nombres de máquinas -o cuentas de usuaria, o incluso pueden terminar abruptamente. Los siguientes -párrafos explican por qué. - -@cindex @file{nsswitch.conf} -La biblioteca de C de GNU implementa un @dfn{selector de servicios de -nombres} (NSS), que es un mecanismo extensible para ``búsquedas de nombres'' -en general: resolución de nombres de máquinas, cuentas de usuaria y más -(@pxref{Selector de servicios de nombres,,, libc, The GNU C Library Reference Manual}). - -@cindex Servicio de información de red (NIS) -@cindex NIS (servicio de información de red) -Al ser extensible, NSS permite el uso de @dfn{módulos}, los cuales -proporcionan nuevas implementaciones de búsqueda de nombres: por ejemplo, el -módulo @code{nss-mdns} permite la resolución de nombres de máquina -@code{.local}, el módulo @code{nis} permite la búsqueda de cuentas de -usuaria usando el servicio de información de red (NIS), etc. Estos -``servicios de búsqueda'' extra se configuran para todo el sistema en -@file{/etc/nsswitch.conf}, y todos los programas en ejecución respetan esta -configuración (@pxref{NSS Configuration File,,, libc, The GNU C Reference -Manual}). - -Cuando se realiza una búsqueda de nombres---por ejemplo, llamando a la -función @code{getaddrinfo} en C---las aplicaciones primero intentarán -conectar con nscd; en caso satisfactorio, nscd realiza la búsqueda de -nombres en delegación suya. Si nscd no está ejecutándose, entonces realizan -la búsqueda por ellas mismas, cargando los servicios de búsqueda de nombres -en su propio espacio de direcciones y ejecutándola. Estos servicios de -búsqueda de nombres---los ficheros @file{libnss_*.so}---son abiertos con -@code{dlopen}, pero pueden venir de la biblioteca de C del sistema, en vez -de la biblioteca de C contra la que la aplicación está enlazada (la -biblioteca de C que viene en Guix). - -Y aquí es donde está el problema: si su aplicación está enlazada contra la -biblioteca de C de Guix (digamos, glibc 2.24) e intenta cargar módulos de -otra biblioteca de C (digamos, @code{libnss_mdns.so} para glibc 2.22), -probablemente terminará abruptamente o sus búsquedas de nombres fallarán -inesperadamente. - -Ejecutar @command{nscd} en el sistema, entre otras ventajas, elimina este -problema de incompatibilidad binaria porque esos ficheros @code{libnss_*.so} -se cargan en el proceso @command{nscd}, no en la aplicación misma. - -@subsection Tipografías X11 - -@cindex tipografías -La mayoría de aplicaciones gráficas usan Fontconfig para encontrar y cargar -tipografías y realizar la renderización del lado del cliente X11. El paquete -@code{fontconfig} en Guix busca tipografías en @file{$HOME/.guix-profile} -por defecto. Por tanto, para permitir a aplicaciones gráficas instaladas con -Guix mostrar tipografías, tiene que instalar las tipografías también con -Guix. Paquetes esenciales de tipografías incluyen @code{gs-fonts}, -@code{font-dejavu} y @code{font-gnu-freefont-ttf}. - -Para mostrar texto escrito en lenguas chinas, Japonés o Coreano en -aplicaciones gráficas, considere instalar @code{font-adobe-source-han-sans} -o @code{font-wqy-zenhei}. La anterior tiene múltiples salidas, una por -familia de lengua (@pxref{Paquetes con múltiples salidas}). Por ejemplo, la -siguiente orden instala tipografías para lenguas chinas: - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Programas más antiguos como @command{xterm} no usan Fontconfig sino que -dependen en el lado del servidor para realizar el renderizado de -tipografías. Dichos programas requieren especificar un nombre completo de -tipografía usando XLFD (Descripción lógica de tipografías X), como esta: - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -Para ser capaz de usar estos nombres completos para las tipografías TrueType -instaladas en su perfil Guix, necesita extender la ruta de fuentes del -servidor X: - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See . -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -Después de eso, puede ejecutar @code{xlsfonts} (del paquete @code{xlsfonts}) -para asegurarse que sus tipografías TrueType se enumeran aquí. - -@cindex @code{fc-cache} -@cindex caché de tipografías -Después de instalar tipografías puede tener que refrescar la caché de -tipografías para usarlas en las aplicaciones. Lo mismo aplica cuando las -aplicaciones instaladas vía Guix no parecen encontrar tipografías. Para -forzar la reconstrucción de la caché de tipografías ejecute @code{fc-cache --f}. La orden @code{fc-cache} es proporcionada por el paquete -@code{fontconfig}. - -@subsection Certificados X.509 - -@cindex @code{nss-certs} -El paquete @code{nss-certs} proporciona certificados X.509, que permiten a -los programas verificar los servidores accedidos por HTTPS. - -Cuando se usa Guix en una distribución distinta, puede instalar este paquete -y definir las variables de entorno relevantes de modo que los paquetes sepan -dónde buscar los certificados. @xref{Certificados X.509}, para información -detallada. - -@subsection Paquetes Emacs - -@cindex @code{emacs} -Cuando instala paquetes Emacs con Guix, los ficheros elisp pueden estar -tanto en @file{$HOME/.guix-profile/share/emacs/site-lisp/} o en -subdirectorios de -@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. El último -directorio existe porque potencialmente pueden existir miles de paquetes -Emacs, y almacenar todos sus ficheros en un directorio único puede no ser -confiable (por conflictos de nombres). Por lo que pensamos que usar un -directorio separado por cada paquete es una buena idea. Es muy similar a -cómo el sistema de paquetes de Emacs organiza la estructura de ficheros -(@pxref{Package Files,,, emacs, The GNU Emacs Manual}). - -Por defecto, Emacs (el instalado con Guix) ``sabe'' donde se alojan estos -paquetes, para que usted no tenga que realizar ninguna configuración. Si, -por alguna razón, desea evitar la carga automática de paquetes Emacs -instalados con Guix, puede hacerlo ejecutando Emacs con la opción -@code{--no-site-file} (@pxref{Init File,,, emacs, The GNU Emacs Manual}). - -@subsection La cadena de herramientas de GCC - -@cindex GCC -@cindex ld-wrapper - -Guix ofrece paquetes de compiladores individuales como @code{gcc}, pero si -necesita una cadena de herramientas completa para compilar y enlazar código -fuente lo que realmente desea es el paquete @code{gcc-toolchain}. Este -paquete proporciona una cadena de herramientas GCC para desarrollo C/C++, -incluyendo el mismo GCC, la biblioteca de C GNU (cabeceras y binarios, más -símbolos de desarrollo en la salida @code{debug}), Binutils y un -recubrimiento del enlazador. - -El propósito del recubrimiento es inspeccionar las opciones @code{-L} y -@code{-l} proporcionadas al enlazador, y los correspondientes parámetros -@code{-rpath}, y llamar al enlazador real con este nuevo conjunto de -parámetros. Puede instruir al recubrimiento para rechazar el enlace contra -bibliotecas que no se encuentren en el almacén fijando el valor de la -variable de entorno @code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} a @code{no}. - -@c TODO What else? - -@c ********************************************************************* -@node Instalación del sistema -@chapter Instalación del sistema - -@cindex instalación del sistema Guix -@cindex sistema Guix, instalación -Esta sección explica cómo instalar el sistema Guix en una máquina. Guix, -como gestor de paquetes, puede instalarse sobre un sistema GNU/Linux en -ejecución, @pxref{Instalación}. - -@ifinfo -@quotation Nota -@c This paragraph is for people reading this from tty2 of the -@c installation image. -Está leyendo esta documentación con un lector Info. Para obtener detalles -sobre su uso, presione la tecla @key{RET} (``retorno de carro'' o ``intro'') -en el siguiente enlace: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU -Info}. Presione después @kbd{l} para volver aquí. - -De manera alternativa, ejecute @command{info info} en otro terminal para -mantener el manual disponible. -@end quotation -@end ifinfo - -@menu -* Limitaciones:: Qué puede esperar. -* Consideraciones sobre el hardware:: Hardware soportado. -* Instalación desde memoria USB y DVD:: Preparar el medio de instalación. -* Preparación para la instalación:: Red, particionado, etc. -* Instalación gráfica guiada:: Instalación gráfica fácil. -* Instalación manual:: Instalación manual para artistas del teclado. -* Tras la instalación del sistema:: Cuando la instalación ha finalizado - satisfactoriamente. -* Instalación de Guix en una máquina virtual:: El patio de recreo del - sistema Guix. -* Construcción de la imagen de instalación:: Cómo esto llega a ser. -@end menu - -@node Limitaciones -@section Limitaciones - -We consider Guix System to be ready for a wide range of ``desktop'' and -server use cases. The reliability guarantees it provides---transactional -upgrades and rollbacks, reproducibility---make it a solid foundation. - -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -No está implementada la funcionalidad del gestor de volúmenes lógicos (LVM). - -@item -Se proporcionan más y más servicios del sistema (@pxref{Servicios}), pero -pueden faltar algunos. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Servicios de escritorio}), as well as a number of X11 window managers. However, KDE is -currently missing. -@end itemize - -More than a disclaimer, this is an invitation to report issues (and success -stories!), and to join us in improving it. @xref{Contribuir}, for more -info. - - -@node Consideraciones sobre el hardware -@section Consideraciones sobre el hardware - -@cindex soporte de hardware en el sistema Guix -GNU@tie{}Guix se enfoca en respetar la libertad de computación de las -usuarias. Se construye sobre el núcleo Linux-libre, lo que significa que -únicamente funciona hardware para el que existen controladores y firmware -libres. Hoy en día, un amplio rango del hardware común funciona con -GNU/Linux-libre---desde teclados a tarjetas gráficas a escáneres y -controladoras Ethernet. Desafortunadamente, todavía hay áreas donde los -fabricantes de hardware deniegan a las usuarias el control de su propia -computación, y dicho hardware no funciona en el sistema Guix. - -@cindex WiFi, soporte hardware -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 @code{%base-firmware} (@pxref{Referencia de ``operating-system'', -@code{firmware}}). - -@cindex RYF, Respeta Su Libertad -La @uref{https://www.fsf.org/, Fundación del Software Libre} patrocina -@uref{https://www.fsf.org/ryf, @dfn{Respeta Su Libertad}} (RYF), un programa -de certificación para productos hardware que respetan su libertad y su -privacidad y se aseguran de que usted tenga el control sobre su -dispositivo. Le recomendamos que compruebe la lista de dispositivos -certificados RYF. - -Otro recurso útil es el sitio web @uref{https://wwww.h-node.org/, -H-Node}. Contiene un catálogo de dispositivos hardware con información -acerca su funcionalidad con GNU/Linux. - - -@node Instalación desde memoria USB y DVD -@section Instalación desde memoria USB y DVD - -Se puede descargar una imagen de instalación ISO-9660 que puede ser escrita -en una memoria USB o grabada en un DVD desde -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{sistema}.iso.xz}, -donde @var{sistema} es uno de los siguientes valores: - -@table @code -@item x86_64-linux -para un sistema GNU/Linux en CPUs compatibles con la arquitectura de 64-bits -de Intel/AMD. - -@item i686-linux -para un sistema GNU/Linux en CPUs compatibles con la arquitectura de 32-bits -de Intel. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Asegurese de descargar el fichero @file{.sig} asociado y de verificar la -autenticidad de la imagen contra él, más o menos así: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{sistema}.iso.xz.sig -$ gpg --verify guix-system-install-@value{VERSION}.@var{sistema}.iso.xz.sig -@end example - -Si la orden falla porque no dispone de la clave pública necesaria, entonces -ejecute esta otra orden para importarla: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -y vuelva a ejecutar la orden @code{gpg --verify}. - -Esta imagen contiene las herramientas necesarias para una instalación. Está -pensada ara ser copiada @emph{tal cual} a una memoria USB o DVD con espacio -suficiente. - -@unnumberedsubsec Copiado en una memoria USB - -Para copiar la imagen en una memoria USB, siga estos pasos: - -@enumerate -@item -Descomprima la imagen usando la orden @command{xz}: - -@example -xz -d guix-system-install-@value{VERSION}.@var{sistema}.iso.xz -@end example - -@item -Conecte una memoria USB de 1@tie{}GiB o más a su máquina, y determine su -nombre de dispositivo. Asumiendo que la memoria USB es @file{/dev/sdX} copie -la imagen con: - -@example -dd if=guix-system-install-@value{VERSION}.@var{sistema}.iso of=/dev/sdX -sync -@end example - -El acceso a @file{/dev/sdX} normalmente necesita privilegios de root. -@end enumerate - -@unnumberedsubsec Grabación en un DVD - -Para copiar la imagen a un DVD, siga estos pasos: - -@enumerate -@item -Descomprima la imagen usando la orden @command{xz}: - -@example -xz -d guix-system-install-@value{VERSION}.@var{sistema}.iso.xz -@end example - -@item -Introduzca un DVD escribible en su máquina, y determine el nombre del -dispositivo. Asumiendo que la unidad DVD es @file{/dev/srX}, copie la imagen -con: - -@example -growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{sistema}.iso -@end example - -El acceso a @file{/dev/srX} normalmente necesita privilegios de root. -@end enumerate - -@unnumberedsubsec Arranque - -Una vez hecho esto, debe ser capaz de reiniciar el sistema y arrancar desde -la memoria USB o el DVD. Lo primero habitualmente requiere que introducirse -en la BIOS o en el menú de arranque UEFI, donde se puede seleccionar el -arranque desde la memoria USB. - -@xref{Instalación de Guix en una máquina virtual}, si, en vez de esto, desea instalar el -sistema Guix en una máquina virtual (VM). - - -@node Preparación para la instalación -@section Preparación para la instalación - -Una vez que haya arrancado, puede usar el instalador gráfico guiado, el cual -facilita la introducción al sistema (@pxref{Instalación gráfica guiada}). Alternativamente, si ya es está familiarizada con GNU/Linux -y desea más control que el que proporciona el instalador gráfico, puede -seleccionar el proceso de instalación ``manual'' (@pxref{Instalación manual}). - -El instalador gráfico está disponible en TTY1. Puede obtener consolas de -root en los TTY 3 a 6 pulsando @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, -etc. TTY2 muestra esta documentación y se puede cambiar a dicha consola con -@kbd{ctrl-alt-f2}. La documentación es explorable usando las órdenes del -lector Info (@pxref{Top,,, info-stnd, Stand-alone GNU Info}). El sistema de -instalación ejecuta el daemon GPM para ratones, el cual le permite -seleccionar texto con el botón izquierdo y pegarlo con el botón central. - -@quotation Nota -La instalación requiere acceso a Internet de modo que cualquier dependencia -de su configuración de sistema no encontrada pueda ser descargada. Véase la -sección ``Red'' más adelante. -@end quotation - -@node Instalación gráfica guiada -@section Instalación gráfica guiada - -El instalador gráfico es una interfaz de usuaria basada en texto. Le guiará, -con cajas de diálogo, a través de los pasos necesarios para instalar el -sistema GNU@tie{}Guix. - -Las primeras cajas de diálogo le permiten configurar el sistema mientras lo -usa durante la instalación: puede seleccionar el idioma, la distribución del -teclado y configurar la red, la cual se usará durante la instalación. La -siguiente imagen muestra el diálogo de configuración de red. - -@image{images/installer-network,5in,, configuración de red en la instalación -gráfica} - -Los siguientes pasos le permitirán particionar su disco duro, como se -muestra en la siguiente imagen, elegir si se usarán o no sistemas de -ficheros cifrados, introducir el nombre de la máquina, la contraseña de root -y crear cuentas adicionales, entre otras cosas. - -@image{images/installer-partitions,5in,, particionado en la instalación -gráfica} - -Tenga en cuenta que, en cualquier momento, el instalador le permite salir de -la instalación actual y retomarla en un paso previo, como se muestra en la -siguiente imagen. - -@image{images/installer-resume,5in,, retomado del proceso de instalación} - -Una vez haya finalizado, el instalador produce una configuración de sistema -operativo y la muestra (@pxref{Uso de la configuración del sistema}). En este -punto puede pulsar ``OK'' y la instalación procederá. En caso de -finalización satisfactoria, puede reiniciar con el nuevo sistema y -disfrutarlo. ¡@xref{Tras la instalación del sistema} para ver cómo proceder a -continuación! - - -@node Instalación manual -@section Instalación manual - -Esta sección describe como podría instalar ``manualmente'' el sistema -GNU@tie{}Guix en su máquina. Esta opción requiere familiaridad con -GNU/Linux, con el shell y con las herramientas de administración comunes. Si -puensa que no es para usted, considere el uso del instalador gráfico guiado -(@pxref{Instalación gráfica guiada}). - -El sistema de instalación proporciona consolas de root en los terminales -virtuales (TTY) 3 a 6; pulse @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4} y -sucesivas teclas para abrirlas. Incluye muchas herramientas comunes -necesarias para la instalación del sistema. Pero es también un sistema Guix -completo, lo que significa que puede instalar paquetes adicionales, en caso -de necesitarlos, mediante el uso de @command{guix package} (@pxref{Invocación de guix package}). - -@menu -* Distribución de teclado y red y particionado:: Configuración inicial. -* Procedimiento de instalación:: Instalación. -@end menu - -@node Distribución de teclado y red y particionado -@subsection Distribución de teclado, red y particionado - -Antes de instalar el sistema, puede desear ajustar la distribución del -teclado, configurar la red y particionar el disco duro deseado. Esta sección -le guiará durante este proceso. - -@subsubsection Distribución de teclado - -@cindex distribución de teclado -La imagen de instalación usa la distribución de teclado QWERTY de los -EEUU. Si desea cambiarla, puede usar la orden @command{loadkeys}. Por -ejemplo, la siguiente orden selecciona la distribución de teclado para el -castellano: - -@example -loadkeys es -@end example - -Véanse los ficheros bajo @file{/run/current-system/profile/share/keymaps} -para la obtención de una lista de distribuciones de teclado -disponibles. Ejecute @command{man loadkeys} para más información. - -@subsubsection Red - -Ejecute la siguiente orden para ver los nombres asignados a sus interfaces -de red: - -@example -ifconfig -a -@end example - -@noindent -@dots{} o, usando la orden específica de GNU/Linux @command{ip}: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -El nombre de las interfaces de cable comienza con @samp{e}; por ejemplo, la -interfaz que corresponde a la primera controladora Ethernet en la placa se -llama @samp{eno1}. El nombre de las interfaces inalámbricas comienza con -@samp{w}, como @samp{w1p2s0}. - -@table @asis -@item Conexión por cable -Para configurar una red por cable ejecute la siguiente orden, substituyendo -@var{interfaz} con el nombre de la interfaz de cable que desea usar. - -@example -ifconfig @var{interfaz} up -@end example - -@item Conexión sin cable -@cindex sin cables -@cindex WiFi -Para configurar una red inalámbrica, puede crear un fichero de configuración -para la herramienta de configuración @command{wpa_supplicant} (su ruta no es -importante) usando uno de los editores de texto disponibles como -@command{nano}: - -@example -nano wpa_supplicant.conf -@end example - -Como un ejemplo, la siguiente plantilla puede colocarse en este fichero y -funcionará para muchas redes inalámbricas, siempre que se proporcione el -SSID y la contraseña reales de la red a la que se va a conectar: - -@example -network=@{ - ssid="@var{mi-ssid}" - key_mgmt=WPA-PSK - psk="la contraseña de la red" -@} -@end example - -Inicie el servicio inalámbrico y ejecutelo en segundo plano con la siguiente -orden (sustituya @var{interfaz} por el nombre de la interfaz de red que -desea usar): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{interfaz} -B -@end example - -Ejecute @command{man wpa_supplicant} para más información. -@end table - -@cindex DHCP -En este punto, necesita obtener una dirección IP. En una red donde las -direcciones IP se asignan automáticamente mediante DHCP, puede ejecutar: - -@example -dhclient -v @var{interfaz} -@end example - -Intente hacer ping a un servidor para comprobar si la red está funcionando -correctamente: - -@example -ping -c 3 gnu.org -@end example - -Configurar el acceso por red es casi siempre un requisito debido a que la -imagen no contiene todo el software y las herramientas que puedan ser -necesarias. - -@cindex instalación por SSH -Si lo desea, puede continuar la instalación de forma remota iniciando un -servidor SSH: - -@example -herd start ssh-daemon -@end example - -Asegurese de fijar una contraseña con @command{passwd}, o configurar la -verificación de clave pública de OpenSSH para la introducción en el sistema. - -@subsubsection Particionado de discos - -A menos que se haya realizado previamente, el siguiente paso es el -particionado, y después dar formato a la/s partición/es deseadas. - -La imagen de instalación contiene varias herramientas de particionado, -incluyendo Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), -@command{fdisk} y @command{cfdisk}. Ejecutelo y configure el mapa de -particiones deseado en su disco: - -@example -cfdisk -@end example - -Si su disco usa el formato de tabla de particiones GUID (GPT) y tiene -pensado instalar GRUB basado en BIOS (la opción predeterminada), asegurese -de tener una partición de arranque BIOS disponible (@pxref{BIOS -installation,,, grub, GNU GRUB manual}). - -@cindex EFI, instalación -@cindex UEFI, instalación -@cindex ESP, partición del sistema EFI -Si en vez de eso desea GRUB basado en EFI, se requiere una @dfn{Partición -del Sistema EFI} (ESP) con formato FAT32. Esta partición puede montarse en -@file{/boot/efi} y debe tener la opción @code{esp} activa. Por ejemplo, en -@command{parted}: - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Nota -@vindex grub-bootloader -@vindex grub-efi-bootloader -¿No esta segura si usar GRUB basado en EFI o en BIOS? Si el directorio -@file{/sys/firmware/efi} existe en la imagen de instalación, probablemente -debería realizar una instalación EFI, usando @code{grub-efi-bootloader}. En -otro caso, debe usar GRUB basado en BIOS, conocido como -@code{grub-bootloader}. @xref{Configuración del gestor de arranque}, para más -información sobre cargadores de arranque. -@end quotation - -Una vez haya terminado con el particionado de la unidad de disco deseada, -tiene que crear un sistema de ficheros en la o las particiónes -relevantes@footnote{Actualmente el sistema Guix únicamente permite sistemas -de ficheros ext4 y btrfs. En particular, el código que lee UUIDs del sistema -de ficheros y etiquetas únicamente funciona para dichos sistemas de -ficheros.}. Para la ESP, si tiene una y asumiendo que es @file{/dev/sda1}, -ejecute: - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Preferentemente, asigne una etiqueta a los sistemas de ficheros de modo que -pueda referirse a ellos de forma fácil y precisa en las declaraciones -@code{file-system} (@pxref{Sistemas de ficheros}). Esto se consigue habitualmente -con la opción @code{-L} de @command{mkfs.ext4} y las ordenes -relacionadas. Por tanto, asumiendo que la partición de la raíz es -@file{/dev/sda2}, se puede crear un sistema de ficheros con la etiqueta -@code{mi-raiz} de esta manera: - -@example -mkfs.ext4 -L mi-raiz /dev/sda2 -@end example - -@cindex disco cifrado -Si en vez de eso planea cifrar la partición raíz, puede usar las -herramientas Crypsetup/LUKS para hacerlo (véase @inlinefmtifelse{html, -@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, -@code{man cryptsetup}} para más información). Asumiendo que quiere almacenar -la partición raíz en @file{/dev/sda2}, la secuencia de ordenes sería más o -menos así: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda1 mi-particion -mkfs.ext4 -L mi-raiz /dev/mapper/mi-particion -@end example - -Una vez hecho esto, monte el sistema de ficheros deseado bajo @file{/mnt} -con una orden como (de nuevo, asumiendo que @code{mi-raiz} es la etiqueta -del sistema de ficheros raíz): - -@example -mount LABEL=mi-raiz /mnt -@end example - -Monte también cualquier otro sistema de ficheros que desee usar en el -sistema resultante relativamente a esta ruta. Si ha optado por -@file{/boot/efi} como el punto de montaje de EFI, por ejemplo, ahora debe -ser montada en @file{/mnt/boot/efi} para que @code{guix system init} pueda -encontrarla más adelante. - -Finalmente, si planea usar una o más particiones de intercambio -(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference -Manual}), asegurese de inicializarla con @command{mkswap}. Asumiendo que -tuviese una partición de intercambio en @file{/dev/sda3}, ejecutaría: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -De manera alternativa, puede usar un fichero de intercambio. Por ejemplo, -asumiendo que en el nuevo sistema desea usar el fichero -@file{/fichero-de-intercambio} como tal, ejecutaría@footnote{Este ejemplo -funcionará para muchos tipos de sistemas de ficheros (por ejemplo, ext4). No -obstante, para los sistemas de ficheros con mecanismos de -copia-durante-escritura (por ejemplo, btrfs) los pasos pueden diferir. Para -obtener más detalles, véanse las páginas de manual para @command{mkswap} y -@command{swapon}.}: - -@example -# Esto son 10GiB de espacio de intercambio. Ajuste "count" para -# cambiar el tamaño. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# Por seguridad, se mantiene el fichero únicamente legible y -# escribible por root. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Fijese que si ha cifrado la partición raíz y creado un fichero de -intercambio en su sistema de ficheros como se ha descrito anteriormente, el -cifrado también protege al fichero de intercambio, como a cualquier fichero -en dicho sistema de ficheros. - -@node Procedimiento de instalación -@subsection Procedimiento de instalación - -Con las particiones deseadas listas y la raíz deseada montada en -@file{/mnt}, estamos preparadas para empezar. Primero, ejecute: - -@example -herd start cow-store /mnt -@end example - -Esto activa la copia-durante-escritura en @file{/gnu/store}, de modo que los -paquetes que se añadan durante la fase de instalación se escriban en el -disco montado en @file{/mnt} en vez de permanecer en memoria. Esto es -necesario debido a que la primera fase de la orden @command{guix system -init} (vea más adelante) implica descargas o construcciones en -@file{/gnu/store}, el cual, inicialmente, está un sistema de ficheros en -memoria. - -Después debe editar un fichero y proporcionar la declaración de sistema -operativo a instalar. Para dicho fin, el sistema de instalación viene con -tres editores de texto. Recomendamos GNU nano (@pxref{Top,,, nano, GNU nano -Manual}), que permite el resaltado de sintaxis y correspondencia de -paréntesis; los otros editores son GNU Zile (un clon de Emacs) y nvi (un -clon del editor @command{vi} original de BSD). Le recomendamos -encarecidamente almacenar ese fichero en el sistema de ficheros raíz, -digamos, como @file{/mnt/etc/config.scm}. En caso de no hacerlo, habrá -perdido su configuración del sistema una vez arranque en el sistema recién -instalado. - -@xref{Uso de la configuración del sistema}, para hacerse una idea del fichero de -configuración. Las configuraciones de ejemplo mencionadas en esa sección -están disponibles bajo @file{/etc/configuration} en la imagen de -instalación. Por tanto, para empezar con una configuración del sistema que -proporcione un servidor gráfico (un sistema de ``escritorio''), puede -ejecutar algo parecido a estas órdenes: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -Debe prestar atención a lo que su fichero de configuración contiene, y en -particular: - -@itemize -@item -Asegurese que la forma @code{bootloader-configuration} especifica la -localización deseada de la instalación de GRUB. Debe mencionar -@code{grub-bootloader} si está usando GRUB con el arranque antiguo, o -@code{grub-efi-bootloader} para sistemas más nuevos UEFI. Para los sistemas -antiguos, el campo @code{target} denomina un dispositivo, como -@code{/dev/sda}; para los sistemas UEFI denomina la ruta de una partición -EFI montada, como @code{/boot/efi}; asegurese de que la ruta está -actualmente montada y haya una entrada @code{file-system} especificada en su -configuración. - -@item -Asegurese que las etiquetas de su sistema de ficheros corresponden con el -valor de sus campos @code{device} respectivos en su configuración -@code{file-system}, asumiendo que su configuración @code{file-system} usa el -procedimiento @code{file-system-label} en su campo @code{device}. - -@item -Si hay particiones cifradas o en RAID, asegurese de añadir un campo -@code{mapped-devices} para describirlas (@pxref{Dispositivos traducidos}). -@end itemize - -Una vez haya terminado de preparar el fichero de configuración, el nuevo -sistema debe ser inicializado (recuerde que el sistema de ficheros raíz -deseado está montado bajo @file{/mnt}): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -Esto copia todos los ficheros necesarios e instala GRUB en @file{/dev/sdX}, -a menos que proporcione la opción @option{--no-bootloader}. Para más -información, @pxref{Invocación de guix system}. Esta orden puede desencadenar -descargas o construcciones de paquetes no encontrados, lo cual puede tomar -algún tiempo. - -Una vez que la orden se complete---¡y, deseablemente, de forma -satisfactoria!---puede ejecutar @command{reboot} y arrancar con el nuevo -sistema. La contraseña de @code{root} en el nuevo sistema está vacía -inicialmente; otras contraseñas de usuarias tienen que ser inicializadas -ejecutando la orden @command{passwd} como @code{root}, a menos que en su -configuración se especifique de otra manera (@pxref{user-account-password, -contraseñas de cuentas de usuaria}). ¡@xref{Tras la instalación del sistema} para -proceder a continuación! - - -@node Tras la instalación del sistema -@section Tras la instalación del sistema - -¡Éxito! ¡Ha arrancado en el sistema Guix! De ahora en adelante, puede -actualizar el sistema cuando quiera mediante la ejecución de, digamos: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -Esto construye una nueva generación del sistema con los últimos paquetes y -servicios (@pxref{Invocación de guix system}). Recomendamos realizarlo de manera -regular de modo que su sistema incluya las últimas actualizaciones de -seguridad (@pxref{Actualizaciones de seguridad}). - -@c See . -@quotation Nota -@cindex sudo y @command{guix pull} -Tenga en cuenta que @command{sudo guix} ejecuta el ejecutable @command{guix} -de su usuaria y @emph{no} el de root, ya que @command{sudo} no altera -@code{PATH}. Para ejecutar explícitamente el ejecutable @command{guix} de -root, escriba @command{sudo -i guix @dots{}}. -@end quotation - -¡Unase a nosotras en @code{#guix} en la red IRC Freenode o en -@file{guix-devel@@gnu.org} para compartir su experiencia! - - -@node Instalación de Guix en una máquina virtual -@section Instalación de Guix en una máquina virtual - -@cindex máquina virtual, instalación del sistema Guix -@cindex servidor virtual privado (VPS) -@cindex VPS (servidor virtual privado) -Si desea instalar el sistema Guix en una máquina virtual (VM) o en un -servidor privado virtual (VPS) en vez de en su preciada máquina, esta -sección es para usted. - -Si quiere arrancar una VM @uref{http://qemu.org/,QEMU} para instalar el -sistema Guix en una imagen de disco, siga estos pasos: - -@enumerate -@item -Primero, obtenga y descomprima la imagen de instalación del sistema Guix -como se ha descrito previamente (@pxref{Instalación desde memoria USB y DVD}). - -@item -Cree una imagen de disco que contendrá el sistema instalado. Para crear una -imagen de disco con formato qcow2, use la orden @command{qemu-img}: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -El fichero que obtenga será mucho menor de 50GB (típicamente menos de 1MB), -pero crecerá cuando el dispositivo de almacenamiento virtualizado se vaya -llenando. - -@item -Arranque la imagen de instalación USB en una máquina virtual: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guix-system-install-@value{VERSION}.@var{sistema}.iso \ - -drive file=guixsd.img -@end example - -El orden de las unidades importa. - -En la consola de la VM, pulse rápidamente la tecla @kbd{F12} para entrar al -menú de arranque. Pulse la tecla @kbd{2} y la tecla @kbd{RET} para confirmar -su selección. - -@item -Ahora es root en la VM, prosiga con el procedimiento de -instalación. @xref{Preparación para la instalación}, y siga las instrucciones. -@end enumerate - -Una vez complete la instalación, puede arrancar el sistema que está en la -imagen @file{guixsd.img}. @xref{Ejecutar Guix en una máquina virtual}, para información -sobre cómo hacerlo. - -@node Construcción de la imagen de instalación -@section Construcción de la imagen de instalación - -@cindex imagen de instalación -La imagen de instalación descrita anteriormente se construyó usando la orden -@command{guix system}, específicamente: - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Eche un vistazo a @file{gnu/system/install.scm} en el árbol de fuentes, y -vea también @ref{Invocación de guix system} para más información acerca de la -imagen de instalación. - -@section Construcción de la imagen de instalación para placas ARM - -Muchas placas ARM necesitan una variante específica del cargador de arranque -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot}. - -Si construye una imagen de disco y el cargador de arranque no está -disponible de otro modo (en otra unidad de arranque, etc.), es recomendable -construir una imagen que incluya el cargador, específicamente: - -@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} es el nombre de la placa. Si especifica una placa -no válida, una lista de placas posibles será mostrada. - -@c ********************************************************************* -@node Gestión de paquetes -@chapter Gestión de paquetes - -@cindex paquetes -El propósito de GNU Guix es permitir a las usuarias instalar, actualizar y -borrar fácilmente paquetes de software, sin tener que conocer acerca de sus -procedimientos de construcción o dependencias. Guix también va más allá de -este conjunto obvio de características. - -Este capítulo describe las principales características de Guix, así como las -herramientas de gestión de paquetes que ofrece. Junto a la interfaz de línea -de órdenes descrita a continuación (@pxref{Invocación de guix package, @code{guix -package}}, también puede usar la interfaz Emacs-Guix (@pxref{Top,,, -emacs-guix, The Emacs Guix Reference Manual}), tras la instalación del -paquete @code{emacs-guix} (ejecute la orden @kbd{M-x guix-help} para -iniciarse en su uso): - -@example -guix package -i emacs-guix -@end example - -@menu -* Características:: Cómo Guix dará brillo a su vida. -* Invocación de guix package:: Instalación de paquetes, borrado, etc. -* Sustituciones:: Descargar binarios pre-construidos. -* Paquetes con múltiples salidas:: Un único paquete de fuentes, - múltiples salidas. -* Invocación de guix gc:: Ejecutar el recolector de basura. -* Invocación de guix pull:: Obtener la última versión de Guix y la - distribución. -* Canales:: Personalizar el recolector de basura. -* Inferiores:: Interactuar con otra revisión de Guix. -* Invocación de guix describe:: Muestra información acerca de su - revisión de Guix. -* Invocación de guix archive:: Exportar e importar ficheros del almacén. -@end menu - -@node Características -@section Características - -Cuando se usa Guix, cada paquete se encuentra en el @dfn{almacén de -paquetes}, en su propio directorio---algo que se asemeja a -@file{/gnu/store/xxx-paquete-1.2}, donde @code{xxx} es una cadena en base32. - -En vez de referirse a estos directorios, las usuarias tienen su propio -@dfn{perfil}, el cual apunta a los paquetes que realmente desean usar. Estos -perfiles se almacenan en el directorio de cada usuaria, en -@code{$HOME/.guix-profile}. - -Por ejemplo, @code{alicia} instala GCC 4.7.2. Como resultado, -@file{/home/alicia/.guix-profile/bin/gcc} apunta a -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Ahora, en la misma máquina, -@code{rober} ha instalado ya GCC 4.8.0. El perfil de @code{rober} -simplemente sigue apuntando a -@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---es decir, ambas versiones de -GCC pueden coexistir en el mismo sistema sin ninguna interferencia. - -La orden @command{guix package} es la herramienta central para gestión de -paquetes (@pxref{Invocación de guix package}). Opera en los perfiles de usuaria, -y puede ser usada @emph{con privilegios de usuaria normal}. - -@cindex transacciones -La orden proporciona las operaciones obvias de instalación, borrado y -actualización. Cada invocación es en realidad una @emph{transacción}: o bien -la operación especificada se realiza satisfactoriamente, o bien nada -sucede. Por tanto, si el proceso @command{guix package} es finalizado -durante una transacción, o un fallo eléctrico ocurre durante la transacción, -el perfil de usuaria permanece en su estado previo, y permanece usable. - -Además, cualquier transacción de paquetes puede ser @emph{vuelta atrás}. Si, -por ejemplo, una actualización instala una nueva versión de un paquete que -resulta tener un error importante, las usuarias pueden volver a la instancia -previa de su perfil, de la cual se tiene constancia que funcionaba bien. De -igual modo, la configuración global del sistema en Guix está sujeta a -actualizaciones transaccionales y vuelta atrás (@pxref{Uso de la configuración del sistema}). - -Todos los paquetes en el almacén de paquetes pueden ser @emph{eliminados por -el recolector de basura}. Guix puede determinar qué paquetes están siendo -todavía referenciados por los perfiles de usuarias, y eliminar aquellos que, -de forma demostrable, no están referenciados (@pxref{Invocación de guix gc}). Las -usuarias pueden también borrar explícitamente generaciones antiguas de su -perfil para que los paquetes referenciados en ellas puedan ser recolectadas. - -@cindex reproducibilidad -@cindex construcciones reproducibles -Guix toma una aproximación @dfn{puramente funcional} en la gestión de -paquetes, como se describe en la introducción (@pxref{Introducción}). Cada -nombre de directorio de paquete en @file{/gnu/store} contiene un hash de -todas las entradas que fueron usadas para construir el paquete---compilador, -bibliotecas, guiones de construcción, etc. Esta correspondencia directa -permite a las usuarias asegurarse que una instalación dada de un paquete -corresponde al estado actual de su distribución. Esto también ayuda a -maximizar la @dfn{reproducibilidad de la construcción}: gracias al uso de -entornos aislados de construcción, una construcción dada probablemente -generará ficheros idénticos bit-a-bit cuando se realice en máquinas -diferentes (@pxref{Invocación de guix-daemon, container}). - -@cindex sustituciones -Estos cimientos permiten a Guix ofrecer @dfn{despliegues transparentes de -binarios/fuentes}. Cuando un binario pre-construido para un elemento de -@file{/gnu/store} está disponible para descarga de una fuente externa---una -@dfn{sustitución}, Guix simplemente lo descarga y desempaqueta; en otro caso -construye el paquete de las fuentes, localmente -(@pxref{Sustituciones}). Debido a que los resultados de construcción son -normalmente reproducibles bit-a-bit, las usuarias no tienen que confiar en -los servidores que proporcionan sustituciones: pueden forzar una -construcción local y @emph{retar} a las proveedoras (@pxref{Invocación de guix challenge}). - -El control sobre el entorno de construcción es una característica que -también es útil para desarrolladoras. La orden @command{guix environment} -permite a desarrolladoras de un paquete configurar rápidamente el entorno de -desarrollo correcto para su paquete, sin tener que instalar manualmente las -dependencias del paquete en su perfil (@pxref{Invocación de guix environment}). - -@cindex replicación, de entornos de software -@cindex seguimiento de procedencia, de artefactos de software -Todo Guix y sus definiciones de paquetes están bajo control de versiones, y -@command{guix pull} le permite ``viajar en el tiempo'' por la historia del -mismo Guix (@pxref{Invocación de guix pull}). Esto hace posible replicar una -instancia de Guix en una máquina diferente o en un punto posterior del -tiempo, lo que a su vez le permite @emph{replicar entornos de software -completos}, mientras que mantiene un preciso @dfn{seguimiento de la -procedencia} del software. - -@node Invocación de guix package -@section Invocación de @command{guix package} - -@cindex instalar paquetes -@cindex borrar paquetes -@cindex instalación de paquetes -@cindex borrado de paquetes -La orden @command{guix package} es la herramienta que permite a las usuarias -instalar, actualizar y borrar paquetes, así como volver a configuraciones -previas. Opera únicamente en el perfil propio de la usuaria, y funciona con -privilegios de usuaria normal (@pxref{Características}). Su sintaxis es: - -@example -guix package @var{opciones} -@end example -@cindex transacciones -Primariamente, @var{opciones} especifica las operaciones a ser realizadas -durante la transacción. Al completarse, un nuevo perfil es creado, pero las -@dfn{generaciones} previas del perfil permanecen disponibles, en caso de que -la usuaria quisiera volver atrás. - -Por ejemplo, para borrar @code{lua} e instalar @code{guile} y -@code{guile-cairo} en una única transacción: - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} también proporciona una @dfn{aproximación -declarativa}, donde la usuaria especifica el conjunto exacto de paquetes a -poner disponibles y la pasa a través de la opción @option{--manifest} -(@pxref{profile-manifest, @option{--manifest}}). - -@cindex perfil -Para cada usuaria, un enlace simbólico al perfil predeterminado de la -usuaria es creado en @file{$HOME/.guix-profile}. Este enlace simbólico -siempre apunta a la generación actual del perfil predeterminado de la -usuaria. Por lo tanto, las usuarias pueden añadir -@file{$HOME/.guix-profile/bin} a su variable de entorno @code{PATH}, y -demás. -@cindex rutas de búsqueda -Si no está usando la Distribución de Sistema Guix, considere añadir las -siguientes líneas a su @file{~/.bash_profile} (@pxref{Bash Startup Files,,, -bash, The GNU Bash Reference Manual}) de modo que los shell lanzados a -partir de entonces obtengan todas las definiciones de variables de entorno -correctas: - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -En una configuración multiusuaria, los perfiles de usuaria se almacenan en -un lugar registrado como una @dfn{raíz del sistema de ficheros}, a la que -apunta @file{$HOME/.guix-profile} (@pxref{Invocación de guix gc}). Ese directorio -normalmente es -@code{@var{localstatedir}/guix/profiles/per-user/@var{usuaria}}, donde -@var{localstatedir} es el valor pasado a @code{configure} como -@code{--localstatedir} y @var{usuaria} es el nombre de usuaria. El -directorio @file{per-user} se crea cuando se lanza @command{guix-daemon}, y -el subdirectorio @var{usuaria} es creado por @command{guix package}. - -Las @var{opciones} pueden ser las siguientes: - -@table @code - -@item --install=@var{paquete} @dots{} -@itemx -i @var{paquete} @dots{} -Instala los @var{paquete}s especificados. - -Cada @var{paquete} puede especificar un nombre simple de paquete, como por -ejemplo @code{guile}, o un nombre de paquete seguido por una arroba y el -número de versión, como por ejemplo @code{guile@@1.8.8} o simplemente -@code{guile@@1.8} (en el último caso la última versión con @code{1.8} como -prefijo es seleccionada). - -Si no se especifica un número de versión, la última versión disponible será -seleccionada. Además, @var{paquete} puede contener dos puntos, seguido por -el nombre de una de las salidas del paquete, como en @code{gcc:doc} o -@code{binutils@@2.22:lib} (@pxref{Paquetes con múltiples salidas}). Los -paquetes con el nombre correspondiente (y opcionalmente la versión) se -buscan entre los módulos de la distribución GNU (@pxref{Módulos de paquetes}). - -@cindex entradas propagadas -A veces los paquetes tienen @dfn{entradas propagadas}: estas son las -dependencias que se instalan automáticamente junto al paquete requerido -(@pxref{package-propagated-inputs, @code{propagated-inputs} in -@code{package} objects}, para información sobre las entradas propagadas en -las definiciones de paquete). - -@anchor{package-cmd-propagated-inputs} -Un ejemplo es la biblioteca GNU MPC: sus ficheros de cabecera C hacen -referencia a los de la biblioteca GNU MPFR, que a su vez hacen referencia a -los de la biblioteca GMP. Por tanto, cuando se instala MPC, las bibliotecas -MPFR y GMP también se instalan en el perfil; borrar MPC también borra MPFR y -GMP---a menos que también se hayan instalado explícitamente por la usuaria. - -Por otra parte, los paquetes a veces dependen de la definición de variables -de entorno para sus rutas de búsqueda (véase a continuación la explicación -de @code{--seach-paths}). Cualquier definición de variable de entorno que -falte o sea posiblemente incorrecta se informa aquí. - -@item --install-from-expression=@var{exp} -@itemx -e @var{exp} -Instala el paquete al que @var{exp} evalúa. - -@var{exp} debe ser una expresión Scheme que evalue a un objeto -@code{}. Esta opción es notablemente útil para desambiguar entre -variantes con el mismo nombre que un paquete, con expresiones como @code{(@@ -(gnu packages base) guile-final)}. - -Fíjese que esta opción instala la primera salida del paquete especificado, -lo cual puede ser insuficiente cuando se necesita una salida específica de -un paquete con múltiples salidas. - -@item --install-from-file=@var{fichero} -@itemx -f @var{fichero} -Instala el paquete que resulta de evaluar el código en @var{fichero}. - -Como un ejemplo, @var{fichero} puede contener una definición como esta -(@pxref{Definición de paquetes}): - -@example -@verbatiminclude package-hello.scm -@end example - -Las desarrolladoras pueden encontrarlo útil para incluir un fichero -@file{guix.scm} in la raíz del árbol de fuentes de su proyecto que puede ser -usado para probar imágenes de desarrollo y crear entornos de desarrollo -reproducibles (@pxref{Invocación de guix environment}). - -@item --remove=@var{paquete} @dots{} -@itemx -r @var{paquete} @dots{} -Borra los @var{paquete}s especificados. - -Como en @code{--install}, cada @var{paquete} puede especificar un número de -versión y/o un nombre de salida además del nombre del paquete. Por ejemplo, -@code{-r glibc:debug} eliminaría la salida @code{debug} de @code{glibc}. - -@item --upgrade[=@var{regexp} @dots{}] -@itemx -u [@var{regexp} @dots{}] -@cindex actualizar paquetes -Actualiza todos los paquetes instalados. Si se especifica una o más -expresiones regular @var{regexp}, actualiza únicamente los paquetes -instalados cuyo nombre es aceptado por @var{regexp}. Véase también la opción -@code{--do-not-upgrade} más adelante. - -Tenga en cuenta que esto actualiza los paquetes a la última versión -encontrada en la distribución instalada actualmente. Para actualizar su -distribución, debe ejecutar regularmente @command{guix pull} -(@pxref{Invocación de guix pull}). - -@item --do-not-upgrade[=@var{regexp} @dots{}] -Cuando se usa junto a la opción @code{--upgrade}, @emph{no} actualiza ningún -paquete cuyo nombre sea aceptado por @var{regexp}. Por ejemplo, para -actualizar todos los paquetes en el perfil actual excepto aquellos que -contengan la cadena ``emacs'': - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{fichero} -@itemx -m @var{fichero} -@cindex declaración del perfil -@cindex manifiesto del perfil -Crea una nueva generación del perfil desde el objeto de manifiesto devuelto -por el código Scheme en @var{fichero}. - -Esto le permite @emph{declarar} los contenidos del perfil en vez de -construirlo a través de una secuencia de @code{--install} y órdenes -similares. La ventaja es que @var{fichero} puede ponerse bajo control de -versiones, copiarse a máquinas diferentes para reproducir el mismo perfil, y -demás. - -@c FIXME: Add reference to (guix profile) documentation when available. -@var{fichero} debe devolver un objeto @dfn{manifest}, que es básicamente una -lista de paquetes: - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Usa una salida específica del paquete. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -En este ejemplo tenemos que conocer qué módulos definen las variables -@code{emacs} y @code{guile-2.0} para proporcionar la línea -@code{use-package-modules} correcta, lo cual puede ser complicado. En cambio -podemos proporcionar especificaciones regulares de paquetes y dejar a -@code{specifications->manifest} buscar los objetos de paquete -correspondientes así: - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex vuelta atrás -@cindex deshacer transacciones -@cindex transacciones, deshaciendo -Vuelve a la @dfn{generación} previa del perfil---es decir, deshace la última -transacción. - -Cuando se combina con opciones como @code{--install}, la vuelta atrás ocurre -antes que cualquier acción. - -Cuando se vuelve atrás en la primera generación que realmente contiene -paquetes instalados, se hace que el perfil apunte a la @dfn{generación -cero}, la cual no contiene ningún fichero a excepción de sus propios -metadatos. - -Después de haber vuelto atrás, instalar, borrar o actualizar paquetes -sobreescribe las generaciones futuras previas. Por tanto, la historia de las -generaciones en un perfil es siempre linear. - -@item --switch-generation=@var{patrón} -@itemx -S @var{patrón} -@cindex generaciones -Cambia a una generación particular definida por el @var{patrón}. - -@var{patrón} puede ser tanto un número de generación como un número -prefijado con ``+'' o ``-''. Esto último significa: mueve atrás/hacia -delante el número especificado de generaciones. Por ejemplo, si quiere -volver a la última generación antes de @code{--roll-back}, use -@code{--switch-generation=+1}. - -La diferencia entre @code{--roll-back} y @code{--switch-generation=-1} es -que @code{--switch-generation} no creará una generación cero, así que si la -generación especificada no existe, la generación actual no se verá cambiada. - -@item --search-paths[=@var{tipo}] -@cindex rutas de búsqueda -Informa de variables de entorno, en sintaxis Bash, que pueden necesitarse -para usar el conjunto de paquetes instalado. Estas variables de entorno se -usan para especificar las @dfn{rutas de búsqueda} para ficheros usadas por -algunos de los paquetes. - -Por ejemplo, GCC necesita que las variables de entorno @code{CPATH} y -@code{LIBRARY_PATH} estén definidas para poder buscar cabeceras y -bibliotecas en el perfil de la usuaria (@pxref{Environment Variables,,, gcc, -Using the GNU Compiler Collection (GCC)}). Si GCC y, digamos, la biblioteca -de C están instaladas en el perfil, entonces @code{--search-paths} sugerirá -fijar dichas variables a @code{@var{perfil}/include} y -@code{@var{perfil}/lib} respectivamente. - -El caso de uso típico es para definir estas variables de entorno en el -shell: - -@example -$ eval `guix package --search-paths` -@end example - -@var{tipo} puede ser @code{exact}, @code{prefix} o @code{suffix}, lo que -significa que las definiciones de variables de entorno devueltas serán -respectivamente las configuraciones exactas, prefijos o sufijos del valor -actual de dichas variables. Cuando se omite, el valor predeterminado de -@var{tipo} es @code{exact}. - -Esta opción puede usarse para calcular las rutas de búsqueda -@emph{combinadas} de varios perfiles. Considere este ejemplo: - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -La última orden informa sobre la variable @code{GUILE_LOAD_PATH}, aunque, -tomada individualmente, ni @file{foo} ni @file{bar} hubieran llevado a esa -recomendación. - - -@item --profile=@var{perfil} -@itemx -p @var{perfil} -Usa @var{perfil} en vez del perfil predeterminado de la usuaria. - -@cindex colisiones, en un perfil -@cindex paquetes con colisiones en perfiles -@cindex colisiones del perfil -@item --allow-collisions -Permite colisiones de paquetes en el nuevo perfil. ¡Úselo bajo su propio -riesgo! - -Por defecto, @command{guix package} informa como un error las -@dfn{colisiones} en el perfil. Las colisiones ocurren cuando dos o más -versiones diferentes o variantes de un paquete dado se han seleccionado para -el perfil. - -@item --bootstrap -Use el Guile usado para el lanzamiento para construir el perfil. Esta opción -es util únicamente a las desarrolladoras de la distribución. - -@end table - -Además de estas acciones, @command{guix package} acepta las siguientes -opciones para consultar el estado actual de un perfil, o la disponibilidad -de paquetes: - -@table @option - -@item --search=@var{regexp} -@itemx -s @var{regexp} -@cindex buscar paquetes -Enumera los paquetes disponibles cuyo nombre, sinopsis o descripción -corresponde con @var{regexp} (sin tener en cuenta la capitalización), -ordenados por relevancia. Imprime todos los metadatos de los paquetes -coincidentes en formato @code{recutils} (@pxref{Top, GNU recutils -databases,, recutils, GNU recutils manual}). - -Esto permite extraer campos específicos usando la orden @command{recsel}, -por ejemplo: - -@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 - -De manera similar, para mostrar el nombre de todos los paquetes disponibles -bajo los términos de la GNU@tie{}LGPL versión 3: - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -Es también posible refinar los resultados de búsqueda usando varias opciones -@code{-s}. Por ejemplo, la siguiente orden devuelve un lista de juegos de -mesa (board en inglés): - -@example -$ guix package -s '\' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -Si omitimos @code{-s game}, también obtendríamos paquetes de software que -tengan que ver con placas de circuitos impresos ("circuit board" en inglés); -borrar los signos mayor y menor alrededor de @code{board} añadiría paquetes -que tienen que ver con teclados (keyboard en inglés). - -Y ahora para un ejemplo más elaborado. La siguiente orden busca bibliotecas -criptográficas, descarta bibliotecas Haskell, Perl, Python y Ruby, e imprime -el nombre y la sinopsis de los paquetes resultantes: - -@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}, para más -información en @dfn{expresiones de selección} para @code{recsel -e}. - -@item --show=@var{paquete} -Muestra los detalles del @var{paquete}, tomado de la lista disponible de -paquetes, en formato @code{recutils} (@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 - -Tambien puede especificar el nombre completo de un paquete para únicamente -obtener detalles sobre una versión específica: -@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}] -Enumera los paquetes actualmente instalados en el perfil especificado, con -los últimos paquetes instalados mostrados al final. Cuando se especifica -@var{regexp}, enumera únicamente los paquetes instalados cuyos nombres son -aceptados por @var{regexp}. - -Por cada paquete instalado, imprime los siguientes elementos, separados por -tabuladores: el nombre del paquete, la cadena de versión, la parte del -paquete que está instalada (por ejemplo, @code{out} para la salida -predeterminada, @code{include} para sus cabeceras, etc.), y la ruta de este -paquete en el almacén. - -@item --list-available[=@var{regexp}] -@itemx -A [@var{regexp}] -Enumera los paquetes disponibles actualmente en la distribución para este -sistema (@pxref{Distribución GNU}). Cuando se especifica @var{regexp}, -enumera únicamente paquetes instalados cuyo nombre coincide con -@var{regexp}. - -Por cada paquete, imprime los siguientes elementos separados por -tabuladores: su nombre, su cadena de versión, las partes del paquete -(@pxref{Paquetes con múltiples salidas}) y la dirección de las fuentes de su -definición. - -@item --list-generations[=@var{patrón}] -@itemx -l [@var{patrón}] -@cindex generaciones -Devuelve una lista de generaciones junto a sus fechas de creación; para cada -generación, muestra los paquetes instalados, con los paquetes instalados más -recientemente mostrados los últimos. Fíjese que la generación cero nunca se -muestra. - -Por cada paquete instalado, imprime los siguientes elementos, separados por -tabuladores: el nombre de un paquete, su cadena de versión, la parte del -paquete que está instalada (@pxref{Paquetes con múltiples salidas}), y la -ruta de este paquete en el almacén. - -Cuando se usa @var{patrón}, la orden devuelve únicamente las generaciones -que se ajustan al patrón. Patrones válidos incluyen: - -@itemize -@item @emph{Enteros y enteros separados por comas}. Ambos patrones denotan -números de generación. Por ejemplo, @code{--list-generations=1} devuelve la -primera. - -Y @code{--list-generations=1,8,2} devuelve las tres generaciones en el orden -especificado. No se permiten ni espacios ni una coma al final. - -@item @emph{Rangos}. @code{--list-generations=2..9} imprime -las generaciones especificadas y todas las intermedias. Fíjese que el inicio -de un rango debe ser menor a su fin. - -También es posible omitir el destino final. Por ejemplo, -@code{--list-generations=2..} devuelve todas las generaciones empezando por -la segunda. - -@item @emph{Duraciones}. Puede también obtener los últimos @emph{N}@tie{}días, semanas, -o meses pasando un entero junto a la primera letra de la duración. Por -ejemplo, @code{--list-generations=20d} enumera las generaciones que tienen -hasta 20 días de antigüedad. -@end itemize - -@item --delete-generations[=@var{patrón}] -@itemx -d [@var{patrón}] -Cuando se omite @var{patrón}, borra todas las generaciones excepto la -actual. - -Esta orden acepta los mismos patrones que -@option{--list-generations}. Cuando se especifica un @var{patrón}, borra las -generaciones coincidentes. Cuando el @var{patrón} especifica una duración, -las generaciones @emph{más antiguas} que la duración especificada son las -borradas. Por ejemplo, @code{--delete-generations=1m} borra las generaciones -de más de un mes de antigüedad. - -Si la generación actual entra en el patrón, @emph{no} es borrada. Tampoco la -generación cero es borrada nunca. - -Fíjese que borrar generaciones previene volver atrás a -ellas. Consecuentemente esta orden debe ser usada con cuidado. - -@end table - -Finalmente, ya que @command{guix package} puede lanzar procesos de -construcción en realidad, acepta todas las opciones comunes de construcción -(@pxref{Opciones comunes de construcción}). También acepta opciones de transformación de -paquetes, como @option{--with-source} (@pxref{Opciones de transformación de paquetes}). No obstante, fíjese que las transformaciones del paquete se -pierden al actualizar; para preservar las transformaciones entre -actualizaciones, debe definir su propia variante del paquete en un módulo -Guile y añadirlo a @code{GUIX_PACKAGE_PATH} (@pxref{Definición de paquetes}). - -@node Sustituciones -@section Sustituciones - -@cindex sustituciones -@cindex binarios pre-construidos -Guix permite despliegues transparentes de fuentes/binarios, lo que significa -que puede tanto construir cosas localmente, como descargar elementos -preconstruidos de un servidor, o ambas. Llamamos a esos elementos -preconstruidos @dfn{sustituciones}---son sustituciones de los resultados de -construcciones locales. En muchos casos, descargar una sustitución es mucho -más rápido que construirla localmente. - -Las sustituciones pueden ser cualquier cosa que resulte de una construcción -de una derivación (@pxref{Derivaciones}). Por supuesto, en el caso común, son -paquetes binarios preconstruidos, pero los archivos de fuentes, por ejemplo, -que también resultan de construcciones de derivaciones, pueden estar -disponibles como sustituciones. - -@menu -* Servidor oficial de sustituciones.:: Una fuente particular de - sustituciones. -* Autorización de servidores de sustituciones:: Cómo habilitar o - deshabilitar - sustituciones. -* Verificación de sustituciones:: Cómo verifica las sustituciones Guix. -* Configuración de la pasarela.:: Cómo obtener sustituciones a través de - una pasarela. -* Fallos en las sustituciones:: Qué pasa cuando una sustitución falla. -* Sobre la confianza en binarios:: ¿Cómo puede usted confiar en esa masa - informe de datos binarios? -@end menu - -@node Servidor oficial de sustituciones. -@subsection Servidor oficial de sustituciones. - -@cindex hydra -@cindex granja de construcción -El servidor @code{@value{SUBSTITUTE-SERVER}} es una fachada a una granja de -construcción oficial que construye paquetes de Guix continuamente para -algunas arquitecturas, y los pone disponibles como sustituciones. Esta es la -fuente predeterminada de sustituciones; puede ser forzada a cambiar pasando -la opción @option{--substitute-urls} bien a @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) o -bien a herramientas cliente como @command{guix package} -(@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). - -Las URLs de sustituciones pueden ser tanto HTTP como HTTPS. Se recomienda -HTTPS porque las comunicaciones están cifradas; de modo contrario, usar HTTP -hace visibles todas las comunicaciones para alguien que las intercepte, -quien puede usar la información obtenida para determinar, por ejemplo, si su -sistema tiene vulnerabilidades de seguridad sin parchear. - -Las sustituciones de la granja de construcción oficial están habilitadas por -defecto cuando se usa la Distribución de sistema Guix (@pxref{Distribución GNU}). No obstante, están deshabilitadas por defecto cuando se usa -Guix en una distribución anfitriona, a menos que las haya habilitado -explícitamente via uno de los pasos recomendados de instalación -(@pxref{Instalación}). Los siguientes párrafos describen como habilitar o -deshabilitar sustituciones para la granja oficial de construcción; el mismo -procedimiento puede usarse para habilitar sustituciones de cualquier otro -servidor que las proporcione. - -@node Autorización de servidores de sustituciones -@subsection Autorización de servidores de sustituciones - -@cindex seguridad -@cindex sustituciones, autorización de las mismas -@cindex listas de control de acceso (ACL), para sustituciones -@cindex ACL (listas de control de acceso), para sustituciones -Para permitir a Guix descargar sustituciones de -@code{@value{SUBSTITUTE-SERVER}} o un espejo suyo, debe añadir su clave -pública a la lista de control de acceso (ACL) de las importaciones de -archivos, mediante el uso de la orden @command{guix archive} -(@pxref{Invocación de guix archive}). Hacerlo implica que confía que -@code{@value{SUBSTITUTE-SERVER}} no ha sido comprometido y proporciona -sustituciones genuinas. - -La clave pública para @code{@value{SUBSTITUTE-SERVER}} se instala junto a -Guix, en @code{@var{prefijo}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, -donde @var{prefijo} es el prefij de instalación de Guix. Si ha instalado -Guix desde las fuentes, debe asegurarse de que comprobó la firma GPG de -@file{guix-@value{VERSION}.tar.gz}, el cual contiene el fichero de clave -pública. Una vez hecho, puede ejecutar algo así: - -@example -# guix archive --authorize < @var{prefijo}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Nota -De manera similar, el fichero @file{hydra.gnu.org.pub} contiene la clave -pública para una granja de construcción independiente que también es parte -del proyecto, la cual se puede encontrar en -@indicateurl{https://mirror.hydra.gnu.org}. -@end quotation - -Una vez esté autorizada, la salida de una orden como @code{guix build} -debería cambiar de algo como: - -@example -$ guix build emacs --dry-run -The following derivations would be built: - /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 -a algo así: - -@example -$ guix build emacs --dry-run -112.3 MB would be downloaded: - /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 -Esto indica que las sustituciones de @code{@value{SUBSTITUTE-SERVER}} son -usables y serán descargadas, cuando sea posible, para construcciones -futuras. - -@cindex sustituciones, cómo deshabilitarlas -El mecanismo de sustituciones puede ser deshabilitado globalmente ejecutando -@code{guix-daemon} con @code{--no-subsitutes} (@pxref{Invocación de guix-daemon}). También puede ser deshabilitado temporalmente pasando la -opción @code{--no-substitutes} a @command{guix package}, @command{guix -build} y otras herramientas de línea de órdenes. - -@node Verificación de sustituciones -@subsection Verificación de sustituciones - -@cindex firmas digitales -Guix detecta y emite errores cuando se intenta usar una sustitución que ha -sido adulterado. Del mismo modo, ignora las sustituciones que no están -firmadas, o que no están firmadas por una de las firmas enumeradas en la -ACL. - -No obstante hay una excepción: si un servidor no autorizado proporciona -sustituciones que son @emph{idénticas bit-a-bit} a aquellas proporcionadas -por un servidor autorizado, entonces el servidor no autorizado puede ser -usado para descargas. Por ejemplo, asumiendo que hemos seleccionado dos -servidores de sustituciones con esta opción: - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex construcciones reproducibles -Si la ACL contiene únicamente la clave para @code{b.example.org}, y si -@code{a.example.org} resulta que proporciona @emph{exactamente las mismas} -sustituciones, Guix descargará sustituciones de @code{a.example.org} porque -viene primero en la lista y puede ser considerado un espejo de -@code{b.example.org}. En la práctica, máquinas de construcción -independientes producen habitualmente los mismos binarios, gracias a las -construcciones reproducibles bit-a-bit (véase a continuación). - -Cuando se usa HTTPS, el certificado X.509 del servidor @emph{no} se valida -(en otras palabras, el servidor no está verificado), lo contrario del -comportamiento habitual de los navegadores Web. Esto es debido a que Guix -verifica la información misma de las sustituciones, como se ha explicado -anteriormente, lo cual nos concierne (mientras que los certificados X.509 -tratan de verificar las conexiones entre nombres de dominio y claves -públicas). - -@node Configuración de la pasarela. -@subsection Configuración de la pasarela. - -@vindex http_proxy -Las sustituciones se descargan por HTTP o HTTPS. La variable de entorno -@code{http_proxy} puede ser incluida en el entorno de @command{guix-daemon} -y la respeta para las descargas de sustituciones. Fíjese que el valor de -@code{http_proxy} en el entorno en que @command{guix build}, @command{guix -package} y otras aplicaciones cliente se ejecuten @emph{no tiene ningún -efecto}. - -@node Fallos en las sustituciones -@subsection Fallos en las sustituciones - -Incluso cuando una sustitución de una derivación está disponible, a veces el -intento de sustitución puede fallar. Esto puede suceder por varias razones: -el servidor de sustituciones puede estar desconectado, la sustitución puede -haber sido borrada, la conexión puede interrumpirse, etc. - -Cuando las sustituciones están activadas y una sustitución para una -derivación está disponible, pero el intento de sustitución falla, Guix -intentará construir la derivación localmente dependiendo si se proporcionó -la opción @code{--fallback} (@pxref{fallback-option,, common build option -@code{--fallback}}). Específicamente, si no se pasó @code{--fallback}, no se -realizarán construcciones locales, y la derivación se considera se considera -fallida. No obstante, si se pasó @code{--fallback}, Guix intentará construir -la derivación localmente, y el éxito o fracaso de la derivación depende del -éxito o fracaso de la construcción local. Fíjese que cuando las -sustituciones están deshabilitadas o no hay sustituciones disponibles para -la derivación en cuestión, la construcción local se realizará -@emph{siempre}, independientemente de si se pasó la opción -@code{--fallback}. - -Para hacerse una idea de cuantas sustituciones hay disponibles en este -momento, puede intentar ejecutar la orden @command{guix weather} -(@pxref{Invocación de guix weather}). Esta orden proporciona estadísticas de las -sustituciones proporcionadas por un servidor. - -@node Sobre la confianza en binarios -@subsection Sobre la confianza en binarios - -@cindex confianza, de binarios pre-construidos -Hoy en día, el control individual sobre nuestra propia computación está a -merced de instituciones, empresas y grupos con suficiente poder y -determinación para subvertir la infraestructura de computación y explotar -sus vulnerabilidades. Mientras que usar las sustituciones de -@code{@value{SUBSTITUTE-SERVER}} puede ser conveniente, recomendamos a las -usuarias también construir sus paquetes, o incluso mantener su propia granja -de construcción, de modo que @code{@value{SUBSTITUTE-SERVER}} sea un -objetivo menos interesante. Una manera de ayudar es publicando el software -que construya usando @command{guix publish} de modo que otras tengan otro -servidor más como opción para descargar sustituciones (@pxref{Invocación de guix publish}). - -Guix tiene los cimientos para maximizar la reproducibilidad de las -construcciones (@pxref{Características}). En la mayor parte de los casos, -construcciones independientes de un paquete o derivación dada deben emitir -resultados idénticos bit a bit. Por tanto, a través de un conjunto diverso -de construcciones independientes de paquetes, podemos reforzar la integridad -de nuestros sistemas. La orden @command{guix challenge} intenta ayudar a las -usuarias en comprobar servidores de sustituciones, y asiste a las -desarrolladoras encontrando construcciones no deterministas de paquetes -(@pxref{Invocación de guix challenge}). Similarmente, la opción @option{--check} -de @command{guix build} permite a las usuarias si las sustituciones -previamente instaladas son genuinas reconstruyendolas localmente -(@pxref{build-check, @command{guix build --check}}). - -En el futuro, queremos que Guix permita la publicación y obtención de -binarios hacia/desde otras usuarias, entre pares (P2P). En caso de -interesarle hablar sobre este proyecto, unase a nosotras en -@email{guix-devel@@gnu.org}. - -@node Paquetes con múltiples salidas -@section Paquetes con múltiples salidas - -@cindex paquetes de salida múltiple -@cindex salidas del paquete -@cindex salidas - -Habitualmente, los paquetes definidos en Guix tienen una @dfn{salida} -única---es decir, el paquete de fuentes proporcionará exactamente un -directorio en el almacén. Cuando se ejecuta @command{guix package -i glibc}, -se instala la salida predeterminada del paquete GNU libc; la salida -predeterminada se llama @code{out}, pero su nombre puede omitirse como se -mostró en esta orden. En este caso particular, la salida predeterminada de -@code{glibc} contiene todos ficheros de cabecera C, bibliotecas dinámicas, -bibliotecas estáticas, documentación Info y otros ficheros auxiliares. - -A veces es más apropiado separar varios tipos de ficheros producidos por un -paquete único de fuentes en salidas separadas. Por ejemplo, la biblioteca C -GLib (usada por GTK+ y paquetes relacionados) instala más de 20 MiB de -documentación de referencia como páginas HTML. Para ahorrar espacio para -usuarias que no la necesiten, la documentación va a una salida separada, -llamada @code{doc}. Para instalar la salida principal de GLib, que contiene -todo menos la documentación, se debe ejecutar: - -@example -guix package -i glib -@end example - -@cindex documentación -La orden que instala su documentación es: - -@example -guix package -i glib:doc -@end example - -Algunos paquetes instalan programas con diferentes ``huellas de -dependencias''. Por ejemplo, el paquete WordNet instala tanto herramientas -de línea de órdenes como interfaces gráficas de usuaria (IGU). Las primeras -dependen únicamente de la biblioteca de C, mientras que las últimas dependen -en Tcl/Tk y las bibliotecas de X subyacentes. En este caso, dejamos las -herramientas de línea de órdenes en la salida predeterminada, mientras que -las IGU están en una salida separada. Esto permite a las usuarias que no -necesitan una IGU ahorrar espacio. La orden @command{guix size} puede ayudar -a exponer estas situaciones (@pxref{Invocación de guix size}). @command{guix -graph} también puede ser útil (@pxref{Invocación de guix graph}). - -Hay varios de estos paquetes con salida múltiple en la distribución -GNU. Otros nombres de salida convencionales incluyen @code{lib} para -bibliotecas y posiblemente ficheros de cabecera, @code{bin} para programas -independientes y @code{debug} para información de depuración -(@pxref{Instalación de ficheros de depuración}). La salida de los paquetes se enumera -en la tercera columna del resultado de @command{guix package ---list-available} (@pxref{Invocación de guix package}). - - -@node Invocación de guix gc -@section Invocación de @command{guix gc} - -@cindex recolector de basura -@cindex espacio en disco -Los paquetes instalados, pero no usados, pueden ser @dfn{recolectados}. La -orden @command{guix gc} permite a las usuarias ejecutar explícitamente el -recolector de basura para reclamar espacio del directorio -@file{/gnu/store}---¡borrar ficheros o directorios manualmente puede dañar -el almacén sin reparación posible! - -@cindex GC, raíces del recolector de basura -@cindex raíces del recolector de basura -El recolector de basura tiene un conjunto de @dfn{raíces} conocidas: -cualquier fichero en @file{/gnu/store} alcanzable desde una raíz se -considera @dfn{vivo} y no puede ser borrado; cualquier otro fichero se -considera @dfn{muerto} y puede ser borrado. El conjunto de raíces del -recolector de basura (``raíces del GC'' para abreviar) incluye los perfiles -predeterminados de las usuarias; por defecto los enlaces bajo -@file{/var/guix/gcroots} representan dichas raíces. Por ejemplo, nuevas -raíces del GC pueden añadirse con @command{guix build --root} -(@pxref{Invocación de guix build}). La orden @command{guix gc --list-roots} las -enumera. - -Antes de ejecutar @code{guix gc --collect-garbage} para liberar espacio, -habitualmente es útil borrar generaciones antiguas de los perfiles de -usuaria; de ese modo, las construcciones antiguas de paquetes referenciadas -por dichas generaciones puede ser reclamada. Esto se consigue ejecutando -@code{guix package --delete-generations} (@pxref{Invocación de guix package}). - -Nuestra recomendación es ejecutar una recolección de basura periódicamente, -o cuando tenga poco espacio en el disco. Por ejemplo, para garantizar que al -menos 5@tie{}GB están disponibles en su disco, simplemente ejecute: - -@example -guix gc -F 5G -@end example - -Es completamente seguro ejecutarla como un trabajo periódico no-interactivo -(@pxref{Ejecución de tareas programadas}, para la configuración de un trabajo de ese -tipo). La ejecución de @command{guix gc} sin ningún parámetro recolectará -tanta basura como se pueda, pero eso es no es normalmente conveniente: puede -encontrarse teniendo que reconstruir o volviendo a bajar software que está -``muerto'' desde el punto de vista del recolector pero que es necesario para -construir otras piezas de software---por ejemplo, la cadena de herramientas -de compilación. - -La orden @command{guix gc} tiene tres modos de operación: puede ser usada -para recolectar ficheros muertos (predeterminado), para borrar ficheros -específicos (la opción @code{--delete}), para mostrar información sobre la -recolección de basura o para consultas más avanzadas. Las opciones de -recolección de basura son las siguientes: - -@table @code -@item --collect-garbage[=@var{min}] -@itemx -C [@var{min}] -Recolecta basura---es decir, ficheros no alcanzables de @file{/gnu/store} y -subdirectorios. Esta operación es la predeterminada cuando no se especifican -opciones. - -Cuando se proporciona @var{min}, para una vez que @var{min} bytes han sido -recolectados. @var{min} puede ser un número de bytes, o puede incluir una -unidad como sufijo, como @code{MiB} para mebibytes y @code{GB} para -gigabytes (@pxref{Block size, size specifications,, coreutils, GNU -Coreutils}). - -Cuando se omite @var{min}, recolecta toda la basura. - -@item --free-space=@var{libre} -@itemx -F @var{libre} -Recolecta basura hasta que haya espacio @var{libre} bajo @file{/gnu/store}, -si es posible: @var{libre} denota espacio de almacenamiento, por ejemplo -@code{500MiB}, como se ha descrito previamente. - -Cuando @var{libre} o más está ya disponible en @file{/gnu/store}, no hace -nada y sale inmediatamente. - -@item --delete-generations[=@var{duración}] -@itemx -d [@var{duración}] -Antes de comenzar el proceso de recolección de basura, borra todas las -generaciones anteriores a @var{duración}, para todos los perfiles de la -usuaria; cuando se ejecuta como root esto aplica a los perfiles de -@emph{todas las usuarias}. - -Por ejemplo, esta orden borra todas las generaciones de todos sus perfiles -que tengan más de 2 meses de antigüedad (excepto generaciones que sean las -actuales), y una vez hecho procede a liberar espacio hasta que al menos 10 -GiB estén disponibles: - -@example -guix gc -d 2m -F 10G -@end example - -@item --delete -@itemx -D -Intenta borrar todos los ficheros del almacén y directorios especificados -como parámetros. Esto falla si alguno de los ficheros no están en el -almacén, o todavía están vivos. - -@item --list-failures -Enumera los elementos del almacén correspondientes a construcciones fallidas -existentes en la caché. - -Esto no muestra nada a menos que el daemon se haya ejecutado pasando -@option{--cache-failures} (@pxref{Invocación de guix-daemon, -@option{--cache-failures}}). - -@item --list-roots -Enumera las raices del recolector de basura poseidas por la usuaria; cuando -se ejecuta como root, enumera @emph{todas} las raices del recolector de -basura. - -@item --clear-failures -Borra los elementos especificados del almacén de la caché de construcciones -fallidas. - -De nuevo, esta opción únicamente tiene sentido cuando el daemon se inicia -con @option{--cache-failures}. De otro modo, no hace nada. - -@item --list-dead -Muestra la lista de ficheros y directorios muertos todavía presentes en el -almacén---es decir, ficheros y directorios que ya no se pueden alcanzar -desde ninguna raíz. - -@item --list-live -Muestra la lista de ficheros y directorios del almacén vivos. - -@end table - -Además, las referencias entre los ficheros del almacén pueden ser -consultadas: - -@table @code - -@item --references -@itemx --referrers -@cindex dependencias de un paquete -Enumera las referencias (o, respectivamente, los referentes) de los ficheros -del almacén pasados como parámetros. - -@item --requisites -@itemx -R -@cindex clausura -Enumera los requistos los ficheros del almacén pasados como parámetros. Los -requisitos incluyen los mismos ficheros del almacén, sus referencias, las -referencias de estas, recursivamente. En otras palabras, la lista devuelta -es la @dfn{clausura transitiva} de los ficheros del almacén. - -@xref{Invocación de guix size}, para una herramienta que perfila el tamaño de la -clausura de un elemento. @xref{Invocación de guix graph}, para una herramienta de -visualización del grafo de referencias. - -@item --derivers -@cindex derivación -Devuelve la/s derivación/es que conducen a los elementos del almacén dados -(@pxref{Derivaciones}). - -Por ejemplo, esta orden: - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -devuelve el/los fichero/s @file{.drv} que conducen al paquete @code{emacs} -instalado en su perfil. - -Fíjese que puede haber cero ficheros @file{.drv} encontrados, por ejemplo -porque estos ficheros han sido recolectados. Puede haber más de un fichero -@file{.drv} encontrado debido a derivaciones de salida fija. -@end table - -Por último, las siguientes opciones le permiten comprobar la integridad del -almacén y controlar el uso del disco. - -@table @option - -@item --verify[=@var{opciones}] -@cindex integridad, del almacén -@cindex comprobación de integridad -Verifica la integridad del almacén. - -Por defecto, comprueba que todos los elementos del almacén marcados como -válidos en la base de datos del daemon realmente existen en -@file{/gnu/store}. - -Cuando se proporcionan, @var{opciones} debe ser una lista separada por comas -que contenga uno o más valores @code{contents} and @code{repair}. - -Cuando se usa @option{--verify=contents}, el daemon calcula el hash del -contenido de cada elemento del almacén y lo compara contra el hash de su -base de datos. Las incongruencias se muestran como corrupciones de -datos. Debido a que recorre @emph{todos los ficheros del almacén}, esta -orden puede tomar mucho tiempo, especialmente en sistemas con una unidad de -disco lenta. - -@cindex reparar el almacén -@cindex corrupción, recuperarse de -El uso de @option{--verify=repair} o @option{--verify=contents,repair} hace -que el daemon intente reparar elementos corruptos del almacén obteniendo -sustituciones para dichos elementos (@pxref{Sustituciones}). Debido a que la -reparación no es atómica, y por tanto potencialmente peligrosa, está -disponible únicamente a la administradora del sistema. Una alternativa -ligera, cuando sabe exactamente qué elementos del almacén están corruptos, -es @command{guix build --repair} (@pxref{Invocación de guix build}). - -@item --optimize -@cindex deduplicación -Optimiza el almacén sustituyendo ficheros idénticos por enlaces duros---esto -es la @dfn{deduplicación}. - -El daemon realiza la deduplicación después de cada construcción -satisfactoria o importación de archivos, a menos que se iniciase con -@code{--disable-deduplication} (@pxref{Invocación de guix-daemon, -@code{--disable-deduplication}}). Por tanto, esta opción es útil -primariamente cuando el daemon se estaba ejecutando con -@code{--disable-deduplication}. - -@end table - -@node Invocación de guix pull -@section Invocación de @command{guix pull} - -@cindex actualizar Guix -@cindex actualizar la versión de Guix -@cindex @command{guix pull} -@cindex pull -Los paquetes se instalan o actualizan con la última versión disponible en la -distribución disponible actualmente en su máquina local. Para actualizar -dicha distribución, junto a las herramientas de Guix, debe ejecutar -@command{guix pull}: esta orden descarga el último código fuente de Guix y -descripciones de paquetes, y lo despliega. El código fuente se descarga de -un repositorio @uref{https://git-scm.com, Git}, por defecto el repositorio -oficial de GNU@tie{}Guix, lo que no obstante puede ser personalizado. - -Una vez completada, @command{guix package} usará paquetes y versiones de -paquetes de esta copia recién obtenida de Guix. No solo eso, sino que todas -las órdenes de Guix y los módulos Scheme también se tomarán de la última -versión. Nuevas sub-órdenes @command{guix} incorporadas por la actualización -también estarán disponibles. - -Cualquier usuaria puede actualizar su copia de Guix usando @command{guix -pull}, y el efecto está limitado a la usuaria que ejecutó @command{guix -pull}. Por ejemplo, cuando la usuaria @code{root} ejecuta @command{guix -pull}, esto no tiene ningún efecto en la versión del Guix que la usuaria -@code{alicia} ve, y viceversa. - -El resultado de ejecutar @command{guix pull} es un @dfn{perfil} disponible -bajo @file{~/.config/guix/current} conteniendo el último Guix. Por tanto, -asegurese de añadirlo al inicio de sus rutas de búsqueda de modo que use la -última versión, de modo similar para el manual Info(@pxref{Documentación}). - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -Las opciones @code{--list-generations} o @code{-l} enumeran las generaciones -pasadas producidas por @command{guix pull}, junto a detalles de su -procedencia: - -@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 - -@ref{Invocación de guix describe, @command{guix describe}}, para otras formas de -describir el estado actual de Guix. - -El perfil @code{~/.config/guix/current} funciona como cualquier otro perfil -creado por @command{guix package} (@pxref{Invocación de guix package}). Esto es, -puede enumerar generaciones, volver a una generación previa---es decir, el -Guix anterior---y más: - -@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/carlos/current-guix-1-link -@end example - -La orden @command{guix pull} se invoca habitualmente sin parámetros, pero -permite las siguientes opciones: - -@table @code -@item --url=@var{url} -@itemx --commit=@var{revisión} -@itemx --branch=@var{rama} -Download code for the @code{guix} channel from the specified @var{url}, at -the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@cindex @file{channels.scm}, fichero de configuración -@cindex fichero de configuración de canales -Estas opciones se proporcionan por conveniencia, pero también puede -especificar su configuración en el fichero -@file{~/.config/guix/channels.scm} o usando la opción @option{--channels} -(vea más adelante). - -@item --channels=@var{fichero} -@itemx -C @var{fichero} -Lee la lista de canales de @var{fichero} en vez de -@file{~/.config/guix/channels.scm}. @var{fichero} debe contener código -Scheme que evalue a una lista de objetos channel. @xref{Canales}, para más -información. - -@item --news -@itemx -N -Display the list of packages added or upgraded since the previous -generation. - -This is the same information as displayed upon @command{guix pull} -completion, but without ellipses; it is also similar to the output of -@command{guix pull -l} for the last generation (see below). - -@item --list-generations[=@var{patrón}] -@itemx -l [@var{patrón}] -Enumera todas las generaciones de @file{~/.config/guix/current} o, si se -proporciona un @var{patrón}, el subconjunto de generaciones que correspondan -con el @var{patrón}. La sintaxis de @var{patrón} es la misma que @code{guix -package --list-generations} (@pxref{Invocación de guix package}). - -@ref{Invocación de guix describe}, para una forma de mostrar información sobre -únicamente la generación actual. - -@item --profile=@var{perfil} -@itemx -p @var{perfil} -Usa @var{perfil} en vez de @file{~/.config/guix/current}. - -@item --dry-run -@itemx -n -Muestra qué revisión/es del canal serían usadas y qué se construiría o -sustituiría, sin efectuar ninguna acción real. - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Intenta construir paquetes para @var{sistema}---por ejemplo, -@code{x86_64-linux}---en vez del tipo de sistema de la máquina de -construcción. - -@item --verbose -Produce salida prolija, escribiendo los logs de construcción por la salida -de error estándar. - -@item --bootstrap -Use el Guile usado para el lanzamiento para construir el último Guix. Esta -opción es útil para las desarrolladoras de Guix únicamente. -@end table - -El mecanismo de @dfn{canales} le permite instruir a @command{guix pull} de -qué repositorio y rama obtener los datos, así como repositorios -@emph{adicionales} que contengan módulos de paquetes que deben ser -desplegados. @xref{Canales}, para más información. - -Además, @command{guix pull} acepta todas las opciones de construcción -comunes (@pxref{Opciones comunes de construcción}). - -@node Canales -@section Canales - -@cindex channels -@cindex @file{channels.scm}, fichero de configuración -@cindex fichero de configuración de canales -@cindex @command{guix pull}, fichero de configuración -@cindex configuración de @command{guix pull} -Guix y su colección de paquetes son actualizados ejecutando @command{guix -pull} (@pxref{Invocación de guix pull}). Por defecto @command{guix pull} descarga -y despliega el mismo Guix del repositorio oficial de GNU@tie{}Guix. Esto -puede ser personalizado definiendo @dfn{canales} en el fichero -@file{~/.config/guix/channels.scm}. Un canal especifica una URL y una rama -de un repositorio Git para ser desplegado, y @command{guix pull} puede ser -instruido para tomar los datos de uno o más canales. En otras palabras, los -canales se pueden usar para @emph{personalizar} y para @emph{extender} Guix, -como vemos a continuación. - -@subsection Uso de un canal de Guix personalizado - -El canal llamado @code{guix} especifica de donde el mismo Guix---sus -herramientas de línea de órdenes y su colección de paquetes---debe ser -descargado. Por ejemplo, suponga que quiere actualizar de su propia copia -del repositorio Guix en @code{example.org}, y específicamente la rama -@code{super-hacks}, para ello puede escribir en -@code{~/.config/guix/channels.scm} esta especificación: - -@lisp -;; Le dice a 'guix pull' que use mi propio repositorio. -(list (channel - (name 'guix) - (url "https://example.org/mi-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -De aquí en adelante, @command{guix pull} obtendrá el código de la rama -@code{super-hacks} del repositorio en @code{example.org}. - -@subsection Especificación de canales adicionales - -@cindex extender la colección de paquetes (canales) -@cindex paquetes personales (canales) -@cindex canales, para paquetes personales -También puede especificar @emph{canales adicionales} de los que obtener -datos. Digamos que tiene un montón de variaciones personalizadas de paquetes -que piensa que no tiene mucho sentido contribuir al proyecto Guix, pero -quiere tener esos paquetes disponibles transparentemente en su línea de -órdenes. Primero escribiría módulos que contengan esas definiciones de -paquete (@pxref{Módulos de paquetes}), los mantendría en un repositorio Git, y -entonces usted y cualquier otra persona podría usarlos como un canal -adicional del que obtener paquetes. Limpio, ¿no? - -@c What follows stems from discussions at -@c as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Aviso -Antes de que, querida usuaria, grite---``¡Guau, esto es @emph{la -caña}!''---y publique su canal personal al mundo, nos gustaría compartir -algunas palabras de precaución: - -@itemize -@item -Antes de publicar un canal, por favor considere contribuir sus definiciones -de paquete al propio Guix (@pxref{Contribuir}). Guix como proyecto es -abierto a software libre de todo tipo, y los paquetes en el propio Guix -están disponibles para todas las usuarias de Guix y se benefician del -proceso de gestión de calidad del proyecto. - -@item -Cuando mantiene definiciones de paquete fuera de Guix, nosotras, las -desarrolladoras de Guix, consideramos que @emph{la carga de la -compatibilidad cae de su lado}. Recuerde que los módulos y definiciones de -paquetes son solo código Scheme que usa varias interfaces programáticas -(APIs). Queremos mantener la libertad de cambiar dichas interfaces para -seguir mejorando Guix, posiblemente en formas que pueden romper su -canal. Nunca cambiamos las interfaces gratuitamente, pero @emph{no} vamos -tampoco a congelar las interfaces. - -@item -Corolario: si está usando un canal externo y el canal se rompe, por favor -@emph{informe del problema a las autoras del canal}, no al proyecto Guix. -@end itemize - -¡Ha quedado advertida! Habiendo dicho esto, creemos que los canales externos -son una forma práctica de ejercitar su libertad para aumentar la colección -de paquetes de Guix y compartir su mejoras, que son pilares básicos del -@uref{https://www.gnu.org/philosophy/free-sw.html, software libre}. Por -favor, envíenos un correo a @email{guix-devel@@gnu.org} si quiere hablar -sobre esto. -@end quotation - -Para usar un canal, escriba en @code{~/.config/guix/channels.scm} para -instruir a @command{guix pull} para obtener datos de él @emph{además} de los -canales Guix predeterminados: - -@vindex %default-channels -@lisp -;; Añade mis paquetes personales a aquellos que Guix provee. -(cons (channel - (name 'mis-paquetes-personales) - (url "https://example.org/paquetes-personales.git")) - %default-channels) -@end lisp - -@noindent -Fíjese que el fragmento previo es (¡como siempre!)@: código Scheme; usamos -@code{cons} para añadir un canal a la lista de canales a la que la variable -@code{%default-channels} hace referencia (@pxref{Pairs, @code{cons} and -lists,, guile, GNU Guile Reference Manual}). Con el fichero en este lugar, -@command{guix pull} no solo construye Guix sino también los módulos de -paquetes de su propio repositorio. El resultado en -@file{~/.config/guix/current} es la unión de Guix con sus propios módulos de -paquetes: - -@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 - mis-paquetes-personales dd3df5e - repository URL: https://example.org/paquetes-personales.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: mi-gimp, mi-emacs-con-cosas, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -La salida de @command{guix pull} previa muestra que la generación@tie{}19 -incluye tanto Guix como paquetes del canal -@code{mis-paquetes-personales}. Entre los paquetes nuevos y actualizados que -son enumerados, algunos como @code{mi-gimp} y @code{mi-emacs-con-cosas} -pueden venir de @code{mis-paquetes-personales}, mientras que otros vienen -del canal predeterminado de Guix. - -Para crear uncanal, cree un repositorio Git que contenga sus propios módulos -de paquetes y haga que esté disponible. El repositorio puede contener -cualquier cosa, pero un canal útil contendrá módulos Guile que exportan -paquetes. Una vez comience a usar un canal, Guix se comportará como si el -directorio raíz del repositorio Git de dicho canal hubiese sido añadido a la -ruta de carga de Guile (@pxref{Load Paths,,, guile, GNU Guile Reference -Manual}). Por ejemplo, si su canal contiene un fichero en -@file{mis-paquetes/mis-herramientas.scm} que define un módulo, entonces -dicho módulo estará disponible bajo el nombre @code{(mis-paquetes -mis-herramientas)}, y podrá usarlo como cualquier otro módulo -(@pxref{Módulos,,, guile, GNU Guile Reference Manual}). - -@cindex dependencias, canales -@cindex metadatos, canales -@subsection Declaración de dependencias de canales - -Las autoras de canales pueden decidir aumentar una colección de paquetes -proporcionada por otros canales. Pueden declarar su canal como dependiente -de otros canales en el fichero de metadatos @file{.guix-channel}, que debe -encontrarse en la raíz del repositorio del canal. - -Este fichero de metadatos debe contener una expresión-S simple como esta: - -@lisp -(channel - (version 0) - (dependencies - (channel - (name una-coleccion) - (url "https://example.org/primera-coleccion.git")) - (channel - (name otra-coleccion) - (url "https://example.org/segunda-coleccion.git") - (branch "pruebas")))) -@end lisp - -En el ejemplo previo, este canal se declara como dependiente de otros dos -canales, que se obtendrán de manera automática. Los módulos proporcionados -por el canal se compilarán en un entorno donde los módulos de todos estos -canales declarados estén disponibles. - -De cara a la confianza proporcionada y el esfuerzo que supondrá su -mantenimiento, debería evitar depender de canales que no controle, y debería -intentar minimizar el número de dependencias. - -@subsection Replicación de Guix - -@cindex clavar, canales -@cindex replicar Guix -@cindex reproducibilidad, de Guix -La salida de @command{guix pull --list-generations} previa muestra -precisamente qué revisiones se usaron para construir esta instancia de -Guix. Por tanto podemos replicarla, digamos, en otra máquina, proporcionando -una especificaciones de canales en @file{~/.config/guix/channels.scm} que -está ``clavada'' en estas revisiones: - -@lisp -;; Despliega unas revisiones específicas de mis canales de interés. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) - (channel - (name 'mis-paquetes-personales) - (url "https://example.org/paquetes-personales.git") - (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -La orden @command{guix describe --format=channels} puede incluso generar -esta lista de canales directamente (@pxref{Invocación de guix describe}). - -En este punto las dos máquinas ejecutan @emph{exactamente el mismo Guix}, -con acceso a @emph{exactamente los mismos paquetes}. La salida de -@command{guix build gimp} en una máquina debe ser exactamente la misma, bit -a bit, que la salida de la misma orden en la otra máquina. Esto también -significa que ambas máquinas tienen acceso a todo el código fuente de Guix -y, transitiamente, a todo el código fuente de cada paquete que define. - -Esto le proporciona superpoderes, permitiendole seguir la pista de la -procedencia de los artefactos binarios con un grano muy fino, y reproducir -entornos de software a su voluntad---un tipo de capacidad de -``meta-reproducibilidad'', si lo desea. @xref{Inferiores}, para otro modo de -tomar ventaja de estos superpoderes. - -@node Inferiores -@section Inferiores - -@c TODO: Remove this once we're more confident about API stability. -@quotation Nota -La funcionalidad descrita aquí es una ``versión de evaluación tecnológica'' -en la versión @value{VERSION}. Como tal, la interfaz está sujeta a cambios. -@end quotation - -@cindex inferiores -@cindex composición de revisiones de Guix -A veces necesita mezclar paquetes de revisiones de la revisión de Guix que -está ejecutando actualmente con paquetes disponibles en una revisión -diferente. Los @dfn{inferiores} de Guix le permiten conseguirlo componiendo -diferentes revisiones de Guix de modo arbitrario. - -@cindex paquetes inferiores -Técnicamente, un ``inferior'' es esencialmente un proceso Guix separado -conectado con su Guix principal a través de una sesión interactiva -(@pxref{Invocación de guix repl}). El módulo @code{(guix inferior)} le permite -crear inferiores y comunicarse con ellos. También proporciona una interfaz -de alto nivel para buscar y manipular los paquetes que un inferior -proporciona---@dfn{paquetes de inferiores}. - -Cuando se combina con los canales (@pxref{Canales}), los inferiores -proporcionan una forma simple de interactuar con una revisión separada de -Guix. Por ejemplo, asumamos que desea instalar en su perfil el paquete -@code{guile} actual, junto al paquete @code{guile-json} como existía en una -revisión más antigua de Guix---quizá porque las versiones nuevas de -@code{guile-json} tienen un API incompatible y quiere ejecutar su código -contra la API antigua. Para hacerlo, puede escribir un manifiesto para -usarlo con @code{guix package --manifest} (@pxref{Invocación de guix package}); -en dicho manifiesto puede crear un inferior para esa versión antigua de Guix -que le interesa, y buscará el paquete @code{guile-json} en el inferior: - -@lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;para 'first' - -(define channels - ;; Esta es la revisión antigua de donde queremos - ;; extraer guile-json. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) - -(define inferior - ;; Un inferior que representa la revisión previa. - (inferior-for-channels channels)) - -;; Ahora crea un manifiesto con el paquete "guile" actual -;; y el antiguo paquete "guile-json". -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) -@end lisp - -En su primera ejecución, @command{guix package --manifest} puede tener que -construir el canal que especificó antes de crear el inferior; las siguientes -ejecuciones serán mucho más rápidas porque la revisión de Guix estará en la -caché. - -El módulo @code{(guix inferior)} proporciona los siguientes procedimientos -para abrir un inferior: - -@deffn {Procedimiento Scheme} inferior-for-channels @var{canales} @ - [#:cache-directory] [#:ttl] -Devuelve un inferior para @var{canales}, una lista de canales. Usa la caché -en @var{cache-directory}, donde las entradas pueden ser reclamadas después -de @var{ttl} segundos. Este procedimiento abre una nueva conexión al daemon -de construcción. - -Como efecto secundario, este procedimiento puede construir o sustituir -binarios para @var{canales}, lo cual puede tomar cierto tiempo. -@end deffn - -@deffn {Procedimiento Scheme} open-inferior @var{directorio} @ - [#:command "bin/guix"] -Abre el Guix inferior en @var{directorio}, ejecutando -@code{@var{directorio}/@var{command} repl} o su equivalente. Devuelve -@code{#f} si el inferior no pudo ser ejecutado. -@end deffn - -@cindex paquetes inferiores -Los procedimientos enumerados a continuación le permiten obtener y manipular -paquetes de inferiores. - -@deffn {Procedimiento Scheme} inferior-packages @var{inferior} -Devuelve la lista de paquetes conocida por @var{inferior}. -@end deffn - -@deffn {Procedimiento Scheme} lookup-inferior-packages @var{inferior} @var{nombre} @ - [@var{versión}] -Devuelve la lista ordenada de paquetes del inferior que corresponden con -@var{nombre} en @var{inferior}, con los números de versión más altos -primero. Si @var{versión} tiene un valor verdadero, devuelve únicamente -paquetes con un número de versión cuyo prefijo es @var{versión}. -@end deffn - -@deffn {Procedimiento Scheme} inferior-package? @var{obj} -Devuelve verdadero si @var{obj} es un paquete inferior. -@end deffn - -@deffn {Procedimiento Scheme} inferior-package-name @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-version @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-synopsis @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-description @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-home-page @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-location @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-inputs @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-native-inputs @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-propagated-inputs @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-transitive-propagated-inputs @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-native-search-paths @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-transitive-native-search-paths @var{paquete} -@deffnx {Procedimiento Scheme} inferior-package-search-paths @var{paquete} -Estos procedimientos son la contraparte de los accesos a los registros de -pquete (@pxref{Referencia de ``package''}). La mayor parte funcionan interrogando al -inferior del que @var{paquete} viene, por lo que el inferior debe estar vivo -cuando llama a dichos procedimientos. -@end deffn - -Los paquetes de inferiores pueden ser usados transparentemente como -cualquier otro paquete u objeto-tipo-fichero en expresiones-G -(@pxref{Expresiones-G}). También se manejan transparentemente por el -procedimiento @code{packages->manifest}, el cual se usa habitualmente en los -manifiestos (@pxref{Invocación de guix package, the @option{--manifest} option of -@command{guix package}}). Por tanto puede insertar un paquete de inferior -prácticamente en cualquier lugar que pueda insertar un paquete normal: en -manifiestos, en el campo @code{packages} de su declaración -@code{operating-system}, etcétera. - -@node Invocación de guix describe -@section Invocación de @command{guix describe} - -@cindex reproducibilidad -@cindex replicar Guix -A menudo desea responder a preguntas como: ``¿Qué revisión de Guix estoy -usando?'' o ``¿Qué canales estoy usando?'' Esto es una información muy útil -en muchas situaciones: si quiere @emph{replicar} un entorno en una máquina -diferente o cuenta de usuaria, si desea informar de un error o determinar -qué cambio en los canales que usa lo causó, o si quiere almacenar el estado -de su sistema por razones de reproducibilidad. La orden @command{guix -describe} responde a estas preguntas. - -Cuando se ejecuta desde un @command{guix} bajado con @command{guix pull}, -@command{guix describe} muestra el/los canal/es desde el/los que se -construyó, incluyendo la URL de su repositorio y los IDs de las revisiones -(@pxref{Canales}): - -@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 - -Si está familiarizado con el sistema de control de versiones Git, esto es -similar a @command{git describe}; la salida también es similar a la de -@command{guix pull --list-generations}, pero limitada a la generación actual -(@pxref{Invocación de guix pull, the @option{--list-generations} option}). Debido -a que el ID de revisión Git mostrado antes refiere sin ambigüedades al -estado de Guix, esta información es todo lo necesario para describir la -revisión de Guix que usa, y también para replicarla. - -Para facilitar la replicación de Guix, también se le puede solicitar a -@command{guix describe} devolver una lista de canales en vez de la -descripción legible por humanos mostrada antes: - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -Puede almacenar esto en un fichero y pasarselo a @command{guix pull -C} en -otra máquina o en un momento futuro, lo cual instanciará @emph{esta revisión -exacta de Guix} (@pxref{Invocación de guix pull, the @option{-C} option}). De -aquí en adelante, ya que puede desplegar la misma revisión de Guix, puede -también @emph{replicar un entorno completo de software}. Nosotras -humildemente consideramos que esto es @emph{impresionante}, ¡y esperamos que -le guste a usted también! - -Los detalles de las opciones aceptadas por @command{guix describe} son las -siguientes: - -@table @code -@item --format=@var{formato} -@itemx -f @var{formato} -Produce salida en el @var{formato} especificado, uno de: - -@table @code -@item human -produce salida legible por humanos; -@item channels -produce una lista de especificaciones de canales que puede ser pasada a -@command{guix pull -C} o instalada como @file{~/.config/guix/channels.scm} -(@pxref{Invocación de guix pull}); -@item json -@cindex JSON -produce una lista de especificaciones de canales en formato JSON; -@item recutils -produce una lista de especificaciones de canales en formato Recutils. -@end table - -@item --profile=@var{perfil} -@itemx -p @var{perfil} -Muestra información acerca del @var{perfil}. -@end table - -@node Invocación de guix archive -@section Invocación de @command{guix archive} - -@cindex @command{guix archive} -@cindex archive -La orden @command{guix archive} permite a las usuarias @dfn{exportar} -ficheros del almacén en un único archivador, e @dfn{importarlos} -posteriormente en una máquina que ejecute Guix. En particular, permite que -los ficheros del almacén sean transferidos de una máquina al almacén de otra -máquina. - -@quotation Nota -Si está buscando una forma de producir archivos en un formato adecuado para -herramientas distintas a Guix, @pxref{Invocación de guix pack}. -@end quotation - -@cindex exportar elementos del almacén -Para exportar ficheros del almacén como un archivo por la salida estándar, -ejecute: - -@example -guix archive --export @var{opciones} @var{especificaciones}... -@end example - -@var{especificaciones} deben ser o bien nombres de ficheros del almacén o -especificaciones de paquetes, como las de @command{guix package} -(@pxref{Invocación de guix package}). Por ejemplo, la siguiente orden crea un -archivo que contiene la salida @code{gui} del paquete @code{git} y la salida -principal de @code{emacs}: - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar -@end example - -Si los paquetes especificados no están todavía construidos, @command{guix -archive} los construye automáticamente. El proceso de construcción puede -controlarse mediante las opciones de construcción comunes (@pxref{Opciones comunes de construcción}). - -Para transferir el paquete @code{emacs} a una máquina conectada por SSH, se -ejecutaría: - -@example -guix archive --export -r emacs | ssh otra-maquina guix archive --import -@end example - -@noindent -De manera similar, un perfil de usuaria completo puede transferirse de una -máquina a otra de esta manera: - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh otra-maquina guix-archive --import -@end example - -@noindent -No obstante, fíjese que, en ambos ejemplos, todo @code{emacs} y el perfil -como también todas sus dependencias son transferidas (debido a la -@code{-r}), independiente de lo que estuviese ya disponible en el almacén de -la máquina objetivo. La opción @code{--missing} puede ayudar a esclarecer -qué elementos faltan en el almacén objetivo. La orden @command{guix copy} -simplifica y optimiza este proceso completo, así que probablemente es lo que -debería usar en este caso (@pxref{Invocación de guix copy}). - -@cindex nar, formato de archivo -@cindex archivo normalizado (nar) -Los archivos se almacenan en el formato de ``archivo normalizado'' o -``nar'', el cual es comparable a `tar' en el espíritu, pero con diferencias -que lo hacen más apropiado para nuestro propósito. Primero, en vez de -almacenar todos los metadatos Unix de cada fichero, el formato nar solo -menciona el tipo de fichero (normal, directorio o enlace simbólico); los -permisos Unix y el par propietario/grupo se descartan. En segundo lugar, el -orden en el cual las entradas de directorios se almacenan siempre siguen el -orden de los nombres de ficheros de acuerdo a la ordenación de cadenas en la -localización C. Esto hace la producción del archivo completamente -determinista. - -@c FIXME: Add xref to daemon doc about signatures. -Durante la exportación, el daemon firma digitalmente los contenidos del -archivo, y la firma digital se adjunta. Durante la importación, el daemon -verifica la firma y rechaza la importación en caso de una firma inválida o -si la clave firmante no está autorizada. - -Las opciones principales son: - -@table @code -@item --export -Exporta los ficheros del almacén o paquetes (véase más adelante). Escribe el -archivo resultante a la salida estándar. - -Las dependencias @emph{no} están incluidas en la salida, a menos que se use -@code{--recursive}. - -@item -r -@itemx --recursive -Cuando se combina con @code{--export}, instruye a @command{guix archive} -para incluir las dependencias de los elementos dados en el archivo. Por -tanto, el archivo resultante está auto-contenido: contiene la clausura de -los elementos exportados del almacén. - -@item --import -Lee un archivo de la entrada estándar, e importa los ficheros enumerados -allí en el almacén. La operación se aborta si el archivo tiene una firma -digital no válida, o si está firmado por una clave pública que no está entre -las autorizadas (vea @code{--authorize} más adelante). - -@item --missing -Lee una lista de nombres de ficheros del almacén de la entrada estándar, uno -por línea, y escribe en la salida estándar el subconjunto de estos ficheros -que faltan en el almacén. - -@item --generate-key[=@var{parámetros}] -@cindex firmar, archivos -Genera un nuevo par de claves para el daemon. Esto es un prerrequisito antes -de que los archivos puedan ser exportados con @code{--export}. Tenga en -cuenta que esta operación normalmente toma tiempo, ya que se necesita -obtener suficiente entropía para generar un par de claves. - -El par de claves generado se almacena típicamente bajo @file{/etc/guix}, en -@file{signing-key.pub} (clave pública) y @file{signing-key.sec} (clave -privada, que se debe mantener secreta). Cuando @var{parámetros} se omite, se -genera una clave ECDSA usando la curva Ed25519, o, en versiones de Libgcrypt -previas a la 1.6.0, es una clave RSA de 4096 bits. De manera alternativa, -los @var{parámetros} pueden especificar parámetros @code{genkey} adecuados -para Libgcrypt (@pxref{General public-key related Functions, -@code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). - -@item --authorize -@cindex autorizar, archivos -Autoriza importaciones firmadas con la clave pública pasada por la entrada -estándar. La clave pública debe estar en el ``formato avanzado de -expresiones-s''---es decir, el mismo formato que el fichero -@file{signing-key.pub}. - -La lista de claves autorizadas se mantiene en el fichero editable por -personas @file{/etc/guix/acl}. El fichero contiene -@url{http://people.csail.mit.edu/rivest/Sexp.text, ``expresiones-s en -formato avanzado''} y está estructurado como una lista de control de acceso -en el formato @url{http://theworld.com/~cme/spki.txt, Infraestructura Simple -de Clave Pública (SPKI)}. - -@item --extract=@var{directorio} -@itemx -x @var{directorio} -Lee un único elemento del archivo como es ofrecido por los servidores de -sustituciones (@pxref{Sustituciones}) y lo extrae a @var{directorio}. Esta es -una operación de bajo nivel necesitada únicamente para casos muy concretos; -véase a continuación. - -Por ejemplo, la siguiente orden extrae la sustitución de Emacs ofrecida por -@code{@value{SUBSTITUTE-SERVER}} en @file{/tmp/emacs}: - -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ - | bunzip2 | guix archive -x /tmp/emacs -@end example - -Los archivos de un único elemento son diferentes de los archivos de -múltiples elementos producidos por @command{guix archive --export}; -contienen un único elemento del almacén, y @emph{no} embeben una firma. Por -tanto esta operación @emph{no} verifica la firma y su salida debe -considerarse insegura. - -El propósito primario de esta operación es facilitar la inspección de los -contenidos de un archivo que provenga probablemente de servidores de -sustituciones en los que no se confía. - -@end table - - -@c ********************************************************************* -@node Desarrollo -@chapter Desarrollo - -@cindex desarrollo de software -Si es una desarrolladora de software, Guix le proporciona herramientas que -debería encontrar útiles---independientemente del lenguaje en el que -desarrolle actualmente. Esto es sobre lo que trata este capítulo. - -La orden @command{guix environment} proporciona una manera conveniente de -configurar un @dfn{entorno de desarrollo} que contenga todas las -dependencias y herramientas necesarias para trabajar en el paquete de -software de su elección. La orden @command{guix pack} le permite crear -@dfn{aplicaciones empaquetadas} que pueden ser distribuidas con facilidad a -usuarias que no usen Guix. - -@menu -* Invocación de guix environment:: Configurar entornos de desarrollo. -* Invocación de guix pack:: Creación de empaquetados de software. -@end menu - -@node Invocación de guix environment -@section Invocación de @command{guix environment} - -@cindex entornos de construcción reproducibles -@cindex entornos de desarrollo -@cindex @command{guix environment} -@cindex entorno, entorno de construcción de paquetes -El propósito de @command{guix environment} es ayudar a las hackers en la -creación de entornos de desarrollo reproducibles sin modificar los paquetes -de su perfil. La herramienta @command{guix environment} toma uno o más -paquetes, construye todas sus entradas y crea un entorno shell para usarlos. - -La sintaxis general es: - -@example -guix environment @var{opciones} @var{paquete}@dots{} -@end example - -El ejemplo siguiente lanza un nuevo shell preparado para el desarrollo de -GNU@tie{}Guile: - -@example -guix environment guile -@end example - -Si las dependencias necesarias no están construidas todavía, @command{guix -environment} las construye automáticamente. El entorno del nuevo shell es -una versión aumentada del entorno en el que @command{guix environment} se -ejecutó. Contiene las rutas de búsqueda necesarias para la construcción del -paquete proporcionado añadidas a las variables ya existentes. Para crear un -entorno ``puro'', donde las variables de entorno previas no existen, use la -opción @code{--pure}@footnote{Las usuarias habitualmente aumentan de forma -incorrecta las variables de entorno como @code{PATH} en su fichero -@file{~/.bashrc}. Como consecuencia, cuando @code{guix environment} se -ejecuta, Bash puede leer @file{~/.bashrc}, por tanto introduciendo -``impurezas'' en esas variables de entorno. Es un error definir dichas -variables de entorno en @file{~/.bashrc}; en vez de ello deben definirse en -@file{.bash_profile}, el cual es únicamente cargado por el shell de ingreso -al sistema. @xref{Bash Startup Files,,, bash, The GNU Bash Reference -Manual}, para detalles sobre los ficheros de inicio de Bash.}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} define la variable @code{GUIX_ENVIRONMENT} en el -shell que lanza; su valor es el nombre de fichero del perfil para este -entorno. Esto permite a las usuarias, digamos, definir un prompt para -entornos de desarrollo en su @file{.bashrc} (@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 -...@: o para explorar el perfil: - -@example -$ ls "$GUIX_ENVIRONMENT/bin" -@end example - -Adicionalmente, más de un paquete puede ser especificado, en cuyo caso se -usa la unión de las entradas de los paquetes proporcionados. Por ejemplo, la -siguiente orden lanza un shell donde todas las dependencias tanto de Guile -como de Emacs están disponibles: - -@example -guix environment guile emacs -@end example - -A veces no se desea una sesión interactiva de shell. Una orden arbitraria -puede invorcarse usando el valor @code{--} para separar la orden del resto -de los parámetros: - -@example -guix environment guile -- make -j4 -@end example - -En otras situaciones, es más conveniente especificar una lista de paquetes -necesarios en el entorno. Por ejemplo, la siguiente orden ejecuta -@command{python} desde un entorno que contiene Python@tie{}2.7 y NumPy: - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -Más allá, se pueden desear las dependencias de un paquete y también algunos -paquetes adicionales que no son dependencias ni en tiempo de construcción ni -en el de ejecución, pero son útiles no obstante para el desarrollo. Por esta -razón, la opción @code{--ad-hoc} es posicional. Los paquetes que aparecen -antes de @code{--ad-hoc} se interpretan como paquetes cuyas dependencias se -añadirán al entorno. Los paquetes que aparecen después se interpretan como -paquetes que se añadirán directamente al entorno. Por ejemplo, la siguiente -orden crea un entorno de desarrollo Guix que incluye adicionalmente Git y -strace: - -@example -guix environment guix --ad-hoc git strace -@end example - -En ocasiones es deseable aislar el entorno tanto como sea posible, para -obtener la máxima pureza y reproducibilidad. En particular, cuando se usa -Guix en una distribución anfitriona que no es el sistema Guix, es deseable -prevenir acceso a @file{/usr/bin} y otros recursos del sistema desde el -entorno de desarrollo. Por ejemplo, la siguiente orden lanza un REPL Guile -en un ``contenedor'' donde únicamente el almacén y el directorio actual -están montados: - -@example -guix environment --ad-hoc --container guile -- guile -@end example - -@quotation Nota -La opción @code{--container} requiere Linux-libre 3.19 o más nuevo. -@end quotation - -Las opciones disponibles se resumen a continuación. - -@table @code -@item --root=@var{fichero} -@itemx -r @var{fichero} -@cindex entorno persistente -@cindex raíz del recolector de basura, para entornos -Hace que @var{fichero} sea un enlace simbólico al perfil para este entorno, -y lo registra como una raíz del recolector de basura. - -Esto es útil si desea proteger su entorno de la recolección de basura, -hacerlo ``persistente''. - -Cuando se omite esta opción, el entorno se protege de la recolección de -basura únicamente por la duración de la sesión @command{guix -environment}. Esto significa que la siguiente vez que vuelva a crear el -mismo entorno, puede tener que reconstruir o volver a descargar -paquetes. @xref{Invocación de guix gc}, para más información sobre las raices del -recolector de basura. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Crea un entorno para el paquete o lista de paquetes a los que evalúa -@var{expr}. - -Por ejemplo, ejecutando: - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -inicia un shell con el entorno para esta variante específica del paquete -PETSc. - -Ejecutar: - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -inicia un shell con todos los paquetes básicos del sistema disponibles. - -Las órdenes previas usan únicamente la salida predeterminada de los paquetes -dados. Para seleccionar otras salidas, tuplas de dos elementos pueden ser -especificadas: - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{fichero} -@itemx -l @var{fichero} -Crea un entorno para el paquete o la lista de paquetes a la que el código en -@var{fichero} evalúa. - -Como un ejemplo, @var{fichero} puede contener una definición como esta -(@pxref{Definición de paquetes}): - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{fichero} -@itemx -m @var{fichero} -Crea un entorno para los paquetes contenidos en el objeto manifest devuelto -por el código Scheme en @var{file}. - -Esto es similar a la opción del mismo nombre en @command{guix package} -(@pxref{profile-manifest, @option{--manifest}}) y usa los mismos ficheros de -manifiesto. - -@item --ad-hoc -Incluye todos los paquetes especificados en el entorno resultante, como si -un paquete @i{ad hoc} hubiese sido definido con ellos como entradas. Esta -opción es útil para la creación rápida un entorno sin tener que escribir una -expresión de paquete que contenga las entradas deseadas. - -Por ejemplo, la orden: - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -ejecuta @command{guile} en un entorno donde están disponibles Guile y -Guile-SDL. - -Fíjese que este ejemplo solicita implícitamente la salida predeterminada de -@code{guile} y @code{guile-sdl}, pero es posible solicitar una salida -específica---por ejemplo, @code{glib:bin} solicita la salida @code{bin} de -@code{glib} (@pxref{Paquetes con múltiples salidas}). - -Esta opción puede componerse con el comportamiento predeterminado de -@command{guix environment}. Los paquetes que aparecen antes de -@code{--ad-hoc} se interpretan como paquetes cuyas dependencias se añadirán -al entorno, el comportamiento predefinido. Los paquetes que aparecen después -se interpretan como paquetes a añadir directamente al entorno. - -@item --pure -Olvida las variables de entorno existentes cuando se construye un nuevo -entorno, excepto aquellas especificadas con @option{--preserve} (véase más -adelante). Esto tiene el efecto de crear un entorno en el que las rutas de -búsqueda únicamente contienen las entradas del paquete. - -@item --preserve=@var{regexp} -@itemx -E @var{regexp} -Cuando se usa junto a @option{--pure}, preserva las variables de entorno que -corresponden con @var{regexp}---en otras palabras, las pone en una lista de -variables de entorno que deben preservarse. Esta opción puede repetirse -varias veces. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -Este ejemplo ejecuta @command{mpirun} en un contexto donde las únicas -variables de entorno definidas son @code{PATH}, variables de entorno cuyo -nombre empiece con @code{SLURM}, así como las variables ``preciosas'' -habituales (@code{HOME}, @code{USER}, etc.). - -@item --search-paths -Muestra las definiciones de variables de entorno que componen el entorno. - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Intenta construir para @var{sistema}---por ejemplo, @code{i686-linux}. - -@item --container -@itemx -C -@cindex container -Ejecuta la @var{orden} en un contenedor aislado. El directorio actual fuera -del contenedor es asociado al interior del contenedor. Adicionalmente, a -menos que se fuerce con @code{--user}, un directorio de prueba de la usuaria -se crea de forma que coincida con el directorio actual de la usuaria, y -@file{/etc/passwd} se configura adecuadamente. - -El proceso lanzado se ejecuta como el usuario actual fuera del -contenedor. Dentro del contenedor, tiene el mismo UID y GID que el usuario -actual, a menos que se proporcione @option{--user} (véase más adelante). - -@item --network -@itemx -N -Para contenedores, comparte el espacio de nombres de red con el sistema -anfitrión. Los contenedores creados sin esta opción únicamente tienen acceso -a la red local. - -@item --link-profile -@itemx -P -Para contenedores, enlaza el perfil del entorno a @file{~/.guix-profile} -dentro del contenedor. Es equivalente a la ejecución de @command{ln -s -$GUIX_ENVIRONMENT ~/.guix-profile} dentro del contenedor. El enlace fallará -e interrumpirá el entorno si el directorio ya existe, lo cual será -probablemente el caso si @command{guix environment} se invocó en el -directorio de la usuaria. - -Determinados paquetes se configuran para buscar en @code{~/.guix-profile} -ficheros de configuración y datos;@footnote{Por ejemplo, el paquete -@code{fontconfig} inspecciona @file{~/.guix-profile/share/fonts} en busca de -nuevas tipografías.} @code{--link-profile} permite a estos programas operar -de la manera esperada dentro del entorno. - -@item --user=@var{usuaria} -@itemx -u @var{usuaria} -Para contenedores, usa el nombre de usuaria @var{usuaria} en vez de la -actual. La entrada generada en @file{/etc/passwd} dentro del contenedor -contendrá el nombre @var{usuaria}; su directorio será -@file{/home/@var{usuaria}} y ningún dato GECOS de la usuaria se copiará. Más -aún, el UID y GID dentro del contenedor son 1000. @var{usuaria} no debe -existir en el sistema. - -Adicionalmente, cualquier ruta compartida o expuesta (véanse @code{--share} -y @code{--expose} respectivamente) cuyo destino esté dentro de la carpeta -actual de la usuaria será reasociada en relación a -@file{/home/@var{usuaria}}; esto incluye la relación automática del -directorio de trabajo actual. - -@example -# expondrá las rutas /home/foo/ddt, /home/foo/prueba y /home/foo/objetivo -cd $HOME/ddt -guix environment --container --user=foo \ - --expose=$HOME/prueba \ - --expose=/tmp/objetivo=$HOME/objetivo -@end example - -Mientras esto limita el escape de la identidad de la usuaria a través de las -rutas de sus directorios y cada uno de los campos de usuaria, esto es -únicamente un componente útil de una solución de privacidad/anonimato más -amplia---no una solución completa. - -@item --expose=@var{fuente}[=@var{destino}] -Para contenedores, expone el sistema de ficheros @var{fuente} del sistema -anfitrión como un sistema de ficheros de solo-lectura @var{destino} dentro -del contenedor. Si no se especifica @var{destino}, @var{fuente} se usa como -el punto de montaje en el contenedor. - -El ejemplo a continuación lanza una sesión interactiva de Guile en un -contenedor donde el directorio principal de la usuaria es accesible en modo -solo-lectura a través del directorio @file{/intercambio}: - -@example -guix environment --container --expose=$HOME=/intercambio --ad-hoc guile -- guile -@end example - -@item --share=@var{fuente}[=@var{destino}] -Para contenedores, comparte el sistema de ficheros @var{fuente} del sistema -anfitrión como el sistema de ficheros @var{destino} con permisos de -escritura dentro del contenedor. Si no se especifica @var{destino}, -@var{fuente} se usa como punto de montaje en el contenedor. - -El siguiente ejemplo lanza un entorno interactivo Guile en un contenedor en -el que el directorio principal de la usuaria está disponible para tanto -lectura como escritura via el directorio @file{/intercambio}: - -@example -guix environment --container --share=$HOME=/intercambio --ad-hoc guile -- guile -@end example -@end table - -Además, @command{guix environment} acepta todas las opciones comunes de -construcción que permite @command{guix build} (@pxref{Opciones comunes de construcción}) -así como las opciones de transformación de paquetes (@pxref{Opciones de transformación de paquetes}). - -@node Invocación de guix pack -@section Invocación de @command{guix pack} - -De manera ocasional querrá dar software a gente que (¡todavía!) no tiene la -suerte de usar Guix. Usted les diría que ejecuten @command{guix package -i -@var{algo}}, pero eso no es posible en este caso. Aquí es donde viene -@command{guix pack}. - -@quotation Nota -Si está buscando formas de intercambiar binarios entre máquinas que ya -ejecutan Guix, @pxref{Invocación de guix copy}, @ref{Invocación de guix publish}, y -@ref{Invocación de guix archive}. -@end quotation - -@cindex pack -@cindex empaquetado -@cindex aplicación empaquetada -@cindex empaquetado de software -La orden @command{guix pack} crea un @dfn{paquete} reducido o -@dfn{empaquetado de software}: crea un archivador tar u otro tipo que -contiene los binarios del software en el que está interesada y todas sus -dependencias. El archivo resultante puede ser usado en una máquina que no -tiene Guix, y la gente puede ejecutar exactamente los mismos binarios que -usted tiene con Guix. El paquete en sí es creado de forma reproducible -bit-a-bit, para que cualquiera pueda verificar que realmente contiene los -resultados de construcción que pretende distribuir. - -Por ejemplo, para crear un empaquetado que contenga Guile, Emacs, Geiser y -todas sus dependencias, puede ejecutar: - -@example -$ guix pack guile emacs geiser -@dots{} -/gnu/store/@dots{}-pack.tar.gz -@end example - -El resultado aquí es un archivador tar que contiene un directorio de -@file{/gnu/store} con todos los paquetes relevantes. El archivador -resultante contiene un @dfn{perfil} con los tres paquetes de interés; el -perfil es el mismo que se hubiera creado por @command{guix package -i}. Este -es el mecanismo usado para crear el propio archivador de binarios separado -de Guix (@pxref{Instalación binaria}). - -Las usuarias de este empaquetad tendrán que ejecutar -@file{/gnu/store/@dots{}-profile/bin/guile} para ejecutar guile, lo que -puede resultar inconveniente. Para evitarlo, puede crear, digamos, un enlace -simbólico @file{/opt/gnu/bin} al perfil: - -@example -guix pack -S /opt/gnu/bin=bin guile emacs geiser -@end example - -@noindent -De este modo, las usuarias pueden escribir alegremente -@file{/opt/gnu/bin/guile} y disfrutar. - -@cindex binarios relocalizables, con @command{guix pack} -¿Qué pasa se la receptora de su paquete no tiene privilegios de root en su -máquina y por lo tanto no puede desempaquetarlo en la raíz del sistema de -ficheros? En ese caso, lo que usted desea es usar la opción -@code{--relocatable} (véase a continuación). Esta opción produce -@dfn{binarios relocalizables}, significando que pueden ser colocados en -cualquier lugar de la jerarquía del sistema de ficheros: en el ejemplo -anterior, las usuarias pueden desempaquetar el archivador en su directorio -de usuaria y ejecutar directamente @file{./opt/gnu/bin/guile}. - -@cindex Docker, construir una imagen con guix pack -De manera alternativa, puede producir un empaquetado en el formato de imagen -Docker usando la siguiente orden: - -@example -guix pack -f docker guile emacs geiser -@end example - -@noindent -El resultado es un archivador tar que puede ser pasado a la orden -@command{docker load}. Véase la -@uref{https://docs.docker.com/engine/reference/commandline/load/, -documentación de Docker} para más información. - -@cindex Singularity, construir una imagen con guix pack -@cindex SquashFS, construir una imagen con guix pack -Otra opción más es producir una imagen SquashFS con la siguiente orden: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -El resultado es una imagen de sistema de ficheros SquashFS que puede ser o -bien montada, o bien usada directamente como una imagen contenedora de -sistemas de ficheros con el @uref{http://singularity.lbl.gov, entorno de -ejecución de contenedores Singularity}, usando órdenes como -@command{singularity shell} o @command{singularity exec}. - -Varias opciones de la línea de órdenes le permiten personalizar su -empaquetado: - -@table @code -@item --format=@var{formato} -@itemx -f @var{formato} -Produce un empaquetado en el @var{formato} específico. - -Los formatos disponibles son: - -@table @code -@item tarball -Es el formato predeterminado. Produce un archivador que contiene todos los -binarios y enlaces simbólicos especificados. - -@item docker -Produce un archivador que sigue la -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -especificación de imágenes Docker}. - -@item squashfs -Produce una imagen SquashFS que contiene todos los binarios y enlaces -simbólicos especificados, así como puntos de montaje vacíos para sistemas de -ficheros virtuales como procfs. -@end table - -@cindex binarios reposicionables -@item --relocatable -@itemx -R -Produce @dfn{binarios reposicionables}---es decir, binarios que se pueden -posicionar en cualquier lugar de la jerarquía del sistema de ficheros, y -ejecutarse desde allí. - -When this option is passed once, the resulting binaries require support for -@dfn{user namespaces} in the kernel Linux; when passed -@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds -PRoot support, can be thought of as the abbreviation of ``Really -Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot -if user namespaces are unavailable, and essentially work anywhere---see -below for the implications. - -Por ejemplo, si crea un empaquetado que contiene Bash con:< - -@example -guix pack -RR -S /mybin=bin bash -@end example - -@noindent -...@: puede copiar ese empaquetado a una máquina que no tiene Guix, y desde -su directorio, como una usuaria normal, ejecutar: - -@example -tar xf pack.tar.gz -./mibin/sh -@end example - -@noindent -En ese shell, si escribe @code{ls /gnu/store}, notará que @file{/gnu/store} -muestra y contiene todas las dependencias de @code{bash}, ¡incluso cuando la -máquina no tiene el directorio @file{/gnu/store}! Esto es probablemente el -modo más simple de desplegar software construido en Guix en una máquina -no-Guix. - -@quotation Nota -No obstante hay un punto a tener en cuenta: esta técnica descansa en la -característica de @dfn{espacios de nombres de usuaria} del núcleo Linux, la -cual permite a usuarias no privilegiadas montar o cambiar la raíz. Versiones -antiguas de Linux no los implementan, y algunas distribuciones GNU/Linux los -deshabilitan. - -Para producir binarios reposicionables que funcionen incluso en ausencia de -espacios de nombre de usuaria, proporcione @option{--relocatable} o -@option{-R} @emph{dos veces}. En ese caso, los binarios intentarán el uso de -espacios de nombres de usuaria y usarán PRoot si no es posible. - -El programa @uref{https://proot-me.github.io/, PRoot} proporciona el soporte -necesario para la virtualización del sistema de ficheros. Lo consigue -mediante el uso de la llamada al sistema @code{ptrace} en el programa en -ejecución. Esta aproximación tiene la ventaja de funcionar sin soporte -especial en el núcleo, pero incurre en una sobrecarga en el tiempo de -ejecución cada vez que se realiza una llamada al sistema. -@end quotation - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considera el paquete al que evalúa @var{expr} - -Esto tiene el mismo propósito que la opción del mismo nombre en -@command{guix build} (@pxref{Opciones de construcción adicionales, @code{--expression} -in @command{guix build}}). - -@item --manifest=@var{fichero} -@itemx -m @var{fichero} -Usa los paquetes contenidos en el objeto manifest devuelto por el código -Scheme en @var{file}. - -Esto tiene un propósito similar al de la opción del mismo nombre en -@command{guix package} (@pxref{profile-manifest, @option{--manifest}}) y usa -los mismos ficheros de manifiesto. Esto le permite definir una colección de -paquetes una vez y usarla tanto para crear perfiles como para crear archivos -en máquinas que no tienen instalado Guix. Fíjese que puede especificar -@emph{o bien} un fichero de manifiesto @emph{o bien} una lista de paquetes, -pero no ambas. - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Intenta construir paquetes para @var{sistema}---por ejemplo, -@code{x86_64-linux}---en vez del tipo de sistema de la máquina de -construcción. - -@item --target=@var{tripleta} -@cindex compilación cruzada -Compilación cruzada para la @var{tripleta}, que debe ser una tripleta GNU -válida, cómo @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, -GNU configuration triplets,, autoconf, Autoconf}). - -@item --compression=@var{herramienta} -@itemx -C @var{herramienta} -Comprime el archivador resultante usando @var{herramienta}---un valor que -puede ser @code{gzip}, @code{bzip2}, @code{xz}, @code{lzip} o @code{none} -para no usar compresión. - -@item --symlink=@var{spec} -@itemx -S @var{spec} -Añade los enlaces simbólicos especificados por @var{spec} al -empaquetado. Esta opción puede aparecer varias veces. - -La forma de @var{spec} es @code{@var{fuente}=@var{destino}}, donde -@var{fuente} es el enlace simbólico que será creado y @var{destino} es el -destino del enlace simbólico. - -Por ejemplo, @code{-S /opt/gnu/bin=bin} crea un enlace simbólico -@file{/opt/gnu/bin} apuntando al subdirectorio @file{bin} del perfil. - -@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{Canales}). - -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{nombre} -Incluye el ``directorio de estado local'', @file{/var/guix}, en el -empaquetado resultante, y notablemente el perfil -@file{/var/guix/profiles/per-user/root/@var{nombre}}---por defecto -@var{nombre} es @code{guix-profile}, que corresponde con -@file{~root/.guix-profile}. - -@file{/var/guix} contiene la base de datos del almacén (@pxref{El almacén}) -así como las raíces del recolector de basura (@pxref{Invocación de guix gc}). Proporcionarlo junto al empaquetado significa que el almacén está -``completo'' y Guix puede trabajar con él; no proporcionarlo significa que -el almacén está ``muerto'': no se pueden añadir o borrar nuevos elementos -después de la extracción del empaquetado. - -Un caso de uso para esto es el archivador tar autocontenido de binarios de -Guix (@pxref{Instalación binaria}). - -@item --bootstrap -Usa los binarios del lanzamiento para construir el empaquetado. Esta opción -es útil únicamente a las desarrolladoras de Guix. -@end table - -Además, @command{guix pack} acepta todas las opciones comunes de -construcción (@pxref{Opciones comunes de construcción}) y todas las opciones de -transformación de paquetes (@pxref{Opciones de transformación de paquetes}). - - -@c ********************************************************************* -@node Interfaz programática -@chapter Interfaz programática - -GNU Guix proporciona viarias interfaces programáticas Scheme (APIs) para -definir, construir y consultar paquetes. La primera interfaz permite a las -usuarias escribir definiciones de paquetes a alto nivel. Estas definiciones -referencian conceptos familiares de empaquetamiento, como el nombre y la -versión de un paquete, su sistema de construcción y sus dependencias. Estas -definiciones se pueden convertir en acciones concretas de construcción. - -Las acciones de construcción son realizadas por el daemon Guix, en -delegación de las usuarias. En una configuración estándar, el daemon tiene -acceso de escritura al almacén---el directorio @file{/gnu/store}---mientras -que las usuarias no. En la configuración recomendada el daemon también -realiza las construcciones en chroots, bajo usuarias específicas de -construcción, para minimizar la interferencia con el resto del sistema. - -@cindex derivación -Las APIs de nivel más bajo están disponibles para interactuar con el daemon -y el almacén. Para instruir al daemon para realizar una acción de -construcción, las usuarias realmente proporcionan una @dfn{derivación}. Una -derivación es una representación de bajo nivel de las acciones de -construcción a tomar, y el entorno en el que deberían suceder---las -derivaciones son a las definiciones de paquetes lo que es el ensamblador a -los programas en C. El término ``derivación'' viene del hecho de que los -resultados de la construcción @emph{derivan} de ellas. - -Este capítulo describe todas estas APIs en orden, empezando por las -definiciones de alto nivel de paquetes. - -@menu -* Módulos de paquetes:: Paquetes bajo el punto de vista del - programador. -* Definición de paquetes:: Definir nuevos paquetes. -* Sistemas de construcción:: Especificar como se construyen los paquetes. -* El almacén:: Manipular el almacén de paquetes. -* Derivaciones:: Interfaz de bajo nivel de las derivaciones de - los paquetes. -* La mónada del almacén:: Interfaz puramente funcional del almacén. -* Expresiones-G:: Manipular expresiones de construcción. -* Invocación de guix repl:: Enredar con Guix interactivamente. -@end menu - -@node Módulos de paquetes -@section Módulos de paquetes - -Desde un punto de vista programático, las definiciones de paquetes de la -distribución GNU se proporcionan por módulos Guile en el espacio de nombres -@code{(gnu packages @dots{})}@footnote{Fíjese que los paquetes bajo el -espacio de nombres de módulo @code{(gnu packages @dots{})} no son -necesariamente ``paquetes GNU''. Este esquema de nombrado de módulos sigue -la convención habitual de Guile para el nombrado de módulos: @code{gnu} -significa que estos módulos se distribuyen como parte del sistema GNU, y -@code{packages} identifica módulos que definen paquetes.} (@pxref{Módulos, -Guile modules,, guile, GNU Guile Reference Manual}). Por ejemplo, el módulo -@code{(gnu packages emacs)} exporta una variable con nombre @code{emacs}, -que está asociada a un objeto @code{} (@pxref{Definición de paquetes}). - -El espacio de nombres de módulos @code{(gnu packages @dots{})} se recorre -automáticamente en busca de paquetes en las herramientas de línea de -ordenes. Por ejemplo, cuando se ejecuta @code{guix package -i emacs}, todos -los módulos @code{(gnu packages @dots{})} son procesados hasta encontrar uno -que exporte un objeto de paquete cuyo nombre sea @code{emacs}. Esta búsqueda -de paquetes se implementa en el módulo @code{(gnu packages)}. - -@cindex personalización, de paquetes -@cindex ruta de búsqueda de módulos de paquetes -Las usuarias pueden almacenar definiciones de paquetes en módulos con -nombres diferentes---por ejemplo, @code{(mis-paquetes -emacs)}@footnote{Fíjese que el nombre de fichero y el nombre de módulo deben -coincidir. Por ejemplo, el módulo @code{(mis-paquetes emacs)} debe -almacenarse en el fichero @file{mis-paquetes/emacs.scm} en relación con la -ruta de carga especificada con @option{--load-path} o -@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, guile, GNU -Guile Reference Manual}, para obtener detalles.}. Existen dos maneras de -hacer visibles estas definiciones de paquetes a las interfaces de usuaria: - -@enumerate -@item -Mediante la adición del directorio que contiene sus módulos de paquetes a la -ruta de búsqueda con la opción @code{-L} de @command{guix package} y otras -órdenes (@pxref{Opciones comunes de construcción}), o usando la variable de entorno -@code{GUIX_PACKAGE_PATH} descrita más adelante. - -@item -Mediante la definición de un @dfn{canal} y la configuración de @command{guix -pull} de manera que se actualice desde él. Un canal es esencialmente un -repositorio Git que contiene módulos de paquetes. @xref{Canales}, para más -información sobre cómo definir y usar canales. -@end enumerate - -@code{GUIX_PACKAGE_PATH} funciona de forma similar a otras variables de -rutas de búsqueda: - -@defvr {Variable de entorno} GUIX_PACKAGE_PATH -Es una lista separada por dos puntos de directorios en los que se buscarán -módulos de paquetes adicionales. Los directorios enumerados en esta variable -tienen preferencia sobre los propios módulos de la distribución. -@end defvr - -La distribución es @dfn{auto-contenida} y completamente @dfn{basada en el -lanzamiento inicial}: cada paquete se construye basado únicamente en otros -paquetes de la distribución. La raíz de este grafo de dependencias es un -pequeño conjunto de @dfn{binarios del lanzamiento inicial}, proporcionados -por el módulo @code{(gnu packages bootstrap)}. Para más información sobre el -lanzamiento inicial, @pxref{Lanzamiento inicial}. - -@node Definición de paquetes -@section Definición de paquetes - -La interfaz de alto nivel de las definiciones de paquetes está implementada -en los módulos @code{(guix packages)} y @code{(guix build-system)}. Como un -ejemplo, la definición de paquete, o @dfn{receta}, para el paquete GNU Hello -es como sigue: - -@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 -Sin ser una experta en Scheme---pero conociendo un poco de inglés---, la -lectora puede haber supuesto el significado de varios campos aquí. Esta -expresión asocia la variable @code{hello} al objeto @code{}, que -esencialmente es un registro (@pxref{SRFI-9, Scheme records,, guile, GNU -Guile Reference Manual}). Este objeto de paquete puede ser inspeccionado -usando los procedimientos encontrados en el módulo @code{(guix packages)}; -por ejemplo, @code{(package-name hello)} -devuelve---¡sorpresa!---@code{"hello"}. - -Con suerte, puede que sea capaz de importar parte o toda la definición del -paquete de su interés de otro repositorio, usando la orden @code{guix -import} (@pxref{Invocación de guix import}). - -En el ejemplo previo, @var{hello} se define en un módulo para ella, -@code{(gnu packages hello)}. Técnicamente, esto no es estrictamente -necesario, pero es conveniente hacerlo: todos los paquetes definidos en -módulos bajo @code{(gnu packages @dots{})} se reconocen automáticamente en -las herramientas de línea de órdenes (@pxref{Módulos de paquetes}). - -Hay unos pocos puntos que merece la pena destacar de la definición de -paquete previa: - -@itemize -@item -El campo @code{source} del paquete es un objeto @code{} -(@pxref{Referencia de ``origin''}, para la referencia completa). Aquí se usa el -método @code{url-fetch} de @code{(guix download)}, lo que significa que la -fuente es un fichero a descargar por FTP o HTTP. - -El prefijo @code{mirror://gnu} instruye a @code{url-fetch} para usar uno de -los espejos GNU definidos en @code{(guix download)}. - -El campo @code{sha256} especifica el hash SHA256 esperado del fichero -descargado. Es obligatorio, y permite a Guix comprobar la integridad del -fichero. La forma @code{(base32 @dots{})} introduce la representación base32 -del hash. Puede obtener esta información con @code{guix download} -(@pxref{Invocación de guix download}) y @code{guix hash} (@pxref{Invocación de guix hash}). - -@cindex parches -Cuando sea necesario, la forma @code{origin} también puede tener un campo -@code{patches} con la lista de parches a ser aplicados, y un campo -@code{snippet} con una expresión Scheme para modificar el código fuente. - -@item -@cindex Sistema de construcción GNU -El campo @code{build-system} especifica el procedimiento de construcción del -paquete (@pxref{Sistemas de construcción}). Aquí, @var{gnu-build-system} representa el -familiar sistema de construcción GNU, donde los paquetes pueden -configurarse, construirse e instalarse con la secuencia de ordenes habitual -@code{./configure && make && make check && make install}. - -@item -El campo @code{arguments} especifica las opciones para el sistema de -construcción (@pxref{Sistemas de construcción}). Aquí son interpretadas por -@var{gnu-build-system} como una petición de ejecutar @file{configure} con la -opción @code{--enable-silent-rules}. - -@cindex quote -@cindex creación de literales -@findex ' -@findex quote -¿Qué son estas comillas simples (@code{'})? Son sintaxis Scheme para -introducir una lista literal; @code{'} es sinónimo de -@code{quote}. @xref{Expression Syntax, quoting,, guile, GNU Guile Reference -Manual}, para más detalles. Aquí el valor del campo @code{arguments} es una -lista de parámetros pasada al sistema de construcción, como con @code{apply} -(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -La secuencia almohadilla-dos puntos (@code{#:}) define una @dfn{palabra -clave} Scheme (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), y -@code{#:configure-flags} es una palabra clave usada para pasar un parámetro -nominal al sistema de construcción (@pxref{Coding With Keywords,,, guile, -GNU Guile Reference Manual}). - -@item -El campo @code{inputs} especifica las entradas al proceso de -construcción---es decir, dependencias de tiempo de construcción o ejecución -del paquete. Aquí, definimos una entrada llamada @code{"gawk"}, cuyo valor -es el de la variable @var{gawk}; @var{gawk} en sí apunta a un objeto -@code{}. - -@cindex acento grave (quasiquote) -@findex ` -@findex quasiquote -@cindex coma (unquote) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -De nuevo, @code{`} (un acento grave, sinónimo de @code{quasiquote}) nos -permite introducir una lista literal en el campo @code{inputs}, mientras que -@code{,} (una coma, sinónimo de @code{unquote}) nos permite insertar un -valor en dicha lista (@pxref{Expression Syntax, unquote,, guile, GNU Guile -Reference Manual}). - -Fíjese que no hace falta que GCC, Coreutils, Bash y otras herramientas -esenciales se especifiquen como entradas aquí. En vez de eso, -@var{gnu-build-system} se hace cargo de asegurar que están presentes -(@pxref{Sistemas de construcción}). - -No obstante, cualquier otra dependencia debe ser especificada en el campo -@code{inputs}. Las dependencias no especificadas aquí simplemente no estarán -disponibles para el proceso de construcción, provocando posiblemente un -fallo de construcción. -@end itemize - -@xref{Referencia de ``package''}, para una descripción completa de los campos -posibles. - -Una vez la definición de paquete esté en su lugar, el paquete puede ser -construido realmente usando la herramienta de línea de órdenes @code{guix -build} (@pxref{Invocación de guix build}), pudiendo resolver cualquier fallo de -construcción que encuentre (@pxref{Depuración de fallos de construcción}). Puede volver -a la definición del paquete fácilmente usando la orden @command{guix edit} -(@pxref{Invocación de guix edit}). @xref{Guías de empaquetamiento}, para más -información sobre cómo probar definiciones de paquetes, y @ref{Invocación de guix lint}, para información sobre cómo comprobar la consistencia del estilo de -una definición. -@vindex GUIX_PACKAGE_PATH -Por último, @pxref{Canales}, para información sobre cómo extender la -distribución añadiendo sus propias definiciones de paquetes en un ``canal''. - -Finalmente, la actualización de la definición con una nueva versión oficial -puede ser automatizada parcialmente por la orden @command{guix refresh} -(@pxref{Invocación de guix refresh}). - -Tras el telón, una derivación correspondiente al objeto @code{} es -calculada mediante el procedimiento @code{package-derivation}. Esta -derivación es almacenada en un fichero @code{.drv} bajo -@file{/gnu/store}. Las acciones de construcción que prescribe pueden -entonces llevarse a cabo usando el procedimiento @code{build-derivations} -(@pxref{El almacén}). - -@deffn {Procedimiento Scheme} package-derivation @var{almacén} @var{paquete} [@var{sistema}] -Devuelve el objeto @code{} del @var{paquete} pra el -@var{sistema} (@pxref{Derivaciones}). - -@var{paquete} debe ser un objeto @code{} válido, y @var{sistema} -debe ser una cadena que denote el tipo de sistema objetivo---por ejemplo, -@code{"x86_64-linux"} para un sistema GNU x86_64 basado en -Linux. @var{almacén} debe ser una conexión al daemon, que opera en el -almacén (@pxref{El almacén}). -@end deffn - -@noindent -@cindex compilación cruzada -De manera similar, es posible calcular una derivación que construye de forma -cruzada un paquete para otro sistema: - -@deffn {Procedimiento Scheme} package-cross-derivation @var{almacén} @ - @var{paquete} @var{plataforma} [@var{sistema}] -Devuelve el objeto @code{} de @var{paquete} compilado de forma -cruzada desde @var{sistema} a @var{plataforma}. - -@var{plataforma} debe ser una tripleta GNU válida que denote el hardware y -sistema operativo objetivo, como @code{"mips64el-linux-gnu"} -(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU -Configure and Build System}). -@end deffn - -@cindex transformación de paquetes -@cindex reescritura de la entrada -@cindex reescritura del árbol de dependencias -Los paquetes se pueden manipular de forma arbitraria. Un ejemplo de -transformación útil es la @dfn{reescritura de entradas}, donde el árbol de -dependencias de un paquete se reescribe reemplazando entradas específicas -por otras: - -@deffn {Procedimiento Scheme} package-input-rewriting @var{reemplazos} @ - [@var{nombre-reescrito}] -Devuelve un procedimiento que, cuando se le pasa un paquete, reemplaza sus -dependencias directas e indirectas (pero no sus entradas implícitas) de -acuerdo a @var{reemplazos}. @var{reemplazos} es una lista de pares de -paquetes; el primer elemento de cada par es el paquete a reemplazar, el -segundo es el reemplazo. - -Opcionalmente, @var{nombre-reescrito} es un procedimiento de un parámetro -que toma el nombre del paquete y devuelve su nuevo nombre tras la -reescritura. -@end deffn - -@noindent -Considere este ejemplo: - -@example -(define libressl-en-vez-de-openssl - ;; Esto es un procedimiento para reemplazar OPENSSL - ;; por LIBRESSL, recursivamente. - (package-input-rewriting `((,openssl . ,libressl)))) - -(define git-con-libressl - (libressl-en-vez-de-openssl git)) -@end example - -@noindent -Aquí primero definimos un procedimiento de reescritura que substituye -@var{openssl} por @var{libressl}. Una vez hecho esto, lo usamos para definir -una @dfn{variante} del paquete @var{git} que usa @var{libressl} en vez de -@var{openssl}. Esto es exactamente lo que hace la opción de línea de órdenes -@option{--with-input} (@pxref{Opciones de transformación de paquetes, -@option{--with-input}}). - -The following variant of @code{package-input-rewriting} can match packages -to be replaced by name rather than by identity. - -@deffn {Procedimiento Scheme} package-input-rewriting/spec @var{reemplazos} -Return a procedure that, given a package, applies the given -@var{replacements} to all the package graph (excluding implicit inputs). -@var{replacements} is a list of spec/procedures pair; each spec is a package -specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure -takes a matching package and returns a replacement for that package. -@end deffn - -The example above could be rewritten this way: - -@example -(define libressl-en-vez-de-openssl - ;; Reemplaza todos los paquetes llamados "openssl" con LibreSSL. - (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example - -The key difference here is that, this time, packages are matched by spec and -not by identity. In other words, any package in the graph that is called -@code{openssl} will be replaced. - -Un procedimiento más genérico para reescribir el grafo de dependencias de un -paquete es @code{package-mapping}: acepta cambios arbitrarios sobre nodos -del grafo. - -@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cortar?}] -Devuelve un procedimiento que, dado un paquete, aplica @var{proc} a todos -los paquetes de los que depende y devuelve el paquete resultante. El -procedimiento para la recursión cuando @var{cortar?} devuelve verdadero para -un paquete dado. -@end deffn - -@menu -* Referencia de ``package'':: El tipo de datos de los paquetes. -* Referencia de ``origin'':: El tipo de datos de orígenes. -@end menu - - -@node Referencia de ``package'' -@subsection Referencia de @code{package} - -Esta sección resume todas las opciones disponibles en declaraciones -@code{package} (@pxref{Definición de paquetes}). - -@deftp {Tipo de datos} package -Este es el tipo de datos que representa la receta de un paquete. - -@table @asis -@item @code{name} -El nombre del paquete, como una cadena. - -@item @code{version} -La versión del paquete, como una cadena. - -@item @code{source} -Un objeto que determina cómo se debería obtener el código fuente del -paquete. La mayor parte del tiempo, es un objeto @code{origin}, que denota -un fichero obtenido de Internet (@pxref{Referencia de ``origin''}). También puede -ser cualquier otro objeto ``tipo-fichero'' como @code{local-file}, que -denota un fichero del sistema local de ficheros (@pxref{Expresiones-G, -@code{local-file}}). - -@item @code{build-system} -El sistema de construcción que debe ser usado para construir el paquete -(@pxref{Sistemas de construcción}). - -@item @code{arguments} (predeterminados: @code{'()}) -Los parámetros que deben ser pasados al sistema de construcción. Es una -lista que normalmente contiene una secuencia de pares de palabra clave y -valor. - -@item @code{inputs} (predeterminadas: @code{'()}) -@itemx @code{native-inputs} (predeterminadas: @code{'()}) -@itemx @code{propagated-inputs} (predeterminadas: @code{'()}) -@cindex entradas, de paquetes -Estos campos enumeran las dependencias del paquete. Cada uno es una lista de -tuplas, donde cada tupla tiene una etiqueta para la entrada (una cadena) -como su primer elemento, un paquete, origen o derivación como su segundo -elemento, y opcionalmente el nombre de la salida que debe ser usada, cuyo -valor predeterminado es @code{"out"} (@pxref{Paquetes con múltiples salidas}, para más información sobre salidas de paquetes). Por ejemplo, la -lista siguiente especifica tres entradas: - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;la salida "bin" de Glib -@end example - -@cindex compilación cruzada, dependencias de paquetes -La distinción entre @code{native-inputs} y @code{inputs} es necesaria cuando -se considera la compilación cruzada. Cuando se compila cruzadamente, las -dependencias enumeradas en @code{inputs} son construidas para la -arquitectura @emph{objetivo}; de modo contrario, las dependencias enumeradas -en @code{native-inputs} se construyen para la arquitectura de la máquina de -@emph{construcción}. - -@code{native-inputs} se usa típicamente para enumerar herramientas -necesarias en tiempo de construcción, pero no en tiempo de ejecución, como -Autoconf, Automake, pkg-config, Gettext o Bison. @command{guix lint} puede -informar de probables errores en este área (@pxref{Invocación de guix lint}). - -@anchor{package-propagated-inputs} -Por último, @code{propagated-inputs} es similar a @code{inputs}, pero los -paquetes especificados se instalarán automáticamente junto al paquete al que -pertenecen (@pxref{package-cmd-propagated-inputs, @command{guix package}}, -para información sobre cómo @command{guix package} maneja las entradas -propagadas). - -Por ejemplo esto es necesario cuando una biblioteca C/C++ necesita cabeceras -de otra biblioteca para compilar, o cuando un fichero pkg-config se refiere -a otro @i{via} su campo @code{Requires}. - -Otro ejemplo donde @code{propagated-inputs} es útil es en lenguajes que -carecen de la facilidad de almacenar la ruta de búsqueda de tiempo de -ejecución de la misma manera que el campo @code{RUNPATH} de los ficheros -ELF; esto incluye Guile, Python, Perl y más. Para asegurarse que las -bibliotecas escritas en esos lenguajes puedan encontrar en tiempo de -ejecución el código de las bibliotecas de las que dependen, las dependencias -de tiempo de ejecución deben enumerarse en @code{propagated-inputs} en vez -de en @code{inputs}. - -@item @code{outputs} (predeterminada: @code{'("out")}) -La lista de nombres de salidas del paquete. @xref{Paquetes con múltiples salidas}, para usos típicos de salidas adicionales. - -@item @code{native-search-paths} (predeterminadas: @code{'()}) -@itemx @code{search-paths} (predeterminadas: @code{'()}) -Una lista de objetos @code{search-path-specification} describiendo las -variables de entorno de rutas de búsqueda respetadas por el paquete. - -@item @code{replacement} (predeterminado: @code{1.0}) -Esto debe ser o bien @code{#f} o bien un objeto package que será usado como -@dfn{reemplazo} para ete paquete. @xref{Actualizaciones de seguridad, injertos}, para -más detalles. - -@item @code{synopsis} -Una descripción en una línea del paquete. - -@item @code{description} -Una descripción más elaborada del paquete. - -@item @code{license} -@cindex licencia, de paquetes -La licencia del paquete; un valor de @code{(guix licenses)}, o una lista de -dichos valores. - -@item @code{home-page} -La URL de la página principal del paquete, como una cadena. - -@item @code{supported-systems} (predeterminados: @code{%supported-systems}) -La lista de sistemas en los que se mantiene el paquete, como cadenas de la -forma @code{arquitectura-núcleo}, por ejemplo @code{"x86_64-linux"}. - -@item @code{maintainers} (predeterminadas: @code{'()}) -La lista de responsables del paquete, como objetos @code{maintainer}. - -@item @code{location} (predeterminada: la localización de los fuentes de la forma @code{package}) -La localización de las fuentes del paquete. Es útil forzar su valor cuando -se hereda de otro paquete, en cuyo caso este campo no se corrige -automáticamente. -@end table -@end deftp - -@deffn {Scheme Syntax} this-package -When used in the @emph{lexical scope} of a package field definition, this -identifier resolves to the package being defined. - -The example below shows how to add a package as a native input of itself -when cross-compiling: - -@example -(package - (name "guile") - ;; ... - - ;; When cross-compiled, Guile, for example, depends on - ;; a native version of itself. Add it here. - (native-inputs (if (%current-target-system) - `(("self" ,this-package)) - '()))) -@end example - -It is an error to refer to @code{this-package} outside a package definition. -@end deffn - -@node Referencia de ``origin'' -@subsection Referencia de @code{origin} - -Esta sección resume todas las opciones disponibles en declaraciones -@code{origin} (@pxref{Definición de paquetes}). - -@deftp {Tipo de datos} origin -Este es el tipo de datos que representa un origen de código fuente. - -@table @asis -@item @code{uri} -Un objeto que contiene el URI de las fuentes. El tipo de objeto depende del -valor de @code{method} (véase a continuación). Por ejemplo, cuando se usa el -método @var{url-fetch} de @code{(guix download)}, los valores válidos de -@code{uri} son: una cadena que contiene una URL, o una lista de cadenas. - -@item @code{method} -Un procedimiento que maneja el URI. - -Algunos ejemplos son: - -@table @asis -@item @var{url-fetch} de @code{(guix download)} -descarga un fichero de la URL HTTP, HTTPS o FTP especificada en el campo -@code{uri}; - -@vindex git-fetch -@item @var{git-fetch} de @code{(guix git-download)} -clona el repositorio de control de versiones Git, y prepara la revisión -especificada en el campo @code{uri} como un objeto @code{git-reference}; una -referencia @code{git-reference} tiene esta forma: - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -Un vector de bytes que contiene el hash SHA-256 de las fuentes. Típicamente -la forma @code{base32} se usa aquí para generar el vector de bytes de una -cadena en base-32. - -Puede obtener esta información usando @code{guix download} (@pxref{Invocación de guix download}) o @code{guix hash} (@pxref{Invocación de guix hash}). - -@item @code{file-name} (predeterminado: @code{#f}) -El nombre de fichero bajo el que el código fuente se almacenará. Cuando este -es @code{#f}, un valor predeterminado sensato se usará en la mayor parte de -casos. En caso de que las fuentes se obtengan de una URL, el nombre de -fichero de la URL se usará. Para copias de trabajo de sistemas de control de -versiones, se recomienda proporcionar el nombre de fichero explícitamente ya -que el predeterminado no es muy descriptivo. - -@item @code{patches} (predeterminados: @code{'()}) -Una lista de nombres de ficheros, orígenes u objetos tipo-fichero -(@pxref{Expresiones-G, objetos tipo-fichero}) apuntando a parches que deben -ser aplicados a las fuentes. - -La lista de parches debe ser incondicional. En particular, no puede depender -del varlo de @code{%current-system} o @code{%current-target-system}. - -@item @code{snippet} (predeterminado: @code{#f}) -Una expresión-G (@pxref{Expresiones-G}) o expresión-S que se ejecutará en el -directorio de fuentes. Esta es una forma conveniente de modificar el -software, a veces más que un parche. - -@item @code{patch-flags} (predeterminadas: @code{'("-p1")}) -Una lista de opciones de línea de órdenes que deberían ser pasadas a la -orden @code{patch}. - -@item @code{patch-inputs} (predeterminada: @code{#f}) -Paquetes o derivaciones de entrada al proceso de aplicación de los -parches. Cuando es @code{#f}, se proporciona el conjunto habitual de -entradas necesarias para la aplicación de parches, como GNU@tie{}Patch. - -@item @code{modules} (predeterminados: @code{'()}) -Una lista de módulos Guile que debe ser cargada durante el proceso de -aplicación de parches y mientras se ejecuta el código del campo -@code{snippet}. - -@item @code{patch-guile} (predeterminado: @code{#f}) -El paquete Guile que debe ser usado durante la aplicación de parches. Cuando -es @code{#f} se usa un valor predeterminado. -@end table -@end deftp - - -@node Sistemas de construcción -@section Sistemas de construcción - -@cindex sistema de construcción -Cada definición de paquete especifica un @dfn{sistema de construcción} y -parámetros para dicho sistema de construcción (@pxref{Definición de paquetes}). Este campo @code{build-system} representa el procedimiento de -construcción del paquete, así como las dependencias implícitas de dicho -procedimiento de construcción. - -Los sistemas de construcción son objetos @code{}. La interfaz -para crear y manipularlos se proporciona en el módulo @code{(guix -build-system)}, y otros módulos exportan sistemas de construcción reales. - -@cindex bag (representación de paquetes de bajo nivel) -En su implementación, los sistemas de construcción primero compilan los -objetos package a objetos @dfn{bag}. Una bolsa (traducción de @dfn{bag}) es -como un paquete, pero con menos ornamentos---en otras palabras, una bolsa es -una representación a un nivel más bajo de un paquete, que contiene todas las -entradas de dicho paquete, incluyendo algunas implícitamente añadidas por el -sistema de construcción. Esta representación intermedia se compila entonces -a una derivación (@pxref{Derivaciones}). - -Los sistemas de construcción aceptan una lista opcional de -@dfn{parámetros}. En las definiciones de paquete, estos son pasados @i{vía} -el campo @code{arguments} (@pxref{Definición de paquetes}). Normalmente son -parámetros con palabras clave (@pxref{Optional Arguments, keyword arguments -in Guile,, guile, GNU Guile Reference Manual}). El valor de estos parámetros -normalmente se evalúa en la @dfn{capa de construcción}---es decir, por un -proceso Guile lanzado por el daemon (@pxref{Derivaciones}). - -El sistema de construcción principal es @var{gnu-build-system}, el cual -implementa el procedimiento estándar de construcción para GNU y muchos otros -paquetes. Se proporciona por el módulo @code{(guix build-system gnu)}. - -@defvr {Variable Scheme} gnu-build-system -@var{gnu-build-system} representa el sistema de construcción GNU y sus -variantes (@pxref{Configuration, configuration and makefile conventions,, -standards, GNU Coding Standards}). - -@cindex fases de construcción -En resumen, los paquetes que lo usan se configuran, construyen e instalan -con la habitual secuencia de órdenes @code{./configure && make && make check -&& make install}. En la práctica, algunos pasos adicionales son necesarios -habitualmente. Todos estos pasos se dividen en @dfn{fases} separadas, -notablemente@footnote{Rogamos que se inspeccionen los módulos @code{(guix -build gnu-build-system)} para más detalles sobre las fases de construcción}: - -@table @code -@item unpack -Extrae el archivador tar de la fuente, y cambia el directorio actual al -directorio recién extraído. Si la fuente es realmente un directorio, lo -copia al árbol de construcción y entra en ese directorio. - -@item patch-source-shebangs -Sustituye secuencias ``#!'' encontradas al inicio de los ficheros de fuentes -para que hagan referencia a los nombres correctos de ficheros del -almacén. Por ejemplo, esto cambia @code{#!/bin/sh} por -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. - -@item configure -Ejecuta el guión @file{configure} con algunas opciones predeterminadas, como -@code{--prefix=/gnu/store/@dots{}}, así como las opciones especificadas por -el parámetro @code{#:configure-flags}. - -@item build -Ejecuta @code{make} con la lista de opciones especificadas en -@code{#:make-flags}. Si el parámetro @code{#:parallel-build?} es verdadero -(por defecto), construye con @code{make -j}. - -@item check -Ejecuta @code{make check}, u otro objetivo especificado con -@code{#:test-target}, a menos que se pasase @code{#:tests? #f}. Si el -parámetro @code{#:parallel-tests?} es verdadero (por defecto), ejecuta -@code{make check -j}. - -@item install -Ejecuta @code{make install} con las opciones enumeradas en -@code{#:make-flags}. - -@item patch-shebangs -Sustituye las secuencias ``#!'' en los ficheros ejecutables instalados. - -@item strip -Extrae los símbolos de depuración de ficheros ELF (a menos que el valor de -@code{#:strip-binaries?} sea falso), copiandolos a la salida @code{debug} -cuando esté disponible (@pxref{Instalación de ficheros de depuración}). -@end table - -@vindex %standard-phases -El módulo del lado de construcción @code{(guix build gnu-build-system)} -define @var{%standard-phases} como la lista predeterminada de fases de -construcción. @var{%standard-phases} es una lista de pares -símbolo/procedimiento, donde el procedimiento implementa la fase real. - -La lista de fases usadas para un paquete particular se puede cambiar con el -parámetro @code{#:phases}. Por ejemplo, pasar: - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -significa que todas las fases descritas anteriormente serán usadas, excepto -la fase @code{configure}. - -Además, este sistema de construcción asegura que el entorno ``estándar'' -para paquetes GNU está disponible. Esto incluye herramientas como GCC, libc, -Coreutils, Bash, Make, Diffutils, grep y sed (vea el módulo @code{(guix -build system gnu)} para una lista completa). A estas las llamamos las -@dfn{entradas implícitas} de un paquete, porque las definiciones de paquete -no las mencionan. -@end defvr - -Se han definido otros objetos @code{} para implementar otras -convenciones y herramientas usadas por paquetes de software libre. Heredan -la mayor parte de @var{gnu-build-system}, y se diferencian principalmente en -el conjunto de entradas implícitamente añadidas al proceso de construcción, -y en la lista de fases ejecutadas. Algunos de estos sistemas de construcción -se enumeran a continuación. - -@defvr {Variable Scheme} ant-build-system -@code{(guix build-system ant)} exporta esta variable. Implementa el -procedimiento de construcción de paquetes Java que pueden construirse con -@url{http://ant.apache.org/, la herramienta de construcción Ant}. - -Añade tanto @code{ant} como el @dfn{kit de desarrollo Java} (JDK), que -proporciona el paquete @code{icedtea}, al conjunto de entradas. Se pueden -especificar paquetes diferentes con los parámetros @code{#:ant} y -@code{#:jdk}, respectivamente. - -Cuando el paquete original no proporciona un fichero Ant apropiado, el -parámetro @code{#:jar-name} puede usarse para generar un fichero de -construcción Ant @file{build.xml} mínimo con tareas para construir el -archivo jar especificado. En este caso, el parámetro @code{#:source-dir} se -puede usar para especificar el subdirectorio de fuentes, con ``src'' como -valor predeterminado. - -El parámetro @code{#:main-class} puede usarse con el fichero de construcción -Ant mínimo para especificar la clase main del archivo jar producido. Esto -permite ejecutar el archivo jar. El parámetro @code{#:test-include} puede -usarse para especificar la lista de tests junit a ejecutar. El valor -predeterminado es @code{(list "**/*Test.java")}. @code{#:test-exclude} puede -usarse para desactivar algunas pruebas. Su valor predeterminado es -@code{(list "**/Abstract*.java")} ya que las clases abstractas no se pueden -ejecutar como pruebas. - -El parámetro @code{#:build-target} se puede usar para especificar la tarea -Ant que debe ser ejecutada durante la fase @code{build}. Por defecto se -ejecuta la tarea ``jar''. - -@end defvr - -@defvr {Variable Scheme} androd-ndk-build-system -@cindex distribución Android -@cindex Sistema de construcción NDK de Android -Esta variable es exportada por @code{(guix build-system -android-ndk)}. Implementa un procedimiento de construcción para paquetes -Android NDK (kit de desarrollo nativo) usando un proceso de construcción -específico de Guix. - -El sistema de construcción asume que los paquetes instalan sus ficheros de -interfaz pública (cabeceras) en el subdirectorio "include" de la salida -"out" y sus bibliotecas en el subdirectorio "lib" de la salida "out". - -También se asume que la unión de todas las dependencias de un paquete no -tiene ficheros en conflicto. - -En este momento no funciona la compilación cruzada - por lo que las -bibliotecas y los ficheros de cabecera se asumen que son locales. - -@end defvr - -@defvr {Variable Scheme} asdf-build-system/source -@defvrx {Variable Scheme} asdf-build-system/sbcl -@defvrx {Variable Scheme} asdf-build-system/ecl - -Estas variables, exportadas por @code{(guix build-system asdf)}, implementan -procedimientos de construcción para paquetes Common Lisp usando -@url{https://common-lisp.net/project/asdf, ``ASDF'''}. ASDF es una utilidad -de definición de sistema para programas y bibliotecas Common Lisp. - -El sistema @code{asdf-build-system/source} instala los paquetes en forma de -fuentes, y puede ser cargado usando cualquier implementación common lisp, -vía ASDF. Los otros, como @code{asdf-build-system/sbcl}, instalan sistemas -binarios en el formato entendido por una implementación particular. Estos -sistemas de construcción también pueden usarse para producir programas -ejecutables, o imágenes lisp que contengan un conjunto precargado de -paquetes. - -El sistema de construcción usa convenciones de nombres. Para paquetes -binarios, el paquete debería estar prefijado con la implementación lisp, -como @code{sbcl-} para @code{asdf-build-system/sbcl}. - -Adicionalmente, el paquete de fuentes correspondiente debe etiquetarse -usando la misma convención que los paquetes python (vea @ref{Módulos Python}), usando el prefijo @code{cl-}. - -Para paquetes binarios, cada sistema debe definirse como un paquete Guix. Si -el campo @code{origin} de un paquete contiene varios sistemas, las -variaciones del paquete pueden crearse para construir todos los -sistemas. Los paquetes de fuentes, los cuales usan -@code{asdf-build-system/source}, pueden contener varios sistemas. - -Para crear programa ejecutables e imágenes, se pueden usar los -procedimientos del lado de construcción @code{build-program} y -@code{build-image}. Deben llamarse en la fase de construcción después de la -fase @code{create-symlinks}, de modo que el sistema recién construido pueda -ser usado dentro de la imagen resultante. @code{build-program} necesita una -lista de expresiones Common Lisp a través del parámetro -@code{#:entry-prgogram}. - -Si el sistema no está definido en su propio fichero @code{.asd} del mismo -nombre, entonces se debe usar el parámetro @code{#:asd-file} para -especificar el fichero en el que se define el sistema. Más allá, si el -paquete define un sistema para sus pruebas en su fichero separado, se -cargará antes de la ejecución de las pruebas si se especifica el parámetro -@code{#:test-asd-file}. Si no se especifica, se probarán si existen los -ficheros @code{-tests.asd}, @code{-test.asd}, -@code{tests.asd} y @code{test.asd}. - -Si por alguna razón el paquete debe ser nombrado de una forma diferente a la -sugerida por las convenciones de nombres, el parámetro -@code{#:asd-system-name} puede usarse para especificar el nombre del -sistema. - -@end defvr - -@defvr {Variable Scheme} cargo-build-system -@cindex lenguaje de programación Rust -@cindex Cargo (sistema de construcción de Rust) -Esta variable se exporta en @code{(guix build-system cargo)}. Permite la -construcción de paquetes usando Cargo, la herramienta de construcción del -@uref{https://www.rust-lang.org, lenguaje de programación Rust}. - -En su fase @code{configure}, este sistema de construcción substituye las -dependencias especificadas en el fichero @file{Cargo.toml} con entradas a -los paquetes Guix. La fase @code{install} instala los binarios, y también -instala el código fuente y el fichero @file{Cargo.toml}. -@end defvr - -@cindex Clojure (lenguaje de programación) -@cindex sistema de construcción simple de Clojure -@defvr {Variable Scheme} clojure-build-system -Esta variable se exporta en @code{(guix build-system clojure)}. Implementa -un procedimiento de construcción simple para paquetes -@uref{https://clojure.org/, Clojure} usando directamente @code{compile} en -Clojure. La compilación cruzada no está disponible todavía. - -Añade @code{clojure}, @code{icedtea} y @code{zip} al conjunto de -entradas. Se pueden especificar paquetes diferentes con los parámetros -@code{#:clojure}, @code{#:jdk} y @code{#:zip}, respectivamente. - -Una lista de directorios de fuentes, directorios de pruebas y nombres de jar -pueden especificarse con los parámetros @code{#:source-dirs}, -@code{#:test-dirs} y @code{#:jar-names}, respectivamente. El directorio de -compilación y la clase principal pueden especificarse con los parámetros -@code{#:compile-dir} y @code{#:main-class}, respectivamente. Otros -parámetros se documentan más adelante. - -Este sistema de construcción es una extensión de @var{ant-build-system}, -pero con las siguientes fases cambiadas: - -@table @code - -@item build -Esta fase llama @code{compile} en Clojure para compilar los ficheros de -fuentes y ejecuta @command{jar} para crear archivadores jar tanto de -ficheros de fuentes y compilados de acuerdo con las listas de inclusión y -exclusión especificadas en @code{#:aot-include} y @code{#:aot-exclude}, -respectivamente. La lista de exclusión tiene prioridad sobre la de -inclusión. Estas listas consisten en símbolos que representan bibliotecas -Clojure o la palabra clave especial @code{#:all} que representa todas las -bibliotecas encontradas en los directorios de fuentes. El parámetro -@code{#:omit-source?} determina si las fuentes deben incluirse en los -archivadores jar. - -@item check -Esta fase ejecuta las pruebas de acuerdo a las listas de inclusión y -exclusión especificadas en @code{#:test-include} y @code{#:test-exclude}, -respectivamente. Sus significados son análogos a los de @code{#:aot-include} -y @code{#:aot-exclude}, excepto que la palabra clave especial @code{#:all} -designa ahora a todas las bibliotecas Clojure encontradas en los directorios -de pruebas. El parámetro @code{#:tests?} determina si se deben ejecutar las -pruebas. - -@item install -Esta fase instala todos los archivadores jar construidos previamente. -@end table - -Además de las previas, este sistema de construcción contiene una fase -adicional: - -@table @code - -@item install-doc -Esta fase instala todos los ficheros de nivel superior con un nombre que -corresponda con @var{%doc-regex}. Una expresión regular diferente se puede -especificar con el parámetro @code{#:doc-regex}. Todos los ficheros dentro -(recursivamente) de los directorios de documentación especificados en -@code{#:doc-dirs} se instalan también. -@end table -@end defvr - -@defvr {Variable Scheme} cmake-build-system -Esta variable se exporta en @code{(guix build-system cmake)}. Implementa el -procedimiento de construcción para paquetes que usen la -@url{http://www.cmake.org, herramienta de construcción CMake}. - -Automáticamente añade el paquete @code{cmake} al conjunto de entradas. El -paquete usado se puede especificar con el parámetro @code{#:cmake}. - -El parámetro @code{#:configure-flags} se toma como una lista de opciones a -pasar a @command{cmake}. El parámetro @code{#:build-type} especifica en -términos abstractos las opciones pasadas al compilador; su valor -predeterminado es @code{"RelWithDebInfo"} (quiere decir ``modo de entrega -con información de depuración''), lo que aproximadamente significa que el -código se compila con @code{-O2 -g}, lo cual es el caso predeterminado en -paquetes basados en Autoconf. -@end defvr - -@defvr {Variable Scheme} 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. - -Automáticamente añade el paquete @code{dune} al conjunto de entradas. El -paquete usado se puede especificar con el parámetro @code{#:dune}. - -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}. - -The @code{#:package} parameter can be passed to specify a package name, -which is useful when a package contains multiple packages and you want to -build only one of them. This is equivalent to passing the @code{-p} -argument to @code{dune}. -@end defvr - -@defvr {Variable Scheme} go-build-system -Esta variable se exporta en @code{(guix build-system go)}. Implementa el -procedimiento de construcción para paquetes Go usando los -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, -mecanismos de construcción de Go} estándares. - -Se espera que la usuaria proporcione un valor para el parámetro -@code{#:import-path} y, en algunos caso, @code{#:unpack-path}. La -@url{https://golang.org/doc/code.html#ImportPaths, ruta de importación} -corresponde a la ruta del sistema de ficheros esperada por los guiones de -construcción del paquete y los paquetes referenciados, y proporciona una -forma de referenciar un paquete Go unívocamente. Está basado típicamente en -una combinación de la URI remota del paquete de ficheros de fuente y la -estructura jerárquica del sistema de ficheros. En algunos casos, necesitará -desempaquetar el código fuente del paquete en una estructura de directorios -diferente a la indicada en la ruta de importación, y @code{#:unpack-path} -debe usarse en dichos casos. - -Los paquetes que proporcionan bibliotecas Go deben instalar su código fuente -en la salida de la construcción. El parámetro @code{#:install-source?}, cuyo -valor por defecto es @code{#t}, controla si se instalará o no el código -fuente. Puede proporcionarse @code{#f} en paquetes que proporcionan -únicamente ficheros ejecutables. -@end defvr - -@defvr {Variable Scheme} glib-or-gtk-build-system -Esta variable se exporta en @code{(guix build-system glib-or-gtk)}. Está -pensada para usarse con paquetes que usan GLib o GTK+. - -Este sistema de construcción añade las siguientes dos fases a las definidas -en @var{gnu-build-system}: - -@table @code -@item glib-or-gtk-wrap -La fase @code{glib-or-gtk-wrap} se asegura de que los programas en -@file{bin/} son capaces de encontrar los ``esquemas'' GLib y los -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, módulos -GTK+}. Esto se consigue recubriendo los programas en guiones de lanzamiento -que establecen apropiadamente las variables de entorno @code{GTK_PATH}. - -Es posible excluir salidas específicas del paquete del proceso de -recubrimiento enumerando sus nombres en el parámetro -@code{#:glib-org-gtk-wrap-excluded-outputs}. Esto es útil cuando se sabe que -una salida no contiene binarios GLib o GTK+, y cuando empaquetar -gratuitamente añadiría una dependencia de dicha salida en GLib y GTK+. - -@item glib-or-gtk-compile-schemas -La fase @code{glib-or-gtk-compile-schemas} se asegura que todos los -@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -esquemas GSettings} o GLib se compilan. La compilación la realiza el -programa @command{glib-compile-schemas}. Lo proporciona el paquete -@code{glib:bin} que se importa automáticamente por el sistema de -construcción. El paquete @code{glib} que proporciona -@command{glib-compile-schemas} puede especificarse con el parámetro -@code{#:glib}. -@end table - -Ambas fases se ejecutan tras la fase @code{install}. -@end defvr - -@defvr {Variable Scheme} guile-build-system -Este sistema de construcción es para paquetes Guile que consisten -exclusivamente en código Scheme y son tan simples que no tienen ni siquiera -un fichero Makefile, menos un guión @file{configure}. Compila código Scheme -usando @command{guild compile} (@pxref{Compilation,,, guile, GNU Guile -Reference Manual}) e instala los ficheros @file{.scm} y @file{.go} en el -lugar correcto. También instala documentación. - -Este sistema de construcción permite la compilación cruzada usando la opción -@code{--target} de @command{guild compile}. - -Los paquetes construidos con @code{guile-build-system} deben proporcionar un -paquete Guile en su campo @code{native-inputs}. -@end defvr - -@defvr {Variable Scheme} minify-build-system -Esta variable se exporta en @code{(guix build-system minify)}. Implementa un -procedimiento de minificación para paquetes JavaScript simples. - -Añade @code{uglify-js} al conjunto de entradas y lo utiliza para comprimir -todos los ficheros JavaScript en el directorio @file{src}. Un paquete de -minificación diferente puede especificarse con el parámetro -@code{#:uglify-js}, pero se espera que el paquete escriba el código -minificado en la salida estándar. - -Cuando los ficheros JavaScript de entrada no se encuentran en el directorio -@file{src}, el parámetro @code{#:javascript-files} puede usarse para -especificar una lista de nombres de fichero que proporcionar al minificador. -@end defvr - -@defvr {Variable Scheme} ocaml-build-system -Esta variable se exporta en @code{(guix build-system ocaml)}. Implementa un -procedimiento de construcción para paquetes @uref{https://ocaml.org, OCaml}, -que consiste en seleccionar el conjunto correcto de órdenes a ejecutar para -cada paquete. Los paquetes OCaml pueden esperar la ejecución de muchas -ordenes diferentes. Este sistema de construcción probará algunas de ellas. - -Cuando el paquete tiene un fichero @file{setup.ml} presente en el nivel -superior, se ejecuta @code{ocaml setup.ml -configure}, @code{ocaml setup.ml --build} y @code{ocaml setup.ml -install}. El sistema de construcción asumirá -que este fichero se generó con @uref{http://oasis.forge.ocamlcore.org/ -OASIS} y se encargará de establecer el prefijo y la habilitación de las -pruebas si no están deshabilitadas. Puede pasar opciones de configuración y -construcción con @code{#:configure-flags} y @code{#:build-flags}, -respectivamente. El parámetro @code{#:test-flags} puede usarse para cambiar -el conjunto de opciones usadas para activar las pruebas. El parámetro -@code{#:use-make?} puede usarse para ignorar este sistema en las fases de -construcción e instalación. - -Cuando el paquete tiene un fichero @file{configure}, se asume que es un -guión de configuración hecho a mano que necesita un formato de parámetros -diferente a los del sistema @code{gnu-build-system}. Puede añadir más -opciones con el parámetro @code{#:configure-flags}. - -Cuando el paquete tiene un fichero @file{Makefile} (o @code{#:use-make?} es -@code{#t}), será usado y se pueden proporcionar más opciones para las fases -de construcción y e instalación con el parámetro @code{#:make-flags}. - -Por último, algunos paquetes no tienen estos ficheros y usan unas -localizaciones de algún modo estándares para su sistema de construcción. En -este caso, el sistema de construcción ejecutará @code{ocaml pkg/pkg.ml} o -@code{ocaml pkg/build.ml} y se hará cargo de proporcionar la ruta del módulo -findlib necesario. Se pueden pasar opciones adicionales con el parámetro -@code{#:build-flags}. De la instalación se hace cargo -@command{opam-installer}. En este caso, el paquete @code{opam} debe añadirse -al campo @code{native-inputs} de la definición del paquete. - -Fíjese que la mayoría de los paquetes OCaml asumen su instalación en el -mismo directorio que OCaml, que no es el comportamiento deseado en guix. En -particular, intentarán instalar ficheros @file{.so} en su directorio de -módulos, normalmente lo adecuado puesto que es el directorio del compilador -de OCaml. No obstante, en guix estas bibliotecas no se pueden encontrar allí -y usamos @code{CAML_LD_LIBRARY_PATH}. Esta variable apunta a -@file{lib/ocaml/site-lib/stubslibs} y allí es donde las bibliotecas -@file{.so} deben instalarse. -@end defvr - -@defvr {Variable Scheme} python-build-system -Esta variable se exporta en @code{(guix build-system python)}. Implementa el -procedimiento más o menos estándar de construcción usado por paquetes -Python, que consiste en la ejecución de @code{python setup.py build} y -@code{python setup.py install --prefix=/gnu/store/@dots{}}. - -Para que instalan programas independientes Python bajo @code{bin/}, se -encarga de envolver dichos programas de modo que su variable de entorno -@code{PYTHONPATH} apunte a las bibliotecas Python de las que dependen. - -Se puede especificar el paquete Python usado para llevar a cabo la -construcción con el parámetro @code{#:python}. Esta es habitualmente una -forma de forzar la construcción de un paquete para una versión específica -del intérprete Python, lo que puede ser necesario si el paquete es -compatible únicamente con una versión del intérprete. - -Por defecto guix llama a @code{setup.py} bajo el control de -@code{setuptools} de manera similar a @command{pip}. Algunos paquetes no son -compatibles con setuptools (y pip), por lo que puede deshabilitar esta -configuración estableciendo el parámetro @code{#:use-setuptools} a -@code{#f}. -@end defvr - -@defvr {Variable Scheme} perl-build-system -Esta variable se exporta en @code{(guix build-system perl)}. Implementa el -procedimiento de construcción estándar para paquetes Perl, lo que o bien -consiste en la ejecución de @code{perl Build.PL ---prefix=/gnu/store/@dots{}}, seguido de @code{Build} y @code{Build -install}; o en la ejecución de @code{perl Makefile.PL -PREFIX=/gnu/store/@dots{}}, seguida de @code{make} y @code{make install}, -dependiendo de si @code{Build.PL} o @code{Makefile.PL} están presentes en la -distribución del paquete. El primero tiene preferencia si existen tanto -@code{Build.PL} como @code{Makefile.PL} en la distribución del paquete. Esta -preferencia puede invertirse especificando @code{#t} en el parámetro -@code{#:make-maker?}. - -La invocación inicial de @code{perl Makefile.PL} o @code{perl Build.PL} pasa -a su vez las opciones especificadas por los parámetros -@code{#:make-maker-flags} o @code{#:module-build-flags}, respectivamente. - -El paquete Perl usado puede especificarse con @code{#:perl}. -@end defvr - -@defvr {Variable Scheme} r-build-system -Esta variable se exporta en @code{(guix build-system r)}. Implementa el -procedimiento de construcción usados por paquetes -@uref{http://r-project.org, R}, lo que esencialmente es poco más que la -ejecución de @code{R CMD INSTALL --library=/gnu/store/@dots{}} en un entorno -donde @code{R_LIBS_SITE} contiene las rutas de todos los paquetes R de -entrada. Las pruebas se ejecutan tras la instalación usando la función R -@code{tools::testInstalledPackage}. -@end defvr - -@defvr {Variable Scheme} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It implements -the build procedure used by @uref{https://rakudo.org/, Rakudo} for -@uref{https://perl6.org/, Perl6} packages. It installs the package to -@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the -binaries, library files and the resources, as well as wrap the files under -the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the -@code{tests?} parameter. - -Which rakudo package is used can be specified with @code{rakudo}. Which -perl6-tap-harness package used for the tests can be specified with -@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} -parameter. Which perl6-zef package used for tests and installing can be -specified with @code{#:zef} or removed by passing @code{#f} to the -@code{with-zef?} parameter. -@end defvr - -@defvr {Variable Scheme} texlive-build-system -Esta variable se exporta en @code{(guix build-system texlive)}. Se usa para -construir paquetes TeX en modo de procesamiento de lotes con el motor -especificado. El sistema de construcción fija la variable @code{TEXINPUTS} -para encontrar todos los ficheros de fuentes TeX en las entradas. - -Por defecto ejecuta @code{luatex} en todos los ficheros que terminan en -@code{ins}. Un motor y formato diferente puede especificarse con el -parámetro @code{#:tex-format}. Los diferentes objetivos de construcción -pueden especificarse con el parámetro @code{#:build-targets}, que espera una -lista de nombres de fichero. El sistema de construcción añade únicamente -@code{texlive-bin} y @code{texlive-latex-base} (ambos desde @code{(gnu -packages tex)} a las entradas. Ambos pueden forzarse con los parámetros -@code{#:texlive-bin} y @code{#:texlive-latex-base} respectivamente. - -El parámetro @code{#:tex-directory} le dice al sistema de construcción dónde -instalar los ficheros construidos bajo el árbol texmf. -@end defvr - -@defvr {Variable Scheme} ruby-build-system -Esta variable se exporta en @code{(guix build-system ruby)}. Implementa el -procedimiento de construcción de RubyGems usado por los paquetes Ruby, que -implica la ejecución de @code{gem build} seguida de @code{gem install}. - -El campo @code{source} de un paquete que usa este sistema de construcción -típicamente se refiere a un archivo gem, ya que este es el formato usado por -las desarrolladoras Ruby cuando publican su software. El sistema de -construcción desempaqueta el archivo gem, potencialmente parchea las -fuentes, ejecuta la batería de pruebas, vuelve a empaquetar el archivo gem y -lo instala. Adicionalmente, directorios y archivadores tar pueden -referenciarse para permitir la construcción de archivos gem no publicados -desde Git o un archivador tar de publicación de fuentes tradicional. - -Se puede especificar el paquete Ruby usado mediante el parámetro -@code{#:ruby}. Una lista de opciones adicionales pueden pasarse a la orden -@command{gem} en el parámetro @code{#:gem-flags}. -@end defvr - -@defvr {Variable Scheme} waf-build-system -Esta variable se exporta en @code{(guix build-system waf)}. Implementa un -procedimiento de construcción alrededor del guión @code{waf}. Las fases -comunes---@code{configure}, @code{build} y @code{install}---se implementan -pasando sus nombres como parámetros al guión @code{waf}. - -El guión @code{waf} es ejecutado por el intérprete Python. El paquete Python -usado para la ejecución puede ser especificado con el parámetro -@code{#:python}. -@end defvr - -@defvr {Variable Scheme} scons-build-system -Esta variable se exporta en @code{(guix build-system scons)}. Implementa en -procedimiento de construcción usado por la herramienta de construcción de -software SCons. Este sistema de construcción ejecuta @code{scons} para -construir el paquete, @code{scons test} para ejecutar las pruebas y después -@code{scons install} para instalar el paquete. - -Las opciones adicionales a pasar a @code{scons} se pueden especificar con el -parámetro @code{#:scons-flags}. La versión de Python usada para ejecutar -SCons puede especificarse seleccionando el paquete SCons apropiado con el -parámetro @code{#:scons}. -@end defvr - -@defvr {Variable Scheme} haskell-build-system -Esta variable se exporta en @code{(guix build-system haskell)}. Implementa -el procedimiento de construcción Cabal usado por paquetes Haskell, el cual -implica la ejecución de @code{runhaskell Setup.hs configure ---prefix=/gnu/store/@dots{}} y @code{runhaskell Setup.hs build}. En vez de -instalar el paquete ejecutando @code{runhaskell Setup.hs install}, para -evitar el intento de registro de bibliotecas en el directorio de -solo-lectura del compilador en el almacén, el sistema de construcción usa -@code{runhaskell Setup.hs copy}, seguido de @code{runhaskell Setup.hs -register}. Además, el sistema de construcción genera la documentación del -paquete ejecutando @code{runhaskell Setup.hs haddock}, a menos que se pasase -@code{#:haddock? #f}. Parámetros opcionales de Haddock pueden proporcionarse -con la ayuda del parámetro @code{#:haddock-flags}. Si el fichero -@code{Setup.hs} no es encontrado, el sistema de construcción busca -@code{Setup.lhs} a su vez. - -El compilador Haskell usado puede especificarse con el parámetro -@code{#:haskell} cuyo valor predeterminado es @code{ghc}. -@end defvr - -@defvr {Variable Scheme} dub-build-system -Esta variable se exporta en @code{(guix build-system dub)}. Implementa el -procedimiento de construcción Dub usado por los paquetes D, que implica la -ejecución de @code{dub build} y @code{dub run}. La instalación se lleva a -cabo con la copia manual de los ficheros. - -El compilador D usado puede ser especificado con el parámetro @code{#:ldc} -cuyo valor predeterminado es @code{ldc}. -@end defvr - -@defvr {Variable Scheme} emacs-build-system -Esta variable se exporta en @code{(guix build-system emacs)}. Implementa un -procedimiento de instalación similar al propio sistema de empaquetado de -Emacs (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Primero crea el fichero @code{@var{paquete}-autoloads.el}, tras lo que -compila todos los ficheros Emacs Lisp. De manera diferente al sistema de -paquetes de Emacs, los ficheros de documentación Info se mueven al -directorio estándar de documentación y se borra el fichero @file{dir}. Cada -paquete se instala en su propio directorio bajo -@file{share/emacs/site-lisp/guix.d}. -@end defvr - -@defvr {Variable Scheme} font-build-system -Esta variable se exporta en @code{(guix build-system font)}. Implementa un -procedimiento de instalación para paquetes de fuentes donde las proveedoras -originales proporcionan ficheros de tipografía TrueType, OpenType, etc.@: -precompilados que simplemente necesitan copiarse en su lugar. Copia los -ficheros de tipografías a las localizaciones estándar en el directorio de -salida. -@end defvr - -@defvr {Variable Scheme} meson-build-system -Esta variable se exporta en @code{(guix build-system meson)}. Implementa el -procedimiento de construcción para paquetes que usan -@url{http://mesonbuild.com, Meson} como su sistema de construcción. - -Añade Meson y @uref{https://ninja-build.org/, Ninja} al conjunto de -entradas, y pueden cambiarse con los parámetros @code{#:meson} y -@code{#:ninja} en caso necesario. La versión de Meson predeterminada es -@code{meson-for-build}, la cual es especial puesto que no limpia el -@code{RUNPATH} de los binarios y bibliotecas durante la instalación. - -Este sistema de construcción es una extensión de @var{gnu-build-system}, -pero con las siguientes fases cambiadas por otras específicas para Meson. - -@table @code - -@item configure -Esta fase ejecuta @code{meson} con las opciones especificadas en -@code{#:configure-flags}. La opción @code{--build-type} siempre se fija a -@code{plain} a menos que se especifique algo distinto en -@code{#:build-type}. - -@item build -Esta fase ejecuta @code{ninja} para construir el paquete en paralelo por -defecto, pero esto puede cambiarse con @code{#:parallel-build?}. - -@item check -Esta fase ejecuta @code{ninja} con el objetivo especificado en -@code{#:test-target}, cuyo valor predeterminado es @code{"test"}. - -@item install -Esta fase ejecuta @code{ninja install} y no puede cambiarse. -@end table - -Aparte de estas, el sistema de ejecución también añade las siguientes fases: - -@table @code - -@item fix-runpath -Esta fase se asegura de que todos los binarios pueden encontrar las -bibliotecas que necesitan. Busca las bibliotecas necesarias en -subdirectorios del paquete en construcción, y añade estas a @code{RUNPATH} -en caso necesario. También elimina referencias a bibliotecas introducidas en -la fase de construcción por @code{meson-for-build}, como las dependencias de -las pruebas, que no se necesitan realmente para la ejecución del programa. - -@item glib-or-gtk-wrap -Esta fase es la fase proporcionada por @code{glib-or-gtk-build-system}, y no -está activa por defecto. Puede activarse con @code{#:glib-or-gtk}. - -@item glib-or-gtk-compile-schemas -Esta fase es la fase proporcionada por @code{glib-or-gtk-build-system}, y no -está activa por defecto. Puede activarse con @code{#:glib-or-gtk}. -@end table -@end defvr - -@defvr {Scheme Variable} linux-module-build-system -@var{linux-module-build-system} allows building Linux kernel modules. - -@cindex fases de construcción -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed: - -@table @code - -@item configure -This phase configures the environment so that the Linux kernel's Makefile -can be used to build the external kernel module. - -@item build -This phase uses the Linux kernel's Makefile in order to build the external -kernel module. - -@item install -This phase uses the Linux kernel's Makefile in order to install the external -kernel module. -@end table - -It is possible and useful to specify the Linux kernel to use for building -the module (in the "arguments" form of a package using the -linux-module-build-system, use the key #:linux to specify it). -@end defvr - -Por último, para paquetes que no necesiten nada tan sofisticado se -proporciona un sistema de construcción ``trivial''. Es trivial en el sentido -de que no proporciona prácticamente funcionalidad: no incorpora entradas -implícitas y no tiene una noción de fases de construcción. - -@defvr {Variable Scheme} trivial-build-system -Esta variable se exporta en @code{(guix build-system trivial)}. - -Este sistema de construcción necesita un parámetro @code{#:builder}. Este -parámetro debe ser una expresión Scheme que construya la(s) salida(s) del -paquete---como en @code{build-expression->derivation} (@pxref{Derivaciones, -@code{build-expression->derivation}}). -@end defvr - -@node El almacén -@section El almacén - -@cindex almacén -@cindex elementos del almacén -@cindex rutas del almacén - -Conceptualmente, el @dfn{almacén} es el lugar donde se almacenan las -derivaciones cuya construcción fue satisfactoria---por defecto, -@file{/gnu/store}. Los subdirectorios en el almacén se denominan -@dfn{elementos del almacén} o @dfn{rutas del almacén} en ocasiones. El -almacén tiene una base de datos asociada que contiene información como las -rutas del almacén a las que referencia cada ruta del almacén, y la lista de -elementos @emph{válidos} del almacén---los resultados de las construcciones -satisfactorias. Esta base de datos reside en -@file{@var{localstatedir}/guix/db}, donde @var{localstatedir} es el -directorio de estado especificado @i{vía} @option{--localstatedir} en tiempo -de configuración, normalmente @file{/var}. - -El almacén @emph{siempre} es accedido a través del daemon en delegación de -sus clientes (@pxref{Invocación de guix-daemon}). Para manipular el almacén, los -clientes se conectan al daemon por un socket de dominio Unix, le envían -peticiones y leen el resultado---esto son llamadas a procedimientos remotos, -o RPC. - -@quotation Nota -Las usuarias @emph{nunca} deben modificar ficheros directamente bajo el -directorio @file{/gnu/store}. Esto llevaría a inconsistencias y rompería las -premisas de inmutabilidad del modelo funcional de Guix -(@pxref{Introducción}). - -@xref{Invocación de guix gc, @command{guix gc --verify}}, para información sobre -cómo comprobar la integridad del almacén e intentar recuperarse de -modificaciones accidentales. -@end quotation - -El módulo @code{(guix store)} proporciona procedimientos para conectarse al -daemon y realizar RPCs. Estos se describen más adelante. Por defecto, -@code{open-connection}, y por tanto todas las órdenes @command{guix}, se -conectan al daemon local o a la URI especificada en la variable de entorno -@code{GUIX_DAEMON_SOCKET}. - -@defvr {Variable de entorno} GUIX_DAEMON_SOCKET -Cuando se ha definido, el valor de esta variable debe ser un nombre de -fichero o una URI designando el punto de conexión del daemon. Cuando es un -nombre de fichero, denota un socket de dominio Unix al que -conectarse. Además de nombres de ficheros, los esquemas de URI aceptados -son: - -@table @code -@item file -@itemx unix -Estos son equivalentes a los sockets de dominio -Unix. @code{file:///var/guix/daemon-socket/socket} es equivalente a -@file{/var/guix/daemon-socket/socket}. - -@item guix -@cindex daemon, acceso remoto -@cindex acceso remoto al daemon -@cindex daemon, configuración en cluster -@cindex daemon, configuración en cluster -Estas URI denotan conexiones sobre TCP/IP, sin cifrado ni verificación de la -máquina remota. La URI debe especificar el nombre de máquina y opcionalmente -un número de puerto (por defecto se usa el puerto 44146): - -@example -guix://principal.guix.example.org:1234 -@end example - -Esta configuración es apropiada para redes locales, como clusters, donde -únicamente los nodos de confianza pueden conectarse al daemon de -construcción en @code{principal.guix.example.org}. - -La opción @code{--listen} de @command{guix-daemon} puede usarse para -indicarle que escuche conexiones TCP (@pxref{Invocación de guix-daemon, -@code{--listen}}). - -@item ssh -@cindex acceso SSH a los daemons de construcción -Estas URI le permiten conectarse a un daemon remoto sobre SSH@footnote{Esta -característica necesita Guile-SSH (@pxref{Requisitos}).}. Una URL típica -debería ser algo así: - -@example -ssh://carlos@@guix.example.org:22 -@end example - -Como con @command{guix copy}, se tienen en cuenta los ficheros habituales de -configuración del cliente OpenSSH (@pxref{Invocación de guix copy}). -@end table - -Esquemas URI adicionales pueden ser aceptados en el futuro. - -@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 Nota -La conexión con daemon de construcción remotos se considera experimental en -@value{VERSION}. Por favor, contacte con nosotras para compartir cualquier -problema o sugerencias que pueda tener (@pxref{Contribuir}). -@end quotation -@end defvr - -@deffn {Procedimiento Scheme} open-connection [@var{uri}] [#:reserve-space? #t] -Abre una conexión al daemon a través del socket de dominio Unix apuntado por -@var{uri} (una cadena). Cuando @var{reserve-space?} es verdadero, le indica -que reserve un poco de espacio extra en el sistema de ficheros de modo que -el recolector de basura pueda operar incluso cuando el disco se -llene. Devuelve un objeto servidor. - -El valor por defecto de @var{uri} es @var{%default-socket-path}, que ese la -ruta esperada según las opciones pasadas a @code{configure}. -@end deffn - -@deffn {Procedimiento Scheme} close-connection @var{servidor} -Cierra la conexión al @var{servidor}. -@end deffn - -@defvr {Variable Scheme} current-build-output-port -Esta variable está enlazada a un parámetro SRFI-39, que referencia al puerto -donde los logs de construcción y error enviados por el daemon deben -escribirse. -@end defvr - -Los procedimientos que realizan RPCs toman todos como primer parámetro un -objeto servidor. - -@deffn {Procedimiento Scheme} valid-path? @var{servidor} @var{ruta} -@cindex elementos inválidos del almacén -Devuelve @code{#t} cuando @var{ruta} designa un elemento válido del almacén -y @code{#f} en otro caso (un elemento no-válido puede existir en el disco -pero aun así no ser válido, por ejemlo debido a que es el resultado de una -construcción interumpida o fallida). - -Una condición @code{&store-protocol-error} se eleva si @var{ruta} no -contiene como prefijo el directorio del almacén (@file{/gnu/store}). -@end deffn - -@deffn {Procedimiento Scheme} add-text-to-store @var{servidor} @var{nombre} @var{texto} [@var{referencias}] -Añade @var{texto} bajo el fichero @var{nombre} en el almacén, y devuelve su -ruta en el almacén. @var{referencias} es la lista de rutas del almacén -referenciadas por la ruta del almacén resultante. -@end deffn - -@deffn {Procedimiento Scheme} build-derivations @var{servidor} @var{derivaciones} -Construye @var{derivaciones} (una lista de objetos @code{} o -rutas de derivaciones) y devuelve el control cuando se termina de -construirlas. Devuelve @code{#t} en caso de éxito. -@end deffn - -Fijese que el módulo @code{(guix monads)} proporciona una mónada así como -versiones monádicas de los procedimientos previos, con el objetivo de hacer -más conveniente el trabajo con código que accede al almacén (@pxref{La mónada del almacén}). - -@c FIXME -@i{Esta sección actualmente está incompleta.} - -@node Derivaciones -@section Derivaciones - -@cindex derivaciones -Las acciones de construcción a bajo nivel y el entorno en el que se realizan -se representan mediante @dfn{derivaciones}. Una derivación contiene las -siguientes piezas de información: - -@itemize -@item -Las salidas de la derivación---las derivaciones producen al menos un fichero -o directorio en el almacén, pero pueden producir más. - -@item -@cindex tiempo de construcción, dependencias -@cindex dependencias, tiempo de construcción -Las entradas de las derivaciones---es decir, sus dependencias de tiempo de -construcción---, que pueden ser otras derivaciones o simples ficheros en el -almacén (parches, guiones de construcción, etc.). - -@item -El tipo de sistema objetivo de la derivación---por ejemplo, -@code{x86_64-linux}. - -@item -El nombre de fichero del guión de construcción en el almacén, junto a los -parámetros que se le deben pasar. - -@item -Una lista de variables de entorno a ser definidas. - -@end itemize - -@cindex ruta de derivación -Las derivaciones permiten a los clientes del daemon comunicar acciones de -construcción al almacén. Existen en dos formas: como una representación en -memoria, tanto en el lado del cliente como el del daemon, y como ficheros en -el almacén cuyo nombre termina en @code{.drv}---estos ficheros se conocen -como @dfn{rutas de derivación}. Las rutas de derivación pueden pasarse al -procedimiento @code{build-derivations} para realizar las acciones de -construcción que prescriben (@pxref{El almacén}). - -@cindex derivaciones de salida fija -Operaciones como la descarga de ficheros y las instantáneas de un control de -versiones para las cuales el hash del contenido esperado se conoce -previamente se modelan como @dfn{derivaciones de salida fija}. Al contrario -que las derivaciones normales, las salidas de una derivación de salida fija -son independientes de sus entradas---por ejemplo, la descarga del código -fuente produce el mismo resultado independientemente del método de descarga -y las herramientas usadas. - -@cindex references -@cindex tiempo de ejecución, dependencias -@cindex dependencias, tiempo de ejecución -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{Invocación de 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. - -El módulo @code{(guix derivations)} proporciona una representación de -derivaciones como objetos Scheme, junto a procedimientos para crear y -manipular de otras formas derivaciones. La primitiva de más bajo nivel para -crear una derivación es el procedimiento @code{derivation}: - -@deffn {Procedimiento Scheme} derivation @var{almacén} @var{nombre} @var{constructor} @ - @var{args} [#: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 '()] -Construye una derivación con los parámetros proporcionados, y devuelve el -objeto @code{} resultante. - -Cuando se proporcionan @var{hash} y @var{hash-algo}, una @dfn{derivación de -salida fija} se crea---es decir, una cuyo resultado se conoce de antemano, -como la descarga de un fichero. Si, además, @var{recursive?} es verdadero, -entonces la salida fijada puede ser un fichero ejecutable o un directorio y -@var{hash} debe ser el hash de un archivador que contenga esta salida. - -Cuando @var{references-graphs} es verdadero, debe ser una lista de pares de -nombre de fichero/ruta del almacén. En ese caso, el grafo de referencias de -cada ruta del almacén se exporta en el entorno de construcción del fichero -correspondiente, en un formato de texto simple. - -Cuando @var{allowed-references} es verdadero, debe ser una lista de -elementos del almacén o salidas a las que puede hacer referencia la salida -de la derivación. Del mismo modo, @var{disallowed-references}, en caso de -ser verdadero, debe ser una lista de cosas a las que las salidas @emph{no} -pueden hacer referencia. - -Cuando @var{leaked-env-vars} es verdadero, debe ser una lista de cadenas que -denoten variables de entorno que se permite ``escapar'' del entorno del -daemon al entorno de construcción. Esto es únicamente aplicable a -derivaciones de salida fija---es decir, cuando @var{hash} es verdadero. El -uso principal es permitir que variables como @code{http_proxy} sean pasadas -a las derivaciones que descargan ficheros. - -Cuando @var{local-build?} es verdadero, declara que la derivación no es una -buena candidata para delegación y debe ser construida localmente -(@pxref{Configuración de delegación del daemon}). Este es el caso para pequeñas derivaciones -donde los costes de transferencia de datos sobrepasarían los beneficios. - -Cuando @var{substitutable?} es falso, declara que las sustituciones de la -salida de la derivación no deben usarse (@pxref{Sustituciones}). Esto es útil, -por ejemplo, cuando se construyen paquetes que capturan detalles sobre el -conjunto de instrucciones de la CPU anfitriona. - -@var{properties} debe ser una lista asociada que describe ``propiedades'' de -la derivación. Debe mantenerse tal cual, sin interpretar, en la derivación. -@end deffn - -@noindent -Esto es un ejemplo con un guión de shell como constructor, asumiendo que -@var{almacén} es una conexión abierta al daemon, @var{bash} apunta al -ejecutable Bash en el almacén: - -@lisp -(use-modules (guix utils) - (guix store) - (guix derivations)) - -(let ((constructor ; añade el guión de Bash al almacén - (add-text-to-store store "mi-constructor.sh" - "echo hola mundo > $out\n" '()))) - (derivation almacen "foo" - bash `("-e" ,builder) - #:inputs `((,bash) (,constructor)) - #:env-vars '(("HOME" . "/sindirectorio")))) -@result{} # /gnu/store/@dots{}-foo> -@end lisp - -Como puede suponerse, el uso directo de esta primitiva es algo -enrevesado. Una mejor aproximación es escribir guiones de construcción en -Scheme, ¡por supuesto! La mejor forma de hacerlo es escribir el código de -construcción como una ``expresión-G'', y pasarla a -@code{gexp->derivation}. Para más información, @pxref{Expresiones-G}. - -En otros tiempos, @code{gexp->derivation} no existía y la creación de -derivaciones con código de construcción escrito en Scheme se conseguía con -@code{build-expression->derivation}, documentada más adelante. Este -procedimiento está ahora obsoleto en favor del procedimiento -@code{gexp->derivation} mucho más conveniente. - -@deffn {Procedimiento Scheme} build-expression->derivation @var{almacén} @ - @var{nombre} @var{exp} @ - [#: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] -Devuelve una derivación que ejecuta la expresión Scheme @var{exp} como un -constructor para la derivación @var{nombre}. @var{inputs} debe ser una lista -de tupletas @code{(nombre ruta-drv sub-drv)}; cuando @var{sub-drv} se omite, -se asume @code{"out"}. @var{modules} es una lista de nombres de módulos -Guile de la ruta actual de búsqueda a copiar en el almacén, compilados, y -poner a disposición en la ruta de carga durante la ejecución de -@var{exp}---por ejemplo, @code{((guix build utils) (guix build -gnu-build-system))}. - -@var{exp} se evalúa en un entorno donde @code{%outputs} está asociada a una -lista de pares salida/ruta, y donde @code{%build-inputs} está asociada a una -lista de pares cadena/ruta-de-salida que provienen de @var{inputs}. De -manera opcional, @var{env-vars} es una lista de pares de cadenas que -especifican el nombre y el valor de las variables de entorno visibles al -constructor. El constructor termina pasando el resultado de @var{exp} a -@code{exit}; por tanto, cuando @var{exp} devuelve @code{#f}, la construcción -se considera fallida. - -@var{exp} se construye usando @var{guile-for-build} (una derivación). Cuando -@var{guile-for-build} se omite o es @code{#f}, el valor del fluido -@code{%guile-for-build} se usa en su lugar. - -Véase el procedimiento @code{derivation} para el significado de -@var{references-graphs}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?} y @var{substitutable?}. -@end deffn - -@noindent -Aquí está un ejemplo de derivación de salida única que crea un directorio -que contiene un fichero: - -@lisp -(let ((constructor '(let ((salida (assoc-ref %outputs "out"))) - (mkdir salida) ; crea /gnu/store/@dots{}-goo - (call-with-output-file (string-append salida "/prueba") - (lambda (p) - (display '(hola guix) p)))))) - (build-expression->derivation almacen "goo" constructor)) - -@result{} # @dots{}> -@end lisp - - -@node La mónada del almacén -@section La mónada del almacén - -@cindex mónada - -Los procedimientos que operan en el almacén descritos en la sección previa -toman todos una conexión abierta al daemon de construcción en su primer -parámetro. Aunque el modelo subyacente es funcional, tienen o bien efectos -secundarios o dependen del estado actual del almacén. - -Lo anterior es inconveniente: la conexión al daemon de construcción tiene -que proporcionarse en todas estas funciones, haciendo imposible la -composición de funciones que no toman ese parámetro con funciones que sí lo -hacen. Lo último puede ser problemático: ya que las operaciones del almacén -tienen efectos secundarios y/o dependen del estado externo, deben ser -secuenciadas de manera adecuada. - -@cindex valores monádicos -@cindex funciones monádicas -Aquí es donde entra en juego el módulo @code{(guix monads)}. Este módulo -proporciona un entorno para trabajar con @dfn{mónadas}, y una mónada -particularmente útil para nuestros usos, la @dfn{mónada del almacén}. Las -mónadas son una construcción que permite dos cosas: asociar ``contexto'' con -valores (en nuestro caso, el contexto es el almacén), y la construcción de -secuencias de computaciones (aquí computaciones incluye accesos al -almacén). Los valores en una mónada---valores que transportan este contexto -adicional---se llaman @dfn{valores monádicos}; los procedimientos que -devuelven dichos valores se llaman @dfn{procedimientos monádicos}. - -Considere este procedimiento ``normal'': - -@example -(define (enlace-sh almacen) - ;; Devuelve una derivación que enlaza el ejecutable 'bash'. - (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 - -Mediante el uso de @code{(guix monads)} y @code{(guix gexp)}, puede -reescribirse como una función monádica: - -@example -(define (enlace-sh) - ;; Lo mismo, pero devuelve un valor monádico. - (mlet %store-monad ((drv (package->derivation bash))) - (gexp->derivation "sh" - #~(symlink (string-append #$drv "/bin/bash") - #$output)))) -@end example - -Hay varias cosas a tener en cuenta en la segunda versión: el parámetro -@code{store} ahora es implícito y es ``hilado en las llamadas a los -procedimientos monádicos @code{package->derivation} y -@code{gexp->derivation}, y el valor monádico devuelto por -@code{package->derivation} es @dfn{asociado} mediante el uso de @code{mlet} -en vez de un simple @code{let}. - -Al final, la llamada a @code{package->derivation} puede omitirse ya que -tendrá lugar implícitamente, como veremos más adelante -(@pxref{Expresiones-G}): - -@example -(define (enlace-sh) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c -@c for the funny quote. -La ejecución del procedimiento monádico @code{enlace-para-sh} no tiene -ningún efecto. Como alguien dijo una vez, ``sales de una mónada como sales -de un edificio en llamas: corriendo'' (run en inglés). Por tanto, para salir -de la mónada y obtener el efecto deseado se debe usar @code{run-with-store}: - -@example -(run-with-store (open-connection) (enlace-sh)) -@result{} /gnu/store/...-enlace-para-sh -@end example - -Fíjese que el módulo @code{(guix monad-repl)} extiende la sesión interactiva -de Guile con nuevos ``meta-comandos'' para facilitar el trabajo con -procedimientos monádicos: @code{run-in-store} y @code{enter-store-monad}. El -primero se usa para ``ejecutar'' un valor monádico único a través del -almacén: - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = # @dots{}> -@end example - -El último entra en un entorno interactivo recursivo, donde todos los valores -devueltos se ejecutan automáticamente a través del almacén: - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = # @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Fijese que los valores no-monádicos no pueden devolverse en el entorno -interactivo @code{store-monad}. - -Las formas sintácticas principales para tratar con mónadas en general se -proporcionan por el módulo @code{(guix monads)} y se describen a -continuación. - -@deffn {Sintaxis Scheme} with-monad @var{mónada} @var{cuerpo} ... -Evalua cualquier forma @code{>>=} o @code{return} en @var{cuerpo} como -estando en @var{mónada}. -@end deffn - -@deffn {Sintaxis Scheme} return @var{val} -Devuelve el valor monádico que encapsula @var{val}. -@end deffn - -@deffn {Sintaxis Scheme} >>= @var{mval} @var{mproc} ... -@dfn{Asocia} el valor monádico @var{mval}, pasando su ``contenido'' a los -procedimientos monádicos @var{mproc}@dots{}@footnote{Esta operación es -habitualmente conocida como ``bind'' (asociación), pero ese nombre denota un -procedimiento no relacionado en Guile. Por tanto usamos este símbolo en -cierto modo críptico heredado del lenguaje Haskell.}. Puede haber un -@var{mproc} o varios, como en este ejemplo: - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'un-estado) - -@result{} 4 -@result{} un-estado -@end example -@end deffn - -@deffn {Sintaxis Scheme} mlet @var{mónada} ((@var{var} @var{mval}) ...) @ - @var{cuerpo} ... -@deffnx {Sintaxis Scheme} mlet* @var{mónada} ((@var{var} @var{mval}) ...) @ - @var{cuerpo} ... Asocia las variables @var{var} a los valores monádicos -@var{mval} en @var{cuerpo}, el cual es una secuencia de expresiones. Como -con el operador bind, esto puede pensarse como el ``desempaquetado'' del -valor crudo no-monádico dentro del ámbito del @var{cuerpo}. La forma -(@var{var} -> @var{val}) asocia @var{var} al valor ``normal'' @var{val}, -como en @code{let}. Las operaciones de asociación ocurren en secuencia de -izquierda a derecha. La última expresión de @var{cuerpo} debe ser una -expresión monádica, y su resultado se convertirá en el resultado de -@code{mlet} o @code{mlet*} cuando se ejecute en la @var{mónada}. - -@code{mlet*} es a @code{mlet} lo que @code{let*} es a @code{let} -(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn - -@deffn {Sistema Scheme} mbegin @var{mónada} @var{mexp} ... -Asocia @var{mexp} y las siguientes expresiones monádicas en secuencia, -devolviendo el resultado de la última expresión. Cada expresión en la -secuencia debe ser una expresión monádica. - -Esto es similar a @code{mlet}, excepto que los valores devueltos por las -expresiones monádicas se ignoran. En ese sentido el funcionamiento es -análogo a @code{begin} pero aplicado a expresiones monádicas. -@end deffn - -@deffn {Sistema Scheme} mwhen @var{condición} @var{mexp0} @var{mexp*} ... -Cuando @var{condición} es verdadero, evalúa la secuencia de expresiones -monádicas @var{mexp0}..@var{mexp*} como dentro de @code{mbegin}. Cuando -@var{condición} es falso, devuelve @code{*unespecified*} en la mónada -actual. Todas las expresiones en la secuencia deben ser expresiones -monádicas. -@end deffn - -@deffn {Sistema Scheme} munless @var{condición} @var{mexp0} @var{mexp*} ... -Cuando @var{condición} es falso, evalúa la secuencia de expresiones -monádicas @var{mexp0}..@var{mexp*} como dentro de @code{mbegin}. Cuando -@var{condición} es verdadero, devuelve @code{*unespecified*} en la mónada -actual. Todas las expresiones en la secuencia deben ser expresiones -monádicas. -@end deffn - -@cindex mónada de estado -El módulo @code{(guix monads)} proporciona la @dfn{mónada de estado}, que -permite que un valor adicional---el estado---sea @emph{hilado} a través de -las llamadas a procedimientos monádicos. - -@defvr {Variable Scheme} %state-monad -La mónada de estado. Procedimientos en la mónada de estado pueden acceder y -cambiar el estado hilado. - -Considere el siguiente ejemplo. El procedimiento @code{cuadrado} devuelve un -valor en la mónada de estado. - -@example -(define (cuadrado x) - (mlet %state-monad ((count (current-state))) - (mbegin %state-monad - (set-current-state (+ 1 count)) - (return (* x x))))) - -(run-with-state (sequence %state-monad (map cuadrado (iota 3))) 0) -@result{} (0 1 4) -@result{} 3 -@end example - -Cuando se ``ejecuta'' a través de @var{%state-monad}, obtenemos un valor -adicional de estado, que ese el número de llamadas a @code{cuadrado}. -@end defvr - -@deffn {Procedimiento monádico} current-state -Devuelve el estado actual como un valor monádico. -@end deffn - -@deffn {Procedimiento monádico} set-current-state @var{valor} -Establece el estado actual a @var{valor} y devuelve el estado previo como un -valor monádico. -@end deffn - -@deffn {Procedimiento monádico} state-push @var{valor} -Apila @var{valor} al estado actual, que se asume que es una lista, y -devuelve el estado previo como un valor monádico. -@end deffn - -@deffn {Procedimiento monádico} state-pop -Desapila un valor del estado actual y lo devuelve como un valor monádico. El -estado se asume que es una lista. -@end deffn - -@deffn {Procedimiento Scheme} run-with-state @var{mval} [@var{estado}] -Ejecuta un valor monádico @var{mval} comenzando con @var{estado} como el -estado inicial. Devuelve dos valores: el valor resultante y el estado -resultante. -@end deffn - -La interfaz principal a la mónada del almacén, proporcionada por el módulo -@code{(guix store)}, es como sigue. - -@defvr {Variable Scheme} %store-monad -La mónada del almacén---un alias para @var{%state-monad}. - -Los valores en la mónada del almacén encapsulan los accesos al -almacén. Cuando su efecto es necesario, un valor de la mónada del almacén -será ``evaluado'' pasandolo al procedimiento @code{run-with-store} (vea más -adelante). -@end defvr - -@deffn {Procedimiento Scheme} run-with-store @var{almacén} @var{mval} [#:guile-for-build] [#:system (%current-system)] -Ejecuta @var{mval}, un valor monádico en la mónada del almacén, en -@var{almacén}, una conexión abierta al almacén. -@end deffn - -@deffn {Procedimiento monádico} text-file @var{nombre} @var{texto} [@var{referencias}] -Devuelve como un valor monádico el nombre absoluto del fichero en el almacén -del fichero que contiene @var{ŧexto}, una cadena. @var{referencias} es una -lista de elementos del almacén a los que el fichero de texto referencia; su -valor predeterminado es la lista vacía. -@end deffn - -@deffn {Procedimiento monádico} binary-file @var{nombre} @var{datos} [@var{referencias}] -Devuelve como un valor monádico el nombre absoluto del fichero en el almacén -del fichero que contiene @var{datos}, un vector de bytes. @var{referencias} -es una lista de elementos del almacén a los que el fichero binario -referencia; su valor predeterminado es la lista vacía. -@end deffn - -@deffn {Procedimiento monádico} interned-file @var{fichero} [@var{nombre}] @ - [#:recursive? #t] [#:select? (const #t)] -Devuelve el nombre del @var{fichero} una vez internado en el almacén. Usa -@var{nombre} como su nombre del almacén, o el nombre base de @var{fichero} -si @var{nombre} se omite. - -Cuando @var{recursive?} es verdadero, los contenidos del @var{fichero} se -añaden recursivamente; si @var{fichero} designa un fichero plano y -@var{recursive?} es verdadero, sus contenidos se añaden, y sus bits de -permisos se mantienen. - -Cuando @var{recursive?} es verdadero, llama a @code{(@var{select?} -@var{fichero} @var{stat})} por cada entrada del directorio, donde -@var{fichero} es el nombre absoluto de fichero de la entrada y @var{stat} es -el resultado de @code{lstat}; excluyendo las entradas para las cuales -@var{select?} no devuelve verdadero. - -El ejemplo siguiente añade un fichero al almacén, bajo dos nombres -diferentes: - -@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 - -El módulo @code{(guix packages)} exporta los siguientes procedimientos -monádicos relacionados con paquetes: - -@deffn {Procedimiento monádico} package-file @var{paquete} [@var{fichero}] @ - [#:system (%current-system)] [#:target #f] @ - [#:output "out"] -Devuelve como un valor monádico el nombre absoluto de fichero de -@var{fichero} dentro del directorio de salida @var{output} del -@var{paquete}. Cuando se omite @var{fichero}, devuelve el nombre del -directorio de salida @var{output} del @var{paquete}. Cuando @var{target} es -verdadero, se usa como una tripleta de compilación cruzada. -@end deffn - -@deffn {Procedimiento monádico} package->derivation @var{paquete} [@var{sistema}] -@deffnx {Procedimiento monádico} package->cross-derivation @var{paquete} @ - @var{objetivo} [@var{sistema}] -Versión monádica de @code{package-derivation} y -@code{package-cross-derivation} (@pxref{Definición de paquetes}). -@end deffn - - -@node Expresiones-G -@section Expresiones-G - -@cindex expresión-G -@cindex escape de código de construcción -Por tanto tenemos ``derivaciones'', que representan una secuencia de -acciones de construcción a realizar para producir un elemento en el almacén -(@pxref{Derivaciones}). Estas acciones de construcción se llevan a cabo -cuando se solicita al daemon construir realmente la derivación; se ejecutan -por el daemon en un contenedor (@pxref{Invocación de guix-daemon}). - -@cindex estratos de código -No debería ser ninguna sorpresa que nos guste escribir estas acciones de -construcción en Scheme. Cuando lo hacemos, terminamos con dos @dfn{estratos} -de código Scheme@footnote{El término @dfn{estrato} en este contexto se debe -a Manuel Serrano et al.@: en el contexto de su trabajo en Hop. Oleg -Kiselyov, quien ha escrito profundos -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, ensayos sobre el -tema}, se refiere a este tipo de generación de código como separación en -etapas o @dfn{staging}.}: el ``código anfitrión''---código que define -paquetes, habla al daemon, etc.---y el ``código de construcción''---código -que realmente realiza las acciones de construcción, como la creación de -directorios, la invocación de @command{make}, etc. - -Para describir una derivación y sus acciones de construcción, típicamente se -necesita embeber código de construcción dentro del código anfitrión. Se -resume en la manipulación de código de construcción como datos, y la -homoiconicidad de Scheme---el código tiene representación directa como -datos---es útil para ello. Pero necesitamos más que el mecanismo normal de -@code{quasiquote} en Scheme para construir expresiones de construcción. - -El módulo @code{(guix gexp)} implementa las @dfn{expresiones-G}, una forma -de expresiones-S adaptada para expresiones de construcción. Las -expresiones-G, o @dfn{gexps}, consiste esencialmente en tres formas -sintácticas: @code{gexp}, @code{ungexp} y @code{ungexp-splicing} (o -simplemente: @code{#~}, @code{#$} y @code{#$@@}), que son comparables a -@code{quasiquote}, @code{unquote} y @code{unquote-splicing}, respectivamente -(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile Reference -Manual}). No obstante, hay importantes diferencias: - -@itemize -@item -Las expresiones-G están destinadas a escribirse en un fichero y ser -ejecutadas o manipuladas por otros procesos. - -@item -Cuando un objeto de alto nivel como un paquete o una derivación se expande -dentro de una expresión-G, el resultado es el mismo que la introducción de -su nombre de fichero de salida. - -@item -Las expresiones-G transportan información acerca de los paquetes o -derivaciones que referencian, y estas referencias se añaden automáticamente -como entradas al proceso de construcción que las usa. -@end itemize - -@cindex bajada de nivel, de objetos de alto nivel en expresiones-G -Este mecanismo no se limita a objetos de paquete ni derivación: pueden -definirse @dfn{compiladores} capaces de ``bajar el nivel'' de otros objetos -de alto nivel a derivaciones o ficheros en el almacén, de modo que esos -objetos puedan introducirse también en expresiones-G. Por ejemplo, un tipo -útil de objetos de alto nivel que pueden insertarse en una expresión-G son -los ``objetos tipo-fichero'', los cuales facilitan la adición de ficheros al -almacén y su referencia en derivaciones y demás (vea @code{local-file} y -@code{plain-file} más adelante). - -Para ilustrar la idea, aquí está un ejemplo de expresión-G: - -@example -(define exp-construccion - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "enumera-ficheros"))) -@end example - -Esta expresión-G puede pasarse a @code{gexp->derivation}; obtenemos una -derivación que construye un directorio que contiene exactamente un enlace -simbólico a @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: - -@example -(gexp->derivation "la-cosa" exp-construccion) -@end example - -Como se puede esperar, la cadena @code{"/gnu/store/@dots{}-coreutils-8.22"} -se sustituye por la referencia al paquete @var{coreutils} en el código de -construcción real, y @var{coreutils} se marca automáticamente como una -entrada a la derivación. Del mismo modo, @code{#$output} (equivalente a -@code{(ungexp output)}) se reemplaza por una cadena que contiene el nombre -del directorio de la salida de la derivación. - -@cindex compilación cruzada -En un contexto de compilación cruzada, es útil distinguir entre referencias -a construcciones @emph{nativas} del paquete---que pueden ejecutarse en el -sistema anfitrión---de referencias de compilaciones cruzadas de un -paquete. Para dicho fin, @code{#+} tiene el mismo papel que @code{#$}, pero -es una referencia a una construcción nativa del paquete: - -@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 -En el ejemplo previo, se usa la construcción nativa de @var{coreutils}, de -modo que @command{ln} pueda realmente ejecutarse en el anfitrión; pero se -hace referencia a la construcción de compilación cruzada de @var{emacs}. - -@cindex módulos importados, para expresiones-G -@findex with-imported-modules -Otra característica de las expresiones-G son los @dfn{módulos importados}: a -veces deseará ser capaz de usar determinados módulos Guile del ``entorno -anfitrión'' en la expresión-G, de modo que esos módulos deban ser importados -en el ``entorno de construcción''. La forma @code{with-imported-modules} le -permite expresarlo: - -@example -(let ((build (with-imported-modules '((guix build utils)) - #~(begin - (use-modules (guix build utils)) - (mkdir-p (string-append #$output "/bin")))))) - (gexp->derivation "directorio-vacio" - #~(begin - #$build - (display "éxito!\n") - #t))) -@end example - -@noindent -En este ejemplo, el módulo @code{(guix build utils)} se incorpora -automáticamente dentro del entorno de construcción aislado de nuestra -expresión-G, de modo que @code{(use-modules (guix build utils))} funciona -como se espera. - -@cindex clausura de módulos -@findex source-module-closure -De manera habitual deseará que la @emph{clausura} del módulo se importe---es -decir, el módulo en sí y todos los módulos de los que depende---en vez del -módulo únicamente; si no se hace, cualquier intento de uso del módulo -fallará porque faltan módulos dependientes. El procedimiento -@code{source-module-closure} computa la clausura de un módulo mirando en las -cabeceras de sus ficheros de fuentes, lo que es útil en este caso: - -@example -(use-modules (guix modules)) ;para 'source-module-closure' - -(with-imported-modules (source-module-closure - '((guix build utils) - (gnu build vm))) - (gexp->derivation "algo-con-maq-virtuales" - #~(begin - (use-modules (guix build utils) - (gnu build vm)) - @dots{}))) -@end example - -@cindex extensiones, para expresiones G -@findex with-extensions -De la misma manera, a veces deseará importar no únicamente módulos puros de -Scheme, pero también ``extensiones'' como enlaces Guile a bibliotecas C u -otros paquetes ``completos''. Si, digamos, necesitase el paquete -@code{guile-json} disponible en el lado de construcción, esta sería la forma -de hacerlo: - -@example -(use-modules (gnu packages guile)) ;para 'guile-json' - -(with-extensions (list guile-json) - (gexp->derivation "algo-con-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -La forma sintáctica para construir expresiones-G se resume a continuación. - -@deffn {Sintaxis Scheme} #~@var{exp} -@deffnx {Sintaxis Scheme} (gexp @var{exp}) -Devuelve una expresión-G que contiene @var{exp}. @var{exp} puede contener -una o más de las siguientes formas: - -@table @code -@item #$@var{obj} -@itemx (ungexp @var{obj}) -Introduce una referencia a @var{obj}. @var{obj} puede tener uno de los tipos -permitidos, por ejemplo un paquete o derivación, en cuyo caso la forma -@code{ungexp} se substituye por el nombre de fichero de su salida---por -ejemplo, @code{"/gnu/store/@dots{}-coreutils-8.22}. - -Si @var{obj} es una lista, se recorre y las referencias a objetos permitidos -se substituyen de manera similar. - -Si @var{obj} es otra expresión-G, su contenido se inserta y sus dependencias -se añaden a aquellas de la expresión-G que la contiene. - -Si @var{obj} es otro tipo de objeto, se inserta tal cual es. - -@item #$@var{obj}:@var{salida} -@itemx (ungexp @var{obj} @var{salida}) -Como la forma previa, pero referenciando explícitamente la @var{salida} de -@var{obj}---esto es útil cuando @var{obj} produce múltiples salidas -(@pxref{Paquetes con múltiples salidas}). - -@item #+@var{obj} -@itemx #+@var{obj}:salida -@itemx (ungexp-native @var{obj}) -@itemx (ungexp-native @var{obj} @var{salida}) -Lo mismo que @code{ungexp}, pero produce una referencia a la construcción -@emph{nativa} de @var{obj} cuando se usa en un contexto de compilación -cruzada. - -@item #$output[:@var{salida}] -@itemx (ungexp output [@var{salida}]) -Inserta una referencia a la salida de la derivación @var{salida}, o a la -salida principal cuando @var{salida} se omite. - -Esto únicamente tiene sentido para expresiones-G pasadas a -@code{gexp->derivation}. - -@item #$@@@var{lst} -@itemx (ungexp-splicing @var{lst}) -Lo mismo que la forma previa, pero expande el contenido de la lista -@var{lst} como parte de la lista que la contiene. - -@item #+@@@var{lst} -@itemx (ungexp-native-splicing @var{lst}) -Lo mismo que la forma previa, pero hace referencia a las construcciones -nativas de los objetos listados en @var{lst}. - -@end table - -Las expresiones-G creadas por @code{gexp} o @code{#~} son objetos del tipo -@code{gexp?} en tiempo de ejecución (vea más adelante). -@end deffn - -@deffn {Sintaxis Scheme} with-imported-modules @var{módulos} @var{cuerpo}@dots{} -Marca las expresiones-G definidas en el @var{cuerpo}@dots{} como si -requiriesen @var{módulos} en su entorno de ejecución. - -Cada elemento en @var{módulos} puede ser el nombre de un módulo, como -@code{(guix build utils)}, o puede ser el nombre de un módulo, seguido de -una flecha, seguido de un objeto tipo-fichero: - -@example -`((guix build utils) - (guix gcrypt) - ((guix config) => ,(scheme-file "config.scm" - #~(define-module @dots{})))) -@end example - -@noindent -En el ejemplo previo, los dos primeros módulos se toman de la ruta de -búsqueda, y el último se crea desde el objeto tipo-fichero proporcionado. - -Esta forma tiene ámbito @emph{léxico}: tiene efecto en las expresiones-G -definidas en @var{cuerpo}@dots{}, pero no en aquellas definidas, digamos, en -procedimientos llamados por @var{cuerpo}@dots{}. -@end deffn - -@deffn {Sintaxis Scheme} with-extensions @var{extensiones} @var{cuerpo}@dots{} -Marca que las expresiones definidas en @var{cuerpo}@dots{} requieren -@var{extensiones} en su entorno de construcción y -ejecución. @var{extensiones} es típicamente una lista de objetos de paquetes -como los que se definen en el módulo @code{(gnu packages guile)}. - -De manera concreta, los paquetes listados en @var{extensiones} se añaden a -la ruta de carga mientras se compilan los módulos importados en -@var{cuerpo}@dots{}; también se añaden a la ruta de carga en la expresión-G -devuelta por @var{cuerpo}@dots{}. -@end deffn - -@deffn {Procedimiento Scheme} gexp? @var{obj} -Devuelve @code{#t} si @var{obj} es una expresión-G. -@end deffn - -Las expresiones-G están destinadas a escribirse en disco, tanto en código -que construye alguna derivación, como en ficheros planos en el almacén. Los -procedimientos monádicos siguientes le permiten hacerlo (@pxref{La mónada del almacén}, para más información sobre mónadas). - -@deffn {Procedimiento monádico} gexp->derivation @var{nombre} @var{exp} @ - [#: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] -Devuelve una derivación @var{nombre} que ejecuta @var{exp} (una expresión-G) -con @var{guile-for-build} (una derivación) en el sistema @var{system}; -@var{exp} se almacena en un fichero llamado @var{script-name}. Cuando -@var{target} es verdadero, se usa como la tripleta de compilación cruzada -para paquetes a los que haga referencia @var{exp}. - -@var{modules} está obsoleto en favor de @code{with-imported-modules}. Su -significado es hacer que los módulos @var{modules} estén disponibles en el -contexto de evaluación de @var{exp}; @var{modules} es una lista de nombres -de módulos Guile buscados en @var{module-path} para ser copiados al almacén, -compilados y disponibles en la ruta de carga durante la ejecución de -@var{exp}---por ejemplo, @code{((guix build utils) (gui build -gnu-build-system))}. - -@var{effective-version} determina la cadena a usar cuando se añaden las -extensiones de @var{exp} (vea @code{with-extensions}) a la ruta de -búsqueda---por ejemplo, @code{"2.2"}. - -@var{graft?} determina si los paquetes a los que @var{exp} hace referencia -deben ser injertados cuando sea posible. - -Cuando @var{references-graphs} es verdadero, debe ser una lista de tuplas de -una de las formas siguientes: - -@example -(@var{nombre-fichero} @var{paquete}) -(@var{nombre-fichero} @var{paquete} @var{salida}) -(@var{nombre-fichero} @var{derivación}) -(@var{nombre-fichero} @var{derivación} @var{salida}) -(@var{nombre-fichero} @var{elemento-almacén}) -@end example - -El lado derecho de cada elemento de @var{references-graphs} se convierte -automáticamente en una entrada del proceso de construcción de @var{exp}. En -el entorno de construcción, cada @var{nombre-fichero} contiene el grafo de -referencias del elemento correspondiente, en un formato de texto simple. - -@var{allowed-references} debe ser o bien @code{#f} o una lista de nombres y -paquetes de salida. En el último caso, la lista denota elementos del almacén -a los que el resultado puede hacer referencia. Cualquier referencia a otro -elemento del almacén produce un error de construcción. De igual manera con -@var{disallowed-references}, que enumera elementos a los que las salidas no -deben hacer referencia. - -@var{deprecation-warnings} determina si mostrar avisos de obsolescencia -durante la compilación de los módulos. Puede ser @code{#f}, @code{#t} o -@code{'detailed}. - -El resto de parámetros funcionan como en @code{derivation} -(@pxref{Derivaciones}). -@end deffn - -@cindex objetos tipo-fichero -Los procedimientos @code{local-file}, @code{plain-file}, -@code{computed-file}, @code{program-file} y @code{scheme-file} a -continuación devuelven @dfn{objetos tipo-fichero}. Esto es, cuando se -expanden en una expresión-G, estos objetos dirigen a un fichero en el -almacén. Considere esta expresión-G: - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/mi-nscd.conf")) -@end example - -El efecto aquí es el ``internamiento'' de @file{/tmp/mi-nscd.conf} mediante -su copia al almacén. Una vez expandida, por ejemplo @i{vía} -@code{gexp->derivation}, la expresión-G hace referencia a la copia bajo -@file{/gnu/store}; por tanto, la modificación o el borrado del fichero en -@file{/tmp} no tiene ningún efecto en lo que la expresión-G -hace. @code{plain-file} puede usarse de manera similar; se diferencia en que -el contenido del fichero se proporciona directamente como una cadena. - -@deffn {Procedimiento Scheme} local-file @var{fichero} [@var{nombre}] @ - [#:recursive? #f] [#:select? (const #t)] -Devuelve un objeto que representa el fichero local @var{fichero} a añadir al -almacén; este objeto puede usarse en una expresión-G. Si @var{fichero} es un -nombre de fichero relativo, se busca de forma relativa al fichero fuente -donde esta forma aparece. @var{fichero} se añadirá al almacén bajo -@var{nombre}---por defecto el nombre base de @var{fichero}. - -Cuando @var{recursive?} es verdadero, los contenidos del @var{fichero} se -añaden recursivamente; si @var{fichero} designa un fichero plano y -@var{recursive?} es verdadero, sus contenidos se añaden, y sus bits de -permisos se mantienen. - -Cuando @var{recursive?} es verdadero, llama a @code{(@var{select?} -@var{fichero} @var{stat})} por cada entrada del directorio, donde -@var{fichero} es el nombre absoluto de fichero de la entrada y @var{stat} es -el resultado de @code{lstat}; excluyendo las entradas para las cuales -@var{select?} no devuelve verdadero. - -Esta es la contraparte declarativa del procedimiento monádico -@code{interned-file} (@pxref{La mónada del almacén, @code{interned-file}}). -@end deffn - -@deffn {Procedimiento Scheme} plain-file @var{nombre} @var{contenido} -Devuelve un objeto que representa un fichero de texto llamado @var{nombre} -con el @var{contenido} proporcionado (una cadena o un vector de bytes) para -ser añadido al almacén. - -Esta es la contraparte declarativa de @code{text-file}. -@end deffn - -@deffn {Procedimiento Scheme} computed-file @var{nombre} @var{gexp} @ - [#:options '(#:local-build? #t)] -Devuelve un objeto que representa el elemento del almacén @var{nombre}, un -fichero o un directorio computado por @var{gexp}. @var{options} es una lista -de parámetros adicionales a pasar a @code{gexp->derivation}. - -Esta es la contraparte declarativa de @code{gexp->derivation}. -@end deffn - -@deffn {Procedimiento monádico} gexp->script @var{nombre} @var{exp} @ - [#:guile (default-guile)] [#:module-path %load-path] -Devuelve un guión ejecutable @var{nombre} que ejecuta @var{exp} usando -@var{guile}, con los módulos importados por @var{exp} en su ruta de -búsqueda. Busca los módulos de @var{exp} en @var{module-path}. - -El ejemplo siguiente construye un guión que simplemente invoca la orden -@command{ls}: - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "enumera-ficheros" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -Cuando se ejecuta a través del almacén (@pxref{La mónada del almacén, -@code{run-with-store}}), obtenemos una derivación que produce un fichero -ejecutable @file{/gnu/store/@dots{}-enumera-ficheros} más o menos así: - -@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 {Procedimiento Scheme} program-file @var{nombre} @var{exp} @ - [#:guile #f] [#:module-path %load-path] -Devuelve un objeto que representa el elemento ejecutable del almacén -@var{nombre} que ejecuta @var{gexp}. @var{guile} es el paquete Guile usado -para ejecutar el guión. Los módulos importados por @var{gexp} se buscan en -@var{module-path}. - -Esta es la contraparte declarativa de @code{gexp->script}. -@end deffn - -@deffn {Procedimiento monádico} gexp->file @var{nombre} @var{exp} @ - [#:set-load-path? #t] [#:module-path %load-path] @ - [#:splice? #f] @ - [#:guile (default-guile)] -Devuelve una derivación que construye un fichero @var{nombre} que contiene -@var{exp}. Cuando @var{splice?} es verdadero, se considera que @var{exp} es -una lista de expresiones que deben ser expandidas en el fichero resultante. - -Cuando @var{set-load-path} es verdadero, emite código en el fichero -resultante para establecer @code{%load-path} y @code{%load-compiled-path} de -manera que respeten los módulos importados por @var{exp}. Busca los módulos -de @var{exp} en @var{module-path}. - -El fichero resultante hace referencia a todas las dependencias de @var{exp} -o a un subconjunto de ellas. -@end deffn - -@deffn {Procedimiento Scheme} scheme-file @var{nombre} @var{exp} [#:splice? #f] -Devuelve un objeto que representa el fichero Scheme @var{nombre} que -contiene @var{exp}. - -Esta es la contraparte declarativa de @code{gexp->file}. -@end deffn - -@deffn {Procedimiento monádico} text-file* @var{nombre} @var{texto} @dots{} -Devuelve como un valor monádico una derivación que construye un fichero de -texto que contiene todo @var{texto}. @var{texto} puede ser una lista de, -además de cadenas, objetos de cualquier tipo que pueda ser usado en -expresiones-G: paquetes, derivaciones, ficheros locales, objetos, etc. El -fichero del almacén resultante hace referencia a todos ellos. - -Esta variante debe preferirse sobre @code{text-file} cuando el fichero a -crear haga referencia a elementos del almacén. Esto es el caso típico cuando -se construye un fichero de configuración que embebe nombres de ficheros del -almacén, como este: - -@example -(define (perfil.sh) - ;; Devuelve el nombre de un guión shell en el almacén - ;; que establece la variable de entorno 'PATH' - (text-file* "perfil.sh" - "export PATH=" coreutils "/bin:" - grep "/bin:" sed "/bin\n")) -@end example - -En este ejemplo, el fichero @file{/gnu/store/@dots{}-perfil.sh} resultante -hará referencia a @var{coreutils}, @var{grep} y @var{sed}, por tanto -evitando que se recolecten como basura durante su tiempo de vida. -@end deffn - -@deffn {Procedimiento Scheme} mixed-text-file @var{nombre} @var{texto} @dots{} -Devuelve un objeto que representa el fichero del almacén @var{nombre} que -contiene @var{texto}. @var{texto} es una secuencia de cadenas y objetos -tipo-fichero, como en: - -@example -(mixed-text-file "perfil" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -Esta es la contraparte declarativa de @code{text-file*}. -@end deffn - -@deffn {Procedimiento Scheme} file-union @var{nombre} @var{ficheros} -Devuelve un @code{} que construye un directorio que contiene -todos los @var{ficheros}. Cada elemento en @var{ficheros} debe ser una lista -de dos elementos donde el primer elemento es el nombre de fichero a usar en -el nuevo directorio y el segundo elemento es una expresión-G que denota el -fichero de destino. Aquí está un ejemplo: - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -Esto emite un directorio @code{etc} que contiene estos dos ficheros. -@end deffn - -@deffn {Procedimiento Scheme} directory-union @var{nombre} @var{cosas} -Devuelve un directorio que es la unión de @var{cosas}, donde @var{cosas} es -una lista de objetos tipo-fichero que denotan directorios. Por ejemplo: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -emite un directorio que es la unión de los paquetes @code{guile} y -@code{emacs}. -@end deffn - -@deffn {Procedimientos Scheme} file-append @var{obj} @var{sufijo} @dots{} -Devuelve un objeto tipo-fichero que se expande a la concatenación de -@var{obj} y @var{sufijo}, donde @var{obj} es un objeto que se puede bajar de -nivel y cada @var{sufijo} es una cadena. - -Como un ejemplo, considere esta expresión-G: - -@example -(gexp->script "ejecuta-uname" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -El mismo efecto podría conseguirse con: - -@example -(gexp->script "ejecuta-uname" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -Hay una diferencia no obstante: en el caso de @code{file-append}, el guión -resultante contiene una ruta absoluta de fichero como una cadena, mientras -que en el segundo caso, el guión resultante contiene una expresión -@code{(string-append @dots{})} para construir el nombre de fichero @emph{en -tiempo de ejecución}. -@end deffn - - -Por supuesto, además de expresiones-G embebidas en código ``anfitrión'', hay -también módulos que contienen herramientas de construcción. Para clarificar -que están destinados para su uso en el estrato de construcción, estos -módulos se mantienen en el espacio de nombres @code{(guix build @dots{})}. - -@cindex bajada de nivel, de objetos de alto nivel en expresiones-G -Internamente, los objetos de alto nivel se @dfn{bajan de nivel}, usando su -compilador, a derivaciones o elementos del almacén. Por ejemplo, bajar de -nivel un paquete emite una derivación, y bajar de nivel un @var{plain-file} -emite un elemento del almacén. Esto se consigue usando el procedimiento -monádico @code{lower-object}. - -@deffn {Procedimiento monádico} lower-object @var{obj} [@var{sistema}] @ - [#:target #f] -Devuelve como un valor en @var{%store-monad} la derivación o elemento del -almacén que corresponde a @var{obj} en @var{sistema}, compilando de manera -cruzada para @var{target} si @var{target} es verdadero. @var{obj} debe ser -un objeto que tiene asociado un compilador de expresiones-G, como -@code{}. -@end deffn - -@node Invocación de guix repl -@section Invocación de @command{guix repl} - -@cindex REPL, bucle de lectura-evaluación-impresión -La orden @command{guix repl} lanza un @dfn{bucle de -lectura-evaluación-impresión} Guile (REPL) para programación interactiva -(@pxref{Using Guile Interactively,,, guile, GNU Guile Reference -Manual}). Comparado a simplemente lanzar la orden @command{guile}, -@command{guix repl} garantiza que todos los módulos Guix y todas sus -dependencias están disponibles en la ruta de búsqueda. Puede usarla de esta -manera: - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = # -@end example - -@cindex inferiores -Además, @command{guix repl} implementa un protocolo del REPL simple legible -por máquinas para su uso por @code{(guix inferior)}, una facilidad para -interactuar con @dfn{inferiores}, procesos separados que ejecutan una -revisión de Guix potencialmente distinta. - -Las opciones disponibles son las siguientes: - -@table @code -@item --type=@var{tipo} -@itemx -t @var{tipo} -Inicia un REPL del @var{TIPO} dado, que puede ser uno de los siguientes: - -@table @code -@item guile -Es el predeterminado, y lanza una sesión interactiva Guile estándar con -todas las características. -@item machine -Lanza un REPL que usa el protocolo legible por máquinas. Este es el -protocolo con el que el módulo @code{(guix inferior)} se comunica. -@end table - -@item --listen=@var{destino} -Por defecto, @command{guix repl} lee de la entrada estándar y escribe en la -salida estándar. Cuando se pasa esta opción, en vez de eso escuchará las -conexiones en @var{destino}. Estos son ejemplos de opciones válidas: - -@table @code -@item --listen=tcp:37146 -Acepta conexiones locales por el puerto 37146. - -@item --listen=unix:/tmp/socket -Acepta conexiones a través del socket de dominio Unix @file{/tmp/socket}. -@end table -@end table - -@c ********************************************************************* -@node Utilidades -@chapter Utilidades - -Esta sección describe las utilidades de línea de órdenes de Guix. Algunas de -ellas están orientadas principalmente para desarrolladoras y usuarias que -escriban definiciones de paquetes nuevas, mientras que otras son útiles de -manera más general. Complementan la interfaz programática Scheme de Guix de -modo conveniente. - -@menu -* Invocación de guix build:: Construir paquetes desde la línea de - órdenes. -* Invocación de guix edit:: Editar las definiciones de paquetes. -* Invocación de guix download:: Descargar un fichero e imprimir su hash. -* Invocación de guix hash:: Calcular el hash criptográfico de un fichero. -* Invocación de guix import:: Importar definiciones de paquetes. -* Invocación de guix refresh:: Actualizar definiciones de paquetes. -* Invocación de guix lint:: Encontrar errores en definiciones de paquetes. -* Invocación de guix size:: Perfilar el uso del disco. -* Invocación de guix graph:: Visualizar el grafo de paquetes. -* Invocación de guix publish:: Compartir sustituciones. -* Invocación de guix challenge:: Poner a prueba servidores de - sustituciones. -* Invocación de guix copy:: Copiar a y desde un almacén remoto. -* Invocación de guix container:: Aislamiento de procesos. -* Invocación de guix weather:: Comprobar la disponibilidad de - sustituciones. -* Invocación de guix processes:: Enumerar los procesos cliente. -@end menu - -@node Invocación de guix build -@section Invocación de @command{guix build} - -@cindex construcción de paquetes -@cindex @command{guix build} -La orden @command{guix build} construye paquetes o derivaciones y sus -dependencias, e imprime las rutas del almacén resultantes. Fíjese que no -modifica el perfil de la usuaria---este es el trabajo de la orden -@command{guix package} (@pxref{Invocación de guix package}). Por tanto, es útil -principalmente para las desarrolladoras de la distribución. - -La sintaxis general es: - -@example -guix build @var{opciones} @var{paquete-o-derivación}@dots{} -@end example - -Como ejemplo, la siguiente orden construye las últimas versiones de Emacs y -Guile, muestra sus log de construcción, y finalmente muestra los directorios -resultantes: - -@example -guix build emacs guile -@end example - -De forma similar, la siguiente orden construye todos los paquetes -disponibles: - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -@var{paquete-o-derivación} puede ser tanto el nombre de un paquete que se -encuentra en la distribución de software como @code{coreutils} o -@code{coreutils@@8.20}, o una derivación como -@file{/gnu/store/@dots{}-coreutils-8.19.drv}. En el primer caso, el paquete -de nombre (y opcionalmente versión) correspondiente se busca entre los -módulos de la distribución GNU (@pxref{Módulos de paquetes}). - -De manera alternativa, la opción @code{--expression} puede ser usada para -especificar una expresión Scheme que evalúa a un paquete; esto es útil para -la desambiguación entre varios paquetes del mismo nombre o si se necesitan -variaciones del paquete. - -Puede haber cero o más @var{opciones}. Las opciones disponibles se describen -en la subsección siguiente. - -@menu -* Opciones comunes de construcción:: Opciones de construcción para la - mayoría de órdenes. -* Opciones de transformación de paquetes:: Crear variantes de paquetes. -* Opciones de construcción adicionales:: Opciones específicas de 'guix - build'. -* Depuración de fallos de construcción:: Experiencia de empaquetamiento - en la vida real. -@end menu - -@node Opciones comunes de construcción -@subsection Opciones comunes de construcción - -Un número de opciones que controlan el proceso de construcción son comunes a -@command{guix build} y otras órdenes que pueden lanzar construcciones, como -@command{guix package} o @command{guix archive}. Son las siguientes: - -@table @code - -@item --load-path=@var{directorio} -@itemx -L @var{directorio} -Añade @var{directorio} al frente de la ruta de búsqueda de módulos de -paquetes (@pxref{Módulos de paquetes}). - -Esto permite a las usuarias definir sus propios paquetes y hacerlos visibles -a las herramientas de línea de órdenes. - -@item --keep-failed -@itemx -K -Mantiene los árboles de construcción de las construcciones fallidas. Por -tanto, si una construcción falla, su árbol de construcción se mantiene bajo -@file{/tmp}, en un directorio cuyo nombre se muestra al final del log de -construcción. Esto es útil cuando se depuran problemas en la -construcción. @xref{Depuración de fallos de construcción}, para trucos y consejos sobre -cómo depurar problemas en la construcción. - -Esta opción no tiene efecto cuando se conecta a un daemon remoto con una URI -@code{guix://} (@pxref{El almacén, the @code{GUIX_DAEMON_SOCKET} variable}). - -@item --keep-going -@itemx -k -Seguir adelante cuando alguna de las derivaciones de un fallo durante la -construcción; devuelve una única vez todas las construcciones que se han -completado o bien han fallado. - -El comportamiento predeterminado es parar tan pronto una de las derivaciones -especificadas falle. - -@item --dry-run -@itemx -n -No construye las derivaciones. - -@anchor{fallback-option} -@item --fallback -Cuando la sustitución de un binario preconstruido falle, intenta la -construcción local de paquetes (@pxref{Fallos en las sustituciones}). - -@item --substitute-urls=@var{urls} -@anchor{client-substitute-urls} -Considera @var{urls} la lista separada por espacios de URLs de fuentes de -sustituciones, anulando la lista predeterminada de URLs de -@command{guix-daemon} (@pxref{daemon-substitute-urls,, @command{guix-daemon -URLs}}). - -Significa que las sustituciones puede ser descargadas de @var{urls}, -mientras que estén firmadas por una clave autorizada por la administradora -del sistema (@pxref{Sustituciones}). - -Cuando @var{urls} es la cadena vacía, las sustituciones están efectivamente -deshabilitadas. - -@item --no-substitutes -No usa sustituciones para la construcción de productos. Esto es, siempre -realiza las construcciones localmente en vez de permitir la descarga de -binarios pre-construidos (@pxref{Sustituciones}). - -@item --no-grafts -No ``injerta'' paquetes. En la práctica esto significa que las -actualizaciones de paquetes disponibles como injertos no se -aplican. @xref{Actualizaciones de seguridad}, para más información sobre los injertos. - -@item --rounds=@var{n} -Construye cada derivación @var{n} veces seguidas, y lanza un error si los -resultados de las construcciones consecutivas no son idénticos bit-a-bit. - -Esto es útil para la detección de procesos de construcción -no-deterministas. Los procesos de construcción no-deterministas son un -problema puesto que prácticamente imposibilitan a las usuarias la -@emph{verificación} de la autenticidad de binarios proporcionados por -terceras partes. @xref{Invocación de guix challenge}, para más sobre esto. - -Fíjese que, actualmente, los resultados de las construcciones discordantes -no se mantienen, por lo que debe que investigar manualmente en caso de un -error---por ejemplo, mediante la extracción de uno de los resultados con -@code{guix archive --export} (@pxref{Invocación de guix archive}), seguida de una -reconstrucción, y finalmente la comparación de los dos resultados. - -@item --no-build-hook -No intenta delegar construcciones a través del ``hook de construcción'' del -daemon (@pxref{Configuración de delegación del daemon}). Es decir, siempre realiza las -construcciones de manera local en vez de delegando construcciones a máquinas -remotas. - -@item --max-silent-time=@var{segundos} -Cuando la construcción o sustitución permanece en silencio más de -@var{segundos}, la finaliza e informa de un fallo de construcción. - -Por defecto, se respeta la configuración del daemon (@pxref{Invocación de guix-daemon, @code{--max-silent-time}}). - -@item --timeout=@var{segundos} -Del mismo modo, cuando el proceso de construcción o sustitución dura más de -@var{segundos}, lo termina e informa un fallo de construcción. - -Por defecto, se respeta la configuración del daemon (@pxref{Invocación de 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 logs de construcción, nivel de descripción -@item -v @var{nivel} -@itemx --verbosity=@var{nivel} -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} -Permite usar @var{n} núcleos de la CPU para la construcción. El valor -especial @code{0} significa usar tantos como núcleos haya en la CPU. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Permite como máximo @var{n} trabajos de construcción en -paralelo. @xref{Invocación de guix-daemon, @code{--max-jobs}}, para detalles -acerca de esta opción y la opción equivalente de @command{guix-daemon}. - -@item --debug=@var{nivel} -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 - -Tras las cortinas, @command{guix build} es esencialmente una interfaz al -procedimiento @code{package-derivation} del módulo @code{(guix packages)}, y -al procedimiento @code{build-derivations} del módulo @code{(guix -derivations)}. - -Además de las opciones proporcionadas explícitamente en la línea de órdenes, -@command{guix build} y otras órdenes @command{guix} que permiten la -construcción respetan el contenido de la variable de entorno -@code{GUIX_BUILD_OPTIONS}. - -@defvr {Variable de entorno} GUIX_BUILD_OPTIONS -Las usuarias pueden definir esta variable para que contenga una lista de -opciones de línea de órdenes que se usarán automáticamente por @command{guix -build} y otras órdenes @command{guix} que puedan realizar construcciones, -como en el ejemplo siguiente: - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -Estas opciones se analizan independientemente, y el resultado se añade a -continuación de las opciones de línea de órdenes. -@end defvr - - -@node Opciones de transformación de paquetes -@subsection Opciones de transformación de paquetes - -@cindex variaciones de paquetes -Otro conjunto de opciones de línea de órdenes permitidas por @command{guix -build} y también @command{guix package} son las @dfn{opciones de -transformación de paquetes}. Son opciones que hacen posible la definición de -@dfn{variaciones de paquetes}---por ejemplo, paquetes construidos con un -código fuente diferente. Es una forma conveniente de crear paquetes -personalizados al vuelo sin tener que escribir las definiciones de las -variaciones del paquete (@pxref{Definición de paquetes}). - -@table @code - -@item --with-source=@var{fuente} -@itemx --with-source=@var{paquete}=@var{fuente} -@itemx --with-source=@var{paquete}@@@var{versión}=@var{fuente} -Usa @var{fuente} como la fuente de @var{paquete}, y @var{versión} como su -número de versión. @var{fuente} debe ser un nombre de fichero o una URL, -como en @command{guix download} (@pxref{Invocación de guix download}). - -Cuando se omite @var{paquete}, se toma el nombre de paquete especificado en -la línea de ordenes que coincide con el nombre base de @var{fuente}---por -ejemplo, si @var{fuente} fuese @code{/src/guile-2.0.10.tar.gz}, el paquete -correspondiente sería @code{guile}. - -Del mismo modo, si se omite @var{versión}, la cadena de versión se deduce de -@var{đuente}; en el ejemplo previo sería @code{2.0.10}. - -Esta opción permite a las usuarias probar versiones del paquete distintas a -las proporcionadas en la distribución. El ejemplo siguiente descarga -@file{ed-1.7.tar.gz} de un espejo GNU y lo usa como la fuente para el -paquete @code{ed}: - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -Como desarrolladora, @code{--with-source} facilita la prueba de versiones -candidatas para la publicación: - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} o la construcción desde una revisión en un entorno limpio: - -@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{paquete}=@var{reemplazo} -Substituye dependencias de @var{paquete} por dependencias de -@var{reemplazo}. @var{paquete} debe ser un nombre de paquete, y -@var{reemplazo} debe ser una especificación de paquete como @code{guile} o -@code{guile@@1.8}. - -Por ejemplo, la orden siguiente construye Guix, pero substituye su -dependencia de la versión estable actual de Guile con una dependencia en la -versión antigua de Guile, @code{guile@@2.0}: - -@example -guix build --with-input=guile=guile@@2.0 guix -@end example - -Esta sustitución se realiza de forma recursiva y en profundidad. Por lo que -en este ejemplo, tanto @code{guix} como su dependencia @code{guile-json} -(que también depende de @code{guile}) se reconstruyen contra -@code{guile@@2.0}. - -Se implementa usando el procedimiento Scheme @code{package-input-rewriting} -(@pxref{Definición de paquetes, @code{package-input-rewriting}}). - -@item --with-graft=@var{paquete}=@var{reemplazo} -Es similar a @code{--with-input} pero con una diferencia importante: en vez -de reconstruir la cadena de dependencias completa, @var{reemplazo} se -construye y se @dfn{injerta} en los binarios que inicialmente hacían -referencia a @var{paquete}. @xref{Actualizaciones de seguridad}, para más información -sobre injertos. - -Por ejemplo, la orden siguiente injerta la versión 3.5.4 de GnuTLS en Wget y -todas sus dependencias, substituyendo las referencias a la versión de GnuTLS -que tienen actualmente: - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -Esta opción tiene la ventaja de ser mucho más rápida que la reconstrucción -de todo. Pero hay una trampa: funciona si y solo si @var{paquete} y -@var{reemplazo} son estrictamente compatibles---por ejemplo, si proporcionan -una biblioteca, la interfaz binaria de aplicación (ABI) de dichas -bibliotecas debe ser compatible. Si @var{reemplazo} es incompatible de -alguna manera con @var{paquete}, el paquete resultante puede no ser -usable. ¡Úsela con precaución! - -@item --with-git-url=@var{paquete}=@var{url} -@cindex Git, usar la última revisión -@cindex última revisión, construcción -Build @var{package} from the latest commit of the @code{master} branch of -the Git repository at @var{url}. Git sub-modules of the repository are -fetched, recursively. - -For example, the following command builds the NumPy Python library against -the latest commit of the master branch of Python itself: - -@example -guix build python-numpy \ - --with-git-url=python=https://github.com/python/cpython -@end example - -This option can also be combined with @code{--with-branch} or -@code{--with-commit} (see below). - -@cindex integración continua -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-branch=@var{paquete}=@var{rama} -Build @var{package} from the latest commit of @var{branch}. If the -@code{source} field of @var{package} is an origin with the @code{git-fetch} -method (@pxref{Referencia de ``origin''}) or a @code{git-checkout} object, the -repository URL is taken from that @code{source}. Otherwise you have to use -@code{--with-git-url} to specify the URL of the Git repository. - -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 - -@item --with-commit=@var{paquete}=@var{revisión} -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 Opciones de construcción adicionales -@subsection Opciones de construcción adicionales - -Las opciones de línea de ordenes presentadas a continuación son específicas -de @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{fichero} -@itemx -f @var{fichero} -Construye el paquete, derivación u otro objeto tipo-fichero al que evalúa el -código en @var{fichero} (@pxref{Expresiones-G, file-like objects}). - -Como un ejemplo, @var{fichero} puede contener una definición como esta -(@pxref{Definición de paquetes}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{expr} -@itemx -e @var{expr} -Construye el paquete o derivación al que @var{expr} evaulua. - -Por ejemplo, @var{expr} puede ser @code{(@@ (gnu packages guile) -guile-1.8)}, que designa sin ambigüedad a esta variante específica de la -versión 1.8 de Guile. - -De manera alternativa, @var{expr} puede ser una expresión-G, en cuyo caso se -usa como un programa de construcción pasado a @code{gexp->derivation} -(@pxref{Expresiones-G}). - -Por último, @var{expr} puede hacer referencia a un procedimiento mónadico -sin parámetros (@pxref{La mónada del almacén}). El procedimiento debe devolver una -derivación como un valor monádico, el cual después se pasa a través de -@code{run-with-store}. - -@item --source -@itemx -S -Construye las derivaciones de las fuentes de los paquetes, en vez de los -paquetes mismos. - -Por ejemplo, @code{guix build -S gcc} devuelve algo como -@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, el cual es el archivador tar de -fuentes de GCC. - -El archivador tar devuelto es el resultado de aplicar cualquier parche y -fragmento de código en el origen (campo @code{origin}) del paquete -(@pxref{Definición de paquetes}). - -@item --sources -Obtiene y devuelve las fuentes de @var{paquete-o-derivación} y todas sus -dependencias, recursivamente. Esto es útil para obtener una copia local de -todo el código fuente necesario para construir los @var{paquetes}, -permitiendole construirlos llegado el momento sin acceso a la red. Es una -extensión de la opción @code{--source} y puede aceptar uno de los siguientes -valores opcionales como parámetro: - -@table @code -@item package -Este valor hace que la opción @code{--sources} se comporte de la misma -manera que la opción @code{--source}. - -@item all -Construye las derivaciones de las fuentes de todos los paquetes, incluyendo -cualquier fuente que pueda enumerarse como entrada (campo -@code{inputs}). Este es el valor predeterminado. - -@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 -Construye las derivaciones de fuentes de todos los paquetes, así como todas -las entradas transitivas de los paquetes. Esto puede usarse, por ejemplo, -para obtener las fuentes de paquetes para una construcción posterior sin -conexión a la red. - -@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{sistema} -@itemx -s @var{sistema} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the -system type of the build host. The @command{guix build} command allows you -to repeat this option several times, in which case it builds for all the -specified systems; other commands ignore extraneous @option{-s} options. - -@quotation Nota -La opción @code{--system} es para compilación @emph{nativa} y no debe -confundirse con la compilación cruzada. Véase @code{--target} más adelante -para información sobre compilación cruzada. -@end quotation - -Un ejemplo de uso de esta opción es en sistemas basados en Linux, que pueden -emular diferentes personalidades. Por ejemplo, pasar -@code{--system=i686-linux} en un sistema @code{x86_64-linux} o -@code{--system=armhf-linux} en un sistema @code{aarch64-linux} le permite -construir paquetes en un entorno de 32-bits completo. - -@quotation Nota -La construcción para un sistema @code{armhf-linux} está habilitada -incondicionalmente en máquinas @code{aarch64-linux}, aunque determinados -procesadores aarch64 no permiten esta funcionalidad, notablemente el -ThunderX. -@end quotation - -De manera similar, cuando la emulación transparente con QEMU y -@code{binfmt_misc} está habilitada (@pxref{Servicios de virtualización, -@code{qemu-binfmt-service-type}}), puede construir para cualquier sistema -para el que un manejador QEMU de @code{binfmt_misc} esté instalado. - -Las construcciones para un sistema distinto al de la máquina que usa pueden -delegarse también a una máquina remota de la arquitectura -correcta. @xref{Configuración de delegación del daemon}, para más información sobre -delegación. - -@item --target=@var{tripleta} -@cindex compilación cruzada -Compilación cruzada para la @var{tripleta}, que debe ser una tripleta GNU -válida, cómo @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, -GNU configuration triplets,, autoconf, Autoconf}). - -@anchor{build-check} -@item --check -@cindex determinismo, comprobación -@cindex reproducibilidad, comprobación -Reconstruye @var{paquete-o-derivación}, que ya está disponible en el -almacén, y emite un error si los resultados de la construcción no son -idénticos bit-a-bit. - -Este mecanismo le permite comprobar si sustituciones previamente instaladas -son genuinas (@pxref{Sustituciones}), o si el resultado de la construcción de -un paquete es determinista. @xref{Invocación de guix challenge}, para más -información de referencia y herramientas. - -Cuando se usa conjuntamente con @option{--keep-failed}, la salida que -difiere se mantiene en el almacén, bajo -@file{/gnu/store/@dots{}-check}. Esto hace fácil buscar diferencias entre -los dos resultados. - -@item --repair -@cindex reparar elementos del almacén -@cindex corrupción, recuperarse de -Intenta reparar los elementos del almacén especificados, si están corruptos, -volviendo a descargarlos o reconstruyendolos. - -Esta operación no es atómica y por lo tanto está restringida a @code{root}. - -@item --derivations -@itemx -d -Devuelve las rutas de derivación, no las rutas de salida, de los paquetes -proporcionados. - -@item --root=@var{fichero} -@itemx -r @var{fichero} -@cindex GC, añadir raíces -@cindex raíces del recolector de basura, añadir -Hace que @var{fichero} sea un enlace simbólico al resultado, y lo registra -como una raíz del recolector de basura. - -Consecuentemente, los resultados de esta invocación de @command{guix build} -se protegen de la recolección de basura hasta que @var{fichero} se -elimine. Cuando se omite esa opción, los resultados son candidatos a la -recolección de basura en cuanto la construcción se haya -completado. @xref{Invocación de guix gc}, para más sobre las raíces del -recolector de basura. - -@item --log-file -@cindex logs de construcción, acceso -Devuelve los nombres de ficheros o URL de los log de construcción para el -@var{paquete-o-derivación} proporcionado, o emite un error si no se -encuentran los log de construcción. - -Esto funciona independientemente de cómo se especificasen los paquetes o -derivaciones. Por ejemplo, las siguientes invocaciones son equivalentes: - -@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 - -Si un log no está disponible localmente, y a menos que se proporcione -@code{--no-substitutes}, la orden busca el log correspondiente en uno de los -servidores de sustituciones (como se especificaron con -@code{--substitute-urls}). - -Por lo que dado el caso, imaginese que desea ver el log de construcción de -GDB en MIPS, pero realmente está en una máquina @code{x86_64}: - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -¡Puede acceder libremente a una biblioteca inmensa de log de construcción! -@end table - -@node Depuración de fallos de construcción -@subsection Depuración de fallos de construcción - -@cindex fallos de construcción, depuración -Cuando esté definiendo un paquete nuevo (@pxref{Definición de paquetes}), -probablemente se encuentre que dedicando algún tiempo a depurar y afinar la -construcción hasta obtener un resultado satisfactorio. Para hacerlo, tiene -que lanzar manualmente las órdenes de construcción en un entorno tan similar -como sea posible al que el daemon de construcción usa. - -Para ello, la primera cosa a hacer es usar la opción @option{--keep-failed} -o @option{-K} de @command{guix build}, lo que mantiene el árbol de la -construcción fallida en @file{/tmp} o el directorio que especificase con -@code{TMPDIR} (@pxref{Invocación de guix build, @code{--keep-failed}}). - -De ahí en adelante, puede usar @command{cd} para ir al árbol de la -construcción fallida y cargar el fichero @file{environment-variables}, que -contiene todas las definiciones de variables de entorno que existían cuando -la construcción falló. Digamos que está depurando un fallo en la -construcción del paquete @code{foo}; una sesión típica sería así: - -@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 - -Ahora puede invocar órdenes (casi) como si fuese el daemon y encontrar los -errores en su proceso de construcción. - -A veces ocurre que, por ejemplo, las pruebas de un paquete pasan cuando las -ejecuta manualmente pero fallan cuando el daemon las ejecuta. Esto puede -suceder debido a que el daemon construye dentro de contenedores donde, al -contrario que en nuestro entorno previo, el acceso a la red no está -disponible, @file{/bin/sh} no existe, etc. (@pxref{Configuración del entorno de construcción}). - -En esos casos, puede tener que inspeccionar el proceso de construcción desde -un contenedor similar al creado por el daemon de construcción: - -@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 - -Aquí, @command{guix environment -C} crea un contenedor y lanza un shell -nuevo en él (@pxref{Invocación de guix environment}). El fragmento -@command{--ad-hoc strace gdb} añade las ordenes @command{strace} y -@command{gdb} al contenedor, las cuales pueden resultar útiles durante la -depuración. La opción @option{--no-grafts} asegura que obtenemos exactamente -el mismo entorno, con paquetes sin injertos (@pxref{Actualizaciones de seguridad}, para -más información sobre los injertos). - -Para acercarnos más al contenedor usado por el daemon de construcción, -podemos eliminar @file{/bin/sh}: - -@example -[env]# rm /bin/sh -@end example - -(No se preocupe, es inocuo: todo esto ocurre en el contenedor de usar y -tirar creado por @command{guix environment}). - -La orden @command{strace} probablemente no esté en la ruta de búsqueda, pero -podemos ejecutar: - -@example -[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check -@end example - -De este modo, no solo habrá reproducido las variables de entorno que usa el -daemon, también estará ejecutando el proceso de construcción en un -contenedor similar al usado por el daemon. - - -@node Invocación de guix edit -@section Invocación de @command{guix edit} - -@cindex @command{guix edit} -@cindex definición de paquete, edición -¡Tantos paquetes, tantos ficheros de fuentes! La orden @command{guix edit} -facilita la vida de las usuarias y empaquetadoras apuntando su editor al -fichero de fuentes que contiene la definición de los paquetes -especificados. Por ejemplo: - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -lanza el programa especificado en la variable de entorno @code{VISUAL} o en -@code{EDITOR} para ver la receta de GCC@tie{}4.9.3 y la de Vim. - -Si está usando una copia de trabajo de Git de Guix (@pxref{Construcción desde Git}), o ha creado sus propios paquetes en @code{GUIX_PACKAGE_PATH} -(@pxref{Módulos de paquetes}), será capaz de editar las recetas de los -paquetes. En otros casos, podrá examinar las recetas en modo de lectura -únicamente para paquetes actualmente en el almacén. - - -@node Invocación de guix download -@section Invocación de @command{guix download} - -@cindex @command{guix download} -@cindex descargando las fuentes de paquetes -Durante la escritura de una definición de paquete, las desarrolladoras -típicamente tienen que descargar un archivador tar de fuentes, calcular su -hash SHA256 y escribir ese hash en la definición del paquete -(@pxref{Definición de paquetes}). La herramienta @command{guix download} ayuda -con esta tarea: descarga un fichero de la URI proporcionada, lo añade al -almacén e imprime tanto su nombre de fichero en el almacén como su hash -SHA256. - -El hecho de que el fichero descargado se añada al almacén ahorra ancho de -banda: cuando el desarrollador intenta construir el paquete recién definido -con @command{guix build}, el archivador de fuentes no tiene que descargarse -de nuevo porque ya está en el almacén. También es una forma conveniente de -conservar ficheros temporalmente, que pueden ser borrados en un momento dado -(@pxref{Invocación de guix gc}). - -La orden @command{guix download} acepta las mismas URI que las usadas en las -definiciones de paquetes. En particular, permite URI @code{mirror://}. Las -URI @code{https} (HTTP sobre TLS) se aceptan @emph{cuando} el enlace Guile -con GnuTLS está disponible en el entorno de la usuaria; cuando no está -disponible se emite un error. @xref{Guile Preparations, how to install the -GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, para más -información. - -@command{guix download} verifica los certificados del servidor HTTPS -cargando las autoridades X.509 del directorio al que apunta la variable de -entorno @code{SSL_CERT_DIR} (@pxref{Certificados X.509}), a menos que se use -@option{--no-check-certificate}. - -Las siguientes opciones están disponibles: - -@table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Escribe el hash en el formato especificado por @var{fmt}. Para más -información sobre los valores aceptados en @var{fmt}, @pxref{Invocación de guix hash}. - -@item --no-check-certificate -No valida los certificados X.509 de los servidores HTTPS. - -Cuando se usa esta opción, no tiene @emph{absolutamente ninguna garantía} de -que está comunicando con el servidor responsable de la URL auténtico, lo que -le hace vulnerables a ataques de intercepción (``man-in-the-middle''). - -@item --output=@var{fichero} -@itemx -o @var{fichero} -Almacena el fichero descargado en @var{fichero} en vez de añadirlo al -almacén. -@end table - -@node Invocación de guix hash -@section Invocación de @command{guix hash} - -@cindex @command{guix hash} -La orden @command{guix hash} calcula el hash SHA256 de un fichero. Es -principalmente una conveniente herramienta para cualquiera que contribuya a -la distribución: calcula el hash criptográfico de un fichero, que puede -usarse en la definición de un paquete (@pxref{Definición de paquetes}). - -La sintaxis general es: - -@example -guix hash @var{opciones} @var{fichero} -@end example - -Cuando @var{fichero} es @code{-} (un guión), @command{guix hash} calcula el -hash de los datos leídos por la entrada estándar. @command{guix hash} tiene -las siguientes opciones: - -@table @code - -@item --format=@var{fmt} -@itemx -f @var{fmt} -Escribe el hash en el formato especificado por @var{fmt}. - -Los formatos disponibles son: @code{nix-base32}, @code{base32}, -@code{base16} (se puede usar también @code{hex} y @code{hexadecimal}). - -Si no se especifica la opción @option{--format}, @command{guix hash} -mostrará el hash en @code{nix-base32}. Esta representación es la usada en -las definiciones de paquetes. - -@item --recursive -@itemx -r -Calcula el hash de @var{fichero} recursivamente. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -Es este caso el hash se calcula en un archivador que contiene @var{fichero}, -incluyendo su contenido si es un directorio. Algunos de los metadatos de -@var{fichero} son parte del archivador; por ejemplo, cuando @var{fichero} es -un fichero normal, el hash es diferente dependiendo de si @var{fichero} es -ejecutable o no. Los metadatos como las marcas de tiempo no influyen en el -hash (@pxref{Invocación de guix archive}). - -@item --exclude-vcs -@itemx -x -Cuando se combina con @option{--recursive}, excluye los directorios del -sistema de control de versiones (@file{.bzr}, @file{.git}, @file{.hg}, -etc.). - -@vindex git-fetch -Como un ejemplo, así es como calcularía el hash de una copia de trabajo Git, -lo cual es útil cuando se usa el método @code{git-fetch} (@pxref{Referencia de ``origin''}): - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Invocación de guix import -@section Invocación de @command{guix import} - -@cindex importar paquetes -@cindex importación de un paquete -@cindex conversión de un paquete -@cindex Invocación de @command{guix import} -La orden @command{guix import} es útil para quienes desean añadir un paquete -a la distribución con el menor trabajo posible---una demanda legítima. La -orden conoce algunos repositorios de los que puede ``importar'' metadatos de -paquetes. El resultado es una definición de paquete, o una plantilla de -ella, en el formato que conocemos (@pxref{Definición de paquetes}). - -La sintaxis general es: - -@example -guix import @var{importador} @var{opciones}@dots{} -@end example - -@var{importador} especifica la fuente de la que se importan los metadatos -del paquete, @var{opciones} especifica un identificador de paquete y otras -opciones específicas del @var{importador}. Actualmente, los ``importadores'' -disponibles son: - -@table @code -@item gnu -Importa los metadatos del paquete GNU seleccionado. Proporciona una -plantilla para la última versión de dicho paquete GNU, incluyendo el hash de -su archivador tar de fuentes, y su sinopsis y descripción canónica. - -Información adicional como las dependencias del paquete y su licencia deben -ser deducidas manualmente. - -Por ejemplo, la siguiente orden devuelve una definición de paquete para -GNU@tie{}Hello. - -@example -guix import gnu hello -@end example - -Las opciones específicas de línea de ordenes son: - -@table @code -@item --key-download=@var{política} -Como en @code{guix refresh}, especifica la política de tratamiento de las -claves OpenPGP no encontradas cuando se verifica la firma del -paquete. @xref{Invocación de guix refresh, @code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Importa metadatos desde el @uref{https://pypi.python.org/, índice de -paquetes Python (PyPI)}. La información se toma de la descripción con -formato JSON disponible en @code{pypi.python.org} y habitualmente incluye -toda la información relevante, incluyendo las dependencias del paquete. Para -una máxima eficiencia, se recomienda la instalación de la utilidad -@command{unzip}, de manera que el importador pueda extraer los archivos -wheel de Python y obtener datos de ellos. - -La siguiente orden importa los meta-datos para el paquete de Python -@code{itsdangerous}: - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -r -Recorre el grafo de dependencias del paquete original proporcionado -recursivamente y genera expresiones de paquete para todos aquellos paquetes -que no estén todavía en Guix. -@end table - -@item gem -@cindex gem -Importa metadatos desde @uref{https://rubygems.org/, RubyGems}. La -información se extrae de la descripción en formato JSON disponible en -@code{rubygems.org} e incluye la información más relevante, incluyendo las -dependencias en tiempo de ejecución. Hay algunos puntos a tener en cuenta, -no obstante. Los metadatos no distinguen entre sinopsis y descripción, por -lo que se usa la misma cadena para ambos campos. Adicionalmente, los -detalles de las dependencias no-Ruby necesarias para construir extensiones -nativas no está disponible y se deja como ejercicio a la empaquetadora. - -La siguiente orden importa los meta-datos para el paquete de Ruby -@code{rails}: - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -r -Recorre el grafo de dependencias del paquete original proporcionado -recursivamente y genera expresiones de paquete para todos aquellos paquetes -que no estén todavía en Guix. -@end table - -@item cpan -@cindex CPAN -Importa metadatos desde @uref{https://www.metacpan.org/, MetaCPAN}. La -información se extrae de la descripción en formato JSON disponible a través -del @uref{https://fastapi.metacpan.org/, API de MetaCPAN} e incluye la -información más relevante, como las dependencias de otros módulos. La -información de la licencia debe ser comprobada atentamente. Si Perl está -disponible en el almacén, se usará la utilidad @code{corelist} para borrar -los módulos básicos de la lista de dependencias. - -La siguiente orden importa los metadatos del módulo Perl -@code{Acme::Boolean}: - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -Importa metadatos desde @uref{https://cran.r-project.org/, CRAN}, el -repositorio central para el @uref{http://r-project.org, entorno estadístico -y gráfico GNU@tie{}R}. - -La información se extrae del fichero @code{DESCRIPTION} del paquete. - -La siguiente orden importa los metadatos del paquete de R @code{Cairo}: - -@example -guix import cran Cairo -@end example - -Cuando se añade @code{--recursive}, el importador recorrerá el grafo de -dependencias del paquete original proporcionado recursivamente y generará -expresiones de paquetes para todos aquellos que no estén todavía en Guix. - -Cuando se agrega @code{--archive=bioconductor}, los metadatos se importan de -@uref{https://www.bioconductor.org, Bioconductor}, un repositorio de -paquetes R para el análisis y comprensión de datos genéticos de alto caudal -en bioinformática. - -La información se extrae del fichero @code{DESCRIPTION} del paquete -publicado en la interfaz web del repositorio SVN de Bioconductor. - -La siguiente orden importa los metadatos del paquete de R -@code{GenomicRanges}: - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex Tex Live -@cindex CTAN -Importa metadatos desde @uref{http://www.ctan.org/, CTAN}, la completa red -de archivos TeX para paquetes TeX que son parte de la -@uref{https://www.tug.org/texlive/, distribución TeX Live}. - -La información del paquete se obtiene a través del API XML proporcionado por -CTAN, mientras que el código fuente se descarga del repositorio SVN del -proyecto TeX Live. Se hace porque CTAN no guarda archivos con versiones. - -La siguiente orden importa los metadatos del paquete de TeX @code{fontspec}: - -@example -guix import texlive fontspec -@end example - -Cuando se añade @code{--archive=DIRECTORIO}, el código fuente no se descarga -del subdirectorio @file{latex} del árbol @file{texmf-dist/source} en el -repositorio SVN de Tex Live, sino de el directorio especificado bajo la -misma raíz. - -La siguiente orden importa los metadatos del paquete @code{ifxetex} de CTAN -mientras que obtiene las fuentes del directorio @file{texmf/source/generic}: - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, importación -Importa metadatos de paquetes desde un fichero JSON local. Considere el -siguiente ejemplo de definición de paquete en formato JSON: - -@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 - -Los nombres de los campos son los mismos que para el registro -@code{} (@xref{Definición de paquetes}). Las referencias a otros -paquetes se proporcionan como listas JSON de cadenas de especificación de -paquete entrecomilladas como @code{guile} o @code{guile@@2.0}. - -El importador también permite una definición de fuentes más explícita usando -los campos comunes de los registros @code{}: - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -La siguiente orden importa los metadatos desde el fichero JSON -@code{hello.json} y devuelve una expresión de ``package'': - -@example -guix import json hello.json -@end example - -@item nix -Importa metadatos desde una copia local de las fuentes de la -@uref{http://nixos.org/nixpkgs/, distribución Nixpkgs}@footnote{Esto depende -de la orden @command{nix-instantiate} de @uref{http://nixos.org/nix/, -Nix}.}. Las definiciones de paquete en Nixpkgs típicamente están escritas en -una mezcla de lenguaje Nix y código Bash. Esta orden únicamente importa la -estructura de alto nivel del paquete escrita en lenguaje Nix. Normalmente -incluye todos los campos básicos de una definición de paquete. - -Cuando se importa un paquete GNU, la sinopsis y la descripción se -substituyen por la variante canónica oficial. - -Habitualmente, tendrá que ejecutar primero: - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -de modo que @command{nix-instantiate} no intente abrir la base de datos Nix. - -Como un ejemplo, la orden siguiente importa la definición de paquete de -LibreOffice (más precisamente, importa la definición del paquete asociado al -atributo de nivel superior @code{libreoffice}): - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Importa metadatos desde el archivo central de paquetes de la comunidad -Haskell @uref{https://hackage.haskell.org/, Hackage}. La información se -obtiene de ficheros Cabal e incluye toda la información relevante, -incluyendo las dependencias del paquete. - -Las opciones específicas de línea de ordenes son: - -@table @code -@item --stdin -@itemx -s -Lee un fichero Cabal por la entrada estándar. -@item --no-test-dependencies -@itemx -t -No incluye las dependencias necesarias únicamente para las baterías de -pruebas. -@item --cabal-environment=@var{alist} -@itemx -e @var{alist} -@var{alist} es una lista asociativa Scheme que define el entorno en el que -los condicionales Cabal se evalúan. Los valores aceptados son: @code{os}, -@code{arch}, @code{impl} y una cadena que representa el nombre de la -condición. El valor asociado a la condición tiene que ser o bien el símbolo -@code{true} o bien @code{false}. Los valores predeterminados asociados a las -claves @code{os}, @code{arch} y @code{impl} son @samp{linux}, @samp{x86_64} -y @samp{ghc}, respectivamente. -@item --recursive -@itemx -r -Recorre el grafo de dependencias del paquete original proporcionado -recursivamente y genera expresiones de paquete para todos aquellos paquetes -que no estén todavía en Guix. -@end table - -La siguiente orden importa los metadatos de la última versión del paquete -Haskell @code{HTTP} sin incluir las dependencias de las pruebas y -especificando la opción @samp{network-uri} con valor @code{false}: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -Se puede especificar opcionalmente una versión específica del paquete -añadiendo al nombre del paquete una arroba y el número de versión como en el -siguiente ejemplo: - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -El importador @code{stackage} es un recubrimiento sobre el de -@code{hackage}. Toma un nombre de paquete, busca la versión de paquete -incluida en una publicación de la versión de mantenimiento extendido (LTS) -@uref{https://www.stackage.org, Stackage} y usa el importador @code{hackage} -para obtener sus metadatos. Fíjese que es su decisión seleccionar una -publicación LTS compatible con el compilador GHC usado en Guix. - -Las opciones específicas de línea de ordenes son: - -@table @code -@item --no-test-dependencies -@itemx -t -No incluye las dependencias necesarias únicamente para las baterías de -pruebas. -@item --lts-version=@var{versión} -@itemx -l @var{versión} -@var{versión} es la versión LTS de publicación deseada. Si se omite se usa -la última publicación. -@item --recursive -@itemx -r -Recorre el grafo de dependencias del paquete original proporcionado -recursivamente y genera expresiones de paquete para todos aquellos paquetes -que no estén todavía en Guix. -@end table - -La siguiente orden importa los metadatos del paquete Haskell @code{HTTP} -incluido en la versión de publicación LTS de Stackage 7.18: - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Importa metadatos desde el repositorio de archivos de paquetes Emacs Lisp -(ELPA) (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Las opciones específicas de línea de ordenes son: - -@table @code -@item --archive=@var{repo} -@itemx -a @var{repo} -@var{repo} identifica el repositorio de archivos del que obtener la -información. Actualmente los repositorios disponibles y sus identificadores -son: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, seleccionado con el identificador -@code{gnu}. Es el predeterminado. - -Los paquetes de @code{elpa.gnu.org} están firmados con una de las claves que -contiene el anillo de claves GnuPG en -@file{share/emacs/25.1/etc/package-keyring.gpg} (o similar) en el paquete -@code{emacs} (@pxref{Package Installation, ELPA package signatures,, emacs, -The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, seleccionado con el -identificador @code{melpa-stable}. - -@item -@uref{http://melpa.org/packages, MELPA}, seleccionado con el identificador -@code{melpa}. -@end itemize - -@item --recursive -@itemx -r -Recorre el grafo de dependencias del paquete original proporcionado -recursivamente y genera expresiones de paquete para todos aquellos paquetes -que no estén todavía en Guix. -@end table - -@item crate -@cindex crate -Importa metadatos desde el repositorio de paquetes Rust -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Importa metadatos desde el repositorio de paquetes -@uref{https://opam.ocaml.org/, OPAM} usado por la comunidad OCaml. -@end table - -La estructura del código de @command{guix import} es modular. Sería útil -tener más importadores para otros formatos de paquetes, y su ayuda es -bienvenida aquí (@pxref{Contribuir}). - -@node Invocación de guix refresh -@section Invocación de @command{guix refresh} - -@cindex @command{guix refresh} -La principal audiencia de @command{guix refresh} son desarrolladoras de la -distribución de software GNU. Por defecto, informa de cualquier paquete -proporcionado por la distribución que esté anticuado comparado con la última -versión oficial, de esta manera: - -@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 - -De manera alternativa, se pueden especificar los paquetes a considerar, en -cuyo caso se emite un aviso para paquetes que carezcan de actualizador: - -@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} navega por los repositorios oficiales de cada paquete -y determina el número de versión mayor entre las publicaciones -encontradas. La orden sabe cómo actualizar tipos específicos de paquetes: -paquetes GNU, paquetes ELPA, etc.---vea la documentación de @option{--type} -más adelante. Hay muchos paquetes, no obstante, para los que carece de un -método para determinar si está disponible una versión oficial posterior. No -obstante, el mecanismo es extensible, ¡no tenga problema en contactarnos -para añadir un método nuevo! - -@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 - -A veces el nombre oficial es diferente al nombre de paquete usado en Guix, y -@command{guix refresh} necesita un poco de ayuda. La mayor parte de los -actualizadores utilizan la propiedad @code{upstream-name} en las -definiciones de paquetes, que puede usarse para obtener dicho efecto: - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -Cuando se proporciona @code{--update}, modifica los ficheros de fuentes de -la distribución para actualizar los números de versión y hash de los -archivadores tar de fuentes en las recetas de los paquetes (@pxref{Definición de paquetes}). Esto se consigue con la descarga del último archivador de -fuentes del paquete y su firma OpenPGP asociada, seguida de la verificación -del archivador descargado y su firma mediante el uso de @command{gpg}, y -finalmente con el cálculo de su hash. Cuando la clave pública usada para -firmar el archivador no se encuentra en el anillo de claves de la usuaria, -se intenta automáticamente su obtención desde un servidor de claves -públicas; cuando se encuentra, la clave se añade al anillo de claves de la -usuaria; en otro caso, @command{guix refresh} informa de un error. - -Se aceptan las siguientes opciones: - -@table @code - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considera el paquete al que evalúa @var{expr} - -Es útil para hacer una referencia precisa de un paquete concreto, como en -este ejemplo: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -Esta orden enumera los paquetes que dependen de la libc ``final'' -(esencialmente todos los paquetes). - -@item --update -@itemx -u -Actualiza los ficheros fuente de la distribución (recetas de paquetes) en su -lugar. Esto se ejecuta habitualmente desde una copia de trabajo del árbol de -fuentes de Guix (@pxref{Ejecución de Guix antes de estar instalado}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Definición de paquetes}, para más información sobre la definición de -paquetes. - -@item --select=[@var{subconjunto}] -@itemx -s @var{subconjunto} -Selecciona todos los paquetes en @var{subconjunto}, o bien @code{core} o -bien @code{non-core}. - -El subconjunto @code{core} hace referencia a todos los paquetes en el núcleo -de la distribución---es decir, paquetes que se usan para construir ``todo lo -demás''. Esto incluye GCC, libc, Binutils, Bash, etc. Habitualmente, cambiar -uno de esos paquetes en la distribución conlleva la reconstrucción de todos -los demás. Por tanto, esas actualizaciones son una inconveniencia para las -usuarias en términos de tiempo de construcción o ancho de banda usado por la -actualización. - -El subconjunto @code{non-core} hace referencia a los paquetes restantes. Es -típicamente útil en casos donde una actualización de paquetes básicos no -sería conveniente. - -@item --manifest=@var{fichero} -@itemx -m @var{fichero} -Selecciona todos los paquetes del manifiesto en @var{fichero}. Es útil para -comprobar si algún paquete del manifiesto puede actualizarse. - -@item --type=@var{actualizador} -@itemx -t @var{actualizador} -Selecciona únicamente paquetes manejados por @var{actualizador} (puede ser -una lista separada por comas de actualizadores). Actualmente, -@var{actualizador} puede ser: - -@table @code -@item gnu -el actualizador de paquetes GNU; -@item gnome -el actualizador para paquetes GNOME; -@item kde -el actualizador para paquetes KDE; -@item xorg -el actualizador para paquetes X.org; -@item kernel.org -el actualizador para paquetes alojados en kernel.org; -@item elpa -el actualizador para paquetes @uref{http://elpa.gnu.org/, ELPA}; -@item cran -el actualizador para paquetes @uref{https://cran.r-project.org/, CRAN}; -@item bioconductor -el actualizador para paquetes R @uref{https://www.bioconductor.org/, -Bioconductor}; -@item cpan -el actualizador para paquetes @uref{http://www.cpan.org/, CPAN}; -@item pypi -el actualizador para paquetes @uref{https://pypi.python.org, PyPI}. -@item gem -el actualizador para paquetes @uref{https://rubygems.org, RubyGems}. -@item github -el actualizador para paquetes @uref{https://github.com, GitHub}. -@item hackage -el actualizador para paquetes @uref{https://hackage.haskell.org, Hackage}. -@item stackage -el actualizador para paquetes @uref{https://www.stackage.org, Stackage}. -@item crate -el actualizador para paquetes @uref{https://crates.io, Crates}. -@item launchpad -el actualizador para paquetes @uref{https://launchpad.net, Launchpad}. -@end table - -Por ejemplo, la siguiente orden únicamente comprueba actualizaciones de -paquetes Emacs alojados en @code{elpa.gnu.org} y actualizaciones de paquetes -CRAN: - -@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 - -Además, @command{guix refresh} puede recibir uno o más nombres de paquetes, -como en este ejemplo: - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -La orden previa actualiza específicamente los paquetes @code{emacs} y -@code{idutils}. La opción @code{--select} no tendría efecto en este caso. - -Cuando se considera la actualización de un paquete, a veces es conveniente -conocer cuantos paquetes se verían afectados por la actualización y su -compatibilidad debería comprobarse. Para ello la siguiente opción puede -usarse cuando se proporcionan uno o más nombres de paquete a @command{guix -refresh}: - -@table @code - -@item --list-updaters -@itemx -L -Enumera los actualizadores disponibles y finaliza (vea la opción previa -@option{--type}). - -Para cada actualizador, muestra la fracción de paquetes que cubre; al final -muestra la fracción de paquetes cubiertos por todos estos actualizadores. - -@item --list-dependent -@itemx -l -Enumera los paquetes de nivel superior dependientes que necesitarían una -reconstrucción como resultado de la actualización de uno o más paquetes. - -@xref{Invocación de guix graph, el tipo @code{reverse-package} de @command{guix -graph}}, para información sobre cómo visualizar la lista de paquetes que -dependen de un paquete. - -@end table - -Sea consciente de que la opción @code{--list-dependent} únicamente -@emph{aproxima} las reconstrucciones necesarias como resultado de una -actualización. Más reconstrucciones pueden ser necesarias bajo algunas -circunstancias. - -@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 - -La orden previa enumera un conjunto de paquetes que puede ser construido -para comprobar la compatibilidad con una versión actualizada del paquete -@code{flex}. - -@table @code - -@item --list-transitive -Enumera todos los paquetes de los que uno o más paquetes dependen. - -@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 - -La orden previa enumera un conjunto de paquetes que, en caso de cambiar, -causarían la reconstrucción de @code{flex}. - -Las siguientes opciones pueden usarse para personalizar la operación de -GnuPG: - -@table @code - -@item --gpg=@var{orden} -Use @var{orden} como la orden de GnuPG 2.x. Se busca @var{orden} en -@code{PATH}. - -@item --keyring=@var{fichero} -Usa @var{fichero} como el anillo de claves para claves de -proveedoras. @var{fichero} debe estar en el @dfn{formato keybox}. Los -ficheros Keybox normalmente tienen un nombre terminado en @file{.kbx} y -GNU@tie{}Privacy Guard (GPG) puede manipular estos ficheros (@pxref{kbxutil, -@command{kbxutil},, gnupg, Using the GNU Privacy Guard}, para información -sobre una herramienta para manipular ficheros keybox). - -Cuando se omite esta opción, @command{guix refresh} usa -@file{~/.config/guix/upstream/trustedkeys.kbx} como el anillo de claves para -las firmas de proveedoras. Las firmas OpenPGP son comprobadas contra claves -de este anillo; las claves que falten son descargadas a este anillo de -claves también (véase @option{--key-download} a continuación). - -Puede exportar claves de su anillo de claves GPG predeterminado en un -fichero keybox usando órdenes como esta: - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mianillo.kbx -@end example - -Del mismo modo, puede obtener claves de un archivo keybox específico así: - -@example -gpg --no-default-keyring --keyring mianillo.kbx \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU -Privacy Guard}, para más información sobre la opción @option{--keyring} de -GPG. - -@item --key-download=@var{política} -Maneja las claves no encontradas de acuerdo a la @var{política}, que puede -ser una de: - -@table @code -@item always -Siempre descarga las claves OpenPGP no encontradas del servidor de claves, y -las añade al anillo de claves GnuPG de la usuaria. - -@item never -Nunca intenta descargar claves OpenPGP no encontradas. Simplemente propaga -el error. - -@item interactive -Cuando se encuentra un paquete firmado por una clave OpenPGP desconocida, -pregunta a la usuaria si descargarla o no. Este es el comportamiento -predeterminado. -@end table - -@item --key-server=@var{dirección} -Use @var{dirección} como el servidor de claves OpenPGP cuando se importa una -clave pública. - -@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 Invocación de guix lint -@section Invocación de @command{guix lint} - -@cindex @command{guix lint} -@cindex paquete, comprobación de errores -La orden @command{guix lint} sirve para ayudar a las desarrolladoras de -paquetes a evitar errores comunes y usar un estilo consistente. Ejecuta un -número de comprobaciones en un conjunto de paquetes proporcionado para -encontrar errores comunes en sus definiciones. Los @dfn{comprobadores} -disponibles incluyen (véase @code{--list-checkers} para una lista completa): - -@table @code -@item synopsis -@itemx description -Valida ciertas reglas tipográficas y de estilo en la descripción y sinopsis -de cada paquete. - -@item inputs-should-be-native -Identifica entradas que probablemente deberían ser entradas nativas. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Comprueba las URL @code{home-page} y @code{source} e informa aquellas que no -sean válidas. Sugiere una URL @code{mirror://} cuando sea aplicable. Si la -URL @code{source} redirecciona a una URL GitHub, recomienda el uso de la URL -GitHub. Comprueba que el nombre de fichero de las fuentes es significativo, -por ejemplo que no es simplemente un número de versión o revisión git, sin -un nombre @code{file-name} declarado (@pxref{Referencia de ``origin''}). - -@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 vulnerabilidades de seguridad -@cindex CVE, vulnerabilidades y exposiciones comunes -Informa de vulnerabilidades encontradas en las bases de datos de -vulnerabilidades y exposiciones comunes (CVE) del año actual y el pasado -@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, publicadas por el NIST de -EEUU}. - -Para ver información acerca de una vulnerabilidad particular, visite páginas -como: - -@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 -donde @code{CVE-YYYY-ABCD} es el identificador CVE---por ejemplo, -@code{CVE-2015-7554}. - -Las desarrolladoras de paquetes pueden especificar en las recetas del -paquete el nombre y versión en la @uref{https://nvd.nist.gov/cpe.cfm, -plataforma común de enumeración (CPE)} del paquete cuando difieren del -nombre o versión que usa Guix, como en este ejemplo: - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE llama a este paquete "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See . -Algunas entradas en la base de datos CVE no especifican a qué versión del -paquete hacen referencia, y por lo tanto ``permanecen visibles'' para -siempre. Las desarrolladoras de paquetes que encuentren alertas CVE y -verifiquen que pueden ignorarse, pueden declararlas como en este ejemplo: - -@example -(package - (name "t1lib") - ;; @dots{} - ;; Estas alertas de CVE no aplican y pueden ignorarse - ;; con seguridad. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item formatting -Avisa de problemas de formato obvios en el código fuente: espacios en blanco -al final de las líneas, uso de tabuladores, etc. -@end table - -La sintaxis general es: - -@example -guix lint @var{opciones} @var{paquete}@dots{} -@end example - -Si no se proporciona ningún paquete en la linea de órdenes, todos los -paquetes se comprueban. Las @var{opciones} pueden ser cero o más de las -siguientes: - -@table @code -@item --list-checkers -@itemx -l -Enumera y describe todos los comprobadores disponibles que se ejecutarán -sobre los paquetes y finaliza. - -@item --checkers -@itemx -c -Habilita únicamente los comprobadores especificados en una lista separada -por comas que use los nombres devueltos por @code{--list-checkers}. - -@end table - -@node Invocación de guix size -@section Invocación de @command{guix size} - -@cindex tamaño -@cindex tamaño del paquete -@cindex clausura -@cindex @command{guix size} -La orden @command{guix size} ayuda a las desarrolladoras de paquetes a -perfilar el uso de disco de los paquetes. Es fácil pasar por encima el -impacto que produce añadir una dependencia adicional a un paquete, o el -impacto del uso de una salida única para un paquete que puede ser dividido -fácilmente (@pxref{Paquetes con múltiples salidas}). Estos son los problemas -típicos que @command{guix size} puede resaltar. - -Se le pueden proporcionar una o más especificaciones de paquete como -@code{gcc@@4.8} o @code{guile:debug}, o un nombre de fichero en el -almacén. Considere este ejemplo: - -@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 clausura -Los elementos del almacén enumerados aquí constituyen la @dfn{clausura -transitiva} de Coreutils---es decir, Coreutils y todas sus dependencias, -recursivamente---como sería devuelto por: - -@example -$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 -@end example - -Aquí la salida muestra tres columnas junto a los elementos del almacén. La -primera columna, etiquetada ``total'', muestra el tamaño en mebibytes (MiB) -de la clausura del elemento del almacén---es decir, su propio tamaño sumado -al tamaño de todas sus dependencias. La siguiente columna, etiquetada -``self'', muestra el tamaño del elemento en sí. La última columna muestra la -relación entre el tamaño del elemento en sí frente al espacio ocupado por -todos los elementos enumerados. - -En este ejemplo, vemos que la clausura de Coreutils ocupa 79@tie{}MiB, cuya -mayor parte son libc y las bibliotecas auxiliares de GCC para tiempo de -ejecución. (Que libc y las bibliotecas de GCC representen una fracción -grande de la clausura no es un problema en sí, puesto que siempre están -disponibles en el sistema de todas maneras). - -Cuando los paquetes pasados a @command{guix size} están disponibles en el -almacén@footnote{Más precisamente, @command{guix size} busca la variante -@emph{sin injertos} de los paquetes, como el devuelto por @code{guix build -@var{paquete} --no-grafts}. @xref{Actualizaciones de seguridad}, para información sobre -injertos.} consultando al daemon para determinar sus dependencias, y mide su -tamaño en el almacén, de forma similar a @command{du -ms --apparent-size} -(@pxref{du invocation,,, coreutils, GNU Coreutils}). - -Cuando los paquetes proporcionados @emph{no} están en el almacén, -@command{guix size} informa en base de las sustituciones disponibles -(@pxref{Sustituciones}). Esto hace posible perfilar el espacio en disco -incluso de elementos del almacén que no están en el disco, únicamente -disponibles de forma remota. - -Puede especificar también varios nombres de paquetes: - -@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 -En este ejemplo vemos que la combinación de los cuatro paquetes toma -102.3@tie{}MiB en total, lo cual es mucho menos que la suma de cada -clausura, ya que tienen muchas dependencias en común. - -Las opciones disponibles son: - -@table @option - -@item --substitute-urls=@var{urls} -Usa la información de sustituciones de -@var{urls}. @xref{client-substitute-urls, la misma opción en @code{guix -build}}. - -@item --sort=@var{clave} -Ordena las líneas de acuerdo a @var{clave}, una de las siguientes opciones: - -@table @code -@item self -el tamaño de cada elemento (predeterminada); -@item clausura -el tamaño total de la clausura del elemento. -@end table - -@item --map-file=@var{fichero} -Escribe un mapa gráfico del uso del disco en formato PNG en el -@var{fichero}. - -Para el ejemplo previo, el mapa tiene esta pinta: - -@image{images/coreutils-size-map,5in,, mapa del uso del disco de Coreutils -producido por @command{guix size}} - -Esta opción necesita que la biblioteca -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} esté -instalada y visible en la ruta de búsqueda de módulos Guile. Cuando no es el -caso, @command{guix size} produce un error al intentar cargarla. - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Considera paquetes para @var{sistema}---por ejemplo, @code{x86_64-linux}. - -@end table - -@node Invocación de guix graph -@section Invocación de @command{guix graph} - -@cindex GAD (DAG en Inglés) -@cindex @command{guix graph} -@cindex dependencias de un paquete -Los paquetes y sus dependencias forman un @dfn{grafo}, específicamente un -grafo acíclico dirigido (GAD, DAG en Inglés). Puede hacerse difícil -rápidamente tener un modelo mental del GAD del paquete, por lo que la orden -@command{guix graph} proporciona una representación virtual del GAD. Por -defecto, @command{guix graph} emite una representación en GAD en el formato -de entrada de @uref{http://graphviz.org/,Graphviz}, por lo que su salida -puede ser pasada directamente a la herramienta @command{dot} de -Graphviz. También puede emitir una página HTMP con código JavaScript -embebido para mostrar un ``diagrama de acorde'' en un navegador Web, usando -la biblioteca @uref{https://d3js.org/, d3.js}, o emitir consultas Cypher -para construir un grafo en una base de datos de grafos que acepte el -lenguaje de consultas @uref{http://www.opencypher.org/, openCypher}. La -sintaxis general es: - -@example -guix graph @var{opciones} @var{paquete}@dots{} -@end example - -Por ejemplo, la siguiente orden genera un fichero PDF que representa el GAD -para GNU@tie{}Core Utilities, mostrando sus dependencias en tiempo de -construcción: - -@example -guix graph coreutils | dot -Tpdf > gad.pdf -@end example - -La salida es algo así: - -@image{images/coreutils-graph,2in,,Grafo de dependencias de GNU Coreutils} - -Bonito y pequeño grafo, ¿no? - -¡Pero hay más de un grafo! El grafo previo es conciso: es el grafo de los -objetos package, omitiendo las entradas implícitas como GCC, libc, grep, -etc. Es habitualmente útil tener un grafo conciso así, pero a veces una -puede querer ver más detalles. @command{guix graph} implementa varios tipos -de grafos, permitiendole seleccionar el nivel de detalle: - -@table @code -@item package -Este es el tipo por defecto usado en el ejemplo previo. Muestra el GAD de -objetos package, excluyendo dependencias implícitas. Es conciso, pero deja -fuera muchos detalles. - -@item reverse-package -Esto muestra el GAD @emph{inverso} de paquetes. Por ejemplo: - -@example -guix graph --type=reverse-package ocaml -@end example - -...@: yields the graph of packages that @emph{explicitly} depend on OCaml -(if you are also interested in cases where OCaml is an implicit dependency, -see @code{reverse-bag} below.) - -Fíjese que esto puede producir grafos inmensos para los paquetes básicos. Si -todo lo que quiere saber es el número de paquetes que dependen de uno -determinado, use @command{guix refresh --list-dependent} (@pxref{Invocación de guix refresh, @option{--list-dependent}}). - -@item bag-emerged -Este es el GAD del paquete, @emph{incluyendo} entradas implícitas. - -Por ejemplo, la siguiente orden: - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > gad.pdf -@end example - -...@: emite este grafo más grande: - -@image{images/coreutils-bag-graph,,5in,Grafo de dependencias detallado de -GNU Coreutils} - -En la parte inferior del grafo, vemos todas las entradas implícitas de -@var{gnu-build-system} (@pxref{Sistemas de construcción, @code{gnu-build-system}}). - -Ahora bien, fijese que las dependencias de estas entradas implícitas---es -decir, las @dfn{dependencias del lanzamiento inicial} -(@pxref{Lanzamiento inicial})---no se muestran aquí para mantener una salida -concisa. - -@item bag -Similar a @code{bag-emerged}, pero esta vez incluye todas las dependencias -del lanzamiento inicial. - -@item bag-with-origins -Similar a @code{bag}, pero también muestra los orígenes y sus dependencias. - -@item reverse-bag -This shows the @emph{reverse} DAG of packages. Unlike -@code{reverse-package}, it also takes implicit dependencies into account. -For example: - -@example -guix graph -t reverse-bag dune -@end example - -@noindent -...@: yields the graph of all packages that depend on Dune, directly or -indirectly. Since Dune is an @emph{implicit} dependency of many packages -@i{via} @code{dune-build-system}, this shows a large number of packages, -whereas @code{reverse-package} would show very few if any. - -@item derivación -Esta es la representación más detallada: muestra el GAD de derivaciones -(@pxref{Derivaciones}) y elementos simples del almacén. Comparada con las -representaciones previas, muchos nodos adicionales son visibles, incluyendo -los guiones de construcción, parches, módulos Guile, etc. - -Para este tipo de grafo, también es posible pasar un nombre de fichero -@file{.drv} en vez del nombre del paquete, como en: - -@example -guix graph -t derivation `guix system build -d mi-configuracion.scm` -@end example - -@item module -Este es el grafo de los @dfn{módulos de paquete} (@pxref{Módulos de paquetes}). Por ejemplo, la siguiente orden muestra el grafo para el módulo -de paquetes que define el paquete @code{guile}: - -@example -guix graph -t module guile | dot -Tpdf > grafo-del-modulo.pdf -@end example -@end table - -Todos los tipos previos corresponden a las @emph{dependencias durante la -construcción}. El grafo siguiente representa las @emph{dependencias en -tiempo de ejecución}: - -@table @code -@item references -Este es el grafo de @dfn{referencias} de la salida de un paquete, como lo -devuelve @command{guix gc --references} (@pxref{Invocación de guix gc}). - -Si la salida del paquete proporcionado no está disponible en el almacén, -@command{guix graph} intenta obtener la información de dependencias desde -las sustituciones. - -Aquí también puede proporcionar un nombre de fichero del almacén en vez de -un nombre de paquete. Por ejemplo, la siguiente orden produce el grafo de -referencias de su perfil (¡el cuál puede ser grande!): - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -Este es el grafo de @dfn{referentes} de la salida de un paquete, como lo -devuelve @command{guix gc --referrers} (@pxref{Invocación de guix gc}). - -Depende exclusivamente de información en su almacén. Por ejemplo, supongamos -que la versión actual de Inkscape está disponible en 10 perfiles en su -máquina; @command{guix graph -t referrers inkscape} mostrará un grafo cuya -raíz es Inkscape y con esos 10 perfiles enlazados a ella. - -Puede ayudar a determinar qué impide que un elemento del almacén sea -recolectado. - -@end table - -Las opciones disponibles son las siguientes: - -@table @option -@item --type=@var{tipo} -@itemx -t @var{tipo} -Produce un grafo de salida de @var{tipo}, donde @var{tipo} debe ser uno de -los valores enumerados previamente. - -@item --list-types -Enumera los tipos de grafos implementados. - -@item --backend=@var{motor} -@itemx -b @var{motor} -Produce un grafo usando el @var{motor} seleccionado. - -@item --list-backends -Enumera los motores de grafos implementados. - -Actualmente, los motores disponibles son Graphviz y d3.js. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considera el paquete al que evalúa @var{expr} - -Es útil para hacer una referencia precisa de un paquete concreto, como en -este ejemplo: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Muestra el grafo para @var{sistema}---por ejemplo, @code{i686-linux}. - -El grafo de dependencias del paquete es altamente independiente de la -arquitectura, pero existen algunas partes dependientes de la arquitectura -que esta opción le permite visualizar. -@end table - - - -@node Invocación de guix publish -@section Invocación de @command{guix publish} - -@cindex @command{guix publish} -El propósito de @command{guix publish} es permitir a las usuarias compartir -fácilmente su almacén con otras, quienes pueden usarlo como servidor de -sustituciones (@pxref{Sustituciones}). - -Cuando @command{guix publish} se ejecuta, lanza un servidor HTTP que permite -a cualquiera que tenga acceso a través de la red obtener sustituciones de -él. Esto significa que cualquier máquina que ejecute Guix puede actuar como -si fuese una granja de construcción, ya que la interfaz HTTP es compatible -con Hydra, el software detrás de la granja de construcción -@code{@value{SUBSTITUTE-SERVER}}. - -Por seguridad, cada sustitución se firma, permitiendo a las receptoras -comprobar su autenticidad e integridad (@pxref{Sustituciones}). Debido a que -@command{guix publish} usa la clave de firma del sistema, que es únicamente -legible por la administradora del sistema, debe iniciarse como root; la -opción @code{--user} hace que renuncie a sus privilegios tan pronto como sea -posible. - -El par claves de firma debe generarse antes de ejecutar @command{guix -publish}, usando @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). - -La sintaxis general es: - -@example -guix publish @var{opciones}@dots{} -@end example - -La ejecución de @command{guix publish} sin ningún parámetro adicional -lanzará un servidor HTTP en el puerto 8080: - -@example -guix publish -@end example - -Una vez el servidor de publicación ha sido autorizado (@pxref{Invocación de guix archive}), el daemon puede descargar sustituciones de él: - -@example -guix-daemon --substitute-urls=http://example.org:8080 -@end example - -Por defecto, @command{guix publish} comprime los archivos al vuelo cuando es -necesario. Este modo ``al vuelo'' es conveniente ya que no necesita -configuración y está disponible inmediatamente. No obstante, cuando se -proporciona servicio a muchos clientes, se recomienda usar la opción -@option{--cache}, que habilita el almacenamiento en caché de los archivos -antes de enviarlos a los clientes---véase a continuación para más -detalles. La orden @command{guix weather} proporciona una forma fácil de -comprobar lo que proporciona un servidor (@pxref{Invocación de guix weather}). - -Además @command{guix publish} también sirve como un espejo de acceso por -contenido a ficheros de fuentes a los que los registros @code{origin} hacen -referencia (@pxref{Referencia de ``origin''}). Por ejemplo, si asumimos que -@command{guix publish} se ejecuta en @code{example.org}, la siguiente URL -devuelve directamente el fichero @file{hello-2.10.tar.gz} con el hash SHA256 -proporcionado (representado en formato @code{nix-base32}, @pxref{Invocación de guix hash}). - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -Obviamente estas URL funcionan solamente para ficheros que se encuentran en -el almacén; en otros casos devuelven un 404 (``No encontrado''). - -@cindex logs de construcción, publicación -Los log de construcción están disponibles desde URL @code{/log} como: - -@example -http://example.org/log/gwspk@dots{}-guile-2.2.3 -@end example - -@noindent -Cuando @command{guix-daemon} está configurado para almacenar comprimidos los -log de construcción, como sucede de forma predeterminada (@pxref{Invocación de guix-daemon}), las URL @code{/log} devuelven los log igualmente comprimidos, -con un @code{Content-Type} adecuado y/o una cabecera -@code{Content-Encoding}. Recomendamos ejecutar @command{guix-daemon} con -@code{--log-compression=gzip} ya que los navegadores Web pueden extraer el -contenido automáticamente, lo cual no es el caso con la compresión bzip2. - -Las siguientes opciones están disponibles: - -@table @code -@item --port=@var{puerto} -@itemx -p @var{puerto} -Escucha peticiones HTTP en @var{puerto}. - -@item --listen=@var{dirección} -Escucha en la interfaz de red de la @var{dirección}. El comportamiento -predeterminado es aceptar conexiones de cualquier interfaz. - -@item --user=@var{usuaria} -@itemx -u @var{usuaria} -Cambia los privilegios a los de @var{usuaria} tan pronto como sea -posible---es decir, una vez el socket del servidor esté abierto y la clave -de firma haya sido leída. - -@item --compression[=@var{nivel}] -@itemx -C [@var{nivel}] -Comprime los datos con el @var{nivel} dado. Cuando el @var{nivel} es cero, -deshabilita la compresión. El rango 1 a 9 corresponde a distintos niveles de -compresión gzip: 1 es el más rápido, y 9 es el mejor (intensivo a nivel de -CPU). El valor predeterminado es 3. - -A menos que se use @option{--cache}, la compresión ocurre al vuelo y los -flujos comprimidos no se almacenan en caché. Por tanto, para reducir la -carga en la máquina que ejecuta @command{guix publish}, puede ser una buena -idea elegir un nivel de compresión bajo, ejecutar @command{guix publish} -detrás de un proxy con caché o usar @option{--cache}. El uso de -@option{--cache} tiene la ventaja de que permite a @command{guix publish} -añadir la cabecera HTTP @code{Content-Length} a sus respuestas. - -@item --cache=@var{directorio} -@itemx -c @var{directorio} -Almacena en caché los archivos y metadatos (URL @code{.narinfo}) en -@var{directorio} y únicamente proporciona archivos que están en la caché. - -Cuando se omite esta opción, los archivos y metadatos se crean al -vuelo. Esto puede reducir el ancho de banda disponible, especialmente cuando -la compresión está habilitada, ya que se puede llegar al límite de la -CPU. Otra desventaja del modo predeterminado es que la longitud de los -archivos no se conoce con anterioridad, por lo que @command{guix publish} no -puede añadir la cabecera HTTP @code{Content-Length} a sus respuestas, lo que -a su vez previene que los clientes conozcan la cantidad de datos a -descargar. - -De manera contraria, cuando se usa @option{--cache}, la primera petición de -un elemento del almacén (a través de una URL @code{.narinfo}) devuelve 404 e -inicia un proceso en segundo plano para @dfn{cocinar} el archivo---calcular -su @code{.narinfo} y comprimirlo, en caso necesario. Una vez el archivo está -alojado en la caché de @var{directorio}, las siguientes peticiones obtendrán -un resultado satisfactorio y se ofrecerá el contenido directamente desde la -caché, lo que garantiza que los clientes obtienen el mejor ancho de banda -posible. - -El proceso de ``cocinado'' se realiza por hilos de trabajo. Por defecto, se -crea un hilo por núcleo de la CPU, pero puede ser personalizado. Véase -@option{--workers} a continuación. - -Cuando se usa @option{--ttl}, las entradas en caché se borran -automáticamente cuando hayan expirado. - -@item --workers=@var{N} -Cuando se usa @option{--cache}, solicita la creación de @var{N} hilos de -trabajo para ``cocinar'' archivos. - -@item --ttl=@var{ttl} -Produce cabeceras HTTP @code{Cache-Control} que anuncian un tiempo-de-vida -(TTL) de @var{ttl}. @var{ttl} debe indicar una duración: @code{5d} significa -5 días, @code{1m} significa un mes, etc. - -Esto permite a la usuaria de Guix mantener información de sustituciones en -la caché durante @var{ttl}. No obstante, fíjese que @code{guix publish} no -garantiza en sí que los elementos del almacén que proporciona de hecho -permanezcan disponibles hasta que @var{ttl} expire. - -Adicionalmente, cuando se usa @option{--cache}, las entradas en caché que no -hayan sido accedidas en @var{ttl} y no tengan un elemento correspondiente en -el almacén pueden ser borradas. - -@item --nar-path=@var{ruta} -Usa @var{ruta} como el prefijo para las URL de los archivos ``nar'' -(@pxref{Invocación de guix archive, archivadores normalizados}). - -Por defecto, los archivos nar se proporcionan en una URL como -@code{/nar/gzip/@dots{}-coreutils-8.25}. Esta opción le permite cambiar la -parte @code{/nar} por @var{ruta}. - -@item --public-key=@var{fichero} -@itemx --private-key=@var{fichero} -Usa los @var{fichero}s específicos como el par de claves pública y privada -usadas para firmar los elementos del almacén publicados. - -Los ficheros deben corresponder al mismo par de claves (la clave privada se -usa para la firma y la clave pública simplemente se anuncia en los metadatos -de la firma). Deben contener claves en el formato canónico de expresiones-S -como el producido por @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). Por defecto, se usan @file{/etc/guix/signing-key.pub} y -@file{/etc/guix/signing-key.sec}. - -@item --repl[=@var{puerto}] -@itemx -r [@var{puerto}] -Lanza un servidor REPL Guile (@pxref{REPL Servers,,, guile, GNU Guile -Reference Manual}) en @var{puerto} (37146 por defecto). Esto se usa -principalmente para la depuración de un servidor @command{guix publish} en -ejecución. -@end table - -Habilitar @command{guix publish} en el sistema Guix consiste en solo una -línea: simplemente instancie un servicio @code{guix-publish-service-type} en -el campo @code{services} de su declaración del sistema operativo -@code{operating-system} (@pxref{guix-publish-service-type, -@code{guix-publish-service-type}}) - -Si en vez de eso ejecuta Guix en una distribución distinta, siga estas -instrucciones: - -@itemize -@item -Si su distribución anfitriona usa el sistema de inicio systemd: - -@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 -Si su distribución anfitriona usa el sistema de inicio Upstart: - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -En otro caso, proceda de forma similar con el sistema de inicio de su -distribución. -@end itemize - -@node Invocación de guix challenge -@section Invocación de @command{guix challenge} - -@cindex construcciones reproducibles -@cindex construcciones verificables -@cindex @command{guix challenge} -@cindex reto (challenge) -¿Los binarios que proporciona este servidor realmente corresponden al código -fuente que dice construir? ¿Es determinista el proceso de construcción de un -paquete? Estas son las preguntas que la orden @command{guix challenge} -intenta responder. - -La primera es obviamente una cuestión importante: antes de usar un servidor -de sustituciones (@pxref{Sustituciones}), es importante haber -@emph{verificado} que proporciona los binarios correctos, y por tanto -@emph{ponerlo a prueba}@footnote{NdT: challenge en inglés.}. La segunda es -lo que permite la primera: si las construcciones de los paquetes son -deterministas, construcciones independientes deberían emitir el mismo -resultado, bit a bit; si el servidor proporciona un binario diferente al -obtenido localmente, o bien está corrupto o bien tiene intenciones -perniciosas. - -Sabemos que el hash que se muestra en los nombres de fichero en -@file{/gnu/store} es el hash de todas las entradas del proceso que construyó -el fichero o directorio---compiladores, bibliotecas, guiones de -construcción, etc. (@pxref{Introducción}). Asumiendo procesos de -construcción deterministas, un nombre de fichero del almacén debe -corresponder exactamente a una salida de construcción. @command{guix -challenge} comprueba si existe, realmente, una asociación unívoca comparando -la salida de la construcción de varias construcciones independientes de -cualquier elemento del almacén proporcionado. - -La salida de la orden muestra algo así: - -@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 -En este ejemplo, @command{guix challenge} primero recorre el almacén para -determinar el conjunto de derivaciones construidas localmente---en oposición -a elementos del almacén que fueron descargados de un servidor de -sustituciones---y consulta a todos los servidores de sustituciones. Una vez -hecho informa de los elementos del almacén para los cuales los servidores -obtuvieron un resultado diferente de el obtenido en la construcción local. - -@cindex no-determinismo, en la construcción de paquetes -Como un ejemplo, @code{guix.example.org} siempre obtiene una respuesta -diferente. Por otro modo, @code{@value{SUBSTITUTE-SERVER}} coincide con las -construcciones locales, excepto en el caso de Git. Esto puede indicar que el -proceso de construcción de Git no es determinista, lo que significa que su -salida varia en función de varias cosas que Guix no controla completamente, -aunque la construcción de paquetes se realice en entornos aislados -(@pxref{Características}). Las fuentes más comunes de indeterminismo incluyen la -adición de marcas de tiempo en los resultados de la construcción, la -inclusión de números aleatorios y las enumeraciones de directorios ordenadas -por número de nodos-i. Véase @uref{https://reproducible-builds.org/docs/} -para más información. - -Para encontrar cuál es el problema con este binario Git, podemos hacer algo -parecido a esto (@pxref{Invocación de 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 - -Esta orden muestra la diferencia entre los ficheros resultantes de la -construcción local y los ficheros resultantes de la construcción en -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging -Files,, diffutils, Comparing and Merging Files}). La orden @command{diff} -funciona muy bien en ficheros de texto. Cuando ficheros binarios difieren, -una opción mejor es @uref{https://diffoscope.org/,Diffoscope}, una -herramienta que ayuda en la visualización de diferencias en todo tipo de -ficheros. - -Una vez haya realizado este trabajo, puede determinar si las diferencias son -debidas a un procedimiento de construcción no-determinista o a un servidor -con intenciones ocultas. Intentamos duramente eliminar las fuentes de -indeterminismo en los paquetes para facilitar la verificación de -sustituciones, pero por supuesto es un proceso que implica no solo a Guix, -sino a una gran parte de la comunidad del software libre. Entre tanto, -@command{guix challenge} es una herramienta para ayudar a afrontar el -problema. - -Si esta escribiendo paquetes para Guix, le recomendamos que compruebe si -@code{@value{SUBSTITUTE-SERVER}} y otros servidores de sustituciones -obtienen el mismo resultado de construcción que el obtenido por usted: - -@example -$ guix challenge @var{paquete} -@end example - -@noindent -donde @var{paquete} es una especificación de paquete como @code{guile@@2.0} -o @code{glibc:debug}. - -La sintaxis general es: - -@example -guix challenge @var{opciones} [@var{paquetes}@dots{}] -@end example - -Cuando se encuentra una diferencia entre el hash de un elemento construido -localmente y el proporcionado por un servidor de sustituciones; o entre las -sustituciones proporcionadas por distintos servidores, esto es mostrado como -en el ejemplo previo y el valor de salida es 2 (otros valores no-cero de la -salida denominan otros tipos de error). - -La única opción de importancia es: - -@table @code - -@item --substitute-urls=@var{urls} -Considera @var{urls} la lista separada por espacios de URL de fuentes de -sustituciones con las que realizar la comparación. - -@item --verbose -@itemx -v -Muestra detalles sobre coincidencias (contenidos idénticos) además de -información sobre las discrepancias. - -@end table - -@node Invocación de guix copy -@section Invocación de @command{guix copy} - -@cindex copiar, elementos del almacén, por SSH -@cindex SSH, copiar elementos del almacén -@cindex compartir elementos del almacén entre máquinas -@cindex transferir elementos del almacén entre máquinas -La orden @command{guix copy} copia elementos del almacén de una máquina al -de otra a través de una conexión de shell seguro (SSH)@footnote{Esta orden -únicamente está disponible cuando ha encontrado -Guile-SSH. @xref{Requisitos}, para detalles.}. Por ejemplo, la siguiente -orden copia el paquete @code{coreutils}, el perfil de la usuaria y todas sus -dependencias a @var{dirección}, ingresando en el sistema como @var{usuaria}: - -@example -guix copy --to=@var{usuaria}@@@var{dirección} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -Si alguno de los elementos del almacén a copiar ya están presentes en -@var{dirección}, no se envían realmente. - -La siguiente orden obtiene @code{libreoffice} y @code{gimp} de -@var{dirección}, asumiendo que estén disponibles allí: - -@example -guix copy --from=@var{dirección} libreoffice gimp -@end example - -La conexión SSH se establece usando el cliente Guile-SSH, que es compatible -con OpenSSH: tiene en cuenta @file{~/.ssh/known_hosts} y -@file{~/.ssh/config}, y usa el agente SSH para la identificación. - -La clave usada para firmar los elementos enviados debe estar aceptada por la -máquina remota. Del mismo modo, la clave usada por la máquina remota para -firmar los elementos recibidos debe estar en @file{/etc/guix/acl} de modo -que sea aceptada por su propio daemon. @xref{Invocación de guix archive}, para -más información sobre la verificación de elementos del almacén. - -La sintaxis general es: - -@example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{elementos}@dots{} -@end example - -Siempre debe especificar una de las siguientes opciones: - -@table @code -@item --to=@var{spec} -@itemx --from=@var{spec} -Especifica la máquina a la que mandar o desde la que recibir. @var{spec} -debe ser una especificación SSH como @code{example.org}, -@code{carlos@@example.org}, or @code{carlos@@example.org:2222}. -@end table - -Los @var{elementos} pueden ser tanto nombres de paquetes, como @code{gimp}, -como elementos del almacén, como @file{/gnu/store/@dots{}-idutils-4.6}. - -Cuando se especifica el nombre del paquete a enviar, primero se construye si -es necesario, a menos que se use @option{--dry-run}. Se aceptan las opciones -comunes de construcción (@pxref{Opciones comunes de construcción}). - - -@node Invocación de guix container -@section Invocación de @command{guix container} -@cindex container -@cindex @command{guix container} -@quotation Nota -En la versión @value{VERSION}, esta herramienta es experimental. La interfaz -está sujeta a cambios radicales en el futuro. -@end quotation - -El propósito de @command{guix container} es la manipulación de procesos en -ejecución dentro de entornos aislados, normalmente conocido como un -``contenedor'', típicamente creado por las órdenes @command{guix -environment} (@pxref{Invocación de guix environment}) y @command{guix system -container} (@pxref{Invocación de guix system}). - -La sintaxis general es: - -@example -guix container @var{acción} @var{opciones}@dots{} -@end example - -@var{acción} especifica la operación a realizar con el contenedor, y -@var{opcines} especifica los parámetros específicos del contexto para la -acción. - -Las siguientes acciones están disponibles: - -@table @code -@item exec -Ejecute una orden en el contexto de un contenedor en ejecución. - -La sintaxis es: - -@example -guix container exec @var{pid} @var{programa} @var{parámetros}@dots{} -@end example - -@var{pid} especifica el ID del proceso del contenedor en -ejecución. @var{programa} especifica el nombre del fichero ejecutable dentro -del sistema de ficheros raíz del contenedor. @var{parámetros} son opciones -adicionales que se pasarán a @var{programa}. - -La siguiente orden lanza un shell interactivo de ingreso al sistema dentro -de un contenedor del sistema, iniciado por @command{guix system container}, -y cuyo ID de proceso es 9001: - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Fíjese que el @var{pid} no puede ser el proceso creador del contenedor. Debe -ser el PID 1 del contenedor o uno de sus procesos hijos. - -@end table - -@node Invocación de guix weather -@section Invocación de @command{guix weather} - -De manera ocasional tendrá un mal día al no estar las sustituciones -disponibles y le toque construir los paquetes a usted misma -(@pxref{Sustituciones}). La orden @command{guix weather} informa de la -disponibilidad de sustituciones en los servidores especificados de modo que -pueda tener una idea sobre cómo será su día hoy. A veces puede ser una -información útil como usuaria, pero es principalmente útil para quienes -ejecuten @command{guix publish} (@pxref{Invocación de guix publish}). - -@cindex estadísticas, para sustituciones -@cindex disponibilidad de sustituciones -@cindex disponibilidad de sustituciones -@cindex weather, disponibilidad de sustituciones -Esta es una ejecución de ejemplo: - -@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 integración continua, estadísticas -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). - -Para conseguirlo, @command{guix weather} consulta los metadatos HTTP(S) -(@dfn{narinfo}s) de todos los elementos relevantes del almacén. Como -@command{guix challenge}, ignora las firmas en esas sustituciones, lo cual -es inocuo puesto que la orden únicamente obtiene estadísticas y no puede -instalar esas sustituciones. - -Entre otras cosas, es posible consultar tipos específicos de sistema y -conjuntos específicos de paquetes. Las opciones disponibles se enumeran a -continuación. - -@table @code -@item --substitute-urls=@var{urls} -@var{urls} es la lista separada por espacios de URL de servidores de -sustituciones a consultar. Cuando se omite esta opción, el conjunto -predeterminado de servidores de sustituciones es el consultado. - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Consulta sustituciones para @var{sistema}---por ejemplo, -@code{aarch64-linux}. Esta opción se puede repetir, en cuyo caso -@command{guix weather} consultará las sustituciones para varios tipos de -sistema. - -@item --manifest=@var{fichero} -En vez de consultar las sustituciones de todos los paquetes, consulta -únicamente los especificados en @var{fichero}. @var{fichero} debe contener -un @dfn{manifiesto}, como el usado en la opción @code{-m} de @command{guix -package} (@pxref{Invocación de guix package}). - -@item --coverage[=@var{numero}] -@itemx -c [@var{numero}] -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.es.info -c 10 -computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.es.info... -updating substitutes from 'https://ci.guix.es.info'... 100.0% -https://ci.guix.es.info - 64.7% substitutes available (6,047 out of 9,343) -@dots{} -2502 packages are missing from 'https://ci.guix.es.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.es.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 Invocación de guix processes -@section Invocación de @command{guix processes} - -La orden @command{guix processes} puede ser útil a desarrolladoras y -administradoras de sistemas, especialmente en máquinas multiusuaria y en -granjas de construcción: enumera las sesiones actuales (conexiones al -daemon), así como información sobre los procesos envueltos@footnote{Las -sesiones remotas, cuando @command{guix-daemon} se ha iniciado con -@option{--listen} especificando un punto de conexión TCP, @emph{no} son -enumeradas.}. A continuación puede verse un ejemplo de la información que -devuelve: - -@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 - -En este ejemplo vemos que @command{guix-daemon} tiene tres clientes: -@command{guix environment}, @command{guix publish} y la herramienta de -integración continua Cuirass; sus identificadores de proceso (PID) se -muestran en el campo @code{ClientPID}. El campo @code{SessionPID} -proporciona el PID del subproceso de @command{guix-daemon} de cada sesión en -particular. - -El campo @code{LockHeld} muestra qué elementos del almacén están bloqueados -actualmente por cada sesión, lo que corresponde a elementos del almacén en -construcción o sustitución (el campo @code{LockHeld} no se muestra cuando -@command{guix processes} no se ejecutó como root). Por último, mediante el -campo @code{ChildProcess} entendemos que esas tres construcciones están -siendo delegadas (@pxref{Configuración de delegación del daemon}). - -La salida está en formato Recutils por lo que podemos usar la útil orden -@command{recsel} para seleccionar sesiones de interés (@pxref{Selection -Expressions,,, recutils, GNU recutils manual}). Como un ejemplo, la -siguiente orden muestra la línea de órdenes y el PID del cliente que inició -la construcción de un paquete Perl: - -@example -$ sudo guix processes | \ - recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -@end example - - -@node Configuración del sistema -@chapter Configuración del sistema - -@cindex configuración del sistema -La Distribución de Sistema Guix permite un mecanismo de configuración del -sistema completo consistente. Con esto queremos decir que todos los aspectos -de la configuración global del sistema---como los servicios disponibles, la -zona horaria y la configuración de localización, las cuentas de -usuarias---se declaran en un lugar único. Dicha @dfn{configuración del -sistema} puede ser @dfn{instanciada}---es decir, hecha efectiva. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -Una de las ventajas de poner toda la configuración del sistema bajo el -control de Guix es que permite actualizaciones transaccionales del sistema, -y hace posible volver a una instanciación previa del sistema, en caso de que -haya algún problema con la nueva (@pxref{Características}). Otra ventaja es que -hace fácil replicar exactamente la misma configuración entre máquinas -diferentes, o en diferentes momentos, sin tener que utilizar herramientas de -administración adicionales sobre las propias herramientas del sistema. - -Esta sección describe este mecanismo. Primero nos enfocaremos en el punto de -vista de la administradora del sistema---explicando cómo se configura e -instancia el sistema. Después mostraremos cómo puede extenderse este -mecanismo, por ejemplo para añadir nuevos servicios del sistema. - -@menu -* Uso de la configuración del sistema:: Personalizar su sistema GNU. -* Referencia de ``operating-system'':: Detalle de las declaraciones de - sistema operativo. -* Sistemas de ficheros:: Configurar el montaje de sistemas de ficheros. -* Dispositivos traducidos:: Procesamiento extra de dispositivos de bloques. -* Cuentas de usuaria:: Especificar las cuentas de usuaria. -* Distribución de teclado:: Cómo interpreta el sistema las pulsaciones - del teclado. -* Localizaciones:: Configuración de idioma y convenciones - culturales. -* Servicios:: Especificar los servicios del sistema. -* Programas con setuid:: Programas que se ejecutan con privilegios de - root. -* Certificados X.509:: Verificar servidores HTTPS. -* Selector de servicios de nombres:: Configurar el selector de servicios de - nombres de libc. -* Disco en RAM inicial:: Arranque de Linux-Libre. -* Configuración del gestor de arranque:: Configurar el gestor de arranque. -* Invocación de guix system:: Instanciar una configuración del sistema. -* Ejecutar Guix en una máquina virtual:: Cómo ejecutar el sistema Guix en - una máquina virtual. -* Definición de servicios:: Añadir nuevas definiciones de servicios. -@end menu - -@node Uso de la configuración del sistema -@section Uso de la configuración del sistema - -El sistema operativo se configura proporcionando una declaración -@code{operating-system} en un fichero que pueda ser proporcionado a la orden -@command{guix system} (@pxref{Invocación de guix system}). Una configuración -simple, con los servicios predeterminados del sistema, el núcleo Linux-Libre -predeterminado, un disco de RAM inicial y un cargador de arranque puede ser -como sigue: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -Este ejemplo debería ser auto-descriptivo. Algunos de los campos definidos -anteriormente, como @code{host-name} y @code{bootloader}, son -necesarios. Otros como @code{packages} y @code{services}, pueden omitirse, -en cuyo caso obtienen un valor por defecto. - -Más adelante se muestran los efectos de algunos de los campos más -importantes (@pxref{Referencia de ``operating-system''}, para detalles acerca de -todos los campos disponibles), y cómo @dfn{instanciar} el sistema operativo -usando @command{guix system}. - -@unnumberedsubsec Cargador de arranque - -@cindex arranque obsoleto, en máquinas Intel -@cindex arranque por BIOS, en máquinas Intel -@cindex arranque UEFI -@cindex arranque EFI -El campo @code{bootloader} describe el método que será usado para arrancar -su sistema. Las máquinas basadas en procesadores Intel pueden arrancar en el -``obsoleto'' modo BIOS, como en el ejemplo previo. No obstante, máquinas más -recientes usan la @dfn{Interfaz Unificada Extensible de Firmware} (UEFI) -para arrancar. En ese caso, el capo @code{bootloader} debe contener algo -parecido a esto: - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -@xref{Configuración del gestor de arranque}, para más información sobre las opciones de -configuración disponibles. - -@unnumberedsubsec Paquetes visibles globalmente - -@vindex %base-packages -El campo @code{packages} enumera los paquetes que serán visibles globalmente -en el sistema, para todas las cuentas de usuaria---es decir, en la variable -de entorno @code{PATH} de cada usuaria---además de los perfiles por usuaria -(@pxref{Invocación de guix package}). La variable @var{%base-packages} -proporciona todas las herramientas esperadas para tareas básicas y de -administración---incluyendo las utilidades básicas GNU, las herramientas de -red GNU, el editor de texto ligero GNU Zile, @command{find}, @command{grep}, -etc. El ejemplo previo se añade GNU@tie{}Screen a estos, tomado del módulo -@code{(gnu packages screen)} (@pxref{Módulos de paquetes}). La sintaxis -@code{(list package output)} puede usarse para añadir una salida específica -de un paquete: - -@lisp -(use-modules (gnu packages)) -(use-modules (gnu packages dns)) - -(operating-system - ;; ... - (packages (cons (list bind "utils") - %base-packages))) -@end lisp - -@findex specification->package -Referirse a los paquetes por nombre de variable, como antes a @code{bind}, -tiene la ventaja de evitar ambigüedades; también permite que errores -tipográficos y demás obtengan un diagnóstico directo como ``variables sin -definir''. La parte problemática es que se necesita conocer qué módulo -define qué paquete, y aumentar adecuadamente la línea de -@code{use-package-modules}. Para evitar esto, se puede usar el procedimiento -@code{specification->package} del módulo @code{(gnu packages)}, que devuelve -el mejor paquete para un nombre dado, o nombre y versión: - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec Servicios del sistema - -@cindex services -@vindex %base-services -The @code{services} field lists @dfn{system services} to be made available -when the system starts (@pxref{Servicios}). 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{Servicios de red, @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{Definición de servicios}). - -@cindex personalización, de servicios -@findex modify-services -De manera ocasional, en vez de usar los servicios básicos tal y como vienen, -puede querer personalizarlos. Para hacerlo, use @code{modify-services} -(@pxref{Referencia de servicios, @code{modify-services}}) para modificar la lista. - -Por ejemplo, supongamos que quiere modificar @code{guix-daemon} y Mingetty -(el punto de acceso al sistema por consola) en la lista @var{%base-services} -(@pxref{Servicios base, @code{%base-services}}). Para hacerlo, puede escribir -lo siguiente en su declaración de sistema operativo: - -@lisp -(define %mis-servicios - ;; Mi propia lista de servicios - (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 %mis-servicios)) -@end lisp - -Esto modifica la configuración---es decir, los parámetros de los -servicios---de la instancia @code{guix-service-type}, y de todas las -instancias de @code{mingetty-service-type} en la lista -@var{%base-services}. Observe cómo se consigue: primero, enlazamos la -configuración actual al identificador @code{config} en el @var{cuerpo}, y -entonces escribimos el @var{cuerpo} de manera que evalue a la configuración -deseada. En particular, fíjese como se usa @code{inherit} para crear una -nueva configuración que tiene los mismos valores que la configuración -antigua, pero con unas pocas modificaciones. - -@cindex disco cifrado -La configuración para un uso típico de ``escritorio'', con una partición de -raíz cifrada, el servidor gráfico X11, GNOME y Xfce (las usuarias pueden -escoger cual de estos entornos de escritorio usarán en la pantalla de inicio -de sesión pulsando @kbd{F1}), gestión de red, gestión de energía y más, -podría ser así: - -@lisp -@include os-config-desktop.texi -@end lisp - -Un sistema gráfico con una selección de gestores de ventanas ligeros en vez -de entornos de escritorio completos podría ser así: - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -Este ejemplo se refiere al sistema de ficheros @file{/boot/efi} por su UUID -@code{1234-ABCD}. Substituya este UUID con el UUID correcto en su sistema, -como el devuelto por la orden @command{blkid}. - -@xref{Servicios de escritorio}, para la lista exacta de servicios proporcionados -por @var{%desktop-services}. @xref{Certificados X.509}, para información -sobre el paquete @code{nss-certs} usado aquí. - -De nuevo, @var{%desktop-services} es simplemente una lista de objetos de -servicios. Si desea borrar servicios de aquí, puede hacerlo usando -procedimientos de filtrado de listas (@pxref{SRFI-1 Filtering and -Partitioning,,, guile, GNU Guile Reference Manual}). Por ejemplo, la -siguiente expresión devuelve una lista que contiene todos los servicios en -@var{%desktop-services} excepto el servicio Avahi: - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Instanciación del sistema - -Asumiendo que la declaración de @code{operating-system} se encuentra en el -fichero @file{my-conf-del-sistema.scm}, la orden @command{guix system -mi-conf-del-sistema.scm} instancia esa configuración, y la convierte en la -entrada predeterminada de GRUB en el arranque (@pxref{Invocación de guix system}). - -La manera habitual de cambiar la configuración del sistema es actualizar -este fichero y volver a ejecutar @command{guix system reconfigure}. Nunca se -deberían tocar los ficheros en @file{/etc} o ejecutar órdenes que modifiquen -el estado del sistema como @command{useradd} o @command{grub-install}. De -hecho, debe evitarlo ya que no únicamente anularía su garantía sino que -también le impediría volver a una versión previa de su sistema, en caso de -necesitarlo. - -@cindex vuelta-atrás, del sistema operativo -Hablando de vuelta atrás, cada vez que ejecuta @command{guix system -reconfigure} se crea una nueva @dfn{generación} del sistema---sin modificar -o borrar generaciones previas. Las generaciones previas tienen una entrada -en el menú del cargador de arranque, permitiendole arrancarlas en caso de -que algo funcionase mal en las últimas generaciones. Tranquilizador, ¿no? La -orden @command{guix system list-generations} enumera las generaciones del -sistema disponibles en el disco. Es también posible volver a una versión -previa con las órdenes @command{guix system roll-back} y @command{guix -system switch-generation}. - -Aunque la orden @command{guix system reconfigure} no modificará las -generaciones previas, debe tener cuidado cuando la generación actual no es -la última (por ejemplo, después de invocar @command{guix system roll-back}), -ya que la operación puede sobreescribir una generación posterior -(@pxref{Invocación de guix system}). - -@unnumberedsubsec La interfaz programática - -A nivel Scheme, el grueso de una declaración @code{operating-system} se -instancia con el siguiente procedimiento monádico (@pxref{La mónada del almacén}): - -@deffn {Procedimiento monádico} operating-system-derivation so -Devuelve una derivación que construye @var{so}, un objeto -@code{operating-system} (@pxref{Derivaciones}). - -La salida de la derivación es un único directorio que hace referencia a -todos los paquetes, ficheros de configuración y otros ficheros auxiliares -necesarios para instanciar @var{so}. -@end deffn - -This procedure is provided by the @code{(gnu system)} module. Along with -@code{(gnu services)} (@pxref{Servicios}), this module contains the guts of -Guix System. Make sure to visit it! - - -@node Referencia de ``operating-system'' -@section Referencia de @code{operating-system} - -Esta sección resume todas las opciones disponibles en las declaraciones de -@code{operating-system} (@pxref{Uso de la configuración del sistema}). - -@deftp {Tipo de datos} operating-system -Este es el tipo de datos que representa la configuración del sistema -operativo. Con ello queremos decir toda la configuración global del sistema, -no la configuración específica de las usuarias (@pxref{Uso de la configuración del sistema}). - -@table @asis -@item @code{kernel} (predeterminado: @code{linux-libre}) -El objeto del paquete del núcleo del sistema operativo -usado@footnote{Actualmente únicamente está disponible el núcleo -Linux-libre. En el futuro será posible usar GNU@tie{}Hurd.}. - -@item @code{kernel-arguments} (default: @code{'("quiet")}) -Lista de cadenas o expresiones-G que representan parámetros adicionales a -pasar en la línea de órdenes del núcleo---por ejemplo, -@code{("console=ttyS0")}. - -@item @code{bootloader} -El objeto de configuración del cargador de arranque del -sistema. @xref{Configuración del gestor de arranque}. - -@item @code{label} -This is the label (a string) as it appears in the bootloader's menu entry. -The default label includes the kernel name and version. - -@item @code{keyboard-layout} (predeterminada: @code{#f}) -This field specifies the keyboard layout to use in the console. It can be -either @code{#f}, in which case the default keyboard layout is used (usually -US English), or a @code{} record. - -This keyboard layout is in effect as soon as the kernel has booted. For -instance, it is the keyboard layout in effect when you type a passphrase if -your root file system is on a @code{luks-device-mapping} mapped device -(@pxref{Dispositivos traducidos}). - -@quotation Nota -This does @emph{not} specify the keyboard layout used by the bootloader, nor -that used by the graphical display server. @xref{Configuración del gestor de arranque}, -for information on how to specify the bootloader's keyboard layout. @xref{Sistema X Window}, for information on how to specify the keyboard layout used by the X -Window System. -@end quotation - -@item @code{initrd-modules} (predeterminados: @code{%base-initrd-modules}) -@cindex initrd -@cindex disco inicial de RAM -La lista de módulos del núcleo Linux que deben estar disponibles en el disco -inicial de RAM. @xref{Disco en RAM inicial}. - -@item @code{initrd} (predeterminado: @code{base-initrd}) -Un procedimiento que devuelve un disco inicial de RAM para el núcleo -Linux. Este campo se proporciona para permitir personalizaciones de bajo -nivel y no debería ser necesario para un uso habitual. @xref{Disco en RAM inicial}. - -@item @code{firmware} (predeterminado: @code{%base-firmware}) -@cindex firmware -Lista de paquetes de firmware que pueden ser cargados por el núcleo del -sistema operativo. - -El valor predeterminado incluye el firmware necesario para dispositivos WiFi -basados en Atheros y Broadcom (módulos Linux-libre @code{ath9k} y -@code{b43-open}, respectivamente). @xref{Consideraciones sobre el hardware}, para más -información sobre hardware soportado. - -@item @code{host-name} -El nombre de la máquina. - -@item @code{hosts-file} -@cindex el fichero hosts -Un objeto tipo-fichero (@pxref{Expresiones-G, objetos tipo-fichero}) para -ser usado como @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C -Library Reference Manual}). El predeterminado es un fichero con entradas -para @code{localhost} y @var{host-name}. - -@item @code{mapped-devices} (predeterminados: @code{'()}) -Una lista de dispositivos traducidos. @xref{Dispositivos traducidos}. - -@item @code{file-systems} -Una lista de sistemas de ficheros. @xref{Sistemas de ficheros}. - -@item @code{swap-devices} (predeterminados: @code{'()}) -@cindex dispositivos de intercambio -Una lista de cadenas que identifiquen dispositivos o ficheros a usar como -``espacio de intercambio'' (@pxref{Memory Concepts,,, libc, The GNU C -Library Reference Manual}). Por ejemplo @code{'("/dev/sda3")} o -@code{'("/fichero-intercambio")}. Es posible especificar un fichero de -intercambio en un sistema de ficheros en un dispositivo traducido, siempre -que la traducción y el sistema de ficheros se especifiquen -también. @xref{Dispositivos traducidos} y @ref{Sistemas de ficheros}. - -@item @code{users} (predeterminadas: @code{%base-user-accounts}) -@itemx @code{groups} (predeterminados: @var{%base-groups}) -Lista de cuentas de usuaria y grupos. @xref{Cuentas de usuaria}. - -Si la lista de @code{usuarias} carece de una cuenta de usuaria con -UID@tie{}0, una cuenta ``root'' con UID@tie{}0 se añade automáticamente. - -@item @code{skeletons} (predeterminados: @code{(default-skeletons)}) -Una lista de tuplas de nombre de fichero de destino/objeto tipo-fichero -(@pxref{Expresiones-G, objetos tipo-fichero}). Estos son los ficheros de -esqueleto que se añadirán al directorio de las cuentas de usuaria que se -creen. - -Por ejemplo, un valor válido puede parecer algo así: - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hola\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (predeterminado: @var{%default-issue}) -Una cadena que denota el contenido del fichero @file{/etc/issue}, que se -muestra cuando las usuarias ingresan al sistema en una consola de texto. - -@item @code{packages} (predeterminados: @var{%base-packages}) -El conjunto de paquetes instalados en el perfil global, que es accesible en -@file{/run/current-system/profile}. - -El conjunto predeterminado incluye utilidades básicas y es una buena -práctica instalar utilidades no-básicas en los perfiles de las usuarias -(@pxref{Invocación de guix package}). - -@item @code{timezone} -Una cadena que identifica la zona horaria---por ejemplo, -@code{"Europe/Paris"}. - -Puede ejecutar la orden @command{tzselect} para encontrar qué cadena de zona -horaria corresponde con su región. Elegir una zona horaria no válida provoca -un fallo en @command{guix system}. - -@item @code{locale} (predeterminado: @code{"en_US.utf8"}) -El nombre de la localización predeterminada (@pxref{Locale Names,,, libc, -The GNU C Library Reference Manual}). @xref{Localizaciones}, para más información. - -@item @code{locale-definitions} (predeterminadas: @var{%default-locale-definitions}) -La lista de definiciones de localizaciones a compilar y que puede ser usada -en tiempo de ejecución. @xref{Localizaciones}. - -@item @code{locale-libcs} (predeterminadas: @code{(list @var{glibc})}) -La lista de paquetes GNU@tie{}libc cuyos datos de localización y -herramientas son usadas para las definiciones de -localizaciones. @xref{Localizaciones}, para consideraciones de compatibilidad que -justifican esta opción. - -@item @code{name-service-switch} (predeterminado: @var{%default-nss}) -Configuración del selector de servicios de nombres de libc (NSS)---un objeto -@code{}. @xref{Selector de servicios de nombres}, para detalles. - -@item considera -Una lista de objetos service denotando los servicios del -sistema. @xref{Servicios}. - -@cindex servicios esenciales -@item @code{essential-services} (predeterminados: ...) -The list of ``essential services''---i.e., things like instances of -@code{system-service-type} and @code{host-name-service-type} (@pxref{Referencia de servicios}), which are derived from the operating system definition itself. -As a user you should @emph{never} need to touch this field. - -@item @code{pam-services} (predeterminados: @code{(base-pam-services)}) -@cindex PAM -@cindex módulos de verificación conectables -@c FIXME: Add xref to PAM services section. -Servicios de los @dfn{módulos de verificación conectables} (PAM) de Linux. - -@item @code{setuid-programs} (predeterminados: @var{%setuid-programs}) -Lista de expresiones-G con valores de cadena que denotan los programas -setuid. @xref{Programas con setuid}. - -@item @code{sudoers-file} (predeterminado: @var{%sudoers-specification}) -@cindex fichero sudoers -El contenido de @file{/etc/sudoers} como un objeto tipo-fichero -(@pxref{Expresiones-G, @code{local-file} y @code{plain-file}}). - -Este fichero especifica qué usuarias pueden usar la orden @command{sudo}, lo -que se les permite hacer y qué privilegios pueden obtener. El comportamiento -predefinido es que únicamente @code{root} y los miembros del grupo -@code{wheel} pueden usar @code{sudo}. - -@end table - -@deffn {Scheme Syntax} this-operating-system -When used in the @emph{lexical scope} of an operating system field -definition, this identifier resolves to the operating system being defined. - -The example below shows how to refer to the operating system being defined -in the definition of the @code{label} field: - -@example -(use-modules (gnu) (guix)) - -(operating-system - ;; ... - (label (package-full-name - (operating-system-kernel this-operating-system)))) -@end example - -It is an error to refer to @code{this-operating-system} outside an operating -system definition. -@end deffn - -@end deftp - -@node Sistemas de ficheros -@section Sistemas de ficheros - -La lista de sistemas de ficheros que deben montarse se especifica en el -campo @code{file-systems} de la declaración del sistema operativo -(@pxref{Uso de la configuración del sistema}). Cada sistema de ficheros se -declara usando la forma @code{file-system}, como en el siguiente ejemplo: - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -Como es habitual, algunos de los campos son obligatorios---aquellos -mostrados en el ejemplo previo---mientras que otros pueden omitirse. Se -describen a continuación. - -@deftp {Tipo de datos} file-system -Objetos de este tipo representan los sistemas de ficheros a -montar. Contienen los siguientes campos: - -@table @asis -@item @code{type} -Este campo es una cadena que especifica el tipo de sistema de ficheros---por -ejemplo, @code{"ext4"}. - -@item @code{mount-point} -Designa la ruta donde el sistema de ficheros debe montarse. - -@item @code{device} -Nombra la ``fuente'' del sistema de ficheros. Puede ser una de estas tres -opciones: una etiqueta de sistema de ficheros, un UUID de sistema de -ficheros o el nombre de un nodo @file{/dev}. Las etiquetas y UUID ofrecen -una forma de hacer referencia a sistemas de ficheros sin codificar su nombre -de dispositivo actual@footnote{Fijese que, aunque es tentador usa -@file{/dev/disk/by-uuid} y nombres de dispositivo similares para obtener el -mismo resultado, no es lo recomendado: estos nodo especiales de dispositivos -se crean por el daemon udev y puede no estar disponible cuando el -dispositivo sea montado.}. - -@findex file-system-label -Las etiquetas del sistema de ficheros se crean mediante el uso del -procedimiento @code{file-system-label}, los UUID se crean mediante el uso de -@code{uuid} y los nodos @file{/dev} son simples cadenas. A continuación se -proporciona un ejemplo de un sistema de ficheros al que se hace referencia -mediante su etiqueta, como es mostrada por la orden @command{e2label}: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "mi-home"))) -@end example - -@findex uuid -Los UUID se convierten dede su representación en forma de cadena (como se -muestra con la orden @command{tune2fs -l}) mediante el uso de la forma -@code{uuid}@footnote{La forma @code{uuid} espera un UUID de 16 bytes como se -define en la @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. Este -es el formato de UUID que usan la familia de sistemas de ficheros ext2 y -otros, pero es diferente de los ``UUID'' de los sistemas de ficheros FAT, -por ejemplo.}, como sigue: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -Cuando la fuente de un sistema de ficheros es un dispositivo traducido -(@pxref{Dispositivos traducidos}), su campo @code{device} @emph{debe} hacer -referencia al nombre del dispositivo traducido---por ejemplo, -@file{"/dev/mapper/particion-raiz"}. Esto es necesario para que el sistema -sepa que el montaje del sistema de ficheros depende del establecimiento de -la traducción de dispositivos correspondiente. - -@item @code{flags} (predeterminadas: @code{'()}) -Una lista de símbolos que denotan opciones del montaje. Las opciones -reconocidas incluyen @code{read-only} (modo de sólo lectura), -@code{bind-mount} (montaje enlazado), @code{no-dev} (prohibición del acceso -a ficheros especiales), @code{no-suid} (ignora los bits setuid y setgid) y -@code{no-exec} (prohibición de la ejecución de programas). - -@item @code{options} (predeterminadas: @code{#f}) -Esto es o bien @code{#f}, o bien una cadena que contiene opciones de -montaje. - -@item @code{mount?} (predeterminado: @code{#t}) -Este valor indica si debe montarse el sistema de ficheros automáticamente al -iniciar el sistema. Cuando se establece como @code{#f}, el sistema de -ficheros tiene una entrada en @file{/etc/fstab} (el cual es leído por la -orden @command{mount}) pero no se montará automáticamente. - -@item @code{needed-for-boot?} (predeterminado: @code{#f}) -Este valor lógico indica si el sistema de ficheros es necesario para el -arranque. Si es verdadero, el sistema de ficheros se monta al cargar el -disco inicial de RAM (initrd). Este es siempre el caso, por ejemplo, para el -sistema de ficheros raíz. - -@item @code{check?} (predeterminado: @code{#t}) -Este valor lógico indica si el sistema de ficheros se debe comprobar en -busca de errores antes de montarse. - -@item @code{create-mount-point?} (predeterminado: @code{#f}) -Cuando es verdadero, el punto de montaje es creado si no existía -previamente. - -@item @code{dependencies} (predeterminadas: @code{'()}) -Una lista de objetos @code{} o @code{} que -representan sistemas de ficheros que deben montarse o dispositivos -traducidos que deben abrirse antes (y desmontarse o cerrarse después) que el -declarado. - -Como ejemplo, considere la siguiente jerarquía de montajes: -@file{/sys/fs/cgroup} es una dependencia de @file{/sys/fs/cgroup/cpu} y -@file{/sys/fs/cgroup/memory}. - -Otro ejemplo es un sistema de ficheros que depende de un dispositivo -traducido, por ejemplo una partición cifrada (@pxref{Dispositivos traducidos}). -@end table -@end deftp - -El módulo @code{(gnu system file-systems)} exporta las siguientes variables -útiles. - -@defvr {Variable Scheme} %base-file-systems -Estos son los sistemas de ficheros esenciales que se necesitan en sistemas -normales, como @var{%pseudo-terminal-file-system} y @var{%immutable-store} -(véase a continuación). Las declaraciones de sistemas operativos deben -contener siempre estos al menos. -@end defvr - -@defvr {Variable Scheme} %pseudo-terminal-file-systems -El sistema de ficheros que debe montarse como @file{/dev/pts}. Permite la -creación de @dfn{pseudoterminales} a través de @code{openpty} y funciones -similares (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference -Manual}). Los pseudoterminales son usados por emuladores de terminales como -@command{xterm}. -@end defvr - -@defvr {Variable Scheme} %shared-memory-file-system -Este sistema de ficheros se monta como @file{/dev/shm} y se usa para -permitir el uso de memoria compartida entre procesos (@pxref{Memory-mapped -I/O, @code{shm_open},, libc, The GNU C Library Reference Manual}). -@end defvr - -@defvr {Variable Scheme} %immutable-store -Este sistema de ficheros crea un montaje enlazado (``bind-mount'') de -@file{/gnu/store}, permitiendo solo el acceso de lectura para todas las -usuarias incluyendo a @code{root}. Esto previene modificaciones accidentales -por software que se ejecuta como @code{root} o por las administradoras del -sistema. - -El daemon sí es capaz de escribir en el almacén: vuelve a montar -@file{/gnu/store} en modo lectura-escritura en su propio ``espacio de -nombres''. -@end defvr - -@defvr {Variable Scheme} %binary-format-file-system -El sistema de ficheros @code{binfmt_misc}, que permite que el manejo de -tipos de ficheros ejecutables arbitrarios se delegue al espacio de -usuaria. Necesita la carga del módulo del núcleo @code{binfmt.ko}. -@end defvr - -@defvr {Variable Scheme} %fuse-control-file-system -El sistema de ficheros @code{fusectl}, que permite a usuarias sin -privilegios montar y desmontar sistemas de ficheros de espacio de usuaria -FUSE. Necesita la carga del módulo del núcleo @code{fuse.ko}. -@end defvr - -@node Dispositivos traducidos -@section Dispositivos traducidos - -@cindex traducción de dispositivos -@cindex dispositivos traducidos -El núcleo Linux tiene una noción de @dfn{traducción de dispositivos}: un -dispositivo de bloques, como una partición de disco duro, puede -@dfn{traducirse} en otro dispositivo, habitualmente en @code{/dev/mapper/}, -con un procesamiento adicional sobre los datos que fluyen a través de -ella@footnote{Fíjese que GNU@tie{}Hurd no diferencia entre el concepto de un -``dispositivo traducido'' y el de un sistema de ficheros: ambos se reducen a -@emph{traducir} operaciones de entrada/salida realizadas en un fichero a -operaciones en su almacenamiento subyacente. Por tanto, Hurd implementa -dispositivos traducidos, como sistemas de ficheros, usando el mecanismo -genérico de @dfn{traducción} (@pxref{Translators,,, hurd, The GNU Hurd -Reference Manual}).}. Un ejemplo típico es la traducción de dispositivos -para el cifrado: todas las escrituras en el dispositivo traducido se cifran, -y todas las lecturas se descifran, de forma transparente. Guix extiende esta -noción considerando cualquier dispositivo o conjunto de dispositivos que son -@dfn{transformados} de alguna manera para crear un nuevo dispositivo; por -ejemplo, los dispositivos RAID se obtienen @dfn{ensamblando} otros -dispositivos, como discos duros o particiones, en uno nuevo que se comporta -como una partición. Otros ejemplos, todavía no implementados, son los -volúmenes lógicos LVM. - -Los dispositivos traducidos se declaran mediante el uso de la forma -@code{mapped-device}, definida a continuación; ejemplos más adelante. - -@deftp {Tipo de datos} mapped-device -Objetos de este tipo representan traducciones de dispositivo que se llevarán -a cabo cuando el sistema arranque. - -@table @code -@item source -Puede ser tanto una cadena que especifica el nombre de un dispositivo de -bloques a traducir, como @code{"/dev/sda3"}, o una lista de dichas cadenas -cuando varios dispositivos necesitan ser ensamblados para crear uno nuevo. - -@item target -Esta cadena especifica el nombre del dispositivo traducido resultante. Para -traductores del núcleo como dispositivos de cifrado del tipo -@code{luks-device-mapping}, especificar @code{"mi-particion"} produce la -creación del dispositivo @code{"/dev/mapper/mi-particion"}. Para -dispositivos RAID de tipo @code{raid-device-mapping}, el nombre del -dispositivo completo como @code{"/dev/md0"} debe ser proporcionado. - -@item type -Debe ser un objeto @code{mapped-device-kind}, que especifica cómo -@var{source} se traduce a @var{target}. -@end table -@end deftp - -@defvr {Variable Scheme} luks-device-mapping -Define el cifrado de bloques LUKS mediante el uso de la orden -@command{cryptsetup} del paquete del mismo nombre. Depende del módulo -@code{dm-crypt} del núcleo Linux. -@end defvr - -@defvr {Variable Scheme} raid-device-mapping -Define un dispositivo RAID, el cual se ensambla mediante el uso de la orden -@code{mdadm} del paquete del mismo nombre. Requiere la carga del módulo del -núcleo Linux para el nivel RAID apropiado, como @code{raid456} para RAID-4, -RAID-5 o RAID-6, o @code{raid10} para RAID-10. -@end defvr - -@cindex cifrado de disco -@cindex LUKS -El siguiente ejemplo especifica una traducción de @file{/dev/sda3} a -@file{/dev/mapper/home} mediante el uso de LUKS---la -@url{https://gitlab.com/cryptsetup/cryptsetup,configuración de claves -unificada de Linux}, un mecanismo estándar para cifrado de disco. El -dispositivo @file{/dev/mapper/home} puede usarse entonces como el campo -@code{device} de una declaración @code{file-system} (@pxref{Sistemas de ficheros}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -De manera alternativa, para independizarse de la numeración de dispositivos, -puede obtenerse el UUID LUKS (@dfn{identificador único}) del dispositivo -fuente con una orden así: - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -y usarlo como sigue: - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex cifrado del intercambio -También es deseable cifrar el espacio de intercambio, puesto que el espacio -de intercambio puede contener información sensible. Una forma de conseguirlo -es usar un fichero de intercambio en un sistema de ficheros en un -dispositivo traducido a través del cifrado LUKS. @xref{Preparación para la instalación,,Particionado del disco}, para un ejemplo. - -Un dispositivo RAID formado por las particiones @file{/dev/sda1} y -@file{/dev/sdb1} puede declararse como se muestra a continuación: - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -El dispositivo @file{/dev/md0} puede usarse entonces como el campo -@code{device} de una declaración @code{file-system} (@pxref{Sistemas de ficheros}). Fíjese que no necesita proporcionar el nivel RAID; se selecciona -durante la creación inicial y formato del dispositivo RAID y después se -determina automáticamente. - - -@node Cuentas de usuaria -@section Cuentas de usuaria - -@cindex usuarias -@cindex cuentas -@cindex cuentas de usuaria -Los grupos y cuentas de usuaria se gestionan completamente a través de la -declaración @code{operating-system}. Se especifican con las formas -@code{user-account} y @code{user-group}: - -@example -(user-account - (name "alicia") - (group "users") - (supplementary-groups '("wheel" ;permite usar sudo, etc. - "audio" ;tarjeta de sonido - "video" ;dispositivos de vídeo como cámaras - "cdrom")) ;el veterano CD-ROM - (comment "hermana de Roberto") - (home-directory "/home/alicia")) -@end example - -Durante el arranque o tras la finalización de @command{guix system -reconfigure}, el sistema se asegura de que únicamente las cuentas de usuaria -y grupos especificados en la declaración @code{operating-system} existen, y -con las propiedades especificadas. Por tanto, la creación o modificación de -cuentas o grupos realizadas directamente invocando órdenes como -@command{useradd} se pierden al reconfigurar o reiniciar el sistema. Esto -asegura que el sistema permanece exactamente como se declaró. - -@deftp {Tipo de datos} user-account -Objetos de este tipo representan cuentas de usuaria. Los siguientes miembros -pueden ser especificados: - -@table @asis -@item @code{name} -El nombre de la cuenta de usuaria. - -@item @code{group} -@cindex grupos -Este es el nombre (una cadena) o identificador (un número) del grupo de -usuarias al que esta cuenta pertenece. - -@item @code{supplementary-groups} (predeterminados: @code{'()}) -Opcionalmente, esto puede definirse como una lista de nombres de grupo a los -que esta cuenta pertenece. - -@item @code{uid} (predeterminado: @code{#f}) -Este es el ID de usuaria para esta cuenta (un número), o @code{#f}. En el -último caso, un número es seleccionado automáticamente por el sistema cuando -la cuenta es creada. - -@item @code{comment} (predeterminado: @code{""}) -Un comentario sobre la cuenta, como el nombre completo de la propietaria. - -@item @code{home-directory} -Este es el nombre del directorio de usuaria de la cuenta. - -@item @code{create-home-directory?} (predeterminado: @code{#t}) -Indica si el directorio de usuaria de esta cuenta debe ser creado si no -existe todavía. - -@item @code{shell} (predeterminado: Bash) -Esto es una expresión-G denotando el nombre de fichero de un programa que -será usado como shell (@pxref{Expresiones-G}). - -@item @code{system?} (predeterminado: @code{#f}) -Este valor lógico indica si la cuenta es una cuenta ``del sistema''. Las -cuentas del sistema se tratan a veces de forma especial; por ejemplo, los -gestores gráficos de inicio no las enumeran. - -@anchor{user-account-password} -@cindex contraseña, para cuentas de usuaria -@item @code{password} (predeterminada: @code{#f}) -Normalmente debería dejar este campo a @code{#f}, inicializar la contraseña -de usuaria como @code{root} con la orden @command{passwd}, y entonces dejar -a las usuarias cambiarla con @command{passwd}. Las contraseñas establecidas -con @command{passwd} son, por supuesto, preservadas entre reinicios y -reconfiguraciones. - -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") - (group "users") - - ;; Specify a SHA-512-hashed initial password. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Nota -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 grupos -Las declaraciones de grupos son más simples incluso: - -@example -(user-group (name "estudiantes")) -@end example - -@deftp {Tipo de datos} user-group -Este tipo es para grupos de usuarias. Hay únicamente unos pocos campos: - -@table @asis -@item @code{name} -En nombre del grupo. - -@item @code{id} (predeterminado: @code{#f}) -El identificador del grupo (un número). Si es @code{#f}, un nuevo número es -reservado automáticamente cuando se crea el grupo. - -@item @code{system?} (predeterminado: @code{#f}) -Este valor booleano indica si el grupo es un grupo ``del sistema''. Los -grupos del sistema tienen identificadores numéricos bajos. - -@item @code{password} (predeterminada: @code{#f}) -¿Qué? ¿Los grupos de usuarias pueden tener una contraseña? Bueno, -aparentemente sí. A menos que sea @code{#f}, este campo especifica la -contraseña del grupo. - -@end table -@end deftp - -Por conveniencia, una variable contiene una lista con todos los grupos de -usuarias básicos que se puede esperar: - -@defvr {Variable Scheme} %base-groups -Esta es la lista de grupos de usuarias básicos que las usuarias y/o los -paquetes esperan que estén presentes en el sistema. Esto incluye grupos como -``root'', ``wheel'' y ``users'', así como grupos usados para controlar el -acceso a dispositivos específicos como ``audio'', ``disk'' y ``cdrom''. -@end defvr - -@defvr {Variable Scheme} %base-user-accounts -Esta es la lista de cuentas de usuaria básicas que los programas pueden -esperar encontrar en un sistema GNU/Linux, como la cuenta ``nobody''. - -Fíjese que la cuenta de ``root'' no se incluye aquí. Es un caso especial y -se añade automáticamente esté o no especificada. -@end defvr - -@node Distribución de teclado -@section Distribución de teclado - -@cindex distribución de teclado -@cindex mapa del teclas -To specify what each key of your keyboard does, you need to tell the -operating system what @dfn{keyboard layout} you want to use. The default, -when nothing is specified, is the US English QWERTY layout for 105-key PC -keyboards. However, German speakers will usually prefer the German QWERTZ -layout, French speakers will want the AZERTY layout, and so on; hackers -might prefer Dvorak or bépo, and they might even want to further customize -the effect of some of the keys. This section explains how to get that done. - -@cindex distribución de teclado, definición -There are three components that will want to know about your keyboard -layout: - -@itemize -@item -The @emph{bootloader} may want to know what keyboard layout you want to use -(@pxref{Configuración del gestor de arranque, @code{keyboard-layout}}). This is useful -if you want, for instance, to make sure that you can type the passphrase of -your encrypted root partition using the right layout. - -@item -The @emph{operating system kernel}, Linux, will need that so that the -console is properly configured (@pxref{Referencia de ``operating-system'', -@code{keyboard-layout}}). - -@item -The @emph{graphical display server}, usually Xorg, also has its own idea of -the keyboard layout (@pxref{Sistema X Window, @code{keyboard-layout}}). -@end itemize - -Guix allows you to configure all three separately but, fortunately, it -allows you to share the same keyboard layout for all three components. - -@cindex XKB, distribuciones de teclado -Keyboard layouts are represented by records created by the -@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following -the X Keyboard extension (XKB), each layout has four attributes: a name -(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), -an optional variant name, an optional keyboard model name, and a possibly -empty list of additional options. In most cases the layout name is all you -care about. Here are a few example: - -@example -;; The German QWERTZ layout. Here we assume a standard -;; "pc105" keyboard model. -(keyboard-layout "de") - -;; The bépo variant of the French layout. -(keyboard-layout "fr" "bepo") - -;; The Catalan layout. -(keyboard-layout "es" "cat") - -;; The Latin American Spanish layout. In addition, the -;; "Caps Lock" key is used as an additional "Ctrl" key, -;; and the "Menu" key is used as a "Compose" key to enter -;; accented letters. -(keyboard-layout "latam" - #:options '("ctrl:nocaps" "compose:menu")) - -;; The Russian layout for a ThinkPad keyboard. -(keyboard-layout "ru" #:model "thinkpad") - -;; The "US international" layout, which is the US layout plus -;; dead keys to enter accented characters. This is for an -;; Apple MacBook keyboard. -(keyboard-layout "us" "intl" #:model "macbook78") -@end example - -See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} -package for a complete list of supported layouts, variants, and models. - -@cindex distribución de teclado, configuración -Let's say you want your system to use the Turkish keyboard layout throughout -your system---bootloader, console, and Xorg. Here's what your system -configuration would look like: - -@findex set-xorg-configuration -@lisp -;; Using the Turkish layout for the bootloader, the console, -;; and for Xorg. - -(operating-system - ;; ... - (keyboard-layout (keyboard-layout "tr")) ;for the console - (bootloader (bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi") - (keyboard-layout keyboard-layout))) ;for GRUB - (services (cons (set-xorg-configuration - (xorg-configuration ;for Xorg - (keyboard-layout keyboard-layout))) - %desktop-services))) -@end lisp - -In the example above, for GRUB and for Xorg, we just refer to the -@code{keyboard-layout} field defined above, but we could just as well refer -to a different layout. The @code{set-xorg-configuration} procedure -communicates the desired Xorg configuration to the graphical log-in manager, -by default GDM. - -We've discussed how to specify the @emph{default} keyboard layout of your -system when it starts, but you can also adjust it at run time: - -@itemize -@item -If you're using GNOME, its settings panel has a ``Region & Language'' entry -where you can select one or more keyboard layouts. - -@item -Under Xorg, the @command{setxkbmap} command (from the same-named package) -allows you to change the current layout. For example, this is how you would -change the layout to US Dvorak: - -@example -setxkbmap us dvorak -@end example - -@item -The @code{loadkeys} command changes the keyboard layout in effect in the -Linux console. However, note that @code{loadkeys} does @emph{not} use the -XKB keyboard layout categorization described above. The command below loads -the French bépo layout: - -@example -loadkeys fr-bepo -@end example -@end itemize - -@node Localizaciones -@section Localizaciones - -@cindex localización -Una @dfn{localización} define convenciones culturales para una lengua y -región del mundo particular (@pxref{Localizaciones,,, libc, The GNU C Library -Reference Manual}). Cada localización tiene un nombre que típicamente tiene -la forma de @code{@var{lengua}_@var{territorio}.@var{codificación}}---por -ejemplo, @code{fr_LU.utf8} designa la localización para la lengua francesa, -con las convenciones culturales de Luxemburgo, usando la codificación UTF-8. - -@cindex definición de localización -Normalmente deseará especificar la localización predeterminada para la -máquina usando el campo @code{locale} de la declaración -@code{operating-system} (@pxref{Referencia de ``operating-system'', @code{locale}}). - -La localización seleccionada es automáticamente añadida a las -@dfn{definiciones de localización} conocidas en el sistema si es necesario, -con su codificación inferida de su nombre---por ejemplo, se asume que -@code{bo_CN.utf8} usa la codificación @code{UTF-8}. Definiciones de -localización adicionales pueden ser especificadas en el campo -@code{locale-definitions} de @code{operating-system}---esto es util, por -ejemplo, si la codificación no puede ser inferida del nombre de la -localización. El conjunto predeterminado de definiciones de localización -incluye algunas localizaciones ampliamente usadas, pero no todas las -disponibles, para ahorrar espacio. - -Por ejemplo, para añadir la localización del frisio del norte para Alemania, -el valor de dicho campo puede ser: - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -De mismo modo, para ahorrar espacio, se puede desear que -@code{locale-definitions} contenga únicamente las localizaciones que son -realmente usadas, como en: - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -Las definiciones de localización compiladas están disponibles en -@file{/run/current-system/locale/X.Y}, donde @code{X.Y} es la versión de -libc, que es la ruta donde la GNU@tie{}libc contenida en Guix buscará los -datos de localización. Esto puede ser sobreescrito usando la variable de -entorno @code{LOCPATH} (@pxref{locales-and-locpath, @code{LOCPATH} and -locale packages}). - -La forma @code{locale-definition} es proporcionada por el módulo @code{(gnu -system locale)}. Los detalles se proporcionan a continuación. - -@deftp {Tipo de datos} locale-definition -Este es el tipo de datos de una definición de localización. - -@table @asis - -@item @code{name} -El nombre de la localización. @xref{Locale Names,,, libc, The GNU C Library -Reference Manual}, para más información sobre nombres de localizaciones. - -@item @code{source} -El nombre de la fuente para dicha localización. Esto típicamente es la parte -@code{@var{idioma}_@var{territorio}} del nombre de localización. - -@item @code{charset} (predeterminado: @code{"UTF-8"}) -La ``codificación de caracteres'' o ``conjunto de caracteres'' para dicha -localización, @uref{http://www.iana.org/assignments/character-sets, como se -define por IANA}. - -@end table -@end deftp - -@defvr {Variable Scheme} %default-locale-definitions -Una lista de localizaciones UTF-8 usadas de forma común, usada como valor -predeterminado del campo @code{locale-definitions} en las declaraciones -@code{operating-system}. - -@cindex nombre de localización -@cindex codificación normalizada en los nombres de localizaciones -Estas definiciones de localizaciones usan la @dfn{codificación normalizada} -para el fragmento tras el punto en el nombre (@pxref{Using gettextized -software, normalized codeset,, libc, The GNU C Library Reference -Manual}). Por lo que por ejemplo es válido @code{uk_UA.utf8} pero @emph{no}, -digamos, @code{uk_UA.UTF-8}. -@end defvr - -@subsection Consideraciones sobre la compatibilidad de datos de localización - -@cindex incompatibilidad, de datos de localización -Las declaraciones @code{operating-system} proporcionan un campo -@code{locale-libcs} para especificar los paquetes GNU@tie{}libc que se -usarán para compilar las declaraciones de localizaciones -(@pxref{Referencia de ``operating-system''}). ``¿Por qué debo preocuparme?'', puede -preguntarse. Bueno, sucede que el formato binario de los datos de -localización es ocasionalmente incompatible de una versión de libc a otra. - -@c See -@c and . -Por ejemplo, un programa enlazado con la versión 2.21 de libc no puede leer -datos de localización producidos con libc 2.22; peor aún, ese programa -@emph{aborta} en vez de simplemente ignorar los datos de localización -incompatibles@footnote{Las versiones 2.23 y posteriores de GNU@tie{}libc -simplemente ignorarán los datos de localización incompatibles, lo cual ya es -un avance.}. De manera similar, un programa enlazado con libc 2.22 puede -leer la mayor parte, pero no todo, de los datos de localización de libc 2.21 -(específicamente, los datos @code{LC_COLLATE} son incompatibles); por tanto -las llamadas a @code{setlocale} pueden fallar, pero los programas no -abortarán. - -El ``problema'' con Guix es que las usuarias tienen mucha libertad: pueden -elegir cuando e incluso si actualizar el software en sus perfiles, y pueden -estar usando una versión de libc diferente de la que la administradora del -sistema usó para construir los datos de localización comunes a todo el -sistema. - -Por suerte, las usuarias sin privilegios también pueden instalar sus propios -datos de localización y definir @var{GUIX_LOCPATH} adecuadamente -(@pxref{locales-and-locpath, @code{GUIX_LOCPATH} y paquetes de -localizaciones}). - -No obstante, es mejor si los datos de localización globales del sistema en -@file{/run/current-system/locale} se construyen para todas las versiones de -libc realmente en uso en el sistema, de manera que todos los programas -puedan acceder a ellos---esto es especialmente crucial en un sistema -multiusuaria. Para hacerlo, la administradora puede especificar varios -paquetes libc en el campo @code{locale-libcs} de @code{operating-system}: - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -Este ejemplo llevaría a un sistema que contiene definiciones de localización -tanto para libc 2.21 como para la versión actual de libc en -@file{/run/current-system/locale}. - - -@node Servicios -@section Servicios - -@cindex servicios del sistema -Una parte importante de la preparación de una declaración -@code{operating-system} es listar los @dfn{servicios del sistema} y su -configuración (@pxref{Uso de la configuración del sistema}). Los servicios del -sistema típicamente son daemon lanzados cuando el sistema arrancha, u otras -acciones necesarias en ese momento---por ejemplo, configurar el acceso de -red. - -Guix has a broad definition of ``service'' (@pxref{Composición de servicios}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Servicios de Shepherd}). 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 - -La orden previa, ejecutada como @code{root}, enumera los servicios -actualmente definidos. La orden @command{herd doc} muestra una sinopsis del -servicio proporcionado y sus acciones asociadas: - -@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 - -Las ordenes internas @command{start}, @command{stop} y @command{restart} -tienen el efecto de arrancar, parar y reiniciar el servicio, -respectivamente. Por ejemplo, las siguientes órdenes paran el servicio nscd -y reinician el servidor gráfico Xorg: - -@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 - -Las siguientes secciones documentan los servicios disponibles, comenzando -con los servicios básicos, que pueden ser usados en una declaración -@code{operating-system}. - -@menu -* Servicios base:: Servicios esenciales del sistema. -* Ejecución de tareas programadas:: El servicio mcron. -* Rotación de logs:: El servicio rottlog. -* Servicios de red:: Configuración de red, daemon SSH, etc. -* Sistema X Window:: Interfaz gráfica. -* Servicios de impresión:: Soporte de impresoras locales y remotas. -* Servicios de escritorio:: D-Bus y servicios de escritorio. -* Servicios de sonido:: Servicios de ALSA y Pulseaudio. -* Servicios de bases de datos:: Bases de datos SQL, almacenes de - clave-valor, etc. -* Servicios de correo:: IMAP, POP3, SMTP y todo eso. -* Servicios de mensajería:: Servicios de mensajería. -* Servicios de telefonía:: Servicios de telefonía. -* Servicios de monitorización:: Servicios de monitorización. -* Servicios Kerberos:: Servicios Kerberos. -* Servicios LDAP:: Servicios LDAP. -* Servicios Web:: Servidores Web. -* Servicios de certificados:: Certificados TLS via Let's Encrypt. -* Servicios DNS:: Demonios DNS. -* Servicios VPN:: Demonios VPN. -* Sistema de ficheros en red:: Servicios relacionados con NFS. -* Integración continua:: El servicio Cuirass. -* Servicios de gestión de energía:: Extender la vida de la batería. -* Servicios de audio:: El MPD. -* Servicios de virtualización:: Servicios de virtualización. -* Servicios de control de versiones:: Proporcionar acceso remoto a - repositorios Git. -* Servicios de juegos:: Servidores de juegos. -* Servicios misceláneos:: Otros servicios. -@end menu - -@node Servicios base -@subsection Servicios base - -El módulo @code{(gnu services base)} proporciona definiciones para los -servicios básicos que se esperan en el sistema. Los servicios exportados por -este módulo se enumeran a continuación. - -@defvr {Variable Scheme} %base-services -Esta variable contiene una lista de servicios básicos (@pxref{Tipos de servicios y servicios}, para más información sobre los objetos servicio) que se -pueden esperar en el sistema: un servicio de ingreso al sistema (mingetty) -en cada tty, syslogd, el daemon de la caché del servicio de nombres (nscd), -el gestor de dispositivos udev, y más. - -Este es el valor predeterminado del campo @code{services} de las -declaraciones @code{operating-system}. De manera habitual, cuando se -personaliza el sistema, es deseable agregar servicios a -@var{%base-services}, de esta forma: - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Variable Scheme} special-files-service-type -El servicio que establece ``ficheros especiales'' como @file{/bin/sh}; una -instancia suya es parte de @code{%base-services}. - -El valor asociado con servicios @code{special-file-service-type} debe ser -una lista de tuplas donde el primer elemento es el ``fichero especial'' y el -segundo elemento es su destino. El valor predeterminado es: - -@cindex @file{/bin/sh} -@cindex @file{sh}, en @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example - -@cindex @file{/usr/bin/env} -@cindex @file{env}, en @file{/usr/bin} -Si quiere añadir, digamos, @code{/usr/bin/env} a su sistema, puede cambiar -su valor por: - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Ya que es parte de @code{%base-services}, puede usar @code{modify-services} -para personalizar el conjunto de ficheros especiales (@pxref{Referencia de servicios, @code{modify-services}}). Pero una forma simple de añadir un -fichero especial es usar el procedimiento @code{extra-special-file} (véase a -continuación). -@end defvr - -@deffn {Procedimiento Scheme} extra-special-file @var{fichero} @var{destino} -Usa @var{destino} como el ``fichero especial'' @var{fichero}. - -Por ejemplo, la adición de las siguientes líneas al campo @code{services} de -su declaración de sistema operativo genera @file{/usr/bin/env} como un -enlace simbólico: - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Procedimiento Scheme} host-name-service @var{nombre} -Devuelve un servicio que establece el nombre de máquina a @var{nombre}. -@end deffn - -@deffn {Procedimiento Scheme} login-service @var{config} -Devuelve un servicio para ejecutar el ingreso al sistema de acuerdo con -@var{config}, un objeto @code{}, que especifica el -mensaje del día, entre otras cosas. -@end deffn - -@deftp {Tipo de datos} login-configuration -Este es el tipo de datos que representa la configuración del ingreso al -sistema. - -@table @asis - -@item @code{motd} -@cindex mensaje del día -Un objeto tipo-fichero que contiene el ``mensaje del día''. - -@item @code{allow-empty-passwords?} (predeterminado: @code{#t}) -Permite contraseñas vacías por defecto para que las primeras usuarias puedan -ingresar en el sistema cuando la cuenta de ``root'' está recién creada. - -@end table -@end deftp - -@deffn {Procedimiento Scheme} mingetty-service @var{config} -Devuelve un servicio para ejecutar mingetty de acuerdo con @var{config}, un -objeto @code{}, que especifica el tty a ejecutar -entre otras cosas. -@end deffn - -@deftp {Tipo de datos} mingetty-configuration -Este es el tipo de datos que representa la configuración de Mingetty, el -cual proporciona la implementación predeterminada de ingreso al sistema en -las consolas virtuales. - -@table @asis - -@item @code{tty} -El sistema de la consola en la que se ejecuta este Mingetty---por ejemplo, -@code{"tty1"}. - -@item @code{auto-login} (predeterminado: @code{#f}) -Cuando sea verdadero, este campo debe ser una cadena que denote el nombre de -usuaria bajo el cual el sistema ingresa automáticamente. Cuando es -@code{#f}, se deben proporcionar un nombre de usuaria y una contraseña para -ingresar en el sistema. - -@item @code{login-program} (predeterminado: @code{#f}) -Debe ser @code{#f}, en cuyo caso se usa el programa predeterminado de -ingreso al sistema (@command{login} de las herramientas Shadow), o una -expresión-G que determine el nombre del programa de ingreso al sistema. - -@item @code{login-pause?} (predeterminado: @code{#f}) -Cuando es @code{#t} en conjunción con @var{auto-login}, la usuaria deberá -presionar una tecla para lanzar el shell de ingreso al sistema. - -@item @code{mingetty} (predeterminado: @var{mingetty}) -El paquete Mingetty usado. - -@end table -@end deftp - -@deffn {Procedure Scheme} agetty-service @var{config} -Devuelve un servicio para ejecutar agetty de acuerdo con @var{config}, un -objeto @code{}, que especifica el tty a ejecutar entre -otras cosas.< -@end deffn - -@deftp {Tipo de datos} agetty-configuration -Este es el tipo de datos que representa la configuración de agetty, que -implementa el ingreso al sistema en las consolas virtuales y serie. Véase la -página de manual @code{agetty(8)} para más información. - -@table @asis - -@item @code{tty} -The name of the console this agetty runs on, as a string---e.g., -@code{"ttyS0"}. This argument is optional, it will default to a reasonable -default serial port used by the kernel Linux. - -For this, if there is a value for an option @code{agetty.tty} in the kernel -command line, agetty will extract the device name of the serial port from it -and use that. - -If not and if there is a value for an option @code{console} with a tty in -the Linux command line, agetty will extract the device name of the serial -port from it and use that. - -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} (predeterminado: @code{#f}) -A string containing a comma-separated list of one or more baud rates, in -descending order. - -@item @code{term} (predeterminado: @code{#f}) -A string containing the value used for the @code{TERM} environment variable. - -@item @code{eight-bits?} (predeterminado: @code{#f}) -When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection -is disabled. - -@item @code{auto-login} (predeterminado: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{no-reset?} (predeterminado: @code{#f}) -When @code{#t}, don't reset terminal cflags (control modes). - -@item @code{host} (predeterminado: @code{#f}) -This accepts a string containing the "login_host", which will be written -into the @file{/var/run/utmpx} file. - -@item @code{remote?} (predeterminado: @code{#f}) -When set to @code{#t} in conjunction with @var{host}, this will add an -@code{-r} fakehost option to the command line of the login program specified -in @var{login-program}. - -@item @code{flow-control?} (predeterminado: @code{#f}) -When set to @code{#t}, enable hardware (RTS/CTS) flow control. - -@item @code{no-issue?} (predeterminado: @code{#f}) -When set to @code{#t}, the contents of the @file{/etc/issue} file will not -be displayed before presenting the login prompt. - -@item @code{init-string} (predeterminada: @code{#f}) -This accepts a string that will be sent to the tty or modem before sending -anything else. It can be used to initialize a modem. - -@item @code{no-clear?} (predeterminado: @code{#f}) -When set to @code{#t}, agetty will not clear the screen before showing the -login prompt. - -@item @code{login-program} (predeterminado: (file-append shadow "/bin/login")) -This must be either a gexp denoting the name of a log-in program, or unset, -in which case the default value is the @command{login} from the Shadow tool -suite. - -@item @code{local-line} (predeterminado: @code{#f}) -Control the CLOCAL line flag. This accepts one of three symbols as -arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, the -default value chosen by agetty is @code{'auto}. - -@item @code{extract-baud?} (predeterminado: @code{#f}) -When set to @code{#t}, instruct agetty to try to extract the baud rate from -the status messages produced by certain types of modems. - -@item @code{skip-login?} (predeterminado: @code{#f}) -When set to @code{#t}, do not prompt the user for a login name. This can be -used with @var{login-program} field to use non-standard login systems. - -@item @code{no-newline?} (predeterminado: @code{#f}) -When set to @code{#t}, do not print a newline before printing the -@file{/etc/issue} file. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (predeterminadas: @code{#f}) -This option accepts a string containing options that are passed to the login -program. When used with the @var{login-program}, be aware that a malicious -user could try to enter a login name containing embedded options that could -be parsed by the login program. - -@item @code{login-pause} (predeterminada: @code{#f}) -When set to @code{#t}, wait for any key before showing the login prompt. -This can be used in conjunction with @var{auto-login} to save memory by -lazily spawning shells. - -@item @code{chroot} (predeterminado: @code{#f}) -Change root to the specified directory. This option accepts a directory -path as a string. - -@item @code{hangup?} (predeterminado: @code{#f}) -Use the Linux system call @code{vhangup} to do a virtual hangup of the -specified terminal. - -@item @code{keep-baud?} (predeterminado: @code{#f}) -When set to @code{#t}, try to keep the existing baud rate. The baud rates -from @var{baud-rate} are used when agetty receives a @key{BREAK} character. - -@item @code{timeout} (predeterminado: @code{#f}) -When set to an integer value, terminate if no user name could be read within -@var{timeout} seconds. - -@item @code{detect-case?} (predeterminado: @code{#f}) -When set to @code{#t}, turn on support for detecting an uppercase-only -terminal. This setting will detect a login name containing only uppercase -letters as indicating an uppercase-only terminal and turn on some -upper-to-lower case conversions. Note that this will not support Unicode -characters. - -@item @code{wait-cr?} (predeterminado: @code{#f}) -When set to @code{#t}, wait for the user or modem to send a carriage-return -or linefeed character before displaying @file{/etc/issue} or login prompt. -This is typically used with the @var{init-string} option. - -@item @code{no-hints?} (predeterminado: @code{#f}) -When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks. - -@item @code{no-hostname?} (predeterminado: @code{#f}) -By default, the hostname is printed. When this option is set to @code{#t}, -no hostname will be shown at all. - -@item @code{long-hostname?} (predeterminado: @code{#f}) -By default, the hostname is only printed until the first dot. When this -option is set to @code{#t}, the fully qualified hostname by -@code{gethostname} or @code{getaddrinfo} is shown. - -@item @code{erase-characters} (predeterminado: @code{#f}) -This option accepts a string of additional characters that should be -interpreted as backspace when the user types their login name. - -@item @code{kill-characters} (predeterminado: @code{#f}) -This option accepts a string that should be interpreted to mean "ignore all -previous characters" (also called a "kill" character) when the types their -login name. - -@item @code{chdir} (predeterminado: @code{#f}) -This option accepts, as a string, a directory path that will be changed to -before login. - -@item @code{delay} (predeterminado: @code{#f}) -This options accepts, as an integer, the number of seconds to sleep before -opening the tty and displaying the login prompt. - -@item @code{nice} (predeterminado: @code{#f}) -This option accepts, as an integer, the nice value with which to run the -@command{login} program. - -@item @code{extra-options} (predeterminadas: @code{'()}) -This option provides an "escape hatch" for the user to provide arbitrary -command-line arguments to @command{agetty} as a list of strings. - -@end table -@end deftp - -@deffn {Procedimiento Scheme} kmscon-service-type @var{config} -Return a service to run -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} according to -@var{config}, a @code{} object, which specifies the -tty to run, among other things. -@end deffn - -@deftp {Tipo de datos} kmscon-configuration -Este es el tipo de datos que representa la configuración de Kmscon, que -implementa el ingreso al sistema en consolas virtuales. - -@table @asis - -@item @code{virtual-terminal} -El sistema de la consola en la que se ejecuta este Kmscon---por ejemplo, -@code{"tty1"}. - -@item @code{login-program} (predeterminado: @code{#~(string-append #$shadow "/bin/login")}) -A gexp denoting the name of the log-in program. The default log-in program -is @command{login} from the Shadow tool suite. - -@item @code{login-arguments} (predeterminados: @code{'("-p")}) -A list of arguments to pass to @command{login}. - -@item @code{auto-login} (predeterminado: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{hardware-acceleration?} (predeterminado: #f) -Determina si se usará aceleración hardware. - -@item @code{kmscon} (predeterminado: @var{kmscon}) -El paquete Kmscon usado. - -@end table -@end deftp - -@cindex daemon de caché del servicio de nombres -@cindex nscd -@deffn {Procedimiento Scheme} nscd-service [@var{configuración}] [#:glibc glibc] @ - [#:name-services '()] -Devuelve un servicio que ejecuta el daemon de la caché del servicio de -nombres (nscd) con la @var{configuración} proporcionada---un objeto -@code{}. @xref{Selector de servicios de nombres}, para un ejemplo. - -Por conveniencia, el servicio ncsd de Shepherd proporciona las siguientes -acciones: - -@table @code -@item invalidate -@cindex invalidación de caché, nscd -@cindex nscd, invalidación de caché -Esto invalida la caché dada. Por ejemplo, ejecutar: - -@example -herd invalidate nscd hosts -@end example - -@noindent -invalida la caché de búsqueda de nombres de máquinas de nscd. - -@item statistics -Ejecutar @command{herd statistics nscd} muestra información del uso nscd y -la caché. -@end table - -@end deffn - -@defvr {Variable Scheme} %nscd-default-configuration -This is the default @code{} value (see below) used by -@code{nscd-service}. It uses the caches defined by -@var{%nscd-default-caches}; see below. -@end defvr - -@deftp {Tipo de datos} nscd-configuration -Este tipo de datos representa la configuración del daemon de caché del -servicio de nombres (nscd). - -@table @asis - -@item @code{name-services} (predeterminados: @code{'()}) -List of packages denoting @dfn{name services} that must be visible to the -nscd---e.g., @code{(list @var{nss-mdns})}. - -@item @code{glibc} (predeterminada: @var{glibc}) -Package object denoting the GNU C Library providing the @command{nscd} -command. - -@item @code{log-file} (predeterminado: @code{"/var/log/nscd.log"}) -Name of the nscd log file. This is where debugging output goes when -@code{debug-level} is strictly positive. - -@item @code{debug-level} (predeterminado: @code{0}) -Integer denoting the debugging levels. Higher numbers mean that more -debugging output is logged. - -@item @code{caches} (predeterminadas: @var{%nscd-default-caches}) -List of @code{} objects denoting things to be cached; see below. - -@end table -@end deftp - -@deftp {Tipo de datos} nscd-cache -Tipo de datos que representa una base de datos de caché de nscd y sus -parámetros. - -@table @asis - -@item @code{base de datos} -This is a symbol representing the name of the database to be cached. Valid -values are @code{passwd}, @code{group}, @code{hosts}, and @code{services}, -which designate the corresponding NSS database (@pxref{NSS Basics,,, libc, -The GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (predeterminado: @code{20}) -A number representing the number of seconds during which a positive or -negative lookup result remains in cache. - -@item @code{check-files?} (predeterminado: @code{#t}) -Whether to check for updates of the files corresponding to @var{database}. - -For instance, when @var{database} is @code{hosts}, setting this flag -instructs nscd to check for updates in @file{/etc/hosts} and to take them -into account. - -@item @code{persistent?} (predeterminada: @code{#t}) -Whether the cache should be stored persistently on disk. - -@item @code{shared?} (predeterminado: @code{#t}) -Whether the cache should be shared among users. - -@item @code{max-database-size} (predeterminado: 32@tie{}MiB) -Maximum size in bytes of the database cache. - -@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert -@c settings, so leave them out. - -@end table -@end deftp - -@defvr {Variable Scheme} %nscd-default-caches -List of @code{} objects used by default by -@code{nscd-configuration} (see above). - -It enables persistent and aggressive caching of service and host name -lookups. The latter provides better host name lookup performance, -resilience in the face of unreliable name servers, and also better -privacy---often the result of host name lookups is in local cache, so -external name servers do not even need to be queried. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex logging -@deftp {Tipo de datos} syslog-configuration -Este tipo de datos representa la configuración del daemon syslog. - -@table @asis -@item @code{syslogd} (predeterminado: @code{#~(string-append #$inetutils "/libexec/syslogd")}) -El daemon syslog usado. - -@item @code{config-file} (predeterminado: @code{%default-syslog.conf}) -El fichero de configuración de syslog usado. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Procedimiento Scheme} syslog-service @var{config} -Return a service that runs a syslog daemon according to @var{config}. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, para más información -sobre la sintaxis del fichero de configuración. -@end deffn - -@defvr {Variable Scheme} guix-service-type -This is the type of the service that runs the build daemon, -@command{guix-daemon} (@pxref{Invocación de guix-daemon}). Its value must be a -@code{guix-configuration} record as described below. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Tipo de datos} guix-configuration -This data type represents the configuration of the Guix build daemon. -@xref{Invocación de guix-daemon}, for more information. - -@table @asis -@item @code{guix} (predeterminado: @var{guix}) -El paquete Guix usado. - -@item @code{build-group} (predeterminado: @code{"guixbuild"}) -El nombre del grupo de las cuentas de usuarias de construcción. - -@item @code{build-accounts} (predeterminadas: @code{10}) -Número de cuentas de usuarias de construcción a crear. - -@item @code{authorize-key?} (predeterminado: @code{#t}) -@cindex sustituciones, autorización de las mismas -Determina si se autoriza las claves de sustituciones listadas en -@code{authorized-keys}---predeterminada la de -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Sustituciones}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (predeterminadas: @var{%default-authorized-guix-keys}) -La lista de ficheros de claves autorizadas para importaciones de archivos, -como una lista de expresiones-G que evalúan a cadenas (@pxref{Invocación de guix archive}). Por defecto, contiene las de @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Sustituciones}). - -@item @code{use-substitutes?} (predeterminado: @code{#t}) -Determina si se usarán sustituciones. - -@item @code{substitute-urls} (predeterminado: @var{%default-substitute-urls}) -La lista de URLs donde se buscarán sustituciones por defecto. - -@item @code{max-silent-time} (predeterminado: @code{0}) -@itemx @code{timeout} (predeterminado: @code{0}) -The number of seconds of silence and the number of seconds of activity, -respectively, after which a build process times out. A value of zero -disables the timeout. - -@item @code{log-compression} (predeterminado: @code{'bzip2}) -El tipo de compresión usado en los log de construcción---o bien @code{gzip}, -o bien @code{bzip2} o @code{none}. - -@item @code{extra-options} (predeterminadas: @code{'()}) -Lista de opciones de línea de órdenes adicionales para -@command{guix-daemon}. - -@item @code{log-file} (predeterminado: @code{"/var/log/guix-daemon.log"}) -Fichero al que se escriben la salida estándar y la salida estándar de error -de @command{guix-daemon}. - -@item @code{http-proxy} (predeterminado: @code{#f}) -El proxy HTTP que se usa para la descarga de derivaciones de salida fija y -sustituciones. - -@item @code{tmpdir} (predeterminado: @code{#f}) -Una ruta de directorio donde @command{guix-daemon} realiza las -construcciones. - -@end table -@end deftp - -@deffn {Procedimiento Scheme} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Run @var{udev}, which populates the @file{/dev} directory dynamically. udev -rules can be provided as a list of files through the @var{rules} variable. -The procedures @var{udev-rule} and @var{file->udev-rule} from @code{(gnu -services base)} simplify the creation of such rule files. -@end deffn - -@deffn {Procedimiento Scheme} udev-rule [@var{nombre-fichero} @var{contenido}] -Devuelve un fichero de reglas de udev con nombre @var{nombre-fichero} que -contiene las reglas definidas en el literal @var{contenido}. - -En el ejemplo siguiente se define una regla para un dispositivo USB que será -almacenada en el fichero @file{90-usb-cosa.rules}. Esta regla ejecuta un -script cuando se detecta un dispositivo USB con un identificador de producto -dado. - -@example -(define %regla-ejemplo-udev - (udev-rule - "90-usb-cosa.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Ejemplo\", " - "RUN+=\"/ruta/al/ejecutable\""))) -@end example - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@end deffn - -Here we show how the default @var{udev-service} can be extended with it. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %regla-ejemplo-udev)))))))) -@end example - -@deffn {Procedimiento Scheme} file->udev-rule [@var{nombre-fichero} @var{fichero}] -Devuelve un fichero de udev con nombre @var{nombre-fichero} que contiene las -reglas definidas en @var{fichero}, un objeto tipo-fichero. - -El ejemplo siguiente muestra cómo podemos usar un fichero de reglas -existente. - -@example -(use-modules (guix download) ;para url-fetch - (guix packages) ;para origin - ;; @dots{}) - -(define %reglas-android-udev - (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 - -Adicionalmente, las definiciones de paquete Gui pueden ser incluidas en -@var{rules} para extender las reglas udev con las definiciones encontradas -bajo su subdirectorio @file{lib/udev/rules.d}. En vez del ejemplo previo de -@var{file->udev-rule}, podíamos haber usado el paquete -@var{android-udev-rules} que existe en Guix en el módulo @code{(gnu packages -android)}. - -El siguiente ejemplo muestra cómo usar el paquete @var{android-udev-rules} -para que la herramienta de Android @command{adb} pueda detectar dispositivos -sin privilegios de root. También detalla como crear el grupo -@code{adbusers}, el cual se requiere para el funcionamiento correcto de las -reglas definidas dentro del paquete @var{android-udev-rules}. Para crear tal -grupo, debemos definirlo tanto como parte de @var{supplementary-groups} de -la declaración de nuestra cuenta de usuaria @var{user-account}, así como en -el campo @var{groups} del registro @var{operating-system}. - -@example -(use-modules (gnu packages android) ;para android-udev-rules - (gnu system shadow) ;para user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;para 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 {Variable Scheme} urandom-seed-service-type -Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom} -when rebooting. It also tries to seed @file{/dev/urandom} from -@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is -readable. -@end defvr - -@defvr {Variable Scheme} %random-seed-file -This is the name of the file where some random bytes are saved by -@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It -defaults to @file{/var/lib/random-seed}. -@end defvr - -@cindex ratón -@cindex gpm -@defvr {Variable Scheme} gpm-service-type -This is the type of the service that runs GPM, the @dfn{general-purpose -mouse daemon}, which provides mouse support to the Linux console. GPM -allows users to use the mouse in the console, notably to select, copy, and -paste text. - -The value for services of this type must be a @code{gpm-configuration} (see -below). This service is not part of @var{%base-services}. -@end defvr - -@deftp {Tipo de datos} gpm-configuration -Tipo de datos que representa la configuración de GPM. - -@table @asis -@item @code{opciones} (predeterminadas: @code{%default-gpm-options}) -Command-line options passed to @command{gpm}. The default set of options -instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}. -@xref{Command Line,,, gpm, gpm manual}, for more information. - -@item @code{gpm} (predeterminado: @code{gpm}) -El paquete GPM usado. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Variable Scheme} guix-publish-service-type -This is the service type for @command{guix publish} (@pxref{Invocación de guix publish}). Its value must be a @code{guix-configuration} object, as -described below. - -This assumes that @file{/etc/guix} already contains a signing key pair as -created by @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). If that is not the case, the service will fail to start. -@end deffn - -@deftp {Tipo de datos} guix-publish-configuration -Tipo de datos que representa la configuración del servicio @code{guix -publish}. - -@table @asis -@item @code{guix} (predeterminado: @code{guix}) -El paquete Guix usado. - -@item @code{port} (predeterminado: @code{80}) -El puerto TCP en el que se esperan conexiones. - -@item @code{host} (predeterminado: @code{"localhost"}) -The host (and thus, network interface) to listen to. Use @code{"0.0.0.0"} -to listen on all the network interfaces. - -@item @code{compression-level} (predeterminado: @code{3}) -The gzip compression level at which substitutes are compressed. Use -@code{0} to disable compression altogether, and @code{9} to get the best -compression ratio at the expense of increased CPU usage. - -@item @code{nar-path} (predeterminado: @code{"nar"}) -The URL path at which ``nars'' can be fetched. @xref{Invocación de guix publish, -@code{--nar-path}}, for details. - -@item @code{cache} (predeterminado: @code{#f}) -When it is @code{#f}, disable caching and instead generate archives on -demand. Otherwise, this should be the name of a directory---e.g., -@code{"/var/cache/guix/publish"}---where @command{guix publish} caches -archives and meta-data ready to be sent. @xref{Invocación de guix publish, -@option{--cache}}, for more information on the tradeoffs involved. - -@item @code{workers} (predeterminado: @code{#f}) -When it is an integer, this is the number of worker threads used for -caching; when @code{#f}, the number of processors is used. @xref{Invocación de guix publish, @option{--workers}}, for more information. - -@item @code{ttl} (predeterminado: @code{#f}) -When it is an integer, this denotes the @dfn{time-to-live} in seconds of the -published archives. @xref{Invocación de guix publish, @option{--ttl}}, for more -information. -@end table -@end deftp - -@anchor{rngd-service} -@deffn {Procedimiento Scheme} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] Return a service that runs the @command{rngd} -program from @var{rng-tools} to add @var{device} to the kernel's entropy -pool. The service will fail if @var{device} does not exist. -@end deffn - -@anchor{pam-limits-service} -@cindex límites por sesión -@cindex ulimit -@cindex prioridad -@cindex tiempo real -@cindex jackd -@deffn {Procedimiento Scheme} pam-limits-service [#:limits @code{'()}] - -Return a service that installs a configuration file for the -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, -@code{pam_limits} module}. The procedure optionally takes a list of -@code{pam-limits-entry} values, which can be used to specify @code{ulimit} -limits and nice priority limits to user sessions. - -The following limits definition sets two hard and soft limits for all login -sessions of users in the @code{realtime} group: - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -The first entry increases the maximum realtime priority for non-privileged -processes; the second entry lifts any restriction of the maximum address -space that can be locked in memory. These settings are commonly used for -real-time audio systems. -@end deffn - -@node Ejecución de tareas programadas -@subsection Ejecución de tareas programadas - -@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{Invocación de 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{Expresiones-G}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define trabajo-updatedb - ;; Ejecuta 'updatedb' a las 3AM cada día. Aquí escribimos - ;; las acciones del trabajo como un procedimiento Scheme. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define trabajo-recolector-basura - ;; Recolecta basura 5 minutos después de media noche, - ;; todos los días. La acción del trabajo es una orden - ;; del shell. - #~(job "5 0 * * *" ;sintaxis de Vixie cron - "guix gc -F 1G")) - -(define trabajo-idutils - ;; Actualiza el índice de la base de datos como "carlos" a las - ;; 12:15 y a las 19:15. Esto se ejecuta desde su directorio. - #~(job '(next-minute-from (next-hour '(12 19)) '(15)) - (string-append #$idutils "/bin/mkid src") - #:user "carlos")) - -(operating-system - ;; @dots{} - (services (cons (service mcron-service-type - (mcron-configuration - (jobs (list trabajo-recolector-basura - trabajo-updatedb - trabajo-idutils)))) - %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 {Variable Scheme} 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{Composición de servicios}). In other -words, it is possible to define services that provide additional mcron jobs -to run. -@end defvr - -@deftp {Tipo de datos} mcron-configuration -Tipo de datos que representa la configuración de mcron. - -@table @asis -@item @code{mcron} (predeterminado: @var{mcron}) -El paquete mcron usado. - -@item @code{jobs} -This is a list of gexps (@pxref{Expresiones-G}), where each gexp corresponds -to an mcron job specification (@pxref{Syntax, mcron job specifications,, -mcron, GNU@tie{}mcron}). -@end table -@end deftp - - -@node Rotación de logs -@subsection Rotación de logs - -@cindex rottlog -@cindex rotación de logs -@cindex logging -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 {Variable Scheme} 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{Ejecución de tareas programadas}) to -run the rottlog service. -@end defvr - -@deftp {Tipo de datos} rottlog-configuration -Tipo de datos que representa la configuración de rottlog. - -@table @asis -@item @code{rottlog} (predeterminado: @code{rottlog}) -El paquete Rottlog usado. - -@item @code{rc-file} (predeterminado: @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} (predeterminadas: @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{Ejecución de tareas programadas}). -@end table -@end deftp - -@deftp {Tipo de datos} log-rotation -Tipo de datos que representa la rotación de un grupo de ficheros de log. - -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 - -La lista de campos es como sigue: - -@table @asis -@item @code{frequency} (predeterminada: @code{'weekly}) -La frecuencia de rotación de logs, un símbolo. - -@item @code{files} -La lista de ficheros o patrones extendidos de fichero a rotar. - -@item @code{options} (predeterminadas: @code{'()}) -The list of rottlog options for this rotation (@pxref{Configuration -parameters,,, rottlog, GNU Rot[t]lg Manual}). - -@item @code{post-rotate} (predeterminado: @code{#f}) -Either @code{#f} or a gexp to execute once the rotation has completed. -@end table -@end deftp - -@defvr {Variable Scheme} %default-rotations -Specifies weekly rotation of @var{%rotated-files} and a couple of other -files. -@end defvr - -@defvr {Variable Scheme} %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 Servicios de red -@subsection Servicios de red - -El módulo @code{(gnu services networking)} proporciona servicios para -configurar la interfaz de red. - -@cindex DHCP, servicio de red -@defvr {Variable Scheme} 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 {Procedimiento Scheme} 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{}. For example: - -@example -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "mi-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end example -@end deffn - -@deftp {Tipo de datos} dhcpd-configuration -@table @asis -@item @code{package} (predeterminado: @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} (predeterminado: @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{Expresiones-G, file-like objects}). See @code{man -dhcpd.conf} for details on the configuration file syntax. -@item @code{version} (predeterminada: @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} (predeterminado: @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} (predeterminado: @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} (predeterminadas: @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 {Variable Scheme} static-networking-service-type -@c TODO Document data structures. -This is the type for statically-configured network interfaces. -@end defvr - -@deffn {Procedimiento Scheme} static-networking-service @var{interfaz} @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. - -Por ejemplo: - -@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 sin cables -@cindex WiFi -@cindex gestión de red -@deffn {Procedimiento Scheme} 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 {Variable Scheme} 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. - -Este servicio es parte de @code{%desktop-services} (@pxref{Servicios de escritorio}). -@end defvr - -@deftp {Tipo de datos} modem-manager-configuration -Tipo de datos que representa la configuración de ModemManager. - -@table @asis -@item @code{modem-manager} (predeterminado: @code{modem-manager}) -El paquete de ModemManager usado. - -@end table -@end deftp - -@cindex NetworkManager - -@defvr {Variable Scheme} 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. - -Este servicio es parte de @code{%desktop-services} (@pxref{Servicios de escritorio}). -@end defvr - -@deftp {Tipo de datos} network-manager-configuration -Tipo de datos que representa la configuración de NetworkManager. - -@table @asis -@item @code{network-manager} (predeterminado: @code{network-manager}) -El paquete de NetworkManager usado. - -@item @code{dns} (predeterminado: @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} (predeterminados: @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 {Variable Scheme} 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 {Tipo de datos} connman-configuration -Tipo de datos que representa la configuración de connman. - -@table @asis -@item @code{connman} (predeterminado: @var{connman}) -El paquete connman usado. - -@item @code{disable-vpn?} (predeterminado: @code{#f}) -Cuando es verdadero, deshabilita el módulo vpn de connman. -@end table -@end deftp - -@cindex WPA Supplicant -@defvr {Variable Scheme} 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 {Tipo de datos} wpa-supplicant-configuration -Tipo de datos que representa la configuración de WPA Supplicant. - -Toma los siguientes parámetros: - -@table @asis -@item @code{wpa-supplicant} (predeterminado: @code{wpa-supplicant}) -El paquete de WPA Supplicant usado. - -@item @code{dbus?} (predeterminado: @code{#t}) -Si se escuchan o no peticiones en D-Bus. - -@item @code{pid-file} (predeterminado: @code{"/var/run/wpa_supplicant.pid"}) -Dónde se almacena el fichero con el PID. - -@item @code{interface} (predeterminado: @code{#f}) -If this is set, it must specify the name of a network interface that WPA -supplicant will control. - -@item @code{config-file} (predeterminado: @code{#f}) -Fichero de configuración opcional usado. - -@item @code{extra-options} (predeterminadas: @code{'()}) -Lista de parámetros adicionales a pasar al daemon en la línea de órdenes. -@end table -@end deftp - -@cindex iptables -@defvr {Variable Scheme} 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 {Tipo de datos} iptables-configuration -El tipo de datos que representa la configuración de iptables. - -@table @asis -@item @code{iptables} (predeterminado: @code{iptables}) -The iptables package that provides @code{iptables-restore} and -@code{ip6tables-restore}. -@item @code{ipv4-rules} (predeterminado: @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{Expresiones-G, file-like -objects}). -@item @code{ipv6-rules} (predeterminadas: @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{Expresiones-G, file-like -objects}). -@end table -@end deftp - -@cindex NTP (protocolo de tiempo de red), servicio -@cindex reloj de tiempo real -@defvr {Variable Scheme} 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 {Tipo de datos} ntp-configuration -Este es el tipo de datos para la configuración del servicio NTP. - -@table @asis -@item @code{servers} (predeterminados: @code{%ntp-servers}) -This is the list of servers (host names) with which @command{ntpd} will be -synchronized. - -@item @code{allow-large-adjustment?} (predeterminado: @code{#f}) -This determines whether @command{ntpd} is allowed to make an initial -adjustment of more than 1,000 seconds. - -@item @code{ntp} (predeterminado: @code{ntp}) -El paquete NTP usado. -@end table -@end deftp - -@defvr {Variable Scheme} %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 {Procedimiento Scheme} 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 {Tipo de datos} openntpd-configuration -@table @asis -@item @code{openntpd} (predeterminado: @code{(file-append openntpd "/sbin/ntpd")}) -El ejecutable openntpd usado. -@item @code{listen-on} (predeterminadas: @code{'("127.0.0.1" "::1")}) -Una lista de direcciones IP o nombres de máquina en los que el daemon ntpd -debe escuchar conexiones. -@item @code{query-from} (predeterminadas: @code{'()}) -Una lista de direcciones IP locales que el daemon ntpd debe usar para -consultas salientes. -@item @code{sensor} (predeterminados: @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} (predeterminadas: @var{%ntp-servers}) -Specify a list of IP addresses or hostnames of NTP servers to synchronize -to. -@item @code{servers} (predeterminados: @code{'()}) -Specify a list of IP addresses or hostnames of NTP pools to synchronize to. -@item @code{constraint-from} (predeterminado: @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} (predeterminadas: @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?} (predeterminado: @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 {Variable Scheme} 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" "/ruta/a/la/clave_ssh" - "-W" "smtp-server:25" "usuaria@@máquina"))))) -@end example - -See below for more details about @code{inetd-configuration}. -@end deffn - -@deftp {Tipo de datos} inetd-configuration -Tipo de datos que representa la configuración de @command{inetd}. - -@table @asis -@item @code{program} (predeterminado: @code{(file-append inetutils "/libexec/inetd")}) -El ejecutable @command{inetd} usado. - -@item @code{entries} (predeterminadas: @code{'()}) -A list of @command{inetd} service entries. Each entry should be created by -the @code{inetd-entry} constructor. -@end table -@end deftp - -@deftp {Tipo de datos} 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} (predeterminado: @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?} (predeterminado: @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} (predeterminado: @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} (predeterminados: @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 {Variable Scheme} 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{} 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 {Tipo de datos} tor-configuration -@table @asis -@item @code{tor} (predeterminado: @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} (predeterminado: @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{Expresiones-G, file-like objects}). See @code{man tor} for details -on the configuration file syntax. - -@item @code{hidden-services} (predeterminados: @code{'()}) -The list of @code{} 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{} records using the -@code{tor-hidden-service} procedure described below. - -@item @code{socks-socket-type} (predeterminado: @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 servicio oculto -@deffn {Procedimiento Scheme} tor-hidden-service @var{nombre} @var{relación} -Define un @dfn{servicio oculto} Tor llamado @var{nombre} y que implementa la -@var{¶elación}. @var{relación} es una lista de tuplas puerto/máquina, como: - -@example - '((22 "127.0.0.1:22") - (80 "127.0.0.1:8080")) -@end example - -En este ejemplo, el puerto 22 del servicio oculto se asocia con el puerto 22 -local, y el puerto 80 se asocia con el puerto 8080 local. - -Esto crea un directorio @file{/var/lib/tor/hidden-services/@var{nombre}}, -donde el fichero @file{hostname} contiene el nombre de máquina @code{.onion} -para el servicio oculto. - -Véase @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, la -documentación del proyecto Tor} para más información. -@end deffn - -El módulo @code{(gnu services rsync)} proporciona los siguientes servicios: - -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 {Variable Scheme} 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 {Tipo de datos} rsync-configuration -Tipo de datos que representa la configuración para @code{rsync-service}. - -@table @asis -@item @code{package} (predeterminado: @var{rsync}) -Paquete @code{rsync} usado. - -@item @code{port-number} (predeterminado: @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} (predeterminado: @code{"/var/run/rsyncd/rsyncd.pid"}) -Name of the file where @command{rsync} writes its PID. - -@item @code{lock-file} (predeterminado: @code{"/var/run/rsyncd/rsyncd.lock"}) -Name of the file where @command{rsync} writes its lock file. - -@item @code{log-file} (predeterminado: @code{"/var/log/rsyncd.log"}) -Name of the file where @command{rsync} writes its log file. - -@item @code{use-chroot?} (predeterminado: @var{#t}) -Whether to use chroot for @command{rsync} shared directory. - -@item @code{share-path} (predeterminado: @file{/srv/rsync}) -Location of the @command{rsync} shared directory. - -@item @code{share-comment} (predeterminado: @code{"Rsync share"}) -Comment of the @command{rsync} shared directory. - -@item @code{read-only?} (predeterminado: @var{#f}) -Read-write permissions to shared directory. - -@item @code{timeout} (predeterminado: @code{300}) -I/O timeout in seconds. - -@item @code{user} (predeterminada: @var{"root"}) -Propietaria del proceso @code{rsync}. - -@item @code{group} (predeterminado: @var{"root"}) -Grupo del proceso @code{rsync}. - -@item @code{uid} (predeterminado: @var{"rsyncd"}) -Nombre o ID de usuaria bajo la cual se efectúan las transferencias desde y -hacia el módulo cuando el daemon se ejecuta como @code{root}. - -@item @code{gid} (predeterminado: @var{"rsyncd"}) -Nombre o ID de grupo que se usa cuando se accede al módulo. - -@end table -@end deftp - -Es más, @code{(gnu services ssh)} proporciona los siguientes servicios. -@cindex SSH -@cindex servidor SSH - -@deffn {Procedimiento Scheme} 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] -Ejecuta el programa @command{lshd} de @var{lsh} para escuchar en el puerto -@var{port-number}. @var{host-key} debe designar a un fichero que contiene la -clave de la máquina, y que sea legible únicamente por 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 servidor SSH -@deffn {Variable Scheme} 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 - `(("alicia" ,(local-file "alicia.pub")) - ("rober" ,(local-file "rober.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 `(("carlos" - ,(local-file "carlos.pub"))))) -@end example -@end deffn - -@deftp {Tipo de datos} openssh-configuration -Este es el registro de configuración para @command{sshd} de OpenSSH. - -@table @asis -@item @code{pid-file} (predeterminado: @code{"/var/run/sshd.pid"}) -Name of the file where @command{sshd} writes its PID. - -@item @code{port-number} (predeterminado: @code{22}) -TCP port on which @command{sshd} listens for incoming connections. - -@item @code{permit-root-login} (predeterminado: @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?} (predeterminado: @code{#f}) -When true, users with empty passwords may log in. When false, they may not. - -@item @code{password-authentication?} (predeterminado: @code{#t}) -When true, users may log in with their password. When false, they have -other authentication methods. - -@item @code{public-key-authentication?} (predeterminado: @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?} (predeterminado: @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?} (predeterminado: @code{#t}) -Whether to allow agent forwarding. - -@item @code{allow-tcp-forwarding?} (predeterminado: @code{#t}) -Whether to allow TCP forwarding. - -@item @code{gateway-ports?} (predeterminado: @code{#f}) -Whether to allow gateway ports. - -@item @code{challenge-response-authentication?} (predeterminado: @code{#f}) -Specifies whether challenge response authentication is allowed (e.g.@: via -PAM). - -@item @code{use-pam?} (predeterminado: @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?} (predeterminado: @code{#t}) -Especifica si @command{sshd} debe imprimir la fecha y hora del último -ingreso al sistema de la usuaria cuando una usuaria ingresa -interactivamente. - -@item @code{subsystems} (predeterminados: @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} (predeterminado: @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} (predeterminadas: @code{'()}) -@cindex claves autorizadas, SSH -@cindex SSH, claves autorizadas -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} (predeterminado: @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} (predeterminado: @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 {Procedimiento Scheme} 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{} -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 {Tipo de datos} dropbear-configuration -This data type represents the configuration of a Dropbear SSH daemon. - -@table @asis -@item @code{dropbear} (predeterminado: @var{dropbear}) -El paquete de Dropbear usado. - -@item @code{port-number} (predeterminado: 22) -Puerto TCP donde el daemon espera conexiones entrantes. - -@item @code{syslog-output?} (predeterminado: @code{#t}) -Whether to enable syslog output. - -@item @code{pid-file} (predeterminado: @code{"/var/run/dropbear.pid"}) -File name of the daemon's PID file. - -@item @code{root-login?} (predeterminado: @code{#f}) -Whether to allow @code{root} logins. - -@item @code{allow-empty-passwords?} (predeterminado: @code{#f}) -Whether to allow empty passwords. - -@item @code{password-authentication?} (predeterminado: @code{#t}) -Whether to enable password-based authentication. -@end table -@end deftp - -@defvr {Variable Scheme} %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{Referencia de ``operating-system'', -@file{/etc/hosts}}): - -@example -(use-modules (gnu) (guix)) - -(operating-system - (host-name "micompu") - ;; ... - (hosts-file - ;; Crea un fichero /etc/hosts file con alias para "localhost" - ;; y "micompu", así como los servidores de facebook. - (plain-file "hosts" - (string-append (local-host-aliases host-name) - %facebook-host-aliases)))) -@end example - -Este mecanismo puede impedir a los programas que se ejecutan localmente, -como navegadores Web, el acceso a Facebook. -@end defvr - -El módulo @code{(gnu services avahi)} proporciona la siguiente definición. - -@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{Selector de servicios de nombres}, 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 {Variable Scheme} 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 {Tipo de datos} 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} (predeterminado: @var{openvswitch}) -Package object of the Open vSwitch. - -@end table -@end deftp - -@node Sistema X Window -@subsection Sistema X Window - -@cindex X11 -@cindex Sistema de ventanas X -@cindex gestor de ingreso en el sistema -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 the GNOME Display Manager (GDM). - -@cindex GDM -@cindex GNOME, login manager -GDM of course allows users to log in into window managers and desktop -environments other than GNOME; for those using GNOME, GDM is required for -features such as automatic screen locking. - -@cindex gestor de ventanas -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{Referencia de ``operating-system'', system-wide packages}). - -@defvr {Scheme Variable} gdm-service-type -This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME -Desktop Manager} (GDM), a program that manages graphical display servers and -handles graphical user logins. Its value must be a @code{gdm-configuration} -(see below.) - -@cindex tipos de sesión (X11) -@cindex X11, tipos de sesión -GDM 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. Packages such as @code{gnome}, -@code{xfce}, and @code{i3} 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} gdm-configuration -@table @asis -@item @code{auto-login?} (predeterminado: @code{#f}) -@itemx @code{default-user} (default: @code{#f}) -When @code{auto-login?} is false, GDM presents a log-in screen. - -When @code{auto-login?} is true, GDM logs in directly as -@code{default-user}. - -@item @code{gnome-shell-assets} (default: ...) -List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. - -@item @code{xorg-configuration} (default: @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xsession} (default: @code{(xinitrc)}) -Script to run before starting a X session. - -@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper}) -File name of the @code{dbus-daemon} executable. - -@item @code{gdm} (default: @code{gdm}) -The GDM package to use. -@end table -@end deftp - -@defvr {Variable Scheme} slim-service-type -Este es el tipo para el gestor de ingreso al sistema gráfico para X11 SLiM. - -Like GDM, SLiM looks for session types described by @file{.desktop} files -and allows users to choose a session from the log-in screen using @kbd{F1}. -It also honors @file{~/.xsession} files. -@end defvr - -@deftp {Tipo de datos} slim-configuration -Data type representing the configuration of @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (predeterminado: @code{#t}) -Whether to allow logins with empty passwords. - -@item @code{auto-login?} (predeterminado: @code{#f}) -@itemx @code{default-user} (predeterminado: @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} (predeterminado: @code{%default-slim-theme}) -@itemx @code{theme-name} (predeterminado: @code{%default-slim-theme-name}) -The graphical theme to use and its name. - -@item @code{auto-login-session} (predeterminado: @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 Nota -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{xorg-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xauth} (predeterminado: @code{xauth}) -El paquete XAuth usado. - -@item @code{shepherd} (predeterminado: @code{shepherd}) -The Shepherd package used when invoking @command{halt} and @command{reboot}. - -@item @code{sessreg} (predeterminado: @code{sessreg}) -The sessreg package used in order to register the session. - -@item @code{slim} (predeterminado: @code{slim}) -El paquete SLiM usado. -@end table -@end deftp - -@defvr {Variable Scheme} %default-theme -@defvrx {Variable Scheme} %default-theme-name -The default SLiM theme and its name. -@end defvr - - -@deftp {Tipo de datos} sddm-configuration -This is the data type representing the sddm service configuration. - -@table @asis -@item @code{display-server} (predeterminado: "x11") -Select display server to use for the greeter. Valid values are "x11" or -"wayland". - -@item @code{numlock} (predeterminado: "on") -Valid values are "on", "off" or "none". - -@item @code{halt-command} (predeterminado @code{#~(string-apppend #$shepherd "/sbin/halt")}) -Command to run when halting. - -@item @code{reboot-command} (predeterminado @code{#~(string-append #$shepherd "/sbin/reboot")}) -Command to run when rebooting. - -@item @code{theme} (predeterminado "maldives") -Theme to use. Default themes provided by SDDM are "elarun" or "maldives". - -@item @code{themes-directory} (predeterminado "/run/current-system/profile/share/sddm/themes") -Directory to look for themes. - -@item @code{faces-directory} (predeterminado "/run/current-system/profile/share/sddm/faces") -Directory to look for faces. - -@item @code{default-path} (predeterminado "/run/current-system/profile/bin") -Default PATH to use. - -@item @code{minimum-uid} (predeterminado 1000) -Minimum UID to display in SDDM. - -@item @code{maximum-uid} (predeterminado 2000) -Maximum UID to display in SDDM - -@item @code{remember-last-user?} (predeterminado #t) -Remember last user. - -@item @code{remember-last-session?} (predeterminado #t) -Remember last session. - -@item @code{hide-users} (predeterminado "") -Usernames to hide from SDDM greeter. - -@item @code{hide-shells} (predeterminado @code{#~(string-append #$shadow "/sbin/nologin")}) -Users with shells listed will be hidden from the SDDM greeter. - -@item @code{session-command} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) -Script to run before starting a wayland session. - -@item @code{sessions-directory} (predeterminado "/run/current-system/profile/share/wayland-sessions") -Directory to look for desktop files starting wayland sessions. - -@item @code{xorg-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xauth-path} (predeterminado @code{#~(string-append #$xauth "/bin/xauth")}) -Path to xauth. - -@item @code{xephyr-path} (predeterminado @code{#~(string-append #$xorg-server "/bin/Xephyr")}) -Path to Xephyr. - -@item @code{xdisplay-start} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) -Script to run after starting xorg-server. - -@item @code{xdisplay-stop} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) -Script to run before stopping xorg-server. - -@item @code{xsession-command} (predeterminado: @code{xinitrc}) -Script to run before starting a X session. - -@item @code{xsessions-directory} (predeterminado: "/run/current-system/profile/share/xsessions") -Directory to look for desktop files starting X sessions. - -@item @code{minimum-vt} (predeterminado: 7) -Minimum VT to use. - -@item @code{auto-login-user} (predeterminado "") -User to use for auto-login. - -@item @code{auto-login-session} (predeterminado "") -Desktop file to use for auto-login. - -@item @code{relogin?} (predeterminado #f) -Relogin after logout. - -@end table -@end deftp - -@cindex gestor de ingreso en el sistema -@cindex X11, ingreso al sistema -@deffn {Procedimiento Scheme} sddm-service config -Return a service that spawns the SDDM graphical login manager for config of -type @code{}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alicia") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@cindex Xorg, configuration -@deftp {Data Type} xorg-configuration -This data type represents the configuration of the Xorg graphical display -server. Note that there is not Xorg service; instead, the X server is -started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the -configuration of these display managers aggregates an -@code{xorg-configuration} record. - -@table @asis -@item @code{modules} (default: @code{%default-xorg-modules}) -This is a list of @dfn{module packages} loaded by the Xorg server---e.g., -@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. - -@item @code{fonts} (default: @code{%default-xorg-fonts}) -This is a list of font directories to add to the server's @dfn{font path}. - -@item @code{drivers} (default: @code{'()}) -This 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")}. - -@item @code{resolutions} (default: @code{'()}) -When @code{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))}. - -@cindex keyboard layout, for Xorg -@cindex keymap, for Xorg -@item @code{keyboard-layout} (predeterminada: @code{#f}) -If this is @code{#f}, Xorg uses the default keyboard layout---usually US -English (``qwerty'') for a 105-key PC keyboard. - -Otherwise this must be a @code{keyboard-layout} object specifying the -keyboard layout in use when Xorg is running. @xref{Distribución de teclado}, for -more information on how to specify the keyboard layout. - -@item @code{extra-config} (default: @code{'()}) -This 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. - -@item @code{server} (default: @code{xorg-server}) -This is the package providing the Xorg server. - -@item @code{server-arguments} (default: @code{%default-xorg-server-arguments}) -This is the list of command-line arguments to pass to the X server. The -default is @code{-nolisten tcp}. -@end table -@end deftp - -@deffn {Scheme Procedure} set-xorg-configuration @var{config} @ - [@var{login-manager-service-type}] Tell the log-in manager (of type -@var{login-manager-service-type}) to use @var{config}, an - record. - -Since the Xorg configuration is embedded in the log-in manager's -configuration---e.g., @code{gdm-configuration}---this procedure provides a -shorthand to set the Xorg configuration. -@end deffn - -@deffn {Scheme Procedure} xorg-start-command [@var{config}] -Return a @code{startx} script in which the modules, fonts, etc. specified in -@var{config}, are available. The result should be used in place of -@code{startx}. - -Usually the X server is started by a login manager. -@end deffn - - -@deffn {Procedimiento Scheme} screen-locker-service @var{paquete} [@var{programa}] -Añade @var{paquete}, un paquete para un bloqueador de sesión o un -salvapantallas cuya orden es @var{programa}, al conjunto de programas setuid -y añade una entrada PAM para él. Por ejemplo: - -@lisp -(screen-locker-service xlockmore "xlock") -@end lisp - -permite usar el viejo XlockMore. -@end deffn - - -@node Servicios de impresión -@subsection Servicios de impresión - -@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 {Variable Scheme} 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 -El paquete CUPS. -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{#f} -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browsing? -Specifies whether shared printers are advertised. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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}. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 -El paquete CUPS. -@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 Servicios de escritorio -@subsection Servicios de escritorio - -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 {Variable Scheme} %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{Sistema X Window, -@code{gdm-service-type}}), screen lockers, a network management tool -(@pxref{Servicios de red, @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{Servicios de red}), the Avahi daemon, and has the -name service switch service configured to be able to use @code{nss-mdns} -(@pxref{Selector de servicios de nombres, mDNS}). -@end defvr - -The @var{%desktop-services} variable can be used as the @code{services} -field of an @code{operating-system} declaration (@pxref{Referencia de ``operating-system'', @code{services}}). - -Additionally, the @code{gnome-desktop-service-type}, -@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-type} -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 GDM as 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. - -@defvr {Scheme Variable} gnome-desktop-service-type -This is the type of the service that adds the @uref{https://www.gnome.org, -GNOME} desktop environment. Its value is a -@code{gnome-desktop-configuration} object (see below.) - -This service adds the @code{gnome} package to the system profile, and -extends polkit with the actions from @code{gnome-settings-daemon}. -@end defvr - -@deftp {Data Type} gnome-desktop-configuration -Configuration record for the GNOME desktop environment. - -@table @asis -@item @code{gnome} (default @code{gnome}) -The GNOME package to use. -@end table -@end deftp - -@defvr {Scheme Variable} xfce-desktop-service-type -This is the type of a service to run the @uref{Xfce, https://xfce.org/} -desktop environment. Its value is an @code{xfce-desktop-configuration} -object (see below.) - -This 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 defvr - -@deftp {Data Type} xfce-desktop-configuration -Configuration record for the Xfce desktop environment. - -@table @asis -@item @code{xfce} (default @code{xfce}) -The Xfce package to use. -@end table -@end deftp - -@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 {Tipo de datos} enlightenment-desktop-service-configuration -@table @asis -@item @code{enlightenment} (predeterminado @code{enlightenment}) -El paquete enlightenment usado. -@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* (service gnome-desktop-service-type) - (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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 {Variable Scheme} %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 {Procedimiento Scheme} 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 {Procedimiento Scheme} 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 Servicios de sonido -@subsection Servicios de sonido - -@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 {Variable Scheme} 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 {Tipo de datos} alsa-configuration -Data type representing the configuration for @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (predeterminados: @var{alsa-plugins}) -El paquete @code{alsa-plugins} usado. - -@item @code{pulseaudio?} (predeterminado: @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} (predeterminado: @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: -# . -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 Servicios de bases de datos -@subsection Servicios de bases de datos - -@cindex base de datos -@cindex SQL -El módulo @code{(gnu services databases)} proporciona los siguientes -servicios. - -@deffn {Procedimiento Scheme} 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 {Procedimiento Scheme} mysql-service [#:config (mysql-configuration)] -Return a service that runs @command{mysqld}, the MySQL or MariaDB database -server. - -El parámetro opcional @var{config} especifica la configuración para -@command{mysqld}, que debe ser un objeto @code{}. -@end deffn - -@deftp {Tipo de datos} mysql-configuration -Data type representing the configuration of @var{mysql-service}. - -@table @asis -@item @code{mysql} (predeterminado: @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} (predeterminado: @code{3306}) -TCP port on which the database server listens for incoming connections. -@end table -@end deftp - -@defvr {Variable Scheme} 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 {Tipo de datos} memcached-configuration -Data type representing the configuration of memcached. - -@table @asis -@item @code{memcached} (predeterminado: @code{memcached}) -El paquete de Memcached usado. - -@item @code{interfaces} (predeterminadas: @code{'("0.0.0.0")}) -Network interfaces on which to listen. - -@item @code{tcp-port} (predeterminado: @code{11211}) -Port on which to accept connections on, - -@item @code{udp-port} (predeterminado: @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} (predeterminadas: @code{'()}) -Additional command line options to pass to @code{memcached}. -@end table -@end deftp - -@defvr {Variable Scheme} 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 {Tipo de datos} mongodb-configuration -Tipo de datos que representa la configuración de GPM. - -@table @asis -@item @code{mongodb} (predeterminado: @code{mongodb}) -El paquete MongoDB usado. - -@item @code{config-file} (predeterminado: @code{%default-mongodb-configuration-file}) -The configuration file for MongoDB. - -@item @code{data-directory} (predeterminado: @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 {Variable Scheme} 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 {Tipo de datos} redis-configuration -Data type representing the configuration of redis. - -@table @asis -@item @code{redis} (predeterminado: @code{redis}) -The Redis package to use. - -@item @code{bind} (predeterminada: @code{"127.0.0.1"}) -La interfaz de red en la que se escucha. - -@item @code{port} (predeterminado: @code{6379}) -Port on which to accept connections on, a value of 0 will disable listening -on a TCP socket. - -@item @code{working-directory} (predeterminado: @code{"/var/lib/redis"}) -Directory in which to store the database and related files. -@end table -@end deftp - -@node Servicios de correo -@subsection Servicios de correo - -@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 Servicio Dovecot - -@deffn {Procedimiento Scheme} 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. - -Por ejemplo, para especificar que el correo se encuentra en -@code{maildir:~/.correo}, se debe instanciar el servicio de Dovecot de esta -manera: - -@example -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.correo"))) -@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 -El paquete dovecot. -@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 -El nombre del protocolo. -@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. - -El valor predeterminado es @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. . 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. - -El valor predeterminado es @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 . 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. . -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 -Tamaño físico -@item %w -Tamaño virtual. -@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 -El valor predeterminado es @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. . Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-gid - -El valor predeterminado es @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 - -El valor predeterminado es @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 - -El valor predeterminado es @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. . 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}. -. 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 .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. . 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{" 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 -número total de bytes leídos del cliente -@item %o -número total de bytes enviados al cliente. -@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 -(' 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} (predeterminado: @code{#f}) -Must be a @code{} 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} (predeterminado: @code{#f}) -Optional alternative override for this configuration. -@end table -@end deftp - -@deftp {Tipo de datos} 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} (predeterminado: @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 Servicios de monitorización -@subsection Servicios de monitorización - -@subsubheading Servicio Tailon - -@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 {Tipo de datos} tailon-configuration -Data type representing the configuration of Tailon. This type has the -following parameters: - -@table @asis -@item @code{config-file} (predeterminado: @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{Expresiones-G}). - -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 "./mi-tailon.conf")))) -@end example - -@item @code{package} (predeterminado: @code{tailon}) -El paquete tailon usado. - -@end table -@end deftp - -@deftp {Tipo de datos} tailon-configuration-file -Tipo de datos que representa las opciones de configuración de Tailon. Este -tipo tiene los siguientes parámetros: - -@table @asis -@item @code{files} (predeterminados: @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} (predeterminado: @code{"localhost:8080"}) -Address and port to which Tailon should bind on. - -@item @code{relative-root} (predeterminado: @code{#f}) -URL path to use for Tailon, set to @code{#f} to not use a path. - -@item @code{allow-transfers?} (predeterminado: @code{#t}) -Allow downloading the log files in the web interface. - -@item @code{follow-names?} (predeterminado: @code{#t}) -Allow tailing of not-yet existent files. - -@item @code{tail-lines} (predeterminado: @code{200}) -Number of lines to read initially from each file. - -@item @code{allowed-commands} (predeterminadas: @code{(list "tail" "grep" "awk")}) -Órdenes cuya ejecución está permitida. Por defecto, @code{sed} está -deshabilitado. - -@item @code{debug?} (predeterminado: @code{#f}) -Set @code{debug?} to @code{#t} to show debug messages. - -@item @code{wrap-lines} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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 '(("usuaria1" . "contraseña1") - ("usuaria2" . "contraseña2")))) -@end example - -@end table -@end deftp - - -@subsubheading Servicio Darkstat -@cindex darkstat -Darkstat is a packet sniffer that captures network traffic, calculates -statistics about usage, and serves reports over HTTP. - -@defvar {Variable Scheme} 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 {Tipo de datos} darkstat-configuration -Tipo de datos que representa la configuración de @command{darkstat}. - -@table @asis -@item @code{package} (predeterminado: @code{darkstat}) -El paquete darkstat usado. - -@item @code{interface} -Captura el tráfico en la interfaz de red especificada. - -@item @code{port} (predeterminado: @code{"667"}) -Bind the web interface to the specified port. - -@item @code{bind-address} (predeterminada: @code{"127.0.0.1"}) -Bind the web interface to the specified address. - -@item @code{base} (predeterminada: @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 Servicio del exportador de nodos Prometheus - -@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 {Variable Scheme} 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 {Tipo de datos} prometheus-node-exporter-configuration -Tipo de datos que representa la configuración de @command{node_exporter}. - -@table @asis -@item @code{package} (predeterminado: @code{go-github-com-prometheus-node-exporter}) -El paquete prometheus-node-exporter usado. - -@item @code{web-listen-address} (predeterminada: @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. - -El valor predeterminado es @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 - -El valor predeterminado es @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. - -El valor predeterminado es @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 - -El valor predeterminado es @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. - -El valor predeterminado es @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 -Configuración de NGINX. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 Servicios Kerberos -@subsection Servicios Kerberos -@cindex Kerberos - -The @code{(gnu services kerberos)} module provides services relating to the -authentication protocol @dfn{Kerberos}. - -@subsubheading Servicio Krb5 - -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 {Variable Scheme} krb5-service-type -A service type for Kerberos 5 clients. -@end defvr - -@noindent -Este es un ejemplo de su uso: -@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 {Tipo de datos} 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 {Tipo de datos} krb5-configuration - -@table @asis -@item @code{allow-weak-crypto?} (predeterminado: @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} (predeterminado: @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 Servicio PAM krb5 -@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 {Variable Scheme} pam-krb5-service-type -A service type for the Kerberos 5 PAM module. -@end defvr - -@deftp {Tipo de datos} 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} (predeterminado: @code{pam-krb5}) -El paquete pam-krb5 usado. - -@item @code{minimum-uid} (predeterminado: @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 Servicios LDAP -@subsection Servicios LDAP -@cindex LDAP -@cindex nslcd, LDAP service - -The @code{(gnu services authentication)} module provides the -@code{nslcd-service-type}, which can be used to authenticate against an LDAP -server. In addition to configuring the service itself, you may want to add -@code{ldap} as a name service to the Name Service Switch. @xref{Selector de servicios de nombres} for detailed information. - -Here is a simple operating system declaration with a default configuration -of the @code{nslcd-service-type} and a Name Service Switch configuration -that consults the @code{ldap} name service last: - -@example -(use-service-modules authentication) -(use-modules (gnu system nss)) -... -(operating-system - ... - (services - (cons* - (service nslcd-service-type) - (service dhcp-client-service-type) - %base-services)) - (name-service-switch - (let ((services (list (name-service (name "db")) - (name-service (name "files")) - (name-service (name "ldap"))))) - (name-service-switch - (inherit %mdns-host-lookup-nss) - (password services) - (shadow services) - (group services) - (netgroup services) - (gshadow services))))) -@end example - -@c %start of generated documentation for nslcd-configuration - -Available @code{nslcd-configuration} fields are: - -@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd -The @code{nss-pam-ldapd} package to use. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads -The number of threads to start that can handle requests and perform LDAP -queries. Each thread opens a separate connection to the LDAP server. The -default is to start 5 threads. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string uid -This specifies the user id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string gid -This specifies the group id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} log-option log -This option controls the way logging is done via a list containing SCHEME -and LEVEL. The SCHEME argument may either be the symbols "none" or -"syslog", or an absolute file name. The LEVEL argument is optional and -specifies the log level. The log level may be one of the following symbols: -"crit", "error", "warning", "notice", "info" or "debug". All messages with -the specified log level or higher are logged. - -Defaults to @samp{("/var/log/nslcd" info)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list uri -The list of LDAP server URIs. Normally, only the first server will be used -with the following servers as fall-back. - -Defaults to @samp{("ldap://localhost:389/")}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version -The version of the LDAP protocol to use. The default is to use the maximum -version supported by the LDAP library. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn -Specifies the distinguished name with which to bind to the directory server -for lookups. The default is to bind anonymously. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw -Specifies the credentials with which to bind. This option is only -applicable when used with binddn. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn -Specifies the distinguished name to use when the root user tries to modify a -user's password using the PAM module. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw -Specifies the credentials with which to bind if the root user tries to -change a user's password. This option is only applicable when used with -rootpwmoddn - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech -Specifies the SASL mechanism to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm -Specifies the SASL realm to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid -Specifies the authentication identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid -Specifies the authorization identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? -Determines whether the LDAP server host name should be canonicalised. If -this is enabled the LDAP library will do a reverse host name lookup. By -default, it is left up to the LDAP library whether this check is performed -or not. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname -Set the name for the GSS-API Kerberos credentials cache. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string base -The directory search base. - -Defaults to @samp{"dc=example,dc=com"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} scope-option scope -Specifies the search scope (subtree, onelevel, base or children). The -default scope is subtree; base scope is almost never useful for name service -lookups; children scope is not supported on all servers. - -Defaults to @samp{(subtree)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref -Specifies the policy for dereferencing aliases. The default policy is to -never dereference aliases. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals -Specifies whether automatic referral chasing should be enabled. The default -behaviour is to chase referrals. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps -This option allows for custom attributes to be looked up instead of the -default RFC 2307 attributes. It is a list of maps, each consisting of the -name of a map, the RFC 2307 attribute to match and the query expression for -the attribute as it is available in the directory. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters -A list of filters consisting of the name of a map to which the filter -applies and an LDAP search filter expression. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit -Specifies the time limit in seconds to use when connecting to the directory -server. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit -Specifies the time limit (in seconds) to wait for a response from the LDAP -server. A value of zero, which is the default, is to wait indefinitely for -searches to be completed. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit -Specifies the period if inactivity (in seconds) after which the con‐ nection -to the LDAP server will be closed. The default is not to time out -connections. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime -Specifies the number of seconds to sleep when connecting to all LDAP servers -fails. By default one second is waited between the first failure and the -first retry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime -Specifies the time after which the LDAP server is considered to be -permanently unavailable. Once this time is reached retries will be done -only once per this time period. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl -Specifies whether to use SSL/TLS or not (the default is not to). If -'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert -Specifies what checks to perform on a server-supplied certificate. The -meaning of the values is described in the ldap.conf(5) manual page. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir -Specifies the directory containing X.509 certificates for peer authen‐ -tication. This parameter is ignored when using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile -Specifies the path to the X.509 certificate for peer authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile -Specifies the path to an entropy source. This parameter is ignored when -using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers -Specifies the ciphers to use for TLS as a string. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert -Specifies the path to the file containing the local certificate for client -TLS authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key -Specifies the path to the file containing the private key for client TLS -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize -Set this to a number greater than 0 to request paged results from the LDAP -server in accordance with RFC2696. The default (0) is to not request paged -results. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers -This option prevents group membership lookups through LDAP for the specified -users. Alternatively, the value 'all-local may be used. With that value -nslcd builds a full list of non-LDAP users on startup. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid -This option ensures that LDAP users with a numeric user id lower than the -specified value are ignored. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset -This option specifies an offset that is added to all LDAP numeric user ids. -This can be used to avoid user id collisions with local users. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset -This option specifies an offset that is added to all LDAP numeric group -ids. This can be used to avoid user id collisions with local groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups -If this option is set, the member attribute of a group may point to another -group. Members of nested groups are also returned in the higher level group -and parent groups are returned when finding groups for a specific user. The -default is not to perform extra searches for nested groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers -If this option is set, the group member list is not retrieved when looking -up groups. Lookups for finding which groups a user belongs to will remain -functional so the user will likely still get the correct groups assigned on -login. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration -If this option is set, functions which cause all user/group entries to be -loaded from the directory will not succeed in doing so. This can -dramatically reduce LDAP server load in situations where there are a great -number of users and/or groups. This option is not recommended for most -configurations. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames -This option can be used to specify how user and group names are verified -within the system. This pattern is used to check all user and group names -that are requested and returned from LDAP. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase -This specifies whether or not to perform searches using case-insensitive -matching. Enabling this could open up the system to authorization bypass -vulnerabilities and introduce nscd cache poisoning vulnerabilities which -allow denial of service. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy -This option specifies whether password policy controls are requested and -handled from the LDAP server when performing user authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search -By default nslcd performs an LDAP search with the user's credentials after -BIND (authentication) to ensure that the BIND operation was successful. The -default search is a simple check to see if the user's DN exists. A search -filter can be specified that will be used instead. It should return at -least one entry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search -This option allows flexible fine tuning of the authorisation check that -should be performed. The search filter specified is executed and if any -entries match, access is granted, otherwise access is denied. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message -If this option is set password modification using pam_ldap will be denied -and the specified message will be presented to the user instead. The -message can be used to direct the user to an alternative means of changing -their password. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list pam-services -List of pam service names for which LDAP authentication should suffice. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of generated documentation for nslcd-configuration - - -@node Servicios Web -@subsection Servicios Web - -@cindex web -@cindex www -@cindex HTTP -El módulo @code{(gnu services web)} proporciona el servidor HTTP Apache, el -servidor web nginx y también un recubrimiento del daemon de fastcgi. - -@subsubheading Servidor HTTP Apache - -@deffn {Variable Scheme} 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 'mi-servidor-extra 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 {Tipo de datos} httpd-configuration -This data type represents the configuration for the httpd service. - -@table @asis -@item @code{package} (predeterminado: @code{httpd}) -El paquete httpd usado. - -@item @code{pid-file} (predeterminado: @code{"/var/run/httpd"}) -El fichero pid usado por el servicio de Shepherd. - -@item @code{config} (predeterminado: @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 {Tipo de datos} 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 {Variable Scheme} %default-httpd-modules -A default list of @code{httpd-module} objects. -@end defvr - -@deffn {Tipo de datos} httpd-config-file -This data type represents a configuration file for the httpd service. - -@table @asis -@item @code{modules} (predeterminados: @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 "\ - - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (predeterminado: @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} (predeterminado: @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} (predeterminado: @code{"/srv/http"}) -The @code{DocumentRoot} from which files will be served. - -@item @code{listen} (predeterminado: @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} (predeterminado: @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} (predeterminado: @code{"/var/log/httpd/error_log"}) -The @code{ErrorLog} to which the server will log errors. - -@item @code{user} (predeterminada: @code{"httpd"}) -La usuaria como la que el servidor responderá a las peticiones. - -@item @code{group} (predeterminado: @code{"httpd"}) -El grupo como el que el servidor responderá a las peticiones. - -@item @code{extra-config} (predeterminadas: @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 {Tipo de datos} 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 'mi-servidor-extra 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 {Variable Scheme} nginx-service-type -Service type for the @uref{https://nginx.org/,NGinx} web server. The value -for this service type is a @code{} 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 'mi-servidor-extra nginx-service-type - (list (nginx-server-configuration - (root "/srv/http/sitio-extra") - (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 {Tipo de datos} 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} (predeterminado: @code{nginx}) -El paquete nginx usado. - -@item @code{log-directory} (predeterminado: @code{"/var/log/nginx"}) -The directory to which NGinx will write log files. - -@item @code{run-directory} (predeterminado: @code{"/var/run/nginx"}) -The directory in which NGinx will create a pid file, and write temporary -files. - -@item @code{server-blocks} (predeterminados: @code{'()}) -A list of @dfn{server blocks} to create in the generated configuration file, -the elements should be of type @code{}. - -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} (predeterminados: @code{'()}) -A list of @dfn{upstream blocks} to create in the generated configuration -file, the elements should be of type @code{}. - -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{} -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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @code{#f}) -Maximum bucket size for the server names hash tables. - -@item @code{extra-content} (predeterminado: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. - -@end table -@end deffn - -@deftp {Tipo de datos} nginx-server-configuration -Data type representing the configuration of an nginx server block. This -type has the following parameters: - -@table @asis -@item @code{listen} (predeterminadas: @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} (predeterminados: @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} (predeterminada: @code{"/srv/http"}) -Raíz del sitio web que nginx proporcionará. - -@item @code{locations} (predeterminado: @code{'()}) -A list of @dfn{nginx-location-configuration} or -@dfn{nginx-named-location-configuration} records to use within this server -block. - -@item @code{index} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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?} (predeterminado: @code{#f}) -Whether the server should add its configuration to response. - -@item @code{raw-content} (predeterminado: @code{'()}) -A list of raw lines added to the server block. - -@end table -@end deftp - -@deftp {Tipo de datos} 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 {Tipo de datos} 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 {Tipo de datos} 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 {Variable Scheme} varnish-service-type -Service type for the Varnish daemon. -@end defvr - -@deftp {Tipo de datos} varnish-configuration -Data type representing the @code{varnish} service configuration. This type -has the following parameters: - -@table @asis -@item @code{package} (predeterminado: @code{varnish}) -El paquete Varnish usado. - -@item @code{name} (predeterminado: @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} (predeterminado: @code{"localhost:8080"}) -The backend to use. This option has no effect if @code{vcl} is set. - -@item @code{vcl} (predeterminado: #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 %espejo-gnu - (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 %espejo-gnu))) - %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} (predeterminada: @code{'("localhost:80")}) -Lista de direcciones en las que Varnish escucha. - -@item @code{storage} (predeterminado: @code{'("malloc,128m")}) -List of storage backends that will be available in VCL. - -@item @code{parameters} (predeterminados: @code{'()}) -List of run-time parameters in the form @code{'(("parameter" . "value"))}. - -@item @code{extra-options} (predeterminadas: @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 {Variable Scheme} fcgiwrap-service-type -A service type for the @code{fcgiwrap} FastCGI proxy. -@end defvr - -@deftp {Tipo de datos} fcgiwrap-configuration -Data type representing the configuration of the @code{fcgiwrap} service. -This type has the following parameters: -@table @asis -@item @code{package} (predeterminado: @code{fcgiwrap}) -El paquete fcgiwrap usado. - -@item @code{socket} (predeterminado: @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} (predeterminado: @code{fcgiwrap}) -@itemx @code{group} (predeterminado: @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 {Variable Scheme} php-fpm-service-type -Un tipo de servicio para @code{php-fpm}. -@end defvr - -@deftp {Tipo de datos} php-fpm-configuration -Tipo de datos para la configuración del servicio php-fpm. -@table @asis -@item @code{php} (predeterminado: @code{php}) -El paquete php usado. -@item @code{socket} (predeterminado: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) -La dirección desde la que FastCGI acepta peticiones. Las sintaxis válidas -son: -@table @asis -@item @code{"dir.ecc.ión.ip:puerto"} -Escucha con un socket TCP en la dirección especificada en un puerto -específico. -@item @code{"puerto"} -Escucha en un socket TCP en todas las direcciones sobre un puerto -específico. -@item @code{"/ruta/a/socket/unix"} -Escucha en un socket Unix. -@end table - -@item @code{user} (predeterminada: @code{php-fpm}) -User who will own the php worker processes. -@item @code{group} (predeterminado: @code{php-fpm}) -Group of the worker processes. -@item @code{socket-user} (predeterminado: @code{php-fpm}) -User who can speak to the php-fpm socket. -@item @code{socket-group} (predeterminado: @code{php-fpm}) -Group that can speak to the php-fpm socket. -@item @code{pid-file} (predeterminado: @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} (predeterminado: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) -Log for the php-fpm master process. -@item @code{process-manager} (predeterminado: @code{(php-fpm-dynamic-process-manager-configuration)}) -Detailed settings for the php-fpm process manager. Must be either: -@table @asis -@item @code{} -@item @code{} -@item @code{} -@end table -@item @code{display-errors} (predeterminado @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} (predeterminado @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} (predeterminado @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 {Tipo de datos} 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} (predeterminados: @code{5}) -Maximum of worker processes. -@item @code{start-servers} (predeterminados: @code{2}) -How many worker processes should be started on start-up. -@item @code{min-spare-servers} (predeterminado: @code{1}) -How many spare worker processes should be kept around at minimum. -@item @code{max-spare-servers} (predeterminados: @code{3}) -How many spare worker processes should be kept around at maximum. -@end table -@end deftp - -@deftp {Tipo de datos} 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} (predeterminados: @code{5}) -Maximum of worker processes. -@end table -@end deftp - -@deftp {Tipo de datos} 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} (predeterminados: @code{5}) -Maximum of worker processes. -@item @code{process-idle-timeout} (predeterminado: @code{10}) -The time in seconds after which a process with no requests is killed. -@end table -@end deftp - - -@deffn {Procedimiento Scheme} 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 {Variable Scheme} hpcguix-web-service-type -El tipo de servicio para @code{hpcguix-web}. -@end defvr - -@deftp {Tipo de datos} hpcguix-web-configuration -El tipo de datos para la configuración del servicio hpcguix-web. - -@table @asis -@item @code{specs} -A gexp (@pxref{Expresiones-G}) specifying the hpcguix-web service -configuration. The main items available in this spec are: - -@table @asis -@item @code{title-prefix} (predeterminado: @code{"hpcguix | "}) -El prefijo del título de la página. - -@item @code{guix-command} (predeterminada: @code{"guix"}) -La orden @command{guix}. - -@item @code{package-filter-proc} (predeterminado: @code{(const #t)}) -A procedure specifying how to filter packages that are displayed. - -@item @code{package-page-extension-proc} (predeterminado: @code{(const '())}) -Extension package for @code{hpcguix-web}. - -@item @code{menu} (predeterminadas: @code{'()}) -Entradas adicionales en el menú de la página. - -@item @code{channels} (predeterminados: @code{%default-channels}) -List of channels from which the package list is built (@pxref{Canales}). - -@item @code{package-list-expiration} (predeterminado: @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} (predeterminado: @code{hpcguix-web}) -The hpcguix-web package to use. -@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 Nota -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{Certificados X.509}, -for more information on X.509 certificates. -@end quotation - -@node Servicios de certificados -@subsection Servicios de certificados - -@cindex Web -@cindex HTTP, HTTPS -@cindex Let's Encrypt -@cindex certificados TLS -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 {Variable Scheme} 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 {Tipo de datos} certbot-configuration -Data type representing the configuration of the @code{certbot} service. -This type has the following parameters: - -@table @asis -@item @code{package} (predeterminado: @code{certbot}) -El paquete certbot usado. - -@item @code{webroot} (predeterminado: @code{/var/www}) -The directory from which to serve the Let's Encrypt challenge/response -files. - -@item @code{certificates} (predeterminados: @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} (predeterminado: @code{2048}) -Tamaño de la clave RSA. - -@item @code{default-location} (predeterminada: @i{vea a continuación}) -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{Servicios Web}, 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 {Tipo de datos} certificate-configuration -Data type representing the configuration of a certificate. This type has -the following parameters: - -@table @asis -@item @code{name} (predeterminado: @i{vea a continuación}) -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} (predeterminado: @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} (predeterminado: @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 Servicios DNS -@subsection Servicios DNS -@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 Servicio Knot - -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 {Variable Scheme} 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 {Tipo de datos} knot-key-configuration -Data type representing a key. This type has the following parameters: - -@table @asis -@item @code{id} (predeterminado: @code{""}) -An identifier for other configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{algorithm} (predeterminado: @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} (predeterminado: @code{""}) -The secret key itself. - -@end table -@end deftp - -@deftp {Tipo de datos} knot-acl-configuration -Data type representing an Access Control List (ACL) configuration. This -type has the following parameters: - -@table @asis -@item @code{id} (predeterminado: @code{""}) -An identifier for ether configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{address} (predeterminada: @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} (predeterminada: @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} (predeterminada: @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?} (predeterminado: @code{#f}) -When true, the ACL defines restrictions. Listed actions are forbidden. -When false, listed actions are allowed. - -@end table -@end deftp - -@deftp {Tipo de datos} zone-entry -Data type represnting a record entry in a zone file. This type has the -following parameters: - -@table @asis -@item @code{name} (predeterminado: @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} (predeterminado: @code{""}) -The Time-To-Live (TTL) of this record. If not set, the default TTL is used. - -@item @code{class} (predeterminada: @code{"IN"}) -The class of the record. Knot currently supports only @code{"IN"} and -partially @code{"CH"}. - -@item @code{type} (predeterminado: @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} (predeterminados: @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 {Tipo de datos} zone-file -Data type representing the content of a zone file. This type has the -following parameters: - -@table @asis -@item @code{entries} (predeterminadas: @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} (predeterminado: @code{""}) -The name of your zone. This parameter cannot be empty. - -@item @code{ns} (predeterminado: @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} (predeterminado: @code{"hostmaster"}) -An email address people can contact you at, as the owner of the zone. This -is translated as @code{@@}. - -@item @code{serial} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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 {Tipo de datos} knot-remote-configuration -Data type representing a remote configuration. This type has the following -parameters: - -@table @asis -@item @code{id} (predeterminado: @code{""}) -An identifier for other configuration fields to refer to this remote. IDs -must be unique and must not be empty. - -@item @code{address} (predeterminada: @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} (predeterminada: @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} (predeterminada: @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 {Tipo de datos} knot-keystore-configuration -Data type representing a keystore to hold dnssec keys. This type has the -following parameters: - -@table @asis -@item @code{id} (predeterminado: @code{""}) -The id of the keystore. It must not be empty. - -@item @code{backend} (predeterminado: @code{'pem}) -El motor en el que se almacenan las claves. Puede ser @code{'pem} o -@code{'pkcs11}. - -@item @code{config} (predeterminada: @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 {Tipo de datos} 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. - -Este tipo tiene los siguientes parámetros: - -@table @asis -@item @code{id} (predeterminado: @code{""}) -The id of the policy. It must not be empty. - -@item @code{keystore} (predeterminado: @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?} (predeterminado: @code{#f}) -Whether the key management is manual or automatic. - -@item @code{single-type-signing?} (predeterminado: @code{#f}) -When @code{#t}, use the Single-Type Signing Scheme. - -@item @code{algorithm} (predeterminado: @code{"ecdsap256sha256"}) -An algorithm of signing keys and issued signatures. - -@item @code{ksk-size} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @code{(* 30 24 3600)}) -The period between ZSK publication and the next rollover initiation. - -@item @code{propagation-delay} (predeterminado: @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} (predeterminado: @code{(* 14 24 3600)}) -A validity period of newly issued signatures. - -@item @code{rrsig-refresh} (predeterminado: @code{(* 7 24 3600)}) -A period how long before a signature expiration the signature will be -refreshed. - -@item @code{nsec3?} (predeterminado: @code{#f}) -When @code{#t}, NSEC3 will be used instead of NSEC. - -@item @code{nsec3-iterations} (predeterminado: @code{5}) -The number of additional times the hashing is performed. - -@item @code{nsec3-salt-length} (predeterminado: @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} (predeterminado: @code{(* 30 24 3600)}) -The validity period of newly issued salt field. - -@end table -@end deftp - -@deftp {Tipo de datos} knot-zone-configuration -Data type representing a zone served by Knot. This type has the following -parameters: - -@table @asis -@item @code{domain} (predeterminado: @code{""}) -The domain served by this configuration. It must not be empty. - -@item @code{file} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @code{#f}) -The main master. When empty, it defaults to the first master in the list of -masters. - -@item @code{notify} (predeterminado: @code{'()}) -A list of slave remote identifiers. - -@item @code{acl} (predeterminado: @code{'()}) -A list of acl identifiers. - -@item @code{semantic-checks?} (predeterminado: @code{#f}) -When set, this adds more semantic checks to the zone. - -@item @code{disable-any?} (predeterminado: @code{#f}) -When set, this forbids queries of the ANY type. - -@item @code{zonefile-sync} (predeterminado: @code{0}) -The delay between a modification in memory and on disk. 0 means immediate -synchronization. - -@item @code{serial-policy} (predeterminado: @code{'increment}) -A policy between @code{'increment} and @code{'unixtime}. - -@end table -@end deftp - -@deftp {Tipo de datos} knot-configuration -Data type representing the Knot configuration. This type has the following -parameters: - -@table @asis -@item @code{knot} (predeterminado: @code{knot}) -El paquete Knot. - -@item @code{run-directory} (predeterminado: @code{"/var/run/knot"}) -The run directory. This directory will be used for pid file and sockets. - -@item @code{listen-v4} (predeterminada: @code{"0.0.0.0"}) -La dirección IP en la que escuchar. - -@item @code{listen-v6} (predeterminada: @code{"::"}) -La dirección IP en la que escuchar. - -@item @code{listen-port} (predeterminado: @code{53}) -El puerto en el que escuchar. - -@item @code{keys} (predeterminada: @code{'()}) -The list of knot-key-configuration used by this configuration. - -@item @code{acls} (predeterminado: @code{'()}) -The list of knot-acl-configuration used by this configuration. - -@item @code{remotes} (predeterminada: @code{'()}) -The list of knot-remote-configuration used by this configuration. - -@item @code{zones} (predeterminada: @code{'()}) -The list of knot-zone-configuration used by this configuration. - -@end table -@end deftp - -@subsubheading Servicio Dnsmasq - -@deffn {Variable Scheme} 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 {Tipo de datos} dnsmasq-configuration -Data type representing the configuration of dnsmasq. - -@table @asis -@item @code{package} (predeterminado: @var{dnsmasq}) -Package object of the dnsmasq server. - -@item @code{no-hosts?} (predeterminado: @code{#f}) -When true, don't read the hostnames in /etc/hosts. - -@item @code{port} (predeterminado: @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?} (predeterminado: @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} (predeterminadas: @code{'()}) -Escucha en las direcciones IP proporcionadas. - -@item @code{resolv-file} (predeterminado: @code{"/etc/resolv.conf"}) -The file to read the IP address of the upstream nameservers from. - -@item @code{no-resolv?} (predeterminado: @code{#f}) -When true, don't read @var{resolv-file}. - -@item @code{servers} (predeterminados: @code{'()}) -Specify IP address of upstream servers directly. - -@item @code{cache-size} (predeterminado: @code{150}) -Set the size of dnsmasq's cache. Setting the cache size to zero disables -caching. - -@item @code{negative-cache?} (predeterminado: @code{#t}) -When false, disable negative caching. - -@end table -@end deftp - -@subsubheading Servicio ddclient - -@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 - -Los campos disponibles de @code{ddclient-configuration} son: - -@deftypevr {@code{ddclient-configuration} parameter} package ddclient -El paquete ddclient. - -@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 -Mail failed update to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string pid -The ddclient PID file. - -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 Servicios VPN -@subsection Servicios VPN -@cindex VPN (red virtual privada) -@cindex red virtual privada (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 {Procedimiento Scheme} openvpn-client-service @ - [#:config (openvpn-client-configuration)] - -Devuelve un servicio que ejecuta @command{openvpn}, un daemon VPN, como -cliente. -@end deffn - -@deffn {Procedimiento Scheme} openvpn-server-service @ - [#:config (openvpn-server-configuration)] - -Devuelve un servicio que ejecuta @command{openvpn}, un daemon VPN, como -servidor. - -Pueden ejecutarse simultáneamente. -@end deffn - -@c %automatically generated documentation - -Los campos disponibles de @code{openvpn-client-configuration} son: - -@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn -El paquete OpenVPN. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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{()}. - -Los campos disponibles de @code{openvpn-remote-configuration} son: - -@deftypevr {@code{openvpn-remote-configuration} parameter} string name -Nombre del servidor. - -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 -El paquete OpenVPN. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 -Nombre del cliente. - -Defaults to @samp{"client"}. - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute -Client own network - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push -Client VPN IP. - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@end deftypevr - - -@c %end of automatic openvpn-server documentation - - -@node Sistema de ficheros en red -@subsection Sistema de ficheros en red -@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 {Variable Scheme} rpcbind-service-type -A service type for the RPC portmapper daemon. -@end defvr - - -@deftp {Tipo de datos} 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 {Variable Scheme} pipefs-service-type -A service type for the pipefs pseudo file system. -@end defvr - -@deftp {Tipo de datos} 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 Servicio del daemon GSS -@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{Servicios Kerberos}). - -@defvr {Variable Scheme} gss-service-type -Un tipo de servicio para el daemon del sistema de seguridad global (GSS). -@end defvr - -@deftp {Tipo de datos} gss-configuration -Data type representing the configuration of the GSS daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (predeterminado: @code{nfs-utils}) -The package in which the @command{rpc.gssd} command is to be found. - -@item @code{pipefs-directory} (predeterminado: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@end table -@end deftp - - -@subsubheading Servicio del daemon IDMAP -@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 {Variable Scheme} idmap-service-type -A service type for the Identity Mapper (IDMAP) daemon. -@end defvr - -@deftp {Tipo de datos} idmap-configuration -Data type representing the configuration of the IDMAP daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (predeterminado: @code{nfs-utils}) -The package in which the @command{rpc.idmapd} command is to be found. - -@item @code{pipefs-directory} (predeterminado: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@item @code{domain} (predeterminado: @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 Integración continua -@subsection Integración continua - -@cindex integración continua -@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{Sustituciones}). - -El módulo @code{(gnu services cuirass)} proporciona el siguiente servicio. - -@defvr {Procedimiento Scheme} 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 {Tipo de datos} cuirass-configuration -Data type representing the configuration of Cuirass. - -@table @asis -@item @code{log-file} (predeterminado: @code{"/var/log/cuirass.log"}) -Location of the log file. - -@item @code{cache-directory} (predeterminado: @code{"/var/cache/cuirass"}) -Location of the repository cache. - -@item @code{user} (predeterminado: @code{"cuirass"}) -Owner of the @code{cuirass} process. - -@item @code{group} (predeterminado: @code{"cuirass"}) -Owner's group of the @code{cuirass} process. - -@item @code{interval} (predeterminado: @code{60}) -Number of seconds between the poll of the repositories followed by the -Cuirass jobs. - -@item @code{database} (predeterminada: @code{"/var/lib/cuirass/cuirass.db"}) -Location of sqlite database which contains the build results and previously -added specifications. - -@item @code{ttl} (predeterminado: @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} (predeterminado: @code{8081}) -Número de puerto usado por el servidor HTTP. - -@item --listen=@var{dirección} -Listen on the network interface for @var{host}. The default is to accept -connections from localhost. - -@item @code{specifications} (predeterminada: @code{#~'()}) -A gexp (@pxref{Expresiones-G}) 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?} (predeterminado: @code{#f}) -This allows using substitutes to avoid building every dependencies of a job -from source. - -@item @code{one-shot?} (predeterminado: @code{#f}) -Only evaluate specifications and build derivations once. - -@item @code{fallback?} (predeterminado: @code{#f}) -When substituting a pre-built binary fails, fall back to building packages -locally. - -@item @code{cuirass} (predeterminado: @code{cuirass}) -El paquete Cuirass usado. -@end table -@end deftp - -@node Servicios de gestión de energía -@subsection Servicios de gestión de energía - -@cindex tlp -@cindex gestión de energía con TLP -@subsubheading Daemon TLP - -El módulo @code{(gnu services pm)} proporciona una definición de servicio -Guix para la herramienta de gestión de energía de Linux 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 {Variable Scheme} 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 -El paquete TLP. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 -Dispositivos de disco duro. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@cindex thermald -@cindex escalado de frecuencia de la CPU con thermald -@subsubheading Daemon Thermald - -El módulo @code{(gnu services pm)} proporciona una interfaz con thermald, un -servicio de escalado de frecuencia de la CPU que ayuda a prevenir el -sobrecalentamiento. - -@defvr {Variable Scheme} 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 {Tipo de datos} thermald-configuration -Tipo de datos que representa la configuración de -@code{thermald-service-type}. - -@table @asis -@item @code{ignore-cpuid-check?} (predeterminado: @code{#f}) -Ignore cpuid check for supported CPU models. - -@item @code{thermald} (predeterminado: @var{thermald}) -Package object of thermald. - -@end table -@end deftp - -@node Servicios de audio -@subsection Servicios de audio - -El módulo @code{(gnu services audio)} proporciona un servicio para iniciar -MPD (el daemon de reproducción de música). - -@cindex mpd -@subsubheading Daemon de reproducción de música (MPD) - -El daemon de reproducción de música (MPD) es un servicio que puede -reproducir música mientras se controla desde la máquina local o sobre una -red por una multitud de clientes. - -El siguiente ejemplo muestra como se puede ejecutar @code{mpd} como -@code{"rober"} en el puerto @code{6666}. Usa pulseaudio para su salida. - -@example -(service mpd-service-type - (mpd-configuration - (user "rober") - (port "6666"))) -@end example - -@defvr {Variable Scheme} mpd-service-type -El tipo de servicio para @command{mpd}. -@end defvr - -@deftp {Tipo de datos} mpd-configuration -Data type representing the configuration of @command{mpd}. - -@table @asis -@item @code{user} (predeterminada: @code{"mpd"}) -Usuaria que ejecuta mpd. - -@item @code{music-dir} (predeterminado: @code{"~/Music"}) -The directory to scan for music files. - -@item @code{playlist-dir} (predeterminado: @code{"~/.mpd/playlists"}) -The directory to store playlists. - -@item @code{db-file} (default: @code{"~/.mpd/tag_cache"}) -The location of the music database. - -@item @code{state-file} (default: @code{"~/.mpd/state"}) -The location of the file that stores current MPD's state. - -@item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"}) -The location of the sticker database. - -@item @code{port} (predeterminado: @code{"6600"}) -Puerto sobre el que se ejecuta mpd. - -@item @code{address} (predeterminada: @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 Servicios de virtualización -@subsection Servicios de virtualización - -The @code{(gnu services virtualization)} module provides services for the -libvirt and virtlog daemons, as well as other virtualization-related -services. - -@subsubheading Demonio Libvirt -@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 {Variable Scheme} 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 -Paquete libvirt. - -@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) - -El valor predeterminado es @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. - -El valor predeterminado es @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 "}. - -@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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 -Filtros de log. - -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:nombre - -@item -x:+nombre - -@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. - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid -Host UUID. UUID must not have all digits be the same. - -El valor predeterminado es @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 Daemon Virtlog -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 {Variable Scheme} 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 -Filtros de log. - -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:nombre - -@item -x:+nombre - -@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 emulación -@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 {Variable Scheme} 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" "mips64el")))) -@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 {Tipo de datos} qemu-binfmt-configuration -This is the configuration for the @code{qemu-binfmt} service. - -@table @asis -@item @code{platforms} (predeterminadas: @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?} (predeterminado: @code{#f}) -When it is true, QEMU and all its dependencies are added to the build -environment of @command{guix-daemon} (@pxref{Invocación de 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} (predeterminado: @code{qemu}) -El paquete QEMU usado. -@end table -@end deftp - -@deffn {Procedimiento Scheme} lookup-qemu-platforms @var{plataformas}@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 {Procedimiento Scheme} qemu-platform? @var{obj} -Devuelve verdadero si @var{obj} es un objeto plataforma. -@end deffn - -@deffn {Procedimiento Scheme} qemu-platform-name @var{plataforma} -Devuelve el nombre de @var{plataforma}---una cadena como @code{"arm"}. -@end deffn - -@node Servicios de control de versiones -@subsection Servicios de control de versiones - -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 {Procedimiento Scheme} git-daemon-service [#:config (git-daemon-configuration)] - -Devuelve un servicio que ejecuta @command{git daemon}, un servidor TCP -simple para exponer repositorios con el protocolo Git para acceso anónimo. - -The optional @var{config} argument should be a -@code{} 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 {Tipo de datos} git-daemon-configuration -Tipo de datos que representa la configuración para -@code{git-daemon-service}. - -@table @asis -@item @code{package} (predeterminado: @var{git}) -Package object of the Git distributed version control system. - -@item @code{export-all?} (predeterminado: @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} (predeterminado: @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} (predeterminado: @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} (predeterminado: @var{'()}) -Whether to listen on specific IP addresses or hostnames, defaults to all. - -@item @code{port} (predeterminado: @var{#f}) -Whether to listen on an alternative port, which defaults to 9418. - -@item @code{whitelist} (predeterminado: @var{'()}) -If not empty, only allow access to this list of directories. - -@item @code{extra-options} (predeterminadas: @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{Servicios Web}, for more on running the necessary @code{fcgiwrap} daemon. - -Guix has a separate configuration data type for serving Git repositories -over HTTP. - -@deftp {Tipo de datos} git-http-configuration -Data type representing the configuration for @code{git-http-service}. - -@table @asis -@item @code{package} (predeterminado: @var{git}) -Package object of the Git distributed version control system. - -@item @code{git-root} (predeterminada: @file{/srv/git}) -Directory containing the Git repositories to expose to the world. - -@item @code{export-all?} (predeterminado: @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} (predeterminada: @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} (predeterminado: @code{127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} daemon is listening. @xref{Servicios Web}. -@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 {Procedimiento Scheme} 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{Servicios de certificados}. 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{Servicios Web}. -@end deffn - -@subsubheading Servicio Cgit - -@cindex servicio Cgit -@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{Expresiones-G, file-like objects}) or a string. - -@c %start of fragment - -Available @code{cgit-configuration} fields are: - -@deftypevr {@code{cgit-configuration} parameter} package package -El paquete CGIT. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx -Configuración de NGINX. - -@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). - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter -Specifies a command that will be invoked for authenticating repository -access. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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). - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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}. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean nocache? -If set to the value @samp{#t} caching will be disabled. - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail? -If set to @samp{#t} showing full author email addresses will be disabled. - -El valor predeterminado es @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. - -El valor predeterminado es @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}. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-title -Text printed as heading on the repository index page. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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}. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url -The relative URL used to access the repository. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter -Override the default @code{about-filter}. - -El valor predeterminado es @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. - -El valor predeterminado es @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}. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc -The value to show as repository description. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage -The value to show as repository homepage. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter -Override the default @code{email-filter}. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{#f} - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore? -Flag which, when set to @samp{#t}, ignores the repository. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link -URL loaded when clicking on the cgit logo image. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter -Override the default @code{owner-filter}. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name -El valor a mostrar como nombre del repositorio. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner -A value used to identify the owner of the repository. - -El valor predeterminado es @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path -La ruta absoluta al directorio del repositorio. - -El valor predeterminado es @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. - -El valor predeterminado es @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. - -El valor predeterminado es @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 -El paquete cgit. -@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 Servicio Gitolite - -@cindex servicio Gitolite -@cindex Git, alojamiento -@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 - "sunombre.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 {Tipo de datos} gitolite-configuration -Tipo de datos que representa la configuración de -@code{gitolite-service-type}. - -@table @asis -@item @code{package} (predeterminado: @var{gitolite}) -Paquete Gitolite usado. - -@item @code{user} (predeterminado: @var{git}) -User to use for Gitolite. This will be user that you use when accessing -Gitolite over SSH. - -@item @code{group} (predeterminado: @var{git}) -Grupo usado por Gitolite. - -@item @code{home-directory} (predeterminado: @var{"/var/lib/gitolite"}) -Directory in which to store the Gitolite configuration and repositories. - -@item @code{rc-file} (predeterminado: @var{(gitolite-rc-file)}) -A ``file-like'' object (@pxref{Expresiones-G, file-like objects}), -representing the configuration for Gitolite. - -@item @code{admin-pubkey} (predeterminada: @var{#f}) -A ``file-like'' object (@pxref{Expresiones-G, 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 {Tipo de datos} gitolite-rc-file -Tipo de datos que representa el fichero RC de Gitolite. - -@table @asis -@item @code{umask} (predeterminada: @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} (predeterminadas: @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} (predeterminados: @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 Servicios de juegos -@subsection Servicios de juegos - -@subsubheading El servicio de La batalla por Wesnoth -@cindex wesnothd -@uref{https://wesnoth.org, La batalla por Wesnoth} es un juego de estrategia -táctica, de fantasía y basado en turnos, con varias campañas de una -jugadora, y partidas para múltiples jugadoras (tanto en red como -localmente). - -@defvar {Variable Scheme} 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 {Tipo de datos} wesnothd-configuration -Tipo de datos que representa la configuración de @command{wesnothd}. - -@table @asis -@item @code{package} (predeterminado: @code{wesnoth-server}) -El paquete del servidor wesnoth usado. - -@item @code{port} (predeterminado: @code{15000}) -Número de puerto usado por el servidor. -@end table -@end deftp - -@node Servicios misceláneos -@subsection Servicios misceláneos - -@cindex huella dactilar -@subsubheading Servicios de huella dactilar - -The @code{(gnu services authentication)} module provides a DBus service to -read and identify fingerprints via a fingerprint sensor. - -@defvr {Variable Scheme} 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 Servicios de control del sistema - -The @code{(gnu services sysctl)} provides a service to configure kernel -parameters at boot. - -@defvr {Variable Scheme} 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 {Tipo de datos} sysctl-configuration -Tipo de datos que representa la configuración de @command{sysctl}. - -@table @asis -@item @code{sysctl} (predeterminado: @code{(file-append procps "/sbin/sysctl"}) -El ejecutable @command{sysctl} usado. - -@item @code{settings} (predeterminados: @code{'()}) -An association list specifies kernel parameters and their values. -@end table -@end deftp - -@cindex pcscd -@subsubheading Servicio del daemon de tarjetas inteligentes PC/SC - -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 {Variable Scheme} 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 {Tipo de datos} pcscd-configuration -The data type representing the configuration of @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (predeterminado: @code{pcsc-lite}) -The pcsc-lite package that provides pcscd. -@item @code{usb-drivers} (predeterminado: @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 Servicio Lirc - -El módulo @code{(gnu services lirc)} proporciona el siguiente servicio. - -@deffn {Procedimiento Scheme} 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 Servicio Spice - -El módulo @code{(gnu services spice)} proporciona el siguiente servicio. - -@deffn {Procedimiento Scheme} 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 - -@cindex inputattach -@subsubheading inputattach Service - -@cindex tablet input, for Xorg -@cindex touchscreen input, for Xorg -The @uref{https://linuxwacom.github.io/, inputattach} service allows you to -use input devices such as Wacom tablets, touchscreens, or joysticks with the -Xorg display server. - -@deffn {Scheme Variable} inputattach-service-type -Type of a service that runs @command{inputattach} on a device and dispatches -events from it. -@end deffn - -@deftp {Data Type} inputattach-configuration -@table @asis -@item @code{device-type} (default: @code{"wacom"}) -The type of device to connect to. Run @command{inputattach --help}, from -the @code{inputattach} package, to see the list of supported device types. - -@item @code{device} (default: @code{"/dev/ttyS0"}) -The device file to connect to the device. - -@item @code{log-file} (default: @code{#f}) -If true, this must be the name of a file to log messages to. -@end table -@end deftp - -@subsection Servicios de diccionario -@cindex diccionario -El módulo @code{(gnu services dict)} proporciona el servicio siguiente: - -@deffn {Procedimiento Scheme} dicod-service [#:config (dicod-configuration)] -Devuelve un servicio que ejecuta el daemon @command{dicod}, una -implementación del servidor DICT (@pxref{Dicod,,, dico, GNU Dico Manual}). - -El parámetro opcional @var{config} especifica la configuración para -@command{dicod}, que debe ser un objeto @code{}, por -defecto proporciona el diccionario colaborativo internacional de Inglés de -GNU. - -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 {Tipo de datos} dicod-configuration -Tipo de datos que representa la configuración de dicod. - -@table @asis -@item @code{dico} (predeterminado: @var{dico}) -Package object of the GNU Dico dictionary server. - -@item @code{interfaces} (predeterminada: @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} (predeterminados: @var{'()}) -List of @code{} objects denoting handlers (module instances). - -@item @code{databases} (predeterminada: @var{(list %dicod-database:gcide)}) -List of @code{} objects denoting dictionaries to be served. -@end table -@end deftp - -@deftp {Tipo de datos} dicod-handler -Data type representing a dictionary handler (module instance). - -@table @asis -@item @code{name} -Name of the handler (module instance). - -@item @code{module} (predeterminado: @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{Módulos,,, dico, GNU Dico -Manual}). - -@item @code{options} -List of strings or gexps representing the arguments for the module handler -@end table -@end deftp - -@deftp {Tipo de datos} dicod-database -Tipo de datos que representa una base de datos de diccionario. - -@table @asis -@item @code{name} -Nombre de la base de datos, será usada en las órdenes DICT. - -@item @code{handler} -Name of the dicod handler (module instance) used by this database -(@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (predeterminado: @var{#f}) -Whether the database configuration complex. The complex configuration will -need a corresponding @code{} 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 {Variable Scheme} %dicod-database:gcide -A @code{} 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 Programas con setuid -@section Programas con setuid - -@cindex programas con setuid -Algunos programas necesitan ejecutarse con privilegios de ``root'', incluso -cuando se ejecutan por usuarias sin privilegios. Un ejemplo notable es el -programa @command{passwd}, que las usuarias ejecutan para cambiar su -contraseña, y que necesita acceso a los ficheros @file{/etc/passwd} y -@file{/etc/shadow}---algo normalmente restringido a root, por razones de -seguridad obvias. Para solventarlo, estos ejecutables tienen @dfn{setuid de -root}, lo que significa que siempre se ejecutan con privilegios de root -(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual}, -para más información sobre el mecanismo setuid). - -El almacén en sí @emph{no puede} contener programas setuid: sería un -problema de seguridad puesto que cualquier usuaria del sistema puede -escribir derivaciones que pueblen el almacén (@pxref{El almacén}). Por tanto, -se usa un mecanismo diferente: en vez de cambiar el bit de setuid -directamente en los ficheros que se encuentran en el almacén, se permite que -la administradora del sistema @emph{declare} qué programas deberían tener -setuid de root. - -El campo @code{setuid-programs} de una declaración @code{operating-system} -contiene una lista de expresiones-G que denotan nombres de programas que -tendrán setuid de root (@pxref{Uso de la configuración del sistema}). Por -ejemplo, el programa @command{passwd}, que es parte del paquete Shadow, -puede designarse con esta expresión-G (@pxref{Expresiones-G}): - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -Un conjunto predeterminado de programas con el bit setuid se define en la -variable @code{%setuid-programs} del módulo @code{(gnu system)}. - -@defvr {Variable Scheme} %setuid-programs -Una lista de expresiones-G que denotan programas comunes que se marcan con -setuid de root. - -La lista incluye órdenes como @command{passwd}, @command{ping}, @command{su} -y @command{sudo}. -@end defvr - -Para su implementación, los programas con setuid reales se crean en el -directorio @file{/run/setuid-programs} durante la activación del -sistema. Los ficheros en este directorio hacen referencia a los binarios -``reales'', que estan en el almacén. - -@node Certificados X.509 -@section Certificados X.509 - -@cindex HTTPS, certificados -@cindex certificados X.509 -@cindex TLS -En las conexiones HTTPS a servidores Web (esto es, HTTP sobre el mecanismo -de seguridad de la capa de transporte, TLS) se envía a los programas -clientes un @dfn{certificado X.509} que el cliente puede usar para -@emph{autentificar} al servidor. Para hacerlo, los clientes verifican que el -certificado del servidor está firmado por una de las llamadas -@dfn{autoridades de certificación} (AC, CA en inglés). Pero para verificar -la firma de una AC, los clientes deben haber obtenido previamente el -certificado de dicha AC. - -Los navegadores Web como GNU@tie{}IceCat incluyen su propio conjunto de -certificados de AC, de manera que pueden verificar las firmas -independientemente. - -No obstante, a la mayor parte de otros programas que pueden comunicarse a -través de HTTPS---@command{wget}, @command{git}, @command{w3m}, etc.---se -les debe informar de dónde pueden encontrar los certificados de CA. - -@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{Referencia de ``operating-system''}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -Fíjese que @emph{no} es parte de @var{%base-packages}, por lo que debe ser -añadido explícitamente. El directorio @file{/etc/ssl/certs}, donde la mayor -parte de las aplicaciones y bibliotecas buscarán los certificados de manera -predeterminada, enlaza a los certificados instalados de manera global. - -Las usuarias sin privilegios, incluyendo a usuarias de Guix en una -distribución distinta, pueden también instalar su propio paquete de -certificados en su perfil. Es necesario definir cierto número de variables -de entorno de manera que las aplicaciones y bibliotecas sepan dónde -encontrarlos. Por ejemplo, la biblioteca OpenSSL inspecciona las variables -@code{SSL_CERT_DIR} y @code{SSL_CERT_FILE}. Algunas aplicaciones añaden sus -variables de entorno propias; por ejemplo, el sistema de control de -versiones Git inspecciona el empaquetado de certificados al que apunta la -variable de entorno @code{GIT_SSL_CAINFO}. Por tanto, en el caso típico se -debe ejecutar algo parecido a esto: - -@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 - -Como otro ejemplo, R necesita que la variable de entorno -@code{CURL_CA_BUNDLE} apunte al empaquetado de certificados, de manera que -se debe ejecutar algo parecido a esto: - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -Para otras aplicaciones puede tener que buscar la variable de entorno -necesaria en la documentación relevante. - - -@node Selector de servicios de nombres -@section Selector de servicios de nombres - -@cindex name service switch -@cindex NSS -El módulo @code{(gnu system nss)} proporciona una interfaz con el fichero de -configuración del @dfn{selector de servicios de nombres} o @dfn{NSS} -(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference -Manual}). En resumen, NSS es un mecanismo que permite la extensión de libc -con nuevos métodos de búsqueda de ``nombres'', lo que incluye nombres de -máquinas, nombres de servicios, cuentas de usuaria y más (@pxref{Selector de servicios de nombres, System Databases and Name Service Switch,, libc, The GNU C -Library Reference Manual}). - -La configuración de NSS especifica, para cada base de datos del sistema, que -método de búsqueda debe ser usado, y cómo los varios métodos se enlazan -entre sí---por ejemplo, bajo qué circunstancias NSS deberá probar con el -siguiente método en la lista. La configuración de NSS se proporciona en el -campo @code{name-service-switch} de las declaraciones -@code{operating-system} (@pxref{Referencia de ``operating-system'', -@code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, búsqueda de nombres de máquina -Como ejemplo, la siguiente declaración configura NSS para usar el -@uref{http://0pointer.de/lennart/projects/nss-mdns/, motor @code{nss-mdns}}, -que permite las búsquedas de nombres de máquinas sobre DNS multicast (mDNS) -para nombres de máquinas terminados en @code{.local}: - -@example -(name-service-switch - (hosts (list %files ;primero, comprueba /etc/hosts - - ;; Si lo anterior no funcionó, prueba - ;; con 'mdns_minimal'. - (name-service - (name "mdns_minimal") - - ;; 'mdns_minimal' tiene autoridad sobre - ;; '.local'. Cuando devuelve 'not-found, - ;; no es necesario intentarlo con los - ;; métodos siguientes. - (reaction (lookup-specification - (not-found => return)))) - - ;; Si no, usa DNS. - (name-service - (name "dns")) - - ;; Finalmente, prueba con 'mdns' "al completo". - (name-service - (name "mdns"))))) -@end example - -No se preocupe: la variable @code{%mdns-host-lookup-nss} (véase a -continuación) contiene esta configuración, de manera que no tiene que -escribirla si todo lo que desea es que funcione la búsqueda de nombres de -máquina en @code{.local}. - -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{Servicios de red, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Servicios de escritorio}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@pxref{Servicios base, @code{nscd-service}}). - -Por conveniencia, las siguientes variables proporcionan configuraciones NSS -típicas. - -@defvr {Variable Scheme} %default-nss -Esta es la configuración predeterminada del selector de servicios de -nombres, un objeto @code{name-service-switch}. -@end defvr - -@defvr {Variable Scheme} %mdns-host-lookup-nss -Esta es la configuración del selector de servicios de nombres que permite la -búsqueda de nombres de máquinas por DNS multicast (mDNS) para nombres de -máquinas terminados en @code{.local}. -@end defvr - -La referencia de la configuración del selector de servicios de nombres se -proporciona a continuación. Tiene una asociación directa con el formato del -fichero de configuración de la biblioteca C, por lo que se recomienda el -manual de la biblioteca C para obtener más información (@pxref{NSS -Configuration File,,, libc, The GNU C Library Reference Manual}). En -comparación con el formato del fichero de configuración del NSS de libc, no -solo tiene solo la ventaja de la cálida sensación proporcionada por la -adición de paréntesis que tanto nos gustan, sino que también tiene -comprobaciones estáticas: conocerá los errores sintácticos y tipográficos -con la ejecución de @command{guix system}. - -@deftp {Tipo de datos} name-service-switch - -El tipo de datos que representa la configuración del selector de servicios -de nombres (NSS). Cada campo a continuación representa una de las bases de -datos del sistema admitidas. - -@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 -Las bases de datos del sistema que maneja el NSS. Cada uno de estos campos -debe ser una lista de objetos @code{} (véase a continuación). -@end table -@end deftp - -@deftp {Tipo de datos} name-service - -Este es el tipo de datos que representa un servicio de nombres real y la -acción de búsqueda asociada. - -@table @code -@item name -Una cadena que denota el nombre de servicio (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). - -Fijese que los servicios de nombres enumerados aquí deben ser visibles para -nscd. Esto se consigue mediante la adición del parámetro -@code{#:name-services} a @code{nscd-service} con la lista de paquetes que -proporcionan los servicios de nombres necesarios (@pxref{Servicios base, -@code{nscd-service}}). - -@item reaction -Una acción especificada mediante el uso del macro -@code{lookup-specification} (@pxref{Actions in the NSS configuration,,, -libc, The GNU C Library Reference Manual}). Por ejemplo: - -@example -(lookup-specification (unavailable => continue) - (success => return)) -@end example -@end table -@end deftp - -@node Disco en RAM inicial -@section Disco en RAM inicial - -@cindex initrd -@cindex disco inicial de RAM -Para el propósito del arranque inicial, se le proporciona al núcleo -Linux-libre un @dfn{disco inicial de RAM}, o @dfn{initrd}. Un initrd -contiene un sistema de ficheros raíz temporal así como un guión de -inicialización. Este último es responsable del montaje del sistema de -ficheros raíz real, así como de la carga de cualquier módulo del núcleo que -pueda ser necesario para esta tarea. - -El campo @code{initrd-modules} de una declaración @code{operating-system} le -permite especificar qué módulos del nucleo Linux-libre deben estar -disponibles en el initrd. En particular, aquñi es donde se debe enumerar los -módulos que controlen realmente el disco duro deonde su partición raíz se -encuentre---aunque el valor predeterminado de @code{initrd-modules} debería -cubrir la mayor parte de casos de uso. Por ejemplo, en caso de necesitar el -módulo @code{megaraid_sas} además de los módulos predeterminados para poder -acceder a sistema de ficheros raíz, se podría escribir: - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Variable Scheme} %base-initrd-modules -Esta es la lista de módulos del nucleo que se incluyen en el initrd -predeterminado. -@end defvr - -Más allá, si necesita personalizaciones de un nivel más bajo, el campo -@code{initrd} de una declaración @code{operating-system} le permite -especificar qué initrd desea usar. El módulo @code{(gnu system -linux-initrd)} proporciona tres formas de construir un initrd: el -procedimiento de alto nivel @code{base-initrd} y los procedimientos de bajo -nivel @code{raw-initrd} y @code{expression->initrd}. - -El procedimiento @code{base-initrd} está pensado para cubrir la mayor parte -de usos comunes. Por ejemplo, si desea añadir algunos módulos del nucleo que -deben cargarse durante el arranque, puede definir el campo @code{initrd} de -la declaración de sistema operativo de esta forma: - -@example -(initrd (lambda (sistemas-de-ficheros . resto) - ;; Crea un initrd estándar pero configura la red - ;; con los parámetros que QEMU espera por omisión. - (apply base-initrd sistemas-de-ficheros - #:qemu-networking? #t - resto))) -@end example - -El procedimiento @code{base-initrd} también maneja casos de uso comunes que -implican el uso del sistema en un anfitrión QEMU, o como un sistema ``live'' -con un sistema de ficheros raíz volátil. - -El procedimiento @code{base-initrd} se construye sobre el procedimiento -@code{raw-initrd}. Al contrario que @code{base-initrd}, @code{raw-initrd} no -funciona a alto nivel, como sería intentar deducir qué módulos del nucleo y -paquetes deben incluirse en el initrd. Un ejemplo de uso de -@code{raw-initrd} es cuando una usuaria tiene personalizada una -configuración del nucleo Linux y los módulos predeterminados del núcleo que -incluye @code{base-initrd} no están disponibles. - -El disco inicial de RAM producido por @code{base-initrd} o @code{raw-initrd} -inspecciona varias opciones proporcionadas por la línea de órdenes al núcleo -Linux (esto es, argumentos pasados a través de la orden @code{linux} de -GRUB, o de la opción @code{-append} de QEMU), notablemente: - -@table @code -@item --load=@var{arranque} -Indica al disco de RAM inicial que cargue @var{arranque}, un fichero que -contiene un programa Scheme, una vez haya montado el sistema de ficheros -raíz. - -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{raíz} -Monta @var{raíz} como el sistema de ficheros raíz. @var{raíz} puede ser un -nombre de dispositivo como @code{/dev/sda1}, una etiqueta del sistema de -ficheros o un UUID del sistema de ficheros. - -@item --system=@var{sistema} -Hace que @file{/run/booted-system} y @file{/run/current-system} apunten a -@var{sistema}. - -@item modprobe.blacklist=@var{módulos}@dots{} -@cindex módulo, lista negra -@cindex lista negra, de módulos del núcleo -Indica al disco inicial de RAM así como a la orden @command{modprobe} (del -paquete kmod) que deben negarse a cargar @var{módulos}. @var{módulos} debe -ser una lista separada por comas de nombres de módulos---por ejemplo, -@code{usbkbd,9pnet}. - -@item --repl -Inicia una sesión interactiva (REPL) desde el disco inicial de RAM antes de -que intente cargar los módulos del núcleo y del montaje del sistema de -ficheros raíz. Nuestro departamento comercial lo llama -@dfn{arranca-en-Guile}. Como amante de Scheme, lo adorará. @xref{Using Guile -Interactively,,, guile, GNU Guile Reference Manual}, para más información -sobre sesiones interactivas Guile. - -@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 disco inicial de RAM -@deffn {Procedimiento Scheme} raw-initrd @var{sistemas-de-ficheros} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ -[#: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{Dispositivos traducidos}). -@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 true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -Cuando @var{qemu-networking?} es verdadero, configura la red con los -parámetros QEMU estándar. Cuando @var{virtio?} es verdadero, carga módulos -adicionales para que la imagen en RAM pueda ser usada como un sistema -virtualizado por QEMU con controladores paravirtualizados de E/S. - -Cuando @var{volatile-root?} es verdadero, el sistema de ficheros raíz tiene -permisos de escritura pero cualquier cambio realizado se perderá. -@end deffn - -@deffn {Procedimiento Scheme} base-initrd @var{sistemas-de-ficheros} @ - [#:mapped-devices '()] [#:keyboard-layout #f] @ [#: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. - -When true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -@var{qemu-networking?} y @var{volatile-root?} funcionan como en -@code{raw-initrd}. - -El initrd incorpora automáticamente todos los módulos del nucleo necesarios -para @var{sistemas-de-ficheros} y para las opciones proporcionadas. Módulos -del nucleo adicionales pueden proporcionarse a través de -@var{linux-modules}. Se añadirán al initrd y se cargarán en tiempo de -arranque en el orden que aparezcan. -@end deffn - -No es necesario decir que los initrd que producimos y usamos embeben un -Guile enlazado estáticamente, y que el programa de inicialización es un -programa Guile. Esto proporciona mucha flexibilidad. El procedimiento -@code{expression->initrd} construye un initrd de ese tipo, una vez -proporcionado el programa a ejecutar en dicho initrd. - -@deffn {Procedimiento Scheme} expression->initrd @var{exp} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] -Devuelve como un objeto tipo-fichero el initrd de Linux (un archivador cpio -comprimido con gzip) que contiene @var{guile} y que evalua a @var{exp}, una -expresión-G, al arranque. Todas las derivaciones a las que @var{exp} hace -referencia se copian automáticamente en el initrd. -@end deffn - -@node Configuración del gestor de arranque -@section Configuración del gestor de arranque - -@cindex bootloader -@cindex cargador de arranque - -El sistema operativo permite varios cargadores de arranque. El cargador de -arranque se configura mediante el uso de la declaración -@code{bootloader-configuration}. Todos los campos de esta estructura son -independientes del cargador de arranque excepto uno, @code{bootloader}, que -indica el cargador de arranque a configurar e instalar. - -Algunos de los cargadores de arranque no inspeccionan todos los campos de -@code{bootloader-configuration}. Por ejemplo, el cargador de arranque -extlinux no permite temas y por lo tanto ignora el campo @code{theme}. - -@deftp {Tipo de datos} bootloader-configuration -El tipo de una declaración de configuración del cargador de arranque. - -@table @asis - -@item @code{bootloader} -@cindex EFI, cargador de arranque -@cindex UEFI, cargador de arranque -@cindex BIOS, cargador de arranque -El cargador de arranque a usar, como un objeto @code{bootloader}. De momento -se aceptan @code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} y @code{u-boot-bootloader}. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} permite el arranque en sistemas modernos que usan -la @dfn{interfaz extendida de firmware unificada} (UEFI). Es el que debería -ser usado si la imagen de instalación contiene un directorio -@file{/sys/firmware/efi} cuando la arranca en su sistema. - -@vindex grub-bootloader -@code{grub-bootloader} permite el arranque en máquinas basadas en Intel en -modo ``antiguo'' BIOS. - -@cindex ARM, cargadores de arranque -@cindex AArch64, cargadores de arranque -Los cargadores de arranque se describen en los módulos @code{(gnu bootloader -@dots{})}. En particular, @code{(gnu bootloader u-boot)} contiene -definiciones de cargadores de arranque para un amplio rango de sistemas ARM -y AArch64, mediante el uso del @uref{http://www.denx.de/wiki/U-Boot/, -cargador de arranque U-Boot}. - -@item @code{target} -Una cadena que indica donde se instalará el cargador de arranque. - -La interpretación depende del cargador de arranque en cuestión. Para -@code{grub-bootloader}, por ejemplo, debe ser un nombre de dispositivo que -entienda la orden @command{install} del cargador de arranque, como -@code{/dev/sda} o @code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU -GRUB Manual}). Para @code{grub-efi-bootloader}, debe apuntar al punto de -montaje del sistema de ficheros EFI, habitualmente @file{/boot/efi}. - -@item @code{menu-entries} (predeterminadas: @code{()}) -Una lista posiblemente vacia de objetos @code{menu-entry} (véase a -continuación), que indican entradas que deben aparecer en el menú del -cargador de arranque, además de la entrada del sistema actual y la entrada -que apunta a generaciones previas del sistema. - -@item @code{default-entry} (predeterminada: @code{0}) -El índice de la entrada del menú de arranque por omisión. El índice 0 es -para la entrada del sistema actual. - -@item @code{timeout} (predeterminado: @code{5}) -El número de segundos que se esperará entrada por el teclado antes de -arrancar. El valor 0 indica que se debe arrancar de forma inmediata, y -1 -que se debe esperar indefinidamente. - -@cindex keyboard layout, for the bootloader -@item @code{keyboard-layout} (predeterminada: @code{#f}) -If this is @code{#f}, the bootloader's menu (if any) uses the default -keyboard layout, usually US@tie{}English (``qwerty''). - -Otherwise, this must be a @code{keyboard-layout} object (@pxref{Distribución de teclado}). - -@quotation Nota -This option is currently ignored by bootloaders other than @code{grub} and -@code{grub-efi}. -@end quotation - -@item @code{theme} (predeterminado: @var{#f}) -El objeto del tema del cargador de arranque que describa el tema a usar. Si -no se proporciona ningún tema, algunos cargadores de arranque pueden usar un -tema por omisión, lo cual es cierto en GRUB. - -@item @code{terminal-outputs} (predeterminada: @code{'gfxterm}) -Los terminales de salida que se usarán para el menú de arranque, como una -lista de símbolos. GRUB acepta los valores: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, -@code{morse} y @code{pkmodem}. Este campo corresponde con la variable -@code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, grub, GNU GRUB -manual}). - -@item @code{terminal-inputs} (predeterminadas: @code{'()}) -Los terminales de entrada que se usarán para el menú de arranque, como una -lista de símbolos. Para GRUB, el valor predeterminado es el terminal nativo -de la platafroma determinado en tiempo de ejecución. GRUB acepta los -valores: @code{console}, @code{serial}, @code{serial@{0-3@}}, -@code{at_keyboard} y @code{usb_keyboard}. Este campo corresponde a la -variable GRUB @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, -grub,GNU GRUB manual}). - -@item @code{serial-unit} (predeterminada: @code{#f}) -La unidad serie usada por el cargador de arranque, como un entero del 0 al -3. Para GRUB, se selecciona en tiempo de ejecución; actualmente GRUB -selecciona 0 lo que corresponde a COM1 (@pxref{Serial terminal,,, grub,GNU -GRUB manual}). - -@item @code{serial-speed} (predeterminada: @code{#f}) -La velocidad de la interfaz serie, como un entero. Para GRUB, el valor -predeterminado se selecciona en tiempo de ejecución, actualmente GRUB -selecciona 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex arranque dual -@cindex menú de arranque -Si desease listar entradas adicionales para el menú de arranque a través del -campo @code{menu-entries} mostrado previamente, deberá crearlas con la forma -@code{menu-entry}. Por ejemplo, imagine que desea ser capaz de arrancar otra -distribución (¡difícil de imaginar!), puede definir una entrada de menú de -esta forma: - -@example -(menu-entry - (label "La otra distribución") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Los detalles se encuentran a continuación. - -@deftp {Tipo de datos} menu-entry -El tipo de una entrada en el menú del cargador de arranque. - -@table @asis - -@item @code{label} -La etiqueta a mostrar en el menú---por ejemplo, @code{"GNU"}. - -@item @code{linux} -La imagen del núcleo Linux a arrancar, por ejemplo: - -@example -(file-append linux-libre "/bzImage") -@end example - -Con GRUB, también es posible especificar un dispositivo explícitamente -mediante el uso de la convención de nombres de dispositivo de GRUB -(@pxref{Naming convention,,, grub, GNU GRUB manual}), por ejemplo: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -Si se especifica el dispositivo explícitamente como en el ejemplo anterior, -el campo @code{device} se ignora completamente. - -@item @code{linux-arguments} (predeterminados: @code{()}) -La lista de parámetros extra de línea de órdenes para el núcleo Linux---por -ejemplo, @code{("console=ttyS0")}. - -@item @code{initrd} -Una expresión-G o una cadena que contiene el nombre de fichero del disco -inicial en RAM a usar (@pxref{Expresiones-G}). -@item @code{device} (predeterminado: @code{#f}) -El dispositivo donde se encuentran el núcleo y el initrd---es decir, para -GRUB, @dfn{raíz} de esta entrada de menú (@pxref{root,,, grub, GNU GRUB -manual}). - -Puede ser una etiqueta de sistema de ficheros (una cadena), un UUID de -sistema de ficheros (un vector de bytes, @pxref{Sistemas de ficheros}), o @code{#f}, -en cuyo caso el cargador de arranque buscará el dispositivo que contenga el -fichero especificado por el campo @code{linux} (@pxref{search,,, grub, GNU -GRUB manual}). @emph{No} debe ser un nombre de dispositivo del SO como -@file{/dev/sda1}. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -For now only GRUB has theme support. GRUB themes are created using the -@code{grub-theme} form, which is not documented yet. - -@defvr {Variable Scheme} %default-theme -Este es el tema predeterminado de GRUB que usa el sistema operativo si no se -especifica el campo @code{theme} en el registro -@code{bootloader-configuration}. - -Viene con una bonita imagen de fondo que muestra los logos de GNU y Guix. -@end defvr - - -@node Invocación de guix system -@section Invocación de @code{guix system} - -Una vez haya escrito la declaración de sistema operativo como se ha visto en -la sección previa, puede @dfn{instanciarse} mediante el uso de la orden -@command{guix system}. Su sinopsis es: - -@example -guix system @var{opciones}@dots{} @var{acción} @var{fichero} -@end example - -@var{fichero} debe ser el nombre de un fichero que contenga una declaración -@code{operating-system}. @var{acción} especifica cómo se instancia el -sistema operativo. Actualmente se permiten los siguientes valores: - -@table @code -@item search -Muestra las definiciones de tipos de servicio disponibles que corresponden -con las expresiones regulares proporcionadas, ordenadas por relevancia: - -@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 - -Como con @command{guix package --search}, el resultado se obtiene en formato -@code{recutils}, lo que facilita el filtrado de la salida (@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}). - -Esta orden crea una nueva generación cuyo número es el sucesor de la -siguiente generación (como lo muestra @command{guix system -list-generations}). Si esa generación ya existe, será sobreescrita. Este -comportamiento es el mismo que el de @command{guix package} (@pxref{Invocación de guix package}). - -También añade una entrada al cargador de arranque para la nueva -configuración del sistema operativo---en caso de que no se proporcione la -opción @option{--no-bootloader}. Con GRUB, mueve las entradas de -configuraciones antiguas a un submenú, permitiendo la selección de una -generación previa del sistema en tiempo de arranque en caso necesario. - -@quotation Nota -@c The paragraph below refers to the problem discussed at -@c . -Es altamente recomendable ejecutar @command{guix pull} antes de la primera -ejecución de @command{guix system reconfigure} (@pxref{Invocación de guix pull}). No hacerlo puede ocasionar que se obtenga una versión más antigua de -Guix una vez que @command{reconfigure} se haya completado. -@end quotation - -@item switch-generation -@cindex generaciones -Cambia a una generación existente del sistema. Esta acción cambia -atómicamente el perfil del sistema a la generación del sistema -especificada. También redistribuye las entradas de sistema del menú de -arranque existentes. Marca como predeterminada la entrada de la generación -de sistema especificada y mueve las entradas de otras generaciones a un -submenú, si el cargador de arranque lo permite. La próxima vez que se -arranque el sistema, se usará la generación de sistema especificada. - -El cargador de arranque en sí no se reinstala durante esta orden. Por tanto, -el cargador de arranque instalado se usa con un fichero de configuración -actualizado. - -La generación deseada puede especificarse explícitamente con su numero de -generación. Por ejemplo, la siguiente invocación cambiaría a la generación 7 -del sistema: - -@example -guix system switch-generation 7 -@end example - -La generación deseada puede especificarse también de forma relativa a la -generación actual con la forma @code{+N} o @code{-N}, donde @code{+3} -significa ``3 generaciones después de la generación actual'', y @code{-1} -significa ``1 generación antes de la generación actual''. Cuando se -especifica un valor negativo como @code{-1} debe ir precedido de @code{--} -para evitar que se analice como una opción. Por ejemplo: - -@example -guix system switch-generation -- -1 -@end example - -Actualmente, el efecto de la invocación de esta acción es @emph{únicamente} -cambiar el perfil del sistema a una generación existente y redistribuir las -entradas del menú de arranque. Para realmente empezar a usar la generación -deseada del sistema, debe reiniciar tras esta acción. En el futuro, se -actualizará para hacer lo mismo que @command{reconfigure}, como activación y -desactivación de servicios. - -Esta acción fallará si la generación especificada no existe. - -@item roll-back -@cindex vuelta atrás -Cambia a la generación de sistema previa. Tras el siguiente arranque del -sistema, usará la generación de sistema precedente. Es la operación inversa -de @command{reconfigure}, y es equivalente a la invocación de -@command{switch-generation} con @code{-1} como parámetro. - -Actualmente, como con @command{switch-generation}, debe reiniciar tras la -ejecución de esta acción para realmente empezar a usar la generación de -sistema precedente. - -@item delete-generations -@cindex deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Invocación de guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Invocación de 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 -Construye la derivación del sistema operativo, que incluye todos los -ficheros de configuración y programas necesarios para el arranque y la -ejecución del sistema. Esta acción no instala nada en realidad. - -@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 mi-conf-del-so.scm /mnt -@end example - -copia a @file{/mnt} todos los elementos del almacén necesarios para la -configuración especificada en @file{mi-conf-del-so.scm}. Esto incluye los -ficheros de configuración, paquetes y demás. También crea otros ficheros -esenciales necesarios para la correcta operación del sistema---por ejemplo, -los directorios @file{/etc}, @file{/var} y @file{/run}, y el fichero -@file{/bin/sh}. - -Esta orden también instala el cargador de arranque en el destino -especificado en @file{mi-conf-del-so.scm}, siempre que no se proporcione la -opción @option{--no-bootloader}. - -@item vm -@cindex máquina virtual -@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 Nota -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{Configuración del entorno de construcción}). -@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 - -La VM comparte su almacén con el sistema anfitrión. - -Sistemas de ficheros adicionales pueden compartirse entre la máquina -anfitriona y la virtual mediante el uso de las opciones @code{--share} y -@code{--expose}: la primera especifica un directorio a compartir con acceso -de escritura, mientras que la última proporciona solo acceso de lectura al -directorio compartido. - -El siguiente ejemplo crea una máquina virtual en la que el directorio de la -usuaria es accesible en modo solo-lecture, y donde el directorio -@file{/intercambio} esta asociado de forma lectura-escritura con -@file{$HOME/tmp} en el sistema anfitrión: - -@example -guix system vm mi-configuracion.scm \ - --expose=$HOME --share=$HOME/tmp=/intercambio -@end example - -En GNU/Linux, lo predeterminado es arrancar directamente el núcleo; esto -posee la ventaja de necesitar únicamente una pequeña imagen del disco raíz -pequeña ya el el almacén de la anfitriona puede montarse. - -La opción @code{--full-boot} fuerza una secuencia de arranque completa, -desde el cargador de arranque. Esto necesita más espacio en disco ya que la -imagen raíz que contiene el núcleo, initrd y los ficheros de datos del -cargador de arranque deben crearse. La opción @code{--image-size} puede -usarse para especificar el tamaño de la imagen. - -@cindex Imágenes de sistema, creación en varios formatos -@cindex Creación de imágenes del sistema en varios formatos -@item vm-image -@itemx disk-image -@itemx docker-image -Devuelve una máquina virtual, imagen de disco o imagen Docker del sistema -operativo declarado en @var{fichero} que es independiente. Por omisión, -@command{guix system} estima el tamaño de la imagen necesario para almacenar -el sistema, pero puede usar la opción @option{--image-size} para especificar -un valor. Las imagenes Docker se construyen para que contengan exactamente -lo que necesitan, por lo que la opción @option{--image-size} se ignora en el -caso de @code{docker-image}. - -Puede especificar el sistema de ficheros raíz mediante el uso de la opción -@option{--file-system-type}. Su valor predeterminado es @code{ext4}. - -When using @code{vm-image}, the returned image is in qcow2 format, which the -QEMU emulator can efficiently use. @xref{Ejecutar Guix en una máquina virtual}, for more -information on how to run the image in a virtual machine. - -Con @code{disk-image} se produce una imagen de disco cruda; puede copiarse -tal cual en una memoria USB, por ejemplo. Asumiendo que @code{/dev/sdc} es -el dispositivo que corresponde a la memoria USB, se podría copiar la imagen -con la siguiente orden: - -@example -# dd if=$(guix system disk-image mi-so.scm) of=/dev/sdc -@end example - -Con @code{docker-image} se produce una imagen Docker. Guix construye la -imagen de cero, no de una imagen Docker base preexistente. Como resultado, -contiene @emph{exactamente} lo definido en el fichero de configuración del -sistema operativo. Puede cargar la imagen y ejecutar un contenedor Docker -mediante el uso de ordenes como las siguientes: - -@example -image_id="$(docker load < guix-system-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 -Devuelve un guión de la ejecución del sistema operativo declarado en -@var{fichero} dentro de un contenedor. Los contenedores son un conjunto de -mecanismos de aislamiento ligeros que proporciona el núcleo Linux-libre. Los -contenedores necesitan sustancialmente menos recursos que máquinas virtuales -completas debido a que el núcleo, los objetos compartidos y otros recursos -pueden compartirse con el sistema anfitrión; esto también significa que -proporcionan un menor aislamiento. - -En este momento, el guión debe ejecutarse como root para permitir más de una -única usuaria y grupo. El contenedor comparte su almacén con la máquina -anfitriona. - -Como con la acción @code{vm} (@pxref{guix system vm}), sistemas de ficheros -adicionales a compartir entre la máquina anfitriona y el contenedor pueden -especificarse mediante el uso de las opciones @option{--share} y -@option{--expose}: - -@example -guix system container mi-configuracion.scm \ - --expose=$HOME --share=$HOME/tmp=/intercambio -@end example - -@quotation Nota -Esta opción requiere Linux-libre 3.19 o posterior. -@end quotation - -@end table - -@var{opciones} puede contener cualquiera de las opciones de construcción -comunes (@pxref{Opciones comunes de construcción}). Además, @var{opciones} puede -contener una de las siguientes: - -@table @option -@item --expression=@var{expr} -@itemx -e @var{expr} -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{Construcción de la imagen de instalación}). - -@item --system=@var{sistema} -@itemx -s @var{sistema} -Intenta la construcción para @var{sistema} en vez de para el tipo de la -máquina anfitriona. Funciona como en @command{guix build} (@pxref{Invocación de guix build}). - -@item --derivation -@itemx -d -Devuelve el nombre de fichero de la derivación del sistema operativo -proporcionado sin construir nada. - -@item --file-system-type=@var{tipo} -@itemx -t @var{tipo} -Para la acción @code{disk-image}, crea un sistema de ficheros del @var{tipo} -proporcionado en la imagen. - -Cuando se omite esta opción, @command{guix system} usa @code{ext4}. - -@cindex ISO-9660, formato -@cindex CD, formato de imagen -@cindex DVD, formato de imagen -@code{--file-system-type=iso9660} produce una imagen ISO-9660, que puede ser -grabada en CD y DVD. - -@item --image-size=@var{tamaño} -Junto a las acciones @code{vm-image} y @code{disk-image}, crea una imagen -del @var{ŧamaño} proporcionado. @var{tamaño} debe ser un número de bytes o -puede incluir una unidad como sufijo (@pxref{Block size, size -specifications,, coreutils, GNU Coreutils}). - -Cuando se omite esta opción, @command{guix system} calcula una estimación -del tamaño de la imagen en función del tamaño del sistema declarado en -@var{fichero}. - -@item --root=@var{fichero} -@itemx -r @var{fichero} -Hace que @var{fichero} sea un enlace simbólico al resultado, y lo registra -como una raíz del recolector de basura. - -@item --skip-checks -Omite las comprobaciones de seguridad previas a la instalación. - -Por omisión, @command{guix system init} y @command{guix system reconfigure} -realizan comprobaciones de seguridad: se aseguran de que los sistemas de -ficheros que aparecen en la declaración @code{operating-system} realmente -existen (@pxref{Sistemas de ficheros}) y que cualquier módulo del núcleo Linux que -pudiese necesitarse durante el arranque se encuentre en -@code{initrd-modules} (@pxref{Disco en RAM inicial}). El uso de esta opción -omite todas estas comprobaciones. - -@cindex on-error -@cindex on-error strategy -@cindex error strategy -@item --on-error=@var{estrategia} -Aplica @var{estrategia} cuando ocurre un error durante la lectura de -@var{fichero}. @var{estrategia} puede ser uno de los siguientes valores: - -@table @code -@item nothing-special -Informa concisamente del error y termina la ejecución. Es la estrategia -predeterminada. - -@item backtrace -Del mismo modo, pero también muestra la secuencia de llamadas. - -@item debug -Informa del error y entra en el depurador de Guile. A partir de ahí, puede -ejecutar órdenes como @code{,bt} para obtener la secuencia de llamads, -@code{,locals} para mostrar los valores de las variables locales, e -inspeccionar el estado del programa de forma más general. @xref{Debug -Commands,,, guile, GNU Guile Reference Manual}, para una lista de órdenes de -depuración disponibles. -@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 -Muestra un resumen de cada generación del sistema operativo disponible en el -disco, de manera legible por humanos. Es similar a la opción -@option{--list-generations} de @command{guix package} (@pxref{Invocación de guix package}). - -De manera opcional, se puede especificar un patrón, con la misma sintaxis -que la usada en @command{guix package --list-generations}, para restringir -la lista de generaciones mostradas. Por ejemplo, la siguiente orden muestra -generaciones que tienen hasta 10 días de antigüedad: - -@example -$ guix system list-generations 10d -@end example - -@end table - -¡La orden @command{guix system} tiene aún más que ofrecer! Las siguientes -ordenes le permiten visualizar cual es la relación entre los servicios del -sistema: - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Emite en formato Dot/Graphviz por la salida estándar el @dfn{grafo de -extensiones de servicio} del sistema operativo definido en @var{fichero} -(@pxref{Composición de servicios}, para más información sobre extensiones de -servicio). - -La orden: - -@example -$ guix system extension-graph @var{fichero} | dot -Tpdf > servicios.pdf -@end example - -produce un fichero PDF que muestra las relaciones de extensiones entre los -servicios. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Emite en formato Dot/Graphviz por la salida estándar el @dfn{grafo de -dependencias} de los servicios shepherd del sistema operativo definido en -@var{fichero}. @xref{Servicios de Shepherd}, para más información y un grafo de -ejemplo. - -@end table - -@node Ejecutar Guix en una máquina virtual -@section Ejecución de Guix en una máquina virtual - -@cindex máquina virtual -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/guix-system-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Invocación de guix system}). The returned image is in qcow2 -format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently -use. - -@cindex QEMU -Si ha construido su propia imagen, debe copiarla fuera del almacén y -proporcionarse a sí misma permisos de escritura sobre dicha copia antes de -usarla. En la invocación de QEMU debe elegir un emulador de sistema que sea -adecuado para su plataforma hardware. Esta es una invocación de QEMU mínima -que arrancará el resultado de @command{guix system vm-image} en hardware -x86_64: - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/imagen-qemu -@end example - -Aquí está el significado de cada una de esas opciones: - -@table @code -@item qemu-system-x86_64 -Esto especifica la plataforma hardware a emular. Debe corresponder con el -anfitrión. - -@item -net user -Habilita la pila de red en modo de usuaria sin privilegios. El SO -virtualizado puede acceder al anfitrión pero no al revés. Esta es la forma -más simple de poner en línea un SO virtualizado. - -@item -net nic,model=virtio -Debe crear una interfaz de red del modelo proporcionado. Si la crea, el -arranque fallará. Asumiendo que su plataforma hardware sea x86_64, puede -obtener una lista de modelos de interfaz de red disponibles ejecutando -@command{qemu-system-x86_64 -net nic,model=help}. - -@item -enable-kvm -Si su sistema tiene extensiones de virtualización por hardware, la -activación de la implementación de máquinas virtuales (KVM) del núcleo Linux -hará que la ejecución sea más rápida. - -@item -m 256 -RAM disponible para el sistema operativo virtualizado, en mebibytes. El -valor predeterminado es 128@tie{}MiB, que puede ser insuficiente para -algunas operaciones. - -@item /tmp/imagen-qemu -El nombre de fichero de la imagen qcow2. -@end table - -El guión @command{run-vm.sh} predeterminado que devuelve la invocación de -@command{guix system vm} no añade una opción @command{-net user} por -defecto. Para obtener acceso a la red desde la máquina virtual añada el -servicio @code{(dhcp-client-service)} a su definición de sistema y arranque -la máquina virtual mediante el uso de @command{`guix system vm config.scm` --net user}. Un punto importante a tener en cuenta del uso de @command{-net -user} para la obtención de red es que @command{ping} no funcionará, puesto -que usa el protocolo ICMP. Deberá usar una orden diferente para comprobar la -conectividad a la red, por ejemplo @command{guix download}. - -@subsection Conexión a través de SSH - -@cindex SSH -@cindex servidor SSH -Para activar SSH dentro de una máquina virtual debe añadir un servidor SSH -como @code{(dropbear-service)} o @code{(lsh-service)} en su máquina -virtual. El servicio @code{(lsh-service)} no arranca actualmente sin -supervisión, ya que precisa de entrada para inicializar el generador de -aleatoriedad. Además tiene que redirigir el puerto SSH, 22 el -predeterminado, a la máquina anfitriona. Puede hacerlo con - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -Para conectarse a la máquina virtual puede ejecutar - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -La @command{-p} indica a @command{ssh} el puerto al que se debe -conectar. @command{-o UserKnownHostsFile=/dev/null} evita que @command{ssh} -se queje cada vez que modifique su fichero @command{config.scm} y la orden -@command{-o StrictHostKeyChecking=no} evita que tenga que autorizar la -conexión a una máquina desconocida cada vez que se conecte. - -@subsection Uso de @command{virt-viewer} con Spice - -Como alternativa al cliente gráfico predeterminado de @command{qemu} puede -usar @command{remote-viewer} del paquete @command{virt-viewer}. Para -conectarse proporcione la opción @command{-spice -port=5930,disable-ticketing} a @command{qemu}. Véase la sección previa para -más información sobre cómo hacer esto. - -Spice también le permite hacer cosas como compartir su portapapeles con su -máquina virtual. Para activarlo debe proporcionar también las siguientes -opciones a @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 - -También debe añadir el @pxref{Servicios misceláneos, servicio Spice}. - -@node Definición de servicios -@section Definición de servicios - -Las secciones anteriores muestran los servicios disponibles y cómo se pueden -combinar en una declaración @code{operating-system}. ¿Pero cómo las -definimos en primer lugar? ¿Y qué es un servicio en cualquier caso? - -@menu -* Composición de servicios:: El modelo para la composición de servicios. -* Tipos de servicios y servicios:: Tipos y servicios -* Referencia de servicios:: Referencia de la API. -* Servicios de Shepherd:: Un tipo de servicio particular. -@end menu - -@node Composición de servicios -@subsection Composición de servicios - -@cindex services -@cindex daemons -Definimos un @dfn{servicio} como, @i{grosso modo}, algo que extiende la -funcionalidad del sistema operativo. Habitualmente un servicio es un -proceso---un @dfn{daemon}---iniciado cuando el sistema arranca: un servidor -de shell seguro, un servidor Web, el daemon de construcción de Guix, etc. A -veces un servicio es un daemon cuya ejecución puede ser iniciada por otro -daemon---por ejemplo, un servidor FTP iniciado por @command{inetd} o un -servicio D-Bus activado por @command{dbus-daemon}. De manera ocasional, un -servicio no se puede asociar a un daemon. Por ejemplo, el servicio -``account'' recopila cuentas de usuaria y se asegura que existen cuando el -sistema se ejecuta; el servicio ``udev'' recopila reglas de gestión de -dispositivos y los pone a disposición del daemon eudev; el servicio -@file{/etc} genera el contenido del directorio @file{/etc} del sistema. - -@cindex extensiones de servicios -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{Servicios de red, -@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{Servicios de escritorio, -@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{Servicios base}). - -Al fin y al cabo, los servicios y sus relaciones de ``extensión'' forman un -grafo acíclico dirigido (GAD). Si representamos los servicios como cajas y -las extensiones como flechas, un sistema típico puede proporcionar algo de -este estilo: - -@image{images/service-graph,,5in,Grafo típico de extensiones de servicios.} - -@cindex servicio del sistema -En la base, podemos ver el @dfn{servicio del sistema}, el cual produce el -directorio que contiene todo lo necesario para ejecutar y arrancar el -sistema, como es devuelto por la orden @command{guix system -build}. @xref{Referencia de servicios}, para aprender acerca de otros servicios -mostrados aquí. @xref{system-extension-graph, la orden @command{guix system -extension-graph}}, para información sobre cómo generar esta representación -para una definición particular de sistema operativo. - -@cindex tipos de servicio -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. - -La siguiente sección describe la interfaz programática para tipos de -servicio y servicios. - -@node Tipos de servicios y servicios -@subsection Tipos de servicios y servicios - -Un @dfn{tipo de servicio} es un nodo en el GAD descrito -previamente. Empecemos con un ejemplo simple, el tipo de servicio para el -daemon de construcción Guix (@pxref{Invocación de 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 -Define tres cosas: - -@enumerate -@item -Un nombre, cuyo único propósito es facilitar la inspección y la depuración. - -@item -Una lista de @dfn{extensiones de servicio}, donde cada extensión designa el -tipo de servicio a extender y un procedimiento que, dados los parámetros del -servicio, devuelve una lista de objetos para extender el servicio de dicho -tipo. - -Cada tipo de servicio tiene al menos una extensión de servicio. La única -excepción es el @dfn{tipo de servicio de arranque}, que es el último -servicio. - -@item -De manera opcional, un valor predeterminado para instancias de este tipo. -@end enumerate - -In this example, @code{guix-service-type} extends three services: - -@table @code -@item shepherd-root-service-type -The @code{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Servicios de Shepherd}). - -@item account-service-type -This extension for this service is computed by @code{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Invocación de guix-daemon}). - -@item activation-service-type -Here @code{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 - -Un servicio de este tipo se puede instanciar de esta manera: - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -El segundo parámetro a la forma @code{service} es un valor que representa -los parámetros de esta instancia específica del -servicio. @xref{guix-configuration-type, @code{guix-configuration}}, para -información acerca del tipo de datos @code{guix-configuration}. Cuando se -omite el valor, se usa el valor predeterminado por @code{guix-service-type}: - -@example -(service guix-service-type) -@end example - -@code{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -El tipo de servicio para un servicio @emph{extensible} puede tener esta -forma: - -@example -(define udev-service-type - (service-type (name 'udev) - (extensions - (list (service-extension shepherd-root-service-type - udev-shepherd-service))) - - (compose concatenate) ;concatena la lista de reglas - (extend (lambda (config rules) - (match config - (($ udev initial-rules) - (udev-configuration - (udev udev) ;el paquete udev a usar - (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 -@code{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -Este es el procedimiento para @dfn{componer} la lista de extensiones en -servicios de este tipo. - -Los servicios pueden extender el servicio udev proporcionandole una lista de -reglas; componemos estas extensiones simplemente concatenandolas. - -@item extend -Este procedimiento define cómo el valor del servicio se @dfn{extiende} con -la composición de la extensión. - -Las extensiones de udev se componen en una lista de reglas, pero el valor -del servicio udev es en sí un registro @code{}. Por -tanto aquí extendemos el registro agregando la lista de reglas que contiene -al final de la lista de reglas que se contribuyeron. - -@item description -Es una cadena que proporciona una descripción del tipo de servicio. Dicha -cadena puede contener lenguaje de marcado Texinfo (@pxref{Overview,,, -texinfo, GNU Texinfo}). La orden @command{guix system search} busca estas -cadenas y las muestra (@pxref{Invocación de guix system}). -@end table - -There can be only one instance of an extensible service type such as -@code{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -¿Todavía aquí? La siguiente sección proporciona una referencia de la -interfaz programática de los servicios. - -@node Referencia de servicios -@subsection Referencia de servicios - -Ya hemos echado un vistazo a los tipos de servicio (@pxref{Tipos de servicios y servicios}). Esta sección proporciona referencias sobre cómo manipular -servicios y tipos de servicio. Esta interfaz se proporciona en el módulo -@code{(gnu services)}. - -@deffn {Procedimiento Scheme} service @var{tipo} [@var{valor}] -Devuelve un nuevo servicio de @var{tipo}, un objeto @code{} -(véase a continuación). @var{valor} puede ser cualquier objeto; represental -los parámetros de esta instancia de servicio particular. - -Cuando se omite @var{valor}, se usa el valor predeterminado especificado por -@var{tipo}; si @var{type} no especifica ningún valor, se produce un error. - -Por ejemplo, esto: - -@example -(service openssh-service-type) -@end example - -@noindent -es equivalente a esto: - -@example -(service openssh-service-type - (openssh-configuration)) -@end example - -En ambos casos el resultado es una instancia de @code{openssh-service-type} -con la configuración predeterminada. -@end deffn - -@deffn {Procedimiento Scheme} service? @var{obj} -Devuelve verdadero si @var{obj} es un servicio. -@end deffn - -@deffn {Procedimiento Scheme} service-kind @var{servicio} -Devuelve el tipo de @var{servicio}---es decir, un objeto -@code{}. -@end deffn - -@deffn {Procedimiento Scheme} service-value @var{servicio} -Devuelve el valor asociado con @var{servicio}. Representa sus parámetros. -@end deffn - -Este es un ejemplo de creación y manipulación de un servicio: - -@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 @code{%base-services} -(@pxref{Servicios base, @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 {Sintaxis Scheme} modify-services @var{servicios} @ - (@var{tipo} @var{variable} => @var{cuerpo}) @dots{} - -Modifica los servicios listados en @var{servicios} de acuerdo a las -cláusulas proporcionadas. Cada cláusula tiene la forma: - -@example -(@var{tipo} @var{variable} => @var{cuerpo}) -@end example - -donde @var{tipo} es un tipo de servicio---por ejemplo, -@code{guix-service-type}---y @var{variable} es un identificador que se -asocia dentro del @var{cuerpo} a los parámetros del servicio---por ejemplo, -una instancia @code{guix-configuration}---del servicio original de dicho -@var{ŧipo}. - -El @var{cuerpo} deve evaluar a los nuevos parámetros del servicio, que serán -usados para configurar el nuevo servicio. Este nuevo servicio reemplaza el -original en la lista resultante. Debido a que los parámetros de servicio de -un servicio se crean mediante el uso de @code{define-record-type*}, puede -escribir un breve @var{cuerpo} que evalúe a los nuevos parámetros del -servicio mediante el uso de la característica @code{inherit} que proporciona -@code{define-record-type*} para heredar los valores antiguos. - -@xref{Uso de la configuración del sistema}, para ejemplos de uso. - -@end deffn - -A continuación se procede con la interfaz programática de los tipos de -servicios. Es algo que debe conocer para escribir definiciones de nuevos -servicios, pero no es cuando busque formas de personalizar su declaración -@code{operating-system}. - -@deftp {Tipo de datos} service-type -@cindex tipo de servicio -Esta es la representación de un @dfn{tipo de servicio} (@pxref{Tipos de servicios y servicios}). - -@table @asis -@item @code{name} -Es un símbolo, usado únicamente para simplificar la inspección y la -depuración. - -@item @code{extensions} -Una lista no vacía de objetos @code{} (véase a -continuación). - -@item @code{compose} (predeterminado: @code{#f}) -Si es @code{#f}, entonces el tipo de servicio denota servicios que no pueden -extenderse---es decir, servicios que no pueden recibir ``valores'' de otros -servicios. - -En otro caso, debe ser un procedimiento de un único parámetro. El -procedimiento es invocado en @code{fold-services} y se le proporciona una -lista de valores recibidos de las extensiones. Puede devolver un valor -único. - -@item @code{extend} (predeterminado: @code{#f}) -Si es @code{#f}, los servicios de este tipo no pueden extenderse. - -En otro caso, debe ser un procedimiento que acepte dos parámetros: -@code{fold-services} lo invoca, proporcionandole el valor inicial del -servicio como el primer parámetro y el resultado de aplicar @code{compose} a -los valores de las extensiones como segundo parámetro. Debe devolver un -valor que es un parámetro válido para la instancia del servicio. -@end table - -@xref{Tipos de servicios y servicios}, para ejemplos. -@end deftp - -@deffn {Procedimiento Scheme} service-extension @var{tipo-deseado} @ - @var{calcula} - -Devuelve una nueva extensión para servicios del tipo -@var{tipo-deseado}. @var{calcula} debe ser un procedimiento de un único -parámetro: es llamado en @code{fold-services}, proporcionandole el valor -asociado con el servicio que proporciona la extensión; debe devolver un -valor válido para el servicio deseado. -@end deffn - -@deffn {Procedimiento Scheme} service-extension? @var{obj} -Devuelve verdadero si @var{obj} es una expresión-G. -@end deffn - -De manera ocasional, puede desear simplemente extender un servicio -existente. Esto implica la creación de un nuevo tipo de servicio y la -especificación de la extensión deseada, lo cual puede ser engorroso; el -procedimiento @code{simple-service} proporciona un atajo para ello. - -@deffn {Procedimiento Scheme} simple-service @var{nombre} @var{deseado} @var{valor} -Devuelve un servicio que extiende @var{deseado} con @var{valor}. Esto -funciona creando una instancia única del tipo de servicio @var{nombre}, de -la cual el servicio devuelto es una instancia. - -Por ejemplo, esto extiende mcron (@pxref{Ejecución de tareas programadas}) con una -tarea adicional: - -@example -(simple-service 'mi-tarea-mcron mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -En el núcleo de la abstracción de los servicios se encuentra el -procedimiento @code{fold-services}, que es responsable de la ``compilación'' -de una lista de servicios en un único directorio que contiene todo lo -necesario para arrancar y ejecutar el sistema---el directorio mostrado por -la orden @command{guix system build} (@pxref{Invocación de guix system}). En -esencia, propaga las extensiones de servicios a través del grafo de -servicios, actualizando los parámetros de cada nodo en el camino, hasta que -alcanza el nodo raíz. - -@deffn {Procedimiento Scheme} fold-services @var{servicios} @ - [#:target-type @var{system-service-type}] -Recorre @var{servicios} propagando sus extensiones hasta la raíz del tipo -@var{target-type}; devuelve el servicio raíz tratado de la manera apropiada. -@end deffn - -Por último, el módulo @code{(gnu services)} también define varios tipos -esenciales de servicios, algunos de los cuales se enumeran a continuación. - -@defvr {Variable Scheme} system-service-type -Esta es la raíz del grafo de servicios. Produce el directorio del sistema -como lo devuelve la orden @code{guix system build}. -@end defvr - -@defvr {Variable Scheme} boot-service-type -El tipo del ``servicio de arranque'', que produce un @dfn{guión de -arranque}. El guión de arranque es lo que ejecuta el disco inicial de RAM -cuando se arranca. -@end defvr - -@defvr {Variable Scheme} etc-service-type -El tipo del servicio @file{/etc}. Este servicio se usa para crear los -ficheros en @file{/etc} y puede extenderse proporcionandole pares -nombre/fichero como estas: - -@example -(list `("issue" ,(plain-file "issue" "¡Bienvenida!\n"))) -@end example - -En este ejemplo, el ejecto sería la adición de un fichero @file{/etc/issue} -que apunta al fichero proporcionado. -@end defvr - -@defvr {Variable Scheme} setuid-program-service-type -Tipo para el ``servicio de programas setuid''. Este servicio recopila listas -de nombres de ficheros ejecutables, proporcionados como expresiones-G, y los -añade al conjunto de programas con setuid de root en el sistema -(@pxref{Programas con setuid}). -@end defvr - -@defvr {Variable Scheme} profile-service-type -Tipo del servicio que genera el @dfn{perfil del sistema}---es decir, los -programas en @file{/run/current-system/profile}. Otros servicios pueden -extenderlo proporcionandole listas de paquetes a añadir al perfil del -sistema. -@end defvr - - -@node Servicios de Shepherd -@subsection Servicios de Shepherd - -@cindex servicios de shepherd -@cindex PID 1 -@cindex sistema de inicio -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{Introducción,,, shepherd, The GNU Shepherd Manual}). - -Los servicios en Shepherd pueden depender de otros servicios. Por ejemplo, -el daemon SSH puede tener que arrancarse tras el arranque del daemon syslog, -lo cual a su vez puede suceder únicamente tras el montaje de todos los -sistemas de ficheros. El sistema operativo simple definido previamente -(@pxref{Uso de la configuración del sistema}) genera un grafo de servicios como -este: - -@image{images/shepherd-graph,,5in,Grafo típico de servicios de shepherd.} - -En realidad puede generar dicho grafo para cualquier definición de sistema -operativo mediante el uso de la orden @command{guix system shepherd-graph} -(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @code{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by -passing it lists of @code{} objects. - -@deftp {Tipo de datos} shepherd-service -El tipo de datos que representa un servicio gestionado por Shepherd. - -@table @asis -@item @code{provision} -Una lista de símbolos que indican lo que proporciona el servicio. - -Esto son nombres que pueden proporcionarse a @command{herd start}, -@command{herd status} y órdenes similares (@pxref{Invoking herd,,, shepherd, -The GNU Shepherd Manual}). @xref{Slots of services, the @code{provides} -slot,, shepherd, The GNU Shepherd Manual}, para más detalles. - -@item @code{requirements} (predeterminados: @code{'()}) -Lista de símbolos que indican los servicios Shepherd de los que este -depende. - -@cindex one-shot services, for the Shepherd -@item @code{one-shot?} (predeterminado: @code{#f}) -Whether this service is @dfn{one-shot}. One-shot services stop immediately -after their @code{start} action has completed. @xref{Slots of services,,, -shepherd, The GNU Shepherd Manual}, for more info. - -@item @code{respawn?} (predeterminado: @code{#t}) -Indica si se debe reiniciar el servicio cuando se para, por ejemplo cuando -el proceso subyacente muere. - -@item @code{start} -@itemx @code{stop} (predeterminado: @code{#~(const #f)}) -Los campos @code{start} y @code{stop} hacen referencia a las características -de Shepherd de arranque y parada de procesos respectivamente (@pxref{Service -De- and Constructors,,, shepherd, The GNU Shepherd Manual}). Se proporcionan -como expresiones-G que se expandirán en el fichero de configuración de -Shepherd (@pxref{Expresiones-G}). - -@item @code{actions} (predeterminadas: @code{'()}) -@cindex acciones, de servicios de Shepherd -Esta es la lista de objetos @code{shepherd-action} (véase a continuación) -que definen las @dfn{acciones} permitidas por el servicio, además de las -acciones estándar @code{start} y @code{stop}. Las acciones que se listan -aquí estarán disponibles como ordenes de @command{herd}: - -@example -herd @var{acción} @var{servicio} [@var{parámetros}@dots{}] -@end example - -@item @code{documentación} -Una cadena de documentación, que se mostrará al ejecutar: - -@example -herd doc @var{nombre-del-servicio} -@end example - -where @var{service-name} is one of the symbols in @code{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @code{%default-modules}) -Esta es la lista de módulos que deben estar dentro del ámbito cuando -@code{start} y @code{stop} son evaluados. - -@end table -@end deftp - -@deftp {Tipo de datos} shepherd-action -Este es el tipo de datos que define acciones adicionales implementadas por -un servicio Shepherd (vea previamente). - -@table @code -@item name -Símbolo que nombra la acción. - -@item documentación -Esta es una cadena de documentación para la acción. Puede verse ejecutando: - -@example -herd doc @var{servicio} action @var{acción} -@end example - -@item procedure -Debe ser una expresión-G que evalua a un procedimiento de al menos un -parámetro, el cual es el ``valor de ejecución'' del servicio (@pxref{Slots -of services,,, shepherd, The GNU Shepherd Manual}). -@end table - -El siguiente ejemplo define una acción llamada @code{di-hola} que saluda -amablemente a la usuaria: - -@example -(shepherd-action - (name 'di-hola) - (documentation "¡Di hola!") - (procedure #~(lambda (running . args) - (format #t "¡Hola, compa! parámetros: ~s\n" - args) - #t))) -@end example - -Asumiendo que esta acción se añade al servicio @code{ejemplo}, puede -ejecutar: - -@example -# herd di-hola ejemplo -¡Hola, compa! parámetros: () -# herd di-hola ejemplo a b c -¡Hola, compa! parámetros: ("a" "b" "c") -@end example - -Esta, como puede ver, es una forma un tanto sofisticada de decir -hola. @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, para -más información sobre acciones. -@end deftp - -@defvr {Variable Scheme} shepherd-root-service-type -El tipo de servicio para el ``servicio raíz'' de Shepherd---es decir, -PID@tie{}1. - -El tipo de servicio que las extensiones declaran cuando desean crear -servicios shepherd (@pxref{Tipos de servicios y servicios}, para un -ejemplo). Cada extensión debe pasar una lista de @code{}. -@end defvr - -@defvr {Variable Scheme} %shepherd-root-service -Este servicio representa el PID@tie{}1. -@end defvr - - -@node Documentación -@chapter Documentación - -@cindex documentación, búsqueda -@cindex búsqueda de documentación -@cindex Info, formato de documentación -@cindex páginas man -@cindex páginas de manual -En la mayor parte de casos, los paquetes instalados con Guix contienen -documentación. Hay dos formatos principales de documentación: ``Info'', un -formato hipertextual navegable usado para software GNU, y ``páginas de -manual'' (o ``páginas man''), la documentación lineal encontrada -tradicionalmente en Unix. Se accede a los manuales Info con la orden -@command{info} o con Emacs, y las páginas man con @command{man}. - -Puede buscar documentación de software instalado en su sistema por palabras -clave. Por ejemplo, la siguiente orden busca información sobre ``TLS'' en -manuales Info: - -@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 -La orden siguiente busca por la misma palabra clave en páginas man: - -@example -$ man -k TLS -SSL (7) - OpenSSL SSL/TLS library -certtool (1) - GnuTLS certificate tool -@dots {} -@end example - -Estas búsquedas son completamente locales en su máquina de modo que tiene la -garantía de que la documentación que encuentre corresponde con lo que está -realmente instalado, puede acceder a ella sin conexión a la red, y se -respeta su privacidad. - -Una vez tenga estos resultados, puede ver la documentación relevante -mediante la ejecución de, digamos: - -@example -$ info "(gnutls)Core TLS API" -@end example - -@noindent -o: - -@example -$ man certtool -@end example - -Los manuales Info contienen secciones e índices, así como enlaces como -aquellos encontrados en páginas Web. El lector @command{info} (@pxref{Top, -Info reader,, info-stnd, Stand-alone GNU Info}) y su contraparte en Emacs -(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) proporcionan -combinaciones de teclas intuitivas para la navegación en los -manuales. @xref{Getting Started,,, info, Info: An Introduction}, para una -introducción a la navegación en Info. - -@node Instalación de ficheros de depuración -@chapter Instalación de ficheros de depuración - -@cindex ficheros de depuración -Los programas binarios, como los producidos por los compiladores GCC por -ejemplo, se escriben típicamente en el formato ELF, con una sección que -contiene @dfn{información de depuración}. La información de depuración es lo -que permite que el depurador, GDB, asocie código binario a código fuente; es -necesaria para depurar un programa compilado en condiciones adecuadas. - -El problema con la información de depuración es que ocupa un espacio -considerable en el disco. Por ejemplo, la información de depuración de la -biblioteca C de GNU ocupa más de 60 MiB. Por tanto, como usuaria, mantener -toda la información de depuración de todos los programas instalados no es -habitualmente una opción. No obstante, el ahorro de espacio no debe ser -impedir la depuración---especialmente en el sistema GNU, que debería -facilitar a sus usuarias ejercitar su libertad de computación (@pxref{Distribución GNU}). - -Afortunadamente, las utilidades binarias GNU (Binutils) y GDB proporcionan -un mecanismo que permite a las usuarias obtener lo mejor de ambos mundos: la -información de depuración puede extraerse de los binarios y almacenarse en -ficheros separados. GDB es capaz entonces de cargar la información de -depuración desde esos ficheros, cuando estén disponibles (@pxref{Separate -Debug Files,,, gdb, Debugging with GDB}). - -La distribución GNU toma ventaja de este hecho almacenando la información de -depuración en el subdirectorio @code{lib/debug} de una salida separada del -paquete llamada @code{debug} (@pxref{Paquetes con múltiples salidas}). Las -usuarias pueden elegir si instalan la salida @code{debug} de un paquete -cuando la necesitan. Por ejemplo, la siguiente orden instala la información -de depuración para la biblioteca C de GNU y para GNU Guile. - -@example -guix package -i glibc:debug guile:debug -@end example - -Se debe decir entonces a GDB que busque los ficheros de depuración en el -perfil de la usuaria, proporcionando un valor a la variable -@code{debug-file-directory} (considere hacerlo en el fichero -@file{~/.gdbinit}, @pxref{Startup,,, gdb, Debugging with GDB}): - -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example - -A partir de ese momento GDB obtendrá la información de depuración de los -ficheros @code{.debug} bajo @file{~/.guix-profile/lib/debug}. - -Además, probablemente desee que GDB sea capaz de mostrar el código fuente -que está depurando. Para hacerlo, tiene que desempaquetar el código fuente -del paquete de su interés (obtenido con @code{guix build --source}, -@pxref{Invocación de guix build}) e indicar a GDB cual es el directorio de -fuentes mediante el uso de la orden @code{directory} (@pxref{Source Path, -@code{directory},, gdb, Debugging with GDB}). - -@c XXX: keep me up-to-date -El mecanismo de la salida @code{debug} en Guix se implementa por el sistema -de construcción @code{gnu-build-system} (@pxref{Sistemas de construcción}). Ahora mismo -necesita una activación explícita---la información de depuración está -disponible únicamente para paquetes con definiciones que declaren -explícitamente una salida @code{debug}. Esto puede cambiarse por una -activación implícita en el futuro si nuestras granjas de construcción pueden -soportar la carga. Para comprobar si un paquete tiene una salida -@code{debug}, use @command{guix package --list-available} (@pxref{Invocación de guix package}). - - -@node Actualizaciones de seguridad -@chapter Actualizaciones de seguridad - -@cindex actualizaciones de seguridad -@cindex vulnerabilidades de seguridad -De manera ocasional, vulnerabilidades importantes de seguridad se descubren -en los paquetes de software y deben parchearse. Las desarrolladoras de Guix -tratan de seguir las vulnerabilidades conocidas y aplicar parches tan pronto -como sea posible en la rama @code{master} de Guix (todavía no proporcionamos -una rama ``estable'' que contenga únicamente actualizaciones de -seguridad). La herramienta @command{guix lint} ayuda a las desarrolladoras a -encontrar versiones vulnerables de paquetes de software en la distribución: - -@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{Invocación de guix lint}, para más información. - -@quotation Nota -En la versión @value{VERSION}, esta característica descrita a continuación -se considera en estado ``beta''. -@end quotation - -Guix sigue una disciplina funcional de gestión de paquetes -(@pxref{Introducción}), lo que implica que, cuando se cambia un paquete, -@emph{todos los paquetes que dependen de él} deben ser reconstruidos. Esto -puede ralentizar de manera significativa el despliegue de correcciones en -paquetes básicos como libc o Bash, ya que básicamente la distribución al -completo debe reconstruirse. El uso de binarios preconstruidos ayuda -(@pxref{Sustituciones}), pero el despliegue aún puede tomar más tiempo del -deseado. - -@cindex injertos (grafts en inglés) -Para afrontar esto, Guix implementa @dfn{injertos}, un mecanismo que permite -un rápido despliegue de actualizaciones críticas sin los costes asociados -con una reconstrucción completa de la distribución. La idea es reconstruir -únicamente el paquete que hace falta parchear, y entonces ``injertarlo'' en -los paquetes explícitamente instalados por la usuaria y que previamente -hacían referencia al paquete original. El coste de realizar un injerto es -menor que una reconstrucción completa de la cadena de dependencias. - -@cindex reemplazos de paquetes, para injertos -For instance, suppose a security update needs to be applied to Bash. Guix -developers will provide a package definition for the ``fixed'' Bash, say -@code{bash-fixed}, in the usual way (@pxref{Definición de paquetes}). 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{Invocación de guix gc})---that -is installed is automatically ``rewritten'' to refer to @code{bash-fixed} -instead of @code{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 (@code{bash-fixed} and @code{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. - -La opción de línea de órdenes @option{--no-grafts} le permite anular -voluntariamente el proceso de injerto (@pxref{Opciones comunes de construcción, -@option{--no-grafts}}). Por tanto, la orden: - -@example -guix build bash --no-grafts -@end example - -@noindent -devuelve el nombre de fichero del almacén de la versión original de Bash, -mientras que: - -@example -guix build bash -@end example - -@noindent -devuelve el nombre de fichero del almacén de la versión ``corregida'', -reemplazo de Bash. Esto le permite distinguir entre las dos variantes de -Bash. - -Para verificar a qué Bash hace referencia su perfil al completo, puede -ejecutar (@pxref{Invocación de guix gc}): - -@example -guix gc -R `readlink -f ~/.guix-profile` | grep bash -@end example - -@noindent -@dots{} y compare los nombres de fichero del almacén que obtendrá con los -ejemplos previos. Del mismo modo, para una generación completa del sistema -Guix: - -@example -guix gc -R `guix system build mi-configuracion.scm` | grep bash -@end example - -Por último, para comprobar qué versión de Bash están usando los procesos en -ejecución, puede usar la orden @command{lsof}: - -@example -lsof | grep /gnu/store/.*bash -@end example - - -@node Lanzamiento inicial -@chapter Lanzamiento inicial - -@c Adapted from the ELS 2013 paper. - -@cindex lanzamiento inicial - -El lanzamiento inicial en nuestro contexto hace referencia a cómo la -distribución se construye ``de la nada''. Recuerde que el entorno de -construcción de una derivación no contiene más que sus entradas declaradas -(@pxref{Introducción}). Por lo que hay un evidente problema ``del huevo y la -gallina'': ¿cómo se construye el primer paquete? ¿Cómo se compila el primer -compilador? Fíjese que esta es una cuestión de interés únicamente para la -hacker curiosa, no para la usuaria normal, así que puede pasar por encima -está sección sin ninguna vergüenza si se considera una ``usuaria normal''. - -@cindex binarios del lanzamiento inicial -El sistema GNU está compuesto principalmente de código C, con libc en su -base. El sistema de construcción GNU en sí asume la disponibilidad del shell -Bourne y las herramientas de línea de órdenes proporcionadas por GNU -Coreutils, Awk, Findutils, `sed' y `grep'. Además, los programas de -construcción---programas que ejecutan @code{./configure}, @code{make}, -etc.---están escritos en Scheme Guile -(@pxref{Derivaciones}). Consecuentemente, para ser capaz de construir -cualquier cosa, desde cero, Guix depende en binarios preconstruidos de -Guile, GCC, Binutils, libc y otros paquetes mencionados anteriormente---los -@dfn{binarios del lanzamiento inicial}. - -Estos binarios del lanzamiento inicial se ``dan por supuestos'', aunque se -pueden volver a crear si se necesita (más sobre esto más adelante). - -@unnumberedsec Preparación para usar los binarios del lanzamiento inicial - -@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,,Grafo de dependencias de las derivaciones -del lanzamiento inicial temprano} - -La figura previa muestra el auténtico inicio del grafo de dependencias de la -distribución, correspondiente a las definiciones de paquete del módulo -@code{(gnu packages bootstrap)}. Un gráfico similar puede generarse con -@command{guix graph} (@pxref{Invocación de guix graph}), más o menos así: - -@example -guix graph -t derivation \ - -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ - | dot -Tps > t.ps -@end example - -En este nivel de detalle, las cosas son ligeramente complejas. Primero, -Guile en sí consiste en un ejecutable ELF, junto a muchas fuentes y ficheros -compilados Scheme que se cargan dinámicamente durante la ejecución. Esto se -almacena en el archivador tar @file{guile-2.0.7.tar.xz} mostrado en este -grafo. Este archivador es parte de la distribución de ``fuentes'' de Guix, y -se inserta en el almacén con @code{add-to-store} (@pxref{El almacén}). - -¿Pero cómo escribimos una derivación que extraiga este archivador y lo añada -al almacén? Para resolver este problema, la derivación -@code{guile-bootstrap-2.0.drv}---la primera en construirse---usa @code{bash} -como su constructor, que ejecuta @code{build-bootstrap-guile.sh}, que a su -vez llama a @code{tar} para extraer el archivador. Por tanto, @file{bash}, -@file{tar}, @file{xz} y @file{mkdir} son binarios enlazados estáticamente, -también parte de la distribución de fuentes de Guix, cuyo único propósito es -permitir la extracción del archivador de Guile. - -Una vez que@code{guile-bootstrap-2.0.drv} se ha construido, tenemos un Guile -funcional que se puede usar para ejecutar los programas de construcción -siguientes. Su primera tarea es descargar los archivadores qu contienen los -otros binarios preconstruidos---esto es lo que las derivaciones -@code{.tar.xz.drv} hacen. Módulos Guix como @code{ftp-client.scm} se usan -para este propósito. Las derivaciones @code{module-import.drv} importan esos -módulos en un directorio del almacén, manteniendo la distribución de -carpetas. Las derivaciones @code{module-import-compiled.drv} compilan esos -módulos, y los escriben en un directorio con la distribución de carpetas -correcta. Esto corresponde al parámetro @code{#:modules} de -@code{build-expression->derivation} (@pxref{Derivaciones}). - -Finalmente, los archivadores tar son extraídos por las derivaciones -@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etcétera, hasta el -punto en el que disponemos de una cadena de herramientas C funcional. - - -@unnumberedsec Construcción de las herramientas de construcción - -El lanzamiento inicial está completo cuando tenemos una cadena de -herramientas completa que no depende en las herramientas preconstruidas del -lanzamiento inicial descritas previamente. Este requisito de no-dependencia -se verifica comprobando si los ficheros de la cadena de herramientas final -contienen referencias a directorios de @file{/gnu/store} de las entradas del -lanzamiento. El proceso que lleva a esta cadena de herramientas ``final'' es -descrito por las definiciones de paquetes encontradas en el módulo -@code{(gnu packages commencement)}. - -La orden @command{guix graph} nos permite ``distanciarnos'' en comparación -con el grafo previo, mirando al nivel de objetos de paquetes en vez de -derivaciones individuales---recuerde que un paquete puede traducirse en -varias derivaciones, típicamente una derivación para descargar sus fuentes, -una para construir los módulos Guile que necesita y uno para realmente -construir el paquete de las fuentes. La orden: - -@example -guix graph -t bag \ - -e '(@@@@ (gnu packages commencement) - glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps -@end example - -@noindent -produce el grafo de dependencias que lleva a la biblioteca C -``final''@footnote{Puede haberse dado cuenta de la etiqueta -@code{glibc-intermediate}, sugiriendo que no es @emph{completamente} final, -pero como es una buena aproximación, la consideraremos final}, mostrado a -continuación. - -@image{images/bootstrap-packages,6in,,Grafo de dependencias de los primeros -paquetes} - -@c See . -La primera herramienta que se construye con los binarios del lanzamiento -inicial es GNU@tie{}Make---marcado como @code{make-boot0} en el grafo---, -que es un pre-requisito para todos los paquetes siguientes. Una vez hecho se -construyen Findutils y Diffutils. - -Después viene la primera fase de Binutils y GCC, construidas como -herramientas pseudo-cruzadas---es decir, con @code{--target} igual a -@code{--host}. Se usan para construir libc. Gracias a este truco de -compilación cruzada, se garantiza que esta libc no tendrá ninguna referencia -a la cadena de herramientas inicial. - -Posteriormente se construyen las herramientas Binutils y GCC (no mostradas -previamente) finales, y enlazan los programas contra la libc recién -construía. Esta cadena de herramientas se usa para construir otros paquetes -usados por Guix y el sistema de construcción GNU: Guile, Bash, Coreutils, -etc. - -¡Y voilà! En este punto tenemos un conjunto completo de herramientas de -construcción esperadas por el sistema de construcción GNU. Están en la -variable @code{%final-inputs} del módulo @code{(gnu packages commencement)}, -y se usan implícitamente por cualquier paquete que use -@code{gnu-build-system} (@pxref{Sistemas de construcción, @code{gnu-build-system}}). - - -@unnumberedsec Construir los binarios de lanzamiento - -@cindex binarios del lanzamiento inicial -Debido a que la cadena de herramientas final no depende de los binarios de -lanzamiento, estos rara vez necesitan ser actualizados. No obstante, es útil -tener una forma automatizada de producirlos en caso de que se dé una -actualización, y esto es lo que proporciona el módulo @code{(gnu packages -make-bootstrap)}. - -La siguiente orden construye los archivadores que contienen los binarios de -lanzamiento (Guile, Binutils, GCC, libc, y un archivador que contiene una -mezcla de Coreutils y otras herramientas básicas de línea de órdenes): - -@example -guix build bootstrap-tarballs -@end example - -Los archivadores generados son aquellos que son referenciados en el módulo -@code{(gnu packages bootstrap)} mencionado al inicio de esta sección. - -¿Todavía aquí? Entonces quizá se habrá empezado a preguntar: ¿cuándo -llegamos a un punto fijo? ¡Esa es una pregunta interesante! La respuesta es -desconocida, pero si pudiese investigar más a fondo (y tiene unos recursos -computacionales y de almacenamiento significativos para hacerlo) háganoslo -saber. - -@unnumberedsec Reducción del conjunto de binarios de lanzamiento - -Nuestros binarios de lanzamiento actualmente incluyen GCC, Guile, etc. ¡Eso -es un montón de código binario! ¿Por qué es eso un problema? Es un problema -porque esos chorros de código binario no son auditables en la práctica, lo -que hace difícil establecer qué código fuente los produjo. Cada binario -no-auditable también nos deja vulnerables a puertas traseras en los -compiladores, como describió Ken Thompson en su publicación de 1984 -@emph{Reflections on Trusting Trust}. - -Esto se mitiga por el hecho de que nuestros binarios de lanzamiento fueron -generados por una revisión anterior de Guix. No obstante, esto no posee el -nivel de transparencia que obtenemos en el resto del grado de dependencias -de los paquetes, donde Guix siempre nos da una asociación de -fuente-a-binario. Por lo tanto, nuestro objetivo es reducir el conjunto de -binarios de lanzamiento al mínimo posible. - -El @uref{http://bootstrappable.org, sitio web Bootstrappable.org} enumera -proyectos en activo realizándolo. Uno de ellos está a punto de sustituir el -GCC de lanzamiento con una secuencia de ensambladores, interpretes y -compiladores de complejidad incremental, que pueden ser construidos desde -las fuentes empezando con un código ensamblador simple y auditable. ¡Su -ayuda es bienvenida! - - -@node Transportar -@chapter Transportar a una nueva plataforma - -Como se explicó previamente, la distribución GNU es autocontenida, lo cual -se consigue dependiendo de unos ``binarios del lanzamiento inicial'' -preconstruidos (@pxref{Lanzamiento inicial}). Estos binarios son específicos para -un núcleo del sistema operativo, arquitectura de la CPU e interfaz binaria -de aplicaciones (ABI). Por tanto, para transportar la distribución a una -nueva plataforma que no está soportada todavía, se deben construir estos -binarios del lanzamiento inicial, y actualizar el módulo @code{(gnu packages -bootstrap)} para usarlos en dicha plataforma. - -Por suerte, Guix puede @emph{compilar de forma cruzada} esos binarios del -lanzamiento inicial. Cuando todo va bien, y asumiendo que la cadena de -herramientas GNU soporta para la plataforma deseada, esto puede ser tan -simple como ejecutar una orden así: - -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example - -Para que esto funcione, el procedimiento @code{glibc-dynamic-linker} en -@code{(gnu packages bootstrap)} debe aumentarse para devolver el nombre de -fichero correcto para el enlazador dinámico de libc en dicha plataforma; de -igual manera, @code{system->linux-architecture} en @code{(gnu packages -linux)} debe modificarse para la nueva plataforma. - -Una vez construidos, el módulo @code{(gnu packages bootstrap)} debe ser -actualizado para hacer referencia a estos binarios en la plataforma -deseada. Esto es, los hash y las URL de los archivadores del lanzamiento -inicial de la nueva plataforma deben añadirse junto a aquellos de las -plataformas disponibles actualmente. El archivador tar del Guile usado para -el lanzamiento inicial se trata de forma especial: se espera que esté -disponible localmente, y @file{gnu/local.mk} tiene reglas que lo descargan -para las arquitecturas disponibles; se debe añadir una regla para la nueva -plataforma también. - -En la práctica puede haber algunas complicaciones. Primero, puede ser que la -tripleta extendida GNU que especifica un ABI (como el sufijo @code{eabi} -previamente) no es reconocida por todas las herramientas GNU. Típicamente, -glibc reconoce algunas de ellas, mientras que GCC usa una opción de -configuración extra @code{--with-abi} (vea @code{gcc.scm} para ejemplos de -como manejar este caso). En segundo lugar, algunos de los paquetes -necesarios pueden fallar en su construcción para dicha plataforma. Por -último, los binarios generados pueden estar defectuosos por alguna razón. - -@c ********************************************************************* -@include contributing.es.texi - -@c ********************************************************************* -@node Reconocimientos -@chapter Reconocimientos - -Guix está basado en el @uref{http://nixops.org/nix, gestor de paquetes Nix}, -que fue diseñado e implementado por Eelco Dolstra, con contribuciones de -otra gente (véase el fichero @file{nix/AUTHORS} en Guix). Nix fue pionero en -la gestión de paquetes funcional, y promovió características sin -precedentes, como las actualizaciones de paquetes transaccionales y vuelta -atrás, perfiles por usuaria y un proceso de compilación referencialmente -transparente. Sin este trabajo, Guix no existiría. - -Las distribuciones de software basadas en Nix, Nixpkgs y NixOS, también han -sido una inspiración para Guix. - -GNU@tie{}Guix en sí es un trabajo colectivo con contribuciones de un número -de gente. Mire el fichero @file{AUTHORS} en Guix para más información sobre -esa gente maja. El fichero @file{THANKS} enumera personas que han ayudado -informando de errores, haciendose cargo de la infraestructura, -proporcionando arte y temas, haciendo sugerencias, y más---¡gracias! - - -@c ********************************************************************* -@node Licencia de documentación libre GNU -@appendix Licencia de documentación libre GNU -@cindex licencia, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Índice de conceptos -@unnumbered Índice de conceptos -@printindex cp - -@node Índice programático -@unnumbered Índice programático -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: diff --git a/doc/guix.fr.texi b/doc/guix.fr.texi deleted file mode 100644 index d961625d72..0000000000 --- a/doc/guix.fr.texi +++ /dev/null @@ -1,26504 +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.fr.info -@documentencoding UTF-8 -@documentlanguage fr -@frenchspacing on -@settitle Manuel de référence de GNU Guix -@c %**end of header - -@include version-fr.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.fr.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, -2019 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, 2019 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@* - -Vous avez la permission de copier, distribuer ou modifier ce document sous -les termes de la Licence GNU Free Documentation, version 1.3 ou toute -version ultérieure publiée par la Free Software Foundation ; sans section -invariante, texte de couverture et sans texte de quatrième de couverture. -Une copie de la licence est incluse dans la section intitulée « GNU Free -Documentation License ». -@end copying - -@dircategory Administration système -@direntry -* Guix: (guix.fr). Gérer les logiciels installés et la - configuration du système. -* guix package : (guix.fr)Invoquer guix package. Installer, supprimer et - mettre à jour des - paquets. -* guix gc : (guix.fr)Invoquer guix gc. Récupérer de l'espace disque - inutilisé. -* guix pull : (guix.fr)Invoquer guix pull. Mettre à jour la liste des - paquets disponibles. -* guix system : (guix.fr)Invoquer guix system. Gérer la configuration du - système d'exploitation. -@end direntry - -@dircategory Développement logiciel -@direntry -* guix environment : (guix.fr)Invoquer guix environment. Construire des - environnements - de construction - avec Guix. -* guix build : (guix.fr)Invoquer guix build. Construire des paquets. -* guix pack : (guix.fr) Invoquer guix pack. Créer des lots binaires. -@end direntry - -@titlepage -@title Manuel de référence de GNU Guix -@subtitle Utiliser le gestionnaire de paquet fonctionnel GNU Guix -@author Les développeurs de GNU Guix - -@page -@vskip 0pt plus 1filll -Édition @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -Cette documentation décrit GNU Guix version @value{VERSION}, un outil de -gestion de paquets fonctionnel écrit pour le système GNU@. - -@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. -Ce manuel est aussi disponible en anglais (@pxref{Top,,, guix, GNU Guix -Reference Manual}) et en allemand (@pxref{Top,,, guix.de, Referenzhandbuch -zu GNU Guix}). Si vous souhaitez nous aider à traduire ce manuel en -français, vous pouvez nous rejoindre sur le -@uref{https://translationproject.org/domain/guix-manual.html, projet de -traduction} et sur la liste de diffusion -@uref{https://listes.traduc.org/mailman/listinfo/traduc/, -traduc@@traduc.org}. - -@menu -* Introduction:: Qu'est-ce que Guix ? -* Installation:: Installer Guix. -* Installation du système:: Installer le système d'exploitation complet. -* Gestion de paquets:: Installation des paquets, mises à jour, etc. -* Développement:: Développement logiciel simplifié par Guix. -* Interface de programmation:: Utiliser Guix en Scheme. -* Utilitaires:: Commandes de gestion de paquets. -* Configuration système:: Configurer le système d'exploitation. -* Documentation:: Visualiser les manuels d'utilisateur des - logiciels. -* Installer les fichiers de débogage:: Nourrir le débogueur. -* Mises à jour de sécurité:: Déployer des correctifs de sécurité - rapidement. -* Bootstrapping:: GNU/Linux depuis zéro. -* Porter:: Cibler une autre plateforme ou un autre noyau. -* Contribuer:: Nous avons besoin de votre aide ! - -* Remerciements:: Merci ! -* La licence GNU Free Documentation:: La licence de ce manuel. -* Index des concepts:: Les concepts. -* Index de programmation:: Types de données, fonctions et variables. - -@detailmenu - --- Liste détaillée des nœuds --- - - - -Introduction - - - -* Gérer ses logiciels avec Guix:: Ce qui est spécial. -* Distribution GNU:: Les paquets et les outils. - -Installation - - - -* Installation binaire:: Commencer à utiliser Guix en un rien de temps - ! -* Prérequis:: Logiciels requis pour construire et lancer - Guix. -* Lancer la suite de tests:: Tester Guix. -* Paramétrer le démon:: Préparer l'environnement du démon de - construction. -* Invoquer guix-daemon:: Lancer le démon de construction. -* Réglages applicatifs:: Réglages spécifiques pour les application. - -Paramétrer le démon - - - -* Réglages de l'environnement de construction:: Préparer l'environnement - de construction isolé. -* Réglages du délestage du démon:: Envoyer des constructions à des - machines distantes. -* Support de SELinux:: Utiliser une politique SELinux pour le démon. - -Installation du système - - - -* Limitations:: Ce à quoi vous attendre. -* Considérations matérielles:: Matériel supporté. -* Installation depuis une clef USB ou un DVD:: Préparer le média - d'installation. -* Préparer l'installation:: Réseau, partitionnement, etc. -* Installation graphique guidée:: Installation graphique facile. -* Installation manuelle:: Installation manuelle pour les sorciers. -* Après l'installation du système:: Une fois que l'installation a - réussi. -* Installer Guix dans une VM:: Jouer avec le système Guix. -* Construire l'image d'installation:: D'où vient tout cela. - -Installation manuelle - - - -* Disposition du clavier réseau et partitionnement:: Paramètres initiaux. -* Effectuer l'installation:: Installer. - -Gestion de paquets - - - -* Fonctionnalités:: Comment Guix va rendre votre vie plus heureuse. -* Invoquer guix package:: Installation, suppression, etc.@: de paquets. -* Substituts:: Télécharger des binaire déjà construits. -* Des paquets avec plusieurs résultats:: Un seul paquet source, plusieurs - résultats. -* Invoquer guix gc:: Lancer le ramasse-miettes. -* Invoquer guix pull:: Récupérer la dernière version de Guix et de - la distribution. -* Canaux:: Personnaliser la collection des paquets. -* Inférieurs:: Interagir avec une autre révision de Guix. -* Invoquer guix describe:: Affiche des informations sur la révision Guix - actuelle. -* Invoquer guix archive:: Exporter et importer des fichiers du dépôt. - -Substituts - - - -* Serveur de substituts officiel:: Une source particulière de substituts. -* Autoriser un serveur de substituts:: Comment activer ou désactiver les - substituts. -* Authentification des substituts:: Comment Guix vérifie les substituts. -* Paramètres de serveur mandataire:: Comment récupérer des substituts à - travers un serveur mandataire. -* Échec de substitution:: Qu'arrive-t-il quand la substitution échoue. -* De la confiance en des binaires:: Comment pouvez-vous avoir confiance en - un paquet binaire ? - -Développement - - - -* Invoquer guix environment:: Mettre en place des environnements de - développement. -* Invoquer guix pack:: Créer des lots de logiciels. - -Interface de programmation - - - -* Modules de paquets:: Les paquets du point de vu du programmeur. -* Définition des paquets:: Définir de nouveaux paquets. -* Systèmes de construction:: Spécifier comment construire les paquets. -* Le dépôt:: Manipuler le dépôt de paquets. -* Dérivations:: Interface de bas-niveau avec les dérivations - de paquets. -* La monade du dépôt:: Interface purement fonctionnelle avec le - dépôt. -* G-Expressions:: Manipuler les expressions de construction. -* Invoquer guix repl:: S'amuser avec Guix de manière interactive. - -Définition des paquets - - - -* Référence des paquets:: Le type de donnée des paquets. -* Référence des origines:: Le type de données d'origine. - -Utilitaires - - - -* Invoquer guix build:: Construire des paquets depuis la ligne de - commande. -* Invoquer guix edit:: Modifier les définitions de paquets. -* Invoquer guix download:: Télécharger un fichier et afficher son hash. -* Invoquer guix hash:: Calculer le hash cryptographique d'un fichier. -* Invoquer guix import:: Importer des définitions de paquets. -* Invoquer guix refresh:: Mettre à jour les définitions de paquets. -* Invoquer guix lint:: Trouver des erreurs dans les définitions de - paquets. -* Invoquer guix size:: Profiler l'utilisation du disque. -* Invoquer guix graph:: Visualiser le graphe des paquets. -* Invoquer guix publish:: Partager des substituts. -* Invoquer guix challenge:: Défier les serveurs de substituts. -* Invoquer guix copy:: Copier vers et depuis un dépôt distant. -* Invoquer guix container:: Isolation de processus. -* Invoquer guix weather:: Mesurer la disponibilité des substituts. -* Invoquer guix processes:: Lister les processus clients. - -Invoquer @command{guix build} - - - -* Options de construction communes:: Options de construction pour la - plupart des commandes. -* Options de transformation de paquets:: Créer des variantes de paquets. -* Options de construction supplémentaires:: Options spécifiques à « - guix build ». -* Débogage des échecs de construction:: La vie d'un empaqueteur. - -Configuration système - - - -* Utiliser le système de configuration:: Personnaliser votre système - GNU@. -* Référence de système d'exploitation:: Détail sur la déclaration de - système d'exploitation. -* Systèmes de fichiers:: Configurer les montages de systèmes de - fichiers. -* Périphériques mappés:: Gestion des périphériques de bloc. -* Comptes utilisateurs:: Spécifier des comptes utilisateurs. -* Disposition du clavier:: La manière dont le système interprète les - touches du clavier. -* Régionalisation:: Paramétrer la langue et les conventions - culturelles. -* Services:: Spécifier les services du système. -* Programmes setuid:: Programmes tournant avec les privilèges root. -* Certificats X.509:: Authentifier les serveurs HTTPS@. -* Name Service Switch:: Configurer le « name service switch » de la - libc. -* Disque de RAM initial:: Démarrage de Linux-Libre. -* Configuration du chargeur d'amorçage:: Configurer le chargeur - d'amorçage. -* Invoquer guix system:: Instantier une configuration du système. -* Lancer Guix dans une VM:: Comment lancer Guix dans une machine virtuelle. -* Définir des services:: Ajouter de nouvelles définitions de services. - -Services - - - -* Services de base:: Services systèmes essentiels. -* Exécution de tâches planifiées:: Le service mcron. -* Rotation des journaux:: Le service rottlog. -* Services réseau:: Paramètres réseau, démon SSH, etc. -* Système de fenêtrage X:: Affichage graphique. -* Services d'impression:: Support pour les imprimantes locales et - distantes. -* Services de bureaux:: D-Bus et les services de bureaux. -* Services de son:: Services ALSA et Pulseaudio. -* Services de bases de données:: Bases SQL, clefs-valeurs, etc. -* Services de courriels:: IMAP, POP3, SMTP, et tout ça. -* Services de messagerie:: Services de messagerie. -* Services de téléphonie:: Services de téléphonie. -* Services de surveillance:: Services de surveillance. -* Services Kerberos:: Services Kerberos. -* Services web:: Services web. -* Services de certificats:: Certificats TLS via Let's Encrypt. -* Services DNS:: Démons DNS@. -* Services VPN:: Démons VPN. -* Système de fichiers en réseau:: Services liés à NFS@. -* Intégration continue:: Le service Cuirass. -* Services de gestion de l'énergie:: Augmenter la durée de vie de la - batterie. -* Services audio:: MPD@. -* Services de virtualisation:: Services de virtualisation. -* Services de contrôle de version:: Fournit des accès distants à des - dépôts Git. -* Services de jeu:: Serveurs de jeu. -* Services divers:: D'autres services. - -Définir des services - - - -* Composition de services:: Le modèle de composition des services. -* Types service et services:: Types et services. -* Référence de service:: Référence de l'API@. -* Services Shepherd:: Un type de service particulier. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Introduction -@chapter Introduction - -@cindex but -GNU Guix@footnote{« Guix » se prononce comme « geeks » (en prononçant le -« s »), ou « ɡiːks » dans l'alphabet phonétique international (API).} est un -outil de gestion de paquets et une distribution pour le système GNU@. Guix -facilite pour les utilisateurs non privilégiés l'installation, la mise à -jour et la suppression de paquets, la restauration à un ensemble de paquets -précédent, la construction de paquets depuis les sources et plus -généralement aide à la création et à la maintenance d'environnements -logiciels. - -@cindex Système Guix -@cindex GuixSD, maintenant le système Guix -@cindex Distribution Système Guix, maintenant le système Guix -Vous pouvez installer GNU@tie{}Guix sur un système GNU/Linux existant pour -compléter les outils disponibles sans interférence (@pxref{Installation}) ou -vous pouvez l'utiliser comme distribution système indépendante, @dfn{Guix -System}@footnote{Nous appelions le système Guix « la distribution système -Guix » ou « GuixSD ». nous considérons maintenant qu'il est plus pertinent -de regrouper tout sous la bannière de « Guix » comme, après tout, Guix -System est directement disponible sous la commande @command{guix system}, -meme si vous utilisez une autre distro en dessous !}. @xref{Distribution GNU}. - -@menu -* Gérer ses logiciels avec Guix:: Ce qui est spécial. -* Distribution GNU:: Les paquets et les outils. -@end menu - -@node Gérer ses logiciels avec Guix -@section Gérer ses logiciels avec Guix - -@cindex interfaces utilisateurs -Guix fournit une interface de gestion des paquets par la ligne de commande -(@pxref{Gestion de paquets}), des outils pour aider au développement -logiciel (@pxref{Développement}), des utilitaires en ligne de commande pour -des utilisations plus avancées (@pxref{Utilitaires}) ainsi que des interfaces -de programmation Scheme (@pxref{Interface de programmation}). -@cindex démon de construction -Son @dfn{démon de construction} est responsable de la construction des -paquets pour les utilisateurs (@pxref{Paramétrer le démon}) et du -téléchargement des binaires pré-construits depuis les sources autorisées -(@pxref{Substituts}). - -@cindex extensibilité de la distribution -@cindex personnalisation, des paquets -Guix contient de nombreuses définitions de paquet GNU et non-GNU qui -respectent tous les @uref{https://www.gnu.org/philosophy/free-sw.fr.html, -libertés de l'utilisateur}. Il est @emph{extensible} : les utilisateurs -peuvent écrire leurs propres définitions de paquets (@pxref{Définition des paquets}) et les rendre disponibles dans des modules de paquets -indépendants (@pxref{Modules de paquets}). Il est aussi -@emph{personnalisable} : les utilisateurs peuvent @emph{dériver} des -définitions de paquets spécialisées à partir de définitions existantes, même -depuis la ligne de commande (@pxref{Options de transformation de paquets}). - -@cindex gestion de paquet fonctionnelle -@cindex isolation -Sous le capot, Guix implémente la discipline de @dfn{gestion de paquet -fonctionnel} inventé par Nix (@pxref{Remerciements}). Dans Guix le -processus de construction et d'installation des paquets est vu comme une -@emph{fonction} dans le sens mathématique du terme. Cette fonction a des -entrées (comme des scripts de construction, un compilateur et des -bibliothèques) et renvoie un paquet installé. En tant que fonction pure, -son résultat ne dépend que de ses entrées. Par exemple, il ne peut pas -faire référence à des logiciels ou des scripts qui n'ont pas été -explicitement passés en entrée. Une fonction de construction produit -toujours le même résultat quand on lui donne le même ensemble d'entrée. -Elle ne peut pas modifier l'environnement du système en cours d'exécution -d'aucune manière ; par exemple elle ne peut pas créer, modifier ou supprimer -des fichiers en dehors de ses répertoires de construction et -d'installation. Ce résultat s'obtient en lançant les processus de -construction dans des environnements isolés (ou des @dfn{conteneurs}) où -seules les entrées explicites sont visibles. - -@cindex dépôt -Le résultat des fonctions de construction de paquets est mis en @dfn{cache} -dans le système de fichier, dans répertoire spécial appelé le @dfn{dépôt} -(@pxref{Le dépôt}). Chaque paquet est installé dans son répertoire propre -dans le dépôt — par défaut dans @file{/gnu/store}. Le nom du répertoire -contient un hash de toutes les entrées utilisées pour construire le paquet ; -ainsi, changer une entrée donnera un nom de répertoire différent. - -Cette approche est le fondement des fonctionnalités les plus importante de -Guix : le support des mises à jour des paquets et des retours en arrière -transactionnels, l'installation différenciée par utilisateur et le ramassage -de miettes pour les paquets (@pxref{Fonctionnalités}). - - -@node Distribution GNU -@section Distribution GNU - -@cindex Système Guix -Guix fournit aussi une distribution du système GNU contenant uniquement des -logiciels libres@footnote{Le terme « libre » se réfère ici bien sûr à -@url{http://www.gnu.org/philosophy/free-sw.fr.html,la liberté offerte à -l'utilisateur de ces logiciels}.}. On peut installer la distribution -elle-même (@pxref{Installation du système}), mais on peut aussi installer Guix -comme gestionnaire de paquets par dessus un système GNU/Linux déjà installé -(@pxref{Installation}). Pour distinguer ces deux cas, on appelle la -distribution autonome le « système Guix » ou Guix@tie{}System. - -La distribution fournit les paquets cœur de GNU comme la GNU libc, GCC et -Binutils, ainsi que de nombreuses applications GNU et non-GNU. La liste -complète des paquets disponibles se trouve -@url{http://www.gnu.org/software/guix/packages,en ligne} ou en lançant -@command{guix package} (@pxref{Invoquer guix package}) : - -@example -guix package --list-available -@end example - -Notre but est de fournir une distribution logicielle entièrement libre de -GNU/Linux et d'autres variantes de GNU, en se concentrant sur la promotion -et l'intégration étroite des composants GNU en insistant sur les programmes -et les outils qui aident l'utilisateur à exercer ses libertés. - -Les paquets sont actuellement disponibles pour les plateformes suivantes : - -@table @code - -@item x86_64-linux -l'architecture Intel et AMD @code{x86_64} avec le noyau Linux-libre ; - -@item i686-linux -l'architecture Intel 32-bits (IA32) avec le noyau Linux-libre ; - -@item armhf-linux -l'architecture ARMv7-A avec gestion des flottants matérielle, Thumb-2 et -NEON, avec l'interface binaire applicative (ABI) EABI hard-float et le noyau -Linux-libre ; - -@item aarch64-linux -les processeurs ARMv8-A 64-bits en little-endian avec le noyau Linux-libre. -Le support est actuellement expérimental et limité. @xref{Contribuer}, -pour savoir comment aider ! - -@item mips64el-linux -les processeurs MIPS 64-bits little-endian, spécifiquement la série -Loongson, ABI n32, avec le noyau Linux-libre. - -@end table - -Avec Guix@tie{}System, vous @emph{déclarez} tous les aspects de la -configuration du système d'exploitation et guix s'occupe d'instancier la -configuration de manière transactionnelle, reproductible et sans état -(@pxref{Configuration système}). Guix System utilise le noyau Linux-libre, -le système d'initialisation Shepherd (@pxref{Introduction,,, shepherd, The -GNU Shepherd Manual}), les outils GNU et la chaîne d'outils familière ainsi -que l'environnement graphique et les services systèmes de votre choix. - -Guix System est disponible sur toutes les plateformes ci-dessus à part -@code{mips64el-linux}. - -@noindent -Pour des informations sur comment porter vers d'autres architectures et -d'autres noyau, @pxref{Porter}. - -La construction de cette distribution est un effort collaboratif et nous -vous invitons à nous rejoindre ! @xref{Contribuer}, pour des informations -sur la manière de nous aider. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex installer Guix - -@quotation Remarque -Nous vous recommandons d'utiliser ce -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -script shell d'installation} pour installer Guix sur un système GNU/Linux -fonctionnel, que nous appelons une @dfn{distro externe}@footnote{Cette -section s'occupe de l'installation du gestionnaire de paquet, ce qui peut se -faire sur un système GNU/Linux existant. Si vous voulez plutôt installer le -système d'exploitation GNU complet, @pxref{Installation du système}.}. Le -script automatise le téléchargement, l'installation et la configuration -initiale de Guix. Vous devez l'exécuter en tant qu'utilisateur root. -@end quotation - -@cindex distro externe -@cindex répertoires liés aux distro externes -Lorsqu'il est installé sur une distro externe, GNU@tie{}Guix complète les -outils disponibles sans interférence. Ses données se trouvent exclusivement -dans deux répertoires, typiquement @file{/gnu/store} et @file{/var/guix} ; -les autres fichiers de votre système comme @file{/etc} sont laissés intacts. - -Une fois installé, Guix peut être mis à jour en lançant @command{guix pull} -(@pxref{Invoquer guix pull}). - -Si vous préférez effectuer les étapes d'installation manuellement ou si vous -voulez les personnaliser, vous trouverez les sections suivantes utile. -Elles décrivent les prérequis logiciels pour Guix, ainsi que la manière de -l'installer manuellement et de se préparer à l'utiliser. - -@menu -* Installation binaire:: Commencer à utiliser Guix en un rien de temps - ! -* Prérequis:: Logiciels requis pour construire et lancer - Guix. -* Lancer la suite de tests:: Tester Guix. -* Paramétrer le démon:: Préparer l'environnement du démon de - construction. -* Invoquer guix-daemon:: Lancer le démon de construction. -* Réglages applicatifs:: Réglages spécifiques pour les application. -@end menu - -@node Installation binaire -@section Installation binaire - -@cindex installer Guix depuis les binaires -@cindex script d'installation -Cette section décrit comment installer Guix sur un système quelconque depuis -un archive autonome qui fournit les binaires pour Guix et toutes ses -dépendances. C'est souvent plus rapide que d'installer depuis les sources, -ce qui est décrit dans les sections suivantes. Le seul prérequis est -d'avoir GNU@tie{}tar et Xz. - -L'installation se comme ceci : - -@enumerate -@item -@cindex téléchargement du Guix binaire -Téléchargez l'archive binaire depuis -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{système}.tar.xz}, -où @var{système} est @code{x86_64-linux} pour une machine @code{x86_64} sur -laquelle tourne déjà le noyau Linux, etc. - -@c The following is somewhat duplicated in ``System Installation''. -Assurez-vous de télécharger le fichier @file{.sig} associé et de vérifier -l'authenticité de l'archive avec, comme ceci : - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{système}.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.@var{système}.tar.xz.sig -@end example - -Si cette commande échoue parce que vous n'avez pas la clef publique requise, -lancez cette commande pour l'importer : - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -et relancez la commande @code{gpg --verify}. - -@item -Maintenant, vous devez devenir l'utilisateur @code{root}. En fonction de -votre distribution, vous devrez lancer @code{su -} ou @code{sudo -i}. En -tant que @code{root}, lancez : - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{système}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -Cela crée @file{/gnu/store} (@pxref{Le dépôt}) and @file{/var/guix}. Ce -deuxième dossier contient un profil prêt à être utilisé pour @code{root} -(voir les étapes suivantes). - -Ne décompressez @emph{pas} l'archive sur un système Guix lancé car cela -écraserait ses propres fichiers essentiels. - -L'option @code{--warning=no-timestamp} s'assure que GNU@tie{}tar ne produise -pas d'avertissement disant que « l'horodatage est trop vieux pour être -plausible » (ces avertissements étaient produits par GNU@tie{}tar 1.26 et -précédents ; les versions récentes n'ont pas ce problème). Cela vient du -fait que les fichiers de l'archive ont pour date de modification zéro (ce -qui signifie le 1er janvier 1970). C'est fait exprès pour s'assurer que le -contenu de l'archive ne dépende pas de la date de création, ce qui la rend -reproductible. - -@item -Rendez le profil disponible sous @file{~root/.config/guix/current}, qui est -l'emplacement où @command{guix pull} installera les mises à jour -(@pxref{Invoquer guix pull}) : - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Sourcez @file{etc/profile} pour augmenter @code{PATH} et les autres -variables d'environnement nécessaires : - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Créez le groupe et les comptes utilisateurs pour les utilisateurs de -construction comme expliqué plus loin (@pxref{Réglages de l'environnement de construction}). - -@item -Lancez le démon et paramétrez-le pour démarrer automatiquement au démarrage. - -Si votre distribution hôte utilise le système d'initialisation systemd, cela -peut se faire avec ces commandes : - -@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 - -Si votre distribution hôte utilise le système d'initialisation Upstart : - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Sinon, vous pouvez toujours démarrer le démon manuellement avec : - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Rendez la commande @command{guix} disponible pour les autres utilisateurs -sur la machine, par exemple avec : - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -C'est aussi une bonne idée de rendre la version Info de ce manuel disponible -ici : - -@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 - -Comme cela, en supposant que @file{/usr/local/share/info} est dans le chemin -de recherche, lancer @command{info guix} ouvrira ce manuel (@pxref{Other -Info Directories,,, texinfo, GNU Texinfo}, pour plus de détails sur comment -changer le chemin de recherche de Info). - -@item -@cindex substituts, autorisations -Pour utiliser les substituts de @code{@value{SUBSTITUTE-SERVER}} ou l'un de -ses miroirs (@pxref{Substituts}), autorisez-les : - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@item -Chaque utilisateur peut avoir besoin d'effectuer des étapes supplémentaires -pour que leur environnement Guix soit prêt à être utilisé, -@pxref{Réglages applicatifs}. -@end enumerate - -Voilà, l'installation est terminée ! - -Vous pouvez confirmer que Guix fonctionne en installant un paquet d'exemple -dans le profil de root : - -@example -# guix package -i hello -@end example - -Le paquet @code{guix} doit rester disponible dans le profil de @code{root} -ou il pourrait être sujet au ramassage de miettes — dans ce cas vous vous -retrouveriez gravement handicapé par l'absence de la commande -@command{guix}. En d'autres termes, ne supprimez pas @code{guix} en lançant -@code{guix package -r guix}. - -L'archive d'installation binaire peut être (re)produite et vérifiée -simplement en lançant la commande suivante dans l'arborescence des sources -de Guix : - -@example -make guix-binary.@var{system}.tar.xz -@end example - -@noindent -…@: ce qui à son tour lance : - -@example -guix pack -s @var{system} --localstatedir \ - --profile-name=current-guix guix -@end example - -@xref{Invoquer guix pack}, pour plus d'info sur cet outil pratique. - -@node Prérequis -@section Prérequis - -Cette section dresse la liste des prérequis pour la construction de Guix -depuis les sources. La procédure de construction pour Guix est la même que -pour les autres logiciels GNU, et n'est pas expliquée ici. Regardez les -fichiers @file{README} et @file{INSTALL} dans l'arborescence des sources de -Guix pour plus de détails. - -@cindex site officiel -GNU Guix est disponible au téléchargement depuis son site web sur -@url{http://www.gnu.org/software/guix/}. - -GNU Guix dépend des paquets suivants : - -@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 ou supérieure, -@item -@uref{http://gnutls.org/, GnuTLS}, en particulier ses liaisons 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 ou supérieure, -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, d'août 2017 ou -ultérieur, -@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 - -Les dépendances suivantes sont facultatives : - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Le support pour la décharge de construction (@pxref{Réglages du délestage du démon}) -et @command{guix copy} (@pxref{Invoquer guix copy}) dépend de -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, version -0.10.2 ou ultérieure. - -@item -Lorsque @url{http://www.bzip.org, libbz2} est disponible, -@command{guix-daemon} peut l'utiliser pour compresser les journaux de -construction. -@end itemize - -À moins que @code{--disable-daemon} ne soit passé à @command{configure}, les -paquets suivants sont aussi requis : - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}, -@item @url{http://sqlite.org, SQLite 3}, -@item @url{http://gcc.gnu.org, GCC's g++}, avec le support pour le -standard C++11. -@end itemize - -@cindex répertoire d'état -Lorsque vous configurez Guix sur un système qui a déjà une installation de -Guix, assurez-vous de spécifier le même répertoire d'état que l'installation -existante avec l'option @code{--localstatedir} du script @command{configure} -(@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding -Standards}). Le script @command{configure} vous protège des mauvaises -configurations involontaires de @var{localstatedir} pour éviter que vous ne -corrompiez votre dépôt (@pxref{Le dépôt}). - -@cindex Nix, compatibilité -Lorsque vous avez une installation fonctionnelle du -@url{http://nixos.org/nix/, gestionnaire de paquets Nix}, vous pouvez -configurer Guix avec @code{--disable-daemon}. Dan ce cas, Nix remplace les -trois dépendances au dessus. - -Guix est compatible avec Nix, donc il est possible de partager le même dépôt -entre les deux. Pour cela, vous devez passer à @command{configure} non -seulement la même valeur de @code{--with-store-dir} mais aussi la même -valeur de @code{--localstatedir}. Cette dernière est nécessaires car elle -spécifie l'emplacement de la base de données qui stocke les métadonnées sur -le dépôt, entre autres choses. Les valeurs par défaut pour Nix sont -@code{--with-store-dir=/nix/store} et @code{--localstatedir=/nix/var}. -Remarquez que @code{--disable-daemon} n'est pas requis si votre but est de -partager le dépôt avec Nix. - -@node Lancer la suite de tests -@section Lancer la suite de tests - -@cindex suite de tests -Après avoir lancé @command{configure} et @code{make} correctement, c'est une -bonne idée de lancer la suite de tests. Elle peut aider à trouver des -erreurs avec la configuration ou l'environnement, ou des bogues dans Guix -lui-même — et vraiment, rapporter des échecs de tests est une bonne manière -d'aider à améliorer le logiciel. Pour lancer la suite de tests, tapez : - -@example -make check -@end example - -Les cas de tests peuvent être lancés en parallèle : vous pouvez utiliser -l'option @code{-j} de GNU@tie{}make pour accélérer les choses. Le premier -lancement peut prendre plusieurs minutes sur une machine récente ; les -lancements suivants seront plus rapides car le dépôt créé pour les tests -aura déjà plusieurs choses en cache. - -Il est aussi possible de lancer un sous-ensemble des tests en définissant la -variable makefile @code{TESTS} comme dans cet exemple : - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -Par défaut, les résultats des tests sont affichés au niveau du fichier. -Pour voir les détails de chaque cas de test individuel, il est possible de -définir la variable makefile @code{SCM_LOG_DRIVER_FLAGS} comme dans cet -exemple : - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -Après un échec, envoyez un courriel à @email{bug-guix@@gnu.org} et attachez -le fichier @file{test-suite.log}. Précisez la version de Guix utilisée -ainsi que les numéros de version de ses dépendances (@pxref{Prérequis}) -dans votre message. - -Guix possède aussi une suite de tests de systèmes complets qui test des -instances complètes du système Guix. Elle ne peut être lancée qui sur un -système où Guix est déjà installé, avec : - -@example -make check-system -@end example - -@noindent -ou, de nouveau, en définissant @code{TESTS} pour choisir un sous-ensemble -des tests à lancer : - -@example -make check-system TESTS="basic mcron" -@end example - -Ces tests systèmes sont définis dans les modules @code{(gnu tests -@dots{})}. Ils fonctionnent en lançant les systèmes d'exploitation sous test -avec une instrumentation légère dans une machine virtuelle (VM). Ils -peuvent être intenses en terme de calculs ou plutôt rapides en fonction de -la disponibilité des substituts de leurs dépendances (@pxref{Substituts}). -Certains requièrent beaucoup d'espace disque pour contenir les images des -VM@. - -De nouveau, en cas d'échec, envoyez tous les détails à -@email{bug-guix@@gnu.org}. - -@node Paramétrer le démon -@section Paramétrer le démon - -@cindex démon -Les opérations comme la construction d'un paquet ou le lancement du -ramasse-miettes sont toutes effectuées par un processus spécialisé, le -@dfn{démon de construction}, pour le compte des clients. Seul le démon peut -accéder au dépôt et à sa base de données associée. Ainsi, toute opération -manipulant le dépôt passe par le démon. Par exemple, les outils en ligne de -commande comme @command{guix package} et @command{guix build} communiquent -avec le démon (@i{via} des appels de procédures distantes) pour lui dire -quoi faire. - -Les sections suivantes expliquent comment préparer l'environnement du démon -de construction. Voir aussi @ref{Substituts} pour apprendre comment -permettre le téléchargement de binaires pré-construits. - -@menu -* Réglages de l'environnement de construction:: Préparer l'environnement - de construction isolé. -* Réglages du délestage du démon:: Envoyer des constructions à des - machines distantes. -* Support de SELinux:: Utiliser une politique SELinux pour le démon. -@end menu - -@node Réglages de l'environnement de construction -@subsection Réglages de l'environnement de construction - -@cindex environnement de construction -Dans une installation standard multi-utilisateurs, Guix et son démon — le -programme @command{guix-daemon} — sont installé par l'administrateur système -; @file{/gnu/store} appartient à @code{root} et @command{guix-daemon} est -lancé en @code{root}. Les utilisateurs non-privilégiés peuvent utiliser les -outils Guix pour construire des paquets ou accéder au dépôt et le démon le -fera pour leur compte en s'assurant que le dépôt garde un état cohérent et -permet le partage des paquets déjà construits entre les utilisateurs. - -@cindex utilisateurs de construction -Alors que @command{guix-daemon} tourne en @code{root}, vous n'avez pas -forcément envie que les processus de construction de paquets tournent aussi -en @code{root}, pour des raisons de sécurité évidentes. Pour éviter cela, -vous devriez créer une réserve spéciale d'@dfn{utilisateurs de construction} -que les processus de construction démarrés par le démon utiliseront. Ces -utilisateurs de construction n'ont pas besoin d'un shell ou d'un répertoire -personnel ; ils seront seulement utilisés quand le démon délaissera ses -privilèges @code{root} dans les processus de construction. En ayant -plusieurs de ces utilisateurs, vous permettez au démon de lancer des -processus de construction distincts sous des UID différent, ce qui garanti -qu'aucune interférence n'ait lieu entre les uns et les autres — une -fonctionnalité essentielle puisque les constructions sont supposées être des -fonctions pures (@pxref{Introduction}). - -Sur un système GNU/Linux, on peut créer une réserve d'utilisateurs de -construction comme ceci (avec la syntaxe Bash et les commandes -@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 "Utilisateur de construction Guix $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -Le nombre d'utilisateurs de construction détermine le nombre de tâches de -constructions qui peuvent tourner en parallèle, tel que spécifié par -l'option @option{--max-jobs} (@pxref{Invoquer guix-daemon, -@option{--max-jobs}}). Pour utiliser @command{guix system vm} et les -commandes liées, vous devrez ajouter les utilisateurs de construction au -groupe @code{kvm} pour qu'ils puissent accéder à @file{/dev/kvm} avec -@code{-G guixbuild,kvm} plutôt que @code{-G guixbuild} (@pxref{Invoquer guix system}). - -Le programme @code{guix-daemon} peut ensuite être lancé en @code{root} avec -la commande suivante@footnote{Si votre machine utilise le système -d'initialisation systemd, copiez le fichier -@file{@var{prefix}/lib/systemd/system/guix-daemon.service} dans -@file{/etc/systemd/system} pour vous assurer que @command{guix-daemon} est -démarré automatiquement. De même, si votre machine utilise le système -d'initialisation Upstart, copiez le fichier -@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} dans -@file{/etc/init}.} : - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -De cette façon, le démon démarre les processus de construction dans un -chroot, sous un des utilisateurs @code{guixbuilder}. Sur GNU/Linux par -défaut, l'environnement chroot ne contient rien d'autre que : - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -un répertoire @code{/dev} minimal, créé presque indépendamment du -@code{/dev} de l'hôte@footnote{« presque », parce que même si l'ensemble des -fichiers qui apparaissent dans le @code{/dev} du chroot sont déterminés à -l'avance, la plupart de ces fichiers ne peut pas être créée si l'hôte ne les -a pas.} ; - -@item -le répertoire @code{/proc} ; il ne montre que les processus du conteneur car -on utilise une espace de nom séparé pour les PID ; - -@item -@file{/etc/passwd} avec une entrée pour l'utilisateur actuel et une entrée -pour l'utilisateur @file{nobody} ; - -@item -@file{/etc/group} avec une entrée pour le groupe de l'utilisateur ; - -@item -@file{/etc/hosts} avec une entrée qui fait correspondre @code{localhost} à -@code{127.0.0.1} ; - -@item -un répertoire @file{/tmp} inscriptible. -@end itemize - -Vous pouvez influencer le répertoire où le démon stocke les arbres de -construction @i{via} la variable d'environnement @code{TMPDIR}. Cependant, -l'arbre de construction dans le chroot sera toujours appelé -@file{/tmp/guix-build-@var{nom}.drv-0}, où @var{nom} est le nom de la -dérivation — p.@: ex.@: @code{coreutils-8.24}. De cette façon, la valeur de -@code{TMPDIR} ne fuite pas à l'intérieur des environnements de construction, -ce qui évite des différences lorsque le processus de construction retient le -nom de leur répertoire de construction. - -@vindex http_proxy -Le démon tient aussi compte de la variable d'environnement @code{http_proxy} -pour ses téléchargements HTTP, que ce soit pour les dérivations à sortie -fixes (@pxref{Dérivations}) ou pour les substituts (@pxref{Substituts}). - -Si vous installez Guix en tant qu'utilisateur non-privilégié, il est -toujours possible de lancer @command{guix-daemon} si vous passez -@code{--disable-chroot}. Cependant, les processus de construction ne seront -pas isolés les uns des autres ni du reste du système. Ainsi les processus -de construction peuvent interférer les uns avec les autres, et peuvent -accéder à des programmes, des bibliothèques et d'autres fichiers présents -sur le système — ce qui rend plus difficile de les voir comme des fonctions -@emph{pures}. - - -@node Réglages du délestage du démon -@subsection Utiliser le dispositif de déchargement - -@cindex déchargement -@cindex crochet de construction -Si vous le souhaitez, le démon de construction peut @dfn{décharger} des -constructions de dérivations sur d'autres machines Guix avec le @dfn{crochet -de construction} @code{offload}@footnote{Cette fonctionnalité n'est -disponible que si @uref{https://github.com/artyom-poptsov/guile-ssh, -Guile-SSH} est présent.}. Lorsque cette fonctionnalité est activée, Guix -lit une liste de machines de constructions spécifiée par l'utilisateur dans -@file{/etc/guix/machines.scm} ; à chaque fois qu'une construction est -demandée, par exemple par @code{guix build}, le démon essaie de la décharger -sur une des machines qui satisfont les contraintes de la dérivation, en -particulier le type de système, p.@: ex.@: @file{x86_64-linux}. Les -prérequis manquants pour la construction sont copiés par SSH sur la machine -de construction qui procède ensuite à la construction ; si elle réussi, les -sorties de la construction sont copiés vers la machine de départ. - -Le fichier @file{/etc/guix/machines.scm} ressemble typiquement à cela : - -@example -(list (build-machine - (name "eightysix.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "bob") - (speed 2.)) ;très rapide ! - - (build-machine - (name "meeps.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alice") - (private-key - (string-append (getenv "HOME") - "/.ssh/identity-for-guix")))) -@end example - -@noindent -Dans l'exemple ci-dessus nous spécifions une liste de deux machines de -construction, une pour l'architecture @code{x86_64} et une pour -l'architecture @code{mips64el}. - -En fait, ce fichier est — et ça ne devrait pas vous surprendre ! — un -fichier Scheme qui est évalué au démarrage du crochet @code{offload}. Sa -valeur de retour doit être une liste d'objets @code{build-machine}. Même si -cet exemple montre une liste fixée de machines de construction, on pourrait -imaginer par exemple utiliser DNS-SD pour renvoyer une liste de machines de -constructions potentielles découvertes sur le réseau local -(@pxref{Introduction, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme -Programs}). Le type de données @code{build-machine} est détaillé plus bas. - -@deftp {Type de données} build-machine -Ce type de données représente les machines de construction sur lesquelles le -démon peut décharger des constructions. Les champs importants sont : - -@table @code - -@item name -Le nom d'hôte de la machine distante. - -@item system -Le type de système de la machine distante, p.@: ex.@: @code{"x86_64-linux"}. - -@item user -Le compte utilisateur à utiliser lors de la connexion à la machine distante -par SSH@. Remarquez que la paire de clef SSH ne doit @emph{pas} être -protégée par mot de passe pour permettre des connexions non-interactives. - -@item host-key -Cela doit être la @dfn{clef d'hôte SSH publique} de la machine au format -OpenSSH@. Elle est utilisée pour authentifier la machine lors de la -connexion. C'est une longue chaîne qui ressemble à cela : - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org -@end example - -Si la machine utilise le démon OpenSSH, @command{sshd}, la clef d'hôte se -trouve dans un fichier comme @file{/etc/ssh/ssh_host_ed25519_key.pub}. - -Si la machine utilise le démon SSH de GNU@tie{}lsh, la clef d'hôte est dans -@file{/etc/lsh/host-key.pub} ou un fichier similaire. Elle peut être -convertie au format OpenSSH avec @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 - -Il y a un certain nombre de champs facultatifs que vous pouvez remplir : - -@table @asis - -@item @code{port} (par défaut : @code{22}) -Numéro de port du serveur SSH sur la machine. - -@item @code{private-key} (par défaut : @file{~root/.ssh/id_rsa}) -Le fichier de clef privée SSH à utiliser lors de la connexion à la machine, -au format OpenSSH@. Cette clef ne doit pas être protégée par phrase de -passe. - -Remarquez que la valeur par défaut est la clef privée @emph{du compte -root}. Assurez-vous qu'elle existe si vous utilisez la valeur par défaut. - -@item @code{compression} (par défaut : @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (par défaut : @code{3}) -Les méthodes de compression au niveau SSH et le niveau de compression -demandé. - -Remarquez que le déchargement utilise la compression SSH pour réduire la -bande passante utilisée lors du transfert vers et depuis les machines de -construction. - -@item @code{daemon-socket} (par défaut : @code{"/var/guix/daemon-socket/socket"}) -Le nom de fichier du socket Unix-domain sur lequel @command{guix-daemon} -écoute sur cette machine. - -@item @code{parallel-builds} (par défaut : @code{1}) -Le nombre de constructions qui peuvent tourner simultanément sur la machine. - -@item @code{speed} (par défaut : @code{1.0}) -Un « facteur de vitesse relatif ». L'ordonnanceur des constructions tendra -à préférer les machines avec un plus grand facteur de vitesse. - -@item @code{features} (par défaut : @code{'()}) -Une liste de chaînes qui contient les fonctionnalités spécifiques supportées -par la machine. Un exemple est @code{"kvm"} pour les machines qui ont le -module Linux KVM et le support matériel correspondant. Les dérivations -peuvent demander des fonctionnalités par leur nom et seront orchestrées sur -les machines de construction correspondantes. - -@end table -@end deftp - -La commande @code{guix} doit être dans le chemin de recherche des machines -de construction. Vous pouvez vérifier si c'est le cas en lançant : - -@example -ssh build-machine guix repl --version -@end example - -Il reste une dernière chose à faire maintenant que @file{machines.scm} est -en place. Comme expliqué ci-dessus, lors du déchargement les fichiers sont -transférés entre les dépôts des machines. Pour que cela fonctionne, vous -devez d'abord générer une paire de clef sur chaque machine pour permettre au -démon d'exporter des archives signées des fichiers de son dépôt -(@pxref{Invoquer guix archive}) : - -@example -# guix archive --generate-key -@end example - -@noindent -Chaque machine de construction doit autoriser la clef de la machine -maîtresse pour qu'ils acceptent les éléments de dépôt de celle-ci : - -@example -# guix archive --authorize < master-public-key.txt -@end example - -@noindent -De même, la machine maîtresse doit autoriser les clefs de chaque machine de -construction. - -Toute cette histoire de clefs permet d'exprimer la confiance mutuelle -deux-à-deux entre le maître et les machines de construction. Concrètement, -lorsque le maître reçoit des fichiers d'une machine de construction (et -vice-versa), son démon de construction s'assure qu'ils sont authentiques, -n'ont pas été modifiés par un tiers et qu'il sont signés par un clef -autorisée. - -@cindex test du déchargement -Pour tester que votre paramétrage fonctionne, lancez cette commande sur le -nœud maître : - -@example -# guix offload test -@end example - -Cela essaiera de se connecter à toutes les machines de construction -spécifiées dans @file{/etc/guix/machines.scm}, s'assurera que Guile et les -modules Guix sont disponibles sur toutes les machines et tentera d'exporter -vers la machine et d'importer depuis elle, et rapportera toute erreur -survenu pendant le processus. - -Si vous souhaitez tester un fichier de machines différent, spécifiez-le sur -la ligne de commande : - -@example -# guix offload test machines-qualif.scm -@end example - -Enfin, vous pouvez tester un sous-ensemble de machines dont le nom -correspond à une expression rationnelle comme ceci : - -@example -# guix offload test machines.scm '\.gnu\.org$' -@end example - -@cindex statut du déchargement -Pour afficher la charge actuelle de tous les hôtes de construction, lancez -cette commande sur le nœud principal : - -@example -# guix offload status -@end example - - -@node Support de SELinux -@subsection Support de SELinux - -@cindex SELinux, politique du démon -@cindex contrôle d'accès obligatoire, SELinux -@cindex sécurité, guix-daemon -Guix inclus un fichier de politique SELinux dans @file{etc/guix-daemon.cil} -qui peut être installé sur un système où SELinux est activé pour que les -fichiers Guix soient étiquetés et pour spécifier le comportement attendu du -démon. Comme Guix System ne fournit pas de politique SELinux de base, la -politique du démon ne peut pas être utilisée sur le système Guix. - -@subsubsection Installer la politique SELinux -@cindex SELinux, installation de la politique -Pour installer la politique, lancez cette commande en root : - -@example -semodule -i etc/guix-daemon.cil -@end example - -Puis ré-étiquetez le système de fichier avec @code{restorecon} ou par un -mécanisme différent fournit par votre système. - -Une fois la politique installée, le système de fichier ré-étiqueté et le -démon redémarré, il devrait être lancé dans le contexte -@code{guix_daemon_t}. Vous pouvez le confirmer avec la commande suivante : - -@example -ps -Zax | grep guix-daemon -@end example - -Surveillez les fichiers journaux de SELinux pendant que vous lancez une -commande comme @code{guix build hello} pour vous convaincre que SELniux -permet toutes les opérations nécessaires. - -@subsubsection Limitations -@cindex SELinux, limites - -La politique n'est pas parfaite. Voici une liste de limitations et de -bizarreries qui vous devriez prendre en compte avant de déployer la -politique SELinux fournie pour le démon Guix. - -@enumerate -@item -@code{guix_daemon_socket_t} n'est pas vraiment utilisé. Aucune des -opérations sur les sockets n'impliquent de contextes qui ont quoi que ce -soit à voir avec @code{guix_daemon_socket_t}. Ça ne fait pas de mal d'avoir -une étiquette inutilisée, mais il serait préférable de définir des règles -sur les sockets uniquement pour cette étiquette. - -@item -@code{guix gc} ne peut pas accéder à n'importe quel lien vers les profils. -Par conception, l'étiquette de fichier de la destination d'un lien -symbolique est indépendant de l'étiquette du lien lui-même. Bien que tous -les profils sous $localstatedir aient une étiquette, les liens vers ces -profils héritent de l'étiquette du répertoire dans lequel ils se trouvent. -Pour les liens dans le répertoire personnel cela sera @code{user_home_t}. -Mais pour les liens du répertoire personnel de l'utilisateur root, ou -@file{/tmp}, ou du répertoire de travail du serveur HTTP, etc, cela ne -fonctionnera pas. SELinux empêcherait @code{guix gc} de lire et de suivre -ces liens. - -@item -La fonctionnalité du démon d'écouter des connexions TCP pourrait ne plus -fonctionner. Cela demande des règles supplémentaires car SELinux traite les -sockets réseau différemment des fichiers. - -@item -Actuellement tous les fichiers qui correspondent à l'expression rationnelle -@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} reçoivent l'étiquette -@code{guix_daemon_exec_t} ; cela signifie que @emph{tout} fichier avec ce -nom dans n'importe quel profil serait autorisé à se lancer dans le domaine -@code{guix_daemon_t}. Ce n'est pas idéal. Un attaquant pourrait construire -un paquet qui fournit cet exécutable et convaincre un utilisateur de -l'installer et de le lancer, ce qui l'élève dans le domaine -@code{guix_daemon_t}. À ce moment SELinux ne pourrait pas l'empêcher -d'accéder à des fichiers autorisés pour les processus de ce domaine. - -Nous pourrions générer une politique bien plus restrictive à l'installation, -pour que seuls les noms de fichiers @emph{exacts} de l'exécutable -@code{guix-daemon} actuellement installé soit étiqueté avec -@code{guix_daemon_exec_t}, plutôt que d'utiliser une expression rationnelle -plus large. L'inconvénient c'est que root devrait installer ou mettre à -jour la politique à l'installation à chaque fois que le paquet Guix qui -fournit l'exécutable @code{guix-daemon} effectivement exécuté est mis à -jour. -@end enumerate - -@node Invoquer guix-daemon -@section Invoquer @command{guix-daemon} - -Le programme @command{guix-daemon} implémente toutes les fonctionnalités -d'accès au dépôt. Cela inclus le lancement des processus de construction, -le lancement du ramasse-miettes, la demande de disponibilité des résultats -de construction, etc. Il tourne normalement en @code{root} comme ceci : - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -Pour des détails sur son paramétrage, @pxref{Paramétrer le démon}. - -@cindex chroot -@cindex conteneur, environnement de construction -@cindex environnement de construction -@cindex constructions reproductibles -Par défaut, @command{guix-daemon} lance les processus de construction sous -différents UID récupérés depuis le groupe de construction spécifié avec -@code{--build-users-group}. En plus, chaque processus de construction est -lancé dans un environnement chroot qui ne contient que le sous-ensemble du -dépôt dont le processus de construction dépend, tel que spécifié par sa -dérivation (@pxref{Interface de programmation, dérivation}), plus un -ensemble de répertoires systèmes spécifiques. Par défaut ce dernier -contient @file{/dev} et @file{/dev/pts}. De plus, sous GNU/Linux, -l'environnement de construction est un @dfn{conteneur} : en plus d'avoir sa -propre arborescence du système de fichier, elle a un espace de montage -séparé, son propre espace de PID, son espace de réseau, etc. Cela aide à -obtenir des constructions reproductibles (@pxref{Fonctionnalités}). - -Lorsque le démon effectue une construction pour le compte de l'utilisateur, -il crée un répertoire sous @file{/tmp} ou sous le répertoire spécifié par sa -variable d'environnement @code{TMPDIR}. Ce répertoire est partagé avec le -conteneur pendant la durée de la construction, bien que dans le conteneur, -l'arborescence de construction est toujours appelée -@file{/tmp/guix-build-@var{name}.drv-0}. - -Le répertoire de construction est automatiquement supprimé à la fin, à moins -que la construction n'ait échoué et que le client ait spécifié -@option{--keep-failed} (@pxref{Invoquer guix build, -@option{--keep-failed}}). - -Le démon écoute les connexions et démarre un sous-processus pour chaque -session démarrée par un client (l'une des sous-commandes de -@command{guix}). La commande @command{guix processes} vous permet d'obtenir -un aperçu de l'activité sur votre système en affichant chaque session et -client actif. @xref{Invoquer guix processes} pour plus d'informations. - -Les options en ligne de commande suivantes sont disponibles : - -@table @code -@item --build-users-group=@var{groupe} -Prendre les utilisateurs de @var{group} pour lancer les processus de -construction (@pxref{Paramétrer le démon, utilisateurs de construction}). - -@item --no-substitutes -@cindex substituts -Ne pas utiliser de substitut pour les résultats de la construction. -C'est-à-dire, toujours construire localement plutôt que de permettre le -téléchargement de binaires pré-construits (@pxref{Substituts}). - -Lorsque le démon tourne avec @code{--no-substitutes}, les clients peuvent -toujours activer explicitement la substitution @i{via} l'appel de procédure -distante @code{set-build-options} (@pxref{Le dépôt}). - -@item --substitute-urls=@var{urls} -@anchor{daemon-substitute-urls} -Considérer @var{urls} comme la liste séparée par des espaces des URL des -sources de substituts par défaut. Lorsque cette option est omise, -@indicateurl{https://@value{SUBSTITUTE-SERVER}} est utilisé. - -Cela signifie que les substituts sont téléchargés depuis les @var{urls}, -tant qu'ils sont signés par une signature de confiance (@pxref{Substituts}). - -@cindex crochet de construction -@item --no-build-hook -Ne pas utiliser le @dfn{crochet de construction}. - -Le crochet de construction est un programme d'aide qui le démon peut -démarrer et auquel soumettre les requêtes de construction. Ce mécanisme est -utilisé pour décharger les constructions à d'autres machines (@pxref{Réglages du délestage du démon}). - -@item --cache-failures -Mettre les échecs de construction en cache. Par défaut, seules les -constructions réussies sont mises en cache. - -Lorsque cette option est utilisée, @command{guix gc --list-failures} peut -être utilisé pour demander l'ensemble des éléments du dépôt marqués comme -échoués ; @command{guix gc --clear-failures} vide la liste des éléments -aillant échoué. @xref{Invoquer guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -Utiliser @var{n} cœurs CPU pour construire chaque dérivation ; @code{0} -signifie autant que possible. - -La valeur par défaut est @code{0}, mais elle peut être modifiée par les -clients comme avec l'option @code{--cores} de @command{guix build} -(@pxref{Invoquer guix build}). - -L'effet est de définir la variable d'environnement @code{NIX_BUILD_CORES} -dans le processus de construction, qui peut ensuite l'utiliser pour -exploiter le parallélisme en interne — par exemple en lançant @code{make --j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Permettre au plus @var{n} travaux de construction en parallèle. La valeur -par défaut est @code{1}. La mettre à @code{0} signifie qu'aucune -construction ne sera effectuée localement ; à la place, le démon déchargera -les constructions (@pxref{Réglages du délestage du démon}) ou échouera. - -@item --max-silent-time=@var{secondes} -Lorsque le processus de construction ou de substitution restent silencieux -pendant plus de @var{secondes}, le terminer et rapporter une erreur de -construction. - -La valeur par défaut est @code{0}, ce qui désactive le délai. - -La valeur spécifiée ici peut être modifiée par les clients (@pxref{Options de construction communes, @code{--max-silent-time}}). - -@item --timeout=@var{secondes} -De même, lorsque le processus de construction ou de substitution dure plus -de @var{secondes}, le terminer et rapporter une erreur de construction. - -La valeur par défaut est @code{0}, ce qui désactive le délai. - -La valeur spécifiée ici peut être modifiée par les clients (@pxref{Options de construction communes, @code{--timeout}}). - -@item --rounds=@var{N} -Construire chaque dérivations @var{N} fois à la suite, et lever une erreur -si les résultats de construction consécutifs ne sont pas identiques -bit-à-bit. Remarquez que ce paramètre peut être modifié par les clients -comme @command{guix build} (@pxref{Invoquer guix build}). - -Lorsqu'utilisé avec @option{--keep-failed}, la sortie différente est gardée -dans le dépôt sous @file{/gnu/store/@dots{}-check}. Cela rend plus facile -l'étude des différences entre les deux résultats. - -@item --debug -Produire une sortie de débogage. - -Cela est utile pour déboguer des problèmes de démarrage du démon, mais -ensuite elle peut être modifiée par les clients, par exemple par l'option -@code{--verbosity} de @command{guix build} (@pxref{Invoquer guix build}). - -@item --chroot-directory=@var{rép} -Ajouter @var{rép} au chroot de construction. - -Cela peut changer le résultat d'un processus de construction — par exemple -s'il utilise une dépendance facultative trouvée dans @var{rép} lorsqu'elle -est disponible ou pas sinon. Pour cette raison, il n'est pas recommandé -d'utiliser cette option. À la place, assurez-vous que chaque dérivation -déclare toutes les entrées dont elle a besoin. - -@item --disable-chroot -Désactive les constructions dans un chroot. - -Utiliser cette option n'est pas recommandé car, de nouveau, elle permet aux -processus de construction d'accéder à des dépendances non déclarées. Elle -est nécessaire cependant lorsque @command{guix-daemon} tourne en tant -qu'utilisateur non privilégié. - -@item --log-compression=@var{type} -Compresser les journaux de construction suivant le @var{type}, parmi -@code{gzip}, @code{bzip2} ou @code{none}. - -À moins que @code{--lose-logs} ne soit utilisé, tous les journaux de -construction sont gardés dans @var{localstatedir}. Pour gagner de la place, -le démon les compresse automatiquement avec bzip2 par défaut. - -@item --disable-deduplication -@cindex déduplication -Désactiver la « déduplication » automatique des fichiers dans le dépôt. - -Par défaut, les fichiers ajoutés au dépôt sont automatiquement « dédupliqués -» : si un nouveau fichier est identique à un autre fichier trouvé dans le -dépôt, le démon en fait un lien en dur vers l'autre fichier. Cela réduit -considérablement l'utilisation de l'espace disque au prix d'une charge en -entrée/sortie plus grande à la fin d'un processus de construction. Cette -option désactive cette optimisation. - -@item --gc-keep-outputs[=yes|no] -Dire si le ramasse-miettes (GC) doit garder les sorties des dérivations -utilisées. - -@cindex racines du GC -@cindex racines du ramasse-miettes -Lorsqu'elle est à « yes », le GC gardera les sorties de toutes les -dérivations — les fichiers @code{.drv} — accessibles dans le dépôt. La -valeur par défaut est « no », ce qui signifie que les sorties des -dérivations ne sont gardées que si elles sont accessibles à partir d'une -racine du GC. @xref{Invoquer guix gc} pour plus d'informations sur les -racines du GC. - -@item --gc-keep-derivations[=yes|no] -Dire si le ramasse-miettes (GC) doit garder les dérivations correspondant à -des sorties utilisées. - -Lorsqu'elle est à « yes », comme c'est le cas par défaut, le GC garde les -dérivations — c.-à-d.@: les fichiers @file{.drv} — tant qu'au moins une de -leurs sorties est utilisée. Cela permet aux utilisateurs de garder une -trace de l'origine des éléments du dépôt. Le mettre à « no » préserve un -peu d'espace disque. - -De cette manière, avec @code{--gc-keep-derivations} à « yes », -l'accessibilité des sorties s'étend des sorties aux dérivations et avec -@code{--gc-keep-outputs} à « yes », elle s'étend des dérivations aux -sorties. Quand les deux options sont à « yes », le GC gardera tous les -prérequis de construction (les sources, le compilateur, les bibliothèques, -et les autres outils de construction) des objets accessibles dans le dépôt, -indépendamment du fait qu'ils soient ou non accessibles depuis une racine du -GC. Cela est pratique pour les développeurs car ça leur fait gagner du -temps de reconstruction et de téléchargement. - -@item --impersonate-linux-2.6 -Sur les système basés sur Linux, se faire passer pour Linux 2.6. Cela -signifie que l'appel système du noyau @code{uname} rapportera 2.6 comme -numéro de version. - -Cela peut être utile pour construire des programmes qui dépendent -(généralement sans fondement) du numéro de version du noyau. - -@item --lose-logs -Ne pas garder les journaux de construction. Par défaut ils sont gardés dans -@code{@var{localstatedir}/guix/log}. - -@item --system=@var{système} -Supposer que @var{système} est le type de système actuel. Par défaut c'est -la paire architecture-noyau trouvée à la configuration, comme -@code{x86_64-linux}. - -@item --listen=@var{extrémité} -Écouter les connexions sur @var{extrémité}. @var{extrémité} est interprété -comme un nom de fichier d'un socket Unix-domain s'il commence par @code{/} -(barre oblique). Sinon, @var{extrémité} est interprété comme un nom de -domaine ou d'hôte et un port sur lequel écouter. Voici quelques exemples : - -@table @code -@item --listen=/gnu/var/daemon -Écouter les connexions sur le socket Unix-domain @file{/gnu/var/daemon} en -le créant si besoin. - -@item --listen=localhost -@cindex démon, accès distant -@cindex accès distant au démon -@cindex démon, paramètres de grappes -@cindex grappes, paramètres du démon -Écouter les connexions TCP sur l'interface réseau correspondant à -@code{localhost} sur le port 44146. - -@item --listen=128.0.0.42:1234 -Écouter les connexions TCP sur l'interface réseau correspondant à -@code{128.0.0.42} sur le port 1234. -@end table - -Cette option peut être répétée plusieurs fois, auquel cas -@command{guix-daemon} accepte des connexions sur toutes les extrémités -spécifiées. Les utilisateurs peuvent dire aux commandes clientes à quelle -extrémité se connecter en paramétrant la variable d'environnement -@code{GUIX_DAEMON_SOCKET} (@pxref{Le dépôt, @code{GUIX_DAEMON_SOCKET}}). - -@quotation Remarque -Le protocole du démon est @emph{non authentifié et non chiffré}. Utiliser -@code{--listen=@var{host}} est adapté sur des réseaux locaux, comme pour des -grappes de serveurs, où seuls des nœuds de confiance peuvent se connecter au -démon de construction. Dans les autres cas où l'accès à distance au démon -est requis, nous conseillons d'utiliser un socket Unix-domain avec SSH@. -@end quotation - -Lorsque @code{--listen} est omis, @command{guix-daemon} écoute les -connexions sur le socket Unix-domain situé à -@file{@var{localstatedir}/guix/daemon-socket/socket}. -@end table - - -@node Réglages applicatifs -@section Réglages applicatifs - -@cindex distro externe -Lorsque vous utilisez Guix par dessus une distribution GNU/Linux qui n'est -pas Guix System — ce qu'on appelle une @dfn{distro externe} — quelques -étapes supplémentaires sont requises pour que tout soit en place. En voici -certaines. - -@subsection Régionalisation - -@anchor{locales-and-locpath} -@cindex régionalisation, en dehors de Guix System -@vindex LOCPATH -@vindex GUIX_LOCPATH -Les paquets installés @i{via} Guix n'utiliseront pas les données de -régionalisation du système hôte. À la place, vous devrez d'abord installer -l'un des paquets linguistiques disponibles dans Guix puis définir la -variable d'environnement @code{GUIX_LOCPATH} : - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Remarquez que le paquet @code{glibc-locales} contient les données pour tous -les environnement linguistiques supportés par la GNU@tie{}libc et pèse -environ 110@tie{}Mo. Autrement, les @code{glibc-utf8-locales} est plus -petit mais limité à quelques environnements UTF-8. - -La variable @code{GUIX_LOCPATH} joue un rôle similaire à @code{LOCPATH} -(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference -Manual}). Il y a deux différences importantes cependant : - -@enumerate -@item -@code{GUIX_LOCPATH} n'est compris que par la libc dans Guix et pas par la -libc fournie par les distros externes. Ainsi, utiliser @code{GUIX_LOCPATH} -vous permet de vous assurer que les programmes de la distro externe ne -chargeront pas de données linguistiques incompatibles. - -@item -La libc ajoute un suffixe @code{/X.Y} à chaque entrée de -@code{GUIX_LOCPATH}, où @code{X.Y} est la version de la libc — p.@: ex.@: -@code{2.22}. Cela signifie que, si votre profile Guix contient un mélange -de programmes liés avec des versions différentes de la libc, chaque version -de la libc essaiera de charger les environnements linguistiques dans le bon -format. -@end enumerate - -Cela est important car le format des données linguistiques utilisés par -différentes version de la libc peuvent être incompatibles. - -@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) -Lorsque vous utilisez Guix sur une distro externe, nous @emph{recommandons -fortement} que ce système fasse tourner le @dfn{démon de cache de service de -noms} de la bibliothèque C de GNU, @command{nscd}, qui devrait écouter sur -le socket @file{/var/run/nscd/socket}. Sans cela, les applications -installées avec Guix peuvent échouer à résoudre des noms d'hôtes ou -d'utilisateurs, ou même planter. Les paragraphes suivants expliquent -pourquoi. - -@cindex @file{nsswitch.conf} -La bibliothèque C de GNU implémente un @dfn{name service switch} (NSS), qui -est un mécanisme d'extension pour les « résolutions de noms » en général : -résolution de nom d'hôte, de compte utilisateur et plus (@pxref{Name Service Switch,,, libc, The GNU C Library Reference Manual}). - -@cindex Network information service (NIS) -@cindex NIS (Network information service) -Comme il est extensible, NSS supporte des @dfn{greffons} qui fournissent une -nouvelle implémentation de résolution de nom : par exemple le greffon -@code{nss-mdns} permet la résolution de noms d'hôtes en @code{.local}, le -greffon @code{nis} permet la résolution de comptes utilisateurs avec le -Network Information Service (NIS), etc. Ces « services de recherches » -supplémentaires sont configurés au niveau du système dans -@file{/etc/nsswitch.conf}, et tous les programmes qui tournent sur ce -système honorent ces paramètres (@pxref{NSS Configuration File,,, libc, The -GNU C Reference Manual}) - -Lorsqu'ils essayent d'effectuer une résolution de nom — par exemple en -appelant la fonction @code{getaddrinfo} en C — les applications essayent -d'abord de se connecter au nscd ; en cas de réussite, nscd effectue la -résolution de nom pour eux. Si le nscd ne tourne pas, alors ils effectuent -la résolution eux-mêmes, en changeant les service de résolution dans leur -propre espace d'adressage et en le lançant. Ce services de résolution de -noms — les fichiers @file{libnns_*.so} — sont @code{dlopen}és mais ils -peuvent provenir de la bibliothèque C du système, plutôt que de la -bibliothèque C à laquelle l'application est liée (la bibliothèque C de -Guix). - -Et c'est là que se trouve le problème : si votre application est liée à la -bibliothèque C de Guix (disons, glibc-2.24) et essaye de charger les -greffons NSS d'une autre bibliothèque C (disons, @code{libnss_mdns.so} pour -glibc-2.22), il est très probable qu'elle plante ou que sa résolution de nom -échoue de manière inattendue. - -Lancer @command{nscd} sur le système, entre autres avantages, élimine ce -problème d'incompatibilité binaire car ces fichiers @code{libnss_*.so} sont -chargés par le processus @command{nscd}, pas par l'application elle-même. - -@subsection Polices X11 - -@cindex polices -La majorité des applications graphiques utilisent fontconfig pour trouver et -charger les police et effectuer le rendu côté client X11. Le paquet -@code{fontconfig} dans Guix cherche les polices dans -@file{$HOME/.guix-profile} par défaut. Ainsi, pour permettre aux -applications graphiques installées avec Guix d'afficher des polices, vous -devez aussi installer des polices avec Guix. Les paquets de polices -essentiels sont @code{gs-fonts}, @code{font-dejavu} et -@code{font-gnu-freefont-ttf}. - -Pour afficher des textes écrits en chinois, en japonais ou en coréen dans -les applications graphiques, installez @code{font-adobe-source-han-sans} ou -@code{font-wqy-zenhei}. Le premier a plusieurs sorties, une par famille de -langue (@pxref{Des paquets avec plusieurs résultats}). Par exemple, la commande -suivante installe les polices pour le chinois : - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Les vieux programmes comme @command{xterm} n'utilisent pas fontconfig et -s'appuient sur le rendu du côté du serveur. Ces programmes ont besoin de -spécifier le nom complet de la police en utilisant XLFD (X Logical Font -Description), comme ceci : - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -Pour pouvoir utiliser ces noms complets avec les polices TrueType installées -dans votre profil Guix, vous devez étendre le chemin des polices du serveur -X : - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See . -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -Ensuite, vous pouvez lancer @code{xlsfonts} (du paquet @code{xlsfonts}) pour -vous assurer que vos polices TrueType y sont listées. - -@cindex @code{fc-cache} -@cindex cache de polices -Après l'installation des polices vous devrez peut-être rafraîchir le cache -des polices pour pouvoir les utiliser dans les applications. Ça s'applique -aussi lorsque les applications installées avec Guix n'ont pas l'air de -trouver les polices. Pour forcer la reconstruction du cache de polices -lancez @code{fc-cache -f}. La commande @code{fc-cache} est fournie par le -paquet @code{fontconfig}. - -@subsection Certificats X.509 - -@cindex @code{nss-certs} -Le paquet @code{nss-certs} fournit les certificats X.509 qui permettent aux -programmes d'authentifier les serveurs web par HTTPS@. - -Lorsque vous utilisez Guix sur une distribution externe, vous pouvez -installer ce paquet et définir les variables d'environnement adéquates pour -que les paquets sachent où trouver les certificats. @xref{Certificats X.509}, pour des informations détaillées. - -@subsection Paquets emacs - -@cindex @code{emacs} -Lorsque vous installez les paquets Emacs avec Guix, les fichiers elisp -peuvent être placés soit dans -@file{$HOME/.guix-profile/share/emacs/site-lisp/} soit dans des -sous-répertoires de -@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. Ce dernier existe -car il existe potentiellement des milliers de paquets Emacs et stocker leurs -fichiers dans un seul répertoire peut ne pas être fiable (à cause de -conflits de noms). Donc on pense qu'utiliser un répertoire séparé est une -bonne idée. C'est très similaire à la manière dont le système de paquet -d'Emacs organise la structure de fichiers (@pxref{Package Files,,, emacs, -The GNU Emacs Manual}). - -Par défaut, Emacs (installé avec Guix) « sait » où ces paquets ce trouvent, -donc vous n'avez pas besoin de le configurer. Si, pour quelque raison que -ce soit, vous souhaitez éviter de charger automatiquement les paquets Emacs -installés avec Guix, vous pouvez le faire en lançant Emacs avec l'option -@code{--no-site-file} (@pxref{Init File,,, emacs, The GNU Emacs Manual}). - -@subsection La chaîne d'outils GCC - -@cindex GCC -@cindex ld-wrapper - -Guix offre des paquets de compilateurs individuels comme @code{gcc} mais si -vous avez besoin d'une chaîne de compilation complète pour compiler et lier -du code source, vous avez en fait besoin du paquet @code{gcc-toolchain}. Ce -paquet fournit une chaîne d'outils GCC pour le développement C/C++, dont GCC -lui-même, la bibliothèque C de GNU (les en-têtes et les binaires, plus les -symboles de débogage dans la sortie @code{debug}), Binutils et une enveloppe -pour l'éditeur de liens. - -Le rôle de l'enveloppe est d'inspecter les paramètres @code{-L} et @code{-l} -passés à l'éditeur de liens, d'ajouter des arguments @code{-rpath} -correspondants et d'invoquer le véritable éditeur de liens avec ce nouvel -ensemble d'arguments. Vous pouvez dire à l'enveloppe de refuser de lier les -programmes à des bibliothèques en dehors du dépôt en paramétrant la variable -d'environnement @code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} sur @code{no}. - -@c TODO What else? - -@c ********************************************************************* -@node Installation du système -@chapter Installation du système - -@cindex installer Guix System -@cindex Guix System, installation -Cette section explique comment installer Guix System sur une machine. Guix, -en tant que gestionnaire de paquets, peut aussi être installé sur un système -GNU/Linux déjà installé, @pxref{Installation}. - -@ifinfo -@quotation Remarque -@c This paragraph is for people reading this from tty2 of the -@c installation image. -Vous lisez cette documentation avec un lecteur Info. Pour des détails sur -son utilisation, appuyez sur la touche @key{ENTRÉE} (« Entrée » ou « à la -ligne ») sur le lien suivant : @pxref{Top, Info reader,, info-stnd, -Stand-alone GNU Info}. Appuyez ensuite sur @kbd{l} pour revenir ici. - -Autrement, lancez @command{info info} dans un autre tty pour garder ce -manuel ouvert. -@end quotation -@end ifinfo - -@menu -* Limitations:: Ce à quoi vous attendre. -* Considérations matérielles:: Matériel supporté. -* Installation depuis une clef USB ou un DVD:: Préparer le média - d'installation. -* Préparer l'installation:: Réseau, partitionnement, etc. -* Installation graphique guidée:: Installation graphique facile. -* Installation manuelle:: Installation manuelle pour les sorciers. -* Après l'installation du système:: Une fois que l'installation a - réussi. -* Installer Guix dans une VM:: Jouer avec le système Guix. -* Construire l'image d'installation:: D'où vient tout cela. -@end menu - -@node Limitations -@section Limitations - -We consider Guix System to be ready for a wide range of ``desktop'' and -server use cases. The reliability guarantees it provides---transactional -upgrades and rollbacks, reproducibility---make it a solid foundation. - -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -LVM (gestionnaire de volumes logiques) n'est pas supporté. - -@item -De plus en plus de services systèmes sont fournis (@pxref{Services}) mais -certains manquent toujours cruellement. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Services de bureaux}), as well as a number of X11 window managers. However, KDE is -currently missing. -@end itemize - -More than a disclaimer, this is an invitation to report issues (and success -stories!), and to join us in improving it. @xref{Contribuer}, for more -info. - - -@node Considérations matérielles -@section Considérations matérielles - -@cindex prise en charge du matériel sur Guix System -GNU@tie{}Guix se concentre sur le respect des libertés de ses utilisateurs. -Il est construit autour du noyau Linux-libre, ce qui signifie que seuls les -matériels pour lesquels des pilotes logiciels et des microgiciels libres -sont disponibles sont pris en charge. De nos jours, une grande gamme de -matériel qu'on peut acheter est prise en charge par GNU/Linux-libre — des -claviers aux cartes graphiques en passant par les scanners et les -contrôleurs Ethernet. Malheureusement, il reste des produit dont les -fabricants refusent de laisser le contrôle aux utilisateurs sur leur propre -utilisation de l'ordinateur, et ces matériels ne sont pas pris en charge par -Guix System. - -@cindex WiFi, support matériel -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 @code{%base-firmware} (@pxref{Référence de système d'exploitation, -@code{firmware}}). - -@cindex RYF, Respects Your Freedom -La @uref{https://www.fsf.org/, Free Software Foundation} a un programme de -certification nommé @uref{https://www.fsf.org/ryf, @dfn{Respects Your -Freedom}} (RYF), pour les produits matériels qui respectent votre liberté et -votre vie privée en s'assurant que vous avez le contrôle sur l'appareil. -Nous vous encourageons à vérifier la liste des appareils certifiés par RYF. - -Une autre ressource utile est le site web @uref{https://www.h-node.org/, -H-Node}. Il contient un catalogue d'appareils avec des informations sur -leur support dans GNU/Linux. - - -@node Installation depuis une clef USB ou un DVD -@section Installation depuis une clef USB ou un DVD - -Une image d'installation ISO-9660 téléchargeable depuis -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{système}.iso.xz} -peut être écrite sur une clef USB ou gravée sur un DVD, où @var{système} est -l'une de ces valeurs : - -@table @code -@item x86_64-linux -pour un système GNU/Linux sur un CPU compatible Intel/AMD 64-bits ; - -@item i686-linux -pour un système GNU/Linux sur un CPU compatible Intel 32-bits ; -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Assurez-vous de télécharger les fichiers @file{.sig} associés et de vérifier -l'authenticité de l'image avec, de cette manière : - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -@end example - -Si cette commande échoue parce que vous n'avez pas la clef publique requise, -lancez cette commande pour l'importer : - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -et relancez la commande @code{gpg --verify}. - -Cette image contient les outils nécessaires à l'installation. Elle est -faite pour être copiée @emph{telle quelle} sur une clef USB assez grosse ou -un DVD. - -@unnumberedsubsec Copie sur une clef USB - -Pour copier l'image sur une clef USB, suivez ces étapes : - -@enumerate -@item -Décompressez l'image avec la commande @command{xz} : - -@example -xz -d guix-system-install-@value{VERSION}.@var{système}.iso.xz -@end example - -@item -Insérez la clef USB de 1@tie{}Gio ou plus dans votre machine et déterminez -son nom d'appareil. En supposant que la clef usb est connue sous le nom de -@file{/dev/sdX}, copiez l'image avec : - -@example -dd if=guix-system-install-@value{VERSION}.@var{système}.iso of=/dev/sdX -sync -@end example - -Accéder à @file{/dev/sdX} requiert généralement les privilèges -super-utilisateur. -@end enumerate - -@unnumberedsubsec Graver sur un DVD - -Pour copier l'image sur un DVD, suivez ces étapes : - -@enumerate -@item -Décompressez l'image avec la commande @command{xz} : - -@example -xz -d guix-system-install-@value{VERSION}.@var{système}.iso.xz -@end example - -@item -Insérez un DVD vierge dans votre machine et déterminez son nom d'appareil. -En supposant que le DVD soit connu sont le nom de @file{/dev/srX}, copiez -l'image avec : - -@example -growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{système}.iso -@end example - -Accéder à @file{/dev/srX} requiert généralement les privilèges -super-utilisateur. -@end enumerate - -@unnumberedsubsec Démarrage - -Une fois que c'est fait, vous devriez pouvoir redémarrer le système et -démarrer depuis la clef USB ou le DVD. Pour cela, vous devrez généralement -entrer dans le menu de démarrage BIOS ou UEFI, où vous pourrez choisir de -démarrer sur la clef USB. - -@xref{Installer Guix dans une VM}, si, à la place, vous souhaitez installer -Guix System dans une machine virtuelle (VM). - - -@node Préparer l'installation -@section Préparer l'installation - -Une fois que vous avez démarré, vous pouvez utiliser l'installateur -graphique, qui rend facile la prise en main (@pxref{Installation graphique guidée}). Autrement, si vous êtes déjà familier avec GNU/Linux et que -vous voulez plus de contrôle que ce que l'installateur graphique ne fournit, -vous pouvez choisir le processus d'installation « manuel » (@pxref{Installation manuelle}). - -L'installateur graphique est disponible sur le TTY1. Vous pouvez obtenir -des shells root sur les TTY 3 à 6 en tapant @kbd{ctrl-alt-f3}, -@kbd{ctrl-alt-f4} etc. Le TTY2 affiche cette documentation que vous pouvez -atteindre avec @kbd{ctrl-alt-f2}. On peut naviguer dans la documentation -avec les commandes du lecteur Info (@pxref{Top,,, info-stnd, Stand-alone GNU -Info}). Le démon de souris GPM tourne sur le système d'installation, ce qui -vous permet de sélectionner du texte avec le bouton gauche de la souris et -de le coller en appuyant sur la molette. - -@quotation Remarque -L'installation nécessite un accès au réseau pour que les dépendances -manquantes de votre configuration système puissent être téléchargées. Voyez -la section « réseau » plus bas. -@end quotation - -@node Installation graphique guidée -@section Installation graphique guidée - -L'installateur graphique est une interface utilisateur en mode texte. Il -vous guidera, avec des boîtes de dialogue, le long des étapes requises pour -installer GNU@tie{}Guix System. - -La première boîte de dialogue vous permet de paramétrer le système comme -vous le souhaitez pendant l'installation : vous pouvez choisir la langue, la -disposition du clavier et paramétrer le réseau, qui sera utilisé pendant -l'installation. L'image ci-dessous montre le dialogue pour le réseau. - -@image{images/installer-network,5in,, paramétrage du réseau avec -l'installateur graphique} - -Les étapes suivantes vous permettent de partitionner votre disque dur, comme -le montre l'image ci-dessous, de choisir si vous voulez ou non utiliser des -systèmes de fichiers chiffrés, de saisir le nom d'hôte et le mot de passe -root et de créer un compte supplémentaire, entre autres choses. - -@image{images/installer-partitions,5in,, partitionnement du disque avec -l'installateur graphique} - -Remarquez que, à tout moment, l'installateur vous permet de sortir de -l'étape d'installation actuelle et de recommencer une étape précédente, -comme le montre l'image ci-dessous. - -@image{images/installer-resume,5in,, reprise du processus d'installation} - -Une fois que vous avez fini, l'installateur produit une configuration de -système d'exploitation et vous la montre (@pxref{Utiliser le système de configuration}). À ce moment, vous pouvez appuyer sur « OK » et l'installation -continuera. Lorsqu'elle aura réussi, vous pourrez redémarrer sur le nouveau -système et vous amuser. @xref{Après l'installation du système}, pour la suite des -festivités ! - - -@node Installation manuelle -@section Installation manuelle - -Cette section décrit comme vous pourriez installe « manuellement » -GNU@tie{}Guix System sur votre machine. Cette option nécessite que vous -soyez familier avec GNU/Linux, le shell et avec les outils d'administration -usuels. Si vous pensez que ce n'est pas pour vous, pensez à utiliser -l'installateur graphique (@pxref{Installation graphique guidée}). - -Le système d'installation fournit des shells root sur les TTY 3 à 6 ; -appuyez sur @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4} etc pour y accéder. Il -inclus plusieurs outils usuels pour requis pour cette tâche. Mais c'est -aussi un système Guix complet, ce qui signifie que vous pouvez installer des -paquets supplémentaires si vous en avez besoin, avec @command{guix package} -(@pxref{Invoquer guix package}). - -@menu -* Disposition du clavier réseau et partitionnement:: Paramètres initiaux. -* Effectuer l'installation:: Installer. -@end menu - -@node Disposition du clavier réseau et partitionnement -@subsection Disposition du clavier réseau et partitionnement - -Avant que vous ne puissiez installer le système, vous voudrez sans doute -ajuster la disposition du clavier, paramétrer le réseau et partitionner le -disque dur cible. Cette section vous guidera à travers tout cela. - -@subsubsection Disposition du clavier - -@cindex disposition du clavier -L'image d'installation utilise la disposition clavier qwerty (US). Si vous -voulez la changer, vous pouvez utiliser la commande @command{loadkeys}. Par -exemple, la commande suivante sélectionne la disposition Dvorak : - -@example -loadkeys dvorak -@end example - -Consultez les fichiers dans @file{/run/current-system/profile/share/keymaps} -pour trouver une liste des dispositions disponibles. Lancez @command{man -loadkey} pour plus d'informations. - -@subsubsection Réseau - -Lancez la commande suivante pour voir comment vos interfaces réseau sont -appelées : - -@example -ifconfig -a -@end example - -@noindent -@dots{} ou, avec la commande spécifique à GNU/Linux @command{ip} : - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Les interfaces filaires ont un nom qui commence par @samp{e} ; par exemple, -l'interface qui correspond au premier contrôleur Ethernet sur la carte mère -est appelé @samp{eno1}. Les interfaces sans-fil ont un nom qui commence par -@samp{w}, comme @samp{w1p2s0}. - -@table @asis -@item Connexion filaire -Pour configure une connexion filaire, lancez la commande suivante, en -remplaçant @var{interface} par le nom de l'interface filaire que vous voulez -utiliser. - -@example -ifconfig @var{interface} up -@end example - -@item Connexion sans-fil -@cindex sans-fil -@cindex WiFi -Pour configurer le réseau sans-fil, vous pouvez créer un fichier de -configuration pour l'outil de configuration @command{wpa_supplicant} (son -emplacement importe peu) avec l'un des éditeurs de texte disponibles comme -@command{nano} : - -@example -nano wpa_supplicant.conf -@end example - -Par exemple, la déclaration qui suit peut aller dans ce fichier et -fonctionnera pour plusieurs réseaux sans-fil, si vous donnez le vrai SSID et -la phrase de passe pour le réseau auquel vous vous connectez : - -@example -network=@{ - ssid="@var{mon-ssid}" - key_mgmt=WPA-PSK - psk="la phrase de passe secrète du réseau" -@} -@end example - -Démarrez le service sans-fil et lancez-le en tache de fond avec la commande -suivante (en remplaçant @var{interface} par le nom de l'interface réseau que -vous voulez utiliser) : - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B -@end example - -Lancez @command{man wpa_supplicant} pour plus d'informations. -@end table - -@cindex DHCP -À partir de ce moment, vous avez besoin d'une adresse IP. Sur les réseaux -où les IP sont automatiquement attribuée par DHCP, vous pouvez lancer : - -@example -dhclient -v @var{interface} -@end example - -Essayez de pinger un serveur pour voir si le réseau fonctionne : - -@example -ping -c 3 gnu.org -@end example - -Mettre en place un accès réseau est presque toujours une nécessité parce que -l'image ne contient pas tous les logiciels et les outils dont vous pourriez -avoir besoin. - -@cindex installer par SSH -Si vous le souhaitez, vous pouvez continuer l'installation à distance en -démarrant un serveur SSH : - -@example -herd start ssh-daemon -@end example - -Assurez-vous soit de définir un mot de passe avec @command{passwd}, soit de -configurer l'authentification par clef OpenSSH avant de vous connecter. - -@subsubsection Partitionnement - -À moins que vous ne l'ayez déjà fait, l'étape suivante consiste à -partitionner le disque puis à formater les partitions cibles. - -L'image d'installation inclus plusieurs outils de partitionnement, dont -Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), -@command{fdisk}, et @command{cfdisk}. Lancez-en un et paramétrez votre -disque avec le partitionnement qui vous convient : - -@example -cfdisk -@end example - -Si votre disque utilise le format des tables de partitions GUID (GPT) et que -vous souhaitez installer un GRUB pour système BIOS (c'est le cas par -défaut), assurez-vous de créer qu'une partition de démarrage BIOS soit bien -disponible (@pxref{BIOS installation,,, grub, GNU GRUB manual}). - -@cindex EFI, installation -@cindex UEFI, installation -@cindex ESP, partition système EFI -Si vous souhaitez à la place utilise GRUB pour système EFI, vous devrez -avoir une @dfn{partition système EFI} (ESP) en FAT32. Cette partition peut -être montée dans @file{/boot/efi} par exemple et doit avoir le drapeau -@code{esp}. P.@: ex.@: pour @command{parted} : - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Remarque -@vindex grub-bootloader -@vindex grub-efi-bootloader -Vous n'êtes pas sûr de savoir si vous devez utiliser un GRUB EFI ou BIOS ? -Si le répertoire @file{/sys/firmware/efi} existe sur l'image d'installation, -vous devriez probablement effectuer une installation EFI, avec -@code{grub-efi-bootloader}. Sinon, vous devriez utiliser le GRUB en BIOS, -@code{grub-bootloader}. @xref{Configuration du chargeur d'amorçage} pour plus -d'information sur le chargeur d'amorçage. -@end quotation - -Une fois que vous avez fini le partitionnement du disque dur cible, vous -devez créer un système de fichier sur les partitions@footnote{Actuellement -Guix System ne supporte que les systèmes de fichiers ext4 et btrfs. En -particulier, le code qui lit les UUID des systèmes de fichiers et les -étiquettes ne fonctionne que pour ces types de systèmes de fichiers.}. Pour -l'ESP, si vous en avez une et en supposant que ce soit @file{/dev/sda1}, -lancez : - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Préférez assigner une étiquette au système de fichier pour que vous puissiez -vous y référer de manière fiable dans la déclaration @code{file-system} -(@pxref{Systèmes de fichiers}). On le fait habituellement avec l'option @code{-L} -de @command{mkfs.ext4} et des commandes liées. Donc, en supposant que la -partition racine soit sur @file{/dev/sda2}, on peut créer un système de -fichier avec pour étiquette @code{my-root} avec : - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex chiffrement du disque -Si vous voulez plutôt chiffrer la partition racine, vous pouvez utiliser les -utilitaires Cryptsetup et LUKS pour cela (voir @inlinefmtifelse{html, -@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, -@code{man cryptsetup}} pour plus d'informations). En supposant que vous -voulez stocker la partition racine sur @file{/dev/sda2}, la séquence de -commandes suivante vous mènerait à ce résultat : - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Une fois cela effectué, montez le système de fichier cible dans @file{/mnt} -avec une commande comme (de nouveau, en supposant que @code{my-root} est -l'étiquette du système de fichiers racine) : - -@example -mount LABEL=my-root /mnt -@end example - -Montez aussi tous les systèmes de fichiers que vous voudriez utiliser sur le -système cible relativement à ce chemin. Si vous avez choisi d'avoir un -@file{/boot/efi} comme point de montage EFI par exemple, montez-la sur -@file{/mnt/boot/efi} maintenant pour qu'elle puisse être trouvée par -@code{guix system init} ensuite. - -Enfin, si vous souhaitez utiliser une ou plusieurs partitions de swap -(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference -Manual}), assurez-vous de les initialiser avec @command{mkswap}. En -supposant que vous avez une partition de swap sur @file{/dev/sda3}, vous -pouvez lancer : - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Autrement, vous pouvez utiliser un fichier de swap. Par exemple, en -supposant que dans le nouveau système vous voulez utiliser le fichier -@file{/swapfile} comme fichier de swap, vous lanceriez@footnote{Cet exemple -fonctionnera sur plusieurs types de systèmes de fichiers (p.@: ex.@: ext4). -Cependant, pour les systèmes de fichiers qui utilisent la copie sur écriture -(COW) comme btrfs, les étapes requises peuvent varier. Pour plus de -détails, regardez les pages de manuel de @command{mkswap} et -@command{swapon}.} : - -@example -# Cela représente 10 Gio d'espace d'échange. Ajustez « count » pour changer la taille. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# Par sécurité, laissez le fichier en lecture et en écriture uniquement pour root. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Remarquez que si vous avez chiffré la partition racine et créé un fichier -d'échange dans son système de fichier comme décrit ci-dessus, alors le -chiffrement protégera aussi le fichier d'échange, comme n'importe quel -fichier de ce système de fichiers. - -@node Effectuer l'installation -@subsection Effectuer l'installation - -Lorsque la partition cible est prête et que les autres partitions sont -montées, on est prêt à commencer l'installation. Commencez par : - -@example -herd start cow-store /mnt -@end example - -Cela rend @file{/gnu/store} capable de faire de la copie sur écriture, de -sorte que les paquets ajoutés pendant l'installation sont écrits sur le -disque cible sur @file{/mnt} plutôt que gardés en mémoire. Cela est -nécessaire parce que la première phase de la commande @command{guix system -init} (voir plus bas) implique de télécharger ou de construire des éléments -de @file{/gnu/store} qui est initialement un système de fichiers en mémoire. - -Ensuite, vous devrez modifier un fichier et fournir la déclaration du -système à installer. Pour cela, le système d'installation propose trois -éditeurs de texte. Nous recommandons GNU nano (@pxref{Top,,, nano, GNU nano -Manual}), qui supporte la coloration syntaxique la correspondance de -parenthèses ; les autres éditeurs sont GNU Zile (un clone d'Emacs) et nvi -(un clone de l'éditeur @command{vi} original de BSD). Nous recommandons -vivement de stocker ce fichier sur le système de fichier racine cible, -disons en tant que @file{/mnt/etc/config.scm}. Sinon, vous perdrez votre -fichier de configuration une fois que vous aurez redémarré sur votre nouveau -système. - -@xref{Utiliser le système de configuration}, pour un aperçu de comment créer votre -fichier de configuration. Les exemples de configuration dont on parle dans -cette section sont disponibles dans @file{/etc/configuration} sur l'image -d'installation. Ainsi, pour commencer avec une configuration du système qui -fournit un serveur d'affichage graphique (un système de « bureau »), vous -pouvez lancer ce qui suit : - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -Vous devriez faire attention à ce que contient votre fichier de -configuration, en particulier : - -@itemize -@item -Assurez-vous que la forme @code{bootloader-configuration} se réfère à la -cible où vous voulez installer GRUB. Elle devrait aussi mentionner -@code{grub-bootloader} si vous installer GRUB en mode BIOS (ou « legacy ») -ou @code{grub-efi-bootloader} pour les système UEFI plus récents. Pour les -anciens systèmes, le champs @code{target} contient un périphérique comme -@code{/dev/sda} ; pour les systèmes UEFI il contient un chemin vers une -partition EFI montée, comme @code{/boot/efi}, et assurez-vous bien que ce -chemin est monté et qu'il y a une entrée @code{file-system} dans votre -configuration. - -@item -Assurez-vous que les étiquettes de vos systèmes de fichiers correspondent -aux valeurs de leur champs @code{device} dans votre configuration -@code{file-system}, en supposant que la configuration @code{file-system} -utilise la procédure @code{file-system-label} dans son champ @code{device}. - -@item -Si vous avez des partitions RAID ou chiffrées, assurez-vous d'ajouter un -champ @code{mapped-device} pour les décrire (@pxref{Périphériques mappés}). -@end itemize - -Une fois que vous avez fini les préparatifs sur le fichier de configuration, -le nouveau système peut être initialisé (rappelez-vous que le système de -fichiers racine cible est dans @file{/mnt}) : - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -Cela copie tous les fichiers nécessaires et installe GRUB sur -@file{/dev/sdX} à moins que vous ne passiez l'option -@option{--no-bootloader}. Pour plus d'informations, @pxref{Invoquer guix system}. Cette commande peut engendrer des téléchargements ou des -constructions pour les paquets manquants, ce qui peut prendre du temps. - -Une fois que cette commande a terminé — et on l'espère réussi ! — vous -pouvez lancer @command{reboot} et démarrer sur votre nouveau système. Le -mot de passe @code{root} est d'abord vide ; les mots de passe des autres -utilisateurs doivent être initialisés avec la commande @command{passwd} en -tant que @code{root}, à mois que votre configuration ne spécifie autre chose -(@pxref{user-account-password, mot de passe des comptes utilisateurs}). -@xref{Après l'installation du système}, pour la suite ! - - -@node Après l'installation du système -@section Après l'installation du système - -Bravo ! Vous avez maintenant redémarré sur votre système Guix ! À partir -de maintenant, vous pouvez mettre à jour le système quand vous voudrez, avec -: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -Cela crée une nouvelle génération du système avec les derniers paquets et -services (@pxref{Invoquer guix system}). Nous vous recommandons de le faire -régulièrement pour que votre système inclue les dernières misse à jour de -sécurité (@pxref{Mises à jour de sécurité}). - -@c See . -@quotation Remarque -@cindex sudo vs.@: @command{guix pull} -Remarquez que @command{sudo guix} exécute la commande @command{guix} de -votre utilisateur et @emph{non} celle de root, parce que @command{sudo} ne -change pas @code{PATH}. Pour utiliser explicitement le @command{guix} de -root, tapez @command{sudo -i guix @dots{}}. -@end quotation - -Rejoignez-nous sur @code{#guix} sur le réseau IRC Freenode ou sur -@file{guix-devel@@gnu.org} pour partager votre expérience ! - - -@node Installer Guix dans une VM -@section Installer Guix sur une machine virtuelle - -@cindex machine virtuelle, installation de Guix System -@cindex serveur privé virtuel (VPS) -@cindex VPS (serveur privé virtuel) -Si vous souhaitez installer Guix System sur une machine virtuelle (VM) ou un -serveur privé virtuel (VPS) plutôt que sur votre machine chérie, cette -section est faite pour vous. - -Pour démarrer une VM @uref{http://qemu.org/,QEMU} pour installer Guix System -sur une image disque, suivez ces étapes : - -@enumerate -@item -Tout d'abord récupérez et décompressez l'image d'installation du système -Guix comme décrit précédemment (@pxref{Installation depuis une clef USB ou un DVD}). - -@item -Créez une image disque qui contiendra le système installé. Pour créer une -image qcow2, utilise la commande @command{qemu-img} : - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -Le fichier qui en résulte sera bien plus petit que les 50 Go (habituellement -moins de 1 Mo) mais il grossira au fur et à mesure que le stockage virtuel -grossira. - -@item -Démarrez l'image d'installation USB dans une VM : - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guix-system-install-@value{VERSION}.@var{système}.iso \ - -drive file=guixsd.img -@end example - -L'ordre des périphérique est important. - -Dans la console de la VM, appuyez rapidement sur @kbd{F12} pour entrer dans -le menu de démarrage. Ensuite appuyez sur @kbd{2} et la touche @kbd{Entrée} -pour valider votre choix. - -@item -Vous êtes maintenant root dans la VM, continuez en suivant la procédure -d'installation. @xref{Préparer l'installation}, et suivez les -instructions. -@end enumerate - -Une fois l'installation terminée, vous pouvez démarrer le système dans votre -image @file{guixsd.img}. @xref{Lancer Guix dans une VM}, pour une manière de -faire. - -@node Construire l'image d'installation -@section Construire l'image d'installation - -@cindex image d'installation -L'image d'installation décrite plus haut a été construite avec la commande -@command{guix system}, plus précisément : - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Regardez le fichier @file{gnu/system/install.scm} dans l'arborescence des -sources et regardez aussi @ref{Invoquer guix system} pour plus -d'informations sur l'image d'installation. - -@section Construire l'image d'installation pour les cartes ARM - -De nombreuses cartes ARM requièrent une variante spécifique du chargeur -d'amorçage @uref{http://www.denx.de/wiki/U-Boot/, U-Boot}. - -Si vous construisez une image disque et que le chargeur d'amorçage n'est pas -disponible autrement (sur un autre périphérique d'amorçage etc), il est -recommandé de construire une image qui inclus le chargeur d'amorçage, plus -précisément : - -@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} est le nom de la carte. Si vous spécifiez une -carte invalide, une liste de cartes possibles sera affichée. - -@c ********************************************************************* -@node Gestion de paquets -@chapter Gestion de paquets - -@cindex paquets -Le but de GNU Guix est de permettre à ses utilisateurs d'installer, mettre à -jour et supprimer facilement des paquets logiciels sans devoir connaître -leur procédure de construction ou leurs dépendances. Guix va aussi plus -loin que ces fonctionnalités évidentes. - -Ce chapitre décrit les principales fonctionnalités de Guix, ainsi que des -outils de gestion des paquets qu'il fournit. En plus de l'interface en -ligne de commande décrite en dessous de (@pxref{Invoquer guix package, -@code{guix package}}), vous pouvez aussi utiliser l'interface Emacs-Guix -(@pxref{Top,,, emacs-guix, Le manuel de référence de emacs-guix}), après -avoir installé le paquet @code{emacs-guix} (lancez la commande @kbd{M-x -guix-help} pour le démarrer) : - -@example -guix package -i emacs-guix -@end example - -@menu -* Fonctionnalités:: Comment Guix va rendre votre vie plus heureuse. -* Invoquer guix package:: Installation, suppression, etc.@: de paquets. -* Substituts:: Télécharger des binaire déjà construits. -* Des paquets avec plusieurs résultats:: Un seul paquet source, plusieurs - résultats. -* Invoquer guix gc:: Lancer le ramasse-miettes. -* Invoquer guix pull:: Récupérer la dernière version de Guix et de - la distribution. -* Canaux:: Personnaliser la collection des paquets. -* Inférieurs:: Interagir avec une autre révision de Guix. -* Invoquer guix describe:: Affiche des informations sur la révision Guix - actuelle. -* Invoquer guix archive:: Exporter et importer des fichiers du dépôt. -@end menu - -@node Fonctionnalités -@section Fonctionnalités - -Lorsque vous utilisez Guix, chaque paquet arrive dans @dfn{dépôt des -paquets}, dans son propre répertoire — quelque chose comme -@file{/gnu/store/xxx-paquet-1.2}, où @code{xxx} est une chaîne en base32. - -Plutôt que de se rapporter à ces répertoires, les utilisateurs ont leur -propre @dfn{profil} qui pointe vers les paquets qu'ils veulent vraiment -utiliser. Ces profils sont stockés dans le répertoire personnel de chaque -utilisateur dans @code{$HOME/.guix-profile}. - -Par exemple, @code{alice} installe GCC 4.7.2. Il en résulte que -@file{/home/alice/.guix-profile/bin/gcc} pointe vers -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Maintenant, sur la même -machine, @code{bob} a déjà installé GCC 4.8.0. Le profil de @code{bob} -continue simplement de pointer vers -@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc} — c.-à-d.@: les deux versions de -GCC coexistent surs le même système sans aucune interférence. - -La commande @command{guix package} est l'outil central pour gérer les -paquets (@pxref{Invoquer guix package}). Il opère sur les profils -utilisateurs et peut être utilisé avec les @emph{privilèges utilisateurs -normaux}. - -@cindex transactions -La commande fournit les opérations évidentes d'installation, de suppression -et de mise à jour. Chaque invocation est en fait une @emph{transaction} : -soit l'opération demandée réussi, soit rien ne se passe. Ainsi, si le -processus @command{guix package} est terminé pendant la transaction ou si -une panne de courant arrive pendant la transaction, le profil de -l'utilisateur reste dans son état précédent et reste utilisable. - -En plus, il est possible @emph{d'annuler} toute transaction sur les -paquets. Donc si par exemple un mise à jour installe une nouvelle version -d'un paquet qui révèle un bogue sérieux, vous pouvez revenir en arrière à -l'instance précédente de votre profil que vous saviez bien fonctionner. De -même, la configuration globale du système dans Guix est sujette aux mises à -jour transactionnelles et aux annulations (@pxref{Utiliser le système de configuration}). - -Tous les paquets du dépôt des paquets peut être @emph{glané}. Guix peut -déterminer quels paquets sont toujours référencés par les profils des -utilisateurs et supprimer ceux qui ne sont plus référencés de manière -prouvable (@pxref{Invoquer guix gc}). Les utilisateurs peuvent toujours -explicitement supprimer les anciennes générations de leur profil pour que -les paquets auxquels elles faisaient référence puissent être glanés. - -@cindex reproductibilité -@cindex constructions reproductibles -Guix prend une approche @dfn{purement fonctionnelle} de la gestion de -paquets, telle que décrite dans l'introduction (@pxref{Introduction}). -Chaque nom de répertoire de paquet dans @file{/gnu/store} contient un hash -de toutes les entrées qui ont été utilisées pendant la construction de ce -paquet — le compilateur, les bibliothèques, les scripts de construction, -etc. Cette correspondance directe permet aux utilisateurs de s'assurer que -l'installation d'un paquet donné correspond à l'état actuel de leur -distribution. Elle aide aussi à maximiser la @dfn{reproductibilité} : grâce -aux environnements de construction utilisés, une construction donnée à de -forte chances de donner des fichiers identiques bit-à-bit lorsqu'elle est -effectuée sur des machines différents (@pxref{Invoquer guix-daemon, -container}). - -@cindex substituts -Ce fondement permet à Guix de supporter le @dfn{déploiement transparent de -binaire ou source}. Lorsqu'une binaire pré-construit pour une entrée de -@file{/gnu/store} est disponible depuis une source externe (un -@dfn{substitut}), Guix le télécharge simplement et le décompresse ; sinon, -il construit le paquet depuis les sources localement (@pxref{Substituts}). -Comme les résultats des constructions sont généralement reproductibles au -bit près, si vous n'avez pas besoin de faire confiance aux serveurs qui -fournissent les substituts : vous pouvez forcer une construction locale et -@emph{défier} les fournisseurs (@pxref{Invoquer guix challenge}). - -Le contrôle de l'environnement de construction est aussi une fonctionnalité -utile pour les développeurs. La commande @command{guix environment} permet -aux développeurs d'un paquet de mettre en place rapidement le bon -environnement de développement pour leur paquet, sans avoir à installer -manuellement les dépendances du paquet dans leur profil (@pxref{Invoquer guix environment}). - -@cindex réplication, des environnements logiciels -@cindex suivi de la provenance, des artefacts logiciels -La totalité de Guix et des définitions de paquets sont placés sous contrôle -de version, et @command{guix pull} vous permet de « voyager dans le temps » -de l'historique de Guix lui-même (@pxref{Invoquer guix pull}). Cela est -rend possible la réplication d'une instance Guix sur une machine différente -ou plus tard, ce qui vous permet de @emph{répliquer des environnements -logiciels complets}, tout en garantissant un @dfn{suivi de provenance} -précis des logiciels. - -@node Invoquer guix package -@section Invoquer @command{guix package} - -@cindex installer des paquets -@cindex supprimer des paquets -@cindex installation de paquets -@cindex suppression de paquets -La commande @command{guix package} est l'outil qui permet d'installer, -mettre à jour et supprimer les paquets ainsi que de revenir à une -configuration précédente. Elle n'opère que dans le profil de l'utilisateur -et fonctionne avec les privilèges utilisateurs normaux -(@pxref{Fonctionnalités}). Sa syntaxe est : - -@example -guix package @var{options} -@end example -@cindex transactions -@var{options} spécifie d'abord les opérations à effectuer pendant la -transaction. À la fin, une nouvelle génération du profil est créée mais les -@dfn{générations} précédentes du profil restent disponibles si l'utilisateur -souhaite y revenir. - -Par exemple, pour supprimer @code{lua} et installer @code{guile} et -@code{guile-cairo} en une seule transaction : - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} supporte aussi une @dfn{approche déclarative} où -l'utilisateur spécifie l'ensemble exact des paquets qui doivent être -disponibles le passe @i{via} l'option @option{--manifest} -(@pxref{profile-manifest, @option{--manifest}}). - -@cindex profil -Pour chaque utilisateur, un lien symbolique vers le profil par défaut de cet -utilisateur est automatiquement créé dans @file{$HOME/.guix-profile}. Ce -lien symbolique pointe toujours vers la génération actuelle du profil par -défaut de l'utilisateur. Ainsi, les utilisateurs peuvent ajouter -@file{$HOME/.guix-profile/bin} à leur variable d'environnement @code{PATH} -etc. -@cindex chemins de recherche -Si vous n'utilisez pas la distribution système Guix, vous devriez ajouter -les lignes suivantes à votre @file{~/.bash_profile} (@pxref{Bash Startup -Files,,, bash, The GNU Bash Reference Manual}) pour que les shells créés -ensuite aient les bonnes définitions des variables d'environnement : - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -Dans un environnement multi-utilisateur, les profils utilisateurs sont -stockés comme une @dfn{racine du ramasse-miettes}, vers laquelle pointe -@file{$HOME/.guix-profile} (@pxref{Invoquer guix gc}). Ce répertoire est -normalement -@code{@var{localstatedir}/guix/profiles/per-user/@var{utilisateur}}, où -@var{localstatedir} est la valeur passée à @code{configure} avec -@code{--localstatedir} et @var{utilisateur} le nom d'utilisateur. Le -répertoire @file{per-user} est créé lorsque @command{guix-daemon} est -démarré et sous-répertoire @var{utilisateur} est créé par @command{guix -package}. - -Les @var{options} peuvent être les suivante : - -@table @code - -@item --install=@var{paquet} @dots{} -@itemx -i @var{paquet} @dots{} -Installer les @var{paquet}s spécifiés. - -Chaque @var{paquet} peut spécifier soit un simple nom de paquet, comme -@code{guile} ou un nom de paquet suivi d'un arobase et d'un numéro de -version, comme @code{guile@@1.8.8} ou simplement @code{guile@@1.8} (dans ce -dernier cas, la version la plus récente commençant par @code{1.8} est -utilisée). - -Si aucun numéro de version n'est spécifié, la version la plus récente -disponible est choisie. En plus, @var{paquet} peut contenir un deux-points, -suivi du nom d'une des sorties du paquet, comme dans @code{gcc:doc} ou -@code{binutils@@2.22:lib} (@pxref{Des paquets avec plusieurs résultats}). Des -paquets avec un nom correspondant et (éventuellement une version) sont -recherchés dans les modules de la distribution GNU (@pxref{Modules de paquets}). - -@cindex entrées propagées -Parfois les paquets ont des @dfn{entrées propagées} : ce sont des -dépendances qui sont installées automatiquement avec le paquet demandé -(@pxref{package-propagated-inputs, @code{propagated-inputs} in -@code{package} objects} pour plus d'informations sur les entrées propagées -dans les définitions des paquets). - -@anchor{package-cmd-propagated-inputs} -Un exemple est la bibliothèque MPC de GNU : ses fichiers d'en-tête C se -réfèrent à ceux de la bibliothèque MPFR de GNU, qui se réfèrent en retour à -ceux de la bibliothèque GMP. Ainsi, lorsqu'on installe MPC, les -bibliothèques MPFR et GMP sont aussi installées dans le profil ; supprimer -MPC supprimera aussi MPFR et GMP — à moins qu'ils n'aient été aussi -installés explicitement par l'utilisateur. - -D'autre part, les paquets dépendent parfois de la définition de variables -d'environnement pour leur chemin de recherche (voir les explications sur -@code{--search-paths} plus bas). Toute définition de variable -d'environnement manquante ou possiblement incorrecte est rapportée ici. - -@item --install-from-expression=@var{exp} -@itemx -e @var{exp} -Installer le paquet évalué par @var{exp} - -@var{exp} doit être une expression Scheme qui s'évalue en un objet -@code{}. Cette option est notamment utile pour distinguer les -variantes d'un paquet avec le même nom, avec des expressions comme @code{(@@ -(gnu packages base) guile-final)}. - -Remarquez que cette option installe la première sortie du paquet, ce qui -peut être insuffisant lorsque vous avez besoin d'une sortie spécifique d'un -paquet à plusieurs sorties. - -@item --install-from-file=@var{fichier} -@itemx -f @var{fichier} -Installer le paquet évalué par le code dans le @var{fichier}. - -Par exemple, @var{fichier} peut contenir une définition comme celle-ci -(@pxref{Définition des paquets}) : - -@example -@verbatiminclude package-hello.scm -@end example - -Les développeurs peuvent trouver utile d'inclure un tel fichier -@file{guix.scm} à la racine de l'arborescence des sources de leur projet qui -pourrait être utilisé pour tester des versions de développement et créer des -environnements de développement reproductibles (@pxref{Invoquer guix environment}). - -@item --remove=@var{paquet} @dots{} -@itemx -r @var{paquet} @dots{} -Supprimer les @var{paquet}s spécifiés. - -Comme pour @code{--install}, chaque @var{paquet} peut spécifier un numéro de -version ou un nom de sortie en plus du nom du paquet. Par exemple, @code{-r -glibc:debug} supprimerait la sortie @code{debug} de @code{glibc}. - -@item --upgrade[=@var{regexp} @dots{}] -@itemx -u [@var{regexp} @dots{}] -@cindex mettre à jour des paquets -Mettre à jour tous les paquets installés. Si une @var{regexp} ou plus est -spécifiée, la mise à jour n'installera que les paquets dont le nom -correspond à @var{regexp}. Voyez aussi l'option @code{--do-not-upgrade} en -dessous. - -Remarquez que cela met à jour vers la dernière version des paquets trouvée -dans la distribution actuellement installée. Pour mettre à jour votre -distribution, vous devriez lancer régulièrement @command{guix pull} -(@pxref{Invoquer guix pull}). - -@item --do-not-upgrade[=@var{regexp} @dots{}] -Lorsqu'elle est utilisée avec l'option @code{--upgrade}, ne @emph{pas} -mettre à jour les paquets dont le nom correspond à @var{regexp}. Par -exemple, pour mettre à jour tous les paquets du profil actuel à l'exception -de ceux qui contiennent la chaîne « emacs » : - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{fichier} -@itemx -m @var{fichier} -@cindex déclaration de profil -@cindex manifest de profil -Créer une nouvelle génération du profil depuis l'objet manifeste renvoyé par -le code Scheme dans @var{fichier}. - -Cela vous permet de @emph{déclarer} le contenu du profil plutôt que de le -construire avec une série de @code{--install} et de commandes similaires. -L'avantage étant que le @var{fichier} peut être placé sous contrôle de -version, copié vers d'autres machines pour reproduire le même profil, etc. - -@c FIXME: Add reference to (guix profile) documentation when available. -@var{fichier} doit retourner un objet @dfn{manifest} qui est en gros une -liste de paquets : - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Utiliser une sortie spécifique d'un paquet. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -Dans cet exemple on doit savoir quels modules définissent les variables -@code{emacs} et @code{guile-2.0} pour fournir la bonne ligne -@code{use-package-modules} ce qui peut être embêtant. On peut à la place -fournir des spécifications de paquets normales et laisser -@code{specifications->manifest} rechercher les objets de paquets -correspondants, comme ceci : - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex revenir en arrière -@cindex défaire des transactions -@cindex transactions, défaire -Revenir à la @dfn{génération} précédente du profil c.-à-d.@: défaire la -dernière transaction. - -Lorsqu'elle est combinée avec des options comme @code{--install}, cette -option revient en arrière avant toute autre action. - -Lorsque vous revenez de la première génération qui contient des fichiers, le -profil pointera vers la @dfn{zéroième génération} qui ne contient aucun -fichier en dehors de ses propres métadonnées. - -Après être revenu en arrière, l'installation, la suppression et la mise à -jour de paquets réécrit les futures générations précédentes. Ainsi, -l'historique des générations dans un profil est toujours linéaire. - -@item --switch-generation=@var{motif} -@itemx -S @var{motif} -@cindex générations -Basculer vers une génération particulière définie par le @var{motif}. - -Le @var{motif} peut être soit un numéro de génération soit un nombre précédé -de « + » ou « - ». Ce dernier signifie : se déplacer en avant ou en arrière -d'un nombre donné de générations. Par exemple, si vous voulez retourner à -la dernière génération après @code{--roll-back}, utilisez -@code{--switch-generation=+1}. - -La différence entre @code{--roll-back} et @code{--switch-generation=-1} est -que @code{--switch-generation} ne vous amènera pas à la zéroième génération, -donc si la génération demandée n'existe pas la génération actuelle ne -changera pas. - -@item --search-paths[=@var{genre}] -@cindex chemins de recherche -Rapporter les définitions des variables d'environnement dans la syntaxe Bash -qui peuvent être requises pour utiliser l'ensemble des paquets installés. -Ces variables d'environnement sont utilisées pour spécifier les @dfn{chemins -de recherche} de fichiers utilisés par les paquets installés. - -Par exemple, GCC a besoin des variables d'environnement @code{CPATH} et -@code{LIBRARY_PATH} pour trouver les en-têtes et les bibliothèques dans le -profil de l'utilisateur (@pxref{Environment Variables,,, gcc, Using the GNU -Compiler Collection (GCC)}). Si GCC et, disons, la bibliothèque C sont -installés dans le profil, alors @code{--search-paths} suggérera -d'initialiser ces variables à @code{@var{profil}/include} et -@code{@var{profil}/lib}, respectivement. - -Le cas d'utilisation typique est de définir ces variables d'environnement -dans le shell : - -@example -$ eval `guix package --search-paths` -@end example - -@var{genre} peut être l'une des valeurs @code{exact}, @code{prefix} ou -@code{suffix}, ce qui signifie que les définitions des variables -d'environnement retournées seront soit les paramètres exactes, ou placés -avant ou après la valeur actuelle de ces paramètres. Lorsqu'il est omis, -@var{genre} a pour valeur par défaut @code{exact}. - -Cette option peut aussi être utilisé pour calculer les chemins de recherche -@emph{combinés} de plusieurs profils. Regardez cet exemple : - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -La dernière commande ci-dessus montre la variable @code{GUILE_LOAD_PATH} -bien que, pris individuellement, ni @file{foo} ni @file{bar} n'auraient -donné cette recommandation. - - -@item --profile=@var{profil} -@itemx -p @var{profil} -Utiliser le @var{profil} à la place du profil par défaut de l'utilisateur. - -@cindex collisions, dans un profil -@cindex faire des collisions de paquets dans des profils -@cindex profil, collisions -@item --allow-collisions -Permettre des collisions de paquets dans le nouveau profil. À utiliser à -vos risques et périls ! - -Par défaut, @command{guix package} rapporte les @dfn{collisions} dans le -profil comme des erreurs. Les collisions ont lieu quand deux version ou -variantes d'un paquet donné se retrouvent dans le profil. - -@item --bootstrap -Utiliser le programme d'amorçage Guile pour compiler le profil. Cette -option n'est utile que pour les développeurs de la distribution. - -@end table - -En plus de ces actions, @command{guix package} supporte les options -suivantes pour demander l'état actuel d'un profil ou la disponibilité des -paquets : - -@table @option - -@item --search=@var{regexp} -@itemx -s @var{regexp} -@cindex chercher des paquets -Lister les paquets disponibles dont le nom, le synopsis ou la description -correspondent à la @var{regexp} (en étant insensible à la casse), triés par -pertinence. Afficher toutes les métadonnées des paquets correspondants au -format @code{recutils} (@pxref{Top, GNU recutils databases,, recutils, GNU -recutils manual}). - -Cela permet à des champs spécifiques d'être extraits avec la commande -@command{recsel}, par exemple : - -@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 - -De manière similaire, pour montrer le nom de tous les paquets disponibles -sous license GNU@tie{}LGPL version 3 : - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -Il est aussi possible de raffiner les résultats de la recherche avec -plusieurs options @code{-s}. Par exemple, la commande suivante renvoie la -liste des jeux de plateau : - -@example -$ guix package -s '\' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -Si on avait oublié @code{-s game}, on aurait aussi eu les paquets logiciels -qui s'occupent de circuits imprimés (en anglais : circuit board) ; supprimer -les chevrons autour de @code{board} aurait aussi ajouté les paquets qui -parlent de clavier (en anglais : key@emph{board}). - -Et maintenant un exemple plus élaboré. La commande suivante recherche les -bibliothèques cryptographiques, retire les bibliothèques Haskell, Perl, -Python et Ruby et affiche le nom et le synopsis des paquets correspondants : - -@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} pour plus -d'information sur les @dfn{expressions de sélection} pour @code{recsel -e}. - -@item --show=@var{paquet} -Afficher les détails du @var{paquet} dans la liste des paquets disponibles, -au format @code{recutils} (@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 - -Vous pouvez aussi spécifier le nom complet d'un paquet pour n'avoir que les -détails concernant une version spécifique : -@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}] -Liste les paquets actuellement installés dans le profil spécifié, avec les -paquets les plus récemment installés en dernier. Lorsque @var{regexp} est -spécifié, liste uniquement les paquets installés dont le nom correspond à -@var{regexp}. - -Pour chaque paquet installé, affiche les éléments suivants, séparés par des -tabulations : le nom du paquet, sa version, la partie du paquet qui est -installé (par exemple, @code{out} pour la sortie par défaut, @code{include} -pour ses en-têtes, etc) et le chemin du paquet dans le dépôt. - -@item --list-available[=@var{regexp}] -@itemx -A [@var{regexp}] -Lister les paquets actuellement disponibles dans la distribution pour ce -système (@pxref{Distribution GNU}). Lorsque @var{regexp} est spécifié, -liste uniquement les paquets dont le nom correspond à @var{regexp}. - -Pour chaque paquet, affiche les éléments suivants séparés par des -tabulations : son nom, sa version, les parties du paquet (@pxref{Des paquets avec plusieurs résultats}), et l'emplacement de sa définition. - -@item --list-generations[=@var{motif}] -@itemx -l [@var{motif}] -@cindex générations -Renvoyer la liste des générations avec leur date de création ; pour chaque -génération, montre les paquets installés avec les paquets installés les plus -récemment en dernier. Remarquez que la zéroième génération n'est jamais -montrée. - -Pour chaque paquet installé, afficher les éléments suivants, séparés par des -tabulations : le nom du paquet, sa version, la partie du paquet qui a été -installée (@pxref{Des paquets avec plusieurs résultats}), et l'emplacement du -paquet dans le dépôt. - -Lorsque @var{motif} est utilisé, la commande ne renvoie que les générations -correspondantes. Les motifs valides sont : - -@itemize -@item @emph{Des entiers et des entiers séparés par des virgules}. Les deux motifs correspondent -à des numéros de version. Par exemple, @code{--list-generations=1} renvoie -la première. - -Et @code{--list-generations=1,8,2} renvoie les trois générations dans -l'ordre spécifié. Aucune espace ni virgule surnuméraire n'est permise. - -@item @emph{Des intervalles}. @code{--list-generations=2..9} affiche les -générations demandées et tout ce qui se trouvent entre elles. Remarquez que -le début d'un intervalle doit être plus petit que sa fin. - -Il est aussi possible d'omettre le numéro final. Par exemple, -@code{--list-generations=2..} renvoie toutes les générations à partir de la -deuxième. - -@item @emph{Des durées}. Vous pouvez aussi récupérer les derniers @emph{N}@tie{}jours, semaines, -ou moins en passant un entier avec la première lettre de la durée (en -anglais : d, w ou m). Par exemple @code{--list-generations=20d} liste les -générations qui sont âgées d'au plus 20 jours. -@end itemize - -@item --delete-generations[=@var{motif}] -@itemx -d [@var{motif}] -Lorsque @var{motif} est omis, supprimer toutes les générations en dehors de -l'actuelle. - -Cette commande accepte les même motifs que @option{--list-generations}. -Lorsque @var{motif} est spécifié, supprimer les générations correspondante. -Lorsque @var{motif} spécifie une durée, les générations @emph{plus vieilles} -que la durée spécifiée correspondent. Par exemple -@code{--delete-generations=1m} supprime les générations vieilles de plus -d'un mois. - -Si la génération actuelle correspond, elle n'est @emph{pas} supprimée. La -zéroième génération n'est elle non plus jamais supprimée. - -Remarquez que supprimer des générations empêche de revenir en arrière vers -elles. Ainsi, cette commande doit être utilisée avec précaution. - -@end table - -Enfin, comme @command{guix package} peut démarrer des processus de -construction, elle supporte les options de construction communes -(@pxref{Options de construction communes}). Elle supporte aussi les options de -transformation de paquets comme @option{--with-source} (@pxref{Options de transformation de paquets}). Cependant, remarquez que les transformations de -paquets sont perdues à la mise à jour ; pour les préserver à travers les -mises à jours, vous devriez définir vos propres variantes des paquets dans -une module Guile et l'ajouter à @code{GUIX_PACKAGE_PATH} (@pxref{Définition des paquets}). - -@node Substituts -@section Substituts - -@cindex substituts -@cindex binaires pré-construits -Guix gère le déploiement depuis des binaires ou des sources de manière -transparente ce qui signifie qu'il peut aussi bien construire localement que -télécharger des éléments pré-construits depuis un serveur ou les deux. Nous -appelons ces éléments pré-construits des @dfn{substituts} — ils se -substituent aux résultats des constructions locales. Dans la plupart des -cas, télécharger un substitut est bien plus rapide que de construire les -choses localement. - -Les substituts peuvent être tout ce qui résulte d'une construction de -dérivation (@pxref{Dérivations}). Bien sûr dans le cas général, il s'agit -de paquets binaires pré-construits, mais les archives des sources par -exemple résultent aussi de la construction d'une dérivation qui peut aussi -être disponible en tant que substitut. - -@menu -* Serveur de substituts officiel:: Une source particulière de substituts. -* Autoriser un serveur de substituts:: Comment activer ou désactiver les - substituts. -* Authentification des substituts:: Comment Guix vérifie les substituts. -* Paramètres de serveur mandataire:: Comment récupérer des substituts à - travers un serveur mandataire. -* Échec de substitution:: Qu'arrive-t-il quand la substitution échoue. -* De la confiance en des binaires:: Comment pouvez-vous avoir confiance en - un paquet binaire ? -@end menu - -@node Serveur de substituts officiel -@subsection Serveur de substituts officiel - -@cindex hydra -@cindex ferme de construction -Le serveur @code{@value{SUBSTITUTE-SERVER}} est une interface à la ferme de -construction officielle qui construit des paquets pour Guix continuellement -pour certaines architectures et les rend disponibles en tant que -substituts. C'est la source par défaut des substituts ; elle peut être -modifiée en passant l'option @option{--substitute-urls} soit à -@command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon ---substitute-urls}}) soit aux outils clients comme @command{guix package} -(@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). - -Les URL des substituts peuvent être soit en HTTP soit en HTTPS. Le HTTPS -est recommandé parce que les communications sont chiffrées ; à l'inverse -HTTP rend les communications visibles pour un espion qui peut utiliser les -informations accumulées sur vous pour déterminer par exemple si votre -système a des vulnérabilités de sécurités non corrigées. - -Les substituts de la ferme de construction officielle sont activés par -défaut dans la distribution système Guix (@pxref{Distribution GNU}). -Cependant, ils sont désactivés par défaut lorsque vous utilisez Guix sur une -distribution externe, à moins que vous ne les ayez explicitement activés via -l'une des étapes d'installation recommandées (@pxref{Installation}). Les -paragraphes suivants décrivent comment activer ou désactiver les substituts -de la ferme de construction ; la même procédure peut être utilisée pour -activer les substituts de n'importe quel autre serveur de substituts. - -@node Autoriser un serveur de substituts -@subsection Autoriser un serveur de substituts - -@cindex sécurité -@cindex substituts, autorisations -@cindex liste de contrôle d'accès (ACL), pour les substituts -@cindex ACL (liste de contrôle d'accès), pour les substituts -Pour permettre à Guix de télécharger les substituts depuis -@code{@value{SUBSTITUTE-SERVER}} ou un miroir, vous devez ajouter sa clef -publique à la liste de contrôle d'accès (ACL) des imports d'archives, avec -la commande @command{guix archive} (@pxref{Invoquer guix archive}). Cela -implique que vous faîtes confiance à @code{@value{SUBSTITUTE-SERVER}} pour -ne pas être compromis et vous servir des substituts authentiques. - -La clef publique pour @code{@value{SUBSTITUTE-SERVER}} est installée avec -Guix, dans @code{@var{préfixe}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, où -@var{préfixe} est le préfixe d'installation de Guix. Si vous avez installé -Guix depuis les sources, assurez-vous d'avoir vérifié la signature GPG de -@file{guix-@value{VERSION}.tar.gz} qui contient ce fichier de clef -publique. Ensuite vous pouvez lancer quelque chose comme ceci : - -@example -# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Remarque -De même, le fichier @file{hydra.gnu.org.pub} contient la clef publique d'une -ferme de construction indépendante qui appartient aussi au projet, -disponible sur @indicateurl{https://mirror.hydra.gnu.org}. -@end quotation - -Une fois que cela est en place, la sortie d'une commande comme @code{guix -build} devrait changer de quelque chose comme : - -@example -$ guix build emacs --dry-run -Les dérivations suivantes seraient construites : - /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 -à quelque chose comme : - -@example -$ guix build emacs --dry-run -112.3 Mo seraient téléchargés : - /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 -Cela indique que les substituts de @code{@value{SUBSTITUTE-SERVER}} sont -utilisables et seront téléchargés, si possible, pour les futures -constructions. - -@cindex substituts, comment les désactiver -Le mécanisme de substitution peut être désactivé globalement en lançant -@code{guix-daemon} avec @code{--no-substitutes} (@pxref{Invoquer guix-daemon}). Il peut aussi être désactivé temporairement en passant -l'option @code{--no-substitutes} à @command{guix package}, @command{guix -build} et aux autres outils en ligne de commande. - -@node Authentification des substituts -@subsection Authentification des substituts - -@cindex signatures numériques -Guix détecte et lève une erreur lorsqu'il essaye d'utiliser un substituts -qui a été modifié. De même, il ignore les substituts qui ne sont pas signés -ou qui ne sont pas signés par l'une des clefs listés dans l'ACL. - -Il y a une exception cependant : si un serveur non autorisé fournit des -substituts qui sont @emph{identiques bit-à-bit} à ceux fournis par un -serveur autorisé, alors le serveur non autorisé devient disponible pour les -téléchargements. Par exemple en supposant qu'on a choisi deux serveurs de -substituts avec cette option : - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex constructions reproductibles -Si l'ACL contient uniquement la clef de @code{b.example.org}, et si -@code{a.example.org} sert @emph{exactement les mêmes} substituts, alors Guix -téléchargera les substituts de @code{a.example.org} parce qu'il vient en -premier dans la liste et peut être considéré comme un miroir de -@code{b.example.org}. En pratique, des machines de constructions produisent -souvent les mêmes binaires grâce à des construction reproductibles au bit -près (voir plus bas). - -Lorsque vous utilisez HTTPS, le certificat X.509 du serveur n'est @emph{pas} -validé (en d'autre termes, le serveur n'est pas authentifié), contrairement -à ce que des clients HTTPS comme des navigateurs web font habituellement. -Cela est dû au fait que Guix authentifie les informations sur les substituts -eux-mêmes, comme expliqué plus haut, ce dont on se soucie réellement (alors -que les certificats X.509 authentifie la relation entre nom de domaine et -clef publique). - -@node Paramètres de serveur mandataire -@subsection Paramètres de serveur mandataire - -@vindex http_proxy -Les substituts sont téléchargés par HTTP ou HTTPS. La variable -d'environnement @code{http_proxy} peut être initialisée dans l'environnement -de @command{guix-daemon} et est respectée pour le téléchargement des -substituts. Remarquez que la valeur de @code{http_proxy} dans -l'environnement où tournent @command{guix build}, @command{guix package} et -les autres clients n'a @emph{absolument aucun effet}. - -@node Échec de substitution -@subsection Échec de substitution - -Même lorsqu'un substitut pour une dérivation est disponible, la substitution -échoue parfois. Cela peut arriver pour plusieurs raisons : le serveur de -substitut peut être hors ligne, le substitut a récemment été supprimé du -serveur, la connexion peut avoir été interrompue, etc. - -Lorsque les substituts sont activés et qu'un substitut pour une dérivation -est disponible, mais que la tentative de substitution échoue, Guix essaiera -de construire la dérivation localement si @code{--fallback} a été passé en -argument (@pxref{option de repli,, common build option @code{--fallback}}). -Plus spécifiquement, si cet option n'a pas été passée en argument, alors -aucune construction locale n'est effectuée et la dérivation est considérée -comme étant en échec. Cependant, si @code{--fallback} est passé en argument, -alors Guix essaiera de construire la dérivation localement et l'échec ou le -succès de la dérivation dépend de l'échec ou du succès de la construction -locale. Remarquez que lorsque les substituts sont désactivés ou qu'aucun -substitut n'est disponible pour la dérivation en question, une construction -locale sera @emph{toujours} effectuée, indépendamment du fait que l'argument -@code{--fallback} ait été ou non passé. - -Pour se donner une idée du nombre de substituts disponibles maintenant, vous -pouvez essayer de lancer la commande @command{guix weather} (@pxref{Invoquer guix weather}). Cette command fournit des statistiques sur les substituts -fournis par un serveur. - -@node De la confiance en des binaires -@subsection De la confiance en des binaires - -@cindex confiance, en des binaires pré-construits -De nos jours, le contrôle individuel sur son utilisation propre de -l'informatique est à la merci d'institutions, de sociétés et de groupes avec -assez de pouvoir et de détermination pour contourner les infrastructures -informatiques et exploiter leurs faiblesses. Bien qu'utiliser les -substituts de @code{@value{SUBSTITUTE-SERVER}} soit pratique, nous -encourageons les utilisateurs à construire aussi par eux-mêmes, voir à faire -tourner leur propre ferme de construction, pour que -@code{@value{SUBSTITUTE-SERVER}} devienne une cible moins intéressante. Une -façon d'aider est de publier les logiciels que vous construisez avec -@command{guix publish} pour que les autres aient plus de choix de serveurs -où télécharger les substituts (@pxref{Invoquer guix publish}). - -Guix possède les fondations pour maximiser la reproductibilité logicielle -(@pxref{Fonctionnalités}). Dans la plupart des cas, des constructions -indépendantes d'un paquet donnée ou d'une dérivation devrait donner des -résultats identiques au bit près. Ainsi, à travers un ensemble de -constructions de paquets indépendantes il est possible de renforcer -l'intégrité du système. La commande @command{guix challenge} a pour but -d'aider les utilisateurs à tester les serveurs de substituts et à aider les -développeurs à trouver les constructions de paquets non-déterministes -(@pxref{Invoquer guix challenge}). De même, l'option @option{--check} de -@command{guix build} permet aux utilisateurs de vérifier si les substituts -précédemment installés sont authentiques en les reconstruisant localement -(@pxref{vérification de la construction, @command{guix build --check}}). - -Dans le futur, nous aimerions que Guix puisse publier et recevoir des -binaires d'autres utilisateurs, d'une manière pair-à-pair. Si vous voulez -discuter de ce projet, rejoignez-nous sur @email{guix-devel@@gnu.org}. - -@node Des paquets avec plusieurs résultats -@section Des paquets avec plusieurs résultats - -@cindex paquets avec plusieurs résultats -@cindex sorties de paquets -@cindex sorties - -Souvent, les paquets définis dans Guix ont une seule @dfn{sortie} — -c.-à-d.@: que le paquet source conduit à exactement un répertoire dans le -dépôt. Lorsque vous lancez @command{guix package -i glibc}, vous installez -la sortie par défaut du paquet GNU libc ; la sortie par défaut est appelée -@code{out} mais son nom peut être omis comme le montre cette commande. Dans -ce cas particuliers, la sortie par défaut de @code{glibc} contient tous les -fichiers d'en-tête C, les bibliothèques partagées, les bibliothèques -statiques, la documentation Info et les autres fichiers de support. - -Parfois il est plus approprié de séparer les divers types de fichiers -produits par un même paquet source en plusieurs sorties. Par exemple, la -bibliothèque C GLib (utilisée par GTK+ et des paquets associés) installe -plus de 20 Mo de documentation de référence dans des pages HTML. Pour -préserver l'espace disque des utilisateurs qui n'en ont pas besoin, la -documentation va dans une sortie séparée nommée @code{doc}. Pour installer -la sortie principale de GLib, qui contient tout sauf la documentation, on -devrait lancer : - -@example -guix package -i glib -@end example - -@cindex documentation -La commande pour installer la documentation est : - -@example -guix package -i glib:doc -@end example - -Certains paquets installent des programmes avec des « empreintes dépendances -» différentes. Par exemple le paquet WordNet installe à la fois les outils -en ligne de commande et les interfaces graphiques (GUI). La première ne -dépend que de la bibliothèque C, alors que cette dernière dépend de Tcl/Tk -et des bibliothèques X sous-jacentes. Dans ce cas, nous laissons les outils -en ligne de commande dans la sortie par défaut et l'interface graphique dans -une sortie séparée. Cela permet aux utilisateurs qui n'ont pas besoin -d'interface graphique de gagner de la place. La commande @command{guix -size} peut aider à trouver ces situations (@pxref{Invoquer guix size}). @command{guix graph} peut aussi être utile (@pxref{Invoquer guix graph}). - -Il y a plusieurs paquets à sorties multiples dans la distribution GNU. -D'autres noms de sorties conventionnels sont @code{lib} pour les -bibliothèques et éventuellement les fichiers d'en-tête, @code{bin} pour les -programmes indépendants et @code{debug} pour les informations de débogage -(@pxref{Installer les fichiers de débogage}). Les sorties d'un paquet sont listés -dans la troisième colonne de la sortie de @command{guix package ---list-available} (@pxref{Invoquer guix package}). - - -@node Invoquer guix gc -@section Invoquer @command{guix gc} - -@cindex ramasse-miettes -@cindex espace disque -Les paquets qui sont installés mais pas utilisés peuvent être @dfn{glanés}. -La commande @command{guix gc} permet aux utilisateurs de lancer -explicitement le ramasse-miettes pour récupérer de l'espace dans le -répertoire @file{/gnu/store}. C'est la @emph{seule} manière de supprimer -des fichiers de @file{/gnu/store} — supprimer des fichiers ou des -répertoires à la main peut le casser de manière impossible à réparer ! - -@cindex racines du GC -@cindex racines du ramasse-miettes -Le ramasse-miettes a un ensemble de @dfn{racines} connues : tout fichier -dans @file{/gnu/store} atteignable depuis une racine est considéré comme -@dfn{utilisé} et ne peut pas être supprimé ; tous les autres fichiers sont -considérés comme @dfn{inutilisés} et peuvent être supprimés. L'ensemble des -racines du ramasse-miettes (ou « racines du GC » pour faire court) inclue -les profils par défaut des utilisateurs ; par défaut les liens symboliques -sous @file{/var/guix/gcroots} représentent ces racines du GC. De nouvelles -racines du GC peuvent être ajoutées avec la @command{guix build -- root} par -exemple (@pxref{Invoquer guix build}). La commande @command{guix gc ---list-roots} permet de les lister. - -Avant de lancer @code{guix gc --collect-garbage} pour faire de la place, -c'est souvent utile de supprimer les anciennes génération des profils -utilisateurs ; de cette façon les anciennes constructions de paquets -référencées par ces générations peuvent être glanées. Cela se fait en -lançant @code{guix package --delete-generations} (@pxref{Invoquer guix package}). - -Nous recommandons de lancer le ramasse-miettes régulièrement ou lorsque vous -avez besoin d'espace disque. Par exemple pour garantir qu'au moins -5@tie{}Go d'espace reste libre sur votre disque, lancez simplement : - -@example -guix gc -F 5G -@end example - -Il est parfaitement possible de le lancer comme une tâche périodique -non-interactive (@pxref{Exécution de tâches planifiées} pour apprendre comment -paramétrer une telle tâche). Lancer @command{guix gc} sans argument -ramassera autant de miettes que possible mais ça n'est pas le plus pratique -: vous pourriez vous retrouver à reconstruire ou re-télécharger des -logiciels « inutilisés » du point de vu du GC mais qui sont nécessaires pour -construire d'autres logiciels — p.@: ex.@: la chaîne de compilation. - -La command @command{guix gc} a trois modes d'opération : il peut être -utilisé pour glaner des fichiers inutilisés (par défaut), pour supprimer des -fichiers spécifiques (l'option @code{--delete}), pour afficher des -informations sur le ramasse-miettes ou pour des requêtes plus avancées. Les -options du ramasse-miettes sont : - -@table @code -@item --collect-garbage[=@var{min}] -@itemx -C [@var{min}] -Ramasse les miettes — c.-à-d.@: les fichiers inaccessibles de -@file{/gnu/store} et ses sous-répertoires. C'est l'opération par défaut -lorsqu'aucune option n'est spécifiée. - -Lorsque @var{min} est donné, s'arrêter une fois que @var{min} octets ont été -collectés. @var{min} pour être un nombre d'octets ou inclure un suffixe -d'unité, comme @code{MiB} pour mébioctet et @code{GB} pour gigaoctet -(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}). - -Lorsque @var{min} est omis, tout glaner. - -@item --free-space=@var{libre} -@itemx -F @var{libre} -Glaner jusqu'à ce que @var{libre} espace soit disponible dans -@file{/gnu/store} si possible ; @var{libre} est une quantité de stockage -comme @code{500MiB} comme décrit ci-dessus. - -Lorsque @var{libre} ou plus est disponible dans @file{/gnu/store} ne rien -faire et s'arrêter immédiatement. - -@item --delete-generations[=@var{durée}] -@itemx -d [@var{durée}] -Avant de commencer le glanage, supprimer toutes les générations plus vielles -que @var{durée}, pour tous les profils utilisateurs ; lorsque cela est lancé -en root, cela s'applique à tous les profils @emph{de tous les utilisateurs}. - -Par exemple, cette commande supprime toutes les générations de tous vos -profils plus vieilles que 2 mois (sauf s'il s'agit de la génération -actuelle) puis libère de l'espace jusqu'à atteindre au moins 10 Go d'espace -libre : - -@example -guix gc -d 2m -F 10G -@end example - -@item --delete -@itemx -D -Essayer de supprimer tous les fichiers et les répertoires du dépôt spécifiés -en argument. Cela échoue si certains des fichiers ne sont pas dans le dépôt -ou s'ils sont toujours utilisés. - -@item --list-failures -Lister les éléments du dépôt qui correspondent à des échecs de construction. - -Cela n'affiche rien à moins que le démon n'ait été démarré avec -@option{--cache-failures} (@pxref{Invoquer guix-daemon, -@option{--cache-failures}}). - -@item --list-roots -Lister les racines du GC appartenant à l'utilisateur ; lorsque la commande -est lancée en root, lister @emph{toutes} les racines du GC. - -@item --clear-failures -Supprimer les éléments du dépôt spécifiés du cache des constructions -échouées. - -De nouveau, cette option ne fait de sens que lorsque le démon est démarré -avec @option{--cache-failures}. Autrement elle ne fait rien. - -@item --list-dead -Montrer la liste des fichiers et des répertoires inutilisés encore présents -dans le dépôt — c.-à-d.@: les fichiers et les répertoires qui ne sont plus -atteignables par aucune racine. - -@item --list-live -Montrer la liste des fichiers et des répertoires du dépôt utilisés. - -@end table - -En plus, les références entre les fichiers existants du dépôt peuvent être -demandés : - -@table @code - -@item --references -@itemx --referrers -@cindex dépendances des paquets -Lister les références (respectivement les référents) des fichiers du dépôt -en argument. - -@item --requisites -@itemx -R -@cindex closure -Lister les prérequis des fichiers du dépôt passés en argument. Les -prérequis sont le fichier du dépôt lui-même, leur références et les -références de ces références, récursivement. En d'autre termes, la liste -retournée est la @dfn{closure transitive} des fichiers du dépôt. - -@xref{Invoquer guix size} pour un outil pour surveiller la taille de la -closure d'un élément. @xref{Invoquer guix graph} pour un outil pour -visualiser le graphe des références. - -@item --derivers -@cindex dérivation -Renvoie les dérivations menant aux éléments du dépôt donnés -(@pxref{Dérivations}). - -Par exemple cette commande : - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -renvoie les fichiers @file{.drv} menant au paquet @code{emacs} installé dans -votre profil. - -Remarquez qu'il peut n'y avoir aucun fichier @file{.drv} par exemple quand -ces fichiers ont été glanés. Il peut aussi y avoir plus d'un fichier -@file{.drv} correspondant à cause de dérivations à sortie fixées. -@end table - -Enfin, les options suivantes vous permettent de vérifier l'intégrité du -dépôt et de contrôler l'utilisation du disque. - -@table @option - -@item --verify[=@var{options}] -@cindex intégrité, du dépôt -@cindex vérification d'intégrité -Vérifier l'intégrité du dépôt. - -Par défaut, s'assurer que tous les éléments du dépôt marqués comme valides -dans la base de données du démon existent bien dans @file{/gnu/store}. - -Lorsqu'elle est fournie, l'@var{option} doit être une liste séparée par des -virgule de l'un ou plus parmi @code{contents} et @code{repair}. - -Lorsque vous passez @option{--verify=contents}, le démon calcul le hash du -contenu de chaque élément du dépôt et le compare au hash de sa base de -données. Les différences de hash sont rapportées comme des corruptions de -données. Comme elle traverse @emph{tous les fichiers du dépôt}, cette -commande peut prendre très longtemps pour terminer, surtout sur un système -avec un disque lent. - -@cindex réparer le dépôt -@cindex corruption, récupérer de -Utiliser @option{--verify=repair} ou @option{--verify=contents,repair} fait -que le démon essaie de réparer les objets du dépôt corrompus en récupérant -leurs substituts (@pxref{Substituts}). Comme la réparation n'est pas -atomique et donc potentiellement dangereuse, elle n'est disponible que pour -l'administrateur système. Une alternative plus légère lorsque vous -connaissez exactement quelle entrée est corrompue consiste à lancer -@command{guix build --repair} (@pxref{Invoquer guix build}). - -@item --optimize -@cindex déduplication -Optimiser le dépôt en liant en dur les fichiers identiques — c'est la -@dfn{déduplication}. - -Le démon effectue une déduplication à chaque construction réussie ou import -d'archive à moins qu'il n'ait été démarré avec -@code{--disable-deduplication} (@pxref{Invoquer guix-daemon, -@code{--disable-deduplication}}). Ainsi, cette option est surtout utile -lorsque le démon tourne avec @code{--disable-deduplication}. - -@end table - -@node Invoquer guix pull -@section Invoquer @command{guix pull} - -@cindex mettre à niveau Guix -@cindex mettre à jour Guix -@cindex @command{guix pull} -@cindex pull -Les paquets sont installés ou mis à jour vers la dernière version disponible -dans la distribution actuellement disponible sur votre machine locale. Pour -mettre à jour cette distribution, en même temps que les outils Guix, vous -devez lancer @command{guix pull} ; la commande télécharge le dernier code -source de Guix et des descriptions de paquets et le déploie. Le code source -est téléchargé depuis un dépôt @uref{https://git-scm.com, Git}, par défaut -le dépôt officiel de GNU@tie{}Guix, bien que cela puisse être personnalisé. - -À la fin, @command{guix package} utilisera les paquets et les versions des -paquets de la copie de Guix tout juste récupérée. Non seulement ça, mais -toutes les commandes Guix et les modules Scheme seront aussi récupérés -depuis la dernière version. Les nouvelles sous-commandes de @command{guix} -ajoutés par la mise à jour sont aussi maintenant disponibles. - -Chaque utilisateur peut mettre à jour sa copie de Guix avec @command{guix -pull} et l'effet est limité à l'utilisateur qui a lancé @command{guix -pull}. Par exemple, lorsque l'utilisateur @code{root} lance @command{guix -pull}, cela n'a pas d'effet sur la version de Guix que vois @code{alice} et -vice-versa. - -Le résultat après avoir lancé @command{guix pull} est un @dfn{profil} -disponible sous @file{~/.config/guix/current} contenant la dernière version -de Guix. Ainsi, assurez-vous de l'ajouter au début de votre chemin de -recherche pour que vous utilisiez la dernière version. Le même conseil -s'applique au manuel Info (@pxref{Documentation}) : - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -L'option @code{--list-generations} ou @code{-l} liste les anciennes -générations produites par @command{guix pull}, avec des détails sur leur -origine : - -@example -$ guix pull -l -Génération 1 10 juin 2018 00:18:18 - guix 65956ad - URL du dépôt : https://git.savannah.gnu.org/git/guix.git - branche : origin/master - commit : 65956ad3526ba09e1f7a40722c96c6ef7c0936fe - -Génération 2 11 juin 2018 11:02:49 - guix e0cc7f6 - URL du dépôt : https://git.savannah.gnu.org/git/guix.git - branche : origin/master - commit : e0cc7f669bec22c37481dd03a7941c7d11a64f1d - 2 nouveaux paquets : keepalived, libnfnetlink - 6 paquets mis à jour : 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 - -Génération 3 13 juin 2018 23:31:07 (actuelle) - guix 844cc1c - URL du dépôt : https://git.savannah.gnu.org/git/guix.git - branche : origin/master - commit : 844cc1c8f394f03b404c5bb3aee086922373490c - 28 nouveaux paquets : emacs-helm-ls-git, emacs-helm-mu, @dots{} - 69 paquets mis à jour : borg@@1.1.6, cheese@@3.28.0, @dots{} -@end example - -@xref{Invoquer guix describe, @command{guix describe}}, pour d'autres -manières de décrire le statut actuel de Guix. - -Ce profil @code{~/.config/guix/current} fonctionne comme les autres profils -créés par @command{guix package} (@pxref{Invoquer guix package}). -C'est-à-dire que vous pouvez lister les générations, revenir en arrière à -une génération précédente — c.-à-d.@: la version de Guix précédente — etc : - -@example -$ guix package -p ~/.config/guix/current --roll-back -passé de la génération 3 à 2 -$ guix package -p ~/.config/guix/current --delete-generations=1 -suppression de /var/guix/profiles/per-user/charlie/current-guix-1-link -@end example - -La commande @command{guix pull} est typiquement invoquée sans arguments mais -il supporte les options suivantes : - -@table @code -@item --url=@var{url} -@itemx --commit=@var{commit} -@itemx --branch=@var{branche} -Download code for the @code{guix} channel from the specified @var{url}, at -the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@cindex @file{channels.scm}, fichier de configuration -@cindex fichier de configuration pour les canaux -Ces options sont fournies pour votre confort, mais vous pouvez aussi -spécifier votre configuration dans le fichier -@file{~/.config/guix/channels.scm} ou en utilisant l'option -@option{--channels} (voir plus bas). - -@item --channels=@var{file} -@itemx -C @var{file} -Lit la liste des canaux dans @var{file} plutôt que dans -@file{~/.config/guix/channels.scm}. @var{file} doit contenir un code Scheme -qui s'évalue en une liste d'objets de canaux. @xref{Canaux} pour plus -d'informations. - -@item --list-generations[=@var{motif}] -@itemx -l [@var{motif}] -Liste toutes les générations de @file{~/.config/guix/current} ou, si -@var{motif} est fournit, le sous-ensemble des générations qui correspondent -à @var{motif}. La syntaxe de @var{motif} est la même qu'avec @code{guix -package --list-generations} (@pxref{Invoquer guix package}). - -@xref{Invoquer guix describe}, pour une manière d'afficher des informations -sur la génération actuelle uniquement. - -@item --profile=@var{profil} -@itemx -p @var{profil} -Utiliser le @var{profil} à la place de @file{~/.config/guix/current}. - -@item --dry-run -@itemx -n -Montrer quels commits des canaux seraient utilisés et ce qui serait -construit ou substitué mais ne pas le faire vraiment. - -@item --system=@var{système} -@itemx -s @var{système} -Tenter de construire pour le @var{système} — p.@: ex.@: @code{i686-linux} — -plutôt que pour le type de système de l'hôte de construction. - -@item --verbose -Produire une sortie verbeuse, en écrivant les journaux de construction sur -la sortie d'erreur standard. - -@item --bootstrap -Utiliser le programme d'amorçage Guile pour construire la dernière version -de Guix. Cette option n'est utile que pour les développeurs de Guix. -@end table - -Le mécanisme de @dfn{canaux} vous permet de dire à @command{guix pull} quels -répertoires et branches récupérer, ainsi que les dépôts -@emph{supplémentaires} contenant des modules de paquets qui devraient être -déployés. @xref{Canaux} pour plus d'information. - -En plus, @command{guix pull} supporte toutes les options de construction -communes (@pxref{Options de construction communes}). - -@node Canaux -@section Canaux - -@cindex canaux -@cindex @file{channels.scm}, fichier de configuration -@cindex fichier de configuration pour les canaux -@cindex @command{guix pull}, fichier de configuration -@cindex configuration de @command{guix pull} -Guix et sa collection de paquets sont mis à jour en lançant @command{guix -pull} (@pxref{Invoquer guix pull}). Par défaut @command{guix pull} -télécharge et déploie Guix lui-même depuis le dépôt officiel de -GNU@tie{}Guix. Cela peut être personnalisé en définissant des @dfn{canaux} -dans le fichier @file{~/.config/guix/channels.scm}. Un canal spécifie l'URL -et la branche d'un répertoire Git à déployer et on peut demander à -@command{guix pull} de récupérer un ou plusieurs canaux. En d'autres -termes, les canaux peuvent être utilisés pour personnaliser et pour -@emph{étendre} Guix, comme on le verra plus bas. - -@subsection Utiliser un canal Guix personnalisé - -Le canal nommé @code{guix} spécifie où Guix lui-même — ses outils en ligne -de commande ainsi que sa collection de paquets — sera téléchargé. Par -exemple, supposons que vous voulez effectuer les mises à jour depuis votre -propre copie du dépôt Guix sur @code{example.org}, et plus particulièrement -depuis la branche @code{super-hacks}. Vous pouvez écrire cette -spécification dans @code{~/.config/guix/channels.scm} : - -@lisp -;; Dit à « guix pull » d'utiliser mon propre dépôt. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -Maintenant, @command{guix pull} récupérera le code depuis la branche -@code{super-hacks} du dépôt sur @code{example.org}. - -@subsection Spécifier des canaux supplémentaires - -@cindex étendre la collection de paquets (canaux) -@cindex paquets personnels (canaux) -@cindex canaux, pour des paquets personnels -Vous pouvez aussi spécifier des @emph{canaux supplémentaires} à récupérer. -Disons que vous avez un ensemble de paquets personnels ou de variantes -personnalisées qu'il ne vaudrait pas le coup de contribuer au projet Guix, -mais que vous voudriez pouvoir utiliser de manière transparente sur la ligne -de commande. Vous écririez d'abord des modules contenant ces définitions de -paquets (@pxref{Modules de paquets}), en les maintenant dans un dépôt Git, puis -vous ou n'importe qui d'autre pourrait l'utiliser comme un canal -supplémentaire où trouver ces paquets. Sympa, non ? - -@c What follows stems from discussions at -@c as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Attention -Avant que vous, cher utilisateur, ne vous exclamiez « Oh mais c'est -@emph{super génial} ! » et que vous ne publiez vos canaux personnels -publiquement, nous voudrions vous donner quelques avertissements : - -@itemize -@item -Avant de publier un canal, envisagez de contribuer vos définitions de -paquets dans Guix (@pxref{Contribuer}). Guix en tant que projet est -ouvert à tous les logiciels libres de toutes sortes, et les paquets dans -Guix sont déjà disponibles à tous les utilisateurs de Guix et bénéficient -des processus d'assurance qualité du projet. - -@item -Lorsque vous maintenez des définitions de paquets en dehors de Guix, nous, -les développeurs de Guix, considérons que @emph{la charge de la -compatibilité vous incombe}. Rappelez-vous que les modules de paquets et -les définitions de paquets ne sont que du code Scheme qui utilise diverses -interfaces de programmation (API). Nous souhaitons rester libres de changer -ces API pour continuer à améliorer Guix, éventuellement d'une manière qui -casse votre canal. Nous ne changeons jamais l'API gratuitement, mais nous -ne nous engageons @emph{pas} à geler les API non plus. - -@item -Corollaire : si vous utilisez un canal externe et que le canal est cassé, -merci de @emph{rapporter le problème à l'auteur du canal}, pas au projet -Guix. -@end itemize - -Vous avez été prévenus ! Maintenant, nous pensons que des canaux externes -sont une manière pratique d'exercer votre liberté pour augmenter la -collection de paquets de Guix et de partager vos améliorations, qui sont les -principes de bases du @uref{https://www.gnu.org/philosophy/free-sw.html, -logiciel libre}. Contactez-nous par courriel sur -@email{guix-devel@@gnu.org} si vous souhaitez discuter à ce propos. -@end quotation - -Pour utiliser un canal, écrivez dans @code{~/.config/guix/channels.scm} pour -dire à @command{guix pull} de récupérer votre canal personnel @emph{en plus} -des canaux par défaut de Guix : - -@vindex %default-channels -@lisp -;; Ajouter mes paquets personnels à ceux fournis par Guix. -(cons (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git")) - %default-channels) -@end lisp - -@noindent -Remarquez que le bout de code au-dessus est (comme toujours !)@: du code -Scheme ; nous utilisons @code{cons} pour ajouter un canal à la liste des -canaux que la variable @code{%default-channels} représente (@pxref{Pairs, -@code{cons} and lists,, guile, GNU Guile Reference Manual}). Avec ce -fichier en place, @command{guix pull} construit non seulement Guix mais -aussi les modules de paquets de votre propre dépôt. Le résultat dans -@file{~/.config/guix/current} est l'union de Guix et de vos propres modules -de paquets : - -@example -$ guix pull --list-generations -@dots{} -Génération 19 Aug 27 2018 16:20:48 - guix d894ab8 - URL du dépôt : https://git.savannah.gnu.org/git/guix.git - branche : master - commit : d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 - my-personal-packages dd3df5e - URL du dépôt : https://example.org/personal-packages.git - branche : master - commit : dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 nouveaux paquets : my-gimp, my-emacs-with-cool-features, @dots{} - 4 paquets mis à jour : emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -La sortie de @command{guix pull} ci-dessus montre que la génération@tie{}19 -contient aussi bien Guix que les paquets du canal -@code{my-personal-packages}. Parmi les nouveaux paquets et les paquets mis -à jour qui sont listés, certains comme @code{my-gimp} et -@code{my-emacs-with-cool-features} peuvent provenir de -@code{my-personal-packages}, tandis que d'autres viennent du canal par -défaut de Guix. - -Pour créer un canal, créez un dépôt Git contenant vos propres modules de -paquets et rendez-le disponible. Le dépôt peut contenir tout ce que vous -voulez, mais un canal utile contiendra des modules Guile qui exportent des -paquets. Une fois que vous avez démarré un canal, Guix se comportera comme -si le répertoire de la racine du dépôt Git de ce canal était ajouté au -chemin de chargement de Guile (@pxref{Load Paths,,, guile, GNU Guile -Reference Manual}). Par exemple, si votre canal contient un fichier -@file{mes-paquets/mes-outils.scm} qui définit un module Guile, le module -sera disponible sous le nom de @code{(mes-paquets mes-outils)} et vous -pourrez l'utiliser comme les autres modules (@pxref{Modules,,, guile, GNU -Guile Reference Manual}). - -@cindex dépendances, canaux -@cindex métadonnées, canaux -@subsection Déclarer des dépendances de canaux - -Les auteurs de canaux peuvent décider d'augmenter une collection de paquets -fournie par d'autres canaux. Ils peuvent déclarer leur canal comme -dépendant d'autres canaux dans le fichier de métadonnées -@file{.guix-channel} qui doit être placé à la racine de dépôt du canal. - -Le fichier de métadonnées devrait contenir une S-expression simple comme -cela : - -@lisp -(channel - (version 0) - (dependencies - (channel - (name une-collection) - (url "https://exemple.org/premiere-collection.git")) - (channel - (name some-autre-collection) - (url "https://exemple.org/deuxieme-collection.git") - (branch "testing")))) -@end lisp - -Dans l'exemple ci-dessus, ce canal est déclaré comme dépendant de deux -autres canaux, qui seront récupérés automatiquement. Les modules fournis -par le canal seront compilés dans un environnement où les modules de tous -les canaux déclarés sont disponibles. - -Pour des raisons de fiabilité et de maintenabilité, vous devriez éviter -d'avoir des dépendances sur des canaux que vous ne maîtrisez pas et vous -devriez ajouter le minimum de dépendances possible. - -@subsection Répliquer Guix - -@cindex épinglage, canaux -@cindex répliquer Guix -@cindex reproductibilité, de Guix -La sortie de @command{guix pull --list-generations} ci-dessus montre -précisément quels commits ont été utilisés pour construire cette instance de -Guix. Nous pouvons donc la répliquer, disons sur une autre machine, en -fournissant une spécification de canal dans -@file{~/.config/guix/channels.scm} qui est « épinglé » à ces commits : - -@lisp -;; Déployer des commits précis de mes canaux préférés. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -La commande @command{guix describe --format=channels} peut même générer -cette liste de canaux directement (@pxref{Invoquer guix describe}). - -À ce moment les deux machines font tourner @emph{exactement le même Guix}, -avec l'accès @emph{exactement aux même paquets}. La sortie de @command{guix -build gimp} sur une machine sera exactement la même, au bit près, que la -sortie de la même commande sur l'autre machine. Cela signifie aussi que les -deux machines ont accès à tous les codes sources de Guix, et transitivement, -à tous les codes sources de tous les paquets qu'il définit. - -Cela vous donne des super-pouvoirs, ce qui vous permet de suivre la -provenance des artefacts binaires avec un grain très fin et de reproduire -les environnements logiciels à volonté — une sorte de capacité de « -méta-reproductibilité », si vous voulez. @xref{Inférieurs}, pour une autre -manière d'utiliser ces super-pouvoirs. - -@node Inférieurs -@section Inférieurs - -@c TODO: Remove this once we're more confident about API stability. -@quotation Remarque -La fonctionnalité décrite ici est un « démonstrateur technique » à la -version @value{VERSION}. Ainsi, l'interface est sujette à changements. -@end quotation - -@cindex inférieurs -@cindex composition de révisions de Guix -Parfois vous pourriez avoir à mélanger des paquets de votre révision de Guix -avec des paquets disponibles dans une révision différente de Guix. Les -@dfn{inférieurs} de Guix vous permettent d'accomplir cette tâche en -composant différentes versions de Guix de manière arbitraire. - -@cindex paquets inférieurs -Techniquement, un « inférieur » est surtout un processus Guix séparé -connecté à votre processus Guix principal à travers un REPL (@pxref{Invoquer guix repl}). Le module @code{(guix inferior)} vous permet de créer des -inférieurs et de communiquer avec eux. Il fournit aussi une interface de -haut-niveau pour naviguer dans les paquets d'un inférieur — @dfn{des paquets -inférieurs} — et les manipuler. - -Lorsqu'on les combine avec des canaux (@pxref{Canaux}), les inférieurs -fournissent une manière simple d'interagir avec un révision de Guix -séparée. Par exemple, disons que vous souhaitiez installer dans votre -profil le paquet guile actuel, avec le @code{guile-json} d'une ancienne -révision de Guix — peut-être parce que la nouvelle version de -@code{guile-json} a une API incompatible et que vous voulez lancer du code -avec l'ancienne API. Pour cela, vous pourriez écrire un manifeste à -utiliser avec @code{guix package --manifest} (@pxref{Invoquer guix package}) -; dans ce manifeste, vous créeriez un inférieur pour l'ancienne révision de -Guix qui vous intéresse et vous chercheriez le paquet @code{guile-json} dans -l'inférieur : - -@lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;pour « first » - -(define channels - ;; L'ancienne révision depuis laquelle on veut - ;; extraire guile-json. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) - -(define inferior - ;; Un inférieur représentant la révision ci-dessus. - (inferior-for-channels channels)) - -;; Maintenant on crée un manifeste avec le paquet « guile » actuel -;; et l'ancien paquet « guile-json ». -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) -@end lisp - -Durant la première exécution, @command{guix package --manifest} pourrait -avoir besoin de construire le canal que vous avez spécifié avant de créer -l'inférieur ; les exécutions suivantes seront bien plus rapides parce que la -révision de Guix sera déjà en cache. - -Le module @code{(guix inferior)} fournit les procédures suivantes pour -ouvrir un inférieur : - -@deffn {Procédure Scheme} inferior-for-channels @var{channels} @ - [#:cache-directory] [#:ttl] -Renvoie un inférieur pour @var{channels}, une liste de canaux. Elle utilise -le cache dans @var{cache-directory}, où les entrées peuvent être glanées -après @var{ttl} secondes. Cette procédure ouvre une nouvelle connexion au -démon de construction. - -Elle a pour effet de bord de construire ou de substituer des binaires pour -@var{channels}, ce qui peut prendre du temps. -@end deffn - -@deffn {Procédure Scheme} open-inferior @var{directory} @ - [#:command "bin/guix"] -Ouvre le Guix inférieur dans @var{directory} et lance -@code{@var{directory}/@var{command} repl} ou équivalent. Renvoie @code{#f} -si l'inférieur n'a pas pu être lancé. -@end deffn - -@cindex paquets inférieurs -Les procédures listées plus bas vous permettent d'obtenir et de manipuler -des paquets inférieurs. - -@deffn {Procédure Scheme} inferior-packages @var{inferior} -Renvoie la liste des paquets connus de l'inférieur @var{inferior}. -@end deffn - -@deffn {Procédure Scheme} lookup-inferior-packages @var{inferior} @var{name} @ - [@var{version}] -Renvoie la liste triée des paquets inférieurs qui correspondent à @var{name} -dans @var{inferior}, avec le plus haut numéro de version en premier. Si -@var{version} est vrai, renvoie seulement les paquets avec un numéro de -version préfixé par @var{version}. -@end deffn - -@deffn {Procédure Scheme} inferior-package? @var{obj} -Renvoie vrai si @var{obj} est un paquet inférieur. -@end deffn - -@deffn {Procédure Scheme} inferior-package-name @var{package} -@deffnx {Procédure Scheme} inferior-package-version @var{package} -@deffnx {Procédure Scheme} inferior-package-synopsis @var{package} -@deffnx {Procédure Scheme} inferior-package-description @var{package} -@deffnx {Procédure Scheme} inferior-package-home-page @var{package} -@deffnx {Procédure Scheme} inferior-package-location @var{package} -@deffnx {Procédure Scheme} inferior-package-inputs @var{package} -@deffnx {Procédure Scheme} inferior-package-native-inputs @var{package} -@deffnx {Procédure Scheme} inferior-package-propagated-inputs @var{package} -@deffnx {Procédure Scheme} inferior-package-transitive-propagated-inputs @var{package} -@deffnx {Procédure Scheme} inferior-package-native-search-paths @var{package} -@deffnx {Procédure Scheme} inferior-package-transitive-native-search-paths @var{package} -@deffnx {Procédure Scheme} inferior-package-search-paths @var{package} -Ces procédures sont la contrepartie des accesseurs des enregistrements de -paquets (@pxref{Référence des paquets}). La plupart fonctionne en effectuant -des requêtes à l'inférieur dont provient @var{package}, donc l'inférieur -doit toujours être disponible lorsque vous appelez ces procédures. -@end deffn - -Les paquets inférieurs peuvent être utilisés de manière transparente comme -tout autre paquet ou objet simili-fichier dans des G-expressions -(@pxref{G-Expressions}). Ils sont aussi gérés de manière transparente par -la procédure @code{packages->manifest}, qui est typiquement utilisée dans -des manifestes (@pxref{Invoquer guix package, l'option @option{--manifest} -de @command{guix package}}). Ainsi, vous pouvez insérer un paquet inférieur -à peu près n'importe où vous utiliseriez un paquet normal : dans des -manifestes, dans le champ @code{packages} de votre déclaration -@code{operating-system}, etc. - -@node Invoquer guix describe -@section Invoquer @command{guix describe} - -@cindex reproductibilité -@cindex répliquer Guix -Souvent vous voudrez répondre à des questions comme « quelle révision de -Guix j'utilise ? » ou « quels canaux est-ce que j'utilise ? ». C'est une -information utile dans de nombreuses situations : si vous voulez -@emph{répliquer} un environnement sur une machine différente ou un compte -utilisateur, si vous voulez rapporter un bogue ou pour déterminer quel -changement dans les canaux que vous utilisez l'a causé ou si vous voulez -enregistrer l'état de votre système pour le reproduire. La commande -@command{guix describe} répond à ces questions. - -Lorsqu'elle est lancée depuis un @command{guix} mis à jour avec -@command{guix pull}, @command{guix describe} affiche les canaux qui ont été -construits, avec l'URL de leur dépôt et l'ID de leur commit -(@pxref{Canaux}) : - -@example -$ guix describe -Generation 10 03 sep. 2018 17:32:44 (actuelle) - guix e0fa68c - URL du dépôt : https://git.savannah.gnu.org/git/guix.git - branche : master - commit : e0fa68c7718fffd33d81af415279d6ddb518f727 -@end example - -Si vous connaissez bien le système de contrôle de version Git, cela -ressemble en essence à @command{git describe} ; la sortie est aussi -similaire à celle de @command{guix pull --list-generations}, mais limitée à -la génération actuelle (@pxref{Invoquer guix pull, l'option -@option{--list-generations}}). Comme l'ID de commit de Git ci-dessus se -réfère sans aucune ambiguïté à un instantané de Guix, cette information est -tout ce dont vous avez besoin pour décrire la révision de Guix que vous -utilisez et pour la répliquer. - -Pour rendre plus facile la réplication de Guix, @command{guix describe} peut -aussi renvoyer une liste de canaux plutôt que la description lisible par un -humain au-dessus : - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -Vous pouvez sauvegarder ceci dans un fichier et le donner à @command{guix -pull -C} sur une autre machine ou plus tard, ce qui instantiera -@emph{exactement la même révision de Guix} (@pxref{Invoquer guix pull, -l'option @option{-C}}). À partir de là, comme vous pouvez déployer la même -révision de Guix, vous pouvez aussi bien @emph{répliquer un environnement -logiciel complet}. Nous pensons humblement que c'est @emph{génial}, et nous -espérons que vous aimerez ça aussi ! - -Voici les détails des options supportées par @command{guix describe} : - -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produire la sortie dans le @var{format} donné, parmi : - -@table @code -@item human -produire une sortie lisible par un humain, -@item canaux -produire une liste de spécifications de canaux qui peut être passée à -@command{guix pull -C} ou installée dans @file{~/.config/guix/channels.scm} -(@pxref{Invoquer guix pull}), -@item json -@cindex JSON -produire une liste de spécifications de canaux dans le format JSON, -@item recutils -produire une liste de spécifications de canaux dans le format Recutils. -@end table - -@item --profile=@var{profil} -@itemx -p @var{profil} -Afficher les informations sur le @var{profil}. -@end table - -@node Invoquer guix archive -@section Invoquer @command{guix archive} - -@cindex @command{guix archive} -@cindex archive -La commande @command{guix archive} permet aux utilisateurs d'@dfn{exporter} -des fichiers du dépôt dans une simple archive puis ensuite de les -@dfn{importer} sur une machine qui fait tourner Guix. En particulier, elle -permet de transférer des fichiers du dépôt d'une machine vers le dépôt d'une -autre machine. - -@quotation Remarque -Si vous chercher une manière de produire des archives dans un format adapté -pour des outils autres que Guix, @pxref{Invoquer guix pack}. -@end quotation - -@cindex exporter des éléments du dépôt -Pour exporter des fichiers du dépôt comme une archive sur la sortie -standard, lancez : - -@example -guix archive --export @var{options} @var{spécifications}... -@end example - -@var{spécifications} peut être soit des noms de fichiers soit des -spécifications de paquets, comme pour @command{guix package} -(@pxref{Invoquer guix package}). Par exemple, la commande suivante crée une -archive contenant la sortie @code{gui} du paquet @code{git} et la sortie -principale de @code{emacs} : - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar -@end example - -Si les paquets spécifiés ne sont pas déjà construits, @command{guix archive} -les construit automatiquement. Le processus de construction peut être -contrôlé avec les options de construction communes (@pxref{Options de construction communes}). - -Pour transférer le paquet @code{emacs} vers une machine connectée en SSH, on -pourrait lancer : - -@example -guix archive --export -r emacs | ssh la-machine guix archive --import -@end example - -@noindent -De même, on peut transférer un profil utilisateur complet d'une machine à -une autre comme cela : - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh la-machine guix-archive --import -@end example - -@noindent -Cependant, remarquez que, dans les deux exemples, le paquet @code{emacs}, le -profil ainsi que toutes leurs dépendances sont transférées (à cause de -@code{-r}), indépendamment du fait qu'ils soient disponibles dans le dépôt -de la machine cible. L'option @code{--missing} peut vous aider à comprendre -les éléments qui manquent dans le dépôt de la machine cible. La commande -@command{guix copy} simplifie et optimise ce processus, c'est donc ce que -vous devriez utiliser dans ce cas (@pxref{Invoquer guix copy}). - -@cindex nar, format d'archive -@cindex archive normalisée (nar) -Les archives sont stockées au format « archive normalisé » ou « nar », qui -est comparable dans l'esprit à « tar » mais avec des différences qui le -rendent utilisable pour ce qu'on veut faire. Tout d'abord, au lieu de -stocker toutes les métadonnées Unix de chaque fichier, le format nar ne -mentionne que le type de fichier (normal, répertoire ou lien symbolique) ; -les permissions Unix, le groupe et l'utilisateur ne sont pas mentionnés. -Ensuite, l'ordre dans lequel les entrées de répertoires sont stockés suit -toujours l'ordre des noms de fichier dans l'environnement linguistique C. -Cela rend la production des archives entièrement déterministe. - -@c FIXME: Add xref to daemon doc about signatures. -Lors de l'export, le démon signe numériquement le contenu de l'archive et -cette signature est ajoutée à la fin du fichier. Lors de l'import, le démon -vérifie la signature et rejette l'import en cas de signature invalide ou si -la clef de signature n'est pas autorisée. - -Les principales options sont : - -@table @code -@item --export -Exporter les fichiers ou les paquets du dépôt (voir plus bas). Écrire -l'archive résultante sur la sortie standard. - -Les dépendances ne sont @emph{pas} incluses dans la sortie à moins que -@code{--recursive} ne soit passé. - -@item -r -@itemx --recursive -En combinaison avec @code{--export}, cette option demande à @command{guix -archive} d'inclure les dépendances des éléments donnés dans l'archive. -Ainsi, l'archive résultante est autonome : elle contient la closure des -éléments du dépôt exportés. - -@item --import -Lire une archive depuis l'entrée standard et importer les fichiers inclus -dans le dépôt. Annuler si l'archive a une signature invalide ou si elle est -signée par une clef publique qui ne se trouve pas dans le clefs autorisées -(voir @code{--authorize} plus bas.) - -@item --missing -Liste une liste de noms de fichiers du dépôt sur l'entrée standard, un par -ligne, et écrit sur l'entrée standard le sous-ensemble de ces fichiers qui -manquent dans le dépôt. - -@item --generate-key[=@var{paramètres}] -@cindex signature, archives -Générer une nouvelle paire de clefs pour le démon. Cela est un prérequis -avant que les archives ne puissent être exportées avec @code{--export}. -Remarquez que cette opération prend généralement du temps parce qu'elle doit -récupère suffisamment d'entropie pour générer la paire de clefs. - -La paire de clefs générée est typiquement stockée dans @file{/etc/guix}, -dans @file{signing-key.pub} (clef publique) et @file{signing-key.sec} (clef -privée, qui doit rester secrète). Lorsque @var{paramètres} est omis, une -clef ECDSA utilisant la courbe Ed25519 est générée ou pour les version de -libgcrypt avant 1.6.0, une clef RSA de 4096 bits. Autrement, -@var{paramètres} peut spécifier les paramètres @code{genkey} adaptés pour -libgcrypt (@pxref{General public-key related Functions, -@code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). - -@item --authorize -@cindex autorisation, archives -Autoriser les imports signés par la clef publique passée sur l'entrée -standard. La clef publique doit être au « format avancé s-expression » — -c.-à-d.@: le même format que le fichier @file{signing-key.pub}. - -La liste des clefs autorisées est gardée dans un fichier modifiable par des -humains dans @file{/etc/guix/acl}. Le fichier contient des -@url{http://people.csail.mit.edu/rivest/Sexp.txt, « s-expressions au format -avancé »} et est structuré comme une liste de contrôle d'accès dans -l'@url{http://theworld.com/~cme/spki.txt, infrastructure à clefs publiques -simple (SPKI)}. - -@item --extract=@var{répertoire} -@itemx -x @var{répertoire} -Lit une archive à un seul élément telle que servie par un serveur de -substituts (@pxref{Substituts}) et l'extrait dans @var{répertoire}. C'est -une opération de bas niveau requise seulement dans de rares cas d'usage ; -voir plus loin. - -Par exemple, la commande suivante extrait le substitut pour Emacs servi par -@code{@value{SUBSTITUTE-SERVER}} dans @file{/tmp/emacs} : - -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ - | bunzip2 | guix archive -x /tmp/emacs -@end example - -Les archives à un seul élément sont différentes des archives à plusieurs -éléments produites par @command{guix archive --export} ; elles contiennent -un seul élément du dépôt et elles n'embarquent @emph{pas} de signature. -Ainsi cette opération ne vérifie @emph{pas} de signature et sa sortie -devrait être considérée comme non sûre. - -Le but principal de cette opération est de faciliter l'inspection du contenu -des archives venant de serveurs auxquels on ne fait potentiellement pas -confiance. - -@end table - - -@c ********************************************************************* -@node Développement -@chapter Développement - -@cindex développement logiciel -Si vous êtes développeur de logiciels, Guix fournit des outils que vous -devriez trouver utiles — indépendamment du langage dans lequel vous -développez. C'est ce dont parle ce chapitre. - -La commande @command{guix environment} permet de créer des -@dfn{environnements de développement} confortables contenant toutes les -dépendances et les outils nécessaires pour travailler sur le paquet logiciel -de votre choix. La commande @command{guix pack} vous permet de créer des -@dfn{lots applicatifs} qui peuvent facilement être distribués à des -utilisateurs qui n'utilisent pas Guix. - -@menu -* Invoquer guix environment:: Mettre en place des environnements de - développement. -* Invoquer guix pack:: Créer des lots de logiciels. -@end menu - -@node Invoquer guix environment -@section Invoquer @command{guix environment} - -@cindex environnements de construction reproductibles -@cindex environnement de développement -@cindex @command{guix environment} -@cindex environnement de construction de paquets -Le but de @command{guix environment} est d'assister les hackers dans la -création d'environnements de développement reproductibles sans polluer leur -profil de paquets. L'outil @command{guix environment} prend un ou plusieurs -paquets, construit leurs entrées et crée un environnement shell pour pouvoir -les utiliser. - -La syntaxe générale est : - -@example -guix environment @var{options} @var{paquet}@dots{} -@end example - -L'exemple suivant crée un nouveau shell préparé pour le développement de -GNU@tie{}Guile : - -@example -guix environment guile -@end example - -Si les dépendances requises ne sont pas déjà construites, @command{guix -environment} les construit automatiquement. L'environnement du nouveau -shell est une version améliorée de l'environnement dans lequel @command{guix -environment} a été lancé. Il contient les chemins de recherche nécessaires -à la construction du paquet donné en plus des variables d'environnement -existantes. Pour créer un environnement « pur », dans lequel les variables -d'environnement de départ ont été nettoyées, utilisez l'option -@code{--pure}@footnote{Les utilisateurs ajoutent parfois à tord des valeurs -supplémentaires dans les variables comme @code{PATH} dans leur -@file{~/.bashrc}. En conséquence, lorsque @code{guix environment} le lance, -Bash peut lire @file{~/.bashrc}, ce qui produit des « impuretés » dans ces -variables d'environnement. C'est une erreur de définir ces variables -d'environnement dans @file{.bashrc} ; à la place, elles devraient être -définie dans @file{.bash_profile}, qui est sourcé uniquement par les shells -de connexion. @xref{Bash Startup Files,,, bash, The GNU Bash Reference -Manual}, pour des détails sur les fichiers de démarrage de Bash.}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} définie la variable @code{GUIX_ENVIRONMENT} dans -le shell qu'il crée ; sa valeur est le nom de fichier du profil de cet -environnement. Cela permet aux utilisateur, disons, de définir un prompt -spécifique pour les environnement de développement dans leur @file{.bashrc} -(@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 -…@: ou de naviguer dans le profil : - -@example -$ ls "$GUIX_ENVIRONMENT/bin" -@end example - -En plus, plus d'un paquet peut être spécifié, auquel cas l'union des entrées -des paquets données est utilisée. Par exemple, la commande ci-dessous crée -un shell où toutes les dépendances de Guile et Emacs sont disponibles : - -@example -guix environment guile emacs -@end example - -Parfois, une session shell interactive est inutile. On peut invoquer une -commande arbitraire en plaçant le jeton @code{--} pour séparer la commande -du reste des arguments : - -@example -guix environment guile -- make -j4 -@end example - -Dans d'autres situations, il est plus pratique de spécifier la liste des -paquets requis dans l'environnement. Par exemple, la commande suivante -lance @command{python} dans un environnement contenant Python@tie{}2.7 et -NumPy : - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -En plus, on peut vouloir les dépendance d'un paquet et aussi des paquets -supplémentaires qui ne sont pas des dépendances à l'exécution ou à la -construction, mais qui sont utiles au développement tout de même. À cause -de cela, le drapeau @code{--ad-hoc} est positionnel. Les paquets qui -apparaissent avant @code{--ad-hoc} sont interprétés comme les paquets dont -les dépendances seront ajoutées à l'environnement. Les paquets qui -apparaissent après @code{--ad-hoc} sont interprétés comme les paquets à -ajouter à l'environnement directement. Par exemple, la commande suivante -crée un environnement de développement pour Guix avec les paquets Git et -strace en plus : - -@example -guix environment guix --ad-hoc git strace -@end example - -Parfois il est souhaitable d'isoler l'environnement le plus possible, pour -une pureté et une reproductibilité maximale. En particulier, lorsque vous -utilisez Guix sur une distribution hôte qui n'est pas le système Guix, il -est souhaitable d'éviter l'accès à @file{/usr/bin} et d'autres ressources du -système depuis les environnements de développement. Par exemple, la -commande suivante crée un REPL Guile dans un « conteneur » où seuls le dépôt -et le répertoire de travail actuel sont montés : - -@example -guix environment --ad-hoc --container guile -- guile -@end example - -@quotation Remarque -L'option @code{--container} requiert Linux-libre 3.19 ou supérieur. -@end quotation - -Les options disponibles sont résumées ci-dessous. - -@table @code -@item --root=@var{fichier} -@itemx -r @var{fichier} -@cindex environnement persistent -@cindex racine du ramasse-miettes, pour les environnements -Fait de @var{fichier} un lien symbolique vers le profil de cet -environnement, et l'enregistre comme une racine du ramasse-miettes. - -C'est utile si vous souhaitez protéger votre environnement du -ramasse-miettes, pour le rendre « persistent ». - -Lorsque cette option est omise, l'environnement n'est protégé du -ramasse-miettes que le temps de la session @command{guix environment}. Cela -signifie que la prochaine fois que vous créerez le même environnement, vous -pourriez avoir à reconstruire ou télécharger des paquets. @xref{Invoquer guix gc}, pour plus d'informations sur les racines du GC. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Crée un environnement pour le paquet ou la liste de paquets en lesquels -s'évalue @var{expr}. - -Par exemple, lancer : - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -démarre un shell avec l'environnement pour cette variante spécifique du -paquet PETSc. - -Lancer : - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -démarre un shell où tous les paquets de base du système sont disponibles. - -Les commande au-dessus n'utilisent que les sorties par défaut des paquets -donnés. Pour choisir d'autres sorties, on peut spécifier des pairs : - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{fichier} -@itemx -l @var{fichier} -Crée un environnement pour le paquet ou la liste de paquets en lesquels -@var{fichier} s'évalue. - -Par exemple, @var{fichier} peut contenir une définition comme celle-ci -(@pxref{Définition des paquets}) : - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{fichier} -@itemx -m @var{fichier} -Crée un environnement pour les paquets contenus dans l'objet manifeste -renvoyé par le code Scheme dans @var{fichier}. - -C'est similaire à l'option de même nom de @command{guix package} -(@pxref{profile-manifest, @option{--manifest}}) et utilise les même fichiers -manifestes. - -@item --ad-hoc -Inclut tous les paquets spécifiés dans l'environnement qui en résulte, comme -si un paquet @i{ad hoc} était spécifié, avec ces paquets comme entrées. -Cette option est utile pour créer un environnement rapidement sans avoir à -écrire une expression de paquet contenant les entrées désirées. - -Par exemple la commande : - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -lance @command{guile} dans un environnement où Guile et Guile-SDDL sont -disponibles. - -Remarquez que cet exemple demande implicitement la sortie par défaut de -@code{guile} et @code{guile-sdl}, mais il est possible de demander une -sortie spécifique — p.@: ex.@: @code{glib:bin} demande la sortie @code{bin} -de @code{glib} (@pxref{Des paquets avec plusieurs résultats}). - -Cette option peut être composée avec le comportement par défaut de -@command{guix environment}. Les paquets qui apparaissent avant -@code{--ad-hoc} sont interprétés comme les paquets dont les dépendances -seront ajoutées à l'environnement, le comportement par défaut. Les paquets -qui apparaissent après @code{--ad-hoc} sont interprétés comme les paquets à -ajouter à l'environnement directement. - -@item --pure -Nettoie les variables d'environnement existantes lors de la construction du -nouvel environnement, sauf celles spécifiées par @option{--preserve} (voir -ci-dessous). Cela a pour effet de créer un environnement dans lequel les -chemins de recherche ne contiennent que des entrées de paquets. - -@item --preserve=@var{regexp} -@itemx -E @var{regexp} -Lorsque vous utilisez @option{--pure}, préserver les variables -d'environnement qui correspondent à @var{regexp} — en d'autres termes, cela -les met en « liste blanche » de variables d'environnement qui doivent être -préservées. Cette option peut être répétée plusieurs fois. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -Cet exemple exécute @command{mpirun} dans un contexte où les seules -variables d'environnement défines sont @code{PATH}, les variables -d'environnement dont le nom commence par @code{SLURM}, ainsi que les -variables « importante » habituelles (@code{HOME}, @code{USER}, etc). - -@item --search-paths -Affiche les définitions des variables d'environnement qui composent -l'environnement. - -@item --system=@var{système} -@itemx -s @var{système} -Essaye de construire pour @var{système} — p.@: ex.@: @code{i686-linux}. - -@item --container -@itemx -C -@cindex conteneur -Lance @var{commande} dans un conteneur isolé. Le répertoire de travail -actuel en dehors du conteneur est monté dans le conteneur. En plus, à moins -de le changer avec @code{--user}, un répertoire personnel fictif est créé -pour correspondre à celui de l'utilisateur actuel et @file{/etc/passwd} est -configuré en conséquence. - -Le processus est lancé en tant que l'utilisateur actuel en dehors du -conteneur. Dans le conteneur, il a le même UID et GID que l'utilisateur -actuel, à moins que vous ne passiez @option{--user} (voir ci-dessous). - -@item --network -@itemx -N -Pour les conteneurs, partage l'espace de nom du réseau avec le système -hôte. Les conteneurs créés sans cette option n'ont accès qu'à l'interface -de boucle locale. - -@item --link-profile -@itemx -P -Pour les conteneurs, lie le profil de l'environnement à -@file{~/.guix-profile} dans le conteneur. C'est équivalent à lance la -commande @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile} dans le -conteneur. La liaison échouera et annulera l'environnement si le répertoire -existe déjà, ce qui sera sans doute le cas si @command{guix environment} est -invoqué dans le répertoire personnel de l'utilisateur. - -Certains paquets sont configurés pour chercher des fichiers de configuration -et des données dans @code{~/.guix-profile}@footnote{Par exemple, le paquet -@code{fontconfig} inspecte @file{~/.guix-profile/share/fonts} pour trouver -des polices supplémentaires.} ; @code{--link-profile} permet à ces -programmes de se comporter comme attendu dans l'environnement. - -@item --user=@var{utilisateur} -@itemx -u @var{utilisateur} -Pour les conteneurs, utilise le nom d'utilisateur @var{utilisateur} à la -place de l'utilisateur actuel. L'entrée générée dans @file{/etc/passwd} -dans le conteneur contiendra le nom @var{utilisateur} ; le répertoire -personnel sera @file{/home/@var{utilisateur}} ; et aucune donnée GECOS ne -sera copiée. En plus, l'UID et le GID dans le conteneur seront 1000. -@var{user} n'a pas besoin d'exister sur le système. - -En plus, tous les chemins partagés ou exposés (voir @code{--share} et -@code{--expose} respectivement) dont la cible est dans le répertoire -personnel de l'utilisateur seront remontés relativement à -@file{/home/UTILISATEUR} ; cela comprend le montage automatique du -répertoire de travail actuel. - -@example -# exposera les chemins comme /home/foo/wd, /home/foo/test et /home/foo/target -cd $HOME/wd -guix environment --container --user=foo \ - --expose=$HOME/test \ - --expose=/tmp/target=$HOME/target -@end example - -Bien que cela limite la fuite de l'identité de l'utilisateur à travers le -chemin du répertoire personnel et des champs de l'utilisateur, ce n'est -qu'un composant utile pour une solution d'anonymisation ou de préservation -de la vie privée — pas une solution en elle-même. - -@item --expose=@var{source}[=@var{cible}] -Pour les conteneurs, expose le système de fichiers @var{source} du système -hôte comme un système de fichiers en lecture seule @var{cible} dans le -conteneur. Si @var{cible} n'est pas spécifiée, @var{source} est utilisé -comme point de montage dans le conteneur. - -L'exemple ci-dessous crée un REPL Guile dans un conteneur dans lequel le -répertoire personnel de l'utilisateur est accessible en lecture-seule via le -répertoire @file{/exchange} : - -@example -guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile -@end example - -@item --share=@var{source}[=@var{cible}] -Pour les conteneurs, partage le système de fichiers @var{source} du système -hôte comme un système de fichiers en lecture-écriture @var{cible} dans le -conteneur. Si @var{cible} n'est pas spécifiée, @var{source} est utilisée -comme point de montage dans le conteneur. - -L'exemple ci-dessous crée un REPL Guile dans un conteneur dans lequel le -répertoire personnel de l'utilisateur est accessible en lecture-écriture via -le répertoire @file{/exchange} : - -@example -guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile -@end example -@end table - -En plus, @command{guix environment} prend en charge toutes les options de -construction communes prises en charge par @command{guix build} -(@pxref{Options de construction communes}) et toutes les options de transformation de -paquets (@pxref{Options de transformation de paquets}). - -@node Invoquer guix pack -@section Invoquer @command{guix pack} - -Parfois vous voulez passer un logiciel à des gens qui n'ont pas (encore !) -la chance d'utiliser Guix. Vous leur diriez bien de lancer @command{guix -package -i @var{quelque chose}} mais ce n'est pas possible dans ce cas. -C'est là que @command{guix pack} entre en jeu. - -@quotation Remarque -Si vous cherchez comment échanger des binaires entre des machines où Guix -est déjà installé, @pxref{Invoquer guix copy}, @ref{Invoquer guix publish}, -et @ref{Invoquer guix archive}. -@end quotation - -@cindex pack -@cindex lot -@cindex lot d'applications -@cindex lot de logiciels -La commande @command{guix pack} crée un @dfn{pack} ou @dfn{lot de logiciels} -: elle crée une archive tar ou un autre type d'archive contenant les -binaires pour le logiciel qui vous intéresse ainsi que ses dépendances. -L'archive qui en résulte peut être utilisée sur toutes les machines qui -n'ont pas Guix et les gens peuvent lancer exactement les mêmes binaires que -ceux que vous avez avec Guix. Le pack lui-même est créé d'une manière -reproductible au bit près, pour que n'importe qui puisse vérifier qu'il -contient bien les résultats que vous prétendez proposer. - -Par exemple, pour créer un lot contenant Guile, Emacs, Geiser et toutes -leurs dépendances, vous pouvez lancer : - -@example -$ guix pack guile emacs geiser -@dots{} -/gnu/store/@dots{}-pack.tar.gz -@end example - -Le résultat ici est une archive tar contenant un répertoire -@file{/gnu/store} avec tous les paquets nécessaires. L'archive qui en -résulte contient un @dfn{profil} avec les trois paquets qui vous intéressent -; le profil est le même qui celui qui aurait été créé avec @command{guix -package -i}. C'est ce mécanisme qui est utilisé pour créer les archives tar -binaires indépendantes de Guix (@pxref{Installation binaire}). - -Les utilisateurs de ce pack devraient lancer -@file{/gnu/store/@dots{}-profile/bin/guile} pour lancer Guile, ce qui n'est -pas très pratique. Pour éviter cela, vous pouvez créer, disons, un lien -symbolique @file{/opt/gnu/bin} vers le profil : - -@example -guix pack -S /opt/gnu/bin=bin guile emacs geiser -@end example - -@noindent -De cette façon, les utilisateurs peuvent joyeusement taper -@file{/opt/gnu/bin/guile} et profiter. - -@cindex binaires repositionnables, avec @command{guix pack} -Et si le destinataire de votre pack n'a pas les privilèges root sur sa -machine, et ne peut donc pas le décompresser dans le système de fichiers -racine ? Dans ce cas, vous pourriez utiliser l'option @code{--relocatable} -(voir plus bas). Cette option produite des @dfn{binaire repositionnables}, -ce qui signifie qu'ils peuvent être placés n'importe où dans l'arborescence -du système de fichiers : dans l'exemple au-dessus, les utilisateurs peuvent -décompresser votre archive dans leur répertoire personnel et lancer -directement @file{./opt/gnu/bin/guile}. - -@cindex Docker, construire une image avec guix pack -Autrement, vous pouvez produire un pack au format d'image Docker avec la -commande suivante : - -@example -guix pack -f docker guile emacs geiser -@end example - -@noindent -Le résultat est une archive tar qui peut être passée à la commande -@command{docker load}. Voir la -@uref{https://docs.docker.com/engine/reference/commandline/load/, -documentation de Docker} pour plus d'informations. - -@cindex Singularity, construire une image avec guix pack -@cindex SquashFS, construire une image avec guix pack -Autrement, vous pouvez produire une image SquashFS avec la commande suivante -: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -Le résultat est une image de système de fichiers SquashFS qui peut soit être -montée directement soit être utilisée comme image de conteneur de système de -fichiers avec l'@uref{http://singularity.lbl.gov, environnement d'exécution -conteneurisé Singularity}, avec des commandes comme @command{singularity -shell} ou @command{singularity exec}. - -Diverses options en ligne de commande vous permettent de personnaliser votre -pack : - -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produire un pack dans le @var{format} donné. - -Les formats disponibles sont : - -@table @code -@item tarball -C'est le format par défaut. Il produit une archive tar contenant tous les -binaires et les liens symboliques spécifiés. - -@item docker -Cela produit une archive tar qui suit la -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -spécification des images Docker}. - -@item squashfs -Cela produit une image SquashFS contenant tous les binaires et liens -symboliques spécifiés, ainsi que des points de montages vides pour les -systèmes de fichiers virtuels comme procfs. -@end table - -@cindex binaires repositionnables -@item --relocatable -@itemx -R -Produire des @dfn{binaires repositionnables} — c.-à-d.@: des binaires que -vous pouvez placer n'importe où dans l'arborescence du système de fichiers -et les lancer à partir de là. - -Lorsque vous passez cette option une fois, les binaires qui en résultent -demandent le support des @dfn{espaces de nom utilisateurs} dans le noyau -Linux ; lorsque vous la passez @emph{deux} fois@footnote{Il y a une astuce -pour s'en rappeler : on peut envisager @code{RR}, qui ajoute le support -PRoot, comme étant l'abréviation de « Réellement Repositionnable ». Pas -mal, hein ?}, les binaires repositionnables utilisent PRoot si les espaces -de noms ne sont pas utilisables, et ça fonctionne partout — voir plus bas -pour comprendre les implications. - -Par exemple, si vous créez un pack contenant Bash avec : - -@example -guix pack -RR -S /mybin=bin bash -@end example - -@noindent -…@: vous pouvez copier ce pack sur une machine qui n'a pas Guix et depuis -votre répertoire personnel en tant qu'utilisateur non-privilégié, lancer : - -@example -tar xf pack.tar.gz -./mybin/sh -@end example - -@noindent -Dans ce shell, si vous tapez @code{ls /gnu/store}, vous remarquerez que -@file{/gnu/store} apparaît et contient toutes les dépendances de -@code{bash}, même si la machine n'a pas du tout de @file{/gnu/store} ! -C'est sans doute la manière la plus simple de déployer du logiciel construit -avec Guix sur une machine sans Guix. - -@quotation Remarque -Par défaut ,les binaires repositionnables s'appuient sur les @dfn{espaces de -noms utilisateurs} du noyau Linux, qui permet à des utilisateurs -non-privilégiés d'effectuer des montages et de changer de racine. Les -anciennes versions de Linux ne le supportait pas et certaines distributions -GNU/Linux le désactive. - -Pour produire des binaires repositionnables qui fonctionnent même sans -espace de nom utilisateur, passez @option{--relocatable} ou @option{-R} -@emph{deux fois}. Dans ce cas, les binaires testeront la prise en charge -des espaces de noms utilisateurs et utiliseront PRoot s'ils ne sont pas pris -en charge. - -Le programme @uref{https://proot-me.github.io/, PRoot} fournit la prise en -charge nécessaire pour la virtualisation du système de fichier. Il y arrive -en utilisant l'appel système @code{ptrace} sur le programme. Cette approche -a l'avantage de fonctionner sans demander de support spécial de la part du -noyau, mais occasionne un coût supplémentaire en temps pour chaque appel -système effectué. -@end quotation - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considérer le paquet évalué par @var{expr}. - -Cela a le même but que l'option de même nom de @command{guix build} -(@pxref{Options de construction supplémentaires, @code{--expression} dans @command{guix -build}}). - -@item --manifest=@var{fichier} -@itemx -m @var{fichier} -Utiliser les paquets contenus dans l'objet manifeste renvoyé par le code -Scheme dans @var{fichier} - -Elle a un but similaire à l'option de même nom dans @command{guix package} -(@pxref{profile-manifest, @option{--manifest}}) et utilise les mêmes -fichiers manifeste. Ils vous permettent de définir une collection de -paquets une fois et de l'utiliser aussi bien pour créer des profils que pour -créer des archives pour des machines qui n'ont pas Guix d'installé. -Remarquez que vous pouvez spécifier @emph{soit} un fichier manifeste, -@emph{soit} une liste de paquet, mais pas les deux. - -@item --system=@var{système} -@itemx -s @var{système} -Tenter de construire pour le @var{système} — p.@: ex.@: @code{i686-linux} — -plutôt que pour le type de système de l'hôte de construction. - -@item --target=@var{triplet} -@cindex compilation croisée -Effectuer une compilation croisée pour @var{triplet} qui doit être un -triplet GNU valide, comme @code{"mips64el-linux-gnu"} (@pxref{Specifying -target triplets, GNU configuration triplets,, autoconf, Autoconf}). - -@item --compression=@var{outil} -@itemx -C @var{outil} -Compresser l'archive résultante avec @var{outil} — l'un des outils parmi -@code{bzip2}, @code{xz}, @code{lzip} ou @code{none} pour aucune compression. - -@item --symlink=@var{spec} -@itemx -S @var{spec} -Ajouter les liens symboliques spécifiés par @var{spec} dans le pack. Cette -option peut apparaître plusieurs fois. - -@var{spec} a la forme @code{@var{source}=@var{cible}}, où @var{source} est -le lien symbolique qui sera créé et @var{cible} est la cible du lien. - -Par exemple, @code{-S /opt/gnu/bin=bin} crée un lien symbolique -@file{/opt/gnu/bin} qui pointe vers le sous-répertoire @file{bin} du profil. - -@item --save-provenance -Sauvegarder les informations de provenance des paquets passés sur la ligne -de commande. Les informations de provenance contiennent l'URL et le commit -des canaux utilisés (@pxref{Canaux}). - -Les informations de provenance sont sauvegardées dans le fichier -@file{/gnu/store/@dots{}-profile/manifest} du pack, avec les métadonnées de -paquets habituelles — le nom et la version de chaque paquet, leurs entrées -propagées, etc. Ce sont des informations utiles pour le destinataire du -pack, qui sait alors comment le pack a (normalement) été obtenu. - -Cette option n'est pas activée par défaut car, comme l'horodatage, les -informations de provenance ne contribuent en rien au processus de -construction. En d'autres termes, il y a une infinité d'URL et d'ID de -commit qui permettent d'obtenir le même pack. Enregistrer de telles -métadonnées « silencieuses » dans la sortie casse donc éventuellement la -propriété de reproductibilité au bit près. - -@item --localstatedir -@itemx --profile-name=@var{nom} -Inclus le « répertoire d'état local », @file{/var/guix}, dans le lot qui en -résulte, et notamment le profil -@file{/var/guix/profiles/per-user/root/@var{nom}} — par défaut @var{nom} est -@code{guix-profile}, ce qui correspond à @file{~root/.guix-profile}. - -@file{/var/guix} contient la base de données du dépôt (@pxref{Le dépôt}) -ainsi que les racines du ramasse-miettes (@pxref{Invoquer guix gc}). Le -fournir dans le pack signifie que le dépôt et « complet » et gérable par -Guix ; ne pas le fournir dans le pack signifie que le dépôt est « mort » : -aucun élément ne peut être ajouté ni enlevé après l'extraction du pack. - -Un cas d'utilisation est l'archive binaire indépendante de Guix -(@pxref{Installation binaire}). - -@item --bootstrap -Utiliser les programmes d'amorçage pour construire le pack. Cette option -n'est utile que pour les développeurs de Guix. -@end table - -En plus, @command{guix pack} supporte toutes les options de construction -communes (@pxref{Options de construction communes}) et toutes les options de -transformation de paquets (@pxref{Options de transformation de paquets}). - - -@c ********************************************************************* -@node Interface de programmation -@chapter Interface de programmation - -GNU Guix fournit diverses interface de programmation Scheme (API) qui pour -définir, construire et faire des requêtes sur des paquets. La première -interface permet aux utilisateurs d'écrire des définitions de paquets de -haut-niveau. Ces définitions se réfèrent à des concepts de création de -paquets familiers, comme le nom et la version du paquet, son système de -construction et ses dépendances. Ces définitions peuvent ensuite être -transformées en actions concrètes lors de la construction. - -Les actions de construction sont effectuées par le démon Guix, pour le -compte des utilisateurs. Dans un environnement standard, le démon possède -les droits en écriture sur le dépôt — le répertoire @file{/gnu/store} — mais -pas les utilisateurs. La configuration recommandée permet aussi au démon -d'effectuer la construction dans des chroots, avec un utilisateur de -construction spécifique pour minimiser les interférences avec le reste du -système. - -@cindex dérivation -Il y a des API de plus bas niveau pour interagir avec le démon et le dépôt. -Pour demander au démon d'effectuer une action de construction, les -utilisateurs lui donnent en fait une @dfn{dérivation}. Une dérivation est -une représentation à bas-niveau des actions de construction à entreprendre -et l'environnement dans lequel elles devraient avoir lieu — les dérivations -sont aux définitions de paquets ce que l'assembleur est aux programmes C. -Le terme de « dérivation » vient du fait que les résultats de la -construction en @emph{dérivent}. - -Ce chapitre décrit toutes ces API tour à tour, à partir des définitions de -paquets à haut-niveau. - -@menu -* Modules de paquets:: Les paquets du point de vu du programmeur. -* Définition des paquets:: Définir de nouveaux paquets. -* Systèmes de construction:: Spécifier comment construire les paquets. -* Le dépôt:: Manipuler le dépôt de paquets. -* Dérivations:: Interface de bas-niveau avec les dérivations - de paquets. -* La monade du dépôt:: Interface purement fonctionnelle avec le - dépôt. -* G-Expressions:: Manipuler les expressions de construction. -* Invoquer guix repl:: S'amuser avec Guix de manière interactive. -@end menu - -@node Modules de paquets -@section Modules de paquets - -D'un point de vue programmatique, les définitions de paquets de la -distribution GNU sont fournies par des modules Guile dans l'espace de noms -@code{(gnu packages @dots{})}@footnote{Remarquez que les paquets sous -l'espace de nom @code{(gnu packages @dots{})} ne sont pas nécessairement des -« paquets GNU ». Le nom de ce module suit la convention de nommage usuelle -de Guile : @code{gnu} signifie que ces modules sont distribués dans le -système GNU, et @code{packages} identifie les modules qui définissent les -paquets.} (@pxref{Modules, Guile modules,, guile, GNU Guile Reference -Manual}). Par exemple, le module @code{(gnu packages emacs)} exporte une -variable nommée @code{emacs}, qui est liée à un objet @code{} -(@pxref{Définition des paquets}). - -L'espace de nom @code{(gnu packages @dots{})} est automatiquement scanné par -les outils en ligne de commande. Par exemple, lorsque vous lancez -@code{guix package -i emacs}, tous les modules @code{(gnu packages @dots{})} -sont scannés jusqu'à en trouver un qui exporte un objet de paquet dont le -nom est @code{emacs}. Cette capacité à chercher des paquets est implémentée -dans le module @code{(gnu packages)}. - -@cindex personnalisation, des paquets -@cindex chemin de recherche des modules de paquets -Les utilisateurs peuvent stocker des définitions dans des modules avec des -noms différents — p.@: ex.@: @code{(my-packages emacs)}@footnote{Remarquez -que le nom de fichier et de module doivent être identiques. Par exemple, le -module @code{(my-packages emacs)} doit être stocké dans un fichier -@file{my-packages/emacs.scm} relativement au chemin de chargement spécifié -avec @option{--load-path} ou @code{GUIX_PACKAGE_PATH}. @xref{Modules and -the File System,,, guile, GNU Guile Reference Manual} pour plus de -détails}. Il y a deux manières de rendre ces définitions visibles aux -interfaces utilisateurs : - -@enumerate -@item -En ajoutant le répertoire contenant vos modules de paquets au chemin de -recherche avec le drapeau @code{-L} de @command{guix package} et des autres -commandes (@pxref{Options de construction communes}) ou en indiquant la variable -d'environnement @code{GUIX_PACKAGE_PATH} décrite plus bas. - -@item -En définissant un @dfn{canal} et en configurant @command{guix pull} pour -qu'il l'utilise. Un canal est essentiellement un dépôt Git contenant des -modules de paquets. @xref{Canaux}, pour plus d'informations sur comment -définir et utiliser des canaux. -@end enumerate - -@code{GUIX_PACKAGE_PATH} fonctionne comme les autres variables de chemins de -recherche : - -@defvr {Variable d'environnement} GUIX_PACKAGE_PATH -C'est une liste séparée par des deux-points de répertoires dans lesquels -trouver des modules de paquets supplémentaires. Les répertoires listés dans -cette variable sont prioritaires par rapport aux paquets de la distribution. -@end defvr - -La distribution est entièrement @dfn{bootstrappée} et @dfn{auto-contenue} : -chaque paquet est construit uniquement à partir d'autres paquets de la -distribution. La racine de ce graphe de dépendance est un petit ensemble de -@dfn{binaires de bootstrap} fournis par le module @code{(gnu packages -bootstrap)}. Pour plus d'informations sur le bootstrap, -@pxref{Bootstrapping}. - -@node Définition des paquets -@section Définition des paquets - -L'interface de haut-niveau pour les définitions de paquets est implémentée -dans les modules @code{(guix packages)} et @code{(guix build-system)}. Par -exemple, la définition du paquet, ou la @dfn{recette}, du paquet GNU Hello -ressemble à cela : - -@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 -Sans être un expert Scheme, le lecteur peut comprendre la signification des -différents champs présents. Cette expression lie la variable @code{hello} à -un objet @code{}, qui est essentiellement un enregistrement -(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). On -peut inspecter cet objet de paquet avec les procédures qui se trouvent dans -le module @code{(guix packages)} ; par exemple, @code{(package-name hello)} -renvoie — oh surprise ! — @code{"hello"}. - -Avec un peu de chance, vous pourrez importer tout ou partie de la définition -du paquet qui vous intéresse depuis un autre répertoire avec la commande -@code{guix import} (@pxref{Invoquer guix import}). - -Dans l'exemple précédent, @var{hello} est défini dans un module à part, -@code{(gnu packages hello)}. Techniquement, cela n'est pas strictement -nécessaire, mais c'est pratique : tous les paquets définis dans des modules -sous @code{(gnu packages @dots{})} sont automatiquement connus des outils en -ligne de commande (@pxref{Modules de paquets}). - -Il y a quelques points à remarquer dans la définition de paquet précédente : - -@itemize -@item -Le champ @code{source} du paquet est un objet @code{} (@pxref{Référence des origines}, pour la référence complète). Ici, on utilise la méthode -@code{url-fetch} de @code{(guix download)}, ce qui signifie que la source -est un fichier à télécharger par FTP ou HTTP. - -Le préfixe @code{mirror://gnu} demande à @code{url-fetch} d'utiliser l'un -des miroirs GNU définis dans @code{(guix download)}. - -Le champ @code{sha256} spécifie le hash SHA256 attendu pour le fichier -téléchargé. Il est requis et permet à Guix de vérifier l'intégrité du -fichier. La forme @code{(base32 @dots{})} introduit a représentation en -base32 du hash. Vous pouvez obtenir cette information avec @code{guix -download} (@pxref{Invoquer guix download}) et @code{guix hash} -(@pxref{Invoquer guix hash}). - -@cindex correctifs -Lorsque cela est requis, la forme @code{origin} peut aussi avec un champ -@code{patches} qui liste les correctifs à appliquer et un champ -@code{snippet} qui donne une expression Scheme pour modifier le code source. - -@item -@cindex Système de construction GNU -Le champ @code{build-system} spécifie la procédure pour construire le paquet -(@pxref{Systèmes de construction}). Ici, @var{gnu-build-system} représente le système -de construction GNU familier, où les paquets peuvent être configurés, -construits et installés avec la séquence @code{./configure && make && make -check && make install} habituelle. - -@item -Le champ @code{arguments} spécifie des options pour le système de -construction (@pxref{Systèmes de construction}). Ici il est interprété par -@var{gnu-build-system} comme une demande de lancer @file{configure} avec le -drapeau @code{--enable-silent-rules}. - -@cindex quote -@cindex quoting -@findex ' -@findex quote -Que sont ces apostrophes (@code{'}) ? C'est de la syntaxe Scheme pour -introduire une liste ; @code{'} est synonyme de la fonction @code{quote}. -@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, pour -des détails. Ice la valeur du champ @code{arguments} est une liste -d'arguments passés au système de construction plus tard, comme avec -@code{apply} (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile -Reference Manual}). - -La séquence dièse-deux-points (@code{#:}) définie un @dfn{mot-clef} Scheme -(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), et -@code{#:configure-flags} est un mot-clef utilisé pour passer un argument au -système de construction (@pxref{Coding With Keywords,,, guile, GNU Guile -Reference Manual}). - -@item -Le champ @code{inputs} spécifie les entrées du processus de construction — -c.-à-d.@: les dépendances à la construction ou à l'exécution du paquet. Ici -on définie une entrée nommée @code{"gawk"} dont la valeur est la variable -@var{gawk} ; @var{gawk} est elle-même liée à un objet @code{}. - -@cindex accent grave (quasiquote) -@findex ` -@findex quasiquote -@cindex virgule (unquote) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -De nouveau, @code{`} (un accent grave, synonyme de la fonction -@code{quasiquote}) nous permet d'introduire une liste littérale dans le -champ @code{inputs}, tandis que @code{,} (une virgule, synonyme de la -fonction @code{unquote}) nous permet d'insérer une valeur dans cette liste -(@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference Manual}). - -Remarquez que GCC, Coreutils, Bash et les autres outils essentiels n'ont pas -besoin d'être spécifiés en tant qu'entrées ici. À la place, le -@var{gnu-build-system} est en charge de s'assurer qu'ils sont présents -(@pxref{Systèmes de construction}). - -Cependant, toutes les autres dépendances doivent être spécifiées dans le -champ @code{inputs}. Toute dépendance qui ne serait pas spécifiée ici sera -simplement indisponible pour le processus de construction, ce qui peut mener -à un échec de la construction. -@end itemize - -@xref{Référence des paquets}, pour une description complète des champs -possibles. - -Lorsqu'une définition de paquet est en place, le paquet peut enfin être -construit avec l'outil en ligne de commande @code{guix build} -(@pxref{Invoquer guix build}), pour résoudre les échecs de construction que -vous pourriez rencontrer (@pxref{Débogage des échecs de construction}). Vous pouvez -aisément revenir à la définition du paquet avec la commande @command{guix -edit} (@pxref{Invoquer guix edit}). @xref{Consignes d'empaquetage}, pour plus -d'informations sur la manière de tester des définitions de paquets et -@ref{Invoquer guix lint}, pour des informations sur la manière de vérifier -que la définition respecte les conventions de style. -@vindex GUIX_PACKAGE_PATH -Enfin, @pxref{Canaux} pour des informations sur la manière d'étendre la -distribution en ajoutant vos propres définitions de paquets dans un « canal -». - -Finalement, la mise à jour de la définition du paquet à une nouvelle version -amont peut en partie s'automatiser avec la commande @command{guix refresh} -(@pxref{Invoquer guix refresh}). - -Sous le capot, une dérivation qui correspond à un objet @code{} est -d'abord calculé par la procédure @code{package-derivation}. Cette -dérivation est stockée dans un fichier @code{.drv} dans @file{/gnu/store}. -Les actions de construction qu'il prescrit peuvent ensuite être réalisées -par la procédure @code{build-derivation} (@pxref{Le dépôt}). - -@deffn {Procédure Scheme} package-derivation @var{store} @var{package} [@var{system}] -Renvoie l'objet @code{} du @var{paquet} pour le @var{système} -(@pxref{Dérivations}). - -@var{paquet} doit être un objet @code{} valide et @var{système} une -chaîne indiquant le type de système cible — p.ex.@: @code{"x86_64-linux"} -pour un système GNU x86_64 basé sur Linux. @var{dépôt} doit être une -connexion au démon, qui opère sur les dépôt (@pxref{Le dépôt}). -@end deffn - -@noindent -@cindex compilation croisée -De manière identique, il est possible de calculer une dérivation qui -effectue une compilation croisée d'un paquet pour un autre système : - -@deffn {Procédure Scheme} package-cross-derivation @var{store} @ - @var{paquet} @var{cible} [@var{système}] renvoie l'objet @code{} -du @var{paquet} construit depuis @var{système} pour @var{cible}. - -@var{cible} doit être un triplet GNU valide indiquant le matériel cible et -le système d'exploitation, comme @code{"mips64el-linux-gnu"} -(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU -Configure and Build System}). -@end deffn - -@cindex transformations de paquets -@cindex réécriture d'entrées -@cindex réécriture de l'arbre des dépendances -On peut manipuler les paquets de manière arbitraire. Une transformation -utile est par exemple la @dfn{réécriture d'entrées} où l'arbre des -dépendances d'un paquet est réécrit en replaçant des entrées spécifiques par -d'autres : - -@deffn {Procédure Scheme} package-input-rewriting @var{replacements} @ - [@var{nom-réécrit}] Renvoie une procédure qui, lorsqu'on lui donne un -paquet, remplace des dépendances directes et indirectes (mais pas ses -entrées implicites) en fonction de @var{remplacements}. @var{remplacements} -est une liste de paires de paquets ; le premier élément de chaque pair est -le paquet à remplacer, le second son remplaçant. - -De manière facultative, @var{nom-réécrit} est une procédure à un argument -qui prend le nom d'un paquet et renvoie son nouveau nom après l'avoir -réécrit. -@end deffn - -@noindent -Regardez cet exemple : - -@example -(define libressl-instead-of-openssl - ;; Cette procédure remplace OPENSSL par LIBRESSL, - ;; récursivement. - (package-input-rewriting `((,openssl . ,libressl)))) - -(define git-with-libressl - (libressl-instead-of-openssl git)) -@end example - -@noindent -Ici nous définissons d'abord une procédure de réécriture qui remplace -@var{openssl} par @var{libressl}. Ensuite nous l'utilisons pour définir une -@dfn{variante} du paquet @var{git} qui utilise @var{libressl} plutôt que -@var{openssl}. cela est exactement ce que l'option en ligne de commande -@option{--with-input} fait (@pxref{Options de transformation de paquets, -@option{--with-input}}). - -La variante suivante de @code{package-input-rewriting} peut repérer les -paquets à remplacer par nom à la place de leur identité. - -@deffn {Procédure Scheme} package-input-rewriting/spec @var{remplacements} -Renvoie une procédure qui, étant donné un paquet, applique les -@var{remplacements} à tous le graphe du paquet (en dehors des entrées -implicites). @var{remplacements} est une liste de paires de spécifications -et de procédures ; chaque spécification est une spécification de paquet -comme @code{"gcc"} ou @code{"guile@@2"}, et chaque procédure prend un paquet -correspondant et renvoie un remplaçant pour ce paquet. -@end deffn - -L'exemple ci-dessus pourrait être réécrit de cette manière : - -@example -(define libressl-instead-of-openssl - ;; Remplace tous les paquets nommés « openssl » par LibreSSL. - (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example - -Le différence clef est que, cette fois-ci, les paquets correspondent à la -spécification et non à l'identité. En d'autres termes, tout paquet dans le -graphe qui est appelé @code{openssl} sera remplacé. - -Une procédure plus générique pour réécrire un graphe de dépendance d'un -paquet est @code{package-mapping} : elle supporte n'importe quel changement -dans les nœuds du graphe. - -@deffn {Procédure Scheme} package-mapping @var{proc} [@var{cut?}] -Renvoie une procédure qui, avec un paquet, applique @var{proc} sur tous les -paquets dont il dépend et renvoie le paquet qui en résulte. La procédure -arrête la récursion là où @var{cut?} renvoie vrai pour un paquet donné. -@end deffn - -@menu -* Référence des paquets:: Le type de donnée des paquets. -* Référence des origines:: Le type de données d'origine. -@end menu - - -@node Référence des paquets -@subsection Référence de @code{package} - -Cette section résume toutes les options disponibles dans les déclarations -@code{package} (@pxref{Définition des paquets}). - -@deftp {Type de données} package -C'est le type de donnée représentant une recette de paquets. - -@table @asis -@item @code{name} -Le nom du paquet, comme une chaîne de caractères. - -@item @code{version} -La version du paquet, comme une chaîne de caractères. - -@item @code{source} -Un objet qui indique comment le code source du paquet devrait être -récupéré. La plupart du temps, c'est un objet @code{origin} qui indique un -fichier récupéré depuis internet (@pxref{Référence des origines}). Il peut aussi -s'agir de tout autre objet ``simili-fichier'' comme un @code{local-file} qui -indique un fichier du système de fichier local (@pxref{G-Expressions, -@code{local-file}}). - -@item @code{build-system} -Le système de construction qui devrait être utilisé pour construire le -paquet (@pxref{Systèmes de construction}). - -@item @code{arguments} (par défaut : @code{'()}) -Les arguments à passer au système de construction. C'est une liste qui -contient typiquement une séquence de paires de clefs-valeurs. - -@item @code{inputs} (par défaut : @code{'()}) -@itemx @code{native-inputs} (par défaut : @code{'()}) -@itemx @code{propagated-inputs} (par défaut : @code{'()}) -@cindex entrées, des paquets -Ces champs listent les dépendances du paquet. Chacune est une liste de -tuples, où chaque tuple a une étiquette pour une entrée (une chaîne de -caractères) comme premier élément, un paquet, une origine ou une dérivation -comme deuxième élément et éventuellement le nom d'une sortie à utiliser qui -est @code{"out"} par défaut (@pxref{Des paquets avec plusieurs résultats}, pour -plus d'informations sur les sorties des paquets). Par exemple, la liste -suivante spécifie trois entrées : - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;la sortie "bin" de Glib -@end example - -@cindex compilation croisée, dépendances des paquets -La distinction entre @code{native-inputs} et @code{inputs} est nécessaire -lorsqu'on considère la compilation croisée. Lors d'une compilation croisée, -les dépendances listées dans @code{inputs} sont construites pour -l'architecture @emph{cible} ; inversement, les dépendances listées dans -@code{native-inputs} sont construites pour l'architecture de la machine de -@emph{construction}. - -@code{native-inputs} est typiquement utilisé pour lister les outils requis à -la construction mais pas à l'exécution, comme Autoconf, Automake, -pkg-config, Gettext ou Bison. @command{guix lint} peut rapporter des -erreurs de ce type (@pxref{Invoquer guix lint}). - -@anchor{package-propagated-inputs} -Enfin, @code{propagated-inputs} est similaire à @code{inputs}, mais les -paquets spécifiés seront automatiquement installés avec le paquet auquel ils -appartiennent (@pxref{package-cmd-propagated-inputs, @command{guix -package}}, pour des informations sur la manière dont @command{guix package} -traite les entrées propagées). - -Par exemple cela est nécessaire lorsque des bibliothèques C/C++ ont besoin -d'en-têtes d'une autre bibliothèque pour être compilé ou lorsqu'un fichier -pkg-config se rapporte à un autre @i{via} son champ @code{Requires}. - -Un autre exemple où @code{propagated-inputs} est utile est pour les langages -auxquels il manque un moyen de retenir le chemin de recherche comme c'est le -cas du @code{RUNPATH} des fichiers ELF ; cela comprend Guile, Python, Perl -et plus. Pour s'assurer que les bibliothèques écrites dans ces langages -peuvent trouver le code des bibliothèques dont elles dépendent à -l'exécution, les dépendances à l'exécution doivent être listées dans -@code{propagated-inputs} plutôt que @code{inputs}. - -@item @code{outputs} (par défaut : @code{'("out")}) -La liste des noms de sorties du paquet. @xref{Des paquets avec plusieurs résultats}, pour des exemples typiques d'utilisation de sorties -supplémentaires. - -@item @code{native-search-paths} (par défaut : @code{'()}) -@itemx @code{search-paths} (par défaut : @code{'()}) -Une liste d'objets @code{search-path-specification} décrivant les variables -d'environnement de recherche de chemins que ce paquet utilise. - -@item @code{replacement} (par défaut : @code{#f}) -Ce champ doit être soit @code{#f} soit un objet de paquet qui sera utilisé -comme @dfn{remplaçant} de ce paquet. @xref{Mises à jour de sécurité, grafts}, pour -plus de détails. - -@item @code{synopsis} -Une description sur une ligne du paquet. - -@item @code{description} -Une description plus détaillée du paquet. - -@item @code{license} -@cindex licence, des paquets -La licence du paquet ; une valeur tirée de @code{(guix licenses)} ou une -liste de ces valeurs. - -@item @code{home-page} -L'URL de la page d'accueil du paquet, en tant que chaîne de caractères. - -@item @code{supported-systems} (par défaut : @var{%supported-systems}) -La liste des systèmes supportés par le paquet, comme des chaînes de -caractères de la forme @code{architecture-noyau}, par exemple -@code{"x86_64-linux"}. - -@item @code{maintainers} (par défaut : @code{'()}) -La liste des mainteneurs du paquet, comme des objets @code{maintainer}. - -@item @code{location} (par défaut : emplacement de la source de la forme @code{package}) -L'emplacement de la source du paquet. C'est utile de le remplacer lorsqu'on -hérite d'un autre paquet, auquel cas ce champ n'est pas automatiquement -corrigé. -@end table -@end deftp - -@deffn {Scheme Syntax} this-package -When used in the @emph{lexical scope} of a package field definition, this -identifier resolves to the package being defined. - -The example below shows how to add a package as a native input of itself -when cross-compiling: - -@example -(package - (name "guile") - ;; ... - - ;; When cross-compiled, Guile, for example, depends on - ;; a native version of itself. Add it here. - (native-inputs (if (%current-target-system) - `(("self" ,this-package)) - '()))) -@end example - -It is an error to refer to @code{this-package} outside a package definition. -@end deffn - -@node Référence des origines -@subsection Référence de @code{origin} - -Cette section résume toutes les options disponibles dans le déclarations -@code{origin} (@pxref{Définition des paquets}). - -@deftp {Type de données} origin -C'est le type de donnée qui représente l'origine d'un code source. - -@table @asis -@item @code{uri} -Un objet contenant l'URI de la source. Le type d'objet dépend de la -@code{method} (voir plus bas). Par exemple, avec la méthode @var{url-fetch} -de @code{(guix download)}, les valeurs valide d'@code{uri} sont : une URL -représentée par une chaîne de caractères, ou une liste de chaînes de -caractères. - -@item @code{method} -Un procédure qui gère l'URI. - -Quelques exemples : - -@table @asis -@item @var{url-fetch} de @code{(guix download)} -télécharge un fichier depuis l'URL HTTP, HTTPS ou FTP spécifiée dans le -champ @code{uri} ; - -@vindex git-fetch -@item @var{git-fetch} de @code{(guix git-download)} -clone le dépôt sous contrôle de version Git et récupère la révision -spécifiée dans le champ @code{uri} en tant qu'objet @code{git-reference} ; -un objet @code{git-reference} ressemble à cela : - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -Un bytevector contenant le hash SHA-256 de la source. Typiquement la forme -@code{base32} est utilisée ici pour générer le bytevector depuis une chaîne -de caractères en base-32. - -Vous pouvez obtenir cette information avec @code{guix download} -(@pxref{Invoquer guix download}) ou @code{guix hash} (@pxref{Invoquer guix hash}). - -@item @code{file-name} (par défaut : @code{#f}) -Le nom de fichier à utiliser pour sauvegarder le fichier. Lorsqu'elle est à -@code{#f}, une valeur par défaut raisonnable est utilisée dans la plupart -des cas. Dans le cas où la source est récupérée depuis une URL, le nom de -fichier est celui de l'URL. Pour les sources récupérées depuis un outil de -contrôle de version, il est recommandé de fournir un nom de fichier -explicitement parce que le nom par défaut n'est pas très descriptif. - -@item @code{patches} (par défaut : @code{'()}) -Une liste de noms de fichiers, d'origines ou d'objets simili-fichiers -(@pxref{G-Expressions, file-like objects}) qui pointent vers des correctifs -à appliquer sur la source. - -Cette liste de correctifs doit être inconditionnelle. En particulier, elle -ne peut pas dépendre des valeurs de @code{%current-system} ou -@code{%current-target-system}. - -@item @code{snippet} (par défaut : @code{#f}) -Une G-expression (@pxref{G-Expressions}) ou une S-expression qui sera lancée -dans le répertoire des sources. C'est une manière pratique de modifier la -source, parfois plus qu'un correctif. - -@item @code{patch-flags} (par défaut : @code{'("-p1")}) -Une liste de drapeaux à passer à la commande @code{patch}. - -@item @code{patch-inputs} (par défaut : @code{#f}) -Paquets d'entrées ou dérivations pour le processus de correction. -Lorsqu'elle est à @code{#f}, l'ensemble d'entrées habituellement nécessaire -pour appliquer des correctifs est fournit, comme GNU@tie{}Patch. - -@item @code{modules} (par défaut : @code{'()}) -Une liste de modules Guile qui devraient être chargés pendant le processus -de correction et pendant que le lancement du code du champ @code{snippet}. - -@item @code{patch-guile} (par défaut : @code{#f}) -Le paquet Guile à utiliser dans le processus de correction. Lorsqu'elle est -à @code{#f}, une valeur par défaut raisonnable est utilisée. -@end table -@end deftp - - -@node Systèmes de construction -@section Systèmes de construction - -@cindex système de construction -Chaque définition de paquet définie un @dfn{système de construction} et des -arguments pour ce système de construction (@pxref{Définition des paquets}). Ce -champ @code{build-system} représente la procédure de construction du paquet, -ainsi que des dépendances implicites pour cette procédure de construction. - -Les systèmes de construction sont des objets -@code{}. L'interface pour les créer et les manipuler est -fournie par le module @code{(guix build-system)} et les systèmes de -construction eux-mêmes sont exportés par des modules spécifiques. - -@cindex sac (représentation à bas-niveau des paquets) -Sous le capot, les systèmes de construction compilent d'abord des objets -paquets en @dfn{sacs}. Un @dfn{sac} est comme un paquet, mais avec moins de -décoration — en d'autres mots, un sac est une représentation à bas-niveau -d'un paquet, qui inclus toutes les entrées de ce paquet, dont certaines ont -été implicitement ajoutées par le système de construction. Cette -représentation intermédiaire est ensuite compilée en une dérivation -(@pxref{Dérivations}). - -Les systèmes de construction acceptent une liste d'@dfn{arguments} -facultatifs. Dans les définitions de paquets, ils sont passés @i{via} le -champ @code{arguments} (@pxref{Définition des paquets}). Ce sont typiquement des -arguments par mot-clef (@pxref{Optional Arguments, keyword arguments in -Guile,, guile, GNU Guile Reference Manual}). La valeur de ces arguments est -habituellement évaluée dans la @dfn{strate de construction} — c.-à-d.@: par -un processus Guile lancé par le démon (@pxref{Dérivations}). - -Le système de construction principal est le @var{gnu-build-system} qui -implémente les procédures de construction standard pour les paquets GNU et -de nombreux autres. Il est fournit par le module @code{(guix build-system -gnu)}. - -@defvr {Variable Scheme} gnu-build-system -@var{gnu-build-system} représente le système de construction GNU et ses -variantes (@pxref{Configuration, configuration and makefile conventions,, -standards, GNU Coding Standards}). - -@cindex phases de construction -En résumé, les paquets qui l'utilisent sont configurés, construits et -installés avec la séquence @code{./configure && make && make check && make -install} habituelle. En pratique, des étapes supplémentaires sont souvent -requises. Toutes ces étapes sont séparées dans des @dfn{phases} -différentes, notamment@footnote{Regardez les modules @code{(guix build -gnu-build-system)} pour plus de détails sur les phases de construction.}: - -@table @code -@item unpack -Décompresse l'archive des sources et se déplace dans l'arborescence des -sources fraîchement extraites. Si la source est en fait un répertoire, le -copie dans l'arborescence de construction et entre dans ce répertoire. - -@item patch-source-shebangs -Corrige les shebangs (@code{#!}) rencontrés dans les fichiers pour qu'ils se -réfèrent aux bons noms de fichiers. Par exemple, elle change -@code{#!/bin/sh} en @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. - -@item configure -Lance le script @code{configure} avec un certain nombre d'options par -défaut, comme @code{--prefix=/gnu/store/@dots{}}, ainsi que les options -spécifiées par l'argument @code{#:configure-flags}. - -@item build -Lance @code{make} avec la liste des drapeaux spécifiés avec -@code{#:make-flags}. Si l'argument @code{#:parallel-build?} est vrai (par -défaut), construit avec @code{make -j}. - -@item check -Lance @code{make check}, ou une autre cible spécifiée par -@code{#:test-target}, à moins que @code{#:tests? #f} ne soit passé. Si -l'argument @code{#:parallel-tests?} est vrai (par défaut), lance @code{make -check -j}. - -@item install -Lance @code{make install} avec les drapeaux listés dans @code{#:make-flags}. - -@item patch-shebangs -Corrige les shebangs des fichiers exécutables installés. - -@item strip -Nettoie les symboles de débogage dans les fichiers ELF (à moins que -@code{#:strip-binaries?} ne soit faux), les copie dans la sortie -@code{debug} lorsqu'elle est disponible (@pxref{Installer les fichiers de débogage}). -@end table - -@vindex %standard-phases -Le module du côté du constructeur @code{(guix build gnu-build-system)} -définie @var{%standard-phases} comme la liste par défaut des phases de -construction. @var{%standard-phases} est une liste de paires de symboles -et de procédures, où la procédure implémente la phase en question. - -La liste des phases utilisées par un paquet particulier peut être modifiée -avec le paramètre @code{#:phases}. Par exemple, en passant : - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -signifie que toutes les procédures décrites plus haut seront utilisées, sauf -la phase @code{configure}. - -En plus, ce système de construction s'assure que l'environnement « standard -» pour les paquets GNU est disponible. Cela inclus des outils comme GCC, -libc, Coreutils, Bash, Make, Diffutils, grep et sed (voir le module -@code{(guix build-system gnu)} pour une liste complète). Nous les appelons -les @dfn{entrées implicites} d'un paquet parce que la définition du paquet -ne les mentionne pas. -@end defvr - -D'autres objets @code{} sont définis pour supporter d'autres -conventions et outils utilisés par les paquets de logiciels libres. Ils -héritent de la plupart de @var{gnu-build-system} et diffèrent surtout dans -l'ensemble des entrées implicites ajoutées au processus de construction et -dans la liste des phases exécutées. Certains de ces systèmes de -construction sont listés ci-dessous. - -@defvr {Variable Scheme} ant-build-system -Cette variable est exportée par @code{(guix build-system ant)}. Elle -implémente la procédure de construction pour les paquets Java qui peuvent -être construits avec @url{http://ant.apache.org/, l'outil de construction -Ant}. - -Elle ajoute à la fois @code{ant} et the @dfn{kit de développement Java} -(JDK) fournit par le paquet @code{icedtea} à l'ensemble des entrées. Des -paquets différents peuvent être spécifiés avec les paramètres @code{#:ant} -et @code{#:jdk} respectivement. - -Lorsque le paquet d'origine ne fournit pas de fichier de construction Ant -acceptable, le paramètre @code{#:jar-name} peut être utilisé pour générer un -fichier de construction Ant @file{build.xml} minimal, avec des tâches pour -construire l'archive jar spécifiée. Dans ce cas, le paramètre -@code{#:source-dir} peut être utilisé pour spécifier le sous-répertoire des -sources, par défaut « src ». - -Le paramètre @code{#:main-class} peut être utilisé avec le fichier de -construction minimal pour spécifier la classe principale du jar. Cela rend -le fichier jar exécutable. Le paramètre @code{#:test-include} peut être -utilisé pour spécifier la liste des tests junits à lancer. Il vaut par -défaut @code{(list "**/*Test.java")}. Le paramètre @code{#:test-exclude} -peut être utilisé pour désactiver certains tests. Sa valeur par défaut est -@code{(list "**/Abstract*.java")}, parce que les classes abstraites ne -peuvent pas être utilisées comme des tests. - -Le paramètre @code{#:build-target} peut être utilisé pour spécifier la tâche -Ant qui devrait être lancée pendant la phase @code{build}. Par défaut la -tâche « jar » sera lancée. - -@end defvr - -@defvr {Variable Scheme} android-ndk-build-system -@cindex Distribution android -@cindex système de construction Android NDK -Cette variable est exportée par @code{(guix build-system android-ndk)}. -Elle implémente une procédure de construction pour les paquets du NDK -Android (@i{native development kit}) avec des processus de construction -spécifiques à Guix. - -Le système de construction suppose que les paquets installent leur interface -publique (les en-têtes) dans un sous-répertoire de « include » de la sortie -« out » et leurs bibliothèques dans le sous-répertoire « lib » de la sortie -« out ». - -Il est aussi supposé que l'union de toutes les dépendances d'un paquet n'a -pas de fichiers en conflit. - -Pour l'instant, la compilation croisée n'est pas supportées — donc pour -l'instant les bibliothèques et les fichiers d'en-têtes sont supposés être -des outils de l'hôte. - -@end defvr - -@defvr {Variable Scheme} asdf-build-system/source -@defvrx {Variable Scheme} asdf-build-system/sbcl -@defvrx {Variable Scheme} asdf-build-system/ecl - -Ces variables, exportées par @code{(guix build-system asdf)}, implémentent -les procédures de constructions pour les paquets en Common Lisp qui -utilisent @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF est -un dispositif de définition de systèmes pour les programmes et les -bibliothèques en Common Lisp. - -Le système @code{asdf-build-system/source} installe les paquets au format -source qui peuvent être chargés avec n'importe quelle implémentation de -common lisp, via ASDF. Les autres, comme @code{asdf-build-system/sbcl}, -installent des binaires au format qu'un implémentation particulière -comprend. Ces systèmes de constructions peuvent aussi être utilisés pour -produire des programmes exécutables ou des images lisp qui contiennent un -ensemble de paquets pré-chargés. - -Le système de construction utilise des conventions de nommage. Pour les -paquets binaires, le nom du paquet devrait être préfixé par l'implémentation -lisp, comme @code{sbcl-} pour @code{asdf-build-system/sbcl}. - -En plus, le paquet source correspondant devrait étiquetté avec la même -convention que les paquets python (voir @ref{Modules python}), avec le -préfixe @code{cl-}. - -Pour les paquets binaires, chaque système devrait être défini comme un -paquet Guix. Si un paquet @code{origine} contient plusieurs systèmes, on -peut créer des variantes du paquet pour construire tous les systèmes. Les -paquets sources, qui utilisent @code{asdf-build-system/source}, peuvent -contenir plusieurs systèmes. - -Pour créer des programmes exécutables et des images, les procédures côté -construction @code{build-program} et @code{build-image} peuvent être -utilisées. Elles devraient être appelées dans une phase de construction -après la phase @code{create-symlinks} pour que le système qui vient d'être -construit puisse être utilisé dans l'image créée. @code{build-program} -requiert une liste d'expressions Common Lisp dans l'argument -@code{#:entry-program}. - -Si le système n'est pas défini dans son propre fichier @code{.asd} du même -nom, alors le paramètre @code{#:asd-file} devrait être utilisé pour -spécifier dans quel fichier le système est défini. De plus, si le paquet -défini un système pour ses tests dans un fichier séparé, il sera chargé -avant que les tests ne soient lancés s'il est spécifié par le paramètre -@code{#:test-asd-file}. S'il n'est pas spécifié, les fichiers -@code{-tests.asd}, @code{-test.asd}, @code{tests.asd} et -@code{test.asd} seront testés. - -Si pour quelque raison que ce soit le paquet doit être nommé d'une manière -différente de ce que la convention de nommage suggère, le paramètre -@code{#:asd-system-name} peut être utilisé pour spécifier le nom du système. - -@end defvr - -@defvr {Variable Scheme} cargo-build-system -@cindex Langage de programmation Rust -@cindex Cargo (système de construction Rust) -Cette variable est exportée par @code{(guix build-system cargo)}. Elle -supporte les construction de paquets avec Cargo, le système de construction -du @uref{https://www.rust-lang.org, langage de programmation Rust}. - -Dans sa phase @code{configure}, ce système de construction remplace les -dépendances spécifiées dans le fichier @file{Cargo.toml} par des paquets -Guix. La phase @code{install} installe les binaires et installe aussi le -code source et le fichier @file{Cargo.toml}. -@end defvr - -@cindex Clojure (langage de programmation) -@cindex système de construction Clojure simple -@defvr {Variable Scheme} clojure-build-system -Cette variable est exportée par @code{(guix build-system clojure)}. Elle -implémente une procédure de construction des paquets simple qui utilise le -bon vieux @code{compile} de Clojure. La compilation croisée n'est pas -encore supportée. - -Elle ajoute @code{clojure}, @code{icedtea} et @code{zip} à l'ensemble des -entrées. Des paquets différents peuvent être spécifiés avec les paramètres -@code{#:clojure}, @code{#:jdk} et @code{#:zip}. - -Une liste de répertoires sources, de répertoires de tests et de noms de jar -peuvent être spécifiés avec les paramètres @code{#:source-dirs}, -@code{#:test-dirs} et @code{#:jar-names}. Le répertoire de construction est -la classe principale peuvent être spécifiés avec les paramètres -@code{#:compile-dir} et @code{#:main-class}. Les autres paramètres sont -documentés plus bas. - -Ce système de construction est une extension de @var{ant-build-system}, mais -avec les phases suivantes modifiées : - -@table @code - -@item build -Cette phase appelle @code{compile} en Clojure pour compiler les fichiers -sources et lance @command{jar} pour créer les fichiers jar à partir des -fichiers sources et des fichiers compilés en suivant la liste d'inclusion et -d'exclusion spécifiées dans @code{#:aot-include} et @code{#:aot-exclude}. -La liste d'exclusion a la priorité sur la liste d'inclusion. Ces listes -consistent en des symboles représentant des bibliothèque Clojure ou le mot -clef spécial @code{#:all}, représentant toutes les bibliothèques Clojure -trouvées dans les répertoires des sources. Le paramètre -@code{#:omit-source?} décide si les sources devraient être incluses dans les -fichiers jar. - -@item check -Cette phase lance les tests en suivant les liste d'inclusion et d'exclusion -spécifiées dans @code{#:test-include} et @code{#:test-exclude}. Leur -signification est analogue à celle de @code{#:aot-include} et -@code{#:aot-exclude}, sauf que le mot-clef spécial @code{#:all} signifie -maintenant toutes les bibliothèques Clojure trouvées dans les répertoires de -tests. Le paramètre @code{#:tests?} décide si les tests devraient être -lancés. - -@item install -Cette phase installe tous les fichiers jar précédemment construits. -@end table - -En dehors de cela, le système de construction contient aussi la phase -suivante : - -@table @code - -@item install-doc -Cette phase installe tous les fichiers dans le répertoire de plus haut -niveau dont le nom correspond à @var{%doc-regex}. On peut spécifier une -regex différente avec le paramètre @code{#:doc-regex}. Tous les fichiers -(récursivement) dans les répertoires de documentations spécifiés dans -@code{#:doc-dirs} sont aussi installés. -@end table -@end defvr - -@defvr {Variable Scheme} cmake-build-system -Cette variable est exportée par @code{(guix build-system cmake)}. Elle -implémente la procédure de construction des paquets qui utilisent -l'@url{http://www.cmake.org, outil de construction CMake}. - -Elle ajoute automatiquement le paquet @code{cmake} à l'ensemble des -entrées. Le paquet utilisé peut être spécifié par le paramètre -@code{#:cmake}. - -Le paramètre @code{#:configure-flags} est pris comme une liste de drapeaux à -passer à la commande @command{cmake}. Le paramètre @code{#:build-type} -spécifie en termes abstrait les drapeaux passés au compilateur ; sa valeur -par défaut est @code{"RelWithDebInfo"} (ce qui veut dire « mode public avec -les informations de débogage » en plus court), ce qui signifie en gros que -le code sera compilé avec @code{-O2 -g} comme pour les paquets autoconf par -défaut. -@end defvr - -@defvr {Variable Scheme} dune-build-system -Cette variable est exportée par @code{(guix build-system dune)}. Elle prend -en charge la construction des paquets qui utilisent -@uref{https://dune.build/, Dune}, un outil de construction pour le langage -de programmation OCaml. Elle est implémentée comme une extension de -@code{ocaml-build-system} décrit plus bas. En tant que tel, les paramètres -@code{#:ocaml} et @code{#:findlib} peuvent être passés à ce système de -construction. - -Elle ajoute automatiquement le paquet @code{dune} à l'ensemble des entrées. -Le paquet utilisé peut être spécifié par le paramètre @code{#:dune}. - -Il n'y a pas de phase @code{configure} parce que les paquets dune n'ont -habituellement pas besoin d'être configurés. Le paramètre -@code{#:build-flags} est interprété comme une liste de drapeaux pour la -commande @code{dune} pendant la construction. - -Le paramètre @code{#:jbuild?} peut être passé pour utiliser la commande -@code{jbuild} à la place de la commande @code{dune} plus récente pour la -construction d'un paquet. Sa valeur par défaut est @code{#f}. - -Le paramètre @code{#:package} peut être passé pour spécifié un nom de -paquet, ce qui est utile lorsqu'un paquet contient plusieurs paquets et que -vous voulez n'en construire qu'un. C'est équivalent à passer l'argument -@code{-p} à @code{dune}. -@end defvr - -@defvr {Variable Scheme} go-build-system -Cette variable est exportée par @code{(guix build-system go)}. Elle -implémente la procédure pour les paquets Go utilisant les -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, -mécanismes de construction Go} standard. - -L'utilisateur doit fournir une valeur à la clef @code{#:import-path} et, -dans certains cas, @code{#:unpack-path}. Le -@url{https://golang.org/doc/code.html#ImportPaths, chemin d'import} -correspond au chemin dans le système de fichiers attendu par le script de -construction du paquet et les paquets qui s'y réfèrent et fournit une -manière unique de se référer à un paquet Go. Il est typiquement basé sur -une combinaison de l'URI du code source du paquet et d'une structure -hiérarchique du système de fichier. Dans certains cas, vous devrez extraire -le code source du paquet dans une structure de répertoires différente que -celle indiquée par le chemin d'import et @code{#:unpack-path} devrait être -utilisé dans ces cas-là. - -Les paquets qui fournissent des bibliothèques Go devraient installer leur -code source dans la sortie du paquet. La clef @code{#:install-source?}, qui -vaut @code{#t} par défaut, contrôle l'installation du code source. Elle -peut être mise à @code{#f} pour les paquets qui ne fournissent que des -fichiers exécutables. -@end defvr - -@defvr {Variable Scheme} glib-or-gtk-build-system -Cette variable est exportée par @code{(guix build-system glib-or-gtk)}. -Elle est conçue pour être utilisée par des paquets qui utilisent GLib ou -GTK+. - -Ce système de construction ajoute les deux phases suivantes à celles -définies par @var{gnu-build-system} : - -@table @code -@item glib-or-gtk-wrap -La phase @code{glib-or-gtk-wrap} s'assure que les programmes dans -@file{bin/} sont capable de trouver les « schemas » GLib et les -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, modules -GTK+}. Ceci est fait en enveloppant les programmes dans des scripts de -lancement qui initialisent correctement les variables d'environnement -@code{XDG_DATA_DIRS} et @code{GTK_PATH}. - -Il est possible d'exclure des sorties spécifiques de ce processus -d'enveloppage en listant leur nom dans le paramètre -@code{#:glib-or-gtk-wrap-excluded-outputs}. C'est utile lorsqu'une sortie -est connue pour ne pas contenir de binaires GLib ou GTK+, et où l'enveloppe -ajouterait une dépendance inutile vers GLib et GTK+. - -@item glib-or-gtk-compile-schemas -La phase @code{glib-or-gtk-compile-schemas} s'assure que tous les -@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -schémas GSettings} de GLib sont compilés. La compilation est effectuée par -le programme @command{glib-compile-schemas}. Il est fournit par le paquet -@code{glib:bin} qui est automatiquement importé par le système de -construction. Le paquet @code{glib} qui fournit -@command{glib-compile-schemas} peut être spécifié avec le paramètre -@code{#:glib}. -@end table - -Ces deux phases sont exécutées après la phase @code{install}. -@end defvr - -@defvr {Variable Scheme} guile-build-system -Ce système de construction sert aux paquets Guile qui consistent -exclusivement en code Scheme et qui sont si simple qu'ils n'ont même pas un -makefile, sans parler d'un script @file{configure}. Il compile le code -Scheme en utilisant @command{guild compile} (@pxref{Compilation,,, guile, -GNU Guile Reference Manual}) et installe les fichiers @file{.scm} et -@file{.go} aux bons emplacements. Il installe aussi la documentation. - -Ce système de construction supporte la compilation croisée en utilisant -l'option @code{--target} de @command{guild compile}. - -Les paquets construits avec @code{guile-build-system} doivent fournir un -paquet Guile dans leur champ @code{native-inputs}. -@end defvr - -@defvr {Variable Scheme} minify-build-system -Cette variable est exportée par @code{(guix build-system minify)}. Elle -implémente une procédure de minification pour des paquets JavaScript -simples. - -Elle ajoute @code{uglify-js} à l'ensemble des entrées et l'utilise pour -compresser tous les fichiers JavaScript du répertoire @file{src}. Un -minifieur différent peut être spécifié avec le paramètre @code{#:uglify-js} -mais il est attendu que ce paquet écrive le code minifié sur la sortie -standard. - -Lorsque les fichiers JavaScript d'entrée ne sont pas situés dans le -répertoire @file{src}, le paramètre @code{#:javascript-files} peut être -utilisé pour spécifier une liste de noms de fichiers à donner au minifieur. -@end defvr - -@defvr {Variable Scheme} ocaml-build-system -Cette variable est exportée par @code{(guix build-system ocaml)}. Elle -implémente une procédure de construction pour les paquets -@uref{https://ocaml.org, OCaml} qui consiste à choisir le bon ensemble de -commande à lancer pour chaque paquet. Les paquets OCaml peuvent demander -des commandes diverses pour être construit. Ce système de construction en -essaye certaines. - -Lorsqu'un fichier @file{setup.ml} est présent dans le répertoire de plus -haut niveau, elle lancera @code{ocaml setup.ml -configure}, @code{ocaml -setup.ml -build} et @code{ocaml setup.ml -install}. Le système de -construction supposera que ces fichiers ont été générés par -@uref{http://oasis.forge.ocamlcore.org/, OASIS} et prendra soin -d'initialiser le préfixe et d'activer les tests s'ils ne sont pas -désactivés. Vous pouvez passer des drapeaux de configuration et de -construction avec @code{#:configure-flags} et @code{#:build-flags}. La clef -@code{#:test-flags} peut être passée pour changer l'ensemble des drapeaux -utilisés pour activer les tests. La clef @code{#:use-make?} peut être -utilisée pour outrepasser ce système dans les phases de construction et -d'installation. - -Lorsque le paquet a un fichier @file{configure}, il est supposé qu'il s'agit -d'un script configure écrit à la main qui demande un format différent de -celui de @code{gnu-build-system}. Vous pouvez ajouter plus de drapeaux avec -la clef @code{#:configure-flags}. - -Lorsque le paquet a un fichier @file{Makefile} (ou @code{#:use-make?} vaut -@code{#t}), il sera utilisé et plus de drapeaux peuvent être passés à la -construction et l'installation avec la clef @code{#:make-flags}. - -Enfin, certains paquets n'ont pas ces fichiers mais utilisent un emplacement -plus ou moins standard pour leur système de construction. Dans ce cas, le -système de construction lancera @code{ocaml pkg/pkg.ml} ou -@code{pkg/build.ml} et prendra soin de fournir le chemin du module findlib -requis. Des drapeaux supplémentaires peuvent être passés via la clef -@code{#:bulid-flags}. L'installation se fait avec -@command{opam-installer}. Dans ce cas, le paquet @code{opam} doit être -ajouté au champ @code{native-inputs} de la définition du paquet. - -Remarquez que la plupart des paquets OCaml supposent qu'ils seront installés -dans le même répertoire qu'OCaml, ce qui n'est pas ce que nous voulons faire -dans Guix. En particulier, ils installeront leurs fichiers @file{.so} dans -leur propre répertoire de module, ce qui est normalement correct puisqu'il -s'agit du répertoire du compilateur OCaml. Dans Guix en revanche, le -bibliothèques ne peuvent pas y être trouvées et on utilise -@code{CAML_LD_LIBRARY_PATH} à la place. Cette variable pointe vers -@file{lib/ocaml/site-lib/stubslibs} et c'est là où les bibliothèques -@file{.so} devraient être installées. -@end defvr - -@defvr {Variable Scheme} python-build-system -Cette variable est exportée par @code{(guix build-system python)}. Elle -implémente la procédure de construction plus ou moins standard utilisée pour -les paquets Python, qui consiste à lancer @code{python setup.py build} puis -@code{python setup.py install --prefix=/gnu/store/@dots{}}. - -Pour les paquets qui installent des programmes autonomes dans @code{bin/}, -elle prend soin d'envelopper ces binaires pour que leur variable -d'environnement @code{PYTHONPATH} pointe vers toutes les bibliothèques -Python dont ils dépendent. - -Le paquet Python utilisé pour effectuer la construction peut être spécifié -avec le paramètre @code{#:python}. C'est une manière utile de forcer un -paquet à être construit avec une version particulière de l'interpréteur -python, ce qui peut être nécessaire si le paquet n'est compatible qu'avec -une version de l'interpréteur. - -Par défaut Guix appelle @code{setup.py} sous le contrôle de -@code{setuptools}, comme le fait @command{pip}. Certains paquets ne sont -pas compatibles avec setuptools (et pip), ainsi vous pouvez désactiver cela -en mettant le paramètre @code{#:use-setuptools} à @code{#f}. -@end defvr - -@defvr {Variable Scheme} perl-build-system -Cette variable est exportée par @code{(guix build-system perl)}. Elle -implémente la procédure de construction standard des paquets Perl, qui -consiste soit à lancer @code{perl Build.PL --prefix=/gnu/store/@dots{}}, -suivi de @code{Build} et @code{Build install} ; ou à lancer @code{perl -Makefile.PL PREFIX=/gnu/store/@dots{}}, suivi de @code{make} et @code{make -install}, en fonction de la présence de @code{Build.PL} ou -@code{Makefile.PL} dans la distribution du paquet. Le premier a la -préférence si @code{Build.PL} et @code{Makefile.PL} existent tous deux dans -la distribution du paquet. Cette préférence peut être inversée en -spécifiant @code{#t} pour le paramètre @code{#:make-maker?}. - -L'invocation initiale de @code{perl Makefile.PL} ou @code{perl Build.PL} -passe les drapeaux spécifiés par le paramètre @code{#:make-maker-flags} ou -@code{#:module-build-flags}, respectivement. - -Le paquet Perl utilisé peut être spécifié avec @code{#:perl}. -@end defvr - -@defvr {Variable Scheme} r-build-system -Cette variable est exportée par @code{(guix build-system r)}. Elle -implémente la procédure de construction utilisée par les paquets -@uref{http://r-project.org, R} qui consiste à lancer à peine plus que -@code{R CMD INSTALL --library=/gnu/store/@dots{}} dans un environnement où -@code{R_LIBS_SITE} contient les chemins de toutes les entrées R. Les tests -sont lancés après l'installation avec la fonction R -@code{tools::testInstalledPackage}. -@end defvr - -@defvr {Variable Scheme} rakudo-build-system -Cette variable est exportée par @code{(guix build-system rakudo)}. Elle -implémente la procédure de construction utilisée par -@uref{https://rakudo.org/, Rakudo} pour les paquets -@uref{https://perl6.org/, Perl6}. Elle installe le paquet dans -@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} et installe les binaires, -les fichiers de bibliothèques et les ressources, et enveloppe les fichiers -dans le répertoire @code{bin/}. Les tests peuvent être passés en indiquant -@code{#f} au paramètres @code{tests?}. - -Le paquet rakudo utilisé peut être spécifié avec @code{rakudo}. Le paquet -perl6-tap-harness utilisé pour les tests peut être spécifié avec -@code{#:prove6} ou supprimé en passant @code{#f} au paramètre -@code{with-prove6?}. Le paquet perl6-zef utilisé pour les tests et -l'installation peut être spécifié avec @code{#:ef} ou supprimé en passant -@code{#f} au paramètre @code{with-zef?}. -@end defvr - -@defvr {Variable Scheme} texlive-build-system -Cette variable est exportée par @code{(guix build-system texlive)}. Elle -est utilisée pour construire des paquets TeX en mode batch avec le moteur -spécifié. Le système de construction initialise la variable -@code{TEXINPUTS} pour trouver tous les fichiers source TeX dans ses entrées. - -Par défaut, elle lance @code{luatex} sur tous les fichiers qui se terminent -par @code{ins}. Un moteur et un format différent peuvent être spécifiés -avec l'argument @code{#:tex-format}. Plusieurs cibles de constructions -peuvent être indiquées avec l'argument @code{#:build-targets} qui attend une -liste de noms de fichiers. Le système de construction ajoute uniquement -@code{texlive-bin} et @code{texlive-latex-base} (de @code{(gnu packages -tex)} à la liste des entrées. Les deux peuvent être remplacés avec les -arguments @code{#:texlive-bin} et @code{#:texlive-latex-base}, -respectivement. - -Le paramètre @code{#:tex-directory} dit au système de construction où -installer les fichiers construit dans l'arbre texmf. -@end defvr - -@defvr {Variable Scheme} ruby-build-system -Cette variable est exportée par @code{(guix build-system ruby)}. Elle -implémenter la procédure de construction RubyGems utilisée par les paquets -Ruby qui consiste à lancer @code{gem build} suivi de @code{gem install}. - -Le champ @code{source} d'un paquet qui utilise ce système de construction -référence le plus souvent une archive gem, puisque c'est le format utilisé -par les développeurs Ruby quand ils publient leur logiciel. Le système de -construction décompresse l'archive gem, éventuellement en corrigeant les -sources, lance la suite de tests, recompresse la gemme et l'installe. En -plus, des répertoires et des archives peuvent être référencés pour permettre -de construire des gemmes qui n'ont pas été publiées depuis Git ou une -archive de sources traditionnelle. - -Le paquet Ruby utilisé peut être spécifié avec le paramètre @code{#:ruby}. -Une liste de drapeaux supplémentaires à passer à la commande @command{gem} -peut être spécifiée avec le paramètre @code{#:gem-flags}. -@end defvr - -@defvr {Variable Scheme} waf-build-system -Cette variable est exportée par @code{(guix build-system waf)}. Elle -implémente une procédure de construction autour du script @code{waf}. Les -phases usuelles — @code{configure}, @code{build} et @code{install} — sont -implémentée en passant leur nom en argument au script @code{waf}. - -Le script @code{waf} est exécuté par l'interpréteur Python. Le paquet -Python utilisé pour lancer le script peut être spécifié avec le paramètre -@code{#:python}. -@end defvr - -@defvr {Variable Scheme} scons-build-system -Cette variable est exportée par @code{(guix build-system scons)}. Elle -implémente la procédure de construction utilisée par l'outil de construction -SCons. Ce système de construction lance @code{scons} pour construire le -paquet, @code{scons test} pour lancer les tests puis @code{scons install} -pour installer le paquet. - -On peut passer des drapeaux supplémentaires à @code{scons} en les spécifiant -avec le paramètre @code{#:scons-flags}. La version de python utilisée pour -lancer SCons peut être spécifiée en sélectionnant le paquet SCons approprié -avec le paramètre @code{#:scons}. -@end defvr - -@defvr {Variable Scheme} haskell-build-system -Cette variable est exportée par @code{(guix build-system haskell)}. Elle -implémente la procédure de construction Cabal utilisée par les paquets -Haskell, qui consiste à lancer @code{runhaskell Setup.hs configure ---prefix=/gnu/store/@dots{}} et @code{runhaskell Setup.hs build}. Plutôt -que d'installer le paquets en lançant @code{runhaskell Setup.hs install}, -pour éviter d'essayer d'enregistrer les bibliothèques dans le répertoire du -dépôt en lecture-seule du compilateur, le système de construction utilise -@code{runhaskell Setup.hs copy}, suivi de @code{runhaskell Setup.hs -register}. En plus, le système de construction génère la documentation du -paquet en lançant @code{runhaskell Setup.hs haddock}, à moins que -@code{#:haddock? #f} ne soit passé. Des paramètres facultatifs pour Haddock -peuvent être passés à l'aide du paramètre @code{#:haddock-flags}. Si le -fichier @code{Setup.hs} n'est pas trouvé, le système de construction -cherchera @code{Setup.lhs} à la place. - -Le compilateur Haskell utilisé peut être spécifié avec le paramètre -@code{#:haskell} qui a pour valeur par défaut @code{ghc}. -@end defvr - -@defvr {Variable Scheme} dub-build-system -Cette variable est exportée par @code{(guix build-system dub)}. Elle -implémente la procédure de construction Dub utilisée par les paquets D qui -consiste à lancer @code{dub build} et @code{dub run}. L'installation est -effectuée en copiant les fichiers manuellement. - -Le compilateur D utilisé peut être spécifié avec le paramètre @code{#:ldc} -qui vaut par défaut @code{ldc}. -@end defvr - -@defvr {Variable Scheme} emacs-build-system -Cette variable est exportée par @code{(guix build-system emacs)}. Elle -implémente une procédure d'installation similaire au système de gestion de -paquet d'Emacs lui-même (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Elle crée d'abord le fichier @code{@var{package}-autoloads.el}, puis compile -tous les fichiers Emacs Lisp en bytecode. Contrairement au système de -gestion de paquets d'Emacs, les fichiers de documentation info sont déplacés -dans le répertoire standard et le fichier @file{dir} est supprimé. Chaque -paquet est installé dans son propre répertoire dans -@file{share/emacs/site-lisp/guix.d}. -@end defvr - -@defvr {Variable Scheme} font-build-system -Cette variable est exportée par @code{(guix build-system font)}. Elle -implémente une procédure d'installation pour les paquets de polices où des -fichiers de polices TrueType, OpenType, etc.@: sont fournis en amont et -n'ont qu'à être copiés à leur emplacement final. Elle copie les fichiers de -polices à l'emplacement standard dans le répertoire de sortie. -@end defvr - -@defvr {Variable Scheme} meson-build-system -Cette variable est exportée par @code{(guix build-system meson)}. Elle -implémente la procédure de construction des paquets qui utilisent -@url{http://mesonbuild.com, Meson} comme système de construction. - -Elle ajoute à la fois Meson et @uref{https://ninja-build.org/, Ninja} à -l'ensemble des entrées, et ils peuvent être modifiés avec les paramètres -@code{#:meson} et @code{#:ninja} si requis. Le Meson par défaut est -@code{meson-for-build}, qui est spécial parce qu'il ne nettoie pas le -@code{RUNPATH} des binaires et les bibliothèques qu'il installe. - -Ce système de construction est une extension de @var{gnu-build-system}, mais -avec les phases suivantes modifiées pour Meson : - -@table @code - -@item configure -La phase lance @code{meson} avec les drapeaux spécifiés dans -@code{#:configure-flags}. Le drapeau @code{--build-type} est toujours -initialisé à @code{plain} à moins que quelque chose d'autre ne soit spécifié -dans @code{#:build-type}. - -@item build -La phase lance @code{ninja} pour construire le paquet en parallèle par -défaut, mais cela peut être changé avec @code{#:parallel-build?}. - -@item check -La phase lance @code{ninja} avec la cible spécifiée dans -@code{#:test-target}, qui est @code{"test"} par défaut. - -@item install -La phase lance @code{ninja install} et ne peut pas être changée. -@end table - -En dehors de cela, le système de construction ajoute aussi la phase suivante -: - -@table @code - -@item fix-runpath -Cette phase s'assure que tous les binaire peuvent trouver les bibliothèques -dont ils ont besoin. Elle cherche les bibliothèques requises dans les -sous-répertoires du paquet en construction et les ajoute au @code{RUNPATH} -là où c'est nécessaire. Elle supprime aussi les références aux -bibliothèques laissées là par la phase de construction par -@code{meson-for-build} comme les dépendances des tests, qui ne sont pas -vraiment requises pour le programme. - -@item glib-or-gtk-wrap -Cette phase est la phase fournie par @code{glib-or-gtk-build-system} et -n'est pas activée par défaut. Elle peut l'être avec @code{#:glib-or-gtk?}. - -@item glib-or-gtk-compile-schemas -Cette phase est la phase fournie par @code{glib-or-gtk-build-system} et -n'est pas activée par défaut. Elle peut l'être avec @code{#:glib-or-gtk?}. -@end table -@end defvr - -@defvr {Scheme Variable} linux-module-build-system -@var{linux-module-build-system} allows building Linux kernel modules. - -@cindex phases de construction -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed: - -@table @code - -@item configure -This phase configures the environment so that the Linux kernel's Makefile -can be used to build the external kernel module. - -@item build -This phase uses the Linux kernel's Makefile in order to build the external -kernel module. - -@item install -This phase uses the Linux kernel's Makefile in order to install the external -kernel module. -@end table - -It is possible and useful to specify the Linux kernel to use for building -the module (in the "arguments" form of a package using the -linux-module-build-system, use the key #:linux to specify it). -@end defvr - -Enfin, pour les paquets qui n'ont pas besoin de choses sophistiquées, un -système de construction « trivial » est disponible. Il est trivial dans le -sens où il ne fournit en gros aucun support : il n'apporte pas de dépendance -implicite, et n'a pas de notion de phase de construction. - -@defvr {Variable Scheme} trivial-build-system -Cette variable est exportée par @code{(guix build-system trivial)}. - -Ce système de construction requiert un argument @code{#:builder}. Cet -argument doit être une expression Scheme qui construit la sortie du paquet — -comme avec @code{build-expression->derivation} (@pxref{Dérivations, -@code{build-expression->derivation}}). -@end defvr - -@node Le dépôt -@section Le dépôt - -@cindex dépôt -@cindex éléments du dépôt -@cindex chemins dans le dépôt - -Conceptuellement, le @dfn{dépôt} est l'endroit où les dérivations qui ont -bien été construites sont stockées — par défaut, @file{/gnu/store}. Les -sous-répertoires dans le dépôt s'appellent des @dfn{éléments du dépôt} ou -parfois des @dfn{chemins du dépôt}. Le dépôt a une base de données associée -qui contient des informations comme les chemins du dépôt auxquels se -réfèrent chaque chemin du dépôt et la liste des éléments du dépôt -@emph{valides} — les résultats d'une construction réussie. Cette base de -données se trouve dans @file{@var{localstatedir}/guix/db} où -@var{localstatedir} est le répertoire d'états spécifié @i{via} @option -{--localstatedir} à la configuration, typiquement @file{/var}. - -C'est @emph{toujours} le démon qui accède au dépôt pour le compte de ses -clients (@pxref{Invoquer guix-daemon}). Pour manipuler le dépôt, les -clients se connectent au démon par un socket Unix-domain, envoient une -requête dessus et lisent le résultat — ce sont des appels de procédures -distantes, ou RPC. - -@quotation Remarque -Les utilisateurs ne doivent @emph{jamais} modifier les fichiers dans -@file{/gnu/store} directement. Cela entraînerait des incohérences et -casserait l'hypothèse d'immutabilité du modèle fonctionnel de Guix -(@pxref{Introduction}). - -@xref{Invoquer guix gc, @command{guix gc --verify}}, pour des informations -sur la manière de vérifier l'intégrité du dépôt et d'essayer de réparer des -modifications accidentelles. -@end quotation - -Le module @code{(guix store)} fournit des procédures pour se connecter au -démon et pour effectuer des RPC. Elles sont décrites plus bas. Par défaut, -@code{open-connection}, et donc toutes les commandes @command{guix} se -connectent au démon local ou à l'URI spécifiée par la variable -d'environnement @code{GUIX_DAEMON_SOCKET}. - -@defvr {Variable d'environnement} GUIX_DAEMON_SOCKET -Lorsqu'elle est initialisée, la valeur de cette variable devrait être un nom -de fichier ou une URI qui désigne l'extrémité du démon. Lorsque c'est un -nom de fichier, il dénote un socket Unix-domain où se connecter. En plus -des noms de fichiers, les schémas d'URI supportés sont : - -@table @code -@item file -@itemx unix -Pour les sockets Unix-domain. @code{file:///var/guix/daemon-socket/socket} -est équivalent à @file{/var/guix/daemon-socket/socket}. - -@item guix -@cindex démon, accès distant -@cindex accès distant au démon -@cindex démon, paramètres de grappes -@cindex grappes, paramètres du démon -Ces URI dénotent des connexions par TCP/IP, sans chiffrement ni -authentification de l'hôte distant. L'URI doit spécifier le nom d'hôte et -éventuellement un numéro de port (par défaut 44146) : - -@example -guix://master.guix.example.org:1234 -@end example - -Ce paramétrage est adapté aux réseaux locaux, comme dans le cas de grappes -de serveurs, où seuls des noms de confiance peuvent se connecter au démon de -construction sur @code{master.guix.example.org}. - -L'option @code{--listen} de @command{guix-daemon} peut être utilisé pour lui -dire d'écouter des connexions TCP (@pxref{Invoquer guix-daemon, -@code{--listen}}). - -@item ssh -@cindex accès SSH au démon de construction -Ces URI vous permettent de vous connecter au démon à distance à travers -SSH@footnote{Cette fonctionnalité requiert Guile-SSH -(@pxref{Prérequis}).}. Une URL typique pourrait ressembler à ceci : - -@example -ssh://charlie@@guix.example.org:22 -@end example - -Comme pour @command{guix copy}, les fichiers de configuration du client -OpenSSH sont respectés (@pxref{Invoquer guix copy}). -@end table - -Des schémas d'URI supplémentaires pourraient être supportés dans le futur. - -@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 Remarque -La capacité de se connecter à un démon de construction distant est considéré -comme expérimental à la version @value{VERSION}. Contactez-nous pour -partager vos problèmes ou des suggestions que vous pourriez avoir -(@pxref{Contribuer}). -@end quotation -@end defvr - -@deffn {Procédure Scheme} open-connection [@var{uri}] [#:reserve-space? #t] -Se connecte au démon à travers le socket Unix-domain à @var{uri} (une chaîne -de caractères). Lorsque @var{reserve-space?} est vrai, cela demande de -réserver un peu de place supplémentaire sur le système de fichiers pour que -le ramasse-miette puisse opérer au cas où le disque serait plein. Renvoie -un objet serveur. - -@var{file} a pour valeur par défaut @var{%default-socket-path}, qui est -l'emplacement normal en fonction des options données à @command{configure}. -@end deffn - -@deffn {Procédure Scheme} close-connection @var{server} -Ferme la connexion au @var{serveur}. -@end deffn - -@defvr {Variable Scheme} current-build-output-port -Cette variable est liée à un paramètre SRFI-39, qui se réfère au port où les -journaux de construction et d'erreur envoyés par le démon devraient être -écrits. -@end defvr - -Les procédures qui font des RPC prennent toutes un objet serveur comme -premier argument. - -@deffn {Procédure Scheme} valid-path? @var{server} @var{path} -@cindex éléments du dépôt invalides -Renvoie @code{#t} lorsque @var{path} désigne un élément du dépôt valide et -@code{#f} sinon (un élément invalide peut exister sur le disque mais rester -invalide, par exemple parce que c'est le résultat d'une construction annulée -ou échouée). - -Une condition @code{&store-protocol-error} est levée si @var{path} n'est pas -préfixée par le répertoire du dépôt (@file{/gnu/store}). -@end deffn - -@deffn {Procédure Scheme} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] -Ajoute @var{text} dans le fichier @var{name} dans le dépôt et renvoie son -chemin. @var{references} est la liste des chemins du dépôt référencés par -le chemin du dépôt qui en résulte. -@end deffn - -@deffn {Procédure Scheme} build-derivations @var{server} @var{derivations} -Construit @var{derivaton} (ne liste d'objets @code{} ou de -chemins de dérivations) et retourne quand le travailleur a fini de les -construire. Renvoie @code{#t} en cas de réussite. -@end deffn - -Remarque que le module @code{(guix monads)} fournit une monade ainsi que des -version monadiques des procédures précédentes, avec le but de rendre plus -facile de travailler avec le code qui accède au dépôt (@pxref{La monade du dépôt}). - -@c FIXME -@i{Cette section est actuellement incomplète.} - -@node Dérivations -@section Dérivations - -@cindex dérivations -Les actions de construction à bas-niveau et l'environnement dans lequel -elles sont effectuées sont représentés par des @dfn{dérivations}. Une -dérivation contient cet ensemble d'informations : - -@itemize -@item -Les sorties de la dérivation — les dérivations produisent au moins un -fichier ou répertoire dans le dépôt, mais peuvent en produire plus. - -@item -@cindex dépendances à la construction -@cindex construction, dépendances -Les entrées de la dérivation — c.-à-d.@: ses dépendances à la construction — -qui peuvent être d'autres dérivations ou des fichiers dans le dépôt -(correctifs, scripts de construction, etc). - -@item -Le type de système ciblé par la dérivation — p.ex.@: @code{x86_64-linux}. - -@item -Le nom de fichier d'un script de construction dans le dépôt avec les -arguments à lui passer. - -@item -Une liste de variables d'environnement à définir. - -@end itemize - -@cindex chemin de dérivation -Les dérivations permettent aux client du démon de communiquer des actions de -construction dans le dépôt. Elles existent sous deux formes : en tant que -représentation en mémoire, à la fois côté client et démon, et en tant que -fichiers dans le dépôt dont le nom fini par @code{.drv} — on dit que ce sont -des @dfn{chemins de dérivations}. Les chemins de dérivations peuvent être -passés à la procédure @code{build-derivations} pour effectuer les actions de -construction qu'ils prescrivent (@pxref{Le dépôt}). - -@cindex dérivations à sortie fixe -Des opérations comme le téléchargement de fichiers et la récupération de -sources gérés par un logiciel de contrôle de version pour lesquels le hash -du contenu est connu à l'avance sont modélisés par des @dfn{dérivations à -sortie fixe}. Contrairement aux dérivation habituelles, les sorties d'une -dérivation à sortie fixe sont indépendantes de ses entrées — p.ex.@: un code -source téléchargé produit le même résultat quelque soit la méthode de -téléchargement utilisée. - -@cindex references -@cindex dépendances à l'exécution -@cindex exécution, dépendances -Les sorties des dérivations — c.-à-d.@: les résultats de la construction — -ont un ensemble de @dfn{références}, comme le rapporte le RPC -@code{references} ou la commande @command{guix gc --references} -(@pxref{Invoquer guix gc}). Les références sont l'ensemble des dépendances -à l'exécution des résultats de la construction. Les références sont un -sous-ensemble des entrées de la dérivation ; ce sous-ensemble est -automatiquement calculé par le démon de construction en scannant tous les -fichiers dans les sorties. - -Le module @code{(guix derivations)} fournit une représentation des -dérivations comme des objets Scheme, avec des procédures pour créer et -manipuler des dérivations. La primitive de plus bas-niveau pour créer une -dérivation est la procédure @code{derivation} : - -@deffn {Procédure Scheme} derivation @var{store} @var{name} @var{builder} @ - @var{args} [#: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 '()] -Construit une dérivation avec les arguments donnés et renvoie l'objet -@code{} obtenu. - -Lorsque @var{hash} et @var{hash-algo} sont donnés, une @dfn{dérivation à -sortie fixe} est créée — c.-à-d.@: une dérivation dont le résultat est connu -à l'avance, comme dans le cas du téléchargement d'un fichier. Si, en plus, -@var{recursive?} est vrai, alors la sortie fixe peut être un fichier -exécutable ou un répertoire et @var{hash} doit être le hash d'une archive -contenant la sortie. - -Lorsque @var{references-graphs} est vrai, il doit s'agir d'une liste de -paires de noms de fichiers et de chemins du dépôt. Dans ce cas, le graphe -des références de chaque chemin du dépôt est exporté dans l'environnement de -construction dans le fichier correspondant, dans un simple format texte. - -Lorsque @var{allowed-references} est vrai, il doit s'agir d'une liste -d'éléments du dépôt ou de sorties auxquelles la sortie de la dérivations -peut faire référence. De même, @var{disallowed-references}, si vrai, doit -être une liste de choses que la sortie ne doit @emph{pas} référencer. - -Lorsque @var{leaked-env-vars} est vrai, il doit s'agir d'une liste de -chaînes de caractères qui désignent les variables d'environnements qui -peuvent « fuiter » de l'environnement du démon dans l'environnement de -construction. Ce n'est possible que pour les dérivations à sortie fixe — -c.-à-d.@: lorsque @var{hash} est vrai. L'utilisation principale est de -permettre à des variables comme @code{http_proxy} d'être passées aux -dérivations qui téléchargent des fichiers. - -Lorsque @var{local-build?} est vrai, déclare que la dérivation n'est pas un -bon candidat pour le déchargement et devrait plutôt être construit -localement (@pxref{Réglages du délestage du démon}). C'est le cas des petites -dérivations où le coût du transfert de données est plus important que les -bénéfices. - -Lorsque que @var{substitutable?} est faux, déclare que les substituts de la -sortie de la dérivation ne devraient pas être utilisés -(@pxref{Substituts}). Cela est utile par exemple pour construire des paquets -qui utilisent des détails du jeu d'instruction du CPU hôte. - -@var{properties} doit être une liste d'association décrivant les « -propriétés » de la dérivation. Elle est gardée telle-quelle, sans être -interprétée, dans la dérivation. -@end deffn - -@noindent -Voici un exemple avec un script shell comme constructeur, en supposant que -@var{store} est une connexion ouverte au démon et @var{bash} pointe vers un -exécutable Bash dans le dépôt : - -@lisp -(use-modules (guix utils) - (guix store) - (guix derivations)) - -(let ((builder ; ajoute le script Bash au dépôt - (add-text-to-store store "my-builder.sh" - "echo hello world > $out\n" '()))) - (derivation store "foo" - bash `("-e" ,builder) - #:inputs `((,bash) (,builder)) - #:env-vars '(("HOME" . "/homeless")))) -@result{} # /gnu/store/@dots{}-foo> -@end lisp - -Comme on pourrait s'en douter, cette primitive est difficile à utiliser -directement. Une meilleure approche est d'écrire les scripts de -construction en Scheme, bien sur ! Le mieux à faire pour cela est d'écrire -le code de construction comme une « G-expression » et de la passer à -@code{gexp->derivation}. Pour plus d'informations, @pxref{G-Expressions}. - -Il fut un temps où @code{gexp->derivation} n'existait pas et où construire -une dérivation donc le code de construction était écrit en Scheme se faisait -avec @code{build-expression->derivation}, documenté plus bas. Cette -procédure est maintenant obsolète, remplacée par @code{gexp->derivation} qui -est meilleure. - -@deffn {Procédure Scheme} build-expression->derivation @var{store} @ - @var{name} @var{exp} @ -[#: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] -Renvoie une dérivation qui exécute l'expression Scheme @var{exp} comme un -constructeur pour la dérivation @var{name}. @var{inputs} doit être une -liste de tuples @code{(name drv-path sub-drv)} ; lorsque @var{sub-drv} est -omis, @code{"out"} est utilisé. @var{modules} est une liste de noms de -modules Guile du chemin de recherche actuel qui seront copiés dans le dépôt, -compilés et rendus disponibles dans le chemin de chargement pendant -l'exécution de @var{exp} — p.@: ex.@: @code{((guix build utils) (guix build -gnu-build-system))}. - -@var{exp} est évaluée dans une environnement où @code{%outputs} est lié à -une liste de paires de sortie/chemin, et où @code{%build-inputs} est lié à -une liste de paires de chaînes de caractères et de chemin de sortie -construite à partir de @var{inputs}. Éventuellement, @var{env-vars} est une -liste de paires de chaînes de caractères spécifiant le nom et la valeur de -variables d'environnement visibles pour le constructeur. Le constructeur -termine en passant le résultat de @var{exp} à @code{exit} ; ainsi, lorsque -@var{exp} renvoie @code{#f}, la construction est considérée en échec. - -@var{exp} est construite avec @var{guile-for-build} (une dérivation). -Lorsque @var{guile-for-build} est omis où est @code{#f}, la valeur du fluide -@code{%guile-for-build} est utilisée à la place. - -Voir la procédure @code{derivation} pour la signification de -@var{references-graph}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?} et @var{substitutable?}. -@end deffn - -@noindent -Voici un exemple de dérivation à sortie unique qui crée un répertoire avec -un fichier : - -@lisp -(let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; create /gnu/store/@dots{}-goo - (call-with-output-file (string-append out "/test") - (lambda (p) - (display '(hello guix) p)))))) - (build-expression->derivation store "goo" builder)) - -@result{} # @dots{}> -@end lisp - - -@node La monade du dépôt -@section La monade du dépôt - -@cindex monad - -Les procédures qui travaillent sur le dépôt décrites dans les sections -précédentes prennent toutes une connexion ouverte au démon de construction -comme premier argument. Bien que le modèle sous-jacent soit fonctionnel, -elles ont soit des effets de bord, soit dépendent de l'état actuel du dépôt. - -Le premier point est embêtant : on doit se balader avec la connexion au -démon dans toutes ces fonctions, ce qui rend impossible le fait de composer -des fonctions qui ne prennent pas ce paramètre avec des fonctions qui le -prennent. Le deuxième point est problématique : comme les opérations sur le -dépôt ont des effets de bord ou dépendent d'états externes, elles doivent -être enchaînés correctement. - -@cindex valeurs monadiques -@cindex fonctions monadiques -C'est là que le module @code{(guix monads)} arrive à la rescousse. Ce -module fournit un cadre pour travailler avec des @dfn{monads}, en -particulier une monade très utile pour notre usage, la @dfn{monade du -dépôt}. Les monades sont des constructions qui permettent deux choses : -associer un « contexte » avec une valeur (dans notre cas, le contexte est le -dépôt) et construire une séquence de calculs (ici les calculs comprennent -des accès au dépôt). Les valeurs dans une monade — les valeurs qui -contiennent ce contexte supplémentaire — sont appelées des @dfn{valeurs -monadiques} ; les procédures qui renvoient ce genre de valeur sont appelées -des @dfn{procédures monadiques}. - -Considérez cette procédure « normale » : - -@example -(define (sh-symlink store) - ;; Renvoie une dérivation qui crée un lien symbolique vers l'exécutable « bash ». - (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 - -En utilisant @code{(guix monads)} et @code{(guix gexp)}, on peut la réécrire -en une fonction monadique : - -@example -(define (sh-symlink) - ;; Pareil, mais renvoie une valeur monadique. - (mlet %store-monad ((drv (package->derivation bash))) - (gexp->derivation "sh" - #~(symlink (string-append #$drv "/bin/bash") - #$output)))) -@end example - -Il y a plusieurs choses à remarquer avec cette deuxième version : le -paramètre @code{store} est maintenant implicitement « enfilé » dans les -appels aux procédures monadiques @code{package->derivation} et -@code{gexp->derivation}, et la valeur monadique renvoyée par -@code{package->derivation} est @dfn{liée} avec @code{mlet} plutôt qu'avec un -simple @code{let}. - -Il se trouve que l'appel à @code{package->derivation} peut même être omis -puisqu'il aura lieu implicitement, comme nous le verrons plus tard -(@pxref{G-Expressions}) : - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c -@c for the funny quote. -L'appel à la procédure monadique @code{sh-symlink} n'a aucun effet. Comme -on pourrait le dire, « on sort d'une monade comme de la monarchie : en -l'exécutant »@footnote{NdT : il y a là un jeu de mot en anglais qui se base -sur un double sens de « run », qui peut se traduire par « exécuter » dans ce -contexte.}. Donc, pour sortir de la monade et obtenir l'effet escompté, on -doit utiliser @code{run-with-store}. - -@example -(run-with-store (open-connection) (sh-symlink)) -@result{} /gnu/store/...-sh-symlink -@end example - -Remarquez que le module @code{(guix monad-repl)} étend la console Guile avec -de nouvelles « méta-commandes » pour rendre plus facile la manipulation de -procédures monadiques : @code{run-in-store} et @code{enter-store-monad}. La -première est utilisée pour « lancer » une seule valeur monadique à travers -le dépôt : - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = # @dots{}> -@end example - -La deuxième entre dans une console récursive, où toutes les valeurs de -retour sont automatiquement lancées à travers le dépôt : - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = # @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Remarquez qu'on ne peut pas renvoyer de valeur non monadique dans la console -@code{store-monad}. - -Les formes syntaxiques principales pour utiliser des monades en général sont -disponibles dans le module @code{(guix monads)} et sont décrites ci-dessous. - -@deffn {Syntaxe Scheme} with-monad @var{monad} @var{body} ... -Évalue n'importe quelle forme @code{>>=} ou @code{return} dans @var{body} -comme une @var{monad}. -@end deffn - -@deffn {Syntaxe Scheme} return @var{val} -Renvoie une valeur monadique qui encapsule @var{val}. -@end deffn - -@deffn {Syntaxe Scheme} >>= @var{mval} @var{mproc} ... -@dfn{Lie} une valeur monadique @var{mval}, en passant son « contenu » aux -procédures monadiques @var{mproc}@dots{}@footnote{Cette opération est -souvent appelée « bind », mais ce nom dénote une procédure qui n'a rien à -voir en Guile. Ainsi, nous empruntons ce symbole quelque peu cryptique au -langage Haskell}. Il peut y avoir une ou plusieurs @code{mproc}, comme dans -cet exemple : - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'some-state) - -@result{} 4 -@result{} some-state -@end example -@end deffn - -@deffn {Syntaxe Scheme} mlet @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -@deffnx {Syntaxe Scheme} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -Lie les variables @var{var} aux valeurs monadiques @var{mval} dans -@var{body}, une séquence d'expressions. Comme avec l'opérateur de liaison, -on peut réfléchir comme si on « ouvrait » la valeur non-monadique « contenue -» dans @var{mval} et comme si on faisait en sorte que @var{var} se réfère à -cette valeur pure, non-monadique, dans la portée de @var{body}. La forme -(@var{var} -> @var{val}) lie @var{var} à la valeur « normale » @var{val}, -comme @code{let}. L'opération de liaison a lieu en séquence de la gauche -vers la droite. La dernière expression de @var{body} doit être une -expression monadique et son résultat deviendra le résultat de @code{mlet} ou -@code{mlet*} lorsque lancé dans la @var{monad}. - -@code{mlet*} est à @code{mlet} ce que @code{let*} est à @code{let} -(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn - -@deffn {Système Scheme} mbegin @var{monad} @var{mexp} ... -Lie @var{mexp} et les expressions monadiques suivantes en séquence, et -renvoie le résultat de la dernière expression. Chaque expression dans la -séquence doit être une expression monadique. - -Cette procédure est similaire à @code{mlet}, sauf que les valeurs de retour -des expressions monadiques sont ignorées. Dans ce sens, elle est analogue à -@code{begin}, mais appliqué à des expressions monadiques. -@end deffn - -@deffn {Système Scheme} mwhen @var{condition} @var{mexp0} @var{mexp*} ... -Lorsque la @var{condition} est vraie, évalue la séquence des expressions -monadiques @var{mexp0}..@var{mexp*} comme dans un @code{mbegin}. Lorsque la -@var{condition} est fausse, renvoie @code{*unspecified*} dans la monade -actuelle. Chaque expression dans la séquence doit être une expression -monadique. -@end deffn - -@deffn {Système Scheme} munless @var{condition} @var{mexp0} @var{mexp*} ... -Lorsque la @var{condition} est fausse, évalue la séquence des expressions -monadiques @var{mexp0}..@var{mexp*} comme dans un @code{mbegin}. Lorsque la -@var{condition} est vraie, renvoie @code{*unspecified*} dans la monade -actuelle. Chaque expression dans la séquence doit être une expression -monadique. -@end deffn - -@cindex monade d'état -Le module @code{(guix monads)} fournit la @dfn{monade d'état} qui permet à -une valeur supplémentaire — l'état — d'être enfilée à travers les appels de -procédures. - -@defvr {Variable Scheme} %state-monad -La monade d'état. les procédure dans la monade d'état peuvent accéder et -modifier l'état qui est enfilé. - -Considérez l'exemple ci-dessous. La procédure @code{square} renvoie une -valeur dans la monade d'état. Elle renvoie le carré de son argument, mais -incrémente aussi la valeur actuelle de l'état : - -@example -(define (square x) - (mlet %state-monad ((count (current-state))) - (mbegin %state-monad - (set-current-state (+ 1 count)) - (return (* x x))))) - -(run-with-state (sequence %state-monad (map square (iota 3))) 0) -@result{} (0 1 4) -@result{} 3 -@end example - -Lorsqu'on la lance à travers @var{%state-monad}, on obtient cet valeur -d'état supplémentaire, qui est le nombre d'appels à @code{square}. -@end defvr - -@deffn {Procédure monadique} current-state -Renvoie l'état actuel dans une valeur monadique. -@end deffn - -@deffn {Procédure monadique} set-current-state @var{value} -Initialise l'état actuel à @var{value} et renvoie l'état précédent dans une -valeur monadique. -@end deffn - -@deffn {Procédure monadique} state-push @var{value} -Pousse @var{value} sur l'état actuel, qui est supposé être une liste, et -renvoie l'état précédent dans une valeur monadique. -@end deffn - -@deffn {Procédure monadique} state-pop -Récupère (pop) une valeur dans l'état actuel et la renvoie comme une valeur -monadique. L'état est supposé être une liste. -@end deffn - -@deffn {Procédure Scheme} run-with-state @var{mval} [@var{state}] -Lance la valeur monadique @var{mval} avec @var{state} comme valeur -initiale. Renvoie deux valeurs : la valeur du résultat et l'état du -résultat. -@end deffn - -L'interface principale avec la monade du dépôt, fournit par le module -@code{(guix store)}, est la suivante. - -@defvr {Variable Scheme} %store-monad -La monade du dépôt — un alias pour @var{%state-monad}. - -Les valeurs dans la monade du dépôt encapsulent des accès au dépôt. Lorsque -son effet est requis, une valeur de la monade du dépôt doit être « évaluée » -en la passant à la procédure @code{run-with-store} (voir plus bas). -@end defvr - -@deffn {Procédure Scheme} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] -Lance @var{mval}, une valeur monadique dans la monade du dépôt, dans -@var{store}, une connexion ouvert au dépôt. -@end deffn - -@deffn {Procédure monadique} text-file @var{name} @var{text} [@var{references}] -Renvoie une valeur monadique correspondant au nom de fichier dans le dépôt -du fichier contenant @var{text}, une chaîne de caractères. @var{references} -est une liste d'éléments du dépôt auxquels le fichier texte en résultat se -réfère ; c'est la liste vide par défaut. -@end deffn - -@deffn {Procédure monadique} binary-file @var{name} @var{data} [@var{references}] -Renvoie une valeur monadique correspondant au nom de fichier absolu dans le -dépôt du fichier contenant @var{data}, un vecteur d'octets. -@var{references} est une liste d'éléments du dépôt auxquels le fichier -binaire en résultat se réfère ; c'est la liste vide par défaut. -@end deffn - -@deffn {Procédure monadique} interned-file @var{file} [@var{name}] @ - [#:recursive? #t] [#:select? (const #t)] -Renvoie le nom de @var{file} une fois ajouté au dépôt. Utilise @var{name} -comme nom dans le dépôt ou le nom de fichier de @var{file} si @var{name} est -omis. - -Lorsque @var{recursive?} est vraie, le contenu de @var{file} est ajouté -récursivement ; si @var{file} désigne un fichier simple et que -@var{recursive?} est vrai, son contenu est ajouté et ses bits de permissions -sont préservés. - -Lorsque @var{recursive?} est vraie, appelle @code{(@var{select?} @var{file} -@var{stat})} pour chaque répertoire où @var{file} est le nom de fichier -absolu de l'entrée et @var{stat} est le résultat de @code{lstat} ; à -l'exception des entrées pour lesquelles @var{select?} ne renvoie pas vrai. - -L'exemple ci-dessous ajoute un fichier au dépôt, sous deux noms différents : - -@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 - -Le module @code{(guix packages)} exporte les procédures monadiques liées aux -paquets suivantes : - -@deffn {Procédure monadique} package-file @var{package} [@var{file}] @ - [#:system (%current-system)] [#:target #f] @ -[#:output "out"] -Renvoie une valeur monadique qui contient le nom de fichier absolu de -@var{file} dans le répertoire @var{output} de @var{package}. Lorsque -@var{file} est omis, renvoie le nom du répertoire @var{output} de -@var{package}. Lorsque @var{target} est vrai, l'utilise comme un triplet de -cible pour la compilation croisée. -@end deffn - -@deffn {Procédure monadique} package->derivation @var{package} [@var{system}] -@deffnx {Procédure monadique} package->cross-derivation @var{package} @ - @var{target} [@var{system}] -Version monadique de @code{package-derivation} et -@code{package-cross-derivation} (@pxref{Définition des paquets}). -@end deffn - - -@node G-Expressions -@section G-Expressions - -@cindex G-expression -@cindex quoting du code de construction -On a donc des « dérivations » qui représentent une séquence d'actions de -construction à effectuer pour produire un élément du dépôt -(@pxref{Dérivations}). Ces actions de construction sont effectuées -lorsqu'on demande au démon de construire effectivement les dérivations ; -elles sont lancées par le démon dans un conteneur (@pxref{Invoquer guix-daemon}). - -@cindex strate de code -Ça ne devrait pas vous surprendre, mais nous aimons écrire ces actions de -construction en Scheme. Lorsqu'on fait ça, on fini avec deux @dfn{strates} -de code Scheme@footnote{Le terme @dfn{strate} dans ce contexte a été inventé -par Manuel Serrano et ses collaborateurs dans le contexte de leur travaux -sur Hop. Oleg Kiselyov, qui a écrit des -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essais perspicaces -et du code sur le sujet}, utilise le terme de « mise en scène » pour ce -genre de génération de code.} : le « code hôte » — le code qui défini les -paquets, parle au démon, etc — et le « code côté construction » — le code -qui effectue effectivement les actions de construction, comme créer des -répertoires, invoquer @code{make}, etc. - -Pour décrire une dérivation et ses actions de construction, on a typiquement -besoin d'intégrer le code de construction dans le code hôte. Ça revient à -manipuler le code de construction comme de la donnée, et l'homoiconicité de -Scheme — le code a une représentation directe en tant que donnée — est très -utile pour cela. Mais on a besoin de plus que le mécanisme de -@code{quasiquote} en Scheme pour construire des expressions de construction. - -Le module @code{(guix gexp)} implémente les @dfn{G-expressions}, une forme -de S-expression adaptée aux expressions de construction. Les G-expression, -ou @dfn{gexps}, consistent en gros en trois formes syntaxiques : -@code{gexp}, @code{ungexp} et @code{ungexp-splicing} (ou plus simplement : -@code{#~}, @code{#$} et @code{#$@@}), qui sont comparable à -@code{quasiquote}, @code{unquote} et @code{unquote-splicing} respectivement -(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile Reference -Manual}). Cependant il y a des différences majeures : - -@itemize -@item -Les Gexps sont conçues pour être écrites dans un fichier et être lancées ou -manipulées par d'autres processus. - -@item -Lorsqu'un objet de haut-niveau comme un paquet ou une dérivation est -unquotée dans une gexp, le résultat est comme si le nom de fichier de son -résultat avait été introduit. - -@item -Les gexps transportent des informations sur les paquets ou les dérivations -auxquels elles se réfèrent, et ces dépendances sont automatiquement ajoutées -comme des entrées du processus de construction qui les utilise. -@end itemize - -@cindex abaissement, des objets haut-niveau dans les gepxs -Ce mécanisme n'est pas limité aux paquets et aux dérivations : on peut -définir des @dfn{compilateurs} capable « d'abaisser » d'autres objets de -haut-niveau ou des fichiers dans le dépôt, pour que ces objets puissent -aussi être insérés dans des gexps. Par exemple, des objets haut-niveau -utiles qui pourraient être insérées dans une gexp sont les « objets -simili-fichiers », qui rendent facile l'ajout de fichiers dans le dépôt et -les références vers eux dans les dérivations et autres (voir -@code{local-file} et @code{plain-file} ci-dessous). - -Pour illustrer cette idée, voici un exemple de gexp : - -@example -(define build-exp - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "list-files"))) -@end example - -Cette gexp peut être passée à @code{gexp->derivation} ; on obtient une -dérivation qui construit une répertoire contenant exactement un lien -symbolique à @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls} : - -@example -(gexp->derivation "the-thing" build-exp) -@end example - -Comme on pourrait s'y attendre, la chaîne -@code{"/gnu/store/@dots{}-coreutils-8.22"} est substituée à la place de la -référence au paquet @var{coreutils} dans le code de construction final, et -@var{coreutils} est automatiquement devenu une entrée de la dérivation. De -même, @code{#$output} (équivalent à @code{(ungexp output)}) est remplacé par -une chaîne de caractères contenant le nom du répertoire de la sortie de la -dérivation. - -@cindex compilation croisée -Dans le contexte d'une compilation croisée, il est utile de distinguer entre -des références à la construction @emph{native} d'un paquet — qui peut être -lancé par l'hôte — et des références à la construction croisée d'un paquet. -Pour cela, @code{#+} joue le même rôle que @code{#$}, mais référence une -construction native d'un paquet : - -@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 -Dans l'exemple ci-dessus, la construction native de @var{coreutils} est -utilisée, pour que @command{ln} puisse effectivement être lancé sur l'hôte ; -mais ensuite la construction croisée d'@var{emacs} est utilisée. - -@cindex modules importés, pour les gexps -@findex with-imported-modules -Une autre fonctionnalité, ce sont les @dfn{modules importés} : parfois vous -voudriez pouvoir utiliser certains modules Guile de « l'environnement hôte » -dans la gexp, donc ces modules devraient être importés dans « -l'environnement de construction ». La forme @code{with-imported-modules} -vous permet d'exprimer ça : - -@example -(let ((build (with-imported-modules '((guix build utils)) - #~(begin - (use-modules (guix build utils)) - (mkdir-p (string-append #$output "/bin")))))) - (gexp->derivation "empty-dir" - #~(begin - #$build - (display "success!\n") - #t))) -@end example - -@noindent -Dans cet exemple, le module @code{(guix build utils)} est automatiquement -récupéré dans l'environnement de construction isolé de notre gexp, pour que -@code{(use-modules (guix build utils))} fonctionne comme on s'y attendrait. - -@cindex closure de module -@findex source-module-closure -Typiquement, vous voudriez que la @emph{closure} complète du module soit -importé — c.-à-d.@: le module lui-même et tous les modules dont il dépend — -plutôt que seulement le module ; sinon, une tentative de chargement du -module échouera à cause des modules dépendants manquants. La procédure -@code{source-module-closure} calcule la closure d'un module en cherchant -dans ses en-têtes sources, ce qui est pratique dans ce cas : - -@example -(use-modules (guix modules)) ;pour 'source-module-closure' - -(with-imported-modules (source-module-closure - '((guix build utils) - (gnu build vm))) - (gexp->derivation "something-with-vms" - #~(begin - (use-modules (guix build utils) - (gnu build vm)) - @dots{}))) -@end example - -@cindex extensions, des gexps -@findex with-extensions -Dans la même idée, parfois vous pouvez souhaiter importer non seulement des -modules en Scheme pur, mais aussi des « extensions » comme des liaisons -Guile de bibliothèques C ou d'autres paquet « complets ». Disons que vous -voulez utiliser le paquet @code{guile-json} du côté de la construction, -voici comme procéder : - -@example -(use-modules (gnu packages guile)) ;pour 'guile-json' - -(with-extensions (list guile-json) - (gexp->derivation "something-with-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -La forme syntaxique pour construire des gexps est résumée ci-dessous. - -@deffn {Syntaxe Scheme} #~@var{exp} -@deffnx {Syntaxe Scheme} (gexp @var{exp}) -Renvoie une G-expression contenant @var{exp}. @var{exp} peut contenir une -ou plusieurs de ces formes : - -@table @code -@item #$@var{obj} -@itemx (ungexp @var{obj}) -Introduit une référence à @var{obj}. @var{obj} peut être d'un des types -supportés, par exemple un paquet ou une dérivation, auquel cas la forme -@code{ungexp} est remplacée par le nom de fichier de sa sortie — p.@: ex.@: -@code{"/gnu/store/@dots{}-coreutils-8.22}. - -Si @var{boj} est une liste, elle est traversée et les références aux objets -supportés sont substitués de manière similaire. - -Si @var{obj} est une autre gexp, son contenu est inséré et ses dépendances -sont ajoutées à celle de la gexp qui l'entoure. - -Si @var{obj} est un autre type d'objet, il est inséré tel quel. - -@item #$@var{obj}:@var{output} -@itemx (ungexp @var{obj} @var{output}) -Cette forme est similaire à la précédente, mais se réfère explicitement à la -sortie @var{output} de l'objet @var{obj} — c'est utile lorsque @var{obj} -produit plusieurs sorties (@pxref{Des paquets avec plusieurs résultats}). - -@item #+@var{obj} -@itemx #+@var{obj}:output -@itemx (ungexp-native @var{obj}) -@itemx (ungexp-native @var{obj} @var{output}) -Comme @code{ungexp}, mais produit une référence à la construction -@emph{native} de @var{obj} lorsqu'elle est utilisée dans une compilation -croisée. - -@item #$output[:@var{output}] -@itemx (ungexp output [@var{output}]) -Insère une référence à la sortie @var{output} de la dérivation, ou à la -sortie principale lorsque @var{output} est omis. - -Cela ne fait du sens que pour les gexps passées à @code{gexp->derivation}. - -@item #$@@@var{lst} -@itemx (ungexp-splicing @var{lst}) -Comme au dessus, mais recolle (@i{splice}) le contenu de @var{lst} dans la -liste qui la contient. - -@item #+@@@var{lst} -@itemx (ungexp-native-splicing @var{lst}) -Comme au dessus, mais se réfère à la construction native des objets listés -dans @var{lst}. - -@end table - -Les G-expressions crées par @code{gexp} ou @code{#~} sont des objets à -l'exécution du type @code{gexp?} (voir plus bas). -@end deffn - -@deffn {Syntaxe Scheme} with-imported-modules @var{modules} @var{body}@dots{} -Marque les gexps définies dans @var{body}@dots{} comme requérant -@var{modules} dans leur environnement d'exécution. - -Chaque élément dans @var{module} peut être le nom d'un module, comme -@code{(guix build utils)} ou le nom d'un module suivi d'une flèche, suivie -d'un objet simili-fichier : - -@example -`((guix build utils) - (guix gcrypt) - ((guix config) => ,(scheme-file "config.scm" - #~(define-module @dots{})))) -@end example - -@noindent -Dans l'exemple au dessus, les deux premiers modules sont récupérés dans le -chemin de recherche, et le dernier est créé à partir d'un objet -simili-fichier. - -Cette forme a une portée @emph{lexicale} : elle a un effet sur les gexp -directement définies dans @var{body}@dots{}, mais pas sur celles définies -dans des procédures appelées par @var{body}@dots{}. -@end deffn - -@deffn {Syntaxe Scheme} with-extensions @var{extensions} @var{body}@dots{} -Marque les gexps définies dans @var{body}@dots{} comme requérant -@var{extensions} dans leur environnement de construction et d'exécution. -@var{extensions} est typiquement une liste d'objets paquets comme définis -dans le module @code{(gnu packages guile)}. - -Concrètement, les paquets listés dans @var{extensions} sont ajoutés au -chemin de chargement lors de la compilation des modules importés dans -@var{body}@dots{} ; ils sont aussi ajoutés au chemin de chargement de la -gexp renvoyée par @var{body}@dots{}. -@end deffn - -@deffn {Procédure Scheme} gexp? @var{obj} -Renvoie @code{#t} si @var{obj} est une G-expression. -@end deffn - -Les G-expressions sont conçues pour être écrites sur le disque, soit en tant -que code pour construire une dérivation, soit en tant que fichier normal -dans le dépôt. Les procédure monadiques suivantes vous permettent de faire -cela (@pxref{La monade du dépôt}, pour plus d'information sur les monads). - -@deffn {Procédure monadique} gexp->derivation @var{name} @var{exp} @ - [#: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] -Renvoie une dérivation @var{name} qui lance @var{exp} (une gexp) avec -@var{guile-for-build} (une dérivation) sur @var{system} ; @var{exp} est -stocké dans un fichier appelé @var{script-name}. Lorsque @var{target} est -vraie, elle est utilisée comme triplet de cible de compilation croisée pour -les paquets référencés par @var{exp}. - -@var{modules} est devenu obsolète en faveur de -@code{with-imported-modules}. Sa signification est de rendre @var{modules} -disponibles dans le contexte d'évaluation de @var{exp} ; @var{modules} est -une liste de noms de modules Guile qui sont cherchés dans @var{module-path} -pour les copier dans le dépôt, les compiler et les rendre disponibles dans -le chemin de chargement pendant l'exécution de @var{exp} — p.@: ex.@: -@code{((guix build utils) (guix build gnu-build-system))}. - -@var{effective-version} détermine la chaîne à utiliser lors d'ajout -d'extensions de @var{exp} (voir @code{with-extensions}) au chemin de -recherche — p.@: ex.@: @code{"2.2"}. - -@var{graft?} détermine si les paquets référencés par @var{exp} devraient -être greffés si possible. - -Lorsque @var{references-graphs} est vrai, il doit s'agir d'une liste de -tuples de la forme suivante : - -@example -(@var{file-name} @var{package}) -(@var{file-name} @var{package} @var{output}) -(@var{file-name} @var{derivation}) -(@var{file-name} @var{derivation} @var{output}) -(@var{file-name} @var{store-item}) -@end example - -La partie droite des éléments de @var{references-graphs} est automatiquement -transformée en une entrée du processus de construction @var{exp}. Dans -l'environnement de construction, chaque @var{file-name} contient le graphe -des références de l'élément correspondant, dans un format texte simple. - -@var{allowed-references} doit soit être @code{#f}, soit une liste de noms de -sorties ou de paquets. Dans ce dernier cas, la liste dénote les éléments du -dépôt auxquels le résultat a le droit de faire référence. Toute référence à -un autre élément du dépôt conduira à une erreur à la construction. Comme -pour @var{disallowed-references}, qui peut lister des éléments qui ne -doivent pas être référencés par les sorties. - -@var{deprecation-warnings} détermine s'il faut afficher les avertissement -d'obsolescence à la compilation de modules. Il peut valoir @code{#f}, -@code{t} ou @code{'detailed}. - -Les autres arguments sont les mêmes que pour @code{derivation} -(@pxref{Dérivations}). -@end deffn - -@cindex objets simili-fichiers -Les procédures @code{local-file}, @code{plain-file}, @code{computed-file}, -@code{program-file} et @code{scheme-file} ci-dessous renvoient des -@dfn{objets simili-fichiers}. C'est-à-dire, lorsqu'ils sont unquotés dans -une G-expression, ces objets donnent un fichier dans le dépôt. Considérez -cette G-expression : - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/my-nscd.conf")) -@end example - -Ici, l'effet est « d'internaliser » @file{/tmp/my-nscd.conf} en le copiant -dans le dépôt. Une fois étendu, par exemple via @code{gexp->derivation}, la -G-expression se réfère à cette copie dans @file{/gnu/store} ; ainsi, -modifier ou supprimer le fichier dans @file{/tmp} n'a aucun effet sur ce que -fait la G-expression. @code{plain-file} peut être utilisé de la même -manière ; elle est seulement différente par le fait que le contenu du -fichier est passé directement par une chaîne de caractères. - -@deffn {Procédure Scheme} local-file @var{file} [@var{name}] @ - [#:recursive? #f] [#:select? (const #t)] -Renvoie un objet représentant un fichier local @var{file} à ajouter au dépôt -; cet objet peut être utilisé dans une gexp. Si @var{file} est un nom de -fichier relatif, il est récupéré à partir de la position du fichier source -dans lequel il apparaît. @var{file} sera ajouté au dépôt sous le nom -@var{name} — par défaut le nom de base de @var{file}. - -Lorsque @var{recursive?} est vraie, le contenu de @var{file} est ajouté -récursivement ; si @var{file} désigne un fichier simple et que -@var{recursive?} est vrai, son contenu est ajouté et ses bits de permissions -sont préservés. - -Lorsque @var{recursive?} est vraie, appelle @code{(@var{select?} @var{file} -@var{stat})} pour chaque répertoire où @var{file} est le nom de fichier -absolu de l'entrée et @var{stat} est le résultat de @code{lstat} ; à -l'exception des entrées pour lesquelles @var{select?} ne renvoie pas vrai. - -C'est la version déclarative de la procédure monadique @code{interned-file} -(@pxref{La monade du dépôt, @code{interned-file}}). -@end deffn - -@deffn {Procédure Scheme} plain-file @var{name} @var{content} -Renvoie un objet représentant un fichier texte nommé @var{name} avec pour -contenu @var{content} (une chaîne de caractères ou un vecteur d'octets) à -ajouter un dépôt. - -C'est la version déclarative de @code{text-file}. -@end deffn - -@deffn {Procédure Scheme} computed-file @var{name} @var{gexp} @ - [#:options '(#:local-build? #t)] -Renvoie un objet représentant un élément du dépôt @var{name}, un fichier ou -un répertoire calculé par @var{gexp}. @var{options} est une liste -d'arguments supplémentaires à passer à @code{gexp->derivation}. - -C'est la version déclarative de @code{gexp->derivation}. -@end deffn - -@deffn {Procédure monadique} gexp->script @var{name} @var{exp} @ - [#:guile (default-guile)] [#:module-path %load-path] -Renvoie un script exécutable @var{name} qui lance @var{exp} avec -@var{guile}, avec les modules importés de @var{exp} dans son chemin de -recherche. Cherche les modules de @var{exp} dans @var{module-path}. - -L'exemple ci-dessous construit un script qui invoque simplement la commande -@command{ls} : - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "list-files" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -Lorsqu'elle est « lancée » à travers le dépôt (@pxref{La monade du dépôt, -@code{run-with-store}}), on obtient une dérivation qui produit une fichier -exécutable @file{/gnu/store/@dots{}-list-files} qui ressemble à : - -@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 {Procédure Scheme} program-file @var{name} @var{exp} @ - [#:guile #f] [#:module-path %load-path] -Renvoie un objet représentant un élément du dépôt @var{name} qui lance -@var{gexp}. @var{guile} est le paquet Guile à utiliser pour exécuter le -script. Les modules importés par @var{gexp} sont recherchés dans -@var{module-path}. - -C'est la version déclarative de @code{gexp->script}. -@end deffn - -@deffn {Procédure monadique} gexp->file @var{name} @var{exp} @ - [#:set-load-path? #t] [#:module-path %load-path] @ -[#:splice? #f] @ -[#:guile (default-guile)] -Renvoie une dérivation qui construit un fichier @var{name} contenant -@var{exp}. Lorsque @var{splice?} est vrai, @var{exp} est considéré comme -une liste d'expressions qui seront splicée dans le fichier qui en résulte. - -Lorsque @var{set-load-path?} est vrai, émet du code dans le fichier de -résultat pour initialiser @code{%load-path} et @code{%load-compiled-path} -pour honorer les modules importés de @var{exp}. Les modules de @var{exp} -sont trouvés dans @var{module-path}. - -Le fichier qui en résulte retient les références à toutes les dépendances de -@var{exp} ou un sous-ensemble. -@end deffn - -@deffn {Procédure Scheme} scheme-file @var{name} @var{exp} [#:splice? #f] -Renvoie un objet représentant le fichier Scheme @var{name} qui contient -@var{exp}. - -C'est la version déclarative de @code{gexp->file}. -@end deffn - -@deffn {Procédure monadique} text-file* @var{name} @var{text} @dots{} -Renvoie une valeur monadique qui construit un ficher texte contenant -@var{text}. @var{text} peut lister, en plus de chaînes de caractères, des -objet de n'importe quel type qui peut être utilisé dans une gexp : des -paquets, des dérivations, des fichiers objet locaux, etc. Le fichier du -dépôt qui en résulte en retient toutes les références. - -Cette variante devrait être préférée à @code{text-file} lorsque vous -souhaitez créer des fichiers qui référencent le dépôt. Cela est le cas -typiquement lorsque vous construisez un fichier de configuration qui -contient des noms de fichiers du dépôt, comme ceci : - -@example -(define (profile.sh) - ;; Renvoie le nom d'un script shell dans le dépôt qui initialise - ;; la variable d'environnement « PATH ». - (text-file* "profile.sh" - "export PATH=" coreutils "/bin:" - grep "/bin:" sed "/bin\n")) -@end example - -Dans cet exemple, le fichier @file{/gnu/store/@dots{}-profile.sh} qui en -résulte référence @var{coreutils}, @var{grep} et @var{sed}, ce qui les -empêche d'être glanés tant que le script est accessible. -@end deffn - -@deffn {Procédure Scheme} mixed-text-file @var{name} @var{text} @dots{} -Renvoie un objet représentant le fichier du dépôt @var{name} contenant -@var{text}. @var{text} est une séquence de chaînes de caractères et de -fichiers simili-objets, comme dans : - -@example -(mixed-text-file "profile" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -C'est la version déclarative de @code{text-file*}. -@end deffn - -@deffn {Procédure Scheme} file-union @var{name} @var{files} -Renvoie un @code{} qui construit un répertoire qui contient -tous les fichiers de @var{files}. Chaque élément de @var{files} doit être -une paire où le premier élément est le nom de fichier à utiliser dans le -nouveau répertoire et le second élément est une gexp dénotant le fichier -cible. Voici un exemple : - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -Cela crée un répertoire @code{etc} contenant ces deux fichiers. -@end deffn - -@deffn {Procédure Scheme} directory-union @var{name} @var{things} -Renvoie un répertoire qui est l'union de @var{things}, où @var{things} est -une liste d'objets simili-fichiers qui dénotent des répertoires. Par exemple -: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -crée un répertoire qui est l'union des paquets @code{guile} et @code{emacs}. -@end deffn - -@deffn {Procédure Scheme} file-append @var{obj} @var{suffix} @dots{} -Renvoie un objet simili-fichier qui correspond à la concaténation de -@var{obj} et @var{suffix} où @var{obj} est un objet abaissable et chaque -@var{suffix} est une chaîne de caractères. - -Par exemple, considérez cette gexp : - -@example -(gexp->script "run-uname" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -On peut obtenir le même effet avec : - -@example -(gexp->script "run-uname" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -Il y a une différence cependant : dans le cas @code{file-append}, le script -qui en résulte contient le nom de fichier absolu comme une chaîne de -caractère alors que dans le deuxième cas, le script contient une expression -@code{(string-append @dots{})} pour construire le nom de fichier @emph{à -l'exécution}. -@end deffn - - -Bien sûr, en plus de gexps inclues dans le code « hôte », certains modules -contiennent des outils de construction. Pour savoir facilement qu'ils sont -à utiliser dans la strate de construction, ces modules sont gardés dans -l'espace de nom @code{(guix build @dots{})}. - -@cindex abaissement, des objets haut-niveau dans les gepxs -En interne, les objets de haut-niveau sont @dfn{abaissés}, avec leur -compilateur, soit en des dérivations, soit en des objets du dépôt. Par -exemple, abaisser un paquet crée une dérivation, et abaisser un -@code{plain-file} crée un élément du dépôt. Cela est effectué par la -procédure monadique @code{lower-object}. - -@deffn {Procédure monadique} lower-object @var{obj} [@var{system}] @ - [#:target #f] -Renvoie la dérivation ou l'élément du dépôt comme une valeur de -@var{%store-monad} qui correspond à @var{obj} pour @var{system}, en -compilant de manière croisée pour @var{target} si @var{target} est vrai. -@var{obj} doit être un objet qui a un compilateur de gexp associé, comme un -@code{}. -@end deffn - -@node Invoquer guix repl -@section Invoquer @command{guix repl} - -@cindex REPL, read-eval-print loop -La commande @command{guix repl} démarre un @dfn{boucle -lecture-évaluation-affichage} Guile pour la programmation interactive -(@pxref{Using Guile Interactively,,, guile, GNU Guile Reference Manual}). -Comparé au lancement de la commande @command{guile}, @command{guix repl} -garanti que tous les modules Guix et toutes ses dépendances sont disponibles -dans le chemin de recherche. Vous pouvez l'utiliser de cette manière : - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = # -@end example - -@cindex inférieurs -En plus, @command{guix repl} implémente un protocole REPL simple lisible par -une machine à utiliser avec @code{(guix inferior)}, un dispositif pour -interagir avec des @dfn{inférieurs}, des processus séparés qui font tourner -une version potentiellement différente de Guix. - -Les options disponibles sont les suivante : - -@table @code -@item --type=@var{type} -@itemx -t @var{type} -Démarrer un REPL du @var{type} donné, qui peut être l'un de ces types : - -@table @code -@item guile -C'est la valeur par défaut. Elle démarre un REPL Guile standard -fonctionnel. -@item machine -Démarre un REPL qui utilise le protocole lisible par machine. C'est le -protocole que parle le module @code{(guix inferior)}. -@end table - -@item --listen=@var{extrémité} -Par défaut, @command{guix repl} lit depuis l'entrée standard et écrit sur la -sortie standard. Lorsque cette option est passée, il écoutera plutôt les -connexions sur @var{endpoint}. Voici un exemple d'options valides : - -@table @code -@item --listen=tcp:37146 -Accepte les connexions sur localhost, sur le port 31. - -@item --listen=unix:/tmp/socket -Accepte les connexions sur le socket Unix-domain @file{/tmp/socket}. -@end table -@end table - -@c ********************************************************************* -@node Utilitaires -@chapter Utilitaires - -Cette section décrit les utilitaires en ligne de commande de Guix. certains -sont surtout faits pour les développeurs qui écrivent de nouvelles -définitions de paquets tandis que d'autres sont plus utiles pour une -utilisation générale. Ils complètent l'interface de programmation Scheme de -Guix d'une manière pratique. - -@menu -* Invoquer guix build:: Construire des paquets depuis la ligne de - commande. -* Invoquer guix edit:: Modifier les définitions de paquets. -* Invoquer guix download:: Télécharger un fichier et afficher son hash. -* Invoquer guix hash:: Calculer le hash cryptographique d'un fichier. -* Invoquer guix import:: Importer des définitions de paquets. -* Invoquer guix refresh:: Mettre à jour les définitions de paquets. -* Invoquer guix lint:: Trouver des erreurs dans les définitions de - paquets. -* Invoquer guix size:: Profiler l'utilisation du disque. -* Invoquer guix graph:: Visualiser le graphe des paquets. -* Invoquer guix publish:: Partager des substituts. -* Invoquer guix challenge:: Défier les serveurs de substituts. -* Invoquer guix copy:: Copier vers et depuis un dépôt distant. -* Invoquer guix container:: Isolation de processus. -* Invoquer guix weather:: Mesurer la disponibilité des substituts. -* Invoquer guix processes:: Lister les processus clients. -@end menu - -@node Invoquer guix build -@section Invoquer @command{guix build} - -@cindex construction de paquets -@cindex @command{guix build} -La commande @command{guix build} construit des paquets ou des dérivations et -leurs dépendances et affiche les chemins du dépôt qui en résulte. Remarquez -qu'elle ne modifie pas le profil de l'utilisateur — c'est le travail de la -commande @command{guix package} (@pxref{Invoquer guix package}). Ainsi, -elle est surtout utile pour les développeurs de la distribution. - -La syntaxe générale est : - -@example -guix build @var{options} @var{package-or-derivation}@dots{} -@end example - -Par exemple, la commande suivante construit la dernière version d'Emacs et -de Guile, affiche leur journaux de construction et enfin affiche les -répertoires des résultats : - -@example -guix build emacs guile -@end example - -De même, la commande suivante construit tous les paquets disponibles : - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -@var{package-or-derivation} peut être soit le nom d'un paquet trouvé dans la -distribution logicielle comme @code{coreutils}, soit @code{coreutils@@8.20}, -soit une dérivation comme @file{/gnu/store/@dots{}-coreutils-8.19.drv}. -Dans le premier cas, la commande cherchera un paquet avec le nom -correspondant (et éventuellement la version) dans les modules de la -distribution GNU (@pxref{Modules de paquets}). - -Autrement, l'option @code{--expression} peut être utilisée pour spécifier -une expression Scheme qui s'évalue en un paquet ; c'est utile pour -différencier des paquets avec le même nom ou des variantes de paquets. - -Il peut y avoir aucune, une ou plusieurs @var{options}. Les options -disponibles sont décrites dans les sous-sections ci-dessous. - -@menu -* Options de construction communes:: Options de construction pour la - plupart des commandes. -* Options de transformation de paquets:: Créer des variantes de paquets. -* Options de construction supplémentaires:: Options spécifiques à « - guix build ». -* Débogage des échecs de construction:: La vie d'un empaqueteur. -@end menu - -@node Options de construction communes -@subsection Options de construction communes - -Un certain nombre d'options qui contrôlent le processus de construction sont -communes avec @command{guix build} et les autres commandes qui peuvent -générer des constructions, comme @command{guix package} ou @command{guix -archive}. Voici ces options : - -@table @code - -@item --load-path=@var{répertoire} -@itemx -L @var{répertoire} -Ajoute @var{répertoire} au début du chemin de recherche de module de paquets -(@pxref{Modules de paquets}). - -Cela permet à des utilisateurs de définir leur propres paquets et les rendre -disponibles aux outils en ligne de commande. - -@item --keep-failed -@itemx -K -Garde l'arborescence de construction des constructions en échec. Ainsi, si -une construction échoue, son arborescence de construction est préservée dans -@file{/tmp}, dans un répertoire dont le nom est affiché à la fin du journal -de construction. Cela est utile pour déboguer des échecs de construction. -@xref{Débogage des échecs de construction}, pour des astuces sur la manière de déboguer -des problèmes de construction. - -Cette option n'a pas d'effet lors de la connexion à un démon distant avec -l'URI @code{guix://} (@pxref{Le dépôt, la variable -@code{GUIX_DAEMON_SOCKET}}). - -@item --keep-going -@itemx -k -Continue lorsque certaines dérivations échouent ; ne s'arrête que lorsque -toutes les constructions ont soit réussies, soit échouées. - -Le comportement par défaut est de s'arrêter dès qu'une des dérivations -spécifiées échoue. - -@item --dry-run -@itemx -n -Ne pas construire les dérivations. - -@anchor{option de repli} -@item --fallback -Lorsque la substitution d'un binaire pré-compilé échoue, construit les -paquets localement à la place (@pxref{Échec de substitution}). - -@item --substitute-urls=@var{urls} -@anchor{client-substitute-urls} -Considère @var{urls} comme une liste d'URL de sources de substituts séparés -par des espaces, et remplace la liste par défaut d'URL de -@command{guix-daemon} (@pxref{daemon-substitute-urls,, @command{guix-daemon} -URLs}). - -Cela signifie que les substituts peuvent être téléchargés depuis @var{urls}, -tant qu'ils sont signés par une clef autorisée par l'administrateur système -(@pxref{Substituts}). - -Lorsque @var{urls} est la chaîne vide, cela a pour effet de désactiver la -substitution. - -@item --no-substitutes -Ne pas utiliser de substitut pour les résultats de la construction. -C'est-à-dire, toujours construire localement plutôt que de permettre le -téléchargement de binaires pré-construits (@pxref{Substituts}). - -@item --no-grafts -Ne par « greffer » les paquets. En pratique, cela signifie que les mises à -jour des paquets disponibles comme des greffes ne sont pas appliquées. -@xref{Mises à jour de sécurité}, pour plus d'information sur les greffes. - -@item --rounds=@var{n} -Construit chaque dérivation @var{n} fois d'affilé, et renvoie une erreur si -les constructions consécutives ne sont pas identiques bit-à-bit. - -Cela est une manière utile pour détecter des processus de construction non -déterministes. Les processus de construction non déterministes sont -problématiques car ils rendent pratiquement impossible la -@emph{vérification} par les utilisateurs de l'authenticité de binaires -tiers. @xref{Invoquer guix challenge}, pour plus d'informations. - -Remarquez que, les résultats qui diffèrent ne sont pas gardés, donc vous -devrez inspecter manuellement chaque erreur — p.@: ex.@: en gardant l'un des -résultats avec @code{guix archive --export} (@pxref{Invoquer guix archive}), -puis en reconstruisant, et enfin en comparant les deux résultats. - -@item --no-build-hook -N'essaye pas de décharger les constructions via le « crochet de construction -» du démon (@pxref{Réglages du délestage du démon}). C'est-à-dire que tout sera -construit localement plutôt que de décharger les constructions à une machine -distante. - -@item --max-silent-time=@var{secondes} -Lorsque le processus de construction ou de substitution restent silencieux -pendant plus de @var{secondes}, le terminer et rapporter une erreur de -construction. - -Par défaut, les paramètres du démon sont pris en compte (@pxref{Invoquer guix-daemon, @code{--max-silent-time}}). - -@item --timeout=@var{secondes} -De même, lorsque le processus de construction ou de substitution dure plus -de @var{secondes}, le terminer et rapporter une erreur de construction. - -Par défaut, les paramètres du démon sont pris en compte (@pxref{Invoquer guix-daemon, @code{--timeout}}). - -@c Note: This option is actually not part of %standard-build-options but -@c most programs honor it. -@cindex verbosité, des outils en ligne de commande -@cindex journaux de construction, verbosité -@item -v [@var{niveau}] -@itemx --verbosity=@var{niveau} -Utiliser le @var{niveau} de verbosité, en tant qu'entier. 0 signifie -qu'aucune sortie n'est produite, 1 signifie une sortie silencieuse et 2 -montre tous les journaux de construction sur la sortie d'erreur standard. - -@item --cores=@var{n} -@itemx -c @var{n} -Permet d'utiliser jusqu'à @var{n} cœurs du CPU pour la construction. La -valeur spéciale @code{0} signifie autant de cœurs que possible. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Permet au plus @var{n} travaux de construction en parallèle. @xref{Invoquer guix-daemon, @code{--max-jobs}}, pour plus de détails sur cette option et -l'option équivalente pour @command{guix-daemon}. - -@item --debug=@var{niveau} -Produire une sortie de débogage qui provient du démon de construction. -@var{niveau} doit être un entier entre 0 et 5 ; plus grand est ce nombre, -plus verbeuse sera la sortie. Indiquer un niveau de 4 ou plus peut être -utile pour déboguer des problèmes d'installation avec le démon de -construction. - -@end table - -Sous le capot, @command{guix build} est surtout un interface à la procédure -@code{package-derivation} du module @code{(guix packages)}, et à la -procédure @code{build-derivations} du module @code{(guix derivations)}. - -En plus des options passées explicitement par la ligne de commande, -@command{guix build} et les autres commande @command{guix} qui peuvent -effectuer des construction honorent la variable d'environnement -@code{GUIX_BUILD_OPTIONS}. - -@defvr {Variable d'environnement} GUIX_BUILD_OPTIONS -Les utilisateurs peuvent définir cette variable à une liste d'options de la -ligne de commande qui seront automatiquement utilisées par @command{guix -build} et les autres commandes @command{guix} qui peuvent effectuer des -constructions, comme dans l'exemple suivant : - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -Ces options sont analysées indépendamment, et le résultat est ajouté aux -options de la ligne de commande analysées. -@end defvr - - -@node Options de transformation de paquets -@subsection Options de transformation de paquets - -@cindex variantes de paquets -Un autre ensemble d'options de la ligne de commande supportés par -@command{guix build} et aussi @command{guix package} sont les @dfn{options -de transformation de paquets}. Ce sont des options qui rendent possible la -définition de @dfn{variantes de paquets} — par exemple, des paquets -construit à partir de sources différentes. C'est une manière simple de -créer des paquets personnalisés à la volée sans avoir à taper les -définitions de variantes de paquets (@pxref{Définition des paquets}). - -@table @code - -@item --with-source=@var{source} -@itemx --with-source=@var{paquet}=@var{source} -@itemx --with-source=@var{paquet}@@@var{version}=@var{source} -Utiles @var{source} comme la source de @var{paquet}, et @var{version} comme -son numéro de version. @var{source} doit être un nom de fichier ou une URL, -comme pour @command{guix download} (@pxref{Invoquer guix download}). - -Lorsque @var{paquet} est omis, la commande utilisera le nom de paquet -spécifié par la base de @var{source} — p.@: ex.@: si @var{source} est -@code{/src/guix-2.0.10.tar.gz}, le paquet correspondant est @code{guile}. - -De même, lorsque @var{version} est omis, la chaîne de version est inférée à -partir de @var{source} ; dans l'exemple précédent, il s'agit de -@code{2.0.10}. - -Cette option permet aux utilisateurs d'essayer des version des paquets -différentes de celles fournies par la distribution. L'exemple ci-dessous -télécharge @file{ed-1.7.tar.g} depuis un miroir GNU et l'utilise comme -source pour le paquet @code{ed} : - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -En tant que développeur, @code{--with-source} permet de tester facilement -des version bêta : - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} ou pour construire un dépôt de gestion de version dans un -environnement vierge : - -@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{paquet}=@var{remplaçant} -Remplace la dépendance sur @var{paquet} par une dépendance à -@var{remplaçant}. @var{paquet} doit être un nom de paquet et -@var{remplaçant} doit être une spécification de paquet comme @code{guile} ou -@code{guile@@1.8}. - -Par exemple, la commande suivante construit Guix, mais remplace sa -dépendance à la version stable actuelle de Guile par une dépendance à une -ancienne version de Guile, @code{guile@@2.0} : - -@example -guix build --with-input=guile=guile@@2.0 guix -@end example - -C'est un remplacement récursif profond. Donc dans cet exemple, à la fois -@code{guix} et ses dépendances @code{guile-json} (qui dépend aussi de -@code{guile}) sont reconstruits avec @code{guile@@2.0}. - -Cette option est implémentée avec la procédure Scheme -@code{package-input-rewriting} (@pxref{Définition des paquets, -@code{package-input-rewriting}}). - -@item --with-graft=@var{paquet}=@var{remplaçant} -Cette option est similaire à @code{--with-input} mais avec une différence -importante : plutôt que de reconstruire la chaîne de dépendance complète, -@var{remplaçant} est construit puis @dfn{greffé} sur les binaires qui -référençaient initialement @var{paquet}. @xref{Mises à jour de sécurité}, pour plus -d'information sur les greffes. - -Par exemple, la commande ci-dessous greffe la version 3.5.4 de GnuTLS sur -Wget et toutes ses dépendances, en remplaçant les références à la version -actuelle de GnuTLS à laquelle ils se réfèrent actuellement : - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -Cela a l'avantage d'être bien plus rapide que de tout reconstruire. Mais il -y a un piège : cela ne fonctionne que si @var{paquet} et @var{remplaçant} -sont strictement compatibles — par exemple, s'ils fournissent une -bibliothèque, l'interface binaire applicative (ABI) de ces bibliothèques -doivent être compatibles. Si @var{remplaçant} est incompatible avec -@var{paquet}, alors le paquet qui en résulte peut devenir inutilisable. À -utilisez avec précaution ! - -@item --with-git-url=@var{paquet}=@var{url} -@cindex Git, utiliser le dernier commit -@cindex dernier commit, construction -Construire @var{paquet} depuis le dernier commit de la branche @code{master} -du dépôt sur @var{url}. Les sous-modules Git du dépôt sont récupérés, -récursivement. - -Par exemple, la commande suivante construit la bibliothèque Python NumPy -avec le dernier commit de la branche master de Python lui-même : - -@example -guix build python-numpy \ - --with-git-url=python=https://github.com/python/cpython -@end example - -Cette option peut aussi être combinée avec @code{--with-branch} ou -@code{--with-commit} (voir plus bas). - -@cindex intégration continue -Évidemment, comme cela utilise le dernier commit d'une branche donnée, le -résultat d'une telle commande varie avec le temps. Néanmoins c'est une -manière pratique pour reconstruire des piles logicielles entières avec le -dernier commit d'un ou plusieurs paquets. C'est particulièrement pratique -dans le contexte d'une intégration continue. - -Les clones sont gardés dans un cache dans @file{~/.cache/guix/checkouts} -pour accélérer les accès consécutifs au même dépôt. Vous pourriez vouloir -le nettoyer de temps en temps pour récupérer de l'espace disque. - -@item --with-branch=@var{paquet}=@var{branche} -Construire @var{paquet} à partir du dernier commit de la @var{branche}. Si -le champ @code{source} de @var{paquet} est une origine avec la méthode -@code{git-fetch} (@pxref{Référence des origines}) ou un objet @code{git-checkout}, -l'URL du dépôt est récupérée à partir de cette @code{source}. Sinon, vous -devez utiliser @code{--with-git-url} pour spécifier l'URL du dépôt Git. - -Par exemple, la commande suivante construit @code{guile-sqlite3} à partir du -dernier commit de sa branche @code{master}, puis construit @code{guix} (qui -en dépend) et @code{cuirass} (qui dépend de @code{guix}) avec cette -construction spécifique de @code{guile-sqlite3} : - -@example -guix build --with-branch=guile-sqlite3=master cuirass -@end example - -@item --with-commit=@var{paquet}=@var{commit} -Cela est similaire à @code{--with-branch}, sauf qu'elle construite à partir -de @var{commit} au lieu du sommet d'une branche. @var{commit} doit être un -identifiant SHA1 de commit Git valide. -@end table - -@node Options de construction supplémentaires -@subsection Options de construction supplémentaires - -Les options de la ligne de commande ci-dessous sont spécifiques à -@command{guix build}. - -@table @code - -@item --quiet -@itemx -q -Construire en silence, sans afficher les journaux de construction ; c'est -équivalent à @code{--verbosity=0}. À la fin, le journal de construction est -gardé dans @file{/var} (ou similaire) et on peut toujours l'y trouver avec -l'option @option{--log-file}. - -@item --file=@var{fichier} -@itemx -f @var{fichier} -Construit le paquet, la dérivation ou l'objet simili-fichier en lequel le -code dans @var{file} s'évalue (@pxref{G-Expressions, file-like objects}). - -Par exemple, @var{file} peut contenir une définition de paquet comme ceci -(@pxref{Définition des paquets}) : - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{expr} -@itemx -e @var{expr} -Construit le paquet ou la dérivation en lequel @var{expr} s'évalue. - -Par exemple, @var{expr} peut être @code{(@@ (gnu packages guile) -guile-1.8)}, qui désigne sans ambiguïté cette variante spécifique de la -version 1.8 de Guile. - -Autrement, @var{exp} peut être une G-expression, auquel cas elle est -utilisée comme un programme de construction passé à @code{gexp->derivation} -(@pxref{G-Expressions}). - -Enfin, @var{expr} peut se référer à une procédure monadique à au moins un -argument (@pxref{La monade du dépôt}). La procédure doit renvoyer une -dérivation comme une valeur monadique, qui est ensuite lancée à travers -@code{run-with-store}. - -@item --source -@itemx -S -Construit les dérivation source des paquets, plutôt que des paquets -eux-mêmes. - -Par exemple, @code{guix build -S gcc} renvoie quelque chose comme -@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, qui est l'archive des sources -de GCC. - -L'archive des sources renvoyée est le résultat de l'application des -correctifs et des extraits de code éventuels spécifiés dans le champ -@code{origin} du paquet (@pxref{Définition des paquets}). - -@item --sources -Récupère et renvoie la source de @var{package-or-derivation} et toute ses -dépendances, récursivement. C'est pratique pour obtenir une copie locale de -tous les codes sources requis pour construire @var{packages}, ce qui vous -permet de les construire plus tard même sans accès réseau. C'est une -extension de l'option @code{--source} et peut accepter l'un des arguments -facultatifs suivants : - -@table @code -@item package -Cette valeur fait que l'option @code{--sources} se comporte comme l'option -@code{--source}. - -@item all -Construit les dérivations des sources de tous les paquets, dont les sources -qui pourraient être listées dans @code{inputs}. C'est la valeur par défaut. - -@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 -Construire les dérivations des sources de tous les paquets, ainsi que toutes -celles des entrées transitives des paquets. On peut par exemple utiliser -cette option pour précharger les sources des paquets pour les construire -plus tard hors ligne. - -@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{système} -@itemx -s @var{système} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the -system type of the build host. The @command{guix build} command allows you -to repeat this option several times, in which case it builds for all the -specified systems; other commands ignore extraneous @option{-s} options. - -@quotation Remarque -Le drapeau @code{--system} est utilisé pour une compilation @emph{native} et -ne doit pas être confondu avec une compilation croisée. Voir -@code{--target} ci-dessous pour des informations sur la compilation croisée. -@end quotation - -Par exemple, passer @code{--system=i686-linux} sur un système -@code{x86_64-linux} ou @code{--system=armhf-linux} sur un système -@code{aarch64-linux} vous permet de construire des paquets dans un -environnement entièrement 32-bits. C'est une exemple d'utilisation de cette -option sur les systèmes Linux, qui peuvent émuler plusieurs personnalités. - -@quotation Remarque -La possibilité de construire pour un système @code{armhf-linux} est activé -sans condition sur les machines @code{aarch64-linux}, bien que certaines -puces aarch64 n'en soient pas capables, comme les ThunderX. -@end quotation - -De même, lorsque l'émulation transparente avec QEMU et @code{binfnmt_misc} -est activée (@pxref{Services de virtualisation, -@code{qemu-binfmt-service-type}}), vous pouvez construire pour n'importe -quel système pour lequel un gestionnaire QEMU @code{binfmt_misc} est -installé. - -Les constructions pour un autre système que celui de la machine que vous -utilisez peuvent aussi être déchargées à une machine distante de la bonne -architecture. @xref{Réglages du délestage du démon}, pour plus d'information sur le -déchargement. - -@item --target=@var{triplet} -@cindex compilation croisée -Effectuer une compilation croisée pour @var{triplet} qui doit être un -triplet GNU valide, comme @code{"mips64el-linux-gnu"} (@pxref{Specifying -target triplets, GNU configuration triplets,, autoconf, Autoconf}). - -@anchor{vérification de la construction} -@item --check -@cindex déterminisme, vérification -@cindex reproductibilité, vérification -Reconstruit les @var{package-or-derivation}, qui sont déjà disponibles dans -le dépôt et lève une erreur si les résultats des constructions ne sont pas -identiques bit-à-bit. - -Ce mécanisme vous permet de vérifier si les substituts précédemment -installés sont authentiques (@pxref{Substituts}) ou si le résultat de la -construction d'un paquet est déterministe. @xref{Invoquer guix challenge} -pour plus d'informations et pour les outils. - -Lorsqu'utilisé avec @option{--keep-failed}, la sortie différente est gardée -dans le dépôt sous @file{/gnu/store/@dots{}-check}. Cela rend plus facile -l'étude des différences entre les deux résultats. - -@item --repair -@cindex réparer les éléments du dépôt -@cindex corruption, récupérer de -Essaye de réparer les éléments du dépôt spécifiés, s'ils sont corrompus, en -les téléchargeant ou en les construisant à nouveau. - -Cette opération n'est pas atomique et donc restreinte à l'utilisateur -@code{root} - -@item --derivations -@itemx -d -Renvoie les chemins de dérivation, et non les chemins de sortie, des paquets -donnés. - -@item --root=@var{fichier} -@itemx -r @var{fichier} -@cindex racines du GC, ajout -@cindex ajout de racines au ramasse-miettes -Fait de @var{fichier} un lien symbolique vers le résultat, et l'enregistre -en tant que racine du ramasse-miettes. - -En conséquence, les résultats de cette invocation de @command{guix build} -sont protégés du ramasse-miettes jusqu'à ce que @var{fichier} soit -supprimé. Lorsque cette option est omise, les constructions sont -susceptibles d'être glanées. - -@item --log-file -@cindex journaux de construction, accès -Renvoie les noms des journaux de construction ou les URL des -@var{package-or-derivation} donnés ou lève une erreur si les journaux de -construction sont absents. - -Cela fonctionne indépendamment de la manière dont les paquets ou les -dérivations sont spécifiées. Par exemple, les invocations suivantes sont -équivalentes : - -@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 - -Si un journal n'est pas disponible localement, à moins que -@code{--no-substitutes} ne soit passé, la commande cherche un journal -correspondant sur l'un des serveurs de substituts (tels que spécifiés avec -@code{--substitute-urls}.) - -Donc par exemple, imaginons que vous souhaitiez voir le journal de -construction de GDB sur MIPS, mais que vous n'avez qu'une machine -@code{x86_64} : - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -Vous pouvez accéder librement à un vaste bibliothèque de journaux de -construction ! -@end table - -@node Débogage des échecs de construction -@subsection Débogage des échecs de construction - -@cindex échecs de construction, débogage -Lors de la définition d'un nouveau paquet (@pxref{Définition des paquets}), vous -passerez probablement du temps à déboguer et modifier la construction -jusqu'à ce que ça marche. Pour cela, vous devez effectuer les commandes de -construction vous-même dans un environnement le plus proche possible de -celui qu'utilise le démon de construction. - -Pour cela, la première chose à faire est d'utiliser l'option -@option{--keep-failed} ou @option{-K} de @command{guix build}, qui gardera -l'arborescence de construction dans @file{/tmp} ou le répertoire spécifié -par @code{TMPDIR} (@pxref{Invoquer guix build, @code{--keep-failed}}). - -À partir de là, vous pouvez vous déplacer dans l'arborescence de -construction et sourcer le fichier @file{environment-variables}, qui -contient toutes les variables d'environnement qui étaient définies lorsque -la construction a échoué. Disons que vous déboguez un échec de construction -dans le paquet @code{foo} ; une session typique ressemblerait à cela : - -@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 - -Maintenant, vous pouvez invoquer les commandes comme si vous étiez le démon -(presque) et corriger le processus de construction. - -Parfois il arrive que, par exemple, les tests d'un paquet réussissent -lorsque vous les lancez manuellement mais échouent quand ils sont lancés par -le démon. Cela peut arriver parce que le démon tourne dans un conteneur où, -contrairement à notre environnement au-dessus, l'accès réseau est -indisponible, @file{/bin/sh} n'existe pas, etc (@pxref{Réglages de l'environnement de construction}). - -Dans ce cas, vous pourriez avoir besoin de lancer le processus de -construction dans un conteneur similaire à celui que le démon crée : - -@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 - -Ici, @command{guix environment -C} crée un conteneur et démarre un nouveau -shell dedans (@pxref{Invoquer guix environment}). La partie -@command{--ad-hoc strace gdb} ajoute les commandes @command{strace} et -@command{gdb} dans le conteneur, ce qui pourrait s'avérer utile pour le -débogage. L'option @option{--no-grafts} s'assure qu'on obtient le même -environnement, avec des paquets non greffés (@pxref{Mises à jour de sécurité}, pour -plus d'informations sur les greffes). - -Pour obtenir un conteneur plus proche de ce qui serait utilisé par le démon -de construction, on peut enlever @file{/bin/sh} : - -@example -[env]# rm /bin/sh -@end example - -Ne vous inquiétez pas, c'est sans danger : tout cela se passe dans un -conteneur jetable créé par @command{guix environment}. - -La commande @command{strace} n'est probablement pas dans le chemin de -recherche, mais on peut lancer : - -@example -[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check -@end example - -De cette manière, non seulement vous aurez reproduit les variables -d'environnement utilisées par le démon, mais vous lancerez aussi le -processus de construction dans un conteneur similaire à celui utilisé par le -démon. - - -@node Invoquer guix edit -@section Invoquer @command{guix edit} - -@cindex @command{guix edit} -@cindex définition de paquets, modification -Tant de paquets, tant de fichiers source ! La commande @command{guix edit} -facilite la vie des utilisateurs et des empaqueteurs en plaçant leur éditeur -sur le fichier source qui contient la définition des paquets spécifiés. Par -exemple : - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -lance le programme spécifié dans la variable d'environnement @code{VISUAL} -ou @code{EDITOR} pour visionner la recette de GCC@tie{}4.9.3 et celle de -Vim. - -Si vous utilisez une copie du dépôt Git de Guix (@pxref{Construire depuis Git}), -ou que vous avez créé vos propres paquets dans @code{GUIX_PACKAGE_PATH} -(@pxref{Modules de paquets}), vous pourrez modifier les recettes des paquets. -Sinon, vous pourrez examiner les recettes en lecture-seule des paquets -actuellement dans le dépôt. - - -@node Invoquer guix download -@section Invoquer @command{guix download} - -@cindex @command{guix download} -@cindex télécharger les sources des paquets -En écrivant des définitions de paquets, les développeurs ont généralement -besoin de télécharger une archive des sources, calculer son hash SHA256 et -écrire ce hash dans la définition du paquet (@pxref{Définition des paquets}). -L'outil @command{guix download} aide à cette tâche : il télécharge un -fichier à l'URL donné, l'ajoute au dépôt et affiche à la fois son nom dans -le dépôt et son hash SHA56. - -Le fait que le fichier téléchargé soit ajouté au dépôt préserve la bande -passante : lorsque les développeurs finissent par construire le paquet -nouvellement défini avec @command{guix build}, l'archive des sources n'aura -pas besoin d'être téléchargée de nouveau puisqu'elle se trouvera déjà dans -le dépôt. C'est aussi une manière pratique de garder des fichiers -temporairement, qui pourront ensuite être supprimés (@pxref{Invoquer guix gc}). - -La commande @command{guix download} supporte les mêmes URI que celles -utilisées dans les définitions de paquets. En particulier, elle supporte -les URI @code {mirror://}. Les URI @code{http} (HTTP sur TLS) sont -supportées @emph{si} les liaisons Guile de GnuTLS sont disponibles dans -l'environnement de l'utilisateur ; si elle ne sont pas disponibles, une -erreur est renvoyée. @xref{Guile Preparations, how to install the GnuTLS -bindings for Guile,, gnutls-guile, GnuTLS-Guile}, pour plus d'informations. - -@command{guix download} vérifie les certificats du serveur HTTPS en -chargeant les autorités de certification X.509 depuis le répertoire vers -lequel pointe la variable d'environnement @code{SSL_CERT_DIR} (@pxref{Certificats X.509}), à moins que @option{--no-check-certificate} ne soit utilisé. - -Les options suivantes sont disponibles : - -@table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Écrit le hash dans le format spécifié par @var{fmt}. Pour plus -d'informations sur les valeurs valides pour @var{fmt}, @pxref{Invoquer guix hash}. - -@item --no-check-certificate -Ne pas valider les certificats HTTPS des serveurs. - -Lorsque vous utilisez cette option, vous n'avez @emph{absolument aucune -garanti} que vous communiquez avec le serveur authentique responsable de -l'URL donnée, ce qui vous rend vulnérable à des attaques de « l'homme du -milieu ». - -@item --output=@var{fichier} -@itemx -o @var{fichier} -Enregistre le fichier téléchargé dans @var{fichier} plutôt que de l'ajouter -au dépôt. -@end table - -@node Invoquer guix hash -@section Invoquer @command{guix hash} - -@cindex @command{guix hash} -La commande @command{guix hash} calcul le hash SHA256 d'un fichier. C'est -surtout un outil pour simplifier la vie des contributeurs de la distribution -: il calcul le hash cryptographique d'un fichier, qui peut être utilisé dans -la définition d'un paquet (@pxref{Définition des paquets}). - -La syntaxe générale est : - -@example -guix hash @var{option} @var{fichier} -@end example - -Lorsque @var{fichier} est @code{-} (un tiret), @command{guix hash} calcul le -hash des données lues depuis l'entrée standard. @command{guix hash} a les -options suivantes : - -@table @code - -@item --format=@var{fmt} -@itemx -f @var{fmt} -Écrit le hash dans le format spécifié par @var{fmt}. - -Les formats supportés sont : @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} et @code{hexadecimal} peuvent aussi être utilisés). - -Si l'option @option {--format} n'est pas spécifiée, @command{guix hash} -affichera le hash en @code{nix-base32}. Cette représentation est utilisée -dans les définitions des paquets. - -@item --recursive -@itemx -r -Calcule le hash sur @var{fichier} récursivement. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -Dans ce cas, le hash est calculé sur une archive contenant @var{fichier}, -dont ses enfants si c'est un répertoire. Certaines métadonnées de -@var{fichier} fait partie de l'archive ; par exemple lorsque @var{fichier} -est un fichier normal, le hash est différent que le @var{fichier} soit -exécutable ou non. Les métadonnées comme un horodatage n'ont aucun impact -sur le hash (@pxref{Invoquer guix archive}). - -@item --exclude-vcs -@itemx -x -Lorsqu'elle est combinée à @option{--recursive}, exclut les répertoires de -système de contrôle de version (@file{.bzr}, @file{.git}, @file{.hg}, etc). - -@vindex git-fetch -Par exemple, voici comment calculer le hash d'un dépôt Git, ce qui est utile -avec la méthode @code{git-fetch} (@pxref{Référence des origines}) : - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Invoquer guix import -@section Invoquer @command{guix import} - -@cindex importer des paquets -@cindex paquets importés -@cindex conversion de paquets -@cindex Invoquer @command{guix import} -La commande @command{guix import} est utile pour les gens qui voudraient -ajouter un paquet à la distribution avec aussi peu de travail que possible — -une demande légitime. La commande connaît quelques dépôts logiciels d'où -elle peut « importer » des métadonnées de paquets. Le résultat est une -définition de paquet, ou un modèle de définition, dans le format reconnu par -Guix (@pxref{Définition des paquets}). - -La syntaxe générale est : - -@example -guix import @var{importer} @var{options}@dots{} -@end example - -@var{importer} spécifie la source depuis laquelle importer des métadonnées -de paquets, et @var{options} spécifie un identifiant de paquet et d'autres -options spécifiques à @var{importer}. Actuellement les « importateurs » -disponibles sont : - -@table @code -@item gnu -Importe des métadonnées d'un paquet GNU donné. Cela fournit un modèle pour -la dernière version de ce paquet GNU, avec le hash de son archive, le -synopsis et la description canonique. - -Les informations supplémentaires comme les dépendances du paquet et sa -licence doivent être renseignées manuellement. - -Par exemple, la commande suivante renvoie une définition de paquets pour -GNU@tie{}Hello : - -@example -guix import gnu hello -@end example - -Les options spécifiques sont : - -@table @code -@item --key-download=@var{politique} -Comme pour @code{guix refresh}, spécifie la politique de gestion des clefs -OpenPGP manquantes lors de la vérification de la signature d'un paquet. -@xref{Invoquer guix refresh, @code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Importe des métadonnées depuis @uref{https://pypi.python.org/, l'index des -paquets Python}. Les informations sont récupérées à partir de la -description en JSON disponible sur @code{pypi.python.org} et inclus -généralement toutes les informations utiles, dont les dépendances des -paquets. Pour une efficacité maximale, il est recommandé d'installer -l'utilitaire @command{unzip}, pour que l'importateur puisse dézipper les -wheels Python et récupérer les informations contenues à l'intérieur. - -La commande ci-dessous importe les métadonnées du paquet Python -@code{itsdangerous} : - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -r -Traverse le graphe des dépendances du paquet amont donné et génère les -expressions de paquets de tous ceux qui ne sont pas déjà dans Guix. -@end table - -@item gem -@cindex gem -Importe des métadonnées de @uref{https://rubygems.org/, RubyGems}. Les -informations sont récupérées au format JSON disponible sur -@code{rubygems.org} et inclut les informations les plus utiles, comme les -dépendances à l'exécution. Il y a des cependant quelques restrictions. Les -métadonnées ne distinguent pas synopsis et description, donc la même chaîne -est utilisée pour les deux champs. En plus, les détails des dépendances non -Ruby requises pour construire des extensions natives sont indisponibles et -laissé en exercice à l'empaqueteur. - -La commande ci-dessous importe les métadonnées pour le paquet Ruby -@code{rails} : - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -r -Traverse le graphe des dépendances du paquet amont donné et génère les -expressions de paquets de tous ceux qui ne sont pas déjà dans Guix. -@end table - -@item cpan -@cindex CPAN -Importe des métadonnées de @uref{https://www.metacpan.org/, MetaCPAN}. Les -informations sont récupérées au format JSON disponible à travers -@uref{https://fastapi.metacpan.org/, l'API de MetaCPAN} et inclus les -informations les plus utiles, comme les dépendances des modules. -L'information sur les licences doit être vérifiée avec attention. Si Perl -est disponible dans le dépôt, alors l'utilitaire @code{corelist} sera -utiliser pour exclure les modules du cœur de la distribution Perl de la -liste des dépendances. - -La commande ci-dessous importe les métadonnées du module Perl -@code{Acme::Boolean} : - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -Importe des métadonnées de @uref{https://cran.r-project.org/, CRAN}, le -dépôt central de @uref{http://r-project.org, l'environnement statistique et -graphique GUN@tie{}R}. - -Les informations sont extraites du fichier @file{DESCRIPTION} du paquet. - -La commande ci-dessous importe les métadonnées du paquet R @code{Cairo} : - -@example -guix import cran Cairo -@end example - -Lorsque l'option @code{--recursive} est utilisée, l'importateur traversera -le graphe des dépendances du paquet amont récursivement et générera des -expressions de paquets pour tous ceux qui ne sont pas déjà dans Guix. - -Lorsque l'option @code{--archive=bioconductor} est utilisée, les métadonnées -sont importées de @uref{https://www.bioconductor.org/, Bioconductor}, un -répertoire de paquets R pour l'analyse et la compréhension de données -génomiques volumineuses en bioinformatique. - -Les informations sont extraites du fichier @file{DESCRIPTION} d'un paquet -publié sur l'interface web du dépôt SVN de Bioconductor. - -La commande ci-dessous importe les métadonnées du paquet R -@code{GenomicRanges} : - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex TeX Live -@cindex CTAN -Importe les métadonnées de @uref{http://www.ctan.org/, CTAN}, l'archive TeX -réseau complète pour les paquets TeX qui font partie de la -@uref{https://www.tug.org/texlive/, distribution TeX Live}. - -Les informations sur les paquets sont obtenues à travers l'API XML fournie -par CTAN, tandis que le code source est téléchargé depuis le dépôt SVN du -projet Tex Live. Cette méthode est utilisée parce que CTAN ne garde pas -d'archives versionnées. - -La commande ci-dessous importe les métadonnées du paquet TeX @code{fontspec} -: - -@example -guix import texlive fontspec -@end example - -Lorsque l'option @code{--archive=DIRECTORY} est utilisée, le code source -n'est pas téléchargé depuis le sous-répertoire @file{latex} du -l'arborescence @file{texmf-dist/source} dans le dépôt SVN de TeX Live, mais -depuis le répertoire voisin spécifié sous la même racine. - -La commande ci-dessous importe les métadonnées du paquet @code{ifxetex} -depuis CTAN en récupérant les sources depuis le répertoire -@file{texmf/source/generic} : - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, import -Importe des métadonnées d'un fichier JSON local. Considérez l'exemple -suivant d'une définition de paquet au format JSON : - -@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 - -Les noms des champs sont les mêmes que pour les enregistrements de -@code{} (@xref{Définition des paquets}). Les référence à d'autres -paquets sont fournies comme des listes JSON de chaînes de spécifications de -paquets comme @code{guile} ou @code{guile@@2.0}. - -L'importateur supporte aussi une définition plus explicite des sources avec -les champs habituels pour les enregistrements @code{} : - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -La commande ci-dessous lit les métadonnées du fichier JSON @code{hello.json} -et renvoie une expression de paquet : - -@example -guix import json hello.json -@end example - -@item nix -Importe les métadonnées d'une copie locale des source de -@uref{http://nixos.org/nixpkgs/, la distribution Nixpkgs}@footnote{Cela -repose sur la commande @command{nix-instantiate} de -@uref{http://nixos.org/nix/, Nix}.}. Les définitions de paquets dans -Nixpkgs sont habituellement écrites en un mélange entre le langage Nix et -Bash. Cette commande n'importe que la structure de haut-niveau du paquet -qui est écrite dans le langage Nix. Elle inclut normalement tous les champs -de base de la définition d'un paquet. - -Lorsque vous importez un paquet GNU, le synopsis et la description sont -replacés par la version canonique en amont. - -Normalement, vous devrez d'abord faire : - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -pour que @command{nix-instantiate} n'essaye pas d'ouvrir la base de données -de Nix. - -Par exemple, la commande ci-dessous importe la définition du paquet de -LibreOffice (plus précisément, elle importe la définition du paquet lié à -l'attribut de plus haut-niveau @code{libreoffice}) : - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Importe les métadonnées de l'archive de paquets centrale de la communauté -Haskell, @uref{https://hackage.haskell.org/, Hackage}. Les informations -sont récupérées depuis les fichiers Cabal et incluent toutes les -informations utiles, dont les dépendances des paquets. - -Les options spécifiques sont : - -@table @code -@item --stdin -@itemx -s -Lit un fichier Cabal depuis l'entrée standard. -@item --no-test-dependencies -@itemx -t -N'inclut pas les dépendances requises uniquement par les suites de tests. -@item --cabal-environment=@var{alist} -@itemx -e @var{alist} -@var{alist} est une alist Scheme qui définie l'environnement dans lequel les -conditions de Cabal sont évaluées. Les clefs acceptées sont : @code{os}, -@code{arch}, @code{impl} et une représentation sous forme de chaîne de -caractères du nom d'un drapeau. La valeur associée à un drapeau doit être -le symbole @code{true} ou @code{false}. La valeur associée aux autres clefs -doivent se conformer avec la définition du format de fichiers Cabal. La -valeur par défaut associée avec les clefs @code{os}, @code{arch} et -@code{impl} sont respectivement @samp{linux}, @samp{x86_64} et @samp{ghc}. -@item --recursive -@itemx -r -Traverse le graphe des dépendances du paquet amont donné et génère les -expressions de paquets de tous ceux qui ne sont pas déjà dans Guix. -@end table - -La commande ci-dessous importe les métadonnées de la dernière version du -paquet Haskell @code{HTTP} sans inclure les dépendances des tests et en -spécifiant la valeur du drapeau @samp{network-uri} comme étant @code{false} -: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -Une version spécifique du paquet peut éventuellement être spécifiée en -faisant suivre le nom du paquet par un arobase et un numéro de version comme -dans l'exemple suivant : - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -L'importateur @code{stackage} est une enveloppe autour de l'importateur -@code{hackage}. Il prend un nom de paquet, recherche la version incluse -dans une version au support étendu (LTS) de @uref{https://www.stackage.org, -Stackage} et utilise l'importateur @code{hackage} pour récupérer les -métadonnées. Remarquez que c'est à vous de choisir une version LTS -compatible avec le compilateur GHC utilisé par Guix. - -Les options spécifiques sont : - -@table @code -@item --no-test-dependencies -@itemx -t -N'inclut pas les dépendances requises uniquement par les suites de tests. -@item --lts-version=@var{version} -@itemx -l @var{version} -@var{version} est la version LTS désirée. Si elle est omise, la dernière -version est utilisée. -@item --recursive -@itemx -r -Traverse le graphe des dépendances du paquet amont donné et génère les -expressions de paquets de tous ceux qui ne sont pas déjà dans Guix. -@end table - -La commande ci-dessous importe les métadonnées du paquet Haskell @code{HTTP} -inclus dans la version LTS 7.18 de Stackage : - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Importe les métadonnées du dépôt de paquets ELPA (Emacs Lisp Package -Archive) (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Les options spécifiques sont : - -@table @code -@item --archive=@var{repo} -@itemx -a @var{repo} -@var{repo} identifie le dépôt d'archive depuis lequel récupérer les -informations. Actuellement les dépôts supportés et leurs identifiants sont -: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, qu'on peut choisir avec -l'identifiant @code{gnu}. C'est la valeur par défaut. - -Les paquets de @code{elpa.gnu.org} avec l'une des clefs contenues dans le -porte-clef GnuPG @file{share/emacs/25.1/etc/package-keyring.gpg} (ou -similaire) dans le paquet @code{emacs} (@pxref{Package Installation, ELPA -package signatures,, emacs, The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, qu'on peut -sélectionner avec l'identifiant @code{melpa-stable}. - -@item -@uref{http://melpa.org/packages, MELPA}, qu'on peut sélectionner avec -l'identifiant @code{melpa}. -@end itemize - -@item --recursive -@itemx -r -Traverse le graphe des dépendances du paquet amont donné et génère les -expressions de paquets de tous ceux qui ne sont pas déjà dans Guix. -@end table - -@item crate -@cindex crate -Importe les métadonnées du répertoire des paquets Rust -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Importe les métadonnées du répertoire de paquets -@uref{https://opam.ocaml.org/, OPAM} utilisé par la communauté OCaml. -@end table - -La structure du code de @command{guix import} est modulaire. Il serait -utile d'avoir plus d'importateurs pour d'autres formats de paquets et votre -aide est la bienvenue sur ce sujet (@pxref{Contribuer}). - -@node Invoquer guix refresh -@section Invoquer @command{guix refresh} - -@cindex @command{guix refresh} -L'audience première de la commande @command{guix refresh} est l'ensemble des -développeurs de la distribution logicielle GNU. Par défaut, elle rapporte -les paquets fournis par la distribution qui sont en retard par rapport aux -dernières versions disponibles en amont, comme ceci : - -@example -$ guix refresh -gnu/packages/gettext.scm:29:13: gettext serait mis à jour de 0.18.1.1 à 0.18.2.1 -gnu/packages/glib.scm:77:12: glib serait mis à jour de 2.34.3 à 2.37.0 -@end example - -Autrement, on peut spécifier les paquets à considérer, auquel cas un -avertissement est émis pour les paquets qui n'ont pas de gestionnaire de -mise à jour associé : - -@example -$ guix refresh coreutils guile guile-ssh -gnu/packages/ssh.scm:205:2 : avertissement : aucun gestionnaire de mise à jour pour guile-ssh -gnu/packages/guile.scm:136:12 : guile serait mis à jour de 2.0.12 à 2.0.13 -@end example - -@command{guix refresh} navigue le dépôt amont de chaque paquet et détermine -le numéro de version le plus élevé parmi les versions publiées. La commande -sait comment mettre à jour certains types de paquets : les paquets GNU, les -paquets ELPA, etc. — voir la documentation pour @option{--type} ci-dessous. -Il y a beaucoup de paquet cependant pour lesquels il manque une méthode pour -déterminer si une nouvelle version est disponible en amont. Cependant, le -mécanisme est extensible, alors n'hésitez pas à nous contacter pour ajouter -une nouvelle méthode ! - -@table @code - -@item --recursive -Considère les paquets spécifiés et tous les paquets dont ils dépendent. - -@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 - -Parfois les noms en amont diffèrent du nom de paquet utilisé par Guix et -@command{guix refresh} a besoin d'un peu d'aide. La plupart des -gestionnaires de mise à jour honorent la propriété @code{upstream-name} dans -les définitions de paquets, ce qui peut être utilisé à cette fin : - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -Lorsque l'option @code{--update} est utilisée, elle modifie les fichiers -source de la distribution pour mettre à jour le numéro de version et le hash -de l'archive source de ces recettes de paquets (@pxref{Définition des paquets}). -Cela est effectué en téléchargeant la dernière version de l'archive des -sources de chaque paquet et des signatures associées, en authentifiant -l'archive téléchargée avec sa signature en utilisant @command{gpg} puis en -calculant son hash. Lorsque la clef publique utilisée pour signer l'archive -manque du porte-clefs de l'utilisateur, le gestionnaire tente de la -récupérer automatiquement d'un serveur de clef public ; si cela réussi, la -clef est ajoutée au porte-clefs de l'utilisateur, sinon @command{guix -refresh} rapporte une erreur. - -Les options suivantes sont supportées : - -@table @code - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considérer le paquet évalué par @var{expr}. - -C'est utile pour précisément se référer à un paquet, comme dans cet exemple -: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -Cette commande liste les paquets qui dépendent de la libc « finale » (en -gros tous les paquets). - -@item --update -@itemx -u -Met à jour les fichiers source de la distribution (les recettes de paquets) -en place. Cette option est généralement utilisée depuis une copie du dépôt -git de Guix (@pxref{Lancer Guix avant qu'il ne soit installé}) : - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Définition des paquets}, pour plus d'information sur les définitions des -paquets. - -@item --select=[@var{subset}] -@itemx -s @var{subset} -Choisi tous les paquets dans @var{subset}, entre @code{core} et -@code{non-core}. - -Le sous-ensemble @code{core} se réfère à tous les paquets du cœur de la -distribution — c.-à-d.@: les paquets qui sont utilisés pour construire « -tout le reste ». Cela comprend GCC, libc, Binutils, Bash, etc. -Habituellement, changer l'un de ces paquets dans la distribution implique de -reconstruire tous les autres. Ainsi, ces mises à jour sont une nuisance -pour les utilisateurs, en terme de temps de compilation et de bande passante -utilisés pour effectuer la mise à jour. - -Le sous-ensemble @code{non-core} se réfère au reste des paquets. C'est -habituellement utile dans les cas où une mise à jour des paquets du cœur -serait dérangeante. - -@item --manifest=@var{fichier} -@itemx -m @var{fichier} -Choisi tous les paquets du manifeste dans @var{file}. C'est utile pour -vérifier qu'aucun des paquets du manifeste utilisateur ne peut être mis à -jour. - -@item --type=@var{updater} -@itemx -t @var{updater} -Chois uniquement les paquets pris en charge par @var{updater} -(éventuellement une liste de gestionnaires de mise à jour séparés par des -virgules). Actuellement, @var{updater} peut être l'une des valeurs suivantes -: - -@table @code -@item gnu -le gestionnaire de mise à jour pour les paquets GNU ; -@item gnome -le gestionnaire de mise à jour pour les paquets GNOME ; -@item kde -le gestionnaire de mise à jour pour les paquets KDE ; -@item xorg -le gestionnaire de mise à jour pour les paquets X.org ; -@item kernel.org -le gestionnaire de mise à jour pour les paquets hébergés sur kernel.org ; -@item elpa -le gestionnaire de mise à jour pour les paquets @uref{http://elpa.gnu.org/, -ELPA} ; -@item cran -le gestionnaire de mise à jour pour les paquets -@uref{https://cran.r-project.org/, CRAN} ; -@item bioconductor -le gestionnaire de mise à jour pour les paquets -@uref{https://www.bioconductor.org/, Bioconductor} ; -@item cpan -le gestionnaire de mise à jour pour les paquets @uref{http://www.cpan.org/, -CPAN} ; -@item pypi -le gestionnaire de mise à jour pour les paquets -@uref{https://pypi.python.org, PyPI} ; -@item gem -le gestionnaire de mise à jour pour les paquets @uref{https://rubygems.org, -RubyGems} ; -@item github -le gestionnaire de mise à jour pour les paquets @uref{https://github.com, -GitHub} ; -@item hackage -le gestionnaire de mise à jour pour les paquets -@uref{https://hackage.haskell.org, Hackage} ; -@item stackage -le gestionnaire de mise à jour pour les paquets -@uref{https://www.stackage.org, Stackage} ; -@item crate -le gestionnaire de mise à jour pour les paquets @uref{https://crates.io, -Crates} ; -@item launchpad -le gestionnaire de mise à jour pour les paquets @uref{https://launchpad.net, -Launchpad} -@end table - -Par exemple, la commande suivante ne vérifie que les mises à jour des -paquets Emacs hébergés sur @code{elpa.gnu.org} et les paquets CRAN : - -@example -$ guix refresh --type=elpa,cran -gnu/packages/statistics.scm:819:13 : r-testthat serait mis à jour de 0.10.0 à 0.11.0 -gnu/packages/emacs.scm:856:13 : emacs-auctex serait mis à jour de 11.88.6 à 11.88.9 -@end example - -@end table - -En plus, on peut passer à @command{guix refresh} un ou plusieurs noms de -paquets, comme dans cet exemple : - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -La commande au-dessus met à jour spécifiquement les paquets @code{emacs} et -@code{idutils}. L'option @code{--select} n'aurait aucun effet dans ce cas. - -Pour déterminer s'il faut mettre à jour un paquet, il est parfois pratique -de savoir quels paquets seraient affectés par la mise à jour pour pouvoir -vérifier la compatibilité. Pour cela l'option suivante peut être utilisée -avec un ou plusieurs noms de paquets passés à @command{guix refresh} : - -@table @code - -@item --list-updaters -@itemx -L -Liste les gestionnaires de mise à jour et quitte (voir l'option -@option{--type} plus haut). - -Pour chaque gestionnaire, affiche le pourcentage de paquets qu'il couvre ; à -la fin, affiche le pourcentage de paquets couverts par tous les -gestionnaires. - -@item --list-dependent -@itemx -l -Liste les paquets de plus haut-niveau qui devraient être reconstruits après -la mise à jour d'un ou plusieurs paquets. - -@xref{Invoquer guix graph, le type @code{reverse-package} de @command{guix -graph}}, pour des informations sur la manière de visualiser la liste des -paquets dépendant d'un autre. - -@end table - -Soyez conscients que l'option @code{--list-dependent} ne fait -@emph{qu'approximer} les reconstructions qui seraient requises par une mise -à jour. Plus de reconstructions pourraient être requises dans certaines -circonstances. - -@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 - -La commande ci-dessus liste un ensemble de paquets qui peuvent être -construits pour vérifier la compatibilité d'une mise à jour de @code{flex}. - -@table @code - -@item --list-transitive -Lister tous les paquets dont un paquet ou plus dépendent. - -@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 - -La commande ci-dessus liste un ensemble de paquets qui, lorsqu'ils sont -modifiés, causent la reconstruction de @code{flex}. - -Les options suivante peuvent être utilisées pour personnaliser les -opérations avec GnuPG : - -@table @code - -@item --gpg=@var{commande} -Utilise @var{commande} comme la commande de GnuPG 2.x. @var{commande} est -recherchée dans @code{PATH}. - -@item --keyring=@var{fichier} -Utilise @var{fichier} comme porte-clefs pour les clefs amont. @var{fichier} -doit être dans le @dfn{format keybox}. Les fichiers Keybox ont d'habitude -un nom qui fini par @file{.kbx} et GNU@tie{}Privacy Guard (GPG) peut -manipuler ces fichiers (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the -Privacy Guard}, pour plus d'informations sur un outil pour manipuler des -fichiers keybox). - -Lorsque cette option est omise, @command{guix refresh} utilise -@file{~/.config/guix/upstream/trustedkeys.kbx} comme porte-clefs pour les -clefs de signature amont. Les signatures OpenPGP sont vérifiées avec ces -clefs ; les clefs manquantes sont aussi téléchargées dans ce porte-clefs -(voir @option{--key-download} plus bas). - -Vous pouvez exporter les clefs de votre porte-clefs GPG par défaut dans un -fichier keybox avec une commande telle que : - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx -@end example - -De même, vous pouvez récupérer des clefs dans un fichier keybox spécifique -comme ceci : - -@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} pour plus d'informations sur l'option @option{--keyring} de -GPG. - -@item --key-download=@var{politique} -Gère les clefs OpenPGP manquantes d'après la @var{politique}, qui peut être -l'une des suivantes : - -@table @code -@item always -Toujours télécharger les clefs manquantes depuis un serveur de clefs et les -ajouter au porte-clefs de l'utilisateur. - -@item never -Ne jamais essayer de télécharger les clefs OpenPGP manquante. Quitter à la -place. - -@item interactive -Lorsqu'on rencontre un paquet signé par une clef OpenPGP inconnue, demander -à l'utilisateur s'il souhaite la télécharger ou non. C'est le comportement -par défaut. -@end table - -@item --key-server=@var{host} -Utiliser @var{host} comme serveur de clefs OpenPGP lors de l'importe d'une -clef publique. - -@end table - -Le gestionnaire de mises à jour @code{github} utilise -@uref{https://developer.github.com/v3/, l'API de GitHub} pour faire des -requêtes sur les nouvelles versions. Lorsqu'elle est utilisé de manière -répétée, p.@: ex.@: lorsque vous vérifiez tous les paquets, GitHub finira -par refuser de répondre à d'autres requêtes de l'API. Par défaut 60 -requêtes à l'heure sont autorisées, et une vérification complète de tous les -paquets GitHub dans Guix requiert bien plus que cela. L'authentification -avec GitHub à travers l'utilisation d'un jeton d'API lève ces limites. Pour -utiliser un jeton de l'API, initialisez la variable d'environnement -@code{GUIX_GITHUB_TOKEN} avec un jeton que vous vous serez procuré sur -@uref{https://github.com/settings/tokens} ou autrement. - - -@node Invoquer guix lint -@section Invoquer @command{guix lint} - -@cindex @command{guix lint} -@cindex paquets, chercher des erreurs -La commande @command{guix lint} est conçue pour aider les développeurs à -éviter des erreurs commune et à utiliser un style cohérent lors de -l'écriture de recettes de paquets. Elle lance des vérifications sur un -ensemble de paquets donnés pour trouver des erreurs communes dans leur -définition. Les @dfn{vérifieurs} disponibles comprennent (voir -@code{--list-checkers} pour une liste complète) : - -@table @code -@item synopsis -@itemx description -Vérifie certaines règles typographiques et stylistiques dans les -descriptions et les synopsis. - -@item inputs-should-be-native -Identifie les entrées qui devraient sans doute plutôt être des entrées -natives. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Sonde les URL @code{home-page} et @code{source} et rapporte celles qui sont -invalides. Suggère une URL en @code{mirror://} lorsque c'est possible. Si -l'URL de @code{source} redirige vers une URL GitHub, recommande d'utiliser -l'URL GitHub. Vérifie que le nom du fichier source a un sens, p.@: ex.@: -qu'il ne s'agisse pas juste d'un numéro de version ou « git-checkout », sans -avoir déclaré un @code{file-name} (@pxref{Référence des origines}). - -@item source-unstable-tarball -Analyse l'URL @code{source} pour déterminer si une archive de GitHub est -autogénérée ou s'il s'agit d'une archive de publication. Malheureusement -les archives autogénérées de GitHub sont parfois régénérées. - -@item cve -@cindex vulnérabilités -@cindex CVE, Common Vulnerabilities and Exposures -Rapporte les vulnérabilités connues trouvées dans les bases de données CVE -(Common Vulnerabilities and Exposures) de l'année en cours et des années -précédentes @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, publié par le -NIST américain}. - -Pour voir les informations sur une vulnérabilité en particulier, visitez les -pages : - -@itemize -@item -@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-ANNÉE-ABCD} -@item -@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-ANNÉE-ABCD} -@end itemize - -@noindent -où @code{CVE-ANNÉE-ABCD} est l'identifiant CVE — p.@: ex.@: -@code{CVE-2015-7554}. - -Les développeurs de paquets peuvent spécifier dans les recettes des paquets -le nom @uref{https://nvd.nist.gov/cpe.cfm,CPE (Common Platform Enumeration)} -et la version du paquet s'ils diffèrent du nom et de la version que Guix -utilise, comme dans cet exemple : - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE calls this package "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See . -Certaines entrées dans la base de données CVE ne spécifient pas la version -du paquet auquel elles s'appliquent et lui restera donc attachée pour -toujours. Les développeurs qui trouvent des alertes CVE et ont vérifiés -qu'elles peuvent être ignorées peuvent les déclarer comme dans cet exemple : - -@example -(package - (name "t1lib") - ;; @dots{} - ;; Ces CVE ne s'appliquent plus et peuvent être ignorée sans problème. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item formatting -Avertit le développeurs lorsqu'il y a des problèmes de formatage du code -source évident : des espaces en fin de ligne, des tabulations, etc. -@end table - -La syntaxe générale est : - -@example -guix lint @var{options} @var{package}@dots{} -@end example - -Si aucun paquet n'est donné par la ligne de commande, tous les paquets -seront vérifiés. Les @var{options} peuvent contenir aucune ou plus des -options suivantes : - -@table @code -@item --list-checkers -@itemx -l -Liste et décrit tous les vérificateurs disponibles qui seront lancés sur les -paquets puis quitte. - -@item --checkers -@itemx -c -N'active que les vérificateurs spécifiés dans une liste de noms séparés par -des virgules parmi la liste renvoyée par @code{--list-checkers}. - -@end table - -@node Invoquer guix size -@section Invoquer @command{guix size} - -@cindex taille -@cindex paquet, taille -@cindex closure -@cindex @command{guix size} -La commande @command{guix size} aide les développeurs à dresser un profil de -l'utilisation du disque que font les paquets. C'est facile de négliger -l'impact d'une dépendance supplémentaire ajoutée à un paquet, ou l'impact de -l'utilisation d'une sortie unique pour un paquet qui pourrait être -facilement séparé (@pxref{Des paquets avec plusieurs résultats}). Ce sont les -problèmes que @command{guix size} peut typiquement mettre en valeur. - -On peut passer un ou plusieurs spécifications de paquets à la commande, -comme @code{gcc@@4.8} ou @code{guile:debug}, ou un nom de fichier dans le -dépôt. Regardez cet exemple : - -@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 closure -Les éléments du dépôt listés ici constituent la @dfn{clôture transitive} de -Coreutils — c.-à-d.@: Coreutils et toutes ses dépendances, récursivement — -comme ce qui serait renvoyé par : - -@example -$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 -@end example - -Ici, la sortie possède trois colonnes à côté de chaque élément du dépôt. La -première colonne, nommée « total », montre la taille en mébioctet (Mio) de -la clôture de l'élément du dépôt — c'est-à-dire sa propre taille plus la -taille de ses dépendances. La colonne suivante, nommée « lui-même », montre -la taille de l'élément lui-même. La dernière colonne montre le ration de la -taille de l'élément lui-même par rapport à celle de tous les éléments -montrés. - -Dans cet exemple, on voit que la clôture de Coreutils pèse 79@tie{}Mio, dont -la plupart est dû à la libc et aux bibliothèques à l'exécution de GCC (ce -n'est pas un problème en soit que la libc et les bibliothèques de GCC -représentent une grande part de la clôture parce qu'elles sont toujours -disponibles sur le système de toute façon). - -Lorsque les paquets passés à @command{guix size} sont disponibles dans le -dépôt@footnote{Plus précisément, @command{guix size} cherche les variantes -@emph{non greffées} des paquets donnés, tels qu'ils sont renvoyés par -@code{guix build @var{paquet} --no-graft}. @xref{Mises à jour de sécurité} pour des -informations sur les greffes}, @command{guix size} demande au démon de -déterminer ses dépendances, et mesure sa taille dans le dépôt, comme avec -@command{du -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU -Coreutils}). - -Lorsque les paquets donnés ne sont @emph{pas} dans le dépôt, @command{guix -size} rapporte les informations en se basant sur les substituts disponibles -(@pxref{Substituts}). Cela permet de profiler l'utilisation du disque des -éléments du dépôt même s'ils ne sont pas sur le disque, mais disponibles à -distance. - -Vous pouvez aussi spécifier plusieurs noms de paquets : - -@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 -Dans cet exemple on voit que la combinaison des quatre paquets prend -102.3@tie{}Mio en tout, ce qui est bien moins que la somme des clôtures -puisqu'ils ont beaucoup de dépendances en commun. - -Les options disponibles sont : - -@table @option - -@item --substitute-urls=@var{urls} -Utilise les informations de substituts de @var{urls}. -@xref{client-substitute-urls, the same option for @code{guix build}}. - -@item --sort=@var{clef} -Trie les lignes en fonction de la @var{clef}, l'une des options suivantes : - -@table @code -@item self -la taille de chaque élément (par défaut) ; -@item closure -la taille totale de la clôture de l'élément. -@end table - -@item --map-file=@var{fichier} -Écrit un schéma de l'utilisation du disque au format PNG dans @var{fichier}. - -Pour l'exemple au-dessus, le schéma ressemble à ceci : - -@image{images/coreutils-size-map,5in,, schéma de l'utilisation du disque de -Coreutils produit par @command{guix size}} - -Cette option requiert l'installation de -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} et qu'il -soit visible dans le chemin de recherche des modules Guile. Lorsque ce -n'est pas le cas, @command{guix size} plante en essayant de le charger. - -@item --system=@var{système} -@itemx -s @var{système} -Considère les paquets pour @var{système} — p.@: ex.@: @code{x86_64-linux}. - -@end table - -@node Invoquer guix graph -@section Invoque @command{guix graph} - -@cindex DAG -@cindex @command{guix graph} -@cindex dépendances des paquets -Les paquets et leurs dépendances forment un @dfn{graphe}, plus précisément -un graphe orienté acyclique (DAG). Il peut vite devenir difficile d'avoir -une représentation mentale du DAG d'un paquet, donc la commande -@command{guix graph} fournit une représentation visuelle du DAG. Par -défaut, @command{guix graph} émet un représentation du DAG dans le format -d'entrée de @uref{http://www.graphviz.org/, Graphviz}, pour que sa sortie -puisse être passée directement à la commande @command{dot} de Graphviz. -Elle peut aussi émettre une page HTML avec du code Javascript pour afficher -un « digramme d'accords » dans un navigateur Web, grâce à la bibliothèque -@uref{https://d3js.org/, d3.js}, ou émettre des requêtes Cypher pour -construire un graphe dans une base de donnée de graphes supportant le -langage de requêtes @uref{http://www.opencypher.org/, openCypher}. La -syntaxe générale est : - -@example -guix graph @var{options} @var{paquet}@dots{} -@end example - -Par exemple, la commande suivante génère un fichier PDF représentant le DAG -du paquet pour GNU@tie{}Core Utilities, qui montre ses dépendances à la -compilation : - -@example -guix graph coreutils | dot -Tpdf > dag.pdf -@end example - -La sortie ressemble à ceci : - -@image{images/coreutils-graph,2in,,Graphe de dépendance de GNU Coreutils} - -Joli petit graphe, non ? - -Mais il y a plus qu'un seul graphe ! Celui au-dessus est concis : c'est le -graphe des objets paquets, en omettant les entrées implicites comme GCC, -libc, grep, etc. Il est souvent utile d'avoir ces graphes concis, mais -parfois on veut voir plus de détails. @command{guix graph} supporte -plusieurs types de graphes, qui vous permettent de choisir le niveau de -détails : - -@table @code -@item package -C'est le type par défaut utilisé dans l'exemple plus haut. Il montre le DAG -des objets paquets, sans les dépendances implicites. C'est concis, mais -omet pas mal de détails. - -@item reverse-package -Cela montre le DAG @emph{inversé} des paquets. Par exemple : - -@example -guix graph --type=reverse-package ocaml -@end example - -…@: crée le graphe des paquets qui dépendent @emph{explicitement} d'OCaml -(si vous vous intéressez aussi au cas où OCaml est une dépendance implicite, -voir @code{reverse-bag} plus bas). - -Remarquez que pour les paquets du cœur de la distribution, cela crée des -graphes énormes. Si vous voulez seulement voir le nombre de paquets qui -dépendent d'un paquet donnés, utilisez @command{guix refresh ---list-dependent} (@pxref{Invoquer guix refresh, -@option{--list-dependent}}). - -@item bag-emerged -C'est le DAG du paquet, @emph{avec} les entrées implicites. - -Par exemple, la commande suivante : - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf -@end example - -…@: montre ce graphe plus gros : - -@image{images/coreutils-bag-graph,,5in,Graphe des dépendances détaillé de -GNU Coreutils} - -En bas du graphe, on voit toutes les entrées implicites de -@var{gnu-build-system} (@pxref{Systèmes de construction, @code{gnu-build-system}}). - -Maintenant, remarquez que les dépendances de ces entrées implicites — -c'est-à-dire les @dfn{dépendances de bootstrap} (@pxref{Bootstrapping}) — ne -sont pas affichées, pour rester concis. - -@item bag -Comme @code{bag-emerged} mais cette fois inclus toutes les dépendances de -bootstrap. - -@item bag-with-origins -Comme @code{bag}, mais montre aussi les origines et leurs dépendances. - -@item reverse-bag -Cela montre le DAG @emph{inverse} des paquets. Contrairement à -@code{reverse-package}, il montre aussi les dépendance implicites. Par -exemple : - -@example -guix graph -t reverse-bag dune -@end example - -@noindent -…@: crée le graphe des tous les paquets qui dépendent de Dune, directement -ou indirectement. Comme Dune est une dépendance @emph{implicite} de -nombreux paquets @i{via} @code{dune-build-system}, cela montre un plus grand -nombre de paquets, alors que @code{reverse-package} en montrerait très peu, -voir aucun. - -@item dérivation -C'est la représentation lu plus détaillée : elle montre le DAG des -dérivations (@pxref{Dérivations}) et des éléments du dépôt. Comparé à la -représentation ci-dessus, beaucoup plus de nœuds sont visibles, dont les -scripts de construction, les correctifs, les modules Guile, etc. - -Pour ce type de graphe, il est aussi possible de passer un nom de fichier -@file{.drv} à la place d'un nom de paquet, comme dans : - -@example -guix graph -t derivation `guix system build -d my-config.scm` -@end example - -@item module -C'est le graphe des @dfn{modules de paquets} (@pxref{Modules de paquets}). Par -exemple, la commande suivante montre le graphe des modules de paquets qui -définissent le paquet @code{guile} : - -@example -guix graph -t module guile | dot -Tpdf > module-graph.pdf -@end example -@end table - -Tous les types ci-dessus correspondent aux @emph{dépendances à la -construction}. Le type de graphe suivant représente les @emph{dépendances à -l'exécution} : - -@table @code -@item references -C'est le graphe des @dfn{references} d'une sortie d'un paquet, telles que -renvoyées par @command{guix gc --references} (@pxref{Invoquer guix gc}). - -Si la sortie du paquet donnée n'est pas disponible dans le dépôt, -@command{guix graph} essayera d'obtenir les informations sur les dépendances -à travers les substituts. - -Vous pouvez aussi passer un nom de fichier du dépôt plutôt qu'un nom de -paquet. Par exemple, la commande ci-dessous produit le graphe des -références de votre profile (qui peut être gros !) : - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -C'est le graphe des @dfn{référents} d'un élément du dépôt, tels que renvoyés -par @command{guix gc --referrers} (@pxref{Invoquer guix gc}). - -Cela repose exclusivement sur les informations de votre dépôt. Par exemple, -supposons que Inkscape est actuellement disponible dans 10 profils sur votre -machine ; @command{guix graph -t referrers inkscape} montrera le graphe dont -la racine est Inkscape avec 10 profils qui y sont liés. - -Cela peut aider à déterminer ce qui empêche un élément du dépôt d'être -glané. - -@end table - -Les options disponibles sont les suivante : - -@table @option -@item --type=@var{type} -@itemx -t @var{type} -Produit un graphe en sortie de type @var{type} où @var{type} doit être l'un -des types au-dessus. - -@item --list-types -Liste les types de graphes supportés. - -@item --backend=@var{moteur} -@itemx -b @var{moteur} -Produit un graphe avec le @var{moteur} choisi. - -@item --list-backends -Liste les moteurs de graphes supportés. - -Actuellement les moteurs disponibles sont Graphviz et d3.js. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Considérer le paquet évalué par @var{expr}. - -C'est utile pour précisément se référer à un paquet, comme dans cet exemple -: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{système} -@itemx -s @var{système} -Affiche le graphe pour @var{système} — p.@: ex.@: @code{i686-linux}. - -Le graphe de dépendance des paquets est la plupart du temps indépendant de -l'architecture, mais il y a quelques parties qui dépendent de l'architecture -que cette option vous permet de visualiser. -@end table - - - -@node Invoquer guix publish -@section Invoquer @command{guix publish} - -@cindex @command{guix publish} -Le but de @command{guix publish} est de vous permettre de partager -facilement votre dépôt avec d'autres personnes qui peuvent ensuite -l'utiliser comme serveur de substituts (@pxref{Substituts}). - -Lorsque @command{guix publish} est lancé, il crée un serveur HTTP qui permet -à n'importe qui avec un accès réseau d'y récupérer des substituts. Cela -signifie que toutes les machines qui font tourner Guix peuvent aussi agir -comme une ferme de construction, puisque l'interface HTTP est compatible -avec Hydra, le logiciel derrière la ferme de construction -@code{@value{SUBSTITUTE-SERVER}}. - -Pour des raisons de sécurité, chaque substitut est signé, ce qui permet aux -destinataires de vérifier leur authenticité et leur intégrité -(@pxref{Substituts}). Comme @command{guix publish} utilise la clef de -signature du système, qui n'est lisible que par l'administrateur système, il -doit être lancé en root ; l'option @code{--user} lui fait baisser ses -privilèges le plus tôt possible. - -La pair de clefs pour les signatures doit être générée avant de lancer -@command{guix publish}, avec @command{guix archive --generate-key} -(@pxref{Invoquer guix archive}). - -La syntaxe générale est : - -@example -guix publish @var{options}@dots{} -@end example - -Lancer @command{guix publish} sans arguments supplémentaires lancera un -serveur HTTP sur le port 8080 : - -@example -guix publish -@end example - -Une fois qu'un serveur de publication a été autorisé (@pxref{Invoquer guix archive}), le démon peut télécharger des substituts à partir de lui : - -@example -guix-daemon --substitute-urls=http://example.org:8080 -@end example - -Par défaut, @command{guix publish} compresse les archives à la volée quand -il les sert. Ce mode « à la volée » est pratique puisqu'il ne demande -aucune configuration et est disponible immédiatement. Cependant, lorsqu'il -s'agit de servir beaucoup de clients, nous recommandons d'utiliser l'option -@option{--cache}, qui active le cache des archives avant de les envoyer aux -clients — voir les détails plus bas. La commande @command{guix weather} -fournit un manière pratique de vérifier ce qu'un serveur fournit -(@pxref{Invoquer guix weather}). - -En bonus, @command{guix publish} sert aussi un miroir adressé par le contenu -des fichiers source référencées dans les enregistrements @code{origin} -(@pxref{Référence des origines}). Par exemple, en supposant que @command{guix -publish} tourne sur @code{example.org}, l'URL suivante renverra le fichier -brut @file{hello-2.10.tar.gz} avec le hash SHA256 donné (représenté sous le -format @code{nix-base32}, @pxref{Invoquer guix hash}) : - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -Évidemment, ces URL ne fonctionnent que pour des fichiers dans le dépôt ; -dans les autres cas, elles renvoie une erreur 404 (« Introuvable »). - -@cindex journaux de construction, publication -Les journaux de construction sont disponibles à partir des URL @code{/log} -comme ceci : - -@example -http://example.org/log/gwspk@dots{}-guile-2.2.3 -@end example - -@noindent -Lorsque @command{guix-daemon} est configuré pour sauvegarder les journaux de -construction compressés, comme c'est le cas par défaut (@pxref{Invoquer guix-daemon}), les URL @code{/log} renvoient le journal compressé tel-quel, -avec un en-tête @code{Content-Type} ou @code{Content-Encoding} approprié. -Nous recommandons de lancer @command{guix-daemon} avec -@code{--log-compression=gzip} parce que les navigateurs web les -décompressent automatiquement, ce qui n'est pas le cas avec la compression -bzip2. - -Les options suivantes sont disponibles : - -@table @code -@item --port=@var{port} -@itemx -p @var{port} -Écoute les requêtes HTTP sur le @var{port} - -@item --listen=@var{hôte} -Écoute sur l'interface réseau de @var{hôte}. Par défaut, la commande -accepte les connexions de n'importe quelle interface. - -@item --user=@var{utilisateur} -@itemx -u @var{utilisateur} -Charge les privilèges de @var{utilisateur} le plus vite possible — -c.-à-d. une fois que la socket du serveur est ouverte et que la clef de -signature a été lue. - -@item --compression[=@var{niveau}] -@itemx -C [@var{niveau}] -Compresse les données au @var{niveau} donné. Lorsque le @var{niveau} est -zéro, désactive la compression. L'intervalle 1 à 9 correspond aux -différents niveaux de compression gzip : 1 est le plus rapide et 9 est la -meilleure (mais gourmande en CPU). Le niveau par défaut est 3. - -À moins que @option{--cache} ne soit utilisé, la compression se fait à la -volée et les flux compressés ne sont pas cachés. Ainsi, pour réduire la -charge sur la machine qui fait tourner @command{guix publish}, c'est une -bonne idée de choisir un niveau de compression faible, de lancer -@command{guix publish} derrière un serveur de cache ou d'utiliser -@option{--cache}. Utilise @option{--cache} a l'avantage qu'il permet à -@command{guix publish} d'ajouter l'en-tête HTTP @code{Content-Length} à sa -réponse. - -@item --cache=@var{répertoire} -@itemx -c @var{répertoire} -Cache les archives et les métadonnées (les URL @code{.narinfo}) dans -@var{répertoire} et ne sert que les archives dans ce cache. - -Lorsque cette option est omise, les archives et les métadonnées sont crées à -la volée. Cela réduit la bande passante disponible, surtout quand la -compression est activée puisqu'elle pourrait être limitée par le CPU. Un -autre inconvénient au mode par défaut est que la taille des archives n'est -pas connue à l'avance, donc @command{guix publish} n'ajoute pas l'en-tête -@code{Content-Length} à ses réponses, ce qui empêche les clients de savoir -la quantité de données à télécharger. - -À l'inverse, lorsque @option{--cache} est utilisée, la première requête pour -un élément du dépôt (via une URL @code{.narinfo}) renvoie une erreur 404 et -déclenche la création de l'archive — en calculant son @code{.narinfo} et en -compressant l'archive au besoin. Une fois l'archive cachée dans -@var{répertoire}, les requêtes suivantes réussissent et sont servies -directement depuis le cache, ce qui garanti que les clients ont la meilleure -bande passante possible. - -Le processus de création est effectué par des threads de travail. Par -défaut, un thread par cœur du CPU est créé, mais cela peut être -personnalisé. Voir @option{--workers} plus bas. - -Lorsque l'option @option{--ttl} est utilisée, les entrées cachées sont -automatiquement supprimées lorsqu'elles expirent. - -@item --workers=@var{N} -Lorsque @option{--cache} est utilisée, demande l'allocation de @var{N} -thread de travail pour créer les archives. - -@item --ttl=@var{ttl} -Produit des en-têtes HTTP @code{Cache-Control} qui expriment une durée de -vie (TTL) de @var{ttl}. @var{ttl} peut dénoter une durée : @code{5d} -signifie 5 jours, @code{1m} signifie un mois, etc. - -Cela permet au Guix de l'utilisateur de garder les informations en cache -pendant @var{ttl}. Cependant, remarquez que @code{guix publish} ne garanti -pas lui-même que les éléments du dépôt qu'il fournit seront toujours -disponible pendant la durée @var{ttl}. - -En plus, lorsque @option{--cache} est utilisée, les entrées cachées qui -n'ont pas été demandé depuis @var{ttl} et n'ont pas d'élément correspondant -dans le dépôt peuvent être supprimées. - -@item --nar-path=@var{chemin} -Utilise @var{chemin} comme préfixe des URL de fichier « nar » -(@pxref{Invoquer guix archive, normalized archives}). - -Par défaut, les nars sont présents à l'URL comme -@code{/nar/gzip/@dots{}-coreutils-8.25}. Cette option vous permet de -changer la partie @code{/nar} en @var{chemin}. - -@item --public-key=@var{fichier} -@itemx --private-key=@var{fichier} -Utilise les @var{fichier}s spécifiques comme pair de clefs utilisées pour -signer les éléments avant de les publier. - -Les fichiers doivent correspondre à la même pair de clefs (la clef privée -est utilisée pour signer et la clef publique est seulement ajouté aux -métadonnées de la signature). Ils doivent contenir les clefs dans le format -s-expression canonique produit par @command{guix archive --generate-key} -(@pxref{Invoquer guix archive}). Par défaut, -@file{/etc/guix/signing-key.pub} et @file{/etc/guix/signing-key.sec} sont -utilisés. - -@item --repl[=@var{port}] -@itemx -r [@var{port}] -Crée un serveur REPL Guile (@pxref{REPL Servers,,, guile, GNU Guile -Reference Manual}) sur @var{pport} (37146 par défaut). C'est surtout utile -pour déboguer un serveur @command{guix publish} qui tourne. -@end table - -Activer @command{guix publish} sur un système Guix est vraiment une seule -ligne : instanciez simplement un service @code{guix-publish-service-type} -dans le champs @code{services} de votre déclaration @code{operating-system} -(@pxref{guix-publish-service-type, @code{guix-publish-service-type}}). - -Si vous avez installé Guix sur une « distro externe », suivez ces -instructions : - -@itemize -@item -Si votre distro hôte utilise le système d'init systemd : - -@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 -Si votre distribution hôte utilise le système d'initialisation Upstart : - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -Sinon, procédez de manière similaire avec votre système d'init de votre -distro. -@end itemize - -@node Invoquer guix challenge -@section Invoquer @command{guix challenge} - -@cindex constructions reproductibles -@cindex constructions vérifiables -@cindex @command{guix challenge} -@cindex défi -Est-ce que les binaires fournis par ce serveur correspondent réellement au -code source qu'il dit avoir construit ? Est-ce que le processus de -construction d'un paquet est déterministe ? Ce sont les question auxquelles -la commande @command{guix challenge} essaye de répondre. - -La première question est évidemment importante : avant d'utiliser un serveur -de substituts (@pxref{Substituts}), il vaut mieux @emph{vérifier} qu'il -fournit les bons binaires et donc le @emph{défier}. La deuxième est ce qui -permet la première : si les constructions des paquets sont déterministes -alors des constructions indépendantes du paquet devraient donner le même -résultat, bit à bit ; si un serveur fournit un binaire différent de celui -obtenu localement, il peut être soit corrompu, soit malveillant. - -On sait que le hash qui apparaît dans @file{/gnu/store} est le hash de -toutes les entrées du processus qui construit le fichier ou le répertoire — -les compilateurs, les bibliothèques, les scripts de construction, -etc. (@pxref{Introduction}). En supposant que les processus de construction -sont déterministes, un nom de fichier dans le dépôt devrait correspondre -exactement à une sortie de construction. @command{guix challenge} vérifie -si il y a bien effectivement une seule correspondance en comparant les -sorties de plusieurs constructions indépendantes d'un élément du dépôt -donné. - -La sortie de la commande ressemble à : - -@smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" -mise à jour de la liste des substituts depuis 'https://@value{SUBSTITUTE-SERVER}'... 100.0% -mise à jour de la liste des substituts depuis 'https://guix.example.org'... 100.0% -le contenu de /gnu/store/@dots{}-openssl-1.0.2d diffère : - empreinte locale : 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d : 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://guix.example.org/nar/@dots{}-openssl-1.0.2d : 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim -le contenu de /gnu/store/@dots{}-git-2.5.0 diffère : - empreinte locale : 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 : 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - https://guix.example.org/nar/@dots{}-git-2.5.0 : 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 -le contenu de /gnu/store/@dots{}-pius-2.1.1 diffère : - empreinte locale : 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 éléments du dépôt ont été analysés : - - 4,749 (74.1%) étaient identiques - - 525 (8.2%) étaient différents - - 1,132 (17.7%) étaient impossibles à évaluer -@end smallexample - -@noindent -Dans cet exemple, @command{guix challenge} scanne d'abord le dépôt pour -déterminer l'ensemble des dérivations construites localement — en opposition -aux éléments qui ont été téléchargées depuis un serveur de substituts — puis -demande leur avis à tous les serveurs de substituts. Il rapporte ensuite -les éléments du dépôt pour lesquels les serveurs ont obtenu un résultat -différent de la construction locale. - -@cindex non-déterminisme, dans les constructions des paquets -Dans l'exemple, @code{guix.example.org} obtient toujours une réponse -différente. Inversement, @code{@value{SUBSTITUTE-SERVER}} est d'accord avec -les constructions locale, sauf dans le cas de Git. Cela peut indiquer que -le processus de construction de Git est non-déterministe, ce qui signifie -que sa sortie diffère en fonction de divers choses que Guix ne contrôle pas -parfaitement, malgré l'isolation des constructions (@pxref{Fonctionnalités}). Les -sources les plus communes de non-déterminisme comprennent l'ajout -d'horodatage dans les résultats des constructions, l'inclusion de nombres -aléatoires et des listes de fichiers ordonnés par numéro d'inœud. Voir -@uref{https://reproducible-builds.org/docs/}, pour plus d'informations. - -Pour trouver ce qui ne va pas avec le binaire de Git, on peut faire quelque -chose comme cela (@pxref{Invoquer 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 - -Cette commande montre les différences entre les fichiers qui résultent de la -construction locale et des fichiers qui résultent de la construction sur -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging -Files,, diffutils, Comparing and Merging Files}). La commande -@command{diff} fonctionne bien avec des fichiers texte. Lorsque des -fichiers binaires diffèrent cependant, @uref{https://diffoscope.org/, -Diffoscope} est une meilleure option. C'est un outil qui aide à visualiser -les différences entre toute sorte de fichiers. - -Une fois que vous avez fait ce travail, vous pourrez dire si les différences -sont dues au non-déterminisme du processus de construction ou à la -malhonnêteté du serveur. Nous avons fait beaucoup d'effort pour éliminer -les sources de non-déterminisme dans les paquets pour rendre plus facile la -vérification des substituts, mais bien sûr, c'est un processus qui -n'implique pas que Guix, mais une grande partie de la communauté des -logiciels libres. Pendant ce temps, @command{guix challenge} est un outil -pour aider à corriger le problème. - -Si vous écrivez un paquet pour Guix, nous vous encourageons à vérifier si -@code{@value{SUBSTITUTE-SERVER}} et d'autres serveurs de substituts -obtiennent le même résultat que vous avec : - -@example -$ guix challenge @var{paquet} -@end example - -@noindent -où @var{paquet} est une spécification de paquet comme @code{guile@@2.0} ou -@code{glibc:debug}. - -La syntaxe générale est : - -@example -guix challenge @var{options} [@var{paquets}@dots{}] -@end example - -Lorsqu'une différence est trouvée entre l'empreinte d'un élément construit -localement et celle d'un substitut fournit par un serveur, ou parmi les -substituts fournis par différents serveurs, la commande l'affiche comme dans -l'exemple ci-dessus et sa valeur de sortie est 2 (les autres valeurs -différentes de 0 indiquent d'autres sortes d'erreurs). - -L'option qui compte est : - -@table @code - -@item --substitute-urls=@var{urls} -Considère @var{urls} comme la liste des URL des sources de substituts -séparés par des espaces avec lesquels comparer les paquets locaux. - -@item --verbose -@itemx -v -Montre des détails sur les correspondances (contenu identique) en plus des -informations sur différences. - -@end table - -@node Invoquer guix copy -@section Invoquer @command{guix copy} - -@cindex copier des éléments du dépôt par SSH -@cindex SSH, copie d'éléments du dépôt -@cindex partager des éléments du dépôt entre plusieurs machines -@cindex transférer des éléments du dépôt entre plusieurs machines -La commande @command{guix copy} copie des éléments du dépôt d'une machine -vers le dépôt d'une autre machine à travers une connexion SSH@footnote{Cette -commande n'est disponible que si Guile-SSH est trouvé. @xref{Prérequis}, -pour des détails}. Par exemple, la commande suivante copie le paquet -@code{coreutils}, le profil utilisateur et toutes leurs dépendances sur -@var{hôte}, en tant qu'utilisateur @var{utilisateur} : - -@example -guix copy --to=@var{utilisateur}@@@var{hôte} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -Si certains éléments à copier sont déjà présents sur @var{hôte}, ils ne sont -pas envoyés. - -La commande ci-dessous récupère @code{libreoffice} et @code{gimp} depuis -@var{hôte}, en supposant qu'ils y sont présents : - -@example -guix copy --from=@var{hôte} libreoffice gimp -@end example - -La connexion SSH est établie avec le client Guile-SSH, qui set compatible -avec OpenSSH : il honore @file{~/.ssh/known_hosts} et @file{~/.ssh/config} -et utilise l'agent SSH pour l'authentification. - -La clef utilisée pour signer les éléments qui sont envoyés doit être -acceptée par la machine distante. De même, la clef utilisée pour la machine -distante depuis laquelle vous récupérez des éléments doit être dans -@file{/etc/guix/acl} pour qu'ils soient acceptés par votre propre démon. -@xref{Invoquer guix archive}, pour plus d'informations sur -l'authentification des éléments du dépôt. - -La syntaxe générale est : - -@example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} -@end example - -Vous devez toujours spécifier l'une des options suivantes : - -@table @code -@item --to=@var{spec} -@itemx --from=@var{spec} -Spécifie l'hôte où envoyer ou d'où recevoir les éléments. @var{spec} doit -être une spécification SSH comme @code{example.org}, -@code{charlie@@example.org} ou @code{charlie@@example.org:2222}. -@end table - -L'option @var{items} peut être des noms de paquets, comme @code{gimp} ou des -éléments du dépôt comme @file{/gnu/store/@dots{}-idutils-4.6}. - -Lorsque vous spécifiez le nom d'un paquet à envoyer, il est d'abord -construit au besoin, sauf si l'option @option{--dry-run} est spécifiée. Les -options de construction communes sont supportées (@pxref{Options de construction communes}). - - -@node Invoquer guix container -@section Invoquer @command{guix container} -@cindex conteneur -@cindex @command{guix container} -@quotation Remarque -À la version @value{VERSION}, cet outil est toujours expérimental. -L'interface est sujette à changement radicaux dans le futur. -@end quotation - -Le but de @command{guix container} est de manipuler des processus qui -tournent dans un environnement séparé, connus sous le nom de « conteneur », -typiquement créés par les commandes @command{guix environment} -(@pxref{Invoquer guix environment}) et @command{guix system container} -(@pxref{Invoquer guix system}). - -La syntaxe générale est : - -@example -guix container @var{action} @var{options}@dots{} -@end example - -@var{action} spécifie les opérations à effectuer avec un conteneur, et -@var{options} spécifie les arguments spécifiques au contexte pour l'action. - -Les actions suivantes sont disponibles : - -@table @code -@item exec -Exécute une commande dans le contexte d'un conteneur lancé. - -La syntaxe est : - -@example -guix container exec @var{pid} @var{programme} @var{arguments}@dots{} -@end example - -@var{pid} spécifie le PID du conteneur lancé. @var{programme} spécifie le -nom du fichier exécutable dans le système de fichiers racine du conteneur. -@var{arguments} sont les options supplémentaires à passer à @var{programme}. - -La commande suivante lance un shell de connexion interactif dans un -conteneur Guix System, démarré par @command{guix system container} et dont -le PID est 9001 : - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Remarquez que @var{pid} ne peut pas être le processus parent d'un -conteneur. Ce doit être le PID 1 du conteneur ou l'un de ses processus -fils. - -@end table - -@node Invoquer guix weather -@section Invoquer @command{guix weather} - -Vous pouvez parfois grogner lorsque les substituts ne sont pas disponibles -et que vous devez construire les paquets vous-même (@pxref{Substituts}). La -commande @command{guix weather} rapporte la disponibilité des substituts sur -les serveurs spécifiés pour que vous sachiez si vous allez raller -aujourd'hui. Cela peut parfois être une information utile pour les -utilisateurs, mais elle est surtout utile pour les personnes qui font -tourner @command{guix publish} (@pxref{Invoquer guix publish}). - -@cindex statistiques sur les substituts -@cindex disponibilité des substituts -@cindex substituts, disponibilité -@cindex weather, disponibilité des substituts -Voici un exemple : - -@example -$ guix weather --substitute-urls=https://guix.example.org -calcul de 5,872 dérivations de paquets pour x86_64-linux… -recherche de 6,128 éléments du dépôt sur https://guix.example.org… -mise à jour de la liste des substituts depuis 'https://guix.example.org'... 100.0% -https://guix.example.org - 43.4% substituts disponibles (2,658 sur 6,128) - 7,032.5 Mo de fichiers nar (compressés) - 19,824.2 Mo sur le disque (décompressés) - 0.030 secondes par requêtes (182.9 secondes au total) - 33.5 requêtes par seconde - - 9.8% (342 sur 3,470) des éléments manquants sont dans la queue - 867 constructions dans la queue - x86_64-linux : 518 (59.7%) - i686-linux : 221 (25.5%) - aarch64-linux : 128 (14.8%) - vitesse de construction : 23.41 constructions par heure - x86_64-linux : 11.16 constructions par heure - i686-linux : 6.03 constructions par heure - aarch64-linux : 6.41 constructions par heure -@end example - -@cindex intégration continue, statistiques -Comme vous pouvez le voir, elle rapporte le pourcentage des paquets pour -lesquels des substituts sont disponibles sur le serveur — indépendamment du -fait que les substituts soient activés, et indépendamment du fait que la -clef de signature du serveur soit autorisée. Elle rapporte aussi la taille -des archives compressées (« nars ») fournies par le serveur, la taille des -éléments du dépôt correspondant dans le dépôt (en supposant que la -déduplication soit désactivée) et la vitesse du serveur. La deuxième partie -donne des statistiques sur l'intégration continue (CI), si le serveur le -supporte. En plus, avec l'option @option{--coverage}, @command{guix -weather} peut lister les substituts de paquets « importants » qui font -défaut sur le serveur (voir plus bas). - -Pour cela, @command{guix weather} récupère par HTTP(S) les métadonnées -(@dfn{narinfos}@ de tous les éléments du dépôts pertinents. Comme -@command{guix challenge}, il ignore les signatures de ces substituts, ce qui -n'est pas dangereux puisque la commande ne fait que récupérer des -statistiques et n'installe pas ces substituts. - -Entre autres choses, il est possible de demander des types de système -particuliers et des ensembles de paquets particuliers. Les options -disponibles sont listées plus bas. - -@table @code -@item --substitute-urls=@var{urls} -@var{urls} est la liste des URL des serveurs de substituts séparés par des -espaces. Lorsque cette option n'est pas renseignée, l'ensemble des serveurs -de substituts par défaut est utilisé. - -@item --system=@var{système} -@itemx -s @var{système} -Effectue des requêtes pour les substituts @var{système} — p.@: ex.@: -@code{aarch64-linux}. Cette option peut être répétée, auquel cas -@command{guix weather} demandera les substituts de plusieurs types de -systèmes. - -@item --manifest=@var{fichier} -Plutôt que de demander des substituts pour tous les paquets, demande -uniquement les paquets spécifiés dans @var{fichier}. @var{fichier} doit -contenir un @dfn{manifeste} comme avec l'option @code{-m} de @command{guix -package} (@pxref{Invoquer guix package}). - -@item --coverage[=@var{count}] -@itemx -c [@var{count}] -Rapporte la couverture des substituts pour les paquets : liste les paquets -avec au moins @var{count} autres paquets qui en dépendent (zéro par défaut) -pour lesquels il n'y a pas de substitut. Les paquets qui en dépendent ne -sont pas listés : si @var{b} dépend de @var{a} et que @var{a} n'a pas de -substitut, seul @var{a} est listé, même si @var{b} n'a habituellement pas de -substitut non plus. Le résultat ressemble à cela : - -@example -$ guix weather --substitute-urls=https://ci.guix.fr.info -c 10 -calcul de 8 983 dérivations de paquets pour x86_64-linux… -recherche de 9 343 éléments du dépôt sur https://ci.guix.fr.info… -mise à jour des substituts depuis « https://ci.guix.fr.info »… 100,0 % -https://ci.guix.fr.info - 64.7 % des substituts sont disponibles (6,047 sur 9,343) -@dots{} -2502 paquets ne sont pas sur « https://ci.guix.fr.info » pour « x86_64-linux », parmi lesquels : - 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 - -Ce que montre cet exemple est que @code{kcoreaddons} et probablement les 58 -paquets qui en dépendent n'ont pas de substituts sur @code{ci.guix.fr.info} ; -de même pour @code{qgpgme} et les 46 paquets qui en dépendent. - -Si vous êtes un développeur de Guix, ou si vous prenez soin de cette ferme -de construction, vous voudrez sans doute inspecter plus finement ces paquets -: ils peuvent simplement avoir échoué à la construction. -@end table - -@node Invoquer guix processes -@section Invoquer @command{guix processes} - -La commande @command{guix processes} peut être utile pour les développeurs -et les administrateurs systèmes, surtout sur des machines multi-utilisateurs -et sur les fermes de construction : elle liste les sessions actuelles (les -connexions au démon), ainsi que des informations sur les processus en -question@footnote{Les sessions distantes, lorsque @command{guix-daemon} est -démarré avec @option{--listen} en spécifiant un point d'entrée TCP, ne sont -@emph{pas} listées.}. Voici un exemple des informations qu'elle renvoie : - -@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 - -Dans cet exemple, on voit que @command{guix-daemon} a trois clients directs -: @command{guix environment}, @command{guix publish} et l'outil -d'intégration continue Cuirass ; leur identifiant de processus (PID) est -donné par le champ @code{ClientPID}. Le champ @code{SessionPID} fournit le -PID du sous-processus @command{guix-daemon} de cette session particulière. - -Les champs @code{LockHeld} montrent quels éléments du dépôt sont -actuellement verrouillés par cette session, ce qui correspond aux éléments -du dépôt qui sont en train d'être construits ou d'être substitués (le champ -@code{LockHeld} n'est pas montré si @command{guix processes} n'est pas lancé -en root). Enfin, en regardant le champ @code{ChildProcess}, on comprend que -ces trois constructions sont déchargées (@pxref{Réglages du délestage du démon}). - -La sortie est dans le format Recutils pour qu'on puisse utiliser la commande -@command{recsel} pour sélectionner les sessions qui nous intéressent -(@pxref{Selection Expressions,,, recutils, GNU recutils manual}). Par -exemple, la commande montre la ligne de commande et le PID du client qui -effectue la construction d'un paquet Perl : - -@example -$ sudo guix processes | \ - recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -@end example - - -@node Configuration système -@chapter Configuration système - -@cindex configuration du système -La distribution système Guix utilise un mécanisme de configuration du -système cohérent. On veut dire par là que tous les aspects de la -configuration globale du système — comme la disponibilité des services -système, des fuseaux horaires, des paramètres linguistiques, des comptes -utilisateurs — sont déclarés à un seul endroit. Une telle -@dfn{configuration système} peut être @dfn{instanciée}, c'est-à-dire entrer -en vigueur. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -L'un des avantages de placer toute la configuration du système sous le -contrôle de Guix est de permettre les mises à jour transactionnelles du -système ce qui rend possible le fait de revenir en arrière à une -instanciation précédent du système, si quelque chose se passait mal avec le -nouveau (@pxref{Fonctionnalités}). Un autre avantage est de rendre facile la -réplication de la même configuration sur plusieurs machines différentes ou à -différents moments dans le temps, sans avoir à recourir à des outils -d'administrations supplémentaires au-dessus des outils du système. - -Cette section décrit ce mécanisme. Tout d'abord nous nous concentrons sur -le point de vue de l'administrateur système en expliquant comment le système -est configuré et instancié. Ensuite nous montrons comment ce mécanisme peut -être étendu, par exemple pour supporter de nouveaux services systèmes. - -@menu -* Utiliser le système de configuration:: Personnaliser votre système - GNU@. -* Référence de système d'exploitation:: Détail sur la déclaration de - système d'exploitation. -* Systèmes de fichiers:: Configurer les montages de systèmes de - fichiers. -* Périphériques mappés:: Gestion des périphériques de bloc. -* Comptes utilisateurs:: Spécifier des comptes utilisateurs. -* Disposition du clavier:: La manière dont le système interprète les - touches du clavier. -* Régionalisation:: Paramétrer la langue et les conventions - culturelles. -* Services:: Spécifier les services du système. -* Programmes setuid:: Programmes tournant avec les privilèges root. -* Certificats X.509:: Authentifier les serveurs HTTPS@. -* Name Service Switch:: Configurer le « name service switch » de la - libc. -* Disque de RAM initial:: Démarrage de Linux-Libre. -* Configuration du chargeur d'amorçage:: Configurer le chargeur - d'amorçage. -* Invoquer guix system:: Instantier une configuration du système. -* Lancer Guix dans une VM:: Comment lancer Guix dans une machine virtuelle. -* Définir des services:: Ajouter de nouvelles définitions de services. -@end menu - -@node Utiliser le système de configuration -@section Utiliser le système de configuration - -Le système d'exploitation est configuré en fournissant une déclaration -@code{operating-system} dans un fichier qui peut être passé à la command -@command{guix system} (@pxref{Invoquer guix system}). Une configuration -simple, avec les services systèmes par défaut, le noyau Linux-Libre par -défaut, un disque de RAM initial et un chargeur d'amorçage ressemble à ceci -: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -Cet exemple devrait se comprendre de lui-même. Certains champs définis -ci-dessus, comme @code{host-name} et @code{bootloader} sont obligatoires. -D'autres comme @code{packages} et @code{services} peuvent être omis auquel -cas ils ont une valeur par défaut. - -Ci-dessous nous discutons des effets de certains des champs les plus -importants (@pxref{Référence de système d'exploitation}, pour des détails sur tous -les champs disponibles) et comment @dfn{instancier} le système -d'exploitation avec @command{guix system}. - -@unnumberedsubsec Bootloader - -@cindex ancien système de démarrage, sur les machines Intel -@cindex démarrage BIOS, sur les machines Intel -@cindex démarrage UEFI -@cindex démarrage EFI -Le champ @code{bootloader} décrit la méthode qui sera utilisée pour démarrer -votre système. Les machines basées sur les processeurs Intel peuvent -démarrer dans l'ancien mode BIOS, comme dans l'exemple au-dessus. -Cependant, les machines plus récentes s'appuient sur l'UEFI (@dfn{Unified -Extensible Firmware Interface}) pour démarrer. Dans ce cas, le champ -@code{bootloader} devrait contenir quelque chose comme cela : - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -@xref{Configuration du chargeur d'amorçage}, pour plus d'informations sur les options de -configuration disponibles. - -@unnumberedsubsec Paquets visibles sur tout le système - -@vindex %base-packages -Le champ @code{packages} liste les paquets qui seront visibles sur tout le -système, pour tous les comptes utilisateurs — c.-à-d.@: dans la variable -d'environnement @code{PATH} de tous les utilisateurs — en plus des profils -utilisateurs (@pxref{Invoquer guix package}). La variable -@var{%base-packages} fournit tous les outils qu'on pourrait attendre pour -les taches de base de l'administrateur et de l'utilisateur — dont les GNU -Core Utilities, les GNU Networking Utilities, l'éditeur de texte léger GNU -Zile, @command{find}, @command{grep}, etc. L'exemple au-dessus ajoute -GNU@tie{}Screen à ces paquets, récupéré depuis le module @code{(gnu packages -screen)} (@pxref{Modules de paquets}). Vous pouvez utiliser la syntaxe -@code{(list paquet sortie)} pour ajouter une sortie spécifique d'un paquet : - -@lisp -(use-modules (gnu packages)) -(use-modules (gnu packages dns)) - -(operating-system - ;; ... - (packages (cons (list bind "utils") - %base-packages))) -@end lisp - -@findex specification->package -Se référer aux paquets par le nom de leur variable, comme @code{bind} -ci-dessus, a l'avantage d'être sans ambiguïté ; cela permet aussi de se -rendre rapidement compte de coquilles quand on a des « variables non liées -». L'inconvénient est qu'on a besoin de savoir dans quel module est défini -le paquet, et de modifier la ligne @code{use-package-modules} en -conséquence. Pour éviter cela, on peut utiliser la procédure -@code{specification->package} du module @code{(gnu packages)}, qui renvoie -le meilleur paquet pour un nom donné ou un nom et une version : - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec Services systèmes - -@cindex services -@vindex %base-services -Le champ @code{services} liste les @dfn{services système} à rendre -disponible lorsque le système démarre (@pxref{Services}). La déclaration -@code{operating-system} au-dessus spécifie que, en plus des services de -base, on veut que le démon ssh OpenSSH écoute sur le port 2222 -(@pxref{Services réseau, @code{openssh-service-type}}). Sous le capot, -@code{openssh-service-type} s'arrange pour que @code{sshd} soit lancé avec -les bonnes options de la ligne de commande, éventuellement en générant des -fichiers de configuration (@pxref{Définir des services}). - -@cindex personnalisation des services -@findex modify-services -Parfois, plutôt que d'utiliser les services de base tels-quels, on peut -vouloir les personnaliser. Pour cela, utilisez @code{modify-services} -(@pxref{Référence de service, @code{modify-services}}) pour modifier la liste. - -Par exemple, supposons que vous souhaitiez modifier @code{guix-daemon} et -Mingetty (l'écran de connexion en console) dans la liste -@var{%base-services} (@pxref{Services de base, @code{%base-services}}). Pour -cela, vous pouvez écrire ce qui suit dans votre déclaration de système -d'exploitation : - -@lisp -(define %my-services - ;; Ma propre liste de services. - (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 - -Cela modifie la configuration — c.-à-d.@: les paramètres du service — de -l'instance de @code{guix-service-type}, et de toutes les instances de -@code{mingetty-service-type} dans la liste @var{%base-services}. Remarquez -comment on fait cela : d'abord, on s'arrange pour que la configuration de -départ soit liée à l'identifiant @code{config} dans @var{body} puis on écrit -@var{body} pour qu'il s'évalue en la configuration désirée. En particulier, -remarquez comment on utilise @code{inherit} pour créer une nouvelle -configuration qui a les même valeurs que l'ancienne configuration, avec -seulement quelques modifications. - -@cindex chiffrement du disque -La configuration pour une utilisation de « bureau » typique, avec une -partition racine chiffrée, le serveur d'affichage X11, GNOME et Xfce (les -utilisateurs peuvent choisir l'environnement de bureau sur l'écran de -connexion en appuyant sur @kbd{F1}), la gestion du réseau, la gestion de -l'énergie, et bien plus, ressemblerait à ceci : - -@lisp -@include os-config-desktop.texi -@end lisp - -Un système graphique avec un choix de gestionnaires de fenêtres légers -plutôt que des environnement de bureaux complets ressemblerait à cela : - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -Cet exemple se réfère au système de fichier @file{/boot/efi} par son UUID, -@code{1234-ABCD}. Remplacez cet UUID par le bon UUID de votre système, -renvoyé par la commande @command{blkid}. - -@xref{Services de bureaux}, pour la liste exacte des services fournis par -@var{%desktop-services}. @xref{Certificats X.509}, pour des informations -sur le paquet @code{nss-certs} utilisé ici. - -Encore une fois, @var{%desktop-services} n'est qu'une liste d'objets -service. Si vous voulez en supprimer des services, vous pouvez le faire -avec des procédures pour les listes (@pxref{SRFI-1 Filtering and -Partitioning,,, guile, GNU Guile Reference Manual}). Par exemple, -l'expression suivante renvoie une liste qui contient tous les services dans -@var{%desktop-services} sauf le service Avahi : - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Instancier le système - -En supposant que la déclaration @code{operating-system} est stockée dans le -fichier @file{my-system-config.scm}, la commande @command{guix system -reconfigure my-system-config.scm} instancie cette configuration et en fait -l'entrée par défaut dans GRUB (@pxref{Invoquer guix system}). - -Pour changer la configuration du système, on met normalement à jour ce -fichier et on relance @command{guix system reconfigure}. On ne devrait -jamais avoir à modifier de fichiers dans @file{/etc} ou à lancer des -commandes qui modifient l'état du système comme @command{useradd} ou -@command{grub-install}. En fait, vous devez les éviter parce que non -seulement ça annulerait vos garanties, mais ça empêcherait aussi de revenir -à des versions précédents du système, si vous en avez besoin. - -@cindex revenir en arrière dans la configuration du système -En parlant de revenir en arrière, à chaque fois que vous lancez -@command{guix system reconfigure}, une nouvelle @dfn{génération} du système -est crée — sans modifier ou supprimer les générations précédentes. Les -anciennes générations du système ont une entrée dans le menu du chargeur -d'amorçage, ce qui vous permet de démarrer dessus au cas où quelque chose se -serait mal passé avec la dernière génération. C'est rassurant, non ? La -commande @command{guix system list-generations} liste les générations du -système disponibles sur le disque. Il est possible de revenir à une -ancienne génération via les commandes @command{guix system roll-back} et -@command{guix system switch-generation}. - -Bien que la commande @command{guix system reconfigure} ne modifiera pas les -générations précédentes, vous devez faire attention lorsque votre génération -actuelle n'est pas la dernière (p.@: ex.@: après avoir invoqué @command{guix -system roll-back}), puisque l'opération pourrait remplacer une génération -suivante (@pxref{Invoquer guix system}). - -@unnumberedsubsec L'interface de programmation - -Au niveau Scheme, la grosse déclaration @code{operating-system} est -instanciée avec la procédure monadique suivante (@pxref{La monade du dépôt}) : - -@deffn {Procédure monadique} operating-system-derivation os -Renvoie une dérivation qui construit @var{os}, un objet -@code{operating-system} (@pxref{Dérivations}). - -La sortie de la dérivation est un répertoire qui se réfère à tous les -paquets et d'autres fichiers supports requis pour instancier @var{os}. -@end deffn - -Cette procédure est fournie par le module @code{(gnu system)}. Avec -@code{(gnu services)} (@pxref{Services}), ce module contient les entrailles -du système Guix. Ouvrez-le un jour ! - - -@node Référence de système d'exploitation -@section Référence de @code{operating-system} - -Cette section résume toutes les options disponibles dans les déclarations -@code{operating-system} (@pxref{Utiliser le système de configuration}). - -@deftp {Type de données} operating-system -C'est le type de données représentant une configuration d'un système -d'exploitation. On veut dire par là toute la configuration globale du -système, mais pas la configuration par utilisateur (@pxref{Utiliser le système de configuration}). - -@table @asis -@item @code{kernel} (par défaut : @var{linux-libre}) -L'objet paquet d'un noyau de système d'exploitation à -utiliser@footnote{Actuellement seul le noyau Linux-libre est supporté. Dans -le futur, il sera possible d'utiliser GNU@tie{}Hurd.}. - -@item @code{kernel-arguments} (par défaut : @code{'()}) -Liste de chaînes ou de gexps représentant des arguments supplémentaires à -passer sur la ligne de commande du noyau — p.@: ex.@: -@code{("console=ttyS0")}. - -@item @code{bootloader} -L'objet de configuration du chargeur d'amorçage. @xref{Configuration du chargeur d'amorçage}. - -@item @code{label} -This is the label (a string) as it appears in the bootloader's menu entry. -The default label includes the kernel name and version. - -@item @code{keyboard-layout} (par défaut : @code{#f}) -Ce champ spécifie la disposition du clavier à utiliser dans la console. Il -peut être soit @code{#f}, auquel cas la disposition par défaut est utilisée -(habituellement anglais américain), ou un enregistrement -@code{}. - -Cette disposition du clavier est effective dès que le noyau démarre. Par -exemple, c'est la disposition du clavier effective lorsque vous saisissez la -phrase de passe de votre système de fichier racine sur une partition -utilisant @code{luks-device-mapping} (@pxref{Périphériques mappés}). - -@quotation Remarque -Cela ne spécifie @emph{pas} la disposition clavier utilisée par le chargeur -d'amorçage, ni celle utilisée par le serveur d'affichage graphique. -@xref{Configuration du chargeur d'amorçage}, pour plus d'information sur la manière de -spécifier la disposition du clavier pour le chargeur d'amorçage. @xref{Système de fenêtrage X}, pour plus d'informations sur la manière de spécifier la disposition -du clavier utilisée par le système de fenêtrage X. -@end quotation - -@item @code{initrd-modules} (par défaut : @code{%base-initrd-modules}) -@cindex initrd -@cindex disque de RAM initial -La liste des modules du noyau linux requis dans l'image disque de RAM -initiale. @xref{Disque de RAM initial}. - -@item @code{initrd} (par défaut : @code{base-initrd}) -Une procédure qui renvoie un disque de RAM initial pour le noyau Linux. Ce -champ est fournit pour pouvoir personnaliser son système à bas-niveau et -n'est que rarement utile dans le cas général. @xref{Disque de RAM initial}. - -@item @code{firmware} (par défaut : @var{%base-firmware}) -@cindex firmware -Liste les paquets de microgiciels chargeables pour le noyau de système -d'exploitation. - -La valeur par défaut contient les microgiciels requis pour les périphériques -WiFi Atheros et Broadcom (modules @code{ath9k} et @code{b43-open} de -Linux-libre, respectivement). @xref{Considérations matérielles}, pour plus -d'info sur les périphériques supportés. - -@item @code{host-name} -Le nom d'hôte. - -@item @code{hosts-file} -@cindex fichier hosts -Un objet simili-fichier (@pxref{G-Expressions, file-like objects}) à -utiliser comme @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C -Library Reference Manual}). La valeur par défaut est un fichier avec des -entrées pour @code{localhost} et @var{host-name}. - -@item @code{mapped-devices} (par défaut : @code{'()}) -Une liste de périphériques mappés. @xref{Périphériques mappés}. - -@item @code{file-systems} -Une liste de systèmes de fichiers. @xref{Systèmes de fichiers}. - -@item @code{swap-devices} (par défaut : @code{'()}) -@cindex espaces d'échange -Une liste de chaînes identifiant les périphériques ou les fichiers utilisé -pour « l'espace d'échange » (@pxref{Memory Concepts,,, libc, The GNU C -Library Reference Manual}). Par exemple, @code{'("/dev/sda3")} ou -@code{'("/swapfile")}. Il est possible de spécifier un fichier d'échange -sur un périphérique mappé, tant que le périphérique nécessaire et le système -de fichiers sont aussi spécifiés. @xref{Périphériques mappés} et @ref{Systèmes de fichiers}. - -@item @code{users} (par défaut : @code{%base-user-accounts}) -@itemx @code{groups} (par défaut : @var{%base-groups}) -Liste les comptes utilisateurs et les groupes. @xref{Comptes utilisateurs}. - -Si la liste @code{users} n'a pas de compte lié à l'UID@tie{}0, un compte « -root » avec l'UID@tie{}0 est automatiquement ajouté. - -@item @code{skeletons} (par défaut : @code{(default-skeletons)}) -Une liste de couples composés d'un nom de fichier cible et d'un objet -simili-fichier (@pxref{G-Expressions, file-like objects}). Ce sont les -fichiers squelettes qui seront ajoutés au répertoire personnel des comptes -utilisateurs nouvellement créés. - -Par exemple, un valeur valide ressemblerait à cela : - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hello\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (par défaut : @var{%default-issue}) -Une chaîne qui dénote le contenu du fichier @file{/etc/issue} qui est -affiché lorsqu'un utilisateur se connecte sur la console. - -@item @code{packages} (par défaut : @var{%base-packages}) -L'ensemble des paquets installés dans le profil global, qui est accessible à -partir de @file{/run/current-system/profile}. - -L'ensemble par défaut contient les utilitaires de base et c'est une bonne -pratique d'installer les utilitaires non essentiels dans les profils -utilisateurs (@pxref{Invoquer guix package}). - -@item @code{timezone} -Une chaîne identifiant un fuseau horaire — p.@: ex.@: @code{"Europe/Paris"}. - -Vous pouvez lancer la commande @command{tzselect} pour trouver le fuseau -horaire correspondant à votre région. Si vous choisissez un nom de fuseau -horaire invalide, @command{guix system} échouera. - -@item @code{locale} (par défaut : @code{"en_US.utf8"}) -Le nom du paramètre régional par défaut (@pxref{Locale Names,,, libc, The -GNU C Library Reference Manual}). @xref{Régionalisation}, pour plus d'informations. - -@item @code{locale-definitions} (par défaut : @var{%default-locale-definitions}) -La liste des définitions de locales à compiler et qui devraient être -utilisées à l'exécution. @xref{Régionalisation}. - -@item @code{locale-libcs} (par défaut : @code{(list @var{glibc})}) -La liste des paquets GNU@tie{}libc dont les données des paramètres -linguistiques sont utilisées pour construire les définitions des paramètres -linguistiques. @xref{Régionalisation}, pour des considérations sur la compatibilité -qui justifient cette option. - -@item @code{name-service-switch} (par défaut : @var{%default-nss}) -La configuration de NSS de la libc (name service switch) — un objet -@code{}. @xref{Name Service Switch}, pour des détails. - -@item @code{services} (par défaut : @var{%base-services}) -Une liste d'objets services qui dénotent les services du système. -@xref{Services}. - -@cindex services essentiels -@item @code{essential-services} (par défaut : …) -La liste des « services essentiels » — c.-à-d.@: les services comme des -instance de @code{system-service-type} et @code{host-name-service-type} -(@pxref{Référence de service}), qui sont dérivés de la définition du système -d'exploitation lui-même. En tant qu'utilisateur vous ne devriez -@emph{jamais} toucher à ce champ. - -@item @code{pam-services} (par défaut : @code{(base-pam-services)}) -@cindex PAM -@cindex pluggable authentication modules -@c FIXME: Add xref to PAM services section. -Services PAM (@dfn{pluggable authentication module}) Linux. - -@item @code{setuid-programs} (par défaut : @var{%setuid-programs}) -Liste de G-expressions qui s'évaluent en chaînes de caractères qui dénotent -les programmes setuid. @xref{Programmes setuid}. - -@item @code{sudoers-file} (par défaut : @var{%sudoers-specification}) -@cindex fichier sudoers -Le contenu du fichier @file{/etc/sudoers} comme un objet simili-fichier -(@pxref{G-Expressions, @code{local-file} et @code{plain-file}}). - -Ce fichier spécifier quels utilisateurs peuvent utiliser la commande -@command{sudo}, ce qu'ils ont le droit de faire, et quels privilèges ils -peuvent gagner. La valeur par défaut est que seul @code{root} et les -membres du groupe @code{wheel} peuvent utiliser @code{sudo}. - -@end table - -@deffn {Scheme Syntax} this-operating-system -When used in the @emph{lexical scope} of an operating system field -definition, this identifier resolves to the operating system being defined. - -The example below shows how to refer to the operating system being defined -in the definition of the @code{label} field: - -@example -(use-modules (gnu) (guix)) - -(operating-system - ;; ... - (label (package-full-name - (operating-system-kernel this-operating-system)))) -@end example - -It is an error to refer to @code{this-operating-system} outside an operating -system definition. -@end deffn - -@end deftp - -@node Systèmes de fichiers -@section Systèmes de fichiers - -La liste des systèmes de fichiers à monter est spécifiée dans le champ -@code{file-systems} de la déclaration de système d'exploitation -(@pxref{Utiliser le système de configuration}). Chaque système de fichier est -déclaré avec la forme @code{file-system}, comme ceci : - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -Comme d'habitude, certains de ces champs sont obligatoire — comme le montre -l'exemple au-dessus — alors que d'autres peuvent être omis. Ils sont -décrits plus bas. - -@deftp {Type de données} file-system -Les objets de ce type représentent des systèmes de fichiers à monter. Ils -contiennent les membres suivants : - -@table @asis -@item @code{type} -C'est une chaîne de caractères spécifiant le type du système de fichier — -p.@: ex.@: @code{"ext4"}. - -@item @code{mount-point} -Désigne l'emplacement où le système de fichier sera monté. - -@item @code{device} -Ce champ nomme le système de fichier « source ». il peut être l'une de ces -trois choses : une étiquette de système de fichiers, un UUID de système de -fichier ou le nom d'un nœud dans @file{/dev}. Les étiquettes et les UUID -offrent une manière de se référer à des systèmes de fichiers sans avoir à -coder en dur le nom de périphérique@footnote{Remarquez que, s'il est tentant -d'utiliser @file{/dev/disk/by-uuid} et autres chemins similaires pour -obtenir le même résultat, ce n'est pas recommandé : ces nœuds de -périphériques spéciaux sont créés par le démon udev et peuvent ne pas être -disponibles au moment de monter le périphérique.}. - -@findex file-system-label -Les étiquettes de systèmes de fichiers sont crées avec la procédure -@code{file-system-label}, les UUID avec @code{uuid} et les nœuds de -@file{/dev} sont de simples chaînes de caractères. Voici un exemple d'un -système de fichiers référencé par son étiquette, donnée par la commande -@command{e2label} : - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "my-home"))) -@end example - -@findex uuid -Les UUID sont convertis à partir de leur représentation en chaîne de -caractères (montrée par la command @command{tune2fs -l}) en utilisant la -forme @code{uuid}@footnote{La forme @code{uuid} s'attend à des UUID sur 16 -octets définis dans la @uref{https://tools.ietf.org/html/rfc4122, -RFC@tie{}4122}. C'est la forme des UUID utilisées par la famille de -systèmes de fichiers ext2 et d'autres, mais ce n'est pas le même type d'UUID -que ceux qui se trouvent sur les systèmes de fichiers FAT par exemple}, -comme ceci : - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -Lorsque la source d'un système de fichiers est un périphérique mappé -(@pxref{Périphériques mappés}), sont champ @code{device} @emph{doit} se référer au -nom du périphérique mappé — p.@: ex.@: @file{"/dev/mapper/root-partition"}. -Cela est requis pour que le système sache que monter ce système de fichier -dépend de la présence du périphérique mappé correspondant. - -@item @code{flags} (par défaut : @code{'()}) -C'est une liste de symboles qui dénotent des drapeaux de montage. Les -drapeaux reconnus sont @code{read-only}, @code{bind-mount}, @code{no-dev} -(interdit l'accès aux fichiers spéciaux), @code{no-suid} (ignore les bits -setuid et setgid) et @code{no-exec} (interdit l'exécution de programmes). - -@item @code{options} (par défaut : @code{#f}) -C'est soit @code{#f} soit une chaîne de caractères dénotant des options de -montage. - -@item @code{mount?} (par défaut : @code{#t}) -Cette valeur indique s'il faut monter automatiquement le système de fichier -au démarrage du système. Lorsque la valeur est @code{#f}, le système de -fichier reçoit une entrée dans @file{/etc/fstab} (lue par la commande -@command{mount}) mais n'est pas monté automatiquement. - -@item @code{needed-for-boot?} (par défaut : @code{#f}) -Cette valeur booléenne indique si le système de fichier est nécessaire au -démarrage. Si c'est vrai alors le système de fichier est monté au -chargement du disque de RAM initial. C'est toujours le cas par exemple du -système de fichiers racine. - -@item @code{check?} (par défaut : @code{#t}) -Cette valeur booléenne indique si le système de fichier doit être vérifié -avant de le monter. - -@item @code{create-mount-point?} (par défaut : @code{#f}) -Lorsque cette valeur est vraie, le point de montage est créé s'il n'existe -pas déjà. - -@item @code{dependencies} (par défaut : @code{'()}) -C'est une liste d'objets @code{} ou @code{} qui -représentent les systèmes de fichiers qui doivent être montés ou les -périphériques mappés qui doivent être ouverts avant (et monté ou fermés -après) celui-ci. - -Par exemple, considérons une hiérarchie de montage : @file{/sys/fs/cgroup} -est une dépendance de @file{/sys/fs/cgroup/cpu} et -@file{/sys/fs/cgroup/memory}. - -Un autre exemple est un système de fichier qui dépend d'un périphérique -mappé, par exemple pour une partition chiffrée (@pxref{Périphériques mappés}). -@end table -@end deftp - -Le module @code{(gnu system file-systems)} exporte les variables utiles -suivantes. - -@defvr {Variable Scheme} %base-file-systems -Ce sont les systèmes de fichiers essentiels qui sont requis sur les systèmes -normaux, comme @var{%pseudo-terminal-file-system} et @var{%immutable-store} -(voir plus bas). Les déclarations de systèmes d'exploitation devraient au -moins les contenir. -@end defvr - -@defvr {Variable Scheme} %pseudo-terminal-file-system -C'est le système de fichier monté sur @file{/dev/pts}. Il supporte les -@dfn{pseudo-terminaux} créés via @code{openpty} et les fonctions similaires -(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}). Les -pseudo-terminaux sont utilisés par les émulateurs de terminaux comme -@command{xterm}. -@end defvr - -@defvr {Variable Scheme} %shared-memory-file-system -Ce système de fichier est monté dans @file{/dev/shm} et est utilisé pour le -partage de mémoire entre processus (@pxref{Memory-mapped I/O, -@code{shm_open},, libc, The GNU C Library Reference Manual}). -@end defvr - -@defvr {Variable Scheme} %immutable-store -Ce système de fichiers effectue un « montage lié » en lecture-seule de -@file{/gnu/store}, ce qui en fait un répertoire en lecture-seule pour tous -les utilisateurs dont @code{root}. Cela évite que des logiciels qui -tournent en @code{root} ou des administrateurs systèmes ne modifient -accidentellement le dépôt. - -Le démon lui-même est toujours capable d'écrire dans le dépôt : il est -remonté en lecture-écriture dans son propre « espace de nom ». -@end defvr - -@defvr {Variable Scheme} %binary-format-file-system -Le système de fichiers @code{binfmt_misc}, qui permet de gérer n'importe -quel type de fichiers exécutables à déléguer en espace utilisateur. Cela -demande que le module du noyau @code{binfmt.ko} soit chargé. -@end defvr - -@defvr {Variable Scheme} %fuse-control-file-system -Le système de fichiers @code{fusectl}, qui permet à des utilisateurs non -privilégiés de monter et de démonter des systèmes de fichiers FUSE en espace -utilisateur. Cela requiert que le module du noyau @code{fuse.ko} soit -chargé. -@end defvr - -@node Périphériques mappés -@section Périphériques mappés - -@cindex mappage de périphériques -@cindex périphériques mappés -Le noyau Linux a une notion de @dfn{mappage de périphériques} : un -périphérique bloc, comme une partition sur un disque dur, peut être -@dfn{mappé} sur un autre périphérique, typiquement dans @code{/dev/mapper}, -avec des calculs supplémentaires sur les données qui naviguent entre les -deux@footnote{Remarquez que le Hurd ne fait pas de différence entre le -concept de « périphérique mappé » et celle d'un système de fichiers : les -deux correspondent à la @emph{traduction} des opérations d'entrée-sortie -faites sur un fichier en des opérations sur ce qui le contient. Ainsi, le -Hurd implémente les périphériques mappés, comme les systèmes de fichiers, -avec le mécanisme des @dfn{traducteurs} générique (@pxref{Translators,,, -hurd, The GNU Hurd Reference Manual}).}. Un exemple typique est le mappage -de périphériques chiffrés : toutes les écritures sont sur le périphérique -mappé sont chiffrées, toutes les lectures déchiffrées, de manière -transparente. Guix étend cette notion en considérant que tout périphérique -ou ensemble de périphériques qui sont @dfn{transformés} d'une certaine -manière créent un nouveau périphérique ; par exemple, les périphériques RAID -sont obtenus en @dfn{assemblant} plusieurs autres périphériques, comme des -disque ou des partitions, en un nouveau périphérique en tant qu'unique -partition. Un autre exemple, qui n'est pas encore disponible, sont les -volumes logiques LVM. - -Les périphériques mappés sont déclarés avec la forme @code{mapped-device}, -définie comme suit ; par exemple, voir ci-dessous. - -@deftp {Type de données} mapped-device -Les objets de ce type représentent des mappages de périphériques qui seront -effectués au démarrage du système. - -@table @code -@item source -C'est soit une chaîne qui spécifie le nom d'un périphérique bloc à mapper, -comme @code{"/dev/sda3"}, soit une liste de plusieurs périphériques à -assembler pour en créer un nouveau. - -@item target -Cette chaîne spécifie le nom du périphérique mappé qui en résulte. Pour les -mappeurs noyaux comme les périphériques chiffrés de type -@code{luks-device-mapping}, spécifier @code{"ma-partition"} crée le -périphérique @code{"/dev/mapper/ma-partition"}. Pour les périphériques RAID -de type @code{raid-device-mapping}, il faut donner le nom complet comme -@code{"/dev/md0"}. - -@item type -Ce doit être un objets @code{mapped-device-kind}, qui spécifie comment -@var{source} est mappés sur @var{target}. -@end table -@end deftp - -@defvr {Variable Scheme} luks-device-mapping -Cela définie les périphériques blocs chiffrés en LUKS avec -@command{cryptsetup} du paquet du même nom. Elle s'appuie sur le module du -noyau Linux @code{dm-crypt}. -@end defvr - -@defvr {Variable Scheme} raid-device-mapping -Cela définie un périphérique RAID qui est assemblé avec la commande -@code{mdadm} du paquet du même nom. Elle nécessite un module noyau Linux -approprié pour le niveau RAID chargé, comme @code{raid456} pour RAID-4, -RAID-5 et RAID-6 ou @code{raid10} pour RAID-10. -@end defvr - -@cindex chiffrement du disque -@cindex LUKS -L'exemple suivant spécifie un mappage de @file{/dev/sda3} vers -@file{/dev/mapper/home} avec LUKS — -@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, un -mécanisme standard pour chiffrer les disques. Le périphérique -@file{/dev/mapper/home} peut ensuite être utilisé comme @code{device} d'une -déclaration @code{file-system} (@pxref{Systèmes de fichiers}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -Autrement, pour devenir indépendant du numéro de périphérique, on peut -obtenir l'UUID LUKS (@dfn{l'identifiant unique}) du périphérique source avec -une commande comme : - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -et l'utiliser ainsi : - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex chiffrement de l'espace d'échange -Il est aussi désirable de chiffrer l'espace d'échange, puisque l'espace -d'échange peut contenir des données sensibles. Une manière de faire cela -est d'utiliser un fichier d'échange dans un système de fichiers sur un -périphérique mappé avec un chiffrement LUKS. De cette manière, le fichier -d'échange est chiffré parce que tout le périphérique est chiffré. -@xref{Préparer l'installation,,Disk Partitioning}, pour un exemple. - -Un périphérique RAID formé des partitions @file{/dev/sda1} et -@file{/dev/sdb1} peut être déclaré ainsi : - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -Le périphérique @file{/dev/md0} peut ensuite être utilisé comme -@code{device} d'une déclaration @code{file-system} (@pxref{Systèmes de fichiers}). -Remarquez que le niveau de RAID n'a pas besoin d'être donné ; il est choisi -pendant la création initiale du périphérique RAID et est ensuite déterminé -automatiquement. - - -@node Comptes utilisateurs -@section Comptes utilisateurs - -@cindex utilisateurs -@cindex comptes -@cindex comptes utilisateurs -Les comptes utilisateurs et les groupes sont gérés entièrement par la -déclaration @code{operating-system}. Ils sont spécifiés avec les formes -@code{user-account} et @code{user-group} : - -@example -(user-account - (name "alice") - (group "users") - (supplementary-groups '("wheel" ;permet d'utiliser sudo, etc. - "audio" ;carte son - "video" ;périphériques réseaux comme les webcams - "cdrom")) ;le bon vieux CD-ROM - (comment "Bob's sister") - (home-directory "/home/alice")) -@end example - -Lors du démarrage ou à la fin de @command{guix system reconfigure}, le -système s'assure que seuls les comptes utilisateurs et les groupes spécifiés -dans la déclaration @code{operating-system} existent, et avec les propriétés -spécifiées. Ainsi, les modifications ou les créations de comptes ou de -groupes effectuées directement en invoquant des commandes comme -@command{useradd} sont perdue à la reconfiguration ou au redémarrage. Cela -permet de s'assurer que le système reste exactement tel que déclaré. - -@deftp {Type de données} user-account -Les objets de se type représentent les comptes utilisateurs. Les membres -suivants peuvent être spécifiés : - -@table @asis -@item @code{name} -Le nom du compte utilisateur. - -@item @code{group} -@cindex groupes -C'est le nom (une chaîne) ou un identifiant (un nombre) du groupe -utilisateur auquel ce compte appartient. - -@item @code{supplementary-groups} (par défaut : @code{'()}) -Éventuellement, cela peut être définie comme une liste de noms de groupes -auxquels ce compte appartient. - -@item @code{uid} (par défaut : @code{#f}) -C'est l'ID utilisateur de ce compte (un nombre) ou @code{#f}. Dans ce -dernier cas, le nombre est choisi automatiquement par le système à la -création du compte. - -@item @code{comment} (par défaut : @code{""}) -Un commentaire à propos du compte, comme le nom complet de l'utilisateur. - -@item @code{home-directory} -C'est le nom du répertoire personnel du compte. - -@item @code{create-home-directory?} (par défaut : @code{#t}) -Indique si le répertoire personnel du compte devrait être créé s'il n'existe -pas déjà. - -@item @code{shell} (par défaut : Bash) -C'est une G-expression qui dénote un nom de fichier d'un programme utilisé -comme shell (@pxref{G-Expressions}). - -@item @code{system?} (par défaut : @code{#f}) -C'est une valeur booléenne qui indique si le compte est un compte « système -». Les comptes systèmes sont parfois traités à part ; par exemple, les -gestionnaires de connexion graphiques ne les liste pas. - -@anchor{user-account-password} -@cindex mot de passe, pour les comptes utilisateurs -@item @code{password} (par défaut : @code{#f}) -Vous laisseriez normalement ce champ à @code{#f} et initialiseriez les mots -de passe utilisateurs en tant que @code{root} avec la commande -@command{passwd}, puis laisseriez l'utilisateur le changer avec -@command{passwd}. Les mots de passes définis avec @command{passwd} sont -bien sûr préservés après redémarrage et reconfiguration. - -Si vous voulez @emph{vraiment} définir un mot de passe pour un compte, alors -ce champ doit contenir le mot de passe chiffré, comme une chaîne de -caractère. Vous pouvez utiliser la procédure @code{crypt} pour cela : - -@example -(user-account - (name "charlie") - (group "users") - - ;; Spécifie un mot de passe initial hashé avec sha512. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Remarque -Le hash de ce mot de passe initial sera disponible dans un fichier dans -@file{/gnu/store}, lisible par tous les utilisateurs, donc cette méthode est -à utiliser avec soin. -@end quotation - -@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, pour -plus d'information sur le chiffrement des mots de passe et -@ref{Encryption,,, guile, GNU Guile Reference Manual}, pour des informations -sur la procédure @code{crypt} de Guile. - -@end table -@end deftp - -@cindex groupes -Les déclarations de groupes sont encore plus simple : - -@example -(user-group (name "students")) -@end example - -@deftp {Type de données} user-group -C'est le type pour, hé bien, les comptes utilisateurs. Il n'y a que -quelques champs : - -@table @asis -@item @code{name} -Le nom du groupe. - -@item @code{id} (par défaut : @code{#f}) -L'identifiant du groupe (un nombre). S'il est @code{#f}, un nouveau nombre -est alloué automatiquement lorsque le groupe est créé. - -@item @code{system?} (par défaut : @code{#f}) -Cette valeur booléenne indique si le groupe est un groupe « système ». les -groupes systèmes ont un numéro d'ID bas. - -@item @code{password} (par défaut : @code{#f}) -Quoi, les groupes utilisateurs peuvent avoir des mots de passe ? On dirait -bien. À moins que la valeur ne soit @code{#f}, ce champ spécifie le mot de -passe du groupe. - -@end table -@end deftp - -Par simplicité, une variable liste les groupes utilisateurs de base auxquels -on pourrait s'attendre : - -@defvr {Variable Scheme} %base-groups -C'est la liste des groupes utilisateur de base que les utilisateurs et les -paquets s'attendent à trouver sur le système. Cela comprend des groupes -comme « root », « wheel » et « users », ainsi que des groupes utilisés pour -contrôler l'accès à certains périphériques, comme « audio », « disk » et « -cdrom ». -@end defvr - -@defvr {Variable Scheme} %base-user-accounts -C'est la liste des compte du système de base que les programmes peuvent -s'attendre à trouver sur un système GNU/Linux, comme le compte « nobody ». - -Remarquez que le compte « root » n'est pas défini ici. C'est un cas -particulier et il est automatiquement ajouté qu'il soit spécifié ou non. -@end defvr - -@node Disposition du clavier -@section Disposition du clavier - -@cindex disposition du clavier -@cindex disposition clavier -Pour spécifier ce que fait chaque touche de votre clavier, vous devez dire -au système d'exploitation quel @dfn{disposition du clavier} vous voulez -utiliser. Par défaut, lorsque rien n'est spécifié, la disposition QWERTY -pour l'anglais américain pour les claviers 105 touches est utilisée. -Cependant, les germanophones préfèrent généralement la disposition QWERTZ, -les francophones la disposition AZERTY etc ; les hackers peuvent préférer -Dvorak ou bépo, et peuvent même vouloir personnaliser plus en détails -l'effet de certaines touches. Cette section explique comment faire cela. - -@cindex disposition du clavier, définition -Il y a trois composants qui devront connaître votre disposition du clavier : - -@itemize -@item -Le @emph{chargeur d'amorçage} peut avoir besoin de connaître la disposition -clavier que vous voulez utiliser (@pxref{Configuration du chargeur d'amorçage, -@code{keyboard-layout}}). C'est utile si vous voulez par exemple vous -assurer que vous pouvez saisir la phrase de passe de votre partition racine -chiffrée avec la bonne disposition. - -@item -Le @emph{noyau du système d'exploitation}, Linux, en aura besoin pour -configurer correctement la console (@pxref{Référence de système d'exploitation, -@code{keyboard-layout}}). - -@item -Le @emph{serveur d'affichage graphique}, habituellement Xorg, a aussi sa -propre idée sur la disposition du clavier à utiliser (@pxref{Système de fenêtrage X, -@code{keyboard-layout}}). -@end itemize - -Guix vous permet de configurer les trois séparément mais, heureusement, il -vous permet de partager la même disposition du clavier pour chacun des trois -composants. - -@cindex XKB, disposition du clavier -Les dispositions de clavier sont représentées par des enregistrements créés -par la procédure @code{keyboard-layout} de @code{(gnu system keyboard)}. En -suivant l'extension clavier de X (XKB), chaque disposition a trois attributs -: un nom (souvent un code de langue comme « fi » pour le finnois ou « jp » -pour le japonais), un nom de variante facultatif, un nom de modèle de -clavier facultatif et une liste éventuellement vide d'options -supplémentaires. Dans la plupart des cas, vous n'aurez besoin que du nom de -la disposition. Voici quelques exemples : - -@example -;; La disposition QWERTZ allemande. Ici on suppose que vous utilisez un clavier -;; type « pc105 » standard. -(keyboard-layout "de") - -;; La variante bépo de la disposition française. -(keyboard-layout "fr" "bepo") - -;; La disposition catalane. -(keyboard-layout "es" "cat") - -;; La disposition espagnole américaine. En plus, la touche -;; « Verr. Maj. » est utilisée comme touche « Ctrl » supplémentaire, -;; et la touche « Menu » est utilisée comme touche « Compose » pour -;; saisir des lettres accentuées. -(keyboard-layout "latam" - #:options '("ctrl:nocaps" "compose:menu")) - -;; La disposition russe pour un clavier de ThinkPad. -(keyboard-layout "ru" #:model "thinkpad") - -;; La disposition « US internationale », qui est comme la disposition US plus -;; des touches mortes pour saisir des caractères accentués. Cet exemple est pour -;; un clavier de MacBook Apple. -(keyboard-layout "us" "intl" #:model "macbook78") -@end example - -Voir le répertoire @file{share/X11/xkb} du paquet @code{xkeyboard-config} -pour une liste complète des disposition, des variantes et des modèles pris -en charge. - -@cindex disposition du clavier, configuration -Disons que vous voulez que votre système utilise la disposition turque sur -tout le système — du chargeur d'amorçage à Xorg en passant par la console. -Voici ce que votre configuration du système contiendrait : - -@findex set-xorg-configuration -@lisp -;; Utiliser la disposition turque pour le chargeur d'amorçage, -;; la console et Xorg. -(operating-system - ;; ... - (keyboard-layout (keyboard-layout "tr")) ;pour la console - (bootloader (bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi") - (keyboard-layout keyboard-layout))) ;pour GRUB - (services (cons (set-xorg-configuration - (xorg-configuration ;pour Xorg - (keyboard-layout keyboard-layout))) - %desktop-services))) -@end lisp - -Dans l'exemple ci-dessus, pour GRUB et pour Xorg, nous nous référons -simplement au champ @code{keyboard-layout} au dessus, mais on pourrait aussi -bien se référer à une autre disposition. La procédure -@code{set-xorg-configuration} communique la configuration Xorg désirée au -gestionnaire de connexion, par défaut GDM. - -Nous avons discuté de la manière de spécifier la disposition du clavier -@emph{par défaut} lorsque votre système démarre, mais vous pouvez aussi -l'ajuster à l'exécution : - -@itemize -@item -Si vous utilisez GNOME, son panneau de configuration contient une entrée « -Région & Langues » où vous pouvez choisir une ou plusieurs dispositions du -clavier. - -@item -Sous Xorg, la commande @command{sexkbmap} (du paquet du même nom) vous -permet de changer la disposition actuelle. Par exemple, voilà comment -changer la disposition pour un Dvorak américain : - -@example -setxkbmap us dvorak -@end example - -@item -La commande @code{loadkey} change la disposition du clavier dans la console -Linux. Cependant, remarque que @code{loadkeys} n'utilise @emph{pas} la -catégorisation des dispositions XKB décrite plus haut. La commande suivante -charge la disposition bépo française : - -@example -loadkeys fr-bepo -@end example -@end itemize - -@node Régionalisation -@section Régionalisation - -@cindex paramètres linguistiques -Un @dfn{paramètre linguistique} définie les conventions culturelles d'une -langue et d'une région particulières (@pxref{Régionalisation,,, libc, The GNU C -Library Reference Manual}). Chaque paramètre linguistique a un nom de la -forme @code{@var{langue}_@var{territoire}.@var{jeudecaractères}} — p.@: -ex.@: @code{fr_LU.utf8} désigne le paramètre linguistique pour le français, -avec les conventions culturelles du Luxembourg, en utilisant l'encodage -UTF-8. - -@cindex définition des paramètres linguistiques -Normalement, vous voudrez spécifier les paramètres linguistiques par défaut -pour la machine en utilisant le champ @code{locale} de la déclaration -@code{operating-system} (@pxref{Référence de système d'exploitation, @code{locale}}). - -Les paramètres régionaux choisis sont automatiquement ajoutés aux -définitions des @dfn{paramètres régionaux} connues par le système au besoin, -avec le jeu de caractères inféré à partir de son nom, p.@: ex.@: -@code{bo_CN.utf8} supposera qu'il faut utiliser le jeu de caractères -@code{UTF-8}. Des définitions supplémentaires peuvent être spécifiées dans -le champ @code{locale-definitions} de @code{operating-system} — c'est utile -par exemple si le jeu de caractères n'a pas été inféré à partir du nom. -L'ensemble par défaut de définitions comprend certains paramètres -linguistiques parmi les plus utilisés, mais pas toutes les variantes -disponibles, pour gagner de la place. - -Par exemple, pour ajouter les paramètres pour le frison septentrional en -Allemagne, la valeur de ce champ serait : - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -De me, pour gagner de la place, on peut vouloir lister dans -@code{locale-definitions} seulement les paramètres qui sont vraiment -utilisés, comme dans : - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -Les définitions des paramètres linguistiques compilées sont disponibles dans -@file{/run/current-system/locale/X.Y}, où @code{X.Y} est la version de la -libc, ce qui est l'emplacement par défaut où la GNU@tie{}libc fournie par -Guix cherche les données de régionalisation. Cet emplacement peut être -modifié avec la variable d'environnement @code{LOCPATH} -(@pxref{locales-and-locpath, @code{LOCPATH} and locale packages}). - -La forme @code{locale-definition} est fournie par le module @code{(gnu -system locale)}. Des détails sont disponibles plus bas. - -@deftp {Type de données} locale-definition -C'est le type de données d'une définition de paramètres linguistiques. - -@table @asis - -@item @code{name} -Le nom du paramètre linguistique. @xref{Locale Names,,, libc, The GNU C -Library Reference Manual}, pour en savoir plus sur les noms de paramètres -linguistiques. - -@item @code{source} -Le nom de la source pour ce paramètre linguistique. C'est typiquement la -partie @code{@var{langue}_@var{territoire}} du nom du paramètre. - -@item @code{charset} (par défaut : @code{"UTF-8"}) -Le « jeu de caractères » d'un paramètre linguistique, -@uref{http://www.iana.org/assignments/character-sets, défini par l'IANA}. - -@end table -@end deftp - -@defvr {Variable Scheme} %default-locale-definitions -Une liste des paramètres linguistiques UTF-8 couramment utilisés, utilisée -comme valeur par défaut pour le champ @code{locale-definitions} des -déclarations @code{operating-system}. - -@cindex nom de paramètre linguistique -@cindex jeu de caractère normalisé dans les noms de paramètres linguistiques -Ces définitions de paramètres linguistiques utilisent le @dfn{jeu de -caractère normalisé} pour la partie qui suit le point dans le nom -(@pxref{Using gettextized software, normalized codeset,, libc, The GNU C -Library Reference Manual}). Donc par exemple il y a @code{uk_UA.utf8} mais -@emph{pas}, disons, @code{uk_UA.UTF-8}. -@end defvr - -@subsection Considérations sur la compatibilité des données linguistiques - -@cindex incompatibilité, des données linguistiques -Les déclaration @code{operating-system} fournissent un champ -@code{locale-libcs} pour spécifier les paquets GNU@tie{}libc à utiliser pour -compiler les déclarations de paramètres linguistiques -(@pxref{Référence de système d'exploitation}). « Pourquoi je devrais m'en soucier ? -», vous demandez-vous sûrement. Hé bien il se trouve que le format binaire -des données linguistique est parfois incompatible d'une version de la libc à -une autre. - -@c See -@c and . -Par exemple, un programme lié à la libc version 2.21 est incapable de lire -les données linguistiques produites par la libc 2.22 ; pire, ce programme -@emph{plante} plutôt que d'ignorer les données linguistiques -incompatibles@footnote{Les version 2.23 et supérieures de la GNU@tie{}libc -sauteront simplement les données linguistiques incompatibles, ce qui est -déjà mieux.}. De même, un programme lié à la libc 2.22 peut lire la plupart -mais pas toutes les données linguistiques de la libc 2.21 (spécifiquement -les données @code{LC_COLLATE} sont incompatibles) ; donc les appels à -@code{setlocale} peuvent échouer, mais les programmes ne plantent pas. - -Le « problème » avec Guix c'est que les utilisateurs ont beaucoup de liberté -: ils peuvent choisir s'ils veulent et quand ils veulent mettre à jour les -logiciels de leur profil, et peuvent utiliser une version différente de la -libc de celle que l'administrateur système utilise pour construire les -données linguistiques du système global. - -Heureusement, les utilisateurs non privilégiés peuvent aussi installer leur -propres données linguistiques et définir @var{GUIX_LOCPATH} comme il le faut -(@pxref{locales-and-locpath, @code{GUIX_LOCPATH} and locale packages}). - -Cependant, c'est encore mieux si les données linguistiques du système dans -@file{/run/current-system/locale} étaient construites avec les versions de -la libc utilisées sur le système, pour que tous les programmes puissent y -accéder — c'est surtout crucial sur un système multi-utilisateurs. Pour -cela, l'administrateur peut spécifier plusieurs paquets de la libc dans le -champ @code{locale-libcs} de @code{operating-system} : - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -Cet exemple créera un système contenant les définitions des paramètres -linguistiques pour la libc 2.21 et pour la version actuelle de la libc dans -@file{/run/current-system/locale}. - - -@node Services -@section Services - -@cindex services systèmes -Une part importante de la préparation d'une déclaration -@code{operating-system} est la liste des @dfn{services systèmes} et de leur -configuration (@pxref{Utiliser le système de configuration}). Les services -systèmes sont typiquement des démons lancés au démarrage ou d'autres actions -requises à ce moment-là — p.@: ex.@: configurer les accès réseaux. - -Guix a une définition large de « service » (@pxref{Composition de services}), -mais beaucoup de services sont gérés par le GNU@tie{}Shepherd -(@pxref{Services Shepherd}). Sur un système lancé, la commande -@command{herd} vous permet de lister les services disponibles, montrer leur -statut, les démarrer et les arrêter, ou faire d'autres opérations -spécifiques (@pxref{Jump Start,,, shepherd, The GNU Shepherd Manual}). Par -exemple : - -@example -# herd status -@end example - -La commande ci-dessus, lancée en @code{root}, liste les services -actuellement définis. La commande @command{herd doc} montre un synopsis du -service donné et ses actions associées : - -@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 - -Les sous-commandes @command{start}, @command{stop} et @command{restart} ont -l'effet auquel on s'attend. Par exemple, les commande suivantes stoppent le -service nscd et redémarrent le serveur d'affichage Xorg : - -@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 - -Les sections suivantes documentent les services disponibles, en commençant -par les services de base qui peuvent être utilisés avec une déclaration -@code{operating-system}. - -@menu -* Services de base:: Services systèmes essentiels. -* Exécution de tâches planifiées:: Le service mcron. -* Rotation des journaux:: Le service rottlog. -* Services réseau:: Paramètres réseau, démon SSH, etc. -* Système de fenêtrage X:: Affichage graphique. -* Services d'impression:: Support pour les imprimantes locales et - distantes. -* Services de bureaux:: D-Bus et les services de bureaux. -* Services de son:: Services ALSA et Pulseaudio. -* Services de bases de données:: Bases SQL, clefs-valeurs, etc. -* Services de courriels:: IMAP, POP3, SMTP, et tout ça. -* Services de messagerie:: Services de messagerie. -* Services de téléphonie:: Services de téléphonie. -* Services de surveillance:: Services de surveillance. -* Services Kerberos:: Services Kerberos. -* Services LDAP:: services LDAP -* Services web:: Services web. -* Services de certificats:: Certificats TLS via Let's Encrypt. -* Services DNS:: Démons DNS@. -* Services VPN:: Démons VPN. -* Système de fichiers en réseau:: Services liés à NFS@. -* Intégration continue:: Le service Cuirass. -* Services de gestion de l'énergie:: Augmenter la durée de vie de la - batterie. -* Services audio:: MPD@. -* Services de virtualisation:: Services de virtualisation. -* Services de contrôle de version:: Fournit des accès distants à des - dépôts Git. -* Services de jeu:: Serveurs de jeu. -* Services divers:: D'autres services. -@end menu - -@node Services de base -@subsection Services de base - -Le module @code{(gnu services base)} fournit des définitions de services -pour les services de base qu'on peut attendre du système. Les services -exportés par ce module sort listés ci-dessous. - -@defvr {Variable Scheme} %base-services -Cette variable contient une liste de services de base (@pxref{Types service et services}, pour plus d'informations sur les objets service) qu'on peut -attendre du système : un service de connexion (mingetty) sur chaque tty, -syslogd, le démon de cache de noms de la libc (nscd), le gestionnaire de -périphériques udev, et plus. - -C'est la valeur par défaut du champ @code{services} des déclarations -@code{operating-system}. Habituellement, lors de la personnalisation d'un -système, vous voudrez ajouter des services à ceux de @var{%base-services}, -comme ceci : - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Variable Scheme} special-files-service-type -C'est le service qui met en place des « fichiers spéciaux » comme -@file{/bin/sh} ; une instance de ce service fait partie de -@code{%base-services}. - -La valeur associée avec les services @code{special-files-service-type} doit -être une liste de couples dont le premier élément est le « fichier spécial » -et le deuxième sa cible. Par défaut il s'agit de : - -@cindex @file{/bin/sh} -@cindex @file{sh}, dans @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example - -@cindex @file{/usr/bin/env} -@cindex @file{env}, dans @file{/usr/bin} -Si vous voulez ajouter, disons, @code{/usr/bin/env} à votre système, vous -pouvez changer cela en : - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Comme il fait parti de @code{%base-services}, vous pouvez utiliser -@code{modify-services} pour personnaliser l'ensemble des fichiers spéciaux -(@pxref{Référence de service, @code{modify-services}}). Mais une manière plus -simple d'ajouter un fichier spécial est d'utiliser la procédure -@code{extra-special-file} (voir plus bas). -@end defvr - -@deffn {Procédure Scheme} extra-special-file @var{file} @var{target} -Utilise @var{target} comme « fichier spécial » @var{file}. - -Par exemple, ajouter l'une des lignes suivantes au champ @code{services} de -votre déclaration de système d'exploitation crée un lien symbolique -@file{/usr/bin/env} : - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Procédure Scheme} host-name-service @var{name} -Renvoie un service qui paramètre le nom d'hôte à @var{name}. -@end deffn - -@deffn {Procédure Scheme} login-service @var{config} -Renvoie un service pour lancer login en suivant @var{config}, un objet -@code{} qui spécifie le message du jour, entre autres -choses. -@end deffn - -@deftp {Type de données} login-configuration -Le type de données qui représente la configuration de login. - -@table @asis - -@item @code{motd} -@cindex message du jour -Un objet simili-fichier contenant le « message du jour ». - -@item @code{allow-empty-passwords?} (par défaut : @code{#t}) -Permet les mots de passes vides par défaut pour que les utilisateurs -puissent se connecter au compte « root » la première fois après sa création. - -@end table -@end deftp - -@deffn {Procédure Scheme} mingetty-service @var{config} -Renvoie un service qui lance mingetty en suivant @var{config}, un objet -@code{}, qui spécifie le tty à lancer entre autres -choses. -@end deffn - -@deftp {Type de données} mingetty-configuration -C'est le type de données représentant la configuration de Mingetty, qui -fournit l'implémentation par défaut de l'écran de connexion des consoles -virtuelles. - -@table @asis - -@item @code{tty} -Le nom de la console sur laquelle tourne ce Mingetty, p.@: ex.@: -@code{"tty1"}. - -@item @code{auto-login} (par défaut : @code{#f}) -Lorsque la valeur est vraie, ce champ doit être une chaîne de caractère -dénotant le nom d'utilisateur pour lequel le système se connecte -automatiquement. Lorsque la valeur est @code{#f}, il faut entrer un nom -d'utilisateur et un mot de passe pour se connecter. - -@item @code{login-program} (par défaut : @code{#f}) -Ce doit être soit @code{#f}, auquel cas le programme de connexion par défaut -est utilisé (@command{login} de la suite d'outils Shadow), soit une gexp -dénotant le nom d'un programme de connexion. - -@item @code{login-pause?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t} en plus de @var{auto-login}, l'utilisateur -devrai appuyer sur une touche avant que le shell de connexion ne soit lancé. - -@item @code{mingetty} (par défaut : @var{mingetty}) -Le paquet Mingetty à utiliser. - -@end table -@end deftp - -@deffn {Procédure Scheme} agetty-service @var{config} -Renvoie un service pour lancer agetty en suivant @var{config}, un objet -@code{}, qui spécifie le tty à lancer, entre autres -choses. -@end deffn - -@deftp {Type de données} agetty-configuration -Ce type de données représente la configuration de agetty, qui implémente -l'écran de connexion des consoles virtuelles et series. Voir la page de -manuel de @code{agetty(8)} pour plus d'informations. - -@table @asis - -@item @code{tty} -Le nom de la console sur laquelle agetty est lancé p.@: ex.@: -@code{"ttyS0"}. Cet argument est facultatif, il aura par défaut une valeur -raisonnable d'un port série utilisé par le noyau Linux. - -Pour cela, s'il y a une valeur pour une option @code{agetty.tty} sur la -ligne de commande du noyau, agetty extraira le nom du périphérique du port -série à partir de cette option. - -Sinon et s'il y a une valeur pour une option @code{console} avec un tty sur -la ligne de commande du noyau Linux, agetty extraira le nom du périphérique -du port série et l'utilisera. - -Dans les deux cas, agetty laissera les autres paramètres du périphérique -série (baud, etc) sans y toucher — dans l'espoir que Linux leur a assigné -les bonnes valeurs. - -@item @code{baud-rate} (par défaut : @code{#f}) -Une chaîne qui contient une liste d'un ou plusieurs taux de baud séparés par -des virgules, en ordre décroissant. - -@item @code{term} (par défaut : @code{#f}) -Une chaîne contenant la valeur utilisée pour la variable d'environnement -@code{TERM}. - -@item @code{eight-bits?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, le tty est supposé être propre pour les -caractères 8-bit et la détection de parité est désactivée. - -@item @code{auto-login} (par défaut : @code{#f}) -Lorsqu'un nom de connexion est passé comme une chaîne de caractères, -l'utilisateur spécifié sera automatiquement connecté sans demande du nom -d'utilisateur ni du mot de passe. - -@item @code{no-reset?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, ne vide pas les cflags du terminal (modes -de contrôle). - -@item @code{host} (par défaut : @code{#f}) -Cette option accepte une chaîne contenant le « login_host », qui sera écrit -dans le fichier @file{/var/run/utmpx}. - -@item @code{remote?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t} en plus de @var{host}, cette option ajoutera -une option fakehost @code{-r} à la ligne de commande du programme de -connexion spécifié dans @var{login-program}. - -@item @code{flow-control?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, active le contrôle de flux matériel -(RTS/CTS). - -@item @code{no-issue?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, le contenu du fichier @file{/etc/issue} ne -sera pas affiché avant de présenter l'écran de connexion. - -@item @code{init-string} (par défaut : @code{#f}) -Cette option accepte une chaîne de caractères qui sera envoyée au tty ou au -modem avant toute autre chose. Elle peut être utilisée pour initialiser un -modem. - -@item @code{no-clear?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, agetty ne nettoiera pas l'écran avant de -montrer l'écran de connexion. - -@item @code{login-program} (par défaut : (file-append shadow "/bin/login")) -Cette option doit être soit une gexp dénotant le nom d'un programme de -connexion, soit non définie, auquel cas la valeur par défaut est la commande -@command{login} de la suite d'outils Shadow. - -@item @code{local-line} (par défaut : @code{#f}) -Contrôle le drapeau CLOCAL. Cette option accepte l'un des trois symboles -comme argument, @code{'auto}, @code{'always} ou @code{'never}. Si la valeur -est @code{#f}, la valeur par défaut choisie par agetty est @code{'auto}. - -@item @code{extract-baud?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, dit à agetty d'essayer d'extraire la taux -de baud depuis les messages de statut produits par certains modems. - -@item @code{skip-login?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, ne demande par de nom d'utilisateur. Elle -peut être utilisée avec le champ @var{login-program} pour utiliser des -systèmes de connexion non standards. - -@item @code{no-newline?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, n'affiche pas de retour à la ligne avant -d'afficher le fichier @file{/etc/issue}. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (par défaut : @code{#f}) -Cette option accepte une chaîne de caractères contenant des options passées -au programme login. Lorsqu'utilisé avec @var{login-program}, soyez -conscient qu'un utilisateur malicieux pourrait essayer de rentrer un nom -d'utilisateur contenant des options incluses qui pourraient être analysées -par le programme de connexion. - -@item @code{login-pause} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, attend qu'une touche soit appuyée avant de -montrer l'écran de connexion. Cela peut être utilisé avec @var{auto-login} -pour sauvegarder de la mémoire en lançant les shells de manière fainéante. - -@item @code{chroot} (par défaut : @code{#f}) -Change de racine dans le répertoire donné. Cette option accepte un chemin -en tant que chaîne de caractères. - -@item @code{hangup?} (par défaut : @code{#f}) -Utilise l'appel système Linux @code{vhangup} pour raccrocher virtuellement -le terminal spécifié. - -@item @code{keep-baud?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, essaye de garder le taux de baud existant. -Les taux de baud de @var{baud-rate} sont utilisés lorsque agetty reçoit un -caractères @key{BREAK}. - -@item @code{timeout} (par défaut : @code{#f}) -Lorsque la valeur est un nombre entier, termine la session si aucun nom -d'utilisateur n'a pu être lu après @var{timeout} secondes. - -@item @code{detect-case?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, active le support pour la détection des -terminaux en majuscule uniquement. Ce paramètre détectera qu'un nom -d'utilisateur qui ne contient que des majuscules indique un terminal en -majuscule et effectuera des conversion de majuscule en minuscule. Remarquez -que cela ne fonctionne pas avec les caractères unicode. - -@item @code{wait-cr?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, attend que l'utilisateur ou le modem envoie -un retour chariot ou un saut de ligne avant d'afficher @file{/etc/issue} ou -l'écran de connexion. Cela est typiquement utilisé avec l'option -@var{init-string}. - -@item @code{no-hints?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, n'affiche par les astuces à propos des -verrouillages numériques, majuscule et défilement. - -@item @code{no-hostname?} (par défaut : @code{#f}) -Par défaut, le nom d'hôte est affiché. Lorsque la valeur est @code{#t}, -aucun nom d'hôte ne sera affiché. - -@item @code{long-hostname?} (par défaut : @code{#f}) -Par défaut, le nom d'hôte n'est affiché qu'après le premier point. Lorsque -la valeur est @code{#t}, le nom d'hôte pleinement qualifié renvoyé par -@code{gethostname} ou @code{getaddrinfo} sera affiché. - -@item @code{erase-characters} (par défaut : @code{#f}) -Cette option accepte une chaîne de caractères de caractères supplémentaires -qui devraient être interprétés comme des effacements lorsque l'utilisateur -les tape dans leur nom d'utilisateur. - -@item @code{kill-characters} (par défaut : @code{#f}) -Cette option accepte une chaîne de caractères qui devrait être interprété -comme signifiant « ignore tous les caractères précédent » (aussi appelé un -caractère « kill ») lorsque l'utilisateur tape son nom d'utilisateur. - -@item @code{chdir} (par défaut : @code{#f}) -Cette option accepte, en tant que chaîne de caractères, un chemin vers un -répertoire dans lequel se trouvera la commande avant la connexion. - -@item @code{delay} (par défaut : @code{#f}) -Cette option accepte, en tant qu'entier, le nombre de secondes à attendre -avant d'ouvrir le tty et afficher l'écran de connexion. - -@item @code{nice} (par défaut : @code{#f}) -Cette option accepte, en tant qu'entier, la valeur « nice » avec laquelle le -programme @command{login} tourne. - -@item @code{extra-options} (par défaut : @code{'()}) -Cette option fournie un « mécanisme de secours » pour que l'utilisateur -puisse ajouter des arguments de la ligne de commande arbitraires à -@command{agetty} comme une liste de chaînes de caractères. - -@end table -@end deftp - -@deffn {Procédure Scheme} kmscon-service-type @var{config} -Renvoie un service qui lance -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} d'après -@var{config}, un objet @code{}, qui spécifie le tty -sur lequel tourner, entre autres choses. -@end deffn - -@deftp {Type de données} kmscon-configuration -C'est le type de données représentant la configuration de Kscon, qui -implémente l'écran de chargement de la console virtuelle. - -@table @asis - -@item @code{virtual-terminal} -Le nom de la console sur laquelle Kmscon tourne, p.@: ex.@: @code{"tty1"}. - -@item @code{login-program} (par défaut : @code{#~(string-append #$shadow "/bin/login")}) -Une gexp qui dénote le nom d'un programme de connexion. le programme de -connexion par défaut est @command{login} de la suite d'outils Shadow. - -@item @code{login-arguments} (par défaut : @code{'("-p")}) -Une liste d'arguments à passer à @command{login}. - -@item @code{auto-login} (par défaut : @code{#f}) -Lorsqu'un nom de connexion est passé comme une chaîne de caractères, -l'utilisateur spécifié sera automatiquement connecté sans demande du nom -d'utilisateur ni du mot de passe. - -@item @code{hardware-acceleration?} (par défaut : #f) -S'il faut utiliser l'accélération matérielle. - -@item @code{kmscon} (par défaut : @var{kmscon}) -Le paquet Kmscon à utiliser. - -@end table -@end deftp - -@cindex name service cache daemon -@cindex nscd -@deffn {Procédure Scheme} nscd-service [@var{config}] [#:glibc glibc] @ - [#:name-services '()] -Renvoie un service qui lance le démon de cache de services de noms de la -libc (nscd) avec la @var{config} donnée — un objet -@code{}. @xref{Name Service Switch}, pour un exemple. - -Parce que c'est pratique, le service du Shepherd pour nscd fournit les -actions suivantes : - -@table @code -@item invalidate -@cindex invalidation du cache, nscd -@cindex nscd, invalidation du cache -Cela invalide le cache donné. Par exemple, en laçant : - -@example -herd invalidate nscd hosts -@end example - -@noindent -on invalide le cache de noms d'hôtes de nscd. - -@item statistiques -Lancer @command{herd statistics nscd} affiche des informations sur -l'utilisation de nscd et des caches. -@end table - -@end deffn - -@defvr {Variable Scheme} %nscd-default-configuration -C'est la valeur par défaut de @code{} (voir plus bas) -utilisée par @code{nscd-service}. Elle utilise les caches définis par -@var{%nscd-default-caches} ; voir plus bas. -@end defvr - -@deftp {Type de données} nscd-configuration -C'est le type de données qui représente la configuration du démon de cache -de services de noms (nscd). - -@table @asis - -@item @code{name-services} (par défaut : @code{'()}) -Liste des paquets dénotant des @dfn{services de noms} qui doivent être -visible pour nscd, p.@: ex.@: @code{(list @var{nss-mdns})}. - -@item @code{glibc} (par défaut : @var{glibc}) -Objet de paquet qui dénote la Bibliothèque C de GNU qui fournit la commande -@command{nscd}. - -@item @code{log-file} (par défaut : @code{"/var/log/nscd.log"}) -Nom du fichier journal de nscd. C'est là que les sorties de débogage sont -envoyée lorsque @code{debug-level} est strictement positif. - -@item @code{debug-level} (par défaut : @code{0}) -Entier qui dénote le niveau de débogage. Les entiers les plus grands -signifient plus de sortie de débogage. - -@item @code{caches} (par défaut : @var{%nscd-default-caches}) -Liste d'objets @code{} qui dénotent des choses à mettre en cache -; voir plus bas. - -@end table -@end deftp - -@deftp {Type de données} nscd-cache -Type de données représentant une base de données de cache de nscd et ses -paramètres. - -@table @asis - -@item @code{database} -C'est un symbole qui représente le nom de la base de donnée à mettre en -cache. Les valeurs valide sont @code{passwd}, @code{group}, @code{hosts} et -@code{services} qui désignent les bases de données NSS correspondantes -(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (par défaut : @code{20}) -Un entier qui représente le nombre de secondes pendant lesquelles un -résultat positif ou négatif reste en cache. - -@item @code{check-files?} (par défaut : @code{#t}) -Indique s'il faut vérifier des mises à jours dans les fichiers correspondant -à @var{database}. - -Par exemple, lorsque @var{database} est @code{hosts}, ce drapeau indique à -nscd de vérifier s'il y a des mises à jour de @file{/etc/hosts} et de les -prendre en compte. - -@item @code{persistent?} (par défaut : @code{#t}) -Indique si le cache devrait être stocké de manière persistante sur le -disque. - -@item @code{shared?} (par défaut : @code{#t}) -Indique si le cache devrait être partagé entre les utilisateurs. - -@item @code{max-database-size} (par défaut : 32@tie{}MiB) -Taille maximale en octets de la base de données en cache. - -@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert -@c settings, so leave them out. - -@end table -@end deftp - -@defvr {Variable Scheme} %nscd-default-caches -Liste d'objets @code{} utilisés par défaut par -@code{nscd-configuration} (voir plus haut). - -Elle active la mise en cache persistante et agressive des recherches de -services et de noms d'hôtes. Ces derniers fournissent une recherche de noms -d'hôtes plus performante, résiliente face à des serveurs de noms peu fiables -et une protection de votre vie privée plus efficace — souvent le résultat -des recherches de noms d'hôtes sont dans le cache local, donc les serveurs -de nom externes n'ont même pas besoin d'être questionnés. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex logging -@deftp {Type de données} syslog-configuration -Ce type de données représente la configuration du démon syslog. - -@table @asis -@item @code{syslogd} (par défaut : @code{#~(string-append #$inetutils "/libexec/syslogd")}) -Le démon syslog à utiliser. - -@item @code{config-file} (par défaut : @code{%default-syslog.conf}) -Le fichier de configuration de syslog à utiliser. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Procédure Scheme} syslog-service @var{config} -Renvoie un service qui lance un démon syslog en suivant @var{config}. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, pour plus -d'informations sur la syntaxe du fichier de configuration. -@end deffn - -@defvr {Variable Scheme} guix-service-type -C'est le type de service qui lance le démon de construction, -@command{guix-daemon} (@pxref{Invoquer guix-daemon}). Sa valeur doit être -un enregistrement @code{guix-configuration} décrit plus bas. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Type de données} guix-configuration -Ce type de données représente la configuration du démon de construction de -Guix. @xref{Invoquer guix-daemon} pour plus d'informations. - -@table @asis -@item @code{guix} (par défaut : @var{guix}) -Le paquet Guix à utiliser. - -@item @code{build-group} (par défaut : @code{"guixbuild"}) -Nom du groupe des comptes utilisateurs de construction. - -@item @code{build-accounts} (par défaut : @code{10}) -Nombre de comptes utilisateurs de construction à créer. - -@item @code{authorize-key?} (par défaut : @code{#t}) -@cindex substituts, autorisations -Indique s'il faut autoriser ou non les clefs de substituts listées dans -@code{authorize-keys} — par défaut celle de @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substituts}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (par défaut : @var{%default-authorized-guix-keys}) -La liste des fichiers de clefs autorisées pour les imports d'archives, en -tant que liste de gexps sous forme de chaînes (@pxref{Invoquer guix archive}). Par défaut, elle contient celle de -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Substituts}). - -@item @code{use-substitutes?} (par défaut : @code{#t}) -S'il faut utiliser les substituts. - -@item @code{substitute-urls} (par défaut : @var{%default-substitute-urls}) -La liste des URL où trouver des substituts par défaut. - -@item @code{max-silent-time} (par défaut : @code{0}) -@itemx @code{timeout} (par défaut : @code{0}) -Le nombre de secondes de silence et le nombre de secondes d'inactivité, -respectivement, après lesquelles un processus de construction son délai -d'attente. Une valeur de zéro désactive le délai d'attente. - -@item @code{log-compression} (par défaut : @code{'bzip2}) -Le type de compression utilisé par les journaux de construction — parmi -@code{gzip}, @code{bzip2} et @code{none}. - -@item @code{extra-options} (par défaut : @code{'()}) -Liste d'options supplémentaires de la ligne de commande pour -@command{guix-daemon}. - -@item @code{log-file} (par défaut : @code{"/var/log/guix-daemon.log"}) -Le fichier où les sorties standard et d'erreur de @command{guix-daemon} sont -écrites. - -@item @code{http-proxy} (par défaut : @code{#f}) -Le serveur mandataire HTTP à utiliser pour télécharger les dérivations à -sortie fixe et les substituts. - -@item @code{tmpdir} (par défaut : @code{#f}) -Un répertoire où @command{guix-daemon} effectuera ses constructions. - -@end table -@end deftp - -@deffn {Procédure Scheme} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Lance @var{udev}, qui rempli le répertoire @file{/dev} dynamiquement. Les -règles udev peuvent être fournies comme une liste de fichier via la variable -@var{rules}. Les procédures @var{udev-rule} et @var{file->udev-rule} de -@code{(gnu services base)} simplifient la création de ces fichiers de règle. -@end deffn - -@deffn {Procédure Scheme} udev-rule [@var{file-name} @var{contents}] -Renvoie un fichier de règle udev nommé @var{file-name} contenant les règles -définie par le littéral @var{contents}. - -Dans l'exemple suivant, on définie une règle pour un périphérique USB qui -sera stockée dans le fichier @file{90-usb-thing.rules}. La règle lance un -script à la détection du périphérique USB avec l'identifiant de produit -donné. - -@example -(define %example-udev-rule - (udev-rule - "90-usb-thing.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Example\", " - "RUN+=\"/path/to/script\""))) -@end example - -La commande @command{herd rules udev}, en tant que root, renvoie le nom du -répertoire contenant toutes les règles udev actives. -@end deffn - -Ici on montre comment le service @var{udev-service} par défaut peut être -étendu avec cette règle. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %example-udev-rule)))))))) -@end example - -@deffn {Procédure Scheme} file->udev-rule [@var{file-name} @var{file}] -Renvoie un fichier udev nommé @var{file-name} contenant les règles définies -dans @var{file}, un objet simili-fichier. - -L'exemple suivant montre comment utiliser un fichier de règles existant. - -@example -(use-modules (guix download) ;pour url-fetch - (guix packages) ;pour 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 - -En plus, les définitions des paquets de Guix peuvent être inclus dans -@var{rules} pour étendre les règles avec les définitions trouvées dans leur -sous-répertoire @file{lib/udev/rules.d}. Au lieu de l'exemple -@var{file->udev-rule} précédent, on aurait pu utiliser le paquet -@var{android-udev-rules} qui existe dans le module @code{(gnu packages -android)}. - -L'exemple suivant montre comment utiliser le paquet @var{android-udev-rules} -pour que l'outil Android @command{adb} puisse détecter les appareils sans -privilège root. Il détaille aussi comment créer le groupe @code{adbusers}, -requis pour le bon fonctionnement des règles définies dans le paquet -@var{android-udev-rules}. Pour créer ce groupe, on doit le définir dans les -@var{supplementary-groups} de la déclaration @var{user-account} ainsi que -dans le champ @var{groups} de l'enregistrement @var{operating-system}. - -@example -(use-modules (gnu packages android) ;for android-udev-rules - (gnu system shadow) ;for user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;for 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 {Variable Scheme} urandom-seed-service-type -Garde de l'entropie dans @var{%random-seed-file} pour démarrer -@file{/dev/urandom} au redémarrage. Ce service essaye aussi de démarrer -@file{/dev/urandom} à partir de @file{/dev/hwrng} au démarrage si -@file{/dev/hwrng} existe et peut être lu. -@end defvr - -@defvr {Variable Scheme} %random-seed-file -C'est le nom du fichier où des octets aléatoires sont sauvegardés par -@var{urandom-seed-service} pour démarrer @file{/dev/urandom} au -redémarrage. Sa valeur par défaut est @file{/var/lib/random-seed}. -@end defvr - -@cindex souris -@cindex gpm -@defvr {Variable Scheme} gpm-service-type -C'est le type du service qui lance GPM, le @dfn{démon de souris à but -général}, qui fournit le support de la souris sur la console Linux. GPM -permet aux utilisateurs d'utiliser la souris dans la console, entre autres -pour sélectionner, copier et coller du texte. - -La valeur pour les services de ce type doit être un @code{gpm-configuration} -(voir plus bas). Ce service ne fait pas partie de @var{%base-services}. -@end defvr - -@deftp {Type de données} gpm-configuration -Type de données représentant la configuration de GPM. - -@table @asis -@item @code{options} (par défaut : @code{%default-gpm-options}) -Les options de la ligne de commande à passer à @command{gpm}. L'ensemble -des options par défaut dit à @command{gpm} d'écouter les événements de la -souris dans @file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, -pour plus d'informations. - -@item @code{gpm} (par défaut : @code{gpm}) -Le paquet GPM à utiliser. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Variable Scheme} guix-publish-service-type -C'est le type de service pour @command{guix publish} (@pxref{Invoquer guix publish}). Sa valeur doit être un objet @code{guix-configuration} décrit -plus bas. - -Ce service suppose que @file{/etc/guix} contient déjà une paire de clefs -créée par @command{guix archive --generate-key} (@pxref{Invoquer guix archive}). Si ce n'est pas le cas, le service ne démarrera pas. -@end deffn - -@deftp {Type de données} guix-publish-configuration -Le type de données représentant la configuration du service @code{guix -publish}. - -@table @asis -@item @code{guix} (par défaut : @code{guix}) -Le paquet Guix à utiliser. - -@item @code{port} (par défaut : @code{80}) -Le port TCP sur lequel écouter les connexions. - -@item @code{host} (par défaut : @code{"localhost"}) -L'hôte (et donc, l'interface réseau) sur lequel écouter. Utilisez -@code{"0.0.0.0"} pour écouter sur toutes les interfaces réseaux. - -@item @code{compression-level} (par défaut : @code{3}) -Le niveau de compression gzip auquel les substituts sont compressés. -Utilisez @code{0} pour désactiver complètement la compression, et @code{9} -pour avoir le meilleur taux de compression contre une plus grande -utilisation du CPU. - -@item @code{nar-path} (par défaut : @code{"nar"}) -Le chemin d'URL où les « nars » se trouvent. @xref{Invoquer guix publish, -@code{--nar-path}}, pour des détails. - -@item @code{cache} (par défaut : @code{#f}) -Lorsque la valeur est @code{#f}, désactive le cache et génère les archives à -la demande. Sinon, cela devrait être le nom d'un répertoire — p.@: ex.@: -@code{"/var/cache/guix/publish"} — où @command{guix publish} gère le cache -des archives et des métadonnées prêtes à être envoyées. @xref{Invoquer guix publish, @option{--cache}}, pour plus d'informations sur les compromis -impliqués. - -@item @code{workers} (par défaut : @code{#f}) -Lorsque la valeur est un entier, c'est le nombre de threads de travail -utilisés pour le cache ; lorsque la valeur est @code{#f}, le nombre de -processeurs est utilisé. @xref{Invoquer guix publish, @option{--workers}}, -pour plus d'informations. - -@item @code{ttl} (par défaut : @code{#f}) -Lorsque la valeur est un entier, il dénote la @dfn{durée de vie} en secondes -des archives publiées. @xref{Invoquer guix publish, @option{--ttl}}, pour -plus d'informations. -@end table -@end deftp - -@anchor{rngd-service} -@deffn {Procédure Scheme} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] -Renvoie un service qui lance le programme @command{rngd} de @var{rng-tools} -pour ajouter @var{device} à la réserve d'entropie du noyau. Le service -échouera si @var{device} n'existe pas. -@end deffn - -@anchor{pam-limits-service} -@cindex limites de session -@cindex ulimit -@cindex priorités -@cindex temps réel -@cindex jackd -@deffn {Procédure Scheme} pam-limits-service [#:limits @code{'()}] - -Renvoie un service qui installe un fichier de configuration pour le -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, module -@code{pam_limits}}. La procédure prend éventuellement une liste de valeurs -@code{pam-limits-entry} qui peuvent être utilisées pour spécifier les -limites @code{ulimit} et les priorités des sessions utilisateurs. - -La définition de limites suivante défini deux limites matérielles et -logicielles pour toutes les sessions connectées des utilisateurs du groupe -@code{realtime} : - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -La première entrée augment la priorité en temps réel maximale des processus -non privilégiés ; la deuxième entrée abandonne les restrictions sur l'espace -d'adressage maximal qui peut être verrouillé en mémoire. Ces paramètres -sont souvent utilisés sur les systèmes audio temps-réel. -@end deffn - -@node Exécution de tâches planifiées -@subsection Exécution de tâches planifiées - -@cindex cron -@cindex mcron -@cindex tâches planifiées -Le module @code{(gnu services mcron)} fournit une interface pour -GNU@tie{}mcron, un démon qui lance des tâches planifiées (@pxref{Top,,, -mcron, GNU@tie{}mcron}). GNU@tie{}mcron est similaire au démon Unix -traditionnel @command{cron} ; la principale différence est qu'il est -implémenté en Guile Scheme, qui fournit beaucoup de flexibilité lors de la -spécification de la planification des tâches et de leurs actions. - -L'exemple en dessous définit un système d'exploitation qui lance les -commandes @command{updatebd} (@pxref{Invoking updatedb,,, find, Finding -Files}) et @command{guix gc} (@pxref{Invoquer guix gc}) tous les jours, -ainsi que la commande @command{mkid} en tant qu'utilisateur non privilégié -(@pxref{mkid invocation,,, idutils, ID Database Utilities}). Il utilise des -gexps pour introduire des définitions de tâches qui sont passées à mcron -(@pxref{G-Expressions}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define updatedb-job - ;; Lance « updatedb » à 3h du matin chaque jour. Ici nous spécifions - ;; l'action de la tâche comme une procédure Scheme. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define garbage-collector-job - ;; Lance le ramasse-miettes tous les jours à minuit cinq. - ;; L'action de la tâche est une commande shell. - #~(job "5 0 * * *" ;Vixie cron syntax - "guix gc -F 1G")) - -(define idutils-job - ;; Met à jour la base de données d'index en tant que « charlie » à 12h15 - ;; et 19h15. La commande est lancée depuis le répertoire personnel de l'utilisateur. - #~(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}, pour -plus d'informations sur les spécifications des tâche de mcron. Ci-dessous -est la référence du service mcron. - -Sur un système lancé, vous pouvez utiliser l'action @code{schedule} du -service pour visualiser les travaux mcron qui seront exécutés ensuite : - -@example -# herd schedule mcron -@end example - -@noindent -Cet exemple ci-dessus montre les cinq tâches qui seront exécutés, mais vous -pouvez spécifier le nombre de tâches à afficher : - -@example -# herd schedule mcron 10 -@end example - -@defvr {Variable Scheme} mcron-service-type -C'est le type du service @code{mcron}, dont la valeur est un objet -@code{mcron-configuration} - -Ce type de service peut être la cible d'une extension de service qui lui -fournit des spécifications de tâches supplémentaires (@pxref{Composition de services}). En d'autres termes, il est possible de définir des services -qui fournissent des tâches mcron à lancer. -@end defvr - -@deftp {Type de données} mcron-configuration -Type données qui représente la configuration de mcron. - -@table @asis -@item @code{mcron} (par défaut : @var{mcron}) -Le paquet mcron à utiliser. - -@item @code{jobs} -C'est la liste des gexps (@pxref{G-Expressions}), où chaque gexp correspond -à une spécification de tâche de mcron (@pxref{Syntax, mcron job -specifications,, mcron, GNU@tie{}mcron}). -@end table -@end deftp - - -@node Rotation des journaux -@subsection Rotation des journaux - -@cindex rottlog -@cindex journaux, rotation -@cindex logging -Les fichiers journaux comme ceux qui se trouvent dans @file{/var/log} ont -tendance à grandir sans fin, donc c'est une bonne idée de le @dfn{faire -tourner} de temps à autres — c.-à-d.@: archiver leur contenu dans des -fichiers séparés, potentiellement compressés. Le module @code{(gnu services -admin)} fournit une interface pour GNU@tie{}Rot[t]log, un outil de rotation -de journaux (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}). - -L'exemple ci-dessous définit un système d'exploitation qui fournit la -rotation des journaux avec les paramètres par défaut, pour les journaux les -plus courants. - -@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 {Variable Scheme} rottlog-service-type -C'est le type du service Rotlog, dont la valeur est un objet -@code{rottlog-configuration}. - -D'autres services peuvent étendre celui-ci avec de nouveaux objets -@code{log-rotation} (voir plus bas), en augmentant ainsi l'ensemble des -fichiers à faire tourner. - -Ce type de service peut définir des taches (@pxref{Exécution de tâches planifiées}) -pour lancer le service rottlog. -@end defvr - -@deftp {Type de données} rottlog-configuration -Type de données représentant la configuration de rottlog. - -@table @asis -@item @code{rottlog} (par défaut : @code{rottlog}) -Le paquet Rottlog à utiliser. - -@item @code{rc-file} (par défaut : @code{(file-append rottlog "/etc/rc")}) -Le fichier de configuration Rottlog à utiliser (@pxref{Mandatory RC -Variables,,, rottlog, GNU Rot[t]log Manual}). - -@item @code{rotations} (par défaut : @code{%default-rotations}) -Une liste d'objets @code{log-rotation} définis plus bas. - -@item @code{jobs} -C'est une liste de gexps où chaque gexp correspond à une spécification de -tache de mcron (@pxref{Exécution de tâches planifiées}). -@end table -@end deftp - -@deftp {Type de données} log-rotation -Type de données représentant la rotation d'un groupe de fichiers journaux. - -En reprenant un exemple du manuel de Rottlog (@pxref{Period Related File -Examples,,, rottlog, GNU Rot[t]log Manual}), on peut définir la rotation -d'un journal de cette manière : - -@example -(log-rotation - (frequency 'daily) - (files '("/var/log/apache/*")) - (options '("storedir apache-archives" - "rotate 6" - "notifempty" - "nocompress"))) -@end example - -La liste des champs est la suivante : - -@table @asis -@item @code{frequency} (par défaut : @code{'weekly}) -La fréquence de rotation, un symbole. - -@item @code{files} -La liste des fichiers ou des motifs de noms de fichiers à faire tourner. - -@item @code{options} (par défaut : @code{'()}) -La liste des options de rottlog pour cette rotation (@pxref{Configuration -parameters,,, rottlog, GNU Rot[t]lg Manual}). - -@item @code{post-rotate} (par défaut : @code{#f}) -Soit @code{#f}, soit une gexp à exécuter une fois la rotation terminée. -@end table -@end deftp - -@defvr {Variable Scheme} %default-rotations -Spécifie la rotation hebdomadaire de @var{%rotated-files} et de quelques -autres fichiers. -@end defvr - -@defvr {Variable Scheme} %rotated-files -La liste des fichiers contrôlés par syslog à faire tourner. Par défaut il -s'agit de : @code{'("/var/log/messages" "/var/log/secure")} -@end defvr - -@node Services réseau -@subsection Services réseau - -Le module @code{(gnu services networking)} fournit des services pour -configurer les interfaces réseaux. - -@cindex DHCP, service réseau -@defvr {Variable Scheme} dhcp-client-service-type -C'est le type de services qui lance @var{dhcp}, un client DHC (protocole de -configuration d'hôte dynamique) sur toutes les interfaces réseau -non-loopback. Sa valeur est le paquet du client DHCP à utiliser, -@code{isc-dhcp} par défaut. -@end defvr - -@deffn {Procédure Scheme} dhcpd-service-type -Ce type définie un service qui lance un démon DHCP. Pour créer un service -de ce type, vous devez appliquer un objet @code{}. Par -exemple : - -@example -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "my-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end example -@end deffn - -@deftp {Type de données} dhcpd-configuration -@table @asis -@item @code{package} (par défaut : @code{isc-dhcp}) -Le paquet qui fournit le démon DHCP. ce paquet doit fournir le démon -@file{sbin/dhcpd} relativement à son répertoire de sortie. Le paquet par -défaut est le @uref{http://www.isc.org/products/DHCP, serveur DHCP d'ISC} -@item @code{config-file} (par défaut : @code{#f}) -Le fichier de configuration à utiliser. Il est requis. Il sera passé à -@code{dhcpd} via son option @code{-cf}. La valeur peut être n'importe quel -objet « simili-fichier » (@pxref{G-Expressions, file-like objects}). Voir -@code{man dhcpd.conf} pour des détails sur la syntaxe du fichier de -configuration. -@item @code{version} (par défaut : @code{"4"}) -La version de DHCP à utiliser. Le serveur DHCP d'ISC supporte les valeur « -4 », « 6 » et « 4o6 ». Elles correspondent aux options @code{-4}, @code{-6} -et @code{-4o6} du programme @code{dhcpd}. Voir @code{man dhcpd} pour plus -de détails. -@item @code{run-directory} (par défaut : @code{"/run/dhcpd"}) -Le répertoire d'exécution à utiliser. Au moment de l'activation du service, -ce répertoire sera créé s'il n'existe pas. -@item @code{pid-file} (par défaut : @code{"/run/dhcpd/dhcpd.pid"}) -Le fichier de PID à utiliser. Cela correspond à l'option @code{-pf} de -@code{dhcpd}. Voir @code{man dhcpd} pour plus de détails. -@item @code{interfaces} (par défaut : @code{'()}) -Les noms des interfaces réseaux sur lesquelles dhcpd écoute. Si cette liste -n'est pas vide, alors ses éléments (qui doivent être des chaînes de -caractères) seront ajoutés à l'invocation de @code{dhcpd} lors du démarrage -du démon. Il n'est pas forcément nécessaire de spécifier des interfaces ici -; voir @code{man dhcpd} pour plus de détails. -@end table -@end deftp - -@defvr {Variable Scheme} static-networking-service-type -@c TODO Document data structures. -C'est le type des interfaces réseaux configurés statiquement. -@end defvr - -@deffn {Procédure Scheme} static-networking-service @var{interface} @var{ip} @ - [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ -[#:requirement @code{'(udev)}] -Renvoie un service qui démarre @var{interface} avec l'adresse @var{ip}. Si -@var{netmask} est vrai, il sera utilisé comme masque de sous-réseau. Si -@var{gateway} est vrai, ce doit être une chaîne de caractères qui spécifie -la passerelle par défaut du réseau. @var{requirement} peut être utilisé -pour déclarer une dépendance sur un autre service avant de configurer -l'interface. - -On peut appeler cette procédure plusieurs fois, une fois par interface -réseau qui nous intéresse. Dans les coulisses, elle étend -@code{static-networking-service-type} avec les interfaces réseaux -supplémentaires à gérer. - -Par exemple : - -@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 sans-fil -@cindex WiFi -@cindex gestion du réseau -@deffn {Procédure Scheme} wicd-service [#:wicd @var{wicd}] -Renvoie un service qui lance @url{https://launchpad.net/wicd,Wicd}, un démon -de gestion réseau qui cherche à simplifier la configuration des réseaux -filaires et sans fil. - -Ce service ajoute le paquet @var{wicd} au profil global, pour fournir des -commandes pour interagir avec le démon et configurer le réseau : -@command{wicd-client}, une interface graphique et les interfaces -utilisateurs @command{wicd-cli} et @command{wicd-curses}. -@end deffn - -@cindex ModemManager - -@defvr {Variable Scheme} modem-manager-service-type -C'est le type de service pour le service -@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}. La -valeur de ce type de service est un enregistrement -@code{modem-manager-configuration}. - -Ce service fait partie de @code{%desktop-services} (@pxref{Services de bureaux}). -@end defvr - -@deftp {Type de données} modem-manager-configuration -Type de donnée représentant la configuration de ModemManager. - -@table @asis -@item @code{modem-manager} (par défaut : @code{modem-manager}) -Le paquet ModemManager à utiliser. - -@end table -@end deftp - -@cindex NetworkManager - -@defvr {Variable Scheme} network-manager-service-type -C'est le type de service pour le service -@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}. La -valeur pour ce type de service est un enregistrement -@code{network-manager-configuration}. - -Ce service fait partie de @code{%desktop-services} (@pxref{Services de bureaux}). -@end defvr - -@deftp {Type de données} network-manager-configuration -Type de données représentant la configuration de NetworkManager. - -@table @asis -@item @code{network-manager} (par défaut : @code{network-manager}) -Le paquet NetworkManager à utiliser. - -@item @code{dns} (par défaut : @code{"default"}) -Mode de gestion pour le DNS, qui affecte la manière dont NetworkManager -utilise le fichier de configuration @code{resolv.conf} - -@table @samp -@item default -NetworkManager mettra à jour @code{resolv.conf} pour refléter les serveurs -de noms fournis par les connexions actives. - -@item dnsmasq -NetworkManager lancera @code{dnsmasq} en tant que serveur de cache local, en -utilisant une configuration « DNS disjointe » si vous êtes connecté par un -VPN puis mettra à jour @code{resolv.conf} pour pointer vers le serveur de -nom local. - -@item none -NetworkManager ne modifiera pas @code{resolv.conf}. -@end table - -@item @code{vpn-plugins} (par défaut : @code{'()}) -C'est la liste des greffons disponibles pour les VPN (réseaux privés -virtuels). Un exemple est le paquet @code{network-manager-openvpn}, qui -permet à NetworkManager de gérer des VPN via OpenVPN. - -@end table -@end deftp - -@cindex Connman -@deffn {Variable Scheme} connman-service-type -C'est le type de service pour lancer @url{https://01.org/connman,Connman}, -un gestionnaire de connexions réseaux. - -Sa valeur doit être un enregistrement @code{connman-configuration} comme -dans cet exemple : - -@example -(service connman-service-type - (connman-configuration - (disable-vpn? #t))) -@end example - -Voir plus bas pour des détails sur @code{connman-configuration}. -@end deffn - -@deftp {Type de données} connman-configuration -Type de données représentant la configuration de connman. - -@table @asis -@item @code{connman} (par défaut : @var{connman}) -Le paquet connman à utiliser. - -@item @code{disable-vpn?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, désactive le greffon vpn de connman. -@end table -@end deftp - -@cindex WPA Supplicant -@defvr {Variable Scheme} wpa-supplicant-service-type -C'est le type du service qui lance@url{https://w1.fi/wpa_supplicant/,WPA -supplicant}, un démon d'authentification requis pour s'authentifier sur des -WiFi chiffrés ou des réseaux ethernet. -@end defvr - -@deftp {Type de données} wpa-supplicant-configuration -Type données qui représente la configuration de WPA Supplicant. - -Il prend les paramètres suivants : - -@table @asis -@item @code{wpa-supplicant} (par défaut : @code{wpa-supplicant}) -Le paquet WPA Supplicant à utiliser. - -@item @code{dbus?} (par défaut : @code{#t}) -Indique s'il faut écouter les requêtes sur D-Bus. - -@item @code{pid-file} (par défaut : @code{"/var/run/wpa_supplicant.pid"}) -Où stocker votre fichier de PID. - -@item @code{interface} (par défaut : @code{#f}) -Si une valeur est indiquée, elle doit spécifier le nom d'une interface -réseau que WPA supplicant contrôlera. - -@item @code{config-file} (par défaut : @code{#f}) -Fichier de configuration facultatif à utiliser. - -@item @code{extra-options} (par défaut : @code{'()}) -Liste d'arguments de la ligne de commande supplémentaires à passer au démon. -@end table -@end deftp - -@cindex iptables -@defvr {Variable Scheme} iptables-service-type -C'est le type de service pour mettre en place une configuration iptables. -iptables est un outil de filtrage de paquets pris en charge par le noyau -Linux. Ce service prend en charge la configuration d'iptable pour IPv4 et -IPv6. Un exemple de configuration simple, qui rejette les connexions -entrantes sauf celles sur le port 22 est présenté ci-dessous. - -@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 {Type de données} iptables-configuration -Type de données représentant la configuration d'iptables. - -@table @asis -@item @code{iptables} (par défaut : @code{iptables}) -Le paquet iptables qui fournit @code{iptables-restore} et -@code{ip6tables-restore}. -@item @code{ipv4-rules} (par défaut : @code{%iptables-accept-all-rules}) -Les règles iptables à utiliser. Elles seront passées à -@code{iptables-restore}. Cela peut être un objet « simili-fichier » -(@pxref{G-Expressions, file-like objects}). -@item @code{ipv6-rules} (par défaut : @code{%iptables-accept-all-rules}) -Les règles iptables à utiliser. Elles seront passées à -@code{ip6tables-restore}. Cela peut être un objet « simili-fichier » -(@pxref{G-Expressions, file-like objects}). -@end table -@end deftp - -@cindex NTP (Network Time Protocol), service -@cindex horloge -@defvr {Variable Scheme} ntp-service-type -C'est le type de service qui lance le démon @uref{http://www.ntp.org, -Network Time Protocol (NTP)}, @command{ntpd}. Le démon gardera l'horloge -système synchronisée avec celle des serveurs NTP spécifiés. - -La valeur de ce service est un objet @code{ntpd-configuration}, décrit -ci-dessous. -@end defvr - -@deftp {Type de données} ntp-configuration -C'est le type de données représentant la configuration du service NTP. - -@table @asis -@item @code{servers} (par défaut : @code{%ntp-servers}) -C'est la liste des serveurs (noms d'hôtes) avec lesquels @command{ntpd} sera -synchronisé. - -@item @code{allow-large-adjustment?} (par défaut : @code{#f}) -Détermine si @code{ntpd} peut faire un ajustement initial de plus de -1@tie{}000 secondes. - -@item @code{ntp} (par défaut : @code{ntp}) -Le paquet NTP à utiliser. -@end table -@end deftp - -@defvr {Variable Scheme} %ntp-servers -Liste de noms d'hôtes à utiliser comme serveurs NTP par défaut. Ce sont les -serveurs du @uref{https://www.ntppool.org/fr/, projet NTP Pool} -@end defvr - -@cindex OpenNTPD -@deffn {Procédure Scheme} openntpd-service-type -Lance le démon NTP @command{ntpd}, implémenté par -@uref{http://www.openntpd.org, OpenNTPD}. Le démon gardera l'horloge -système synchronisée avec celle des serveurs donnés. - -@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 {Type de données} openntpd-configuration -@table @asis -@item @code{openntpd} (par défaut : @code{(file-append openntpd "/sbin/ntpd")}) -L'exécutable openntpd à utiliser. -@item @code{listen-on} (par défaut : @code{'("127.0.0.1" "::1")}) -Une liste d'adresses IP locales ou de noms d'hôtes que devrait écouter le -démon ntpd. -@item @code{query-from} (par défaut : @code{'()}) -Une liste d'adresses IP que le démon devrait utiliser pour les requêtes -sortantes. -@item @code{sensor} (par défaut : @code{'()}) -Spécifie une liste de senseurs de différences de temps que ntpd devrait -utiliser. @code{ntpd} écoutera chaque senseur qui existe et ignorera ceux -qui n'existent pas. Voir @uref{https://man.openbsd.org/ntpd.conf, la -documentation en amont} pour plus d'informations. -@item @code{server} (par défaut : @var{%ntp-servers}) -Spécifie une liste d'adresses IP ou de noms d'hôtes de serveurs NTP avec -lesquels se synchroniser. -@item @code{servers} (par défaut : @code{'()}) -Spécifie une liste d'adresses IP ou de noms d'hôtes de banques de serveurs -NTP avec lesquelles se synchroniser. -@item @code{constraint-from} (par défaut : @code{'()}) -@code{ntpd} peut être configuré pour demander la « Date » à des serveurs -HTTPS de confiance via TLS. Cette information de temps n'est pas utilisée -pour sa précision mais agit comme une contrainte authentifiée, ce qui réduit -l'impact d'une attaque par l'homme du milieu sur le protocole NTP non -authentifié. Spécifie une liste d'URL, d'adresses IP ou de noms d'hôtes de -serveurs HTTPS qui fournissent cette contrainte. -@item @code{constraints-from} (par défaut : @code{'()}) -Comme pour @code{constraint-from}, spécifie une liste d'URL, d'adresses IP -ou de noms d'hôtes de serveurs HTTPS qui fournissent une contrainte. Si les -noms d'hôtes sont résolus en plusieurs adresses IP, @code{ntpd} calculera la -contrainte médiane. -@item @code{allow-large-adjustment?} (par défaut : @code{#f}) -Détermine si @code{ntpd} peut faire un ajustement initial de plus de 180 -secondes. -@end table -@end deftp - -@cindex inetd -@deffn {Variable Scheme} inetd-service-type -Ce service lance le démon @command{inetd} (@pxref{inetd invocation,,, -inetutils, GNU Inetutils}). @command{inetd} écoute des connexions sur des -sockets internet et démarre le programme spécifié uniquement lorsqu'une -connexion arrive sur l'un de ces sockets. - -La valeur de ce service est un objet @code{inetd-configuration}. L'exemple -suivant configure le démon @command{inetd} pour qu'il fournisse le service -@command{echo}, ainsi qu'un service smtp qui transfère le trafic smtp par -ssh à un serveur @code{smtp-server} derrière une passerelle @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 - -Voir plus bas pour plus de détails sur @code{inetd-configuration}. -@end deffn - -@deftp {Type de données} inetd-configuration -Type de données représentant la configuration de @command{inetd}. - -@table @asis -@item @code{program} (par défaut : @code{(file-append inetutils "/libexec/inetd")}) -L'exécutable @command{inetd} à utiliser. - -@item @code{entries} (par défaut : @code{'()}) -Une liste d'entrées de services @command{inetd}. Chaque entrée devrait être -crée avec le constructeur @code{inetd-entry}. -@end table -@end deftp - -@deftp {Type de données} inetd-entry -Type de données représentant une entrée dans la configuration -d'@command{inetd}. Chaque entrée correspond à un socket sur lequel -@command{inetd} écoutera les requêtes. - -@table @asis -@item @code{node} (par défaut : @code{#f}) -Chaîne de caractères facultative, un liste d'adresses locales séparées par -des virgules que @command{inetd} devrait utiliser pour écouter ce service. -@xref{Configuration file,,, inetutils, GNU Inetutils} pour une description -complète de toutes les options. -@item @code{name} -Une chaîne de caractères dont le nom doit correspondre à une entrée de -@code{/etc/services}. -@item @code{socket-type} -Un symbole parmi @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} ou -@code{'seqpacket}. -@item @code{protocol} -Une chaîne de caractères qui doit correspondre à une entrée dans -@code{/etc/protocols}. -@item @code{wait?} (par défaut : @code{#t}) -Indique si @command{inetd} devrait attendre que le serveur ait quitté avant -d'écouter de nouvelles demandes de service. -@item @code{user} -Une chaîne de caractères contenant le nom d'utilisateur (et éventuellement -de groupe) de l'utilisateur en tant que lequel le serveur devrait tourner. -Le nom du groupe peut être spécifié comme un suffixe, séparé par un -deux-points ou un point, c.-à-d.@: @code{"utilisateur"}, -@code{"utilisateur:groupe"} ou @code{"utilisateur.groupe"}. -@item @code{program} (par défaut : @code{"internal"}) -Le programme du serveur qui servira les requêtes, ou @code{"internal"} si -@command{inetd} devrait utiliser un service inclus. -@item @code{arguments} (par défaut : @code{'()}) -Une liste de chaînes de caractères ou d'objets simili-fichiers qui sont les -arguments du programme du serveur, en commençant par le zéroième argument, -c.-à-d.@: le nom du programme lui-même. Pour les services internes à -@command{inetd}, cette entrée doit être @code{'()} ou @code{'("internal")}. -@end table - -@xref{Configuration file,,, inetutils, GNU Inetutils} pour trouver une -discussion plus détaillée de chaque champ de configuration. -@end deftp - -@cindex Tor -@defvr {Variable Scheme} tor-service-type -C'est le type pour un service qui lance le démon de navigation anonyme -@uref{https://torproject.org, Tor}. Le service est configuré avec un -enregistrement @code{}. Par défaut, le démon Tor est -lancé en tant qu'utilisateur non privilégié @code{tor}, membre du groupe -@code{tor}. - -@end defvr - -@deftp {Type de données} tor-configuration -@table @asis -@item @code{tor} (par défaut : @code{tor}) -Le paquet qui fournit le démon Tor. Ce paquet doit fournir le démon -@file{bin/tor} relativement à son répertoire de sortie. Le paquet par -défaut est le l'implémentation du @uref{https://www.torproject.org, projet -Tor}. - -@item @code{config-file} (par défaut : @code{(plain-file "empty" "")}) -Le fichier de configuration à utiliser. Il sera ajouté au fichier de -configuration par défaut, et le fichier de configuration final sera passé à -@code{tor} via son option @code{-f}. Cela peut être n'importe quel objet « -simili-fichier » (@pxref{G-Expressions, file-like objects}). Voir @code{man -tor} pour plus de détails sur la syntaxe du fichier de configuration. - -@item @code{hidden-services} (par défaut : @code{'()}) -La liste des enregistrements @code{} à utiliser. Pour -n'importe quel service cache que vous ajoutez à cette liste, la -configuration appropriée pour activer le service caché sera automatiquement -ajouté au fichier de configuration par défaut. Vous pouvez aussi créer des -enregistrements @code{} avec la procédure -@code{tor-hidden-service} décrite plus bas. - -@item @code{socks-socket-type} (par défaut : @code{'tcp}) -Le type de socket par défaut que Tor devrait utiliser pour les socket -SOCKS. Cela doit être soit @code{'tcp} soit @code{'unix}. S'il s'agit de -@code{'tcp}, alors Tor écoutera pas défaut sur le port TCP 9050 sur -l'interface de boucle locale (c.-à-d.@: localhost). S'il s'agit de -@code{'unix}, Tor écoutera sur le socket UNIX domain -@file{/var/run/tor/socks-sock}, qui sera inscriptible pour les membres du -groupe @code{tor}. - -Si vous voulez personnaliser le socket SOCKS plus avant, laissez -@code{socks-socket-type} à sa valeur par défaut de @code{'tcp} et utilisez -@code{config-file} pour remplacer les valeurs par défaut avec votre propre -option @code{SocksPort}. -@end table -@end deftp - -@cindex service caché -@deffn {Procédure Scheme} tor-hidden-service @var{name} @var{mapping} -Définie un @dfn{service caché} pour Tor nommé @var{name} qui implémente -@var{mapping}. @var{mapping} est une liste de paires de port et d'hôte, -comme dans : - -@example - '((22 "127.0.0.1:22") - (80 "127.0.0.1:8080")) -@end example - -Dans cet exemple, le port 22 du service caché est relié au port local 22 et -le port 80 est relié au port local 8080. - -Cela crée un répertoire @file{/var/lib/tor/hidden-services/@var{name}} où le -fichier @file{hostname} contient le nom d'hôte @code{.onion} pour le service -caché. - -Voir @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the -Tor project's documentation} pour trouver plus d'information. -@end deffn - -Le module @code{(gnu services rsync)} fournit les services suivant : - -Vous pourriez vouloir un démon rsync si vous voulez que des fichiers soient -disponibles pour que n'importe qui (ou juste vous) puisse télécharger des -fichiers existants ou en téléverser des nouveaux. - -@deffn {Variable Scheme} rsync-service-type -C'est le type pour le démon @uref{https://rsync.samba.org, rsync}, qui prend -un enregistrement @command{rsync-configuration} comme dans cet exemple : - -@example -(service rsync-service-type) -@end example - -Voir plus pas pour trouver des détails à propos de -@code{rsync-configuration}. -@end deffn - -@deftp {Type de données} rsync-configuration -Type de données représentant la configuration de @code{rsync-service}. - -@table @asis -@item @code{package} (par défaut : @var{rsync}) -Le paquet @code{rsync} à utiliser. - -@item @code{port-number} (par défaut : @code{873}) -Le port TCP sur lequel @command{rsync} écoute les connexions entrantes. Si -le port est inférieur à @code{1024}, @command{rsync} doit être démarré en -tant qu'utilisateur et groupe @code{root}. - -@item @code{pid-file} (par défaut : @code{"/var/run/rsyncd/rsyncd.pid"}) -Nom du fichier où @command{rsync} écrit son PID. - -@item @code{lock-file} (par défaut : @code{"/var/run/rsyncd/rsyncd.lock"}) -Nom du fichier où @command{rsync} écrit son fichier de verrouillage. - -@item @code{log-file} (par défaut : @code{"/var/log/rsyncd.log"}) -Nom du fichier où @command{rsync} écrit son fichier de journal. - -@item @code{use-chroot?} (par défaut : @var{#t}) -S'il faut utiliser un chroot pour le répertoire partagé de @command{rsync}. - -@item @code{share-path} (par défaut : @file{/srv/rsync}) -Emplacement du répertoire partagé de @command{rsync}. - -@item @code{share-comment} (par défaut : @code{"Rsync share"}) -Commentaire du répertoire partagé de @command{rsync}. - -@item @code{read-only?} (par défaut : @var{#f}) -Permission en écriture sur le répertoire partagé. - -@item @code{timeout} (par défaut : @code{300}) -Délai d'attente d'entrée-sortie en secondes. - -@item @code{user} (par défaut : @var{"root"}) -Propriétaire du processus @code{rsync}. - -@item @code{group} (par défaut : @var{"root"}) -Groupe du processus @code{rsync}. - -@item @code{uid} (par défaut : @var{"rsyncd"}) -Nom d'utilisateur ou ID utilisateur en tant que lequel les transferts de -fichiers ont lieu si le démon a été lancé en @code{root}. - -@item @code{gid} (par défaut : @var{"rsyncd"}) -Nom du groupe ou ID du groupe qui sera utilisé lors de l'accès au module. - -@end table -@end deftp - -En plus, @code{(gnu services ssh)} fournit les services suivant. -@cindex SSH -@cindex serveur SSH - -@deffn {Procédure Scheme} 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] -Lance le programme @command{lshd} de @var{lsh} pour écouter sur le port -@var{port-number}. @var{host-key} doit désigner un fichier contenant la -clef d'hôte et ne doit être lisible que par root. - -Lorsque @var{daemonic?} est vrai, @command{lshd} se détachera du terminal -qui le contrôle et enregistrera ses journaux avec syslogd, à moins que -@var{syslog-output?} ne soit faux. Évidemment, cela rend aussi lsh-service -dépendant de l'existence d'un service syslogd. Lorsque @var{pid-file?} est -vrai, @command{lshd} écrit son PID dans le fichier @var{pid-file}. - -Lorsque @var{initialize?} est vrai, la graine et la clef d'hôte seront créés -lors de l'activation du service s'ils n'existent pas encore. Cela peut -prendre du temps et demande une interaction. - -Lorsque @var{initialize?} est faux, c'est à l'utilisateur d'initialiser le -générateur d'aléatoire (@pxref{lsh-make-seed,,, lsh, LSH Manual}) et de crée -une paire de clefs dont la clef privée sera stockée dans le fichier -@var{host-key} (@pxref{lshd basics,,, lsh, LSH Manual}). - -Lorsque @var{interfaces} est vide, lshd écoute les connexions sur toutes les -interfaces réseau ; autrement, @var{interfaces} doit être une liste de noms -d'hôtes et d'adresses. - -@var{allow-empty-passwords?} spécifie si les connexions avec des mots de -passes vides sont acceptés et @var{root-login?} spécifie si la connexion en -root est acceptée. - -Les autres options devraient être évidentes. -@end deffn - -@cindex SSH -@cindex serveur SSH -@deffn {Variable Scheme} openssh-service-type -C'est le type pour le démon ssh @uref{http://www.openssh.org, OpenSSH}, -@command{sshd}. Sa valeur doit être un enregistrement -@code{openssh-configuration} comme dans cet exemple : - -@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 - -Voir plus bas pour trouver des détails sur @code{openssh-configuration}. - -Ce service peut être étendu avec des clefs autorisées supplémentaires, comme -dans cet exemple : - -@example -(service-extension openssh-service-type - (const `(("charlie" - ,(local-file "charlie.pub"))))) -@end example -@end deffn - -@deftp {Type de données} openssh-configuration -C'est l'enregistrement de la configuration de la commande @command{sshd} -d'OpenSSH. - -@table @asis -@item @code{pid-file} (par défaut : @code{"/var/run/sshd.pid"}) -Nom du fichier où @command{sshd} écrit son PID. - -@item @code{port-number} (par défaut : @code{22}) -Port TCP sur lequel @command{sshd} écoute les connexions entrantes. - -@item @code{permit-root-login} (par défaut : @code{#f}) -Ce champ détermine si et quand autoriser les connexions en root. Si la -valeur est @code{#f}, les connexions en root sont désactivées ; si la valeur -est @code{#t}, elles sont autorisées. S'il s'agit du symbole -@code{'without-password}, alors les connexions root sont autorisées mais pas -par une authentification par mot de passe. - -@item @code{allow-empty-passwords?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, les utilisateurs avec un mot de passe vide -peuvent se connecter. Sinon, ils ne peuvent pas. - -@item @code{password-authentication?} (par défaut : @code{#t}) -Lorsque la valeur est vraie, les utilisateurs peuvent se connecter avec leur -mot de passe. Sinon, ils doivent utiliser une autre méthode -d'authentification. - -@item @code{public-key-authentication?} (par défaut : @code{#t}) -Lorsque la valeur est vraie, les utilisateurs peuvent se connecter avec leur -clef publique. Sinon, les utilisateurs doivent utiliser une autre méthode -d'authentification. - -Les clefs publiques autorisées sont stockées dans -@file{~/.ssh/authorized_keys}. Ce n'est utilisé que par le protocole -version 2. - -@item @code{x11-forwarding?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, le transfert de connexion du client graphique -X11 est activé — en d'autre termes, les options @option{-X} et @option{-Y} -de @command{ssh} fonctionneront. - -@item @code{allow-agent-forwarding?} (par défaut : @code{#t}) -Indique s'il faut autoriser la redirection d'agent. - -@item @code{allow-tcp-forwarding?} (par défaut : @code{#t}) -Indique s'il faut autoriser la redirection TCP. - -@item @code{gateway-ports?} (par défaut : @code{#f}) -Indique s'il faut autoriser les ports de passerelle. - -@item @code{challenge-response-authentication?} (par défaut : @code{#f}) -Spécifie si l'authentification par défi est autorisée (p.@: ex.@: via PAM). - -@item @code{use-pam?} (par défaut : @code{#t}) -Active l'interface avec le module d'authentification greffable, PAM. Si la -valeur est @code{#t}, cela activera l'authentification PAM avec -@code{challenge-response-authentication?} et -@code{password-authentication?}, en plus des modules de compte et de session -de PAM pour tous les types d'authentification. - -Comme l'authentification par défi de PAM sert généralement un rôle -équivalent à l'authentification par mot de passe, vous devriez désactiver -soit @code{challenge-response-authentication?}, soit -@code{password-authentication?}. - -@item @code{print-last-log?} (par défaut : @code{#t}) -Spécifie si @command{sshd} devrait afficher la date et l'heure de dernière -connexion des utilisateurs lorsqu'un utilisateur se connecte de manière -interactive. - -@item @code{subsystems} (par défaut : @code{'(("sftp" "internal-sftp"))}) -Configure les sous-systèmes externes (p.@: ex.@: le démon de transfert de -fichiers). - -C'est une liste de paires, composées chacune du nom du sous-système et d'une -commande (avec éventuellement des arguments) à exécuter à la demande du -sous-système. - -La commande @command{internal-sftp} implémente un serveur SFTP dans le -processus. Autrement, on peut spécifier la commande @command{sftp-server} : -@example -(service openssh-service-type - (openssh-configuration - (subsystems - `(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) -@end example - -@item @code{accepted-environment} (par défaut : @code{'()}) -Liste de chaînes de caractères qui décrivent les variables d'environnement -qui peuvent être exportées. - -Chaque chaîne a sa propre ligne. Voir l'option @code{AcceptEnv} dans -@code{man sshd_config}. - -Cet exemple permet aux clients ssh d'exporter la variable @code{COLORTERM}. -Elle est initialisée par les émulateurs de terminaux qui supportent les -couleurs. Vous pouvez l'utiliser dans votre fichier de ressource de votre -shell pour activer les couleurs sur la ligne de commande si cette variable -est initialisée. - -@example -(service openssh-service-type - (openssh-configuration - (accepted-environment '("COLORTERM")))) -@end example - -@item @code{authorized-keys} (par défaut : @code{'()}) -@cindex clefs autorisées, SSH -@cindex SSH, clefs autorisées -C'est la liste des clefs autorisées. Chaque élément de la liste est un nom -d'utilisateur suivit d'un ou plusieurs objets simili-fichiers qui -représentent les clefs publiques SSH. Par exemple : - -@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 -enregistre les clefs publiques spécifiées pour les comptes @code{rekado}, -@code{chris} et @code{root}. - -Des clefs autorisées supplémentaires peuvent être spécifiées via -@code{service-extension}. - -Remarquez que cela n'interfère @emph{pas} avec l'utilisation de -@file{~/.ssh/authorized_keys}. - -@item @code{log-level} (par défaut : @code{'info}) -C'est le symbole qui spécifie le niveau de journalisation : @code{quiet}, -@code{fatal}, @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. -Voir la page de manuel de @file{sshd_config} pour trouver la liste complète -des noms de niveaux. - -@item @code{extra-content} (par défaut : @code{""}) -Ce champ peut être utilisé pour ajouter un texte arbitraire au fichier de -configuration. C'est particulièrement utile pour des configurations -élaborées qui ne pourraient pas être exprimées autrement. Cette -configuration, par exemple, désactiverait les connexions en root, mais les -permettrait depuis une adresse IP spécifique : - -@example -(openssh-configuration - (extra-content "\ -Match Address 192.168.0.1 - PermitRootLogin yes")) -@end example - -@end table -@end deftp - -@deffn {Procédure Scheme} dropbear-service [@var{config}] -Lance le @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,démon SSH -Dropbear} avec la configuration @var{config} donnée, un objet -@code{}. - -Par exemple, pour spécifier un service Dropbear qui écoute sur le port 1234, -ajoutez cet appel au champ @code{services} de votre système d'exploitation : - -@example -(dropbear-service (dropbear-configuration - (port-number 1234))) -@end example -@end deffn - -@deftp {Type de données} dropbear-configuration -Ce type de données représente la configuration d'un démon SSH Dropbear. - -@table @asis -@item @code{dropbear} (par défaut : @var{dropbear}) -Le paquet Dropbear à utiliser. - -@item @code{port-number} (par défaut : 22) -Le port TCP sur lequel le démon attend des connexions entrantes. - -@item @code{syslog-output?} (par défaut : @code{#t}) -Indique s'il faut activer la sortie vers syslog. - -@item @code{pid-file} (par défaut : @code{"/var/run/dropbear.pid"}) -Nom du fichier de PID du démon. - -@item @code{root-login?} (par défaut : @code{#f}) -Indique s'il faut autoriser les connexions en @code{root}. - -@item @code{allow-empty-passwords?} (par défaut : @code{#f}) -Indique s'il faut autoriser les mots de passes vides. - -@item @code{password-authentication?} (par défaut : @code{#t}) -Indique s'il faut autoriser l'authentification par mot de passe. -@end table -@end deftp - -@defvr {Variable Scheme} %facebook-host-aliases -Cette variable contient une chaîne de caractères à utiliser dans -@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference -Manual}). Chaque ligne contient une entrée qui fait correspondre les noms -des serveurs connus du service en ligne Facebook — p.@: ex.@: -@code{www.facebook.com} — à l'hôte local — @code{127.0.0.1} ou son -équivalent en IPv6, @code{::1}. - -Cette variable est typiquement utilisée dans le champ @code{hosts-file} -d'une déclaration @code{operating-system} (@pxref{Référence de système d'exploitation, @file{/etc/hosts}}) : - -@example -(use-modules (gnu) (guix)) - -(operating-system - (host-name "mamachine") - ;; ... - (hosts-file - ;; Crée un fichier /etc/hosts avec des alias pour « localhost » - ;; et « mamachine », ainsi que pour les serveurs de Facebook. - (plain-file "hosts" - (string-append (local-host-aliases host-name) - %facebook-host-aliases)))) -@end example - -Ce mécanisme peut éviter que des programmes qui tournent localement, comme -des navigateurs Web, ne se connectent à Facebook. -@end defvr - -Le module @code{(gnu services avahi)} fourni la définition suivante. - -@defvr {Variable Scheme} avahi-service-type -C'est le service qui lance @command{avahi-daemon}, un service système qui -répond aux requêtes mDNS/DNS-SD qui permet la découverte de service et la -recherche de nom en « zéro configuration » (voir @uref{http://avahi.org/}). -Sa valeur doit être un enregistrement @code{zero-configuration} — voir plus -bas. - -Ce service étend le démon de cache de services de noms (nscd) pour qu'il -puisse résoudre les noms d'hôtes en @code{.local} avec -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name Service Switch}, pour plus d'informations sur la résolution des noms d'hôte. - -En plus, cela ajoute le paquet @var{avahi} au profil du système pour que les -commandes comme @command{avahi-browse} soient directement utilisables. -@end defvr - -@deftp {Type de données} avahi-configuration -Type de données représentant la configuration d'Avahi. - -@table @asis - -@item @code{host-name} (par défaut : @code{#f}) -Si la valeur n'est pas @code{#f}, utilise cette valeur comme nom d'hôte à -publier pour la machine ; sinon, utilise le vrai nom d'hôte de la machine. - -@item @code{publish?} (par défaut : @code{#t}) -Lorsque la valeur est vraie, permet la publication sur le réseau (en -diffusion) des noms d'hôtes et des services. - -@item @code{publish-workstation?} (par défaut : @code{#t}) -Lorsque la valeur est vraie, @command{avahi-daemon} publie le nom d'hôte et -l'adresse IP de la machine via mDNS sur le réseau local. Pour voir les noms -d'hôtes publiés sur votre réseau local, vous pouvez lancer : - -@example -avahi-browse _workstation._tcp -@end example - -@item @code{wide-area?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, DNS-SD sur DNS unicast est activé. - -@item @code{ipv4?} (par défaut : @code{#t}) -@itemx @code{ipv6?} (par défaut : @code{#t}) -Ces champs déterminent s'il faut utiliser des socket IPv4/IPv6. - -@item @code{domains-to-browse} (par défaut : @code{'()}) -C'est la liste des domaines sur lesquels naviguer. -@end table -@end deftp - -@deffn {Variable Scheme} openvswitch-service-type -C'est le type du service @uref{http://www.openvswitch.org, Open vSwitch}, -dont la valeur devrait être un objet @code{openvswitch-configuration}. -@end deffn - -@deftp {Type de données} openvswitch-configuration -Type de données représentant la configuration de Open vSwitch, un -commutateur virtuel multiniveaux conçu pour rendre possible l'automatisation -massive des réseaux avec des extensions programmables. - -@table @asis -@item @code{package} (par défaut : @var{openvswitch}) -Objet de paquet de Open vSwitch. - -@end table -@end deftp - -@node Système de fenêtrage X -@subsection Système de fenêtrage X - -@cindex X11 -@cindex Système de fenêtrage X -@cindex gestionnaire de connexion -La prise en chargue du système d'affichage graphique X Window — en -particulier Xorg — est fournit par le module @code{(gnu services xorg)}. -Remarquez qu'il n'y a pas de procédure @code{xorg-service}. À la place, le -serveur X est démarré par le @dfn{gestionnaire de connexion}, par défaut le -gestionnaire d'affichage de GNOME (GDM). - -@cindex GDM -@cindex GNOME, gestionnaire de connexion -GDM permet évidemment aux utilisateurs de se connecter et d'ouvrir un -gestionnaire de fenêtre ou un gestionnaire d'environnement autre que GNOME ; -pour ceux qui utilisent GNOME, GDM est requis pour certaines fonctionnalités -comme l'écran de verrouillage automatique. - -@cindex gestionnaire de fenêtre -Pour utiliser X11, vous devez installer au moins un @dfn{gestionnaire de -fenêtre} — par exemple les paquets @code{windowmaker} ou @code{openbox} — de -préférence en l'ajoutant au champ @code{packages} de votre définition de -système d'exploitation (@pxref{Référence de système d'exploitation, system-wide -packages}). - -@defvr {Variable Scheme} gdm-service-type -C'est le type pour le @uref{https://wiki.gnome.org/Projects/GDM/, -gestionnaire d'affichage de GNOME} (GDM), un programme qui gère les serveurs -d'affichage graphiques et s'occupe de la connexion graphique des -utilisateurs. Sa valeur doit être un @code{gdm-configuration} (voir plus -bas). - -@cindex types de sessions (X11) -@cindex X11, types de sessions -GDM cherche des @dfn{types de sessions} définies par les fichiers -@file{.desktop} dans @file{/run/current-system/profile/share/xsessions} et -permet aux utilisateurs de choisir une session depuis l'écran de connexion. -Les paquets comme @code{gnmoe}, @code{xfce} et @code{i3} fournissent des -fichiers @file{.desktop} ; les ajouter à l'ensemble des paquets du système -les rendra automatiquement disponibles sur l'écran de connexion. - -En plus, les fichiers @file{~/.xsession} sont honorées. Lorsqu'il est -disponible, @file{~/.xsession} doit être un fichier exécutable qui démarre -un gestionnaire de fenêtre au un autre client X. -@end defvr - -@deftp {Type de données} gdm-configuration -@table @asis -@item @code{auto-login?} (par défaut : @code{#f}) -@itemx @code{default-user} (par défaut : @code{#f}) -Lorsque @code{auto-login?} est faux, GDM présente un écran de connexion. - -Lorsque @code{auto-login?} est vrai, GDM se connecte directement en tant que -@code{default-user}. - -@item @code{gnome-shell-assets} (par défaut : …) -Liste de données requises par GDM : un thème d'icônes, des polices, etc. - -@item @code{xorg-configuration} (par défaut : @code{(xorg-configuration)}) -Configuration du serveur graphique Xorg. - -@item @code{xsession} (par défaut : @code{xinitrc}) -Le script à lancer avant de démarrer une session X. - -@item @code{dbus-daemon} (par défaut : @code{dbus-daemon-wrapper}) -Nom du fichier de l'exécutable @code{dbus-daemon}. - -@item @code{gdm} (par défaut : @code{gdm}) -Le paquet GDM à utiliser. -@end table -@end deftp - -@defvr {Variable Scheme} slim-service-type -C'est de type pour le gestionnaire de connexion graphique SLiM pour X11. - -Comme GDM, SLiM recherche des types de sessions décrites par des fichiers -@file{.desktop} et permet aux utilisateurs de choisir une session à partir -de l'écran de connexion avec @kbd{F1}. Il comprend aussi les fichiers -@file{~/.xsession}. -@end defvr - -@deftp {Type de données} slim-configuration -Type de données représentant la configuration de @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (par défaut : @code{#t}) -S'il faut autoriser les connexions avec un mot de passe vide. - -@item @code{auto-login?} (par défaut : @code{#f}) -@itemx @code{default-user} (par défaut : @code{""}) -Lorsque @code{auto-login?} est faux, SLiM présent un écran de connexion. - -Lorsque @code{auto-login?} est vrai, SLiM se connecte directement en tant -que @code{default-user}. - -@item @code{theme} (par défaut : @code{%default-slim-theme}) -@itemx @code{theme-name} (par défaut : @code{%default-slim-theme-name}) -Le thème graphique à utiliser et son nom. - -@item @code{auto-login-session} (par défaut : @code{#f}) -Si la valeur est vraie, elle doit être le nom d'un exécutable à démarrer -comme session par défaut — p.@: ex.@: @code{(file-append windowmaker -"/bin/windowmaker")}. - -Si la valeur est fausse, une session décrite par l'un des fichiers -@file{.desktop} disponibles dans @code{/run/current-system/profile} et -@code{~/.guix-profile} sera utilisée. - -@quotation Remarque -Vous devez installer au moins un gestionnaire de fenêtres dans le profil du -système ou dans votre profil utilisateur. Sinon, si -@code{auto-login-session} est faux, vous ne serez jamais capable de vous -connecter. -@end quotation - -@item @code{xorg-configuration} (par défaut : @code{(xorg-configuration)}) -Configuration du serveur graphique Xorg. - -@item @code{xauth} (par défaut : @code{xauth}) -Le paquet XAuth à utiliser. - -@item @code{shepherd} (par défaut : @code{shepherd}) -Le paquet Shepherd à utiliser pour invoquer @command{halt} et -@command{reboot}. - -@item @code{sessreg} (par défaut : @code{sessreg}) -Le paquet sessreg à utiliser pour enregistrer la session. - -@item @code{slim} (par défaut : @code{slim}) -Le paquet SLiM à utiliser. -@end table -@end deftp - -@defvr {Variable Scheme} %default-theme -@defvrx {Variable Scheme} %default-theme-name -Le thème SLiM par défaut et son nom. -@end defvr - - -@deftp {Type de données} sddm-configuration -C'est le type de données représentant la configuration du service sddm. - -@table @asis -@item @code{display-server} (par défaut : "x11") -Choisit le serveur d'affichage à utiliser pour l'écran d'accueil. Les -valeurs valides sont « x11 » et « wayland ». - -@item @code{numlock} (par défaut : "on") -Les valeurs valides sont « on », « off » ou « none ». - -@item @code{halt-command} (par défaut : @code{#~(string-apppend #$shepherd "/sbin/halt")}) -La commande à lancer à l'arrêt du système. - -@item @code{reboot-command} (par défaut : @code{#~(string-append #$shepherd "/sbin/reboot")}) -La commande à lancer lors du redémarrage du système. - -@item @code{theme} (par défaut : "maldives") -Le thème à utiliser. Les thèmes par défaut fournis par SDDM sont « elarun » -et « maldives ». - -@item @code{themes-directory} (par défaut : "/run/current-system/profile/share/sddm/themes") -Le répertoire où se trouvent les thèmes. - -@item @code{faces-directory} (par défaut : "/run/current-system/profile/share/sddm/faces") -Répertoire où se trouvent les avatars. - -@item @code{default-path} (par défaut : "/run/current-system/profile/bin") -Le PATH par défaut à utiliser. - -@item @code{minimum-uid} (par défaut : 1000) -UID minimum pour être affiché dans SDDM. - -@item @code{maximum-uid} (par défaut : 2000) -UID maximum pour être affiché dans SDDM - -@item @code{remember-last-user?} (par défaut : #t) -S'il faut se rappeler le dernier utilisateur connecté. - -@item @code{remember-last-session?} (par défaut : #t) -S'il faut se rappeler la dernière session. - -@item @code{hide-users} (par défaut : "") -Les noms d'utilisateurs à cacher sur l'écran d'accueil de SDDM. - -@item @code{hide-shells} (par défaut : @code{#~(string-append #$shadow "/sbin/nologin")}) -Les utilisateurs avec les shells listés seront cachés sur l'écran d'accueil -de SDDM. - -@item @code{session-command} (par défaut : @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) -Le script à lancer avant de démarrer une session wayland. - -@item @code{sessions-directory} (par défaut : "/run/current-system/profile/share/wayland-sessions") -Le répertoire où trouver les fichiers .desktop qui démarrent des sessions -wayland. - -@item @code{xorg-configuration} (par défaut : @code{(xorg-configuration)}) -Configuration du serveur graphique Xorg. - -@item @code{xauth-path} (par défaut : @code{#~(string-append #$xauth "/bin/xauth")}) -Chemin vers xauth. - -@item @code{xephyr-path} (par défaut : @code{#~(string-append #$xorg-server "/bin/Xephyr")}) -Chemin vers Xephyr. - -@item @code{xdisplay-start} (par défaut : @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) -Le script à lancer après avoir démarré xorg-server. - -@item @code{xdisplay-stop} (par défaut : @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) -Le script à lancer avant d'arrêter xorg-server. - -@item @code{xsession-command} (par défaut : @code{xinitrc}) -Le script à lancer avant de démarrer une session X. - -@item @code{xsessions-directory} (par défaut : "/run/current-system/profile/share/xsessions") -Répertoire où trouver les fichiers .desktop pour les sessions X. - -@item @code{minimum-vt} (par défaut : 7) -VT minimal à utiliser. - -@item @code{auto-login-user} (par défaut : "") -Utilisateur à utiliser pour la connexion automatique. - -@item @code{auto-login-session} (par défaut : "") -Le fichier desktop à utiliser pour la connexion automatique. - -@item @code{relogin?} (par défaut : #f) -S'il faut se reconnecter après la déconnexion. - -@end table -@end deftp - -@cindex gestionnaire de connexion -@cindex connexion X11 -@deffn {Procédure Scheme} sddm-service config -Renvoie un service qui démarre le gestionnaire de connexion graphique SDDM -avec une configuration de type @code{}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@cindex Xorg, configuration -@deftp {Type de données} xorg-configuration -Ce type de données représente la configuration du serveur d'affichage -graphique Xorg. Remarquez qu'il ne s'agit pas d'un service Xorg ; à la -place, le serveur X est démarré par un « gestionnaire d'affichage graphique -» comme GDM, SDDM et SLiM. Ainsi, la configuration de ces gestionnaires -d'affichage agrègent un enregistrement @code{xorg-configuration}. - -@table @asis -@item @code{modules} (par défaut : @code{%default-xorg-modules}) -C'est une liste de @dfn{paquets de module} chargés par le serveur Xorg — -p.@: ex.@: @code{xf86-video-vesa}, @code{xf86-input-keyboard} etc. - -@item @code{fonts} (par défaut : @code{%default-xorg-fonts}) -C'est une liste de répertoires de polices à ajouter au @dfn{chemin de -polices} du serveur. - -@item @code{drivers} (par défaut : @code{'()}) -Cela doit être soit la liste vide, auquel cas Xorg choisit un pilote -graphique automatiquement, soit une liste de noms de pilotes qui seront -essayés dans cet ordre — p.@: ex.@: @code{("modesetting" "vesa")} - -@item @code{resolutions} (par défaut : @code{'()}) -Lorsque @code{resolutions} est la liste vide, Xorg choisit une résolution -d'écran appropriée. Sinon, il doit s'agir d'une liste de résolutions — p.@: -ex.@: @code{((1024 768) (640 480))} - -@cindex disposition du clavier, pour Xorg -@cindex disposition des touches, Xorg -@item @code{keyboard-layout} (par défaut : @code{#f}) -Si la valeur est @code{#f}, Xorg utilise la disposition du clavier par -défaut — habituellement la disposition anglaise américaine (« qwerty ») pour -un clavier de PC à 105 touches. - -Sinon cela doit être un objet @code{keyboard-layout} spécifiant la -disposition du clavier à utiliser lorsque Xorg tourne. @xref{Disposition du clavier} pour plus d'informations sur la manière de spécifier la disposition -du clavier. - -@item @code{extra-config} (par défaut : @code{'()}) -C'est une liste de chaînes de caractères ou d'objets ajoutés au fichier de -configuration. Elle est utile pour ajouter du texte supplémentaire -directement dans le fichier de configuration. - -@item @code{server} (par défaut : @code{xorg-server}) -C'est le paquet fournissant le serveur Xorg. - -@item @code{server-arguments} (par défaut : @code{%default-xorg-server-arguments}) -Liste d'arguments de la ligne de commande supplémentaires à passer au -serveur X. La valeur par défaut est @code{-nolisten tcp}. -@end table -@end deftp - -@deffn {Procédure Scheme} set-xorg-configuration @var{config} @ - [@var{login-manager-service-type}] -Dit au gestionnaire de connexion (de type @var{login-manager-service-type}) -d'utiliser @var{config}, un enregistrement . - -Comme la configuration Xog est incluse dans la configuration du gestionnaire -de connexion — p.@: ex.@: @code{gdm-configuration} — cette procédure fournit -un raccourci pour configurer Xorg. -@end deffn - -@deffn {Procédure Scheme} xorg-start-command [@var{config}] -Renvoie un script @code{startx} dans lequel les modules, les polices, etc, -spécifiés dans @var{config} sont disponibles. Le résultat devrait être -utilisé à la place de @code{startx}. - -Habituellement le serveur X est démarré par un gestionnaire de connexion. -@end deffn - - -@deffn {Procédure Scheme} screen-locker-service @var{package} [@var{program}] -Ajoute @var{package}, un paquet pour un verrouiller l'écran ou un -économiseur d'écran dont la commande est @var{program}, à l'ensemble des -programmes setuid et lui ajoute une entrée PAM. Par exemple : - -@lisp -(screen-locker-service xlockmore "xlock") -@end lisp - -rend utilisable le bon vieux XlockMore. -@end deffn - - -@node Services d'impression -@subsection Services d'impression - -@cindex support des imprimantes avec CUPS -Le module @code{(gnu services cups)} fournit une définition de service Guix -pour le service d'impression CUPS. Pour ajouter la prise en charge d'une -imprimante à un système Guix, ajoutez un @code{cups-service} à la définition -du système d'exploitation : - -@deffn {Variable Scheme} cups-service-type -Le type de service pour un serveur d'impression CUPS. Sa valeur devrait -être une configuration CUPS valide (voir plus bas). Pour utiliser les -paramètres par défaut, écrivez simplement : -@example -(service cups-service-type) -@end example -@end deffn - -La configuration de CUPS contrôle les paramètres de base de votre -installation CUPS : sur quelles interfaces il doit écouter, que faire si un -travail échoue, combien de journalisation il faut faire, etc. Pour ajouter -une imprimante, vous devrez visiter l'URL @url{http://localhost:631} ou -utiliser un outil comme les services de configuration d'imprimante de -GNOME. Par défaut, la configuration du service CUPS générera un certificat -auto-signé si besoin, pour les connexions sécurisée avec le serveur -d'impression. - -Supposons que vous souhaitiez activer l'interface Web de CUPS et ajouter le -support pour les imprimantes Epson via le paquet @code{escpr} et pour les -imprimantes HP via le paquet @code{hplip-minimal}. Vous pouvez le faire -directement, comme ceci (vous devez utiliser le module @code{(gnu packages -cups)}) : - -@example -(service cups-service-type - (cups-configuration - (web-interface? #t) - (extensions - (list cups-filters escpr hplip-minimal)))) -@end example - -Remarque : si vous souhaitez utiliser la GUI basée sur Qt5 qui provient du -paquet hplip, nous vous suggérons d'installer le paquet @code{hplip}, soit -dans votre configuration d'OS, soit en tant qu'utilisateur. - -Les paramètres de configuration disponibles sont les suivants. Chaque -définition des paramètres est précédé par son type ; par exemple, -@samp{string-list foo} indique que le paramètre @code{foo} devrait être -spécifié comme une liste de chaînes de caractères. Il y a aussi une manière -de spécifier la configuration comme une chaîne de caractères, si vous avez -un vieux fichier @code{cupsd.conf} que vous voulez porter depuis un autre -système ; voir la fin pour plus de détails. - -@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. - - -Les champs de @code{cups-configuration} disponibles sont : - -@deftypevr {paramètre de @code{cups-configuration}} package cups -Le paquet CUPS. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} package-list extensions -Pilotes et autres extensions du paquet CUPS. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} files-configuration files-configuration -Configuration de l'emplacement où écrire les journaux, quels répertoires -utiliser pour les travaux d'impression et les paramètres de configuration -privilégiés liés. - -Les champs @code{files-configuration} disponibles sont : - -@deftypevr {paramètre de @code{files-configuration}} log-location access-log -Définit le fichier de journal d'accès. Spécifier un nom de fichier vide -désactive la génération de journaux d'accès. La valeur @code{stderr} fait -que les entrées du journal seront envoyés sur l'erreur standard lorsque -l'ordonnanceur est lancé au premier plan ou vers le démon de journal système -lorsqu'il tourne en tache de fond. La valeur @code{syslog} fait que les -entrées du journal sont envoyées au démon de journalisation du système. Le -nom du serveur peut être inclus dans les noms de fichiers avec la chaîne -@code{%s}, comme dans @code{/var/log/cups/%s-access_log}. - -La valeur par défaut est @samp{"/var/log/cups/access_log"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} file-name cache-dir -L'emplacement où CUPS devrait mettre les données en cache. - -La valeur par défaut est @samp{"/var/cache/cups"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string config-file-perm -Spécifie les permissions pour tous les fichiers de configuration que -l'ordonnanceur écrit. - -Remarquez que les permissions pour le fichier printers.conf sont -actuellement masqués pour ne permettre que l'accès par l'utilisateur de -l'ordonnanceur (typiquement root). La raison est que les URI des -imprimantes contiennent des informations d'authentification sensibles qui ne -devraient pas être connues sur le système. Il n'est pas possible de -désactiver cette fonctionnalité de sécurité. - -La valeur par défaut est @samp{"0640"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} log-location error-log -Définit le fichier de journal d'erreur. Spécifier un nom de fichier vide -désactive la génération de journaux d'erreur. La valeur @code{stderr} fait -que les entrées du journal seront envoyés sur l'erreur standard lorsque -l'ordonnanceur est lancé au premier plan ou vers le démon de journal système -lorsqu'il tourne en tache de fond. La valeur @code{syslog} fait que les -entrées du journal sont envoyées au démon de journalisation du système. Le -nom du serveur peut être inclus dans les noms de fichiers avec la chaîne -@code{%s}, comme dans @code{/var/log/cups/%s-error_log}. - -La valeur par défaut est @samp{"/var/log/cups/error_log"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string fatal-errors -Spécifie quelles erreurs sont fatales, qui font terminer l'ordonnanceur. -Les types de chaînes sont : - -@table @code -@item none -Aucune erreur n'est fatale. - -@item all -Toutes les erreurs ci-dessous sont fatales. - -@item browse -Les erreurs d'initialisation de la navigation sont fatales, par exemple les -connexion échouées au démon DNS-SD. - -@item config -Les erreurs de syntaxe du fichier de configuration sont fatale. - -@item listen -Les erreurs d'écoute ou de port sont fatales, sauf pour les erreurs d'IPv6 -sur la boucle locale ou les adresses @code{any}. - -@item log -Les erreurs de création ou d'écriture des fichiers de journal sont fatales. - -@item permissions -Les mauvaises permissions des fichiers de démarrage sont fatales, par -exemple un certificat TLS et des fichiers de clefs avec des permissions -permettant la lecture à tout le monde. -@end table - -La valeur par défaut est @samp{"all -browse"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} boolean file-device? -Spécifie si le fichier de pseudo-périphérique peut être utilisé pour de -nouvelles queues d'impression. L'URI @uref{file:///dev/null} est toujours -permise. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string group -Spécifie le nom ou l'ID du groupe qui sera utilisé lors de l'exécution de -programmes externes. - -La valeur par défaut est @samp{"lp"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string log-file-perm -Spécifie les permissions pour tous les fichiers de journal que -l'ordonnanceur écrit. - -La valeur par défaut est @samp{"0644"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} log-location page-log -Définit le fichier de journal de page. Spécifier un nom de fichier vide -désactive la génération de journaux de pages. La valeur @code{stderr} fait -que les entrées du journal seront envoyés sur l'erreur standard lorsque -l'ordonnanceur est lancé au premier plan ou vers le démon de journal système -lorsqu'il tourne en tache de fond. La valeur @code{syslog} fait que les -entrées du journal sont envoyées au démon de journalisation du système. Le -nom du serveur peut être inclus dans les noms de fichiers avec la chaîne -@code{%s}, comme dans @code{/var/log/cups/%s-page_log}. - -La valeur par défaut est @samp{"/var/log/cups/page_log"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string remote-root -Spécifie le nom d'utilisateur associé aux accès non authentifiés par des -clients qui se disent être l'utilisateur root. La valeur par défaut est -@code{remroot}. - -La valeur par défaut est @samp{"remroot"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} file-name request-root -Spécifie le répertoire qui contient les travaux d'impression et d'autres -données des requêtes HTTP. - -La valeur par défaut est @samp{"/var/spool/cups"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} sandboxing sandboxing -Spécifie le niveau d'isolation de sécurité appliqué aux filtres -d'impression, aux moteurs et aux autres processus fils de l'ordonnanceur ; -soit @code{relaxed} soit @code{strict}. Cette directive n'est actuellement -utilisée et supportée que sur macOS. - -La valeur par défaut est @samp{strict}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} file-name server-keychain -Spécifie l'emplacement des certifications TLS et des clefs privées. CUPS -cherchera les clefs publiques et privées dans ce répertoire : un fichier -@code{.crt} pour un certificat encodé en PEM et le fichier @code{.key} -correspondant pour la clef privée encodée en PEM. - -La valeur par défaut est @samp{"/etc/cups/ssl"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} file-name server-root -Spécifie le répertoire contenant les fichiers de configuration du serveur. - -La valeur par défaut est @samp{"/etc/cups"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} boolean sync-on-close? -Spécifie si l'ordonnanceur appelle fsync(2) après avoir écrit la -configuration ou les fichiers d'état. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} space-separated-string-list system-group -Spécifie le groupe ou les groupes à utiliser pour l'authentification du -groupe @code{@@SYSTEM}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} file-name temp-dir -Spécifie le répertoire où les fichiers temporaires sont stockés. - -La valeur par défaut est @samp{"/var/spool/cups/tmp"}. -@end deftypevr - -@deftypevr {paramètre de @code{files-configuration}} string user -Spécifie le nom d'utilisateur ou l'ID utilisé pour lancer des programmes -externes. - -La valeur par défaut est @samp{"lp"}. -@end deftypevr -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} access-log-level access-log-level -Spécifie le niveau de journalisation pour le fichier AccessLog. Le niveau -@code{config} enregistre les ajouts, suppressions et modifications -d'imprimantes et de classes et lorsque les fichiers de configuration sont -accédés ou mis à jour. Le niveau @code{actions} enregistre la soumission, -la suspension, la libération, la modification et l'annulation des travaux et -toutes les conditions de @code{config}. Le niveau @code{all} enregistre -toutes les requêtes. - -La valeur par défaut est @samp{actions}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean auto-purge-jobs? -Spécifie s'il faut vider l'historique des travaux automatiquement lorsqu'il -n'est plus nécessaire pour les quotas. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} browse-local-protocols browse-local-protocols -Spécifie les protocoles à utiliser pour partager les imprimantes sur le -réseau local. - -La valeur par défaut est @samp{dnssd}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean browse-web-if? -Spécifie si l'interface web de CUPS est publiée. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean browsing? -Spécifie si les imprimantes partagées sont publiées. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string classification -Spécifie la classification de sécurité du serveur. N'importe quel nom de -bannière peut être utilisé, comme « classifié », « confidentiel », « secret -», « top secret » et « déclassifié » ou la bannière peut être omise pour -désactiver les fonctions d'impression sécurisées. - -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean classify-override? -Spécifie si les utilisateurs peuvent remplacer la classification (page de -couverture) des travaux d'impression individuels avec l'option -@code{job-sheets}. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} default-auth-type default-auth-type -Spécifie le type d'authentification par défaut à utiliser. - -La valeur par défaut est @samp{Basic}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} default-encryption default-encryption -Spécifie si le chiffrement sera utilisé pour les requêtes authentifiées. - -La valeur par défaut est @samp{Required}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string default-language -Spécifie la langue par défaut à utiliser pour le contenu textuel et web. - -La valeur par défaut est @samp{"en"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string default-paper-size -Spécifie la taille de papier par défaut pour les nouvelles queues -d'impression. @samp{"Auto"} utilise la valeur par défaut du paramètre de -régionalisation, tandis que @samp{"None"} spécifie qu'il n'y a pas de taille -par défaut. Des noms de tailles spécifique sont par exemple @samp{"Letter"} -et @samp{"A4"}. - -La valeur par défaut est @samp{"Auto"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string default-policy -Spécifie la politique d'accès par défaut à utiliser. - -La valeur par défaut est @samp{"default"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean default-shared? -Spécifie si les imprimantes locales sont partagées par défaut. - -La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer dirty-clean-interval -Spécifie le délai pour mettre à jour les fichiers de configuration et -d'état. Une valeur de 0 fait que la mise à jour arrive aussi vite que -possible, typiquement en quelques millisecondes. - -La valeur par défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} error-policy error-policy -Spécifie ce qu'il faut faire si une erreur a lieu. Les valeurs possibles -sont @code{abort-job}, qui supprimera les travaux d'impression en échec ; -@code{retry-job}, qui tentera de nouveau l'impression plus tard ; -@code{retry-this-job}, qui retentera l'impression immédiatement ; et -@code{stop-printer} qui arrête l'imprimante. - -La valeur par défaut est @samp{stop-printer}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer filter-limit -Spécifie le coût maximum des filtres qui sont lancés en même temps, pour -minimiser les problèmes de ressources de disque, de mémoire et de CPU. Une -limite de 0 désactive la limite de filtrage. Une impression standard vers -une imprimante non-PostScript requiert une limite de filtre d'environ 200. -Une imprimante PostScript requiert environ la moitié (100). Mettre en place -la limite en dessous de ces valeurs limitera l'ordonnanceur à un seul -travail d'impression à la fois. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer filter-nice -Spécifie la priorité des filtres de l'ordonnanceur qui sont lancés pour -imprimer un travail. La valeur va de 0, la plus grande priorité, à 19, la -plus basse priorité. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} host-name-lookups host-name-lookups -Spécifie s'il faut faire des résolutions inverses sur les clients qui se -connectent. Le paramètre @code{double} fait que @code{cupsd} vérifie que le -nom d'hôte résolu depuis l'adresse correspond à l'une des adresses renvoyées -par ce nom d'hôte. Les résolutions doubles évitent aussi que des clients -avec des adresses non enregistrées ne s'adressent à votre serveur. -N'initialisez cette valeur qu'à @code{#t} ou @code{double} que si c'est -absolument nécessaire. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer job-kill-delay -Spécifie le nombre de secondes à attendre avant de tuer les filtres et les -moteurs associés avec un travail annulé ou suspendu. - -La valeur par défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer job-retry-interval -Spécifie l'intervalle des nouvelles tentatives en secondes. C'est -typiquement utilisé pour les queues de fax mais peut aussi être utilisé avec -des queues d'impressions normales dont la politique d'erreur est -@code{retry-job} ou @code{retry-current-job}. - -La valeur par défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer job-retry-limit -Spécifie le nombre de nouvelles tentatives pour les travaux. C'est -typiquement utilisé pour les queues de fax mais peut aussi être utilisé pour -les queues d'impressions dont la politique d'erreur est @code{retry-job} ou -@code{retry-current-job}. - -La valeur par défaut est @samp{5}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean keep-alive? -Spécifie s'il faut supporter les connexion HTTP keep-alive. - -La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer keep-alive-timeout -Spécifie combien de temps les connexions inactives avec les clients restent -ouvertes, en secondes. - -La valeur par défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer limit-request-body -Spécifie la taille maximale des fichiers à imprimer, des requêtes IPP et des -données de formulaires HTML. Une limite de 0 désactive la vérification de -la limite. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} multiline-string-list listen -Écoute sur les interfaces spécifiées. Les valeurs valides sont de la forme -@var{adresse}:@var{port}, où @var{adresse} est soit une adresse IPv6 dans -des crochets, soit une adresse IPv4, soit @code{*} pour indiquer toutes les -adresses. Les valeurs peuvent aussi être des noms de fichiers de socket -UNIX domain. La directive Listen est similaire à la directive Port mais -vous permet de restreindre l'accès à des interfaces ou des réseaux -spécifiques. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer listen-back-log -Spécifie le nombre de connexions en attente qui seront permises. Ça -n'affecte normalement que les serveurs très actifs qui ont atteint la limite -MaxClients, mais peut aussi être déclenché par un grand nombre de connexions -simultanées. Lorsque la limite est atteinte, le système d'exploitation -refusera les connexions supplémentaires jusqu'à ce que l'ordonnanceur -accepte les connexions en attente. - -La valeur par défaut est @samp{128}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} location-access-control-list location-access-controls -Spécifie un ensemble de contrôles d'accès supplémentaires. - -Les champs de @code{location-access-controls} disponibles sont : - -@deftypevr {paramètre de @code{location-access-controls}} file-name path -Spécifie le chemin d'URI auquel les contrôles d'accès s'appliquent. -@end deftypevr - -@deftypevr {paramètre de @code{location-access-controls}} access-control-list access-controls -Les contrôles d'accès pour tous les accès à ce chemin, dans le même format -que le champ @code{access-controls} de @code{operation-access-control}. - -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{location-access-controls}} method-access-control-list method-access-controls -Contrôles d'accès pour les accès spécifiques à la méthode à ce chemin. - -La valeur par défaut est @samp{()}. - -Les champs de @code{method-access-controls} disponibles sont : - -@deftypevr {paramètre de @code{method-access-controls}} boolean reverse? -Si la valeur est @code{#t}, applique les contrôles d'accès à toutes les -méthodes sauf les méthodes listées. Sinon, applique le contrôle uniquement -aux méthodes listées. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{method-access-controls}} method-list methods -Les méthodes auxquelles ce contrôle d'accès s'applique. - -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{method-access-controls}} access-control-list access-controls -Directives de contrôle d'accès, comme une liste de chaînes de caractères. -Chaque chaîne devrait être une directive, comme « Order allow, deny ». - -La valeur par défaut est @samp{()}. -@end deftypevr -@end deftypevr -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer log-debug-history -Spécifie le nombre de messages de débogage qui sont retenu pour la -journalisation si une erreur arrive dans un travail d'impression. Les -messages de débogage sont journalisés indépendamment du paramètre LogLevel. - -La valeur par défaut est @samp{100}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} log-level log-level -Spécifie le niveau de journalisation du fichier ErrorLog. La valeur -@code{none} arrête toute journalisation alors que que @code{debug2} -enregistre tout. - -La valeur par défaut est @samp{info}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} log-time-format log-time-format -Spécifie le format de la date et de l'heure dans les fichiers de journaux. -La valeur @code{standard} enregistre les secondes entières alors que -@code{usecs} enregistre les microsecondes. - -La valeur par défaut est @samp{standard}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-clients -Spécifie le nombre maximum de clients simultanés qui sont autorisés par -l'ordonnanceur. - -La valeur par défaut est @samp{100}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-clients-per-host -Spécifie le nombre maximum de clients simultanés permis depuis une même -adresse. - -La valeur par défaut est @samp{100}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-copies -Spécifie le nombre maximum de copies qu'un utilisateur peut imprimer pour -chaque travail. - -La valeur par défaut est @samp{9999}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-hold-time -Spécifie la durée maximum qu'un travail peut rester dans l'état de -suspension @code{indefinite} avant qu'il ne soit annulé. La valeur 0 -désactive l'annulation des travaux suspendus. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-jobs -Spécifie le nombre maximum de travaux simultanés autorisés. La valeur 0 -permet un nombre illimité de travaux. - -La valeur par défaut est @samp{500}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-jobs-per-printer -Spécifie le nombre maximum de travaux simultanés autorisés par imprimante. -La valeur 0 permet au plus MaxJobs travaux par imprimante. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-jobs-per-user -Spécifie le nombre maximum de travaux simultanés permis par utilisateur. La -valeur 0 permet au plus MaxJobs travaux par utilisateur. - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-job-time -Spécifie la durée maximum qu'un travail peut prendre avant qu'il ne soit -annulé, en secondes. Indiquez 0 pour désactiver l'annulation des travaux « -coincés ». - -La valeur par défaut est @samp{10800}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer max-log-size -Spécifie la taille maximale des fichiers de journaux avant qu'on ne les -fasse tourner, en octets. La valeur 0 désactive la rotation. - -La valeur par défaut est @samp{1048576}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer multiple-operation-timeout -Spécifie la durée maximale à permettre entre les fichiers d'un travail en -contenant plusieurs, en secondes. - -La valeur par défaut est @samp{300}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string page-log-format -Spécifie le format des lignes PageLog. Les séquences qui commencent par un -pourcent (@samp{%}) sont remplacées par l'information correspondante, tandis -que les autres caractères sont copiés littéralement. Les séquences pourcent -suivantes sont reconnues : - -@table @samp -@item %% -insère un seul caractères pourcent - -@item %@{name@} -insère la valeur de l'attribut IPP spécifié - -@item %C -insère le nombre de copies pour la page actuelle - -@item %P -insère le numéro de page actuelle - -@item %T -insère la date et l'heure actuelle dans un format de journal commun - -@item %j -insère l'ID du travail - -@item %p -insère le nom de l'imprimante - -@item %u -insère le nom d'utilisateur -@end table - -Si la valeur est la chaîne vide, le PageLog est désactivée. La chaîne -@code{%p %u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@} -%@{job-name@} %@{media@} %@{sides@}} crée un PageLog avec les entrées -standards. - -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} environment-variables environment-variables -Passe les variables d'environnement spécifiées aux processus fils ; une -liste de chaînes de caractères. - -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} policy-configuration-list policies -Spécifie des politiques de contrôle d'accès nommées. - -Les champs de @code{policy-configuration} disponibles sont : - -@deftypevr {paramètre de @code{policy-configuration}} string name -Nom de la politique. -@end deftypevr - -@deftypevr {paramètre de @code{policy-configuration}} string job-private-access -Spécifie une liste d'accès pour les valeurs privées du travail. -@code{@@ACL} correspond aux valeurs requesting-user-name-allowed ou -requesting-user-name-denied de l'imprimante. @code{@@OWNER} correspond au -propriétaire du travail. @code{@@SYSTEM} correspond aux groupes listés dans -le champ @code{system-group} de la configuration @code{files-config}, qui -est réifié dans le fichier @code{cups-files.conf(5)}. Les autres éléments -possibles de la liste d'accès sont des noms d'utilisateurs spécifiques et -@code{@@@var{group}} pour indiquer les membres d'un groupe spécifique. La -liste d'accès peut aussi être simplement @code{all} ou @code{default}. - -La valeur par défaut est @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {paramètre de @code{policy-configuration}} string job-private-values -Spécifie la liste des valeurs de travaux à rendre privée, ou @code{all}, -@code{default}, ou @code{none}. - -La valeur par défaut est @samp{"job-name job-originating-host-name -job-originating-user-name phone"}. -@end deftypevr - -@deftypevr {paramètre de @code{policy-configuration}} string subscription-private-access -Spécifie un liste d'accès pour les valeurs privées de la souscription. -@code{@@ACL} correspond aux valeurs requesting-user-name-allowed ou -requesting-user-name-denied de l'imprimante. @code{@@OWNER} correspond au -propriétaire du travail. @code{@@SYSTEM} correspond aux groupes listés dans -le champ @code{system-group} de la configuration @code{files-config}, qui -est réifié dans le fichier @code{cups-files.conf(5)}. Les autres éléments -possibles de la liste d'accès sont des noms d'utilisateurs spécifiques et -@code{@@@var{group}} pour indiquer les membres d'un groupe spécifique. La -liste d'accès peut aussi être simplement @code{all} ou @code{default}. - -La valeur par défaut est @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {paramètre de @code{policy-configuration}} string subscription-private-values -Spécifie la liste des valeurs de travaux à rendre privée, ou @code{all}, -@code{default}, ou @code{none}. - -La valeur par défaut est @samp{"notify-events notify-pull-method -notify-recipient-uri notify-subscriber-user-name notify-user-data"}. -@end deftypevr - -@deftypevr {paramètre de @code{policy-configuration}} operation-access-control-list access-controls -Contrôle d'accès par les actions IPP. - -La valeur par défaut est @samp{()}. -@end deftypevr -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean-or-non-negative-integer preserve-job-files -Spécifie si les fichiers de travaux (les documents) sont préservés après -qu'un travail est imprimé. Si une valeur numérique est spécifiée, les -fichiers de travaux sont préservés pour le nombre de secondes indiquées -après l'impression. Sinon, une valeur booléenne s'applique indéfiniment. - -La valeur par défaut est @samp{86400}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean-or-non-negative-integer preserve-job-history -Spécifie si l'historique des travaux est préservé après qu'un travail est -imprimé. Si une valeur numérique est spécifiée, l'historique des travaux -est préservé pour le nombre de secondes indiquées après l'impression. Si la -valeur est @code{#t}, l'historique des travaux est préservé jusqu'à -atteindre la limite MaxJobs. - -La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer reload-timeout -Spécifie la durée d'attente pour la fin des travaux avant de redémarrer -l'ordonnanceur. - -La valeur par défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string rip-cache -Spécifie la quantité de mémoire maximale à utiliser pour convertir des -documents en bitmaps pour l'imprimante. - -La valeur par défaut est @samp{"128m"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string server-admin -Spécifie l'adresse de courriel de l'administrateur système. - -La valeur par défaut est @samp{"root@@localhost.localdomain"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} host-name-list-or-* server-alias -La directive ServerAlias est utilisée pour la validation des en-tête HTTP -Host lorsque les clients se connectent à l'ordonnanceur depuis des -interfaces externes. Utiliser le nom spécial @code{*} peut exposer votre -système à des attaques connues de recombinaison DNS dans le navigateur, même -lorsque vous accédez au site à travers un pare-feu. Si la découverte -automatique des autres noms ne fonctionne pas, nous vous recommandons de -lister chaque nom alternatif avec une directive SeverAlias plutôt que -d'utiliser @code{*}. - -La valeur par défaut est @samp{*}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string server-name -Spécifie le nom d'hôte pleinement qualifié du serveur. - -La valeur par défaut est @samp{"localhost"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} server-tokens server-tokens -Spécifie les informations incluses dans les en-têtes Server des réponses -HTTP. @code{None} désactive l'en-tête Server. @code{ProductOnly} rapporte -@code{CUPS}. @code{Major} rapporte @code{CUPS 2}. @code{Minor} rapporte -@code{CUPS 2.0}. @code{Minimal} rapporte @code{CUPS 2.0.0}. @code{OS} -rapporte @code{CUPS 2.0.0 (@var{uname})} où @var{uname} est la sortie de la -commande @code{uname}. @code{Full} rapporte @code{CUPS 2.0.0 (@var{uname}) -IPP/2.0}. - -La valeur par défaut est @samp{Minimal}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} string set-env -Indique que la variable d'environnement spécifiée doit être passée aux -processus fils. - -La valeur par défaut est @samp{"variable value"}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} multiline-string-list ssl-listen -Écoute des connexions chiffrées sur les interfaces spécifiées. Les valeurs -valides sont de la forme @var{adresse}:@var{port}, où @var{adresse} est soit -une adresse IPv6 dans des crochets, soit une adresse IPv4, soit @code{*} -pour indiquer toutes les interfaces. - -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} ssl-options ssl-options -Indique les options de chiffrement. Par défaut, CUPS ne supporte que le -chiffrement avec TLS 1.0 ou plus avec des suites de chiffrement connues pour -être sures. L'option @code{AllowRC4} active les suites de chiffrement -128-bits RC4, qui sont requises pour certains vieux clients qui -n'implémentent pas les nouvelles. L'option @code{AllowSSL3} active SSL -v3.0, qui est requis par certains vieux clients qui ne supportent pas TLS -v1.0. - -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean strict-conformance? -Spécifie si l'ordonnanceur demande aux clients d'adhérer aux spécifications -IPP. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} non-negative-integer timeout -Spécifie le délai d'attente des requêtes HTTP, en secondes. - -La valeur par défaut est @samp{300}. - -@end deftypevr - -@deftypevr {paramètre de @code{cups-configuration}} boolean web-interface? -Spécifie si l'interface web est activée. - -La valeur par défaut est @samp{#f}. -@end deftypevr - -Maintenant, vous vous dîtes peut-être « oh la la, cher manuel de Guix, je -t'aime bien mais arrête maintenant avec ces options de configuration -»@footnote{NdT : je vous rassure, c'est aussi mon sentiment au moment de -traduire ces lignes. Et pour moi, c'est encore loin d'être fini.}. En -effet. cependant, encore un point supplémentaire : vous pouvez avoir un -fichier @code{cupsd.conf} existant que vous pourriez vouloir utiliser. Dans -ce cas, vous pouvez passer un @code{opaque-cups-configuration} en -configuration d'un @code{cups-service-type}. - -Les champs de @code{opaque-cups-configuration} disponibles sont : - -@deftypevr {paramètre de @code{opaque-cups-configuration}} package cups -Le paquet CUPS. -@end deftypevr - -@deftypevr {paramètre de @code{opaque-cups-configuration}} string cupsd.conf -Le contenu de @code{cupsd.conf}, en tant que chaîne de caractères. -@end deftypevr - -@deftypevr {paramètre de @code{opaque-cups-configuration}} string cups-files.conf -Le contenu du fichier @code{cups-files.conf}, en tant que chaîne de -caractères. -@end deftypevr - -Par exemple, si vos fichiers @code{cupsd.conf} et @code{cups-files.conf} -sont dans des chaînes du même nom, pouvez instancier un service CUPS de -cette manière : - -@example -(service cups-service-type - (opaque-cups-configuration - (cupsd.conf cupsd.conf) - (cups-files.conf cups-files.conf))) -@end example - - -@node Services de bureaux -@subsection Services de bureaux - -Le module @code{(gnu services desktop)} fournit des services qui sont -habituellement utiles dans le contexte d'une installation « de bureau » — -c'est-à-dire sur une machine qui fait tourner un service d'affichage -graphique, éventuellement avec des interfaces utilisateurs graphiques, etc. -Il définit aussi des services qui fournissent des environnements de bureau -spécifiques comme GNOME, Xfce et MATE. - -Pour simplifier les choses, le module définit une variable contenant -l'ensemble des services que les utilisateurs s'attendent en général à avoir -sur une machine avec un environnement graphique et le réseau : - -@defvr {Variable Scheme} %desktop-services -C'est la liste des services qui étend @var{%base-services} en ajoutant ou en -ajustant des services pour une configuration « de bureau » typique. - -En particulier, il ajoute un gestionnaire de connexion graphique (@pxref{Système de fenêtrage X, @code{gdm-service-type}}), des verrouilleurs d'écran, un outil de -gestion réseau (@pxref{Services réseau, -@code{network-manager-service-type}}), des services de gestion de l'énergie -et des couleurs, le gestionnaire de connexion et de session @code{elogind}, -le service de privilèges Polkit, le service de géolocalisation GeoClue, le -démon Accounts Service qui permet aux utilisateurs autorisés de changer les -mots de passe du système, un client NTP (@pxref{Services réseau}), le -démon Avahi, et le service name service switch est configuré pour pouvoir -utiliser @code{nss-mdns} (@pxref{Name Service Switch, mDNS}). -@end defvr - -La variable @var{%desktop-services} peut être utilisée comme champ -@code{services} d'une déclaration @code{operating-system} -(@pxref{Référence de système d'exploitation, @code{services}}). - -En plus, les procédures @code{gnome-desktop-service-type}, -@code{xfce-desktop-service}, @code{mate-desktop-service-type} et -@code{enlightenment-desktop-service-type} peuvent ajouter GNOME, Xfce, MATE -ou Enlightenment à un système. « Ajouter GNOME » signifie que les services -du système comme les utilitaires d'ajustement de la luminosité et de gestion -de l'énergie sont ajoutés au système, en étendant @code{polkit} et -@code{dbus} de la bonne manière, ce qui permet à GNOME d'opérer avec des -privilèges plus élevés sur un nombre limité d'interfaces systèmes -spécialisées. En plus, ajouter un service construit par -@code{gnome-desktop-service-type} ajoute le métapaquet GNOME au profil du -système. De même, ajouter le service Xfce ajoute non seulement le -métapaquet @code{xfce} au profil système, mais il permet aussi au -gestionnaire de fichiers Thunar d'ouvrir une fenêtre de gestion des fichier -« en mode root », si l'utilisateur s'authentifie avec le mot de passe -administrateur via l'interface graphique polkit standard. « Ajouter MATE » -signifie que @code{polkit} et @code{dbus} sont étendue de la bonne manière, -ce qui permet à MATE d'opérer avec des privilèges plus élevés sur un nombre -limité d'interface systèmes spécialisées. En plus, ajouter un service de -type @code{mate-desktop-service-type} ajoute le métapaquet MATE au profil du -système. « Ajouter Enlightenment » signifie que @code{dbus} est étendu -comme il faut et que plusieurs binaires d'Enlightenment récupèrent le bit -setuid, ce qui permet au verrouilleur d'écran d'Enlightenment et à d'autres -fonctionnalités de fonctionner correctement. - -Les environnement de bureau dans Guix utilisent le service d'affichage Xorg -par défaut. Si vous voulez utiliser le protocol de serveur d'affichage plus -récent Wayland, vous devez utiliser @code{sddm-service} à la place de GDM -comme gestionnaire de connexion graphique. Vous devriez ensuite -sélectionner la session « GNOME (Wayland) » dans SDDM. Autrement, vous -pouvez essayer de démarrer GNOME sur Wayland manuellement depuis un TTY avec -la commande @command{XDG_SESSION_TYPE=wayland exec dbus-run-session -gnome-session}. Actuellement seul GNOME support Wayland. - -@defvr {Variable Scheme} gnome-desktop-service-type -C'est le type de service qui ajoute l'environnement de bureau -@uref{https://www.gnome.org, GNOME}. Sa valeur est un objet -@code{gnome-desktop-configuration} (voir plus bas). - -Ce service ajoute le paquet @code{gnome} au profil du système et étend -polkit avec les actions de @code{gnome-settings-daemon}. -@end defvr - -@deftp {Type de données} gnome-desktop-configuration -Enregistrement de la configuration de l'environnement de bureau GNOME. - -@table @asis -@item @code{gnome} (par défaut : @code{gnome}) -Le paquet GNOME à utiliser. -@end table -@end deftp - -@defvr {Variable Scheme} xfce-desktop-service-type -C'est le type de service qui lance l'environnement de bureau @uref{Xfce, -https://xfce.org/}. Sa valeur est un objet -@code{xfce-desktop-configuration} (voir plus bas). - -Ce service ajoute le paquet @code{xfce} au profil du système et étend polkit -avec la possibilité pour @code{thunar} de manipuler le système de fichier en -root depuis une session utilisateur, après que l'utilisateur s'authentifie -avec le mot de passe administrateur. -@end defvr - -@deftp {Type de données} xfce-desktop-configuration -Enregistrement de la configuration de l'environnement de bureau Xfce. - -@table @asis -@item @code{xfce} (par défaut : @code{xfce}) -Le paquet Xfce à utiliser. -@end table -@end deftp - -@deffn {Variable Scheme} mate-desktop-service-type -C'est le type de service qui lance @uref{https://mate-desktop.org/, -l'environnement de bureau MATE}. Sa valeur est un objet -@code{mate-desktop-configuration} (voir plus bas). - -Ce service ajoute le paquet @code{mate} au profil du système, et étend -polkit avec les actions de @code{mate-settings-daemon}. -@end deffn - -@deftp {Type de données} mate-desktop-configuration -Enregistrement de configuration pour l'environnement de bureau MATE. - -@table @asis -@item @code{mate} (par défaut : @code{mate}) -Le paquet MATE à utiliser. -@end table -@end deftp - -@deffn {Variable Scheme} enlightenment-desktop-service-type -Renvoie un service qui ajoute le paquet @code{enlightenment} et étend dbus -avec les actions de @code{efl} -@end deffn - -@deftp {Type de données} enlightenment-desktop-service-configuration -@table @asis -@item @code{enlightenment} (par défaut : @code{enlightenment}) -Le paquet enlightenment à utiliser. -@end table -@end deftp - -Comme les services de bureau GNOME, Xfce et MATE récupèrent tant de paquet, -la variable @code{%desktop-services} par défaut n'inclut aucun d'entre eux. -Pour ajouter GNOME, Xfce ou MATE, utilisez @code{cons} pour les ajouter à -@code{%desktop-services} dans le champ @code{services} de votre -@code{operating-system} : - -@example -(use-modules (gnu)) -(use-service-modules desktop) -(operating-system - ... - ;; cons* ajoute des éléments à la liste donnée en dernier argument. - (services (cons* (service gnome-desktop-service-type) - (service xfce-desktop-service) - %desktop-services)) - ...) -@end example - -Ces environnements de bureau seront alors disponibles comme une option dans -la fenêtre de connexion graphique. - -Les définitions de service qui sont vraiment incluses dans -@code{%desktop-services} et fournies par @code{(gnu services dbus)} et -@code{(gnu services desktop)} sont décrites plus bas. - -@deffn {Procédure Scheme} dbus-service [#:dbus @var{dbus}] [#:services '()] -Renvoie un service qui lance le « bus système », @var{dbus}, avec le support -de @var{services}. - -@uref{http://dbus.freedesktop.org/, D-Bus} est un utilitaire de -communication inter-processus. Son bus système est utilisé pour permettre à -des services systèmes de communiquer et d'être notifiés d'événements -systèmes. - -@var{services} doit être une liste de paquets qui fournissent un répertoire -@file{etc/dbus-1/system.d} contenant de la configuration D-Bus -supplémentaire et des fichiers de politiques. Par exemple, pour permettre à -avahi-daemon d'utiliser le bus système, @var{services} doit être égal à -@code{(list avahi)}. -@end deffn - -@deffn {Procédure Scheme} elogind-service [#:config @var{config}] -Renvoie un service qui lance le démon de gestion de connexion et de session -@code{elogind}. @uref{https://github.com/elogind/elogind, Elogind} expose -une interface D-Bus qui peut être utilisée pour connaître quels utilisateurs -sont connectés, le type de session qu'ils sont ouverte, suspendre le -système, désactiver la veille système, redémarrer le système et d'autre -taches. - -Elogind gère la plupart des événements liés à l'énergie du système, par -exemple mettre en veille le système quand l'écran est rabattu ou en -l'éteignant quand le bouton de démarrage est appuyé. - -L'argument @var{config} spécifie la configuration d'elogind et devrait être -le résultat d'une invocation de @code{(elogind-configuration -(@var{parameter} @var{value})...)}. Les paramètres disponibles et leur -valeur par défaut sont : - -@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 {Procédure Scheme} accountsservice-service @ - [#:accountsservice @var{accountsservice}] -Renvoie un service qui lance AccountsService, un service système qui peut -lister les comptes disponibles, changer leur mot de passe, etc. -AccountsService s'intègre à Polkit pour permettre aux utilisateurs non -privilégiés de pouvoir modifier la configuration de leur système. -@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, le site de -accountsservice} pour trouver plus d'informations. - -L'argument @var{accountsservice} est le paquet @code{accountsservice} à -exposer comme un service. -@end deffn - -@deffn {Procédure Scheme} polkit-service @ - [#:polkit @var{polkit}] -Renvoie un service qui lance le -@uref{http://www.freedesktop.org/wiki/Software/polkit/, service de gestion -des privilèges Polkit}, qui permet aux administrateurs systèmes de permettre -l'accès à des opération privilégiées d'une manière structurée. En demandant -au service Polkit, un composant système privilégié peut savoir lorsqu'il -peut donner des privilèges supplémentaires à des utilisateurs normaux. Par -exemple, un utilisateur normal peut obtenir le droit de mettre le système en -veille si l'utilisateur est connecté localement. -@end deffn - -@defvr {Variable Scheme} upower-service-type -Service qui lance @uref{http://upower.freedesktop.org/, @command{upowerd}}, -un moniteur système de consommation d'énergie et de niveau de batterie, avec -les paramètres de configuration donnés. - -Il implémente l'interface D-Bus @code{org.freedesktop.UPower} et est -notamment utilisé par GNOME. -@end defvr - -@deftp {Type de données} upower-configuration -Type de données représentant la configuration de UPower. - -@table @asis - -@item @code{upower} (par défaut : @var{upower}) -Paquet à utiliser pour @code{upower}. - -@item @code{watts-up-pro?} (par défaut : @code{#f}) -Active le périphérique Watts Up Pro. - -@item @code{poll-batteries?} (par défaut : @code{#t}) -Active les requêtes au noyau pour les changements de niveau de batterie. - -@item @code{ignore-lid?} (par défaut : @code{#f}) -Ignore l'état de l'écran, ce qui peut être utile s'il est incorrect sur un -appareil. - -@item @code{use-percentage-for-policy?} (par défaut : @code{#f}) -Indique si la politique de batterie basée sur le pourcentage devrait être -utilisée. La valeur par défaut est d'utiliser la durée restante, changez en -@code{#t} pour utiliser les pourcentages. - -@item @code{percentage-low} (par défaut : @code{10}) -Lorsque @code{use-percentage-for-policy?} est @code{#t}, cela indique à quel -niveau la batterie est considérée comme faible. - -@item @code{percentage-critical} (par défaut : @code{3}) -Lorsque @code{use-percentage-for-policy?} est @code{#t}, cela indique à quel -niveau la batterie est considérée comme critique. - -@item @code{percentage-action} (par défaut : @code{2}) -Lorsque @code{use-percentage-for-policy?} est @code{#t}, cela indique à quel -niveau l'action sera prise. - -@item @code{time-low} (par défaut : @code{1200}) -Lorsque @code{use-percentage-for-policy?} est @code{#f}, cela indique à -quelle durée restante en secondes la batterie est considérée comme faible. - -@item @code{time-critical} (par défaut : @code{300}) -Lorsque @code{use-percentage-for-policy?} est @code{#f}, cela indique à -quelle durée restante en secondes la batterie est considérée comme critique. - -@item @code{time-action} (par défaut : @code{120}) -Lorsque @code{use-percentage-for-policy?} est @code{#f}, cela indique à -quelle durée restante en secondes l'action sera prise. - -@item @code{critical-power-action} (par défaut : @code{'hybrid-sleep}) -L'action à prendre lorsque @code{percentage-action} ou @code{time-action} -est atteint (en fonction de la configuration de -@code{use-percentage-for-policy?}). - -Les valeurs possibles sont : - -@itemize @bullet -@item -@code{'power-off} - -@item -@code{'hibernate} - -@item -@code{'hybrid-sleep}. -@end itemize - -@end table -@end deftp - -@deffn {Procédure Scheme} udisks-service [#:udisks @var{udisks}] -Renvoie un service pour @uref{http://udisks.freedesktop.org/docs/latest/, -UDisks}, un démon de @dfn{gestion de disques} qui fournit des notifications -et la capacité de monter et démonter des disques à des interfaces -utilisateurs. Les programmes qui parlent à UDisks sont par exemple la -commande @command{udisksctl}, qui fait partie de UDisks et GNOME Disks. -@end deffn - -@deffn {Procédure Scheme} colord-service [#:colord @var{colord}] -Renvoie un service qui lance @command{colord}, un service système avec une -interface D-Bus pour gérer les profils de couleur des périphériques -d'entrées et de sorties comme les écrans et les scanners. Il est notamment -utilisé par l'outil graphique GNOME Color Manager. Voir -@uref{http://www.freedesktop.org/software/colord/, le site web de colord} -pour plus d'informations. -@end deffn - -@deffn {Procédure Scheme} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] -Renvoie une configuration qui permet d'accéder aux données de localisation -de GeoClue. @var{name} est l'ID Desktop de l'application, sans la partie en -@code{.desktop}. Si @var{allowed?} est vraie, l'application aura droit -d'accéder aux informations de localisation par défaut. Le booléen -@var{system?} indique si une application est un composant système ou non. -Enfin @var{users} est la liste des UID des utilisateurs pour lesquels cette -application a le droit d'accéder aux informations de géolocalisation. Une -liste d'utilisateurs vide indique que tous les utilisateurs sont autorisés. -@end deffn - -@defvr {Variable Scheme} %standard-geoclue-applications -La liste standard de configuration des application GeoClue connues, qui -permet à l'utilitaire date-and-time de GNOME de demander l'emplacement -actuel pour initialiser le fuseau horaire et aux navigateurs web IceCat et -Epiphany de demander les informations de localisation. IceCat et Epiphany -demandent tous deux à l'utilisateur avant de permettre à une page web de -connaître l'emplacement de l'utilisateur. -@end defvr - -@deffn {Procédure Scheme} 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] -Renvoie un service qui lance le service de géolocalisation GeoClue. Ce -service fournit une interface D-Bus pour permettre aux applications de -demande l'accès à la position de l'utilisateur et éventuellement d'ajouter -des informations à des bases de données de géolocalisation en ligne. Voir -@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, le site web de -GeoClue} pour plus d'informations. -@end deffn - -@deffn {Procédure Scheme} bluetooth-service [#:bluez @var{bluez}] @ - [@w{#:auto-enable? #f}] -Renvoie un service qui lance le démon @command{bluetoothd} qui gère tous les -appareils Bluetooth et fournit un certain nombre d'interfaces D-Bus. -Lorsque @var{auto-enable?} est vraie, le contrôler bluetooth est -automatiquement alimenté au démarrage, ce qui peut être utile lorsque vous -utilisez un clavier ou une souris bluetooth. - -Les utilisateurs doivent être dans le groupe @code{lp} pour accéder au -service D-Bus. -@end deffn - -@node Services de son -@subsection Services de son - -@cindex support du son -@cindex ALSA -@cindex PulseAudio, support du son - -Le module @code{(gnu services sound)} fournit un service pour configurer le -système ALSA (architecture son linux avancée), qui fait de PulseAudio le -pilote de sortie préféré d'ALSA. - -@deffn {Variable Scheme} alsa-service-type -C'est le type pour le système @uref{https://alsa-project.org/, Advanced -Linux Sound Architecture} (ALSA), qui génère le fichier de configuration -@file{/etc/asound.conf}. La valeur de ce type est un enregistrement -@command{alsa-configuration} comme dans cet exemple : - -@example -(service alsa-service-type) -@end example - -Voir plus bas pour des détails sur @code{alsa-configuration}. -@end deffn - -@deftp {Type de données} alsa-configuration -Type de données représentant la configuration pour @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (par défaut : @var{alsa-plugins}) -Le paquet @code{alsa-plugins} à utiliser. - -@item @code{pulseaudio?} (par défaut : @var{#t}) -Indique si les applications ALSA devraient utiliser le serveur de son -@uref{http://www.pulseaudio.org/, PulseAudio} de manière transparente pour -elles. - -Utiliser PulseAudio vous permet dans lancer plusieurs applications qui -produisent du son en même temps et de les contrôler individuellement via -@command{pavucontrol} entre autres choses. - -@item @code{extra-options} (par défaut : @var{""}) -Chaîne à ajouter au fichier @file{/etc/asound.conf}. - -@end table -@end deftp - -Les utilisateurs individuels qui veulent modifier la configuration système -d'ALSA peuvent le faire avec le fichier @file{~/.asoundrc} : - -@example -# Dans guix, il faut spécifier le chemin absolu des greffons. -pcm_type.jack @{ - lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so" -@} - -# Faire passer ALSA par Jack : -# . -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 - -Voir @uref{https://www.alsa-project.org/main/index.php/Asoundrc} pour les -détails. - - -@node Services de bases de données -@subsection Services de bases de données - -@cindex database -@cindex SQL -Le module @code{(gnu services databases)} fournit les services suivants. - -@deffn {Procédure Scheme} postgresql-service [#:postgresql postgresql] @ - [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ -[#:port 5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] -Renvoie un service qui lance @var{postgresql}, le service de bases de -données PostgreSQL. - -Le démon PostgreSQL charge sa configuration à l'exécution depuis -@var{config-file}, crée une grappe de bases de données avec @var{locale} -comme paramètre de régionalisation par défaut, stockée dans -@var{data-directory}. Il écoute ensuite sur @var{port}. - -@cindex postgresql extension-packages -Des extensions supplémentaires peuvent être chargées à partir de paquets -listés dans @var{extension-packages}. Les extensions sont disponibles à -l'exécution. Par exemple, pour créer une base de données géographique avec -l'extension @code{postgis}, on peut configurer postgresql-service de cette -manière : - -@cindex postgis -@example -(use-package-modules databases geo) - -(operating-system - ... - ;; postgresql est requis pour lancer `psql' mais postgis n'est pas requis pour son - ;; bon fonctionnement. - (packages (cons* postgresql %base-packages)) - (services - (cons* - (postgresql-service #:extension-packages (list postgis)) - %base-services))) -@end example - -Ensuite l'extension devient visible et vous pouvez initialiser une base de -données géographique de cette manière : - -@example -psql -U postgres -> create database postgistest; -> \connect postgistest; -> create extension postgis; -> create extension postgis_topology; -@end example - -Vous n'avez pas besoin d'ajouter ce champ pour les extensions « contrib » -comme hstore ou dblink comme elles sont déjà exploitables par postgresql. -Ce champ n'est requis que pour ajouter des extensions fournies par d'autres -paquets. -@end deffn - -@deffn {Procédure Scheme} mysql-service [#:config (mysql-configuration)] -Renvoie un service qui lance @command{mysqld}, le service de bases de -données MySQL ou MariaDB. - -L'argument @var{config} facultatif spécifie la configuration de -@command{mysqld}, qui devrait être un objet @code{}. -@end deffn - -@deftp {Type de données} mysql-configuration -Type de données représentant la configuration de @var{mysql-service}. - -@table @asis -@item @code{mysql} (par défaut : @var{mariadb}) -Objet paquet du serveur de base de données MySQL, qui peut être soit -@var{mariadb}, soit @var{mysql}. - -Pour MySQL, un mot de passe root temporaire sera affiché à l'activation. -Pour MariaDB, le mot de passe root est vide. - -@item @code{port} (par défaut : @code{3306}) -Port TCP sur lequel le serveur de base de données écoute les connexions -entrantes. -@end table -@end deftp - -@defvr {Variable Scheme} memcached-service-type -C'est le type de service pour le service @uref{https://memcached.org/, -Memcached} qui fournit un cache en mémoire distribué. La valeur pour le -type de service est un objet @code{memcached-configuration}. -@end defvr - -@example -(service memcached-service-type) -@end example - -@deftp {Type de données} memcached-configuration -Type de données représentant la configuration de memcached. - -@table @asis -@item @code{memcached} (par défaut : @code{memcached}) -Le paquet Memcached à utiliser. - -@item @code{interfaces} (par défaut : @code{'("0.0.0.0")}) -Les interfaces réseaux sur lesquelles écouter. - -@item @code{tcp-port} (par défaut : @code{11211}) -Port sur lequel accepter les connexions. - -@item @code{udp-port} (par défaut : @code{11211}) -Port sur lequel accepter les connexions UDP, une valeur de 0 désactive -l'écoute en UDP. - -@item @code{additional-options} (par défaut : @code{'()}) -Options de la ligne de commande supplémentaires à passer à @code{memcached}. -@end table -@end deftp - -@defvr {Variable Scheme} mongodb-service-type -C'est le type de service pour @uref{https://www.mongodb.com/, MongoDB}. La -valeur de ce service est un objet @code{mongodb-configuration}. -@end defvr - -@example -(service mongodb-service-type) -@end example - -@deftp {Type de données} mongodb-configuration -Type de données représentant la configuration de mongodb. - -@table @asis -@item @code{mongodb} (par défaut : @code{mongodb}) -Le paquet MongoDB à utiliser. - -@item @code{config-file} (par défaut : @code{%default-mongodb-configuration-file}) -Le fichier de configuration pour MongoDB. - -@item @code{data-directory} (par défaut : @code{"/var/lib/mongodb"}) -Cette valeur est utilisée pour créer le répertoire, pour qu'il existe et -appartienne à l'utilisateur mongodb. Il devrait correspondre au -data-directory que MongoDB est configuré pour utiliser dans son fichier de -configuration. -@end table -@end deftp - -@defvr {Variable Scheme} redis-service-type -C'est le type de service pour la base clef-valeur @uref{https://redis.io/, -Redis} dont la valeur est un objet @code{redis-configuration}. -@end defvr - -@deftp {Type de données} redis-configuration -Type de données représentant la configuration de redis. - -@table @asis -@item @code{redis} (par défaut : @code{redis}) -Le paquet Redis à utiliser. - -@item @code{bind} (par défaut : @code{"127.0.0.1"}) -Interface réseau sur laquelle écouter. - -@item @code{port} (par défaut : @code{6379}) -Port sur lequel accepter les connexions, une valeur de 0 désactive l'écoute -sur un socket TCP. - -@item @code{working-directory} (par défaut : @code{"/var/lib/redis"}) -Répertoire dans lequel stocker la base de données et les fichiers liés. -@end table -@end deftp - -@node Services de courriels -@subsection Services de courriels - -@cindex courriel -@cindex email -Le module @code{(gnu services mail)} fournit des définitions de services -Guix pour les services de courriel : des serveurs IMAP, POP3 et LMTP ainsi -que des MTA (Mail Transport Agent). Que d'acronymes ! Ces services sont -détaillés dans les sous-sections ci-dessous. - -@subsubheading Service Dovecot - -@deffn {Procédure Scheme} dovecot-service [#:config (dovecot-configuration)] -Renvoie un service qui lance le serveur de courriel IMAP/POP3/LMTP Dovecot. -@end deffn - -Par défaut, Dovecot n'a pas besoin de beaucoup de configuration ; l'objet de -configuration par défaut créé par @code{(dovecot-configuration)} suffira si -votre courriel est livré dans @code{~/Maildir}. Un certificat auto-signé -sera généré pour les connexions TLS, bien que Dovecot écoutera aussi sur les -ports non chiffrés par défaut. Il y a quelques options cependant, que les -administrateurs peuvent avoir besoin de changer et comme c'est le cas avec -d'autres services, Guix permet aux administrateurs systèmes de spécifier ces -paramètres via une interface Scheme unifiée. - -Par exemple, pour spécifier que les courriels se trouvent dans -@code{maildir~/.mail}, on peut instancier Dovecot de cette manière : - -@example -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.mail"))) -@end example - -Les paramètres de configuration disponibles sont les suivants. Chaque -définition des paramètres est précédé par son type ; par exemple, -@samp{string-list foo} indique que le paramètre @code{foo} devrait être -spécifié comme une liste de chaînes de caractères. Il y a aussi une manière -de spécifier la configuration comme une chaîne de caractères, si vous avez -un vieux fichier @code{dovecot.conf} que vous voulez porter depuis un autre -système ; voir la fin pour plus de détails. - -@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. - -Les champs de @code{dovecot-configuration} disponibles sont : - -@deftypevr {paramètre de @code{dovecot-configuration}} package dovecot -Le paquet dovecot. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} comma-separated-string-list listen -Une liste d'IP ou d'hôtes à écouter pour les connexions. @samp{*} écoute -sur toutes les interfaces IPv4, @samp{::} écoute sur toutes les interfaces -IPv6. Si vous voulez spécifier des ports différents de la valeur par défaut -ou quelque chose de plus complexe, complétez les champs d'adresse et de port -de @samp{inet-listener} des services spécifiques qui vous intéressent. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} protocol-configuration-list protocols -Liste des protocoles que vous voulez servir. Les protocoles disponibles -comprennent @samp{imap}, @samp{pop3} et @samp{lmtp}. - -Les champs @code{protocol-configuration} disponibles sont : - -@deftypevr {paramètre de @code{protocol-configuration}} string name -Le nom du protocole. -@end deftypevr - -@deftypevr {paramètre de @code{protocol-configuration}} string auth-socket-path -Le chemin d'un socket UNIX vers le serveur d'authentification maître pour -trouver les utilisateurs. C'est utilisé par imap (pour les utilisateurs -partagés) et lda. Sa valeur par défaut est -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {paramètre de @code{protocol-configuration}} space-separated-string-list mail-plugins -Liste de greffons à charger séparés par des espaces. -@end deftypevr - -@deftypevr {paramètre de @code{protocol-configuration}} non-negative-integer mail-max-userip-connections -Nombre maximum de connexions IMAP permises pour un utilisateur depuis chaque -adresse IP. Remarque : la comparaison du nom d'utilisateur est sensible à -la casse. Par défaut @samp{10}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} service-configuration-list services -Liste des services à activer. Les services disponibles comprennent -@samp{imap}, @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth} -et @samp{lmtp}. - -Les champs de @code{service-configuration} disponibles sont : - -@deftypevr {paramètre de @code{service-configuration}} string kind -Le type de service. Les valeurs valides comprennent @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} ou n'importe quoi d'autre. -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} listener-configuration-list listeners -Les auditeurs du service. Un auditeur est soit un -@code{unix-listener-configuration}, soit un -@code{fifo-listener-configuration}, soit un -@code{inet-listener-configuration}. La valeur par défaut est @samp{()}. - -Les champs de @code{unix-listener-configuration} disponibles sont : - -@deftypevr {paramètre de @code{unix-listener-configuration}} string path -Chemin vers le fichier, relativement au champ @code{base-dir}. C'est aussi -utilisé comme nom de section. -@end deftypevr - -@deftypevr {paramètre de @code{unix-listener-configuration}} string mode -Le mode d'accès pour le socket. La valeur par défaut est @samp{"0600"}. -@end deftypevr - -@deftypevr {paramètre de @code{unix-listener-configuration}} string user -L'utilisateur à qui appartient le socket. La valeur par défaut est -@samp{""} -@end deftypevr - -@deftypevr {paramètre de @code{unix-listener-configuration}} string group -Le groupe auquel appartient le socket. La valeur par défaut est @samp{""}. -@end deftypevr - - -Les champs de @code{fifo-listener-configuration} disponibles sont : - -@deftypevr {paramètre de @code{fifo-listener-configuration}} string path -Chemin vers le fichier, relativement au champ @code{base-dir}. C'est aussi -utilisé comme nom de section. -@end deftypevr - -@deftypevr {paramètre de @code{fifo-listener-configuration}} string mode -Le mode d'accès pour le socket. La valeur par défaut est @samp{"0600"}. -@end deftypevr - -@deftypevr {paramètre de @code{fifo-listener-configuration}} string user -L'utilisateur à qui appartient le socket. La valeur par défaut est -@samp{""} -@end deftypevr - -@deftypevr {paramètre de @code{fifo-listener-configuration}} string group -Le groupe auquel appartient le socket. La valeur par défaut est @samp{""}. -@end deftypevr - - -Les champs de @code{inet-listener-configuration} disponibles sont : - -@deftypevr {paramètre de @code{inet-listener-configuration}} string protocol -Le protocole à écouter. -@end deftypevr - -@deftypevr {paramètre de @code{inet-listener-configuration}} string address -L'adresse sur laquelle écouter, ou la chaîne vide pour toutes les adresses. -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{inet-listener-configuration}} non-negative-integer port -Le port sur lequel écouter. -@end deftypevr - -@deftypevr {paramètre de @code{inet-listener-configuration}} boolean ssl? -S'il faut utiliser SSL pour ce service ; @samp{yes}, @samp{no} ou -@samp{required}. La valeur par défaut est @samp{#t}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} non-negative-integer client-limit -Connexions de clients simultanées maximum par processus. Une fois ce nombre -de connections atteint, la connexion suivante fera en sorte que Dovecot -démarre un autre processus. Si la valeur est 0, @code{default-client-limit} -est utilisé à la place. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} non-negative-integer service-count -Nombre de connexions à gérer avant de démarrer un nouveau processus. -Typiquement les valeurs utiles sont 0 (sans limite) ou 1. 1 est plus sûr, -mais 0 est plus rapide. . La valeur par défaut -est @samp{1}. - -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} non-negative-integer process-limit -Nombre de processus maximum qui peut exister pour ce service. Si la valeur -est 0, @code{default-process-limit} est utilisé à la place. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} non-negative-integer process-min-avail -Nombre de processus à toujours garder en attente de connexions. La valeur -par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{service-configuration}} non-negative-integer vsz-limit -Si vous mettez @samp{service-count 0}, vous avez sans doute besoin -d'augmenter ce paramètre. La valeur par défaut est @samp{256000000}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} dict-configuration dict -Configuration du dictionnaire, créé par le constructeur -@code{dict-configuration}. - -Les champs de @code{dict-configuration} disponibles sont : - -@deftypevr {paramètre de @code{dict-configuration}} free-form-fields entries -Une liste de paires de clefs-valeurs que ce dictionnaire contient. La -valeur par défaut est @samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} passdb-configuration-list passdbs -Une liste de configurations passdb, chacune créée par le constructeur -@code{passdb-configuration}. - -Les champs de @code{passdb-configuration} disponibles sont : - -@deftypevr {paramètre de @code{passdb-configuration}} string driver -Le pilote à utiliser par passdb. Les valeur valides comprennent @samp{pam}, -@samp{passwd}, @samp{shadow}, @samp{bsdauth} et @samp{static}. La valeur -par défaut est @samp{"pam"}. -@end deftypevr - -@deftypevr {paramètre de @code{passdb-configuration}} space-separated-string-list args -Liste d'arguments pour le pilote passdb séparés par des espaces. La valeur -par défaut est @samp{""}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} userdb-configuration-list userdbs -Liste des configurations userdb, chacune créée par le constructeur -@code{userdb-configuration}. - -Les champs de @code{userdb-configuration} disponibles sont : - -@deftypevr {paramètre de @code{userdb-configuration}} string driver -Le pilote que userdb devrait utiliser. Les valeurs valides comprennent -@samp{passwd} et @samp{static}. La valeur par défaut est @samp{"passwd"}. -@end deftypevr - -@deftypevr {paramètre de @code{userdb-configuration}} space-separated-string-list args -Liste des arguments du pilote userdb séparés par des espaces. La valeur par -défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{userdb-configuration}} free-form-args override-fields -Remplace des champs de passwd. La valeur par défaut est @samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} plugin-configuration plugin-configuration -Configuration du greffon, créé par le constructeur -@code{plugin-configuration}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} list-of-namespace-configuration namespaces -Liste d'espaces de noms. Chaque élément de la liste est créé par le -constructeur @code{namespace-configuration}. - -Les champs de @code{namespace-configuration} disponibles sont : - -@deftypevr {paramètre de @code{namespace-configuration}} string name -Nom de cet espace de nom. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} string type -Type d'espace de nom : @samp{private}, @samp{shared} ou @samp{public}. La -valeur par défaut est @samp{"private"}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} string separator -Séparateur de hiérarchie à utiliser. Vous devriez utiliser le même -séparateur pour tous les espaces de noms ou certains clients seront confus. -@samp{/} est généralement une bonne valeur. La valeur par défaut dépend -cependant du format de stockage sous-jacent. La valeur par défaut est -@samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} string prefix -Préfixe requis pour accéder à cet espace de nom. Ce paramètres doit être -différent pour tous les espaces de noms. Par exemple @samp{Public/}. La -valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} string location -Emplacement physique de la boîte aux lettres. C'est le même format que -mail_location, qui est aussi la valeur par défaut. La valeur par défaut est -@samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} boolean inbox? -Il ne peut y avoir qu'un INBOX, et ce paramètre définit l'espace de nom qui -le possède. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} boolean hidden? -Si l'espace de nom est caché, il n'est pas publié auprès des clients par -l'extension NAMESPACE. Vous voudrez aussi sans doute indiquer @samp{list? -#f}. C'est surtout utile lors de la conversion depuis un autre serveur avec -des espaces de noms différents que vous voulez rendre obsolètes sans les -casser. Par exemple vous pouvez cacher les espaces de noms avec les -préfixes @samp{~/mail/}, @samp{~%u/mail/} et @samp{mail/}. La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} boolean list? -Montre les boîtes aux lettres sons cet espace de nom avec la commande LIST. -Cela rend l'espace de nom visible pour les clients qui ne supportent pas -l'extension NAMESPACE. La valeur spéciale @code{children} liste les boîtes -aux lettres filles mais cache le préfixe de l'espace de nom. La valeur par -défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} boolean subscriptions? -Les espaces de noms gèrent leur propre souscription. Si la valeur est -@code{#f}, l'espace de nom parent s'en charge. Le préfixe vide devrait -toujours avoir cette valeur à @code{#t}. La valeur par défaut est -@samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{namespace-configuration}} mailbox-configuration-list mailboxes -Liste des boîtes aux lettres prédéfinies dans cet espace de nom. La valeur -par défaut est @samp{()}. - -Les champs de @code{mailbox-configuration} disponibles sont : - -@deftypevr {paramètre de @code{mailbox-configuration}} string name -Nom de cette boîte aux lettres. -@end deftypevr - -@deftypevr {paramètre de @code{mailbox-configuration}} string auto -@samp{create} créera automatiquement cette boîte aux lettres. -@samp{subscribe} créera et souscrira à la boîte aux lettres. La valeur par -défaut est @samp{"no"}. -@end deftypevr - -@deftypevr {paramètre de @code{mailbox-configuration}} space-separated-string-list special-use -Liste des attributs @code{SPECIAL-USE} IMAP spécifiés par la RFC 6154. Les -valeurs valides sont @code{\All}, @code{\Archive}, @code{\Drafts}, -@code{\Flagged}, @code{\Junk}, @code{\Sent} et @code{\Trash}. La valeur par -défaut est @samp{()}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name base-dir -Répertoire de base où stocker les données d'exécution. La valeur par défaut -est @samp{"/var/run/dovecot/"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string login-greeting -Message d'accueil pour les clients. La valeur par défaut est @samp{"Dovecot -ready."}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list login-trusted-networks -Liste des groupes d'adresses de confiance. Les connexions depuis ces IP -sont autorisées à modifier leurs adresses IP et leurs ports (pour la -connexion et la vérification d'authentification). -@samp{disable-plaintext-auth} est aussi ignoré pour ces réseaux. -Typiquement vous voudrez spécifier votre mandataire IMAP ici. La valeur par -défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list login-access-sockets -Liste des sockets de vérification d'accès de connexion (p.@: ex.@: -tcpwrap). La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean verbose-proctitle? -Montre des titres de processus plus verbeux (dans ps). Actuellement, montre -le nom d'utilisateur et l'adresse IP. Utile pour voir qui utilise en -réalité les processus IMAP (p.@: ex.@: des boîtes aux lettres partagées ou -si le même uid est utilisé pour plusieurs comptes). La valeur par défaut -est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean shutdown-clients? -Indique si les processus devraient toujours être tués lorsque le processus -maître de Dovecot est éteint. La valeur @code{#f} signifie que Dovecot peut -être mis à jour sans forcer les connexions clientes existantes à se fermer -(bien que cela puisse être un problème si la mise à jour est un correctif de -sécurité par exemple). La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer doveadm-worker-count -Si la valeur n'est pas zéro, lance les commandes de courriel via ce nombre -de connexions au serveur doveadm au lieu de les lancer dans le même -processus. La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string doveadm-socket-path -Socket UNIX ou hôte:port utilisé pour se connecter au serveur doveadm. La -valeur par défaut est @samp{"doveadm-server"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list import-environment -Liste des variables d'environnement qui sont préservées au démarrage de -Dovecot et passées à tous ses processus fils. Vous pouvez aussi donner des -paires clef=valeur pour toujours spécifier ce paramètre. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean disable-plaintext-auth? -Désactive la commande LOGIN et toutes les autres authentifications en texte -clair à moins que SSL/TLS ne soit utilisé (capacité LOGINDISABLED). -Remarquez que si l'IP distante correspond à l'IP locale (c.-à-d.@: que vous -vous connectez depuis le même ordinateur), la connexion est considérée comme -sécurisée et l'authentification en texte clair est permise. Voir aussi le -paramètre ssl=required. La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer auth-cache-size -Taille du cache d'authentification (p.@: ex.@: @samp{#e10e6}). 0 signifie -qu'il est désactivé. Remarquez que bsdauth, PAM et vpopmail ont besoin que -@samp{cache-key} soit indiqué pour que le cache soit utilisé. La valeur par -défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-cache-ttl -Durée de vie des données en cache. Après l'expiration du TTL -l'enregistrement en cache n'est plus utilisé *sauf* si la requête à la base -de données principale revoie une erreur interne. Nous essayons aussi de -gérer les changements de mot de passe automatiquement : si -l'authentification précédente de l'utilisateur était réussie mais pas -celle-ci, le cache n'est pas utilisé. Pour l'instant cela fonctionne avec -l'authentification en texte clair uniquement. La valeur par défaut est -@samp{"1 hour"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-cache-negative-ttl -TTL pour les résultats négatifs (l'utilisateur n'est pas trouvé ou le mot de -passe ne correspond pas). 0 désactive la mise en cache complètement. La -valeur par défaut est @samp{"1 hour"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list auth-realms -Liste des domaines pour les mécanismes d'authentification SASL qui en ont -besoin. Vous pouvez laisser ce paramètre vide si vous ne voulez pas -utiliser plusieurs domaines. Beaucoup de clients utilisent le premier -domaine listé ici, donc gardez celui par défaut en premier. La valeur par -défaut est @samp{()} -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-default-realm -Domaine par défaut à utiliser si aucun n'est spécifié. C'est utilisé pour -les domaines SASL et pour ajouter @@domaine au nom d'utilisateur dans les -authentification en texte clair. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-username-chars -Liste des caractères autorisés dans les noms d'utilisateur. Si le nom -d'utilisateur donné par l'utilisateur contient un caractère qui n'est pas -listé ici, la connexion échoue automatiquement. C'est juste une -vérification supplémentaire pour s'assure que l'utilisateur ne puisse pas -exploiter des vulnérabilités potentielles d'échappement de guillemets avec -les bases de données SQL/LDAP. Si vous voulez autoriser tous les -caractères, indiquez la liste vide. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-username-translation -Traduction de caractères dans les noms d'utilisateur avant qu'ils ne soient -cherchés en base. La valeur contient une série de caractère de -> à. Par -exemple @samp{#@@/@@} signifie que @samp{#} et @samp{/} sont traduits en -@samp{@@}. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-username-format -Format des noms d'utilisateur avant qu'ils ne soient cherchés en base. Vous -pouvez utiliser les variables standard ici, p.@: ex.@: %Lu est le nom -d'utilisateur en minuscule, %n enlève le domaine s'il est donné ou -@samp{%n-AT-%d} changerait le @samp{@@} en @samp{-AT-}. Cette traduction -est faite après les changements de @samp{auth-username-translation}. La -valeur par défaut est @samp{"%Lu"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-master-user-separator -Si vous voulez permettre aux utilisateurs maîtres de se connecter en -spécifiant le nom d'utilisateur maître dans la chaîne de nom d'utilisateur -normal (c.-à-d.@: sans utiliser le support du mécanisme SASL pour cela), -vous pouvez spécifier le caractère de séparation ici. Le format est ensuite -. UW-IMAP utilise -@samp{*} comme séparateur, donc ça pourrait être un bon choix. La valeur -par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-anonymous-username -Nom d'utilisateur à utiliser pour les utilisateurs qui se connectent avec le -mécanisme SASL ANONYMOUS. La valeur par défaut est @samp{"anonymous"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer auth-worker-max-count -Nombre maximum de processus de travail dovecot-auth. Ils sont utilisés pour -exécuter des requêtes passdb et userdb bloquantes (p.@: ex.@: MySQL et -PAM). Ils sont créés automatiquement et détruits au besoin. La valeur par -défaut est @samp{30}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-gssapi-hostname -Nom d'hôte à utiliser dans les noms GSSAPI principaux. La valeur par défaut -est d'utiliser le nom renvoyé par gethostname(). Utilisez @samp{$ALL} (avec -des guillemets) pour permettre toutes les entrées keytab. La valeur par -défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-krb5-keytab -Keytab Kerberos à utiliser pour le mécanisme GSSAPI. Utilisera la valeur -par défaut du système (typiquement @file{/etc/krb5.keytab}) s'il n'est pas -spécifié. Vous pourriez avoir besoin de faire en sorte que le service -d'authentification tourne en root pour pouvoir lire ce fichier. La valeur -par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-use-winbind? -Effectue l'authentification NTLM et GSS-SPNEGO avec le démon winbind de -Samba et l'utilitaire @samp{ntlm-auth}. -. La valeur par défaut est -@samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name auth-winbind-helper-path -Chemin du binaire @samp{ntlm-auth} de samba. La valeur par défaut est -@samp{"/usr/bin/ntlm_auth"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string auth-failure-delay -Durée d'attente avant de répondre à des authentifications échouées. La -valeur par défaut est @samp{"2 secs"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-ssl-require-client-cert? -Requiert un certification client SSL valide ou l'authentification échoue. -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-ssl-username-from-cert? -Prend le nom d'utilisateur du certificat SSL client, avec -@code{X509_NAME_get_text_by_NID()} qui renvoie le CommonName du DN du -sujet. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list auth-mechanisms -Liste des mécanismes d'authentification souhaités. Les mécanismes supportés -sont : @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, -@samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, -@samp{otp}, @samp{skey} et @samp{gss-spnego}. Remarquez : Voir aussi le -paramètre @samp{disable-plaintext-auth}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list director-servers -Liste des IP ou des noms d'hôtes des serveurs directeurs, dont soi-même. -Les ports peuvent être spécifiés avec ip:port. Le port par défaut est le -même que le @samp{inet-listener} du service directeur. La valeur par défaut -est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list director-mail-servers -Liste des IP ou des noms d'hôtes de tous les serveurs de courriel de la -grappe. Les intervalles sont aussi permis, comme 10.0.0.10-10.0.0.30. La -valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string director-user-expire -Combien de temps avant de rediriger les utilisateurs à un serveur spécifique -après qu'il n'y a plus de connexion. La valeur par défaut est @samp{"15 -min"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string director-username-hash -La manière de traduire le nom d'utilisateur avant de le hasher. Les valeurs -utiles comprennent %Ln si l'utilisateur peut se connecter avec ou sans -@@domain, %Ld si les boîtes aux lettres sont partagées dans le domaine. La -valeur par défaut est @samp{"%Lu"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string log-path -Fichier de journal à utiliser pour les messages d'erreur. @samp{syslog} -journalise vers syslog, @samp{/dev/stderr} vers la sortie d'erreur. La -valeur par défaut est @samp{"syslog"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string info-log-path -Fichier de journal à utiliser pour les messages d'information. La valeur -par défaut est @samp{log-path}. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string debug-log-path -Fichier de journal à utiliser pour les messages de débogage. La valeur par -défaut est @samp{info-log-path}. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string syslog-facility -Dispositif syslog à utiliser si vous journalisez avec syslog. Normalement -si vous ne voulez pas utiliser @samp{mail}, vous voudrez utiliser -local0..local7. D'autres dispositifs standard sont supportés. La valeur -par défaut est @samp{"mail"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-verbose? -Indique s'il faut enregistrer les tentatives de connexion échouées et la -raison de leur échec. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-verbose-passwords? -Dans le cas où le mot de passe n'était pas correct, indique s'il faut -enregistrer le mauvais mot de passe. Les valeurs valides sont « no », « -plain » et « sha1 ». Il peut être utile d'indiquer « sha1 » pour -discriminer des attaques par force brute d'utilisateurs qui réessayent -encore et encore le même mot de passe. Vous pouvez aussi tronquer la valeur -à n caractères en ajoutant « :n » (p.@: ex.@: « sha1:6 »). La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-debug? -Journaux encore plus verbeux pour le débogage. Cela montre par exemple les -requêtes SQL effectuées. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean auth-debug-passwords? -Dans le cas où le mot de passe était incorrect, indique s'il faut -enregistrer les mots de passe et les schémas utilisés pour que le problème -puisse être débogué. Activer cette option active aussi @samp{auth-debug}. -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mail-debug? -Indique s'il faut activer le débogage du traitement des courriels. Cela -peut vous aider à comprendre pourquoi Dovecot ne trouve pas vos courriels. -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean verbose-ssl? -Indique s'il faut montrer les erreurs au niveau SSL. La valeur par défaut -est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string log-timestamp -Préfixe à utiliser devant chaque ligne écrite dans le fichier journal. Les -codes % sont au format strftime(3). La valeur par défaut est @samp{"\"%b %d -%H:%M:%S \""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list login-log-format-elements -Liste des éléments qu'il faut enregistrer. Les éléments qui ont une -variable non vide sont agrégés pour former une chaîne de mots séparés par -des virgules. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string login-log-format -Format du journal de connexion. %s contient la chaîne -@samp{login-log-format-elements}, %$ contient la donnée à enregistrer. La -valeur par défaut est @samp{"%$: %s"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-log-prefix -Préfixe à utiliser devant chaque ligne du fichier de journal pour les -processus traitant les courriels. Voir doc/wiki/Variables.txt pour trouver -la liste des variables que vous pouvez utiliser. La valeur par défaut est -@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string deliver-log-format -Format à utiliser pour enregistrer les livraisons de courriels. Vous pouvez -utiliser ces variables : -@table @code -@item %$ -Message de statut de la livraison (p.@: ex.@: @samp{saved to INBOX}) -@item %m -Message-ID -@item %s -Objet -@item %f -Adresse « de » -@item %p -Taille physique -@item %w -Taille virtuelle. -@end table -La valeur par défaut est @samp{"msgid=%m: %$"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-location -Emplacement des boîtes à lettre des utilisateurs. La valeur par défaut est -vide, ce qui signifie que Dovecot essaiera de trouver les boîte aux lettres -automatiquement. Cela ne fonctionnera pas si l'utilisateur n'a aucun -courriel, donc il vaut mieux indiquer explicitement le bon emplacement à -Dovecot. - -Si vous utilisez mbox, il ne suffit pas de donner le chemin vers le fichier -INBOX (p.@: ex.@: /var/mail/%u). Vous devrez aussi dire à Dovecot où les -autres boîtes aux lettres se trouvent. Cela s'appelle le « répertoire -racine des courriels » et il doit être le premier chemin donné à l'option -@samp{mail-location}. - -Il y a quelques variables spéciales que vous pouvez utiliser : - -@table @samp -@item %u -nom d'utilisateur -@item %n -la partie « utilisateur » dans « utilisateur@@domaine », comme %u s'il n'y a -pas de domaine -@item %d -la partie « domaine » dans « utilisateur@@domaine », vide s'il n'y a pas de -domaine -@item %h -répertoire personnel -@end table - -Voir doc/wiki/Variables.txt pour la liste complète. Quelques exemple : -@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 -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-uid -Utilisateur et groupe système utilisé pour accéder aux courriels. Si vous -utilisez multiple, userdb peut remplacer ces valeurs en renvoyant les champs -uid et gid. Vous pouvez utiliser soit des nombres, soit des noms. -. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-gid - -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-privileged-group -Groupe à activer temporairement pour les opérations privilégiées. -Actuellement cela est utilisé uniquement avec INBOX lors de sa création -initiale et quand le verrouillage échoie. Typiquement, vous pouvez utiliser -« mail » pour donner accès à /var/mail. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-access-groups -Donne l'accès à ces groupes supplémentaires aux processus de courriel. Ils -sont typiquement utilisés pour mettre en place l'accès à des boîtes aux -lettres partagées. Remarquez qu'il peut être dangereux d'utiliser cette -option si l'utilisateur peut créer des liens symboliques (p.@: ex.@: si le -groupe « mail » est utilisé ici, « ln -s /var/mail ~/mail/var » peut -permettre à un utilisateur de supprimer les boîtes aux lettres des autres, -ou « ln -s /secret/shared/box ~/mail/mybox » lui permettrait de la lire). -La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mail-full-filesystem-access? -Permet l'accès complet au système de fichiers pour les clients. Il n'y a -pas de vérification d'accès autres que ce que le système d'exploitation fait -avec les UID/GID. Cela fonctionne aussi bien avec maildir qu'avec mbox, ce -qui vous permet de préfixer les noms des boîtes aux lettres avec p.@: ex.@: -/chemin/ ou ~utilisateur/. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mmap-disable? -Ne pas du tout utiliser mmap(). Cela est requis si vous stockez les index -dans des systèmes de fichiers partagés (NFS ou clusterfs). La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean dotlock-use-excl? -S'appuyer sur @samp{O_EXCL} lors de la création de fichiers de -verrouillage. NFS supporte @samp{O_EXCL} depuis la version 3, donc cette -option est sûre de nos jours. La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-fsync -Quand utiliser les appels à fsync() ou fdatasync() : -@table @code -@item optimized -Lorsque cela est nécessaire pour éviter de perdre des données importantes -@item always -Utile lorsque par exemple les écritures NFS sont retardées -@item never -Ne l'utilisez pas (ça a de meilleures performances, mais les crashs font -perdre toutes les données). -@end table -La valeur par défaut est @samp{"optimized"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mail-nfs-storage? -Le stockage des courriels se fait sur NFS. Utilisez cette option pour que -Dovecot vide les caches NFS lorsque c'est nécessaire. Si vous utilisez -seulement un simple serveur de courriel, ce n'est pas nécessaire. La valeur -par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mail-nfs-index? -Les fichiers d'index de courriels sont sur un système de fichiers NFS. Pour -utiliser cette option, vous aurez besoin de @samp{mmap-disable? #t} et -@samp{fsync-disable? #f}. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string lock-method -Méthode de verrouillage des fichiers d'index. Les alternatives sont fcntl, -flock et dotlock. Le verrouillage-point (dotlocking) utilise des astuces -qui peuvent créer plus d'utilisation du disque que les autres méthodes de -verrouillage. Pour les utilisateurs de NFS, flock ne marche pas, et -rappelez-vous de modifier @samp{mmap-disable}. La valeur par défaut est -@samp{"fcntl"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name mail-temp-dir -Le répertoire dans lequel LDA/LMTP stockent temporairement les courriels de -plus de 128 Ko. La valeur par défaut est @samp{"/tmp"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer first-valid-uid -L'intervalle d'UID valides pour les utilisateurs. Cette option est surtout -utile pour s'assurer que les utilisateurs ne peuvent pas s'authentifier en -tant que démon ou qu'un autre utilisateur système. Remarquez que la -connexion en root est interdite en dur dans le binaire de dovecot et qu'on -ne peut pas l'autoriser même si @samp{first-valid-uid} vaut 0. La valeur -par défaut est @samp{500}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer last-valid-uid - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer first-valid-gid -Li'ntervalle de GID valides pour les utilisateurs. Les utilisateurs qui ont -un GID non-valide comme numéro de groupe primaire ne peuvent pas se -connecter. Si l'utilisateur appartient à un groupe avec un GID non valide, -ce groupe n'est pas utilisable. La valeur par défaut est @samp{1}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer last-valid-gid - -La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer mail-max-keyword-length -Longueur maximale autorisée pour les mots-clefs. Elle n'est utilisée que -lors de la création de nouveaux mots-clefs. La valeur par défaut est -@samp{50}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} colon-separated-file-name-list valid-chroot-dirs -Liste des répertoires sous lesquels le chroot est permis pour les processus -de traitement des courriels (c.-à-d.@: /var/mail permettra aussi de se -chrooter dans /var/mail/foo/bar). Ce paramètre n'affecte pas -@samp{login-chroot} @samp{mail-chroot} ou les paramètres de chroot de -l'authentification. Si ce paramètre est vide, « /./ » dans les répertoires -personnels sont ignorés. ATTENTION : n'ajoutez jamais de répertoires ici -que les utilisateurs locaux peuvent modifier, puisque ça pourrait permettre -d'escalader les privilèges. Normalement vous ne devriez le faire que si les -utilisateurs n'ont pas d'accès shell. . La valeur -par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-chroot -Répertoire chroot par défaut pour les processus de traitement des -courriels. Cela peut être modifié pour des utilisateurs particuliers dans -la base de donnée en donnant /./ dans le répertoire personnel (p.@: ex.@: -/home/./utilisateur permet de se chrooter dans /home). Remarquez qu'il n'y -a d'habitude pas besoin de se chrooter. Dovecot ne permet pas aux -utilisateurs d'accéder aux fichiers en dehors de leur répertoire de -courriels de toute façon. Si vos répertoires personnels sont préfixés par -le répertoire de chroot, ajoutez « /. » à @samp{mail-chroot}. -. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name auth-socket-path -Chemin de socket UNIX vers le serveur d'authentification maître pour trouver -les utilisateurs. C'est utilisé par imap (pour les utilisateurs partagés) -et lda. La valeur par défaut est @samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name mail-plugin-dir -Répertoire où trouver les greffons. La valeur par défaut est -@samp{"/usr/lib/dovecot"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list mail-plugins -Liste des greffons à charger pour tous les services. Les greffons -spécifiques à IMAP, LDA, etc sont ajoutés à cette liste dans leur propre -fichiers .conf. La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer mail-cache-min-mail-count -Le nombre minimal de courriels dans une boîte aux lettres avant de mettre à -jour le fichier de cache. Cela permet d'optimiser le comportement de -Dovecot pour qu'il fasse moins d'écriture disque contre plus de lecture -disque. La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mailbox-idle-check-interval -Lorsque la commande IDLE est lancée, la boîte aux lettres est vérifiée de -temps en temps pour voir s'il y a de nouveaux messages ou d'autres -changements. Ce paramètre défini le temps d'attente minimum entre deux -vérifications. Dovecot peut aussi utilise dnotify, inotify et kqueue pour -trouver immédiatement les changements. La valeur par défaut est @samp{"30 -secs"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mail-save-crlf? -Sauvegarder les courriels avec CR+LF plutôt que seulement LF. Cela permet -de consommer moins de CPU en envoyant ces courriels, surtout avec l'appel -système sendfile() de Linux et FreeBSD. Mais cela crée un peu plus -d'utilisation du disque, ce qui peut aussi le ralentir. Remarquez aussi que -si d'autres logiciels lisent les mbox/maildirs, ils peuvent se tromper dans -leur traitement de ces CR supplémentaires et causer des problèmes. La -valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean maildir-stat-dirs? -Par défaut la commande LIST renvoie toutes les entrées du maildir qui -commencent par un point. Activer cette option permet à Dovecot de renvoyer -uniquement les entrées qui sont des répertoires. Cela se fait avec stat() -sur chaque entrée, ce qui cause plus d'utilisation du disque. For systems -setting struct @samp{dirent->d_type} this check is free and it's done always -regardless of this setting). La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean maildir-copy-with-hardlinks? -Lors de la copie d'un message, le faire avec des liens en dur si possible. -Cela améliore un peu la performance et n'a que peu de chance d'avoir des -effets secondaires. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean maildir-very-dirty-syncs? -Suppose que Dovecot est le seul MUA qui accède à Maildir : scanne le -répertoire cur/ seulement lorsque son mtime change de manière inattendue ou -lorsqu'il ne peut pas trouver le courriel autrement. La valeur par défaut -est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list mbox-read-locks -La méthode de verrouillage à utiliser pour verrouiller le boîtes aux lettres -mbox. Il y en a quatre : - -@table @code -@item dotlock -Crée un fichier .lock. C'est la solution la plus ancienne et la -plus sûr pour NFS. Si vous voulez utiliser /var/mail/, les utilisateurs -auront besoin de l'accès en écriture à ce répertoire. -@item dotlock-try -Comme pour dotlock, mais si elle échoue à cause d'un problème de permission -ou parce qu'il n'y a pas assez d'espace disque, l'ignore. -@item fcntl -Utilisez cette méthode si possible. Elle fonctionne aussi avec NFS si vous -utilisez lockd. -@item flock -Peut ne pas exister sur tous les systèmes. Ne fonctionne pas avec NFS. -@item lockf -Peut ne pas exister sur tous les systèmes. Ne fonctionne pas avec NFS. -@end table - -Vous pouvez utiliser plusieurs méthodes de verrouillage ; dans ce cas -l'ordre dans lequel elles sont déclarées est important pour éviter des -interblocages si d'autres MTA/MUA utilisent aussi plusieurs méthodes. -Certains systèmes d'exploitation ne permettent pas d'utiliser certaines -méthodes en même temps. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list mbox-write-locks - -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mbox-lock-timeout -Temps d'attente maximal pour un verrou (tous les verrous) avant -d'abandonner. La valeur par défaut est @samp{"5 mins"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mbox-dotlock-change-timeout -Si le fichier dotlock existe mais que la boîte aux lettres n'est pas -modifiée, remplacer le fichier de verrouillage après ce temps d'attente. La -valeur par défaut est @samp{"2 mins"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mbox-dirty-syncs? -Lorsqu'un mbox change ne manière inattendue, il faut le lire en entier pour -savoir ce qui a changé. Si le mbox est assez grand cela peut prendre -beaucoup de temps. Comme le changement est habituellement un simple -courriel supplémentaire, il serait plus rapide de lire le nouveaux -courriels. Si ce paramètre est activé, Dovecot fait cela mais revient -toujours à relire le fichier mbox complet si le fichier n'est pas comme -attendu. Le seul réel inconvénient à ce paramètre est que certains MUA -changent les drapeaux des messages, et dans ce cas Dovecot ne s'en rend pas -immédiatement compte. Remarquez qu'une synchronisation complète est -effectuée avec les commandes SELECT, EXAMINE, EXPUNGE et CHECK. La valeur -par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mbox-very-dirty-syncs? -Comme @samp{mbox-dirty-syncs}, mais ne synchronise pas complètement même -avec les commandes SELECT, EXAMINE, EXPUNGE ou CHECK. Si l'option n'est pas -activée, @samp{mbox-dirty-syncs} est ignorée. La valeur par défaut est -@samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mbox-lazy-writes? -Attendre avant d'écrire les en-têtes mbox jusqu'à la prochaine -synchronisation des écritures (les commandes EXPUNGE et CHECK et quand on -ferme la boîte aux lettres). C'est surtout utile pour POP3 où les clients -suppriment souvent tous les courriels. L'inconvénient c'est que vos -changements ne sont pas immédiatement visibles pour les autres MUA. La -valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer mbox-min-index-size -Si la taille du fichier mbox est plus petite que cela (p.@: ex.@: 100k), ne -pas écrire de fichier d'index. Si un fichier d'index existe déjà il est -toujours lu, mais pas mis à jour. La valeur par défaut est @samp{0}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer mdbox-rotate-size -Taille du fichier dbox maximale avant rotation. La valeur par défaut est -@samp{10000000}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mdbox-rotate-interval -Âge maximum du fichier dbox avant rotation. Typiquement en jours. Les -jours commencent à minuit, donc 1d signifie aujourd'hui, 2d pour hier, etc. -0 pour désactiver la vérification. La valeur par défaut est @samp{"1d"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean mdbox-preallocate-space? -Lors de la création des fichiers mdbox, préallouer immédiatement leur taille -à @samp{mdbox-rotate-size}. Ce paramètre ne fonctionne actuellement que -dans Linux avec certains systèmes de fichiers (ext4, xfs). La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-attachment-dir -Les formats sdbox et mdbox supportent la sauvegarde des pièces-jointes dans -des fichiers externes, ce qui permet de les stocker une seule fois. Les -autres moteurs ne le supportent pas pour le moment. - -ATTENTION : Cette fonctionnalité n'a pas été beaucoup testée. Utilisez-la à -vos risques et périls. - -Racine du répertoire où stocker les pièces-jointes. Désactivé si vide. La -valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer mail-attachment-min-size -Les pièces-jointes plus petites que cela ne sont pas enregistrées à part. -Il est aussi possible d'écrire un greffon pour désactiver l'enregistrement -externe de certaines pièces-jointes spécifiques. La valeur par défaut est -@samp{128000}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-attachment-fs -Moteur du système de fichier à utiliser pour sauvegarder les pièces-jointes -: -@table @code -@item posix -Pas de SiS (single instance storage) par Dovecot (mais cela peut aider la -déduplication du système de fichier) -@item sis posix -SiS avec comparaison bit-à-bit immédiate pendant la sauvegarde -@item sis-queue posix -SiS avec déduplication et comparaison différées. -@end table -La valeur par défaut est @samp{"sis posix"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-attachment-hash -Format de hash à utiliser dans les noms de fichiers des pièces-jointes. -Vous pouvez ajouter n'importe quel texte ou variable : @code{%@{md4@}}, -@code{%@{md5@}}, @code{%@{sha1@}}, @code{%@{sha256@}}, @code{%@{sha512@}}, -@code{%@{size@}}. Les variables peuvent être tronquées, p.@: ex.@: -@code{%@{sha256:80@}} renvoie seulement les 80 premiers bits. La valeur par -défaut est @samp{"%@{sha1@}"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer default-process-limit - -La valeur par défaut est @samp{100}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer default-client-limit - -La valeur par défaut est @samp{1000}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer default-vsz-limit -Limite VSZ (taille mémoire virtuelle) par défaut pour les processus de -service. C'est surtout pour attraper et tuer les processus qui font fuiter -la mémoire avant qu'ils ne l'utilisent en entier. La valeur par défaut est -@samp{256000000}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string default-login-user -Utilisateur de connexion utilisé en interne par les processus de connexion. -C'est l'utilisateur avec la confiance minimale pour Dovecot. Il ne devrait -avoir accès à rien du tout. La valeur par défaut est @samp{"dovenull"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string default-internal-user -Utilisateur utilisé en interne par les processus non privilégiés. Il -devrait être différent de l'utilisateur de connexion, pour que les processus -de connexion ne puissent pas perturber les autres processus. La valeur par -défaut est @samp{"dovecot"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl? -Support SSL/TLS : yes, no, required. . La valeur par -défaut est @samp{"required"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-cert -Certificat SSL/TLS X.509 encodé en PEM (clef publique). La valeur par -défaut est @samp{" was automatically -rejected:%n%r"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string recipient-delimiter -Caractère de délimitation entre la partie locale et le détail des adresses -de courriel. La valeur par défaut est @samp{"+"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string lda-original-recipient-header -En-tête où l'adresse du destinataire d'origine (l'adresse RCPT TO de SMTP) -est récupérée si elle n'est pas disponible ailleurs. Le paramètre -a de -dovecot-lda le remplace. L'en-tête couramment utilisée pour cela est -X-Original-To. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean lda-mailbox-autocreate? -Sauvegarder un courriel dans un fichier qui n'existe pas devrait-il le créer -? La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean lda-mailbox-autosubscribe? -Devrait-on aussi se souscrire aux boîtes aux lettres nouvellement créées ? -La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} non-negative-integer imap-max-line-length -Longueur maximale de la ligne de commande IMAP. Certains clients génèrent -des lignes de commandes très longues avec des boîtes aux lettres énormes, -donc vous pourriez avoir besoin d'augmenter cette limite si vous obtenez les -erreurs « Too long argument » ou « IMAP command line too large ». La valeur -par défaut est @samp{64000}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string imap-logout-format -Format de la chaîne de déconnexion IMAP : -@table @code -@item %i -nombre d'octets lus par le client -@item %o -nombre total d'octets envoyés au client. -@end table -Voir @file{doc/wiki/Variables.txt} pour une liste de toutes les variables -utilisables. La valeur par défaut est @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 {paramètre de @code{dovecot-configuration}} string imap-capability -Remplace la réponse CAPABILITY d'IMAP. Si la valeur commence par « + », -ajoute les capacités données en haut des valeur par défaut (p.@: ex.@: +XFOO -XBAR). La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string imap-idle-notify-interval -Temps d'attente entre les notifications « OK Still here » lorsque le client -est en IDLE. La valeur par défaut est @samp{"2 mins"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string imap-id-send -Noms des champs ID et de leur valeur à envoyer aux clients. « * » signifie -la valeur par défaut. Les champs suivants ont actuellement des valeurs par -défaut : name, version, os, os-version, support-url, support-email. La -valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string imap-id-log -Champs ID envoyés par le client à enregistrer. « * » signifie tout. La -valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} space-separated-string-list imap-client-workarounds -Contournements pour divers bogues de certains client : - -@table @code -@item delay-newmail -Envoi des notifications de nouveau message EXISTS/RECENT seulement en -réponse aux commandes NOOP et CHECK. Certains clients les ignorent -autrement, par exemple OSX Mail (< v2.1). Outlook Express est encore plus -cassé, sans cela il peut montrer des erreurs de type « Le message n'est plus -sur le serveur ». Remarquez que OE6 est toujours cassé même avec ce -contournement si la synchronisation est à « En-têtes seulement ». - -@item tb-extra-mailbox-sep -Thunderbird se mélange les pinceaux avec LAYOUT=fs (mbox et dbox) et ajoute -un suffixe @samp{/} supplémentaire sur les noms des boîtes aux lettres. -Cette option fait que dovecot ignore le @samp{/} supplémentaire au lieu de -le traiter comme un nom de boîte aux lettres invalide. - -@item tb-lsub-flags -Montre les drapeaux \Noselect pour les réponses LSUB avec LAYOUT=fs (p.@: -ex.@: mbox). Cela fait que Thunderbird réalise qu'ils ne sont pas -sélectionnables et les montre en grisé, au lieu de montrer un popup « non -sélectionnable » après coup. -@end table -La valeur par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string imap-urlauth-host -Hôte autorisé dans les URL URLAUTH envoyés par les clients. « * » les -autorise tous. La valeur par défaut est @samp{""}. -@end deftypevr - - -Ouf ! Tant d'options de configuration. La bonne nouvelle, c'est que Guix a -une interface complète avec le langage de configuration de Dovecot. Cela -permet non seulement de déclarer la configuration de manière agréable, mais -aussi d'offrir des capacités de réflexion : les utilisateurs peuvent écrire -du code pour inspecter et transformer les configuration depuis Scheme. - -Cependant, vous pourriez avoir un fichier @code{dovecot.conf} déjà tout -prêt. Dans ce cas, vous pouvez passer un objet -@code{opaque-dovecot-configuration} comme paramètre @code{#:config} à -@code{dovecot-service}. Comme son nom l'indique, une configuration opaque -n'a pas les capacités de réflexions. - -Les champs de @code{opaque-dovecot-configuration} disponibles sont : - -@deftypevr {paramètre de @code{opaque-dovecot-configuration}} package dovecot -Le paquet dovecot. -@end deftypevr - -@deftypevr {paramètre de @code{opaque-dovecot-configuration}} string string -Le contenu de @code{dovecot.conf}, en tant que chaîne de caractères. -@end deftypevr - -Par exemple, si votre @code{dovecot.conf} est simplement la chaîne vide, -vous pouvez instancier un service dovecot comme cela : - -@example -(dovecot-service #:config - (opaque-dovecot-configuration - (string ""))) -@end example - -@subsubheading Service OpenSMTPD - -@deffn {Variable Scheme} opensmtpd-service-type -C'est le type de service de @uref{https://www.opensmtpd.org, OpenSMTPD}, -dont la valeur devrait être un objet @code{opensmtpd-configuration} comme -dans cet exemple : - -@example -(service opensmtpd-service-type - (opensmtpd-configuration - (config-file (local-file "./my-smtpd.conf")))) -@end example -@end deffn - -@deftp {Type de données} opensmtpd-configuration -Type de données représentant la configuration de opensmtpd. - -@table @asis -@item @code{package} (par défaut : @var{opensmtpd}) -Objet de paquet du serveur SMTP OpenSMTPD. - -@item @code{config-file} (par défaut : @var{%default-opensmtpd-file}) -Objet simili-fichier du fichier de configuration de OpenSMTPD à utiliser. -Par défaut il écoute sur l'interface de boucle locale et accepte les -courriels des utilisateurs et des démons de la machine locale, et autorise -l'envoi de courriels à des serveurs distants. Lancez @command{man -smtpd.conf} pour plus d'information. - -@end table -@end deftp - -@subsubheading Service Exim - -@cindex agent de transfert de courriel (MTA) -@cindex MTA (agent de transfert de courriel) -@cindex SMTP - -@deffn {Variable Scheme} exim-service-type -C'est le type de l'agent de transfert de courriel (MTA) -@uref{https://exim.org, Exim}, dont la valeur devrait être un objet -@code{exim-configuration} comme dans cet exemple : - -@example -(service exim-service-type - (exim-configuration - (config-file (local-file "./my-exim.conf")))) -@end example -@end deffn - -Pour utilise le service @code{exim-service-type} vous devez aussi avoir un -service @code{mail-aliases-service-type} dans votre @code{operating-system} -(même sans alias). - -@deftp {Type de données} exim-configuration -Type de données représentant la configuration d'exim. - -@table @asis -@item @code{package} (par défaut : @var{exim}) -Objet de paquet du serveur Exim. - -@item @code{config-file} (par défaut : @code{#f}) -Objet simili-fichier du fichier de configuration d'Exim à utiliser. Si sa -valeur est @code{#f} alors le service utilisera la configuration par défaut -du paquet fournit dans @code{package}. Le fichier de configuration qui en -résulte est chargé après avoir mis en place les variables de configuration -@code{exim_user} et @code{exim_group}. - -@end table -@end deftp - -@subsubheading Service d'alias de courriel - -@cindex alias de courriel -@cindex alias, pour les adresses de courriel - -@deffn {Variable Scheme} mail-aliases-service-type -C'est le type de service qui fournit @code{/etc/aliases} et qui spécifie -comment délivrer les courriels aux utilisateurs du système. - -@example -(service mail-aliases-service-type - '(("postmaster" "bob") - ("bob" "bob@@example.com" "bob@@example2.com"))) -@end example -@end deffn - -La configuration pour un service @code{mail-aliases-service-type} est une -liste associative qui dénote comment délivrer les courriels qui arrivent au -système. Chaque entrée est de la forme @code{(alias adresses ...)} avec -@code{alias} qui spécifie l'alias local et @code{adresses} qui spécifie où -délivrer les courriels de cet utilisateur. - -Les alias n'ont pas besoin de correspondre à des utilisateurs locaux du -système. Dans l'exemple au-dessus, il n'y a pas besoin d'une entrée -@code{postmaster} dans la liste @code{user-accounts} du -@code{operating-system} pour délivrer les courriels à destination de -@code{postmaster} à @code{bob} (qui ensuite délivrerait le courriel à -@code{bob@@example.com} et @code{bob@@example2.com}). - -@subsubheading Démon IMAP4 GNU Mailutils -@cindex Démon IMAP4 GNU Mailutils - -@deffn {Variable Scheme} imap4d-service-type -C'est le type du démon IMAP4 GNU Mailutils, dont la valeur devrait être un -objet @code{imap4d-configuration} comme dans cet exemple : - -@example -(service imap4d-service-type - (imap4d-configuration - (config-file (local-file "imap4d.conf")))) -@end example -@end deffn - -@deftp {Type de données} imap4d-configuration -Type de données représentant la configuration de @command{imap4d}. - -@table @asis -@item @code{package} (par défaut : @code{mailutils}) -Le paquet qui fournit @command{imap4d}. - -@item @code{config-file} (par défaut : @code{%default-imap4d-config-file}) -Objet simili-fichier du fichier de configuration à utiliser. Par défaut, la -configuration fera écouter sur le port TCP 143 sur @code{localhost}. -@xref{Conf-imap4d,,, mailutils, GNU Mailutils Manual}, pour les détails. - -@end table -@end deftp - -@node Services de messagerie -@subsection Services de messagerie - -@cindex messagerie instantanée -@cindex jabber -@cindex XMPP -Le module @code{(gnu services messaging)} fournit des définitions de -services Guix pour les services de messageries instantanées : actuellement -seul Prosody est supporté. - -@subsubheading Service Prosody - -@deffn {Variable Scheme} prosody-service-type -C'est le type pour le @uref{https://prosody.im, le serveur de communication -XMPP Prosody}. Sa valeur doit être un enregistrement -@code{prosody-configuration} comme dans cet exemple : - -@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 - -Voir plus bas pour des détails sur @code{prosody-configuration}. - -@end deffn - -Par défaut, Prosody n'a pas besoin de beaucoup de configuration. Seul un -champ @code{virtualhosts} est requis : il spécifie le domaine que vous -voulez voir Prosody servir. - -Vous pouvez effectuer plusieurs vérifications de la configuration générée -avec la commande @code{prosodyctl check}. - -Prosodyctl vous aidera aussi à importer des certificats du répertoire -@code{letsencrypt} pour que l'utilisateur @code{prosody} puisse y accéder. -Voir @url{https://prosody.im/doc/letsencrypt}. - -@example -prosodyctl --root cert import /etc/letsencrypt/live -@end example - -Les paramètres de configuration disponibles sont les suivants. Chaque -définition des paramètres est précédé par son type ; par exemple, -@samp{string-list foo} indique que le paramètre @code{foo} devrait être -spécifié comme une liste de chaînes de caractères. Les types précédés de -@code{maybe-} signifient que le paramètre n'apparaîtra pas dans -@code{prosody.cfg.lua} lorsque sa valeur est @code{'disabled}. - -Il y a aussi une manière de spécifier la configuration en tant que chaîne de -caractères si vous avez un vieux fichier @code{prosody.cfg.lua} que vous -voulez porter depuis un autre système ; voir la fin pour plus de détails. - -Le type @code{file-object} désigne soit un objet simili-fichier -(@pxref{G-Expressions, file-like objects}), soit un nom de fichier. - -@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. - -Les champs de @code{prosody-configuration} disponibles sont : - -@deftypevr {paramètre de @code{prosody-configuration}} package prosody -Le paquet Prosody. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} file-name data-path -Emplacement du répertoire de stockage des données de Prosody. Voir -@url{https://prosody.im/doc/configure}. La valeur par défaut est -@samp{"/var/lib/prosody"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} file-object-list plugin-paths -Répertoires de greffons supplémentaires. Ils sont analysés dans l'ordre -spécifié. Voir @url{https://prosody.im/doc/plugins_directory}. La valeur -par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} file-name certificates -Chaque hôte virtuel et composant a besoin d'un certificat pour que les -clients et les serveurs puissent vérifier son identité. Prosody chargera -automatiquement les clefs et les certificats dans le répertoire spécifié -ici. La valeur par défaut est @samp{"/etc/prosody/certs"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string-list admins -C'est une liste des comptes administrateurs de ce serveur. Remarquez que -vous devez créer les comptes séparément. Voir -@url{https://prosody.im/doc/admins} et -@url{https://prosody.im/doc/creating_accounts}. Par exemple : @code{(admins -'("user1@@example.com" "user2@@example.net"))}. La valeur par défaut est -@samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} boolean use-libevent? -Active l'utilisation de libevent pour de meilleures performances sous une -forte charge. Voir @url{https://prosody.im/doc/libevent}. La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} module-list modules-enabled -C'est la liste des modules que Prosody chargera au démarrage. Il cherchera -@code{mod_modulename.lua} dans le répertoire des greffons, donc assurez-vous -qu'il existe aussi. La documentation des modules se trouve sur -@url{https://prosody.im/doc/modules}. La valeur par défaut est -@samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" -"blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" -"admin_adhoc")}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string-list modules-disabled -@samp{"offline"},@samp{"c2s"} et @samp{"s2s"} sont chargés automatiquement, -mais si vous voulez les désactiver, ajoutez-les à cette liste. La valeur -par défaut est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} file-object groups-file -Chemin vers un fichier texte où les groupes partagés sont définis. Si ce -chemin est vide alors @samp{mod_groups} ne fait rien. Voir -@url{https://prosody.im/doc/modules/mod_groups}. La valeur par défaut est -@samp{"/var/lib/prosody/sharedgroups.txt"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} boolean allow-registration? -Désactive la création de compte par défaut, pour la sécurité. Voir -@url{https://prosody.im/doc/creating_accounts}. La valeur par défaut est -@samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} maybe-ssl-configuration ssl -Ce sont les paramètres liés à SSL/TLS. La plupart sont désactivés pour -pouvoir utiliser les paramètres par défaut de Prosody. Si vous ne comprenez -pas complètement ces options, ne les ajoutez pas à votre configuration, il -est aisé de diminuer la sécurité de votre serveur en les modifiant. Voir -@url{https://prosody.im/doc/advanced_ssl_config}. - -Les champs de @code{ssl-configuration} disponibles sont : - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string protocol -Cela détermine la poignée de main à utiliser. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-file-name key -Chemin vers votre fichier de clef privée. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-file-name certificate -Chemin vers votre fichier de certificat. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} file-object capath -Chemin vers le répertoire contenant les certificats racines que vous voulez -voir Prosody utiliser lors de la vérification des certificats des serveurs -distants. La valeur par défaut est @samp{"/etc/ssl/certs"}. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-file-object cafile -Chemin vers un fichier contenant les certificats racines auxquels Prosody -devra faire confiance. Comme @code{capath} mais avec les certificats -concaténés ensemble. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string-list verify -Une liste d'options de vérification (qui correspondent globalement aux -drapeaux @code{set_verify()} d'OpenSSL). -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string-list options -Une liste d'options générales liées à SSL/TLS. Elles correspondent -globalement à @code{set_options()} d'OpenSSL. Pour une liste complète des -options disponibles dans LuaSec, voir les sources de LuaSec. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-non-negative-integer depth -Longueur maximale d'une chaîne d'autorités de certifications avant la -racine. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string ciphers -Une chaîne de méthodes de chiffrement OpenSSL. Cela choisi les méthodes de -chiffrement que Prosody offrira aux clients, et dans quel ordre de -préférence. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-file-name dhparam -Un chemin vers un fichier contenant les paramètres pour l'échange de clef -Diffie-Hellman. Vous pouvez créer un tel fichier avec : @code{openssl -dhparam -out /etc/prosody/certs/dh-2048.pem 2048} -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string curve -Courbe pour Diffie-Hellman sur courbe elliptique. La valeur par défaut de -Prosody est @samp{"secp384r1"}. -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string-list verifyext -Une liste d'options de vérification « supplémentaires ». -@end deftypevr - -@deftypevr {paramètre de @code{ssl-configuration}} maybe-string password -Mot de passe pour les clefs privées chiffrées. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} boolean c2s-require-encryption? -S'il faut forcer toutes les connexions client-serveur à être chiffrées ou -non. Voir @url{https://prosody.im/doc/modules/mod_tls}. La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string-list disable-sasl-mechanisms -Ensemble de mécanismes qui ne seront jamais offerts. Voir -@url{https://prosody.im/doc/modules/mod_saslauth}. La valeur par défaut est -@samp{("DIGEST-MD5")}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} boolean s2s-require-encryption? -S'il faut forcer toutes les connexion serveur-serveur à être chiffrées ou -non. Voir @url{https://prosody.im/doc/modules/mod_tls}. La valeur par -défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} boolean s2s-secure-auth? -S'il faut requérir le chiffrement et l'authentification du certificat. Cela -fournit une sécurité idéale, mais demande que les serveurs avec lesquels -vous communiquez supportent le chiffrement ET présentent un certificat -valide et de confiance. Voir @url{https://prosody.im/doc/s2s#security}. La -valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string-list s2s-insecure-domains -Beaucoup de serveurs ne supportent pas le chiffrement ou ont un certificat -invalide ou auto-signé. Vous pouvez lister les domaines ici qui n'ont pas -besoin de s'authentifier avec des certificats. Ils seront authentifiés par -DNS. Voir @url{https://prosody.im/doc/s2s#security}. La valeur par défaut -est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string-list s2s-secure-domains -Même si vous laissez @code{s2s-secure-auth?} désactivé, vous pouvez toujours -demander un certificat valide pour certains domaine en spécifiant la liste -ici. Voir @url{https://prosody.im/doc/s2s#security}. La valeur par défaut -est @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string authentication -Choisi le moteur d'authentification à utiliser. Le moteur par défaut stocke -les mots de passes en texte clair et utilise la configuration de stockage -des données de Prosody pour stocker les données authentifiées. Si vous -n'avez pas confiance dans le serveur, lisez -@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} pour plus -d'information sur l'utilisation du moteur hashed. Voir aussi -@url{https://prosody.im/doc/authentication}. La valeur par défaut est -@samp{"internal_plain"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} maybe-string log -Indique les options de journalisation. La configuration avancée des -journaux n'est pas encore supportée par le service Prosody. Voir -@url{https://prosody.im/doc/logging}. La valeur par défaut est -@samp{"*syslog"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} file-name pidfile -Fichier où écrire le PID. Voir -@url{https://prosody.im/doc/modules/mod_posix}. La valeur par défaut est -@samp{"/var/run/prosody/prosody.pid"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} maybe-non-negative-integer http-max-content-size -Taille maximum autorisée pour le corps HTTP (en octets). -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} maybe-string http-external-url -Certains modules exposent leur propre URL de diverses manières. Cette URL -est construite à partir du protocole, de l'hôte et du port utilisé. Si -Prosody se trouve derrière un proxy, l'URL publique sera -@code{http-external-url} à la place. Voir -@url{https://prosody.im/doc/http#external_url}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} virtualhost-configuration-list virtualhosts -Un hôte dans Prosody est un domaine sur lequel les comptes utilisateurs sont -créés. Par exemple si vous voulez que vos utilisateurs aient une adresse -comme @samp{"john.smith@@example.com"} vous devrez ajouter un hôte -@samp{"example.com"}. Toutes les options de cette liste seront appliquées -uniquement à cet hôte. - -Remarque : le nom d'hôte « virtuel » est utilisé dans la configuration pour -éviter de le confondre avec le nom d'hôte physique réel de la machine qui -héberge Prosody. Une seule instance de Prosody peut servir plusieurs -domaines, chacun défini comme une entrée VirtualHost dans la configuration -de Prosody. Ainsi, un serveur qui n'héberge qu'un seul domaine n'aura -qu'une entrée VirtualHost. - -Voir @url{https://prosody.im/doc/configure#virtual_host_settings}. - -Les champs de @code{virtualhost-configuration} disponibles sont : - -tous ces champs de @code{prosody-configuration} : @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 {paramètre de @code{virtualhost-configuration}} string domain -Domaine que vous souhaitez que Prosody serve. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} int-component-configuration-list int-components -Les composant sont des services supplémentaires qui sont disponibles pour -les clients, habituellement sur un sous-domaine du serveur principal (comme -@samp{"mycomponent.example.com"}). Des exemples de composants sont des -serveurs de chatroom, des répertoires utilisateurs ou des passerelles vers -d'autres protocoles. - -Les composants internes sont implémentés dans des greffons spécifiques à -Prosody. Pour ajouter un composant interne, vous n'avez qu'à remplir le -champ de nom d'hôte et le greffon que vous voulez utiliser pour le -composant. - -Voir @url{https://prosody.im/doc/components}. La valeur par défaut est -@samp{()}. - -Les champs de @code{int-component-configuration} disponibles sont : - -tous ces champs de @code{prosody-configuration} : @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 {paramètre de @code{int-component-configuration}} string hostname -Nom d'hôte du composant. -@end deftypevr - -@deftypevr {paramètre de @code{int-component-configuration}} string plugin -Greffon que vous voulez utiliser pour ce composant. -@end deftypevr - -@deftypevr {paramètre de @code{int-component-configuration}} maybe-mod-muc-configuration mod-muc -Le chat multi-utilisateur (MUC) est le modules de Prosody qui vous permet de -créer des chatrooms/conférences pour les utilisateurs XMPP. - -Des informations générales sur la configuration des chatrooms -multi-utilisateurs se trouvent dans la documentation sur les chatrooms -(@url{https://prosody.im/doc/chatrooms}), que vous devriez lire si vous les -découvrez. - -Voir aussi @url{https://prosody.im/doc/modules/mod_muc}. - -Les champs de @code{mod-muc-configuration} disponibles sont : - -@deftypevr {paramètre de @code{mod-muc-configuration}} string name -Le nom à renvoyer dans les réponses de découverte de services. La valeur -par défaut est @samp{"Prosody Chatrooms"}. -@end deftypevr - -@deftypevr {paramètre de @code{mod-muc-configuration}} string-or-boolean restrict-room-creation -Si la valeur est @samp{#t}, cela permettra uniquement aux admins de créer de -nouveaux salons. Sinon n'importe qui peut créer un salon. La valeur -@samp{"local"} restreint la création aux utilisateurs du domaine parent du -service. P.@: ex.@: @samp{user@@example.com} peut créer des salons sur -@samp{rooms.example.com}. La valeur @samp{"admin"} restreint ce service aux -administrateurs. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{mod-muc-configuration}} non-negative-integer max-history-messages -Nombre maximum de messages d'historique qui seront envoyés aux membres qui -viennent de rejoindre le salon. La valeur par défaut est @samp{20}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} ext-component-configuration-list ext-components -Les composants externes utilisent XEP-0114, que la plupart des composants -supportent. Pour ajouter un composant externe, vous remplissez simplement -le champ de nom d'hôte. Voir @url{https://prosody.im/doc/components}. La -valeur par défaut est @samp{()}. - -Les champs de @code{ext-component-configuration} disponibles sont : - -tous ces champs de @code{prosody-configuration} : @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 {paramètre de @code{ext-component-configuration}} string component-secret -Mot de passe que le composant utilisera pour s'authentifier. -@end deftypevr - -@deftypevr {paramètre de @code{ext-component-configuration}} string hostname -Nom d'hôte du composant. -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} non-negative-integer-list component-ports -Ports sur lesquels Prosody écoutera les connexions des composants. La -valeur par défaut est @samp{(5347)}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} string component-interface -Interface sur laquelle Prosody écoutera les connexions des composants. La -valeur par défaut est @samp{"127.0.0.1"}. -@end deftypevr - -@deftypevr {paramètre de @code{prosody-configuration}} maybe-raw-content raw-content -Contenu brut qui sera ajouté au fichier de configuration. -@end deftypevr - -Il se peut que vous ayez juste envie de lancer un fichier -@code{prosody.cfg.lua} directement. Dans ce cas, vous pouvez passer un -enregistrement @code{opaque-prosody-configuration} comme valeur à -@code{prosody-service-type}. Comme son nom l'indique, une configuration -opaque n'a pas de capacités de réflexion simples. Les champs disponibles de -@code{opaque-prosody-configuration} sont : - -@deftypevr {paramètre de @code{opaque-prosody-configuration}} package prosody -Le paquet prosody. -@end deftypevr - -@deftypevr {paramètre de @code{opaque-prosody-configuration}} string prosody.cfg.lua -Le contenu de @code{prosody.cfg.lua} à utiliser. -@end deftypevr - -Par exemple, si votre @code{prosody.cfg.lua} est juste la chaîne vide, vous -pouvez instancier un service prosody comme ceci : - -@example -(service prosody-service-type - (opaque-prosody-configuration - (prosody.cfg.lua ""))) -@end example - -@c end of Prosody auto-generated documentation - -@subsubheading Service BitlBee - -@cindex IRC (Internet Relay Chat) -@cindex passerelle IRC -@url{http://bitlbee.org,BitlBee} est une passerelle qui fournit une -interface IRC vers une variété de protocoles de messagerie instantanée comme -XMPP. - -@defvr {Variable Scheme} bitlbee-service-type -C'est le type de service pour le démon de passerelle IRC -@url{http://bitlbee.org,BitlBee}. Sa valeur est un -@code{bitlbee-configuration} (voir plus bas). - -Pour que BitlBee écoute sur le port 6667 sur localhost, ajoutez cette ligne -à vos services : - -@example -(service bitlbee-service-type) -@end example -@end defvr - -@deftp {Type de données} bitlbee-configuration -C'est la configuration de BitlBee, avec les champs suivants : - -@table @asis -@item @code{interface} (par défaut : @code{"127.0.0.1"}) -@itemx @code{port} (par défaut : @code{6667}) -Écoute sur l'interface réseau correspondant à l'adresse IP dans -@var{interface}, sur @var{port}. - -Lorsque @var{interface} vaut @code{127.0.0.1}, seuls les clients locaux -peuvent se connecter ; lorsqu'elle vaut @code{0.0.0.0}, les connexions -peuvent venir de n'importe quelle interface réseau. - -@item @code{package} (par défaut : @code{bitlbee}) -Le paquet BitlBee à utiliser. - -@item @code{plugins} (par défaut : @code{'()}) -Liste des paquets de greffons à utiliser — p.@: ex.@: -@code{bitlbee-discord}. - -@item @code{extra-settings} (par défaut : @code{""}) -Partie de configuration ajoutée telle-quelle au fichier de configuration de -BitlBee. -@end table -@end deftp - -@subsubheading Service Quassel - -@cindex IRC (Internet Relay Chat) -@url{https://quassel-irc.org/,Quassel} est un client IRC distribué, ce qui -signifie qu'un client ou plus peuvent s'attacher et se détacher du cœur -central. - -@defvr {Variable Scheme} quassel-service-type -C'est le type de service pour le démon IRC -@url{https://quassel-irc.org/,Quassel}. Sa valeur est un -@code{quassel-configuration} (voir plus bas). -@end defvr - -@deftp {Type de données} quassel-configuration -C'est la configuration de Quassel, avec les champs suivants : - -@table @asis -@item @code{quassel} (par défaut : @code{quassel}) -Le paquet Quassel à utiliser. - -@item @code{interface} (par défaut : @code{"::,0.0.0.0"}) -@item @code{port} (par défaut : @code{4242}) -Écoute sur les interfaces réseau correspondant à l'adresse IPv4 ou IPv6 des -interfaces spécifiées dans @var{interface}, une liste de chaînes délimitées -par des virgules, sur @var{port}. - -@item @code{loglevel} (par défaut : @code{"info"}) -Le niveau de journalisation souhaité. Les valeurs acceptées sont « Debug », -« Info », « Warning » et « Error ». -@end table -@end deftp - -@node Services de téléphonie -@subsection Services de téléphonie - -@cindex Murmur (serveur VoIP) -@cindex serveur VoIP -Cette section décrit comment configurer et lancer un serveur Murmur. Murmur -est le serveur de la suite de voix-sur-IP (VoIP) @uref{https://mumble.info, -Mumble}. - -@deftp {Type de données} murmur-configuration -Le type de service pour le serveur Murmur. Voici un exemple de -configuration : - -@example -(service murmur-service-type - (murmur-configuration - (welcome-text - "Bienvenue sur ce serveur Mumble qui tourne sur Guix !") - (cert-required? #t) ;désactive les connections par mot de passe - (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") - (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) -@end example - -Après avoir reconfiguré votre système, vous pouvez manuellement indiquer le -mot de passe @code{SuperUser} de murmur avec la commande qui s'affiche -pendant la phase d'activation. - -Il est recommandé d'enregistrer un compte utilisateur Mumble normal et de -lui donner les droits admin ou modérateur. Vous pouvez utiliser le client -@code{mumble} pour vous connecter en tant que nouvel utilisateur normal, -vous enregistrer et vous déconnecter. Pour l'étape suivante, connectez-vous -avec le nom @code{SuperUser} en utilisant le mot de passe @code{SuperUser} -que vous avez indiqué précédemment et accordez les droits administrateur ou -modérateur à vous utilisateur mumble nouvellement enregistré et créez -quelques salons. - -Les champs de @code{murmur-configuration} disponibles sont : - -@table @asis -@item @code{package} (par défaut : @code{mumble}) -Paquet qui contient @code{bin/murmurd}. - -@item @code{user} (par défaut : @code{"murmur"}) -Utilisateur qui lancera le serveur Murmur. - -@item @code{group} (par défaut : @code{"murmur"}) -Groupe de l'utilisateur qui lancera le serveur Murmur. - -@item @code{port} (par défaut : @code{64738}) -Port sur lequel le serveur écoutera. - -@item @code{welcome-text} (par défaut : @code{""}) -Texte de bienvenue envoyé aux clients lors de leur connexion. - -@item @code{server-password} (par défaut : @code{""}) -Mot de passe que les clients devront entrer pour se connecter. - -@item @code{max-users} (par défaut : @code{100}) -Nombre maximum d'utilisateurs qui peuvent se connecter à ce serveur en même -temps. - -@item @code{max-user-bandwidth} (par défaut : @code{#f}) -Trafic de voix maximum qu'un utilisateur peut envoyer par seconde. - -@item @code{database-file} (par défaut : @code{"/var/lib/murmur/db.sqlite"}) -Nom de fichier de la base de données sqlite. L'utilisateur du service -deviendra propriétaire du répertoire. - -@item @code{log-file} (par défaut : @code{"/var/log/murmur/murmur.log"}) -Nom du fichier de journal. L'utilisateur du service deviendra propriétaire -du répertoire. - -@item @code{autoban-attempts} (par défaut : @code{10}) -Nombre maximum de connexions qu'un utilisateur peut faire pendant -@code{autoban-timeframe} sans être banni automatiquement pour -@code{autoban-time}. - -@item @code{autoban-timeframe} (par défaut : @code{120}) -Durée du temps pendant lequel le nombre de connexions est compté. - -@item @code{autoban-time} (par défaut : @code{300}) -Durée du bannissement automatique en secondes. - -@item @code{opus-threshold} (par défaut : @code{100}) -Pourcentage des clients qui doivent supporter opus avant de passer sur le -codec audio opus. - -@item @code{channel-nesting-limit} (par défaut : @code{10}) -Profondeur maximum des canaux. - -@item @code{channelname-regex} (par défaut : @code{#f}) -Une chaîne de la forme d'une expression régulière Qt que les noms de canaux -doivent respecter. - -@item @code{username-regex} (par défaut : @code{#f}) -Une chaîne de la forme d'une expression régulière Qt que les noms -d'utilisateurs doivent respecter. - -@item @code{text-message-length} (par défaut : @code{5000}) -Taille maximum en octets qu'un utilisateur peut envoyer en un seul message -textuel. - -@item @code{image-message-length} (par défaut : @code{(* 128 1024)}) -Taille maximum en octets qu'un utilisateur peut envoyer en une seule image. - -@item @code{cert-required?} (par défaut : @code{#f}) -Si la valeur est @code{#t} les clients utilisant une authentification par -mot de passe faible ne seront pas acceptés. Les utilisateurs doivent -compléter l'assistant de configuration des certificats pour rejoindre le -serveur. - -@item @code{remember-channel?} (paramètre de : @code{#f}) -Indique si murmur devrait se rappeler du dernier canal dans lequel étaient -les utilisateurs au moment de leur déconnexion et les y remettre lorsqu'ils -se reconnectent. - -@item @code{allow-html?} (par défaut : @code{#f}) -Indique si le html est autorisé dans les messages textuels, les commentaires -utilisateurs et les descriptions des canaux. - -@item @code{allow-ping?} (par défaut : @code{#f}) -Mettre à vrai expose le nombre d'utilisateurs, le nombre d'utilisateurs -maximum et la bande passante maximale du serveur par client aux utilisateurs -non connectés. Dans le client Mumble, cette information est affichée dans -la boîte de dialogue de connexion. - -Désactiver ce paramètre empêchera le serveur d'être publiquement listé. - -@item @code{bonjour?} (par défaut : @code{#f}) -Indique si le serveur se présente sur le réseau local à travers le protocole -bonjour. - -@item @code{send-version?} (par défaut : @code{#f}) -Indique si la version du serveur murmur doit être exposée dans les requêtes -ping. - -@item @code{log-days} (par défaut : @code{31}) -Murmur stocke aussi les journaux en base de données, qui sont accessible via -RPC. La valeur par défaut est 31 jours, mais vous pouvez le mettre à 0 pour -les garder pour toujours ou à -1 pour désactiver la journalisation dans la -base de données. - -@item @code{obfuscate-ips?} (par défaut : @code{#t}) -Indique si les IP enregistrées doivent être cachées pour protéger la vie -privée des utilisateurs. - -@item @code{ssl-cert} (par défaut : @code{#f}) -Nom de fichier du certificat SSL/TLS utilisé pour les connexions chiffrées. - -@example -(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") -@end example -@item @code{ssl-key} (par défaut : @code{#f}) -Chemin de fichier vers la clef privée ssl pour les connexions chiffrées. -@example -(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") -@end example - -@item @code{ssl-dh-params} (par défaut : @code{#f}) -Nom de fichier d'un fichier encodé en PEM avec les paramètres Diffie-Hellman -pour le chiffrement SSL/TLS. Autrement vous pouvez indiquer -@code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, -@code{"@@ffdhe6144"} ou @code{"@@ffdhe8192"} pour utiliser les paramètres -inclus de la RFC 7919. - -@item @code{ssl-ciphers} (par défaut : @code{#f}) -L'option @code{ssl-ciphers} permet de choisir les suites de chiffrement -disponibles pour SSL/TLS. - -Cette option est spécifiée en utilisant -l'@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, -OpenSSL cipher list notation} - -Nous vous recommandons d'essayer votre chaîne de suites de chiffrements avec -« openssl ciphers » avant de l'indiquer ici, pour avoir une idée -des suites de chiffrement que vous aurez. Après avoir indiqué cette option, -nous vous recommandons d'inspecter les journaux de Murmur pour vous assurer -que Murmur utilise les suites de chiffrements auxquelles vous vous attendez. - -Remarque : modifier cette option peut impacter la rétrocompatibilité de -votre serveur Murmur, et peut empêcher que des clients Mumble anciens se -connectent. - -@item @code{public-registration} (par défaut : @code{#f}) -Doit être un enregistrement -@code{} ou @code{#f}. - -Vous pouvez aussi enregistrer votre serveur dans la liste des serveurs -publiques que le client @code{mumble} affiche au démarrage. Vous ne pouvez -pas enregistrer votre serveur si vous avez un @code{server-password} ou -@code{allow-ping} à @code{#f}. - -Cela peut prendre quelques heures avant d'arriver sur la liste publique. - -@item @code{file} (par défaut : @code{#f}) -Version alternative de cette configuration : si vous indiquez quelque chose, -le reste est ignoré. -@end table -@end deftp - -@deftp {Type de données} murmur-public-registration-configuration -Configuration pour l'enregistrement public du service murmur. - -@table @asis -@item @code{name} -C'est le nom d'affichage de votre serveur. Ne pas le confondre avec le nom -d'hôte. - -@item @code{password} -Un mot de passe pour identifier votre enregistrement. Les mises à jours -suivantes devront utiliser le même mot de passe. Ne le perdez pas. - -@item @code{url} -Cela devrait être le lien @code{http://} ou @code{https://} vers votre site -web. - -@item @code{hostname} (par défaut : @code{#f}) -Par défaut votre serveur sera listé par son adresse IP. Si cette option est -indiquée votre serveur sera listé par son nom d'hôte. -@end table -@end deftp - - - -@node Services de surveillance -@subsection Services de surveillance - -@subsubheading Service Tailon - -@uref{https://tailon.readthedocs.io/, Tailon} est une application web pour -visualiser et chercher des fichiers de journaux. - -L'exemple suivant configurera le service avec les valeurs par défaut. Par -défaut, on peut accéder à Tailon sur le pour 8080 -(@code{http://localhost:8080}). - -@example -(service tailon-service-type) -@end example - -L'exemple suivant personnalise un peu plus la configuration de Tailon, en -ajoutant @command{sed} à la liste des commandes autorisées. - -@example -(service tailon-service-type - (tailon-configuration - (config-file - (tailon-configuration-file - (allowed-commands '("tail" "grep" "awk" "sed")))))) -@end example - - -@deftp {Type de données} tailon-configuration -Type de données représentant la configuration de Tailon. Ce type a les -paramètres suivants : - -@table @asis -@item @code{config-file} (par défaut : @code{(tailon-configuration-file)}) -Le fichier de configuration à utiliser pour Tailon. Ce champ peut contenir -un enregistrement @dfn{tailon-configuration-file} ou n'importe quelle gexp -(@pxref{G-Expressions}). - -Par exemple, pour utiliser un fichier local à la place, on peut utiliser la -fonction @code{local-file} : - -@example -(service tailon-service-type - (tailon-configuration - (config-file (local-file "./my-tailon.conf")))) -@end example - -@item @code{package} (par défaut : @code{tailon}) -Le paquet tailon à utiliser. - -@end table -@end deftp - -@deftp {Type de données} tailon-configuration-file -Type de données représentant les options de configuration de Tailon. Ce -type a les paramètres suivants : - -@table @asis -@item @code{files} (par défaut : @code{(list "/var/log")}) -Liste des fichiers à afficher. La liste peut inclure des chaînes pour des -fichiers simple ou des répertoires, ou une liste, où le premier élément est -le nom d'un sous-section et le reste des fichiers ou des répertoires de -cette sous-section. - -@item @code{bind} (par défaut : @code{"localhost:8080"}) -Adresse et port sur lesquels Tailon écoute. - -@item @code{relative-root} (par défaut : @code{#f}) -Chemin de l'URL à utiliser pour Tailon, ou @code{#f} pour ne pas utiliser de -chemin. - -@item @code{allow-transfers?} (par défaut : @code{#t}) -Permet de télécharger les journaux dans l'interface web. - -@item @code{follow-names?} (par défaut : @code{#t}) -Permet de surveiller des fichiers qui n'existent pas encore. - -@item @code{tail-lines} (par défaut : @code{200}) -Nombre de lignes à lire initialement dans chaque fichier. - -@item @code{allowed-commands} (par défaut : @code{(list "tail" "grep" "awk")}) -Commandes autorisées. Par défaut, @code{sed} est désactivé. - -@item @code{debug?} (par défaut : @code{#f}) -Configurez @code{debug?} à @code{#t} pour montrer les messages de débogage. - -@item @code{wrap-lines} (par défaut : @code{#t}) -État initial du retour à la ligne dans l'interface web. Configurez l'option -à @code{#t} pour retourner à la ligne (par défaut) ou à @code{#f} pour ne -pas retourner à la ligne au début. - -@item @code{http-auth} (par défaut : @code{#f}) -Type d'authentification HTTP à utiliser. Indiquez @code{#f} pour désactiver -l'authentification (par défaut). Les valeur supportées sont @code{"digest"} -et @code{"basic"}. - -@item @code{users} (par défaut : @code{#f}) -Si l'authentification HTTP est activée (voir @code{http-auth}), l'accès sera -restreint aux identifiants fournis ici. Pour configurer des utilisateurs, -utilisez une liste de paires, où le premier élément de la paire est le nom -d'utilisateur et le second élément est le mot de passe. - -@example -(tailon-configuration-file - (http-auth "basic") - (users '(("user1" . "password1") - ("user2" . "password2")))) -@end example - -@end table -@end deftp - - -@subsubheading Service Darkstat -@cindex darkstat -Darkstat est un « renifleur de paquets » qui capture le trafic réseau, -calcul des statistiques sur l'utilisation et sert des rapport sur HTTP. - -@defvar {Variable Scheme} darkstat-service-type -C'est le type de service pour le service -@uref{https://unix4lyfe.org/darkstat/, darkstat}, sa valeur doit être un -enregistrement @code{darkstat-configuration} comme dans cet exemple : - -@example -(service darkstat-service-type - (darkstat-configuration - (interface "eno1"))) -@end example -@end defvar - -@deftp {Type de données} darkstat-configuration -Type de données représentant la configuration de @command{darkstat}. - -@table @asis -@item @code{package} (par défaut : @code{darkstat}) -Le paquet darkstat à utiliser. - -@item @code{interface} -Capture le trafic sur l'interface réseau spécifiée. - -@item @code{port} (par défaut : @code{"667"}) -Lie l'interface web sur le port spécifié. - -@item @code{bind-address} (par défaut : @code{"127.0.0.1"}) -Lie l'interface web sur l'adresse spécifiée. - -@item @code{base} (par défaut : @code{"/"}) -Spécifie le chemin de base des URL. C'est utile si on accède à -@command{darkstat} à travers un proxy inverse. - -@end table -@end deftp - -@subsubheading Service d'export de nœud de Prometheus - -@cindex prometheus-node-exporter -L'exportateur de nœuds de Prometheus rend disponible les statistiques sur le -matériel et le système d'exploitation fournies par le noyau Linux pour le -système de surveillance Prometheus. Ce service devrait être déployé sur -tous les nœuds physiques et les machines virtuelles, où vous voulez -surveiller ces statistiques. - -@defvar {Variable Scheme} prometheus-node-exporter-service-type -C'est le type de service pour le service -@uref{https://github.com/prometheus/node_exporter/, -prometheus-node-exporter}, sa valeur doit être un enregistrement -@code{prometheus-node-exporter-configuration} comme dans cet exemple : - -@example -(service prometheus-node-exporter-service-type - (prometheus-node-exporter-configuration - (web-listen-address ":9100"))) -@end example -@end defvar - -@deftp {Type de données} prometheus-node-exporter-configuration -Type de données représentant la configuration de @command{node_exporter} - -@table @asis -@item @code{package} (par défaut : @code{go-github-com-prometheus-node-exporter}) -Le paquet prometheus-node-exporter à utiliser. - -@item @code{web-listen-address} (par défaut : @code{":9100"}) -Lie l'interface web sur l'adresse spécifiée. - -@end table -@end deftp - -@subsubheading Server zabbix -@cindex zabbix zabbix-server -Zabbix fournit des métriques de suivi entre autres de l'utilisation du -réseau, de la charge CPU et de l'espace disque : - -@itemize -@item Haute performance, haute capacité (il est capable de surveiller des centaines de milliers d'appareils). -@item Découverte automatique des serveurs, des appareils et leurs interfaces réseaux. -@item Découverte bas-niveau, qui permet de commencer automatiquement à surveiller de nouveaux éléments, des systèmes de fichiers ou des interfaces réseaux entre autres. -@item Surveillance distribuée avec une administration web centralisée. -@item Agents natifs haute-performance. -@item Métriques SLA et ITIL KPI dans les rapports. -@item Vue haut-niveau (businness) des ressources surveillées à travers des écrans de consoles visuelles définie par l'utilisateur et des panneaux de commande. -@item Exécution à distance à travers les mandataires Zabbix. -@end itemize - -@c %start of fragment - -Les champs de @code{zabbix-server-configuration} disponibles sont : - -@deftypevr {paramètre de @code{zabbix-server-configuration}} package zabbix-server -Le paquet zabbix-server. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string user -Utilisateur qui lancera le serveur Zabbix. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} group group -Groupe qui lancera le serveur Zabbix. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string db-host -Le nom d'hôte de la base de données. - -La valeur par défaut est @samp{"127.0.0.1"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string db-name -Nom de la base de données. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string db-user -Utilisateur de la base de données. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string db-password -Mot de passe de la base de données. Utilisez plutôt @code{include-files} -avec @code{DBPassword=SECRET} dans le fichier spécifié à la place. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} number db-port -Port de la base de données. - -La valeur par défaut est @samp{5432}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string log-type -Spécifie où les messages de journalisation seront écrits : - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - fichier spécifié par le paramètre @code{log-file}. - -@item -@code{console} - sortie standard. - -@end itemize - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string log-file -Nom du fichier de journal lorsque le paramètre @code{log-type} vaut -@code{file}. - -La valeur par défaut est @samp{"/var/log/zabbix/server.log"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string pid-file -Nom du fichier de PID. - -La valeur par défaut est @samp{"/var/run/zabbix/zabbix_server.pid"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string ssl-ca-location -Emplacement des fichiers d'autorités de certification (AC) pour la -vérification des certificats SSL du serveur. - -La valeur par défaut est @samp{"/etc/ssl/certs/ca-certificates.crt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string ssl-cert-location -Emplacement des certificats SSL des clients. - -La valeur par défaut est @samp{"/etc/ssl/certs"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} string extra-options -Options supplémentaires ajoutées à la fin du fichier de configuration du -serveur Zabbix. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-server-configuration}} include-files include-files -Vous pouvez inclure des fichiers individuels ou tous les fichiers d'un -répertoire dans le fichier de configuration. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Agent zabbix -@cindex zabbix zabbix-agent - -L'agent Zabbix récupère des informations pour le serveur Zabbix. - -@c %start of fragment - -Les champs de @code{zabbix-agent-configuration} disponibles sont : - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} package zabbix-agent -Le paquet zabbix-agent. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string user -Utilisateur qui lancera l'agent Zabbix. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} group group -Groupe qui lancera l'agent Zabbix. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string hostname -Noms d'hôte unique et sensible à la casse requis pour les vérifications -actives et qui doit correspondre au nom d'hôte configuré sur le serveur. - -La valeur par défaut est @samp{"Zabbix server"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string log-type -Spécifie où les messages de journalisation seront écrits : - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - fichier spécifié par le paramètre @code{log-file}. - -@item -@code{console} - sortie standard. - -@end itemize - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string log-file -Nom du fichier de journal lorsque le paramètre @code{log-type} vaut -@code{file}. - -La valeur par défaut est @samp{"/var/log/zabbix/agent.log"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string pid-file -Nom du fichier de PID. - -La valeur par défaut est @samp{"/var/run/zabbix/zabbix_agent.pid"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} list server -Liste d'adresses IP, éventuellement en notation CIDR ou de noms d'hôtes de -serveurs Zabbix et de mandataires Zabbix. Les connexions entrantes ne -seront acceptées que si elles viennent des hôtes listés ici. - -La valeur par défaut est @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} list server-active -Liste de paires d'IP:port (ou nom d'hôte:port) de serveurs Zabbix et de -mandataires Zabbix pour les vérifications actives. Si le port n'est pas -spécifié, le port par défaut est utilisé. Si ce paramètre n'est pas -spécifié, les vérifications actives sont désactivées. - -La valeur par défaut est @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} string extra-options -Options supplémentaires ajoutées à la fin du fichier de configuration du -serveur Zabbix. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-agent-configuration}} include-files include-files -Vous pouvez inclure des fichiers individuels ou tous les fichiers d'un -répertoire dans le fichier de configuration. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Interface utilisateur Zabbix -@cindex zabbix zabbix-front-end - -Ce service fournit une interface WEB au serveur Zabbix. - -@c %start of fragment - -Les champs de @code{zabbix-front-end-configuration} disponibles sont : - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} nginx-server-configuration-list nginx -Configuration Nginx. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string db-host -Le nom d'hôte de la base de données. - -La valeur par défaut est @samp{"localhost"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} number db-port -Port de la base de données. - -La valeur par défaut est @samp{5432}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string db-name -Nom de la base de données. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string db-user -Utilisateur de la base de données. - -La valeur par défaut est @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string db-password -Mot de passe de la base de données. Utilisez plutôt @code{db-secret-file}. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string db-secret-file -Fichier de secrets qui sera ajouté au fichier @file{zabbix.conf.php}. Ce -fichier contient les paramètres d'authentification utilisés par Zabbix. On -s'attend à ce que vous le créiez manuellement. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} string zabbix-host -Nom d'hôte du serveur Zabbix. - -La valeur par défaut est @samp{"localhost"}. - -@end deftypevr - -@deftypevr {paramètre de @code{zabbix-front-end-configuration}} number zabbix-port -Port du serveur Zabbix. - -La valeur par défaut est @samp{10051}. - -@end deftypevr - - -@c %end of fragment - -@node Services Kerberos -@subsection Services Kerberos -@cindex Kerberos - -Le module @code{(gnu services kerberos)} fournit des services liés au -protocole d'authentification @dfn{Kerberos}. - -@subsubheading Service Krb5 - -Les programmes qui utilisent une bibliothèque cliente Kerberos s'attendent à -trouver un fichier de configuration dans @file{/etc/krb5.conf}. Ce service -génère un tel fichier à partir d'une définition fournie par la déclaration -de système d'exploitation. Il ne démarre aucun démon. - -Aucun fichier « keytab » n'est fourni par ce service — vous devez les créer -explicitement. Ce service est connu pour fonctionner avec la bibliothèque -cliente MIT, @code{mit-krb5}. Les autres implémentations n'ont pas été -testées. - -@defvr {Variable Scheme} krb5-service-type -Un type de service pour les clients Kerberos 5. -@end defvr - -@noindent -Voici un exemple d'utilisation : -@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 -Cet exemple fournit une configuration cliente Kerberos@tie{}5 qui : -@itemize -@item Reconnais deux domaines : « EXAMPLE.COM » et « ARGREX.EDU », tous deux -aillant des serveurs d'administration et des centres de distribution de -clefs distincts ; -@item Utilisera le domaine « EXAMPLE.COM » pr défaut si le domaine n'est pas spécifié -explicitement par les clients ; -@item Acceptera les services qui ne supportent que des types de chiffrements connus pour être faibles. -@end itemize - -Les types @code{krb5-realm} et @code{krb5-configuration} ont de nombreux -champs. Seuls les plus communs sont décrits ici. Pour une liste complète, -et plus de détails sur chacun d'entre eux, voir la documentation de MIT -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}. - - -@deftp {Type de données} krb5-realm -@cindex domaine, kerberos -@table @asis -@item @code{name} -Ce champ est une chaîne identifiant le nom d'un domaine. Une convention -courante est d'utiliser le nom pleinement qualifié de votre organisation, -converti en majuscule. - -@item @code{admin-server} -Ce champ est une chaîne identifiant l'hôte où le serveur d'administration -tourne. - -@item @code{kdc} -Ce champ est une chaîne identifiant le centre de distribution de clefs pour -ce domaine. -@end table -@end deftp - -@deftp {Type de données} krb5-configuration - -@table @asis -@item @code{allow-weak-crypto?} (par défaut : @code{#f}) -Si ce drapeau est @code{#t} les services qui n'offrent que des algorithmes -de chiffrement faibles seront acceptés. - -@item @code{default-realm} (par défaut : @code{#f}) -Ce champ devrait être une chaîne identifiant le domaine Kerberos par défaut -pour le client. Vous devriez mettre le nom de votre domaine Kerberos dans -ce champ. Si cette valeur est @code{#f} alors un domaine doit être spécifié -pour chaque principal Kerberos à l'invocation des programmes comme -@command{kinit}. - -@item @code{realms} -Cela doit être une liste non-vide d'objets @code{krb5-realm}, auxquels les -clients peuvent accéder. Normalement, l'un d'entre eux aura un champ -@code{name} qui correspond au champ @code{default-realm}. -@end table -@end deftp - - -@subsubheading Service PAM krb5 -@cindex pam-krb5 - -Le service @code{pam-krb5} permet la connexion et la gestion des mots de -passe par Kerberos. Vous aurez besoin de ce service si vous voulez que les -applications qui utilisent PAM puissent authentifier automatiquement les -utilisateurs avec Kerberos. - -@defvr {Variable Scheme} pam-krb5-service-type -Un type de service pour le module PAM Kerberos 5. -@end defvr - -@deftp {Type de données} pam-krb5-configuration -Type de données représentant la configuration du module PAM Kerberos 5. Ce -type a les paramètres suivants : -@table @asis -@item @code{pam-krb5} (par défaut : @code{pam-krb5}) -Le paquet pam-krb5 à utiliser. - -@item @code{minimum-uid} (par défaut : @code{1000}) -Le plus petite ID utilisateur pour lequel les authentifications Kerberos -devraient être tentées. Les comptes locaux avec une valeur plus petite -échoueront silencieusement leur authentification Kerberos. -@end table -@end deftp - - -@node Services LDAP -@subsection Services LDAP -@cindex LDAP -@cindex nslcd, service LDAP - -Le module @code{(gnu services authentication)} fournit le type de service -@code{nslcd-service-type}, qui peut être utilisé pour l'authentification par -LDAP. En plus de configurer le service lui-même, vous pouvez ajouter -@code{ldap} comme service de noms au Name Service Switch. @xref{Name Service Switch} pour des informations détaillées. - -Voici une déclaration de système d'exploitation simple avec une -configuration par défaut pour @code{nslcd-service-type} et une configuration -du Name Service Switch qui consulte le service de noms @code{ldap} en -dernier : - -@example -(use-service-modules authentication) -(use-modules (gnu system nss)) -... -(operating-system - ... - (services - (cons* - (service nslcd-service-type) - (service dhcp-client-service-type) - %base-services)) - (name-service-switch - (let ((services (list (name-service (name "db")) - (name-service (name "files")) - (name-service (name "ldap"))))) - (name-service-switch - (inherit %mdns-host-lookup-nss) - (password services) - (shadow services) - (group services) - (netgroup services) - (gshadow services))))) -@end example - -@c %start of generated documentation for nslcd-configuration - -Les champs de @code{nslcd-configuration} disponibles sont : - -@deftypevr {paramètre de @code{nslcd-configuration}} package nss-pam-ldapd -Le paquet @code{nss-pam-ldapd} à utiliser. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number threads -Le nombre de threads à démarrer qui peuvent gérer les requête et effectuer -des requêtes LDAP. Chaque thread ouvre une connexion séparée au serveur -LDAP. La valeur par défaut est de 5 threads. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} string uid -Cela spécifie l'id de l'utilisateur sous lequel le démon devrait tourner. - -La valeur par défaut est @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} string gid -Cela spécifie l'id du groupe sous lequel le démon devrait tourner. - -La valeur par défaut est @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} log-option log -Cette option contrôle la journalisation via une liste contenant le schéma et -le niveau. Le schéma peut être soit un symbole « none », « syslog », soit -un nom de fichier absolu. Le niveau est facultatif et spécifie le niveau de -journalisation. Le niveau de journalisation peut être l'un des symboles -suivants : « crit », « error », « warning », « notice », « info » ou « debug -». Tous les messages avec le niveau spécifié ou supérieurs sont -enregistrés. - -La valeur par défaut est @samp{("/var/log/nslcd" info)}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} list uri -La liste des URI des serveurs LDAP. Normalement, seul le premier serveur -sera utilisé avec les serveurs suivants comme secours. - -La valeur par défaut est @samp{("ldap://localhost:389/")}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string ldap-version -La version du protocole LDAP à utiliser. La valeur par défaut est -d'utiliser la version maximum supportée par la bibliothèque LDAP. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string binddn -Spécifie le nom distingué avec lequel se lier au serveur de répertoire pour -les recherches. La valeur par défaut est de se lier anonymement. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string bindpw -Spécifie le mot de passe avec lequel se lier. Cette option n'est valable -que lorsqu'elle est utilisée avec binddn. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string rootpwmoddn -Spécifie le nom distingué à utiliser lorsque l'utilisateur root essaye de -modifier le mot de passe d'un utilisateur avec le module PAM. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string rootpwmodpw -Spécifie le mot de passe à utiliser pour se lier si l'utilisateur root -essaye de modifier un mot de passe utilisateur. Cette option n'est valable -que si elle est utilisée avec rootpwmoddn - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string sasl-mech -Spécifie le mécanisme SASL à utiliser lors de l'authentification SASL. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string sasl-realm -Spécifie le royaume SASL à utiliser pour effectuer une authentification -SASL. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string sasl-authcid -Spécifie l'identité d'authentification à utiliser pour effectuer une -authentification SASL. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string sasl-authzid -Spécifie l'identité d'autorisation à utiliser lors d'une authentification -SASL. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean sasl-canonicalize? -Détermine si le nom d'hôte du serveur LDAP devrait être canonalisé. Si -c'est activé la bibliothèque LDAP effectuera une recherche de nom d'hôte -inversée. Par défaut, il est laissé à la bibliothèque LDAP le soin de -savoir si la vérification doit être effectuée ou non. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string krb5-ccname -Indique le nom du cache d'informations de connexion de GSS-API Kerberos. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} string base -La base de recherche de répertoires. - -La valeur par défaut est @samp{"dc=example,dc=com"}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} scope-option scope -Spécifie la portée de la recherche (subtree, onelevel, base ou children). -La portée par défaut est subtree ; la portée base n'est presque jamais utile -pour les recherches de service de noms ; la portée children n'est pas prise -en charge par tous les serveurs. - -La valeur par défaut est @samp{(subtree)}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-deref-option deref -Spécifie la politique de déréférencement des alias. La politique par défaut -est de ne jamais déréférencer d'alias. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean referrals -Spécifie s'il faut activer le suivi de référence. Le comportement par -défaut est de suivre les références. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} list-of-map-entries maps -Cette option permet d'ajouter des attributs personnalisés à rechercher à la -place des attributs par défaut de la RFC 2307. C'est une liste de -correspondances, consistant chacune en un nom, en l'attribut RFC 2307 à -utiliser et l'expression de la requête pour l'attribut tel qu'il sera -disponible dans le répertoire. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} list-of-filter-entries filters -Une liste de filtres consistant en le nom d'une correspondance à laquelle -applique le filtre et en une expression de filtre de recherche LDAP. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number bind-timelimit -Spécifie la limite de temps en seconds à utiliser lors de la connexion au -serveur de répertoire. La valeur par défaut est de 10 secondes. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number timelimit -Spécifie la limite de temps (en secondes) à attendre une réponse d'un -serveur LDAP. La valeur de zéro, par défaut, permet d'attendre indéfiniment -la fin des recherches. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number idle-timelimit -Spécifie la période d'inactivité (en seconde) après laquelle la connexion au -serveur LDAP sera fermée. La valeur par défaut est de ne jamais la fermer. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number reconnect-sleeptime -Spécifie le nombre de secondes pendant laquelle attendre lorsque la -connexion à tous les serveurs LDAP a échouée. Par défaut, il y a une -seconde d'attente entre le premier échec et la tentative suivante. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number reconnect-retrytime -Spécifie la durée après laquelle le serveur LDAP est considéré comme -définitivement inatteignable. Une fois cette durée atteinte, les tentatives -de connexions n'auront plus lieu qu'une fois par cet intervalle de temps. -La valeur par défaut est de 10 secondes. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-ssl-option ssl -Spécifie s'il faut utiliser SSL/TLS ou non (la valeur par défaut est non). -Si 'start-tls est spécifié alors StartTLS est utilisé à la place de LDAP sur -SSL. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-tls-reqcert-option tls-reqcert -Spécifie quelles vérifications effectuer sur les certificats donnés par les -serveurs. La signification des valeurs est décrite dans la page de manuel -de ldap.conf(5). - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-cacertdir -Spécifie le répertoire contenant les certificats X.509 pour -l'authentification des pairs. Ce paramètre est ignoré quand il est utilisé -avec GnuTLS. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-cacertfile -Spécifie le chemin des certificats X.509 pour l'authentification des pairs. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-randfile -Spécifie le chemin d'une source d'entropie. Ce paramètre est ignoré quand -il est utilisé avec GnuTLS. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-ciphers -Spécifie les suites de chiffrements à utiliser pour TLS en tant que chaîne -de caractères. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-cert -Spécifie le chemin vers le fichier contenant le certificat local pour -l'authentification TLS du client. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string tls-key -Spécifie le chemin du fichier contenant la clef privée pour -l'authentification TLS du client. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number pagesize -Indiquez un nombre plus grand que 0 pour demander des résultats paginés au -serveur LDAP en accord avec la RFC 2696. La valeur par défaut (0) est de ne -pas demander de pagination des résultats. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-ignore-users-option nss-initgroups-ignoreusers -Cette option évite les recherches d'appartenance au groupe à travers le LDAP -pour les utilisateurs spécifiés. Autrement, la valeur 'all-local peut être -utilisée. Avec cette valeur nslcd construit une liste complète des -utilisateurs non-LDAP au démarrage. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number nss-min-uid -Cette option s'assure que les utilisateurs LDAP avec un id utilisateur -numérique plus petit que la valeur spécifiée sont ignorés. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number nss-uid-offset -Cette option spécifie un décalage à ajouter à tous les id utilisateurs -numériques LDAP. Cela peut être utile pour éviter des collisions d'id -utilisateurs avec des utilisateurs locaux. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-number nss-gid-offset -Cette option spécifie un décalage à ajouter à tous les id de groupe -numériques LDAP. Cela peut être utile pour éviter des collisions d'id -utilisateurs avec des groupes locaux. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean nss-nested-groups -Si cette option est indiquée, l'attribut de membre de groupe peut pointer -vers un autre groupe. Les membres de groupes imbriqués sont aussi renvoyés -dans le groupe de haut-niveau et les groupes parents sont renvoyés lorsqu'on -recherche un utilisateur spécifique. La valeur par défaut est de ne pas -effectuer de recherche supplémentaire sur les groupes imbriqués. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean nss-getgrent-skipmembers -Si cette option est indiqée, la liste de membres du groupe n'est pas -récupérée lorsqu'on cherche un groupe. Les recherches pour trouver les -groupes auxquels un utilisateur appartient resteront fonctionnelles donc -l'utilisateur obtiendra probablement les bons groupes à la connexion. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean nss-disable-enumeration -Si cette option est indiquée, les fonctions qui causent le chargement de -toutes les entrées d'utilisateur et de groupe depuis le répertoire ne -pourront pas le faire. Cela peut grandement diminuer la charge du serveur -LDAP dans des situations où il y a beaucoup d'utilisateurs et de groupes. -Cette option n'est pas recommandées pour la plupart des configurations. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string validnames -Cette option peut être utilisée pour spécifier comment les noms -d'utilisateurs et de groupes sont vérifiés sur le système. Ce motif est -utilisé pour vérifier tous les noms d'utilisateurs et de groupes qui sont -demandés et renvoyés par le LDAP. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean ignorecase -Cela spécifie s'il faut ou non effectuer des recherches avec une -correspondance sensible à la casse. Activer cela pourrait mener à des -vulnérabilités de type contournement d'authentification sur le système et -introduire des vulnérabilité d'empoisonnement de cache nscd qui permettent -un déni de service. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-boolean pam-authc-ppolicy -Cette option spécifie si des contrôles de la politique de mots de passe sont -demandés et gérés par le serveur LDAP à l'authentification de l'utilisateur. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string pam-authc-search -Par défaut nslcd effectue une recherche LDAP avec le mot de passe de -l'utilisateur après BIND (authentification) pour s'assurer que l'opération -BIND a bien réussi. La recherche par défaut est une simple vérification que -le DN de l'utilisateur existe. Un filtre de recherche peut être spécifié -pour l'utiliser à la place. Il devrait renvoyer au moins une entrée. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string pam-authz-search -Cette option permet la configuration fine et flexible de la vérification -d'autorisation qui devrait être effectuée. Le filtre de recherche est -exécuté et si une entrée correspond, l'accès est autorisé, sinon il est -refusé. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} maybe-string pam-password-prohibit-message -Si cette option est indiquée, la modification de mot de passe par pam_ldap -sera refusée et le message spécifié sera présenté à l'utilisateur à la -place. Le message peut être utilisé pour rediriger les utilisateurs vers -une autre méthode pour changer leur mot de passe. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{nslcd-configuration}} list pam-services -Liste de noms de service pam pour lesquels l'authentification LDAP devrait -suffire. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@c %end of generated documentation for nslcd-configuration - - -@node Services web -@subsection Services web - -@cindex web -@cindex www -@cindex HTTP -Le module @code{(gnu services web)} fournit le serveur Apache HTTP, le -serveur web nginx et aussi un démon fastcgi. - -@subsubheading Serveur Apache HTTP - -@deffn {Variable Scheme} httpd-service-type -Type de service pour le serveur @uref{https://httpd.apache.org/,Apache HTTP} -(@dfn{httpd}). La valeur de ce type de service est un enregistrement -@code{httpd-configuration}. - -Un exemple de configuration simple est donné ci-dessous. - -@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 - -D'autres services peuvent aussi étendre @code{httpd-service-type} pour être -ajouté à la 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 - -Les détails des types d'enregistrement @code{httpd-configuration}, -@code{httpd-module}, @code{httpd-config-file} et @code{httpd-virtualhost} -sont donnés plus bas. - -@deffn {Type de données} httpd-configuration -Ce type de données représente la configuration du service httpd. - -@table @asis -@item @code{package} (par défaut : @code{httpd}) -Le paquet httpd à utiliser. - -@item @code{pid-file} (par défaut : @code{"/var/run/httpd"}) -Le fichier de pid utilisé par le service shepherd. - -@item @code{config} (par défaut : @code{(httpd-config-file)}) -Le fichier de configuration à utiliser avec le service httpd. La valeur par -défaut est un enregistrement @code{httpd-config-file} mais cela peut aussi -être un G-expression qui génère un fichier, par exemple un -@code{plain-file}. Un fichier en dehors du dépôt peut aussi être spécifié -avec une chaîne de caractères. - -@end table -@end deffn - -@deffn {Type de données} httpd-module -Ce type de données représente un module pour le service httpd. - -@table @asis -@item @code{name} -Le nom du module. - -@item @code{file} -Le fichier pour le module. Cela peut être relatif au paquet httpd utilisé, -l'emplacement absolu d'un fichier ou une G-expression pour un fichier dans -le dépôt, par exemple @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}. - -@end table -@end deffn - -@defvr {Variable Scheme} %default-httpd-modules -Une liste par défaut des objets @code{httpd-module}. -@end defvr - -@deffn {Type de données} httpd-config-file -Ce type de données représente un fichier de configuration pour le service -httpd. - -@table @asis -@item @code{modules} (par défaut : @code{%default-httpd-modules}) -Les modules à charger. Les modules supplémentaires peuvent être ajoutés ici -ou chargés par des configuration supplémentaires. - -Par exemple, pour gérer les requêtes pour des fichiers PHP, vous pouvez -utiliser le module @code{mod_proxy_fcgi} d'Apache avec -@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 "\ - - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (par défaut : @code{httpd}) -Le @code{ServerRoot} dans le fichier de configuration, par défaut le paquet -httpd. Les directives comme @code{Include} et @code{LoadModule} sont prises -relativement à la racine du serveur. - -@item @code{server-name} (par défaut : @code{#f}) -Le @code{ServerName} dans le fichier de configuration, utilisé pour -spécifier le schéma de requête, le nom d'hôte et le port que le serveur -utilise pour s'identifier. - -Cela n'a pas besoin d'être dans la configuration du serveur, et peut être -spécifié dans les hôtes virtuels. La valeur par défaut est @code{#f} pour -ne pas spécifier de @code{ServerName}. - -@item @code{document-root} (par défaut : @code{"/srv/http"}) -Le @code{DocumentRoot} depuis lequel les fichiers seront servis. - -@item @code{listen} (par défaut : @code{'("80")}) -La liste des valeurs pour les directives @code{Listen} dans le fichier de -configuration. La valeur devrait être une liste de chaînes, où chacune -spécifie le port sur lequel écouter et éventuellement une adresse IP et un -protocole à utiliser. - -@item @code{pid-file} (par défaut : @code{"/var/run/httpd"}) -Le @code{PidFile} à utiliser. Cela devrait correspondre à @code{pid-file} -indiqué dans @code{httpd-configuration} pour que le service Shepherd soit -correctement configuré. - -@item @code{error-log} (par défaut : @code{"/var/log/httpd/error_log"}) -Le @code{ErrorLog} où le serveur écrit les journaux d'erreurs. - -@item @code{user} (par défaut : @code{"httpd"}) -Le @code{User} en tant que lequel le serveur répondra aux requêtes. - -@item @code{group} (par défaut : @code{"httpd"}) -Le @code{Group} que le serveur utilisera pour répondre aux requêtes. - -@item @code{extra-config} (par défaut : @code{(list "TypesConfig etc/httpd/mime.types")}) -Une liste plate de chaînes et de G-expressions qui seront ajoutées à la fin -du fichier de configuration. - -N'importe quelle valeur avec laquelle le service est étendu sera ajouté à -cette liste. - -@end table -@end deffn - -@deffn {Type de données} httpd-virtualhost -Ce type de données représente la configuration d'un hôte virtuel pour le -service httpd. - -Ils devraient être ajoutés à extra-config dans 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} -L'adresse et le port pour la directive @code{VirtualHost}. - -@item @code{contents} -Le contenu de la directive @code{VirtualHost}, cela devrait être une liste -de chaîne et de G-expressions. - -@end table -@end deffn - -@subsubheading NGINX - -@deffn {Variable Scheme} nginx-service-type -Type de service pour le serveur web @uref{https://nginx.org/,NGinx}. La -valeur de ce service est un enregistrement @code{}. - -Un exemple de configuration simple est donné ci-dessous. - -@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 - -En plus d'ajouter des blocs de serveurs dans la configuration du service -directement, ce service peut être étendu par d'autres services pour ajouter -des blocs de serveurs, comme dans cet exemple : - -@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 - -Au démarrage, @command{nginx} n'a pas encore lu son fichier de -configuration, donc il utilise les fichiers par défaut pour les messages -d'erreur. S'il échoue à charger sa configuration, c'est là où les messages -seront enregistrés. Après la lecture du fichier de configuration, le -fichier de journal d'erreur par défaut change en fonction de celle-ci. Dans -notre cas, les messages d'erreur au démarrage se trouvent dans -@file{/var/run/nginx/logs/error.log} et après la configuration dans -@file{/var/log/nginx/error.log}. Ce second emplacement peut être modifié -avec l'option de configuration @var{log-directory}. - -@deffn {Type de données} nginx-configuration -Ce type de données représente la configuration de NGinx. Certaines -configurations peuvent se faire ici et d'autres fournissent des types -d'enregistrement ou éventuellement, on peut fournir un fichier de -configuration. - -@table @asis -@item @code{nginx} (par défaut : @code{nginx}) -Le paquet nginx à utiliser. - -@item @code{log-directory} (par défaut : @code{"/var/log/nginx"}) -Le répertoire dans lequel NGinx écrira ses fichiers journaux. - -@item @code{run-directory} (par défaut : @code{"/var/run/nginx"}) -Le répertoire dans lequel NGinx créera un fichier de pid et écrira des -fichiers temporaires. - -@item @code{server-blocks} (par défaut : @code{'()}) -Une liste de @dfn{blocs serveur} à créer dans le fichier de configuration -généré, dont les éléments sont de type @code{}. - -L'exemple suivant paramètre NGinx pour servir @code{www.example.com} depuis -le répertoire @code{/srv/http/www.example.com} sans utiliser 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} (par défaut : @code{'()}) -Une liste de @dfn{blocs amont} à créer dans le fichier de configuration -généré, dont les éléments sont de type -@code{}. - -Configurer les serveurs amont à travers les @code{upstream-blocks} peut être -utile en combinaison avec @code{locations} dans les enregistrements -@code{}. L'exemple suivant crée une -configuration de serveur avec une configuration « location » qui sera -mandataire pour une configuration amont, qui gérera les requêtes avec deux -serveurs. - -@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} (par défaut : @code{#f}) -Si un fichier de configuration @var{file} est fourni, il sera utilisé au -lieu de générer un fichier de configuration à partir des -@code{log-directory}, @code{run-directory}, @code{server-blocks} et -@code{upstream-blocks} fournis. Pour un bon fonctionnement, ces arguments -devraient correspondre à ce qui se trouve dans @var{file} pour s'assurer que -les répertoires sont créé lorsque le service est activé. - -Cela peut être utile si vous avez déjà un fichier de configuration existant -ou s'il n'est pas possible de faire ce dont vous avez besoin avec les autres -parties de l'enregistrement nginx-configuration. - -@item @code{server-names-hash-bucket-size} (par défaut : @code{#f}) -Taille du seau pour les tables de hashage des noms de serveurs, par dauft -@code{#f} pour utilise la taille des lignes de cache du processeur. - -@item @code{server-names-hash-bucket-max-size} (par défaut : @code{#f}) -Taille maximum des seaux pour les tables de hashage des serveurs de noms. - -@item @code{extra-content} (par défaut : @code{""}) -Contenu supplémentaire du bloc @code{http}. Cela devrait être une chaîne ou -un G-expression. - -@end table -@end deffn - -@deftp {Type de données} nginx-server-configuration -Type de données représentant la configuration d'un bloc serveur de nginx. -Ce type a les paramètres suivants : - -@table @asis -@item @code{listen} (par défaut : @code{'("80" "443 ssl")}) -Chaque directive @code{listen} indique l'adresse et le port pour le -protocole IP ou le chemin d'un socket UNIX-domain sur lequel le serveur -acceptera les connexions. On peut spécifier l'adresse et le port, ou juste -l'adresse ou juste le port. Une adresse peut aussi être un nom d'hôte, par -exemple : - -@example -'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") -@end example - -@item @code{server-name} (par défaut : @code{(list 'default)}) -Une liste de noms de serveurs que ce serveur représente. @code{'default} -représente le serveur par défaut pour les connexions qui ne correspondent à -aucun autre serveur. - -@item @code{root} (par défaut : @code{"/srv/http"}) -Racine du site web que sert nginx. - -@item @code{locations} (par défaut : @code{'()}) -Une liste d'enregistrements @dfn{nginx-location-configuration} ou -@dfn{nginx-named-location-configuration} à utiliser dans ce bloc serveur. - -@item @code{index} (par défaut : @code{(list "index.html")}) -Fichiers d'index à chercher lorsque les clients demandent un répertoire. -S'il ne peut pas être trouvé, Nginx enverra la liste des fichiers dans le -répertoire. - -@item @code{try-files} (par défaut : @code{'()}) -Une liste de fichiers dont l'existence doit être vérifiée dans l'ordre -spécifié. @code{nginx} utilisera le premier fichier trouvé pour satisfaire -la requête. - -@item @code{ssl-certificate} (par défaut : @code{#f}) -Où trouver les certificats pour les connexions sécurisées. Indiquez -@code{#f} si vous n'avez pas de certificats et que vous ne voulez pas -utiliser HTTPS. - -@item @code{ssl-certificate-key} (par défaut : @code{#f}) -Où trouver la clef privée pour les connexions sécurisées. Indiquez -@code{#f} si vous n'avez pas de clef et que vous ne voulez pas utiliser -HTTPS. - -@item @code{server-tokens?} (par défaut : @code{#f}) -Indique si le serveur devrait ajouter sa configuration dans les réponses. - -@item @code{raw-content} (par défaut : @code{'()}) -Une liste de lignes brutes à ajouter dans le bloc serveur. - -@end table -@end deftp - -@deftp {Type de données} nginx-upstream-configuration -Type de données représentant la configuration d'un bloc @code{upstream} -nginx. Ce type a les paramètres suivants : - -@table @asis -@item @code{name} -Nome de ces groupe de serveurs. - -@item @code{serveurs} -Spécifie les adresses des serveurs dans le groupe. L'adresse peut être -spécifié avec une adresse IP (p.@: ex.@: @samp{127.0.0.1}), un nom de -domaine (p.@: ex.@: @samp{backend1.example.com}) ou un chemin vers un socket -UNIX avec le préfixe @samp{unix:}. Pour les adresse utilisant une adresse -IP ou un nom de domaine, le port par défaut est 80 et un port différent peut -être spécifié explicitement. - -@end table -@end deftp - -@deftp {Type de données} nginx-location-configuration -Type de données représentant la configuration d'un bloc @code{location} -nginx. Ce type a les paramètres suivants : - -@table @asis -@item @code{uri} -URI qui correspond à ce bloc. - -@anchor{nginx-location-configuration body} -@item @code{body} -Corps du block location, spécifié comme une liste de chaînes de caractères. -Cela peut contenir de nombreuses directives de configuration. Par exemple, -pour passer des requêtes à un groupe de serveurs amont définis dans un bloc -@code{nginx-upstream-configuration}, la directive suivante peut être -spécifiée dans le corps : @samp{(list "proxy_pass http://upstream-name;")}. - -@end table -@end deftp - -@deftp {Type de données} nginx-named-location-configuration -Type de données représentant la configuration d'un bloc location nginx -nommé. Les blocs location nommés sont utilisé les redirections de requêtes -et pas pour le traitement des requêtes normales. Ce type a les paramètres -suivants : - -@table @asis -@item @code{name} -Nom pour identifier ce bloc location. - -@item @code{body} -@xref{nginx-location-configuration body}, comme le corps d'un bloc location -nommé peut être utilisé de la même manière que -@code{nginx-location-configuration body}. Une restriction est que le corps -d'un bloc location nommé ne peut pas contenir de bloc location. - -@end table -@end deftp - -@subsubheading Cache Varnish -@cindex Varnish -Varnish est un serveur de cache rapide qui se trouve entre les applications -web et les utilisateurs. Il sert de serveur mandataire pour les requêtes -des clients et met les URL accédées en cache pour que plusieurs requêtes à -la même ressource ne crée qu'une requête au moteur. - -@defvr {Variable Scheme} varnish-service-type -Type de service pour le démon Varnish. -@end defvr - -@deftp {Type de données} varnish-configuration -Type de données représentant la configuration du service @code{varnish}. Ce -type a les paramètres suivants : - -@table @asis -@item @code{package} (par défaut : @code{varnish}) -Le paquet Varnish à utiliser. - -@item @code{name} (par défaut : @code{"default"}) -Un nom pour cet instance de Varnish. Varnish va créer un répertoire dans -@file{/var/varnish/} avec ce nom et gardera des fichiers temporaires à cet -endroit. Si le nom commence par une barre oblique, il est interprété comme -un nom de répertoire absolu. - -Passez l'argument @code{-n} aux autres programmes Varnish pour vous -connecter à l'instance nommée, p.@: ex.@: @command{varnishncsa -n default}. - -@item @code{backend} (par défaut : @code{"localhost:8080"}) -Le moteur à utiliser. Cette option n'a pas d'effet si @code{vcl} est vrai. - -@item @code{vcl} (par défaut : #f) -Le programme @dfn{VCL} (Varnish Configuration Language) à lancer. Si la -valeur est @code{#f}, Varnsh servira de mandataire pour @code{backend} avec -la configuration par défaut. Sinon, ce doit être un objet simili-fichier -avec une syntaxe VCL valide. - -@c Varnish does not support HTTPS, so keep this URL to avoid confusion. -Par exemple, pour créer un miroir de @url{http://www.gnu.org,www.gnu.org} -avec VCL vous pouvez faire quelque chose comme cela : - -@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 - -On peut inspecter la configuration d'une instance Varnish actuellement -lancée en utilisant le programme @command{varnishadm}. - -Consultez le @url{https://varnish-cache.org/docs/,guide utilisateur de -varnish} et le @url{https://book.varnish-software.com/4.0/,livre varnish} -pour une documentation complète sur Varnish et son langage de configuration. - -@item @code{listen} (par défaut : @code{'("localhost:80")}) -Liste des adresses sur lesquelles écoute Varnish. - -@item @code{storage} (par défaut : @code{'("malloc,128m")}) -Liste de moteurs de stockage qui seront disponibles en VCL. - -@item @code{parameters} (par défaut : @code{'()}) -Liste des paramètres à l'exécution de la forme @code{'(("parameter" -. "value"))}. - -@item @code{extra-options} (par défaut : @code{'()}) -Arguments supplémentaires à passer au processus @command{varnishd}. - -@end table -@end deftp - -@subsubheading FastCGI -@cindex fastcgi -@cindex fcgiwrap -FastCGI est une interface entre le frontal et le moteur d'un service web. -C'est un dispositif quelque peu désuet ; les nouveaux services devraient -généralement juste parler HTTP entre le frontal et le moteur. Cependant il -y a un certain nombre de services de moteurs comme PHP ou l'accès aux dépôts -Git optimisé en HTTP qui utilisent FastCGI, donc nous le supportons dans -Guix. - -Pour utiliser FastCGI, vous configurez le serveur web frontal (p.@: ex.@: -nginx) pour envoyer un sous-ensemble de ses requêtes au moteur fastcgi, qui -écoute sur un socket UNIX ou TCP local. Il y a un programme @code{fcgiwrap} -intermédiaire qui se trouve entre le processus du moteur et le serveur web. -Le frontal indique quel moteur lancer, en passant cette information au -processus @code{fcgiwrap}. - -@defvr {Variable Scheme} fcgiwrap-service-type -Un type de service pour le mandataire FastCGI @code{fcgiwrap}. -@end defvr - -@deftp {Type de données} fcgiwrap-configuration -Type de données représentant la configuration du service @code{fcgiwrap}. -Ce type a les paramètres suivants : -@table @asis -@item @code{package} (par défaut : @code{fcgiwrap}) -Le paquet fcgiwrap à utiliser. - -@item @code{socket} (par défaut : @code{tcp:127.0.0.1:9000}) -Le socket sur lequel le processus @code{fcgiwrap} écoute, en tant que chaîne -de caractères. Les valeurs valides de @var{socket} sont -@code{unix:@var{/path/to/unix/socket}}, -@code{tcp:@var{dot.ted.qu.ad}:@var{port}} et -@code{tcp6:[@var{ipv6_addr}]:port}. - -@item @code{user} (par défaut : @code{fcgiwrap}) -@itemx @code{group} (par défaut : @code{fcgiwrap}) -Les noms de l'utilisateur et du groupe, en tant que chaînes de caractères, -sous lesquels lancer le processus @code{fcgiwrap}. Le service -@code{fastcgi} s'assurera que si l'utilisateur demande les noms -d'utilisateurs et de groupes @code{fcgiwrap} l'utilisateur et le groupe -correspondant seront présents sur le système. - -Il est possible de configurer un service web soutenu par FastCGI pour passer -les informations d'authentification HTTP depuis le frontal jusqu'au moteur, -et de permettre à @code{fcgiwrap} dans lancer le processus de moteur avec -l'utilisateur correspondant. Pour activer cette fonctionnalité sur le -moteur, lancez @code{fcgiwrap} en tant qu'utilisateur et groupe -@code{root}. Remarquez que cette fonctionnalité doit aussi être configurée -sur le frontal. -@end table -@end deftp - -@cindex php-fpm -PHP-FPM (FastCGI Process Manager) est une implémentation FastCGI de PHP -alternative avec quelques fonctionnalités supplémentaires utiles pour les -sites de toutes tailles. - -Ces fonctionnalités comprennent : -@itemize @bullet -@item La création de processus adaptative -@item Des statistiques de base (comme le mod_status d'Apache) -@item La gestion des processus avancée avec arrêt et démarrage sans heurts -@item La possibilité de démarrer des processus de travail avec différents uid/gid/chroot/environnement -et différents php.ini (à la place de safe_mode) -@item L'enregistrement des journaux sur stdout et stderr -@item Le redémarrage d'urgence dans le cas de la destruction accidentelle du cache des opcodes -@item Le support des téléversements accélérés -@item Le support de « showlog » -@item Des améliorations à FastCGI, comme fastcgi_finish_request() - -une fonction spéciale pour terminer la requête et nettoyer toutes les -données tout en continuant à faire d'autres choses qui prennent du temps -(conversion vidéo, gestion des stats, etc…). -@end itemize -…@: et bien plus. - -@defvr {Variable Scheme} php-fpm-service-type -Un type de service pour @code{php-fpm}. -@end defvr - -@deftp {Type de données} php-fpm-configuration -Type de données pour la configuration du service php-fpm. -@table @asis -@item @code{php} (par défaut : @code{php}) -Le paquet php à utiliser. -@item @code{socket} (par défaut : @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) -L'adresse sur laquelle accepter les requêtes FastCGI. Les syntaxes valides -sont : -@table @asis -@item @code{"ip.add.re.ss:port"} -Écoute sur un socket TCP sur l'adresse spécifiée sur un port spécifié. -@item @code{"port"} -Écoute sur un socket TCP sur toutes les adresse sur un port spécifique. -@item @code{"/path/to/unix/socket"} -Écoute sur un socket unix. -@end table - -@item @code{user} (par défaut : @code{php-fpm}) -Utilisateur à qui appartiendra le processus de travail de php. -@item @code{group} (par défaut : @code{php-fpm}) -Groupe du processus de travail. -@item @code{socket-user} (par défaut : @code{php-fpm}) -Utilisateur qui peut parler au socket php-fpm. -@item @code{socket-group} (par défaut : @code{php-fpm}) -Groupe qui peut parler au socket php-fpm. -@item @code{pid-file} (par défaut : @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")}) -Le pid de php-fpm est écrit dans ce fichier une fois que le service a -démarré. -@item @code{log-file} (par défaut : @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) -Fichier de journal pour le processus maître de php-fpm. -@item @code{process-manager} (par défaut : @code{(php-fpm-dynamic-process-manager-configuration)}) -Configuration détaillée pour le gestionnaire de processus de php-fpm. Il -doit s'agir soit de : -@table @asis -@item @code{} -@item @code{ ou} -@item @code{} -@end table -@item @code{display-errors} (par défaut : @code{#f}) -Détermine si les erreurs et les avertissements php doivent être envoyés aux -clients et affichés dans leur navigateur. Cela est utile pour un -développement php local, mais un risque pour la sécurité pour les sites -publics, comme les messages d'erreur peuvent révéler des mots de passes et -des données personnelles. -@item @code{timezone} (par défaut : @code{#f}) -Spécifie le paramètre @code{php_admin_value[date.timezone]}. -@item @code{workers-logfile} (par défaut : @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")}) -Ce fichier enregistrera la sortie @code{stderr} des processus de travail de -php. On peut indiquer @code{#f} pour désactiver la journalisation. -@item @code{file} (par défaut : @code{#f}) -Une version alternative de la configuration complète. Vous pouvez utiliser -la fonction @code{mixed-text-file} ou un chemin de fichier absolu. -@end table -@end deftp - -@deftp {Type de données} php-fpm-dynamic-process-manager-configuration -Type de données pour le gestionnaire de processus @code{dynamic} de -php-fpm. Avec le gestionnaire de processus @code{dynamic}, des processus de -travail de secours sont gardés en fonction des limites configurées. -@table @asis -@item @code{max-children} (par défaut : @code{5}) -Nombre maximum de processus de travail. -@item @code{start-servers} (par défaut : @code{2}) -Nombre de processus de travail au démarrage. -@item @code{min-spare-servers} (par défaut : @code{1}) -Nombre de processus de travail de secours minimum qui doivent rester à -disposition. -@item @code{max-spare-servers} (par défaut : @code{3}) -Nombre maximum de processus de travail de secours qui peuvent rester à -disposition. -@end table -@end deftp - -@deftp {Type de données} php-fpm-static-process-manager-configuration -Type de données pour le gestionnaire de processus @code{static} de php-fpm. -Avec le gestionnaire de processus @code{static}, un nombre constant de -processus de travail est créé. -@table @asis -@item @code{max-children} (par défaut : @code{5}) -Nombre maximum de processus de travail. -@end table -@end deftp - -@deftp {Type de données} php-fpm-on-demand-process-manager-configuration -Type de données pour le gestionnaire de processus @code{on-demand} de -php-fpm. Avec le gestionnaire de processus @code{on-demand}, les processus -de travail ne sont créés que lorsque les requêtes arrivent. -@table @asis -@item @code{max-children} (par défaut : @code{5}) -Nombre maximum de processus de travail. -@item @code{process-idle-timeout} (par défaut : @code{10}) -La durée en secondes après laquelle un processus sans requête sera tué. -@end table -@end deftp - - -@deffn {Procédure Scheme} nginx-php-fpm-location @ - [#:nginx-package nginx] @ -[socket (string-append "/var/run/php" @ -(version-major (package-version php)) @ -"-fpm.sock")] -Une fonction d'aide pour ajouter rapidement php à un -@code{nginx-server-configuration}. -@end deffn - -Une configuration simple de services pour php ressemble à ceci : -@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 -Le générateur d'avatar de chat est un simple service pour démontrer -l'utilisation de php-fpm dans @code{Nginx}. Il permet de générer des -avatars de chats à partir d'une graine, par exemple le hash de l'adresse de -courriel d'un utilisateur. - -@deffn {Procédure Scheme} cat-avatar-generator-service @ - [#:cache-dir "/var/cache/cat-avatar-generator"] @ -[#:package cat-avatar-generator] @ -[#:configuration (nginx-server-configuration)] -Renvoie un nginx-server-configuration qui hérite de @code{configuration}. -Il étend la configuration nginx pour ajouter un bloc de serveur qui sert -@code{package}, une version de cat-avatar-generator. Pendant l'exécution, -cat-avatar-generator pourra utiliser @code{cache-dir} comme répertoire de -cache. -@end deffn - -Une configuration simple de cat-avatar-generator ressemble à ceci : -@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 -Le programme @uref{hpcguix-web, -https://github.com/UMCUGenetics/hpcguix-web/} est une interface web -personnalisable pour naviguer dans les paquets Guix, initialement conçue -pour les utilisateurs des grappes de calcul de haute performance (HPC). - -@defvr {Variable Scheme} hpcguix-web-service-type -Le type de service pour @code{hpcguix-web}. -@end defvr - -@deftp {Type de données} hpcguix-web-configuration -Type de données pour la configuration du service hpcguix-web. - -@table @asis -@item @code{specs} -Une gexp (@pxref{G-Expressions}) spécifiant la configuration du service -hpcguix-web. Les éléments principaux disponibles dans cette spec sont : - -@table @asis -@item @code{title-prefix} (par défaut : @code{"hpcguix | "}) -Le préfixe du titre des pages. - -@item @code{guix-command} (par défaut : @code{"guix"}) -La commande @command{guix} - -@item @code{package-filter-proc} (par défaut : @code{(const #t)}) -Une procédure qui spécifie comment filtrer les paquets qui seront affichés. - -@item @code{package-page-extension-proc} (par défaut : @code{(const '())}) -Paquet d'extensions pour @code{hpcguix-web}. - -@item @code{menu} (par défaut : @code{'()}) -Entrée supplémentaire dans la page @code{menu}. - -@item @code{channels} (par défaut : @code{%default-channels}) -Liste des canaux depuis lesquels la liste des paquets est construite -(@pxref{Canaux}). - -@item @code{package-list-expiration} (par défaut : @code{(* 12 3600)}) -Le temps d'expiration, en secondes, après lequel la liste des paquets est -reconstruite depuis les dernières instance des canaux donnés. -@end table - -Voir le dépôt hpcguix-web pour un -@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm, -exemple complet} - -@item @code{package} (par défaut : @code{hpcguix-web}) -Le paquet hpcguix-web à utiliser. -@end table -@end deftp - -Une déclaration de service hpcguix-web typique ressemble à cela : - -@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 Remarque -Le service hpcguix-web met régulièrement à jour la liste des paquets qu'il -publie en récupérant les canaux depuis Git. Pour cela, il doit accéder aux -certificats X.509 pour qu'il puisse authentifier les serveurs Git quand il -communique en HTTPS, et il suppose que @file{/etc/ssl/certs} contient ces -certificats. - -Ainsi, assurez-vous d'ajouter @code{nss-certs} ou un autre paquet de -certificats dans le champ @code{packages} de votre configuration. -@ref{Certificats X.509} pour plus d'informations sur les certificats X.509. -@end quotation - -@node Services de certificats -@subsection Services de certificats - -@cindex Web -@cindex HTTP, HTTPS -@cindex Let's Encrypt -@cindex certificats TLS -Le module @code{(gnu services certbot)} fournit un service qui récupère -automatiquement un certificat TLS valide de l'autorité de certification -Let's Encrypt. Ces certificats peuvent ensuite être utilisés pour servir du -contenu de manière sécurisée sur HTTPS et d'autres protocoles basés sur TLS, -en sachant que le client sera capable de vérifier l'authenticité du serveur. - -@url{https://letsencrypt.org/, Let's Encrypt} fournit l'outil @code{certbot} -pour automatiser le processus de certification. Cet outil génère d'abord un -clef sur le serveur de manière sécurisée. Ensuite il demande à l'autorité -de certification Let's Encrypt de signer la clef. La CA vérifie que la -requête provient de l'hôte en question en utilisant un protocole de -défi-réponse, ce qui requiert que le serveur fournisse sa réponse par HTTP. -Si ce protocole se passe sans encombre, la CA signe la clef et on obtient un -certificat. Ce certificat est valide pour une durée limitée et donc, pour -continuer à fournir des services en TLS, le serveur doit régulièrement -demander à la CA de renouveler sa signature. - -Le service certbot automatise ce processus : la génération initiale de la -clef, la demande de certification initiale au service Let's Encrypt, -l'intégration du protocole de défi/réponse dans le serveur web, l'écriture -du certificat sur le disque, les renouvellements périodiques et les taches -de déploiement avec le renouvellement (p.@: ex.@: recharger les services, -copier les clefs avec d'autres permissions). - -Certbot est lancé deux fois par jour, à une minute aléatoire dans l'heure. -Il ne fera rien sauf si vos certificats doivent être renouvelés ou sont -révoqués, mais le lancer régulièrement permettra à vos services de rester en -ligne si Let's Encrypt décide de révoquer votre certificat. - -En utilisant ce service, vous acceptez le document « ACME Subscriber -Agreement », qu'on peut trouver ici : -@url{https://acme-v01.api.letsencrypt.org/directory}. - -@defvr {Variable Scheme} certbot-service-type -Un type de service pour le client Let's Encrypt @code{certbot}. Sa valeur -doit être un enregistrement @code{certbot-configuration} comme dans cet -exemple : - -@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 - -Voir plus bas pour des détails sur @code{certbot-configuration}. -@end defvr - -@deftp {Type de données} certbot-configuration -Type données représentant la configuration du service @code{certbot}. Ce -type a les paramètres suivants : - -@table @asis -@item @code{package} (par défaut : @code{certbot}) -Le paquet certbot à utiliser. - -@item @code{webroot} (par défaut : @code{/var/www}) -Le répertoire depuis lequel servir les fichiers du défi/réponse de Let's -Encrypt. - -@item @code{certificates} (par défaut : @code{()}) -Une liste de @code{certificates-configuration} pour lesquels générer des -certificats et demander des signatures. Chaque certificat a un @code{name} -et plusieurs @code{domains}. - -@item @code{email} -Courriel obligatoire utilisé pour la création de compte, le contact en cas -de problème et des notifications importantes sur le compte. - -@item @code{rsa-key-size} (par défaut : @code{2048}) -Taille de la clef RSA. - -@item @code{default-location} (par défaut : @i{voir plus bas}) -Le @code{nginx-location-configuration} par défaut. Comme @code{certbot} -doit pouvoir servir les défis et les réponses, il doit être capable de -lancer un serveur web. Cela se fait en étendant le service web @code{nginx} -avec un @code{nginx-server-configuration} qui écoute sur les @var{domains} -sur le port 80 et qui a un @code{nginx-location-configuration} pour le -chemin @code{/.well-known/} utilisé par Let's Encrypt. @xref{Services web} -pour plus d'information sur les types de données de la configuration de -nginx. - -Les requêtes vers d'autres URL correspondra à @code{default-location}, qui, -s'il est présent, sera ajout é à tous les @code{nginx-server-configuration}. - -Par défaut, le @code{default-location} sera une redirection de -@code{http://@var{domain}/…} vers @code{https://@var{domain}/…}, en vous -laissant définir ce que vous voulez servir sur votre site en @code{https}. - -Passez @code{#f} pour ne pas utiliser de location par défaut. -@end table -@end deftp - -@deftp {Type de données} certificate-configuration -Type de données représentant la configuration d'un certificat. Ce type a -les paramètres suivants : - -@table @asis -@item @code{name} (par défaut : @i{voir plus bas}) -Ce nom est utilisé par Certbot pour ses tâches quotidiennes et dans les -chemins de fichiers ; il n'affecte pas le contenu des certificats -eux-mêmes. Pour voir les noms des certificats, lancez @code{certbot -certificates}. - -Sa valeur par défaut est le premier domaine spécifié. - -@item @code{domains} (par défaut : @code{()}) -Le premier domaine spécifié sera le CN du sujet du certificat, et tous les -domaines seront les noms alternatifs du sujet dans le certificat. - -@item @code{deploy-hook} (par défaut : @code{#f}) -Commande à lancer dans un shell une fois par certificat récupéré avec -succès. Pour cette commande, la variable @code{$RENEWED_LINEAGE} pointera -sur le sous-répertoire live (par exemple, -@samp{"/etc/letsencrypt/live/example.com"}) contenant le nouveau certificat -et la clef ; la variable @code{$RENEWED_DOMAINS} contiendra les noms de -domaines séparés par des espaces (par exemple @samp{"example.com -www.example.com"}). - -@end table -@end deftp - -Pour chaque @code{certificate-configuration}, le certificat est sauvegardé -dans @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} et la clef est -sauvegardée dans @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. -@node Services DNS -@subsection Services DNS -@cindex DNS (domain name system) -@cindex domain name system (DNS) - -Le module @code{(gnu services dns)} fournit des services liés au -@dfn{système de noms de domaines} (DNS). Il fournit un service de serveur -pour héberger un serveur DNS @emph{faisant autorité} pour plusieurs zones, -en esclave ou en maître. Ce service utilise @uref{https://www.knot-dns.cz/, -Knot DNS}. Il fournit aussi un service de cache et de renvoie DNS pour le -LAN, qui utilise @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, -dnsmasq}. - -@subsubheading Service Knot - -Voici un exemple de configuration pour un serveur faisant autorité sur deux -zone, un maître et un esclave : - -@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 {Variable Scheme} knot-service-type -C'est le type pour le serveur DNS Knot. - -Knot DNS est un serveur DNS faisant autorité, ce qui signifie qu'il peut -servir plusieurs zones, c'est-à-dire des noms de domaines que vous achetez à -un registrar. Ce serveur n'est pas un résolveur, ce qui signifie qu'il ne -peut pas résoudre les noms pour lesquels il ne fait pas autorité. Ce -serveur peut être configuré pour servir des zones comme un serveur maître ou -comme un serveur esclave, en fonction des zones. Les zones esclaves -récupèrent leurs données des maîtres, et seront servies comme faisant -autorité. Du point de vue d'un résolveur, il n'y a pas de différence entre -un maître et un esclave@footnote{NdT : Voir la conférence en Français de -Stéphane Bortzmeyer pour en apprendre plus sur le DNS : -@url{https://iletaitunefoisinternet.fr/dns-bortzmeyer/index.html}}. - -Les types de données suivants sont utilisés pour configurer le serveur DNS -Knot : -@end deffn - -@deftp {Type de données} knot-key-configuration -Type de données représentant une clef. Ce type a les paramètres suivants : - -@table @asis -@item @code{id} (par défaut : @code{""}) -Un identifiant pour d'autres champs de configuration qui se réfèrent à cette -clef. Les ID doivent être uniques et non vides. - -@item @code{algorithm} (par défaut : @code{#f}) -L'algorithme à utiliser. Choisissez entre @code{#f}, @code{'hmac-md5}, -@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, -@code{'hmac-sha384} et @code{'hmac-sha512}. - -@item @code{secret} (par défaut : @code{""}) -La clef secrète elle-même. - -@end table -@end deftp - -@deftp {Type de données} knot-acl-configuration -Type de données représentant une configuration de liste de contrôle d'accès -(ACL). Ce type a les paramètres suivants : - -@table @asis -@item @code{id} (par défaut : @code{""}) -Un identifiant pour d'autres champs de configuration qui se réfèrent à cette -clef. Les ID doivent être uniques et non vides. - -@item @code{address} (par défaut : @code{'()}) -Une liste ordonnée d'adresses IP, de sous-réseaux ou d'intervalles de -réseaux représentés par des chaînes de caractères. La requête doit -correspondre à l'une d'entre elles. La valeur vide signifie que l'adresse -n'a pas besoin de correspondre. - -@item @code{key} (par défaut : @code{'()}) -Une liste ordonnées de références à des clefs représentés par des chaînes. -La chaîne doit correspondre à un ID définie dans un -@code{knot-key-configuration}. Aucune clef signifie qu'une clef n'est pas -nécessaire pour correspondre à l'ACL. - -@item @code{action} (par défaut : @code{'()}) -Une liste ordonnée d'actions permises ou interdites par cet ACL. Les -valeurs possibles sont une liste de zéro ou plus d'éléments entre -@code{'transfer}, @code{'notify} et @code{'update}. - -@item @code{deny?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, l'ACL définie des restrictions. Les actions -listées sont interdites. Lorsque la valeur est fausse, les actions listées -sont autorisées. - -@end table -@end deftp - -@deftp {Type de données} zone-entry -Type de données représentant une entrée dans un fichier de zone. Ce type a -les paramètres suivants : - -@table @asis -@item @code{name} (par défaut : @code{"@@"}) -Le nom de l'enregistrement. @code{"@@"} se réfère à l'origine de la zone. -Les noms sont relatifs à l'origine de la zone. Par exemple, dans la zone -@code{example.org}, @code{"ns.example.org"} se réfère en fait à -@code{ns.example.org.example.org}. Les noms qui finissent par un point sont -absolus, ce qui signifie que @code{"ns.example.org."} se réfère bien à -@code{ns.example.org}. - -@item @code{ttl} (par défaut : @code{""}) -La durée de vie (TTL) de cet enregistrement. S'il n'est pas indiqué, le TTL -par défaut est utilisé. - -@item @code{class} (par défaut : @code{"IN"}) -La classe de l'enregistrement. Knot ne supporte actuellement que -@code{"IN"} et partiellement @code{"CH"}. - -@item @code{type} (par défaut : @code{"A"}) -Le type d'enregistrement. Les types usuels sont A (une adresse IPv4), NS -(serveur de nom) et MX (serveur de courriel). Bien d'autres types sont -définis. - -@item @code{data} (par défaut : @code{""}) -Les données contenues dans l'enregistrement. Par exemple une adresse IP -associée à un enregistrement A, ou un nom de domaine associé à un -enregistrement NS. Rappelez-vous que les noms de domaines sont relatifs à -l'origine à moins qu'ils ne finissent par un point. - -@end table -@end deftp - -@deftp {Type de données} zone-file -Type données représentant le contenu d'un fichier de zone. Ce type a les -paramètres suivants : - -@table @asis -@item @code{entries} (par défaut : @code{'()}) -La liste des entrées. On s'occupe de l'enregistrement SOA, donc vous n'avez -pas besoin de l'ajouter dans la liste des entrées. Cette liste devrait -contenir une entrée pour votre serveur DNS primaire faisant autorité. En -plus d'utiliser une liste des entrées directement, vous pouvez utiliser -@code{define-zone-entries} pour définir un objet contenant la liste des -entrées plus facilement, que vous pouvez ensuite passer au champ -@code{entries} de @code{zone-file}. - -@item @code{origin} (par défaut : @code{""}) -Le nom de votre zone. Ce paramètre ne peut pas être vide. - -@item @code{ns} (par défaut : @code{"ns"}) -Le domaine de votre serveur DNS primaire faisant autorité. Le nom est -relatif à l'origine, à moins qu'il finisse par un point. Il est nécessaire -que ce serveur DNS primaire corresponde à un enregistrement NS dans la zone -et qu'il soit associé à une adresse IP dans la liste des entrées. - -@item @code{mail} (par défaut : @code{"hostmaster"}) -Une adresse de courriel pour vous contacter en tant que propriétaire de la -zone. Cela se transforme en @code{@@}. - -@item @code{serial} (par défaut : @code{1}) -Le numéro de série de la zone. Comme c'est utilisé pour vérifier les -changements à la fois par les esclaves et par les résolveurs, il est -nécessaire qu'il ne décroisse @emph{jamais}. Incrémentez-le toujours quand -vous faites un changement sur votre zone. - -@item @code{refresh} (par défaut : @code{(* 2 24 3600)}) -La fréquence à laquelle les esclaves demanderont un transfert de zone. -Cette valeur est un nombre de secondes. On peut le calculer avec des -multiplications ou avec @code{(string->duration)}. - -@item @code{retry} (par défaut : @code{(* 15 60)}) -La période après laquelle un esclave essaiera de contacter son maître -lorsqu'il échoue à le faire la première fois. - -@item @code{expiry} (par défaut : @code{(* 14 24 3600)}) -TTL par défaut des enregistrements. Les enregistrements existants sont -considérés corrects pour au moins cette durée. Après cette période, les -résolveurs invalideront leur cache et vérifieront de nouveau qu'ils existent -toujours. - -@item @code{nx} (par défaut : @code{3600}) -TTL par défaut des enregistrement inexistants. Ce TTL est habituellement -court parce que vous voulez que vous nouveaux domaines soient disponibles -pour tout le monde le plus rapidement possible. - -@end table -@end deftp - -@deftp {Type de données} knot-remote-configuration -Type de données représentant une configuration de serveurs distants. Ce -type a les paramètres suivants : - -@table @asis -@item @code{id} (par défaut : @code{""}) -Un identifiant pour que les autres champs de configuration se réfèrent à ce -serveur distant. les ID doivent être uniques et non vides. - -@item @code{address} (par défaut : @code{'()}) -Une liste ordonnée d'adresses IP de destination. Ces adresses sont essayées -en séquence. Un port facultatif peut être donné avec le séparateur @@. Par -exemple @code{(list "1.2.3.4" "2.3.4.5@@53")}. Le port par défaut est le -53. - -@item @code{via} (par défaut : @code{'()}) -Une liste ordonnée d'adresses IP sources. Une liste vide fera choisir une -IP source appropriée à Knot. Un port facultatif peut être donné avec le -séparateur @@. La valeur par défaut est de choisir aléatoirement. - -@item @code{key} (par défaut : @code{#f}) -Une référence à une clef, c'est-à-dire une chaîne contenant l'identifiant -d'une clef définie dans un champ @code{knot-key-configuration}. - -@end table -@end deftp - -@deftp {Type de données} knot-keystore-configuration -Type de données représentant une base de clefs pour garder les clefs -dnssec. Ce type a les paramètres suivants : - -@table @asis -@item @code{id} (par défaut : @code{""}) -L'id de cette base de clefs. Il ne doit pas être vide. - -@item @code{backend} (par défaut : @code{'pem}) -Le moteur de stockage des clefs. Cela peut être @code{'pem} ou -@code{'pkcs11}. - -@item @code{config} (par défaut : @code{"/var/lib/knot/keys/keys"}) -La chaîne de configuration pour le moteur. Voici un exemple pour PKCS#11 : -@code{"pkcs11:token=knot;pin-value=1234 -/gnu/store/.../lib/pkcs11/libsofthsm2.so"}. Pour le moteur pem, la chaîne -représente un chemin dans le système de fichiers. - -@end table -@end deftp - -@deftp {Type de données} knot-policy-configuration -Type de données représentant une politique dnssec. Knot DNS est capable de -signer automatiquement vos zones. Il peut soit générer et gérer vos clefs -automatiquement ou utiliser des clefs que vous générez. - -Dnssec est habituellement implémenté avec deux clefs : une KSK (key signing -key) qui est utilisé pour signer une seconde, la ZSK (zone signing key) qui -est utilisée pour signer la zone. Pour pouvoir être de confiance, la KSK -doit être présente dans la zone parente (normalement un domaine de haut -niveau). Si votre registrar supporte dnssec, vous devrez leur envoyer le -hash de votre KSK pour qu'il puisse ajouter un enregistrement DS dans la -zone parente. Ce n'est pas automatique et vous devrez le faire à chaque -fois que vous changerez votre KSK. - -La politique définie aussi la durée de vie des clefs. Habituellement, la -ZSK peut être changée facilement et utilise des fonctions cryptographiques -plus faibles (avec un paramètre plus faible) pour signer les enregistrements -rapidement, donc elles sont changées très régulièrement. La KSK en revanche -requiert une interaction manuelle avec le registrar, donc elle change moins -souvent et utilise des paramètres plus robustes puisqu'elle ne signe qu'un -seul enregistrement. - -Ce type a les paramètres suivants : - -@table @asis -@item @code{id} (par défaut : @code{""}) -L'id de la politique. Il ne doit pas être vide. - -@item @code{keystore} (par défaut : @code{"default"}) -Une référence à une base de clefs, c'est-à-dire une chaîne contenant -l'identifiant d'une base de clefs définie dans un champ -@code{knot-keystore-configuration}. L'identifiant @code{"default"} signifie -la base par défaut (une base de données kasp initialisée par ce service). - -@item @code{manual?} (par défaut : @code{#f}) -Indique si la clef est gérée manuellement ou automatiquement. - -@item @code{single-type-signing?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, utilise le schéma de signature Single-Type. - -@item @code{algorithm} (par défaut : @code{"ecdsap256sha256"}) -Un algorithme de clef de signature et de signatures. - -@item @code{ksk-size} (par défaut : @code{256}) -La longueur de la KSK. Remarquez que cette valeur est correcte pour -l'algorithme par défaut, mais ne serait pas sécurisée pour d'autres -algorithmes. - -@item @code{zsk-size} (par défaut : @code{256}) -La longueur de la ZSK. Remarquez que cette valeur est correcte pour -l'algorithme par défaut, mais ne serait pas sécurisée pour d'autres -algorithmes. - -@item @code{dnskey-ttl} (par défaut : @code{'default}) -La valeur du TTL pour les enregistrements DNSKEY ajoutés au sommet de la -zone. La valeur spéciale @code{'default} signifie la même valeur que le TTL -du SOA de la zone. - -@item @code{zsk-lifetime} (par défaut : @code{(* 30 24 3600)}) -La période entre la publication d'une ZSK et l'initialisation d'un nouveau -changement. - -@item @code{propagation-delay} (par défaut : @code{(* 24 3600)}) -Un délai supplémentaire pour chaque étape du changement. Cette valeur -devrait être assez grande pour couvrir le temps de propagation des données -entre le serveur primaire et tous les secondaires. - -@item @code{rrsig-lifetime} (par défaut : @code{(* 14 24 3600)}) -Une période de validité des nouvelles signatures. - -@item @code{rrsig-refresh} (par défaut : @code{(* 7 24 3600)}) -Une période qui indique combien de temps avant l'expiration d'une signature -elle sera rafraîchie. - -@item @code{nsec3?} (par défaut : @code{#f}) -Lorsque la valeur est @code{#t}, on utilisera NSEC3 au lien de NSEC. - -@item @code{nsec3-iterations} (par défaut : @code{5}) -Le nombre de fois supplémentaires que le hash est effectué. - -@item @code{nsec3-salt-length} (par défaut : @code{8}) -La longueur du champ de sel en octets, ajouté au nom du propriétaire avant -de hasher. - -@item @code{nsec3-salt-lifetime} (par défaut : @code{(* 30 24 3600)}) -La période de validité des nouveaux champs sel. - -@end table -@end deftp - -@deftp {Type de données} knot-zone-configuration -Type de données représentant la zone servie par Knot. ce type a les -paramètres suivants : - -@table @asis -@item @code{domain} (par défaut : @code{""}) -Le domaine servi par cette configuration. Il ne doit pas être vide. - -@item @code{file} (par défaut : @code{""}) -Le fichier où la zone est sauvegardée. Ce paramètre est ignoré pour les -zones maîtres. La valeur vide signifie l'emplacement par défaut qui dépend -du nom de domaine. - -@item @code{zone} (par défaut : @code{(zone-file)}) -Le contenu du fichier de zone. Ce paramètre est ignoré par les zones -esclaves. Il doit contenir un enregistrement zone-file. - -@item @code{master} (par défaut : @code{'()}) -Une liste des serveurs distants maîtres. Lorsque la liste est vide, cette -zone est un maître. Lorsque la valeur est indiquée, cette zone est un -esclave. C'est al liste des identifiants des serveurs distants. - -@item @code{ddns-master} (par défaut : @code{#f}) -Le maître principal. Lorsque la valeur est vide, la valeur par défaut est -le premier maître de la liste des maîtres. - -@item @code{notify} (par défaut : @code{'()}) -Une liste d'identifiants de groupe de serveurs esclaves. - -@item @code{acl} (par défaut : @code{'()}) -Une liste d'identifiants d'ACL. - -@item @code{semantic-checks?} (par défaut : @code{#f}) -Lorsque la valeur est indiquée, cela ajoute plus de vérifications -sémantiques à la zone. - -@item @code{disable-any?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, cela interdit les requêtes de type ANY. - -@item @code{zonefile-sync} (par défaut : @code{0}) -Le délai entre une modification en mémoire et sur le disque. 0 signifie une -synchronisation immédiate. - -@item @code{serial-policy} (par défaut : @code{'increment}) -Une politique entre @code{'increment} et @code{'unixtime}. - -@end table -@end deftp - -@deftp {Type de données} knot-configuration -Type de données représentant la configuration de Knot. Ce type a les -paramètres suivants : - -@table @asis -@item @code{knot} (par défaut : @code{knot}) -Le paquet Knot. - -@item @code{run-directory} (par défaut : @code{"/var/run/knot"}) -Le répertoire de travail. Ce répertoire sera utilisé pour le fichier pid et -les sockets. - -@item @code{listen-v4} (par défaut : @code{"0.0.0.0"}) -Une adresse IP sur laquelle écouter. - -@item @code{listen-v6} (par défaut : @code{"::"}) -Une adresse IP sur laquelle écouter. - -@item @code{listen-port} (par défaut : @code{53}) -Un port sur lequel écouter. - -@item @code{keys} (par défaut : @code{'()}) -La liste des knot-key-configuration utilisés par cette configuration. - -@item @code{acls} (par défaut : @code{'()}) -La liste des knot-acl-configuration utilisés par cette configuration. - -@item @code{remotes} (par défaut : @code{'()}) -La liste des knot-remote-configuration utilisés par cette configuration. - -@item @code{zones} (par défaut : @code{'()}) -La liste des knot-zone-configuration utilisés par cette configuration. - -@end table -@end deftp - -@subsubheading Services Dnsmasq - -@deffn {Variable Scheme} dnsmasq-service-type -C'est le type du service dnsmasq, dont la valeur devrait être un objet -@code{dnsmasq-configuration} comme dans cet exemple : - -@example -(service dnsmasq-service-type - (dnsmasq-configuration - (no-resolv? #t) - (servers '("192.168.1.1")))) -@end example -@end deffn - -@deftp {Type de données} dnsmasq-configuration -Type de données qui représente la configuration de dnsmasq. - -@table @asis -@item @code{package} (par défaut : @var{dnsmasq}) -L'objet de paquet du serveur dnsmasq. - -@item @code{no-hosts?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, ne pas lire les noms d'hôte dans /etc/hosts. - -@item @code{port} (par défaut : @code{53}) -Le port sur lequel écouter. Le mettre à zéro désactive complètement les -réponses DNS, ce qui ne laisse que les fonctions DHCP et TFTP. - -@item @code{local-service?} (par défaut : @code{#t}) -Accepte les requêtes DNS seulement des hôtes dont les adresses sont sur le -sous-réseau local, c.-à-d.@: sur un sous-réseau pour lequel une interface -existe sur le serveur. - -@item @code{listen-addresses} (par défaut : @code{'()}) -Écoute sur le adresses IP données. - -@item @code{resolv-file} (par défaut : @code{"/etc/resolv.conf"}) -Le fichier où lire l'adresse IP des serveurs de noms en amont. - -@item @code{no-resolv?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, ne pas lire @var{resolv-file}. - -@item @code{servers} (par défaut : @code{'()}) -Spécifiez l'adresse IP des serveurs en amont directement. - -@item @code{cache-size} (par défaut : @code{150}) -Indique la taille du cache de dnsmasq. Indiquer 0 désactive le cache. - -@item @code{negative-cache?} (par défaut : @code{#t}) -Lorsque la valeur est fausse, désactive le cache des réponses négatives. - -@end table -@end deftp - -@subsubheading Service ddclient - -@cindex ddclient -Le service ddclient décrit plus bas lance le démon ddclient, qui prend en -charge la mise à jour automatique des entrées DNS pour les fournisseurs de -service comme @uref{https://dyn.com/dns/, Dyn}. - -L'exemple suivant montre comment instantier le service avec sa configuration -par défaut : - -@example -(service ddclient-service-type) -@end example - -Remarquez que ddclient a besoin d'accéder à des identifiants stockés dans un -@dfn{fichier de secrets}, par défaut @file{/etc/ddclient/secrets} (voir -@code{secret-file} plus bas). On s'attend à ce que vous créiez ce fichier -manuellement, de manière externe à guix (vous @emph{pourriez} ajouter ce -fichier dans une partie de votre configuration, par exemple avec -@code{plain-file}, mais il serait lisible pour tout le monde via -@file{/gnu/store}). Vois les exemples dans le répertoire -@file{share/ddclient} du paquet @code{ddclient}. - -@c %start of fragment - -Les champs de @code{ddclient-configuration} disponibles sont : - -@deftypevr {paramètre de @code{ddclient-configuration}} package ddclient -Le paquet ddclient. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} integer daemon -La période après laquelle ddclient réessaiera de vérifier l'IP et le nom de -domaine. - -La valeur par défaut est @samp{300}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} boolean syslog -Utiliser syslog pour la sortie. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string mail -Courriel de l'utilisateur. - -La valeur par défaut est @samp{"root"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string mail-failure -Courriel de l'utilisateur pour les échecs. - -La valeur par défaut est @samp{"root"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string pid -Le fichier de PID de ddclient. - -La valeur par défaut est @samp{"/var/run/ddclient/ddclient.pid"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} boolean ssl -Activer le support de SSL. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string user -Spécifie le nm d'utilisateur ou l'ID qui est utilisé pour lancer le -programme ddclient. - -La valeur par défaut est @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string group -Groupe de l'utilisateur qui lancera le programme ddclient. - -La valeur par défaut est @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} string secret-file -Fichier de secrets qui sera ajouté au fichier @file{ddclient.conf}. Ce -fichier contient les paramètres d'authentification utilisés par ddclient. -On s'attend à ce que vous le créiez manuellement. - -La valeur par défaut est @samp{"/etc/ddclient/secrets.conf"}. - -@end deftypevr - -@deftypevr {paramètre de @code{ddclient-configuration}} list extra-options -Options supplémentaires qui seront ajoutées au fichier @file{ddclient.conf}. - -La valeur par défaut est @samp{()}. - -@end deftypevr - - -@c %end of fragment - - -@node Services VPN -@subsection Services VPN -@cindex VPN (réseau privé virtuel) -@cindex réseau privé virtuel (VPN) - -Le module @code{(gnu services vpn)} fournit des services liés aux -@dfn{réseaux privés virtuels} (VPN). Il fournit un srevice @emph{client} -pour que votre machine se connecte à un VPN et un service @emph{serveur} -pour que votre machine héberge un VPN. Les deux services utilisent -@uref{https://openvpn.net/, OpenVPN}. - -@deffn {Procédure Scheme} openvpn-client-service @ - [#:config (openvpn-client-configuration)] - -Renvoie un service qui lance @command{openvpn}, un démon VPN, en tant que -client. -@end deffn - -@deffn {Procédure Scheme} openvpn-server-service @ - [#:config (openvpn-server-configuration)] - -Renvoie un service qui lance @command{openvpn}, un démon VPN, en tant que -serveur. - -Les deux services peuvent être lancés en même temps. -@end deffn - -@c %automatically generated documentation - -Les champs de @code{openvpn-client-configuration} disponibles sont : - -@deftypevr {paramètre de @code{openvpn-client-configuration}} package openvpn -Le paquet OpenVPN. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} string pid-file -Le fichier de PID d'OpenVPN. - -La valeur par défaut est @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} proto proto -Le protocole (UDP ou TCP) utilisé pour ouvrir un canal entre les clients et -les serveurs. - -La valeur par défaut est @samp{udp}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} dev dev -Le périphérique utilisé pour représenter la connexion VPN. - -La valeur par défaut est @samp{tun}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} string ca -L'autorité de certification qui sert à vérifier les connexions. - -La valeur par défaut est @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} string cert -Le certificat de la machine sur laquelle tourne le démon. Il devrait être -signé par l'autorité indiquée dans @code{ca}. - -La valeur par défaut est @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} string key -La clef de la machine sur laquelle tourne le démon. Elle doit être la clef -dont le certificat est donné dans @code{cert}. - -La valeur par défaut est @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} boolean comp-lzo? -Indique s'il faut utiliser l'algorithme de compression lzo. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} boolean persist-key? -Ne pas relire les fichiers de clefs entre les SIGUSR1 et les --ping-restart. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} boolean persist-tun? -Ne pas fermer et rouvrir les périphériques TUN/TAP ou lancer de scripts de -démarrage/d'arrêt entre les SIGUSR1 et les --ping-restart. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} number verbosity -Niveau de verbosité. - -La valeur par défaut est @samp{3}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} tls-auth-client tls-auth -Ajoute une couche d'authentification HMAC supplémentaire au dessus du canal -de contrôle TLS pour se protéger contre les attaques DoS. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} key-usage verify-key-usage? -Indique s'il faut vérifier que le certificat du serveur a l'extension -d'utilisation. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} bind bind? -Se lier à un port spécifique. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} resolv-retry resolv-retry? -Réessayer de résoudre l'adresse du serveur. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-client-configuration}} openvpn-remote-list remote -Une liste de serveurs distants sur lesquels se connecter. - -La valeur par défaut est @samp{()}. - -Les champs de @code{openvpn-remote-configuration} disponibles sont : - -@deftypevr {paramètre de @code{openvpn-remote-configuration}} string name -Nom du serveur. - -La valeur par défaut est @samp{"my-server"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-remote-configuration}} number port -Numéro de port sur lequel écoute le serveur. - -La valeur par défaut est @samp{1194}. - -@end deftypevr - -@end deftypevr -@c %end of automatic openvpn-client documentation - -@c %automatically generated documentation - -Les champs de @code{openvpn-server-configuration} disponibles sont : - -@deftypevr {paramètre de @code{openvpn-server-configuration}} package openvpn -Le paquet OpenVPN. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string pid-file -Le fichier de PID d'OpenVPN. - -La valeur par défaut est @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} proto proto -Le protocole (UDP ou TCP) utilisé pour ouvrir un canal entre les clients et -les serveurs. - -La valeur par défaut est @samp{udp}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} dev dev -Le périphérique utilisé pour représenter la connexion VPN. - -La valeur par défaut est @samp{tun}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string ca -L'autorité de certification qui sert à vérifier les connexions. - -La valeur par défaut est @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string cert -Le certificat de la machine sur laquelle tourne le démon. Il devrait être -signé par l'autorité indiquée dans @code{ca}. - -La valeur par défaut est @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string key -La clef de la machine sur laquelle tourne le démon. Elle doit être la clef -dont le certificat est donné dans @code{cert}. - -La valeur par défaut est @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} boolean comp-lzo? -Indique s'il faut utiliser l'algorithme de compression lzo. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} boolean persist-key? -Ne pas relire les fichiers de clefs entre les SIGUSR1 et les --ping-restart. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} boolean persist-tun? -Ne pas fermer et rouvrir les périphériques TUN/TAP ou lancer de scripts de -démarrage/d'arrêt entre les SIGUSR1 et les --ping-restart. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} number verbosity -Niveau de verbosité. - -La valeur par défaut est @samp{3}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} tls-auth-server tls-auth -Ajoute une couche d'authentification HMAC supplémentaire au dessus du canal -de contrôle TLS pour se protéger contre les attaques DoS. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} number port -Spécifie le numéro de port sur lequel les serveurs écoutent. - -La valeur par défaut est @samp{1194}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} ip-mask server -Une ip et un masque de sous-réseau spécifiant le sous-réseau dans le réseau -virtuel. - -La valeur par défaut est @samp{"10.8.0.0 255.255.255.0"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} cidr6 server-ipv6 -Une notation CIDR pour spécifier le sous-réseau IPv6 dans le réseau virtuel. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string dh -Le fichier de paramètres Diffie-Hellman. - -La valeur par défaut est @samp{"/etc/openvpn/dh2048.pem"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string ifconfig-pool-persist -Le fichier qui enregistre les IP des clients. - -La valeur par défaut est @samp{"/etc/openvpn/ipp.txt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} gateway redirect-gateway? -Lorsque la valeur est vraie, le serveur agira comme une passerelle pour ses -clients. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} boolean client-to-client? -Lorsque la valeur est vraie, les clients sont autorisés à se parler entre -eux dans le VPN. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} keepalive keepalive -Fait que des messages de ping sont envoyés régulièrement dans les deux sens -pour que chaque côté sache quand l'autre n'est plus disponible. -@code{keepalive} a besoin d'une paire. Le premier élément est la période -d'envoi du ping, et le second élément est le délai d'attente avant de -considéré que l'autre côté n'est plus disponible. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} number max-clients -Le nombre maximum de clients. - -La valeur par défaut est @samp{100}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} string status -Le fichier de statut. Ce fichier montre un court rapport sur les connexions -actuelles. Il est tronqué et réécrit toutes les minutes. - -La valeur par défaut est @samp{"/var/run/openvpn/status"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-server-configuration}} openvpn-ccd-list client-config-dir -La liste des configuration pour certains clients. - -La valeur par défaut est @samp{()}. - -Les champs de @code{openvpn-ccd-configuration} disponibles sont : - -@deftypevr {paramètre de @code{openvpn-ccd-configuration}} string name -Nom du client. - -La valeur par défaut est @samp{"client"}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-ccd-configuration}} ip-mask iroute -Le réseau du client - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{openvpn-ccd-configuration}} ip-mask ifconfig-push -IP du client sur le VPN. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@end deftypevr - - -@c %end of automatic openvpn-server documentation - - -@node Système de fichiers en réseau -@subsection Système de fichiers en réseau -@cindex NFS - -Le module @code{(gnu services nfs)} fournit les services suivants, qui sont -tous utilisés pour monter et exporter des arborescences de répertoires en -@dfn{network file systems} (NFS). - -@subsubheading Service RPC Bind -@cindex rpcbind - -Le service RPC Bind fournit un dispositif pour faire correspondre les -numéros de programmes à des adresses universelles. De nombreux services -liés à NFS utilisent ce dispositif. Donc il est automatiquement démarré -lorsqu'un service qui en dépend est démarré. - -@defvr {Variable Scheme} rpcbind-service-type -Un type de service pour le démon RPC portmapper. -@end defvr - - -@deftp {Type de données} rpcbind-configuration -Type données représentant la configuration du service RPC Bind. Ce type a -les paramètres suivants : -@table @asis -@item @code{rpcbind} (par défaut : @code{rpcbind}) -Le paquet rpcbind à utiliser. - -@item @code{warm-start?} (par défaut : @code{#t}) -Si ce paramètre est @code{#t}, alors le démon lira un fichier d'état au -démarrage ce qui lui fait recharger les informations d'états sauvegardés par -une instance précédente. -@end table -@end deftp - - -@subsubheading Pseudo-système de fichiers Pipefs -@cindex pipefs -@cindex rpc_pipefs - -Le système de fichiers pipefs est utilisé pour transférer des données liées -à NFS entre le noyau et les programmes en espace utilisateur. - -@defvr {Variable Scheme} pipefs-service-type -Un type de service pour le pseudo-système de fichiers pipefs. -@end defvr - -@deftp {Type de données} pipefs-configuration -Type de données représentant la configuration du service du pseudo-système -de fichiers pipefs. Ce type a les paramètres suivants : -@table @asis -@item @code{mount-point} (par défaut : @code{"/var/lib/nfs/rpc_pipefs"}) -Le répertoire dans lequel le système de fichiers est attaché. -@end table -@end deftp - - -@subsubheading Service de démon GSS -@cindex GSSD -@cindex GSS -@cindex système de sécurité global - -Le démon du @dfn{système de sécurité global} (GSS) fournit une sécurité -forte pour les protocoles basés sur des RPC. Avant d'échanger des requêtes -RPC, un client RPC doit établir un contexte sécurisé. Typiquement cela se -fait avec la commande Kerberos @command{kinit} ou automatiquement à la -connexion avec les services PAM (@pxref{Services Kerberos}). - -@defvr {Variable Scheme} gss-service-type -Un type de service pour le démon du système de sécurité global (GSS). -@end defvr - -@deftp {Type de données} gss-configuration -Type de données représentant la configuration du service du démon GSS. Ce -type a les paramètres suivants : -@table @asis -@item @code{nfs-utils} (par défaut : @code{nfs-utils}) -Le paquet dans lequel la commande @command{rpc.gssd} se trouve. - -@item @code{pipefs-directory} (par défaut : @code{"/var/lib/nfs/rpc_pipefs"}) -Le répertoire où le système de fichier pipefs doit être monté. - -@end table -@end deftp - - -@subsubheading Service de démon IDMAP -@cindex idmapd -@cindex correspondance de nom - -Le service du démon idmap fournit une correspondance entre les ID -utilisateur et les noms d'utilisateurs. Typiquement, cela est requis pour -accéder aux systèmes de fichiers montés via NFSv4. - -@defvr {Variable Scheme} idmap-service-type -Un type de service pour le démon de correspondance d'identité (IDMAP). -@end defvr - -@deftp {Type de données} idmap-configuration -Type de données représentant la configuration du service du démon IDMAP. Ce -type a les paramètres suivants : -@table @asis -@item @code{nfs-utils} (par défaut : @code{nfs-utils}) -Le paquet dans lequel se trouve la commande @command{rpc.idmapd}. - -@item @code{pipefs-directory} (par défaut : @code{"/var/lib/nfs/rpc_pipefs"}) -Le répertoire où le système de fichier pipefs doit être monté. - -@item @code{domain} (par défaut : @code{#f}) -Le nom de domaine NFSv4 local. Il faut que ce soit une chaîne de caractères -ou @code{#f}. Si la valeur est @code{#f} le démon utilisera le nom de -domaine pleinement qualifié de l'hôte. - -@end table -@end deftp - -@node Intégration continue -@subsection Intégration continue - -@cindex intégration continue -@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} est -un outil d'intégration continue pour Guix. On peut l'utiliser aussi bien -pour le développement que pour fournir des substituts à d'autres -(@pxref{Substituts}). - -Le module @code{(gnu services cuirass)} fournit le service suivant. - -@defvr {Procédure Scheme} cuirass-service-type -Le type du service Cuirass. Sa valeur doit être un objet -@code{cuirass-configuration}, décrit ci-dessous. -@end defvr - -Pour ajouter des travaux de construction, vous devez indiquer le champ -@code{specifications} de la configuration. Voici un exemple de service qui -récupère le dépôt Guix et construit les paquets depuis un manifeste. -Certains des paquets sont définis dans l'entrée @code{"custom-packages"}, -qui est l'équivalent de @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 - -Tandis que les informations liés aux travaux de construction sont -directement dans les spécifications, les paramètres globaux pour le -processus @command{cuirass} sont accessibles dans les autres champs de -@code{cuirass-configuration}. - -@deftp {Type de données} cuirass-configuration -Type de données représentant la configuration de Cuirass. - -@table @asis -@item @code{log-file} (par défaut : @code{"/var/log/cuirass.log"}) -Emplacement du fichier de journal. - -@item @code{cache-directory} (par défaut : @code{"/var/cache/cuirass"}) -Emplacement du cache du dépôt. - -@item @code{user} (par défaut : @code{"cuirass"}) -Propriétaire du processus @code{cuirass}. - -@item @code{group} (par défaut : @code{"cuirass"}) -Groupe du propriétaire du processus @code{cuirass}. - -@item @code{interval} (par défaut : @code{60}) -Nombre de secondes entre les mises à jour du dépôt suivis des travaux de -Cuirass. - -@item @code{database} (par défaut : @code{"/var/lib/cuirass/cuirass.db"}) -Emplacement de la base de données sqlite qui contient les résultats de -construction et les spécifications précédemment ajoutées. - -@item @code{ttl} (par défaut : @code{(* 30 24 3600)}) -Spécifie la durée de vie (TTL) en seconde des racines du ramasse-miette qui -sont enregistrés comme des résultats de construction. Cela signifie que les -résultats de construction ne seront pas glanés pendant au moins @var{ttl} -secondes. - -@item @code{port} (par défaut : @code{8081}) -Numéro de port utilisé pour le serveur HTTP. - -@item --listen=@var{hôte} -Écoute sur l'interface réseau de @var{host}. La valeur par défaut est -d'accepter les connexions depuis localhost. - -@item @code{specifications} (par défaut : @code{#~'()}) -Une gexp (@pxref{G-Expressions}) qui s'évalue en une liste de -spécifications, où une spécification est une liste d'association -(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) dont les -clefs sont des mots-clefs (@code{#:exemple-de-mot-clef}) comme dans -l'exemple plus haut. - -@item @code{use-substitutes?} (par défaut : @code{#f}) -Cela permet d'utiliser des substituts pour éviter de construire toutes les -dépendance d'un travail depuis les sources. - -@item @code{one-shot?} (par défaut : @code{#f}) -N'évaluer les spécification et construire les dérivations qu'une seule fois. - -@item @code{fallback?} (par défaut : @code{#f}) -Lorsque la substitution d'un binaire pré-construit échoue, revenir à la -construction locale du paquet. - -@item @code{cuirass} (par défaut : @code{cuirass}) -Le paquet Cuirass à utiliser. -@end table -@end deftp - -@node Services de gestion de l'énergie -@subsection Services de gestion de l'énergie - -@cindex tlp -@cindex gestion de l'énergie avec TLP -@subsubheading démon TLP - -Le module @code{(gnu services pm)} fournit une définition de service Guix -pour l'outil de gestion d'énergie Linux TLP. - -TLP active plusieurs modes un espace utilisateur et dans le noyau. -Contrairement à @code{upower-service}, ce n'est pas un outil passif de -surveillance, puisqu'il applique des paramètres personnalisés à chaque fois -qu'il détecte une nouvelle source d'énergie. Vous pouvez trouver plus -d'informations sur @uref{http://linrunner.de/en/tlp/tlp.html, la page -d'accueil de TLP}. - -@deffn {Variable Scheme} tlp-service-type -Le type de service pour l'outil TLP. Sa valeur devrait être une -configuration valide de TLP (voir plus bas). Pour utiliser les paramètres -par défaut, écrivez simplement : -@example -(service tlp-service-type) -@end example -@end deffn - -Par défaut TLP n'a pas besoin de beaucoup de configuration mais la plupart -des paramètres de TLP peuvent être modifiés avec @code{tlp-configuration}. - -Chaque définition de paramètre est précédée par son type ; par exemple, -@samp{boolean foo} indique que le paramètre @code{foo} doit être spécifié -comme un booléen. Les types qui commencent par @code{maybe-} dénotent des -paramètres qui n'apparaîtront pas dans la configuration de TLP lorsque leur -valeur est @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. - -Les champs de @code{tlp-configuration} disponibles sont : - -@deftypevr {paramètre de @code{tlp-configuration}} package tlp -Le paquet TLP. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean tlp-enable? -Indiquez vrai si vous souhaitez activer TLP. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string tlp-default-mode -Mode par défaut lorsqu'aucune source d'énergie ne peut être détectée. Les -possibilités sont AC et BAT. - -La valeur par défaut est @samp{"AC"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer disk-idle-secs-on-ac -Nombre de secondes que le noyau Linux doit attendre après que les disques -s'arrêtent pour se synchroniser quand il est sur secteur. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer disk-idle-secs-on-bat -Comme @code{disk-idle-ac} mais en mode batterie. - -La valeur par défaut est @samp{2}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer max-lost-work-secs-on-ac -Périodicité du nettoyage des pages invalidées, en secondes. - -La valeur par défaut est @samp{15}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer max-lost-work-secs-on-bat -Comme @code{max-lost-work-secs-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{60}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list cpu-scaling-governor-on-ac -Gouverneur de fréquence d'horloge sur secteur. Avec le pilote intel_pstate, -les possibilités sont powersave et performance. Avec le pilote -acpi-cpufreq, les possibilités sont ondemand, powersave, performance et -conservative. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list cpu-scaling-governor-on-bat -Comme @code{cpu-scaling-governor-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-scaling-min-freq-on-ac -Indique la fréquence d'horloge minimale pour le gouverneur sur secteur. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-scaling-max-freq-on-ac -Indique la fréquence d'horloge maximale pour le gouverneur sur secteur. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-scaling-min-freq-on-bat -Indique la fréquence d'horloge minimale pour le gouverneur sur batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-scaling-max-freq-on-bat -Indique la fréquence d'horloge maximale pour le gouverneur sur batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-min-perf-on-ac -Limite le P-état minimum pour contrôler la dissipation de puissance dans le -CPU, sur secteur. Les valeurs sont indiqués comme un pourcentage des -performances disponibles. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-max-perf-on-ac -Limite le P-état maximum pour contrôler la dissipation de puissance dans le -CPU, sur secteur. Les valeurs sont indiqués comme un pourcentage des -performances disponibles. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-min-perf-on-bat -Comme @code{cpu-min-perf-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-non-negative-integer cpu-max-perf-on-bat -Comme @code{cpu-max-perf-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-boolean cpu-boost-on-ac? -Active la fonctionnalité turbo boost du CPU sur secteur. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-boolean cpu-boost-on-bat? -Comme @code{cpu-boost-on-ac?} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean sched-powersave-on-ac? -Permet au noyau Linux de minimiser le nombre de cœurs/hyper-threads CPU -utilisés lorsque la charge est faible. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean sched-powersave-on-bat? -Comme @code{sched-powersave-on-ac?} mais en mode batterie. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean nmi-watchdog? -Active le chien de garde NMI du noyau Linux. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-string phc-controls -Pour les noyaux Linux avec le correctif PHC, change le voltage du CPU. Une -valeur serait par exemple @samp{"F:V F:V F:V F:V"}. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string energy-perf-policy-on-ac -Indique le niveau de performance du CPU par rapport à la politique de -gestion de l'énergie sur secteur. Les possibilités sont performance, normal -et powersave. - -La valeur par défaut est @samp{"performance"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string energy-perf-policy-on-bat -Comme @code{energy-perf-policy-ac} mais en mode batterie. - -La valeur par défaut est @samp{"powersave"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} space-separated-string-list disks-devices -Périphériques de disque dur. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} space-separated-string-list disk-apm-level-on-ac -Niveau de gestion de l'énergie avancé des disques durs. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} space-separated-string-list disk-apm-level-on-bat -Comme @code{disk-apm-bat} mais en mode batterie. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list disk-spindown-timeout-on-ac -Délai d'attente pour arrêter de faire tourner les disques. Une valeur doit -être spécifiée pour chaque disque dur déclaré. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list disk-spindown-timeout-on-bat -Comme @code{disk-spindown-timeout-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list disk-iosched -Sélectionne l'ordonnanceur d'entrées-sorties pour le disque. Une valeur -doit être spécifiée pour chaque disque déclaré. Les possibilités sont par -exemple cfq, deadline et noop. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string sata-linkpwr-on-ac -Niveau de gestion de l'énergie des lien SATA aggressive (ALPM). Les -possibilités sont min_power, medium_power et max_performance. - -La valeur par défaut est @samp{"max_performance"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string sata-linkpwr-on-bat -Comme @code{sata-linkpwr-ac} mais en mode batterie. - -La valeur par défaut est @samp{"min_power"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-string sata-linkpwr-blacklist -Exclu les périphériques SATA spécifiés de la gestion de l'énergie des liens. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-on-off-boolean ahci-runtime-pm-on-ac? -Active la gestion de l'énergie à l'exécution pour les contrôleurs AHCI et -les disques, sur secteur. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-on-off-boolean ahci-runtime-pm-on-bat? -Comme @code{ahci-runtime-pm-on-ac} mais en mode batterie. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer ahci-runtime-pm-timeout -Secondes d'inactivités avant de suspendre les disques. - -La valeur par défaut est @samp{15}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string pcie-aspm-on-ac -Niveau de gestion de l'énergie des états actifs de PCI Express. Les -possibilités sont default, performance et powersave. - -La valeur par défaut est @samp{"performance"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string pcie-aspm-on-bat -Comme @code{pcie-aspm-ac} mais en mode batterie. - -La valeur par défaut est @samp{"powersave"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-power-profile-on-ac -Niveau de vitesse de l'horloge des cartes graphiques Radeon. Les -possibilités sont low, mid, high, auto et default. - -La valeur par défaut est @samp{"high"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-power-profile-on-bat -Comme @code{radeon-power-ac} mais en mode batterie. - -La valeur par défaut est @samp{"low"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-dpm-state-on-ac -Méthode de gestion de l'énergie dynamique de Radeon (DPM). Les possibilités -sont battery et performance. - -La valeur par défaut est @samp{"performance"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-dpm-state-on-bat -Comme @code{radeon-dpm-state-ac} mais en mode batterie. - -La valeur par défaut est @samp{"battery"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-dpm-perf-level-on-ac -Niveau de performance de DPM. Les possibilités sont auto, low et high. - -La valeur par défaut est @samp{"auto"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string radeon-dpm-perf-level-on-bat -Comme @code{radeon-dpm-perf-ac} mais en mode batterie. - -La valeur par défaut est @samp{"auto"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} on-off-boolean wifi-pwr-on-ac? -Mode de gestion de l'énergie wifi. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} on-off-boolean wifi-pwr-on-bat? -Comme @code{wifi-power-ac?} mais en mode batterie. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} y-n-boolean wol-disable? -Désactive wake on LAN. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer sound-power-save-on-ac -Durée d'attente en secondes avant d'activer la gestion de l'énergie audio -sur les périphériques Intel HDA et AC97. La valeur 0 désactive la gestion -de l'énergie. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} non-negative-integer sound-power-save-on-bat -Comme @code{sound-powersave-ac} mais en mode batterie. - -La valeur par défaut est @samp{1}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} y-n-boolean sound-power-save-controller? -Désactive le contrôleur en mode de gestion de l'énergie sur les -périphériques Intel HDA. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean bay-poweroff-on-bat? -Active le périphérique optique AltraBay/MediaBay en mode batterie. Le -périphérique peut être de nouveau alimenté en lâchant (et en réinsérant) le -levier d'éjection ou en appuyant sur le bouton d'éjection sur les modèles -plus récents. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string bay-device -Nom du périphérique optique à éteindre. - -La valeur par défaut est @samp{"sr0"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string runtime-pm-on-ac -Gestion de l'énergie à l'exécution sur les bus PCI(e). Les possibilités -sont on et auto. - -La valeur par défaut est @samp{"on"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} string runtime-pm-on-bat -Comme @code{runtime-pm-ac} mais en mode batterie. - -La valeur par défaut est @samp{"auto"}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean runtime-pm-all? -Gestion de l'énergie à l'exécution pour tous les bus PCI(e), sauf ceux en -liste noire. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-space-separated-string-list runtime-pm-blacklist -Exclue les adresses des périphériques PCI(e) spécifiés de la gestion de -l'énergie à l'exécution. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} space-separated-string-list runtime-pm-driver-blacklist -Exclue les périphériques PCI(e) assignés aux pilotes spécifiés de la gestion -de l'énergie à l'exécution. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean usb-autosuspend? -Active la fonctionnalité de mise en veille automatique de l'USB. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-string usb-blacklist -Exclue les périphériques spécifiés de la mise en veille automatique de -l'USB. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean usb-blacklist-wwan? -Exclue les périphériques WWAN de la mise en veille automatique de l'USB. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-string usb-whitelist -Inclue les périphériques spécifiés dans la mise en veille automatique de -l'USB, même s'ils sont déjà exclus par le pilote ou via -@code{usb-blacklist-wwan?}. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} maybe-boolean usb-autosuspend-disable-on-shutdown? -Active la mise en veille de l'USB avant l'arrêt. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{tlp-configuration}} boolean restore-device-state-on-startup? -Restaure l'état des périphériques radio (bluetooth, wifi, wwan) du dernier -arrêt au démarrage du système. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@cindex thermald -@cindex gestion de la fréquence du CPU avec thermald -@subsubheading démon Thermald - -Le module @code{(gnu services pm)} fournit une interface pour thermald, un -service de gestion de l'horloge CPU qui aide à éviter la surchauffe. - -@defvr {Variable Scheme} thermald-service-type -C'est le type de service pour @uref{https://01.org/linux-thermal-daemon/, -thermald}, le démon de température de Linux, responsable du contrôle de -l'état thermique des processeurs et d'éviter la surchauffe. -@end defvr - -@deftp {Type de données} thermald-configuration -Type de données représentant la configuration de -@code{thermald-service-type}. - -@table @asis -@item @code{ignore-cpuid-check?} (par défaut : @code{#f}) -Ignore la vérification des modèles CPU supportés avec cpuid. - -@item @code{thermald} (par défaut : @var{thermald}) -Objet du paquet de thermald. - -@end table -@end deftp - -@node Services audio -@subsection Services audio - -Le module @code{(gnu services audio)} fournit un service qui lance MPD (le -démon de lecture de musique). - -@cindex mpd -@subsubheading Music Player Daemon - -Le démon de lecture de musique (MPD) est un service qui joue de la musique -tout en étant contrôlé depuis la machine locale ou à travers le réseau par -divers clients. - -L'exemple suivant montre comment on peut lancer @code{mpd} en tant -qu'utilisateur @code{"bob"} sur le port @code{6666}. Il utilise pulseaudio -pour la sortie audio. - -@example -(service mpd-service-type - (mpd-configuration - (user "bob") - (port "6666"))) -@end example - -@defvr {Variable Scheme} mpd-service-type -Le type de service pour @command{mpd}. -@end defvr - -@deftp {Type de données} mpd-configuration -Type de données représentant la configuration de @command{mpd}. - -@table @asis -@item @code{user} (par défaut : @code{"mpd"}) -L'utilisateur qui lance mpd. - -@item @code{music-dir} (par défaut : @code{"~/Music"}) -Le répertoire à scanner pour trouver les fichiers de musique. - -@item @code{playlist-dir} (par défaut : @code{"~/.mpd/playlists"}) -Le répertoire où stocker les playlists. - -@item @code{db-file} (par défaut : @code{"~/.mpd/tag_cache"}) -Emplacement de la base de données de musiques. - -@item @code{state-file} (par défaut : @code{"~/.mpd/state"}) -Emplacement du fichier qui stocke l'état actuel de MPD. - -@item @code{sticker-file} (par défaut : @code{"~/.mpd/sticker.sql"}) -Emplacement de la base de données de stickers. - -@item @code{port} (par défaut : @code{"6600"}) -Le port sur lequel lancer mpd. - -@item @code{address} (par défaut : @code{"any"}) -L'adresse sur laquelle se lie mpd. Pour utiliser un socket Unix domain, un -chemin absolu peut être spécifié ici. - -@end table -@end deftp - -@node Services de virtualisation -@subsection services de virtualisation - -Le module @code{(gnu services virtualization)} fournit des services pour les -démons libvirt et virtlog, ainsi que d'autres services liés à la -virtualisation. - -@subsubheading démon libvirt -@code{libvirtd} est le démon côté serveur du système de gestion de -virtualisation libvirt. Ce démon tourne sur des serveurs hôtes et effectue -les taches de gestion requises pour les clients virtualisés. - -@deffn {Variable Scheme} libvirt-service-type -C'est le type du @uref{https://libvirt.org, démon libvirt}. Sa valeur doit -être un @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) -Les champs de @code{libvirt-configuration} disponibles sont : - -@deftypevr {paramètre de @code{libvirt-configuration}} package libvirt -Paquet libvirt. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean listen-tls? -Indique s'il faut écouter des connexions TLS sécurisées sur le port TCP/IP -public. Vous devez remplir le champ @code{listen} pour que cela ait un -effet. - -Il est nécessaire de mettre en place une CA et de créer un certificat -serveur avant d'utiliser cette fonctionnalité. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean listen-tcp? -Écoute des connexions non-chiffrées sur le port TCP/IP public. Vous devez -remplir le champ @code{listen} pour que cela ait un effet. - -L'utilisation des sockets TCP requiert une authentification SASL par -défaut. Seuls les mécanismes SASL qui supportent le chiffrement des données -sont permis. Il s'agit de DIGEST_MD5 et GSSAPI (Kerberos5). - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string tls-port -Port pour accepter les connexions TLS sécurisées. Il peut s'agir d'un -numéro de port ou d'un nom de service - -La valeur par défaut est @samp{"16514"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string tcp-port -Port sur lequel accepter les connexions TCP non sécurisées. Cela peut être -un numéro de port ou un nom de service - -La valeur par défaut est @samp{"16509"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string listen-addr -Adresse IP ou nom d'hôte utilisé pour les connexions des clients. - -La valeur par défaut est @samp{"0.0.0.0"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean mdns-adv? -Indique s'il faut publier le service libvirt en mDNS. - -Autrement, vous pouvez désactiver cela pour tous les services en stoppant le -démon Avahi. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string mdns-name -Nom publié par défaut sur mDNS. Cela doit être unique sur le réseau local. - -La valeur par défaut est @samp{"Virtualization Host "}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string unix-sock-group -Groupe propriétaire du socket Unix domain. Cela peut être utilisé pour -permettre à un ensemble d'utilisateurs « de confiance » de gérer les -fonctionnalités sans devenir root. - -La valeur par défaut est @samp{"root"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string unix-sock-ro-perms -Permission Unix pour le socket en lecture seule. Il est utilisé pour -surveiller le statut des VM uniquement. - -La valeur par défaut est @samp{"0777"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string unix-sock-rw-perms -Permission Unix pour le socket en lecture-écriture. La valeur par défaut -n'autorise que root. Si PolicyKit est activé sur le socket, la valeur par -défaut change et permet tout le monde (c.-à-d.@: 0777). - -La valeur par défaut est @samp{"0770"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string unix-sock-admin-perms -Permissions Unix pour le socket d'administration. La valeur par défaut ne -permet que le propriétaire (root), ne la changez pas à moins que vous ne -soyez sûr de savoir à qui vous exposez cet accès. - -La valeur par défaut est @samp{"0777"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string unix-sock-dir -Le répertoire dans lequel les sockets sont créés. - -La valeur par défaut est @samp{"/var/run/libvirt"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string auth-unix-ro -Schéma d'authentification pour les socket Unix en lecture-seule. Par défaut -les permissions des socket permettent à n'importe qui de se connecter - -La valeur par défaut est @samp{"polkit"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string auth-unix-rw -Schéma d'authentification pour les socket UNIX en lecture-écriture. Par -défaut les permissions du socket ne permettent que root. Si le support de -PolicyKit a été compilé dans libvirt, la valeur par défaut utilise -l'authentification « polkit ». - -La valeur par défaut est @samp{"polkit"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string auth-tcp -Schéma d'authentification pour les sockets TCP. Si vous n'avez pas activé -SASL, alors tout le trafic TCP est en clair. Ne le faites pas en dehors de -scénario de développement ou de test. - -La valeur par défaut est @samp{"sasl"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string auth-tls -Schéma d'authentification pour les sockets TLS. Les sockets TLS sont déjà -chiffrés par la couche TLS, et une authentification limitée est effectuée -avec les certificats. - -Il est possible d'utiliser de n'importe quel mécanisme d'authentification -SASL en utilisant « sasl » pour cette option - -La valeur par défaut est @samp{"none"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} optional-list access-drivers -Schéma de contrôle d'accès à l'API. - -Par défaut un utilisateur authentifié peut accéder à toutes les API. Les -pilotes d'accès peuvent placer des restrictions là-dessus. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string key-file -Chemin de fichier de la clef du serveur. Si la valeur est une chaîne vide, -aucune clef privée n'est chargée. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string cert-file -Chemin de fichier de la clef du serveur. Si la chaîne est vide, aucun -certificat n'est chargé. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string ca-file -Chemin de fichier de la clef du serveur. Si la chaîne est vide, aucun -certificat de CA n'est chargé. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string crl-file -Chemin de la liste de révocation des certificats. Si la chaîne est vide, -aucun CRL n'est chargé. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean tls-no-sanity-cert -Désactive la vérification de nos propres certificats serveurs. - -Lorsque libvirtd démarre il effectue des vérifications de routine sur ses -propres certificats. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean tls-no-verify-cert -Désactive la vérification des certificats clients. - -La vérification des certificats clients est le mécanisme d'authentification -principal. Tout client qui ne présent pas de certificat signé par la CA -sera rejeté. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} optional-list tls-allowed-dn-list -Liste blanche des Distinguished Name x509 autorisés. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} optional-list sasl-allowed-usernames -Liste blanche des noms d'utilisateur SASL permis. Le format des noms -d'utilisateurs dépend du mécanisme d'authentification SASL. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string tls-priority -Modifie la chaîne de priorité TLS par défaut fixée à la compilation. La -valeur par défaut est typiquement « NORMAL » à moins qu'elle n'ait été -modifiée à la compilation. Ne l'indiquez que si vous voulez que libvirt -agisse différemment des paramètres par défaut globaux. - -La valeur par défaut est @samp{"NORMAL"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-clients -Nombre maximum de connexions clientes en même temps sur tous les sockets. - -La valeur par défaut est @samp{5000}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-queued-clients -Longueur maximum de la queue de connexions en attente d'acceptation du -démon. Remarquez que certains protocoles supportant la retransmission -peuvent obéir à ce paramètre pour qu'une connexion ultérieure réussisse. - -La valeur par défaut est @samp{1000}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-anonymous-clients -Longueur maximum de la queue des clients acceptés mais pas authentifiés. -Indiquez zéro pour désactiver ce paramètre - -La valeur par défaut est @samp{20}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer min-workers -Nombre de processus de travail démarrés initialement. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-workers -Nombre maximum de threads de travail. - -Si le nombre de clients actifs dépasse @code{min-workers}, plus de threads -seront démarrés, jusqu'à la limite de max_workers. Typiquement vous voulez -que max_workers soit égal au nombre maximum de clients permis. - -La valeur par défaut est @samp{20}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer prio-workers -Nombre de travailleurs prioritaires. Si tous les threads de travail du -groupe ci-dessus sont bloqués, certains appels marqués comme prioritaires -(notamment domainDestroy) peuvent être exécutés par ce groupe. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-requests -Limite globale totale sur les appels RPC concurrents. - -La valeur par défaut est @samp{20}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer max-client-requests -Limite de requêtes concurrentes depuis une connexion cliente unique. Pour -éviter qu'un client ne monopolise le serveur, vous devriez indiquer une -petite partie des paramètres global max_requests et max_workers. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-min-workers -Comme @code{min-workers} mais pour l'interface d'administration. - -La valeur par défaut est @samp{1}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-max-workers -Comme @code{max-workers} mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-max-clients -Comme @code{max-clients} mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-max-queued-clients -Comme @code{max-queued-clients} mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-max-client-requests -Comme @code{max-client-requests} mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer log-level -Niveau de journalisation. 4 : erreurs, 3 : avertissements, 2 : information, -1 : débogage. - -La valeur par défaut est @samp{3}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string log-filters -Filtres de journalisation. - -Un filtre qui permet de sélectionner plusieurs niveaux de journalisation -pour une catégorie donnée. Le format d'un filtre est : - -@itemize @bullet -@item -x:nom - -@item -x:+nom - -@end itemize - -où @code{nom} est une chaîne de caractères qui correspond à la catégorie -donnée dans @code{VIR_LOG_INIT()} au début de chaque fichier source de -libvirt, p.@: ex.@: « remote », « qemu » ou « util.json » (le nom dans le -filtre peut être une sous-chaîne du nom complet de la catégorie, pour -pouvoir correspondre à plusieurs catégories similaires), le préfixe -facultatif « + » dit à libvirt d'enregistrer les traces de piles pour chaque -message qui correspond au nom, et @code{x} est le niveau minimal des -messages qui devraient être enregistrés : - -@itemize @bullet -@item -1 : DEBUG - -@item -2 : INFO - -@item -3 : WARNING - -@item -4 : ERROR - -@end itemize - -On peut définir plusieurs filtres dans une seule déclaration de filtres, ils -doivent juste être séparés par des espaces. - -La valeur par défaut est @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string log-outputs -Sorties de débogage. - -Une sortie est l'un des endroits où les journaux sont enregistrés. Le -format d'une sortie peut être : - -@table @code -@item x:stderr -la sortie va vers stderr - -@item x:syslog:nom -utilise syslog comme sortie et utilise le nom donné comme identifiant - -@item x:file:chemin_fichier -la sortie va vers un fichier, avec le chemin donné - -@item x:journald -la sortie va vers le système de journalisation journald - -@end table - -Dans tous les cas, le préfixe x est le niveau minimal, qui agit comme un -filtre - -@itemize @bullet -@item -1 : DEBUG - -@item -2 : INFO - -@item -3 : WARNING - -@item -4 : ERROR - -@end itemize - -Plusieurs sorties peuvent être définies, elles doivent juste être séparées -par des espaces. - -La valeur par défaut est @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer audit-level -Permet de modifier l'utilisation du sous-système d'audit - -@itemize @bullet -@item -0 : désactive tout audit - -@item -1 : active l'audit, seulement s'il est activé sur l'hôte - -@item -2 : active l'audit, et quitte s'il est désactivé sur l'hôte. - -@end itemize - -La valeur par défaut est @samp{1}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} boolean audit-logging -Envoie les messages d'audit via l'infrastructure de journalisation de -libvirt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} optional-string host-uuid -UUID de l'hôte. L'UUID ne doit pas avoir tous ses nombres identiques. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} string host-uuid-source -Source où lire l'UUID de l'hôte. - -@itemize @bullet -@item -@code{smbios} : récupère l'UUID à partir de @code{dmidecode -s system-uuid} - -@item -@code{machine-id} : récupère l'UUID à partir de @code{/etc/machine-id} - -@end itemize - -Si @code{dmidecode} ne fournit pas un UUID valide, un UUID temporaire sera -généré. - -La valeur par défaut est @samp{"smbios"}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer keepalive-interval -Un message keepalive est envoyé au client après @code{keepalive_interval} -secondes d'inactivité pour vérifier si le client répond toujours. Si la -valeur est -1, libvirtd n'enverra jamais de requête keepalive ; cependant -les clients peuvent toujours en envoyer et le démon y répondra. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer keepalive-count -Nombre maximum de messages keepalive qui peuvent être envoyés au client sans -réponse avant que la connexion ne soit considérée comme cassée. - -En d'autres termes, la connexion est approximativement fermée après -@code{keepalive_interval * (keepalive_count + 1)} secondes après le dernier -message reçu de la part du client. Lorsque @code{keepalive-count} est à 0, -les connexions seront automatiquement fermées après -@code{keepalive-interval} secondes d'inactivité sans envoyer le moindre -message keepalive. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-keepalive-interval -Comme précédemment, mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer admin-keepalive-count -Comme précédemment, mais pour l'interface d'administration. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{libvirt-configuration}} integer ovs-timeout -Délai d'attente pour les appels Open vSwitch. - -L'utilitaire @code{ovs-vsctl} est utilisé pour la configuration et son -option de délai d'attente est à 5 secondes pour éviter qu'une attente -infinie ne bloque libvirt. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@c %end of autogenerated docs - -@subsubheading démon Virrlog -Le service virtlogd est un démon côté serveur qui fait partie de libvirt, -utilisé pour gérer les journaux des consoles des machines virtuelles. - -Ce démon n'est pas utilisé directement par les clients libvirt, mais il est -appelé pour eux par @code{libvirtd}. En maintenant les journaux dans un -démon séparé, le démon @code{libvirtd} principal peut être redémarré sans -risque de perte de journaux. Le démon @code{virtlogd} a la possibilité de -ré-exécuter exec() sur lui-même quand il reçoit @code{SIGUSR1}, pour -permettre des mises à jour à chaux sans temps mort. - -@deffn {Variable Scheme} virtlog-service-type -Le type de service pour le démon virtlogd. Sa valeur doit être un -@code{virtlog-configuration}. - -@example -(service virtlog-service-type - (virtlog-configuration - (max-clients 1000))) -@end example -@end deffn - -@deftypevr {paramètre de @code{virtlog-configuration}} integer log-level -Niveau de journalisation. 4 : erreurs, 3 : avertissements, 2 : information, -1 : débogage. - -La valeur par défaut est @samp{3}. - -@end deftypevr - -@deftypevr {paramètre de @code{virtlog-configuration}} string log-filters -Filtres de journalisation. - -Un filtre qui permet de sélectionner plusieurs niveaux de journalisation -pour une catégorie donnée. Le format d'un filtre est : - -@itemize @bullet -@item -x:nom - -@item -x:+nom - -@end itemize - -où @code{nom} est une chaîne de caractères qui correspond à la catégorie -donnée dans @code{VIR_LOG_INIT()} au début de chaque fichier source de -libvirt, p.@: ex.@: « remote », « qemu » ou « util.json » (le nom dans le -filtre peut être une sous-chaîne du nom complet de la catégorie, pour -pouvoir correspondre à plusieurs catégories similaires), le préfixe -facultatif « + » dit à libvirt d'enregistrer les traces de piles pour chaque -message qui correspond au nom, et @code{x} est le niveau minimal des -messages qui devraient être enregistrés : - -@itemize @bullet -@item -1 : DEBUG - -@item -2 : INFO - -@item -3 : WARNING - -@item -4 : ERROR - -@end itemize - -On peut définir plusieurs filtres dans une seule déclaration de filtres, ils -doivent juste être séparés par des espaces. - -La valeur par défaut est @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {paramètre de @code{virtlog-configuration}} string log-outputs -Sorties de débogage. - -Une sortie est l'un des endroits où les journaux sont enregistrés. Le -format d'une sortie peut être : - -@table @code -@item x:stderr -la sortie va vers stderr - -@item x:syslog:nom -utilise syslog comme sortie et utilise le nom donné comme identifiant - -@item x:file:chemin_fichier -la sortie va vers un fichier, avec le chemin donné - -@item x:journald -la sortie va vers le système de journalisation journald - -@end table - -Dans tous les cas, le préfixe x est le niveau minimal, qui agit comme un -filtre - -@itemize @bullet -@item -1 : DEBUG - -@item -2 : INFO - -@item -3 : WARNING - -@item -4 : ERROR - -@end itemize - -Plusieurs sorties peuvent être définies, elles doivent juste être séparées -par des espaces. - -La valeur par défaut est @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {paramètre de @code{virtlog-configuration}} integer max-clients -Nombre maximum de connexions clientes en même temps sur tous les sockets. - -La valeur par défaut est @samp{1024}. - -@end deftypevr - -@deftypevr {paramètre de @code{virtlog-configuration}} integer max-size -Taille de fichier maximale avant roulement. - -La valeur par défaut est @samp{2MB}. - -@end deftypevr - -@deftypevr {paramètre de @code{virtlog-configuration}} integer max-backups -Nombre maximal de fichiers de sauvegardes à garder. - -La valeur par défaut est @samp{3}. - -@end deftypevr - -@subsubheading Émulation transparente avec QEMU - -@cindex émulation -@cindex @code{binfmt_misc} -@code{qemu-binfmt-service-type} fournit le support de l'émulation -transparente de binaires construits pour des architectures différentes — -p.@: ex.@: il permet d'exécuter de manière transparente des programmes ARMv -sur une machine x86_64. Cela se fait en combinant l'émulateur -@uref{https://www.qemu.org, QEMU} et la fonctionnalité @code{binfmt_misc} du -noyau Linux. - -@defvr {Variable Scheme} qemu-binfmt-service-type -Le type du service QEMU/binfmt pour l'émulation transparente. Sa valeur -doit être un objet @code{qemu-binfmt-configuration}, qui spécifie le paquet -QEMU à utiliser ainsi que l'architecture que vous voulez émuler : - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")))) -@end example - -Dans cet exemple, on active l'émulation transparente pour les plateformes -ARM et aarch64. Lancer @code{herd stop qemu-binfmt} l'éteint et lancer -@code{herd start qemu-binfmt} le rallume (@pxref{Invoking herd, the -@command{herd} command,, shepherd, The GNU Shepherd Manual}). -@end defvr - -@deftp {Type de données} qemu-binfmt-configuration -La configuration du service @code{qemu-binfmt}. - -@table @asis -@item @code{platforms} (par défaut : @code{'()}) -La liste des plates-formes émulées par QEMU. Chaque élément doit être un -objet @dfn{platform object} tel que renvoyé par @code{lookup-qemu-platforms} -(voir plus bas). - -@item @code{guix-support?} (par défaut : @code{#f}) -Lorsque la valeur est vraie, QEMU et toutes ses dépendances sont ajoutés à -l'environnement de construction de @command{guix-daemon} (@pxref{Invoquer guix-daemon, @code{--chroot-directory} option}). Cela permet d'utiliser les -gestionnaires @code{binfmt_misc} dans l'environnement de cosntruction, ce -qui signifie que vous pouvez construire des programmes pour d'autres -architectures de manière transparente. - -Par exemple, supposons que vous soyez sur une machine x86_64 et que vous -avez ce services : - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm")) - (guix-support? #t))) -@end example - -Vous pouvez lancer : - -@example -guix build -s armhf-linux inkscape -@end example - -@noindent -et cela construira Inkscape pour ARMv7 @emph{comme s'il s'agissait d'une -construction native}, de manière transparente avec QEMU pour émuler un CPU -ARMv7. Plutôt pratique si vous voulez tester un paquet construit pour une -architecture à laquelle vous n'avez pas accès ! - -@item @code{qemu} (par défaut : @code{qemu}) -Le paquet QEMU à utiliser. -@end table -@end deftp - -@deffn {Procédure Scheme} lookup-qemu-platforms @var{platforms}@dots{} -Renvoie la liste des objets de plates-formes QEMU correspondant à -@var{platforms}@dots{}. @var{platforms} doit être une liste de chaînes de -caractères correspondant aux noms de plates-formes, comme @code{"arm"}, -@code{"sparc"}, @code{"mips64el"} etc. -@end deffn - -@deffn {Procédure Scheme} qemu-platform? @var{obj} -Renvoie vrai s i@var{obj} est un objet de plate-forme. -@end deffn - -@deffn {Procédure Scheme} qemu-platform-name @var{platform} -Renvoie le nom de @var{platform} — une chaîne comme @code{"arm"}. -@end deffn - -@node Services de contrôle de version -@subsection Services de contrôle de version - -Le module @code{(gnu services version-control)} fournit un service pour -permettre l'accès à distance à des dépôts Git locaux. Il y a trois options -: en utilisant @code{git-daemon-service} qui fournit un accès aux dépôts via -le protocole non sécurisé @code{git://} basé sur TCP, en étendant le serveur -web @code{nginx} pour relayer les requêtes vers @code{git-http-backend} ou -en fournissant une interface web avec @code{cgit-service-type}. - -@deffn {Procédure Scheme} git-daemon-service [#:config (git-daemon-configuration)] - -Renvoie un service qui lance @command{git daemon}, un serveur TCP simple -pour exposer des dépôts sur le protocole Git pour des accès anonymes. - -L'argument facultatif @var{config} devrait être un objet -@code{}, par défaut il permet l'accès en -lecture-seule aux dépôts exportés@footnote{En créant le fichier magique « -git-daemon-export-ok » dans le répertoire du dépôt.} dans @file{/srv/git}. - -@end deffn - -@deftp {Type de données} git-daemon-configuration -Type de données représentnt la configuration de @code{git-daemon-service}. - -@table @asis -@item @code{package} (par défaut : @var{git}) -Objet de paquet du système de contrôle de version distribué Git. - -@item @code{export-all?} (par défaut : @var{#f}) -Indique s'il faut permettre l'accès à tous les dépôts Git, même s'ils n'ont -pas le fichier @file{git-daemon-export-ok}. - -@item @code{base-path} (par défaut : @file{/srv/git}) -Indique s'il faut traduire toutes les requêtes de chemins relativement au -chemin actuel. Si vous lancez le démon git avec @var{(base-path -"/srv/git")} sur example.com, si vous essayez ensuite de récupérer -@code{git://example.com/hello.git}, le démon git interprétera ce chemin -comme étant @code{/srv/git/hello.git}. - -@item @code{user-path} (par défaut : @var{#f}) -Indique s'il faut permettre la notation @code{~user} dans les requêtes. -Lorsque spécifié avec une chaîne vide, les requêtes à -@code{git://host/~alice/foo} sont des requêtes d'accès au dépôt @code{foo} -dans le répertoire personnel de l'utilisateur @code{alice}. Si -@var{(user-path "chemin")} est spécifié, la même requête est interprétée -comme accédant au répertoire @code{chemin/foo} dans le répertoire personnel -de l'utilisateur @code{alice}. - -@item @code{listen} (par défaut : @var{'()}) -Indique s'il faut écouter sur des adresses IP ou des noms d'hôtes -particuliers, par défaut tous. - -@item @code{port} (par défaut : @var{#f}) -Indique s'il faut écouter sur un port particulier, par défaut le 9418. - -@item @code{whitelist} (par défaut : @var{'()}) -Si la liste n'est pas vide, n'autoriser l'accès qu'aux dossiers spécifiés. - -@item @code{extra-options} (par défaut : @var{'()}) -Options supplémentaires qui seront passées à @code{git daemon}, lancez -@command{man git-daemon} pour plus d'informations. - -@end table -@end deftp - -Le protocole @code{git://} ne permet pas l'authentification. Lorsque vous -récupérez un dépôt via @code{git://}, vous ne pouvez pas savoir si les -données que vous recevez ont été modifiées ou si elles viennent bien de -l'hôte spécifié, et votre connexion pourrait être espionnée. Il est -préférable d'utiliser un protocole de transport authentifié et chiffré, -comme @code{https}. Bien que Git vous permette de servir des dépôts avec un -serveur web peu sophistiqué basé sur les fichiers, il y a un protocole plus -rapide implémenté par le programme @code{git-http-backend}. Ce programme -est le moteur des services web Git corrects. Il est conçu pour se trouver -derrière un mandataire FastCGI. @xref{Services web} pour plus -d'informations sur la manière de lancer le démon @code{fcgiwrap} nécessaire. - -Guix a un type de données de configuration séparé pour servir des dépôts Git -par HTTP. - -@deftp {Type de données} git-http-configuration -Type de données représentant la configuration de @code{git-http-service}. - -@table @asis -@item @code{package} (par défaut : @var{git}) -Objet de paquet du système de contrôle de version distribué Git. - -@item @code{git-root} (par défaut : @file{/srv/git}) -Répertoire contenant les dépôts Git à exposer au monde. - -@item @code{export-all?} (par défaut : @var{#f}) -Indique s'il faut exposer l'accès de tous les dépôts Git dans -@var{git-root}, même s'ils n'ont pas le fichier @file{git-daemon-export-ok}. - -@item @code{uri-path} (par défaut : @file{/git/}) -Préfixe du chemin pour l'accès Git. Avec le préfixe @code{/git/} par -défaut, cela traduira @code{http://@var{server}/git/@var{repo}.git} en -@code{/sr/git/@var{repo}.git}. Les requêtes dont les chemins d'URI ne -commencent pas par ce préfixe ne seront pas passées à cette instance de Git. - -@item @code{fcgiwrap-socket} (par défaut : @code{127.0.0.1:9000}) -Le socket sur lequel le démon @code{fcgiwrap} écoute. @xref{Services web}. -@end table -@end deftp - -Il n'y a pas de @code{git-http-service-type}, actuellement ; à la place vous -pouvez créer un @code{nginx-location-configuration} à partir d'un -@code{git-http-configuration} puis ajouter cela au serveur web. - -@deffn {Procédure Scheme} git-http-nginx-location-configuration @ - [config=(git-http-configuration)] -Calcule un @code{nginx-location-configuration} qui correspond à la -configuration http Git donnée. Voici un exemple de définition de service -nginx qui sert le répertoire @file{/srv/git} par défaut en HTTPS : - -@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 - -Ce exemple suppose que vous utilisez Let's Encrypt pour récupérer votre -certificat TLS. @xref{Services de certificats}. Le service @code{certbot} par -défaut redirigera tout le trafic HTTP de @code{git.my-host.org} en HTTPS. -Vous devrez aussi ajouter un mandataire @code{fcgiwrap} à vos services -systèmes. @xref{Services web}. -@end deffn - -@subsubheading Service Cgit - -@cindex service cgit -@cindex git, interface web -@uref{https://git.zx2c4.com/cgit/, Cgit} est une interface web pour des -dépôts Git écrite en C. - -L'exemple suivant configurera le service avec les valeurs par défaut. Par -défaut, on peut accéder à Cgit sur le port (@code{http://localhost:80}). - -@example -(service cgit-service-type) -@end example - -Le type @code{file-object} désigne soit un objet simili-fichier -(@pxref{G-Expressions, file-like objects}), soit une chaîne. - -@c %start of fragment - -Les champs de @code{cgit-configuration} disponibles sont : - -@deftypevr {paramètre de @code{cgit-configuration}} package package -Le paquet cgit. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} nginx-server-configuration-list nginx -Configuration Nginx. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object about-filter -Spécifie une commande qui doit être invoquée pour formater le contenu des -pages « à propos » (au plus haut niveau et pour chaque dépôt). - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string agefile -Spécifie un chemin, relativement à chaque dépôt, qui peut être utilisé pour -spécifier la date et l'heure du plus récent commit du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object auth-filter -Spécifie une commande qui sera invoquée pour authentifier l'accès au dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string branch-sort -Drapeau qui, lorsqu'il vaut @samp{age}, active le trie par date dans la -liste des branches, et le trie par nom lorsqu'il vaut @samp{name}. - -La valeur par défaut est @samp{"name"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string cache-root -Chemin utilisé pour stocker les entrées de cache de cgit. - -La valeur par défaut est @samp{"/var/cache/cgit"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-static-ttl -Nombre qui spécifie le temps de vie, en minute, des versions en cache des -pages du dépôt accédées par leur SHA-1. - -La valeur par défaut est @samp{-1}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-dynamic-ttl -Nombre qui spécifie le temps de vie, en minutes, des version en cache des -pages du dépôt accédées sans leur SHA1. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-repo-ttl -Nombre qui spécifie le temps de vie, en minute, des version en cache de la -page de résumé du dépôt. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-root-ttl -Nombre qui spécifie le temps de vie, en minutes, de la version en cache de -la page d'index du dépôt. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-scanrc-ttl -Nombre qui spécifie le temps de vie, en minutes, de la version en cache du -résultat du scan d'un chemin dans le dépôt Git. - -La valeur par défaut est @samp{15}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-about-ttl -Nombre qui spécifie le temps de vie, en minutes, de la version en cache de -la page « à propos » du dépôt. - -La valeur par défaut est @samp{15}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-snapshot-ttl -Nombre qui spécifie le temps de vie, en minutes, de la version en cache des -archives. - -La valeur par défaut est @samp{5}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer cache-size -Le nombre maximum d'entrées dans le cache de cgit. Lorsque la valeur est -@samp{0}, le cache est désactivé. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean case-sensitive-sort? -Indique si le tri des éléments est sensible à la casse. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} list clone-prefix -Liste des préfixes communs qui, lorsqu'ils sont combinés à l'URL du dépôt, -génèrent des URL de clone valides pour le dépôt. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} list clone-url -Liste des modèles @code{clone-url} - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object commit-filter -Commande qui sera invoquée pour formater les messages de commit. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string commit-sort -Drapeau qui, s'il vaut @samp{date}, active le tri par date strict dans le -messages de commit, et le tri topologique strict lorsqu'il vaut @samp{topo}. - -La valeur par défaut est @samp{"git log"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object css -URL qui spécifie le document css à inclure dans les pages cgit. - -La valeur par défaut est @samp{"/share/cgit/cgit.css"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object email-filter -Spécifie une commande qui sera invoquée pour formater les noms et l'adresse -de courriel des commiteurs, des auteurs et des taggueurs, représentés à -plusieurs endroits dans l'interface cgit. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean embedded? -Drapeau qui, s'il vaut @samp{#t}, fera générer un fragment HTML à cgit qu'il -sera possible d'inclure dans d'autres pages HTML. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-commit-graph? -Drapeau qui, lorsqu'il vaut @samp{#t}, fera afficher un historique en -ASCII-art à gauche des messages de commit dans la page de log du dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-filter-overrides? -Drapeau qui, lorsqu'il vaut @samp{#t}, permet à tous les paramètres de -filtrage d'être modifiés dans des fichiers cgitrc spécifiques au dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-follow-links? -Drapeau qui, s'il vaut @samp{#t}, permet aux utilisateurs de suivre un -fichier dans la vue « log ». - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-http-clone? -Si la valeur est @samp{#t}, cgit agira comme un point d'accès HTTP idiot -pour les clones Git. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-index-links? -Drapeau qui, s'il vaut @samp{#t}, fera générer des liens « résumé », « -commit » et « arborescence » supplémentaires poru chaque dépôt dans l'index -des dépôts. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-index-owner? -Drapeau qui, s'il vaut @samp{#t}, fera afficher le propriétaire de chaque -dépôt dans l'index des dépôts. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-log-filecount? -Drapeau qui, s'il vaut @samp{#t}, fera afficher à cgit le nombre de fichiers -modifiés pour chaque commit sur la page de log du dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-log-linecount? -Drapeau qui, s'il vaut @samp{#t}, fera afficher à cgit le nombre de lignes -ajoutées et enlevées pour chaque commit de la page de log du dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-remote-branches? -Drapeau qui, s'il vaut @samp{#t}, fera afficher les branches distantes dans -les vues du résumé et des références. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-subject-links? -Drapeau qui, s'il vaut @samp{1}, fera utiliser à cgit le sujet du commit -parent comme texte du lien lors de la génération des liens vers les commits -parents dans la vue des commits. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-html-serving? -Drapeau qui, s'il vaut @samp{#t}, fera utiliser à cgit l esujet du commit -parent comme texte du lien lors de la génération des liens vers le commit -parent dans la vue des commits. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-tree-linenumbers? -Drapeau qui, s'il vaut @samp{#t}, fera générer à cgit des liens vers le -numéro de ligne pour les blobs en texte brut affichés dans la vue de -l'arborescence. - -La valeur par défaut est @samp{#t}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean enable-git-config? -Drapeau qui, s'il vaut @samp{#t}, permettra à cgit d'utiliser la -configuration Git pour spécifier des paramètres spécifiques au dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object favicon -URL utilisée comme lien vers un icône pour cgit. - -La valeur par défaut est @samp{"/favicon.ico"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string footer -Le contenu du fichier spécifié avec cette option sera inclus directement au -bas de toutes les pages (c.-à-d.@: qu'il remplace le message « généré par -…@: » générique). - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string head-include -Le contenu du fichier spécifié dans cette option sera inclus directement -dans la section HEAD HTML de toutes les pages. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string header -Le contenu du fichier spécifié avec cette option sera inclus directement au -début de toutes les pages. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object include -Nom d'un fichier de configuration à inclure avant que le reste du fichier de -configuration actuel ne soit analysé. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string index-header -Le contenu du fichier spécifié avec cette option sera inclus directement au -dessus de l'index des dépôts. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string index-info -Le contenu du fichier spécifié avec cette option sera inclus directement en -dessous de l'en-tête sur la page d'index du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean local-time? -Drapeau qui, s'il vaut @samp{#t}, fera afficher à cgit l'heure et la date de -commit et de tag dans le fuseau horaire du serveur. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object logo -URL qui spécifie la source d'une image utilisé comme logo sur toutes les -pages cgit. - -La valeur par défaut est @samp{"/share/cgit/cgit.png"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string logo-link -URL chargée lors du clic sur l'image du logo de cgit. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object owner-filter -Commande qui sera invoquée pour formater la colonne propriétaire sur la page -principale. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-atom-items -Nombre d'éléments à afficher dans la vue des flux atom. - -La valeur par défaut est @samp{10}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-commit-count -Nombre d'éléments à lister par page dans la vue « log ». - -La valeur par défaut est @samp{50}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-message-length -Nombre caractères de messages de commit à afficher dans la vue « log ». - -La valeur par défaut est @samp{80}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-repo-count -Spécifie le nombre d'éléments à lister par page sur la page de l'index des -dépôts. - -La valeur par défaut est @samp{50}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-repodesc-length -Spécifie le nombre maximum de caractères de description de dépôts à afficher -sur la page d'index des dépôts. - -La valeur par défaut est @samp{80}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer max-blob-size -Spécifie la taille maximale d'un blob pour lequel afficher du HTML en -kilo-octets. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string max-stats -Période de statistiques maximale. Les valeurs valides sont @samp{week}, -@samp{month}, @samp{quarter} et @samp{year}. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} mimetype-alist mimetype -Type mime pour l'extension de fichier spécifiée. - -La valeur par défaut est @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 {paramètre de @code{cgit-configuration}} file-object mimetype-file -Spécifie le fichier à utiliser pour la recherche automatique de type mime. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string module-link -Texte qui sera utilisé comme chaîne de formatage pour un lien hypertexte -lorsqu'un sous-module est affiché dans la liste du répertoire. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean nocache? -Si la valeur est @samp{#t}, le cache est désactivé. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean noplainemail? -Si la valeur est @samp{#t}, l'affichage des adresse de courriel des auteurs -sera désactivé. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean noheader? -Drapeau qui, s'il vaut @samp{#t}, fera omettre à cgit l'en-tête standard sur -toutes les pages. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} project-list project-list -UNe liste de sous-répertoires dans @code{repository-directory}, relativement -à lui, qui devrait être chargé comme des dépôts Git. Une liste vide -signifie que tous les sous-répertoires seront chargés. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object readme -Texte utilisé comme valeur par défaut pour @code{cgit-repo-readme}. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean remove-suffix? -Si la valeur est @code{#t} et que @code{repository-directory} est activé, si -un dépôt avec un suffixe de @code{.git} est trouvé, ce suffixe sera supprimé -de l'URL et du nom. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer renamelimit -Nombre maximum de fichiers à considérer lors de la détection des renommages. - -La valeur par défaut est @samp{-1}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string repository-sort -La manière dont les dépôt de chaque section sont rangés. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} robots-list robots -Texte utilisé comme contenu du méta-attribut @code{robots}. - -La valeur par défaut est @samp{("noindex" "nofollow")}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string root-desc -Texte affiché en dessous de l'en-tête de la page d'index des dépôts. - -La valeur par défaut est @samp{"a fast webinterface for the git dscm"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string root-readme -Le contenu du fichier spécifié avec cette option sera inclus directement en -dessous du lien « à propos » sur la page d'index du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string root-title -Texte affiché sur la page d'index des dépôts. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean scan-hidden-path -Si la valeur est @samp{#t} et que repository-directory est activé, -repository-directory recherchera de manière récursive dans les répertoires -dont le nom commence par un point. Sinon, repository-directory restera hors -de ces répertoires, considérés comme « cachés ». Remarquez que cela ne -s'applique pas au répertoire « .git » dans le dépôts. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} list snapshots -Texte qui spécifie l'ensemble des formats d'archives par défaut pour -lesquelles cgit générera un lien. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} repository-directory repository-directory -Nom du répertoire à scanner pour trouver les dépôts (représente -@code{scan-path}). - -La valeur par défaut est @samp{"/srv/git"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string section -Le nom de la section de dépôts actuelle — tous les dépôts définis après ce -point hériterons du nom de section actuel. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string section-sort -Drapeau qui, s'il vaut @samp{1}, triera les sections dans la liste des -dépôts par nom. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer section-from-path -Un nombre qui, s'il est défini avant repository-directory, spécifier combien -d'éléments de chemin de chaque chemin de dépôt utiliser comme nom de section -par défaut. - -La valeur par défaut est @samp{0}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} boolean side-by-side-diffs? -Si la valeur est @samp{#t}, afficher des diffs côte à côte au lieu des -unidiffs par défaut. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} file-object source-filter -Spécifie une commande qui sera invoquée pour formater les blobs en texte -brut dans la vue de l'arborescence. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer summary-branches -Spécifie le nombre de branches à afficher dans la vue de résumé du dépôt. - -La valeur par défaut est @samp{10}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer summary-log -Spécifie le nombre d'élément du journal à afficher dans la vue résumé du -dépôt. - -La valeur par défaut est @samp{10}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} integer summary-tags -Spécifie le nombre de tags à afficher dans la vue résumé du dépôt. - -La valeur par défaut est @samp{10}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string strict-export -Nom de fichier qui, s'il est spécifié, doit être présent dans le dépôt pour -que cgit accorde l'accès à ce dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} string virtual-root -URL qui, si elle est spécifiée, sera utilisée comme racine pour tous les -liens cgit. - -La valeur par défaut est @samp{"/"}. - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} repository-cgit-configuration-list repositories -Une liste d'enregistrements @dfn{cgit-repo} à utiliser avec config. - -La valeur par défaut est @samp{()}. - -Les champs de @code{repository-cgit-configuration} disponibles sont : - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-list snapshots -Un masque de formats d'archives pour ce dépôt pour lesquelles cgit générera -un lien, restreint par le paramètre @code{snapshots} global. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object source-filter -Modifie le @code{source-filter} par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string url -URL relative utilisée pour accéder au dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object about-filter -Modifie le paramètre @code{about-filter} par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string branch-sort -Drapeau qui, s'il vaut @samp{age}, active le tri par date dans la liste des -branches, et lorsqu'il vaut @samp{name}, le tri par nom. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-list clone-url -Un liste d'URL qui peuvent être utilisées pour cloner ce dépôt. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object commit-filter -Modifie le paramètre @code{commit-filter} par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string commit-sort -Drapeau qui, s'il vaut @samp{date}, active le tri par date strict dans le -messages de commit, et le tri topologique strict lorsqu'il vaut @samp{topo}. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string defbranch -Le nom de la branche par défaut de ce dépôt. Si cette branche n'existe pas -dans le dépôt, le premier nom de branche (trié) sera utilisé par défaut. -Par défaut la branche pointée par HEAD, ou « master » s'il n'y a pas de HEAD -convenable. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string desc -La valeur à afficher comme description du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string homepage -La valeur à afficher comme page d'accueil du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object email-filter -Modifie le paramètre @code{email-filter} par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-commit-graph? -Un drapeau qui peut être utilisé pour désactiver le paramètre -@code{enable-commit-graph?} global. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-log-filecount? -Un drapeau qui peut être utilisé pour désactiver le paramètre -@code{enable-log-filecount?} global. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-log-linecount? -Un drapeau qui peut être utilisé pour désactiver le paramètre -@code{enable-log-linecount?} global. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-remote-branches? -Drapeau qui, s'il vaut @samp{#t}, fera afficher les branches distantes dans -les vues du résumé et des références. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-subject-links? -Un drapeau qui peut être utilisé pour modifier le paramètre -@code{enable-subject-links?} global. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} maybe-repo-boolean enable-html-serving? -Un drapeau qui peut être utilisé pour modifier le paramètre -@code{enable-html-serving?} global. - -La valeur par défaut est @samp{disabled}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-boolean hide? -Drapeau qui, s'il vaut @code{#t}, cache le dépôt de l'index des dépôts. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-boolean ignore? -Drapeau qui, s'il vaut @code{#t}, ignore le dépôt. - -La valeur par défaut est @samp{#f}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object logo -URL qui spécifie la source d'une image qui sera utilisée comme logo sur les -pages de ce dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string logo-link -URL chargée lors du clic sur l'image du logo de cgit. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-file-object owner-filter -Modifie le paramètre @code{owner-filter} par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string module-link -Texte qui sera utilisé comme chaîne de formatage pour un lien hypertexte -lorsqu'un sous-module est affiché dans une liste de fichiers. Les arguments -pour la chaîne de formatage sont le chemin et le SHA1 du commit du -sous-module. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} module-link-path module-link-path -Texte qui sera utilisé comme chaîne de formatage lorsqu'un sous-module avec -un chemin spécifié sera affiché dans une liste de fichiers. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string max-stats -Modifie la période de statistique maximale par défaut. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string name -La valeur à afficher comme nom de dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string owner -Une valeur utilisée pour identifier le propriétaire du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string path -Un chemin absolu vers le répertoire du dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string readme -Un chemin (relatif au dépôt) qui spécifie un fichier à inclure directement -comme page « À propos » pour ce dépôt. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-string section -Le nom de la section de dépôts actuelle — tous les dépôts définis après ce -point hériterons du nom de section actuel. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {paramètre de @code{repository-cgit-configuration}} repo-list extra-options -Options supplémentaires ajoutées à la fin du fichier cgitrc. - -La valeur par défaut est @samp{()}. - -@end deftypevr - -@end deftypevr - -@deftypevr {paramètre de @code{cgit-configuration}} list extra-options -Options supplémentaires ajoutées à la fin du fichier cgitrc. - -La valeur par défaut est @samp{()}. - -@end deftypevr - - -@c %end of fragment - -Cependant, vous pourriez vouloir simplement récupérer un @code{cgitrc} et -l'utiliser. Dans ce cas, vous pouvez passer un -@code{opaque-cgit-configuration} comme enregistrement à -@code{cgit-service-type}. Comme son nom l'indique, une configuration opaque -n'a pas de capacité de réflexion facile. - -Les champs de @code{opaque-cgit-configuration} disponibles sont : - -@deftypevr {paramètre de @code{opaque-cgit-configuration}} package cgit -Le paquet cgit. -@end deftypevr - -@deftypevr {paramètre de @code{opaque-cgit-configuration}} string string -Le contenu de @code{cgitrc}, en tant que chaîne de caractère. -@end deftypevr - -Par exemple, si votre @code{cgitrc} est juste la chaîne vide, vous pouvez -instancier un service cgit ainsi : - -@example -(service cgit-service-type - (opaque-cgit-configuration - (cgitrc ""))) -@end example - -@subsubheading Service Gitolite - -@cindex service Gitolite -@cindex Git, hébergement -@uref{http://gitolite.com/gitolite/, Gitolite} est un outil pour héberger -des dépôts Git sur un serveur central. - -Gitolite peut gérer plusieurs dépôts et utilisateurs et supporte une -configuration flexible des permissions pour les utilisateurs sur ces dépôts. - -L'exemple suivant configure Gitolite en utilisant l'utilisateur @code{git} -par défaut et la clef SSH fournie. - -@example -(service gitolite-service-type - (gitolite-configuration - (admin-pubkey (plain-file - "yourname.pub" - "ssh-rsa AAAA... guix@@example.com")))) -@end example - -Gitolite est configuré via un dépôt d'administration spécial que vous pouvez -cloner. Par exemple, si vous hébergez Gitolite sur @code{example.com}, vous -pouvez lancer la commande suivante pour cloner le dépôt d'administration. - -@example -git clone git@@example.com:gitolite-admin -@end example - -Lorsque le service Gitolite est activé, la clef @code{admin-pubkey} fournie -sera insérée dans le répertoire @file{keydir} du dépôt gitolite-admin. Si -cela change le dépôt, un commit sera effectué avec le message « gitolite -setup by GNU Guix ». - -@deftp {Type de données} gitolite-configuration -Type de données représentant la configuration de -@code{gitolite-service-type}. - -@table @asis -@item @code{package} (par défaut : @var{gitolite}) -Le paquet Gitolite à utiliser. - -@item @code{user} (par défaut : @var{git}) -Utilisateur pour utiliser Gitolite. Cela sera l'utilisateur à utiliser pour -accéder à Gitolite par SSH. - -@item @code{group} (par défaut : @var{git}) -Groupe à utiliser pour Gitolite. - -@item @code{home-directory} (par défaut : @var{"/var/lib/gitolite"}) -Répertoire dans lequel stocker la configuration et les dépôts de Gitolite. - -@item @code{rc-file} (par défaut : @var{(gitolite-rc-file)}) -Un objet « simili-fichier » (@pxref{G-Expressions, file-like objects}) -représentant la configuration de Gitolite. - -@item @code{admin-pubkey} (par défaut : @var{#f}) -Un objet « simili-fichier » (@pxref{G-Expressions, file-like objects}) -utilisé pour paramétrer Gitolite. Il sera inséré dans le répertoire -@file{keydir} dans le dépôt gitolite-admin. - -Pour spécifier la clef SSH comme chaîne de caractère, utilisez la fonction -@code{plain-file}. - -@example -(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") -@end example - -@end table -@end deftp - -@deftp {Type de données} gitolite-rc-file -Type de données représentant le fichier RC de Gitolite. - -@table @asis -@item @code{umask} (par défaut : @code{#o0077}) -Cela contrôle les permissions que Gitolite propose sur les dépôts et leur -contenu. - -Une valeur comme @code{#o0027} donnera accès en lecture au groupe utilisé -par Gitolite (par défaut : @code{git}). Cel aest nécessaire lorsque vous -utilise Gitolite avec un logiciel comme cgit ou gitweb. - -@item @code{git-config-keys} (par défaut : @code{""}) -Gitolite vous permet de modifier les configurations git avec le mot-clef « -config ». Ce paramètre vous permet de contrôler les clefs de configuration -acceptables. - -@item @code{roles} (par défaut : @code{'(("READERS" . 1) ("WRITERS" . ))}) -Indique les noms des rôles qui peuvent être utilisés par les utilisateurs -avec la commande perms. - -@item @code{enable} (par défaut : @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")}) -Ce paramètre contrôle les commandes et les fonctionnalités à activer dans -Gitolite. - -@end table -@end deftp - - -@node Services de jeu -@subsection Services de jeu - -@subsubheading Le service de la Bataille pour Wesnoth -@cindex wesnothd -@uref{https://wesnoth.org, La Bataille pour Wesnoth} est un jeu de stratégie -en tour par tour dans un univers fantastique, avec plusieurs campagnes solo -et des parties multijoueurs (en réseau et en local). - -@defvar {Variable Scheme} wesnothd-service-type -Type de service pour le service wesnothd. Sa valeur doit être un objet -@code{wesnothd-configuration}. Pour lancer wesnothd avec la configuration -par défaut, instanciez-le ainsi : - -@example -(service wesnothd-service-type) -@end example -@end defvar - -@deftp {Type de données} wesnothd-configuration -Type de donées représentant la configuration de @command{wesnothd}. - -@table @asis -@item @code{package} (par défaut : @code{wesnoth-server}) -Le paquet de serveur de wesnoth à utiliser. - -@item @code{port} (par défaut : @code{15000}) -Le pour sur lequel lier le serveur. -@end table -@end deftp - -@node Services divers -@subsection Services divers - -@cindex empreinte digitale -@subsubheading Service d'empreintes digitales - -The @code{(gnu services authentication)} module provides a DBus service to -read and identify fingerprints via a fingerprint sensor. - -@defvr {Variable Scheme} fprintd-service-type -Le type de service pour @command{fprintd}, qui fournit des capacités de -lecture d'empreinte. - -@example -(service fprintd-service-type) -@end example -@end defvr - -@cindex sysctl -@subsubheading Service de contrôle du système - -Le module @code{(gnu services sysctl)} fournit un service pour configurer -les paramètres du noyau au démarrage. - -@defvr {Variable Scheme} sysctl-service-type -Le type de service pour @command{sysctl}, qui modifie les paramètres du -noyau dans @file{/proc/sys/}. Pour activer le transfert d'IPv4, vous pouvez -l'instancier ainsi : - -@example -(service sysctl-service-type - (sysctl-configuration - (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example -@end defvr - -@deftp {Type de données} sysctl-configuration -Le type de données représentant la configuration de @command{sysctl}. - -@table @asis -@item @code{sysctl} (par défaut : @code{(file-append procps "/sbin/sysctl"}) -L'exécutable @command{sysctl} à utiliser. - -@item @code{settings} (par défaut : @code{'()}) -Une liste d'association spécifiant les paramètres du noyau et leur valeur. -@end table -@end deftp - -@cindex pcscd -@subsubheading Service du démon PC/SC Smart Card - -Le module @code{(gnu services security-token)} fournit le service suivant -qui lance @command{pcscd}, le démon PC/SC Smart Card. @command{pcscd} est -le démon pour pcsc-lite et MuscleCard. C'est un gestionnaire de ressource -qui coordonne les communications avec les lecteurs de smart cards, les smart -cards et les jetons cryptographiques connectés au système. - -@defvr {Variable Scheme} pcscd-service-type -Le type de service pour le service @command{pcscd}. Sa valeur doit être un -objet @code{pcscd-configuration}. Pour lancer pcscd dans sa configuration -par défaut, instantiez-le avec : - -@example -(service pcscd-service-type) -@end example -@end defvr - -@deftp {Type de données} pcscd-configuration -Type de données représentant la configuration de @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (par défaut : @code{pcsc-lite}) -Le paquet pcsc-lite qui fournit pcscd. -@item @code{usb-drivers} (par défaut : @code{(list ccid)}) -Liste des paquets qui fournissent des pilotes USB à pcscd. Les pilotes -doivent être dans @file{pcsc/drivers} dans le répertoire du dépôt du paquet. -@end table -@end deftp - -@cindex lirc -@subsubheading Service Lirc - -Le module @code{(gnu services lirc)} fournit le service suivant. - -@deffn {Procédure Scheme} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ -[#:extra-options '()] -Renvoie un service qui lance @url{http://www.lirc.org,LIRC}, un démon qui -décode les signaux infrarouges des télécommandes. - -Éventuellement, @var{device}, @var{driver} et @var{config-file} (le nom du -fichier de configuration) peuvent être spécifiés. Voir le manuel de -@command{lircd} pour plus de détails. - -Enfin, @var{extra-options} est une liste d'options de la ligne de commande -supplémentaires à passer à @command{lircd}. -@end deffn - -@cindex spice -@subsubheading Service Spice - -Le module @code{(gnu services spice)} fournit le service suivant. - -@deffn {Procédure Scheme} spice-vdagent-service [#:spice-vdagent] -Renvoie un service qui lance @url{http://www.spice-space.org,VDAGENT}, un -démon qui permet le partage du presse-papier avec une vm et de configurer la -résolution d'affichage du client lorsque la fenêtre de la console graphique -est redimensionnée. -@end deffn - -@cindex inputattach -@subsubheading Service inputattach - -@cindex entrée tablette, pour Xorg -@cindex écran tactile, pour Xorg -Le service @uref{https://linuxwacom.github.io/, inputattach} vous permet -d'utiliser des périphériques d'entrée comme les tablettes Wacom, les écrans -tactiles ou les joysticks avec le serveur d'affichage Xorg. - -@deffn {Variable Scheme} inputattach-service-type -Type d'un service qui lance @command{inputattach} sur un appareil et envie -les événements qu'il reçoit. -@end deffn - -@deftp {Type de données} inputattach-configuration -@table @asis -@item @code{device-type} (par défaut : @code{"wacom"}) -Le type du périphérique à gérer. Lancez @command{inputattach --help}, du -paquet @code{inputattach}, pour voir la liste des types de périphériques -supportés. - -@item @code{device} (par défaut : @code{"/dev/ttyS0"}) -Le fichier de périphérique pour s'y connecter. - -@item @code{log-file} (par défaut : @code{#f}) -Si la valeur est vraie, cela doit être le nom d'un fichier où enregistrer -les messages. -@end table -@end deftp - -@subsection Services de dictionnaires -@cindex dictionnaire -Le module @code{(gnu services dict)} fournit le service suivant : - -@deffn {Procédure Scheme} dicod-service [#:config (dicod-configuration)] -Renvoie un service qui lance le démon @command{dicod}, une implémentation du -serveur DICT (@pxref{Dicod,,, dico, GNU Dico Manual}). - -L'argument @var{config} facultatif spécifie la configuration pour -@command{dicod}, qui devrait être un objet @code{}, par -défaut il sert le dictionnaire international collaboratif de GNU pour -l'anglais. - -Vous pouvez ajouter @command{open localhost} à votre fichier @file{~/.dico} -pour faire de @code{localhost} le serveur par défaut du client -@command{dico} (@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn - -@deftp {Type de données} dicod-configuration -Type de données représentant la configuration de dicod. - -@table @asis -@item @code{dico} (par défaut : @var{dico}) -Objet de paquet du serveur de dictionnaire GNU Dico. - -@item @code{interfaces} (par défaut : @var{'("localhost")}) -C'est la liste des adresses IP et des ports et éventuellement des noms de -fichiers de socket sur lesquels écouter (@pxref{Server Settings, -@code{listen} directive,, dico, GNU Dico Manual}). - -@item @code{handlers} (par défaut : @var{'()}) -Liste des objets @code{} qui définissent des gestionnaires -(des instances de modules). - -@item @code{databases} (par défaut : @var{(list %dicod-database:gcide)}) -Liste d'objets @code{} qui définissent des dictionnaires à -servir. -@end table -@end deftp - -@deftp {Type de données} dicod-handler -Type de données représentant un gestionnaire de dictionnaire (instance de -module). - -@table @asis -@item @code{name} -Nom du gestionnaire (instance de module). - -@item @code{module} (par défaut : @var{#f}) -Nom du module dicod du gestionnaire (instance). Si la valeur est @code{#f}, -le module a le même nom que le gestionnaire. (@pxref{Modules,,, dico, GNU -Dico Manual}). - -@item @code{options} -Liste de chaînes ou de gexps représentant les arguments pour le gestionnaire -de module -@end table -@end deftp - -@deftp {Type de données} dicod-database -Type de données représentant une base de données de dictionnaire. - -@table @asis -@item @code{name} -Nom de la base de données, qui sera utilisée dans les commande DICT. - -@item @code{handler} -Nom du gestionnaire dicod (instance de module) utilisé par cette base de -données (@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (par défaut : @var{#f}) -Indique si la configuration est pour une base de données complexe. La -configuration complexe a besoin d'un objet @code{} -correspondant, sinon inutile. - -@item @code{options} -Liste de chaînes ou de gexps représentant les arguments pour la base de -données (@pxref{Databases,,, dico, GNU Dico Manual}). -@end table -@end deftp - -@defvr {Variable Scheme} %dicod-database:gcide -Un objet @code{} servant le dictionnaire international -collaboratif en anglais via le paquet @code{gcide}. -@end defvr - -Voici un exemple de configuration de @code{dicod-service}. - -@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 Service Docker - -Le module @code{(gnu services docker)} fournit le service suivant. - -@defvr {Variable Scheme} docker-service-type - -C'est le type du service qui lance @url{http://www.docker.com,Docker}, un -démon qui peut exécuter des lots applicatifs (aussi appelés « conteneurs ») -dans des environnements isolés. - -@end defvr - -@deftp {Type de données} docker-configuration -Le type de données qui représente la configuration de Docker et Containerd. - -@table @asis - -@item @code{package} (par défaut : @code{docker}) -Le paquet Docker à utiliser. - -@item @code{containerd} (par défaut : @var{containerd}) -Le paquet Containerd à utiliser. - -@end table -@end deftp - -@node Programmes setuid -@section Programmes setuid - -@cindex programmes setuid -Certains programmes doivent être lancés avec les privilèges « root » même -lorsqu'ils sont lancés par un utilisateur non privilégié. Un exemple -notoire est le programme @command{passwd}, que les utilisateurs peuvent -appeler pour modifier leur mot de passe et qui doit accéder à -@file{/etc/passwd} et @file{/etc/shadow} — ce qui est normalement réservé à -root, pour des raisons de sécurité évidentes. Pour contourner cela, ces -exécutables sont @dfn{setuid-root}, ce qui signifie qu'ils seront toujours -lancés avec les privilèges root (@pxref{How Change Persona,,, libc, The GNU -C Library Reference Manual}, pour plus d'informations sur le mécanisme -setuid). - -Le dépôt lui-même ne @emph{peut pas} contenir de programmes setuid ; cela -serait un problème de sécurité puisque n'importe quel utilisateur du système -peut écrire une dérivation qui rempli le dépôt (@pxref{Le dépôt}). Donc, -un mécanisme différent est utilisé : au lieu de changer le bit setuid -directement sur les fichiers qui sont dans le dépôt, nous laissons à -l'administrateur système le soit de @emph{déclarer} les programmes qui -devraient être setuid root. - -Le champ @code{setuid-programs} d'une déclaration @code{operating-system} -contient une liste de G-expressions qui dénotent les noms des programmes à -rendre setuid-root (@pxref{Utiliser le système de configuration}). Par exemple, -le programme @command{passwd}, qui fait partie du paquet Shadow, peut être -désigné par cette G-expression (@pxref{G-Expressions}) : - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -Un ensemble de programmes par défaut est défini par la variable -@code{%setuid-programs} du module @code{(gnu system)}. - -@defvr {Variable Scheme} %setuid-programs -Une liste de G-expressions qui dénotent les programmes communément -setuid-root. - -La liste inclus des commandes comme @command{passwd}, @command{ping}, -@command{su} et @command{sudo}. -@end defvr - -Sous le capot, les programmes setuid sont créés dans le répertoire -@file{/run/setuid-programs} au moment de l'activation du système. Les -fichiers dans ce répertoire se réfèrent aux « vrais » binaires, qui sont -dans le dépot. - -@node Certificats X.509 -@section Certificats X.509 - -@cindex HTTPS, certificats -@cindex certificats X.509 -@cindex TLS -Les serveurs web disponibles par HTTPS (c'est-à-dire HTTP sur le mécanisme -de la couche de transport sécurisée, TLS) envoient aux clients un -@dfn{certificat X.509} que les clients peuvent utiliser pour -@emph{authentifier} le serveur. Pour cela, les clients vérifient que le -certificat du serveur est signé par une @dfn{autorité de certification} (AC -ou CA). Mais pour vérifier la signature de la CA, les clients doivent -d'abord avoir récupéré le certificat de la CA. - -Les navigateurs web comme GNU@tie{}IceCat incluent leur propre liste de -certificats, pour qu'ils puissent vérifier les signatures des CA -directement. - -Cependant, la plupart des autres programmes qui peuvent parler HTTPS — -@command{wget}, @command{git}, @command{w3m}, etc — doivent savoir où -trouver les certificats des CA. - -@cindex @code{nss-certs} -Dans Guix, cela se fait en ajoutant un paquet qui fournit les certificats -dans le champ @code{packages} de la déclaration @code{operating-system} -(@pxref{Référence de système d'exploitation}). Guix inclut l'un de ces paquets, -@code{nss-certs}, qui est un ensemble de certificats de CA fourni par les -services de sécurité réseau de Mozilla (nss). - -Remarquez qu'il ne fait @emph{pas} partie de @var{%base-packages}, donc vous -devez explicitement l'ajouter. Le répertoire @file{/etc/ssl/certs}, là où -la plupart des applications et bibliothèques vont rechercher les certificats -par défaut, pointe vers les certificats installés globalement. - -Les utilisateurs non privilégiés, dont les utilisateurs de Guix sur une -distro externe, peuvent aussi installer leur propre paquet de certificats -dans leur profil. Un certain nombre de variables d'environnement doivent -être définies pour que les applications et les bibliothèques puissent les -trouver. En particulier, la bibliothèque OpenSSL honore les variables -@code{SSL_CERT_DIR} et @code{SSL_CERT_FILE}. Certaines applications -ajoutent leurs propres variables, par exemple le système de contrôle de -version Git honore le lot de certificats pointé par la variable -d'environnement @code{GIT_SSL_CAINFO}. Ainsi, vous lanceriez quelque chose -comme ceci : - -@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 - -Un autre exemple serait R, qui requière que la variable d'environnement -@code{CURL_CA_BUNDLE} pointe sur le lot de certificats, donc vous lanceriez -quelque chose comme ceci : - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -Pour d'autres applications vous pourriez avoir besoin de chercher la -variable d'environnement requise dans leur documentation. - - -@node Name Service Switch -@section Name Service Switch - -@cindex name service switch -@cindex NSS -Le module @code{(gnu system nss)} fournit des liaisons pour le fichier de -configuration du @dfn{name service switch} ou @dfn{NSS} de la libc -(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference -Manual}). En résumé, NSS est un mécanisme qui permet à la libc d'être -étendue avec de nouvelles méthodes de résolution de « noms » dans les bases -de données du système, comme les noms d'hôtes, les noms des services, les -comptes utilisateurs et bien plus (@pxref{Name Service Switch, System -Databases and Name Service Switch,, libc, The GNU C Library Reference -Manual}). - -La configuration de NSS spécifie, pour chaque base de données du système, -quelle méthode de résolution utiliser, et comment les diverses méthodes sont -enchaînées — par exemple, sous certaines circonstances, NSS devrait essayer -la méthode suivante de la liste. La configuration de NSS est donnée dans le -champ @code{name-service-switch} de la déclaration @code{operating-system} -(@pxref{Référence de système d'exploitation, @code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, résolution de nom d'hôte -Par exemple, la déclation ci-dessous configure NSS pour utiliser le -@uref{http://0pointer.de/lennart/projects/nss-mdns/, moteur -@code{nss-mdns}}, qui supporte la résolution de nom d'hôte sur le DNS -multicast (mDNS) pour les noms d'hôtes terminant par @code{.local} : - -@example -(name-service-switch - (hosts (list %files ;first, check /etc/hosts - - ;; Si ce qui précède n'a pas fonctionné, essayer - ;; avec « mdns_minimal ». - (name-service - (name "mdns_minimal") - - ;; « mdns_minimal » fait autorité pour - ;; « .local ». Lorsqu'il renvoie « pas trouvé », - ;; inutile d'essayer la méthode suivante. - (reaction (lookup-specification - (not-found => return)))) - - ;; Puis revenir sur DNS. - (name-service - (name "dns")) - - ;; Enfin, essayer avec « mdns complet ». - (name-service - (name "mdns"))))) -@end example - -Ne vous inquiétez pas : la variable @code{%mdns-host-lookup-nss} (voir plus -bas) contient cette configuration, donc vous n'avez pas besoin de tout taper -si vous voulez simplement que la résolution de nom en @code{.local} -fonctionne. - -Remarquez que dans ce cas, en plus de mettre en place le -@code{name-service-switch} de la déclaration @code{operating-system}, vous -devez aussi utiliser @code{avahi-service-type} (@pxref{Services réseau, -@code{avahi-service}}), ou @var{%desktop-services} qui l'inclut -(@pxref{Services de bureaux}). Cela rend @code{nss-mdns} accessible au démon -de cache du service de nom (@pxref{Services de base, @code{nscd-service}}). - -Pour votre confort, les variables suivantes contiennent des configurations -NSS typiques. - -@defvr {Variable Scheme} %default-nss -C'est la configuration NSS par défaut, un objet @code{name-service-switch}. -@end defvr - -@defvr {Variable Scheme} %mdns-host-lookup-nss -C'est la configuration NSS avec le support de la résolution de noms sur DNS -multicast (mDNS) pour les noms d'hôtes en @code{.local}. -@end defvr - -La référence pour la configuration de NSS est donnée ci-dessous. C'est une -correspondance directe avec le format de fichier de la bibliothèque C, donc -référez-vous au manuel de la bibliothèque C pour plus d'informations -(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference -Manual}). Comparé au format de fichier de configuration de NSS, cette -configuration a l'avantage non seulement d'ajouter ces bonnes vieilles -parenthèses, mais aussi des vérifications statiques ; vous saurez s'il y a -des erreurs de syntaxe et des coquilles dès que vous lancerez @command{guix -system}. - -@deftp {Type de données} name-service-switch - -C'est le type de données représentant la configuration de NSS. Chaque champ -ci-dessous représente l'un des système de bases de données supportés. - -@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 -Les bases de données du système gérées par NSS. Chaque champ doit être une -liste d'objets @code{} (voir plus bas). -@end table -@end deftp - -@deftp {Type de données} name-service - -C'est le type de données représentant un service de noms et l'action de -résolution associée. - -@table @code -@item name -Une chaîne dénotant le service de nom (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). - -Remarquez que les services de dnoms listés ici doivent être visibles à -nscd. Cela se fait en passant la liste des paquets fournissant les services -de noms à l'argument @code{#:name-services} de @code{nscd-service} -(@pxref{Services de base, @code{nscd-service}}). - -@item reaction -Une action spécifiée par la macro @code{lookup-specification} -(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library -Reference Manual}). Par exemple : - -@example -(lookup-specification (unavailable => continue) - (success => return)) -@end example -@end table -@end deftp - -@node Disque de RAM initial -@section Disque de RAM initial - -@cindex initrd -@cindex disque de RAM initial -Pour le démarrage, on passe au noyau Linux-Libre un @dfn{disque de RAM -initial} ou @dfn{initrd}. Un initrd contient un système de fichier racine -temporaire ainsi qu'un script d'initialisation. Ce dernier est responsable -du montage du vrai système de fichier racine et du chargement des modules du -noyau qui peuvent être nécessaires à cette tâche. - -Le champ @code{initrd-modules} d'une déclaration @code{operating-system} -vous permet de spécifier les modules du noyau Linux-Libre qui doivent être -disponibles dans l'initrd. En particulier, c'est là où vous devez lister -les modules requis pour effectivement piloter le disque dur où se trouve la -partition racine — bien que la valeur par défaut de @code{initrd-modules} -couvre la plupart des cas. Par exemple, en supposant que vous ayez besoin -du module @code{megaraid_sas} en plus des modules par défaut pour accéder à -votre système de fichiers racine, vous écririez : - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Variable Scheme} %base-initrd-modules -C'est la liste des modules du noyau inclus dans l'initrd par défaut. -@end defvr - -En plus, si vous avez besoin de paramétrages plus bas niveau, le champ -@code{initrd} d'une déclaration @code{operating-system} vous permet de -spécifier quel initrd vous voudriez utiliser. Le module @code{(gnu system -linux-initrd)} fournit trois manières de construire un initrd : la procédure -@code{base-initrd} de haut niveau et les procédures @code{raw-initrd} et -@code{expression->initrd} de bas niveau. - -La procédure @code{base-initrd} est conçue pour couvrir la plupart des -usages courants. Par exemple, si vous voulez ajouter des modules du noyau à -charger au démarrage, vous pouvez définir le champ @code{initrd} de votre -déclaration de système d'exploitation ainsi : - -@example -(initrd (lambda (file-systems . rest) - ;; Crée un initrd standard mais paramètre le réseau - ;; avec les paramètres que QEMU attend par défaut. - (apply base-initrd file-systems - #:qemu-networking? #t - rest))) -@end example - -La procédure @code{base-initrd} gère aussi les cas d'utilisation courants -qui concernent l'utilisation du système comme client QEMU, ou comme un -système « live » avec un système de fichier racine volatile. - -La procédure @code{base-initrd} est construite à partir de la procédure -@code{raw-initrd}. Contrairement à @code{base-initrd}, @code{raw-initrd} ne -fait rien à haut-niveau, comme essayer de deviner les modules du noyau et -les paquets qui devraient être inclus dans l'initrd. Un exemple -d'utilisation de @code{raw-initrd} serait si un utilisateur a une -configuration personnalisée du noyau Linux et que les modules du noyau -inclus par défaut par @code{base-initrd} ne sont pas disponibles. - -Le disque de RAM initial produit par @code{base-initrd} ou @code{raw-initrd} -honore plusieurs options passées par la ligne de commande du noyau Linux -(c'est-à-dire les arguments passés via la commande @code{linux} de GRUB ou -l'option @code{-append} de QEMU), notamment : - -@table @code -@item --load=@var{boot} -Dit au disque de RAM initial de charger @var{boot}, un fichier contenant un -programme Scheme, une fois qu'il a monté le système de fichier racine. - -Guix utilise cette option pour donner le contrôle à un programme de -démarrage qui lance les programmes d'activation de services puis démarre le -GNU@tie{}Shepherd, le système d'initialisation. - -@item --root=@var{root} -Monte @var{root} comme système de fichier racine. @var{root} peut être un -nom de périphérique comme @code{/dev/sda1}, une étiquette de système de -fichiers ou un UUID de système de fichiers. - -@item --system=@var{système} -S'assure que @file{/run/booted-system} et @file{/run/current-system} -pointent vers @var{system}. - -@item modprobe.blacklist=@var{modules}@dots{} -@cindex module, black-list -@cindex black-list, des modules du noyau -Dit au disque de RAM initial ainsi qu'à la commande @command{modprobe} (du -paquet kmod) de refuser de charger @var{modules}. @var{modules} doit être -une liste de noms de modules séparés par des virgules — p.@: ex.@: -@code{usbkbd,9pnet}. - -@item --repl -Démarre une boucle lecture-évaluation-affichage (REPL) depuis le disque de -RAM initial avant qu'il n'essaye de charger les modules du noyau et de -monter le système de fichiers racine. Notre équipe commerciale appelle cela -@dfn{boot-to-Guile}. Le Schemeur en vous va adorer. @xref{Using Guile -Interactively,,, guile, GNU Guile Reference Manual}, pour plus d'information -sur le REPL de Guile. - -@end table - -Maintenant que vous connaissez toutes les fonctionnalités des disques de RAM -initiaux produits par @code{base-initrd} et @code{raw-initrd}, voici comment -l'utiliser le personnalisé plus avant. - -@cindex initrd -@cindex disque de RAM initial -@deffn {Procédure Scheme} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ -[#:keyboard-layout #f] @ -[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] -Renvoie une dérivation qui construit un initrd. @var{file-systems} est une -liste de systèmes de fichiers à monter par l'initrd, éventuellement en plus -du système de fichier racine spécifié sur la ligne de commande du noyau via -@code{--root}. @var{linux-modules} est une liste de modules du noyau à -charger au démarrage. @var{mapped-devices} est une liste de correspondances -de périphériques à réaliser avant que les @var{file-systems} ne soient -montés (@pxref{Périphériques mappés}). @var{helper-packages} est une liste de -paquets à copier dans l'initrd. Elle peut inclure @code{e2fsck/static} ou -d'autres paquets requis par l'initrd pour vérifier le système de fichiers -racine. - -Lorsque la valeur est vraie, @var{keyboard-layout} est un enregistrement -@code{} dénotant la disposition du clavier désirée pour la -console. Cela est effectuée avant que les @var{mapped-devices} ne soient -créés et avant que les @var{file-systems} ne soient montés, de sorte que, si -l'utilisateur au besoin de saisir une phrase de passe ou d'utiliser le REPL, -cela arrive avec la disposition du clavier voulue. - -Lorsque @var{qemu-networking?} est vrai, paramètre le réseau avec les -paramètres QEMU standards. Lorsque @var{virtio?} est vrai, charge des -modules supplémentaires pour que l'initrd puisse être utilisé comme client -QEMU avec les pilotes I/O para-virtualisés. - -Lorsque @var{volatile-root?} est vrai, le système de fichier racine est -inscriptible mais tous les changements seront perdus. -@end deffn - -@deffn {Procédure Scheme} base-initrd @var{file-systems} @ - [#:mapped-devices '()] [#:keyboard-layout #f] @ -[#:qemu-networking? #f] [#:volatile-root? #f] @ -[#:linux-modules '()] -Renvoie un objet simili-fichier contenant un initrd générique, avec les -modules du noyau de @var{linux}. @var{file-systems} est une liste de -systèmes de fichiers à monter par l'initrd, éventuellement en plus du -système de fichiers racine spécifié sur la ligne de commande du noyau via -@code{--root}. @var{mapped-devices} est une liste de correspondances de -périphériques à réaliser avant de monter les @var{file-systems}. - -Lorsque la valeur est vraie, @var{keyboard-layout} est un enregistrement -@code{} dénotant la disposition du clavier désirée pour la -console. Cela est effectuée avant que les @var{mapped-devices} ne soient -créés et avant que les @var{file-systems} ne soient montés, de sorte que, si -l'utilisateur au besoin de saisir une phrase de passe ou d'utiliser le REPL, -cela arrive avec la disposition du clavier voulue. - -@var{qemu-networking?} et @var{volatile-root?} se comportent comme pour -@code{raw-initrd}. - -L'initrd est automatiquement remplie avec tous les modules du noyau requis -pour @var{file-systems} et pour les options données. On peut lister des -modules supplémentaires dans @var{linux-modules}. Ils seront ajoutés à -l'initrd et chargés au démarrage dans l'ordre dans lequel ils apparaissent. -@end deffn - -Inutile de le dire, les initrds que nous produisons et utilisons incluent -une version de Guile liée statiquement, et le programme d'initialisation est -un programme Guile. Cela donne beaucoup de flexibilité. La procédure -@code{expression->initrd} construit un tel initrd, étant donné le programme -à lancer dans cet initrd. - -@deffn {Procédure Scheme} expression->initrd @var{exp} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] -Renvoie un objet simili-fichier contenant un initrd Linux (une archive cpio -compressée avec gzip) contenant @var{guile} et qui évalue @var{exp}, une -G-expression, au démarrage. Toutes les dérivations référencées par -@var{exp} sont automatiquement copiées dans l'initrd. -@end deffn - -@node Configuration du chargeur d'amorçage -@section Configuration du chargeur d'amorçage - -@cindex bootloader -@cindex chargeur d'amorçage - -Le système d'exploitation supporte plusieurs chargeurs d'amorçage. La -configuration du chargeur d'amorçage se fait avec la déclaration -@code{bootloader-configuration}. Tous les champs de cette structure sont -indépendants du chargeur d'amorçage sauf un, @code{bootloader} qui indique -le chargeur d'amorçage à configurer et à installer. - -Certains chargeurs d'amorçage ne respectent pas tous les champs de -@code{bootloader-configuration}. Par exemple, le chargeur d'amorçage -extlinux ne supporte pas les thèmes et ignore donc le champ @code{theme}. - -@deftp {Type de données} bootloader-configuration -Le type d'une déclaration de configuration de chargeur d'amorçage. - -@table @asis - -@item @code{bootloader} -@cindex EFI, chargeur d'amorçage -@cindex UEFI, chargeur d'amorçage -@cindex BIOS, chargeur d'amorçage -Le chargeur d'amorçage à utiliser, comme objet @code{bootloader}. Pour -l'instant @code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} et @code{u-boot-bootloader} sont supportés. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} permet de démarrer sur un système moderne qui -utilise l'UEFI (@dfn{Unified Extensible Firmware Interface}). C'est ce que -vous devriez utiliser si l'image d'installation contient un répertoire -@file{/sys/firmware/efi} lorsque vous démarrez dessus sur votre machine. - -@vindex grub-bootloader -@code{grub-bootloader} vous permet de démarrer en particulier sur des -machines Intel en mode BIOS « legacy ». - -@cindex ARM, chargeurs d'amorçage -@cindex AArch64, chargeurs d'amorçage -Les chargeurs d'amorçage disponibles sont décrits dans les modules -@code{(gnu bootloader @dots{})}. En particulier, @code{(gnu bootloader -u-boot)} contient des définitions de chargeurs d'amorçage pour une large -gamme de systèmes ARM et AArch, à l'aide du -@uref{http://www.denx.de/wiki/U-Boot/, chargeur d'amorçage U-Boot} - -@item @code{target} -C'est une chaîne qui dénote la cible sur laquelle installer le chargeur -d'amorçage. - -L'interprétation dépend du chargeur d'amorçage en question. Pour -@code{grub-bootloader} par exemple, cela devrait être un nom de périphérique -compris par la commande @command{installer} du chargeur d'amorçage, comme -@code{/dev/sda} ou @code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU -GRUB Manual}). Pour @code{grub-efi-bootloader}, cela devrait être le point -de montage du système de fichiers EFI, typiquement @file{/boot/efi}. - -@item @code{menu-entries} (par défaut : @code{()}) -Une liste éventuellement vide d'objets @code{menu-entry} (voir plus bas), -dénotant les entrées qui doivent apparaître dans le menu du chargeur -d'amorçage, en plus de l'entrée pour le système actuel et l'entrée pointant -vers les générations précédentes. - -@item @code{default-entry} (par défaut : @code{0}) -L'index de l'entrée du menu de démarrage par défaut. L'index 0 correspond -au système actuel. - -@item @code{timeout} (par défaut : @code{5}) -Le nombre de secondes à attendre une entrée clavier avant de démarrer. -Indiquez 0 pour démarre immédiatement, et -1 pour attendre indéfiniment. - -@cindex disposition du clavier, pour le chargeur d'amorçage -@item @code{keyboard-layout} (par défaut : @code{#f}) -Si c'est @code{#f}, le menu du chargeur d'amorçage (s'il y en a un) utilise -la disposition du clavier par défaut, normalement pour l'anglais américain -(« qwerty »). - -Sinon, cela doit être un objet @code{keyboard-layout} (@pxref{Disposition du clavier}). - -@quotation Remarque -Cette option est actuellement ignorée par les chargeurs d'amorçage autre que -@code{grub} et @code{grub-efi}. -@end quotation - -@item @code{theme} (par défaut : @var{#f}) -L'objet de thème du chargeur d'amorçage décrivant le thème utilisé. Si -aucun thème n'est fournit, certains chargeurs d'amorçage peuvent utiliser un -thème par défaut, c'est le cas de GRUB. - -@item @code{terminal-outputs} (par défaut : @code{'gfxterm}) -Les terminaux de sortie utilisés par le menu de démarrage du chargeur -d'amorçage, en tant que liste de symboles. GRUB accepte les valeurs -@code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{gfxterm}, -@code{vga_text}, @code{mda_text}, @code{morse} et @code{pkmodem}. Ce champ -correspond à la variable GRUB @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple -configuration,,, grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (par défaut : @code{'()}) -Les terminaux d'entrée utilisés par le menu de démarrage du chargeur -d'amorçage, en tant que liste de symboles. Pour GRUB, la valeur par défaut -est le terminal natif de la plate-forme déterminé à l'exécution. GRUB -accepte les valeurs @code{console}, @code{serial}, @code{serial_@{0-3@}}, -@code{at_keyboard} et @code{usb_keyboard}. Ce champ correspond à la -variable GRUB @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, -grub,GNU GRUB manual}). - -@item @code{serial-unit} (par défaut : @code{#f}) -L'unitié série utilisée par le chargeur d'amorçage, en tant qu'entier entre -0 et 3. Pour GRUB, il est choisi à l'exécution ; actuellement GRUB choisi -0, ce qui correspond à COM1 (@pxref{Serial terminal,,, grub,GNU GRUB -manual}). - -@item @code{serial-speed} (par défaut : @code{#f}) -La vitesse de l'interface série, en tant qu'entier. Pour GRUB, la valeur -par défaut est choisie à l'exécution ; actuellement GRUB choisi -9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex dual boot -@cindex menu de démarrage -Si vous voulez lister des entrées du menu de démarrage supplémentaires via -le champ @code{menu-entries} ci-dessus, vous devrez les créer avec la forme -@code{menu-entry}. Par exemple, imaginons que vous souhaitiez pouvoir -démarrer sur une autre distro (c'est difficile à concevoir !), vous pourriez -alors définir une entrée du menu comme ceci : - -@example -(menu-entry - (label "L'autre distro") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Les détails suivent. - -@deftp {Type de données} menu-entry -Le type d'une entrée dans le menu du chargeur d'amorçage. - -@table @asis - -@item @code{label} -L'étiquette à montrer dans le menu — p.@: ex.@: @code{"GNU"}. - -@item @code{linux} -L'image du noyau Linux à démarrer, par exemple : - -@example -(file-append linux-libre "/bzImage") -@end example - -Pour GRUB, il est aussi possible de spécifier un périphérique explicitement -dans le chemin de fichier avec la convention de nommage de GRUB -(@pxref{Naming convention,,, grub, GNU GRUB manual}), par exemple : - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -Si le périphérique est spécifié explicitement comme au-dessus, le champ -@code{device} est complètement ignoré. - -@item @code{linux-arguments} (par défaut : @code{()}) -La liste des arguments de la ligne de commande du noyau supplémentaires — -p.@: ex.@: @code{("console=ttyS0")}. - -@item @code{initrd} -Une G-expression ou une chaîne dénotant le nom de fichier du disque de RAM -initial à utiliser (@pxref{G-Expressions}). -@item @code{device} (par défaut : @code{#f}) -Le périphérique où le noyau et l'initrd se trouvent — c.-à-d.@: pour GRUB, -l'option @dfn{root} de cette entrée de menu (@pxref{root,,, grub, GNU GRUB -manual}). - -Cela peut être une étiquette de système de fichiers (une chaîne), un UUID de -système de fichiers (un vecteur d'octets, @pxref{Systèmes de fichiers}) ou -@code{#f}, auquel cas le chargeur d'amorçage recherchera le périphérique -contenant le fichier spécifié par le champ @code{linux} (@pxref{search,,, -grub, GNU GRUB manual}). Cela ne doit @emph{pas} être un nom de -périphérique donné par l'OS comme @file{/dev/sda1}. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -For now only GRUB has theme support. GRUB themes are created using the -@code{grub-theme} form, which is not documented yet. - -@defvr {Variable Scheme} %default-theme -C'est le thème par défaut de GRUB utilisé par le système d'exploitation si -aucun champ @code{theme} n'est spécifié dans l'enregistrement -@code{bootloader-configuration}. - -Il contient une image de fond sympathique avec les logos de GNU et de Guix. -@end defvr - - -@node Invoquer guix system -@section Invoquer @code{guix system} - -Une fois que vous avez écrit une déclaration de système d'exploitation comme -nous l'avons vu dans les sections précédentes, elle peut être instanciée -avec la commande @command{guix system}. Voici le résumé de la commande : - -@example -guix system @var{options}@dots{} @var{action} @var{file} -@end example - -@var{file} doit être le nom d'un fichier contenant une déclaration -@code{operating-system}. @var{action} spécifie comme le système -d'exploitation est instancié. Actuellement les valeurs suivantes sont -supportées : - -@table @code -@item search -Affiche les définitions des types de services disponibles qui correspondent -aux expressions régulières données, triées par pertinence : - -@example -$ guix system search console font -name: console-fonts -location: gnu/services/base.scm:773:2 -extends: shepherd-root -description: Installe des polices données sur les ttys spécifiés (les polices sont par console virtuelle sous GNU/Linux). la valeur de ces service est une liste de paires -+ de tty/police comme ceci : -+ -+ '(("tty1" . "LatGrkCyr-8x16")) -relevance: 16 - -name: mingetty -location: gnu/services/base.scm:1144:2 -extends: shepherd-root -description: Fournit la connexion en console avec le programme `mingetty'. -relevance: 4 - -name: login -location: gnu/services/base.scm:819:2 -extends: pam -description: Fournit un service de connexion en console tel que spécifié par sa valeur de configuration, un objet `login-configuration'. -relevance: 4 - -@dots{} -@end example - -Comme pour @command{guix package --search}, le résultat est écrit au format -@code{recutils}, ce qui rend facile le filtrage de la sortie (@pxref{Top, -GNU recutils databases,, recutils, GNU recutils manual}). - -@item reconfigure -Construit le système d'exploitation décrit dans @var{file}, l'active et -passe dessus@footnote{Cette action (et les action liées que sont -@code{switch-generation} et @code{roll-back}) ne sont utilisables que sur -les systèmes sous Guix System.}. - -Cela met en application toute la configuration spécifiée dans @var{file} : -les comptes utilisateurs, les services du système, la liste globale des -paquets, les programmes setuid, etc. La commande démarre les services -systèmes spécifiés dans @var{file} qui ne sont pas actuellement lancés ; si -un service est actuellement exécuté cette commande s'arrange pour qu'il soit -mis à jour la prochaine fois qu'il est stoppé (p.@: ex@: par @code{herd stop -X} ou @code{herd restart X}). - -Cette commande crée une nouvelle génération dont le numéro est un de plus -que la génération actuelle (rapportée par @command{guix system -list-generations}). Si cette génération existe déjà, elle sera réécrite. -Ce comportement correspond à celui de @command{guix package} -(@pxref{Invoquer guix package}). - -Elle ajoute aussi une entrée de menu du chargeur d'amorçage pour la nouvelle -configuration, à moins que @option{--no-bootloader} ne soit passé. Pour -GRUB, elle déplace les entrées pour les anciennes configurations dans un -sous-menu, ce qui vous permet de choisir une ancienne génération au -démarrage si vous en avez besoin. - -@quotation Remarque -@c The paragraph below refers to the problem discussed at -@c . -Il est grandement recommandé de lancer @command{guix pull} une fois avant de -lancer @command{guix system reconfigure} pour la première fois -(@pxref{Invoquer guix pull}). Sans cela, vous verriez une version plus -ancienne de Guix une fois @command{reconfigure} terminé. -@end quotation - -@item switch-generation -@cindex générations -Passe à une génération existante du système. Cette action change -automatiquement le profil système vers la génération spécifiée. Elle -réarrange aussi les entrées existantes du menu du chargeur d'amorçage du -système. Elle fait de l'entrée du menu pour la génération spécifiée -l'entrée par défaut et déplace les entrées pour les autres générations dans -un sous-menu, si cela est supporté par le chargeur d'amorçage utilisé. Lors -du prochain démarrage du système, la génération du système spécifiée sera -utilisée. - -Le chargeur d'amorçage lui-même n'est pas réinstallé avec cette commande. -Ainsi, le chargeur d'amorçage est utilisé avec un fichier de configuration -plus à jour. - -La génération cible peut être spécifiée explicitement par son numéro de -génération. Par exemple, l'invocation suivante passerait à la génération 7 -du système : - -@example -guix system switch-generation 7 -@end example - -La génération cible peut aussi être spécifiée relativement à la génération -actuelle avec la forme @code{+N} ou @code{-N}, où @code{+3} signifie « trois -générations après la génération actuelle » et @code{-1} signifie « une -génération précédent la génération actuelle ». Lorsque vous spécifiez un -nombre négatif comme @code{-1}, il doit être précédé de @code{--} pour -éviter qu'il ne soit compris comme une option. Par exemple : - -@example -guix system switch-generation -- -1 -@end example - -Actuellement, l'effet de l'invocation de cette action est @emph{uniquement} -de passer au profil du système vers une autre génération existante et de -réarranger le menu du chargeur d'amorçage. Pour vraiment commencer à -utiliser la génération spécifiée, vous devez redémarrer après avoir lancé -cette action. Dans le futur, elle sera corrigée pour faire la même chose -que @command{reconfigure}, comme réactiver et désactiver les services. - -Cette action échouera si la génération spécifiée n'existe pas. - -@item roll-back -@cindex revenir en arrière -Passe à la génération précédente du système. Au prochain démarrage, la -génération précédente sera utilisée. C'est le contraire de -@command{reconfigure}, et c'est exactement comme invoquer -@command{switch-generation} avec pour argument @code{-1}. - -Actuellement, comme pour @command{switch-generation}, vous devez redémarrer -après avoir lancé cette action pour vraiment démarrer sur la génération -précédente du système. - -@item delete-generations -@cindex supprimer des générations du système -@cindex gagner de la place -Supprimer des générations du système, ce qui les rend disponibles pour le -ramasse-miettes (@pxref{Invoquer guix gc}, pour des informations sur la -manière de lancer le « ramasse-miettes »). - -Cela fonctionne comme pour @command{guix package --delete-generations} -(@pxref{Invoquer guix package, @code{--delete-generations}}). Avec aucun -argument, toutes les générations du système sauf la génération actuelle sont -supprimées : - -@example -guix system delete-generations -@end example - -Vous pouvez aussi choisir les générations que vous voulez supprimer. -L'exemple plus bas supprime toutes les génération du système plus vieilles -que deux mois : - -@example -guix system delete-generations 2m -@end example - -Lancer cette commande réinstalle automatiquement le chargeur d'amorçage avec -une liste à jour d'entrées de menu — p.@: ex.@: le sous-menu « anciennes -générations » dans GRUB ne liste plus les générations qui ont été -supprimées. - -@item build -Construit la dérivation du système d'exploitation, ce qui comprend tous les -fichiers de configuration et les programmes requis pour démarrer et lancer -le système. Cette action n'installe rien. - -@item init -Rempli le répertoire donné avec tous les fichiers nécessaires à lancer le -système d'exploitation spécifié dans @var{file}. C'est utile pour la -première installation de Guix System. Par exemple : - -@example -guix system init my-os-config.scm /mnt -@end example - -copie tous les éléments du dépôt requis par la configuration spécifiée dans -@file{my-os-config.scm} dans @file{/mnt}. Cela comprend les fichiers de -configuration, les paquets, etc. Elle crée aussi d'autres fichiers -essentiels requis pour que le système fonctionne correctement — p.@: ex.@: -les répertoires @file{/etc}, @file{/var} et @file{/run} et le fichier -@file{/bin/sh}. - -Cette commande installe aussi le chargeur d'amorçage sur la cible spécifiée -dans @file{my-os-config}, à moins que l'option @option{--no-bootloader} ne -soit passée. - -@item vm -@cindex machine virtuelle -@cindex VM -@anchor{guix system vm} -Construit une machine virtuelle qui contient le système d'exploitation -déclaré dans @var{file} et renvoie un script pour lancer cette machine -virtuelle (VM). - -@quotation Remarque -Les actions @code{vm} et les autres plus bas peuvent utiliser la prise en -charge KVM du noyau Linux-libre. Plus spécifiquement, si la machine prend -en charge la virtualisation matérielle, le module noyau KVM correspondant -devrait être chargé, et le nœud de périphérique @file{/dev/kvm} devrait -exister et être lisible et inscriptible pour l'utilisateur et pour les -utilisateurs de construction du démon (@pxref{Réglages de l'environnement de construction}). -@end quotation - -Les arguments passés au script sont passés à QEMU comme dans l'exemple -ci-dessous, qui active le réseau et demande 1@tie{}Go de RAM pour la machine -émulée : - -@example -$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user -@end example - -La VM partage sont dépôt avec le système hôte. - -Vous pouvez partager des fichiers supplémentaires entre l'hôte et la VM avec -les options en ligne de commande @code{--share} et @code{--expose} : la -première spécifie un répertoire à partager avec accès en écriture, tandis -que le deuxième fournit un accès en lecture-seule au répertoire partagé. - -L'exemple ci-dessous crée une VM dans laquelle le répertoire personnel de -l'utilisateur est accessible en lecture-seule, et où le répertoire -@file{/exchange} est une correspondance en lecture-écriture à -@file{$HOME/tmp} sur l'hôte : - -@example -guix system vm my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -Sur GNU/Linux, le comportement par défaut consiste à démarrer directement -sur le noyau ; cela a l'avantage de n'avoir besoin que d'une toute petite -image disque puisque le dépôt de l'hôte peut ensuite être monté. - -L'option @code{--full-boot} force une séquence de démarrage complète, en -commençant par le chargeur d'amorçage. Cela requiert plus d'espace disque -puisqu'une image racine contenant au moins le noyau, l'initrd et les -fichiers de données du chargeur d'amorçage doit être créé. On peut utiliser -l'option @code{--image-size} pour spécifier la taille de l'image. - -@cindex Images système, création en divers formats -@cindex Créer des images systèmes sous différents formats -@item vm-image -@itemx disk-image -@itemx docker-image -Renvoie une machine virtuelle, une image disque ou une image Docker du -système d'exploitation déclaré dans @var{file} qui se suffit à elle-même. -Par défaut, @command{guix system} estime la taille de l'image requise pour -stocker le système, mais vous pouvez utiliser l'option @option{--image-size} -pour spécifier une valeur. Les images Docker sont construites pour contenir -exactement ce dont elles ont besoin, donc l'option @option{--image-size} est -ignorée dans le cas de @code{docker-image}. - -Vous pouvez spécifier le type de système de fichiers racine avec l'option -@option{--file-system-type}. La valeur par défaut est @code{ext4}. - -Lorsque vous utilisez @code{vm-image}, l'image renvoyée est au format qcow2, -que l'émulateur QEMU peut utiliser efficacement. @xref{Lancer Guix dans une VM}, pour plus d'informations sur la manière de lancer l'image dans une -machine virtuelle. - -Lorsque vous utilisez @code{disk-image}, une image disque brute est produite -; elle peut être copiée telle quelle sur un périphérique USB. En supposant -que @code{/dev/sdc} est le périphérique correspondant à une clef USB, on -peut copier l'image dessus avec la commande suivante : - -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example - -En utilisant @code{docker-image}, on produit une image Docker. Guix -construit l'image de zéro, et non à partir d'une image Docker de base -pré-existante. En conséquence, elle contient @emph{exactly} ce que vous -avez défini dans le fichier de configuration du système. Vous pouvez -ensuite charger l'image et lancer un conteneur Docker avec des commande -comme : - -@example -image_id="$(docker load < guix-system-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 - -Cette commande démarre un nouveau conteneur Docker à partir de l'image -spécifiée. Il démarrera le système Guix de la manière habituelle, ce qui -signifie qu'il démarrera tous les services que vous avez définis dans la -configuration du système d'exploitation. En fonction de ce que vous lancez -dans le conteneur Docker, il peut être nécessaire de donner des permissions -supplémentaires au conteneur. Par exemple, si vous voulez construire des -paquets avec Guix dans le conteneur Docker, vous devriez passer -@option{--privileged} à @code{docker run}. - -@item conteneur -Renvoie un script qui lance le système d'exploitation déclaré dans -@var{file} dans un conteneur. Les conteneurs sont un ensemble de mécanismes -d'isolation légers fournis par le noyau Linux-libre. Les conteneurs sont -substantiellement moins gourmands en ressources que les machines virtuelles -complètes car le noyau, les objets partagés et d'autres ressources peuvent -être partagés avec le système hôte ; cela signifie aussi une isolation moins -complète. - -Actuellement, le script doit être lancé en root pour pouvoir supporter plus -d'un utilisateur et d'un groupe. Le conteneur partage son dépôt avec le -système hôte. - -Comme avec l'action @code{vm} (@pxref{guix system vm}), des systèmes de -fichiers supplémentaires peuvent être partagés entre l'hôte et le conteneur -avec les options @option{--share} et @option{--expose} : - -@example -guix system container my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -@quotation Remarque -Cette option requiert Linux-libre ou supérieur. -@end quotation - -@end table - -@var{options} peut contenir n'importe quelle option commune de construction -(@pxref{Options de construction communes}). En plus, @var{options} peut contenir l'une -de ces options : - -@table @option -@item --expression=@var{expr} -@itemx -e @var{expr} -Considère le système d'exploitation en lequel s'évalue @var{expr}. C'est -une alternative à la spécification d'un fichier qui s'évalue en un système -d'exploitation. C'est utilisé pour générer l'installateur du système Guix -(@pxref{Construire l'image d'installation}). - -@item --system=@var{système} -@itemx -s @var{système} -Essaye de construire pour @var{system} au lieu du type du système hôte. -Cela fonction comme pour @command{guix build} (@pxref{Invoquer guix build}). - -@item --derivation -@itemx -d -Renvoie le nom du fichier de dérivation du système d'exploitation donné sans -rien construire. - -@item --file-system-type=@var{type} -@itemx -t @var{type} -Pour l'action @code{disk-image}, crée un système de fichier du @var{type} -donné sur l'image. - -Lorsque cette option est omise, @command{guix system} utilise @code{ext4}. - -@cindex format ISO-9660 -@cindex format d'image de CD -@cindex format d'image de DVD -@code{--file-system-type=iso9660} produit une image ISO-9660, qu'il est -possible de graver sur un CD ou un DVD. - -@item --image-size=@var{size} -Pour les actions @code{vm-image} et @code{disk-image}, crée une image de la -taille donnée @var{size}. @var{size} peut être un nombre d'octets ou -contenir un suffixe d'unité (@pxref{Block size, size specifications,, -coreutils, GNU Coreutils}). - -Lorsque cette option est omise, @command{guix system} calcule une estimation -de la taille de l'image en fonction de la taille du système déclaré dans -@var{file}. - -@item --root=@var{fichier} -@itemx -r @var{fichier} -Fait de @var{fichier} un lien symbolique vers le résultat, et l'enregistre -en tant que racine du ramasse-miettes. - -@item --skip-checks -Passe les vérifications de sécurité avant l'installation. - -Par défaut, @command{guix system init} et @command{guix system reconfigure} -effectuent des vérifications de sécurité : ils s'assurent que les systèmes -de fichiers qui apparaissent dans la déclaration @code{operating-system} -existent vraiment (@pxref{Systèmes de fichiers}) et que les modules de noyau Linux -qui peuvent être requis au démarrage sont listés dans @code{initrd-modules} -(@pxref{Disque de RAM initial}). Passer cette option saute ces vérifications -complètement. - -@cindex on-error -@cindex stratégie on-error -@cindex stratégie en cas d'erreur -@item --on-error=@var{strategy} -Applique @var{strategy} lorsqu'une erreur arrive lors de la lecture de -@var{file}. @var{strategy} peut être l'une des valeurs suivantes : - -@table @code -@item nothing-special -Rapporte l'erreur de manière concise et quitte. C'est la stratégie par -défaut. - -@item backtrace -Pareil, mais affiche aussi une trace de débogage. - -@item debug -Rapporte l'erreur et entre dans le débogueur Guile. À partir de là, vous -pouvez lancer des commandes comme @code{,bt} pour obtenir une trace de -débogage, @code{,locals} pour afficher les valeurs des variables locales et -plus généralement inspecter l'état du programme. @xref{Debug Commands,,, -guile, GNU Guile Reference Manual}, pour une liste de commandes de débogage -disponibles. -@end table -@end table - -Une fois que vous avez construit, re-configuré et re-re-configuré votre -installation Guix, vous pourriez trouver utile de lister les générations du -système disponibles sur le disque — et que vous pouvez choisir dans le menu -du chargeur d'amorçage : - -@table @code - -@item list-generations -Affiche un résumé de chaque génération du système d'exploitation disponible -sur le disque, dans un format lisible pour un humain. C'est similaire à -l'option @option{--list-generations} de @command{guix package} -(@pxref{Invoquer guix package}). - -Éventuellement, on peut spécifier un motif, avec la même syntaxe utilisée -pour @command{guix package --list-generations}, pour restreindre la liste -des générations affichées. Par exemple, la commande suivante affiche les -générations de moins de 10 jours : - -@example -$ guix system list-generations 10d -@end example - -@end table - -La commande @command{guix system} a même plus à proposer ! Les -sous-commandes suivantes vous permettent de visualiser comme vos services -systèmes sont liés les uns aux autres : - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Affiche le @dfn{graphe d'extension des services} du système d'exploitation -défini dans @var{file} au format Dot/Graphviz sur la sortie standard -(@pxref{Composition de services}, pour plus d'informations sur l'extension des -services). - -La commande : - -@example -$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf -@end example - -produit un fichier PDF montrant les relations d'extension entre les -services. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Affiche le @dfn{graphe de dépendance} des services shepherd du système -d'exploitation défini dans @var{file} au format Dot/Graphviz sur la sortie -standard. @xref{Services Shepherd}, pour plus d'informations et un exemple -de graphe. - -@end table - -@node Lancer Guix dans une VM -@section Exécuter Guix sur une machine virtuelle - -@cindex machine virtuelle -Pour exécuter GuixSD sur une machine virtuelle (VM), on peut soit utiliser -l'image de VM GuixSD pré-construite sur -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{système}.xz} -ou construire sa propre image de machine virtuelle avec @command{guix system -vm-image} (@pxref{Invoquer guix system}). L'image renvoyée est au format -qcow2, que l'@uref{http://qemu.org/,émulateur QEMU} peut utiliser -efficacement. - -@cindex QEMU -Si vous construisez votre propre image, vous devez la copier en dehors du -dépôt (@pxref{Le dépôt}) et vous donner la permission d'écrire sur la copie -avant de pouvoir l'utiliser. Lorsque vous invoquez QEMU, vous devez choisir -un émulateur système correspondant à votre plate-forme matérielle. Voici -une invocation minimale de QEMU qui démarrera le résultat de @command{guix -system vm-image} sur un matériel x8_64 : - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image -@end example - -Voici la signification de ces options : - -@table @code -@item qemu-system-x86_64 -Cela spécifie la plate-forme matérielle à émuler. Elle doit correspondre à -l'hôte. - -@item -net user -Active la pile réseau non privilégiée en mode utilisateur. L'OS émulé peut -accéder à l'hôte mais pas l'inverse. C'est la manière la plus simple de -connecter le client. - -@item -net nic,model=virtio -Vous devez créer une interface réseau d'un modèle donné. Si vous ne créez -pas de NIC, le démarrage échouera. En supposant que votre plate-forme est -x86_64, vous pouvez récupérer une liste des modèles de NIC disponibles en -lançant @command{qemu-system-x86_64 -net nic,model=help}. - -@item -enable-kvm -Si votre système a des extensions de virtualisation matérielle, activer le -support des machines virtuelles de Linux (KVM) accélérera les choses. - -@item -m 256 -RAM disponible sur l'OS émulé, en mébioctets. La valeur par défaut est -128@tie{}Mo, ce qui peut ne pas suffire pour certaines opérations. - -@item /tmp/qemu-image -Le nom de fichier de l'image qcow2. -@end table - -Le script @command{run-vm.sh} par défaut renvoyé par une invocation de -@command{guix system vm} n'ajoute pas le drapeau @command{-net user} par -défaut. Pour avoir accès au réseau dans la vm, ajoutez le -@code{(dhcp-client-service)} à votre définition et démarrez la VM avec -@command{`guix system vm config.scm` -net user}. Un problème important avec -@command{-net user} pour le réseau, est que @command{ping} ne fonctionnera -pas, car il utilise le protocole ICMP. Vous devrez utiliser une autre -commande pour vérifier la connectivité réseau, par exemple @command{guix -download}. - -@subsection Se connecter par SSH - -@cindex SSH -@cindex serveur SSH -Pour activer SSH dans une VM vous devez ajouter un serveur SSH comme -@code{(dropbear-service)} ou @code{(lsh-service)} à votre VM. Le service -@code{(lsh-service)} ne peut actuellement pas démarrer sans supervision. Il -a besoin que vous tapiez quelques caractères pour initialiser le générateur -d'aléatoire. En plus vous devez transférer le port 22, par défaut, à -l'hôte. Vous pouvez faire cela avec - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -Pour vous connecter à la VM vous pouvez lancer - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -Le @command{-p} donne le port auquel vous voulez vous connecter à -@command{ssh}, @command{-o UserKnownHostsFile=/dev/null} évite que -@command{ssh} ne se plaigne à chaque fois que vous modifiez le fichier -@command{config.scm} et @command{-o StrictHostKeyChecking=no} évite que vous -n'ayez à autoriser une connexion à un hôte inconnu à chaque fois que vous -vous connectez. - -@subsection Utiliser @command{virt-viewer} avec Spice - -Alternativement au client graphique @command{qemu} par défaut vous pouvez -utiliser @command{remote-viewer} du paquet @command{virt-viewer}. Pour vous -connecter, passez le drapeau @command{-spice port=5930,disable-ticketing} à -@command{qemu}. Voir les sections précédentes pour plus d'informations sur -comment faire cela. - -Spice a aussi de chouettes fonctionnalités comme le partage de votre -presse-papier avec la VM. Pour activer cela vous devrez aussi passer les -drapeaux suivants à @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 - -Vous devrez aussi ajouter le @pxref{Services divers, Spice service}. - -@node Définir des services -@section Définir des services - -Les sections précédentes montrent les services disponibles et comment on -peut les combiner dans une déclaration @code{operating-system}. Mais, déjà, -comment les définir ? Et qu'est-ce qu'un service au fait ? - -@menu -* Composition de services:: Le modèle de composition des services. -* Types service et services:: Types et services. -* Référence de service:: Référence de l'API@. -* Services Shepherd:: Un type de service particulier. -@end menu - -@node Composition de services -@subsection Composition de services - -@cindex services -@cindex démons -Ici nous définissons un @dfn{service} comme étant, assez largement, quelque -chose qui étend la fonctionnalité d'un système d'exploitation. Souvent un -service est un processus — un @dfn{démon} — démarré lorsque le système -démarre : un serveur ssh, un serveur web, le démon de construction de Guix, -etc. Parfois un service est un démon dont l'exécution peut être déclenchée -par un autre démon — p.@: ex.@: un serveur FTP démarré par @command{inetd} -ou un service D-Bus activé par @command{dbus-daemon}. Parfois, un service -ne correspond pas à un démon. Par exemple, le service « de comptes » -récupère la liste des comptes utilisateurs et s'assure qu'ils existent bien -lorsque le système est lancé ; le service « udev » récupère les règles de -gestion des périphériques et les rend disponible au démon eudev ; le service -@file{/etc} rempli le répertoire @file{/etc} du système. - -@cindex extensions de service -Les services de Guix sont connectés par des @dfn{extensions}. Par exemple, -le service ssh @dfn{étend} le Shepherd — le système d'initialisation de -GuixSD, qui tourne en tant que PID@tie{}1 — en lui donnant les lignes de -commande pour démarrer et arrêter le démon ssh (@pxref{Services réseau, -@code{lsh-service}}) ; le service UPower étend le service D-Bus en lui -passant sa spécification @file{.service} et étend le service udev en lui -passant des règles de gestion de périphériques (@pxref{Services de bureaux, -@code{upower-service}}) ; le démon Guix étend le Shepherd en lui passant les -lignes de commande pour démarrer et arrêter le démon et étend le service de -comptes en lui passant une liste des comptes utilisateurs de constructions -requis (@pxref{Services de base}). - -En définitive, les services et leurs relation « d'extensions » forment un -graphe orienté acyclique (DAG). Si nous représentons les services comme des -boîtes et les extensions comme des flèches, un système typique pourrait -fournir quelque chose comme cela : - -@image{images/service-graph,,5in,Graphe d'extension des services typique.} - -@cindex service système -En bas, on voit le @dfn{service système} qui produit le répertoire contenant -tout et lançant et démarrant le système, renvoyé par la commande -@command{guix system build}. @xref{Référence de service}, pour apprendre les -autres types de services montrés ici. @xref{system-extension-graph, the -@command{guix system extension-graph} command}, pour plus d'informations sur -la manière de générer cette représentation pour une définition de système -d'exploitation particulière. - -@cindex types de services -Techniquement, les développeurs peuvent définir des @dfn{types de services} -pour exprimer ces relations. Il peut y avoir n'importe quel quantité de -services d'un type donné sur le système — par exemple, un système sur lequel -tournent deux instances du serveur ssh de GNU (lsh) a deux instance de -@var{lsh-service-type}, avec des paramètres différents. - -La section suivante décrit l'interface de programmation des types de -services et des services. - -@node Types service et services -@subsection Types service et services - -Un @dfn{type de service} est un nœud dans le DAG décrit plus haut. -Commençons avec un exemple simple, le type de service pour le démon de -construction de Guix (@pxref{Invoquer 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 -Il définit trois choses : - -@enumerate -@item -Un nom, dont le seul but de rendre l'inspection et le débogage plus faciles. - -@item -Une liste d'@dfn{extensions de services}, où chaque extension désigne le -type de service cible et une procédure qui, étant donné les paramètres du -service, renvoie une liste d'objets pour étendre le service de ce type. - -Chaque type de service a au moins une extension de service. La seule -exception est le @dfn{type de service boot}, qui est le service ultime. - -@item -Éventuellement, une valeur par défaut pour les instances de ce type. -@end enumerate - -In this example, @code{guix-service-type} extends three services: - -@table @code -@item shepherd-root-service-type -The @code{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Services Shepherd}). - -@item account-service-type -This extension for this service is computed by @code{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Invoquer guix-daemon}). - -@item activation-service-type -Here @code{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 - -Un service de ce type est instancié de cette manière : - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -Le deuxième argument de la forme @code{service} est une valeur représentant -les paramètres de cet instance spécifique du service. -@xref{guix-configuration-type, @code{guix-configuration}}, pour plus -d'informations sur le type de données @code{guix-configuration}. Lorsque la -valeur est omise, la valeur par défaut spécifiée par -@code{guix-service-type} est utilisée : - -@example -(service guix-service-type) -@end example - -@code{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -Le type de service pour un service @emph{extensible} ressemble à ceci : - -@example -(define udev-service-type - (service-type (name 'udev) - (extensions - (list (service-extension shepherd-root-service-type - udev-shepherd-service))) - - (compose concatenate) ; concatène la liste des règles - (extend (lambda (config rules) - (match config - (($ udev initial-rules) - (udev-configuration - (udev udev) ; le paquet udev à utiliser - (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 -@code{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -C'est la procédure pour @dfn{composer} la liste des extensions de services -de ce type. - -Les services peuvent étendre le service udev en lui passant des listes de -règles ; on compose ces extensions simplement en les concaténant. - -@item extend -Cette procédure définie comme la valeur du service est @dfn{étendue} avec la -composition des extensions. - -Les extensions Udev sont composés en une liste de règles, mais la valeur du -service udev est elle-même un enregistrement @code{}. -Donc ici, nous étendons cet enregistrement en ajoutant la liste des règle -contribuées à la liste des règles qu'il contient déjà. - -@item description -C'est une chaîne donnant un aperçu du type de service. Elle peut contenir -du balisage Texinfo (@pxref{Overview,,, texinfo, GNU Texinfo}). La commande -@command{guix system search} permet de rechercher dans ces chaînes et de les -afficher (@pxref{Invoquer guix system}). -@end table - -There can be only one instance of an extensible service type such as -@code{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -Toujours ici ? La section suivante fournit une référence de l'interface de -programmation des services. - -@node Référence de service -@subsection Référence de service - -Nous avons vu un résumé des types de services (@pxref{Types service et services}). Cette section fournit une référence sur la manière de manipuler -les services et les types de services. Cette interface est fournie par le -module @code{(gnu services)}. - -@deffn {Procédure Scheme} service @var{type} [@var{value}] -Renvoie un nouveau service de type @var{type}, un objet -@code{} (voir plus bas). @var{value}peut être n'importe quel -objet ; il représente les paramètres de cette instance particulière du -service. - -Lorsque @var{value} est omise, la valeur par défaut spécifiée par @var{type} -est utilisée ; si @var{type} ne spécifie pas de valeur par défaut, une -erreur est levée. - -Par exemple ceci : - -@example -(service openssh-service-type) -@end example - -@noindent -est équivalent à ceci : - -@example -(service openssh-service-type - (openssh-configuration)) -@end example - -Dans les deux cas le résultat est une instance de -@code{openssh-service-type} avec la configuration par défaut. -@end deffn - -@deffn {Procédure Scheme} service? @var{obj} -Renvoie vrai si @var{obj} est un service. -@end deffn - -@deffn {Procédure Scheme} service-kind @var{service} -Renvoie le type de @var{service} — c.-à-d.@: un objet @code{}. -@end deffn - -@deffn {Procédure Scheme} service-value @var{service} -Renvoie la valeur associée à @var{service}. Elle représente ses paramètres. -@end deffn - -Voici un exemple de la manière dont un service est créé et manipulé : - -@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 @code{%base-services} -(@pxref{Services de base, @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 {Syntaxe Scheme} modify-services @var{services} @ - (@var{type} @var{variable} => @var{body}) @dots{} - -Modifie les services listés dans @var{services} en fonction des clauses -données. Chaque clause à la forme : - -@example -(@var{type} @var{variable} => @var{body}) -@end example - -où @var{type} est un type de service — p.@: ex.@: @code{guix-service-type} — -et @var{variable} est un identifiant lié dans @var{body} aux paramètres du -service — p.@: ex.@: une instance de @code{guix-configuration} — du service -original de ce @var{type}. - -La variable @var{body} devrait s'évaluer en de nouveaux paramètres de -service, qui seront utilisés pour configurer le nouveau service. Ce nouveau -service remplacera l'original dans la liste qui en résulte. Comme les -paramètres d'un service sont créés avec @code{define-record-type*}, vous -pouvez écrire un @var{body} court qui s'évalue en de nouveaux paramètres -pour le services en utilisant @code{inherit}, fourni par -@code{define-record-type*}. - -@xref{Utiliser le système de configuration} pour des exemples d'utilisation. - -@end deffn - -Suit l'interface de programmation des types de services. Vous devrez la -connaître pour écrire de nouvelles définitions de services, mais pas -forcément lorsque vous cherchez des manières simples de personnaliser votre -déclaration @code{operating-system}. - -@deftp {Type de données} service-type -@cindex type de service -C'est la représentation d'un @dfn{type de service} (@pxref{Types service et services}). - -@table @asis -@item @code{name} -C'est un symbole, utilisé seulement pour simplifier l'inspection et le -débogage. - -@item @code{extensions} -Une liste non-vide d'objets @code{} (voir plus bas). - -@item @code{compose} (par défaut : @code{#f}) -S'il s'agit de @code{#f}, le type de service dénote des services qui ne -peuvent pas être étendus — c.-à-d.@: qui ne reçoivent pas de « valeurs » -d'autres services. - -Sinon, ce doit être une procédure à un argument. La procédure est appelée -par @code{fold-services} et on lui passe une liste de valeurs collectées par -les extensions. Elle peut renvoyer n'importe quelle valeur simple. - -@item @code{extend} (par défaut : @code{#f}) -Si la valeur est @code{#f}, les services de ce type ne peuvent pas être -étendus. - -Sinon, il doit s'agir 'une procédure à deux arguments : @code{fold-services} -l'appelle et lui passe la valeur initiale du service comme premier argument -et le résultat de l'application de @code{compose} sur les valeurs -d'extension en second argument. Elle doit renvoyer une valeur qui est une -valeur de paramètre valide pour l'instance du service. -@end table - -@xref{Types service et services}, pour des exemples. -@end deftp - -@deffn {Procédure Scheme} service-extension @var{target-type} @ - @var{compute} -Renvoie une nouvelle extension pour les services de type @var{target-type}. -@var{compute} doit être une procédure à un argument : @code{fold-services} -l'appelle et lui passe la valeur associée au service qui fournit cette -extension ; elle doit renvoyer une valeur valide pour le service cible. -@end deffn - -@deffn {Procédure Scheme} service-extension? @var{obj} -Renvoie vrai si @var{obj} est une extension de service. -@end deffn - -Parfois, vous voudrez simplement étendre un service existant. Cela implique -de créer un nouveau type de service et de spécifier l'extension qui vous -intéresse, ce qui peut être assez verbeux ; la procédure -@code{simple-service} fournit un raccourci pour ce cas. - -@deffn {Procédure Scheme} simple-service @var{name} @var{target} @var{value} -Renvoie un service qui étend @var{target} avec @var{value}. Cela fonctionne -en créant un type de service singleton @var{name}, dont le service renvoyé -est une instance. - -Par exemple, cela étend mcron (@pxref{Exécution de tâches planifiées}) avec une -tâche supplémentaire : - -@example -(simple-service 'my-mcron-job mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -Au cœur de l'abstraction des services se cache la procédure -@code{fold-services}, responsable de la « compilation » d'une liste de -services en un répertoire unique qui contient tout ce qui est nécessaire au -démarrage et à l'exécution du système — le répertoire indiqué par la -commande @command{guix system build} (@pxref{Invoquer guix system}). En -soit, elle propage les extensions des services le long du graphe des -services, en mettant à jour chaque paramètre des nœuds sur son chemin, -jusqu'à atteindre le nœud racine. - -@deffn {Procédure Scheme} fold-services @var{services} @ - [#:target-type @var{system-service-type}] -Replie @var{services} en propageant leurs extensions jusqu'à la racine de -type @var{target-type} ; renvoie le service racine ajusté de cette manière. -@end deffn - -Enfin, le module @code{(gnu services)} définie aussi divers types de -services essentiels, dont certains sont listés ci-dessous. - -@defvr {Variable Scheme} system-service-type -C'est la racine du graphe des services. Il produit le répertoire du système -renvoyé par la commande @command{guix system build}. -@end defvr - -@defvr {Variable Scheme} boot-service-type -Le type du service « boot », qui produit le @dfn{script de démarrage}. Le -script de démarrage est ce que le disque de RAM initial lance au démarrage. -@end defvr - -@defvr {Variable Scheme} etc-service-type -Le type du service @file{/etc}. Ce service est utilisé pour créer des -fichiers dans @file{/etc} et peut être étendu en lui passant des tuples -nom/fichier comme ceci : - -@example -(list `("issue" ,(plain-file "issue" "Bienvenue !\n"))) -@end example - -Dans cet exemple, l'effet serait d'ajouter un fichier @file{/etc/issue} -pointant vers le fichier donné. -@end defvr - -@defvr {Variable Scheme} setuid-program-service-type -Le type du « service setuid ». Ce service récupère des listes de noms de -fichiers exécutables, passés en tant que gexps, et les ajoute à l'ensemble -des programmes setuid root sur le système (@pxref{Programmes setuid}). -@end defvr - -@defvr {Variable Scheme} profile-service-type -De type du service qui rempli le @dfn{profil du système} — c.-à-d.@: les -programmes dans @file{/run/current-system/profile}. Les autres services -peuvent l'étendre en lui passant des listes de paquets à ajouter au profil -du système. -@end defvr - - -@node Services Shepherd -@subsection Services Shepherd - -@cindex services shepherd -@cindex PID 1 -@cindex système d'init -Le module @code{(gnu services shepherd)} fournit une manière de définir les -services gérés par le GNU@tie{}Shepherd, qui est le système d'initialisation -— le premier processus démarré lorsque le système démarre, aussi connu comme -étant le PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU Shepherd -Manual}). - -Les services dans le Shepherd peuvent dépendre les uns des autres. Par -exemple, le démon SSH peut avoir besoin d'être démarré après le démon -syslog, qui à son tour doit être démarré après le montage des systèmes de -fichiers. Le système d'exploitation simple déclaré précédemment -(@pxref{Utiliser le système de configuration}) crée un graphe de service comme -ceci : - -@image{images/shepherd-graph,,5in,Graphe de service typique du shepherd.} - -Vous pouvez générer un tel graphe pour n'importe quelle définition de -système d'exploitation avec la commande @command{guix system shepherd-graph} -(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @code{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by -passing it lists of @code{} objects. - -@deftp {Type de données} shepherd-service -Le type de données représentant un service géré par le Shepherd. - -@table @asis -@item @code{provision} -C'est une liste de symboles dénotant ce que le service fournit. - -Ce sont les noms qui peuvent être passés à @command{herd start}, -@command{herd status} et les commandes similaires (@pxref{Invoking herd,,, -shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the -@code{provides} slot,, shepherd, The GNU Shepherd Manual}, pour plus de -détails. - -@item @code{requirements} (par défaut : @code{'()}) -Liste de symboles dénotant les services du Shepherd dont celui-ci dépend. - -@item @code{respawn?} (par défaut : @code{#t}) -Indique s'il faut redémarrer le service lorsqu'il s'arrête, par exemple si -le processus sous-jacent meurt. - -@item @code{start} -@itemx @code{stop} (par défaut : @code{#~(const #f)}) -Les champs @code{start} et @code{stop} se réfèrent à la capacité du Shepherd -de démarrer et d'arrêter des processus (@pxref{Service De- and -Constructors,,, shepherd, The GNU Shepherd Manual}). Ils sont donnés comme -des G-expressions qui sont étendues dans le fichier de configuration du -Shepherd (@pxref{G-Expressions}). - -@item @code{actions} (par défaut : @code{'()}) -@cindex action, des services Shepherd -C'est une liste d'objets @code{shepherd-action} (voir plus bas) définissant -des @dfn{actions} supportées par le service, en plus des actions -@code{start} et @code{stop} standards. Les actions listées ici sont -disponibles en tant que sous-commande de @command{herd} : - -@example -herd @var{action} @var{service} [@var{arguments}@dots{}] -@end example - -@item @code{documentation} -Une chaîne de documentation, montrée lorsqu'on lance : - -@example -herd doc @var{service-name} -@end example - -where @var{service-name} is one of the symbols in @code{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @code{%default-modules}) -C'est la liste des modules qui doivent être dans le contexte lorsque -@code{start} et @code{stop} sont évalués. - -@end table -@end deftp - -@deftp {Type de données} shepherd-action -C'est le type de données qui définie des actions supplémentaires -implémentées par un service Shepherd (voir au-dessus). - -@table @code -@item name -Symbole nommant l'action. - -@item documentation -C'est une chaîne de documentation pour l'action. Elle peut être consultée -avec : - -@example -herd doc @var{service} action @var{action} -@end example - -@item procedure -Cela devrait être une gexp qui s'évalue en une procédure à au moins un -argument, la « valeur de lancement » du service (@pxref{Slots of services,,, -shepherd, The GNU Shepherd Manual}). -@end table - -L'exemple suivant définie une action nommée @code{dire-bonjour} qui salue -amicalement l'utilisateur : - -@example -(shepherd-action - (name 'dire-bonjour) - (documentation "Dit salut !") - (procedure #~(lambda (running . args) - (format #t "Salut, l'ami ! arguments : ~s\n" - args) - #t))) -@end example - -En supposant que cette action est ajoutée dans le service @code{example}, -vous pouvez écrire : - -@example -# herd dire-bonjour example -Salut, l'ami ! arguments : () -# herd dire-bonjour example a b c -Salut, l'ami ! arguments : ("a" "b" "c") -@end example - -Comme vous pouvez le voir, c'est une manière assez sophistiquée de dire -bonjour. @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, -pour plus d'informations sur les actions. -@end deftp - -@defvr {Variable Scheme} shepherd-root-service-type -Le type de service pour le « service racine » du Shepherd — c.-à-d.@: le -PID@tie{}1. - -C'est le type de service que les extensions ciblent lorqu'elles veulent -créer un service shepherd (@pxref{Types service et services}, pour un -exemple). Chaque extension doit passer une liste de -@code{}. -@end defvr - -@defvr {Variable Scheme} %shepherd-root-service -Ce service représente le PID@tie{}1. -@end defvr - - -@node Documentation -@chapter Documentation - -@cindex documentation, recherche -@cindex chercher de la documentation -@cindex Info, format de documentation -@cindex man, pages de manuel -@cindex pages de manuel -Dans la plupart des cas les paquets installés avec Guix ont une -documentation. Il y a deux formats de documentation principaux : « Info », -un format hypertexte navigable utilisé par les logiciels GNU et les « pages -de manuel » (ou « pages de man »), le format de documentation linéaire -traditionnel chez Unix. Les manuels Info sont disponibles via la commande -@command{info} ou avec Emacs, et les pages de man sont accessibles via la -commande @command{man}. - -Vous pouvez chercher de la documentation pour les logiciels installés sur -votre système par mot-clef. Par exemple, la commande suivante recherche des -informations sur « TLS » dans les manuels Info : - -@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 -La commande suivante recherche le même mot-clef dans les pages de man : - -@example -$ man -k TLS -SSL (7) - OpenSSL SSL/TLS library -certtool (1) - GnuTLS certificate tool -@dots {} -@end example - -Ces recherches sont purement locales à votre ordinateur donc vous savez que -la documentation trouvée correspond à ce qui est effectivement installé, -vous pouvez y accéder hors ligne et votre vie privée est préservée. - -Une fois que vous avez ces résultats, vous pouvez visualiser la -documentation appropriée avec, disons : - -@example -$ info "(gnutls)Core TLS API" -@end example - -@noindent -ou : - -@example -$ man certtool -@end example - -Les manuels Info contiennent des sections et des indexs ainsi que des -hyperliens comme ce qu'on trouve sur les pages Web. Le lecteur -@command{info} (@pxref{Top, Info reader,, info-stnd, Stand-alone GNU Info}) -et sa contre-partie dans Emacs (@pxref{Misc Help,,, emacs, The GNU Emacs -Manual}) fournissent des raccourcis claviers intuitifs pour naviguer dans -les manuels @xref{Getting Started,,, info, Info: An Introduction} pour -trouver une introduction sur la navigation dans info. - -@node Installer les fichiers de débogage -@chapter Installer les fichiers de débogage - -@cindex fichiers de débogage -Les binaires des programmes, produits par les compilateurs GCC par exemple, -sont typiquement écrits au format ELF, avec une section contenant des -@dfn{informations de débogage}. Les informations de débogage sont ce qui -permet au débogueur, GDB, de relier le code binaire et le code source ; -elles sont requises pour déboguer un programme compilé dans de bonnes -conditions. - -Le problème avec les informations de débogage est qu'elles prennent pas mal -de place sur le disque. Par exemple, les informations de débogage de la -bibliothèque C de GNU prend plus de 60 Mo. Ainsi, en tant qu'utilisateur, -garder toutes les informations de débogage de tous les programmes installés -n'est souvent pas une possibilité. Cependant, l'économie d'espace ne devrait -pas empêcher le débogage — en particulier, dans le système GNU, qui devrait -faciliter pour ses utilisateurs l'exercice de leurs libertés -(@pxref{Distribution GNU}). - -Heureusement, les utilitaires binaires de GNU (Binutils) et GDB fournissent -un mécanisme qui permet aux utilisateurs d'avoir le meilleur des deux mondes -: les informations de débogage peuvent être nettoyées des binaires et -stockées dans des fichiers séparés. GDB peut ensuite charger les -informations de débogage depuis ces fichiers, lorsqu'elles sont disponibles -(@pxref{Separate Debug Files,,, gdb, Debugging with GDB}). - -La distribution GNU se sert de cela pour stocker les informations de -débogage dans le sous-répertoire @code{lib/debug} d'une sortie séparée du -paquet appelée sans grande imagination @code{debug} (@pxref{Des paquets avec plusieurs résultats}). Les utilisateurs peuvent choisir d'installer la sortie -@code{debug} d'un paquet lorsqu'ils en ont besoin. Par exemple, la commande -suivante installe les informations de débogage pour la bibliothèque C de GNU -et pour GNU Guile : - -@example -guix package -i glibc:debug guile:debug -@end example - -On doit ensuite dire à GDB de chercher les fichiers de débogage dans le -profil de l'utilisateur, en remplissant la variable -@code{debug-file-directory} (vous pourriez aussi l'instancier depuis le -fichier @file{~/.gdbinit}, @pxref{Startup,,, gdb, Debugging with GDB}) : - -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example - -À partir de maintenant, GDB récupérera les informations de débogage dans les -fichiers @code{.debug} de @file{~/.guix-profile/lib/debug}. - -EN plus, vous voudrez sans doute que GDB puisse montrer le code source -débogué. Pour cela, vous devrez désarchiver le code source du paquet qui -vous intéresse (obtenu via @code{guix build --source}, @pxref{Invoquer guix build}) et pointer GDB vers ce répertoire des sources avec la commande -@code{directory} (@pxref{Source Path, @code{directory},, gdb, Debugging with -GDB}). - -@c XXX: keep me up-to-date -Le mécanisme de la sortie @code{debug} dans Guix est implémenté par le -@code{gnu-build-system} (@pxref{Systèmes de construction}). Actuellement, ce n'est pas -obligatoire — les informations de débogage sont disponibles uniquement si -les définitions déclarent explicitement une sortie @code{debug}. Cela -pourrait être modifié tout en permettant aux paquets de s'en passer dans le -futur si nos serveurs de construction peuvent tenir la charge. Pour -vérifier si un paquet a une sortie @code{debug}, utilisez @command{guix -package --list-available} (@pxref{Invoquer guix package}). - - -@node Mises à jour de sécurité -@chapter Mises à jour de sécurité - -@cindex mises à jour de sécurité -@cindex vulnérabilités -Parfois, des vulnérabilités importantes sont découvertes dans les paquets -logiciels et doivent être corrigées. Les développeurs de Guix essayent de -suivre les vulnérabilités connues et d'appliquer des correctifs aussi vite -que possible dans la branche @code{master} de Guix (nous n'avons pas encore -de branche « stable » contenant seulement des mises à jour de sécurité). -L'outil @command{guix lint} aide les développeurs à trouver les versions -vulnérables des paquets logiciels dans la distribution : - -@smallexample -$ guix lint -c cve -gnu/packages/base.scm:652:2: glibc@@2.21: probablement vulnérable à CVE-2015-1781, CVE-2015-7547 -gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probablement vulnérable à CVE-2015-5276 -gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probablement vulnérable à CVE-2016-1923, CVE-2016-1924 -@dots{} -@end smallexample - -@xref{Invoquer guix lint}, pour plus d'informations. - -@quotation Remarque -À la version @value{VERSION}, la fonctionnalité ci-dessous est considérée -comme « bêta ». -@end quotation - -Guix suit une discipline de gestion de paquets fonctionnelle -(@pxref{Introduction}), ce qui implique que lorsqu'un paquet change, -@emph{tous les paquets qui en dépendent} doivent être reconstruits. Cela -peut grandement ralentir le déploiement de corrections dans les paquets du -cœur comme libc ou bash comme presque toute la distribution aurait besoin -d'être reconstruite. Cela aide d'utiliser des binaires pré-construits -(@pxref{Substituts}), mais le déploiement peut toujours prendre plus de -temps de souhaité. - -@cindex greffes -Pour corriger cela, Guix implémente les @dfn{greffes}, un mécanisme qui -permet un déploiement rapide des mises à jour de sécurité critiques sans le -coût associé à une reconstruction complète de la distribution. L'idée est -de reconstruire uniquement le paquet qui doit être corrigé puis de le « -greffer » sur les paquets qui sont explicitement installés par l'utilisateur -et qui se référaient avant au paquet d'origine. Le coût d'une greffe est -typiquement très bas, et plusieurs ordres de grandeurs moins élevé que de -reconstruire tout la chaîne de dépendance. - -@cindex remplacement de paquet, pour les greffes -For instance, suppose a security update needs to be applied to Bash. Guix -developers will provide a package definition for the ``fixed'' Bash, say -@code{bash-fixed}, in the usual way (@pxref{Définition des paquets}). 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{Invoquer guix gc})---that -is installed is automatically ``rewritten'' to refer to @code{bash-fixed} -instead of @code{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 (@code{bash-fixed} and @code{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. - -L'option en ligne de commande @option{--no-grafts} vous permet d'éviter les -greffes (@pxref{Options de construction communes, @option{--no-grafts}}). Donc la -commande : - -@example -guix build bash --no-grafts -@end example - -@noindent -renvoie le nom de fichier dans les dépôt du Bash original, alors que : - -@example -guix build bash -@end example - -@noindent -renvoie le nom de fichier du Bash « corrigé » de remplacement. Cela vous -permet de distinguer les deux variantes de Bash. - -Pour vérifier à quel Bash votre profil se réfère, vous pouvez lancer -(@pxref{Invoquer guix gc}) : - -@example -guix gc -R `readlink -f ~/.guix-profile` | grep bash -@end example - -@noindent -@dots{} et comparer les noms de fichiers que vous obtenez avec ceux du -dessus. De la même manière pour une génération du système Guix : - -@example -guix gc -R `guix system build my-config.scm` | grep bash -@end example - -Enfin, pour vérifier quelles processus Bash lancés vous utilisez, vous -pouvez utiliser la commande @command{lsof} : - -@example -lsof | grep /gnu/store/.*bash -@end example - - -@node Bootstrapping -@chapter Bootstrapping - -@c Adapted from the ELS 2013 paper. - -@cindex bootstrap - -Dans notre contexte, le bootstrap se réfère à la manière dont la -distribution est construite « à partir de rien ». Rappelez-vous que -l'environnement de construction d'une dérivation ne contient rien d'autre -que les entrées déclarées (@pxref{Introduction}). Donc il y a un problème -évident de poule et d'œuf : comment le premier paquet est-il construit ? -Comment le premier compilateur est-il construit ? Remarquez que c'est une -question qui intéressera uniquement le hacker curieux, pas l'utilisateur -normal, donc vous pouvez sauter cette section sans avoir honte si vous vous -considérez comme un « utilisateur normal ». - -@cindex binaires de bootstrap -Le système GNU est surtout fait de code C, avec la libc en son cœur. Le -système de construction GNU lui-même suppose la disponibilité d'un shell -Bourne et d'outils en ligne de commande fournis par GNU Coreutils, Awk, -Findutils, sed et grep. En plus, les programmes de construction — les -programmes qui exécutent @code{./configure}, @code{make} etc — sont écrits -en Guile Scheme (@pxref{Dérivations}). En conséquence, pour pouvoir -construire quoi que ce soit, de zéro, Guix a besoin de binaire -pré-construits de Guile, GCC, Binutils, la libc et des autres paquets -mentionnés plus haut — les @dfn{binaires de bootstrap}. - -Ces binaires de bootstrap sont pris comme des acquis, bien qu'on puisse les -recréer (ça arrive plus tard). - -@unnumberedsec Se préparer à utiliser les binaires de bootstrap - -@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,,Graphe de dépendance des premières -dérivations de bootstrap} - -La figure ci-dessus montre le tout début du graphe de dépendances de la -distribution, correspondant aux définitions des paquets du module @code{(gnu -packages bootstrap)}. Une figure similaire peut être générée avec -@command{guix graph} (@pxref{Invoquer guix graph}), de cette manière : - -@example -guix graph -t derivation \ - -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ - | dot -Tps > t.ps -@end example - -À ce niveau de détails, les choses sont légèrement complexes. Tout d'abord, -Guile lui-même consiste en an exécutable ELF, avec plusieurs fichiers Scheme -sources et compilés qui sont chargés dynamiquement quand il est exécuté. -Cela est stocké dans l'archive @file{guile-2.0.7.tar.xz} montrée dans ce -graphe. Cette archive fait parti de la distribution « source » de Guix, et -est insérée dans le dépôt avec @code{add-to-store} (@pxref{Le dépôt}). - -Mais comment écrire une dérivation qui décompresse cette archive et l'ajoute -au dépôt ? Pour résoudre ce problème, la dérivation -@code{guile-bootstrap-2.0.drv} — la première qui est construite — utilise -@code{bash} comme constructeur, qui lance @code{build-bootstrap-guile.sh}, -qui à son tour appelle @code{tar} pour décompresser l'archive. Ainsi, -@file{bash}, @file{tar}, @file{xz} et @file{mkdir} sont des binaires liés -statiquement, qui font aussi partie de la distribution source de Guix, dont -le seul but est de permettre à l'archive de Guile d'être décompressée. - -Une fois que @code{guile-bootstrap-2.0.drv} est construit, nous avons un -Guile fonctionnel qui peut être utilisé pour exécuter les programmes de -construction suivants. Sa première tâche consiste à télécharger les -archives contenant les autres binaires pré-construits — c'est ce que la -dérivation @code{.tar.xz.drv} fait. Les modules Guix comme -@code{ftp-client.scm} sont utilisés pour cela. Les dérivations -@code{module-import.drv} importent ces modules dans un répertoire dans le -dépôt, en utilisant la disposition d'origine. Les dérivations -@code{module-import-compiled.drv} compilent ces modules, et les écrivent -dans un répertoire de sortie avec le bon agencement. Cela correspond à -l'argument @code{#:modules} de @code{build-expression->derivation} -(@pxref{Dérivations}). - -Enfin, les diverses archives sont décompressées par les dérivations -@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etc, à partir de -quoi nous avons une chaîne de compilation C fonctionnelle. - - -@unnumberedsec Construire les outils de construction - -Le bootstrap est complet lorsque nous avons une chaîne d'outils complète qui -ne dépend pas des outils de bootstrap pré-construits dont on vient de -parler. Ce pré-requis d'indépendance est vérifié en s'assurant que les -fichiers de la chaîne d'outil finale ne contiennent pas de référence vers -les répertoires @file{/gnu/store} des entrées de bootstrap. Le processus -qui mène à cette chaîne d'outils « finale » est décrit par les définitions -de paquets qui se trouvent dans le module @code{(gnu packages -commencement)}. - -La commande @command{guix graph} nous permet de « dézoomer » comparé au -graphe précédent, en regardant au niveau des objets de paquets plutôt que -des dérivations individuelles — rappelez-vous qu'un paquet peut se traduire -en plusieurs dérivations, typiquement une dérivation pour télécharger ses -sources, une pour les modules Guile dont il a besoin et une pour -effectivement compiler le paquet depuis les sources. La commande : - -@example -guix graph -t bag \ - -e '(@@@@ (gnu packages commencement) - glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps -@end example - -@noindent -produit le graphe de dépendances qui mène à la bibliothèque C « finale -»@footnote{Vous remarquerez qu'elle s'appelle @code{glibc-intermediate}, ce -qui suggère qu'elle n'est pas @emph{tout à fait} finale, mais c'est une -bonne approximation tout de même.}, que voici : - -@image{images/bootstrap-packages,6in,,Graphe de dépendance des premiers -paquets} - -@c See . -Le premier outil construit avec les binaires de bootstrap est GNU@tie{}Make -— appelé @code{make-boot0} ci-dessus — qui est un prérequis de tous les -paquets suivants . Ensuite, Findutils et Diffutils sont construits. - -Ensuite vient la première passe de Binutils et GCC, construits comme des -pseudo outils croisés — c.-à-d.@: dont @code{--target} égal à -@code{--host}. Ils sont utilisés pour construire la libc. Grâce à cette -astuce de compilation croisée, la libc est garantie de ne contenir aucune -référence à la chaîne d'outils initiale. - -À partir de là, les Bintulis et GCC finaux (pas visibles ci-dessus) sont -construits. GCC utilise @code{ld} du Binutils final et lie les programme -avec la libc qui vient d'être construite. Cette chaîne d'outils est -utilisée pour construire les autres paquets utilisés par Guix et par le -système de construction de GNU : Guile, Bash, Coreutils, etc. - -Et voilà ! À partir de là nous avons l'ensemble complet des outils auxquels -s'attend le système de construction GNU. Ils sont dans la variable -@code{%final-inputs} du module @code{(gnu packages commencement)} et sont -implicitement utilisés par tous les paquets qui utilisent le -@code{gnu-build-system} (@pxref{Systèmes de construction, @code{gnu-build-system}}). - - -@unnumberedsec Construire les binaires de bootstrap - -@cindex binaires de bootstrap -Comme la chaîne d'outils finale ne dépend pas des binaires de bootstrap, ils -ont rarement besoin d'être mis à jour. Cependant, il est utile d'avoir une -manière de faire cela automatiquement, dans le cas d'une mise à jour et -c'est ce que le module @code{(gnu packages make-bootstrap)} fournit. - -La commande suivante construit les archives contenant les binaires de -bootstrap (Guile, Binutils, GCC, la libc et une archive contenant un mélange -de Coreutils et d'autres outils en ligne de commande de base) : - -@example -guix build bootstrap-tarballs -@end example - -Les archives générées sont celles qui devraient être référencées dans le -module @code{(gnu packages bootstrap)} au début de cette section. - -Vous êtes toujours là ? Alors peut-être que maintenant vous vous demandez, -quand est-ce qu'on atteint un point fixe ? C'est une question intéressante -! La réponse est inconnue, mais si vous voulez enquêter plus profondément -(et que vous avez les ressources en puissance de calcul et en capacité de -stockage pour cela), dites-le nous. - -@unnumberedsec Réduire l'ensemble des binaires de bootstrap - -Nous binaires de bootstrap incluent actuellement GCC, Guile, etc. C'est -beaucoup de code binaire ! Pourquoi est-ce un problème ? C'est un problème -parce que ces gros morceaux de code binaire sont en pratique impossibles à -auditer, ce qui fait qu'il est difficile d'établir quel code source les a -produit. Chaque binaire non auditable nous rend aussi vulnérable à des -portes dérobées dans les compilateurs comme le décrit Ken Thompson dans le -papier de 1984 @emph{Reflections on Trusting Trust}. - -Cela est rendu moins inquiétant par le fait que les binaires de bootstrap -ont été générés par une révision antérieure de Guix. Cependant, il leur -manque le niveau de transparence que l'on obtient avec le reste des paquets -du graphe de dépendance, où Guix nous donne toujours une correspondance -source-binaire. Ainsi, notre but est de réduire l'ensemble des binaires de -bootstrap au minimum. - -Le @uref{http://bootstrappable.org, site web Bootstrappable.org} liste les -projets en cours à ce sujet. L'un d'entre eux parle de remplacer le GCC de -bootstrap par une série d'assembleurs, d'interpréteurs et de compilateurs -d'une complexité croissante, qui pourraient être construits à partir des -sources à partir d'un assembleur simple et auditable. Votre aide est la -bienvenue ! - - -@node Porter -@chapter Porter vers une nouvelle plateforme - -Comme nous en avons discuté plus haut, la distribution GNU est -auto-contenue, et cela est possible en se basant sur des « binaires de -bootstrap » pré-construits (@pxref{Bootstrapping}). Ces binaires sont -spécifiques au noyau de système d'exploitation, à l'architecture CPU et à -l'interface applicative binaire (ABI). Ainsi, pour porter la distribution -sur une plateforme qui n'est pas encore supportée, on doit construire ces -binaires de bootstrap et mettre à jour le module @code{(gnu packages -bootstrap)} pour les utiliser sur cette plateforme. - -Heureusement, Guix peut effectuer une @emph{compilation croisée} de ces -binaires de bootstrap. Lorsque tout va bien, et en supposant que la chaîne -d'outils GNU supporte la plateforme cible, cela peut être aussi simple que -de lancer une commande comme ceci : - -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example - -Pour que cela fonctione, la procédure @code{glibc-dynamic-linker} dans -@code{(gnu packages bootstrap)} doit être augmentée pour renvoyer le bon nom -de fichier pour l'éditeur de lien dynamique de la libc sur cette plateforme -; de même, il faut indiquer cette nouvelle platefore à -@code{system->linux-architecture} dans @code{(gnu packages linux)}. - -Une fois qu'ils sont construits, le module @code{(gnu packages bootstrap)} -doit être mis à jour pour se référer à ces binaires sur la plateforme -cible. C'est à dire que les hashs et les URL des archives de bootstrap pour -la nouvelle plateforme doivent être ajoutés avec ceux des plateformes -actuellement supportées. L'archive de bootstrap de Guile est traitée -séparément : elle doit être disponible localement, et @file{gnu/local.mk} a -une règle pour la télécharger pour les architectures supportées ; vous devez -également ajouter une règle pour la nouvelle plateforme. - -En pratique, il peut y avoir des complications. Déjà, il se peut que le -triplet GNU étendu qui spécifie l'ABI (comme le suffixe @code{eabi} -ci-dessus) ne soit pas reconnu par tous les outils GNU. Typiquement, la -glibc en reconnais certains, alors que GCC utilise un drapeau de configure -@code{--with-abi} supplémentaire (voir @code{gcc.scm} pour trouver des -exemples où ce cas est géré). Ensuite, certains des paquets requis -pourraient échouer à se construire pour cette plateforme. Enfin, les -binaires générés pourraient être cassé pour une raison ou une autre. - -@c ********************************************************************* -@include contributing.fr.texi - -@c ********************************************************************* -@node Remerciements -@chapter Remerciements - -Guix se base sur le @uref{http://nixos.org/nix/, gestionnaire de paquets -Nix} conçu et implémenté par Eelco Dolstra, avec des contributions d'autres -personnes (voir le fichier @file{nix/AUTHORS} dans Guix). Nix a inventé la -gestion de paquet fonctionnelle et promu des fonctionnalités sans précédents -comme les mises à jour de paquets transactionnelles et les retours en -arrière, les profils par utilisateurs et les processus de constructions -transparents pour les références. Sans ce travail, Guix n'existerait pas. - -Les distributions logicielles basées sur Nix, Nixpkgs et NixOS, ont aussi -été une inspiration pour Guix. - -GNU@tie{}Guix lui-même est un travail collectif avec des contributions d'un -grand nombre de personnes. Voyez le fichier @file{AUTHORS} dans Guix pour -plus d'information sur ces personnes de qualité. Le fichier @file{THANKS} -liste les personnes qui ont aidé en rapportant des bogues, en prenant soin -de l'infrastructure, en fournissant des images et des thèmes, en faisant des -suggestions et bien plus. Merci ! - - -@c ********************************************************************* -@node La licence GNU Free Documentation -@appendix La licence GNU Free Documentation -@cindex license, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Index des concepts -@unnumbered Index des concepts -@printindex cp - -@node Index de programmation -@unnumbered Index de programmation -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: diff --git a/doc/guix.zh_CN.texi b/doc/guix.zh_CN.texi deleted file mode 100644 index 993220fdc0..0000000000 --- a/doc/guix.zh_CN.texi +++ /dev/null @@ -1,25352 +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.zh_CN.info -@documentencoding UTF-8 -@settitle GNU Guix参考手册 -@c %**end of header - -@include version-zh_CN.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.zh_CN.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, -2019 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, 2019 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@* - -Permission is granted to copy, distribute and/or modify this document under -the terms of the GNU Free Documentation License, Version 1.3 or any later -version published by the Free Software Foundation; with no Invariant -Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the -license is included in the section entitled ``GNU Free Documentation -License''. -@end copying - -@dircategory System administration -@direntry -* Guix: (guix). Manage installed software and system - configuration. -* guix package: (guix)Invoking guix package. Installing, removing, and - upgrading packages. -* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space. -* guix pull: (guix)Invoking guix pull. Update the list of available - packages. -* guix system: (guix)Invoking guix system. Manage the operating system - configuration. -@end direntry - -@dircategory Software development -@direntry -* guix environment: (guix)Invoking guix environment. Building development - environments with - Guix. -* guix build: (guix)Invoking guix build. Building packages. -* guix pack: (guix)Invoking guix pack. Creating binary bundles. -@end direntry - -@titlepage -@title GNU Guix参考手册 -@subtitle Using the GNU Guix Functional Package Manager -@author The GNU Guix Developers - -@page -@vskip 0pt plus 1filll -Edition @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -This document describes GNU Guix version @value{VERSION}, a functional -package management tool written for the GNU system. - -@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. -This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de -référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch -zu GNU Guix}). If you would like to translate it in your native language, -consider joining the -@uref{https://translationproject.org/domain/guix-manual.html, Translation -Project}. - -@menu -* Introduction:: What is Guix about? -* Installation:: Installing Guix. -* System Installation:: Installing the whole operating system. -* Package Management:: Package installation, upgrade, etc. -* Development:: Guix-aided software development. -* Programming Interface:: Using Guix in Scheme. -* Utilities:: Package management commands. -* System Configuration:: Configuring the operating system. -* Documentation:: Browsing software user manuals. -* Installing Debugging Files:: Feeding the debugger. -* Security Updates:: Deploying security fixes quickly. -* Bootstrapping:: GNU/Linux built from scratch. -* Porting:: Targeting another platform or kernel. -* 贡献:: Your help needed! - -* Acknowledgments:: Thanks! -* GNU Free Documentation License:: The license of this manual. -* Concept Index:: Concepts. -* Programming Index:: Data types, functions, and variables. - -@detailmenu - --- The Detailed Node Listing --- - - - -Introduction - - - -* Managing Software the Guix Way:: What's special. -* GNU Distribution:: The packages and tools. - -Installation - - - -* Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. -* Setting Up the Daemon:: Preparing the build daemon's environment. -* Invoking guix-daemon:: Running the build daemon. -* Application Setup:: Application-specific setup. - -Setting Up the Daemon - - - -* Build Environment Setup:: Preparing the isolated build environment. -* Daemon Offload Setup:: Offloading builds to remote machines. -* SELinux Support:: Using an SELinux policy for the daemon. - -System Installation - - - -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Guided Graphical Installation:: Easy graphical installation. -* Manual Installation:: Manual installation for wizards. -* After System Installation:: When installation succeeded. -* Installing Guix in a VM:: Guix System playground. -* Building the Installation Image:: How this comes to be. - -Manual Installation - - - -* Keyboard Layout and Networking and Partitioning:: Initial setup. -* Proceeding with the Installation:: Installing. - -Package Management - - - -* Features:: How Guix will make your life brighter. -* Invoking guix package:: Package installation, removal, etc. -* Substitutes:: Downloading pre-built binaries. -* Packages with Multiple Outputs:: Single source package, multiple outputs. -* Invoking guix gc:: Running the garbage collector. -* Invoking guix pull:: Fetching the latest Guix and distribution. -* Channels:: Customizing the package collection. -* Inferiors:: Interacting with another revision of Guix. -* Invoking guix describe:: Display information about your Guix revision. -* Invoking guix archive:: Exporting and importing store files. - -Substitutes - - - -* Official Substitute Server:: One particular source of substitutes. -* Substitute Server Authorization:: How to enable or disable substitutes. -* Substitute Authentication:: How Guix verifies substitutes. -* Proxy Settings:: How to get substitutes via proxy. -* Substitution Failure:: What happens when substitution fails. -* On Trusting Binaries:: How can you trust that binary blob? - -Development - - - -* Invoking guix environment:: Setting up development environments. -* Invoking guix pack:: Creating software bundles. - -Programming Interface - - - -* Package Modules:: Packages from the programmer's viewpoint. -* Defining Packages:: Defining new packages. -* Build Systems:: Specifying how packages are built. -* The Store:: Manipulating the package store. -* Derivations:: Low-level interface to package derivations. -* The Store Monad:: Purely functional interface to the store. -* G-Expressions:: Manipulating build expressions. -* Invoking guix repl:: Fiddling with Guix interactively. - -Defining Packages - - - -* package Reference:: The package data type. -* origin Reference:: The origin data type. - -Utilities - - - -* Invoking guix build:: Building packages from the command line. -* Invoking guix edit:: Editing package definitions. -* Invoking guix download:: Downloading a file and printing its hash. -* Invoking guix hash:: Computing the cryptographic hash of a file. -* Invoking guix import:: Importing package definitions. -* Invoking guix refresh:: Updating package definitions. -* Invoking guix lint:: Finding errors in package definitions. -* Invoking guix size:: Profiling disk usage. -* Invoking guix graph:: Visualizing the graph of packages. -* Invoking guix publish:: Sharing substitutes. -* Invoking guix challenge:: Challenging substitute servers. -* Invoking guix copy:: Copying to and from a remote store. -* Invoking guix container:: Process isolation. -* Invoking guix weather:: Assessing substitute availability. -* Invoking guix processes:: Listing client processes. - -Invoking @command{guix build} - - - -* Common Build Options:: Build options for most commands. -* Package Transformation Options:: Creating variants of packages. -* Additional Build Options:: Options specific to 'guix build'. -* Debugging Build Failures:: Real life packaging experience. - -System Configuration - - - -* Using the Configuration System:: Customizing your GNU system. -* operating-system Reference:: Detail of operating-system declarations. -* File Systems:: Configuring file system mounts. -* Mapped Devices:: Block device extra processing. -* User Accounts:: Specifying user accounts. -* Keyboard Layout:: How the system interprets key strokes. -* Locales:: Language and cultural convention settings. -* Services:: Specifying system services. -* Setuid Programs:: Programs running with root privileges. -* X.509 Certificates:: Authenticating HTTPS servers. -* Name Service Switch:: Configuring libc's name service switch. -* Initial RAM Disk:: Linux-Libre bootstrapping. -* Bootloader Configuration:: Configuring the boot loader. -* Invoking guix system:: Instantiating a system configuration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Defining Services:: Adding new service definitions. - -Services - - - -* Base Services:: Essential system services. -* Scheduled Job Execution:: The mcron service. -* Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. -* X Window:: Graphical display. -* Printing Services:: Local and remote printer support. -* Desktop Services:: D-Bus and desktop services. -* Sound Services:: ALSA and Pulseaudio services. -* Database Services:: SQL databases, key-value stores, etc. -* Mail Services:: IMAP, POP3, SMTP, and all that. -* Messaging Services:: Messaging services. -* Telephony Services:: Telephony services. -* Monitoring Services:: Monitoring services. -* Kerberos Services:: Kerberos services. -* Web Services:: Web servers. -* Certificate Services:: TLS certificates via Let's Encrypt. -* DNS Services:: DNS daemons. -* VPN Services:: VPN daemons. -* Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. -* Power Management Services:: Extending battery life. -* Audio Services:: The MPD. -* Virtualization Services:: Virtualization services. -* Version Control Services:: Providing remote access to Git repositories. -* Game Services:: Game servers. -* Miscellaneous Services:: Other services. - -Defining Services - - - -* Service Composition:: The model for composing services. -* Service Types and Services:: Types and services. -* Service Reference:: API reference. -* Shepherd Services:: A particular type of service. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Introduction -@chapter Introduction - -@cindex purpose -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 user interfaces -Guix provides a command-line package management interface (@pxref{Package -Management}), tools to help with software development (@pxref{Development}), -command-line utilities for more advanced usage, (@pxref{Utilities}), as well -as Scheme programming interfaces (@pxref{Programming Interface}). -@cindex build daemon -Its @dfn{build daemon} is responsible for building packages on behalf of -users (@pxref{Setting Up the Daemon}) and for downloading pre-built binaries -from authorized sources (@pxref{Substitutes}). - -@cindex extensibility of the distribution -@cindex customization, of packages -Guix includes package definitions for many GNU and non-GNU packages, all of -which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the user's -computing freedom}. It is @emph{extensible}: users can write their own -package definitions (@pxref{Defining Packages}) and make them available as -independent package modules (@pxref{Package Modules}). It is also -@emph{customizable}: users can @emph{derive} specialized package definitions -from existing ones, including from the command line (@pxref{Package -Transformation Options}). - -@cindex functional package management -@cindex isolation -Under the hood, Guix implements the @dfn{functional package management} -discipline pioneered by Nix (@pxref{Acknowledgments}). In Guix, the package -build and installation process is seen as a @emph{function}, in the -mathematical sense. That function takes inputs, such as build scripts, a -compiler, and libraries, and returns an installed package. As a pure -function, its result depends solely on its inputs---for instance, it cannot -refer to software or scripts that were not explicitly passed as inputs. A -build function always produces the same result when passed a given set of -inputs. It cannot alter the environment of the running system in any way; -for instance, it cannot create, modify, or delete files outside of its build -and installation directories. This is achieved by running build processes -in isolated environments (or @dfn{containers}), where only their explicit -inputs are visible. - -@cindex store -The result of package build functions is @dfn{cached} in the file system, in -a special directory called @dfn{the store} (@pxref{The Store}). Each -package is installed in a directory of its own in the store---by default -under @file{/gnu/store}. The directory name contains a hash of all the -inputs used to build that package; thus, changing an input yields a -different directory name. - -This approach is the foundation for the salient features of Guix: support -for transactional package upgrade and rollback, per-user installation, and -garbage collection of packages (@pxref{Features}). - - -@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{System Installation}), 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. - -The distribution provides core GNU packages such as GNU libc, GCC, and -Binutils, as well as many GNU and non-GNU applications. The complete list -of available packages can be browsed -@url{http://www.gnu.org/software/guix/packages,on-line} or by running -@command{guix package} (@pxref{Invoking guix package}): - -@example -guix package --list-available -@end example - -Our goal is to provide a practical 100% free software distribution of -Linux-based and other variants of GNU, with a focus on the promotion and -tight integration of GNU components, and an emphasis on programs and tools -that help users exert that freedom. - -Packages are currently available on the following platforms: - -@table @code - -@item x86_64-linux -Intel/AMD @code{x86_64} architecture, Linux-Libre kernel; - -@item i686-linux -Intel 32-bit architecture (IA32), Linux-Libre kernel; - -@item armhf-linux -ARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABI -hard-float application binary interface (ABI), and Linux-Libre kernel. - -@item aarch64-linux -little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is -currently in an experimental stage, with limited support. -@xref{贡献}, for how to help! - -@item mips64el-linux -little-endian 64-bit MIPS processors, specifically the Loongson series, n32 -ABI, and Linux-Libre 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{System -Configuration}). Guix System uses the Linux-libre kernel, the Shepherd -initialization system (@pxref{Introduction,,, 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 -For information on porting to other architectures or kernels, -@pxref{Porting}. - -Building this distribution is a cooperative effort, and you are invited to -join! @xref{贡献}, for information about how you can help. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex installing Guix - -@quotation Note -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{System Installation}.} The script -automates the download, installation, and initial configuration of Guix. It -should be run as the root user. -@end quotation - -@cindex foreign distro -@cindex directories related to foreign distro -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. - -Once installed, Guix can be updated by running @command{guix pull} -(@pxref{Invoking 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 -* Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. -* Setting Up the Daemon:: Preparing the build daemon's environment. -* Invoking guix-daemon:: Running the build daemon. -* Application Setup:: Application-specific setup. -@end menu - -@node Binary Installation -@section Binary Installation - -@cindex installing Guix from binaries -@cindex installer script -This section describes how to install Guix on an arbitrary system from a -self-contained tarball providing binaries for Guix and for all its -dependencies. This is often quicker than installing from source, which is -described in the next sections. The only requirement is to have -GNU@tie{}tar and Xz. - -Installing goes along these lines: - -@enumerate -@item -@cindex downloading Guix binary -Download the binary tarball from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}, -where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine -already running the kernel Linux, and so on. - -@c The following is somewhat duplicated in ``System Installation''. -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the tarball against it, along these lines: - -@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 - -If that command fails because you do not have the required public key, then -run this command to import it: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -and rerun the @code{gpg --verify} command. - -@item -Now, you need to become the @code{root} user. Depending on your -distribution, you may have to run @code{su -} or @code{sudo -i}. As -@code{root}, run: - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{system}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}. -The latter contains a ready-to-use profile for @code{root} (see next step.) - -Do @emph{not} unpack the tarball on a working Guix system since that would -overwrite its own essential files. - -The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does not -emit warnings about ``implausibly old time stamps'' (such warnings were -triggered by GNU@tie{}tar 1.26 and older; recent versions are fine.) They -stem from the fact that all the files in the archive have their modification -time set to zero (which means January 1st, 1970.) This is done on purpose -to make sure the archive content is independent of its creation time, thus -making it reproducible. - -@item -Make the profile available under @file{~root/.config/guix/current}, which is -where @command{guix pull} will install updates (@pxref{Invoking guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Source @file{etc/profile} to augment @code{PATH} and other relevant -environment variables: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Create the group and user accounts for build users as explained below -(@pxref{Build Environment Setup}). - -@item -Run the daemon, and set it to automatically start on boot. - -If your host distro uses the systemd init system, this can be achieved with -these commands: - -@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 - -If your host distro uses the Upstart init system: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Otherwise, you can still start the daemon manually with: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Make the @command{guix} command available to other users on the machine, for -instance with: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -It is also a good idea to make the Info version of this manual available -there: - -@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 - -That way, assuming @file{/usr/local/share/info} is in the search path, -running @command{info guix} will open this manual (@pxref{Other Info -Directories,,, texinfo, GNU Texinfo}, for more details on changing the Info -search path.) - -@item -@cindex substitutes, authorization thereof -To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its -mirrors (@pxref{Substitutes}), authorize them: - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@item -Each user may need to perform a few additional steps to make their Guix -environment ready for use, @pxref{Application Setup}. -@end enumerate - -Voilà, the installation is complete! - -You can confirm that Guix is working by installing a sample package into the -root profile: - -@example -# guix package -i hello -@end example - -The @code{guix} package must remain available in @code{root}'s profile, or -it would become subject to garbage collection---in which case you would find -yourself badly handicapped by the lack of the @command{guix} command. In -other words, do not remove @code{guix} by running @code{guix package -r -guix}. - -The binary installation tarball can be (re)produced and verified simply by -running the following command in the Guix source tree: - -@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 - -@xref{Invoking guix pack}, for more info on this handy tool. - -@node Requirements -@section Requirements - -This section lists requirements when building Guix from source. The build -procedure for Guix is the same as for other GNU software, and is not covered -here. Please see the files @file{README} and @file{INSTALL} in the Guix -source tree for additional details. - -@cindex official website -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. - -GNU Guix depends on the following packages: - -@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 or later; -@item -@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings -(@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 or later; -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 -or later; -@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 - -The following dependencies are optional: - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Support for build offloading (@pxref{Daemon Offload Setup}) and -@command{guix copy} (@pxref{Invoking guix copy}) depends on -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, version -0.10.2 or later. - -@item -When @url{http://www.bzip.org, libbz2} is available, @command{guix-daemon} -can use it to compress build logs. -@end itemize - -Unless @code{--disable-daemon} was passed to @command{configure}, the -following packages are also needed: - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}; -@item @url{http://sqlite.org, SQLite 3}; -@item @url{http://gcc.gnu.org, GCC's g++}, with support for the -C++11 standard. -@end itemize - -@cindex state directory -When configuring Guix on a system that already has a Guix installation, be -sure to specify the same state directory as the existing installation using -the @code{--localstatedir} option of the @command{configure} script -(@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding -Standards}). The @command{configure} script protects against unintended -misconfiguration of @var{localstatedir} so you do not inadvertently corrupt -your store (@pxref{The Store}). - -@cindex Nix, compatibility -When a working installation of @url{http://nixos.org/nix/, the Nix package -manager} is available, you can instead configure Guix with -@code{--disable-daemon}. In that case, Nix replaces the three dependencies -above. - -Guix is compatible with Nix, so it is possible to share the same store -between both. To do so, you must pass @command{configure} not only the same -@code{--with-store-dir} value, but also the same @code{--localstatedir} -value. The latter is essential because it specifies where the database that -stores metadata about the store is located, among other things. The default -values for Nix are @code{--with-store-dir=/nix/store} and -@code{--localstatedir=/nix/var}. Note that @code{--disable-daemon} is not -required if your goal is to share the store with Nix. - -@node Running the Test Suite -@section Running the Test Suite - -@cindex test suite -After a successful @command{configure} and @code{make} run, it is a good -idea to run the test suite. It can help catch issues with the setup or -environment, or bugs in Guix itself---and really, reporting test failures is -a good way to help improve the software. To run the test suite, type: - -@example -make check -@end example - -Test cases can run in parallel: you can use the @code{-j} option of -GNU@tie{}make to speed things up. The first run may take a few minutes on a -recent machine; subsequent runs will be faster because the store that is -created for test purposes will already have various things in cache. - -It is also possible to run a subset of the tests by defining the -@code{TESTS} makefile variable as in this example: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -By default, tests results are displayed at a file level. In order to see -the details of every individual test cases, it is possible to define the -@code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -Upon failure, please email @email{bug-guix@@gnu.org} and attach the -@file{test-suite.log} file. Please specify the Guix version being used as -well as version numbers of the dependencies (@pxref{Requirements}) in your -message. - -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 -or, again, by defining @code{TESTS} to select a subset of tests to run: - -@example -make check-system TESTS="basic mcron" -@end example - -These system tests are defined in the @code{(gnu tests @dots{})} modules. -They work by running the operating systems under test with lightweight -instrumentation in a virtual machine (VM). They can be computationally -intensive or rather cheap, depending on whether substitutes are available -for their dependencies (@pxref{Substitutes}). Some of them require a lot of -storage space to hold VM images. - -Again in case of test failures, please send @email{bug-guix@@gnu.org} all -the details. - -@node Setting Up the Daemon -@section Setting Up the Daemon - -@cindex daemon -Operations such as building a package or running the garbage collector are -all performed by a specialized process, the @dfn{build daemon}, on behalf of -clients. Only the daemon may access the store and its associated database. -Thus, any operation that manipulates the store goes through the daemon. For -instance, command-line tools such as @command{guix package} and -@command{guix build} communicate with the daemon (@i{via} remote procedure -calls) to instruct it what to do. - -The following sections explain how to prepare the build daemon's -environment. See also @ref{Substitutes}, for information on how to allow -the daemon to download pre-built binaries. - -@menu -* Build Environment Setup:: Preparing the isolated build environment. -* Daemon Offload Setup:: Offloading builds to remote machines. -* SELinux Support:: Using an SELinux policy for the daemon. -@end menu - -@node Build Environment Setup -@subsection Build Environment Setup - -@cindex build environment -In a standard multi-user setup, Guix and its daemon---the -@command{guix-daemon} program---are installed by the system administrator; -@file{/gnu/store} is owned by @code{root} and @command{guix-daemon} runs as -@code{root}. Unprivileged users may use Guix tools to build packages or -otherwise access the store, and the daemon will do it on their behalf, -ensuring that the store is kept in a consistent state, and allowing built -packages to be shared among users. - -@cindex build users -When @command{guix-daemon} runs as @code{root}, you may not want package -build processes themselves to run as @code{root} too, for obvious security -reasons. To avoid that, a special pool of @dfn{build users} should be -created for use by build processes started by the daemon. These build users -need not have a shell and a home directory: they will just be used when the -daemon drops @code{root} privileges in build processes. Having several such -users allows the daemon to launch distinct build processes under separate -UIDs, which guarantees that they do not interfere with each other---an -essential feature since builds are regarded as pure functions -(@pxref{Introduction}). - -On a GNU/Linux system, a build user pool may be created like this (using -Bash syntax and the @code{shadow} commands): - -@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 build user $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -The number of build users determines how many build jobs may run in -parallel, as specified by the @option{--max-jobs} option (@pxref{Invoking -guix-daemon, @option{--max-jobs}}). To use @command{guix system vm} and -related commands, you may need to add the build users to the @code{kvm} -group so they can access @file{/dev/kvm}, using @code{-G guixbuild,kvm} -instead of @code{-G guixbuild} (@pxref{Invoking guix system}). - -The @code{guix-daemon} program may then be run as @code{root} with the -following command@footnote{If your machine uses the systemd init system, -dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} file -in @file{/etc/systemd/system} will ensure that @command{guix-daemon} is -automatically started. Similarly, if your machine uses the Upstart init -system, drop the @file{@var{prefix}/lib/upstart/system/guix-daemon.conf} -file in @file{/etc/init}.}: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -This way, the daemon starts build processes in a chroot, under one of the -@code{guixbuilder} users. On GNU/Linux, by default, the chroot environment -contains nothing but: - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -a minimal @code{/dev} directory, created mostly independently from the host -@code{/dev}@footnote{``Mostly'', because while the set of files that appear -in the chroot's @code{/dev} is fixed, most of these files can only be -created if the host has them.}; - -@item -the @code{/proc} directory; it only shows the processes of the container -since a separate PID name space is used; - -@item -@file{/etc/passwd} with an entry for the current user and an entry for user -@file{nobody}; - -@item -@file{/etc/group} with an entry for the user's group; - -@item -@file{/etc/hosts} with an entry that maps @code{localhost} to -@code{127.0.0.1}; - -@item -a writable @file{/tmp} directory. -@end itemize - -You can influence the directory where the daemon stores build trees @i{via} -the @code{TMPDIR} environment variable. However, the build tree within the -chroot is always called @file{/tmp/guix-build-@var{name}.drv-0}, where -@var{name} is the derivation name---e.g., @code{coreutils-8.24}. This way, -the value of @code{TMPDIR} does not leak inside build environments, which -avoids discrepancies in cases where build processes capture the name of -their build tree. - -@vindex http_proxy -The daemon also honors the @code{http_proxy} environment variable for HTTP -downloads it performs, be it for fixed-output derivations -(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}). - -If you are installing Guix as an unprivileged user, it is still possible to -run @command{guix-daemon} provided you pass @code{--disable-chroot}. -However, build processes will not be isolated from one another, and not from -the rest of the system. Thus, build processes may interfere with each -other, and may access programs, libraries, and other files available on the -system---making it much harder to view them as @emph{pure} functions. - - -@node Daemon Offload Setup -@subsection Using the Offload Facility - -@cindex offloading -@cindex build hook -When desired, the build daemon can @dfn{offload} derivation builds to other -machines running Guix, using the @code{offload} @dfn{build -hook}@footnote{This feature is available only when -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is present.}. -When that feature is enabled, a list of user-specified build machines is -read from @file{/etc/guix/machines.scm}; every time a build is requested, -for instance via @code{guix build}, the daemon attempts to offload it to one -of the machines that satisfy the constraints of the derivation, in -particular its system type---e.g., @file{x86_64-linux}. Missing -prerequisites for the build are copied over SSH to the target machine, which -then proceeds with the build; upon success the output(s) of the build are -copied back to the initial machine. - -The @file{/etc/guix/machines.scm} file typically looks like this: - -@example -(list (build-machine - (name "eightysix.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "bob") - (speed 2.)) ;incredibly fast! - - (build-machine - (name "meeps.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alice") - (private-key - (string-append (getenv "HOME") - "/.ssh/identity-for-guix")))) -@end example - -@noindent -In the example above we specify a list of two build machines, one for the -@code{x86_64} architecture and one for the @code{mips64el} architecture. - -In fact, this file is---not surprisingly!---a Scheme file that is evaluated -when the @code{offload} hook is started. Its return value must be a list of -@code{build-machine} objects. While this example shows a fixed list of -build machines, one could imagine, say, using DNS-SD to return a list of -potential build machines discovered in the local network -(@pxref{Introduction, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme -Programs}). The @code{build-machine} data type is detailed below. - -@deftp {Data Type} build-machine -This data type represents build machines to which the daemon may offload -builds. The important fields are: - -@table @code - -@item name -The host name of the remote machine. - -@item system -The system type of the remote machine---e.g., @code{"x86_64-linux"}. - -@item user -The user account to use when connecting to the remote machine over SSH. -Note that the SSH key pair must @emph{not} be passphrase-protected, to allow -non-interactive logins. - -@item host-key -This must be the machine's SSH @dfn{public host key} in OpenSSH format. -This is used to authenticate the machine when we connect to it. It is a -long string that looks like this: - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org -@end example - -If the machine is running the OpenSSH daemon, @command{sshd}, the host key -can be found in a file such as @file{/etc/ssh/ssh_host_ed25519_key.pub}. - -If the machine is running the SSH daemon of GNU@tie{}lsh, @command{lshd}, -the host key is in @file{/etc/lsh/host-key.pub} or a similar file. It can -be converted to the OpenSSH format using @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 - -A number of optional fields may be specified: - -@table @asis - -@item @code{port} (default: @code{22}) -Port number of SSH server on the machine. - -@item @code{private-key} (default: @file{~root/.ssh/id_rsa}) -The SSH private key file to use when connecting to the machine, in OpenSSH -format. This key must not be protected with a passphrase. - -Note that the default value is the private key @emph{of the root account}. -Make sure it exists if you use the default. - -@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (default: @code{3}) -The SSH-level compression methods and compression level requested. - -Note that offloading relies on SSH compression to reduce bandwidth usage -when transferring files to and from build machines. - -@item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"}) -File name of the Unix-domain socket @command{guix-daemon} is listening to on -that machine. - -@item @code{parallel-builds} (default: @code{1}) -The number of builds that may run in parallel on the machine. - -@item @code{speed} (default: @code{1.0}) -A ``relative speed factor''. The offload scheduler will tend to prefer -machines with a higher speed factor. - -@item @code{features} (default: @code{'()}) -A list of strings denoting specific features supported by the machine. An -example is @code{"kvm"} for machines that have the KVM Linux modules and -corresponding hardware support. Derivations can request features by name, -and they will be scheduled on matching build machines. - -@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 - -There is one last thing to do once @file{machines.scm} is in place. As -explained above, when offloading, files are transferred back and forth -between the machine stores. For this to work, you first need to generate a -key pair on each machine to allow the daemon to export signed archives of -files from the store (@pxref{Invoking guix archive}): - -@example -# guix archive --generate-key -@end example - -@noindent -Each build machine must authorize the key of the master machine so that it -accepts store items it receives from the master: - -@example -# guix archive --authorize < master-public-key.txt -@end example - -@noindent -Likewise, the master machine must authorize the key of each build machine. - -All the fuss with keys is here to express pairwise mutual trust relations -between the master and the build machines. Concretely, when the master -receives files from a build machine (and @i{vice versa}), its build daemon -can make sure they are genuine, have not been tampered with, and that they -are signed by an authorized key. - -@cindex offload test -To test whether your setup is operational, run this command on the master -node: - -@example -# guix offload test -@end example - -This will attempt to connect to each of the build machines specified in -@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are -available on each machine, attempt to export to the machine and import from -it, and report any error in the process. - -If you want to test a different machine file, just specify it on the command -line: - -@example -# guix offload test machines-qualif.scm -@end example - -Last, you can test the subset of the machines whose name matches a regular -expression like this: - -@example -# guix offload test machines.scm '\.gnu\.org$' -@end example - -@cindex offload status -To display the current load of all build hosts, run this command on the main -node: - -@example -# guix offload status -@end example - - -@node SELinux Support -@subsection SELinux Support - -@cindex SELinux, daemon policy -@cindex mandatory access control, SELinux -@cindex security, 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 Installing the SELinux policy -@cindex SELinux, policy installation -To install the policy run this command as root: - -@example -semodule -i etc/guix-daemon.cil -@end example - -Then relabel the file system with @code{restorecon} or by a different -mechanism provided by your system. - -Once the policy is installed, the file system has been relabeled, and the -daemon has been restarted, it should be running in the @code{guix_daemon_t} -context. You can confirm this with the following command: - -@example -ps -Zax | grep guix-daemon -@end example - -Monitor the SELinux log files as you run a command like @code{guix build -hello} to convince yourself that SELinux permits all necessary operations. - -@subsubsection Limitations -@cindex SELinux, limitations - -This policy is not perfect. Here is a list of limitations or quirks that -should be considered when deploying the provided SELinux policy for the Guix -daemon. - -@enumerate -@item -@code{guix_daemon_socket_t} isn’t actually used. None of the socket -operations involve contexts that have anything to do with -@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label, but -it would be preferrable to define socket rules for only this label. - -@item -@code{guix gc} cannot access arbitrary links to profiles. By design, the -file label of the destination of a symlink is independent of the file label -of the link itself. Although all profiles under $localstatedir are -labelled, the links to these profiles inherit the label of the directory -they are in. For links in the user’s home directory this will be -@code{user_home_t}. But for links from the root user’s home directory, or -@file{/tmp}, or the HTTP server’s working directory, etc, this won’t work. -@code{guix gc} would be prevented from reading and following these links. - -@item -The daemon’s feature to listen for TCP connections might no longer work. -This might require extra rules, because SELinux treats network sockets -differently from files. - -@item -Currently all files with a name matching the regular expression -@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the -label @code{guix_daemon_exec_t}; this means that @emph{any} file with that -name in any profile would be permitted to run in the @code{guix_daemon_t} -domain. This is not ideal. An attacker could build a package that provides -this executable and convince a user to install and run it, which lifts it -into the @code{guix_daemon_t} domain. At that point SELinux could not -prevent it from accessing files that are allowed for processes in that -domain. - -We could generate a much more restrictive policy at installation time, so -that only the @emph{exact} file name of the currently installed -@code{guix-daemon} executable would be labelled with -@code{guix_daemon_exec_t}, instead of using a broad regular expression. The -downside is that root would have to install or upgrade the policy at -installation time whenever the Guix package that provides the effectively -running @code{guix-daemon} executable is upgraded. -@end enumerate - -@node Invoking guix-daemon -@section Invoking @command{guix-daemon} - -The @command{guix-daemon} program implements all the functionality to access -the store. This includes launching build processes, running the garbage -collector, querying the availability of a build result, etc. It is normally -run as @code{root} like this: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -For details on how to set it up, @pxref{Setting Up the Daemon}. - -@cindex chroot -@cindex container, build environment -@cindex build environment -@cindex reproducible builds -By default, @command{guix-daemon} launches build processes under different -UIDs, taken from the build group specified with @code{--build-users-group}. -In addition, each build process is run in a chroot environment that only -contains the subset of the store that the build process depends on, as -specified by its derivation (@pxref{Programming Interface, derivation}), -plus a set of specific system directories. By default, the latter contains -@file{/dev} and @file{/dev/pts}. Furthermore, on GNU/Linux, the build -environment is a @dfn{container}: in addition to having its own file system -tree, it has a separate mount name space, its own PID name space, network -name space, etc. This helps achieve reproducible builds (@pxref{Features}). - -When the daemon performs a build on behalf of the user, it creates a build -directory under @file{/tmp} or under the directory specified by its -@code{TMPDIR} environment variable. This directory is shared with the -container for the duration of the build, though within the container, the -build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}. - -The build directory is automatically deleted upon completion, unless the -build failed and the client specified @option{--keep-failed} -(@pxref{Invoking guix build, @option{--keep-failed}}). - -The daemon listens for connections and spawns one sub-process for each -session started by a client (one of the @command{guix} sub-commands.) The -@command{guix processes} command allows you to get an overview of the -activity on your system by viewing each of the active sessions and clients. -@xref{Invoking guix processes}, for more information. - -The following command-line options are supported: - -@table @code -@item --build-users-group=@var{group} -Take users from @var{group} to run build processes (@pxref{Setting Up the -Daemon, build users}). - -@item --no-substitutes -@cindex substitutes -Do not use substitutes for build products. That is, always build things -locally instead of allowing downloads of pre-built binaries -(@pxref{Substitutes}). - -When the daemon runs with @code{--no-substitutes}, clients can still -explicitly enable substitution @i{via} the @code{set-build-options} remote -procedure call (@pxref{The 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. - -This means that substitutes may be downloaded from @var{urls}, as long as -they are signed by a trusted signature (@pxref{Substitutes}). - -@cindex build hook -@item --no-build-hook -Do not use the @dfn{build hook}. - -The build hook is a helper program that the daemon can start and to which it -submits build requests. This mechanism is used to offload builds to other -machines (@pxref{Daemon Offload Setup}). - -@item --cache-failures -Cache build failures. By default, only successful builds are cached. - -When this option is used, @command{guix gc --list-failures} can be used to -query the set of store items marked as failed; @command{guix gc ---clear-failures} removes store items from the set of cached failures. -@xref{Invoking guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -Use @var{n} CPU cores to build each derivation; @code{0} means as many as -available. - -The default value is @code{0}, but it may be overridden by clients, such as -the @code{--cores} option of @command{guix build} (@pxref{Invoking guix -build}). - -The effect is to define the @code{NIX_BUILD_CORES} environment variable in -the build process, which can then use it to exploit internal -parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Allow at most @var{n} build jobs in parallel. The default value is -@code{1}. Setting it to @code{0} means that no builds will be performed -locally; instead, the daemon will offload builds (@pxref{Daemon Offload -Setup}), or simply fail. - -@item --max-silent-time=@var{seconds} -When the build or substitution process remains silent for more than -@var{seconds}, terminate it and report a build failure. - -The default value is @code{0}, which disables the timeout. - -The value specified here can be overridden by clients (@pxref{Common Build -Options, @code{--max-silent-time}}). - -@item --timeout=@var{seconds} -Likewise, when the build or substitution process lasts for more than -@var{seconds}, terminate it and report a build failure. - -The default value is @code{0}, which disables the timeout. - -The value specified here can be overridden by clients (@pxref{Common Build -Options, @code{--timeout}}). - -@item --rounds=@var{N} -Build each derivation @var{n} times in a row, and raise an error if -consecutive build results are not bit-for-bit identical. Note that this -setting can be overridden by clients such as @command{guix build} -(@pxref{Invoking guix build}). - -When used in conjunction with @option{--keep-failed}, the differing output -is kept in the store, under @file{/gnu/store/@dots{}-check}. This makes it -easy to look for differences between the two results. - -@item --debug -Produce debugging output. - -This is useful to debug daemon start-up issues, but then it may be -overridden by clients, for example the @code{--verbosity} option of -@command{guix build} (@pxref{Invoking guix build}). - -@item --chroot-directory=@var{dir} -Add @var{dir} to the build chroot. - -Doing this may change the result of build processes---for instance if they -use optional dependencies found in @var{dir} when it is available, and not -otherwise. For that reason, it is not recommended to do so. Instead, make -sure that each derivation declares all the inputs that it needs. - -@item --disable-chroot -Disable chroot builds. - -Using this option is not recommended since, again, it would allow build -processes to gain access to undeclared dependencies. It is necessary, -though, when @command{guix-daemon} is running under an unprivileged user -account. - -@item --log-compression=@var{type} -Compress build logs according to @var{type}, one of @code{gzip}, -@code{bzip2}, or @code{none}. - -Unless @code{--lose-logs} is used, all the build logs are kept in the -@var{localstatedir}. To save space, the daemon automatically compresses -them with bzip2 by default. - -@item --disable-deduplication -@cindex deduplication -Disable automatic file ``deduplication'' in the store. - -By default, files added to the store are automatically ``deduplicated'': if -a newly added file is identical to another one found in the store, the -daemon makes the new file a hard link to the other file. This can -noticeably reduce disk usage, at the expense of slightly increased -input/output load at the end of a build process. This option disables this -optimization. - -@item --gc-keep-outputs[=yes|no] -Tell whether the garbage collector (GC) must keep outputs of live -derivations. - -@cindex GC roots -@cindex garbage collector roots -When set to ``yes'', the GC will keep the outputs of any live derivation -available in the store---the @code{.drv} files. The default is ``no'', -meaning that derivation outputs are kept only if they are reachable from a -GC root. @xref{Invoking guix gc}, for more on GC roots. - -@item --gc-keep-derivations[=yes|no] -Tell whether the garbage collector (GC) must keep derivations corresponding -to live outputs. - -When set to ``yes'', as is the case by default, the GC keeps -derivations---i.e., @code{.drv} files---as long as at least one of their -outputs is live. This allows users to keep track of the origins of items in -their store. Setting it to ``no'' saves a bit of disk space. - -In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness -to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to -``yes'' causes liveness to flow from derivations to outputs. When both are -set to ``yes'', the effect is to keep all the build prerequisites (the -sources, compiler, libraries, and other build-time tools) of live objects in -the store, regardless of whether these prerequisites are reachable from a GC -root. This is convenient for developers since it saves rebuilds or -downloads. - -@item --impersonate-linux-2.6 -On Linux-based systems, impersonate Linux 2.6. This means that the kernel's -@code{uname} system call will report 2.6 as the release number. - -This might be helpful to build programs that (usually wrongfully) depend on -the kernel version number. - -@item --lose-logs -Do not keep build logs. By default they are kept under -@code{@var{localstatedir}/guix/log}. - -@item --system=@var{system} -Assume @var{system} as the current system type. By default it is the -architecture/kernel pair found at configure time, such as -@code{x86_64-linux}. - -@item --listen=@var{endpoint} -Listen for connections on @var{endpoint}. @var{endpoint} is interpreted as -the file name of a Unix-domain socket if it starts with @code{/} (slash -sign). Otherwise, @var{endpoint} is interpreted as a host name or host name -and port to listen to. Here are a few examples: - -@table @code -@item --listen=/gnu/var/daemon -Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket, -creating it if needed. - -@item --listen=localhost -@cindex daemon, remote access -@cindex remote access to the daemon -@cindex daemon, cluster setup -@cindex clusters, daemon setup -Listen for TCP connections on the network interface corresponding to -@code{localhost}, on port 44146. - -@item --listen=128.0.0.42:1234 -Listen for TCP connections on the network interface corresponding to -@code{128.0.0.42}, on port 1234. -@end table - -This option can be repeated multiple times, in which case -@command{guix-daemon} accepts connections on all the specified endpoints. -Users can tell client commands what endpoint to connect to by setting the -@code{GUIX_DAEMON_SOCKET} environment variable (@pxref{The Store, -@code{GUIX_DAEMON_SOCKET}}). - -@quotation Note -The daemon protocol is @emph{unauthenticated and unencrypted}. Using -@code{--listen=@var{host}} is suitable on local networks, such as clusters, -where only trusted nodes may connect to the build daemon. In other cases -where remote access to the daemon is needed, we recommend using Unix-domain -sockets along with SSH. -@end quotation - -When @code{--listen} is omitted, @command{guix-daemon} listens for -connections on the Unix-domain socket located at -@file{@var{localstatedir}/guix/daemon-socket/socket}. -@end table - - -@node Application Setup -@section Application Setup - -@cindex foreign distro -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 -Packages installed @i{via} Guix will not use the locale data of the host -system. Instead, you must first install one of the locale packages -available with Guix and then define the @code{GUIX_LOCPATH} environment -variable: - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Note that the @code{glibc-locales} package contains data for all the locales -supported by the GNU@tie{}libc and weighs in at around 110@tie{}MiB. -Alternatively, the @code{glibc-utf8-locales} is smaller but limited to a few -UTF-8 locales. - -The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH} -(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference -Manual}). There are two important differences though: - -@enumerate -@item -@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc -provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you to -make sure the programs of the foreign distro will not end up loading -incompatible locale data. - -@item -libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where -@code{X.Y} is the libc version---e.g., @code{2.22}. This means that, should -your Guix profile contain a mixture of programs linked against different -libc version, each libc version will only try to load locale data in the -right format. -@end enumerate - -This is important because the locale data format used by different libc -versions may be incompatible. - -@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) -When using Guix on a foreign distro, we @emph{strongly recommend} that the -system run the GNU C library's @dfn{name service cache daemon}, -@command{nscd}, which should be listening on the @file{/var/run/nscd/socket} -socket. Failing to do that, applications installed with Guix may fail to -look up host names or user accounts, or may even crash. The next paragraphs -explain why. - -@cindex @file{nsswitch.conf} -The GNU C library implements a @dfn{name service switch} (NSS), which is an -extensible mechanism for ``name lookups'' in general: host name resolution, -user accounts, and more (@pxref{Name Service Switch,,, libc, The GNU C -Library Reference Manual}). - -@cindex Network information service (NIS) -@cindex NIS (Network information service) -Being extensible, the NSS supports @dfn{plugins}, which provide new name -lookup implementations: for example, the @code{nss-mdns} plugin allow -resolution of @code{.local} host names, the @code{nis} plugin allows user -account lookup using the Network information service (NIS), and so on. -These extra ``lookup services'' are configured system-wide in -@file{/etc/nsswitch.conf}, and all the programs running on the system honor -those settings (@pxref{NSS Configuration File,,, libc, The GNU C Reference -Manual}). - -When they perform a name lookup---for instance by calling the -@code{getaddrinfo} function in C---applications first try to connect to the -nscd; on success, nscd performs name lookups on their behalf. If the nscd -is not running, then they perform the name lookup by themselves, by loading -the name lookup services into their own address space and running it. These -name lookup services---the @file{libnss_*.so} files---are @code{dlopen}'d, -but they may come from the host system's C library, rather than from the C -library the application is linked against (the C library coming from Guix). - -And this is where the problem is: if your application is linked against -Guix's C library (say, glibc 2.24) and tries to load NSS plugins from -another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will -likely crash or have its name lookups fail unexpectedly. - -Running @command{nscd} on the system, among other advantages, eliminates -this binary incompatibility problem because those @code{libnss_*.so} files -are loaded in the @command{nscd} process, not in applications themselves. - -@subsection X11 Fonts - -@cindex fonts -The majority of graphical applications use Fontconfig to locate and load -fonts and perform X11-client-side rendering. The @code{fontconfig} package -in Guix looks for fonts in @file{$HOME/.guix-profile} by default. Thus, to -allow graphical applications installed with Guix to display fonts, you have -to install fonts with Guix as well. Essential font packages include -@code{gs-fonts}, @code{font-dejavu}, and @code{font-gnu-freefont-ttf}. - -To display text written in Chinese languages, Japanese, or Korean in -graphical applications, consider installing -@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former has -multiple outputs, one per language family (@pxref{Packages with Multiple -Outputs}). For instance, the following command installs fonts for Chinese -languages: - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Older programs such as @command{xterm} do not use Fontconfig and instead -rely on server-side font rendering. Such programs require to specify a full -name of a font using XLFD (X Logical Font Description), like this: - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -To be able to use such full names for the TrueType fonts installed in your -Guix profile, you need to extend the font path of the X server: - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See . -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -After that, you can run @code{xlsfonts} (from @code{xlsfonts} package) to -make sure your TrueType fonts are listed there. - -@cindex @code{fc-cache} -@cindex font cache -After installing fonts you may have to refresh the font cache to use them in -applications. The same applies when applications installed via Guix do not -seem to find fonts. To force rebuilding of the font cache run -@code{fc-cache -f}. The @code{fc-cache} command is provided by the -@code{fontconfig} package. - -@subsection X.509 Certificates - -@cindex @code{nss-certs} -The @code{nss-certs} package provides X.509 certificates, which allow -programs to authenticate Web servers accessed over HTTPS. - -When using Guix on a foreign distro, you can install this package and define -the relevant environment variables so that packages know where to look for -certificates. @xref{X.509 Certificates}, for detailed information. - -@subsection Emacs Packages - -@cindex @code{emacs} -When you install Emacs packages with Guix, the elisp files may be placed -either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in -sub-directories of -@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter -directory exists because potentially there may exist thousands of Emacs -packages and storing all their files in a single directory may not be -reliable (because of name conflicts). So we think using a separate -directory for each package is a good idea. It is very similar to how the -Emacs package system organizes the file structure (@pxref{Package Files,,, -emacs, The GNU Emacs Manual}). - -By default, Emacs (installed with Guix) ``knows'' where these packages are -placed, so you do not need to perform any configuration. If, for some -reason, you want to avoid auto-loading Emacs packages installed with Guix, -you can do so by running Emacs with @code{--no-site-file} option -(@pxref{Init File,,, emacs, The GNU Emacs Manual}). - -@subsection The GCC toolchain - -@cindex GCC -@cindex ld-wrapper - -Guix offers individual compiler packages such as @code{gcc} but if you are -in need of a complete toolchain for compiling and linking source code what -you really want is the @code{gcc-toolchain} package. This package provides -a complete GCC toolchain for C/C++ development, including GCC itself, the -GNU C Library (headers and binaries, plus debugging symbols in the -@code{debug} output), Binutils, and a linker wrapper. - -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 System Installation -@chapter System Installation - -@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 Note -@c This paragraph is for people reading this from tty2 of the -@c installation image. -You are reading this documentation with an Info reader. For details on how -to use it, hit the @key{RET} key (``return'' or ``enter'') on the link that -follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU Info}. Hit -@kbd{l} afterwards to come back here. - -Alternately, run @command{info info} in another tty to keep the manual -available. -@end quotation -@end ifinfo - -@menu -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Guided Graphical Installation:: Easy graphical installation. -* Manual Installation:: Manual installation for wizards. -* After System Installation:: When installation succeeded. -* Installing Guix in a VM:: Guix System playground. -* Building the Installation Image:: How this comes to be. -@end menu - -@node Limitations -@section Limitations - -We consider Guix System to be ready for a wide range of ``desktop'' and -server use cases. The reliability guarantees it provides---transactional -upgrades and rollbacks, reproducibility---make it a solid foundation. - -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -Support for the Logical Volume Manager (LVM) is missing. - -@item -More and more system services are provided (@pxref{Services}), but some may -be missing. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop -Services}), as well as a number of X11 window managers. However, KDE is -currently missing. -@end itemize - -More than a disclaimer, this is an invitation to report issues (and success -stories!), and to join us in improving it. @xref{贡献}, for more -info. - - -@node Hardware Considerations -@section Hardware Considerations - -@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 WiFi, hardware support -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 @code{%base-firmware} (@pxref{operating-system Reference, -@code{firmware}}). - -@cindex RYF, Respects Your Freedom -The @uref{https://www.fsf.org/, Free Software Foundation} runs -@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a -certification program for hardware products that respect your freedom and -your privacy and ensure that you have control over your device. We -encourage you to check the list of RYF-certified devices. - -Another useful resource is the @uref{https://www.h-node.org/, H-Node} web -site. It contains a catalog of hardware devices with information about -their support in GNU/Linux. - - -@node USB Stick and DVD Installation -@section USB Stick and DVD Installation - -An ISO-9660 installation image that can be written to a USB stick or burnt -to a DVD can be downloaded from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, -where @var{system} is one of: - -@table @code -@item x86_64-linux -for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs; - -@item i686-linux -for a 32-bit GNU/Linux system on Intel-compatible CPUs. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the image against it, along these lines: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -@end example - -If that command fails because you do not have the required public key, then -run this command to import it: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -and rerun the @code{gpg --verify} command. - -This image contains the tools necessary for an installation. It is meant to -be copied @emph{as is} to a large-enough USB stick or DVD. - -@unnumberedsubsec Copying to a USB Stick - -To copy the image to a USB stick, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a USB stick of 1@tie{}GiB or more into your machine, and determine -its device name. Assuming that the USB stick is known as @file{/dev/sdX}, -copy the image with: - -@example -dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX -sync -@end example - -Access to @file{/dev/sdX} usually requires root privileges. -@end enumerate - -@unnumberedsubsec Burning on a DVD - -To copy the image to a DVD, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a blank DVD into your machine, and determine its device name. -Assuming that the DVD drive is known as @file{/dev/srX}, copy the image -with: - -@example -growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso -@end example - -Access to @file{/dev/srX} usually requires root privileges. -@end enumerate - -@unnumberedsubsec Booting - -Once this is done, you should be able to reboot the system and boot from the -USB stick or DVD. The latter usually requires you to get in the BIOS or -UEFI boot menu, where you can choose to boot from the USB stick. - -@xref{Installing Guix in a VM}, if, instead, you would like to install Guix -System in a virtual machine (VM). - - -@node Preparing for Installation -@section Preparing for Installation - -Once you have booted, you can use the guided graphical installer, which -makes it easy to get started (@pxref{Guided Graphical Installation}). -Alternately, if you are already familiar with GNU/Linux and if you want more -control than what the graphical installer provides, you can choose the -``manual'' installation process (@pxref{Manual Installation}). - -The graphical installer is available on TTY1. You can obtain root shells on -TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 -shows this documentation and you can reach it with @kbd{ctrl-alt-f2}. -Documentation is 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 Note -Installation requires access to the Internet so that any missing -dependencies of your system configuration can be downloaded. See the -``Networking'' section below. -@end quotation - -@node Guided Graphical Installation -@section Guided Graphical Installation - -The graphical installer is a text-based user interface. It will guide you, -with dialog boxes, through the steps needed to install GNU@tie{}Guix System. - -The first dialog boxes allow you to set up the system as you use it during -the installation: you can choose the language, keyboard layout, and set up -networking, which will be used during the installation. The image below -shows the networking dialog. - -@image{images/installer-network,5in,, networking setup with the graphical -installer} - -Later steps allow you to partition your hard disk, as shown in the image -below, to choose whether or not to use encrypted file systems, to enter the -host name and root password, and to create an additional account, among -other things. - -@image{images/installer-partitions,5in,, partitioning with the graphical -installer} - -Note that, at any time, the installer allows you to exit the current -installation step and resume at a previous step, as show in the image below. - -@image{images/installer-resume,5in,, resuming the installation process} - -Once you're done, the installer produces an operating system configuration -and displays it (@pxref{Using the Configuration System}). At that point you -can hit ``OK'' and installation will proceed. On success, you can reboot -into the new system and enjoy. @xref{After System Installation}, for what's -next! - - -@node Manual Installation -@section Manual Installation - -This section describes how you would ``manually'' install GNU@tie{}Guix -System on your machine. This option requires familiarity with GNU/Linux, -with the shell, and with common administration tools. If you think this is -not for you, consider using the guided graphical installer (@pxref{Guided -Graphical Installation}). - -The installation system provides root shells on TTYs 3 to 6; press -@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes -many common tools needed to install the system. 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{Invoking guix package}). - -@menu -* Keyboard Layout and Networking and Partitioning:: Initial setup. -* Proceeding with the Installation:: Installing. -@end menu - -@node Keyboard Layout and Networking and Partitioning -@subsection Keyboard Layout, Networking, and Partitioning - -Before you can install the system, you may want to adjust the keyboard -layout, set up networking, and partition your target hard disk. This -section will guide you through this. - -@subsubsection Keyboard Layout - -@cindex keyboard layout -The installation image uses the US qwerty keyboard layout. If you want to -change it, you can use the @command{loadkeys} command. For example, the -following command selects the Dvorak keyboard layout: - -@example -loadkeys dvorak -@end example - -See the files under @file{/run/current-system/profile/share/keymaps} for a -list of available keyboard layouts. Run @command{man loadkeys} for more -information. - -@subsubsection Networking - -Run the following command to see what your network interfaces are called: - -@example -ifconfig -a -@end example - -@noindent -@dots{} or, using the GNU/Linux-specific @command{ip} command: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Wired interfaces have a name starting with @samp{e}; for example, the -interface corresponding to the first on-board Ethernet controller is called -@samp{eno1}. Wireless interfaces have a name starting with @samp{w}, like -@samp{w1p2s0}. - -@table @asis -@item Wired connection -To configure a wired network run the following command, substituting -@var{interface} with the name of the wired interface you want to use. - -@example -ifconfig @var{interface} up -@end example - -@item Wireless connection -@cindex wireless -@cindex WiFi -To configure wireless networking, you can create a configuration file for -the @command{wpa_supplicant} configuration tool (its location is not -important) using one of the available text editors such as @command{nano}: - -@example -nano wpa_supplicant.conf -@end example - -As an example, the following stanza can go to this file and will work for -many wireless networks, provided you give the actual SSID and passphrase for -the network you are connecting to: - -@example -network=@{ - ssid="@var{my-ssid}" - key_mgmt=WPA-PSK - psk="the network's secret passphrase" -@} -@end example - -Start the wireless service and run it in the background with the following -command (substitute @var{interface} with the name of the network interface -you want to use): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B -@end example - -Run @command{man wpa_supplicant} for more information. -@end table - -@cindex DHCP -At this point, you need to acquire an IP address. On a network where IP -addresses are automatically assigned @i{via} DHCP, you can run: - -@example -dhclient -v @var{interface} -@end example - -Try to ping a server to see if networking is up and running: - -@example -ping -c 3 gnu.org -@end example - -Setting up network access is almost always a requirement because the image -does not contain all the software and tools that may be needed. - -@cindex installing over SSH -If you want to, you can continue the installation remotely by starting an -SSH server: - -@example -herd start ssh-daemon -@end example - -Make sure to either set a password with @command{passwd}, or configure -OpenSSH public key authentication before logging in. - -@subsubsection Disk Partitioning - -Unless this has already been done, the next step is to partition, and then -format the target partition(s). - -The installation image includes several partitioning tools, including Parted -(@pxref{Overview,,, parted, GNU Parted User Manual}), @command{fdisk}, and -@command{cfdisk}. Run it and set up your disk with the partition layout you -want: - -@example -cfdisk -@end example - -If your disk uses the GUID Partition Table (GPT) format and you plan to -install BIOS-based GRUB (which is the default), make sure a BIOS Boot -Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB manual}). - -@cindex EFI, installation -@cindex UEFI, installation -@cindex ESP, EFI system partition -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 Note -@vindex grub-bootloader -@vindex grub-efi-bootloader -Unsure whether to use EFI- or BIOS-based GRUB? If the directory -@file{/sys/firmware/efi} exists in the installation image, then you should -probably perform an EFI installation, using @code{grub-efi-bootloader}. -Otherwise you should use the BIOS-based GRUB, known as -@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on -bootloaders. -@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 - -Preferably, assign file systems a label so that you can easily and reliably -refer to them in @code{file-system} declarations (@pxref{File Systems}). -This is typically done using the @code{-L} option of @command{mkfs.ext4} and -related commands. So, assuming the target root partition lives at -@file{/dev/sda2}, a file system with the label @code{my-root} can be created -with: - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex encrypted disk -If you are instead planning to encrypt the root partition, you can use the -Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, -@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, -@code{man cryptsetup}} for more information.) Assuming you want to store -the root partition on @file{/dev/sda2}, the command sequence would be along -these lines: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Once that is done, mount the target file system under @file{/mnt} with a -command like (again, assuming @code{my-root} is the label of the root file -system): - -@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. - -Finally, if you plan to use one or more swap partitions (@pxref{Memory -Concepts, swap space,, libc, The GNU C Library Reference Manual}), make sure -to initialize them with @command{mkswap}. Assuming you have one swap -partition on @file{/dev/sda3}, you would run: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Alternatively, you may use a swap file. For example, assuming that in the -new system you want to use the file @file{/swapfile} as a swap file, you -would run@footnote{This example will work for many types of file systems -(e.g., ext4). However, for copy-on-write file systems (e.g., btrfs), the -required steps may be different. For details, see the manual pages for -@command{mkswap} and @command{swapon}.}: - -@example -# This is 10 GiB of swap space. Adjust "count" to change the size. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# For security, make the file readable and writable only by root. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Note that if you have encrypted the root partition and created a swap file -in its file system as described above, then the encryption also protects the -swap file, just like any other file in that file system. - -@node Proceeding with the Installation -@subsection Proceeding with the Installation - -With the target partitions ready and the target root mounted on @file{/mnt}, -we're ready to go. First, run: - -@example -herd start cow-store /mnt -@end example - -This makes @file{/gnu/store} copy-on-write, such that packages added to it -during the installation phase are written to the target disk on @file{/mnt} -rather than kept in memory. This is necessary because the first phase of -the @command{guix system init} command (see below) entails downloads or -builds to @file{/gnu/store} which, initially, is an in-memory file system. - -Next, you have to edit a file and provide the declaration of the operating -system to be installed. To that end, the installation system comes with -three text editors. We recommend GNU nano (@pxref{Top,,, nano, GNU nano -Manual}), which supports syntax highlighting and parentheses matching; other -editors include GNU Zile (an Emacs clone), and nvi (a clone of the original -BSD @command{vi} editor). We strongly recommend storing that file on the -target root file system, say, as @file{/mnt/etc/config.scm}. Failing to do -that, you will have lost your configuration file once you have rebooted into -the newly-installed system. - -@xref{Using the Configuration System}, for an overview of the configuration -file. The example configurations discussed in that section are available -under @file{/etc/configuration} in the installation image. Thus, to get -started with a system configuration providing a graphical display server (a -``desktop'' system), you can run something along these lines: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -You should pay attention to what your configuration file contains, and in -particular: - -@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 -Be sure that your file system labels match the value of their respective -@code{device} fields in your @code{file-system} configuration, assuming your -@code{file-system} configuration uses the @code{file-system-label} procedure -in its @code{device} field. - -@item -If there are encrypted or RAID partitions, make sure to add a -@code{mapped-devices} field to describe them (@pxref{Mapped Devices}). -@end itemize - -Once you are done preparing the configuration file, the new system must be -initialized (remember that the target root file system is mounted under -@file{/mnt}): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -This copies all the necessary files and installs GRUB on @file{/dev/sdX}, -unless you pass the @option{--no-bootloader} option. For more information, -@pxref{Invoking guix system}. This command may trigger downloads or builds -of missing packages, which can take some time. - -Once that command has completed---and hopefully succeeded!---you can run -@command{reboot} and boot into the new system. The @code{root} password in -the new system is initially empty; other users' passwords need to be -initialized by running the @command{passwd} command as @code{root}, unless -your configuration specifies otherwise (@pxref{user-account-password, user -account passwords}). @xref{After System Installation}, for what's next! - - -@node After System Installation -@section After System Installation - -Success, you've now booted into 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{Invoking guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Security Updates}). - -@c See . -@quotation Note -@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! - - -@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{USB Stick and DVD Installation}). - -@item -Create a disk image that will hold the installed system. To make a -qcow2-formatted disk image, use the @command{qemu-img} command: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -The resulting file will be much smaller than 50 GB (typically less than 1 -MB), but it will grow as the virtualized storage device is filled up. - -@item -Boot the USB installation image in an VM: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guix-system-install-@value{VERSION}.@var{system}.iso \ - -drive file=guixsd.img -@end example - -The ordering of the drives matters. - -In the VM console, quickly press the @kbd{F12} key to enter the boot menu. -Then press the @kbd{2} key and the @kbd{RET} key to validate your selection. - -@item -You're now root in the VM, proceed with the installation process. -@xref{Preparing for Installation}, and follow the instructions. -@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 Building the Installation Image -@section Building the Installation Image - -@cindex installation image -The installation image described above was built using the @command{guix -system} command, specifically: - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Have a look at @file{gnu/system/install.scm} in the source tree, and see -also @ref{Invoking guix system} for more information about the installation -image. - -@section Building the Installation Image for ARM Boards - -Many ARM boards require a specific variant of the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. - -If you build a disk image and the bootloader is not available otherwise (on -another boot drive etc), it's advisable to build an image that includes the -bootloader, specifically: - -@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} is the name of the board. If you specify an -invalid board, a list of possible boards will be printed. - -@c ********************************************************************* -@node Package Management -@chapter Package Management - -@cindex packages -The purpose of GNU Guix is to allow users to easily install, upgrade, and -remove software packages, without having to know about their build -procedures or dependencies. Guix also goes beyond this obvious set of -features. - -This chapter describes the main features of Guix, as well as the package -management tools it provides. Along with the command-line interface -described below (@pxref{Invoking guix package, @code{guix package}}), you -may also use the Emacs-Guix interface (@pxref{Top,,, emacs-guix, The -Emacs-Guix Reference Manual}), after installing @code{emacs-guix} package -(run @kbd{M-x guix-help} command to start with it): - -@example -guix package -i emacs-guix -@end example - -@menu -* Features:: How Guix will make your life brighter. -* Invoking guix package:: Package installation, removal, etc. -* Substitutes:: Downloading pre-built binaries. -* Packages with Multiple Outputs:: Single source package, multiple outputs. -* Invoking guix gc:: Running the garbage collector. -* Invoking guix pull:: Fetching the latest Guix and distribution. -* Channels:: Customizing the package collection. -* Inferiors:: Interacting with another revision of Guix. -* Invoking guix describe:: Display information about your Guix revision. -* Invoking guix archive:: Exporting and importing store files. -@end menu - -@node Features -@section Features - -When using Guix, each package ends up in the @dfn{package store}, in its own -directory---something that resembles @file{/gnu/store/xxx-package-1.2}, -where @code{xxx} is a base32 string. - -Instead of referring to these directories, users have their own -@dfn{profile}, which points to the packages that they actually want to use. -These profiles are stored within each user's home directory, at -@code{$HOME/.guix-profile}. - -For example, @code{alice} installs GCC 4.7.2. As a result, -@file{/home/alice/.guix-profile/bin/gcc} points to -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, -@code{bob} had already installed GCC 4.8.0. The profile of @code{bob} -simply continues to point to -@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC -coexist on the same system without any interference. - -The @command{guix package} command is the central tool to manage packages -(@pxref{Invoking guix package}). It operates on the per-user profiles, and -can be used @emph{with normal user privileges}. - -@cindex transactions -The command provides the obvious install, remove, and upgrade operations. -Each invocation is actually a @emph{transaction}: either the specified -operation succeeds, or nothing happens. Thus, if the @command{guix package} -process is terminated during the transaction, or if a power outage occurs -during the transaction, then the user's profile remains in its previous -state, and remains usable. - -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{Using the Configuration System}). - -All packages in the package store may be @emph{garbage-collected}. Guix can -determine which packages are still referenced by user profiles, and remove -those that are provably no longer referenced (@pxref{Invoking guix gc}). -Users may also explicitly remove old generations of their profile so that -the packages they refer to can be collected. - -@cindex reproducibility -@cindex reproducible builds -Guix takes a @dfn{purely functional} approach to package management, as -described in the introduction (@pxref{Introduction}). Each -@file{/gnu/store} package directory name contains a hash of all the inputs -that were used to build that package---compiler, libraries, build scripts, -etc. This direct correspondence allows users to make sure a given package -installation matches the current state of their distribution. It also helps -maximize @dfn{build reproducibility}: thanks to the isolated build -environments that are used, a given build is likely to yield bit-identical -files when performed on different machines (@pxref{Invoking guix-daemon, -container}). - -@cindex substitutes -This foundation allows Guix to support @dfn{transparent binary/source -deployment}. When a pre-built binary for a @file{/gnu/store} item is -available from an external source---a @dfn{substitute}, Guix just downloads -it and unpacks it; otherwise, it builds the package from source, locally -(@pxref{Substitutes}). Because build results are usually bit-for-bit -reproducible, users do not have to trust servers that provide substitutes: -they can force a local build and @emph{challenge} providers (@pxref{Invoking -guix challenge}). - -Control over the build environment is a feature that is also useful for -developers. The @command{guix environment} command allows developers of a -package to quickly set up the right development environment for their -package, without having to manually install the dependencies of the package -into their profile (@pxref{Invoking guix environment}). - -@cindex replication, of software environments -@cindex provenance tracking, of software artifacts -All of Guix and its package definitions is version-controlled, and -@command{guix pull} allows you to ``travel in time'' on the history of Guix -itself (@pxref{Invoking guix pull}). This makes it possible to replicate a -Guix instance on a different machine or at a later point in time, which in -turn allows you to @emph{replicate complete software environments}, while -retaining precise @dfn{provenance tracking} of the software. - -@node Invoking guix package -@section Invoking @command{guix package} - -@cindex installing packages -@cindex removing packages -@cindex package installation -@cindex package removal -The @command{guix package} command is the tool that allows users to install, -upgrade, and remove packages, as well as rolling back to previous -configurations. It operates only on the user's own profile, and works with -normal user privileges (@pxref{Features}). Its syntax is: - -@example -guix package @var{options} -@end example -@cindex transactions -Primarily, @var{options} specifies the operations to be performed during the -transaction. Upon completion, a new profile is created, but previous -@dfn{generations} of the profile remain available, should the user want to -roll back. - -For example, to remove @code{lua} and install @code{guile} and -@code{guile-cairo} in a single transaction: - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} also supports a @dfn{declarative approach} whereby -the user specifies the exact set of packages to be available and passes it -@i{via} the @option{--manifest} option (@pxref{profile-manifest, -@option{--manifest}}). - -@cindex profile -For each user, a symlink to the user's default profile is automatically -created in @file{$HOME/.guix-profile}. This symlink always points to the -current generation of the user's default profile. Thus, users can add -@file{$HOME/.guix-profile/bin} to their @code{PATH} environment variable, -and so on. -@cindex search paths -If you are not using the Guix System Distribution, consider adding the -following lines to your @file{~/.bash_profile} (@pxref{Bash Startup Files,,, -bash, The GNU Bash Reference Manual}) so that newly-spawned shells get all -the right environment variable definitions: - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -In a multi-user setup, user profiles are stored in a place registered as a -@dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points to -(@pxref{Invoking guix gc}). That directory is normally -@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where -@var{localstatedir} is the value passed to @code{configure} as -@code{--localstatedir}, and @var{user} is the user name. The -@file{per-user} directory is created when @command{guix-daemon} is started, -and the @var{user} sub-directory is created by @command{guix package}. - -The @var{options} can be among the following: - -@table @code - -@item --install=@var{package} @dots{} -@itemx -i @var{package} @dots{} -Install the specified @var{package}s. - -Each @var{package} may specify either a simple package name, such as -@code{guile}, or a package name followed by an at-sign and version number, -such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter case, -the newest version prefixed by @code{1.8} is selected.) - -If no version number is specified, the newest available version will be -selected. In addition, @var{package} may contain a colon, followed by the -name of one of the outputs of the package, as in @code{gcc:doc} or -@code{binutils@@2.22:lib} (@pxref{Packages with Multiple Outputs}). -Packages with a corresponding name (and optionally version) are searched for -among the GNU distribution modules (@pxref{Package Modules}). - -@cindex propagated inputs -Sometimes packages have @dfn{propagated inputs}: these are dependencies that -automatically get installed along with the required package -(@pxref{package-propagated-inputs, @code{propagated-inputs} in -@code{package} objects}, for information about propagated inputs in package -definitions). - -@anchor{package-cmd-propagated-inputs} -An example is the GNU MPC library: its C header files refer to those of the -GNU MPFR library, which in turn refer to those of the GMP library. Thus, -when installing MPC, the MPFR and GMP libraries also get installed in the -profile; removing MPC also removes MPFR and GMP---unless they had also been -explicitly installed by the user. - -Besides, packages sometimes rely on the definition of environment variables -for their search paths (see explanation of @code{--search-paths} below). -Any missing or possibly incorrect environment variable definitions are -reported here. - -@item --install-from-expression=@var{exp} -@itemx -e @var{exp} -Install the package @var{exp} evaluates to. - -@var{exp} must be a Scheme expression that evaluates to a @code{} -object. This option is notably useful to disambiguate between same-named -variants of a package, with expressions such as @code{(@@ (gnu packages -base) guile-final)}. - -Note that this option installs the first output of the specified package, -which may be insufficient when needing a specific output of a -multiple-output package. - -@item --install-from-file=@var{file} -@itemx -f @var{file} -Install the package that the code within @var{file} evaluates to. - -As an example, @var{file} might contain a definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude package-hello.scm -@end example - -Developers may find it useful to include such a @file{guix.scm} file in the -root of their project source tree that can be used to test development -snapshots and create reproducible development environments (@pxref{Invoking -guix environment}). - -@item --remove=@var{package} @dots{} -@itemx -r @var{package} @dots{} -Remove the specified @var{package}s. - -As for @code{--install}, each @var{package} may specify a version number -and/or output name in addition to the package name. For instance, @code{-r -glibc:debug} would remove the @code{debug} output of @code{glibc}. - -@item --upgrade[=@var{regexp} @dots{}] -@itemx -u [@var{regexp} @dots{}] -@cindex upgrading packages -Upgrade all the installed packages. If one or more @var{regexp}s are -specified, upgrade only installed packages whose name matches a -@var{regexp}. Also see the @code{--do-not-upgrade} option below. - -Note that this upgrades package to the latest version of packages found in -the distribution currently installed. To update your distribution, you -should regularly run @command{guix pull} (@pxref{Invoking guix pull}). - -@item --do-not-upgrade[=@var{regexp} @dots{}] -When used together with the @code{--upgrade} option, do @emph{not} upgrade -any packages whose name matches a @var{regexp}. For example, to upgrade all -packages in the current profile except those containing the substring -``emacs'': - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{file} -@itemx -m @var{file} -@cindex profile declaration -@cindex profile manifest -Create a new generation of the profile from the manifest object returned by -the Scheme code in @var{file}. - -This allows you to @emph{declare} the profile's contents rather than -constructing it through a sequence of @code{--install} and similar -commands. The advantage is that @var{file} can be put under version -control, copied to different machines to reproduce the same profile, and so -on. - -@c FIXME: Add reference to (guix profile) documentation when available. -@var{file} must return a @dfn{manifest} object, which is roughly a list of -packages: - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Use a specific package output. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -In this example we have to know which modules define the @code{emacs} and -@code{guile-2.0} variables to provide the right @code{use-package-modules} -line, which can be cumbersome. We can instead provide regular package -specifications and let @code{specifications->manifest} look up the -corresponding package objects, like this: - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex rolling back -@cindex undoing transactions -@cindex transactions, undoing -Roll back to the previous @dfn{generation} of the profile---i.e., undo the -last transaction. - -When combined with options such as @code{--install}, roll back occurs before -any other actions. - -When rolling back from the first generation that actually contains installed -packages, the profile is made to point to the @dfn{zeroth generation}, which -contains no files apart from its own metadata. - -After having rolled back, installing, removing, or upgrading packages -overwrites previous future generations. Thus, the history of the -generations in a profile is always linear. - -@item --switch-generation=@var{pattern} -@itemx -S @var{pattern} -@cindex generations -Switch to a particular generation defined by @var{pattern}. - -@var{pattern} may be either a generation number or a number prefixed with -``+'' or ``-''. The latter means: move forward/backward by a specified -number of generations. For example, if you want to return to the latest -generation after @code{--roll-back}, use @code{--switch-generation=+1}. - -The difference between @code{--roll-back} and @code{--switch-generation=-1} -is that @code{--switch-generation} will not make a zeroth generation, so if -a specified generation does not exist, the current generation will not be -changed. - -@item --search-paths[=@var{kind}] -@cindex search paths -Report environment variable definitions, in Bash syntax, that may be needed -in order to use the set of installed packages. These environment variables -are used to specify @dfn{search paths} for files used by some of the -installed packages. - -For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH} environment -variables to be defined so it can look for headers and libraries in the -user's profile (@pxref{Environment Variables,,, gcc, Using the GNU Compiler -Collection (GCC)}). If GCC and, say, the C library are installed in the -profile, then @code{--search-paths} will suggest setting these variables to -@code{@var{profile}/include} and @code{@var{profile}/lib}, respectively. - -The typical use case is to define these environment variables in the shell: - -@example -$ eval `guix package --search-paths` -@end example - -@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix}, -meaning that the returned environment variable definitions will either be -exact settings, or prefixes or suffixes of the current value of these -variables. When omitted, @var{kind} defaults to @code{exact}. - -This option can also be used to compute the @emph{combined} search paths of -several profiles. Consider this example: - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -The last command above reports about the @code{GUILE_LOAD_PATH} variable, -even though, taken individually, neither @file{foo} nor @file{bar} would -lead to that recommendation. - - -@item --profile=@var{profile} -@itemx -p @var{profile} -Use @var{profile} instead of the user's default profile. - -@cindex collisions, in a profile -@cindex colliding packages in profiles -@cindex profile collisions -@item --allow-collisions -Allow colliding packages in the new profile. Use at your own risk! - -By default, @command{guix package} reports as an error @dfn{collisions} in -the profile. Collisions happen when two or more different versions or -variants of a given package end up in the profile. - -@item --bootstrap -Use the bootstrap Guile to build the profile. This option is only useful to -distribution developers. - -@end table - -In addition to these actions, @command{guix package} supports the following -options to query the current state of a profile, or the availability of -packages: - -@table @option - -@item --search=@var{regexp} -@itemx -s @var{regexp} -@cindex searching for packages -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}). - -This allows specific fields to be extracted using the @command{recsel} -command, for instance: - -@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 - -Similarly, to show the name of all the packages available under the terms of -the GNU@tie{}LGPL version 3: - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -It is also possible to refine search results using several @code{-s} flags. -For example, the following command returns a list of board games: - -@example -$ guix package -s '\' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -If we were to omit @code{-s game}, we would also get software packages that -deal with printed circuit boards; removing the angle brackets around -@code{board} would further add packages that have to do with keyboards. - -And now for a more elaborate example. The following command searches for -cryptographic libraries, filters out Haskell, Perl, Python, and Ruby -libraries, and prints the name and synopsis of the matching packages: - -@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}, for more -information on @dfn{selection expressions} for @code{recsel -e}. - -@item --show=@var{package} -Show details about @var{package}, taken from the list of available packages, -in @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 - -You may also specify the full name of a package to only get details about a -specific version of it: -@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}] -List the currently installed packages in the specified profile, with the -most recently installed packages shown last. When @var{regexp} is -specified, list only installed packages whose name matches @var{regexp}. - -For each installed package, print the following items, separated by tabs: -the package name, its version string, the part of the package that is -installed (for instance, @code{out} for the default output, @code{include} -for its headers, etc.), and the path of this package in the store. - -@item --list-available[=@var{regexp}] -@itemx -A [@var{regexp}] -List packages currently available in the distribution for this system -(@pxref{GNU Distribution}). When @var{regexp} is specified, list only -installed packages whose name matches @var{regexp}. - -For each package, print the following items separated by tabs: its name, its -version string, the parts of the package (@pxref{Packages with Multiple -Outputs}), and the source location of its definition. - -@item --list-generations[=@var{pattern}] -@itemx -l [@var{pattern}] -@cindex generations -Return a list of generations along with their creation dates; for each -generation, show the installed packages, with the most recently installed -packages shown last. Note that the zeroth generation is never shown. - -For each installed package, print the following items, separated by tabs: -the name of a package, its version string, the part of the package that is -installed (@pxref{Packages with Multiple Outputs}), and the location of this -package in the store. - -When @var{pattern} is used, the command returns only matching generations. -Valid patterns include: - -@itemize -@item @emph{Integers and comma-separated integers}. Both patterns denote -generation numbers. For instance, @code{--list-generations=1} returns the -first one. - -And @code{--list-generations=1,8,2} outputs three generations in the -specified order. Neither spaces nor trailing commas are allowed. - -@item @emph{Ranges}. @code{--list-generations=2..9} prints the -specified generations and everything in between. Note that the start of a -range must be smaller than its end. - -It is also possible to omit the endpoint. For example, -@code{--list-generations=2..}, returns all generations starting from the -second one. - -@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, -or months by passing an integer along with the first letter of the -duration. For example, @code{--list-generations=20d} lists generations that -are up to 20 days old. -@end itemize - -@item --delete-generations[=@var{pattern}] -@itemx -d [@var{pattern}] -When @var{pattern} is omitted, delete all generations except the current -one. - -This command accepts the same patterns as @option{--list-generations}. When -@var{pattern} is specified, delete the matching generations. When -@var{pattern} specifies a duration, generations @emph{older} than the -specified duration match. For instance, @code{--delete-generations=1m} -deletes generations that are more than one month old. - -If the current generation matches, it is @emph{not} deleted. Also, the -zeroth generation is never deleted. - -Note that deleting generations prevents rolling back to them. Consequently, -this command must be used with care. - -@end table - -Finally, since @command{guix package} may actually start build processes, it -supports all the common build options (@pxref{Common Build Options}). It -also supports package transformation options, such as @option{--with-source} -(@pxref{Package Transformation Options}). However, note that package -transformations are lost when upgrading; to preserve transformations across -upgrades, you should define your own package variant in a Guile module and -add it to @code{GUIX_PACKAGE_PATH} (@pxref{Defining Packages}). - -@node Substitutes -@section Substitutes - -@cindex substitutes -@cindex pre-built binaries -Guix supports transparent source/binary deployment, which means that it can -either build things locally, or download pre-built items from a server, or -both. We call these pre-built items @dfn{substitutes}---they are -substitutes for local build results. In many cases, downloading a -substitute is much faster than building things locally. - -Substitutes can be anything resulting from a derivation build -(@pxref{Derivations}). Of course, in the common case, they are pre-built -package binaries, but source tarballs, for instance, which also result from -derivation builds, can be available as substitutes. - -@menu -* Official Substitute Server:: One particular source of substitutes. -* Substitute Server Authorization:: How to enable or disable substitutes. -* Substitute Authentication:: How Guix verifies substitutes. -* Proxy Settings:: How to get substitutes via proxy. -* Substitution Failure:: What happens when substitution fails. -* On Trusting Binaries:: How can you trust that binary blob? -@end menu - -@node Official Substitute Server -@subsection Official Substitute 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}). - -Substitute URLs can be either HTTP or HTTPS. HTTPS is recommended because -communications are encrypted; conversely, using HTTP makes all -communications visible to an eavesdropper, who could use the information -gathered to determine, for instance, whether your system has unpatched -security vulnerabilities. - -Substitutes from the official build farm are enabled by default when using -the Guix System Distribution (@pxref{GNU Distribution}). However, they are -disabled by default when using Guix on a foreign distribution, unless you -have explicitly enabled them via one of the recommended installation steps -(@pxref{Installation}). The following paragraphs describe how to enable or -disable substitutes for the official build farm; the same procedure can also -be used to enable substitutes for any other substitute server. - -@node Substitute Server Authorization -@subsection Substitute Server Authorization - -@cindex security -@cindex substitutes, authorization thereof -@cindex access control list (ACL), for substitutes -@cindex ACL (access control list), for substitutes -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{Invoking 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 Note -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 - -Once this is in place, the output of a command like @code{guix build} should -change from something like: - -@example -$ guix build emacs --dry-run -The following derivations would be built: - /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 -to something like: - -@example -$ guix build emacs --dry-run -112.3 MB would be downloaded: - /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 substitutes, how to disable -The substitute mechanism can be disabled globally by running -@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking -guix-daemon}). It can also be disabled temporarily by passing the -@code{--no-substitutes} option to @command{guix package}, @command{guix -build}, and other command-line tools. - -@node Substitute Authentication -@subsection Substitute Authentication - -@cindex digital signatures -Guix detects and raises an error when attempting to use a substitute that -has been tampered with. Likewise, it ignores substitutes that are not -signed, or that are not signed by one of the keys listed in the ACL. - -There is one exception though: if an unauthorized server provides -substitutes that are @emph{bit-for-bit identical} to those provided by an -authorized server, then the unauthorized server becomes eligible for -downloads. For example, assume we have chosen two substitute servers with -this option: - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex reproducible builds -If the ACL contains only the key for @code{b.example.org}, and if -@code{a.example.org} happens to serve the @emph{exact same} substitutes, -then Guix will download substitutes from @code{a.example.org} because it -comes first in the list and can be considered a mirror of -@code{b.example.org}. In practice, independent build machines usually -produce the same binaries, thanks to bit-reproducible builds (see below). - -When using HTTPS, the server's X.509 certificate is @emph{not} validated (in -other words, the server is not authenticated), contrary to what HTTPS -clients such as Web browsers usually do. This is because Guix authenticates -substitute information itself, as explained above, which is what we care -about (whereas X.509 certificates are about authenticating bindings between -domain names and public keys.) - -@node Proxy Settings -@subsection Proxy Settings - -@vindex http_proxy -Substitutes are downloaded over HTTP or HTTPS. The @code{http_proxy} -environment variable can be set in the environment of @command{guix-daemon} -and is honored for downloads of substitutes. Note that the value of -@code{http_proxy} in the environment where @command{guix build}, -@command{guix package}, and other client commands are run has -@emph{absolutely no effect}. - -@node Substitution Failure -@subsection Substitution Failure - -Even when a substitute for a derivation is available, sometimes the -substitution attempt will fail. This can happen for a variety of reasons: -the substitute server might be offline, the substitute may recently have -been deleted, the connection might have been interrupted, etc. - -When substitutes are enabled and a substitute for a derivation is available, -but the substitution attempt fails, Guix will attempt to build the -derivation locally depending on whether or not @code{--fallback} was given -(@pxref{fallback-option,, common build option @code{--fallback}}). -Specifically, if @code{--fallback} was omitted, then no local build will be -performed, and the derivation is considered to have failed. However, if -@code{--fallback} was given, then Guix will attempt to build the derivation -locally, and the success or failure of the derivation depends on the success -or failure of the local build. Note that when substitutes are disabled or -no substitute is available for the derivation in question, a local build -will @emph{always} be performed, regardless of whether or not -@code{--fallback} was given. - -To get an idea of how many substitutes are available right now, you can try -running the @command{guix weather} command (@pxref{Invoking guix weather}). -This command provides statistics on the substitutes provided by a server. - -@node On Trusting Binaries -@subsection On Trusting Binaries - -@cindex trust, of pre-built binaries -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{Invoking guix publish}). - -Guix has the foundations to maximize build reproducibility -(@pxref{Features}). In most cases, independent builds of a given package or -derivation should yield bit-identical results. Thus, through a diverse set -of independent package builds, we can strengthen the integrity of our -systems. The @command{guix challenge} command aims to help users assess -substitute servers, and to assist developers in finding out about -non-deterministic package builds (@pxref{Invoking guix challenge}). -Similarly, the @option{--check} option of @command{guix build} allows users -to check whether previously-installed substitutes are genuine by rebuilding -them locally (@pxref{build-check, @command{guix build --check}}). - -In the future, we want Guix to have support to publish and retrieve binaries -to/from other users, in a peer-to-peer fashion. If you would like to -discuss this project, join us on @email{guix-devel@@gnu.org}. - -@node Packages with Multiple Outputs -@section Packages with Multiple Outputs - -@cindex multiple-output packages -@cindex package outputs -@cindex outputs - -Often, packages defined in Guix have a single @dfn{output}---i.e., the -source package leads to exactly one directory in the store. When running -@command{guix package -i glibc}, one installs the default output of the GNU -libc package; the default output is called @code{out}, but its name can be -omitted as shown in this command. In this particular case, the default -output of @code{glibc} contains all the C header files, shared libraries, -static libraries, Info documentation, and other supporting files. - -Sometimes it is more appropriate to separate the various types of files -produced from a single source package into separate outputs. For instance, -the GLib C library (used by GTK+ and related packages) installs more than -20 MiB of reference documentation as HTML pages. To save space for users -who do not need it, the documentation goes to a separate output, called -@code{doc}. To install the main GLib output, which contains everything but -the documentation, one would run: - -@example -guix package -i glib -@end example - -@cindex documentation -The command to install its documentation is: - -@example -guix package -i glib:doc -@end example - -Some packages install programs with different ``dependency footprints''. -For instance, the WordNet package installs both command-line tools and -graphical user interfaces (GUIs). The former depend solely on the C -library, whereas the latter depend on Tcl/Tk and the underlying X -libraries. In this case, we leave the command-line tools in the default -output, whereas the GUIs are in a separate output. This allows users who do -not need the GUIs to save space. The @command{guix size} command can help -find out about such situations (@pxref{Invoking guix size}). @command{guix -graph} can also be helpful (@pxref{Invoking guix graph}). - -There are several such multiple-output packages in the GNU distribution. -Other conventional output names include @code{lib} for libraries and -possibly header files, @code{bin} for stand-alone programs, and @code{debug} -for debugging information (@pxref{Installing Debugging Files}). The outputs -of a packages are listed in the third column of the output of @command{guix -package --list-available} (@pxref{Invoking guix package}). - - -@node Invoking guix gc -@section Invoking @command{guix gc} - -@cindex garbage collector -@cindex disk space -Packages that are installed, but not used, may be @dfn{garbage-collected}. -The @command{guix gc} command allows users to explicitly run the garbage -collector to reclaim space from the @file{/gnu/store} directory. It is the -@emph{only} way to remove files from @file{/gnu/store}---removing files or -directories manually may break it beyond repair! - -@cindex GC roots -@cindex garbage collector roots -The garbage collector has a set of known @dfn{roots}: any file under -@file{/gnu/store} reachable from a root is considered @dfn{live} and cannot -be deleted; any other file is considered @dfn{dead} and may be deleted. The -set of garbage collector roots (``GC roots'' for short) includes default -user profiles; by default, the symlinks under @file{/var/guix/gcroots} -represent these GC roots. New GC roots can be added with @command{guix -build --root}, for example (@pxref{Invoking guix build}). The @command{guix -gc --list-roots} command lists them. - -Prior to running @code{guix gc --collect-garbage} to make space, it is often -useful to remove old generations from user profiles; that way, old package -builds referenced by those generations can be reclaimed. This is achieved -by running @code{guix package --delete-generations} (@pxref{Invoking guix -package}). - -Our recommendation is to run a garbage collection periodically, or when you -are short on disk space. For instance, to guarantee that at least 5@tie{}GB -are available on your disk, simply run: - -@example -guix gc -F 5G -@end example - -It is perfectly safe to run as a non-interactive periodic job -(@pxref{Scheduled Job Execution}, 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. - -The @command{guix gc} command has three modes of operation: it can be used -to garbage-collect any dead files (the default), to delete specific files -(the @code{--delete} option), to print garbage-collector information, or for -more advanced queries. The garbage collection options are as follows: - -@table @code -@item --collect-garbage[=@var{min}] -@itemx -C [@var{min}] -Collect garbage---i.e., unreachable @file{/gnu/store} files and -sub-directories. This is the default operation when no option is specified. - -When @var{min} is given, stop once @var{min} bytes have been collected. -@var{min} may be a number of bytes, or it may include a unit as a suffix, -such as @code{MiB} for mebibytes and @code{GB} for gigabytes (@pxref{Block -size, size specifications,, coreutils, GNU Coreutils}). - -When @var{min} is omitted, collect all the garbage. - -@item --free-space=@var{free} -@itemx -F @var{free} -Collect garbage until @var{free} space is available under @file{/gnu/store}, -if possible; @var{free} denotes storage space, such as @code{500MiB}, as -described above. - -When @var{free} or more is already available in @file{/gnu/store}, do -nothing and exit immediately. - -@item --delete-generations[=@var{duration}] -@itemx -d [@var{duration}] -Before starting the garbage collection process, delete all the generations -older than @var{duration}, for all the user profiles; when run as root, this -applies to all the profiles @emph{of all the users}. - -For example, this command deletes all the generations of all your profiles -that are older than 2 months (except generations that are current), and then -proceeds to free space until at least 10 GiB are available: - -@example -guix gc -d 2m -F 10G -@end example - -@item --delete -@itemx -D -Attempt to delete all the store files and directories specified as -arguments. This fails if some of the files are not in the store, or if they -are still live. - -@item --list-failures -List store items corresponding to cached build failures. - -This prints nothing unless the daemon was started with -@option{--cache-failures} (@pxref{Invoking guix-daemon, -@option{--cache-failures}}). - -@item --list-roots -List the GC roots owned by the user; when run as root, list @emph{all} the -GC roots. - -@item --clear-failures -Remove the specified store items from the failed-build cache. - -Again, this option only makes sense when the daemon is started with -@option{--cache-failures}. Otherwise, it does nothing. - -@item --list-dead -Show the list of dead files and directories still present in the -store---i.e., files and directories no longer reachable from any root. - -@item --list-live -Show the list of live store files and directories. - -@end table - -In addition, the references among existing store files can be queried: - -@table @code - -@item --references -@itemx --referrers -@cindex package dependencies -List the references (respectively, the referrers) of store files given as -arguments. - -@item --requisites -@itemx -R -@cindex closure -List the requisites of the store files passed as arguments. Requisites -include the store files themselves, their references, and the references of -these, recursively. In other words, the returned list is the -@dfn{transitive closure} of the store files. - -@xref{Invoking guix size}, for a tool to profile the size of the closure of -an element. @xref{Invoking guix graph}, for a tool to visualize the graph -of references. - -@item --derivers -@cindex derivation -Return the derivation(s) leading to the given store items -(@pxref{Derivations}). - -For example, this command: - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -returns the @file{.drv} file(s) leading to the @code{emacs} package -installed in your profile. - -Note that there may be zero matching @file{.drv} files, for instance because -these files have been garbage-collected. There can also be more than one -matching @file{.drv} due to fixed-output derivations. -@end table - -Lastly, the following options allow you to check the integrity of the store -and to control disk usage. - -@table @option - -@item --verify[=@var{options}] -@cindex integrity, of the store -@cindex integrity checking -Verify the integrity of the store. - -By default, make sure that all the store items marked as valid in the -database of the daemon actually exist in @file{/gnu/store}. - -When provided, @var{options} must be a comma-separated list containing one -or more of @code{contents} and @code{repair}. - -When passing @option{--verify=contents}, the daemon computes the content -hash of each store item and compares it against its hash in the database. -Hash mismatches are reported as data corruptions. Because it traverses -@emph{all the files in the store}, this command can take a long time, -especially on systems with a slow disk drive. - -@cindex repairing the store -@cindex corruption, recovering from -Using @option{--verify=repair} or @option{--verify=contents,repair} causes -the daemon to try to repair corrupt store items by fetching substitutes for -them (@pxref{Substitutes}). Because repairing is not atomic, and thus -potentially dangerous, it is available only to the system administrator. A -lightweight alternative, when you know exactly which items in the store are -corrupt, is @command{guix build --repair} (@pxref{Invoking guix build}). - -@item --optimize -@cindex deduplication -Optimize the store by hard-linking identical files---this is -@dfn{deduplication}. - -The daemon performs deduplication after each successful build or archive -import, unless it was started with @code{--disable-deduplication} -(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus, this -option is primarily useful when the daemon was running with -@code{--disable-deduplication}. - -@end table - -@node Invoking guix pull -@section Invoking @command{guix pull} - -@cindex upgrading Guix -@cindex updating Guix -@cindex @command{guix pull} -@cindex pull -Packages are installed or upgraded to the latest version available in the -distribution currently available on your local machine. To update that -distribution, along with the Guix tools, you must run @command{guix pull}: -the command downloads the latest Guix source code and package descriptions, -and deploys it. Source code is downloaded from a @uref{https://git-scm.com, -Git} repository, by default the official GNU@tie{}Guix repository, though -this can be customized. - -On completion, @command{guix package} will use packages and package versions -from this just-retrieved copy of Guix. Not only that, but all the Guix -commands and Scheme modules will also be taken from that latest version. -New @command{guix} sub-commands added by the update also become available. - -Any user can update their Guix copy using @command{guix pull}, and the -effect is limited to the user who run @command{guix pull}. For instance, -when user @code{root} runs @command{guix pull}, this has no effect on the -version of Guix that user @code{alice} sees, and vice versa. - -The result of running @command{guix pull} is a @dfn{profile} available under -@file{~/.config/guix/current} containing the latest Guix. Thus, make sure -to add it to the beginning of your search path so that you use the latest -version, and similarly for the Info manual (@pxref{Documentation}): - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -The @code{--list-generations} or @code{-l} option lists past generations -produced by @command{guix pull}, along with details about their provenance: - -@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 - -@xref{Invoking guix describe, @command{guix describe}}, for other ways to -describe the current status of Guix. - -This @code{~/.config/guix/current} profile works like any other profile -created by @command{guix package} (@pxref{Invoking guix package}). That is, -you can list generations, roll back to the previous generation---i.e., the -previous Guix---and so on: - -@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 - -The @command{guix pull} command is usually invoked with no arguments, but it -supports the following options: - -@table @code -@item --url=@var{url} -@itemx --commit=@var{commit} -@itemx --branch=@var{branch} -Download code for the @code{guix} channel from the specified @var{url}, at -the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@cindex @file{channels.scm}, configuration file -@cindex configuration file for channels -These options are provided for convenience, but you can also specify your -configuration in the @file{~/.config/guix/channels.scm} file or using the -@option{--channels} option (see below). - -@item --channels=@var{file} -@itemx -C @var{file} -Read the list of channels from @var{file} instead of -@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code -that evaluates to a list of channel objects. @xref{Channels}, for more -information. - -@item --news -@itemx -N -Display the list of packages added or upgraded since the previous -generation. - -This is the same information as displayed upon @command{guix pull} -completion, but without ellipses; it is also similar to the output of -@command{guix pull -l} for the last generation (see below). - -@item --list-generations[=@var{pattern}] -@itemx -l [@var{pattern}] -List all the generations of @file{~/.config/guix/current} or, if -@var{pattern} is provided, the subset of generations that match -@var{pattern}. The syntax of @var{pattern} is the same as with @code{guix -package --list-generations} (@pxref{Invoking guix package}). - -@xref{Invoking guix describe}, for a way to display information about the -current generation only. - -@item --profile=@var{profile} -@itemx -p @var{profile} -Use @var{profile} instead of @file{~/.config/guix/current}. - -@item --dry-run -@itemx -n -Show which channel commit(s) would be used and what would be built or -substituted but do not actually do it. - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the -system type of the build host. - -@item --verbose -Produce verbose output, writing build logs to the standard error output. - -@item --bootstrap -Use the bootstrap Guile to build the latest Guix. This option is only -useful to Guix developers. -@end table - -The @dfn{channel} mechanism allows you to instruct @command{guix pull} which -repository and branch to pull from, as well as @emph{additional} -repositories containing package modules that should be deployed. -@xref{Channels}, for more information. - -In addition, @command{guix pull} supports all the common build options -(@pxref{Common Build Options}). - -@node Channels -@section Channels - -@cindex channels -@cindex @file{channels.scm}, configuration file -@cindex configuration file for channels -@cindex @command{guix pull}, configuration file -@cindex configuration of @command{guix pull} -Guix and its package collection are updated by running @command{guix pull} -(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and -deploys Guix itself from the official GNU@tie{}Guix repository. This can be -customized by defining @dfn{channels} in the -@file{~/.config/guix/channels.scm} file. A channel specifies a URL and -branch of a Git repository to be deployed, and @command{guix pull} can be -instructed to pull from one or more channels. In other words, channels can -be used to @emph{customize} and to @emph{extend} Guix, as we will see below. - -@subsection Using a Custom Guix Channel - -The channel called @code{guix} specifies where Guix itself---its -command-line tools as well as its package collection---should be -downloaded. For instance, suppose you want to update from your own copy of -the Guix repository at @code{example.org}, and specifically the -@code{super-hacks} branch, you can write in -@code{~/.config/guix/channels.scm} this specification: - -@lisp -;; Tell 'guix pull' to use my own repo. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -From there on, @command{guix pull} will fetch code from the -@code{super-hacks} branch of the repository at @code{example.org}. - -@subsection Specifying Additional Channels - -@cindex extending the package collection (channels) -@cindex personal packages (channels) -@cindex channels, for personal packages -You can also specify @emph{additional channels} to pull from. Let's say you -have a bunch of custom package variants or personal packages that you think -would make little sense to contribute to the Guix project, but would like to -have these packages transparently available to you at the command line. You -would first write modules containing those package definitions -(@pxref{Package Modules}), maintain them in a Git repository, and then you -and anyone else can use it as an additional channel to get packages from. -Neat, no? - -@c What follows stems from discussions at -@c as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Warning -Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and -publish your personal channel to the world, we would like to share a few -words of caution: - -@itemize -@item -Before publishing a channel, please consider contributing your package -definitions to Guix proper (@pxref{贡献}). Guix as a project is -open to free software of all sorts, and packages in Guix proper are readily -available to all Guix users and benefit from the project's quality assurance -process. - -@item -When you maintain package definitions outside Guix, we, Guix developers, -consider that @emph{the compatibility burden is on you}. Remember that -package modules and package definitions are just Scheme code that uses -various programming interfaces (APIs). We want to remain free to change -these APIs to keep improving Guix, possibly in ways that break your -channel. We never change APIs gratuitously, but we will @emph{not} commit -to freezing APIs either. - -@item -Corollary: if you're using an external channel and that channel breaks, -please @emph{report the issue to the channel authors}, not to the Guix -project. -@end itemize - -You've been warned! Having said this, we believe external channels are a -practical way to exert your freedom to augment Guix' package collection and -to share your improvements, which are basic tenets of -@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please -email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. -@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 -;; Add my personal packages to those Guix provides. -(cons (channel - (name 'my-personal-packages) - (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 - my-personal-packages dd3df5e - repository URL: https://example.org/personal-packages.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -The output of @command{guix pull} above shows that Generation@tie{}19 -includes both Guix and packages from the @code{my-personal-packages} -channel. Among the new and upgraded packages that are listed, some like -@code{my-gimp} and @code{my-emacs-with-cool-features} might come from -@code{my-personal-packages}, while others come from the Guix default -channel. - -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{Modules,,, 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 Replicating Guix - -@cindex pinning, channels -@cindex replicating Guix -@cindex reproducibility, of Guix -The @command{guix pull --list-generations} output above shows precisely -which commits were used to build this instance of Guix. We can thus -replicate it, say, on another machine, by providing a channel specification -in @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: - -@lisp -;; Deploy specific commits of my channels of interest. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). - -At this point the two machines run the @emph{exact same Guix}, with access -to the @emph{exact same packages}. The output of @command{guix build gimp} -on one machine will be exactly the same, bit for bit, as the output of the -same command on the other machine. It also means both machines have access -to all the source code of Guix and, transitively, to all the source code of -every package it defines. - -This gives you super powers, allowing you to track the provenance of binary -artifacts with very fine grain, and to reproduce software environments at -will---some sort of ``meta reproducibility'' capabilities, if you will. -@xref{Inferiors}, for another way to take advantage of these super powers. - -@node Inferiors -@section Inferiors - -@c TODO: Remove this once we're more confident about API stability. -@quotation Note -The functionality described here is a ``technology preview'' as of version -@value{VERSION}. As such, the interface is subject to change. -@end quotation - -@cindex inferiors -@cindex composition of Guix revisions -Sometimes you might need to mix packages from the revision of Guix you're -currently running with packages available in a different revision of Guix. -Guix @dfn{inferiors} allow you to achieve that by composing different Guix -revisions in arbitrary ways. - -@cindex inferior packages -Technically, an ``inferior'' is essentially a separate Guix process -connected to your main Guix process through a REPL (@pxref{Invoking guix -repl}). The @code{(guix inferior)} module allows you to create inferiors -and to communicate with them. It also provides a high-level interface to -browse and manipulate the packages that an inferior provides---@dfn{inferior -packages}. - -When combined with channels (@pxref{Channels}), inferiors provide a simple -way to interact with a separate revision of Guix. For example, let's assume -you want to install in your profile the current @code{guile} package, along -with the @code{guile-json} as it existed in an older revision of -Guix---perhaps because the newer @code{guile-json} has an incompatible API -and you want to run your code against the old API@. To do that, you could -write a manifest for use by @code{guix package --manifest} (@pxref{Invoking -guix package}); in that manifest, you would create an inferior for that old -Guix revision you care about, and you would look up the @code{guile-json} -package in the inferior: - -@lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;for 'first' - -(define channels - ;; This is the old revision from which we want to - ;; extract guile-json. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) - -(define inferior - ;; An inferior representing the above revision. - (inferior-for-channels channels)) - -;; Now create a manifest with the current "guile" package -;; and the old "guile-json" package. -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) -@end lisp - -On its first run, @command{guix package --manifest} might have to build the -channel you specified before it can create the inferior; subsequent runs -will be much faster because the Guix revision will be cached. - -The @code{(guix inferior)} module provides the following procedures to open -an inferior: - -@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ - [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of -channels. Use the cache at @var{cache-directory}, where entries can be -reclaimed after @var{ttl} seconds. This procedure opens a new connection to -the build daemon. - -As a side effect, this procedure may build or substitute binaries for -@var{channels}, which can take time. -@end deffn - -@deffn {Scheme Procedure} open-inferior @var{directory} @ - [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running -@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} -if the inferior could not be launched. -@end deffn - -@cindex inferior packages -The procedures listed below allow you to obtain and manipulate inferior -packages. - -@deffn {Scheme Procedure} inferior-packages @var{inferior} -Return the list of packages known to @var{inferior}. -@end deffn - -@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @ - [@var{version}] Return the sorted list of inferior packages matching -@var{name} in @var{inferior}, with highest version numbers first. If -@var{version} is true, return only packages with a version number prefixed -by @var{version}. -@end deffn - -@deffn {Scheme Procedure} inferior-package? @var{obj} -Return true if @var{obj} is an inferior package. -@end deffn - -@deffn {Scheme Procedure} inferior-package-name @var{package} -@deffnx {Scheme Procedure} inferior-package-version @var{package} -@deffnx {Scheme Procedure} inferior-package-synopsis @var{package} -@deffnx {Scheme Procedure} inferior-package-description @var{package} -@deffnx {Scheme Procedure} inferior-package-home-page @var{package} -@deffnx {Scheme Procedure} inferior-package-location @var{package} -@deffnx {Scheme Procedure} inferior-package-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-search-paths @var{package} -These procedures are the counterpart of package record accessors -(@pxref{package Reference}). Most of them work by querying the inferior -@var{package} comes from, so the inferior must still be live when you call -these procedures. -@end deffn - -Inferior packages can be used transparently like any other package or -file-like object in G-expressions (@pxref{G-Expressions}). They are also -transparently handled by the @code{packages->manifest} procedure, which is -commonly use in manifests (@pxref{Invoking guix package, the -@option{--manifest} option of @command{guix package}}). Thus you can insert -an inferior package pretty much anywhere you would insert a regular package: -in manifests, in the @code{packages} field of your @code{operating-system} -declaration, and so on. - -@node Invoking guix describe -@section Invoking @command{guix describe} - -@cindex reproducibility -@cindex replicating Guix -Often you may want to answer questions like: ``Which revision of Guix am I -using?'' or ``Which channels am I using?'' This is useful information in -many situations: if you want to @emph{replicate} an environment on a -different machine or user account, if you want to report a bug or to -determine what change in the channels you are using caused it, or if you -want to record your system state for reproducibility purposes. The -@command{guix describe} command answers these questions. - -When run from a @command{guix pull}ed @command{guix}, @command{guix -describe} displays the channel(s) that it was built from, including their -repository URL and commit IDs (@pxref{Channels}): - -@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 - -If you're familiar with the Git version control system, this is similar in -spirit to @command{git describe}; the output is also similar to that of -@command{guix pull --list-generations}, but limited to the current -generation (@pxref{Invoking guix pull, the @option{--list-generations} -option}). Because the Git commit ID shown above unambiguously refers to a -snapshot of Guix, this information is all it takes to describe the revision -of Guix you're using, and also to replicate it. - -To make it easier to replicate Guix, @command{guix describe} can also be -asked to return a list of channels instead of the human-readable description -above: - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -You can save this to a file and feed it to @command{guix pull -C} on some -other machine or at a later point in time, which will instantiate @emph{this -exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). -From there on, since you're able to deploy the same revision of Guix, you -can just as well @emph{replicate a complete software environment}. We -humbly think that this is @emph{awesome}, and we hope you'll like it too! - -The details of the options supported by @command{guix describe} are as -follows: - -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produce output in the specified @var{format}, one of: - -@table @code -@item human -produce human-readable output; -@item channels -produce a list of channel specifications that can be passed to @command{guix -pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking -guix pull}); -@item json -@cindex JSON -produce a list of channel specifications in JSON format; -@item recutils -produce a list of channel specifications in Recutils format. -@end table - -@item --profile=@var{profile} -@itemx -p @var{profile} -Display information about @var{profile}. -@end table - -@node Invoking guix archive -@section Invoking @command{guix archive} - -@cindex @command{guix archive} -@cindex archive -The @command{guix archive} command allows users to @dfn{export} files from -the store into a single archive, and to later @dfn{import} them on a machine -that runs Guix. In particular, it allows store files to be transferred from -one machine to the store on another machine. - -@quotation Note -If you're looking for a way to produce archives in a format suitable for -tools other than Guix, @pxref{Invoking guix pack}. -@end quotation - -@cindex exporting store items -To export store files as an archive to standard output, run: - -@example -guix archive --export @var{options} @var{specifications}... -@end example - -@var{specifications} may be either store file names or package -specifications, as for @command{guix package} (@pxref{Invoking guix -package}). For instance, the following command creates an archive -containing the @code{gui} output of the @code{git} package and the main -output of @code{emacs}: - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar -@end example - -If the specified packages are not built yet, @command{guix archive} -automatically builds them. The build process may be controlled with the -common build options (@pxref{Common Build Options}). - -To transfer the @code{emacs} package to a machine connected over SSH, one -would run: - -@example -guix archive --export -r emacs | ssh the-machine guix archive --import -@end example - -@noindent -Similarly, a complete user profile may be transferred from one machine to -another like this: - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh the-machine guix-archive --import -@end example - -@noindent -However, note that, in both examples, all of @code{emacs} and the profile as -well as all of their dependencies are transferred (due to @code{-r}), -regardless of what is already available in the store on the target machine. -The @code{--missing} option can help figure out which items are missing from -the target store. The @command{guix copy} command simplifies and optimizes -this whole process, so this is probably what you should use in this case -(@pxref{Invoking guix copy}). - -@cindex nar, archive format -@cindex normalized archive (nar) -Archives are stored in the ``normalized archive'' or ``nar'' format, which -is comparable in spirit to `tar', but with differences that make it more -appropriate for our purposes. First, rather than recording all Unix -metadata for each file, the nar format only mentions the file type (regular, -directory, or symbolic link); Unix permissions and owner/group are -dismissed. Second, the order in which directory entries are stored always -follows the order of file names according to the C locale collation order. -This makes archive production fully deterministic. - -@c FIXME: Add xref to daemon doc about signatures. -When exporting, the daemon digitally signs the contents of the archive, and -that digital signature is appended. When importing, the daemon verifies the -signature and rejects the import in case of an invalid signature or if the -signing key is not authorized. - -The main options are: - -@table @code -@item --export -Export the specified store files or packages (see below.) Write the -resulting archive to the standard output. - -Dependencies are @emph{not} included in the output, unless -@code{--recursive} is passed. - -@item -r -@itemx --recursive -When combined with @code{--export}, this instructs @command{guix archive} to -include dependencies of the given items in the archive. Thus, the resulting -archive is self-contained: it contains the closure of the exported store -items. - -@item --import -Read an archive from the standard input, and import the files listed therein -into the store. Abort if the archive has an invalid digital signature, or -if it is signed by a public key not among the authorized keys (see -@code{--authorize} below.) - -@item --missing -Read a list of store file names from the standard input, one per line, and -write on the standard output the subset of these files missing from the -store. - -@item --generate-key[=@var{parameters}] -@cindex signing, archives -Generate a new key pair for the daemon. This is a prerequisite before -archives can be exported with @code{--export}. Note that this operation -usually takes time, because it needs to gather enough entropy to generate -the key pair. - -The generated key pair is typically stored under @file{/etc/guix}, in -@file{signing-key.pub} (public key) and @file{signing-key.sec} (private key, -which must be kept secret.) When @var{parameters} is omitted, an ECDSA key -using the Ed25519 curve is generated, or, for Libgcrypt versions before -1.6.0, it is a 4096-bit RSA key. Alternatively, @var{parameters} can -specify @code{genkey} parameters suitable for Libgcrypt (@pxref{General -public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The Libgcrypt -Reference Manual}). - -@item --authorize -@cindex authorizing, archives -Authorize imports signed by the public key passed on standard input. The -public key must be in ``s-expression advanced format''---i.e., the same -format as the @file{signing-key.pub} file. - -The list of authorized keys is kept in the human-editable file -@file{/etc/guix/acl}. The file contains -@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format -s-expressions''} and is structured as an access-control list in the -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure -(SPKI)}. - -@item --extract=@var{directory} -@itemx -x @var{directory} -Read a single-item archive as served by substitute servers -(@pxref{Substitutes}) and extract it to @var{directory}. This is a -low-level operation needed in only very narrow use cases; see below. - -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 - -Single-item archives are different from multiple-item archives produced by -@command{guix archive --export}; they contain a single store item, and they -do @emph{not} embed a signature. Thus this operation does @emph{no} -signature verification and its output should be considered unsafe. - -The primary purpose of this operation is to facilitate inspection of archive -contents coming from possibly untrusted substitute servers. - -@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 -* Invoking guix environment:: Setting up development environments. -* Invoking guix pack:: Creating software bundles. -@end menu - -@node Invoking guix environment -@section Invoking @command{guix environment} - -@cindex reproducible build environments -@cindex development environments -@cindex @command{guix environment} -@cindex environment, package build environment -The purpose of @command{guix environment} is to assist hackers in creating -reproducible development environments without polluting their package -profile. The @command{guix environment} tool takes one or more packages, -builds all of their inputs, and creates a shell environment to use them. - -The general syntax is: - -@example -guix environment @var{options} @var{package}@dots{} -@end example - -The following example spawns a new shell set up for the development of -GNU@tie{}Guile: - -@example -guix environment guile -@end example - -If the needed dependencies are not built yet, @command{guix environment} -automatically builds them. The environment of the new shell is an augmented -version of the environment that @command{guix environment} was run in. It -contains the necessary search paths for building the given package added to -the existing environment variables. To create a ``pure'' environment, in -which the original environment variables have been unset, use the -@code{--pure} option@footnote{Users sometimes wrongfully augment environment -variables such as @code{PATH} in their @file{~/.bashrc} file. As a -consequence, when @code{guix environment} launches it, Bash may read -@file{~/.bashrc}, thereby introducing ``impurities'' in these environment -variables. It is an error to define such environment variables in -@file{.bashrc}; instead, they should be defined in @file{.bash_profile}, -which is sourced only by log-in shells. @xref{Bash Startup Files,,, bash, -The GNU Bash Reference Manual}, for details on Bash start-up files.}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} defines the @code{GUIX_ENVIRONMENT} variable in -the shell it spawns; its value is the file name of the profile of this -environment. This allows users to, say, define a specific prompt for -development environments in their @file{.bashrc} (@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 - -Additionally, more than one package may be specified, in which case the -union of the inputs for the given packages are used. For example, the -command below spawns a shell where all of the dependencies of both Guile and -Emacs are available: - -@example -guix environment guile emacs -@end example - -Sometimes an interactive shell session is not desired. An arbitrary command -may be invoked by placing the @code{--} token to separate the command from -the rest of the arguments: - -@example -guix environment guile -- make -j4 -@end example - -In other situations, it is more convenient to specify the list of packages -needed in the environment. For example, the following command runs -@command{python} from an environment containing Python@tie{}2.7 and NumPy: - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -Furthermore, one might want the dependencies of a package and also some -additional packages that are not build-time or runtime dependencies, but are -useful when developing nonetheless. Because of this, the @code{--ad-hoc} -flag is positional. Packages appearing before @code{--ad-hoc} are -interpreted as packages whose dependencies will be added to the -environment. Packages appearing after are interpreted as packages that will -be added to the environment directly. For example, the following command -creates a Guix development environment that additionally includes Git and -strace: - -@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 Note -The @code{--container} option requires Linux-libre 3.19 or newer. -@end quotation - -The available options are summarized below. - -@table @code -@item --root=@var{file} -@itemx -r @var{file} -@cindex persistent environment -@cindex garbage collector root, for environments -Make @var{file} a symlink to the profile for this environment, and register -it as a garbage collector root. - -This is useful if you want to protect your environment from garbage -collection, to make it ``persistent''. - -When this option is omitted, the environment is protected from garbage -collection only for the duration of the @command{guix environment} session. -This means that next time you recreate the same environment, you could have -to rebuild or re-download packages. @xref{Invoking guix gc}, for more on GC -roots. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Create an environment for the package or list of packages that @var{expr} -evaluates to. - -For example, running: - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -starts a shell with the environment for this specific variant of the PETSc -package. - -Running: - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -starts a shell with all the base system packages available. - -The above commands only use the default output of the given packages. To -select other outputs, two element tuples can be specified: - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{file} -@itemx -l @var{file} -Create an environment for the package or list of packages that the code -within @var{file} evaluates to. - -As an example, @var{file} might contain a definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{file} -@itemx -m @var{file} -Create an environment for the packages contained in the manifest object -returned by the Scheme code in @var{file}. - -This is similar to the same-named option in @command{guix package} -(@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest -files. - -@item --ad-hoc -Include all specified packages in the resulting environment, as if an @i{ad -hoc} package were defined with them as inputs. This option is useful for -quickly creating an environment without having to write a package expression -to contain the desired inputs. - -For instance, the command: - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -runs @command{guile} in an environment where Guile and Guile-SDL are -available. - -Note that this example implicitly asks for the default output of -@code{guile} and @code{guile-sdl}, but it is possible to ask for a specific -output---e.g., @code{glib:bin} asks for the @code{bin} output of @code{glib} -(@pxref{Packages with Multiple Outputs}). - -This option may be composed with the default behavior of @command{guix -environment}. Packages appearing before @code{--ad-hoc} are interpreted as -packages whose dependencies will be added to the environment, the default -behavior. Packages appearing after are interpreted as packages that will be -added to the environment directly. - -@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 -Display the environment variable definitions that make up the environment. - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system}---e.g., @code{i686-linux}. - -@item --container -@itemx -C -@cindex container -Run @var{command} within an isolated container. The current working -directory outside the container is mapped inside the container. -Additionally, unless overridden with @code{--user}, a dummy home directory -is created that matches the current user's home directory, and -@file{/etc/passwd} is configured accordingly. - -The spawned process runs as the current user outside the container. Inside -the container, it has the same UID and GID as the current user, unless -@option{--user} is passed (see below.) - -@item --network -@itemx -N -For containers, share the network namespace with the host system. -Containers created without this flag only have access to the loopback -device. - -@item --link-profile -@itemx -P -For containers, link the environment profile to @file{~/.guix-profile} -within the container. This is equivalent to running the command @command{ln --s $GUIX_ENVIRONMENT ~/.guix-profile} within the container. Linking will -fail and abort the environment if the directory already exists, which will -certainly be the case if @command{guix environment} was invoked in the -user's home directory. - -Certain packages are configured to look in @code{~/.guix-profile} for -configuration files and data;@footnote{For example, the @code{fontconfig} -package inspects @file{~/.guix-profile/share/fonts} for additional fonts.} -@code{--link-profile} allows these programs to behave as expected within the -environment. - -@item --user=@var{user} -@itemx -u @var{user} -For containers, use the username @var{user} in place of the current user. -The generated @file{/etc/passwd} entry within the container will contain the -name @var{user}, the home directory will be @file{/home/@var{user}}, and no -user GECOS data will be copied. Furthermore, the UID and GID inside the -container are 1000. @var{user} need not exist on the system. - -Additionally, any shared or exposed path (see @code{--share} and -@code{--expose} respectively) whose target is within the current user's home -directory will be remapped relative to @file{/home/USER}; this includes the -automatic mapping of the current working directory. - -@example -# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target -cd $HOME/wd -guix environment --container --user=foo \ - --expose=$HOME/test \ - --expose=/tmp/target=$HOME/target -@end example - -While this will limit the leaking of user identity through home paths and -each of the user fields, this is only one useful component of a broader -privacy/anonymity solution---not one in and of itself. - -@item --expose=@var{source}[=@var{target}] -For containers, expose the file system @var{source} from the host system as -the read-only file system @var{target} within the container. If -@var{target} is not specified, @var{source} is used as the target mount -point in the container. - -The example below spawns a Guile REPL in a container in which the user's -home directory is accessible read-only via the @file{/exchange} directory: - -@example -guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile -@end example - -@item --share=@var{source}[=@var{target}] -For containers, share the file system @var{source} from the host system as -the writable file system @var{target} within the container. If @var{target} -is not specified, @var{source} is used as the target mount point in the -container. - -The example below spawns a Guile REPL in a container in which the user's -home directory is accessible for both reading and writing via the -@file{/exchange} directory: - -@example -guix environment --container --share=$HOME=/exchange --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{Common Build Options}) as well as -package transformation options (@pxref{Package Transformation Options}). - -@node Invoking guix pack -@section Invoking @command{guix pack} - -Occasionally you want to pass software to people who are not (yet!) lucky -enough to be using Guix. You'd tell them to run @command{guix package -i -@var{something}}, but that's not possible in this case. This is where -@command{guix pack} comes in. - -@quotation Note -If you are looking for ways to exchange binaries among machines that already -run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix publish}, and -@ref{Invoking guix archive}. -@end quotation - -@cindex pack -@cindex bundle -@cindex application bundle -@cindex software bundle -The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or -@dfn{software bundle}: it creates a tarball or some other archive containing -the binaries of the software you're interested in, and all its -dependencies. The resulting archive can be used on any machine that does -not have Guix, and people can run the exact same binaries as those you have -with Guix. The pack itself is created in a bit-reproducible fashion, so -anyone can verify that it really contains the build results that you pretend -to be shipping. - -For example, to create a bundle containing Guile, Emacs, Geiser, and all -their dependencies, you can run: - -@example -$ guix pack guile emacs geiser -@dots{} -/gnu/store/@dots{}-pack.tar.gz -@end example - -The result here is a tarball containing a @file{/gnu/store} directory with -all the relevant packages. The resulting tarball contains a @dfn{profile} -with the three packages of interest; the profile is the same as would be -created by @command{guix package -i}. It is this mechanism that is used to -create Guix's own standalone binary tarball (@pxref{Binary Installation}). - -Users of this pack would have to run -@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may find -inconvenient. To work around it, you can create, say, a @file{/opt/gnu/bin} -symlink to the profile: - -@example -guix pack -S /opt/gnu/bin=bin guile emacs geiser -@end example - -@noindent -That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy. - -@cindex relocatable binaries, with @command{guix pack} -What if the recipient of your pack does not have root privileges on their -machine, and thus cannot unpack it in the root file system? In that case, -you will want to use the @code{--relocatable} option (see below). This -option produces @dfn{relocatable binaries}, meaning they they can be placed -anywhere in the file system hierarchy: in the example above, users can -unpack your tarball in their home directory and directly run -@file{./opt/gnu/bin/guile}. - -@cindex Docker, build an image with guix pack -Alternatively, you can produce a pack in the Docker image format using the -following command: - -@example -guix pack -f docker guile emacs geiser -@end example - -@noindent -The result is a tarball that can be passed to the @command{docker load} -command. See the -@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker -documentation} for more information. - -@cindex Singularity, build an image with guix pack -@cindex SquashFS, build an image with guix pack -Yet another option is to produce a SquashFS image with the following -command: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -The result is a SquashFS file system image that can either be mounted or -directly be used as a file system container image with the -@uref{http://singularity.lbl.gov, Singularity container execution -environment}, using commands like @command{singularity shell} or -@command{singularity exec}. - -Several command-line options allow you to customize your pack: - -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produce a pack in the given @var{format}. - -The available formats are: - -@table @code -@item tarball -This is the default format. It produces a tarball containing all the -specified binaries and symlinks. - -@item docker -This produces a tarball that follows the -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -Docker Image Specification}. - -@item squashfs -This produces a SquashFS image containing all the specified binaries and -symlinks, as well as empty mount points for virtual file systems like -procfs. -@end table - -@cindex relocatable binaries -@item --relocatable -@itemx -R -Produce @dfn{relocatable binaries}---i.e., binaries that can be placed -anywhere in the file system hierarchy and run from there. - -When this option is passed once, the resulting binaries require support for -@dfn{user namespaces} in the kernel Linux; when passed -@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds -PRoot support, can be thought of as the abbreviation of ``Really -Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot -if user namespaces are unavailable, and essentially work anywhere---see -below for the implications. - -For example, if you create a pack containing Bash with: - -@example -guix pack -RR -S /mybin=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 -./mybin/sh -@end example - -@noindent -In that shell, if you type @code{ls /gnu/store}, you'll notice that -@file{/gnu/store} shows up and contains all the dependencies of @code{bash}, -even though the machine actually lacks @file{/gnu/store} altogether! That is -probably the simplest way to deploy Guix-built software on a non-Guix -machine. - -@quotation Note -By default, relocatable binaries rely on the @dfn{user namespace} feature of -the kernel Linux, which allows unprivileged users to mount or change root. -Old versions of Linux did not support it, and some GNU/Linux distributions -turn it off. - -To produce relocatable binaries that work even in the absence of user -namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In -that case, binaries will try user namespace support and fall back to PRoot -if user namespaces are not supported. - -The @uref{https://proot-me.github.io/, PRoot} program provides the necessary -support for file system virtualization. It achieves that by using the -@code{ptrace} system call on the running program. This approach has the -advantage to work without requiring special kernel support, but it incurs -run-time overhead every time a system call is made. -@end quotation - -@item --expression=@var{expr} -@itemx -e @var{expr} -Consider the package @var{expr} evaluates to. - -This has the same purpose as the same-named option in @command{guix build} -(@pxref{Additional Build Options, @code{--expression} in @command{guix -build}}). - -@item --manifest=@var{file} -@itemx -m @var{file} -Use the packages contained in the manifest object returned by the Scheme -code in @var{file}. - -This has a similar purpose as the same-named option in @command{guix -package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same -manifest files. It allows you to define a collection of packages once and -use it both for creating profiles and for creating archives for use on -machines that do not have Guix installed. Note that you can specify -@emph{either} a manifest file @emph{or} a list of packages, but not both. - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the -system type of the build host. - -@item --target=@var{triplet} -@cindex cross-compilation -Cross-build for @var{triplet}, which must be a valid GNU triplet, such as -@code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU -configuration triplets,, autoconf, Autoconf}). - -@item --compression=@var{tool} -@itemx -C @var{tool} -Compress the resulting tarball using @var{tool}---one of @code{gzip}, -@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression. - -@item --symlink=@var{spec} -@itemx -S @var{spec} -Add the symlinks specified by @var{spec} to the pack. This option can -appear several times. - -@var{spec} has the form @code{@var{source}=@var{target}}, where @var{source} -is the symlink that will be created and @var{target} is the symlink target. - -For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin} -symlink pointing to the @file{bin} sub-directory of the profile. - -@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{Channels}). - -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} -Include the ``local state directory'', @file{/var/guix}, in the resulting -pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}} -profile---by default @var{name} is @code{guix-profile}, which corresponds to -@file{~root/.guix-profile}. - -@file{/var/guix} contains the store database (@pxref{The Store}) as well as -garbage-collector roots (@pxref{Invoking guix gc}). Providing it in the -pack means that the store is ``complete'' and manageable by Guix; not -providing it pack means that the store is ``dead'': items cannot be added to -it or removed from it after extraction of the pack. - -One use case for this is the Guix self-contained binary tarball -(@pxref{Binary Installation}). - -@item --bootstrap -Use the bootstrap binaries to build the pack. This option is only useful to -Guix developers. -@end table - -In addition, @command{guix pack} supports all the common build options -(@pxref{Common Build Options}) and all the package transformation options -(@pxref{Package Transformation Options}). - - -@c ********************************************************************* -@node Programming Interface -@chapter Programming Interface - -GNU Guix provides several Scheme programming interfaces (APIs) to define, -build, and query packages. The first interface allows users to write -high-level package definitions. These definitions refer to familiar -packaging concepts, such as the name and version of a package, its build -system, and its dependencies. These definitions can then be turned into -concrete build actions. - -Build actions are performed by the Guix daemon, on behalf of users. In a -standard setup, the daemon has write access to the store---the -@file{/gnu/store} directory---whereas users do not. The recommended setup -also has the daemon perform builds in chroots, under a specific build users, -to minimize interference with the rest of the system. - -@cindex derivation -Lower-level APIs are available to interact with the daemon and the store. -To instruct the daemon to perform a build action, users actually provide it -with a @dfn{derivation}. A derivation is a low-level representation of the -build actions to be taken, and the environment in which they should -occur---derivations are to package definitions what assembly is to C -programs. The term ``derivation'' comes from the fact that build results -@emph{derive} from them. - -This chapter describes all these APIs in turn, starting from high-level -package definitions. - -@menu -* Package Modules:: Packages from the programmer's viewpoint. -* Defining Packages:: Defining new packages. -* Build Systems:: Specifying how packages are built. -* The Store:: Manipulating the package store. -* Derivations:: Low-level interface to package derivations. -* The Store Monad:: Purely functional interface to the store. -* G-Expressions:: Manipulating build expressions. -* Invoking guix repl:: Fiddling with Guix interactively. -@end menu - -@node Package Modules -@section Package Modules - -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{Modules, 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{} object (@pxref{Defining -Packages}). - -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 customization, of packages -@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{Common Build Options}), 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{Channels}, 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 Defining Packages -@section Defining Packages - -The high-level interface to package definitions is implemented in the -@code{(guix packages)} and @code{(guix build-system)} modules. As an -example, the package definition, or @dfn{recipe}, for the GNU Hello package -looks like this: - -@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 -Without being a Scheme expert, the reader may have guessed the meaning of -the various fields here. This expression binds the variable @code{hello} to -a @code{} object, which is essentially a record (@pxref{SRFI-9, -Scheme records,, guile, GNU Guile Reference Manual}). This package object -can be inspected using procedures found in the @code{(guix packages)} -module; for instance, @code{(package-name hello)} -returns---surprise!---@code{"hello"}. - -With luck, you may be able to import part or all of the definition of the -package you are interested in from another repository, using the @code{guix -import} command (@pxref{Invoking guix import}). - -In the example above, @var{hello} is defined in a module of its own, -@code{(gnu packages hello)}. Technically, this is not strictly necessary, -but it is convenient to do so: all the packages defined in modules under -@code{(gnu packages @dots{})} are automatically known to the command-line -tools (@pxref{Package Modules}). - -There are a few points worth noting in the above package definition: - -@itemize -@item -The @code{source} field of the package is an @code{} object -(@pxref{origin Reference}, for the complete reference). Here, the -@code{url-fetch} method from @code{(guix download)} is used, meaning that -the source is a file to be downloaded over FTP or HTTP. - -The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of the -GNU mirrors defined in @code{(guix download)}. - -The @code{sha256} field specifies the expected SHA256 hash of the file being -downloaded. It is mandatory, and allows Guix to check the integrity of the -file. The @code{(base32 @dots{})} form introduces the base32 representation -of the hash. You can obtain this information with @code{guix download} -(@pxref{Invoking guix download}) and @code{guix hash} (@pxref{Invoking guix -hash}). - -@cindex patches -When needed, the @code{origin} form can also have a @code{patches} field -listing patches to be applied, and a @code{snippet} field giving a Scheme -expression to modify the source code. - -@item -@cindex GNU Build System -The @code{build-system} field specifies the procedure to build the package -(@pxref{Build Systems}). Here, @var{gnu-build-system} represents the -familiar GNU Build System, where packages may be configured, built, and -installed with the usual @code{./configure && make && make check && make -install} command sequence. - -@item -The @code{arguments} field specifies options for the build system -(@pxref{Build Systems}). Here it is interpreted by @var{gnu-build-system} -as a request run @file{configure} with the @code{--enable-silent-rules} -flag. - -@cindex quote -@cindex quoting -@findex ' -@findex quote -What about these quote (@code{'}) characters? They are Scheme syntax to -introduce a literal list; @code{'} is synonymous with @code{quote}. -@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, for -details. Here the value of the @code{arguments} field is a list of -arguments passed to the build system down the road, as with @code{apply} -(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword} -(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and -@code{#:configure-flags} is a keyword used to pass a keyword argument to the -build system (@pxref{Coding With Keywords,,, guile, GNU Guile Reference -Manual}). - -@item -The @code{inputs} field specifies inputs to the build process---i.e., -build-time or run-time dependencies of the package. Here, we define an -input called @code{"gawk"} whose value is that of the @var{gawk} variable; -@var{gawk} is itself bound to a @code{} object. - -@cindex backquote (quasiquote) -@findex ` -@findex quasiquote -@cindex comma (unquote) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows us -to introduce a literal list in the @code{inputs} field, while @code{,} (a -comma, synonymous with @code{unquote}) allows us to insert a value in that -list (@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference -Manual}). - -Note that GCC, Coreutils, Bash, and other essential tools do not need to be -specified as inputs here. Instead, @var{gnu-build-system} takes care of -ensuring that they are present (@pxref{Build Systems}). - -However, any other dependencies need to be specified in the @code{inputs} -field. Any dependency not specified here will simply be unavailable to the -build process, possibly leading to a build failure. -@end itemize - -@xref{package Reference}, for a full description of possible fields. - -Once a package definition is in place, the package may actually be built -using the @code{guix build} command-line tool (@pxref{Invoking guix build}), -troubleshooting any build failures you encounter (@pxref{Debugging Build -Failures}). You can easily jump back to the package definition using the -@command{guix edit} command (@pxref{Invoking guix edit}). @xref{打包指导}, for more information on how to test package definitions, and -@ref{Invoking guix lint}, for information on how to check a definition for -style conformance. -@vindex GUIX_PACKAGE_PATH -Lastly, @pxref{Channels}, for information on how to extend the distribution -by adding your own package definitions in a ``channel''. - -Finally, updating the package definition to a new upstream version can be -partly automated by the @command{guix refresh} command (@pxref{Invoking guix -refresh}). - -Behind the scenes, a derivation corresponding to the @code{} object -is first computed by the @code{package-derivation} procedure. That -derivation is stored in a @code{.drv} file under @file{/gnu/store}. The -build actions it prescribes may then be realized by using the -@code{build-derivations} procedure (@pxref{The Store}). - -@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] -Return the @code{} object of @var{package} for @var{system} -(@pxref{Derivations}). - -@var{package} must be a valid @code{} object, and @var{system} must -be a string denoting the target system type---e.g., @code{"x86_64-linux"} -for an x86_64 Linux-based GNU system. @var{store} must be a connection to -the daemon, which operates on the store (@pxref{The Store}). -@end deffn - -@noindent -@cindex cross-compilation -Similarly, it is possible to compute a derivation that cross-builds a -package for some other system: - -@deffn {Scheme Procedure} package-cross-derivation @var{store} @ - @var{package} @var{target} [@var{system}] Return the @code{} -object of @var{package} cross-built from @var{system} to @var{target}. - -@var{target} must be a valid GNU triplet denoting the target hardware and -operating system, such as @code{"mips64el-linux-gnu"} (@pxref{Configuration -Names, GNU configuration triplets,, configure, GNU Configure and Build -System}). -@end deffn - -@cindex package transformations -@cindex input rewriting -@cindex dependency tree rewriting -Packages can be manipulated in arbitrary ways. An example of a useful -transformation is @dfn{input rewriting}, whereby the dependency tree of a -package is rewritten by replacing specific inputs by others: - -@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @ - [@var{rewrite-name}] Return a procedure that, when passed a package, -replaces its direct and indirect dependencies (but not its implicit inputs) -according to @var{replacements}. @var{replacements} is a list of package -pairs; the first element of each pair is the package to replace, and the -second one is the replacement. - -Optionally, @var{rewrite-name} is a one-argument procedure that takes the -name of a package and returns its new name after rewrite. -@end deffn - -@noindent -Consider this example: - -@example -(define libressl-instead-of-openssl - ;; This is a procedure to replace OPENSSL by LIBRESSL, - ;; recursively. - (package-input-rewriting `((,openssl . ,libressl)))) - -(define git-with-libressl - (libressl-instead-of-openssl git)) -@end example - -@noindent -Here we first define a rewriting procedure that replaces @var{openssl} with -@var{libressl}. Then we use it to define a @dfn{variant} of the @var{git} -package that uses @var{libressl} instead of @var{openssl}. This is exactly -what the @option{--with-input} command-line option does (@pxref{Package -Transformation Options, @option{--with-input}}). - -The following variant of @code{package-input-rewriting} can match packages -to be replaced by name rather than by identity. - -@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} -Return a procedure that, given a package, applies the given -@var{replacements} to all the package graph (excluding implicit inputs). -@var{replacements} is a list of spec/procedures pair; each spec is a package -specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure -takes a matching package and returns a replacement for that package. -@end deffn - -The example above could be rewritten this way: - -@example -(define libressl-instead-of-openssl - ;; Replace all the packages called "openssl" with LibreSSL. - (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example - -The key difference here is that, this time, packages are matched by spec and -not by identity. In other words, any package in the graph that is called -@code{openssl} will be replaced. - -A more generic procedure to rewrite a package dependency graph is -@code{package-mapping}: it supports arbitrary changes to nodes in the graph. - -@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] -Return a procedure that, given a package, applies @var{proc} to all the -packages depended on and returns the resulting package. The procedure stops -recursion when @var{cut?} returns true for a given package. -@end deffn - -@menu -* package Reference:: The package data type. -* origin Reference:: The origin data type. -@end menu - - -@node package Reference -@subsection @code{package} Reference - -This section summarizes all the options available in @code{package} -declarations (@pxref{Defining Packages}). - -@deftp {Data Type} package -This is the data type representing a package recipe. - -@table @asis -@item @code{name} -The name of the package, as a string. - -@item @code{version} -The version of the package, as a string. - -@item @code{source} -An object telling how the source code for the package should be acquired. -Most of the time, this is an @code{origin} object, which denotes a file -fetched from the Internet (@pxref{origin Reference}). It can also be any -other ``file-like'' object such as a @code{local-file}, which denotes a file -from the local file system (@pxref{G-Expressions, @code{local-file}}). - -@item @code{build-system} -The build system that should be used to build the package (@pxref{Build -Systems}). - -@item @code{arguments} (default: @code{'()}) -The arguments that should be passed to the build system. This is a list, -typically containing sequential keyword-value pairs. - -@item @code{inputs} (default: @code{'()}) -@itemx @code{native-inputs} (default: @code{'()}) -@itemx @code{propagated-inputs} (default: @code{'()}) -@cindex inputs, of packages -These fields list dependencies of the package. Each one is a list of -tuples, where each tuple has a label for the input (a string) as its first -element, a package, origin, or derivation as its second element, and -optionally the name of the output thereof that should be used, which -defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for more -on package outputs). For example, the list below specifies three inputs: - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;the "bin" output of Glib -@end example - -@cindex cross compilation, package dependencies -The distinction between @code{native-inputs} and @code{inputs} is necessary -when considering cross-compilation. When cross-compiling, dependencies -listed in @code{inputs} are built for the @emph{target} architecture; -conversely, dependencies listed in @code{native-inputs} are built for the -architecture of the @emph{build} machine. - -@code{native-inputs} is typically used to list tools needed at build time, -but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or -Bison. @command{guix lint} can report likely mistakes in this area -(@pxref{Invoking guix lint}). - -@anchor{package-propagated-inputs} -Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the -specified packages will be automatically installed alongside the package -they belong to (@pxref{package-cmd-propagated-inputs, @command{guix -package}}, for information on how @command{guix package} deals with -propagated inputs.) - -For example this is necessary when a C/C++ library needs headers of another -library to compile, or when a pkg-config file refers to another one @i{via} -its @code{Requires} field. - -Another example where @code{propagated-inputs} is useful is for languages -that lack a facility to record the run-time search path akin to the -@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and more. -To ensure that libraries written in those languages can find library code -they depend on at run time, run-time dependencies must be listed in -@code{propagated-inputs} rather than @code{inputs}. - -@item @code{outputs} (default: @code{'("out")}) -The list of output names of the package. @xref{Packages with Multiple -Outputs}, for typical uses of additional outputs. - -@item @code{native-search-paths} (default: @code{'()}) -@itemx @code{search-paths} (default: @code{'()}) -A list of @code{search-path-specification} objects describing search-path -environment variables honored by the package. - -@item @code{replacement} (default: @code{#f}) -This must be either @code{#f} or a package object that will be used as a -@dfn{replacement} for this package. @xref{Security Updates, grafts}, for -details. - -@item @code{synopsis} -A one-line description of the package. - -@item @code{description} -A more elaborate description of the package. - -@item @code{license} -@cindex license, of packages -The license of the package; a value from @code{(guix licenses)}, or a list -of such values. - -@item @code{home-page} -The URL to the home-page of the package, as a string. - -@item @code{supported-systems} (default: @var{%supported-systems}) -The list of systems supported by the package, as strings of the form -@code{architecture-kernel}, for example @code{"x86_64-linux"}. - -@item @code{maintainers} (default: @code{'()}) -The list of maintainers of the package, as @code{maintainer} objects. - -@item @code{location} (default: source location of the @code{package} form) -The source location of the package. It is useful to override this when -inheriting from another package, in which case this field is not -automatically corrected. -@end table -@end deftp - -@deffn {Scheme Syntax} this-package -When used in the @emph{lexical scope} of a package field definition, this -identifier resolves to the package being defined. - -The example below shows how to add a package as a native input of itself -when cross-compiling: - -@example -(package - (name "guile") - ;; ... - - ;; When cross-compiled, Guile, for example, depends on - ;; a native version of itself. Add it here. - (native-inputs (if (%current-target-system) - `(("self" ,this-package)) - '()))) -@end example - -It is an error to refer to @code{this-package} outside a package definition. -@end deffn - -@node origin Reference -@subsection @code{origin} Reference - -This section summarizes all the options available in @code{origin} -declarations (@pxref{Defining Packages}). - -@deftp {Data Type} origin -This is the data type representing a source code origin. - -@table @asis -@item @code{uri} -An object containing the URI of the source. The object type depends on the -@code{method} (see below). For example, when using the @var{url-fetch} -method of @code{(guix download)}, the valid @code{uri} values are: a URL -represented as a string, or a list thereof. - -@item @code{method} -A procedure that handles the URI. - -Examples include: - -@table @asis -@item @var{url-fetch} from @code{(guix download)} -download a file from the HTTP, HTTPS, or FTP URL specified in the @code{uri} -field; - -@vindex git-fetch -@item @var{git-fetch} from @code{(guix git-download)} -clone the Git version control repository, and check out the revision -specified in the @code{uri} field as a @code{git-reference} object; a -@code{git-reference} looks like this: - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -A bytevector containing the SHA-256 hash of the source. Typically the -@code{base32} form is used here to generate the bytevector from a base-32 -string. - -You can obtain this information using @code{guix download} (@pxref{Invoking -guix download}) or @code{guix hash} (@pxref{Invoking guix hash}). - -@item @code{file-name} (default: @code{#f}) -The file name under which the source code should be saved. When this is -@code{#f}, a sensible default value will be used in most cases. In case the -source is fetched from a URL, the file name from the URL will be used. For -version control checkouts, it is recommended to provide the file name -explicitly because the default is not very descriptive. - -@item @code{patches} (default: @code{'()}) -A list of file names, origins, or file-like objects (@pxref{G-Expressions, -file-like objects}) pointing to patches to be applied to the source. - -This list of patches must be unconditional. In particular, it cannot depend -on the value of @code{%current-system} or @code{%current-target-system}. - -@item @code{snippet} (default: @code{#f}) -A G-expression (@pxref{G-Expressions}) or S-expression that will be run in -the source directory. This is a convenient way to modify the source, -sometimes more convenient than a patch. - -@item @code{patch-flags} (default: @code{'("-p1")}) -A list of command-line flags that should be passed to the @code{patch} -command. - -@item @code{patch-inputs} (default: @code{#f}) -Input packages or derivations to the patching process. When this is -@code{#f}, the usual set of inputs necessary for patching are provided, such -as GNU@tie{}Patch. - -@item @code{modules} (default: @code{'()}) -A list of Guile modules that should be loaded during the patching process -and while running the code in the @code{snippet} field. - -@item @code{patch-guile} (default: @code{#f}) -The Guile package that should be used in the patching process. When this is -@code{#f}, a sensible default is used. -@end table -@end deftp - - -@node Build Systems -@section Build Systems - -@cindex build system -Each package definition specifies a @dfn{build system} and arguments for -that build system (@pxref{Defining Packages}). This @code{build-system} -field represents the build procedure of the package, as well as implicit -dependencies of that build procedure. - -Build systems are @code{} objects. The interface to create -and manipulate them is provided by the @code{(guix build-system)} module, -and actual build systems are exported by specific modules. - -@cindex bag (low-level package representation) -Under the hood, build systems first compile package objects to @dfn{bags}. -A @dfn{bag} is like a package, but with less ornamentation---in other words, -a bag is a lower-level representation of a package, which includes all the -inputs of that package, including some that were implicitly added by the -build system. This intermediate representation is then compiled to a -derivation (@pxref{Derivations}). - -Build systems accept an optional list of @dfn{arguments}. In package -definitions, these are passed @i{via} the @code{arguments} field -(@pxref{Defining Packages}). They are typically keyword arguments -(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile -Reference Manual}). The value of these arguments is usually evaluated in -the @dfn{build stratum}---i.e., by a Guile process launched by the daemon -(@pxref{Derivations}). - -The main build system is @var{gnu-build-system}, which implements the -standard build procedure for GNU and many other packages. It is provided by -the @code{(guix build-system gnu)} module. - -@defvr {Scheme Variable} gnu-build-system -@var{gnu-build-system} represents the GNU Build System, and variants thereof -(@pxref{Configuration, configuration and makefile conventions,, standards, -GNU Coding Standards}). - -@cindex build phases -In a nutshell, packages using it are configured, built, and installed with -the usual @code{./configure && make && make check && make install} command -sequence. In practice, a few additional steps are often needed. All these -steps are split up in separate @dfn{phases}, notably@footnote{Please see the -@code{(guix build gnu-build-system)} modules for more details about the -build phases.}: - -@table @code -@item unpack -Unpack the source tarball, and change the current directory to the extracted -source tree. If the source is actually a directory, copy it to the build -tree, and enter that directory. - -@item patch-source-shebangs -Patch shebangs encountered in source files so they refer to the right store -file names. For instance, this changes @code{#!/bin/sh} to -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. - -@item configure -Run the @file{configure} script with a number of default options, such as -@code{--prefix=/gnu/store/@dots{}}, as well as the options specified by the -@code{#:configure-flags} argument. - -@item build -Run @code{make} with the list of flags specified with @code{#:make-flags}. -If the @code{#:parallel-build?} argument is true (the default), build with -@code{make -j}. - -@item check -Run @code{make check}, or some other target specified with -@code{#:test-target}, unless @code{#:tests? #f} is passed. If the -@code{#:parallel-tests?} argument is true (the default), run @code{make -check -j}. - -@item install -Run @code{make install} with the flags listed in @code{#:make-flags}. - -@item patch-shebangs -Patch shebangs on the installed executable files. - -@item strip -Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} is -false), copying them to the @code{debug} output when available -(@pxref{Installing Debugging Files}). -@end table - -@vindex %standard-phases -The build-side module @code{(guix build gnu-build-system)} defines -@var{%standard-phases} as the default list of build phases. -@var{%standard-phases} is a list of symbol/procedure pairs, where the -procedure implements the actual phase. - -The list of phases used for a particular package can be changed with the -@code{#:phases} parameter. For instance, passing: - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -means that all the phases described above will be used, except the -@code{configure} phase. - -In addition, this build system ensures that the ``standard'' environment for -GNU packages is available. This includes tools such as GCC, libc, -Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix -build-system gnu)} module for a complete list). We call these the -@dfn{implicit inputs} of a package, because package definitions do not have -to mention them. -@end defvr - -Other @code{} objects are defined to support other conventions -and tools used by free software packages. They inherit most of -@var{gnu-build-system}, and differ mainly in the set of inputs implicitly -added to the build process, and in the list of phases executed. Some of -these build systems are listed below. - -@defvr {Scheme Variable} ant-build-system -This variable is exported by @code{(guix build-system ant)}. It implements -the build procedure for Java packages that can be built with -@url{http://ant.apache.org/, Ant build tool}. - -It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided -by the @code{icedtea} package to the set of inputs. Different packages can -be specified with the @code{#:ant} and @code{#:jdk} parameters, -respectively. - -When the original package does not provide a suitable Ant build file, the -parameter @code{#:jar-name} can be used to generate a minimal Ant build file -@file{build.xml} with tasks to build the specified jar archive. In this -case the parameter @code{#:source-dir} can be used to specify the source -sub-directory, defaulting to ``src''. - -The @code{#:main-class} parameter can be used with the minimal ant buildfile -to specify the main class of the resulting jar. This makes the jar file -executable. The @code{#:test-include} parameter can be used to specify the -list of junit tests to run. It defaults to @code{(list "**/*Test.java")}. -The @code{#:test-exclude} can be used to disable some tests. It defaults to -@code{(list "**/Abstract*.java")}, because abstract classes cannot be run as -tests. - -The parameter @code{#:build-target} can be used to specify the Ant task that -should be run during the @code{build} phase. By default the ``jar'' task -will be run. - -@end defvr - -@defvr {Scheme Variable} android-ndk-build-system -@cindex Android distribution -@cindex Android NDK build system -This variable is exported by @code{(guix build-system android-ndk)}. It -implements a build procedure for Android NDK (native development kit) -packages using a Guix-specific build process. - -The build system assumes that packages install their public interface -(header) files to the subdirectory "include" of the "out" output and their -libraries to the subdirectory "lib" of the "out" output. - -It's also assumed that the union of all the dependencies of a package has no -conflicting files. - -For the time being, cross-compilation is not supported - so right now the -libraries and header files are assumed to be host tools. - -@end defvr - -@defvr {Scheme Variable} asdf-build-system/source -@defvrx {Scheme Variable} asdf-build-system/sbcl -@defvrx {Scheme Variable} asdf-build-system/ecl - -These variables, exported by @code{(guix build-system asdf)}, implement -build procedures for Common Lisp packages using -@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system -definition facility for Common Lisp programs and libraries. - -The @code{asdf-build-system/source} system installs the packages in source -form, and can be loaded using any common lisp implementation, via ASDF. The -others, such as @code{asdf-build-system/sbcl}, install binary systems in the -format which a particular implementation understands. These build systems -can also be used to produce executable programs, or lisp images which -contain a set of packages pre-loaded. - -The build system uses naming conventions. For binary packages, the package -name should be prefixed with the lisp implementation, such as @code{sbcl-} -for @code{asdf-build-system/sbcl}. - -Additionally, the corresponding source package should be labeled using the -same convention as python packages (see @ref{Python模块}), using the -@code{cl-} prefix. - -For binary packages, each system should be defined as a Guix package. If -one package @code{origin} contains several systems, package variants can be -created in order to build all the systems. Source packages, which use -@code{asdf-build-system/source}, may contain several systems. - -In order to create executable programs and images, the build-side procedures -@code{build-program} and @code{build-image} can be used. They should be -called in a build phase after the @code{create-symlinks} phase, so that the -system which was just built can be used within the resulting image. -@code{build-program} requires a list of Common Lisp expressions to be passed -as the @code{#:entry-program} argument. - -If the system is not defined within its own @code{.asd} file of the same -name, then the @code{#:asd-file} parameter should be used to specify which -file the system is defined in. Furthermore, if the package defines a system -for its tests in a separate file, it will be loaded before the tests are run -if it is specified by the @code{#:test-asd-file} parameter. If it is not -set, the files @code{-tests.asd}, @code{-test.asd}, -@code{tests.asd}, and @code{test.asd} will be tried if they exist. - -If for some reason the package must be named in a different way than the -naming conventions suggest, the @code{#:asd-system-name} parameter can be -used to specify the name of the system. - -@end defvr - -@defvr {Scheme Variable} cargo-build-system -@cindex Rust programming language -@cindex Cargo (Rust build system) -This variable is exported by @code{(guix build-system cargo)}. It supports -builds of packages using Cargo, the build tool of the -@uref{https://www.rust-lang.org, Rust programming language}. - -In its @code{configure} phase, this build system replaces dependencies -specified in the @file{Carto.toml} file with inputs to the Guix package. -The @code{install} phase installs the binaries, and it also installs the -source code and @file{Cargo.toml} file. -@end defvr - -@cindex Clojure (programming language) -@cindex simple Clojure build system -@defvr {Scheme Variable} clojure-build-system -This variable is exported by @code{(guix build-system clojure)}. It -implements a simple build procedure for @uref{https://clojure.org/, Clojure} -packages using plain old @code{compile} in Clojure. Cross-compilation is -not supported yet. - -It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs. -Different packages can be specified with the @code{#:clojure}, @code{#:jdk} -and @code{#:zip} parameters, respectively. - -A list of source directories, test directories and jar names can be -specified with the @code{#:source-dirs}, @code{#:test-dirs} and -@code{#:jar-names} parameters, respectively. Compile directory and main -class can be specified with the @code{#:compile-dir} and @code{#:main-class} -parameters, respectively. Other parameters are documented below. - -This build system is an extension of @var{ant-build-system}, but with the -following phases changed: - -@table @code - -@item build -This phase calls @code{compile} in Clojure to compile source files and runs -@command{jar} to create jars from both source files and compiled files -according to the include list and exclude list specified in -@code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude -list has priority over the include list. These lists consist of symbols -representing Clojure libraries or the special keyword @code{#:all} -representing all Clojure libraries found under the source directories. The -parameter @code{#:omit-source?} decides if source should be included into -the jars. - -@item check -This phase runs tests according to the include list and exclude list -specified in @code{#:test-include} and @code{#:test-exclude}, respectively. -Their meanings are analogous to that of @code{#:aot-include} and -@code{#:aot-exclude}, except that the special keyword @code{#:all} now -stands for all Clojure libraries found under the test directories. The -parameter @code{#:tests?} decides if tests should be run. - -@item install -This phase installs all jars built previously. -@end table - -Apart from the above, this build system also contains an additional phase: - -@table @code - -@item install-doc -This phase installs all top-level files with base name matching -@var{%doc-regex}. A different regex can be specified with the -@code{#:doc-regex} parameter. All files (recursively) inside the -documentation directories specified in @code{#:doc-dirs} are installed as -well. -@end table -@end defvr - -@defvr {Scheme Variable} cmake-build-system -This variable is exported by @code{(guix build-system cmake)}. It -implements the build procedure for packages using the -@url{http://www.cmake.org, CMake build tool}. - -It automatically adds the @code{cmake} package to the set of inputs. Which -package is used can be specified with the @code{#:cmake} parameter. - -The @code{#:configure-flags} parameter is taken as a list of flags passed to -the @command{cmake} command. The @code{#:build-type} parameter specifies in -abstract terms the flags passed to the compiler; it defaults to -@code{"RelWithDebInfo"} (short for ``release mode with debugging -information''), which roughly means that code is compiled with @code{-O2 --g}, as is the case for Autoconf-based packages by default. -@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}. - -The @code{#:package} parameter can be passed to specify a package name, -which is useful when a package contains multiple packages and you want to -build only one of them. This is equivalent to passing the @code{-p} -argument to @code{dune}. -@end defvr - -@defvr {Scheme Variable} go-build-system -This variable is exported by @code{(guix build-system go)}. It implements a -build procedure for Go packages using the standard -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, Go -build mechanisms}. - -The user is expected to provide a value for the key @code{#:import-path} -and, in some cases, @code{#:unpack-path}. The -@url{https://golang.org/doc/code.html#ImportPaths, import path} corresponds -to the file system path expected by the package's build scripts and any -referring packages, and provides a unique way to refer to a Go package. It -is typically based on a combination of the package source code's remote URI -and file system hierarchy structure. In some cases, you will need to unpack -the package's source code to a different directory structure than the one -indicated by the import path, and @code{#:unpack-path} should be used in -such cases. - -Packages that provide Go libraries should install their source code into the -built output. The key @code{#:install-source?}, which defaults to -@code{#t}, controls whether or not the source code is installed. It can be -set to @code{#f} for packages that only provide executable files. -@end defvr - -@defvr {Scheme Variable} glib-or-gtk-build-system -This variable is exported by @code{(guix build-system glib-or-gtk)}. It is -intended for use with packages making use of GLib or GTK+. - -This build system adds the following two phases to the ones defined by -@var{gnu-build-system}: - -@table @code -@item glib-or-gtk-wrap -The phase @code{glib-or-gtk-wrap} ensures that programs in @file{bin/} are -able to find GLib ``schemas'' and -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+ -modules}. This is achieved by wrapping the programs in launch scripts that -appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH} environment -variables. - -It is possible to exclude specific package outputs from that wrapping -process by listing their names in the -@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful when -an output is known not to contain any GLib or GTK+ binaries, and where -wrapping would gratuitously add a dependency of that output on GLib and -GTK+. - -@item glib-or-gtk-compile-schemas -The phase @code{glib-or-gtk-compile-schemas} makes sure that all -@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -GSettings schemas} of GLib are compiled. Compilation is performed by the -@command{glib-compile-schemas} program. It is provided by the package -@code{glib:bin} which is automatically imported by the build system. The -@code{glib} package providing @command{glib-compile-schemas} can be -specified with the @code{#:glib} parameter. -@end table - -Both phases are executed after the @code{install} phase. -@end defvr - -@defvr {Scheme Variable} guile-build-system -This build system is for Guile packages that consist exclusively of Scheme -code and that are so lean that they don't even have a makefile, let alone a -@file{configure} script. It compiles Scheme code using @command{guild -compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and -installs the @file{.scm} and @file{.go} files in the right place. It also -installs documentation. - -This build system supports cross-compilation by using the @code{--target} -option of @command{guild compile}. - -Packages built with @code{guile-build-system} must provide a Guile package -in their @code{native-inputs} field. -@end defvr - -@defvr {Scheme Variable} minify-build-system -This variable is exported by @code{(guix build-system minify)}. It -implements a minification procedure for simple JavaScript packages. - -It adds @code{uglify-js} to the set of inputs and uses it to compress all -JavaScript files in the @file{src} directory. A different minifier package -can be specified with the @code{#:uglify-js} parameter, but it is expected -that the package writes the minified code to the standard output. - -When the input JavaScript files are not all located in the @file{src} -directory, the parameter @code{#:javascript-files} can be used to specify a -list of file names to feed to the minifier. -@end defvr - -@defvr {Scheme Variable} ocaml-build-system -This variable is exported by @code{(guix build-system ocaml)}. It -implements a build procedure for @uref{https://ocaml.org, OCaml} packages, -which consists of choosing the correct set of commands to run for each -package. OCaml packages can expect many different commands to be run. This -build system will try some of them. - -When the package has a @file{setup.ml} file present at the top-level, it -will run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and -@code{ocaml setup.ml -install}. The build system will assume that this file -was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will -take care of setting the prefix and enabling tests if they are not -disabled. You can pass configure and build flags with the -@code{#:configure-flags} and @code{#:build-flags}. The @code{#:test-flags} -key can be passed to change the set of flags used to enable tests. The -@code{#:use-make?} key can be used to bypass this system in the build and -install phases. - -When the package has a @file{configure} file, it is assumed that it is a -hand-made configure script that requires a different argument format than in -the @code{gnu-build-system}. You can add more flags with the -@code{#:configure-flags} key. - -When the package has a @file{Makefile} file (or @code{#:use-make?} is -@code{#t}), it will be used and more flags can be passed to the build and -install phases with the @code{#:make-flags} key. - -Finally, some packages do not have these files and use a somewhat standard -location for its build system. In that case, the build system will run -@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of -providing the path to the required findlib module. Additional flags can be -passed via the @code{#:build-flags} key. Install is taken care of by -@command{opam-installer}. In this case, the @code{opam} package must be -added to the @code{native-inputs} field of the package definition. - -Note that most OCaml packages assume they will be installed in the same -directory as OCaml, which is not what we want in guix. In particular, they -will install @file{.so} files in their module's directory, which is usually -fine because it is in the OCaml compiler directory. In guix though, these -libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This -variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where -@file{.so} libraries should be installed. -@end defvr - -@defvr {Scheme Variable} python-build-system -This variable is exported by @code{(guix build-system python)}. It -implements the more or less standard build procedure used by Python -packages, which consists in running @code{python setup.py build} and then -@code{python setup.py install --prefix=/gnu/store/@dots{}}. - -For packages that install stand-alone Python programs under @code{bin/}, it -takes care of wrapping these programs so that their @code{PYTHONPATH} -environment variable points to all the Python libraries they depend on. - -Which Python package is used to perform the build can be specified with the -@code{#:python} parameter. This is a useful way to force a package to be -built for a specific version of the Python interpreter, which might be -necessary if the package is only compatible with a single interpreter -version. - -By default guix calls @code{setup.py} under control of @code{setuptools}, -much like @command{pip} does. Some packages are not compatible with -setuptools (and pip), thus you can disable this by setting the -@code{#:use-setuptools} parameter to @code{#f}. -@end defvr - -@defvr {Scheme Variable} perl-build-system -This variable is exported by @code{(guix build-system perl)}. It implements -the standard build procedure for Perl packages, which either consists in -running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, followed by -@code{Build} and @code{Build install}; or in running @code{perl Makefile.PL -PREFIX=/gnu/store/@dots{}}, followed by @code{make} and @code{make install}, -depending on which of @code{Build.PL} or @code{Makefile.PL} is present in -the package distribution. Preference is given to the former if both -@code{Build.PL} and @code{Makefile.PL} exist in the package distribution. -This preference can be reversed by specifying @code{#t} for the -@code{#:make-maker?} parameter. - -The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation -passes flags specified by the @code{#:make-maker-flags} or -@code{#:module-build-flags} parameter, respectively. - -Which Perl package is used can be specified with @code{#:perl}. -@end defvr - -@defvr {Scheme Variable} r-build-system -This variable is exported by @code{(guix build-system r)}. It implements -the build procedure used by @uref{http://r-project.org, R} packages, which -essentially is little more than running @code{R CMD INSTALL ---library=/gnu/store/@dots{}} in an environment where @code{R_LIBS_SITE} -contains the paths to all R package inputs. Tests are run after -installation using the R function @code{tools::testInstalledPackage}. -@end defvr - -@defvr {Scheme Variable} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It implements -the build procedure used by @uref{https://rakudo.org/, Rakudo} for -@uref{https://perl6.org/, Perl6} packages. It installs the package to -@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the -binaries, library files and the resources, as well as wrap the files under -the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the -@code{tests?} parameter. - -Which rakudo package is used can be specified with @code{rakudo}. Which -perl6-tap-harness package used for the tests can be specified with -@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} -parameter. Which perl6-zef package used for tests and installing can be -specified with @code{#:zef} or removed by passing @code{#f} to the -@code{with-zef?} parameter. -@end defvr - -@defvr {Scheme Variable} texlive-build-system -This variable is exported by @code{(guix build-system texlive)}. It is used -to build TeX packages in batch mode with a specified engine. The build -system sets the @code{TEXINPUTS} variable to find all TeX source files in -the inputs. - -By default it runs @code{luatex} on all files ending on @code{ins}. A -different engine and format can be specified with the @code{#:tex-format} -argument. Different build targets can be specified with the -@code{#:build-targets} argument, which expects a list of file names. The -build system adds only @code{texlive-bin} and @code{texlive-latex-base} -(both from @code{(gnu packages tex}) to the inputs. Both can be overridden -with the arguments @code{#:texlive-bin} and @code{#:texlive-latex-base}, -respectively. - -The @code{#:tex-directory} parameter tells the build system where to install -the built files under the texmf tree. -@end defvr - -@defvr {Scheme Variable} ruby-build-system -This variable is exported by @code{(guix build-system ruby)}. It implements -the RubyGems build procedure used by Ruby packages, which involves running -@code{gem build} followed by @code{gem install}. - -The @code{source} field of a package that uses this build system typically -references a gem archive, since this is the format that Ruby developers use -when releasing their software. The build system unpacks the gem archive, -potentially patches the source, runs the test suite, repackages the gem, and -installs it. Additionally, directories and tarballs may be referenced to -allow building unreleased gems from Git or a traditional source release -tarball. - -Which Ruby package is used can be specified with the @code{#:ruby} -parameter. A list of additional flags to be passed to the @command{gem} -command can be specified with the @code{#:gem-flags} parameter. -@end defvr - -@defvr {Scheme Variable} waf-build-system -This variable is exported by @code{(guix build-system waf)}. It implements -a build procedure around the @code{waf} script. The common -phases---@code{configure}, @code{build}, and @code{install}---are -implemented by passing their names as arguments to the @code{waf} script. - -The @code{waf} script is executed by the Python interpreter. Which Python -package is used to run the script can be specified with the @code{#:python} -parameter. -@end defvr - -@defvr {Scheme Variable} scons-build-system -This variable is exported by @code{(guix build-system scons)}. It -implements the build procedure used by the SCons software construction -tool. This build system runs @code{scons} to build the package, @code{scons -test} to run tests, and then @code{scons install} to install the package. - -Additional flags to be passed to @code{scons} can be specified with the -@code{#:scons-flags} parameter. The version of Python used to run SCons can -be specified by selecting the appropriate SCons package with the -@code{#:scons} parameter. -@end defvr - -@defvr {Scheme Variable} haskell-build-system -This variable is exported by @code{(guix build-system haskell)}. It -implements the Cabal build procedure used by Haskell packages, which -involves running @code{runhaskell Setup.hs configure ---prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}. Instead -of installing the package by running @code{runhaskell Setup.hs install}, to -avoid trying to register libraries in the read-only compiler store -directory, the build system uses @code{runhaskell Setup.hs copy}, followed -by @code{runhaskell Setup.hs register}. In addition, the build system -generates the package documentation by running @code{runhaskell Setup.hs -haddock}, unless @code{#:haddock? #f} is passed. Optional Haddock -parameters can be passed with the help of the @code{#:haddock-flags} -parameter. If the file @code{Setup.hs} is not found, the build system looks -for @code{Setup.lhs} instead. - -Which Haskell compiler is used can be specified with the @code{#:haskell} -parameter which defaults to @code{ghc}. -@end defvr - -@defvr {Scheme Variable} dub-build-system -This variable is exported by @code{(guix build-system dub)}. It implements -the Dub build procedure used by D packages, which involves running @code{dub -build} and @code{dub run}. Installation is done by copying the files -manually. - -Which D compiler is used can be specified with the @code{#:ldc} parameter -which defaults to @code{ldc}. -@end defvr - -@defvr {Scheme Variable} emacs-build-system -This variable is exported by @code{(guix build-system emacs)}. It -implements an installation procedure similar to the packaging system of -Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -It first creates the @code{@var{package}-autoloads.el} file, then it byte -compiles all Emacs Lisp files. Differently from the Emacs packaging system, -the Info documentation files are moved to the standard documentation -directory and the @file{dir} file is deleted. Each package is installed in -its own directory under @file{share/emacs/site-lisp/guix.d}. -@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 -This variable is exported by @code{(guix build-system meson)}. It -implements the build procedure for packages that use -@url{http://mesonbuild.com, Meson} as their build system. - -It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of -inputs, and they can be changed with the parameters @code{#:meson} and -@code{#:ninja} if needed. The default Meson is @code{meson-for-build}, -which is special because it doesn't clear the @code{RUNPATH} of binaries and -libraries when they are installed. - -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed to some specific for Meson: - -@table @code - -@item configure -The phase runs @code{meson} with the flags specified in -@code{#:configure-flags}. The flag @code{--build-type} is always set to -@code{plain} unless something else is specified in @code{#:build-type}. - -@item build -The phase runs @code{ninja} to build the package in parallel by default, but -this can be changed with @code{#:parallel-build?}. - -@item check -The phase runs @code{ninja} with the target specified in -@code{#:test-target}, which is @code{"test"} by default. - -@item install -The phase runs @code{ninja install} and can not be changed. -@end table - -Apart from that, the build system also adds the following phases: - -@table @code - -@item fix-runpath -This phase ensures that all binaries can find the libraries they need. It -searches for required libraries in subdirectories of the package being -built, and adds those to @code{RUNPATH} where needed. It also removes -references to libraries left over from the build phase by -@code{meson-for-build}, such as test dependencies, that aren't actually -required for the program to run. - -@item glib-or-gtk-wrap -This phase is the phase provided by @code{glib-or-gtk-build-system}, and it -is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. - -@item glib-or-gtk-compile-schemas -This phase is the phase provided by @code{glib-or-gtk-build-system}, and it -is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. -@end table -@end defvr - -@defvr {Scheme Variable} linux-module-build-system -@var{linux-module-build-system} allows building Linux kernel modules. - -@cindex build phases -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed: - -@table @code - -@item configure -This phase configures the environment so that the Linux kernel's Makefile -can be used to build the external kernel module. - -@item build -This phase uses the Linux kernel's Makefile in order to build the external -kernel module. - -@item install -This phase uses the Linux kernel's Makefile in order to install the external -kernel module. -@end table - -It is possible and useful to specify the Linux kernel to use for building -the module (in the "arguments" form of a package using the -linux-module-build-system, use the key #:linux to specify it). -@end defvr - -Lastly, for packages that do not need anything as sophisticated, a -``trivial'' build system is provided. It is trivial in the sense that it -provides basically no support: it does not pull any implicit inputs, and -does not have a notion of build phases. - -@defvr {Scheme Variable} trivial-build-system -This variable is exported by @code{(guix build-system trivial)}. - -This build system requires a @code{#:builder} argument. This argument must -be a Scheme expression that builds the package output(s)---as with -@code{build-expression->derivation} (@pxref{Derivations, -@code{build-expression->derivation}}). -@end defvr - -@node The Store -@section The Store - -@cindex store -@cindex store items -@cindex store paths - -Conceptually, the @dfn{store} is the place where derivations that have been -built successfully are stored---by default, @file{/gnu/store}. -Sub-directories in the store are referred to as @dfn{store items} or -sometimes @dfn{store paths}. The store has an associated database that -contains information such as the store paths referred to by each store path, -and the list of @emph{valid} store items---results of successful builds. -This database resides in @file{@var{localstatedir}/guix/db}, where -@var{localstatedir} is the state directory specified @i{via} -@option{--localstatedir} at configure time, usually @file{/var}. - -The store is @emph{always} accessed by the daemon on behalf of its clients -(@pxref{Invoking guix-daemon}). To manipulate the store, clients connect to -the daemon over a Unix-domain socket, send requests to it, and read the -result---these are remote procedure calls, or RPCs. - -@quotation Note -Users must @emph{never} modify files under @file{/gnu/store} directly. This -would lead to inconsistencies and break the immutability assumptions of -Guix's functional model (@pxref{Introduction}). - -@xref{Invoking guix gc, @command{guix gc --verify}}, for information on how -to check the integrity of the store and attempt recovery from accidental -modifications. -@end quotation - -The @code{(guix store)} module provides procedures to connect to the daemon, -and to perform RPCs. These are described below. By default, -@code{open-connection}, and thus all the @command{guix} commands, connect to -the local daemon or to the URI specified by the @code{GUIX_DAEMON_SOCKET} -environment variable. - -@defvr {Environment Variable} GUIX_DAEMON_SOCKET -When set, the value of this variable should be a file name or a URI -designating the daemon endpoint. When it is a file name, it denotes a -Unix-domain socket to connect to. In addition to file names, the supported -URI schemes are: - -@table @code -@item file -@itemx unix -These are for Unix-domain sockets. -@code{file:///var/guix/daemon-socket/socket} is equivalent to -@file{/var/guix/daemon-socket/socket}. - -@item guix -@cindex daemon, remote access -@cindex remote access to the daemon -@cindex daemon, cluster setup -@cindex clusters, daemon setup -These URIs denote connections over TCP/IP, without encryption nor -authentication of the remote host. The URI must specify the host name and -optionally a port number (by default port 44146 is used): - -@example -guix://master.guix.example.org:1234 -@end example - -This setup is suitable on local networks, such as clusters, where only -trusted nodes may connect to the build daemon at -@code{master.guix.example.org}. - -The @code{--listen} option of @command{guix-daemon} can be used to instruct -it to listen for TCP connections (@pxref{Invoking guix-daemon, -@code{--listen}}). - -@item ssh -@cindex SSH access to build daemons -These URIs allow you to connect to a remote daemon over SSH@footnote{This -feature requires Guile-SSH (@pxref{Requirements}).}. A typical URL might -look like this: - -@example -ssh://charlie@@guix.example.org:22 -@end example - -As for @command{guix copy}, the usual OpenSSH client configuration files are -honored (@pxref{Invoking guix copy}). -@end table - -Additional URI schemes may be supported in the future. - -@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 Note -The ability to connect to remote build daemons is considered experimental as -of @value{VERSION}. Please get in touch with us to share any problems or -suggestions you may have (@pxref{贡献}). -@end quotation -@end defvr - -@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t] -Connect to the daemon over the Unix-domain socket at @var{uri} (a string). -When @var{reserve-space?} is true, instruct it to reserve a little bit of -extra space on the file system so that the garbage collector can still -operate should the disk become full. Return a server object. - -@var{file} defaults to @var{%default-socket-path}, which is the normal -location given the options that were passed to @command{configure}. -@end deffn - -@deffn {Scheme Procedure} close-connection @var{server} -Close the connection to @var{server}. -@end deffn - -@defvr {Scheme Variable} current-build-output-port -This variable is bound to a SRFI-39 parameter, which refers to the port -where build and error logs sent by the daemon should be written. -@end defvr - -Procedures that make RPCs all take a server object as their first argument. - -@deffn {Scheme Procedure} valid-path? @var{server} @var{path} -@cindex invalid store items -Return @code{#t} when @var{path} designates a valid store item and @code{#f} -otherwise (an invalid item may exist on disk but still be invalid, for -instance because it is the result of an aborted or failed build.) - -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 Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] -Add @var{text} under file @var{name} in the store, and return its store -path. @var{references} is the list of store paths referred to by the -resulting store path. -@end deffn - -@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations} -Build @var{derivations} (a list of @code{} objects or derivation -paths), and return when the worker is done building them. Return @code{#t} -on success. -@end deffn - -Note that the @code{(guix monads)} module provides a monad as well as -monadic versions of the above procedures, with the goal of making it more -convenient to work with code that accesses the store (@pxref{The Store -Monad}). - -@c FIXME -@i{This section is currently incomplete.} - -@node Derivations -@section Derivations - -@cindex derivations -Low-level build actions and the environment in which they are performed are -represented by @dfn{derivations}. A derivation contains the following -pieces of information: - -@itemize -@item -The outputs of the derivation---derivations produce at least one file or -directory in the store, but may produce more. - -@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 -The system type targeted by the derivation---e.g., @code{x86_64-linux}. - -@item -The file name of a build script in the store, along with the arguments to be -passed. - -@item -A list of environment variables to be defined. - -@end itemize - -@cindex derivation path -Derivations allow clients of the daemon to communicate build actions to the -store. They exist in two forms: as an in-memory representation, both on the -client- and daemon-side, and as files in the store whose name end in -@code{.drv}---these files are referred to as @dfn{derivation paths}. -Derivations paths can be passed to the @code{build-derivations} procedure to -perform the build actions they prescribe (@pxref{The Store}). - -@cindex fixed-output derivations -Operations such as file downloads and version-control checkouts for which -the expected content hash is known in advance are modeled as -@dfn{fixed-output derivations}. Unlike regular derivations, the outputs of -a fixed-output derivation are independent of its inputs---e.g., a source -code download produces the same result regardless of the download method and -tools being used. - -@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{Invoking 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. - -The @code{(guix derivations)} module provides a representation of -derivations as Scheme objects, along with procedures to create and otherwise -manipulate derivations. The lowest-level primitive to create a derivation -is the @code{derivation} procedure: - -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @ - @var{args} [#: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 '()] Build a derivation with the given -arguments, and return the resulting @code{} object. - -When @var{hash} and @var{hash-algo} are given, a @dfn{fixed-output -derivation} is created---i.e., one whose result is known in advance, such as -a file download. If, in addition, @var{recursive?} is true, then that fixed -output may be an executable file or a directory and @var{hash} must be the -hash of an archive containing this output. - -When @var{references-graphs} is true, it must be a list of file name/store -path pairs. In that case, the reference graph of each store path is -exported in the build environment in the corresponding file, in a simple -text format. - -When @var{allowed-references} is true, it must be a list of store items or -outputs that the derivation's output may refer to. Likewise, -@var{disallowed-references}, if true, must be a list of things the outputs -may @emph{not} refer to. - -When @var{leaked-env-vars} is true, it must be a list of strings denoting -environment variables that are allowed to ``leak'' from the daemon's -environment to the build environment. This is only applicable to -fixed-output derivations---i.e., when @var{hash} is true. The main use is -to allow variables such as @code{http_proxy} to be passed to derivations -that download files. - -When @var{local-build?} is true, declare that the derivation is not a good -candidate for offloading and should rather be built locally (@pxref{Daemon -Offload Setup}). This is the case for small derivations where the costs of -data transfers would outweigh the benefits. - -When @var{substitutable?} is false, declare that substitutes of the -derivation's output should not be used (@pxref{Substitutes}). This is -useful, for instance, when building packages that capture details of the -host CPU instruction set. - -@var{properties} must be an association list describing ``properties'' of -the derivation. It is kept as-is, uninterpreted, in the derivation. -@end deffn - -@noindent -Here's an example with a shell script as its builder, assuming @var{store} -is an open connection to the daemon, and @var{bash} points to a Bash -executable in the store: - -@lisp -(use-modules (guix utils) - (guix store) - (guix derivations)) - -(let ((builder ; add the Bash script to the store - (add-text-to-store store "my-builder.sh" - "echo hello world > $out\n" '()))) - (derivation store "foo" - bash `("-e" ,builder) - #:inputs `((,bash) (,builder)) - #:env-vars '(("HOME" . "/homeless")))) -@result{} # /gnu/store/@dots{}-foo> -@end lisp - -As can be guessed, this primitive is cumbersome to use directly. A better -approach is to write build scripts in Scheme, of course! The best course of -action for that is to write the build code as a ``G-expression'', and to -pass it to @code{gexp->derivation}. For more information, -@pxref{G-Expressions}. - -Once upon a time, @code{gexp->derivation} did not exist and constructing -derivations with build code written in Scheme was achieved with -@code{build-expression->derivation}, documented below. This procedure is -now deprecated in favor of the much nicer @code{gexp->derivation}. - -@deffn {Scheme Procedure} build-expression->derivation @var{store} @ - @var{name} @var{exp} @ [#: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] Return a derivation that -executes Scheme expression @var{exp} as a builder for derivation -@var{name}. @var{inputs} must be a list of @code{(name drv-path sub-drv)} -tuples; when @var{sub-drv} is omitted, @code{"out"} is assumed. -@var{modules} is a list of names of Guile modules from the current search -path to be copied in the store, compiled, and made available in the load -path during the execution of @var{exp}---e.g., @code{((guix build utils) -(guix build gnu-build-system))}. - -@var{exp} is evaluated in an environment where @code{%outputs} is bound to a -list of output/path pairs, and where @code{%build-inputs} is bound to a list -of string/output-path pairs made from @var{inputs}. Optionally, -@var{env-vars} is a list of string pairs specifying the name and value of -environment variables visible to the builder. The builder terminates by -passing the result of @var{exp} to @code{exit}; thus, when @var{exp} returns -@code{#f}, the build is considered to have failed. - -@var{exp} is built using @var{guile-for-build} (a derivation). When -@var{guile-for-build} is omitted or is @code{#f}, the value of the -@code{%guile-for-build} fluid is used instead. - -See the @code{derivation} procedure for the meaning of -@var{references-graphs}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?}, and @var{substitutable?}. -@end deffn - -@noindent -Here's an example of a single-output derivation that creates a directory -containing one file: - -@lisp -(let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; create /gnu/store/@dots{}-goo - (call-with-output-file (string-append out "/test") - (lambda (p) - (display '(hello guix) p)))))) - (build-expression->derivation store "goo" builder)) - -@result{} # @dots{}> -@end lisp - - -@node The Store Monad -@section The Store Monad - -@cindex monad - -The procedures that operate on the store described in the previous sections -all take an open connection to the build daemon as their first argument. -Although the underlying model is functional, they either have side effects -or depend on the current state of the store. - -The former is inconvenient: the connection to the build daemon has to be -carried around in all those functions, making it impossible to compose -functions that do not take that parameter with functions that do. The -latter can be problematic: since store operations have side effects and/or -depend on external state, they have to be properly sequenced. - -@cindex monadic values -@cindex monadic functions -This is where the @code{(guix monads)} module comes in. This module -provides a framework for working with @dfn{monads}, and a particularly -useful monad for our uses, the @dfn{store monad}. Monads are a construct -that allows two things: associating ``context'' with values (in our case, -the context is the store), and building sequences of computations (here -computations include accesses to the store). Values in a monad---values -that carry this additional context---are called @dfn{monadic values}; -procedures that return such values are called @dfn{monadic procedures}. - -Consider this ``normal'' procedure: - -@example -(define (sh-symlink store) - ;; Return a derivation that symlinks the 'bash' executable. - (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 - -Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten as a -monadic function: - -@example -(define (sh-symlink) - ;; Same, but return a monadic value. - (mlet %store-monad ((drv (package->derivation bash))) - (gexp->derivation "sh" - #~(symlink (string-append #$drv "/bin/bash") - #$output)))) -@end example - -There are several things to note in the second version: the @code{store} -parameter is now implicit and is ``threaded'' in the calls to the -@code{package->derivation} and @code{gexp->derivation} monadic procedures, -and the monadic value returned by @code{package->derivation} is @dfn{bound} -using @code{mlet} instead of plain @code{let}. - -As it turns out, the call to @code{package->derivation} can even be omitted -since it will take place implicitly, as we will see later -(@pxref{G-Expressions}): - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c -@c for the funny quote. -Calling the monadic @code{sh-symlink} has no effect. As someone once said, -``you exit a monad like you exit a building on fire: by running''. So, to -exit the monad and get the desired effect, one must use -@code{run-with-store}: - -@example -(run-with-store (open-connection) (sh-symlink)) -@result{} /gnu/store/...-sh-symlink -@end example - -Note that the @code{(guix monad-repl)} module extends the Guile REPL with -new ``meta-commands'' to make it easier to deal with monadic procedures: -@code{run-in-store}, and @code{enter-store-monad}. The former is used to -``run'' a single monadic value through the store: - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = # @dots{}> -@end example - -The latter enters a recursive REPL, where all the return values are -automatically run through the store: - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = # @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Note that non-monadic values cannot be returned in the @code{store-monad} -REPL. - -The main syntactic forms to deal with monads in general are provided by the -@code{(guix monads)} module and are described below. - -@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ... -Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in -@var{monad}. -@end deffn - -@deffn {Scheme Syntax} return @var{val} -Return a monadic value that encapsulates @var{val}. -@end deffn - -@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ... -@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic -procedures @var{mproc}@dots{}@footnote{This operation is commonly referred -to as ``bind'', but that name denotes an unrelated procedure in Guile. Thus -we use this somewhat cryptic symbol inherited from the Haskell language.}. -There can be one @var{mproc} or several of them, as in this example: - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'some-state) - -@result{} 4 -@result{} some-state -@end example -@end deffn - -@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... Bind the variables @var{var} to the monadic values -@var{mval} in @var{body}, which is a sequence of expressions. As with the -bind operator, this can be thought of as ``unpacking'' the raw, non-monadic -value ``contained'' in @var{mval} and making @var{var} refer to that raw, -non-monadic value within the scope of the @var{body}. The form (@var{var} --> @var{val}) binds @var{var} to the ``normal'' value @var{val}, as per -@code{let}. The binding operations occur in sequence from left to right. -The last expression of @var{body} must be a monadic expression, and its -result will become the result of the @code{mlet} or @code{mlet*} when run in -the @var{monad}. - -@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} -(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn - -@deffn {Scheme System} mbegin @var{monad} @var{mexp} ... -Bind @var{mexp} and the following monadic expressions in sequence, returning -the result of the last expression. Every expression in the sequence must be -a monadic expression. - -This is akin to @code{mlet}, except that the return values of the monadic -expressions are ignored. In that sense, it is analogous to @code{begin}, -but applied to monadic expressions. -@end deffn - -@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ... -When @var{condition} is true, evaluate the sequence of monadic expressions -@var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is -false, return @code{*unspecified*} in the current monad. Every expression -in the sequence must be a monadic expression. -@end deffn - -@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ... -When @var{condition} is false, evaluate the sequence of monadic expressions -@var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is -true, return @code{*unspecified*} in the current monad. Every expression in -the sequence must be a monadic expression. -@end deffn - -@cindex state monad -The @code{(guix monads)} module provides the @dfn{state monad}, which allows -an additional value---the state---to be @emph{threaded} through monadic -procedure calls. - -@defvr {Scheme Variable} %state-monad -The state monad. Procedures in the state monad can access and change the -state that is threaded. - -Consider the example below. The @code{square} procedure returns a value in -the state monad. It returns the square of its argument, but also increments -the current state value: - -@example -(define (square x) - (mlet %state-monad ((count (current-state))) - (mbegin %state-monad - (set-current-state (+ 1 count)) - (return (* x x))))) - -(run-with-state (sequence %state-monad (map square (iota 3))) 0) -@result{} (0 1 4) -@result{} 3 -@end example - -When ``run'' through @var{%state-monad}, we obtain that additional state -value, which is the number of @code{square} calls. -@end defvr - -@deffn {Monadic Procedure} current-state -Return the current state as a monadic value. -@end deffn - -@deffn {Monadic Procedure} set-current-state @var{value} -Set the current state to @var{value} and return the previous state as a -monadic value. -@end deffn - -@deffn {Monadic Procedure} state-push @var{value} -Push @var{value} to the current state, which is assumed to be a list, and -return the previous state as a monadic value. -@end deffn - -@deffn {Monadic Procedure} state-pop -Pop a value from the current state and return it as a monadic value. The -state is assumed to be a list. -@end deffn - -@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}] -Run monadic value @var{mval} starting with @var{state} as the initial -state. Return two values: the resulting value, and the resulting state. -@end deffn - -The main interface to the store monad, provided by the @code{(guix store)} -module, is as follows. - -@defvr {Scheme Variable} %store-monad -The store monad---an alias for @var{%state-monad}. - -Values in the store monad encapsulate accesses to the store. When its -effect is needed, a value of the store monad must be ``evaluated'' by -passing it to the @code{run-with-store} procedure (see below.) -@end defvr - -@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] -Run @var{mval}, a monadic value in the store monad, in @var{store}, an open -store connection. -@end deffn - -@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}] -Return as a monadic value the absolute file name in the store of the file -containing @var{text}, a string. @var{references} is a list of store items -that the resulting text file refers to; it defaults to the empty list. -@end deffn - -@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}] -Return as a monadic value the absolute file name in the store of the file -containing @var{data}, a bytevector. @var{references} is a list of store -items that the resulting binary file refers to; it defaults to the empty -list. -@end deffn - -@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @ - [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} once -interned in the store. Use @var{name} as its store name, or the basename of -@var{file} if @var{name} is omitted. - -When @var{recursive?} is true, the contents of @var{file} are added -recursively; if @var{file} designates a flat file and @var{recursive?} is -true, its contents are added, and its permission bits are kept. - -When @var{recursive?} is true, call @code{(@var{select?} @var{file} -@var{stat})} for each directory entry, where @var{file} is the entry's -absolute file name and @var{stat} is the result of @code{lstat}; exclude -entries for which @var{select?} does not return true. - -The example below adds a file to the store, under two different names: - -@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 - -The @code{(guix packages)} module exports the following package-related -monadic procedures: - -@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @ - [#:system (%current-system)] [#:target #f] @ [#:output "out"] Return as a -monadic value in the absolute file name of @var{file} within the -@var{output} directory of @var{package}. When @var{file} is omitted, return -the name of the @var{output} directory of @var{package}. When @var{target} -is true, use it as a cross-compilation target triplet. -@end deffn - -@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}] -@deffnx {Monadic Procedure} package->cross-derivation @var{package} @ - @var{target} [@var{system}] Monadic version of @code{package-derivation} and -@code{package-cross-derivation} (@pxref{Defining Packages}). -@end deffn - - -@node G-Expressions -@section G-Expressions - -@cindex G-expression -@cindex build code quoting -So we have ``derivations'', which represent a sequence of build actions to -be performed to produce an item in the store (@pxref{Derivations}). These -build actions are performed when asking the daemon to actually build the -derivations; they are run by the daemon in a container (@pxref{Invoking -guix-daemon}). - -@cindex strata of code -It should come as no surprise that we like to write these build actions in -Scheme. When we do that, we end up with two @dfn{strata} of Scheme -code@footnote{The term @dfn{stratum} in this context was coined by Manuel -Serrano et al.@: in the context of their work on Hop. Oleg Kiselyov, who -has written insightful -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code on -this topic}, refers to this kind of code generation as @dfn{staging}.}: the -``host code''---code that defines packages, talks to the daemon, etc.---and -the ``build code''---code that actually performs build actions, such as -making directories, invoking @command{make}, etc. - -To describe a derivation and its build actions, one typically needs to embed -build code inside host code. It boils down to manipulating build code as -data, and the homoiconicity of Scheme---code has a direct representation as -data---comes in handy for that. But we need more than the normal -@code{quasiquote} mechanism in Scheme to construct build expressions. - -The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of -S-expressions adapted to build expressions. G-expressions, or @dfn{gexps}, -consist essentially of three syntactic forms: @code{gexp}, @code{ungexp}, -and @code{ungexp-splicing} (or simply: @code{#~}, @code{#$}, and -@code{#$@@}), which are comparable to @code{quasiquote}, @code{unquote}, and -@code{unquote-splicing}, respectively (@pxref{Expression Syntax, -@code{quasiquote},, guile, GNU Guile Reference Manual}). However, there are -major differences: - -@itemize -@item -Gexps are meant to be written to a file and run or manipulated by other -processes. - -@item -When a high-level object such as a package or derivation is unquoted inside -a gexp, the result is as if its output file name had been introduced. - -@item -Gexps carry information about the packages or derivations they refer to, and -these dependencies are automatically added as inputs to the build processes -that use them. -@end itemize - -@cindex lowering, of high-level objects in gexps -This mechanism is not limited to package and derivation objects: -@dfn{compilers} able to ``lower'' other high-level objects to derivations or -files in the store can be defined, such that these objects can also be -inserted into gexps. For example, a useful type of high-level objects that -can be inserted in a gexp is ``file-like objects'', which make it easy to -add files to the store and to refer to them in derivations and such (see -@code{local-file} and @code{plain-file} below.) - -To illustrate the idea, here is an example of a gexp: - -@example -(define build-exp - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "list-files"))) -@end example - -This gexp can be passed to @code{gexp->derivation}; we obtain a derivation -that builds a directory containing exactly one symlink to -@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: - -@example -(gexp->derivation "the-thing" build-exp) -@end example - -As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string -is substituted to the reference to the @var{coreutils} package in the actual -build code, and @var{coreutils} is automatically made an input to the -derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp -output)}) is replaced by a string containing the directory name of the -output of the derivation. - -@cindex cross compilation -In a cross-compilation context, it is useful to distinguish between -references to the @emph{native} build of a package---that can run on the -host---versus references to cross builds of a package. To that end, the -@code{#+} plays the same role as @code{#$}, but is a reference to a native -package build: - -@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 -In the example above, the native build of @var{coreutils} is used, so that -@command{ln} can actually run on the host; but then the cross-compiled build -of @var{emacs} is referenced. - -@cindex imported modules, for gexps -@findex with-imported-modules -Another gexp feature is @dfn{imported modules}: sometimes you want to be -able to use certain Guile modules from the ``host environment'' in the gexp, -so those modules should be imported in the ``build environment''. The -@code{with-imported-modules} form allows you to express that: - -@example -(let ((build (with-imported-modules '((guix build utils)) - #~(begin - (use-modules (guix build utils)) - (mkdir-p (string-append #$output "/bin")))))) - (gexp->derivation "empty-dir" - #~(begin - #$build - (display "success!\n") - #t))) -@end example - -@noindent -In this example, the @code{(guix build utils)} module is automatically -pulled into the isolated build environment of our gexp, such that -@code{(use-modules (guix build utils))} works as expected. - -@cindex module closure -@findex source-module-closure -Usually you want the @emph{closure} of the module to be imported---i.e., the -module itself and all the modules it depends on---rather than just the -module; failing to do that, attempts to use the module will fail because of -missing dependent modules. The @code{source-module-closure} procedure -computes the closure of a module by looking at its source file headers, -which comes in handy in this case: - -@example -(use-modules (guix modules)) ;for 'source-module-closure' - -(with-imported-modules (source-module-closure - '((guix build utils) - (gnu build vm))) - (gexp->derivation "something-with-vms" - #~(begin - (use-modules (guix build utils) - (gnu build vm)) - @dots{}))) -@end example - -@cindex extensions, for gexps -@findex with-extensions -In the same vein, sometimes you want to import not just pure-Scheme modules, -but also ``extensions'' such as Guile bindings to C libraries or other -``full-blown'' packages. Say you need the @code{guile-json} package -available on the build side, here's how you would do it: - -@example -(use-modules (gnu packages guile)) ;for 'guile-json' - -(with-extensions (list guile-json) - (gexp->derivation "something-with-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -The syntactic form to construct gexps is summarized below. - -@deffn {Scheme Syntax} #~@var{exp} -@deffnx {Scheme Syntax} (gexp @var{exp}) -Return a G-expression containing @var{exp}. @var{exp} may contain one or -more of the following forms: - -@table @code -@item #$@var{obj} -@itemx (ungexp @var{obj}) -Introduce a reference to @var{obj}. @var{obj} may have one of the supported -types, for example a package or a derivation, in which case the -@code{ungexp} form is replaced by its output file name---e.g., -@code{"/gnu/store/@dots{}-coreutils-8.22}. - -If @var{obj} is a list, it is traversed and references to supported objects -are substituted similarly. - -If @var{obj} is another gexp, its contents are inserted and its dependencies -are added to those of the containing gexp. - -If @var{obj} is another kind of object, it is inserted as is. - -@item #$@var{obj}:@var{output} -@itemx (ungexp @var{obj} @var{output}) -This is like the form above, but referring explicitly to the @var{output} of -@var{obj}---this is useful when @var{obj} produces multiple outputs -(@pxref{Packages with Multiple Outputs}). - -@item #+@var{obj} -@itemx #+@var{obj}:output -@itemx (ungexp-native @var{obj}) -@itemx (ungexp-native @var{obj} @var{output}) -Same as @code{ungexp}, but produces a reference to the @emph{native} build -of @var{obj} when used in a cross compilation context. - -@item #$output[:@var{output}] -@itemx (ungexp output [@var{output}]) -Insert a reference to derivation output @var{output}, or to the main output -when @var{output} is omitted. - -This only makes sense for gexps passed to @code{gexp->derivation}. - -@item #$@@@var{lst} -@itemx (ungexp-splicing @var{lst}) -Like the above, but splices the contents of @var{lst} inside the containing -list. - -@item #+@@@var{lst} -@itemx (ungexp-native-splicing @var{lst}) -Like the above, but refers to native builds of the objects listed in -@var{lst}. - -@end table - -G-expressions created by @code{gexp} or @code{#~} are run-time objects of -the @code{gexp?} type (see below.) -@end deffn - -@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{} -Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} in -their execution environment. - -Each item in @var{modules} can be the name of a module, such as @code{(guix -build utils)}, or it can be a module name, followed by an arrow, followed by -a file-like object: - -@example -`((guix build utils) - (guix gcrypt) - ((guix config) => ,(scheme-file "config.scm" - #~(define-module @dots{})))) -@end example - -@noindent -In the example above, the first two modules are taken from the search path, -and the last one is created from the given file-like object. - -This form has @emph{lexical} scope: it has an effect on the gexps directly -defined in @var{body}@dots{}, but not on those defined, say, in procedures -called from @var{body}@dots{}. -@end deffn - -@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{} -Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in -their build and execution environment. @var{extensions} is typically a list -of package objects such as those defined in the @code{(gnu packages guile)} -module. - -Concretely, the packages listed in @var{extensions} are added to the load -path while compiling imported modules in @var{body}@dots{}; they are also -added to the load path of the gexp returned by @var{body}@dots{}. -@end deffn - -@deffn {Scheme Procedure} gexp? @var{obj} -Return @code{#t} if @var{obj} is a G-expression. -@end deffn - -G-expressions are meant to be written to disk, either as code building some -derivation, or as plain files in the store. The monadic procedures below -allow you to do that (@pxref{The Store Monad}, for more information about -monads.) - -@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @ - [#: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] Return a derivation @var{name} that runs @var{exp} (a -gexp) with @var{guile-for-build} (a derivation) on @var{system}; @var{exp} -is stored in a file called @var{script-name}. When @var{target} is true, it -is used as the cross-compilation target triplet for packages referred to by -@var{exp}. - -@var{modules} is deprecated in favor of @code{with-imported-modules}. Its -meaning is to make @var{modules} available in the evaluation context of -@var{exp}; @var{modules} is a list of names of Guile modules searched in -@var{module-path} to be copied in the store, compiled, and made available in -the load path during the execution of @var{exp}---e.g., @code{((guix build -utils) (guix build gnu-build-system))}. - -@var{effective-version} determines the string to use when adding extensions -of @var{exp} (see @code{with-extensions}) to the search path---e.g., -@code{"2.2"}. - -@var{graft?} determines whether packages referred to by @var{exp} should be -grafted when applicable. - -When @var{references-graphs} is true, it must be a list of tuples of one of -the following forms: - -@example -(@var{file-name} @var{package}) -(@var{file-name} @var{package} @var{output}) -(@var{file-name} @var{derivation}) -(@var{file-name} @var{derivation} @var{output}) -(@var{file-name} @var{store-item}) -@end example - -The right-hand-side of each element of @var{references-graphs} is -automatically made an input of the build process of @var{exp}. In the build -environment, each @var{file-name} contains the reference graph of the -corresponding item, in a simple text format. - -@var{allowed-references} must be either @code{#f} or a list of output names -and packages. In the latter case, the list denotes store items that the -result is allowed to refer to. Any reference to another store item will -lead to a build error. Similarly for @var{disallowed-references}, which can -list items that must not be referenced by the outputs. - -@var{deprecation-warnings} determines whether to show deprecation warnings -while compiling modules. It can be @code{#f}, @code{#t}, or -@code{'detailed}. - -The other arguments are as for @code{derivation} (@pxref{Derivations}). -@end deffn - -@cindex file-like objects -The @code{local-file}, @code{plain-file}, @code{computed-file}, -@code{program-file}, and @code{scheme-file} procedures below return -@dfn{file-like objects}. That is, when unquoted in a G-expression, these -objects lead to a file in the store. Consider this G-expression: - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/my-nscd.conf")) -@end example - -The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it to -the store. Once expanded, for instance @i{via} @code{gexp->derivation}, the -G-expression refers to that copy under @file{/gnu/store}; thus, modifying or -removing the file in @file{/tmp} does not have any effect on what the -G-expression does. @code{plain-file} can be used similarly; it differs in -that the file content is directly passed as a string. - -@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @ - [#:recursive? #f] [#:select? (const #t)] Return an object representing local -file @var{file} to add to the store; this object can be used in a gexp. If -@var{file} is a relative file name, it is looked up relative to the source -file where this form appears. @var{file} will be added to the store under -@var{name}--by default the base name of @var{file}. - -When @var{recursive?} is true, the contents of @var{file} are added -recursively; if @var{file} designates a flat file and @var{recursive?} is -true, its contents are added, and its permission bits are kept. - -When @var{recursive?} is true, call @code{(@var{select?} @var{file} -@var{stat})} for each directory entry, where @var{file} is the entry's -absolute file name and @var{stat} is the result of @code{lstat}; exclude -entries for which @var{select?} does not return true. - -This is the declarative counterpart of the @code{interned-file} monadic -procedure (@pxref{The Store Monad, @code{interned-file}}). -@end deffn - -@deffn {Scheme Procedure} plain-file @var{name} @var{content} -Return an object representing a text file called @var{name} with the given -@var{content} (a string or a bytevector) to be added to the store. - -This is the declarative counterpart of @code{text-file}. -@end deffn - -@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ - [#:options '(#:local-build? #t)] Return an object representing the store -item @var{name}, a file or directory computed by @var{gexp}. @var{options} -is a list of additional arguments to pass to @code{gexp->derivation}. - -This is the declarative counterpart of @code{gexp->derivation}. -@end deffn - -@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @ - [#:guile (default-guile)] [#:module-path %load-path] Return an executable -script @var{name} that runs @var{exp} using @var{guile}, with @var{exp}'s -imported modules in its search path. Look up @var{exp}'s modules in -@var{module-path}. - -The example below builds a script that simply invokes the @command{ls} -command: - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "list-files" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -When ``running'' it through the store (@pxref{The Store Monad, -@code{run-with-store}}), we obtain a derivation that produces an executable -file @file{/gnu/store/@dots{}-list-files} along these lines: - -@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 Procedure} program-file @var{name} @var{exp} @ - [#:guile #f] [#:module-path %load-path] Return an object representing the -executable store item @var{name} that runs @var{gexp}. @var{guile} is the -Guile package used to execute that script. Imported modules of @var{gexp} -are looked up in @var{module-path}. - -This is the declarative counterpart of @code{gexp->script}. -@end deffn - -@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @ - [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] @ [#:guile -(default-guile)] Return a derivation that builds a file @var{name} -containing @var{exp}. When @var{splice?} is true, @var{exp} is considered -to be a list of expressions that will be spliced in the resulting file. - -When @var{set-load-path?} is true, emit code in the resulting file to set -@code{%load-path} and @code{%load-compiled-path} to honor @var{exp}'s -imported modules. Look up @var{exp}'s modules in @var{module-path}. - -The resulting file holds references to all the dependencies of @var{exp} or -a subset thereof. -@end deffn - -@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f] -Return an object representing the Scheme file @var{name} that contains -@var{exp}. - -This is the declarative counterpart of @code{gexp->file}. -@end deffn - -@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} -Return as a monadic value a derivation that builds a text file containing -all of @var{text}. @var{text} may list, in addition to strings, objects of -any type that can be used in a gexp: packages, derivations, local file -objects, etc. The resulting store file holds references to all these. - -This variant should be preferred over @code{text-file} anytime the file to -create will reference items from the store. This is typically the case when -building a configuration file that embeds store file names, like this: - -@example -(define (profile.sh) - ;; Return the name of a shell script in the store that - ;; initializes the 'PATH' environment variable. - (text-file* "profile.sh" - "export PATH=" coreutils "/bin:" - grep "/bin:" sed "/bin\n")) -@end example - -In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file -will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby -preventing them from being garbage-collected during its lifetime. -@end deffn - -@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{} -Return an object representing store file @var{name} containing @var{text}. -@var{text} is a sequence of strings and file-like objects, as in: - -@example -(mixed-text-file "profile" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -This is the declarative counterpart of @code{text-file*}. -@end deffn - -@deffn {Scheme Procedure} file-union @var{name} @var{files} -Return a @code{} that builds a directory containing all of -@var{files}. Each item in @var{files} must be a two-element list where the -first element is the file name to use in the new directory, and the second -element is a gexp denoting the target file. Here's an example: - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -This yields an @code{etc} directory containing these two files. -@end deffn - -@deffn {Scheme Procedure} directory-union @var{name} @var{things} -Return a directory that is the union of @var{things}, where @var{things} is -a list of file-like objects denoting directories. For example: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -yields a directory that is the union of the @code{guile} and @code{emacs} -packages. -@end deffn - -@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{} -Return a file-like object that expands to the concatenation of @var{obj} and -@var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is -a string. - -As an example, consider this gexp: - -@example -(gexp->script "run-uname" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -The same effect could be achieved with: - -@example -(gexp->script "run-uname" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -There is one difference though: in the @code{file-append} case, the -resulting script contains the absolute file name as a string, whereas in the -second case, the resulting script contains a @code{(string-append @dots{})} -expression to construct the file name @emph{at run time}. -@end deffn - - -Of course, in addition to gexps embedded in ``host'' code, there are also -modules containing build tools. To make it clear that they are meant to be -used in the build stratum, these modules are kept in the @code{(guix build -@dots{})} name space. - -@cindex lowering, of high-level objects in gexps -Internally, high-level objects are @dfn{lowered}, using their compiler, to -either derivations or store items. For instance, lowering a package yields -a derivation, and lowering a @code{plain-file} yields a store item. This is -achieved using the @code{lower-object} monadic procedure. - -@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @ - [#:target #f] Return as a value in @var{%store-monad} the derivation or -store item corresponding to @var{obj} for @var{system}, cross-compiling for -@var{target} if @var{target} is true. @var{obj} must be an object that has -an associated gexp compiler, such as a @code{}. -@end deffn - -@node Invoking guix repl -@section Invoking @command{guix repl} - -@cindex REPL, read-eval-print loop -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 = # -@end example - -@cindex inferiors -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. - -The available options are as follows: - -@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{endpoint} -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 Utilities -@chapter Utilities - -This section describes Guix command-line utilities. Some of them are -primarily targeted at developers and users who write new package -definitions, while others are more generally useful. They complement the -Scheme programming interface of Guix in a convenient way. - -@menu -* Invoking guix build:: Building packages from the command line. -* Invoking guix edit:: Editing package definitions. -* Invoking guix download:: Downloading a file and printing its hash. -* Invoking guix hash:: Computing the cryptographic hash of a file. -* Invoking guix import:: Importing package definitions. -* Invoking guix refresh:: Updating package definitions. -* Invoking guix lint:: Finding errors in package definitions. -* Invoking guix size:: Profiling disk usage. -* Invoking guix graph:: Visualizing the graph of packages. -* Invoking guix publish:: Sharing substitutes. -* Invoking guix challenge:: Challenging substitute servers. -* Invoking guix copy:: Copying to and from a remote store. -* Invoking guix container:: Process isolation. -* Invoking guix weather:: Assessing substitute availability. -* Invoking guix processes:: Listing client processes. -@end menu - -@node Invoking guix build -@section Invoking @command{guix build} - -@cindex package building -@cindex @command{guix build} -The @command{guix build} command builds packages or derivations and their -dependencies, and prints the resulting store paths. Note that it does not -modify the user's profile---this is the job of the @command{guix package} -command (@pxref{Invoking guix package}). Thus, it is mainly useful for -distribution developers. - -The general syntax is: - -@example -guix build @var{options} @var{package-or-derivation}@dots{} -@end example - -As an example, the following command builds the latest versions of Emacs and -of Guile, displays their build logs, and finally displays the resulting -directories: - -@example -guix build emacs guile -@end example - -Similarly, the following command builds all the available packages: - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -@var{package-or-derivation} may be either the name of a package found in the -software distribution such as @code{coreutils} or @code{coreutils@@8.20}, or -a derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the -former case, a package with the corresponding name (and optionally version) -is searched for among the GNU distribution modules (@pxref{Package -Modules}). - -Alternatively, the @code{--expression} option may be used to specify a -Scheme expression that evaluates to a package; this is useful when -disambiguating among several same-named packages or package variants is -needed. - -There may be zero or more @var{options}. The available options are -described in the subsections below. - -@menu -* Common Build Options:: Build options for most commands. -* Package Transformation Options:: Creating variants of packages. -* Additional Build Options:: Options specific to 'guix build'. -* Debugging Build Failures:: Real life packaging experience. -@end menu - -@node Common Build Options -@subsection Common Build Options - -A number of options that control the build process are common to -@command{guix build} and other commands that can spawn builds, such as -@command{guix package} or @command{guix archive}. These are the following: - -@table @code - -@item --load-path=@var{directory} -@itemx -L @var{directory} -Add @var{directory} to the front of the package module search path -(@pxref{Package Modules}). - -This allows users to define their own packages and make them visible to the -command-line tools. - -@item --keep-failed -@itemx -K -Keep the build tree of failed builds. Thus, if a build fails, its build -tree is kept under @file{/tmp}, in a directory whose name is shown at the -end of the build log. This is useful when debugging build issues. -@xref{Debugging Build Failures}, for tips and tricks on how to debug build -issues. - -This option has no effect when connecting to a remote daemon with a -@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET} -variable}). - -@item --keep-going -@itemx -k -Keep going when some of the derivations fail to build; return only once all -the builds have either completed or failed. - -The default behavior is to stop as soon as one of the specified derivations -has failed. - -@item --dry-run -@itemx -n -Do not build the derivations. - -@anchor{fallback-option} -@item --fallback -When substituting a pre-built binary fails, fall back to building packages -locally (@pxref{Substitution Failure}). - -@item --substitute-urls=@var{urls} -@anchor{client-substitute-urls} -Consider @var{urls} the whitespace-separated list of substitute source URLs, -overriding the default list of URLs of @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}). - -This means that substitutes may be downloaded from @var{urls}, provided they -are signed by a key authorized by the system administrator -(@pxref{Substitutes}). - -When @var{urls} is the empty string, substitutes are effectively disabled. - -@item --no-substitutes -Do not use substitutes for build products. That is, always build things -locally instead of allowing downloads of pre-built binaries -(@pxref{Substitutes}). - -@item --no-grafts -Do not ``graft'' packages. In practice, this means that package updates -available as grafts are not applied. @xref{Security Updates}, for more -information on grafts. - -@item --rounds=@var{n} -Build each derivation @var{n} times in a row, and raise an error if -consecutive build results are not bit-for-bit identical. - -This is a useful way to detect non-deterministic builds processes. -Non-deterministic build processes are a problem because they make it -practically impossible for users to @emph{verify} whether third-party -binaries are genuine. @xref{Invoking guix challenge}, for more. - -Note that, currently, the differing build results are not kept around, so -you will have to manually investigate in case of an error---e.g., by -stashing one of the build results with @code{guix archive --export} -(@pxref{Invoking guix archive}), then rebuilding, and finally comparing the -two results. - -@item --no-build-hook -Do not attempt to offload builds @i{via} the ``build hook'' of the daemon -(@pxref{Daemon Offload Setup}). That is, always build things locally -instead of offloading builds to remote machines. - -@item --max-silent-time=@var{seconds} -When the build or substitution process remains silent for more than -@var{seconds}, terminate it and report a build failure. - -By default, the daemon's setting is honored (@pxref{Invoking guix-daemon, -@code{--max-silent-time}}). - -@item --timeout=@var{seconds} -Likewise, when the build or substitution process lasts for more than -@var{seconds}, terminate it and report a build failure. - -By default, the daemon's setting is honored (@pxref{Invoking 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{level} -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} -Allow the use of up to @var{n} CPU cores for the build. The special value -@code{0} means to use as many CPU cores as available. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Allow at most @var{n} build jobs in parallel. @xref{Invoking guix-daemon, -@code{--max-jobs}}, for details about this option and the equivalent -@command{guix-daemon} option. - -@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 - -Behind the scenes, @command{guix build} is essentially an interface to the -@code{package-derivation} procedure of the @code{(guix packages)} module, -and to the @code{build-derivations} procedure of the @code{(guix -derivations)} module. - -In addition to options explicitly passed on the command line, @command{guix -build} and other @command{guix} commands that support building honor the -@code{GUIX_BUILD_OPTIONS} environment variable. - -@defvr {Environment Variable} GUIX_BUILD_OPTIONS -Users can define this variable to a list of command line options that will -automatically be used by @command{guix build} and other @command{guix} -commands that can perform builds, as in the example below: - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -These options are parsed independently, and the result is appended to the -parsed command-line options. -@end defvr - - -@node Package Transformation Options -@subsection Package Transformation Options - -@cindex package variants -Another set of command-line options supported by @command{guix build} and -also @command{guix package} are @dfn{package transformation options}. These -are options that make it possible to define @dfn{package variants}---for -instance, packages built from different source code. This is a convenient -way to create customized packages on the fly without having to type in the -definitions of package variants (@pxref{Defining Packages}). - -@table @code - -@item --with-source=@var{source} -@itemx --with-source=@var{package}=@var{source} -@itemx --with-source=@var{package}@@@var{version}=@var{source} -Use @var{source} as the source of @var{package}, and @var{version} as its -version number. @var{source} must be a file name or a URL, as for -@command{guix download} (@pxref{Invoking guix download}). - -When @var{package} is omitted, it is taken to be the package name specified -on the command line that matches the base of @var{source}---e.g., if -@var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding package -is @code{guile}. - -Likewise, when @var{version} is omitted, the version string is inferred from -@var{source}; in the previous example, it is @code{2.0.10}. - -This option allows users to try out versions of packages other than the one -provided by the distribution. The example below downloads -@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for the -@code{ed} package: - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -As a developer, @code{--with-source} makes it easy to test release -candidates: - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} or to build from a checkout in a pristine environment: - -@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{package}=@var{replacement} -Replace dependency on @var{package} by a dependency on @var{replacement}. -@var{package} must be a package name, and @var{replacement} must be a -package specification such as @code{guile} or @code{guile@@1.8}. - -For instance, the following command builds Guix, but replaces its dependency -on the current stable version of Guile with a dependency on the legacy -version of Guile, @code{guile@@2.0}: - -@example -guix build --with-input=guile=guile@@2.0 guix -@end example - -This is a recursive, deep replacement. So in this example, both @code{guix} -and its dependency @code{guile-json} (which also depends on @code{guile}) -get rebuilt against @code{guile@@2.0}. - -This is implemented using the @code{package-input-rewriting} Scheme -procedure (@pxref{Defining Packages, @code{package-input-rewriting}}). - -@item --with-graft=@var{package}=@var{replacement} -This is similar to @code{--with-input} but with an important difference: -instead of rebuilding the whole dependency chain, @var{replacement} is built -and then @dfn{grafted} onto the binaries that were initially referring to -@var{package}. @xref{Security Updates}, for more information on grafts. - -For example, the command below grafts version 3.5.4 of GnuTLS onto Wget and -all its dependencies, replacing references to the version of GnuTLS they -currently refer to: - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -This has the advantage of being much faster than rebuilding everything. But -there is a caveat: it works if and only if @var{package} and -@var{replacement} are strictly compatible---for example, if they provide a -library, the application binary interface (ABI) of those libraries must be -compatible. If @var{replacement} is somehow incompatible with -@var{package}, then the resulting package may be unusable. Use with care! - -@item --with-git-url=@var{package}=@var{url} -@cindex Git, using the latest commit -@cindex latest commit, building -Build @var{package} from the latest commit of the @code{master} branch of -the Git repository at @var{url}. Git sub-modules of the repository are -fetched, recursively. - -For example, the following command builds the NumPy Python library against -the latest commit of the master branch of Python itself: - -@example -guix build python-numpy \ - --with-git-url=python=https://github.com/python/cpython -@end example - -This option can also be combined with @code{--with-branch} or -@code{--with-commit} (see below). - -@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-branch=@var{package}=@var{branch} -Build @var{package} from the latest commit of @var{branch}. If the -@code{source} field of @var{package} is an origin with the @code{git-fetch} -method (@pxref{origin Reference}) or a @code{git-checkout} object, the -repository URL is taken from that @code{source}. Otherwise you have to use -@code{--with-git-url} to specify the URL of the Git repository. - -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 - -@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 Additional Build Options -@subsection Additional Build Options - -The command-line options presented below are specific to @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{file} -@itemx -f @var{file} -Build the package, derivation, or other file-like object that the code -within @var{file} evaluates to (@pxref{G-Expressions, file-like objects}). - -As an example, @var{file} might contain a package definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{expr} -@itemx -e @var{expr} -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-Expressions}). - -Lastly, @var{expr} may refer to a zero-argument monadic procedure -(@pxref{The Store Monad}). 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{Defining Packages}). - -@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} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the -system type of the build host. The @command{guix build} command allows you -to repeat this option several times, in which case it builds for all the -specified systems; other commands ignore extraneous @option{-s} options. - -@quotation Note -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 Note -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{Virtualization Services, @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{Daemon -Offload Setup}, for more information on offloading. - -@item --target=@var{triplet} -@cindex cross-compilation -Cross-build for @var{triplet}, which must be a valid GNU triplet, such as -@code{"mips64el-linux-gnu"} (@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{Substitutes}), or whether the build result of a package -is deterministic. @xref{Invoking guix challenge}, for more background -information and tools. - -When used in conjunction with @option{--keep-failed}, the differing output -is kept in the store, under @file{/gnu/store/@dots{}-check}. This makes it -easy to look for differences between the two results. - -@item --repair -@cindex repairing store items -@cindex corruption, recovering from -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{Invoking 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 Debugging Build Failures -@subsection Debugging Build Failures - -@cindex build failures, debugging -When defining a new package (@pxref{Defining Packages}), 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{Invoking 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{Build Environment Setup}). - -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{Invoking 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{Security Updates}, 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 Invoking 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{从Git编译}), or have -created your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{Package -Modules}), 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 Invoking 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{Defining Packages}). 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{Invoking -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 Certificates}), -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{Invoking 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 Invoking 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{Defining Packages}). - -The general syntax is: - -@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{Invoking 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 -Reference}): - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Invoking 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{Defining Packages}). - -The general syntax is: - -@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{Invoking 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{} record -(@xref{Defining Packages}). 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{} 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{贡献}). - -@node Invoking 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{Defining Packages}). 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{expr} -@itemx -e @var{expr} -Consider the package @var{expr} evaluates to. - -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}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Defining Packages}, 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{file} -@itemx -m @var{file} -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. -@item launchpad -the updater for @uref{https://launchpad.net, Launchpad} 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{Invoking 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{file} -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 Invoking 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 Reference}). - -@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 . -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 - -The general syntax is: - -@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 Invoking guix size -@section Invoking @command{guix size} - -@cindex size -@cindex package size -@cindex closure -@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{Packages with Multiple -Outputs}). 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 closure -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{Security Updates}, 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{Substitutes}). 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 closure -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 Invoking guix graph -@section Invoking @command{guix graph} - -@cindex DAG -@cindex @command{guix graph} -@cindex package dependencies -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 @emph{explicitly} depend on OCaml -(if you are also interested in cases where OCaml is an implicit dependency, -see @code{reverse-bag} below.) - -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{Invoking 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{Build Systems, @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 reverse-bag -This shows the @emph{reverse} DAG of packages. Unlike -@code{reverse-package}, it also takes implicit dependencies into account. -For example: - -@example -guix graph -t reverse-bag dune -@end example - -@noindent -...@: yields the graph of all packages that depend on Dune, directly or -indirectly. Since Dune is an @emph{implicit} dependency of many packages -@i{via} @code{dune-build-system}, this shows a large number of packages, -whereas @code{reverse-package} would show very few if any. - -@item derivation -This is the most detailed representation: It shows the DAG of derivations -(@pxref{Derivations}) 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{Package Modules}). 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{Invoking 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{Invoking 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{expr} -@itemx -e @var{expr} -Consider the package @var{expr} evaluates to. - -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 Invoking guix publish -@section Invoking @command{guix publish} - -@cindex @command{guix publish} -The purpose of @command{guix publish} is to enable users to easily share -their store with others, who can then use it as a substitute server -(@pxref{Substitutes}). - -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. - -For security, each substitute is signed, allowing recipients to check their -authenticity and integrity (@pxref{Substitutes}). Because @command{guix -publish} uses the signing key of the system, which is only readable by the -system administrator, it must be started as root; the @code{--user} option -makes it drop root privileges early on. - -The signing key pair must be generated before @command{guix publish} is -launched, using @command{guix archive --generate-key} (@pxref{Invoking guix -archive}). - -The general syntax is: - -@example -guix publish @var{options}@dots{} -@end example - -Running @command{guix publish} without any additional arguments will spawn -an HTTP server on port 8080: - -@example -guix publish -@end example - -Once a publishing server has been authorized (@pxref{Invoking guix -archive}), the daemon may download substitutes from it: - -@example -guix-daemon --substitute-urls=http://example.org:8080 -@end example - -By default, @command{guix publish} compresses archives on the fly as it -serves them. This ``on-the-fly'' mode is convenient in that it requires no -setup and is immediately available. However, when serving lots of clients, -we recommend using the @option{--cache} option, which enables caching of the -archives before they are sent to clients---see below for details. The -@command{guix weather} command provides a handy way to check what a server -provides (@pxref{Invoking guix weather}). - -As a bonus, @command{guix publish} also serves as a content-addressed mirror -for source files referenced in @code{origin} records (@pxref{origin -Reference}). For instance, assuming @command{guix publish} is running on -@code{example.org}, the following URL returns the raw -@file{hello-2.10.tar.gz} file with the given SHA256 hash (represented in -@code{nix-base32} format, @pxref{Invoking guix hash}): - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -Obviously, these URLs only work for files that are in the store; in other -cases, they return 404 (``Not Found''). - -@cindex build logs, publication -Build logs are available from @code{/log} URLs like: - -@example -http://example.org/log/gwspk@dots{}-guile-2.2.3 -@end example - -@noindent -When @command{guix-daemon} is configured to save compressed build logs, as -is the case by default (@pxref{Invoking guix-daemon}), @code{/log} URLs -return the compressed log as-is, with an appropriate @code{Content-Type} -and/or @code{Content-Encoding} header. We recommend running -@command{guix-daemon} with @code{--log-compression=gzip} since Web browsers -can automatically decompress it, which is not the case with bzip2 -compression. - -The following options are available: - -@table @code -@item --port=@var{port} -@itemx -p @var{port} -Listen for HTTP requests on @var{port}. - -@item --listen=@var{host} -Listen on the network interface for @var{host}. The default is to accept -connections from any interface. - -@item --user=@var{user} -@itemx -u @var{user} -Change privileges to @var{user} as soon as possible---i.e., once the server -socket is open and the signing key has been read. - -@item --compression[=@var{level}] -@itemx -C [@var{level}] -Compress data using the given @var{level}. When @var{level} is zero, -disable compression. The range 1 to 9 corresponds to different gzip -compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). -The default is 3. - -Unless @option{--cache} is used, compression occurs on the fly and the -compressed streams are not cached. Thus, to reduce load on the machine that -runs @command{guix publish}, it may be a good idea to choose a low -compression level, to run @command{guix publish} behind a caching proxy, or -to use @option{--cache}. Using @option{--cache} has the advantage that it -allows @command{guix publish} to add @code{Content-Length} HTTP header to -its responses. - -@item --cache=@var{directory} -@itemx -c @var{directory} -Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} and -only serve archives that are in cache. - -When this option is omitted, archives and meta-data are created on-the-fly. -This can reduce the available bandwidth, especially when compression is -enabled, since this may become CPU-bound. Another drawback of the default -mode is that the length of archives is not known in advance, so -@command{guix publish} does not add a @code{Content-Length} HTTP header to -its responses, which in turn prevents clients from knowing the amount of -data being downloaded. - -Conversely, when @option{--cache} is used, the first request for a store -item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a background -process to @dfn{bake} the archive---computing its @code{.narinfo} and -compressing the archive, if needed. Once the archive is cached in -@var{directory}, subsequent requests succeed and are served directly from -the cache, which guarantees that clients get the best possible bandwidth. - -The ``baking'' process is performed by worker threads. By default, one -thread per CPU core is created, but this can be customized. See -@option{--workers} below. - -When @option{--ttl} is used, cached entries are automatically deleted when -they have expired. - -@item --workers=@var{N} -When @option{--cache} is used, request the allocation of @var{N} worker -threads to ``bake'' archives. - -@item --ttl=@var{ttl} -Produce @code{Cache-Control} HTTP headers that advertise a time-to-live -(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5 -days, @code{1m} means 1 month, and so on. - -This allows the user's Guix to keep substitute information in cache for -@var{ttl}. However, note that @code{guix publish} does not itself guarantee -that the store items it provides will indeed remain available for as long as -@var{ttl}. - -Additionally, when @option{--cache} is used, cached entries that have not -been accessed for @var{ttl} and that no longer have a corresponding item in -the store, may be deleted. - -@item --nar-path=@var{path} -Use @var{path} as the prefix for the URLs of ``nar'' files (@pxref{Invoking -guix archive, normalized archives}). - -By default, nars are served at a URL such as -@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to change -the @code{/nar} part to @var{path}. - -@item --public-key=@var{file} -@itemx --private-key=@var{file} -Use the specific @var{file}s as the public/private key pair used to sign the -store items being published. - -The files must correspond to the same key pair (the private key is used for -signing and the public key is merely advertised in the signature metadata). -They must contain keys in the canonical s-expression format as produced by -@command{guix archive --generate-key} (@pxref{Invoking guix archive}). By -default, @file{/etc/guix/signing-key.pub} and -@file{/etc/guix/signing-key.sec} are used. - -@item --repl[=@var{port}] -@itemx -r [@var{port}] -Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile Reference -Manual}) on @var{port} (37146 by default). This is used primarily for -debugging a running @command{guix publish} server. -@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}}). - -If you are instead running Guix on a ``foreign distro'', follow these -instructions:” - -@itemize -@item -If your host distro uses the systemd init system: - -@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 -If your host distro uses the Upstart init system: - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -Otherwise, proceed similarly with your distro's init system. -@end itemize - -@node Invoking guix challenge -@section Invoking @command{guix challenge} - -@cindex reproducible builds -@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{Substitutes}), 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{Introduction}). 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{Features}). 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{Invoking 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}. - -The general syntax is: - -@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 Invoking 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{Requirements}, 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{Invoking guix archive}, for more information about store item -authentication. - -The general syntax is: - -@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{Common Build Options}). - - -@node Invoking guix container -@section Invoking @command{guix container} -@cindex container -@cindex @command{guix container} -@quotation Note -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{Invoking guix -environment}) and @command{guix system container} (@pxref{Invoking guix -system}) commands. - -The general syntax is: - -@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 Invoking guix weather -@section Invoking @command{guix weather} - -Occasionally you're grumpy because substitutes are lacking and you end up -building packages by yourself (@pxref{Substitutes}). 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{Invoking 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{file} -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{Invoking 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.zh_CN.info -c 10 -computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.zh_CN.info... -updating substitutes from 'https://ci.guix.zh_CN.info'... 100.0% -https://ci.guix.zh_CN.info - 64.7% substitutes available (6,047 out of 9,343) -@dots{} -2502 packages are missing from 'https://ci.guix.zh_CN.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.zh_CN.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 Invoking guix processes -@section Invoking @command{guix processes} - -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{Daemon -Offload Setup}). - -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 System Configuration -@chapter System Configuration - -@cindex system configuration -The Guix System Distribution supports a consistent whole-system -configuration mechanism. By that we mean that all aspects of the global -system configuration---such as the available system services, timezone and -locale settings, user accounts---are declared in a single place. Such a -@dfn{system configuration} can be @dfn{instantiated}---i.e., effected. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -One of the advantages of putting all the system configuration under the -control of Guix is that it supports transactional system upgrades, and makes -it possible to roll back to a previous system instantiation, should -something go wrong with the new one (@pxref{Features}). Another advantage -is that it makes it easy to replicate the exact same configuration across -different machines, or at different points in time, without having to resort -to additional administration tools layered on top of the own tools of the -system. - -This section describes this mechanism. First we focus on the system -administrator's viewpoint---explaining how the system is configured and -instantiated. Then we show how this mechanism can be extended, for instance -to support new system services. - -@menu -* Using the Configuration System:: Customizing your GNU system. -* operating-system Reference:: Detail of operating-system declarations. -* File Systems:: Configuring file system mounts. -* Mapped Devices:: Block device extra processing. -* User Accounts:: Specifying user accounts. -* Keyboard Layout:: How the system interprets key strokes. -* Locales:: Language and cultural convention settings. -* Services:: Specifying system services. -* Setuid Programs:: Programs running with root privileges. -* X.509 Certificates:: Authenticating HTTPS servers. -* Name Service Switch:: Configuring libc's name service switch. -* Initial RAM Disk:: Linux-Libre bootstrapping. -* Bootloader Configuration:: Configuring the boot loader. -* Invoking guix system:: Instantiating a system configuration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Defining Services:: Adding new service definitions. -@end menu - -@node Using the Configuration System -@section Using the Configuration System - -The operating system is configured by providing an @code{operating-system} -declaration in a file that can then be passed to the @command{guix system} -command (@pxref{Invoking guix system}). A simple setup, with the default -system services, the default Linux-Libre kernel, initial RAM disk, and boot -loader looks like this: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -This example should be self-describing. Some of the fields defined above, -such as @code{host-name} and @code{bootloader}, are mandatory. Others, such -as @code{packages} and @code{services}, can be omitted, in which case they -get a default value. - -Below we discuss the effect of some of the most important fields -(@pxref{operating-system Reference}, for details about all the available -fields), and how to @dfn{instantiate} the operating system using -@command{guix system}. - -@unnumberedsubsec Bootloader - -@cindex legacy boot, on Intel machines -@cindex BIOS boot, on Intel machines -@cindex UEFI boot -@cindex EFI boot -The @code{bootloader} field describes the method that will be used to boot -your system. Machines based on Intel processors can boot in ``legacy'' BIOS -mode, as in the example above. However, more recent machines rely instead -on the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that -case, the @code{bootloader} field should contain something along these -lines: - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -@xref{Bootloader Configuration}, for more information on the available -configuration options. - -@unnumberedsubsec Globally-Visible Packages - -@vindex %base-packages -The @code{packages} field lists packages that will be globally visible on -the system, for all user accounts---i.e., in every user's @code{PATH} -environment variable---in addition to the per-user profiles (@pxref{Invoking -guix package}). The @var{%base-packages} variable provides all the tools -one would expect for basic user and administrator tasks---including the GNU -Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text -editor, @command{find}, @command{grep}, etc. The example above adds -GNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module -(@pxref{Package Modules}). The @code{(list package output)} syntax can be -used to add a specific output of a package: - -@lisp -(use-modules (gnu packages)) -(use-modules (gnu packages dns)) - -(operating-system - ;; ... - (packages (cons (list bind "utils") - %base-packages))) -@end lisp - -@findex specification->package -Referring to packages by variable name, like @code{bind} above, has the -advantage of being unambiguous; it also allows typos and such to be -diagnosed right away as ``unbound variables''. The downside is that one -needs to know which module defines which package, and to augment the -@code{use-package-modules} line accordingly. To avoid that, one can use the -@code{specification->package} procedure of the @code{(gnu packages)} module, -which returns the best package for a given name or name and version: - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec System Services - -@cindex services -@vindex %base-services -The @code{services} field lists @dfn{system services} to be made available -when the system starts (@pxref{Services}). 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{Networking -Services, @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{Defining Services}). - -@cindex customization, of services -@findex modify-services -Occasionally, instead of using the base services as is, you will want to -customize them. To do this, use @code{modify-services} (@pxref{Service -Reference, @code{modify-services}}) to modify the list. - -For example, suppose you want to modify @code{guix-daemon} and Mingetty (the -console log-in) in the @var{%base-services} list (@pxref{Base Services, -@code{%base-services}}). To do that, you can write the following in your -operating system declaration: - -@lisp -(define %my-services - ;; My very own list of services. - (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 - -This changes the configuration---i.e., the service parameters---of the -@code{guix-service-type} instance, and that of all the -@code{mingetty-service-type} instances in the @var{%base-services} list. -Observe how this is accomplished: first, we arrange for the original -configuration to be bound to the identifier @code{config} in the @var{body}, -and then we write the @var{body} so that it evaluates to the desired -configuration. In particular, notice how we use @code{inherit} to create a -new configuration which has the same values as the old configuration, but -with a few modifications. - -@cindex encrypted disk -The configuration for a typical ``desktop'' usage, with an encrypted root -partition, the X11 display server, GNOME and Xfce (users can choose which of -these desktop environments to use at the log-in screen by pressing -@kbd{F1}), network management, power management, and more, would look like -this: - -@lisp -@include os-config-desktop.texi -@end lisp - -A graphical system with a choice of lightweight window managers instead of -full-blown desktop environments would look like this: - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -This example refers to the @file{/boot/efi} file system by its UUID, -@code{1234-ABCD}. Replace this UUID with the right UUID on your system, as -returned by the @command{blkid} command. - -@xref{Desktop Services}, for the exact list of services provided by -@var{%desktop-services}. @xref{X.509 Certificates}, for background -information about the @code{nss-certs} package that is used here. - -Again, @var{%desktop-services} is just a list of service objects. If you -want to remove services from there, you can do so using the procedures for -list filtering (@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile -Reference Manual}). For instance, the following expression returns a list -that contains all the services in @var{%desktop-services} minus the Avahi -service: - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Instantiating the System - -Assuming the @code{operating-system} declaration is stored in the -@file{my-system-config.scm} file, the @command{guix system reconfigure -my-system-config.scm} command instantiates that configuration, and makes it -the default GRUB boot entry (@pxref{Invoking guix system}). - -The normal way to change the system configuration is by updating this file -and re-running @command{guix system reconfigure}. One should never have to -touch files in @file{/etc} or to run commands that modify the system state -such as @command{useradd} or @command{grub-install}. In fact, you must -avoid that since that would not only void your warranty but also prevent you -from rolling back to previous versions of your system, should you ever need -to. - -@cindex roll-back, of the operating system -Speaking of roll-back, each time you run @command{guix system reconfigure}, -a new @dfn{generation} of the system is created---without modifying or -deleting previous generations. Old system generations get an entry in the -bootloader boot menu, allowing you to boot them in case something went wrong -with the latest generation. Reassuring, no? The @command{guix system -list-generations} command lists the system generations available on disk. -It is also possible to roll back the system via the commands @command{guix -system roll-back} and @command{guix system switch-generation}. - -Although the @command{guix system reconfigure} command will not modify -previous generations, you must take care when the current generation is not -the latest (e.g., after invoking @command{guix system roll-back}), since the -operation might overwrite a later generation (@pxref{Invoking guix system}). - -@unnumberedsubsec The Programming Interface - -At the Scheme level, the bulk of an @code{operating-system} declaration is -instantiated with the following monadic procedure (@pxref{The Store Monad}): - -@deffn {Monadic Procedure} operating-system-derivation os -Return a derivation that builds @var{os}, an @code{operating-system} object -(@pxref{Derivations}). - -The output of the derivation is a single directory that refers to all the -packages, configuration files, and other supporting files needed to -instantiate @var{os}. -@end deffn - -This procedure is provided by the @code{(gnu system)} module. Along with -@code{(gnu services)} (@pxref{Services}), this module contains the guts of -Guix System. Make sure to visit it! - - -@node operating-system Reference -@section @code{operating-system} Reference - -This section summarizes all the options available in @code{operating-system} -declarations (@pxref{Using the Configuration System}). - -@deftp {Data Type} operating-system -This is the data type representing an operating system configuration. By -that, we mean all the global system configuration, not per-user -configuration (@pxref{Using the Configuration System}). - -@table @asis -@item @code{kernel} (default: @var{linux-libre}) -The package object of the operating system kernel to use@footnote{Currently -only the Linux-libre kernel is supported. In the future, it will be -possible to use the GNU@tie{}Hurd.}. - -@item @code{kernel-arguments} (default: @code{'("quiet")}) -List of strings or gexps representing additional arguments to pass on the -command-line of the kernel---e.g., @code{("console=ttyS0")}. - -@item @code{bootloader} -The system bootloader configuration object. @xref{Bootloader -Configuration}. - -@item @code{label} -This is the label (a string) as it appears in the bootloader's menu entry. -The default label includes the kernel name and version. - -@item @code{keyboard-layout} (default: @code{#f}) -This field specifies the keyboard layout to use in the console. It can be -either @code{#f}, in which case the default keyboard layout is used (usually -US English), or a @code{} record. - -This keyboard layout is in effect as soon as the kernel has booted. For -instance, it is the keyboard layout in effect when you type a passphrase if -your root file system is on a @code{luks-device-mapping} mapped device -(@pxref{Mapped Devices}). - -@quotation Note -This does @emph{not} specify the keyboard layout used by the bootloader, nor -that used by the graphical display server. @xref{Bootloader Configuration}, -for information on how to specify the bootloader's keyboard layout. @xref{X -Window}, for information on how to specify the keyboard layout used by the X -Window System. -@end quotation - -@item @code{initrd-modules} (default: @code{%base-initrd-modules}) -@cindex initrd -@cindex initial RAM disk -The list of Linux kernel modules that need to be available in the initial -RAM disk. @xref{Initial RAM Disk}. - -@item @code{initrd} (default: @code{base-initrd}) -A procedure that returns an initial RAM disk for the Linux kernel. This -field is provided to support low-level customization and should rarely be -needed for casual use. @xref{Initial RAM Disk}. - -@item @code{firmware} (default: @var{%base-firmware}) -@cindex firmware -List of firmware packages loadable by the operating system kernel. - -The default includes firmware needed for Atheros- and Broadcom-based WiFi -devices (Linux-libre modules @code{ath9k} and @code{b43-open}, -respectively). @xref{Hardware Considerations}, for more info on supported -hardware. - -@item @code{host-name} -The host name. - -@item @code{hosts-file} -@cindex hosts file -A file-like object (@pxref{G-Expressions, file-like objects}) for use as -@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference -Manual}). The default is a file with entries for @code{localhost} and -@var{host-name}. - -@item @code{mapped-devices} (default: @code{'()}) -A list of mapped devices. @xref{Mapped Devices}. - -@item @code{file-systems} -A list of file systems. @xref{File Systems}. - -@item @code{swap-devices} (default: @code{'()}) -@cindex swap devices -A list of strings identifying devices or files to be used for ``swap space'' -(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). For -example, @code{'("/dev/sda3")} or @code{'("/swapfile")}. It is possible to -specify a swap file in a file system on a mapped device, provided that the -necessary device mapping and file system are also specified. @xref{Mapped -Devices} and @ref{File Systems}. - -@item @code{users} (default: @code{%base-user-accounts}) -@itemx @code{groups} (default: @var{%base-groups}) -List of user accounts and groups. @xref{User Accounts}. - -If the @code{users} list lacks a user account with UID@tie{}0, a ``root'' -account with UID@tie{}0 is automatically added. - -@item @code{skeletons} (default: @code{(default-skeletons)}) -A list target file name/file-like object tuples (@pxref{G-Expressions, -file-like objects}). These are the skeleton files that will be added to the -home directory of newly-created user accounts. - -For instance, a valid value may look like this: - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hello\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (default: @var{%default-issue}) -A string denoting the contents of the @file{/etc/issue} file, which is -displayed when users log in on a text console. - -@item @code{packages} (default: @var{%base-packages}) -The set of packages installed in the global profile, which is accessible at -@file{/run/current-system/profile}. - -The default set includes core utilities and it is good practice to install -non-core utilities in user profiles (@pxref{Invoking guix package}). - -@item @code{timezone} -A timezone identifying string---e.g., @code{"Europe/Paris"}. - -You can run the @command{tzselect} command to find out which timezone string -corresponds to your region. Choosing an invalid timezone name causes -@command{guix system} to fail. - -@item @code{locale} (default: @code{"en_US.utf8"}) -The name of the default locale (@pxref{Locale Names,,, libc, The GNU C -Library Reference Manual}). @xref{Locales}, for more information. - -@item @code{locale-definitions} (default: @var{%default-locale-definitions}) -The list of locale definitions to be compiled and that may be used at run -time. @xref{Locales}. - -@item @code{locale-libcs} (default: @code{(list @var{glibc})}) -The list of GNU@tie{}libc packages whose locale data and tools are used to -build the locale definitions. @xref{Locales}, for compatibility -considerations that justify this option. - -@item @code{name-service-switch} (default: @var{%default-nss}) -Configuration of the libc name service switch (NSS)---a -@code{} object. @xref{Name Service Switch}, for -details. - -@item @code{services} (default: @var{%base-services}) -A list of service objects denoting system services. @xref{Services}. - -@cindex essential services -@item @code{essential-services} (default: ...) -The list of ``essential services''---i.e., things like instances of -@code{system-service-type} and @code{host-name-service-type} (@pxref{Service -Reference}), which are derived from the operating system definition itself. -As a user you should @emph{never} need to touch this field. - -@item @code{pam-services} (default: @code{(base-pam-services)}) -@cindex PAM -@cindex pluggable authentication modules -@c FIXME: Add xref to PAM services section. -Linux @dfn{pluggable authentication module} (PAM) services. - -@item @code{setuid-programs} (default: @var{%setuid-programs}) -List of string-valued G-expressions denoting setuid programs. @xref{Setuid -Programs}. - -@item @code{sudoers-file} (default: @var{%sudoers-specification}) -@cindex sudoers file -The contents of the @file{/etc/sudoers} file as a file-like object -(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}). - -This file specifies which users can use the @command{sudo} command, what -they are allowed to do, and what privileges they may gain. The default is -that only @code{root} and members of the @code{wheel} group may use -@code{sudo}. - -@end table - -@deffn {Scheme Syntax} this-operating-system -When used in the @emph{lexical scope} of an operating system field -definition, this identifier resolves to the operating system being defined. - -The example below shows how to refer to the operating system being defined -in the definition of the @code{label} field: - -@example -(use-modules (gnu) (guix)) - -(operating-system - ;; ... - (label (package-full-name - (operating-system-kernel this-operating-system)))) -@end example - -It is an error to refer to @code{this-operating-system} outside an operating -system definition. -@end deffn - -@end deftp - -@node File Systems -@section File Systems - -The list of file systems to be mounted is specified in the -@code{file-systems} field of the operating system declaration (@pxref{Using -the Configuration System}). Each file system is declared using the -@code{file-system} form, like this: - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -As usual, some of the fields are mandatory---those shown in the example -above---while others can be omitted. These are described below. - -@deftp {Data Type} file-system -Objects of this type represent file systems to be mounted. They contain the -following members: - -@table @asis -@item @code{type} -This is a string specifying the type of the file system---e.g., -@code{"ext4"}. - -@item @code{mount-point} -This designates the place where the file system is to be mounted. - -@item @code{device} -This names the ``source'' of the file system. It can be one of three -things: a file system label, a file system UUID, or the name of a -@file{/dev} node. Labels and UUIDs offer a way to refer to file systems -without having to hard-code their actual device name@footnote{Note that, -while it is tempting to use @file{/dev/disk/by-uuid} and similar device -names to achieve the same result, this is not recommended: These special -device nodes are created by the udev daemon and may be unavailable at the -time the device is mounted.}. - -@findex file-system-label -File system labels are created using the @code{file-system-label} procedure, -UUIDs are created using @code{uuid}, and @file{/dev} node are plain -strings. Here's an example of a file system referred to by its label, as -shown by the @command{e2label} command: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "my-home"))) -@end example - -@findex uuid -UUIDs are converted from their string representation (as shown by the -@command{tune2fs -l} command) using the @code{uuid} form@footnote{The -@code{uuid} form expects 16-byte UUIDs as defined in -@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the form -of UUID used by the ext2 family of file systems and others, but it is -different from ``UUIDs'' found in FAT file systems, for instance.}, like -this: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -When the source of a file system is a mapped device (@pxref{Mapped -Devices}), its @code{device} field @emph{must} refer to the mapped device -name---e.g., @file{"/dev/mapper/root-partition"}. This is required so that -the system knows that mounting the file system depends on having the -corresponding device mapping established. - -@item @code{flags} (default: @code{'()}) -This is a list of symbols denoting mount flags. Recognized flags include -@code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to -special files), @code{no-suid} (ignore setuid and setgid bits), and -@code{no-exec} (disallow program execution.) - -@item @code{options} (default: @code{#f}) -This is either @code{#f}, or a string denoting mount options. - -@item @code{mount?} (default: @code{#t}) -This value indicates whether to automatically mount the file system when the -system is brought up. When set to @code{#f}, the file system gets an entry -in @file{/etc/fstab} (read by the @command{mount} command) but is not -automatically mounted. - -@item @code{needed-for-boot?} (default: @code{#f}) -This Boolean value indicates whether the file system is needed when -booting. If that is true, then the file system is mounted when the initial -RAM disk (initrd) is loaded. This is always the case, for instance, for the -root file system. - -@item @code{check?} (default: @code{#t}) -This Boolean indicates whether the file system needs to be checked for -errors before being mounted. - -@item @code{create-mount-point?} (default: @code{#f}) -When true, the mount point is created if it does not exist yet. - -@item @code{dependencies} (default: @code{'()}) -This is a list of @code{} or @code{} objects -representing file systems that must be mounted or mapped devices that must -be opened before (and unmounted or closed after) this one. - -As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is a -dependency of @file{/sys/fs/cgroup/cpu} and @file{/sys/fs/cgroup/memory}. - -Another example is a file system that depends on a mapped device, for -example for an encrypted partition (@pxref{Mapped Devices}). -@end table -@end deftp - -The @code{(gnu system file-systems)} exports the following useful variables. - -@defvr {Scheme Variable} %base-file-systems -These are essential file systems that are required on normal systems, such -as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see -below.) Operating system declarations should always contain at least these. -@end defvr - -@defvr {Scheme Variable} %pseudo-terminal-file-system -This is the file system to be mounted as @file{/dev/pts}. It supports -@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar functions -(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}). -Pseudo-terminals are used by terminal emulators such as @command{xterm}. -@end defvr - -@defvr {Scheme Variable} %shared-memory-file-system -This file system is mounted as @file{/dev/shm} and is used to support memory -sharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc, -The GNU C Library Reference Manual}). -@end defvr - -@defvr {Scheme Variable} %immutable-store -This file system performs a read-only ``bind mount'' of @file{/gnu/store}, -making it read-only for all the users including @code{root}. This prevents -against accidental modification by software running as @code{root} or by -system administrators. - -The daemon itself is still able to write to the store: it remounts it -read-write in its own ``name space.'' -@end defvr - -@defvr {Scheme Variable} %binary-format-file-system -The @code{binfmt_misc} file system, which allows handling of arbitrary -executable file types to be delegated to user space. This requires the -@code{binfmt.ko} kernel module to be loaded. -@end defvr - -@defvr {Scheme Variable} %fuse-control-file-system -The @code{fusectl} file system, which allows unprivileged users to mount and -unmount user-space FUSE file systems. This requires the @code{fuse.ko} -kernel module to be loaded. -@end defvr - -@node Mapped Devices -@section Mapped Devices - -@cindex device mapping -@cindex mapped devices -The Linux kernel has a notion of @dfn{device mapping}: a block device, such -as a hard disk partition, can be @dfn{mapped} into another device, usually -in @code{/dev/mapper/}, with additional processing over the data that flows -through it@footnote{Note that the GNU@tie{}Hurd makes no difference between -the concept of a ``mapped device'' and that of a file system: both boil down -to @emph{translating} input/output operations made on a file to operations -on its backing store. Thus, the Hurd implements mapped devices, like file -systems, using the generic @dfn{translator} mechanism (@pxref{Translators,,, -hurd, The GNU Hurd Reference Manual}).}. A typical example is encryption -device mapping: all writes to the mapped device are encrypted, and all reads -are deciphered, transparently. Guix extends this notion by considering any -device or set of devices that are @dfn{transformed} in some way to create a -new device; for instance, RAID devices are obtained by @dfn{assembling} -several other devices, such as hard disks or partitions, into a new one that -behaves as one partition. Other examples, not yet implemented, are LVM -logical volumes. - -Mapped devices are declared using the @code{mapped-device} form, defined as -follows; for examples, see below. - -@deftp {Data Type} mapped-device -Objects of this type represent device mappings that will be made when the -system boots up. - -@table @code -@item source -This is either a string specifying the name of the block device to be -mapped, such as @code{"/dev/sda3"}, or a list of such strings when several -devices need to be assembled for creating a new one. - -@item target -This string specifies the name of the resulting mapped device. For kernel -mappers such as encrypted devices of type @code{luks-device-mapping}, -specifying @code{"my-partition"} leads to the creation of the -@code{"/dev/mapper/my-partition"} device. For RAID devices of type -@code{raid-device-mapping}, the full device name such as @code{"/dev/md0"} -needs to be given. - -@item type -This must be a @code{mapped-device-kind} object, which specifies how -@var{source} is mapped to @var{target}. -@end table -@end deftp - -@defvr {Scheme Variable} luks-device-mapping -This defines LUKS block device encryption using the @command{cryptsetup} -command from the package with the same name. It relies on the -@code{dm-crypt} Linux kernel module. -@end defvr - -@defvr {Scheme Variable} raid-device-mapping -This defines a RAID device, which is assembled using the @code{mdadm} -command from the package with the same name. It requires a Linux kernel -module for the appropriate RAID level to be loaded, such as @code{raid456} -for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10. -@end defvr - -@cindex disk encryption -@cindex LUKS -The following example specifies a mapping from @file{/dev/sda3} to -@file{/dev/mapper/home} using LUKS---the -@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a -standard mechanism for disk encryption. The @file{/dev/mapper/home} device -can then be used as the @code{device} of a @code{file-system} declaration -(@pxref{File Systems}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -Alternatively, to become independent of device numbering, one may obtain the -LUKS UUID (@dfn{unique identifier}) of the source device by a command like: - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -and use it as follows: - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex swap encryption -It is also desirable to encrypt swap space, since swap space may contain -sensitive data. One way to accomplish that is to use a swap file in a file -system on a device mapped via LUKS encryption. In this way, the swap file -is encrypted because the entire device is encrypted. @xref{Preparing for -Installation,,Disk Partitioning}, for an example. - -A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1} -may be declared as follows: - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -The @file{/dev/md0} device can then be used as the @code{device} of a -@code{file-system} declaration (@pxref{File Systems}). Note that the RAID -level need not be given; it is chosen during the initial creation and -formatting of the RAID device and is determined automatically later. - - -@node User Accounts -@section User Accounts - -@cindex users -@cindex accounts -@cindex user accounts -User accounts and groups are entirely managed through the -@code{operating-system} declaration. They are specified with the -@code{user-account} and @code{user-group} forms: - -@example -(user-account - (name "alice") - (group "users") - (supplementary-groups '("wheel" ;allow use of sudo, etc. - "audio" ;sound card - "video" ;video devices such as webcams - "cdrom")) ;the good ol' CD-ROM - (comment "Bob's sister") - (home-directory "/home/alice")) -@end example - -When booting or upon completion of @command{guix system reconfigure}, the -system ensures that only the user accounts and groups specified in the -@code{operating-system} declaration exist, and with the specified -properties. Thus, account or group creations or modifications made by -directly invoking commands such as @command{useradd} are lost upon -reconfiguration or reboot. This ensures that the system remains exactly as -declared. - -@deftp {Data Type} user-account -Objects of this type represent user accounts. The following members may be -specified: - -@table @asis -@item @code{name} -The name of the user account. - -@item @code{group} -@cindex groups -This is the name (a string) or identifier (a number) of the user group this -account belongs to. - -@item @code{supplementary-groups} (default: @code{'()}) -Optionally, this can be defined as a list of group names that this account -belongs to. - -@item @code{uid} (default: @code{#f}) -This is the user ID for this account (a number), or @code{#f}. In the -latter case, a number is automatically chosen by the system when the account -is created. - -@item @code{comment} (default: @code{""}) -A comment about the account, such as the account owner's full name. - -@item @code{home-directory} -This is the name of the home directory for the account. - -@item @code{create-home-directory?} (default: @code{#t}) -Indicates whether the home directory of this account should be created if it -does not exist yet. - -@item @code{shell} (default: Bash) -This is a G-expression denoting the file name of a program to be used as the -shell (@pxref{G-Expressions}). - -@item @code{system?} (default: @code{#f}) -This Boolean value indicates whether the account is a ``system'' account. -System accounts are sometimes treated specially; for instance, graphical -login managers do not list them. - -@anchor{user-account-password} -@cindex password, for user accounts -@item @code{password} (default: @code{#f}) -You would normally leave this field to @code{#f}, initialize user passwords -as @code{root} with the @command{passwd} command, and then let users change -it with @command{passwd}. Passwords set with @command{passwd} are of course -preserved across reboot and reconfiguration. - -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") - (group "users") - - ;; Specify a SHA-512-hashed initial password. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Note -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 groups -User group declarations are even simpler: - -@example -(user-group (name "students")) -@end example - -@deftp {Data Type} user-group -This type is for, well, user groups. There are just a few fields: - -@table @asis -@item @code{name} -The name of the group. - -@item @code{id} (default: @code{#f}) -The group identifier (a number). If @code{#f}, a new number is -automatically allocated when the group is created. - -@item @code{system?} (default: @code{#f}) -This Boolean value indicates whether the group is a ``system'' group. -System groups have low numerical IDs. - -@item @code{password} (default: @code{#f}) -What, user groups can have a password? Well, apparently yes. Unless -@code{#f}, this field specifies the password of the group. - -@end table -@end deftp - -For convenience, a variable lists all the basic user groups one may expect: - -@defvr {Scheme Variable} %base-groups -This is the list of basic user groups that users and/or packages expect to -be present on the system. This includes groups such as ``root'', ``wheel'', -and ``users'', as well as groups used to control access to specific devices -such as ``audio'', ``disk'', and ``cdrom''. -@end defvr - -@defvr {Scheme Variable} %base-user-accounts -This is the list of basic system accounts that programs may expect to find -on a GNU/Linux system, such as the ``nobody'' account. - -Note that the ``root'' account is not included here. It is a special-case -and is automatically added whether or not it is specified. -@end defvr - -@node Keyboard Layout -@section Keyboard Layout - -@cindex keyboard layout -@cindex keymap -To specify what each key of your keyboard does, you need to tell the -operating system what @dfn{keyboard layout} you want to use. The default, -when nothing is specified, is the US English QWERTY layout for 105-key PC -keyboards. However, German speakers will usually prefer the German QWERTZ -layout, French speakers will want the AZERTY layout, and so on; hackers -might prefer Dvorak or bépo, and they might even want to further customize -the effect of some of the keys. This section explains how to get that done. - -@cindex keyboard layout, definition -There are three components that will want to know about your keyboard -layout: - -@itemize -@item -The @emph{bootloader} may want to know what keyboard layout you want to use -(@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is useful -if you want, for instance, to make sure that you can type the passphrase of -your encrypted root partition using the right layout. - -@item -The @emph{operating system kernel}, Linux, will need that so that the -console is properly configured (@pxref{operating-system Reference, -@code{keyboard-layout}}). - -@item -The @emph{graphical display server}, usually Xorg, also has its own idea of -the keyboard layout (@pxref{X Window, @code{keyboard-layout}}). -@end itemize - -Guix allows you to configure all three separately but, fortunately, it -allows you to share the same keyboard layout for all three components. - -@cindex XKB, keyboard layouts -Keyboard layouts are represented by records created by the -@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following -the X Keyboard extension (XKB), each layout has four attributes: a name -(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), -an optional variant name, an optional keyboard model name, and a possibly -empty list of additional options. In most cases the layout name is all you -care about. Here are a few example: - -@example -;; The German QWERTZ layout. Here we assume a standard -;; "pc105" keyboard model. -(keyboard-layout "de") - -;; The bépo variant of the French layout. -(keyboard-layout "fr" "bepo") - -;; The Catalan layout. -(keyboard-layout "es" "cat") - -;; The Latin American Spanish layout. In addition, the -;; "Caps Lock" key is used as an additional "Ctrl" key, -;; and the "Menu" key is used as a "Compose" key to enter -;; accented letters. -(keyboard-layout "latam" - #:options '("ctrl:nocaps" "compose:menu")) - -;; The Russian layout for a ThinkPad keyboard. -(keyboard-layout "ru" #:model "thinkpad") - -;; The "US international" layout, which is the US layout plus -;; dead keys to enter accented characters. This is for an -;; Apple MacBook keyboard. -(keyboard-layout "us" "intl" #:model "macbook78") -@end example - -See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} -package for a complete list of supported layouts, variants, and models. - -@cindex keyboard layout, configuration -Let's say you want your system to use the Turkish keyboard layout throughout -your system---bootloader, console, and Xorg. Here's what your system -configuration would look like: - -@findex set-xorg-configuration -@lisp -;; Using the Turkish layout for the bootloader, the console, -;; and for Xorg. - -(operating-system - ;; ... - (keyboard-layout (keyboard-layout "tr")) ;for the console - (bootloader (bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi") - (keyboard-layout keyboard-layout))) ;for GRUB - (services (cons (set-xorg-configuration - (xorg-configuration ;for Xorg - (keyboard-layout keyboard-layout))) - %desktop-services))) -@end lisp - -In the example above, for GRUB and for Xorg, we just refer to the -@code{keyboard-layout} field defined above, but we could just as well refer -to a different layout. The @code{set-xorg-configuration} procedure -communicates the desired Xorg configuration to the graphical log-in manager, -by default GDM. - -We've discussed how to specify the @emph{default} keyboard layout of your -system when it starts, but you can also adjust it at run time: - -@itemize -@item -If you're using GNOME, its settings panel has a ``Region & Language'' entry -where you can select one or more keyboard layouts. - -@item -Under Xorg, the @command{setxkbmap} command (from the same-named package) -allows you to change the current layout. For example, this is how you would -change the layout to US Dvorak: - -@example -setxkbmap us dvorak -@end example - -@item -The @code{loadkeys} command changes the keyboard layout in effect in the -Linux console. However, note that @code{loadkeys} does @emph{not} use the -XKB keyboard layout categorization described above. The command below loads -the French bépo layout: - -@example -loadkeys fr-bepo -@end example -@end itemize - -@node Locales -@section Locales - -@cindex locale -A @dfn{locale} defines cultural conventions for a particular language and -region of the world (@pxref{Locales,,, libc, The GNU C Library Reference -Manual}). Each locale has a name that typically has the form -@code{@var{language}_@var{territory}.@var{codeset}}---e.g., -@code{fr_LU.utf8} designates the locale for the French language, with -cultural conventions from Luxembourg, and using the UTF-8 encoding. - -@cindex locale definition -Usually, you will want to specify the default locale for the machine using -the @code{locale} field of the @code{operating-system} declaration -(@pxref{operating-system Reference, @code{locale}}). - -The selected locale is automatically added to the @dfn{locale definitions} -known to the system if needed, with its codeset inferred from its -name---e.g., @code{bo_CN.utf8} will be assumed to use the @code{UTF-8} -codeset. Additional locale definitions can be specified in the -@code{locale-definitions} slot of @code{operating-system}---this is useful, -for instance, if the codeset could not be inferred from the locale name. -The default set of locale definitions includes some widely used locales, but -not all the available locales, in order to save space. - -For instance, to add the North Frisian locale for Germany, the value of that -field may be: - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -Likewise, to save space, one might want @code{locale-definitions} to list -only the locales that are actually used, as in: - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -The compiled locale definitions are available at -@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc version, -which is the default location where the GNU@tie{}libc provided by Guix looks -for locale data. This can be overridden using the @code{LOCPATH} -environment variable (@pxref{locales-and-locpath, @code{LOCPATH} and locale -packages}). - -The @code{locale-definition} form is provided by the @code{(gnu system -locale)} module. Details are given below. - -@deftp {Data Type} locale-definition -This is the data type of a locale definition. - -@table @asis - -@item @code{name} -The name of the locale. @xref{Locale Names,,, libc, The GNU C Library -Reference Manual}, for more information on locale names. - -@item @code{source} -The name of the source for that locale. This is typically the -@code{@var{language}_@var{territory}} part of the locale name. - -@item @code{charset} (default: @code{"UTF-8"}) -The ``character set'' or ``code set'' for that locale, -@uref{http://www.iana.org/assignments/character-sets, as defined by IANA}. - -@end table -@end deftp - -@defvr {Scheme Variable} %default-locale-definitions -A list of commonly used UTF-8 locales, used as the default value of the -@code{locale-definitions} field of @code{operating-system} declarations. - -@cindex locale name -@cindex normalized codeset in locale names -These locale definitions use the @dfn{normalized codeset} for the part that -follows the dot in the name (@pxref{Using gettextized software, normalized -codeset,, libc, The GNU C Library Reference Manual}). So for instance it -has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}. -@end defvr - -@subsection Locale Data Compatibility Considerations - -@cindex incompatibility, of locale data -@code{operating-system} declarations provide a @code{locale-libcs} field to -specify the GNU@tie{}libc packages that are used to compile locale -declarations (@pxref{operating-system Reference}). ``Why would I care?'', -you may ask. Well, it turns out that the binary format of locale data is -occasionally incompatible from one libc version to another. - -@c See -@c and . -For instance, a program linked against libc version 2.21 is unable to read -locale data produced with libc 2.22; worse, that program @emph{aborts} -instead of simply ignoring the incompatible locale data@footnote{Versions -2.23 and later of GNU@tie{}libc will simply skip the incompatible locale -data, which is already an improvement.}. Similarly, a program linked -against libc 2.22 can read most, but not all, of the locale data from libc -2.21 (specifically, @code{LC_COLLATE} data is incompatible); thus calls to -@code{setlocale} may fail, but programs will not abort. - -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. - -Fortunately, unprivileged users can also install their own locale data and -define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath, -@code{GUIX_LOCPATH} and locale packages}). - -Still, it is best if the system-wide locale data at -@file{/run/current-system/locale} is built for all the libc versions -actually in use on the system, so that all the programs can access it---this -is especially crucial on a multi-user system. To do that, the administrator -can specify several libc packages in the @code{locale-libcs} field of -@code{operating-system}: - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -This example would lead to a system containing locale definitions for both -libc 2.21 and the current version of libc in -@file{/run/current-system/locale}. - - -@node Services -@section Services - -@cindex system services -An important part of preparing an @code{operating-system} declaration is -listing @dfn{system services} and their configuration (@pxref{Using the -Configuration System}). System services are typically daemons launched when -the system boots, or other actions needed at that time---e.g., configuring -network access. - -Guix has a broad definition of ``service'' (@pxref{Service Composition}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd -Services}). 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 - -The above command, run as @code{root}, lists the currently defined -services. The @command{herd doc} command shows a synopsis of the given -service and its associated actions: - -@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 - -The @command{start}, @command{stop}, and @command{restart} sub-commands have -the effect you would expect. For instance, the commands below stop the nscd -service and restart the Xorg display server: - -@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 - -The following sections document the available services, starting with the -core services, that may be used in an @code{operating-system} declaration. - -@menu -* Base Services:: Essential system services. -* Scheduled Job Execution:: The mcron service. -* Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. -* X Window:: Graphical display. -* Printing Services:: Local and remote printer support. -* Desktop Services:: D-Bus and desktop services. -* Sound Services:: ALSA and Pulseaudio services. -* Database Services:: SQL databases, key-value stores, etc. -* Mail Services:: IMAP, POP3, SMTP, and all that. -* Messaging Services:: Messaging services. -* Telephony Services:: Telephony services. -* Monitoring Services:: Monitoring services. -* Kerberos Services:: Kerberos services. -* LDAP Services:: LDAP services. -* Web Services:: Web servers. -* Certificate Services:: TLS certificates via Let's Encrypt. -* DNS Services:: DNS daemons. -* VPN Services:: VPN daemons. -* Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. -* Power Management Services:: Extending battery life. -* Audio Services:: The MPD. -* Virtualization Services:: Virtualization services. -* Version Control Services:: Providing remote access to Git repositories. -* Game Services:: Game servers. -* Miscellaneous Services:: Other services. -@end menu - -@node Base Services -@subsection Base Services - -The @code{(gnu services base)} module provides definitions for the basic -services that one expects from the system. The services exported by this -module are listed below. - -@defvr {Scheme Variable} %base-services -This variable contains a list of basic services (@pxref{Service Types and -Services}, for more information on service objects) one would expect from -the system: a login service (mingetty) on each tty, syslogd, the libc name -service cache daemon (nscd), the udev device manager, and more. - -This is the default value of the @code{services} field of -@code{operating-system} declarations. Usually, when customizing a system, -you will want to append services to @var{%base-services}, like this: - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Scheme Variable} special-files-service-type -This is the service that sets up ``special files'' such as @file{/bin/sh}; -an instance of it is part of @code{%base-services}. - -The value associated with @code{special-files-service-type} services must be -a list of tuples where the first element is the ``special file'' and the -second element is its target. By default it is: - -@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} -If you want to add, say, @code{/usr/bin/env} to your system, you can change -it to: - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Since this is part of @code{%base-services}, you can use -@code{modify-services} to customize the set of special files (@pxref{Service -Reference, @code{modify-services}}). But the simple way to add a special -file is @i{via} the @code{extra-special-file} procedure (see below.) -@end defvr - -@deffn {Scheme Procedure} extra-special-file @var{file} @var{target} -Use @var{target} as the ``special file'' @var{file}. - -For example, adding the following lines to the @code{services} field of your -operating system declaration leads to a @file{/usr/bin/env} symlink: - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Scheme Procedure} host-name-service @var{name} -Return a service that sets the host name to @var{name}. -@end deffn - -@deffn {Scheme Procedure} login-service @var{config} -Return a service to run login according to @var{config}, a -@code{} object, which specifies the message of the day, -among other things. -@end deffn - -@deftp {Data Type} login-configuration -This is the data type representing the configuration of login. - -@table @asis - -@item @code{motd} -@cindex message of the day -A file-like object containing the ``message of the day''. - -@item @code{allow-empty-passwords?} (default: @code{#t}) -Allow empty passwords by default so that first-time users can log in when -the 'root' account has just been created. - -@end table -@end deftp - -@deffn {Scheme Procedure} mingetty-service @var{config} -Return a service to run mingetty according to @var{config}, a -@code{} object, which specifies the tty to run, -among other things. -@end deffn - -@deftp {Data Type} mingetty-configuration -This is the data type representing the configuration of Mingetty, which -provides the default implementation of virtual console log-in. - -@table @asis - -@item @code{tty} -The name of the console this Mingetty runs on---e.g., @code{"tty1"}. - -@item @code{auto-login} (default: @code{#f}) -When true, this field must be a string denoting the user name under which -the system automatically logs in. When it is @code{#f}, a user name and -password must be entered to log in. - -@item @code{login-program} (default: @code{#f}) -This must be either @code{#f}, in which case the default log-in program is -used (@command{login} from the Shadow tool suite), or a gexp denoting the -name of the log-in program. - -@item @code{login-pause?} (default: @code{#f}) -When set to @code{#t} in conjunction with @var{auto-login}, the user will -have to press a key before the log-in shell is launched. - -@item @code{mingetty} (default: @var{mingetty}) -The Mingetty package to use. - -@end table -@end deftp - -@deffn {Scheme Procedure} agetty-service @var{config} -Return a service to run agetty according to @var{config}, an -@code{} object, which specifies the tty to run, among -other things. -@end deffn - -@deftp {Data Type} agetty-configuration -This is the data type representing the configuration of agetty, which -implements virtual and serial console log-in. See the @code{agetty(8)} man -page for more information. - -@table @asis - -@item @code{tty} -The name of the console this agetty runs on, as a string---e.g., -@code{"ttyS0"}. This argument is optional, it will default to a reasonable -default serial port used by the kernel Linux. - -For this, if there is a value for an option @code{agetty.tty} in the kernel -command line, agetty will extract the device name of the serial port from it -and use that. - -If not and if there is a value for an option @code{console} with a tty in -the Linux command line, agetty will extract the device name of the serial -port from it and use that. - -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} (default: @code{#f}) -A string containing a comma-separated list of one or more baud rates, in -descending order. - -@item @code{term} (default: @code{#f}) -A string containing the value used for the @code{TERM} environment variable. - -@item @code{eight-bits?} (default: @code{#f}) -When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection -is disabled. - -@item @code{auto-login} (default: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{no-reset?} (default: @code{#f}) -When @code{#t}, don't reset terminal cflags (control modes). - -@item @code{host} (default: @code{#f}) -This accepts a string containing the "login_host", which will be written -into the @file{/var/run/utmpx} file. - -@item @code{remote?} (default: @code{#f}) -When set to @code{#t} in conjunction with @var{host}, this will add an -@code{-r} fakehost option to the command line of the login program specified -in @var{login-program}. - -@item @code{flow-control?} (default: @code{#f}) -When set to @code{#t}, enable hardware (RTS/CTS) flow control. - -@item @code{no-issue?} (default: @code{#f}) -When set to @code{#t}, the contents of the @file{/etc/issue} file will not -be displayed before presenting the login prompt. - -@item @code{init-string} (default: @code{#f}) -This accepts a string that will be sent to the tty or modem before sending -anything else. It can be used to initialize a modem. - -@item @code{no-clear?} (default: @code{#f}) -When set to @code{#t}, agetty will not clear the screen before showing the -login prompt. - -@item @code{login-program} (default: (file-append shadow "/bin/login")) -This must be either a gexp denoting the name of a log-in program, or unset, -in which case the default value is the @command{login} from the Shadow tool -suite. - -@item @code{local-line} (default: @code{#f}) -Control the CLOCAL line flag. This accepts one of three symbols as -arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, the -default value chosen by agetty is @code{'auto}. - -@item @code{extract-baud?} (default: @code{#f}) -When set to @code{#t}, instruct agetty to try to extract the baud rate from -the status messages produced by certain types of modems. - -@item @code{skip-login?} (default: @code{#f}) -When set to @code{#t}, do not prompt the user for a login name. This can be -used with @var{login-program} field to use non-standard login systems. - -@item @code{no-newline?} (default: @code{#f}) -When set to @code{#t}, do not print a newline before printing the -@file{/etc/issue} file. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (default: @code{#f}) -This option accepts a string containing options that are passed to the login -program. When used with the @var{login-program}, be aware that a malicious -user could try to enter a login name containing embedded options that could -be parsed by the login program. - -@item @code{login-pause} (default: @code{#f}) -When set to @code{#t}, wait for any key before showing the login prompt. -This can be used in conjunction with @var{auto-login} to save memory by -lazily spawning shells. - -@item @code{chroot} (default: @code{#f}) -Change root to the specified directory. This option accepts a directory -path as a string. - -@item @code{hangup?} (default: @code{#f}) -Use the Linux system call @code{vhangup} to do a virtual hangup of the -specified terminal. - -@item @code{keep-baud?} (default: @code{#f}) -When set to @code{#t}, try to keep the existing baud rate. The baud rates -from @var{baud-rate} are used when agetty receives a @key{BREAK} character. - -@item @code{timeout} (default: @code{#f}) -When set to an integer value, terminate if no user name could be read within -@var{timeout} seconds. - -@item @code{detect-case?} (default: @code{#f}) -When set to @code{#t}, turn on support for detecting an uppercase-only -terminal. This setting will detect a login name containing only uppercase -letters as indicating an uppercase-only terminal and turn on some -upper-to-lower case conversions. Note that this will not support Unicode -characters. - -@item @code{wait-cr?} (default: @code{#f}) -When set to @code{#t}, wait for the user or modem to send a carriage-return -or linefeed character before displaying @file{/etc/issue} or login prompt. -This is typically used with the @var{init-string} option. - -@item @code{no-hints?} (default: @code{#f}) -When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks. - -@item @code{no-hostname?} (default: @code{#f}) -By default, the hostname is printed. When this option is set to @code{#t}, -no hostname will be shown at all. - -@item @code{long-hostname?} (default: @code{#f}) -By default, the hostname is only printed until the first dot. When this -option is set to @code{#t}, the fully qualified hostname by -@code{gethostname} or @code{getaddrinfo} is shown. - -@item @code{erase-characters} (default: @code{#f}) -This option accepts a string of additional characters that should be -interpreted as backspace when the user types their login name. - -@item @code{kill-characters} (default: @code{#f}) -This option accepts a string that should be interpreted to mean "ignore all -previous characters" (also called a "kill" character) when the types their -login name. - -@item @code{chdir} (default: @code{#f}) -This option accepts, as a string, a directory path that will be changed to -before login. - -@item @code{delay} (default: @code{#f}) -This options accepts, as an integer, the number of seconds to sleep before -opening the tty and displaying the login prompt. - -@item @code{nice} (default: @code{#f}) -This option accepts, as an integer, the nice value with which to run the -@command{login} program. - -@item @code{extra-options} (default: @code{'()}) -This option provides an "escape hatch" for the user to provide arbitrary -command-line arguments to @command{agetty} as a list of strings. - -@end table -@end deftp - -@deffn {Scheme Procedure} kmscon-service-type @var{config} -Return a service to run -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} according to -@var{config}, a @code{} object, which specifies the -tty to run, among other things. -@end deffn - -@deftp {Data Type} kmscon-configuration -This is the data type representing the configuration of Kmscon, which -implements virtual console log-in. - -@table @asis - -@item @code{virtual-terminal} -The name of the console this Kmscon runs on---e.g., @code{"tty1"}. - -@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")}) -A gexp denoting the name of the log-in program. The default log-in program -is @command{login} from the Shadow tool suite. - -@item @code{login-arguments} (default: @code{'("-p")}) -A list of arguments to pass to @command{login}. - -@item @code{auto-login} (default: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{hardware-acceleration?} (default: #f) -Whether to use hardware acceleration. - -@item @code{kmscon} (default: @var{kmscon}) -The Kmscon package to use. - -@end table -@end deftp - -@cindex name service cache daemon -@cindex nscd -@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @ - [#:name-services '()] Return a service that runs the libc name service cache -daemon (nscd) with the given @var{config}---an @code{} -object. @xref{Name Service Switch}, for an example. - -For convenience, the Shepherd service for nscd provides the following -actions: - -@table @code -@item invalidate -@cindex cache invalidation, nscd -@cindex nscd, cache invalidation -This invalidate the given cache. For instance, running: - -@example -herd invalidate nscd hosts -@end example - -@noindent -invalidates the host name lookup cache of nscd. - -@item statistics -Running @command{herd statistics nscd} displays information about nscd usage -and caches. -@end table - -@end deffn - -@defvr {Scheme Variable} %nscd-default-configuration -This is the default @code{} value (see below) used by -@code{nscd-service}. It uses the caches defined by -@var{%nscd-default-caches}; see below. -@end defvr - -@deftp {Data Type} nscd-configuration -This is the data type representing the name service cache daemon (nscd) -configuration. - -@table @asis - -@item @code{name-services} (default: @code{'()}) -List of packages denoting @dfn{name services} that must be visible to the -nscd---e.g., @code{(list @var{nss-mdns})}. - -@item @code{glibc} (default: @var{glibc}) -Package object denoting the GNU C Library providing the @command{nscd} -command. - -@item @code{log-file} (default: @code{"/var/log/nscd.log"}) -Name of the nscd log file. This is where debugging output goes when -@code{debug-level} is strictly positive. - -@item @code{debug-level} (default: @code{0}) -Integer denoting the debugging levels. Higher numbers mean that more -debugging output is logged. - -@item @code{caches} (default: @var{%nscd-default-caches}) -List of @code{} objects denoting things to be cached; see below. - -@end table -@end deftp - -@deftp {Data Type} nscd-cache -Data type representing a cache database of nscd and its parameters. - -@table @asis - -@item @code{database} -This is a symbol representing the name of the database to be cached. Valid -values are @code{passwd}, @code{group}, @code{hosts}, and @code{services}, -which designate the corresponding NSS database (@pxref{NSS Basics,,, libc, -The GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (default: @code{20}) -A number representing the number of seconds during which a positive or -negative lookup result remains in cache. - -@item @code{check-files?} (default: @code{#t}) -Whether to check for updates of the files corresponding to @var{database}. - -For instance, when @var{database} is @code{hosts}, setting this flag -instructs nscd to check for updates in @file{/etc/hosts} and to take them -into account. - -@item @code{persistent?} (default: @code{#t}) -Whether the cache should be stored persistently on disk. - -@item @code{shared?} (default: @code{#t}) -Whether the cache should be shared among users. - -@item @code{max-database-size} (default: 32@tie{}MiB) -Maximum size in bytes of the database cache. - -@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 -List of @code{} objects used by default by -@code{nscd-configuration} (see above). - -It enables persistent and aggressive caching of service and host name -lookups. The latter provides better host name lookup performance, -resilience in the face of unreliable name servers, and also better -privacy---often the result of host name lookups is in local cache, so -external name servers do not even need to be queried. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex logging -@deftp {Data Type} syslog-configuration -This data type represents the configuration of the syslog daemon. - -@table @asis -@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")}) -The syslog daemon to use. - -@item @code{config-file} (default: @code{%default-syslog.conf}) -The syslog configuration file to use. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Scheme Procedure} syslog-service @var{config} -Return a service that runs a syslog daemon according to @var{config}. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more information -on the configuration file syntax. -@end deffn - -@defvr {Scheme Variable} guix-service-type -This is the type of the service that runs the build daemon, -@command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a -@code{guix-configuration} record as described below. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Data Type} guix-configuration -This data type represents the configuration of the Guix build daemon. -@xref{Invoking guix-daemon}, for more information. - -@table @asis -@item @code{guix} (default: @var{guix}) -The Guix package to use. - -@item @code{build-group} (default: @code{"guixbuild"}) -Name of the group for build user accounts. - -@item @code{build-accounts} (default: @code{10}) -Number of build user accounts to create. - -@item @code{authorize-key?} (default: @code{#t}) -@cindex substitutes, authorization thereof -Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substitutes}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys}) -The list of authorized key files for archive imports, as a list of -string-valued gexps (@pxref{Invoking guix archive}). By default, it -contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}). - -@item @code{use-substitutes?} (default: @code{#t}) -Whether to use substitutes. - -@item @code{substitute-urls} (default: @var{%default-substitute-urls}) -The list of URLs where to look for substitutes by default. - -@item @code{max-silent-time} (default: @code{0}) -@itemx @code{timeout} (default: @code{0}) -The number of seconds of silence and the number of seconds of activity, -respectively, after which a build process times out. A value of zero -disables the timeout. - -@item @code{log-compression} (default: @code{'bzip2}) -The type of compression used for build logs---one of @code{gzip}, -@code{bzip2}, or @code{none}. - -@item @code{extra-options} (default: @code{'()}) -List of extra command-line options for @command{guix-daemon}. - -@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"}) -File where @command{guix-daemon}'s standard output and standard error are -written. - -@item @code{http-proxy} (default: @code{#f}) -The HTTP proxy used for downloading fixed-output derivations and -substitutes. - -@item @code{tmpdir} (default: @code{#f}) -A directory path where the @command{guix-daemon} will perform builds. - -@end table -@end deftp - -@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Run @var{udev}, which populates the @file{/dev} directory dynamically. udev -rules can be provided as a list of files through the @var{rules} variable. -The procedures @var{udev-rule} and @var{file->udev-rule} from @code{(gnu -services base)} simplify the creation of such rule files. -@end deffn - -@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] -Return a udev-rule file named @var{file-name} containing the rules defined -by the @var{contents} literal. - -In the following example, a rule for a USB device is defined to be stored in -the file @file{90-usb-thing.rules}. The rule runs a script upon detecting a -USB device with a given product identifier. - -@example -(define %example-udev-rule - (udev-rule - "90-usb-thing.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Example\", " - "RUN+=\"/path/to/script\""))) -@end example - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@end deffn - -Here we show how the default @var{udev-service} can be extended with it. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %example-udev-rule)))))))) -@end example - -@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}] -Return a udev file named @var{file-name} containing the rules defined within -@var{file}, a file-like object. - -The following example showcases how we can use an existing rule file. - -@example -(use-modules (guix download) ;for url-fetch - (guix packages) ;for 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 - -Additionally, Guix package definitions can be included in @var{rules} in -order to extend the udev rules with the definitions found under their -@file{lib/udev/rules.d} sub-directory. In lieu of the previous -@var{file->udev-rule} example, we could have used the -@var{android-udev-rules} package which exists in Guix in the @code{(gnu -packages android)} module. - -The following example shows how to use the @var{android-udev-rules} package -so that the Android tool @command{adb} can detect devices without root -privileges. It also details how to create the @code{adbusers} group, which -is required for the proper functioning of the rules defined within the -@var{android-udev-rules} package. To create such a group, we must define it -both as part of the @var{supplementary-groups} of our @var{user-account} -declaration, as well as in the @var{groups} field of the -@var{operating-system} record. - -@example -(use-modules (gnu packages android) ;for android-udev-rules - (gnu system shadow) ;for user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;for 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 -Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom} -when rebooting. It also tries to seed @file{/dev/urandom} from -@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is -readable. -@end defvr - -@defvr {Scheme Variable} %random-seed-file -This is the name of the file where some random bytes are saved by -@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It -defaults to @file{/var/lib/random-seed}. -@end defvr - -@cindex mouse -@cindex gpm -@defvr {Scheme Variable} gpm-service-type -This is the type of the service that runs GPM, the @dfn{general-purpose -mouse daemon}, which provides mouse support to the Linux console. GPM -allows users to use the mouse in the console, notably to select, copy, and -paste text. - -The value for services of this type must be a @code{gpm-configuration} (see -below). This service is not part of @var{%base-services}. -@end defvr - -@deftp {Data Type} gpm-configuration -Data type representing the configuration of GPM. - -@table @asis -@item @code{options} (default: @code{%default-gpm-options}) -Command-line options passed to @command{gpm}. The default set of options -instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}. -@xref{Command Line,,, gpm, gpm manual}, for more information. - -@item @code{gpm} (default: @code{gpm}) -The GPM package to use. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Scheme Variable} guix-publish-service-type -This is the service type for @command{guix publish} (@pxref{Invoking guix -publish}). Its value must be a @code{guix-configuration} object, as -described below. - -This assumes that @file{/etc/guix} already contains a signing key pair as -created by @command{guix archive --generate-key} (@pxref{Invoking guix -archive}). If that is not the case, the service will fail to start. -@end deffn - -@deftp {Data Type} guix-publish-configuration -Data type representing the configuration of the @code{guix publish} service. - -@table @asis -@item @code{guix} (default: @code{guix}) -The Guix package to use. - -@item @code{port} (default: @code{80}) -The TCP port to listen for connections. - -@item @code{host} (default: @code{"localhost"}) -The host (and thus, network interface) to listen to. Use @code{"0.0.0.0"} -to listen on all the network interfaces. - -@item @code{compression-level} (default: @code{3}) -The gzip compression level at which substitutes are compressed. Use -@code{0} to disable compression altogether, and @code{9} to get the best -compression ratio at the expense of increased CPU usage. - -@item @code{nar-path} (default: @code{"nar"}) -The URL path at which ``nars'' can be fetched. @xref{Invoking guix publish, -@code{--nar-path}}, for details. - -@item @code{cache} (default: @code{#f}) -When it is @code{#f}, disable caching and instead generate archives on -demand. Otherwise, this should be the name of a directory---e.g., -@code{"/var/cache/guix/publish"}---where @command{guix publish} caches -archives and meta-data ready to be sent. @xref{Invoking guix publish, -@option{--cache}}, for more information on the tradeoffs involved. - -@item @code{workers} (default: @code{#f}) -When it is an integer, this is the number of worker threads used for -caching; when @code{#f}, the number of processors is used. @xref{Invoking -guix publish, @option{--workers}}, for more information. - -@item @code{ttl} (default: @code{#f}) -When it is an integer, this denotes the @dfn{time-to-live} in seconds of the -published archives. @xref{Invoking guix publish, @option{--ttl}}, for more -information. -@end table -@end deftp - -@anchor{rngd-service} -@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] Return a service that runs the @command{rngd} -program from @var{rng-tools} to add @var{device} to the kernel's entropy -pool. The service will fail if @var{device} does not exist. -@end deffn - -@anchor{pam-limits-service} -@cindex session limits -@cindex ulimit -@cindex priority -@cindex realtime -@cindex jackd -@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}] - -Return a service that installs a configuration file for the -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, -@code{pam_limits} module}. The procedure optionally takes a list of -@code{pam-limits-entry} values, which can be used to specify @code{ulimit} -limits and nice priority limits to user sessions. - -The following limits definition sets two hard and soft limits for all login -sessions of users in the @code{realtime} group: - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -The first entry increases the maximum realtime priority for non-privileged -processes; the second entry lifts any restriction of the maximum address -space that can be locked in memory. These settings are commonly used for -real-time audio systems. -@end deffn - -@node Scheduled Job Execution -@subsection Scheduled Job Execution - -@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{Invoking 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-Expressions}). - -@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{Service Composition}). 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-Expressions}), 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 logging -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{Scheduled Job Execution}) 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{Scheduled Job Execution}). -@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 Networking Services -@subsection Networking Services - -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{}. 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-Expressions, 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 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. - -For example: - -@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 wireless -@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 Services}). -@end defvr - -@deftp {Data Type} modem-manager-configuration -Data type representing the configuration of ModemManager. - -@table @asis -@item @code{modem-manager} (default: @code{modem-manager}) -The ModemManager package to use. - -@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 Services}). -@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 -Data type representing the configuration of WPA Supplicant. - -It takes the following parameters: - -@table @asis -@item @code{wpa-supplicant} (default: @code{wpa-supplicant}) -The WPA Supplicant package to use. - -@item @code{dbus?} (default: @code{#t}) -Whether to listen for requests on D-Bus. - -@item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"}) -Where to store the PID file. - -@item @code{interface} (default: @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}) -Optional configuration file to use. - -@item @code{extra-options} (default: @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 {Data Type} iptables-configuration -The data type representing the configuration of iptables. - -@table @asis -@item @code{iptables} (default: @code{iptables}) -The iptables package that provides @code{iptables-restore} and -@code{ip6tables-restore}. -@item @code{ipv4-rules} (default: @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-Expressions, file-like -objects}). -@item @code{ipv6-rules} (default: @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-Expressions, file-like -objects}). -@end table -@end deftp - -@cindex NTP (Network Time Protocol), service -@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 {Data Type} ntp-configuration -This is the data type for the NTP service configuration. - -@table @asis -@item @code{servers} (default: @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} (default: @code{ntp}) -The NTP package to use. -@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} (default: @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?} (default: @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} (default: @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{} 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 {Data Type} tor-configuration -@table @asis -@item @code{tor} (default: @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} (default: @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-Expressions, file-like objects}). See @code{man tor} for details -on the configuration file syntax. - -@item @code{hidden-services} (default: @code{'()}) -The list of @code{} 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{} records using the -@code{tor-hidden-service} procedure described below. - -@item @code{socks-socket-type} (default: @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?} (default: @code{#t}) -Whether to allow agent forwarding. - -@item @code{allow-tcp-forwarding?} (default: @code{#t}) -Whether to allow TCP forwarding. - -@item @code{gateway-ports?} (default: @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} (default: @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} (default: @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{} -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 Reference, -@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 the GNOME Display Manager (GDM). - -@cindex GDM -@cindex GNOME, login manager -GDM of course allows users to log in into window managers and desktop -environments other than GNOME; for those using GNOME, GDM is required for -features such as automatic screen locking. - -@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 Reference, system-wide packages}). - -@defvr {Scheme Variable} gdm-service-type -This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME -Desktop Manager} (GDM), a program that manages graphical display servers and -handles graphical user logins. Its value must be a @code{gdm-configuration} -(see below.) - -@cindex session types (X11) -@cindex X11 session types -GDM 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. Packages such as @code{gnome}, -@code{xfce}, and @code{i3} 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} gdm-configuration -@table @asis -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (default: @code{#f}) -When @code{auto-login?} is false, GDM presents a log-in screen. - -When @code{auto-login?} is true, GDM logs in directly as -@code{default-user}. - -@item @code{gnome-shell-assets} (default: ...) -List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. - -@item @code{xorg-configuration} (default: @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xsession} (default: @code{(xinitrc)}) -Script to run before starting a X session. - -@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper}) -File name of the @code{dbus-daemon} executable. - -@item @code{gdm} (default: @code{gdm}) -The GDM package to use. -@end table -@end deftp - -@defvr {Scheme Variable} slim-service-type -This is the type for the SLiM graphical login manager for X11. - -Like GDM, SLiM looks for session types described by @file{.desktop} files -and allows users to choose a session from the log-in screen using @kbd{F1}. -It also honors @file{~/.xsession} files. -@end defvr - -@deftp {Data Type} slim-configuration -Data type representing the configuration of @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (default: @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 Note -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{xorg-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg 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-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg graphical 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} (default: @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{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{}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@cindex Xorg, configuration -@deftp {Data Type} xorg-configuration -This data type represents the configuration of the Xorg graphical display -server. Note that there is not Xorg service; instead, the X server is -started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the -configuration of these display managers aggregates an -@code{xorg-configuration} record. - -@table @asis -@item @code{modules} (default: @code{%default-xorg-modules}) -This is a list of @dfn{module packages} loaded by the Xorg server---e.g., -@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. - -@item @code{fonts} (default: @code{%default-xorg-fonts}) -This is a list of font directories to add to the server's @dfn{font path}. - -@item @code{drivers} (default: @code{'()}) -This 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")}. - -@item @code{resolutions} (default: @code{'()}) -When @code{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))}. - -@cindex keyboard layout, for Xorg -@cindex keymap, for Xorg -@item @code{keyboard-layout} (default: @code{#f}) -If this is @code{#f}, Xorg uses the default keyboard layout---usually US -English (``qwerty'') for a 105-key PC keyboard. - -Otherwise this must be a @code{keyboard-layout} object specifying the -keyboard layout in use when Xorg is running. @xref{Keyboard Layout}, for -more information on how to specify the keyboard layout. - -@item @code{extra-config} (default: @code{'()}) -This 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. - -@item @code{server} (default: @code{xorg-server}) -This is the package providing the Xorg server. - -@item @code{server-arguments} (default: @code{%default-xorg-server-arguments}) -This is the list of command-line arguments to pass to the X server. The -default is @code{-nolisten tcp}. -@end table -@end deftp - -@deffn {Scheme Procedure} set-xorg-configuration @var{config} @ - [@var{login-manager-service-type}] Tell the log-in manager (of type -@var{login-manager-service-type}) to use @var{config}, an - record. - -Since the Xorg configuration is embedded in the log-in manager's -configuration---e.g., @code{gdm-configuration}---this procedure provides a -shorthand to set the Xorg configuration. -@end deffn - -@deffn {Scheme Procedure} xorg-start-command [@var{config}] -Return a @code{startx} script in which the modules, fonts, etc. specified in -@var{config}, are available. The result should be used in place of -@code{startx}. - -Usually the X server is started by a login manager. -@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 Printing Services -@subsection Printing Services - -@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 Services -@subsection Desktop Services - -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{gdm-service-type}}), screen lockers, a network management tool -(@pxref{Networking Services, @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{Networking Services}), 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 -Reference, @code{services}}). - -Additionally, the @code{gnome-desktop-service-type}, -@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-type} -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 GDM as 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. - -@defvr {Scheme Variable} gnome-desktop-service-type -This is the type of the service that adds the @uref{https://www.gnome.org, -GNOME} desktop environment. Its value is a -@code{gnome-desktop-configuration} object (see below.) - -This service adds the @code{gnome} package to the system profile, and -extends polkit with the actions from @code{gnome-settings-daemon}. -@end defvr - -@deftp {Data Type} gnome-desktop-configuration -Configuration record for the GNOME desktop environment. - -@table @asis -@item @code{gnome} (default @code{gnome}) -The GNOME package to use. -@end table -@end deftp - -@defvr {Scheme Variable} xfce-desktop-service-type -This is the type of a service to run the @uref{Xfce, https://xfce.org/} -desktop environment. Its value is an @code{xfce-desktop-configuration} -object (see below.) - -This 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 defvr - -@deftp {Data Type} xfce-desktop-configuration -Configuration record for the Xfce desktop environment. - -@table @asis -@item @code{xfce} (default @code{xfce}) -The Xfce package to use. -@end table -@end deftp - -@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} (default @code{enlightenment}) -The enlightenment package to use. -@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* (service gnome-desktop-service-type) - (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 Sound Services -@subsection Sound Services - -@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 {Data Type} alsa-configuration -Data type representing the configuration for @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (default: @var{alsa-plugins}) -@code{alsa-plugins} package to use. - -@item @code{pulseaudio?} (default: @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} (default: @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: -# . -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 Database Services -@subsection Database Services - -@cindex database -@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{} 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 Services -@subsection Mail Services - -@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. . 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 . 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. . -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. . 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. . 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}. -. 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 .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. . 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{" 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 -(' 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{} 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 Monitoring Services -@subsection Monitoring Services - -@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-Expressions}). - -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 -Data type representing the configuration of @command{node_exporter}. - -@table @asis -@item @code{package} (default: @code{go-github-com-prometheus-node-exporter}) -The prometheus-node-exporter package to use. - -@item @code{web-listen-address} (default: @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 Services -@subsection Kerberos Services -@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 LDAP Services -@subsection LDAP Services -@cindex LDAP -@cindex nslcd, LDAP service - -The @code{(gnu services authentication)} module provides the -@code{nslcd-service-type}, which can be used to authenticate against an LDAP -server. In addition to configuring the service itself, you may want to add -@code{ldap} as a name service to the Name Service Switch. @xref{Name Service -Switch} for detailed information. - -Here is a simple operating system declaration with a default configuration -of the @code{nslcd-service-type} and a Name Service Switch configuration -that consults the @code{ldap} name service last: - -@example -(use-service-modules authentication) -(use-modules (gnu system nss)) -... -(operating-system - ... - (services - (cons* - (service nslcd-service-type) - (service dhcp-client-service-type) - %base-services)) - (name-service-switch - (let ((services (list (name-service (name "db")) - (name-service (name "files")) - (name-service (name "ldap"))))) - (name-service-switch - (inherit %mdns-host-lookup-nss) - (password services) - (shadow services) - (group services) - (netgroup services) - (gshadow services))))) -@end example - -@c %start of generated documentation for nslcd-configuration - -Available @code{nslcd-configuration} fields are: - -@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd -The @code{nss-pam-ldapd} package to use. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads -The number of threads to start that can handle requests and perform LDAP -queries. Each thread opens a separate connection to the LDAP server. The -default is to start 5 threads. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string uid -This specifies the user id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string gid -This specifies the group id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} log-option log -This option controls the way logging is done via a list containing SCHEME -and LEVEL. The SCHEME argument may either be the symbols "none" or -"syslog", or an absolute file name. The LEVEL argument is optional and -specifies the log level. The log level may be one of the following symbols: -"crit", "error", "warning", "notice", "info" or "debug". All messages with -the specified log level or higher are logged. - -Defaults to @samp{("/var/log/nslcd" info)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list uri -The list of LDAP server URIs. Normally, only the first server will be used -with the following servers as fall-back. - -Defaults to @samp{("ldap://localhost:389/")}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version -The version of the LDAP protocol to use. The default is to use the maximum -version supported by the LDAP library. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn -Specifies the distinguished name with which to bind to the directory server -for lookups. The default is to bind anonymously. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw -Specifies the credentials with which to bind. This option is only -applicable when used with binddn. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn -Specifies the distinguished name to use when the root user tries to modify a -user's password using the PAM module. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw -Specifies the credentials with which to bind if the root user tries to -change a user's password. This option is only applicable when used with -rootpwmoddn - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech -Specifies the SASL mechanism to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm -Specifies the SASL realm to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid -Specifies the authentication identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid -Specifies the authorization identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? -Determines whether the LDAP server host name should be canonicalised. If -this is enabled the LDAP library will do a reverse host name lookup. By -default, it is left up to the LDAP library whether this check is performed -or not. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname -Set the name for the GSS-API Kerberos credentials cache. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string base -The directory search base. - -Defaults to @samp{"dc=example,dc=com"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} scope-option scope -Specifies the search scope (subtree, onelevel, base or children). The -default scope is subtree; base scope is almost never useful for name service -lookups; children scope is not supported on all servers. - -Defaults to @samp{(subtree)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref -Specifies the policy for dereferencing aliases. The default policy is to -never dereference aliases. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals -Specifies whether automatic referral chasing should be enabled. The default -behaviour is to chase referrals. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps -This option allows for custom attributes to be looked up instead of the -default RFC 2307 attributes. It is a list of maps, each consisting of the -name of a map, the RFC 2307 attribute to match and the query expression for -the attribute as it is available in the directory. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters -A list of filters consisting of the name of a map to which the filter -applies and an LDAP search filter expression. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit -Specifies the time limit in seconds to use when connecting to the directory -server. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit -Specifies the time limit (in seconds) to wait for a response from the LDAP -server. A value of zero, which is the default, is to wait indefinitely for -searches to be completed. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit -Specifies the period if inactivity (in seconds) after which the con‐ nection -to the LDAP server will be closed. The default is not to time out -connections. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime -Specifies the number of seconds to sleep when connecting to all LDAP servers -fails. By default one second is waited between the first failure and the -first retry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime -Specifies the time after which the LDAP server is considered to be -permanently unavailable. Once this time is reached retries will be done -only once per this time period. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl -Specifies whether to use SSL/TLS or not (the default is not to). If -'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert -Specifies what checks to perform on a server-supplied certificate. The -meaning of the values is described in the ldap.conf(5) manual page. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir -Specifies the directory containing X.509 certificates for peer authen‐ -tication. This parameter is ignored when using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile -Specifies the path to the X.509 certificate for peer authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile -Specifies the path to an entropy source. This parameter is ignored when -using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers -Specifies the ciphers to use for TLS as a string. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert -Specifies the path to the file containing the local certificate for client -TLS authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key -Specifies the path to the file containing the private key for client TLS -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize -Set this to a number greater than 0 to request paged results from the LDAP -server in accordance with RFC2696. The default (0) is to not request paged -results. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers -This option prevents group membership lookups through LDAP for the specified -users. Alternatively, the value 'all-local may be used. With that value -nslcd builds a full list of non-LDAP users on startup. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid -This option ensures that LDAP users with a numeric user id lower than the -specified value are ignored. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset -This option specifies an offset that is added to all LDAP numeric user ids. -This can be used to avoid user id collisions with local users. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset -This option specifies an offset that is added to all LDAP numeric group -ids. This can be used to avoid user id collisions with local groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups -If this option is set, the member attribute of a group may point to another -group. Members of nested groups are also returned in the higher level group -and parent groups are returned when finding groups for a specific user. The -default is not to perform extra searches for nested groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers -If this option is set, the group member list is not retrieved when looking -up groups. Lookups for finding which groups a user belongs to will remain -functional so the user will likely still get the correct groups assigned on -login. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration -If this option is set, functions which cause all user/group entries to be -loaded from the directory will not succeed in doing so. This can -dramatically reduce LDAP server load in situations where there are a great -number of users and/or groups. This option is not recommended for most -configurations. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames -This option can be used to specify how user and group names are verified -within the system. This pattern is used to check all user and group names -that are requested and returned from LDAP. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase -This specifies whether or not to perform searches using case-insensitive -matching. Enabling this could open up the system to authorization bypass -vulnerabilities and introduce nscd cache poisoning vulnerabilities which -allow denial of service. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy -This option specifies whether password policy controls are requested and -handled from the LDAP server when performing user authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search -By default nslcd performs an LDAP search with the user's credentials after -BIND (authentication) to ensure that the BIND operation was successful. The -default search is a simple check to see if the user's DN exists. A search -filter can be specified that will be used instead. It should return at -least one entry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search -This option allows flexible fine tuning of the authorisation check that -should be performed. The search filter specified is executed and if any -entries match, access is granted, otherwise access is denied. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message -If this option is set password modification using pam_ldap will be denied -and the specified message will be presented to the user instead. The -message can be used to direct the user to an alternative means of changing -their password. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list pam-services -List of pam service names for which LDAP authentication should suffice. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of generated documentation for nslcd-configuration - - -@node Web Services -@subsection Web Services - -@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 "\ - - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -")))))) -(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{} 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{}. - -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{}. - -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{} -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} (default: @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} (default: @code{varnish}) -The Varnish package to use. - -@item @code{name} (default: @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} (default: @code{"localhost:8080"}) -The backend to use. This option has no effect if @code{vcl} is set. - -@item @code{vcl} (default: #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} (default: @code{'("localhost:80")}) -List of addresses Varnish will listen on. - -@item @code{storage} (default: @code{'("malloc,128m")}) -List of storage backends that will be available in VCL. - -@item @code{parameters} (default: @code{'()}) -List of run-time parameters in the form @code{'(("parameter" . "value"))}. - -@item @code{extra-options} (default: @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{} -@item @code{} -@item @code{} -@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-Expressions}) specifying the hpcguix-web service -configuration. The main items available in this spec are: - -@table @asis -@item @code{title-prefix} (default: @code{"hpcguix | "}) -The page title prefix. - -@item @code{guix-command} (default: @code{"guix"}) -The @command{guix} command. - -@item @code{package-filter-proc} (default: @code{(const #t)}) -A procedure specifying how to filter packages that are displayed. - -@item @code{package-page-extension-proc} (default: @code{(const '())}) -Extension package for @code{hpcguix-web}. - -@item @code{menu} (default: @code{'()}) -Additional entry in page @code{menu}. - -@item @code{channels} (default: @code{%default-channels}) -List of channels from which the package list is built (@pxref{Channels}). - -@item @code{package-list-expiration} (default: @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} (default: @code{hpcguix-web}) -The hpcguix-web package to use. -@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 Note -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 Certificates}, -for more information on X.509 certificates. -@end quotation - -@node Certificate Services -@subsection Certificate Services - -@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 -Services}, 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 Services -@subsection DNS Services -@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 Service - -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{@@}. - -@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 Service - -@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 {Data Type} dnsmasq-configuration -Data type representing the configuration of dnsmasq. - -@table @asis -@item @code{package} (default: @var{dnsmasq}) -Package object of the dnsmasq server. - -@item @code{no-hosts?} (default: @code{#f}) -When true, don't read the hostnames in /etc/hosts. - -@item @code{port} (default: @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?} (default: @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} (default: @code{'()}) -Listen on the given IP addresses. - -@item @code{resolv-file} (default: @code{"/etc/resolv.conf"}) -The file to read the IP address of the upstream nameservers from. - -@item @code{no-resolv?} (default: @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} (default: @code{150}) -Set the size of dnsmasq's cache. Setting the cache size to zero disables -caching. - -@item @code{negative-cache?} (default: @code{#t}) -When false, disable negative caching. - -@end table -@end deftp - -@subsubheading ddclient Service - -@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 -The ddclient package. - -@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 -Mail failed update to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string pid -The ddclient PID file. - -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 Services -@subsection VPN Services -@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 Services}). - -@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 Continuous Integration -@subsection Continuous 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{Substitutes}). - -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} (default: @code{"/var/lib/cuirass/cuirass.db"}) -Location of sqlite database which contains the build results and previously -added specifications. - -@item @code{ttl} (default: @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-Expressions}) 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 Power Management Services -@subsection Power Management Services - -@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 Services -@subsection Audio Services - -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{db-file} (default: @code{"~/.mpd/tag_cache"}) -The location of the music database. - -@item @code{state-file} (default: @code{"~/.mpd/state"}) -The location of the file that stores current MPD's state. - -@item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"}) -The location of the sticker database. - -@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 Virtualization Services -@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 "}. - -@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" "mips64el")))) -@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{Invoking 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 Version Control Services -@subsection Version Control Services - -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{} 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 -Services}, 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 -Services}. -@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{Certificate Services}. 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 Services}. -@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-Expressions, 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 Service - -@cindex Gitolite service -@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 {Data Type} gitolite-configuration -Data type representing the configuration for @code{gitolite-service-type}. - -@table @asis -@item @code{package} (default: @var{gitolite}) -Gitolite package to use. - -@item @code{user} (default: @var{git}) -User to use for Gitolite. This will be user that you use when accessing -Gitolite over SSH. - -@item @code{group} (default: @var{git}) -Group to use for Gitolite. - -@item @code{home-directory} (default: @var{"/var/lib/gitolite"}) -Directory in which to store the Gitolite configuration and repositories. - -@item @code{rc-file} (default: @var{(gitolite-rc-file)}) -A ``file-like'' object (@pxref{G-Expressions, file-like objects}), -representing the configuration for Gitolite. - -@item @code{admin-pubkey} (default: @var{#f}) -A ``file-like'' object (@pxref{G-Expressions, 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 {Data Type} gitolite-rc-file -Data type representing the Gitolite RC file. - -@table @asis -@item @code{umask} (default: @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} (default: @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} (default: @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 Game Services -@subsection Game Services - -@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 Miscellaneous Services -@subsection Miscellaneous Services - -@cindex fingerprint -@subsubheading Fingerprint Service - -The @code{(gnu services authentication)} 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 {Data Type} pcscd-configuration -The data type representing the configuration of @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (default: @code{pcsc-lite}) -The pcsc-lite package that provides pcscd. -@item @code{usb-drivers} (default: @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 - -@cindex inputattach -@subsubheading inputattach Service - -@cindex tablet input, for Xorg -@cindex touchscreen input, for Xorg -The @uref{https://linuxwacom.github.io/, inputattach} service allows you to -use input devices such as Wacom tablets, touchscreens, or joysticks with the -Xorg display server. - -@deffn {Scheme Variable} inputattach-service-type -Type of a service that runs @command{inputattach} on a device and dispatches -events from it. -@end deffn - -@deftp {Data Type} inputattach-configuration -@table @asis -@item @code{device-type} (default: @code{"wacom"}) -The type of device to connect to. Run @command{inputattach --help}, from -the @code{inputattach} package, to see the list of supported device types. - -@item @code{device} (default: @code{"/dev/ttyS0"}) -The device file to connect to the device. - -@item @code{log-file} (default: @code{#f}) -If true, this must be the name of a file to log messages to. -@end table -@end deftp - -@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{} 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{} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{} 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{Modules,,, 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{} 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{} 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 Programs -@section Setuid Programs - -@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{The 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{Using the Configuration System}). For instance, the -@command{passwd} program, which is part of the Shadow package, can be -designated by this G-expression (@pxref{G-Expressions}): - -@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 Certificates -@section X.509 Certificates - -@cindex HTTPS, certificates -@cindex X.509 certificates -@cindex TLS -Web servers available over HTTPS (that is, HTTP over the transport-layer -security mechanism, TLS) send client programs an @dfn{X.509 certificate} -that the client can then use to @emph{authenticate} the server. To do that, -clients verify that the server's certificate is signed by a so-called -@dfn{certificate authority} (CA). But to verify the CA's signature, clients -must have first acquired the CA's certificate. - -Web browsers such as GNU@tie{}IceCat include their own set of CA -certificates, such that they are able to verify CA signatures -out-of-the-box. - -However, most other programs that can talk HTTPS---@command{wget}, -@command{git}, @command{w3m}, etc.---need to be told where CA certificates -can be found. - -@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 Reference}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -Note that it is @emph{not} part of @var{%base-packages}, so you need to -explicitly add it. The @file{/etc/ssl/certs} directory, which is where most -applications and libraries look for certificates by default, points to the -certificates installed globally. - -Unprivileged users, including users of Guix on a foreign distro, can also -install their own certificate package in their profile. A number of -environment variables need to be defined so that applications and libraries -know where to find them. Namely, the OpenSSL library honors the -@code{SSL_CERT_DIR} and @code{SSL_CERT_FILE} variables. Some applications -add their own environment variables; for instance, the Git version control -system honors the certificate bundle pointed to by the @code{GIT_SSL_CAINFO} -environment variable. Thus, you would typically run something like: - -@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 - -As another example, R requires the @code{CURL_CA_BUNDLE} environment -variable to point to a certificate bundle, so you would have to run -something like this: - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -For other applications you may want to look up the required environment -variable in the relevant documentation. - - -@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 -Reference, @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{Networking Services, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@pxref{Base Services, @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{} 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{Base Services, @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 Initial RAM Disk -@section Initial RAM Disk - -@cindex initrd -@cindex initial 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 initial RAM disk -@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ -[#: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{Mapped Devices}). -@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 true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -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 '()] [#:keyboard-layout #f] @ [#: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. - -When true, @var{keyboard-layout} is a @code{} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -@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 Configuration -@section Bootloader Configuration - -@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. - -@cindex keyboard layout, for the bootloader -@item @code{keyboard-layout} (default: @code{#f}) -If this is @code{#f}, the bootloader's menu (if any) uses the default -keyboard layout, usually US@tie{}English (``qwerty''). - -Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard -Layout}). - -@quotation Note -This option is currently ignored by bootloaders other than @code{grub} and -@code{grub-efi}. -@end quotation - -@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-Expressions}). -@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{File Systems}), 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. -For 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 Invoking guix system -@section Invoking @code{guix system} - -Once you have written an operating system declaration as seen in the -previous section, it can be @dfn{instantiated} using the @command{guix -system} command. The synopsis is: - -@example -guix system @var{options}@dots{} @var{action} @var{file} -@end example - -@var{file} must be the name of a file containing an @code{operating-system} -declaration. @var{action} specifies how the operating system is -instantiated. Currently the following values are supported: - -@table @code -@item search -Display available service type definitions that match the given regular -expressions, sorted by relevance: - -@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 - -As for @command{guix package --search}, the result is written in -@code{recutils} format, which makes it easy to filter the output -(@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}). - -This command creates a new generation whose number is one greater than the -current generation (as reported by @command{guix system list-generations}). -If that generation already exists, it will be overwritten. This behavior -mirrors that of @command{guix package} (@pxref{Invoking guix package}). - -It also adds a bootloader menu entry for the new OS configuration, ---unless -@option{--no-bootloader} is passed. For GRUB, it moves entries for older -configurations to a submenu, allowing you to choose an older system -generation at boot time should you need it. - -@quotation Note -@c The paragraph below refers to the problem discussed at -@c . -It is highly recommended to run @command{guix pull} once before you run -@command{guix system reconfigure} for the first time (@pxref{Invoking guix -pull}). Failing to do that you would see an older version of Guix once -@command{reconfigure} has completed. -@end quotation - -@item switch-generation -@cindex generations -Switch to an existing system generation. This action atomically switches -the system profile to the specified system generation. It also rearranges -the system's existing bootloader menu entries. It makes the menu entry for -the specified system generation the default, and it moves the entries for -the other generatiors to a submenu, if supported by the bootloader being -used. The next time the system boots, it will use the specified system -generation. - -The bootloader itself is not being reinstalled when using this command. -Thus, the installed bootloader is used with an updated configuration file. - -The target generation can be specified explicitly by its generation number. -For example, the following invocation would switch to system generation 7: - -@example -guix system switch-generation 7 -@end example - -The target generation can also be specified relative to the current -generation with the form @code{+N} or @code{-N}, where @code{+3} means ``3 -generations ahead of the current generation,'' and @code{-1} means ``1 -generation prior to the current generation.'' When specifying a negative -value such as @code{-1}, you must precede it with @code{--} to prevent it -from being parsed as an option. For example: - -@example -guix system switch-generation -- -1 -@end example - -Currently, the effect of invoking this action is @emph{only} to switch the -system profile to an existing generation and rearrange the bootloader menu -entries. To actually start using the target system generation, you must -reboot after running this action. In the future, it will be updated to do -the same things as @command{reconfigure}, like activating and deactivating -services. - -This action will fail if the specified generation does not exist. - -@item roll-back -@cindex rolling back -Switch to the preceding system generation. The next time the system boots, -it will use the preceding system generation. This is the inverse of -@command{reconfigure}, and it is exactly the same as invoking -@command{switch-generation} with an argument of @code{-1}. - -Currently, as with @command{switch-generation}, you must reboot after -running this action to actually start using the preceding system generation. - -@item delete-generations -@cindex deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Invoking guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Invoking 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 -Build the derivation of the operating system, which includes all the -configuration files and programs needed to boot and run the system. This -action does not actually install anything. - -@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 - -copies to @file{/mnt} all the store items required by the configuration -specified in @file{my-os-config.scm}. This includes configuration files, -packages, and so on. It also creates other essential files needed for the -system to operate correctly---e.g., the @file{/etc}, @file{/var}, and -@file{/run} directories, and the @file{/bin/sh} file. - -This command also installs bootloader on the target specified in -@file{my-os-config}, unless the @option{--no-bootloader} option was passed. - -@item vm -@cindex virtual machine -@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 Note -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{Build Environment Setup}). -@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 - -The VM shares its store with the host system. - -Additional file systems can be shared between the host and the VM using the -@code{--share} and @code{--expose} command-line options: the former -specifies a directory to be shared with write access, while the latter -provides read-only access to the shared directory. - -The example below creates a VM in which the user's home directory is -accessible read-only, and where the @file{/exchange} directory is a -read-write mapping of @file{$HOME/tmp} on the host: - -@example -guix system vm my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -On GNU/Linux, the default is to boot directly to the kernel; this has the -advantage of requiring only a very tiny root disk image since the store of -the host can then be mounted. - -The @code{--full-boot} option forces a complete boot sequence, starting with -the bootloader. This requires more disk space since a root image containing -at least the kernel, initrd, and bootloader data files must be created. The -@code{--image-size} option can be used to specify the size of the image. - -@cindex System images, creation in various formats -@cindex Creating system images in various formats -@item vm-image -@itemx disk-image -@itemx docker-image -Return a virtual machine, disk image, or Docker image of the operating -system declared in @var{file} that stands alone. By default, @command{guix -system} estimates the size of the image needed to store the system, but you -can use the @option{--image-size} option to specify a value. Docker images -are built to contain exactly what they need, so the @option{--image-size} -option is ignored in the case of @code{docker-image}. - -You can specify the root file system type by using the -@option{--file-system-type} option. It defaults to @code{ext4}. - -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. - -When using @code{disk-image}, a raw disk image is produced; it can be copied -as is to a USB stick, for instance. Assuming @code{/dev/sdc} is the device -corresponding to a USB stick, one can copy the image to it using the -following command: - -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example - -When using @code{docker-image}, a Docker image is produced. Guix builds the -image from scratch, not from a pre-existing Docker base image. As a result, -it contains @emph{exactly} what you define in the operating system -configuration file. You can then load the image and launch a Docker -container using commands like the following: - -@example -image_id="$(docker load < guix-system-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 -Return a script to run the operating system declared in @var{file} within a -container. Containers are a set of lightweight isolation mechanisms -provided by the kernel Linux-libre. Containers are substantially less -resource-demanding than full virtual machines since the kernel, shared -objects, and other resources can be shared with the host system; this also -means they provide thinner isolation. - -Currently, the script must be run as root in order to support more than a -single user and group. The container shares its store with the host system. - -As with the @code{vm} action (@pxref{guix system vm}), additional file -systems to be shared between the host and container can be specified using -the @option{--share} and @option{--expose} options: - -@example -guix system container my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -@quotation Note -This option requires Linux-libre 3.19 or newer. -@end quotation - -@end table - -@var{options} can contain any of the common build options (@pxref{Common -Build Options}). In addition, @var{options} can contain one of the -following: - -@table @option -@item --expression=@var{expr} -@itemx -e @var{expr} -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{Building the -Installation Image}). - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system} instead of the host system type. This -works as per @command{guix build} (@pxref{Invoking guix build}). - -@item --derivation -@itemx -d -Return the derivation file name of the given operating system without -building anything. - -@item --file-system-type=@var{type} -@itemx -t @var{type} -For the @code{disk-image} action, create a file system of the given -@var{type} on the image. - -When this option is omitted, @command{guix system} uses @code{ext4}. - -@cindex ISO-9660 format -@cindex CD image format -@cindex DVD image format -@code{--file-system-type=iso9660} produces an ISO-9660 image, suitable for -burning on CDs and DVDs. - -@item --image-size=@var{size} -For the @code{vm-image} and @code{disk-image} actions, create an image of -the given @var{size}. @var{size} may be a number of bytes, or it may -include a unit as a suffix (@pxref{Block size, size specifications,, -coreutils, GNU Coreutils}). - -When this option is omitted, @command{guix system} computes an estimate of -the image size as a function of the size of the system declared in -@var{file}. - -@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 -Skip pre-installation safety checks. - -By default, @command{guix system init} and @command{guix system reconfigure} -perform safety checks: they make sure the file systems that appear in the -@code{operating-system} declaration actually exist (@pxref{File Systems}), -and that any Linux kernel modules that may be needed at boot time are listed -in @code{initrd-modules} (@pxref{Initial RAM Disk}). Passing this option -skips these tests altogether. - -@cindex on-error -@cindex on-error strategy -@cindex error strategy -@item --on-error=@var{strategy} -Apply @var{strategy} when an error occurs when reading @var{file}. -@var{strategy} may be one of the following: - -@table @code -@item nothing-special -Report the error concisely and exit. This is the default strategy. - -@item backtrace -Likewise, but also display a backtrace. - -@item debug -Report the error and enter Guile's debugger. From there, you can run -commands such as @code{,bt} to get a backtrace, @code{,locals} to display -local variable values, and more generally inspect the state of the program. -@xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for a list of -available debugging commands. -@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 -List a summary of each generation of the operating system available on disk, -in a human-readable way. This is similar to the @option{--list-generations} -option of @command{guix package} (@pxref{Invoking guix package}). - -Optionally, one can specify a pattern, with the same syntax that is used in -@command{guix package --list-generations}, to restrict the list of -generations displayed. For instance, the following command displays -generations that are up to 10 days old: - -@example -$ guix system list-generations 10d -@end example - -@end table - -The @command{guix system} command has even more to offer! The following -sub-commands allow you to visualize how your system services relate to each -other: - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Emit in Dot/Graphviz format to standard output the @dfn{service extension -graph} of the operating system defined in @var{file} (@pxref{Service -Composition}, for more information on service extensions.) - -The command: - -@example -$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf -@end example - -produces a PDF file showing the extension relations among services. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Emit in Dot/Graphviz format to standard output the @dfn{dependency graph} of -shepherd services of the operating system defined in @var{file}. -@xref{Shepherd Services}, for more information and for an example graph. - -@end table - -@node Running Guix in a VM -@section Running Guix in a Virtual Machine - -@cindex virtual machine -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/guix-system-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Invoking 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{The -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{Miscellaneous Services, Spice service}. - -@node Defining Services -@section Defining Services - -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 -* Service Composition:: The model for composing services. -* Service Types and Services:: Types and services. -* Service Reference:: API reference. -* Shepherd Services:: A particular type of service. -@end menu - -@node Service Composition -@subsection Service Composition - -@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{Networking Services, -@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 Services, -@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{Base Services}). - -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 Reference}, 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 Service Types and Services -@subsection Service Types and Services - -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{Invoking 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, @code{guix-service-type} extends three services: - -@table @code -@item shepherd-root-service-type -The @code{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd -Services}). - -@item account-service-type -This extension for this service is computed by @code{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Invoking guix-daemon}). - -@item activation-service-type -Here @code{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 - -@code{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 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 -@code{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{} 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{Invoking guix system}). -@end table - -There can be only one instance of an extensible service type such as -@code{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 Reference -@subsection Service Reference - -We have seen an overview of service types (@pxref{Service Types and -Services}). 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{} 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{} 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 @code{%base-services} -(@pxref{Base Services, @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{services} @ - (@var{type} @var{variable} => @var{body}) @dots{} - -Modify the services listed in @var{services} according to the given -clauses. Each clause has the form: - -@example -(@var{type} @var{variable} => @var{body}) -@end example - -where @var{type} is a service type---e.g., @code{guix-service-type}---and -@var{variable} is an identifier that is bound within the @var{body} to the -service parameters---e.g., a @code{guix-configuration} instance---of the -original service of that @var{type}. - -The @var{body} should evaluate to the new service parameters, which will be -used to configure the new service. This new service will replace the -original in the resulting list. Because a service's service parameters are -created using @code{define-record-type*}, you can write a succinct -@var{body} that evaluates to the new service parameters by using the -@code{inherit} feature that @code{define-record-type*} provides. - -@xref{Using the Configuration System}, for example usage. - -@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{Service Types and -Services}). - -@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{} 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{Service Types and Services}, 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{Scheduled Job Execution}) 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{Invoking 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 Programs}). -@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 Services -@subsection Shepherd Services - -@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{Introduction,,, 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{Using the Configuration -System}) 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 @code{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by -passing it lists of @code{} 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. - -@cindex one-shot services, for the Shepherd -@item @code{one-shot?} (default: @code{#f}) -Whether this service is @dfn{one-shot}. One-shot services stop immediately -after their @code{start} action has completed. @xref{Slots of services,,, -shepherd, The GNU Shepherd Manual}, for more info. - -@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-Expressions}). - -@item @code{actions} (default: @code{'()}) -@cindex actions, of Shepherd services -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{documentation} -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 @code{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @code{%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 {Data Type} shepherd-action -This is the data type that defines additional actions implemented by a -Shepherd service (see above). - -@table @code -@item name -Symbol naming the action. - -@item documentation -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{Service Types and Services}, for an example). -Each extension must pass a list of @code{}. -@end defvr - -@defvr {Scheme Variable} %shepherd-root-service -This service represents PID@tie{}1. -@end defvr - - -@node Documentation -@chapter Documentation - -@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 Installing Debugging Files -@chapter Installing Debugging Files - -@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{Packages with Multiple -Outputs}). 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{Invoking 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{Build Systems}). 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{Invoking guix package}). - - -@node Security Updates -@chapter Security Updates - -@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{Invoking guix lint}, for more information. - -@quotation Note -As of version @value{VERSION}, the feature described below is considered -``beta''. -@end quotation - -Guix follows a functional package management discipline -(@pxref{Introduction}), 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{Substitutes}), 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 -@code{bash-fixed}, in the usual way (@pxref{Defining Packages}). 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{Invoking guix gc})---that -is installed is automatically ``rewritten'' to refer to @code{bash-fixed} -instead of @code{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 (@code{bash-fixed} and @code{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{Common Build Options, @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{Invoking 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{Introduction}). 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{Derivations}). -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{Invoking 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{The 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{Derivations}). - -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 . -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{Build Systems, -@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 Porting -@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.zh_CN.texi - -@c ********************************************************************* -@node Acknowledgments -@chapter Acknowledgments - -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 Free Documentation License -@appendix GNU Free Documentation License -@cindex license, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Programming Index -@unnumbered Programming Index -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: -- cgit v1.2.3