├── img
    ├── config.png
    ├── graph.png
    └── overview.png
├── bachelor_thesis
    ├── bachelor.pdf
    ├── img
    │   ├── graph.png
    │   ├── login.png
    │   ├── node.png
    │   ├── config.png
    │   ├── grafana.png
    │   ├── serial.jpg
    │   ├── ul-logo.png
    │   ├── backbone.png
    │   ├── overview.png
    │   ├── toolstack.png
    │   ├── topology.png
    │   ├── mgmt-testbed.png
    │   ├── overview-24h.png
    │   ├── htop-prometheus.png
    │   ├── cloud-sync-steps.png
    │   ├── seq_show_netsjon.png
    │   └── seq_change_mesh_pw.png
    ├── Makefile
    ├── prometheus.yml
    ├── rules.yml
    ├── flash.txt
    ├── lime-defaults
    ├── bachelor.bib
    ├── ieee.csl
    └── bachelor.md
├── packages
    ├── meshrc
    │   ├── files
    │   │   ├── web
    │   │   │   ├── etc
    │   │   │   │   └── uci-defaults
    │   │   │   │   │   └── restart_rpcd.sh
    │   │   │   ├── usr
    │   │   │   │   ├── share
    │   │   │   │   │   └── rpcd
    │   │   │   │   │   │   └── acl.d
    │   │   │   │   │   │       └── meshrc.json
    │   │   │   │   ├── libexec
    │   │   │   │   │   └── rpcd
    │   │   │   │   │   │   └── meshrc
    │   │   │   │   └── bin
    │   │   │   │   │   └── p2n
    │   │   │   └── www
    │   │   │   │   └── meshrc
    │   │   │   │       ├── static
    │   │   │   │           ├── js
    │   │   │   │           │   ├── settings.js
    │   │   │   │           │   ├── fmt.js
    │   │   │   │           │   ├── overview.js
    │   │   │   │           │   ├── graph.js
    │   │   │   │           │   ├── config.js
    │   │   │   │           │   └── netjsongraph.js
    │   │   │   │           └── css
    │   │   │   │           │   ├── netjsongraph.css
    │   │   │   │           │   └── netjsongraph-theme.css
    │   │   │   │       └── index.html
    │   │   ├── client
    │   │   │   ├── etc
    │   │   │   │   └── init.d
    │   │   │   │   │   └── meshrc-client
    │   │   │   └── usr
    │   │   │   │   └── bin
    │   │   │   │       └── meshrc-client
    │   │   ├── initial
    │   │   │   ├── etc
    │   │   │   │   └── init.d
    │   │   │   │   │   └── meshrc-initial
    │   │   │   └── usr
    │   │   │   │   └── bin
    │   │   │   │       └── meshrc-initial
    │   │   └── cli
    │   │   │   └── usr
    │   │   │       └── bin
    │   │   │           └── meshrc-cli
    │   └── Makefile
    └── prometheus-bmx7-targets
    │   ├── files
    │       ├── etc
    │       │   └── init.d
    │       │   │   └── prometheus-bmx7-targets
    │       └── usr
    │       │   └── bin
    │       │       └── prometheus-bmx7-targets
    │   └── Makefile
├── root
    └── etc
    │   ├── uci-defaults
    │       └── zz-prometheus-node-exporter-bind
    │   └── config
    │       └── lime-defaults
└── README.md


/img/config.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/img/config.png


--------------------------------------------------------------------------------
/img/graph.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/img/graph.png


--------------------------------------------------------------------------------
/img/overview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/img/overview.png


--------------------------------------------------------------------------------
/bachelor_thesis/bachelor.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/bachelor.pdf


--------------------------------------------------------------------------------
/bachelor_thesis/img/graph.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/graph.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/login.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/login.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/node.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/node.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/config.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/config.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/grafana.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/grafana.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/serial.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/serial.jpg


--------------------------------------------------------------------------------
/bachelor_thesis/img/ul-logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/ul-logo.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/backbone.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/backbone.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/overview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/overview.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/toolstack.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/toolstack.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/topology.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/topology.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/mgmt-testbed.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/mgmt-testbed.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/overview-24h.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/overview-24h.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/htop-prometheus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/htop-prometheus.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/cloud-sync-steps.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/cloud-sync-steps.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/seq_show_netsjon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/seq_show_netsjon.png


--------------------------------------------------------------------------------
/bachelor_thesis/img/seq_change_mesh_pw.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/aparcar/meshrc/HEAD/bachelor_thesis/img/seq_change_mesh_pw.png


--------------------------------------------------------------------------------
/bachelor_thesis/Makefile:
--------------------------------------------------------------------------------
1 | all:
2 | 	pandoc --template=eisvogel bachelor.md -o bachelor.pdf -N --listings --filter pandoc-citeproc --csl ieee.csl
3 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/etc/uci-defaults/restart_rpcd.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 | 
3 | # make rpcd aware of the added meshrc commands
4 | /etc/init.d/rpcd restart
5 | 


--------------------------------------------------------------------------------
/root/etc/uci-defaults/zz-prometheus-node-exporter-bind:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 | 
3 | uci set prometheus-node-exporter.main.listen_address '::'
4 | uci commit prometheus-node-exporter
5 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/usr/share/rpcd/acl.d/meshrc.json:
--------------------------------------------------------------------------------
 1 | {
 2 | 	"meshrc": {
 3 | 		"description": "control the mesh",
 4 | 		"read": {
 5 | 			"ubus": {
 6 | 				"meshrc": [
 7 | 					"*"
 8 | 				]
 9 | 			}
10 | 		}
11 | 	}
12 | }
13 | 


--------------------------------------------------------------------------------
/bachelor_thesis/prometheus.yml:
--------------------------------------------------------------------------------
 1 | global:
 2 |   scrape_interval: 2m               # Scrape nodes every 2 minutes
 3 | 
 4 | rule_files:
 5 |   - /etc/rules.yml
 6 | 
 7 | scrape_configs:
 8 |   - job_name: "mesh"
 9 |     file_sd_configs:
10 |     - files:
11 |       - "/tmp/targets_bmx7.json"    # File created by prometheus-bmx7-targets
12 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/client/etc/init.d/meshrc-client:
--------------------------------------------------------------------------------
 1 | #!/bin/sh /etc/rc.common
 2 | 
 3 | START=92
 4 | USE_PROCD=1
 5 | 
 6 | BIN=/usr/bin/meshrc-client
 7 | 
 8 | start_service() {
 9 | 	procd_open_instance "meshrc-client"
10 | 	procd_set_param command "$BIN"
11 | 	procd_set_param stdout 1
12 | 	procd_set_param stderr 1
13 | 	procd_set_param respawn
14 | 	procd_close_instance
15 | }
16 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/initial/etc/init.d/meshrc-initial:
--------------------------------------------------------------------------------
 1 | #!/bin/sh /etc/rc.common
 2 | 
 3 | START=91
 4 | USE_PROCD=1
 5 | 
 6 | BIN=/usr/bin/meshrc-initial
 7 | 
 8 | start_service() {
 9 | 	procd_open_instance "meshrc-initial"
10 | 	procd_set_param command "$BIN"
11 | 	procd_set_param stdout 1
12 | 	procd_set_param stderr 1
13 | 	procd_set_param respawn
14 | 	procd_close_instance
15 | }
16 | 


--------------------------------------------------------------------------------
/packages/prometheus-bmx7-targets/files/etc/init.d/prometheus-bmx7-targets:
--------------------------------------------------------------------------------
 1 | #!/bin/sh /etc/rc.common
 2 | START=92
 3 | USE_PROCD=1
 4 | 
 5 | BIN=/usr/bin/prometheus-bmx7-targets
 6 | 
 7 | start_service() {
 8 | 	procd_open_instance "prometheus-bmx7-targets"
 9 | 	procd_set_param command "$BIN" -d
10 | 	procd_set_param stdout 1
11 | 	procd_set_param stderr 1
12 | 	procd_set_param respawn
13 | 	procd_close_instance
14 | }
15 | 


--------------------------------------------------------------------------------
/bachelor_thesis/rules.yml:
--------------------------------------------------------------------------------
 1 | groups:
 2 | - name: rules.yml
 3 |   rules:
 4 |   - alert: node_down
 5 |     expr: up{job="mesh"} == 0
 6 |     for: 10m
 7 |     annotations:
 8 |       summary: node {{ $labels.hostname }} is down
 9 |   - alert: node_high_load
10 |     expr: load_15{job="mesh"} > 1
11 |     annotations:
12 |       summary: node {{ $labels.hostname }} has load of over 2.0
13 |   - alert: link_bad_quality
14 |     expr: bmx7_link_rxRate{job="mesh"} < 1000*1000
15 |     for: 10m
16 |     annotations:
17 |       summary: link between {{ $labels.source }} and {{ $labels.target }} slow
18 | 


--------------------------------------------------------------------------------
/packages/prometheus-bmx7-targets/Makefile:
--------------------------------------------------------------------------------
 1 | include $(TOPDIR)/rules.mk
 2 | 
 3 | PKG_NAME:=prometheus-bmx7-targets
 4 | PKG_VERSION:=0.1
 5 | PKG_RELEASE:=4
 6 | 
 7 | include $(INCLUDE_DIR)/package.mk
 8 | 
 9 | define Package/prometheus-bmx7-targets
10 |   SECTION:=utils
11 |   CATEGORY:=Utilities
12 |   TITLE:=prometheus-bmx7-targets
13 |   MAINTAINER:=Paul Spooren <spooren@informatik.uni-leipzig.de>
14 |   DEPENDS:=bmx7 +bmx7-json +inotifywait +jshn
15 | endef
16 | 
17 | define Build/Compile
18 | endef
19 | 
20 | define Build/Configure
21 | endef
22 | 
23 | define Package/prometheus-bmx7-targets/install
24 | 	$(CP) files/* $(1)/
25 | endef
26 | 
27 | $(eval $(call BuildPackage,prometheus-bmx7-targets))
28 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/settings.js:
--------------------------------------------------------------------------------
 1 | // where to find the ubus daeom
 2 | ubus_url = "/ubus"
 3 | 
 4 | // properties to show in graph and overview table
 5 | // must exists with same name in in the NetJson output generated by `p2n`
 6 | // also add formater function if desired
 7 | properties_active = {
 8 |     "load": ["Load", false],
 9 |     "memory": ["Free memory", fmt_percent],
10 |     "traffic_mesh": ["Traffic Mesh", fmt_filesize],
11 |     "traffic_ap": ["Traffic AP", fmt_filesize],
12 |     "clients": ["Clients", fmt_default],
13 |     "model": ["Device", fmt_default],
14 |     "uptime": ["Uptime", fmt_duration]
15 | }
16 | 
17 | // counter for ubus calls - shouldn't be changed
18 | ubus_counter = 1
19 | 
20 | 


--------------------------------------------------------------------------------
/bachelor_thesis/flash.txt:
--------------------------------------------------------------------------------
 1 | daemon.info meshrc-initial: Try neighbor fe80::<mac1>:
 2 | daemon.err meshrc-initial: Downloading 'http://[fe80::<mac1>%br-lan]:8123/config.tar.gz'
 3 | daemon.err meshrc-initial: Connecting to fe80::<mac1>:8123
 4 | daemon.err meshrc-initial: Connection error: Connection failed
 5 | daemon.info meshrc-initial: Try neighbor fe80::<mac2>:
 6 | daemon.err meshrc-initial: Downloading 'http://[fe80::<mac>%br-lan]:8123/config.tar.gz'
 7 | daemon.err meshrc-initial: Connecting to fe80::<mac2>:8123
 8 | daemon.err meshrc-initial: Writing to 'config.tar.gz'
 9 | config.tar.gz        100% |*******************************|   670   0:00:00 ETA
10 | daemon.err meshrc-initial: Download completed (670 bytes)
11 | daemon.info meshrc-initial: successfully downloaded config
12 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/css/netjsongraph.css:
--------------------------------------------------------------------------------
 1 | njg-hidden {
 2 |     display: none !important;
 3 |     visibility: hidden !important;
 4 | }
 5 | 
 6 | .njg-tooltip{
 7 |     font-family: sans-serif;
 8 |     font-size: 10px;
 9 |     fill: #000;
10 |     opacity: 0.5;
11 |     text-anchor: middle;
12 | }
13 | 
14 | .njg-overlay{
15 |     display: none;
16 |     position: absolute;
17 |     z-index: 11;
18 | }
19 | 
20 | .njg-close{
21 |     cursor: pointer;
22 |     position: absolute;
23 |     right: 10px;
24 |     top: 10px;
25 | }
26 | .njg-close:before { content: "\2716"; }
27 | 
28 | .njg-metadata{
29 |     display: none;
30 |     position: absolute;
31 |     z-index: 12;
32 | }
33 | 
34 | .njg-node{ cursor: pointer }
35 | .njg-link{ cursor: pointer }
36 | 
37 | #njg-select-group {
38 |     text-align: center;
39 |     box-shadow: 0 0 10px #ccc;
40 |     position: fixed;
41 |     left: 50%;
42 |     top: 50%;
43 |     width: 50%;
44 |     margin-top: -7.5em;
45 |     margin-left: -25%;
46 |     padding: 5em 2em;
47 | }
48 | 
49 | #njg-select-group select {
50 |     font-size: 2em;
51 |     padding: 10px 15px;
52 |     width: 50%;
53 |     cursor: pointer;
54 | }
55 | 
56 | #njg-select-group option {
57 |     padding: 0.5em;
58 | }
59 | 
60 | #njg-select-group option[value=""] {
61 |     color: #aaa;
62 | }
63 | 


--------------------------------------------------------------------------------
/bachelor_thesis/lime-defaults:
--------------------------------------------------------------------------------
 1 | config lime system
 2 |     option hostname 'meshrc-%m1%m2%m3' # initial hostname is MAC based
 3 |     option domain 'lan'
 4 |     option keep_on_upgrade 'libremesh base-files-essential /etc/sysupgrade.conf'
 5 | 
 6 | config lime network
 7 |     option primary_interface eth0
 8 |     option main_ipv4_address '10.%m1.%m2.1/24' # IP is MAC based
 9 |     option main_ipv6_address 'fd43:1508:%m1%m2:%m300::/64'
10 |     list protocols ieee80211s # enable mesh
11 |     list protocols lan
12 |     list protocols bmx7
13 |     list resolvers '1.1.1.1'  # dns providers to use
14 |     option bmx7_over_batman false
15 |     option bmx7_pref_gw none
16 |     option bmx7_mtu '1500'
17 | 
18 | config lime wifi
19 |     option legacy_rates '0'   # enable wider spectrum
20 |     option country 'DE'
21 |     option distance '1000'
22 |     option ap_ssid '%H'       # set AP name to hostname
23 |     option ap_encryption 'psk2+aes'
24 |     option ieee80211s_mesh_fwding '0'
25 |     option ieee80211s_mesh_id 'mesh'
26 |     option ieee80211s_encryption 'psk2+aes'
27 | 
28 | config smart_wifi 'smart_wifi'
29 |     option mesh_2ghz '0'            # disable mesh on 2.4 ghz
30 |     list channels_2ghz '13 9 5 1'   # channels to use if multiple radios exists
31 |     list channels_5ghz '128 100'    # same for 5ghz frequencies
32 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/initial/usr/bin/meshrc-initial:
--------------------------------------------------------------------------------
 1 | #!/bin/sh
 2 | 
 3 | # interface to search for neighbors
 4 | INTERFACE="br-lan"
 5 | # name of configuration file to ask for
 6 | CONFIG="config.tar.gz"
 7 | # port where server hosts the config
 8 | PORT="8123"
 9 | 
10 | # loop until config is found, below is an conditional break if config is found
11 | while true; do
12 |     # get list of directly connected neighbors
13 |     neighbors="$(ping6 -I ${INTERFACE} ff02::1 -c 2 | awk '{ print $4 }' | \
14 |             tail -n +2 | head -n -4 | cut -d'%' -f 1 | sort | uniq)"
15 | 
16 |     # iterate over all found neighbors
17 |     for neighbor in $neighbors; do
18 |         echo "Try neighbor $neighbor"
19 |         # try to download configuration
20 |         wget "http://[${neighbor%:}%${INTERFACE}]:${PORT}/config.tar.gz" -P /tmp
21 |         # if configuration is successfully downloaded stop the loop
22 |         [[ -e "/tmp/${CONFIG}" ]] && { 
23 |             echo "successfully downloaded config"
24 |             break 
25 |         }
26 |     done
27 |     sleep 5
28 | done
29 | 
30 | # disable initial service until firstboot reset
31 | /etc/init.d/meshrc-initial disable
32 | 
33 | # extract config files to / of node
34 | tar xz -C / -f /tmp/config.tar.gz
35 | 
36 | # reboot device to make LEDs blink and apply files of /etc/uci-defaults
37 | reboot
38 | 


--------------------------------------------------------------------------------
/root/etc/config/lime-defaults:
--------------------------------------------------------------------------------
 1 | config lime system
 2 |     option hostname 'meshrc-%m1%m2%m3'
 3 |     option domain 'lan'
 4 |     option keep_on_upgrade 'libremesh base-files-essential /etc/sysupgrade.conf'
 5 | 
 6 | config lime network
 7 |     option primary_interface eth0
 8 |     option main_ipv4_address '10.%m1.%m2.1/24'
 9 |     option main_ipv6_address 'fd43:1508:%m1%m2:%m300::/64'
10 |     list protocols ieee80211s
11 |     list protocols lan
12 |     list protocols bmx7
13 |     list resolvers '1.1.1.1'
14 |     list resolvers '9.9.9.9'
15 |     option bmx7_over_batman false
16 |     option bmx7_pref_gw none
17 |     option bmx7_mtu '1500'
18 | 
19 | config lime wifi
20 |     option channel_2ghz '11'
21 |     option channel_5ghz '128'
22 |     option htmode_5ghz 'HT20'
23 |     option country 'DE'
24 |     option distance '1000'
25 |     #disabled wifi on startup
26 |     #list modes 'ap'
27 |     #list modes 'ieee80211s'
28 |     option ap_ssid '%H'
29 |     option ap_encryption 'psk2+aes'
30 |     option ap_key 'ap-password'
31 |     option ieee80211s_mesh_fwding '0'
32 |     option ieee80211s_mesh_id 'mesh'
33 |     option ieee80211s_encryption 'psk2+aes'
34 |     option ieee80211s_key 'mesh-password'
35 | 
36 | config smart_wifi 'smart_wifi'
37 |     option ap_2ghz '1'
38 |     option ap_5ghz '0'
39 |     option mesh_2ghz '0'
40 |     option mesh_5ghz '1'
41 |     option all_to_mesh '0'
42 |     option all_to_ap '0'
43 |     list channels_2ghz '13 9 5 1'
44 |     list channels_5ghz '128 100'
45 | 
46 | config meshrc
47 |     list trusted '0F44CA257F447C838E602410F8E14F4C21D96E87DFCB9C3E867BC2BB'
48 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/fmt.js:
--------------------------------------------------------------------------------
 1 | // some simple formating functions
 2 | 
 3 | // return value or "-" if undefined
 4 | function fmt_default(input) {
 5 |     return (input && input.length) ? input : "-";
 6 | }
 7 | 
 8 | // turn float into formated percent number
 9 | function fmt_percent(percent) {
10 |     if (isNaN(percent)) return '-'
11 |     return Number.parseFloat(percent).toFixed(2) + '%'
12 | }
13 | 
14 | // format seconds to human readable duration
15 | function fmt_duration(duration) {
16 |     if (isNaN(duration)) return '-'
17 |     duration = parseInt(duration)
18 |     days = Math.floor(duration / (60 * 60 * 24))
19 |     duration %= 60 * 60 * 24
20 |     hours = Math.floor(duration / (60 * 60))
21 |     duration %= 60 * 60
22 |     minutes = Math.floor(duration / 60)
23 |     if (days > 1) return days + 'd'
24 |     if (days == 1) return (hours + 24) + 'h'
25 |     if (hours > 1) return hours + 'h'
26 |     if (hours == 1) return (minutes + 60) + 'm'
27 |     return minutes + 'm'
28 | }
29 | 
30 | // format Bits/Bytes to human readable size
31 | function fmt_filesize(size, suffix) {
32 |     if (typeof suffix == 'undefined') {
33 |         suffix = 'B'
34 |     }
35 |     if (isNaN(size)) return '-'
36 |     size = Number.parseFloat(size)
37 |     units = [
38 |         '',
39 |         'Ki',
40 |         'Mi',
41 |         'Gi'
42 |     ]
43 |     for (unit in units) {
44 |         if (Math.abs(size) < 1024) {
45 |             return size.toFixed(1) + units[unit] + suffix
46 |         }
47 |         size /= 1024
48 |     }
49 |     return size.toFixed(1) + 'Ti' + suffix
50 | }
51 | 


--------------------------------------------------------------------------------
/packages/prometheus-bmx7-targets/files/usr/bin/prometheus-bmx7-targets:
--------------------------------------------------------------------------------
 1 | #!/bin/sh
 2 | 
 3 | . /usr/share/libubox/jshn.sh
 4 | 
 5 | # touch targets_bmx7.json to make sure it exists
 6 | touch /tmp/targets_bmx7.json
 7 | 
 8 | update() {
 9 |     # preserve existing bmx7 nodes as targets
10 |     cat /tmp/targets_bmx7.json | tail -n +2 | head -n -1 > /tmp/targets_bmx7.tmp
11 | 
12 |     json_load "$(bmx7 -c jshow=originators)"
13 |     json_select "originators"
14 |     idx="1"
15 | 
16 |     while json_get_type Type "$idx" && [ "$Type" == object ]; do
17 |         json_select "$idx"
18 |         json_get_var shortId shortId
19 |         json_get_var name name
20 |         json_get_var primaryIp primaryIp
21 |         printf "$primaryIp $name\n$primaryIp $shortId\n" >> /tmp/hosts/bmx7
22 |         printf "{ \"targets\": [ \"[${primaryIp}]:9100\" ],\"labels\": { \"shortId\": \"${shortId}\", \"hostname\": \"${name}\"}},\n" >> /tmp/targets_bmx7.tmp
23 |         json_select ..
24 |         $((idx++)) 2> /dev/null
25 |     done
26 | 
27 |     # create new prometheus targets_bmx7 file
28 |     echo "[" > /tmp/targets_bmx7.json
29 |     cat /tmp/targets_bmx7.tmp | sort | uniq >> /tmp/targets_bmx7.json
30 |     echo "{} ]" >> /tmp/targets_bmx7.json
31 | }
32 | 
33 | daemon() {
34 |     while true; do
35 |         update
36 | 
37 |         inotifywait -e create -e delete -q /var/run/bmx7/json/originators/ || \
38 |                 sleep 60
39 |     done
40 | }
41 | 
42 | case $1 in
43 |     -d)
44 |         daemon
45 |         ;;
46 |     -r)
47 |         [[ -n $2 ]] || exit 1
48 |         sed -i "/$2/d" /tmp/targets_bmx7.tmp
49 |         ;;
50 |     *)
51 |         update
52 |         ;;
53 | esac
54 | 
55 | 
56 | 


--------------------------------------------------------------------------------
/packages/meshrc/Makefile:
--------------------------------------------------------------------------------
 1 | include $(TOPDIR)/rules.mk
 2 | 
 3 | PKG_NAME:=meshrc
 4 | PKG_VERSION:=0.8
 5 | PKG_RELEASE:=1
 6 | 
 7 | PKG_MAINTAINER:=Paul Spooren <spooren@informatik.uni-leipzig.de>
 8 | 
 9 | include $(INCLUDE_DIR)/package.mk
10 | 
11 | define Package/meshrc/Default
12 |   SECTION:=utils
13 |   CATEGORY:=Utilities
14 |   TITLE:=meshrc
15 |   PKGARCH:=all
16 | endef
17 | 
18 | define Package/meshrc-initial
19 |   $(call Package/meshrc/Default)
20 |   TITLE+= initial
21 |   DEPENDS:=+lime-system
22 | endef
23 | 
24 | define Package/meshrc-client
25 |   $(call Package/meshrc/Default)
26 |   TITLE+= client
27 |   DEPENDS:=bmx7 +lime-system +bmx7-sms +inotifywait
28 | endef
29 | 
30 | define Package/meshrc-cli
31 |   $(call Package/meshrc/Default)
32 |   TITLE+= cli
33 |   DEPENDS:=bmx7 +lime-system +bmx7-sms
34 | endef
35 | 
36 | define Package/meshrc-web
37 |   $(call Package/meshrc/Default)
38 |   TITLE+= web
39 |   DEPENDS:=+uhttpd-mod-ubus +python3-light +python3-email +python3-idna +python3-codecs
40 | endef
41 | 
42 | Build/Compile=
43 | 
44 | define Package/meshrc-initial/install
45 | 		$(INSTALL_DIR) $(1)/
46 | 		$(CP) -r files/initial/* $(1)/
47 | endef
48 | 
49 | define Package/meshrc-client/install
50 | 		$(INSTALL_DIR) $(1)/
51 | 		$(CP) -r files/client/* $(1)/
52 | endef
53 | 
54 | define Package/meshrc-cli/install
55 | 		$(INSTALL_DIR) $(1)/
56 | 		$(CP) -r files/cli/* $(1)/
57 | endef
58 | 
59 | define Package/meshrc-web/install
60 | 		$(INSTALL_DIR) $(1)/
61 | 		$(CP) -r files/web/* $(1)/
62 | endef
63 | 
64 | $(eval $(call BuildPackage,meshrc-initial))
65 | $(eval $(call BuildPackage,meshrc-client))
66 | $(eval $(call BuildPackage,meshrc-cli))
67 | $(eval $(call BuildPackage,meshrc-web))
68 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/overview.js:
--------------------------------------------------------------------------------
 1 | // draws table based on NetJson
 2 | function reload_overview() {
 3 |     console.log("table_content" + netjson_data)
 4 |     tbl = document.getElementById("table_overview")
 5 |     tbl.innerHTML = ""
 6 |     var header = tbl.createTHead();
 7 |     var header_row = header.insertRow(0);
 8 |     header_row.insertCell().innerHTML = "Hostname"
 9 |     for (var property in properties_active) {
10 |         header_row.insertCell().innerHTML = properties_active[property][0]
11 |     }
12 | 
13 |     var nodes = netjson_data.nodes
14 | 
15 |     for (node_index in nodes) {
16 |         var node = nodes[node_index]
17 |         var tr = tbl.insertRow();
18 |         var properties = node.properties
19 |         var button = document.createElement("a")
20 |         button.href = "#node" + node.id
21 |         button.classList.add("btn")
22 |         button.style.width = "100%"
23 |         button.innerHTML = node.label
24 | 
25 |         // change class based on load
26 |         if (properties.node_state == "down") {
27 |             button.classList.add("btn-danger")
28 |             button.href = ""
29 |         } else if (properties.node_state == "up-mload") {
30 |             button.classList.add("btn-warning")
31 |         } else {
32 |             button.classList.add("btn-success")
33 |         }
34 | 
35 |         tr.insertCell().appendChild(button);
36 |         for (var property in properties_active) {
37 |             var td = tr.insertCell();
38 |             if (!properties_active[property][1]) {
39 |                 var value = fmt_default(properties[property])
40 |             } else {
41 |                 var value = properties_active[property][1](properties[property])
42 |             }
43 |             td.appendChild(document.createTextNode(value));
44 |         }
45 |     }
46 | }
47 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/graph.js:
--------------------------------------------------------------------------------
 1 | // loads up the NetJsonGrah and slighty modifies "onClickNode" and "onClickLink"
 2 | // functions, both are copied from the lib and expanded to show more information
 3 | function reload_graph() {
 4 |     d3.select("svg").remove(); // resets the graph
 5 |     d3.netJsonGraph(netjson_data, {
 6 |         el: "#graph",
 7 |         linkDistance: 150,
 8 |         charge: -200,
 9 |         circleRadius: 12,
10 |         defaultStyle: false,
11 |         linkClassProperty: "best_rate",
12 |         nodeClassProperty: "node_state",
13 |         gravity: 0.03,
14 |         onClickNode: function(n) {
15 |             var overlay = d3.select(".njg-overlay"),
16 |                 overlayInner = d3.select(".njg-overlay > .njg-inner"),
17 |                 html = "<p><b>Short ID</b>: " + n.id + "</p>";
18 |             if (n.id) {
19 |                 if (n.label) {
20 |                     html += "<p><b>Hostname</b>: <a href='#node" + n.id + "'>" + n.label + "</a></p>";
21 |                 }
22 |             } else {
23 |                 if (n.label) {
24 |                     html += "<p><b>Hostname</b>: " + n.label + "</p>";
25 |                 }
26 |             }
27 |             if (n.properties) {
28 |                 for (var property in properties_active) {
29 |                     if (!properties_active[property][1]) {
30 |                         var value = n.properties[property]
31 |                     } else {
32 |                         var value = properties_active[property][1](n.properties[property])
33 |                     }
34 |                     html += "<p><b>" + properties_active[property][0] + "</b>: " + value + "</p>";
35 |                 }
36 |             }
37 | 
38 |             if (n.linkCount) {
39 |                 html += "<p><b>Link Count</b>: " + n.linkCount + "</p>";
40 |             }
41 |             if (n.local_addresses) {
42 |                 html += "<p><b>Local Addresses</b>:<br>" + n.local_addresses.join('<br>') + "</p>";
43 |             }
44 |             overlayInner.html(html);
45 |             overlay.classed("njg-hidden", false);
46 |             overlay.style("display", "block");
47 |             removeOpenClass();
48 |             d3.select(this).classed("njg-open", true);
49 |         },
50 |         onClickLink: function(l) {
51 |             var overlay = d3.select(".njg-overlay"),
52 |                 overlayInner = d3.select(".njg-overlay > .njg-inner"),
53 |                 html = "<p><b>source</b>: " + (l.source.label || l.source.id) + "</p>";
54 |             html += "<p><b>target</b>: " + (l.target.label || l.target.id) + "</p>";
55 |             if (l.properties) {
56 |                 for (var key in l.properties) {
57 |                     if (!l.properties.hasOwnProperty(key) || key == "devs" || key == "rate") {
58 |                         continue;
59 |                     }
60 |                     html += "<p><b>" + key.replace(/_/g, " ") + "</b>: " + l.properties[key] + "</p>";
61 |                 }
62 |             }
63 |             html += "<b>devices:<b></br>"
64 |             for (var dev in l.properties.devs) {
65 |                 html += "- " + dev + ": " + fmt_filesize(l.properties.devs[dev], "b/s") + "</br>";
66 |             }
67 |             overlayInner.html(html);
68 |             overlay.classed("njg-hidden", false);
69 |             overlay.style("display", "block");
70 |             removeOpenClass();
71 |             d3.select(this).classed("njg-open", true);
72 |         },
73 |     });
74 | }
75 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/usr/libexec/rpcd/meshrc:
--------------------------------------------------------------------------------
  1 | #!/bin/sh
  2 | 
  3 | # load OpenWrt script to handle json
  4 | . /usr/share/libubox/jshn.sh
  5 | 
  6 | case "$1" in
  7 | # this creates a special json format description of the service which is then
  8 | # generically integrated into OpenWrts ubus daemon
  9 | list)
 10 |     json_init
 11 |     json_add_object "hostname"
 12 |     json_add_string "node_id"
 13 |     json_add_string "param"
 14 |     json_close_object
 15 |     json_add_object "mesh_id"
 16 |     json_add_string "node_id"
 17 |     json_add_string "param"
 18 |     json_close_object
 19 |     json_add_object "mesh_key"
 20 |     json_add_string "node_id"
 21 |     json_add_string "param"
 22 |     json_close_object
 23 |     json_add_object "ap_key"
 24 |     json_add_string "param"
 25 |     json_add_string "node_id"
 26 |     json_close_object
 27 |     json_add_object "firstboot"
 28 |     json_add_string "param"
 29 |     json_add_string "node_id"
 30 |     json_close_object
 31 |     json_add_object "raw"
 32 |     json_add_string "param"
 33 |     json_add_string "node_id"
 34 |     json_close_object
 35 |     json_add_object "set_ssh"
 36 |     json_add_string "param"
 37 |     json_add_string "node_id"
 38 |     json_close_object
 39 |     json_add_object "get_hostname"
 40 |     json_add_string "node_id"
 41 |     json_close_object
 42 |     json_add_object "get_config"
 43 |     json_close_object
 44 |     json_add_object "netjson"
 45 |     json_add_string "param"
 46 |     json_close_object
 47 |     json_add_object "initial"
 48 |     json_add_boolean "param"
 49 |     json_close_object
 50 |     json_dump
 51 |     ;;
 52 | call)
 53 |     # load input from json
 54 |     read input;
 55 |     json_load "$input"
 56 |     json_get_var node_id node_id
 57 |     json_get_var param param
 58 | 
 59 |     case "$2" in
 60 |     hostname)
 61 |         meshrc-cli -i "$node_id" -H "$param"
 62 |         ;;
 63 |     mesh_id)
 64 |         meshrc-cli -i "$node_id" -d "$param"
 65 |         ;;
 66 |     mesh_key)
 67 |         meshrc-cli -i "$node_id" -k "$param"
 68 |         ;;
 69 |     ap_key)
 70 |         meshrc-cli -i "$node_id" -a "$param"
 71 |         ;;
 72 |     firstboot)
 73 |         meshrc-cli -i "$node_id" -f "$param"
 74 |         ;;
 75 |     raw)
 76 |         meshrc-cli -i "$node_id" -r "$param"
 77 |         ;;
 78 |     set_ssh)
 79 |         meshrc-cli -i "$node_id" -s "$param"
 80 |         ;;
 81 |     # get hostname of any node
 82 |     get_hostname)
 83 |         json_load "$(cat /var/run/bmx7/json/originators/${node_id}*)"
 84 |         json_get_var hostname name
 85 |         json_init
 86 |         json_add_string "hostname" "$hostname"
 87 |         json_dump
 88 |         ;;
 89 |     # function to get currently configuration which is displayed in web interface
 90 |     get_config)
 91 |         json_init
 92 |         json_add_string "mesh_id" "$(uci -q get lime.wifi.ieee80211s_mesh_id)"
 93 |         json_add_string "mesh_key" "$(uci -q get lime.wifi.ieee80211s_key)"
 94 |         json_add_string "ap_key" "$(uci -q get lime.wifi.ap_key)"
 95 |         json_add_string "initial" "$(uci -q get lime.meshrc.initial)"
 96 |         json_add_string "ssh_keys" "$(cat /etc/dropbear/authorized_keys)"
 97 |         json_dump
 98 |         ;;
 99 |     # dump netjson
100 |     netjson)
101 |         /usr/bin/p2n "$param"
102 |         ;;
103 |     # set initial config sharing
104 |     initial)
105 |         meshrc-cli -I "$param"
106 |         ;;
107 |     esac
108 |     ;;
109 | esac
110 | 
111 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/css/netjsongraph-theme.css:
--------------------------------------------------------------------------------
  1 | .njg-overlay {
  2 |     background: #fbfbfb;
  3 |     border-radius: 2px;
  4 |     border: 1px solid #ccc;
  5 |     color: #6d6357;
  6 |     font-family: Arial, sans-serif;
  7 |     font-family: sans-serif;
  8 |     font-size: 14px;
  9 |     line-height: 20px;
 10 |     height: auto;
 11 |     min-width: 200px;
 12 |     padding: 15px;
 13 |     right: 10px;
 14 |     top: 66px;
 15 |     width: auto;
 16 | }
 17 | 
 18 | .njg-metadata {
 19 |     background: #fbfbfb;
 20 |     border-radius: 2px;
 21 |     border: 1px solid #ccc;
 22 |     color: #6d6357;
 23 |     display: none;
 24 |     font-family: Arial, sans-serif;
 25 |     font-family: sans-serif;
 26 |     font-size: 14px;
 27 |     height: auto;
 28 |     left: 10px;
 29 |     min-width: 200px;
 30 |     padding: 15px;
 31 |     top: 66px;
 32 |     width: auto;
 33 | }
 34 | 
 35 | .njg-node {
 36 |     stroke-opacity: 0.0;
 37 |     stroke-width: 7px;
 38 |     stroke: #fff;
 39 | }
 40 | 
 41 | .njg-node:hover,
 42 | .njg-node.njg-open {
 43 |     stroke-opacity: 0.5;
 44 |     stroke: #000;
 45 | }
 46 | 
 47 | .njg-link {
 48 |     cursor: pointer;
 49 |     stroke: #999;
 50 |     stroke-width: 4;
 51 |     stroke-opacity: 0.5;
 52 | }
 53 | 
 54 | .njg-link:hover,
 55 | .njg-link.njg-open {
 56 |     stroke-width: 4 !important;
 57 |     stroke-opacity: 1;
 58 | }
 59 | 
 60 | #graph {
 61 |     min-height: 99%;
 62 | }
 63 | 
 64 | html,
 65 | body {
 66 |     height: 100%
 67 | }
 68 | 
 69 | .fill {
 70 |     padding-top: 70px;
 71 |     min-height: 100%;
 72 |     height: 100%;
 73 | }
 74 | 
 75 | /* legend */
 76 | 
 77 | #legend {
 78 |     position: absolute;
 79 |     top: auto;
 80 |     left: 5px;
 81 |     bottom: 15px;
 82 |     width: auto;
 83 |     height: auto;
 84 |     max-width: 250px;
 85 |     padding: 0 15px;
 86 |     background: #fbfbfb;
 87 |     border-radius: 2px;
 88 |     border: 1px solid #ccc;
 89 |     color: #6d6357;
 90 |     font-family: Arial, sans-serif;
 91 |     font-family: sans-serif;
 92 |     font-size: 14px;
 93 | }
 94 | 
 95 | #legend p {
 96 |     line-height: 16px;
 97 |     margin: 10px 0
 98 | }
 99 | 
