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 --- 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 ---------------------------------------- 8 files changed, 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') 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 1.4.1