[pve-devel] [PATCH docs v2 0/3] network: update & reword

[pve-devel] [PATCH docs v2 0/3] network: update & reword

[Aaron Lauterer]

Update the network section to
- remove mentioning ifup & ifdown as it can break connections of running
guests
- ifupdown2 is default now, we can remove the verbose install guide
- rework the introduction to make a few conecpts clear to people that
are not used to it yet

changes since v1:
* add note about ifupdown2 on a PVE on top of Debian installation

Aaron Lauterer (3):
  network: remove ifup ifdown as it won't reattach guests
  network: adapt apply config section to PVE 7
  network: rework introduction for people with less experience

 pve-network.adoc | 62 +++++++++++++++++++++++++-----------------------
 1 file changed, 32 insertions(+), 30 deletions(-)

-- 
2.30.2

[pve-devel] [PATCH docs v2 1/3] network: remove ifup ifdown as it won't reattach guests

[Aaron Lauterer]

Mentioning 'ifup' and 'ifdown' can lead to users running into situations
where they take down one interface, for example an vmbrX. In this
situation the connection to the guests will be lost and not
reestablished automatically if the interface is brought up again with
'ifup'. The better way to apply network changes is to run 'ifreload -a'.

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
 pve-network.adoc | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index c5e9a17..a33b90c 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -12,9 +12,6 @@ complete format description. All {pve} tools try hard to keep direct
 user modifications, but using the GUI is still preferable, because it
 protects you from errors.
 
-Once the network is configured, you can use the Debian traditional tools `ifup`
-and `ifdown` commands to bring interfaces up and down.
-
 Apply Network Changes
 ~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.30.2

[pve-devel] [PATCH docs v2 2/3] network: adapt apply config section to PVE 7

[Aaron Lauterer]

ifupdown2 is now installed by default, we can therefore omit the whole
installation part except a small note for people who installed PVE on
top of Debian.

also mention the CLI variant for users who like to edit the network
config directly or are using some config management tools

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
changes: add note about installing ifupdown2 if PVE was installed on
top of Debian

 pve-network.adoc | 33 +++++++++++----------------------
 1 file changed, 11 insertions(+), 22 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index a33b90c..eab0e02 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -24,34 +24,23 @@ inaccessible.
 Reboot Node to apply
 ^^^^^^^^^^^^^^^^^^^^
 
-With the default installed `ifupdown` network managing package you need to
-reboot to commit any pending network changes. Most of the time, the basic {pve}
-network setup is stable and does not change often, so rebooting should not be
-required often.
+One way to apply a new network configuration is to reboot the node.
 
 Reload Network with ifupdown2
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-With the optional `ifupdown2` network managing package you also can reload the
-network configuration live, without requiring a reboot.
+With the 'ifupdown2' package (default since {pve} 7), it is possible to apply
+network configuration changes without a reboot. If you change the network
+configuration via the GUI, you can click the 'Apply Configuration' button. Run
+the following command if you make changes directly to the
+`/etc/network/interfaces` file:
 
-Since {pve} 6.1 you can apply pending network changes over the web-interface,
-using the 'Apply Configuration' button in the 'Network' panel of a node.
-
-To install 'ifupdown2' ensure you have the latest {pve} updates installed, then
-
-WARNING: installing 'ifupdown2' will remove 'ifupdown', but as the removal
-scripts of 'ifupdown' before version '0.8.35+pve1' have a issue where network
-is fully stopped on removal footnote:[Introduced with Debian Buster:
-https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=945877] you *must* ensure
-that you have a up to date 'ifupdown' package version.
-
-For the installation itself you can then simply do:
-
- apt install ifupdown2
+----
+ ifreload -a
+----
 
-With that you're all set. You can also switch back to the 'ifupdown' variant at
-any time, if you run into issues.
+NOTE: If you installed {pve} on top of Debian, make sure 'ifupdown2' is
+installed: 'apt install ifupdown2'
 
 Naming Conventions
 ~~~~~~~~~~~~~~~~~~
-- 
2.30.2

[pve-devel] [PATCH docs v2 3/3] network: rework introduction for people with less experience

[Aaron Lauterer]

Mentioning explicitly, that the vmbr interfaces can be thought of as a
virtual switch and what can be done overall in the introduction will
hopefully help new users to grasp the networking more quickly.

Also mention the SDN to point people in that direction if they need it

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
 pve-network.adoc | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index eab0e02..8ad9903 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -5,13 +5,26 @@ ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
 
