Merge pull request #1 from spookey/master

first steps to documentation

Readme.md

@@ -0,0 +1,11 @@
+# gluon site examples
+
+This is a commented version of Lübecks `site.conf` and `site.mk` (without **gluon-legacy** package and configuration).
+
+Other site.conf Repositories:
+
+* [Hamburg](https://github.com/freifunkhamburg/site-ffhh)
+* [Lübeck](https://github.com/freifunk-gluon/site-ffhl)
+* [Mainz](https://github.com/Freifunk-Mainz/site-ffmz)
+* Oldenburg: [gitphp](http://git.freifunk-ol.de/projects/ffol/gluon-siteconf.git) / [redmine](https://ticket.freifunk-ol.de/projects/siteconf-ffol/repository)
+* [Paderborn](https://git.c3pb.de/freifunk-pb/site-ffpb)

site.conf

@@ -1,13 +1,59 @@
+--[[	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 json anymore.
+
+	Happy compiling!
+]]
+
 {
+	--[[	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 (TODO: Is this the local DNS entry?)
+	]]
 	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 RandAV
+	]]
 	prefix4 = '10.130.0.0/20',
 	prefix6 = 'fdef:ffc0:3dd7::/64',
 
-	timezone = 'CET-1CEST,M3.5.0,M10.5.0/3', -- Europe/Berlin
+
+	--[[	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
+	channel:		Wifi channel to use
+	htmode:
+	mesh_ssid:
+	mesh_bssid:
+	mesh_mcast_rate:
+		(TODO: fill me)
+	]]
 	regdom = 'DE',
 
 	wifi24 = {
@@ -18,6 +64,7 @@
 		mesh_bssid = '02:d1:11:37:fc:38',
 		mesh_mcast_rate = 12000,
 	},
+
 	wifi5 = {
 		ssid = 'luebeck.freifunk.net (5GHz)',
 		channel = 44,
@@ -27,13 +74,40 @@
 		mesh_mcast_rate = 12000,
 	},
 
+
+	--[[	Next-Node
+	next_node:		Howto reach the the node you are currently connected to
+		(TODO: Is this really the use of it? Which Interfaces are used?)
+		sub
+	ip4:			IPv4 Address to use
+	ip6:			IPv6 Address to use
+	mac:			MAC Address to use
+		(TODO: Why is there a mac?)
+	]]
 	next_node = {
 		ip4 = '10.130.0.1',
 		ip6 = 'fdef:ffc0:3dd7::1',
-
+		-- TODO why is there a mac ?
 		mac = '16:41:95:40:f7:dc',
 	},
 
+
+	--[[	Gateway settings
+	fastd_mesh_vpn:	fastd vpn settings
+		sub
+	methods:		encryption algorithms to use
+		(TODO: What happens if you use multiple? Is this possible?)
+	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,
@@ -60,6 +134,25 @@
 		},
 	},
 
+
+	--[[	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 = {
@@ -75,10 +168,15 @@
 				},
 			},
 			experimental = {
+				-- DE: Name des "braches" wird beim erstellen von Images / update generiert
 				name = 'experimental',
+				-- DE: Update Server. Diest ist ein einfacher Webserver ohne spezielle Konfiguration
 				mirrors = {'http://1.updates.services.ffhl/experimental/sysupgrade'},
+				-- TODO was ist das ?
 				probability = 1.00,
+				good_signatures = 2,
 				good_signatures = 1,
+				-- DE: Oeffentlicher Schluessel / Public Key der Entwickler
 				pubkeys = {
 					'496136b37e5f561dfdf523611f14e4b6bc2a745cbc1ab7daffa59fded5f202d1', -- philae
 				},
@@ -86,6 +184,16 @@
 		},
 	},
 
+
+	--[[	Simple TC settings
+		(TODO: What is this?)
+	mesh_vpn:
+		sub
+	ifname:
+	enabled:
+	limit_egress:
+	limit_ingress:
+	]]
 	simple_tc = {
 		mesh_vpn = {
 			ifname = 'mesh-vpn',
@@ -95,6 +203,14 @@
 		},
 	},
 
+
+	--[[	Config Mode settings
+		Text shown on local website on node. you can use html here.
+	msg_welcome:	Welcome message shown at first 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.
+	]]
 	config_mode = {
 		msg_welcome = [[
 Willkommen zum Einrichtungsassistenten für deinen neuen Lübecker

site.mk

@@ -1,3 +1,8 @@
+##	gluon site.mk makefile example
+
+## GLUON_SITE_PACKAGES
+#		specify gluon/openwrt packages to include here
+
 GLUON_SITE_PACKAGES := \
 	gluon-alfred \
 	gluon-autoupdater \
@@ -16,6 +21,12 @@ GLUON_SITE_PACKAGES := \
 	haveged
 
 
+## DEFAULT_GLUON_RELEASE
+#		version string to use for images
+#		gluon relies on
+#			opkg compare-versions "$1" '>>' "$2"
+#		to decide if a version is newer or not.
+
 DEFAULT_GLUON_RELEASE := 0.4+0-exp$(shell date '+%Y%m%d')
 
 # Allow overriding the release number from the command line