HopGlass Server

The HopGlass Server collects data from Freifunk networks and processes it to be used in HopGlass, for statistics and other purposes.

How to use

Installation

1. Install a recent version of NodeJS. It is recommended to use your distribution's package manager: https://nodejs.org/en/download/package-manager/

2. Clone the hopglass-server repository to /opt/hopglass/server

   mkdir -p /opt/hopglass
   git clone https://github.com/hopglass/hopglass-server /opt/hopglass/server
   

3. Install NPM dependencies with yarn

   cd /opt/hopglass/server
   yarn install
   

4. Copy the systemd service file to /etc/systemd/system, or create an init-script if your distribution does not support systemd.

   cp /opt/hopglass/server/[email protected] /etc/systemd/system/
   systemctl daemon-reload
   

5. Start the HopGlass Server: # systemctl start hopglass-server@default

   systemctl start hopglass-server@default
   

6. (Optional) Automatically start the HopGlass Server at boot:

   systemctl enable hopglass-server@default
   

After installation

Optionally create a configuration file in /etc/hopglass-server/default/config.json, and an aliases file in /var/lib/hopglass-server/default/aliases.json. Ensure, that the ports, you configured are open in your firewall (default port 1001 UDP and 45123 UDP).

You might want to

• Install a webserver (search for Nginx or Apache) and configure a reverse proxy and gzip-compression
• Install HopGlass
• Install Prometheus and Grafana

Update

Warning: The HopGlass Server is subject to major changes. Updates may require manual intervention.

For a start, you can try this:

1. pull

   cd /opt/hopglass/server
   git pull
   

2. Copy the new systemd service file to /etc/systemd/system or /lib/systemd/system/ and reload with:

   cp /opt/hopglass/server/[email protected] /etc/systemd/system/
   systemctl daemon-reload
   

3. check for possible needed changes in the config.json

   diff config.json config.json.example
   

4. rebuild the server:

   cd /opt/hopglass/server
   yarn install
   

5. restart the service

   systemctl restart hopglass-server@default
   

Note: The default paths for configuration and state files might have changed. Make sure your config.json, raw.json and aliases.json are located in /etc/hopglass-server/default/config.json, /var/lib/hopglass-server/default/aliases.json and /var/lib/hopglass-server/default/raw.json respectively.

Possible webserver queries

Query Location	Description
/nodes.json	HopGlass nodes.json v2
/graph.json	HopGlass graph.json v1
/mv/nodes.json	Meshviewer nodes.json v2
/mv/graph.json	Meshviewer graph.json v1
/mv1/nodes.json	Meshviewer nodes.json v1
/mv1/graph.json	Meshviewer graph.json v1
/raw.json	Raw data collected, same as the raw.json save file
/nodelist.json	nodelist.json format (github.com/ffansbach/nodelist)
/hosts	hosts file to be placed in /etc/hosts
/metrics	Prometheus metrics
/wifi-aliases.txt	Aliases file for Wifi Analyzer app
/WifiAnalyzer_Alias.txt	Aliases file for Wifi Analyzer app
/ffapi.json	Freifunk API file
/nodes.zone	Named DNS zone file
/contacts	All unique contact entries
/noloc-contacts	All unique contacts of nodes w/o location
/nodes	List all nodes (hostname;nodeid)

Metrics values

per node (all with the labels hostname, and nodeid):

• statistics.clients.total
• statistics.uptime
• statistics.traffic
• statistics.loadavg
• statistics.memory_usage

total values:

• meshnodes_total
• meshnodes_online_total
• total_clients
• total_traffic

Filter / queries

Syntax

• [query_location]?filter=[filterName]&value=[filterValue] useful example: [nodes|nodelist].json?filter=[filterName]&value=[filterValue]

Filternames

• site
• firmware_release
• firstseen
• lastseen
• uptime
• clients
• nodeid
• contact

Development timeline

oldmaster (outdated)

v0.1.0 (outdated)

• fully modular conversion system
• many bugfixes
• meshviewer provider
• ffapi provider
• label-based traffic metrics

v0.1.1 (outdated)

• bugfix release

v0.1.2 (outdated)

• many bugfixes (many contributors)
• additional input checks (Joshua1337, eberhab)
• provider/hopglass: resolve gateways to nodeids (mar-v-in)
• provider/hopglass: nexthop key (eberhab)
• new provider: dns zone output (eberhab)
• probably more I forgot

v0.1.3 (outdated)

• fix the install script

v1.0.0 (current)

• various bugfixes (many contributors)
• remove obsolete installation scripts
• rewrite systemd service file to use DynamicUser and StateDirectory options
• new provider: meshviewers nodes.json v1 (rotanid)
• allow hjson for aliases and config
• receiver/announced: offset queries for different data typesnodeinfo/statistics
• receiver/announced: Ensure multicast interface is set (tobleminer)
• add Nix derivation and flake
• Recommended NodeJS version: 12+
• provider/prometheus: only add gateway label to online metric

v2.0.0 (next)

• provide a graph-generation implementation for all providers
• graph caching
• handle gateway flag correctly without aliases
• alfred receiver
• new HopGlass data format
• network-transparent receivers