From patchwork Mon Dec 18 20:25:15 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxim Cournoyer X-Patchwork-Id: 57699 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id BEEBD27BBE9; Mon, 18 Dec 2023 20:26:20 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-1.4 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,IP_LINK_PLUS,MAILING_LIST_MULTI, NUMERIC_HTTP_ADDR,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 6CBD827BBE2 for ; Mon, 18 Dec 2023 20:26:15 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rFKBe-0002HM-5i; Mon, 18 Dec 2023 15:26:02 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rFKBd-0002HA-2P for guix-patches@gnu.org; Mon, 18 Dec 2023 15:26:01 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rFKBc-0007xh-QZ for guix-patches@gnu.org; Mon, 18 Dec 2023 15:26:00 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rFKBe-0005bY-F0 for guix-patches@gnu.org; Mon, 18 Dec 2023 15:26:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#67885] [PATCH] Add network bridge guide to the cookbook. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 18 Dec 2023 20:26:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 67885 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 67885@debbugs.gnu.org Cc: Maxim Cournoyer X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.170293115521518 (code B ref -1); Mon, 18 Dec 2023 20:26:02 +0000 Received: (at submit) by debbugs.gnu.org; 18 Dec 2023 20:25:55 +0000 Received: from localhost ([127.0.0.1]:33688 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rFKBW-0005az-39 for submit@debbugs.gnu.org; Mon, 18 Dec 2023 15:25:54 -0500 Received: from lists.gnu.org ([2001:470:142::17]:41264) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rFKBT-0005ad-Ij for submit@debbugs.gnu.org; Mon, 18 Dec 2023 15:25:52 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rFKBL-0002GT-Gl for guix-patches@gnu.org; Mon, 18 Dec 2023 15:25:43 -0500 Received: from mail-qk1-x736.google.com ([2607:f8b0:4864:20::736]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rFKBJ-0007wk-34 for guix-patches@gnu.org; Mon, 18 Dec 2023 15:25:43 -0500 Received: by mail-qk1-x736.google.com with SMTP id af79cd13be357-77f8308616eso328160085a.2 for ; Mon, 18 Dec 2023 12:25:40 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1702931140; x=1703535940; darn=gnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=gYrghNRxO9HMcjfFUXOVADfS7i/9vP/lSgy9mjxXddQ=; b=J5TsXdUmoLwa/tvDgmMLoCcgqyv3uMmtwlFFyZ9SQUG+uTabDM76+BoEwoEDjd8rrl RQcNf7qFv3kgvVYTFG+WjfzJUIl7e72jO5gITrINb/L/GGVh52b8Y57AW4FC541twxKo lM3BBdPuJ8WI4lFwzGtrAPbFOmDFDj3Cs2TyV+t6xmHjwlc+cSI43QkhHwmsuSHnEotR uJXfiPWQytiD5AmIfpu5d9LFShm4fSI64YjUS4OnjFZOVCFK+921i1COZikVAoYL/hNF CLVRTgRztG7zyjMp1nVnzmnpCO3LjMQrsRPDc1a1chgC1/MHFHi+TRlU69inRSA5n9s+ 7PlQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1702931140; x=1703535940; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=gYrghNRxO9HMcjfFUXOVADfS7i/9vP/lSgy9mjxXddQ=; b=Xc8ip87hcPj1a0gqqHZkDXmeWuhBYomcxGDFH4VI4MwYBxYNK6Wrbyxj5gnPcyZe1y FCqFdf8v6ZYc4ZJUwx7eMbJe9vG0NEzo+LZPsaW9fXJG+2F+kWCJNM7x+FSFoG6jhsIa X5bgphVnrHzV13E9EUC7LuZOmlGGYAFAJTTM4ug6Lck/rcfD3sD2/I4ytohWa+LhyON1 tGVCip0ecplNYT+MkevV6YgXeCdzaGQoGV59pldJfWABtznw+2scJ5u75fXCP7jGfdTS hCARmd1e8g1zXSqSeV8N3XSMc3Yv7+0PcHsW29TJCC38rucI2I7IWsXc14dYwxEhWl9x zOhQ== X-Gm-Message-State: AOJu0YxausDMEdpQf3L+wcTp7zyS7Svd+keyhqyKJZWsrveqM7YSaeAr bAQW76Jh5YN88WepTjPiBmWRlHg+/rQ= X-Google-Smtp-Source: AGHT+IFHdSD6rputM2SePJMhxxVTP/AufZjLchHK3l/wyS+HxN3/q/Slc+q8yQklIefoI9FnGIg9Bg== X-Received: by 2002:a05:620a:480c:b0:77d:cbe4:cb86 with SMTP id eb12-20020a05620a480c00b0077dcbe4cb86mr20021183qkb.11.1702931139445; Mon, 18 Dec 2023 12:25:39 -0800 (PST) Received: from localhost.localdomain (dsl-205-236-230-90.b2b2c.ca. [205.236.230.90]) by smtp.gmail.com with ESMTPSA id rb3-20020a05620a8d0300b00774350813ccsm8580893qkn.118.2023.12.18.12.25.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Dec 2023 12:25:39 -0800 (PST) From: Maxim Cournoyer Date: Mon, 18 Dec 2023 15:25:15 -0500 Message-ID: <5a380627d07dd47a8494caa41abdef7651a4f51d.1702931114.git.maxim.cournoyer@gmail.com> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::736; envelope-from=maxim.cournoyer@gmail.com; helo=mail-qk1-x736.google.com X-Spam_score_int: -8 X-Spam_score: -0.9 X-Spam_bar: / X-Spam_report: (-0.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, IP_LINK_PLUS=0.012, NUMERIC_HTTP_ADDR=1.242, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches Change-Id: If478196985aac7947067329957516f82bcb95ca4 --- doc/guix-cookbook.texi | 236 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) base-commit: d1eac4f3b744737d5274efca40c0437e6246c9db diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index cdca411706..3be1ad3243 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -77,6 +77,7 @@ Top * 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 @@ Top * 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 @@ Container Networking 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 Rounted 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 + + virbr0 + + + + + + + + +@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