The @file{/etc/guix/machines.scm} file typically looks like this:
-@example
+@lisp
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
(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
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
of packages:
@findex packages->manifest
-@example
+@lisp
(use-package-modules guile emacs)
(packages->manifest
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}
@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
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}
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)
(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
@noindent
Consider this example:
-@example
+@lisp
(define libressl-instead-of-openssl
;; This is a procedure to replace OPENSSL by LIBRESSL,
;; recursively.
(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}
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
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
The example below shows how to add a package as a native input of itself when
cross-compiling:
-@example
+@lisp
(package
(name "guile")
;; ...
(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
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}
Consider this ``normal'' procedure:
-@example
+@lisp
(define (sh-symlink store)
;; Return a derivation that symlinks the 'bash' executable.
(let* ((drv (package-derivation store bash))
(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
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/>
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:
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)
@result{} 4
@result{} some-state
-@end example
+@end lisp
@end deffn
@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
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
(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.
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
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
@code{#+} plays the same role as @code{#$}, but is a reference to a
native package build:
-@example
+@lisp
(gexp->derivation "vi"
#~(begin
(mkdir #$output)
(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
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))
#$build
(display "success!\n")
#t)))
-@end example
+@end lisp
@noindent
In this example, the @code{(guix build utils)} module is automatically
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
(use-modules (guix build utils)
(gnu build vm))
@dots{})))
-@end example
+@end lisp
@cindex extensions, for gexps
@findex with-extensions
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)
#~(begin
(use-modules (json))
@dots{})))
-@end example
+@end lisp
The syntactic form to construct gexps is summarized below.
@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
@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}
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
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
@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
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
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
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
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}
@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
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
developers who found CVE alerts and verified they can be ignored can
declare them as in this example:
-@example
+@lisp
(package
(name "t1lib")
;; @dots{}
"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,
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.
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
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
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.
(@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.
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
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
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
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
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}).
@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")
"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
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
@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:
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")
;; 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.
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
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
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
@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
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}
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.
Here we show how the default @var{udev-service} can be extended with it.
-@example
+@lisp
(operating-system
;; @dots{}
(services
(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
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{})
"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
@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{})
(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}
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.
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
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/*"))
"rotate 6"
"notifempty"
"nocompress")))
-@end example
+@end lisp
The list of fields is as follows:
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
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
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
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
(constraints-from '("https://www.google.com/"))
(allow-large-adjustment? #t)))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} openntpd-configuration
forwards smtp traffic over ssh to a server @code{smtp-server} behind a
gateway @code{hostname}:
-@example
+@lisp
(service
inetd-service-type
(inetd-configuration
(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
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
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)
(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
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.
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
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},
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
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
@code{operating-system} declaration (@pxref{operating-system Reference,
@file{/etc/hosts}}):
-@example
+@lisp
(use-modules (gnu) (guix))
(operating-system
(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.
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
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,
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
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
-@example
+@lisp
(use-modules (gnu))
(use-service-modules desktop)
(operating-system
(service xfce-desktop-service)
%desktop-services))
...)
-@end example
+@end lisp
These desktop environments will then be available as options in the
graphical login window.
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
configure the postgresql-service as in this example:
@cindex postgis
-@example
+@lisp
(use-package-modules databases geo)
(operating-system
(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:
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.
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.
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}
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
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
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
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
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
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))
(list
(virtualhost-configuration
(domain "example.net"))))))
-@end example
+@end lisp
See below for details about @code{prosody-configuration}.
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
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
The service type for the Murmur server. An example configuration can
look like this:
-@example
+@lisp
(service murmur-service-type
(murmur-configuration
(welcome-text
(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.
@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
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
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.
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
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
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
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))
...
(group services)
(netgroup services)
(gshadow services)))))
-@end example
+@end lisp
@c %start of generated documentation for nslcd-configuration
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
(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},
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
(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
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
(list (string-append
"ServerName "www.example.com
DocumentRoot \"/srv/http/www.example.com\"")))))
-@end example
+@end lisp
@table @asis
@item @code{addresses-and-ports}
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
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
will proxy requests to a upstream configuration, which will handle
requests with two servers.
-@example
+@lisp
(service
nginx-service-type
(nginx-configuration
(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
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
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"
(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.
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")
(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
@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
(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
@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
A typical hpcguix-web service declaration looks like this:
-@example
+@lisp
(service hpcguix-web-service-type
(hpcguix-web-configuration
(specs
(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
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"
(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
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
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
the @code{"custom-packages"} input, which is the equivalent of
@code{GUIX_PACKAGE_PATH}.
-@example
+@lisp
(define %cuirass-specs
#~(list
'((#:name . "my-manifest")
(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
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
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}
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)
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
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
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:
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
(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}
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.
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
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
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
@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
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
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
@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
The following is an example @code{dicod-service} configuration.
-@example
+@lisp
(dicod-service #:config
(dicod-configuration
(handlers (list (dicod-handler
(handler "wordnet")
(options '("database=wn")))
%dicod-database:gcide))))
-@end example
+@end lisp
@cindex Docker
@subsubheading Docker Service
@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)
(services (append (list (service nix-service-type))
%base-services)))
-@end example
+@end lisp
After @command{guix system reconfigure} configure Nix for your user:
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
;; 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
(@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
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.
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
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.
@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
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
(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
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)
(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:
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.
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.
The service type for an @emph{extensible} service looks like this:
-@example
+@lisp
(define udev-service-type
(service-type (name 'udev)
(extensions
(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
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.
Here is an example of how a service is created and manipulated:
-@example
+@lisp
(define s
(service nginx-service-type
(nginx-configuration
(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
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}
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.
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!")
(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:
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