Merge pull request #210 from freifunk-gluon/2014.3.x-site-example

docs: unclutter site-example for 2014.3.x

docs/site-example/modules

-##	gluon site modules example
-#		this file allows to define additional
-#		package feeds to be used.
-#		packages from this feeds can then be included
-#		via site.mk
-
-
-##	GLUON_SITE_FEEDS
-#		feeds to include, note that this is not called
-#		GLUON_FEEDS as in the Gluon modules file.
+# This file allows specifying additional repositories to use
+# when building gluon.
 #
-#		for each feed name given, there have to be
-#		two variables given in the following.
-GLUON_SITE_FEEDS='ffhh_packages'
+# In most cases, it is not required so don't add it.
 
+##	GLUON_SITE_FEEDS
+#		for each feed name given, add the corresponding PACKAGES_* lines
+#		documented below
+#GLUON_SITE_FEEDS='my_own_packages'
 
 ##	PACKAGES_$feedname_REPO
 #		the  git repository from where to clone the package feed
-PACKAGES_FFHH_PACKAGES_REPO=git://github.com/freifunkhamburg/ffhh-packages.git
+#PACKAGES_MY_OWN_PACKAGES_REPO=https://github.com/.../my-own-packages.git
 
 
 ##	PACKAGES_$feedname_COMMIT
 #		the version/commit of the git repository to clone
-PACKAGES_FFHH_PACKAGES_COMMIT=0fc9d44e95000c61a69b04278e4d38f2a3f57e49
+#PACKAGES_MY_OWN_PACKAGES_COMMIT=123456789aabcda1a69b04278e4d38f2a3f57e49
 
+##  PACKAGES_$feedname_BRANCH
+#   the branch to check out
+#PACKAGES_MY_OWN_PACKAGES_BRANCH=my_branch

docs/site-example/site.conf

