Browse Source

Update documentation

Karsten Böddeker 7 years ago
parent
commit
7d930bd635

+ 5 - 0
ReadMe.md

@@ -0,0 +1,5 @@
+ffho-packages
+=============
+
+Welcome to `ffho-packages`, the package repository of Freifunk Hochstift.
+The original repository can be found at https://git.c3pb.de/freifunk-pb/ffho-packages.git.

+ 23 - 15
ffho/ffho-aptimer/ReadMe.md

@@ -1,25 +1,33 @@
 ffho-aptimer
 ============
 
-Timer for the client wifi
+Timer for the client wifi with three modes (daily, weekly, monthly)
 
 /etc/config/aptimer
 -------------------
-```
-config aptimer 'settings'
-        option enabled '1'
-        option type '$type'
 
-config $type '$day'
-        list on '06:00'
-        list off '23:00'
-```
+**aptimer.settings.enabled:**
+- `0` disables the aptimer (default)
+- `1` enables the aptimer
+
+**aptimer.settings.type:**
+- `day`, $day = all
+- `week`, $day = [Mon|Tue|Wed|Thu|Fri|Sat|Sun]
+- `month`, $day = [01-31]
 
-**$type=day**
-- $day=all
+**aptimer.$day.on:**
+- List of time to enable wireless
 
-**$type=week**
-- $day=[Mon|Tue|Wed|Thu|Fri|Sat|Sun]
+**aptimer.$day.off:**
+- List of time to disable wireless
 
-**$type=month**
-- $day=[01-31]
+### example
+```
+config aptimer 'settings'
+	option enabled '1'
+	option type 'week'
+
+config week 'Sun'
+	list on '06:00'
+	list off '23:00'
+```

+ 2 - 1
ffho/ffho-autoupdater-wifi-fallback-legacy/ReadMe.md

@@ -1,4 +1,5 @@
 ffho-autoupdater-wifi-fallback-legacy
 =====================================
 
-Only needed to upgrade the configuration from an old version to the current on.
+Only needed to upgrade the configuration from an old version of
+`ffho-autoupdater-wifi-fallback` to the current on.

+ 20 - 4
ffho/ffho-autoupdater-wifi-fallback/ReadMe.md

@@ -2,7 +2,23 @@ ffho-autoupdater-wifi-fallback
 ==============================
 
 If a node has no connection to the mesh, neither via wlan-mesh nor via
