From 471ca1d1a8ae34204ae80dafaa7619cb3710e626 Mon Sep 17 00:00:00 2001
From: Grische <github@grische.xyz>
Date: Sat, 22 Oct 2022 20:19:22 +0200
Subject: [PATCH] docs: update multidomain-site example

Expanded and updated the documentation, based on docs/site-example/site.conf
---
 .../domains/alpha_centauri.conf               | 85 +++++++++++++++----
 docs/multidomain-site-example/site.conf       | 72 +++++++++++++---
 2 files changed, 129 insertions(+), 28 deletions(-)

diff --git a/docs/multidomain-site-example/domains/alpha_centauri.conf b/docs/multidomain-site-example/domains/alpha_centauri.conf
index 82245972..275bc3a8 100644
--- a/docs/multidomain-site-example/domains/alpha_centauri.conf
+++ b/docs/multidomain-site-example/domains/alpha_centauri.conf
@@ -1,3 +1,10 @@
+-- This is an example domain configuration for Gluon v2022.1
+--
+-- Take a look at the documentation located at
+-- https://gluon.readthedocs.io/ for details.
+--
+-- This configuration will not work as is. You're required to make
+-- community specific changes to it!
 {
   -- multiple codes/names can be defined, the first one is the primary name
   -- additional aliases can be defined
@@ -7,62 +14,106 @@
     proxima_centauri = 'Proxima Centauri',
   },
 
-  -- 32 byte random data in hexadecimal encoding
+  -- 32 bytes of random data, encoded in hexadecimal
   -- This data must be unique among all sites and domains!
   -- Can be generated using: echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
   domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
 
   -- unique network prefixes per domain
+  -- prefix6 is required, prefix4 can be omitted if next_node.ip4
+  -- is not set.
   prefix4 = '10.xxx.0.0/20',
-  prefix6 = 'fdxx:xxxx:xxxx:xxxx::/64',
-
-  next_node = {
-    ip4 = '10.xxx.yyy.zzz',
-    ip6 = 'fdxx:xxxx:xxxx:xxxx::xxxx',
-  },
+  prefix6 = 'fdxx:xxxx:xxxx::/64',
 
+  -- Wireless configuration for 2.4 GHz interfaces.
   wifi24 = {
+    -- ESSIDs used for client network.
     ap = {
-      ssid = "alpha-centauri.example.org",
-      channel = 1,
+      -- ssid = 'alpha-centauri.freifunk.net', (optional - SSID for open client network)
+      -- disabled = true, -- (optional)
+
+      -- Configuration for a backward compatible OWE network below.
+      -- owe_ssid = 'owe.alpha-centauri.freifunk.net', -- (optional - SSID for OWE client network)
+      -- owe_transition_mode = true, -- (optional - enables transition-mode - requires ssid as well as owe_ssid)
     },
+
     mesh = {
+      -- Adjust these values!
       id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
+      -- disabled = true, -- (optional)
     },
   },
 
+  -- Wireless configuration for 5 GHz interfaces.
+  -- This should be equal to the 2.4 GHz variant, except
+  -- for channel.
   wifi5 = {
     ap = {
-      ssid = "alpha-centauri.example.org",
-      channel = 44,
+      ssid = 'alpha-centauri.freifunk.net',
     },
     mesh = {
+      -- Adjust these values!
       id = 'ueH3uXjdp',
     },
   },
 
-  mesh = {
-    batman_adv = {
-      routing_algo = 'BATMAN_IV',
-    },
+
+  -- The next node feature allows clients to always reach the node it is
+  -- connected to using a known IP address.
+  next_node = {
+    -- anycast IPs of all nodes
+    -- name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
+    ip4 = '10.xxx.0.xxx',
+    ip6 = 'fdxx:xxxx:xxxx::xxxx',
   },
 
   mesh_vpn = {
+    -- enabled = true,
+
     fastd = {
+      -- Refer to https://fastd.readthedocs.io/en/latest/ to better understand
+      -- what these options do.
+
+      -- List of crypto-methods to use.
+      methods = {'salsa2012+umac'},
+      mtu = 1312,
+      -- configurable = true,
+      -- syslog_level = 'warn',
+
       groups = {
         backbone = {
+          -- Limit number of connected peers to reduce bandwidth.
+          limit = 1,
+
+          -- List of peers.
           peers = {
             peer1 = {
               key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-              remotes = {'"peer1.example.org" port xxxxx'},
+
+              -- This is a list, so you might add multiple entries.
+              remotes = {'ipv4 "xxx.somehost.invalid" port xxxxxx'},
             },
             peer2 = {
               key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
-              remotes = {'"peer2.example.org" port xxxxx'},
+              -- You can also omit the ipv4 to allow both connection via ipv4 and ipv6
+              remotes = {'"xxx.somehost2.invalid" port xxxxx'},
             },
           },
+
+          -- Optional: nested peer groups
+          -- groups = {
+            -- backbone_sub = {
+              -- ...
+            -- },
+          -- ...
+          -- },
         },
+        -- Optional: additional peer groups, possibly with other limits
+        -- backbone2 = {
+          -- ...
+        -- },
       },
     },
+
   },
 }
