ffmap-backend/README.md

118 lines
3.5 KiB
Markdown
Raw Normal View History

2014-06-21 20:18:41 +02:00
# Data for Freifunk Map, Graph and Node List
2014-06-21 20:04:14 +02:00
2015-03-24 18:06:54 +01:00
[![Build Status](https://travis-ci.org/ffnord/ffmap-backend.svg?branch=master)](https://travis-ci.org/ffnord/ffmap-backend)
2015-04-02 18:52:00 +02:00
ffmap-backend gathers information on the batman network by invoking :
2015-03-21 01:26:56 +01:00
2015-04-02 18:52:00 +02:00
* batctl (might require root),
2015-03-21 01:26:56 +01:00
* alfred-json and
* batadv-vis
2015-04-02 18:52:00 +02:00
The output will be written to a directory (`-d output`).
2014-06-21 20:04:14 +02:00
2015-04-02 18:52:00 +02:00
Run `backend.py --help` for a quick overview of all available options.
2014-06-21 20:04:14 +02:00
For the script's regular execution add the following to the crontab:
2015-04-02 18:52:00 +02:00
2014-06-21 20:18:41 +02:00
<pre>
2015-04-12 12:07:48 +02:00
* * * * * backend.py -d /path/to/output -a /path/to/aliases.json --vpn ae:7f:58:7d:6c:2a d2:d0:93:63:f7:da
2014-06-21 20:18:41 +02:00
</pre>
2015-03-21 01:26:56 +01:00
2015-04-30 17:37:19 +02:00
# Dependencies
2015-05-15 18:20:49 +02:00
- Python 3
- Python 3 Package [Networkx](https://networkx.github.io/)
2015-04-30 17:37:19 +02:00
- [alfred-json](https://github.com/tcatm/alfred-json)
2015-05-15 18:20:49 +02:00
- rrdtool (if run with `--with-rrd`)
2015-04-30 17:37:19 +02:00
# Running as unprivileged user
Some information collected by ffmap-backend requires access to specific system resources.
Make sure the user you are running this under is part of the group that owns the alfred socket, so
alfred-json can access the alfred daemon.
# ls -al /var/run/alfred.sock
srw-rw---- 1 root alfred 0 Mar 19 22:00 /var/run/alfred.sock=
# adduser map alfred
Adding user `map' to group `alfred' ...
Adding user map to group alfred
Done.
$ groups
map alfred
Running batctl requires passwordless sudo access, because it needs to access the debugfs to retrive
the gateway list.
# echo 'map ALL = NOPASSWD: /usr/sbin/batctl' | tee /etc/sudoers.d/map
map ALL = NOPASSWD: /usr/sbin/batctl
# chmod 0440 /etc/sudoers.d/map
That should be everything. The script automatically detects if it is run in unprivileged mode and
will prefix `sudo` where necessary.
2015-03-21 01:26:56 +01:00
# Data format
## nodes.json
{ 'nodes': {
node_id: { 'flags': { flags },
'firstseen': isoformat,
'lastseen': isoformat,
'nodeinfo': {...}, # copied from alfred type 158
'statistics': {
'uptime': double, # seconds
'memory_usage': double, # 0..1
'clients': double,
'rootfs_usage': double, # 0..1
'loadavg': double,
'gateway': mac
}
},
...
}
'timestamp': isoformat
}
### flags (bool)
- online
- gateway
2015-04-01 23:31:34 +02:00
## Old data format
If you want to still use the old [ffmap-d3](https://github.com/ffnord/ffmap-d3)
front end, you can use the file `ffmap-d3.jq` to convert the new output to the
old one:
```
jq -n -f ffmap-d3.jq \
--argfile nodes nodedb/nodes.json \
--argfile graph nodedb/graph.json \
> nodedb/ffmap-d3.json
```
Then point your ffmap-d3 instance to the `ffmap-d3.json` file.
2015-04-01 23:31:34 +02:00
# Removing owner information
If you'd like to redact information about the node owner from `nodes.json`,
you may use a filter like [jq]. In this case, specify an output directory
different from your webserver directory, e.g.:
./backend.py -d /ffmap-data
Don't write to files generated in there. ffmap-backend uses them as its
database.
After running ffmap-backend, copy `graph.json` to your webserver. Then,
filter `nodes.json` using `jq` like this:
jq '.nodes = (.nodes | with_entries(del(.value.nodeinfo.owner)))' \
< /ffmap-data/nodes.json > /var/www/data/nodes.json
This will remove owner information from nodes.json before copying the data
to your webserver.
[jq]: https://stedolan.github.io/jq/