GNU bug report logs - #77153
[PATCH 0/3] doc: cookbook: Manual libvirt networking.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 77153 in the body.
You can then email your comments to 77153 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: guix-patches <at> gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH 0/3] doc: cookbook: Manual libvirt networking.
Date: Fri, 21 Mar 2025 20:49:31 +0530

45mg (3):
  doc: cookbook: Fix terminology for libvirt virtual network switches
  doc: cookbook: Clarify virtual network switches.
  doc: cookbook: Document manual libvirt networking.

 doc/guix-cookbook.texi | 154 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 138 insertions(+), 16 deletions(-)


base-commit: 9eddd250b773043fcac5e7eaa4939e5a2d9940bd
-- 
2.48.1

Message #8 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH 1/3] doc: cookbook: Fix terminology for libvirt virtual
 network switches.
Date: Fri, 21 Mar 2025 20:51:58 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Routed network for
libvirt]: Replace the term 'virtual bridge' with 'virtual network
switch'.  This is the term used by the libvirt Wiki to refer to the
combined setup of a 'virtual bridge' network interface, dnsmasq instance
bound to it, and firewall rules associated with it.

Change-Id: Ibd10fe76321eb61e9ca23d8124634d1108d4faad
---
 doc/guix-cookbook.texi | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index d9b98a2ab3..8bfc859a90 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3879,29 +3879,29 @@ Routed network for libvirt
 @section Routed network for libvirt
 @cindex Virtual network bridge interface
 @cindex networking, virtual bridge
-@cindex libvirt, virtual network bridge
+@cindex libvirt, virtual network switch
 
 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
+case, the next best option is to use a @emph{virtual network switch}
+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
+@subsection Creating a virtual network switch
 
-A virtual network bridge consists of a few components/configurations,
+A virtual network switch 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
+switch.  You first need to choose a network subnet for your virtual
+switch; 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:
 

base-commit: 9eddd250b773043fcac5e7eaa4939e5a2d9940bd
-- 
2.48.1

Message #11 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH 2/3] doc: cookbook: Clarify virtual network switches.
Date: Fri, 21 Mar 2025 20:51:59 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Routed network for
libvirt] {Creating a virtual network switch}: Remove unnecessarily
noncommital language ("a few components/configurations, such as...").
Correct 'TUN interface', as bridges are currently used.  Add a link to
the libvirt Wiki for more information.

Change-Id: I6ffdeca8e4d32155c8cce547d4930bf1b0cb471b
---
 doc/guix-cookbook.texi | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 8bfc859a90..325b1d9c2a 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3896,14 +3896,19 @@ Routed network for libvirt
 
 @subsection Creating a virtual network switch
 
