[bug#77153,1/3] doc: cookbook: Fix terminology for libvirt virtual network switches.
Commit Message
* 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(-)
base-commit: 9eddd250b773043fcac5e7eaa4939e5a2d9940bd
Comments
Hi,
45mg <45mg.writes@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.
Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> Hi,
>
> 45mg <45mg.writes@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.
Hi,
45mg <45mg.writes@gmail.com> writes:
> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Hi,
>>
>> 45mg <45mg.writes@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.
@@ -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: