Subject: [bug#77153] [PATCH 1/3] doc: cookbook: Fix terminology for libvirt virtual network switches.

From: 45mg <[email-masked]>
Date: Sat, 22 Mar 2025 11:09:05 +0000

Maxim Cournoyer <[email-masked]> writes:

> Hi,
>
> 45mg <[email-masked]> 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.