100 | #legend span {
101 |     width: 16px;
102 |     margin-right: 5px;
103 | }
104 | 
105 | #legend span.circle {
106 |     display: inline-block;
107 |     border-radius: 50%;
108 |     height: 16px;
109 | }
110 | 
111 | #legend span.link {
112 |     display: inline-block;
113 |     height: 5px;
114 |     border-bottom-width: 6px;
115 |     border-bottom-style: solid;
116 | }
117 | 
118 | #legend .node {
119 |     background-color: grey
120 | }
121 | 
122 | #legend .up {
123 |     background-color: green !important
124 | }
125 | 
126 | #legend .up-mload {
127 |     background-color: orange !important
128 | }
129 | 
130 | #legend .up-hload {
131 |     background-color: red !important
132 | }
133 | 
134 | #legend .up-gateway {
135 |     background-color: #9932CC !important
136 | }
137 | 
138 | #legend .over1Gbit {
139 |     border-color: #9900ff
140 | }
141 | 
142 | #legend .over100Mbit {
143 |     border-color: #6666ff
144 | }
145 | 
146 | #legend .over50Mbit {
147 |     border-color: green
148 | }
149 | 
150 | #legend .over10Mbit {
151 |     border-color: yellow
152 | }
153 | 
154 | #legend .over5Mbit {
155 |     border-color: #ff9900
156 | }
157 | 
158 | #legend .under5Mbit {
159 |     border-color: red
160 | }
161 | 
162 | .njg-node {
163 |     fill: grey
164 | }
165 | 
166 | .njg-node.up {
167 |     fill: green !important
168 | }
169 | 
170 | .njg-node.up-mload {
171 |     fill: orange !important
172 | }
173 | 
174 | .njg-node.up-hload {
175 |     fill: red !important
176 | }
177 | 
178 | .njg-node.up-gateway {
179 |     stroke-opacity: 0.8;
180 |     stroke: #9932CC;
181 |     fill: green !important;
182 | }
183 | 
184 | .njg-node.up-mload-gateway {
185 |     stroke-opacity: 0.8;
186 |     stroke: #9932CC;
187 |     fill: orange !important;
188 | }
189 | 
190 | .njg-node.up-hload-gateway {
191 |     stroke-opacity: 0.8;
192 |     stroke: #9932CC;
193 |     fill: red !important;
194 | }
195 | 
196 | .over1Gbit {
197 |     stroke: #9900ff
198 | }
199 | 
200 | .over100Mbit {
201 |     stroke: #6666ff
202 | }
203 | 
204 | .over50Mbit {
205 |     stroke: green
206 | }
207 | 
208 | .over10Mbit {
209 |     stroke: yellow
210 | }
211 | 
212 | .over5Mbit {
213 |     stroke: #ff9900
214 | }
215 | 
216 | .under5Mbit {
217 |     stroke: red
218 | }
219 | 


--------------------------------------------------------------------------------
/bachelor_thesis/bachelor.bib:
--------------------------------------------------------------------------------
  1 | @article{neumann2016secure,
  2 |   title={Secure and Decentralized Distance-Vector Routing with BMX7},
  3 |   author={Neumann, Axel},
  4 |   year={2016}
  5 | }
  6 | 
  7 | @inproceedings{neumann2016securely,
  8 |   title={Securely-entrusted multi-topology routing for community networks},
  9 |   author={Neumann, Axel and L{\'o}pez, Ester and Cerd{\`a}-Alabern, Lloren{\c{c}} and Navarro, Leandro},
 10 |   booktitle={Wireless On-demand Network Systems and Services (WONS), 2016 12th Annual Conference on},
 11 |   pages={1--8},
 12 |   year={2016},
 13 |   organization={IEEE}
 14 | }
 15 | 
 16 | @article{neumann2017cooperation,
 17 |   title={Cooperation in open, decentralized, and heterogeneous computer networks},
 18 |   author={Neumann, Axel},
 19 |   year={2017},
 20 |   publisher={Universitat Polit{\`e}cnica de Catalunya}
 21 | }
 22 | 
 23 | @techreport{perkins2011mobility,
 24 |   title={Mobility support in IPv6},
 25 |   author={Perkins, Charles and Johnson, David and Arkko, Jari},
 26 |   year={2011}
 27 | }
 28 | 
 29 | @article{hiertz2010ieee,
 30 |   title={IEEE 802.11 s: the WLAN mesh standard},
 31 |   author={Hiertz, Guido R and Denteneer, Dee and Max, Sebastian and Taori, Rakesh and Cardona, Javier and Berlemann, Lars and Walke, Bernhard},
 32 |   journal={IEEE Wireless Communications},
 33 |   volume={17},
 34 |   number={1},
 35 |   year={2010},
 36 |   publisher={IEEE}
 37 | }
 38 | 
 39 | @article{centelles2015enhancing,
 40 |   title={Enhancing reflection and self-determination in a real-life community mesh network},
 41 |   author={Centelles, Roger Pueyo and Oncins, Victor and Neumann, Axel},
 42 |   journal={Computer Networks},
 43 |   volume={93},
 44 |   pages={297--307},
 45 |   year={2015},
 46 |   publisher={Elsevier}
 47 | }
 48 | 
 49 | @inproceedings{cerda2013experimental,
 50 |   title={Experimental evaluation of a wireless community mesh network},
 51 |   author={Cerd{\`a}-Alabern, Lloren{\c{c}} and Neumann, Axel and Escrich, Pau},
 52 |   booktitle={Proceedings of the 16th ACM international conference on Modeling, analysis \& simulation of wireless and mobile systems},
 53 |   pages={23--30},
 54 |   year={2013},
 55 |   organization={ACM}
 56 | }
 57 | 
 58 | @article{klyne2002rfc,
 59 |   title={Rfc 3339: Date and time on the internet: Timestamps},
 60 |   author={Klyne, G and Newman, C},
 61 |   journal={The Internet Society, Request for Comments Jul},
 62 |   year={2002}
 63 | }
 64 | 
 65 | @article{escrich2012quick,
 66 |   title={Quick deployment network using MANET},
 67 |   author={Escrich Garcia, Pau},
 68 |   year={2012},
 69 |   publisher={Universitat Polit{\`e}cnica de Catalunya}
 70 | }
 71 | 
 72 | @article{jacquet2003optimized,
 73 |   title={Optimized link state routing protocol (olsr)},
 74 |   author={Jacquet, Philippe},
 75 |   year={2003}
 76 | }
 77 | 
 78 | @article{chroboczek2011babel,
 79 |   title={The babel routing protocol},
 80 |   author={Chroboczek, Juliusz},
 81 |   year={2011}
 82 | }
 83 | 
 84 | @article{baig2012evaluation,
 85 |   title={Evaluation of dynamic routing protocols on realistic wireless topologies},
 86 |   author={Baig, Roger},
 87 |   journal={Universitat Aut{\`o}noma de Barcelona},
 88 |   year={2012}
 89 | }
 90 | 
 91 | @inproceedings{donenfeld2017wireguard,
 92 |   title={Wireguard: Next generation kernel network tunnel},
 93 |   author={Donenfeld, Jason A},
 94 |   booktitle={Proceedings of the 2017 Network and Distributed System Security Symposium, NDSS},
 95 |   volume={17},
 96 |   year={2017}
 97 | }
 98 | 
 99 | @article{harkins2017rfc,
100 |   title={RFC 8110-Opportunistic Wireless Encryption},
101 |   author={Harkins, Dan and Kumari, Warren},
102 |   year={2017}
103 | }
104 | 
105 | @article{tan2013security,
106 |   title={A security analysis of the 802.11 s wireless mesh network routing protocol and its secure routing protocols},
107 |   author={Tan, Whye Kit and Lee, Sang-Gon and Lam, Jun Huy and Yoo, Seong-Moo},
108 |   journal={Sensors},
109 |   volume={13},
110 |   number={9},
111 |   pages={11553--11585},
112 |   year={2013},
113 |   publisher={Multidisciplinary Digital Publishing Institute}
114 | }
115 | 
116 | @inproceedings{vega2012topology,
117 |   title={Topology patterns of a community network: Guifi. net},
118 |   author={Vega, Davide and Cerda-Alabern, Llorenc and Navarro, Leandro and Meseguer, Roc},
119 |   booktitle={Wireless and Mobile Computing, Networking and Communications (WiMob), 2012 IEEE 8th International Conference on},
120 |   pages={612--619},
121 |   year={2012},
122 |   organization={IEEE}
123 | }
124 | 
125 | @article{kos2015nodewatcher,
126 |   title={nodewatcher: A substrate for growing your own community network},
127 |   author={Kos, Jernej and Milutinovi{\'c}, Mitar and {\v{C}}ehovin, Luka},
128 |   journal={Computer Networks},
129 |   volume={93},
130 |   pages={279--296},
131 |   year={2015},
132 |   publisher={Elsevier}
133 | }
134 | 
135 | @article{hinden2006ip,
136 |   title={IP version 6 addressing architecture},
137 |   author={Hinden, Robert M and Deering, Stephen E},
138 |   year={2006}
139 | }
140 | @techreport{rfc42912006version,
141 |   title={Version 6 Addressing Architecture},
142 |   author={RFC4291, IP},
143 |   year={2006},
144 |   institution={Standards Track, IETF Network Working Group}
145 | }
146 | 
147 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # meshrc 
  2 | 
  3 | Tool set to simplify monitoring and managing of a mesh network. All software
  4 | was created within my bachelor thesis. Feel free to comment & grumble.
  5 | 
  6 | Scope during development was the distribution of internet uplink for festivals
  7 | or events. However parts could be useful for community networks as well.
  8 | 
  9 | The development will not stop at this point, I'll continue to expand the tools
 10 | functionality and hopefully make it more generic.
 11 | 
 12 | ## meshrc-web
 13 | 
 14 | Uses the
 15 | [prometheus-node-exporter-lua](https://github.com/openwrt/packages/tree/master/utils/prometheus-node-exporter-lua)
 16 | with BMX7 plugin to generate valid [NetJson](http://netjson.org/) which can be
 17 | visualized via [netjsongraph.js](https://github.com/netjson/netjsongraph.js)
 18 | 
 19 | ![graph](img/graph.png)
 20 | 
 21 | Also creates an simple overview & allow configuration of the mesh via `meshrc-client`.
 22 | 
 23 | ![config](img/config.png)
 24 | ![overview](img/overview.png)
 25 | 
 26 | ## meshrc-cli
 27 | 
 28 | Has various command to set the mesh configuration:
 29 | 
 30 | ```
 31 | Usage: ./cli.sh
 32 |     -h --help                           : show this message
 33 |     -i --shortid <shortid>              : short id of node to be configured
 34 |     -l --list-nodes                     : show all nodes of mesh network
 35 |     -n --node-name <name>               : sets node name for given shortId
 36 |     -a --ap-pass <passworkd>            : set access point password of all nodes
 37 |     -m --mesh-pass <passworkd>          : set mesh password of all nodes
 38 |     -f --firstboot                      : resets all nodes by removing overlayfs
 39 |     -r --raw                            : runs given command directly on node
 40 |     -s --set-ssh <ssh_keys>             : set ssh key to all nodes
 41 | Examples:
 42 |     ./cli.sh -i ABCD1234 -a "individual-ap-password"
 43 |     ./cli.sh -i ABCD1234 -r "reboot"
 44 |     ./cli.sh -m "new-mesh-password"
 45 | ```
 46 | 
 47 | The command transport is done via `bmx7-sms` and requires clients that trust the
 48 | sending node.
 49 | 
 50 | ## meshrc-client
 51 | 
 52 | Runs a daemon which waits for received commands and runs them if the sender is
 53 | trusted.
 54 | 
 55 | ## meshrc-initial
 56 | 
 57 | Daemon that tries to download an initial configuration from all directly
 58 | connected devices via `link-local`. If an archive is successfully received it
 59 | will unpack it to the device root `/` and reboots.
 60 | 
 61 | This is especially useful with `uci-defaults` and is used by [meshrc-web] which
 62 | automatically generates an archive containing all settings from the
 63 | configuration view. On change, a new archive is packed and locally delivered.
 64 | Unconfigured nodes can be connected to the device running [meshrc-web] and
 65 | automatically receive passwords to connect to the encrypted mesh.
 66 | 
 67 | # Installation
 68 | 
 69 | As `meshrc` is (currently) highly dependent on LibreMesh, the following steps
 70 | require you to have a current version of LibreMesh running, mainly tested with
 71 | the development branch.
 72 | 
 73 | To install the *meshrc* the repository containing the compiled packages should
 74 | be added to the router. This should be done based on the devices architecture.
 75 | However, as all packages only containing scripts which do not require any
 76 | compilation and have `PKGARCH:=all` in the Makefile, every repository works for
 77 | every device.
 78 | 
 79 | The `x86/64` can therefore be added to the `/etc/opkg/limefeeds.conf` file:
 80 | 
 81 |     echo "https://snapshots.libremesh.org/packages/x86_64/meshrc/" >> /etc/opkg/limefeeds.conf
 82 | 
 83 | As the snapshot key signed the *meshrc* packages as well the installation is
 84 | directly possible via:
 85 | 
 86 |     opkg update
 87 |     # on the server
 88 |     opkg install meshrc-web meshrc-cli 
 89 | 
 90 |     # on clients 
 91 |     opkg install meshrc-initial meshrc-client
 92 | 
 93 | Once installed the server offers a special interface independent of the regular
 94 | *Luci* interface at `http://<router_ip>/meshrc`. The required password is the
 95 | `root` password.
 96 | 
 97 | After an successful login in everything likely stays empty, as no client nodes
 98 | are connected yet. Click the *Config* tab to activate the initial config
 99 | distribution and change settings according to your needs.
100 | 
101 | Now the client nodes can be directly connected via a cable to the servers LAN
102 | interface. After a few seconds the LEDs of the client node should start
103 | blinking, indicating a reboot after successfully downloading the servers
104 | configuration. It is possible to have multiple clients connected at the same
105 | time, for instance via a switch.
106 | 
107 | The client nodes reboot and activate the wireless mesh and open access points,
108 | based on a hash of their mac address. At this point the nodes should appear in
109 | the graph and overview. Clicking on the hostnames opens an individual
110 | configuration to set the nodes hostname, resulting also in a change of the
111 | wireless access point name. Some characters are not available as hostnames and
112 | therefore not useable as AP name.
113 | 
114 | Changed done via the *Config* view are automatically distributed to existing
115 | (and active) nodes but also update the initial config file, meaning newly setup
116 | nodes always start with the latest configuration.
117 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/client/usr/bin/meshrc-client:
--------------------------------------------------------------------------------
  1 | #!/bin/sh
  2 | 
  3 | # import OpenWrt script to handle json
  4 | . /usr/share/libubox/jshn.sh
  5 | 
  6 | # loads trusted bmx7 ids from lime(-defaults)
  7 | trusted_ids=$(uci -q get lime-defaults.meshrc.trusted)
  8 | [[ -z "$trusted_ids" ]]  && {
  9 |     trusted_ids=$(uci -q get lime.meshrc.trusted)
 10 |     [[ -z "$trusted_ids" ]] && {
 11 |         uci -q set lime.meshrc="lime"
 12 |         uci -q add_list lime.meshrc.trusted=""
 13 |         echo "please add section trusted_nodes in /etc/config/lime"
 14 |         exit 1
 15 |     }
 16 | }
 17 | 
 18 | # parses the own shortid and stores it in uci format
 19 | bmx7_shortid="$(uci -q get lime.system.bmx7_shortid)"
 20 | bmx7_nodeid="$(uci -q get lime.system.bmx7_nodeid)"
 21 | [[ -z "$bmx7_shortid" || -z "$bmx7_nodeid" ]] && {
 22 |     json_load "$(cat /var/run/bmx7/json/status)"
 23 |     json_select status
 24 |     json_get_var bmx7_shortid shortId
 25 |     json_get_var bmx7_nodeid nodeId
 26 |     uci -q set lime.system.bmx7_shortid="$bmx7_shortid"
 27 |     uci -q set lime.system.bmx7_nodeid="$bmx7_nodeid"
 28 |     uci commit lime
 29 | }
 30 | 
 31 | # return all node ids currently active in the network
 32 | active_node_ids() {
 33 |     echo "$(ls -1 /var/run/bmx7/json/originators/)"
 34 | }
 35 | 
 36 | # return all node ids which acked the comment $1
 37 | acked_command() {
 38 |     # own ack isn't in rcvdSms folder
 39 |     echo "$bmx7_nodeid"
 40 |     # trusted nodes may don't run the client and so no acks
 41 |     echo "$trusted_ids"
 42 |     # all acks from other nodes running the client
 43 |     echo "$(ls /var/run/bmx7/sms/rcvdSms/*:${1}-ack | cut -d '/' -f 7 | \
 44 |             cut -d ':' -f 1)"
 45 | }
 46 | 
 47 | # sync cmd $1-ack to the cloud and wait until all other nodes acked it
 48 | wait_cloud_synced() {
 49 |     ack_file="/var/run/bmx7/sms/sendSms/${1}-ack"
 50 |     # create & share acked file
 51 |     [[ -e "$ack_file" ]] || {
 52 |         touch "$ack_file"
 53 |         /usr/sbin/bmx7 -c syncSms="${1}-ack"
 54 |     }
 55 | 
 56 |     # check if cloud is synced for the specified task
 57 |     if [[ "$(active_node_ids | sort)" != "$(acked_command $1 | sort)" ]]; then
 58 |         # stop distribution of the ack
 59 |         rm "/var/run/bmx7/sms/sendSms/${1}-ack"
 60 |         # wait before executing the command to give bmx a bit more time to
 61 |         # distribute received acks to neighboured nodes
 62 |         sleep 5
 63 |         echo 1
 64 |     else
 65 |         sleep 5
 66 |         echo 0
 67 |     fi
 68 | }
 69 | 
 70 | run_lime() {
 71 |     echo "run lime $1"
 72 |     uci -q set lime."${1}"
 73 | 
 74 |     # only apply changes if something was changed
 75 |     [[ "$(uci -q changes)" != "" ]] && {
 76 |         uci commit lime
 77 |         lime-config
 78 |         lime-apply
 79 |     }
 80 | }
 81 | 
 82 | while true; do
 83 |     for trusted_id in $trusted_ids; do
 84 |         [[ -z "$trusted_id" ]] && return
 85 |         echo "$trusted_id"
 86 |         for config_path in $(ls /var/run/bmx7/sms/rcvdSms/${trusted_id}*); do
 87 |             config_file="$(basename $config_path | cut -d ':' -f 2)"
 88 |             echo "received config of trusted node ${config_file}"
 89 |             echo "$config_file"
 90 |             case $config_file in
 91 |                 lm-*_${bmx7_shortid})
 92 |                     echo "run lime node spcific command $config_file"
 93 |                     run_lime "$(cat $config_path)"
 94 |                     continue
 95 |                     ;;
 96 |                 lm-*_*) 
 97 |                     # ignore commands from other nodes
 98 |                     continue
 99 |                     ;;
100 |                 lm-*)
101 |                     # if not yet synced skip command for now
102 |                     [[ "$(wait_cloud_synced $config_file)" == 1 ]] || \
103 |                         continue
104 | 
105 |                     run_lime "$(cat $config_path)"
106 |                     ;;
107 |                 rc-ssh)
108 |                     echo "run ssh key change"
109 |                     # handle ssh changes as it's not an UCI setting
110 |                     ssh_new="$(md5sum $config_path | cut -d ' ' -f 1)"
111 |                     ssh_local="$(md5sum /etc/dropbear/authorized_keys | cut -d ' ' -f 1)"
112 | 
113 |                     # only apply new ssh keys if they changed
114 |                     [[ "$ssh_new" != "$ssh_local" ]] && {
115 |                         echo "copy new keys"
116 |                         cp "$config_path" /etc/dropbear/authorized_keys
117 |                     }
118 |                     ;;
119 |                 rc-*_${bmx7_shortid})
120 |                     echo "run generic node command $config_file"
121 |                     $(cat "$config_path")
122 |                     continue
123 |                     ;;
124 |                 rc-*_*)
125 |                     # ignore commands from other nodes
126 |                     continue
127 |                     ;;
128 |                 rc-*)
129 |                     echo "run generic command $config_file"
130 | 
131 |                     # if not yet synced return
132 |                     [[ "$(wait_cloud_synced $config_file)" == 1 ]] || \
133 |                         continue
134 | 
135 |                     # raw content execution
136 |                     $(cat "$config_path")
137 |                     ;;
138 |             esac
139 |         done
140 |     done
141 | 
142 |     # wait for newly received sms
143 |     inotifywait -q -e delete -e create -e modify /var/run/bmx7/sms/rcvdSms || sleep 10
144 | done
145 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 | 
  4 | <head>
  5 |     <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  6 |     <meta charset="utf-8">
  7 |     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  8 |     <meta name="description" content="">
  9 |     <meta name="author" content="">
 10 |     <title>Mesh Controller</title>
 11 |     <link href="static/css/bootstrap.min.css" rel="stylesheet">
 12 |     <link href="static/css/netjsongraph-theme.css" rel="stylesheet">
 13 |     <link href="static/css/netjsongraph.css" rel="stylesheet">
 14 | </head>
 15 | 
 16 | <body onhashchange="navi()">
 17 |     <nav class="navbar fixed-top navbar-expand-md navbar-dark bg-dark mb-4">
 18 |         <a class="navbar-brand" href="#">Mesh Controller</a>
 19 |         <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
 20 |         <span class="navbar-toggler-icon"></span>
 21 |       </button>
 22 |         <div class="collapse navbar-collapse" id="navbarCollapse">
 23 |             <ul class="navbar-nav mr-auto">
 24 |                 <li class="nav-item">
 25 |                     <a class="nav-link" href="#graph">Network Graph</a>
 26 |                 </li>
 27 |                 <li class="nav-item">
 28 |                     <a class="nav-link" href="#overview">Device overview</a>
 29 |                 </li>
 30 |                 <li class="nav-item">
 31 |                     <a class="nav-link" href="#config">Configuration</a>
 32 |                 </li>
 33 |             </ul>
 34 |             <form class="form-inline">
 35 |                 <select class="custom-select" id="time_relative" onchange="reload_netjson(this.value)">
 36 |                 <option value="">Now</option>
 37 |                 <option value="2m">2 minutes ago</option>
 38 |                 <option value="15m">15 minutes ago</option>
 39 |                 <option value="1h">1 hour ago</option>
 40 |                 <option value="12h">12 hour ago</option>
 41 |                 <option value="24h">24 hour ago</option>
 42 |             </select>
 43 |             </form>
 44 |         </div>
 45 |     </nav>
 46 |     <main role="main" class="container-fluid fill" id="content">
 47 |         <div id="login">
 48 |             <form class="form-signin" onsubmit="event.preventDefault();" id="form_login">
 49 |                 <h1 class="h3 mb-3 font-weight-normal">Please sign in</h1>
 50 |                 <label for="inputPassword" class="sr-only">Password</label>
 51 |                 <input id="login_password" class="form-control" placeholder="Password" required="" type="password">
 52 |                 <br><button class="btn btn-primary" onclick="ubus_login()" role="button">Sign in</button>
 53 |             </form>
 54 |         </div>
 55 |         <div id="graph" style="display: none">
 56 |             <div id="legend">
 57 |                 <p><span class="circle up">&nbsp;</span> Node up</p>
 58 |                 <p><span class="circle up-mload">&nbsp;</span> Medium load</p>
 59 |                 <p><span class="circle up-hload">&nbsp;</span> High load</p>
 60 |                 <p><span class="circle up-gateway">&nbsp;</span> Node gateway</p>
 61 |                 <p><span class="circle node">&nbsp;</span> Node down/unknown</p>
 62 |                 <p><span class="link over1Gbit">&nbsp;</span> Over 1Gbit</p>
 63 |                 <p><span class="link over100Mbit">&nbsp;</span> Over 100Mbit</p>
 64 |                 <p><span class="link over50Mbit">&nbsp;</span> Over 50Mbit</p>
 65 |                 <p><span class="link over10Mbit">&nbsp;</span> Over 10Mbit</p>
 66 |                 <p><span class="link over5Mbit">&nbsp;</span> Over 5Mbit</p>
 67 |                 <p><span class="link under5Mbit">&nbsp;</span> Under 5Mbit</p>
 68 |             </div>
 69 |         </div>
 70 |         <div id="node" style="display: none">
 71 |             <form action="#" onsubmit="event.preventDefault();" method="post" id="form_node">
 72 |                 <div class="form-group row">
 73 |                     <label for="hostname" class="col-sm-4 col-form-label">Host & Access Point Name</label>
 74 |                     <div class="col-sm-4">
 75 |                         <input class="form-control" id="hostname" placeholder="Hostname" type="text">
 76 |                     </div>
 77 |                     <div class="col-sm-4">
 78 |                         <button class="btn btn-primary" name="apply" onclick="apply_config('#form_node')">Apply</button>
 79 |                     </div>
 80 |                 </div>
 81 |             </form>
 82 |         </div>
 83 |         <div id="config" style="display: none">
 84 |             <form action="#" onsubmit="event.preventDefault();" method="post" id="form_config">
 85 |                 <div class="form-group row">
 86 |                     <label for="ap_key" class="col-sm-2 col-form-label">Access Point Password</label>
 87 |                     <div class="col-sm-4">
 88 |                         <input class="form-control" id="ap_key" placeholder="Password" type="password">
 89 |                     </div>
 90 |                     <div class="col-sm-2"></div>
 91 |                     <div class="col-sm-4">
 92 |                         <div class="form-check">
 93 |                             <input class="form-check-input" type="checkbox" id="initial">
 94 |                             <label class="form-check-label" for="initial">Initial Configuration distribution</label>
 95 |                         </div>
 96 |                     </div>
 97 |                 </div>
 98 |                 <div class="form-group row">
 99 |                     <label for="mesh_id" class="col-sm-2 col-form-label">Mesh ID</label>