diff --git a/docs/multidomain-site-example/site.conf b/docs/multidomain-site-example/site.conf
index fc5298f7..fc9b5a7c 100644
--- a/docs/multidomain-site-example/site.conf
+++ b/docs/multidomain-site-example/site.conf
@@ -1,46 +1,96 @@
+-- This is an multidomain example site configuration for Gluon v2022.1
+--
+-- Take a look at the documentation located at
+-- https://gluon.readthedocs.io/ for details.
+--
+-- This configuration will not work as is. You're required to make
+-- community specific changes to it!
 {
-  site_name = 'Centauri Mesh',
-  site_code = 'centauri',
+  -- Used for generated hostnames, e.g. freifunk-abcdef123456. (optional)
+  -- hostname_prefix = 'freifunk-',
+
+  -- Name of the community.
+  site_name = 'Freifunk Alpha Centauri',
+
+  -- Shorthand of the community.
+  site_code = 'ffxx',
+
+  -- Default Domain configuration
   default_domain = 'alpha_centauri',
 
+  -- Timezone of your community.
+  -- See https://openwrt.org/docs/guide-user/base-system/system_configuration#time_zones
   timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',
-  ntp_server = {'ntp1.example.org', 'ntp2.example.org'},
+
+  -- List of NTP servers in your community.
+  -- Must be reachable using IPv6!
+  ntp_servers = {'1.ntp.services.ffxx'},
+
+  -- Wireless regulatory domain of your community.
   regdom = 'DE',
 
+  -- Wireless configuration for 2.4 GHz interfaces.
+  -- Channels can be specified per domain or globally
   wifi24 = {
+    -- Wireless channel.
+    channel = 1,
+
     mesh = {
       mcast_rate = 12000,
     },
   },
 
+  -- Wireless configuration for 5 GHz interfaces.
+  -- Channels can be specified per domain or globally
   wifi5 = {
+    channel = 44,
+    outdoor_chanlist = '100-140',
     mesh = {
       mcast_rate = 12000,
     },
   },
 
+  mesh = {
+    batman_adv = {
+      routing_algo = 'BATMAN_IV',
+    },
+  },
+
   mesh_vpn = {
-
-    fastd = {
-      methods = {'salsa2012+umac'},
-      mtu = 1312,
-    },
+    -- enabled = true,
 
     bandwidth_limit = {
+      -- The bandwidth limit can be enabled by default here.
       enabled = false,
-      egress = 200, -- kbit/s
-      ingress = 3000, -- kbit/s
+
+      -- Default upload limit (kbit/s).
+      egress = 200,
+
+      -- Default download limit (kbit/s).
+      ingress = 3000,
     },
   },
 
   autoupdater = {
+    -- Default branch (optional), can be overridden by setting GLUON_AUTOUPDATER_BRANCH when building.
+    -- Set GLUON_AUTOUPDATER_ENABLED to enable the autoupdater by default for newly installed nodes.
     branch = 'stable',
 
+    -- List of branches. You may define multiple branches.
     branches = {
       stable = {
         name = 'stable',
-        mirrors = {'http://update.example.org/stable/sysupgrade'},
+
+        -- List of mirrors to fetch images from. IPv6 required!
+        mirrors = {'http://1.updates.services.ffhl/stable/sysupgrade'},
+
+        -- Number of good signatures required.
+        -- Have multiple maintainers sign your build and only
+        -- accept it when a sufficient number of them have
+        -- signed it.
         good_signatures = 2,
+
+        -- List of public keys of maintainers.
         pubkeys = {
           'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
           'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob