Merge branch 'master' into gnome-team

3 files changed, 364 insertions, 61 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 7337f4bd58..5707ff5cde 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -457,7 +457,7 @@ configuration file:
           (group-n 3 (one-or-more digit))
           line-end))
 
-;; Reduce the number of prompts with 'M-x debbugs-gnu'.
+;; Change the default when run as 'M-x debbugs-gnu'.
 (setq debbugs-gnu-default-packages '("guix" "guix-patches"))
 
 ;; Show feature requests.
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index cdca411706..2366c13caf 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -77,6 +77,7 @@ manual}).
 * Packaging::                   Packaging tutorials
 * System Configuration::        Customizing the GNU System
 * Containers::                  Isolated environments and nested systems
+* Virtual Machines::            Virtual machines usage and configuration
 * Advanced package management::  Power to the users!
 * Software Development::        Environments, continuous integration, etc.
 * Environment management::      Control environment
@@ -155,6 +156,11 @@ Guix System Containers
 * A Database Container::
 * Container Networking::
 
+Virtual Machines
+
+* Network bridge for QEMU::
+* Routed network for libvirt::
+
 Advanced package management
 
 * Guix Profiles in Practice::   Strategies for multiple profiles and manifests.
@@ -3702,6 +3708,236 @@ sudo ip netns del $ns
 sudo ip link del $host
 @end example
 
