From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <s.lendl@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by lists.proxmox.com (Postfix) with ESMTPS id 1346A9A86A
 for <pve-devel@lists.proxmox.com>; Fri, 17 Nov 2023 14:56:08 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
 by firstgate.proxmox.com (Proxmox) with ESMTP id E8A7F33DDB
 for <pve-devel@lists.proxmox.com>; Fri, 17 Nov 2023 14:55:37 +0100 (CET)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
 [94.136.29.106])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by firstgate.proxmox.com (Proxmox) with ESMTPS
 for <pve-devel@lists.proxmox.com>; Fri, 17 Nov 2023 14:55:37 +0100 (CET)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
 by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 031E543E47
 for <pve-devel@lists.proxmox.com>; Fri, 17 Nov 2023 14:55:37 +0100 (CET)
From: Stefan Lendl <s.lendl@proxmox.com>
To: pve-devel@lists.proxmox.com
Date: Fri, 17 Nov 2023 14:55:26 +0100
Message-ID: <20231117135531.3198353-2-s.lendl@proxmox.com>
X-Mailer: git-send-email 2.42.0
In-Reply-To: <20231117135531.3198353-1-s.lendl@proxmox.com>
References: <20231117135531.3198353-1-s.lendl@proxmox.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results:  0
 AWL 0.066 Adjusted score from AWL reputation of From: address
 BAYES_00                 -1.9 Bayes spam probability is 0 to 1%
 DMARC_MISSING             0.1 Missing DMARC policy
 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
 SPF_HELO_NONE           0.001 SPF: HELO does not publish an SPF Record
 SPF_PASS               -0.001 SPF: sender matches SPF record
 T_SCC_BODY_TEXT_LINE    -0.01 -
Subject: [pve-devel] [PATCH v2 pve-docs 1/6] sdn: installation,
 overview and main configuration
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Fri, 17 Nov 2023 13:56:08 -0000

refs only work with subsequent patches

Signed-off-by: Stefan Lendl <s.lendl@proxmox.com>
---
 pvesdn.adoc | 67 +++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index b796c5e..562e081 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -15,18 +15,16 @@ xref:getting_help[mailing lists or in the forum] for questions and feedback.
 
 [[pvesdn_installation]]
 Installation
-------------
+-------------
 
 To enable the experimental Software-Defined Network (SDN) integration, you need
-to install the `libpve-network-perl` and `ifupdown2` packages on every node:
+to install the `libpve-network-perl` package on every node:
 
 ----
 apt update
-apt install libpve-network-perl ifupdown2
+apt install libpve-network-perl
 ----
 
-NOTE: {pve} version 7 and above come installed with ifupdown2.
-
 After this, you need to add the following line to the end of the
 `/etc/network/interfaces` configuration file, so that the SDN configuration gets
 included and activated.
@@ -36,47 +34,56 @@ source /etc/network/interfaces.d/*
 ----
 
 
-Basic Overview
---------------
+[[pvesdn_overview]]
+Overview
+-------------
 
 The {pve} SDN allows for separation and fine-grained control of virtual guest
 networks, using flexible, software-controlled configurations.
 
-Separation is managed through zones, where a zone is its own virtual separated
-network area. A 'VNet' is a type of a virtual network connected to a zone.
-Depending on which type or plugin the zone uses, it can behave differently and
-offer different features, advantages, and disadvantages. Normally, a 'VNet'
-appears as a common Linux bridge with either a VLAN or 'VXLAN' tag, however,
-some can also use layer 3 routing for control. 'VNets' are deployed locally on
-each node, after being configured from the cluster-wide datacenter SDN
-administration interface.
+Separation is managed through *zones*, virtual networks (*VNets*), and
+*subnets*.  A zone is its own virtually separated network area.  A VNet is a
+virtual network that belongs to a zone. A subnet is an IP range inside a VNet.
 
+Depending on the type of the zone, the network behaves differently and offers
+specific features, advantages, and limitations.
 
-Main Configuration
-~~~~~~~~~~~~~~~~~~
+Use cases for SDN range from an isolated private network on each individual node
+to complex overlay networks across multiple PVE clusters on different locations.
 
-Configuration is done at the datacenter (cluster-wide) level and is saved in
-files located in the shared configuration file system:
-`/etc/pve/sdn`
+After configuring an VNet in the cluster-wide datacenter SDN administration
+interface, it is available as a common Linux bridge, locally on each node, to be
+assigned to VMs and Containers.
+
+
+[[pvesdn_main_configuration]]
+Main Configuration
+-------------
 
-On the web-interface, SDN features 3 main sections:
+Configuration is done at the web UI at datacenter level and is saved in files
+located in the shared configuration file system at `/etc/pve/sdn`.
 
-* SDN: An overview of the SDN state
+On the web interface, SDN features the following sections:
 
-* Zones: Create and manage the virtually separated network zones
+* xref:pvesdn_config_main_sdn[SDN]:: An overview of the SDN state
 
-* VNets: Create virtual network bridges and manage subnets
+* xref:pvesdn_config_zone[Zones]: Create and manage the virtually separated
+  network zones
 
-In addition to this, the following options are offered:
+* xref:pvesdn_config_vnets[VNets] VNets: Create virtual network bridges and
+  manage subnets
 
-* Controller: For controlling layer 3 routing in complex setups
+The Options category allows adding and managing additional services to be used
+in your SDN setup.
 
-* Subnets: Used to defined IP networks on VNets
+* xref:pvesdn_config_controllers[Controllers]: For controlling layer 3 routing
+  in complex setups
 
-* IPAM: Enables the use of external tools for IP address management (guest
-  IPs)
+* xref:pvesdn_config_ipam[IPAM]: Enables external for IP address management for
+  guests
 
-* DNS: Define a DNS server API for registering virtual guests' hostname and IP
+* xref:pvesdn_config_dns[DNS]: Define a DNS server integration for registering
+  virtual guests' hostname and IP
   addresses
 
 [[pvesdn_config_main_sdn]]
-- 
2.42.0