100 |                     <div class="col-sm-4">
101 |                         <input class="form-control" id="mesh_id" placeholder="" type="text">
102 |                     </div>
103 |                     <label for="mesh_key" class="col-sm-2 col-form-label">Mesh Password</label>
104 |                     <div class="col-sm-4">
105 |                         <input class="form-control" id="mesh_key" placeholder="Password" type="password">
106 |                     </div>
107 |                 </div>
108 |                 <div class="form-group row">
109 |                     <label for="ssh_keys" class="col-sm-2 col-form-label">SSH Keys</label>
110 |                     <div class="col-sm-10">
111 |                         <textarea style="white-space: pre; overflow: auto;" class="form-control" id="ssh_keys" rows="6"></textarea>
112 |                     </div>
113 |                 </div>
114 |                 <div class="form-group row">
115 |                     <div class="col-sm-10">
116 |                         <button class="btn btn-primary" name="apply" onclick="apply_config('#form_config')">Apply</button>
117 |                         <button class="btn btn-danger" name="reset" onclick="firstboot()">Reset network</button>
118 |                     </div>
119 |                 </div>
120 |             </form>
121 |         </div>
122 |         <div id="overview" style="display: none;">
123 |             <table class="table" id="table_overview"></table>
124 |         </div>
125 |         <div id="debug" style="display: none;"></div>
126 |         <script>
127 |             var timestamp = "0h"
128 |         </script>
129 |         <script src="static/js/d3.min.js"></script>
130 |         <script src="static/js/netjsongraph.js"></script>
131 |         <script src="static/js/fmt.js"></script>
132 |         <script src="static/js/settings.js"></script>
133 |         <script src="static/js/graph.js"></script>
134 |         <script src="static/js/overview.js"></script>
135 |         <script src="static/js/config.js"></script>
136 |     </main>
137 | </body>
138 | 
139 | </html>
140 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/config.js:
--------------------------------------------------------------------------------
  1 | // convinience functions
  2 | function $(s) {
  3 |     return document.getElementById(s.substring(1));
  4 | }
  5 | 
  6 | function show(s) {
  7 |     console.log("show " + s)
  8 |     $(s).style.display = 'block';
  9 | }
 10 | 
 11 | function hide(s) {
 12 |     console.log("hide " + s)
 13 |     $(s).style.display = 'none';
 14 | }
 15 | 
 16 | // set parameter in url
 17 | // from https://stackoverflow.com/a/487049/8309585
 18 | function set_url_param(key, value) {
 19 |     key = encodeURI(key);
 20 |     value = encodeURI(value);
 21 | 
 22 |     var kvp = document.location.search.substr(1).split('&');
 23 | 
 24 |     var i = kvp.length;
 25 |     var x;
 26 |     while (i--) {
 27 |         x = kvp[i].split('=');
 28 | 
 29 |         if (x[0] == key) {
 30 |             x[1] = value;
 31 |             kvp[i] = x.join('=');
 32 |             break;
 33 |         }
 34 |     }
 35 | 
 36 |     if (i < 0) {
 37 |         kvp[kvp.length] = [key, value].join('=');
 38 |     }
 39 | 
 40 |     //this will reload the page, it's likely better to store this until finished
 41 |     document.location.search = kvp.join('&');
 42 | }
 43 | 
 44 | // get parameter from url
 45 | // from https://stackoverflow.com/a/5448595/8309585
 46 | function get_url_param(parameterName) {
 47 |     var result = "",
 48 |         tmp = [];
 49 |     location.search.substr(1).split("&").forEach(function(item) {
 50 |         tmp = item.split("=");
 51 |         if (tmp[0] === parameterName) {
 52 |             result = decodeURIComponent(tmp[1]);
 53 |         }
 54 |     });
 55 |     return result;
 56 | }
 57 | 
 58 | // interacts with the OpenWrt ubus daemon
 59 | function ubus_call(command, argument, params, callback) {
 60 |     console.log(command + " " + argument + " " + params + " " + callback)
 61 |     var request_data = {};
 62 |     request_data.jsonrpc = "2.0";
 63 |     request_data.id = ubus_counter;
 64 |     request_data.method = "call";
 65 |     request_data.params = [ubus_rpc_session, command, argument, params]
 66 |     console.log(JSON.stringify(request_data))
 67 |     fetch(ubus_url, {
 68 |             method: "POST",
 69 |             body: JSON.stringify(request_data)
 70 |         })
 71 |         .then(function(res) {
 72 |             return res.json();
 73 |         })
 74 |         .then(function(data) {
 75 |             if (typeof data["error"] == "undefined") {
 76 |                 if (typeof callback != "undefined") {
 77 |                     callback(data);
 78 |                 }
 79 |             } else {
 80 |                 authed = 0;
 81 |                 navi()
 82 |             }
 83 |         })
 84 |     ubus_counter++;
 85 | }
 86 | 
 87 | // function takes form data and performs ubus calls to trigger the local 
 88 | // `meshrc-cli` which then changes settings and distributes them to other nodes
 89 | function apply_config(form) {
 90 |     console.log("apply config")
 91 |     var fe = $(form).elements
 92 |     for (var i = 0; i < fe.length; i++) {
 93 |         if (fe[i].type == "checkbox") {
 94 |             var value = fe[i].checked
 95 |         } else {
 96 |             var value = fe[i].value
 97 |         }
 98 |         if (fe[i].value != "" && fe[i].name != "apply" && fe[i].name != "reset") {
 99 |             ubus_call("meshrc", fe[i].id, {
100 |                 "param": value,
101 |                 "node_id": node_id
102 |             }, debug_callback)
103 |         }
104 |     }
105 |     set_url_param("node-id", "")
106 | }
107 | 
108 | // verify that the user really wants to reset the network
109 | function firstboot() {
110 |     console.log("reset network")
111 |     var txt;
112 |     var confirmation = confirm("Reset?");
113 |     if (confirmation) {
114 |         ubus_call("meshrc", "firstboot", {
115 |             "node_id": node_id
116 |         }, debug_callback)
117 |     }
118 | }
119 | 
120 | // function to handle ubus login sequence
121 | function ubus_login_callback(data) {
122 |     console.log("callback")
123 |     if (data.result == 6) {
124 |         alert("Wrong password!")
125 |     } else {
126 |         authed = true
127 |         ubus_rpc_session = data.result[1].ubus_rpc_session
128 |         set_url_param("ubus-session", ubus_rpc_session)
129 |     }
130 | }
131 | 
132 | // special function to perform ubus login sequence
133 | function ubus_login() {
134 |     ubus_rpc_session = "00000000000000000000000000000000"
135 |     ubus_call("session", "login", {
136 |         "username": "root",
137 |         "password": $("#login_password").value
138 |     }, ubus_login_callback)
139 | }
140 | 
141 | // loads hostname of node to show individual config view
142 | function reload_node() {
143 |     console.log("reload config")
144 |     ubus_call("meshrc", "get_hostname", {
145 |         "node_id": node_id
146 |     }, reload_node_callback)
147 | }
148 | 
149 | function reload_node_callback(data) {
150 |     var fe = $("#form_node").elements
151 |     for (var i = 0; i < fe.length; i++) {
152 |         fe[i].value = data.result[1][fe[i].id]
153 |     }
154 | }
155 | 
156 | // loads local device settings to show in general config view
157 | function reload_config() {
158 |     console.log("reload config")
159 |     ubus_call("meshrc", "get_config", {}, reload_config_callback)
160 | }
161 | 
162 | function reload_config_callback(data) {
163 |     console.log(data.result[1])
164 |     var fe = $("#form_config").elements
165 |     for (var i = 0; i < fe.length; i++) {
166 |         var value = data.result[1][fe[i].id]
167 |         if (fe[i].type == "checkbox") {
168 |             if (value == "true" || value == "1") {
169 |                 fe[i].checked = true
170 |             } else {
171 |                 fe[i].checked = false
172 |             }
173 |         } else {
174 |             fe[i].value = value
175 |         }
176 |     }
177 | }
178 | 
179 | // load netjson from ubus and reload graph or table
180 | function reload_netjson(timestamp_new) {
181 |     ubus_call("meshrc", "netjson", {
182 |         "param": timestamp_new
183 |     }, reload_netjson_callback)
184 |     set_url_param("timestamp", timestamp_new)
185 | }
186 | 
187 | function reload_netjson_callback(data) {
188 |     netjson_data = data.result[1]
189 |     func = "reload_" + window.location.hash.substring(1)
190 |     console.log("reload_func " + func)
191 |     window[func]()
192 | }
193 | 
194 | // used to show plain Netjson, only for debugging
195 | function reload_debug() {
196 |     $("#debug").innerHTML = "<pre>" + JSON.stringify(netjson_data, null, 4) + "</pre>"
197 | }
198 | 
199 | function debug_callback(data) {
200 |     console.log(data.result[1])
201 | }
202 | 
203 | // trivial navigation function, hide all elements, check if successfull login
204 | function navi() {
205 |     hide("#debug")
206 |     hide("#config")
207 |     hide("#node")
208 |     hide("#overview")
209 |     hide("#graph")
210 |     if (authed) {
211 |         var hash = window.location.hash;
212 |         if (hash.startsWith("#node")) {
213 |             show("#node")
214 |             node_id = hash.substring(5)
215 |             reload_node()
216 |         } else {
217 |             node_id = ""
218 |             if (hash == "" || hash == "#") {
219 |                 window.location.hash = "graph"
220 |             } else {
221 |                 show(hash)
222 |                 reload_netjson(timestamp)
223 |             }
224 |         }
225 |     } else {
226 |         show("#login")
227 |     }
228 | }
229 | 
230 | // used to stay logged in between reload
231 | ubus_rpc_session = get_url_param("ubus-session")
232 | // timestap is used to show network states of the past
233 | timestamp = get_url_param("timestamp") || ""
234 | $("#time_relative").value = timestamp
235 | authed = false
236 | 
237 | // bootstrap function called on page load
238 | if (!ubus_rpc_session) {
239 |     show("#login")
240 | } else {
241 |     hide("#login")
242 |     authed = true
243 |     navi()
244 | }
245 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/cli/usr/bin/meshrc-cli:
--------------------------------------------------------------------------------
  1 | #!/bin/sh
  2 | 
  3 | # include OpenWrt script to handle json
  4 | . /usr/share/libubox/jshn.sh
  5 | 
  6 | # config file name
  7 | CONFIG="config.tar.gz"
  8 | # where to store the config file
  9 | CONFIG_DIR="/var/lib/config/"
 10 | 
 11 | # add a file to be distributed by bmx
 12 | bmx7_add_sms_entry() {
 13 |     echo "add bmx7 entry $1"
 14 |     bmx7 -c syncSms="${1}"
 15 | }
 16 | 
 17 | # remove a file from distribution
 18 | bmx7_del_sms_entry() {
 19 |     uci delete bmx7.${1}
 20 | }
 21 | 
 22 | # copy file to bmx send folder and starts distributing it
 23 | bmx7_add_sms_file() {
 24 |     filename = "basename($1)"
 25 |     bmx7_add_sms_entry "${filename}"
 26 |     ln -s "$1" "/var/run/bmx7/sms/sendSms/${filename}"
 27 | }
 28 | 
 29 | # removes file from send folder
 30 | bmx7_del_sms_file() {
 31 |     filename = "basename($1)"
 32 |     rm "/var/run/bmx7/sms/sendSms/${filename}"
 33 | }
 34 | 
 35 | # update the initial config which contains current wifi id and key
 36 | # also adds locally installed ssh keys to clients
 37 | update_initial_config() {
 38 |         cat <<EOF > "${CONFIG_DIR}/etc/uci-defaults/51_wifi"
 39 | #!/bin/sh
 40 | 
 41 | # take the same wifi settings as the current node
 42 | uci set lime.wifi.ieee80211s_mesh_id="$(uci -q get lime.wifi.ieee80211s_mesh_id)"
 43 | uci set lime.wifi.ieee80211s_key="$(uci -q get lime.wifi.ieee80211s_key)"
 44 | uci set lime.wifi.ap_key="$(uci -q get lime.wifi.ap_key)"
 45 | 
 46 | EOF
 47 | 
 48 |     # add gateway ssh keys on new clients
 49 |     [ -e /etc/dropbear/authorized_keys ] && \
 50 |         cat /etc/dropbear/authorized_keys > "${CONFIG_DIR}/etc/dropbear/authorized_keys"
 51 | 
 52 |     tar c -z -C "$CONFIG_DIR" . -x "${CONFIG}" -f "${CONFIG_DIR}/${CONFIG}"
 53 |     chmod 644 "${CONFIG_DIR}/${CONFIG}"
 54 | }
 55 | 
 56 | # activate or deactivate the config distribution
 57 | initial_config_distribution() {
 58 |     # either takes 1 or "true"
 59 |     if [[ "$1" == "1" -o "$1" == "true" ]]; then 
 60 | 
 61 |         # load bmx7 id
 62 |         json_load "$(cat /var/run/bmx7/json/status)"
 63 |         json_select status
 64 |         json_get_var bmx7_nodeid nodeId
 65 | 
 66 |         # create required folders
 67 |         mkdir -p "${CONFIG_DIR}/etc/config/"
 68 |         mkdir -p "${CONFIG_DIR}/etc/uci-defaults/"
 69 |         mkdir -p "${CONFIG_DIR}/etc/dropbear/"
 70 | 
 71 |         # add initial config to activate ap/mesh and trust this node
 72 |         cat <<EOF > "${CONFIG_DIR}/etc/uci-defaults/50_initial_config"
 73 | #!/bin/sh
 74 | 
 75 | # activate the access point and mesh wifi
 76 | uci add_list lime.wifi.modes='ap'
 77 | uci add_list lime.wifi.modes='ieee80211s'
 78 | 
 79 | # all network interfaces are bridged an so br-lan is primary instead of eth0
 80 | uci set lime.network.primary_interface='br-lan'
 81 | 
 82 | # automatically trust this node
 83 | uci set lime.meshrc="lime"
 84 | uci delete lime.meshrc.trusted
 85 | uci add_list lime.meshrc.trusted='$bmx7_nodeid'
 86 | EOF
 87 | 
 88 |         # set the prometheus exporter to listen on any interface
 89 |         cat <<EOF > "${CONFIG_DIR}/etc/uci-defaults/70_prometheus-node-exporter-lua"
 90 | #!/bin/sh
 91 | 
 92 | uci set prometheus-node-exporter-lua.main.listen_address='::'
 93 | uci commit prometheus-node-exporter-lua
 94 | EOF
 95 | 
 96 |         # eventually run lime config scripts to finish setup
 97 |         cat <<EOF > "${CONFIG_DIR}/etc/uci-defaults/80_lime-apply"
 98 | #!/bin/sh
 99 | 
100 | # apply lime changes
101 | lime-smart-wifi
102 | lime-config
103 | lime-apply
104 | EOF
105 | 
106 |         # create initial config archive
107 |         mkdir -p "/www/config/"
108 |         update_initial_config
109 | 
110 |         # activate the config distribution via uhttpd
111 |         uci -q set lime.meshrc="lime"
112 |         uci -q set lime.meshrc.initial=true
113 |         uci -q set uhttpd.nodeconfig=uhttpd
114 |         uci -q set uhttpd.nodeconfig.home="$CONFIG_DIR"
115 |         uci -q set uhttpd.nodeconfig.listen_http="8123"
116 |     else
117 |         # disable the config sharing
118 |         uci -q delete uhttpd.nodeconfig
119 |         uci -q set lime.meshrc.initial=false
120 |     fi
121 | 
122 |     # apply setting and reload uhttpd
123 |     uci commit lime
124 |     uci commit uhttpd
125 |     /etc/init.d/uhttpd reload
126 | }
127 | 
128 | # takes two parameters
129 | # command name - file name, should be prefixed by either "lm" for libremesh
130 | # specific command or "rc" to run direclty in clients shell
131 | run_command() {
132 |     echo "run command $1"
133 |     if [[ "$node_id" == "" ]]; then
134 |         # run on all nodes
135 |         echo "$2" > "/var/run/bmx7/sms/sendSms/${1}"
136 |         bmx7_add_sms_entry "${1}"
137 |     else
138 |         # run only on <node_id>
139 |         echo "$2" > "/var/run/bmx7/sms/sendSms/${1}_${node_id}"
140 |         bmx7_add_sms_entry "${1}_${node_id}"
141 |     fi
142 | 
143 |     # update archive if distribution is activated
144 |     [[ "$(uci -q get lime.meshrc.initial)" == "true" ]] && \
145 |         update_initial_config
146 | }
147 | 
148 | # run libremesh config changes locally as well
149 | run_lime() {
150 |     echo "run lime $1"
151 | 
152 |     # if lime command is for all nodes, run on gateway as well
153 |     if [[ "$node_id" == "" ]]; then
154 |         uci -q set lime."${1}"
155 |         # only apply changes if something was changed
156 |         [[ "$(uci -q changes)" != "" ]] && {
157 |             uci commit lime
158 |             lime-config
159 |             lime-apply
160 |         }
161 |     fi
162 | 
163 |     run_command "$1" "$2"
164 | }
165 | 
166 | # prints usage of the cli
167 | usage() {
168 |     cat << EOF
169 | Usage: $0 
170 | 
171 |     -h --help                           : show this message
172 |     -i --shortid <shortid>              : short id of node to be configured
173 |     -l --list-nodes                     : show all nodes of mesh network
174 |     -H --hostname <name>                : sets node name for given shortId
175 |     -a --ap-key <passworkd>             : set access point password of all nodes
176 |     -m --mesh-id <new_id>               : set mesh id of all nodes
177 |     -m --mesh-key <passworkd>           : set mesh password of all nodes
178 |     -f --firstboot                      : resets all nodes by removing overlayfs
179 |     -r --raw <command>                  : runs given command directly on node
180 |     -s --set-ssh <ssh_keys>             : set ssh key to all nodes
181 | 
182 | Examples:
183 | 
184 |     $0 -i ABCD1234 -a "individual-ap-password"
185 |     $0 -i BCDE2345 -r "reboot"
186 |     $0 -m "new-mesh-password"
187 | EOF
188 | }
189 | 
190 | node_id=""
191 | 
192 | while [ "$#" ]; do
193 |     case $1 in
194 |         -h|--help)
195 |             usage
196 |             shift
197 |             ;;
198 |         -l|--list-nodes)
199 |             bmx7 -c originators | tail -n +3 | awk '{ print $1" "$2 }'
200 |             shift
201 |             ;;
202 |         -i|--shortid)
203 |             node_id="$2"
204 |             shift; shift
205 |             ;;
206 |         -H|--hostname)
207 |             run_lime "lm-hn" "system.hostname=${2}"
208 |             shift; shift
209 |             ;;
210 |         -a|--ap-key)
211 |             run_lime "lm-ak" "wifi.ap_key=${2}"
212 |             shift; shift
213 |             ;;
214 |         -d|--mesh-id)
215 |             run_lime "lm-mi" "wifi.ieee80211s_mesh_id=${2}"
216 |             shift; shift
217 |             ;;
218 |         -m|--mesh-key)
219 |             run_lime "lm-mk" "wifi.ieee80211s_key=${2}"
220 |             shift; shift
221 |             ;;
222 |         -f|--firstboot)
223 |             read -p "confirm network reset [y/N]" -n 1 -r
224 |             # verify before resetting the entire network
225 |             if [[ $REPLY == "Y" || $REPLY == "y" ]]
226 |             then
227 |                 echo "send reset command to mesh network"
228 |                 run_command "rc-rst" "firstboot -y"
229 |             else
230 |                 echo "reset canceled"
231 |             fi
232 |             shift
233 |             ;;
234 |         -r|--raw)
235 |             run_command "rc-raw" "${2}"
236 |             shift; shift
237 |             ;;
238 |         -s|--set-ssh)
239 |             run_command "rc-ssh" "${2}"
240 |             shift; shift
241 |             ;;
242 |         -I|--initial-distribution)
243 |             initial_config_distribution "${2}"
244 |             shift
245 |             ;;
246 |         --me)
247 |             # get bmx7 id of current node, usefull to manually add as trusted
248 |             # key to other nodes
249 |             json_load "$(cat /var/run/bmx7/json/status)"
250 |             json_select status
251 |             json_get_var bmx7_nodeid nodeId
252 |             echo "$bmx7_nodeid"
253 |             shift
254 |             ;;
255 |         *)
256 |             break
257 |         ;;
258 |     esac
259 | done
260 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/usr/bin/p2n:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/python3
  2 | 
  3 | import json
  4 | import urllib.request
  5 | import urllib.parse
  6 | import time
  7 | import datetime
  8 | import sys
  9 | 
 10 | # this class uses the prometheus API to create NetJson which can then be showed
 11 | # via various tool, primary focus the web interface of meshrc, however
 12 | # compatible with other NetJson tools as well
 13 | class PromNetJson():
 14 |     def __init__(self):
 15 |         # the following information is shown in the graph view
 16 |         self.LABEL = "p2n Network"
 17 |         self.VERSION = "0.1"
 18 |         self.METRIC = "rxRate"
 19 |         # address of prometheus, should run locally for performence
 20 |         self.PROMETHEUS_HOST = "http://localhost:9090"
 21 |         # metrics to load and include in the generated NetJson
 22 |         # format: <label> <prometheus query> <use label instead of value> <merge multiple values>
 23 |         self.properties_active = [
 24 |             ["traffic_mesh",
 25 |                 """sum(node_network_transmit_bytes{device=~'wlan.*mesh'}) by (shortId) + sum(node_network_receive_bytes{device=~'wlan.*mesh'}) by (shortId)"""],
 26 |             ["traffic_ap",
 27 |                 """sum(node_network_transmit_bytes{device=~'wlan.*ap'}) by (shortId) + sum(node_network_receive_bytes{device=~'wlan.*ap'}) by (shortId)"""],
 28 |             ["uptime", "node_time - node_boot_time"],
 29 |             ["load", "node_load15"], ["tunIn", "bmx7_tunIn", "network", True],
 30 |             ["memory", "100 * (node_memory_MemFree / node_memory_MemTotal)"],
 31 |             ["clients",
 32 |                 "count(wifi_station_signal{ifname=~'wlan.*-ap.*'}) by (shortId)"],
 33 |             [None, "node_openwrt_info", ["model", "release", "revision"]]
 34 |         ]
 35 | 
 36 |     # resets the NetJson
 37 |     def init_netjsongraph(self):
 38 |         self.njg= {}
 39 |         self.njg["type"]= "NetworkGraph"
 40 |         self.njg["label"]= self.LABEL
 41 |         self.njg["protocol"]= "BMX7"
 42 |         self.njg["version"]= self.VERSION
 43 |         self.njg["metric"]= self.METRIC
 44 |         # dict containing all nodes of network
 45 |         self.njg_nodes= {}
 46 |         # dict containing all links between nodes
 47 |         self.njg_links= {}
 48 | 
 49 |     # merge links found in the network
 50 |     # all links are bidirectional, meaning appear twice, once per device
 51 |     def merge_links(self, links):
 52 |         online_links = set()
 53 |         for link in links:
 54 |             # sort to save bidirectional links only once
 55 |             n1, n2 = sorted([link["source"], link["target"]])
 56 |             online_links.add(n1)
 57 | 
 58 |             # if link is found before one of the nodes where added to the nodes
 59 |             # dict, ignore the link. this can happen as Prometheus may delay
 60 |             # node scraping resulting in the node appearing offline. Missing
 61 |             # nodes however cause the NetJsonGraph.js lib to fail completly.
 62 |             if not n1 in self.njg_nodes or not n2 in self.njg_nodes:
 63 |                 continue
 64 | 
 65 |             if not n1 in self.njg_links:
 66 |                 self.njg_links[n1]= {}
 67 | 
 68 |             if not n2 in self.njg_links[n1]:
 69 |                 self.njg_links[n1][n2]= {}
 70 | 
 71 |             self.njg_links[n1][n2]["source"]= n1
 72 |             self.njg_links[n1][n2]["target"]= n2
 73 | 
 74 |             if not "properties" in self.njg_links[n1][n2]:
 75 |                 self.njg_links[n1][n2]["properties"]= {}
 76 | 
 77 | 
 78 |             if not "devs" in self.njg_links[n1][n2]["properties"]:
 79 |                 self.njg_links[n1][n2]["properties"]["devs"]= {}
 80 | 
 81 |             self.njg_links[n1][n2]["properties"]["devs"][link["dev"]]= \
 82 |                 link["rxRate"]
 83 | 
 84 |             if not "rate" in self.njg_links[n1][n2]["properties"]:
 85 |                 self.njg_links[n1][n2]["properties"]["rate"]= 0
 86 | 
 87 |             rx_rate= int(link["rxRate"])
 88 | 
 89 |             # add class to rate so the web interface can color the links based
 90 |             # on network speed
 91 |             if rx_rate > self.njg_links[n1][n2]["properties"]["rate"]:
 92 |                 self.njg_links[n1][n2]["properties"]["rate"]= rx_rate
 93 |                 if rx_rate > 9.9 * 10 ** 8:
 94 |                     best_rate= "over1Gbit"
 95 |                 elif rx_rate > 9.9 * 10 ** 7:
 96 |                     best_rate= "over100Mbit"
 97 |                 elif rx_rate > 4.9 * 10 ** 6:
 98 |                     best_rate= "over50Mbit"
 99 |                 elif rx_rate > 9.9 * 10 ** 6:
