docs: more work on docs

docs: Basic site documentation
docs: Basic autoupdater documentation
docs: minimal autoupdater info
docs: bump version to 2014.2

Closes #114

docs/conf.py

@@ -54,9 +54,9 @@ copyright = '2014, Nils Schneider'
 # built documents.
 #
 # The short X.Y version.
-version = '2014.1'
+version = '2014.2'
 # The full version, including alpha/beta/rc tags.
-release = '2014.1'
+release = '2014.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/features/autoupdater.rst

@@ -0,0 +1,39 @@
+Autoupdater
+===========
+
+Infrastructure
+--------------
+
+We suggest to have following directory tree accessible via http:
+
+::
+
+    firmware/
+            stable/
+                    sysupgrade/
+                    factory/
+            snapshot/
+                    sysupgrade/
+                    factory/
+            experimental/
+                    sysupgrade/
+                    factory/
+
+The last level is generated by the Gluon build process. Do not forget
+to rename the ``<branch>.manifest`` into ``manifest`` inside of the
+sysupgrade directories.
+
+The server should be available via IPv6.
+
+Command Line
+------------
+
+::
+
+   # Update with some probability
+   autoupdate
+
+::
+
+   # Force Update Check
+   autoupdater -f

docs/index.rst

@@ -22,6 +22,7 @@ User Documentation
 
    user/getting_started
    user/features
+   user/site
    user/builds
    user/faq
    user/admin

docs/user/site.rst

@@ -0,0 +1,172 @@
+Site
+====
+
+The ``site`` consists of the files ``site.conf`` and ``site.mk``.
+In the first community based values are defined, which both are processed
+during the build process and runtime.
+The last is directly included in the make process of Gluon.
+
+Configuration
+-------------
+
+The ``site.conf`` is a lua dictionary with the following defined keys.
+
+hostname_prefix
+    A string which shall prefix the default hostname of a device.
+
+site_name
+    The name of your community.
+
+site_code
+    The code of your community. It is good practice to use the TLD of
+    your community here.
+
+prefix4
+    The IPv4 Subnet of your community mesh network in CIDR notation, e.g.
+    ::
+       prefix4 = '10.111.111.0/18'
+
+prefix6
+    The IPv6 subnet of your community mesh network, e.g.
+    ::
+       prefix6 = 'fdca::ffee:babe:1::/64'
+
+timezone
+    The timezone of your community live in, e.g.
+    ::
+      -- Europe/Berlin
+      timezone = 'CET-1CEST,M3.5.0,M10.5.0/3'
+
+ntp_server
+    List of NTP servers available in your community or used by your community, e.g.:
+    ::
+       ntp_servers = {'1.ntp.services.ffeh','2.tnp.services.ffeh'}
+
+opkg_repo : optional
+    Overwrite the default ``opkg`` repository server, e.g.:
+    ::
+      opkg_repo = 'http://opkg.services.ffeh/attitude_adjustment/12.09/%S/packages'
+    The `%S` is a variable, which is replaced with the platform of an device
+    during the build process.
+
+regdom
+    The wireless regulatory domain responsible for your area,e.g.:
+    ::
+      regdom = 'DE'
+
+wifi24
+    WLAN Configuration of your community in the 2.4Ghz radio. Consisting
+    of ``ssid`` of your client network, the ``channel`` your community is using,
+    ``htmode``, the adhoc ssid ``mesh_ssid`` used between devices, the adhoc
+    bssid ``mesh_bssid`` and the adhoc multicast rate ``mesh_mcast_rate``.
+    Combined in an dictionary, e.g.:
+    ::
+       wifi24 = {
+         ssid = 'http://kiel.freifunk.net/',
+         channel = 11,
+         htmode = 'HT40-',
+         mesh_ssid = 'ff:ff:ff:ee:ba:be',
+         mesh_bssid = 'ff:ff:ff:ee:ba:be',
+         mesh_mcast_rate = 12000,
+       },
+
+wifi5
+    Same as `wifi24` but for the 5Ghz radio.
+
+next_node : package
+    Configuration of the local node feature of Gluon
+    ::
+      next_node = {
+        ip4 = '10.23.42.1',
+        ip6 = 'fdca:ffee:babe:1::1',
+        mac = 'ca:ff:ee:ba:be'
+      }
+
+
+fastd_mesh_vpn
+    Remote server setup for vpn.
+    ::
+      fastd_mesh_vpn = {
+        methods = {'salsa2012+gmac'},
+        mtu = 1426,
+        backbone = {
+          limit = 2,
+          peers = {
+            ffki_rz = {
+              key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+              remotes = {'ipv4 "vpn1.entenhausen.freifunk.net" port 10000'},
+            },
+          }
+        }
+      }
+
+autoupdater : package
+    Configuration for the autoupdater feature of Gluon.
+    ::
+      autoupdater = {
+        enabled = 1,
+        branch = 'experimental',
+        branches = {
+          stable = {
+            name = 'stable',
+            mirrors = {
+              'http://{fdca:ffee:babe:1::fec1}/firmware/stable/sysupgrade/',
+              'http://{fdca:ffee:babe:1::fec2}/firmware/stable/sysupgrade/',
+            },
+            probability = 0.08,
+            good_signatures = 2,
+            pubkeys = {
+              'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someguy
+              'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someother
+            }
+          }
+        }
+      }
+
+simple_tc : package
+    Uplink traffic control
+    ::
+      simple_tc = {
+        mesh_vpn = {
+          ifname = 'mesh-vpn',
+          enabled = 0,
+          limit_egress = 200,
+          limit_ingress = 3000,
+        },
+      },
+
+config_mode : package
+    Configuration Mode text blocks
+
+legacy : package
+    Configuration for the legacy upgrade path.
+    This is only required in communities upgrading from Lübeck's LFF-0.3.x.
+
+    ::
+      legacy = {
+             version_files = {'/etc/.freifunk_version_keep', '/etc/.eff_version_keep'},
+             old_files = {'/etc/config/config_mode', '/etc/config/ffeh', '/etc/config/freifunk'},
+             config_mode_configs = {'config_mode', 'ffeh', 'freifunk'},
+             fastd_configs = {'ffeh_mesh_vpn', 'mesh_vpn'},
+             mesh_ifname = 'freifunk',
+             tc_configs = {'ffki', 'freifunk'},
+             wifi_names = {'wifi_freifunk', 'wifi_freifunk5', 'wifi_mesh', 'wifi_mesh5'},
+      }
+
+Packages
+--------
+
+The ``site.mk`` is a Makefile which should define constants
+involved in the build process of Gluon.
+
+GLUON_SITE_PACKAGES
+    Defines a list of packages which should installed additional
+    to the ``gluon_core`` package.
+
+GLUON_RELEASE
+    The current release version Gluon should use.
+
+Examples
+--------
+
+An example configuration is maintained at https://github.com/freifunk-gluon/site-example.