Browse Source

docs: add site-example

Nils Schneider 9 years ago
parent
commit
a0635e4ca9
4 changed files with 349 additions and 1 deletions
  1. 28 0
      docs/site-example/modules
  2. 254 0
      docs/site-example/site.conf
  3. 49 0
      docs/site-example/site.mk
  4. 18 1
      docs/user/site.rst

+ 28 - 0
docs/site-example/modules

@@ -0,0 +1,28 @@
+##	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.
+#
+#		for each feed name given, there have to be
+#		two variables given in the following.
+
+GLUON_SITE_FEEDS='ffhh_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_$feedname_COMMIT
+#		the version/commit of the git repository to clone
+
+PACKAGES_FFHH_PACKAGES_COMMIT=0fc9d44e95000c61a69b04278e4d38f2a3f57e49
+

+ 254 - 0
docs/site-example/site.conf

@@ -0,0 +1,254 @@
+--[[	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!
+]]
+
+{
+	--[[	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 = 'ff:ff:ff:ff:ff:ff',
+		mesh_bssid = 'ff:ff:ff:ff:ff:ff',
+		mesh_mcast_rate = 12000,
+	},
+
+	wifi5 = {
+		ssid = 'luebeck.freifunk.net',
+		channel = 44,
+		htmode = 'HT40+',
+		mesh_ssid = 'ff:ff:ff:ff:ff:ff',
+		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 = [[
+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 = [[
+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
+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 = [[
+<p>
+Dein Knoten startet gerade neu und wird anschließend versuchen,
+sich anschließend mit anderen Freifunk-Knoten in seiner Nähe zu
+verbinden. Weitere Informationen zur
+Lübecker Freifunk-Community findest du auf
+<a href="https://luebeck.freifunk.net/">unserer Webseite</a>.
+</p>
+<p>
+Viel Spaß mit deinem Knoten und der Erkundung von Freifunk!
+</p>
+]],
+	},
+}

+ 49 - 0
docs/site-example/site.mk

@@ -0,0 +1,49 @@
+##	gluon site.mk makefile example
+
+##	GLUON_SITE_PACKAGES
+#		specify gluon/openwrt packages to include here
+
+GLUON_SITE_PACKAGES := \
+	gluon-alfred \
+	gluon-announced \
+	gluon-autoupdater \
+	gluon-config-mode-hostname \
+	gluon-config-mode-autoupdater \
+	gluon-config-mode-mesh-vpn \
+	gluon-config-mode-geo-location \
+	gluon-config-mode-contact-info \
+	gluon-ebtables-filter-multicast \
+	gluon-ebtables-filter-ra-dhcp \
+	gluon-luci-admin \
+	gluon-luci-autoupdater \
+	gluon-luci-portconfig \
+	gluon-next-node \
+	gluon-mesh-batman-adv \
+	gluon-mesh-vpn-fastd \
+	gluon-radvd \
+	gluon-status-page \
+	iwinfo \
+	iptables \
+	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')
+
+
+##	GLUON_RELEASE
+#		call make with custom GLUON_RELEASE flag, to use your own release version scheme.
+#		e.g.:
+#			$ make images GLUON_RELEASE=23.42+5
+#		would generate images named like this:
+#			gluon-ff%site_code%-23.42+5-%router_model%.bin
+
+# Allow overriding the release number from the command line
+GLUON_RELEASE ?= $(DEFAULT_GLUON_RELEASE)
+
+# Default priority for updates.
+GLUON_PRIORITY ?= 0

+ 18 - 1
docs/user/site.rst

@@ -188,4 +188,21 @@ GLUON_PRIORITY
 Examples
 --------
 
-An example configuration is maintained at https://github.com/freifunk-gluon/site-example.
+site.mk
+^^^^^^^
+
+.. literalinclude:: ../site-example/site.mk
+  :language: makefile
+
+site.conf
+^^^^^^^^^
+
+.. literalinclude:: ../site-example/site.conf
+  :language: lua
+
+modules
+^^^^^^^
+
+.. literalinclude:: ../site-example/modules
+  :language: makefile
+