100 |                     best_rate= "over10Mbit"
101 |                 elif rx_rate > 4.9 * 10 ** 2:
102 |                     best_rate= "over5Mbit"
103 |                 else:
104 |                     best_rate= "under5Mbit"
105 |                 self.njg_links[n1][n2]["properties"]["best_rate"]= best_rate
106 | 
107 |         # remove outdated links to dead nodes
108 |         njg_links_set= set(self.njg_links.keys())
109 |         for offline_link in (njg_links_set - online_links):
110 |             del self.njg_links[offline_link]
111 | 
112 |     # requests a query from the Prometheus API
113 |     def api_call(self, query):
114 |         try:
115 |             params= urllib.parse.urlencode({"time": self.timestamp, "query":
116 |                                              query})
117 |             url= "{}/api/v1/query?{}".format(self.PROMETHEUS_HOST, params)
118 |             request= urllib.request.urlopen(url).read()
119 |             response= json.loads(request.decode("utf-8"))["data"]["result"]
120 |         except:
121 |             response= []
122 |         return response
123 | 
124 |     # add properties based on query and additional params
125 |     # special cases are metrics which contain text, like device names, in these
126 |     # cases a "label" is used rather then the value
127 |     # multi is used if a metric appear multiple times and should therefore be
128 |     # merged, for instance network interfaces
129 |     def api_call_propertie(self, propertie, query, labels=None, multi=False):
130 |         for v in self.api_call(query):
131 |             shortId= v["metric"]["shortId"]
132 |             if shortId in self.njg_nodes:
133 |                 if not propertie and labels:
134 |                     for label in labels:
135 |                         if label in v["metric"]:
136 |                             self.njg_nodes[shortId]["properties"][label] = \
137 |                                     v["metric"][label]
138 |                 else:
139 |                     if labels:
140 |                         value= v["metric"][labels]
141 |                     else:
142 |                         value= v["value"][1]
143 | 
144 |                     if not multi:
145 |                         self.njg_nodes[shortId]["properties"][propertie]= value
146 |                     else:
147 |                         if not propertie in self.njg_nodes[shortId]["properties"]:
148 |                             self.njg_nodes[shortId]["properties"][propertie]= []
149 |                         self.njg_nodes[shortId]["properties"][propertie] \
150 |                             .append(value)
151 | 
152 |     # get all nodes based on the Prometheus job called "mesh"
153 |     def get_nodes_bmx7(self):
154 |         for v in self.api_call("up{job='mesh'}"):
155 |             self.njg_nodes[v["metric"]["shortId"]]= {}
156 |             self.njg_nodes[v["metric"]["shortId"]]["id"]= \
157 |                 v["metric"]["shortId"]
158 |             if "hostname" in v["metric"]:
159 |                 self.njg_nodes[v["metric"]["shortId"]]["label"]=  v["metric"]["hostname"]
160 |             else:
161 |                 self.njg_nodes[v["metric"]["shortId"]]["label"]= v["metric"]["shortId"]
162 |             self.njg_nodes[v["metric"]["shortId"]]["properties"]= {}
163 |             if v["value"][1] == "1":
164 |                 self.njg_nodes[v["metric"]["shortId"]]["properties"]["node_state"]= "up"
165 |             else:
166 |                 self.njg_nodes[v["metric"]["shortId"]]["properties"]["node_state"]= "down"
167 | 
168 |         for propertie in self.properties_active:
169 |             self.api_call_propertie(*propertie)
170 | 
171 |         # add special tags to nodes based on status
172 |         # based on load and if the node is a gateway, the colors change
173 |         for node in self.njg_nodes.values():
174 |             if node["properties"]["node_state"] == "up":
175 |                 if "tunIn" in node["properties"]:
176 |                     if "0.0.0.0/0" in node["properties"]["tunIn"]:
177 |                         node["properties"]["node_state"]= "up-gateway"
178 |                 node_load= float(node["properties"]["load"])
179 |                 if node_load > 2:
180 |                     if node["properties"]["node_state"] == "up-gateway":
181 |                         node["properties"]["node_state"]= "up-hload-gateway"
182 |                     else:
183 |                         node["properties"]["node_state"]= "up-hload"
184 |                 elif node_load > 1:
185 |                     if node["properties"]["node_state"] == "up-gateway":
186 |                         node["properties"]["node_state"]= "up-mload-gateway"
187 |                     else:
188 |                         node["properties"]["node_state"]= "up-mload"
189 | 
190 |         return self.njg_nodes
191 | 
192 |     # get all link of Prometheus job called "mesh"
193 |     def get_links_bmx7(self):
194 |         links= []
195 |         for link in self.api_call("bmx7_link_rxRate{job='mesh'}"):
196 |             metric= link["metric"]
197 |             value= link["value"][1]
198 |             metric["rxRate"]= value
199 |             links.append(metric)
200 | 
201 |         self.merge_links(links)
202 | 
203 |     # write NetJson to a local file, usefull for debugging
204 |     def write_json(self, dest="netjson.json"):
205 |         with open(dest, "w") as netjson_dest:
206 |             netjson_dest.write(json.dumps(self.njg_out))
207 | 
208 |     # merge links and nodes to a single NetJson file
209 |     def dump_json(self):
210 |         self.njg_out= self.njg
211 | 
212 |         self.njg_out["nodes"]= []
213 |         for node in self.njg_nodes.values():
214 |             self.njg_out["nodes"].append(node)
215 | 
216 |         self.njg_out["links"]= []
217 |         for source in self.njg_links:
218 |             for target in self.njg_links[source]:
219 |                 self.njg_out["links"].append(self.njg_links[source][target])
220 | 
221 |         return json.dumps(self.njg_out)
222 | 
223 |     # meta function to parse Prometheus, called by default
224 |     # takes an additional timestap which can be a relative date like 5h or 1w
225 |     def get_bmx7(self, timestamp=None):
226 |         if timestamp and timestamp != "undefined":
227 |             value= int(timestamp[0:-1])
228 |             suffix= timestamp[-1]
229 |             seconds= 0
230 |             minutes= 0
231 |             hours= 0
232 |             days= 0
233 |             weeks= 0
234 |             if suffix == "s":
235 |                 seconds= value
236 |             elif suffix == "m":
237 |                 minutes= value
238 |             elif suffix == "h":
239 |                 hours= value
240 |             elif suffix == "d":
241 |                 days= value
242 |             elif suffix == "w":
243 |                 weeks= value
244 |             delta= datetime.datetime.now() - datetime.timedelta(
245 |                 seconds=seconds, minutes=minutes, hours=hours,
246 |                 days=days, weeks=weeks)
247 |             self.timestamp= delta.timestamp()
248 |         else:
249 |             self.timestamp= ""
250 |         self.init_netjsongraph()
251 |         self.get_nodes_bmx7()
252 |         self.get_links_bmx7()
253 |         return self.dump_json()
254 | 
255 | 
256 | # if called directly take first parameter as timestamp and scrape & return bmx7
257 | if __name__ == '__main__':
258 |     if len(sys.argv) > 1:
259 |         timestamp= sys.argv[1]
260 |     else:
261 |         timestamp= ""
262 | 
263 |     print(PromNetJson().get_bmx7(timestamp))
264 | 


--------------------------------------------------------------------------------
/bachelor_thesis/ieee.csl:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="utf-8"?>
  2 | <style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="sort-only">
  3 |   <info>
  4 |     <title>IEEE</title>
  5 |     <id>http://www.zotero.org/styles/ieee</id>
  6 |     <link href="http://www.zotero.org/styles/ieee" rel="self"/>
  7 |     <link href="http://www.ieee.org/documents/style_manual.pdf" rel="documentation"/>
  8 |     <link href="http://www.ieee.org/documents/auinfo07.pdf" rel="documentation"/>
  9 |     <author>
 10 |       <name>Michael Berkowitz</name>
 11 |       <email>mberkowi@gmu.edu</email>
 12 |     </author>
 13 |     <contributor>
 14 |       <name>Julian Onions</name>
 15 |       <email>julian.onions@gmail.com</email>
 16 |     </contributor>
 17 |     <contributor>
 18 |       <name>Rintze Zelle</name>
 19 |       <uri>http://twitter.com/rintzezelle</uri>
 20 |     </contributor>
 21 |     <contributor>
 22 |       <name>Stephen Frank</name>
 23 |       <uri>http://www.zotero.org/sfrank</uri>
 24 |     </contributor>
 25 |     <contributor>
 26 |       <name>Sebastian Karcher</name>
 27 |     </contributor>
 28 |     <category citation-format="numeric"/>
 29 |     <category field="engineering"/>
 30 |     <category field="generic-base"/>
 31 |     <updated>2016-10-06T15:32:30+00:00</updated>
 32 |     <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
 33 |   </info>
 34 |   <locale xml:lang="en">
 35 |     <terms>
 36 |       <term name="chapter" form="short">ch.</term>
 37 |       <term name="presented at">presented at the</term>
 38 |       <term name="available at">available</term>
 39 |     </terms>
 40 |   </locale>
 41 |   <!-- Macros -->
 42 |   <macro name="edition">
 43 |     <choose>
 44 |       <if type="bill book chapter graphic legal_case legislation motion_picture paper-conference report song" match="any">
 45 |         <choose>
 46 |           <if is-numeric="edition">
 47 |             <group delimiter=" ">
 48 |               <number variable="edition" form="ordinal"/>
 49 |               <text term="edition" form="short"/>
 50 |             </group>
 51 |           </if>
 52 |           <else>
 53 |             <text variable="edition" text-case="capitalize-first" suffix="."/>
 54 |           </else>
 55 |         </choose>
 56 |       </if>
 57 |     </choose>
 58 |   </macro>
 59 |   <macro name="issued">
 60 |     <choose>
 61 |       <if type="article-journal report" match="any">
 62 |         <date variable="issued">
 63 |           <date-part name="month" form="short" suffix=" "/>
 64 |           <date-part name="year" form="long"/>
 65 |         </date>
 66 |       </if>
 67 |       <else-if type="bill book chapter graphic legal_case legislation motion_picture paper-conference song thesis" match="any">
 68 |         <date variable="issued">
 69 |           <date-part name="year" form="long"/>
 70 |         </date>
 71 |       </else-if>
 72 |       <else>
 73 |         <date variable="issued">
 74 |           <date-part name="day" form="numeric-leading-zeros" suffix="-"/>
 75 |           <date-part name="month" form="short" suffix="-" strip-periods="true"/>
 76 |           <date-part name="year" form="long"/>
 77 |         </date>
 78 |       </else>
 79 |     </choose>
 80 |   </macro>
 81 |   <macro name="author">
 82 |     <names variable="author">
 83 |       <name and="text" et-al-min="7" et-al-use-first="1" initialize-with=". "/>
 84 |       <label form="short" prefix=", " text-case="capitalize-first"/>
 85 |       <et-al font-style="italic"/>
 86 |       <substitute>
 87 |         <names variable="editor"/>
 88 |         <names variable="translator"/>
 89 |       </substitute>
 90 |     </names>
 91 |   </macro>
 92 |   <macro name="editor">
 93 |     <names variable="editor">
 94 |       <name initialize-with=". " delimiter=", " and="text"/>
 95 |       <label form="short" prefix=", " text-case="capitalize-first"/>
 96 |     </names>
 97 |   </macro>
 98 |   <macro name="locators">
 99 |     <group delimiter=", ">
100 |       <text macro="edition"/>
101 |       <group delimiter=" ">
102 |         <text term="volume" form="short"/>
103 |         <number variable="volume" form="numeric"/>
104 |       </group>
105 |       <group delimiter=" ">
106 |         <number variable="number-of-volumes" form="numeric"/>
107 |         <text term="volume" form="short" plural="true"/>
108 |       </group>
109 |       <group delimiter=" ">
110 |         <text term="issue" form="short"/>
111 |         <number variable="issue" form="numeric"/>
112 |       </group>
113 |     </group>
114 |   </macro>
115 |   <macro name="title">
116 |     <choose>
117 |       <if type="bill book graphic legal_case legislation motion_picture song" match="any">
118 |         <text variable="title" font-style="italic"/>
119 |       </if>
120 |       <else>
121 |         <text variable="title" quotes="true"/>
122 |       </else>
123 |     </choose>
124 |   </macro>
125 |   <macro name="publisher">
126 |     <choose>
127 |       <if type="bill book chapter graphic legal_case legislation motion_picture paper-conference song" match="any">
128 |         <group delimiter=": ">
129 |           <text variable="publisher-place"/>
130 |           <text variable="publisher"/>
131 |         </group>
132 |       </if>
133 |       <else>
134 |         <group delimiter=", ">
135 |           <text variable="publisher"/>
136 |           <text variable="publisher-place"/>
137 |         </group>
138 |       </else>
139 |     </choose>
140 |   </macro>
141 |   <macro name="event">
142 |     <choose>
143 |       <if type="paper-conference speech" match="any">
144 |         <choose>
145 |           <!-- Published Conference Paper -->
146 |           <if variable="container-title">
147 |             <group delimiter=", ">
148 |               <group delimiter=" ">
149 |                 <text term="in"/>
150 |                 <text variable="container-title" font-style="italic"/>
151 |               </group>
152 |               <text variable="event-place"/>
153 |             </group>
154 |           </if>
155 |           <!-- Unpublished Conference Paper -->
156 |           <else>
157 |             <group delimiter=", ">
158 |               <group delimiter=" ">
159 |                 <text term="presented at"/>
160 |                 <text variable="event"/>
161 |               </group>
162 |               <text variable="event-place"/>
163 |             </group>
164 |           </else>
165 |         </choose>
166 |       </if>
167 |     </choose>
168 |   </macro>
169 |   <macro name="access">
170 |     <choose>
171 |       <if type="webpage">
172 |         <choose>
173 |           <if variable="URL">
174 |             <group delimiter=". ">
175 |               <text term="online" prefix="[" suffix="]" text-case="capitalize-first"/>
176 |               <group delimiter=": ">
177 |                 <text term="available at" text-case="capitalize-first"/>
178 |                 <text variable="URL"/>
179 |               </group>
180 |               <group prefix="[" suffix="]" delimiter=": ">
181 |                 <text term="accessed" text-case="capitalize-first"/>
182 |                 <date variable="accessed">
183 |                   <date-part name="day" form="numeric-leading-zeros" suffix="-"/>
184 |                   <date-part name="month" form="short" suffix="-" strip-periods="true"/>
185 |                   <date-part name="year" form="long"/>
186 |                 </date>
187 |               </group>
188 |             </group>
189 |           </if>
190 |         </choose>
191 |       </if>
192 |     </choose>
193 |   </macro>
194 |   <macro name="page">
195 |     <group>
196 |       <label variable="page" form="short" suffix=" "/>
197 |       <text variable="page"/>
198 |     </group>
199 |   </macro>
200 |   <macro name="citation-locator">
201 |     <group delimiter=" ">
202 |       <choose>
203 |         <if locator="page">
204 |           <label variable="locator" form="short"/>
205 |         </if>
206 |         <else>
207 |           <label variable="locator" form="short" text-case="capitalize-first"/>
208 |         </else>
209 |       </choose>
210 |       <text variable="locator"/>
211 |     </group>
212 |   </macro>
213 |   <!-- Citation -->
214 |   <citation collapse="citation-number">
215 |     <sort>
216 |       <key variable="citation-number"/>
217 |     </sort>
218 |     <layout delimiter=", ">
219 |       <group prefix="[" suffix="]" delimiter=", ">
220 |         <text variable="citation-number"/>
221 |         <text macro="citation-locator"/>
222 |       </group>
223 |     </layout>
224 |   </citation>
225 |   <!-- Bibliography -->
226 |   <bibliography entry-spacing="0" second-field-align="flush">
227 |     <layout suffix=".">
228 |       <!-- Citation Number -->
229 |       <text variable="citation-number" prefix="[" suffix="]"/>
230 |       <!-- Author(s) -->
231 |       <text macro="author" suffix=", "/>
232 |       <!-- Rest of Citation -->
233 |       <choose>
234 |         <!-- Specific Formats -->
235 |         <if type="article-journal">
236 |           <group delimiter=", ">
237 |             <text macro="title"/>
238 |             <text variable="container-title" font-style="italic" form="short"/>
239 |             <text macro="locators"/>
240 |             <text macro="page"/>
241 |             <text macro="issued"/>
242 |           </group>
243 |         </if>
244 |         <else-if type="paper-conference speech" match="any">
245 |           <group delimiter=", ">
246 |             <text macro="title"/>
247 |             <text macro="event"/>
248 |             <text macro="issued"/>
249 |             <text macro="locators"/>
250 |             <text macro="page"/>
251 |           </group>
252 |         </else-if>
253 |         <else-if type="report">
254 |           <group delimiter=", ">
255 |             <text macro="title"/>
256 |             <text macro="publisher"/>
257 |             <group delimiter=" ">
258 |               <text variable="genre"/>
259 |               <text variable="number"/>
260 |             </group>
261 |             <text macro="issued"/>
262 |           </group>
263 |         </else-if>
264 |         <else-if type="thesis">
265 |           <group delimiter=", ">
266 |             <text macro="title"/>
267 |             <text variable="genre"/>
268 |             <text macro="publisher"/>
269 |             <text macro="issued"/>
270 |           </group>
271 |         </else-if>
272 |         <else-if type="webpage post-weblog" match="any">
273 |           <group delimiter=", " suffix=". ">
274 |             <text macro="title"/>
275 |             <text variable="container-title" font-style="italic"/>
276 |             <text macro="issued"/>
277 |           </group>
278 |           <text macro="access"/>
279 |         </else-if>
280 |         <else-if type="patent">
281 |           <group delimiter=", ">
282 |             <text macro="title"/>
283 |             <text variable="number"/>
284 |             <text macro="issued"/>
285 |           </group>
286 |         </else-if>
287 |         <!-- Generic/Fallback Formats -->
288 |         <else-if type="bill book graphic legal_case legislation motion_picture report song" match="any">
289 |           <group delimiter=", " suffix=". ">
290 |             <text macro="title"/>
291 |             <text macro="locators"/>
292 |           </group>
293 |           <group delimiter=", ">
294 |             <text macro="publisher"/>
295 |             <text macro="issued"/>
296 |             <text macro="page"/>
297 |           </group>
298 |         </else-if>
299 |         <else-if type="article-magazine article-newspaper broadcast interview manuscript map patent personal_communication song speech thesis webpage" match="any">
300 |           <group delimiter=", ">
301 |             <text macro="title"/>
302 |             <text variable="container-title" font-style="italic"/>
303 |             <text macro="locators"/>
304 |             <text macro="publisher"/>
305 |             <text macro="page"/>
306 |             <text macro="issued"/>
307 |           </group>
308 |         </else-if>
309 |         <else-if type="chapter paper-conference" match="any">
310 |           <group delimiter=", " suffix=", ">
311 |             <text macro="title"/>
312 |             <group delimiter=" ">
313 |               <text term="in"/>
314 |               <text variable="container-title" font-style="italic"/>
315 |             </group>
316 |             <text macro="locators"/>
317 |           </group>
318 |           <text macro="editor" suffix=" "/>
319 |           <group delimiter=", ">
320 |             <text macro="publisher"/>
321 |             <text macro="issued"/>
322 |             <text macro="page"/>
323 |           </group>
324 |         </else-if>
325 |         <else>
326 |           <group delimiter=", " suffix=". ">
327 |             <text macro="title"/>
328 |             <text variable="container-title" font-style="italic"/>
329 |             <text macro="locators"/>
330 |           </group>
331 |           <group delimiter=", ">
332 |             <text macro="publisher"/>
333 |             <text macro="page"/>
334 |             <text macro="issued"/>
335 |           </group>
336 |         </else>
337 |       </choose>
338 |     </layout>
339 |   </bibliography>
340 | </style>
341 | 


