From 9f8afd49fafd8357158566ac5914f107293e9895 Mon Sep 17 00:00:00 2001 From: Daniel Ehlers Date: Sat, 24 May 2014 21:49:55 +0200 Subject: [PATCH] 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 | 4 +- docs/features/autoupdater.rst | 39 ++++++++ docs/index.rst | 1 + docs/user/site.rst | 172 ++++++++++++++++++++++++++++++++++ 4 files changed, 214 insertions(+), 2 deletions(-) create mode 100644 docs/features/autoupdater.rst create mode 100644 docs/user/site.rst diff --git a/docs/conf.py b/docs/conf.py index cd3bb6d8..4b26eac6 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/features/autoupdater.rst b/docs/features/autoupdater.rst new file mode 100644 index 00000000..c0777ebd --- /dev/null +++ b/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 ``.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 diff --git a/docs/index.rst b/docs/index.rst index 2dfbfe84..2decc906 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,7 @@ User Documentation user/getting_started user/features + user/site user/builds user/faq user/admin diff --git a/docs/user/site.rst b/docs/user/site.rst new file mode 100644 index 00000000..700b8ad2 --- /dev/null +++ b/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.