Copyright @copyright{} 2016, 2017 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016 ng0@*
-Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017 Clément Lassieur@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
Copyright @copyright{} 2017 Marius Bakke@*
-Copyright @copyright{} 2017 Hartmut Goebel
+Copyright @copyright{} 2017 Hartmut Goebel@*
+Copyright @copyright{} 2017 Maxim Cournoyer@*
+Copyright @copyright{} 2017 Tobias Geerinckx-Rice
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
-* Database Services:: SQL databases.
+* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
* Monitoring Services:: Monitoring services.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
* Power management Services:: The TLP tool.
+* Audio Services:: The MPD.
+* Virtualization Services:: Virtualization services.
* Miscellaneous Services:: Other services.
Defining Services
@cindex security
@cindex digital signatures
@cindex substitutes, authorization thereof
+@cindex access control list (ACL), for substitutes
+@cindex ACL (access control list), for substitutes
To allow Guix to download substitutes from @code{hydra.gnu.org} or a
mirror thereof, you
must add its public key to the access control list (ACL) of archive
This indicates that substitutes from @code{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.
-Guix ignores substitutes that are not signed, or that are not signed by
-one of the keys listed in the ACL. It also detects and raises an error
-when attempting to use a substitute that has been tampered with.
+Guix detects and raises an error when attempting to use a substitute
+that has been tampered with. Likewise, it ignores substitutes that are
+not signed, or that are not signed by one of the keys listed in the ACL.
+
+There is one exception though: if an unauthorized server provides
+substitutes that are @emph{bit-for-bit identical} to those provided by
+an authorized server, then the unauthorized server becomes eligible for
+downloads. For example, assume we have chosen two substitute servers
+with this option:
+
+@example
+--substitute-urls="https://a.example.org https://b.example.org"
+@end example
+
+@noindent
+@cindex reproducible builds
+If the ACL contains only the key for @code{b.example.org}, and if
+@code{a.example.org} happens to serve the @emph{exact same} substitutes,
+then Guix will download substitutes from @code{a.example.org} because it
+comes first in the list and can be considered a mirror of
+@code{b.example.org}. In practice, independent build machines usually
+produce the same binaries, thanks to bit-reproducible builds (see
+below).
@vindex http_proxy
Substitutes are downloaded over HTTP or HTTPS.
@item --compression=@var{tool}
@itemx -C @var{tool}
Compress the resulting tarball using @var{tool}---one of @code{gzip},
-@code{bzip2}, @code{xz}, or @code{lzip}.
+@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
@item --symlink=@var{spec}
@itemx -S @var{spec}
Sort lines according to @var{key}, one of the following options:
@table @code
-@item closure
-the total size of the item's closure (the default);
@item self
-the size of each item.
+the size of each item (the default);
+@item closure
+the total size of the item's closure.
@end table
@item --map-file=@var{file}
* Limitations:: What you can expect.
* Hardware Considerations:: Supported hardware.
* USB Stick Installation:: Preparing the installation medium.
+* DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
* Installing GuixSD in a VM:: GuixSD playground.
@subsection USB Stick Installation
An installation image for USB sticks can be downloaded from
-@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz},
where @var{system} is one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
-$ gpg --verify guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.xz.sig
@end example
If that command fails because you do not have the required public key,
and rerun the @code{gpg --verify} command.
@c end duplication
-This image contains a single partition with the tools necessary for an
-installation. It is meant to be copied @emph{as is} to a large-enough
-USB stick.
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
To copy the image to a USB stick, follow these steps:
Decompress the image using the @command{xz} command:
@example
-xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
+xz -d guixsd-install-@value{VERSION}.@var{system}.xz
@end example
@item
copy the image with:
@example
-dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
+dd if=guixsd-install-@value{VERSION}.x86_64 of=/dev/sdX
sync
@end example
@xref{Installing GuixSD in a VM}, if, instead, you would like to install
GuixSD in a virtual machine (VM).
+@node DVD Installation
+@subsection DVD Installation
+
+An installation image for DVDs can be downloaded from
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz},
+where @var{system} is one of:
+
+@table @code
+@item x86_64-linux
+for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+
+@item i686-linux
+for a 32-bit GNU/Linux system on Intel-compatible CPUs.
+@end table
+
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
+@example
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.xz.sig
+@end example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
+@example
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
+
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
+
+To copy the image to a DVD, follow these steps:
+
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
+
+@example
+xz -d guixsd-install-@value{VERSION}.@var{system}.xz
+@end example
+
+@item
+Insert a blank DVD into your machine, and determine
+its device name. Assuming that the DVD drive is known as @file{/dev/srX},
+copy the image with:
+
+@example
+growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64
+@end example
+
+Access to @file{/dev/srX} usually requires root privileges.
+@end enumerate
+
+Once this is done, you should be able to reboot the system and boot from
+the DVD. The latter usually requires you to get in the BIOS or
+UEFI boot menu, where you can choose to boot from the DVD.
+
+@xref{Installing GuixSD in a VM}, if, instead, you would like to install
+GuixSD in a virtual machine (VM).
+
@node Preparing for Installation
@subsection Preparing for Installation
-Once you have successfully booted the image on the USB stick, you should
-end up with a root prompt. Several console TTYs are configured and can
-be used to run commands as root. TTY2 shows this documentation,
+Once you have successfully booted your computer using the installation medium,
+you should end up with a root prompt. Several console TTYs are configured
+and can be used to run commands as root. TTY2 shows this documentation,
browsable using the Info reader commands (@pxref{Top,,, info-stnd,
Stand-alone GNU Info}). The installation system runs the GPM mouse
daemon, which allows you to select text with the left mouse button and
@itemize
@item
-Make sure the @code{grub-configuration} form refers to the device you
-want to install GRUB on. You also need to specify the @code{grub-efi}
-package if you wish to use native UEFI boot.
+Make sure the @code{grub-configuration} form refers to the target you
+want to install GRUB on. It should mention @code{grub-bootloader} if
+you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
+for newer UEFI systems. For legacy systems, the @code{target} field
+names a device, like @code{/dev/sda}; for UEFI systems it names a path
+to a mounted EFI partition, like @code{/boot/efi}, and do make sure the
+path is actually mounted.
@item
Be sure that your partition labels match the value of their respective
@example
qemu-system-x86_64 -m 1024 -smp 1 \
-net user -net nic,model=virtio -boot menu=on \
- -drive file=guixsd-usb-install-@value{VERSION}.@var{system} \
+ -drive file=guixsd-install-@value{VERSION}.@var{system} \
-drive file=guixsd.img
@end example
provides all the tools one would expect for basic user and administrator
tasks---including the GNU Core Utilities, the GNU Networking Utilities,
the GNU Zile lightweight text editor, @command{find}, @command{grep},
-etc. The example above adds tcpdump to those, taken from the @code{(gnu
-packages admin)} module (@pxref{Package Modules}). The
+etc. The example above adds GNU@tie{}Screen and OpenSSH to those,
+taken from the @code{(gnu packages screen)} and @code{(gnu packages ssh)}
+modules (@pxref{Package Modules}). The
@code{(list package output)} syntax can be used to add a specific output
of a package:
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
-* Database Services:: SQL databases.
+* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
* Monitoring Services:: Monitoring services.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
* Power management Services:: The TLP tool.
+* Audio Services:: The MPD.
+* Virtualization Services:: Virtualization services.
* Miscellaneous Services:: Other services.
@end menu
@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
service. The value for this service type is a
@code{network-manager-configuration} record.
+
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
@end defvr
@deftp {Data Type} network-manager-configuration
adds or adjusts services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), screen lockers,
-a network management tool (@pxref{Networking
-Services, @code{wicd-service}}), energy and color management services,
-the @code{elogind} login and seat manager, the Polkit privilege service,
-the GeoClue location service, an NTP client (@pxref{Networking
-Services}), the Avahi daemon, and has the name service switch service
-configured to be able to use @code{nss-mdns} (@pxref{Name Service
-Switch, mDNS}).
+@code{slim-service}}), screen lockers, a network management tool
+(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
+management services, the @code{elogind} login and seat manager, the
+Polkit privilege service, the GeoClue location service, the
+AccountsService daemon that allows authorized users change system
+passwords, an NTP client (@pxref{Networking Services}), the Avahi
+daemon, and has the name service switch service configured to be able to
+use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
@end defvr
The @var{%desktop-services} variable can be used as the @code{services}
@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
Return a service that runs the @code{elogind} login and
-seat management daemon. @uref{https://github.com/andywingo/elogind,
+seat management daemon. @uref{https://github.com/elogind/elogind,
Elogind} exposes a D-Bus interface that can be used to know which users
are logged in, know what kind of sessions they have open, suspend the
system, inhibit system suspend, reboot the system, and other tasks.
@end table
@end deffn
+@deffn {Scheme Procedure} accountsservice-service @
+ [#:accountsservice @var{accountsservice}]
+Return a service that runs AccountsService, a system service that can
+list available accounts, change their passwords, and so on.
+AccountsService integrates with PolicyKit to enable unprivileged users
+to acquire the capability to modify their system configuration.
+@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
+accountsservice web site} for more information.
+
+The @var{accountsservice} keyword argument is the @code{accountsservice}
+package to expose as a service.
+@end deffn
+
@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the
web site} for more information.
@end deffn
-@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}]
-Return a service that runs the @command{bluetoothd} daemon, which manages
-all the Bluetooth devices and provides a number of D-Bus interfaces.
+@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
+ [@w{#:auto-enable? #f}]
+Return a service that runs the @command{bluetoothd} daemon, which
+manages all the Bluetooth devices and provides a number of D-Bus
+interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
+powered automatically at boot, which can be useful when using a
+bluetooth keyboard or mouse.
Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn
The @code{(gnu services web)} module provides the nginx web server and
also a fastcgi wrapper daemon.
-@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
- [#:log-directory ``/var/log/nginx''] @
- [#:run-directory ``/var/run/nginx''] @
- [#:server-list '()] @
- [#:upstream-list '()] @
- [#:config-file @code{#f}]
-
-Return a service that runs @var{nginx}, the nginx web server.
-
-The nginx daemon loads its runtime configuration from @var{config-file}.
-Log files are written to @var{log-directory} and temporary runtime data
-files are written to @var{run-directory}. For proper operation, these
-arguments should match what is in @var{config-file} to ensure that the
-directories are created when the service is activated.
-
-As an alternative to using a @var{config-file}, @var{server-list} can be
-used to specify the list of @dfn{server blocks} required on the host and
-@var{upstream-list} can be used to specify a list of @dfn{upstream
-blocks} to configure. For this to work, use the default value for
-@var{config-file}.
-
-At startup, @command{nginx} has not yet read its configuration file, so it
-uses a default file to log error messages. If it fails to load its
-configuration file, that is where error messages are logged. After the
-configuration file is loaded, the default error log file changes as per
-configuration. In our case, startup error messages can be found in
-@file{/var/run/nginx/logs/error.log}, and after configuration in
-@file{/var/log/nginx/error.log}. The second location can be changed with the
-@var{log-directory} configuration option.
+@deffn {Scheme Variable} nginx-service-type
+Service type for the @uref{https://nginx.org/,NGinx} web server. The
+value for this service type is a @code{<nginx-configuration>} record.
-@end deffn
+A simple example configuration is given below.
-@deffn {Scheme Variable} nginx-service-type
-This is type for the nginx web server.
+@example
+(service nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f))))))
+@end example
-This service can be extended to add server blocks in addition to the
-default one, as in this example:
+In addition to adding server blocks to the service configuration
+directly, this service can be extended by other services to add server
+blocks, as in this example:
@example
(simple-service 'my-extra-server nginx-service-type
(list (nginx-server-configuration
(https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f)
(root "/srv/http/extra-website"))))
@end example
@end deffn
+At startup, @command{nginx} has not yet read its configuration file, so
+it uses a default file to log error messages. If it fails to load its
+configuration file, that is where error messages are logged. After the
+configuration file is loaded, the default error log file changes as per
+configuration. In our case, startup error messages can be found in
+@file{/var/run/nginx/logs/error.log}, and after configuration in
+@file{/var/log/nginx/error.log}. The second location can be changed
+with the @var{log-directory} configuration option.
+
+@deffn {Data Type} nginx-configuration
+This data type represents the configuration for NGinx. Some
+configuration can be done through this and the other provided record
+types, or alternatively, a config file can be provided.
+
+@table @asis
+@item @code{nginx} (default: @code{nginx})
+The nginx package to use.
+
+@item @code{log-directory} (default: @code{"/var/log/nginx"})
+The directory to which NGinx will write log files.
+
+@item @code{run-directory} (default: @code{"/var/run/nginx"})
+The directory in which NGinx will create a pid file, and write temporary
+files.
+
+@item @code{server-blocks} (default: @code{'()})
+A list of @dfn{server blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-server-configuration>}.
+
+The following example would setup NGinx to serve @code{www.example.com}
+from the @code{/srv/http/www.example.com} directory, without using
+HTTPS.
+@example
+(service nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f))))))
+@end example
+
+@item @code{upstream-blocks} (default: @code{'()})
+A list of @dfn{upstream blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-upstream-configuration>}.
+
+Configuring upstreams through the @code{upstream-blocks} can be useful
+when combined with @code{locations} in the
+@code{<nginx-server-configuration>} records. The following example
+creates a server configuration with one location configuration, that
+will proxy requests to a upstream configuration, which will handle
+requests with two servers.
+
+@example
+(service
+ nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f)
+ (locations
+ (list
+ (nginx-location-configuration
+ (uri "/path1")
+ (body '("proxy_pass http://server-proxy;"))))))))
+ (upstream-blocks
+ (list (nginx-upstream-configuration
+ (name "server-proxy")
+ (servers (list "server1.example.com"
+ "server2.example.com")))))))
+@end example
+
+@item @code{file} (default: @code{#f})
+If a configuration @var{file} is provided, this will be used, rather than
+generating a configuration file from the provided @code{log-directory},
+@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
+proper operation, these arguments should match what is in @var{file} to ensure
+that the directories are created when the service is activated.
+
+This can be useful if you have an existing configuration file, or it's
+not possible to do what is required through the other parts of the
+nginx-configuration record.
+
+@end table
+@end deffn
+
@deftp {Data Type} nginx-server-configuration
Data type representing the configuration of an nginx server block.
This type has the following parameters:
(#:branch . "master"))))
(service cuirass-service-type
(cuirass-configuration
- (specifications #~(list #$spec)))))
+ (specifications #~(list '#$spec)))))
@end example
While information related to build jobs is located directly in the
Location of sqlite database which contains the build results and previously
added specifications.
-@item @code{port} (default: @code{8080})
+@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
@item @code{specifications} (default: @code{#~'()})
@end table
@end deftp
+@node Audio Services
+@subsubsection Audio Services
+
+The @code{(gnu services audio)} module provides a service to start MPD
+(the Music Player Daemon).
+
+@cindex mpd
+@subsubheading Music Player Daemon
+
+The Music Player Daemon (MPD) is a service that can play music while
+being controlled from the local machine or over the network by a variety
+of clients.
+
+The following example shows how one might run @code{mpd} as user
+@code{"bob"} on port @code{6666}. It uses pulseaudio for output.
+
+@example
+(service mpd-service-type
+ (mpd-configuration
+ (user "bob")
+ (port "6666")))
+@end example
+
+@defvr {Scheme Variable} mpd-service-type
+The service type for @command{mpd}
+@end defvr
+
+@deftp {Data Type} mpd-configuration
+Data type representing the configuration of @command{mpd}.
+
+@table @asis
+@item @code{user} (default: @code{"mpd"})
+The user to run mpd as.
+
+@item @code{music-dir} (default: @code{"~/Music"})
+The directory to scan for music files.
+
+@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
+The directory to store playlists.
+
+@item @code{port} (default: @code{"6600"})
+The port to run mpd on.
+
+@item @code{address} (default: @code{"any"})
+The address that mpd will bind to. To use a Unix domain socket,
+an absolute path can be specified here.
+
+@end table
+@end deftp
+
+@node Virtualization Services
+@subsubsection Virtualization services
+The @code{(gnu services virtualization)} module provides services for
+the libvirt and virtlog daemons.
+
+@subsubheading Libvirt daemon
+@code{libvirtd} is the server side daemon component of the libvirt
+virtualization management system. This daemon runs on host servers
+and performs required management tasks for virtualized guests.
+
+@deffn {Scheme Variable} libvirt-service-type
+This is the type of the @uref{https://libvirt.org, libvirt daemon}.
+Its value must be a @code{libvirt-configuration}.
+
+@example
+(service libvirt-service-type
+ (libvirt-configuration
+ (unix-sock-group "libvirt")
+ (tls-port "16555")))
+@end example
+@end deffn
+
+@c Auto-generated with (generate-libvirt-documentation)
+Available @code{libvirt-configuration} fields are:
+
+@deftypevr {@code{libvirt-configuration} parameter} package libvirt
+Libvirt package.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
+Flag listening for secure TLS connections on the public TCP/IP port.
+must set @code{listen} for this to have any effect.
+
+It is necessary to setup a CA and issue server certificates before using
+this capability.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
+Listen for unencrypted TCP connections on the public TCP/IP port. must
+set @code{listen} for this to have any effect.
+
+Using the TCP socket requires SASL authentication by default. Only SASL
+mechanisms which support data encryption are allowed. This is
+DIGEST_MD5 and GSSAPI (Kerberos5)
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tls-port
+Port for accepting secure TLS connections This can be a port number, or
+service name
+
+Defaults to @samp{"16514"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tcp-port
+Port for accepting insecure TCP connections This can be a port number,
+or service name
+
+Defaults to @samp{"16509"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string listen-addr
+IP address or hostname used for client connections.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
+Flag toggling mDNS advertisement of the libvirt service.
+
+Alternatively can disable for all services on a host by stopping the
+Avahi daemon.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string mdns-name
+Default mDNS advertisement name. This must be unique on the immediate
+broadcast network.
+
+Defaults to @samp{"Virtualization Host <hostname>"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
+UNIX domain socket group ownership. This can be used to allow a
+'trusted' set of users access to management capabilities without
+becoming root.
+
+Defaults to @samp{"root"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
+UNIX socket permissions for the R/O socket. This is used for monitoring
+VM status only.
+
+Defaults to @samp{"0777"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
+UNIX socket permissions for the R/W socket. Default allows only root.
+If PolicyKit is enabled on the socket, the default will change to allow
+everyone (eg, 0777)
+
+Defaults to @samp{"0770"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
+UNIX socket permissions for the admin socket. Default allows only owner
+(root), do not change it unless you are sure to whom you are exposing
+the access to.
+
+Defaults to @samp{"0777"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
+The directory in which sockets will be found/created.
+
+Defaults to @samp{"/var/run/libvirt"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
+Authentication scheme for UNIX read-only sockets. By default socket
+permissions allow anyone to connect
+
+Defaults to @samp{"polkit"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
+Authentication scheme for UNIX read-write sockets. By default socket
+permissions only allow root. If PolicyKit support was compiled into
+libvirt, the default will be to use 'polkit' auth.
+
+Defaults to @samp{"polkit"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
+Authentication scheme for TCP sockets. If you don't enable SASL, then
+all TCP traffic is cleartext. Don't do this outside of a dev/test
+scenario.
+
+Defaults to @samp{"sasl"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-tls
+Authentication scheme for TLS sockets. TLS sockets already have
+encryption provided by the TLS layer, and limited authentication is done
+by certificates.
+
+It is possible to make use of any SASL authentication mechanism as well,
+by using 'sasl' for this option
+
+Defaults to @samp{"none"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
+API access control scheme.
+
+By default an authenticated user is allowed access to all APIs. Access
+drivers can place restrictions on this.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string key-file
+Server key file path. If set to an empty string, then no private key is
+loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string cert-file
+Server key file path. If set to an empty string, then no certificate is
+loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string ca-file
+Server key file path. If set to an empty string, then no CA certificate
+is loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string crl-file
+Certificate revocation list path. If set to an empty string, then no
+CRL is loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
+Disable verification of our own server certificates.
+
+When libvirtd starts it performs some sanity checks against its own
+certificates.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
+Disable verification of client certificates.
+
+Client certificate verification is the primary authentication mechanism.
+Any client which does not present a certificate signed by the CA will be
+rejected.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
+Whitelist of allowed x509 Distinguished Name.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
+Whitelist of allowed SASL usernames. The format for username depends on
+the SASL authentication mechanism.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tls-priority
+Override the compile time default TLS priority string. The default is
+usually "NORMAL" unless overridden at build time. Only set this is it
+is desired for libvirt to deviate from the global default settings.
+
+Defaults to @samp{"NORMAL"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-clients
+Maximum number of concurrent client connections to allow over all
+sockets combined.
+
+Defaults to @samp{5000}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
+Maximum length of queue of connections waiting to be accepted by the
+daemon. Note, that some protocols supporting retransmission may obey
+this so that a later reattempt at connection succeeds.
+
+Defaults to @samp{1000}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
+Maximum length of queue of accepted but not yet authenticated clients.
+Set this to zero to turn this feature off
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer min-workers
+Number of workers to start up initially.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-workers
+Maximum number of worker threads.
+
+If the number of active clients exceeds @code{min-workers}, then more
+threads are spawned, up to max_workers limit. Typically you'd want
+max_workers to equal maximum number of clients allowed.
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
+Number of priority workers. If all workers from above pool are stuck,
+some calls marked as high priority (notably domainDestroy) can be
+executed in this pool.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-requests
+Total global limit on concurrent RPC calls.
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
+Limit on concurrent requests from a single client connection. To avoid
+one client monopolizing the server this should be a small fraction of
+the global max_requests and max_workers parameter.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
+Same as @code{min-workers} but for the admin interface.
+
+Defaults to @samp{1}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
+Same as @code{max-workers} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
+Same as @code{max-clients} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
+Same as @code{max-queued-clients} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
+Same as @code{max-client-requests} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer log-level
+Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
+
+Defaults to @samp{3}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string log-filters
+Logging filters.
+
+A filter allows to select a different logging level for a given category
+of logs The format for a filter is one of:
+
+@itemize @bullet
+@item
+x:name
+
+@item
+x:+name
+
+@end itemize
+
+where @code{name} is a string which is matched against the category
+given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
+file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
+be a substring of the full category name, in order to match multiple
+similar categories), the optional "+" prefix tells libvirt to log stack
+trace for each message matching name, and @code{x} is the minimal level
+where matching messages should be logged:
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple filters can be defined in a single filters statement, they just
+need to be separated by spaces.
+
+Defaults to @samp{"3:remote 4:event"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string log-outputs
+Logging outputs.
+
+An output is one of the places to save logging information The format
+for an output can be:
+
+@table @code
+@item x:stderr
+output goes to stderr
+
+@item x:syslog:name
+use syslog for the output and use the given name as the ident
+
+@item x:file:file_path
+output to a file, with the given filepath
+
+@item x:journald
+output to journald logging system
+
+@end table
+
+In all case the x prefix is the minimal level, acting as a filter
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple outputs can be defined, they just need to be separated by
+spaces.
+
+Defaults to @samp{"3:stderr"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer audit-level
+Allows usage of the auditing subsystem to be altered
+
+@itemize @bullet
+@item
+0: disable all auditing
+
+@item
+1: enable auditing, only if enabled on host
+
+@item
+2: enable auditing, and exit if disabled on host.
+
+@end itemize
+
+Defaults to @samp{1}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
+Send audit messages via libvirt logging infrastructure.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
+Host UUID. UUID must not have all digits be the same.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
+Source to read host UUID.
+
+@itemize @bullet
+@item
+@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
+
+@item
+@code{machine-id}: fetch the UUID from @code{/etc/machine-id}
+
+@end itemize
+
+If @code{dmidecode} does not provide a valid UUID a temporary UUID will
+be generated.
+
+Defaults to @samp{"smbios"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
+A keepalive message is sent to a client after @code{keepalive_interval}
+seconds of inactivity to check if the client is still responding. If
+set to -1, libvirtd will never send keepalive requests; however clients
+can still send them and the daemon will send responses.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
+Maximum number of keepalive messages that are allowed to be sent to the
+client without getting any response before the connection is considered
+broken.
+
+In other words, the connection is automatically closed approximately
+after @code{keepalive_interval * (keepalive_count + 1)} seconds since
+the last message received from the client. When @code{keepalive-count}
+is set to 0, connections will be automatically closed after
+@code{keepalive-interval} seconds of inactivity without sending any
+keepalive messages.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
+Same as above but for admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
+Same as above but for admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
+Timeout for Open vSwitch calls.
+
+The @code{ovs-vsctl} utility is used for the configuration and its
+timeout option is set by default to 5 seconds to avoid potential
+infinite waits blocking libvirt.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@c %end of autogenerated docs
+
+@subsubheading Virtlog daemon
+The virtlogd service is a server side daemon component of libvirt that is
+used to manage logs from virtual machine consoles.
+
+This daemon is not used directly by libvirt client applications, rather it
+is called on their behalf by @code{libvirtd}. By maintaining the logs in a
+standalone daemon, the main @code{libvirtd} daemon can be restarted without
+risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
+itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
+
+@deffn {Scheme Variable} virtlog-service-type
+This is the type of the virtlog daemon.
+Its value must be a @code{virtlog-configuration}.
+
+@example
+(service virtlog-service-type
+ (virtlog-configuration
+ (max-clients 1000)))
+@end example
+@end deffn
+
+@deftypevr {@code{virtlog-configuration} parameter} integer log-level
+Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
+
+Defaults to @samp{3}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} string log-filters
+Logging filters.
+
+A filter allows to select a different logging level for a given category
+of logs The format for a filter is one of:
+
+@itemize @bullet
+@item
+x:name
+
+@item
+x:+name
+
+@end itemize
+
+where @code{name} is a string which is matched against the category
+given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
+file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
+be a substring of the full category name, in order to match multiple
+similar categories), the optional "+" prefix tells libvirt to log stack
+trace for each message matching name, and @code{x} is the minimal level
+where matching messages should be logged:
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple filters can be defined in a single filters statement, they just
+need to be separated by spaces.
+
+Defaults to @samp{"3:remote 4:event"}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} string log-outputs
+Logging outputs.
+
+An output is one of the places to save logging information The format
+for an output can be:
+
+@table @code
+@item x:stderr
+output goes to stderr
+
+@item x:syslog:name
+use syslog for the output and use the given name as the ident
+
+@item x:file:file_path
+output to a file, with the given filepath
+
+@item x:journald
+output to journald logging system
+
+@end table
+
+In all case the x prefix is the minimal level, acting as a filter
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple outputs can be defined, they just need to be separated by
+spaces.
+
+Defaults to @samp{"3:stderr"}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-clients
+Maximum number of concurrent client connections to allow over all
+sockets combined.
+
+Defaults to @samp{1024}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-size
+Maximum file size before rolling over.
+
+Defaults to @samp{2MB}
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-backups
+Maximum number of backup files to keep.
+
+Defaults to @samp{3}
+
+@end deftypevr
+
@node Miscellaneous Services
@subsubsection Miscellaneous Services
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules.
-@item @code{device}
-This is a string denoting the boot device. It must be a device name
-understood by the bootloader @command{installer} command, such as
-@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking grub-install,,, grub,
-GNU GRUB Manual}).
+@item @code{target}
+This is a string denoting the target onto which to install the
+bootloader. The exact interpretation depends on the bootloader in
+question; for @code{grub-bootloader}, for example, it should be a device
+name understood by the bootloader @command{installer} command, such as
+@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking
+grub-install,,, grub, GNU GRUB Manual}). For
+@code{grub-efi-bootloader}, it should be the path to a mounted EFI file
+system.
@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
-This command also installs bootloader on the device specified in
+This command also installs bootloader on the target specified in
@file{my-os-config}, unless the @option{--no-bootloader} option was
passed.
HCoop / jackhill / guix / guix.git / blobdiff