[bug#77153,2/3] doc: cookbook: Clarify virtual network switches.
Commit Message
* 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(-)
Comments
Hi,
45mg <45mg.writes@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.
Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> Hi,
>
> 45mg <45mg.writes@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@gmail.com/
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] {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.
@@ -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>