Skip to content

The HopGlass Server, which collects data from Freifunk networks and processes it to be used in HopGlass or for statistics

License

Notifications You must be signed in to change notification settings

ffansbach/hopglass-server

 
 

Repository files navigation

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

About

The HopGlass Server, which collects data from Freifunk networks and processes it to be used in HopGlass or for statistics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 97.7%
  • Dockerfile 1.8%
  • Nix 0.5%