The (gnu services virtualization) module provides services for the
libvirt and virtlog daemons, as well as other virtualization-related
services.
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. To connect to
the libvirt daemon as an unprivileged user, it must be added to the
‘libvirt’ group, as shown in the example below.
This is the type of the libvirt daemon. Its
value must be a libvirt-configuration.
(users (cons (user-account (name "user") (group "users") (supplementary-groups '("libvirt" "audio" "video" "wheel"))) %base-user-accounts)) (service libvirt-service-type (libvirt-configuration (tls-port "16555")))
Available libvirt-configuration fields are:
libvirt-configuration parameter: package libvirt ¶Libvirt package.
libvirt-configuration parameter: boolean listen-tls? ¶Flag listening for secure TLS connections on the public TCP/IP port. You
must set listen for this to have any effect.
It is necessary to setup a CA and issue server certificates before using this capability.
Defaults to ‘#t’.
libvirt-configuration parameter: boolean listen-tcp? ¶Listen for unencrypted TCP connections on the public TCP/IP port. You must
set 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 ‘#f’.
libvirt-configuration parameter: string tls-port ¶Port for accepting secure TLS connections. This can be a port number, or service name.
Defaults to ‘"16514"’.
libvirt-configuration parameter: string tcp-port ¶Port for accepting insecure TCP connections. This can be a port number, or service name.
Defaults to ‘"16509"’.
libvirt-configuration parameter: string listen-addr ¶IP address or hostname used for client connections.
Defaults to ‘"0.0.0.0"’.
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 ‘#f’.
libvirt-configuration parameter: string mdns-name ¶Default mDNS advertisement name. This must be unique on the immediate broadcast network.
Defaults to ‘"Virtualization Host <hostname>"’.
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 ‘"libvirt"’.
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 ‘"0777"’.
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 ‘"0770"’.
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 ‘"0777"’.
libvirt-configuration parameter: string unix-sock-dir ¶The directory in which sockets will be found/created.
Defaults to ‘"/var/run/libvirt"’.
libvirt-configuration parameter: string auth-unix-ro ¶Authentication scheme for UNIX read-only sockets. By default socket permissions allow anyone to connect
Defaults to ‘"polkit"’.
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 ‘"polkit"’.
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 ‘"sasl"’.
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 ‘"none"’.
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 ‘'()’.
libvirt-configuration parameter: string key-file ¶Server key file path. If set to an empty string, then no private key is loaded.
Defaults to ‘""’.
libvirt-configuration parameter: string cert-file ¶Server key file path. If set to an empty string, then no certificate is loaded.
Defaults to ‘""’.
libvirt-configuration parameter: string ca-file ¶Server key file path. If set to an empty string, then no CA certificate is loaded.
Defaults to ‘""’.
libvirt-configuration parameter: string crl-file ¶Certificate revocation list path. If set to an empty string, then no CRL is loaded.
Defaults to ‘""’.
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 ‘#f’.
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 ‘#f’.
libvirt-configuration parameter: optional-list tls-allowed-dn-list ¶Whitelist of allowed x509 Distinguished Name.
Defaults to ‘'()’.
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 ‘'()’.
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 ‘"NORMAL"’.
libvirt-configuration parameter: integer max-clients ¶Maximum number of concurrent client connections to allow over all sockets combined.
Defaults to ‘5000’.
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 ‘1000’.
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 ‘20’.
libvirt-configuration parameter: integer min-workers ¶Number of workers to start up initially.
Defaults to ‘5’.
libvirt-configuration parameter: integer max-workers ¶Maximum number of worker threads.
If the number of active clients exceeds 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 ‘20’.
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 ‘5’.
libvirt-configuration parameter: integer max-requests ¶Total global limit on concurrent RPC calls.
Defaults to ‘20’.
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 ‘5’.
libvirt-configuration parameter: integer admin-min-workers ¶Same as min-workers but for the admin interface.
Defaults to ‘1’.
libvirt-configuration parameter: integer admin-max-workers ¶Same as max-workers but for the admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer admin-max-clients ¶Same as max-clients but for the admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer admin-max-queued-clients ¶Same as max-queued-clients but for the admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer admin-max-client-requests ¶Same as max-client-requests but for the admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer log-level ¶Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
Defaults to ‘3’.
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:
where name is a string which is matched against the category given in
the 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 x is the
minimal level where matching messages should be logged:
Multiple filters can be defined in a single filters statement, they just need to be separated by spaces.
Defaults to ‘"3:remote 4:event"’.
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:
x:stderroutput goes to stderr
x:syslog:nameuse syslog for the output and use the given name as the ident
x:file:file_pathoutput to a file, with the given filepath
x:journaldoutput to journald logging system
In all case the x prefix is the minimal level, acting as a filter
Multiple outputs can be defined, they just need to be separated by spaces.
Defaults to ‘"3:stderr"’.
libvirt-configuration parameter: integer audit-level ¶Allows usage of the auditing subsystem to be altered
Defaults to ‘1’.
libvirt-configuration parameter: boolean audit-logging ¶Send audit messages via libvirt logging infrastructure.
Defaults to ‘#f’.
libvirt-configuration parameter: optional-string host-uuid ¶Host UUID. UUID must not have all digits be the same.
Defaults to ‘""’.
libvirt-configuration parameter: string host-uuid-source ¶Source to read host UUID.
smbios: fetch the UUID from dmidecode -s system-uuid
machine-id: fetch the UUID from /etc/machine-id
If dmidecode does not provide a valid UUID a temporary UUID will be
generated.
Defaults to ‘"smbios"’.
libvirt-configuration parameter: integer keepalive-interval ¶A keepalive message is sent to a client after 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 ‘5’.
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
keepalive_interval * (keepalive_count + 1) seconds since the last
message received from the client. When keepalive-count is set to 0,
connections will be automatically closed after keepalive-interval
seconds of inactivity without sending any keepalive messages.
Defaults to ‘5’.
libvirt-configuration parameter: integer admin-keepalive-interval ¶Same as above but for admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer admin-keepalive-count ¶Same as above but for admin interface.
Defaults to ‘5’.
libvirt-configuration parameter: integer ovs-timeout ¶Timeout for Open vSwitch calls.
The 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 ‘5’.
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 libvirtd. By maintaining the logs in a
standalone daemon, the main libvirtd daemon can be restarted without
risk of losing logs. The virtlogd daemon has the ability to
re-exec() itself upon receiving SIGUSR1, to allow live upgrades
without downtime.
This is the type of the virtlog daemon. Its value must be a
virtlog-configuration.
(service virtlog-service-type
(virtlog-configuration
(max-clients 1000)))
libvirt parameter: package libvirt ¶Libvirt package.
virtlog-configuration parameter: integer log-level ¶Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
Defaults to ‘3’.
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:
where name is a string which is matched against the category given in
the 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 x is the minimal level where matching messages
should be logged:
Multiple filters can be defined in a single filters statement, they just need to be separated by spaces.
Defaults to ‘"3:remote 4:event"’.
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:
x:stderroutput goes to stderr
x:syslog:nameuse syslog for the output and use the given name as the ident
x:file:file_pathoutput to a file, with the given filepath
x:journaldoutput to journald logging system
In all case the x prefix is the minimal level, acting as a filter
Multiple outputs can be defined, they just need to be separated by spaces.
Defaults to ‘"3:stderr"’.
virtlog-configuration parameter: integer max-clients ¶Maximum number of concurrent client connections to allow over all sockets combined.
Defaults to ‘1024’.
virtlog-configuration parameter: integer max-size ¶Maximum file size before rolling over.
Defaults to ‘2MB’
virtlog-configuration parameter: integer max-backups ¶Maximum number of backup files to keep.
Defaults to ‘3’
qemu-binfmt-service-type provides support for transparent emulation
of program binaries built for different architectures—e.g., it allows you
to transparently execute an ARMv7 program on an x86_64 machine. It achieves
this by combining the QEMU emulator and the
binfmt_misc feature of the kernel Linux. This feature only allows
you to emulate GNU/Linux on a different architecture, but see below for
GNU/Hurd support.
This is the type of the QEMU/binfmt service for transparent emulation. Its
value must be a qemu-binfmt-configuration object, which specifies the
QEMU package to use as well as the architecture we want to emulated:
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
(platforms (lookup-qemu-platforms "arm" "aarch64"))))
In this example, we enable transparent emulation for the ARM and aarch64
platforms. Running herd stop qemu-binfmt turns it off, and running
herd start qemu-binfmt turns it back on (see the
herd command in The GNU Shepherd Manual).
This is the configuration for the qemu-binfmt service.
platforms (default: '())The list of emulated QEMU platforms. Each item must be a platform
object as returned by lookup-qemu-platforms (see below).
For example, let’s suppose you’re on an x86_64 machine and you have this service:
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
(platforms (lookup-qemu-platforms "arm"))))
You can run:
guix build -s armhf-linux inkscape
and it will build Inkscape for ARMv7 as if it were a native build, transparently using QEMU to emulate the ARMv7 CPU. Pretty handy if you’d like to test a package build for an architecture you don’t have access to!
qemu (default: qemu)The QEMU package to use.
Return the list of QEMU platform objects corresponding to
platforms…. platforms must be a list of strings
corresponding to platform names, such as "arm", "sparc",
"mips64el", and so on.
Return true if obj is a platform object.
Return the name of platform—a string such as "arm".
The QEMU guest agent provides control over the emulated system to the host.
The qemu-guest-agent service runs the agent on Guix guests. To
control the agent from the host, open a socket by invoking QEMU with the
following arguments:
qemu-system-x86_64 \ -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \ -device virtio-serial \ -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \ ...
This creates a socket at /tmp/qga.sock on the host. Once the guest
agent is running, you can issue commands with socat:
$ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
{"execute": "guest-get-host-name"}
{"return": {"host-name": "guix"}}
See QEMU guest agent documentation for more options and commands.
Service type for the QEMU guest agent service.
Configuration for the qemu-guest-agent service.
qemu (default: qemu-minimal)The QEMU package to use.
device (default: "")File name of the device or socket the agent uses to communicate with the host. If empty, QEMU uses a default file name.
Virtual build machines or “build VMs” let you offload builds to a fully controlled environment. “How can it be more controlled than regular builds? And why would it be useful?”, you ask. Good questions.
Builds spawned by guix-daemon indeed run in a controlled environment;
specifically the daemon spawns build processes in separate namespaces and in
a chroot, such as that build processes only see their declared dependencies
and a well-defined subset of the file system tree (see 设置构建环境, for details). A few aspects of the environments are not controlled
though: the operating system kernel, the CPU model, and the date. Most of
the time, these aspects have no impact on the build process: the level of
isolation guix-daemon provides is “good enough”.
However, there are occasionally cases where those aspects do influence the build process. A typical example is time traps: build processes that stop working after a certain date35. Another one is software that optimizes for the CPU microarchitecture it is built on or, worse, bugs that manifest only on specific CPUs.
To address that, virtual-build-machine-service-type lets you add a
virtual build machine on your system, as in this example:
(use-modules (gnu services virtualization)) (operating-system ;; … (services (append (list (service virtual-build-machine-service-type)) %base-services)))
By default, you have to explicitly start the build machine when you need it, at which point builds may be offloaded to it (see 使用任务下发设施):
herd start build-vm
With the default setting shown above, the build VM runs with its clock set to a date several years in the past, and on a CPU model that corresponds to that date—a model possibly older than that of your machine. This lets you rebuild today software from the past that would otherwise fail to build due to a time trap or other issues in its build process. You can view the VM’s config like this:
herd configuration build-vm
You can configure the build VM, as in this example:
(service virtual-build-machine-service-type
(virtual-build-machine
(cpu "Westmere")
(cpu-count 8)
(memory-size (* 1 1024))
(auto-start? #t)))
The available options are shown below.
This is the service type to run virtual build machines. Virtual build machines are configured so that builds are offloaded to them when they are running.
This is the data type specifying the configuration of a build machine. It contains the fields below:
name (default: 'build-vm)The name of this build VM. It is used to construct the name of its Shepherd service.
映像The image of the virtual machine (see 创建系统镜像). This notably
specifies the virtual disk size and the operating system running into it
(see operating-system Reference). The default value is a minimal
operating system image.
qemu (default: qemu-minimal)The QEMU package to run the image.
cpuThe CPU model being emulated as a string denoting a model known to QEMU.
The default value is a model that matches date (see below). To see
what CPU models are available, run, for example:
qemu-system-x86_64 -cpu help
cpu-count (default: 4)The number of CPUs emulated by the virtual machine.
memory-size (default: 2048)Size in mebibytes (MiB) of the virtual machine’s main memory (RAM).
date (default: a few years ago)Date inside the virtual machine when it starts; this must be a SRFI-19 date object (see SRFI-19 Date in GNU Guile Reference Manual).
port-forwardings (default: 11022 and 11004)TCP ports of the virtual machine forwarded to the host. By default, the SSH and secrets ports are forwarded into the host.
systems (default: (list (%current-system)))List of system types supported by the build VM—e.g.,
"x86_64-linux".
auto-start? (default: #f)Whether to start the virtual machine when the system boots.
In the next section, you’ll find a variant on this theme: GNU/Hurd virtual machines!
Service hurd-vm provides support for running GNU/Hurd in a virtual
machine (VM), a so-called childhurd. This service is meant to be used
on GNU/Linux and the given GNU/Hurd operating system configuration is
cross-compiled. The virtual machine is a Shepherd service that can be
referred to by the names hurd-vm and childhurd and be
controlled with commands such as:
herd start hurd-vm herd stop childhurd
When the service is running, you can view its console by connecting to it with a VNC client, for example with:
guix shell tigervnc-client -- vncviewer localhost:5900
The default configuration (see hurd-vm-configuration below) spawns a
secure shell (SSH) server in your GNU/Hurd system, which QEMU (the virtual
machine emulator) redirects to port 10022 on the host. By default, the
service enables offloading such that the host guix-daemon
automatically offloads GNU/Hurd builds to the childhurd (see 使用任务下发设施). This is what happens when running a command like the
following one, where i586-gnu is the system type of 32-bit GNU/Hurd:
guix build emacs-minimal -s i586-gnu
The childhurd is volatile and stateless: it starts with a fresh root file
system every time you restart it. By default though, all the files under
/etc/childhurd on the host are copied as is to the root file system
of the childhurd when it boots. This allows you to initialize “secrets”
inside the VM: SSH host keys, authorized substitute keys, and so on—see
the explanation of secret-root below.
You will probably find it useful to create an account for you in the
GNU/Hurd virtual machine and to authorize logins with your SSH key. To do
that, you can define the GNU/Hurd system in the usual way (see 使用配置系统), and then pass that operating system as the os
field of hurd-vm-configuration, as in this example:
(define childhurd-os ;; Definition of my GNU/Hurd system, derived from the default one. (operating-system (inherit %hurd-vm-operating-system) ;; Add a user account. (users (cons (user-account (name "charlie") (comment "This is me!") (group "users") (supplementary-groups '("wheel"))) ;for 'sudo' %base-user-accounts)) (services ;; Modify the SSH configuration to allow login as "root" ;; and as "charlie" using public key authentication. (modify-services (operating-system-user-services %hurd-vm-operating-system) (openssh-service-type config => (openssh-configuration (inherit config) (authorized-keys `(("root" ,(local-file "/home/charlie/.ssh/id_rsa.pub")) ("charlie" ,(local-file "/home/charlie/.ssh/id_rsa.pub")))))))))) (operating-system ;; … (services ;; Add the 'hurd-vm' service, configured to use the ;; operating system configuration above. (append (list (service hurd-vm-service-type (hurd-vm-configuration (os %childhurd-os)))) %base-services)))
That’s it! The remainder of this section provides the reference of the service configuration.
This is the type of the Hurd in a Virtual Machine service. Its value must
be a hurd-vm-configuration object, which specifies the operating
system (see operating-system Reference) and the disk size for the Hurd
Virtual Machine, the QEMU package to use as well as the options for running
it.
For example:
(service hurd-vm-service-type (hurd-vm-configuration (disk-size (* 5000 (expt 2 20))) ;5G (memory-size 1024))) ;1024MiB
would create a disk image big enough to build GNU Hello, with some extra memory.
The data type representing the configuration for
hurd-vm-service-type.
os (default: %hurd-vm-operating-system)The operating system to instantiate. This default is bare-bones with a
permissive OpenSSH secure shell daemon listening on port 2222
(see openssh-service-type).
qemu (default: qemu-minimal)The QEMU package to use.
image (default: hurd-vm-disk-image)The image object representing the disk image of this virtual machine (see 创建系统镜像).
disk-size (default: 'guess)The size of the disk image.
memory-size (default: 512)The memory size of the Virtual Machine in mebibytes.
options (default: '("--snapshot"))The extra options for running QEMU.
id (default: #f)If set, a non-zero positive integer used to parameterize Childhurd
instances. It is appended to the service’s name, e.g. childhurd1.
net-options (default: hurd-vm-net-options)The procedure used to produce the list of QEMU networking options.
By default, it produces
'("--device" "rtl8139,netdev=net0" "--netdev" (string-append "user,id=net0," "hostfwd=tcp:127.0.0.1:secrets-port-:1004," "hostfwd=tcp:127.0.0.1:ssh-port-:2222," "hostfwd=tcp:127.0.0.1:vnc-port-:5900"))
with forwarded ports:
secrets-port:(+ 11004 (* 1000 ID))ssh-port:(+ 10022 (* 1000 ID))vnc-port:(+ 15900 (* 1000 ID))
offloading? (default: #t)Whether to automatically set up offloading of builds to the childhurd.
When enabled, this lets you run GNU/Hurd builds on the host and have them transparently offloaded to the VM, for instance when running a command like this:
guix build coreutils -s i586-gnu
This option automatically sets up offloading like so:
guix archive --authorize, for more
on that).
offloading dedicated to offloading in
the childhurd.
offloading account in the childhurd.
secret-root (default: /etc/childhurd)The root directory with out-of-band secrets to be installed into the childhurd once it runs. Childhurds are volatile which means that on every startup, secrets such as the SSH host keys and Guix signing key are recreated.
If the /etc/childhurd directory does not exist, the
secret-service running in the Childhurd will be sent an empty list of
secrets.
By default, the service automatically populates /etc/childhurd with the following non-volatile secrets, unless they already exist:
/etc/childhurd/etc/guix/acl /etc/childhurd/etc/guix/signing-key.pub /etc/childhurd/etc/guix/signing-key.sec /etc/childhurd/etc/ssh/authorized_keys.d/offloading /etc/childhurd/etc/ssh/ssh_host_ed25519_key /etc/childhurd/etc/ssh/ssh_host_ecdsa_key /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
Note that by default the VM image is volatile, i.e., once stopped the
contents are lost. If you want a stateful image instead, override the
configuration’s image and options without the
--snapshot flag using something along these lines:
(service hurd-vm-service-type
(hurd-vm-configuration
(image (const "/out/of/store/writable/hurd.img"))
(options '())))
注: This service is considered experimental. Configuration options may be changed in a backwards-incompatible manner, and not all features have been thorougly tested. Users of this service are encouraged to share their experience at guix-devel@gnu.org.
Ganeti is a virtual machine management system. It is designed to keep
virtual machines running on a cluster of servers even in the event of
hardware failures, and to make maintenance and recovery tasks easy. It
consists of multiple services which are described later in this section. In
addition to the Ganeti service, you will need the OpenSSH service
(see openssh-service-type), and update the
/etc/hosts file (see hosts-service-type) with the cluster name and address (or use a DNS
server).
All nodes participating in a Ganeti cluster should have the same Ganeti and
/etc/hosts configuration. Here is an example configuration for a
Ganeti cluster node that supports multiple storage backends, and installs
the debootstrap and guix OS providers:
(use-package-modules virtualization) (use-service-modules base ganeti networking ssh) (operating-system ;; … (host-name "node1") ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph ;; in order to use the "plain", "drbd" and "rbd" storage backends. (packages (append (map specification->package '("qemu" "lvm2" "drbd-utils" "ceph" ;; Add the debootstrap and guix OS providers. "ganeti-instance-guix" "ganeti-instance-debootstrap")) %base-packages)) (services (append (list (service static-networking-service-type (list (static-networking (addresses (list (network-address (device "eth0") (value "192.168.1.201/24")))) (routes (list (network-route (destination "default") (gateway "192.168.1.254")))) (name-servers '("192.168.1.252" "192.168.1.253"))))) ;; Ganeti uses SSH to communicate between nodes. (service openssh-service-type (openssh-configuration (permit-root-login 'prohibit-password))) (simple-service 'ganeti-hosts-entries hosts-service-type (list (host "192.168.1.200" "ganeti.example.com") (host "192.168.1.201" "node1.example.com" '("node1")) (host "192.168.1.202" "node2.example.com" '("node2")))) (service ganeti-service-type (ganeti-configuration ;; This list specifies allowed file system paths ;; for storing virtual machine images. (file-storage-paths '("/srv/ganeti/file-storage")) ;; This variable configures a single "variant" for ;; both Debootstrap and Guix that works with KVM. (os %default-ganeti-os)))) %base-services)))
Users are advised to read the Ganeti administrators guide to learn about the various cluster options and day-to-day operations. There is also a blog post describing how to configure and initialize a small cluster.
This is a service type that includes all the various services that Ganeti nodes should run.
Its value is a ganeti-configuration object that defines the package
to use for CLI operations, as well as configuration for the various
daemons. Allowed file storage paths and available guest operating systems
are also configured through this data type.
The ganeti service takes the following configuration options:
ganeti (default: ganeti)The ganeti package to use. It will be installed to the system
profile and make gnt-cluster, gnt-instance, etc
available. Note that the value specified here does not affect the other
services as each refer to a specific ganeti package (see below).
noded-configuration (default: (ganeti-noded-configuration))confd-configuration (default: (ganeti-confd-configuration))wconfd-configuration (default: (ganeti-wconfd-configuration))luxid-configuration (default: (ganeti-luxid-configuration))rapi-configuration (default: (ganeti-rapi-configuration))kvmd-configuration (default: (ganeti-kvmd-configuration))mond-configuration (default: (ganeti-mond-configuration))metad-configuration (default: (ganeti-metad-configuration))watcher-configuration (default: (ganeti-watcher-configuration))cleaner-configuration (default: (ganeti-cleaner-configuration))These options control the various daemons and cron jobs that are distributed with Ganeti. The possible values for these are described in detail below. To override a setting, you must use the configuration type for that service:
(service ganeti-service-type
(ganeti-configuration
(rapi-configuration
(ganeti-rapi-configuration
(interface "eth1"))))
(watcher-configuration
(ganeti-watcher-configuration
(rapi-ip "10.0.0.1"))))
file-storage-paths (default: '())List of allowed directories for file storage backend.
hooks (default: #f)When set, this should be a file-like object containing a directory with cluster execution hooks.
os (default: %default-ganeti-os)List of <ganeti-os> records.
In essence ganeti-service-type is shorthand for declaring each
service individually:
(service ganeti-noded-service-type) (service ganeti-confd-service-type) (service ganeti-wconfd-service-type) (service ganeti-luxid-service-type) (service ganeti-kvmd-service-type) (service ganeti-mond-service-type) (service ganeti-metad-service-type) (service ganeti-watcher-service-type) (service ganeti-cleaner-service-type)
Plus a service extension for etc-service-type that configures the
file storage backend and OS variants.
This data type is suitable for passing to the os parameter of
ganeti-configuration. It takes the following parameters:
名字The name for this OS provider. It is only used to specify where the configuration ends up. Setting it to “debootstrap” will create /etc/ganeti/instance-debootstrap.
extension (default: #f)The file extension for variants of this OS type. For example .conf or .scm. It will be appended to the variant file name if set.
variants (default: '())This must be either a list of ganeti-os-variant objects for this OS,
or a “file-like” object (see file-like objects)
representing the variants directory.
To use the Guix OS provider with variant definitions residing in a local directory instead of declaring individual variants (see guix-variants below), you can do:
(ganeti-os
(name "guix")
(variants (local-file "ganeti-guix-variants"
#:recursive? #true)))
Note that you will need to maintain the variants.list file (see
ganeti-os-interface(7)) manually in this case.
This is the data type for a Ganeti OS variant. It takes the following parameters:
名字The name of this variant.
configurationA configuration file for this variant.
This variable contains hooks to configure networking and the GRUB bootloader.
This variable contains a list of packages suitable for a fully-virtualized guest.
This data type creates configuration files suitable for the debootstrap OS provider.
hooks (default: %default-debootstrap-hooks)When not #f, this must be a G-expression that specifies a directory
with scripts that will run when the OS is installed. It can also be a list
of (name . file-like) pairs. For example:
`((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
That will create a directory with one executable named 99-hello-world
and run it every time this variant is installed. If set to #f, hooks
in /etc/ganeti/instance-debootstrap/hooks will be used, if any.
proxy (default: #f)Optional HTTP proxy to use.
mirror (default: #f)The Debian mirror. Typically something like
http://ftp.no.debian.org/debian. The default varies depending on the
distribution.
arch (default: #f)The dpkg architecture. Set to armhf to debootstrap an ARMv7 instance
on an AArch64 host. Default is to use the current system architecture.
suite (default: "stable")When set, this must be a Debian distribution “suite” such as buster
or focal. If set to #f, the default for the OS provider is
used.
extra-pkgs (default: %default-debootstrap-extra-pkgs)List of extra packages that will get installed by dpkg in addition to the minimal system.
components (default: #f)When set, must be a list of Debian repository “components”. For example
'("main" "contrib").
generate-cache? (default: #t)Whether to automatically cache the generated debootstrap archive.
clean-cache (default: 14)Discard the cache after this amount of days. Use #f to never clear
the cache.
partition-style (default: 'msdos)The type of partition to create. When set, it must be one of 'msdos,
'none or a string.
partition-alignment (default: 2048)Alignment of the partition in sectors.
This is a helper procedure that creates a ganeti-os-variant record.
It takes two parameters: a name and a debootstrap-configuration
object.
This is a helper procedure that creates a ganeti-os record. It takes
a list of variants created with debootstrap-variant.
This is a helper procedure that creates a ganeti-os-variant record
for use with the Guix OS provider. It takes a name and a G-expression that
returns a “file-like” (see file-like objects) object
containing a Guix System configuration.
This is a helper procedure that creates a ganeti-os record. It takes
a list of variants produced by guix-variant.
This is a convenience variable to make the debootstrap provider work “out of the box” without users having to declare variants manually. It contains a single debootstrap variant with the default configuration:
(list (debootstrap-variant
"default"
(debootstrap-configuration)))
This is a convenience variable to make the Guix OS provider work without additional configuration. It creates a virtual machine that has an SSH server, a serial console, and authorizes the Ganeti hosts SSH keys.
(list (guix-variant
"default"
(file-append ganeti-instance-guix
"/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
Users can implement support for OS providers unbeknownst to Guix by
extending the ganeti-os and ganeti-os-variant records
appropriately. For example:
(ganeti-os
(name "custom")
(extension ".conf")
(variants
(list (ganeti-os-variant
(name "foo")
(configuration (plain-file "bar" "this is fine"))))))
That creates /etc/ganeti/instance-custom/variants/foo.conf which
points to a file in the store with contents this is fine. It also
creates /etc/ganeti/instance-custom/variants/variants.list with
contents foo.
Obviously this may not work for all OS providers out there. If you find the interface limiting, please reach out to guix-devel@gnu.org.
The rest of this section documents the various services that are included by
ganeti-service-type.
ganeti-noded is the daemon responsible for node-specific functions
within the Ganeti system. The value of this service must be a
ganeti-noded-configuration object.
This is the configuration for the ganeti-noded service.
ganeti (default: ganeti)The ganeti package to use for this service.
port (default: 1811)The TCP port on which the node daemon listens for network requests.
address (default: "0.0.0.0")The network address that the daemon will bind to. The default address means bind to all available addresses.
interface (default: #f)When this is set, it must be a specific network interface (e.g.
eth0) that the daemon will bind to.
max-clients (default: 20)This sets a limit on the maximum number of simultaneous client connections that the daemon will handle. Connections above this count are accepted, but no responses will be sent until enough connections have closed.
ssl? (default: #t)Whether to use SSL/TLS to encrypt network communications. The certificate
is automatically provisioned by the cluster and can be rotated with
gnt-cluster renew-crypto.
ssl-key (default: "/var/lib/ganeti/server.pem")This can be used to provide a specific encryption key for TLS communications.
ssl-cert (default: "/var/lib/ganeti/server.pem")This can be used to provide a specific certificate for TLS communications.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes. Note that this will leak encryption details to the log files, use with caution.
ganeti-confd answers queries related to the configuration of a
Ganeti cluster. The purpose of this daemon is to have a highly available
and fast way to query cluster configuration values. It is automatically
active on all master candidates. The value of this service must be a
ganeti-confd-configuration object.
This is the configuration for the ganeti-confd service.
ganeti (default: ganeti)The ganeti package to use for this service.
port (default: 1814)The UDP port on which to listen for network requests.
address (default: "0.0.0.0")Network address that the daemon will bind to.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-wconfd is the daemon that has authoritative knowledge about
the cluster configuration and is the only entity that can accept changes to
it. All jobs that need to modify the configuration will do so by sending
appropriate requests to this daemon. It only runs on the master node
and will automatically disable itself on other nodes.
The value of this service must be a ganeti-wconfd-configuration
object.
This is the configuration for the ganeti-wconfd service.
ganeti (default: ganeti)The ganeti package to use for this service.
no-voting? (default: #f)The daemon will refuse to start if the majority of cluster nodes does not
agree that it is running on the master node. Set to #t to start even
if a quorum can not be reached (dangerous, use with caution).
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-luxid is a daemon used to answer queries related to the
configuration and the current live state of a Ganeti cluster. Additionally,
it is the authoritative daemon for the Ganeti job queue. Jobs can be
submitted via this daemon and it schedules and starts them.
It takes a ganeti-luxid-configuration object.
This is the configuration for the ganeti-luxid service.
ganeti (default: ganeti)The ganeti package to use for this service.
no-voting? (default: #f)The daemon will refuse to start if it cannot verify that the majority of
cluster nodes believes that it is running on the master node. Set to
#t to ignore such checks and start anyway (this can be dangerous).
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-rapi provides a remote API for Ganeti clusters. It runs on
the master node and can be used to perform cluster actions programmatically
via a JSON-based RPC protocol.
Most query operations are allowed without authentication (unless require-authentication? is set), whereas write operations require explicit authorization via the /var/lib/ganeti/rapi/users file. See the Ganeti Remote API documentation for more information.
The value of this service must be a ganeti-rapi-configuration object.
This is the configuration for the ganeti-rapi service.
ganeti (default: ganeti)The ganeti package to use for this service.
require-authentication? (default: #f)Whether to require authentication even for read-only operations.
port (default: 5080)The TCP port on which to listen to API requests.
address (default: "0.0.0.0")The network address that the service will bind to. By default it listens on all configured addresses.
interface (default: #f)When set, it must specify a specific network interface such as eth0
that the daemon will bind to.
max-clients (default: 20)The maximum number of simultaneous client requests to handle. Further connections are allowed, but no responses are sent until enough connections have closed.
ssl? (default: #t)Whether to use SSL/TLS encryption on the RAPI port.
ssl-key (default: "/var/lib/ganeti/server.pem")This can be used to provide a specific encryption key for TLS communications.
ssl-cert (default: "/var/lib/ganeti/server.pem")This can be used to provide a specific certificate for TLS communications.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes. Note that this will leak encryption details to the log files, use with caution.
ganeti-kvmd is responsible for determining whether a given KVM
instance was shut down by an administrator or a user. Normally Ganeti will
restart an instance that was not stopped through Ganeti itself. If the
cluster option user_shutdown is true, this daemon monitors the
QMP socket provided by QEMU and listens for shutdown events, and
marks the instance as USER_down instead of ERROR_down when it
shuts down gracefully by itself.
It takes a ganeti-kvmd-configuration object.
ganeti (default: ganeti)The ganeti package to use for this service.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-mond is an optional daemon that provides Ganeti monitoring
functionality. It is responsible for running data collectors and publish
the collected information through a HTTP interface.
It takes a ganeti-mond-configuration object.
ganeti (default: ganeti)The ganeti package to use for this service.
port (default: 1815)The port on which the daemon will listen.
address (default: "0.0.0.0")The network address that the daemon will bind to. By default it binds to all available interfaces.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-metad is an optional daemon that can be used to provide
information about the cluster to instances or OS install scripts.
It takes a ganeti-metad-configuration object.
ganeti (default: ganeti)The ganeti package to use for this service.
port (default: 80)The port on which the daemon will listen.
address (default: #f)If set, the daemon will bind to this address only. If left unset, the behavior depends on the cluster configuration.
debug? (default: #f)When true, the daemon performs additional logging for debugging purposes.
ganeti-watcher is a script designed to run periodically and ensure
the health of a cluster. It will automatically restart instances that have
stopped without Ganeti’s consent, and repairs DRBD links in case a node has
rebooted. It also archives old cluster jobs and restarts Ganeti daemons
that are not running. If the cluster parameter ensure_node_health is
set, the watcher will also shutdown instances and DRBD devices if the node
it is running on is declared offline by known master candidates.
It can be paused on all nodes with gnt-cluster watcher pause.
The service takes a ganeti-watcher-configuration object.
ganeti (default: ganeti)The ganeti package to use for this service.
schedule (default: '(next-second-from (next-minute (range 0 60 5))))How often to run the script. The default is every five minutes.
rapi-ip (default: #f)This option needs to be specified only if the RAPI daemon is configured to use a particular interface or address. By default the cluster address is used.
job-age (default: (* 6 3600))Archive cluster jobs older than this age, specified in seconds. The default
is 6 hours. This keeps gnt-job list manageable.
verify-disks? (default: #t)If this is #f, the watcher will not try to repair broken DRBD links
automatically. Administrators will need to use gnt-cluster
verify-disks manually instead.
debug? (default: #f)When #t, the script performs additional logging for debugging
purposes.
ganeti-cleaner is a script designed to run periodically and remove
old files from the cluster. This service type controls two cron jobs:
one intended for the master node that permanently purges old cluster jobs,
and one intended for every node that removes expired X509 certificates,
keys, and outdated ganeti-watcher information. Like all Ganeti
services, it is safe to include even on non-master nodes as it will disable
itself as necessary.
It takes a ganeti-cleaner-configuration object.
ganeti (default: ganeti)The ganeti package to use for the gnt-cleaner command.
master-schedule (default: "45 1 * * *")How often to run the master cleaning job. The default is once per day, at 01:45:00.
node-schedule (default: "45 2 * * *")How often to run the node cleaning job. The default is once per day, at 02:45:00.
The most widespread example of time traps is test suites that involve checking the expiration date of a certificate. Such tests exists in TLS implementations such as OpenSSL and GnuTLS, but also in high-level software such as Python.