---[[	gluon site.conf example
-
-	This file is loosely related to the original site.conf used in Lübeck.
-	There are comments added to most switches to explain the usage of gluon.
-
-	This is lua code now, not perl anymore.
-
-	Happy compiling!
-]]
-
+-- This is an example site configuration for Gluon v2014.3.x
+--
+-- Take a look at the documentation located at
+-- http://gluon.readthedocs.org/ for details.
+--
+-- This configuration will not work as it. You're required to make
+-- community specific changes to it!
 {
-	--[[	Community settings
-	hostname_prefix:	Nodename prefix
-		freifunk-abcdef123456 (hex-part is generated from node's MAC address)
-	site_name:		Name of your community
-	site_code:		Shortcode of your community
-	]]
-	hostname_prefix = 'freifunk',
-	site_name = 'Freifunk Lübeck',
-	site_code = 'ffhl',
-
-	--[[	General network settings
-	prefix4:			IPv4 range of your community
-	prefix6:			IPv6 range of your community
-		is also required for radvd
-	]]
-	prefix4 = '10.130.0.0/20',
-	prefix6 = 'fdef:ffc0:3dd7::/64',
-
-	--[[	NTP settings
-		Synchronize the time of the nodes
-	timezone:		Timezone of your community
-		http://wiki.openwrt.org/doc/uci/system#time.zones
-	ntp_servers:		List of NTP-Servers to query. You can use any public and/or your private NTP-Servers of your community.
-		http://www.pool.ntp.org/zone/de
-	 ]]
-	timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',
-	ntp_servers = {'1.ntp.services.ffhl'},
-
-	--[[	Wireless settings
-	regdom:			IEEE 802.11 Regulatory Domain
-		http://en.wikipedia.org/wiki/IEEE_802.11#Regulatory_domains_and_legal_compliance
-	wifi24:			Wifi settings for 2.4 GHz frequency devices
-	wifi5:			Wifi settings for 5 GHz frequency devices
-		sub
-	ssid:			Wifi name shown to the user (We recommend %site_code%.freifunk.net)
-	channel:		Wifi channel to use
-	htmode:			Specifies the channel width in 802.11n and 802.11ac mode, possible values are:
-						HT20 (single 20MHz channel),
-						HT40- (2x 20MHz channels, primary/control channel is upper, secondary channel is below)
-						HT40+ (2x 20MHz channels, primary/control channel is lower, secondary channel is above).
-						VHT20 / VHT40 / VHT80 / VHT160 (channel width in 802.11ac, extra channels are picked according to the specification)
-		http://wiki.openwrt.org/doc/uci/wireless#common.options (-> htmode)
-	mesh_ssid:		SSID of the mesh-interface, only used between nodes
-	mesh_bssid:		BSSID of the mesh-interface
-	                        The supplied default of ff:ff:ff:ff:ff:ff will not work.
-	                        You'll need to replace it with randomly generated, non-broadcast BSSID!
-	mesh_mcast_rate:	multicast rate of the mesh-interface
-	]]
-	regdom = 'DE',
-
-	wifi24 = {
-		ssid = 'luebeck.freifunk.net',
-		channel = 1,
-		htmode = 'HT40+',
-		mesh_ssid = 'mesh.ffhl',
-		mesh_bssid = 'ff:ff:ff:ff:ff:ff',
-		mesh_mcast_rate = 12000,
-	},
-	wifi5 = {
-		ssid = 'luebeck.freifunk.net',
-		channel = 44,
-		htmode = 'HT40+',
-		mesh_ssid = 'mesh.ffhl',
-		mesh_bssid = 'ff:ff:ff:ff:ff:ff',
-		mesh_mcast_rate = 12000,
-	},
-
-	--[[	Next-Node
-	next_node:		Howto reach the node you are currently connected to
-			The node will always be reachable at that address, and it's the same on all nodes. Because next_node packets are redirected within the node itself, there will be no conflicts.
-		sub
-	ip4:			IPv4 Address to use
-	ip6:			IPv6 Address to use
-	mac:			MAC Address to use
-		(TODO: What is the purpose of this MAC-Address here?)
-	]]
-	next_node = {
-		ip4 = '10.130.0.1',
-		ip6 = 'fdef:ffc0:3dd7::1',
-		mac = '16:41:95:40:f7:dc',
-	},
-
-
-	--[[	Gateway settings
-	fastd_mesh_vpn:	fastd vpn settings
-		https://projects.universe-factory.net/projects/fastd/wiki/User_manual
-		sub
-	methods:		encryption algorithms to use
-		https://projects.universe-factory.net/projects/fastd/wiki/Methods
-		When multiple method statements are given, the first one has the highest preference.
-	mtu:			package size
-	backbone:		fastd vpn gateways of your community
-		sub
-	limit:			Number of gateways each node connects to
-		On startup, each node tries to connect to every gateway, and then chooses the number of 'limit' fastest gateways it could reach
-	peers:			Gateways
-		sub sub
-	key:			public fastd key of your gateway
-		https://github.com/tcatm/ecdsautils
-	remotes:		List of fastd configuration strings to connect to your gateway server
-	]]
-	fastd_mesh_vpn = {
-		methods = {'salsa2012+gmac'},
-		mtu = 1426,
-		backbone = {
-			limit = 2,
-			peers = {
-				burgtor = {
-					key = '657af03e36ff1b8bbe5a5134982a4f110c8523a9a63293870caf548916a95a03',
-					remotes = {'ipv4 "burgtor.mesh.ffhl.chaotikum.org" port 10000'},
-				},
-				holstentor = {
-					key = '8c660f7511bf101ea1b599fe53af20e1146cd923c9e9d2a3a0d534ee75af9067',
-					remotes = {'ipv4 "holstentor.mesh.ffhl.chaotikum.org" port 10000'},
-				},
-				huextertor = {
-					key = 'a1b124f43eae4f5929850c09cda825ef35d659e3db4d7746e3d97627e9fa7238',
-					remotes = {'ipv4 "huextertor.mesh.ffhl.chaotikum.org" port 10000'},
-				},
-				muehlentor = {
-					key = 'bd4ec3cf87bb0042eed2fa121fbc402154d28fb1ae9dff9cdb71bb21892f401a',
-					remotes = {'ipv4 "muehlentor.mesh.ffhl.chaotikum.org" port 10000'},
-				},
-			},
-		},
-	},
-
-	--[[	Autoupdater settings
-	branch:			Automatically update to this branch
-	branches:		Available branches your community is publishing
-		sub sub
-	name:			Name of branch (is used when compiling images)
-	mirrors:		List of urls where to find the firmware
-		just serve the images on port 80 via http. a simple apache file-listing is enough.
-		see: http://luebeck.freifunk.net/firmware/
-	probability:	How often should a node search for updates
-		1.0 - perform an update every hour
-		0.5 - on average, perform an update every two hours
-		0.0 - inhibit any automatic updates
-	good_signatures:	How many signatures should be valid so the node decides to upgrade itself
-	pubkeys:		public keys by developers used in manifest file of branch
-		manifest file - see gluon readme
-		$ make manifest GLUON_BRANCH=mybranch
-		$ contrib/sign.sh $SECRETKEY.file images/sysupgrade/manifest
-	]]
-	autoupdater = {
-		branch = 'experimental',
-		branches = {
-			stable = {
-				name = 'stable',
-				mirrors = {'http://1.updates.services.ffhl/stable/sysupgrade'},
-				probability = 0.08,
-				good_signatures = 2,
-				pubkeys = {
-					'daa19b44bbd7033965e02088127bad9516ba0fea8f34267a777144a23ec8900c', -- Linus
-					'a8dd60765b07330a4bbfdf8406102befca132881a4b65f3efda32cf2d5b362d9', -- Nils
-					'323bd3285c4e5547a89cd6da1f2aef67f1654b0928bbd5b104efc9dab2156d0b', -- NeoRaider
-				},
-			},
-			experimental = {
-				-- DE: Name des "braches" wird beim erstellen von Images / update generiert
-				name = 'experimental',
-				mirrors = {'http://1.updates.services.ffhl/experimental/sysupgrade'},
-				probability = 1.00,
-				good_signatures = 2,
-				good_signatures = 1,
-				-- DE: Oeffentlicher Schluessel / Public Key der Entwickler
-				pubkeys = {
-					'496136b37e5f561dfdf523611f14e4b6bc2a745cbc1ab7daffa59fded5f202d1', -- philae
-				},
-			},
-		},
-	},
-
-	--[[	Simple TC settings to limit the bandwidth of the vpn-uplink
-	mesh_vpn:
-		sub
-	ifname:		name of the interface/bridge
-	enabled:	default-value
-	limit_egress:	default-value
-	limit_ingress:	default-value
-	]]
-	simple_tc = {
-		mesh_vpn = {
-			ifname = 'mesh-vpn',
-			enabled = false,
-			limit_egress = 200,
-			limit_ingress = 3000,
-		},
-	},
-
-
-	--[[	Config Mode settings
-		Text shown on local website on node while in config mode (after initial flashing or after a long press and hold on the primary button and reboot). You can use html here.
-	msg_welcome:		Welcome message shown at startup
-	msg_pubkey:		Instructions for the user how your community handles the key exchange
-		only shown if VPN setting is selected
-	msg_reboot:		Message shown when configuration is finished while the node is rebooting.
-
-		Variables
-		Within the text given here you can use variables which are
-		replaced when the respective website is delivered to the user.
-		Variables must be used in the format <%=NAME%>. See msg_pubkey for an example.
-	hostname		hostname of the node
-	pubkey			fastd public key of the node
-	sysconfig.primary_mac	the primary mac of the node, also found printed beneath the device
-	... other sysconfig.* variables: config_ifname, lan_ifname, wan_ifname
-	]]
-	config_mode = {
-		msg_welcome = [[
+  -- Used for generated hostnames, e.g. freifunk-abcdef123456.
+  hostname_prefix = 'freifunk',
+
+  -- Name of the community.
+  site_name = 'Freifunk Lübeck',
+
+  -- Shorthand of the community.
+  site_code = 'ffhl',
+
+  -- Prefixes used within the mesh. Both are required.
+  prefix4 = '10.130.0.0/20',
+  prefix6 = 'fdef:ffc0:3dd7::/64',
+
+  -- Timezone of your community.
+  -- See http://wiki.openwrt.org/doc/uci/system#time.zones
+  timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',
+
+  -- List of NTP servers in your community.
+  -- Must be reachable using IPv6!
+  ntp_servers = {'1.ntp.services.ffhl'},
+
+  -- Wireless regulatory domain of your community.
+  regdom = 'DE',
+
+  -- Wireless configuratoin for 2.4 GHz interfaces.
+  wifi24 = {
+    -- Wireless channel.
+    channel = 1,
+
+    -- ESSID used for client network.
+    ssid = 'luebeck.freifunk.net',
+
+    -- Specifies the channel width in 802.11n and 802.11ac mode.
+    -- Possible values are:
+    -- HT20 (single 20MHz channel),
+    -- HT40- (2x 20MHz channels, secondary below)
+    -- HT40+ (2x 20MHz channels, secondary above)
+    htmode = 'HT20',
+
+    -- Adjust these values! ff... will not work!
+    mesh_ssid = 'ff:ff:ff:ff:ff:ff',  -- ESSID used for mesh
+    mesh_bssid = 'ff:ff:ff:ff:ff:ff', -- BSSID used for mesh
+
+    -- Bitrate used for multicast/broadcast packets.
+    mesh_mcast_rate = 12000,
+  },
+
+  -- Wireless configuration for 5 GHz interfaces.
+  -- This should be equal to the 2.4 GHz variant, except
+  -- for channel and htmode.
+  wifi5 = {
+    ssid = 'luebeck.freifunk.net',
+    channel = 44,
+    htmode = 'HT20',
+    mesh_ssid = 'ff:ff:ff:ff:ff:ff',
+    mesh_bssid = 'ff:ff:ff:ff:ff:ff',
+    mesh_mcast_rate = 12000,
+  },
+
+  -- 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
+    ip4 = '10.130.0.1',
+    ip6 = 'fdef:ffc0:3dd7::1',
+
+    -- anycast MAC of all nodes
+    mac = '16:41:95:40:f7:dc',
+  },
+
+  -- Refer to http://fastd.readthedocs.org/en/latest/ to better understand
+  -- what these options do.
+  fastd_mesh_vpn = {
+    -- List of crypto-methods to use.
+    methods = {'salsa2012+gmac'},
+    mtu = 1426,
+    backbone = {
+      -- Limit number of connected peers to reduce bandwidth.
+      limit = 2,
+
+      -- List of peers.
+      peers = {
+        burgtor = {
+          key = '657af03e36ff1b8bbe5a5134982a4f110c8523a9a63293870caf548916a95a03',
+
+          -- This is a list, so you might add multiple entries.
+          remotes = {'ipv4 "burgtor.mesh.ffhl.chaotikum.org" port 10000'},
+        },
+        holstentor = {
+          key = '8c660f7511bf101ea1b599fe53af20e1146cd923c9e9d2a3a0d534ee75af9067',
+          remotes = {'ipv4 "holstentor.mesh.ffhl.chaotikum.org" port 10000'},
+        },
+      },
+    },
+  },
+
+  autoupdater = {
+    -- Default branch. Don't forget to set GLUON_BRANCH when building!
+    branch = 'stable',
+
+    -- List of branches. You may define multiple branches.
+    branches = {
+      stable = {
+        name = 'stable',
+
+        -- 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 = {
+                'daa19b44bbd7033965e02088127bad9516ba0fea8f34267a777144a23ec8900c', -- Linus
+                'a8dd60765b07330a4bbfdf8406102befca132881a4b65f3efda32cf2d5b362d9', -- Nils
+                '323bd3285c4e5547a89cd6da1f2aef67f1654b0928bbd5b104efc9dab2156d0b', -- NeoRaider
+        },
+      },
+    },
+  },
+
+  -- Bandwidth limiting
+  simple_tc = {
+    mesh_vpn = {
+      ifname = 'mesh-vpn',
+
+      -- You may enable it by default here.
+      enabled = false,
+
+      -- Default upload limit (kbit/s).
+      limit_egress = 200,
+
+      -- Default download limit (kbit/s).
+      limit_ingress = 3000,
+    },
+  },
+
+  -- These strings are shown in config mode. Some HTML is permissible.
+  --
+  -- msg_welcome: shown at startup
+  -- msg_pubkey:  shown when VPN is enabled
+  -- msg_reboot:  shown during reboot (after finishing configuration)
+  --
+  -- You may use some variables, e.g.:
+  --
+  -- <%=hostname%>               - the node's hostname
+  -- <%=pubkey%>                - the fastd public key
+  -- <%=sysconfig.primary_mac%> - the node's primary MAC
+  config_mode = {
+    msg_welcome = [[
 Willkommen zum Einrichtungsassistenten für deinen neuen Lübecker
 Freifunk-Knoten. Fülle das folgende Formular deinen Vorstellungen
 entsprechend aus und sende es ab.
 ]],
-		msg_pubkey = [[
+    msg_pubkey = [[
 Dies ist der öffentliche Schlüssel deines Freifunk-Knotens. Erst nachdem
 er auf den Servern des Lübecker Freifunk-Projektes eingetragen wurde,
 kann sich dein Knoten mit dem Lübecker Mesh-VPN zu verbinden. Bitte
@@ -231,7 +171,7 @@ schicke dazu diesen Schlüssel und den Namen deines Knotens
 (<em><%=hostname%></em>) an
 <a href="mailto:keys@luebeck.freifunk.net">keys@luebeck.freifunk.net</a>.
 ]],
-		msg_reboot = [[
+    msg_reboot = [[
 <p>
 Dein Knoten startet gerade neu und wird anschließend versuchen,
 sich anschließend mit anderen Freifunk-Knoten in seiner Nähe zu
@@ -243,5 +183,5 @@ Lübecker Freifunk-Community findest du auf
 Viel Spaß mit deinem Knoten und der Erkundung von Freifunk!
 </p>
 ]],
-	},
+  },
 }