diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.de.texi | 1008 | ||||
| -rw-r--r-- | doc/contributing.fr.texi | 1005 | ||||
| -rw-r--r-- | doc/contributing.texi | 7 | ||||
| -rw-r--r-- | doc/guix.de.texi | 25126 | ||||
| -rw-r--r-- | doc/guix.fr.texi | 25303 | ||||
| -rw-r--r-- | doc/guix.texi | 979 | ||||
| -rw-r--r-- | doc/local.mk | 22 |
7 files changed, 732 insertions, 52718 deletions
diff --git a/doc/contributing.de.texi b/doc/contributing.de.texi deleted file mode 100644 index 259523aa6f..0000000000 --- a/doc/contributing.de.texi +++ /dev/null @@ -1,1008 +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 (@pxref{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 -(@pxref{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 @xref{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 erstellen. 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 @xref{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 auf @pxref{Der Store}). - -Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen -(@pxref{Die Testsuite laufen lassen}). Falls etwas fehlschlägt, werfen Sie einen -Blick auf die Installationsanweisungen (@pxref{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 (@pxref{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 (@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 - -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} (@pxref{Aufruf von guix pull}). Um -Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen -@command{git pull} benutzen. - - -@node Perfekt eingerichtet -@section Perfekt eingerichtet - -The Perfect Setup to hack on Guix is basically the perfect setup used for -Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference -Manual}). First, you need more than an editor, you need -@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful -@url{http://nongnu.org/geiser/, Geiser}. To set that up, run: - -@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 -(@pxref{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 packages, creating -The GNU distribution is nascent and may well lack some of your favorite -packages. This section describes how you can help make the distribution -grow. - -Free software packages are usually distributed in the form of @dfn{source -code tarballs}---typically @file{tar.gz} files that contain all the source -files. Adding a package to the distribution means essentially two things: -adding a @dfn{recipe} that describes how to build the package, including a -list of other packages required to build it, and adding @dfn{package -metadata} along with that recipe, such as a description and licensing -information. - -In Guix all this information is embodied in @dfn{package definitions}. -Package definitions provide a high-level view of the package. They are -written using the syntax of the Scheme programming language; in fact, for -each package we define a variable bound to the package definition, and -export that variable from a module (@pxref{Paketmodule}). However, -in-depth Scheme knowledge is @emph{not} a prerequisite for creating -packages. For more information on package definitions, @pxref{Pakete definieren}. - -Once a package definition is in place, stored in a file in the Guix source -tree, it can be tested using the @command{guix build} command -(@pxref{Aufruf von guix build}). For example, assuming the new package is -called @code{gnew}, you may run this command from the Guix build tree -(@pxref{Guix vor der Installation ausführen}): - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Using @code{--keep-failed} makes it easier to debug build failures since it -provides access to the failed build tree. Another useful command-line -option when debugging is @code{--log-file}, to access the build log. - -If the package is unknown to the @command{guix} command, it may be that the -source file contains a syntax error, or lacks a @code{define-public} clause -to export the package variable. To figure it out, you may load the module -from Guile to get more information about the actual error: - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Once your package builds correctly, please send us a patch -(@pxref{Einreichen von Patches}). Well, if you need help, we will be happy to -help you too. Once the patch is committed in the Guix repository, the new -package automatically gets built on the supported platforms by -@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration -system}. - -@cindex substituter -Users can obtain the new package definition simply by running @command{guix -pull} (@pxref{Aufruf von guix pull}). When @code{@value{SUBSTITUTE-SERVER}} -is done building the package, installing the package automatically downloads -binaries from there (@pxref{Substitute}). The only place where human -intervention is needed is to review and apply the patch. - - -@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 free software -The GNU operating system has been developed so that users can have freedom -in their computing. GNU is @dfn{free software}, meaning that users have the -@url{http://www.gnu.org/philosophy/free-sw.html,four essential freedoms}: to -run the program, to study and change the program in source code form, to -redistribute exact copies, and to distribute modified versions. Packages -found in the GNU distribution provide only software that conveys these four -freedoms. - -In addition, the GNU distribution follow the -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free -software distribution guidelines}. Among other things, these guidelines -reject non-free firmware, recommendations of non-free software, and discuss -ways to deal with trademarks and patents. - -Some otherwise free upstream package sources contain a small and optional -subset that violates the above guidelines, for instance because this subset -is itself non-free code. When that happens, the offending items are removed -with appropriate patches or code snippets in the @code{origin} form of the -package (@pxref{Pakete definieren}). This way, @code{guix build --source} -returns the ``freed'' source rather than the unmodified upstream source. - - -@node Paketbenennung -@subsection Paketbenennung - -@cindex package name -A package has actually two names associated with it: First, there is the -name of the @emph{Scheme variable}, the one following @code{define-public}. -By this name, the package can be made known in the Scheme code, for instance -as input to another package. Second, there is the string in the @code{name} -field of a package definition. This name is used by package management -commands such as @command{guix package} and @command{guix build}. - -Both are usually the same and correspond to the lowercase conversion of the -project name chosen upstream, with underscores replaced with hyphens. For -instance, GNUnet is available as @code{gnunet}, and SDL_net as -@code{sdl-net}. - -We do not add @code{lib} prefixes for library packages, unless these are -already part of the official project name. But @pxref{Python-Module} and -@ref{Perl-Module} for special rules concerning modules for the Python and -Perl languages. - -Font package names are handled differently, @pxref{Schriftarten}. - - -@node Versionsnummern -@subsection Versionsnummern - -@cindex package version -We usually package only the latest version of a given free software -project. But sometimes, for instance for incompatible library versions, two -(or more) versions of the same package are needed. These require different -Scheme variable names. We use the name as defined in @ref{Paketbenennung} -for the most recent version; previous versions use the same name, suffixed -by @code{-} and the smallest prefix of the version number that may -distinguish the two versions. - -The name inside the package definition is the same for all versions of a -package and does not contain any version number. - -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 <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, -@c for a discussion of what follows. -@cindex version number, for VCS snapshots -Occasionally, we package snapshots of upstream's version control system -(VCS) instead of formal releases. This should remain exceptional, because -it is up to upstream developers to clarify what the stable release is. Yet, -it is sometimes necessary. So, what should we put in the @code{version} -field? - -Clearly, we need to make the commit identifier of the VCS snapshot visible -in the version string, but we also need to make sure that the version string -is monotonically increasing so that @command{guix package --upgrade} can -determine which version is newer. Since commit identifiers, notably with -Git, are not monotonically increasing, we add a revision number that we -increase each time we upgrade to a newer snapshot. The resulting version -string looks like this: - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- upstream commit ID - | | - | `--- Guix package revision - | -latest upstream version -@end example - -It is a good idea to strip commit identifiers in the @code{version} field -to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics -have a role to play here) as well as problems related to OS limits such as -the maximum shebang length (127 bytes for the Linux kernel.) It is best to -use the full commit identifiers in @code{origin}s, though, to avoid -ambiguities. A typical package definition may look like this: - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Guix package 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 Zusammenfassungen und Beschreibungen -@subsection Zusammenfassungen und Beschreibungen - -@cindex package description -@cindex package synopsis -As we have seen before, each package in GNU@tie{}Guix includes a synopsis -and a description (@pxref{Pakete definieren}). Synopses and descriptions -are important: They are what @command{guix package --search} searches, and a -crucial piece of information to help users determine whether a given package -suits their needs. Consequently, packagers should pay attention to what -goes into them. - -Synopses must start with a capital letter and must not end with a period. -They must not start with ``a'' or ``the'', which usually does not bring -anything; for instance, prefer ``File-frobbing tool'' over ``A tool that -frobs files''. The synopsis should say what the package is---e.g., ``Core -GNU utilities (file, text, shell)''---or what it is used for---e.g., the -synopsis for GNU@tie{}grep is ``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-Module -@subsection Python-Module - -@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{Versionsnummern}. 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«-Referenz, -inputs}). Although the @code{pypi} importer normally does a good job -(@pxref{Aufruf von 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{Einreichen von Patches, @command{guix size}}). - -@end itemize - - -@node Perl-Module -@subsection Perl-Module - -@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-Pakete -@subsection Java-Pakete - -@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 Schriftarten -@subsection Schriftarten - -@cindex Schriftarten -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 Code-Stil -@section Code-Stil - -Im Allgemeinen folgt unser Code den GNU Coding Standards (@pxref{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 (@pxref{Development,,, 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 (@pxref{Senden einer Patch-Reihe}). - -Bitte schreiben Sie Commit-Logs im ChangeLog-Format (@pxref{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 kryptographische Signatur 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 @xref{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 -(@pxref{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 -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" "ppc" "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, powerpc, 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=powerpc-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 -Take a look at the profile reported by @command{guix size} (@pxref{Aufruf von 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{Pakete mit mehreren Ausgaben.}), 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 -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 (@pxref{Aufruf von guix refresh}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. -@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 in @code{master} gemerget. 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 (@pxref{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. - -Another option is to use @command{guix challenge} (@pxref{Aufruf von 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 -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} (@pxref{Formatierung von Code}). - -@item -Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL -(@pxref{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 (@pxref{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.fr.texi b/doc/contributing.fr.texi deleted file mode 100644 index 8900c7c704..0000000000 --- a/doc/contributing.fr.texi +++ /dev/null @@ -1,1005 +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 - -The Perfect Setup to hack on Guix is basically the perfect setup used for -Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference -Manual}). First, you need more than an editor, you need -@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful -@url{http://nongnu.org/geiser/, Geiser}. To set that up, run: - -@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 -The GNU distribution is nascent and may well lack some of your favorite -packages. This section describes how you can help make the distribution -grow. - -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 - -Once your package builds correctly, please send us a patch -(@pxref{Envoyer des correctifs}). Well, if you need help, we will be happy to -help you too. Once the patch is committed in the Guix repository, the new -package automatically gets built on the supported platforms by -@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration -system}. - -@cindex substitution -Users can obtain the new package definition simply by running @command{guix -pull} (@pxref{Invoquer guix pull}). When @code{@value{SUBSTITUTE-SERVER}} -is done building the package, installing the package automatically downloads -binaries from there (@pxref{Substituts}). The only place where human -intervention is needed is to review and apply the patch. - - -@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 <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, -@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. - -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 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 de paquet, 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{Development,,, 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 -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" "ppc" "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, powerpc, 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=powerpc-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 -Take a look at the profile reported by @command{guix size} (@pxref{Invoquer 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{Des paquets avec plusieurs résultats}), 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 -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 <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. -@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. - -Another option is to use @command{guix challenge} (@pxref{Invoquer 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 -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.texi b/doc/contributing.texi index 9459c481a7..5331d3e18a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -827,7 +827,7 @@ your @code{operating-system} configuration: @example (service qemu-binfmt-service-type (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc" "mips64el")) + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) (guix-support? #t))) @end example @@ -835,12 +835,11 @@ 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, powerpc, or mips64 architectures, you would run the -following commands, respectively: +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=powerpc-linux --rounds=2 hello guix build --system=mips64el-linux --rounds=2 hello @end example diff --git a/doc/guix.de.texi b/doc/guix.de.texi deleted file mode 100644 index 83dae0d3ec..0000000000 --- a/doc/guix.de.texi +++ /dev/null @@ -1,25126 +0,0 @@ -\input texinfo -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c -*-texinfo-*- - -@c %**start of header -@setfilename guix.de.info -@documentencoding UTF-8 -@documentlanguage de -@frenchspacing on -@settitle Referenzhandbuch zu GNU Guix -@c %**end of header - -@include version-de.texi - -@c Identifier of the OpenPGP key used to sign tarballs and such. -@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 -@set KEY-SERVER pool.sks-keyservers.net - -@c The official substitute server used by default. -@set SUBSTITUTE-SERVER ci.guix.de.info - -@copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 -Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* -Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, -2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* -Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} -2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 -Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo -Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} -2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018 -Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright -@copyright{} 2016, 2017 ng0@* Copyright @copyright{} 2016, 2017, -2018, 2019 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* -Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, -2017, 2018, 2019 Christopher Baines@* Copyright @copyright{} 2017, 2018 -Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* -Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, -2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* -Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 -Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@* -Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017 -Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@* -Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 -Andy Wingo@* Copyright @copyright{} 2017, 2018 Arun Isaac@* Copyright -@copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* -Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike -Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright -@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian -Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} -2018 Alex Vong@* - -Es ist Ihnen gestattet, dieses Dokument zu vervielfältigen, weiterzugeben -und/oder zu verändern, unter den Bedingungen der GNU Free Documentation -License, entweder gemäß Version 1.3 der Lizenz oder (nach Ihrer Option) -einer späteren Version, die von der Free Software Foundation veröffentlicht -wurde, ohne unveränderliche Abschnitte, ohne vorderen Umschlagtext und ohne -hinteren Umschlagtext. Eine Kopie der Lizenz finden Sie im Abschnitt mit dem -Titel »GNU Free Documentation License«. -@end copying - -@dircategory Systemadministration -@direntry -* Guix: (guix.de). Installierte Software und Systemkonfigurationen - verwalten. -* guix package: (guix.de)guix package aufrufen. Pakete installieren, - entfernen und - aktualisieren. -* guix gc: (guix.de)guix gc aufrufen. Unbenutzten Plattenspeicher wieder - freigeben. -* guix pull: (guix.de)guix pull aufrufen. Die Liste verfügbarer Pakete - aktualisieren. -* guix system: (guix.de)guix system aufrufen. Die - Betriebssystemkonfiguration - verwalten. -@end direntry - -@dircategory Softwareentwicklung -@direntry -* guix environment: (guix.de)guix environment aufrufen. Umgebungen für - Entwickler - erstellen -* guix build: (guix.de)guix build aufrufen. Erstellen von Paketen. -* guix pack: (guix.de)guix pack aufrufen. Bündel aus Binärdateien - erstellen. -@end direntry - -@titlepage -@title Referenzhandbuch zu GNU Guix -@subtitle Den funktionalen Paketmanager GNU Guix benutzen -@author Die GNU-Guix-Entwickler - -@page -@vskip 0pt plus 1filll -Edition @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -Dieses Dokument beschreibt GNU Guix, Version @value{VERSION}, ein Werkzeug -zur funktionalen Verwaltung von Softwarepaketen, das für das GNU-System -geschrieben wurde. - -@c TRANSLATORS: You can replace the following paragraph with information on -@c how to join your own translation team and how to report issues with the -@c translation. -Dieses Handbuch ist auch auf Englisch (@pxref{Top,,, guix, GNU Guix -Reference Manual}) und Französisch verfügbar (@pxref{Top,,, guix.fr, Manuel -de référence de GNU Guix}). Wenn Sie es in Ihre eigene Sprache übersetzen -möchten, dann sind Sie beim -@uref{https://translationproject.org/domain/guix-manual.html, Translation -Project} herzlich willkommen. - -@menu -* Einführung:: Was ist Guix überhaupt? -* Installation:: Guix installieren. -* Systeminstallation:: Das ganze Betriebssystem installieren. -* Paketverwaltung:: Pakete installieren, aktualisieren usw. -* Development:: Guix-aided software development. -* Programmierschnittstelle:: Guix in Scheme verwenden. -* Zubehör:: Befehle zur Paketverwaltung. -* Systemkonfiguration:: Das Betriebssystem konfigurieren. -* Dokumentation:: Wie man Nutzerhandbücher von Software liest. -* Dateien zur Fehlersuche installieren:: Womit man seinen Debugger - füttert. -* Sicherheitsaktualisierungen:: Sicherheits-Patches schnell einspielen. -* Bootstrapping:: GNU/Linux von Grund auf selbst erstellen. -* Portierung:: Guix auf andere Plattformen und Kernels - bringen. -* Mitwirken:: Ihre Hilfe ist nötig! - -* Danksagungen:: Danke! -* GNU-Lizenz für freie Dokumentation:: Die Lizenz dieses Handbuchs. -* Konzeptverzeichnis:: Konzepte. -* Programmierverzeichnis:: Datentypen, Funktionen und Variable. - -@detailmenu - --- Detaillierte Liste der Knoten --- - - - -Einführung - - - -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. - -Installation - - - -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Die Testsuite laufen lassen:: Guix testen. -* Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons - einrichtet. -* Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. -* Anwendungen einrichten:: Anwendungsspezifische Einstellungen. - -Den Daemon einrichten - - - -* Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen - vorbereiten. -* Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen - auslagern. -* SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon - einrichtet. - -Systeminstallation - - - -* Einschränkungen:: Was Sie erwarten dürfen. -* Hardware-Überlegungen:: Unterstützte Hardware. -* Installation von USB-Stick oder DVD:: Das Installationsmedium - vorbereiten. -* Vor der Installation:: Netzwerkanbindung, Partitionierung etc. -* Fortfahren mit der Installation:: Die Hauptsache. -* Installing Guix in a VM:: Guix System playground. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. - -Paketverwaltung - - - -* Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird. -* Aufruf von guix package:: Pakete installieren, entfernen usw. -* Substitute:: Vorerstelle Binärdateien herunterladen. -* Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben. -* Aufruf von guix gc:: Den Müllsammler laufen lassen. -* Aufruf von guix pull:: Das neueste Guix samt Distribution laden. -* Kanäle:: Die Paketsammlung anpassen. -* Untergeordnete:: Mit einer anderen Version von Guix - interagieren. -* Aufruf von guix describe:: Informationen über Ihre Guix-Version - anzeigen. -* Aufruf von guix archive:: Import und Export von Store-Dateien. - -Substitute - - - -* Offizieller Substitut-Server:: Eine besondere Quelle von Substituten. -* Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet. -* Substitutauthentifizierung:: Wie Guix Substitute verifiziert. -* Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen. -* Fehler bei der Substitution:: Was passiert, wenn die Substitution - fehlschlägt. -* Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären - Blob trauen? - -Development - - - -* Aufruf von guix environment:: Entwicklungsumgebungen einrichten. -* Aufruf von guix pack:: Software-Bündel erstellen. - -Programmierschnittstelle - - - -* Paketmodule:: Pakete aus Sicht des Programmierers. -* Pakete definieren:: Wie Sie neue Pakete definieren. -* Erstellungssysteme:: Angeben, wie Pakete erstellt werden. -* Der Store:: Den Paket-Store verändern. -* Ableitungen:: Systemnahe Schnittstelle für Paketableitungen. -* Die Store-Monade:: Rein funktionale Schnittstelle zum Store. -* G-Ausdrücke:: Erstellungsausdrücke verarbeiten. -* Aufruf von guix repl:: Interaktiv an Guix herumbasteln. - -Pakete definieren - - - -* »package«-Referenz:: Der Datentyp für Pakete. -* »origin«-Referenz:: Datentyp für Paketursprünge. - -Zubehör - - - -* Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen. -* Aufruf von guix edit:: Paketdefinitionen bearbeiten. -* Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres - Hashes. -* Aufruf von guix hash:: Den kryptographischen Hash einer Datei - berechnen. -* Aufruf von guix import:: Paketdefinitionen importieren. -* Aufruf von guix refresh:: Paketdefinitionen aktualisieren. -* Aufruf von guix lint:: Fehler in Paketdefinitionen finden. -* Aufruf von guix size:: Plattenverbrauch profilieren. -* Aufruf von guix graph:: Den Paketgraphen visualisieren. -* Aufruf von guix publish:: Substitute teilen. -* Aufruf von guix challenge:: Die Substitut-Server anfechten. -* Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen. -* Aufruf von guix container:: Prozesse isolieren. -* Aufruf von guix weather:: Die Verfügbarkeit von Substituten - einschätzen. -* Aufruf von guix processes:: Auflisten der Client-Prozesse - -Aufruf von @command{guix build} - - - -* Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten - Befehle. -* Paketumwandlungsoptionen:: Varianten von Paketen erzeugen. -* Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix - build«. -* Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der - Paketerstellung. - -Systemkonfiguration - - - -* Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen. -* »operating-system«-Referenz:: Details der Betriebssystem-Deklarationen. -* Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. -* Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. -* Benutzerkonten:: Benutzerkonten festlegen. -* Locales:: Sprache und kulturelle Konventionen. -* Dienste:: Systemdienste festlegen. -* Setuid-Programme:: Mit Administratorrechten startende Programme. -* X.509-Zertifikate:: HTTPS-Server authentifizieren. -* Name Service Switch:: Den Name Service Switch von libc konfigurieren. -* Initiale RAM-Disk:: Linux-libre hochfahren. -* Bootloader-Konfiguration:: Den Bootloader konfigurieren. -* Aufruf von guix system:: Instanziierung einer Systemkonfiguration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Dienste definieren:: Neue Dienstdefinitionen hinzufügen. - -Dienste - - - -* Basisdienste:: Essenzielle Systemdienste. -* Geplante Auftragsausführung:: Der mcron-Dienst. -* Log-Rotation:: Der rottlog-Dienst. -* Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc. -* X Window:: Grafische Anzeige. -* Druckdienste:: Unterstützung für lokale und entfernte - Drucker. -* Desktop-Dienste:: D-Bus- und Desktop-Dienste. -* Tondienste:: Dienste für ALSA und Pulseaudio. -* Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc. -* Mail-Dienste:: IMAP, POP3, SMTP und so weiter. -* Kurznachrichtendienste:: Dienste für Kurznachrichten. -* Telefondienste:: Telefoniedienste. -* Überwachungsdienste:: Dienste zur Systemüberwachung. -* Kerberos-Dienste:: Kerberos-Dienste. -* Web-Dienste:: Web-Server. -* Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt. -* DNS-Dienste:: DNS-Daemons. -* VPN-Dienste:: VPN-Daemons. -* Network File System:: Dienste mit Bezug zum Netzwerkdateisystem. -* Kontinuierliche Integration:: Der Cuirass-Dienst. -* Dienste zur Stromverbrauchsverwaltung:: Den Akku schonen. -* Audio-Dienste:: Der MPD. -* Virtualisierungsdienste:: Dienste für virtuelle Maschinen. -* Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten. -* Spieldienste:: Spielserver. -* Verschiedene Dienste:: Andere Dienste. - -Dienste definieren - - - -* Dienstkompositionen:: Wie Dienste zusammengestellt werden. -* Diensttypen und Dienste:: Typen und Dienste. -* Service-Referenz:: Referenz zur Programmierschnittstelle. -* Shepherd-Dienste:: Eine spezielle Art von Dienst. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Einführung -@chapter Einführung - -@cindex Zweck -GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using -the international phonetic alphabet (IPA).} is a package management tool for -and distribution of the GNU system. Guix makes it easy for unprivileged -users to install, upgrade, or remove software packages, to roll back to a -previous package set, to build packages from source, and generally assists -with the creation and maintenance of software environments. - -@cindex Guix System -@cindex GuixSD, now Guix System -@cindex Guix System Distribution, now Guix System -You can install GNU@tie{}Guix on top of an existing GNU/Linux system where -it complements the available tools without interference -(@pxref{Installation}), or you can use it as a standalone operating system -distribution, @dfn{Guix@tie{}System}@footnote{We used to refer to Guix -System as ``Guix System Distribution'' or ``GuixSD''. We now consider it -makes more sense to group everything under the ``Guix'' banner since, after -all, Guix System is readily available through the @command{guix system} -command, even if you're using a different distro underneath!}. @xref{GNU-Distribution}. - -@menu -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. -@end menu - -@node Managing Software the Guix Way -@section Managing Software the Guix Way - -@cindex Benutzeroberflächen -Guix provides a command-line package management interface (@pxref{Paketverwaltung}), tools to help with software development (@pxref{Development}), -command-line utilities for more advanced usage, (@pxref{Zubehör}), as well -as Scheme programming interfaces (@pxref{Programmierschnittstelle}). -@cindex Erstellungs-Daemon -Der @dfn{Erstellungs-Daemon} ist für das Erstellen von Paketen im Auftrag -von Nutzern verantwortlich (@pxref{Den Daemon einrichten}) und für das -Herunterladen vorerstellter Binärdateien aus autorisierten Quellen -(@pxref{Substitute}). - -@cindex Erweiterbarkeit der Distribution -@cindex Anpassung, von Paketen -Guix enthält Paketdefinitionen für viele Pakete, von GNU und nicht von GNU, -die alle @uref{https://www.gnu.org/philosophy/free-sw.html, die Freiheit des -Computernutzers respektieren}. Es ist @emph{erweiterbar}: Nutzer können ihre -eigenen Paketdefinitionen schreiben (@pxref{Pakete definieren}) und sie als -unabhängige Paketmodule verfügbar machen (@pxref{Paketmodule}). Es ist -auch @emph{anpassbar}: Nutzer können spezialisierte Paketdefinitionen aus -bestehenden @emph{ableiten}, auch von der Befehlszeile (@pxref{Paketumwandlungsoptionen}). - -@cindex funktionale Paketverwaltung -@cindex Isolierung -Intern implementiert Guix die Disziplin der @dfn{funktionalen -Paketverwaltung}, zu der Nix schon die Pionierarbeit geleistet hat -(@pxref{Danksagungen}). In Guix wird der Prozess, ein Paket zu erstellen -und zu installieren, als eine @emph{Funktion} im mathematischen Sinn -aufgefasst. Diese Funktion hat Eingaben, wie zum Beispiel -Erstellungs-Skripts, einen Compiler und Bibliotheken, und liefert ein -installiertes Paket. Als eine reine Funktion hängt sein Ergebnis allein von -seinen Eingaben ab — zum Beispiel kann er nicht auf Software oder Skripts -Bezug nehmen, die nicht ausdrücklich als Eingaben übergeben wurden. Eine -Erstellungsfunktion führt immer zum selben Ergebnis, wenn ihr die gleiche -Menge an Eingaben übergeben wurde. Sie kann die Umgebung des laufenden -Systems auf keine Weise beeinflussen, zum Beispiel kann sie keine Dateien -außerhalb ihrer Erstellungs- und Installationsverzeichnisse verändern. Um -dies zu erreichen, laufen Erstellungsprozesse in isolieren Umgebungen -(sogenannte @dfn{Container}), wo nur ausdrückliche Eingaben sichtbar sind. - -@cindex Store -Das Ergebnis von Paketerstellungsfunktionen wird im Dateisystem -@dfn{zwischengespeichert} in einem besonderen Verzeichnis, was als @dfn{der -Store} bezeichnet wird (@pxref{Der Store}). Jedes Paket wird in sein eigenes -Verzeichnis im Store installiert — standardmäßig ist er unter -@file{/gnu/store} zu finden. Der Verzeichnisname enthält einen Hash aller -Eingaben, anhand derer das Paket erzeugt wurde, somit hat das Ändern einer -Eingabe einen völlig anderen Verzeichnisnamen zur Folge. - -Dieses Vorgehen ist die Grundlage für die Guix auszeichnenden -Funktionalitäten: Unterstützung transaktionsbasierter Paketaktualisierungen -und -rückstufungen, Installation von Paketen als einfacher Nutzer sowie -Garbage Collection für Pakete (@pxref{Funktionalitäten}). - - -@node GNU-Distribution -@section GNU-Distribution - -@cindex Guix System -Guix comes with a distribution of the GNU system consisting entirely of free -software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to users of -that software}.}. The distribution can be installed on its own -(@pxref{Systeminstallation}), but it is also possible to install Guix as a -package manager on top of an installed GNU/Linux system -(@pxref{Installation}). When we need to distinguish between the two, we -refer to the standalone distribution as Guix@tie{}System. - -Die Distribution stellt den Kern der GNU-Pakete, also insbesondere GNU libc, -GCC und Binutils, sowie zahlreiche zum GNU-Projekt gehörende und nicht dazu -gehörende Anwendungen zur Verfügung. Die vollständige Liste verfügbarer -Pakete können Sie @url{http://www.gnu.org/software/guix/packages,online} -einsehen, oder indem Sie @command{guix package} ausführen (@pxref{Aufruf von guix package}): - -@example -guix package --list-available -@end example - -Unser Ziel ist, eine zu 100% freie Software-Distribution von Linux-basierten -und von anderen GNU-Varianten anzubieten, mit dem Fokus darauf, das -GNU-Projekt und die enge Zusammenarbeit seiner Bestandteile zu befördern, -sowie die Programme und Werkzeuge hervorzuheben, die die Nutzer dabei -unterstützen, von dieser Freiheit Gebrauch zu machen. - -Pakete sind zur Zeit auf folgenden Plattformen verfügbar: - -@table @code - -@item x86_64-linux -Intel/AMD-@code{x86_64}-Architektur, Linux-Libre als Kernel, - -@item i686-linux -Intel-32-Bit-Architektur (IA-32), Linux-Libre als Kernel, - -@item armhf-linux -ARMv7-A-Architektur mit »hard float«, Thumb-2 und NEON, für die EABI -»hard-float application binary interface«, mit Linux-Libre als Kernel. - -@item aarch64-linux -64-Bit-ARMv8-A-Prozessoren, little-endian, Linux-Libre als Kernel. Derzeit -ist dies noch in der Erprobungsphase mit begrenzter Unterstützung. Unter -@xref{Mitwirken} steht, wie Sie dabei helfen können! - -@item mips64el-linux -64-Bit-MIPS-Prozessoren, little-endian, insbesondere die Loongson-Reihe, -n32-ABI, mit Linux-Libre als Kernel. - -@end table - -With Guix@tie{}System, you @emph{declare} all aspects of the operating -system configuration and Guix takes care of instantiating the configuration -in a transactional, reproducible, and stateless fashion (@pxref{Systemkonfiguration}). Guix System uses the Linux-libre kernel, the Shepherd -initialization system (@pxref{Einführung,,, shepherd, The GNU Shepherd -Manual}), the well-known GNU utilities and tool chain, as well as the -graphical environment or system services of your choice. - -Guix System is available on all the above platforms except -@code{mips64el-linux}. - -@noindent -Informationen, wie auf andere Architekturen oder Kernels portiert werden -kann, finden Sie im Abschnitt @pxref{Portierung}. - -Diese Distribution aufzubauen basiert auf Kooperation, und Sie sind herzlich -eingeladen, dabei mitzumachen! Im Abschnitt @xref{Mitwirken} stehen -weitere Informationen, wie Sie uns helfen können. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex Guix installieren - -@quotation Anmerkung -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script} to install Guix on top of a running GNU/Linux -system, thereafter called a @dfn{foreign distro}.@footnote{This section is -concerned with the installation of the package manager, which can be done on -top of a running GNU/Linux system. If, instead, you want to install the -complete GNU operating system, @pxref{Systeminstallation}.} The script -automates the download, installation, and initial configuration of Guix. It -should be run as the root user. -@end quotation - -@cindex Fremddistribution -@cindex Verzeichnisse auf einer Fremddistribution -When installed on a foreign distro, GNU@tie{}Guix complements the available -tools without interference. Its data lives exclusively in two directories, -usually @file{/gnu/store} and @file{/var/guix}; other files on your system, -such as @file{/etc}, are left untouched. - -Sobald es installiert ist, kann Guix durch Ausführen von @command{guix pull} -aktualisiert werden (@pxref{Aufruf von guix pull}). - -If you prefer to perform the installation steps manually or want to tweak -them, you may find the following subsections useful. They describe the -software requirements of Guix, as well as how to install it manually and get -ready to use it. - -@menu -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Die Testsuite laufen lassen:: Guix testen. -* Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons - einrichtet. -* Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. -* Anwendungen einrichten:: Anwendungsspezifische Einstellungen. -@end menu - -@node Aus Binärdatei installieren -@section Aus Binärdatei installieren - -@cindex Guix aus Binärdateien installieren -@cindex Installations-Skript -Dieser Abschnitt beschreibt, wie sich Guix auf einem beliebigen System aus -einem alle Komponenten umfassenden Tarball installieren lässt, der -Binärdateien für Guix und all seine Abhängigkeiten liefert. Dies geht in der -Regel schneller, als Guix aus seinen Quelldateien zu installieren, was in -den nächsten Abschnitten beschrieben wird. Vorausgesetzt wird hier -lediglich, dass GNU@tie{}tar und Xz verfügbar sind. - -Die Installation läuft so ab: - -@enumerate -@item -@cindex Guix-Binärdatei herunterladen -Laden Sie den binären Tarball von -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{System}.tar.xz} -herunter, wobei @var{System} für @code{x86_64-linux} steht, falls Sie es auf -einer Maschine mit @code{x86_64}-Architektur einrichten, auf der bereits der -Linux-Kernel läuft, oder entsprechend für andere Maschinen. - -@c The following is somewhat duplicated in ``System Installation''. -Achten Sie darauf, auch die zugehörige @file{.sig}-Datei herunterzuladen und -verifizieren Sie damit die Authentizität des Tarballs, ungefähr so: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{System}.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.@var{System}.tar.xz.sig -@end example - -Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen -öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl -importieren: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -und den Befehl @code{gpg --verify} erneut ausführen. - -@item -Nun müssen Sie zum Administratornutzer @code{root} wechseln. Abhängig von -Ihrer Distribution müssen Sie dazu etwa @code{su -} oder @code{sudo -i} -ausführen. Danach führen Sie als @code{root}-Nutzer aus: - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{System}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -Dadurch wird @file{/gnu/store} (@pxref{Der Store}) und @file{/var/guix} -erzeugt. Letzteres enthält ein fertiges Guix-Profil für den -Administratornutzer @code{root} (wie im nächsten Schritt beschrieben). - -Entpacken Sie den Tarball @emph{nicht} auf einem schon funktionierenden -Guix-System, denn es würde seine eigenen essenziellen Dateien überschreiben. - -Die Befehlszeilenoption @code{--warning=no-timestamp} stellt sicher, dass -GNU@tie{}tar nicht vor »unplausibel alten Zeitstempeln« warnt (solche -Warnungen traten bei GNU@tie{}tar 1.26 und älter auf, neue Versionen machen -keine Probleme). Sie treten auf, weil alle Dateien im Archiv als -Änderungszeitpunkt null eingetragen bekommen haben (das bezeichnet den -1. Januar 1970). Das ist Absicht, damit der Inhalt des Archivs nicht davon -abhängt, wann es erstellt wurde, und es somit reproduzierbar wird. - -@item -Machen Sie das Profil als @file{~root/.config/guix/current} verfügbar, wo -@command{guix pull} es aktualisieren kann (@pxref{Aufruf von guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -»Sourcen« Sie @file{etc/profile}, um @code{PATH} und andere relevante -Umgebungsvariable zu ergänzen: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Erzeugen Sie Nutzergruppe und Nutzerkonten für die Erstellungs-Benutzer wie -folgt (@pxref{Einrichten der Erstellungsumgebung}). - -@item -Führen Sie den Daemon aus, und lassen Sie ihn automatisch bei jedem -Hochfahren starten. - -Wenn Ihre Wirts-Distribution systemd als »init«-System verwendet, können Sie -das mit folgenden Befehlen veranlassen: - -@c Versions of systemd that supported symlinked service files are not -@c yet widely deployed, so we should suggest that users copy the service -@c files into place. -@c -@c See this thread for more information: -@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html - -@example -# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ - /etc/systemd/system/ -# systemctl start guix-daemon && systemctl enable guix-daemon -@end example - -Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Andernfalls können Sie den Daemon immer noch manuell starten, mit: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Stellen Sie den @command{guix}-Befehl auch anderen Nutzern Ihrer Maschine -zur Verfügung, zum Beispiel so: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -Es ist auch eine gute Idee, die Info-Version dieses Handbuchs ebenso -verfügbar zu machen: - -@example -# mkdir -p /usr/local/share/info -# cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; - do ln -s $i ; done -@end example - -Auf diese Art wird, unter der Annahme, dass bei Ihnen -@file{/usr/local/share/info} im Suchpfad eingetragen ist, das Ausführen von -@command{info guix} dieses Handbuch öffnen (@pxref{Other Info Directories,,, -texinfo, GNU Texinfo} hat weitere Details, wie Sie den Info-Suchpfad ändern -können). - -@item -@cindex Substitute, deren Autorisierung -To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its -mirrors (@pxref{Substitute}), authorize them: - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@item -Alle Nutzer müssen womöglich ein paar zusätzliche Schritte ausführen, damit -ihre Guix-Umgebung genutzt werden kann, siehe @pxref{Anwendungen einrichten}. -@end enumerate - -Voilà, die Installation ist fertig! - -Sie können nachprüfen, dass Guix funktioniert, indem Sie ein Beispielpaket -in das root-Profil installieren: - -@example -# guix package -i hello -@end example - -Das @code{guix}-Paket muss im Profil von @code{root} installiert bleiben, -damit es nicht vom Müllsammler geholt wird, denn ohne den -@command{guix}-Befehl wären Sie lahmgelegt. Anders gesagt, entfernen Sie -@code{guix} @emph{nicht} mit @code{guix package -r guix}. - -Der Tarball zur Installation aus einer Binärdatei kann einfach durch -Ausführung des folgenden Befehls im Guix-Quellbaum (re-)produziert und -verifiziert werden: - -@example -make guix-binary.@var{System}.tar.xz -@end example - -@noindent -...@: which, in turn, runs: - -@example -guix pack -s @var{System} --localstatedir \ - --profile-name=current-guix guix -@end example - -Siehe @xref{Aufruf von guix pack} für weitere Informationen zu diesem -praktischen Werkzeug. - -@node Voraussetzungen -@section Voraussetzungen - -Dieser Abschnitt listet Voraussetzungen auf, um Guix aus seinem Quellcode zu -erstellen. Der Erstellungsprozess für Guix ist derselbe wie für andere -GNU-Software und wird hier nicht beschrieben. Bitte lesen Sie die Dateien -@file{README} und @file{INSTALL} im Guix-Quellbaum, um weitere Details zu -erfahren. - -@cindex Offizielle Webpräsenz -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. - -GNU Guix hat folgende Pakete als Abhängigkeiten: - -@itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; -@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, Version -0.1.0 oder neuer, -@item -@uref{http://gnutls.org/, GnuTLS}, im Speziellen dessen Bindungen für Guile -(@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, -gnutls-guile, GnuTLS-Guile}), -@item -@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, -Version 0.1.0 oder neuer, -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, vom August 2017 -oder neuer, -@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; -@item @url{http://zlib.net, zlib}, -@item @url{http://www.gnu.org/software/make/, GNU Make}. -@end itemize - -Folgende Abhängigkeiten sind optional: - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Unterstützung für das Auslagern von Erstellungen (@pxref{Auslagern des Daemons einrichten}) und @command{guix copy} (@pxref{Aufruf von guix copy}) hängt von -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, Version -0.10.2 oder neuer, ab. - -@item -Wenn @url{http://www.bzip.org, libbz2} verfügbar ist, kann -@command{guix-daemon} damit Erstellungsprotokolle komprimieren. -@end itemize - -Sofern nicht @code{--disable-daemon} beim Aufruf von @command{configure} -übergeben wurde, benötigen Sie auch folgende Pakete: - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}, -@item @url{http://sqlite.org, SQLite 3}, -@item @url{http://gcc.gnu.org, GCC's g++} mit Unterstützung für den -C++11-Standard. -@end itemize - -@cindex Zustandsverzeichnis -Sollten Sie Guix auf einem System konfigurieren, auf dem Guix bereits -installiert ist, dann stellen Sie sicher, dasselbe Zustandsverzeichnis wie -für die bestehende Installation zu verwenden. Benutzen Sie dazu die -Befehlszeilenoption @code{--localstatedir} des @command{configure}-Skripts -(@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding -Standards}). Das @command{configure}-Skript schützt vor ungewollter -Fehlkonfiguration der @var{localstatedir}, damit sie nicht versehentlich -Ihren Store verfälschen (@pxref{Der Store}). - -@cindex Nix, Kompatibilität -Wenn eine funktionierende Installation of @url{http://nixos.org/nix/, the -Nix package manager} verfügbar ist, können Sie Guix stattdessen mit -@code{--disable-daemon} konfigurieren. In diesem Fall ersetzt Nix die drei -oben genannten Abhängigkeiten. - -Guix ist mit Nix kompatibel, daher ist es möglich, denselben Store für beide -zu verwenden. Dazu müssen Sie an @command{configure} nicht nur denselben -Wert für @code{--with-store-dir} übergeben, sondern auch denselben Wert für -@code{--localstatedir}. Letzterer ist deswegen essenziell, weil er unter -Anderem angibt, wo die Datenbank liegt, in der sich die Metainformationen -über den Store befinden. Für Nix sind die Werte standardmäßig -@code{--with-store-dir=/nix/store} und -@code{--localstatedir=/nix/var}. Beachten Sie, dass @code{--disable-daemon} -nicht erforderlich ist, wenn Sie die Absicht haben, den Store mit Nix zu -teilen. - -@node Die Testsuite laufen lassen -@section Die Testsuite laufen lassen - -@cindex Testkatalog -Nachdem @command{configure} und @code{make} erfolgreich durchgelaufen sind, -ist es ratsam, den Testkatalog auszuführen. Er kann dabei helfen, Probleme -mit der Einrichtung oder Systemumgebung zu finden, oder auch Probleme in -Guix selbst — und Testfehler zu melden ist eine wirklich gute Art und Weise, -bei der Verbesserung von Guix mitzuhelfen. Um den Testkatalog auszuführen, -geben Sie Folgendes ein: - -@example -make check -@end example - -Testfälle können parallel ausgeführt werden. Sie können die -Befehlszeiltenoption @code{-j} von GNU@tie{}make benutzen, damit es -schneller geht. Der erste Durchlauf kann auf neuen Maschinen ein paar -Minuten dauern, nachfolgende Ausführungen werden schneller sein, weil der -für die Tests erstellte Store schon einige Dinge zwischengespeichert haben -wird. - -Es ist auch möglich, eine Teilmenge der Tests laufen zu lassen, indem Sie -die @code{TESTS}-Variable des Makefiles ähnlich wie in diesem Beispiel -definieren: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -Standardmäßig werden Testergebnisse pro Datei angezeigt. Um die Details -jedes einzelnen Testfalls zu sehen, können Sie wie in diesem Beispiel die -@code{SCM_LOG_DRIVER_FLAGS}-Variable des Makefiles definieren: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -Kommt es zum Fehlschlag, senden Sie bitte eine E-Mail an -@email{bug-guix@@gnu.org} und fügen Sie die Datei @file{test-suite.log} als -Anhang bei. Bitte geben Sie dabei in Ihrer Nachricht die benutzte Version -von Guix an sowie die Versionsnummern der Abhängigkeiten -(@pxref{Voraussetzungen}). - -Guix also comes with a whole-system test suite that tests complete Guix -System instances. It can only run on systems where Guix is already -installed, using: - -@example -make check-system -@end example - -@noindent -Oder, auch hier, indem Sie @code{TESTS} definieren, um eine Teilmenge der -auszuführenden Tests anzugeben: - -@example -make check-system TESTS="basic mcron" -@end example - -Diese Systemtests sind in den @code{(gnu tests @dots{})}-Modulen -definiert. Sie funktionieren, indem Sie das getestete Betriebssystem mitsamt -schlichter Instrumentierung in einer virtuellen Maschine (VM) ausführen. Die -Tests können aufwendige Berechnungen durchführen oder sie günstig umgehen, -je nachdem, ob für ihre Abhängigkeiten Substitute zur Verfügung stehen -(@pxref{Substitute}). Manche von ihnen nehmen viel Speicherplatz in -Anspruch, um die VM-Abbilder zu speichern. - -Auch hier gilt: Falls Testfehler auftreten, senden Sie bitte alle Details an -@email{bug-guix@@gnu.org}. - -@node Den Daemon einrichten -@section Den Daemon einrichten - -@cindex Daemon -Operationen wie das Erstellen eines Pakets oder Laufenlassen des -Müllsammlers werden alle durch einen spezialisierten Prozess durchgeführt, -den @dfn{Erstellungs-Daemon}, im Auftrag seiner Kunden (den Clients). Nur -der Daemon darf auf den Store und seine zugehörige Datenbank -zugreifen. Daher wird jede den Store verändernde Operation durch den Daemon -durchgeführt. Zum Beispiel kommunizieren Befehlszeilenwerkzeuge wie -@command{guix package} und @command{guix build} mit dem Daemon (mittels -entfernter Prozeduraufrufe), um ihm Anweisungen zu geben, was er tun soll. - -Folgende Abschnitte beschreiben, wie Sie die Umgebung des -Erstellungs-Daemons ausstatten sollten. Siehe auch @ref{Substitute} für -Informationen darüber, wie Sie es dem Daemon ermöglichen, vorerstellte -Binärdateien herunterzuladen. - -@menu -* Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen - vorbereiten. -* Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen - auslagern. -* SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon - einrichtet. -@end menu - -@node Einrichten der Erstellungsumgebung -@subsection Einrichten der Erstellungsumgebung - -@cindex Erstellungsumgebung -In einem normalen Mehrbenutzersystem werden Guix und sein Daemon — das -Programm @command{guix-daemon} — vom Systemadministrator installiert; -@file{/gnu/store} gehört @code{root} und @command{guix-daemon} läuft als -@code{root}. Nicht mit erweiterten Rechten ausgestattete Nutzer können -Guix-Werkzeuge benutzen, um Pakete zu erstellen oder anderweitig auf den -Store zuzugreifen, und der Daemon wird dies für sie erledigen und dabei -sicherstellen, dass der Store in einem konsistenten Zustand verbleibt und -sich die Nutzer erstellte Pakete teilen. - -@cindex Erstellungsbenutzer -Wenn @command{guix-daemon} als Administratornutzer @code{root} läuft, wollen -Sie aber vielleicht dennoch nicht, dass Paketerstellungsprozesse auch als -@code{root} ablaufen, aus offensichtlichen Sicherheitsgründen. Um dies zu -vermeiden, sollte ein besonderer Pool aus @dfn{Erstellungsbenutzern} -geschaffen werden, damit vom Daemon gestartete Erstellungsprozesse ihn -benutzen. Diese Erstellungsbenutzer müssen weder eine Shell noch ein -Persönliches Verzeichnis zugewiesen bekommen, sie werden lediglich benutzt, -wenn der Daemon @code{root}-Rechte in Erstellungsprozessen ablegt. Mehrere -solche Benutzer zu haben, ermöglicht es dem Daemon, verschiedene -Erstellungsprozessen unter verschiedenen Benutzeridentifikatoren (UIDs) zu -starten, was garantiert, dass sie einander nicht stören — eine essenzielle -Funktionalität, da Erstellungen als reine Funktionen angesehen werden -(@pxref{Einführung}). - -Auf einem GNU/Linux-System kann ein Pool von Erstellungsbenutzern wie folgt -erzeugt werden (mit Bash-Syntax und den Befehlen von @code{shadow}): - -@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html -@c for why `-G' is needed. -@example -# groupadd --system guixbuild -# for i in `seq -w 1 10`; - do - useradd -g guixbuild -G guixbuild \ - -d /var/empty -s `which nologin` \ - -c "Guix-Erstellungsbenutzer $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -Die Anzahl der Erstellungsbenutzer entscheidet, wieviele Erstellungsaufträge -parallel ausgeführt werden können, wie es mit der Befehlszeilenoption -@option{--max-jobs} vorgegeben werden kann (@pxref{Aufruf des guix-daemon, -@option{--max-jobs}}). Um @command{guix system vm} und ähnliche Befehle -nutzen zu können, müssen Sie die Erstellungsbenutzer unter Umständen zur -@code{kvm}-Benutzergruppe hinzufügen, damit sie Zugriff auf @file{/dev/kvm} -haben, mit @code{-G guixbuild,kvm} statt @code{-G guixbuild} -(@pxref{Aufruf von guix system}). - -Das Programm @code{guix-daemon} kann mit dem folgenden Befehl als -@code{root} gestartet werden@footnote{Wenn Ihre Maschine systemd als -»init«-System verwendet, genügt es, die Datei -@file{@var{prefix}/lib/systemd/system/guix-daemon.service} in -@file{/etc/systemd/system} zu platzieren, damit @command{guix-daemon} -automatisch gestartet wird. Ebenso können Sie, wenn Ihre Maschine Upstart -als »init«-System benutzt, die Datei -@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} in @file{/etc/init} -platzieren.}: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -Auf diese Weise startet der Daemon Erstellungsprozesse in einem chroot als -einer der @code{guixbuilder}-Benutzer. Auf GNU/Linux enthält die -chroot-Umgebung standardmäßig nichts außer: - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -einem minimalen @code{/dev}-Verzeichnis, was größtenteils vom @code{/dev} -des Wirtssystems unabhängig erstellt wurde@footnote{»Größtenteils«, denn -obwohl die Menge an Dateien, die im @code{/dev} des chroots vorkommen, fest -ist, können die meisten dieser Dateien nur dann erstellt werden, wenn das -Wirtssystem sie auch hat.}, - -@item -dem @code{/proc}-Verzeichnis, es zeigt nur die Prozesse des Containers, weil -ein separater Namensraum für Prozess-IDs (PIDs) benutzt wird, - -@item -@file{/etc/passwd} mit einem Eintrag für den aktuellen Benutzer und einem -Eintrag für den Benutzer @file{nobody}, - -@item -@file{/etc/group} mit einem Eintrag für die Gruppe des Benutzers, - -@item -@file{/etc/hosts} mit einem Eintrag, der @code{localhost} auf -@code{127.0.0.1} abbildet, - -@item -einem @file{/tmp}-Verzeichnis mit Schreibrechten. -@end itemize - -Sie können beeinflussen, in welchem Verzeichnis der Daemon Erstellungsbäume -unterbringt, indem sie den Wert der Umgebungsvariablen @code{TMPDIR} -ändern. Allerdings heißt innerhalb des chroots der Erstellungsbaum immer -@file{/tmp/guix-build-@var{name}.drv-0}, wobei @var{name} der Ableitungsname -ist — z.B. @code{coreutils-8.24}. Dadurch hat der Wert von @code{TMPDIR} -keinen Einfluss auf die Erstellungsumgebung, wodurch Unterschiede vermieden -werden, falls Erstellungsprozesse den Namen ihres Erstellungsbaumes -einfangen. - -@vindex http_proxy -Der Daemon befolgt außerdem den Wert der Umgebungsvariablen -@code{http_proxy} für von ihm durchgeführte HTTP-Downloads, sei es für -Ableitungen mit fester Ausgabe (@pxref{Ableitungen}) oder für Substitute -(@pxref{Substitute}). - -Wenn Sie Guix als ein Benutzer ohne erweiterte Rechte installieren, ist es -dennoch möglich, @command{guix-daemon} auszuführen, sofern Sie -@code{--disable-chroot} übergeben. Allerdings können Erstellungsprozesse -dann nicht voneinander und vom Rest des Systems isoliert werden. Daher -können sich Erstellungsprozesse gegenseitig stören und auf Programme, -Bibliotheken und andere Dateien zugreifen, die dem restlichen System zur -Verfügung stehen — was es deutlich schwerer macht, sie als @emph{reine} -Funktionen aufzufassen. - - -@node Auslagern des Daemons einrichten -@subsection Nutzung der Auslagerungsfunktionalität - -@cindex auslagern -@cindex Build-Hook -Wenn erwünscht kann der Erstellungs-Daemon Ableitungserstellungen -@dfn{auslagern} auf andere Maschinen, auf denen Guix läuft, mit Hilfe des -@code{offload}-»@dfn{Build-Hooks}«@footnote{Diese Funktionalität ist nur -verfügbar, wenn @uref{https://github.com/artyom-poptsov/guile-ssh, -Guile-SSH} vorhanden ist.}. Wenn diese Funktionalität aktiviert ist, wird -eine nutzerspezifizierte Liste von Erstellungsmaschinen aus -@file{/etc/guix/machines.scm} gelesen. Wann immer eine Erstellung angefragt -wird, zum Beispiel durch @code{guix build}, versucht der Daemon, sie an eine -der Erstellungsmaschinen auszulagern, die die Einschränkungen der Ableitung -erfüllen, insbesondere ihren Systemtyp — z.B. @file{x86_64-linux}. Fehlende -Voraussetzungen für die Erstellung werden über SSH auf die Zielmaschine -kopiert, welche dann mit der Erstellung weitermacht. Hat sie Erfolg damit, -so werden die Ausgabe oder Ausgaben der Erstellung zurück auf die -ursprüngliche Maschine kopiert. - -Die Datei @file{/etc/guix/machines.scm} sieht normalerweise so aus: - -@example -(list (build-machine - (name "eightysix.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "bob") - (speed 2.)) ;unglaublich schnell! - - (build-machine - (name "meeps.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alice") - (private-key - (string-append (getenv "HOME") - "/.ssh/identität-für-guix")))) -@end example - -@noindent -Im obigen Beispiel geben wir eine Liste mit zwei Erstellungsmaschinen vor, -eine für die @code{x86_64}-Architektur und eine für die -@code{mips64el}-Architektur. - -Tatsächlich ist diese Datei — wenig überraschend! — eine Scheme-Datei, die -ausgewertet wird, wenn der @code{offload}-Hook gestartet wird. Der Wert, den -sie zurückliefert, muss eine Liste von @code{build-machine}-Objekten -sein. Obwohl dieses Beispiel eine feste Liste von Erstellungsmaschinen -zeigt, könnte man auch auf die Idee kommen, etwa mit DNS-SD eine Liste -möglicher im lokalen Netzwerk entdeckter Erstellungsmaschinen zu liefern -(@pxref{Einführung, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme -Programs}). Der Datentyp @code{build-machine} wird im Folgenden weiter -ausgeführt. - -@deftp {Datentyp} build-machine -Dieser Datentyp repräsentiert Erstellungsmaschinen, an die der Daemon -Erstellungen auslagern darf. Die wichtigen Felder sind: - -@table @code - -@item name -Der Hostname (d.h. der Rechnername) der entfernten Maschine. - -@item system -Der Systemtyp der entfernten Maschine — z.B. @code{"x86_64-linux"}. - -@item user -Das Benutzerkonto, mit dem eine Verbindung zur entfernten Maschine über SSH -aufgebaut werden soll. Beachten Sie, dass das SSH-Schlüsselpaar @emph{nicht} -durch eine Passphrase geschützt sein darf, damit nicht-interaktive -Anmeldungen möglich sind. - -@item host-key -Dies muss der @dfn{öffentliche SSH-Host-Schlüssel} der Maschine im -OpenSSH-Format sein. Er wird benutzt, um die Identität der Maschine zu -prüfen, wenn wir uns mit ihr verbinden. Er ist eine lange Zeichenkette, die -ungefähr so aussieht: - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org -@end example - -Wenn auf der Maschine der OpenSSH-Daemon, @command{sshd}, läuft, ist der -Host-Schlüssel in einer Datei wie @file{/etc/ssh/ssh_host_ed25519_key.pub} -zu finden. - -Wenn auf der Maschine der SSH-Daemon von GNU@tie{}lsh, nämlich -@command{lshd}, läuft, befindet sich der Host-Schlüssel in -@file{/etc/lsh/host-key.pub} oder einer ähnlichen Datei. Er kann ins -OpenSSH-Format umgewandelt werden durch @command{lsh-export-key} -(@pxref{Converting keys,,, lsh, LSH Manual}): - -@example -$ lsh-export-key --openssh < /etc/lsh/host-key.pub -ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{} -@end example - -@end table - -Eine Reihe optionaler Felder kann festgelegt werden: - -@table @asis - -@item @code{port} (Vorgabe: @code{22}) -Portnummer des SSH-Servers auf der Maschine. - -@item @code{private-key} (Vorgabe: @file{~root/.ssh/id_rsa}) -Die Datei mit dem privaten SSH-Schlüssel, der beim Verbinden zur Maschine -genutzt werden soll, im OpenSSH-Format. Dieser Schlüssel darf nicht mit -einer Passphrase geschützt sein. - -Beachten Sie, dass als Vorgabewert der private Schlüssel @emph{des -root-Benutzers} genommen wird. Vergewissern Sie sich, dass er existiert, -wenn Sie die Standardeinstellung verwenden. - -@item @code{compression} (Vorgabe: @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (Vorgabe: @code{3}) -Die Kompressionsmethoden auf SSH-Ebene und das angefragte -Kompressionsniveau. - -Beachten Sie, dass Auslagerungen SSH-Kompression benötigen, um beim -Übertragen von Dateien an Erstellungsmaschinen und zurück weniger Bandbreite -zu benutzen. - -@item @code{daemon-socket} (Vorgabe: @code{"/var/guix/daemon-socket/socket"}) -Dateiname des Unix-Sockets, auf dem @command{guix-daemon} auf der Maschine -lauscht. - -@item @code{parallel-builds} (Vorgabe: @code{1}) -Die Anzahl der Erstellungen, die auf der Maschine parallel ausgeführt werden -können. - -@item @code{speed} (Vorgabe: @code{1.0}) -Ein »relativer Geschwindigkeitsfaktor«. Der Auslagerungsplaner gibt -tendenziell Maschinen mit höherem Geschwindigkeitsfaktor den Vorrang. - -@item @code{features} (Vorgabe: @code{'()}) -Eine Liste von Zeichenketten, die besondere von der Maschine unterstützte -Funktionalitäten bezeichnen. Ein Beispiel ist @code{"kvm"} für Maschinen, -die über die KVM-Linux-Module zusammen mit entsprechender -Hardware-Unterstützung verfügen. Ableitungen können Funktionalitäten dem -Namen nach anfragen und werden dann auf passenden Erstellungsmaschinen -eingeplant. - -@end table -@end deftp - -The @command{guix} command must be in the search path on the build -machines. You can check whether this is the case by running: - -@example -ssh build-machine guix repl --version -@end example - -Es gibt noch eine weitere Sache zu tun, sobald @file{machines.scm} -eingerichtet ist. Wie zuvor erklärt, werden beim Auslagern Dateien zwischen -den Stores der Maschinen hin- und hergeschickt. Damit das funktioniert, -müssen Sie als Erstes ein Schlüsselpaar auf jeder Maschine erzeugen, damit -der Daemon signierte Archive mit den Dateien aus dem Store versenden kann -(@pxref{Aufruf von guix archive}): - -@example -# guix archive --generate-key -@end example - -@noindent -Jede Erstellungsmaschine muss den Schlüssel der Hauptmaschine autorisieren, -damit diese Store-Objekte von der Hauptmaschine empfangen kann: - -@example -# guix archive --authorize < öffentlicher-schlüssel-hauptmaschine.txt -@end example - -@noindent -Andersherum muss auch die Hauptmaschine den jeweiligen Schlüssel jeder -Erstellungsmaschine autorisieren. - -Der ganze Umstand mit den Schlüsseln soll ausdrücken, dass sich Haupt- und -Erstellungsmaschinen paarweise gegenseitig vertrauen. Konkret kann der -Erstellungs-Daemon auf der Hauptmaschine die Echtheit von den -Erstellungsmaschinen empfangener Dateien gewährleisten (und umgekehrt), und -auch dass sie nicht sabotiert wurden und mit einem autorisierten Schlüssel -signiert wurden. - -@cindex Auslagerung testen -Um zu testen, ob Ihr System funktioniert, führen Sie diesen Befehl auf der -Hauptmaschine aus: - -@example -# guix offload test -@end example - -Dadurch wird versucht, zu jeder Erstellungsmaschine eine Verbindung -herzustellen, die in @file{/etc/guix/machines.scm} angegeben wurde, -sichergestellt, dass auf jeder Guile und die Guix-Module nutzbar sind, und -jeweils versucht, etwas auf die Erstellungsmaschine zu exportieren und von -dort zu imporieren. Dabei auftretende Fehler werden gemeldet. - -Wenn Sie stattdessen eine andere Maschinendatei verwenden möchten, geben Sie -diese einfach auf der Befehlszeile an: - -@example -# guix offload test maschinen-qualif.scm -@end example - -Letztendlich können Sie hiermit nur die Teilmenge der Maschinen testen, -deren Name zu einem regulären Ausdruck passt: - -@example -# guix offload test maschinen.scm '\.gnu\.org$' -@end example - -@cindex Auslagerungs-Lagebericht -Um die momentane Auslastung aller Erstellungs-Hosts anzuzeigen, führen Sie -diesen Befehl auf dem Hauptknoten aus: - -@example -# guix offload status -@end example - - -@node SELinux-Unterstützung -@subsection SELinux-Unterstützung - -@cindex SELinux, Policy für den Daemon -@cindex Mandatory Access Control, SELinux -@cindex Sicherheit, des guix-daemon -Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that can -be installed on a system where SELinux is enabled, in order to label Guix -files and to specify the expected behavior of the daemon. Since Guix System -does not provide an SELinux base policy, the daemon policy cannot be used on -Guix System. - -@subsubsection Installieren der SELinux-Policy -@cindex SELinux, Policy installieren -Um die Richtlinie (Policy) zu installieren, führen Sie folgenden Befehl mit -Administratorrechten aus: - -@example -semodule -i etc/guix-daemon.cil -@end example - -Kennzeichnen Sie dann das Dateisystem neu mit @code{restorecon} oder einem -anderen, von Ihrem System angebotenen Mechanismus. - -Sobald die Richtlinie installiert ist, das Dateisystem neu gekennzeichnet -wurde und der Daemon neugestartet wurde, sollte er im Kontext -@code{guix_daemon_t} laufen. Sie können dies mit dem folgenden Befehl -nachprüfen: - -@example -ps -Zax | grep guix-daemon -@end example - -Beobachten Sie die Protokolldateien von SELinux, wenn Sie einen Befehl wie -@code{guix build hello} ausführen, um sich zu überzeugen, dass SELinux alle -notwendigen Operationen gestattet. - -@subsubsection Einschränkungen -@cindex SELinux, Einschränkungen - -Diese Richtlinie ist nicht perfekt. Im Folgenden finden Sie eine Liste von -Einschränkungen oder merkwürdigen Verhaltensweisen, die bedacht werden -sollten, wenn man die mitgelieferte SELinux-Richtlinie für den Guix-Daemon -einspielt. - -@enumerate -@item -@code{guix_daemon_socket_t} wird nicht wirklich benutzt. Keine der -Socket-Operationen benutzt Kontexte, die irgendetwas mit -@code{guix_daemon_socket_t} zu tun haben. Es schadet nicht, diese ungenutzte -Kennzeichnung zu haben, aber es wäre besser, für die Kennzeichnung auch -Socket-Regeln festzulegen. - -@item -@code{guix gc} kann nicht auf beliebige Verknüpfungen zu Profilen -zugreifen. Die Kennzeichnung des Ziels einer symbolischen Verknüpfung ist -notwendigerweise unabhängig von der Dateikennzeichnung der -Verknüpfung. Obwohl alle Profile unter $localstatedir gekennzeichnet sind, -erben die Verknüpfungen auf diese Profile die Kennzeichnung desjenigen -Verzeichnisses, in dem sie sich befinden. Für Verknüpfungen im Persönlichen -Verzeichnis des Benutzers ist das @code{user_home_t}, aber Verknüpfungen aus -dem Persönlichen Verzeichnis des Administratornutzers, oder @file{/tmp}, -oder das Arbeitsverzeichnis des HTTP-Servers, etc., funktioniert das -nicht. @code{guix gc} würde es nicht gestattet, diese Verknüpfungen -auszulesen oder zu verfolgen. - -@item -Die vom Daemon gebotene Funktionalität, auf TCP-Verbindungen zu lauschen, -könnte nicht mehr funktionieren. Dies könnte zusätzliche Regeln brauchen, -weil SELinux Netzwerk-Sockets anders behandelt als Dateien. - -@item -Derzeit wird allen Dateien mit einem Namen, der zum regulären Ausdruck -@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} passt, die -Kennzeichnung @code{guix_daemon_exec_t} zugewiesen, wodurch @emph{jede -beliebige} Datei mit diesem Namen in irgendeinem Profil gestattet wäre, in -der Domäne @code{guix_daemon_t} ausgeführt zu werden. Das ist nicht -ideal. Ein Angreifer könnte ein Paket erstellen, dass solch eine ausführbare -Datei enthält, und den Nutzer überzeugen, es zu installieren und -auszuführen. Dadurch käme es in die Domäne @code{guix_daemon_t}. Ab diesem -Punkt könnte SELinux nicht mehr verhindern, dass es auf Dateien zugreift, -auf die Prozesse in dieser Domäne zugreifen dürfen. - -Wir könnten zum Zeitpunkt der Installation eine wesentlich restriktivere -Richtlinie generieren, für die nur @emph{genau derselbe} Dateiname des -gerade installierten @code{guix-daemon}-Programms als -@code{guix_daemon_exec_t} gekennzeichnet würde, statt einen vieles -umfassenden regulären Ausdruck zu benutzen. Aber dann müsste der -Administratornutzer zum Zeitpunkt der Installation jedes Mal die Richtlinie -installieren oder aktualisieren müssen, sobald das Guix-Paket aktualisiert -wird, dass das tatsächlich in Benutzung befindliche -@code{guix-daemon}-Programm enthält. -@end enumerate - -@node Aufruf des guix-daemon -@section Aufruf von @command{guix-daemon} - -Das Programm @command{guix-daemon} implementiert alle Funktionalitäten, um -auf den Store zuzugreifen. Dazu gehört das Starten von Erstellungsprozessen, -das Ausführen des Müllsammlers, das Abfragen, ob ein Erstellungsergebnis -verfügbar ist, etc. Normalerweise wird er so als Administratornutzer -(@code{root}) gestartet: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -Details, wie Sie ihn einrichten, finden Sie im Abschnitt @pxref{Den Daemon einrichten}. - -@cindex chroot -@cindex Container, Erstellungsumgebung -@cindex Erstellungsumgebung -@cindex Reproduzierbare Erstellungen -Standardmäßig führt @command{guix-daemon} Erstellungsprozesse mit -unterschiedlichen UIDs aus, die aus der Erstellungsgruppe stammen, deren -Name mit @code{--build-users-group} übergeben wurde. Außerdem läuft jeder -Erstellungsprozess in einer chroot-Umgebung, die nur die Teilmenge des -Stores enthält, von der der Erstellungsprozess abhängt, entsprechend seiner -Ableitung (@pxref{Programmierschnittstelle, derivation}), und ein paar -bestimmte Systemverzeichnisse, darunter standardmäßig auch @file{/dev} und -@file{/dev/pts}. Zudem ist die Erstellungsumgebung auf GNU/Linux ein -@dfn{Container}: Nicht nur hat er seinen eigenen Dateisystembaum, er hat -auch einen separaten Namensraum zum Einhängen von Dateisystemen, seinen -eigenen Namensraum für PIDs, für Netzwerke, etc. Dies hilft dabei, -reproduzierbare Erstellungen zu garantieren (@pxref{Funktionalitäten}). - -Wenn der Daemon im Auftrag des Nutzers eine Erstellung durchführt, erzeugt -er ein Erstellungsverzeichnis, entweder in @file{/tmp} oder im Verzeichnis, -das durch die Umgebungsvariable @code{TMPDIR} angegeben wurde. Dieses -Verzeichnis wird mit dem Container geteilt, solange die Erstellung noch -läuft, allerdings trägt es im Container stattdessen immer den Namen -»/tmp/guix-build-NAME.drv-0«. - -Nach Abschluss der Erstellung wird das Erstellungsverzeichnis automatisch -entfernt, außer wenn die Erstellung fehlgeschlagen ist und der Client -@option{--keep-failed} angegeben hat (@pxref{Aufruf von guix build, -@option{--keep-failed}}). - -Der Daemon lauscht auf Verbindungen und erstellt jeweils einen Unterprozess -für jede von einem Client begonnene Sitzung (d.h. von einem der -@command{guix}-Unterbefehle.) Der Befehl @command{guix processes} zeigt -Ihnen eine Übersicht solcher Systemaktivitäten; damit werden Ihnen alle -aktiven Sitzungen und Clients gezeigt. Weitere Informationen finden Sie -unter @xref{Aufruf von guix processes}. - -Die folgenden Befehlszeilenoptionen werden unterstützt: - -@table @code -@item --build-users-group=@var{Gruppe} -Verwende die Benutzerkonten aus der @var{Gruppe}, um Erstellungsprozesse -auszuführen (@pxref{Den Daemon einrichten, build users}). - -@item --no-substitutes -@cindex Substitute -Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle -Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab -erstellten Binärdateien erlaubt ist (@pxref{Substitute}). - -Wenn der Daemon mit @code{--no-substitutes} ausgeführt wird, können Clients -trotzdem Substitute explizit aktivieren über den entfernten Prozeduraufruf -@code{set-build-options} (@pxref{Der Store}). - -@item --substitute-urls=@var{URLs} -@anchor{daemon-substitute-urls} -Consider @var{urls} the default whitespace-separated list of substitute -source URLs. When this option is omitted, -@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used. - -Das hat zur Folge, dass Substitute von den @var{URLs} heruntergeladen werden -können, solange sie mit einer Signatur versehen sind, der vertraut wird -(@pxref{Substitute}). - -@cindex Build-Hook -@item --no-build-hook -Den »@dfn{Build-Hook}« nicht benutzen. - -»Build-Hook« ist der Name eines Hilfsprogramms, das der Daemon starten kann -und an das er Erstellungsanfragen übermittelt. Durch diesen Mechanismus -können Erstellungen an andere Maschinen ausgelagert werden (@pxref{Auslagern des Daemons einrichten}). - -@item --cache-failures -Fehler bei der Erstellung zwischenspeichern. Normalerweise werden nur -erfolgreiche Erstellungen gespeichert. - -Wenn diese Befehlszeilenoption benutzt wird, kann @command{guix gc ---list-failures} benutzt werden, um die Menge an Store-Objekten abzufragen, -die als Fehlschläge markiert sind; @command{guix gc --clear-failures} -entfernt Store-Objekte aus der Menge zwischengespeicherter -Fehlschläge. @xref{Aufruf von guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -@var{n} CPU-Kerne zum Erstellen jeder Ableitung benutzen; @code{0} heißt, so -viele wie verfügbar sind. - -Der Vorgabewert ist @code{0}, jeder Client kann jedoch eine abweichende -Anzahl vorgeben, zum Beispiel mit der Befehlszeilenoption @code{--cores} von -@command{guix build} (@pxref{Aufruf von guix build}). - -Dadurch wird die Umgebungsvariable @code{NIX_BUILD_CORES} im -Erstellungsprozess definiert, welcher sie benutzen kann, um intern parallele -Ausführungen zuzulassen — zum Beispiel durch Nutzung von @code{make --j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Höchstenss @var{n} Erstellungsaufträge parallel bearbeiten. Der Vorgabewert -liegt bei @code{1}. Wird er auf @code{0} gesetzt, werden keine Erstellungen -lokal durchgeführt, stattdessen lagert der Daemon sie nur aus (@pxref{Auslagern des Daemons einrichten}) oder sie schlagen einfach fehl. - -@item --max-silent-time=@var{Sekunden} -Wenn der Erstellungs- oder Substitutionsprozess länger als -@var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein -Fehler beim Erstellen gemeldet. - -Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung -gibt. - -Clients können einen anderen Wert als den hier angegebenen verwenden lassen -(@pxref{Gemeinsame Erstellungsoptionen, @code{--max-silent-time}}). - -@item --timeout=@var{Sekunden} -Entsprechend wird hier der Erstellungs- oder Substitutionsprozess -abgebrochen und als Fehlschlag gemeldet, wenn er mehr als -@var{Sekunden}-lang dauert. - -Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung -gibt. - -Clients können einen anderen Wert verwenden lassen (@pxref{Gemeinsame Erstellungsoptionen, @code{--timeout}}). - -@item --rounds=@var{N} -Jede Ableitung @var{n}-mal hintereinander erstellen und einen Fehler melden, -wenn nacheinander ausgewertete Erstellungsergebnisse nicht Bit für Bit -identisch sind. Beachten Sie, dass Clients wie @command{guix build} einen -anderen Wert verwenden lassen können (@pxref{Aufruf von guix build}). - -Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich -unterscheidenden Ausgaben im Store unter dem Namen -@file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den -beiden Ergebnissen leicht erkannt werden. - -@item --debug -Informationen zur Fehlersuche ausgeben. - -Dies ist nützlich, um Probleme beim Starten des Daemons nachzuvollziehen; -Clients könn aber auch ein abweichenden Wert verwenden lassen, zum Beispiel -mit der Befehlszeilenoption @code{--verbosity} von @command{guix build} -(@pxref{Aufruf von guix build}). - -@item --chroot-directory=@var{Verzeichnis} -Füge das @var{Verzeichnis} zum chroot von Erstellungen hinzu. - -Dadurch kann sich das Ergebnis von Erstellungsprozessen ändern — zum -Beispiel, wenn diese optionale Abhängigkeiten aus dem @var{Verzeichnis} -verwenden, wenn sie verfügbar sind, und nicht, wenn es fehlt. Deshalb ist es -nicht empfohlen, dass Sie diese Befehlszeilenoption verwenden, besser -sollten Sie dafür sorgen, dass jede Ableitung alle von ihr benötigten -Eingabgen deklariert. - -@item --disable-chroot -Erstellungen ohne chroot durchführen. - -Diese Befehlszeilenoption zu benutzen, wird nicht empfohlen, denn auch -dadurch bekämen Erstellungsprozesse Zugriff auf nicht deklarierte -Abhängigkeiten. Sie ist allerdings unvermeidlich, wenn @command{guix-daemon} -auf einem Benutzerkonto ohne ausreichende Berechtigungen ausgeführt wird. - -@item --log-compression=@var{Typ} -Erstellungsprotokolle werden entsprechend dem @var{Typ} komprimiert, der -entweder @code{gzip}, @code{bzip2} oder @code{none} (für keine Kompression) -sein muss. - -Sofern nicht @code{--lose-logs} angegeben wurde, werden alle -Erstellungsprotokolle in der @var{localstatedir} gespeichert. Um Platz zu -sparen, komprimiert sie der Daemon standardmäßig automatisch mit bzip2. - -@item --disable-deduplication -@cindex Deduplizieren -Automatische Dateien-»Deduplizierung« im Store ausschalten. - -Standardmäßig werden zum Store hinzugefügte Objekte automatisch -»dedupliziert«: Wenn eine neue Datei mit einer anderen im Store -übereinstimmt, wird die neue Datei stattdessen als harte Verknüpfung auf die -andere Datei angelegt. Dies reduziert den Speicherverbrauch auf der Platte -merklich, jedoch steigt andererseits die Auslastung bei der Ein-/Ausgabe im -Erstellungsprozess geringfügig. Durch diese Option wird keine solche -Optimierung durchgeführt. - -@item --gc-keep-outputs[=yes|no] -Gibt an, ob der Müllsammler (Garbage Collector, GC) die Ausgaben lebendiger -Ableitungen behalten muss (»yes«) oder nicht (»no«). - -@cindex GC-Wurzeln -@cindex Müllsammlerwurzeln -Für »yes« behält der Müllsammler die Ausgaben aller lebendigen Ableitungen -im Store — die @code{.drv}-Dateien. Der Vorgabewert ist aber »no«, so dass -Ableitungsausgaben nur vorgehalten werden, wenn sie von einer -Müllsammlerwurzel aus erreichbar sind. Siehe den Abschnitt @xref{Aufruf von guix gc} für weitere Informationen zu Müllsammlerwurzeln. - -@item --gc-keep-derivations[=yes|no] -Gibt an, ob der Müllsammler (GC) Ableitungen behalten muss (»yes«), wenn sie -lebendige Ausgaben haben, oder nicht (»no«). - -Für »yes«, den Vorgabewert, behält der Müllsammler Ableitungen — -z.B. @code{.drv}-Dateien —, solange zumindest eine ihrer Ausgaben lebendig -ist. Dadurch können Nutzer den Ursprung der Dateien in ihrem Store -nachvollziehen. Setzt man den Wert auf »no«, wird ein bisschen weniger -Speicher auf der Platte verbraucht. - -Auf diese Weise überträgt sich, wenn @code{--gc-keep-derivations} auf »yes« -steht, die Lebendigkeit von Ausgaben auf Ableitungen, und wenn -@code{--gc-keep-outputs} auf »yes« steht, die Lebendigkeit von Ableitungen -auf Ausgaben. Stehen beide auf »yes«, bleiben so alle -Erstellungsvoraussetzungen wie Quelldateien, Compiler, Bibliotheken und -andere Erstellungswerkzeuge lebendiger Objekte im Store erhalten, ob sie von -einer Müllsammlerwurzel aus erreichbar sind oder nicht. Entwickler können -sich so erneute Erstellungen oder erneutes Herunterladen sparen. - -@item --impersonate-linux-2.6 -Auf Linux-basierten Systemen wird hiermit vorgetäuscht, dass es sich um -Linux 2.6 handeln würde, indem der Kernel für einen -@code{uname}-Systemaufruf als Version der Veröffentlichung mit 2.6 -antwortet. - -Dies kann hilfreich sein, um Programme zu erstellen, die (normalerweise zu -Unrecht) von der Kernel-Versionsnummer abhängen. - -@item --lose-logs -Keine Protokolle der Erstellungen vorhalten. Normalerweise würden solche in -@code{@var{localstatedir}/guix/log} gespeichert. - -@item --system=@var{System} -Verwende @var{System} als aktuellen Systemtyp. Standardmäßig ist dies das -Paar aus Befehlssatz und Kernel, welches beim Aufruf von @code{configure} -erkannt wurde, wie zum Beispiel @code{x86_64-linux}. - -@item --listen=@var{Endpunkt} -Lausche am @var{Endpunkt} auf Verbindungen. Dabei wird der @var{Endpunkt} -als Dateiname eines Unix-Sockets verstanden, wenn er mit einem @code{/} -(Schrägstrich) beginnt. Andernfalls wird der @var{Endpunkt} als Hostname -(d.h. Rechnername) oder als Hostname-Port-Paar verstanden, auf dem gelauscht -wird. Hier sind ein paar Beispiele: - -@table @code -@item --listen=/gnu/var/daemon -Lausche auf Verbindungen am Unix-Socket @file{/gnu/var/daemon}, falls nötig -wird er dazu erstellt. - -@item --listen=localhost -@cindex Daemon, Fernzugriff -@cindex Fernzugriff auf den Daemon -@cindex Daemon, Einrichten auf Clustern -@cindex Cluster, Einrichtung des Daemons -Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die -@code{localhost} entspricht, auf Port 44146. - -@item --listen=128.0.0.42:1234 -Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die -@code{128.0.0.42} entspricht, auf Port 1234. -@end table - -Diese Befehlszeilenoption kann mehrmals wiederholt werden. In diesem Fall -akzeptiert @command{guix-daemon} Verbindungen auf allen angegebenen -Endpunkten. Benutzer können bei Client-Befehlen angeben, mit welchem -Endpunkt sie sich verbinden möchten, indem sie die Umgebungsvariable -@code{GUIX_DAEMON_SOCKET} festlegen (@pxref{Der Store, -@code{GUIX_DAEMON_SOCKET}}). - -@quotation Anmerkung -Das Daemon-Protokoll ist @emph{weder authentifiziert noch -verschlüsselt}. Die Benutzung von @code{--listen=@var{Host}} eignet sich für -lokale Netzwerke, wie z.B. in Rechen-Clustern, wo sich nur solche Knoten mit -dem Daemon verbinden, denen man vertraut. In Situationen, wo ein Fernzugriff -auf den Daemon durchgeführt wird, empfehlen wir, über Unix-Sockets in -Verbindung mit SSH zuzugreifen. -@end quotation - -Wird @code{--listen} nicht angegeben, lauscht @command{guix-daemon} auf -Verbindungen auf dem Unix-Socket, der sich unter -@file{@var{localstatedir}/guix/daemon-socket/socket} befindet. -@end table - - -@node Anwendungen einrichten -@section Anwendungen einrichten - -@cindex Fremddistribution -When using Guix on top of GNU/Linux distribution other than Guix System---a -so-called @dfn{foreign distro}---a few additional steps are needed to get -everything in place. Here are some of them. - -@subsection Locales - -@anchor{locales-and-locpath} -@cindex locales, when not on Guix System -@vindex LOCPATH -@vindex GUIX_LOCPATH -Über Guix installierte Pakete benutzen nicht die Daten zu Regions- und -Spracheinstellungen (Locales) des Wirtssystems. Stattdessen müssen Sie erst -eines der Locale-Pakete installieren, die für Guix verfügbar sind, und dann -den Wert Ihrer Umgebungsvariablen @code{GUIX_LOCPATH} passend festlegen: - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Beachten Sie, dass das Paket @code{glibc-locales} Daten für alle von -GNU@tie{}libc unterstützten Locales enthält und deswegen um die 110@tie{}MiB -wiegt. Alternativ gibt es auch @code{glibc-utf8-locales}, was kleiner, aber -auf ein paar UTF-8-Locales beschränkt ist. - -Die Variable @code{GUIX_LOCPATH} spielt eine ähnliche Rolle wie -@code{LOCPATH} (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C -Library Reference Manual}). Es gibt jedoch zwei wichtige Unterschiede: - -@enumerate -@item -@code{GUIX_LOCPATH} wird nur von der libc in Guix beachtet und nicht der von -Fremddistributionen bereitgestellten libc. Mit @code{GUIX_LOCPATH} können -Sie daher sicherstellen, dass die Programme der Fremddistribution keine -inkompatiblen Locale-Daten von Guix laden. - -@item -libc hängt an jeden @code{GUIX_LOCPATH}-Eintrag @code{/X.Y} an, wobei -@code{X.Y} die Version von libc ist — z.B. @code{2.22}. Sollte Ihr -Guix-Profil eine Mischung aus Programmen enthalten, die an verschiedene -libc-Versionen gebunden sind, wird jede nur die Locale-Daten im richtigen -Format zu laden versuchen. -@end enumerate - -Das ist wichtig, weil das Locale-Datenformat verschiedener libc-Versionen -inkompatibel sein könnte. - -@subsection Name Service Switch - -@cindex Name Service Switch, glibc -@cindex NSS (Name Service Switch), glibc -@cindex nscd (Name Service Caching Daemon) -@cindex Name Service Caching Daemon (nscd) -Wenn Sie Guix auf einer Fremddistribution verwenden, @emph{empfehlen wir -stärkstens}, dass Sie den @dfn{Name Service Cache Daemon} der -GNU-C-Bibliothek, @command{nscd}, laufen lassen, welcher auf dem Socket -@file{/var/run/nscd/socket} lauschen sollte. Wenn Sie das nicht tun, könnten -mit Guix installierte Anwendungen Probleme beim Auflösen von Hostnamen -(d.h. Rechnernamen) oder Benutzerkonten haben, oder sogar abstürzen. Die -nächsten Absätze erklären warum. - -@cindex @file{nsswitch.conf} -Die GNU-C-Bibliothek implementiert einen @dfn{Name Service Switch} (NSS), -welcher einen erweiterbaren Mechanismus zur allgemeinen »Namensauflösung« -darstellt: Hostnamensauflösung, Benutzerkonten und weiteres (@pxref{Name Service Switch,,, libc, The GNU C Library Reference Manual}). - -@cindex Network Information Service (NIS) -@cindex NIS (Network Information Service) -Für die Erweiterbarkeit unterstützt der NSS @dfn{Plugins}, welche neue -Implementierungen zur Namensauflösung bieten: Zum Beispiel ermöglicht das -Plugin @code{nss-mdns} die Namensauflösung für @code{.local}-Hostnamen, das -Plugin @code{nis} gestattet die Auflösung von Benutzerkonten über den -Network Information Service (NIS) und so weiter. Diese zusätzlichen -»Auflösungsdienste« werden systemweit konfiguriert in -@file{/etc/nsswitch.conf} und alle auf dem System laufenden Programme halten -sich an diese Einstellungen (@pxref{NSS Configuration File,,, libc, The GNU -C Reference Manual}). - -Wenn sie eine Namensauflösung durchführen — zum Beispiel, indem sie die -@code{getaddrinfo}-Funktion in C aufrufen — versuchen die Anwendungen als -Erstes, sich mit dem nscd zu verbinden; ist dies erfolgreich, führt nscd für -sie die weiteren Namensauflösungen durch. Falls nscd nicht läuft, führen sie -selbst die Namensauflösungen durch, indem sie die Namensauflösungsdienste in -ihren eigenen Adressraum laden und ausführen. Diese Namensauflösungsdienste -— die @file{libnss_*.so}-Dateien — werden mit @code{dlopen} geladen, aber -sie kommen von der C-Bibliothek des Wirtssystems und nicht von der -C-Bibliothek, mit der die Anwendung gebunden wurde (also der C-Bibliothek -von Guix). - -Und hier kommt es zum Problem: Wenn die Anwendung mit der C-Bibliothek von -Guix (etwa glibc 2.24) gebunden wurde und die NSS-Plugins von einer anderen -C-Bibliothek (etwa @code{libnss_mdns.so} für glibc 2.22) zu laden versucht, -wird sie vermutlich abstürzen oder die Namensauflösungen werden unerwartet -fehlschlagen. - -Durch das Ausführen von @command{nscd} auf dem System wird, neben anderen -Vorteilen, dieses Problem der binären Inkompatibilität vermieden, weil diese -@code{libnss_*.so}-Dateien vom @command{nscd}-Prozess geladen werden, nicht -in den Anwendungen selbst. - -@subsection X11-Schriftarten - -@cindex Schriftarten -Die Mehrheit der grafischen Anwendungen benutzen Fontconfig zum Finden und -Laden von Schriftarten und für die Darstellung im X11-Client. Im Paket -@code{fontconfig} in Guix werden Schriftarten standardmäßig in -@file{$HOME/.guix-profile} gesucht. Um es grafischen Anwendungen, die mit -Guix installiert wurden, zu ermöglichen, Schriftarten anzuzeigen, müssen Sie -die Schriftarten auch mit Guix installieren. Essenzielle Pakete für -Schriftarten sind unter Anderem @code{gs-fonts}, @code{font-dejavu} und -@code{font-gnu-freefont-ttf}. - -Um auf Chinesisch, Japanisch oder Koreanisch verfassten Text in grafischen -Anwendungen anzeigen zu können, möchten Sie vielleicht -@code{font-adobe-source-han-sans} oder @code{font-wqy-zenhei} -installieren. Ersteres hat mehrere Ausgaben, für jede Sprachfamilie eine -(@pxref{Pakete mit mehreren Ausgaben.}). Zum Beispiel installiert folgender -Befehl Schriftarten für chinesische Sprachen: - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Ältere Programme wie @command{xterm} benutzen kein Fontconfig, sondern -X-Server-seitige Schriftartendarstellung. Solche Programme setzen voraus, -dass der volle Name einer Schriftart mit XLFD (X Logical Font Description) -angegeben wird, z.B. so: - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -Um solche vollen Namen für die in Ihrem Guix-Profil installierten -TrueType-Schriftarten zu verwenden, müssen Sie den Pfad für Schriftarten -(Font Path) des X-Servers anpassen: - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See <https://bugs.gnu.org/30655>. -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -Danach können Sie den Befehl @code{xlsfonts} ausführen (aus dem Paket -@code{xlsfonts}), um sicherzustellen, dass dort Ihre TrueType-Schriftarten -aufgeführt sind. - -@cindex @code{fc-cache} -@cindex Font-Cache -Nach der Installation der Schriftarten müssen Sie unter Umständen den -Schriftarten-Zwischenspeicher (Font-Cache) erneuern, um diese in Anwendungen -benutzen zu können. Gleiches gilt, wenn mit Guix installierte Anwendungen -anscheinend keine Schriftarten finden können. Um das Erneuern des -Font-Caches zu erzwingen, führen Sie @code{fc-cache -f} aus. Der Befehl -@code{fc-cache} wird vom Paket @code{fontconfig} angeboten. - -@subsection X.509-Zertifikate - -@cindex @code{nss-certs} -Das Paket @code{nss-certs} bietet X.509-Zertifikate, womit Programme die -Identität von Web-Servern authentifizieren können, auf die über HTTPS -zugegriffen wird. - -Wenn Sie Guix auf einer Fremddistribution verwenden, können Sie dieses Paket -installieren und die relevanten Umgebungsvariablen festlegen, damit Pakete -wissen, wo sie Zertifikate finden. In @xref{X.509-Zertifikate} stehen -genaue Informationen. - -@subsection Emacs-Pakete - -@cindex @code{emacs} -Wenn Sie mit Guix Pakete für Emacs installieren, werden deren elisp-Dateien -entweder in @file{$HOME/.guix-profile/share/emacs/site-lisp/} oder in -Unterverzeichnissen von -@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/} -gespeichert. Letzteres Verzeichnis gibt es, weil es Tausende von -Emacs-Paketen gibt und sie alle im selben Verzeichnis zu speichern -vielleicht nicht verlässlich funktioniert (wegen Namenskonflikten). Daher -halten wir es für richtig, für jedes Paket ein anderes Verzeichnis zu -benutzen. Das Emacs-Paketsystem organisiert die Dateistruktur ähnlich -(@pxref{Package Files,,, emacs, The GNU Emacs Manual}). - -Standardmäßig »weiß« Emacs (wenn er mit Guix installiert wurde), wo diese -Pakete liegen, Sie müssen also nichts selbst konfigurieren. Wenn Sie aber -aus irgendeinem Grund mit Guix installierte Pakete nicht automatisch laden -lassen möchten, können Sie Emacs mit der Befehlszeilenoption -@code{--no-site-file} starten (@pxref{Init File,,, emacs, The GNU Emacs -Manual}). - -@subsection GCC-Toolchain - -@cindex GCC -@cindex ld-wrapper - -Guix bietet individuelle Compiler-Pakete wie etwa @code{gcc}, aber wenn Sie -einen vollständigen Satz an Werkzeugen zum Kompilieren und Binden von -Quellcode brauchen, werden Sie eigentlich das Paket @code{gcc-toolchain} -haben wollen. Das Paket bietet eine vollständige GCC-Toolchain für die -Entwicklung mit C/C++, einschließlich GCC selbst, der GNU-C-Bibliothek -(Header-Dateien und Binärdateien samt Symbolen zur Fehlersuche/Debugging in -der @code{debug}-Ausgabe), Binutils und einen Wrapper für den Binder/Linker. - -The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches -passed to the linker, add corresponding @code{-rpath} arguments, and invoke -the actual linker with this new set of arguments. You can instruct the -wrapper to refuse to link against libraries not in the store by setting the -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. - -@c TODO What else? - -@c ********************************************************************* -@node Systeminstallation -@chapter Systeminstallation - -@cindex installing Guix System -@cindex Guix System, installation -This section explains how to install Guix System on a machine. Guix, as a -package manager, can also be installed on top of a running GNU/Linux system, -@pxref{Installation}. - -@ifinfo -@quotation Anmerkung -@c This paragraph is for people reading this from tty2 of the -@c installation image. -Sie lesen diese Dokumentation mit einem Info-Betrachter. Details, wie Sie -ihn bedienen, erfahren Sie, indem Sie die Eingabetaste (auch »Return« oder -»Enter« genannt) auf folgender Verknüpfung drücken: @pxref{Top, Info -reader,, info-stnd, Stand-alone GNU Info}. Drücken Sie danach @kbd{l}, um -hierher zurückzukommen. - -Führen Sie alternativ @command{info info} auf einer anderen Konsole (tty) -aus, um dieses Handbuch offen zu lassen. -@end quotation -@end ifinfo - -@menu -* Einschränkungen:: Was Sie erwarten dürfen. -* Hardware-Überlegungen:: Unterstützte Hardware. -* Installation von USB-Stick oder DVD:: Das Installationsmedium - vorbereiten. -* Vor der Installation:: Netzwerkanbindung, Partitionierung etc. -* Fortfahren mit der Installation:: Die Hauptsache. -* Installing Guix in a VM:: Guix System playground. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. -@end menu - -@node Einschränkungen -@section Einschränkungen - -As of version @value{VERSION}, Guix System is not production-ready. It may -contain bugs and lack important features. Thus, if you are looking for a -stable production system that respects your freedom as a computer user, a -good solution at this point is to consider -@url{http://www.gnu.org/distros/free-distros.html, one of the more -established GNU/Linux distributions}. We hope you can soon switch to the -Guix System without fear, of course. In the meantime, you can also keep -using your distribution and try out the package manager on top of it -(@pxref{Installation}). - -Bevor Sie mit der Installation fortfahren, beachten Sie die folgenden -merklichen Einschränkungen der Version @value{VERSION}: - -@itemize -@item -Für den Installationsprozess wird keine grafische Oberfläche mitgeliefert -und er erfordert Erfahrung mit GNU/Linux (siehe die folgenden -Unterabschnitte, um ein Gefühl dafür zu bekommen, was wir damit meinen). - -@item -Der Logical Volume Manager (LVM) wird nicht unterstützt. - -@item -Immer mehr Systemdienste sind verfügbar (@pxref{Dienste}), aber manche -könnten noch fehlen. - -@item -More than 8,500 packages are available, but you might occasionally find that -a useful package is missing. - -@item -GNOME, Xfce, LXDE und Enlightenment stehen zur Verfügung (@pxref{Desktop-Dienste}), ebenso eine Reihe von X11-Fensterverwaltungsprogrammen. Manche -grafischen Anwendungen könnten aber noch fehlen, ebenso fehlt KDE. -@end itemize - -Sie wurden gewarnt! Dies soll allerdings nicht nur ein Hinweis sein, sondern -auch als Einladung aufgefasst werden, uns Fehler (und Erfolgsgeschichten!) -zu melden und bei uns mitzumachen, um Guix zu verbessern. Siehe den -Abschnitt @xref{Mitwirken}. - - -@node Hardware-Überlegungen -@section Hardware-Überlegungen - -@cindex hardware support on Guix System -GNU@tie{}Guix focuses on respecting the user's computing freedom. It builds -around the kernel Linux-libre, which means that only hardware for which free -software drivers and firmware exist is supported. Nowadays, a wide range of -off-the-shelf hardware is supported on GNU/Linux-libre---from keyboards to -graphics cards to scanners and Ethernet controllers. Unfortunately, there -are still areas where hardware vendors deny users control over their own -computing, and such hardware is not supported on Guix System. - -@cindex WLAN, Hardware-Unterstützung -One of the main areas where free drivers or firmware are lacking is WiFi -devices. WiFi devices known to work include those using Atheros chips -(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre -driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core -Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. -Free firmware exists for both and is available out-of-the-box on Guix -System, as part of @var{%base-firmware} (@pxref{»operating-system«-Referenz, -@code{firmware}}). - -@cindex RYF, Respects Your Freedom -Die @uref{https://www.fsf.org/, Free Software Foundation} betreibt -@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), ein -Zertifizierungsprogramm für Hardware-Produkte, die Ihre Freiheit und -Privatsphäre respektieren und sicherstellen, dass Sie die Kontrolle über Ihr -Gerät haben. Wir ermutigen Sie dazu, die Liste RYF-zertifizierter Geräte zu -beachten. - -Eine weitere nützliche Ressource ist die Website -@uref{https://www.h-node.org/, H-Node}. Dort steht ein Katalog von -Hardware-Geräten mit Informationen darüber, wie gut sie von GNU/Linux -unterstützt werden. - - -@node Installation von USB-Stick oder DVD -@section Installation von USB-Stick oder DVD - -Sie können ein ISO-9660-Installationsabbild von -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{System}.iso.xz} -herunterladen, dass Sie auf einen USB-Stick aufspielen oder auf eine DVD -brennen können, wobei Sie für @var{System} eines der folgenden schreiben -müssen: - -@table @code -@item x86_64-linux -für ein GNU/Linux-System auf Intel/AMD-kompatiblen 64-Bit-Prozessoren, - -@item i686-linux -für ein 32-Bit-GNU/Linux-System auf Intel-kompatiblen Prozessoren. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Laden Sie auch die entsprechende @file{.sig}-Datei herunter und verifizieren -Sie damit die Authentizität Ihres Abbilds, indem Sie diese Befehle eingeben: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{System}.iso.xz.sig -$ gpg --verify guixsd-install-@value{VERSION}.@var{System}.iso.xz.sig -@end example - -Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen -öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl -importieren: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -und den Befehl @code{gpg --verify} erneut ausführen. - -Dieses Abbild enthält die Werkzeuge, die Sie zur Installation brauchen. Es -ist dafür gedacht, @emph{so wie es ist} auf einen hinreichend großen -USB-Stick oder eine DVD kopiert zu werden. - -@unnumberedsubsec Kopieren auf einen USB-Stick - -Um das Abbild auf einen USB-Stick zu kopieren, führen Sie folgende Schritte -durch: - -@enumerate -@item -Entpacken Sie das Abbild mit dem @command{xz}-Befehl: - -@example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz -@end example - -@item -Stecken Sie einen USB-Stick in Ihren Rechner ein, der mindestens 1@tie{}GiB -groß ist, und bestimmen Sie seinen Gerätenamen. Ist der Gerätename des -USB-Sticks @file{/dev/sdX}, dann kopieren Sie das Abbild mit dem Befehl: - -@example -dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX -sync -@end example - -Sie benötigen in der Regel Administratorrechte, um auf @file{/dev/sdX} -zuzugreifen. -@end enumerate - -@unnumberedsubsec Auf eine DVD brennen - -Um das Abbild auf eine DVD zu kopieren, führen Sie diese Schritte durch: - -@enumerate -@item -Entpacken Sie das Abbild mit dem @command{xz}-Befehl: - -@example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz -@end example - -@item -Legen Sie eine unbespielte DVD in Ihren Rechner ein und bestimmen Sie ihren -Gerätenamen. Angenommen der Name des DVD-Laufwerks ist @file{/dev/srX}, -kopieren Sie das Abbild mit: - -@example -growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso -@end example - -Der Zugriff auf @file{/dev/srX} setzt in der Regel Administratorrechte -voraus. -@end enumerate - -@unnumberedsubsec Das System starten - -Sobald das erledigt ist, sollten Sie Ihr System neu starten und es vom -USB-Stick oder der DVD booten können. Dazu müssen Sie wahrscheinlich beim -Starten des Rechners in das BIOS- oder UEFI-Boot-Menü gehen, von wo aus Sie -auswählen können, dass vom USB-Stick gebootet werden soll. - -@xref{Installing Guix in a VM}, if, instead, you would like to install Guix -System in a virtual machine (VM). - - -@node Vor der Installation -@section Vor der Installation - -Once you have successfully booted your computer using the installation -medium, you should end up with the welcome page of the graphical installer. -The graphical installer is a text-based user interface built upon the newt -library. It shall guide you through all the different steps needed to -install GNU@tie{}Guix System. However, as the graphical installer is still -under heavy development, you might want to fallback to the original, shell -based install process, by switching to TTYs 3 to 6 with the shortcuts -CTRL-ALT-F[3-6]. The following sections describe the installation procedure -assuming you're using one of those TTYs. They are configured and can be used -to run commands as root. - -TTY2 shows this documentation, browsable using the Info reader commands -(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system -runs the GPM mouse daemon, which allows you to select text with the left -mouse button and to paste it with the middle button. - -@quotation Anmerkung -Für die Installation benötigen Sie Zugang zum Internet, damit fehlende -Abhängigkeiten Ihrer Systemkonfiguration heruntergeladen werden können. Im -Abschnitt »Netzwerkkonfiguration« weiter unten finden Sie mehr Informationen -dazu. -@end quotation - -The installation system includes many common tools needed for this task. -But it is also a full-blown Guix System, which means that you can install -additional packages, should you need it, using @command{guix package} -(@pxref{Aufruf von guix package}). - -@subsection Tastaturbelegung - -@cindex Tastaturbelegung -Das Installationsabbild verwendet die US-amerikanische -QWERTY-Tastaturbelegung. Wenn Sie dies ändern möchten, können Sie den -@command{loadkeys}-Befehl benutzen. Mit folgendem Befehl würden Sie zum -Beispiel die Dvorak-Tastaturbelegung auswählen: - -@example -loadkeys dvorak -@end example - -Schauen Sie sich an, welche Dateien im Verzeichnis -@file{/run/current-system/profile/share/keymaps} stehen, um eine Liste -verfügbarer Tastaturbelegungen zu sehen. Wenn Sie mehr Informationen -brauchen, führen Sie @command{man loadkeys} aus. - -@subsection Netzwerkkonfiguration - -Führen Sie folgenden Befehl aus, um zu sehen, wie Ihre -Netzwerkschnittstellen benannt sind: - -@example -ifconfig -a -@end example - -@noindent -@dots{} oder mit dem GNU/Linux-eigenen @command{ip}-Befehl: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Der Name kabelgebundener Schnittstellen (engl. Interfaces) beginnt mit dem -Buchstaben @samp{e}, zum Beispiel heißt die dem ersten fest eingebauten -Ethernet-Adapter entsprechende Schnittstelle @samp{eno1}. Drahtlose -Schnittstellen werden mit einem Namen bezeichnet, der mit dem Buchstaben -@samp{w} beginnt, etwa @samp{w1p2s0}. - -@table @asis -@item Kabelverbindung -Um ein kabelgebundenes Netzwerk einzurichten, führen Sie den folgenden -Befehl aus, wobei Sie statt @var{Schnittstelle} den Namen der -kabelgebundenen Schnittstelle eintippen, die Sie benutzen möchten. - -@example -ifconfig @var{Schnittstelle} up -@end example - -@item Drahtlose Verbindung -@cindex WLAN -@cindex WiFi -Um Drahtlosnetzwerke einzurichten, können Sie eine Konfigurationsdatei für -das Konfigurationswerkzeug des @command{wpa_supplicant} schreiben (wo Sie -sie speichern, ist nicht wichtig), indem Sie eines der verfügbaren -Textbearbeitungsprogramme wie etwa @command{nano} benutzen: - -@example -nano wpa_supplicant.conf -@end example - -Zum Beispiel können Sie die folgende Formulierung in der Datei speichern, -die für viele Drahtlosnetzwerke funktioniert, sofern Sie die richtige SSID -und Passphrase für das Netzwerk eingeben, mit dem Sie sich verbinden -möchten: - -@example -network=@{ - ssid="@var{meine-ssid}" - key_mgmt=WPA-PSK - psk="geheime Passphrase des Netzwerks" -@} -@end example - -Starten Sie den Dienst für Drahtlosnetzwerke und lassen Sie ihn im -Hintergrund laufen, indem Sie folgenden Befehl eintippen (ersetzen Sie dabei -@var{Schnittstelle} durch den Namen der Netzwerkschnittstelle, die Sie -benutzen möchten): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{Schnittstelle} -B -@end example - -Führen Sie @command{man wpa_supplicant} aus, um mehr Informationen zu -erhalten. -@end table - -@cindex DHCP -Zu diesem Zeitpunkt müssen Sie sich eine IP-Adresse beschaffen. Auf einem -Netzwerk, wo IP-Adressen automatisch @i{via} DHCP zugewiesen werden, können -Sie das hier ausführen: - -@example -dhclient -v @var{Schnittstelle} -@end example - -Versuchen Sie, einen Server zu pingen, um zu prüfen, ob sie mit dem Internet -verbunden sind und alles richtig funktioniert: - -@example -ping -c 3 gnu.org -@end example - -Einen Internetzugang herzustellen, ist in jedem Fall nötig, weil das Abbild -nicht alle Software und Werkzeuge enthält, die nötig sein könnten. - -@cindex Über SSH installieren -Wenn Sie möchten, können Sie die weitere Installation auch per Fernwartung -durchführen, indem Sie einen SSH-Server starten: - -@example -herd start ssh-daemon -@end example - -Vergewissern Sie sich vorher, dass Sie entweder ein Passwort mit -@command{passwd} festgelegt haben, oder dass Sie für OpenSSH eine -Authentifizierung über öffentliche Schlüssel eingerichtet haben, bevor Sie -sich anmelden. - -@subsection Plattenpartitionierung - -Sofern nicht bereits geschehen, ist der nächste Schritt, zu partitionieren -und dann die Zielpartition zu formatieren. - -Auf dem Installationsabbild sind mehrere Partitionierungswerkzeuge zu -finden, einschließlich (@pxref{Overview,,, parted, GNU Parted User Manual}), -@command{fdisk} und @command{cfdisk}. Starten Sie eines davon und -partitionieren Sie Ihre Festplatte oder sonstigen Massenspeicher: - -@example -cfdisk -@end example - -Wenn Ihre Platte mit einer »GUID Partition Table« (GPT) formatiert ist, und -Sie vorhaben, die BIOS-basierte Variante des GRUB-Bootloaders zu -installieren (was der Vorgabe entspricht), stellen Sie sicher, dass eine -Partition als BIOS-Boot-Partition ausgewiesen ist (@pxref{BIOS -installation,,, grub, GNU GRUB manual}). - -@cindex EFI, Installation -@cindex UEFI, Installation -@cindex ESP, EFI-Systempartition -If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System -Partition} (ESP) is required. This partition can be mounted at -@file{/boot/efi} for instance and must have the @code{esp} flag set. E.g., -for @command{parted}: - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Anmerkung -@vindex grub-bootloader -@vindex grub-efi-bootloader -Falls Sie nicht wissen, ob Sie einen EFI- oder BIOS-basierten GRUB -installieren möchten: Wenn bei Ihnen das Verzeichnis -@file{/sys/firmware/efi} im Dateisystem existiert, möchten Sie vermutlich -eine EFI-Installation durchführen, wozu Sie in Ihrer Konfiguration -@code{grub-efi-bootloader} benutzen. Ansonsten sollten Sie den -BIOS-basierten GRUB benutzen, der mit @code{grub-bootloader} bezeichnet -wird. Siehe @xref{Bootloader-Konfiguration}, wenn Sie mehr Informationen -über Bootloader brauchen. -@end quotation - -Once you are done partitioning the target hard disk drive, you have to -create a file system on the relevant partition(s)@footnote{Currently Guix -System only supports ext4 and btrfs file systems. In particular, code that -reads file system UUIDs and labels only works for these file system -types.}. For the ESP, if you have one and assuming it is @file{/dev/sda1}, -run: - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Geben Sie Ihren Dateisystemen auch besser eine Bezeichnung (»Label«), damit -Sie sie zuverlässig wiedererkennen und später in den -@code{file-system}-Deklarationen darauf Bezug nehmen können (@pxref{Dateisysteme}). Dazu benutzen Sie typischerweise die Befehlszeilenoption -@code{-L} des Befehls @command{mkfs.ext4} oder entsprechende Optionen für -andere Befehle. Wenn wir also annehmen, dass @file{/dev/sda2} die Partition -ist, auf der Ihr Wurzeldateisystem (englisch »root«) wohnen soll, können Sie -dort mit diesem Befehl ein Dateisystem mit der Bezeichnung @code{my-root} -erstellen: - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex verschlüsselte Partition -Falls Sie aber vorhaben, die Partition mit dem Wurzeldateisystem zu -verschlüsseln, können Sie dazu die Cryptsetup-/LUKS-Werkzeuge verwenden -(siehe @inlinefmtifelse{html, @uref{https://linux.die.net/man/8/cryptsetup, -@code{man cryptsetup}}, @code{man cryptsetup}}, um mehr darüber zu -erfahren). Angenommen Sie wollen die Partition für das Wurzeldateisystem -verschlüsselt auf @file{/dev/sda2} installieren, dann brauchen Sie eine -Befehlsfolge ähnlich wie diese: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Sobald das erledigt ist, binden Sie dieses Dateisystem als Installationsziel -mit dem Einhängepunkt @file{/mnt} ein, wozu Sie einen Befehl wie hier -eintippen (auch hier unter der Annahme, dass @code{my-root} die Bezeichnung -des künftigen Wurzeldateisystems ist): - -@example -mount LABEL=my-root /mnt -@end example - -Also mount any other file systems you would like to use on the target system -relative to this path. If you have opted for @file{/boot/efi} as an EFI -mount point for example, mount it at @file{/mnt/boot/efi} now so it is found -by @code{guix system init} afterwards. - -Wenn Sie zudem auch vorhaben, eine oder mehrere Swap-Partitionen zu benutzen -(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference -Manual}), initialisieren Sie diese nun mit @command{mkswap}. Angenommen Sie -haben eine Swap-Partition auf @file{/dev/sda3}, dann würde der Befehl so -lauten: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Alternativ können Sie eine Swap-Datei benutzen. Angenommen, Sie wollten die -Datei @file{/swapdatei} im neuen System als eine Swapdatei benutzen, dann -müssten Sie Folgendes ausführen@footnote{Dieses Beispiel wird auf vielen -Arten von Dateisystemen funktionieren (z.B. auf ext4). Auf Dateisystemen mit -Copy-on-Write (wie z.B. btrfs) können sich die nötigen Schritte -unterscheiden. Details finden Sie in der Dokumentation auf den -Handbuchseiten von @command{mkswap} und @command{swapon}.}: - -@example -# Das bedeutet 10 GiB Swapspeicher. "count" anpassen zum ändern. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# Zur Sicherheit darf nur der Administrator lesen und schreiben. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Bedenken Sie, dass, wenn Sie die Partition für das Wurzeldateisystem -(»root«) verschlüsselt und eine Swap-Datei in diesem Dateisystem wie oben -beschrieben erstellt haben, die Verschlüsselung auch die Swap-Datei schützt, -genau wie jede andere Datei in dem Dateisystem. - -@node Fortfahren mit der Installation -@section Fortfahren mit der Installation - -Wenn die Partitionen des Installationsziels bereit sind und dessen -Wurzeldateisystem unter @file{/mnt} eingebunden wurde, kann es losgehen mit -der Installation. Führen Sie zuerst aus: - -@example -herd start cow-store /mnt -@end example - -Dadurch wird @file{/gnu/store} copy-on-write, d.h. dorthin von Guix -erstellte Pakete werden in ihrer Installationsphase auf dem unter -@file{/mnt} befindlichen Zieldateisystem gespeichert, statt den -Arbeitsspeicher auszulasten. Das ist nötig, weil die erste Phase des Befehls -@command{guix system init} (siehe unten) viele Dateien nach -@file{/gnu/store} herunterlädt oder sie erstellt, Änderungen am -@file{/gnu/store} aber bis dahin wie das übrige Installationssystem nur im -Arbeitsspeicher gelagert werden konnten. - -Als Nächstes müssen Sie eine Datei bearbeiten und dort eine Deklaration des -Betriebssystems, das Sie installieren möchten, hineinschreiben. Zu diesem -Zweck sind im Installationssystem drei Texteditoren enthalten. Wir -empfehlen, dass Sie GNU nano benutzen (@pxref{Top,,, nano, GNU nano -Manual}), welcher Syntax und zueinander gehörende Klammern hervorheben -kann. Andere mitgelieferte Texteditoren, die Sie benutzen können, sind GNU -Zile (ein Emacs-Klon) und nvi (ein Klon des ursprünglichen -@command{vi}-Editors von BSD). Wir empfehlen sehr, dass Sie diese Datei im -Zieldateisystem der Installation speichern, etwa als -@file{/mnt/etc/config.scm}, weil Sie Ihre Konfigurationsdatei im frisch -installierten System noch brauchen werden. - -Der Abschnitt @xref{Das Konfigurationssystem nutzen} gibt einen Überblick -über die Konfigurationsdatei. Die in dem Abschnitt diskutierten -Beispielkonfigurationen sind im Installationsabbild im Verzeichnis -@file{/etc/configuration} zu finden. Um also mit einer Systemkonfiguration -anzufangen, die einen grafischen »Display-Server« (eine -»Desktop«-Arbeitsumgebung) bietet, könnten Sie so etwas ausführen: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -Achten Sie darauf, was in Ihrer Konfigurationsdatei steht, und besonders auf -Folgendes: - -@itemize -@item -Make sure the @code{bootloader-configuration} form refers to the target you -want to install GRUB on. It should mention @code{grub-bootloader} if you -are installing GRUB in the legacy way, or @code{grub-efi-bootloader} for -newer UEFI systems. For legacy systems, the @code{target} field names a -device, like @code{/dev/sda}; for UEFI systems it names a path to a mounted -EFI partition, like @code{/boot/efi}; do make sure the path is currently -mounted and a @code{file-system} entry is specified in your configuration. - -@item -Dateisystembezeichnungen müssen mit den jeweiligen @code{device}-Feldern in -Ihrer @code{file-system}-Konfiguration übereinstimmen, sofern Sie in Ihrer -@code{file-system}-Konfiguration die Prozedur @code{file-system-label} für -ihre @code{device}-Felder benutzen. - -@item -Gibt es verschlüsselte Partitionen oder RAID-Partitionen, dann müssen sie im -@code{mapped-devices}-Feld genannt werden (@pxref{Zugeordnete Geräte}). -@end itemize - -Wenn Sie damit fertig sind, Ihre Konfigurationsdatei vorzubereiten, können -Sie das neue System initialisieren (denken Sie daran, dass zukünftige -Wurzeldateisystem muss unter @file{/mnt} wie bereits beschrieben eingebunden -sein): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -Dies kopiert alle notwendigen Dateien und installiert GRUB auf -@file{/dev/sdX}, sofern Sie nicht noch die Befehlszeilenoption -@option{--no-bootloader} benutzen. Weitere Informationen finden Sie im -Abschnitt @pxref{Aufruf von guix system}. Der Befehl kann das Herunterladen -oder Erstellen fehlender Softwarepakete auslösen, was einige Zeit in -Anspruch nehmen kann. - -Sobald der Befehl erfolgreich — hoffentlich! — durchgelaufen ist, können Sie -mit dem Befehl @command{reboot} das neue System booten lassen. Der -Administratornutzer @code{root} hat im neuen System zunächst ein leeres -Passwort und Passwörter der anderen Nutzer müssen Sie erst setzen, indem Sie -den Befehl @command{passwd} als @code{root} ausführen, außer Ihre -Konfiguration enthält schon Passwörter (@pxref{user-account-password, user -account passwords}). - -@cindex upgrading Guix System -From then on, you can update the system whenever you want by running, say: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -This builds a new system generation with the latest packages and services -(@pxref{Aufruf von guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Sicherheitsaktualisierungen}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@quotation Anmerkung -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. -@end quotation - -Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience---good or not so good. - -@node Installing Guix in a VM -@section Installing Guix in a Virtual Machine - -@cindex virtual machine, Guix System installation -@cindex Virtual Private Server (VPS) -@cindex VPS (Virtual Private Server) -If you'd like to install Guix System in a virtual machine (VM) or on a -virtual private server (VPS) rather than on your beloved machine, this -section is for you. - -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a -disk image, follow these steps: - -@enumerate -@item -First, retrieve and decompress the Guix system installation image as -described previously (@pxref{Installation von USB-Stick oder DVD}). - -@item -Legen Sie nun ein Disk-Image an, das das System nach der Installation -enthalten soll. Um ein qcow2-formatiertes Disk-Image zu erstellen, benutzen -Sie den Befehl @command{qemu-img}: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -Die Datei, die Sie herausbekommen, wird wesentlich kleiner als 50 GB sein -(typischerweise kleiner als 1 MB), vergrößert sich aber, wenn der -virtualisierte Speicher gefüllt wird. - -@item -Starten Sie das USB-Installationsabbild auf einer virtuellen Maschine: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guixsd-install-@value{VERSION}.@var{System}.iso \ - -drive file=guixsd.img -@end example - -Halten Sie obige Reihenfolge der @option{-drive}-Befehlszeilenoptionen für -die Laufwerke ein. - -Drücken Sie auf der Konsole der virtuellen Maschine schnell die -@kbd{F12}-Taste, um ins Boot-Menü zu gelangen. Drücken Sie dort erst die -Taste @kbd{2} und dann die Eingabetaste @kbd{RET}, um Ihre Auswahl zu -bestätigen. - -@item -Sie sind nun in der virtuellen Maschine als Administratornutzer @code{root} -angemeldet und können mit der Installation wie gewohnt fortfahren. Folgen -Sie der Anleitung im Abschnitt @xref{Vor der Installation}. -@end enumerate - -Once installation is complete, you can boot the system that's on your -@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do that. - -@node Ein Abbild zur Installation erstellen -@section Ein Abbild zur Installation erstellen - -@cindex Installationsabbild -Das oben beschriebene Installationsabbild wurde mit dem Befehl @command{guix -system} erstellt, genauer gesagt mit: - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Die Datei @file{gnu/system/install.scm} finden Sie im Quellbaum von -Guix. Schauen Sie sich die Datei und auch den Abschnitt @ref{Aufruf von guix system} an, um mehr Informationen über das Installationsabbild zu erhalten. - -@section Abbild zur Installation für ARM-Rechner erstellen - -Viele ARM-Chips funktionieren nur mit ihrer eigenen speziellen Variante des -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot}-Bootloaders. - -Wenn Sie ein Disk-Image erstellen und der Bootloader nicht anderweitig schon -installiert ist (auf einem anderen Laufwerk), ist es ratsam, ein Disk-Image -zu erstellen, was den Bootloader enthält, mit dem Befehl: - -@example -guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' -@end example - -@code{A20-OLinuXino-Lime2} ist der Name des Chips. Wenn Sie einen ungültigen -Namen eingeben, wird eine Liste möglicher Chip-Namen ausgegeben. - -@c ********************************************************************* -@node Paketverwaltung -@chapter Paketverwaltung - -@cindex Pakete -Der Zweck von GNU Guix ist, Benutzern die leichte Installation, -Aktualisierung und Entfernung von Software-Paketen zu ermöglichen, ohne dass -sie ihre Erstellungsprozeduren oder Abhängigkeiten kennen müssen. Guix kann -natürlich noch mehr als diese offensichtlichen Funktionalitäten. - -Dieses Kapitel beschreibt die Hauptfunktionalitäten von Guix, sowie die von -Guix angebotenen Paketverwaltungswerkzeuge. Zusätzlich von den im Folgenden -beschriebenen Befehlszeilen-Benutzerschnittstellen (@pxref{Aufruf von guix package, @code{guix package}}) können Sie auch mit der -Emacs-Guix-Schnittstelle (@pxref{Top,,, emacs-guix, The Emacs-Guix Reference -Manual}) arbeiten, nachdem Sie das Paket @code{emacs-guix} installiert haben -(führen Sie zum Einstieg in Emacs-Guix den Emacs-Befehl @kbd{M-x guix-help} -aus): - -@example -guix package -i emacs-guix -@end example - -@menu -* Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird. -* Aufruf von guix package:: Pakete installieren, entfernen usw. -* Substitute:: Vorerstelle Binärdateien herunterladen. -* Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben. -* Aufruf von guix gc:: Den Müllsammler laufen lassen. -* Aufruf von guix pull:: Das neueste Guix samt Distribution laden. -* Kanäle:: Die Paketsammlung anpassen. -* Untergeordnete:: Mit einer anderen Version von Guix - interagieren. -* Aufruf von guix describe:: Informationen über Ihre Guix-Version - anzeigen. -* Aufruf von guix archive:: Import und Export von Store-Dateien. -@end menu - -@node Funktionalitäten -@section Funktionalitäten - -Wenn Sie Guix benutzen, landet jedes Paket schließlich im @dfn{Paket-Store} -in seinem eigenen Verzeichnis — der Name ist ähnlich wie -@file{/gnu/store/xxx-package-1.2}, wobei @code{xxx} eine Zeichenkette in -Base32-Darstellung ist. - -Statt diese Verzeichnisse direkt anzugeben, haben Nutzer ihr eigenes -@dfn{Profil}, welches auf diejenigen Pakete zeigt, die sie tatsächlich -benutzen wollen. Diese Profile sind im Persönlichen Verzeichnis des -jeweiligen Nutzers gespeichert als @code{$HOME/.guix-profile}. - -Zum Beispiel installiert @code{alice} GCC 4.7.2. Dadurch zeigt dann -@file{/home/alice/.guix-profile/bin/gcc} auf -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Auf demselben Rechner hat -@code{bob} bereits GCC 4.8.0 installiert. Das Profil von @code{bob} zeigt -dann einfach weiterhin auf @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc} — -d.h. beide Versionen von GCC koexistieren auf demselben System, ohne sich zu -stören. - -Der Befehl @command{guix package} ist das zentrale Werkzeug, um Pakete zu -verwalten (@pxref{Aufruf von guix package}). Es arbeitet auf dem eigenen -Profil jedes Nutzers und kann @emph{mit normalen Benutzerrechten} ausgeführt -werden. - -@cindex Transaktionen -Der Befehl stellt die offensichtlichen Installations-, Entfernungs- und -Aktualisierungsoperationen zur Verfügung. Jeder Aufruf ist tatsächlich eine -eigene @emph{Transaktion}: Entweder die angegebene Operation wird -erfolgreich durchgeführt, oder gar nichts passiert. Wenn also der Prozess -von @command{guix package} während der Transaktion beendet wird, oder es zum -Stromausfall während der Transaktion kommt, dann bleibt der alte, nutzbare -Zustands des Nutzerprofils erhalten. - -In addition, any package transaction may be @emph{rolled back}. So, if, for -example, an upgrade installs a new version of a package that turns out to -have a serious bug, users may roll back to the previous instance of their -profile, which was known to work well. Similarly, the global system -configuration on Guix is subject to transactional upgrades and roll-back -(@pxref{Das Konfigurationssystem nutzen}). - -Alle Pakete im Paket-Store können vom @emph{Müllsammler} (Garbage Collector) -gelöscht werden. Guix ist in der Lage, festzustellen, welche Pakete noch -durch Benutzerprofile referenziert werden, und entfernt nur diese, die -nachweislich nicht mehr referenziert werden (@pxref{Aufruf von guix gc}). Benutzer können auch ausdrücklich alte Generationen ihres Profils -löschen, damit die zugehörigen Pakete vom Müllsammler gelöscht werden -können. - -@cindex Reproduzierbarkeit -@cindex Reproduzierbare Erstellungen -Guix verfolgt einen @dfn{rein funktionalen} Ansatz bei der Paketverwaltung, -wie er in der Einleitung beschrieben wurde (@pxref{Einführung}). Jedes -Paketverzeichnis im @file{/gnu/store} hat einen Hash all seiner bei der -Erstellung benutzten Eingaben im Namen — Compiler, Bibliotheken, -Erstellungs-Skripts etc. Diese direkte Entsprechung ermöglicht es Benutzern, -eine Paketinstallation zu benutzen, die sicher dem aktuellen Stand ihrer -Distribution entspricht. Sie maximiert auch die @dfn{Reproduzierbarkeit der -Erstellungen} zu maximieren: Dank der isolierten Erstellungsumgebungen, die -benutzt werden, resultiert eine Erstellung wahrscheinlich in bitweise -identischen Dateien, auch wenn sie auf unterschiedlichen Maschinen -durchgeführt wird (@pxref{Aufruf des guix-daemon, container}). - -@cindex Substitute -Auf dieser Grundlage kann Guix @dfn{transparent Binär- oder Quelldateien -ausliefern}. Wenn eine vorerstellte Binärdatei für ein -@file{/gnu/store}-Objekt von einer externen Quelle verfügbar ist — ein -@dfn{Substitut} —, lädt Guix sie einfach herunter und entpackt sie, -andernfalls erstellt Guix das Paket lokal aus seinem Quellcode -(@pxref{Substitute}). Weil Erstellungsergebnisse normalerweise Bit für Bit -reproduzierbar sind, müssen die Nutzer den Servern, die Substitute anbieten, -nicht blind vertrauen; sie können eine lokale Erstellung erzwingen und -Substitute @emph{anfechten} (@pxref{Aufruf von guix challenge}). - -Kontrolle über die Erstellungsumgebung ist eine auch für Entwickler -nützliche Funktionalität. Der Befehl @command{guix environment} ermöglicht -es Entwicklern eines Pakets, schnell die richtige Entwicklungsumgebung für -ihr Paket einzurichten, ohne manuell die Abhängigkeiten des Pakets in ihr -Profil installieren zu müssen (@pxref{Aufruf von guix environment}). - -@cindex Nachbildung, von Software-Umgebungen -@cindex Provenienzverfolgung, von Software-Artefakten -Ganz Guix und all seine Paketdefinitionen stehen unter Versionskontrolle und -@command{guix pull} macht es möglich, auf dem Verlauf der Entwicklung von -Guix selbst »in der Zeit zu reisen« (@pxref{Aufruf von guix pull}). Dadurch -kann eine Instanz von Guix auf einer anderen Maschine oder zu einem späteren -Zeitpunkt genau nachgebildet werden, wodurch auch @emph{vollständige -Software-Umgebungen gänzlich nachgebildet} werden können, mit genauer -@dfn{Provenienzverfolgung}, wo diese Software herkommt. - -@node Aufruf von guix package -@section Invoking @command{guix package} - -@cindex Installieren von Paketen -@cindex Entfernen von Paketen -@cindex Paketinstallation -@cindex Paketentfernung -Der Befehl @command{guix package} ist ein Werkzeug, womit Nutzer Pakete -installieren, aktualisieren, entfernen und auf vorherige Konfigurationen -zurücksetzen können. Dabei wird nur das eigene Profil des Nutzers verwendet, -und es funktioniert mit normalen Benutzerrechten, ohne Administratorrechte -(@pxref{Funktionalitäten}). Die Syntax ist: - -@example -guix package @var{Optionen} -@end example -@cindex Transaktionen -In erster Linie geben die @var{Optionen} an, welche Operationen in der -Transaktion durchgeführt werden sollen. Nach Abschluss wird ein neues Profil -erzeugt, aber vorherige @dfn{Generationen} des Profils bleiben verfügbar, -falls der Benutzer auf sie zurückwechseln will. - -Um zum Beispiel @code{lua} zu entfernen und @code{guile} und -@code{guile-cairo} in einer einzigen Transaktion zu installieren: - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} unterstützt auch ein @dfn{deklaratives Vorgehen}, -wobei der Nutzer die genaue Menge an Paketen, die verfügbar sein sollen, -festlegt und über die Befehlszeilenoption @option{--manifest} übergibt -(@pxref{profile-manifest, @option{--manifest}}). - -@cindex Profil -Für jeden Benutzer wird automatisch eine symbolische Verknüpfung zu seinem -Standardprofil angelegt als @file{$HOME/.guix-profile}. Diese symbolische -Verknüpfung zeigt immer auf die aktuelle Generation des Standardprofils des -Benutzers. Somit können Nutzer @file{$HOME/.guix-profile/bin} z.B. zu ihrer -Umgebungsvariablen @code{PATH} hinzufügen. -@cindex Suchpfade -Wenn Sie nicht die Guix System Distribution benutzen, sollten Sie in -Betracht ziehen, folgende Zeilen zu Ihrem @file{~/.bash_profile} -hinzuzufügen (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference -Manual}), damit in neu erzeugten Shells alle Umgebungsvariablen richtig -definiert werden: - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -Ist Ihr System für mehrere Nutzer eingerichtet, werden Nutzerprofile an -einem Ort gespeichert, der als @dfn{Müllsammlerwurzel} registriert ist, auf -die @file{$HOME/.guix-profile} zeigt (@pxref{Aufruf von guix gc}). Dieses -Verzeichnis ist normalerweise -@code{@var{localstatedir}/guix/profiles/per-user/@var{Benutzer}}, wobei -@var{localstatedir} der an @code{configure} als @code{--localstatedir} -übergebene Wert ist und @var{Benutzer} für den jeweiligen Benutzernamen -steht. Das @file{per-user}-Verzeichnis wird erstellt, wenn -@command{guix-daemon} gestartet wird, und das Unterverzeichnis -@var{Benutzer} wird durch @command{guix package} erstellt. - -Als @var{Optionen} kann vorkommen: - -@table @code - -@item --install=@var{Paket} @dots{} -@itemx -i @var{Paket} @dots{} -Die angegebenen @var{Paket}e installieren. - -Jedes @var{Paket} kann entweder einfach durch seinen Paketnamen aufgeführt -werden, wie @code{guile}, oder als Paketname gefolgt von einem At-Zeichen @@ -und einer Versionsnummer, wie @code{guile@@1.8.8} oder auch nur -@code{guile@@1.8} (in letzterem Fall wird die neueste Version mit Präfix -@code{1.8} ausgewählt.) - -Wird keine Versionsnummer angegeben, wird die neueste verfügbare Version -ausgewählt. Zudem kann im @var{Paket} ein Doppelpunkt auftauchen, gefolgt -vom Namen einer der Ausgaben des Pakets, wie @code{gcc:doc} oder -@code{binutils@@2.22:lib} (@pxref{Pakete mit mehreren Ausgaben.}). Pakete -mit zugehörigem Namen (und optional der Version) werden unter den Modulen -der GNU-Distribution gesucht (@pxref{Paketmodule}). - -@cindex propagierte Eingaben -Manchmal haben Pakete @dfn{propagierte Eingaben}: Als solche werden -Abhängigkeiten bezeichnet, die automatisch zusammen mit dem angeforderten -Paket installiert werden (im Abschnitt @pxref{package-propagated-inputs, -@code{propagated-inputs} in @code{package} objects} sind weitere -Informationen über propagierte Eingaben in Paketdefinitionen zu finden). - -@anchor{package-cmd-propagated-inputs} -Ein Beispiel ist die GNU-MPC-Bibliothek: Ihre C-Headerdateien verweisen auf -die der GNU-MPFR-Bibliothek, welche wiederum auf die der GMP-Bibliothek -verweisen. Wenn also MPC installiert wird, werden auch die MPFR- und -GMP-Bibliotheken in das Profil installiert; entfernt man MPC, werden auch -MPFR und GMP entfernt — außer sie wurden noch auf andere Art ausdrücklich -vom Nutzer installiert. - -Abgesehen davon setzen Pakete manchmal die Definition von Umgebungsvariablen -für ihre Suchpfade voraus (siehe die Erklärung von @code{--search-paths} -weiter unten). Alle fehlenden oder womöglich falschen Definitionen von -Umgebungsvariablen werden hierbei gemeldet. - -@item --install-from-expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Das Paket installieren, zu dem der @var{Ausdruck} ausgewertet wird. - -Beim @var{Ausdruck} muss es sich um einen Scheme-Ausdruck handeln, der zu -einem @code{<package>}-Objekt ausgewertet wird. Diese Option ist besonders -nützlich, um zwischen gleichnamigen Varianten eines Pakets zu unterscheiden, -durch Ausdrücke wie @code{(@@ (gnu packages base) guile-final)}. - -Beachten Sie, dass mit dieser Option die erste Ausgabe des angegebenen -Pakets installiert wird, was unzureichend sein kann, wenn eine bestimmte -Ausgabe eines Pakets mit mehreren Ausgaben gewünscht ist. - -@item --install-from-file=@var{Datei} -@itemx -f @var{Datei} -Das Paket installieren, zu dem der Code in der @var{Datei} ausgewertet wird. - -Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten -(@pxref{Pakete definieren}): - -@example -@verbatiminclude package-hello.scm -@end example - -Entwickler könnten es für nützlich erachten, eine solche -@file{guix.scm}-Datei im Quellbaum ihres Projekts abzulegen, mit der -Zwischenstände der Entwicklung getestet und reproduzierbare -Erstellungsumgebungen aufgebaut werden können (@pxref{Aufruf von guix environment}). - -@item --remove=@var{Paket} @dots{} -@itemx -r @var{Paket} @dots{} -Die angegebenen @var{Paket}e entfernen. - -Wie auch bei @code{--install} kann jedes @var{Paket} neben dem Paketnamen -auch eine Versionsnummer und/oder eine Ausgabe benennen. Zum Beispiel würde -@code{-r glibc:debug} die @code{debug}-Ausgabe von @code{glibc} aus dem -Profil entfernen. - -@item --upgrade[=@var{Regexp} @dots{}] -@itemx -u [@var{Regexp} @dots{}] -@cindex Pakete aktualisieren -Alle installierten Pakete aktualisieren. Wenn einer oder mehr reguläre -Ausdrücke (Regexps) angegeben wurden, werden nur diejenigen installierten -Pakete aktualisiert, deren Name zu einer der @var{Regexp}s passt. Siehe auch -weiter unten die Befehlszeilenoption @code{--do-not-upgrade}. - -Beachten Sie, dass das Paket so auf die neueste Version unter den Paketen -gebracht wird, die in der aktuell installierten Distribution vorliegen. Um -jedoch Ihre Distribution zu aktualisieren, sollten Sie regelmäßig -@command{guix pull} ausführen (@pxref{Aufruf von guix pull}). - -@item --do-not-upgrade[=@var{Regexp} @dots{}] -In Verbindung mit der Befehlszeilenoption @code{--upgrade}, führe -@emph{keine} Aktualisierung von Paketen durch, deren Name zum regulären -Ausdruck @var{Regexp} passt. Um zum Beispiel alle Pakete im aktuellen Profil -zu aktualisieren mit Ausnahme derer, die »emacs« im Namen haben: - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{Datei} -@itemx -m @var{Datei} -@cindex Profildeklaration -@cindex Profilmanifest -Erstellt eine neue Generation des Profils aus dem vom Scheme-Code in -@var{Datei} gelieferten Manifest-Objekt. - -Dadurch könnrn Sie den Inhalt des Profils @emph{deklarieren}, statt ihn -durch eine Folge von Befehlen wie @code{--install} u.Ä. zu generieren. Der -Vorteil ist, dass die @var{Datei} unter Versionskontrolle gestellt werden -kann, auf andere Maschinen zum Reproduzieren desselben Profils kopiert -werden kann und Ähnliches. - -@c FIXME: Add reference to (guix profile) documentation when available. -Der Code in der @var{Datei} muss ein @dfn{Manifest}-Objekt liefern, was -ungefähr einer Liste von Paketen entspricht: - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Eine bestimmte Paketausgabe nutzen. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -In diesem Beispiel müssen wir wissen, welche Module die Variablen -@code{emacs} und @code{guile-2.0} definieren, um die richtige Angabe mit -@code{use-package-modules} machen zu können, was umständlich sein kann. Wir -können auch normale Paketnamen angeben und sie durch -@code{specifications->manifest} zu den entsprechenden Paketobjekten -auflösen, zum Beispiel so: - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex rücksetzen -@cindex Zurücksetzen von Transaktionen -@cindex Transaktionen, zurücksetzen -Wechselt zur vorherigen @dfn{Generation} des Profils zurück — d.h. macht die -letzte Transaktion rückgängig. - -In Verbindung mit Befehlszeilenoptionen wie @code{--install} wird zuerst -zurückgesetzt, bevor andere Aktionen durchgeführt werden. - -Ein Rücksetzen der ersten Generation, die installierte Pakete enthält, -wechselt das Profil zur @dfn{nullten Generation}, die keinerlei Dateien -enthält, abgesehen von Metadaten über sich selbst. - -Nach dem Zurücksetzen überschreibt das Installieren, Entfernen oder -Aktualisieren von Paketen vormals zukünftige Generationen, d.h. der Verlauf -der Generationen eines Profils ist immer linear. - -@item --switch-generation=@var{Muster} -@itemx -S @var{Muster} -@cindex Generationen -Wechselt zu der bestimmten Generation, die durch das @var{Muster} bezeichnet -wird. - -Als @var{Muster} kann entweder die Nummer einer Generation oder eine Nummer -mit vorangestelltem »+« oder »-« dienen. Letzteres springt die angegebene -Anzahl an Generationen vor oder zurück. Zum Beispiel kehrt -@code{--switch-generation=+1} nach einem Zurücksetzen wieder zur neueren -Generation zurück. - -Der Unterschied zwischen @code{--roll-back} und -@code{--switch-generation=-1} ist, dass @code{--switch-generation} keine -nullte Generation erzeugen wird; existiert die angegebene Generation nicht, -bleibt schlicht die aktuelle Generation erhalten. - -@item --search-paths[=@var{Art}] -@cindex Suchpfade -Führe die Definitionen von Umgebungsvariablen auf, in Bash-Syntax, die nötig -sein könnten, um alle installierten Pakete nutzen zu können. Diese -Umgebungsvariablen werden benutzt, um die @dfn{Suchpfade} für Dateien -festzulegen, die von einigen installierten Paketen benutzt werden. - -Zum Beispiel braucht GCC die Umgebungsvariablen @code{CPATH} und -@code{LIBRARY_PATH}, um zu wissen, wo sich im Benutzerprofil Header und -Bibliotheken befinden (@pxref{Environment Variables,,, gcc, Using the GNU -Compiler Collection (GCC)}). Wenn GCC und, sagen wir, die C-Bibliothek im -Profil installiert sind, schlägt @code{--search-paths} also vor, diese -Variablen jeweils auf @code{@var{profile}/include} und -@code{@var{profile}/lib} verweisen zu lassen. - -Die typische Nutzung ist, in der Shell diese Variablen zu definieren: - -@example -$ eval `guix package --search-paths` -@end example - -Als @var{Art} kann entweder @code{exact}, @code{prefix} oder @code{suffix} -gewählt werden, wodurch die gelieferten Definitionen der Umgebungsvariablen -entweder exakt die Einstellungen für Guix meldet, oder sie als Präfix oder -Suffix an den aktuellen Wert dieser Variablen anhängt. Gibt man keine -@var{Art} an, wird der Vorgabewert @code{exact} verwendet. - -Diese Befehlszeilenoption kann auch benutzt werden, um die -@emph{kombinierten} Suchpfade mehrerer Profile zu berechnen. Betrachten Sie -dieses Beispiel: - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -Der letzte Befehl oben meldet auch die Definition der Umgebungsvariablen -@code{GUILE_LOAD_PATH}, obwohl für sich genommen weder @file{foo} noch -@file{bar} zu dieser Empfehlung führen würden. - - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Auf @var{Profil} anstelle des Standardprofils des Benutzers arbeiten. - -@cindex Kollisionen, in einem Profil -@cindex Paketkollisionen in Profilen -@cindex Profilkollisionen -@item --allow-collisions -Kollidierende Pakete im neuen Profil zulassen. Benutzung auf eigene Gefahr! - -Standardmäßig wird @command{guix package} @dfn{Kollisionen} als Fehler -auffassen und melden. Zu Kollisionen kommt es, wenn zwei oder mehr -verschiedene Versionen oder Varianten desselben Pakets im Profil landen. - -@item --bootstrap -Erstellt das Profil mit dem Bootstrap-Guile. Diese Option ist nur für -Entwickler der Distribution nützlich. - -@end table - -Zusätzlich zu diesen Aktionen unterstützt @command{guix package} folgende -Befehlszeilenoptionen, um den momentanen Zustand eines Profils oder die -Verfügbarkeit von Paketen nachzulesen: - -@table @option - -@item --search=@var{Regexp} -@itemx -s @var{Regexp} -@cindex Suche nach Paketen -List the available packages whose name, synopsis, or description matches -@var{regexp} (in a case-insensitive fashion), sorted by relevance. Print -all the metadata of matching packages in @code{recutils} format (@pxref{Top, -GNU recutils databases,, recutils, GNU recutils manual}). - -So können bestimmte Felder mit dem Befehl @command{recsel} extrahiert -werden, zum Beispiel: - -@example -$ guix package -s malloc | recsel -p name,version,relevance -name: jemalloc -version: 4.5.0 -relevance: 6 - -name: glibc -version: 2.25 -relevance: 1 - -name: libgc -version: 7.6.0 -relevance: 1 -@end example - -Ebenso kann der Name aller zu den Bedingungen der GNU@tie{}LGPL, Version 3, -verfügbaren Pakete ermittelt werden: - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -Es ist auch möglich, Suchergebnisse näher einzuschränken, indem Sie -@code{-s} mehrmals übergeben. Zum Beispiel liefert folgender Befehl eines -Liste von Brettspielen: - -@example -$ guix package -s '\<board\>' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -Würden wir @code{-s game} weglassen, bekämen wir auch Software-Pakete -aufgelistet, die mit »printed circuit boards« (elektronischen Leiterplatten) -zu tun haben; ohne die spitzen Klammern um @code{board} bekämen wir auch -Pakete, die mit »keyboards« (Tastaturen, oder musikalischen Keyboard) zu tun -haben. - -Es ist Zeit für ein komplexeres Beispiel. Folgender Befehl sucht -kryptographische Bibliotheken, filtert Haskell-, Perl-, Python- und -Ruby-Bibliotheken heraus und gibt Namen und Zusammenfassung passender Pakete -aus: - -@example -$ guix package -s crypto -s library | \ - recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis -@end example - -@noindent -@xref{Selection Expressions,,, recutils, GNU recutils manual} enthält -weitere Informationen über @dfn{Auswahlausdrücke} mit @code{recsel -e}. - -@item --show=@var{Paket} -Zeigt Details über das @var{Paket} aus der Liste verfügbarer Pakete, im -@code{recutils}-Format (@pxref{Top, GNU recutils databases,, recutils, GNU -recutils manual}). - -@example -$ guix package --show=python | recsel -p name,version -name: python -version: 2.7.6 - -name: python -version: 3.3.5 -@end example - -Sie können auch den vollständigen Namen eines Pakets angeben, um Details nur -über diese Version angezeigt zu bekommen: -@example -$ guix package --show=python@@3.4 | recsel -p name,version -name: python -version: 3.4.3 -@end example - - - -@item --list-installed[=@var{Regexp}] -@itemx -I [@var{Regexp}] -Listet die derzeit installierten Pakete im angegebenen Profil auf, die -zuletzt installierten Pakete zuletzt. Wenn ein regulärer Ausdruck -@var{Regexp} angegeben wird, werden nur installierte Pakete aufgeführt, -deren Name zu @var{Regexp} passt. - -Zu jedem installierten Paket werden folgende Informationen angezeigt, durch -Tabulatorzeichen getrennt: der Paketname, die Version als Zeichenkette, -welche Teile des Pakets installiert sind (zum Beispiel @code{out}, wenn die -Standard-Paketausgabe installiert ist, @code{include}, wenn seine Header -installiert sind, usw.) und an welchem Pfad das Paket im Store zu finden -ist. - -@item --list-available[=@var{Regexp}] -@itemx -A [@var{Regexp}] -Listet Pakete auf, die in der aktuell installierten Distribution dieses -Systems verfügbar sind (@pxref{GNU-Distribution}). Wenn ein regulärer -Ausdruck @var{Regexp} angegeben wird, werden nur Pakete aufgeführt, deren -Name zum regulären Ausdruck @var{Regexp} passt. - -Zu jedem Paket werden folgende Informationen getrennt durch Tabulatorzeichen -ausgegeben: der Name, die Version als Zeichenkette, die Teile des Programms -(@pxref{Pakete mit mehreren Ausgaben.}) und die Stelle im Quellcode, an der -das Paket definiert ist. - -@item --list-generations[=@var{Muster}] -@itemx -l [@var{Muster}] -@cindex Generationen -Liefert eine Liste der Generationen zusammen mit dem Datum, an dem sie -erzeugt wurden; zu jeder Generation werden zudem die installierten Pakete -angezeigt, zuletzt installierte Pakete zuletzt. Beachten Sie, dass die -nullte Generation niemals angezeigt wird. - -Zu jedem installierten Paket werden folgende Informationen durch -Tabulatorzeichen getrennt angezeigt: der Name des Pakets, die Version als -Zeichenkette, welcher Teil des Pakets installiert ist (@pxref{Pakete mit mehreren Ausgaben.}) und an welcher Stelle sich das Paket im Store befindet. - -Wenn ein @var{Muster} angegeben wird, liefert der Befehl nur dazu passende -Generationen. Gültige Muster sind zum Beispiel: - -@itemize -@item @emph{Ganze Zahlen und kommagetrennte ganze Zahlen}. Beide Muster bezeichnen -Generationsnummern. Zum Beispiel liefert @code{--list-generations=1} die -erste Generation. - -Durch @code{--list-generations=1,8,2} werden drei Generationen in der -angegebenen Reihenfolge angezeigt. Weder Leerzeichen noch ein Komma am -Schluss der Liste ist erlaubt. - -@item @emph{Bereiche}. @code{--list-generations=2..9} gibt die -angegebenen Generationen und alles dazwischen aus. Beachten Sie, dass der -Bereichsanfang eine kleinere Zahl als das Bereichsende sein muss. - -Sie können auch kein Bereichsende angeben, zum Beispiel liefert -@code{--list-generations=2..} alle Generationen ab der zweiten. - -@item @emph{Zeitdauern}. Sie können auch die letzten @emph{N}@tie{}Tage, Wochen -oder Monate angeben, indem Sie eine ganze Zahl gefolgt von jeweils »d«, »w« -oder »m« angeben (dem ersten Buchstaben der Maßeinheit der Dauer im -Englischen). Zum Beispiel listet @code{--list-generations=20d} die -Generationen auf, die höchstens 20 Tage alt sind. -@end itemize - -@item --delete-generations[=@var{Muster}] -@itemx -d [@var{Muster}] -Wird kein @var{Muster} angegeben, werden alle Generationen außer der -aktuellen entfernt. - -Dieser Befehl akzeptiert dieselben Muster wie -@option{--list-generations}. Wenn ein @var{Muster} angegeben wird, werden -die passenden Generationen gelöscht. Wenn das @var{Muster} für eine -Zeitdauer steht, werden diejenigen Generationen gelöscht, die @emph{älter} -als die angegebene Dauer sind. Zum Beispiel löscht -@code{--delete-generations=1m} die Generationen, die mehr als einen Monat -alt sind. - -Falls die aktuelle Generation zum Muster passt, wird sie @emph{nicht} -gelöscht. Auch die nullte Generation wird niemals gelöscht. - -Beachten Sie, dass Sie auf gelöschte Generationen nicht zurückwechseln -können. Dieser Befehl sollte also nur mit Vorsicht benutzt werden. - -@end table - -Zu guter Letzt können Sie, da @command{guix package} Erstellungsprozesse zu -starten vermag, auch alle gemeinsamen Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}) verwenden. Auch Paketumwandlungsoptionen wie -@option{--with-source} sind möglich (@pxref{Paketumwandlungsoptionen}). Beachten Sie jedoch, dass die verwendeten -Paketumwandlungsoptionen verloren gehen, nachdem Sie die Pakete aktualisiert -haben. Damit Paketumwandlungen über Aktualisierungen hinweg erhalten -bleiben, sollten Sie Ihre eigene Paketvariante in einem Guile-Modul -definieren und zur Umgebungsvariablen @code{GUIX_PACKAGE_PATH} hinzufügen -(@pxref{Pakete definieren}). - -@node Substitute -@section Substitute - -@cindex Substitute -@cindex vorerstellte Binärdateien -Guix kann transparent Binär- oder Quelldateien ausliefern. Das heißt, Dinge -können sowohl lokal erstellt, als auch als vorerstellte Objekte von einem -Server heruntergeladen werden, oder beides gemischt. Wir bezeichnen diese -vorerstellten Objekte als @dfn{Substitute} — sie substituieren lokale -Erstellungsergebnisse. In vielen Fällen geht das Herunterladen eines -Substituts wesentlich schneller, als Dinge lokal zu erstellen. - -Substitute können alles sein, was das Ergebnis einer Ableitungserstellung -ist (@pxref{Ableitungen}). Natürlich sind sie üblicherweise vorerstellte -Paket-Binärdateien, aber wenn zum Beispiel ein Quell-Tarball das Ergebnis -einer Ableitungserstellung ist, kann auch er als Substitut verfügbar sein. - -@menu -* Offizieller Substitut-Server:: Eine besondere Quelle von Substituten. -* Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet. -* Substitutauthentifizierung:: Wie Guix Substitute verifiziert. -* Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen. -* Fehler bei der Substitution:: Was passiert, wenn die Substitution - fehlschlägt. -* Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären - Blob trauen? -@end menu - -@node Offizieller Substitut-Server -@subsection Offizieller Substitut-Server - -@cindex Hydra -@cindex Build-Farm -The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official -build farm that builds packages from Guix continuously for some -architectures, and makes them available as substitutes. This is the default -source of substitutes; it can be overridden by passing the -@option{--substitute-urls} option either to @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) or -to client tools such as @command{guix package} -(@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). - -Substitut-URLs können entweder HTTP oder HTTPS sein. HTTPS wird empfohlen, -weil die Kommunikation verschlüsselt ist; umgekehrt kann bei HTTP die -Kommunikation belauscht werden, wodurch der Angreifer zum Beispiel erfahren -könnte, ob Ihr System über noch nicht behobene Sicherheitsschwachstellen -verfügt. - -Substitute von der offiziellen Build-Farm sind standardmäßig erlaubt, wenn -Sie die Guix-System-Distribution verwenden (@pxref{GNU-Distribution}). Auf -Fremddistributionen sind sie allerdings standardmäßig ausgeschaltet, solange -Sie sie nicht ausdrücklich in einem der empfohlenen Installationsschritte -erlaubt haben (@pxref{Installation}). Die folgenden Absätze beschreiben, wie -Sie Substitute für die offizielle Build-Farm an- oder ausschalten; dieselbe -Prozedur kann auch benutzt werden, um Substitute für einen beliebigen -anderen Substitutsserver zu erlauben. - -@node Substitut-Server autorisieren -@subsection Substitut-Server autorisieren - -@cindex Sicherheit -@cindex Substitute, deren Autorisierung -@cindex Access Control List (ACL), für Substitute -@cindex ACL (Access Control List), für Substitute -To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} -or a mirror thereof, you must add its public key to the access control list -(ACL) of archive imports, using the @command{guix archive} command -(@pxref{Aufruf von guix archive}). Doing so implies that you trust -@code{@value{SUBSTITUTE-SERVER}} to not be compromised and to serve genuine -substitutes. - -The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with -Guix, in @code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where -@var{prefix} is the installation prefix of Guix. If you installed Guix from -source, make sure you checked the GPG signature of -@file{guix-@value{VERSION}.tar.gz}, which contains this public key file. -Then, you can run something like this: - -@example -# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Anmerkung -Similarly, the @file{hydra.gnu.org.pub} file contains the public key of an -independent build farm also run by the project, reachable at -@indicateurl{https://mirror.hydra.gnu.org}. -@end quotation - -Sobald es eingerichtet wurde, sollte sich die Ausgabe eines Befehls wie -@code{guix build} von so etwas: - -@example -$ guix build emacs --dry-run -Folgende Ableitungen würden erstellt: - /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv - /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv - /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv - /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv -@dots{} -@end example - -@noindent -in so etwas verwandeln: - -@example -$ guix build emacs --dry-run -112.3 MB würden heruntergeladen: - /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 - /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d - /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 - /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 -@dots{} -@end example - -@noindent -This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are -usable and will be downloaded, when possible, for future builds. - -@cindex Substitute, wie man sie ausschaltet -Der Substitutsmechanismus kann global ausgeschaltet werden, indem Sie dem -@code{guix-daemon} beim Starten die Befehlszeilenoption -@code{--no-substitutes} übergeben (@pxref{Aufruf des guix-daemon}). Er kann -auch temporär ausgeschaltet werden, indem Sie @code{--no-substitutes} an -@command{guix package}, @command{guix build} und andere -Befehlszeilenwerkzeuge übergeben. - -@node Substitutauthentifizierung -@subsection Substitutauthentifizierung - -@cindex digitale Signaturen -Guix erkennt, wenn ein verfälschtes Substitut benutzt würde, und meldet -einen Fehler. Ebenso werden Substitute ignoriert, die nich signiert sind, -oder nicht mit einem in der ACL aufgelisteten Schlüssel signiert sind. - -Es gibt nur eine Ausnahme: Wenn ein unautorisierter Server Substitute -anbietet, die @emph{Bit für Bit identisch} mit denen von einem autorisierten -Server sind, können sie auch vom unautorisierten Server heruntergeladen -werden. Zum Beispiel, angenommen wir haben zwei Substitutserver mit dieser -Befehlszeilenoption ausgewählt: - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex Reproduzierbare Erstellungen -Wenn in der ACL nur der Schlüssel für @code{b.example.org} aufgeführt wurde, -aber @code{a.example.org} @emph{exakt dieselben} Substitute anbietet, wird -Guix auch Substitute von @code{a.example.org} herunterladen, weil es in der -Liste zuerst kommt und als Spiegelserver für @code{b.example.org} aufgefasst -werden kann. In der Praxis haben unabhängige Maschinen bei der Erstellung -normalerweise dieselben Binärdateien als Ergebnis, dank bit-reproduzierbarer -Erstellungen (siehe unten). - -Wenn Sie HTTPS benutzen, wird das X.509-Zertifikat des Servers @emph{nicht} -validiert (mit anderen Worten, die Identität des Servers wird nicht -authentifiziert), entgegen dem, was HTTPS-Clients wie Web-Browser -normalerweise tun. Da Guix Substitutinformationen selbst überprüft, wie oben -erklärt, wäre es unnötig (wohingegen mit X.509-Zertifikaten geprüft wird, ob -ein Domain-Name zu öffentlichen Schlüsseln passt). - -@node Proxy-Einstellungen -@subsection Proxy-Einstellungen - -@vindex http_proxy -Substitute werden über HTTP oder HTTPS heruntergeladen. Die -Umgebungsvariable @code{http_proxy} kann in der Umgebung von -@command{guix-daemon} definiert werden und wirkt sich dann auf das -Herunterladen von Substituten aus. Beachten Sie, dass der Wert von -@code{http_proxy} in der Umgebung, in der @command{guix build}, -@command{guix package} und andere Client-Befehle ausgeführt werden, -@emph{keine Rolle spielt}. - -@node Fehler bei der Substitution -@subsection Fehler bei der Substitution - -Selbst wenn ein Substitut für eine Ableitung verfügbar ist, schlägt die -versuchte Substitution manchmal fehl. Das kann aus vielen Gründen geschehen: -die Substitutsserver könnten offline sein, das Substitut könnte kürzlich -gelöscht worden sein, die Netzwerkverbindunge könnte unterbrochen worden -sein, usw. - -Wenn Substitute aktiviert sind und ein Substitut für eine Ableitung zwar -verfügbar ist, aber die versuchte Substitution fehlschlägt, kann Guix -versuchen, die Ableitung lokal zu erstellen, je nachdem, ob -@code{--fallback} übergeben wurde (@pxref{fallback-option,, common build -option @code{--fallback}}). Genauer gesagt, wird keine lokale Erstellung -durchgeführt, solange kein @code{--fallback} angegeben wurde, und die -Ableitung wird als Fehlschlag angesehen. Wenn @code{--fallback} übergeben -wurde, wird Guix versuchen, die Ableitung lokal zu erstellen, und ob die -Ableitung erfolgreich ist oder nicht, hängt davon ab, ob die lokale -Erstellung erfolgreich ist oder nicht. Beachten Sie, dass, falls Substitute -ausgeschaltet oder erst gar kein Substitut verfügbar ist, @emph{immer} eine -lokale Erstellung durchgeführt wird, egal ob @code{--fallback} übergeben -wurde oder nicht. - -Um eine Vorstellung zu bekommen, wieviele Substitute gerade verfügbar sind, -können Sie den Befehl @command{guix weather} benutzen (@pxref{Aufruf von guix weather}). Dieser Befehl zeigt Statistiken darüber an, wie es um die von -einem Server verfügbaren Substitute steht. - -@node Vom Vertrauen gegenüber Binärdateien -@subsection Vom Vertrauen gegenüber Binärdateien - -@cindex Vertrauen, gegenüber vorerstellten Binärdateien -Today, each individual's control over their own computing is at the mercy of -institutions, corporations, and groups with enough power and determination -to subvert the computing infrastructure and exploit its weaknesses. While -using @code{@value{SUBSTITUTE-SERVER}} substitutes can be convenient, we -encourage users to also build on their own, or even run their own build -farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an interesting -target. One way to help is by publishing the software you build using -@command{guix publish} so that others have one more choice of server to -download substitutes from (@pxref{Aufruf von guix publish}). - -Guix hat die richtigen Grundlagen, um die Reproduzierbarkeit von -Erstellungen zu maximieren (@pxref{Funktionalitäten}). In den meisten Fällen sollten -unabhängige Erstellungen eines bestimmten Pakets zu bitweise identischen -Ergebnissen führen. Wir können also mit Hilfe einer vielschichtigen Menge an -unabhängigen Paketerstellungen die Integrität unseres Systems besser -gewährleisten. Der Befehl @command{guix challenge} hat das Ziel, Nutzern zu -ermöglichen, Substitutserver zu beurteilen, und Entwickler dabei zu -unterstützen, nichtdeterministische Paketerstellungen zu finden -(@pxref{Aufruf von guix challenge}). Ebenso ermöglicht es die -Befehlszeilenoption @option{--check} von @command{guix build}, dass Nutzer -bereits installierte Substitute auf Echtheit zu prüfen, indem sie lokal -nachgebaut werden (@pxref{build-check, @command{guix build --check}}). - -In Zukunft wollen wir, dass Guix Binärdateien an und von Nutzern -peer-to-peer veröffentlichen kann. Wenn Sie mit uns dieses Projekt -diskuttieren möchten, kommen Sie auf unsere Mailing-Liste -@email{guix-devel@@gnu.org}. - -@node Pakete mit mehreren Ausgaben. -@section Pakete mit mehreren Ausgaben. - -@cindex mehrere Ausgaben, bei Paketen -@cindex Paketausgaben -@cindex Ausgaben - -Oft haben in Guix definierte Pakete eine einzige @dfn{Ausgabe} — d.h. aus -dem Quellpaket entsteht genau ein Verzeichnis im Store. Wenn Sie -@command{guix package -i glibc} ausführen, wird die Standard-Paketausgabe -des GNU-libc-Pakets installiert; die Standardausgabe wird @code{out} -genannt, aber ihr Name kann weggelassen werden, wie sie an obigem Befehl -sehen. In diesem speziellen Fall enthält die Standard-Paketausgabe von -@code{glibc} alle C-Headerdateien, gemeinsamen Bibliotheken (»Shared -Libraries«), statische Bibliotheken (»Static Libraries«), Dokumentation für -Info sowie andere zusätzliche Dateien. - -Manchmal ist es besser, die verschiedenen Arten von Dateien, die aus einem -einzelnen Quellpaket hervorgehen, in getrennte Ausgaben zu unterteilen. Zum -Beispiel installiert die GLib-C-Bibliothek (die von GTK und damit -zusammenhängenden Paketen benutzt wird) mehr als 20 MiB an HTML-Seiten mit -Referenzdokumentation. Um den Nutzern, die das nicht brauchen, Platz zu -sparen, wird die Dokumentation in einer separaten Ausgabe abgelegt, genannt -@code{doc}. Um also die Hauptausgabe von GLib zu installieren, zu der alles -außer der Dokumentation gehört, ist der Befehl: - -@example -guix package -i glib -@end example - -@cindex Dokumentation -Der Befehl, um die Dokumentation zu installieren, ist: - -@example -guix package -i glib:doc -@end example - -Manche Pakete installieren Programme mit unterschiedlich großem -»Abhängigkeiten-Fußabdruck«. Zum Beispiel installiert das Paket WordNet -sowohl Befehlszeilenwerkzeuge als auch grafische Benutzerschnittstellen -(GUIs). Erstere hängen nur von der C-Bibliothek ab, während Letztere auch -von Tcl/Tk und den zu Grunde liegenden X-Bibliotheken abhängen. Jedenfalls -belassen wir deshalb die Befehlszeilenwerkzeuge in der -Standard-Paketausgabe, während sich die GUIs in einer separaten Ausgabe -befinden. So können Benutzer, die die GUIs nicht brauchen, Platz sparen. Der -Befehl @command{guix size} kann dabei helfen, solche Situationen zu erkennen -(@pxref{Aufruf von guix size}). @command{guix graph} kann auch helfen -(@pxref{Aufruf von guix graph}). - -In der GNU-Distribution gibt es viele solche Pakete mit mehreren -Ausgaben. Andere Konventionen für Ausgabenamen sind zum Beispiel @code{lib} -für Bibliotheken und eventuell auch ihre Header-Dateien,, @code{bin} für -eigenständige Programme und @code{debug} für Informationen zur -Fehlerbehandlung (@pxref{Dateien zur Fehlersuche installieren}). Die Ausgaben eines -Pakets stehen in der dritten Spalte der Anzeige von @command{guix package ---list-available} (@pxref{Aufruf von guix package}). - - -@node Aufruf von guix gc -@section @command{guix gc} aufrufen - -@cindex Müllsammler -@cindex Plattenspeicher -Pakete, die zwar installiert sind, aber nicht benutzt werden, können vom -@dfn{Müllsammler} entfernt werden. Mit dem Befehl @command{guix gc} können -Benutzer den Müllsammler ausdrücklich aufrufen, um Speicher im Verzeichnis -@file{/gnu/store} freizugeben. Dies ist der @emph{einzige} Weg, Dateien aus -@file{/gnu/store} zu entfernen — das manuelle Entfernen von Dateien kann den -Store irreparabel beschädigen! - -@cindex GC-Wurzeln -@cindex Müllsammlerwurzeln -Der Müllsammler kennt eine Reihe von @dfn{Wurzeln}: Jede Datei in -@file{/gnu/store}, die von einer Wurzel aus erreichbar ist, gilt als -@dfn{lebendig} und kann nicht entfernt werden; jede andere Datei gilt als -@dfn{tot} und ist ein Kandidat, gelöscht zu werden. Die Menge der -Müllsammlerwurzeln (kurz auch »GC-Wurzeln«, von englisch »Garbage -Collector«) umfasst Standard-Benutzerprofile; standardmäßig werden diese -Müllsammlerwurzeln durch symbolische Verknüpfungen in -@file{/var/guix/gcroots} dargestellt. Neue Müllsammlerwurzeln können zum -Beispiel mit @command{guix build --root} festgelegt werden (@pxref{Aufruf von guix build}). - -Bevor Sie mit @code{guix gc --collect-garbage} Speicher freimachen, wollen -Sie vielleicht alte Generationen von Benutzerprofilen löschen, damit alte -Paketerstellungen von diesen Generationen entfernt werden können. Führen Sie -dazu @code{guix package --delete-generations} aus (@pxref{Aufruf von guix package}). - -Unsere Empfehlung ist, dass Sie den Müllsammler regelmäßig laufen lassen und -wenn Sie wenig freien Speicherplatz zur Verfügung haben. Um zum Beispiel -sicherzustellen, dass Sie mindestens 5@tie{}GB auf Ihrer Platte zur -Verfügung haben, benutzen Sie einfach: - -@example -guix gc -F 5G -@end example - -It is perfectly safe to run as a non-interactive periodic job -(@pxref{Geplante Auftragsausführung}, for how to set up such a job). Running -@command{guix gc} with no arguments will collect as much garbage as it can, -but that is often inconvenient: you may find yourself having to rebuild or -re-download software that is ``dead'' from the GC viewpoint but that is -necessary to build other pieces of software---e.g., the compiler tool chain. - -Der Befehl @command{guix gc} hat drei Arbeitsmodi: Er kann benutzt werden, -um als Müllsammler tote Dateien zu entfernen (das Standardverhalten), um -ganz bestimmte, angegebene Datein zu löschen (mit der Befehlszeilenoption -@code{--delete}), um Müllsammlerinformationen auszugeben oder -fortgeschrittenere Anfragen zu verarbeiten. Die -Müllsammler-Befehlszeilenoptionen sind wie folgt: - -@table @code -@item --collect-garbage[=@var{Minimum}] -@itemx -C [@var{Minimum}] -Lässt Müll sammeln — z.B. nicht erreichbare Dateien in @file{/gnu/store} und -seinen Unterverzeichnissen. Wird keine andere Befehlszeilenoption angegeben, -wird standardmäßig diese durchgeführt. - -Wenn ein @var{Minimum} angegeben wurde, hört der Müllsammler auf, sobald -@var{Minimum} Bytes gesammelt wurden. Das @var{Minimum} kann die Anzahl der -Bytes bezeichnen oder mit einer Einheit als Suffix versehen sein, wie etwa -@code{MiB} für Mebibytes und @code{GB} für Gigabytes (@pxref{Block size, -size specifications,, coreutils, GNU Coreutils}). - -Wird kein @var{Minimum} angegeben, sammelt der Müllsammler allen Müll. - -@item --free-space=@var{Menge} -@itemx -F @var{Menge} -Sammelt Müll, bis die angegebene @var{Menge} an freiem Speicher in -@file{/gnu/store} zur Verfügung steht, falls möglich; die @var{Menge} ist -eine Speichergröße wie @code{500MiB}, wie oben beschrieben. - -Wenn die angegebene @var{Menge} oder mehr bereits in @file{/gnu/store} frei -verfügbar ist, passiert nichts. - -@item --delete -@itemx -d -Versucht, alle als Argumente angegebenen Dateien oder Verzeichnisse im Store -zu löschen. Dies schlägt fehl, wenn manche der Dateien oder Verzeichnisse -nicht im Store oder noch immer lebendig sind. - -@item --list-failures -Store-Objekte auflisten, die zwischengespeicherten Erstellungsfehlern -entsprechen. - -Hierbei wird nichts ausgegeben, sofern der Daemon nicht mit -@option{--cache-failures} gestartet wurde (@pxref{Aufruf des guix-daemon, -@option{--cache-failures}}). - -@item --clear-failures -Die angegebenen Store-Objekte aus dem Zwischenspeicher für fehlgeschlagene -Erstellungen entfernen. - -Auch diese Option macht nur Sinn, wenn der Daemon mit -@option{--cache-failures} gestartet wurde. Andernfalls passiert nichts. - -@item --list-dead -Zeigt die Liste toter Dateien und Verzeichnisse an, die sich noch im Store -befinden — das heißt, Dateien, die von keiner Wurzel mehr erreichbar sind. - -@item --list-live -Zeige die Liste lebendiger Store-Dateien und -Verzeichnisse. - -@end table - -Außerdem können Referenzen unter bestehenden Store-Dateien gefunden werden: - -@table @code - -@item --references -@itemx --referrers -@cindex Paketabhängigkeiten -Listet die referenzierten bzw. sie referenzierenden Objekte der angegebenen -Store-Dateien auf. - -@item --requisites -@itemx -R -@cindex Abschluss -Listet alle Voraussetzungen der als Argumente übergebenen Store-Dateien -auf. Voraussetzungen sind die Store-Dateien selbst, ihre Referenzen sowie -die Referenzen davon, rekursiv. Mit anderen Worten, die zurückgelieferte -Liste ist der @dfn{transitive Abschluss} dieser Store-Dateien. - -Der Abschnitt @xref{Aufruf von guix size} erklärt ein Werkzeug, um den -Speicherbedarf des Abschlusses eines Elements zu ermitteln. Siehe -@xref{Aufruf von guix graph} für ein Werkzeug, um den Referenzgraphen zu -veranschaulichen. - -@item --derivers -@cindex Ableitung -Liefert die Ableitung(en), die zu den angegebenen Store-Objekten führen -(@pxref{Ableitungen}). - -Zum Beispiel liefert dieser Befehl: - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -die @file{.drv}-Datei(en), die zum in Ihrem Profil installierten -@code{emacs}-Paket führen. - -Beachten Sie, dass es auch sein kann, dass keine passenden -@file{.drv}-Dateien existieren, zum Beispiel wenn diese Dateien bereits dem -Müllsammler zum Opfer gefallen sind. Es kann auch passieren, dass es mehr -als eine passende @file{.drv} gibt, bei Ableitungen mit fester Ausgabe. -@end table - -Zuletzt können Sie mit folgenden Befehlszeilenoptionen die Integrität des -Stores prüfen und den Plattenspeicherverbrauch im Zaum halten. - -@table @option - -@item --verify[=@var{Optionen}] -@cindex Integrität, des Stores -@cindex Integritätsprüfung -Die Integrität des Stores verifizieren - -Standardmäßig wird sichergestellt, dass alle Store-Objekte, die in der -Datenbank des Daemons als gültig markiert wurden, auch tatsächlich in -@file{/gnu/store} existieren. - -Wenn angegeben, müssen die @var{Optionen} eine kommagetrennte Liste aus -mindestens einem der Worte @code{contents} und @code{repair} sein. - -Wenn Sie @option{--verify=contents} übergeben, berechnet der Daemon den Hash -des Inhalts jedes Store-Objekts und vergleicht ihn mit dem Hash in der -Datenbank. Sind die Hashes ungleich, wird eine Datenbeschädigung -gemeldet. Weil dabei @emph{alle Dateien im Store} durchlaufen werden, kann -der Befehl viel Zeit brauchen, besonders auf Systemen mit langsamer Platte. - -@cindex Store, reparieren -@cindex Datenbeschädigung, Behebung -Mit @option{--verify=repair} oder @option{--verify=contents,repair} versucht -der Daemon, beschädigte Store-Objekte zu reparieren, indem er Substitute für -selbige herunterlädt (@pxref{Substitute}). Weil die Reparatur nicht atomar -und daher womöglich riskant ist, kann nur der Systemadministrator den Befehl -benutzen. Eine weniger aufwendige Alternative, wenn Sie wissen, welches -Objekt beschädigt ist, ist, @command{guix build --repair} zu benutzen -(@pxref{Aufruf von guix build}). - -@item --optimize -@cindex Deduplizieren -Den Store durch Nutzung harter Verknüpfungen für identische Dateien -optimieren — mit anderen Worten wird der Store @dfn{dedupliziert}. - -Der Daemon führt Deduplizierung automatisch nach jeder erfolgreichen -Erstellung und jedem Importieren eines Archivs durch, sofern er nicht mit -@code{--disable-deduplication} (@pxref{Aufruf des guix-daemon, -@code{--disable-deduplication}}) gestartet wurde. Diese Befehlszeilenoption -brauchen Sie also in erster Linie dann, wenn der Daemon zuvor mit -@code{--disable-deduplication} gestartet worden ist. - -@end table - -@node Aufruf von guix pull -@section @command{guix pull} aufrufen - -@cindex Aktualisieren von Guix -@cindex Updaten von Guix -@cindex @command{guix pull} -@cindex pull -Nach der Installation oder Aktualisierung wird stets die neueste Version von -Paketen verwendet, die in der aktuell installierten Distribution verfügbar -ist. Um die Distribution und die Guix-Werkzeuge zu aktualisieren, führen Sie -@command{guix pull} aus. Der Befehl lädt den neuesten Guix-Quellcode -einschließlich Paketbeschreibungen herunter und installiert ihn. Quellcode -wird aus einem @uref{https://git-scm.com, Git}-Repository geladen, -standardmäßig dem offiziellen Repository von GNU@tie{}Guix, was Sie aber -auch ändern können. - -Danach wird @command{guix package} Pakete und ihre Versionen entsprechend -der gerade heruntergeladenen Kopie von Guix benutzen. Nicht nur das, auch -alle Guix-Befehle und Scheme-Module werden aus der neuesten Version von Guix -kommen. Neue @command{guix}-Unterbefehle, die durch die Aktualisierung -hinzugekommen sind, werden also auch verfügbar. - -Jeder Nutzer kann seine Kopie von Guix mittels @command{guix pull} -aktualisieren, wodurch sich nur für den Nutzer etwas verändert, der -@command{guix pull} ausgeführt hat. Wenn also zum Beispiel der -Administratornutzer @code{root} den Befehl @command{guix pull} ausführt, hat -das keine Auswirkungen auf die für den Benutzer @code{alice} sichtbare -Guix-Version, und umgekehrt. - -Das Ergebnis von @command{guix pull} ist ein als -@file{~/.config/guix/current} verfügbares @dfn{Profil} mit dem neuesten -Guix. Stellen Sie sicher, dass es am Anfang Ihres Suchpfades steht, damit -Sie auch wirklich das neueste Guix und sein Info-Handbuch sehen -(@pxref{Dokumentation}): - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -Die Befehlszeilenoption @code{--list-generations} oder kurz @code{-l} listet -ältere von @command{guix pull} erzeugte Generationen auf, zusammen mit -Informationen zu deren Provenienz. - -@example -$ guix pull -l -Generation 1 Jun 10 2018 00:18:18 - guix 65956ad - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe - -Generation 2 Jun 11 2018 11:02:49 - guix e0cc7f6 - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d - 2 new packages: keepalived, libnfnetlink - 6 packages upgraded: emacs-nix-mode@@2.0.4, - guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac, - heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4 - -Generation 3 Jun 13 2018 23:31:07 (current) - guix 844cc1c - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: 844cc1c8f394f03b404c5bb3aee086922373490c - 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{} - 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} -@end example - -Im Abschnitt @ref{Aufruf von guix describe, @command{guix describe}} werden -andere Möglichkeiten erklärt, sich den momentanen Zustand von Guix -beschreiben zu lassen. - -Das Profil @code{~/.config/guix/current} verhält sich genau wie jedes andere -Profil, das von @command{guix package} erzeugt wurde (@pxref{Aufruf von guix package}). Das bedeutet, Sie können seine Generationen auflisten und es auf -die vorherige Generation — also das vorherige Guix — zurücksetzen und so -weiter: - -@example -$ guix package -p ~/.config/guix/current --roll-back -switched from generation 3 to 2 -$ guix package -p ~/.config/guix/current --delete-generations=1 -deleting /var/guix/profiles/per-user/charlie/current-guix-1-link -@end example - -Der Befehl @command{guix pull} wird in der Regel ohne Befehlszeilenargumente -aufgerufen, aber er versteht auch folgende Befehlszeilenoptionen: - -@table @code -@item --url=@var{URL} -@itemx --commit=@var{Commit} -@itemx --branch=@var{Branch} -Code wird von der angegebenen @var{URL} für den angegebenen @var{Commit} -(eine gültige Commit-ID, dargestellt als hexadezimale Zeichenkette) oder -@var{Branch} heruntergeladen. - -@cindex @file{channels.scm}, Konfigurationsdatei -@cindex Konfigurationsdatei für Kanäle -Diese Befehlszeilenoptionen sind manchmal bequemer, aber Sie können Ihre -Konfiguration auch in der Datei @file{~/.config/guix/channels.scm} oder über -die Option @option{--channels} angeben (siehe unten). - -@item --channels=@var{Datei} -@itemx -C @var{Datei} -Die Liste der Kanäle aus der angegebenen @var{Datei} statt aus -@file{~/.config/guix/channels.scm} auslesen. Die @var{Datei} muss -Scheme-Code enthalten, der zu einer Liste von Kanalobjekten ausgewertet -wird. Siehe @xref{Kanäle} für nähere Informationen. - -@item --list-generations[=@var{Muster}] -@itemx -l [@var{Muster}] -Alle Generationen von @file{~/.config/guix/current} bzw., wenn ein -@var{Muster} angegeben wird, die dazu passenden Generationen auflisten. Die -Syntax für das @var{Muster} ist dieselbe wie bei @code{guix package ---list-generations} (@pxref{Aufruf von guix package}). - -Im Abschnitt @ref{Aufruf von guix describe, @command{guix describe}} wird eine -Möglichkeit erklärt, sich Informationen nur über die aktuelle Generation -anzeigen zu lassen. - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Auf @var{Profil} anstelle von @file{~/.config/guix/current} arbeiten. - -@item --dry-run -@itemx -n -Anzeigen, welche(r) Commit(s) für die Kanäle benutzt würde(n) und was -jeweils erstellt oder substituiert würde, ohne es tatsächlich durchzuführen. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@item --verbose -Ausführliche Informationen ausgeben und Erstellungsprotokolle auf der -Standardfehlerausgabe ausgeben. - -@item --bootstrap -Das neueste Guix mit dem Bootstrap-Guile erstellen. Diese -Befehlszeilenoption ist nur für Guix-Entwickler von Nutzen. -@end table - -Mit Hilfe von @dfn{Kanälen} können Sie bei @command{guix pull} anweisen, von -welchem Repository und welchem Branch Guix aktualisiert werden soll, sowie -von welchen @emph{weiteren} Repositorys Paketmodule bezogen werden -sollen. Im Abschnitt @xref{Kanäle} finden Sie nähere Informationen. - -Außerdem unterstützt @command{guix pull} alle gemeinsamen -Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}). - -@node Kanäle -@section Kanäle - -@cindex Kanäle -@cindex @file{channels.scm}, Konfigurationsdatei -@cindex Konfigurationsdatei für Kanäle -@cindex @command{guix pull}, Konfigurationsdatei -@cindex Konfiguration von @command{guix pull} -Guix und die Sammlung darin verfügbarer Pakete können Sie durch Ausführen -von @command{guix pull} aktualisieren (@pxref{Aufruf von guix pull}). Standardmäßig lädt @command{guix pull} Guix selbst vom offiziellen -Repository von GNU@tie{}Guix herunter und installiert es. Diesen Vorgang -können Sie anpassen, indem Sie @dfn{Kanäle} in der Datei -@file{~/.config/guix/channels.scm} angeben. Ein Kanal enthält eine Angabe -einer URL und eines Branches eines zu installierenden Git-Repositorys und -Sie können @command{guix pull} veranlassen, die Aktualisierungen von einem -oder mehreren Kanälen zu beziehen. Mit anderen Worten können Kanäle benutzt -werden, um Guix @emph{anzupassen} und zu @emph{erweitern}, wie wir im -Folgenden sehen werden. - -@subsection Einen eigenen Guix-Kanal benutzen - -Der Kanal namens @code{guix} gibt an, wovon Guix selbst — seine -Befehlszeilenwerkzeuge und seine Paketsammlung — heruntergeladen werden -sollten. Wenn Sie zum Beispiel mit Ihrer eigenen Kopie des Guix-Repositorys -arbeiten möchten und diese auf @code{example.org} zu finden ist, und zwar im -Branch namens @code{super-hacks}, dann schreiben Sie folgende Spezifikation -in @code{~/.config/guix/channels.scm}: - -@lisp -;; 'guix pull' mein eigenes Repository benutzen lassen. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -Ab dann wird @command{guix pull} seinen Code vom Branch @code{super-hacks} -des Repositorys auf @code{example.org} beziehen. - -@subsection Weitere Kanäle angeben - -@cindex Paketsammlung erweitern (Kanäle) -@cindex Eigene Pakete (Kanäle) -@cindex Kanäle, für eigene Pakete -Sie können auch @emph{weitere Kanäle} als Bezugsquelle angeben. Sagen wir, -Sie haben ein paar eigene Paketvarianten oder persönliche Pakete, von denen -Sie meinen, dass sie @emph{nicht} geeignet sind, ins Guix-Projekt selbst -aufgenommen zu werden, die Ihnen aber dennoch wie andere Pakete auf der -Befehlszeile zur Verfügung stehen sollen. Dann würden Sie zunächst Module -mit diesen Paketdefinitionen schreiben (@pxref{Paketmodule}) und diese -dann in einem Git-Repository verwalten, welches Sie selbst oder jeder andere -dann als zusätzlichen Kanal eintragen können, von dem Pakete geladen -werden. Klingt gut, oder? - -@c What follows stems from discussions at -@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Warnung -Bevor Sie, verehrter Nutzer, ausrufen: »Wow, das ist @emph{soooo coool}!«, -und Ihren eigenen Kanal der Welt zur Verfügung stellen, möchten wir Ihnen -auch ein paar Worte der Warnung mit auf den Weg geben: - -@itemize -@item -Bevor Sie einen Kanal veröffentlichen, überlegen Sie sich bitte erst, ob Sie -die Pakete nicht besser zum eigentlichen Guix-Projekt beisteuern -(@pxref{Mitwirken}). Das Guix-Projekt ist gegenüber allen Arten freier -Software offen und zum eigentlichen Guix gehörende Pakete stehen allen -Guix-Nutzern zur Verfügung, außerdem profitieren sie von Guix’ -Qualitätssicherungsprozess. - -@item -Wenn Sie Paketdefinitionen außerhalb von Guix betreuen, sehen wir -Guix-Entwickler es als @emph{Ihre Aufgabe an, deren Kompatibilität -sicherzstellen}. Bedenken Sie, dass Paketmodule und Paketdefinitionen nur -Scheme-Code sind, der verschiedene Programmierschnittstellen (APIs) -benutzt. Wir nehmen uns das Recht heraus, diese APIs jederzeit zu ändern, -damit wir Guix besser machen können, womöglich auf eine Art, wodurch Ihr -Kanal nicht mehr funktioniert. Wir ändern APIs nie einfach so, werden aber -auch @emph{nicht} versprechen, APIs nicht zu verändern. - -@item -Das bedeutet auch, dass Sie, wenn Sie einen externen Kanal verwenden und -dieser kaputt geht, Sie dies bitte @emph{den Autoren des Kanals} und nicht -dem Guix-Projekt melden. -@end itemize - -Wir haben Sie gewarnt! Allerdings denken wir auch, dass externe Kanäle eine -praktische Möglichkeit sind, die Paketsammlung von Guix zu ergänzen und Ihre -Verbesserungen mit anderen zu teilen, wie es dem Grundgedanken -@uref{https://www.gnu.org/philosophy/free-sw.html, freier Software} -entspricht. Bitte schicken Sie eine E-Mail an @email{guix-devel@@gnu.org}, -wenn Sie dies diskutieren möchten. -@end quotation - -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @emph{in addition} to the default Guix -channel(s): - -@vindex %default-channels -@lisp -;; Meine persönlichen Pakete zu denen von Guix dazunehmen. -(cons (channel - (name 'meine-persönlichen-pakete) - (url "https://example.org/personal-packages.git")) - %default-channels) -@end lisp - -@noindent -Note that the snippet above is (as always!)@: Scheme code; we use -@code{cons} to add a channel the list of channels that the variable -@code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,, -guile, GNU Guile Reference Manual}). With this file in place, @command{guix -pull} builds not only Guix but also the package modules from your own -repository. The result in @file{~/.config/guix/current} is the union of -Guix with your own package modules: - -@example -$ guix pull --list-generations -@dots{} -Generation 19 Aug 27 2018 16:20:48 - guix d894ab8 - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 - meine-persönlichen-pakete dd3df5e - repository URL: https://example.org/personal-packages.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: mein-gimp, mein-emacs-mit-coolen-features, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -Obige Ausgabe von @command{guix pull} zeigt an, dass Generation@tie{}19 -sowohl Guix als auch Pakete aus dem Kanal @code{meine-persönlichen-pakete} -enthält. Unter den aufgeführten neuen und aktualisierten Paketen kommen -vielleicht manche wie @code{mein-gimp} und -@code{mein-emacs-mit-coolen-features} aus @code{meine-persönlichen-pakete}, -während andere aus dem Standard-Guix-Kanal kommen. - -To create a channel, create a Git repository containing your own package -modules and make it available. The repository can contain anything, but a -useful channel will contain Guile modules that export packages. Once you -start using a channel, Guix will behave as if the root directory of that -channel's Git repository has been added to the Guile load path (@pxref{Load -Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel -contains a file at @file{my-packages/my-tools.scm} that defines a Guile -module, then the module will be available under the name @code{(my-packages -my-tools)}, and you will be able to use it like any other module -(@pxref{Module,,, guile, GNU Guile Reference Manual}). - -@cindex dependencies, channels -@cindex meta-data, channels -@subsection Declaring Channel Dependencies - -Channel authors may decide to augment a package collection provided by other -channels. They can declare their channel to be dependent on other channels -in a meta-data file @file{.guix-channel}, which is to be placed in the root -of the channel repository. - -The meta-data file should contain a simple S-expression like this: - -@lisp -(channel - (version 0) - (dependencies - (channel - (name some-collection) - (url "https://example.org/first-collection.git")) - (channel - (name some-other-collection) - (url "https://example.org/second-collection.git") - (branch "testing")))) -@end lisp - -In the above example this channel is declared to depend on two other -channels, which will both be fetched automatically. The modules provided by -the channel will be compiled in an environment where the modules of all -these declared channels are available. - -For the sake of reliability and maintainability, you should avoid -dependencies on channels that you don't control, and you should aim to keep -the number of dependencies to a minimum. - -@subsection Guix nachbilden - -@cindex Festsetzen, bei Kanälen -@cindex Nachbilden von Guix -@cindex Reproduzierbarkeit von Guix -Die Ausgabe von @command{guix pull --list-generations} oben zeigt genau, aus -welchen Commits diese Guix-Instanz erstellt wurde. Wir können Guix so zum -Beispiel auf einer anderen Maschine nachbilden, indem wir eine -Kanalspezifikation in @file{~/.config/guix/channels.scm} angeben, die auf -diese Commits »festgesetzt« ist. - -@lisp -;; Ganz bestimmte Commits der relevanten Kanäle installieren. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) - (channel - (name 'meine-persönlichen-pakete) - (url "https://example.org/personal-packages.git") - (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -Der Befehl @command{guix describe --format=channels} kann diese Kanalliste -sogar direkt erzeugen (@pxref{Aufruf von guix describe}). - -Somit läuft auf beiden Maschinen @emph{genau dasselbe Guix} und es hat -Zugang zu @emph{genau denselben Paketen}. Die Ausgabe von @command{guix -build gimp} auf der einen Maschine wird Bit für Bit genau dieselbe wie die -desselben Befehls auf der anderen Maschine sein. Das bedeutet auch, dass -beide Maschinen Zugang zum gesamten Quellcode von Guix und daher auch -transitiv Zugang zum Quellcode jedes davon definierten Pakets haben. - -Das verleiht Ihnen Superkräfte, mit denen Sie die Provenienz binärer -Artefakte sehr feinkörnig nachverfolgen können und Software-Umgebungen nach -Belieben nachbilden können. Sie können es als eine Art Fähigkeit zur -»Meta-Reproduzierbarkeit« auffassen, wenn Sie möchten. Der Abschnitt -@xref{Untergeordnete} beschreibt eine weitere Möglichkeit, diese Superkräfte zu -nutzen. - -@node Untergeordnete -@section Untergeordnete - -@c TODO: Remove this once we're more confident about API stability. -@quotation Anmerkung -Die hier beschriebenen Funktionalitäten sind in der Version @value{VERSION} -bloß eine »Technologie-Vorschau«, daher kann sich die Schnittstelle in -Zukunft noch ändern. -@end quotation - -@cindex Untergeordnete -@cindex Mischen von Guix-Versionen -Manchmal könnten Sie Pakete aus der gerade laufenden Fassung von Guix mit -denen mischen wollen, die in einer anderen Guix-Version verfügbar sind. -Guix-@dfn{Untergeordnete} ermöglichen dies, indem Sie verschiedene -Guix-Versionen beliebig mischen können. - -@cindex untergeordnete Pakete -Aus technischer Sicht ist ein »Untergeordneter« im Kern ein separater -Guix-Prozess, der über eine REPL (@pxref{Aufruf von guix repl}) mit Ihrem -Haupt-Guix-Prozess verbunden ist. Das Modul @code{(guix inferior)} -ermöglicht es Ihnen, Untergeordnete zu erstellen und mit ihnen zu -kommunizieren. Dadurch steht Ihnen auch eine hochsprachliche Schnittstelle -zur Verfügung, um die von einem Untergeordneten angebotenen Pakete zu -durchsuchen und zu verändern — @dfn{untergeordnete Pakete}. - -In Kombination mit Kanälen (@pxref{Kanäle}) bieten Untergeordnete eine -einfache Möglichkeit, mit einer anderen Version von Guix zu -interagieren. Nehmen wir zum Beispiel an, Sie wollen das aktuelle -@code{guile}-Paket in Ihr Profil installieren, zusammen mit dem -@code{guile-json}, wie es in einer früheren Guix-Version existiert hat — -vielleicht weil das neuere @code{guile-json} eine inkompatible API hat und -Sie daher Ihren Code mit der alten API benutzen möchten. Dazu könnten Sie -ein Manifest für @code{guix package --manifest} schreiben (@pxref{Aufruf von guix package}); in diesem Manifest würden Sie einen Untergeordneten für -diese alte Guix-Version erzeugen, für die Sie sich interessieren, und aus -diesem Untergeordneten das @code{guile-json}-Paket holen: - -@lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;für die Prozedur 'first' - -(define channels - ;; Dies ist die alte Version, aus der wir - ;; guile-json extrahieren möchten. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) - -(define inferior - ;; Ein Untergeordneter, der obige Version repräsentiert. - (inferior-for-channels channels)) - -;; Daraus erzeugen wir jetzt ein Manifest mit dem aktuellen -;; »guile«-Paket und dem alten »guile-json«-Paket. -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) -@end lisp - -Bei seiner ersten Ausführung könnte für @command{guix package --manifest} -erst der angegebene Kanal erstellt werden müssen, bevor der Untergeordnete -erstellt werden kann; nachfolgende Durchläufe sind wesentlich schneller, -weil diese Guix-Version bereits zwischengespeichert ist. - -Folgende Prozeduren werden im Modul @code{(guix inferior)} angeboten, um -einen Untergeordneten zu öffnen: - -@deffn {Scheme-Prozedur} inferior-for-channels @var{Kanäle} @ - [#:cache-directory] [#:ttl] Liefert einen Untergeordneten für die -@var{Kanäle}, einer Liste von Kanälen. Dazu wird der Zwischenspeicher im -Verzeichnis @var{cache-directory} benutzt, dessen Einträge nach @var{ttl} -Sekunden gesammelt werden dürfen. Mit dieser Prozedur wird eine neue -Verbindung zum Erstellungs-Daemon geöffnet. - -Als Nebenwirkung erstellt oder substituiert diese Prozedur unter Umständen -Binärdateien für die @var{Kanäle}, was einige Zeit in Anspruch nehmen kann. -@end deffn - -@deffn {Scheme-Prozedur} open-inferior @var{Verzeichnis} @ - [#:command "bin/guix"] Öffnet das untergeordnete Guix mit dem Befehl -@var{command} im angegebenen @var{Verzeichnis} durch Ausführung von -@code{@var{Verzeichnis}/@var{command} repl} oder entsprechend. Liefert -@code{#f}, wenn der Untergeordnete nicht gestartet werden konnte. -@end deffn - -@cindex untergeordnete Pakete -Die im Folgenden aufgeführten Prozeduren ermöglichen es Ihnen, -untergeordnete Pakete abzurufen und zu verändern. - -@deffn {Scheme-Prozedur} inferior-packages @var{Untergeordneter} -Liefert die Liste der Pakete in @var{Untergeordneter}. -@end deffn - -@deffn {Scheme-Prozedur} lookup-inferior-packages @var{Untergeordneter} @var{Name} @ - [@var{Version}] Liefert die sortierte Liste der untergeordneten Pakete in -@var{Untergeordneter}, die zum Muster @var{Name} in @var{Untergeordneter} -passen, dabei kommen höhere Versionsnummern zuerst. Wenn @var{Version} auf -wahr gesetzt ist, werden nur Pakete geliefert, deren Versionsnummer mit dem -Präfix @var{Version} beginnt. -@end deffn - -@deffn {Scheme-Prozedur} inferior-package? @var{Objekt} -Liefert wahr, wenn das @var{obj} ein Untergeordneter ist. -@end deffn - -@deffn {Scheme-Prozedur} inferior-package-name @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-version @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-synopsis @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-description @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-home-page @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-location @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-native-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-propagated-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-transitive-propagated-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-native-search-paths @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-transitive-native-search-paths @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-search-paths @var{Paket} -Diese Prozeduren sind das Gegenstück zu den Zugriffsmethoden des Verbunds -»package« für Pakete (@pxref{»package«-Referenz}). Die meisten davon -funktionieren durch eine Abfrage auf dem Untergeordneten, von dem das -@var{Paket} kommt, weshalb der Untergeordnete noch lebendig sein muss, wenn -Sie diese Prozeduren aufrufen. -@end deffn - -Untergeordnete Pakete können transparent wie jedes andere Paket oder -dateiartige Objekt in G-Ausdrücken verwendet werden -(@pxref{G-Ausdrücke}). Sie werden auch transparent wie reguläre Pakete von -der Prozedur @code{packages->manifest} behandelt, welche oft in Manifesten -benutzt wird (@pxref{Aufruf von guix package, siehe die Befehlszeilenoption -@option{--manifest} von @command{guix package}}). Somit können Sie ein -untergeordnetes Paket ziemlich überall dort verwenden, wo Sie ein reguläres -Paket einfügen würden: in Manifesten, im Feld @code{packages} Ihrer -@code{operating-system}-Deklaration und so weiter. - -@node Aufruf von guix describe -@section @command{guix describe} aufrufen - -@cindex Reproduzierbarkeit -@cindex Nachbilden von Guix -Sie könnten sich des Öfteren Fragen stellen wie: »Welche Version von Guix -benutze ich gerade?« oder »Welche Kanäle benutze ich?« Diese Informationen -sind in vielen Situationen nützlich: wenn Sie eine Umgebung auf einer -anderen Maschine oder mit einem anderen Benutzerkonto @emph{nachbilden} -möchten, wenn Sie einen Fehler melden möchten, wenn Sie festzustellen -versuchen, welche Änderung an den von Ihnen verwendeten Kanälen diesen -Fehler verursacht hat, oder wenn Sie Ihren Systemzustand zum Zweck der -Reproduzierbarkeit festhalten möchten. Der Befehl @command{guix describe} -gibt Ihnen Antwort auf diese Fragen. - -Wenn Sie ihn aus einem mit @command{guix pull} bezogenen @command{guix} -heraus ausführen, zeigt Ihnen @command{guix describe} die Kanäle an, aus -denen es erstellt wurde, jeweils mitsamt ihrer Repository-URL und Commit-ID -(@pxref{Kanäle}): - -@example -$ guix describe -Generation 10 Sep 03 2018 17:32:44 (current) - guix e0fa68c - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: e0fa68c7718fffd33d81af415279d6ddb518f727 -@end example - -Wenn Sie mit dem Versionskontrollsystem Git vertraut sind, erkennen Sie -vielleicht die Ähnlichkeit zu @command{git describe}; die Ausgabe ähnelt -auch der von @command{guix pull --list-generations} eingeschränkt auf die -aktuelle Generation (@pxref{Aufruf von guix pull, die Befehlszeilenoption -@option{--list-generations}}). Weil die oben gezeigte Git-Commit-ID -eindeutig eine bestimmte Version von Guix bezeichnet, genügt diese -Information, um die von Ihnen benutzte Version von Guix zu beschreiben, und -auch, um sie nachzubilden. - -Damit es leichter ist, Guix nachzubilden, kann Ihnen @command{guix describe} -auch eine Liste der Kanäle statt einer menschenlesbaren Beschreibung wie -oben liefern: - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -Sie können die Ausgabe in einer Datei speichern, die Sie an @command{guix -pull -C} auf einer anderen Maschine oder zu einem späteren Zeitpunkt -übergeben, wodurch dann eine Instanz @emph{von genau derselben Guix-Version} -installiert wird (@pxref{Aufruf von guix pull, die Befehlszeilenoption -@option{-C}}). Daraufhin können Sie, weil Sie jederzeit dieselbe Version von -Guix installieren können, auch gleich @emph{eine vollständige -Softwareumgebung genau nachbilden}. Wir halten das trotz aller -Bescheidenheit für @emph{klasse} und hoffen, dass Ihnen das auch gefällt! - -Die genauen Befehlszeilenoptionen, die @command{guix describe} unterstützt, -lauten wie folgt: - -@table @code -@item --format=@var{Format} -@itemx -f @var{Format} -Die Ausgabe im angegebenen @var{Format} generieren, was eines der Folgenden -sein muss: - -@table @code -@item human -für menschenlesbare Ausgabe, -@item Kanäle -eine Liste von Kanalspezifikationen erzeugen, die an @command{guix pull -C} -übergeben werden oder als @file{~/.config/guix/channels.scm} eingesetzt -werden können (@pxref{Aufruf von guix pull}), -@item json -@cindex JSON -generiert eine Liste von Kanalspezifikationen im JSON-Format, -@item recutils -generiert eine Liste von Kanalspezifikationen im Recutils-Format. -@end table - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Informationen über das @var{Profil} anzeigen. -@end table - -@node Aufruf von guix archive -@section @command{guix archive} aufrufen - -@cindex @command{guix archive} -@cindex Archivdateien -Der Befehl @command{guix archive} ermöglicht es Nutzern, Dateien im Store in -eine einzelne Archivdatei zu @dfn{exportieren} und diese später auf einer -Maschine, auf der Guix läuft, zu @dfn{importieren}. Insbesondere können so -Store-Objekte von einer Maschine in den Store einer anderen Maschine -übertragen werden. - -@quotation Anmerkung -Wenn Sie nach einer Möglichkeit suchen, Archivdateien für andere Werkzeuge -als Guix zu erstellen, finden Sie Informationen dazu im Abschnitt -@pxref{Aufruf von guix pack}. -@end quotation - -@cindex Store-Objekte exportieren -Führen Sie Folgendes aus, um Store-Dateien als ein Archiv auf die -Standardausgabe zu exportieren: - -@example -guix archive --export @var{Optionen} @var{Spezifikationen}... -@end example - -@var{Spezifikationen} sind dabei entweder die Namen von Store-Dateien oder -Paketspezifikationen wie bei @command{guix package} (@pxref{Aufruf von guix package}). Zum Beispiel erzeugt der folgende Befehl ein Archiv der -@code{gui}-Ausgabe des Pakets @code{git} sowie die Hauptausgabe von -@code{emacs}: - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > groß.nar -@end example - -Wenn die angegebenen Pakete noch nicht erstellt worden sind, werden sie -durch @command{guix archive} automatisch erstellt. Der Erstellungsprozess -kann durch die gemeinsamen Erstellungsoptionen gesteuert werden -(@pxref{Gemeinsame Erstellungsoptionen}). - -Um das @code{emacs}-Paket auf eine über SSH verbundene Maschine zu -übertragen, würde man dies ausführen: - -@example -guix archive --export -r emacs | ssh die-maschine guix archive --import -@end example - -@noindent -Auf gleiche Art kann auch ein vollständiges Benutzerprofil von einer -Maschine auf eine andere übertragen werden: - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh die-maschine guix-archive --import -@end example - -@noindent -Jedoch sollten Sie in beiden Beispielen beachten, dass alles, was zu -@code{emacs}, dem Profil oder deren Abhängigkeiten (wegen @code{-r}) gehört, -übertragen wird, egal ob es schon im Store der Zielmaschine vorhanden ist -oder nicht. Mit der Befehlszeilenoption @code{--missing} lässt sich -herausfinden, welche Objekte im Ziel-Store noch fehlen. Der Befehl -@command{guix copy} vereinfacht und optimiert diesen gesamten Prozess, ist -also, was Sie in diesem Fall wahrscheinlich eher benutzen wollten -(@pxref{Aufruf von guix copy}). - -@cindex Nar, Archivformat -@cindex Normalisiertes Archiv (Nar) -Archive werden als »Normalisiertes Archiv«, kurz »Nar«, formatiert. Diese -Technik folgt einem ähnlichen Gedanken wie beim »tar«-Format, unterscheidet -sich aber auf eine für unsere Zwecke angemessene Art. Erstens werden im -Nar-Format nicht sämtliche Unix-Metadaten aller Dateien aufgenommen, sondern -nur der Dateityp (ob es sich um eine reguläre Datei, ein Verzeichnis oder -eine symbolische Verknüpfung handelt). Unix-Dateiberechtigungen sowie -Besitzer und Gruppe werden nicht gespeichert. Zweitens entspricht die -Reihenfolge, in der der Inhalt von Verzeichnissen abgelegt wird, immer der -Reihenfolge, in der die Dateinamen gemäß der C-Locale sortiert -würden. Dadurch wird die Erstellung von Archivdateien völlig -deterministisch. - -@c FIXME: Add xref to daemon doc about signatures. -Beim Exportieren versieht der Daemon den Inhalt des Archivs mit einer -digitalen Signatur. Diese digitale Signatur wird an das Archiv -angehängt. Beim Importieren verifiziert der Daemon die Signatur und lehnt -den Import ab, falls die Signatur ungültig oder der signierende Schlüssel -nicht autorisiert ist. - -Die wichtigsten Befehlszeilenoptionen sind: - -@table @code -@item --export -Exportiert die angegebenen Store-Dateien oder Pakete (siehe unten) und -schreibt das resultierende Archiv auf die Standardausgabe. - -Abhängigkeiten @emph{fehlen} in der Ausgabe, außer wenn @code{--recursive} -angegeben wurde. - -@item -r -@itemx --recursive -Zusammen mit @code{--export} wird @command{guix archive} hiermit angewiesen, -Abhängigkeiten der angegebenen Objekte auch ins Archiv aufzunehmen. Das -resultierende Archiv ist somit eigenständig; es enthält den Abschluss der -exportierten Store-Objekte. - -@item --import -Ein Archiv von der Standardeingabe lesen und darin enthaltende Dateien in -den Store importieren. Der Import bricht ab, wenn das Archiv keine gültige -digitale Signatur hat oder wenn es von einem öffentlichen Schlüssel signiert -wurde, der keiner der autorisierten Schlüssel ist (siehe @code{--authorize} -weiter unten). - -@item --missing -Eine Liste der Store-Dateinamen von der Standardeingabe lesen, je ein Name -pro Zeile, und auf die Standardausgabe die Teilmenge dieser Dateien -schreiben, die noch nicht im Store vorliegt. - -@item --generate-key[=@var{Parameter}] -@cindex Signieren, von Archiven -Ein neues Schlüsselpaar für den Daemon erzeugen. Dies ist erforderlich, -damit Archive mit @code{--export} exportiert werden können. Beachten Sie, -dass diese Option normalerweise einige Zeit in Anspruch nimmt, da erst -Entropie für die Erzeugung des Schlüsselpaares gesammelt werden muss. - -Das erzeugte Schlüsselpaar wird typischerweise unter @file{/etc/guix} -gespeichert, in den Dateien @file{signing-key.pub} (für den öffentlichen -Schlüssel) und @file{signing-key.sec} (für den privaten Schlüssel, der -geheim gehalten werden muss). Wurden keine @var{Parameters} angegeben, wird -ein ECDSA-Schlüssel unter Verwendung der Kurve Ed25519 erzeugt, oder, falls -die Libgcrypt-Version älter als 1.6.0 ist, ein 4096-Bit-RSA-Schlüssel. Sonst -geben die @var{Parameter} für Libgcrypt geeignete Parameter für -@code{genkey} an (@pxref{General public-key related Functions, -@code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). - -@item --authorize -@cindex Autorisieren, von Archiven -Mit dem auf der Standardeingabe übergebenen öffentlichen Schlüssel signierte -Importe autorisieren. Der öffentliche Schlüssel muss als -»advanced«-formatierter S-Ausdruck gespeichert sein, d.h. im selben Format -wie die Datei @file{signing-key.pub}. - -Die Liste autorisierter Schlüssel wird in der Datei @file{/etc/guix/acl} -gespeichert, die auch von Hand bearbeitet werden kann. Die Datei enthält -@url{http://people.csail.mit.edu/rivest/Sexp.txt, »advanced«-formatierte -S-Ausdrücke} und ist als eine Access Control List für die -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure -(SPKI)} aufgebaut. - -@item --extract=@var{Verzeichnis} -@itemx -x @var{Verzeichnis} -Ein Archiv mit einem einzelnen Objekt lesen, wie es von Substitutservern -geliefert wird (@pxref{Substitute}) und ins @var{Verzeichnis} -entpacken. Dies ist eine systemnahe Operation, die man nur selten direkt -benutzt; siehe unten. - -For example, the following command extracts the substitute for Emacs served -by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: - -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ - | bunzip2 | guix archive -x /tmp/emacs -@end example - -Archive mit nur einem einzelnen Objekt unterscheiden sich von Archiven für -mehrere Dateien, wie sie @command{guix archive --export} erzeugt; sie -enthalten nur ein einzelnes Store-Objekt und @emph{keine} eingebettete -Signatur. Beim Entpacken findet also @emph{keine} Signaturprüfung statt und -ihrer Ausgabe sollte so erst einmal nicht vertraut werden. - -Der eigentliche Zweck dieser Operation ist, die Inspektion von -Archivinhalten von Substitutservern möglich zu machen, auch wenn diesen -unter Umständen nicht vertraut wird. - -@end table - - -@c ********************************************************************* -@node Development -@chapter Development - -@cindex software development -If you are a software developer, Guix provides tools that you should find -helpful---independently of the language you're developing in. This is what -this chapter is about. - -The @command{guix environment} command provides a convenient way to set up -@dfn{development environments} containing all the dependencies and tools -necessary to work on the software package of your choice. The @command{guix -pack} command allows you to create @dfn{application bundles} that can be -easily distributed to users who do not run Guix. - -@menu -* Aufruf von guix environment:: Entwicklungsumgebungen einrichten. -* Aufruf von guix pack:: Software-Bündel erstellen. -@end menu - -@node Aufruf von guix environment -@section @command{guix environment} aufrufen - -@cindex reproduzierbare Erstellungsumgebungen -@cindex Entwicklungsumgebungen -@cindex @command{guix environment} -@cindex Umgebung, Paketerstellungsumgebung -Der Zweck von @command{guix environment} ist es, Hacker beim Aufbau einer -reproduzierbaren Entwicklungsumgebung zu unterstützen, ohne dass diese ihr -Paketprofil verunreinigen müssen. Das Werkzeug @command{guix environment} -nimmt eines oder mehrere Pakete entgegen und erstellt erst all ihre -Eingaben, um dann eine Shell-Umgebung herzustellen, in der diese benutzt -werden können. - -Die allgemeine Syntax lautet: - -@example -guix environment @var{Optionen} @var{Paket}@dots{} -@end example - -Folgendes Beispiel zeigt, wie eine neue Shell gestartet wird, auf der alles -für die Entwicklung von GNU@tie{}Guile eingerichtet ist: - -@example -guix environment guile -@end example - -Wenn benötigte Abhängigkeiten noch nicht erstellt worden sind, wird -@command{guix environment} sie automatisch erstellen lassen. Die Umgebung -der neuen Shell ist eine ergänzte Version der Umgebung, in der @command{guix -environment} ausgeführt wurde. Sie enthält neben den existierenden -Umgebungsvariablen auch die nötigen Suchpfade, um das angegebene Paket -erstellen zu können. Um eine »reine« Umgebung zu erstellen, in der die -ursprünglichen Umgebungsvariablen nicht mehr vorkommen, kann die -Befehlszeilenoption @code{--pure} benutzt werden@footnote{Manchmal ergänzen -Nutzer fälschlicherweise Umgebungsvariable wie @code{PATH} in ihrer -@file{~/.bashrc}-Datei. Das hat zur Folge, dass wenn @code{guix environment} -Bash startet, selbige @file{~/.bashrc} von Bash gelesen wird und die neuen -Umgebungen somit »verunreinigt«. Es ist ein Fehler, solche Umgebungsvariable -in @file{.bashrc} zu definieren, stattdessen sollten sie in -@file{.bash_profile} geschrieben werden, was nur von Login-Shells mit -»source« geladen wird. @xref{Bash Startup Files,,, bash, The GNU Bash -Reference Manual}, für Details über beim Starten von Bash gelesene Dateien}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} definiert die Variable @code{GUIX_ENVIRONMENT} in -der neu erzeugten Shell. Ihr Wert ist der Dateiname des Profils dieser neuen -Umgebung. Das könnten Nutzer verwenden, um zum Beispiel eine besondere -Prompt als Eingabeaufforderung für Entwicklungsumgebungen in ihrer -@file{.bashrc} festzulegen (@pxref{Bash Startup Files,,, bash, The GNU Bash -Reference Manual}): - -@example -if [ -n "$GUIX_ENVIRONMENT" ] -then - export PS1="\u@@\h \w [dev]\$ " -fi -@end example - -@noindent -...@: or to browse the profile: - -@example -$ ls "$GUIX_ENVIRONMENT/bin" -@end example - -Des Weiteren kann mehr als ein Paket angegeben werden. In diesem Fall wird -die Vereinigung der Eingaben der jeweiligen Pakete zugänglich gemacht. Zum -Beispiel erzeugt der folgende Befehl eine Shell, in der alle Abhängigkeiten -von sowohl Guile als auch Emacs verfügbar sind: - -@example -guix environment guile emacs -@end example - -Manchmal will man keine interaktive Shell-Sitzung. Ein beliebiger Befehl -kann aufgerufen werden, indem man nach Angabe der Pakete noch @code{--} vor -den gewünschten Befehl schreibt, um ihn von den übrigen Argumenten -abzutrennen: - -@example -guix environment guile -- make -j4 -@end example - -In anderen Situationen ist es bequemer, aufzulisten, welche Pakete in der -Umgebung benötigt werden. Zum Beispiel führt der folgende Befehl -@command{python} aus einer Umgebung heraus aus, in der Python@tie{}2.7 und -NumPy enthalten sind: - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -Man kann auch sowohl die Abhängigkeiten eines Pakets haben wollen, als auch -ein paar zusätzliche Pakete, die nicht Erstellungs- oder -Laufzeitabhängigkeiten davon sind, aber trotzdem bei der Entwicklung -nützlich sind. Deshalb hängt die Wirkung von der Position der -Befehlszeilenoption @code{--ad-hoc} ab. Pakete, die links von -@code{--ad-hoc} stehen, werden als Pakete interpretiert, deren -Abhängigkeiten zur Umgebung hinzugefügt werden. Pakete, die rechts stehen, -werden selbst zur Umgebung hinzugefügt. Zum Beispiel erzeugt der folgende -Befehl eine Guix-Entwicklungsumgebung, die zusätzlich Git und strace -umfasst: - -@example -guix environment guix --ad-hoc git strace -@end example - -Sometimes it is desirable to isolate the environment as much as possible, -for maximal purity and reproducibility. In particular, when using Guix on a -host distro that is not Guix System, it is desirable to prevent access to -@file{/usr/bin} and other system-wide resources from the development -environment. For example, the following command spawns a Guile REPL in a -``container'' where only the store and the current working directory are -mounted: - -@example -guix environment --ad-hoc --container guile -- guile -@end example - -@quotation Anmerkung -Die Befehlszeilenoption @code{--container} funktioniert nur mit Linux-libre -3.19 oder neuer. -@end quotation - -Im Folgenden werden die verfügbaren Befehlszeilenoptionen zusammengefasst. - -@table @code -@item --root=@var{file} -@itemx -r @var{file} -@cindex persistente Umgebung -@cindex Müllsammlerwurzel, für Umgebungen -Die @var{Datei} zu einer symbolischen Verknüpfung auf das Profil dieser -Umgebung machen und als eine Müllsammlerwurzel registrieren. - -Das ist nützlich, um seine Umgebung vor dem Müllsammler zu schützen und sie -»persistent« zu machen. - -Wird diese Option weggelassen, ist die Umgebung nur, solange die Sitzung von -@command{guix environment} besteht, vor dem Müllsammler sicher. Das -bedeutet, wenn Sie das nächste Mal dieselbe Umgebung neu erzeugen, müssen -Sie vielleicht Pakete neu erstellen oder neu herunterladen. @xref{Aufruf von guix gc} hat mehr Informationen über Müllsammlerwurzeln. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Eine Umgebung für das Paket oder die Liste von Paketen erzeugen, zu der der -@var{Ausdruck} ausgewertet wird. - -Zum Beispiel startet dies: - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -eine Shell mit der Umgebung für eben diese bestimmte Variante des Pakets -PETSc. - -Wenn man dies ausführt: - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -starts a shell with all the base system packages available. - -Die obigen Befehle benutzen nur die Standard-Ausgabe des jeweiligen -Pakets. Um andere Ausgaben auszuwählen, können zweielementige Tupel -spezifiziert werden: - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{Datei} -@itemx -l @var{Datei} -Eine Umgebung erstellen für das Paket oder die Liste von Paketen, zu der der -Code in der @var{Datei} ausgewertet wird. - -Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten -(@pxref{Pakete definieren}): - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Eine Umgebung für die Pakete erzeugen, die im Manifest-Objekt enthalten -sind, das vom Scheme-Code in der @var{Datei} geliefert wird. - -Dies verhält sich ähnlich wie die gleichnamige Option des Befehls -@command{guix package} (@pxref{profile-manifest, @option{--manifest}}) und -benutzt auch dieselben Manifestdateien. - -@item --ad-hoc -Alle angegebenen Pakete in der resultierenden Umgebung einschließen, als -wären sie Eingaben eines @i{ad hoc} definierten Pakets. Diese -Befehlszeilenoption ist nützlich, um schnell Umgebungen aufzusetzen, ohne -dafür einen Paketausdruck schreiben zu müssen, der die gewünschten Eingaben -enthält. - -Zum Beispiel wird mit diesem Befehl: - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -@command{guile} in einer Umgebung ausgeführt, in der sowohl Guile als auch -Guile-SDL zur Verfügung stehen. - -Beachten Sie, dass in diesem Beispiel implizit die vorgegebene Ausgabe von -@code{guile} und @code{guile-sdl} verwendet wird, es aber auch möglich ist, -eine bestimmte Ausgabe auszuwählen — z.B. wird mit @code{glib:bin} die -Ausgabe @code{bin} von @code{glib} gewählt (@pxref{Pakete mit mehreren Ausgaben.}). - -Diese Befehlszeilenoption kann mit dem standardmäßigen Verhalten von -@command{guix environment} verbunden werden. Pakete, die vor @code{--ad-hoc} -aufgeführt werden, werden als Pakete interpretiert, deren Abhängigkeiten zur -Umgebung hinzugefügt werden, was dem standardmäßigen Verhalten -entspricht. Pakete, die danach aufgeführt werden, werden selbst zur Umgebung -hinzugefügt. - -@item --pure -Unset existing environment variables when building the new environment, -except those specified with @option{--preserve} (see below.) This has the -effect of creating an environment in which search paths only contain package -inputs. - -@item --preserve=@var{regexp} -@itemx -E @var{regexp} -When used alongside @option{--pure}, preserve the environment variables -matching @var{regexp}---in other words, put them on a ``white list'' of -environment variables that must be preserved. This option can be repeated -several times. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -This example runs @command{mpirun} in a context where the only environment -variables defined are @code{PATH}, environment variables whose name starts -with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME}, -@code{USER}, etc.) - -@item --search-paths -Die Umgebungsvariablendefinitionen anzeigen, aus denen die Umgebung besteht. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für das angegebene @var{System} zu erstellen — -z.B. @code{i686-linux}. - -@item --container -@itemx -C -@cindex container -Den @var{Befehl} in einer isolierten Umgebung (einem sogenannten -»Container«) ausführen. Das aktuelle Arbeitsverzeichnis außerhalb des -Containers wird in den Container zugeordnet. Zusätzlich wird, wenn es mit -der Befehlszeilenoption @code{--user} nicht anders spezifiziert wurde, ein -stellvertretendes persönliches Verzeichnis erzeugt, dessen Inhalt der des -wirklichen persönlichen Verzeichnisses ist, sowie eine passend konfigurierte -Datei @file{/etc/passwd}. Der erzeugte Prozess läuft außerhalb des -Containers als der momentane Nutzer, aber im Kontext des Containers hat er -Administratorrechte. - -@item --network -@itemx -N -Bei isolierten Umgebungen (»Containern«) wird hiermit der -Netzwerk-Namensraum mit dem des Wirtssystems geteilt. Container, die ohne -diese Befehlszeilenoption erzeugt wurden, haben nur Zugriff auf das -Loopback-Gerät. - -@item --link-profile -@itemx -P -Bei isolierten Umgebungen (»Containern«) wird das Umgebungsprofil im -Container als @file{~/.guix-profile} verknüpft. Das ist äquivalent dazu, den -Befehl @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile} im Container -auszuführen. Wenn das Verzeichnis bereits existiert, schlägt das Verknüpfen -fehl und die Umgebung wird nicht hergestellt. Dieser Fehler wird immer -eintreten, wenn @command{guix environment} im persönlichen Verzeichnis des -Benutzers aufgerufen wurde. - -Bestimmte Pakete sind so eingerichtet, dass sie in @code{~/.guix-profile} -nach Konfigurationsdateien und Daten suchen,@footnote{Zum Beispiel -inspiziert das Paket @code{fontconfig} das Verzeichnis -@file{~/.guix-profile/share/fonts}, um zusätzliche Schriftarten zu finden.} -weshalb @code{--link-profile} benutzt werden kann, damit sich diese -Programme auch in der isolierten Umgebung wie erwartet verhalten. - -@item --user=@var{Benutzer} -@itemx -u @var{Benutzer} -Bei isolierten Umgebungen (»Containern«) wird der Benutzername -@var{Benutzer} anstelle des aktuellen Benutzers benutzt. Der erzeugte -Eintrag in @file{/etc/passwd} im Container wird also den Namen -@var{Benutzer} enthalten und das persönliche Verzeichnis wird den Namen -@file{/home/BENUTZER} tragen; keine GECOS-Daten über den Nutzer werden in -die Umgebung übernommen. @var{Benutzer} muss auf dem System nicht -existieren. - -Zusätzlich werden alle geteilten oder exponierten Pfade (siehe jeweils -@code{--share} und @code{--expose}), deren Ziel innerhalb des persönlichen -Verzeichnisses des aktuellen Benutzers liegt, relativ zu -@file{/home/BENUTZER} erscheinen, einschließlich der automatischen Zuordnung -des aktuellen Arbeitsverzeichnisses. - -@example -# wird Pfade als /home/foo/wd, /home/foo/test und /home/foo/target exponieren -cd $HOME/wd -guix environment --container --user=foo \ - --expose=$HOME/test \ - --expose=/tmp/target=$HOME/target -@end example - -Obwohl dies das Datenleck von Nutzerdaten durch Pfade im persönlichen -Verzeichnis und die Benutzereinträge begrenzt, kann dies nur als Teil einer -größeren Lösung für Privatsphäre und Anonymität sinnvoll eingesetzt -werden. Es sollte nicht für sich allein dazu eingesetzt werden. - -@item --expose=@var{Quelle}[=@var{Ziel}] -Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter -@var{Quelle} vom Wirtssystem als Nur-Lese-Dateisystem @var{Ziel} im -Container zugänglich gemacht. Wenn kein @var{Ziel} angegeben wurde, wird die -@var{Quelle} auch als Ziel-Einhängepunkt in der isolierten Umgebung benutzt. - -Im folgenden Beispiel wird eine Guile-REPL in einer isolierten Umgebung -gestartet, in der das persönliche Verzeichnis des Benutzers als Verzeichnis -@file{/austausch} nur für Lesezugriffe zugänglich gemacht wurde: - -@example -guix environment --container --expose=$HOME=/austausch --ad-hoc guile -- guile -@end example - -@item --share=@var{Quelle}[=@var{Ziel}] -Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter -@var{Quelle} vom Wirtssystem als beschreibbares Dateisystem @var{Ziel} im -Container zugänglich gemacht. Wenn kein @var{Ziel} angegeben wurde, wird die -@var{Quelle} auch als Ziel-Einhängepunkt in der isolierten Umgebung benutzt. - -Im folgenden Beispiel wird eine Guile-REPL in einer isolierten Umgebung -gestartet, in der das persönliche Verzeichnis des Benutzers als Verzeichnis -@file{/austausch} sowohl für Lese- als auch für Schreibzugriffe zugänglich -gemacht wurde: - -@example -guix environment --container --share=$HOME=/austausch --ad-hoc guile -- guile -@end example -@end table - -@command{guix environment} also supports all of the common build options -that @command{guix build} supports (@pxref{Gemeinsame Erstellungsoptionen}) as well as -package transformation options (@pxref{Paketumwandlungsoptionen}). - -@node Aufruf von guix pack -@section @command{guix pack} aufrufen - -Manchmal möchten Sie Software an Leute weitergeben, die (noch!) nicht das -Glück haben, Guix zu benutzen. Mit Guix würden sie nur @command{guix package --i @var{irgendetwas}} einzutippen brauchen, aber wenn sie kein Guix haben, -muss es anders gehen. Hier kommt @command{guix pack} ins Spiel. - -@quotation Anmerkung -Wenn Sie aber nach einer Möglichkeit suchen, Binärdateien unter Maschinen -auszutauschen, auf denen Guix bereits läuft, sollten Sie einen Blick auf die -Abschnitte @pxref{Aufruf von guix copy}, @ref{Aufruf von guix publish} und -@ref{Aufruf von guix archive} werfen. -@end quotation - -@cindex Pack -@cindex Bündel -@cindex Anwendungsbündel -@cindex Software-Bündel -Der Befehl @command{guix pack} erzeugt ein gut verpacktes -@dfn{Software-Bündel}: Konkret wird dadurch ein Tarball oder eine andere Art -von Archiv mit den Binärdateien der Software erzeugt, die Sie sich gewünscht -haben, zusammen mit all ihren Abhängigkeiten. Der resultierende Archiv kann -auch auf jeder Maschine genutzt werden, die kein Guix hat, und jeder kann -damit genau dieselben Binärdateien benutzen, die Ihnen unter Guix zur -Verfügung stehen. Das Bündel wird dabei auf eine Bit für Bit reproduzierbare -Art erzeugt, damit auch jeder nachprüfen kann, dass darin wirklich -diejenigen Binärdateien enthalten sind, von denen Sie es behaupten. - -Um zum Beispiel ein Bündel mit Guile, Emacs, Geiser und all ihren -Abhängigkeiten zu erzeugen, führen Sie diesen Befehl aus: - -@example -$ guix pack guile emacs geiser -@dots{} -/gnu/store/@dots{}-pack.tar.gz -@end example - -Als Ergebnis erhalten Sie einen Tarball mit einem Verzeichnis -@file{/gnu/store}, worin sich alles relevanten Pakete befinden. Der -resultierende Tarball enthält auch ein @dfn{Profil} mit den drei angegebenen -Paketen; es ist dieselbe Art von Profil, die auch @command{guix package -i} -erzeugen würde. Mit diesem Mechanismus wird auch der binäre Tarball zur -Installation von Guix erzeugt (@pxref{Aus Binärdatei installieren}). - -Benutzer des Bündels müssten dann aber zum Beispiel -@file{/gnu/store/@dots{}-profile/bin/guile} eintippen, um Guile auszuführen, -was Ihnen zu unbequem sein könnte. Ein Ausweg wäre, dass Sie etwa eine -symbolische Verknüpfung @file{/opt/gnu/bin} auf das Profil anlegen: - -@example -guix pack -S /opt/gnu/bin=bin guile emacs geiser -@end example - -@noindent -Benutzer müssten dann nur noch @file{/opt/gnu/bin/guile} eintippen, um Guile -zu genießen. - -@cindex pfad-agnostische Binärdateien, mit @command{guix pack} -Doch was ist, wenn die Empfängerin Ihres Bündels keine Administratorrechte -auf ihrer Maschine hat, das Bündel also nicht ins Wurzelverzeichnis ihres -Dateisystems entpacken kann? Dann möchten Sie vielleicht die -Befehlszeilenoption @code{--relocatable} benutzen (siehe weiter unten). Mit -dieser Option werden @dfn{pfad-agnostische Binärdateien} erzeugt, die auch -in einem beliebigen anderen Verzeichnis in der Dateisystemhierarchie -abgelegt und von dort ausgeführt werden können. In obigem Beispiel würden -Benutzer Ihren Tarball in ihr Persönliches Verzeichnis (das -»Home«-Verzeichnis) entpacken und von dort den Befehl -@file{./opt/gnu/bin/guile} ausführen. - -@cindex Docker, ein Abbild erstellen mit guix pack -Eine weitere Möglichkeit ist, das Bündel im Format eines Docker-Abbilds -(englisch Docker-Image) zu erzeugen. Das geht mit dem folgenden Befehl: - -@example -guix pack -f docker guile emacs geiser -@end example - -@noindent -Das Ergebnis ist ein Tarball, der dem Befehl @command{docker load} übergeben -werden kann. In der -@uref{https://docs.docker.com/engine/reference/commandline/load/, -Dokumentation von Docker} finden Sie nähere Informationen. - -@cindex Singularity, ein Abbild erstellen mit guix pack -@cindex SquashFS, ein Abbild erstellen mit guix pack -Und noch eine weitere Möglichkeit ist, dass Sie ein SquashFS-Abbild mit -folgendem Befehl erzeugen: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -Das Ergebnis ist ein SquashFS-Dateisystemabbild, dass entweder als -Dateisystem eingebunden oder mit Hilfe der @uref{http://singularity.lbl.gov, -Singularity-Container-Ausführungsumgebung} als Dateisystemcontainer benutzt -werden kann, mit Befehlen wie @command{singularity shell} oder -@command{singularity exec}. - -Es gibt mehrere Befehlszeilenoptionen, mit denen Sie Ihr Bündel anpassen -können: - -@table @code -@item --format=@var{Format} -@itemx -f @var{Format} -Generiert ein Bündel im angegebenen @var{Format}. - -Die verfügbaren Formate sind: - -@table @code -@item tarball -Das standardmäßig benutzte Format. Damit wird ein Tarball generiert, der -alle angegebenen Binärdateien und symbolischen Verknüpfungen enthält. - -@item docker -Generiert einen Tarball gemäß der -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -Docker Image Specification}, d.h. der Spezifikation für Docker-Abbilder. - -@item squashfs -Generiert ein SquashFS-Abbild, das alle angegebenen Binärdateien und -symbolischen Verknüpfungen enthält, sowie leere Einhängepunkte für virtuelle -Dateisysteme wie procfs. -@end table - -@item --relocatable -@itemx -R -Erzeugt @dfn{pfad-agnostische Binärdateien} — also »portable« Binärdateien, -die an einer beliebigen Stelle in der Dateisystemhierarchie platziert und -von dort ausgeführt werden können. Zum Beispiel können Sie ein Bash -enthalltendes Bündel erzeugen mit: - -@example -guix pack -R -S /meine-bin=bin bash -@end example - -@noindent -...@: you can copy that pack to a machine that lacks Guix, and from your -home directory as a normal user, run: - -@example -tar xf pack.tar.gz -./meine-bin/sh -@end example - -@noindent -Wenn Sie in der so gestarteten Shell dann @code{ls /gnu/store} eintippen, -sehen Sie, dass Ihnen angezeigt wird, in @file{/gnu/store} befänden sich -alle Abhängigkeiten von @code{bash}, obwohl auf der Maschine überhaupt kein -Verzeichnis @file{/gnu/store} existiert! Dies ist vermutlich die einfachste -Art, mit Guix erstellte Software für eine Maschine ohne Guix auszuliefern. - -Die Sache hat nur einen Haken: Diese Technik funktioniert nur mit -@dfn{Benutzernamensräumen} (englisch @dfn{User namespaces}), einer -Funktionalität des Linux-Kernels, mit der Benutzer ohne besondere -Berechtigungen Dateisysteme einbinden (englisch »mount«) oder die Wurzel des -Dateisystems wechseln können (»change root«, kurz »chroot«). Alte Versionen -von Linux haben es noch nicht unterstützt und manche Distributionen von -GNU/Linux schalten diese Funktionalität ab; auf diesen Systemen @emph{werden -Programme aus dem Bündel nicht funktionieren}, solange sie nicht in das -echte Wurzeldateisystem entpackt werden. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -Der Zweck hiervon ist derselbe wie bei der gleichnamigen Befehlszeilenoption -in @command{guix build} (@pxref{Zusätzliche Erstellungsoptionen, -@code{--expression} in @command{guix build}}). - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Die Pakete benutzen, die im Manifest-Objekt aufgeführt sind, das vom -Scheme-Code in der angegebenen @var{Datei} geliefert wird. - -Dies hat einen ähnlichen Zweck wie die gleichnamige Befehlszeilenoption in -@command{guix package} (@pxref{profile-manifest, @option{--manifest}}) und -benutzt dieselben Regeln für Manifest-Dateien. Damit können Sie eine Reihe -von Paketen einmal definieren und dann sowohl zum Erzeugen von Profilesn als -auch zum Erzeugen von Archiven benutzen, letztere für Maschinen, auf denen -Guix nicht installiert ist. Beachten Sie, dass Sie @emph{entweder} eine -Manifest-Datei @emph{oder} eine Liste von Paketen angeben können, aber nicht -beides. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@item --target=@var{Tripel} -@cindex Cross-Kompilieren -Lässt für das angegebene @var{Tripel} cross-erstellen, dieses muss ein -gültiges GNU-Tripel wie z.B. @code{"mips64el-linux-gnu"} sein -(@pxref{Specifying target triplets, GNU configuration triplets,, autoconf, -Autoconf}). - -@item --compression=@var{Werkzeug} -@itemx -C @var{Werkzeug} -Komprimiert den resultierenden Tarball mit dem angegebenen @var{Werkzeug} — -dieses kann @code{gzip}, @code{bzip2}, @code{xz}, @code{lzip} oder -@code{none} für keine Kompression sein. - -@item --symlink=@var{Spezifikation} -@itemx -S @var{Spezifikation} -Fügt die in der @var{Spezifikation} festgelegten symbolischen Verknüpfungen -zum Bündel hinzu. Diese Befehlszeilenoption darf mehrmals vorkommen. - -Die @var{Spezifikation} muss von der Form -@code{@var{Quellort}=@var{Zielort}} sein, wobei der @var{Quellort} der Ort -der symbolischen Verknüpfung, die erstellt wird, und @var{Zielort} das Ziel -der symbolischen Verknüpfung ist. - -Zum Beispiel wird mit @code{-S /opt/gnu/bin=bin} eine symbolische -Verknüpfung @file{/opt/gnu/bin} auf das Unterverzeichnis @file{bin} im -Profil erzeugt. - -@item --save-provenance -Save provenance information for the packages passed on the command line. -Provenance information includes the URL and commit of the channels in use -(@pxref{Kanäle}). - -Provenance information is saved in the -@file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the -usual package metadata---the name and version of each package, their -propagated inputs, and so on. It is useful information to the recipient of -the pack, who then knows how the pack was (supposedly) obtained. - -This option is not enabled by default because, like timestamps, provenance -information contributes nothing to the build process. In other words, there -is an infinity of channel URLs and commit IDs that can lead to the same -pack. Recording such ``silent'' metadata in the output thus potentially -breaks the source-to-binary bitwise reproducibility property. - -@item --localstatedir -@itemx --profile-name=@var{Name} -Das »lokale Zustandsverzeichnis« @file{/var/guix} ins resultierende Bündel -aufnehmen, speziell auch das Profil -@file{/var/guix/profiles/per-user/root/@var{Name}} — der vorgegebene -@var{Name} ist @code{guix-profile}, was @file{~root/.guix-profile} -entspricht. - -@file{/var/guix} enthält die Store-Datenbank (@pxref{Der Store}) sowie die -Müllsammlerwurzeln (@pxref{Aufruf von guix gc}). Es ins Bündel aufzunehmen, -bedeutet, dass der enthaltene Store »vollständig« ist und von Guix verwaltet -werden kann, andernfalls wäre der Store im Bündel »tot« und nach dem -Auspacken des Bündels könnte Guix keine Objekte mehr dort hinzufügen oder -entfernen. - -Ein Anwendungsfall hierfür ist der eigenständige, alle Komponenten -umfassende binäre Tarball von Guix (@pxref{Aus Binärdatei installieren}). - -@item --bootstrap -Mit den Bootstrap-Binärdateien das Bündel erstellen. Diese Option ist nur -für Guix-Entwickler nützlich. -@end table - -Außerdem unterstützt @command{guix pack} alle gemeinsamen -Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}) und alle -Paketumwandlungsoptionen (@pxref{Paketumwandlungsoptionen}). - - -@c ********************************************************************* -@node Programmierschnittstelle -@chapter Programmierschnittstelle - -GNU Guix bietet mehrere Programmierschnittstellen (APIs) in der -Programmiersprache Scheme an, mit denen Software-Pakete definiert, erstellt -und gesucht werden können. Die erste Schnittstelle erlaubt es Nutzern, ihre -eigenen Paketdefinitionen in einer Hochsprache zu schreiben. Diese -Definitionen nehmen Bezug auf geläufige Konzepte der Paketverwaltung, wie -den Namen und die Version eines Pakets, sein Erstellungssystem (Build -System) und seine Abhängigkeiten (Dependencies). Diese Definitionen können -dann in konkrete Erstellungsaktionen umgewandelt werden. - -Erstellungsaktionen werden vom Guix-Daemon für dessen Nutzer -durchgeführt. Bei einer normalen Konfiguration hat der Daemon Schreibzugriff -auf den Store, also das Verzeichnis @file{/gnu/store}, Nutzer hingegen -nicht. Die empfohlene Konfiguration lässt den Daemon die Erstellungen in -chroot-Umgebungen durchführen, mit eigenen Benutzerkonten für -»Erstellungsbenutzer«, um gegenseitige Beeinflussung der Erstellung und des -übrigen Systems zu minimieren. - -@cindex Ableitung -Systemnahe APIs stehen zur Verfügung, um mit dem Daemon und dem Store zu -interagieren. Um den Daemon anzuweisen, eine Erstellungsaktion -durchzuführen, versorgen ihn Nutzer jeweils mit einer @dfn{Ableitung}. Eine -Ableitung ist, wie durchzuführende Erstellungsaktionen, sowie die -Umgebungen, in denen sie durchzuführen sind, in Guix eigentlich intern -dargestellt werden. Ableitungen verhalten sich zu Paketdefinitionen -vergleichbar mit Assembler-Code zu C-Programmen. Der Begriff »Ableitung« -kommt daher, dass Erstellungsergebnisse daraus @emph{abgeleitet} werden. - -Dieses Kapitel beschreibt der Reihe nach all diese Programmierschnittstellen -(APIs), angefangen mit hochsprachlichen Paketdefinitionen. - -@menu -* Paketmodule:: Pakete aus Sicht des Programmierers. -* Pakete definieren:: Wie Sie neue Pakete definieren. -* Erstellungssysteme:: Angeben, wie Pakete erstellt werden. -* Der Store:: Den Paket-Store verändern. -* Ableitungen:: Systemnahe Schnittstelle für Paketableitungen. -* Die Store-Monade:: Rein funktionale Schnittstelle zum Store. -* G-Ausdrücke:: Erstellungsausdrücke verarbeiten. -* Aufruf von guix repl:: Interaktiv an Guix herumbasteln. -@end menu - -@node Paketmodule -@section Paketmodule - -From a programming viewpoint, the package definitions of the GNU -distribution are provided by Guile modules in the @code{(gnu packages -@dots{})} name space@footnote{Note that packages under the @code{(gnu -packages @dots{})} module name space are not necessarily ``GNU packages''. -This module naming scheme follows the usual Guile module naming convention: -@code{gnu} means that these modules are distributed as part of the GNU -system, and @code{packages} identifies modules that define packages.} -(@pxref{Module, Guile modules,, guile, GNU Guile Reference Manual}). For -instance, the @code{(gnu packages emacs)} module exports a variable named -@code{emacs}, which is bound to a @code{<package>} object (@pxref{Pakete definieren}). - -The @code{(gnu packages @dots{})} module name space is automatically scanned -for packages by the command-line tools. For instance, when running -@code{guix package -i emacs}, all the @code{(gnu packages @dots{})} modules -are scanned until one that exports a package object whose name is -@code{emacs} is found. This package search facility is implemented in the -@code{(gnu packages)} module. - -@cindex Anpassung, von Paketen -@cindex package module search path -Users can store package definitions in modules with different names---e.g., -@code{(my-packages emacs)}@footnote{Note that the file name and module name -must match. For instance, the @code{(my-packages emacs)} module must be -stored in a @file{my-packages/emacs.scm} file relative to the load path -specified with @option{--load-path} or @code{GUIX_PACKAGE_PATH}. -@xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, for -details.}. There are two ways to make these package definitions visible to -the user interfaces: - -@enumerate -@item -By adding the directory containing your package modules to the search path -with the @code{-L} flag of @command{guix package} and other commands -(@pxref{Gemeinsame Erstellungsoptionen}), or by setting the @code{GUIX_PACKAGE_PATH} -environment variable described below. - -@item -By defining a @dfn{channel} and configuring @command{guix pull} so that it -pulls from it. A channel is essentially a Git repository containing package -modules. @xref{Kanäle}, for more information on how to define and use -channels. -@end enumerate - -@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: - -@defvr {Environment Variable} GUIX_PACKAGE_PATH -This is a colon-separated list of directories to search for additional -package modules. Directories listed in this variable take precedence over -the own modules of the distribution. -@end defvr - -The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: each -package is built based solely on other packages in the distribution. The -root of this dependency graph is a small set of @dfn{bootstrap binaries}, -provided by the @code{(gnu packages bootstrap)} module. For more -information on bootstrapping, @pxref{Bootstrapping}. - -@node Pakete definieren -@section Pakete definieren - -Mit den Modulen @code{(guix packages)} und @code{(guix build-system)} können -Paketdefinitionen auf einer hohen Abstraktionsebene geschrieben werden. Zum -Beispiel sieht die Paketdefinition bzw. das @dfn{Rezept} für das Paket von -GNU Hello so aus: - -@example -(define-module (gnu packages hello) - #:use-module (guix packages) - #:use-module (guix download) - #:use-module (guix build-system gnu) - #:use-module (guix licenses) - #:use-module (gnu packages gawk)) - -(define-public hello - (package - (name "hello") - (version "2.10") - (source (origin - (method url-fetch) - (uri (string-append "mirror://gnu/hello/hello-" version - ".tar.gz")) - (sha256 - (base32 - "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) - (build-system gnu-build-system) - (arguments '(#:configure-flags '("--enable-silent-rules"))) - (inputs `(("gawk" ,gawk))) - (synopsis "Hello, GNU world: An example GNU package") - (description "Guess what GNU Hello prints!") - (home-page "http://www.gnu.org/software/hello/") - (license gpl3+))) -@end example - -@noindent -Auch ohne ein Experte in Scheme zu sein, könnten Leser erraten haben, was -die verschiedenen Felder dabei bedeuten. Dieser Ausdruck bindet die Variable -@code{hello} an ein @code{<package>}-Objekt, was an sich nur ein Verbund -(Record) ist (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference -Manual}). Die Felder dieses Paket-Objekts lassen sich mit den Prozeduren aus -dem Modul @code{(guix packages)} auslesen, zum Beispiel liefert -@code{(package-name hello)} — Überraschung! — @code{"hello"}. - -Mit etwas Glück können Sie die Definition vielleicht teilweise oder sogar -ganz aus einer anderen Paketsammlung importieren, indem Sie den Befehl -@code{guix import} verwenden (@pxref{Aufruf von guix import}). - -In obigem Beispiel wurde @var{hello} in einem eigenen Modul ganz für sich -alleine definiert, und zwar @code{(gnu packages hello)}. Technisch gesehen -muss es nicht unbedingt in einem solchen Modul definiert werden, aber es ist -bequem, denn alle Module unter @code{(gnu packages @dots{})} werden -automatisch von den Befehlszeilenwerkzeugen gefunden (@pxref{Paketmodule}). - -Ein paar Dinge sind noch erwähnenswert in der obigen Paketdefinition: - -@itemize -@item -Das @code{source}-Feld für die Quelle des Pakets ist ein -@code{<origin>}-Objekt, was den Paketursprung angibt (siehe @pxref{»origin«-Referenz}, für eine vollständige Referenz). Hier wird dafür die Methode -@code{url-fetch} aus dem Modul @code{(guix download)} benutzt, d.h. die -Quelle ist eine Datei, die über FTP oder HTTP heruntergeladen werden soll. - -Das Präfix @code{mirror://gnu} lässt @code{url-fetch} einen der -GNU-Spiegelserver benutzen, die in @code{(guix download)} definiert sind. - -Das Feld @code{sha256} legt den erwarteten SHA256-Hashwert der -herunterzuladenden Datei fest. Ihn anzugeben ist Pflicht und er ermöglicht -es Guix, die Integrität der Datei zu überprüfen. Die Form @code{(base32 -@dots{})} geht der base32-Darstellung des Hash-Wertes voraus. Sie finden die -base32-Darstellung mit Hilfe der Befehle @code{guix download} -(@pxref{Aufruf von guix download}) und @code{guix hash} (@pxref{Aufruf von guix hash}). - -@cindex Patches -Wenn nötig kann in der @code{origin}-Form auch ein @code{patches}-Feld -stehen, wo anzuwendende Patches aufgeführt werden, sowie ein -@code{snippet}-Feld mit einem Scheme-Ausdruck mit den Anweisungen, wie der -Quellcode zu modifizieren ist. - -@item -@cindex GNU-Erstellungssystem -Das Feld @code{build-system} legt fest, mit welcher Prozedur das Paket -erstellt werden soll (@pxref{Erstellungssysteme}). In diesem Beispiel steht -@var{gnu-build-system} für das wohlbekannte GNU-Erstellungssystem, wo Pakete -mit der üblichen Befehlsfolge @code{./configure && make && make check && -make install} konfiguriert, erstellt und installiert werden. - -@item -Das Feld @code{arguments} gibt an, welche Optionen dem Erstellungssystem -mitgegeben werden sollen (@pxref{Erstellungssysteme}). In diesem Fall -interpretiert @var{gnu-build-system} diese als Auftrag, @file{configure} mit -der Befehlszeilenoption @code{--enable-silent-rules} auszuführen. - -@cindex quote -@cindex Maskierung -@findex ' -@findex quote -Was hat es mit diesen einfachen Anführungszeichen (@code{'}) auf sich? Sie -gehören zur Syntax von Scheme und führen eine wörtlich zu interpretierende -Datenlisten ein; dies nennt sich Maskierung oder Quotierung. @code{'} ist -synonym mit @code{quote}. @xref{Expression Syntax, quoting,, guile, GNU -Guile Reference Manual}, enthält weitere Details. Hierbei ist also der Wert -des @code{arguments}-Feldes eine Liste von Argumenten, die an das -Erstellungssystem weitergereicht werden, wie bei @code{apply} (@pxref{Fly -Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -Ein Doppelkreuz gefolgt von einem Doppelpunkt (@code{#:}) definiert ein -Scheme-@dfn{Schlüsselwort} (@pxref{Keywords,,, guile, GNU Guile Reference -Manual}) und @code{#:configure-flags} ist ein Schlüsselwort, um eine -Befehlszeilenoption an das Erstellungssystem mitzugeben (@pxref{Coding With -Keywords,,, guile, GNU Guile Reference Manual}). - -@item -Das Feld @code{inputs} legt Eingaben an den Erstellungsprozess fest — -d.h. Abhängigkeiten des Pakets zur Erstellungs- oder Laufzeit. Hier -definieren wir eine Eingabe namens @code{"gawk"}, deren Wert wir auf den -Wert der @var{gawk}-Variablen festlegen; @var{gawk} ist auch selbst wiederum -an ein @code{<package>}-Objekt als Variablenwert gebunden. - -@cindex Backquote (Quasimaskierung) -@findex ` -@findex quasiquote -@cindex Komma (Demaskierung) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -Auch mit @code{`} (einem Backquote, stattdessen kann man auch das längere -Synonym @code{quasiquote} schreiben) können wir eine wörtlich als Daten -interpretierte Liste im @code{inputs}-Feld einführen, aber bei dieser -»Quasimaskierung« kann @code{,} (ein Komma, oder dessen Synonym -@code{unquote}) benutzt werden, um den ausgewerteten Wert eines Ausdrucks in -diese Liste einzufügen (@pxref{Expression Syntax, unquote,, guile, GNU Guile -Reference Manual}). - -Beachten Sie, dass GCC, Coreutils, Bash und andere essenzielle Werkzeuge -hier nicht als Eingaben aufgeführt werden müssen. Stattdessen sorgt schon -@var{gnu-build-system} dafür, dass diese vorhanden sein müssen (@pxref{Erstellungssysteme}). - -Sämtliche anderen Abhängigkeiten müssen aber im @code{inputs}-Feld -aufgezählt werden. Jede hier nicht angegebene Abhängigkeit wird während des -Erstellungsprozesses schlicht nicht verfügbar sein, woraus ein -Erstellungsfehler resultieren kann. -@end itemize - -Siehe @xref{»package«-Referenz} für eine umfassende Beschreibung aller -erlaubten Felder. - -Sobald eine Paketdefinition eingesetzt wurde, können Sie das Paket mit Hilfe -des Befehlszeilenwerkzeugs @code{guix build} dann auch tatsächlich erstellen -(@pxref{Aufruf von guix build}) und dabei jegliche Erstellungsfehler, auf die -Sie stoßen, beseitigen (@pxref{Fehlschläge beim Erstellen untersuchen}). Sie können den -Befehl @command{guix edit} benutzen, um leicht zur Paketdefinition -zurückzuspringen (@pxref{Aufruf von guix edit}). Unter @xref{Paketrichtlinien} finden Sie mehr Informationen darüber, wie Sie Paketdefinitionen -testen, und unter @ref{Aufruf von guix lint} finden Sie Informationen, wie Sie -prüfen, ob eine Definition alle Stilkonventionen einhält. -@vindex GUIX_PACKAGE_PATH -Zuletzt finden Sie unter @pxref{Kanäle} Informationen, wie Sie die -Distribution um Ihre eigenen Pakete in einem »Kanal« erweitern. - -Zu all dem sei auch erwähnt, dass Sie das Aktualisieren einer -Paketdefinition auf eine vom Anbieter neu veröffentlichte Version mit dem -Befehl @command{guix refresh} teilweise automatisieren können -(@pxref{Aufruf von guix refresh}). - -Hinter den Kulissen wird die einem @code{<package>}-Objekt entsprechende -Ableitung zuerst durch @code{package-derivation} berechnet. Diese Ableitung -wird in der @code{.drv}-Datei unter @file{/gnu/store} gespeichert. Die von -ihr vorgeschriebenen Erstellungsaktionen können dann durch die Prozedur -@code{build-derivations} umgesetzt werden (@pxref{Der Store}). - -@deffn {Scheme-Prozedur} package-derivation @var{Store} @var{Paket} [@var{System}] -Das @code{<derivation>}-Objekt zum @var{Paket} für das angegebene -@var{System} liefern (@pxref{Ableitungen}). - -Als @var{Paket} muss ein gültiges @code{<package>}-Objekt angegeben werden -und das @var{System} muss eine Zeichenkette sein, die das Zielsystem angibt -— z.B. @code{"x86_64-linux"} für ein auf x86_64 laufendes Linux-basiertes -GNU-System. @var{Store} muss eine Verbindung zum Daemon sein, der die -Operationen auf dem Store durchführt (@pxref{Der Store}). -@end deffn - -@noindent -@cindex Cross-Kompilieren -Auf ähnliche Weise kann eine Ableitung berechnet werden, die ein Paket für -ein anderes System cross-erstellt. - -@deffn {Scheme-Prozedur} package-cross-derivation @var{Store} @ - @var{Paket} @var{Ziel} [@var{System}] Liefert das -@code{<derivation>}-Objekt, um das @var{Paket} zu cross-erstellen vom -@var{System} aus für das @var{Ziel}-System. - -Als @var{Ziel} muss ein gültiges GNU-Tripel angegeben werden, was die -Ziel-Hardware und das zugehörige Betriebssystem beschreibt, wie -z.B. @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU -configuration triplets,, configure, GNU Configure and Build System}). -@end deffn - -@cindex Paketumwandlungen -@cindex Eingaben umschreiben -@cindex Abhängigkeitsbaum umschreiben -Pakete können auf beliebige Art verändert werden. Ein Beispiel für eine -nützliche Veränderung ist das @dfn{Umschreiben von Eingaben}, womit der -Abhängigkeitsbaum eines Pakets umgeschrieben wird, indem bestimmte Eingaben -durch andere ersetzt werden: - -@deffn {Scheme-Prozedur} package-input-rewriting @var{Ersetzungen} @ - [@var{umgeschriebener-Name}] Eine Prozedur liefern, die für ein ihr -übergebenes Paket dessen direkte und indirekte Abhängigkeit (aber nicht -dessen implizite Eingaben) gemäß den @var{Ersetzungen} -umschreibt. @var{Ersetzungen} ist eine Liste von Paketpaaren; das erste -Element eines Paares ist das zu ersetzende Paket und das zweite ist, wodurch -es ersetzt werden soll. - -Optional kann als @var{umgeschriebener-Name} eine ein Argument nehmende -Prozedur angegeben werden, die einen Paketnamen nimmt und den Namen nach dem -Umschreiben zurückliefert. -@end deffn - -@noindent -Betrachten Sie dieses Beispiel: - -@example -(define libressl-statt-openssl - ;; Dies ist eine Prozedur, mit der OPENSSL durch LIBRESSL - ;; rekursiv ersetzt wird. - (package-input-rewriting `((,openssl . ,libressl)))) - -(define git-mit-libressl - (libressl-statt-openssl git)) -@end example - -@noindent -Hier definieren wir zuerst eine Umschreibeprozedur, die @var{openssl} durch -@var{libressl} ersetzt. Dann definieren wir damit eine @dfn{Variante} des -@var{git}-Pakets, die @var{libressl} statt @var{openssl} benutzt. Das ist -genau, was auch die Befehlszeilenoption @option{--with-input} tut -(@pxref{Paketumwandlungsoptionen, @option{--with-input}}). - -Eine allgemeiner anwendbare Prozedur, um den Abhängigkeitsgraphen eines -Pakets umzuschreiben, ist @code{package-mapping}. Sie unterstützt beliebige -Änderungen an den Knoten des Graphen. - -@deffn {Scheme-Prozedur} package-mapping @var{Prozedur} [@var{Schnitt?}] -Liefert eine Prozedur, die, wenn ihr ein Paket übergeben wird, die an -@code{package-mapping} übergebene @var{Prozedur} auf alle vom Paket -abhängigen Pakete anwendet. Die Prozedur liefert das resultierende -Paket. Wenn @var{Schnitt?} für ein Paket davon einen wahren Wert liefert, -findet kein rekursiver Abstieg in dessen Abhängigkeiten statt. -@end deffn - -@menu -* »package«-Referenz:: Der Datentyp für Pakete. -* »origin«-Referenz:: Datentyp für Paketursprünge. -@end menu - - -@node »package«-Referenz -@subsection @code{package}-Referenz - -Dieser Abschnitt fasst alle in @code{package}-Deklarationen zur Verfügung -stehenden Optionen zusammen (@pxref{Pakete definieren}). - -@deftp {Datentyp} package -Dieser Datentyp steht für ein Paketrezept. - -@table @asis -@item @code{name} -Der Name des Pakets als Zeichenkette. - -@item @code{version} -Die Version des Pakets als Zeichenkette. - -@item @code{source} -Ein Objekt, das beschreibt, wie der Quellcode des Pakets bezogen werden -soll. Meistens ist es ein @code{origin}-Objekt, welches für eine aus dem -Internet heruntergeladene Datei steht (@pxref{»origin«-Referenz}). Es kann -aber auch ein beliebiges anderes »dateiähnliches« Objekt sein, wie z.B. ein -@code{local-file}, was eine Datei im lokalen Dateisystem bezeichnet -(@pxref{G-Ausdrücke, @code{local-file}}). - -@item @code{build-system} -Das Erstellungssystem, mit dem das Paket erstellt werden soll (@pxref{Erstellungssysteme}). - -@item @code{arguments} (Vorgabe: @code{'()}) -Die Argumente, die an das Erstellungssystem übergeben werden sollen. Dies -ist eine Liste, typischerweise eine Reihe von Schlüssel-Wert-Paaren. - -@item @code{inputs} (Vorgabe: @code{'()}) -@itemx @code{native-inputs} (Vorgabe: @code{'()}) -@itemx @code{propagated-inputs} (Vorgabe: @code{'()}) -@cindex Eingaben, von Paketen -In diesen Feldern werden die Abhängigkeiten des Pakets aufgeführt. Jedes -dieser Felder enthält eine Liste von Tupeln, wobei jedes Tupel eine -Bezeichnung für die Eingabe (als Zeichenkette) als erstes Element, dann ein -»package«-, »origin«- oder »derivation«-Objekt (Paket, Ursprung oder -Ableitung) als zweites Element und optional die Benennung der davon zu -benutzenden Ausgabe umfasst; letztere hat als Vorgabewert @code{"out"} -(siehe @pxref{Pakete mit mehreren Ausgaben.} für mehr Informationen zu -Paketausgaben). Im folgenden Beispiel etwa werden drei Eingaben festgelegt: - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;Ausgabe "bin" von Glib -@end example - -@cindex Cross-Kompilieren, Paketabhängigkeiten -Die Unterscheidung zwischen @code{native-inputs} und @code{inputs} ist -wichtig, damit Cross-Kompilieren möglich ist. Beim Cross-Kompilieren werden -als @code{inputs} aufgeführte Abhängigkeiten für die -Ziel-Prozessorarchitektur (@emph{target}) erstellt, andersherum werden als -@code{native-inputs} aufgeführte Abhängigkeiten für die Prozessorarchitektur -der erstellenden Maschine (@emph{build}) erstellt. - -@code{native-inputs} listet typischerweise die Werkzeuge auf, die während -der Erstellung gebraucht werden, aber nicht zur Laufzeit des Programms -gebraucht werden. Beispiele sind Autoconf, Automake, pkg-config, Gettext -oder Bison. @command{guix lint} kann melden, ob wahrscheinlich Fehler in der -Auflistung sind (@pxref{Aufruf von guix lint}). - -@anchor{package-propagated-inputs} -Schließlich ist @code{propagated-inputs} ähnlich wie @code{inputs}, aber die -angegebenen Pakete werden automatisch mit ins Profil installiert, wenn das -Paket installiert wird, zu dem sie gehören (siehe -@pxref{package-cmd-propagated-inputs, @command{guix package}}, für -Informationen darüber, wie @command{guix package} mit propagierten Eingaben -umgeht). - -Dies ist zum Beispiel nötig, wenn eine C-/C++-Bibliothek Header-Dateien -einer anderen Bibliothek braucht, um mit ihr kompilieren zu können, oder -wenn sich eine pkg-config-Datei auf eine andere über ihren -@code{Requires}-Eintrag bezieht. - -Noch ein Beispiel, wo @code{propagated-inputs} nützlich ist, sind Sprachen, -die den Laufzeit-Suchpfad @emph{nicht} zusammen mit dem Programm abspeichern -(@emph{nicht} wie etwa im @code{RUNPATH} bei ELF-Dateien), also Sprachen wie -Guile, Python, Perl und weitere. Damit auch in solchen Sprachen geschriebene -Bibliotheken zur Laufzeit den von ihnen benötigten Code finden können, -müssen deren Laufzeit-Abhängigkeiten in @code{propagated-inputs} statt in -@code{inputs} aufgeführt werden. - -@item @code{self-native-input?} (Vorgabe: @code{#f}) -Dieses boolesche Feld gibt an, ob das Paket sich selbst als eine native -Eingabe beim Cross-Kompilieren braucht. - -@item @code{outputs} (Vorgabe: @code{'("out")}) -Die Liste der Benennungen der Ausgaben des Pakets. Der Abschnitt -@xref{Pakete mit mehreren Ausgaben.} beschreibt übliche Nutzungen -zusätzlicher Ausgaben. - -@item @code{native-search-paths} (Vorgabe: @code{'()}) -@itemx @code{search-paths} (Vorgabe: @code{'()}) -Eine Liste von @code{search-path-specification}-Objekten, die -Umgebungsvariable für von diesem Paket beachtete Suchpfade (»search paths«) -beschreiben. - -@item @code{replacement} (Vorgabe: @code{#f}) -Dies muss entweder @code{#f} oder ein package-Objekt sein, das als Ersatz -(@dfn{replacement}) dieses Pakets benutzt werden soll. Im Abschnitt -@xref{Sicherheitsaktualisierungen, grafts}, wird dies erklärt. - -@item @code{synopsis} -Eine einzeilige Beschreibung des Pakets. - -@item @code{description} -Eine ausführlichere Beschreibung des Pakets. - -@item @code{license} -@cindex Lizenz, von Paketen -Die Lizenz des Pakets; benutzt werden kann ein Wert aus dem Modul -@code{(guix licenses)} oder eine Liste solcher Werte. - -@item @code{home-page} -Die URL, die die Homepage des Pakets angibt, als Zeichenkette. - -@item @code{supported-systems} (Vorgabe: @var{%supported-systems}) -Die Liste der vom Paket unterstützten Systeme als Zeichenketten der Form -@code{Architektur-Kernel}, zum Beispiel @code{"x86_64-linux"}. - -@item @code{maintainers} (Vorgabe: @code{'()}) -Die Liste der Betreuer (Maintainer) des Pakets als -@code{maintainer}-Objekte. - -@item @code{location} (Vorgabe: die Stelle im Quellcode, wo die @code{package}-Form steht) -Wo im Quellcode das Paket definiert wurde. Es ist sinnvoll, dieses Feld -manuell zuzuweisen, wenn das Paket von einem anderen Paket erbt, weil dann -dieses Feld nicht automatisch berichtigt wird. -@end table -@end deftp - - -@node »origin«-Referenz -@subsection @code{origin}-Referenz - -Dieser Abschnitt fasst alle Optionen zusammen, die in -@code{origin}-Deklarationen zur Verfügung stehen (@pxref{Pakete definieren}). - -@deftp {Datentyp} origin -Mit diesem Datentyp wird ein Ursprung, von dem Quellcode geladen werden -kann, beschrieben. - -@table @asis -@item @code{uri} -Ein Objekt, was die URI des Quellcodes enthält. Der Objekttyp hängt von der -@code{Methode} ab (siehe unten). Zum Beispiel sind, wenn die -@var{url-fetch}-Methode aus @code{(guix download)} benutzt wird, die -gültigen Werte für @code{uri}: eine URL dargestellt als Zeichenkette oder -eine Liste solcher URLs. - -@item @code{method} -Eine Prozedur, die die URI verwertet. - -Beispiele sind unter Anderem: - -@table @asis -@item @var{url-fetch} aus @code{(guix download)} -Herunterladen einer Datei von einer HTTP-, HTTPS- oder FTP-URL, die im -@code{uri}-Feld angegeben wurde. - -@vindex git-fetch -@item @var{git-fetch} aus @code{(guix git-download)} -Das im @code{uri}-Feld spezifizierte Repository des -Git-Versionskontrollsystems klonen und davon den im @code{uri}-Feld als ein -@code{git-reference}-Objekt angegebenen Commit benutzen; eine -@code{git-reference} sieht so aus: - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -Ein Bytevektor, der den SHA-256-Hash der Quelldateien -enthält. Typischerweise wird hier mit der @code{base32}-Form der Bytevektor -aus einer Base-32-Zeichenkette generiert. - -Diese Informationen liefert Ihnen der Befehl @code{guix download} -(@pxref{Aufruf von guix download}) oder @code{guix hash} (@pxref{Aufruf von guix hash}). - -@item @code{file-name} (Vorgabe: @code{#f}) -Der Dateiname, unter dem der Quellcode abgespeichert werden sollte. Wenn er -auf @code{#f} steht, wird ein vernünftiger Name automatisch gewählt. Falls -der Quellcode von einer URL geladen wird, wird der Dateiname aus der URL -genommen. Wenn der Quellcode von einem Versionskontrollsystem bezogen wird, -empfiehlt es sich, den Dateinamen ausdrücklich anzugeben, weil dann keine -sprechende Benennung automatisch gefunden werden kann. - -@item @code{patches} (Vorgabe: @code{'()}) -Eine Liste von Dateinamen, Ursprüngen oder dateiähnlichen Objekten -(@pxref{G-Ausdrücke, file-like objects}) mit Patches, welche auf den -Quellcode anzuwenden sind. - -Die Liste von Patches kann nicht von Parametern der Erstellung -abhängen. Insbesondere kann sie nicht vom Wert von @code{%current-system} -oder @code{%current-target-system} abḧängen. - -@item @code{snippet} (Vorgabe: @code{#f}) -Ein im Quellcode-Verzeichnis auszuführender G-Ausdruck -(@pxref{G-Ausdrücke}) oder S-Ausdruck. Hiermit kann der Quellcode bequem -modifiziert werden, manchmal ist dies bequemer als mit einem Patch. - -@item @code{patch-flags} (Vorgabe: @code{'("-p1")}) -Eine Liste der Befehlszeilenoptionen, die dem @code{patch}-Befehl übergeben -werden sollen. - -@item @code{patch-inputs} (Vorgabe: @code{#f}) -Eingabepakete oder -ableitungen für den Patch-Prozess. Bei @code{#f} werden -die üblichen Patcheingaben wie GNU@tie{}Patch bereitgestellt. - -@item @code{modules} (Vorgabe: @code{'()}) -Eine Liste von Guile-Modulen, die während des Patch-Prozesses und während -der Ausführung des @code{snippet}-Felds geladen werden sollten. - -@item @code{patch-guile} (Vorgabe: @code{#f}) -Welches Guile-Paket für den Patch-Prozess benutzt werden sollte. Bei -@code{#f} wird ein vernünftiger Vorgabewert angenommen. -@end table -@end deftp - - -@node Erstellungssysteme -@section Erstellungssysteme - -@cindex Erstellungssystem -Jede Paketdefinition legt ein @dfn{Erstellungssystem} (»build system«) sowie -dessen Argumente fest (@pxref{Pakete definieren}). Das -@code{build-system}-Feld steht für die Erstellungsprozedur des Pakets sowie -für weitere implizite Eingaben für die Erstellungsprozedur. - -Erstellungssysteme sind @code{<build-system>}-Objekte. Die Schnittstelle, um -solche zu erzeugen und zu verändern, ist im Modul @code{(guix build-system)} -zu finden, und die eigentlichen Erstellungssysteme werden jeweils von ihren -eigenen Modulen exportiert. - -@cindex Bag (systemnahe Paketrepräsentation) -Intern funktionieren Erstellungssysteme, indem erst Paketobjekte zu -@dfn{Bags} kompiliert werden. Eine Bag (deutsch: Beutel, Sack) ist wie ein -Paket, aber mit weniger Zierrat — anders gesagt ist eine Bag eine -systemnähere Darstellung eines Pakets, die sämtliche Eingaben des Pakets -einschließlich vom Erstellungssystem hinzugefügter Eingaben enthält. Diese -Zwischendarstellung wird dann zur eigentlichen Ableitung kompiliert -(@pxref{Ableitungen}). - -Erstellungssysteme akzeptieren optional eine Liste von @dfn{Argumenten}. In -Paketdefinitionen werden diese über das @code{arguments}-Feld übergeben -(@pxref{Pakete definieren}). Sie sind in der Regel Schlüsselwort-Argumente -(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile -Reference Manual}). Der Wert dieser Argumente wird normalerweise vom -Erstellungssystem in der @dfn{Erstellungsschicht} ausgewertet, d.h. von -einem durch den Daemon gestarteten Guile-Prozess (@pxref{Ableitungen}). - -Das häufigste Erstellungssystem ist @var{gnu-build-system}, was die übliche -Erstellungsprozedur für GNU-Pakete und viele andere Pakete darstellt. Es -wird vom Modul @code{(guix build-system gnu)} bereitgestellt. - -@defvr {Scheme-Variable} gnu-build-system -@var{gnu-build-system} steht für das GNU-Erstellungssystem und Varianten -desselben (@pxref{Configuration, configuration and makefile conventions,, -standards, GNU Coding Standards}). - -@cindex Erstellungsphasen -Kurz gefasst werden Pakete, die es benutzen, konfiguriert, erstellt und -installiert mit der üblichen Befehlsfolge @code{./configure && make && make -check && make install}. In der Praxis braucht man oft noch ein paar weitere -Schritte. Alle Schritte sind in voneinander getrennte @dfn{Phasen} -unterteilt. Erwähnt werden sollten@footnote{Bitte schauen Sie in den Modulen -unter @code{(guix build gnu-build-system)}, wenn Sie mehr Details zu -Erstellungsphasen brauchen.}: - -@table @code -@item unpack -Den Quell-Tarball entpacken und das Arbeitsverzeichnis wechseln in den -entpackten Quellbaum. Wenn die Quelle bereits ein Verzeichnis ist, wird es -in den Quellbaum kopiert und dorthin gewechselt. - -@item patch-source-shebangs -»Shebangs« in Quelldateien beheben, damit Sie sich auf die richtigen -Store-Dateipfade beziehen. Zum Beispiel könnte @code{#!/bin/sh} zu -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh} geändert werden. - -@item configure -Das Skript @file{configure} mit einigen vorgegebenen Befehlszeilenoptionen -ausführen, wie z.B. mit @code{--prefix=/gnu/store/@dots{}}, sowie mit den im -@code{#:configure-flags}-Argument angegebenen Optionen. - -@item build -@code{make} ausführen mit den Optionen aus der Liste in -@code{#:make-flags}. Wenn das Argument @code{#:parallel-build?} auf wahr -gesetzt ist (was der Vorgabewert ist), wird @code{make -j} zum Erstellen -ausgeführt. - -@item check -@code{make check} (oder statt @code{check} ein anderes bei -@code{#:test-target} angegebenes Ziel) ausführen, außer falls @code{#:tests? -#f} gesetzt ist. Wenn das Argument @code{#:parallel-tests?} auf wahr gesetzt -ist (der Vorgabewert), führe @code{make check -j} aus. - -@item install -@code{make install} mit den in @code{#:make-flags} aufgelisteten Optionen -ausführen. - -@item patch-shebangs -Shebangs in den installierten ausführbaren Dateien beheben. - -@item strip -Symbole zur Fehlerbehebung aus ELF-Dateien entfernen (außer -@code{#:strip-binaries?} ist auf falsch gesetzt) und in die -@code{debug}-Ausgabe kopieren, falls diese verfügbar ist (@pxref{Dateien zur Fehlersuche installieren}). -@end table - -@vindex %standard-phases -Das erstellungsseitige Modul @code{(guix build gnu-build-system)} definiert -@var{%standard-phases} als die vorgegebene Liste der -Erstellungsphasen. @var{%standard-phases} ist eine Liste von Paaren aus je -einem Symbol und einer Prozedur. Letztere implementiert die eigentliche -Phase. - -Die Liste der Phasen, die für ein bestimmtes Paket verwendet werden sollen, -kann vom Parameter @code{#:phases} überschrieben werden. Zum Beispiel werden -bei Übergabe von: - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -alle oben beschriebenen Phasen benutzt außer der @code{configure}-Phase. - -Zusätzlich stellt dieses Erstellungssystem sicher, dass die -»Standard«-Umgebung für GNU-Pakete zur Verfügung steht. Diese umfasst -Werkzeuge wie GCC, libc, Coreutils, Bash, Make, Diffutils, grep und sed -(siehe das Modul @code{(guix build-system gnu)} für eine vollständige -Liste). Wir bezeichnen sie als @dfn{implizite Eingaben} eines Pakets, weil -Paketdefinitionen sie nicht aufführen müssen. -@end defvr - -Andere @code{<build-system>}-Objekte werden definiert, um andere -Konventionen und Werkzeuge von Paketen für freie Software zu -unterstützen. Die anderen Erstellungssysteme erben den Großteil vom -@var{gnu-build-system} und unterscheiden sich hauptsächlich darin, welche -Eingaben dem Erstellungsprozess implizit hinzugefügt werden und welche Liste -von Phasen durchlaufen wird. Manche dieser Erstellungssysteme sind im -Folgenden aufgeführt. - -@defvr {Scheme-Variable} ant-build-system -Diese Variable wird vom Modul @code{(guix build-system ant)} exportiert. Sie -implementiert die Erstellungsprozedur für Java-Pakete, die mit dem -@url{http://ant.apache.org/, Ant build tool} erstellt werden können. - -Sowohl @code{ant} als auch der @dfn{Java Development Kit} (JDK), wie er vom -Paket @code{icedtea} bereitgestellt wird, werden zu den Eingaben -hinzugefügt. Wenn andere Pakete dafür benutzt werden sollen, können sie -jeweils mit den Parametern @code{#:ant} und @code{#:jdk} festgelegt werden. - -Falls das ursprüngliche Paket über keine nutzbare Ant-Erstellungsdatei -(»Ant-Buildfile«) verfügt, kann aus der Angabe im Parameter -@code{#:jar-name} eine minimale Ant-Erstellungsdatei @file{build.xml} -erzeugt werden, in der die für die Erstellung durchzuführenden Aufgaben -(Tasks) für die Erstellung des angegebenen Jar-Archivs stehen. In diesem -Fall kann der Parameter @code{#:source-dir} benutzt werden, um das -Unterverzeichnis mit dem Quellcode anzugeben; sein Vorgabewert ist »src«. - -Der Parameter @code{#:main-class} kann mit einer minimalen -Ant-Erstellungsdatei benutzt werden, um die Hauptklasse des resultierenden -Jar-Archivs anzugeben. Dies ist nötig, wenn die Jar-Datei ausführbar sein -soll. Mit dem Parameter @code{#:test-include} kann eine Liste angegeben -werden, welche Junit-Tests auszuführen sind. Der Vorgabewert ist @code{(list -"**/*Test.java")}. Mit @code{#:test-exclude} kann ein Teil der Testdateien -ignoriert werden. Der Vorgabewert ist @code{(list "**/Abstract*.java")}, -weil abstrakte Klassen keine ausführbaren Tests enthalten können. - -Der Parameter @code{#:build-target} kann benutzt werden, um die Ant-Aufgabe -(Task) anzugeben, die während der @code{build}-Phase ausgeführt werden -soll. Vorgabe ist, dass die Aufgabe (Task) »jar« ausgeführt wird. - -@end defvr - -@defvr {Scheme-Variable} android-ndk-build-system -@cindex Android-Distribution -@cindex Android-NDK-Erstellungssystem -Diese Variable wird von @code{(guix build-system android-ndk)} -exportiert. Sie implementiert eine Erstellungsprozedur für das Android NDK -(Native Development Kit) benutzende Pakete mit einem Guix-spezifischen -Erstellungsprozess. - -Für das Erstellungssystem wird angenommen, dass Pakete die zu ihrer -öffentlichen Schnittstelle gehörenden Header-Dateien im Unterverzeichnis -"include" der Ausgabe "out" und ihre Bibliotheken im Unterverzeichnis "lib" -der Ausgabe "out" platzieren. - -Ebenso wird angenommen, dass es keine im Konflikt stehenden Dateien unter -der Vereinigung aller Abhängigkeiten gibt. - -Derzeit wird Cross-Kompilieren hierfür nicht unterstützt, also wird dabei -vorausgesetzt, dass Bibliotheken und Header-Dateien dieselben wie im -Wirtssystem sind. - -@end defvr - -@defvr {Scheme-Variable} asdf-build-system/source -@defvrx {Scheme-Variable} asdf-build-system/sbcl -@defvrx {Scheme-Variable} asdf-build-system/ecl - -Diese Variablen, die vom Modul @code{(guix build-system asdf)} exportiert -werden, implementieren Erstellungsprozeduren für Common-Lisp-Pakete, welche -@url{https://common-lisp.net/project/asdf/, »ASDF«} benutzen. ASDF dient der -Systemdefinition für Common-Lisp-Programme und -Bibliotheken. - -Das Erstellungssystem @code{asdf-build-system/source} installiert die Pakete -in Quellcode-Form und kann @i{via} ASDF mit jeder -Common-Lisp-Implementierung geladen werden. Die anderen Erstellungssysteme -wie @code{asdf-build-system/sbcl} installieren binäre Systeme in dem Format, -das von einer bestimmten Implementierung verstanden wird. Diese -Erstellungssysteme können auch benutzt werden, um ausführbare Programme zu -erzeugen oder um Lisp-Abbilder mit einem vorab geladenen Satz von Paketen zu -erzeugen. - -Das Erstellungssystem benutzt gewisse Namenskonventionen. Bei Binärpaketen -sollte dem Paketnamen die Lispimplementierung als Präfix vorangehen, -z.B.@code{sbcl-} für @code{asdf-build-system/sbcl}. - -Zudem sollte das entsprechende Quellcode-Paket mit der Konvention wie bei -Python-Paketen (siehe @ref{Python-Module}) ein @code{cl-} als Präfix -bekommen. - -Für Binärpakete sollte für jedes System ein Guix-Paket definiert -werden. Wenn für einen Ursprung im @code{origin} mehrere Systeme enthalten -sind, können Paketvarianten geschrieben werden, mit denen alle Systeme -erstellt werden. Quellpakete, die @code{asdf-build-system/source} benutzen, -können mehrere Systeme enthalten. - -Um ausführbare Programme und Abbilder zu erzeugen, können die -erstellungsseitigen Prozeduren @code{build-program} und @code{build-image} -benutzt werden. Sie sollten in einer Erstellungsphase nach der -@code{create-symlinks}-Phase aufgerufen werden, damit das gerade erstellte -System Teil des resultierenden Abbilds sein kann. An @code{build-program} -muss eine Liste von Common-Lisp-Ausdrücken über das Argument -@code{#:entry-program} übergeben werden. - -Wenn das System nicht in seiner eigenen gleichnamigen @code{.asd}-Datei -definiert ist, sollte der Parameter @code{#:asd-file} benutzt werden, um -anzugeben, in welcher Datei das System definiert ist. Außerdem wird bei -Paketen, für deren Tests ein System in einer separaten Datei definiert -wurde, dieses System geladen, bevor die Tests ablaufen, wenn es im Parameter -@code{#:test-asd-file} steht. Ist dafür kein Wert gesetzt, werden die -Dateien @code{<system>-tests.asd}, @code{<system>-test.asd}, -@code{tests.asd} und @code{test.asd} durchsucht, wenn sie existieren. - -Wenn aus irgendeinem Grund der Paketname nicht den Namenskonventionen folgen -kann, kann der Parameter @code{#:asd-system-name} benutzt werden, um den -Namen des Systems anzugeben. - -@end defvr - -@defvr {Scheme-Variable} cargo-build-system -@cindex Rust-Programmiersprache -@cindex Cargo (Rust-Erstellungssystem) -Diese Variable wird vom Modul @code{(guix build-system cargo)} -exportiert. Damit können Pakete mit Cargo erstellt werden, dem -Erstellungswerkzeug der @uref{https://www.rust-lang.org, -Rust-Programmiersprache}. - -In seiner @code{configure}-Phase ersetzt dieses Erstellungssystem in der -Datei @file{Carto.toml} angegebene Abhängigkeiten durch Eingaben im -Guix-Paket. Die Phase @code{install} installiert die Binärdateien und auch -den Quellcode und die @file{Cargo.toml}-Datei. -@end defvr - -@cindex Clojure (Programmiersprache) -@cindex einfaches Clojure-Erstellungssystem -@defvr {Scheme-Variable} clojure-build-system -Diese Variable wird durch das Modul @code{(guix build-system clojure)} -exportiert. Sie implementiert eine einfache Erstellungsprozedur für in -@uref{https://clojure.org/, Clojure} geschriebene Pakete mit dem guten alten -@code{compile} in Clojure. Cross-Kompilieren wird noch nicht unterstützt. - -Das Erstellungssystem fügt @code{clojure}, @code{icedtea} und @code{zip} zu -den Eingaben hinzu. Sollen stattdessen andere Pakete benutzt werden, können -diese jeweils mit den Parametern @code{#:clojure}, @code{#:jdk} und -@code{#:zip} spezifiziert werden. - -Eine Liste der Quellcode-Verzeichnisse, Test-Verzeichnisse und Namen der -Jar-Dateien können jeweils über die Parameter @code{#:source-dirs}, -@code{#:test-dirs} und @code{#:jar-names} angegeben werden. Das Verzeichnis, -in das kompiliert wird, sowie die Hauptklasse können jeweils mit den -Parametern @code{#:compile-dir} und @code{#:main-class} angegeben -werden. Andere Parameter sind im Folgenden dokumentiert. - -Dieses Erstellungssystem ist eine Erweiterung des @var{ant-build-system}, -bei der aber die folgenden Phasen geändert wurden: - -@table @code - -@item build -Diese Phase ruft @code{compile} in Clojure auf, um Quelldateien zu -kompilieren, und führt @command{jar} aus, um Jar-Dateien aus sowohl -Quelldateien als auch kompilierten Dateien zu erzeugen, entsprechend der -jeweils in @code{#:aot-include} und @code{#:aot-exclude} festgelegten Listen -aus in der Menge der Quelldateien eingeschlossenen und ausgeschlossenen -Bibliotheken. Die Ausschlussliste hat Vorrang vor der Einschlussliste. Diese -Listen setzen sich aus Symbolen zusammen, die für Clojure-Bibliotheken -stehen oder dem Schlüsselwort @code{#:all} entsprechen, was für alle im -Quellverzeichis gefundenen Clojure-Bibliotheken steht. Der Parameter -@code{#:omit-source?} entscheidet, ob Quelldateien in die Jar-Archive -aufgenommen werden sollten. - -@item check -In dieser Phase werden Tests auf die durch Einschluss- und Ausschlussliste -@code{#:test-include} bzw. @code{#:test-exclude} angegebenen Dateien -ausgeführt. Deren Bedeutung ist analog zu @code{#:aot-include} und -@code{#:aot-exclude}, außer dass das besondere Schlüsselwort @code{#:all} -jetzt für alle Clojure-Bibliotheken in den Test-Verzeichnissen steht. Der -Parameter @code{#:tests?} entscheidet, ob Tests ausgeführt werden sollen. - -@item install -In dieser Phase werden alle zuvor erstellten Jar-Dateien installiert. -@end table - -Zusätzlich zu den bereits angegebenen enthält dieses Erstellungssystem noch -eine weitere Phase. - -@table @code - -@item install-doc -Diese Phase installiert alle Dateien auf oberster Ebene, deren Basisnamen -ohne Verzeichnisangabe zu @var{%doc-regex} passen. Ein anderer regulärer -Ausdruck kann mit dem Parameter @code{#:doc-regex} verwendet werden. All die -so gefundenen oder (rekursiv) in den mit @code{#:doc-dirs} angegebenen -Dokumentationsverzeichnissen liegenden Dateien werden installiert. -@end table -@end defvr - -@defvr {Scheme-Variable} cmake-build-system -Diese Variable wird von @code{(guix build-system cmake)} exportiert. Sie -implementiert die Erstellungsprozedur für Pakete, die das -@url{http://www.cmake.org, CMake-Erstellungswerkzeug} benutzen. - -Das Erstellungssystem fügt automatisch das Paket @code{cmake} zu den -Eingaben hinzu. Welches Paket benutzt wird, kann mit dem Parameter -@code{#:cmake} geändert werden. - -Der Parameter @code{#:configure-flags} wird als Liste von -Befehlszeilenoptionen aufgefasst, die an den Befehl @command{cmake} -übergeben werden. Der Parameter @code{#:build-type} abstrahiert, welche -Befehlszeilenoptionen dem Compiler übergeben werden; der Vorgabewert ist -@code{"RelWithDebInfo"} (kurz für »release mode with debugging -information«), d.h. kompiliert wird für eine Produktionsumgebung und -Informationen zur Fehlerbehebung liegen bei, was ungefähr @code{-O2 -g} -entspricht, wie bei der Vorgabe für Autoconf-basierte Pakete. -@end defvr - -@defvr {Scheme Variable} dune-build-system -This variable is exported by @code{(guix build-system dune)}. It supports -builds of packages using @uref{https://dune.build/, Dune}, a build tool for -the OCaml programming language. It is implemented as an extension of the -@code{ocaml-build-system} which is described below. As such, the -@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build -system. - -It automatically adds the @code{dune} package to the set of inputs. Which -package is used can be specified with the @code{#:dune} parameter. - -There is no @code{configure} phase because dune packages typically don't -need to be configured. The @code{#:build-flags} parameter is taken as a -list of flags passed to the @code{dune} command during the build. - -The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} -command instead of the more recent @code{dune} command while building a -package. Its default value is @code{#f}. -@end defvr - -@defvr {Scheme-Variable} go-build-system -Diese Variable wird vom Modul @code{(guix build-system go)} exportiert. Mit -ihr ist eine Erstellungsprozedur für Go-Pakete implementiert, die dem -normalen -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, -Go-Erstellungsmechanismus} entspricht. - -Beim Aufruf wird ein Wert für den Schlüssel @code{#:import-path} und -manchmal auch für @code{#:unpack-path} erwartet. Der -@url{https://golang.org/doc/code.html#ImportPaths, »import path«} entspricht -dem Dateisystempfad, den die Erstellungsskripts des Pakets und darauf Bezug -nehmende Pakete erwarten; durch ihn wird ein Go-Paket eindeutig -bezeichnet. Typischerweise setzt er sich aus einer Kombination der -entfernten URI des Paketquellcodes und der Dateisystemhierarchie -zusammen. Manchmal ist es nötig, den Paketquellcode in ein anderes als das -vom »import path« bezeichnete Verzeichnis zu entpacken; diese andere -Verzeichnisstruktur sollte dann als @code{#:unpack-path} angegeben werden. - -Pakete, die Go-Bibliotheken zur Verfügung stellen, sollten zusammen mit -ihrem Quellcode installiert werden. Der Schlüssel @code{#:install-source?}, -sein Vorgabewert ist @code{#t}, steuert, ob Quellcode installiert wird. Bei -Paketen, die nur ausführbare Dateien liefern, kann der Wert auf @code{#f} -gesetzt werden. -@end defvr - -@defvr {Scheme-Variable} glib-or-gtk-build-system -Diese Variable wird vom Modul @code{(guix build-system glib-or-gtk)} -exportiert. Sie ist für Pakete gedacht, die GLib oder GTK benutzen. - -Dieses Erstellungssystem fügt die folgenden zwei Phasen zu denen von -@var{gnu-build-system} hinzu: - -@table @code -@item glib-or-gtk-wrap -Die Phase @code{glib-or-gtk-wrap} stellt sicher, dass Programme in -@file{bin/} in der Lage sind, GLib-»Schemata« und -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK-Module} -zu finden. Dazu wird für das Programm ein Wrapper-Skript erzeugt, dass das -eigentliche Programm mit den richtigen Werten für die Umgebungsvariablen -@code{XDG_DATA_DIRS} und @code{GTK_PATH} aufruft. - -Es ist möglich, bestimmte Paketausgaben von diesem Wrapping-Prozess -auszunehmen, indem Sie eine Liste ihrer Namen im Parameter -@code{#:glib-or-gtk-wrap-excluded-outputs} angeben. Das ist nützlich, wenn -man von einer Ausgabe weiß, dass sie keine Binärdateien enthält, die GLib -oder GTK benutzen, und diese Ausgabe durch das Wrappen ohne Not eine weitere -Abhängigkeit von GLib und GTK bekäme. - -@item glib-or-gtk-compile-schemas -Mit der Phase @code{glib-or-gtk-compile-schemas} wird sichergestellt, dass -alle @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -GSettings-Schemata} für GLib kompiliert werden. Dazu wird das Programm -@command{glib-compile-schemas} ausgeführt. Es kommt aus dem Paket -@code{glib:bin}, was automatisch vom Erstellungssystem importiert -wird. Welches @code{glib}-Paket dieses @command{glib-compile-schemas} -bereitstellt, kann mit dem Parameter @code{#:glib} spezifiziert werden. -@end table - -Beide Phasen finden nach der @code{install}-Phase statt. -@end defvr - -@defvr {Scheme-Variable} guile-build-system -Dieses Erstellungssystem ist für Guile-Pakete gedacht, die nur aus -Scheme-Code bestehen und so schlicht sind, dass sie nicht einmal ein -Makefile und erst recht keinen @file{configure}-Skript enthalten. Hierzu -wird Scheme-Code mit @command{guild compile} kompiliert -(@pxref{Compilation,,, guile, GNU Guile Reference Manual}) und die -@file{.scm}- und @file{.go}-Dateien an den richtigen Pfad installiert. Auch -Dokumentation wird installiert. - -Das Erstellungssystem unterstützt Cross-Kompilieren durch die -Befehlszeilenoption @code{--target} für @command{guild compile}. - -Mit @code{guile-build-system} erstellte Pakete müssen ein Guile-Paket in -ihrem @code{native-inputs}-Feld aufführen. -@end defvr - -@defvr {Scheme-Variable} minify-build-system -Diese Variable wird vom Modul @code{(guix build-system minify)} -exportiert. Sie implementiert eine Prozedur zur Minifikation einfacher -JavaScript-Pakete. - -Es fügt @code{uglify-js} zur Menge der Eingaben hinzu und komprimiert damit -alle JavaScript-Dateien im @file{src}-Verzeichnis. Ein anderes Programm zur -Minifikation kann verwendet werden, indem es mit dem Parameter -@code{#:uglify-js} angegeben wird; es wird erwartet, dass das angegebene -Paket den minifizierten Code auf der Standardausgabe ausgibt. - -Wenn die Eingabe-JavaScript-Dateien nicht alle im @file{src}-Verzeichnis -liegen, kann mit dem Parameter @code{#:javascript-files} eine Liste der -Dateinamen übergeben werden, auf die das Minifikationsprogramm aufgerufen -wird. -@end defvr - -@defvr {Scheme-Variable} ocaml-build-system -Diese Variable wird vom Modul @code{(guix build-system ocaml)} -exportiert. Mit ihr ist ein Erstellungssystem für @uref{https://ocaml.org, -OCaml}-Pakete implementiert, was bedeutet, dass es die richtigen -auszuführenden Befehle für das jeweilige Paket auswählt. OCaml-Pakete können -sehr unterschiedliche Befehle erwarten. Dieses Erstellungssystem probiert -manche davon durch. - -Wenn im Paket eine Datei @file{setup.ml} auf oberster Ebene vorhanden ist, -wird @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} und -@code{ocaml setup.ml -install} ausgeführt. Das Erstellungssystem wird -annehmen, dass die Datei durch @uref{http://oasis.forge.ocamlcore.org/, -OASIS} erzeugt wurde, und wird das Präfix setzen und Tests aktivieren, wenn -diese nicht abgeschaltet wurden. Sie können Befehlszeilenoptionen zum -Konfigurieren und Erstellen mit den Parametern @code{#:configure-flags} und -@code{#:build-flags} übergeben. Der Schlüssel @code{#:test-flags} kann -übergeben werden, um die Befehlszeilenoptionen zu ändern, mit denen die -Tests aktiviert werden. Mit dem Parameter @code{#:use-make?} kann dieses -Erstellungssystem für die build- und install-Phasen abgeschaltet werden. - -Verfügt das Paket über eine @file{configure}-Datei, wird angenommen, dass -diese von Hand geschrieben wurde mit einem anderen Format für Argumente als -bei einem Skript des @code{gnu-build-system}. Sie können weitere -Befehlszeilenoptionen mit dem Schlüssel @code{#:configure-flags} hinzufügen. - -Falls dem Paket ein @file{Makefile} beiliegt (oder @code{#:use-make?} auf -@code{#t} gesetzt wurde), wird dieses benutzt und weitere -Befehlszeilenoptionen können mit dem Schlüssel @code{#:make-flags} zu den -build- und install-Phasen hinzugefügt werden. - -Letztlich gibt es in manchen Pakete keine solchen Dateien, sie halten sich -aber an bestimmte Konventionen, wo ihr eigenes Erstellungssystem zu finden -ist. In diesem Fall führt Guix’ OCaml-Erstellungssystem @code{ocaml -pkg/pkg.ml} oder @code{ocaml pkg/build.ml} aus und kümmert sich darum, dass -der Pfad zu dem benötigten findlib-Modul passt. Weitere -Befehlszeilenoptionen können über den Schlüssel @code{#:build-flags} -übergeben werden. Um die Installation kümmert sich -@command{opam-installer}. In diesem Fall muss das @code{opam}-Paket im -@code{native-inputs}-Feld der Paketdefinition stehen. - -Beachten Sie, dass die meisten OCaml-Pakete davon ausgehen, dass sie in -dasselbe Verzeichnis wie OCaml selbst installiert werden, was wir in Guix -aber nicht so haben wollen. Solche Pakete installieren ihre -@file{.so}-Dateien in das Verzeichnis ihres Moduls, was für die meisten -anderen Einrichtungen funktioniert, weil es im OCaml-Compilerverzeichnis -liegt. Jedoch können so in Guix die Bibliotheken nicht gefunden werden, -deswegen benutzen wir @code{CAML_LD_LIBRARY_PATH}. Diese Umgebungsvariable -zeigt auf @file{lib/ocaml/site-lib/stubslibs} und dorthin sollten -@file{.so}-Bibliotheken installiert werden. -@end defvr - -@defvr {Scheme-Variable} python-build-system -Diese Variable wird vom Modul @code{(guix build-system python)} -exportiert. Sie implementiert mehr oder weniger die konventionelle -Erstellungsprozedur, wie sie für Python-Pakete üblich ist, d.h. erst wird -@code{python setup.py build} ausgeführt und dann @code{python setup.py -install --prefix=/gnu/store/@dots{}}. - -Für Pakete, die eigenständige Python-Programme nach @code{bin/} -installieren, sorgt dieses Erstellungssystem dafür, dass die Programme in -ein Wrapper-Skript verpackt werden, welches die eigentlichen Programme mit -einer Umgebungsvariablen @code{PYTHONPATH} aufruft, die alle -Python-Bibliotheken auflistet, von denen die Programme abhängen. - -Welches Python-Paket benutzt wird, um die Erstellung durchzuführen, kann mit -dem Parameter @code{#:python} bestimmt werden. Das ist nützlich, wenn wir -erzwingen wollen, dass ein Paket mit einer bestimmten Version des -Python-Interpretierers arbeitet, was nötig sein kann, wenn das Programm nur -mit einer einzigen Interpretiererversion kompatibel ist. - -Standardmäßig ruft Guix @code{setup.py} auf, was zu @code{setuptools} -gehört, ähnlich wie es auch @command{pip} tut. Manche Pakete sind mit -setuptools (und pip) inkompatibel, deswegen können Sie diese Einstellung -abschalten, indem Sie den Parameter @code{#:use-setuptools} auf @code{#f} -setzen. -@end defvr - -@defvr {Scheme-Variable} perl-build-system -Diese Variable wird vom Modul @code{(guix build-system perl)} -exportiert. Mit ihr wird die Standard-Erstellungsprozedur für Perl-Pakete -implementiert, welche entweder darin besteht, @code{perl Build.PL ---prefix=/gnu/store/@dots{}} gefolgt von @code{Build} und @code{Build -install} auszuführen, oder @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}} -gefolgt von @code{make} und @code{make install} auszuführen, je nachdem, ob -eine Datei @code{Build.PL} oder eine Datei @code{Makefile.PL} in der -Paketdistribution vorliegt. Den Vorrang hat erstere, wenn sowohl -@code{Build.PL} als auch @code{Makefile.PL} in der Paketdistribution -existieren. Der Vorrang kann umgekehrt werden, indem @code{#t} für den -Parameter @code{#:make-maker?} angegeben wird. - -Der erste Aufruf von @code{perl Makefile.PL} oder @code{perl Build.PL} -übergibt die im Parameter @code{#:make-maker-flags} -bzw. @code{#:module-build-flags} angegebenen Befehlszeilenoptionen, je -nachdem, was verwendet wird. - -Welches Perl-Paket dafür benutzt wird, kann mit @code{#:perl} angegeben -werden. -@end defvr - -@defvr {Scheme-Variable} r-build-system -Diese Variable wird vom Modul @code{(guix build-system r)} exportiert. Sie -entspricht einer Implementierung der durch @uref{http://r-project.org, -R}-Pakete genutzten Erstellungsprozedur, die wenig mehr tut, als @code{R CMD -INSTALL --library=/gnu/store/@dots{}} in einer Umgebung auszuführen, in der -die Umgebungsvariable @code{R_LIBS_SITE} die Pfade aller R-Pakete unter den -Paketeingaben enthält. Tests werden nach der Installation mit der R-Funktion -@code{tools::testInstalledPackage} ausgeführt. -@end defvr - -@defvr {Scheme-Variable} texlive-build-system -Diese Variable wird vom Modul @code{(guix build-system texlive)} -exportiert. Mit ihr werden TeX-Pakete in Stapelverarbeitung (»batch mode«) -mit der angegebenen Engine erstellt. Das Erstellungssystem setzt die -Variable @code{TEXINPUTS} so, dass alle TeX-Quelldateien unter den Eingaben -gefunden werden können. - -Standardmäßig wird @code{luatex} auf allen Dateien mit der Dateiendung -@code{ins} ausgeführt. Eine andere Engine oder ein anderes Format kann mit -dem Argument @code{#:tex-format} angegeben werden. Verschiedene -Erstellungsziele können mit dem Argument @code{#:build-targets} festgelegt -werden, das eine Liste von Dateinamen erwartet. Das Erstellungssystem fügt -nur @code{texlive-bin} und @code{texlive-latex-base} zu den Eingaben hinzu -(beide kommen aus dem Modul @code{(gnu packages tex}). Für beide kann das zu -benutzende Paket jeweils mit den Argumenten @code{#:texlive-bin} oder -@code{#:texlive-latex-base} geändert werden. - -Der Parameter @code{#:tex-directory} sagt dem Erstellungssystem, wohin die -installierten Dateien im texmf-Verzeichnisbaum installiert werden sollen. -@end defvr - -@defvr {Scheme-Variable} ruby-build-system -Diese Variable wird vom Modul @code{(guix build-system ruby)} -exportiert. Sie steht für eine Implementierung der -RubyGems-Erstellungsprozedur, die für Ruby-Pakete benutzt wird, wobei -@code{gem build} gefolgt von @code{gem install} ausgeführt wird. - -Das @code{source}-Feld eines Pakets, das dieses Erstellungssystem benutzt, -verweist typischerweise auf ein Gem-Archiv, weil Ruby-Entwickler dieses -Format benutzen, wenn sie ihre Software veröffentlichen. Das -Erstellungssystem entpackt das Gem-Archiv, spielt eventuell Patches für den -Quellcode ein, führt die Tests aus, verpackt alles wieder in ein Gem-Archiv -und installiert dieses. Neben Gem-Archiven darf das Feld auch auf -Verzeichnisse und Tarballs verweisen, damit es auch möglich ist, -unveröffentlichte Gems aus einem Git-Repository oder traditionelle -Quellcode-Veröffentlichungen zu benutzen. - -Welches Ruby-Paket benutzt werden soll, kann mit dem Parameter @code{#:ruby} -festgelegt werden. Eine Liste zusätzlicher Befehlszeilenoptionen für den -Aufruf des @command{gem}-Befehls kann mit dem Parameter @code{#:gem-flags} -angegeben werden. -@end defvr - -@defvr {Scheme-Variable} waf-build-system -Diese Variable wird durch das Modul @code{(guix build-system waf)} -exportiert. Damit ist eine Erstellungsprozedur rund um das @code{waf}-Skript -implementiert. Die üblichen Phasen — @code{configure}, @code{build} und -@code{install} — sind implementiert, indem deren Namen als Argumente an das -@code{waf}-Skript übergeben werden. - -Das @code{waf}-Skript wird vom Python-Interpetierer ausgeführt. Mit welchem -Python-Paket das Skript ausgeführt werden soll, kann mit dem Parameter -@code{#:python} angegeben werden. -@end defvr - -@defvr {Scheme-Variable} scons-build-system -Diese Variable wird vom Modul @code{(guix build-system scons)} -exportiert. Sie steht für eine Implementierung der Erstellungsprozedur, die -das SCons-Softwarekonstruktionswerkzeug (»software construction tool«) -benutzt. Das Erstellungssystem führt @code{scons} aus, um das Paket zu -erstellen, führt mit @code{scons test} Tests aus und benutzt @code{scons -install}, um das Paket zu installieren. - -Zusätzliche Optionen, die an @code{scons} übergeben werden sollen, können -mit dem Parameter @code{#:scons-flags} angegeben werden. Die Python-Version, -die benutzt werden soll, um SCons auszuführen, kann festgelegt werden, indem -das passende SCons-Paket mit dem Parameter @code{#:scons} ausgewählt wird. -@end defvr - -@defvr {Scheme-Variable} haskell-build-system -Diese Variable wird vom Modul @code{(guix build-system haskell)} -exportiert. Sie bietet Zugang zur Cabal-Erstellungsprozedur, die von -Haskell-Paketen benutzt wird, was bedeutet, @code{runhaskell Setup.hs -configure --prefix=/gnu/store/@dots{}} und @code{runhaskell Setup.hs build} -auszuführen. Statt das Paket mit dem Befehl @code{runhaskell Setup.hs -install} zu installieren, benutzt das Erstellungssystem @code{runhaskell -Setup.hs copy} gefolgt von @code{runhaskell Setup.hs register}, um keine -Bibliotheken im Store-Verzeichnis des Compilers zu speichern, auf dem keine -Schreibberechtigung besteht. Zusätzlich generiert das Erstellungssystem -Dokumentation durch Ausführen von @code{runhaskell Setup.hs haddock}, außer -@code{#:haddock? #f} wurde übergeben. Optional können an Haddock Parameter -mit Hilfe des Parameters @code{#:haddock-flags} übergeben werden. Wird die -Datei @code{Setup.hs} nicht gefunden, sucht das Erstellungssystem -stattdessen nach @code{Setup.lhs}. - -Welcher Haskell-Compiler benutzt werden soll, kann über den -@code{#:haskell}-Parameter angegeben werden. Als Vorgabewert verwendet er -@code{ghc}. -@end defvr - -@defvr {Scheme-Variable} dub-build-system -Diese Variable wird vom Modul @code{(guix build-system dub)} exportiert. Sie -verweist auf eine Implementierung des Dub-Erstellungssystems, das von -D-Paketen benutzt wird. Dabei werden @code{dub build} und @code{dub run} -ausgeführt. Die Installation wird durch manuelles Kopieren der Dateien -durchgeführt. - -Welcher D-Compiler benutzt wird, kann mit dem Parameter @code{#:ldc} -festgelegt werden, was als Vorgabewert @code{ldc} benutzt. -@end defvr - -@defvr {Scheme-Variable} emacs-build-system -Diese Variable wird vom Modul @code{(guix build-system emacs)} -exportiert. Darin wird eine Installationsprozedur ähnlich der des -Paketsystems von Emacs selbst implementiert (@pxref{Packages,,, emacs, The -GNU Emacs Manual}). - -Zunächst wird eine Datei @code{@var{Paket}-autoloads.el} erzeugt, dann -werden alle Emacs-Lisp-Dateien zu Bytecode kompiliert. Anders als beim -Emacs-Paketsystem werden die Info-Dokumentationsdateien in das -Standardverzeichnis für Dokumentation verschoben und die Datei @file{dir} -gelöscht. Jedes Paket wird in sein eigenes Verzeichnis unter -@file{share/emacs/site-lisp/guix.d} installiert. -@end defvr - -@defvr {Scheme-Variable} font-build-system -This variable is exported by @code{(guix build-system font)}. It implements -an installation procedure for font packages where upstream provides -pre-compiled TrueType, OpenType, etc.@: font files that merely need to be -copied into place. It copies font files to standard locations in the output -directory. -@end defvr - -@defvr {Scheme-Variable} meson-build-system -Diese Variable wird vom Modul @code{(guix build-system meson)} -exportiert. Sie enthält die Erstellungsprozedur für Pakete, die -@url{http://mesonbuild.com, Meson} als ihr Erstellungssystem benutzen. - -Mit ihr werden sowohl Meson als auch @uref{https://ninja-build.org/, Ninja} -zur Menge der Eingaben hinzugefügt; die Pakete dafür können mit den -Parametern @code{#:meson} und @code{#:ninja} geändert werden, wenn -nötig. Das vorgegebene Meson-Paket ist @code{meson-for-build}, ein -besonderes Paket, dessen Besonderheit darin besteht, den @code{RUNPATH} von -Binärdateien und Bibliotheken @emph{nicht} zu entfernen, wenn sie -installiert werden. - -Dieses Erstellungssystem ist eine Erweiterung für das -@var{gnu-build-system}, aber mit Änderungen an den folgenden Phasen, die -Meson-spezifisch sind: - -@table @code - -@item configure -Diese Phase führt den @code{meson}-Befehl mit den in -@code{#:configure-flags} angegebenen Befehlszeilenoptionen aus. Die -Befehlszeilenoption @code{--build-type} wird immer auf @code{plain} gesetzt, -solange nichts anderes mit dem Parameter @code{#:build-type} angegeben -wurde. - -@item build -Diese Phase ruft @code{ninja} auf, um das Paket standardmäßig parallel zu -erstellen. Die Vorgabeeinstellung, dass parallel erstellt wird, kann -verändert werden durch Setzen von @code{#:parallel-build?}. - -@item check -Diese Phase führt @code{ninja} mit dem als @code{#:test-target} -spezifizierten Ziel für Tests auf, der Vorgabewert ist das Ziel namens -@code{"test"}. - -@item install -Diese Phase führt @code{ninja install} aus und kann nicht verändert werden. -@end table - -Dazu fügt das Erstellungssystem noch folgende neue Phasen: - -@table @code - -@item fix-runpath -In dieser Phase wird sichergestellt, dass alle Binärdateien die von ihnen -benötigten Bibliotheken finden können. Die benötigten Bibliotheken werden in -den Unterverzeichnissen des Pakets, das erstellt wird, gesucht, und zum -@code{RUNPATH} hinzugefügt, wann immer es nötig ist. Auch werden diejenigen -Referenzen zu Bibliotheken aus der Erstellungsphase wieder entfernt, die bei -@code{meson-for-build} hinzugefügt wurden, aber eigentlich zur Laufzeit -nicht gebraucht werden, wie Abhängigkeiten nur für Tests. - -@item glib-or-gtk-wrap -Diese Phase ist dieselbe, die auch im @code{glib-or-gtk-build-system} zur -Verfügung gestellt wird, und mit Vorgabeeinstellungen wird sie nicht -durchlaufen. Wenn sie gebraucht wird, kann sie mit dem Parameter -@code{#:glib-or-gtk?} aktiviert werden. - -@item glib-or-gtk-compile-schemas -Diese Phase ist dieselbe, die auch im @code{glib-or-gtk-build-system} zur -Verfügung gestellt wird, und mit Vorgabeeinstellungen wird sie nicht -durchlaufen. Wenn sie gebraucht wird, kann sie mit dem Parameter -@code{#:glib-or-gtk?} aktiviert werden. -@end table -@end defvr - -Letztlich gibt es für die Pakete, die bei weitem nichts so komplexes -brauchen, ein »triviales« Erstellungssystem. Es ist in dem Sinn trivial, -dass es praktisch keine Hilfestellungen gibt: Es fügt keine impliziten -Eingaben hinzu und hat kein Konzept von Erstellungsphasen. - -@defvr {Scheme-Variable} trivial-build-system -Diese Variable wird vom Modul @code{(guix build-system trivial)} exportiert. - -Diesem Erstellungssystem muss im Argument @code{#:builder} ein -Scheme-Ausdruck übergeben werden, der die Paketausgabe(n) erstellt — wie bei -@code{build-expression->derivation} (@pxref{Ableitungen, -@code{build-expression->derivation}}). -@end defvr - -@node Der Store -@section Der Store - -@cindex Store -@cindex Store-Objekte -@cindex Store-Pfade - -Konzeptionell ist der @dfn{Store} der Ort, wo Ableitungen nach erfolgreicher -Erstellung gespeichert werden — standardmäßig finden Sie ihn in -@file{/gnu/store}. Unterverzeichnisse im Store werden @dfn{Store-Objekte} -oder manchmal auch @dfn{Store-Pfade} genannt. Mit dem Store ist eine -Datenbank assoziiert, die Informationen enthält wie zum Beispiel, welche -Store-Pfade jeder Store-Pfad jeweils referenziert, und eine Liste, welche -Store-Objekte @emph{gültig} sind, also Ergebnisse erfolgreicher Erstellungen -sind. Die Datenbank befindet sich in @file{@var{localstatedir}/guix/db}, -wobei @var{localstatedir} das mit @option{--localstatedir} bei der -Ausführung von »configure« angegebene Zustandsverzeichnis ist, normalerweise -@file{/var}. - -Auf den Store wird @emph{nur} durch den Daemon im Auftrag seiner Clients -zugegriffen (@pxref{Aufruf des guix-daemon}). Um den Store zu verändern, -verbinden sich Clients über einen Unix-Socket mit dem Daemon, senden ihm -entsprechende Anfragen und lesen dann dessen Antwort — so etwas nennt sich -entfernter Prozeduraufruf (englisch »Remote Procedure Call« oder kurz RPC). - -@quotation Anmerkung -Benutzer dürfen @emph{niemals} Dateien in @file{/gnu/store} direkt -verändern, sonst wären diese nicht mehr konsistent und die Grundannahmen im -funktionalen Modell von Guix, dass die Objekte unveränderlich sind, wären -dahin (@pxref{Einführung}). - -Siehe @xref{Aufruf von guix gc, @command{guix gc --verify}}, für -Informationen, wie die Integrität des Stores überprüft und nach -versehentlichen Veränderungen unter Umständen wiederhergestellt werden kann. -@end quotation - -Das Modul @code{(guix store)} bietet Prozeduren an, um sich mit dem Daemon -zu verbinden und entfernte Prozeduraufrufe durchzuführen. Diese werden im -Folgenden beschrieben. Das vorgegebene Verhalten von @code{open-connection}, -und daher allen @command{guix}-Befehlen, ist, sich mit dem lokalen Daemon -oder dem an der in der Umgebungsvariablen @code{GUIX_DAEMON_SOCKET} -angegeben URL zu verbinden. - -@defvr {Umgebungsvariable} GUIX_DAEMON_SOCKET -Ist diese Variable gesetzt, dann sollte ihr Wert ein Dateipfad oder eine URI -sein, worüber man sich mit dem Daemon verbinden kann. Ist der Wert der Pfad -zu einer Datei, bezeichnet dieser einen Unix-Socket, mit dem eine Verbindung -hergestellt werden soll. Ist er eine URI, so werden folgende URI-Schemata -unterstützt: - -@table @code -@item file -@itemx unix -Für Unix-Sockets. @code{file:///var/guix/daemon-socket/socket} kann -gleichbedeutend auch als @file{/var/guix/daemon-socket/socket} angegeben -werden. - -@item guix -@cindex Daemon, Fernzugriff -@cindex Fernzugriff auf den Daemon -@cindex Daemon, Einrichten auf Clustern -@cindex Cluster, Einrichtung des Daemons -Solche URIs benennen Verbindungen über TCP/IP ohne Verschlüsselung oder -Authentifizierung des entfernten Rechners. Die URI muss den Hostnamen, also -den Rechnernamen des entfernten Rechners, und optional eine Port-Nummer -angeben (sonst wird als Vorgabe der Port 44146 benutzt): - -@example -guix://master.guix.example.org:1234 -@end example - -Diese Konfiguration ist für lokale Netzwerke wie etwa in Rechen-Clustern -geeignet, wo sich nur vertrauenswürdige Knoten mit dem Erstellungs-Daemon -z.B. unter @code{master.guix.example.org} verbinden können. - -Die Befehlszeilenoption @code{--listen} von @command{guix-daemon} kann -benutzt werden, damit er auf TCP-Verbindungen lauscht (@pxref{Aufruf des guix-daemon, @code{--listen}}). - -@item ssh -@cindex SSH-Zugriff auf Erstellungs-Daemons -Mit solchen URIs kann eine Verbindung zu einem entfernten Daemon über SSH -hergestellt werden@footnote{Diese Funktionalitäts setzt Guile-SSH voraus -(@pxref{Voraussetzungen}).}. Eine typische URL sieht so aus: - -@example -ssh://charlie@@guix.example.org:22 -@end example - -Was @command{guix copy} betrifft, richtet es sich nach den üblichen -OpenSSH-Client-Konfigurationsdateien (@pxref{Aufruf von guix copy}). -@end table - -In Zukunft könnten weitere URI-Schemata unterstützt werden. - -@c XXX: Remove this note when the protocol incurs fewer round trips -@c and when (guix derivations) no longer relies on file system access. -@quotation Anmerkung -Die Fähigkeit, sich mit entfernten Erstellungs-Daemons zu verbinden, sehen -wir als experimentell an, Stand @value{VERSION}. Bitte diskutieren Sie mit -uns jegliche Probleme oder Vorschläge, die Sie haben könnten -(@pxref{Mitwirken}). -@end quotation -@end defvr - -@deffn {Scheme-Prozedur} open-connection [@var{Uri}] [#:reserve-space? #t] -Sich mit dem Daemon über den Unix-Socket an @var{Uri} verbinden (einer -Zeichenkette). Wenn @var{reserve-space?} wahr ist, lässt ihn das etwas -zusätzlichen Speicher im Dateisystem reservieren, damit der Müllsammler auch -dann noch funktioniert, wenn die Platte zu voll wird. Liefert ein -Server-Objekt. - -@var{Uri} nimmt standardmäßig den Wert von @var{%default-socket-path} an, -was dem bei der Installation mit dem Aufruf von @command{configure} -ausgewählten Vorgabeort entspricht, gemäß den Befehlszeilenoptionen, mit -denen @command{configure} aufgerufen wurde. -@end deffn - -@deffn {Scheme-Prozedur} close-connection @var{Server} -Die Verbindung zum @var{Server} trennen. -@end deffn - -@defvr {Scheme-Variable} current-build-output-port -Diese Variable ist an einen SRFI-39-Parameter gebunden, der auf den -Scheme-Port verweist, an den vom Daemon empfangene Erstellungsprotokolle und -Fehlerprotokolle geschrieben werden sollen. -@end defvr - -Prozeduren, die entfernte Prozeduraufrufe durchführen, nehmen immer ein -Server-Objekt als ihr erstes Argument. - -@deffn {Scheme-Prozedur} valid-path? @var{Server} @var{Pfad} -@cindex ungültige Store-Objekte -Liefert @code{#t}, wenn der @var{Pfad} ein gültiges Store-Objekt benennt, -und sonst @code{#f} (ein ungültiges Objekt kann auf der Platte gespeichert -sein, tatsächlich aber ungültig sein, zum Beispiel weil es das Ergebnis -einer abgebrochenen oder fehlgeschlagenen Erstellung ist). - -A @code{&store-protocol-error} condition is raised if @var{path} is not -prefixed by the store directory (@file{/gnu/store}). -@end deffn - -@deffn {Scheme-Prozedur} add-text-to-store @var{Server} @var{Name} @var{Text} [@var{Referenzen}] -Den @var{Text} im Store in einer Datei namens @var{Name} ablegen und ihren -Store-Pfad zurückliefern. @var{Referenzen} ist die Liste der Store-Pfade, -die der Store-Pfad dann referenzieren soll. -@end deffn - -@deffn {Scheme-Prozedur} build-derivations @var{Server} @var{Ableitungen} -Die @var{Ableitungen} erstellen (eine Liste von @code{<derivation>}-Objekten -oder von Pfaden zu Ableitungen) und terminieren, sobald der Worker-Prozess -mit dem Erstellen fertig ist. Liefert @code{#t} bei erfolgreicher -Erstellung. -@end deffn - -Es sei erwähnt, dass im Modul @code{(guix monads)} eine Monade sowie -monadische Versionen obiger Prozeduren angeboten werden, damit an Code, der -auf den Store zugreift, bequemer gearbeitet werden kann (@pxref{Die Store-Monade}). - -@c FIXME -@i{Dieser Abschnitt ist im Moment noch unvollständig.} - -@node Ableitungen -@section Ableitungen - -@cindex Ableitungen -Systemnahe Erstellungsaktionen sowie die Umgebung, in der selbige -durchzuführen sind, werden durch @dfn{Ableitungen} dargestellt. Eine -Ableitung enthält folgende Informationen: - -@itemize -@item -Die Ausgaben, die die Ableitung hat. Ableitungen erzeugen mindestens eine -Datei bzw. ein Verzeichnis im Store, können aber auch mehrere erzeugen. - -@item -@cindex build-time dependencies -@cindex dependencies, build-time -The inputs of the derivations---i.e., its build-time dependencies---which -may be other derivations or plain files in the store (patches, build -scripts, etc.) - -@item -Das System, wofür mit der Ableitung erstellt wird, also ihr Ziel — -z.B. @code{x86_64-linux}. - -@item -Der Dateiname eines Erstellungsskripts im Store, zusammen mit den -Argumenten, mit denen es aufgerufen werden soll. - -@item -Eine Liste zu definierender Umgebungsvariabler. - -@end itemize - -@cindex Ableitungspfad -Ableitungen ermöglichen es den Clients des Daemons, diesem -Erstellungsaktionen für den Store mitzuteilen. Es gibt davon zwei Arten, -sowohl Darstellungen im Arbeitsspeicher jeweils für Client und Daemon, als -auch Dateien im Store, deren Namen auf @code{.drv} enden — diese Dateien -werden als @dfn{Ableitungspfade} bezeichnet. Ableitungspfade können an die -Prozedur @code{build-derivations} übergeben werden, damit die darin -niedergeschriebenen Erstellungsaktionen durchgeführt werden (@pxref{Der Store}). - -@cindex Ableitungen mit fester Ausgabe -Operationen wie das Herunterladen von Dateien und Checkouts von unter -Versionskontrolle stehenden Quelldateien, bei denen der Hash des Inhalts im -Voraus bekannt ist, werden als @dfn{Ableitungen mit fester Ausgabe} -modelliert. Anders als reguläre Ableitungen sind die Ausgaben von -Ableitungen mit fester Ausgabe unabhängig von ihren Eingaben — z.B. liefert -das Herunterladen desselben Quellcodes dasselbe Ergebnis unabhängig davon, -mit welcher Methode und welchen Werkzeugen er heruntergeladen wurde. - -@cindex references -@cindex run-time dependencies -@cindex dependencies, run-time -The outputs of derivations---i.e., the build results---have a set of -@dfn{references}, as reported by the @code{references} RPC or the -@command{guix gc --references} command (@pxref{Aufruf von guix gc}). -References are the set of run-time dependencies of the build results. -References are a subset of the inputs of the derivation; this subset is -automatically computed by the build daemon by scanning all the files in the -outputs. - -Das Modul @code{(guix derivations)} stellt eine Repräsentation von -Ableitungen als Scheme-Objekte zur Verfügung, zusammen mit Prozeduren, um -Ableitungen zu erzeugen und zu manipulieren. Die am wenigsten abstrahierte -Methode, eine Ableitung zu erzeugen, ist mit der Prozedur @code{derivation}: - -@deffn {Scheme-Prozedur} derivation @var{Store} @var{Name} @var{Ersteller} @ - @var{Argumente} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ -[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ [#:system -(%current-system)] [#:references-graphs #f] @ [#:allowed-references #f] -[#:disallowed-references #f] @ [#:leaked-env-vars #f] [#:local-build? #f] @ -[#:substitutable? #t] [#:properties '()] Eine Ableitungen mit den -@var{Argumente}n erstellen und das resultierende @code{<derivation>}-Objekt -liefern. - -Wurden @var{hash} und @var{hash-algo} angegeben, wird eine @dfn{Ableitung -mit fester Ausgabe} erzeugt — d.h. eine, deren Ausgabe schon im Voraus -bekannt ist, wie z.B. beim Herunterladen einer Datei. Wenn des Weiteren auch -@var{recursive?} wahr ist, darf die Ableitung mit fester Ausgabe eine -ausführbare Datei oder ein Verzeichnis sein und @var{hash} muss die -Prüfsumme eines Archivs mit dieser Ausgabe sein. - -Ist @var{references-graphs} wahr, dann muss es eine Liste von Paaren aus je -einem Dateinamen und einem Store-Pfad sein. In diesem Fall wird der -Referenzengraph jedes Store-Pfads in einer Datei mit dem angegebenen Namen -in der Erstellungsumgebung zugänglich gemacht, in einem einfachen -Text-Format. - -Ist @var{allowed-references} ein wahr, muss es eine Liste von Store-Objekten -oder Ausgaben sein, die die Ausgabe der Ableitung referenzieren darf. Ebenso -muss @var{disallowed-references}, wenn es auf wahr gesetzt ist, eine Liste -von Dingen bezeichnen, die die Ausgaben @emph{nicht} referenzieren dürfen. - -Ist @var{leaked-env-vars} wahr, muss es eine Liste von Zeichenketten sein, -die Umgebungsvariable benennen, die aus der Umgebung des Daemons in die -Erstellungsumgebung überlaufen — ein »Leck«, englisch »leak«. Dies kann nur -in Ableitungen mit fester Ausgabe benutzt werden, also wenn @var{hash} wahr -ist. So ein Leck kann zum Beispiel benutzt werden, um Variable wie -@code{http_proxy} an Ableitungen zu übergeben, die darüber Dateien -herunterladen. - -Ist @var{local-build?} wahr, wird die Ableitung als schlechter Kandidat für -das Auslagern deklariert, der besser lokal erstellt werden sollte -(@pxref{Auslagern des Daemons einrichten}). Dies betrifft kleine Ableitungen, wo das -Übertragen der Daten aufwendiger als ihre Erstellung ist. - -Ist @var{substitutable?} falsch, wird deklariert, dass für die Ausgabe der -Ableitung keine Substitute benutzt werden sollen (@pxref{Substitute}). Das -ist nützlich, wenn Pakete erstellt werden, die Details über den -Prozessorbefehlssatz des Wirtssystems auslesen. - -@var{properties} muss eine assoziative Liste enthalten, die »Eigenschaften« -der Ableitungen beschreibt. Sie wird genau so, wie sie ist, in der Ableitung -gespeichert. -@end deffn - -@noindent -Hier ist ein Beispiel mit einem Shell-Skript, das als Ersteller benutzt -wird. Es wird angenommen, dass @var{Store} eine offene Verbindung zum Daemon -ist und @var{bash} auf eine ausführbare Bash im Store verweist: - -@lisp -(use-modules (guix utils) - (guix store) - (guix derivations)) - -(let ((builder ; das Ersteller-Bash-Skript in den Store einfügen - (add-text-to-store store "my-builder.sh" - "echo Hallo Welt > $out\n" '()))) - (derivation store "foo" - bash `("-e" ,builder) - #:inputs `((,bash) (,builder)) - #:env-vars '(("HOME" . "/homeless")))) -@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> -@end lisp - -Wie man sehen kann, ist es umständlich, diese grundlegende Methode direkt zu -benutzen. Natürlich ist es besser, Erstellungsskripts in Scheme zu -schreiben! Am besten schreibt man den Erstellungscode als »G-Ausdruck« und -übergibt ihn an @code{gexp->derivation}. Mehr Informationen finden Sie im -Abschnitt @pxref{G-Ausdrücke}. - -Doch es gab einmal eine Zeit, zu der @code{gexp->derivation} noch nicht -existiert hatte und wo das Zusammenstellen von Ableitungen mit -Scheme-Erstellungscode noch mit @code{build-expression->derivation} -bewerkstelligt wurde, was im Folgenden beschrieben wird. Diese Prozedur gilt -als veraltet und man sollte nunmehr die viel schönere Prozedur -@code{gexp->derivation} benutzen. - -@deffn {Scheme-Prozedur} build-expression->derivation @var{Store} @ - @var{Name} @var{Ausdruck} @ [#:system (%current-system)] [#:inputs '()] @ -[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] -[#:env-vars '()] [#:modules '()] @ [#:references-graphs #f] -[#:allowed-references #f] @ [#:disallowed-references #f] @ [#:local-build? -#f] [#:substitutable? #t] [#:guile-for-build #f] Liefert eine Ableitung, die -den Scheme-Ausdruck @var{Ausdruck} als Ersteller einer Ableitung namens -@var{Name} ausführt. @var{inputs} muss die Liste der Eingaben enthalten, -jeweils als Tupel @code{(Name Ableitungspfad Unterableitung)}; wird keine -@var{Unterableitung} angegeben, wird @code{"out"} angenommen. @var{Module} -ist eine Liste der Namen von Guile-Modulen im momentanen Suchpfad, die in -den Store kopiert, kompiliert und zur Verfügung gestellt werden, wenn der -@var{Ausdruck} ausgeführt wird — z.B. @code{((guix build utils) (guix build -gnu-build-system))}. - -Der @var{Ausdruck} wird in einer Umgebung ausgewertet, in der -@code{%outputs} an eine Liste von Ausgabe-/Pfad-Paaren gebunden wurde und in -der @code{%build-inputs} an eine Liste von Zeichenkette-/Ausgabepfad-Paaren -gebunden wurde, die aus den @var{inputs}-Eingaben konstruiert worden -ist. Optional kann in @var{env-vars} eine Liste von Paaren aus Zeichenketten -stehen, die Name und Wert von für den Ersteller sichtbaren -Umgebungsvariablen angeben. Der Ersteller terminiert, indem er @code{exit} -mit dem Ergebnis des @var{Ausdruck}s aufruft; wenn also der @var{Ausdruck} -den Wert @code{#f} liefert, wird angenommen, dass die Erstellung -fehlgeschlagen ist. - -@var{Ausdruck} wird mit einer Ableitung @var{guile-for-build} erstellt. Wird -kein @var{guile-for-build} angegeben oder steht es auf @code{#f}, wird -stattdessen der Wert der Fluiden @code{%guile-for-build} benutzt. - -Siehe die Erklärungen zur Prozedur @code{derivation} für die Bedeutung von -@var{references-graphs}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?} und @var{substitutable?}. -@end deffn - -@noindent -Hier ist ein Beispiel einer Ableitung mit nur einer Ausgabe, die ein -Verzeichnis erzeugt, in dem eine einzelne Datei enthalten ist: - -@lisp -(let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; das Verzeichnis - ; /gnu/store/@dots{}-goo erstellen - (call-with-output-file (string-append out "/test") - (lambda (p) - (display '(Hallo Guix) p)))))) - (build-expression->derivation store "goo" builder)) - -@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> -@end lisp - - -@node Die Store-Monade -@section Die Store-Monade - -@cindex Monade - -Die auf dem Store arbeitenden Prozeduren, die in den vorigen Abschnitten -beschrieben wurden, nehmen alle eine offene Verbindung zum -Erstellungs-Daemon als ihr erstes Argument entgegen. Obwohl das ihnen zu -Grunde liegende Modell funktional ist, weisen sie doch alle Nebenwirkungen -auf oder hängen vom momentanen Zustand des Stores ab. - -Ersteres ist umständlich, weil die Verbindung zum Erstellungs-Daemon -zwischen all diesen Funktionen durchgereicht werden muss, so dass eine -Komposition mit Funktionen ohne diesen Parameter unmöglich wird. Letzteres -kann problematisch sein, weil Operationen auf dem Store Nebenwirkungen -und/oder Abhängigkeiten von externem Zustand haben und ihre -Ausführungsreihenfolge deswegen eine Rolle spielt. - -@cindex monadische Werte -@cindex monadische Funktionen -Hier kommt das Modul @code{(guix monads)} ins Spiel. Im Rahmen dieses Moduls -können @dfn{Monaden} benutzt werden und dazu gehört insbesondere eine für -unsere Zwecke sehr nützliche Monade, die @dfn{Store-Monade}. Monaden sind -ein Konstrukt, mit dem zwei Dinge möglich sind: eine Assoziation von Werten -mit einem »Kontext« (in unserem Fall ist das die Verbindung zum Store) und -das Festlegen einer Reihenfolge für Berechnungen (hiermit sind auch Zugriffe -auf den Store gemeint). Werte in einer Monade — solche, die mit weiterem -Kontext assoziiert sind — werden @dfn{monadische Werte} genannt; Prozeduren, -die solche Werte liefern, heißen @dfn{monadische Prozeduren}. - -Betrachten Sie folgende »normale« Prozedur: - -@example -(define (sh-symlink store) - ;; Eine Ableitung liefern, die mit der ausführbaren Datei »bash« - ;; symbolisch verknüpft. - (let* ((drv (package-derivation store bash)) - (out (derivation->output-path drv)) - (sh (string-append out "/bin/bash"))) - (build-expression->derivation store "sh" - `(symlink ,sh %output)))) -@end example - -Unter Verwendung von @code{(guix monads)} und @code{(guix gexp)} lässt sie -sich als monadische Funktion aufschreiben: - -@example -(define (sh-symlink) - ;; Ebenso, liefert aber einen monadischen Wert. - (mlet %store-monad ((drv (package->derivation bash))) - (gexp->derivation "sh" - #~(symlink (string-append #$drv "/bin/bash") - #$output)))) -@end example - -An der zweiten Version lassen sich mehrere Dinge beobachten: Der Parameter -@code{Store} ist jetzt implizit geworden und wurde in die Aufrufe der -monadischen Prozeduren @code{package->derivation} und -@code{gexp->derivation} »eingefädelt« und der von @code{package->derivation} -gelieferte monadische Wert wurde mit @code{mlet} statt einem einfachen -@code{let} @dfn{gebunden}. - -Wie sich herausstellt, muss man den Aufruf von @code{package->derivation} -nicht einmal aufschreiben, weil er implizit geschieht, wie wir später sehen -werden (siehe @pxref{G-Ausdrücke}): - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> -@c for the funny quote. -Die monadische @code{sh-symlink} einfach aufzurufen, bewirkt nichts. Wie -jemand einst sagte: »Mit einer Monade geht man um, wie mit Gefangenen, gegen -die man keine Beweise hat: Man muss sie laufen lassen.« Um also aus der -Monade auszubrechen und die gewünschte Wirkung zu erzielen, muss man -@code{run-with-store} benutzen: - -@example -(run-with-store (open-connection) (sh-symlink)) -@result{} /gnu/store/...-sh-symlink -@end example - -Erwähnenswert ist, dass das Modul @code{(guix monad-repl)} die REPL von -Guile um neue »Meta-Befehle« erweitert, mit denen es leichter ist, mit -monadischen Prozeduren umzugehen: @code{run-in-store} und -@code{enter-store-monad}. Mit Ersterer wird ein einzelner monadischer Wert -durch den Store »laufen gelassen«: - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -@end example - -Mit Letzterer wird rekursiv eine weitere REPL betreten, in der alle -Rückgabewerte automatisch durch den Store laufen gelassen werden: - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hallo!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Beachten Sie, dass in einer @code{store-monad}-REPL keine nicht-monadischen -Werte zurückgeliefert werden können. - -Die wichtigsten syntaktischen Formen, um mit Monaden im Allgemeinen -umzugehen, werden im Modul @code{(guix monads)} bereitgestellt und sind im -Folgenden beschrieben. - -@deffn {Scheme-Syntax} with-monad @var{Monade} @var{Rumpf} ... -Alle @code{>>=}- oder @code{return}-Formen im @var{Rumpf} in der -@var{Monade} auswerten. -@end deffn - -@deffn {Scheme-Syntax} return @var{Wert} -Einen monadischen Wert liefern, der den übergebenen @var{Wert} kapselt. -@end deffn - -@deffn {Scheme-Syntax} >>= @var{mWert} @var{mProz} ... -Den monadischen Wert @var{mWert} @dfn{binden}, wobei sein »Inhalt« an die -monadischen Prozeduren @var{mProz}@dots{} übergeben wird@footnote{Diese -Operation wird gemeinhin »bind« genannt, aber mit diesem Begriff wird in -Guile eine völlig andere Prozedur bezeichnet, die nichts damit zu tun -hat. Also benutzen wir dieses etwas kryptische Symbol als Erbe der -Haskell-Programmiersprache.}. Es kann eine einzelne @var{mProz} oder mehrere -davon geben, wie in diesem Beispiel: - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'irgendein-Zustand) - -@result{} 4 -@result{} irgendein-Zustand -@end example -@end deffn - -@deffn {Scheme-Syntax} mlet @var{Monade} ((@var{Variable} @var{mWert}) ...) @ - @var{Rumpf} ... -@deffnx {Scheme-Syntax} mlet* @var{Monade} ((@var{Variable} @var{mWert}) ...) @ - @var{Rumpf} ... Die @var{Variable}n an die monadischen Werte @var{mWert} im -@var{Rumpf} binden, der eine Folge von Ausdrücken ist. Wie beim -bind-Operator kann man es sich vorstellen als »Auspacken« des rohen, -nicht-monadischen Werts, der im @var{mWert} steckt, wobei anschließend -dieser rohe, nicht-monadische Wert im Sichtbarkeitsbereich des @var{Rumpf}s -von der @var{Variable}n bezeichnet wird. Die Form (@var{Variable} -> -@var{Wert}) bindet die @var{Variable} an den »normalen« @var{Wert}, wie es -@code{let} tun würde. Die Bindungsoperation geschieht in der Reihenfolge von -links nach rechts. Der letzte Ausdruck des @var{Rumpfs} muss ein monadischer -Ausdruck sein und dessen Ergebnis wird das Ergebnis von @code{mlet} oder -@code{mlet*} werden, wenn es durch die @var{Monad} laufen gelassen wurde. - -@code{mlet*} verhält sich gegenüber @code{mlet} wie @code{let*} gegenüber -@code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn - -@deffn {Scheme-System} mbegin @var{Monade} @var{mAusdruck} ... -Der Reihe nach den @var{mAusdruck} und die nachfolgenden monadischen -Ausdrücke binden und als Ergebnis das des letzten Ausdrucks liefern. Jeder -Ausdruck in der Abfolge muss ein monadischer Ausdruck sein. - -Dies verhält sich ähnlich wie @code{mlet}, außer dass die Rückgabewerte der -monadischen Prozeduren ignoriert werden. In diesem Sinn verhält es sich -analog zu @code{begin}, nur auf monadischen Ausdrücken. -@end deffn - -@deffn {Scheme-System} mwhen @var{Bedingung} @var{mAusdr0} @var{mAusdr*} ... -Wenn die @var{Bedingung} wahr ist, wird die Folge monadischer Ausdrücke -@var{mAusdr0}..@var{mAusdr*} wie bei @code{mbegin} ausgewertet. Wenn die -@var{Bedingung} falsch ist, wird @code{*unspecified*} in der momentanen -Monade zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer -Ausdruck sein. -@end deffn - -@deffn {Scheme-System} munless @var{Bedingung} @var{mAusdr0} @var{mAusdr*} ... -Wenn die @var{Bedingung} falsch ist, wird die Folge monadischer Ausdrücke -@var{mAusdr0}..@var{mAusdr*} wie bei @code{mbegin} ausgewertet. Wenn die -@var{Bedingung} wahr ist, wird @code{*unspecified*} in der momentanen Monade -zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer Ausdruck -sein. -@end deffn - -@cindex Zustandsmonade -Das Modul @code{(guix monads)} macht die @dfn{Zustandsmonade} (englisch -»state monad«) verfügbar, mit der ein zusätzlicher Wert — der Zustand — -durch die monadischen Prozeduraufrufe @emph{gefädelt} werden kann. - -@defvr {Scheme-Variable} %state-monad -Die Zustandsmonade. Prozeduren in der Zustandsmonade können auf den -gefädelten Zustand zugreifen und ihn verändern. - -Betrachten Sie das folgende Beispiel. Die Prozedur @code{Quadrat} liefert -einen Wert in der Zustandsmonade zurück. Sie liefert das Quadrat ihres -Arguments, aber sie inkrementiert auch den momentanen Zustandswert: - -@example -(define (Quadrat x) - (mlet %state-monad ((Anzahl (current-state))) - (mbegin %state-monad - (set-current-state (+ 1 Anzahl)) - (return (* x x))))) - -(run-with-state (sequence %state-monad (map Quadrat (iota 3))) 0) -@result{} (0 1 4) -@result{} 3 -@end example - -Wird das »durch« die Zustandsmonade @var{%state-monad} laufen gelassen, -erhalten wir jenen zusätzlichen Zustandswert, der der Anzahl der Aufrufe von -@code{Quadrat} entspricht. -@end defvr - -@deffn {Monadische Prozedur} current-state -Liefert den momentanen Zustand als einen monadischen Wert. -@end deffn - -@deffn {Monadische Prozedur} set-current-state @var{Wert} -Setzt den momentanen Zustand auf @var{Wert} und liefert den vorherigen -Zustand als einen monadischen Wert. -@end deffn - -@deffn {Monadische Prozedur} state-push @var{Wert} -Hängt den @var{Wert} vorne an den momentanen Zustand an, der eine Liste sein -muss. Liefert den vorherigen Zustand als monadischen Wert. -@end deffn - -@deffn {Monadische Prozedur} state-pop -Entfernt einen Wert vorne vom momentanen Zustand und liefert ihn als -monadischen Wert zurück. Dabei wird angenommen, dass es sich beim Zustand um -eine Liste handelt. -@end deffn - -@deffn {Scheme-Prozedur} run-with-state @var{mWert} [@var{Zustand}] -Den monadischen Wert @var{mWert} mit @var{Zustand} als initialem Zustand -laufen lassen. Dies liefert zwei Werte: den Ergebniswert und den -Ergebniszustand. -@end deffn - -Die zentrale Schnittstelle zur Store-Monade, wie sie vom Modul @code{(guix -store)} angeboten wird, ist die Folgende: - -@defvr {Scheme-Variable} %store-monad -Die Store-Monade — ein anderer Name für @var{%state-monad}. - -Werte in der Store-Monade kapseln Zugriffe auf den Store. Sobald seine -Wirkung gebraucht wird, muss ein Wert der Store-Monade »ausgewertet« werden, -indem er an die Prozedur @code{run-with-store} übergeben wird (siehe unten). -@end defvr - -@deffn {Scheme-Prozedur} run-with-store @var{Store} @var{mWert} [#:guile-for-build] [#:system (%current-system)] -Den @var{mWert}, einen monadischen Wert in der Store-Monade, in der offenen -Verbindung @var{Store} laufen lassen. -@end deffn - -@deffn {Monadische Prozedur} text-file @var{Name} @var{Text} [@var{Referenzen}] -Als monadischen Wert den absoluten Dateinamen im Store für eine Datei -liefern, deren Inhalt der der Zeichenkette @var{Text} ist. @var{Referenzen} -ist dabei eine Liste von Store-Objekten, die die Ergebnis-Textdatei -referenzieren wird; der Vorgabewert ist die leere Liste. -@end deffn - -@deffn {Monadische Prozedur} binary-file @var{Name} @var{Daten} [@var{Referenzen}] -Den absoluten Dateinamen im Store als monadischen Wert für eine Datei -liefern, deren Inhalt der des Byte-Vektors @var{Daten} ist. @var{Referenzen} -ist dabei eine Liste von Store-Objekten, die die Ergebnis-Binärdatei -referenzieren wird; der Vorgabewert ist die leere Liste. -@end deffn - -@deffn {Monadische Prozedur} interned-file @var{Datei} [@var{Name}] @ - [#:recursive? #t] [#:select? (const #t)] Liefert den Namen der @var{Datei}, -nachdem sie in den Store interniert wurde. Dabei wird der @var{Name} als ihr -Store-Name verwendet, oder, wenn kein @var{Name} angegeben wurde, der -Basisname der @var{Datei}. - -Ist @var{recursive?} wahr, werden in der @var{Datei} enthaltene Dateien -rekursiv hinzugefügt; ist die @var{Datei} eine flache Datei und -@var{recursive?} ist wahr, wird ihr Inhalt in den Store eingelagert und ihre -Berechtigungs-Bits übernommen. - -Steht @var{recursive?} auf wahr, wird @code{(@var{select?} @var{Datei} -@var{Stat})} für jeden Verzeichniseintrag aufgerufen, wobei @var{Datei} der -absolute Dateiname und @var{Stat} das Ergebnis von @code{lstat} ist, außer -auf den Einträgen, wo @var{select?} keinen wahren Wert liefert. - -Folgendes Beispiel fügt eine Datei unter zwei verschiedenen Namen in den -Store ein: - -@example -(run-with-store (open-connection) - (mlet %store-monad ((a (interned-file "README")) - (b (interned-file "README" "LEGU-MIN"))) - (return (list a b)))) - -@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN") -@end example - -@end deffn - -Das Modul @code{(guix packages)} exportiert die folgenden paketbezogenen -monadischen Prozeduren: - -@deffn {Monadische Prozedur} package-file @var{Paket} [@var{Datei}] @ - [#:system (%current-system)] [#:target #f] @ [#:output "out"] Liefert als -monadischen Wert den absoluten Dateinamen der @var{Datei} innerhalb des -Ausgabeverzeichnisses @var{output} des @var{Paket}s. Wird keine @var{Datei} -angegeben, wird der Name des Ausgabeverzeichnisses @var{output} für das -@var{Paket} zurückgeliefert. Ist @var{target} wahr, wird sein Wert als das -Zielsystem bezeichnendes Tripel zum Cross-Kompilieren benutzt. -@end deffn - -@deffn {Monadische Prozedur} package->derivation @var{Paket} [@var{System}] -@deffnx {Monadische Prozedur} package->cross-derivation @var{Paket} @ - @var{Ziel} [@var{System}] Monadische Version von @code{package-derivation} -und @code{package-cross-derivation} (@pxref{Pakete definieren}). -@end deffn - - -@node G-Ausdrücke -@section G-Ausdrücke - -@cindex G-Ausdruck -@cindex Erstellungscode maskieren -Es gibt also »Ableitungen«, die eine Abfolge von Erstellungsaktionen -repräsentieren, die durchgeführt werden müssen, um ein Objekt im Store zu -erzeugen (@pxref{Ableitungen}). Diese Erstellungsaktionen werden -durchgeführt, nachdem der Daemon gebeten wurde, die Ableitungen tatsächlich -zu erstellen; dann führt der Daemon sie in einer isolierten Umgebung (einem -sogenannten Container) aus (@pxref{Aufruf des guix-daemon}). - -@cindex Schichten von Code -Wenig überraschend ist, dass wir diese Erstellungsaktionen gerne in Scheme -schreiben würden. Wenn wir das tun, bekommen wir zwei verschiedene -@dfn{Schichten} von Scheme-Code@footnote{Der Begriff @dfn{Schicht}, englisch -Stratum, wurde in diesem Kontext von Manuel Serrano et al.@: in ihrer Arbeit -an Hop geprägt. Oleg Kiselyov, der aufschlussreiche -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, Essays und Code zu -diesem Thema} geschrieben hat, nennt diese Art der Code-Generierung -@dfn{Staging}, deutsch etwa Inszenierung bzw.@: Aufführung.}: den -»wirtsseitigen Code« (»host code«) — also Code, der Pakete definiert, mit -dem Daemon kommuniziert etc. — und den »erstellungsseitigen Code« (»build -code«) — also Code, der die Erstellungsaktionen auch wirklich umsetzt, indem -Dateien erstellt werden, @command{make} aufgerufen wird etc. - -Um eine Ableitung und ihre Erstellungsaktionen zu beschreiben, muss man -normalerweise erstellungsseitigen Code im wirtsseitigen Code einbetten. Das -bedeutet, man behandelt den erstellungsseitigen Code als Daten, was wegen -der Homoikonizität von Scheme — dass Code genauso als Daten repräsentiert -werden kann — sehr praktisch ist. Doch brauchen wir hier mehr als nur den -normalen Quasimaskierungsmechanismus mit @code{quasiquote} in Scheme, wenn -wir Erstellungsausdrücke konstruieren möchten. - -Das Modul @code{(guix gexp)} implementiert @dfn{G-Ausdrücke}, eine Form von -S-Ausdrücken, die zu Erstellungsausdrücken angepasst wurden. G-Ausdrücke -(englisch »G-expressions«, kurz @dfn{Gexps}) setzen sich grundlegend aus -drei syntaktischen Formen zusammen: @code{gexp}, @code{ungexp} und -@code{ungexp-splicing} (alternativ einfach: @code{#~}, @code{#$} und -@code{#$@@}), die jeweils mit @code{quasiquote}, @code{unquote} und -@code{unquote-splicing} vergleichbar sind (@pxref{Expression Syntax, -@code{quasiquote},, guile, GNU Guile Reference Manual}). Es gibt aber auch -erhebliche Unterschiede: - -@itemize -@item -G-Ausdrücke sind dafür gedacht, in eine Datei geschrieben zu werden, wo sie -von anderen Prozessen ausgeführt oder manipuliert werden können. - -@item -Wenn ein abstraktes Objekt wie ein Paket oder eine Ableitung innerhalb eines -G-Ausdrücks demaskiert wird, ist das Ergebnis davon dasselbe, wie wenn -dessen Ausgabedateiname genannt worden wäre. - -@item -G-Ausdrücke tragen Informationen über die Pakete oder Ableitungen mit sich, -auf die sie sich beziehen, und diese Abhängigkeiten werden automatisch zu -den sie benutzenden Erstellungsprozessen als Eingaben hinzugefügt. -@end itemize - -@cindex Herunterbrechen, von abstrakten Objekten in G-Ausdrücken -Dieser Mechanismus ist nicht auf Pakete und Ableitung beschränkt: Es können -@dfn{Compiler} definiert werden, die weitere abstrakte, hochsprachliche -Objekte auf Ableitungen oder Dateien im Store »herunterbrechen«, womit diese -Objekte dann auch in G-Ausdrücken eingefügt werden können. Zum Beispiel sind -»dateiartige Objekte« ein nützlicher Typ solcher abstrakter Objekte. Mit -ihnen können Dateien leicht in den Store eingefügt und von Ableitungen und -Anderem referenziert werden (siehe unten @code{local-file} und -@code{plain-file}). - -Zur Veranschaulichung dieser Idee soll uns dieses Beispiel eines G-Ausdrucks -dienen: - -@example -(define build-exp - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "list-files"))) -@end example - -Indem wir diesen G-Ausdruck an @code{gexp->derivation} übergeben, bekommen -wir eine Ableitung, die ein Verzeichnis mit genau einer symbolischen -Verknüpfung auf @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls} erstellt: - -@example -(gexp->derivation "das-ding" build-exp) -@end example - -Wie man es erwarten würde, wird die Zeichenkette -@code{"/gnu/store/@dots{}-coreutils-8.22"} anstelle der Referenzen auf das -Paket @var{coreutils} im eigentlichen Erstellungscode eingefügt und -@var{coreutils} automatisch zu einer Eingabe der Ableitung gemacht. Genauso -wird auch @code{#$output} (was äquivalent zur Schreibweise @code{(ungexp -output)} ist) ersetzt durch eine Zeichenkette mit dem Namen der Ausgabe der -Ableitung. - -@cindex Cross-Kompilieren -Im Kontext der Cross-Kompilierung bietet es sich an, zwischen Referenzen auf -die @emph{native} Erstellung eines Pakets — also der, die auf dem -Wirtssystem ausgeführt werden kann — und Referenzen auf Cross-Erstellungen -eines Pakets zu unterscheiden. Hierfür spielt @code{#+} dieselbe Rolle wie -@code{#$}, steht aber für eine Referenz auf eine native Paketerstellung. - -@example -(gexp->derivation "vi" - #~(begin - (mkdir #$output) - (system* (string-append #+coreutils "/bin/ln") - "-s" - (string-append #$emacs "/bin/emacs") - (string-append #$output "/bin/vi"))) - #:target "mips64el-linux-gnu") -@end example - -@noindent -Im obigen Beispiel wird die native Erstellung der @var{coreutils} benutzt, -damit @command{ln} tatsächlich auf dem Wirtssystem ausgeführt werden kann, -aber danach die cross-kompilierte Erstellung von @var{emacs} referenziert. - -@cindex importierte Module, in G-Ausdrücken -@findex with-imported-modules -Eine weitere Funktionalität von G-Ausdrücken stellen @dfn{importierte -Module} dar. Manchmal will man bestimmte Guile-Module von der »wirtsseitigen -Umgebung« im G-Ausdruck benutzen können, deswegen sollten diese Module in -die »erstellungsseitige Umgebung« importiert werden. Die -@code{with-imported-modules}-Form macht das möglich: - -@example -(let ((build (with-imported-modules '((guix build utils)) - #~(begin - (use-modules (guix build utils)) - (mkdir-p (string-append #$output "/bin")))))) - (gexp->derivation "leeres-Verzeichnis" - #~(begin - #$build - (display "Erfolg!\n") - #t))) -@end example - -@noindent -In diesem Beispiel wird das Modul @code{(guix build utils)} automatisch in -die isolierte Erstellungsumgebung unseres G-Ausdrucks geholt, so dass -@code{(use-modules (guix build utils))} wie erwartet funktioniert. - -@cindex Modulabschluss -@findex source-module-closure -Normalerweise möchten Sie, dass der @emph{Abschluss} eines Moduls importiert -wird — also das Modul und alle Module, von denen es abhängt — statt nur das -Modul selbst. Ansonsten scheitern Versuche, das Modul zu benutzen, weil -seine Modulabhängigkeiten fehlen. Die Prozedur @code{source-module-closure} -berechnet den Abschluss eines Moduls, indem es den Kopf seiner Quelldatei -analysiert, deswegen schafft die Prozedur hier Abhilfe: - -@example -(use-modules (guix modules)) ;»source-module-closure« verfügbar machen - -(with-imported-modules (source-module-closure - '((guix build utils) - (gnu build vm))) - (gexp->derivation "etwas-mit-vms" - #~(begin - (use-modules (guix build utils) - (gnu build vm)) - @dots{}))) -@end example - -@cindex Erweiterungen, für G-Ausdrücke -@findex with-extensions -Auf die gleiche Art können Sie auch vorgehen, wenn Sie nicht bloß reine -Scheme-Module importieren möchten, sondern auch »Erweiterungen« wie -Guile-Anbindungen von C-Bibliotheken oder andere »vollumfängliche« -Pakete. Sagen wir, Sie bräuchten das Paket @code{guile-json} auf der -Erstellungsseite, dann könnten Sie es hiermit bekommen: - -@example -(use-modules (gnu packages guile)) ;für »guile-json« - -(with-extensions (list guile-json) - (gexp->derivation "etwas-mit-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -Die syntaktische Form, in der G-Ausdrücke konstruiert werden, ist im -Folgenden zusammengefasst. - -@deffn {Scheme-Syntax} #~@var{Ausdruck} -@deffnx {Scheme-Syntax} (gexp @var{Ausdruck}) -Liefert einen G-Ausdruck, der den @var{Ausdruck} enthält. Der @var{Ausdruck} -kann eine oder mehrere der folgenden Formen enthalten: - -@table @code -@item #$@var{Objekt} -@itemx (ungexp @var{Objekt}) -Eine Referenz auf das @var{Objekt} einführen. Das @var{Objekt} kann einen -der unterstützten Typen haben, zum Beispiel ein Paket oder eine Ableitung, -so dass die @code{ungexp}-Form durch deren Ausgabedateiname ersetzt wird — -z.B. @code{"/gnu/store/@dots{}-coreutils-8.22}. - -Wenn das @var{Objekt} eine Liste ist, wird diese durchlaufen und alle -unterstützten Objekte darin auf diese Weise ersetzt. - -Wenn das @var{Objekt} ein anderer G-Ausdruck ist, wird sein Inhalt eingefügt -und seine Abhängigkeiten zu denen des äußeren G-Ausdrucks hinzugefügt. - -Wenn das @var{Objekt} eine andere Art von Objekt ist, wird es so wie es ist -eingefügt. - -@item #$@var{Objekt}:@var{Ausgabe} -@itemx (ungexp @var{Objekt} @var{Ausgabe}) -Dies verhält sich wie die Form oben, bezieht sich aber ausdrücklich auf die -angegebene @var{Ausgabe} des @var{Objekt}s — dies ist nützlich, wenn das -@var{Objekt} mehrere Ausgaben generiert (@pxref{Pakete mit mehreren Ausgaben.}). - -@item #+@var{Objekt} -@itemx #+@var{Objekt}:@var{Ausgabe} -@itemx (ungexp-native @var{Objekt}) -@itemx (ungexp-native @var{Objekt} @var{Ausgabe}) -Das Gleiche wie @code{ungexp}, jedoch wird im Kontext einer -Cross-Kompilierung eine Referenz auf die @emph{native} Erstellung des -@var{Objekt}s eingefügt. - -@item #$output[:@var{Ausgabe}] -@itemx (ungexp output [@var{Ausgabe}]) -Fügt eine Referenz auf die angegebene @var{Ausgabe} dieser Ableitung ein, -oder auf die Hauptausgabe, wenn keine @var{Ausgabe} angegeben wurde. - -Dies ist nur bei G-Ausdrücken sinnvoll, die an @code{gexp->derivation} -übergeben werden. - -@item #$@@@var{Liste} -@itemx (ungexp-splicing @var{Liste}) -Das Gleiche wie oben, jedoch wird nur der Inhalt der @var{Liste} in die -äußere Liste eingespleißt. - -@item #+@@@var{Liste} -@itemx (ungexp-native-splicing @var{Liste}) -Das Gleiche, aber referenziert werden native Erstellungen der Objekte in der -@var{Liste}. - -@end table - -G-Ausdrücke, die mit @code{gexp} oder @code{#~} erzeugt wurden, sind zur -Laufzeit Objekte vom Typ @code{gexp?} (siehe unten). -@end deffn - -@deffn {Scheme-Syntax} with-imported-modules @var{Module} @var{Rumpf}@dots{} -Markiert die in @var{Rumpf}@dots{} definierten G-Ausdrücke, dass sie in -ihrer Ausführungsumgebung die angegebenen @var{Module} brauchen. - -Jedes Objekt unter den @var{Module}n kann der Name eines Moduls wie -@code{(guix build utils)} sein, oder es kann nacheinander ein Modulname, ein -Pfeil und ein dateiartiges Objekt sein: - -@example -`((guix build utils) - (guix gcrypt) - ((guix config) => ,(scheme-file "config.scm" - #~(define-module @dots{})))) -@end example - -@noindent -Im Beispiel oben werden die ersten beiden Module vom Suchpfad genommen und -das letzte aus dem angegebenen dateiartigen Objekt erzeugt. - -Diese Form hat einen @emph{lexikalischen} Sichtbarkeitsbereich: Sie wirkt -sich auf die direkt in @var{Rumpf}@dots{} definierten G-Ausdrücke aus, aber -nicht auf jene, die, sagen wir, in aus @var{Rumpf}@dots{} heraus -aufgerufenen Prozeduren definiert wurden. -@end deffn - -@deffn {Scheme-Syntax} with-extensions @var{Erweiterungen} @var{Rumpf}@dots{} -Markiert die in @var{Rumpf}@dots{} definierten G-Ausdrücke, dass sie -@var{Erweiterungen} in ihrer Erstellungs- und Ausführungsumgebung -benötigen. @var{Erweiterungen} sind typischerweise eine Liste von -Paketobjekten wie zum Beispiel die im Modul @code{(gnu packages guile)} -definierten. - -Konkret werden die unter den @var{Erweiterungen} aufgeführten Pakete zum -Ladepfad hinzugefügt, während die in @var{Rumpf}@dots{} aufgeführten -importierten Module kompiliert werden und sie werden auch zum Ladepfad des -von @var{Rumpf}@dots{} gelieferten G-Ausdrucks hinzugefügt. -@end deffn - -@deffn {Scheme-Prozedur} gexp? @var{Objekt} -Liefert @code{#t}, wenn das @var{Objekt} ein G-Ausdruck ist. -@end deffn - -G-Ausdrücke sind dazu gedacht, auf die Platte geschrieben zu werden, -entweder als Code, der eine Ableitung erstellt, oder als einfache Dateien im -Store. Die monadischen Prozeduren unten ermöglichen Ihnen das (@pxref{Die Store-Monade}, wenn Sie mehr Informationen über Monaden suchen). - -@deffn {Monadische Prozedur} gexp->derivation @var{Name} @var{Ausdruck} @ - [#:system (%current-system)] [#:target #f] [#:graft? #t] @ [#:hash #f] -[#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ -[#:module-path @var{%load-path}] @ [#:effective-version "2.2"] @ -[#:references-graphs #f] [#:allowed-references #f] @ -[#:disallowed-references #f] @ [#:leaked-env-vars #f] @ [#:script-name -(string-append @var{Name} "-builder")] @ [#:deprecation-warnings #f] @ -[#:local-build? #f] [#:substitutable? #t] @ [#:properties '()] -[#:guile-for-build #f] Liefert eine Ableitung unter dem @var{Name}n, die -jeden @var{Ausdruck} (ein G-Ausdruck) mit @var{guile-for-build} (eine -Ableitung) für das @var{System} erstellt; der @var{Ausdruck} wird dabei in -einer Datei namens @var{script-name} gespeichert. Wenn »@var{target}« wahr -ist, wird es beim Cross-Kompilieren als Zieltripel für mit @var{Ausdruck} -bezeichnete Pakete benutzt. - -@var{modules} gilt als veraltet; stattdessen sollte -@code{with-imported-modules} benutzt werden. Die Bedeutung ist, dass die -@var{Module} im Ausführungskontext des @var{Ausdruck}s verfügbar gemacht -werden; @var{modules} ist dabei eine Liste von Namen von Guile-Modulen, die -im Modulpfad @var{module-path} gesucht werden, um sie in den Store zu -kopieren, zu kompilieren und im Ladepfad während der Ausführung des -@var{Ausdruck}s verfügbar zu machen — z.B. @code{((guix build utils) (guix -build gnu-build-system))}. - -@var{effective-version} bestimmt, unter welcher Zeichenkette die -Erweiterungen des @var{Ausdruck}s zum Suchpfad hinzugefügt werden (siehe -@code{with-extensions}) — z.B. @code{"2.2"}. - -@var{graft?} bestimmt, ob vom @var{Ausdruck} benannte Pakete veredelt werden -sollen, falls Veredelungen zur Verfügung stehen. - -Ist @var{references-graphs} wahr, muss es eine Liste von Tupeln in einer der -folgenden Formen sein: - -@example -(@var{Dateiname} @var{Paket}) -(@var{Dateiname} @var{Paket} @var{Ausgabe}) -(@var{Dateiname} @var{Ableitung}) -(@var{Dateiname} @var{Ableitung} @var{Ausgabe}) -(@var{Dateiname} @var{Store-Objekt}) -@end example - -Bei jedem Element von @var{references-graphs} wird das rechts Stehende -automatisch zu einer Eingabe des Erstellungsprozesses vom @var{Ausdruck} -gemacht. In der Erstellungsumgebung enthält das, was mit @var{Dateiname} -bezeichnet wird, den Referenzgraphen des entsprechenden Objekts in einem -einfachen Textformat. - -@var{allowed-references} muss entweder @code{#f} oder eine Liste von -Ausgabenamen und Paketen sein. Eine solche Liste benennt Store-Objekte, die -das Ergebnis referenzieren darf. Jede Referenz auf ein nicht dort -aufgeführtes Store-Objekt löst einen Erstellungsfehler aus. Genauso -funktioniert @var{disallowed-references}, was eine Liste von Objekten sein -kann, die von den Ausgaben nicht referenziert werden dürfen. - -@var{deprecation-warnings} bestimmt, ob beim Kompilieren von Modulen -Warnungen angezeigt werden sollen, wenn auf als veraltet markierten Code -zugegriffen wird (»deprecation warnings«). @var{deprecation-warnings} kann -@code{#f}, @code{#t} oder @code{'detailed} (detailliert) sein. - -Die anderen Argumente verhalten sich wie bei @code{derivation} -(@pxref{Ableitungen}). -@end deffn - -@cindex dateiartige Objekte -Die im Folgenden erklärten Prozeduren @code{local-file}, @code{plain-file}, -@code{computed-file}, @code{program-file} und @code{scheme-file} liefern -@dfn{dateiartige Objekte}. Das bedeutet, dass diese Objekte, wenn sie in -einem G-Ausdruck demaskiert werden, zu einer Datei im Store -führen. Betrachten Sie zum Beispiel diesen G-Ausdruck: - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/my-nscd.conf")) -@end example - -Der Effekt hiervon ist, dass @file{/tmp/my-nscd.conf} »interniert« wird, -indem es in den Store kopiert wird. Sobald er umgeschrieben wurde, zum -Beispiel über @code{gexp->derivation}, referenziert der G-Ausdruck diese -Kopie im @file{/gnu/store}. Die Datei in @file{/tmp} zu bearbeiten oder zu -löschen, hat dann keinen Effekt mehr darauf, was der G-Ausdruck -tut. @code{plain-file} kann in ähnlicher Weise benutzt werden, es -unterscheidet sich aber darin, dass dort der Prozedur der Inhalt der Datei -als eine Zeichenkette übergeben wird. - -@deffn {Scheme-Prozedur} local-file @var{Datei} [@var{Name}] @ - [#:recursive? #f] [#:select? (const #t)] Liefert ein Objekt, dass die lokale -Datei @var{Datei} repräsentiert und sie zum Store hinzufügen lässt; dieses -Objekt kann in einem G-Ausdruck benutzt werden. Wurde für die @var{Datei} -ein relativer Dateiname angegeben, wird sie relativ zur Quelldatei gesucht, -in der diese Form steht. Die @var{Datei} wird unter dem angegebenen -@var{Name}n im Store abgelegt — als Vorgabe wird dabei der Basisname der -@var{Datei} genommen. - -Ist @var{recursive?} wahr, werden in der @var{Datei} enthaltene Dateien -rekursiv hinzugefügt; ist die @var{Datei} eine flache Datei und -@var{recursive?} ist wahr, wird ihr Inhalt in den Store eingelagert und ihre -Berechtigungs-Bits übernommen. - -Steht @var{recursive?} auf wahr, wird @code{(@var{select?} @var{Datei} -@var{Stat})} für jeden Verzeichniseintrag aufgerufen, wobei @var{Datei} der -absolute Dateiname und @var{Stat} das Ergebnis von @code{lstat} ist, außer -auf den Einträgen, wo @var{select?} keinen wahren Wert liefert. - -Dies ist das deklarative Gegenstück zur monadischen Prozedur -@code{interned-file} (@pxref{Die Store-Monade, @code{interned-file}}). -@end deffn - -@deffn {Scheme-Prozedur} plain-file @var{Name} @var{Inhalt} -Liefert ein Objekt, das eine Textdatei mit dem angegebenen @var{Name}n -repräsentiert, die den angegebenen @var{Inhalt} hat (eine Zeichenkette oder -ein Bytevektor), welche zum Store hinzugefügt werden soll. - -Dies ist das deklarative Gegenstück zu @code{text-file}. -@end deffn - -@deffn {Scheme-Prozedur} computed-file @var{Name} @var{G-Ausdruck} @ - [#:options '(#:local-build? #t)] Liefert ein Objekt, das das Store-Objekt -mit dem @var{Name}n repräsentiert, eine Datei oder ein Verzeichnis, das vom -@var{G-Ausdruck} berechnet wurde. @var{options} ist eine Liste zusätzlicher -Argumente, die an @code{gexp->derivation} übergeben werden. - -Dies ist das deklarative Gegenstück zu @code{gexp->derivation}. -@end deffn - -@deffn {Monadische Prozedur} gexp->script @var{Name} @var{Ausdruck} @ - [#:guile (default-guile)] [#:module-path %load-path] Liefert ein -ausführbares Skript namens @var{Name}, das den @var{Ausdruck} mit dem -angegebenen @var{guile} ausführt, wobei vom @var{Ausdruck} importierte -Module in seinem Suchpfad stehen. Die Module des @var{Ausdruck}s werden dazu -im Modulpfad @var{module-path} gesucht. - -Folgendes Beispiel erstellt ein Skript, das einfach nur den Befehl -@command{ls} ausführt: - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "list-files" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -Lässt man es durch den Store »laufen« (siehe @pxref{Die Store-Monade, -@code{run-with-store}}), erhalten wir eine Ableitung, die eine ausführbare -Datei @file{/gnu/store/@dots{}-list-files} generiert, ungefähr so: - -@example -#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds -!# -(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls") -@end example -@end deffn - -@deffn {Scheme-Prozedur} program-file @var{Name} @var{G-Ausdruck} @ - [#:guile #f] [#:module-path %load-path] Liefert ein Objekt, das eine -ausführbare Store-Datei @var{Name} repräsentiert, die den @var{G-Ausdruck} -ausführt. @var{guile} ist das zu verwendende Guile-Paket, mit dem das Skript -ausgeführt werden kann. Importierte Module des @var{G-Ausdruck}s werden im -Modulpfad @var{module-path} gesucht. - -Dies ist das deklarative Gegenstück zu @code{gexp->script}. -@end deffn - -@deffn {Monadische Prozedur} gexp->file @var{Name} @var{G-Ausdruck} @ - [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] @ [#:guile -(default-guile)] Liefert eine Ableitung, die eine Datei @var{Name} erstellen -wird, deren Inhalt der @var{G-Ausdruck} ist. Ist @var{splice?} wahr, dann -wird @var{G-Ausdruck} stattdessen als eine Liste von mehreren G-Ausdrücken -behandelt, die alle in die resultierende Datei gespleißt werden. - -Ist @var{set-load-path?} wahr, wird in die resultierende Datei Code -hinzugefügt, der den Ladepfad @code{%load-path} und den Ladepfad für -kompilierte Dateien @code{%load-compiled-path} festlegt, die für die -importierten Module des @var{G-Ausdruck}s nötig sind. Die Module des -@var{G-Ausdruck}s werden im Modulpfad @var{module-path} gesucht. - -Die resultierende Datei referenziert alle Abhängigkeiten des -@var{G-Ausdruck}s oder eine Teilmenge davon. -@end deffn - -@deffn {Scheme-Prozedur} scheme-file @var{Name} @var{G-Ausdruck} [#:splice? #f] -Liefert ein Objekt, das die Scheme-Datei @var{Name} mit dem @var{G-Ausdruck} -als Inhalt repräsentiert. - -Dies ist das deklarative Gegenstück zu @code{gexp->file}. -@end deffn - -@deffn {Monadische Prozedur} text-file* @var{Name} @var{Text} @dots{} -Liefert eine Ableitung als monadischen Wert, welche eine Textdatei erstellt, -in der der gesamte @var{Text} enthalten ist. @var{Text} kann eine Folge -nicht nur von Zeichenketten, sondern auch Objekten beliebigen Typs sein, die -in einem G-Ausdruck benutzt werden können, also Paketen, Ableitungen, -Objekte lokaler Dateien und so weiter. Die resultierende Store-Datei -referenziert alle davon. - -Diese Variante sollte gegenüber @code{text-file} bevorzugt verwendet werden, -wann immer die zu erstellende Datei Objekte im Store referenzieren -wird. Typischerweise ist das der Fall, wenn eine Konfigurationsdatei -erstellt wird, die Namen von Store-Dateien enthält, so wie hier: - -@example -(define (profile.sh) - ;; Liefert den Namen eines Shell-Skripts im Store, - ;; welcher die Umgebungsvariable »PATH« initialisiert. - (text-file* "profile.sh" - "export PATH=" coreutils "/bin:" - grep "/bin:" sed "/bin\n")) -@end example - -In diesem Beispiel wird die resultierende Datei -@file{/gnu/store/@dots{}-profile.sh} sowohl @var{coreutils}, @var{grep} als -auch @var{sed} referenzieren, so dass der Müllsammler diese nicht löscht, -während die resultierende Datei noch lebendig ist. -@end deffn - -@deffn {Scheme-Prozedur} mixed-text-file @var{Name} @var{Text} @dots{} -Liefert ein Objekt, was die Store-Datei @var{Name} repräsentiert, die -@var{Text} enthält. @var{Text} ist dabei eine Folge von Zeichenketten und -dateiartigen Objekten wie zum Beispiel: - -@example -(mixed-text-file "profile" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -Dies ist das deklarative Gegenstück zu @code{text-file*}. -@end deffn - -@deffn {Scheme-Prozedur} file-union @var{Name} @var{Dateien} -Liefert ein @code{<computed-file>}, das ein Verzeichnis mit allen -@var{Dateien} enthält. Jedes Objekt in @var{Dateien} muss eine -zweielementige Liste sein, deren erstes Element der im neuen Verzeichnis zu -benutzende Dateiname ist und deren zweites Element ein G-Ausdruck ist, der -die Zieldatei benennt. Hier ist ein Beispiel: - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -Dies liefert ein Verzeichnis @code{etc}, das zwei Dateien enthält. -@end deffn - -@deffn {Scheme-Prozedur} directory-union @var{Name} @var{Dinge} -Liefert ein Verzeichnis, was die Vereinigung (englisch »Union«) der -@var{Dinge} darstellt, wobei @var{Dinge} eine Liste dateiartiger Objekte -sein muss, die Verzeichnisse bezeichnen. Zum Beispiel: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -Das liefert ein Verzeichnis, welches die Vereinigung der Pakete @code{guile} -und @code{emacs} ist. -@end deffn - -@deffn {Scheme-Prozedur} file-append @var{Objekt} @var{Suffix} @dots{} -Liefert ein dateiartiges Objekt, das zur Aneinanderreihung von @var{Objekt} -und @var{Suffix} umgeschrieben wird, wobei das @var{Objekt} ein -herunterbrechbares Objekt und jedes @var{Suffix} eine Zeichenkette sein -muss. - -Betrachten Sie zum Beispiel diesen G-Ausdruck: - -@example -(gexp->script "uname-ausfuehren" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -Denselben Effekt könnte man erreichen mit: - -@example -(gexp->script "uname-ausfuehren" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -Es gibt jedoch einen Unterschied, nämlich enthält das resultierende Skript -bei @code{file-append} tatsächlich den absoluten Dateinamen als -Zeichenkette, während im anderen Fall das resultierende Skript einen -Ausdruck @code{(string-append @dots{})} enthält, der den Dateinamen erst -@emph{zur Laufzeit} zusammensetzt. -@end deffn - - -Natürlich gibt es zusätzlich zu in »wirtsseitigem« Code eingebetteten -G-Ausdrücken auch Module mit »erstellungsseitig« nutzbaren Werkzeugen. Um -klarzustellen, dass sie dafür gedacht sind, in der Erstellungsschicht -benutzt zu werden, bleiben diese Module im Namensraum @code{(guix build -@dots{})}. - -@cindex Herunterbrechen, von abstrakten Objekten in G-Ausdrücken -Intern werden hochsprachliche, abstrakte Objekte mit ihrem Compiler entweder -zu Ableitungen oder zu Store-Objekten @dfn{heruntergebrochen}. Wird zum -Beispiel ein Paket heruntergebrochen, bekommt man eine Ableitung, während -ein @code{plain-file} zu einem Store-Objekt heruntergebrochen wird. Das wird -mit der monadischen Prozedur @code{lower-object} bewerkstelligt. - -@deffn {Monadische Prozedur} lower-object @var{Objekt} [@var{System}] @ - [#:target #f] Liefert die Ableitung oder das Store-Objekt, das dem -@var{Objekt} für @var{System} als Wert in der Store-Monade -@var{%store-monad} entspricht, cross-kompiliert für das Zieltripel -@var{target}, wenn @var{target} wahr ist. Das @var{Objekt} muss ein Objekt -sein, für das es einen mit ihm assoziierten G-Ausdruck-Compiler gibt, wie -zum Beispiel ein @code{<package>}. -@end deffn - -@node Aufruf von guix repl -@section @command{guix repl} aufrufen - -@cindex REPL (Lese-Auswerten-Schreiben-Schleife) -The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop} -(REPL) for interactive programming (@pxref{Using Guile Interactively,,, -guile, GNU Guile Reference Manual}). Compared to just launching the -@command{guile} command, @command{guix repl} guarantees that all the Guix -modules and all its dependencies are available in the search path. You can -use it this way: - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> -@end example - -@cindex Untergeordnete -In addition, @command{guix repl} implements a simple machine-readable REPL -protocol for use by @code{(guix inferior)}, a facility to interact with -@dfn{inferiors}, separate processes running a potentially different revision -of Guix. - -Folgende @var{Optionen} gibt es: - -@table @code -@item --type=@var{type} -@itemx -t @var{type} -Start a REPL of the given @var{TYPE}, which can be one of the following: - -@table @code -@item guile -This is default, and it spawns a standard full-featured Guile REPL. -@item machine -Spawn a REPL that uses the machine-readable protocol. This is the protocol -that the @code{(guix inferior)} module speaks. -@end table - -@item --listen=@var{Endpunkt} -By default, @command{guix repl} reads from standard input and writes to -standard output. When this option is passed, it will instead listen for -connections on @var{endpoint}. Here are examples of valid options: - -@table @code -@item --listen=tcp:37146 -Accept connections on localhost on port 37146. - -@item --listen=unix:/tmp/socket -Accept connections on the Unix-domain socket @file{/tmp/socket}. -@end table -@end table - -@c ********************************************************************* -@node Zubehör -@chapter Zubehör - -Dieser Abschnitt beschreibt die Befehlszeilenwerkzeuge von Guix. Manche -davon richten sich hauptsächlich an Entwickler und solche Nutzer, die neue -Paketdefinitionen schreiben, andere sind auch für ein breiteres Publikum -nützlich. Sie ergänzen die Scheme-Programmierschnittstelle um bequeme -Befehle. - -@menu -* Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen. -* Aufruf von guix edit:: Paketdefinitionen bearbeiten. -* Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres - Hashes. -* Aufruf von guix hash:: Den kryptographischen Hash einer Datei - berechnen. -* Aufruf von guix import:: Paketdefinitionen importieren. -* Aufruf von guix refresh:: Paketdefinitionen aktualisieren. -* Aufruf von guix lint:: Fehler in Paketdefinitionen finden. -* Aufruf von guix size:: Plattenverbrauch profilieren. -* Aufruf von guix graph:: Den Paketgraphen visualisieren. -* Aufruf von guix publish:: Substitute teilen. -* Aufruf von guix challenge:: Die Substitut-Server anfechten. -* Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen. -* Aufruf von guix container:: Prozesse isolieren. -* Aufruf von guix weather:: Die Verfügbarkeit von Substituten - einschätzen. -* Aufruf von guix processes:: Auflisten der Client-Prozesse -@end menu - -@node Aufruf von guix build -@section Aufruf von @command{guix build} - -@cindex Paketerstellung -@cindex @command{guix build} -Der Befehl @command{guix build} lässt Pakete oder Ableitungen samt ihrer -Abhängigkeiten erstellen und gibt die resultierenden Pfade im Store -aus. Beachten Sie, dass das Nutzerprofil dadurch nicht modifiziert wird — -eine solche Installation bewirkt der Befehl @command{guix package} -(@pxref{Aufruf von guix package}). @command{guix build} wird also -hauptsächlich von Entwicklern der Distribution benutzt. - -Die allgemeine Syntax lautet: - -@example -guix build @var{Optionen} @var{Paket-oder-Ableitung}@dots{} -@end example - -Zum Beispiel wird mit folgendem Befehl die neueste Version von Emacs und von -Guile erstellt, das zugehörige Erstellungsprotokoll angezeigt und -letztendlich werden die resultierenden Verzeichnisse ausgegeben: - -@example -guix build emacs guile -@end example - -Folgender Befehl erstellt alle Pakete, die zur Verfügung stehen: - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -Als @var{Paket-oder-Ableitung} muss entweder der Name eines in der -Software-Distribution zu findenden Pakets, wie etwa @code{coreutils} oder -@code{coreutils@@8.20}, oder eine Ableitung wie -@file{/gnu/store/@dots{}-coreutils-8.19.drv} sein. Im ersten Fall wird nach -einem Paket mit entsprechendem Namen (und optional der entsprechenden -Version) in den Modulen der GNU-Distribution gesucht (@pxref{Paketmodule}). - -Alternativ kann die Befehlszeilenoption @code{--expression} benutzt werden, -um einen Scheme-Ausdruck anzugeben, der zu einem Paket ausgewertet wird; -dies ist nützlich, wenn zwischen mehreren gleichnamigen Paketen oder -Paket-Varianten unterschieden werden muss. - -Null oder mehr @var{Optionen} können angegeben werden. Zur Verfügung stehen -die in den folgenden Unterabschnitten beschriebenen Befehlszeilenoptionen. - -@menu -* Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten - Befehle. -* Paketumwandlungsoptionen:: Varianten von Paketen erzeugen. -* Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix - build«. -* Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der - Paketerstellung. -@end menu - -@node Gemeinsame Erstellungsoptionen -@subsection Gemeinsame Erstellungsoptionen - -Einige dieser Befehlszeilenoptionen zur Steuerung des Erstellungsprozess -haben @command{guix build} und andere Befehle, mit denen Erstellungen -ausgelöst werden können, wie @command{guix package} oder @command{guix -archive}, gemeinsam. Das sind folgende: - -@table @code - -@item --load-path=@var{Verzeichnis} -@itemx -L @var{Verzeichnis} -Das @var{Verzeichnis} vorne an den Suchpfad für Paketmodule anfügen -(@pxref{Paketmodule}). - -Damit können Nutzer dafür sorgen, dass ihre eigenen selbstdefinierten Pakete -für die Befehlszeilenwerkzeuge sichtbar sind. - -@item --keep-failed -@itemx -K -Den Verzeichnisbaum, in dem fehlgeschlagene Erstellungen durchgeführt -wurden, behalten. Wenn also eine Erstellung fehlschlägt, bleibt ihr -Erstellungsbaum in @file{/tmp} erhalten. Der Name dieses Unterverzeichnisses -wird am Ende dem Erstellungsprotokolls ausgegeben. Dies hilft bei der Suche -nach Fehlern in Erstellungen. Der Abschnitt @xref{Fehlschläge beim Erstellen untersuchen} -zeigt Ihnen Hinweise und Tricks, wie Erstellungsfehler untersucht werden -können. - -Diese Option hat keine Auswirkungen, wenn eine Verbindung zu einem -entfernten Daemon über eine @code{guix://}-URI verwendet wurde (@pxref{Der Store, the @code{GUIX_DAEMON_SOCKET} variable}). - -@item --keep-going -@itemx -k -Weitermachen, auch wenn ein Teil der Erstellungen fehlschlägt. Das bedeutet, -dass der Befehl erst terminiert, wenn alle Erstellungen erfolgreich oder mit -Fehler durchgeführt wurden. - -Das normale Verhalten ist, abzubrechen, sobald eine der angegebenen -Ableitungen fehlschlägt. - -@item --dry-run -@itemx -n -Die Ableitungen nicht erstellen. - -@anchor{fallback-option} -@item --fallback -Wenn das Substituieren vorerstellter Binärdateien fehlschlägt, diese als -»Fallback« lokal selbst erstellen (@pxref{Fehler bei der Substitution}). - -@item --substitute-urls=@var{URLs} -@anchor{client-substitute-urls} -Die @var{urls} als durch Leerraumzeichen getrennte Liste von Quell-URLs für -Substitute anstelle der vorgegebenen URL-Liste für den @command{guix-daemon} -verwenden (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}). - -Das heißt, die Substitute dürfen von den @var{urls} heruntergeladen werden, -sofern sie mit einem durch den Systemadministrator autorisierten Schlüssel -signiert worden sind (@pxref{Substitute}). - -Wenn als @var{urls} eine leere Zeichenkette angegeben wurde, verhält es -sich, als wären Substitute abgeschaltet. - -@item --no-substitutes -Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle -Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab -erstellten Binärdateien erlaubt ist (@pxref{Substitute}). - -@item --no-grafts -Pakete nicht »veredeln« (engl. »graft«). Praktisch heißt das, dass als -Veredelungen verfügbare Paketaktualisierungen nicht angewandt werden. Der -Abschnitt @xref{Sicherheitsaktualisierungen} hat weitere Informationen zu Veredelungen. - -@item --rounds=@var{n} -Jede Ableitung @var{n}-mal nacheinander erstellen und einen Fehler melden, -wenn die aufeinanderfolgenden Erstellungsergebnisse nicht Bit für Bit -identisch sind. - -Das ist eine nützliche Methode, um nicht-deterministische -Erstellungsprozesse zu erkennen. Nicht-deterministische Erstellungsprozesse -sind ein Problem, weil Nutzer dadurch praktisch nicht @emph{verifizieren} -können, ob von Drittanbietern bereitgestellte Binärdateien echt sind. Der -Abschnitt @xref{Aufruf von guix challenge} erklärt dies genauer. - -Beachten Sie, dass die sich unterscheidenden Erstellungsergebnisse nicht -erhalten bleiben, so dass Sie eventuelle Fehler manuell untersuchen müssen, -z.B. indem Sie eines oder mehrere der Erstellungsergebnisse @code{guix -archive --export} auslagern (@pxref{Aufruf von guix archive}), dann neu -erstellen und letztlich die beiden Erstellungsergebnisse vergleichen. - -@item --no-build-hook -Nicht versuchen, Erstellungen über den »Build-Hook« des Daemons auszulagern -(@pxref{Auslagern des Daemons einrichten}). Somit wird lokal erstellt, statt -Erstellungen auf entfernte Maschinen auszulagern. - -@item --max-silent-time=@var{Sekunden} -Wenn der Erstellungs- oder Substitutionsprozess länger als -@var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein -Fehler beim Erstellen gemeldet. - -Standardmäßig wird die Einstellung für den Daemon benutzt (@pxref{Aufruf des guix-daemon, @code{--max-silent-time}}). - -@item --timeout=@var{Sekunden} -Entsprechend wird hier der Erstellungs- oder Substitutionsprozess -abgebrochen und als Fehlschlag gemeldet, wenn er mehr als -@var{Sekunden}-lang dauert. - -Standardmäßig wird die Einstellung für den Daemon benutzt (@pxref{Aufruf des guix-daemon, @code{--timeout}}). - -@c Note: This option is actually not part of %standard-build-options but -@c most programs honor it. -@cindex verbosity, of the command-line tools -@cindex build logs, verbosity -@item -v @var{level} -@itemx --verbosity=@var{Stufe} -Use the given verbosity @var{level}, an integer. Choosing 0 means that no -output is produced, 1 is for quiet output, and 2 shows all the build log -output on standard error. - -@item --cores=@var{n} -@itemx -c @var{n} -Die Nutzung von bis zu @var{n} Prozessorkernen für die Erstellungen -gestatten. Der besondere Wert @code{0} bedeutet, dass so viele wie möglich -benutzt werden. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Höchstens @var{n} gleichzeitige Erstellungsaufträge erlauben. Im Abschnitt -@xref{Aufruf des guix-daemon, @code{--max-jobs}}, finden Sie Details zu dieser -Option und der äquivalenten Option des @command{guix-daemon}. - -@item --debug=@var{level} -Produce debugging output coming from the build daemon. @var{level} must be -an integer between 0 and 5; higher means more verbose output. Setting a -level of 4 or more may be helpful when debugging setup issues with the build -daemon. - -@end table - -Intern ist @command{guix build} im Kern eine Schnittstelle zur Prozedur -@code{package-derivation} aus dem Modul @code{(guix packages)} und zu der -Prozedur @code{build-derivations} des Moduls @code{(guix derivations)}. - -Neben auf der Befehlszeile übergebenen Optionen beachten @command{guix -build} und andere @command{guix}-Befehle, die Erstellungen durchführen -lassen, die Umgebungsvariable @code{GUIX_BUILD_OPTIONS}. - -@defvr {Umgebungsvariable} GUIX_BUILD_OPTIONS -Nutzer können diese Variable auf eine Liste von Befehlszeilenoptionen -definieren, die automatisch von @command{guix build} und anderen -@command{guix}-Befehlen, die Erstellungen durchführen lassen, benutzt wird, -wie in folgendem Beispiel: - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -Diese Befehlszeilenoptionen werden unabhängig von den auf der Befehlszeile -übergebenen Befehlszeilenoptionen grammatikalisch analysiert und das -Ergebnis an die bereits analysierten auf der Befehlszeile übergebenen -Befehlszeilenoptionen angehängt. -@end defvr - - -@node Paketumwandlungsoptionen -@subsection Paketumwandlungsoptionen - -@cindex Paketvarianten -Eine weitere Gruppe von Befehlszeilenoptionen, die @command{guix build} und -auch @command{guix package} unterstützen, sind -@dfn{Paketumwandlungsoptionen}. Diese Optionen ermöglichen es, -@dfn{Paketvarianten} zu definieren — zum Beispiel können Pakete aus einem -anderen Quellcode als normalerweise erstellt werden. Damit ist es leicht, -angepasste Pakete schnell zu erstellen, ohne die vollständigen Definitionen -von Paketvarianten einzutippen (@pxref{Pakete definieren}). - -@table @code - -@item --with-source=@var{Quelle} -@itemx --with-source=@var{Paket}=@var{Quelle} -@itemx --with-source=@var{Paket}@@@var{Version}=@var{Quelle} -Den Paketquellcode für das @var{Paket} von der angegebenen @var{Quelle} -holen und die @var{Version} als seine Versionsnummer verwenden. Die -@var{Quelle} muss ein Dateiname oder eine URL sein wie bei @command{guix -download} (@pxref{Aufruf von guix download}). - -Wird kein @var{Paket} angegeben, wird als Paketname derjenige auf der -Befehlszeile angegebene Paketname angenommen, der zur Basis am Ende der -@var{Quelle} passt — wenn z.B. als @var{Quelle} die Datei -@code{/src/guile-2.0.10.tar.gz} angegeben wurde, entspricht das dem -@code{guile}-Paket. - -Ebenso wird, wenn keine @var{Version} angegeben wurde, die Version als -Zeichenkette aus der @var{Quelle} abgeleitet; im vorherigen Beispiel wäre -sie @code{2.0.10}. - -Mit dieser Option können Nutzer versuchen, eine andere Version ihres Pakets -auszuprobieren, als die in der Distribution enthaltene Version. Folgendes -Beispiel lädt @file{ed-1.7.tar.gz} von einem GNU-Spiegelserver herunter und -benutzt es als Quelle für das @code{ed}-Paket: - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -Für Entwickler wird es einem durch @code{--with-source} leicht gemacht, -»Release Candidates«, also Vorabversionen, zu testen: - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} oder ein Checkout eines versionskontrollierten Repositorys in einer -isolierten Umgebung zu erstellen: - -@example -$ git clone git://git.sv.gnu.org/guix.git -$ guix build guix --with-source=guix@@1.0=./guix -@end example - -@item --with-input=@var{Paket}=@var{Ersatz} -Abhängigkeiten vom @var{Paket} durch eine Abhängigkeit vom -@var{Ersatz}-Paket ersetzen. Als @var{Paket} muss ein Paketname angegeben -werden und als @var{Ersatz} eine Paketspezifikation wie @code{guile} oder -@code{guile@@1.8}. - -Mit folgendem Befehl wird zum Beispiel Guix erstellt, aber statt der -aktuellen stabilen Guile-Version hängt es von der alten Guile-Version -@code{guile@@2.0} ab: - -@example -guix build --with-input=guile=guile@@2.0 guix -@end example - -Die Ersetzung ist rekursiv und umfassend. In diesem Beispiel würde nicht nur -@code{guix}, sondern auch seine Abhängigkeit @code{guile-json} (was auch von -@code{guile} abhängt) für @code{guile@@2.0} neu erstellt. - -Implementiert wird das alles mit der Scheme-Prozedur -@code{package-input-rewriting} (@pxref{Pakete definieren, -@code{package-input-rewriting}}). - -@item --with-graft=@var{Paket}=@var{Ersatz} -Dies verhält sich ähnlich wie mit @code{--with-input}, aber mit dem -wichtigen Unterschied, dass nicht die gesamte Abhängigkeitskette neu -erstellt wird, sondern das @var{Ersatz}-Paket erstellt und die -ursprünglichen Binärdateien, die auf das @var{Paket} verwiesen haben, damit -@dfn{veredelt} werden. Im Abschnitt @xref{Sicherheitsaktualisierungen} finden Sie -weitere Informationen über Veredelungen. - -Zum Beispiel veredelt folgender Befehl Wget und alle Abhängigkeiten davon -mit der Version 3.5.4 von GnuTLS, indem Verweise auf die ursprünglich -verwendete GnuTLS-Version ersetzt werden: - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -Das hat den Vorteil, dass es viel schneller geht, als alles neu zu -erstellen. Die Sache hat aber einen Haken: Veredelung funktioniert nur, wenn -das @var{Paket} und sein @var{Ersatz} miteinander streng kompatibel sind — -zum Beispiel muss, wenn diese eine Programmbibliothek zur Verfügung stellen, -deren Binärschnittstelle (»Application Binary Interface«, kurz ABI) -kompatibel sein. Wenn das @var{Ersatz}-Paket auf irgendeine Art inkompatibel -mit dem @var{Paket} ist, könnte das Ergebnispaket unbrauchbar sein. Vorsicht -ist also geboten! - -@item --with-branch=@var{package}=@var{branch} -@cindex Git, using the latest commit -@cindex latest commit, building -Build @var{package} from the latest commit of @var{branch}. The -@code{source} field of @var{package} must be an origin with the -@code{git-fetch} method (@pxref{»origin«-Referenz}) or a @code{git-checkout} -object; the repository URL is taken from that @code{source}. Git -sub-modules of the repository are fetched, recursively. - -For instance, the following command builds @code{guile-sqlite3} from the -latest commit of its @code{master} branch, and then builds @code{guix} -(which depends on it) and @code{cuirass} (which depends on @code{guix}) -against this specific @code{guile-sqlite3} build: - -@example -guix build --with-branch=guile-sqlite3=master cuirass -@end example - -@cindex continuous integration -Obviously, since it uses the latest commit of the given branch, the result -of such a command varies over time. Nevertheless it is a convenient way to -rebuild entire software stacks against the latest commit of one or more -packages. This is particularly useful in the context of continuous -integration (CI). - -Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed -up consecutive accesses to the same repository. You may want to clean it up -once in a while to save disk space. - -@item --with-commit=@var{package}=@var{commit} -This is similar to @code{--with-branch}, except that it builds from -@var{commit} rather than the tip of a branch. @var{commit} must be a valid -Git commit SHA1 identifier. -@end table - -@node Zusätzliche Erstellungsoptionen -@subsection Zusätzliche Erstellungsoptionen - -Die unten aufgeführten Befehlszeilenoptionen funktionieren nur mit -@command{guix build}. - -@table @code - -@item --quiet -@itemx -q -Build quietly, without displaying the build log; this is equivalent to -@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var} -(or similar) and can always be retrieved using the @option{--log-file} -option. - -@item --file=@var{Datei} -@itemx -f @var{Datei} -Das Paket, die Ableitung oder das dateiähnliche Objekt erstellen, zu dem der -Code in der @var{Datei} ausgewertet wird (@pxref{G-Ausdrücke, file-like -objects}). - -Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen -(@pxref{Pakete definieren}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Build the package or derivation @var{expr} evaluates to. - -For example, @var{expr} may be @code{(@@ (gnu packages guile) guile-1.8)}, -which unambiguously designates this specific variant of version 1.8 of -Guile. - -Alternatively, @var{expr} may be a G-expression, in which case it is used as -a build program passed to @code{gexp->derivation} (@pxref{G-Ausdrücke}). - -Lastly, @var{expr} may refer to a zero-argument monadic procedure -(@pxref{Die Store-Monade}). The procedure must return a derivation as a -monadic value, which is then passed through @code{run-with-store}. - -@item --source -@itemx -S -Build the source derivations of the packages, rather than the packages -themselves. - -For instance, @code{guix build -S gcc} returns something like -@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC source -tarball. - -The returned source tarball is the result of applying any patches and code -snippets specified in the package @code{origin} (@pxref{Pakete definieren}). - -@item --sources -Fetch and return the source of @var{package-or-derivation} and all their -dependencies, recursively. This is a handy way to obtain a local copy of -all the source code needed to build @var{packages}, allowing you to -eventually build them even without network access. It is an extension of -the @code{--source} option and can accept one of the following optional -argument values: - -@table @code -@item package -This value causes the @code{--sources} option to behave in the same way as -the @code{--source} option. - -@item all -Build the source derivations of all packages, including any source that -might be listed as @code{inputs}. This is the default value. - -@example -$ guix build --sources tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzdata2015b.tar.gz.drv - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv -@end example - -@item transitive -Build the source derivations of all packages, as well of all transitive -inputs to the packages. This can be used e.g.@: to prefetch package source -for later offline building. - -@example -$ guix build --sources=transitive tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv - /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv - /gnu/store/@dots{}-grep-2.21.tar.xz.drv - /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv - /gnu/store/@dots{}-make-4.1.tar.xz.drv - /gnu/store/@dots{}-bash-4.3.tar.xz.drv -@dots{} -@end example - -@end table - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@quotation Anmerkung -The @code{--system} flag is for @emph{native} compilation and must not be -confused with cross-compilation. See @code{--target} below for information -on cross-compilation. -@end quotation - -An example use of this is on Linux-based systems, which can emulate -different personalities. For instance, passing @code{--system=i686-linux} -on an @code{x86_64-linux} system or @code{--system=armhf-linux} on an -@code{aarch64-linux} system allows you to build packages in a complete -32-bit environment. - -@quotation Anmerkung -Building for an @code{armhf-linux} system is unconditionally enabled on -@code{aarch64-linux} machines, although certain aarch64 chipsets do not -allow for this functionality, notably the ThunderX. -@end quotation - -Similarly, when transparent emulation with QEMU and @code{binfmt_misc} is -enabled (@pxref{Virtualisierungsdienste, @code{qemu-binfmt-service-type}}), -you can build for any system for which a QEMU @code{binfmt_misc} handler is -installed. - -Builds for a system other than that of the machine you are using can also be -offloaded to a remote machine of the right architecture. @xref{Auslagern des Daemons einrichten}, for more information on offloading. - -@item --target=@var{Tripel} -@cindex Cross-Kompilieren -Lässt für das angegebene @var{Tripel} cross-erstellen, dieses muss ein -gültiges GNU-Tripel wie z.B. @code{"mips64el-linux-gnu"} sein -(@pxref{Specifying target triplets, GNU configuration triplets,, autoconf, -Autoconf}). - -@anchor{build-check} -@item --check -@cindex determinism, checking -@cindex reproducibility, checking -Rebuild @var{package-or-derivation}, which are already available in the -store, and raise an error if the build results are not bit-for-bit -identical. - -This mechanism allows you to check whether previously installed substitutes -are genuine (@pxref{Substitute}), or whether the build result of a package -is deterministic. @xref{Aufruf von guix challenge}, for more background -information and tools. - -Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich -unterscheidenden Ausgaben im Store unter dem Namen -@file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den -beiden Ergebnissen leicht erkannt werden. - -@item --repair -@cindex repairing store items -@cindex Datenbeschädigung, Behebung -Attempt to repair the specified store items, if they are corrupt, by -re-downloading or rebuilding them. - -This operation is not atomic and thus restricted to @code{root}. - -@item --derivations -@itemx -d -Return the derivation paths, not the output paths, of the given packages. - -@item --root=@var{file} -@itemx -r @var{file} -@cindex GC roots, adding -@cindex garbage collector roots, adding -Make @var{file} a symlink to the result, and register it as a garbage -collector root. - -Consequently, the results of this @command{guix build} invocation are -protected from garbage collection until @var{file} is removed. When that -option is omitted, build results are eligible for garbage collection as soon -as the build completes. @xref{Aufruf von guix gc}, for more on GC roots. - -@item --log-file -@cindex build logs, access -Return the build log file names or URLs for the given -@var{package-or-derivation}, or raise an error if build logs are missing. - -This works regardless of how packages or derivations are specified. For -instance, the following invocations are equivalent: - -@example -guix build --log-file `guix build -d guile` -guix build --log-file `guix build guile` -guix build --log-file guile -guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' -@end example - -If a log is unavailable locally, and unless @code{--no-substitutes} is -passed, the command looks for a corresponding log on one of the substitute -servers (as specified with @code{--substitute-urls}.) - -So for instance, imagine you want to see the build log of GDB on MIPS, but -you are actually on an @code{x86_64} machine: - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -You can freely access a huge library of build logs! -@end table - -@node Fehlschläge beim Erstellen untersuchen -@subsection Fehlschläge beim Erstellen untersuchen - -@cindex build failures, debugging -When defining a new package (@pxref{Pakete definieren}), you will probably -find yourself spending some time debugging and tweaking the build until it -succeeds. To do that, you need to operate the build commands yourself in an -environment as close as possible to the one the build daemon uses. - -To that end, the first thing to do is to use the @option{--keep-failed} or -@option{-K} option of @command{guix build}, which will keep the failed build -tree in @file{/tmp} or whatever directory you specified as @code{TMPDIR} -(@pxref{Aufruf von guix build, @code{--keep-failed}}). - -From there on, you can @command{cd} to the failed build tree and source the -@file{environment-variables} file, which contains all the environment -variable definitions that were in place when the build failed. So let's say -you're debugging a build failure in package @code{foo}; a typical session -would look like this: - -@example -$ guix build foo -K -@dots{} @i{build fails} -$ cd /tmp/guix-build-foo.drv-0 -$ source ./environment-variables -$ cd foo-1.2 -@end example - -Now, you can invoke commands as if you were the daemon (almost) and -troubleshoot your build process. - -Sometimes it happens that, for example, a package's tests pass when you run -them manually but they fail when the daemon runs them. This can happen -because the daemon runs builds in containers where, unlike in our -environment above, network access is missing, @file{/bin/sh} does not exist, -etc. (@pxref{Einrichten der Erstellungsumgebung}). - -In such cases, you may need to run inspect the build process from within a -container similar to the one the build daemon creates: - -@example -$ guix build -K foo -@dots{} -$ cd /tmp/guix-build-foo.drv-0 -$ guix environment --no-grafts -C foo --ad-hoc strace gdb -[env]# source ./environment-variables -[env]# cd foo-1.2 -@end example - -Here, @command{guix environment -C} creates a container and spawns a new -shell in it (@pxref{Aufruf von guix environment}). The @command{--ad-hoc -strace gdb} part adds the @command{strace} and @command{gdb} commands to the -container, which would may find handy while debugging. The -@option{--no-grafts} option makes sure we get the exact same environment, -with ungrafted packages (@pxref{Sicherheitsaktualisierungen}, for more info on grafts). - -To get closer to a container like that used by the build daemon, we can -remove @file{/bin/sh}: - -@example -[env]# rm /bin/sh -@end example - -(Don't worry, this is harmless: this is all happening in the throw-away -container created by @command{guix environment}.) - -The @command{strace} command is probably not in the search path, but we can -run: - -@example -[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check -@end example - -In this way, not only you will have reproduced the environment variables the -daemon uses, you will also be running the build process in a container -similar to the one the daemon uses. - - -@node Aufruf von guix edit -@section Invoking @command{guix edit} - -@cindex @command{guix edit} -@cindex package definition, editing -So many packages, so many source files! The @command{guix edit} command -facilitates the life of users and packagers by pointing their editor at the -source file containing the definition of the specified packages. For -instance: - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -launches the program specified in the @code{VISUAL} or in the @code{EDITOR} -environment variable to view the recipe of GCC@tie{}4.9.3 and that of Vim. - -If you are using a Guix Git checkout (@pxref{Erstellung aus dem Git}), or have -created your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{Paketmodule}), you will be able to edit the package recipes. In other cases, -you will be able to examine the read-only recipes for packages currently in -the store. - - -@node Aufruf von guix download -@section Invoking @command{guix download} - -@cindex @command{guix download} -@cindex downloading package sources -When writing a package definition, developers typically need to download a -source tarball, compute its SHA256 hash, and write that hash in the package -definition (@pxref{Pakete definieren}). The @command{guix download} tool -helps with this task: it downloads a file from the given URI, adds it to the -store, and prints both its file name in the store and its SHA256 hash. - -The fact that the downloaded file is added to the store saves bandwidth: -when the developer eventually tries to build the newly defined package with -@command{guix build}, the source tarball will not have to be downloaded -again because it is already in the store. It is also a convenient way to -temporarily stash files, which may be deleted eventually (@pxref{Aufruf von guix gc}). - -The @command{guix download} command supports the same URIs as used in -package definitions. In particular, it supports @code{mirror://} URIs. -@code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guile -bindings for GnuTLS are available in the user's environment; when they are -not available, an error is raised. @xref{Guile Preparations, how to install -the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more -information. - -@command{guix download} verifies HTTPS server certificates by loading the -certificates of X.509 authorities from the directory pointed to by the -@code{SSL_CERT_DIR} environment variable (@pxref{X.509-Zertifikate}), -unless @option{--no-check-certificate} is used. - -The following options are available: - -@table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. For more information -on the valid values for @var{fmt}, @pxref{Aufruf von guix hash}. - -@item --no-check-certificate -Do not validate the X.509 certificates of HTTPS servers. - -When using this option, you have @emph{absolutely no guarantee} that you are -communicating with the authentic server responsible for the given URL, which -makes you vulnerable to ``man-in-the-middle'' attacks. - -@item --output=@var{file} -@itemx -o @var{file} -Save the downloaded file to @var{file} instead of adding it to the store. -@end table - -@node Aufruf von guix hash -@section Invoking @command{guix hash} - -@cindex @command{guix hash} -The @command{guix hash} command computes the SHA256 hash of a file. It is -primarily a convenience tool for anyone contributing to the distribution: it -computes the cryptographic hash of a file, which can be used in the -definition of a package (@pxref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix hash @var{option} @var{file} -@end example - -When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the -hash of data read from standard input. @command{guix hash} has the -following options: - -@table @code - -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. - -Supported formats: @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} and @code{hexadecimal} can be used as well). - -If the @option{--format} option is not specified, @command{guix hash} will -output the hash in @code{nix-base32}. This representation is used in the -definitions of packages. - -@item --recursive -@itemx -r -Compute the hash on @var{file} recursively. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -In this case, the hash is computed on an archive containing @var{file}, -including its children if it is a directory. Some of the metadata of -@var{file} is part of the archive; for instance, when @var{file} is a -regular file, the hash is different depending on whether @var{file} is -executable or not. Metadata such as time stamps has no impact on the hash -(@pxref{Aufruf von guix archive}). - -@item --exclude-vcs -@itemx -x -When combined with @option{--recursive}, exclude version control system -directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.) - -@vindex git-fetch -As an example, here is how you would compute the hash of a Git checkout, -which is useful when using the @code{git-fetch} method (@pxref{»origin«-Referenz}): - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Aufruf von guix import -@section Invoking @command{guix import} - -@cindex importing packages -@cindex package import -@cindex package conversion -@cindex Invoking @command{guix import} -The @command{guix import} command is useful for people who would like to add -a package to the distribution with as little work as possible---a legitimate -demand. The command knows of a few repositories from which it can -``import'' package metadata. The result is a package definition, or a -template thereof, in the format we know (@pxref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix import @var{importer} @var{options}@dots{} -@end example - -@var{importer} specifies the source from which to import package metadata, -and @var{options} specifies a package identifier and other options specific -to @var{importer}. Currently, the available ``importers'' are: - -@table @code -@item gnu -Import metadata for the given GNU package. This provides a template for the -latest version of that GNU package, including the hash of its source -tarball, and its canonical synopsis and description. - -Additional information such as the package dependencies and its license -needs to be figured out manually. - -For example, the following command returns a package definition for -GNU@tie{}Hello: - -@example -guix import gnu hello -@end example - -Specific command-line options are: - -@table @code -@item --key-download=@var{policy} -As for @code{guix refresh}, specify the policy to handle missing OpenPGP -keys when verifying the package signature. @xref{Aufruf von guix refresh, -@code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Import metadata from the @uref{https://pypi.python.org/, Python Package -Index}. Information is taken from the JSON-formatted description available -at @code{pypi.python.org} and usually includes all the relevant information, -including package dependencies. For maximum efficiency, it is recommended -to install the @command{unzip} utility, so that the importer can unzip -Python wheels and gather data from them. - -The command below imports metadata for the @code{itsdangerous} Python -package: - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item gem -@cindex gem -Import metadata from @uref{https://rubygems.org/, RubyGems}. Information is -taken from the JSON-formatted description available at @code{rubygems.org} -and includes most relevant information, including runtime dependencies. -There are some caveats, however. The metadata doesn't distinguish between -synopses and descriptions, so the same string is used for both fields. -Additionally, the details of non-Ruby dependencies required to build native -extensions is unavailable and left as an exercise to the packager. - -The command below imports metadata for the @code{rails} Ruby package: - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item cpan -@cindex CPAN -Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}. -Information is taken from the JSON-formatted metadata provided through -@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most -relevant information, such as module dependencies. License information -should be checked closely. If Perl is available in the store, then the -@code{corelist} utility will be used to filter core modules out of the list -of dependencies. - -The command command below imports metadata for the @code{Acme::Boolean} Perl -module: - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -Import metadata from @uref{https://cran.r-project.org/, CRAN}, the central -repository for the @uref{http://r-project.org, GNU@tie{}R statistical and -graphical environment}. - -Information is extracted from the @code{DESCRIPTION} file of the package. - -The command command below imports metadata for the @code{Cairo} R package: - -@example -guix import cran Cairo -@end example - -When @code{--recursive} is added, the importer will traverse the dependency -graph of the given upstream package recursively and generate package -expressions for all those packages that are not yet in Guix. - -When @code{--archive=bioconductor} is added, metadata is imported from -@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R -packages for for the analysis and comprehension of high-throughput genomic -data in bioinformatics. - -Information is extracted from the @code{DESCRIPTION} file of a package -published on the web interface of the Bioconductor SVN repository. - -The command below imports metadata for the @code{GenomicRanges} R package: - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex TeX Live -@cindex CTAN -Import metadata from @uref{http://www.ctan.org/, CTAN}, the comprehensive -TeX archive network for TeX packages that are part of the -@uref{https://www.tug.org/texlive/, TeX Live distribution}. - -Information about the package is obtained through the XML API provided by -CTAN, while the source code is downloaded from the SVN repository of the Tex -Live project. This is done because the CTAN does not keep versioned -archives. - -The command command below imports metadata for the @code{fontspec} TeX -package: - -@example -guix import texlive fontspec -@end example - -When @code{--archive=DIRECTORY} is added, the source code is downloaded not -from the @file{latex} sub-directory of the @file{texmf-dist/source} tree in -the TeX Live SVN repository, but from the specified sibling directory under -the same root. - -The command below imports metadata for the @code{ifxetex} package from CTAN -while fetching the sources from the directory @file{texmf/source/generic}: - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, import -Import package metadata from a local JSON file. Consider the following -example package definition in JSON format: - -@example -@{ - "name": "hello", - "version": "2.10", - "source": "mirror://gnu/hello/hello-2.10.tar.gz", - "build-system": "gnu", - "home-page": "https://www.gnu.org/software/hello/", - "synopsis": "Hello, GNU world: An example GNU package", - "description": "GNU Hello prints a greeting.", - "license": "GPL-3.0+", - "native-inputs": ["gcc@@6"] -@} -@end example - -The field names are the same as for the @code{<package>} record -(@xref{Pakete definieren}). References to other packages are provided as -JSON lists of quoted package specification strings such as @code{guile} or -@code{guile@@2.0}. - -The importer also supports a more explicit source definition using the -common fields for @code{<origin>} records: - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -The command below reads metadata from the JSON file @code{hello.json} and -outputs a package expression: - -@example -guix import json hello.json -@end example - -@item nix -Import metadata from a local copy of the source of the -@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies -on the @command{nix-instantiate} command of @uref{http://nixos.org/nix/, -Nix}.}. Package definitions in Nixpkgs are typically written in a mixture -of Nix-language and Bash code. This command only imports the high-level -package structure that is written in the Nix language. It normally includes -all the basic fields of a package definition. - -When importing a GNU package, the synopsis and descriptions are replaced by -their canonical upstream variant. - -Usually, you will first need to do: - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -so that @command{nix-instantiate} does not try to open the Nix database. - -As an example, the command below imports the package definition of -LibreOffice (more precisely, it imports the definition of the package bound -to the @code{libreoffice} top-level attribute): - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Import metadata from the Haskell community's central package archive -@uref{https://hackage.haskell.org/, Hackage}. Information is taken from -Cabal files and includes all the relevant information, including package -dependencies. - -Specific command-line options are: - -@table @code -@item --stdin -@itemx -s -Read a Cabal file from standard input. -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --cabal-environment=@var{alist} -@itemx -e @var{alist} -@var{alist} is a Scheme alist defining the environment in which the Cabal -conditionals are evaluated. The accepted keys are: @code{os}, @code{arch}, -@code{impl} and a string representing the name of a flag. The value -associated with a flag has to be either the symbol @code{true} or -@code{false}. The value associated with other keys has to conform to the -Cabal file format definition. The default value associated with the keys -@code{os}, @code{arch} and @code{impl} is @samp{linux}, @samp{x86_64} and -@samp{ghc}, respectively. -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -The command below imports metadata for the latest version of the @code{HTTP} -Haskell package without including test dependencies and specifying the value -of the flag @samp{network-uri} as @code{false}: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -A specific package version may optionally be specified by following the -package name by an at-sign and a version number as in the following example: - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -The @code{stackage} importer is a wrapper around the @code{hackage} one. It -takes a package name, looks up the package version included in a long-term -support (LTS) @uref{https://www.stackage.org, Stackage} release and uses the -@code{hackage} importer to retrieve its metadata. Note that it is up to you -to select an LTS release compatible with the GHC compiler used by Guix. - -Specific command-line options are: - -@table @code -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --lts-version=@var{version} -@itemx -l @var{Version} -@var{version} is the desired LTS release version. If omitted the latest -release is used. -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -The command below imports metadata for the @code{HTTP} Haskell package -included in the LTS Stackage release version 7.18: - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Import metadata from an Emacs Lisp Package Archive (ELPA) package repository -(@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Specific command-line options are: - -@table @code -@item --archive=@var{repo} -@itemx -a @var{repo} -@var{repo} identifies the archive repository from which to retrieve the -information. Currently the supported repositories and their identifiers -are: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} -identifier. This is the default. - -Packages from @code{elpa.gnu.org} are signed with one of the keys contained -in the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (or -similar) in the @code{emacs} package (@pxref{Package Installation, ELPA -package signatures,, emacs, The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the -@code{melpa-stable} identifier. - -@item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} -identifier. -@end itemize - -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item crate -@cindex crate -Import metadata from the crates.io Rust package repository -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package -repository used by the OCaml community. -@end table - -The structure of the @command{guix import} code is modular. It would be -useful to have more importers for other package formats, and your help is -welcome here (@pxref{Mitwirken}). - -@node Aufruf von guix refresh -@section Invoking @command{guix refresh} - -@cindex @command{guix refresh} -The primary audience of the @command{guix refresh} command is developers of -the GNU software distribution. By default, it reports any packages provided -by the distribution that are outdated compared to the latest upstream -version, like this: - -@example -$ guix refresh -gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1 -gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0 -@end example - -Alternately, one can specify packages to consider, in which case a warning -is emitted for packages that lack an updater: - -@example -$ guix refresh coreutils guile guile-ssh -gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh -gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13 -@end example - -@command{guix refresh} browses the upstream repository of each package and -determines the highest version number of the releases therein. The command -knows how to update specific types of packages: GNU packages, ELPA packages, -etc.---see the documentation for @option{--type} below. There are many -packages, though, for which it lacks a method to determine whether a new -upstream release is available. However, the mechanism is extensible, so -feel free to get in touch with us to add a new method! - -@table @code - -@item --recursive -Consider the packages specified, and all the packages upon which they -depend. - -@example -$ guix refresh --recursive coreutils -gnu/packages/acl.scm:35:2: warning: no updater for acl -gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4 -gnu/packages/xml.scm:68:2: warning: no updater for expat -gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp -@dots{} -@end example - -@end table - -Sometimes the upstream name differs from the package name used in Guix, and -@command{guix refresh} needs a little help. Most updaters honor the -@code{upstream-name} property in package definitions, which can be used to -that effect: - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -When passed @code{--update}, it modifies distribution source files to update -the version numbers and source tarball hashes of those package recipes -(@pxref{Pakete definieren}). This is achieved by downloading each package's -latest source tarball and its associated OpenPGP signature, authenticating -the downloaded tarball against its signature using @command{gpg}, and -finally computing its hash. When the public key used to sign the tarball is -missing from the user's keyring, an attempt is made to automatically -retrieve it from a public key server; when this is successful, the key is -added to the user's keyring; otherwise, @command{guix refresh} reports an -error. - -The following options are supported: - -@table @code - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -This is useful to precisely refer to a package, as in this example: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -This command lists the dependents of the ``final'' libc (essentially all the -packages.) - -@item --update -@itemx -u -Update distribution source files (package recipes) in place. This is -usually run from a checkout of the Guix source tree (@pxref{Guix vor der Installation ausführen}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Pakete definieren}, for more information on package definitions. - -@item --select=[@var{subset}] -@itemx -s @var{subset} -Select all the packages in @var{subset}, one of @code{core} or -@code{non-core}. - -The @code{core} subset refers to all the packages at the core of the -distribution---i.e., packages that are used to build ``everything else''. -This includes GCC, libc, Binutils, Bash, etc. Usually, changing one of -these packages in the distribution entails a rebuild of all the others. -Thus, such updates are an inconvenience to users in terms of build time or -bandwidth used to achieve the upgrade. - -The @code{non-core} subset refers to the remaining packages. It is -typically useful in cases where an update of the core packages would be -inconvenient. - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Select all the packages from the manifest in @var{file}. This is useful to -check if any packages of the user manifest can be updated. - -@item --type=@var{updater} -@itemx -t @var{updater} -Select only packages handled by @var{updater} (may be a comma-separated list -of updaters). Currently, @var{updater} may be one of: - -@table @code -@item gnu -the updater for GNU packages; -@item gnome -the updater for GNOME packages; -@item kde -the updater for KDE packages; -@item xorg -the updater for X.org packages; -@item kernel.org -the updater for packages hosted on kernel.org; -@item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; -@item cran -the updater for @uref{https://cran.r-project.org/, CRAN} packages; -@item bioconductor -the updater for @uref{https://www.bioconductor.org/, Bioconductor} R -packages; -@item cpan -the updater for @uref{http://www.cpan.org/, CPAN} packages; -@item pypi -the updater for @uref{https://pypi.python.org, PyPI} packages. -@item gem -the updater for @uref{https://rubygems.org, RubyGems} packages. -@item github -the updater for @uref{https://github.com, GitHub} packages. -@item hackage -the updater for @uref{https://hackage.haskell.org, Hackage} packages. -@item stackage -the updater for @uref{https://www.stackage.org, Stackage} packages. -@item crate -the updater for @uref{https://crates.io, Crates} packages. -@end table - -For instance, the following command only checks for updates of Emacs -packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages: - -@example -$ guix refresh --type=elpa,cran -gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0 -gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9 -@end example - -@end table - -In addition, @command{guix refresh} can be passed one or more package names, -as in this example: - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -The command above specifically updates the @code{emacs} and @code{idutils} -packages. The @code{--select} option would have no effect in this case. - -When considering whether to upgrade a package, it is sometimes convenient to -know which packages would be affected by the upgrade and should be checked -for compatibility. For this the following option may be used when passing -@command{guix refresh} one or more package names: - -@table @code - -@item --list-updaters -@itemx -L -List available updaters and exit (see @option{--type} above.) - -For each updater, display the fraction of packages it covers; at the end, -display the fraction of packages covered by all these updaters. - -@item --list-dependent -@itemx -l -List top-level dependent packages that would need to be rebuilt as a result -of upgrading one or more packages. - -@xref{Aufruf von guix graph, the @code{reverse-package} type of @command{guix -graph}}, for information on how to visualize the list of dependents of a -package. - -@end table - -Be aware that the @code{--list-dependent} option only @emph{approximates} -the rebuilds that would be required as a result of an upgrade. More -rebuilds might be required under some circumstances. - -@example -$ guix refresh --list-dependent flex -Building the following 120 packages would ensure 213 dependent packages are rebuilt: -hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} -@end example - -The command above lists a set of packages that could be built to check for -compatibility with an upgraded @code{flex} package. - -@table @code - -@item --list-transitive -List all the packages which one or more packages depend upon. - -@example -$ guix refresh --list-transitive flex -flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6 -bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{} -@end example - -@end table - -The command above lists a set of packages which, when changed, would cause -@code{flex} to be rebuilt. - -The following options can be used to customize GnuPG operation: - -@table @code - -@item --gpg=@var{command} -Use @var{command} as the GnuPG 2.x command. @var{command} is searched for -in @code{$PATH}. - -@item --keyring=@var{Datei} -Use @var{file} as the keyring for upstream keys. @var{file} must be in the -@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx} -and the GNU@tie{}Privacy Guard (GPG) can manipulate these files -(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, -for information on a tool to manipulate keybox files). - -When this option is omitted, @command{guix refresh} uses -@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream -signing keys. OpenPGP signatures are checked against keys from this -keyring; missing keys are downloaded to this keyring as well (see -@option{--key-download} below.) - -You can export keys from your default GPG keyring into a keybox file using -commands like this one: - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx -@end example - -Likewise, you can fetch keys to a specific keybox file like this: - -@example -gpg --no-default-keyring --keyring mykeyring.kbx \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU -Privacy Guard}, for more information on GPG's @option{--keyring} option. - -@item --key-download=@var{policy} -Handle missing OpenPGP keys according to @var{policy}, which may be one of: - -@table @code -@item always -Always download missing OpenPGP keys from the key server, and add them to -the user's GnuPG keyring. - -@item never -Never try to download missing OpenPGP keys. Instead just bail out. - -@item interactive -When a package signed with an unknown OpenPGP key is encountered, ask the -user whether to download it or not. This is the default behavior. -@end table - -@item --key-server=@var{host} -Use @var{host} as the OpenPGP key server when importing a public key. - -@end table - -The @code{github} updater uses the @uref{https://developer.github.com/v3/, -GitHub API} to query for new releases. When used repeatedly e.g.@: when -refreshing all packages, GitHub will eventually refuse to answer any further -API requests. By default 60 API requests per hour are allowed, and a full -refresh on all GitHub packages in Guix requires more than this. -Authentication with GitHub through the use of an API token alleviates these -limits. To use an API token, set the environment variable -@code{GUIX_GITHUB_TOKEN} to a token procured from -@uref{https://github.com/settings/tokens} or otherwise. - - -@node Aufruf von guix lint -@section Invoking @command{guix lint} - -@cindex @command{guix lint} -@cindex package, checking for errors -The @command{guix lint} command is meant to help package developers avoid -common errors and use a consistent style. It runs a number of checks on a -given set of packages in order to find common mistakes in their -definitions. Available @dfn{checkers} include (see @code{--list-checkers} -for a complete list): - -@table @code -@item synopsis -@itemx description -Validate certain typographical and stylistic rules about package -descriptions and synopses. - -@item inputs-should-be-native -Identify inputs that should most likely be native inputs. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Probe @code{home-page} and @code{source} URLs and report those that are -invalid. Suggest a @code{mirror://} URL when applicable. If the -@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub -URL. Check that the source file name is meaningful, e.g.@: is not just a -version number or ``git-checkout'', without a declared @code{file-name} -(@pxref{»origin«-Referenz}). - -@item source-unstable-tarball -Parse the @code{source} URL to determine if a tarball from GitHub is -autogenerated or if it is a release tarball. Unfortunately GitHub's -autogenerated tarballs are sometimes regenerated. - -@item cve -@cindex security vulnerabilities -@cindex CVE, Common Vulnerabilities and Exposures -Report known vulnerabilities found in the Common Vulnerabilities and -Exposures (CVE) databases of the current and past year -@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US NIST}. - -To view information about a particular vulnerability, visit pages such as: - -@itemize -@item -@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD} -@item -@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD} -@end itemize - -@noindent -where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g., -@code{CVE-2015-7554}. - -Package developers can specify in package recipes the -@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)} name -and version of the package when they differ from the name or version that -Guix uses, as in this example: - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE calls this package "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>. -Some entries in the CVE database do not specify which version of a package -they apply to, and would thus ``stick around'' forever. Package developers -who found CVE alerts and verified they can be ignored can declare them as in -this example: - -@example -(package - (name "t1lib") - ;; @dots{} - ;; These CVEs no longer apply and can be safely ignored. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item formatting -Warn about obvious source code formatting issues: trailing white space, use -of tabulations, etc. -@end table - -Die allgemeine Syntax lautet: - -@example -guix lint @var{options} @var{package}@dots{} -@end example - -If no package is given on the command line, then all packages are checked. -The @var{options} may be zero or more of the following: - -@table @code -@item --list-checkers -@itemx -l -List and describe all the available checkers that will be run on packages -and exit. - -@item --checkers -@itemx -c -Only enable the checkers specified in a comma-separated list using the names -returned by @code{--list-checkers}. - -@end table - -@node Aufruf von guix size -@section Invoking @command{guix size} - -@cindex size -@cindex package size -@cindex Abschluss -@cindex @command{guix size} -The @command{guix size} command helps package developers profile the disk -usage of packages. It is easy to overlook the impact of an additional -dependency added to a package, or the impact of using a single output for a -package that could easily be split (@pxref{Pakete mit mehreren Ausgaben.}). Such are the typical issues that @command{guix size} can -highlight. - -The command can be passed one or more package specifications such as -@code{gcc@@4.8} or @code{guile:debug}, or a file name in the store. -Consider this example: - -@example -$ guix size coreutils -store item total self -/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1% -/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6% -/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0% -/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4% -/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9% -/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5% -/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3% -/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2% -total: 78.9 MiB -@end example - -@cindex Abschluss -The store items listed here constitute the @dfn{transitive closure} of -Coreutils---i.e., Coreutils and all its dependencies, recursively---as would -be returned by: - -@example -$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 -@end example - -Here the output shows three columns next to store items. The first column, -labeled ``total'', shows the size in mebibytes (MiB) of the closure of the -store item---that is, its own size plus the size of all its dependencies. -The next column, labeled ``self'', shows the size of the item itself. The -last column shows the ratio of the size of the item itself to the space -occupied by all the items listed here. - -In this example, we see that the closure of Coreutils weighs in at -79@tie{}MiB, most of which is taken by libc and GCC's run-time support -libraries. (That libc and GCC's libraries represent a large fraction of the -closure is not a problem @i{per se} because they are always available on the -system anyway.) - -When the package(s) passed to @command{guix size} are available in the -store@footnote{More precisely, @command{guix size} looks for the -@emph{ungrafted} variant of the given package(s), as returned by @code{guix -build @var{package} --no-grafts}. @xref{Sicherheitsaktualisierungen}, for information -on grafts.}, @command{guix size} queries the daemon to determine its -dependencies, and measures its size in the store, similar to @command{du -ms ---apparent-size} (@pxref{du invocation,,, coreutils, GNU Coreutils}). - -When the given packages are @emph{not} in the store, @command{guix size} -reports information based on the available substitutes -(@pxref{Substitute}). This makes it possible it to profile disk usage of -store items that are not even on disk, only available remotely. - -You can also specify several package names: - -@example -$ guix size coreutils grep sed bash -store item total self -/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4% -/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8% -/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6% -/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2% -@dots{} -total: 102.3 MiB -@end example - -@noindent -In this example we see that the combination of the four packages takes -102.3@tie{}MiB in total, which is much less than the sum of each closure -since they have a lot of dependencies in common. - -The available options are: - -@table @option - -@item --substitute-urls=@var{URLs} -Use substitute information from @var{urls}. @xref{client-substitute-urls, -the same option for @code{guix build}}. - -@item --sort=@var{key} -Sort lines according to @var{key}, one of the following options: - -@table @code -@item self -the size of each item (the default); -@item Abschluss -the total size of the item's closure. -@end table - -@item --map-file=@var{file} -Write a graphical map of disk usage in PNG format to @var{file}. - -For the example above, the map looks like this: - -@image{images/coreutils-size-map,5in,, map of Coreutils disk usage produced -by @command{guix size}} - -This option requires that -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be -installed and visible in Guile's module search path. When that is not the -case, @command{guix size} fails as it tries to load it. - -@item --system=@var{System} -@itemx -s @var{System} -Consider packages for @var{system}---e.g., @code{x86_64-linux}. - -@end table - -@node Aufruf von guix graph -@section Invoking @command{guix graph} - -@cindex DAG -@cindex @command{guix graph} -@cindex Paketabhängigkeiten -Packages and their dependencies form a @dfn{graph}, specifically a directed -acyclic graph (DAG). It can quickly become difficult to have a mental model -of the package DAG, so the @command{guix graph} command provides a visual -representation of the DAG. By default, @command{guix graph} emits a DAG -representation in the input format of @uref{http://www.graphviz.org/, -Graphviz}, so its output can be passed directly to the @command{dot} command -of Graphviz. It can also emit an HTML page with embedded JavaScript code to -display a ``chord diagram'' in a Web browser, using the -@uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct -a graph in a graph database supporting the @uref{http://www.opencypher.org/, -openCypher} query language. The general syntax is: - -@example -guix graph @var{options} @var{package}@dots{} -@end example - -For example, the following command generates a PDF file representing the -package DAG for the GNU@tie{}Core Utilities, showing its build-time -dependencies: - -@example -guix graph coreutils | dot -Tpdf > dag.pdf -@end example - -The output looks like this: - -@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils} - -Nice little graph, no? - -But there is more than one graph! The one above is concise: it is the graph -of package objects, omitting implicit inputs such as GCC, libc, grep, etc. -It is often useful to have such a concise graph, but sometimes one may want -to see more details. @command{guix graph} supports several types of graphs, -allowing you to choose the level of detail: - -@table @code -@item package -This is the default type used in the example above. It shows the DAG of -package objects, excluding implicit dependencies. It is concise, but -filters out many details. - -@item reverse-package -This shows the @emph{reverse} DAG of packages. For example: - -@example -guix graph --type=reverse-package ocaml -@end example - -...@: yields the graph of packages that depend on OCaml. - -Note that for core packages this can yield huge graphs. If all you want is -to know the number of packages that depend on a given package, use -@command{guix refresh --list-dependent} (@pxref{Aufruf von guix refresh, -@option{--list-dependent}}). - -@item bag-emerged -This is the package DAG, @emph{including} implicit inputs. - -For instance, the following command: - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf -@end example - -...@: yields this bigger graph: - -@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU -Coreutils} - -At the bottom of the graph, we see all the implicit inputs of -@var{gnu-build-system} (@pxref{Erstellungssysteme, @code{gnu-build-system}}). - -Now, note that the dependencies of these implicit inputs---that is, the -@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown here, -for conciseness. - -@item bag -Similar to @code{bag-emerged}, but this time including all the bootstrap -dependencies. - -@item bag-with-origins -Similar to @code{bag}, but also showing origins and their dependencies. - -@item Ableitung -This is the most detailed representation: It shows the DAG of derivations -(@pxref{Ableitungen}) and plain store items. Compared to the above -representation, many additional nodes are visible, including build scripts, -patches, Guile modules, etc. - -For this type of graph, it is also possible to pass a @file{.drv} file name -instead of a package name, as in: - -@example -guix graph -t derivation `guix system build -d my-config.scm` -@end example - -@item module -This is the graph of @dfn{package modules} (@pxref{Paketmodule}). For -example, the following command shows the graph for the package module that -defines the @code{guile} package: - -@example -guix graph -t module guile | dot -Tpdf > module-graph.pdf -@end example -@end table - -All the types above correspond to @emph{build-time dependencies}. The -following graph type represents the @emph{run-time dependencies}: - -@table @code -@item references -This is the graph of @dfn{references} of a package output, as returned by -@command{guix gc --references} (@pxref{Aufruf von guix gc}). - -If the given package output is not available in the store, @command{guix -graph} attempts to obtain dependency information from substitutes. - -Here you can also pass a store file name instead of a package name. For -example, the command below produces the reference graph of your profile -(which can be big!): - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -This is the graph of the @dfn{referrers} of a store item, as returned by -@command{guix gc --referrers} (@pxref{Aufruf von guix gc}). - -This relies exclusively on local information from your store. For instance, -let us suppose that the current Inkscape is available in 10 profiles on your -machine; @command{guix graph -t referrers inkscape} will show a graph rooted -at Inkscape and with those 10 profiles linked to it. - -It can help determine what is preventing a store item from being garbage -collected. - -@end table - -The available options are the following: - -@table @option -@item --type=@var{type} -@itemx -t @var{type} -Produce a graph output of @var{type}, where @var{type} must be one of the -values listed above. - -@item --list-types -List the supported graph types. - -@item --backend=@var{backend} -@itemx -b @var{backend} -Produce a graph using the selected @var{backend}. - -@item --list-backends -List the supported graph backends. - -Currently, the available backends are Graphviz and d3.js. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -This is useful to precisely refer to a package, as in this example: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{System} -@itemx -s @var{System} -Display the graph for @var{system}---e.g., @code{i686-linux}. - -The package dependency graph is largely architecture-independent, but there -are some architecture-dependent bits that this option allows you to -visualize. -@end table - - - -@node Aufruf von guix publish -@section @command{guix publish} aufrufen - -@cindex @command{guix publish} -Der Zweck von @command{guix publish} ist, es Nutzern zu ermöglichen, ihren -Store auf einfache Weise mit anderen zu teilen, die ihn dann als -Substitutserver einsetzen können (@pxref{Substitute}). - -When @command{guix publish} runs, it spawns an HTTP server which allows -anyone with network access to obtain substitutes from it. This means that -any machine running Guix can also act as if it were a build farm, since the -HTTP interface is compatible with Hydra, the software behind the -@code{@value{SUBSTITUTE-SERVER}} build farm. - -Um Sicherheit zu gewährleisten, wird jedes Substitut signiert, so dass -Empfänger dessen Authentizität und Integrität nachprüfen können (siehe -@pxref{Substitute}). Weil @command{guix publish} den Signierschlüssel des -Systems benutzt, der nur vom Systemadministrator gelesen werden kann, muss -es als der Administratornutzer »root« gestartet werden. Mit der -Befehlszeilenoption @code{--user} werden Administratorrechte bald nach dem -Start wieder abgelegt. - -Das Schlüsselpaar zum Signieren muss erzeugt werden, bevor @command{guix -publish} gestartet wird. Dazu können Sie @command{guix archive ---generate-key} ausführen (@pxref{Aufruf von guix archive}). - -Die allgemeine Syntax lautet: - -@example -guix publish @var{Optionen}@dots{} -@end example - -Wird @command{guix publish} ohne weitere Argumente ausgeführt, wird damit -ein HTTP-Server gestartet, der auf Port 8080 lauscht: - -@example -guix publish -@end example - -Sobald ein Server zum Veröffentlichen autorisiert wurde (@pxref{Aufruf von guix archive}), kann der Daemon davon Substitute herunterladen: - -@example -guix-daemon --substitute-urls=http://example.org:8080 -@end example - -Nach den Voreinstellungen komprimiert @command{guix publish} Archive erst -dann, wenn sie angefragt werden. Dieser »dynamische« Modus bietet sich an, -weil so nichts weiter eingerichtet werden muss und er direkt verfügbar -ist. Wenn Sie allerdings viele Clients bedienen wollen, empfehlen wir, dass -Sie die Befehlszeilenoption @option{--cache} benutzen, die das -Zwischenspeichern der komprimierten Archive aktiviert, bevor diese an die -Clients geschickt werden — siehe unten für Details. Mit dem Befehl -@command{guix weather} haben Sie eine praktische Methode zur Hand, zu -überprüfen, was so ein Server anbietet (@pxref{Aufruf von guix weather}). - -Als Bonus dient @command{guix publish} auch als inhaltsadressierbarer -Spiegelserver für Quelldateien, die in @code{origin}-Verbundsobjekten -eingetragen sind (@pxref{»origin«-Referenz}). Wenn wir zum Beispiel annehmen, -dass @command{guix publish} auf @code{example.org} läuft, liefert folgende -URL die rohe @file{hello-2.10.tar.gz}-Datei mit dem angegebenen SHA256-Hash -als ihre Prüfsumme (dargestellt im @code{nix-base32}-Format, siehe -@pxref{Aufruf von guix hash}): - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -Offensichtlich funktionieren diese URLs nur mit solchen Dateien, die auch im -Store vorliegen; in anderen Fällen werden sie 404 (»Nicht gefunden«) -zurückliefern. - -@cindex Erstellungsprotokolle, Veröffentlichen -Erstellungsprotokolle sind unter @code{/log}-URLs abrufbar: - -@example -http://example.org/log/gwspk@dots{}-guile-2.2.3 -@end example - -@noindent -Ist der @command{guix-daemon} so eingestellt, dass er Erstellungsprotokolle -komprimiert abspeichert, wie es voreingestellt ist (@pxref{Aufruf des guix-daemon}), liefern @code{/log}-URLs das unveränderte komprimierte -Protokoll, mit einer entsprechenden @code{Content-Type}- und/oder -@code{Content-Encoding}-Kopfzeile. Wir empfehlen dabei, dass Sie den -@command{guix-daemon} mit @code{--log-compression=gzip} ausführen, weil -Web-Browser dieses Format automatisch dekomprimieren können, was bei -bzip2-Kompression nicht der Fall ist. - -The following options are available: - -@table @code -@item --port=@var{Port} -@itemx -p @var{Port} -Auf HTTP-Anfragen auf diesem @var{Port} lauschen. - -@item --listen=@var{Host} -Auf der Netzwerkschnittstelle für den angegebenen @var{Host}, also der -angegebenen Rechneradresse, lauschen. Vorgegeben ist, Verbindungen mit jeder -Schnittstelle zu akzeptieren. - -@item --user=@var{Benutzer} -@itemx -u @var{Benutzer} -So früh wie möglich alle über die Berechtigungen des @var{Benutzer}s -hinausgehenden Berechtigungen ablegen — d.h. sobald der Server-Socket -geöffnet und der Signierschlüssel gelesen wurde. - -@item --compression[=@var{Stufe}] -@itemx -C [@var{Stufe}] -Daten auf der angegebenen Kompressions-@var{Stufe} komprimieren. Wird als -@var{Stufe} null angegeben, wird Kompression deaktiviert. Der Bereich von 1 -bis 9 entspricht unterschiedlichen gzip-Kompressionsstufen: 1 ist am -schnellsten, während 9 am besten komprimiert (aber den Prozessor mehr -auslastet). Der Vorgabewert ist 3. - -Wenn @option{--cache} nicht übergeben wird, werden Daten dynamisch immer -erst dann komprimiert, wenn sie abgeschickt werden; komprimierte Datenströme -landen in keinem Zwischenspeicher. Um also die Auslastung der Maschine, auf -der @command{guix publish} läuft, zu reduzieren, kann es eine gute Idee -sein, eine niedrige Kompressionsstufe zu wählen, @command{guix publish} -einen Proxy mit Zwischenspeicher (einen »Caching Proxy«) voranzuschalten, -oder @option{--cache} zu benutzen. @option{--cache} zu benutzen, hat den -Vorteil, dass @command{guix publish} damit eine -@code{Content-Length}-HTTP-Kopfzeile seinen Antworten beifügen kann. - -@item --cache=@var{Verzeichnis} -@itemx -c @var{Verzeichnis} -Archive und Metadaten (@code{.narinfo}-URLs) in das @var{Verzeichnis} -zwischenspeichern und nur solche Archive versenden, die im Zwischenspeicher -vorliegen. - -Wird diese Befehlszeilenoption weggelassen, dann werden Archive und -Metadaten »dynamisch« erst auf eine Anfrage hin erzeugt. Dadurch kann die -verfügbare Bandbreite reduziert werden, besonders wenn Kompression aktiviert -ist, weil die Operation dann durch die Prozessorleistung beschränkt sein -kann. Noch ein Nachteil des voreingestellten Modus ist, dass die Länge der -Archive nicht im Voraus bekannt ist, @command{guix publish} also keine -@code{Content-Length}-HTTP-Kopfzeile an seine Antworten anfügt, wodurch -Clients nicht wissen können, welche Datenmenge noch heruntergeladen werden -muss. - -Im Gegensatz dazu liefert, wenn @option{--cache} benutzt wird, die erste -Anfrage nach einem Store-Objekt (über dessen @code{.narinfo}-URL) den -Fehlercode 404, und im Hintergrund wird ein Prozess gestartet, der das -Archiv in den Zwischenspeicher einlagert (auf Englisch sagen wir »@dfn{bake} -the archive«), d.h. seine @code{.narinfo} wird berechnet und das Archiv, -falls nötig, komprimiert. Sobald das Archiv im @var{Verzeichnis} -zwischengespeichert wurde, werden nachfolgende Anfragen erfolgreich sein und -direkt aus dem Zwischenspeicher bedient, der garantiert, dass Clients -optimale Bandbreite genießen. - -Der Prozess zum Einlagern wird durch Worker-Threads umgesetzt. Der Vorgabe -entsprechend wird dazu pro Prozessorkern ein Thread erzeugt, aber dieses -Verhalten kann angepasst werden. Siehe @option{--workers} weiter unten. - -Wird @option{--ttl} verwendet, werden zwischengespeicherte Einträge -automatisch gelöscht, sobald die dabei angegebene Zeit abgelaufen ist. - -@item --workers=@var{N} -Wird @option{--cache} benutzt, wird die Reservierung von @var{N} -Worker-Threads angefragt, um Archive einzulagern. - -@item --ttl=@var{ttl} -@code{Cache-Control}-HTTP-Kopfzeilen erzeugen, die eine Time-to-live (TTL) -von @var{ttl} signalisieren. Für @var{ttl} muss eine Dauer (mit dem -Anfangsbuchstaben der Maßeinheit der Dauer im Englischen) angegeben werden: -@code{5d} bedeutet 5 Tage, @code{1m} bedeutet 1 Monat und so weiter. - -Das ermöglicht es Guix, Substitutinformationen @var{ttl} lang -zwischenzuspeichern. Beachten Sie allerdings, dass @code{guix publish} -selbst @emph{nicht} garantiert, dass die davon angebotenen Store-Objekte so -lange verfügbar bleiben, wie es die @var{ttl} vorsieht. - -Des Weiteren können bei Nutzung von @option{--cache} die -zwischengespeicherten Einträge gelöscht werden, wenn auf sie @var{ttl} lang -nicht zugegriffen wurde und kein ihnen entsprechendes Objekt mehr im Store -existiert. - -@item --nar-path=@var{Pfad} -Den @var{Pfad} als Präfix für die URLs von »nar«-Dateien benutzen -(@pxref{Aufruf von guix archive, normalized archives}). - -Vorgegeben ist, dass Nars unter einer URL mit -@code{/nar/gzip/@dots{}-coreutils-8.25} angeboten werden. Mit dieser -Befehlszeilenoption können Sie den @code{/nar}-Teil durch den angegebenen -@var{Pfad} ersetzen. - -@item --public-key=@var{Datei} -@itemx --private-key=@var{Datei} -Die angegebenen @var{Datei}en als das Paar aus öffentlichem und privatem -Schlüssel zum Signieren veröffentlichter Store-Objekte benutzen. - -Die Dateien müssen demselben Schlüsselpaar entsprechen (der private -Schlüssel wird zum Signieren benutzt, der öffentliche Schlüssel wird -lediglich in den Metadaten der Signatur aufgeführt). Die Dateien müssen -Schlüssel im kanonischen (»canonical«) S-Ausdruck-Format enthalten, wie es -von @command{guix archive --generate-key} erzeugt wird (@pxref{Aufruf von guix archive}). Vorgegeben ist, dass @file{/etc/guix/signing-key.pub} und -@file{/etc/guix/signing-key.sec} benutzt werden. - -@item --repl[=@var{Port}] -@itemx -r [@var{Port}] -Einen Guile-REPL-Server (@pxref{REPL Servers,,, guile, GNU Guile Reference -Manual}) auf diesem @var{Port} starten (37146 ist voreingestellt). Dies kann -zur Fehlersuche auf einem laufenden »@command{guix publish}«-Server benutzt -werden. -@end table - -Enabling @command{guix publish} on Guix System is a one-liner: just -instantiate a @code{guix-publish-service-type} service in the -@code{services} field of the @code{operating-system} declaration -(@pxref{guix-publish-service-type, @code{guix-publish-service-type}}). - -Falls Sie Guix aber auf einer »Fremddistribution« laufen lassen, folgen Sie -folgenden Anweisungen: - -@itemize -@item -Wenn Ihre Wirtsdistribution systemd als »init«-System benutzt: - -@example -# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \ - /etc/systemd/system/ -# systemctl start guix-publish && systemctl enable guix-publish -@end example - -@item -Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet: - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -Verfahren Sie andernfalls auf die gleiche Art für das »init«-System, das -Ihre Distribution verwendet. -@end itemize - -@node Aufruf von guix challenge -@section Invoking @command{guix challenge} - -@cindex Reproduzierbare Erstellungen -@cindex verifiable builds -@cindex @command{guix challenge} -@cindex challenge -Do the binaries provided by this server really correspond to the source code -it claims to build? Is a package build process deterministic? These are the -questions the @command{guix challenge} command attempts to answer. - -The former is obviously an important question: Before using a substitute -server (@pxref{Substitute}), one had better @emph{verify} that it provides -the right binaries, and thus @emph{challenge} it. The latter is what -enables the former: If package builds are deterministic, then independent -builds of the package should yield the exact same result, bit for bit; if a -server provides a binary different from the one obtained locally, it may be -either corrupt or malicious. - -We know that the hash that shows up in @file{/gnu/store} file names is the -hash of all the inputs of the process that built the file or -directory---compilers, libraries, build scripts, -etc. (@pxref{Einführung}). Assuming deterministic build processes, one -store file name should map to exactly one build output. @command{guix -challenge} checks whether there is, indeed, a single mapping by comparing -the build outputs of several independent builds of any given store item. - -The command output looks like this: - -@smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" -updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0% -updating list of substitutes from 'https://guix.example.org'... 100.0% -/gnu/store/@dots{}-openssl-1.0.2d contents differ: - local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim -/gnu/store/@dots{}-git-2.5.0 contents differ: - local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 -/gnu/store/@dots{}-pius-2.1.1 contents differ: - local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs - -@dots{} - -6,406 store items were analyzed: - - 4,749 (74.1%) were identical - - 525 (8.2%) differed - - 1,132 (17.7%) were inconclusive -@end smallexample - -@noindent -In this example, @command{guix challenge} first scans the store to determine -the set of locally-built derivations---as opposed to store items that were -downloaded from a substitute server---and then queries all the substitute -servers. It then reports those store items for which the servers obtained a -result different from the local build. - -@cindex non-determinism, in package builds -As an example, @code{guix.example.org} always gets a different answer. -Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, -except in the case of Git. This might indicate that the build process of -Git is non-deterministic, meaning that its output varies as a function of -various things that Guix does not fully control, in spite of building -packages in isolated environments (@pxref{Funktionalitäten}). Most common sources -of non-determinism include the addition of timestamps in build results, the -inclusion of random numbers, and directory listings sorted by inode number. -See @uref{https://reproducible-builds.org/docs/}, for more information. - -To find out what is wrong with this Git binary, we can do something along -these lines (@pxref{Aufruf von guix archive}): - -@example -$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ - | guix archive -x /tmp/git -$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git -@end example - -This command shows the difference between the files resulting from the local -build, and the files resulting from the build on -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging -Files,, diffutils, Comparing and Merging Files}). The @command{diff} -command works great for text files. When binary files differ, a better -option is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps -visualize differences for all kinds of files. - -Once you have done that work, you can tell whether the differences are due -to a non-deterministic build process or to a malicious server. We try hard -to remove sources of non-determinism in packages to make it easier to verify -substitutes, but of course, this is a process that involves not just Guix, -but a large part of the free software community. In the meantime, -@command{guix challenge} is one tool to help address the problem. - -If you are writing packages for Guix, you are encouraged to check whether -@code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the -same build result as you did with: - -@example -$ guix challenge @var{package} -@end example - -@noindent -where @var{package} is a package specification such as @code{guile@@2.0} or -@code{glibc:debug}. - -Die allgemeine Syntax lautet: - -@example -guix challenge @var{options} [@var{packages}@dots{}] -@end example - -When a difference is found between the hash of a locally-built item and that -of a server-provided substitute, or among substitutes provided by different -servers, the command displays it as in the example above and its exit code -is 2 (other non-zero exit codes denote other kinds of errors.) - -The one option that matters is: - -@table @code - -@item --substitute-urls=@var{URLs} -Consider @var{urls} the whitespace-separated list of substitute source URLs -to compare to. - -@item --verbose -@itemx -v -Show details about matches (identical contents) in addition to information -about mismatches. - -@end table - -@node Aufruf von guix copy -@section Invoking @command{guix copy} - -@cindex copy, of store items, over SSH -@cindex SSH, copy of store items -@cindex sharing store items across machines -@cindex transferring store items across machines -The @command{guix copy} command copies items from the store of one machine -to that of another machine over a secure shell (SSH) -connection@footnote{This command is available only when Guile-SSH was -found. @xref{Voraussetzungen}, for details.}. For example, the following -command copies the @code{coreutils} package, the user's profile, and all -their dependencies over to @var{host}, logged in as @var{user}: - -@example -guix copy --to=@var{user}@@@var{host} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -If some of the items to be copied are already present on @var{host}, they -are not actually sent. - -The command below retrieves @code{libreoffice} and @code{gimp} from -@var{host}, assuming they are available there: - -@example -guix copy --from=@var{host} libreoffice gimp -@end example - -The SSH connection is established using the Guile-SSH client, which is -compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and -@file{~/.ssh/config}, and uses the SSH agent for authentication. - -The key used to sign items that are sent must be accepted by the remote -machine. Likewise, the key used by the remote machine to sign items you are -retrieving must be in @file{/etc/guix/acl} so it is accepted by your own -daemon. @xref{Aufruf von guix archive}, for more information about store item -authentication. - -Die allgemeine Syntax lautet: - -@example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} -@end example - -You must always specify one of the following options: - -@table @code -@item --to=@var{spec} -@itemx --from=@var{spec} -Specify the host to send to or receive from. @var{spec} must be an SSH spec -such as @code{example.org}, @code{charlie@@example.org}, or -@code{charlie@@example.org:2222}. -@end table - -The @var{items} can be either package names, such as @code{gimp}, or store -items, such as @file{/gnu/store/@dots{}-idutils-4.6}. - -When specifying the name of a package to send, it is first built if needed, -unless @option{--dry-run} was specified. Common build options are supported -(@pxref{Gemeinsame Erstellungsoptionen}). - - -@node Aufruf von guix container -@section Invoking @command{guix container} -@cindex container -@cindex @command{guix container} -@quotation Anmerkung -As of version @value{VERSION}, this tool is experimental. The interface is -subject to radical change in the future. -@end quotation - -The purpose of @command{guix container} is to manipulate processes running -within an isolated environment, commonly known as a ``container'', typically -created by the @command{guix environment} (@pxref{Aufruf von guix environment}) and @command{guix system container} (@pxref{Aufruf von guix system}) commands. - -Die allgemeine Syntax lautet: - -@example -guix container @var{action} @var{options}@dots{} -@end example - -@var{action} specifies the operation to perform with a container, and -@var{options} specifies the context-specific arguments for the action. - -The following actions are available: - -@table @code -@item exec -Execute a command within the context of a running container. - -The syntax is: - -@example -guix container exec @var{pid} @var{program} @var{arguments}@dots{} -@end example - -@var{pid} specifies the process ID of the running container. @var{program} -specifies an executable file name within the root file system of the -container. @var{arguments} are the additional options that will be passed -to @var{program}. - -The following command launches an interactive login shell inside a Guix -system container, started by @command{guix system container}, and whose -process ID is 9001: - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Note that the @var{pid} cannot be the parent process of a container. It -must be PID 1 of the container or one of its child processes. - -@end table - -@node Aufruf von guix weather -@section Invoking @command{guix weather} - -Occasionally you're grumpy because substitutes are lacking and you end up -building packages by yourself (@pxref{Substitute}). The @command{guix -weather} command reports on substitute availability on the specified servers -so you can have an idea of whether you'll be grumpy today. It can sometimes -be useful info as a user, but it is primarily useful to people running -@command{guix publish} (@pxref{Aufruf von guix publish}). - -@cindex statistics, for substitutes -@cindex availability of substitutes -@cindex substitute availability -@cindex weather, substitute availability -Here's a sample run: - -@example -$ guix weather --substitute-urls=https://guix.example.org -computing 5,872 package derivations for x86_64-linux... -looking for 6,128 store items on https://guix.example.org.. -updating list of substitutes from 'https://guix.example.org'... 100.0% -https://guix.example.org - 43.4% substitutes available (2,658 out of 6,128) - 7,032.5 MiB of nars (compressed) - 19,824.2 MiB on disk (uncompressed) - 0.030 seconds per request (182.9 seconds in total) - 33.5 requests per second - - 9.8% (342 out of 3,470) of the missing items are queued - 867 queued builds - x86_64-linux: 518 (59.7%) - i686-linux: 221 (25.5%) - aarch64-linux: 128 (14.8%) - build rate: 23.41 builds per hour - x86_64-linux: 11.16 builds per hour - i686-linux: 6.03 builds per hour - aarch64-linux: 6.41 builds per hour -@end example - -@cindex continuous integration, statistics -As you can see, it reports the fraction of all the packages for which -substitutes are available on the server---regardless of whether substitutes -are enabled, and regardless of whether this server's signing key is -authorized. It also reports the size of the compressed archives (``nars'') -provided by the server, the size the corresponding store items occupy in the -store (assuming deduplication is turned off), and the server's throughput. -The second part gives continuous integration (CI) statistics, if the server -supports it. In addition, using the @option{--coverage} option, -@command{guix weather} can list ``important'' package substitutes missing on -the server (see below). - -To achieve that, @command{guix weather} queries over HTTP(S) meta-data -(@dfn{narinfos}) for all the relevant store items. Like @command{guix -challenge}, it ignores signatures on those substitutes, which is innocuous -since the command only gathers statistics and cannot install those -substitutes. - -Among other things, it is possible to query specific system types and -specific package sets. The available options are listed below. - -@table @code -@item --substitute-urls=@var{URLs} -@var{urls} is the space-separated list of substitute server URLs to query. -When this option is omitted, the default set of substitute servers is -queried. - -@item --system=@var{System} -@itemx -s @var{System} -Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This -option can be repeated, in which case @command{guix weather} will query -substitutes for several system types. - -@item --manifest=@var{Datei} -Instead of querying substitutes for all the packages, only ask for those -specified in @var{file}. @var{file} must contain a @dfn{manifest}, as with -the @code{-m} option of @command{guix package} (@pxref{Aufruf von guix package}). - -@item --coverage[=@var{count}] -@itemx -c [@var{count}] -Report on substitute coverage for packages: list packages with at least -@var{count} dependents (zero by default) for which substitutes are -unavailable. Dependent packages themselves are not listed: if @var{b} -depends on @var{a} and @var{a} has no substitutes, only @var{a} is listed, -even though @var{b} usually lacks substitutes as well. The result looks -like this: - -@example -$ guix weather --substitute-urls=https://ci.guix.de.info -c 10 -computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.de.info... -updating substitutes from 'https://ci.guix.de.info'... 100.0% -https://ci.guix.de.info - 64.7% substitutes available (6,047 out of 9,343) -@dots{} -2502 packages are missing from 'https://ci.guix.de.info' for 'x86_64-linux', among which: - 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 - 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 - 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 - @dots{} -@end example - -What this example shows is that @code{kcoreaddons} and presumably the 58 -packages that depend on it have no substitutes at @code{ci.guix.de.info}; -likewise for @code{qgpgme} and the 46 packages that depend on it. - -If you are a Guix developer, or if you are taking care of this build farm, -you'll probably want to have a closer look at these packages: they may -simply fail to build. -@end table - -@node Aufruf von guix processes -@section @command{guix processes} aufrufen - -The @command{guix processes} command can be useful to developers and system -administrators, especially on multi-user machines and on build farms: it -lists the current sessions (connections to the daemon), as well as -information about the processes involved@footnote{Remote sessions, when -@command{guix-daemon} is started with @option{--listen} specifying a TCP -endpoint, are @emph{not} listed.}. Here's an example of the information it -returns: - -@example -$ sudo guix processes -SessionPID: 19002 -ClientPID: 19090 -ClientCommand: guix environment --ad-hoc python - -SessionPID: 19402 -ClientPID: 19367 -ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{} - -SessionPID: 19444 -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock -LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock -LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock -ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800 -ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800 -ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800 -@end example - -In this example we see that @command{guix-daemon} has three clients: -@command{guix environment}, @command{guix publish}, and the Cuirass -continuous integration tool; their process identifier (PID) is given by the -@code{ClientPID} field. The @code{SessionPID} field gives the PID of the -@command{guix-daemon} sub-process of this particular session. - -The @code{LockHeld} fields show which store items are currently locked by -this session, which corresponds to store items being built or substituted -(the @code{LockHeld} field is not displayed when @command{guix processes} is -not running as root.) Last, by looking at the @code{ChildProcess} field, we -understand that these three builds are being offloaded (@pxref{Auslagern des Daemons einrichten}). - -The output is in Recutils format so we can use the handy @command{recsel} -command to select sessions of interest (@pxref{Selection Expressions,,, -recutils, GNU recutils manual}). As an example, the command shows the -command line and PID of the client that triggered the build of a Perl -package: - -@example -$ sudo guix processes | \ - recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -@end example - - -@node Systemkonfiguration -@chapter Systemkonfiguration - -@cindex Systemkonfiguration -Die Guix-Systemdistribution unterstützt einen Mechanismus zur konsistenten -Konfiguration des gesamten Systems. Damit meinen wir, dass alle Aspekte der -globalen Systemkonfiguration an einem Ort stehen, d.h. die zur Verfügung -gestellten Systemdienste, die Zeitzone und Einstellungen zur Locale (also -die Anpassung an regionale Gepflogenheiten und Sprachen) sowie -Benutzerkonten. Sie alle werden an derselben Stelle deklariert. So eine -@dfn{Systemkonfiguration} kann @dfn{instanziiert}, also umgesetzt, werden. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -Einer der Vorteile, die ganze Systemkonfiguration unter die Kontrolle von -Guix zu stellen, ist, dass so transaktionelle Systemaktualisierungen möglich -werden und dass diese rückgängig gemacht werden können, wenn das -aktualisierte System nicht richtig funktioniert (@pxref{Funktionalitäten}). Ein -anderer Vorteil ist, dass dieselbe Systemkonfiguration leicht auf einer -anderen Maschine oder zu einem späteren Zeitpunkt benutzt werden kann, ohne -dazu eine weitere Schicht administrativer Werkzeuge über den systemeigenen -Werkzeugen einsetzen zu müssen. - -In diesem Abschnitt wird dieser Mechanismus beschrieben. Zunächst betrachten -wir ihn aus der Perspektive eines Administrators. Dabei wird erklärt, wie -das System konfiguriert und instanziiert werden kann. Dann folgt eine -Demonstration, wie der Mechanismus erweitert werden kann, etwa um neue -Systemdienste zu unterstützen. - -@menu -* Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen. -* »operating-system«-Referenz:: Details der Betriebssystem-Deklarationen. -* Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. -* Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. -* Benutzerkonten:: Benutzerkonten festlegen. -* Locales:: Sprache und kulturelle Konventionen. -* Dienste:: Systemdienste festlegen. -* Setuid-Programme:: Mit Administratorrechten startende Programme. -* X.509-Zertifikate:: HTTPS-Server authentifizieren. -* Name Service Switch:: Den Name Service Switch von libc konfigurieren. -* Initiale RAM-Disk:: Linux-libre hochfahren. -* Bootloader-Konfiguration:: Den Bootloader konfigurieren. -* Aufruf von guix system:: Instanziierung einer Systemkonfiguration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Dienste definieren:: Neue Dienstdefinitionen hinzufügen. -@end menu - -@node Das Konfigurationssystem nutzen -@section Das Konfigurationssystem nutzen - -Das Betriebssystem können Sie konfigurieren, indem Sie eine -@code{operating-system}-Deklaration in einer Datei speichern, die Sie dann -dem Befehl @command{guix system} übergeben (@pxref{Aufruf von guix system}). Eine einfache Konfiguration mit den vorgegebenen Systemdiensten -und dem vorgegebenen Linux-Libre als Kernel und mit einer initialen RAM-Disk -und einem Bootloader, sieht so aus: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -Dieses Beispiel sollte selbsterklärend sein. Manche der Felder oben, wie -etwa @code{host-name} und @code{bootloader}, müssen angegeben werden. Andere -sind optional, wie etwa @code{packages} und @code{services}, sind optional; -werden sie nicht angegeben, nehmen sie einen Vorgabewert an. - -Im Folgenden werden die Effekte von einigen der wichtigsten Feldern -erläutert (@pxref{»operating-system«-Referenz}, für Details zu allen -verfügbaren Feldern), dann wird beschrieben, wie man das Betriebssystem mit -@command{guix system} @dfn{instanziieren} kann. - -@unnumberedsubsec Bootloader - -@cindex Legacy-Boot, auf Intel-Maschinen -@cindex BIOS-Boot, auf Intel-Maschinen -@cindex UEFI-Boot -@cindex EFI-Boot -Das @code{bootloader}-Feld beschreibt, mit welcher Methode Ihr System -»gebootet« werden soll. Maschinen, die auf Intel-Prozessoren basieren, -können im alten »Legacy«-BIOS-Modus gebootet werden, wie es im obigen -Beispiel der Fall wäre. Neuere Maschinen benutzen stattdessen das -@dfn{Unified Extensible Firmware Interface} (UEFI) zum Booten. In diesem -Fall sollte das @code{bootloader}-Feld in etwa so aussehen: - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -Siehe den Abschnitt @xref{Bootloader-Konfiguration} für weitere -Informationen zu den verfügbaren Konfigurationsoptionen. - -@unnumberedsubsec global sichtbare Pakete - -@vindex %base-packages -Im Feld @code{packages} werden Pakete aufgeführt, die auf dem System für -alle Benutzerkonten global sichtbar sein sollen, d.h. in der -@code{PATH}-Umgebungsvariablen jedes Nutzers, zusätzlich zu den -nutzereigenen Profilen (@pxref{Aufruf von guix package}). Die Variable -@var{%base-packages} bietet alle Werkzeuge, die man für grundlegende Nutzer- -und Administratortätigkeiten erwarten würde, einschließlich der GNU Core -Utilities, der GNU Networking Utilities, des leichtgewichtigen Texteditors -GNU Zile, @command{find}, @command{grep} und so weiter. Obiges Beispiel fügt -zu diesen noch das Programm GNU@tie{}Screen hinzu, welches aus dem Modul -@code{(gnu packages screen)} genommen wird (@pxref{Paketmodule}). Die -Syntax @code{(list package output)} kann benutzt werden, um eine bestimmte -Ausgabe eines Pakets auszuwählen: - -@lisp -(use-modules (gnu packages)) -(use-modules (gnu packages dns)) - -(operating-system - ;; ... - (packages (cons (list bind "utils") - %base-packages))) -@end lisp - -@findex specification->package -Sich auf Pakete anhand ihres Variablennamens zu beziehen, wie oben bei -@code{bind}, hat den Vorteil, dass der Name eindeutig ist; Tippfehler werden -direkt als »unbound variables« gemeldet. Der Nachteil ist, dass man wissen -muss, in welchem Modul ein Paket definiert wird, um die Zeile mit -@code{use-package-modules} entsprechend zu ergänzen. Um dies zu vermeiden, -kann man auch die Prozedur @code{specification->package} aus dem Modul -@code{(gnu packages)} aufrufen, welche das einem angegebenen Namen oder -Name-Versions-Paar zu Grunde liegende Paket liefert: - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec Systemdienste - -@cindex services -@vindex %base-services -The @code{services} field lists @dfn{system services} to be made available -when the system starts (@pxref{Dienste}). The @code{operating-system} -declaration above specifies that, in addition to the basic services, we want -the OpenSSH secure shell daemon listening on port 2222 (@pxref{Netzwerkdienste, @code{openssh-service-type}}). Under the hood, -@code{openssh-service-type} arranges so that @command{sshd} is started with -the right command-line options, possibly with supporting configuration files -generated as needed (@pxref{Dienste definieren}). - -@cindex Anpassung, von Diensten -@findex modify-services -Gelegentlich werden Sie die Basis-Dienste nicht einfach so, wie sie sind, -benutzen, sondern anpassen wollen. Benutzen Sie @code{modify-services} -(@pxref{Service-Referenz, @code{modify-services}}), um die Liste der -Basis-Dienste zu modifizieren. - -Wenn Sie zum Beispiel @code{guix-daemon} und Mingetty (das Programm, womit -Sie sich auf der Konsole anmelden) in der @var{%base-services}-Liste -modifizieren möchten (@pxref{Basisdienste, @code{%base-services}}), -schreiben Sie das Folgende in Ihre Betriebssystemdeklaration: - -@lisp -(define %my-services - ;; Meine ganz eigene Liste von Diensten. - (modify-services %base-services - (guix-service-type config => - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '("--gc-keep-derivations")))) - (mingetty-service-type config => - (mingetty-configuration - (inherit config))))) - -(operating-system - ;; @dots{} - (services %my-services)) -@end lisp - -Dadurch ändert sich die Konfiguration — d.h. die Dienst-Parameter — der -@code{guix-service-type}-Instanz und die aller -@code{mingetty-service-type}-Instanzen in der -@var{%base-services}-Liste. Das funktioniert so: Zunächst arrangieren wir, -dass die ursprüngliche Konfiguration an den Bezeichner @code{config} im -@var{Rumpf} gebunden wird, dann schreiben wir den @var{Rumpf}, damit er zur -gewünschten Konfiguration ausgewertet wird. Beachten Sie insbesondere, wie -wir mit @code{inherit} eine neue Konfiguration erzeugen, die dieselben Werte -wie die alte Konfiguration hat, aber mit ein paar Modifikationen. - -@cindex verschlüsselte Partition -Die Konfiguration für typische »Schreibtisch«-Nutzung zum Arbeiten, mit -einer verschlüsselten Partition für das Wurzeldateisystem, einem -X11-Display-Server, GNOME und Xfce (Benutzer können im Anmeldebildschirm -auswählen, welche dieser Arbeitsumgebungen sie möchten, indem sie die Taste -@kbd{F1} drücken), Netzwerkverwaltung, Verwaltungswerkzeugen für den -Energieverbrauch, und Weiteres, würde so aussehen: - -@lisp -@include os-config-desktop.texi -@end lisp - -Ein grafisches System mit einer Auswahl an leichtgewichtigen -Fenster-Managern statt voll ausgestatteten Arbeitsumgebungen würde so -aussehen: - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -Dieses Beispiel bezieht sich auf das Dateisystem hinter @file{/boot/efi} -über dessen UUID, @code{1234-ABCD}. Schreiben Sie statt dieser UUID die -richtige UUID für Ihr System, wie sie der Befehl @command{blkid} liefert. - -Im Abschnitt @xref{Desktop-Dienste} finden Sie eine genaue Liste der unter -@var{%desktop-services} angebotenen Dienste. Der Abschnitt @xref{X.509-Zertifikate} hat Hintergrundinformationen über das @code{nss-certs}-Paket, -das hier benutzt wird. - -Beachten Sie, dass @var{%desktop-services} nur eine Liste von die Dienste -repräsentierenden service-Objekten ist. Wenn Sie Dienste daraus entfernen -möchten, können Sie dazu die Prozeduren zum Filtern von Listen benutzen -(@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile Reference -Manual}). Beispielsweise liefert der folgende Ausdruck eine Liste mit allen -Diensten von @var{%desktop-services} außer dem Avahi-Dienst. - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Das System instanziieren - -Angenommen, Sie haben die @code{operating-system}-Deklaration in einer Datei -@file{my-system-config.scm} gespeichert, dann instanziiert der Befehl -@command{guix system reconfigure my-system-config.scm} diese Konfiguration -und macht sie zum voreingestellten GRUB-Boot-Eintrag (@pxref{Aufruf von guix system}). - -Der normale Weg, die Systemkonfiguration nachträglich zu ändern, ist, die -Datei zu aktualisieren und @command{guix system reconfigure} erneut -auszuführen. Man sollte nie die Dateien in @file{/etc} bearbeiten oder den -Systemzustand mit Befehlen wie @command{useradd} oder @command{grub-install} -verändern. Tatsächlich müssen Sie das ausdrücklich vermeiden, sonst verfällt -nicht nur Ihre Garantie, sondern Sie können Ihr System auch nicht mehr auf -eine alte Version des Systems zurücksetzen, falls das jemals notwendig wird. - -@cindex Zurücksetzen, des Betriebssystems -Zurücksetzen bezieht sich hierbei darauf, dass jedes Mal, wenn Sie -@command{guix system reconfigure} ausführen, eine neue @dfn{Generation} des -Systems erzeugt wird — ohne vorherige Generationen zu verändern. Alte -Systemgenerationen bekommen einen Eintrag im Boot-Menü des Bootloaders, -womit Sie alte Generationen beim Booten des Rechners auswählen können, wenn -mit der neuesten Generation etwas nicht stimmt. Eine beruhigende -Vorstellung, oder? Der Befehl @command{guix system list-generations} führt -die auf der Platte verfügbaren Systemgenerationen auf. Es ist auch möglich, -das System mit den Befehlen @command{guix system roll-back} und -@command{guix system switch-generation} zurückzusetzen. - -Obwohl der Befehl @command{guix system reconfigure} vorherige Generationen -nicht verändern wird, müssen Sie Acht geben, dass wenn die momentan aktuelle -Generation nicht die neueste ist (z.B. nach einem Aufruf von @command{guix -system roll-back}), weil @command{guix system reconfigure} alle neueren -Generationen überschreibt (@pxref{Aufruf von guix system}). - -@unnumberedsubsec Die Programmierschnittstelle - -Auf der Ebene von Scheme wird der Großteil der -@code{operating-system}-Deklaration mit der folgenden monadischen Prozedur -instanziiert (@pxref{Die Store-Monade}): - -@deffn {Monadische Prozedur} operating-system-derivation os -Liefert eine Ableitung, mit der ein @code{operating-system}-Objekt @var{os} -erstellt wird (@pxref{Ableitungen}). - -Die Ausgabe der Ableitung ist ein einzelnes Verzeichnis mit Verweisen auf -alle Pakete, Konfigurationsdateien und andere unterstützenden Dateien, die -nötig sind, um @var{os} zu instanziieren. -@end deffn - -This procedure is provided by the @code{(gnu system)} module. Along with -@code{(gnu services)} (@pxref{Dienste}), this module contains the guts of -Guix System. Make sure to visit it! - - -@node »operating-system«-Referenz -@section @code{operating-system}-Referenz - -Dieser Abschnitt fasst alle Optionen zusammen, die für -@code{operating-system}-Deklarationen zur Verfügung stehen (@pxref{Das Konfigurationssystem nutzen}). - -@deftp {Datentyp} operating-system -Der die Betriebssystemkonfiguration repräsentierende Datentyp. Damit meinen -wir die globale Konfiguration des Systems und nicht die, die sich nur auf -einzelne Nutzer bezieht (@pxref{Das Konfigurationssystem nutzen}). - -@table @asis -@item @code{kernel} (Vorgabe: @var{linux-libre}) -Das Paket für den zu nutzenden Betriebssystem-Kernel als -»package«-Objekt@footnote{Derzeit wird nur der Kernel Linux-libre -unterstützt. In der Zukunft wird man auch GNU@tie{}Hurd benutzen können.}. - -@item @code{kernel-arguments} (Vorgabe: @code{'()}) -Eine Liste aus Zeichenketten oder G-Ausdrücken, die für zusätzliche -Argumente an den Kernel stehen, die ihm auf seiner Befehlszeile übergeben -werden — wie z.B. @code{("console=ttyS0")}. - -@item @code{bootloader} -Das Konfigurationsobjekt für den Bootloader, mit dem das System gestartet -wird. Siehe @xref{Bootloader-Konfiguration}. - -@item @code{initrd-modules} (Vorgabe: @code{%base-initrd-modules}) -@cindex initrd -@cindex initiale RAM-Disk -Die Liste der Linux-Kernel-Module, die in der initialen RAM-Disk zur -Verfügung stehen sollen @xref{Initiale RAM-Disk}. - -@item @code{initrd} (Vorgabe: @code{base-initrd}) -Eine Prozedur, die eine initiale RAM-Disk für den Linux-Kernel -liefert. Dieses Feld gibt es, damit auch sehr systemnahe Anpassungen -vorgenommen werden können, aber für die normale Nutzung sollte man es kaum -brauchen. Siehe @xref{Initiale RAM-Disk}. - -@item @code{firmware} (Vorgabe: @var{%base-firmware}) -@cindex Firmware -Eine Liste der Firmware-Pakete, die vom Betriebssystem-Kernel geladen werden -können. - -Vorgegeben ist, dass für Atheros- und Broadcom-basierte WLAN-Geräte nötige -Firmware geladen werden kann (genauer jeweils die Linux-libre-Module -@code{ath9k} und @code{b43-open}). Siehe den Abschnitt @xref{Hardware-Überlegungen}, für mehr Informationen zu unterstützter Hardware. - -@item @code{host-name} -Der Hostname - -@item @code{hosts-file} -@cindex hosts-Datei -Ein dateiartiges Objekt (@pxref{G-Ausdrücke, file-like objects}), das für -@file{/etc/hosts} benutzt werden soll (@pxref{Host Names,,, libc, The GNU C -Library Reference Manual}). Der Vorgabewert ist eine Datei mit Einträgen für -@code{localhost} und @var{host-name}. - -@item @code{mapped-devices} (Vorgabe: @code{'()}) -Eine Liste zugeordneter Geräte (»mapped devices«). Siehe @xref{Zugeordnete Geräte}. - -@item @code{file-systems} -Eine Liste von Dateisystemen. Siehe @xref{Dateisysteme}. - -@item @code{swap-devices} (Vorgabe: @code{'()}) -@cindex Swap-Geräte -Eine Liste von Zeichenketten, die Geräte identifizieren oder als -»Swap-Speicher« genutzte Dateien identifizieren (@pxref{Memory Concepts,,, -libc, The GNU C Library Reference Manual}). Beispiele wären etwa -@code{'("/dev/sda3")} oder @code{'("/swapdatei")}. Es ist möglich, eine -Swap-Datei auf dem Dateisystem eines zugeordneten Geräts anzugeben, sofern -auch die Gerätezuordnung und das Dateisystem mit angegeben werden. Siehe -@xref{Zugeordnete Geräte} und @ref{Dateisysteme}. - -@item @code{users} (Vorgabe: @code{%base-user-accounts}) -@itemx @code{groups} (Vorgabe: @var{%base-groups}) -Liste der Benutzerkonten und Benutzergruppen. Siehe @xref{Benutzerkonten}. - -Wenn in der @code{users}-Liste kein Benutzerkonto mit der UID-Kennung@tie{}0 -aufgeführt wird, wird automatisch für den Administrator ein -»root«-Benutzerkonto mit UID-Kennung@tie{}0 hinzugefügt. - -@item @code{skeletons} (Vorgabe: @code{(default-skeletons)}) -Eine Liste von Tupeln aus je einem Ziel-Dateinamen und einem dateiähnlichen -Objekt (@pxref{G-Ausdrücke, file-like objects}). Diese Objekte werden als -Skeleton-Dateien im Persönlichen Verzeichnis (»Home«-Verzeichnis) jedes -neuen Benutzerkontos angelegt. - -Ein gültiger Wert könnte zum Beispiel so aussehen: - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hallo\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (Vorgabe: @var{%default-issue}) -Eine Zeichenkette, die als Inhalt der Datei @file{/etc/issue} verwendet -werden soll, der jedes Mal angezeigt wird, wenn sich ein Nutzer auf einer -Textkonsole anmeldet. - -@item @code{packages} (Vorgabe: @var{%base-packages}) -Die Menge der Pakete, die ins globale Profil installiert werden sollen, -welches unter @file{/run/current-system/profile} zu finden ist. - -Die vorgegebene Paketmenge umfasst zum Kern des Systems gehörende Werkzeuge -(»core utilities«). Es ist empfehlenswert, nicht zum Kern gehörende -Werkzeuge (»non-core«) stattdessen in Nutzerprofile zu installieren -(@pxref{Aufruf von guix package}). - -@item @code{timezone} -Eine Zeichenkette, die die Zeitzone bezeichnet, wie -z.B. @code{"Europe/Berlin"}. - -Mit dem Befehl @command{tzselect} können Sie herausfinden, welche -Zeichenkette der Zeitzone Ihrer Region entspricht. Wenn Sie eine ungültige -Zeichenkette angeben, schlägt @command{guix system} fehl. - -@item @code{locale} (Vorgabe: @code{"en_US.utf8"}) -Der Name der als Voreinstellung zu verwendenden Locale (@pxref{Locale -Names,,, libc, The GNU C Library Reference Manual}). Siehe @xref{Locales} -für weitere Informationen. - -@item @code{locale-definitions} (Vorgabe: @var{%default-locale-definitions}) -Die Liste der Locale-Definitionen, die kompiliert werden sollen und dann im -laufenden System benutzt werden können. Siehe @xref{Locales}. - -@item @code{locale-libcs} (Vorgabe: @code{(list @var{glibc})}) -Die Liste der GNU-libc-Pakete, deren Locale-Daten und -Werkzeuge zum -Erzeugen der Locale-Definitionen verwendet werden sollen. Siehe -@xref{Locales} für eine Erläuterung der Kompatibilitätsauswirkungen, -deretwegen man diese Option benutzen wollen könnte. - -@item @code{name-service-switch} (Vorgabe: @var{%default-nss}) -Die Konfiguration des Name Service Switch (NSS) der libc — ein -@code{<name-service-switch>}-Objekt. Siehe @xref{Name Service Switch}, für -Details. - -@item @code{services} (Vorgabe: @var{%base-services}) -Eine Liste von »service«-Objekten, die die Systemdienste -repräsentieren. Siehe @xref{Dienste}. - -@item @code{pam-services} (Vorgabe: @code{(base-pam-services)}) -@cindex PAM -@cindex Pluggable Authentication Modules -@c FIXME: Add xref to PAM services section. -Dienste für »@dfn{Pluggable Authentication Modules}« (PAM) von Linux. - -@item @code{setuid-programs} (Vorgabe: @var{%setuid-programs}) -Eine Liste von Zeichenketten liefernden G-Ausdrücken, die setuid-Programme -bezeichnen. Siehe @xref{Setuid-Programme}. - -@item @code{sudoers-file} (Vorgabe: @var{%sudoers-specification}) -@cindex sudoers-Datei -Der Inhalt der Datei @file{/etc/sudoers} als ein dateiähnliches Objekt -(@pxref{G-Ausdrücke, @code{local-file} und @code{plain-file}}). - -Diese Datei gibt an, welche Nutzer den Befehl @command{sudo} benutzen -dürfen, was sie damit tun und welche Berechtigungen sie so erhalten -können. Die Vorgabe ist, dass nur der Administratornutzer @code{root} und -Mitglieder der Benutzergruppe @code{wheel} den @code{sudo}-Befehl verwenden -dürfen. - -@end table -@end deftp - -@node Dateisysteme -@section Dateisysteme - -Die Liste der Dateisysteme, die eingebunden werden sollen, steht im -@code{file-systems}-Feld der Betriebssystemdeklaration (@pxref{Das Konfigurationssystem nutzen}). Jedes Dateisystem wird mit der -@code{file-system}-Form deklariert, etwa so: - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -Wie immer müssen manche Felder angegeben werden — die, die im Beispiel oben -stehen —, während andere optional sind. Die Felder werden nun beschrieben. - -@deftp {Datentyp} file-system -Objekte dieses Typs repräsentieren einzubindende Dateisysteme. Sie weisen -folgende Komponenten auf: - -@table @asis -@item @code{type} -Eine Zeichenkette, die den Typ des Dateisystems spezifiziert, -z.B. @code{"ext4"}. - -@item @code{mount-point} -Der Einhängepunkt, d.h. der Pfad, an dem das Dateisystem eingebunden werden -soll. - -@item @code{device} -Hiermit wird die »Quelle« des Dateisystems bezeichnet. Sie kann eines von -drei Dingen sein: die Bezeichnung (»Labels«) eines Dateisystems, die -UUID-Kennung des Dateisystems oder der Name eines @file{/dev}-Knotens. Mit -Bezeichnungen und UUIDs kann man Dateisysteme benennen, ohne den Gerätenamen -festzuschreiben@footnote{Beachten Sie: Obwohl es verführerisch ist, mit -@file{/dev/disk/by-uuid} und ähnlichen Gerätenamen dasselbe Resultat -bekommen zu wollen, raten wir davon ab: Diese speziellen Gerätenamen werden -erst vom udev-Daemon erzeugt und sind, wenn die Geräte eingebunden werden, -vielleicht noch nicht verfügbar.}. - -@findex file-system-label -Dateisystem-Bezeichnungen (»Labels«) werden mit der Prozedur -@code{file-system-label} erzeugt und UUID-Kennungen werden mit @code{uuid} -erzeugt, während Knoten in @file{/dev} mit ihrem Pfad als einfache -Zeichenketten aufgeführt werden. Hier ist ein Beispiel, wie wir ein -Dateisystem anhand seiner Bezeichnung aufführen, wie sie vom Befehl -@command{e2label} angezeigt wird: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "my-home"))) -@end example - -@findex uuid -UUID-Kennungen werden mit der @code{uuid}-Form von ihrer Darstellung als -Zeichenkette (wie sie vom Befehl @command{tune2fs -l} angezeigt wird) -konvertiert@footnote{Die @code{uuid}-Form nimmt 16-Byte-UUIDs entgegen, wie -sie in @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122} definiert -sind. Diese Form der UUID wird unter Anderem von der ext2-Familie von -Dateisystemen verwendet, sie unterscheidet sich jedoch zum Beispiel von den -»UUID« genannten Kennungen, wie man sie bei FAT-Dateisystemen findet.} wie -hier: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -Wenn die Quelle eines Dateisystems ein zugeordnetes Gerät (@pxref{Zugeordnete Geräte}) ist, @emph{muss} sich das @code{device}-Feld auf den zugeordneten -Gerätenamen beziehen — z.B. @file{"/dev/mapper/root-partition"}. Das ist -nötig, damit das System weiß, dass das Einbinden des Dateisystems davon -abhängt, die entsprechende Gerätezuordnung hergestellt zu haben. - -@item @code{flags} (Vorgabe: @code{'()}) -Eine Liste von Symbolen, die Einbinde-Flags (»mount flags«) -bezeichnen. Erkannt werden unter Anderem @code{read-only}, -@code{bind-mount}, @code{no-dev} (Zugang zu besonderen Dateien verweigern), -@code{no-suid} (setuid- und setgid-Bits ignorieren) und @code{no-exec} -(Programmausführungen verweigern). - -@item @code{options} (Vorgabe: @code{#f}) -Entweder @code{#f} oder eine Zeichenkette mit Einbinde-Optionen (»mount -options«). - -@item @code{mount?} (Vorgabe: @code{#t}) -Dieser Wert zeigt an, ob das Dateisystem automatisch eingebunden werden -soll, wenn das System gestartet wird. Ist der Wert @code{#f}, dann erhält -das Dateisystem nur einen Eintrag in der Datei @file{/etc/fstab} (welche vom -@command{mount}-Befehl zum Einbinden gelesen wird), es wird aber nicht -automatisch eingebunden. - -@item @code{needed-for-boot?} (Vorgabe: @code{#f}) -Dieser boolesche Wert gibt an, ob das Dateisystem zum Hochfahren des Systems -notwendig ist. In diesem Fall wird das Dateisystem eingebunden, wenn die -initiale RAM-Disk (initrd) geladen wird. Für zum Beispiel das -Wurzeldateisystem ist dies ohnehin immer der Fall. - -@item @code{check?} (Vorgabe: @code{#t}) -Dieser boolesche Wert sagt aus, ob das Dateisystem vor dem Einbinden auf -Fehler hin geprüft werden soll. - -@item @code{create-mount-point?} (Vorgabe: @code{#f}) -Steht dies auf wahr, wird der Einhängepunkt vor dem Einbinden erstellt, wenn -er noch nicht existiert. - -@item @code{dependencies} (Vorgabe: @code{'()}) -Dies ist eine Liste von @code{<file-system>}- oder -@code{<mapped-device>}-Objekten, die Dateisysteme repräsentieren, die vor -diesem Dateisystem eingebunden oder zugeordnet werden müssen (und nach -diesem ausgehängt oder geschlossen werden müssen). - -Betrachten Sie zum Beispiel eine Hierarchie von Einbindungen: -@file{/sys/fs/cgroup} ist eine Abhängigkeit von @file{/sys/fs/cgroup/cpu} -und @file{/sys/fs/cgroup/memory}. - -Ein weiteres Beispiel ist ein Dateisystem, was von einem zugeordneten Gerät -abhängt, zum Beispiel zur Verschlüsselung einer Partition (@pxref{Zugeordnete Geräte}). -@end table -@end deftp - -Das Modul @code{(gnu system file-systems)} exportiert die folgenden -nützlichen Variablen. - -@defvr {Scheme-Variable} %base-file-systems -Hiermit werden essenzielle Dateisysteme bezeichnet, die für normale Systeme -unverzichtbar sind, wie zum Beispiel @var{%pseudo-terminal-file-system} und -@var{%immutable-store} (siehe unten). Betriebssystemdeklaration sollten auf -jeden Fall mindestens diese enthalten. -@end defvr - -@defvr {Scheme-Variable} %pseudo-terminal-file-system -Das als @file{/dev/pts} einzubindende Dateisystem. Es unterstützt über -@code{openpty} und ähnliche Funktionen erstellte @dfn{Pseudo-Terminals} -(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference -Manual}). Pseudo-Terminals werden von Terminal-Emulatoren wie -@command{xterm} benutzt. -@end defvr - -@defvr {Scheme-Variable} %shared-memory-file-system -Dieses Dateisystem wird als @file{/dev/shm} eingebunden, um Speicher -zwischen Prozessen teilen zu können (@pxref{Memory-mapped I/O, -@code{shm_open},, libc, The GNU C Library Reference Manual}). -@end defvr - -@defvr {Scheme-Variable} %immutable-store -Dieses Dateisystem vollzieht einen »bind mount« des @file{/gnu/store}, um -ihn für alle Nutzer einschließlich des Administratornutzers @code{root} nur -lesbar zu machen, d.h. Schreibrechte zu entziehen. Dadurch kann als -@code{root} ausgeführte Software, oder der Systemadministrator, nicht aus -Versehen den Store modifizieren. - -Der Daemon kann weiterhin in den Store schreiben, indem er ihn selbst mit -Schreibrechten in seinem eigenen »Namensraum« einbindet. -@end defvr - -@defvr {Scheme-Variable} %binary-format-file-system -Das @code{binfmt_misc}-Dateisystem, durch das beliebige Dateitypen als -ausführbare Dateien auf der Anwendungsebene (dem User Space) zugänglich -gemacht werden können. Es setzt voraus, dass das Kernel-Modul -@code{binfmt.ko} geladen wurde. -@end defvr - -@defvr {Scheme-Variable} %fuse-control-file-system -Das @code{fusectl}-Dateisystem, womit »unprivilegierte« Nutzer ohne -besondere Berechtigungen im User Space FUSE-Dateisysteme einbinden und -aushängen können. Dazu muss das Kernel-Modul @code{fuse.ko} geladen sein. -@end defvr - -@node Zugeordnete Geräte -@section Zugeordnete Geräte - -@cindex Gerätezuordnung -@cindex zugeordnete Geräte -Der Linux-Kernel unterstützt das Konzept der @dfn{Gerätezuordnung}: Ein -blockorientiertes Gerät wie eine Festplattenpartition kann einem neuen Gerät -@dfn{zugeordnet} werden, gewöhnlich unter @code{/dev/mapper/}, wobei das -neue Gerät durchlaufende Daten zusätzlicher Verarbeitung unterzogen -werden@footnote{Beachten Sie, dass mit GNU@tie{}Hurd kein Unterschied -zwischen dem Konzept eines »zugeordneten Geräts« und dem eines Dateisystems -besteht: Dort werden bei beiden Ein- und Ausgabeoperationen auf eine Datei -in Operationen auf dessen Hintergrundspeicher @emph{übersetzt}. Hurd -implementiert zugeordnete Geräte genau wie Dateisysteme mit dem generischen -@dfn{Übersetzer}-Mechanismus (@pxref{Translators,,, hurd, The GNU Hurd -Reference Manual}).}. Ein typisches Beispiel ist eine Gerätezuordnung zur -Verschlüsselung: Jeder Schreibzugriff auf das zugeordnete Gerät wird -transparent verschlüsselt und jeder Lesezugriff ebenso entschlüsselt. Guix -erweitert dieses Konzept, indem es darunter jedes Gerät und jede Menge von -Geräten versteht, die auf irgendeine Weise @dfn{umgewandelt} wird, um ein -neues Gerät zu bilden; zum Beispiel entstehen auch RAID-Geräte aus einem -@dfn{Verbund} mehrerer anderer Geräte, wie etwa Festplatten oder Partition -zu einem einzelnen Gerät, das sich wie eine Partition verhält. Ein weiteres -Beispiel, das noch nicht in Guix implementiert wurde, sind »LVM logical -volumes«. - -Zugeordnete Geräte werden mittels einer @code{mapped-device}-Form -deklariert, die wie folgt definiert ist; Beispiele folgen weiter unten. - -@deftp {Datentyp} mapped-device -Objekte dieses Typs repräsentieren Gerätezuordnungen, die gemacht werden, -wenn das System hochfährt. - -@table @code -@item source -Es handelt sich entweder um eine Zeichenkette, die den Namen eines -zuzuordnenden blockorientierten Geräts angibt, wie @code{"/dev/sda3"}, oder -um eine Liste solcher Zeichenketten, sofern mehrere Geräts zu einem neuen -Gerät verbunden werden. - -@item target -Diese Zeichenkette gibt den Namen des neuen zugeordneten Geräts an. Bei -Kernel-Zuordnern, wie verschlüsselten Geräten vom Typ -@code{luks-device-mapping}, wird durch Angabe von @code{"my-partition"} ein -Gerät @code{"/dev/mapper/my-partition"} erzeugt. Bei RAID-Geräten vom Typ -@code{raid-device-mapping} muss der Gerätename als voller Pfad wie zum -Beispiel @code{"/dev/md0"} angegeben werden. - -@item type -Dies muss ein @code{mapped-device-kind}-Objekt sein, das angibt, wie die -Quelle @var{source} dem Ziel @var{target} zugeordnet wird. -@end table -@end deftp - -@defvr {Scheme-Variable} luks-device-mapping -Hiermit wird ein blockorientiertes Gerät mit LUKS verschlüsselt, mit Hilfe -des Befehls @command{cryptsetup} aus dem gleichnamigen Paket. Dazu wird das -Linux-Kernel-Modul @code{dm-crypt} vorausgesetzt. -@end defvr - -@defvr {Scheme-Variable} raid-device-mapping -Dies definiert ein RAID-Gerät, das mit dem Befehl @code{mdadm} aus dem -gleichnamigen Paket als Verbund zusammengestellt wird. Es setzt voraus, dass -das Linux-Kernel-Modul für das entsprechende RAID-Level geladen ist, -z.B. @code{raid456} für RAID-4, RAID-5 oder RAID-6, oder @code{raid10} für -RAID-10. -@end defvr - -@cindex Laufwerksverschlüsselung -@cindex LUKS -Das folgende Beispiel gibt eine Zuordnung von @file{/dev/sda3} auf -@file{/dev/mapper/home} mit LUKS an — dem -@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, -einem Standardmechanismus zur Plattenverschlüsselung. Das Gerät -@file{/dev/mapper/home} kann dann als @code{device} einer -@code{file-system}-Deklaration benutzt werden (@pxref{Dateisysteme}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -Um nicht davon abhängig zu sein, wie Ihre Geräte nummeriert werden, können -Sie auch die LUKS-UUID (@dfn{unique identifier}, d.h. den eindeutigen -Bezeichner) des Quellgeräts auf der Befehlszeile ermitteln: - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -und wie folgt benutzen: - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex Swap-Verschlüsselung -Es ist auch wünschenswert, Swap-Speicher zu verschlüsseln, da in den -Swap-Speicher sensible Daten ausgelagert werden können. Eine Möglichkeit -ist, eine Swap-Datei auf einem mit LUKS-Verschlüsselung zugeordneten -Dateisystem zu verwenden. Dann wird die Swap-Datei verschlüsselt, weil das -ganze Gerät verschlüsselt wird. Ein Beispiel finden Sie im Abschnitt -@xref{Vor der Installation,,Disk Partitioning}. - -Ein RAID-Gerät als Verbund der Partitionen @file{/dev/sda1} und -@file{/dev/sdb1} kann wie folgt deklariert werden: - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -Das Gerät @file{/dev/md0} kann als @code{device} in einer -@code{file-system}-Deklaration dienen (@pxref{Dateisysteme}). Beachten Sie, -dass das RAID-Level dabei nicht angegeben werden muss; es wird während der -initialen Erstellung und Formatierung des RAID-Geräts festgelegt und später -automatisch bestimmt. - - -@node Benutzerkonten -@section Benutzerkonten - -@cindex Benutzer -@cindex Konten -@cindex Benutzerkonten -Benutzerkonten und Gruppen werden allein durch die -@code{operating-system}-Deklaration des Betriebssystems verwaltet. Sie -werden mit den @code{user-account}- und @code{user-group}-Formen angegeben: - -@example -(user-account - (name "alice") - (group "users") - (supplementary-groups '("wheel" ;zur sudo-Nutzung usw. berechtigen - "audio" ;Soundkarte - "video" ;Videogeräte wie Webcams - "cdrom")) ;die gute alte CD-ROM - (comment "Bobs Schwester") - (home-directory "/home/alice")) -@end example - -Beim Hochfahren oder nach Abschluss von @command{guix system reconfigure} -stellt das System sicher, dass nur die in der -@code{operating-system}-Deklaration angegebenen Benutzerkonten und Gruppen -existieren, mit genau den angegebenen Eigenschaften. Daher gehen durch -direkten Aufruf von Befehlen wie @command{useradd} erwirkte Erstellungen -oder Modifikationen von Konten oder Gruppen verloren, sobald rekonfiguriert -oder neugestartet wird. So wird sichergestellt, dass das System genau so -funktioniert, wie es deklariert wurde. - -@deftp {Datentyp} user-account -Objekte dieses Typs repräsentieren Benutzerkonten. Darin können folgende -Komponenten aufgeführt werden: - -@table @asis -@item @code{name} -Der Name des Benutzerkontos. - -@item @code{group} -@cindex Gruppen -Dies ist der Name (als Zeichenkette) oder die Bezeichnung (als Zahl) der -Benutzergruppe, zu der dieses Konto gehört. - -@item @code{supplementary-groups} (Vorgabe: @code{'()}) -Dies kann optional als Liste von Gruppennamen angegeben werden, zu denen -dieses Konto auch gehört. - -@item @code{uid} (Vorgabe: @code{#f}) -Dies ist entweder der Benutzeridentifikator dieses Kontos (seine »User ID«) -als Zahl oder @code{#f}. Bei Letzterem wird vom System automatisch eine Zahl -gewählt, wenn das Benutzerkonto erstellt wird. - -@item @code{comment} (Vorgabe: @code{""}) -Ein Kommentar zu dem Konto, wie etwa der vollständige Name des -Kontoinhabers. - -@item @code{home-directory} -Der Name des Persönlichen Verzeichnisses (»Home«-Verzeichnis) für dieses -Konto. - -@item @code{create-home-directory?} (Vorgabe: @code{#t}) -Zeigt an, ob das Persönliche Verzeichnis für das Konto automatisch erstellt -werden soll, falls es noch nicht existiert. - -@item @code{shell} (Vorgabe: Bash) -Ein G-Ausdruck, der den Dateinamen des Programms angibt, das dem Benutzer -als Shell dienen soll (@pxref{G-Ausdrücke}). - -@item @code{system?} (Vorgabe: @code{#f}) -Dieser boolesche Wert zeigt an, ob das Konto ein »System«-Benutzerkonto -ist. Systemkonten werden manchmal anders behandelt, zum Beispiel werden sie -auf graphischen Anmeldebildschirmen nicht aufgeführt. - -@anchor{user-account-password} -@cindex password, for user accounts -@item @code{password} (Vorgabe: @code{#f}) -Normalerweise lassen Sie dieses Feld auf @code{#f} und initialisieren -Benutzerpasswörter als @code{root} mit dem @command{passwd}-Befehl. Die -Benutzer lässt man ihr eigenes Passwort dann mit @command{passwd} -ändern. Mit @command{passwd} festgelegte Passwörter bleiben natürlich beim -Neustarten und beim Rekonfigurieren erhalten. - -If you @emph{do} want to set an initial password for an account, then this -field must contain the encrypted password, as a string. You can use the -@code{crypt} procedure for this purpose: - -@example -(user-account - (name "charlie") - (home-directory "/home/charlie") - (group "users") - - ;; Specify a SHA-512-hashed initial password. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Anmerkung -The hash of this initial password will be available in a file in -@file{/gnu/store}, readable by all the users, so this method must be used -with care. -@end quotation - -@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for -more information on password encryption, and @ref{Encryption,,, guile, GNU -Guile Reference Manual}, for information on Guile's @code{crypt} procedure. - -@end table -@end deftp - -@cindex Gruppen -Benutzergruppen-Deklarationen sind noch einfacher aufgebaut: - -@example -(user-group (name "students")) -@end example - -@deftp {Datentyp} user-group -Dieser Typ gibt, nun ja, eine Benutzergruppe an. Es gibt darin nur ein paar -Felder: - -@table @asis -@item @code{name} -Der Name der Gruppe. - -@item @code{id} (Vorgabe: @code{#f}) -Der Gruppenbezeichner (eine Zahl). Wird er als @code{#f} angegeben, wird -automatisch eine neue Zahl reserviert, wenn die Gruppe erstellt wird. - -@item @code{system?} (Vorgabe: @code{#f}) -Dieser boolesche Wert gibt an, ob es sich um eine »System«-Gruppe -handelt. Systemgruppen sind solche mit einer kleinen Zahl als Bezeichner. - -@item @code{password} (Vorgabe: @code{#f}) -Wie, Benutzergruppen können ein Passwort haben? Nun ja, anscheinend -schon. Wenn es nicht auf @code{#f} steht, gibt dieses Feld das Passwort der -Gruppe an. - -@end table -@end deftp - -Um Ihnen das Leben zu erleichtern, gibt es eine Variable, worin alle -grundlegenden Benutzergruppen aufgeführt sind, die man erwarten könnte: - -@defvr {Scheme-Variable} %base-groups -Die Liste von Basis-Benutzergruppen, von denen Benutzer und/oder Pakete -erwarten könnten, dass sie auf dem System existieren. Dazu gehören Gruppen -wie »root«, »wheel« und »users«, sowie Gruppen, um den Zugriff auf bestimmte -Geräte einzuschränken, wie »audio«, »disk« und »cdrom«. -@end defvr - -@defvr {Scheme-Variable} %base-user-accounts -Diese Liste enthält Basis-Systembenutzerkonten, von denen Programme erwarten -können, dass sie auf einem GNU/Linux-System existieren, wie das Konto -»nobody«. - -Beachten Sie, dass das Konto »root« für den Administratornutzer nicht -dazugehört. Es ist ein Sonderfall und wird automatisch erzeugt, egal ob es -spezifiziert wurde oder nicht. -@end defvr - -@node Locales -@section Locales - -@cindex Locale -Eine @dfn{Locale} legt die kulturellen Konventionen einer bestimmten Sprache -und Region auf der Welt fest (@pxref{Locales,,, libc, The GNU C Library -Reference Manual}). Jede Locale hat einen Namen, der typischerweise von der -Form @code{@var{Sprache}_@var{Territorium}.@var{Kodierung}} — z.B. benennt -@code{fr_LU.utf8} die Locale für französische Sprache mit den kulturellen -Konventionen aus Luxemburg unter Verwendung der UTF-8-Kodierung. - -@cindex Locale-Definition -Normalerweise werden Sie eine standardmäßig zu verwendende Locale für die -Maschine vorgeben wollen, indem Sie das @code{locale}-Feld der -@code{operating-system}-Deklaration verwenden (@pxref{»operating-system«-Referenz, @code{locale}}). - -Die ausgewählte Locale wird automatisch zu den dem System bekannten -@dfn{Locale-Definitionen} hinzugefügt, falls nötig, und ihre Kodierung wird -aus dem Namen hergeleitet — z.B. wird angenommen, dass @code{bo_CN.utf8} als -Kodierung @code{UTF-8} verwendet. Zusätzliche Locale-Definitionen können im -Feld @code{locale-definitions} vom @code{operating-system} festgelegt werden -— das ist zum Beispiel dann nützlich, wenn die Kodierung nicht aus dem -Locale-Namen hergeleitet werden konnte. Die vorgegebene Menge an -Locale-Definitionen enthält manche weit verbreiteten Locales, aber um Platz -zu sparen, nicht alle verfügbaren Locales. - -Um zum Beispiel die nordfriesische Locale für Deutschland hinzuzufügen, -könnte der Wert des Feldes wie folgt aussehen: - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -Um Platz zu sparen, könnte man auch wollen, dass @code{locale-definitions} -nur die tatsächlich benutzen Locales aufführt, wie etwa: - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -Die kompilierten Locale-Definitionen sind unter -@file{/run/current-system/locale/X.Y} verfügbar, wobei @code{X.Y} die -Version von libc bezeichnet. Dies entspricht dem Pfad, an dem eine von Guix -ausgelieferte GNU@tie{}libc standardmäßig nach Locale-Daten sucht. Er kann -überschrieben werden durch die Umgebungsvariable @code{LOCPATH} -(@pxref{locales-and-locpath, @code{LOCPATH} und Locale-Pakete}). - -Die @code{locale-definition}-Form wird vom Modul @code{(gnu system locale)} -zur Verfügung gestellt. Details folgen unten. - -@deftp {Datentyp} locale-definition -Dies ist der Datentyp einer Locale-Definition. - -@table @asis - -@item @code{name} -Der Name der Locale. Siehe @xref{Locale Names,,, libc, The GNU C Library -Reference Manual} für mehr Informationen zu Locale-Namen. - -@item @code{source} -Der Name der Quelle der Locale. Typischerweise ist das der Teil aus -@code{@var{Sprache}_@var{Territorium}} des Locale-Namens. - -@item @code{charset} (Vorgabe: @code{"UTF-8"}) -Der »Zeichensatz« oder das »Code set«, d.h. die Kodierung dieser Locale, -@uref{http://www.iana.org/assignments/character-sets, wie die IANA sie -definiert}. - -@end table -@end deftp - -@defvr {Scheme-Variable} %default-locale-definitions -Eine Liste häufig benutzter UTF-8-Locales, die als Vorgabewert des -@code{locale-definitions}-Feldes in @code{operating-system}-Deklarationen -benutzt wird. - -@cindex Locale-Name -@cindex Normalisiertes Codeset in Locale-Namen -Diese Locale-Definitionen benutzen das @dfn{normalisierte Codeset} für den -Teil des Namens, der nach dem Punkt steht (@pxref{Using gettextized -software, normalized codeset,, libc, The GNU C Library Reference -Manual}). Zum Beispiel ist @code{uk_UA.utf8} enthalten, dagegen ist etwa -@code{uk_UA.UTF-8} darin @emph{nicht} enthalten. -@end defvr - -@subsection Kompatibilität der Locale-Daten - -@cindex Inkompatibilität, von Locale-Daten -@code{operating-system}-Deklarationen verfügen über ein -@code{locale-libcs}-Feld, um die GNU@tie{}libc-Pakete anzugeben, die zum -Kompilieren von Locale-Deklarationen verwendet werden sollen -(@pxref{»operating-system«-Referenz}). »Was interessiert mich das?«, könnten -Sie fragen. Naja, leider ist das binäre Format der Locale-Daten von einer -libc-Version auf die nächste manchmal nicht miteinander kompatibel. - -@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> -@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. -Zum Beispiel kann ein mit der libc-Version 2.21 gebundenes Programm keine -mit libc 2.22 erzeugten Locale-Daten lesen; schlimmer noch, das Programm -@emph{terminiert} statt einfach die inkompatiblen Locale-Daten zu -ignorieren@footnote{Versionen 2.23 von GNU@tie{}libc und neuere werden -inkompatible Locale-Daten nur mehr überspringen, was schon einmal eine -Verbesserung ist.}. Ähnlich kann ein gegen libc 2.22 gebundenes Programm die -meisten, aber nicht alle, Locale-Daten von libc 2.21 lesen (Daten zu -@code{LC_COLLATE} sind aber zum Beispiel inkompatibel); somit schlagen -Aufrufe von @code{setlocale} vielleicht fehl, aber das Programm läuft -weiter. - -The ``problem'' with Guix is that users have a lot of freedom: They can -choose whether and when to upgrade software in their profiles, and might be -using a libc version different from the one the system administrator used to -build the system-wide locale data. - -Glücklicherweise können »unprivilegierte« Nutzer ohne zusätzliche -Berechtigungen dann zumindest ihre eigenen Locale-Daten installieren und -@var{GUIX_LOCPATH} entsprechend definieren (@pxref{locales-and-locpath, -@code{GUIX_LOCPATH} und Locale-Pakete}). - -Trotzdem ist es am besten, wenn die systemweiten Locale-Daten unter -@file{/run/current-system/locale} für alle libc-Versionen erstellt werden, -die auf dem System noch benutzt werden, damit alle Programme auf sie -zugreifen können — was auf einem Mehrbenutzersystem ganz besonders wichtig -ist. Dazu kann der Administrator des Systems mehrere libc-Pakete im -@code{locale-libcs}-Feld vom @code{operating-system} angeben: - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -Mit diesem Beispiel ergäbe sich ein System, was Locale-Definitionen sowohl -für libc 2.21 als auch die aktuelle Version von libc in -@file{/run/current-system/locale} hat. - - -@node Dienste -@section Dienste - -@cindex Systemdienste -Ein wichtiger Bestandteil des Schreibens einer -@code{operating-system}-Deklaration ist das Auflisten der -@dfn{Systemdienste} und ihrer Konfiguration (@pxref{Das Konfigurationssystem nutzen}). Systemdienste sind typischerweise im Hintergrund laufende -Daemon-Programme, die beim Hochfahren des Systems gestartet werden, oder -andere Aktionen, die zu dieser Zeit durchgeführt werden müssen — wie das -Konfigurieren des Netzwerkzugangs. - -Guix has a broad definition of ``service'' (@pxref{Dienstkompositionen}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd-Dienste}). On a running system, the @command{herd} command allows you to -list the available services, show their status, start and stop them, or do -other specific operations (@pxref{Jump Start,,, shepherd, The GNU Shepherd -Manual}). For example: - -@example -# herd status -@end example - -Dieser Befehl, durchgeführt als @code{root}, listet die momentan definierten -Dienste auf. Der Befehl @command{herd doc} fasst kurz zusammen, was ein -gegebener Dienst ist und welche Aktionen mit ihm assoziiert sind: - -@example -# herd doc nscd -Run libc's name service cache daemon (nscd). - -# herd doc nscd action invalidate -invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups. -@end example - -Die Unterbefehle @command{start}, @command{stop} und @command{restart} haben -die Wirkung, die man erwarten würde. Zum Beispiel kann mit folgenden -Befehlen der nscd-Dienst angehalten und der Xorg-Display-Server neu -gestartet werden: - -@example -# herd stop nscd -Service nscd has been stopped. -# herd restart xorg-server -Service xorg-server has been stopped. -Service xorg-server has been started. -@end example - -Die folgenden Abschnitte dokumentieren die verfügbaren Dienste, die in einer -@code{operating-system}-Deklaration benutzt werden können, angefangen mit -den Diensten im Kern des Systems (»core services«) - -@menu -* Basisdienste:: Essenzielle Systemdienste. -* Geplante Auftragsausführung:: Der mcron-Dienst. -* Log-Rotation:: Der rottlog-Dienst. -* Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc. -* X Window:: Grafische Anzeige. -* Druckdienste:: Unterstützung für lokale und entfernte - Drucker. -* Desktop-Dienste:: D-Bus- und Desktop-Dienste. -* Tondienste:: Dienste für ALSA und Pulseaudio. -* Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc. -* Mail-Dienste:: IMAP, POP3, SMTP und so weiter. -* Kurznachrichtendienste:: Dienste für Kurznachrichten. -* Telefondienste:: Telefoniedienste. -* Überwachungsdienste:: Dienste zur Systemüberwachung. -* Kerberos-Dienste:: Kerberos-Dienste. -* Web-Dienste:: Web-Server. -* Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt. -* DNS-Dienste:: DNS-Daemons. -* VPN-Dienste:: VPN-Daemons. -* Network File System:: Dienste mit Bezug zum Netzwerkdateisystem. -* Kontinuierliche Integration:: Der Cuirass-Dienst. -* Dienste zur Stromverbrauchsverwaltung:: Den Akku schonen. -* Audio-Dienste:: Der MPD. -* Virtualisierungsdienste:: Dienste für virtuelle Maschinen. -* Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten. -* Spieldienste:: Spielserver. -* Verschiedene Dienste:: Andere Dienste. -@end menu - -@node Basisdienste -@subsection Basisdienste - -Das Modul @code{(gnu services base)} stellt Definitionen für Basis-Dienste -zur Verfügung, von denen man erwartet, dass das System sie anbietet. Im -Folgenden sind die von diesem Modul exportierten Dienste aufgeführt. - -@defvr {Scheme-Variable} %base-services -Diese Variable enthält eine Liste von Basis-Diensten, die man auf einem -System vorzufinden erwartet (siehe @pxref{Diensttypen und Dienste} für -weitere Informationen zu Dienstobjekten): ein Anmeldungsdienst (mingetty) -auf jeder Konsole (jedem »tty«), syslogd, den Name Service Cache Daemon -(nscd) von libc, die udev-Geräteverwaltung und weitere. - -Dies ist der Vorgabewert für das @code{services}-Feld für die Dienste von -@code{operating-system}-Deklarationen. Normalerweise werden Sie, wenn Sie -ein Betriebssystem anpassen, Dienste an die @var{%base-services}-Liste -anhängen, wie hier gezeigt: - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Scheme-Variable} special-files-service-type -Dieser Dienst richtet »besondere Dateien« wie @file{/bin/sh} ein; eine -Instanz des Dienstes ist Teil der @code{%base-services}. - -Der mit @code{special-files-service-type}-Diensten assoziierte Wert muss -eine Liste von Tupeln sein, deren erstes Element eine »besondere Datei« und -deren zweites Element deren Zielpfad ist. Der Vorgabewert ist: - -@cindex @file{/bin/sh} -@cindex @file{sh}, in @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example - -@cindex @file{/usr/bin/env} -@cindex @file{env}, in @file{/usr/bin} -Wenn Sie zum Beispiel auch @code{/usr/bin/env} zu Ihrem System hinzufügen -möchten, können Sie den Wert ändern auf: - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Da dieser Dienst Teil der @code{%base-services} ist, können Sie -@code{modify-services} benutzen, um die Liste besonderer Dateien abzuändern -(@pxref{Service-Referenz, @code{modify-services}}). Die leichte -Alternative, um eine besondere Datei hinzuzufügen, ist über die Prozedur -@code{extra-special-file} (siehe unten). -@end defvr - -@deffn {Scheme-Prozedur} extra-special-file @var{Datei} @var{Ziel} -Das @var{Ziel} als »besondere Datei« @var{Datei} verwenden. - -Beispielsweise können Sie die folgenden Zeilen in das @code{services}-Feld -Ihrer Betriebssystemdeklaration einfügen für eine symbolische Verknüpfung -@file{/usr/bin/env}: - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Scheme-Prozedur} host-name-service @var{Name} -Liefert einen Dienst, der den Rechnernamen (den »Host«-Namen des Rechners) -als @var{Name} festlegt. -@end deffn - -@deffn {Scheme-Prozedur} login-service @var{Konfiguration} -Liefert einen Dienst, der die Benutzeranmeldung möglich macht. Dazu -verwendet er die angegebene @var{Konfiguration}, ein -@code{<login-configuration>}-Objekt, das unter Anderem die beim Anmelden -angezeigte Mitteilung des Tages (englisch »Message of the Day«) festlegt. -@end deffn - -@deftp {Datentyp} login-configuration -Dies ist der Datentyp, der die Anmeldekonfiguration repräsentiert. - -@table @asis - -@item @code{motd} -@cindex Message of the Day -Ein dateiartiges Objekt, das die »Message of the Day« enthält. - -@item @code{allow-empty-passwords?} (Vorgabe: @code{#t}) -Leere Passwörter standardmäßig zulassen, damit sich neue Anwender anmelden -können, direkt nachdem das Benutzerkonto »root« für den Administrator -angelegt wurde. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} mingetty-service @var{Konfiguration} -Liefert einen Dienst, der mingetty nach den Vorgaben der @var{Konfiguration} -ausführt, einem @code{<mingetty-configuration>}-Objekt, das unter Anderem -die Konsole (das »tty«) festlegt, auf der mingetty laufen soll. -@end deffn - -@deftp {Datentyp} mingetty-configuration -Dieser Datentyp repräsentiert die Konfiguration von Mingetty, der -vorgegebenen Implementierung zur Anmeldung auf einer virtuellen Konsole. - -@table @asis - -@item @code{tty} -Der Name der Konsole, auf der diese Mingetty-Instanz läuft — -z.B. @code{"tty1"}. - -@item @code{auto-login} (Vorgabe: @code{#f}) -Steht dieses Feld auf wahr, muss es eine Zeichenkette sein, die den -Benutzernamen angibt, als der man vom System automatisch angemeldet -wird. Ist es @code{#f}, so muss zur Anmeldung ein Benutzername und ein -Passwort eingegeben werden. - -@item @code{login-program} (Vorgabe: @code{#f}) -Dies muss entweder @code{#f} sein, dann wird das voreingestellte -Anmeldeprogramm benutzt (@command{login} aus dem Shadow-Werkzeugsatz) oder -der Name des Anmeldeprogramms als G-Ausdruck. - -@item @code{login-pause?} (Vorgabe: @code{#f}) -Ist es auf @code{#t} gesetzt, sorgt es in Verbindung mit @var{auto-login} -dafür, dass der Benutzer eine Taste drücken muss, ehe eine Anmelde-Shell -gestartet wird. - -@item @code{mingetty} (Vorgabe: @var{mingetty}) -Welches Mingetty-Paket benutzt werden soll. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} agetty-service @var{Konfiguration} -Liefert einen Dienst, um agetty entsprechend der @var{Konfiguration} -auszuführen, welche ein @code{<agetty-configuration>}-Objekt sein muss, das -unter Anderem festlegt, auf welchem tty es laufen soll. -@end deffn - -@deftp {Datentyp} agetty-configuration -Dies ist der Datentyp, der die Konfiguration von agetty repräsentiert, was -Anmeldungen auf einer virtuellen oder seriellen Konsole implementiert. Siehe -die Handbuchseite @code{agetty(8)} für mehr Informationen. - -@table @asis - -@item @code{tty} -Der Name der Konsole, auf der diese Instanz von agetty läuft, als -Zeichenkette — z.B. @code{"ttyS0"}. Dieses Argument ist optional, sein -Vorgabewert ist eine vernünftige Wahl unter den seriellen Schnittstellen, -auf deren Benutzung der Linux-Kernel eingestellt ist. - -Hierzu wird, wenn in der Kernel-Befehlszeile ein Wert für eine Option namens -@code{agetty.tty} festgelegt wurde, der Gerätename daraus für agetty -extrahiert und benutzt. - -Andernfalls wird agetty, falls auf der Kernel-Befehlszeile eine Option -@code{console} mit einem tty vorkommt, den daraus extrahierten Gerätenamen -der seriellen Schnittstelle benutzen. - -In both cases, agetty will leave the other serial device settings (baud rate -etc.)@: alone---in the hope that Linux pinned them to the correct values. - -@item @code{baud-rate} (Vorgabe: @code{#f}) -Eine Zeichenkette, die aus einer kommagetrennten Liste von einer oder -mehreren Baud-Raten besteht, absteigend sortiert. - -@item @code{term} (Vorgabe: @code{#f}) -Eine Zeichenkette, die den Wert enthält, der für die Umgebungsvariable -@code{TERM} benutzt werden soll. - -@item @code{eight-bits?} (Vorgabe: @code{#f}) -Steht dies auf @code{#t}, wird angenommen, dass das tty 8-Bit-korrekt ist, -so dass die Paritätserkennung abgeschaltet wird. - -@item @code{auto-login} (Vorgabe: @code{#f}) -Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der -angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder -Passwort zu fragen. - -@item @code{no-reset?} (Vorgabe: @code{#f}) -Steht dies auf @code{#t}, werden die Cflags des Terminals (d.h. dessen -Steuermodi) nicht zurückgesetzt. - -@item @code{host} (Vorgabe: @code{#f}) -Dies akzeptiert eine Zeichenkette mit dem einzutragenden -Anmeldungs-Rechnernamen "login_host", der in die Datei @file{/var/run/utmpx} -geschrieben wird. - -@item @code{remote?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird in Verbindung mit @var{host} eine -Befehlszeilenoption @code{-r} für einen falschen Rechnernamen (»Fakehost«) -in der Befehlszeile des mit @var{login-program} angegebenen Anmeldeprogramms -übergeben. - -@item @code{flow-control?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird Hardware-Flusssteuerung (RTS/CTS) -aktiviert. - -@item @code{no-issue?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird der Inhalt der Datei @file{/etc/issue} -@emph{nicht} angezeigt, bevor die Anmeldeaufforderung zu sehen ist. - -@item @code{init-string} (Vorgabe: @code{#f}) -Dies akzeptiert eine Zeichenkette, die zum tty oder zum Modem zuerst vor -allem Anderen gesendet wird. Es kann benutzt werden, um ein Modem zu -initialisieren. - -@item @code{no-clear?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird agetty den Bildschirm @emph{nicht} -löschen, bevor es die Anmeldeaufforderung anzeigt. - -@item @code{login-program} (Vorgabe: (file-append shadow "/bin/login")) -Hier muss entweder ein G-Ausdruck mit dem Namen eines Anmeldeprogramms -übergeben werden, oder dieses Feld wird nicht gesetzt, so dass als -Vorgabewert das Programm @command{login} aus dem Shadow-Werkzeugsatz -verwendet wird. - -@item @code{local-line} (Vorgabe: @code{#f}) -Steuert den Leitungsschalter CLOCAL. Hierfür wird eines von drei Symbolen -als Argument akzeptiert, @code{'auto}, @code{'always} oder -@code{'never}. Für @code{#f} wählt agetty als Vorgabewert @code{'auto}. - -@item @code{extract-baud?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, so wird agetty angewiesen, die Baud-Rate aus -den Statusmeldungen mancher Arten von Modem abzulesen. - -@item @code{skip-login?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird der Benutzer nicht aufgefordert, einen -Anmeldenamen einzugeben. Dies kann zusammen mit dem @var{login-program}-Feld -benutzt werden, um nicht standardkonforme Anmeldesysteme zu benutzen. - -@item @code{no-newline?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird @emph{kein} Zeilenumbruch ausgegeben, -bevor die Datei @file{/etc/issue} ausgegeben wird. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette mit den Befehlszeilenoptionen für -das Anmeldeprogramm. Beachten Sie, dass bei einem selbst gewählten -@var{login-program} ein böswilliger Nutzer versuchen könnte, als -Anmeldenamen etwas mit eingebetteten Befehlszeilenoptionen anzugeben, die -vom Anmeldeprogramm interpretiert werden könnten. - -@item @code{login-pause} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird auf das Drücken einer beliebigen Taste -gewartet, bevor die Anmeldeaufforderung angezeigt wird. Hiermit kann in -Verbindung mit @var{auto-login} weniger Speicher verbraucht werden, indem -man Shells erst erzeugt, wenn sie benötigt werden. - -@item @code{chroot} (Vorgabe: @code{#f}) -Wechselt die Wurzel des Dateisystems auf das angegebene Verzeichnis. Dieses -Feld akzeptiert einen Verzeichnispfad als Zeichenkette. - -@item @code{hangup?} (Vorgabe: @code{#f}) -Mit dem Linux-Systemaufruf @code{vhangup} auf dem angegebenen Terminal -virtuell auflegen. - -@item @code{keep-baud?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird versucht, die bestehende Baud-Rate -beizubehalten. Die Baud-Raten aus dem Feld @var{baud-rate} werden benutzt, -wenn agetty ein @key{BREAK}-Zeichen empfängt. - -@item @code{timeout} (Vorgabe: @code{#f}) -Ist dies auf einen ganzzahligen Wert gesetzt, wird terminiert, falls kein -Benutzername innerhalb von @var{timeout} Sekunden eingelesen werden konnte. - -@item @code{detect-case?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird Unterstützung für die Erkennung von -Terminals aktiviert, die nur Großschreibung beherrschen. Mit dieser -Einstellung wird, wenn ein Anmeldename nur aus Großbuchstaben besteht, -dieser als Anzeichen dafür aufgefasst, dass das Terminal nur Großbuchstaben -beherrscht, und einige Umwandlungen von Groß- in Kleinbuchstaben -aktiviert. Beachten Sie, dass dabei @emph{keine} Unicode-Zeichen unterstützt -werden. - -@item @code{wait-cr?} (Vorgabe: @code{#f}) -Wenn dies auf @code{#t} gesetzt ist, wird gewartet, bis der Benutzer oder -das Modem einen Wagenrücklauf (»Carriage Return«) oder einen Zeilenvorschub -(»Linefeed«) absendet, ehe @file{/etc/issue} oder eine Anmeldeaufforderung -angezeigt wird. Dies wird typischerweise zusammen mit dem Feld -@var{init-string} benutzt. - -@item @code{no-hints?} (Vorgabe: @code{#f}) -Ist es auf @code{#t} gesetzt, werden @emph{keine} Hinweise zu den -Feststelltasten Num-Taste, Umschaltsperre (»Caps Lock«) und Rollen-Taste -(»Scroll Lock«) angezeigt. - -@item @code{no-hostname?} (Vorgabe: @code{#f}) -Das vorgegebene Verhalten ist, den Rechnernamen auszugeben. Ist dieses Feld -auf @code{#t} gesetzt, wird überhaupt kein Rechnername angezeigt. - -@item @code{long-hostname?} (Vorgabe: @code{#f}) -Das vorgegebene Verhalten ist, den Rechnernamen nur bis zu seinem ersten -Punkt anzuzeigen. Ist dieses Feld auf @code{#t} gesetzt, wird der -vollständige Rechnername (der »Fully Qualified Hostname«), wie ihn -@code{gethostname} oder @code{getaddrinfo} liefern, angezeigt. - -@item @code{erase-characters} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette aus Zeichen, die auch als Rücktaste -(zum Löschen) interpretiert werden sollen, wenn der Benutzer seinen -Anmeldenamen eintippt. - -@item @code{kill-characters} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette aus Zeichen, deren Eingabe als -»ignoriere alle vorherigen Zeichen« interpretiert werden soll (auch -»kill«-Zeichen genannt), wenn der Benutzer seinen Anmeldenamen eintippt. - -@item @code{chdir} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette, die einen Verzeichnispfad angibt, -zu dem vor der Anmeldung gewechselt wird. - -@item @code{delay} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine ganze Zahl mit der Anzahl Sekunden, die gewartet -werden soll, bis ein tty geöffnet und die Anmeldeaufforderung angezeigt -wird. - -@item @code{nice} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine ganze Zahl mit dem »nice«-Wert, mit dem das -Anmeldeprogramm ausgeführt werden soll. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Dieses Feld ist ein »Notausstieg«, mit dem Nutzer beliebige -Befehlszeilenoptionen direkt an @command{agetty} übergeben können. Diese -müssen hier als eine Liste von Zeichenketten angegeben werden. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} kmscon-service-type @var{Konfiguration} -Liefert einen Dienst, um -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} entsprechend -der @var{Konfiguration} auszuführen. Diese ist ein -@code{<kmscon-configuration>}-Objekt, das unter Anderem angibt, auf welchem -tty es ausgeführt werden soll. -@end deffn - -@deftp {Datentyp} kmscon-configuration -Dieser Datentyp repräsentiert die Konfiguration von Kmscon, die das Anmelden -auf virtuellen Konsolen ermöglicht. - -@table @asis - -@item @code{virtual-terminal} -Der Name der Konsole, auf der diese Kmscon läuft — z.B. @code{"tty1"}. - -@item @code{login-program} (Vorgabe: @code{#~(string-append #$shadow "/bin/login")}) -Ein G-Ausdruck, der den Namen des Anmeldeprogramms angibt. Als Vorgabe wird -das Anmeldeprogramm @command{login} aus dem Shadow-Werkzeugsatz verwendet. - -@item @code{login-arguments} (Vorgabe: @code{'("-p")}) -Eine Liste der Argumente, die an @command{login} übergeben werden sollen. - -@item @code{auto-login} (Vorgabe: @code{#f}) -Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der -angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder -Passwort zu fragen. - -@item @code{hardware-acceleration?} (Vorgabe: #f) -Ob Hardware-Beschleunigung verwendet werden soll. - -@item @code{kmscon} (Vorgabe: @var{kmscon}) -Das Kmscon-Paket, das benutzt werden soll. - -@end table -@end deftp - -@cindex Name Service Cache Daemon -@cindex nscd -@deffn {Scheme-Prozedur} nscd-service [@var{Konfiguration}] [#:glibc glibc] @ - [#:name-services '()] Liefert einen Dienst, der den Name Service Cache -Daemon (nscd) von libc mit der angegebenen @var{Konfiguration} ausführt — -diese muss ein @code{<nscd-configuration>}-Objekt sein. Siehe @xref{Name Service Switch} für ein Beispiel. - -Der Einfachheit halber bietet der Shepherd-Dienst für nscd die folgenden -Aktionen an: - -@table @code -@item invalidate -@cindex Zwischenspeicher ungültig machen, nscd -@cindex nscd, Ungültigmachen des Zwischenspeichers -Dies macht den angegebenen Zwischenspeicher ungültig. Wenn Sie zum Beispiel: - -@example -herd invalidate nscd hosts -@end example - -@noindent -ausführen, wird der Zwischenspeicher für die Auflösung von Rechnernamen (von -»Host«-Namen) des nscd ungültig. - -@item statistics -Wenn Sie @command{herd statistics nscd} ausführen, werden Ihnen -Informationen angezeigt, welche Ihnen Informationen über den nscd-Zustand -und die Zwischenspeicher angezeigt. -@end table - -@end deffn - -@defvr {Scheme-Variable} %nscd-default-configuration -Dies ist der vorgegebene Wert für die @code{<nscd-configuration>} (siehe -unten), die @code{nscd-service} benutzt. Die Konfiguration benutzt die -Zwischenspeicher, die in @var{%nscd-default-caches} definiert sind; siehe -unten. -@end defvr - -@deftp {Datentyp} nscd-configuration -Dieser Datentyp repräsentiert die Konfiguration des Name Service Caching -Daemon (kurz »nscd«). - -@table @asis - -@item @code{name-services} (Vorgabe: @code{'()}) -Liste von Paketen, die @dfn{Namensdienste} bezeichnen, die für den nscd -sichtbar sein müssen, z.B. @code{(list @var{nss-mdns})}. - -@item @code{glibc} (Vorgabe: @var{glibc}) -Ein Paket-Objekt, das die GNU-C-Bibliothek angibt, woraus der -@command{nscd}-Befehl genommen werden soll. - -@item @code{log-file} (Vorgabe: @code{"/var/log/nscd.log"}) -Name der nscd-Protokolldatei. Hierhin werden Ausgaben zur Fehlersuche -geschrieben, falls @code{debug-level} echt positiv ist. - -@item @code{debug-level} (Vorgabe: @code{0}) -Eine ganze Zahl, die den Detailgrad der Ausgabe zur Fehlersuche -angibt. Größere Zahlen bewirken eine ausführlichere Ausgabe. - -@item @code{caches} (Vorgabe: @var{%nscd-default-caches}) -Liste der @code{<nscd-cache>}-Objekte, die repräsentieren, was alles -zwischengespeichert werden soll; siehe unten. - -@end table -@end deftp - -@deftp {Datentyp} nscd-cache -Ein Datentyp, der eine Zwischenspeicher-Datenbank von nscd mitsamt ihren -Parametern definiert. - -@table @asis - -@item @code{Datenbank} -Dies ist ein Symbol, was den Namen der Datenbank repräsentiert, die -zwischengespeichert werden soll. Gültige Werte sind @code{passwd}, -@code{group}, @code{hosts} und @code{services}, womit jeweils die -entsprechende NSS-Datenbank bezeichnet wird (@pxref{NSS Basics,,, libc, The -GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (Vorgabe: @code{20}) -Eine Zahl, die für die Anzahl an Sekunden steht, die ein erfolgreiches -(positives) oder erfolgloses (negatives) Nachschlageresultat im -Zwischenspeicher verbleibt. - -@item @code{check-files?} (Vorgabe: @code{#t}) -Ob auf Änderungen an den der @var{database} entsprechenden Dateien reagiert -werden soll. - -Wenn @var{database} zum Beispiel @code{hosts} ist, wird, wenn dieses Feld -gesetzt ist, nscd Änderungen an @file{/etc/hosts} beobachten und -berücksichtigen. - -@item @code{persistent?} (Vorgabe: @code{#t}) -Ob der Zwischenspeicher dauerhaft auf der Platte gespeichert werden soll. - -@item @code{shared?} (Vorgabe: @code{#t}) -Ob der Zwischenspeicher zwischen den Nutzern geteilt werden soll. - -@item @code{max-database-size} (Vorgabe: 32@tie{}MiB) -Die Maximalgröße des Datenbank-Zwischenspeichers in Bytes. - -@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert -@c settings, so leave them out. - -@end table -@end deftp - -@defvr {Scheme-Variable} %nscd-default-caches -Liste von @code{<nscd-cache>}-Objekten, die von der vorgegebenen -@code{nscd-configuration} benutzt werden (siehe oben). - -Damit wird dauerhaftes und aggressives Zwischenspeichern beim Nachschlagen -von Dienst- und Rechnernamen (»Host«-Namen) aktiviert. Letzteres verbessert -die Leistungsfähigkeit beim Nachschlagen von Rechnernamen, sorgt für mehr -Widerstandsfähigkeit gegenüber unverlässlichen Namens-Servern und bietet -außerdem einen besseren Schutz der Privatsphäre — oftmals befindet sich das -Ergebnis einer Anfrage nach einem Rechnernamen bereits im lokalen -Zwischenspeicher und externe Namens-Server müssen nicht miteinbezogen -werden. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex Protokollierung -@deftp {Datentyp} syslog-configuration -Dieser Datentyp repräsentiert die Konfiguration des syslog-Daemons. - -@table @asis -@item @code{syslogd} (Vorgabe: @code{#~(string-append #$inetutils "/libexec/syslogd")}) -Welcher Syslog-Daemon benutzt werden soll. - -@item @code{config-file} (Vorgabe: @code{%default-syslog.conf}) -Die zu benutzende syslog-Konfigurationsdatei. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Scheme-Prozedur} syslog-service @var{Konfiguration} -Liefert einen Dienst, der einen syslog-Daemon entsprechend der -@var{Konfiguration} ausführt. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, für weitere -Informationen über die Syntax der Konfiguration. -@end deffn - -@defvr {Scheme-Variable} guix-service-type -Dies ist der Typ für den Dienst, der den Erstellungs-Daemon -@command{guix-daemon} ausführt (@pxref{Aufruf des guix-daemon}). Als Wert muss -ein @code{guix-configuration}-Verbundsobjekt verwendet werden, wie unten -beschrieben. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Datentyp} guix-configuration -Dieser Datentyp repräsentiert die Konfiguration des Erstellungs-Daemons von -Guix. Siehe @xref{Aufruf des guix-daemon} für weitere Informationen. - -@table @asis -@item @code{guix} (Vorgabe: @var{guix}) -Das zu verwendende Guix-Paket. - -@item @code{build-group} (Vorgabe: @code{"guixbuild"}) -Der Name der Gruppe, zu der die Erstellungs-Benutzerkonten gehören. - -@item @code{build-accounts} (Vorgabe: @code{10}) -Die Anzahl zu erzeugender Erstellungs-Benutzerkonten. - -@item @code{authorize-key?} (Vorgabe: @code{#t}) -@cindex Substitute, deren Autorisierung -Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substitute}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (Vorgabe: @var{%default-authorized-guix-keys}) -The list of authorized key files for archive imports, as a list of -string-valued gexps (@pxref{Aufruf von guix archive}). By default, it -contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitute}). - -@item @code{use-substitutes?} (Vorgabe: @code{#t}) -Ob Substitute benutzt werden sollen. - -@item @code{substitute-urls} (Vorgabe: @var{%default-substitute-urls}) -Die Liste der URLs, auf denen nach Substituten gesucht wird, wenn nicht -anders angegeben. - -@item @code{max-silent-time} (Vorgabe: @code{0}) -@itemx @code{timeout} (Vorgabe: @code{0}) -Die Anzahl an Sekunden, die jeweils nichts in die Ausgabe geschrieben werden -darf bzw. die es insgesamt dauern darf, bis ein Erstellungsprozess -abgebrochen wird. Beim Wert null wird nie abgebrochen. - -@item @code{log-compression} (Vorgabe: @code{'bzip2}) -Die für Erstellungsprotokolle zu benutzende Kompressionsmethode — entweder -@code{gzip}, @code{bzip2} oder @code{none}. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Eine Liste zusätzlicher Befehlszeilenoptionen zu @command{guix-daemon}. - -@item @code{log-file} (Vorgabe: @code{"/var/log/guix-daemon.log"}) -Die Datei, in die die Standardausgabe und die Standardfehlerausgabe von -@command{guix-daemon} geschrieben werden. - -@item @code{http-proxy} (Vorgabe: @code{#f}) -Der für das Herunterladen von Ableitungen mit fester Ausgabe und von -Substituten zu verwendende HTTP-Proxy. - -@item @code{tmpdir} (Vorgabe: @code{#f}) -Ein Verzeichnispfad, der angibt, wo @command{guix-daemon} seine Erstellungen -durchführt. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Führt @var{udev} aus, was zur Laufzeit Gerätedateien ins Verzeichnis -@file{/dev} einfügt. udev-Regeln können über die @var{rules}-Variable als -eine Liste von Dateien übergeben werden. Die Prozeduren @var{udev-rule} und -@var{file->udev-rule} aus @code{(gnu services base)} vereinfachen die -Erstellung einer solchen Regeldatei. -@end deffn - -@deffn {Scheme-Prozedur} udev-rule [@var{Dateiname} @var{Inhalt}] -Liefert eine udev-Regeldatei mit dem angegebenen @var{Dateiname}n, in der -die vom Literal @var{Inhalt} definierten Regeln stehen. - -Im folgenden Beispiel wird eine Regel für ein USB-Gerät definiert und in der -Datei @file{90-usb-ding.rules} gespeichert. Mit der Regel wird ein Skript -ausgeführt, sobald ein USB-Gerät mit der angegebenen Produktkennung erkannt -wird. - -@example -(define %beispiel-udev-rule - (udev-rule - "90-usb-ding.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Beispiel\", " - "RUN+=\"/pfad/zum/skript\""))) -@end example - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@end deffn - -Hier zeigen wir, wie man den vorgegebenen @var{udev-service} um sie -erweitern kann. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %beispiel-udev-rule)))))))) -@end example - -@deffn {Scheme-Prozedur} file->udev-rule [@var{Dateiname} @var{Datei}] -Liefert eine udev-Datei mit dem angegebenen @var{Dateiname}n, in der alle in -der @var{Datei}, einem dateiartigen Objekt, definierten Regeln stehen. - -Folgendes Beispiel stellt dar, wie wir eine bestehende Regeldatei verwenden -können. - -@example -(use-modules (guix download) ;für url-fetch - (guix packages) ;für origin - ;; @dots{}) - -(define %android-udev-rules - (file->udev-rule - "51-android-udev.rules" - (let ((version "20170910")) - (origin - (method url-fetch) - (uri (string-append "https://raw.githubusercontent.com/M0Rf30/" - "android-udev-rules/" version "/51-android.rules")) - (sha256 - (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) -@end example -@end deffn - -Zusätzlich können Guix-Paketdefinitionen unter den @var{rules} aufgeführt -werden, um die udev-Regeln um diejenigen Definitionen zu ergänzen, die im -Unterverzeichnis @file{lib/udev/rules.d} des jeweiligen Pakets aufgeführt -sind. Statt des bisherigen Beispiels zu @var{file->udev-rule} hätten wir -also auch das Paket @var{android-udev-rules} benutzen können, das in Guix im -Modul @code{(gnu packages android)} vorhanden ist. - -Das folgende Beispiel zeit, wie dieses Paket @var{android-udev-rules} -benutzt werden kann, damit das »Android-Tool« @command{adb} Geräte erkennen -kann, ohne dafür Administratorrechte vorauszusetzen. Man sieht hier auch, -wie die Benutzergruppe @code{adbusers} erstellt werden kann, die existieren -muss, damit die im Paket @var{android-udev-rules} definierten Regeln richtig -funktionieren. Um so eine Benutzergruppe zu erzeugen, müssen wir sie sowohl -unter den @var{supplementary-groups} unserer @var{user-account}-Deklaration -aufführen, als auch sie im @var{groups}-Feld des -@var{operating-system}-Verbundsobjekts aufführen. - -@example -(use-modules (gnu packages android) ;für android-udev-rules - (gnu system shadow) ;für user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;für adb - "wheel" "netdev" "audio" "video")) - ;; @dots{}))) - - (groups (cons (user-group (system? #t) (name "adbusers")) - %base-groups)) - - ;; @dots{} - - (services - (modify-services %desktop-services - (udev-service-type - config => - (udev-configuration (inherit config) - (rules (cons android-udev-rules - (udev-configuration-rules config)))))))) -@end example - -@defvr {Scheme-Variable} urandom-seed-service-type -Etwas Entropie in der Datei @var{%random-seed-file} aufsparen, die als -Startwert (als sogenannter »Seed«) für @file{/dev/urandom} dienen kann, -nachdem das System neu gestartet wurde. Es wird auch versucht, -@file{/dev/urandom} beim Hochfahren mit Werten aus @file{/dev/hwrng} zu -starten, falls @file{/dev/hwrng} existiert und lesbar ist. -@end defvr - -@defvr {Scheme-Variable} %random-seed-file -Der Name der Datei, in der einige zufällige Bytes vom -@var{urandom-seed-service} abgespeichert werden, um sie nach einem Neustart -von dort als Startwert für @file{/dev/urandom} auslesen zu können. Als -Vorgabe wird @file{/var/lib/random-seed} verwendet. -@end defvr - -@cindex Keymap -@cindex Tastatur -@deffn {Scheme-Prozedur} console-keymap-service @var{Dateien} ... -@cindex Tastaturbelegung -Liefert einen Dienst, um Tastenzuordnungen (»Keymaps«) für die Konsole aus -den @var{Dateien} laden zu können. Dazu wird der Befehl @command{loadkeys} -aufgerufen. Wahrscheinlich möchten Sie irgendeine vorgefertigte Keymap -laden, etwa so: - -@example -(console-keymap-service "dvorak") -@end example - -Oder um zum Beispiel eine schwedische Tastaturbelegung zu bekommen, könnten -Sie die folgenden Keymaps kombinieren müssen: -@example -(console-keymap-service "se-lat6" "se-fi-lat6") -@end example - -Sie können alternativ auch den oder die vollständigen Dateinamen Ihrer -Keymap(s) angeben. Siehe @code{man loadkeys} für Details. - -@end deffn - -@cindex Maus -@cindex gpm -@defvr {Scheme-Variable} gpm-service-type -Dieser Typ wird für den Dienst verwendet, der GPM ausführt, den -»@dfn{General-Purpose Mouse Daemon}«, welcher zur Linux-Konsole -Mausunterstützung hinzufügt. GPM ermöglicht es seinen Benutzern, auch in der -Konsole die Maus zu benutzen und damit etwa Text auszuwählen, zu kopieren -und einzufügen. - -Der Wert für Dienste dieses Typs muss eine @code{gpm-configuration} sein -(siehe unten). Dieser Dienst gehört @emph{nicht} zu den -@var{%base-services}. -@end defvr - -@deftp {Datentyp} gpm-configuration -Repräsentiert die Konfiguration von GPM. - -@table @asis -@item @code{options} (Vorgabe: @code{%default-gpm-options}) -Befehlszeilenoptionen, die an @command{gpm} übergeben werden. Die -vorgegebenen Optionen weisen @command{gpm} an, auf Maus-Ereignisse auf der -Datei @file{/dev/input/mice} zu lauschen. Siehe @xref{Command Line,,, gpm, -gpm manual} für weitere Informationen. - -@item @code{gpm} (Vorgabe: @code{gpm}) -Das GPM-Paket, was benutzt werden soll. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Scheme-Variable} guix-publish-service-type -Dies ist der Diensttyp für @command{guix publish} (@pxref{Aufruf von guix publish}). Sein Wert muss ein @code{guix-publish-configuration}-Objekt sein, -wie im Folgenden beschrieben. - -Hierbei wird angenommen, dass @file{/etc/guix} bereits ein mit @command{guix -archive --generate-key} erzeugtes Schlüsselpaar zum Signieren enthält -(@pxref{Aufruf von guix archive}). Falls nicht, wird der Dienst beim Starten -fehlschlagen. -@end deffn - -@deftp {Datentyp} guix-publish-configuration -Der Datentyp, der die Konfiguration des »@code{guix publish}«-Dienstes -repräsentiert. - -@table @asis -@item @code{guix} (Vorgabe: @code{guix}) -Das zu verwendende Guix-Paket. - -@item @code{port} (Vorgabe: @code{80}) -Der TCP-Port, auf dem auf Verbindungen gelauscht werden soll. - -@item @code{host} (Vorgabe: @code{"localhost"}) -Unter welcher Rechneradresse (welchem »Host«, also welcher -Netzwerkschnittstelle) auf Verbindungen gelauscht wird. Benutzen Sie -@code{"0.0.0.0"}, wenn auf allen verfügbaren Netzwerkschnittstellen -gelauscht werden soll. - -@item @code{compression-level} (Vorgabe: @code{3}) -Die gzip-Kompressionsstufe, mit der Substitute komprimiert werden -sollen. Benutzen Sie @code{0}, um Kompression völlig abzuschalten, und -@code{9} für das höchste Kompressionsverhältnis, zu Lasten von zusätzlicher -Prozessorauslastung. - -@item @code{nar-path} (Vorgabe: @code{"nar"}) -Der URL-Pfad, unter dem »Nars« zum Herunterladen angeboten werden. Siehe -@xref{Aufruf von guix publish, @code{--nar-path}}, für Details. - -@item @code{cache} (Vorgabe: @code{#f}) -Wenn dies @code{#f} ist, werden Archive nicht zwischengespeichert, sondern -erst bei einer Anfrage erzeugt. Andernfalls sollte dies der Name eines -Verzeichnisses sein — z.B. @code{"/var/cache/guix/publish"} —, in das -@command{guix publish} fertige Archive und Metadaten zwischenspeichern -soll. Siehe @xref{Aufruf von guix publish, @option{--cache}}, für weitere -Informationen über die jeweiligen Vor- und Nachteile. - -@item @code{workers} (Vorgabe: @code{#f}) -Ist dies eine ganze Zahl, gibt es die Anzahl der Worker-Threads an, die zum -Zwischenspeichern benutzt werden; ist es @code{#f}, werden so viele benutzt, -wie es Prozessoren gibt. Siehe @xref{Aufruf von guix publish, -@option{--workers}}, für mehr Informationen. - -@item @code{ttl} (Vorgabe: @code{#f}) -Wenn dies eine ganze Zahl ist, bezeichnet sie die @dfn{Time-to-live} als die -Anzahl der Sekunden, die heruntergeladene veröffentlichte Archive -zwischengespeichert werden dürfen. Siehe @xref{Aufruf von guix publish, -@option{--ttl}}, für mehr Informationen. -@end table -@end deftp - -@anchor{rngd-service} -@deffn {Scheme-Prozedur} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] Liefert einen Dienst, der das -@command{rngd}-Programm aus den @var{rng-tools} benutzt, um das mit -@var{device} bezeichnete Gerät zum Entropie-Pool des Kernels -hinzuzufügen. Dieser Dienst wird fehlschlagen, falls das mit @var{device} -bezeichnete Gerät nicht existiert. -@end deffn - -@anchor{pam-limits-service} -@cindex Sitzungs-Limits -@cindex ulimit -@cindex Priorität -@cindex Echtzeit -@cindex jackd -@deffn {Scheme-Prozedur} pam-limits-service [#:limits @code{'()}] - -Liefert einen Dienst, der eine Konfigurationsdatei für das -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, -@code{pam_limits}-Modul} installiert. Diese Prozedur nimmt optional eine -Liste von @code{pam-limits-entry}-Werten entgegen, die benutzt werden -können, um @code{ulimit}-Limits und nice-Prioritäten für Benutzersitzungen -festzulegen. - -Die folgenden Limit-Definitionen setzen zwei harte und weiche Limits für -alle Anmeldesitzungen für Benutzer in der @code{realtime}-Gruppe. - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -Der erste Eintrag erhöht die maximale Echtzeit-Priorität für unprivilegierte -Prozesse ohne zusätzliche Berechtigungen; der zweite Eintrag hebt jegliche -Einschränkungen des maximalen Adressbereichs auf, der im Speicher reserviert -werden darf. Diese Einstellungen werden in dieser Form oft für -Echtzeit-Audio-Systeme verwendet. -@end deffn - -@node Geplante Auftragsausführung -@subsection Geplante Auftragsausführung - -@cindex cron -@cindex mcron -@cindex scheduling jobs -The @code{(gnu services mcron)} module provides an interface to -GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, -mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix -@command{cron} daemon; the main difference is that it is implemented in -Guile Scheme, which provides a lot of flexibility when specifying the -scheduling of jobs and their actions. - -The example below defines an operating system that runs the -@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) and -the @command{guix gc} commands (@pxref{Aufruf von guix gc}) daily, as well as -the @command{mkid} command on behalf of an unprivileged user (@pxref{mkid -invocation,,, idutils, ID Database Utilities}). It uses gexps to introduce -job definitions that are passed to mcron (@pxref{G-Ausdrücke}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define updatedb-job - ;; Run 'updatedb' at 3AM every day. Here we write the - ;; job's action as a Scheme procedure. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define garbage-collector-job - ;; Collect garbage 5 minutes after midnight every day. - ;; The job's action is a shell command. - #~(job "5 0 * * *" ;Vixie cron syntax - "guix gc -F 1G")) - -(define idutils-job - ;; Update the index database as user "charlie" at 12:15PM - ;; and 19:15PM. This runs from the user's home directory. - #~(job '(next-minute-from (next-hour '(12 19)) '(15)) - (string-append #$idutils "/bin/mkid src") - #:user "charlie")) - -(operating-system - ;; @dots{} - (services (cons (service mcron-service-type - (mcron-configuration - (jobs (list garbage-collector-job - updatedb-job - idutils-job)))) - %base-services))) -@end lisp - -@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for -more information on mcron job specifications. Below is the reference of the -mcron service. - -On a running system, you can use the @code{schedule} action of the service -to visualize the mcron jobs that will be executed next: - -@example -# herd schedule mcron -@end example - -@noindent -The example above lists the next five tasks that will be executed, but you -can also specify the number of tasks to display: - -@example -# herd schedule mcron 10 -@end example - -@defvr {Scheme Variable} mcron-service-type -This is the type of the @code{mcron} service, whose value is an -@code{mcron-configuration} object. - -This service type can be the target of a service extension that provides it -additional job specifications (@pxref{Dienstkompositionen}). In other -words, it is possible to define services that provide additional mcron jobs -to run. -@end defvr - -@deftp {Data Type} mcron-configuration -Data type representing the configuration of mcron. - -@table @asis -@item @code{mcron} (default: @var{mcron}) -The mcron package to use. - -@item @code{jobs} -This is a list of gexps (@pxref{G-Ausdrücke}), where each gexp corresponds -to an mcron job specification (@pxref{Syntax, mcron job specifications,, -mcron, GNU@tie{}mcron}). -@end table -@end deftp - - -@node Log-Rotation -@subsection Log-Rotation - -@cindex rottlog -@cindex log rotation -@cindex Protokollierung -Log files such as those found in @file{/var/log} tend to grow endlessly, so -it's a good idea to @dfn{rotate} them once in a while---i.e., archive their -contents in separate files, possibly compressed. The @code{(gnu services -admin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotation -tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}). - -The example below defines an operating system that provides log rotation -with the default settings, for commonly encountered log files. - -@lisp -(use-modules (guix) (gnu)) -(use-service-modules admin mcron) -(use-package-modules base idutils) - -(operating-system - ;; @dots{} - (services (cons (service rottlog-service-type) - %base-services))) -@end lisp - -@defvr {Scheme Variable} rottlog-service-type -This is the type of the Rottlog service, whose value is a -@code{rottlog-configuration} object. - -Other services can extend this one with new @code{log-rotation} objects (see -below), thereby augmenting the set of files to be rotated. - -This service type can define mcron jobs (@pxref{Geplante Auftragsausführung}) to -run the rottlog service. -@end defvr - -@deftp {Data Type} rottlog-configuration -Data type representing the configuration of rottlog. - -@table @asis -@item @code{rottlog} (default: @code{rottlog}) -The Rottlog package to use. - -@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")}) -The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,, -rottlog, GNU Rot[t]log Manual}). - -@item @code{rotations} (default: @code{%default-rotations}) -A list of @code{log-rotation} objects as defined below. - -@item @code{jobs} -This is a list of gexps where each gexp corresponds to an mcron job -specification (@pxref{Geplante Auftragsausführung}). -@end table -@end deftp - -@deftp {Data Type} log-rotation -Data type representing the rotation of a group of log files. - -Taking an example from the Rottlog manual (@pxref{Period Related File -Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be defined -like this: - -@example -(log-rotation - (frequency 'daily) - (files '("/var/log/apache/*")) - (options '("storedir apache-archives" - "rotate 6" - "notifempty" - "nocompress"))) -@end example - -The list of fields is as follows: - -@table @asis -@item @code{frequency} (default: @code{'weekly}) -The log rotation frequency, a symbol. - -@item @code{files} -The list of files or file glob patterns to rotate. - -@item @code{options} (default: @code{'()}) -The list of rottlog options for this rotation (@pxref{Configuration -parameters,,, rottlog, GNU Rot[t]lg Manual}). - -@item @code{post-rotate} (default: @code{#f}) -Either @code{#f} or a gexp to execute once the rotation has completed. -@end table -@end deftp - -@defvr {Scheme Variable} %default-rotations -Specifies weekly rotation of @var{%rotated-files} and a couple of other -files. -@end defvr - -@defvr {Scheme Variable} %rotated-files -The list of syslog-controlled files to be rotated. By default it is: -@code{'("/var/log/messages" "/var/log/secure")}. -@end defvr - -@node Netzwerkdienste -@subsection Netzwerkdienste - -The @code{(gnu services networking)} module provides services to configure -the network interface. - -@cindex DHCP, networking service -@defvr {Scheme Variable} dhcp-client-service-type -This is the type of services that run @var{dhcp}, a Dynamic Host -Configuration Protocol (DHCP) client, on all the non-loopback network -interfaces. Its value is the DHCP client package to use, @code{isc-dhcp} by -default. -@end defvr - -@deffn {Scheme Procedure} dhcpd-service-type -This type defines a service that runs a DHCP daemon. To create a service of -this type, you must supply a @code{<dhcpd-configuration>}. For example: - -@example -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "my-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end example -@end deffn - -@deftp {Data Type} dhcpd-configuration -@table @asis -@item @code{package} (default: @code{isc-dhcp}) -The package that provides the DHCP daemon. This package is expected to -provide the daemon at @file{sbin/dhcpd} relative to its output directory. -The default package is the @uref{http://www.isc.org/products/DHCP, ISC's -DHCP server}. -@item @code{config-file} (default: @code{#f}) -The configuration file to use. This is required. It will be passed to -@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' -object (@pxref{G-Ausdrücke, file-like objects}). See @code{man -dhcpd.conf} for details on the configuration file syntax. -@item @code{version} (default: @code{"4"}) -The DHCP version to use. The ISC DHCP server supports the values ``4'', -``6'', and ``4o6''. These correspond to the @code{dhcpd} program options -@code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for details. -@item @code{run-directory} (default: @code{"/run/dhcpd"}) -The run directory to use. At service activation time, this directory will -be created if it does not exist. -@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"}) -The PID file to use. This corresponds to the @code{-pf} option of -@code{dhcpd}. See @code{man dhcpd} for details. -@item @code{interfaces} (default: @code{'()}) -The names of the network interfaces on which dhcpd should listen for -broadcasts. If this list is not empty, then its elements (which must be -strings) will be appended to the @code{dhcpd} invocation when starting the -daemon. It may not be necessary to explicitly specify any interfaces here; -see @code{man dhcpd} for details. -@end table -@end deftp - -@defvr {Scheme Variable} static-networking-service-type -@c TODO Document <static-networking> data structures. -This is the type for statically-configured network interfaces. -@end defvr - -@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ - [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ [#:requirement -@code{'(udev)}] Return a service that starts @var{interface} with address -@var{ip}. If @var{netmask} is true, use it as the network mask. If -@var{gateway} is true, it must be a string specifying the default network -gateway. @var{requirement} can be used to declare a dependency on another -service before configuring the interface. - -This procedure can be called several times, one for each network interface -of interest. Behind the scenes what it does is extend -@code{static-networking-service-type} with additional network interfaces to -handle. - -Zum Beispiel: - -@example -(static-networking-service "eno1" "192.168.1.82" - #:gateway "192.168.1.2" - #:name-servers '("192.168.1.2")) -@end example -@end deffn - -@cindex wicd -@cindex WLAN -@cindex WiFi -@cindex network management -@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] -Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network -management daemon that aims to simplify wired and wireless networking. - -This service adds the @var{wicd} package to the global profile, providing -several commands to interact with the daemon and configure networking: -@command{wicd-client}, a graphical user interface, and the -@command{wicd-cli} and @command{wicd-curses} user interfaces. -@end deffn - -@cindex ModemManager - -@defvr {Scheme Variable} modem-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} -service. The value for this service type is a -@code{modem-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}). -@end defvr - -@deftp {Data Type} modem-manager-configuration -Repräsentiert die Konfiguration vom ModemManager. - -@table @asis -@item @code{modem-manager} (Vorgabe: @code{modem-manager}) -Das ModemManager-Paket, was benutzt werden soll. - -@end table -@end deftp - -@cindex NetworkManager - -@defvr {Scheme Variable} network-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} -service. The value for this service type is a -@code{network-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}). -@end defvr - -@deftp {Data Type} network-manager-configuration -Data type representing the configuration of NetworkManager. - -@table @asis -@item @code{network-manager} (default: @code{network-manager}) -The NetworkManager package to use. - -@item @code{dns} (default: @code{"default"}) -Processing mode for DNS, which affects how NetworkManager uses the -@code{resolv.conf} configuration file. - -@table @samp -@item default -NetworkManager will update @code{resolv.conf} to reflect the nameservers -provided by currently active connections. - -@item dnsmasq -NetworkManager will run @code{dnsmasq} as a local caching nameserver, using -a "split DNS" configuration if you are connected to a VPN, and then update -@code{resolv.conf} to point to the local nameserver. - -@item none -NetworkManager will not modify @code{resolv.conf}. -@end table - -@item @code{vpn-plugins} (default: @code{'()}) -This is the list of available plugins for virtual private networks (VPNs). -An example of this is the @code{network-manager-openvpn} package, which -allows NetworkManager to manage VPNs @i{via} OpenVPN. - -@end table -@end deftp - -@cindex Connman -@deffn {Scheme Variable} connman-service-type -This is the service type to run @url{https://01.org/connman,Connman}, a -network connection manager. - -Its value must be an @code{connman-configuration} record as in this example: - -@example -(service connman-service-type - (connman-configuration - (disable-vpn? #t))) -@end example - -See below for details about @code{connman-configuration}. -@end deffn - -@deftp {Data Type} connman-configuration -Data Type representing the configuration of connman. - -@table @asis -@item @code{connman} (default: @var{connman}) -The connman package to use. - -@item @code{disable-vpn?} (default: @code{#f}) -When true, disable connman's vpn plugin. -@end table -@end deftp - -@cindex WPA Supplicant -@defvr {Scheme Variable} wpa-supplicant-service-type -This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA -supplicant}, an authentication daemon required to authenticate against -encrypted WiFi or ethernet networks. -@end defvr - -@deftp {Data Type} wpa-supplicant-configuration -Repräsentiert die Konfiguration des WPA-Supplikanten. - -Sie hat folgende Parameter: - -@table @asis -@item @code{wpa-supplicant} (Vorgabe: @code{wpa-supplicant}) -Das WPA-Supplicant-Paket, was benutzt werden soll. - -@item @code{dbus?} (Vorgabe: @code{#t}) -Whether to listen for requests on D-Bus. - -@item @code{pid-file} (Vorgabe: @code{"/var/run/wpa_supplicant.pid"}) -Wo die PID-Datei abgelegt wird. - -@item @code{interface} (Vorgabe: @code{#f}) -If this is set, it must specify the name of a network interface that WPA -supplicant will control. - -@item @code{config-file} (default: @code{#f}) -Optionale Konfigurationsdatei. - -@item @code{extra-options} (Vorgabe: @code{'()}) -List of additional command-line arguments to pass to the daemon. -@end table -@end deftp - -@cindex iptables -@defvr {Scheme Variable} iptables-service-type -This is the service type to set up an iptables configuration. iptables is a -packet filtering framework supported by the Linux kernel. This service -supports configuring iptables for both IPv4 and IPv6. A simple example -configuration rejecting all incoming connections except those to the ssh -port 22 is shown below. - -@lisp -(service iptables-service-type - (iptables-configuration - (ipv4-rules (plain-file "iptables.rules" "*filter -:INPUT ACCEPT -:FORWARD ACCEPT -:OUTPUT ACCEPT --A INPUT -p tcp --dport 22 -j ACCEPT --A INPUT -j REJECT --reject-with icmp-port-unreachable -COMMIT -")) - (ipv6-rules (plain-file "ip6tables.rules" "*filter -:INPUT ACCEPT -:FORWARD ACCEPT -:OUTPUT ACCEPT --A INPUT -p tcp --dport 22 -j ACCEPT --A INPUT -j REJECT --reject-with icmp6-port-unreachable -COMMIT -")))) -@end lisp -@end defvr - -@deftp {Datentyp} iptables-configuration -Repräsentiert die iptables-Konfiguration. - -@table @asis -@item @code{iptables} (Vorgabe: @code{iptables}) -The iptables package that provides @code{iptables-restore} and -@code{ip6tables-restore}. -@item @code{ipv4-rules} (Vorgabe: @code{%iptables-accept-all-rules}) -The iptables rules to use. It will be passed to @code{iptables-restore}. -This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like -objects}). -@item @code{ipv6-rules} (Vorgabe: @code{%iptables-accept-all-rules}) -The ip6tables rules to use. It will be passed to @code{ip6tables-restore}. -This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like -objects}). -@end table -@end deftp - -@cindex NTP (Network Time Protocol), Dienst -@cindex real time clock -@defvr {Scheme Variable} ntp-service-type -This is the type of the service running the @uref{http://www.ntp.org, -Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep -the system clock synchronized with that of the specified NTP servers. - -The value of this service is an @code{ntpd-configuration} object, as -described below. -@end defvr - -@deftp {Datentyp} ntp-configuration -Der Datentyp für die Dienstkonfiguration des NTP-Dienstes. - -@table @asis -@item @code{servers} (Vorgabe: @code{%ntp-servers}) -This is the list of servers (host names) with which @command{ntpd} will be -synchronized. - -@item @code{allow-large-adjustment?} (default: @code{#f}) -This determines whether @command{ntpd} is allowed to make an initial -adjustment of more than 1,000 seconds. - -@item @code{ntp} (Vorgabe: @code{ntp}) -Das NTP-Paket, was benutzt werden soll. -@end table -@end deftp - -@defvr {Scheme Variable} %ntp-servers -List of host names used as the default NTP servers. These are servers of -the @uref{https://www.ntppool.org/en/, NTP Pool Project}. -@end defvr - -@cindex OpenNTPD -@deffn {Scheme Procedure} openntpd-service-type -Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as -implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will -keep the system clock synchronized with that of the given servers. - -@example -(service - openntpd-service-type - (openntpd-configuration - (listen-on '("127.0.0.1" "::1")) - (sensor '("udcf0 correction 70000")) - (constraint-from '("www.gnu.org")) - (constraints-from '("https://www.google.com/")) - (allow-large-adjustment? #t))) - -@end example -@end deffn - -@deftp {Data Type} openntpd-configuration -@table @asis -@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")}) -The openntpd executable to use. -@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")}) -A list of local IP addresses or hostnames the ntpd daemon should listen on. -@item @code{query-from} (default: @code{'()}) -A list of local IP address the ntpd daemon should use for outgoing queries. -@item @code{sensor} (default: @code{'()}) -Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} -will listen to each sensor that acutally exists and ignore non-existant -ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} -for more information. -@item @code{server} (default: @var{%ntp-servers}) -Specify a list of IP addresses or hostnames of NTP servers to synchronize -to. -@item @code{servers} (default: @code{'()}) -Specify a list of IP addresses or hostnames of NTP pools to synchronize to. -@item @code{constraint-from} (default: @code{'()}) -@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers -via TLS. This time information is not used for precision but acts as an -authenticated constraint, thereby reducing the impact of unauthenticated NTP -man-in-the-middle attacks. Specify a list of URLs, IP addresses or -hostnames of HTTPS servers to provide a constraint. -@item @code{constraints-from} (default: @code{'()}) -As with constraint from, specify a list of URLs, IP addresses or hostnames -of HTTPS servers to provide a constraint. Should the hostname resolve to -multiple IP addresses, @code{ntpd} will calculate a median constraint from -all of them. -@item @code{allow-large-adjustment?} (default: @code{#f}) -Determines if @code{ntpd} is allowed to make an initial adjustment of more -than 180 seconds. -@end table -@end deftp - -@cindex inetd -@deffn {Scheme variable} inetd-service-type -This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils, -GNU Inetutils}) daemon. @command{inetd} listens for connections on internet -sockets, and lazily starts the specified server program when a connection is -made on one of these sockets. - -The value of this service is an @code{inetd-configuration} object. The -following example configures the @command{inetd} daemon to provide the -built-in @command{echo} service, as well as an smtp service which forwards -smtp traffic over ssh to a server @code{smtp-server} behind a gateway -@code{hostname}: - -@example -(service - inetd-service-type - (inetd-configuration - (entries (list - (inetd-entry - (name "echo") - (socket-type 'stream) - (protocol "tcp") - (wait? #f) - (user "root")) - (inetd-entry - (node "127.0.0.1") - (name "smtp") - (socket-type 'stream) - (protocol "tcp") - (wait? #f) - (user "root") - (program (file-append openssh "/bin/ssh")) - (arguments - '("ssh" "-qT" "-i" "/path/to/ssh_key" - "-W" "smtp-server:25" "user@@hostname"))))) -@end example - -See below for more details about @code{inetd-configuration}. -@end deffn - -@deftp {Data Type} inetd-configuration -Data type representing the configuration of @command{inetd}. - -@table @asis -@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")}) -The @command{inetd} executable to use. - -@item @code{entries} (default: @code{'()}) -A list of @command{inetd} service entries. Each entry should be created by -the @code{inetd-entry} constructor. -@end table -@end deftp - -@deftp {Data Type} inetd-entry -Data type representing an entry in the @command{inetd} configuration. Each -entry corresponds to a socket where @command{inetd} will listen for -requests. - -@table @asis -@item @code{node} (Vorgabe: @code{#f}) -Optional string, a comma-separated list of local addresses @command{inetd} -should use when listening for this service. @xref{Configuration file,,, -inetutils, GNU Inetutils} for a complete description of all options. -@item @code{name} -A string, the name must correspond to an entry in @code{/etc/services}. -@item @code{socket-type} -One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or -@code{'seqpacket}. -@item @code{protocol} -A string, must correspond to an entry in @code{/etc/protocols}. -@item @code{wait?} (Vorgabe: @code{#t}) -Whether @command{inetd} should wait for the server to exit before listening -to new service requests. -@item @code{user} -A string containing the user (and, optionally, group) name of the user as -whom the server should run. The group name can be specified in a suffix, -separated by a colon or period, i.e.@: @code{"user"}, @code{"user:group"} or -@code{"user.group"}. -@item @code{program} (default: @code{"internal"}) -The server program which will serve the requests, or @code{"internal"} if -@command{inetd} should use a built-in service. -@item @code{arguments} (Vorgabe: @code{'()}) -A list strings or file-like objects, which are the server program's -arguments, starting with the zeroth argument, i.e.@: the name of the program -itself. For @command{inetd}'s internal services, this entry must be -@code{'()} or @code{'("internal")}. -@end table - -@xref{Configuration file,,, inetutils, GNU Inetutils} for a more detailed -discussion of each configuration field. -@end deftp - -@cindex Tor -@defvr {Scheme Variable} tor-service-type -This is the type for a service that runs the @uref{https://torproject.org, -Tor} anonymous networking daemon. The service is configured using a -@code{<tor-configuration>} record. By default, the Tor daemon runs as the -@code{tor} unprivileged user, which is a member of the @code{tor} group. - -@end defvr - -@deftp {Datentyp} tor-configuration -@table @asis -@item @code{tor} (Vorgabe: @code{tor}) -The package that provides the Tor daemon. This package is expected to -provide the daemon at @file{bin/tor} relative to its output directory. The -default package is the @uref{https://www.torproject.org, Tor Project's} -implementation. - -@item @code{config-file} (Vorgabe: @code{(plain-file "empty" "")}) -The configuration file to use. It will be appended to a default -configuration file, and the final configuration file will be passed to -@code{tor} via its @code{-f} option. This may be any ``file-like'' object -(@pxref{G-Ausdrücke, file-like objects}). See @code{man tor} for details -on the configuration file syntax. - -@item @code{hidden-services} (Vorgabe: @code{'()}) -The list of @code{<hidden-service>} records to use. For any hidden service -you include in this list, appropriate configuration to enable the hidden -service will be automatically added to the default configuration file. You -may conveniently create @code{<hidden-service>} records using the -@code{tor-hidden-service} procedure described below. - -@item @code{socks-socket-type} (Vorgabe: @code{'tcp}) -The default socket type that Tor should use for its SOCKS socket. This must -be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by -default Tor will listen on TCP port 9050 on the loopback interface (i.e., -localhost). If it is @code{'unix}, then Tor will listen on the UNIX domain -socket @file{/var/run/tor/socks-sock}, which will be made writable by -members of the @code{tor} group. - -If you want to customize the SOCKS socket in more detail, leave -@code{socks-socket-type} at its default value of @code{'tcp} and use -@code{config-file} to override the default by providing your own -@code{SocksPort} option. -@end table -@end deftp - -@cindex hidden service -@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping} -Define a new Tor @dfn{hidden service} called @var{name} and implementing -@var{mapping}. @var{mapping} is a list of port/host tuples, such as: - -@example - '((22 "127.0.0.1:22") - (80 "127.0.0.1:8080")) -@end example - -In this example, port 22 of the hidden service is mapped to local port 22, -and port 80 is mapped to local port 8080. - -This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, -where the @file{hostname} file contains the @code{.onion} host name for the -hidden service. - -See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the -Tor project's documentation} for more information. -@end deffn - -The @code{(gnu services rsync)} module provides the following services: - -You might want an rsync daemon if you have files that you want available so -anyone (or just yourself) can download existing files or upload new files. - -@deffn {Scheme Variable} rsync-service-type -This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon, -@command{rsync-configuration} record as in this example: - -@example -(service rsync-service-type) -@end example - -See below for details about @code{rsync-configuration}. -@end deffn - -@deftp {Data Type} rsync-configuration -Data type representing the configuration for @code{rsync-service}. - -@table @asis -@item @code{package} (default: @var{rsync}) -@code{rsync} package to use. - -@item @code{port-number} (default: @code{873}) -TCP port on which @command{rsync} listens for incoming connections. If port -is less than @code{1024} @command{rsync} needs to be started as the -@code{root} user and group. - -@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"}) -Name of the file where @command{rsync} writes its PID. - -@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"}) -Name of the file where @command{rsync} writes its lock file. - -@item @code{log-file} (default: @code{"/var/log/rsyncd.log"}) -Name of the file where @command{rsync} writes its log file. - -@item @code{use-chroot?} (default: @var{#t}) -Whether to use chroot for @command{rsync} shared directory. - -@item @code{share-path} (default: @file{/srv/rsync}) -Location of the @command{rsync} shared directory. - -@item @code{share-comment} (default: @code{"Rsync share"}) -Comment of the @command{rsync} shared directory. - -@item @code{read-only?} (default: @var{#f}) -Read-write permissions to shared directory. - -@item @code{timeout} (default: @code{300}) -I/O timeout in seconds. - -@item @code{user} (default: @var{"root"}) -Owner of the @code{rsync} process. - -@item @code{group} (default: @var{"root"}) -Group of the @code{rsync} process. - -@item @code{uid} (default: @var{"rsyncd"}) -User name or user ID that file transfers to and from that module should take -place as when the daemon was run as @code{root}. - -@item @code{gid} (default: @var{"rsyncd"}) -Group name or group ID that will be used when accessing the module. - -@end table -@end deftp - -Furthermore, @code{(gnu services ssh)} provides the following services. -@cindex SSH -@cindex SSH server - -@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ - [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ -[#:allow-empty-passwords? #f] [#:root-login? #f] @ [#:syslog-output? #t] -[#:x11-forwarding? #t] @ [#:tcp/ip-forwarding? #t] -[#:password-authentication? #t] @ [#:public-key-authentication? #t] -[#:initialize? #t] Run the @command{lshd} program from @var{lsh} to listen -on port @var{port-number}. @var{host-key} must designate a file containing -the host key, and readable only by root. - -When @var{daemonic?} is true, @command{lshd} will detach from the -controlling terminal and log its output to syslogd, unless one sets -@var{syslog-output?} to false. Obviously, it also makes lsh-service depend -on existence of syslogd service. When @var{pid-file?} is true, -@command{lshd} writes its PID to the file called @var{pid-file}. - -When @var{initialize?} is true, automatically create the seed and host key -upon service activation if they do not exist yet. This may take long and -require interaction. - -When @var{initialize?} is false, it is up to the user to initialize the -randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to -create a key pair with the private key stored in file @var{host-key} -(@pxref{lshd basics,,, lsh, LSH Manual}). - -When @var{interfaces} is empty, lshd listens for connections on all the -network interfaces; otherwise, @var{interfaces} must be a list of host names -or addresses. - -@var{allow-empty-passwords?} specifies whether to accept log-ins with empty -passwords, and @var{root-login?} specifies whether to accept log-ins as -root. - -The other options should be self-descriptive. -@end deffn - -@cindex SSH -@cindex SSH server -@deffn {Scheme Variable} openssh-service-type -This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell -daemon, @command{sshd}. Its value must be an @code{openssh-configuration} -record as in this example: - -@example -(service openssh-service-type - (openssh-configuration - (x11-forwarding? #t) - (permit-root-login 'without-password) - (authorized-keys - `(("alice" ,(local-file "alice.pub")) - ("bob" ,(local-file "bob.pub")))))) -@end example - -See below for details about @code{openssh-configuration}. - -This service can be extended with extra authorized keys, as in this example: - -@example -(service-extension openssh-service-type - (const `(("charlie" - ,(local-file "charlie.pub"))))) -@end example -@end deffn - -@deftp {Data Type} openssh-configuration -This is the configuration record for OpenSSH's @command{sshd}. - -@table @asis -@item @code{pid-file} (default: @code{"/var/run/sshd.pid"}) -Name of the file where @command{sshd} writes its PID. - -@item @code{port-number} (default: @code{22}) -TCP port on which @command{sshd} listens for incoming connections. - -@item @code{permit-root-login} (default: @code{#f}) -This field determines whether and when to allow logins as root. If -@code{#f}, root logins are disallowed; if @code{#t}, they are allowed. If -it's the symbol @code{'without-password}, then root logins are permitted but -not with password-based authentication. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -When true, users with empty passwords may log in. When false, they may not. - -@item @code{password-authentication?} (default: @code{#t}) -When true, users may log in with their password. When false, they have -other authentication methods. - -@item @code{public-key-authentication?} (default: @code{#t}) -When true, users may log in using public key authentication. When false, -users have to use other authentication method. - -Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is -used only by protocol version 2. - -@item @code{x11-forwarding?} (default: @code{#f}) -When true, forwarding of X11 graphical client connections is enabled---in -other words, @command{ssh} options @option{-X} and @option{-Y} will work. - -@item @code{allow-agent-forwarding?} (Vorgabe: @code{#t}) -Whether to allow agent forwarding. - -@item @code{allow-tcp-forwarding?} (Vorgabe: @code{#t}) -Whether to allow TCP forwarding. - -@item @code{gateway-ports?} (Vorgabe: @code{#f}) -Whether to allow gateway ports. - -@item @code{challenge-response-authentication?} (default: @code{#f}) -Specifies whether challenge response authentication is allowed (e.g.@: via -PAM). - -@item @code{use-pam?} (default: @code{#t}) -Enables the Pluggable Authentication Module interface. If set to @code{#t}, -this will enable PAM authentication using -@code{challenge-response-authentication?} and -@code{password-authentication?}, in addition to PAM account and session -module processing for all authentication types. - -Because PAM challenge response authentication usually serves an equivalent -role to password authentication, you should disable either -@code{challenge-response-authentication?} or -@code{password-authentication?}. - -@item @code{print-last-log?} (default: @code{#t}) -Specifies whether @command{sshd} should print the date and time of the last -user login when a user logs in interactively. - -@item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))}) -Configures external subsystems (e.g.@: file transfer daemon). - -This is a list of two-element lists, each of which containing the subsystem -name and a command (with optional arguments) to execute upon subsystem -request. - -The command @command{internal-sftp} implements an in-process SFTP server. -Alternately, one can specify the @command{sftp-server} command: -@example -(service openssh-service-type - (openssh-configuration - (subsystems - `(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) -@end example - -@item @code{accepted-environment} (default: @code{'()}) -List of strings describing which environment variables may be exported. - -Each string gets on its own line. See the @code{AcceptEnv} option in -@code{man sshd_config}. - -This example allows ssh-clients to export the @code{COLORTERM} variable. It -is set by terminal emulators, which support colors. You can use it in your -shell's ressource file to enable colors for the prompt and commands if this -variable is set. - -@example -(service openssh-service-type - (openssh-configuration - (accepted-environment '("COLORTERM")))) -@end example - -@item @code{authorized-keys} (default: @code{'()}) -@cindex authorized keys, SSH -@cindex SSH authorized keys -This is the list of authorized keys. Each element of the list is a user -name followed by one or more file-like objects that represent SSH public -keys. For example: - -@example -(openssh-configuration - (authorized-keys - `(("rekado" ,(local-file "rekado.pub")) - ("chris" ,(local-file "chris.pub")) - ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub"))))) -@end example - -@noindent -registers the specified public keys for user accounts @code{rekado}, -@code{chris}, and @code{root}. - -Additional authorized keys can be specified @i{via} -@code{service-extension}. - -Note that this does @emph{not} interfere with the use of -@file{~/.ssh/authorized_keys}. - -@item @code{log-level} (Vorgabe: @code{'info}) -This is a symbol specifying the logging level: @code{quiet}, @code{fatal}, -@code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man -page for @file{sshd_config} for the full list of level names. - -@item @code{extra-content} (Vorgabe: @code{""}) -This field can be used to append arbitrary text to the configuration file. -It is especially useful for elaborate configurations that cannot be -expressed otherwise. This configuration, for example, would generally -disable root logins, but permit them from one specific IP address: - -@example -(openssh-configuration - (extra-content "\ -Match Address 192.168.0.1 - PermitRootLogin yes")) -@end example - -@end table -@end deftp - -@deffn {Scheme Procedure} dropbear-service [@var{config}] -Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH -daemon} with the given @var{config}, a @code{<dropbear-configuration>} -object. - -For example, to specify a Dropbear service listening on port 1234, add this -call to the operating system's @code{services} field: - -@example -(dropbear-service (dropbear-configuration - (port-number 1234))) -@end example -@end deffn - -@deftp {Data Type} dropbear-configuration -This data type represents the configuration of a Dropbear SSH daemon. - -@table @asis -@item @code{dropbear} (default: @var{dropbear}) -The Dropbear package to use. - -@item @code{port-number} (default: 22) -The TCP port where the daemon waits for incoming connections. - -@item @code{syslog-output?} (default: @code{#t}) -Whether to enable syslog output. - -@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"}) -File name of the daemon's PID file. - -@item @code{root-login?} (default: @code{#f}) -Whether to allow @code{root} logins. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -Whether to allow empty passwords. - -@item @code{password-authentication?} (default: @code{#t}) -Whether to enable password-based authentication. -@end table -@end deftp - -@defvr {Scheme Variable} %facebook-host-aliases -This variable contains a string for use in @file{/etc/hosts} (@pxref{Host -Names,,, libc, The GNU C Library Reference Manual}). Each line contains a -entry that maps a known server name of the Facebook on-line service---e.g., -@code{www.facebook.com}---to the local host---@code{127.0.0.1} or its IPv6 -equivalent, @code{::1}. - -This variable is typically used in the @code{hosts-file} field of an -@code{operating-system} declaration (@pxref{»operating-system«-Referenz, -@file{/etc/hosts}}): - -@example -(use-modules (gnu) (guix)) - -(operating-system - (host-name "mymachine") - ;; ... - (hosts-file - ;; Create a /etc/hosts file with aliases for "localhost" - ;; and "mymachine", as well as for Facebook servers. - (plain-file "hosts" - (string-append (local-host-aliases host-name) - %facebook-host-aliases)))) -@end example - -This mechanism can prevent programs running locally, such as Web browsers, -from accessing Facebook. -@end defvr - -The @code{(gnu services avahi)} provides the following definition. - -@defvr {Scheme Variable} avahi-service-type -This is the service that runs @command{avahi-daemon}, a system-wide -mDNS/DNS-SD responder that allows for service discovery and -``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). -Its value must be a @code{zero-configuration} record---see below. - -This service extends the name service cache daemon (nscd) so that it can -resolve @code{.local} host names using -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name Service Switch}, for information on host name resolution. - -Additionally, add the @var{avahi} package to the system profile so that -commands such as @command{avahi-browse} are directly usable. -@end defvr - -@deftp {Data Type} avahi-configuration -Data type representation the configuration for Avahi. - -@table @asis - -@item @code{host-name} (default: @code{#f}) -If different from @code{#f}, use that as the host name to publish for this -machine; otherwise, use the machine's actual host name. - -@item @code{publish?} (default: @code{#t}) -When true, allow host names and services to be published (broadcast) over -the network. - -@item @code{publish-workstation?} (default: @code{#t}) -When true, @command{avahi-daemon} publishes the machine's host name and IP -address via mDNS on the local network. To view the host names published on -your local network, you can run: - -@example -avahi-browse _workstation._tcp -@end example - -@item @code{wide-area?} (default: @code{#f}) -When true, DNS-SD over unicast DNS is enabled. - -@item @code{ipv4?} (default: @code{#t}) -@itemx @code{ipv6?} (default: @code{#t}) -These fields determine whether to use IPv4/IPv6 sockets. - -@item @code{domains-to-browse} (default: @code{'()}) -This is a list of domains to browse. -@end table -@end deftp - -@deffn {Scheme Variable} openvswitch-service-type -This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} -service, whose value should be an @code{openvswitch-configuration} object. -@end deffn - -@deftp {Data Type} openvswitch-configuration -Data type representing the configuration of Open vSwitch, a multilayer -virtual switch which is designed to enable massive network automation -through programmatic extension. - -@table @asis -@item @code{package} (default: @var{openvswitch}) -Package object of the Open vSwitch. - -@end table -@end deftp - -@node X Window -@subsection X Window - -@cindex X11 -@cindex X Window System -@cindex login manager -Support for the X Window graphical display system---specifically Xorg---is -provided by the @code{(gnu services xorg)} module. Note that there is no -@code{xorg-service} procedure. Instead, the X server is started by the -@dfn{login manager}, by default SLiM. - -@cindex window manager -To use X11, you must install at least one @dfn{window manager}---for example -the @code{windowmaker} or @code{openbox} packages---preferably by adding it -to the @code{packages} field of your operating system definition -(@pxref{»operating-system«-Referenz, system-wide packages}). - -@defvr {Scheme Variable} slim-service-type -This is the type for the SLiM graphical login manager for X11. - -@cindex session types (X11) -@cindex X11 session types -SLiM looks for @dfn{session types} described by the @file{.desktop} files in -@file{/run/current-system/profile/share/xsessions} and allows users to -choose a session from the log-in screen using @kbd{F1}. Packages such as -@code{xfce}, @code{sawfish}, and @code{ratpoison} provide @file{.desktop} -files; adding them to the system-wide set of packages automatically makes -them available at the log-in screen. - -In addition, @file{~/.xsession} files are honored. When available, -@file{~/.xsession} must be an executable that starts a window manager and/or -other X clients. -@end defvr - -@deftp {Data Type} slim-configuration -Data type representing the configuration of @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (Vorgabe: @code{#t}) -Whether to allow logins with empty passwords. - -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (default: @code{""}) -When @code{auto-login?} is false, SLiM presents a log-in screen. - -When @code{auto-login?} is true, SLiM logs in directly as -@code{default-user}. - -@item @code{theme} (default: @code{%default-slim-theme}) -@itemx @code{theme-name} (default: @code{%default-slim-theme-name}) -The graphical theme to use and its name. - -@item @code{auto-login-session} (default: @code{#f}) -If true, this must be the name of the executable to start as the default -session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}. - -If false, a session described by one of the available @file{.desktop} files -in @code{/run/current-system/profile} and @code{~/.guix-profile} will be -used. - -@quotation Anmerkung -You must install at least one window manager in the system profile or in -your user profile. Failing to do that, if @code{auto-login-session} is -false, you will be unable to log in. -@end quotation - -@item @code{startx} (default: @code{(xorg-start-command)}) -The command used to start the X11 graphical server. - -@item @code{xauth} (default: @code{xauth}) -The XAuth package to use. - -@item @code{shepherd} (default: @code{shepherd}) -The Shepherd package used when invoking @command{halt} and @command{reboot}. - -@item @code{sessreg} (default: @code{sessreg}) -The sessreg package used in order to register the session. - -@item @code{slim} (default: @code{slim}) -The SLiM package to use. -@end table -@end deftp - -@defvr {Scheme Variable} %default-theme -@defvrx {Scheme Variable} %default-theme-name -The default SLiM theme and its name. -@end defvr - - -@deftp {Data Type} sddm-configuration -This is the data type representing the sddm service configuration. - -@table @asis -@item @code{display-server} (default: "x11") -Select display server to use for the greeter. Valid values are "x11" or -"wayland". - -@item @code{numlock} (default: "on") -Valid values are "on", "off" or "none". - -@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")}) -Command to run when halting. - -@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")}) -Command to run when rebooting. - -@item @code{theme} (default "maldives") -Theme to use. Default themes provided by SDDM are "elarun" or "maldives". - -@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes") -Directory to look for themes. - -@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces") -Directory to look for faces. - -@item @code{default-path} (default "/run/current-system/profile/bin") -Default PATH to use. - -@item @code{minimum-uid} (default 1000) -Minimum UID to display in SDDM. - -@item @code{maximum-uid} (default 2000) -Maximum UID to display in SDDM - -@item @code{remember-last-user?} (default #t) -Remember last user. - -@item @code{remember-last-session?} (default #t) -Remember last session. - -@item @code{hide-users} (default "") -Usernames to hide from SDDM greeter. - -@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")}) -Users with shells listed will be hidden from the SDDM greeter. - -@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) -Script to run before starting a wayland session. - -@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions") -Directory to look for desktop files starting wayland sessions. - -@item @code{xorg-server-path} (default @code{xorg-start-command}) -Path to xorg-server. - -@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")}) -Path to xauth. - -@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")}) -Path to Xephyr. - -@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) -Script to run after starting xorg-server. - -@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) -Script to run before stopping xorg-server. - -@item @code{xsession-command} (Vorgabe: @code{xinitrc}) -Script to run before starting a X session. - -@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions") -Directory to look for desktop files starting X sessions. - -@item @code{minimum-vt} (default: 7) -Minimum VT to use. - -@item @code{xserver-arguments} (default "-nolisten tcp") -Arguments to pass to xorg-server. - -@item @code{auto-login-user} (default "") -User to use for auto-login. - -@item @code{auto-login-session} (default "") -Desktop file to use for auto-login. - -@item @code{relogin?} (default #f) -Relogin after logout. - -@end table -@end deftp - -@cindex login manager -@cindex X11 login -@deffn {Scheme Procedure} sddm-service config -Return a service that spawns the SDDM graphical login manager for config of -type @code{<sddm-configuration>}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@deffn {Scheme Procedure} xorg-start-command [#:guile] @ - [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @ -[#:configuration-file (xorg-configuration-file @dots{})] @ [#:xorg-server -@var{xorg-server}] [#:xserver-arguments '("-nolisten" "tcp")] Return a -@code{startx} script in which @var{modules}, a list of X module packages, -and @var{fonts}, a list of X font directories, are available. See -@code{xorg-wrapper} for more details on the arguments. The result should be -used in place of @code{startx}. - -Usually the X server is started by a login manager. -@end deffn - -@cindex @code{-listen tcp}, for X11. -This procedure is useful to override command line options for the X server, -such as having it listen to over TCP: - -@example -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:xserver-arguments '("-listen" "tcp")))))))) -@end example - -@deffn {Scheme Procedure} xorg-configuration-file @ - [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @ -[#:drivers '()] [#:resolutions '()] [#:extra-config '()] Return a -configuration file for the Xorg server containing search paths for all the -common drivers. - -@var{modules} must be a list of @dfn{module packages} loaded by the Xorg -server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so -on. @var{fonts} must be a list of font directories to add to the server's -@dfn{font path}. - -@var{drivers} must be either the empty list, in which case Xorg chooses a -graphics driver automatically, or a list of driver names that will be tried -in this order---e.g., @code{("modesetting" "vesa")}. - -Likewise, when @var{resolutions} is the empty list, Xorg chooses an -appropriate screen resolution; otherwise, it must be a list of -resolutions---e.g., @code{((1024 768) (640 480))}. - -Last, @var{extra-config} is a list of strings or objects appended to the -configuration file. It is used to pass extra text to be added verbatim to -the configuration file. - -@cindex Keymap -@cindex Tastaturbelegung -This procedure is especially useful to configure a different keyboard layout -than the default US keymap. For instance, to use the ``bépo'' keymap by -default on the display manager: - -@example -(define bepo-evdev - "Section \"InputClass\" - Identifier \"evdev keyboard catchall\" - Driver \"evdev\" - MatchIsKeyboard \"on\" - Option \"xkb_layout\" \"fr\" - Option \"xkb_variant\" \"bepo\" -EndSection") - -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:configuration-file - (xorg-configuration-file - #:extra-config - (list bepo-evdev))))))))) -@end example - -The @code{MatchIsKeyboard} line specifies that we only apply the -configuration to keyboards. Without this line, other devices such as -touchpad may not work correctly because they will be attached to the wrong -driver. In this example, the user typically used @code{setxkbmap fr bepo} -to set their favorite keymap once logged in. The first argument corresponds -to the layout, while the second argument corresponds to the variant. The -@code{xkb_variant} line can be omitted to select the default variant. -@end deffn - -@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}] -Add @var{package}, a package for a screen locker or screen saver whose -command is @var{program}, to the set of setuid programs and add a PAM entry -for it. For example: - -@lisp -(screen-locker-service xlockmore "xlock") -@end lisp - -makes the good ol' XlockMore usable. -@end deffn - - -@node Druckdienste -@subsection Druckdienste - -@cindex printer support with CUPS -The @code{(gnu services cups)} module provides a Guix service definition for -the CUPS printing service. To add printer support to a Guix system, add a -@code{cups-service} to the operating system definition: - -@deffn {Scheme Variable} cups-service-type -The service type for the CUPS print server. Its value should be a valid -CUPS configuration (see below). To use the default settings, simply write: -@example -(service cups-service-type) -@end example -@end deffn - -The CUPS configuration controls the basic things about your CUPS -installation: what interfaces it listens on, what to do if a print job -fails, how much logging to do, and so on. To actually add a printer, you -have to visit the @url{http://localhost:631} URL, or use a tool such as -GNOME's printer configuration services. By default, configuring a CUPS -service will generate a self-signed certificate if needed, for secure -connections to the print server. - -Suppose you want to enable the Web interface of CUPS and also add support -for Epson printers @i{via} the @code{escpr} package and for HP printers -@i{via} the @code{hplip-minimal} package. You can do that directly, like -this (you need to use the @code{(gnu packages cups)} module): - -@example -(service cups-service-type - (cups-configuration - (web-interface? #t) - (extensions - (list cups-filters escpr hplip-minimal)))) -@end example - -Note: If you wish to use the Qt5 based GUI which comes with the hplip -package then it is suggested that you install the @code{hplip} package, -either in your OS configuration file or as your user. - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. There is -also a way to specify the configuration as a string, if you have an old -@code{cupsd.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services cups). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as CUPS updates. - - -Available @code{cups-configuration} fields are: - -@deftypevr {@code{cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} package-list extensions -Drivers and other extensions to the CUPS package. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration -Configuration of where to write logs, what directories to use for print -spools, and related privileged configuration parameters. - -Available @code{files-configuration} fields are: - -@deftypevr {@code{files-configuration} parameter} log-location access-log -Defines the access log filename. Specifying a blank filename disables -access log generation. The value @code{stderr} causes log entries to be -sent to the standard error file when the scheduler is running in the -foreground, or to the system log daemon when run in the background. The -value @code{syslog} causes log entries to be sent to the system log daemon. -The server name may be included in filenames using the string @code{%s}, as -in @code{/var/log/cups/%s-access_log}. - -Defaults to @samp{"/var/log/cups/access_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name cache-dir -Where CUPS should cache data. - -Defaults to @samp{"/var/cache/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string config-file-perm -Specifies the permissions for all configuration files that the scheduler -writes. - -Note that the permissions for the printers.conf file are currently masked to -only allow access from the scheduler user (typically root). This is done -because printer device URIs sometimes contain sensitive authentication -information that should not be generally known on the system. There is no -way to disable this security feature. - -Defaults to @samp{"0640"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location error-log -Defines the error log filename. Specifying a blank filename disables access -log generation. The value @code{stderr} causes log entries to be sent to -the standard error file when the scheduler is running in the foreground, or -to the system log daemon when run in the background. The value -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-error_log}. - -Defaults to @samp{"/var/log/cups/error_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string fatal-errors -Specifies which errors are fatal, causing the scheduler to exit. The kind -strings are: - -@table @code -@item none -No errors are fatal. - -@item all -All of the errors below are fatal. - -@item browse -Browsing initialization errors are fatal, for example failed connections to -the DNS-SD daemon. - -@item config -Configuration file syntax errors are fatal. - -@item listen -Listen or Port errors are fatal, except for IPv6 failures on the loopback or -@code{any} addresses. - -@item log -Log file creation or write errors are fatal. - -@item permissions -Bad startup file permissions are fatal, for example shared TLS certificate -and key files with world-read permissions. -@end table - -Defaults to @samp{"all -browse"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean file-device? -Specifies whether the file pseudo-device can be used for new printer -queues. The URI @uref{file:///dev/null} is always allowed. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string group -Specifies the group name or ID that will be used when executing external -programs. - -Defaults to @samp{"lp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string log-file-perm -Specifies the permissions for all log files that the scheduler writes. - -Defaults to @samp{"0644"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location page-log -Defines the page log filename. Specifying a blank filename disables access -log generation. The value @code{stderr} causes log entries to be sent to -the standard error file when the scheduler is running in the foreground, or -to the system log daemon when run in the background. The value -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-page_log}. - -Defaults to @samp{"/var/log/cups/page_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string remote-root -Specifies the username that is associated with unauthenticated accesses by -clients claiming to be the root user. The default is @code{remroot}. - -Defaults to @samp{"remroot"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name request-root -Specifies the directory that contains print jobs and other HTTP request -data. - -Defaults to @samp{"/var/spool/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing -Specifies the level of security sandboxing that is applied to print filters, -backends, and other child processes of the scheduler; either @code{relaxed} -or @code{strict}. This directive is currently only used/supported on macOS. - -Defaults to @samp{strict}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-keychain -Specifies the location of TLS certificates and private keys. CUPS will look -for public and private keys in this directory: a @code{.crt} files for -PEM-encoded certificates and corresponding @code{.key} files for PEM-encoded -private keys. - -Defaults to @samp{"/etc/cups/ssl"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-root -Specifies the directory containing the server configuration files. - -Defaults to @samp{"/etc/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean sync-on-close? -Specifies whether the scheduler calls fsync(2) after writing configuration -or state files. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group -Specifies the group(s) to use for @code{@@SYSTEM} group authentication. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name temp-dir -Specifies the directory where temporary files are stored. - -Defaults to @samp{"/var/spool/cups/tmp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string user -Specifies the user name or ID that is used when running external programs. - -Defaults to @samp{"lp"}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level -Specifies the logging level for the AccessLog file. The @code{config} level -logs when printers and classes are added, deleted, or modified and when -configuration files are accessed or updated. The @code{actions} level logs -when print jobs are submitted, held, released, modified, or canceled, and -any of the conditions for @code{config}. The @code{all} level logs all -requests. - -Defaults to @samp{actions}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs? -Specifies whether to purge job history data automatically when it is no -longer required for quotas. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols -Specifies which protocols to use for local printer sharing. - -Defaults to @samp{dnssd}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if? -Specifies whether the CUPS web interface is advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browsing? -Specifies whether shared printers are advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string classification -Specifies the security classification of the server. Any valid banner name -can be used, including "classified", "confidential", "secret", "topsecret", -and "unclassified", or the banner can be omitted to disable secure printing -functions. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean classify-override? -Specifies whether users may override the classification (cover page) of -individual print jobs using the @code{job-sheets} option. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type -Specifies the default type of authentication to use. - -Defaults to @samp{Basic}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption -Specifies whether encryption will be used for authenticated requests. - -Defaults to @samp{Required}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-language -Specifies the default language to use for text and web content. - -Defaults to @samp{"en"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-paper-size -Specifies the default paper size for new print queues. @samp{"Auto"} uses a -locale-specific default, while @samp{"None"} specifies there is no default -paper size. Specific size names are typically @samp{"Letter"} or -@samp{"A4"}. - -Defaults to @samp{"Auto"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-policy -Specifies the default access policy to use. - -Defaults to @samp{"default"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean default-shared? -Specifies whether local printers are shared by default. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval -Specifies the delay for updating of configuration and state files, in -seconds. A value of 0 causes the update to happen as soon as possible, -typically within a few milliseconds. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} error-policy error-policy -Specifies what to do when an error occurs. Possible values are -@code{abort-job}, which will discard the failed print job; @code{retry-job}, -which will retry the job at a later time; @code{retry-this-job}, which -retries the failed job immediately; and @code{stop-printer}, which stops the -printer. - -Defaults to @samp{stop-printer}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit -Specifies the maximum cost of filters that are run concurrently, which can -be used to minimize disk, memory, and CPU resource problems. A limit of 0 -disables filter limiting. An average print to a non-PostScript printer -needs a filter limit of about 200. A PostScript printer needs about half -that (100). Setting the limit below these thresholds will effectively limit -the scheduler to printing a single job at any time. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice -Specifies the scheduling priority of filters that are run to print a job. -The nice value ranges from 0, the highest priority, to 19, the lowest -priority. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups -Specifies whether to do reverse lookups on connecting clients. The -@code{double} setting causes @code{cupsd} to verify that the hostname -resolved from the address matches one of the addresses returned for that -hostname. Double lookups also prevent clients with unregistered addresses -from connecting to your server. Only set this option to @code{#t} or -@code{double} if absolutely required. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay -Specifies the number of seconds to wait before killing the filters and -backend associated with a canceled or held job. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval -Specifies the interval between retries of jobs in seconds. This is -typically used for fax queues but can also be used with normal print queues -whose error policy is @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit -Specifies the number of retries that are done for jobs. This is typically -used for fax queues but can also be used with normal print queues whose -error policy is @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{5}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean keep-alive? -Specifies whether to support HTTP keep-alive connections. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout -Specifies how long an idle client connection remains open, in seconds. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body -Specifies the maximum size of print files, IPP requests, and HTML form -data. A limit of 0 disables the limit check. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen -Listens on the specified interfaces for connections. Valid values are of -the form @var{address}:@var{port}, where @var{address} is either an IPv6 -address enclosed in brackets, an IPv4 address, or @code{*} to indicate all -addresses. Values can also be file names of local UNIX domain sockets. The -Listen directive is similar to the Port directive but allows you to restrict -access to specific interfaces or networks. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log -Specifies the number of pending connections that will be allowed. This -normally only affects very busy servers that have reached the MaxClients -limit, but can also be triggered by large numbers of simultaneous -connections. When the limit is reached, the operating system will refuse -additional connections until the scheduler can accept the pending ones. - -Defaults to @samp{128}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls -Specifies a set of additional access controls. - -Available @code{location-access-controls} fields are: - -@deftypevr {@code{location-access-controls} parameter} file-name path -Specifies the URI path to which the access control applies. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls -Access controls for all access to this path, in the same format as the -@code{access-controls} of @code{operation-access-control}. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls -Access controls for method-specific access to this path. - -Defaults to @samp{()}. - -Available @code{method-access-controls} fields are: - -@deftypevr {@code{method-access-controls} parameter} boolean reverse? -If @code{#t}, apply access controls to all methods except the listed -methods. Otherwise apply to only the listed methods. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{method-access-controls} parameter} method-list methods -Methods to which this access control applies. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls -Access control directives, as a list of strings. Each string should be one -directive, such as "Order allow,deny". - -Defaults to @samp{()}. -@end deftypevr -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history -Specifies the number of debugging messages that are retained for logging if -an error occurs in a print job. Debug messages are logged regardless of the -LogLevel setting. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-level log-level -Specifies the level of logging for the ErrorLog file. The value @code{none} -stops all logging while @code{debug2} logs everything. - -Defaults to @samp{info}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format -Specifies the format of the date and time in the log files. The value -@code{standard} logs whole seconds while @code{usecs} logs microseconds. - -Defaults to @samp{standard}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients -Specifies the maximum number of simultaneous clients that are allowed by the -scheduler. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host -Specifies the maximum number of simultaneous clients that are allowed from a -single address. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies -Specifies the maximum number of copies that a user can print of each job. - -Defaults to @samp{9999}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time -Specifies the maximum time a job may remain in the @code{indefinite} hold -state before it is canceled. A value of 0 disables cancellation of held -jobs. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs -Specifies the maximum number of simultaneous jobs that are allowed. Set to -0 to allow an unlimited number of jobs. - -Defaults to @samp{500}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer -Specifies the maximum number of simultaneous jobs that are allowed per -printer. A value of 0 allows up to MaxJobs jobs per printer. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user -Specifies the maximum number of simultaneous jobs that are allowed per -user. A value of 0 allows up to MaxJobs jobs per user. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time -Specifies the maximum time a job may take to print before it is canceled, in -seconds. Set to 0 to disable cancellation of "stuck" jobs. - -Defaults to @samp{10800}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size -Specifies the maximum size of the log files before they are rotated, in -bytes. The value 0 disables log rotation. - -Defaults to @samp{1048576}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout -Specifies the maximum amount of time to allow between files in a multiple -file print job, in seconds. - -Defaults to @samp{300}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string page-log-format -Specifies the format of PageLog lines. Sequences beginning with percent -(@samp{%}) characters are replaced with the corresponding information, while -all other characters are copied literally. The following percent sequences -are recognized: - -@table @samp -@item %% -insert a single percent character - -@item %@{name@} -insert the value of the specified IPP attribute - -@item %C -insert the number of copies for the current page - -@item %P -insert the current page number - -@item %T -insert the current date and time in common log format - -@item %j -insert the job ID - -@item %p -insert the printer name - -@item %u -insert the username -@end table - -A value of the empty string disables page logging. The string @code{%p %u -%j %T %P %C %@{job-billing@} %@{job-originating-host-name@} %@{job-name@} -%@{media@} %@{sides@}} creates a page log with the standard items. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables -Passes the specified environment variable(s) to child processes; a list of -strings. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies -Specifies named access control policies. - -Available @code{policy-configuration} fields are: - -@deftypevr {@code{policy-configuration} parameter} string name -Name of the policy. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-access -Specifies an access list for a job's private values. @code{@@ACL} maps to -the printer's requesting-user-name-allowed or requesting-user-name-denied -values. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps to -the groups listed for the @code{system-group} field of the -@code{files-config} configuration, which is reified into the -@code{cups-files.conf(5)} file. Other possible elements of the access list -include specific user names, and @code{@@@var{group}} to indicate members of -a specific group. The access list may also be simply @code{all} or -@code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"job-name job-originating-host-name -job-originating-user-name phone"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-access -Specifies an access list for a subscription's private values. @code{@@ACL} -maps to the printer's requesting-user-name-allowed or -requesting-user-name-denied values. @code{@@OWNER} maps to the job's -owner. @code{@@SYSTEM} maps to the groups listed for the -@code{system-group} field of the @code{files-config} configuration, which is -reified into the @code{cups-files.conf(5)} file. Other possible elements of -the access list include specific user names, and @code{@@@var{group}} to -indicate members of a specific group. The access list may also be simply -@code{all} or @code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri -notify-subscriber-user-name notify-user-data"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls -Access control by IPP operation. - -Defaults to @samp{()}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files -Specifies whether job files (documents) are preserved after a job is -printed. If a numeric value is specified, job files are preserved for the -indicated number of seconds after printing. Otherwise a boolean value -applies indefinitely. - -Defaults to @samp{86400}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history -Specifies whether the job history is preserved after a job is printed. If a -numeric value is specified, the job history is preserved for the indicated -number of seconds after printing. If @code{#t}, the job history is -preserved until the MaxJobs limit is reached. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout -Specifies the amount of time to wait for job completion before restarting -the scheduler. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string rip-cache -Specifies the maximum amount of memory to use when converting documents into -bitmaps for a printer. - -Defaults to @samp{"128m"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-admin -Specifies the email address of the server administrator. - -Defaults to @samp{"root@@localhost.localdomain"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias -The ServerAlias directive is used for HTTP Host header validation when -clients connect to the scheduler from external interfaces. Using the -special name @code{*} can expose your system to known browser-based DNS -rebinding attacks, even when accessing sites through a firewall. If the -auto-discovery of alternate names does not work, we recommend listing each -alternate name with a ServerAlias directive instead of using @code{*}. - -Defaults to @samp{*}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-name -Specifies the fully-qualified host name of the server. - -Defaults to @samp{"localhost"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens -Specifies what information is included in the Server header of HTTP -responses. @code{None} disables the Server header. @code{ProductOnly} -reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor} -reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}. -@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the -output of the @code{uname} command. @code{Full} reports @code{CUPS 2.0.0 -(@var{uname}) IPP/2.0}. - -Defaults to @samp{Minimal}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string set-env -Set the specified environment variable to be passed to child processes. - -Defaults to @samp{"variable value"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen -Listens on the specified interfaces for encrypted connections. Valid values -are of the form @var{address}:@var{port}, where @var{address} is either an -IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate -all addresses. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options -Sets encryption options. By default, CUPS only supports encryption using -TLS v1.0 or higher using known secure cipher suites. The @code{AllowRC4} -option enables the 128-bit RC4 cipher suites, which are required for some -older clients that do not implement newer ones. The @code{AllowSSL3} option -enables SSL v3.0, which is required for some older clients that do not -support TLS v1.0. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance? -Specifies whether the scheduler requires clients to strictly adhere to the -IPP specifications. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout -Specifies the HTTP request timeout, in seconds. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean web-interface? -Specifies whether the web interface is enabled. - -Defaults to @samp{#f}. -@end deftypevr - -At this point you're probably thinking ``oh dear, Guix manual, I like you -but you can stop already with the configuration options''. Indeed. -However, one more point: it could be that you have an existing -@code{cupsd.conf} that you want to use. In that case, you can pass an -@code{opaque-cups-configuration} as the configuration of a -@code{cups-service-type}. - -Available @code{opaque-cups-configuration} fields are: - -@deftypevr {@code{opaque-cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf -The contents of the @code{cupsd.conf}, as a string. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf -The contents of the @code{cups-files.conf} file, as a string. -@end deftypevr - -For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in -strings of the same name, you could instantiate a CUPS service like this: - -@example -(service cups-service-type - (opaque-cups-configuration - (cupsd.conf cupsd.conf) - (cups-files.conf cups-files.conf))) -@end example - - -@node Desktop-Dienste -@subsection Desktop-Dienste - -The @code{(gnu services desktop)} module provides services that are usually -useful in the context of a ``desktop'' setup---that is, on a machine running -a graphical display server, possibly with graphical user interfaces, etc. -It also defines services that provide specific desktop environments like -GNOME, XFCE or MATE. - -To simplify things, the module defines a variable containing the set of -services that users typically expect on a machine with a graphical -environment and networking: - -@defvr {Scheme Variable} %desktop-services -This is a list of services that builds upon @var{%base-services} and adds or -adjusts services for a typical ``desktop'' setup. - -In particular, it adds a graphical login manager (@pxref{X Window, -@code{slim-service}}), screen lockers, a network management tool -(@pxref{Netzwerkdienste, @code{network-manager-service-type}}), energy -and color management services, the @code{elogind} login and seat manager, -the Polkit privilege service, the GeoClue location service, the -AccountsService daemon that allows authorized users change system passwords, -an NTP client (@pxref{Netzwerkdienste}), the Avahi daemon, and has the -name service switch service configured to be able to use @code{nss-mdns} -(@pxref{Name Service Switch, mDNS}). -@end defvr - -The @var{%desktop-services} variable can be used as the @code{services} -field of an @code{operating-system} declaration (@pxref{»operating-system«-Referenz, @code{services}}). - -Additionally, the @code{gnome-desktop-service}, @code{xfce-desktop-service}, -@code{mate-desktop-service-type} and -@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, -MATE and/or Enlightenment to a system. To ``add GNOME'' means that -system-level services like the backlight adjustment helpers and the power -management utilities are added to the system, extending @code{polkit} and -@code{dbus} appropriately, allowing GNOME to operate with elevated -privileges on a limited number of special-purpose system interfaces. -Additionally, adding a service made by @code{gnome-desktop-service} adds the -GNOME metapackage to the system profile. Likewise, adding the XFCE service -not only adds the @code{xfce} metapackage to the system profile, but it also -gives the Thunar file manager the ability to open a ``root-mode'' file -management window, if the user authenticates using the administrator's -password via the standard polkit graphical interface. To ``add MATE'' means -that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE -to operate with elevated privileges on a limited number of special-purpose -system interfaces. Additionally, adding a service of type -@code{mate-desktop-service-type} adds the MATE metapackage to the system -profile. ``Adding Enlightenment'' means that @code{dbus} is extended -appropriately, and several of Enlightenment's binaries are set as setuid, -allowing Enlightenment's screen locker and other functionality to work as -expetected. - -The desktop environments in Guix use the Xorg display server by default. If -you'd like to use the newer display server protocol called Wayland, you need -to use the @code{sddm-service} instead of the @code{slim-service} for the -graphical login manager. You should then select the ``GNOME (Wayland)'' -session in SDDM. Alternatively you can also try starting GNOME on Wayland -manually from a TTY with the command ``XDG_SESSION_TYPE=wayland exec -dbus-run-session gnome-session``. Currently only GNOME has support for -Wayland. - -@deffn {Scheme Procedure} gnome-desktop-service -Return a service that adds the @code{gnome} package to the system profile, -and extends polkit with the actions from @code{gnome-settings-daemon}. -@end deffn - -@deffn {Scheme Procedure} xfce-desktop-service -Return a service that adds the @code{xfce} package to the system profile, -and extends polkit with the ability for @code{thunar} to manipulate the file -system as root from within a user session, after the user has authenticated -with the administrator's password. -@end deffn - -@deffn {Scheme Variable} mate-desktop-service-type -This is the type of the service that runs the -@uref{https://mate-desktop.org/, MATE desktop environment}. Its value is a -@code{mate-desktop-configuration} object (see below.) - -This service adds the @code{mate} package to the system profile, and extends -polkit with the actions from @code{mate-settings-daemon}. -@end deffn - -@deftp {Data Type} mate-desktop-configuration -Configuration record for the MATE desktop environment. - -@table @asis -@item @code{mate} (default @code{mate}) -The MATE package to use. -@end table -@end deftp - -@deffn {Scheme Variable} enlightenment-desktop-service-type -Return a service that adds the @code{enlightenment} package to the system -profile, and extends dbus with actions from @code{efl}. -@end deffn - -@deftp {Data Type} enlightenment-desktop-service-configuration -@table @asis -@item @code{enlightenment} (Vorgabe: @code{enlightenment}) -Das Enlightenment-Paket, was benutzt werden soll. -@end table -@end deftp - -Because the GNOME, XFCE and MATE desktop services pull in so many packages, -the default @code{%desktop-services} variable doesn't include any of them by -default. To add GNOME, XFCE or MATE, just @code{cons} them onto -@code{%desktop-services} in the @code{services} field of your -@code{operating-system}: - -@example -(use-modules (gnu)) -(use-service-modules desktop) -(operating-system - ... - ;; cons* adds items to the list given as its last argument. - (services (cons* (gnome-desktop-service) - (xfce-desktop-service) - %desktop-services)) - ...) -@end example - -These desktop environments will then be available as options in the -graphical login window. - -The actual service definitions included in @code{%desktop-services} and -provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are -described below. - -@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] -Return a service that runs the ``system bus'', using @var{dbus}, with -support for @var{services}. - -@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication -facility. Its system bus is used to allow system services to communicate -and to be notified of system-wide events. - -@var{services} must be a list of packages that provide an -@file{etc/dbus-1/system.d} directory containing additional D-Bus -configuration and policy files. For example, to allow avahi-daemon to use -the system bus, @var{services} must be equal to @code{(list avahi)}. -@end deffn - -@deffn {Scheme Procedure} elogind-service [#:config @var{config}] -Return a service that runs the @code{elogind} login and seat management -daemon. @uref{https://github.com/elogind/elogind, Elogind} exposes a D-Bus -interface that can be used to know which users are logged in, know what kind -of sessions they have open, suspend the system, inhibit system suspend, -reboot the system, and other tasks. - -Elogind handles most system-level power events for a computer, for example -suspending the system when a lid is closed, or shutting it down when the -power button is pressed. - -The @var{config} keyword argument specifies the configuration for elogind, -and should be the result of an @code{(elogind-configuration (@var{parameter} -@var{value})...)} invocation. Available parameters and their default values -are: - -@table @code -@item kill-user-processes? -@code{#f} -@item kill-only-users -@code{()} -@item kill-exclude-users -@code{("root")} -@item inhibit-delay-max-seconds -@code{5} -@item handle-power-key -@code{poweroff} -@item handle-suspend-key -@code{suspend} -@item handle-hibernate-key -@code{hibernate} -@item handle-lid-switch -@code{suspend} -@item handle-lid-switch-docked -@code{ignore} -@item power-key-ignore-inhibited? -@code{#f} -@item suspend-key-ignore-inhibited? -@code{#f} -@item hibernate-key-ignore-inhibited? -@code{#f} -@item lid-switch-ignore-inhibited? -@code{#t} -@item holdoff-timeout-seconds -@code{30} -@item idle-action -@code{ignore} -@item idle-action-seconds -@code{(* 30 60)} -@item runtime-directory-size-percent -@code{10} -@item runtime-directory-size -@code{#f} -@item remove-ipc? -@code{#t} -@item suspend-state -@code{("mem" "standby" "freeze")} -@item suspend-mode -@code{()} -@item hibernate-state -@code{("disk")} -@item hibernate-mode -@code{("platform" "shutdown")} -@item hybrid-sleep-state -@code{("disk")} -@item hybrid-sleep-mode -@code{("suspend" "platform" "shutdown")} -@end table -@end deffn - -@deffn {Scheme Procedure} accountsservice-service @ - [#:accountsservice @var{accountsservice}] Return a service that runs -AccountsService, a system service that can list available accounts, change -their passwords, and so on. AccountsService integrates with PolicyKit to -enable unprivileged users to acquire the capability to modify their system -configuration. -@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the -accountsservice web site} for more information. - -The @var{accountsservice} keyword argument is the @code{accountsservice} -package to expose as a service. -@end deffn - -@deffn {Scheme Procedure} polkit-service @ - [#:polkit @var{polkit}] Return a service that runs the -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege -management service}, which allows system administrators to grant access to -privileged operations in a structured way. By querying the Polkit service, -a privileged system component can know when it should grant additional -capabilities to ordinary users. For example, an ordinary user can be -granted the capability to suspend the system if the user is logged in -locally. -@end deffn - -@defvr {Scheme Variable} upower-service-type -Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, -a system-wide monitor for power consumption and battery levels, with the -given configuration settings. - -It implements the @code{org.freedesktop.UPower} D-Bus interface, and is -notably used by GNOME. -@end defvr - -@deftp {Data Type} upower-configuration -Data type representation the configuration for UPower. - -@table @asis - -@item @code{upower} (default: @var{upower}) -Package to use for @code{upower}. - -@item @code{watts-up-pro?} (default: @code{#f}) -Enable the Watts Up Pro device. - -@item @code{poll-batteries?} (default: @code{#t}) -Enable polling the kernel for battery level changes. - -@item @code{ignore-lid?} (default: @code{#f}) -Ignore the lid state, this can be useful if it's incorrect on a device. - -@item @code{use-percentage-for-policy?} (default: @code{#f}) -Whether battery percentage based policy should be used. The default is to -use the time left, change to @code{#t} to use the percentage. - -@item @code{percentage-low} (default: @code{10}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered low. - -@item @code{percentage-critical} (default: @code{3}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered critical. - -@item @code{percentage-action} (default: @code{2}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which action will be taken. - -@item @code{time-low} (default: @code{1200}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered low. - -@item @code{time-critical} (default: @code{300}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered critical. - -@item @code{time-action} (default: @code{120}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which action will be taken. - -@item @code{critical-power-action} (default: @code{'hybrid-sleep}) -The action taken when @code{percentage-action} or @code{time-action} is -reached (depending on the configuration of -@code{use-percentage-for-policy?}). - -Possible values are: - -@itemize @bullet -@item -@code{'power-off} - -@item -@code{'hibernate} - -@item -@code{'hybrid-sleep}. -@end itemize - -@end table -@end deftp - -@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, -UDisks}, a @dfn{disk management} daemon that provides user interfaces with -notifications and ways to mount/unmount disks. Programs that talk to UDisks -include the @command{udisksctl} command, part of UDisks, and GNOME Disks. -@end deffn - -@deffn {Scheme Procedure} colord-service [#:colord @var{colord}] -Return a service that runs @command{colord}, a system service with a D-Bus -interface to manage the color profiles of input and output devices such as -screens and scanners. It is notably used by the GNOME Color Manager -graphical tool. See @uref{http://www.freedesktop.org/software/colord/, the -colord web site} for more information. -@end deffn - -@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] -Return a configuration allowing an application to access GeoClue location -data. @var{name} is the Desktop ID of the application, without the -@code{.desktop} part. If @var{allowed?} is true, the application will have -access to location information by default. The boolean @var{system?} value -indicates whether an application is a system component or not. Finally -@var{users} is a list of UIDs of all users for which this application is -allowed location info access. An empty users list means that all users are -allowed. -@end deffn - -@defvr {Scheme Variable} %standard-geoclue-applications -The standard list of well-known GeoClue application configurations, granting -authority to the GNOME date-and-time utility to ask for the current location -in order to set the time zone, and allowing the IceCat and Epiphany web -browsers to request location information. IceCat and Epiphany both query -the user before allowing a web page to know the user's location. -@end defvr - -@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ - [#:whitelist '()] @ [#:wifi-geolocation-url -"https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ -[#:submit-data? #f] [#:wifi-submission-url -"https://location.services.mozilla.com/v1/submit?key=geoclue"] @ -[#:submission-nick "geoclue"] @ [#:applications -%standard-geoclue-applications] Return a service that runs the GeoClue -location service. This service provides a D-Bus interface to allow -applications to request access to a user's physical location, and optionally -to add information to online location databases. See -@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue web -site} for more information. -@end deffn - -@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @ - [@w{#:auto-enable? #f}] Return a service that runs the @command{bluetoothd} -daemon, which manages all the Bluetooth devices and provides a number of -D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is -powered automatically at boot, which can be useful when using a bluetooth -keyboard or mouse. - -Users need to be in the @code{lp} group to access the D-Bus service. -@end deffn - -@node Tondienste -@subsection Tondienste - -@cindex sound support -@cindex ALSA -@cindex PulseAudio, sound support - -The @code{(gnu services sound)} module provides a service to configure the -Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the -preferred ALSA output driver. - -@deffn {Scheme Variable} alsa-service-type -This is the type for the @uref{https://alsa-project.org/, Advanced Linux -Sound Architecture} (ALSA) system, which generates the -@file{/etc/asound.conf} configuration file. The value for this type is a -@command{alsa-configuration} record as in this example: - -@example -(service alsa-service-type) -@end example - -See below for details about @code{alsa-configuration}. -@end deffn - -@deftp {Datentyp} alsa-configuration -Repräsentiert die Konfiguration für den Dienst @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (Vorgabe: @var{alsa-plugins}) -@code{alsa-plugins}-Paket, was benutzt werden soll. - -@item @code{pulseaudio?} (Vorgabe: @var{#t}) -Whether ALSA applications should transparently be made to use the -@uref{http://www.pulseaudio.org/, PulseAudio} sound server. - -Using PulseAudio allows you to run several sound-producing applications at -the same time and to individual control them @i{via} @command{pavucontrol}, -among other things. - -@item @code{extra-options} (Vorgabe: @var{""}) -String to append to the @file{/etc/asound.conf} file. - -@end table -@end deftp - -Individual users who want to override the system configuration of ALSA can -do it with the @file{~/.asoundrc} file: - -@example -# In guix, we have to specify the absolute path for plugins. -pcm_type.jack @{ - lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so" -@} - -# Routing ALSA to jack: -# <http://jackaudio.org/faq/routing_alsa.html>. -pcm.rawjack @{ - type jack - playback_ports @{ - 0 system:playback_1 - 1 system:playback_2 - @} - - capture_ports @{ - 0 system:capture_1 - 1 system:capture_2 - @} -@} - -pcm.!default @{ - type plug - slave @{ - pcm "rawjack" - @} -@} -@end example - -See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the -details. - - -@node Datenbankdienste -@subsection Datenbankdienste - -@cindex Datenbank -@cindex SQL -The @code{(gnu services databases)} module provides the following services. - -@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @ - [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ [#:port -5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] Return a service -that runs @var{postgresql}, the PostgreSQL database server. - -The PostgreSQL daemon loads its runtime configuration from -@var{config-file}, creates a database cluster with @var{locale} as the -default locale, stored in @var{data-directory}. It then listens on -@var{port}. - -@cindex postgresql extension-packages -Additional extensions are loaded from packages listed in -@var{extension-packages}. Extensions are available at runtime. For -instance, to create a geographic database using the @code{postgis} -extension, a user can configure the postgresql-service as in this example: - -@cindex postgis -@example -(use-package-modules databases geo) - -(operating-system - ... - ;; postgresql is required to run `psql' but postgis is not required for - ;; proper operation. - (packages (cons* postgresql %base-packages)) - (services - (cons* - (postgresql-service #:extension-packages (list postgis)) - %base-services))) -@end example - -Then the extension becomes visible and you can initialise an empty -geographic database in this way: - -@example -psql -U postgres -> create database postgistest; -> \connect postgistest; -> create extension postgis; -> create extension postgis_topology; -@end example - -There is no need to add this field for contrib extensions such as hstore or -dblink as they are already loadable by postgresql. This field is only -required to add extensions provided by other packages. -@end deffn - -@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)] -Return a service that runs @command{mysqld}, the MySQL or MariaDB database -server. - -The optional @var{config} argument specifies the configuration for -@command{mysqld}, which should be a @code{<mysql-configuration>} object. -@end deffn - -@deftp {Data Type} mysql-configuration -Data type representing the configuration of @var{mysql-service}. - -@table @asis -@item @code{mysql} (default: @var{mariadb}) -Package object of the MySQL database server, can be either @var{mariadb} or -@var{mysql}. - -For MySQL, a temporary root password will be displayed at activation time. -For MariaDB, the root password is empty. - -@item @code{port} (default: @code{3306}) -TCP port on which the database server listens for incoming connections. -@end table -@end deftp - -@defvr {Scheme Variable} memcached-service-type -This is the service type for the @uref{https://memcached.org/, Memcached} -service, which provides a distributed in memory cache. The value for the -service type is a @code{memcached-configuration} object. -@end defvr - -@example -(service memcached-service-type) -@end example - -@deftp {Data Type} memcached-configuration -Data type representing the configuration of memcached. - -@table @asis -@item @code{memcached} (default: @code{memcached}) -The Memcached package to use. - -@item @code{interfaces} (default: @code{'("0.0.0.0")}) -Network interfaces on which to listen. - -@item @code{tcp-port} (default: @code{11211}) -Port on which to accept connections on, - -@item @code{udp-port} (default: @code{11211}) -Port on which to accept UDP connections on, a value of 0 will disable -listening on a UDP socket. - -@item @code{additional-options} (default: @code{'()}) -Additional command line options to pass to @code{memcached}. -@end table -@end deftp - -@defvr {Scheme Variable} mongodb-service-type -This is the service type for @uref{https://www.mongodb.com/, MongoDB}. The -value for the service type is a @code{mongodb-configuration} object. -@end defvr - -@example -(service mongodb-service-type) -@end example - -@deftp {Data Type} mongodb-configuration -Data type representing the configuration of mongodb. - -@table @asis -@item @code{mongodb} (default: @code{mongodb}) -The MongoDB package to use. - -@item @code{config-file} (default: @code{%default-mongodb-configuration-file}) -The configuration file for MongoDB. - -@item @code{data-directory} (default: @code{"/var/lib/mongodb"}) -This value is used to create the directory, so that it exists and is owned -by the mongodb user. It should match the data-directory which MongoDB is -configured to use through the configuration file. -@end table -@end deftp - -@defvr {Scheme Variable} redis-service-type -This is the service type for the @uref{https://redis.io/, Redis} key/value -store, whose value is a @code{redis-configuration} object. -@end defvr - -@deftp {Data Type} redis-configuration -Data type representing the configuration of redis. - -@table @asis -@item @code{redis} (default: @code{redis}) -The Redis package to use. - -@item @code{bind} (default: @code{"127.0.0.1"}) -Network interface on which to listen. - -@item @code{port} (default: @code{6379}) -Port on which to accept connections on, a value of 0 will disable listening -on a TCP socket. - -@item @code{working-directory} (default: @code{"/var/lib/redis"}) -Directory in which to store the database and related files. -@end table -@end deftp - -@node Mail-Dienste -@subsection Mail-Dienste - -@cindex mail -@cindex email -The @code{(gnu services mail)} module provides Guix service definitions for -email services: IMAP, POP3, and LMTP servers, as well as mail transport -agents (MTAs). Lots of acronyms! These services are detailed in the -subsections below. - -@subsubheading Dovecot Service - -@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)] -Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. -@end deffn - -By default, Dovecot does not need much configuration; the default -configuration object created by @code{(dovecot-configuration)} will suffice -if your mail is delivered to @code{~/Maildir}. A self-signed certificate -will be generated for TLS-protected connections, though Dovecot will also -listen on cleartext ports by default. There are a number of options, -though, which mail administrators might need to change, and as is the case -with other services, Guix allows the system administrator to specify these -parameters via a uniform Scheme interface. - -For example, to specify that mail is located at @code{maildir~/.mail}, one -would instantiate the Dovecot service like this: - -@example -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.mail"))) -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. There is -also a way to specify the configuration as a string, if you have an old -@code{dovecot.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services mail). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as dovecot updates. - -Available @code{dovecot-configuration} fields are: - -@deftypevr {@code{dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen -A list of IPs or hosts where to listen for connections. @samp{*} listens on -all IPv4 interfaces, @samp{::} listens on all IPv6 interfaces. If you want -to specify non-default ports or anything more complex, customize the address -and port fields of the @samp{inet-listener} of the specific services you are -interested in. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols -List of protocols we want to serve. Available protocols include -@samp{imap}, @samp{pop3}, and @samp{lmtp}. - -Available @code{protocol-configuration} fields are: - -@deftypevr {@code{protocol-configuration} parameter} string name -The name of the protocol. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path -UNIX socket path to the master authentication server to find users. This is -used by imap (for shared users) and lda. It defaults to -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins -Space separated list of plugins to load. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections -Maximum number of IMAP connections allowed for a user from each IP address. -NOTE: The username is compared case-sensitively. Defaults to @samp{10}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services -List of services to enable. Available services include @samp{imap}, -@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and -@samp{lmtp}. - -Available @code{service-configuration} fields are: - -@deftypevr {@code{service-configuration} parameter} string kind -The service kind. Valid values include @code{director}, @code{imap-login}, -@code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth}, -@code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or -anything else. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners -Listeners for the service. A listener is either a -@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or -an @code{inet-listener-configuration}. Defaults to @samp{()}. - -Available @code{unix-listener-configuration} fields are: - -@deftypevr {@code{unix-listener-configuration} parameter} string path -Path to the file, relative to @code{base-dir} field. This is also used as -the section name. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string mode -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{fifo-listener-configuration} fields are: - -@deftypevr {@code{fifo-listener-configuration} parameter} string path -Path to the file, relative to @code{base-dir} field. This is also used as -the section name. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string mode -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{inet-listener-configuration} fields are: - -@deftypevr {@code{inet-listener-configuration} parameter} string protocol -The protocol to listen for. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} string address -The address on which to listen, or empty for all addresses. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port -The port on which to listen. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl? -Whether to use SSL for this service; @samp{yes}, @samp{no}, or -@samp{required}. Defaults to @samp{#t}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit -Maximum number of simultaneous client connections per process. Once this -number of connections is received, the next incoming connection will prompt -Dovecot to spawn another process. If set to 0, @code{default-client-limit} -is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count -Number of connections to handle before starting a new process. Typically -the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is -faster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit -Maximum number of processes that can exist for this service. If set to 0, -@code{default-process-limit} is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail -Number of processes to always keep waiting for more connections. Defaults -to @samp{0}. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit -If you set @samp{service-count 0}, you probably need to grow this. Defaults -to @samp{256000000}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict -Dict configuration, as created by the @code{dict-configuration} constructor. - -Available @code{dict-configuration} fields are: - -@deftypevr {@code{dict-configuration} parameter} free-form-fields entries -A list of key-value pairs that this dict should hold. Defaults to -@samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs -A list of passdb configurations, each one created by the -@code{passdb-configuration} constructor. - -Available @code{passdb-configuration} fields are: - -@deftypevr {@code{passdb-configuration} parameter} string driver -The driver that the passdb should use. Valid values include @samp{pam}, -@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaults -to @samp{"pam"}. -@end deftypevr - -@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args -Space separated list of arguments to the passdb driver. Defaults to -@samp{""}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs -List of userdb configurations, each one created by the -@code{userdb-configuration} constructor. - -Available @code{userdb-configuration} fields are: - -@deftypevr {@code{userdb-configuration} parameter} string driver -The driver that the userdb should use. Valid values include @samp{passwd} -and @samp{static}. Defaults to @samp{"passwd"}. -@end deftypevr - -@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args -Space separated list of arguments to the userdb driver. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields -Override fields from passwd. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration -Plug-in configuration, created by the @code{plugin-configuration} -constructor. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces -List of namespaces. Each item in the list is created by the -@code{namespace-configuration} constructor. - -Available @code{namespace-configuration} fields are: - -@deftypevr {@code{namespace-configuration} parameter} string name -Name for this namespace. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string type -Namespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to -@samp{"private"}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string separator -Hierarchy separator to use. You should use the same separator for all -namespaces or some clients get confused. @samp{/} is usually a good one. -The default however depends on the underlying mail storage format. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string prefix -Prefix required to access this namespace. This needs to be different for -all namespaces. For example @samp{Public/}. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string location -Physical location of the mailbox. This is in the same format as -mail_location, which is also the default for it. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean inbox? -There can be only one INBOX, and this setting defines which namespace has -it. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean hidden? -If namespace is hidden, it's not advertised to clients via NAMESPACE -extension. You'll most likely also want to set @samp{list? #f}. This is -mostly useful when converting from another server with different namespaces -which you want to deprecate but still keep working. For example you can -create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} and -@samp{mail/}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean list? -Show the mailboxes under this namespace with the LIST command. This makes -the namespace visible for clients that do not support the NAMESPACE -extension. The special @code{children} value lists child mailboxes, but -hides the namespace prefix. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions? -Namespace handles its own subscriptions. If set to @code{#f}, the parent -namespace handles them. The empty prefix should always have this as -@code{#t}). Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes -List of predefined mailboxes in this namespace. Defaults to @samp{()}. - -Available @code{mailbox-configuration} fields are: - -@deftypevr {@code{mailbox-configuration} parameter} string name -Name for this mailbox. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} string auto -@samp{create} will automatically create this mailbox. @samp{subscribe} will -both create and subscribe to the mailbox. Defaults to @samp{"no"}. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use -List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Valid -values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged}, -@code{\Junk}, @code{\Sent}, and @code{\Trash}. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir -Base directory where to store runtime data. Defaults to -@samp{"/var/run/dovecot/"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-greeting -Greeting message for clients. Defaults to @samp{"Dovecot ready."}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks -List of trusted network ranges. Connections from these IPs are allowed to -override their IP addresses and ports (for logging and for authentication -checks). @samp{disable-plaintext-auth} is also ignored for these networks. -Typically you would specify your IMAP proxy servers here. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets -List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? -Show more verbose process titles (in ps). Currently shows user name and IP -address. Useful for seeing who is actually using the IMAP processes (e.g.@: -shared mailboxes or if the same uid is used for multiple accounts). -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients? -Should all processes be killed when Dovecot master process shuts down. -Setting this to @code{#f} means that Dovecot can be upgraded without forcing -existing client connections to close (although that could also be a problem -if the upgrade is e.g.@: due to a security fix). Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count -If non-zero, run mail commands via this many connections to doveadm server, -instead of running them directly in the same process. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path -UNIX socket or host:port used for connecting to doveadm server. Defaults to -@samp{"doveadm-server"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment -List of environment variables that are preserved on Dovecot startup and -passed down to all of its child processes. You can also give key=value -pairs to always set specific settings. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth? -Disable LOGIN command and all other plaintext authentications unless SSL/TLS -is used (LOGINDISABLED capability). Note that if the remote IP matches the -local IP (i.e.@: you're connecting from the same computer), the connection -is considered secure and plaintext authentication is allowed. See also -ssl=required setting. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size -Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled. -Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for -caching to be used. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl -Time to live for cached data. After TTL expires the cached record is no -longer used, *except* if the main database lookup returns internal failure. -We also try to handle password changes automatically: If user's previous -authentication was successful, but this one wasn't, the cache isn't used. -For now this works only with plaintext authentication. Defaults to @samp{"1 -hour"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl -TTL for negative hits (user not found, password mismatch). 0 disables -caching them completely. Defaults to @samp{"1 hour"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms -List of realms for SASL authentication mechanisms that need them. You can -leave it empty if you don't want to support multiple realms. Many clients -simply use the first one listed here, so keep the default realm first. -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm -Default realm/domain to use if none was specified. This is used for both -SASL realms and appending @@domain to username in plaintext logins. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars -List of allowed characters in username. If the user-given username contains -a character not listed in here, the login automatically fails. This is just -an extra check to make sure user can't exploit any potential quote escaping -vulnerabilities with SQL/LDAP databases. If you want to allow all -characters, set this value to empty. Defaults to -@samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation -Username character translations before it's looked up from databases. The -value contains series of from -> to characters. For example @samp{#@@/@@} -means that @samp{#} and @samp{/} characters are translated to @samp{@@}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format -Username formatting before it's looked up from databases. You can use the -standard variables here, e.g.@: %Lu would lowercase the username, %n would -drop away the domain if it was given, or @samp{%n-AT-%d} would change the -@samp{@@} into @samp{-AT-}. This translation is done after -@samp{auth-username-translation} changes. Defaults to @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator -If you want to allow master users to log in by specifying the master -username within the normal username string (i.e.@: not using SASL -mechanism's support for it), you can specify the separator character here. -The format is then <username><separator><master username>. UW-IMAP uses -@samp{*} as the separator, so that could be a good choice. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username -Username to use for users logging in with ANONYMOUS SASL mechanism. -Defaults to @samp{"anonymous"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count -Maximum number of dovecot-auth worker processes. They're used to execute -blocking passdb and userdb queries (e.g.@: MySQL and PAM). They're -automatically created and destroyed as needed. Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname -Host name to use in GSSAPI principal names. The default is to use the name -returned by gethostname(). Use @samp{$ALL} (with quotes) to allow all -keytab entries. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab -Kerberos keytab to use for the GSSAPI mechanism. Will use the system -default (usually @file{/etc/krb5.keytab}) if not specified. You may need to -change the auth service to run as root to be able to read this file. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind? -Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and -@samp{ntlm-auth} helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path -Path for Samba's @samp{ntlm-auth} helper binary. Defaults to -@samp{"/usr/bin/ntlm_auth"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay -Time to delay before replying to failed authentications. Defaults to -@samp{"2 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert? -Require a valid SSL client certificate or the authentication fails. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert? -Take the username from client's SSL certificate, using -@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's -CommonName. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms -List of wanted authentication mechanisms. Supported mechanisms are: -@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm}, -@samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, @samp{otp}, -@samp{skey}, and @samp{gss-spnego}. NOTE: See also -@samp{disable-plaintext-auth} setting. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers -List of IPs or hostnames to all director servers, including ourself. Ports -can be specified as ip:port. The default port is the same as what director -service's @samp{inet-listener} is using. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers -List of IPs or hostnames to all backend mail servers. Ranges are allowed -too, like 10.0.0.10-10.0.0.30. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire -How long to redirect users to a specific server after it no longer has any -connections. Defaults to @samp{"15 min"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash -How the username is translated before being hashed. Useful values include -%Ln if user can log in with or without @@domain, %Ld if mailboxes are shared -within domain. Defaults to @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-path -Log file to use for error messages. @samp{syslog} logs to syslog, -@samp{/dev/stderr} logs to stderr. Defaults to @samp{"syslog"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string info-log-path -Log file to use for informational messages. Defaults to @samp{log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path -Log file to use for debug messages. Defaults to @samp{info-log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility -Syslog facility to use if you're logging to syslog. Usually if you don't -want to use @samp{mail}, you'll use local0..local7. Also other standard -facilities are supported. Defaults to @samp{"mail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose? -Log unsuccessful authentication attempts and the reasons why they failed. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? -In case of password mismatches, log the attempted password. Valid values -are no, plain and sha1. sha1 can be useful for detecting brute force -password attempts vs. user simply trying the same password over and over -again. You can also truncate the value to n chars by appending ":n" (e.g.@: -sha1:6). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? -Even more verbose logging for debugging purposes. Shows for example SQL -queries. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords? -In case of password mismatches, log the passwords and used scheme so the -problem can be debugged. Enabling this also enables @samp{auth-debug}. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug? -Enable mail process debugging. This can help you figure out why Dovecot -isn't finding your mails. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl? -Show protocol level SSL errors. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp -Prefix for each line written to log file. % codes are in strftime(3) -format. Defaults to @samp{"\"%b %d %H:%M:%S \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements -List of elements we want to log. The elements which have a non-empty -variable value are joined together to form a comma-separated string. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-log-format -Login log format. %s contains @samp{login-log-format-elements} string, %$ -contains the data we want to log. Defaults to @samp{"%$: %s"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix -Log prefix for mail processes. See doc/wiki/Variables.txt for list of -possible variables you can use. Defaults to -@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format -Format to use for logging mail deliveries. You can use variables: -@table @code -@item %$ -Delivery status message (e.g.@: @samp{saved to INBOX}) -@item %m -Message-ID -@item %s -Subject -@item %f -From address -@item %p -Physical size -@item %w -Virtual size. -@end table -Defaults to @samp{"msgid=%m: %$"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-location -Location for users' mailboxes. The default is empty, which means that -Dovecot tries to find the mailboxes automatically. This won't work if the -user doesn't yet have any mail, so you should explicitly tell Dovecot the -full location. - -If you're using mbox, giving a path to the INBOX file (e.g.@: /var/mail/%u) -isn't enough. You'll also need to tell Dovecot where the other mailboxes -are kept. This is called the "root mail directory", and it must be the -first path given in the @samp{mail-location} setting. - -There are a few special variables you can use, eg.: - -@table @samp -@item %u -username -@item %n -user part in user@@domain, same as %u if there's no domain -@item %d -domain part in user@@domain, empty if there's no domain -@item %h -home director -@end table - -See doc/wiki/Variables.txt for full list. Some examples: -@table @samp -@item maildir:~/Maildir -@item mbox:~/mail:INBOX=/var/mail/%u -@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/% -@end table -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-uid -System user and group used to access mails. If you use multiple, userdb can -override these by returning uid or gid fields. You can use either numbers -or names. <doc/wiki/UserIds.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-gid - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group -Group to enable temporarily for privileged operations. Currently this is -used only with INBOX when either its initial creation or dotlocking fails. -Typically this is set to "mail" to give access to /var/mail. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups -Grant access to these supplementary groups for mail processes. Typically -these are used to set up access to shared mailboxes. Note that it may be -dangerous to set these if users can create symlinks (e.g.@: if "mail" group -is set here, ln -s /var/mail ~/mail/var could allow a user to delete others' -mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading -it). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access? -Allow full file system access to clients. There's no access checks other -than what the operating system does for the active UID/GID. It works with -both maildir and mboxes, allowing you to prefix mailboxes names with e.g.@: -/path/ or ~user/. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable? -Don't use mmap() at all. This is required if you store indexes to shared -file systems (NFS or clustered file system). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl? -Rely on @samp{O_EXCL} to work when creating dotlock files. NFS supports -@samp{O_EXCL} since version 3, so this should be safe to use nowadays by -default. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync -When to use fsync() or fdatasync() calls: -@table @code -@item optimized -Whenever necessary to avoid losing important data -@item always -Useful with e.g.@: NFS when write()s are delayed -@item never -Never use it (best performance, but crashes can lose data). -@end table -Defaults to @samp{"optimized"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage? -Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS -caches whenever needed. If you're using only a single mail server this -isn't needed. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index? -Mail index files also exist in NFS. Setting this to yes requires -@samp{mmap-disable? #t} and @samp{fsync-disable? #f}. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string lock-method -Locking method for index files. Alternatives are fcntl, flock and dotlock. -Dotlocking uses some tricks which may create more disk I/O than other -locking methods. NFS users: flock doesn't work, remember to change -@samp{mmap-disable}. Defaults to @samp{"fcntl"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir -Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. -Defaults to @samp{"/tmp"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid -Valid UID range for users. This is mostly to make sure that users can't log -in as daemons or other system users. Note that denying root logins is -hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid} -is set to 0. Defaults to @samp{500}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid -Valid GID range for users. Users having non-valid GID as primary group ID -aren't allowed to log in. If user belongs to supplementary groups with -non-valid GIDs, those groups are not set. Defaults to @samp{1}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length -Maximum allowed length for mail keyword name. It's only forced when trying -to create new keywords. Defaults to @samp{50}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs -List of directories under which chrooting is allowed for mail processes -(i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This -setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot -settings. If this setting is empty, "/./" in home dirs are ignored. -WARNING: Never add directories here which local users can modify, that may -lead to root exploit. Usually this should be done only if you don't allow -shell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot -Default chroot directory for mail processes. This can be overridden for -specific users in user database by giving /./ in user's home directory -(e.g.@: /home/./user chroots into /home). Note that usually there is no -real need to do chrooting, Dovecot doesn't allow users to access files -outside their mail directory anyway. If your home directories are prefixed -with the chroot directory, append "/."@: to @samp{mail-chroot}. -<doc/wiki/Chrooting.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path -UNIX socket path to master authentication server to find users. This is -used by imap (for shared users) and lda. Defaults to -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir -Directory where to look up mail plugins. Defaults to -@samp{"/usr/lib/dovecot"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins -List of plugins to load for all services. Plugins specific to IMAP, LDA, -etc.@: are added to this list in their own .conf files. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count -The minimum number of mails in a mailbox before updates are done to cache -file. This allows optimizing Dovecot's behavior to do less disk writes at -the cost of more disk reads. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval -When IDLE command is running, mailbox is checked once in a while to see if -there are any new mails or other changes. This setting defines the minimum -time to wait between those checks. Dovecot can also use dnotify, inotify -and kqueue to find out immediately when changes occur. Defaults to -@samp{"30 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf? -Save mails with CR+LF instead of plain LF. This makes sending those mails -take less CPU, especially with sendfile() syscall with Linux and FreeBSD. -But it also creates a bit more disk I/O which may just make it slower. Also -note that if other software reads the mboxes/maildirs, they may handle the -extra CRs wrong and cause problems. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs? -By default LIST command returns all entries in maildir beginning with a -dot. Enabling this option makes Dovecot return only entries which are -directories. This is done by stat()ing each entry, so it causes more disk -I/O. (For systems setting struct @samp{dirent->d_type} this check is free -and it's done always regardless of this setting). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks? -When copying a message, do it with hard links whenever possible. This makes -the performance much better, and it's unlikely to have any side effects. -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs? -Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only -when its mtime changes unexpectedly or when we can't find the mail -otherwise. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks -Which locking methods to use for locking mbox. There are four available: - -@table @code -@item dotlock -Create <mailbox>.lock file. This is the oldest and most NFS-safe solution. -If you want to use /var/mail/ like directory, the users will need write -access to that directory. -@item dotlock-try -Same as dotlock, but if it fails because of permissions or because there -isn't enough disk space, just skip it. -@item fcntl -Use this if possible. Works with NFS too if lockd is used. -@item flock -May not exist in all systems. Doesn't work with NFS. -@item lockf -May not exist in all systems. Doesn't work with NFS. -@end table - -You can use multiple locking methods; if you do the order they're declared -in is important to avoid deadlocks if other MTAs/MUAs are using multiple -locking methods as well. Some operating systems don't allow using some of -them simultaneously. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout -Maximum time to wait for lock (all of them) before aborting. Defaults to -@samp{"5 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout -If dotlock exists but the mailbox isn't modified in any way, override the -lock file after this much time. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs? -When mbox changes unexpectedly we have to fully read it to find out what -changed. If the mbox is large this can take a long time. Since the change -is usually just a newly appended mail, it'd be faster to simply read the new -mails. If this setting is enabled, Dovecot does this but still safely -fallbacks to re-reading the whole mbox file whenever something in mbox isn't -how it's expected to be. The only real downside to this setting is that if -some other MUA changes message flags, Dovecot doesn't notice it -immediately. Note that a full sync is done with SELECT, EXAMINE, EXPUNGE -and CHECK commands. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs? -Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT, -EXAMINE, EXPUNGE or CHECK commands. If this is set, @samp{mbox-dirty-syncs} -is ignored. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes? -Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK -commands and when closing the mailbox). This is especially useful for POP3 -where clients often delete all mails. The downside is that our changes -aren't immediately visible to other MUAs. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size -If mbox size is smaller than this (e.g.@: 100k), don't write index files. -If an index file already exists it's still read, just not updated. Defaults -to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size -Maximum dbox file size until it's rotated. Defaults to @samp{10000000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval -Maximum dbox file age until it's rotated. Typically in days. Day begins -from midnight, so 1d = today, 2d = yesterday, etc. 0 = check disabled. -Defaults to @samp{"1d"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space? -When creating new mdbox files, immediately preallocate their size to -@samp{mdbox-rotate-size}. This setting currently works only in Linux with -some file systems (ext4, xfs). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir -sdbox and mdbox support saving mail attachments to external files, which -also allows single instance storage for them. Other backends don't support -this for now. - -WARNING: This feature hasn't been tested much yet. Use at your own risk. - -Directory root where to store mail attachments. Disabled, if empty. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size -Attachments smaller than this aren't saved externally. It's also possible -to write a plugin to disable saving specific attachments externally. -Defaults to @samp{128000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs -File system backend to use for saving attachments: -@table @code -@item posix -No SiS done by Dovecot (but this might help FS's own deduplication) -@item sis posix -SiS with immediate byte-by-byte comparison during saving -@item sis-queue posix -SiS with delayed comparison and deduplication. -@end table -Defaults to @samp{"sis posix"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash -Hash format to use in attachment filenames. You can add any text and -variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}}, -@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be -truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits. -Defaults to @samp{"%@{sha1@}"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit - -Defaults to @samp{1000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit -Default VSZ (virtual memory size) limit for service processes. This is -mainly intended to catch and kill processes that leak memory before they eat -up everything. Defaults to @samp{256000000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string default-login-user -Login user is internally used by login processes. This is the most -untrusted user in Dovecot system. It shouldn't have access to anything at -all. Defaults to @samp{"dovenull"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user -Internal user is used by unprivileged processes. It should be separate from -login user, so that login processes can't disturb other processes. Defaults -to @samp{"dovecot"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl? -SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to -@samp{"required"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert -PEM encoded X.509 SSL/TLS certificate (public key). Defaults to -@samp{"</etc/dovecot/default.pem"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-key -PEM encoded SSL/TLS private key. The key is opened before dropping root -privileges, so keep the key file unreadable by anyone but root. Defaults to -@samp{"</etc/dovecot/private/default.pem"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password -If key file is password protected, give the password here. Alternatively -give it when starting dovecot with -p parameter. Since this file is often -world-readable, you may want to place this setting instead to a different. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca -PEM encoded trusted certificate authority. Set this only if you intend to -use @samp{ssl-verify-client-cert? #t}. The file should contain the CA -certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca -</etc/ssl/certs/ca.pem}). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl? -Require that CRL check succeeds for client certificates. Defaults to -@samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert? -Request client to send a certificate. If you also want to require it, set -@samp{auth-ssl-require-client-cert? #t} in auth section. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field -Which field from certificate to use for username. commonName and -x500UniqueIdentifier are the usual choices. You'll also need to set -@samp{auth-ssl-username-from-cert? #t}. Defaults to @samp{"commonName"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol -Minimum SSL protocol version to accept. Defaults to @samp{"TLSv1"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list -SSL ciphers to use. Defaults to -@samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device -SSL crypto device to use, for valid values run "openssl engine". Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address -Address to use when sending rejection mails. %d expands to recipient -domain. Defaults to @samp{"postmaster@@%d"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string hostname -Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and -in LMTP replies. Default is the system's real hostname@@domain. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail? -If user is over quota, return with temporary failure instead of bouncing the -mail. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path -Binary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string submission-host -If non-empty, send mails via this SMTP host[:port] instead of sendmail. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject -Subject: header to use for rejection mails. You can use the same variables -as for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason -Human readable error message for rejection mails. You can use variables: - -@table @code -@item %n -CRLF -@item %r -reason -@item %s -original subject -@item %t -recipient -@end table -Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter -Delimiter character between local-part and detail in email address. -Defaults to @samp{"+"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header -Header where the original recipient address (SMTP's RCPT TO: address) is -taken from if not available elsewhere. With dovecot-lda -a parameter -overrides this. A commonly used header for this is X-Original-To. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate? -Should saving a mail to a nonexistent mailbox automatically create it?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe? -Should automatically created mailboxes be also automatically subscribed?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length -Maximum IMAP command line length. Some clients generate very long command -lines with huge mailboxes, so you may need to raise this if you get "Too -long argument" or "IMAP command line too large" errors often. Defaults to -@samp{64000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format -IMAP logout format string: -@table @code -@item %i -total number of bytes read from client -@item %o -total number of bytes sent to client. -@end table -See @file{doc/wiki/Variables.txt} for a list of all the variables you can -use. Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} -expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} -hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} -body_bytes=%@{fetch_body_bytes@}"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-capability -Override the IMAP CAPABILITY response. If the value begins with '+', add -the given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval -How long to wait between "OK Still here" notifications when client is -IDLEing. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send -ID field names and values to send to clients. Using * as the value makes -Dovecot use the default value. The following fields have default values -currently: name, version, os, os-version, support-url, support-email. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log -ID fields sent by client to log. * means everything. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds -Workarounds for various client bugs: - -@table @code -@item delay-newmail -Send EXISTS/RECENT new mail notifications only when replying to NOOP and -CHECK commands. Some clients ignore them otherwise, for example OSX Mail -(<v2.1). Outlook Express breaks more badly though, without this it may show -user "Message no longer in server" errors. Note that OE6 still breaks even -with this workaround if synchronization is set to "Headers Only". - -@item tb-extra-mailbox-sep -Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds -extra @samp{/} suffixes to mailbox names. This option causes Dovecot to -ignore the extra @samp{/} instead of treating it as invalid mailbox name. - -@item tb-lsub-flags -Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This -makes Thunderbird realize they aren't selectable and show them greyed out, -instead of only later giving "not selectable" popup error. -@end table -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host -Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to -@samp{""}. -@end deftypevr - - -Whew! Lots of configuration options. The nice thing about it though is that -Guix has a complete interface to Dovecot's configuration language. This -allows not only a nice way to declare configurations, but also offers -reflective capabilities as well: users can write code to inspect and -transform configurations from within Scheme. - -However, it could be that you just want to get a @code{dovecot.conf} up and -running. In that case, you can pass an @code{opaque-dovecot-configuration} -as the @code{#:config} parameter to @code{dovecot-service}. As its name -indicates, an opaque configuration does not have easy reflective -capabilities. - -Available @code{opaque-dovecot-configuration} fields are: - -@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{opaque-dovecot-configuration} parameter} string string -The contents of the @code{dovecot.conf}, as a string. -@end deftypevr - -For example, if your @code{dovecot.conf} is just the empty string, you could -instantiate a dovecot service like this: - -@example -(dovecot-service #:config - (opaque-dovecot-configuration - (string ""))) -@end example - -@subsubheading OpenSMTPD Service - -@deffn {Scheme Variable} opensmtpd-service-type -This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service, -whose value should be an @code{opensmtpd-configuration} object as in this -example: - -@example -(service opensmtpd-service-type - (opensmtpd-configuration - (config-file (local-file "./my-smtpd.conf")))) -@end example -@end deffn - -@deftp {Data Type} opensmtpd-configuration -Data type representing the configuration of opensmtpd. - -@table @asis -@item @code{package} (default: @var{opensmtpd}) -Package object of the OpenSMTPD SMTP server. - -@item @code{config-file} (default: @var{%default-opensmtpd-file}) -File-like object of the OpenSMTPD configuration file to use. By default it -listens on the loopback network interface, and allows for mail from users -and daemons on the local machine, as well as permitting email to remote -servers. Run @command{man smtpd.conf} for more information. - -@end table -@end deftp - -@subsubheading Exim Service - -@cindex mail transfer agent (MTA) -@cindex MTA (mail transfer agent) -@cindex SMTP - -@deffn {Scheme Variable} exim-service-type -This is the type of the @uref{https://exim.org, Exim} mail transfer agent -(MTA), whose value should be an @code{exim-configuration} object as in this -example: - -@example -(service exim-service-type - (exim-configuration - (config-file (local-file "./my-exim.conf")))) -@end example -@end deffn - -In order to use an @code{exim-service-type} service you must also have a -@code{mail-aliases-service-type} service present in your -@code{operating-system} (even if it has no aliases). - -@deftp {Data Type} exim-configuration -Data type representing the configuration of exim. - -@table @asis -@item @code{package} (default: @var{exim}) -Package object of the Exim server. - -@item @code{config-file} (default: @code{#f}) -File-like object of the Exim configuration file to use. If its value is -@code{#f} then use the default configuration file from the package provided -in @code{package}. The resulting configuration file is loaded after setting -the @code{exim_user} and @code{exim_group} configuration variables. - -@end table -@end deftp - -@subsubheading Mail Aliases Service - -@cindex email aliases -@cindex aliases, for email addresses - -@deffn {Scheme Variable} mail-aliases-service-type -This is the type of the service which provides @code{/etc/aliases}, -specifying how to deliver mail to users on this system. - -@example -(service mail-aliases-service-type - '(("postmaster" "bob") - ("bob" "bob@@example.com" "bob@@example2.com"))) -@end example -@end deffn - -The configuration for a @code{mail-aliases-service-type} service is an -association list denoting how to deliver mail that comes to this -system. Each entry is of the form @code{(alias addresses ...)}, with -@code{alias} specifying the local alias and @code{addresses} specifying -where to deliver this user's mail. - -The aliases aren't required to exist as users on the local system. In the -above example, there doesn't need to be a @code{postmaster} entry in the -@code{operating-system}'s @code{user-accounts} in order to deliver the -@code{postmaster} mail to @code{bob} (which subsequently would deliver mail -to @code{bob@@example.com} and @code{bob@@example2.com}). - -@node Kurznachrichtendienste -@subsection Kurznachrichtendienste - -@cindex messaging -@cindex jabber -@cindex XMPP -The @code{(gnu services messaging)} module provides Guix service definitions -for messaging services: currently only Prosody is supported. - -@subsubheading Prosody Service - -@deffn {Scheme Variable} prosody-service-type -This is the type for the @uref{https://prosody.im, Prosody XMPP -communication server}. Its value must be a @code{prosody-configuration} -record as in this example: - -@example -(service prosody-service-type - (prosody-configuration - (modules-enabled (cons "groups" "mam" %default-modules-enabled)) - (int-components - (list - (int-component-configuration - (hostname "conference.example.net") - (plugin "muc") - (mod-muc (mod-muc-configuration))))) - (virtualhosts - (list - (virtualhost-configuration - (domain "example.net")))))) -@end example - -See below for details about @code{prosody-configuration}. - -@end deffn - -By default, Prosody does not need much configuration. Only one -@code{virtualhosts} field is needed: it specifies the domain you wish -Prosody to serve. - -You can perform various sanity checks on the generated configuration with -the @code{prosodyctl check} command. - -Prosodyctl will also help you to import certificates from the -@code{letsencrypt} directory so that the @code{prosody} user can access -them. See @url{https://prosody.im/doc/letsencrypt}. - -@example -prosodyctl --root cert import /etc/letsencrypt/live -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. Types -starting with @code{maybe-} denote parameters that won't show up in -@code{prosody.cfg.lua} when their value is @code{'disabled}. - -There is also a way to specify the configuration as a string, if you have an -old @code{prosody.cfg.lua} file that you want to port over from some other -system; see the end for more details. - -The @code{file-object} type designates either a file-like object -(@pxref{G-Ausdrücke, file-like objects}) or a file name. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services messaging). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as Prosody updates. - -Available @code{prosody-configuration} fields are: - -@deftypevr {@code{prosody-configuration} parameter} package prosody -The Prosody package. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name data-path -Location of the Prosody data storage directory. See -@url{https://prosody.im/doc/configure}. Defaults to -@samp{"/var/lib/prosody"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths -Additional plugin directories. They are searched in all the specified paths -in order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name certificates -Every virtual host and component needs a certificate so that clients and -servers can securely verify its identity. Prosody will automatically load -certificates/keys from the directory specified here. Defaults to -@samp{"/etc/prosody/certs"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list admins -This is a list of accounts that are admins for the server. Note that you -must create the accounts separately. See -@url{https://prosody.im/doc/admins} and -@url{https://prosody.im/doc/creating_accounts}. Example: @code{(admins -'("user1@@example.com" "user2@@example.net"))} Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent? -Enable use of libevent for better performance under high load. See -@url{https://prosody.im/doc/libevent}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled -This is the list of modules Prosody will load on startup. It looks for -@code{mod_modulename.lua} in the plugins folder, so make sure that exists -too. Documentation on modules can be found at: -@url{https://prosody.im/doc/modules}. Defaults to @samp{("roster" -"saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" -"version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled -@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should -you want to disable them then add them to this list. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object groups-file -Path to a text file where the shared groups are defined. If this path is -empty then @samp{mod_groups} does nothing. See -@url{https://prosody.im/doc/modules/mod_groups}. Defaults to -@samp{"/var/lib/prosody/sharedgroups.txt"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration? -Disable account creation by default, for security. See -@url{https://prosody.im/doc/creating_accounts}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl -These are the SSL/TLS-related settings. Most of them are disabled so to use -Prosody's defaults. If you do not completely understand these options, do -not add them to your config, it is easy to lower the security of your server -using them. See @url{https://prosody.im/doc/advanced_ssl_config}. - -Available @code{ssl-configuration} fields are: - -@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol -This determines what handshake to use. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key -Path to your private key file. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate -Path to your certificate file. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} file-object capath -Path to directory containing root certificates that you wish Prosody to -trust when verifying the certificates of remote servers. Defaults to -@samp{"/etc/ssl/certs"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile -Path to a file containing root certificates that you wish Prosody to trust. -Similar to @code{capath} but with all certificates concatenated together. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify -A list of verification options (these mostly map to OpenSSL's -@code{set_verify()} flags). -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options -A list of general options relating to SSL/TLS. These map to OpenSSL's -@code{set_options()}. For a full list of options available in LuaSec, see -the LuaSec source. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth -How long a chain of certificate authorities to check when looking for a -trusted root certificate. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers -An OpenSSL cipher string. This selects what ciphers Prosody will offer to -clients, and in what order. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam -A path to a file containing parameters for Diffie-Hellman key exchange. You -can create such a file with: @code{openssl dhparam -out -/etc/prosody/certs/dh-2048.pem 2048} -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string curve -Curve for Elliptic curve Diffie-Hellman. Prosody's default is -@samp{"secp384r1"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext -A list of "extra" verification options. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string password -Password for encrypted private keys. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption? -Whether to force all client-to-server connections to be encrypted or not. -See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms -Set of mechanisms that will never be offered. See -@url{https://prosody.im/doc/modules/mod_saslauth}. Defaults to -@samp{("DIGEST-MD5")}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption? -Whether to force all server-to-server connections to be encrypted or not. -See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth? -Whether to require encryption and certificate authentication. This provides -ideal security, but requires servers you communicate with to support -encryption AND present valid, trusted certificates. See -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains -Many servers don't support encryption or have invalid or self-signed -certificates. You can list domains here that will not be required to -authenticate using certificates. They will be authenticated using DNS. See -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains -Even if you leave @code{s2s-secure-auth?} disabled, you can still require -valid certificates for some domains by specifying a list here. See -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string authentication -Select the authentication backend to use. The default provider stores -passwords in plaintext and uses Prosody's configured data storage to store -the authentication data. If you do not trust your server please see -@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for -information about using the hashed backend. See also -@url{https://prosody.im/doc/authentication} Defaults to -@samp{"internal_plain"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-string log -Set logging options. Advanced logging configuration is not yet supported by -the Guix Prosody Service. See @url{https://prosody.im/doc/logging}. -Defaults to @samp{"*syslog"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name pidfile -File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}. -Defaults to @samp{"/var/run/prosody/prosody.pid"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size -Maximum allowed size of the HTTP body (in bytes). -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url -Some modules expose their own URL in various ways. This URL is built from -the protocol, host and port used. If Prosody sits behind a proxy, the -public URL will be @code{http-external-url} instead. See -@url{https://prosody.im/doc/http#external_url}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts -A host in Prosody is a domain on which user accounts can be created. For -example if you want your users to have addresses like -@samp{"john.smith@@example.com"} then you need to add a host -@samp{"example.com"}. All options in this list will apply only to this -host. - -Note: the name "virtual" host is used in configuration to avoid confusion -with the actual physical host that Prosody is installed on. A single -Prosody instance can serve many domains, each one defined as a VirtualHost -entry in Prosody's configuration. Conversely a server that hosts a single -domain would have just one VirtualHost entry. - -See @url{https://prosody.im/doc/configure#virtual_host_settings}. - -Available @code{virtualhost-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{virtualhost-configuration} parameter} string domain -Domain you wish Prosody to serve. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components -Components are extra services on a server which are available to clients, -usually on a subdomain of the main server (such as -@samp{"mycomponent.example.com"}). Example components might be chatroom -servers, user directories, or gateways to other protocols. - -Internal components are implemented with Prosody-specific plugins. To add -an internal component, you simply fill the hostname field, and the plugin -you wish to use for the component. - -See @url{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{int-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{int-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@deftypevr {@code{int-component-configuration} parameter} string plugin -Plugin you wish to use for the component. -@end deftypevr - -@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc -Multi-user chat (MUC) is Prosody's module for allowing you to create hosted -chatrooms/conferences for XMPP users. - -General information on setting up and using multi-user chatrooms can be -found in the "Chatrooms" documentation -(@url{https://prosody.im/doc/chatrooms}), which you should read if you are -new to XMPP chatrooms. - -See also @url{https://prosody.im/doc/modules/mod_muc}. - -Available @code{mod-muc-configuration} fields are: - -@deftypevr {@code{mod-muc-configuration} parameter} string name -The name to return in service discovery responses. Defaults to -@samp{"Prosody Chatrooms"}. -@end deftypevr - -@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation -If @samp{#t}, this will only allow admins to create new chatrooms. -Otherwise anyone can create a room. The value @samp{"local"} restricts room -creation to users on the service's parent domain. E.g.@: -@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The -value @samp{"admin"} restricts to service administrators only. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages -Maximum number of history messages that will be sent to the member that has -just joined the room. Defaults to @samp{20}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components -External components use XEP-0114, which most standalone components support. -To add an external component, you simply fill the hostname field. See -@url{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{ext-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{ext-component-configuration} parameter} string component-secret -Password which the component will use to log in. -@end deftypevr - -@deftypevr {@code{ext-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports -Port(s) Prosody listens on for component connections. Defaults to -@samp{(5347)}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string component-interface -Interface Prosody listens on for component connections. Defaults to -@samp{"127.0.0.1"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content -Raw content that will be added to the configuration file. -@end deftypevr - -It could be that you just want to get a @code{prosody.cfg.lua} up and -running. In that case, you can pass an @code{opaque-prosody-configuration} -record as the value of @code{prosody-service-type}. As its name indicates, -an opaque configuration does not have easy reflective capabilities. -Available @code{opaque-prosody-configuration} fields are: - -@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody -The prosody package. -@end deftypevr - -@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua -The contents of the @code{prosody.cfg.lua} to use. -@end deftypevr - -For example, if your @code{prosody.cfg.lua} is just the empty string, you -could instantiate a prosody service like this: - -@example -(service prosody-service-type - (opaque-prosody-configuration - (prosody.cfg.lua ""))) -@end example - -@c end of Prosody auto-generated documentation - -@subsubheading BitlBee Service - -@cindex IRC (Internet Relay Chat) -@cindex IRC gateway -@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC interface -to a variety of messaging protocols such as XMPP. - -@defvr {Scheme Variable} bitlbee-service-type -This is the service type for the @url{http://bitlbee.org,BitlBee} IRC -gateway daemon. Its value is a @code{bitlbee-configuration} (see below). - -To have BitlBee listen on port 6667 on localhost, add this line to your -services: - -@example -(service bitlbee-service-type) -@end example -@end defvr - -@deftp {Data Type} bitlbee-configuration -This is the configuration for BitlBee, with the following fields: - -@table @asis -@item @code{interface} (default: @code{"127.0.0.1"}) -@itemx @code{port} (default: @code{6667}) -Listen on the network interface corresponding to the IP address specified in -@var{interface}, on @var{port}. - -When @var{interface} is @code{127.0.0.1}, only local clients can connect; -when it is @code{0.0.0.0}, connections can come from any networking -interface. - -@item @code{package} (default: @code{bitlbee}) -The BitlBee package to use. - -@item @code{plugins} (Vorgabe: @code{'()}) -List of plugin packages to use---e.g., @code{bitlbee-discord}. - -@item @code{extra-settings} (default: @code{""}) -Configuration snippet added as-is to the BitlBee configuration file. -@end table -@end deftp - -@subsubheading Quassel Service - -@cindex IRC (Internet Relay Chat) -@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning -that one or more clients can attach to and detach from the central core. - -@defvr {Scheme Variable} quassel-service-type -This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC -backend daemon. Its value is a @code{quassel-configuration} (see below). -@end defvr - -@deftp {Data Type} quassel-configuration -This is the configuration for Quassel, with the following fields: - -@table @asis -@item @code{quassel} (default: @code{quassel}) -The Quassel package to use. - -@item @code{interface} (default: @code{"::,0.0.0.0"}) -@item @code{port} (default: @code{4242}) -Listen on the network interface(s) corresponding to the IPv4 or IPv6 -interfaces specified in the comma delimited @var{interface}, on @var{port}. - -@item @code{loglevel} (default: @code{"Info"}) -The level of logging desired. Accepted values are Debug, Info, Warning and -Error. -@end table -@end deftp - -@node Telefondienste -@subsection Telefondienste - -@cindex Murmur (VoIP server) -@cindex VoIP server -This section describes how to set up and run a Murmur server. Murmur is the -server of the @uref{https://mumble.info, Mumble} voice-over-IP (VoIP) suite. - -@deftp {Data Type} murmur-configuration -The service type for the Murmur server. An example configuration can look -like this: - -@example -(service murmur-service-type - (murmur-configuration - (welcome-text - "Welcome to this Mumble server running on Guix!") - (cert-required? #t) ;disallow text password logins - (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") - (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) -@end example - -After reconfiguring your system, you can manually set the murmur -@code{SuperUser} password with the command that is printed during the -activation phase. - -It is recommended to register a normal Mumble user account and grant it -admin or moderator rights. You can use the @code{mumble} client to login as -new normal user, register yourself, and log out. For the next step login -with the name @code{SuperUser} use the @code{SuperUser} password that you -set previously, and grant your newly registered mumble user administrator or -moderator rights and create some channels. - -Available @code{murmur-configuration} fields are: - -@table @asis -@item @code{package} (default: @code{mumble}) -Package that contains @code{bin/murmurd}. - -@item @code{user} (default: @code{"murmur"}) -User who will run the Murmur server. - -@item @code{group} (default: @code{"murmur"}) -Group of the user who will run the murmur server. - -@item @code{port} (default: @code{64738}) -Port on which the server will listen. - -@item @code{welcome-text} (default: @code{""}) -Welcome text sent to clients when they connect. - -@item @code{server-password} (default: @code{""}) -Password the clients have to enter in order to connect. - -@item @code{max-users} (default: @code{100}) -Maximum of users that can be connected to the server at once. - -@item @code{max-user-bandwidth} (default: @code{#f}) -Maximum voice traffic a user can send per second. - -@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"}) -File name of the sqlite database. The service's user will become the owner -of the directory. - -@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"}) -File name of the log file. The service's user will become the owner of the -directory. - -@item @code{autoban-attempts} (default: @code{10}) -Maximum number of logins a user can make in @code{autoban-timeframe} without -getting auto banned for @code{autoban-time}. - -@item @code{autoban-timeframe} (default: @code{120}) -Timeframe for autoban in seconds. - -@item @code{autoban-time} (default: @code{300}) -Amount of time in seconds for which a client gets banned when violating the -autoban limits. - -@item @code{opus-threshold} (default: @code{100}) -Percentage of clients that need to support opus before switching over to -opus audio codec. - -@item @code{channel-nesting-limit} (default: @code{10}) -How deep channels can be nested at maximum. - -@item @code{channelname-regex} (default: @code{#f}) -A string in form of a Qt regular expression that channel names must conform -to. - -@item @code{username-regex} (default: @code{#f}) -A string in form of a Qt regular expression that user names must conform to. - -@item @code{text-message-length} (default: @code{5000}) -Maximum size in bytes that a user can send in one text chat message. - -@item @code{image-message-length} (default: @code{(* 128 1024)}) -Maximum size in bytes that a user can send in one image message. - -@item @code{cert-required?} (default: @code{#f}) -If it is set to @code{#t} clients that use weak password authentification -will not be accepted. Users must have completed the certificate wizard to -join. - -@item @code{remember-channel?} (Vorgabe: @code{#f}) -Should murmur remember the last channel each user was in when they -disconnected and put them into the remembered channel when they rejoin. - -@item @code{allow-html?} (default: @code{#f}) -Should html be allowed in text messages, user comments, and channel -descriptions. - -@item @code{allow-ping?} (default: @code{#f}) -Setting to true exposes the current user count, the maximum user count, and -the server's maximum bandwidth per client to unauthenticated users. In the -Mumble client, this information is shown in the Connect dialog. - -Disabling this setting will prevent public listing of the server. - -@item @code{bonjour?} (default: @code{#f}) -Should the server advertise itself in the local network through the bonjour -protocol. - -@item @code{send-version?} (default: @code{#f}) -Should the murmur server version be exposed in ping requests. - -@item @code{log-days} (default: @code{31}) -Murmur also stores logs in the database, which are accessible via RPC. The -default is 31 days of months, but you can set this setting to 0 to keep logs -forever, or -1 to disable logging to the database. - -@item @code{obfuscate-ips?} (Vorgabe: @code{#t}) -Should logged ips be obfuscated to protect the privacy of users. - -@item @code{ssl-cert} (default: @code{#f}) -File name of the SSL/TLS certificate used for encrypted connections. - -@example -(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") -@end example -@item @code{ssl-key} (default: @code{#f}) -Filepath to the ssl private key used for encrypted connections. -@example -(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") -@end example - -@item @code{ssl-dh-params} (default: @code{#f}) -File name of a PEM-encoded file with Diffie-Hellman parameters for the -SSL/TLS encryption. Alternatively you set it to @code{"@@ffdhe2048"}, -@code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or -@code{"@@ffdhe8192"} to use bundled parameters from RFC 7919. - -@item @code{ssl-ciphers} (default: @code{#f}) -The @code{ssl-ciphers} option chooses the cipher suites to make available -for use in SSL/TLS. - -This option is specified using -@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, -OpenSSL cipher list notation}. - -It is recommended that you try your cipher string using 'openssl ciphers -<string>' before setting it here, to get a feel for which cipher suites you -will get. After setting this option, it is recommend that you inspect your -Murmur log to ensure that Murmur is using the cipher suites that you -expected it to. - -Note: Changing this option may impact the backwards compatibility of your -Murmur server, and can remove the ability for older Mumble clients to be -able to connect to it. - -@item @code{public-registration} (default: @code{#f}) -Must be a @code{<murmur-public-registration-configuration>} record or -@code{#f}. - -You can optionally register your server in the public server list that the -@code{mumble} client shows on startup. You cannot register your server if -you have set a @code{server-password}, or set @code{allow-ping} to -@code{#f}. - -It might take a few hours until it shows up in the public list. - -@item @code{file} (default: @code{#f}) -Optional alternative override for this configuration. -@end table -@end deftp - -@deftp {Data Type} murmur-public-registration-configuration -Configuration for public registration of a murmur service. - -@table @asis -@item @code{name} -This is a display name for your server. Not to be confused with the -hostname. - -@item @code{password} -A password to identify your registration. Subsequent updates will need the -same password. Don't lose your password. - -@item @code{url} -This should be a @code{http://} or @code{https://} link to your web site. - -@item @code{hostname} (default: @code{#f}) -By default your server will be listed by its IP address. If it is set your -server will be linked by this host name instead. -@end table -@end deftp - - - -@node Überwachungsdienste -@subsection Überwachungsdienste - -@subsubheading Tailon Service - -@uref{https://tailon.readthedocs.io/, Tailon} is a web application for -viewing and searching log files. - -The following example will configure the service with default values. By -default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}). - -@example -(service tailon-service-type) -@end example - -The following example customises more of the Tailon configuration, adding -@command{sed} to the list of allowed commands. - -@example -(service tailon-service-type - (tailon-configuration - (config-file - (tailon-configuration-file - (allowed-commands '("tail" "grep" "awk" "sed")))))) -@end example - - -@deftp {Data Type} tailon-configuration -Data type representing the configuration of Tailon. This type has the -following parameters: - -@table @asis -@item @code{config-file} (default: @code{(tailon-configuration-file)}) -The configuration file to use for Tailon. This can be set to a -@dfn{tailon-configuration-file} record value, or any gexp -(@pxref{G-Ausdrücke}). - -For example, to instead use a local file, the @code{local-file} function can -be used: - -@example -(service tailon-service-type - (tailon-configuration - (config-file (local-file "./my-tailon.conf")))) -@end example - -@item @code{package} (default: @code{tailon}) -The tailon package to use. - -@end table -@end deftp - -@deftp {Data Type} tailon-configuration-file -Data type representing the configuration options for Tailon. This type has -the following parameters: - -@table @asis -@item @code{files} (default: @code{(list "/var/log")}) -List of files to display. The list can include strings for a single file or -directory, or a list, where the first item is the name of a subsection, and -the remaining items are the files or directories in that subsection. - -@item @code{bind} (default: @code{"localhost:8080"}) -Address and port to which Tailon should bind on. - -@item @code{relative-root} (default: @code{#f}) -URL path to use for Tailon, set to @code{#f} to not use a path. - -@item @code{allow-transfers?} (default: @code{#t}) -Allow downloading the log files in the web interface. - -@item @code{follow-names?} (default: @code{#t}) -Allow tailing of not-yet existent files. - -@item @code{tail-lines} (default: @code{200}) -Number of lines to read initially from each file. - -@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")}) -Commands to allow running. By default, @code{sed} is disabled. - -@item @code{debug?} (default: @code{#f}) -Set @code{debug?} to @code{#t} to show debug messages. - -@item @code{wrap-lines} (default: @code{#t}) -Initial line wrapping state in the web interface. Set to @code{#t} to -initially wrap lines (the default), or to @code{#f} to initially not wrap -lines. - -@item @code{http-auth} (default: @code{#f}) -HTTP authentication type to use. Set to @code{#f} to disable authentication -(the default). Supported values are @code{"digest"} or @code{"basic"}. - -@item @code{users} (default: @code{#f}) -If HTTP authentication is enabled (see @code{http-auth}), access will be -restricted to the credentials provided here. To configure users, use a list -of pairs, where the first element of the pair is the username, and the 2nd -element of the pair is the password. - -@example -(tailon-configuration-file - (http-auth "basic") - (users '(("user1" . "password1") - ("user2" . "password2")))) -@end example - -@end table -@end deftp - - -@subsubheading Darkstat Service -@cindex darkstat -Darkstat is a packet sniffer that captures network traffic, calculates -statistics about usage, and serves reports over HTTP. - -@defvar {Scheme Variable} darkstat-service-type -This is the service type for the @uref{https://unix4lyfe.org/darkstat/, -darkstat} service, its value must be a @code{darkstat-configuration} record -as in this example: - -@example -(service darkstat-service-type - (darkstat-configuration - (interface "eno1"))) -@end example -@end defvar - -@deftp {Data Type} darkstat-configuration -Data type representing the configuration of @command{darkstat}. - -@table @asis -@item @code{package} (default: @code{darkstat}) -The darkstat package to use. - -@item @code{interface} -Capture traffic on the specified network interface. - -@item @code{port} (default: @code{"667"}) -Bind the web interface to the specified port. - -@item @code{bind-address} (default: @code{"127.0.0.1"}) -Bind the web interface to the specified address. - -@item @code{base} (default: @code{"/"}) -Specify the path of the base URL. This can be useful if @command{darkstat} -is accessed via a reverse proxy. - -@end table -@end deftp - -@subsubheading Prometheus Node Exporter Service - -@cindex prometheus-node-exporter -The Prometheus ``node exporter'' makes hardware and operating system -statistics provided by the Linux kernel available for the Prometheus -monitoring system. This service should be deployed on all physical nodes -and virtual machines, where monitoring these statistics is desirable. - -@defvar {Scheme variable} prometheus-node-exporter-service-type -This is the service type for the -@uref{https://github.com/prometheus/node_exporter/, -prometheus-node-exporter} service, its value must be a -@code{prometheus-node-exporter-configuration} record as in this example: - -@example -(service prometheus-node-exporter-service-type - (prometheus-node-exporter-configuration - (web-listen-address ":9100"))) -@end example -@end defvar - -@deftp {Data Type} prometheus-node-exporter-configuration -Repräsentiert die Konfiguration von @command{node_exporter}. - -@table @asis -@item @code{package} (Vorgabe: @code{go-github-com-prometheus-node-exporter}) -Das Paket für den prometheus-node-exporter, was benutzt werden soll. - -@item @code{web-listen-address} (Vorgabe: @code{":9100"}) -Bind the web interface to the specified address. - -@end table -@end deftp - -@subsubheading Zabbix server -@cindex zabbix zabbix-server -Zabbix provides monitoring metrics, among others network utilization, CPU -load and disk space consumption: - -@itemize -@item High performance, high capacity (able to monitor hundreds of thousands of devices). -@item Auto-discovery of servers and network devices and interfaces. -@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others. -@item Distributed monitoring with centralized web administration. -@item Native high performance agents. -@item SLA, and ITIL KPI metrics on reporting. -@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards. -@item Remote command execution through Zabbix proxies. -@end itemize - -@c %start of fragment - -Available @code{zabbix-server-configuration} fields are: - -@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server -The zabbix-server package. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string user -User who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} group group -Group who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"127.0.0.1"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-password -Database password. Please, use @code{include-files} with -@code{DBPassword=SECRET} inside a specified file instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/server.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location -The location of certificate authority (CA) files for SSL server certificate -verification. - -Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location -Location of SSL client certificates. - -Defaults to @samp{"/etc/ssl/certs"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files -You may include individual files or all files in a directory in the -configuration file. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix agent -@cindex zabbix zabbix-agent - -Zabbix agent gathers information for Zabbix server. - -@c %start of fragment - -Available @code{zabbix-agent-configuration} fields are: - -@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent -The zabbix-agent package. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string user -User who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} group group -Group who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname -Unique, case sensitive hostname which is required for active checks and must -match hostname as configured on the server. - -Defaults to @samp{"Zabbix server"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/agent.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} list server -List of IP addresses, optionally in CIDR notation, or hostnames of Zabbix -servers and Zabbix proxies. Incoming connections will be accepted only from -the hosts listed here. - -Defaults to @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active -List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix -proxies for active checks. If port is not specified, default port is used. -If this parameter is not specified, active checks are disabled. - -Defaults to @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files -You may include individual files or all files in a directory in the -configuration file. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix front-end -@cindex zabbix zabbix-front-end - -This service provides a WEB interface to Zabbix server. - -@c %start of fragment - -Available @code{zabbix-front-end-configuration} fields are: - -@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password -Database password. Please, use @code{db-secret-file} instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file -Secret file which will be appended to @file{zabbix.conf.php} file. This -file contains credentials for use by Zabbix front-end. You are expected to -create it manually. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host -Zabbix server hostname. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port -Zabbix server port. - -Defaults to @samp{10051}. - -@end deftypevr - - -@c %end of fragment - -@node Kerberos-Dienste -@subsection Kerberos-Dienste -@cindex Kerberos - -The @code{(gnu services kerberos)} module provides services relating to the -authentication protocol @dfn{Kerberos}. - -@subsubheading Krb5 Service - -Programs using a Kerberos client library normally expect a configuration -file in @file{/etc/krb5.conf}. This service generates such a file from a -definition provided in the operating system declaration. It does not cause -any daemon to be started. - -No ``keytab'' files are provided by this service---you must explicitly -create them. This service is known to work with the MIT client library, -@code{mit-krb5}. Other implementations have not been tested. - -@defvr {Scheme Variable} krb5-service-type -A service type for Kerberos 5 clients. -@end defvr - -@noindent -Here is an example of its use: -@lisp -(service krb5-service-type - (krb5-configuration - (default-realm "EXAMPLE.COM") - (allow-weak-crypto? #t) - (realms (list - (krb5-realm - (name "EXAMPLE.COM") - (admin-server "groucho.example.com") - (kdc "karl.example.com")) - (krb5-realm - (name "ARGRX.EDU") - (admin-server "kerb-admin.argrx.edu") - (kdc "keys.argrx.edu")))))) -@end lisp - -@noindent -This example provides a Kerberos@tie{}5 client configuration which: -@itemize -@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both -of which have distinct administration servers and key distribution centers; -@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly -specified by clients; -@item Accepts services which only support encryption types known to be weak. -@end itemize - -The @code{krb5-realm} and @code{krb5-configuration} types have many fields. -Only the most commonly used ones are described here. For a full list, and -more detailed explanation of each, see the MIT -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} -documentation. - - -@deftp {Data Type} krb5-realm -@cindex realm, kerberos -@table @asis -@item @code{name} -This field is a string identifying the name of the realm. A common -convention is to use the fully qualified DNS name of your organization, -converted to upper case. - -@item @code{admin-server} -This field is a string identifying the host where the administration server -is running. - -@item @code{kdc} -This field is a string identifying the key distribution center for the -realm. -@end table -@end deftp - -@deftp {Data Type} krb5-configuration - -@table @asis -@item @code{allow-weak-crypto?} (default: @code{#f}) -If this flag is @code{#t} then services which only offer encryption -algorithms known to be weak will be accepted. - -@item @code{default-realm} (default: @code{#f}) -This field should be a string identifying the default Kerberos realm for the -client. You should set this field to the name of your Kerberos realm. If -this value is @code{#f} then a realm must be specified with every Kerberos -principal when invoking programs such as @command{kinit}. - -@item @code{realms} -This should be a non-empty list of @code{krb5-realm} objects, which clients -may access. Normally, one of them will have a @code{name} field matching -the @code{default-realm} field. -@end table -@end deftp - - -@subsubheading PAM krb5 Service -@cindex pam-krb5 - -The @code{pam-krb5} service allows for login authentication and password -management via Kerberos. You will need this service if you want PAM enabled -applications to authenticate users using Kerberos. - -@defvr {Scheme Variable} pam-krb5-service-type -A service type for the Kerberos 5 PAM module. -@end defvr - -@deftp {Data Type} pam-krb5-configuration -Data type representing the configuration of the Kerberos 5 PAM module This -type has the following parameters: -@table @asis -@item @code{pam-krb5} (default: @code{pam-krb5}) -The pam-krb5 package to use. - -@item @code{minimum-uid} (default: @code{1000}) -The smallest user ID for which Kerberos authentications should be -attempted. Local accounts with lower values will silently fail to -authenticate. -@end table -@end deftp - - -@node Web-Dienste -@subsection Web-Dienste - -@cindex web -@cindex www -@cindex HTTP -The @code{(gnu services web)} module provides the Apache HTTP Server, the -nginx web server, and also a fastcgi wrapper daemon. - -@subsubheading Apache HTTP Server - -@deffn {Scheme Variable} httpd-service-type -Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server -(@dfn{httpd}). The value for this service type is a -@code{httpd-configuration} record. - -A simple example configuration is given below. - -@example -(service httpd-service-type - (httpd-configuration - (config - (httpd-config-file - (server-name "www.example.com") - (document-root "/srv/http/www.example.com"))))) -@end example - -Other services can also extend the @code{httpd-service-type} to add to the -configuration. - -@example -(simple-service 'my-extra-server httpd-service-type - (list - (httpd-virtualhost - "*:80" - (list (string-append - "ServerName "www.example.com - DocumentRoot \"/srv/http/www.example.com\""))))) -@end example -@end deffn - -The details for the @code{httpd-configuration}, @code{httpd-module}, -@code{httpd-config-file} and @code{httpd-virtualhost} record types are given -below. - -@deffn {Data Type} httpd-configuration -This data type represents the configuration for the httpd service. - -@table @asis -@item @code{package} (default: @code{httpd}) -The httpd package to use. - -@item @code{pid-file} (default: @code{"/var/run/httpd"}) -The pid file used by the shepherd-service. - -@item @code{config} (default: @code{(httpd-config-file)}) -The configuration file to use with the httpd service. The default value is a -@code{httpd-config-file} record, but this can also be a different -G-expression that generates a file, for example a @code{plain-file}. A file -outside of the store can also be specified through a string. - -@end table -@end deffn - -@deffn {Data Type} httpd-module -This data type represents a module for the httpd service. - -@table @asis -@item @code{name} -The name of the module. - -@item @code{file} -The file for the module. This can be relative to the httpd package being -used, the absolute location of a file, or a G-expression for a file within -the store, for example @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}. - -@end table -@end deffn - -@defvr {Scheme Variable} %default-httpd-modules -A default list of @code{httpd-module} objects. -@end defvr - -@deffn {Data Type} httpd-config-file -This data type represents a configuration file for the httpd service. - -@table @asis -@item @code{modules} (default: @code{%default-httpd-modules}) -The modules to load. Additional modules can be added here, or loaded by -additional configuration. - -For example, in order to handle requests for PHP files, you can use Apache’s -@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}: - -@example -(service httpd-service-type - (httpd-configuration - (config - (httpd-config-file - (modules (cons* - (httpd-module - (name "proxy_module") - (file "modules/mod_proxy.so")) - (httpd-module - (name "proxy_fcgi_module") - (file "modules/mod_proxy_fcgi.so")) - %default-httpd-modules)) - (extra-config (list "\ -<FilesMatch \\.php$> - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -</FilesMatch>")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (default: @code{httpd}) -The @code{ServerRoot} in the configuration file, defaults to the httpd -package. Directives including @code{Include} and @code{LoadModule} are taken -as relative to the server root. - -@item @code{server-name} (default: @code{#f}) -The @code{ServerName} in the configuration file, used to specify the request -scheme, hostname and port that the server uses to identify itself. - -This doesn't need to be set in the server config, and can be specifyed in -virtual hosts. The default is @code{#f} to not specify a @code{ServerName}. - -@item @code{document-root} (default: @code{"/srv/http"}) -The @code{DocumentRoot} from which files will be served. - -@item @code{listen} (default: @code{'("80")}) -The list of values for the @code{Listen} directives in the config file. The -value should be a list of strings, when each string can specify the port -number to listen on, and optionally the IP address and protocol to use. - -@item @code{pid-file} (default: @code{"/var/run/httpd"}) -The @code{PidFile} to use. This should match the @code{pid-file} set in the -@code{httpd-configuration} so that the Shepherd service is configured -correctly. - -@item @code{error-log} (default: @code{"/var/log/httpd/error_log"}) -The @code{ErrorLog} to which the server will log errors. - -@item @code{user} (default: @code{"httpd"}) -The @code{User} which the server will answer requests as. - -@item @code{group} (default: @code{"httpd"}) -The @code{Group} which the server will answer requests as. - -@item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")}) -A flat list of strings and G-expressions which will be added to the end of -the configuration file. - -Any values which the service is extended with will be appended to this list. - -@end table -@end deffn - -@deffn {Data Type} httpd-virtualhost -This data type represents a virtualhost configuration block for the httpd -service. - -These should be added to the extra-config for the httpd-service. - -@example -(simple-service 'my-extra-server httpd-service-type - (list - (httpd-virtualhost - "*:80" - (list (string-append - "ServerName "www.example.com - DocumentRoot \"/srv/http/www.example.com\""))))) -@end example - -@table @asis -@item @code{addresses-and-ports} -The addresses and ports for the @code{VirtualHost} directive. - -@item @code{contents} -The contents of the @code{VirtualHost} directive, this should be a list of -strings and G-expressions. - -@end table -@end deffn - -@subsubheading NGINX - -@deffn {Scheme Variable} nginx-service-type -Service type for the @uref{https://nginx.org/,NGinx} web server. The value -for this service type is a @code{<nginx-configuration>} record. - -A simple example configuration is given below. - -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -In addition to adding server blocks to the service configuration directly, -this service can be extended by other services to add server blocks, as in -this example: - -@example -(simple-service 'my-extra-server nginx-service-type - (list (nginx-server-configuration - (root "/srv/http/extra-website") - (try-files (list "$uri" "$uri/index.html"))))) -@end example -@end deffn - -At startup, @command{nginx} has not yet read its configuration file, so it -uses a default file to log error messages. If it fails to load its -configuration file, that is where error messages are logged. After the -configuration file is loaded, the default error log file changes as per -configuration. In our case, startup error messages can be found in -@file{/var/run/nginx/logs/error.log}, and after configuration in -@file{/var/log/nginx/error.log}. The second location can be changed with -the @var{log-directory} configuration option. - -@deffn {Data Type} nginx-configuration -This data type represents the configuration for NGinx. Some configuration -can be done through this and the other provided record types, or -alternatively, a config file can be provided. - -@table @asis -@item @code{nginx} (default: @code{nginx}) -The nginx package to use. - -@item @code{log-directory} (default: @code{"/var/log/nginx"}) -The directory to which NGinx will write log files. - -@item @code{run-directory} (default: @code{"/var/run/nginx"}) -The directory in which NGinx will create a pid file, and write temporary -files. - -@item @code{server-blocks} (default: @code{'()}) -A list of @dfn{server blocks} to create in the generated configuration file, -the elements should be of type @code{<nginx-server-configuration>}. - -The following example would setup NGinx to serve @code{www.example.com} from -the @code{/srv/http/www.example.com} directory, without using HTTPS. -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -@item @code{upstream-blocks} (default: @code{'()}) -A list of @dfn{upstream blocks} to create in the generated configuration -file, the elements should be of type @code{<nginx-upstream-configuration>}. - -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{<nginx-server-configuration>} -records. The following example creates a server configuration with one -location configuration, that will proxy requests to a upstream -configuration, which will handle requests with two servers. - -@example -(service - nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com") - (locations - (list - (nginx-location-configuration - (uri "/path1") - (body '("proxy_pass http://server-proxy;")))))))) - (upstream-blocks - (list (nginx-upstream-configuration - (name "server-proxy") - (servers (list "server1.example.com" - "server2.example.com"))))))) -@end example - -@item @code{file} (default: @code{#f}) -If a configuration @var{file} is provided, this will be used, rather than -generating a configuration file from the provided @code{log-directory}, -@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For -proper operation, these arguments should match what is in @var{file} to -ensure that the directories are created when the service is activated. - -This can be useful if you have an existing configuration file, or it's not -possible to do what is required through the other parts of the -nginx-configuration record. - -@item @code{server-names-hash-bucket-size} (default: @code{#f}) -Bucket size for the server names hash tables, defaults to @code{#f} to use -the size of the processors cache line. - -@item @code{server-names-hash-bucket-max-size} (default: @code{#f}) -Maximum bucket size for the server names hash tables. - -@item @code{extra-content} (Vorgabe: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. - -@end table -@end deffn - -@deftp {Data Type} nginx-server-configuration -Data type representing the configuration of an nginx server block. This -type has the following parameters: - -@table @asis -@item @code{listen} (default: @code{'("80" "443 ssl")}) -Each @code{listen} directive sets the address and port for IP, or the path -for a UNIX-domain socket on which the server will accept requests. Both -address and port, or only address or only port can be specified. An address -may also be a hostname, for example: - -@example -'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") -@end example - -@item @code{server-name} (default: @code{(list 'default)}) -A list of server names this server represents. @code{'default} represents -the default server for connections matching no other server. - -@item @code{root} (default: @code{"/srv/http"}) -Root of the website nginx will serve. - -@item @code{locations} (default: @code{'()}) -A list of @dfn{nginx-location-configuration} or -@dfn{nginx-named-location-configuration} records to use within this server -block. - -@item @code{index} (default: @code{(list "index.html")}) -Index files to look for when clients ask for a directory. If it cannot be -found, Nginx will send the list of files in the directory. - -@item @code{try-files} (default: @code{'()}) -A list of files whose existence is checked in the specified order. -@code{nginx} will use the first file it finds to process the request. - -@item @code{ssl-certificate} (default: @code{#f}) -Where to find the certificate for secure connections. Set it to @code{#f} -if you don't have a certificate or you don't want to use HTTPS. - -@item @code{ssl-certificate-key} (default: @code{#f}) -Where to find the private key for secure connections. Set it to @code{#f} -if you don't have a key or you don't want to use HTTPS. - -@item @code{server-tokens?} (default: @code{#f}) -Whether the server should add its configuration to response. - -@item @code{raw-content} (default: @code{'()}) -A list of raw lines added to the server block. - -@end table -@end deftp - -@deftp {Data Type} nginx-upstream-configuration -Data type representing the configuration of an nginx @code{upstream} block. -This type has the following parameters: - -@table @asis -@item @code{name} -Name for this group of servers. - -@item @code{servers} -Specify the addresses of the servers in the group. The address can be -specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@: -@samp{backend1.example.com}) or a path to a UNIX socket using the prefix -@samp{unix:}. For addresses using an IP address or domain name, the default -port is 80, and a different port can be specified explicitly. - -@end table -@end deftp - -@deftp {Data Type} nginx-location-configuration -Data type representing the configuration of an nginx @code{location} block. -This type has the following parameters: - -@table @asis -@item @code{uri} -URI which this location block matches. - -@anchor{nginx-location-configuration body} -@item @code{body} -Body of the location block, specified as a list of strings. This can contain -many configuration directives. For example, to pass requests to a upstream -server group defined using an @code{nginx-upstream-configuration} block, the -following directive would be specified in the body @samp{(list "proxy_pass -http://upstream-name;")}. - -@end table -@end deftp - -@deftp {Data Type} nginx-named-location-configuration -Data type representing the configuration of an nginx named location block. -Named location blocks are used for request redirection, and not used for -regular request processing. This type has the following parameters: - -@table @asis -@item @code{name} -Name to identify this location block. - -@item @code{body} -@xref{nginx-location-configuration body}, as the body for named location -blocks can be used in a similar way to the -@code{nginx-location-configuration body}. One restriction is that the body -of a named location block cannot contain location blocks. - -@end table -@end deftp - -@subsubheading Varnish Cache -@cindex Varnish -Varnish is a fast cache server that sits in between web applications and end -users. It proxies requests from clients and caches the accessed URLs such -that multiple requests for the same resource only creates one request to the -back-end. - -@defvr {Scheme Variable} varnish-service-type -Service type for the Varnish daemon. -@end defvr - -@deftp {Data Type} varnish-configuration -Data type representing the @code{varnish} service configuration. This type -has the following parameters: - -@table @asis -@item @code{package} (Vorgabe: @code{varnish}) -Das Varnish-Paket, was benutzt werden soll. - -@item @code{name} (Vorgabe: @code{"default"}) -A name for this Varnish instance. Varnish will create a directory in -@file{/var/varnish/} with this name and keep temporary files there. If the -name starts with a forward slash, it is interpreted as an absolute directory -name. - -Pass the @code{-n} argument to other Varnish programs to connect to the -named instance, e.g.@: @command{varnishncsa -n default}. - -@item @code{backend} (Vorgabe: @code{"localhost:8080"}) -The backend to use. This option has no effect if @code{vcl} is set. - -@item @code{vcl} (Vorgabe: #f) -The @dfn{VCL} (Varnish Configuration Language) program to run. If this is -@code{#f}, Varnish will proxy @code{backend} using the default -configuration. Otherwise this must be a file-like object with valid VCL -syntax. - -@c Varnish does not support HTTPS, so keep this URL to avoid confusion. -For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can -do something along these lines: - -@example -(define %gnu-mirror - (plain-file - "gnu.vcl" - "vcl 4.1; -backend gnu @{ .host = "www.gnu.org"; @}")) - -(operating-system - ... - (services (cons (service varnish-service-type - (varnish-configuration - (listen '(":80")) - (vcl %gnu-mirror))) - %base-services))) -@end example - -The configuration of an already running Varnish instance can be inspected -and changed using the @command{varnishadm} program. - -Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and -@url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive -documentation on Varnish and its configuration language. - -@item @code{listen} (Vorgabe: @code{'("localhost:80")}) -List of addresses Varnish will listen on. - -@item @code{storage} (Vorgabe: @code{'("malloc,128m")}) -List of storage backends that will be available in VCL. - -@item @code{parameters} (Vorgabe: @code{'()}) -List of run-time parameters in the form @code{'(("parameter" . "value"))}. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Additional arguments to pass to the @command{varnishd} process. - -@end table -@end deftp - -@subsubheading FastCGI -@cindex fastcgi -@cindex fcgiwrap -FastCGI is an interface between the front-end and the back-end of a web -service. It is a somewhat legacy facility; new web services should -generally just talk HTTP between the front-end and the back-end. However -there are a number of back-end services such as PHP or the optimized HTTP -Git repository access that use FastCGI, so we have support for it in Guix. - -To use FastCGI, you configure the front-end web server (e.g., nginx) to -dispatch some subset of its requests to the fastcgi backend, which listens -on a local TCP or UNIX socket. There is an intermediary @code{fcgiwrap} -program that sits between the actual backend process and the web server. -The front-end indicates which backend program to run, passing that -information to the @code{fcgiwrap} process. - -@defvr {Scheme Variable} fcgiwrap-service-type -A service type for the @code{fcgiwrap} FastCGI proxy. -@end defvr - -@deftp {Data Type} fcgiwrap-configuration -Data type representing the configuration of the @code{fcgiwrap} service. -This type has the following parameters: -@table @asis -@item @code{package} (default: @code{fcgiwrap}) -The fcgiwrap package to use. - -@item @code{socket} (default: @code{tcp:127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} process should listen, as a string. -Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}}, -@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and -@code{tcp6:[@var{ipv6_addr}]:port}. - -@item @code{user} (default: @code{fcgiwrap}) -@itemx @code{group} (default: @code{fcgiwrap}) -The user and group names, as strings, under which to run the @code{fcgiwrap} -process. The @code{fastcgi} service will ensure that if the user asks for -the specific user or group names @code{fcgiwrap} that the corresponding user -and/or group is present on the system. - -It is possible to configure a FastCGI-backed web service to pass HTTP -authentication information from the front-end to the back-end, and to allow -@code{fcgiwrap} to run the back-end process as a corresponding local user. -To enable this capability on the back-end., run @code{fcgiwrap} as the -@code{root} user and group. Note that this capability also has to be -configured on the front-end as well. -@end table -@end deftp - -@cindex php-fpm -PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI -implementation with some additional features useful for sites of any size. - -These features include: -@itemize @bullet -@item Adaptive process spawning -@item Basic statistics (similar to Apache's mod_status) -@item Advanced process management with graceful stop/start -@item Ability to start workers with different uid/gid/chroot/environment -and different php.ini (replaces safe_mode) -@item Stdout & stderr logging -@item Emergency restart in case of accidental opcode cache destruction -@item Accelerated upload support -@item Support for a "slowlog" -@item Enhancements to FastCGI, such as fastcgi_finish_request() - -a special function to finish request & flush all data while continuing to do -something time-consuming (video converting, stats processing, etc.) -@end itemize -...@: and much more. - -@defvr {Scheme Variable} php-fpm-service-type -A Service type for @code{php-fpm}. -@end defvr - -@deftp {Data Type} php-fpm-configuration -Data Type for php-fpm service configuration. -@table @asis -@item @code{php} (default: @code{php}) -The php package to use. -@item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) -The address on which to accept FastCGI requests. Valid syntaxes are: -@table @asis -@item @code{"ip.add.re.ss:port"} -Listen on a TCP socket to a specific address on a specific port. -@item @code{"port"} -Listen on a TCP socket to all addresses on a specific port. -@item @code{"/path/to/unix/socket"} -Listen on a unix socket. -@end table - -@item @code{user} (default: @code{php-fpm}) -User who will own the php worker processes. -@item @code{group} (default: @code{php-fpm}) -Group of the worker processes. -@item @code{socket-user} (default: @code{php-fpm}) -User who can speak to the php-fpm socket. -@item @code{socket-group} (default: @code{php-fpm}) -Group that can speak to the php-fpm socket. -@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")}) -The process id of the php-fpm process is written to this file once the -service has started. -@item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) -Log for the php-fpm master process. -@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)}) -Detailed settings for the php-fpm process manager. Must be either: -@table @asis -@item @code{<php-fpm-dynamic-process-manager-configuration>} -@item @code{<php-fpm-static-process-manager-configuration>} -@item @code{<php-fpm-on-demand-process-manager-configuration>} -@end table -@item @code{display-errors} (default @code{#f}) -Determines whether php errors and warning should be sent to clients and -displayed in their browsers. This is useful for local php development, but -a security risk for public sites, as error messages can reveal passwords and -personal data. -@item @code{timezone} (default @code{#f}) -Specifies @code{php_admin_value[date.timezone]} parameter. -@item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")}) -This file will log the @code{stderr} outputs of php worker processes. Can -be set to @code{#f} to disable logging. -@item @code{file} (default @code{#f}) -An optional override of the whole configuration. You can use the -@code{mixed-text-file} function or an absolute filepath for it. -@end table -@end deftp - -@deftp {Data type} php-fpm-dynamic-process-manager-configuration -Data Type for the @code{dynamic} php-fpm process manager. With the -@code{dynamic} process manager, spare worker processes are kept around based -on it's configured limits. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@item @code{start-servers} (default: @code{2}) -How many worker processes should be started on start-up. -@item @code{min-spare-servers} (default: @code{1}) -How many spare worker processes should be kept around at minimum. -@item @code{max-spare-servers} (default: @code{3}) -How many spare worker processes should be kept around at maximum. -@end table -@end deftp - -@deftp {Data type} php-fpm-static-process-manager-configuration -Data Type for the @code{static} php-fpm process manager. With the -@code{static} process manager, an unchanging number of worker processes are -created. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@end table -@end deftp - -@deftp {Data type} php-fpm-on-demand-process-manager-configuration -Data Type for the @code{on-demand} php-fpm process manager. With the -@code{on-demand} process manager, worker processes are only created as -requests arrive. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@item @code{process-idle-timeout} (default: @code{10}) -The time in seconds after which a process with no requests is killed. -@end table -@end deftp - - -@deffn {Scheme Procedure} nginx-php-fpm-location @ - [#:nginx-package nginx] @ [socket (string-append "/var/run/php" @ -(version-major (package-version php)) @ "-fpm.sock")] A helper function to -quickly add php to an @code{nginx-server-configuration}. -@end deffn - -A simple services setup for nginx with php can look like this: -@example -(services (cons* (service dhcp-client-service-type) - (service php-fpm-service-type) - (service nginx-service-type - (nginx-server-configuration - (server-name '("example.com")) - (root "/srv/http/") - (locations - (list (nginx-php-location))) - (listen '("80")) - (ssl-certificate #f) - (ssl-certificate-key #f))) - %base-services)) -@end example - -@cindex cat-avatar-generator -The cat avatar generator is a simple service to demonstrate the use of -php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for -instance the hash of a user's email address. - -@deffn {Scheme Procedure} cat-avatar-generator-service @ - [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package -cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] -Returns an nginx-server-configuration that inherits @code{configuration}. -It extends the nginx configuration to add a server block that serves -@code{package}, a version of cat-avatar-generator. During execution, -cat-avatar-generator will be able to use @code{cache-dir} as its cache -directory. -@end deffn - -A simple setup for cat-avatar-generator can look like this: -@example -(services (cons* (cat-avatar-generator-service - #:configuration - (nginx-server-configuration - (server-name '("example.com")))) - ... - %base-services)) -@end example - -@subsubheading Hpcguix-web - -@cindex hpcguix-web -The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/} program -is a customizable web interface to browse Guix packages, initially designed -for users of high-performance computing (HPC) clusters. - -@defvr {Scheme Variable} hpcguix-web-service-type -The service type for @code{hpcguix-web}. -@end defvr - -@deftp {Data Type} hpcguix-web-configuration -Data type for the hpcguix-web service configuration. - -@table @asis -@item @code{specs} -A gexp (@pxref{G-Ausdrücke}) specifying the hpcguix-web service -configuration. The main items available in this spec are: - -@table @asis -@item @code{title-prefix} (Vorgabe: @code{"hpcguix | "}) -Das Präfix der Webseitentitel. - -@item @code{guix-command} (Vorgabe: @code{"guix"}) -Der @command{guix}-Befehl. - -@item @code{package-filter-proc} (Vorgabe: @code{(const #t)}) -Eine Prozedur, die festlegt, wie anzuzeigende Pakete gefiltert werden. - -@item @code{package-page-extension-proc} (Vorgabe: @code{(const '())}) -Extension package for @code{hpcguix-web}. - -@item @code{menu} (Vorgabe: @code{'()}) -Additional entry in page @code{menu}. - -@item @code{channels} (Vorgabe: @code{%default-channels}) -List of channels from which the package list is built (@pxref{Kanäle}). - -@item @code{package-list-expiration} (Vorgabe: @code{(* 12 3600)}) -The expiration time, in seconds, after which the package list is rebuilt -from the latest instances of the given channels. -@end table - -See the hpcguix-web repository for a -@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm, -complete example}. - -@item @code{package} (Vorgabe: @code{hpcguix-web}) -Das hpcguix-web-Paket, was benutzt werden soll. -@end table -@end deftp - -A typical hpcguix-web service declaration looks like this: - -@example -(service hpcguix-web-service-type - (hpcguix-web-configuration - (specs - #~(define site-config - (hpcweb-configuration - (title-prefix "Guix-HPC - ") - (menu '(("/about" "ABOUT")))))))) -@end example - -@quotation Anmerkung -The hpcguix-web service periodically updates the package list it publishes -by pulling channels from Git. To that end, it needs to access X.509 -certificates so that it can authenticate Git servers when communicating over -HTTPS, and it assumes that @file{/etc/ssl/certs} contains those -certificates. - -Thus, make sure to add @code{nss-certs} or another certificate package to -the @code{packages} field of your configuration. @ref{X.509-Zertifikate}, -for more information on X.509 certificates. -@end quotation - -@node Zertifikatsdienste -@subsection Zertifikatsdienste - -@cindex Web -@cindex HTTP, HTTPS -@cindex Let's Encrypt -@cindex TLS certificates -The @code{(gnu services certbot)} module provides a service to automatically -obtain a valid TLS certificate from the Let's Encrypt certificate -authority. These certificates can then be used to serve content securely -over HTTPS or other TLS-based protocols, with the knowledge that the client -will be able to verify the server's authenticity. - -@url{https://letsencrypt.org/, Let's Encrypt} provides the @code{certbot} -tool to automate the certification process. This tool first securely -generates a key on the server. It then makes a request to the Let's Encrypt -certificate authority (CA) to sign the key. The CA checks that the request -originates from the host in question by using a challenge-response protocol, -requiring the server to provide its response over HTTP. If that protocol -completes successfully, the CA signs the key, resulting in a certificate. -That certificate is valid for a limited period of time, and therefore to -continue to provide TLS services, the server needs to periodically ask the -CA to renew its signature. - -The certbot service automates this process: the initial key generation, the -initial certification request to the Let's Encrypt service, the web server -challenge/response integration, writing the certificate to disk, the -automated periodic renewals, and the deployment tasks associated with the -renewal (e.g.@: reloading services, copying keys with different -permissions). - -Certbot is run twice a day, at a random minute within the hour. It won't do -anything until your certificates are due for renewal or revoked, but running -it regularly would give your service a chance of staying online in case a -Let's Encrypt-initiated revocation happened for some reason. - -By using this service, you agree to the ACME Subscriber Agreement, which can -be found there: @url{https://acme-v01.api.letsencrypt.org/directory}. - -@defvr {Scheme Variable} certbot-service-type -A service type for the @code{certbot} Let's Encrypt client. Its value must -be a @code{certbot-configuration} record as in this example: - -@example -(define %nginx-deploy-hook - (program-file - "nginx-deploy-hook" - #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read))) - (kill pid SIGHUP)))) - -(service certbot-service-type - (certbot-configuration - (email "foo@@example.net") - (certificates - (list - (certificate-configuration - (domains '("example.net" "www.example.net")) - (deploy-hook %nginx-deploy-hook)) - (certificate-configuration - (domains '("bar.example.net"))))))) -@end example - -See below for details about @code{certbot-configuration}. -@end defvr - -@deftp {Data Type} certbot-configuration -Data type representing the configuration of the @code{certbot} service. -This type has the following parameters: - -@table @asis -@item @code{package} (default: @code{certbot}) -The certbot package to use. - -@item @code{webroot} (default: @code{/var/www}) -The directory from which to serve the Let's Encrypt challenge/response -files. - -@item @code{certificates} (default: @code{()}) -A list of @code{certificates-configuration}s for which to generate -certificates and request signatures. Each certificate has a @code{name} and -several @code{domains}. - -@item @code{email} -Mandatory email used for registration, recovery contact, and important -account notifications. - -@item @code{rsa-key-size} (default: @code{2048}) -Size of the RSA key. - -@item @code{default-location} (default: @i{see below}) -The default @code{nginx-location-configuration}. Because @code{certbot} -needs to be able to serve challenges and responses, it needs to be able to -run a web server. It does so by extending the @code{nginx} web service with -an @code{nginx-server-configuration} listening on the @var{domains} on port -80, and which has a @code{nginx-location-configuration} for the -@code{/.well-known/} URI path subspace used by Let's Encrypt. @xref{Web-Dienste}, for more on these nginx configuration data types. - -Requests to other URL paths will be matched by the @code{default-location}, -which if present is added to all @code{nginx-server-configuration}s. - -By default, the @code{default-location} will issue a redirect from -@code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving -you to define what to serve on your site via @code{https}. - -Pass @code{#f} to not issue a default location. -@end table -@end deftp - -@deftp {Data Type} certificate-configuration -Data type representing the configuration of a certificate. This type has -the following parameters: - -@table @asis -@item @code{name} (default: @i{see below}) -This name is used by Certbot for housekeeping and in file paths; it doesn't -affect the content of the certificate itself. To see certificate names, run -@code{certbot certificates}. - -Its default is the first provided domain. - -@item @code{domains} (default: @code{()}) -The first domain provided will be the subject CN of the certificate, and all -domains will be Subject Alternative Names on the certificate. - -@item @code{deploy-hook} (default: @code{#f}) -Command to be run in a shell once for each successfully issued certificate. -For this command, the shell variable @code{$RENEWED_LINEAGE} will point to -the config live subdirectory (for example, -@samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates -and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a -space-delimited list of renewed certificate domains (for example, -@samp{"example.com www.example.com"}. - -@end table -@end deftp - -For each @code{certificate-configuration}, the certificate is saved to -@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved -to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. -@node DNS-Dienste -@subsection DNS-Dienste -@cindex DNS (domain name system) -@cindex domain name system (DNS) - -The @code{(gnu services dns)} module provides services related to the -@dfn{domain name system} (DNS). It provides a server service for hosting an -@emph{authoritative} DNS server for multiple zones, slave or master. This -service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a caching -and forwarding DNS server for the LAN, which uses -@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}. - -@subsubheading Knot-Dienst - -An example configuration of an authoritative server for two zones, one -master and one slave, is: - -@lisp -(define-zone-entries example.org.zone -;; Name TTL Class Type Data - ("@@" "" "IN" "A" "127.0.0.1") - ("@@" "" "IN" "NS" "ns") - ("ns" "" "IN" "A" "127.0.0.1")) - -(define master-zone - (knot-zone-configuration - (domain "example.org") - (zone (zone-file - (origin "example.org") - (entries example.org.zone))))) - -(define slave-zone - (knot-zone-configuration - (domain "plop.org") - (dnssec-policy "default") - (master (list "plop-master")))) - -(define plop-master - (knot-remote-configuration - (id "plop-master") - (address (list "208.76.58.171")))) - -(operating-system - ;; ... - (services (cons* (service knot-service-type - (knot-configuration - (remotes (list plop-master)) - (zones (list master-zone slave-zone)))) - ;; ... - %base-services))) -@end lisp - -@deffn {Scheme Variable} knot-service-type -This is the type for the Knot DNS server. - -Knot DNS is an authoritative DNS server, meaning that it can serve multiple -zones, that is to say domain names you would buy from a registrar. This -server is not a resolver, meaning that it can only resolve names for which -it is authoritative. This server can be configured to serve zones as a -master server or a slave server as a per-zone basis. Slave zones will get -their data from masters, and will serve it as an authoritative server. From -the point of view of a resolver, there is no difference between master and -slave. - -The following data types are used to configure the Knot DNS server: -@end deffn - -@deftp {Data Type} knot-key-configuration -Data type representing a key. This type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{algorithm} (default: @code{#f}) -The algorithm to use. Choose between @code{#f}, @code{'hmac-md5}, -@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, -@code{'hmac-sha384} and @code{'hmac-sha512}. - -@item @code{secret} (default: @code{""}) -The secret key itself. - -@end table -@end deftp - -@deftp {Data Type} knot-acl-configuration -Data type representing an Access Control List (ACL) configuration. This -type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for ether configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -An ordered list of IP addresses, network subnets, or network ranges -represented with strings. The query must match one of them. Empty value -means that address match is not required. - -@item @code{key} (default: @code{'()}) -An ordered list of references to keys represented with strings. The string -must match a key ID defined in a @code{knot-key-configuration}. No key -means that a key is not require to match that ACL. - -@item @code{action} (default: @code{'()}) -An ordered list of actions that are permitted or forbidden by this ACL. -Possible values are lists of zero or more elements from @code{'transfer}, -@code{'notify} and @code{'update}. - -@item @code{deny?} (default: @code{#f}) -When true, the ACL defines restrictions. Listed actions are forbidden. -When false, listed actions are allowed. - -@end table -@end deftp - -@deftp {Data Type} zone-entry -Data type represnting a record entry in a zone file. This type has the -following parameters: - -@table @asis -@item @code{name} (default: @code{"@@"}) -The name of the record. @code{"@@"} refers to the origin of the zone. -Names are relative to the origin of the zone. For example, in the -@code{example.org} zone, @code{"ns.example.org"} actually refers to -@code{ns.example.org.example.org}. Names ending with a dot are absolute, -which means that @code{"ns.example.org."} refers to @code{ns.example.org}. - -@item @code{ttl} (default: @code{""}) -The Time-To-Live (TTL) of this record. If not set, the default TTL is used. - -@item @code{class} (default: @code{"IN"}) -The class of the record. Knot currently supports only @code{"IN"} and -partially @code{"CH"}. - -@item @code{type} (default: @code{"A"}) -The type of the record. Common types include A (IPv4 address), AAAA (IPv6 -address), NS (Name Server) and MX (Mail eXchange). Many other types are -defined. - -@item @code{data} (default: @code{""}) -The data contained in the record. For instance an IP address associated -with an A record, or a domain name associated with an NS record. Remember -that domain names are relative to the origin unless they end with a dot. - -@end table -@end deftp - -@deftp {Data Type} zone-file -Data type representing the content of a zone file. This type has the -following parameters: - -@table @asis -@item @code{entries} (default: @code{'()}) -The list of entries. The SOA record is taken care of, so you don't need to -put it in the list of entries. This list should probably contain an entry -for your primary authoritative DNS server. Other than using a list of -entries directly, you can use @code{define-zone-entries} to define a object -containing the list of entries more easily, that you can later pass to the -@code{entries} field of the @code{zone-file}. - -@item @code{origin} (default: @code{""}) -The name of your zone. This parameter cannot be empty. - -@item @code{ns} (default: @code{"ns"}) -The domain of your primary authoritative DNS server. The name is relative -to the origin, unless it ends with a dot. It is mandatory that this primary -DNS server corresponds to an NS record in the zone and that it is associated -to an IP address in the list of entries. - -@item @code{mail} (default: @code{"hostmaster"}) -An email address people can contact you at, as the owner of the zone. This -is translated as @code{<mail>@@<origin>}. - -@item @code{serial} (default: @code{1}) -The serial number of the zone. As this is used to keep track of changes by -both slaves and resolvers, it is mandatory that it @emph{never} decreases. -Always increment it when you make a change in your zone. - -@item @code{refresh} (default: @code{(* 2 24 3600)}) -The frequency at which slaves will do a zone transfer. This value is a -number of seconds. It can be computed by multiplications or with -@code{(string->duration)}. - -@item @code{retry} (default: @code{(* 15 60)}) -The period after which a slave will retry to contact its master when it -fails to do so a first time. - -@item @code{expiry} (default: @code{(* 14 24 3600)}) -Default TTL of records. Existing records are considered correct for at most -this amount of time. After this period, resolvers will invalidate their -cache and check again that it still exists. - -@item @code{nx} (default: @code{3600}) -Default TTL of inexistant records. This delay is usually short because you -want your new domains to reach everyone quickly. - -@end table -@end deftp - -@deftp {Data Type} knot-remote-configuration -Data type representing a remote configuration. This type has the following -parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this remote. IDs -must be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -An ordered list of destination IP addresses. Addresses are tried in -sequence. An optional port can be given with the @@ separator. For -instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53. - -@item @code{via} (default: @code{'()}) -An ordered list of source IP addresses. An empty list will have Knot choose -an appropriate source IP. An optional port can be given with the @@ -separator. The default is to choose at random. - -@item @code{key} (default: @code{#f}) -A reference to a key, that is a string containing the identifier of a key -defined in a @code{knot-key-configuration} field. - -@end table -@end deftp - -@deftp {Data Type} knot-keystore-configuration -Data type representing a keystore to hold dnssec keys. This type has the -following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the keystore. It must not be empty. - -@item @code{backend} (default: @code{'pem}) -The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}. - -@item @code{config} (default: @code{"/var/lib/knot/keys/keys"}) -The configuration string of the backend. An example for the PKCS#11 is: -@code{"pkcs11:token=knot;pin-value=1234 -/gnu/store/.../lib/pkcs11/libsofthsm2.so"}. For the pem backend, the string -reprensents a path in the file system. - -@end table -@end deftp - -@deftp {Data Type} knot-policy-configuration -Data type representing a dnssec policy. Knot DNS is able to automatically -sign your zones. It can either generate and manage your keys automatically -or use keys that you generate. - -Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that -is used to sign the second, and a Zone Signing Key (ZSK) that is used to -sign the zone. In order to be trusted, the KSK needs to be present in the -parent zone (usually a top-level domain). If your registrar supports -dnssec, you will have to send them your KSK's hash so they can add a DS -record in their zone. This is not automated and need to be done each time -you change your KSK. - -The policy also defines the lifetime of keys. Usually, ZSK can be changed -easily and use weaker cryptographic functions (they use lower parameters) in -order to sign records quickly, so they are changed often. The KSK however -requires manual interaction with the registrar, so they are changed less -often and use stronger parameters because they sign only one record. - -This type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the policy. It must not be empty. - -@item @code{keystore} (default: @code{"default"}) -A reference to a keystore, that is a string containing the identifier of a -keystore defined in a @code{knot-keystore-configuration} field. The -@code{"default"} identifier means the default keystore (a kasp database that -was setup by this service). - -@item @code{manual?} (default: @code{#f}) -Whether the key management is manual or automatic. - -@item @code{single-type-signing?} (default: @code{#f}) -When @code{#t}, use the Single-Type Signing Scheme. - -@item @code{algorithm} (default: @code{"ecdsap256sha256"}) -An algorithm of signing keys and issued signatures. - -@item @code{ksk-size} (default: @code{256}) -The length of the KSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{zsk-size} (default: @code{256}) -The length of the ZSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{dnskey-ttl} (default: @code{'default}) -The TTL value for DNSKEY records added into zone apex. The special -@code{'default} value means same as the zone SOA TTL. - -@item @code{zsk-lifetime} (default: @code{(* 30 24 3600)}) -The period between ZSK publication and the next rollover initiation. - -@item @code{propagation-delay} (default: @code{(* 24 3600)}) -An extra delay added for each key rollover step. This value should be high -enough to cover propagation of data from the master server to all slaves. - -@item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)}) -A validity period of newly issued signatures. - -@item @code{rrsig-refresh} (default: @code{(* 7 24 3600)}) -A period how long before a signature expiration the signature will be -refreshed. - -@item @code{nsec3?} (default: @code{#f}) -When @code{#t}, NSEC3 will be used instead of NSEC. - -@item @code{nsec3-iterations} (default: @code{5}) -The number of additional times the hashing is performed. - -@item @code{nsec3-salt-length} (default: @code{8}) -The length of a salt field in octets, which is appended to the original -owner name before hashing. - -@item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)}) -The validity period of newly issued salt field. - -@end table -@end deftp - -@deftp {Data Type} knot-zone-configuration -Data type representing a zone served by Knot. This type has the following -parameters: - -@table @asis -@item @code{domain} (default: @code{""}) -The domain served by this configuration. It must not be empty. - -@item @code{file} (default: @code{""}) -The file where this zone is saved. This parameter is ignored by master -zones. Empty means default location that depends on the domain name. - -@item @code{zone} (default: @code{(zone-file)}) -The content of the zone file. This parameter is ignored by slave zones. It -must contain a zone-file record. - -@item @code{master} (default: @code{'()}) -A list of master remotes. When empty, this zone is a master. When set, -this zone is a slave. This is a list of remotes identifiers. - -@item @code{ddns-master} (default: @code{#f}) -The main master. When empty, it defaults to the first master in the list of -masters. - -@item @code{notify} (default: @code{'()}) -A list of slave remote identifiers. - -@item @code{acl} (default: @code{'()}) -A list of acl identifiers. - -@item @code{semantic-checks?} (default: @code{#f}) -When set, this adds more semantic checks to the zone. - -@item @code{disable-any?} (default: @code{#f}) -When set, this forbids queries of the ANY type. - -@item @code{zonefile-sync} (default: @code{0}) -The delay between a modification in memory and on disk. 0 means immediate -synchronization. - -@item @code{serial-policy} (default: @code{'increment}) -A policy between @code{'increment} and @code{'unixtime}. - -@end table -@end deftp - -@deftp {Data Type} knot-configuration -Data type representing the Knot configuration. This type has the following -parameters: - -@table @asis -@item @code{knot} (default: @code{knot}) -The Knot package. - -@item @code{run-directory} (default: @code{"/var/run/knot"}) -The run directory. This directory will be used for pid file and sockets. - -@item @code{listen-v4} (default: @code{"0.0.0.0"}) -An ip address on which to listen. - -@item @code{listen-v6} (default: @code{"::"}) -An ip address on which to listen. - -@item @code{listen-port} (default: @code{53}) -A port on which to listen. - -@item @code{keys} (default: @code{'()}) -The list of knot-key-configuration used by this configuration. - -@item @code{acls} (default: @code{'()}) -The list of knot-acl-configuration used by this configuration. - -@item @code{remotes} (default: @code{'()}) -The list of knot-remote-configuration used by this configuration. - -@item @code{zones} (default: @code{'()}) -The list of knot-zone-configuration used by this configuration. - -@end table -@end deftp - -@subsubheading Dnsmasq-Dienst - -@deffn {Scheme Variable} dnsmasq-service-type -This is the type of the dnsmasq service, whose value should be an -@code{dnsmasq-configuration} object as in this example: - -@example -(service dnsmasq-service-type - (dnsmasq-configuration - (no-resolv? #t) - (servers '("192.168.1.1")))) -@end example -@end deffn - -@deftp {Datentyp} dnsmasq-configuration -Repräsentiert die dnsmasq-Konfiguration. - -@table @asis -@item @code{package} (Vorgabe: @var{dnsmasq}) -Package object of the dnsmasq server. - -@item @code{no-hosts?} (Vorgabe: @code{#f}) -When true, don't read the hostnames in /etc/hosts. - -@item @code{port} (Vorgabe: @code{53}) -The port to listen on. Setting this to zero completely disables DNS -responses, leaving only DHCP and/or TFTP functions. - -@item @code{local-service?} (Vorgabe: @code{#t}) -Accept DNS queries only from hosts whose address is on a local subnet, ie a -subnet for which an interface exists on the server. - -@item @code{listen-addresses} (Vorgabe: @code{'()}) -Listen on the given IP addresses. - -@item @code{resolv-file} (Vorgabe: @code{"/etc/resolv.conf"}) -The file to read the IP address of the upstream nameservers from. - -@item @code{no-resolv?} (Vorgabe: @code{#f}) -When true, don't read @var{resolv-file}. - -@item @code{servers} (default: @code{'()}) -Specify IP address of upstream servers directly. - -@item @code{cache-size} (Vorgabe: @code{150}) -Set the size of dnsmasq's cache. Setting the cache size to zero disables -caching. - -@item @code{negative-cache?} (Vorgabe: @code{#t}) -When false, disable negative caching. - -@end table -@end deftp - -@subsubheading ddclient-Dienst - -@cindex ddclient -The ddclient service described below runs the ddclient daemon, which takes -care of automatically updating DNS entries for service providers such as -@uref{https://dyn.com/dns/, Dyn}. - -The following example show instantiates the service with its default -configuration: - -@example -(service ddclient-service-type) -@end example - -Note that ddclient needs to access credentials that are stored in a -@dfn{secret file}, by default @file{/etc/ddclient/secrets} (see -@code{secret-file} below.) You are expected to create this file manually, -in an ``out-of-band'' fashion (you @emph{could} make this file part of the -service configuration, for instance by using @code{plain-file}, but it will -be world-readable @i{via} @file{/gnu/store}.) See the examples in the -@file{share/ddclient} directory of the @code{ddclient} package. - -@c %start of fragment - -Available @code{ddclient-configuration} fields are: - -@deftypevr {@code{ddclient-configuration} parameter} package ddclient -Das ddclient-Paket. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} integer daemon -The period after which ddclient will retry to check IP and domain name. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean syslog -Use syslog for the output. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail -Mail to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail-failure -Den Nutzer per Mail bei fehlgeschlagenen Aktualisierungen benachrichtigen. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string pid -PID-Datei für den ddclient. - -Defaults to @samp{"/var/run/ddclient/ddclient.pid"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean ssl -Enable SSL support. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string user -Specifies the user name or ID that is used when running ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string group -Group of the user who will run the ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string secret-file -Secret file which will be appended to @file{ddclient.conf} file. This file -contains credentials for use by ddclient. You are expected to create it -manually. - -Defaults to @samp{"/etc/ddclient/secrets.conf"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} list extra-options -Extra options will be appended to @file{ddclient.conf} file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - - -@node VPN-Dienste -@subsection VPN-Dienste -@cindex VPN (virtual private network) -@cindex virtual private network (VPN) - -The @code{(gnu services vpn)} module provides services related to -@dfn{virtual private networks} (VPNs). It provides a @emph{client} service -for your machine to connect to a VPN, and a @emph{servire} service for your -machine to host a VPN. Both services use @uref{https://openvpn.net/, -OpenVPN}. - -@deffn {Scheme Procedure} openvpn-client-service @ - [#:config (openvpn-client-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a client. -@end deffn - -@deffn {Scheme Procedure} openvpn-server-service @ - [#:config (openvpn-server-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a server. - -Both can be run simultaneously. -@end deffn - -@c %automatically generated documentation - -Available @code{openvpn-client-configuration} fields are: - -@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file -The OpenVPN pid file. - -Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} proto proto -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} dev dev -The device type used to represent the VPN connection. - -Defaults to @samp{tun}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string ca -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string cert -The certificate of the machine the daemon is running on. It should be -signed by the authority given in @code{ca}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string key -The key of the machine the daemon is running on. It must be the key whose -certificate is @code{cert}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo? -Whether to use the lzo compression algorithm. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key? -Don't re-read key files across SIGUSR1 or --ping-restart. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun? -Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 -or --ping-restart restarts. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity -Verbosity level. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth -Add an additional layer of HMAC authentication on top of the TLS control -channel to protect against DoS attacks. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? -Whether to check the server certificate has server usage extension. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} bind bind? -Bind to a specific local port number. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry? -Retry resolving server address. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote -A list of remote servers to connect to. - -Defaults to @samp{()}. - -Available @code{openvpn-remote-configuration} fields are: - -@deftypevr {@code{openvpn-remote-configuration} parameter} string name -Server name. - -Defaults to @samp{"my-server"}. - -@end deftypevr - -@deftypevr {@code{openvpn-remote-configuration} parameter} number port -Port number the server listens to. - -Defaults to @samp{1194}. - -@end deftypevr - -@end deftypevr -@c %end of automatic openvpn-client documentation - -@c %automatically generated documentation - -Available @code{openvpn-server-configuration} fields are: - -@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file -The OpenVPN pid file. - -Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} proto proto -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} dev dev -The device type used to represent the VPN connection. - -Defaults to @samp{tun}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string ca -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string cert -The certificate of the machine the daemon is running on. It should be -signed by the authority given in @code{ca}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string key -The key of the machine the daemon is running on. It must be the key whose -certificate is @code{cert}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo? -Whether to use the lzo compression algorithm. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key? -Don't re-read key files across SIGUSR1 or --ping-restart. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun? -Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 -or --ping-restart restarts. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity -Verbosity level. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth -Add an additional layer of HMAC authentication on top of the TLS control -channel to protect against DoS attacks. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number port -Specifies the port number on which the server listens. - -Defaults to @samp{1194}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server -An ip and mask specifying the subnet inside the virtual network. - -Defaults to @samp{"10.8.0.0 255.255.255.0"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6 -A CIDR notation specifying the IPv6 subnet inside the virtual network. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string dh -The Diffie-Hellman parameters file. - -Defaults to @samp{"/etc/openvpn/dh2048.pem"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist -The file that records client IPs. - -Defaults to @samp{"/etc/openvpn/ipp.txt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway? -When true, the server will act as a gateway for its clients. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client? -When true, clients are allowed to talk to each other inside the VPN. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive -Causes ping-like messages to be sent back and forth over the link so that -each side knows when the other side has gone down. @code{keepalive} -requires a pair. The first element is the period of the ping sending, and -the second element is the timeout before considering the other side down. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients -The maximum number of clients. - -Defaults to @samp{100}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string status -The status file. This file shows a small report on current connection. It -is truncated and rewritten every minute. - -Defaults to @samp{"/var/run/openvpn/status"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir -The list of configuration for some clients. - -Defaults to @samp{()}. - -Available @code{openvpn-ccd-configuration} fields are: - -@deftypevr {@code{openvpn-ccd-configuration} parameter} string name -Client name. - -Defaults to @samp{"client"}. - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute -Client own network - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push -Client VPN IP. - -Defaults to @samp{#f}. - -@end deftypevr - -@end deftypevr - - -@c %end of automatic openvpn-server documentation - - -@node Network File System -@subsection Network File System -@cindex NFS - -The @code{(gnu services nfs)} module provides the following services, which -are most commonly used in relation to mounting or exporting directory trees -as @dfn{network file systems} (NFS). - -@subsubheading RPC Bind Service -@cindex rpcbind - -The RPC Bind service provides a facility to map program numbers into -universal addresses. Many NFS related services use this facility. Hence it -is automatically started when a dependent service starts. - -@defvr {Scheme Variable} rpcbind-service-type -A service type for the RPC portmapper daemon. -@end defvr - - -@deftp {Data Type} rpcbind-configuration -Data type representing the configuration of the RPC Bind Service. This type -has the following parameters: -@table @asis -@item @code{rpcbind} (default: @code{rpcbind}) -The rpcbind package to use. - -@item @code{warm-start?} (default: @code{#t}) -If this parameter is @code{#t}, then the daemon will read a state file on -startup thus reloading state information saved by a previous instance. -@end table -@end deftp - - -@subsubheading Pipefs Pseudo File System -@cindex pipefs -@cindex rpc_pipefs - -The pipefs file system is used to transfer NFS related data between the -kernel and user space programs. - -@defvr {Scheme Variable} pipefs-service-type -A service type for the pipefs pseudo file system. -@end defvr - -@deftp {Data Type} pipefs-configuration -Data type representing the configuration of the pipefs pseudo file system -service. This type has the following parameters: -@table @asis -@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory to which the file system is to be attached. -@end table -@end deftp - - -@subsubheading GSS Daemon Service -@cindex GSSD -@cindex GSS -@cindex global security system - -The @dfn{global security system} (GSS) daemon provides strong security for -RPC based protocols. Before exchanging RPC requests an RPC client must -establish a security context. Typically this is done using the Kerberos -command @command{kinit} or automatically at login time using PAM services -(@pxref{Kerberos-Dienste}). - -@defvr {Scheme Variable} gss-service-type -A service type for the Global Security System (GSS) daemon. -@end defvr - -@deftp {Data Type} gss-configuration -Data type representing the configuration of the GSS daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.gssd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@end table -@end deftp - - -@subsubheading IDMAP Daemon Service -@cindex idmapd -@cindex name mapper - -The idmap daemon service provides mapping between user IDs and user names. -Typically it is required in order to access file systems mounted via NFSv4. - -@defvr {Scheme Variable} idmap-service-type -A service type for the Identity Mapper (IDMAP) daemon. -@end defvr - -@deftp {Data Type} idmap-configuration -Data type representing the configuration of the IDMAP daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.idmapd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@item @code{domain} (default: @code{#f}) -The local NFSv4 domain name. This must be a string or @code{#f}. If it is -@code{#f} then the daemon will use the host's fully qualified domain name. - -@end table -@end deftp - -@node Kontinuierliche Integration -@subsection Kontinuierliche Integration - -@cindex continuous integration -@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a -continuous integration tool for Guix. It can be used both for development -and for providing substitutes to others (@pxref{Substitute}). - -The @code{(gnu services cuirass)} module provides the following service. - -@defvr {Scheme Procedure} cuirass-service-type -The type of the Cuirass service. Its value must be a -@code{cuirass-configuration} object, as described below. -@end defvr - -To add build jobs, you have to set the @code{specifications} field of the -configuration. Here is an example of a service that polls the Guix -repository and builds the packages from a manifest. Some of the packages -are defined in the @code{"custom-packages"} input, which is the equivalent -of @code{GUIX_PACKAGE_PATH}. - -@example -(define %cuirass-specs - #~(list - '((#:name . "my-manifest") - (#:load-path-inputs . ("guix")) - (#:package-path-inputs . ("custom-packages")) - (#:proc-input . "guix") - (#:proc-file . "build-aux/cuirass/gnu-system.scm") - (#:proc . cuirass-jobs) - (#:proc-args . ((subset . "manifests") - (systems . ("x86_64-linux")) - (manifests . (("config" . "guix/manifest.scm"))))) - (#:inputs . (((#:name . "guix") - (#:url . "git://git.savannah.gnu.org/guix.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t)) - ((#:name . "config") - (#:url . "git://git.example.org/config.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t)) - ((#:name . "custom-packages") - (#:url . "git://git.example.org/custom-packages.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t))))))) - -(service cuirass-service-type - (cuirass-configuration - (specifications %cuirass-specs))) -@end example - -While information related to build jobs is located directly in the -specifications, global settings for the @command{cuirass} process are -accessible in other @code{cuirass-configuration} fields. - -@deftp {Data Type} cuirass-configuration -Data type representing the configuration of Cuirass. - -@table @asis -@item @code{log-file} (default: @code{"/var/log/cuirass.log"}) -Location of the log file. - -@item @code{cache-directory} (default: @code{"/var/cache/cuirass"}) -Location of the repository cache. - -@item @code{user} (default: @code{"cuirass"}) -Owner of the @code{cuirass} process. - -@item @code{group} (default: @code{"cuirass"}) -Owner's group of the @code{cuirass} process. - -@item @code{interval} (default: @code{60}) -Number of seconds between the poll of the repositories followed by the -Cuirass jobs. - -@item @code{database} (Vorgabe: @code{"/var/lib/cuirass/cuirass.db"}) -Location of sqlite database which contains the build results and previously -added specifications. - -@item @code{ttl} (Vorgabe: @code{(* 30 24 3600)}) -Specifies the time-to-live (TTL) in seconds of garbage collector roots that -are registered for build results. This means that build results are -protected from garbage collection for at least @var{ttl} seconds. - -@item @code{port} (default: @code{8081}) -Port number used by the HTTP server. - -@item --listen=@var{Host} -Listen on the network interface for @var{host}. The default is to accept -connections from localhost. - -@item @code{specifications} (default: @code{#~'()}) -A gexp (@pxref{G-Ausdrücke}) that evaluates to a list of specifications, -where a specification is an association list (@pxref{Associations Lists,,, -guile, GNU Guile Reference Manual}) whose keys are keywords -(@code{#:keyword-example}) as shown in the example above. - -@item @code{use-substitutes?} (default: @code{#f}) -This allows using substitutes to avoid building every dependencies of a job -from source. - -@item @code{one-shot?} (default: @code{#f}) -Only evaluate specifications and build derivations once. - -@item @code{fallback?} (default: @code{#f}) -When substituting a pre-built binary fails, fall back to building packages -locally. - -@item @code{cuirass} (default: @code{cuirass}) -The Cuirass package to use. -@end table -@end deftp - -@node Dienste zur Stromverbrauchsverwaltung -@subsection Dienste zur Stromverbrauchsverwaltung - -@cindex tlp -@cindex power management with TLP -@subsubheading TLP-Daemon - -The @code{(gnu services pm)} module provides a Guix service definition for -the Linux power management tool TLP. - -TLP enables various powersaving modes in userspace and kernel. Contrary to -@code{upower-service}, it is not a passive, monitoring tool, as it will -apply custom settings each time a new power source is detected. More -information can be found at @uref{http://linrunner.de/en/tlp/tlp.html, TLP -home page}. - -@deffn {Scheme Variable} tlp-service-type -The service type for the TLP tool. Its value should be a valid TLP -configuration (see below). To use the default settings, simply write: -@example -(service tlp-service-type) -@end example -@end deffn - -By default TLP does not need much configuration but most TLP parameters can -be tweaked using @code{tlp-configuration}. - -Each parameter definition is preceded by its type; for example, -@samp{boolean foo} indicates that the @code{foo} parameter should be -specified as a boolean. Types starting with @code{maybe-} denote parameters -that won't show up in TLP config file when their value is @code{'disabled}. - -@c The following documentation was initially generated by -@c (generate-tlp-documentation) in (gnu services pm). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as TLP updates. - -Available @code{tlp-configuration} fields are: - -@deftypevr {@code{tlp-configuration} parameter} package tlp -The TLP package. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable? -Set to true if you wish to enable TLP. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode -Default mode when no power supply can be detected. Alternatives are AC and -BAT. - -Defaults to @samp{"AC"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac -Number of seconds Linux kernel has to wait after the disk goes idle, before -syncing on AC. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat -Same as @code{disk-idle-ac} but on BAT mode. - -Defaults to @samp{2}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac -Dirty pages flushing periodicity, expressed in seconds. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat -Same as @code{max-lost-work-secs-on-ac} but on BAT mode. - -Defaults to @samp{60}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac -CPU frequency scaling governor on AC mode. With intel_pstate driver, -alternatives are powersave and performance. With acpi-cpufreq driver, -alternatives are ondemand, powersave, performance and conservative. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat -Same as @code{cpu-scaling-governor-on-ac} but on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac -Set the min available frequency for the scaling governor on AC. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac -Set the max available frequency for the scaling governor on AC. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat -Set the min available frequency for the scaling governor on BAT. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat -Set the max available frequency for the scaling governor on BAT. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac -Limit the min P-state to control the power dissipation of the CPU, in AC -mode. Values are stated as a percentage of the available performance. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac -Limit the max P-state to control the power dissipation of the CPU, in AC -mode. Values are stated as a percentage of the available performance. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat -Same as @code{cpu-min-perf-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat -Same as @code{cpu-max-perf-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac? -Enable CPU turbo boost feature on AC mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat? -Same as @code{cpu-boost-on-ac?} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac? -Allow Linux kernel to minimize the number of CPU cores/hyper-threads used -under light load conditions. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat? -Same as @code{sched-powersave-on-ac?} but on BAT mode. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog? -Enable Linux kernel NMI watchdog. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls -For Linux kernels with PHC patch applied, change CPU voltages. An example -value would be @samp{"F:V F:V F:V F:V"}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac -Set CPU performance versus energy saving policy on AC. Alternatives are -performance, normal, powersave. - -Defaults to @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat -Same as @code{energy-perf-policy-ac} but on BAT mode. - -Defaults to @samp{"powersave"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices -Hard disk devices. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac -Hard disk advanced power management level. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat -Same as @code{disk-apm-bat} but on BAT mode. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac -Hard disk spin down timeout. One value has to be specified for each -declared hard disk. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat -Same as @code{disk-spindown-timeout-on-ac} but on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched -Select IO scheduler for disk devices. One value has to be specified for -each declared hard disk. Example alternatives are cfq, deadline and noop. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac -SATA aggressive link power management (ALPM) level. Alternatives are -min_power, medium_power, max_performance. - -Defaults to @samp{"max_performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat -Same as @code{sata-linkpwr-ac} but on BAT mode. - -Defaults to @samp{"min_power"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist -Exclude specified SATA host devices for link power management. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac? -Enable Runtime Power Management for AHCI controller and disks on AC mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat? -Same as @code{ahci-runtime-pm-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout -Seconds of inactivity before disk is suspended. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac -PCI Express Active State Power Management level. Alternatives are default, -performance, powersave. - -Defaults to @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat -Same as @code{pcie-aspm-ac} but on BAT mode. - -Defaults to @samp{"powersave"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac -Radeon graphics clock speed level. Alternatives are low, mid, high, auto, -default. - -Defaults to @samp{"high"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat -Same as @code{radeon-power-ac} but on BAT mode. - -Defaults to @samp{"low"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac -Radeon dynamic power management method (DPM). Alternatives are battery, -performance. - -Defaults to @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat -Same as @code{radeon-dpm-state-ac} but on BAT mode. - -Defaults to @samp{"battery"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac -Radeon DPM performance level. Alternatives are auto, low, high. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat -Same as @code{radeon-dpm-perf-ac} but on BAT mode. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac? -Wifi power saving mode. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat? -Same as @code{wifi-power-ac?} but on BAT mode. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable? -Disable wake on LAN. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac -Timeout duration in seconds before activating audio power saving on Intel -HDA and AC97 devices. A value of 0 disables power saving. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat -Same as @code{sound-powersave-ac} but on BAT mode. - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller? -Disable controller in powersaving mode on Intel HDA devices. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat? -Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be powered -on again by releasing (and reinserting) the eject lever or by pressing the -disc eject button on newer models. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string bay-device -Name of the optical drive device to power off. - -Defaults to @samp{"sr0"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac -Runtime Power Management for PCI(e) bus devices. Alternatives are on and -auto. - -Defaults to @samp{"on"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat -Same as @code{runtime-pm-ac} but on BAT mode. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all? -Runtime Power Management for all PCI(e) bus devices, except blacklisted -ones. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist -Exclude specified PCI(e) device addresses from Runtime Power Management. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist -Exclude PCI(e) devices assigned to the specified drivers from Runtime Power -Management. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend? -Enable USB autosuspend feature. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist -Exclude specified devices from USB autosuspend. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan? -Exclude WWAN devices from USB autosuspend. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist -Include specified devices into USB autosuspend, even if they are already -excluded by the driver or via @code{usb-blacklist-wwan?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? -Enable USB autosuspend before shutdown. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup? -Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on -system startup. - -Defaults to @samp{#f}. - -@end deftypevr - -@cindex thermald -@cindex CPU frequency scaling with thermald -@subsubheading Thermald-Daemon - -The @code{(gnu services pm)} module provides an interface to thermald, a CPU -frequency scaling service which helps prevent overheating. - -@defvr {Scheme Variable} thermald-service-type -This is the service type for @uref{https://01.org/linux-thermal-daemon/, -thermald}, the Linux Thermal Daemon, which is responsible for controlling -the thermal state of processors and preventing overheating. -@end defvr - -@deftp {Data Type} thermald-configuration -Data type representing the configuration of @code{thermald-service-type}. - -@table @asis -@item @code{ignore-cpuid-check?} (default: @code{#f}) -Ignore cpuid check for supported CPU models. - -@item @code{thermald} (default: @var{thermald}) -Package object of thermald. - -@end table -@end deftp - -@node Audio-Dienste -@subsection Audio-Dienste - -The @code{(gnu services audio)} module provides a service to start MPD (the -Music Player Daemon). - -@cindex mpd -@subsubheading Music Player Daemon - -The Music Player Daemon (MPD) is a service that can play music while being -controlled from the local machine or over the network by a variety of -clients. - -The following example shows how one might run @code{mpd} as user -@code{"bob"} on port @code{6666}. It uses pulseaudio for output. - -@example -(service mpd-service-type - (mpd-configuration - (user "bob") - (port "6666"))) -@end example - -@defvr {Scheme Variable} mpd-service-type -The service type for @command{mpd} -@end defvr - -@deftp {Data Type} mpd-configuration -Data type representing the configuration of @command{mpd}. - -@table @asis -@item @code{user} (default: @code{"mpd"}) -The user to run mpd as. - -@item @code{music-dir} (default: @code{"~/Music"}) -The directory to scan for music files. - -@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"}) -The directory to store playlists. - -@item @code{port} (default: @code{"6600"}) -The port to run mpd on. - -@item @code{address} (default: @code{"any"}) -The address that mpd will bind to. To use a Unix domain socket, an absolute -path can be specified here. - -@end table -@end deftp - -@node Virtualisierungsdienste -@subsection Virtualization services - -The @code{(gnu services virtualization)} module provides services for the -libvirt and virtlog daemons, as well as other virtualization-related -services. - -@subsubheading Libvirt daemon -@code{libvirtd} is the server side daemon component of the libvirt -virtualization management system. This daemon runs on host servers and -performs required management tasks for virtualized guests. - -@deffn {Scheme Variable} libvirt-service-type -This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its -value must be a @code{libvirt-configuration}. - -@example -(service libvirt-service-type - (libvirt-configuration - (unix-sock-group "libvirt") - (tls-port "16555"))) -@end example -@end deffn - -@c Auto-generated with (generate-libvirt-documentation) -Available @code{libvirt-configuration} fields are: - -@deftypevr {@code{libvirt-configuration} parameter} package libvirt -Libvirt package. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls? -Flag listening for secure TLS connections on the public TCP/IP port. must -set @code{listen} for this to have any effect. - -It is necessary to setup a CA and issue server certificates before using -this capability. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp? -Listen for unencrypted TCP connections on the public TCP/IP port. must set -@code{listen} for this to have any effect. - -Using the TCP socket requires SASL authentication by default. Only SASL -mechanisms which support data encryption are allowed. This is DIGEST_MD5 -and GSSAPI (Kerberos5) - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tls-port -Port for accepting secure TLS connections This can be a port number, or -service name - -Defaults to @samp{"16514"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tcp-port -Port for accepting insecure TCP connections This can be a port number, or -service name - -Defaults to @samp{"16509"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string listen-addr -IP address or hostname used for client connections. - -Defaults to @samp{"0.0.0.0"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv? -Flag toggling mDNS advertisement of the libvirt service. - -Alternatively can disable for all services on a host by stopping the Avahi -daemon. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string mdns-name -Default mDNS advertisement name. This must be unique on the immediate -broadcast network. - -Defaults to @samp{"Virtualization Host <hostname>"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group -UNIX domain socket group ownership. This can be used to allow a 'trusted' -set of users access to management capabilities without becoming root. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms -UNIX socket permissions for the R/O socket. This is used for monitoring VM -status only. - -Defaults to @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms -UNIX socket permissions for the R/W socket. Default allows only root. If -PolicyKit is enabled on the socket, the default will change to allow -everyone (eg, 0777) - -Defaults to @samp{"0770"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms -UNIX socket permissions for the admin socket. Default allows only owner -(root), do not change it unless you are sure to whom you are exposing the -access to. - -Defaults to @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir -The directory in which sockets will be found/created. - -Defaults to @samp{"/var/run/libvirt"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro -Authentication scheme for UNIX read-only sockets. By default socket -permissions allow anyone to connect - -Defaults to @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw -Authentication scheme for UNIX read-write sockets. By default socket -permissions only allow root. If PolicyKit support was compiled into -libvirt, the default will be to use 'polkit' auth. - -Defaults to @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-tcp -Authentication scheme for TCP sockets. If you don't enable SASL, then all -TCP traffic is cleartext. Don't do this outside of a dev/test scenario. - -Defaults to @samp{"sasl"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-tls -Authentication scheme for TLS sockets. TLS sockets already have encryption -provided by the TLS layer, and limited authentication is done by -certificates. - -It is possible to make use of any SASL authentication mechanism as well, by -using 'sasl' for this option - -Defaults to @samp{"none"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers -API access control scheme. - -By default an authenticated user is allowed access to all APIs. Access -drivers can place restrictions on this. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string key-file -Server key file path. If set to an empty string, then no private key is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string cert-file -Server key file path. If set to an empty string, then no certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string ca-file -Server key file path. If set to an empty string, then no CA certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string crl-file -Certificate revocation list path. If set to an empty string, then no CRL is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert -Disable verification of our own server certificates. - -When libvirtd starts it performs some sanity checks against its own -certificates. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert -Disable verification of client certificates. - -Client certificate verification is the primary authentication mechanism. -Any client which does not present a certificate signed by the CA will be -rejected. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list -Whitelist of allowed x509 Distinguished Name. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames -Whitelist of allowed SASL usernames. The format for username depends on the -SASL authentication mechanism. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tls-priority -Override the compile time default TLS priority string. The default is -usually "NORMAL" unless overridden at build time. Only set this is it is -desired for libvirt to deviate from the global default settings. - -Defaults to @samp{"NORMAL"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{5000}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients -Maximum length of queue of connections waiting to be accepted by the -daemon. Note, that some protocols supporting retransmission may obey this -so that a later reattempt at connection succeeds. - -Defaults to @samp{1000}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients -Maximum length of queue of accepted but not yet authenticated clients. Set -this to zero to turn this feature off - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer min-workers -Number of workers to start up initially. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-workers -Maximum number of worker threads. - -If the number of active clients exceeds @code{min-workers}, then more -threads are spawned, up to max_workers limit. Typically you'd want -max_workers to equal maximum number of clients allowed. - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer prio-workers -Number of priority workers. If all workers from above pool are stuck, some -calls marked as high priority (notably domainDestroy) can be executed in -this pool. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-requests -Total global limit on concurrent RPC calls. - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests -Limit on concurrent requests from a single client connection. To avoid one -client monopolizing the server this should be a small fraction of the global -max_requests and max_workers parameter. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers -Same as @code{min-workers} but for the admin interface. - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers -Same as @code{max-workers} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients -Same as @code{max-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients -Same as @code{max-queued-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests -Same as @code{max-client-requests} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string log-filters -Logging filters. - -A filter allows to select a different logging level for a given category of -logs The format for a filter is one of: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., -"remote", "qemu", or "util.json" (the name in the filter can be a substring -of the full category name, in order to match multiple similar categories), -the optional "+" prefix tells libvirt to log stack trace for each message -matching name, and @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string log-outputs -Logging outputs. - -An output is one of the places to save logging information The format for an -output can be: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer audit-level -Allows usage of the auditing subsystem to be altered - -@itemize @bullet -@item -0: disable all auditing - -@item -1: enable auditing, only if enabled on host - -@item -2: enable auditing, and exit if disabled on host. - -@end itemize - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging -Send audit messages via libvirt logging infrastructure. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid -Host UUID. UUID must not have all digits be the same. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source -Source to read host UUID. - -@itemize @bullet -@item -@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid} - -@item -@code{machine-id}: fetch the UUID from @code{/etc/machine-id} - -@end itemize - -If @code{dmidecode} does not provide a valid UUID a temporary UUID will be -generated. - -Defaults to @samp{"smbios"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval -A keepalive message is sent to a client after @code{keepalive_interval} -seconds of inactivity to check if the client is still responding. If set to --1, libvirtd will never send keepalive requests; however clients can still -send them and the daemon will send responses. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count -Maximum number of keepalive messages that are allowed to be sent to the -client without getting any response before the connection is considered -broken. - -In other words, the connection is automatically closed approximately after -@code{keepalive_interval * (keepalive_count + 1)} seconds since the last -message received from the client. When @code{keepalive-count} is set to 0, -connections will be automatically closed after @code{keepalive-interval} -seconds of inactivity without sending any keepalive messages. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout -Timeout for Open vSwitch calls. - -The @code{ovs-vsctl} utility is used for the configuration and its timeout -option is set by default to 5 seconds to avoid potential infinite waits -blocking libvirt. - -Defaults to @samp{5}. - -@end deftypevr - -@c %end of autogenerated docs - -@subsubheading Virtlog daemon -The virtlogd service is a server side daemon component of libvirt that is -used to manage logs from virtual machine consoles. - -This daemon is not used directly by libvirt client applications, rather it -is called on their behalf by @code{libvirtd}. By maintaining the logs in a -standalone daemon, the main @code{libvirtd} daemon can be restarted without -risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec() -itself upon receiving @code{SIGUSR1}, to allow live upgrades without -downtime. - -@deffn {Scheme Variable} virtlog-service-type -This is the type of the virtlog daemon. Its value must be a -@code{virtlog-configuration}. - -@example -(service virtlog-service-type - (virtlog-configuration - (max-clients 1000))) -@end example -@end deffn - -@deftypevr {@code{virtlog-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} string log-filters -Logging filters. - -A filter allows to select a different logging level for a given category of -logs The format for a filter is one of: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., -"remote", "qemu", or "util.json" (the name in the filter can be a substring -of the full category name, in order to match multiple similar categories), -the optional "+" prefix tells libvirt to log stack trace for each message -matching name, and @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} string log-outputs -Logging outputs. - -An output is one of the places to save logging information The format for an -output can be: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{1024}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-size -Maximum file size before rolling over. - -Defaults to @samp{2MB} - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-backups -Maximum number of backup files to keep. - -Defaults to @samp{3} - -@end deftypevr - -@subsubheading Transparent Emulation with QEMU - -@cindex emulation -@cindex @code{binfmt_misc} -@code{qemu-binfmt-service-type} provides support for transparent emulation -of program binaries built for different architectures---e.g., it allows you -to transparently execute an ARMv7 program on an x86_64 machine. It achieves -this by combining the @uref{https://www.qemu.org, QEMU} emulator and the -@code{binfmt_misc} feature of the kernel Linux. - -@defvr {Scheme Variable} qemu-binfmt-service-type -This is the type of the QEMU/binfmt service for transparent emulation. Its -value must be a @code{qemu-binfmt-configuration} object, which specifies the -QEMU package to use as well as the architecture we want to emulated: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc")))) -@end example - -In this example, we enable transparent emulation for the ARM and aarch64 -platforms. Running @code{herd stop qemu-binfmt} turns it off, and running -@code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the -@command{herd} command,, shepherd, The GNU Shepherd Manual}). -@end defvr - -@deftp {Data Type} qemu-binfmt-configuration -This is the configuration for the @code{qemu-binfmt} service. - -@table @asis -@item @code{platforms} (default: @code{'()}) -The list of emulated QEMU platforms. Each item must be a @dfn{platform -object} as returned by @code{lookup-qemu-platforms} (see below). - -@item @code{guix-support?} (default: @code{#f}) -When it is true, QEMU and all its dependencies are added to the build -environment of @command{guix-daemon} (@pxref{Aufruf des guix-daemon, -@code{--chroot-directory} option}). This allows the @code{binfmt_misc} -handlers to be used within the build environment, which in turn means that -you can transparently build programs for another architecture. - -For example, let's suppose you're on an x86_64 machine and you have this -service: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm")) - (guix-support? #t))) -@end example - -You can run: - -@example -guix build -s armhf-linux inkscape -@end example - -@noindent -and it will build Inkscape for ARMv7 @emph{as if it were a native build}, -transparently using QEMU to emulate the ARMv7 CPU. Pretty handy if you'd -like to test a package build for an architecture you don't have access to! - -@item @code{qemu} (default: @code{qemu}) -The QEMU package to use. -@end table -@end deftp - -@deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{} -Return the list of QEMU platform objects corresponding to -@var{platforms}@dots{}. @var{platforms} must be a list of strings -corresponding to platform names, such as @code{"arm"}, @code{"sparc"}, -@code{"mips64el"}, and so on. -@end deffn - -@deffn {Scheme Procedure} qemu-platform? @var{obj} -Return true if @var{obj} is a platform object. -@end deffn - -@deffn {Scheme Procedure} qemu-platform-name @var{platform} -Return the name of @var{platform}---a string such as @code{"arm"}. -@end deffn - -@node Versionskontrolldienste -@subsection Versionskontrolldienste - -The @code{(gnu services version-control)} module provides a service to allow -remote access to local Git repositories. There are three options: the -@code{git-daemon-service}, which provides access to repositories via the -@code{git://} unsecured TCP-based protocol, extending the @code{nginx} web -server to proxy some requests to @code{git-http-backend}, or providing a web -interface with @code{cgit-service-type}. - -@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] - -Return a service that runs @command{git daemon}, a simple TCP server to -expose repositories over the Git protocol for anonymous access. - -The optional @var{config} argument should be a -@code{<git-daemon-configuration>} object, by default it allows read-only -access to exported@footnote{By creating the magic file -"git-daemon-export-ok" in the repository directory.} repositories under -@file{/srv/git}. - -@end deffn - -@deftp {Data Type} git-daemon-configuration -Data type representing the configuration for @code{git-daemon-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{export-all?} (default: @var{#f}) -Whether to allow access for all Git repositories, even if they do not have -the @file{git-daemon-export-ok} file. - -@item @code{base-path} (default: @file{/srv/git}) -Whether to remap all the path requests as relative to the given path. If -you run git daemon with @var{(base-path "/srv/git")} on example.com, then if -you later try to pull @code{git://example.com/hello.git}, git daemon will -interpret the path as @code{/srv/git/hello.git}. - -@item @code{user-path} (default: @var{#f}) -Whether to allow @code{~user} notation to be used in requests. When -specified with empty string, requests to @code{git://host/~alice/foo} is -taken as a request to access @code{foo} repository in the home directory of -user @code{alice}. If @var{(user-path "path")} is specified, the same -request is taken as a request to access @code{path/foo} repository in the -home directory of user @code{alice}. - -@item @code{listen} (default: @var{'()}) -Whether to listen on specific IP addresses or hostnames, defaults to all. - -@item @code{port} (default: @var{#f}) -Whether to listen on an alternative port, which defaults to 9418. - -@item @code{whitelist} (default: @var{'()}) -If not empty, only allow access to this list of directories. - -@item @code{extra-options} (default: @var{'()}) -Extra options will be passed to @code{git daemon}, please run @command{man -git-daemon} for more information. - -@end table -@end deftp - -The @code{git://} protocol lacks authentication. When you pull from a -repository fetched via @code{git://}, you don't know that the data you -receive was modified is really coming from the specified host, and you have -your connection is subject to eavesdropping. It's better to use an -authenticated and encrypted transport, such as @code{https}. Although Git -allows you to serve repositories using unsophisticated file-based web -servers, there is a faster protocol implemented by the -@code{git-http-backend} program. This program is the back-end of a proper -Git web service. It is designed to sit behind a FastCGI proxy. @xref{Web-Dienste}, for more on running the necessary @code{fcgiwrap} daemon. - -Guix has a separate configuration data type for serving Git repositories -over HTTP. - -@deftp {Data Type} git-http-configuration -Data type representing the configuration for @code{git-http-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{git-root} (default: @file{/srv/git}) -Directory containing the Git repositories to expose to the world. - -@item @code{export-all?} (default: @var{#f}) -Whether to expose access for all Git repositories in @var{git-root}, even if -they do not have the @file{git-daemon-export-ok} file. - -@item @code{uri-path} (default: @file{/git/}) -Path prefix for Git access. With the default @code{/git/} prefix, this will -map @code{http://@var{server}/git/@var{repo}.git} to -@code{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin with -this prefix are not passed on to this Git instance. - -@item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web-Dienste}. -@end table -@end deftp - -There is no @code{git-http-service-type}, currently; instead you can create -an @code{nginx-location-configuration} from a @code{git-http-configuration} -and then add that location to a web server. - -@deffn {Scheme Procedure} git-http-nginx-location-configuration @ - [config=(git-http-configuration)] Compute an -@code{nginx-location-configuration} that corresponds to the given Git http -configuration. An example nginx service definition to serve the default -@file{/srv/git} over HTTPS might be: - -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list - (nginx-server-configuration - (listen '("443 ssl")) - (server-name "git.my-host.org") - (ssl-certificate - "/etc/letsencrypt/live/git.my-host.org/fullchain.pem") - (ssl-certificate-key - "/etc/letsencrypt/live/git.my-host.org/privkey.pem") - (locations - (list - (git-http-nginx-location-configuration - (git-http-configuration (uri-path "/")))))))))) -@end example - -This example assumes that you are using Let's Encrypt to get your TLS -certificate. @xref{Zertifikatsdienste}. The default @code{certbot} -service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS. -You will also need to add an @code{fcgiwrap} proxy to your system services. -@xref{Web-Dienste}. -@end deffn - -@subsubheading Cgit Service - -@cindex Cgit service -@cindex Git, web interface -@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git -repositories written in C. - -The following example will configure the service with default values. By -default, Cgit can be accessed on port 80 (@code{http://localhost:80}). - -@example -(service cgit-service-type) -@end example - -The @code{file-object} type designates either a file-like object -(@pxref{G-Ausdrücke, file-like objects}) or a string. - -@c %start of fragment - -Available @code{cgit-configuration} fields are: - -@deftypevr {@code{cgit-configuration} parameter} package package -The CGIT package. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object about-filter -Specifies a command which will be invoked to format the content of about -pages (both top-level and for each repository). - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string agefile -Specifies a path, relative to each repository path, which can be used to -specify the date and time of the youngest commit in the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter -Specifies a command that will be invoked for authenticating repository -access. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set @samp{name} enables ordering by branch name. - -Defaults to @samp{"name"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string cache-root -Path used to store the cgit cache entries. - -Defaults to @samp{"/var/cache/cgit"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of repository pages accessed with a fixed SHA1. - -Defaults to @samp{-1}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of repository pages accessed without a fixed SHA1. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository summary page. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository index page. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl -Number which specifies the time-to-live, in minutes, for the result of -scanning a path for Git repositories. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository about page. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of snapshots. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-size -The maximum number of entries in the cgit cache. When set to @samp{0}, -caching is disabled. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort? -Sort items in the repo list case sensitively. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list clone-prefix -List of common prefixes which, when combined with a repository URL, -generates valid clone URLs for the repository. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list clone-url -List of @code{clone-url} templates. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter -Command which will be invoked to format commit messages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{"git log"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object css -URL which specifies the css document to include in all cgit pages. - -Defaults to @samp{"/share/cgit/cgit.css"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object email-filter -Specifies a command which will be invoked to format names and email address -of committers, authors, and taggers, as represented in various places -throughout the cgit interface. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean embedded? -Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment -suitable for embedding in other HTML pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph? -Flag which, when set to @samp{#t}, will make cgit print an ASCII-art commit -history graph to the left of the commit messages in the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides? -Flag which, when set to @samp{#t}, allows all filter settings to be -overridden in repository-specific cgitrc files. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links? -Flag which, when set to @samp{#t}, allows users to follow a file in the log -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone? -If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links? -Flag which, when set to @samp{#t}, will make cgit generate extra links -"summary", "commit", "tree" for each repo in the repository index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner? -Flag which, when set to @samp{#t}, will make cgit display the owner of each -repo in the repository index. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount? -Flag which, when set to @samp{#t}, will make cgit print the number of -modified files for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount? -Flag which, when set to @samp{#t}, will make cgit print the number of added -and removed lines for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links? -Flag which, when set to @code{1}, will make cgit use the subject of the -parent commit as link text when generating links to parent commits in commit -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving? -Flag which, when set to @samp{#t}, will make cgit use the subject of the -parent commit as link text when generating links to parent commits in commit -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers? -Flag which, when set to @samp{#t}, will make cgit generate linenumber links -for plaintext blobs printed in the tree view. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config? -Flag which, when set to @samp{#f}, will allow cgit to use Git config to set -any repo specific settings. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object favicon -URL used as link to a shortcut icon for cgit. - -Defaults to @samp{"/favicon.ico"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string footer -The content of the file specified with this option will be included verbatim -at the bottom of all pages (i.e.@: it replaces the standard "generated -by..."@: message). - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string head-include -The content of the file specified with this option will be included verbatim -in the HTML HEAD section on all pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string header -The content of the file specified with this option will be included verbatim -at the top of all pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object include -Name of a configfile to include before the rest of the current config- file -is parsed. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string index-header -The content of the file specified with this option will be included verbatim -above the repository index. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string index-info -The content of the file specified with this option will be included verbatim -below the heading on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean local-time? -Flag which, if set to @samp{#t}, makes cgit print commit and tag times in -the servers timezone. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object logo -URL which specifies the source of an image which will be used as a logo on -all cgit pages. - -Defaults to @samp{"/share/cgit/cgit.png"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter -Command which will be invoked to format the Owner column of the main page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items -Number of items to display in atom feeds view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count -Number of entries to list per page in "log" view. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-message-length -Number of commit message characters to display in "log" view. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count -Specifies the number of entries to list per page on the repository index -page. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length -Specifies the maximum number of repo description characters to display on -the repository index page. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size -Specifies the maximum size of a blob to display HTML for in KBytes. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string max-stats -Maximum statistics period. Valid values are @samp{week},@samp{month}, -@samp{quarter} and @samp{year}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype -Mimetype for the specified filename extension. - -Defaults to @samp{((gif "image/gif") (html "text/html") (jpg "image/jpeg") -(jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg -"image/svg+xml"))}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file -Specifies the file to use for automatic mimetype lookup. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string module-link -Text which will be used as the formatstring for a hyperlink when a submodule -is printed in a directory listing. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean nocache? -If set to the value @samp{#t} caching will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail? -If set to @samp{#t} showing full author email addresses will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noheader? -Flag which, when set to @samp{#t}, will make cgit omit the standard header -on all pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} project-list project-list -A list of subdirectories inside of @code{repository-directory}, relative to -it, that should loaded as Git repositories. An empty list means that all -subdirectories will be loaded. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object readme -Text which will be used as default value for @code{cgit-repo-readme}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix? -If set to @code{#t} and @code{repository-directory} is enabled, if any -repositories are found with a suffix of @code{.git}, this suffix will be -removed for the URL and name. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer renamelimit -Maximum number of files to consider when detecting renames. - -Defaults to @samp{-1}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string repository-sort -The way in which repositories in each section are sorted. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} robots-list robots -Text used as content for the @code{robots} meta-tag. - -Defaults to @samp{("noindex" "nofollow")}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-desc -Text printed below the heading on the repository index page. - -Defaults to @samp{"a fast webinterface for the git dscm"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-readme -The content of the file specified with this option will be included verbatim -below thef "about" link on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-title -Text printed as heading on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path -If set to @samp{#t} and repository-directory is enabled, -repository-directory will recurse into directories whose name starts with a -period. Otherwise, repository-directory will stay away from such -directories, considered as "hidden". Note that this does not apply to the -".git" directory in non-bare repos. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list snapshots -Text which specifies the default set of snapshot formats that cgit generates -links for. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory -Name of the directory to scan for repositories (represents -@code{scan-path}). - -Defaults to @samp{"/srv/git"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string section -The name of the current repository section - all repositories defined after -this option will inherit the current section name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string section-sort -Flag which, when set to @samp{1}, will sort the sections on the repository -listing by name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer section-from-path -A number which, if defined prior to repository-directory, specifies how many -path elements from each repo path to use as a default section name. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs? -If set to @samp{#t} shows side-by-side diffs instead of unidiffs per -default. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object source-filter -Specifies a command which will be invoked to format plaintext blobs in the -tree view. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-branches -Specifies the number of branches to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-log -Specifies the number of log entries to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-tags -Specifies the number of tags to display in the repository "summary" view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string strict-export -Filename which, if specified, needs to be present within the repository for -cgit to allow access to that repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string virtual-root -URL which, if specified, will be used as root for all cgit links. - -Defaults to @samp{"/"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories -A list of @dfn{cgit-repo} records to use with config. - -Defaults to @samp{()}. - -Available @code{repository-cgit-configuration} fields are: - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots -A mask of snapshot formats for this repo that cgit generates links for, -restricted by the global @code{snapshots} setting. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter -Override the default @code{source-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url -The relative URL used to access the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter -Override the default @code{about-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set to @samp{name} enables ordering by branch name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url -A list of URLs which can be used to clone repo. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter -Override the default @code{commit-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch -The name of the default branch for this repository. If no such branch -exists in the repository, the first branch name (when sorted) is used as -default instead. By default branch pointed to by HEAD, or "master" if there -is no suitable HEAD. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc -The value to show as repository description. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage -The value to show as repository homepage. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter -Override the default @code{email-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph? -A flag which can be used to disable the global setting -@code{enable-commit-graph?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount? -A flag which can be used to disable the global setting -@code{enable-log-filecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount? -A flag which can be used to disable the global setting -@code{enable-log-linecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links? -A flag which can be used to override the global setting -@code{enable-subject-links?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving? -A flag which can be used to override the global setting -@code{enable-html-serving?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide? -Flag which, when set to @code{#t}, hides the repository from the repository -index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore? -Flag which, when set to @samp{#t}, ignores the repository. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo -URL which specifies the source of an image which will be used as a logo on -this repo’s pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter -Override the default @code{owner-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link -Text which will be used as the formatstring for a hyperlink when a submodule -is printed in a directory listing. The arguments for the formatstring are -the path and SHA1 of the submodule commit. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path -Text which will be used as the formatstring for a hyperlink when a submodule -with the specified subdirectory path is printed in a directory listing. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats -Override the default maximum statistics period. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name -The value to show as repository name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner -A value used to identify the owner of the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path -An absolute path to the repository directory. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme -A path (relative to repo) which specifies a file to include verbatim as the -"About" page for this repo. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string section -The name of the current repository section - all repositories defined after -this option will inherit the current section name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - -However, it could be that you just want to get a @code{cgitrc} up and -running. In that case, you can pass an @code{opaque-cgit-configuration} as -a record to @code{cgit-service-type}. As its name indicates, an opaque -configuration does not have easy reflective capabilities. - -Available @code{opaque-cgit-configuration} fields are: - -@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit -The cgit package. -@end deftypevr - -@deftypevr {@code{opaque-cgit-configuration} parameter} string string -The contents of the @code{cgitrc}, as a string. -@end deftypevr - -For example, if your @code{cgitrc} is just the empty string, you could -instantiate a cgit service like this: - -@example -(service cgit-service-type - (opaque-cgit-configuration - (cgitrc ""))) -@end example - -@subsubheading Gitolite-Dienst - -@cindex Gitolite-Dienst -@cindex Git, hosting -@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git -repositories on a central server. - -Gitolite can handle multiple repositories and users, and supports flexible -configuration of the permissions for the users on the repositories. - -The following example will configure Gitolite using the default @code{git} -user, and the provided SSH public key. - -@example -(service gitolite-service-type - (gitolite-configuration - (admin-pubkey (plain-file - "yourname.pub" - "ssh-rsa AAAA... guix@@example.com")))) -@end example - -Gitolite is configured through a special admin repository which you can -clone, for example, if you setup Gitolite on @code{example.com}, you would -run the following command to clone the admin repository. - -@example -git clone git@@example.com:gitolite-admin -@end example - -When the Gitolite service is activated, the provided @code{admin-pubkey} -will be inserted in to the @file{keydir} directory in the gitolite-admin -repository. If this results in a change in the repository, it will be -committed using the message ``gitolite setup by GNU Guix''. - -@deftp {Datentyp} gitolite-configuration -Repräsentiert die Konfiguration vom @code{gitolite-service-type}. - -@table @asis -@item @code{package} (Vorgabe: @var{gitolite}) -Welches Gitolite-Paket benutzt werden soll. - -@item @code{user} (Vorgabe: @var{git}) -User to use for Gitolite. This will be user that you use when accessing -Gitolite over SSH. - -@item @code{group} (Vorgabe: @var{git}) -Group to use for Gitolite. - -@item @code{home-directory} (Vorgabe: @var{"/var/lib/gitolite"}) -Directory in which to store the Gitolite configuration and repositories. - -@item @code{rc-file} (Vorgabe: @var{(gitolite-rc-file)}) -A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}), -representing the configuration for Gitolite. - -@item @code{admin-pubkey} (Vorgabe: @var{#f}) -A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}) used to -setup Gitolite. This will be inserted in to the @file{keydir} directory -within the gitolite-admin repository. - -To specify the SSH key as a string, use the @code{plain-file} function. - -@example -(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") -@end example - -@end table -@end deftp - -@deftp {Datentyp} gitolite-rc-file -Repräsentiert die Gitolie-RC-Datei. - -@table @asis -@item @code{umask} (Vorgabe: @code{#o0077}) -This controls the permissions Gitolite sets on the repositories and their -contents. - -A value like @code{#o0027} will give read access to the group used by -Gitolite (by default: @code{git}). This is necessary when using Gitolite -with software like cgit or gitweb. - -@item @code{git-config-keys} (Vorgabe: @code{""}) -Gitolite allows you to set git config values using the "config" -keyword. This setting allows control over the config keys to accept. - -@item @code{roles} (Vorgabe: @code{'(("READERS" . 1) ("WRITERS" . ))}) -Set the role names allowed to be used by users running the perms command. - -@item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")}) -This setting controls the commands and features to enable within Gitolite. - -@end table -@end deftp - - -@node Spieldienste -@subsection Spieldienste - -@subsubheading The Battle for Wesnoth Service -@cindex wesnothd -@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based -tactical strategy game, with several single player campaigns, and -multiplayer games (both networked and local). - -@defvar {Scheme Variable} wesnothd-service-type -Service type for the wesnothd service. Its value must be a -@code{wesnothd-configuration} object. To run wesnothd in the default -configuration, instantiate it as: - -@example -(service wesnothd-service-type) -@end example -@end defvar - -@deftp {Data Type} wesnothd-configuration -Data type representing the configuration of @command{wesnothd}. - -@table @asis -@item @code{package} (default: @code{wesnoth-server}) -The wesnoth server package to use. - -@item @code{port} (default: @code{15000}) -The port to bind the server to. -@end table -@end deftp - -@node Verschiedene Dienste -@subsection Verschiedene Dienste - -@cindex fingerprint -@subsubheading Fingerabdrucklese-Dienst - -The @code{(gnu services fingerprint)} module provides a DBus service to read -and identify fingerprints via a fingerprint sensor. - -@defvr {Scheme Variable} fprintd-service-type -The service type for @command{fprintd}, which provides the fingerprint -reading capability. - -@example -(service fprintd-service-type) -@end example -@end defvr - -@cindex sysctl -@subsubheading System Control Service - -The @code{(gnu services sysctl)} provides a service to configure kernel -parameters at boot. - -@defvr {Scheme Variable} sysctl-service-type -The service type for @command{sysctl}, which modifies kernel parameters -under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated -as: - -@example -(service sysctl-service-type - (sysctl-configuration - (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example -@end defvr - -@deftp {Data Type} sysctl-configuration -The data type representing the configuration of @command{sysctl}. - -@table @asis -@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"}) -The @command{sysctl} executable to use. - -@item @code{settings} (default: @code{'()}) -An association list specifies kernel parameters and their values. -@end table -@end deftp - -@cindex pcscd -@subsubheading PC/SC Smart Card Daemon Service - -The @code{(gnu services security-token)} module provides the following -service to run @command{pcscd}, the PC/SC Smart Card Daemon. -@command{pcscd} is the daemon program for pcsc-lite and the MuscleCard -framework. It is a resource manager that coordinates communications with -smart card readers, smart cards and cryptographic tokens that are connected -to the system. - -@defvr {Scheme Variable} pcscd-service-type -Service type for the @command{pcscd} service. Its value must be a -@code{pcscd-configuration} object. To run pcscd in the default -configuration, instantiate it as: - -@example -(service pcscd-service-type) -@end example -@end defvr - -@deftp {Datentyp} pcscd-configuration -Repräsentiert die Konfiguration von @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (Vorgabe: @code{pcsc-lite}) -The pcsc-lite package that provides pcscd. -@item @code{usb-drivers} (Vorgabe: @code{(list ccid)}) -List of packages that provide USB drivers to pcscd. Drivers are expected to -be under @file{pcsc/drivers} in the store directory of the package. -@end table -@end deftp - -@cindex lirc -@subsubheading Lirc Service - -The @code{(gnu services lirc)} module provides the following service. - -@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()] -Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that -decodes infrared signals from remote controls. - -Optionally, @var{device}, @var{driver} and @var{config-file} (configuration -file name) may be specified. See @command{lircd} manual for details. - -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn - -@cindex spice -@subsubheading Spice Service - -The @code{(gnu services spice)} module provides the following service. - -@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a -daemon that enables sharing the clipboard with a vm and setting the guest -display resolution when the graphical console window resizes. -@end deffn - -@subsection Dictionary Services -@cindex dictionary -The @code{(gnu services dict)} module provides the following service: - -@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] -Return a service that runs the @command{dicod} daemon, an implementation of -DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). - -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{<dicod-configuration>} object, by -default it serves the GNU Collaborative International Dictonary of English. - -You can add @command{open localhost} to your @file{~/.dico} file to make -@code{localhost} the default server for @command{dico} client -(@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn - -@deftp {Data Type} dicod-configuration -Data type representing the configuration of dicod. - -@table @asis -@item @code{dico} (default: @var{dico}) -Package object of the GNU Dico dictionary server. - -@item @code{interfaces} (default: @var{'("localhost")}) -This is the list of IP addresses and ports and possibly socket file names to -listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico -Manual}). - -@item @code{handlers} (default: @var{'()}) -List of @code{<dicod-handler>} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{<dicod-database>} objects denoting dictionaries to be served. -@end table -@end deftp - -@deftp {Data Type} dicod-handler -Data type representing a dictionary handler (module instance). - -@table @asis -@item @code{name} -Name of the handler (module instance). - -@item @code{module} (default: @var{#f}) -Name of the dicod module of the handler (instance). If it is @code{#f}, the -module has the same name as the handler. (@pxref{Module,,, dico, GNU Dico -Manual}). - -@item @code{options} -List of strings or gexps representing the arguments for the module handler -@end table -@end deftp - -@deftp {Data Type} dicod-database -Data type representing a dictionary database. - -@table @asis -@item @code{name} -Name of the database, will be used in DICT commands. - -@item @code{handler} -Name of the dicod handler (module instance) used by this database -(@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (default: @var{#f}) -Whether the database configuration complex. The complex configuration will -need a corresponding @code{<dicod-handler>} object, otherwise not. - -@item @code{options} -List of strings or gexps representing the arguments for the database -(@pxref{Databases,,, dico, GNU Dico Manual}). -@end table -@end deftp - -@defvr {Scheme Variable} %dicod-database:gcide -A @code{<dicod-database>} object serving the GNU Collaborative International -Dictionary of English using the @code{gcide} package. -@end defvr - -The following is an example @code{dicod-service} configuration. - -@example -(dicod-service #:config - (dicod-configuration - (handlers (list (dicod-handler - (name "wordnet") - (module "dictorg") - (options - (list #~(string-append "dbdir=" #$wordnet)))))) - (databases (list (dicod-database - (name "wordnet") - (complex? #t) - (handler "wordnet") - (options '("database=wn"))) - %dicod-database:gcide)))) -@end example - -@cindex Docker -@subsubheading Docker Service - -The @code{(gnu services docker)} module provides the following service. - -@defvr {Scheme Variable} docker-service-type - -This is the type of the service that runs -@url{http://www.docker.com,Docker}, a daemon that can execute application -bundles (sometimes referred to as ``containers'') in isolated environments. - -@end defvr - -@deftp {Data Type} docker-configuration -This is the data type representing the configuration of Docker and -Containerd. - -@table @asis - -@item @code{package} (default: @code{docker}) -The Docker package to use. - -@item @code{containerd} (default: @var{containerd}) -The Containerd package to use. - -@end table -@end deftp - -@node Setuid-Programme -@section Setuid-Programme - -@cindex setuid programs -Some programs need to run with ``root'' privileges, even when they are -launched by unprivileged users. A notorious example is the @command{passwd} -program, which users can run to change their password, and which needs to -access the @file{/etc/passwd} and @file{/etc/shadow} files---something -normally restricted to root, for obvious security reasons. To address that, -these executables are @dfn{setuid-root}, meaning that they always run with -root privileges (@pxref{How Change Persona,,, libc, The GNU C Library -Reference Manual}, for more info about the setuid mechanism.) - -The store itself @emph{cannot} contain setuid programs: that would be a -security issue since any user on the system can write derivations that -populate the store (@pxref{Der Store}). Thus, a different mechanism is -used: instead of changing the setuid bit directly on files that are in the -store, we let the system administrator @emph{declare} which programs should -be setuid root. - -The @code{setuid-programs} field of an @code{operating-system} declaration -contains a list of G-expressions denoting the names of programs to be -setuid-root (@pxref{Das Konfigurationssystem nutzen}). For instance, the -@command{passwd} program, which is part of the Shadow package, can be -designated by this G-expression (@pxref{G-Ausdrücke}): - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -A default set of setuid programs is defined by the @code{%setuid-programs} -variable of the @code{(gnu system)} module. - -@defvr {Scheme Variable} %setuid-programs -A list of G-expressions denoting common programs that are setuid-root. - -The list includes commands such as @command{passwd}, @command{ping}, -@command{su}, and @command{sudo}. -@end defvr - -Under the hood, the actual setuid programs are created in the -@file{/run/setuid-programs} directory at system activation time. The files -in this directory refer to the ``real'' binaries, which are in the store. - -@node X.509-Zertifikate -@section X.509-Zertifikate - -@cindex HTTPS, Zertifikate -@cindex X.509-Zertifikate -@cindex TLS -Über HTTPS verfügbare Webserver (also HTTP mit gesicherter Transportschicht, -englisch »Transport-Layer Security«, kurz TLS) senden Client-Programmen ein -@dfn{X.509-Zertifikat}, mit dem der Client den Server dann -@emph{authentifizieren} kann. Dazu verifiziert der Client, dass das -Zertifikat des Servers von einer sogenannten Zertifizierungsstelle signiert -wurde (englisch @dfn{Certificate Authority}, kurz CA). Damit er aber die -Signatur der Zertifizierungsstelle verifizieren kann, muss jeder Client das -Zertifikat der Zertifizierungsstelle besitzen. - -Web-Browser wie GNU@tie{}IceCat liefern ihre eigenen CA-Zertifikate mit, -damit sie von Haus aus Zertifikate verifizieren können. - -Den meisten anderen Programmen, die HTTPS sprechen können — @command{wget}, -@command{git}, @command{w3m} etc. — muss allerdings erst mitgeteilt werden, -wo die CA-Zertifikate installiert sind. - -@cindex @code{nss-certs} -In Guix, this is done by adding a package that provides certificates to the -@code{packages} field of the @code{operating-system} declaration -(@pxref{»operating-system«-Referenz}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -Beachten Sie, dass es @emph{nicht} zu den @var{%base-packages} gehört, Sie -es also ausdrücklich hinzufügen müssen. Das Verzeichnis -@file{/etc/ssl/certs}, wo die meisten Anwendungen und Bibliotheken ihren -Voreinstellungen entsprechend nach Zertifikaten suchen, verweist auf die -global installierten Zertifikate. - -Unprivilegierte Benutzer, wie die, die Guix auf einer Fremddistribution -benutzen, können sich auch lokal ihre eigenen Pakete mit Zertifikaten in ihr -Profil installieren. Eine Reihe von Umgebungsvariablen muss dazu definiert -werden, damit Anwendungen und Bibliotheken wissen, wo diese Zertifikate zu -finden sind. Und zwar folgt die OpenSSL-Bibliothek den Umgebungsvariablen -@code{SSL_CERT_DIR} und @code{SSL_CERT_FILE}, manche Anwendungen benutzen -stattdessen aber ihre eigenen Umgebungsvariablen. Das Versionskontrollsystem -Git liest den Ort zum Beispiel aus der Umgebungsvariablen -@code{GIT_SSL_CAINFO} aus. Sie würden typischerweise also so etwas -ausführen: - -@example -$ guix package -i nss-certs -$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" -$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -$ export GIT_SSL_CAINFO="$SSL_CERT_FILE" -@end example - -Ein weiteres Beispiel ist R, was voraussetzt, dass die Umgebungsvariable -@code{CURL_CA_BUNDLE} auf ein Zertifikatsbündel verweist, weshalb Sie etwas -wie hier ausführen müssten: - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -Für andere Anwendungen möchten Sie die Namen der benötigten -Umgebungsvariablen vielleicht in deren Dokumentation nachschlagen. - - -@node Name Service Switch -@section Name Service Switch - -@cindex Name Service Switch -@cindex NSS -The @code{(gnu system nss)} module provides bindings to the configuration -file of the libc @dfn{name service switch} or @dfn{NSS} (@pxref{NSS -Configuration File,,, libc, The GNU C Library Reference Manual}). In a -nutshell, the NSS is a mechanism that allows libc to be extended with new -``name'' lookup methods for system databases, which includes host names, -service names, user accounts, and more (@pxref{Name Service Switch, System -Databases and Name Service Switch,, libc, The GNU C Library Reference -Manual}). - -The NSS configuration specifies, for each system database, which lookup -method is to be used, and how the various methods are chained together---for -instance, under which circumstances NSS should try the next method in the -list. The NSS configuration is given in the @code{name-service-switch} -field of @code{operating-system} declarations (@pxref{»operating-system«-Referenz, @code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, host name lookup -As an example, the declaration below configures the NSS to use the -@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns} -back-end}, which supports host name lookups over multicast DNS (mDNS) for -host names ending in @code{.local}: - -@example -(name-service-switch - (hosts (list %files ;first, check /etc/hosts - - ;; If the above did not succeed, try - ;; with 'mdns_minimal'. - (name-service - (name "mdns_minimal") - - ;; 'mdns_minimal' is authoritative for - ;; '.local'. When it returns "not found", - ;; no need to try the next methods. - (reaction (lookup-specification - (not-found => return)))) - - ;; Then fall back to DNS. - (name-service - (name "dns")) - - ;; Finally, try with the "full" 'mdns'. - (name-service - (name "mdns"))))) -@end example - -Do not worry: the @code{%mdns-host-lookup-nss} variable (see below) -contains this configuration, so you will not have to type it if all you want -is to have @code{.local} host lookup working. - -Note that, in this case, in addition to setting the -@code{name-service-switch} of the @code{operating-system} declaration, you -also need to use @code{avahi-service-type} (@pxref{Netzwerkdienste, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Desktop-Dienste}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@pxref{Basisdienste, @code{nscd-service}}). - -For convenience, the following variables provide typical NSS configurations. - -@defvr {Scheme Variable} %default-nss -This is the default name service switch configuration, a -@code{name-service-switch} object. -@end defvr - -@defvr {Scheme Variable} %mdns-host-lookup-nss -This is the name service switch configuration with support for host name -lookup over multicast DNS (mDNS) for host names ending in @code{.local}. -@end defvr - -The reference for name service switch configuration is given below. It is a -direct mapping of the configuration file format of the C library , so please -refer to the C library manual for more information (@pxref{NSS Configuration -File,,, libc, The GNU C Library Reference Manual}). Compared to the -configuration file format of libc NSS, it has the advantage not only of -adding this warm parenthetic feel that we like, but also static checks: you -will know about syntax errors and typos as soon as you run @command{guix -system}. - -@deftp {Data Type} name-service-switch - -This is the data type representation the configuration of libc's name -service switch (NSS). Each field below represents one of the supported -system databases. - -@table @code -@item aliases -@itemx ethers -@itemx group -@itemx gshadow -@itemx hosts -@itemx initgroups -@itemx netgroup -@itemx networks -@itemx password -@itemx public-key -@itemx rpc -@itemx services -@itemx shadow -The system databases handled by the NSS. Each of these fields must be a -list of @code{<name-service>} objects (see below). -@end table -@end deftp - -@deftp {Data Type} name-service - -This is the data type representing an actual name service and the associated -lookup action. - -@table @code -@item name -A string denoting the name service (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). - -Note that name services listed here must be visible to nscd. This is -achieved by passing the @code{#:name-services} argument to -@code{nscd-service} the list of packages providing the needed name services -(@pxref{Basisdienste, @code{nscd-service}}). - -@item reaction -An action specified using the @code{lookup-specification} macro -(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library -Reference Manual}). For example: - -@example -(lookup-specification (unavailable => continue) - (success => return)) -@end example -@end table -@end deftp - -@node Initiale RAM-Disk -@section Initiale RAM-Disk - -@cindex initrd -@cindex initiale RAM-Disk -For bootstrapping purposes, the Linux-Libre kernel is passed an @dfn{initial -RAM disk}, or @dfn{initrd}. An initrd contains a temporary root file system -as well as an initialization script. The latter is responsible for mounting -the real root file system, and for loading any kernel modules that may be -needed to achieve that. - -The @code{initrd-modules} field of an @code{operating-system} declaration -allows you to specify Linux-libre kernel modules that must be available in -the initrd. In particular, this is where you would list modules needed to -actually drive the hard disk where your root partition is---although the -default value of @code{initrd-modules} should cover most use cases. For -example, assuming you need the @code{megaraid_sas} module in addition to the -default modules to be able to access your root file system, you would write: - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Scheme Variable} %base-initrd-modules -This is the list of kernel modules included in the initrd by default. -@end defvr - -Furthermore, if you need lower-level customization, the @code{initrd} field -of an @code{operating-system} declaration allows you to specify which initrd -you would like to use. The @code{(gnu system linux-initrd)} module provides -three ways to build an initrd: the high-level @code{base-initrd} procedure -and the low-level @code{raw-initrd} and @code{expression->initrd} -procedures. - -The @code{base-initrd} procedure is intended to cover most common uses. For -example, if you want to add a bunch of kernel modules to be loaded at boot -time, you can define the @code{initrd} field of the operating system -declaration like this: - -@example -(initrd (lambda (file-systems . rest) - ;; Create a standard initrd but set up networking - ;; with the parameters QEMU expects by default. - (apply base-initrd file-systems - #:qemu-networking? #t - rest))) -@end example - -The @code{base-initrd} procedure also handles common use cases that involves -using the system as a QEMU guest, or as a ``live'' system with volatile root -file system. - -The @code{base-initrd} procedure is built from @code{raw-initrd} procedure. -Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level, -such as trying to guess which kernel modules and packages should be included -to the initrd. An example use of @code{raw-initrd} is when a user has a -custom Linux kernel configuration and default kernel modules included by -@code{base-initrd} are not available. - -The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd} -honors several options passed on the Linux kernel command line (that is, -arguments passed @i{via} the @code{linux} command of GRUB, or the -@code{-append} option of QEMU), notably: - -@table @code -@item --load=@var{boot} -Tell the initial RAM disk to load @var{boot}, a file containing a Scheme -program, once it has mounted the root file system. - -Guix uses this option to yield control to a boot program that runs the -service activation programs and then spawns the GNU@tie{}Shepherd, the -initialization system. - -@item --root=@var{root} -Mount @var{root} as the root file system. @var{root} can be a device name -like @code{/dev/sda1}, a file system label, or a file system UUID. - -@item --system=@var{System} -Have @file{/run/booted-system} and @file{/run/current-system} point to -@var{system}. - -@item modprobe.blacklist=@var{modules}@dots{} -@cindex module, black-listing -@cindex black list, of kernel modules -Instruct the initial RAM disk as well as the @command{modprobe} command -(from the kmod package) to refuse to load @var{modules}. @var{modules} must -be a comma-separated list of module names---e.g., @code{usbkbd,9pnet}. - -@item --repl -Start a read-eval-print loop (REPL) from the initial RAM disk before it -tries to load kernel modules and to mount the root file system. Our -marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will love -it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual}, -for more information on Guile's REPL. - -@end table - -Now that you know all the features that initial RAM disks produced by -@code{base-initrd} and @code{raw-initrd} provide, here is how to use it and -customize it further. - -@cindex initrd -@cindex initiale RAM-Disk -@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:helper-packages '()] -[#:qemu-networking? #f] [#:volatile-root? #f] Return a derivation that -builds a raw initrd. @var{file-systems} is a list of file systems to be -mounted by the initrd, possibly in addition to the root file system -specified on the kernel command line via @code{--root}. @var{linux-modules} -is a list of kernel modules to be loaded at boot time. @var{mapped-devices} -is a list of device mappings to realize before @var{file-systems} are -mounted (@pxref{Zugeordnete Geräte}). @var{helper-packages} is a list of -packages to be copied in the initrd. It may include @code{e2fsck/static} or -other packages needed by the initrd to check the root file system. - -When @var{qemu-networking?} is true, set up networking with the standard -QEMU parameters. When @var{virtio?} is true, load additional modules so -that the initrd can be used as a QEMU guest with para-virtualized I/O -drivers. - -When @var{volatile-root?} is true, the root file system is writable but any -changes to it are lost. -@end deffn - -@deffn {Scheme Procedure} base-initrd @var{file-systems} @ - [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@ -[#:linux-modules '()] Return as a file-like object a generic initrd, with -kernel modules taken from @var{linux}. @var{file-systems} is a list of -file-systems to be mounted by the initrd, possibly in addition to the root -file system specified on the kernel command line via @code{--root}. -@var{mapped-devices} is a list of device mappings to realize before -@var{file-systems} are mounted. - -@var{qemu-networking?} and @var{volatile-root?} behaves as in -@code{raw-initrd}. - -The initrd is automatically populated with all the kernel modules necessary -for @var{file-systems} and for the given options. Additional kernel modules -can be listed in @var{linux-modules}. They will be added to the initrd, and -loaded at boot time in the order in which they appear. -@end deffn - -Needless to say, the initrds we produce and use embed a statically-linked -Guile, and the initialization program is a Guile program. That gives a lot -of flexibility. The @code{expression->initrd} procedure builds such an -initrd, given the program to run in that initrd. - -@deffn {Scheme Procedure} expression->initrd @var{exp} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a -file-like object a Linux initrd (a gzipped cpio archive) containing -@var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All -the derivations referenced by @var{exp} are automatically copied to the -initrd. -@end deffn - -@node Bootloader-Konfiguration -@section Bootloader-Konfiguration - -@cindex bootloader -@cindex boot loader - -The operating system supports multiple bootloaders. The bootloader is -configured using @code{bootloader-configuration} declaration. All the -fields of this structure are bootloader agnostic except for one field, -@code{bootloader} that indicates the bootloader to be configured and -installed. - -Some of the bootloaders do not honor every field of -@code{bootloader-configuration}. For instance, the extlinux bootloader does -not support themes and thus ignores the @code{theme} field. - -@deftp {Data Type} bootloader-configuration -The type of a bootloader configuration declaration. - -@table @asis - -@item @code{bootloader} -@cindex EFI, bootloader -@cindex UEFI, bootloader -@cindex BIOS, bootloader -The bootloader to use, as a @code{bootloader} object. For now -@code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should -use if the installation image contains a @file{/sys/firmware/efi} directory -when you boot it on your system. - -@vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. - -@cindex ARM, bootloaders -@cindex AArch64, bootloaders -Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. In particular, @code{(gnu bootloader u-boot)} contains definitions -of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. - -@item @code{target} -This is a string denoting the target onto which to install the bootloader. - -The interpretation depends on the bootloader in question. For -@code{grub-bootloader}, for example, it should be a device name understood -by the bootloader @command{installer} command, such as @code{/dev/sda} or -@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For -@code{grub-efi-bootloader}, it should be the mount point of the EFI file -system, usually @file{/boot/efi}. - -@item @code{menu-entries} (default: @code{()}) -A possibly empty list of @code{menu-entry} objects (see below), denoting -entries to appear in the bootloader menu, in addition to the current system -entry and the entry pointing to previous system generations. - -@item @code{default-entry} (default: @code{0}) -The index of the default boot menu entry. Index 0 is for the entry of the -current system. - -@item @code{timeout} (default: @code{5}) -The number of seconds to wait for keyboard input before booting. Set to 0 -to boot immediately, and to -1 to wait indefinitely. - -@item @code{theme} (default: @var{#f}) -The bootloader theme object describing the theme to use. If no theme is -provided, some bootloaders might use a default theme, that's true for GRUB. - -@item @code{terminal-outputs} (default: @code{'gfxterm}) -The output terminals used for the bootloader boot menu, as a list of -symbols. GRUB accepts the values: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, -@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB -variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, -grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (default: @code{'()}) -The input terminals used for the bootloader boot menu, as a list of -symbols. For GRUB, the default is the native platform terminal as -determined at run-time. GRUB accepts the values: @code{console}, -@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and -@code{usb_keyboard}. This field corresponds to the GRUB variable -@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB -manual}). - -@item @code{serial-unit} (default: @code{#f}) -The serial unit used by the bootloader, as an integer from 0 to 3. For -GRUB, it is chosen at run-time; currently GRUB chooses 0, which corresponds -to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}). - -@item @code{serial-speed} (default: @code{#f}) -The speed of the serial interface, as an integer. For GRUB, the default -value is chosen at run-time; currently GRUB chooses 9600@tie{}bps -(@pxref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex dual boot -@cindex boot menu -Should you want to list additional boot menu entries @i{via} the -@code{menu-entries} field above, you will need to create them with the -@code{menu-entry} form. For example, imagine you want to be able to boot -another distro (hard to imagine!), you can define a menu entry along these -lines: - -@example -(menu-entry - (label "The Other Distro") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Details below. - -@deftp {Data Type} menu-entry -The type of an entry in the bootloader menu. - -@table @asis - -@item @code{label} -The label to show in the menu---e.g., @code{"GNU"}. - -@item @code{linux} -The Linux kernel image to boot, for example: - -@example -(file-append linux-libre "/bzImage") -@end example - -For GRUB, it is also possible to specify a device explicitly in the file -path using GRUB's device naming convention (@pxref{Naming convention,,, -grub, GNU GRUB manual}), for example: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -If the device is specified explicitly as above, then the @code{device} field -is ignored entirely. - -@item @code{linux-arguments} (default: @code{()}) -The list of extra Linux kernel command-line arguments---e.g., -@code{("console=ttyS0")}. - -@item @code{initrd} -A G-Expression or string denoting the file name of the initial RAM disk to -use (@pxref{G-Ausdrücke}). -@item @code{device} (default: @code{#f}) -The device where the kernel and initrd are to be found---i.e., for GRUB, -@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}). - -This may be a file system label (a string), a file system UUID (a -bytevector, @pxref{Dateisysteme}), or @code{#f}, in which case the -bootloader will search the device containing the file specified by the -@code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It must -@emph{not} be an OS device name such as @file{/dev/sda1}. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -Fow now only GRUB has theme support. GRUB themes are created using the -@code{grub-theme} form, which is not documented yet. - -@defvr {Scheme Variable} %default-theme -This is the default GRUB theme used by the operating system if no -@code{theme} field is specified in @code{bootloader-configuration} record. - -It comes with a fancy background image displaying the GNU and Guix logos. -@end defvr - - -@node Aufruf von guix system -@section @code{guix system} aufrufen - -Sobald Sie eine Betriebssystemdeklaration geschrieben haben, wie wir sie in -den vorangehenden Abschnitten gesehen haben, kann diese @dfn{instanziiert} -werden, indem Sie den Befehl @command{guix system} -aufrufen. Zusammengefasst: - -@example -guix system @var{Optionen}@dots{} @var{Aktion} @var{Datei} -@end example - -@var{Datei} muss der Name einer Datei sein, in der eine -Betriebssystemdeklaration als @code{operating-system}-Objekt -steht. @var{Aktion} gibt an, wie das Betriebssystem instanziiert -wird. Derzeit werden folgende Werte dafür unterstützt: - -@table @code -@item search -Verfügbare Diensttypendefinitionen anzeigen, die zum angegebenen regulären -Ausdruck passen, sortiert nach Relevanz: - -@example -$ guix system search console font -name: console-fonts -location: gnu/services/base.scm:729:2 -extends: shepherd-root -description: Install the given fonts on the specified ttys (fonts are -+ per virtual console on GNU/Linux). The value of this service is a list -+ of tty/font pairs like: -+ -+ '(("tty1" . "LatGrkCyr-8x16")) -relevance: 20 - -name: mingetty -location: gnu/services/base.scm:1048:2 -extends: shepherd-root -description: Provide console login using the `mingetty' program. -relevance: 2 - -name: login -location: gnu/services/base.scm:775:2 -extends: pam -description: Provide a console log-in service as specified by its -+ configuration value, a `login-configuration' object. -relevance: 2 - -@dots{} -@end example - -Wie auch bei @command{guix package --search} wird das Ergebnis im -@code{recutils}-Format geliefert, so dass es leicht ist, die Ausgabe zu -filtern (@pxref{Top, GNU recutils databases,, recutils, GNU recutils -manual}). - -@item reconfigure -Build the operating system described in @var{file}, activate it, and switch -to it@footnote{This action (and the related actions @code{switch-generation} -and @code{roll-back}) are usable only on systems already running Guix -System.}. - -This effects all the configuration specified in @var{file}: user accounts, -system services, global package list, setuid programs, etc. The command -starts system services specified in @var{file} that are not currently -running; if a service is currently running this command will arrange for it -to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or -@code{herd restart X}). - -Dieser Befehl erzeugt eine neue Generation, deren Nummer (wie @command{guix -system list-generations} sie anzeigt) um eins größer als die der aktuellen -Generation ist. Wenn die so nummerierte Generation bereits existiert, wird -sie überschrieben. Dieses Verhalten entspricht dem von @command{guix -package} (@pxref{Aufruf von guix package}). - -Des Weiteren wird für den Bootloader ein Menüeintrag für die neue -Betriebssystemkonfiguration hinzugefügt, außer die Befehlszeilenoption -@option{--no-bootloader} wurde übergeben. Bei GRUB werden Einträge für -ältere Konfigurationen in ein Untermenü verschoben, so dass Sie auch eine -ältere Systemgeneration beim Booten noch hochfahren können, falls es -notwendig wird. - -@quotation Anmerkung -@c The paragraph below refers to the problem discussed at -@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. -Es ist sehr zu empfehlen, @command{guix pull} einmal auszuführen, bevor Sie -@command{guix system reconfigure} zum ersten Mal aufrufen (@pxref{Aufruf von guix pull}). Wenn Sie das nicht tun, könnten Sie nach dem Abschluss von -@command{reconfigure} eine ältere Version von Guix vorfinden, als Sie vorher -hatten. -@end quotation - -@item switch-generation -@cindex Generationen -Zu einer bestehenden Systemgeneration wechseln. Diese Aktion wechselt das -Systemprofil atomar auf die angegebene Systemgeneration. Hiermit werden auch -die bestehenden Menüeinträge des Bootloaders umgeordnet. Der Menüeintrag für -die angegebene Systemgeneration wird voreingestellt und die Einträge der -anderen Generationen werden in ein Untermenü verschoben, sofern der -verwendete Bootloader dies unterstützt. Das nächste Mal, wenn das System -gestartet wird, wird die hier angegebene Systemgeneration hochgefahren. - -Der Bootloader selbst wird durch diesen Befehl @emph{nicht} neu -installiert. Es wird also lediglich der bereits installierte Bootloader mit -einer neuen Konfigurationsdatei benutzt werden. - -Die Zielgeneration kann ausdrücklich über ihre Generationsnummer angegeben -werden. Zum Beispiel würde folgender Aufruf einen Wechsel zur -Systemgeneration 7 bewirken: - -@example -guix system switch-generation 7 -@end example - -Die Zielgeneration kann auch relativ zur aktuellen Generation angegeben -werden, in der Form @code{+N} oder @code{-N}, wobei @code{+3} zum Beispiel -»3 Generationen weiter als die aktuelle Generation« bedeuten würde und -@code{-1} »1 Generation vor der aktuellen Generation« hieße. Wenn Sie einen -negativen Wert wie @code{-1} angeben, müssen Sie @code{--} der -Befehlszeilenoption voranstellen, damit die negative Zahl nicht selbst als -Befehlszeilenoption aufgefasst wird. Zum Beispiel: - -@example -guix system switch-generation -- -1 -@end example - -Zur Zeit bewirkt ein Aufruf dieser Aktion @emph{nur} einen Wechsel des -Systemprofils auf eine bereits existierende Generation und ein Umordnen der -Bootloader-Menüeinträge. Um die Ziel-Systemgeneration aber tatsächlich zu -benutzen, müssen Sie Ihr System neu hochfahren, nachdem Sie diese Aktion -ausgeführt haben. In einer zukünftigen Version von Guix wird diese Aktion -einmal dieselben Dinge tun, wie @command{reconfigure}, also etwa Dienste -aktivieren und deaktivieren. - -Diese Aktion schlägt fehl, wenn die angegebene Generation nicht existiert. - -@item roll-back -@cindex rücksetzen -Zur vorhergehenden Systemgeneration wechseln. Wenn das System das nächste -Mal hochgefahren wird, wird es die vorhergehende Systemgeneration -benutzen. Dies ist die Umkehrung von @command{reconfigure} und tut genau -dasselbe, wie @command{switch-generation} mit dem Argument @code{-1} -aufzurufen. - -Wie auch bei @command{switch-generation} müssen Sie derzeit, nachdem Sie -diese Aktion aufgerufen haben, Ihr System neu starten, um die vorhergehende -Systemgeneration auch tatsächlich zu benutzen. - -@item delete-generations -@cindex deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Aufruf von guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Aufruf von guix package, @code{--delete-generations}}). With no -arguments, all system generations but the current one are deleted: - -@example -guix system delete-generations -@end example - -You can also select the generations you want to delete. The example below -deletes all the system generations that are more than two month old: - -@example -guix system delete-generations 2m -@end example - -Running this command automatically reinstalls the bootloader with an updated -list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no -longer lists the generations that have been deleted. - -@item build -Die Ableitung des Betriebssystems erstellen, einschließlich aller -Konfigurationsdateien und Programme, die zum Booten und Starten benötigt -werden. Diese Aktion installiert jedoch nichts davon. - -@item init -Populate the given directory with all the files necessary to run the -operating system specified in @var{file}. This is useful for first-time -installations of Guix System. For instance: - -@example -guix system init my-os-config.scm /mnt -@end example - -Hiermit werden alle Store-Objekte nach @file{/mnt} kopiert, die von der in -@file{my-os-config.scm} angegebenen Konfiguration vorausgesetzt werden. Dazu -gehören Konfigurationsdateien, Pakete und so weiter. Auch andere essenzielle -Dateien, die auf dem System vorhanden sein müssen, damit es richtig -funktioniert, werden erzeugt — z.B. die Verzeichnisse @file{/etc}, -@file{/var} und @file{/run} und die Datei @file{/bin/sh}. - -Dieser Befehl installiert auch den Bootloader auf dem in @file{my-os-config} -angegebenen Ziel, außer die Befehlszeilenoption @option{--no-bootloader} -wurde übergeben. - -@item vm -@cindex virtuelle Maschine -@cindex VM -@anchor{guix system vm} -Build a virtual machine that contains the operating system declared in -@var{file}, and return a script to run that virtual machine (VM). - -@quotation Anmerkung -The @code{vm} action and others below can use KVM support in the Linux-libre -kernel. Specifically, if the machine has hardware virtualization support, -the corresponding KVM kernel module should be loaded, and the -@file{/dev/kvm} device node must exist and be readable and writable by the -user and by the build users of the daemon (@pxref{Einrichten der Erstellungsumgebung}). -@end quotation - -Arguments given to the script are passed to QEMU as in the example below, -which enables networking and requests 1@tie{}GiB of RAM for the emulated -machine: - -@example -$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user -@end example - -Die virtuelle Maschine verwendet denselben Store wie das Wirtssystem. - -Mit den Befehlszeilenoptionen @code{--share} und @code{--expose} können -weitere Dateisysteme zwischen dem Wirtssystem und der VM geteilt werden: Der -erste Befehl gibt ein mit Schreibzugriff zu teilendes Verzeichnis an, -während der letzte Befehl nur Lesezugriff auf das gemeinsame Verzeichnis -gestattet. - -Im folgenden Beispiel wird eine virtuelle Maschine erzeugt, die auf das -Persönliche Verzeichnis des Benutzers nur Lesezugriff hat, wo das -Verzeichnis @file{/austausch} aber mit Lese- und Schreibzugriff dem -Verzeichnis @file{$HOME/tmp} auf dem Wirtssystem zugeordnet wurde: - -@example -guix system vm my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/austausch -@end example - -Für GNU/Linux ist das vorgegebene Verhalten, direkt in den Kernel zu booten, -wodurch nur ein sehr winziges »Disk-Image« (eine Datei mit einem Abbild des -Plattenspeichers der virtuellen Maschine) für das Wurzeldateisystem nötig -wird, weil der Store des Wirtssystems davon eingebunden werden kann. - -Mit der Befehlszeilenoption @code{--full-boot} wird erzwungen, einen -vollständigen Bootvorgang durchzuführen, angefangen mit dem -Bootloader. Dadurch wird mehr Plattenplatz verbraucht, weil dazu ein -Disk-Image mindestens mit dem Kernel, initrd und Bootloader-Datendateien -erzeugt werden muss. Mit der Befehlszeilenoption @code{--image-size} kann -die Größe des Disk-Images angegeben werden. - -@cindex System-Disk-Images, Erstellung in verschiedenen Formaten -@cindex Erzeugen von System-Disk-Images in verschiedenen Formaten -@item vm-image -@itemx disk-image -@itemx docker-image -Ein eigenständiges Disk-Image für eine virtuelle Maschine, ein allgemeines -Disk-Image oder ein Docker-Abbild für das in der @var{Datei} deklarierte -Betriebssystem liefern. Das vorgegebene Verhalten von @command{guix system} -ist, die Größe des Images zu schätzen, die zum Speichern des Systems -benötigt wird, aber Sie können mit der Befehlszeilenoption -@option{--image-size} selbst Ihre gewünschte Größe -bestimmen. Docker-Abbilder werden aber so erstellt, dass sie gerade nur das -enthalten, was für sie nötig ist, daher wird die Befehlszeilenoption -@option{--image-size} im Fall von @code{docker-image} ignoriert. - -Sie können den Dateisystemtyp für das Wurzeldateisystem mit der -Befehlszeilenoption @option{--file-system-type} festlegen. Vorgegeben ist, -@code{ext4} zu verwenden. - -When using @code{vm-image}, the returned image is in qcow2 format, which the -QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for more -information on how to run the image in a virtual machine. - -Wenn Sie ein @code{disk-image} anfordern, wird ein rohes Disk-Image -hergestellt; es kann zum Beispiel auf einen USB-Stick kopiert -werden. Angenommen @code{/dev/sdc} ist das dem USB-Stick entsprechende -Gerät, dann kann das Disk-Image mit dem folgenden Befehls darauf kopiert -werden: - -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example - -Wenn Sie ein @code{docker-image} anfordern, wird ein Abbild für Docker -hergestellt. Guix erstellt das Abbild von Grund auf und @emph{nicht} aus -einem vorerstellten Docker-Basisabbild heraus, daher enthält es @emph{exakt} -das, was Sie in der Konfigurationsdatei für das Betriebssystem angegeben -haben. Sie können das Abbild dann wie folgt laden und einen Docker-Container -damit erzeugen: - -@example -image_id="$(docker load < guixsd-docker-image.tar.gz)" -docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ - --entrypoint /var/guix/profiles/system/profile/bin/guile \\ - $image_id /var/guix/profiles/system/boot -@end example - -This command starts a new Docker container from the specified image. It -will boot the Guix system in the usual manner, which means it will start any -services you have defined in the operating system configuration. Depending -on what you run in the Docker container, it may be necessary to give the -container additional permissions. For example, if you intend to build -software using Guix inside of the Docker container, you may need to pass the -@option{--privileged} option to @code{docker run}. - -@item container -Liefert ein Skript, um das in der @var{Datei} deklarierte Betriebssystem in -einem Container auszuführen. Mit Container wird hier eine Reihe -ressourcenschonender Isolierungsmechanismen im Kernel Linux-libre -bezeichnet. Container beanspruchen wesentlich weniger Ressourcen als -vollumfängliche virtuelle Maschinen, weil der Kernel, Bibliotheken in -gemeinsam nutzbaren Objektdateien (»Shared Objects«) sowie andere Ressourcen -mit dem Wirtssystem geteilt werden können. Damit ist also eine »dünnere« -Isolierung möglich. - -Zur Zeit muss das Skript als Administratornutzer »root« ausgeführt werden, -damit darin mehr als nur ein einzelner Benutzer und eine Benutzergruppe -unterstützt wird. Der Container teilt seinen Store mit dem Wirtssystem. - -Wie bei der Aktion @code{vm} (@pxref{guix system vm}) können zusätzlich -weitere Dateisysteme zwischen Wirt und Container geteilt werden, indem man -die Befehlszeilenoptionen @option{--share} und @option{--expose} verwendet: - -@example -guix system container my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/austausch -@end example - -@quotation Anmerkung -Diese Befehlszeilenoption funktioniert nur mit Linux-libre 3.19 oder neuer. -@end quotation - -@end table - -Unter den @var{Optionen} können beliebige gemeinsame Erstellungsoptionen -aufgeführt werden (siehe @pxref{Gemeinsame Erstellungsoptionen}). Des Weiteren kann -als @var{Optionen} Folgendes angegeben werden: - -@table @option -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Consider the operating-system @var{expr} evaluates to. This is an -alternative to specifying a file which evaluates to an operating system. -This is used to generate the Guix system installer @pxref{Ein Abbild zur Installation erstellen}). - -@item --system=@var{System} -@itemx -s @var{System} -Versuche, für das angegebene @var{System} statt für denselben Systemtyp wie -auf dem Wirtssystem zu erstellen. Dies funktioniert wie bei @command{guix -build} (@pxref{Aufruf von guix build}). - -@item --derivation -@itemx -d -Liefert den Namen der Ableitungsdatei für das angegebene Betriebssystem, -ohne dazu etwas zu erstellen. - -@item --file-system-type=@var{Typ} -@itemx -t @var{type} -Für die Aktion @code{disk-image} wird hiermit ein Dateisystem des -angegebenen @var{Typ}s im Abbild bzw. Disk-Image erzeugt. - -Wird diese Befehlszeilenoption nicht angegeben, so benutzt @command{guix -system} als Dateisystemtyp @code{ext4}. - -@cindex ISO-9660-Format -@cindex CD-Abbild-Format -@cindex DVD-Abbild-Format -@code{--file-system-type=iso9660} erzeugt ein Abbild im Format ISO-9660, was -für das Brennen auf CDs und DVDs geeignet ist. - -@item --image-size=@var{Größe} -Für die Aktionen @code{vm-image} und @code{disk-image} wird hiermit -festgelegt, dass ein Abbild der angegebenen @var{Größe} erstellt werden -soll. Die @var{Größe} kann als Zahl die Anzahl Bytes angeben oder mit einer -Einheit als Suffix versehen werden (siehe @pxref{Block size, size -specifications,, coreutils, GNU Coreutils}). - -Wird keine solche Befehlszeilenoption angegeben, berechnet @command{guix -system} eine Schätzung der Abbildgröße anhand der Größe des in der -@var{Datei} deklarierten Systems. - -@item --root=@var{file} -@itemx -r @var{file} -Make @var{file} a symlink to the result, and register it as a garbage -collector root. - -@item --skip-checks -Die Konfiguration @emph{nicht} vor der Installation zur Sicherheit auf -Fehler prüfen. - -Das vorgegebene Verhalten von @command{guix system init} und @command{guix -system reconfigure} sieht vor, die Konfiguration zur Sicherheit auf Fehler -hin zu überprüfen, die ihr Autor übersehen haben könnte: Es wird -sichergestellt, dass die in der @code{operating-system}-Deklaration -erwähnten Dateisysteme tatsächlich existieren (@pxref{Dateisysteme}) und -dass alle Linux-Kernelmodule, die beim Booten benötigt werden könnten, auch -im @code{initrd-modules}-Feld aufgeführt sind (@pxref{Initiale RAM-Disk}). Mit dieser Befehlszeilenoption werden diese Tests allesamt -übersprungen. - -@cindex on-error -@cindex on-error strategy -@cindex error strategy -@item --on-error=@var{Strategie} -Beim Auftreten eines Fehlers beim Einlesen der @var{Datei} die angegebene -@var{Strategie} verfolgen. Als @var{Strategie} dient eine der Folgenden: - -@table @code -@item nothing-special -Nichts besonderes; der Fehler wird kurz gemeldet und der Vorgang -abgebrochen. Dies ist die vorgegebene Strategie. - -@item backtrace -Ebenso, aber zusätzlich wird eine Rückverfolgung des Fehlers (ein -»Backtrace«) angezeigt. - -@item debug -Nach dem Melden des Fehlers wird der Debugger von Guile zur Fehlersuche -gestartet. Von dort können Sie Befehle ausführen, zum Beispiel können Sie -sich mit @code{,bt} eine Rückverfolgung (»Backtrace«) anzeigen lassen und -mit @code{,locals} die Werte lokaler Variabler anzeigen lassen. Im -Allgemeinen können Sie mit Befehlen den Zustand des Programms -inspizieren. Siehe @xref{Debug Commands,,, guile, GNU Guile Reference -Manual} für eine Liste verfügbarer Befehle zur Fehlersuche. -@end table -@end table - -Once you have built, configured, re-configured, and re-re-configured your -Guix installation, you may find it useful to list the operating system -generations available on disk---and that you can choose from the bootloader -boot menu: - -@table @code - -@item list-generations -Eine für Menschen verständliche Zusammenfassung jeder auf der Platte -verfügbaren Generation des Betriebssystems ausgeben. Dies ähnelt der -Befehlszeilenoption @option{--list-generations} von @command{guix package} -(@pxref{Aufruf von guix package}). - -Optional kann ein Muster angegeben werden, was dieselbe Syntax wie -@command{guix package --list-generations} benutzt, um damit die Liste -anzuzeigender Generationen einzuschränken. Zum Beispiel zeigt der folgende -Befehl Generationen an, die bis zu 10 Tage alt sind: - -@example -$ guix system list-generations 10d -@end example - -@end table - -Der Befehl @command{guix system} hat sogar noch mehr zu bieten! Mit -folgenden Unterbefehlen wird Ihnen visualisiert, wie Ihre Systemdienste -voneinander abhängen: - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Im Dot-/Graphviz-Format auf die Standardausgabe den -@dfn{Diensterweiterungsgraphen} des in der @var{Datei} definierten -Betriebssystems ausgeben (@pxref{Dienstkompositionen}, für mehr -Informationen zu Diensterweiterungen). - -Der Befehl: - -@example -$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf -@end example - -erzeugt eine PDF-Datei, in der die Erweiterungsrelation unter Diensten -angezeigt wird. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Im Dot-/Graphviz-Format auf die Standardausgabe den -@dfn{Abhängigkeitsgraphen} der Shepherd-Dienste des in der @var{Datei} -definierten Betriebssystems ausgeben. Siehe @xref{Shepherd-Dienste} für -mehr Informationen sowie einen Beispielgraphen. - -@end table - -@node Running Guix in a VM -@section Running Guix in a Virtual Machine - -@cindex virtuelle Maschine -To run Guix in a virtual machine (VM), one can either use the pre-built Guix -VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Aufruf von guix system}). The returned image is in qcow2 -format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently -use. - -@cindex QEMU -If you built your own image, you must copy it out of the store (@pxref{Der Store}) and give yourself permission to write to the copy before you can use -it. When invoking QEMU, you must choose a system emulator that is suitable -for your hardware platform. Here is a minimal QEMU invocation that will -boot the result of @command{guix system vm-image} on x86_64 hardware: - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image -@end example - -Here is what each of these options means: - -@table @code -@item qemu-system-x86_64 -This specifies the hardware platform to emulate. This should match the -host. - -@item -net user -Enable the unprivileged user-mode network stack. The guest OS can access -the host but not vice versa. This is the simplest way to get the guest OS -online. - -@item -net nic,model=virtio -You must create a network interface of a given model. If you do not create -a NIC, the boot will fail. Assuming your hardware platform is x86_64, you -can get a list of available NIC models by running -@command{qemu-system-x86_64 -net nic,model=help}. - -@item -enable-kvm -If your system has hardware virtualization extensions, enabling the virtual -machine support (KVM) of the Linux kernel will make things run faster. - -@item -m 256 -RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB, -which may be insufficient for some operations. - -@item /tmp/qemu-image -The file name of the qcow2 image. -@end table - -The default @command{run-vm.sh} script that is returned by an invocation of -@command{guix system vm} does not add a @command{-net user} flag by -default. To get network access from within the vm add the -@code{(dhcp-client-service)} to your system definition and start the VM -using @command{`guix system vm config.scm` -net user}. An important caveat -of using @command{-net user} for networking is that @command{ping} will not -work, because it uses the ICMP protocol. You'll have to use a different -command to check for network connectivity, for example @command{guix -download}. - -@subsection Connecting Through SSH - -@cindex SSH -@cindex SSH server -To enable SSH inside a VM you need to add a SSH server like -@code{(dropbear-service)} or @code{(lsh-service)} to your VM. The -@code{(lsh-service}) doesn't currently boot unsupervised. It requires you -to type some characters to initialize the randomness generator. In addition -you need to forward the SSH port, 22 by default, to the host. You can do -this with - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -To connect to the VM you can run - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -The @command{-p} tells @command{ssh} the port you want to connect to. -@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from -complaining every time you modify your @command{config.scm} file and the -@command{-o StrictHostKeyChecking=no} prevents you from having to allow a -connection to an unknown host every time you connect. - -@subsection Using @command{virt-viewer} with Spice - -As an alternative to the default @command{qemu} graphical client you can use -the @command{remote-viewer} from the @command{virt-viewer} package. To -connect pass the @command{-spice port=5930,disable-ticketing} flag to -@command{qemu}. See previous section for further information on how to do -this. - -Spice also allows you to do some nice stuff like share your clipboard with -your VM. To enable that you'll also have to pass the following flags to -@command{qemu}: - -@example --device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 --chardev spicevmc,name=vdagent,id=vdagent --device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent, -name=com.redhat.spice.0 -@end example - -You'll also need to add the @pxref{Verschiedene Dienste, Spice service}. - -@node Dienste definieren -@section Dienste definieren - -The previous sections show the available services and how one can combine -them in an @code{operating-system} declaration. But how do we define them -in the first place? And what is a service anyway? - -@menu -* Dienstkompositionen:: Wie Dienste zusammengestellt werden. -* Diensttypen und Dienste:: Typen und Dienste. -* Service-Referenz:: Referenz zur Programmierschnittstelle. -* Shepherd-Dienste:: Eine spezielle Art von Dienst. -@end menu - -@node Dienstkompositionen -@subsection Dienstkompositionen - -@cindex services -@cindex daemons -Here we define a @dfn{service} as, broadly, something that extends the -functionality of the operating system. Often a service is a process---a -@dfn{daemon}---started when the system boots: a secure shell server, a Web -server, the Guix build daemon, etc. Sometimes a service is a daemon whose -execution can be triggered by another daemon---e.g., an FTP server started -by @command{inetd} or a D-Bus service activated by @command{dbus-daemon}. -Occasionally, a service does not map to a daemon. For instance, the -``account'' service collects user accounts and makes sure they exist when -the system runs; the ``udev'' service collects device management rules and -makes them available to the eudev daemon; the @file{/etc} service populates -the @file{/etc} directory of the system. - -@cindex service extensions -Guix system services are connected by @dfn{extensions}. For instance, the -secure shell service @emph{extends} the Shepherd---the initialization -system, running as PID@tie{}1---by giving it the command lines to start and -stop the secure shell daemon (@pxref{Netzwerkdienste, -@code{openssh-service-type}}); the UPower service extends the D-Bus service -by passing it its @file{.service} specification, and extends the udev -service by passing it device management rules (@pxref{Desktop-Dienste, -@code{upower-service}}); the Guix daemon service extends the Shepherd by -passing it the command lines to start and stop the daemon, and extends the -account service by passing it a list of required build user accounts -(@pxref{Basisdienste}). - -All in all, services and their ``extends'' relations form a directed acyclic -graph (DAG). If we represent services as boxes and extensions as arrows, a -typical system might provide something like this: - -@image{images/service-graph,,5in,Typical service extension graph.} - -@cindex system service -At the bottom, we see the @dfn{system service}, which produces the directory -containing everything to run and boot the system, as returned by the -@command{guix system build} command. @xref{Service-Referenz}, to learn -about the other service types shown here. @xref{system-extension-graph, the -@command{guix system extension-graph} command}, for information on how to -generate this representation for a particular operating system definition. - -@cindex service types -Technically, developers can define @dfn{service types} to express these -relations. There can be any number of services of a given type on the -system---for instance, a system running two instances of the GNU secure -shell server (lsh) has two instances of @code{lsh-service-type}, with -different parameters. - -The following section describes the programming interface for service types -and services. - -@node Diensttypen und Dienste -@subsection Diensttypen und Dienste - -A @dfn{service type} is a node in the DAG described above. Let us start -with a simple example, the service type for the Guix build daemon -(@pxref{Aufruf des guix-daemon}): - -@example -(define guix-service-type - (service-type - (name 'guix) - (extensions - (list (service-extension shepherd-root-service-type guix-shepherd-service) - (service-extension account-service-type guix-accounts) - (service-extension activation-service-type guix-activation))) - (default-value (guix-configuration)))) -@end example - -@noindent -It defines three things: - -@enumerate -@item -A name, whose sole purpose is to make inspection and debugging easier. - -@item -A list of @dfn{service extensions}, where each extension designates the -target service type and a procedure that, given the parameters of the -service, returns a list of objects to extend the service of that type. - -Every service type has at least one service extension. The only exception -is the @dfn{boot service type}, which is the ultimate service. - -@item -Optionally, a default value for instances of this type. -@end enumerate - -In this example, @var{guix-service-type} extends three services: - -@table @var -@item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{<shepherd-service>} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd-Dienste}). - -@item account-service-type -This extension for this service is computed by @var{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Aufruf des guix-daemon}). - -@item activation-service-type -Here @var{guix-activation} is a procedure that returns a gexp, which is a -code snippet to run at ``activation time''---e.g., when the service is -booted. -@end table - -A service of this type is instantiated like this: - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -The second argument to the @code{service} form is a value representing the -parameters of this specific service instance. -@xref{guix-configuration-type, @code{guix-configuration}}, for information -about the @code{guix-configuration} data type. When the value is omitted, -the default value specified by @code{guix-service-type} is used: - -@example -(service guix-service-type) -@end example - -@var{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -The service type for an @emph{extensible} service looks like this: - -@example -(define udev-service-type - (service-type (name 'udev) - (extensions - (list (service-extension shepherd-root-service-type - udev-shepherd-service))) - - (compose concatenate) ;concatenate the list of rules - (extend (lambda (config rules) - (match config - (($ <udev-configuration> udev initial-rules) - (udev-configuration - (udev udev) ;the udev package to use - (rules (append initial-rules rules))))))))) -@end example - -This is the service type for the -@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management -daemon}. Compared to the previous example, in addition to an extension of -@var{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -This is the procedure to @dfn{compose} the list of extensions to services of -this type. - -Services can extend the udev service by passing it lists of rules; we -compose those extensions simply by concatenating them. - -@item extend -This procedure defines how the value of the service is @dfn{extended} with -the composition of the extensions. - -Udev extensions are composed into a list of rules, but the udev service -value is itself a @code{<udev-configuration>} record. So here, we extend -that record by appending the list of rules it contains to the list of -contributed rules. - -@item description -This is a string giving an overview of the service type. The string can -contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The -@command{guix system search} command searches these strings and displays -them (@pxref{Aufruf von guix system}). -@end table - -There can be only one instance of an extensible service type such as -@var{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -Still here? The next section provides a reference of the programming -interface for services. - -@node Service-Referenz -@subsection Service-Referenz - -We have seen an overview of service types (@pxref{Diensttypen und Dienste}). This section provides a reference on how to manipulate services -and service types. This interface is provided by the @code{(gnu services)} -module. - -@deffn {Scheme Procedure} service @var{type} [@var{value}] -Return a new service of @var{type}, a @code{<service-type>} object (see -below.) @var{value} can be any object; it represents the parameters of this -particular service instance. - -When @var{value} is omitted, the default value specified by @var{type} is -used; if @var{type} does not specify a default value, an error is raised. - -For instance, this: - -@example -(service openssh-service-type) -@end example - -@noindent -is equivalent to this: - -@example -(service openssh-service-type - (openssh-configuration)) -@end example - -In both cases the result is an instance of @code{openssh-service-type} with -the default configuration. -@end deffn - -@deffn {Scheme Procedure} service? @var{obj} -Return true if @var{obj} is a service. -@end deffn - -@deffn {Scheme Procedure} service-kind @var{service} -Return the type of @var{service}---i.e., a @code{<service-type>} object. -@end deffn - -@deffn {Scheme Procedure} service-value @var{service} -Return the value associated with @var{service}. It represents its -parameters. -@end deffn - -Here is an example of how a service is created and manipulated: - -@example -(define s - (service nginx-service-type - (nginx-configuration - (nginx nginx) - (log-directory log-directory) - (run-directory run-directory) - (file config-file)))) - -(service? s) -@result{} #t - -(eq? (service-kind s) nginx-service-type) -@result{} #t -@end example - -The @code{modify-services} form provides a handy way to change the -parameters of some of the services of a list such as @var{%base-services} -(@pxref{Basisdienste, @code{%base-services}}). It evaluates to a list of -services. Of course, you could always use standard list combinators such as -@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, -GNU Guile Reference Manual}); @code{modify-services} simply provides a more -concise form for this common pattern. - -@deffn {Scheme-Syntax} modify-services @var{Dienste} @ - (@var{Typ} @var{Variable} => @var{Rumpf}) @dots{} - -Passt die von @var{Dienste} bezeichnete Dienst-Liste entsprechend den -angegebenen Klauseln an. Jede Klausel hat die Form: - -@example -(@var{Typ} @var{Variable} => @var{Rumpf}) -@end example - -wobei @var{Typ} einen Diensttyp (»service type«) bezeichnet — wie zum -Beispiel @code{guix-service-type} — und @var{Variable} ein Bezeichner ist, -der im @var{Rumpf} an die Dienst-Parameter — z.B. eine -@code{guix-configuration}-Instanz — des ursprünglichen Dienstes mit diesem -@var{Typ} gebunden wird. - -Der @var{Rumpf} muss zu den neuen Dienst-Parametern ausgewertet werden, -welche benutzt werden, um den neuen Dienst zu konfigurieren. Dieser neue -Dienst wird das Original in der resultierenden Liste ersetzen. Weil die -Dienstparameter eines Dienstes mit @code{define-record-type*} erzeugt -werden, können Sie einen kurzen @var{Rumpf} schreiben, der zu den neuen -Dienstparametern ausgewertet wird, indem Sie die Funktionalität namens -@code{inherit} benutzen, die von @code{define-record-type*} bereitgestellt -wird. - -Siehe @xref{Das Konfigurationssystem nutzen} für ein Anwendungsbeispiel. - -@end deffn - -Next comes the programming interface for service types. This is something -you want to know when writing new service definitions, but not necessarily -when simply looking for ways to customize your @code{operating-system} -declaration. - -@deftp {Data Type} service-type -@cindex service type -This is the representation of a @dfn{service type} (@pxref{Diensttypen und Dienste}). - -@table @asis -@item @code{name} -This is a symbol, used only to simplify inspection and debugging. - -@item @code{extensions} -A non-empty list of @code{<service-extension>} objects (see below). - -@item @code{compose} (default: @code{#f}) -If this is @code{#f}, then the service type denotes services that cannot be -extended---i.e., services that do not receive ``values'' from other -services. - -Otherwise, it must be a one-argument procedure. The procedure is called by -@code{fold-services} and is passed a list of values collected from -extensions. It may return any single value. - -@item @code{extend} (default: @code{#f}) -If this is @code{#f}, services of this type cannot be extended. - -Otherwise, it must be a two-argument procedure: @code{fold-services} calls -it, passing it the initial value of the service as the first argument and -the result of applying @code{compose} to the extension values as the second -argument. It must return a value that is a valid parameter value for the -service instance. -@end table - -@xref{Diensttypen und Dienste}, for examples. -@end deftp - -@deffn {Scheme Procedure} service-extension @var{target-type} @ - @var{compute} Return a new extension for services of type -@var{target-type}. @var{compute} must be a one-argument procedure: -@code{fold-services} calls it, passing it the value associated with the -service that provides the extension; it must return a valid value for the -target service. -@end deffn - -@deffn {Scheme Procedure} service-extension? @var{obj} -Return true if @var{obj} is a service extension. -@end deffn - -Occasionally, you might want to simply extend an existing service. This -involves creating a new service type and specifying the extension of -interest, which can be verbose; the @code{simple-service} procedure provides -a shorthand for this. - -@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value} -Return a service that extends @var{target} with @var{value}. This works by -creating a singleton service type @var{name}, of which the returned service -is an instance. - -For example, this extends mcron (@pxref{Geplante Auftragsausführung}) with an -additional job: - -@example -(simple-service 'my-mcron-job mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -At the core of the service abstraction lies the @code{fold-services} -procedure, which is responsible for ``compiling'' a list of services down to -a single directory that contains everything needed to boot and run the -system---the directory shown by the @command{guix system build} command -(@pxref{Aufruf von guix system}). In essence, it propagates service -extensions down the service graph, updating each node parameters on the way, -until it reaches the root node. - -@deffn {Scheme Procedure} fold-services @var{services} @ - [#:target-type @var{system-service-type}] Fold @var{services} by propagating -their extensions down to the root of type @var{target-type}; return the root -service adjusted accordingly. -@end deffn - -Lastly, the @code{(gnu services)} module also defines several essential -service types, some of which are listed below. - -@defvr {Scheme Variable} system-service-type -This is the root of the service graph. It produces the system directory as -returned by the @command{guix system build} command. -@end defvr - -@defvr {Scheme Variable} boot-service-type -The type of the ``boot service'', which produces the @dfn{boot script}. The -boot script is what the initial RAM disk runs when booting. -@end defvr - -@defvr {Scheme Variable} etc-service-type -The type of the @file{/etc} service. This service is used to create files -under @file{/etc} and can be extended by passing it name/file tuples such -as: - -@example -(list `("issue" ,(plain-file "issue" "Welcome!\n"))) -@end example - -In this example, the effect would be to add an @file{/etc/issue} file -pointing to the given file. -@end defvr - -@defvr {Scheme Variable} setuid-program-service-type -Type for the ``setuid-program service''. This service collects lists of -executable file names, passed as gexps, and adds them to the set of -setuid-root programs on the system (@pxref{Setuid-Programme}). -@end defvr - -@defvr {Scheme Variable} profile-service-type -Type of the service that populates the @dfn{system profile}---i.e., the -programs under @file{/run/current-system/profile}. Other services can -extend it by passing it lists of packages to add to the system profile. -@end defvr - - -@node Shepherd-Dienste -@subsection Shepherd-Dienste - -@cindex shepherd services -@cindex PID 1 -@cindex init system -The @code{(gnu services shepherd)} module provides a way to define services -managed by the GNU@tie{}Shepherd, which is the initialization system---the -first process that is started when the system boots, also known as -PID@tie{}1 (@pxref{Einführung,,, shepherd, The GNU Shepherd Manual}). - -Services in the Shepherd can depend on each other. For instance, the SSH -daemon may need to be started after the syslog daemon has been started, -which in turn can only happen once all the file systems have been mounted. -The simple operating system defined earlier (@pxref{Das Konfigurationssystem nutzen}) results in a service graph like this: - -@image{images/shepherd-graph,,5in,Typical shepherd service graph.} - -You can actually generate such a graph for any operating system definition -using the @command{guix system shepherd-graph} command -(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @var{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended by -passing it lists of @code{<shepherd-service>} objects. - -@deftp {Data Type} shepherd-service -The data type representing a service managed by the Shepherd. - -@table @asis -@item @code{provision} -This is a list of symbols denoting what the service provides. - -These are the names that may be passed to @command{herd start}, -@command{herd status}, and similar commands (@pxref{Invoking herd,,, -shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the -@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details. - -@item @code{requirements} (default: @code{'()}) -List of symbols denoting the Shepherd services this one depends on. - -@item @code{respawn?} (default: @code{#t}) -Whether to restart the service when it stops, for instance when the -underlying process dies. - -@item @code{start} -@itemx @code{stop} (default: @code{#~(const #f)}) -The @code{start} and @code{stop} fields refer to the Shepherd's facilities -to start and stop processes (@pxref{Service De- and Constructors,,, -shepherd, The GNU Shepherd Manual}). They are given as G-expressions that -get expanded in the Shepherd configuration file (@pxref{G-Ausdrücke}). - -@item @code{actions} (Vorgabe: @code{'()}) -@cindex Aktionen, bei Shepherd-Diensten -This is a list of @code{shepherd-action} objects (see below) defining -@dfn{actions} supported by the service, in addition to the standard -@code{start} and @code{stop} actions. Actions listed here become available -as @command{herd} sub-commands: - -@example -herd @var{action} @var{service} [@var{arguments}@dots{}] -@end example - -@item @code{Dokumentation} -A documentation string, as shown when running: - -@example -herd doc @var{service-name} -@end example - -where @var{service-name} is one of the symbols in @var{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @var{%default-modules}) -This is the list of modules that must be in scope when @code{start} and -@code{stop} are evaluated. - -@end table -@end deftp - -@deftp {Datentyp} shepherd-action -This is the data type that defines additional actions implemented by a -Shepherd service (see above). - -@table @code -@item name -Die Aktion bezeichnendes Symbol. - -@item Dokumentation -This is a documentation string for the action. It can be viewed by running: - -@example -herd doc @var{service} action @var{action} -@end example - -@item procedure -This should be a gexp that evaluates to a procedure of at least one -argument, which is the ``running value'' of the service (@pxref{Slots of -services,,, shepherd, The GNU Shepherd Manual}). -@end table - -The following example defines an action called @code{say-hello} that kindly -greets the user: - -@example -(shepherd-action - (name 'say-hello) - (documentation "Say hi!") - (procedure #~(lambda (running . args) - (format #t "Hello, friend! arguments: ~s\n" - args) - #t))) -@end example - -Assuming this action is added to the @code{example} service, then you can -do: - -@example -# herd say-hello example -Hello, friend! arguments: () -# herd say-hello example a b c -Hello, friend! arguments: ("a" "b" "c") -@end example - -This, as you can see, is a fairly sophisticated way to say hello. -@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more -info on actions. -@end deftp - -@defvr {Scheme Variable} shepherd-root-service-type -The service type for the Shepherd ``root service''---i.e., PID@tie{}1. - -This is the service type that extensions target when they want to create -shepherd services (@pxref{Diensttypen und Dienste}, for an example). -Each extension must pass a list of @code{<shepherd-service>}. -@end defvr - -@defvr {Scheme Variable} %shepherd-root-service -This service represents PID@tie{}1. -@end defvr - - -@node Dokumentation -@chapter Dokumentation - -@cindex documentation, searching for -@cindex searching for documentation -@cindex Info, documentation format -@cindex man pages -@cindex manual pages -In most cases packages installed with Guix come with documentation. There -are two main documentation formats: ``Info'', a browseable hypertext format -used for GNU software, and ``manual pages'' (or ``man pages''), the linear -documentation format traditionally found on Unix. Info manuals are accessed -with the @command{info} command or with Emacs, and man pages are accessed -using @command{man}. - -You can look for documentation of software installed on your system by -keyword. For example, the following command searches for information about -``TLS'' in Info manuals: - -@example -$ info -k TLS -"(emacs)Network Security" -- STARTTLS -"(emacs)Network Security" -- TLS -"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags -"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function -@dots{} -@end example - -@noindent -The command below searches for the same keyword in man pages: - -@example -$ man -k TLS -SSL (7) - OpenSSL SSL/TLS library -certtool (1) - GnuTLS certificate tool -@dots {} -@end example - -These searches are purely local to your computer so you have the guarantee -that documentation you find corresponds to what you have actually installed, -you can access it off-line, and your privacy is respected. - -Once you have these results, you can view the relevant documentation by -running, say: - -@example -$ info "(gnutls)Core TLS API" -@end example - -@noindent -or: - -@example -$ man certtool -@end example - -Info manuals contain sections and indices as well as hyperlinks like those -found in Web pages. The @command{info} reader (@pxref{Top, Info reader,, -info-stnd, Stand-alone GNU Info}) and its Emacs counterpart (@pxref{Misc -Help,,, emacs, The GNU Emacs Manual}) provide intuitive key bindings to -navigate manuals. @xref{Getting Started,,, info, Info: An Introduction}, -for an introduction to Info navigation. - -@node Dateien zur Fehlersuche installieren -@chapter Dateien zur Fehlersuche installieren - -@cindex debugging files -Program binaries, as produced by the GCC compilers for instance, are -typically written in the ELF format, with a section containing -@dfn{debugging information}. Debugging information is what allows the -debugger, GDB, to map binary code to source code; it is required to debug a -compiled program in good conditions. - -The problem with debugging information is that is takes up a fair amount of -disk space. For example, debugging information for the GNU C Library weighs -in at more than 60 MiB. Thus, as a user, keeping all the debugging info of -all the installed programs is usually not an option. Yet, space savings -should not come at the cost of an impediment to debugging---especially in -the GNU system, which should make it easier for users to exert their -computing freedom (@pxref{GNU-Distribution}). - -Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism -that allows users to get the best of both worlds: debugging information can -be stripped from the binaries and stored in separate files. GDB is then -able to load debugging information from those files, when they are available -(@pxref{Separate Debug Files,,, gdb, Debugging with GDB}). - -The GNU distribution takes advantage of this by storing debugging -information in the @code{lib/debug} sub-directory of a separate package -output unimaginatively called @code{debug} (@pxref{Pakete mit mehreren Ausgaben.}). Users can choose to install the @code{debug} output of a package -when they need it. For instance, the following command installs the -debugging information for the GNU C Library and for GNU Guile: - -@example -guix package -i glibc:debug guile:debug -@end example - -GDB must then be told to look for debug files in the user's profile, by -setting the @code{debug-file-directory} variable (consider setting it from -the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with GDB}): - -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example - -From there on, GDB will pick up debugging information from the @code{.debug} -files under @file{~/.guix-profile/lib/debug}. - -In addition, you will most likely want GDB to be able to show the source -code being debugged. To do that, you will have to unpack the source code of -the package of interest (obtained with @code{guix build --source}, -@pxref{Aufruf von guix build}), and to point GDB to that source directory -using the @code{directory} command (@pxref{Source Path, @code{directory},, -gdb, Debugging with GDB}). - -@c XXX: keep me up-to-date -The @code{debug} output mechanism in Guix is implemented by the -@code{gnu-build-system} (@pxref{Erstellungssysteme}). Currently, it is -opt-in---debugging information is available only for the packages with -definitions explicitly declaring a @code{debug} output. This may be changed -to opt-out in the future if our build farm servers can handle the load. To -check whether a package has a @code{debug} output, use @command{guix package ---list-available} (@pxref{Aufruf von guix package}). - - -@node Sicherheitsaktualisierungen -@chapter Sicherheitsaktualisierungen - -@cindex security updates -@cindex security vulnerabilities -Occasionally, important security vulnerabilities are discovered in software -packages and must be patched. Guix developers try hard to keep track of -known vulnerabilities and to apply fixes as soon as possible in the -@code{master} branch of Guix (we do not yet provide a ``stable'' branch -containing only security updates.) The @command{guix lint} tool helps -developers find out about vulnerable versions of software packages in the -distribution: - -@smallexample -$ guix lint -c cve -gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 -gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276 -gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 -@dots{} -@end smallexample - -@xref{Aufruf von guix lint}, for more information. - -@quotation Anmerkung -As of version @value{VERSION}, the feature described below is considered -``beta''. -@end quotation - -Guix follows a functional package management discipline -(@pxref{Einführung}), which implies that, when a package is changed, -@emph{every package that depends on it} must be rebuilt. This can -significantly slow down the deployment of fixes in core packages such as -libc or Bash, since basically the whole distribution would need to be -rebuilt. Using pre-built binaries helps (@pxref{Substitute}), but -deployment may still take more time than desired. - -@cindex grafts -To address this, Guix implements @dfn{grafts}, a mechanism that allows for -fast deployment of critical updates without the costs associated with a -whole-distribution rebuild. The idea is to rebuild only the package that -needs to be patched, and then to ``graft'' it onto packages explicitly -installed by the user and that were previously referring to the original -package. The cost of grafting is typically very low, and order of -magnitudes lower than a full rebuild of the dependency chain. - -@cindex replacements of packages, for grafts -For instance, suppose a security update needs to be applied to Bash. Guix -developers will provide a package definition for the ``fixed'' Bash, say -@var{bash-fixed}, in the usual way (@pxref{Pakete definieren}). Then, the -original package definition is augmented with a @code{replacement} field -pointing to the package containing the bug fix: - -@example -(define bash - (package - (name "bash") - ;; @dots{} - (replacement bash-fixed))) -@end example - -From there on, any package depending directly or indirectly on Bash---as -reported by @command{guix gc --requisites} (@pxref{Aufruf von guix gc})---that -is installed is automatically ``rewritten'' to refer to @var{bash-fixed} -instead of @var{bash}. This grafting process takes time proportional to the -size of the package, usually less than a minute for an ``average'' package -on a recent machine. Grafting is recursive: when an indirect dependency -requires grafting, then grafting ``propagates'' up to the package that the -user is installing. - -Currently, the length of the name and version of the graft and that of the -package it replaces (@var{bash-fixed} and @var{bash} in the example above) -must be equal. This restriction mostly comes from the fact that grafting -works by patching files, including binary files, directly. Other -restrictions may apply: for instance, when adding a graft to a package -providing a shared library, the original shared library and its replacement -must have the same @code{SONAME} and be binary-compatible. - -The @option{--no-grafts} command-line option allows you to forcefully avoid -grafting (@pxref{Gemeinsame Erstellungsoptionen, @option{--no-grafts}}). Thus, the -command: - -@example -guix build bash --no-grafts -@end example - -@noindent -returns the store file name of the original Bash, whereas: - -@example -guix build bash -@end example - -@noindent -returns the store file name of the ``fixed'', replacement Bash. This allows -you to distinguish between the two variants of Bash. - -To verify which Bash your whole profile refers to, you can run -(@pxref{Aufruf von guix gc}): - -@example -guix gc -R `readlink -f ~/.guix-profile` | grep bash -@end example - -@noindent -@dots{} and compare the store file names that you get with those above. -Likewise for a complete Guix system generation: - -@example -guix gc -R `guix system build my-config.scm` | grep bash -@end example - -Lastly, to check which Bash running processes are using, you can use the -@command{lsof} command: - -@example -lsof | grep /gnu/store/.*bash -@end example - - -@node Bootstrapping -@chapter Bootstrapping - -@c Adapted from the ELS 2013 paper. - -@cindex bootstrapping - -Bootstrapping in our context refers to how the distribution gets built -``from nothing''. Remember that the build environment of a derivation -contains nothing but its declared inputs (@pxref{Einführung}). So there's -an obvious chicken-and-egg problem: how does the first package get built? -How does the first compiler get compiled? Note that this is a question of -interest only to the curious hacker, not to the regular user, so you can -shamelessly skip this section if you consider yourself a ``regular user''. - -@cindex bootstrap binaries -The GNU system is primarily made of C code, with libc at its core. The GNU -build system itself assumes the availability of a Bourne shell and -command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and -`grep'. Furthermore, build programs---programs that run @code{./configure}, -@code{make}, etc.---are written in Guile Scheme (@pxref{Ableitungen}). -Consequently, to be able to build anything at all, from scratch, Guix relies -on pre-built binaries of Guile, GCC, Binutils, libc, and the other packages -mentioned above---the @dfn{bootstrap binaries}. - -These bootstrap binaries are ``taken for granted'', though we can also -re-create them if needed (more on that later). - -@unnumberedsec Preparing to Use the Bootstrap Binaries - -@c As of Emacs 24.3, Info-mode displays the image, but since it's a -@c large image, it's hard to scroll. Oh well. -@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap -derivations} - -The figure above shows the very beginning of the dependency graph of the -distribution, corresponding to the package definitions of the @code{(gnu -packages bootstrap)} module. A similar figure can be generated with -@command{guix graph} (@pxref{Aufruf von guix graph}), along the lines of: - -@example -guix graph -t derivation \ - -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ - | dot -Tps > t.ps -@end example - -At this level of detail, things are slightly complex. First, Guile itself -consists of an ELF executable, along with many source and compiled Scheme -files that are dynamically loaded when it runs. This gets stored in the -@file{guile-2.0.7.tar.xz} tarball shown in this graph. This tarball is part -of Guix's ``source'' distribution, and gets inserted into the store with -@code{add-to-store} (@pxref{Der Store}). - -But how do we write a derivation that unpacks this tarball and adds it to -the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} -derivation---the first one that gets built---uses @code{bash} as its -builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls -@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, @file{xz}, -and @file{mkdir} are statically-linked binaries, also part of the Guix -source distribution, whose sole purpose is to allow the Guile tarball to be -unpacked. - -Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning Guile -that can be used to run subsequent build programs. Its first task is to -download tarballs containing the other pre-built binaries---this is what the -@code{.tar.xz.drv} derivations do. Guix modules such as -@code{ftp-client.scm} are used for this purpose. The -@code{module-import.drv} derivations import those modules in a directory in -the store, using the original layout. The @code{module-import-compiled.drv} -derivations compile those modules, and write them in an output directory -with the right layout. This corresponds to the @code{#:modules} argument of -@code{build-expression->derivation} (@pxref{Ableitungen}). - -Finally, the various tarballs are unpacked by the derivations -@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etc., at which -point we have a working C tool chain. - - -@unnumberedsec Building the Build Tools - -Bootstrapping is complete when we have a full tool chain that does not -depend on the pre-built bootstrap tools discussed above. This no-dependency -requirement is verified by checking whether the files of the final tool -chain contain references to the @file{/gnu/store} directories of the -bootstrap inputs. The process that leads to this ``final'' tool chain is -described by the package definitions found in the @code{(gnu packages -commencement)} module. - -The @command{guix graph} command allows us to ``zoom out'' compared to the -graph above, by looking at the level of package objects instead of -individual derivations---remember that a package may translate to several -derivations, typically one derivation to download its source, one to build -the Guile modules it needs, and one to actually build the package from -source. The command: - -@example -guix graph -t bag \ - -e '(@@@@ (gnu packages commencement) - glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps -@end example - -@noindent -produces the dependency graph leading to the ``final'' C -library@footnote{You may notice the @code{glibc-intermediate} label, -suggesting that it is not @emph{quite} final, but as a good approximation, -we will consider it final.}, depicted below. - -@image{images/bootstrap-packages,6in,,Dependency graph of the early -packages} - -@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. -The first tool that gets built with the bootstrap binaries is -GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite for -all the following packages. From there Findutils and Diffutils get built. - -Then come the first-stage Binutils and GCC, built as pseudo cross -tools---i.e., with @code{--target} equal to @code{--host}. They are used to -build libc. Thanks to this cross-build trick, this libc is guaranteed not -to hold any reference to the initial tool chain. - -From there the final Binutils and GCC (not shown above) are built. GCC uses -@code{ld} from the final Binutils, and links programs against the just-built -libc. This tool chain is used to build the other packages used by Guix and -by the GNU Build System: Guile, Bash, Coreutils, etc. - -And voilà! At this point we have the complete set of build tools that the -GNU Build System expects. These are in the @code{%final-inputs} variable of -the @code{(gnu packages commencement)} module, and are implicitly used by -any package that uses @code{gnu-build-system} (@pxref{Erstellungssysteme, -@code{gnu-build-system}}). - - -@unnumberedsec Building the Bootstrap Binaries - -@cindex bootstrap binaries -Because the final tool chain does not depend on the bootstrap binaries, -those rarely need to be updated. Nevertheless, it is useful to have an -automated way to produce them, should an update occur, and this is what the -@code{(gnu packages make-bootstrap)} module provides. - -The following command builds the tarballs containing the bootstrap binaries -(Guile, Binutils, GCC, libc, and a tarball containing a mixture of Coreutils -and other basic command-line tools): - -@example -guix build bootstrap-tarballs -@end example - -The generated tarballs are those that should be referred to in the -@code{(gnu packages bootstrap)} module mentioned at the beginning of this -section. - -Still here? Then perhaps by now you've started to wonder: when do we reach a -fixed point? That is an interesting question! The answer is unknown, but if -you would like to investigate further (and have significant computational -and storage resources to do so), then let us know. - -@unnumberedsec Reducing the Set of Bootstrap Binaries - -Our bootstrap binaries currently include GCC, Guile, etc. That's a lot of -binary code! Why is that a problem? It's a problem because these big chunks -of binary code are practically non-auditable, which makes it hard to -establish what source code produced them. Every unauditable binary also -leaves us vulnerable to compiler backdoors as described by Ken Thompson in -the 1984 paper @emph{Reflections on Trusting Trust}. - -This is mitigated by the fact that our bootstrap binaries were generated -from an earlier Guix revision. Nevertheless it lacks the level of -transparency that we get in the rest of the package dependency graph, where -Guix always gives us a source-to-binary mapping. Thus, our goal is to -reduce the set of bootstrap binaries to the bare minimum. - -The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists -on-going projects to do that. One of these is about replacing the bootstrap -GCC with a sequence of assemblers, interpreters, and compilers of increasing -complexity, which could be built from source starting from a simple and -auditable assembler. Your help is welcome! - - -@node Portierung -@chapter Porting to a New Platform - -As discussed above, the GNU distribution is self-contained, and -self-containment is achieved by relying on pre-built ``bootstrap binaries'' -(@pxref{Bootstrapping}). These binaries are specific to an operating system -kernel, CPU architecture, and application binary interface (ABI). Thus, to -port the distribution to a platform that is not yet supported, one must -build those bootstrap binaries, and update the @code{(gnu packages -bootstrap)} module to use them on that platform. - -Fortunately, Guix can @emph{cross compile} those bootstrap binaries. When -everything goes well, and assuming the GNU tool chain supports the target -platform, this can be as simple as running a command like this one: - -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example - -For this to work, the @code{glibc-dynamic-linker} procedure in @code{(gnu -packages bootstrap)} must be augmented to return the right file name for -libc's dynamic linker on that platform; likewise, -@code{system->linux-architecture} in @code{(gnu packages linux)} must be -taught about the new platform. - -Once these are built, the @code{(gnu packages bootstrap)} module needs to be -updated to refer to these binaries on the target platform. That is, the -hashes and URLs of the bootstrap tarballs for the new platform must be added -alongside those of the currently supported platforms. The bootstrap Guile -tarball is treated specially: it is expected to be available locally, and -@file{gnu/local.mk} has rules to download it for the supported -architectures; a rule for the new platform must be added as well. - -In practice, there may be some complications. First, it may be that the -extended GNU triplet that specifies an ABI (like the @code{eabi} suffix -above) is not recognized by all the GNU tools. Typically, glibc recognizes -some of these, whereas GCC uses an extra @code{--with-abi} configure flag -(see @code{gcc.scm} for examples of how to handle this). Second, some of -the required packages could fail to build for that platform. Lastly, the -generated binaries could be broken for some reason. - -@c ********************************************************************* -@include contributing.de.texi - -@c ********************************************************************* -@node Danksagungen -@chapter Danksagungen - -Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, -which was designed and implemented by Eelco Dolstra, with contributions from -other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered -functional package management, and promoted unprecedented features, such as -transactional package upgrades and rollbacks, per-user profiles, and -referentially transparent build processes. Without this work, Guix would -not exist. - -The Nix-based software distributions, Nixpkgs and NixOS, have also been an -inspiration for Guix. - -GNU@tie{}Guix itself is a collective work with contributions from a number -of people. See the @file{AUTHORS} file in Guix for more information on -these fine people. The @file{THANKS} file lists people who have helped by -reporting bugs, taking care of the infrastructure, providing artwork and -themes, making suggestions, and more---thank you! - - -@c ********************************************************************* -@node GNU-Lizenz für freie Dokumentation -@appendix GNU-Lizenz für freie Dokumentation -@cindex license, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Konzeptverzeichnis -@unnumbered Konzeptverzeichnis -@printindex cp - -@node Programmierverzeichnis -@unnumbered Programmierverzeichnis -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: diff --git a/doc/guix.fr.texi b/doc/guix.fr.texi deleted file mode 100644 index 541fd6f0d0..0000000000 --- a/doc/guix.fr.texi +++ /dev/null @@ -1,25303 +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 -Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright -@copyright{} 2016, 2017 ng0@* Copyright @copyright{} 2016, 2017, -2018, 2019 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* -Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, -2017, 2018, 2019 Christopher Baines@* Copyright @copyright{} 2017, 2018 -Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* -Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, -2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* -Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 -Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@* -Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017 -Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@* -Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 -Andy Wingo@* Copyright @copyright{} 2017, 2018 Arun Isaac@* Copyright -@copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* -Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike -Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright -@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian -Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} -2018 Alex Vong@* - -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. -* Development:: Guix-aided software development. -* 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 - - - -* Managing Software the Guix Way:: What's special. -* Distribution GNU:: The packages and tools. - -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. -* Effectuer l'installation:: Pour de vrai. -* Installing Guix in a VM:: Guix System playground. -* Construire l'image d'installation:: D'où vient tout cela. - -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 ? - -Development - - - -* 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 de paquet:: Le type de donnée des paquets. -* Référence d'origine:: 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. -* 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. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* 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'' 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{Distribution GNU}. - -@menu -* Managing Software the Guix Way:: What's special. -* Distribution GNU:: The packages and tools. -@end menu - -@node Managing Software the Guix Way -@section Managing Software the Guix Way - -@cindex interfaces utilisateurs -Guix provides a command-line package management interface (@pxref{Gestion de paquets}), tools to help with software development (@pxref{Development}), -command-line utilities for more advanced usage, (@pxref{Utilitaires}), as well -as Scheme programming interfaces (@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 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{Installation du système}), 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. - -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 - -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{Configuration système}). 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 -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 -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{Installation du système}.} The script -automates the download, installation, and initial configuration of Guix. It -should be run as the root user. -@end quotation - -@cindex distro extérieure -@cindex répertoires liés aux distro extérieures -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. - -Une fois installé, Guix peut être mis à jour en lançant @command{guix pull} -(@pxref{Invoquer 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 -* 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 -To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its -mirrors (@pxref{Substituts}), authorize them: - -@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 -...@: which, in turn, runs: - -@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 is available for download from its website at -@url{https://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 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 -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 - -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 - -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 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 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} -Consider @var{urls} the default whitespace-separated list of substitute -source URLs. When this option is omitted, -@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used. - -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 extérieure -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 Régionalisation - -@anchor{locales-and-locpath} -@cindex locales, when not on 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 <https://bugs.gnu.org/30655>. -@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. - -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 Installation du système -@chapter Installation du système - -@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 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. -* Effectuer l'installation:: Pour de vrai. -* Installing Guix in a VM:: Guix System playground. -* Construire l'image d'installation:: D'où vient tout cela. -@end menu - -@node Limitations -@section Limitations - -As of version @value{VERSION}, Guix System is not production-ready. It may -contain bugs and lack important features. Thus, if you are looking for a -stable production system that respects your freedom as a computer user, a -good solution at this point is to consider -@url{http://www.gnu.org/distros/free-distros.html, one of the more -established GNU/Linux distributions}. We hope you can soon switch to the -Guix System without fear, of course. In the meantime, you can also keep -using your distribution and try out the package manager on top of it -(@pxref{Installation}). - -Avant de procéder à l'installation, soyez conscient de ces limitations les -plus importantes qui s'appliquent à la version @value{VERSION} : - -@itemize -@item -Le procédé d'installation n'a pas d'interface utilisateur graphique et -requiert une certaine familiarité avec GNU/Linux (voir les sous-sections -suivantes pour avoir un aperçu de ce que cela signifie). - -@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 -More than 8,500 packages are available, but you might occasionally find that -a useful package is missing. - -@item -GNOME, Xfce, LXDE et Enlightenment sont disponibles (@pxref{Services de bureaux}), ainsi qu'un certain nombre de gestionnaires de fenêtres X11. -cependant, certaines applications graphiques peuvent manquer, ainsi que KDE. -@end itemize - -Vous êtes avertis ! Mais plus qu'un avertissement, c'est une invitation à -rapporter les problèmes (et vos succès !) et à nous rejoindre pour améliorer -la distribution. @xref{Contribuer}, pour plus d'info. - - -@node Considérations matérielles -@section Considérations matérielles - -@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, 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 @var{%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/guixsd-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/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guixsd-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 guixsd-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=guixsd-install-@value{VERSION}.@var{system}.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 guixsd-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=guixsd-install-@value{VERSION}.@var{system}.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{Installing Guix in a VM}, if, instead, you would like to install Guix -System in a virtual machine (VM). - - -@node Préparer l'installation -@section Préparer l'installation - -Once you have successfully booted your computer using the installation -medium, you should end up with the welcome page of the graphical installer. -The graphical installer is a text-based user interface built upon the newt -library. It shall guide you through all the different steps needed to -install GNU@tie{}Guix System. However, as the graphical installer is still -under heavy development, you might want to fallback to the original, shell -based install process, by switching to TTYs 3 to 6 with the shortcuts -CTRL-ALT-F[3-6]. The following sections describe the installation procedure -assuming you're using one of those TTYs. They are configured and can be used -to run commands as root. - -TTY2 shows this documentation, browsable using the Info reader commands -(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system -runs the GPM mouse daemon, which allows you to select text with the left -mouse button and to paste it with the middle button. - -@quotation 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 - -The installation system includes many common tools needed for this task. -But it is also a full-blown Guix System, which means that you can install -additional packages, should you need it, using @command{guix package} -(@pxref{Invoquer guix package}). - -@subsection 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. - -@subsection 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. - -@subsection 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 -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 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 - -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 - -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 - -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. - -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 -@section 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 -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-sytem} entry is specified in your 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ée — 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}). - -@cindex upgrading Guix System -From then on, you can update the system whenever you want by running, say: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -This builds a new system generation with the latest packages and services -(@pxref{Invoquer guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Mises à jour de sécurité}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@quotation Remarque -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. -@end quotation - -Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience---good or not so good. - -@node Installing Guix in a VM -@section Installing Guix in a Virtual Machine - -@cindex virtual machine, Guix System installation -@cindex serveur privé virtuel (VPS) -@cindex VPS (serveur privé virtuel) -If you'd like to install Guix System in a virtual machine (VM) or on a -virtual private server (VPS) rather than on your beloved machine, this -section is for you. - -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a -disk image, follow these steps: - -@enumerate -@item -First, retrieve and decompress the Guix system installation image as -described previously (@pxref{Installation 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=guixsd-install-@value{VERSION}.@var{system}.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 - -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 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. - -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{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{<package>}. 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 -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}). - -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 '\<board\>' -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 -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}). - -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 -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{Invoquer 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 Remarque -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 - -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 -This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are -usable and will be downloaded, when possible, for future builds. - -@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 -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{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}). - -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 - -It is perfectly safe to run as a non-interactive periodic job -(@pxref{Exécution de tâches planifiées}, 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. - -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 -@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 --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 - -@ref{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} -Télécharger le code depuis l'@var{url} spécifié, au @var{commit} donné (un -commit Git valide représenté par une chaîne hexadécimale) ou à la branche -@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}). - -@ref{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 <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> 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 - -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 -;; 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 -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{} -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. - -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 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 de paquet}). 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. - -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 - -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 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 -* 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 -...@: or to browse the profile: - -@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 - -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 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 - -starts a shell with all the base system packages available. - -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 -Unset existing environment variables when building the new environment, -except those specified with @option{--inherit} (see below.) This has the -effect of creating an environment in which search paths only contain package -inputs. - -@item --inherit=@var{regexp} -When used alongside @option{--pure}, inherit all 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 --inherit=^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 -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, mais a les privilèges root dans le contexte -du conteneur. - -@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/UTILISATEUR} ; et aucune donnée GECOS ne sera -copiée. @var{utilisateur} 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 - -@command{guix environment} also supports all of the common build options -that @command{guix build} supports (@pxref{Options de construction communes}) as well as -package transformation options (@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 - -@item --relocatable -@itemx -R -Produit 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à. Par exemple, si vous créez un pack contenant -Bash avec : - -@example -guix pack -R -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 -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. - -Il y a un inconvénient cependant : cette technique repose sur les -@dfn{espaces de noms} du noyau Linux qui permettent à des utilisateurs -non-privilégiés de monter des systèmes de fichiers ou de changer de racine. -Les anciennes versions de Linux ne le supportaient pas et certaines -distributions GNU/Linux les désactivent ; sur ces système, les programme du -pack @emph{ne fonctionneront pas} à moins qu'ils ne soient décompressés à la -racine du système de fichiers. - -@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 --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{<package>} -(@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{<package>}, 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{<origin>} (@pxref{Référence d'origine}, 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{<package>}. - -@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 de paquet}, 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{<package>} 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{<derivation>} du @var{paquet} pour le @var{système} -(@pxref{Dérivations}). - -@var{paquet} doit être un objet @code{<package>} 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{<derivation>} -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}}). - -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 de paquet:: Le type de donnée des paquets. -* Référence d'origine:: Le type de données d'origine. -@end menu - - -@node Référence de paquet -@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 d'origine}). 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{self-native-input?} (par défaut : @code{#f}) -C'est un champ booléen qui indique si le paquet devrait s'utiliser lui-même -comme entrée native lors de la compilation croisée. - -@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 - - -@node Référence d'origine -@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{<build-system>}. 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{<build-system>} 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{<system>-tests.asd}, @code{<system>-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 {Scheme Variable} dune-build-system -This variable is exported by @code{(guix build-system dune)}. It supports -builds of packages using @uref{https://dune.build/, Dune}, a build tool for -the OCaml programming language. It is implemented as an extension of the -@code{ocaml-build-system} which is described below. As such, the -@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build -system. - -It automatically adds the @code{dune} package to the set of inputs. Which -package is used can be specified with the @code{#:dune} parameter. - -There is no @code{configure} phase because dune packages typically don't -need to be configured. The @code{#:build-flags} parameter is taken as a -list of flags passed to the @code{dune} command during the build. - -The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} -command instead of the more recent @code{dune} command while building a -package. Its default value is @code{#f}. -@end defvr - -@defvr {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 être installées -avec leur code source. La clef @code{#:install-soruce?}, 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} 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 -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 {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 - -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}).}. - -@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). - -A @code{&store-protocol-error} condition is raised if @var{path} is not -prefixed by the store directory (@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{<derivation>} 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 -Les entrées de la dérivation, 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. - -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{<derivation>} 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{} #<derivation /gnu/store/@dots{}-foo.drv => /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{} #<derivation /gnu/store/@dots{}-goo.drv => @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 <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> -@c for the funny quote. -L'appel à la procédure monadique @code{sh-symlink} n'a aucun effet. En -anglais on pourrait dire « you exit a monad like you exit a building on -fire: by running »@footnote{NdT : « on sort d'une monade comme d'un immeuble -en flamme, en courant ». Le jeu de mot est perdu à la traduction : courir -et lancer utilisent le même verbe @i{run} en anglais.}. 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 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @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 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @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{<computed-file>} 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{<package>}. -@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 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> -@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 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} -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{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 - -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-branch=@var{package}=@var{branch} -@cindex Git, using the latest commit -@cindex latest commit, building -Build @var{package} from the latest commit of @var{branch}. The -@code{source} field of @var{package} must be an origin with the -@code{git-fetch} method (@pxref{Référence d'origine}) or a @code{git-checkout} -object; the repository URL is taken from that @code{source}. Git -sub-modules of the repository are fetched, recursively. - -For instance, the following command builds @code{guile-sqlite3} from the -latest commit of its @code{master} branch, and then builds @code{guix} -(which depends on it) and @code{cuirass} (which depends on @code{guix}) -against this specific @code{guile-sqlite3} build: - -@example -guix build --with-branch=guile-sqlite3=master cuirass -@end example - -@cindex intégration continue -Obviously, since it uses the latest commit of the given branch, the result -of such a command varies over time. Nevertheless it is a convenient way to -rebuild entire software stacks against the latest commit of one or more -packages. This is particularly useful in the context of continuous -integration (CI). - -Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed -up consecutive accesses to the same repository. You may want to clean it up -once in a while to save disk space. - -@item --with-commit=@var{package}=@var{commit} -This is similar to @code{--with-branch}, except that it builds from -@var{commit} rather than the tip of a branch. @var{commit} must be a valid -Git commit SHA1 identifier. -@end table - -@node 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 -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{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 -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{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. - -@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 d'origine}) : - -@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 -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. - -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 -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. - -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 -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. - -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 -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 - -Les noms des champs sont les mêmes que pour les enregistrements de -@code{<package>} (@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{<origin>} : - -@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 -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 - -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} ; -@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 -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. - -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 - -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 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 -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{Référence d'origine}). - -@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 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 <http://www.openwall.com/lists/oss-security/2017/03/15/3>. -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 - -...@: yields the graph of packages that depend on OCaml. - -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 - -...@: yields this bigger graph: - -@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 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}). - -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. - -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 d'origine}). 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 - -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}}). - -Si vous avez installé Guix sur une « distro extérieure », 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" -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 é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 -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{Fonctionnalités}). 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. - -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 - -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. - -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. - -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{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}. - -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 - -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 -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). - -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}] -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.fr.info -c 10 -computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.fr.info... -updating substitutes from 'https://ci.guix.fr.info'... 100.0% -https://ci.guix.fr.info - 64.7% substitutes available (6,047 out of 9,343) -@dots{} -2502 packages are missing from 'https://ci.guix.fr.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.fr.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 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. -* 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. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* 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 -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{Services réseau, @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{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 - -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 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{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{<name-service-switch>}. @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}. - -@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 -@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{<file-system>} ou @code{<mapped-device>} 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} -@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. @xref{crypt,,, 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 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 <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> -@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. -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. - -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. - -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 has a broad definition of ``service'' (@pxref{Composition de services}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Services 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 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 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{<login-configuration>} 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{<mingetty-configuration>}, 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{<agetty-configuration>}, 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. - -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} (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{<kmscon-configuration>}, 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{<nscd-configuration>}. @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{<nscd-configuration>} (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{<nscd-cache>} 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{<nscd-cache>} 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 -Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substituts}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (par défaut : @var{%default-authorized-guix-keys}) -The list of authorized key files for archive imports, as a list of -string-valued gexps (@pxref{Invoquer guix archive}). By default, it -contains that of @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 - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@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 disposition clavier -@cindex clavier -@deffn {Procédure Scheme} console-keymap-service @var{files} ... -@cindex disposition du clavier -Renvoie un service qui charge les dispositions claviers de @var{files} avec -la commande @command{loadkeys}. Vraisemblablement, vous voudrez charger une -disposition par défaut, ce qui se fait ainsi : - -@example -(console-keymap-service "dvorak") -@end example - -Ou par exemple pour un clavier suédois, vous pourriez avoir besoin de -combiner les dispositions suivantes : -@example -(console-keymap-service "se-lat6" "se-fi-lat6") -@end example - -Vous pouvez aussi spécifier le nom de fichier (ou les noms de fichiers) -complets de vos dispositions. Voir @code{man loadkeys} pour des détails. - -@end deffn - -@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{<dhcpd-configuration>}. 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 <static-networking> 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 -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 {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 -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. - -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} -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} (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{'()}) -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} 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{<tor-configuration>}. 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{<hidden-service>} à 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{<hidden-service>} 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}) -Specifies whether challenge response authentication is allowed (e.g.@: 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"))}) -Configures external subsystems (e.g.@: file transfer daemon). - -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{""}) -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 {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{<dropbear-configuration>}. - -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 {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 {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 -Le support pour le 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 SLiM. - -@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} slim-service-type -C'est de type pour le gestionnaire de connexion graphique SLiM pour X11. - -@cindex types de sessions (X11) -@cindex X11, types de sessions -SLiM 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 -avec @kbd{F1}. Les paquets comme @code{xfce}, @code{sawfish} et -@code{ratpoison} 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} 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{startx} (par défaut : @code{(xorg-start-command)}) -La commande utilisée pour démarrer le serveur graphique X11. - -@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-server-path} (par défaut : @code{xorg-start-command}) -Chemin vers xorg-server. - -@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{xserver-arguments} (par défaut : "-nolisten tcp") -Arguments à passer à xorg-server. - -@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{<sddm-configuration>}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@deffn {Procédure Scheme} xorg-start-command [#:guile] @ - [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @ -[#:configuration-file (xorg-configuration-file @dots{})] @ [#:xorg-server -@var{xorg-server}] [#:xserver-arguments '("-nolisten" "tcp")] Return a -@code{startx} script in which @var{modules}, a list of X module packages, -and @var{fonts}, a list of X font directories, are available. See -@code{xorg-wrapper} for more details on the arguments. The result should be -used in place of @code{startx}. - -Habituellement le serveur X est démarré par un gestionnaire de connexion. -@end deffn - -@cindex @code{-listen tcp}, for X11. -This procedure is useful to override command line options for the X server, -such as having it listen to over TCP: - -@example -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:xserver-arguments '("-listen" "tcp")))))))) -@end example - -@deffn {Procédure Scheme} xorg-configuration-file @ - [#:modules %default-xorg-modules] @ -[#:fonts %default-xorg-fonts] @ -[#:drivers '()] [#:resolutions '()] [#:extra-config '()] -Renvoie un fichier de configuration pour le serveur Xorg qui contient des -chemins de recherche pour tous les pilotes communs. - -@var{modules} doit être une liste de @dfn{paquets de modules} chargés par le -serveur Xorg — p.@: ex.@: @code{xf86-video-vesa}, @code{xf86-input-keyboard} -etc. @var{fonts} doit être une liste de répertoires de polices à ajouter au -@dfn{chemin de polices} du serveur. - -@var{drivers} doit être soit la liste vide, auquel cas Xorg choisis un -pilote graphique automatiquement, soit une liste de noms de pilotes qui -seront essayés dans cet ordre — p.@: ex.@: @code{("modesetting" "vesa")}. - -De même, lorsque @var{resolutions} est la liste vide, Xorg choisis une -résolution d'écran appropriée ; autrement, ce doit être une liste de -résolutions — p.@: ex.@: @code{((1024 768) (640 480))}. - -Enfin, @var{extra-config} est une liste de chaînes de caractères ou d'objets -ajoutés au fichier de configuration. Elle est utilisée pour passer du texte -supplémentaire à être ajouté directement au fichier de configuration. - -@cindex disposition clavier -@cindex disposition du clavier -Cette procédure est particulièrement utile pour configurer une disposition -de clavier différente de la disposition US par défaut. Par exemple, pour -utiliser la disposition « bépo » par défaut sur le gestionnaire d'affichage -: - -@example -(define bepo-evdev - "Section \"InputClass\" - Identifier \"evdev keyboard catchall\" - Driver \"evdev\" - MatchIsKeyboard \"on\" - Option \"xkb_layout\" \"fr\" - Option \"xkb_variant\" \"bepo\" -EndSection") - -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:configuration-file - (xorg-configuration-file - #:extra-config - (list bepo-evdev))))))))) -@end example - -La ligne @code{MatchIsKeyboard} spécifie que nous n'appliquons la -configuration qu'aux claviers. Sans cette ligne, d'autres périphériques -comme les pavés tactiles ne fonctionneront pas correctement parce qu'ils -seront associés au mauvais pilote. Dans cet exemple, l'utilisateur -utiliserait typiquement @code{setxkbmap fr bepo} pour utiliser sa -disposition de clavier préférée une fois connecté. Le premier argument -correspond à la disposition, tandis que le second argument correspond à la -variante. La ligne @code{xkb_variant} peut être omise pour choisir la -variante par défaut. -@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 -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 -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{slim-service}}), 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 leur -mot de passe, 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}, -@code{xfce-desktop-service}, @code{mate-desktop-service} 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} ajoute le métapaquet GNOME au profil du -système. de même, ajouter le service XFCE ajoute 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. « 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 -@code{slim-service} 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. - -@deffn {Procédure Scheme} gnome-desktop-service -Renvoie un service qui ajoute le paquet @code{gnome} au profil système et -étend polkit avec des actions de @code{gnome-settings-daemon}. -@end deffn - -@deffn {Procédure Scheme} xfce-desktop-service -Renvoie un service qui ajoute le paquet @code{xfce} au profil du système et -étend polkit avec la capacité pour @code{thunar} de manipuler le système de -fichier en tant que root depuis une session utilisateur, après que -l'utilisateur s'est authentifié avec le mot de passe administrateur. -@end deffn - -@deffn {Procédure Scheme} mate-desktop-service -Renvoie un service qui ajoute le paquet @code{mate} au profil du système et -étend polkit avec les actions de @code{mate-settings-daemon}. -@end deffn - -@deffn {Procédure 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 les élément à la liste donnée en dernier argument - (services (cons* (gnome-desktop-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 {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 {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 : -# <http://jackaudio.org/faq/routing_alsa.html>. -pcm.rawjack @{ - type jack - playback_ports @{ - 0 system:playback_1 - 1 system:playback_2 - @} - - capture_ports @{ - 0 system:capture_1 - 1 system:capture_2 - @} -@} - -pcm.!default @{ - type plug - slave @{ - pcm "rawjack" - @} -@} -@end example - -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 '()] Return a service -that runs @var{postgresql}, the PostgreSQL database server. - -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 -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 {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{<mysql-configuration>}. -@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. <doc/wiki/LoginProcess.txt>. 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 -List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} 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 {paramètre de @code{dovecot-configuration}} 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 {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? -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 {paramètre de @code{dovecot-configuration}} 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 {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 -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 {paramètre de @code{dovecot-configuration}} string auth-master-user-separator -If you want to allow master users to log in by specifying the master -username within the normal username string (i.e.@: not using SASL -mechanism's support for it), you can specify the separator character here. -The format is then <username><separator><master username>. UW-IMAP uses -@samp{*} as the separator, so that could be a good choice. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {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 -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 {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}. -<doc/wiki/Authentication/Mechanisms/Winbind.txt>. 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? -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 {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 %$ -Delivery status message (e.g.@: @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. - -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. - -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. -<doc/wiki/UserIds.txt>. 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 -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 {paramètre de @code{dovecot-configuration}} 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 {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 -Useful with e.g.@: NFS when write()s are delayed -@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 -List of directories under which chrooting is allowed for mail processes -(i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This -setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot -settings. If this setting is empty, "/./" in home dirs are ignored. -WARNING: Never add directories here which local users can modify, that may -lead to root exploit. Usually this should be done only if you don't allow -shell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string mail-chroot -Default chroot directory for mail processes. This can be overridden for -specific users in user database by giving /./ in user's home directory -(e.g.@: /home/./user chroots into /home). Note that usually there is no -real need to do chrooting, Dovecot doesn't allow users to access files -outside their mail directory anyway. If your home directories are prefixed -with the chroot directory, append "/."@: to @samp{mail-chroot}. -<doc/wiki/Chrooting.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {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 -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 {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 <mailbox>.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 -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 {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 -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 {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. <doc/wiki/SSL.txt>. 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{"</etc/dovecot/default.pem"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-key -Clef privée SSL/TLS encodée en PEM. La clef est ouverte avant l'abandon des -privilèges root, donc laissez-la non-lisible pour les utilisateurs. La -valeur par défaut est @samp{"</etc/dovecot/private/default.pem"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-key-password -Si le fichier de clef est protégé par un mot de passe, donnez-le ici. -Autrement, donnez-le en démarrant dovecot avec le paramètre -p. Comme ce -fichier est souvent lisible pour tout le monde, vous pourriez vouloir placer -ce paramètre dans un autre fichier. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-ca -PEM encoded trusted certificate authority. Set this only if you intend to -use @samp{ssl-verify-client-cert? #t}. The file should contain the CA -certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca -</etc/ssl/certs/ca.pem}). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean ssl-require-crl? -Indique si les certificats clients doivent réussir la vérification du CRL. -La valeur par défaut est @samp{#t}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean ssl-verify-client-cert? -Demande aux clients d'envoyer un certificat. Si vous voulez aussi le -requérir, indiquez @samp{auth-ssl-require-client-cert? #t} dans la section -auth. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-cert-username-field -Le champ du certificat à utiliser pour le nom d'utilisateur. Les choix -habituels sont commonName et X500UniqueIdentifier. Vous devrez aussi -indiquer @samp{auth-ssl-username-from-cert? #t}. La valeur par défaut est -@samp{"commonName"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-min-protocol -Version minimale de SSL à accepter. La valeur par défaut est -@samp{"TLSv1"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-cipher-list -Méthodes de chiffrement à utiliser. La valeur par défaut est -@samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string ssl-crypto-device -Moteur cryptographique SSL à utiliser. Pour les valeur valides, lancez « -openssl engine ». La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string postmaster-address -Adresse à utiliser pour envoyer les courriels de rejet. %d correspond au -domaine du destinataire. La valeur par défaut est @samp{"postmaster@@%d"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string hostname -Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and -in LMTP replies. Default is the system's real hostname@@domain. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} boolean quota-full-tempfail? -Si l'utilisateur dépasse le quota, renvoie un échec temporaire au lieu de -rejeter le courriel. La valeur par défaut est @samp{#f}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} file-name sendmail-path -Binaire à utiliser pour envoyer des courriels. La valeur par défaut est -@samp{"/usr/sbin/sendmail"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string submission-host -Si la valeur est non vide, envoyer les courriels à ce serveur SMTP -hôte[:port] au lieu de sendmail. La valeur par défaut est @samp{""}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string rejection-subject -En-tête d'objet à utiliser pour les courriels de rejet. Vous pouvez -utiliser les mêmes variables que pour @samp{rejection-reason} ci-dessous. -La valeur par défaut est @samp{"Rejected: %s"}. -@end deftypevr - -@deftypevr {paramètre de @code{dovecot-configuration}} string rejection-reason -Message d'erreur pour les humains dans les courriels de rejet. Vous pouvez -utiliser ces variables : - -@table @code -@item %n -CRLF -@item %r -raison -@item %s -objet du courriel de départ -@item %t -destinataire -@end table -La valeur par défaut est @samp{"Your message to <%t> 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 -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 {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 -Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This -makes Thunderbird realize they aren't selectable and show them greyed out, -instead of only later giving "not selectable" popup error. -@end table -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 - - -Whew! Lots of configuration options. The nice thing about it though is that -Guix has a complete interface to Dovecot's configuration language. This -allows not only a nice way to declare configurations, but also offers -reflective capabilities as well: users can write code to inspect and -transform configurations from within Scheme. - -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}). - -@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 -Set logging options. Advanced logging configuration is not yet supported by -the Guix Prosody Service. See @url{https://prosody.im/doc/logging}. -Defaults to @samp{"*syslog"}. -@end deftypevr - -@deftypevr {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 -If @samp{#t}, this will only allow admins to create new chatrooms. -Otherwise anyone can create a room. The value @samp{"local"} restricts room -creation to users on the service's parent domain. E.g.@: -@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The -value @samp{"admin"} restricts to service administrators only. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {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 Quassel Service - -@cindex IRC (Internet Relay Chat) -@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning -that one or more clients can attach to and detach from the central core. - -@defvr {Scheme Variable} quassel-service-type -This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC -backend daemon. Its value is a @code{quassel-configuration} (see below). -@end defvr - -@deftp {Data Type} quassel-configuration -This is the configuration for Quassel, with the following fields: - -@table @asis -@item @code{quassel} (default: @code{quassel}) -The Quassel package to use. - -@item @code{interface} (default: @code{"::,0.0.0.0"}) -@item @code{port} (default: @code{4242}) -Listen on the network interface(s) corresponding to the IPv4 or IPv6 -interfaces specified in the comma delimited @var{interface}, on @var{port}. - -@item @code{loglevel} (default: @code{"Info"}) -The level of logging desired. Accepted values are Debug, Info, Warning and -Error. -@end table -@end deftp - -@node 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 - "Welcome to this Mumble server running on Guix!") - (cert-required? #t) ;disallow text password logins - (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") - (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) -@end example - -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 <chaîne> » 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{<murmur-public-registration-configuration>} 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 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. - -La valeur par défaut est @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 - -La valeur par défaut est @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. - -La valeur par défaut est @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. - -La valeur par défaut est @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 - -La valeur par défaut est @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. - -La valeur par défaut est @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. - -La valeur par défaut est @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 -Configuration Nginx. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host -Database host name. - -La valeur par défaut est @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. - -La valeur par défaut est @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. - -La valeur par défaut est @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host -Zabbix server hostname. - -La valeur par défaut est @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 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 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 "\ -<FilesMatch \\.php$> - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -</FilesMatch>")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (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{<nginx-configuration>}. - -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{<nginx-server-configuration>}. - -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{<nginx-upstream-configuration>}. - -Configurer les serveurs amont à travers les @code{upstream-blocks} peut être -utile en combinaison avec @code{locations} dans les enregistrements -@code{<nginx-server-configuration>}. 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} -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 {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. - -Pass the @code{-n} argument to other Varnish programs to connect to the -named instance, e.g.@: @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 -Data type representing the configuration of the @code{fcgiwrap} service. -This type has the following parameters: -@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 -...@: and much more. - -@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{<php-fpm-dynamic-process-manager-configuration>,} -@item @code{<php-fpm-static-process-manager-configuration> ou} -@item @code{<php-fpm-on-demand-process-manager-configuration>} -@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} (default @code{#f}) -Specifies @code{php_admin_value[date.timezone]} parameter. -@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 {Scheme Procedure} 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. - -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 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{<mail>@@<origin>}. - -@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{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 -Pour 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 -Pour 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 <hostname>"}. - -@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" "ppc")))) -@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{<git-daemon-configuration>}, 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 -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). - -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 - -Le module @code{(gnu services fingerprint)} fournit un service DBus pour -lire et identifier les empreintes digitales via un lecteur d'empreinte. - -@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 - -@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{<dicod-configuration>}, 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{<dicod-handler>} qui définissent des gestionnaires -(des instances de modules). - -@item @code{databases} (par défaut : @var{(list %dicod-database:gcide)}) -Liste d'objets @code{<dicod-database>} 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{<dicod-handler>} -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{<dicod-database>} 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 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 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} -In Guix, this is done by adding a package that provides certificates to the -@code{packages} field of the @code{operating-system} declaration -(@pxref{Référence de système d'exploitation}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -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. - -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{Services réseau, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Services de bureaux}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@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{<name-service>} (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 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} -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 '()] @ -[#: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 @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 '()] [#: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}. - -@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. - -@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. -Pour l'instant seul GRUB supporte les thèmes. On crée un thème GRUB avec la -forme @code{grub-theme}, qui n'est pas encore documentée. - -@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 -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}). - -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 <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. -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 deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Invoquer guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Invoquer 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 -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 -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 - -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} -Build a virtual machine that contains the operating system declared in -@var{file}, and return a script to run that virtual machine (VM). - -@quotation Remarque -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{Réglages de l'environnement de construction}). -@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 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}. - -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. - -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 < guixsd-docker-image.tar.gz)" -docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ - --entrypoint /var/guix/profiles/system/profile/bin/guile \\ - $image_id /var/guix/profiles/system/boot -@end example - -This command starts a new Docker container from the specified image. It -will boot the Guix system in the usual manner, which means it will start any -services you have defined in the operating system configuration. Depending -on what you run in the Docker container, it may be necessary to give the -container additional permissions. For example, if you intend to build -software using Guix inside of the Docker container, you may need to pass the -@option{--privileged} option to @code{docker run}. - -@item 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} -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{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 on-error strategy -@cindex error strategy -@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 - -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 -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 Running Guix in a VM -@section Running Guix in a Virtual Machine - -@cindex machine virtuelle -To run Guix in a virtual machine (VM), one can either use the pre-built Guix -VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Invoquer guix system}). The returned image is in qcow2 -format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently -use. - -@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 -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{Services réseau, -@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{Services de bureaux, -@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{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 -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 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 - -Dans cet exemple, @var{guix-service-type} étend trois services : - -@table @var -@item shepherd-root-service-type -La procédure @var{guix-shepherd-service} définit comment le service du -Shepherd est étendu. En fait, elle renvoie un objet -@code{<shepherd-service>} qui définit comment @command{guix-daemon} est -démarré et stoppé (@pxref{Services Shepherd}). - -@item account-service-type -Cette extension pour ce service est calculée par @var{guix-accounts}, qui -renvoie une liste d'objets @code{user-group} et @code{user-account} -représentant les comptes des utilisateurs de construction (@pxref{Invoquer guix-daemon}). - -@item activation-service-type -Ici, @var{guix-activation} est une procédure qui renvoie une gexp, qui est -un bout de code qui s'exécute au moment de l'activation — p.@: ex.@: lorsque -le service est démarré. -@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 - -@var{guix-service-type} est très simple car il étend d'autres services mais -ne peut pas être étendu. - -@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-configuration> udev initial-rules) - (udev-configuration - (udev udev) ; le paquet udev à utiliser - (rules (append initial-rules rules))))))))) -@end example - -C'est le type de service pour le -@uref{https://wiki.gentoo.org/wiki/Project:Eudev, le démon de gestion des -périphériques eudev}. Comparé à l'exemple précédent, en plus d'une -extension de @var{shepherd-root-service-type}, on trouve deux nouveaux -champs : - -@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{<udev-configuration>}. -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 - -Il ne peut y avoir qu'une instance d'un type de service extensible comme -@var{udev-service-type}. S'il y en avait plus, les spécification -@code{service-extension} seraient ambiguës. - -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{<service-type>} (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{<service-type>}. -@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 - -La forme @code{modify-services} fournit une manière pratique de modifier les -paramètres de certains services d'une liste comme @var{%base-services} -(@pxref{Services de base, @code{%base-services}}). Elle s'évalue en une liste -de services. Bien sûr, vous pouvez toujours utiliser les combinateurs de -liste standards comme @code{map} et @code{fold} pour cela (@pxref{SRFI-1, -List Library,, guile, GNU Guile Reference Manual}) ; @code{modify-services} -fournit simplement une manière plus concise pour ce besoin commun. - -@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{<service-extension>} (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 -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}). - -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}}). - -La variable @var{%shepherd-root-service} est un objet de service -représentant le PID@tie{}1, de type @var{shepherd-root-service-type} ; il -peut être étendu en lui passant des listes d'objets -@code{<shepherd-service>}. - -@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 - -où @var{service-name} est l'un des symboles dans @var{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (par défaut : @var{%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{<shepherd-service>}. -@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 -Par exemple, supposons qu'une mise à jour de sécurité doive être appliquée à -Bash. Les développeurs de Guix fourniront une définition de paquet pour le -Bash « corrigé », disons @var{bash-fixed}, de la manière habituelle -(@pxref{Définition des paquets}). Ensuite, la définition originale du paquet est -augmentée avec un champ @code{replacement} qui pointe vers le paquet -contenant le correctif de sécurité : - -@example -(define bash - (package - (name "bash") - ;; @dots{} - (replacement bash-fixed))) -@end example - -À partir de maintenant, tout paquet dépendant directement ou indirectement -de Bash — rapporté par @command{guix gc --requisites} (@pxref{Invoquer guix gc}) — installé est automatiquement « réécrit » pour se référer à -@var{bash-fixed} au lieu de @var{bash}. Ce processus de greffe prend du -temps en proportion de la taille du paquet, typiquement moins d'une minute -pour un paquet de taille « moyenne » sur une machine récente. La greffe est -récursive : lorsqu'une dépendance indirecte a besoin d'être greffée, la -greffe se « propage » jusqu'au paquet que l'utilisateur installe. - -Actuellement la longueur du nom et la version de la greffe et du paquet -qu'il remplace (@var{bash-fixed} et @var{bash} dans l'exemple ci-dessus) -doivent être identiques. Cette restriction vient surtout du fait que la -greffe fonctionne en corrigeant les fichiers, dont des fichiers binaires, -directement. D'autres restrictions peuvent apparaître : par exemple, si -vous ajoutez une greffe à un paquet fournissant une bibliothèque partagée, -la bibliothèque partagée originale et son remplacement doivent avoir le même -@code{SONAME} et être compatibles au niveau binaire. - -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{} 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 - -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 <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. -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.texi b/doc/guix.texi index 3afdccac75..9553a373e8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -13,8 +13,12 @@ @set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 @set KEY-SERVER pool.sks-keyservers.net +@c Base URL for downloads. +@set BASE-URL https://ftp.gnu.org/gnu/guix + @c The official substitute server used by default. @set SUBSTITUTE-SERVER ci.guix.info +@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER} @copying Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@* @@ -108,10 +112,11 @@ 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 +This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN, +GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU +Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), and +Spanish (@pxref{Top,,, guix.es, Manual de referencia de 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}. @@ -251,6 +256,7 @@ System Configuration * 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. @@ -513,13 +519,22 @@ 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. +@c Note duplicated from the ``Installation'' node. +@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}. The script automates the download, installation, and +initial configuration steps described below. It should be run as the root +user. +@end quotation + 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}, +@indicateurl{@value{BASE-URL}/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. @@ -528,7 +543,7 @@ 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 +$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig @end example @@ -675,15 +690,9 @@ You can confirm that Guix is working by installing a sample package into the root profile: @example -# guix package -i hello +# guix install 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: @@ -1569,7 +1578,7 @@ available with Guix and then define the @code{GUIX_LOCPATH} environment variable: @example -$ guix package -i glibc-locales +$ guix install glibc-locales $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale @end example @@ -1669,7 +1678,7 @@ Multiple Outputs}). For instance, the following command installs fonts for Chinese languages: @example -guix package -i font-adobe-source-han-sans:cn +guix install font-adobe-source-han-sans:cn @end example @cindex @code{xterm} @@ -1794,26 +1803,15 @@ available. @node Limitations @section Limitations -As of version @value{VERSION}, Guix System is -not production-ready. It may contain bugs and lack important -features. Thus, if you are looking for a stable production system that -respects your freedom as a computer user, a good solution at this point -is to consider @url{http://www.gnu.org/distros/free-distros.html, one of -the more established GNU/Linux distributions}. We hope you can soon switch -to the Guix System without fear, of course. In the meantime, you can -also keep using your distribution and try out the package manager on top -of it (@pxref{Installation}). +We consider Guix System to be ready for a wide range of ``desktop'' and server +use cases. The reliability guarantees it provides---transactional upgrades +and rollbacks, reproducibility---make it a solid foundation. -Before you proceed with the installation, be aware of the following -noteworthy limitations applicable to version @value{VERSION}: +Nevertheless, before you proceed with the installation, be aware of the +following noteworthy limitations applicable to version @value{VERSION}: @itemize @item -The installation process does not include a graphical user interface and -requires familiarity with GNU/Linux (see the following subsections to -get a feel of what that means.) - -@item Support for the Logical Volume Manager (LVM) is missing. @item @@ -1821,18 +1819,14 @@ More and more system services are provided (@pxref{Services}), but some may be missing. @item -More than 8,500 packages are available, but you might -occasionally find that a useful package is missing. - -@item GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, some graphical -applications may be missing, as well as KDE. +as well as a number of X11 window managers. However, KDE is currently +missing. @end itemize -You have been warned! But more than a disclaimer, this is an invitation -to report issues (and success stories!), and to join us in improving it. -@xref{Contributing}, for more info. +More than a disclaimer, this is an invitation to report issues (and success +stories!), and to join us in improving it. @xref{Contributing}, for more +info. @node Hardware Considerations @@ -1855,7 +1849,7 @@ devices. WiFi devices known to work include those using Atheros chips driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. Free firmware exists for both and is available -out-of-the-box on Guix System, as part of @var{%base-firmware} +out-of-the-box on Guix System, as part of @code{%base-firmware} (@pxref{operating-system Reference, @code{firmware}}). @cindex RYF, Respects Your Freedom @@ -1875,7 +1869,7 @@ about their support in GNU/Linux. 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}, +@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, where @var{system} is one of: @table @code @@ -1891,7 +1885,7 @@ 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 +$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig $ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig @end example @@ -2499,7 +2493,7 @@ emacs-guix, The Emacs-Guix Reference Manual}), after installing with it): @example -guix package -i emacs-guix +guix install emacs-guix @end example @menu @@ -2617,6 +2611,7 @@ 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 @@ -2630,6 +2625,24 @@ For example, to remove @code{lua} and install @code{guile} and guix package -r lua -i guile guile-cairo @end example +@cindex aliases, for @command{guix package} +For your convenience, we also provide the following aliases: + +@itemize +@item +@command{guix search} is an alias for @command{guix package -s}, +@item +@command{guix install} is an alias for @command{guix package -i}, +@item +@command{guix remove} is an alias for @command{guix package -r}, +@item +and @command{guix upgrade} is an alias for @command{guix package -u}. +@end itemize + +These aliases are less expressive than @command{guix package} and provide +fewer options, so in some cases you'll probably want to use @command{guix +package} directly. + @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 @@ -2642,7 +2655,7 @@ 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 +If you are not using Guix System, 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: @@ -2942,12 +2955,13 @@ 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: +It is also possible to refine search results using several @code{-s} flags to +@command{guix package}, or several arguments to @command{guix search}. For +example, the following command returns a list of board games (this time using +the @command{guix search} alias): @example -$ guix package -s '\<board\>' -s game | recsel -p name +$ guix search '\<board\>' game | recsel -p name name: gnubg @dots{} @end example @@ -2962,7 +2976,7 @@ 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 | \ +$ guix search crypto library | \ recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis @end example @@ -3129,7 +3143,7 @@ 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, +using Guix System (@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 @@ -3319,7 +3333,7 @@ like to discuss this project, join us on @email{guix-devel@@gnu.org}. 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 +@command{guix install 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 @@ -3335,14 +3349,14 @@ 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 +guix install glib @end example @cindex documentation The command to install its documentation is: @example -guix package -i glib:doc +guix install glib:doc @end example Some packages install programs with different ``dependency footprints''. @@ -3384,7 +3398,7 @@ 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}). +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 @@ -3437,8 +3451,22 @@ 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 +@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. @@ -3450,6 +3478,10 @@ 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. @@ -3620,7 +3652,7 @@ Generation 3 Jun 13 2018 23:31:07 (current) 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} @end example -@ref{Invoking guix describe, @command{guix describe}}, for other ways to +@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 @@ -3642,8 +3674,9 @@ but it supports the following options: @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} -Download code from the specified @var{url}, at the given @var{commit} (a valid -Git commit ID represented as a hexadecimal string), or @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 @@ -3658,6 +3691,14 @@ Read the list of channels from @var{file} instead of 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} @@ -3665,7 +3706,7 @@ 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}). -@ref{Invoking guix describe}, for a way to display information about the +@xref{Invoking guix describe}, for a way to display information about the current generation only. @item --profile=@var{profile} @@ -4556,9 +4597,11 @@ 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, but has root privileges in -the context of the container. +@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 @@ -4586,8 +4629,9 @@ the environment. @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/USER}; and no user GECOS data will be copied. @var{user} +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 @@ -4963,7 +5007,7 @@ module exports a variable named @code{emacs}, which is bound to a 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 +instance, when running @code{guix install 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. @@ -5360,10 +5404,6 @@ 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{self-native-input?} (default: @code{#f}) -This is a Boolean field telling whether the package should use itself as -a native input when cross-compiling. - @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. @@ -5406,6 +5446,27 @@ 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 @@ -5816,6 +5877,11 @@ list of flags passed to the @code{dune} command during the build. The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} command instead of the more recent @code{dune} command while building a package. Its default value is @code{#f}. + +The @code{#:package} parameter can be passed to specify a package name, which +is useful when a package contains multiple packages and you want to build +only one of them. This is equivalent to passing the @code{-p} argument to +@code{dune}. @end defvr @defvr {Scheme Variable} go-build-system @@ -6187,6 +6253,33 @@ 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, @@ -7973,7 +8066,9 @@ The following derivations will be built: @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 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 @@ -10016,14 +10111,14 @@ 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.info -c 10 +$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10 computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.info... -updating substitutes from 'https://ci.guix.info'... 100.0% -https://ci.guix.info +looking for 9,343 store items on @value{SUBSTITUTE-URL}... +updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0% +@value{SUBSTITUTE-URL} 64.7% substitutes available (6,047 out of 9,343) @dots{} -2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which: +2502 packages are missing from '@value{SUBSTITUTE-URL}' 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 @@ -10100,7 +10195,7 @@ ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} @chapter System Configuration @cindex system configuration -The Guix System Distribution supports a consistent whole-system configuration +Guix System 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 @@ -10127,6 +10222,7 @@ instance to support new system services. * 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. @@ -10393,13 +10489,35 @@ 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{'()}) +@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{<keyboard-layout>} 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 @@ -10506,6 +10624,13 @@ 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 @@ -10527,6 +10652,27 @@ 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 @@ -10610,10 +10756,15 @@ corresponding device mapping established. 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.) +bits), @code{no-atime} (do not update file access times), and @code{no-exec} +(disallow program execution). @xref{Mount-Unmount-Remount,,, libc, The GNU C +Library Reference Manual}, for more information on these flags. @item @code{options} (default: @code{#f}) -This is either @code{#f}, or a string denoting mount options. +This is either @code{#f}, or a string denoting mount options passed to the +file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C Library +Reference Manual}, for details and run @command{man 8 mount} for options for +various file systems. @item @code{mount?} (default: @code{#t}) This value indicates whether to automatically mount the file system when @@ -10902,7 +11053,6 @@ this field must contain the encrypted password, as a string. You can use the @example (user-account (name "charlie") - (home-directory "/home/charlie") (group "users") ;; Specify a SHA-512-hashed initial password. @@ -10969,6 +11119,138 @@ 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 @@ -11861,29 +12143,6 @@ This is the name of the file where some random bytes are saved by It defaults to @file{/var/lib/random-seed}. @end defvr -@cindex keymap -@cindex keyboard -@deffn {Scheme Procedure} console-keymap-service @var{files} ... -@cindex keyboard layout -Return a service to load console keymaps from @var{files} using -@command{loadkeys} command. Most likely, you want to load some default -keymap, which can be done like this: - -@example -(console-keymap-service "dvorak") -@end example - -Or, for example, for a Swedish keyboard, you may need to combine -the following keymaps: -@example -(console-keymap-service "se-lat6" "se-fi-lat6") -@end example - -Also you can specify a full file name (or file names) of your keymap(s). -See @code{man loadkeys} for details. - -@end deffn - @cindex mouse @cindex gpm @defvr {Scheme Variable} gpm-service-type @@ -13161,7 +13420,13 @@ Package object of the Open vSwitch. Support for the X Window graphical display system---specifically Xorg---is provided by the @code{(gnu services xorg)} module. Note that there is no @code{xorg-service} procedure. Instead, the X server is -started by the @dfn{login manager}, by default SLiM. +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 @@ -13169,23 +13434,59 @@ 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} slim-service-type -This is the type for the SLiM graphical login manager for X11. +@defvr {Scheme Variable} gdm-service-type +This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME +Desktop Manager} (GDM), a program that manages graphical display servers and +handles graphical user logins. Its value must be a @code{gdm-configuration} +(see below.) @cindex session types (X11) @cindex X11 session types -SLiM looks for @dfn{session types} described by the @file{.desktop} files in -@file{/run/current-system/profile/share/xsessions} and allows users to -choose a session from the log-in screen using @kbd{F1}. Packages such -as @code{xfce}, @code{sawfish}, and @code{ratpoison} provide -@file{.desktop} files; adding them to the system-wide set of packages -automatically makes them available at the log-in screen. +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}. @@ -13218,8 +13519,8 @@ your user profile. Failing to do that, if @code{auto-login-session} is false, you will be unable to log in. @end quotation -@item @code{startx} (default: @code{(xorg-start-command)}) -The command used to start the X11 graphical server. +@item @code{xorg-configuration} (default @code{(xorg-configuration)}) +Configuration of the Xorg graphical server. @item @code{xauth} (default: @code{xauth}) The XAuth package to use. @@ -13295,8 +13596,8 @@ Script to run before starting a wayland session. @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions") Directory to look for desktop files starting wayland sessions. -@item @code{xorg-server-path} (default @code{xorg-start-command}) -Path to xorg-server. +@item @code{xorg-configuration} (default @code{(xorg-configuration)}) +Configuration of the Xorg graphical server. @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")}) Path to xauth. @@ -13319,9 +13620,6 @@ Directory to look for desktop files starting X sessions. @item @code{minimum-vt} (default: 7) Minimum VT to use. -@item @code{xserver-arguments} (default "-nolisten tcp") -Arguments to pass to xorg-server. - @item @code{auto-login-user} (default "") User to use for auto-login. @@ -13347,99 +13645,73 @@ type @code{<sddm-configuration>}. @end example @end deffn -@deffn {Scheme Procedure} xorg-start-command [#:guile] @ - [#:modules %default-xorg-modules] @ - [#:fonts %default-xorg-fonts] @ - [#:configuration-file (xorg-configuration-file @dots{})] @ - [#:xorg-server @var{xorg-server}] - [#:xserver-arguments '("-nolisten" "tcp")] -Return a @code{startx} script in which @var{modules}, a list of X module -packages, and @var{fonts}, a list of X font directories, are available. See -@code{xorg-wrapper} for more details on the arguments. The result should be -used in place of @code{startx}. +@cindex Xorg, 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. -Usually the X server is started by a login manager. -@end deffn +@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. -@cindex @code{-listen tcp}, for X11. -This procedure is useful to override command line options for the X server, -such as having it listen to over TCP: +@item @code{fonts} (default: @code{%default-xorg-fonts}) +This is a list of font directories to add to the server's @dfn{font path}. -@example -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:xserver-arguments '("-listen" "tcp")))))))) -@end example - -@deffn {Scheme Procedure} xorg-configuration-file @ - [#:modules %default-xorg-modules] @ - [#:fonts %default-xorg-fonts] @ - [#:drivers '()] [#:resolutions '()] [#:extra-config '()] -Return a configuration file for the Xorg server containing search paths for -all the common drivers. - -@var{modules} must be a list of @dfn{module packages} loaded by the Xorg -server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. -@var{fonts} must be a list of font directories to add to the server's -@dfn{font path}. +@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")}. -@var{drivers} must be either the empty list, in which case Xorg chooses a -graphics driver automatically, or a list of driver names that will be tried in -this order---e.g., @code{("modesetting" "vesa")}. +@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))}. -Likewise, when @var{resolutions} is the empty list, Xorg chooses an -appropriate screen resolution; otherwise, it must be a list of -resolutions---e.g., @code{((1024 768) (640 480))}. +@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. -Last, @var{extra-config} is a list of strings or objects appended to the -configuration file. It is used to pass extra text to be -added verbatim to the configuration file. +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. -@cindex keymap -@cindex keyboard layout -This procedure is especially useful to configure a different keyboard layout -than the default US keymap. For instance, to use the ``bépo'' keymap by -default on the display manager: +@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. -@example -(define bepo-evdev - "Section \"InputClass\" - Identifier \"evdev keyboard catchall\" - Driver \"evdev\" - MatchIsKeyboard \"on\" - Option \"xkb_layout\" \"fr\" - Option \"xkb_variant\" \"bepo\" -EndSection") +@item @code{server} (default: @code{xorg-server}) +This is the package providing the Xorg server. -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:configuration-file - (xorg-configuration-file - #:extra-config - (list bepo-evdev))))))))) -@end example - -The @code{MatchIsKeyboard} line specifies that we only apply the configuration -to keyboards. Without this line, other devices such as touchpad may not work -correctly because they will be attached to the wrong driver. In this example, -the user typically used @code{setxkbmap fr bepo} to set their favorite keymap -once logged in. The first argument corresponds to the layout, while the second -argument corresponds to the variant. The @code{xkb_variant} line can be omitted -to select the default variant. +@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 <xorg-configuration> 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 @@ -14301,7 +14573,7 @@ The @code{(gnu services desktop)} module provides services that are usually useful in the context of a ``desktop'' setup---that is, on a machine running a graphical display server, possibly with graphical user interfaces, etc. It also defines services that provide specific desktop -environments like GNOME, XFCE or MATE. +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 @@ -14312,7 +14584,7 @@ This is a list of services that builds upon @var{%base-services} and adds or adjusts services for a typical ``desktop'' setup. In particular, it adds a graphical login manager (@pxref{X Window, -@code{slim-service}}), screen lockers, a network management tool +@code{gdm-service-type}}), screen lockers, a network management tool (@pxref{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 @@ -14326,16 +14598,16 @@ 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}, +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 +@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To ``add GNOME'' means that system-level services like the backlight adjustment helpers and the power management utilities are added to the system, extending @code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with elevated privileges on a limited number of special-purpose system interfaces. Additionally, -adding a service made by @code{gnome-desktop-service} adds the GNOME -metapackage to the system profile. Likewise, adding the XFCE service +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 @@ -14351,25 +14623,50 @@ functionality to work as expetected. The desktop environments in Guix use the Xorg display server by default. If you'd like to use the newer display server protocol -called Wayland, you need to use the @code{sddm-service} instead of the -@code{slim-service} for the graphical login manager. You should then +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. -@deffn {Scheme Procedure} gnome-desktop-service -Return a service that adds the @code{gnome} package to the system -profile, and extends polkit with the actions from -@code{gnome-settings-daemon}. -@end deffn +@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.) -@deffn {Scheme Procedure} xfce-desktop-service -Return a service that adds the @code{xfce} package to the system profile, -and extends polkit with the ability for @code{thunar} to manipulate the -file system as root from within a user session, after the user has -authenticated with the administrator's password. -@end deffn +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/, @@ -14402,9 +14699,9 @@ The enlightenment package to use. @end table @end deftp -Because the GNOME, XFCE and MATE desktop services pull in so many packages, +Because the GNOME, Xfce and MATE desktop services pull in so many packages, the default @code{%desktop-services} variable doesn't include any of -them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto +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}: @@ -14414,8 +14711,8 @@ them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto (operating-system ... ;; cons* adds items to the list given as its last argument. - (services (cons* (gnome-desktop-service) - (xfce-desktop-service) + (services (cons* (service gnome-desktop-service-type) + (service xfce-desktop-service) %desktop-services)) ...) @end example @@ -16382,6 +16679,36 @@ the @code{operating-system}'s @code{user-accounts} in order to deliver the @code{postmaster} mail to @code{bob} (which subsequently would deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). +@subsubheading GNU Mailutils IMAP4 Daemon +@cindex GNU Mailutils IMAP4 Daemon + +@deffn {Scheme Variable} imap4d-service-type +This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, +mailutils, GNU Mailutils Manual}), whose value should be an +@code{imap4d-configuration} object as in this example: + +@example +(service imap4d-service-type + (imap4d-configuration + (config-file (local-file "imap4d.conf")))) +@end example +@end deffn + +@deftp {Data Type} imap4d-configuration +Data type representing the configuration of @command{imap4d}. + +@table @asis +@item @code{package} (default: @code{mailutils}) +The package that provides @command{imap4d}. + +@item @code{config-file} (default: @code{%default-imap4d-config-file}) +File-like object of the configuration file to use, by default it will listen +on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU +Mailutils Manual}, for details. + +@end table +@end deftp + @node Messaging Services @subsection Messaging Services @@ -19130,6 +19457,26 @@ Its default is the first provided domain. 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{challenge} (default: @code{#f}) +The challenge type that has to be run by certbot. If @code{#f} is specified, +default to the HTTP challenge. If a value is specified, defaults to the +manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and +the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}). + +@item @code{authentication-hook} (default: @code{#f}) +Command to be run in a shell once for each certificate challenge to be +answered. For this command, the shell variable @code{$CERTBOT_DOMAIN} +will contain the domain being authenticated, @code{$CERTBOT_VALIDATION} +contains the validation string and @code{$CERTBOT_TOKEN} contains the +file name of the resource requested when performing an HTTP-01 challenge. + +@item @code{cleanup-hook} (default: @code{#f}) +Command to be run in a shell once for each certificate challenge that +have been answered by the @code{auth-hook}. For this command, the shell +variables available in the @code{auth-hook} script are still available, and +additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output +of the @code{auth-hook} script. + @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 @@ -19511,6 +19858,45 @@ When set, this forbids queries of the ANY type. The delay between a modification in memory and on disk. 0 means immediate synchronization. +@item @code{zonefile-load} (default: @code{#f}) +The way the zone file contents are applied during zone load. Possible values +are: + +@itemize +@item @code{#f} for using the default value from Knot, +@item @code{'none} for not using the zone file at all, +@item @code{'difference} for computing the difference between already available +contents and zone contents and applying it to the current zone contents, +@item @code{'difference-no-serial} for the same as @code{'difference}, but +ignoring the SOA serial in the zone file, while the server takes care of it +automatically. +@item @code{'whole} for loading zone contents from the zone file. +@end itemize + +@item @code{journal-content} (default: @code{#f}) +The way the journal is used to store zone and its changes. Possible values +are @code{'none} to not use it at all, @code{'changes} to store changes and +@code{'all} to store contents. @code{#f} does not set this option, so the +default value from Knot is used. + +@item @code{max-journal-usage} (default: @code{#f}) +The maximum size for the journal on disk. @code{#f} does not set this option, +so the default value from Knot is used. + +@item @code{max-journal-depth} (default: @code{#f}) +The maximum size of the history. @code{#f} does not set this option, so the +default value from Knot is used. + +@item @code{max-zone-size} (default: @code{#f}) +The maximum size of the zone file. This limit is enforced for incoming +transfer and updates. @code{#f} does not set this option, so the default +value from Knot is used. + +@item @code{dnssec-policy} (default: @code{#f}) +A reference to a @code{knot-policy-configuration} record, or the special +name @code{"default"}. If the value is @code{#f}, there is no dnssec signing +on this zone. + @item @code{serial-policy} (default: @code{'increment}) A policy between @code{'increment} and @code{'unixtime}. @@ -19528,6 +19914,19 @@ 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{includes} (default: @code{'()}) +A list of strings or file-like objects denoting other files that must be +included at the top of the configuration file. + +@cindex secrets, Knot service +This can be used to manage secrets out-of-band. For example, secret +keys may be stored in an out-of-band file not managed by Guix, and +thus not visible in @file{/gnu/store}---e.g., you could store secret +key configuration in @file{/etc/knot/secrets.conf} and add this file +to the @code{includes} list. + +It can also be used to add configuration not supported by this interface. + @item @code{listen-v4} (default: @code{"0.0.0.0"}) An ip address on which to listen. @@ -21624,7 +22023,7 @@ emulated: @example (service qemu-binfmt-service-type (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc")))) + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")))) @end example In this example, we enable transparent emulation for the ARM and aarch64 @@ -22915,7 +23314,7 @@ The port to bind the server to. @cindex fingerprint @subsubheading Fingerprint Service -The @code{(gnu services fingerprint)} module provides a DBus service to +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 @@ -23261,7 +23660,7 @@ pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you would typically run something like: @example -$ guix package -i nss-certs +$ guix install 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" @@ -23272,7 +23671,7 @@ variable to point to a certificate bundle, so you would have to run something like this: @example -$ guix package -i nss-certs +$ guix install nss-certs $ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" @end example @@ -23528,6 +23927,7 @@ here is how to use it and customize it further. @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 @@ -23539,6 +23939,12 @@ the root file system specified on the kernel command line via @code{--root}. 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{<keyboard-layout>} 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. @@ -23548,7 +23954,8 @@ to it are lost. @end deffn @deffn {Scheme Procedure} base-initrd @var{file-systems} @ - [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@ + [#: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 @@ -23556,6 +23963,12 @@ 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{<keyboard-layout>} 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 @@ -23649,6 +24062,19 @@ current system. 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 @@ -23749,7 +24175,7 @@ must @emph{not} be an OS device name such as @file{/dev/sda1}. @end deftp @c FIXME: Write documentation once it's stable. -Fow now only GRUB has theme support. GRUB themes are created using +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 @@ -24221,13 +24647,23 @@ example graph. @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. +To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image +distributed at +@indicateurl{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.@var{system}.xz} +This image is a compressed image in QCOW format. You will first need to +decompress with @command{xz -d}, and then you can pass it to an emulator such +as QEMU (see below for details). + +This image boots the Xfce graphical environment and it contains some +commonly-used tools. You can install more software in the image by running +@command{guix package} in a terminal (@pxref{Invoking guix package}). You can +also reconfigure the system based on its initial configuration file available +as @file{/etc/config.scm} (@pxref{Using the Configuration System}). + +Instead of using this pre-built image, one can also 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 @@ -24240,7 +24676,9 @@ vm-image} on x86_64 hardware: @example $ qemu-system-x86_64 \ -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image + -enable-kvm -m 512 \ + -device virtio-blk,drive=myhd \ + -drive if=none,file=/tmp/qemu-image,id=myhd @end example Here is what each of these options means: @@ -24266,12 +24704,20 @@ 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 +@c To run Xfce + 'guix pull', we need at least 1G of RAM. +@item -m 1024 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. +@item -device virtio-blk,drive=myhd +Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a +``paravirtualization'' mechanism for block devices that allows QEMU to achieve +better performance than if it were emulating a complete disk drive. See the +QEMU and KVM documentation for more info. + +@item -drive if=none,file=/tmp/qemu-image,id=myhd +Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the +the ``myhd'' drive. @end table The default @command{run-vm.sh} script that is returned by an invocation of @@ -24287,11 +24733,10 @@ network connectivity, for example @command{guix download}. @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 +To enable SSH inside a VM you need to add an SSH server like +@code{openssh-service-type} to your VM (@pxref{Networking Services, +@code{openssh-service-type}}). 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 @@ -24435,23 +24880,23 @@ exception is the @dfn{boot service type}, which is the ultimate service. Optionally, a default value for instances of this type. @end enumerate -In this example, @var{guix-service-type} extends three services: +In this example, @code{guix-service-type} extends three services: -@table @var +@table @code @item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd +The @code{guix-shepherd-service} procedure defines how the Shepherd service is extended. Namely, it returns a @code{<shepherd-service>} object that defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd Services}). @item account-service-type -This extension for this service is computed by @var{guix-accounts}, +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 @var{guix-activation} is a procedure that returns a gexp, which is +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 @@ -24476,7 +24921,7 @@ value is omitted, the default value specified by (service guix-service-type) @end example -@var{guix-service-type} is quite simple because it extends other +@code{guix-service-type} is quite simple because it extends other services but is not extensible itself. @c @subsubsubsection Extensible Service Types @@ -24502,7 +24947,7 @@ The service type for an @emph{extensible} service looks like this: This is the service type for the @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management daemon}. Compared to the previous example, in addition to an -extension of @var{shepherd-root-service-type}, we see two new fields: +extension of @code{shepherd-root-service-type}, we see two new fields: @table @code @item compose @@ -24529,7 +24974,7 @@ them (@pxref{Invoking guix system}). @end table There can be only one instance of an extensible service type such as -@var{udev-service-type}. If there were more, the +@code{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 @@ -24603,7 +25048,7 @@ Here is an example of how a service is created and manipulated: The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as -@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It +@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}); @@ -24784,8 +25229,8 @@ You can actually generate such a graph for any operating system definition using the @command{guix system shepherd-graph} command (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). -The @var{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended +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{<shepherd-service>} objects. @deftp {Data Type} shepherd-service @@ -24803,6 +25248,12 @@ shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the @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. @@ -24833,10 +25284,10 @@ A documentation string, as shown when running: herd doc @var{service-name} @end example -where @var{service-name} is one of the symbols in @var{provision} +where @var{service-name} is one of the symbols in @code{provision} (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). -@item @code{modules} (default: @var{%default-modules}) +@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. @@ -25002,7 +25453,7 @@ installs the debugging information for the GNU C Library and for GNU Guile: @example -guix package -i glibc:debug guile:debug +guix install glibc:debug guile:debug @end example GDB must then be told to look for debug files in the user's profile, by @@ -25083,7 +25534,7 @@ order of magnitudes lower than a full rebuild of the dependency chain. @cindex replacements of packages, for grafts For instance, suppose a security update needs to be applied to Bash. Guix developers will provide a package definition for the ``fixed'' -Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining +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: @@ -25098,14 +25549,14 @@ Packages}). Then, the original package definition is augmented with a 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 -@var{bash-fixed} instead of @var{bash}. This grafting process takes +@code{bash-fixed} instead of @code{bash}. This grafting process takes time proportional to the size of the package, usually less than a minute for an ``average'' package on a recent machine. Grafting is recursive: when an indirect dependency requires grafting, then grafting ``propagates'' up to the package that the user is installing. Currently, the length of the name and version of the graft and that of -the package it replaces (@var{bash-fixed} and @var{bash} in the example +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 diff --git a/doc/local.mk b/doc/local.mk index 4ad19b5e37..204e1990a5 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -21,9 +21,11 @@ # You should have received a copy of the GNU General Public License # along with GNU Guix. If not, see <http://www.gnu.org/licenses/>. -info_TEXINFOS = %D%/guix.texi \ - %D%/guix.fr.texi \ - %D%/guix.de.texi +info_TEXINFOS = %D%/guix.texi \ + %D%/guix.es.texi \ + %D%/guix.fr.texi \ + %D%/guix.de.texi \ + %D%/guix.zh_CN.texi %C%_guix_TEXINFOS = \ %D%/contributing.texi \ @@ -55,11 +57,15 @@ OS_CONFIG_EXAMPLES_TEXI = \ %D%/os-config-desktop.texi \ %D%/os-config-lightweight-desktop.texi -TRANSLATED_INFO = \ - %D%/guix.de.texi \ - %D%/guix.fr.texi \ - %D%/contributing.de.texi \ - %D%/contributing.fr.texi +TRANSLATED_INFO = \ + %D%/guix.de.texi \ + %D%/guix.es.texi \ + %D%/guix.fr.texi \ + %D%/guix.zh_CN.texi \ + %D%/contributing.de.texi \ + %D%/contributing.es.texi \ + %D%/contributing.fr.texi \ + %D%/contributing.zh_CN.texi # Bundle this file so that makeinfo finds it in out-of-source-tree builds. BUILT_SOURCES += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO) |