--------------------------------------------------------------------------------
/packages/meshrc/files/web/www/meshrc/static/js/netjsongraph.js:
--------------------------------------------------------------------------------
  1 | // version 0.1
  2 | (function () {
  3 |     /**
  4 |      * vanilla JS implementation of jQuery.extend()
  5 |      */
  6 |     d3._extend = function(defaults, options) {
  7 |         var extended = {},
  8 |             prop;
  9 |         for(prop in defaults) {
 10 |             if(Object.prototype.hasOwnProperty.call(defaults, prop)) {
 11 |                 extended[prop] = defaults[prop];
 12 |             }
 13 |         }
 14 |         for(prop in options) {
 15 |             if(Object.prototype.hasOwnProperty.call(options, prop)) {
 16 |                 extended[prop] = options[prop];
 17 |             }
 18 |         }
 19 |         return extended;
 20 |     };
 21 | 
 22 |     /**
 23 |       * @function
 24 |       *   @name d3._pxToNumber
 25 |       * Convert strings like "10px" to 10
 26 |       *
 27 |       * @param  {string}       val         The value to convert
 28 |       * @return {int}              The converted integer
 29 |       */
 30 |     d3._pxToNumber = function(val) {
 31 |         return parseFloat(val.replace('px'));
 32 |     };
 33 | 
 34 |     /**
 35 |       * @function
 36 |       *   @name d3._windowHeight
 37 |       *
 38 |       * Get window height
 39 |       *
 40 |       * @return  {int}            The window innerHeight
 41 |       */
 42 |     d3._windowHeight = function() {
 43 |         return window.innerHeight || document.documentElement.clientHeight || 600;
 44 |     };
 45 | 
 46 |     /**
 47 |       * @function
 48 |       *   @name d3._getPosition
 49 |       *
 50 |       * Get the position of `element` relative to `container`
 51 |       *
 52 |       * @param  {object}      element
 53 |       * @param  {object}      container
 54 |       */
 55 |      d3._getPosition = function(element, container) {
 56 |          var n = element.node(),
 57 |              nPos = n.getBoundingClientRect();
 58 |              cPos = container.node().getBoundingClientRect();
 59 |          return {
 60 |             top: nPos.top - cPos.top,
 61 |             left: nPos.left - cPos.left,
 62 |             width: nPos.width,
 63 |             bottom: nPos.bottom - cPos.top,
 64 |             height: nPos.height,
 65 |             right: nPos.right - cPos.left
 66 |         };
 67 |      };
 68 | 
 69 |     /**
 70 |      * netjsongraph.js main function
 71 |      *
 72 |      * @constructor
 73 |      * @param  {string}      url             The NetJSON file url
 74 |      * @param  {object}      opts            The object with parameters to override {@link d3.netJsonGraph.opts}
 75 |      */
 76 |     d3.netJsonGraph = function(url, opts) {
 77 |         /**
 78 |          * Default options
 79 |          *
 80 |          * @param  {string}     el                  "body"      The container element                                  el: "body" [description]
 81 |          * @param  {bool}       metadata            true        Display NetJSON metadata at startup?
 82 |          * @param  {bool}       defaultStyle        true        Use css style?
 83 |          * @param  {bool}       animationAtStart    false       Animate nodes or not on load
 84 |          * @param  {array}      scaleExtent         [0.25, 5]   The zoom scale's allowed range. @see {@link https://github.com/mbostock/d3/wiki/Zoom-Behavior#scaleExtent}
 85 |          * @param  {int}        charge              -130        The charge strength to the specified value. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#charge}
 86 |          * @param  {int}        linkDistance        50          The target distance between linked nodes to the specified value. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#linkDistance}
 87 |          * @param  {float}      linkStrength        0.2         The strength (rigidity) of links to the specified value in the range. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#linkStrength}
 88 |          * @param  {float}      friction            0.9         The friction coefficient to the specified value. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#friction}
 89 |          * @param  {string}     chargeDistance      Infinity    The maximum distance over which charge forces are applied. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#chargeDistance}
 90 |          * @param  {float}      theta               0.8         The Barnes–Hut approximation criterion to the specified value. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#theta}
 91 |          * @param  {float}      gravity             0.1         The gravitational strength to the specified numerical value. @see {@link https://github.com/mbostock/d3/wiki/Force-Layout#gravity}
 92 |          * @param  {int}        circleRadius        8           The radius of circles (nodes) in pixel
 93 |          * @param  {string}     labelDx             "0"         SVG dx (distance on x axis) attribute of node labels in graph
 94 |          * @param  {string}     labelDy             "-1.3em"    SVG dy (distance on y axis) attribute of node labels in graph
 95 |          * @param  {function}   onInit                          Callback function executed on initialization
 96 |          * @param  {function}   onLoad                          Callback function executed after data has been loaded
 97 |          * @param  {function}   onEnd                           Callback function executed when initial animation is complete
 98 |          * @param  {function}   linkDistanceFunc                By default high density areas have longer links
 99 |          * @param  {function}   redraw                          Called when panning and zooming
100 |          * @param  {function}   prepareData                     Used to convert NetJSON NetworkGraph to the javascript data
101 |          * @param  {function}   onClickNode                     Called when a node is clicked
102 |          * @param  {function}   onClickLink                     Called when a link is clicked
103 |          */
104 |         opts = d3._extend({
105 |             el: "body",
106 |             metadata: true,
107 |             defaultStyle: true,
108 |             animationAtStart: true,
109 |             scaleExtent: [0.25, 5],
110 |             charge: -130,
111 |             linkDistance: 50,
112 |             linkStrength: 0.2,
113 |             friction: 0.9,  // d3 default
114 |             chargeDistance: Infinity,  // d3 default
115 |             theta: 0.8,  // d3 default
116 |             gravity: 0.1,
117 |             circleRadius: 8,
118 |             labelDx: "0",
119 |             labelDy: "-1.3em",
120 |             nodeClassProperty: null,
121 |             linkClassProperty: null,
122 |             /**
123 |              * @function
124 |              * @name onInit
125 |              *
126 |              * Callback function executed on initialization
127 |              * @param  {string|object}  url     The netJson remote url or object
128 |              * @param  {object}         opts    The object of passed arguments
129 |              * @return {function}
130 |              */
131 |             onInit: function(url, opts) {},
132 |             /**
133 |              * @function
134 |              * @name onLoad
135 |              *
136 |              * Callback function executed after data has been loaded
137 |              * @param  {string|object}  url     The netJson remote url or object
138 |              * @param  {object}         opts    The object of passed arguments
139 |              * @return {function}
140 |              */
141 |             onLoad: function(url, opts) {},
142 |             /**
143 |              * @function
144 |              * @name onEnd
145 |              *
146 |              * Callback function executed when initial animation is complete
147 |              * @param  {string|object}  url     The netJson remote url or object
148 |              * @param  {object}         opts    The object of passed arguments
149 |              * @return {function}
150 |              */
151 |             onEnd: function(url, opts) {},
152 |             /**
153 |              * @function
154 |              * @name linkDistanceFunc
155 |              *
156 |              * By default, high density areas have longer links
157 |              */
158 |             linkDistanceFunc: function(d){
159 |                 var val = opts.linkDistance;
160 |                 if(d.source.linkCount >= 4 && d.target.linkCount >= 4) {
161 |                     return val * 2;
162 |                 }
163 |                 return val;
164 |             },
165 |             /**
166 |              * @function
167 |              * @name redraw
168 |              *
169 |              * Called on zoom and pan
170 |              */
171 |             redraw: function() {
172 |                 panner.attr("transform",
173 |                     "translate(" + d3.event.translate + ") " +
174 |                     "scale(" + d3.event.scale + ")"
175 |                 );
176 |             },
177 |             /**
178 |              * @function
179 |              * @name prepareData
180 |              *
181 |              * Convert NetJSON NetworkGraph to the data structure consumed by d3
182 |              *
183 |              * @param graph {object}
184 |              */
185 |             prepareData: function(graph) {
186 |                 var nodesMap = {},
187 |                     nodes = graph.nodes.slice(), // copy
188 |                     links = graph.links.slice(), // copy
189 |                     nodes_length = graph.nodes.length,
190 |                     links_length = graph.links.length;
191 | 
192 |                 for(var i = 0; i < nodes_length; i++) {
193 |                     // count how many links every node has
194 |                     nodes[i].linkCount = 0;
195 |                     nodesMap[nodes[i].id] = i;
196 |                 }
197 |                 for(var c = 0; c < links_length; c++) {
198 |                     var sourceIndex = nodesMap[links[c].source],
199 |                     targetIndex = nodesMap[links[c].target];
200 |                     // ensure source and target exist
201 |                     if(!nodes[sourceIndex]) { throw("source '" + links[c].source + "' not found"); }
202 |                     if(!nodes[targetIndex]) { throw("target '" + links[c].target + "' not found"); }
203 |                     links[c].source = nodesMap[links[c].source];
204 |                     links[c].target = nodesMap[links[c].target];
205 |                     // add link count to both ends
206 |                     nodes[sourceIndex].linkCount++;
207 |                     nodes[targetIndex].linkCount++;
208 |                 }
209 |                 return { "nodes": nodes, "links": links };
210 |             },
211 |             /**
212 |              * @function
213 |              * @name onClickNode
214 |              *
215 |              * Called when a node is clicked
216 |              */
217 |             onClickNode: function(n) {
218 |                 var overlay = d3.select(".njg-overlay"),
219 |                     overlayInner = d3.select(".njg-overlay > .njg-inner"),
220 |                     html = "<p><b>id</b>: " + n.id + "</p>";
221 |                     if(n.label) { html += "<p><b>label</b>: " + n.label + "</p>"; }
222 |                     if(n.properties) {
223 |                         for(var key in n.properties) {
224 |                             if(!n.properties.hasOwnProperty(key)) { continue; }
225 |                             html += "<p><b>"+key.replace(/_/g, " ")+"</b>: " + n.properties[key] + "</p>";
226 |                     }
227 |                 }
228 |                 if(n.linkCount) { html += "<p><b>links</b>: " + n.linkCount + "</p>"; }
229 |                 if(n.local_addresses) {
230 |                     html += "<p><b>local addresses</b>:<br>" + n.local_addresses.join('<br>') + "</p>";
231 |                 }
232 |                 overlayInner.html(html);
233 |                 overlay.classed("njg-hidden", false);
234 |                 overlay.style("display", "block");
235 |                 // set "open" class to current node
236 |                 removeOpenClass();
237 |                 d3.select(this).classed("njg-open", true);
238 |             },
239 |             /**
240 |              * @function
241 |              * @name onClickLink
242 |              *
243 |              * Called when a node is clicked
244 |              */
245 |             onClickLink: function(l) {
246 |                 var overlay = d3.select(".njg-overlay"),
247 |                     overlayInner = d3.select(".njg-overlay > .njg-inner"),
248 |                     html = "<p><b>source</b>: " + (l.source.label || l.source.id) + "</p>";
249 |                     html += "<p><b>target</b>: " + (l.target.label || l.target.id) + "</p>";
250 |                     html += "<p><b>cost</b>: " + l.cost + "</p>";
251 |                 if(l.properties) {
252 |                     for(var key in l.properties) {
253 |                         if(!l.properties.hasOwnProperty(key)) { continue; }
254 |                         html += "<p><b>"+ key.replace(/_/g, " ") +"</b>: " + l.properties[key] + "</p>";
255 |                     }
256 |                 }
257 |                 overlayInner.html(html);
258 |                 overlay.classed("njg-hidden", false);
259 |                 overlay.style("display", "block");
260 |                 // set "open" class to current link
261 |                 removeOpenClass();
262 |                 d3.select(this).classed("njg-open", true);
263 |             }
264 |         }, opts);
265 | 
266 |         // init callback
267 |         opts.onInit(url, opts);
268 | 
269 |         if(!opts.animationAtStart) {
270 |             opts.linkStrength = 2;
271 |             opts.friction = 0.3;
272 |             opts.gravity = 0;
273 |         }
274 |         if(opts.el == "body") {
275 |             var body = d3.select(opts.el),
276 |                 rect = body.node().getBoundingClientRect();
277 |             if (d3._pxToNumber(d3.select("body").style("height")) < 60) {
278 |                 body.style("height", d3._windowHeight() - rect.top - rect.bottom + "px");
279 |             }
280 |         }
281 |         var el = d3.select(opts.el).style("position", "relative"),
282 |             width = d3._pxToNumber(el.style('width')),
283 |             height = d3._pxToNumber(el.style('height')),
284 |             force = d3.layout.force()
285 |                       .charge(opts.charge)
286 |                       .linkStrength(opts.linkStrength)
287 |                       .linkDistance(opts.linkDistanceFunc)
288 |                       .friction(opts.friction)
289 |                       .chargeDistance(opts.chargeDistance)
290 |                       .theta(opts.theta)
291 |                       .gravity(opts.gravity)
292 |                       // width is easy to get, if height is 0 take the height of the body
293 |                       .size([width, height]),
294 |             zoom = d3.behavior.zoom().scaleExtent(opts.scaleExtent),
295 |             // panner is the element that allows zooming and panning
296 |             panner = el.append("svg")
297 |                        .attr("width", width)
298 |                        .attr("height", height)
299 |                        .call(zoom.on("zoom", opts.redraw))
300 |                        .append("g")
301 |                        .style("position", "absolute"),
302 |             svg = d3.select(opts.el + " svg"),
303 |             drag = force.drag(),
304 |             overlay = d3.select(opts.el).append("div").attr("class", "njg-overlay"),
305 |             closeOverlay = overlay.append("a").attr("class", "njg-close"),
306 |             overlayInner = overlay.append("div").attr("class", "njg-inner"),
307 |             metadata = d3.select(opts.el).append("div").attr("class", "njg-metadata"),
308 |             metadataInner = metadata.append("div").attr("class", "njg-inner"),
309 |             closeMetadata = metadata.append("a").attr("class", "njg-close"),
310 |             // container of ungrouped networks
311 |             str = [],
312 |             selected = [],
313 |             /**
314 |              * @function
315 |              * @name removeOpenClass
316 |              *
317 |              * Remove open classes from nodes and links
318 |              */
319 |             removeOpenClass = function () {
320 |                 d3.selectAll("svg .njg-open").classed("njg-open", false);
321 |             };
322 |             processJson = function(graph) {
323 |                 /**
324 |                  * Init netJsonGraph
325 |                  */
326 |                 init = function(url, opts) {
327 |                     d3.netJsonGraph(url, opts);
328 |                 };
329 |                 /**
330 |                  * Remove all instances
331 |                  */
332 |                 destroy = function() {
333 |                     force.stop();
334 |                     d3.select("#selectGroup").remove();
335 |                     d3.select(".njg-overlay").remove();
336 |                     d3.select(".njg-metadata").remove();
337 |                     overlay.remove();
338 |                     overlayInner.remove();
339 |                     metadata.remove();
340 |                     svg.remove();
341 |                     node.remove();
342 |                     link.remove();
343 |                     nodes = [];
344 |                     links = [];
345 |                 };
346 |                 /**
347 |                  * Destroy and e-init all instances
348 |                  * @return {[type]} [description]
349 |                  */
350 |                 reInit = function() {
351 |                     destroy();
352 |                     init(url, opts);
353 |                 };
354 | 
355 |                 var data = opts.prepareData(graph),
356 |                     links = data.links,
357 |                     nodes = data.nodes;
358 | 
359 |                 // disable some transitions while dragging
360 |                 drag.on('dragstart', function(n){
361 |                     d3.event.sourceEvent.stopPropagation();
362 |                     zoom.on('zoom', null);
363 |                 })
364 |                 // re-enable transitions when dragging stops
365 |                 .on('dragend', function(n){
366 |                     zoom.on('zoom', opts.redraw);
367 |                 })
368 |                 .on("drag", function(d) {
369 |                     // avoid pan & drag conflict
370 |                     d3.select(this).attr("x", d.x = d3.event.x).attr("y", d.y = d3.event.y);
371 |                 });
372 | 
373 |                 force.nodes(nodes).links(links).start();
374 | 
375 |                 var link = panner.selectAll(".link")
376 |                                  .data(links)
377 |                                  .enter().append("line")
378 |                                  .attr("class", function (link) {
379 |                                      var baseClass = "njg-link",
380 |                                          addClass = null;
381 |                                          value = link.properties && link.properties[opts.linkClassProperty];
382 |                                      if (opts.linkClassProperty && value) {
383 |                                          // if value is stirng use that as class
384 |                                          if (typeof(value) === "string") {
385 |                                              addClass = value;
386 |                                          }
387 |                                          else if (typeof(value) === "number") {
388 |                                              addClass = opts.linkClassProperty + value;
389 |                                          }
390 |                                          else if (value === true) {
391 |                                              addClass = opts.linkClassProperty;
392 |                                          }
393 |                                          return baseClass + " " + addClass;
394 |                                      }
395 |                                      return baseClass;
396 |                                  })
397 |                                  .on("click", opts.onClickLink),
398 |                     groups = panner.selectAll(".node")
399 |                                    .data(nodes)
400 |                                    .enter()
401 |                                    .append("g");
402 |                     node = groups.append("circle")
403 |                                  .attr("class", function (node) {
404 |                                      var baseClass = "njg-node",
405 |                                          addClass = null;
406 |                                          value = node.properties && node.properties[opts.nodeClassProperty];
407 |                                      if (opts.nodeClassProperty && value) {
408 |                                          // if value is stirng use that as class
409 |                                          if (typeof(value) === "string") {
410 |                                              addClass = value;
411 |                                          }
412 |                                          else if (typeof(value) === "number") {
413 |                                              addClass = opts.nodeClassProperty + value;
414 |                                          }
415 |                                          else if (value === true) {
416 |                                              addClass = opts.nodeClassProperty;
417 |                                          }
418 |                                          return baseClass + " " + addClass;
419 |                                      }
420 |                                      return baseClass;
421 |                                  })
422 |                                  .attr("r", opts.circleRadius)
423 |                                  .on("click", opts.onClickNode)
424 |                                  .call(drag);
425 | 
426 |                     var labels = groups.append('text')
427 |                                        .text(function(n){ return n.label || n.id })
428 |                                        .attr('dx', opts.labelDx)
429 |                                        .attr('dy', opts.labelDy)
430 |                                        .attr('class', 'njg-tooltip');
431 | 
432 |                 // Close overlay
433 |                 closeOverlay.on("click", function() {
434 |                     removeOpenClass();
435 |                     overlay.classed("njg-hidden", true);
436 |                 });
437 |                 // Close Metadata panel
438 |                 closeMetadata.on("click", function() {
439 |                     // Reinitialize the page
440 |                     if(graph.type === "NetworkCollection") {
441 |                         reInit();
442 |                     }
443 |                     else {
444 |                         removeOpenClass();
445 |                         metadata.classed("njg-hidden", true);
446 |                     }
447 |                 });
448 |                 // default style
449 |                 // TODO: probably change defaultStyle
450 |                 // into something else
451 |                 if(opts.defaultStyle) {
452 |                     var colors = d3.scale.category20c();
453 |                     node.style({
454 |                         "fill": function(d){ return colors(d.linkCount); },
455 |                         "cursor": "pointer"
456 |                     });
457 |                 }
458 |                 // Metadata style
459 |                 if(opts.metadata) {
460 |                     metadata.attr("class", "njg-metadata").style("display", "block");
461 |                 }
462 | 
463 |                 var attrs = ["protocol",
464 |                              "version",
465 |                              "revision",
466 |                              "metric",
467 |                              "router_id",
468 |                              "topology_id"],
469 |                     html = "";
470 |                 if(graph.label) {
471 |                     html += "<h3>" + graph.label + "</h3>";
472 |                 }
473 |                 for(var i in attrs) {
474 |                     var attr = attrs[i];
475 |                     if(graph[attr]) {
476 |                         html += "<p><b>" + attr + "</b>: <span>" + graph[attr] + "</span></p>";
477 |                     }
478 |                 }
479 |                 // Add nodes and links count
480 |                 html += "<p><b>nodes</b>: <span>" + graph.nodes.length + "</span></p>";
481 |                 html += "<p><b>links</b>: <span>" + graph.links.length + "</span></p>";
482 |                 metadataInner.html(html);
483 |                 metadata.classed("njg-hidden", false);
484 | 
485 |                 // onLoad callback
486 |                 opts.onLoad(url, opts);
487 | 
488 |                 force.on("tick", function() {
489 |                     link.attr("x1", function(d) {
490 |                         return d.source.x;
491 |                     })
492 |                     .attr("y1", function(d) {
493 |                         return d.source.y;
494 |                     })
495 |                     .attr("x2", function(d) {
496 |                         return d.target.x;
497 |                     })
498 |                     .attr("y2", function(d) {
499 |                         return d.target.y;
500 |                     });
501 | 
502 |                     node.attr("cx", function(d) {
503 |                         return d.x;
504 |                     })
505 |                     .attr("cy", function(d) {
506 |                         return d.y;
507 |                     });
508 | 
509 |                     labels.attr("transform", function(d) {
510 |                         return "translate(" + d.x + "," + d.y + ")";
511 |                     });
512 |                 })
513 |                 .on("end", function(){
514 |                     force.stop();
515 |                     // onEnd callback
516 |                     opts.onEnd(url, opts);
517 |                 });
518 | 
519 |                 return force;
520 |             };
521 | 
522 |         if(typeof(url) === "object") {
523 |             processJson(url);
524 |         }
525 |         else {
526 |             /**
527 |             * Parse the provided json file
528 |             * and call processJson() function
529 |             *
530 |             * @param  {string}     url         The provided json file
531 |             * @param  {function}   error
532 |             */
533 |             d3.json(url, function(error, graph) {
534 |                 if(error) { throw error; }
535 |                 /**
536 |                 * Check if the json contains a NetworkCollection
537 |                 */
538 |                 if(graph.type === "NetworkCollection") {
539 |                     var selectGroup = body.append("div").attr("id", "njg-select-group"),
540 |                         select = selectGroup.append("select")
541 |                                             .attr("id", "select");
542 |                         str = graph;
543 |                     select.append("option")
544 |                           .attr({
545 |                               "value": "",
546 |                               "selected": "selected",
547 |                               "name": "default",
548 |                               "disabled": "disabled"
549 |                           })
550 |                           .html("Choose the network to display");
551 |                     graph.collection.forEach(function(structure) {
552 |                         select.append("option").attr("value", structure.type).html(structure.type);
553 |                         // Collect each network json structure
554 |                         selected[structure.type] = structure;
555 |                     });
556 |                     select.on("change", function() {
557 |                         selectGroup.attr("class", "njg-hidden");
558 |                         // Call selected json structure
559 |                         processJson(selected[this.options[this.selectedIndex].value]);
560 |                     });
561 |                 }
562 |                 else {
563 |                     processJson(graph);
564 |                 }
565 |             });
566 |         }
567 |      };
568 | })();
569 | 