+@c *********************************************************************
+@node Virtual Machines
+@chapter Virtual Machines
+
+Guix can produce disk images (@pxref{Invoking guix system,,, guix, GNU
+Guix Reference Manual}) that can be used with virtual machines solutions
+such as virt-manager, GNOME Boxes or the more bare QEMU, among others.
+
+This chapter aims to provide hands-on, practical examples that relates
+to the usage and configuration of virtual machines on a Guix System.
+
+@menu
+* Network bridge for QEMU::
+* Routed network for libvirt::
+@end menu
+
+@node Network bridge for QEMU
+@section Network bridge for QEMU
+@cindex Network bridge interface
+@cindex networking, bridge
+@cindex qemu, network bridge
+
+By default, QEMU uses a so-called ``user mode'' host network back-end,
+which is convenient as it does not require any configuration.
+Unfortunately, it is also quite limited.  In this mode, the guest
+@abbr{VM, virtual machine} can access the network the same way the host
+would, but it cannot be reached from the host.  Additionally, since the
+QEMU user networking mode relies on ICMP, ICMP-based networking tools
+such as @command{ping} do @emph{not} work in this mode.  Thus, it is
+often desirable to configure a network bridge, which enables the guest
+to fully participate in the network.  This is necessary, for example,
+when the guest is to be used as a server.
+
+@subsection Creating a network bridge interface
+
+There are many ways to create a network bridge.  The following command
+shows how to use NetworkManager and its @command{nmcli} command line
+interface (CLI) tool, which should already be available if your
+operating system declaration is based on one of the desktop templates:
+
+@example sh
+# nmcli con add type bridge con-name br0 ifname br0
+@end example
+
+To have this bridge be part of your network, you must associate your
+network bridge with the Ethernet interface used to connect with the
+network.  Assuming your interface is named @samp{enp2s0}, the following
+command can be used to do so:
+
+@example sh
+# nmcli con add type bridge-slave ifname enp2s0 master br0
+@end example
+
+@quotation Important
+Only Ethernet interfaces can be added to a bridge.  For wireless
+interfaces, consider the routed network approach detailed in
+@xref{Routed network for libvirt}.
+@end quotation
+
+By default, the network bridge will allow your guests to obtain their IP
+address via DHCP, if available on your local network.  For simplicity,
+this is what we will use here.  To easily find the guests, they can be
+configured to advertise their host names via mDNS.
+
+@subsection Configuring the QEMU bridge helper script
+
+QEMU comes with a helper program to conveniently make use of a network
+bridge interface as an unprivileged user @pxref{Network options,,, QEMU,
+QEMU Documentation}.  The binary must be made setuid root for proper
+operation; this can be achieved by adding it to the
+@code{setuid-programs} field of your (host) @code{operating-system}
+definition, as shown below:
+
+@example lisp
+(setuid-programs
+ (cons (file-append qemu "/libexec/qemu-bridge-helper")
+       %setuid-programs))
+@end example
+
+The file @file{/etc/qemu/bridge.conf} must also be made to allow the
+bridge interface, as the default is to deny all.  Add the following to
+your list of services to do so:
+
+@example lisp
+(extra-special-file "/etc/qemu/host.conf" "allow br0\n")
+@end example
+
+@subsection Invoking QEMU with the right command line options
+
+When invoking QEMU, the following options should be provided so that the
+network bridge is used, after having selected a unique MAC address for
+the guest.
+
+@quotation Important
+By default, a single MAC address is used for all guests, unless
+provided.  Failing to provided different MAC addresses to each virtual
+machine making use of the bridge would cause networking issues.
+@end quotation
+
+@example sh
+$ qemu-system-x86_64 [...] \
+    -device virtio-net-pci,netdev=user0,mac=XX:XX:XX:XX:XX:XX \
+    -netdev bridge,id=user0,br=br0 \
+    [...]
+@end example
+
+To generate MAC addresses that have the QEMU registered prefix, the
+following snippet can be employed:
+
+@example sh
+mac_address="52:54:00:$(dd if=/dev/urandom bs=512 count=1 2>/dev/null \
+                           | md5sum \
+                           | sed -E 's/^(..)(..)(..).*$/\1:\2:\3/')"
+echo $mac_address
+@end example
+
+@subsection Networking issues caused by Docker
+
+If you use Docker on your machine, you may experience connectivity
+issues when attempting to use a network bridge, which are caused by
+Docker also relying on network bridges and configuring its own routing
+rules.  The solution is add the following @code{iptables} snippet to
+your @code{operating-system} declaration:
+
+@example lisp
+(service iptables-service-type
+             (iptables-configuration
+              (ipv4-rules (plain-file "iptables.rules" "\
+*filter
+:INPUT ACCEPT [0:0]
+:FORWARD DROP [0:0]
+:OUTPUT ACCEPT [0:0]
+-A FORWARD -i br0 -o br0 -j ACCEPT
+COMMIT
+"))
+@end example
+
+@node Routed network for libvirt
+@section Routed network for libvirt
+@cindex Virtual network bridge interface
+@cindex networking, virtual bridge
+@cindex libvirt, virtual network bridge
+
+If the machine hosting your virtual machines is connected wirelessly to
+the network, you won't be able to use a true network bridge as explained
+in the preceding section (@pxref{Network bridge for QEMU}).  In this
+case, the next best option is to use a @emph{virtual} bridge with static
+routing and to configure a libvirt-powered virtual machine to use it
+(via the @command{virt-manager} GUI for example).  This is similar to
+the default mode of operation of QEMU/libvirt, except that instead of
+using @abbr{NAT, Network Address Translation}, it relies on static
+routes to join the @abbr{VM, virtual machine} IP address to the
+@abbr{LAN, local area network}.  This provides two-way connectivity to
+and from the virtual machine, which is needed for exposing services
+hosted on the virtual machine.
+
+@subsection Creating a virtual network bridge
+
+A virtual network bridge consists of a few components/configurations,
+such as a @abbr{TUN, network tunnel} interface, DHCP server (dnsmasq)
+and firewall rules (iptables).  The @command{virsh} command, provided by
+the @code{libvirt} package, makes it very easy to create a virtual
+bridge.  You first need to choose a network subnet for your virtual
+bridge; if your home LAN is in the @samp{192.168.1.0/24} network, you
+could opt to use e.g.@: @samp{192.168.2.0/24}.  Define an XML file,
+e.g.@: @file{/tmp/virbr0.xml}, containing the following:
+
+@example
+<network>
+  <name>virbr0</name>
+  <bridge name="virbr0" />
+  <forward mode="route"/>
+  <ip address="192.168.2.0" netmask="255.255.255.0">
+    <dhcp>
+      <range start="192.168.2.1" end="192.168.2.254"/>
+    </dhcp>
+  </ip>
+</network>
+@end example
+
+Then create and configure the interface using the @command{virsh}
+command, as root:
+
+@example
+virsh net-define /tmp/virbr0.xml
+virsh net-autostart virbr0
+virsh net-start virbr0
+@end example
+
+The @samp{virbr0} interface should now be visible e.g.@: via the
+@samp{ip address} command.  It will be automatically started every time
+your libvirt virtual machine is started.
+
+@subsection Configuring the static routes for your virtual bridge
+
+If you configured your virtual machine to use your newly created
+@samp{virbr0} virtual bridge interface, it should already receive an IP
+via DHCP such as @samp{192.168.2.15} and be reachable from the server
+hosting it, e.g.@: via @samp{ping 192.168.2.15}.  There's one last
+configuration needed so that the VM can reach the external network:
+adding static routes to the network's router.
+
+In this example, the LAN network is @samp{192.168.1.0/24} and the router
+configuration web page may be accessible via e.g.@: the
+@url{http://192.168.1.1} page.  On a router running the
+@url{https://librecmc.org/, libreCMC} firmware, you would navigate to
+the @clicksequence{Network @click{} Static Routes} page
+(@url{https://192.168.1.1/cgi-bin/luci/admin/network/routes}), and you
+would add a new entry to the @samp{Static IPv4 Routes} with the
+following information:
+
+@table @samp
+@item Interface
+lan
+@item Target
+192.168.2.0
+@item IPv4-Netmask
+255.255.255.0
+@item IPv4-Gateway
+@var{server-ip}
+@item Route type
+unicast
+@end table
+
+where @var{server-ip} is the IP address of the machine hosting the VMs,
+which should be static.
+
+After saving/applying this new static route, external connectivity
+should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
+to verify that it functions correctly.
 
 @c *********************************************************************
 @node Advanced package management
diff --git a/doc/guix.texi b/doc/guix.texi
index 50d66e9557..daf3ee22cf 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12197,6 +12197,11 @@ This is like the form above, but referring explicitly to the
 @var{output} of @var{obj}---this is useful when @var{obj} produces
 multiple outputs (@pxref{Packages with Multiple Outputs}).
 
+Sometimes a gexp unconditionally refers to the @code{"out"} output, but
+the user of that gexp would still like to insert a reference to another
+output.  The @code{gexp-input} procedure aims to address that.
+@xref{gexp-input}.
+
 @item #+@var{obj}
 @itemx #+@var{obj}:output
 @itemx (ungexp-native @var{obj})
@@ -12309,10 +12314,9 @@ When @var{references-graphs} is true, it must be a list of tuples of one of the
 following forms:
 
 @example
-(@var{file-name} @var{package})
-(@var{file-name} @var{package} @var{output})
-(@var{file-name} @var{derivation})
-(@var{file-name} @var{derivation} @var{output})
+(@var{file-name} @var{obj})
+(@var{file-name} @var{obj} @var{output})
+(@var{file-name} @var{gexp-input})
 (@var{file-name} @var{store-item})
 @end example
 
@@ -12590,6 +12594,39 @@ The example above returns an object that corresponds to the i686 build
 of Coreutils, regardless of the current value of @code{%current-system}.
 @end defmac
 
+@anchor{gexp-input}
+@deffn {Procedure} gexp-input @var{obj} [@var{output}] [#:native? #f]
+Return a @dfn{gexp input} record for the given @var{output} of file-like
+object @var{obj}, with @code{#:native?} determining whether this is a
+native reference (as with @code{ungexp-native}) or not.
+
+This procedure is helpful when you want to pass a reference to a
+specific output of an object to some procedure that may not know about
+that output.  For example, assume you have this procedure, which takes
+one file-like object:
+
+@lisp
+(define (make-symlink target)
+  (computed-file "the-symlink"
+                 #~(symlink #$target #$output)))
+@end lisp
+
+Here @code{make-symlink} can only ever refer to the default output of
+@var{target}---the @code{"out"} output (@pxref{Packages with Multiple
+Outputs}).  To have it refer to, say, the @code{"lib"} output of the
+@code{hwloc} package, you can call it like so:
+
+@lisp
+(make-symlink (gexp-input hwloc "lib"))
+@end lisp
+
+You can also compose it like any other file-like object:
+
+@lisp
+(make-symlink
+  (file-append (gexp-input hwloc "lib") "/lib/libhwloc.so"))
+@end lisp
+@end deffn
 
 Of course, in addition to gexps embedded in ``host'' code, there are
 also modules containing build tools.  To make it clear that they are
@@ -34161,6 +34198,9 @@ The Laminar package to use.
 @item @code{home-directory} (default: @code{"/var/lib/laminar"})
 The directory for job configurations and run directories.
 
+@item @code{supplementary-groups} (default: @code{()})
+Supplementary groups for the Laminar user account.
+
 @item @code{bind-http} (default: @code{"*:8080"})
 The interface/port or unix socket on which laminard should listen for
 incoming connections to the web frontend.
@@ -35169,17 +35209,24 @@ services.
 @subsubheading Libvirt daemon
 
 @code{libvirtd} is the server side daemon component of the libvirt
-virtualization management system.  This daemon runs on host servers
-and performs required management tasks for virtualized guests.
+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
+@samp{libvirt} group, as shown in the example below.
 
 @defvar libvirt-service-type
 This is the type of the @uref{https://libvirt.org, libvirt daemon}.
 Its value must be a @code{libvirt-configuration}.
 
 @lisp
+(users (cons (user-account
+              (name "user")
+              (group "users")
+              (supplementary-groups '("libvirt"
+                                      "audio" "video" "wheel")))
+             %base-user-accounts))
 (service libvirt-service-type
          (libvirt-configuration
-          (unix-sock-group "libvirt")
           (tls-port "16555")))
 @end lisp
 @end defvar
@@ -35261,7 +35308,7 @@ 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"}.
+Defaults to @samp{"libvirt"}.
 
 @end deftypevr
 
@@ -38761,58 +38808,6 @@ the coordinator database, and is used by the agent to authenticate.
 @end table
 @end deftp
 
-The Guix Build Coordinator package contains a script to query an
-instance of the Guix Data Service for derivations to build, and then
-submit builds for those derivations to the coordinator.  The service
-type below assists in running this script.  This is an additional tool
-that may be useful when building derivations contained within an
-instance of the Guix Data Service.
-
-@defvar guix-build-coordinator-queue-builds-service-type
-Service type for the
-guix-build-coordinator-queue-builds-from-guix-data-service script.  Its
-value must be a @code{guix-build-coordinator-queue-builds-configuration}
-object.
-@end defvar
-
-@deftp {Data Type} guix-build-coordinator-queue-builds-configuration
-Data type representing the options to the queue builds from guix data
-service script.
-
-@table @asis
-@item @code{package} (default: @code{guix-build-coordinator})
-The Guix Build Coordinator package to use.
-
-@item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
-The system user to run the service as.
-
-@item @code{coordinator} (default: @code{"http://localhost:8746"})
-The URI to use when connecting to the coordinator.
-
-@item @code{systems} (default: @code{#f})
-The systems for which to fetch derivations to build.
-
-@item @code{systems-and-targets} (default: @code{#f})
-An association list of system and target pairs for which to fetch
-derivations to build.
-
-@item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
-The Guix Data Service instance from which to query to find out about
-derivations to build.
-
-@item @code{guix-data-service-build-server-id} (default: @code{#f})
-The Guix Data Service build server ID corresponding to the builds being
-submitted.  Providing this speeds up the submitting of builds as
-derivations that have already been submitted can be skipped before
-asking the coordinator to build them.
-
-@item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
-A file to record which commits have been processed, to avoid needlessly
-processing them again if the service is restarted.
-
-@end table
-@end deftp
-
 @subsubheading Guix Data Service
 The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
 and provides data about GNU Guix.  This includes information about
@@ -45119,6 +45114,7 @@ sound support.
 
 @cindex PulseAudio, home service
 @cindex RTP, for PulseAudio
+@subsubheading PulseAudio RTP Streaming Services
 
 The following services dynamically reconfigure the
 @uref{https://pulseaudio.org,PulseAudio sound server}: they let you
@@ -45206,6 +45202,77 @@ Stopping the Shepherd service turns off broadcasting.
 This is the multicast address used by default by the two services above.
 @end defvar
 
+@cindex PipeWire, home service
+@subsubheading PipeWire Home Service
+
+@uref{https://pipewire.org, PipeWire} provides a low-latency,
+graph-based audio and video processing service.  In addition to its
+native protocol, it can also be used as a replacement for both JACK and
+PulseAudio.
+
+While PipeWire provides the media processing and API, it does not,
+directly, know about devices such as sound cards, nor how you might want
+to connect applications, hardware, and media processing filters.
+Instead, PipeWire relies on a @dfn{session manager} to specify all these
+relationships.  While you may use any session manager you wish, for most
+people the @url{https://pipewire.pages.freedesktop.org/wireplumber/,
+WirePlumber} session manager, a reference implementation provided by the
+PipeWire project itself, suffices, and that is the one
+@code{home-pipewire-service-type} uses.
+
+PipeWire can be used as a replacement for PulseAudio by setting
+@code{enable-pulseaudio?} to @code{#t} in
+@code{home-pipewire-configuration}, so that existing PulseAudio clients
+may use it without any further configuration.
+
+In addition, JACK clients may connect to PipeWire by using the
+@command{pw-jack} program, which comes with PipeWire.  Simply prefix the
+command with @command{pw-jack} when you run it, and audio data should go
+through PipeWire:
+
+@example
+pw-jack mpv -ao=jack sound-file.wav
+@end example
+
+For more information on PulseAudio emulation, see
+@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio},
+for JACK, see
+@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK}.
+
+As PipeWire does not use @code{dbus} to start its services on demand
+(as PulseAudio does), @code{home-pipewire-service-type} uses Shepherd
+to start services when logged in, provisioning the @code{pipewire},
+@code{wireplumber}, and, if configured, @code{pipewire-pulseaudio}
+services.  @xref{Shepherd Home Service}.
+
+@defvar home-pipewire-service-type
+This provides the service definition for @command{pipewire}, which will
+run on login.  Its value is a @code{home-pipewire-configuration} object.
+
+To start the service, add it to the @code{service} field of your
+@code{home-environment}, such as:
+
+@lisp
+(service home-pipewire-service-type)
+@end lisp
+@end defvar
+
+@deftp {Data Type} home-pipewire-configuration
+Available @code{home-pipewire-configuration} fields are:
+
+@table @asis
+@item @code{pipewire} (default: @code{pipewire}) (type: file-like)
+The PipeWire package to use.
+
+@item @code{wireplumber} (default: @code{wireplumber}) (type: file-like)
+The WirePlumber package to use.
+
+@item @code{enable-pulseaudio?} (default: @code{#t}) (type: boolean)
+When true, enable PipeWire's PulseAudio emulation support, allowing
+PulseAudio clients to use PipeWire transparently.
+@end table
+@end deftp
+
 @node Mail Home Services
 @subsection Mail Home Services