-mesh-vpn, it ist not possible to update this node via ``autoupdater``. There for
-the *wifi-fallback* was developed, to check whether the node is part of a fully
-working mesh or not. Else the node connects to a visible "Freifunknetz" and
-tries downloads an update as wlan-client via executing ``autoupdater -f``.
+mesh-vpn, it ist not possible to update this node via `autoupdater`. Therefor
+the *wifi-fallback* was developed. It checks hourly whether the node is part of
+a fully operative mesh or not. Else the node connects to a visible "Freifunknetz"
+and tries downloads an update as wlan-client via executing `autoupdater -f`.
+
+Actually this needs `iw connect` patched into `iw`. See our patch within our
+[site repository](https://git.c3pb.de/freifunk-pb/site-ffho).
+
+/etc/config/autoupdater-wifi-fallback
+-------------------------------------
+
+**autoupdater-wifi-fallback.settings.enabled:**
+- `0` disables the fallback mode
+- `1` enables the fallback mode
+
+### example
+```
+config autoupdater-wifi-fallback 'settings'
+	option enabled '1'
+```

+ 47 - 1
ffho/ffho-autoupdater/ReadMe.md

@@ -1,4 +1,50 @@
 ffho-autoupdater
 ================
 
-This is a customized version of ``gluon-autoupdater``.
+This is a customized version of `gluon-autoupdater`.
+
+site.conf
+---------
+
+**autoupdater.branch: optional**
+- Enables the autoupdater by default on the specifyed branch
+
+**autoupdater.branches.$name.name:**
+- Branch name, has to be same as $name
+
+**autoupdater.branches.$name.mirrors:**
+There are various patterns which can be used in the URLs
+- `%n` is replaced by the OpenWrt version codename
+- `%v` is replaced by the OpenWrt version number
+- `%S` is replaced by the target architecture
+- `%GS` is replaced by the Gluon site code
+- `%GV` is replaced by the Gluon version
+- `%GR` is replaced by the Gluon release
+
+**autoupdater.branches.$name.good_signatures:**
+- Number of signatures needed to validate an update
+
+**autoupdater.branches.$name.pubkeys:**
+- Public keys for signature validation
+
+### example
+```lua
+{
+  autoupdater = {
+    branch = 'stable',
+    branches = {
+      stable = {
+        name = 'stable',
+        mirrors = { 'http://firmware.ffho.net/%GS/stable' },
+        good_signatures = 2,
+        pubkeys = {
+          'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- Alice
+          'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- Bob
+        },
+      },
+      ...
+    },
+  },
+  ...
+},
+```

+ 15 - 4
ffho/ffho-config-mode-geo-location/ReadMe.md

@@ -8,7 +8,18 @@ corresponding field can be disabled.
 site.conf
 ---------
 
-**config_mode.geo_location.show_altitude : optional**
-- ``true`` enables the altitude field
-- ``false`` disables the altitude field if altitude has not yet been set
-- defaults to ``true``
+**config_mode.geo_location.show_altitude: optional**
+- `true` enables the altitude field (default)
+- `false` disables the altitude field if altitude has not yet been set
+
+### example
+```lua
+{
+  config_mode = {
+    geo_location = {
+      show_altitude = false,
+    },
+  },
+  ...
+},
+```

+ 22 - 1
ffho/ffho-config-mode-mesh-vpn/ReadMe.md

@@ -1,5 +1,26 @@
 ffho-config-mode-mesh-vpn
 =========================
 
-Costomization of ``gluon-config-mode-mesh-vpn`` to use the contactinformation
+Costomization of `gluon-config-mode-mesh-vpn` to use the contactinformation
 within the reboot page.
+
+site/i18n/*.po
+--------------
+
+Within `msgid "gluon-config-mode:pubkey"` you can use:
+- `<%=contact%>`
+- `<%=hostname%>`
+- `<%=pubkey%>`
+- `<%=sysconfig.*%>`
+
+### example
+```
+msgid "gluon-config-mode:pubkey"
+msgstr ""
+"<div class=\"the-key\">"
+"<%=hostname%><br/><br/>"
+"# Owner: <%=contact%><br/>"
+"# MAC: <%=sysconfig.primary_mac%><br/>"
+"key \"<%= pubkey %>\";"
+"</div>"
+```

+ 21 - 14
ffho/ffho-config-mode-site-select/README.md

@@ -1,19 +1,26 @@
 ffho-config-mode-site-select
-======================
+============================
 
-This Repository contains a Gluon package to choose between different sites after flashing the image. <br>
-This does not apply to the site.mk!
+This Package provides a drop-down list for the config mode, to select the site/region
+the node will be placed in. If the selection has changed the upgrade scripts in
+`/lib/gluon/upgrade/` are triggered.
 
-This is a modified Version of gluon-config-mode-site-select
+site/extra/sites.conf
+---------------------
 
-Usage
------
-Create a file called sites.conf in $gluondir/site/extra/.
-This file should include a lua-table with the following informations about the different sites
-* site_name
-* site_code
-* ssid
+**site_select.hidden: optional**
+- `0`, show this site in drop-down list (default)
+- `1`, hide this site within config mode
 
-<br>
-Das ganze sieht dann so aus: <br>
-![](http://labor19.net/Hendrik/preview1.png)
+### example
+```lua
+{
+  {
+    site_select: = {
+      hidden = 1,
+    },
+    ...
+  },
+  ...
+},
+```

+ 17 - 5
ffho/ffho-debug/ReadMe.md

@@ -1,16 +1,28 @@
 ffho-debug
 ==========
 
-Debug scripts for Freifunk Hochstift.
+Debug scripts for gluon nodes.
 
 site.conf
 ---------
 
-**debugserver.host**
+**debugserver.host:**
 - list of possible debugserver
 
-**debugserver.port**
+**debugserver.port:**
 - destination port for debug reports
 
-**debugserver.liveport**
-- destination port for ``ffho-debug-live``
+**debugserver.liveport: optional**
+- destination port for `ffho-debug-live`
+
+### example
+```lua
+{
+  debugserver = {
+    host = { 'debugreport.ffho.net' },
+    port = 1337,
+    liveport = 1338,
+  },
+  ...
+},
+```

+ 15 - 4
ffho/ffho-ebtables-net-rules/ReadMe.md

@@ -1,15 +1,26 @@
 ffho-ebtables-net-rules
 =======================
 
+Additional ebtables rules for Freifunk-Nodes
+
 site.conf
 ---------
 
-**prefix4**
+**prefix4:**
 - IPv4 prefix
 
-**prefix6**
+**prefix6:**
 - IPv6 prefix
 
-**additional_prefix6 : optional**
-- list of additional IPv6 prefixes
+**additional_prefix6: optional**
+- list of additional IPv6 prefix
 
+### example
+```lua
+{
+  prefix4 = '10.132.0.0./18',
+  prefix6 = 'fdca:ffee:ff12:132::/64',
+  additional_prefix6 = { '2a03:2260:2342:2300::/64' },
+  ...
+},
+```

+ 1 - 1
ffho/ffho-geo-location-altitude-delete/ReadMe.md

@@ -2,4 +2,4 @@ ffho-geo-location-altitude-delete
 =================================
 
 As the usage of the altitude is not well defined this package provides an
-upgrade script to delete the altitude value.
+upgrade script to delete the altitude value if already set.

+ 3 - 2
ffho/ffho-luci-autoupdater-wifi-fallback/ReadMe.md

@@ -1,5 +1,6 @@
 ffho-luci-autoupdater-wifi-fallback
 ===================================
 
-Luci module for ``gluon-autoupdater`` and ``ffho-autoupdater-wifi-fallback``,
-based on ``gluon-luci-autoupdater``.
+Luci module for `gluon-autoupdater` and `ffho-autoupdater-wifi-fallback`,
+based on `gluon-luci-autoupdater`. In addition to `gluon-luci-autoupdater`
+you can also enable or disable wifi-fallback-mode.

+ 1 - 0
ffho/ffho-node-tuning/ReadMe.md

@@ -1,3 +1,4 @@
 ffho-node-tuning
 ================
 
+comming soon ...

+ 11 - 3
ffho/ffho-respondd-config/ReadMe.md

@@ -1,11 +1,19 @@
 ffho-respondd-config
 ====================
 
-Customization of respondd data. Actually it transmitts the site_name in addition
-to other values.
+Package for customization of respondd data. Actually this adds the `site_name`
+to data transmitted by respondd.
 
 site.conf
 ---------
 
-**site_name**
+**site_name:**
 - The name of your community
+
+### example
+```lua
+{
+  site_name = 'Freifunk Hochstift',
+  ...
+},
+```

+ 58 - 7
ffho/ffho-site-auto-select/ReadMe.md

@@ -1,16 +1,67 @@
 ffho-site-auto-select
 =====================
 
-Autoselect correct site-code by geocoordinates during upgrade and by ``gluon-neighbour-info`` hourly.
-One can specify a default site within site.conf, if the coordinates do not match to any site defined within extra/geo.json.
+This Package tries to autoselect the correct site-code of gluon nodes.
+
+If geocoordinates are set it matchs them to the areas provided by geo.json file.
+If there is no match, the *geo-default-site*, specified in site.conf, is selected.
+If no coordinates are set, it tries to discover the site-code via
+`gluon-neighbour-info` hourly.
 
 site.conf
 ---------
 
-site_select.geo_default_site : optional
-    - ``'ffho_uml'``
+**site_select.geo_default_site: optional**
+- default site_code if geolocation is set but does not match to defined areas.
+
+### example
+```lua
+{
+  site_select = {
+    default_site = 'ffho_uml',
+  },
+  ...
+},
+```
+
+site/extra/geo.json
+-------------------
 
-extra/geo.json
---------------
+File with geojson format. The corresponding `site_code` has to be defined within
+`"properties"` section as `"site_code": "ffho_abn"`.
 
-File with geojson format. The corresponding site_code has to be defined within ``properties`` section as ``"site_code": "ffho_abn"``.
+### example
+```json
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [
+              8.8845,
+              51.69
+            ],
+            [
+              8.8765,
+              51.6925
+            ],
+            [
+              8.8815,
+              51.7105
+            ],
+            ...
+          ]
+        ]
+      },
+      "properties": {
+        "site_code": "ffho_abn"
+      }
+    },
+    ...
+  ]
+}
+```

+ 106 - 0
ffho/ffho-site-generate/ReadMe.md

@@ -0,0 +1,106 @@
+ffho-site-generate
+==================
+
+This package generates the needed `site.json` directly on the node after firmware
+upgrad has been performed. This can be used, to support different sites/regions
+within one firmware image. The default `site.json` is partially overridden by the
+variables defined in `site/extra/sites.conf` and `site/extra/groups.conf`.
+
+This does not belong to the `site.mk`.
+
+/etc/config/currentsite
+-----------------------
+
+**currentsite.current.name:**
+- Site, the node belogs to
+
+### example
+```
+config site 'current'
+	option name 'ffho_abn'
+```
+
+site/extra/sites.conf
+---------------------
+
+Array of possible sites, containing site specific configuration different to the
+original site.conf and group specific config. Same configuration as in the site.conf
+can be done here.
+
+**site_select.group: optional**
+- specify a group out of `site/extra/groups.conf` the site belongs to
+
+### example
+```
+{
+  {
+    site_name = 'Freifunk Hochstift - Altenbeken',
+    site_code = 'ffho_abn',
+    wifi24 = {
+      ap = {
+        ssid = 'hochstift.freifunk.net/altenbkn',
+      },
+    },
+    wifi5 = {
+      ap = {
+        ssid = 'hochstift.freifunk.net/altenbkn',
+      },
+    },
+    site_select = {
+      group = 'ffho_ost',
+    },
+  },
+  ...
+}
+```
+
+site/extra/groups.conf
+----------------------
+
+Array of groups, containing group specific configuration different to the original
+site.conf. Same configuration as in the site.conf can be done here.
+
+### example
+```
+{
+  ffho_ost = {
+    prefix4 = '10.132.xxx.0/21',
+    prefix6 = '2a03:2260:2342:2303::/64',
+    wifi24 = {
+      ibss = {
+        ssid = 'ffho-mesh-ost',
+        bssid = '02:ff:03:ff:00:24',
+      },
+    },
+    wifi5 = {
+      ibss = {
+        ssid = 'ffho-mesh-ost',
+        bssid = '02:ff:03:ff:00:05',
+      },
+    },
+    next_node = {
+      ip4 = '10.132.xxx.1',
+      ip6 = '2a03:2260:2342:2303::1',
+      mac = '02:ff:03:ff:00:00',
+    },
+    fastd_mesh_vpn = {
+      groups = {
+        backbone = {
+          peers = {
+            gw01 = {
+              key = 'GW01_KEY',
+              remotes = {
+                '"gw01.ffho.net" port 10003',
+                ...
+              },
+            },
+            ...
+          },
+        },
+      },
+    },
+  },
+  ...
+}
+```
+

+ 17 - 4
ffho/ffho-status-page/ReadMe.md

@@ -1,11 +1,24 @@
 ffho-status-page
 ================
 
-This is a customized version of the *old* ``gluon-status-page``. Link to the map
-can be specified within the ``site.conf``.
+This is a customized version of the *old* `gluon-status-page`.
+
+A link to a (geographical) map can be specified within the `site.conf` and it
+will be shown together with the koordinates. To identify the node, its nodeid
+will be added at the end.
 
 site.conf
 ---------
 
-status_page.location_link : optional
-    - ``'https://map.hochstift.freifunk.net/#!v:m;n:'`` nodeid will be added at the end.
+**status_page.location_link: optional**
+- Link to a (geographical) map
+
+### example
+```lua
+{
+  status_page = {
+    location_link = 'https://map.hochstift.freifunk.net/#!v:m;n:',
+  },
+  ...
+},
+```

+ 23 - 6
ffho/ffho-wifi-mesh-macfilter/ReadMe.md

@@ -1,9 +1,26 @@
 ffho-wifi-mesh-macfilter
 ========================
 
-Setting plink_action [block|open], when 802.11s mesh-interface comes up. Define
-filterpolicy in uci wireless.<wifi-iface>.macfilter=[disable|deny|allow]. Deny
-sets ``iw dev <device> station set <mac> plink_action block`` and allow sets
-``iw dev <device> mesh_param mesh_auto_open_plink=0`` and ``iw dev <device>
-station set <mac> plink_action open``. List MAC addresses (divided by spaces) in
-``wireless.<wifi-iface>.maclist``.
+Setting plink_action [block|open], when 802.11s mesh-interface comes up.
+
+/etc/config/wireless
+--------------------
+
+**wireless.wifi-iface.macfilter: optional**
+- `disable`, disables the macfilter
+- `deny`, blocks the listed MACs by executing
+  `iw dev $device station set $mac plink_action block`
+- `allow`, only allows the listed MACs by executing
+  `iw dev $device mesh_param mesh_auto_open_plink=0` and
+  `iw dev $device$ station set $mac plink_action open`
+
+**wireless.$wifi-iface.maclist: optional**
+List of MAC addresses (devided by spaces)
+
+### example
+```
+config wifi-iface 'mesh_radio0'
+	option macfilter 'deny'
+	option maxlist '01:23:45:67:89:ab 45:67:89:ab:cd:ef'
+	...
+```