--------------------------------------------------------------------------------
/bachelor_thesis/bachelor.md:
--------------------------------------------------------------------------------
   1 | ---
   2 | title: "Wireless Mesh as easy deployable and scaleable Internet backbone"
   3 | subtitle: "Bachelorarbeit"
   4 | toc: True
   5 | author: [Paul Spooren]
   6 | birthday: 22.12.1992
   7 | date: 09.08.2018
   8 | tags: [Mesh, Internet, OpenWrt]
   9 | titlepage: True
  10 | betreuer: Dr. Michael Martin
  11 | titlegraphic: img/ul-logo
  12 | bibliography: bachelor.bib
  13 | link-citations: True
  14 | numbersections: True
  15 | toc-own-page: True
  16 | toc-depth: 3
  17 | lot: False
  18 | lof: False
  19 | titlepage-rule-color: ffffff
  20 | fontsize: 10pt
  21 | handout: True
  22 | abstract: |
  23 |   Within the last years the importance of internet driven applications
  24 |   continuously raised and so
  25 |   the need of its distribution. The question of distribution is broadly solved
  26 |   for static setups, however lacks an answer for quickly deployed installations
  27 |   setup by non-professionals which would allow Internet coverage of events
  28 |   for instance music festivals or winter markets but also in case of an emergency
  29 |   where other infrastructure crashed.
  30 | 
  31 |   The main research question of this project is to find a way which allows easy
  32 |   creation of wireless access points (APs) with minimal manual configuration. It
  33 |   solves the challenge of establishing a backbone network which connects all
  34 |   devices offering an AP so that traffic is routed to the Internet.
  35 | 
  36 |   A feasible approach to easily setup a backbone network is to use a mesh
  37 |   topology, where nodes are connected to their surrounding neighbors (other
  38 |   nodes). This topology can be seen as an alternative to the classical star
  39 |   topology where one device connects to multiple others. Changes within the
  40 |   network, like extending the covered area with more APs, are automatically
  41 |   detected by an application running on every node. The network becomes easily
  42 |   redundant once nodes are connected to multiple neighbors. In case of device
  43 |   failures alternative routes are calculated and used without manual
  44 |   intervention.
  45 | 
  46 |   The final outcome is a firmware to automatically create APs and a backbone
  47 |   network based on wireless mesh. To make this practically usable tools are
  48 |   created to monitor and configure the network in an easy fashion.  Additionally,
  49 |   there are hardware recommendations attached to the software stack providing a
  50 |   full setup within this work which is practically usable for the use cases
  51 |   mentioned previously.
  52 | 
  53 | ---
  54 | 
  55 | # Introduction
  56 | 
  57 | Due to the collaboration over the last two years with several Community Networks
  58 | I learned about the advances of mesh networks in contrast to statically
  59 | installed ones. During deployment of such networks I repeatedly realized the
  60 | absence of a toolset to simplify the setup and keep track of the network health.
  61 | In this work I implemented the missing tools and extended existing solutions to
  62 | be easily usable in real environments.
  63 | 
  64 | Community networks introduce additional challenges which exceed the focus of
  65 | this document. For that reason I decided to focus on use cases where all
  66 | hardware is owned by a single instance, simplifying the setup and lowering
  67 | security requirements. The tool created can nevertheless be used in community
  68 | networks, although this may require some additional modifications to follow
  69 | their decentralized requirements.
  70 | 
  71 | ## Motivation
  72 | 
  73 | Creating a backbone network is a non trivial task. It requires experts to plan
  74 | the network topology ahead and define the way traffic network is routed  within
  75 | the network. Changes of the structure or optimization to prevent overload need
  76 | manual intervention. Manual setups may also lead to misconfiguration and cause
  77 | network downtimes. A more automated way could simplify the setup of backbone
  78 | networks possibly with mesh networks.
  79 | 
  80 | While for many years WiFi mesh networks have only been used by network activists
  81 | like Freifunk[^web_freifunk] or LibreMesh[^web_libremesh] the technology now
  82 | has been adopted even by big companies like Google Inc.[^google_mesh].
  83 | 
  84 | Having seen the mesh approach work in Community Networks[^qmp_barcelona] I
  85 | decided to make it usable for other use cases as well, allowing individuals
  86 | interested, which haven't touched this area yet, to deploy their own
  87 | decentralized backbone network.
  88 | 
  89 | [^web_freifunk]: https://freifunk.net/
  90 | [^web_libremesh]: https://libremesh.org/
  91 | [^google_mesh]: https://store.google.com/product/google_wifi_learn
  92 | 
  93 | ## Aim
  94 | 
  95 | This work focuses on the simple initial setup, monitoring and configuration of a
  96 | backbone network which distributes an Internet uplink, setup and managed by a
  97 | central instance owning all nodes of the network.
  98 | 
  99 | This approach is not to be compared to tools and setups specialized on community
 100 | networks as exceedingly discussed in other works [@kos2015nodewatcher p. 4].
 101 | While parts of the implemented tools may be used in such a setup, the
 102 | centralized management is focused.
 103 | 
 104 | The outputs of this project are the following three parts:
 105 | 
 106 | * Node firmware which automatically integrates into the mesh network.
 107 | * A monitoring tool to check the usage and health of the network.
 108 | * A configuration tool to set basic properties of the network.
 109 | 
 110 | Different from existing approaches for monitoring and managing wireless
 111 | networks, no complex per device configuration is planned following the idea of
 112 | zero configuration, keeping all devices as generic as possible. Neither is any
 113 | longtime monitoring over several years implemented like for instance at
 114 | Guifi.net[^guifi_growmap]. This is due to this works focus on temporal
 115 | installations, where no such long time periods occur.
 116 | 
 117 | [^guifi_growmap]: https://guifi.net/en/guifi/menu/stats/growthmap
 118 | 
 119 | ## Illustrative use case
 120 | 
 121 | To give a better idea of what the output of this work could be used for, below a
 122 | short description of a possible use case.
 123 | 
 124 | A winter market takes place yearly within the center of a city. For this event
 125 | small houses are built up and sell various goods. An electronic payment system
 126 | requires an Internet connection to verify payments. As thousands of mobile
 127 | devices with LTE arrive to the event, mobile telephony network may become
 128 | overloaded and the payment system could break down, if it would rely on it.
 129 | Instead, a number of WiFi access points could be created, where only authorized
 130 | payment devices can connect to. The mesh approach explained before could be used
 131 | in the following way, to allow the easy setup and spreading of APs. A small
 132 | number of vendors receive a pre configured mesh node and connect them to a power
 133 | plug. Active nodes connect with all other nodes in reach and offer an access
 134 | point at the same time. A special gateway node announces its direct Internet
 135 | connection to all active nodes, which then start using it.
 136 | 
 137 | If the winter market, due to unforeseen reasons, is shaped in a different way
 138 | than initially planed, the nodes connect dynamically, providing the same
 139 | functional backbone network. Additionally, if the winter market grows over the
 140 | initially planed area, a node is added and the access point coverage increases.
 141 | While the mesh approach could solve the growth and dynamic changes easily, a
 142 | classical static network likely requires manual, configuration per devices.
 143 | 
 144 | ## Structure
 145 | 
 146 | This work is separated into sections starting from assessing requirements and
 147 | ends with a summary of the final product. In the section *project requirements*
 148 | \ref{project-requirements} specific needs of the works scope are explained. It
 149 | includes the sub-section *design decisions* \ref{design-decisions} elaborating
 150 | on used concepts and concrete realization - followed by section *implementation*
 151 | \ref{implementation} which covers technical details of used software and created
 152 | code. The last section *conclusion* \ref{conclusion} gives a summary of all work
 153 | done leading to fulfill the main objective.
 154 | 
 155 | Additionally provided are *attachments* \ref{attachments} which discuss hardware
 156 | and configurations used within this work.
 157 | 
 158 | ## Related work
 159 | 
 160 | Previous to this work established solutions in the area of mesh networks were
 161 | reviewed to find a suitable starting point. The projects mentioned below are
 162 | community driven with a focus on community networks (CNs) [@vega2012topology
 163 | p.1]. While CNs are not focus of this work the software stack is open source and
 164 | can therefore be modified to fit the [projects
 165 | requirements](#project-requirements).
 166 | 
 167 | All below mentioned distribution or frameworks are based on OpenWrt and run on
 168 | regular home routers.
 169 | 
 170 | ### Freifunk's Gluon
 171 | 
 172 | The Gluon software stack is broadly established in various states of
 173 | Germany^[https://multi.meshviewer.org/]. The software allows users to share
 174 | their Internet connectivity in two ways. Primary it is possible to offer
 175 | Internet connection (received by DSL or TV Cable) via an open AP to surrounding
 176 | neighbors. The traffic is routed over a community-owned VPN to avoid possible
 177 | lawsuits. Secondly the routers connect via wireless mesh with neighbored nodes
 178 | and share their uplink if existent, also vice versa.
 179 | 
 180 | To create the mesh network both *802.11s* and *ad hoc* are supported, for
 181 | routing the protocol B.A.T.M.A.N. Advanced[^batman_adv] is used.
 182 | 
 183 | [^batadv_scale]: https://trier.freifunk.net/2017/08/28/die-hoods-kommen/
 184 | [^gluon_monitoring]: https://develop.meshviewer.org/
 185 | 
 186 | ### The Quick Mesh Project (qMp)
 187 | 
 188 | This distribution offers firmware images to setup a mesh network with minimal
 189 | manual intervention. The firmware automatically sets up all requirements to be
 190 | used in a mesh network and automatically connects to neighbors. If an Internet
 191 | upstream is announced by the mesh routing protocol, it automatically offers the
 192 | connection to connected clients. The project is actively used in the Barcelona
 193 | city area[^qmp_barcelona] with an active user base.
 194 | 
 195 | The firmware relies on the mesh routing protocol BMX6[^bmx6_github] and creates
 196 | the backbone mesh connection via *ad hoc* (in contrast to the newer *802.11s*
 197 | modes).
 198 | 
 199 | [^qmp_barcelona]: http://tomir.ac.upc.edu/qmpmon
 200 | [^bmx6_github]: https://github.com/bmx-routing/bmx6
 201 | 
 202 | ### LibreMesh (LiMe)
 203 | 
 204 | LibreMesh is more a community driven framework than a distribution. Due to its
 205 | modularity it supports various use cases. It is possible to change activated
 206 | routing protocols, preinstalled software and IP addresses of subnets used. A
 207 | single configuration file[^lime_defaults] allows to control all WiFi, mesh and
 208 | network related settings.
 209 | 
 210 | Additionally it offers precompiled firmware images which work without any
 211 | further configuration. These images use a combination of *BMX6* and
 212 | *B.A.T.M.A.N*.
 213 | 
 214 | [^lime_defaults]: https://github.com/libremesh/lime-packages/blob/develop/packages/lime-system/files/etc/config/lime-defaults
 215 | 
 216 | The project is under active development and therefore offers a good starting
 217 | point to fulfill the requirements stated in section \ref{project-requirements}.
 218 | 
 219 | \newpage
 220 | # Basics concepts
 221 | 
 222 | This section aims to offer introducing knowledge of used technologies, covering
 223 | basics of wireless mesh networks, routing and dynamic routing protocols and
 224 | lastly the operating system for embedded devices OpenWrt.
 225 | 
 226 | ## Physical connection between devices
 227 | 
 228 | Using cable or fiber connection between the nodes is optimal in terms of speed
 229 | but requires more work to setup. For the rapid deployment wireless connections
 230 | are preferred. This approach is broadly tested in various community
 231 | networks [@vega2012topology p. 2].
 232 | 
 233 | ### Wireless access points
 234 | 
 235 | The most established setup for Wireless LAN or WiFi is an access point offering
 236 | a network to which clients may connect. This approach is found in nearly every
 237 | house with Internet access and many public places.  This setup is also usable to
 238 | provide uplink connectivity and is used by Wireless Internet Service Providers.
 239 | A fail of the access point results in connection loss between all connected
 240 | client nodes, even if they would be within line of sight.
 241 | 
 242 | ### Wireless mesh
 243 | 
 244 | The WiFi standard *802.11s* (*11s*) [@hiertz2010ieee] offers the possibility that
 245 | two or more devices connect without the limits of a *client* and *access point*
 246 | setup.  All devices are connected equally, allowing continuous connectivity even
 247 | if single devices fail, as illustrated below. The *11s* WiFi mesh creates the
 248 | foundation of the backbone network discussed in this project.
 249 | 
 250 | Important to mention, the *11s* standard also introduces a routing protocol
 251 | which is deactivated in this project in favor of the routing protocol *BMX7*,
 252 | offering required features.
 253 | 
 254 | ![**Wireless mesh network** - Possible setup of a mesh network which offers
 255 | inter mesh connections to clients and via a gateway Internet access.\label{backbone}](img/backbone.png)
 256 | 
 257 | Figure \ref{backbone} shows an illustrative mesh network combining wireless mesh
 258 | connections with *11s* and APs. The red arrows stand for the backbone which is
 259 | handled by the dynamic routing protocol and transparent for connected clients.
 260 | Clients may connect via IP addresses to other clients within the mesh or use a
 261 | gateway node which offers uplink to the Internet.
 262 | 
 263 | ## Routing of network traffic
 264 | 
 265 | A telecommunication network means the connection from any number of devices in a
 266 | way that they can communicate with each other. Nodes within the network require
 267 | routing information to forward or deliver packages to its receiver.
 268 | 
 269 | The following information is vastly simplified and has an exceeding explanation
 270 | in related works [@escrich2012quick p. 5].
 271 | 
 272 | ### Classical network topologies
 273 | 
 274 | A network topology describes the connection design between nodes of a network.
 275 | Figure \ref{topology} pictures both star and tree topology.
 276 | 
 277 | ![**Star and tree topologies**\label{topology}](img/topology.png)
 278 | 
 279 | This approach has the disadvantage that a node might move from one subnet to
 280 | another. Furthermore chaining of nodes is difficult as it requires previous
 281 | planning of subnetwork sizes.
 282 | 
 283 | ### Dynamic routing protocol
 284 | 
 285 | The statically routed network described above can be set once and then work
 286 | without any additional daemons running on nodes of the network. To allow
 287 | dynamic changes of the network, like adding a new device, an active service has
 288 | to run on devices and react on changes. Dynamic routing protocols are active
 289 | components which automatically adapt the routing so that devices stay
 290 | reachable. The protocols use metrics to determine the link quality and choose
 291 | the fastest link to connect between devices.
 292 | 
 293 | This project takes advantage of the actively developed and constantly improved
 294 | mesh routing protocol *BMX7* [@neumann2017cooperation]. While there exist
 295 | multiple other dynamic and on mesh specialized routing protocols *BMX7* is
 296 | chosen for its integrated features covered in section \ref{design-decisions}.
 297 | 
 298 | ## Operating systems for routers & network devices
 299 | 
 300 | Many home routers are able to run or are actually delivered with a very light
 301 | Linux operation system called OpenWrt[^openwrt_web]. It uses a modified Linux
 302 | kernel and has various optimizations to be usable on devices which often have
 303 | as little as 8MB of storage and 32MB of memory.
 304 | 
 305 | [^openwrt_web]: https://openwrt.org/
 306 | 
 307 | OpenWrt is comparable to other Linux distributions like Debian, but focused on
 308 | network related devices and embedded devices in general.
 309 | 
 310 | By default it can work as a wireless AP just usable as home routers do. However
 311 | it is possible to install mesh related packages via a package manager and
 312 | configure them depending on the required setup.
 313 | 
 314 | \newpage
 315 | # Project requirements
 316 | 
 317 | The following requirements and decisions regarding design are separated in node
 318 | and management specific lists. All items are based on my previous experiences
 319 | with the deployment and maintenance of mesh networks and advises from existing
 320 | Communities managing their own network.
 321 | 
 322 | Additional are aspects specially for this use case that cover the security of
 323 | the network which is normally not implemented in Community networks as they
 324 | use unencrypted connections between devices.
 325 | 
 326 | ## Overall project requirements
 327 | 
 328 | Meta requirements that lead general design decisions \ref{design-decisions}.
 329 | 
 330 | * M1 **Reuse existing solutions:** Before implementing new software it should be
 331 |   tried to adapt to or extend existing solutions.
 332 | 
 333 | * M2 **Modularity:** While focused on the described use case, created software
 334 |   should be modular enough to be used in other scenarios as well.
 335 | 
 336 | ## Requirements of the Mesh Firmware (N)
 337 | 
 338 | Covering the requirements of the software stack running on nodes.
 339 | 
 340 | * N1 **Zero-Conf Setup:** The initial setup of routers must work without
 341 |   per-device specific configuration, making it easy to rapidly deploy new
 342 |   devices.
 343 | 
 344 | * N2 **Encryption:** All wireless communication must be encrypted. Only devices
 345 |   authenticated with a password can enter the network.
 346 | 
 347 | * N3 **Frequency separation:** APs must run on a different frequency than the
 348 |   backbone mesh network to avoid connected clients to affect the backbone
 349 |   connection quality.
 350 | 
 351 | * N4 **Automatic device discovery:** New setup devices must automatically
 352 |   connect to the network and participate in the mesh network.
 353 | 
 354 | ## Requirements of the management interface (I)
 355 | 
 356 | Covering the requirements of the monitoring and management interface for
 357 | administrative users.
 358 | 
 359 | Beneath the previously mentioned community collaboration the monitoring
 360 | interface is inspired by preceding work in this area
 361 |  [@centelles2015enhancing] [@cerda2013experimental] to build on previously
 362 | acquired knowledge of demands in mesh network monitoring.
 363 | 
 364 | * I1 **Limited access:** Only authorized users can see monitoring data or change
 365 |   the network configuration.
 366 | 
 367 | * I2 **Simple setup:** No complex dependencies and no complex manual setup must
 368 |   be required to install the management interface, allowing non technical users
 369 |   to setup their own network.
 370 | 
 371 | * I3 **Network graph:** A graph showing all mesh-nodes of the network and the
 372 |   connection quality between them. This visualizes the network and helps to spot
 373 |   bottlenecks and malfunctioning devices.
 374 | 
 375 | * I4 **Automatic monitoring:** New mesh-nodes must be automatically added to
 376 |   monitoring and management interface, allowing configuration and status checks.
 377 | 
 378 | * I5 **Alerts:** In case of device failures or overloads the network
 379 |   administrators must automatically receive a warning.
 380 | 
 381 | * I6 **Network configuration:** The interface must allow the configuration of
 382 |   basic parameters of the network, like Access Point names (SSID) and passwords.
 383 | 
 384 | ## State of current mesh distributions
 385 | 
 386 | In this subsection some key limitations of the mesh distributions above
 387 | described are mentioned and thereby the choice for *LibreMesh* will be
 388 | explained.
 389 | 
 390 | ### Gluon
 391 | 
 392 | * **req. I2** Gluon offers a very sophisticated monitoring system
 393 |   [^gluon_monitoring] which exceeds the scope of this work. However it worked as
 394 |   a good inspirational source for the herewith created interface.
 395 | 
 396 | * **req. N1** Nodes are individually configured and use manually selected IP
 397 |   addresses^[https://config.berlin.freifunk.net/wizard/routers].
 398 | 
 399 | * While it is not a primary goal of this work to be highly scaleable, it is
 400 |   reasonable to offer greater numbers of access points to cover large areas.
 401 |   However using *B.A.T.M.A.N.* as mesh routing protocols comes with limitations
 402 |   in terms of scalability and thereby requires additional configuration around
 403 |   this issue[^batadv_scale].
 404 | 
 405 | ### qMp
 406 | 
 407 | * **req. N2** The final firmware is required to offer encrypted wireless
 408 |   connection between nodes and clients but also between nodes. This isn't
 409 |   possible for *ad hoc* mode and only available via *802.11s*. In recent
 410 |   development versions of *qMp* support for *802.11s* was added[^qmp_80211s] for
 411 |   testing but long after the decision to use *LibreMesh* as a base.
 412 | 
 413 | * **req. I3** Work was done for a monitoring system but never became fully
 414 |   integrated in the *qMp* [@centelles2015enhancing]. The scope of the monitoring
 415 |   system was also different as it was implemented in a decentralized way.
 416 | 
 417 | \newpage
 418 | 
 419 | ### LibreMesh
 420 | 
 421 | * *LibreMesh* did not offer any monitoring possibilities apart from a very
 422 |   rudimentary network graph offered by the `luci-app-bmx6`[^luci-app-bmx6]
 423 |   package.
 424 | 
 425 | * **req. I6** With a package called `first-boot-wizard`[^fbw] it is possible to
 426 |   distribute the initial configuration file called `lime-defaults` to other,
 427 |   unconfigured nodes within read. While this approach works for an initial setup
 428 |   it does not allow continuous changes nor distribution of settings outside the
 429 |   `lime-defaults` file, like SSH keys.
 430 | 
 431 | [^fbw]: https://github.com/libremesh/FirstBootWizard
 432 | [^luci-app-bmx6]: https://github.com/openwrt-routing/packages/tree/master/luci-app-bmx6
 433 | [^qmp_80211s]: dev.qmp.cat/projects/qmp/repository/revisions/003700f24b3859836644425de4f30c773bf6acca
 434 | 
 435 | | req. ID | Feature / Requirement         | Gluon     | qMp   | LibreMesh |
 436 | | ---     | ---                           | ---       | ---   | ---       |
 437 | |         | **Node**                      |           |       |           |
 438 | | N1      | Zero-Conf Setup               | N         | Y     | E         |
 439 | | N2      | Encryption                    | N         | N     | E         |
 440 | | N3      | Frequency separation          | N         | Y     | I         |
 441 | | N4      | Automatic device discovery    | N         | Y     | E         |
 442 | |         | **Management interface**      |           |       |           |
 443 | | I1      | Limited Access                | N         | N     | I         |
 444 | | I2      | Simple setup                  | N         | N     | I         |
 445 | | I3      | Network graph                 | Y         | N     | I         |
 446 | | I4      | Automatic monitoring          | N         | N     | I         |
 447 | | I5      | Alerts                        | U         | N     | I         |
 448 | | I6      | Network configuration         | N         | N     | I         |
 449 | 
 450 | Table: **Mesh distribution features:** *[Y]* exists, *[N]* missing, *[U]* unknown,
 451 | *[E]* extended within this work, *[I]* implemented within this work.
 452 | 
 453 | ## Design decisions
 454 | 
 455 | This sections cover the output of this work and explains how the previous stated
 456 | [project requirements] were fulfilled. The content is focused on fundamentals
 457 | and basic concepts and less technical than the following section covering the
 458 | concrete [implementation].
 459 | 
 460 | ### BMX7 as routing protocol
 461 | 
 462 | While there exists various mesh routing protocols like Batman
 463 | Advanced[^batman_adv], OLSR [@jacquet2003optimized] and
 464 | Babel [@chroboczek2011babel], three main reasons led this project to use *BMX7*.
 465 | 
 466 | * It is predecessor *BMX6* is the main routing protocol of qMp [@escrich2012quick
 467 |   p. 23] and LibreMesh both were used as a main source of inspiration.
 468 | * *BMX6* was evaluated to likely show better scaling and overall performance
 469 |   then the competitors Babel and OLSR [@baig2012evaluation pp. 53-54].
 470 | * It offers various plugins avoiding to re-implement required
 471 |   features^[https://github.com/bmx-routing/bmx7#bmx7-plugins].
 472 | 
 473 | ### Monitoring
 474 | 
 475 | To maintain a stable mesh network it is crucial to know key live information of
 476 | the devices. This can be done by a monitoring system obtaining data from nodes
 477 | and presenting them in an easily readable fashion.
 478 | 
 479 | #### Required data
 480 | 
 481 | It has to be distinguished between *device* and *network structure*. The
 482 | combination of both enables network administrators to quickly check the health
 483 | of the network and find bottlenecks.
 484 | 
 485 | ##### Monitoring of nodes
 486 | 
 487 | The collected metrics must allow the administrator to easily recognize device
 488 | malfunction and give an overview of the running network. The *per device*
 489 | monitoring therefore contains the following data:
 490 | 
 491 | * CPU load
 492 | * Free memory
 493 | * Traffic of AP and mesh
 494 | * Number of connected clients
 495 | * Firmware version
 496 | * Device hardware
 497 | 
 498 | #### Network structure and quality graph
 499 | 
 500 | Next to individual device data it is useful to track the connectivity between
 501 | nodes allowing an optimization, following the idea of *If you can't measure it,
 502 | you can't improve it*. It must be possible to check the health of links and the
 503 | estimated maximal achievable bandwidth between devices, all in an easily
 504 | readable graph.
 505 | 
 506 | Required information about the structure are therefore:
 507 | 
 508 | * List of nodes
 509 | * Connection between nodes (links)
 510 | * Estimated bandwidth of link
 511 | * Used interface for connection (Cable or WiFi)
 512 | 
 513 | #### Monitoring backend
 514 | 
 515 | A monitoring backend must be capable of efficiently storing metrics and offer
 516 | a convenient API to extract the data. Newly added nodes must appear
 517 | automatically in the monitoring system without any manual intervention. Also
 518 | metrics are *pulled* from the nodes by the monitoring instance rather
 519 | than *pushed* from the node to the backend. The *pull* approach offers various
 520 | advantages for this setup:
 521 | 
 522 | * Easily setup multiple monitoring instances for redundancy.
 523 | * Migration to a new monitoring machine does not require any node configuration.
 524 | * Even with a higher number of nodes, the monitoring backend won't be overloaded
 525 |   by to many incoming metrics pushed by nodes. The backend decides on its own
 526 |   when to collect metrics from nodes.
 527 | * Let the backend decide which metrics are of interest instead of receiving all
 528 |   possible metrics available[^collect].
 529 | 
 530 | This project will not cover a comparison between monitoring engines so an
 531 | established and easy to setup solution is chosen: Prometheus[^prometheusio]. It
 532 | offers the required backend to scrape nodes, store the data and offer them via
 533 | an API[^prometheus_api] or various web interfaces like Grafana[^grafana].
 534 | 
 535 | [^prometheus_package]: https://github.com/openwrt/packages/pull/5903
 536 | [^prom_service]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/
 537 | [^prom_bmx7]: https://github.com/aparcar/meshrc/tree/master/packages/prometheus-bmx7-targets
 538 | [^prometheusio]: https://prometheus.io
 539 | [^prometheus_api]: https://prometheus.io/docs/prometheus/latest/querying/api/
 540 | [^grafana]: https://prometheus.io/docs/visualization/grafana/
 541 | [^node_exporter_lua]: https://github.com/openwrt/packages/tree/master/utils/prometheus-node-exporter-lua
 542 | [^collect]: https://github.com/prometheus/node_exporter/#filtering-enabled-collectors
 543 | 
 544 | #### Monitoring web interface
 545 | 
 546 | ![meshrc Login page. All interaction, receiving monitoring data or changing
 547 | settings, requires authentication which is handled by UBUS.\label{login}](img/login.png)
 548 | 
 549 | The web interface requires an authentication to only allow administrators to
 550 | view stats and change the configuration. Instead of implementing an individual
 551 | authentication it is taking advantage of OpenWrt micro Bus system called *ubus*
 552 | [^ubus] which manages user login. The password entered in fig. \ref{login} is
 553 | send to *ubus* via the *uhttpd-mod-ubus*[^uhttpd-mod] package which allows Bus
 554 | communication over HTTP(S).
 555 | 
 556 | [^uhttpd-mod]: https://openwrt.org/packages/pkgdata/uhttpd-mod-ubus
 557 | 
 558 | ![**meshrc Graph now** - Shows the current state of the network rendered based
 559 | on the JSON output of *p2n*.\label{graph}](img/graph.png)
 560 | 
 561 | Figure \ref{graph} shows a test-bed where a total number of 11 nodes are
 562 | deployed. All nodes are running the *prometheus-node-exporter-lua* script with
 563 | the mentioned *BMX7* plugin to show their active links. Most connections work
 564 | fine and are estimated with more than 50Mbit/s bandwidth. Connections with
 565 | higher throughput are colored in purple and are likely by cable.
 566 | 
 567 | Additionally, the node *liebmann92-m5* has currently high load and is shown in
 568 | orange. This likely happens due to the use of weak hardware, not fulfilling the
 569 | minimal requirements described below, a malfunctioning application or script
 570 | causes the high load. The viewer can easily spot where further manual inspection
 571 | is required. Both nodes *rhizomia-buero* and *rhizomia-link* are currently down
 572 | and no data can be obtained. Nodes that provide uplink connectivity (gateways)
 573 | are marked with a purple border around the dot, helping the viewer to understand
 574 | the network flow.
 575 | 
 576 | ![**meshrc Overview now** - Rendered table based on the JSON output of
 577 | *p2n*.\label{overview}](img/overview.png)
 578 | 
 579 | Figure \ref{overview} shows a table with additional information about all
 580 | devices. All data monitored can be added to this table. The exact metrics of
 581 | interest should be evaluated in further practical tests and exceeds the scope of
 582 | this work.
 583 | 
 584 | ![**meshrc Overview 24 hours ago** - The NetJson was generated with the
 585 | relative timestamp `24h` to show a previous state of the network.
 586 | \label{overview-24h}](img/overview-24h.png)
 587 | 
 588 | Finally the top right corner of fig. \ref{overview-24h} is a drop-down menu
 589 | allowing to see previous states of the network, various values between 2 minutes
 590 | and 24 hours. In this test-bed some nodes were down 24 hours ago.
 591 | 
 592 | ### Configuration tool
 593 | 
 594 | The mesh configuration is limited to a very basic set of options to allow only
 595 | surfacing settings to be changed, protecting non technical users from breaking
 596 | the network. As mentioned in the project requirements above, the network must be
 597 | self configuring as much as possible.
 598 | 
 599 | #### User interface for configuration
 600 | 
 601 | Figure \ref{config} shows that the basic configuration interface only allows to
 602 | change the *mesh password* which is used for the mesh backbone connection and
 603 | the *access point password* which is used for clients. Distribution of initial
 604 | configuration can be disabled via the top left checkbox and additional SSH keys
 605 | for remote access can be set.
 606 | 
 607 | ![**meshrc Configuration** - Basic configuration is possible via the
 608 | configuration interface.\label{config}](img/config.png)
 609 | 
 610 | Also, the red *reset* button will flush all configuration on all nodes. This is
 611 | useful to bring all nodes back in a mode where they try to fetch a configuration
 612 | via a *link local* connection [@rfc42912006version p. 11]. Further details about
 613 | this are described below in the section *meshrc-initial*
 614 | \ref{initial-configuration-retrieving}. Additionally, as shown in fig.
 615 | \ref{node} it is possible to set individual settings per node, regarding the
 616 | nodes *host-name* and it is *access point name*.
 617 | 
 618 | ![**meshrc Node configuration** - Per node configuration with limited
 619 | functionality to prevent user from breaking
 620 | connectivity.\label{node}](img/node.png)
 621 | 
 622 | #### Distribution of new configurations
 623 | 
 624 | Instead of implementing a new tool to distribute data over a mesh network,
 625 | requiring also a secure way for authentication, I chose to use the existing
 626 | solution called *bmx7-sms*[^bmx7-sms]. It solves the two requirements needed:
 627 | 
 628 | * Distribute commands or configuration files to all nodes of the mesh network.
 629 | * Add authentication layer to allow nodes verifying the received command or
 630 |   configuration is legitimate.
 631 | 
 632 | All nodes of a *BMX7* based mesh network have a unique identification[^bmx7-id]
 633 | which is based on a public key pair created on first boot. All
 634 | descriptions[^bmx7-descriptions] are signed by the nodes and so are the messages
 635 | distributed by the *bmx7-sms* plugin [@neumann2016securely].
 636 | 
 637 | Badly signed messages are not accepted by nodes and thereby not distributed nor
 638 | processed. Received messages are stored in a file system containing the sending
 639 | nodes ID. Thereby it is easy to check legitimate commands by controlling if the
 640 | name of the received file starts with the ID of a trusted node.
 641 | 
 642 | An additional point of consideration is the question on how to deal with
 643 | connection breaking changes. Meaning, if for instance the *mesh password* is
 644 | changed, nodes further distanced from the initial sending nodes can no longer
 645 | communicate and thereby not receive the new password. To address this problem I
 646 | implemented a function to wait until the cloud is successfully synced.
 647 | 
 648 | [^bmx7-sms]: https://github.com/bmx-routing/bmx7#sms-plugin
 649 | [^bmx7-id]: https://github.com/bmx-routing/bmx7#global-id
 650 | [^bmx7-descriptions]: https://github.com/bmx-routing/bmx7#descriptions
 651 | 
 652 | ### Initial firmware creation
 653 | 
 654 | Nearly all router models require individual firmware images due to different
 655 | specifics like used CPU architecture and available hardware
 656 | components[^openwrt_toh]. Instead of creating preconfigured images for a
 657 | specific setup, there is an *initial firmware* which has all required packages
 658 | preinstalled and a generic configuration (\ref{lime_defaults}) with disabled
 659 | wireless radios for security reasons.
 660 | 
 661 | Obtaining the firmware can be achieved by using an online tool like Chef[^chef]
 662 | or setting up a local OpenWrt build environment[^openwrt_buildroot].
 663 | 
 664 | The section below covers the topic how a specific configuration is applied.
 665 | 
 666 | [^openwrt_buildroot]: https://openwrt.org/docs/guide-developer/build-system/install-buildsystem
 667 | [^chef]: https://chef.libremesh.org
 668 | 
 669 | ### Initial configuration
 670 | 
 671 | Changing settings in the web interface results in the creation or update of an
 672 | archive containing all configuration files. OpenWrt already uses this approach
 673 | to backup and restore configured routers[^gh_openwrt_restore].
 674 | The very same approach is performed for initial node configuration in the
 675 | following way.
 676 | 
 677 | A daemon running on the *initial firmware* checks if the node is already
 678 | configured. If not, it tries to download the node configuration archive from all
 679 | devices connected via link local. The idea behind that is, after a flash with
 680 | the plain *initial firmware* image, the device just needs to be connected via
 681 | cable to the gateway node and will automatically configure itself.
 682 | 
 683 | This allows to use a firmware image only containing a generic `lime-defaults`
 684 | configuration file \ref{lime_defaults}. A reset of the router will remove all
 685 | configurations and restart the daemon looking for an applicable configuration.
 686 | 
 687 | [^gh_openwrt_restore]: https://github.com/openwrt/luci/blob/master/modules/luci-mod-admin-mini/luasrc/controller/mini/system.lua#L18
 688 | 
 689 | \newpage
 690 | # Implementation
 691 | 
 692 | This section covers technical details on how the previously stated requirements
 693 | are implemented. As stated in req. M1 as overall paradigm it was tried to avoid
 694 | re-implementing existing software and rather combine present tools to fulfill
 695 | the task in a simple way.
 696 | 
 697 | All source code is published on GitHub.com in the `meshrc` repository
 698 | ^[https://github.com/aparcar/meshrc] and in the official OpenWrt upstream
 699 | packages ^[https://github.com/openwrt/packages/].
 700 | 
 701 | Figure \ref{toolstack} gives an overview of all implemented, ported and
 702 | extended tools and their position within the mesh network.
 703 | 
 704 | ![**Tool stack** - Tools installed on the management and gateway node or on a generic node. \label{toolstack}](img/toolstack.png)
 705 | 
 706 | ## Administrative backend
 707 | 
 708 | To allow portability on different operating systems and easy extension
 709 | without the need to be extremely performant[^performant], the web interface and
 710 | it is components are written in Python3, Shell, and JavaScript.
 711 | 
 712 | [^performant]: The code was design to never exceed $O(n)$, where $n$ is the
 713 | number of nodes. Time measurements were done with up to 100 virtual nodes
 714 | resulting in response time of a few milliseconds.
 715 | 
 716 | ### Web interface & authentication via UBUS
 717 | 
 718 | The web interface was initially planned to use the Python Web Framework
 719 | Flask^[http://flask.pocoo.org/] but was quickly replaced for pure JavaScript and
 720 | the use of OpenWrts ubus[^ubus] to minimize library dependencies and therefore
 721 | storage footprint. Also the use of a full grown JavaScript framework to generate
 722 | the web interface, apart from the graph creation, was decided against. The
 723 | current implementation is done using only basic JavaScript function and contains
 724 | in total less than 450 lines of code. To be usable on a mobile phones Twitters
 725 | Bootstrap[^web_bootstrap] is used for styling which also offers a responsive
 726 | design for mobile administration.
 727 | 
 728 | All web interface functionality is guarded by *UBUS*, meaning only after a
 729 | successful authentication it is possible to receive collected monitoring data or
 730 | execute configuration commands. This follows *req. M1* as no additional
 731 | authentication stack is implemented. After a successful login *UBUS* returns a
 732 | token which is attached to every request by the web interface. It automatically
 733 | times out five minutes after the last usage.
 734 | 
 735 | Receiving JSON data via *UBUS* simplifies the implementation as the front-end
 736 | part is entirely written in JavaScript without additional server side code. This
 737 | brings the advantage that all rendering is performed on the viewing devices
 738 | instead of the server, therefore it is also easier to scale if parts of the
 739 | monitoring data should be accessible to clients without authentication.
 740 | 
 741 | Figure \ref{seq_show_netjson} illustrates the login sequence and communication
 742 | between web interface and the backend which creates the JSON data. This and the
 743 | following sequence diagram only handles the case that the provided password was
 744 | correct. In case of bad input an error is returned by *UBUS*, brute force
 745 | attacks are handled equally to UNIX logins, with delayed responses.
 746 | 
 747 | ![**Login sequence** - The user has to provide the *root* password authenticate
 748 | in UBUS. After a successful authentication NetJson is requested from the UBUS
 749 | daemon. UBUS runs the below discussed NetJson generator *p2n* and forwards it is
 750 | output to the web interface. Via JavaScript the JSON data is rendered to HTML
 751 | and presented to the user.\label{seq_show_netjson}](img/seq_show_netsjon.png)
 752 | 
 753 | [^ubus]: https://openwrt.org/docs/techref/ubus
 754 | 
 755 | Just as for receiving monitoring data an authentication is required to change
 756 | any configuration. Again *UBUS* is used, meaning a successful login allows
 757 | seamlessly switching between checking monitoring data and applying
 758 | configurations, as the *UBUS* token works for both functionalities. The use of
 759 | *UBUS* for the configuration is shown in fig. \ref{seq_change_mesh_pw}.
 760 | 
 761 | ![**Configuration sequence** - User has to provide a valid password to login.
 762 | On success the configuration is loaded in the configuration form. To apply new
 763 | settings changed values are submitted to the UBUS daemon which then executes
 764 | the CLI. *BMX7* is requested by the CLI to distribute the new configuration
 765 | files as described
 766 | below.\label{seq_change_mesh_pw}](img/seq_change_mesh_pw.png)
 767 | 
 768 | #### Obtaining data from nodes
 769 | 
 770 | To fulfill *req I7* all nodes require a running service to parse local device
 771 | metrics and offer them in the Prometheus format[^prom_format]. This can be
 772 | achieved using an active service running on each nodes which parses device
 773 | information from places like `/proc/` and expose them on a specified port via
 774 | HTTP.
 775 | 
 776 | The tool `prometheus-node-exporter-lua` is a LUA re-implementation of the
 777 | official Prometheus `node_exporter`[^prom_exporter] and offers such
 778 | functionality compatible with Prometheus.
 779 | 
 780 | While the tool already works for device metrics, some key information are
 781 | missing to make it usable for this work. Following *req. M1* the script was
 782 | extended with additional export capabilities:
 783 | 
 784 | * `prometheus-node-exporter-lua-openwrt`[^pr_6007]: Exports installed firmware
 785 |   version and hardware model to spot outdated devices within the monitor and
 786 |   have an overview of used hardware.
 787 | 
 788 | [^pr_6007]: https://github.com/openwrt/packages/pull/6007
 789 | 
 790 | [^prom_exporter]: https://github.com/prometheus/node_exporter
 791 | 
 792 | * `prometheus-node-exporter-lua-bmx7`[^pr_bmx7_exporter]: While per device
 793 | metrics are a standard requirement for monitoring, this work needed a way to
 794 | monitor the network structure as well. The created *BMX7* plugin uses the
 795 | routing protocols JSON output stored in `/var/run/bmx7/json/` to export
 796 | connections and resource usage of the routing service. This allows to view
 797 | network development over time, how link quality changes and CPU and memory
 798 | increase during network growth.
 799 | 
 800 | * `prometheus-node-exporter-lua-textfile`[^prom_textfile]: Additionally a plugin
 801 | was created to generically export metrics from bash scripts or static text
 802 | files. This allows to monitor further metrics like node owner, sensor data or
 803 | device locations.
 804 | 
 805 | [^prom_format]: https://prometheus.io/docs/instrumenting/exposition_formats/
 806 | [^lua]: https://www.lua.org/
 807 | [^pr_bmx7_exporter]: https://github.com/openwrt/packages/pull/5578
 808 | [^prom_textfile]: https://github.com/openwrt/packages/pull/5894
 809 | 
 810 | All changes were accepted upstream and all plugins are independently  available
 811 | in the official package repository of OpenWrt, following *req. M1* and *req.
 812 | M2*.
 813 | 
 814 | #### Radio frequency separation
 815 | 
 816 | To avoid user traffic interfering with the backbone connection those frequencies
 817 | should be separated (*req. N3*) to 2.4GHz for access points and 5GHz for mesh.
 818 | This feature was not available in the LibreMesh framework so an additional
 819 | package was created called `lime-smart-wifi`[^lime-smart-wifi].
 820 | 
 821 | It scans for all attached wireless radio transmitters and checks their
 822 | capabilities (supported frequencies, transmission power and channel bandwidth).
 823 | With a simple heuristic approach it assigns roles to radio devices:
 824 | 
 825 | * **single band:** AP and mesh share the same radio.
 826 | * **dual band:** AP runs on 2.4GHz and mesh on 5GHz.
 827 | * **tri band:** like dual band but additional AP on 5GHz with different channel.
 828 | * **quad band:** dual AP and mesh each on different frequency and channel.
 829 | 
 830 | The tool chooses channels with maximum distance for minimal interference.
 831 | 
 832 | During the creation of this project the *hostapd*[^hostapd_web] daemon did not
 833 | support to run an encrypted mesh and an encrypted AP on the same radio.
 834 | Therefore the package is also required to obey *req. N2*.
 835 | 
 836 | As the package has no dependencies apart from the LibreMesh framework it is
 837 | usable independently of this works software stack (*req M2*).
 838 | 
 839 | #### Porting Prometheus to OpenWrt Buildroot
 840 | 
 841 | To allow an easy installation (*req. I2*) of Prometheus on OpenWrt an
 842 | architecture specific package is required.
 843 | 
 844 | The OpenWrt operating system manages all packages in a public Git repository. It
 845 | stores per package a Makefile containing all information required for creation.
 846 | So called Buildbots automatically download the git repositories and containing
 847 | Makefiles and compile the packages, resulting in the official package
 848 | feeds[^owrt_packages]. It is important that code is cross compiled which means
 849 | to be compiled on a different architecture than eventually run. This is
 850 | necessary as most routing devices use other architectures than
 851 | x86[^openwrt_toh].
 852 | 
 853 | OpenWrt Buildroot can compile various programming languages to run on targeted
 854 | devices. The support for Go[^golang] was added in May 2018[^np_go] and so allows
 855 | porting Prometheus to OpenWrt.
 856 | 
 857 | [^golang]: https://golang.org/
 858 | [^np_go]: https://github.com/openwrt/packages/pull/5780
 859 | 
 860 | Therefore the Prometheus package was ported within this
 861 | project[^prometheus_package]. It required to understand the newly introduced
 862 | features of OpenWrt's Buildroot to be compatible with the Buildbots (*req. 1*).
 863 | 
 864 | [^owrt_packages]: https://downloads.openwrt.org/snapshots/packages/
 865 | 
 866 | #### Network visualization with NetJson
 867 | 
 868 | Looking for tools to visualize network graphs, especially in the field of mesh
 869 | networks, the only viable tool was NetjsonGraph.js [^gh_netjsonjs]. The graph
 870 | framework uses the data format NetJson^[https://netjson.org] as input data and
 871 | shows an interactive graph with additional metrics, zooming and dragging
 872 | capabilities.
 873 | 
 874 | NetJson is a format designed for network statistics. It also allows the handling
 875 | of connections between devices[^netjson_links] which are then visualized by
 876 | NetjsonGraph.js.
 877 | 
 878 | As written earlier within the design decisions \ref{design-decisions},
 879 | Prometheus is used for device monitoring. While it offers an API to read stored
 880 | metrics, the file format is insufficiently to directly use it as input for a
 881 | bidirectional graph.
 882 | 
 883 | For this work the tool Prometheus2NetJson (*p2n*)[^p2n] was created. It outputs
 884 | valid NetJson containing all nodes with collected metrics as well as all links
 885 | and their quality. On execution *p2n* connects to a configured Prometheus
 886 | instance and performs various API requests to collect all desired data. The
 887 | received metrics are then merged into a single NetJson file. Next, the output is
 888 | used by NetjsonGraph.js[^graph_netjson] and the overview table.
 889 | 
 890 | To show the link quality between devices the NetjsonGraph.js framework
 891 | was extended to colorize the edge connection nodes depending on estimated
 892 | throughput[^graph_quality].
 893 | 
 894 | Additionally *p2n* can take a time input as relative time delta, specific time
 895 | in the Unix time stamp format or following RFC3339 [@klyne2002rfc]. This enables
 896 | to create NetJson of any time in the past, allowing to visualize development of
 897 | the network.
 898 | 
 899 | For the overview page the generated NetJson is interpreted and visualized in a
 900 | table. The visualization of the graph and table is done in both cases via
 901 | JavaScript relieving the monitoring node from render the actual output. This
 902 | implementation allows a modular use of the  interface even for other NetJson
 903 | files not produced by *p2n*.
 904 | 
 905 | [^gh_netjsonjs]: https://github.com/netjson/netjsongraph.js
 906 | [^netjson_links]: http://netjson.org/#third/1
 907 | [^p2n]: https://github.com/aparcar/meshrc/blob/master/packages/meshrc/files/web/usr/bin/p2n
 908 | [^graph_quality]: https://github.com/aparcar/meshrc/blob/master/packages/meshrc/files/web/www/meshrc/static/css/netjsongraph-theme.css#L196
 909 | [^graph_netjson]: https://github.com/aparcar/meshrc/blob/master/meshrc/templates/graph.html#L102
 910 | [^web_bootstrap]: https://getbootstrap.com/
 911 | 
 912 | #### Automatic monitoring of new nodes
 913 | 
 914 | Prometheus supports various ways for service discovery[^prom_service] meaning to
 915 | automatically add monitored targets after creation. Until now there was no
 916 | solution for automatically monitoring (*req. I4*) of all devices of a mesh
 917 | network based on the routing protocol *BMX7*. The package
 918 | `prometheus-bmx7-targets`[^prom_targets] was created to automatically add *BMX7*
 919 | nodes to a file readable by the Prometheus instance[^prom_bmx7]. A minimal
 920 | configuration for Prometheus is attached below in \ref{prom_config}.
 921 | 
 922 | [^prom_targets]: https://github.com/aparcar/meshrc/tree/master/packages/prometheus-bmx7-targets
 923 | 
 924 | To work the `bmx7-json` plugin[^bmx7-json] is enabled which creates JSON files
 925 | containing status information of the running *BMX7* daemon. The created tool
 926 | monitors changes via `inotifywait`^[https://linux.die.net/man/1/inotifywait].
 927 | Concretely it scans the folder `/var/run/bmx7/json/originators/` where status
 928 | information of all *BMX7* nodes of the network are stored. The wait command
 929 | blocks until a file (node) is added or removed. Once unblocked, the output file
 930 | containing Prometheus targets is updated and `inotifywait` blocks again until
 931 | another change of connected nodes happens[^prom-bmx7-targets]. Prometheus
 932 | detects changes to the target file automatically and starts scraping new
 933 | entries.
 934 | 
 935 | [^prom-bmx7-targets]: https://github.com/aparcar/meshrc/blob/master/packages/prometheus-bmx7-targets/files/usr/bin/prometheus-bmx7-targets
 936 | [^bmx7-json]: https://github.com/bmx-routing/bmx7#json-plugin
 937 | 
 938 | #### Synchronize cloud via `cloud sync`
 939 | 
 940 | When changing connection disruptive commands like change of the mesh ID or key,
 941 | it is important to happen on all nodes at the same time. If a single node misses
 942 | the new configuration it is lost with outdated configurations, no longer being
 943 | able to connect.
 944 | 
 945 | The current implementation distributes a *SMS* of the form
 946 | `<received_command>-ack` to all other nodes, stating its acknowledgement of the
 947 | command. On receiving an `ack` from another node, the node compares the list of
 948 | known nodes with the list of received acknowledgments. Once both lists are
 949 | equal the node executes the received command. This process is illustrated in
 950 | fig. \ref{cloud_sync}.
 951 | 
 952 | ![**Cloud sync visualization**\label{cloud_sync}](img/cloud-sync-steps.png)
 953 | 
 954 | ## Initial configuration retrieving
 955 | 
 956 | To distribute the *initial configuration* the gateway node has to install
 957 | *meshrc-web*. Changing settings in the web interface sends the configuration to
 958 | connected nodes and also updates a locally stored archive containing these
 959 | settings and offer it via a web server to directly connected devices.
 960 | 
 961 | Unconfigured nodes try to find all directly connected neighbors of the *LAN*
 962 | bridge (`br-lan`). It is scanned via an IPv6 broadcast ping^[`ping6 -I br-lan
 963 | ff02::1`]. The *meshrc-initial* daemon tries to download a file called
 964 | *config.tar.gz* from all found neighbors. In case the config archive was
 965 | downloaded successfully, it is extracted to the devices file system root and a
 966 | reboot performed after which all settings are activated.
 967 | 
 968 | As the `link-local` address [@hinden2006ip pp. 11] is used only directly
 969 | connected nodes can download the archive and no regular IP addresses are
 970 | required. This implementation prevents external parties from accessing the
 971 | archive containing passwords only making it accessible to users which have
 972 | hardware access to the gateway node.
 973 | 
 974 | ## Usage of `bmx7-sms` plugin for configuration
 975 | 
 976 | All nodes setup with the *initial configuration* automatically trust the *BMX7*
 977 | ID of the node they received the configuration from.
 978 | 
 979 | An ID could look like `F28A940935AA41D9019476FB397913CB45D798B593AD45544DBDC33A`
 980 | which is the SHA224 hash of the nodes public key.
 981 | 
 982 | Files distributed via the `bmx7-sms` plugin are prefixed with this ID, so a file
 983 | `mesh` becomes 
 984 | \newline
 985 | `F28A940935AA41D9019476FB397913CB45D798B593AD45544DBDC33A:mesh` and is stored on
 986 | all other nodes in `/var/run/bmx7/sms/rcvdSms/`. If a node tries to fake the ID
 987 | of another (maybe known to be trusted) node the spoof will fail due to the fact
 988 | that the faking node is not in possession of the real node's private key, which
 989 | is required to sign the distributed file. Badly signed files are deleted by
 990 | surrounding nodes and not further distributed to the mesh.
 991 | 
 992 | It is trivial to scan the previously mentioned folder for files starting with one
 993 | of the *trusted* IDs. In case of a match, the file name and content is examined
 994 | and processed.
 995 | 
 996 | The following list shows all supported commands distributed as file. The file
 997 | content is used as value for the command. It distinguishes between two filename
 998 | prefixes for LibreMesh specific commands `lm-*` and raw commands `rc-*`. The
 999 | former only change the framework file `/etc/config/lime` and applies the changes
1000 | via `lime-config && lime-apply` while the latter run the command directly on the
1001 | node.
1002 | 
1003 | Currently the following list of functions is implemented:
1004 | 
1005 | * `lm-hn_<short_id>`: Set Hostname of specific node with `<short_id>`.
1006 | * `lm-mk`: Set the mesh password (key) used by the backbone network.
1007 | * `lm-mi`: Set the mesh ID used by the backbone network.
1008 | * `lm-ak`: Set nodes access point password (key).
1009 | * `rc-rst`: Resets nodes to the state of the *initial firmware*.
1010 | * `rc-ssh`: Set the ssh keys allowed to login as root.
1011 | 
1012 | For all of the above commands it is possible to append `_<short_id>` to the
1013 | filename so it is only executed on the specific node. Notable that changing the
1014 | Mesh ID or key of a single node would result in connection loss.
1015 | 
1016 | As of commit
1017 | `9883383`^[https://github.com/bmx-routing/bmx7/blob/9883383dc26df16da67b9ef7ba99efe62f79c4e7/lib/bmx7_sms/sms.h#L25]
1018 | the `bmx7-sms` plugin only supports filenames up to a length of 16 characters.
1019 | This can result in confusion if implementing own commands.
1020 | 
1021 | ## IP address collision avoidance
1022 | 
1023 | Following *req. N1* all nodes must automatically choose a IPv4 subnetwork from
1024 | which they offers addresses to connecting clients. The IPv4 addresses must not
1025 | overlap as the routing protocol wouldn't know which node handles the subnetwork.
1026 | Per
1027 | default^[https://github.com/libremesh/lime-packages/blob/develop/packages/lime-system/files/usr/lib/lua/lime/network.lua#L41]
1028 | LibreMesh tries to avoid IP collision by picking pseudo random data, like the
1029 | MD5 hash of the used AP name. While this works, the devices IP address changes
1030 | every time the AP name changes. To avoid this, an additional parameter, which
1031 | uses a MD5 hash of the primary MAC address, was implemented for this project.
1032 | This results in an equally small chance of collision but keeps a static address
1033 | for each device. The
1034 | changes^[https://github.com/libremesh/lime-packages/pull/349] were accepted
1035 | upstream.
1036 | 
1037 | The attached `lime-defaults` configuration file \ref{lime_defaults} uses `10.%m1.%m2.1/24` which
1038 | results in a collision probability of $n/(256^2)$ where $n$ is the number of
1039 | used nodes.
1040 | 
1041 | ## Alerts in case of malfunction
1042 | 
1043 | Adding alert support when using Prometheus is fairly trivial. The attached
1044 | configuration file \ref{prom_rules} sends an alert in the following three cases:
1045 | 
1046 | * `node_down`: A previously connected node is offline for more than 10 minutes.
1047 | 	* Indicating device failure.
1048 | * `node_high_load`: The average load of the last 15 minutes is over 1.0.
1049 | 	* Indicating a bottleneck or software malfunction.
1050 | * `link_bad_quality`: Estimated link quality between two nodes is under 10Mbit
1051 |   for 10 minutes.
1052 |   	* Indicating an obstacle may started to block direct line of sight or
1053 | 	  antenna malfunction.
1054 | 
1055 | The alert system can use any metric collected by Prometheus and so can easily be
1056 | extended to custom needs[^prom_alert_config] in other use cases (*req. M2*).
1057 | 
1058 | [^prom_alert_config]: https://prometheus.io/docs/alerting/configuration/
1059 | 
1060 | \newpage
1061 | # Collaboration
1062 | 
1063 | This work exists due to the collaboration with multiple individuals and
1064 | communities working on various aspects in the area of mesh technologies.
1065 | Instead of reinventing existing solutions for the initially described project
1066 | requirements, I decided to evaluate established approaches and extend their
1067 | functionality if possible to fit the stated needs.
1068 | 
1069 | ## LibreMesh extension and fixing
1070 | 
1071 | As explained before in the section design decisions \ref{design-decisions} I
1072 | worked in various areas[^gh_lime_aparcar] of LibreMesh[^libremesh_website] and
1073 | added multiple features or fixed existing bugs.
1074 | 
1075 | The most important bug fix regarding this project was the fixing of interface
1076 | detection of *BMX7*^[https://github.com/libremesh/lime-packages/issues/335]. To
1077 | successfully estimate the possible bandwidth of a network interface *BMX7* has
1078 | to know about the nature of the interface (cable or wireless). Before the fixing
1079 | patch [^gh_interface_patch] all wireless interfaces would be interpreted as a
1080 | cable and wrongly diagnosed with full Gigabit bandwidth making monitoring of
1081 | link quality useless.
1082 | 
1083 | [^gh_interface_patch]: https://github.com/bmx-routing/bmx7/pull/12
1084 | 
1085 | ## Encrypted mesh networks
1086 | 
1087 | Started with an issue on GitHub[^gh_crypt_mesh] regarding an encrypted mesh
1088 | network the OpenWrt core developer Daniel Golle[^gh_dango] and me started to
1089 | investigate the problem together. With various tests and bug fixes in an
1090 | especially for this issue setup test-bed, we eventually created a working
1091 | version and closed the initial issue. This also showed the path for the backbone
1092 | encryption of this project.
1093 | 
1094 | [^gh_crypt_mesh]: https://github.com/libremesh/lime-packages/issues/208
1095 | [^gh_dango]: https://github.com/openwrt/openwrt/commits?author=dangowrt
1096 | 
1097 | ## Working at the UPC Barcelona
1098 | 
1099 | During my exchange semester in Barcelona I could highly benefit from the
1100 | collaboration with the network laboratory at the UPC[^upc_web]. Thanks to it is
1101 | members I could setup a test-bed to evaluate initial ideas for the
1102 | implementation. Also I could discuss there various features and drawbacks of
1103 | LibreMesh and the Quick Mesh Project[^qmp_web].
1104 | 
1105 | Members of the community project Guifi.net[^guifi_web] offered insights in their
1106 | mesh setups and I had the chance to discuss various requirements for a useful
1107 | monitoring solution. Furthermore I got the chance to run the software created
1108 | within this project on various networks to have a more complex test-bed.
1109 | 
1110 | [^gh_lime_aparcar]: https://github.com/libremesh/lime-packages/commits?author=aparcar
1111 | [^libremesh_website]: https://libremesh.org
1112 | [^upc_web]: https://upc.edu
1113 | [^qmp_web]: https://qmp.cat
1114 | [^guifi_web]: https://guifi.net
1115 | [^lime-smart-wifi]: https://github.com/libremesh/lime-packages/pull/321
1116 | [^hostapd_web]: https://w1.fi/
1117 | [^dfs]: http://wifi-insider.com/wlan/dfs.htm
1118 | 
1119 | \newpage
1120 | # Evaluation
1121 | 
1122 | After implementing an initial prototype of the software stack it was iteratively
1123 | evaluated and checked for functionality. This section consists of two parts, the
1124 | summary of the monitoring and the management part.
1125 | 
1126 | The former was tested within an actively used mesh network while the latter
1127 | could only be tested in a test-bed with perfect conditions due to the lack of
1128 | hardware and location changes.
1129 | 
1130 | ## Monitoring evaluation
1131 | 
1132 | In various parts of Leipzig exists mesh infrastructure handled by
1133 | Freifunk[^ff_leipzig] and a wireless internet service provider[^reudnetz]. The
1134 | monitoring system  was installed on parts of this infrastructure as it is not
1135 | putting the devices connectivity at risk. It merely requires adding the read
1136 | only exporter per device. The underlying mesh routing protocol used in the
1137 | network was already *BMX7*, so no additional configuration was required.
1138 | 
1139 | The figures \ref{graph}, \ref{overview} and \ref{overview-24h} are screenshots
1140 | of the *meshrc* interface running in the previously described network. Collected
1141 | data is consistent with manually gathered information, therefore the output can
1142 | be considered valid.
1143 | 
1144 | As fig. \ref{overview} shows the network consists of various devices, partly
1145 | used for the backbone connections (*Loco M XW* and *Nanostation M XW*), access
1146 | points (*TL-WDR3600*) or both (*ZBT-WG3426*).  Devices are connected as shown in
1147 | fig. \ref{graph} where backbone distances vary between 100 and 2000 meters.
1148 | 
1149 | This shows a shortcoming of the current monitoring approach as the distances
1150 | between devices are not visualized. The metric is not available and so could not
1151 | be implemented. However a future version of the monitoring view could be
1152 | extended to handle the metric if available or calculate distances based on
1153 | locations provided by a static file containing location coordinates.
1154 | 
1155 | While setting up the monitoring system a high load on node *liebmann92-m5* was
1156 | discovered and investigated. A bug of the LibreMesh firmware caused on that
1157 | device the constant crash and reload of a service, resulting in high CPU usage.
1158 | The malfunction later was fixed normalizing the load. A case like this document
1159 | the need for an active monitoring system.
1160 | 
1161 | ### Resource requirements for monitoring
1162 | 
1163 | ![Unix tool `htop` shows memory and CPU usage of running Prometheus instance on monitoring node.\label{htop}](img/htop-prometheus.png)
1164 | 
1165 | Figure \ref{htop} shows the low resource footprint of the running Prometheus
1166 | instance. As shown, it uses less than 20% of the 240 MByte available memory,
1167 | meaning under 50 MByte for the Prometheus process. This allows to use small
1168 | embedded devices like the Raspberry Pi [^rpibplus] to act as the monitoring node
1169 | and does not require a real server setup.
1170 | 
1171 | This value was captured with only a single instance of the monitoring web
1172 | interface opened and only 11 nodes participating in the network. Further
1173 | research has to show the resource usage of the Prometheus process in a growing
1174 | mesh network. Fortunately Prometheus offers to monitor its own resource usage as
1175 | well, allowing to easily compare it to the  number of monitored nodes.
1176 | 
1177 | Beneath the monitoring service the data is aggregated by the *p2n* script which
1178 | runtime naturally increases with the number of nodes. It is designed to run in
1179 | $O(n)$ and should therefore be scaleable with higher numbers of nodes.
1180 | 
1181 | A test with the test-bed described above however showed an unexpected long time
1182 | for the NetJson creation.
1183 | 
1184 | ```bash
1185 | root@rdntz-gateway:~# time p2n > /dev/null
1186 | real    0m 0.51s
1187 | user    0m 0.45s
1188 | sys     0m 0.02s
1189 | ```
1190 | 
1191 | In the current implementation of *p2n* all metrics are serially retrieved which
1192 | is performed via a `localhost` HTTP API request. Establishing the connection
1193 | does significantly slow down the response, meaning more nodes would affect
1194 | response time less than additional metrics. One could gather all metrics in
1195 | parallel and use additional caching to stop unnecessary recreation of the
1196 | NetJson output.
1197 | 
1198 | [^rpibplus]: https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/
1199 | 
1200 | [^ff_leipzig]: https://leipzig.freifunk.net
1201 | [^reudnetz]: https://reudnetz.org
1202 | 
1203 | ## Management evaluation
1204 | 
1205 | Due to a location change and the fact that the mesh network in Leipzig was
1206 | actively in use, it was not feasible to test and improve the management part
1207 | there. For that reason a small test-bed was created allowing the evaluation of
1208 | the control instance. It consisted of the previously mentioned **Raspberry
1209 | Pi**[^rpibplus] (Pi) and three **Buffalo WSR-1166DHP** routers. The *Pi* was
1210 | used to monitor and control the network while the routers formed a partly wired
1211 | and partly wireless mesh network. Hardware choice was made based on availability
1212 | in Tokyo, Japan, low price and compatibility with Prometheus, OpenWrt and the
1213 | *802.11s* mesh mode.
1214 | 
1215 | ![**Management test-bed** using 4 devices connected wired and
1216 | wireless.\label{mgmt-testbed}](img/mgmt-testbed.png)
1217 | 
1218 | The test-bed was setup as illustrated in fig. \ref{mgmt-testbed}, with distances
1219 | of only a few meters. As the *Pi* features only a single LAN port it is not
1220 | suitable as a gateway. As a replacement one of the nodes was used as gateway
1221 | which is seamlessly possible due to LibreMesh's automatic configuration. Due to
1222 | the combination of wireless and wired combination the distance between the
1223 | management node *Pi* and the last *Buffalo* node connected to the Internet has
1224 | as many hops (nodes in between) as possible, which gives a slightly more
1225 | realistic test-bed.
1226 | 
1227 | ### Initial node setup
1228 | 
1229 | Firstly the initial configuration (*req. N1*) via the package `meshrc-initial`
1230 | was tested. A generic image was created which would not setup any wireless
1231 | connections, instead searching for a node connected via cable to retrieve an
1232 | initial configuration. This step worked flawlessly as once a node was connected
1233 | to the *Pi* it instantly downloaded the configuration, applied it and rebooted.
1234 | The reboot let routers LED's flash which signals implying configuration
1235 | retrieval was successful.
1236 | 
1237 | \newpage
1238 | \lstinputlisting[caption=Example of initial config download.]{flash.txt}
1239 | 
1240 | Below log paste shows how a node finds two neighbors (MAC addresses substituted)
1241 | and tries to download the configuration. The second node is the *Pi*. All three
1242 | devices are connected via cable.
1243 | 
1244 | Changing option in the management interface fig. \ref{config} instantly updated
1245 | the archive containing all settings and started also to distribute it over
1246 | *BMX7*. This ensures that new initialized nodes as well as already setup nodes
1247 | contain the same configurations.
1248 | 
1249 | ### Testing the `cloud-sync` feature
1250 | 
1251 | Due to the small test-bed and perfect conditions regarding connectivity only
1252 | limited tests were possible. However, stopping a node manually from sending a
1253 | command acknowledgment lets other nodes wait, which is the intended behavior.
1254 | Once the *ack* is sent, other nodes apply the new settings.
1255 | 
1256 | The testing however brought up the difficulty of *split brain* prevention, a
1257 | state where a distributed system is unintentionally clustered due to disparate
1258 | states of configuration. In this case, the `cloud-sync` feature acknowledges the
1259 | successfully received configuration, however the distribution of acknowledgments
1260 | is no further verified. Meaning, a node could reboot before it distributed other
1261 | nodes acknowledgments, resulting in other nodes to infinitely wait for missing
1262 | *acks*. To work around this issue, the current implementation starts a timer
1263 | once all acknowledgments are received, taking for granted that all nodes are
1264 | reachable as they sent an *ack*. During the countdown ticking, *acks* are
1265 | further distributed, assume all nodes received all *acks* within the countdown.
1266 | 
1267 | As *BMX7* rapidly forwards received configurations a short countdown of 5
1268 | seconds were chosen, however this should be further evaluated in a real test-bed
1269 | with more devices.
1270 | 
1271 | ### LibreMesh with encrypted mesh
1272 | 
1273 | As LibreMesh is an established framework it mostly worked as excepted and the
1274 | biggest extension of functionality in the package `lime-smart-wifi` was the
1275 | possibility to encrypted mesh connection (*req. N2*). It turned out to perform
1276 | very well with a stable connection and no immense performance drawback.
1277 | 
1278 | Only additional node is the initial connection time. As both nodes communicate
1279 | encrypted they have to exchange a secret via a Diffie–Hellman key exchange,
1280 | resulting in extra calculation before the connection to another node is
1281 | established. Depending on the node's computation power, this can take up to a
1282 | minute, while unencrypted mesh connections are nearly instantly ready.
1283 | 
1284 | \newpage
1285 | # Conclusion
1286 | 
1287 | All initially set requirements where fulfilled and so the work should be seen as
1288 | successful! It is usable for the target group and flexible enough to extend it
1289 | to additional needs. During the development and collaboration with community
1290 | network, some already stated interest to use the software.
1291 | 
1292 | ## Solved project requirements
1293 | 
1294 | * req. N1 **Zero-Conf Setup:** Extended via the creation of *initial
1295 |   configurations* which are generically included in all created firmware
1296 | images.^[https://github.com/libremesh/network-profiles/tree/master/meshrc/node]
1297 | 
1298 | * req. N2 **Encryption:** Within this project the SAE encryption of
1299 |   *802.11s* [@tan2013security pp. 17-19] connections were exceedingly tested in
1300 |   various test-bed setups and reached an usable state.
1301 | 
1302 | * req. N3 **Frequency separation:** The newly
1303 |   `lime-smart-wifi`^[https://github.com/libremesh/lime-packages/tree/develop/packages/lime-smart-wifi]
1304 |   package separates the frequency used by the access points from the one used by
1305 |   the mesh backbone connection.
1306 | 
1307 | * req. N4 **Simple setup:** All created tools for the monitoring  are
1308 |   installable via the `opkg`[^opkg].
1309 | 
1310 | [^opkg]: https://openwrt.org/docs/guide-user/additional-software/opkg
1311 | 
1312 | * req. I1 **Limited access:** Fulfilled by using OpenWrt authentication system
1313 |   via *ubus*.
1314 | 
1315 | * req. I2 **Simple setup:** Feasible installable via an *opkg* package.
1316 | 
1317 | * req. I3 **Network graph:** Implemented via the `meshrc-web` package and
1318 |   NetJsonGraph.js.
1319 | 
1320 | * req. I4 **Automatic monitoring:** Implemented via the
1321 |   `prometheus-bmx7-targets` package.
1322 | 
1323 | * req. I5 **Alerts:** Possible via the ported `prometheus-alertmanager` package.
1324 |   The alert manager requires individual configuration based on the desired
1325 |   notification
1326 |   channel^[https://prometheus.io/docs/alerting/configuration/#%3Cemail_config%3E].
1327 | 
1328 | * req. I6 **Network configuration:** Implemented via the `meshrc-cli` and
1329 |   `meshrc-web` package.
1330 | 
1331 | ## Created, extended and ported packages
1332 | 
1333 | Here is a list of software which was created, extended or ported by me. I'd like
1334 | to emphasize the work on the extending and porting part, as it required to learn
1335 | new programming languages and to understand building environments and processes.
1336 | 
1337 | ### Package creation
1338 | 
1339 | The web front-end is (apart from the NetjsonGraph.js library) a new created
1340 | code.  It was packed to be installable via the OpenWrt package manger called
1341 | `opkg`.
1342 | 
1343 | * `meshrc-web`: Web interface giving an overview of the network and allowing the
1344 |   configuration of various parameters.
1345 | 
1346 | * `meshrc-cli`: Command line interface which is used by the web interface.
1347 |   Allowing more detailed configuration of nodes. Also used for the distribution
1348 |   of the *initial configurations*.
1349 | 
1350 | * `meshrc-client`: Daemon to be run on clients which checks for incoming
1351 |   commands and executes them.
1352 | 
1353 | * `meshrc-initital`: Daemon to be run on clients which automatically download
1354 |   and setup an *initial configuration* which is supplied by the `meshrc-cli`.
1355 | 
1356 | * `prometheus-bmx7-targets`: Automatically adds active nodes of a *BMX7* mesh as
1357 |   targets to a running *Prometheus* instance.
1358 | 
1359 | ### Package extension
1360 | 
1361 | In the development branch of OpenWrt already existed a tool called
1362 | `prometheus-node-exporter-lua` which was missing some features required for this
1363 | project. The functionality was extended and the created code will be available
1364 | in the next stable release of OpenWrt.
1365 | 
1366 | * `prometheus-node-exporter-lua-bmx7`: Exports *BMX7* related metrics like
1367 |   active links, CPU & memory usage of the `bmx7` daemon and loaded plugins.
1368 | 
1369 | * `prometheus-node-exporter-lua-textfile`: Exports content of existing text
1370 |   files already in a *Prometheus* compatible format. Uses a generic way to
1371 |   export output of shell scripts or static information like node locations
1372 |   coordinates.
1373 | 
1374 | * `prometheus-node-exporter-lua-openwrt`: Exports OpenWrt specific metrics like
1375 |   currently installed OS release and node model.
1376 | 
1377 | ### Package porting
1378 | 
1379 | As Prometheus is written in Go, it is possible to run it on various devices if
1380 | the binary package was specially compiled for that architecture. Normally the
1381 | architecture specific compilation is done by the OpenWrt Buildroot[^buildroot],
1382 | but until May 2018 no Go code compiling was available[^no_go].
1383 | 
1384 | [^buildroot]: https://wiki.openwrt.org/doc/techref/buildroot
1385 | [^no_go]: https://github.com/openwrt/packages/pull/5780
1386 | 
1387 | After support became available I ported Prometheus and the alertmanger to
1388 | OpenWrt, adapting to the new build methods[^prom_port]:
1389 | 
1390 | * `prometheus`
1391 | * `prometeus-alertmanager`
1392 | 
1393 | [^prom_port]: https://github.com/openwrt/packages/pull/5903
1394 | 
1395 | ## Projects drawbacks and limits
1396 | 
1397 | Even though I could implement previously stated requirements, during the process
1398 | I recognized various flaws of the design decisions \ref{design-decisions} which
1399 | are shortly covered in the following sections.
1400 | 
1401 | ### Plain text configuration
1402 | 
1403 | With the current configuration approach all commands, including passwords, are
1404 | sent unencrypted to all nodes of the network. It is within this project's design
1405 | as the mesh network requires an authentication to participate. However the
1406 | current approach wouldn't be suitable for bigger network where multiple *mesh
1407 | clouds* are connected, sharing an uplink connection, but are managed by
1408 | different individuals or communities. Within the scope of this project this is
1409 | not a problem due to mesh encryption.
1410 | 
1411 | ### No roaming support between devices
1412 | 
1413 | Moving as a client between access points results in a short loss of connection
1414 | as the clients requests a new IP from the newly connected access point. While
1415 | for web browsing this shouldn't be a problem, VoIP telecommunication might be
1416 | disrupted.
1417 | 
1418 | The LibreMesh framework offers a roaming solution for that by using B.A.T.M.A.N
1419 | Advanced[^batman_adv] (batadv).  While the use of *batadv* with *BMX7* is
1420 | possible, it is currently insufficient tested. Further work may provide a working
1421 | setup including *BMX7* and *batadv* for full roaming support.
1422 | 
1423 | Another approach could be the use of Mobile IPv6 [@perkins2011mobility], using
1424 | the *gateway node* as *Home Agent*. However, this requires further research,
1425 | implementation and by far exceeds the projects scope.
1426 | 
1427 | [^batman_adv]: https://www.open-mesh.org/projects/batman-adv/wiki/Doc-overview
1428 | 
1429 | ### Complicated initial router flash
1430 | 
1431 | As this project does not use specialized hardware, the preinstalled software is
1432 | not suitable to be used in a mesh setup. A custom firmware flash is required,
1433 | which requires specific device knowledge and is usually not generically
1434 | possible.
1435 | 
1436 | ![Serial connection with bricked router.\label{serial}](img/serial.jpg)
1437 | 
1438 | Figure \ref{serial} shows a router which struck a power cut during firmware
1439 | flashing. The router wasn't able to boot anymore and so was opened to connect a
1440 | serial console to directly enter commands without the need of a working network
1441 | connection.
1442 | 
1443 | A possible solution would be to focus device homogeneity in a mesh setup or use
1444 | specialized hardware with the mesh framework LibreMesh
1445 | preinstalled[^librerouter].
1446 | 
1447 | ### Insecure connection to configuration interface
1448 | 
1449 | While this project solved authenticated configuration of mesh nodes, the
1450 | configuration between the administrators device and the gateway running the
1451 | configuration web interface is unencrypted. With the current software a secure
1452 | connection can still be used by establishing secure shell connection (*SSH*)
1453 | with port forwarding to the gateway node.
1454 | 
1455 | ### BMX7 dependencies
1456 | 
1457 | The entire project is build around the routing protocol *BMX7* which creates a
1458 | strong dependence on exactly this software. As mentioned earlier there are
1459 | various routing protocols, which may outperform the current choice. All created
1460 | tools, however, depend on *BMX7* JSON output and its API.
1461 | 
1462 | Future versions could be designed in a more flexible way, just like the
1463 | *LibreMesh* framework itself.
1464 | 
1465 | ### No IPv6 connectivity for clients
1466 | 
1467 | The current implementation does not offer the handling of IPv6 addresses for
1468 | clients. While IPv6 should be granted in today's network, it is a long standing
1469 | issue of the LibreMesh
1470 | distribution^[https://github.com/libremesh/lime-packages/pull/71]. Therefore it
1471 | would exceed the scope of this work and will be tackled apart from this work.
1472 | 
1473 | ## Outlook
1474 | 
1475 | This project can be seen as an advanced proof of concept. It is functional and
1476 | fulfills the initial's goals. However, various rough edges could be improved and
1477 | are shortly explained in the following.
1478 | 
1479 | ### Interface design
1480 | 
1481 | Based on practical experiences the web interface could be extended to show a
1482 | better collection of metrics, helping network administrators to maintain the
1483 | network in an easier fashion. This could happen in cooperation with the authors
1484 | of previous works [@centelles2015enhancing] [@cerda2013experimental].
1485 | 
1486 | ### Grafana to visualize metric graphs
1487 | 
1488 | The current overview offers a specific time frame of metrics, but lacks an over
1489 | time view. Grafans graphs could be embedded into the current interface, a quick
1490 | illustration for a possible output in Figure \ref{grafana}.
1491 | 
1492 | ![Graph created by Grafana shows gateway traffic over time.\label{grafana}](img/grafana.png)
1493 | 
1494 | ### Test scalability of routing BMX7
1495 | 
1496 | It is possible to see the CPU and memory usage of the running mesh routing
1497 | protocol *BMX7* process. The resource usage of the routing daemon can be
1498 | monitored and the limitation of scalability can be estimated. This is especially
1499 | useful with historical information about the number of links and nodes.
1500 | 
1501 | ### Sensor network
1502 | 
1503 | Using the `prometheus-node-exporter-lua-textfile` daemon allows to monitor
1504 | generically any floating point based metric and the delivery of labels
1505 | containing text information. The project could be extended to be used in a
1506 | sensor network tracking data like air quality or car traffic.
1507 | 
1508 | ### Encrypted transport layer
1509 | 
1510 | While the wireless connection between nodes is encrypted, the tunnels created by
1511 | the routing protocol to connect nodes are unencrypted, allowing evil nodes to
1512 | spy on forwarded traffic. This prevents the current network setup from being
1513 | open, to allow others to participate in the mesh, while staying secure. A
1514 | possible solution is the use of Wireguard [@donenfeld2017wireguard] allowing
1515 | encrypted peer to peer connections. The setup would define a trusted gateway,
1516 | where all clients nodes establish a encrypted connection to. From this point on,
1517 | no node can eavesdrop and so the network can be opened to non-self-controlled
1518 | nodes.
1519 | 
1520 | ### Opportunistically encrypted open hotspots
1521 | 
1522 | Currently both the mesh connection as well as the AP is encrypted to provide
1523 | secure data transportation for connected users. While the previously mentioned
1524 | encrypted transport layer could open the former, the AP must remain encrypted
1525 | to prevent attackers from monitoring users traffic. This approach requires
1526 | authentication and thereby a password - disallowing open hotspots.
1527 | 
1528 | A possible solution to provide open hotspots and encrypted wireless connections
1529 | is the newly introduced *Opportunistic Wireless Encryption* [@harkins2017rfc],
1530 | which could solve this in the future.
1531 | 
1532 | ### Modular configuration distribution
1533 | 
1534 | To avoid the dependence on `bmx7-sms` the configuration distribution should be
1535 | implemented in a more modular way, allowing the usage of other mesh routing
1536 | protocols. Two different ways are possible:
1537 | 
1538 | * The tool *Alfred*[^web_alfred] allows distribution of arbitral data within a
1539 |   mesh network without relying on a specific routing protocol.
1540 | * A central server (within the mesh network) which is periodically polled by
1541 |   nodes for new configurations.
1542 | 
1543 | Both approaches lack authentication of received configuration files. To counter
1544 | this lack it is possible to use *usign*[^git_usign], which comes preinstalled on
1545 | all OpenWrt nodes. The tool is used to verify packages downloaded by the package
1546 | manager *opkg*, but may also check other signed files, like received
1547 | configurations.
1548 | 
1549 | [^web_alfred]: https://www.open-mesh.org/projects/alfred/wiki
1550 | [^git_usign]: https://git.openwrt.org/project/usign.git
1551 | 
1552 | \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
1553 | 
1554 | \newpage
1555 | # Attachments
1556 | 
1557 | Attached is a list of advises and configuration which enable an interested user
1558 | to setup a mesh network. Just as the design decision \ref{design-decisions} all
1559 | recommendations are based on evaluations with existing mesh communities.
1560 | 
1561 | ## Recommended hardware for mesh networks
1562 | 
1563 | In the following a short suggestion on what hardware can be used. As the
1564 | hardware support of the *802.11s* standard broadly varies it is highly recommended
1565 | to only use devices, concretely chip-sets and WiFi cards, which are known for
1566 | good support.
1567 | 
1568 | This project does not cover deeper analysis of hardware support regarding mesh
1569 | setups, however, during the software development some hardware worked better
1570 | then other. For further tests and interested developers I'd like to point out
1571 | the experiences I made.
1572 | 
1573 | ### Mesh nodes
1574 | 
1575 | Recommendations for nodes which are used providing access points and connections
1576 | to the backbone network.
1577 | 
1578 | #### Dual-Band
1579 | 
1580 | As the mesh approach of this project mostly involve connections over WiFi, all
1581 | devices should be equipped with potent wireless cards.
1582 | 
1583 | Simply said, the 2.4GHz frequencies pass better through obstacles while
1584 | offering a smaller bandwidth to transport data. On the other hand 5GHz has a
1585 | higher throughput with a shorter range[^24ghz5ghz].
1586 | 
1587 | In a practical setup most nodes would be positioned so that they have a direct
1588 | line of sight. Clients likely move around and signal can be reduced by
1589 | obstacles.  For this reason the *backbone* network should run on 5GHz while the
1590 | access points use 2.4GHz. As a result the used hardware should have at least
1591 | two bands covering both frequencies.
1592 | 
1593 | [^24ghz5ghz]:
1594 |   https://www.speedguide.net/faq/is-5ghz-wireless-better-than-24ghz-340
1595 | 
1596 | #### Storage and memory
1597 | 
1598 | The used mesh software, discussed below, requires slightly more space than
1599 | devices used as regular home routers due to the used routing protocol and it is
1600 | dependencies of cryptographic libraries. Therefore additional storage and memory
1601 | is recommended. The created firmware image has a size of about 6MB so devices
1602 | with 8MB are perfectly suited.
1603 | 
1604 | #### Optional: outdoor proof
1605 | 
1606 | This requirement can be archived in various ways using waterproof boxes or even
1607 | plastic bags. The waves of 2.4GHz frequencies are just the same as of microwave
1608 | ovens used in kitchens and so easily pass plastic shells with no problematic
1609 | reduction of signal.
1610 | 
1611 | Various companies offer outdoor routers with a water and sunlight proof case
1612 | [^ubnt_outdoor].
1613 | 
1614 | [^ubnt_outdoor]: https://www.ubnt.com/products/#unifi
1615 | 
1616 | #### Optional: Power over Ethernet (PoE)
1617 | 
1618 | Most router devices use a power supply of 12 Volt and up about 1 Ampere. The
1619 | power supply can be connected directly to the device or instead PoE is used to
1620 | supply the needed current via a regular patch cable. The advantage of this is
1621 | to connect devices to power and LAN with a single cable.
1622 | 
1623 | #### Special hardware
1624 | 
1625 | There are various specialized devices for mesh networks, from professional
1626 | companies [^openmesh_products][^ubnt_mesh] to communities creating own hardware
1627 | [^librerouter]. While companies and communities may use equal protocols like
1628 | *802.11s* the software is vastly different and incompatible.
1629 | 
1630 | Most devices offer dual band or even triple band (2x5GHz) to offer access
1631 | points in different frequencies. [^triple_band]
1632 | 
1633 | [^openmesh_products]: https://www.openmesh.com/products/wifi
1634 | [^ubnt_mesh]: https://unifi-mesh.ubnt.com/
1635 | [^librerouter]: https://librerouter.org/
1636 | [^triple_band]: https://librerouter.org/document/specifications-sheet-v6/
1637 | 
1638 | #### Home routers
1639 | 
1640 | Instead of using specialized hardware, which often comes to higher prices, it is
1641 | also possible to use a wide range[^openwrt_toh] of home router which fulfill the
1642 | requirements above. As mentioned before the support for *802.11s* and
1643 | compatibility for OpenWrt must be granted.
1644 | 
1645 | #### Suggested node hardware
1646 | 
1647 | The following home routers are found of ideal hardware in terms of support,
1648 | fulfilling all requirements:
1649 | 
1650 | * Buffalo WSR-1166DHP[^buffalo_wikidevi] (AC)
1651 | * Xiaomi MiWifFi 3G[^xiaomi_wikidevi] (AC)
1652 | * TP-LINK TL-WDR4300[^tplink_wikidevi]
1653 | 
1654 | [^buffalo_wikidevi]: https://wikidevi.com/wiki/Buffalo_AirStation_WSR-1166DHP
1655 | [^xiaomi_wikidevi]: https://wikidevi.com/wiki/Xiaomi_MiWiFi_3G
1656 | [^tplink_wikidevi]: https://wikidevi.com/wiki/TP-LINK_TL-WDR4300
1657 | 
1658 | ##### Home router flashing
1659 | 
1660 | As these devices are usually sold with branded and locked down software,
1661 | devices must be flashed with the software mentioned below. This process varies
1662 | between devices, vendor and CPU [^initial_installation_4300]
1663 | [^initial_installation_mini][^buffalo_initial].
1664 | 
1665 | [^openwrt_toh]: https://openwrt.org/toh/start
1666 | [^initial_installation_4300]:
1667 |   https://wiki.openwrt.org/toh/tp-link/tl-wdr4300#initial_installation
1668 | [^initial_installation_mini]:
1669 |   https://wiki.openwrt.org/toh/xiaomi/mini#quick_openwrt_installation
1670 | [^buffalo_initial]: https://patchwork.ozlabs.org/patch/704793/
1671 | 
1672 | ### Gateway
1673 | 
1674 | The gateway node can be a node just like all other node as well. The mesh setup
1675 | enables any node to serve a connected uplink to all other nodes within the
1676 | mesh. While this is possible and adds flexibility to the network setup it does
1677 | make sense to use special devices which serve as a gateway.
1678 | 
1679 | #### Gateway requirements
1680 | 
1681 | These requirements are additional but optional to the requirements of a *mesh
1682 | node*. Gateways may have no wireless radio installed at all, if connected to
1683 | other *mesh nodes* via cable.
1684 | 
1685 | ##### Network address translation (NAT)
1686 | 
1687 | Independent of the IP protocol used within the network a gateway has to perform
1688 | network address translation for IPv4 connections. This requires additional CPU
1689 | power which is rare on the used home routers mentioned above. The gateway has to
1690 | have noticeably more processor power than nodes to avoid becoming a bottleneck
1691 | of the network.
1692 | 
1693 | ##### CPU architecture
1694 | 
1695 | While OpenWrt supports a wide variety of hardware architectures
1696 | [^openwrt_architectures] the used monitoring software Prometheus is written in
1697 | Go[^web_golang] and so only supports a fraction of OpenWrts
1698 | architectures[^golang_architectures].
1699 | 
1700 | [^openwrt_architectures]: https://downloads.lede-project.org/snapshots/targets/
1701 | [^golang_architectures]: https://github.com/golang/go/wiki/MinimumRequirements#architectures
1702 | [^web_golang]: https://golang.org/
1703 | 
1704 | ##### Suggested gateway hardware
1705 | 
1706 | The previously mentioned APU Board from PCEngines[^apu_board] are ideal for the
1707 | projects setup. The used architecture is x86/64 and so supports Go.
1708 | A miniPCI SSD can expand the internal storage for logging and a miniPCI wireless
1709 | adapter can be used to connect to the rest of the mesh network[^ac_adapter]
1710 | allowing full 802:11ac speed.
1711 | 
1712 | [^ac_adapter]: https://www.asiarf.com/1W-High-Power-MT7612E-802-11ac-n-WiFi-Mini-PCIe-Module-2-4GHz-MT7612-G01-product-view-406.html
1713 | [^apu_board]: https://www.pcengines.ch/apu2.htm
1714 | 
1715 | \newpage
1716 | 
1717 | ## `/etc/config/lime-defaults`\label{lime_defaults}
1718 | 
1719 | \lstinputlisting[caption=Minimal lime-defaults file to be usable by meshrc.]{lime-defaults}
1720 | 
1721 | ## `/etc/prometheus.yml`\label{prom_config}
1722 | 
1723 | \lstinputlisting[caption=Example configuration for Prometheus to monitor devices of the mesh.]{prometheus.yml}
1724 | 
1725 | ## `/etc/rules.yml`\label{prom_rules}
1726 | 
1727 | \lstinputlisting[caption=Example configuration file for alerts.]{rules.yml}
1728 | 
1729 | ## Document creation
1730 | 
1731 | This document is written in Markdown with additional segments LaTex. The
1732 | Markdown input is converted to LaTex via `pandoc`^[http://pandoc.org/] using the
1733 | *Eisvogel*
1734 | template^[https://github.com/Wandmalfarbe/pandoc-latex-template/blob/master/eisvogel.tex]
1735 | 
1736 | All photos, screenshots and images are self created.
1737 | 
1738 | * All network graphs were created with draw.io^[https://draw.io].
1739 | * Sequence diagrams were created via the Mermaid Live Editor^[https://mermaidjs.github.io/mermaid-live-editor/].
1740 | 
1741 | \newpage
1742 | 
1743 | # Erklärung {-}
1744 | 
1745 | Ich versichere hiermit, dass ich die vorliegende Arbeit selbständig verfasst
1746 | und keine anderen als die im Literaturverzeichnis angegebenen Quellen benutzt
1747 | habe. Alle Stellen, die wörtlich oder sinngemäß aus veröffentlichten oder noch
1748 | nicht veröffentlichten Quellen entnommen sind, sind als solche kenntlich
1749 | gemacht.  Die Zeichnungen oder Abbildungen in dieser Arbeit sind von mir selbst
1750 | erstellt worden. Diese Arbeit ist in gleicher oder ähnlicher Form noch bei
1751 | keiner anderen Prüfungsbehörde eingereicht worden.
1752 | 
1753 | Paul Spooren
1754 | 
1755 | \newpage
1756 | # References
1757 | 


--------------------------------------------------------------------------------