[lxc-devel] [lxd/master] Net bridge documentation

[danielrobbins on Github]

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 353 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20191212/3ceb5b8d/attachment.bin>
-------------- next part --------------
From 62abd13c43ad528bef33bd513cb93ef50d403f23 Mon Sep 17 00:00:00 2001
From: Daniel Robbins <drobbins at funtoo.org>
Date: Thu, 12 Dec 2019 15:57:36 -0700
Subject: [PATCH] Add basic bridge documentation

I found that this wasn't clearly documented so I've started to expand the Networking doc to have more than just configuration settings.

Signed-off-by: Daniel Robbins <drobbins at funtoo.org>
---
 doc/networks.md | 44 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/doc/networks.md b/doc/networks.md
index 0e971d35b2..4f18dced1b 100644
--- a/doc/networks.md
+++ b/doc/networks.md
@@ -1,8 +1,4 @@
 # Network configuration
-LXD supports creating and managing bridges, below is a list of the
-configuration options supported for those bridges.
-
-Note that this feature was introduced as part of API extension "network".
 
 The key/value configuration is namespaced with the following namespaces
 currently supported:
@@ -16,8 +12,44 @@ currently supported:
  - `raw` (raw configuration file content)
  - `user` (free form key/value for user metadata)
 
-It is expected that IP addresses and subnets are given using CIDR notation (`1.1.1.1/24` or `fd80:1234::1/64`).
-The exception being tunnel local and remote addresses which are just plain addresses (`1.1.1.1` or `fd80:1234::1`).
+## Bridges
+
+As one of the possible network configuration types under LXD,
+LXD supports creating and managing network bridges. LXD bridges 
+can leverage underlying native Linux bridges and Open vSwitch. 
+
+Creation and management of LXD bridges is performed via the `lxc network`
+command. A bridge created by LXD is by default "managed" which 
+means that LXD also will additionally set up a local `dnsmasq` 
+DHCP server and if desired also perform NAT for the bridge (this 
+is the default.)
+
+When a bridge is managed by LXD, configuration values
+under the `bridge` namespace can be used to configure it.
+
+Additionally, LXD can utilize a pre-existing Linux
+bridge. In this case, the bridge does not need to be created via
+`lxd network` and can simply be referenced in a container or
+profile device configuration as follows:
+
+```
+devices:
+  eth0:
+     name: eth0
+     nictype: bridged
+     parent: br0
+     type: nic
+```
+
+## Configuration Settings
+
+A complete list of configuration settings for LXD networks can
+be found below.
+
+It is expected that IP addresses and subnets are given using CIDR 
+notation (`1.1.1.1/24` or `fd80:1234::1/64`). The exception being 
+tunnel local and remote addresses which are just plain addresses 
+(`1.1.1.1` or `fd80:1234::1`).
 
 Key                             | Type      | Condition             | Default                   | Description
 :--                             | :--       | :--                   | :--                       | :--