-Network configuration can be done either via the GUI, or by manually
-editing the file `/etc/network/interfaces`, which contains the
-whole network configuration. The  `interfaces(5)` manual page contains the
-complete format description. All {pve} tools try hard to keep direct
-user modifications, but using the GUI is still preferable, because it
+{pve} is using the Linux network stack. This provides a lot of flexibility on
+how to set up the network on the {pve} nodes. The configuration can be done
+either via the GUI, or by manually editing the file `/etc/network/interfaces`,
+which contains the whole network configuration. The  `interfaces(5)` manual
+page contains the complete format description. All {pve} tools try hard to keep
+direct user modifications, but using the GUI is still preferable, because it
 protects you from errors.
 
+A 'vmbr' interface is needed to connect guests to the underlying physical
+network.  They are a Linux bridge which can be thought of as a virtual switch
+to which the guests and physical interfaces are connected to.  This section
+provides some examples on how the network can be set up to accomodate different
+use cases like redundancy with a xref:sysadmin_network_bond['bond'],
+xref:sysadmin_network_vlan['vlans'] or
+xref:sysadmin_network_routed['routed'] and
+xref:sysadmin_network_masquerading['NAT'] setups.
+
+The xref:chapter_pvesdn[Software Defined Network] is an option for more complex
+virtual networks in {pve} clusters.
+
 Apply Network Changes
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -153,6 +166,7 @@ physical network. The network, in turn, sees each virtual machine as
 having its own MAC, even though there is only one network cable
 connecting all of these VMs to the network.
 
+[[sysadmin_network_routed]]
 Routed Configuration
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -195,6 +209,7 @@ iface vmbr0 inet static
 ----
 
 
+[[sysadmin_network_masquerading]]
 Masquerading (NAT) with `iptables`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -247,7 +262,7 @@ https://lwn.net/Articles/370152/[Patch on netdev-list introducing conntrack zone
 https://blog.lobraun.de/2019/05/19/prox/[Blog post with a good explanation by using TRACE in the raw table]
 
 
-
+[[sysadmin_network_bond]]
 Linux Bond
 ~~~~~~~~~~
 
@@ -385,6 +400,7 @@ iface vmbr0 inet static
 ----
 
 
+[[sysadmin_network_vlan]]
 VLAN 802.1Q
 ~~~~~~~~~~~
 
-- 
2.30.2

Re: [pve-devel] [PATCH docs v2 0/3] network: update & reword

[Aaron Lauterer]

ping?

On 6/2/22 11:22, Aaron Lauterer wrote:
> Update the network section to
> - remove mentioning ifup & ifdown as it can break connections of running
> guests
> - ifupdown2 is default now, we can remove the verbose install guide
> - rework the introduction to make a few conecpts clear to people that
> are not used to it yet
> 
> changes since v1:
> * add note about ifupdown2 on a PVE on top of Debian installation
> 
> Aaron Lauterer (3):
>    network: remove ifup ifdown as it won't reattach guests
>    network: adapt apply config section to PVE 7
>    network: rework introduction for people with less experience
> 
>   pve-network.adoc | 62 +++++++++++++++++++++++++-----------------------
>   1 file changed, 32 insertions(+), 30 deletions(-)
> 

[pve-devel] applied: [PATCH docs v2 1/3] network: remove ifup ifdown as it won't reattach guests

[Thomas Lamprecht]

Am 02/06/2022 um 11:22 schrieb Aaron Lauterer:
> Mentioning 'ifup' and 'ifdown' can lead to users running into situations
> where they take down one interface, for example an vmbrX. In this
> situation the connection to the guests will be lost and not
> reestablished automatically if the interface is brought up again with
> 'ifup'. The better way to apply network changes is to run 'ifreload -a'.
> 

all true, but in the light of the pitfalls it is actually better to actively
warn, not just remove. Done so in a follow-up.

> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
> ---
>  pve-network.adoc | 3 ---
>  1 file changed, 3 deletions(-)
> 
>

applied, thanks!

[pve-devel] applied-series: [PATCH docs v2 0/3] network: update & reword

[Thomas Lamprecht]

Am 02/06/2022 um 11:22 schrieb Aaron Lauterer:
> Update the network section to
> - remove mentioning ifup & ifdown as it can break connections of running
> guests
> - ifupdown2 is default now, we can remove the verbose install guide
> - rework the introduction to make a few conecpts clear to people that
> are not used to it yet
> 
> changes since v1:
> * add note about ifupdown2 on a PVE on top of Debian installation
> 
> Aaron Lauterer (3):
>   network: remove ifup ifdown as it won't reattach guests
>   network: adapt apply config section to PVE 7
>   network: rework introduction for people with less experience
> 
>  pve-network.adoc | 62 +++++++++++++++++++++++++-----------------------
>  1 file changed, 32 insertions(+), 30 deletions(-)
> 

applied, with a followup (see git log for details), thanks!