diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 713 |
1 files changed, 381 insertions, 332 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 6d6a09b36b..55935b3794 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -48,7 +48,7 @@ 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, 2019 Maxim Cournoyer@* Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* @@ -1035,7 +1035,7 @@ build are copied back to the initial machine. The @file{/etc/guix/machines.scm} file typically looks like this: -@example +@lisp (list (build-machine (name "eightysix.example.org") (system "x86_64-linux") @@ -1051,7 +1051,7 @@ The @file{/etc/guix/machines.scm} file typically looks like this: (private-key (string-append (getenv "HOME") "/.ssh/identity-for-guix")))) -@end example +@end lisp @noindent In the example above we specify a list of two build machines, one for @@ -1724,8 +1724,8 @@ to make sure your TrueType fonts are listed there. After installing fonts you may have to refresh the font cache to use them in applications. The same applies when applications installed via Guix do not seem to find fonts. To force rebuilding of the font cache -run @code{fc-cache -f}. The @code{fc-cache} command is provided by the -@code{fontconfig} package. +run @code{fc-cache -rv}. The @code{fc-cache} command is provided by +the @code{fontconfig} package. @subsection X.509 Certificates @@ -2756,9 +2756,9 @@ Install the package that the code within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): -@example +@lisp @verbatiminclude package-hello.scm -@end example +@end lisp Developers may find it useful to include such a @file{guix.scm} file in the root of their project source tree that can be used to test @@ -2814,7 +2814,7 @@ so on. of packages: @findex packages->manifest -@example +@lisp (use-package-modules guile emacs) (packages->manifest @@ -2822,7 +2822,7 @@ of packages: guile-2.0 ;; Use a specific package output. (list guile-2.0 "debug"))) -@end example +@end lisp @findex specifications->manifest In this example we have to know which modules define the @code{emacs} @@ -2832,10 +2832,10 @@ instead provide regular package specifications and let @code{specifications->manifest} look up the corresponding package objects, like this: -@example +@lisp (specifications->manifest '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example +@end lisp @item --roll-back @cindex rolling back @@ -3496,6 +3496,10 @@ This prints nothing unless the daemon was started with List the GC roots owned by the user; when run as root, list @emph{all} the GC roots. +@item --list-busy +List store items in use by currently running processes. These store +items are effectively considered GC roots: they cannot be deleted. + @item --clear-failures Remove the specified store items from the failed-build cache. @@ -3620,7 +3624,7 @@ version. New @command{guix} sub-commands added by the update also become available. Any user can update their Guix copy using @command{guix pull}, and the -effect is limited to the user who run @command{guix pull}. For +effect is limited to the user who ran @command{guix pull}. For instance, when user @code{root} runs @command{guix pull}, this has no effect on the version of Guix that user @code{alice} sees, and vice versa. @@ -4548,9 +4552,9 @@ within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): -@example +@lisp @verbatiminclude environment-gdb.scm -@end example +@end lisp @item --manifest=@var{file} @itemx -m @var{file} @@ -5124,7 +5128,7 @@ The high-level interface to package definitions is implemented in the example, the package definition, or @dfn{recipe}, for the GNU Hello package looks like this: -@example +@lisp (define-module (gnu packages hello) #:use-module (guix packages) #:use-module (guix download) @@ -5150,7 +5154,7 @@ package looks like this: (description "Guess what GNU Hello prints!") (home-page "https://www.gnu.org/software/hello/") (license gpl3+))) -@end example +@end lisp @noindent Without being a Scheme expert, the reader may have guessed the meaning @@ -5331,7 +5335,7 @@ the name of a package and returns its new name after rewrite. @noindent Consider this example: -@example +@lisp (define libressl-instead-of-openssl ;; This is a procedure to replace OPENSSL by LIBRESSL, ;; recursively. @@ -5339,7 +5343,7 @@ Consider this example: (define git-with-libressl (libressl-instead-of-openssl git)) -@end example +@end lisp @noindent Here we first define a rewriting procedure that replaces @var{openssl} @@ -5361,11 +5365,11 @@ replacement for that package. The example above could be rewritten this way: -@example +@lisp (define libressl-instead-of-openssl ;; Replace all the packages called "openssl" with LibreSSL. (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example +@end lisp The key difference here is that, this time, packages are matched by spec and not by identity. In other words, any package in the graph that is called @@ -5431,11 +5435,11 @@ defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for more on package outputs). For example, the list below specifies three inputs: -@example +@lisp `(("libffi" ,libffi) ("libunistring" ,libunistring) ("glib:bin" ,glib "bin")) ;the "bin" output of Glib -@end example +@end lisp @cindex cross compilation, package dependencies The distinction between @code{native-inputs} and @code{inputs} is @@ -5516,7 +5520,7 @@ 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 +@lisp (package (name "guile") ;; ... @@ -5526,7 +5530,7 @@ cross-compiling: (native-inputs (if (%current-target-system) `(("self" ,this-package)) '()))) -@end example +@end lisp It is an error to refer to @code{this-package} outside a package definition. @end deffn @@ -5563,11 +5567,11 @@ clone the Git version control repository, and check out the revision specified in the @code{uri} field as a @code{git-reference} object; a @code{git-reference} looks like this: -@example +@lisp (git-reference (url "https://git.savannah.gnu.org/git/hello.git") (commit "v2.10")) -@end example +@end lisp @end table @item @code{sha256} @@ -6779,7 +6783,7 @@ in a monad---values that carry this additional context---are called Consider this ``normal'' procedure: -@example +@lisp (define (sh-symlink store) ;; Return a derivation that symlinks the 'bash' executable. (let* ((drv (package-derivation store bash)) @@ -6787,19 +6791,19 @@ Consider this ``normal'' procedure: (sh (string-append out "/bin/bash"))) (build-expression->derivation store "sh" `(symlink ,sh %output)))) -@end example +@end lisp Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten as a monadic function: -@example +@lisp (define (sh-symlink) ;; Same, but return a monadic value. (mlet %store-monad ((drv (package->derivation bash))) (gexp->derivation "sh" #~(symlink (string-append #$drv "/bin/bash") #$output)))) -@end example +@end lisp There are several things to note in the second version: the @code{store} parameter is now implicit and is ``threaded'' in the calls to the @@ -6811,12 +6815,12 @@ As it turns out, the call to @code{package->derivation} can even be omitted since it will take place implicitly, as we will see later (@pxref{G-Expressions}): -@example +@lisp (define (sh-symlink) (gexp->derivation "sh" #~(symlink (string-append #$bash "/bin/bash") #$output))) -@end example +@end lisp @c See @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> @@ -6826,10 +6830,10 @@ said, ``you exit a monad like you exit a building on fire: by running''. So, to exit the monad and get the desired effect, one must use @code{run-with-store}: -@example +@lisp (run-with-store (open-connection) (sh-symlink)) @result{} /gnu/store/...-sh-symlink -@end example +@end lisp Note that the @code{(guix monad-repl)} module extends the Guile REPL with new ``meta-commands'' to make it easier to deal with monadic procedures: @@ -6878,7 +6882,7 @@ Guile. Thus we use this somewhat cryptic symbol inherited from the Haskell language.}. There can be one @var{mproc} or several of them, as in this example: -@example +@lisp (run-with-state (with-monad %state-monad (>>= (return 1) @@ -6888,7 +6892,7 @@ in this example: @result{} 4 @result{} some-state -@end example +@end lisp @end deffn @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ @@ -6947,7 +6951,7 @@ Consider the example below. The @code{square} procedure returns a value in the state monad. It returns the square of its argument, but also increments the current state value: -@example +@lisp (define (square x) (mlet %state-monad ((count (current-state))) (mbegin %state-monad @@ -6957,7 +6961,7 @@ increments the current state value: (run-with-state (sequence %state-monad (map square (iota 3))) 0) @result{} (0 1 4) @result{} 3 -@end example +@end lisp When ``run'' through @var{%state-monad}, we obtain that additional state value, which is the number of @code{square} calls. @@ -7032,14 +7036,14 @@ entries for which @var{select?} does not return true. The example below adds a file to the store, under two different names: -@example +@lisp (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 lisp @end deffn @@ -7133,22 +7137,22 @@ below.) To illustrate the idea, here is an example of a gexp: -@example +@lisp (define build-exp #~(begin (mkdir #$output) (chdir #$output) (symlink (string-append #$coreutils "/bin/ls") "list-files"))) -@end example +@end lisp This gexp can be passed to @code{gexp->derivation}; we obtain a derivation that builds a directory containing exactly one symlink to @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: -@example +@lisp (gexp->derivation "the-thing" build-exp) -@end example +@end lisp As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is substituted to the reference to the @var{coreutils} package in the @@ -7164,7 +7168,7 @@ host---versus references to cross builds of a package. To that end, the @code{#+} plays the same role as @code{#$}, but is a reference to a native package build: -@example +@lisp (gexp->derivation "vi" #~(begin (mkdir #$output) @@ -7173,7 +7177,7 @@ native package build: (string-append #$emacs "/bin/emacs") (string-append #$output "/bin/vi"))) #:target "mips64el-linux-gnu") -@end example +@end lisp @noindent In the example above, the native build of @var{coreutils} is used, so @@ -7187,7 +7191,7 @@ able to use certain Guile modules from the ``host environment'' in the gexp, so those modules should be imported in the ``build environment''. The @code{with-imported-modules} form allows you to express that: -@example +@lisp (let ((build (with-imported-modules '((guix build utils)) #~(begin (use-modules (guix build utils)) @@ -7197,7 +7201,7 @@ The @code{with-imported-modules} form allows you to express that: #$build (display "success!\n") #t))) -@end example +@end lisp @noindent In this example, the @code{(guix build utils)} module is automatically @@ -7213,7 +7217,7 @@ because of missing dependent modules. The @code{source-module-closure} procedure computes the closure of a module by looking at its source file headers, which comes in handy in this case: -@example +@lisp (use-modules (guix modules)) ;for 'source-module-closure' (with-imported-modules (source-module-closure @@ -7224,7 +7228,7 @@ headers, which comes in handy in this case: (use-modules (guix build utils) (gnu build vm)) @dots{}))) -@end example +@end lisp @cindex extensions, for gexps @findex with-extensions @@ -7233,7 +7237,7 @@ modules, but also ``extensions'' such as Guile bindings to C libraries or other ``full-blown'' packages. Say you need the @code{guile-json} package available on the build side, here's how you would do it: -@example +@lisp (use-modules (gnu packages guile)) ;for 'guile-json' (with-extensions (list guile-json) @@ -7241,7 +7245,7 @@ package available on the build side, here's how you would do it: #~(begin (use-modules (json)) @dots{}))) -@end example +@end lisp The syntactic form to construct gexps is summarized below. @@ -7310,12 +7314,12 @@ Each item in @var{modules} can be the name of a module, such as @code{(guix build utils)}, or it can be a module name, followed by an arrow, followed by a file-like object: -@example +@lisp `((guix build utils) (guix gcrypt) ((guix config) => ,(scheme-file "config.scm" #~(define-module @dots{})))) -@end example +@end lisp @noindent In the example above, the first two modules are taken from the search @@ -7414,10 +7418,10 @@ The @code{local-file}, @code{plain-file}, @code{computed-file}, @dfn{file-like objects}. That is, when unquoted in a G-expression, these objects lead to a file in the store. Consider this G-expression: -@example +@lisp #~(system* #$(file-append glibc "/sbin/nscd") "-f" #$(local-file "/tmp/my-nscd.conf")) -@end example +@end lisp The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it to the store. Once expanded, for instance @i{via} @@ -7473,13 +7477,13 @@ Look up @var{exp}'s modules in @var{module-path}. The example below builds a script that simply invokes the @command{ls} command: -@example +@lisp (use-modules (guix gexp) (gnu packages base)) (gexp->script "list-files" #~(execl #$(file-append coreutils "/bin/ls") "ls")) -@end example +@end lisp When ``running'' it through the store (@pxref{The Store Monad, @code{run-with-store}}), we obtain a derivation that produces an @@ -7537,14 +7541,14 @@ to create will reference items from the store. This is typically the case when building a configuration file that embeds store file names, like this: -@example +@lisp (define (profile.sh) ;; Return the name of a shell script in the store that ;; initializes the 'PATH' environment variable. (text-file* "profile.sh" "export PATH=" coreutils "/bin:" grep "/bin:" sed "/bin\n")) -@end example +@end lisp In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby @@ -7556,10 +7560,10 @@ Return an object representing store file @var{name} containing @var{text}. @var{text} is a sequence of strings and file-like objects, as in: -@example +@lisp (mixed-text-file "profile" "export PATH=" coreutils "/bin:" grep "/bin") -@end example +@end lisp This is the declarative counterpart of @code{text-file*}. @end deffn @@ -7570,13 +7574,13 @@ Each item in @var{files} must be a two-element list where the first element is t file name to use in the new directory, and the second element is a gexp denoting the target file. Here's an example: -@example +@lisp (file-union "etc" `(("hosts" ,(plain-file "hosts" "127.0.0.1 localhost")) ("bashrc" ,(plain-file "bashrc" "alias ls='ls --color=auto'")))) -@end example +@end lisp This yields an @code{etc} directory containing these two files. @end deffn @@ -7585,9 +7589,9 @@ This yields an @code{etc} directory containing these two files. Return a directory that is the union of @var{things}, where @var{things} is a list of file-like objects denoting directories. For example: -@example +@lisp (directory-union "guile+emacs" (list guile emacs)) -@end example +@end lisp yields a directory that is the union of the @code{guile} and @code{emacs} packages. @end deffn @@ -7599,19 +7603,19 @@ and @var{suffix}, where @var{obj} is a lowerable object and each As an example, consider this gexp: -@example +@lisp (gexp->script "run-uname" #~(system* #$(file-append coreutils "/bin/uname"))) -@end example +@end lisp The same effect could be achieved with: -@example +@lisp (gexp->script "run-uname" #~(system* (string-append #$coreutils "/bin/uname"))) -@end example +@end lisp There is one difference though: in the @code{file-append} case, the resulting script contains the absolute file name as a string, whereas in @@ -8099,9 +8103,9 @@ Build the package, derivation, or other file-like object that the code within As an example, @var{file} might contain a package definition like this (@pxref{Defining Packages}): -@example +@lisp @verbatiminclude package-hello.scm -@end example +@end lisp @item --expression=@var{expr} @itemx -e @var{expr} @@ -8908,7 +8912,17 @@ in Guix. @item crate @cindex crate Import metadata from the crates.io Rust package repository -@uref{https://crates.io, crates.io}. +@uref{https://crates.io, crates.io}, as in this example: + +@example +guix import crate blake2-rfc +@end example + +The crate importer also allows you to specify a version string: + +@example +guix import crate constant-time-eq@@0.1.0 +@end example @item opam @cindex OPAM @@ -8974,13 +8988,13 @@ 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 +@lisp (define-public network-manager (package (name "network-manager") ;; @dots{} (properties '((upstream-name . "NetworkManager"))))) -@end example +@end lisp When passed @code{--update}, it modifies distribution source files to update the version numbers and source tarball hashes of those package @@ -9323,14 +9337,14 @@ Package developers can specify in package recipes the name and version of the package when they differ from the name or version that Guix uses, as in this example: -@example +@lisp (package (name "grub") ;; @dots{} ;; CPE calls this package "grub2". (properties '((cpe-name . "grub2") (cpe-version . "2.3"))) -@end example +@end lisp @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>. Some entries in the CVE database do not specify which version of a @@ -9338,7 +9352,7 @@ 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 +@lisp (package (name "t1lib") ;; @dots{} @@ -9347,7 +9361,7 @@ declare them as in this example: "CVE-2011-1553" "CVE-2011-1554" "CVE-2011-5244"))))) -@end example +@end lisp @item formatting Warn about obvious source code formatting issues: trailing white space, @@ -10447,11 +10461,11 @@ mode, as in the example above. However, more recent machines rely instead on the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case, the @code{bootloader} field should contain something along these lines: -@example +@lisp (bootloader-configuration (bootloader grub-efi-bootloader) (target "/boot/efi")) -@end example +@end lisp @xref{Bootloader Configuration}, for more information on the available configuration options. @@ -10588,11 +10602,11 @@ Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the following expression returns a list that contains all the services in @code{%desktop-services} minus the Avahi service: -@example +@lisp (remove (lambda (service) (eq? (service-kind service) avahi-service-type)) %desktop-services) -@end example +@end lisp @unnumberedsubsec Instantiating the System @@ -10753,12 +10767,12 @@ the home directory of newly-created user accounts. For instance, a valid value may look like this: -@example +@lisp `((".bashrc" ,(plain-file "bashrc" "echo Hello\n")) (".guile" ,(plain-file "guile" "(use-modules (ice-9 readline)) (activate-readline)"))) -@end example +@end lisp @item @code{issue} (default: @code{%default-issue}) A string denoting the contents of the @file{/etc/issue} file, which is @@ -10836,14 +10850,14 @@ 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 +@lisp (use-modules (gnu) (guix)) (operating-system ;; ... (label (package-full-name (operating-system-kernel this-operating-system)))) -@end example +@end lisp It is an error to refer to @code{this-operating-system} outside an operating system definition. @@ -10859,12 +10873,12 @@ The list of file systems to be mounted is specified in the (@pxref{Using the Configuration System}). Each file system is declared using the @code{file-system} form, like this: -@example +@lisp (file-system (mount-point "/home") (device "/dev/sda3") (type "ext4")) -@end example +@end lisp As usual, some of the fields are mandatory---those shown in the example above---while others can be omitted. These are described below. @@ -10898,12 +10912,12 @@ procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are plain strings. Here's an example of a file system referred to by its label, as shown by the @command{e2label} command: -@example +@lisp (file-system (mount-point "/home") (type "ext4") (device (file-system-label "my-home"))) -@end example +@end lisp @findex uuid UUIDs are converted from their string representation (as shown by the @@ -10914,12 +10928,12 @@ form of UUID used by the ext2 family of file systems and others, but it is different from ``UUIDs'' found in FAT file systems, for instance.}, like this: -@example +@lisp (file-system (mount-point "/home") (type "ext4") (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example +@end lisp When the source of a file system is a mapped device (@pxref{Mapped Devices}), its @code{device} field @emph{must} refer to the mapped @@ -11094,12 +11108,12 @@ The @file{/dev/mapper/home} device can then be used as the @code{device} of a @code{file-system} declaration (@pxref{File Systems}). -@example +@lisp (mapped-device (source "/dev/sda3") (target "home") (type luks-device-mapping)) -@end example +@end lisp Alternatively, to become independent of device numbering, one may obtain the LUKS UUID (@dfn{unique identifier}) of the source device by a @@ -11111,12 +11125,12 @@ cryptsetup luksUUID /dev/sda3 and use it as follows: -@example +@lisp (mapped-device (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) (target "home") (type luks-device-mapping)) -@end example +@end lisp @cindex swap encryption It is also desirable to encrypt swap space, since swap space may contain @@ -11128,12 +11142,12 @@ swap file is encrypted because the entire device is encrypted. A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1} may be declared as follows: -@example +@lisp (mapped-device (source (list "/dev/sda1" "/dev/sdb1")) (target "/dev/md0") (type raid-device-mapping)) -@end example +@end lisp The @file{/dev/md0} device can then be used as the @code{device} of a @code{file-system} declaration (@pxref{File Systems}). @@ -11152,7 +11166,7 @@ User accounts and groups are entirely managed through the @code{operating-system} declaration. They are specified with the @code{user-account} and @code{user-group} forms: -@example +@lisp (user-account (name "alice") (group "users") @@ -11162,7 +11176,7 @@ User accounts and groups are entirely managed through the "cdrom")) ;the good ol' CD-ROM (comment "Bob's sister") (home-directory "/home/alice")) -@end example +@end lisp When booting or upon completion of @command{guix system reconfigure}, the system ensures that only the user accounts and groups specified in @@ -11226,14 +11240,14 @@ 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 +@lisp (user-account (name "charlie") (group "users") ;; Specify a SHA-512-hashed initial password. (password (crypt "InitialPassword!" "$6$abc"))) -@end example +@end lisp @quotation Note The hash of this initial password will be available in a file in @@ -11251,9 +11265,9 @@ Guile Reference Manual}, for information on Guile's @code{crypt} procedure. @cindex groups User group declarations are even simpler: -@example +@lisp (user-group (name "students")) -@end example +@end lisp @deftp {Data Type} user-group This type is for, well, user groups. There are just a few fields: @@ -11340,7 +11354,7 @@ 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 +@lisp ;; The German QWERTZ layout. Here we assume a standard ;; "pc105" keyboard model. (keyboard-layout "de") @@ -11365,7 +11379,7 @@ about. Here are a few example: ;; dead keys to enter accented characters. This is for an ;; Apple MacBook keyboard. (keyboard-layout "us" "intl" #:model "macbook78") -@end example +@end lisp See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package for a complete list of supported layouts, variants, and models. @@ -11455,20 +11469,20 @@ used locales, but not all the available locales, in order to save space. For instance, to add the North Frisian locale for Germany, the value of that field may be: -@example +@lisp (cons (locale-definition (name "fy_DE.utf8") (source "fy_DE")) %default-locale-definitions) -@end example +@end lisp Likewise, to save space, one might want @code{locale-definitions} to list only the locales that are actually used, as in: -@example +@lisp (list (locale-definition (name "ja_JP.eucjp") (source "ja_JP") (charset "EUC-JP"))) -@end example +@end lisp @vindex LOCPATH The compiled locale definitions are available at @@ -11554,13 +11568,13 @@ it---this is especially crucial on a multi-user system. To do that, the administrator can specify several libc packages in the @code{locale-libcs} field of @code{operating-system}: -@example +@lisp (use-package-modules base) (operating-system ;; @dots{} (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example +@end lisp This example would lead to a system containing locale definitions for both libc 2.21 and the current version of libc in @@ -11665,11 +11679,11 @@ This is the default value of the @code{services} field of system, you will want to append services to @code{%base-services}, like this: -@example +@lisp (append (list (service avahi-service-type) (service openssh-service-type)) %base-services) -@end example +@end lisp @end defvr @defvr {Scheme Variable} special-files-service-type @@ -11682,19 +11696,19 @@ and the second element is its target. By default it is: @cindex @file{/bin/sh} @cindex @file{sh}, in @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example +@lisp +`(("/bin/sh" ,(file-append bash "/bin/sh"))) +@end lisp @cindex @file{/usr/bin/env} @cindex @file{env}, in @file{/usr/bin} If you want to add, say, @code{/usr/bin/env} to your system, you can change it to: -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example +@lisp +`(("/bin/sh" ,(file-append bash "/bin/sh")) + ("/usr/bin/env" ,(file-append coreutils "/bin/env"))) +@end lisp Since this is part of @code{%base-services}, you can use @code{modify-services} to customize the set of special files @@ -11710,10 +11724,10 @@ For example, adding the following lines to the @code{services} field of your operating system declaration leads to a @file{/usr/bin/env} symlink: -@example +@lisp (extra-special-file "/usr/bin/env" (file-append coreutils "/bin/env")) -@end example +@end lisp @end deffn @deffn {Scheme Procedure} host-name-service @var{name} @@ -12212,14 +12226,14 @@ In the following example, a rule for a USB device is defined to be stored in the file @file{90-usb-thing.rules}. The rule runs a script upon detecting a USB device with a given product identifier. -@example +@lisp (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 +@end lisp The @command{herd rules udev} command, as root, returns the name of the directory containing all the active udev rules. @@ -12227,7 +12241,7 @@ directory containing all the active udev rules. Here we show how the default @var{udev-service} can be extended with it. -@example +@lisp (operating-system ;; @dots{} (services @@ -12236,7 +12250,7 @@ Here we show how the default @var{udev-service} can be extended with it. (udev-configuration (inherit config) (rules (append (udev-configuration-rules config) (list %example-udev-rule)))))))) -@end example +@end lisp @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}] Return a udev file named @var{file-name} containing the rules defined @@ -12244,7 +12258,7 @@ within @var{file}, a file-like object. The following example showcases how we can use an existing rule file. -@example +@lisp (use-modules (guix download) ;for url-fetch (guix packages) ;for origin ;; @dots{}) @@ -12259,7 +12273,7 @@ The following example showcases how we can use an existing rule file. "android-udev-rules/" version "/51-android.rules")) (sha256 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) -@end example +@end lisp @end deffn Additionally, Guix package definitions can be included in @var{rules} in @@ -12278,7 +12292,7 @@ create such a group, we must define it both as part of the @var{supplementary-groups} of our @var{user-account} declaration, as well as in the @var{groups} field of the @var{operating-system} record. -@example +@lisp (use-modules (gnu packages android) ;for android-udev-rules (gnu system shadow) ;for user-group ;; @dots{}) @@ -12304,7 +12318,7 @@ well as in the @var{groups} field of the @var{operating-system} record. (udev-configuration (inherit config) (rules (cons android-udev-rules (udev-configuration-rules config)))))))) -@end example +@end lisp @defvr {Scheme Variable} urandom-seed-service-type Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom} @@ -12378,9 +12392,9 @@ This is a list of compression method/level tuple used when compressing substitutes. For example, to compress all substitutes with @emph{both} lzip at level 7 and gzip at level 9, write: -@example +@lisp '(("lzip" 7) ("gzip" 9)) -@end example +@end lisp Level 9 achieves the best compression ratio at the expense of increased CPU usage, whereas level 1 achieves fast compression. @@ -12435,12 +12449,12 @@ Return a service that installs a configuration file for the The following limits definition sets two hard and soft limits for all login sessions of users in the @code{realtime} group: -@example +@lisp (pam-limits-service (list (pam-limits-entry "@@realtime" 'both 'rtprio 99) (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example +@end lisp The first entry increases the maximum realtime priority for non-privileged processes; the second entry lifts any restriction of the @@ -12647,7 +12661,7 @@ 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 +@lisp (log-rotation (frequency 'daily) (files '("/var/log/apache/*")) @@ -12655,7 +12669,7 @@ defined like this: "rotate 6" "notifempty" "nocompress"))) -@end example +@end lisp The list of fields is as follows: @@ -12704,12 +12718,12 @@ 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 +@lisp (service dhcpd-service-type (dhcpd-configuration (config-file (local-file "my-dhcpd.conf")) (interfaces '("enp0s25")))) -@end example +@end lisp @end deffn @deftp {Data Type} dhcpd-configuration @@ -12765,11 +12779,11 @@ to handle. For example: -@example +@lisp (static-networking-service "eno1" "192.168.1.82" #:gateway "192.168.1.2" #:name-servers '("192.168.1.2")) -@end example +@end lisp @end deffn @cindex wicd @@ -12924,11 +12938,11 @@ a network connection manager. Its value must be an @code{connman-configuration} record as in this example: -@example +@lisp (service connman-service-type (connman-configuration (disable-vpn? #t))) -@end example +@end lisp See below for details about @code{connman-configuration}. @end deffn @@ -13028,6 +13042,7 @@ objects}). @end deftp @cindex NTP (Network Time Protocol), service +@cindex ntpd, service for the Network Time Protocol daemon @cindex real time clock @defvr {Scheme Variable} ntp-service-type This is the type of the service running the @uref{http://www.ntp.org, @@ -13043,10 +13058,11 @@ This is the data type for the NTP service configuration. @table @asis @item @code{servers} (default: @code{%ntp-servers}) -This is the list of servers (host names) with which @command{ntpd} will be -synchronized. +This is the list of servers (@code{<ntp-server>} records) with which +@command{ntpd} will be synchronized. See the @code{ntp-server} data type +definition below. -@item @code{allow-large-adjustment?} (default: @code{#f}) +@item @code{allow-large-adjustment?} (default: @code{#t}) This determines whether @command{ntpd} is allowed to make an initial adjustment of more than 1,000 seconds. @@ -13060,13 +13076,39 @@ 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 +@deftp {Data Type} ntp-server +The data type representing the configuration of a NTP server. + +@table @asis +@item @code{type} (default: @code{'server}) +The type of the NTP server, given as a symbol. One of @code{'pool}, +@code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}. + +@item @code{address} +The address of the server, as a string. + +@item @code{options} +NTPD options to use with that specific server, given as a list of option names +and/or of option names and values tuples. The following example define a server +to use with the options @option{iburst} and @option{prefer}, as well as +@option{version} 3 and a @option{maxpoll} time of 16 seconds. + +@example +(ntp-server + (type 'server) + (address "some.ntp.server.org") + (options `(iburst (version 3) (maxpoll 16) prefer)))) +@end example +@end table +@end deftp + @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 +@lisp (service openntpd-service-type (openntpd-configuration @@ -13076,9 +13118,14 @@ clock synchronized with that of the given servers. (constraints-from '("https://www.google.com/")) (allow-large-adjustment? #t))) -@end example +@end lisp @end deffn +@defvr {Scheme Variable} %openntpd-servers +This variable is a list of the server addresses defined in +@var{%ntp-servers}. +@end defvr + @deftp {Data Type} openntpd-configuration @table @asis @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")}) @@ -13092,9 +13139,9 @@ Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} will listen to each sensor that actually exists and ignore non-existent ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more information. -@item @code{server} (default: @var{%ntp-servers}) +@item @code{server} (default: @code{'()}) Specify a list of IP addresses or hostnames of NTP servers to synchronize to. -@item @code{servers} (default: @code{'()}) +@item @code{servers} (default: @var{%openntp-servers}) 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. @@ -13126,7 +13173,7 @@ 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 +@lisp (service inetd-service-type (inetd-configuration @@ -13148,7 +13195,7 @@ gateway @code{hostname}: (arguments '("ssh" "-qT" "-i" "/path/to/ssh_key" "-W" "smtp-server:25" "user@@hostname"))))) -@end example +@end lisp See below for more details about @code{inetd-configuration}. @end deffn @@ -13284,9 +13331,9 @@ This is the service type for the @uref{https://rsync.samba.org, rsync} daemon, The value for this service type is a @command{rsync-configuration} record as in this example: -@example +@lisp (service rsync-service-type) -@end example +@end lisp See below for details about @code{rsync-configuration}. @end deffn @@ -13390,7 +13437,7 @@ 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 +@lisp (service openssh-service-type (openssh-configuration (x11-forwarding? #t) @@ -13398,18 +13445,18 @@ shell daemon, @command{sshd}. Its value must be an (authorized-keys `(("alice" ,(local-file "alice.pub")) ("bob" ,(local-file "bob.pub")))))) -@end example +@end lisp See below for details about @code{openssh-configuration}. This service can be extended with extra authorized keys, as in this example: -@example +@lisp (service-extension openssh-service-type (const `(("charlie" ,(local-file "charlie.pub"))))) -@end example +@end lisp @end deffn @deftp {Data Type} openssh-configuration @@ -13486,12 +13533,12 @@ subsystem request. The command @command{internal-sftp} implements an in-process SFTP server. Alternately, one can specify the @command{sftp-server} command: -@example +@lisp (service openssh-service-type (openssh-configuration (subsystems `(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) -@end example +@end lisp @item @code{accepted-environment} (default: @code{'()}) List of strings describing which environment variables may be exported. @@ -13504,11 +13551,11 @@ 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 +@lisp (service openssh-service-type (openssh-configuration (accepted-environment '("COLORTERM")))) -@end example +@end lisp @item @code{authorized-keys} (default: @code{'()}) @cindex authorized keys, SSH @@ -13517,13 +13564,13 @@ 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 +@lisp (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 +@end lisp @noindent registers the specified public keys for user accounts @code{rekado}, @@ -13546,12 +13593,12 @@ 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 +@lisp (openssh-configuration (extra-content "\ Match Address 192.168.0.1 PermitRootLogin yes")) -@end example +@end lisp @end table @end deftp @@ -13564,10 +13611,10 @@ object. For example, to specify a Dropbear service listening on port 1234, add this call to the operating system's @code{services} field: -@example +@lisp (dropbear-service (dropbear-configuration (port-number 1234))) -@end example +@end lisp @end deffn @deftp {Data Type} dropbear-configuration @@ -13608,7 +13655,7 @@ This variable is typically used in the @code{hosts-file} field of an @code{operating-system} declaration (@pxref{operating-system Reference, @file{/etc/hosts}}): -@example +@lisp (use-modules (gnu) (guix)) (operating-system @@ -13620,7 +13667,7 @@ This variable is typically used in the @code{hosts-file} field of an (plain-file "hosts" (string-append (local-host-aliases host-name) %facebook-host-aliases)))) -@end example +@end lisp This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook. @@ -14054,9 +14101,9 @@ system, add a @code{cups-service} to the operating system definition: 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 +@lisp (service cups-service-type) -@end example +@end lisp @end deffn The CUPS configuration controls the basic things about your CUPS @@ -14072,13 +14119,13 @@ 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 +@lisp (service cups-service-type (cups-configuration (web-interface? #t) (extensions (list cups-filters escpr hplip-minimal)))) -@end example +@end lisp 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, @@ -14886,12 +14933,12 @@ 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 +@lisp (service cups-service-type (opaque-cups-configuration (cupsd.conf cupsd.conf) (cups-files.conf cups-files.conf))) -@end example +@end lisp @node Desktop Services @@ -15034,7 +15081,7 @@ 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 +@lisp (use-modules (gnu)) (use-service-modules desktop) (operating-system @@ -15044,7 +15091,7 @@ them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto (service xfce-desktop-service) %desktop-services)) ...) -@end example +@end lisp These desktop environments will then be available as options in the graphical login window. @@ -15313,9 +15360,9 @@ 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 +@lisp (service alsa-service-type) -@end example +@end lisp See below for details about @code{alsa-configuration}. @end deffn @@ -15401,7 +15448,7 @@ to create a geographic database using the @code{postgis} extension, a user can configure the postgresql-service as in this example: @cindex postgis -@example +@lisp (use-package-modules databases geo) (operating-system @@ -15413,7 +15460,7 @@ configure the postgresql-service as in this example: (cons* (postgresql-service #:extension-packages (list postgis)) %base-services))) -@end example +@end lisp Then the extension becomes visible and you can initialise an empty geographic database in this way: @@ -15461,9 +15508,9 @@ Memcached} service, which provides a distributed in memory cache. The value for the service type is a @code{memcached-configuration} object. @end defvr -@example +@lisp (service memcached-service-type) -@end example +@end lisp @deftp {Data Type} memcached-configuration Data type representing the configuration of memcached. @@ -15492,9 +15539,9 @@ 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 +@lisp (service mongodb-service-type) -@end example +@end lisp @deftp {Data Type} mongodb-configuration Data type representing the configuration of mongodb. @@ -15565,11 +15612,11 @@ 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 +@lisp (dovecot-service #:config (dovecot-configuration (mail-location "maildir:~/.mail"))) -@end example +@end lisp The available configuration parameters follow. Each parameter definition is preceded by its type; for example, @samp{string-list foo} @@ -16905,11 +16952,11 @@ The contents of the @code{dovecot.conf}, as a string. For example, if your @code{dovecot.conf} is just the empty string, you could instantiate a dovecot service like this: -@example +@lisp (dovecot-service #:config (opaque-dovecot-configuration (string ""))) -@end example +@end lisp @subsubheading OpenSMTPD Service @@ -16918,11 +16965,11 @@ 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 +@lisp (service opensmtpd-service-type (opensmtpd-configuration (config-file (local-file "./my-smtpd.conf")))) -@end example +@end lisp @end deffn @deftp {Data Type} opensmtpd-configuration @@ -16952,11 +16999,11 @@ 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 +@lisp (service exim-service-type (exim-configuration (config-file (local-file "./my-exim.conf")))) -@end example +@end lisp @end deffn In order to use an @code{exim-service-type} service you must also have a @@ -17280,11 +17327,11 @@ Defaults to @samp{()}. This is the type of the service which provides @code{/etc/aliases}, specifying how to deliver mail to users on this system. -@example +@lisp (service mail-aliases-service-type '(("postmaster" "bob") ("bob" "bob@@example.com" "bob@@example2.com"))) -@end example +@end lisp @end deffn The configuration for a @code{mail-aliases-service-type} service is an @@ -17307,11 +17354,11 @@ 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 +@lisp (service imap4d-service-type (imap4d-configuration (config-file (local-file "imap4d.conf")))) -@end example +@end lisp @end deffn @deftp {Data Type} imap4d-configuration @@ -17345,7 +17392,7 @@ 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 +@lisp (service prosody-service-type (prosody-configuration (modules-enabled (cons "groups" "mam" %default-modules-enabled)) @@ -17359,7 +17406,7 @@ record as in this example: (list (virtualhost-configuration (domain "example.net")))))) -@end example +@end lisp See below for details about @code{prosody-configuration}. @@ -17747,11 +17794,11 @@ The contents of the @code{prosody.cfg.lua} to use. For example, if your @code{prosody.cfg.lua} is just the empty string, you could instantiate a prosody service like this: -@example +@lisp (service prosody-service-type (opaque-prosody-configuration (prosody.cfg.lua ""))) -@end example +@end lisp @c end of Prosody auto-generated documentation @@ -17770,9 +17817,9 @@ below). To have BitlBee listen on port 6667 on localhost, add this line to your services: -@example +@lisp (service bitlbee-service-type) -@end example +@end lisp @end defvr @deftp {Data Type} bitlbee-configuration @@ -17844,7 +17891,7 @@ the server of the @uref{https://mumble.info, Mumble} voice-over-IP The service type for the Murmur server. An example configuration can look like this: -@example +@lisp (service murmur-service-type (murmur-configuration (welcome-text @@ -17852,7 +17899,7 @@ look like this: (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 +@end lisp After reconfiguring your system, you can manually set the murmur @code{SuperUser} password with the command that is printed during the activation phase. @@ -17966,14 +18013,14 @@ 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 +@lisp (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") -@end example +@end lisp @item @code{ssl-key} (default: @code{#f}) Filepath to the ssl private key used for encrypted connections. -@example +@lisp (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") -@end example +@end lisp @item @code{ssl-dh-params} (default: @code{#f}) File name of a PEM-encoded file with Diffie-Hellman parameters @@ -18047,20 +18094,20 @@ 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 +@lisp (service tailon-service-type) -@end example +@end lisp The following example customises more of the Tailon configuration, adding @command{sed} to the list of allowed commands. -@example +@lisp (service tailon-service-type (tailon-configuration (config-file (tailon-configuration-file (allowed-commands '("tail" "grep" "awk" "sed")))))) -@end example +@end lisp @deftp {Data Type} tailon-configuration @@ -18076,11 +18123,11 @@ The configuration file to use for Tailon. This can be set to a For example, to instead use a local file, the @code{local-file} function can be used: -@example +@lisp (service tailon-service-type (tailon-configuration (config-file (local-file "./my-tailon.conf")))) -@end example +@end lisp @item @code{package} (default: @code{tailon}) The tailon package to use. @@ -18136,12 +18183,12 @@ 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 +@lisp (tailon-configuration-file (http-auth "basic") (users '(("user1" . "password1") ("user2" . "password2")))) -@end example +@end lisp @end table @end deftp @@ -18158,11 +18205,11 @@ This is the service type for the service, its value must be a @code{darkstat-configuration} record as in this example: -@example +@lisp (service darkstat-service-type (darkstat-configuration (interface "eno1"))) -@end example +@end lisp @end defvar @deftp {Data Type} darkstat-configuration @@ -18202,11 +18249,11 @@ This is the service type for the service, its value must be a @code{prometheus-node-exporter-configuration} record as in this example: -@example +@lisp (service prometheus-node-exporter-service-type (prometheus-node-exporter-configuration (web-listen-address ":9100"))) -@end example +@end lisp @end defvar @deftp {Data Type} prometheus-node-exporter-configuration @@ -18682,7 +18729,7 @@ Here is a simple operating system declaration with a default configuration of the @code{nslcd-service-type} and a Name Service Switch configuration that consults the @code{ldap} name service last: -@example +@lisp (use-service-modules authentication) (use-modules (gnu system nss)) ... @@ -18704,7 +18751,7 @@ consults the @code{ldap} name service last: (group services) (netgroup services) (gshadow services))))) -@end example +@end lisp @c %start of generated documentation for nslcd-configuration @@ -19163,19 +19210,19 @@ Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server A simple example configuration is given below. -@example +@lisp (service httpd-service-type (httpd-configuration (config (httpd-config-file (server-name "www.example.com") (document-root "/srv/http/www.example.com"))))) -@end example +@end lisp Other services can also extend the @code{httpd-service-type} to add to the configuration. -@example +@lisp (simple-service 'my-extra-server httpd-service-type (list (httpd-virtualhost @@ -19183,7 +19230,7 @@ the configuration. (list (string-append "ServerName "www.example.com DocumentRoot \"/srv/http/www.example.com\""))))) -@end example +@end lisp @end deffn The details for the @code{httpd-configuration}, @code{httpd-module}, @@ -19240,7 +19287,7 @@ 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 +@lisp (service httpd-service-type (httpd-configuration (config @@ -19261,7 +19308,7 @@ For example, in order to handle requests for PHP files, you can use Apache’s (php-fpm-configuration (socket "/var/run/php-fpm.sock") (socket-group "httpd"))) -@end example +@end lisp @item @code{server-root} (default: @code{httpd}) The @code{ServerRoot} in the configuration file, defaults to the httpd @@ -19315,7 +19362,7 @@ This data type represents a virtualhost configuration block for the httpd servic These should be added to the extra-config for the httpd-service. -@example +@lisp (simple-service 'my-extra-server httpd-service-type (list (httpd-virtualhost @@ -19323,7 +19370,7 @@ These should be added to the extra-config for the httpd-service. (list (string-append "ServerName "www.example.com DocumentRoot \"/srv/http/www.example.com\""))))) -@end example +@end lisp @table @asis @item @code{addresses-and-ports} @@ -19344,25 +19391,25 @@ value for this service type is a @code{<nginx-configuration>} record. A simple example configuration is given below. -@example +@lisp (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 +@end lisp 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 +@lisp (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 lisp @end deffn At startup, @command{nginx} has not yet read its configuration file, so @@ -19398,14 +19445,14 @@ file, the elements should be of type 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 +@lisp (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 +@end lisp @item @code{upstream-blocks} (default: @code{'()}) A list of @dfn{upstream blocks} to create in the generated configuration @@ -19419,7 +19466,7 @@ creates a server configuration with one location configuration, that will proxy requests to a upstream configuration, which will handle requests with two servers. -@example +@lisp (service nginx-service-type (nginx-configuration @@ -19437,7 +19484,7 @@ requests with two servers. (name "server-proxy") (servers (list "server1.example.com" "server2.example.com"))))))) -@end example +@end lisp @item @code{file} (default: @code{#f}) If a configuration @var{file} is provided, this will be used, rather than @@ -19475,9 +19522,9 @@ 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 +@lisp '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") -@end example +@end lisp @item @code{server-name} (default: @code{(list 'default)}) A list of server names this server represents. @code{'default} represents the @@ -19615,7 +19662,7 @@ VCL syntax. For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can do something along these lines: -@example +@lisp (define %gnu-mirror (plain-file "gnu.vcl" @@ -19629,7 +19676,7 @@ backend gnu @{ .host = "www.gnu.org"; @}")) (listen '(":80")) (vcl %gnu-mirror))) %base-services))) -@end example +@end lisp The configuration of an already running Varnish instance can be inspected and changed using the @command{varnishadm} program. @@ -19665,7 +19712,7 @@ Service type for Patchwork. The following example is an example of a minimal service for Patchwork, for the @code{patchwork.example.com} domain. -@example +@lisp (service patchwork-service-type (patchwork-configuration (domain "patchwork.example.com") @@ -19685,7 +19732,7 @@ the @code{patchwork.example.com} domain. (extra-parameters '((mailboxes . ("Patches")))))))) -@end example +@end lisp There are three records for configuring the Patchwork service. The @code{<patchwork-configuration>} relates to the configuration for Patchwork @@ -20004,7 +20051,7 @@ 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 +@lisp (services (cons* (service dhcp-client-service-type) (service php-fpm-service-type) (service nginx-service-type @@ -20017,7 +20064,7 @@ A simple services setup for nginx with php can look like this: (ssl-certificate #f) (ssl-certificate-key #f))) %base-services)) -@end example +@end lisp @cindex cat-avatar-generator The cat avatar generator is a simple service to demonstrate the use of php-fpm @@ -20035,14 +20082,14 @@ 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 +@lisp (services (cons* (cat-avatar-generator-service #:configuration (nginx-server-configuration (server-name '("example.com")))) ... %base-services)) -@end example +@end lisp @subsubheading Hpcguix-web @@ -20099,7 +20146,7 @@ The hpcguix-web package to use. A typical hpcguix-web service declaration looks like this: -@example +@lisp (service hpcguix-web-service-type (hpcguix-web-configuration (specs @@ -20107,7 +20154,7 @@ A typical hpcguix-web service declaration looks like this: (hpcweb-configuration (title-prefix "Guix-HPC - ") (menu '(("/about" "ABOUT")))))))) -@end example +@end lisp @quotation Note The hpcguix-web service periodically updates the package list it publishes by @@ -20167,7 +20214,7 @@ can be found there: 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 +@lisp (define %nginx-deploy-hook (program-file "nginx-deploy-hook" @@ -20184,7 +20231,7 @@ must be a @code{certbot-configuration} record as in this example: (deploy-hook %nginx-deploy-hook)) (certificate-configuration (domains '("bar.example.net"))))))) -@end example +@end lisp See below for details about @code{certbot-configuration}. @end defvr @@ -20255,7 +20302,9 @@ all domains will be Subject Alternative Names on the certificate. 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}). +the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}), +and gives Let's Encrypt permission to log the public IP address of the +requesting machine. @item @code{authentication-hook} (default: @code{#f}) Command to be run in a shell once for each certificate challenge to be @@ -20766,12 +20815,12 @@ The list of knot-zone-configuration used by this configuration. This is the type of the dnsmasq service, whose value should be an @code{dnsmasq-configuration} object as in this example: -@example +@lisp (service dnsmasq-service-type (dnsmasq-configuration (no-resolv? #t) (servers '("192.168.1.1")))) -@end example +@end lisp @end deffn @deftp {Data Type} dnsmasq-configuration @@ -20824,9 +20873,9 @@ care of automatically updating DNS entries for service providers such as The following example show instantiates the service with its default configuration: -@example +@lisp (service ddclient-service-type) -@end example +@end lisp Note that ddclient needs to access credentials that are stored in a @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see @@ -21416,7 +21465,7 @@ 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 +@lisp (define %cuirass-specs #~(list '((#:name . "my-manifest") @@ -21447,7 +21496,7 @@ the @code{"custom-packages"} input, which is the equivalent of (service cuirass-service-type (cuirass-configuration (specifications %cuirass-specs))) -@end example +@end lisp While information related to build jobs is located directly in the specifications, global settings for the @command{cuirass} process are @@ -21535,9 +21584,9 @@ source is detected. More information can be found at 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 +@lisp (service tlp-service-type) -@end example +@end lisp @end deffn By default TLP does not need much configuration but most TLP parameters @@ -22065,12 +22114,12 @@ 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 +@lisp (service mpd-service-type (mpd-configuration (user "bob") (port "6666"))) -@end example +@end lisp @defvr {Scheme Variable} mpd-service-type The service type for @command{mpd} @@ -22124,12 +22173,12 @@ and performs required management tasks for virtualized guests. This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its value must be a @code{libvirt-configuration}. -@example +@lisp (service libvirt-service-type (libvirt-configuration (unix-sock-group "libvirt") (tls-port "16555"))) -@end example +@end lisp @end deffn @c Auto-generated with (generate-libvirt-documentation) @@ -22690,11 +22739,11 @@ itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime. This is the type of the virtlog daemon. Its value must be a @code{virtlog-configuration}. -@example +@lisp (service virtlog-service-type (virtlog-configuration (max-clients 1000))) -@end example +@end lisp @end deffn @deftypevr {@code{virtlog-configuration} parameter} integer log-level @@ -22832,11 +22881,11 @@ 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 +@lisp (service qemu-binfmt-service-type (qemu-binfmt-configuration (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")))) -@end example +@end lisp In this example, we enable transparent emulation for the ARM and aarch64 platforms. Running @code{herd stop qemu-binfmt} turns it off, and @@ -22862,12 +22911,12 @@ 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 +@lisp (service qemu-binfmt-service-type (qemu-binfmt-configuration (platforms (lookup-qemu-platforms "arm")) (guix-support? #t))) -@end example +@end lisp You can run: @@ -23018,7 +23067,7 @@ 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 +@lisp (service nginx-service-type (nginx-configuration (server-blocks @@ -23034,7 +23083,7 @@ serve the default @file{/srv/git} over HTTPS might be: (list (git-http-nginx-location-configuration (git-http-configuration (uri-path "/")))))))))) -@end example +@end lisp This example assumes that you are using Let's Encrypt to get your TLS certificate. @xref{Certificate Services}. The default @code{certbot} @@ -23053,9 +23102,9 @@ 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 +@lisp (service cgit-service-type) -@end example +@end lisp The @code{file-object} type designates either a file-like object (@pxref{G-Expressions, file-like objects}) or a string. @@ -23988,11 +24037,11 @@ The contents of the @code{cgitrc}, as a string. For example, if your @code{cgitrc} is just the empty string, you could instantiate a cgit service like this: -@example +@lisp (service cgit-service-type (opaque-cgit-configuration (cgitrc ""))) -@end example +@end lisp @subsubheading Gitolite Service @@ -24007,13 +24056,13 @@ 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 +@lisp (service gitolite-service-type (gitolite-configuration (admin-pubkey (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")))) -@end example +@end lisp 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 @@ -24056,9 +24105,9 @@ within the gitolite-admin repository. To specify the SSH key as a string, use the @code{plain-file} function. -@example +@lisp (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") -@end example +@end lisp @end table @end deftp @@ -24103,9 +24152,9 @@ 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 +@lisp (service wesnothd-service-type) -@end example +@end lisp @end defvar @deftp {Data Type} wesnothd-configuration @@ -24133,9 +24182,9 @@ read and identify fingerprints via a fingerprint sensor. The service type for @command{fprintd}, which provides the fingerprint reading capability. -@example +@lisp (service fprintd-service-type) -@end example +@end lisp @end defvr @cindex sysctl @@ -24149,11 +24198,11 @@ The service type for @command{sysctl}, which modifies kernel parameters under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated as: -@example +@lisp (service sysctl-service-type (sysctl-configuration (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example +@end lisp @end defvr @deftp {Data Type} sysctl-configuration @@ -24182,9 +24231,9 @@ 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 +@lisp (service pcscd-service-type) -@end example +@end lisp @end defvr @deftp {Data Type} pcscd-configuration @@ -24339,7 +24388,7 @@ Dictionary of English using the @code{gcide} package. The following is an example @code{dicod-service} configuration. -@example +@lisp (dicod-service #:config (dicod-configuration (handlers (list (dicod-handler @@ -24353,7 +24402,7 @@ The following is an example @code{dicod-service} configuration. (handler "wordnet") (options '("database=wn"))) %dicod-database:gcide)))) -@end example +@end lisp @cindex Docker @subsubheading Docker Service @@ -24453,7 +24502,7 @@ This is the type of the service that runs build daemon of the @url{https://nixos.org/nix/, Nix} package manager. Here is an example showing how to use it: -@example +@lisp (use-modules (gnu)) (use-service-modules nix) (use-package-modules package-management) @@ -24465,7 +24514,7 @@ how to use it: (services (append (list (service nix-service-type)) %base-services))) -@end example +@end lisp After @command{guix system reconfigure} configure Nix for your user: @@ -24620,7 +24669,7 @@ As an example, the declaration below configures the NSS to use the back-end}, which supports host name lookups over multicast DNS (mDNS) for host names ending in @code{.local}: -@example +@lisp (name-service-switch (hosts (list %files ;first, check /etc/hosts @@ -24642,7 +24691,7 @@ for host names ending in @code{.local}: ;; Finally, try with the "full" 'mdns'. (name-service (name "mdns"))))) -@end example +@end lisp 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 @@ -24723,10 +24772,10 @@ 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 +@lisp (lookup-specification (unavailable => continue) (success => return)) -@end example +@end lisp @end table @end deftp @@ -24750,11 +24799,11 @@ 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 +@lisp (operating-system ;; @dots{} (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example +@end lisp @defvr {Scheme Variable} %base-initrd-modules This is the list of kernel modules included in the initrd by default. @@ -24772,14 +24821,14 @@ 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 +@lisp (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 +@end lisp 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 @@ -25031,13 +25080,13 @@ Should you want to list additional boot menu entries @i{via} the boot another distro (hard to imagine!), you can define a menu entry along these lines: -@example +@lisp (menu-entry (label "The Other Distro") (linux "/boot/old/vmlinux-2.6.32") (linux-arguments '("root=/dev/sda2")) (initrd "/boot/old/initrd")) -@end example +@end lisp Details below. @@ -25052,9 +25101,9 @@ The label to show in the menu---e.g., @code{"GNU"}. @item @code{linux} The Linux kernel image to boot, for example: -@example +@lisp (file-append linux-libre "/bzImage") -@end example +@end lisp For GRUB, it is also possible to specify a device explicitly in the file path using GRUB's device naming convention (@pxref{Naming @@ -25590,7 +25639,7 @@ guix deploy @var{file} Such an invocation will deploy the machines that the code within @var{file} evaluates to. As an example, @var{file} might contain a definition like this: -@example +@lisp ;; This is a Guix deployment of a "bare bones" setup, with ;; no X11 display server, to a machine with an SSH daemon ;; listening on localhost:2222. A configuration such as this @@ -25630,7 +25679,7 @@ evaluates to. As an example, @var{file} might contain a definition like this: (user "alice") (identity "./id_rsa") (port 2222))))) -@end example +@end lisp The file should evaluate to a list of @var{machine} objects. This example, upon being deployed, will create a new generation on the remote system @@ -25919,7 +25968,7 @@ A @dfn{service type} is a node in the DAG described above. Let us start with a simple example, the service type for the Guix build daemon (@pxref{Invoking guix-daemon}): -@example +@lisp (define guix-service-type (service-type (name 'guix) @@ -25928,7 +25977,7 @@ with a simple example, the service type for the Guix build daemon (service-extension account-service-type guix-accounts) (service-extension activation-service-type guix-activation))) (default-value (guix-configuration)))) -@end example +@end lisp @noindent It defines three things: @@ -25972,12 +26021,12 @@ booted. A service of this type is instantiated like this: -@example +@lisp (service guix-service-type (guix-configuration (build-accounts 5) (use-substitutes? #f))) -@end example +@end lisp The second argument to the @code{service} form is a value representing the parameters of this specific service instance. @@ -25986,9 +26035,9 @@ 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 +@lisp (service guix-service-type) -@end example +@end lisp @code{guix-service-type} is quite simple because it extends other services but is not extensible itself. @@ -25997,7 +26046,7 @@ services but is not extensible itself. The service type for an @emph{extensible} service looks like this: -@example +@lisp (define udev-service-type (service-type (name 'udev) (extensions @@ -26011,7 +26060,7 @@ The service type for an @emph{extensible} service looks like this: (udev-configuration (udev udev) ;the udev package to use (rules (append initial-rules rules))))))))) -@end example +@end lisp This is the service type for the @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device @@ -26068,17 +26117,17 @@ raised. For instance, this: -@example +@lisp (service openssh-service-type) -@end example +@end lisp @noindent is equivalent to this: -@example +@lisp (service openssh-service-type (openssh-configuration)) -@end example +@end lisp In both cases the result is an instance of @code{openssh-service-type} with the default configuration. @@ -26099,7 +26148,7 @@ parameters. Here is an example of how a service is created and manipulated: -@example +@lisp (define s (service nginx-service-type (nginx-configuration @@ -26113,7 +26162,7 @@ Here is an example of how a service is created and manipulated: (eq? (service-kind s) nginx-service-type) @result{} #t -@end example +@end lisp The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as @@ -26215,10 +26264,10 @@ service is an instance. For example, this extends mcron (@pxref{Scheduled Job Execution}) with an additional job: -@example +@lisp (simple-service 'my-mcron-job mcron-service-type #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example +@end lisp @end deffn At the core of the service abstraction lies the @code{fold-services} @@ -26253,9 +26302,9 @@ 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 +@lisp (list `("issue" ,(plain-file "issue" "Welcome!\n"))) -@end example +@end lisp In this example, the effect would be to add an @file{/etc/issue} file pointing to the given file. @@ -26391,7 +26440,7 @@ shepherd, The GNU Shepherd Manual}). The following example defines an action called @code{say-hello} that kindly greets the user: -@example +@lisp (shepherd-action (name 'say-hello) (documentation "Say hi!") @@ -26399,7 +26448,7 @@ greets the user: (format #t "Hello, friend! arguments: ~s\n" args) #t))) -@end example +@end lisp Assuming this action is added to the @code{example} service, then you can do: @@ -26606,13 +26655,13 @@ Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining Packages}). Then, the original package definition is augmented with a @code{replacement} field pointing to the package containing the bug fix: -@example +@lisp (define bash (package (name "bash") ;; @dots{} (replacement bash-fixed))) -@end example +@end lisp From there on, any package depending directly or indirectly on Bash---as reported by @command{guix gc --requisites} (@pxref{Invoking guix |