From 8347527af4c611067eaea73243f7cf7f3c620cd3 Mon Sep 17 00:00:00 2001 From: Nils Schneider Date: Mon, 13 Oct 2014 14:02:28 +0200 Subject: [PATCH] docs: unclutter site-example --- docs/site-example/modules | 30 ++- docs/site-example/site.conf | 355 +++++++++++++++--------------------- 2 files changed, 156 insertions(+), 229 deletions(-) diff --git a/docs/site-example/modules b/docs/site-example/modules index 2bfc3731..05856ce4 100644 --- a/docs/site-example/modules +++ b/docs/site-example/modules @@ -1,28 +1,22 @@ -## 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 - +# This file allows specifying additional repositories to use +# when building gluon. +# +# In most cases, it is not required so don't add it. ## 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' - +# 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_MY_OWN_PACKAGES_COMMIT=123456789aabcda1a69b04278e4d38f2a3f57e49 -PACKAGES_FFHH_PACKAGES_COMMIT=0fc9d44e95000c61a69b04278e4d38f2a3f57e49 - +## PACKAGES_$feedname_BRANCH +# the branch to check out +#PACKAGES_MY_OWN_PACKAGES_BRANCH=my_branch diff --git a/docs/site-example/site.conf b/docs/site-example/site.conf index 12607a55..2ecd898d 100644 --- a/docs/site-example/site.conf +++ b/docs/site-example/site.conf @@ -1,236 +1,169 @@ ---[[ 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.4 +-- +-- 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', + -- Used for generated hostnames, e.g. freifunk-abcdef123456. + hostname_prefix = 'freifunk', + -- Name of the community. + site_name = 'Freifunk Lübeck', - --[[ 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', + -- 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', - --[[ 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'}, + -- 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 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', + -- Wireless regulatory domain of your community. + 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, - }, + -- Wireless configuratoin for 2.4 GHz interfaces. + wifi24 = { + -- Wireless channel. + channel = 1, - 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, - }, + -- 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', - --[[ 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', - }, + -- 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, + }, - --[[ 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'}, - }, - }, - }, - }, + -- 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', - --[[ 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 - }, - }, - }, - }, + -- 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, - --[[ 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, - }, - }, + -- 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'}, + }, + }, + }, + }, - --[[ 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. + autoupdater = { + -- Default branch. Don't forget to set GLUON_BRANCH when building! + branch = 'stable', - 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 = [[ + -- 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 @@ -238,7 +171,7 @@ schicke dazu diesen Schlüssel und den Namen deines Knotens (<%=hostname%>) an keys@luebeck.freifunk.net. ]], - msg_reboot = [[ + msg_reboot = [[

Dein Knoten startet gerade neu und wird anschließend versuchen, sich anschließend mit anderen Freifunk-Knoten in seiner Nähe zu @@ -250,5 +183,5 @@ Lübecker Freifunk-Community findest du auf Viel Spaß mit deinem Knoten und der Erkundung von Freifunk!

]], - }, + }, }