-A virtual network switch 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
-switch.  You first need to choose a network subnet for your virtual
-switch; 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:
+A virtual network switch consists of a virtual network device called a
+`virtual bridge', DHCP server (dnsmasq) and firewall rules
+(iptables). See the
+@url{https://wiki.libvirt.org/VirtualNetworking.html, libvirt Wiki
+article on Virtual Networking} for more details on the modes of
+operation, management and implementation of virtual network switches.
+
+The @command{virsh} command, provided by the @code{libvirt}
+package, makes it very easy to create a virtual switch.  You first need
+to choose a network subnet for your virtual switch; 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>
-- 
2.48.1

Message #14 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH 3/3] doc: cookbook: Document manual libvirt networking.
Date: Fri, 21 Mar 2025 20:52:00 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Manual libvirt
networking]: New section.

Change-Id: Ice79c5dc8183ec694ac8b846a5ec88cb98cac9ff
---
 doc/guix-cookbook.texi | 120 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 325b1d9c2a..338dba25be 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3750,6 +3750,7 @@ Virtual Machines
 @menu
 * Network bridge for QEMU::
 * Routed network for libvirt::
+* Manual libvirt networking::
 @end menu
 
 @node Network bridge for QEMU
@@ -3974,6 +3975,125 @@ Routed network for libvirt
 should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
 to verify that it functions correctly.
 
+@node Manual libvirt networking
+@section Manual libvirt networking
+
+As mentioned in the preceding section (@pxref{Routed network for libvirt}),
+libvirt allows virtual networks to be defined via XML files and managed
+by the @command{virsh} command.  The details of the creation and removal
+of virtual network switches are handled by libvirt, so the user does not
+have to deal with them.
+
+However, libvirt's handling of virtual network switches can sometimes
+clash with more complex networking setups.  In particular, the iptables
+rules inserted by libvirt for switches operating in the NAT mode can
+clash with existing iptables/nftables rules, leading to insecure or
+broken packet filtering.
+
+In such cases, the only solution is to manually set up a virtual network
+switch.  This section will provide instructions on how to do so using
+Guix System services.
+
+This section is based on
+@url{https://jamielinux.com/docs/libvirt-networking-handbook/custom-nat-based-network.html,
+the corresponding section from the (unofficial) libvirt Networking
+Handbook}.  It should be noted that at the time of writing (March 2025),
+this resource had not been updated since 2015, and is therefore somewhat
+outdated.  In particular, the creation of a `dummy interface' is no
+longer necessary.
+
+@subsection Creating the virtual network bridge
+
+The @code{static-networking-service-type} can be used to create a
+virtual network bridge and assign an IP address to it:
+
+@example lisp
+(service static-networking-service-type
+         (list (static-networking
+                ;; The default provision is 'networking; if you're using any
+                ;; other service with this provision, such as
+                ;; `network-manager-service-type`, then you need to change the
+                ;; default
+                (provision '(static-networking))
+                (links
+                 (list (network-link
+                        (name "virbr0")
+                        (type 'bridge)
+                        (arguments '((stp_state . 1))))))
+                (addresses
+                 (list (network-address
+                        (device "virbr0")
+                        (value "192.168.10.1/24")))))))
+@end example
+
+@subsection Running dnsmasq for the virtual network bridge
+
+The @code{dnsmasq-service-type} can be used to provide DNS and DHCP for
+guests connected to this virtual network switch:
+
+@example lisp
+(service dnsmasq-service-type
+         (dnsmasq-configuration
+          ;; You can have multiple instances of `dnsmasq-service-type` as long
+          ;; as each one has a different provision
+          (provision '(dnsmasq-virbr0))
+          (extra-options (list
+                          ;; Only bind to the virtual bridge. This
+                          ;; avoids conflicts with other running
+                          ;; dnsmasq instances.
+                          "--except-interface=lo"
+                          "--interface=virbr0"
+                          "--bind-dynamic"
+                          ;; IPv4 addresses to offer to VMs. This
+                          ;; should match the chosen subnet.
+                          "--dhcp-range=192.168.10.2,192.168.10.254"))))
+@end example
+
+@subsection Configuring NAT for the virtual network switch
+
+If you intend to use the virtual network switch in NAT mode, you will
+need to use nftables (or iptables) rules to set up IP masquerading.  The
+following example shows how to use @code{nftables-service-type} to do
+this:
+
+@example lisp
+(service nftables-service-type
+         (nftables-configuration
+          (ruleset
+           (plain-file "nftables.conf"
+                       "\
+table inet filter @{
+
+  chain input @{
+    type filter hook input priority filter; policy drop;
+    # Add your existing packet filtering rules here....
+    iifname "virbr0" udp dport 67 counter accept comment "allow dhcp on virbr0"
+    iifname "virbr0" meta l4proto @{tcp, udp@} th dport 53 accept comment "allow dns on virbr0"
+  @}
+
+  chain forward @{
+    type filter hook forward priority filter; policy drop;
+    # Add your existing forwarding rules here....
+    iifname "virbr0" accept comment "allow outbound traffic from virbr0"
+    oifname "virbr0" ct state @{established, related @} accept comment "allow established traffic to virbr0"
+  @}
+
+@}
+
+table inet nat @{
+  chain postrouting @{
+    type nat hook postrouting priority srcnat; policy accept;
+    # Add your existing nat rules here...
+    iifname "virbr0" ip daddr @{ 224.0.0.0/24, 255.255.255.255/32 @} return comment "don't masquerade to reserved address blocks"
+    iifname "virbr0" oifname != "virbr0" masquerade comment "masquerade all outgoing traffic from VMs"
+  @}
+@}
+"))))
+@end example
+
+Ensure that you have IPv4 forwarding enabled (you can use
+@code{sysctl-service-type} for this).
+
 @c *********************************************************************
 @node Advanced package management
 @chapter Advanced package management
-- 
2.48.1

Message #17 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 1/3] doc: cookbook: Fix terminology for
 libvirt virtual network switches.
Date: Sat, 22 Mar 2025 17:17:10 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
> libvirt]: Replace the term 'virtual bridge' with 'virtual network
> switch'.  This is the term used by the libvirt Wiki to refer to the
> combined setup of a 'virtual bridge' network interface, dnsmasq instance
> bound to it, and firewall rules associated with it.

I'm not sure 'switch' is clearer than 'bridge' in the context of
libvirt; and I doubt a wiki has much authority on the topic.  I find the
'bridge' terminology most common on Linux, and it matches to options
documented in libvirt-related tools such as `man virt-install` from the
virt-manager package:

--8<---------------cut here---------------start------------->8---
       bridge=BRIDGE
              Connect to a bridge device in the host called BRIDGE.  Use  this
              option  if the host has static networking config & the guest re‐
              quires full outbound and inbound connectivity to/from  the  LAN.
              Also use this if live migration will be used with this guest.
--8<---------------cut here---------------end--------------->8---

So I'm not convinced of the value of the proposed change.

-- 
Thanks,
Maxim

Message #20 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 2/3] doc: cookbook: Clarify virtual network
 switches.
Date: Sat, 22 Mar 2025 17:21:40 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
> libvirt] {Creating a virtual network switch}: Remove unnecessarily
> noncommital language ("a few components/configurations, such as...").
> Correct 'TUN interface', as bridges are currently used.  Add a link to
> the libvirt Wiki for more information.

I'm also not sure of the benefit here; we drop some words but refer the
user to an external wiki page instead, which seems worst to me.

-- 
Thanks,
Maxim

Message #23 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 1/3] doc: cookbook: Fix terminology for
 libvirt virtual network switches.
Date: Sat, 22 Mar 2025 11:09:05 +0000

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:

> Hi,
>
> 45mg <45mg.writes <at> gmail.com> writes:
>
>> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
>> libvirt]: Replace the term 'virtual bridge' with 'virtual network
>> switch'.  This is the term used by the libvirt Wiki to refer to the
>> combined setup of a 'virtual bridge' network interface, dnsmasq instance
>> bound to it, and firewall rules associated with it.
>
> I'm not sure 'switch' is clearer than 'bridge' in the context of
> libvirt; and I doubt a wiki has much authority on the topic.  I find the
> 'bridge' terminology most common on Linux, and it matches to options
> documented in libvirt-related tools such as `man virt-install` from the
> virt-manager package:
>
> --8<---------------cut here---------------start------------->8---
>        bridge=BRIDGE
>               Connect to a bridge device in the host called BRIDGE.  Use  this
>               option  if the host has static networking config & the guest re‐
>               quires full outbound and inbound connectivity to/from  the  LAN.
>               Also use this if live migration will be used with this guest.
> --8<---------------cut here---------------end--------------->8---
>
> So I'm not convinced of the value of the proposed change.

The idea is to use 'switch' to refer to "the combined setup of a
'virtual bridge' network interface, dnsmasq instance bound to it, and
firewall rules associated with it", which is what libvirt creates from a
'virtual network' specified in an XML file.

'Bridge' is ambiguous because it is sometimes used with this meaning
(for example, in the target of this patch), and sometimes to refer
specifically to the virtual network device called a 'bridge' (as in your
example). This quickly gets confusing; patch 3/3 in particular would be
a lot more confusing if I didn't introduce a term to make the
distinction.

The Wiki should be authoritative enough for our purposes, given that the
official documentation links to it. For example, from
[libvirt: Network XML format](https://libvirt.org/formatnetwork.html):
> This page provides an introduction to the network XML format. For
> background information on the concepts referred to here, consult the
> relevant wiki page.

Message #26 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 3/3] doc: cookbook: Document manual libvirt
 networking.
Date: Sat, 22 Mar 2025 20:18:34 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> * doc/guix-cookbook.texi (Virtual Machines): [Manual libvirt
> networking]: New section.

Thanks for writing this.

> Change-Id: Ice79c5dc8183ec694ac8b846a5ec88cb98cac9ff
> ---
>  doc/guix-cookbook.texi | 120 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 120 insertions(+)
>
> diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
> index 325b1d9c2a..338dba25be 100644
> --- a/doc/guix-cookbook.texi
> +++ b/doc/guix-cookbook.texi
> @@ -3750,6 +3750,7 @@ Virtual Machines
>  @menu
>  * Network bridge for QEMU::
>  * Routed network for libvirt::
> +* Manual libvirt networking::
>  @end menu
>  
>  @node Network bridge for QEMU
> @@ -3974,6 +3975,125 @@ Routed network for libvirt
>  should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
>  to verify that it functions correctly.
>  
> +@node Manual libvirt networking
> +@section Manual libvirt networking

Perhaps this should be named 'Custom NAT-based network', as in Jamie's
handbook, as every other configurations also involve manual steps?

> +
> +As mentioned in the preceding section (@pxref{Routed network for libvirt}),
> +libvirt allows virtual networks to be defined via XML files and managed
> +by the @command{virsh} command.  The details of the creation and removal
> +of virtual network switches are handled by libvirt, so the user does not
> +have to deal with them.

As discussed previously, I think it may be best to stick to our existing
terminology of 'virtual bridge' instead of 'virtual switch'.

> +However, libvirt's handling of virtual network switches can sometimes
> +clash with more complex networking setups.  In particular, the iptables
> +rules inserted by libvirt for switches operating in the NAT mode can
> +clash with existing iptables/nftables rules, leading to insecure or
> +broken packet filtering.
> +
> +In such cases, the only solution is to manually set up a virtual network
> +switch.  This section will provide instructions on how to do so using
> +Guix System services.
> +
> +This section is based on
> +@url{https://jamielinux.com/docs/libvirt-networking-handbook/custom-nat-based-network.html,
> +the corresponding section from the (unofficial) libvirt Networking
> +Handbook}.  It should be noted that at the time of writing (March 2025),
> +this resource had not been updated since 2015, and is therefore somewhat
> +outdated.  In particular, the creation of a `dummy interface' is no
> +longer necessary.

I would drop this paragraph.  The other sections are also based on that
same handbook.  It's up to us to extract the good bits and avoid the
obsolete one and keep our own doc up to date :-).

> +@subsection Creating the virtual network bridge
> +
> +The @code{static-networking-service-type} can be used to create a
> +virtual network bridge and assign an IP address to it:

'network bridge', hm? ;-)

> +
> +@example lisp
> +(service static-networking-service-type
> +         (list (static-networking
> +                ;; The default provision is 'networking; if you're using any
> +                ;; other service with this provision, such as
> +                ;; `network-manager-service-type`, then you need to change the
> +                ;; default

Use complete sentences for line comments (i.e. add a terminating period
above).

> +                (provision '(static-networking))
> +                (links
> +                 (list (network-link
> +                        (name "virbr0")
> +                        (type 'bridge)
> +                        (arguments '((stp_state . 1))))))

I've never seen this stp_state argument; is it useful?  Perhaps it
deserves a comment.

> +                (addresses
> +                 (list (network-address
> +                        (device "virbr0")
> +                        (value "192.168.10.1/24")))))))
> +@end example
> +
> +@subsection Running dnsmasq for the virtual network bridge
> +
> +The @code{dnsmasq-service-type} can be used to provide DNS and DHCP for
> +guests connected to this virtual network switch:
> +
> +@example lisp
> +(service dnsmasq-service-type
> +         (dnsmasq-configuration
> +          ;; You can have multiple instances of `dnsmasq-service-type` as long
> +          ;; as each one has a different provision

Missing ending period.

> +          (provision '(dnsmasq-virbr0))
> +          (extra-options (list
> +                          ;; Only bind to the virtual bridge. This
> +                          ;; avoids conflicts with other running
> +                          ;; DNSMASQ instances.
> +                          "--except-interface=lo"
> +                          "--interface=virbr0"
> +                          "--bind-dynamic"
> +                          ;; IPv4 addresses to offer to VMs. This
> +                          ;; should match the chosen subnet.
> +                          "--dhcp-range=192.168.10.2,192.168.10.254"))))
> +@end example
> +
> +@subsection Configuring NAT for the virtual network switch
> +
> +If you intend to use the virtual network switch in NAT mode, you will
> +need to use nftables (or iptables) rules to set up IP masquerading.  The
> +following example shows how to use @code{nftables-service-type} to do
> +this:
> +
> +@example lisp
> +(service nftables-service-type
> +         (nftables-configuration
> +          (ruleset
> +           (plain-file "nftables.conf"
> +                       "\
> +table inet filter @{
> +
> +  chain input @{
> +    type filter hook input priority filter; policy drop;
> +    # Add your existing packet filtering rules here....

s/..../.../

> +    iifname "virbr0" udp dport 67 counter accept comment "allow dhcp on virbr0"
> +    iifname "virbr0" meta l4proto @{tcp, udp@} th dport 53 accept comment "allow dns on virbr0"
> +  @}
> +
> +  chain forward @{
> +    type filter hook forward priority filter; policy drop;
> +    # Add your existing forwarding rules here....

s/..../.../

> +    iifname "virbr0" accept comment "allow outbound traffic from virbr0"
> +    oifname "virbr0" ct state @{established, related @} accept comment "allow established traffic to virbr0"
> +  @}
> +
> +@}
> +
> +table inet nat @{
> +  chain postrouting @{
> +    type nat hook postrouting priority srcnat; policy accept;
> +    # Add your existing nat rules here...


> +    iifname "virbr0" ip daddr @{ 224.0.0.0/24, 255.255.255.255/32 @} return comment "don't masquerade to reserved address blocks"
> +    iifname "virbr0" oifname != "virbr0" masquerade comment "masquerade all outgoing traffic from VMs"
> +  @}
> +@}
> +"))))
> +@end example

I think the long lines (> 80 columns) may be a problem in PDF-rendered
documentation, possible info as well.  It'd be better to break the long
lines; perhaps possible via a backslash before the newline?

Indeed, looking at 'man 8 nft', it says:

--8<---------------cut here---------------start------------->8---
INPUT FILE FORMATS
   LEXICAL CONVENTIONS
       Input is parsed line-wise. When the last character of a line,
       just before the newline character, is a non-quoted backslash (\),
       the next line is treated as a continuation. Multiple commands on
       the same line can be separated using a semicolon (;).
--8<---------------cut here---------------end--------------->8---

Could you please send a v2 with the above requested changes?  I'd also
drop the first two commits of this series and stick to 'virtual bridge'
in this current one, for consistency and matching the vocabulaty the
interfaces actually use.

Thanks for working on this!

-- 
Maxim

Message #29 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 2/3] doc: cookbook: Clarify virtual network
 switches.
Date: Sat, 22 Mar 2025 11:20:32 +0000

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:

> Hi,
>
> 45mg <45mg.writes <at> gmail.com> writes:
>
>> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
>> libvirt] {Creating a virtual network switch}: Remove unnecessarily
>> noncommital language ("a few components/configurations, such as...").
>> Correct 'TUN interface', as bridges are currently used.  Add a link to
>> the libvirt Wiki for more information.
>
> I'm also not sure of the benefit here; we drop some words but refer the
> user to an external wiki page instead, which seems worst to me.

If you look carefully at the patch, you'll see that the dropping of
words doesn't actually remove any information; it just makes the
langauge a bit more definite and confident.

As I mentioned in my previous message [1], the official libvirt
documentation links to the Wiki, so it should be authoritative enough
for our purposes. The information in that article there is especially
relevant to the topic of this subsection, so I think it's worth having
the link.

[1] https://yhetil.org/guix/87ldsx725q.fsf <at> gmail.com/

Message #32 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 3/3] doc: cookbook: Document manual libvirt
 networking.
Date: Sat, 22 Mar 2025 11:40:10 +0000

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:

> Hi,
>
> 45mg <45mg.writes <at> gmail.com> writes:
>
>> * doc/guix-cookbook.texi (Virtual Machines): [Manual libvirt
>> networking]: New section.
>
> Thanks for writing this.
>
>> Change-Id: Ice79c5dc8183ec694ac8b846a5ec88cb98cac9ff
>> ---
>>  doc/guix-cookbook.texi | 120 +++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 120 insertions(+)
>>
>> diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
>> index 325b1d9c2a..338dba25be 100644
>> --- a/doc/guix-cookbook.texi
>> +++ b/doc/guix-cookbook.texi
>> @@ -3750,6 +3750,7 @@ Virtual Machines
>>  @menu
>>  * Network bridge for QEMU::
>>  * Routed network for libvirt::
>> +* Manual libvirt networking::
>>  @end menu
>>
>>  @node Network bridge for QEMU
>> @@ -3974,6 +3975,125 @@ Routed network for libvirt
>>  should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
>>  to verify that it functions correctly.
>>
>> +@node Manual libvirt networking
>> +@section Manual libvirt networking
>
> Perhaps this should be named 'Custom NAT-based network', as in Jamie's
> handbook, as every other configurations also involve manual steps?

Ok, makes sense.

>> +
>> +As mentioned in the preceding section (@pxref{Routed network for libvirt}),
>> +libvirt allows virtual networks to be defined via XML files and managed
>> +by the @command{virsh} command.  The details of the creation and removal
>> +of virtual network switches are handled by libvirt, so the user does not
>> +have to deal with them.
>
> As discussed previously, I think it may be best to stick to our existing
> terminology of 'virtual bridge' instead of 'virtual switch'.

See previous message [1].

>> +However, libvirt's handling of virtual network switches can sometimes
>> +clash with more complex networking setups.  In particular, the iptables
>> +rules inserted by libvirt for switches operating in the NAT mode can
>> +clash with existing iptables/nftables rules, leading to insecure or
>> +broken packet filtering.
>> +
>> +In such cases, the only solution is to manually set up a virtual network
>> +switch.  This section will provide instructions on how to do so using
>> +Guix System services.
>> +
>> +This section is based on
>> +@url{https://jamielinux.com/docs/libvirt-networking-handbook/custom-nat-based-network.html,
>> +the corresponding section from the (unofficial) libvirt Networking
>> +Handbook}.  It should be noted that at the time of writing (March 2025),
>> +this resource had not been updated since 2015, and is therefore somewhat
>> +outdated.  In particular, the creation of a `dummy interface' is no
>> +longer necessary.
>
> I would drop this paragraph.  The other sections are also based on that
> same handbook.  It's up to us to extract the good bits and avoid the
> obsolete one and keep our own doc up to date :-).

We should probably link to it somewhere. It provides more explanation
and context for the steps listed in this and the other sections. And
just in principle, we should probably cite our sources. But it would be
irresponsible to do so without mentioning that parts of it are
outdated... hence that paragraph.

I'm open to linking it somewhere else in the Cookbook, though. Thoughts?

>> +@subsection Creating the virtual network bridge
>> +
>> +The @code{static-networking-service-type} can be used to create a
>> +virtual network bridge and assign an IP address to it:
>
> 'network bridge', hm? ;-)

Yes. We are referring specifically to a virtual network interface here.
The virtual network bridge is one component of the virtual network
switch.

>> +
>> +@example lisp
>> +(service static-networking-service-type
>> +         (list (static-networking
>> +                ;; The default provision is 'networking; if you're using any
>> +                ;; other service with this provision, such as
>> +                ;; `network-manager-service-type`, then you need to change the
>> +                ;; default
>
> Use complete sentences for line comments (i.e. add a terminating period
> above).

Ok.

>> +                (provision '(static-networking))
>> +                (links
>> +                 (list (network-link
>> +                        (name "virbr0")
>> +                        (type 'bridge)
>> +                        (arguments '((stp_state . 1))))))
>
> I've never seen this stp_state argument; is it useful?  Perhaps it
> deserves a comment.

I have no idea what it does, but I think I needed it for the bridge to
work? The handbook also includes it (`brctl stp virbr10 on`).

>> +                (addresses
>> +                 (list (network-address
>> +                        (device "virbr0")
>> +                        (value "192.168.10.1/24")))))))
>> +@end example
>> +
>> +@subsection Running dnsmasq for the virtual network bridge
>> +
>> +The @code{dnsmasq-service-type} can be used to provide DNS and DHCP for
>> +guests connected to this virtual network switch:
>> +
>> +@example lisp
>> +(service dnsmasq-service-type
>> +         (dnsmasq-configuration
>> +          ;; You can have multiple instances of `dnsmasq-service-type` as long
>> +          ;; as each one has a different provision
>
> Missing ending period.

Ok.

>> +          (provision '(dnsmasq-virbr0))
>> +          (extra-options (list
>> +                          ;; Only bind to the virtual bridge. This
>> +                          ;; avoids conflicts with other running
>> +                          ;; DNSMASQ instances.
>> +                          "--except-interface=lo"
>> +                          "--interface=virbr0"
>> +                          "--bind-dynamic"
>> +                          ;; IPv4 addresses to offer to VMs. This
>> +                          ;; should match the chosen subnet.
>> +                          "--dhcp-range=192.168.10.2,192.168.10.254"))))
>> +@end example
>> +
>> +@subsection Configuring NAT for the virtual network switch
>> +
>> +If you intend to use the virtual network switch in NAT mode, you will
>> +need to use nftables (or iptables) rules to set up IP masquerading.  The
>> +following example shows how to use @code{nftables-service-type} to do
>> +this:
>> +
>> +@example lisp
>> +(service nftables-service-type
>> +         (nftables-configuration
>> +          (ruleset
>> +           (plain-file "nftables.conf"
>> +                       "\
>> +table inet filter @{
>> +
>> +  chain input @{
>> +    type filter hook input priority filter; policy drop;
>> +    # Add your existing packet filtering rules here....
>
> s/..../.../

Ok.

>> +    iifname "virbr0" udp dport 67 counter accept comment "allow dhcp on virbr0"
>> +    iifname "virbr0" meta l4proto @{tcp, udp@} th dport 53 accept comment "allow dns on virbr0"
>> +  @}
>> +
>> +  chain forward @{
>> +    type filter hook forward priority filter; policy drop;
>> +    # Add your existing forwarding rules here....
>
> s/..../.../

Ok.

>> +    iifname "virbr0" accept comment "allow outbound traffic from virbr0"
>> +    oifname "virbr0" ct state @{established, related @} accept comment "allow established traffic to virbr0"
>> +  @}
>> +
>> +@}
>> +
>> +table inet nat @{
>> +  chain postrouting @{
>> +    type nat hook postrouting priority srcnat; policy accept;
>> +    # Add your existing nat rules here...
>
>
>> +    iifname "virbr0" ip daddr @{ 224.0.0.0/24, 255.255.255.255/32 @} return comment "don't masquerade to reserved address blocks"
>> +    iifname "virbr0" oifname != "virbr0" masquerade comment "masquerade all outgoing traffic from VMs"
>> +  @}
>> +@}
>> +"))))
>> +@end example
>
> I think the long lines (> 80 columns) may be a problem in PDF-rendered
> documentation, possible info as well.  It'd be better to break the long
> lines; perhaps possible via a backslash before the newline?
>
> Indeed, looking at 'man 8 nft', it says:
>
> --8<---------------cut here---------------start------------->8---
> INPUT FILE FORMATS
>    LEXICAL CONVENTIONS
>        Input is parsed line-wise. When the last character of a line,
>        just before the newline character, is a non-quoted backslash (\),
>        the next line is treated as a continuation. Multiple commands on
>        the same line can be separated using a semicolon (;).
> --8<---------------cut here---------------end--------------->8---

I'll look into it.

> Could you please send a v2 with the above requested changes?  I'd also
> drop the first two commits of this series and stick to 'virtual bridge'
> in this current one, for consistency and matching the vocabulaty the
> interfaces actually use.

Sure, but first let's see if we can come to a consensus on the
terminology here. See [1].

> Thanks for working on this!
>
> --
> Maxim

[1] https://yhetil.org/guix/87ldsx725q.fsf <at> gmail.com/

Message #35 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 1/3] doc: cookbook: Fix terminology for
 libvirt virtual network switches.
Date: Sat, 22 Mar 2025 21:16:19 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:
>
>> Hi,
>>
>> 45mg <45mg.writes <at> gmail.com> writes:
>>
>>> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
>>> libvirt]: Replace the term 'virtual bridge' with 'virtual network
>>> switch'.  This is the term used by the libvirt Wiki to refer to the
>>> combined setup of a 'virtual bridge' network interface, dnsmasq instance
>>> bound to it, and firewall rules associated with it.
>>
>> I'm not sure 'switch' is clearer than 'bridge' in the context of
>> libvirt; and I doubt a wiki has much authority on the topic.  I find the
>> 'bridge' terminology most common on Linux, and it matches to options
>> documented in libvirt-related tools such as `man virt-install` from the
>> virt-manager package:
>>
>> --8<---------------cut here---------------start------------->8---
>>        bridge=BRIDGE
>>               Connect to a bridge device in the host called BRIDGE.  Use  this
>>               option  if the host has static networking config & the guest re‐
>>               quires full outbound and inbound connectivity to/from  the  LAN.
>>               Also use this if live migration will be used with this guest.
>> --8<---------------cut here---------------end--------------->8---
>>
>> So I'm not convinced of the value of the proposed change.
>
> The idea is to use 'switch' to refer to "the combined setup of a
> 'virtual bridge' network interface, dnsmasq instance bound to it, and
> firewall rules associated with it", which is what libvirt creates from a
> 'virtual network' specified in an XML file.
>
> 'Bridge' is ambiguous because it is sometimes used with this meaning
> (for example, in the target of this patch), and sometimes to refer
> specifically to the virtual network device called a 'bridge' (as in your
> example). This quickly gets confusing; patch 3/3 in particular would be
> a lot more confusing if I didn't introduce a term to make the
> distinction.
>
> The Wiki should be authoritative enough for our purposes, given that the
> official documentation links to it. For example, from
> [libvirt: Network XML format](https://libvirt.org/formatnetwork.html):

OK.  I guess that now that I understand the fine distinction of using
'virtual switch' for the complete construction vs 'virtual bridge' for
the Linux-side implementation of one of its parts, that could make
sense.

I don't mind to keep it then, if you think it helps clarify the text.

-- 
Thanks,
Maxim

Message #38 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 2/3] doc: cookbook: Clarify virtual network
 switches.
Date: Sat, 22 Mar 2025 21:18:09 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:
>
>> Hi,
>>
>> 45mg <45mg.writes <at> gmail.com> writes:
>>
>>> * doc/guix-cookbook.texi (Virtual Machines): [Routed network for
>>> libvirt] {Creating a virtual network switch}: Remove unnecessarily
>>> noncommital language ("a few components/configurations, such as...").
>>> Correct 'TUN interface', as bridges are currently used.  Add a link to
>>> the libvirt Wiki for more information.
>>
>> I'm also not sure of the benefit here; we drop some words but refer the
>> user to an external wiki page instead, which seems worst to me.
>
> If you look carefully at the patch, you'll see that the dropping of
> words doesn't actually remove any information; it just makes the
> langauge a bit more definite and confident.
>
> As I mentioned in my previous message [1], the official libvirt
> documentation links to the Wiki, so it should be authoritative enough
> for our purposes. The information in that article there is especially
> relevant to the topic of this subsection, so I think it's worth having
> the link.

OK, I'm convinced.

-- 
Thanks,
Maxim

Message #41 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH 3/3] doc: cookbook: Document manual libvirt
 networking.
Date: Sat, 22 Mar 2025 21:20:30 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

[...]

> Sure, but first let's see if we can come to a consensus on the
> terminology here. See [1].

Our two people consensus has been achieved (I agree to use your 2 first
commits).  More people are welcome to weigh in, of course.

-- 
Thanks,
Maxim

Message #44 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v2 0/3] doc: cookbook: Custom NAT-based libvirt networks.
Date: Sat, 22 Mar 2025 18:27:35 +0530

Changes from v1:
1/3:
- Added copyright.
- Modified commit message to include the discussed rationale for this change.
3/3: Addressed Maxim's review [1].
Unaddressed, pending items [2]:
- Link to libvirt networking handbook - keep, move, or ditch?
- What does 'stp_state' param for a bridge actually do?

[1] https://yhetil.org/guix/87y0wxia9h.fsf <at> gmail.com/
[2] https://yhetil.org/guix/87frj570px.fsf <at> gmail.com/

45mg (3):
  doc: cookbook: Fix terminology for libvirt virtual network switches.
  doc: cookbook: Clarify virtual network switches.
  doc: cookbook: Custom NAT-based libvirt networks.

 doc/guix-cookbook.texi | 162 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 146 insertions(+), 16 deletions(-)


base-commit: 9eddd250b773043fcac5e7eaa4939e5a2d9940bd
-- 
2.48.1

Message #47 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v2 1/3] doc: cookbook: Fix terminology for libvirt virtual
 network switches.
Date: Sat, 22 Mar 2025 18:30:11 +0530

* doc/guix-cookbook.texi (Virtual Machines) [Routed network for
libvirt]: Replace the term 'virtual bridge' with 'virtual network
switch'.  This is the term used by the libvirt Wiki to refer to the
combined setup of a 'virtual bridge' network interface, dnsmasq instance
bound to it, and firewall rules associated with it; 'bridge' is
ambiguous because it is sometimes used with this meaning, and sometimes
to refer specifically to the virtual network device called a 'bridge'.

Change-Id: Ibd10fe76321eb61e9ca23d8124634d1108d4faad
---
 doc/guix-cookbook.texi | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index d9b98a2ab3..a0d148f469 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -25,6 +25,7 @@
 Copyright @copyright{} 2023-2024 Ludovic Courtès@*
 Copyright @copyright{} 2023 Thomas Ieong@*
 Copyright @copyright{} 2024 Florian Pelz@*
+Copyright @copyright{} 2025 45mg@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -3879,29 +3880,29 @@ Routed network for libvirt
 @section Routed network for libvirt
 @cindex Virtual network bridge interface
 @cindex networking, virtual bridge
-@cindex libvirt, virtual network bridge
+@cindex libvirt, virtual network switch
 
 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
+case, the next best option is to use a @emph{virtual network switch}
+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
+@subsection Creating a virtual network switch
 
-A virtual network bridge consists of a few components/configurations,
+A virtual network switch 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
+switch.  You first need to choose a network subnet for your virtual
+switch; 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:
 
-- 
2.48.1

Message #50 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v2 2/3] doc: cookbook: Clarify virtual network switches.
Date: Sat, 22 Mar 2025 18:30:12 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Routed network for
libvirt] {Creating a virtual network switch}: Remove unnecessarily
noncommital language ("a few components/configurations, such as...").
Correct 'TUN interface', as bridges are currently used.  Add a link to
the libvirt Wiki for more information.

Change-Id: I6ffdeca8e4d32155c8cce547d4930bf1b0cb471b
---
 doc/guix-cookbook.texi | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index a0d148f469..9c56790edc 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3897,14 +3897,19 @@ Routed network for libvirt
 
 @subsection Creating a virtual network switch
 
-A virtual network switch 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
-switch.  You first need to choose a network subnet for your virtual
-switch; 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:
+A virtual network switch consists of a virtual network device called a
+`virtual bridge', DHCP server (dnsmasq) and firewall rules
+(iptables). See the
+@url{https://wiki.libvirt.org/VirtualNetworking.html, libvirt Wiki
+article on Virtual Networking} for more details on the modes of
+operation, management and implementation of virtual network switches.
+
+The @command{virsh} command, provided by the @code{libvirt}
+package, makes it very easy to create a virtual switch.  You first need
+to choose a network subnet for your virtual switch; 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>
-- 
2.48.1

Message #53 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v2 3/3] doc: cookbook: Custom NAT-based libvirt networks.
Date: Sat, 22 Mar 2025 18:30:13 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Custom NAT-based network
for libvirt]: New section.

Change-Id: Ice79c5dc8183ec694ac8b846a5ec88cb98cac9ff
---
 doc/guix-cookbook.texi | 124 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 9c56790edc..68cd05e6f2 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3751,6 +3751,7 @@ Virtual Machines
 @menu
 * Network bridge for QEMU::
 * Routed network for libvirt::
+* Custom NAT-based network for libvirt::
 @end menu
 
 @node Network bridge for QEMU
@@ -3975,6 +3976,129 @@ Routed network for libvirt
 should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
 to verify that it functions correctly.
 
+@node Custom NAT-based network for libvirt
+@section Custom NAT-based network for libvirt
+
+As mentioned in the preceding section (@pxref{Routed network for libvirt}),
+libvirt allows virtual networks to be defined via XML files and managed
+by the @command{virsh} command.  The details of the creation and removal
+of virtual network switches are handled by libvirt, so the user does not
+have to deal with them.
+
+However, libvirt's handling of virtual network switches can sometimes
+clash with more complex networking setups.  In particular, the iptables
+rules inserted by libvirt for switches operating in the NAT mode can
+clash with existing iptables/nftables rules, leading to insecure or
+broken packet filtering.
+
+In such cases, the only solution is to manually set up a virtual network
+switch.  This section will provide instructions on how to do so using
+Guix System services.
+
+This section is based on
+@url{https://jamielinux.com/docs/libvirt-networking-handbook/custom-nat-based-network.html,
+the corresponding section from the (unofficial) libvirt Networking
+Handbook}.  It should be noted that at the time of writing (March 2025),
+this resource had not been updated since 2015, and is therefore somewhat
+outdated.  In particular, the creation of a `dummy interface' is no
+longer necessary.
+
+@subsection Creating the virtual network bridge
+
+The @code{static-networking-service-type} can be used to create a
+virtual network bridge and assign an IP address to it:
+
+@example lisp
+(service static-networking-service-type
+         (list (static-networking
+                ;; The default provision is 'networking; if you're using any
+                ;; other service with this provision, such as
+                ;; `network-manager-service-type`, then you need to change the
+                ;; default.
+                (provision '(static-networking))
+                (links
+                 (list (network-link
+                        (name "virbr0")
+                        (type 'bridge)
+                        (arguments '((stp_state . 1))))))
+                (addresses
+                 (list (network-address
+                        (device "virbr0")
+                        (value "192.168.10.1/24")))))))
+@end example
+
+@subsection Running dnsmasq for the virtual network bridge
+
+The @code{dnsmasq-service-type} can be used to provide DNS and DHCP for
+guests connected to this virtual network switch:
+
+@example lisp
+(service dnsmasq-service-type
+         (dnsmasq-configuration
+          ;; You can have multiple instances of `dnsmasq-service-type` as long
+          ;; as each one has a different provision.
+          (provision '(dnsmasq-virbr0))
+          (extra-options (list
+                          ;; Only bind to the virtual bridge. This
+                          ;; avoids conflicts with other running
+                          ;; dnsmasq instances.
+                          "--except-interface=lo"
+                          "--interface=virbr0"
+                          "--bind-dynamic"
+                          ;; IPv4 addresses to offer to VMs. This
+                          ;; should match the chosen subnet.
+                          "--dhcp-range=192.168.10.2,192.168.10.254"))))
+@end example
+
+@subsection Configuring NAT for the virtual network switch
+
+If you intend to use the virtual network switch in NAT mode, you will
+need to use nftables (or iptables) rules to set up IP masquerading.  The
+following example shows how to use @code{nftables-service-type} to do
+this:
+
+@example lisp
+(service nftables-service-type
+         (nftables-configuration
+          (ruleset
+           (plain-file "nftables.conf"
+                       "\
+table inet filter @{
+
+  chain input @{
+    type filter hook input priority filter; policy drop;
+    # Add your existing packet filtering rules here...
+    iifname virbr0 udp dport 67 counter accept comment \"allow dhcp on virbr0\"
+    iifname virbr0 meta l4proto @{tcp, udp@} th dport 53 accept \\
+        comment \"allow dns on virbr0\"
+  @}
+
+  chain forward @{
+    type filter hook forward priority filter; policy drop;
+    # Add your existing forwarding rules here...
+    iifname virbr0 accept comment \"allow outbound traffic from virbr0\"
+    oifname virbr0 ct state @{established, related @} accept \\
+        comment \"allow established traffic to virbr0\"
+  @}
+
+@}
+
+table inet nat @{
+  chain postrouting @{
+    type nat hook postrouting priority srcnat; policy accept;
+    # Add your existing nat rules here...
+    iifname virbr0 ip daddr @{ 224.0.0.0/24, 255.255.255.255/32 @} return \\
+        comment \"don't masquerade to reserved address blocks\"
+    iifname virbr0 oifname != virbr0 masquerade \\
+        comment \"masquerade all outgoing traffic from VMs\"
+  @}
+@}
+"))))
+@end example
+
+Ensure that you have IPv4 forwarding enabled (you can use
+@code{sysctl-service-type} for this).
+
 @c *********************************************************************
 @node Advanced package management
 @chapter Advanced package management
-- 
2.48.1

Message #56 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153 <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH v2 0/3] doc: cookbook: Custom NAT-based
 libvirt networks.
Date: Sun, 23 Mar 2025 00:50:17 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> Changes from v1:
> 1/3:
> - Added copyright.
> - Modified commit message to include the discussed rationale for this change.
> 3/3: Addressed Maxim's review [1].
> Unaddressed, pending items [2]:
> - Link to libvirt networking handbook - keep, move, or ditch?

Not sure.  If we link to it, I'd do so from the first section covering
material sourced from it.

> - What does 'stp_state' param for a bridge actually do?

Apparently it means this, per man 8 bridge:

       state STP_STATE
              The spanning tree state, see the state option of bridge
              link set for supported states.

and from the same manual:

       state STP_STATE
              the operation state of the vlan. One may enter STP state
              name (case insensitive), or one of the numbers below.
              Negative inputs are ignored, and unrecognized names return
              an error. Note that the state is set only for the vlan of
              the specified device, e.g. if it is a bridge port then the
              state will be set only for the vlan of the port.

              0 - vlan is in STP DISABLED state. Make this vlan
              completely inactive for STP. This is also called BPDU
              filter and could be used to disable STP on an untrusted
              vlan.

              1 - vlan is in STP LISTENING state. Only valid if STP is
              enabled on the bridge. In this state the vlan listens for
              STP BPDUs and drops all other traffic frames.

              2 - vlan is in STP LEARNING state. Only valid if STP is
              enabled on the bridge. In this state the vlan will accept
              traffic only for the purpose of updating MAC address
              tables.

              3 - vlan is in STP FORWARDING state. This is the default
              vlan state.

              4 - vlan is in STP BLOCKING state. Only valid if STP is
              enabled on the bridge. This state is used during the STP
              election process. In this state, the vlan will only process
              STP BPDUs.

So you could add comment mentioning that this is to configure the bridge
in the listening @acronym{STP, Spanning Tree State} or similar, or
something nicer if you have a better understanding of why that is useful.

-- 
Thanks,
Maxim

Message #59 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v3 0/3] doc: cookbook: Custom NAT-based libvirt networks.
Date: Sat, 22 Mar 2025 22:33:14 +0530

Changes from v2:
3/3:
. Removed the 'stp_state' argument for creating the bridge; further testing
  revealed that it isn't actually necessary.
. Moved the link to the libvirt Networking Handbook to a new section
  'References'.

45mg (3):
  doc: cookbook: Fix terminology for libvirt virtual network switches.
  doc: cookbook: Clarify virtual network switches.
  doc: cookbook: Custom NAT-based libvirt networks.

 doc/guix-cookbook.texi | 166 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 150 insertions(+), 16 deletions(-)


base-commit: fbfd2b93831978aadbb96f32cafdab997b04c6c6
-- 
2.49.0

Message #62 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v3 1/3] doc: cookbook: Fix terminology for libvirt virtual
 network switches.
Date: Sat, 22 Mar 2025 22:33:15 +0530

* doc/guix-cookbook.texi (Virtual Machines) [Routed network for
libvirt]: Replace the term 'virtual bridge' with 'virtual network
switch'.  This is the term used by the libvirt Wiki to refer to the
combined setup of a 'virtual bridge' network interface, dnsmasq instance
bound to it, and firewall rules associated with it; 'bridge' is
ambiguous because it is sometimes used with this meaning, and sometimes
to refer specifically to the virtual network device called a 'bridge'.

Change-Id: Ibd10fe76321eb61e9ca23d8124634d1108d4faad
---
 doc/guix-cookbook.texi | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index d9b98a2ab3..a0d148f469 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -25,6 +25,7 @@
 Copyright @copyright{} 2023-2024 Ludovic Courtès@*
 Copyright @copyright{} 2023 Thomas Ieong@*
 Copyright @copyright{} 2024 Florian Pelz@*
+Copyright @copyright{} 2025 45mg@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -3879,29 +3880,29 @@ Routed network for libvirt
 @section Routed network for libvirt
 @cindex Virtual network bridge interface
 @cindex networking, virtual bridge
-@cindex libvirt, virtual network bridge
+@cindex libvirt, virtual network switch
 
 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
+case, the next best option is to use a @emph{virtual network switch}
+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
+@subsection Creating a virtual network switch
 
-A virtual network bridge consists of a few components/configurations,
+A virtual network switch 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
+switch.  You first need to choose a network subnet for your virtual
+switch; 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:
 
-- 
2.49.0

Message #65 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v3 2/3] doc: cookbook: Clarify virtual network switches.
Date: Sat, 22 Mar 2025 22:33:16 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Routed network for
libvirt] {Creating a virtual network switch}: Remove unnecessarily
noncommital language ("a few components/configurations, such as...").
Correct 'TUN interface', as bridges are currently used.  Add a link to
the libvirt Wiki for more information.

Change-Id: I6ffdeca8e4d32155c8cce547d4930bf1b0cb471b
---
 doc/guix-cookbook.texi | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index a0d148f469..9c56790edc 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3897,14 +3897,19 @@ Routed network for libvirt
 
 @subsection Creating a virtual network switch
 
-A virtual network switch 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
-switch.  You first need to choose a network subnet for your virtual
-switch; 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:
+A virtual network switch consists of a virtual network device called a
+`virtual bridge', DHCP server (dnsmasq) and firewall rules
+(iptables). See the
+@url{https://wiki.libvirt.org/VirtualNetworking.html, libvirt Wiki
+article on Virtual Networking} for more details on the modes of
+operation, management and implementation of virtual network switches.
+
+The @command{virsh} command, provided by the @code{libvirt}
+package, makes it very easy to create a virtual switch.  You first need
+to choose a network subnet for your virtual switch; 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>
-- 
2.49.0

Message #68 received at 77153 <at> debbugs.gnu.org (full text, mbox):

From: 45mg <45mg.writes <at> gmail.com>
To: 77153 <at> debbugs.gnu.org
Cc: 45mg <45mg.writes <at> gmail.com>
Subject: [PATCH v3 3/3] doc: cookbook: Custom NAT-based libvirt networks.
Date: Sat, 22 Mar 2025 22:33:17 +0530

* doc/guix-cookbook.texi (Virtual Machines): [Custom NAT-based network
for libvirt]: New section.
[References]: New section.

Change-Id: Ice79c5dc8183ec694ac8b846a5ec88cb98cac9ff
---
 doc/guix-cookbook.texi | 128 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 9c56790edc..2a49f4b27f 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3751,6 +3751,8 @@ Virtual Machines
 @menu
 * Network bridge for QEMU::
 * Routed network for libvirt::
+* Custom NAT-based network for libvirt::
+* References::
 @end menu
 
 @node Network bridge for QEMU
@@ -3975,6 +3977,132 @@ Routed network for libvirt
 should work from within your VM; you can e.g.@: run @samp{ping gnu.org}
 to verify that it functions correctly.
 
+@node Custom NAT-based network for libvirt
+@section Custom NAT-based network for libvirt
+
+As mentioned in the preceding section (@pxref{Routed network for libvirt}),
+libvirt allows virtual networks to be defined via XML files and managed
+by the @command{virsh} command.  The details of the creation and removal
+of virtual network switches are handled by libvirt, so the user does not
+have to deal with them.
+
+However, libvirt's handling of virtual network switches can sometimes
+clash with more complex networking setups.  In particular, the iptables
+rules inserted by libvirt for switches operating in the NAT mode can
+clash with existing iptables/nftables rules, leading to insecure or
+broken packet filtering.
+
+In such cases, the only solution is to manually set up a virtual network
+switch.  This section will provide instructions on how to do so using
+Guix System services.
+
+@subsection Creating the virtual network bridge
+
+The @code{static-networking-service-type} can be used to create a
+virtual network bridge and assign an IP address to it:
+
+@example lisp
+(service static-networking-service-type
+         (list (static-networking
+                ;; The default provision is 'networking; if you're using any
+                ;; other service with this provision, such as
+                ;; `network-manager-service-type`, then you need to change the
+                ;; default.
+                (provision '(static-networking))
+                (links
+                 (list (network-link
+                        (name "virbr0")
+                        (type 'bridge)
+                        (arguments '()))))
+                (addresses
+                 (list (network-address
+                        (device "virbr0")
+                        (value "192.168.10.1/24")))))))
+@end example
+
+@subsection Running dnsmasq for the virtual network bridge
+
+The @code{dnsmasq-service-type} can be used to provide DNS and DHCP for
+guests connected to this virtual network switch:
+
+@example lisp
+(service dnsmasq-service-type
+         (dnsmasq-configuration
+          ;; You can have multiple instances of `dnsmasq-service-type` as long
+          ;; as each one has a different provision.
+          (provision '(dnsmasq-virbr0))
+          (extra-options (list
+                          ;; Only bind to the virtual bridge. This
+                          ;; avoids conflicts with other running
+                          ;; dnsmasq instances.
+                          "--except-interface=lo"
+                          "--interface=virbr0"
+                          "--bind-dynamic"
+                          ;; IPv4 addresses to offer to VMs. This
+                          ;; should match the chosen subnet.
+                          "--dhcp-range=192.168.10.2,192.168.10.254"))))
+@end example
+
+@subsection Configuring NAT for the virtual network switch
+
+If you intend to use the virtual network switch in NAT mode, you will
+need to use nftables (or iptables) rules to set up IP masquerading.  The
+following example shows how to use @code{nftables-service-type} to do
+this:
+
+@example lisp
+(service nftables-service-type
+         (nftables-configuration
+          (ruleset
+           (plain-file "nftables.conf"
+                       "\
+table inet filter @{
+
+  chain input @{
+    type filter hook input priority filter; policy drop;
+    # Add your existing packet filtering rules here...
+    iifname virbr0 udp dport 67 counter accept comment \"allow dhcp on virbr0\"
+    iifname virbr0 meta l4proto @{tcp, udp@} th dport 53 accept \\
+        comment \"allow dns on virbr0\"
+  @}
+
+  chain forward @{
+    type filter hook forward priority filter; policy drop;
+    # Add your existing forwarding rules here...
+    iifname virbr0 accept comment \"allow outbound traffic from virbr0\"
+    oifname virbr0 ct state @{established, related @} accept \\
+        comment \"allow established traffic to virbr0\"
+  @}
+
+@}
+
+table inet nat @{
+  chain postrouting @{
+    type nat hook postrouting priority srcnat; policy accept;
+    # Add your existing nat rules here...
+    iifname virbr0 ip daddr @{ 224.0.0.0/24, 255.255.255.255/32 @} return \\
+        comment \"don't masquerade to reserved address blocks\"
+    iifname virbr0 oifname != virbr0 masquerade \\
+        comment \"masquerade all outgoing traffic from VMs\"
+  @}
+@}
+"))))
+@end example
+
+Ensure that you have IPv4 forwarding enabled (you can use
+@code{sysctl-service-type} for this).
+
+@section References
+
+@itemize
+@item
+@uref{https://jamielinux.com/docs/libvirt-networking-handbook/index.html,
+The (unofficial) libvirt Networking Handbook}@*
+Note that this resource is rather outdated at the time of writing (as of
+March 2025, it was last updated in 2015).  Nevertheless, the authors of
+this chapter have found it to be a valuable source of information.
+@end itemize
+
 @c *********************************************************************
 @node Advanced package management
 @chapter Advanced package management
-- 
2.49.0

Message #73 received at 77153-done <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: 45mg <45mg.writes <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 77153-done <at> debbugs.gnu.org
Subject: Re: [bug#77153] [PATCH v3 3/3] doc: cookbook: Custom NAT-based
 libvirt networks.
Date: Sun, 23 Mar 2025 13:14:44 +0900

Hi,

45mg <45mg.writes <at> gmail.com> writes:

> * doc/guix-cookbook.texi (Virtual Machines): [Custom NAT-based network
> for libvirt]: New section.
> [References]: New section.

I needed to add a missing @node for the new section and refresh the
menus (C-c C-u C-a in texinfo-mode in Emacs), resulting in:

--8<---------------cut here---------------start------------->8---
Unstaged changes (1)
modified   doc/guix-cookbook.texi
@@ -167,6 +167,8 @@ Top
 
 * Network bridge for QEMU::
 * Routed network for libvirt::
+* Custom NAT-based network for libvirt::
+* References: VM References.    Further reading on virtual machines.
 
 Advanced package management
 
@@ -3752,7 +3754,7 @@ Virtual Machines
 * Network bridge for QEMU::
 * Routed network for libvirt::
 * Custom NAT-based network for libvirt::
-* References::
+* References: VM References.    Further reading on virtual machines.
 @end menu
 
 @node Network bridge for QEMU
@@ -4092,6 +4094,7 @@ Custom NAT-based network for libvirt
 Ensure that you have IPv4 forwarding enabled (you can use
 @code{sysctl-service-type} for this).
 
+@node VM References
 @section References
 
 @itemize
--8<---------------cut here---------------end--------------->8---

I struggled a bit because nodes must apparently have unique names (and
they are what the menus references, so previously it'd refer to a
different section).

In the end I chose to name the node differently from the section, and
use the alternate 'Name: Node name.' form for a menu entry.  See (info
"(texinfo) Menu Parts").

Another small thing: GNU ChangeLog commit messages should document
changes, not reasoning.  It's OK and welcome to add a rationale to the
commit message, but it should appear in a paragraph between the summary
line and the changelog.

Pushed as commit da09013802.

-- 
Thanks,
Maxim

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.