document site.conf settings

site.conf

@@ -1,16 +1,34 @@
 {
+	// A new node's name will be autogenerated from
+	// it's primary MAC address and this prefix.
+	// e.g. freifunk-0123456789ab
 	hostname_prefix => 'freifunk',
+
+	// name of this community
 	site_name => 'Freifunk Paderborn',
+	// short name of this community
 	site_code => 'ffpb',
+
+	// firmware release (use "'.nightly" to include current date)
 	release => '0.4~beta1-exp' . nightly,
 
+	// v4 and v6 prefixes in which nodes+clients might get an IP
 	prefix4 => '10.132.0.0/16',
 	prefix6 => 'fdca:ffee:ff12:132::/64',
 
+	// timezone
 	timezone => 'CET-1CEST,M3.5.0,M10.5.0/3', # Europe/Berlin
+
+	// network-internal ntp service
 	ntp_servers => ['ntp.services.ffpb'],
+
+	// regulatory domain of your wifi
 	regdom => 'DE',
 
+	// wifi settings (2.4 GHz and 5 GHz)
+	// the most important thing to change is the SSID
+	// of the client network (yourcity.freifunk.net) and
+	// both(!) mesh_?ssid ad-hoc mesh network ids.
 	wifi24 => {
 		ssid => 'paderborn.freifunk.net',
 		channel => 1,
@@ -28,21 +46,41 @@
 		mesh_mcast_rate => 12000,
 	},
 
+	// IP address of each router
+	// At this IP a client can always connect to its
+	// currently connected node. Both v4 and v6 addr.
+	// must lie in the above prefix4 and prefix6.
 	next_node => {
 		ip4 => '10.132.0.1',
 		ip6 => 'fdca:ffee:ff12:132::1',
 
+		// mac address, must be unique in the client network
+		// (usually, you don't need to change this)
 		mac => '16:41:95:40:f7:dc',
 	},
 
+	// fastd (vpn) settings
 	fastd_mesh_vpn => {
+		// cipher(s) to use
 		methods => ['salsa2012+gmac'],
+
+		// the maximum transfer unit
+		// use 1426 for IPv4 gateways
 		mtu => 1426,
+
 		backbone => {
+			// specifies how many servers are contacted
+			// by a client simultanously
 			limit => 2,
+
+			// list all available vpn servers
 			peers => {
 				gw01 => {
+					// public fastd key of the vpn server
 					key => '97bc56ae561f67cfe15364134868c3553b5f1eab06f7bd9c5b93fbf280a52b51',
+					// remotes is an array of ways on how to reach the VPN server
+					// Use public addresses here, these addresses are used when the mesh might not be connected yet.
+					// format: '[|ipv4|ipv6] "hostname-or-ip-address" port 10000'
 					remotes => ['ipv6 "gw01.paderborn.freifunk.net" port 10000', 'ipv4 "gw01.paderborn.freifunk.net" port 10000'],
 				},
 				gw02 => {
@@ -53,15 +91,33 @@
 		},
 	},
 
+	// configure the autoupdater
 	autoupdater => {
 		enabled => 1,
+
+		// default branch for a firmware
+		// In config-mode, the user can select a different branch from below
 		branch => 'stable',
+
+		// available branches for the autoupdater
 		branches => {
 			stable => {
+				// visible name of this branch (why not use the internal identifier here, too)
 				name => 'stable',
+
+				// where to get the manifest file (without the trailing /manifest)
+				// It's wise to use an internal address here,
+				// but specifying a publicly available update site does not hurt.
 				mirrors => ['http://[fdca:ffee:ff12:132:1::42]/stable','http://firmware.paderborn.freifunk.net/stable'],
+				// A node rolls the dice once per hour - with
+				// this probably the dice says "go check if there is new firmware"
+				// A value of 8% (0.08) means that we estimate a update check every 12-13 hours (100/8=12.5).
 				probability => 0.08,
+
+				// Number of valid manifest signatures necessary to accept the manifest as "good".
 				good_signatures => 2,
+
+				// list of public keys which are considered "good" for manifest signatures
 				pubkeys => [
 					'16b0e942929d6592d4a01b66b334427ba4db03b388a876432958d9010bd8d8b5', # HeJ
 					'b0197042824a752c2dba717a4b2ded88852111bbe12e6b5f57fdfa3abb9312c0', # thardes2
@@ -82,6 +138,7 @@
 		},
 	},
 
+	// default traffic shaping (bandwidth limit) settings
 	simple_tc => {
 		mesh_vpn => {
 			ifname => 'mesh-vpn',
@@ -91,6 +148,7 @@
 		},
 	},
 
+	// custom messages in config mode
 	config_mode => {
 		msg_welcome => <<'END',
 Willkommen zum Einrichtungsassistenten für deinen neuen Paderborner