allmon3-netmap

Lightweight PHP add-on for Allmon3 that queries the Asterisk AMI and returns a map of every node reachable through the linked AllStarLink network — local nodes with live keyed state, remote nodes with description and optional lat/lon coordinates.

A single endpoint (netmap.php) handles node discovery, metadata enrichment, and coordinate lookup. Output can be consumed as JSON (the default), GeoJSON for those mapping APIs that are very smart, or KML for direct import into Google Earth, Google Maps, or any GIS tool that speaks KML.

How It Works

1. Reads /etc/allmon3/netmap-settings.ini for one or more Asterisk AMI servers, each with a list of locally-hosted node numbers.
2. Connects to each AMI server and issues an RptStatus XStat command for every listed node.
3. Parses the LinkedNodes: field from each response, which contains the full transitive set of all reachable nodes — no recursive graph traversal needed.
4. Merges results from all servers into a single deduplicated JSON object.
5. Filters out private nodes (number < 2000) and enriches each entry with:
   • Call sign and description from /var/lib/asterisk/astdb.txt
   • Optional lat/lon and label overrides from /etc/allmon3/netmap-nodelist.ini

Requirements

Requirement	Notes
Allmon3	Installed and serving from /usr/share/allmon3
PHP 8.0+	With sockets / fsockopen support (standard in most distros)
Asterisk AMI	Port 5038 accessible from the web server; AMI manager account configured
/var/lib/asterisk/astdb.txt	Node metadata flat file; generated by AllStarLink node tools. The API degrades gracefully if absent.

Installation

1. Clone the repository

The recommended location is /opt/allmon3-netmap — the standard path for self-contained third-party add-ons not managed by the distro package manager.

sudo git clone https://github.com/JoshuaCarroll/allmon3-netmap /opt/allmon3-netmap

2. Run the installer

sudo bash /opt/allmon3-netmap/install.sh

The installer:

• Creates a symlink /usr/share/allmon3/netmap.php → /opt/allmon3-netmap/netmap.php. Because it is a symlink, Allmon3 package upgrades will not overwrite it, and re-running the installer recreates the link if it is ever removed.
• Copies netmap-settings.ini and netmap-nodelist.ini template files to /etc/allmon3/ only if they do not already exist, so your edits are never overwritten.

3. Configure settings

Edit /etc/allmon3/netmap-settings.ini to set your AMI credentials and (optionally) QRZ.com credentials for automatic coordinate lookup:

; ── Asterisk AMI server ───────────────────────────────────────────────────────
[local]
host  = 127.0.0.1
port  = 5038
user  = admin
pass  = your-ami-secret
nodes = 499600

; ── QRZ.com coordinate lookup (optional — leave blank to disable) ──────────
[qrz]
user = your-qrz-username
pass = your-qrz-password

The file must be readable by the web server user:

sudo chmod 640 /etc/allmon3/netmap-settings.ini
sudo chown root:www-data /etc/allmon3/netmap-settings.ini

Multiple AMI servers are supported — add additional [section] blocks for each Asterisk instance.

4. (Optional) Add node coordinates

Edit /etc/allmon3/netmap-nodelist.ini to add lat/lon for any nodes you want to display on a map. You can generate a pre-populated template from the live network by hitting the ?template=1 endpoint (see API below), then saving the output to /etc/allmon3/netmap-nodelist.ini.

[499600]
lat = 34.799
lon = -92.500
; label = My Repeater   ; optional — overrides the node description

5. Verify

curl http://localhost/allmon3/netmap.php

API

All requests are GET. The endpoint is served from Allmon3's web root.

URL	Description
/allmon3/netmap.php	Returns the full node map as JSON
/allmon3/netmap.php?pretty=1	Same, with human-readable indentation
/allmon3/netmap.php?format=kml	Returns the node map as a KML document (Google Earth / Google Maps)
/allmon3/netmap.php?format=geojson	Returns the node map as GeoJSON for GIS tools and modern map viewers
/allmon3/netmap.php?template=1	Returns a netmap-nodelist.ini template pre-populated with all currently discovered nodes. Nodes that already have coordinates in the live config are pre-filled.

JSON Response Format

{
  "499600": {
    "callsign": "AA5JC",
    "desc": "AA5JC 146.775 Little Rock, AR",
    "txkeyed": false,
    "rxkeyed": false,
    "txekeyed": false,
    "numlinks": 4,
    "uptime": 86400,
    "reloadtime": 3600,
    "lat": 34.899,
    "lon": -92.980,
    "local": true
  },
  "65017": {
    "callsign": "W5XYZ",
    "desc": "W5XYZ Hub Node Dallas, TX",
    "lat": null,
    "lon": null,
    "local": false
  }
}

local: true indicates the node was directly queried via AMI (lives on one of your configured servers). Remote nodes discovered through LinkedNodes: carry live key state only when they happen to be listed on another configured server; otherwise key state fields are absent.

KML Output (?format=kml)

Returns a standard KML 2.2 document suitable for Google Earth, Google Maps (My Maps > Import), QGIS, and any other KML-capable tool.

• Only nodes that have both lat and lon are emitted as Placemarks; nodes without coordinates are silently omitted.
• Each Placemark's info balloon shows the callsign, node number, description, and whether the node is local or remote.
• Three icon styles distinguish node categories:

Style	Color	Meaning
local-asl	Blue	Node directly queried via AMI
remote-asl	Green	Node discovered through LinkedNodes:
echolink	Yellow	EchoLink / phone-portal node

Updating

Because netmap.php is installed as a symlink back to the repo, updating is a single pull with no reinstall required:

cd /opt/allmon3-netmap && sudo git pull

Uninstallation

sudo bash /opt/allmon3-netmap/uninstall.sh

The uninstaller removes the symlink from /usr/share/allmon3/ but does not delete your config files in /etc/allmon3/. Those contain your credentials and coordinate data and must be removed manually if desired:

sudo rm /etc/allmon3/netmap-settings.ini
sudo rm /etc/allmon3/netmap-nodelist.ini

File Layout

/opt/allmon3-netmap/          ← repo clone
├── netmap.php                ← the API endpoint (symlinked into Allmon3)
├── netmap-settings.ini       ← settings template (copied once to /etc/allmon3/)
├── netmap-nodelist.ini       ← coordinates template (copied once to /etc/allmon3/)
├── install.sh
└── uninstall.sh

/usr/share/allmon3/
└── netmap.php  →  /opt/allmon3-netmap/netmap.php   (symlink)

/etc/allmon3/
├── netmap-settings.ini       ← your live AMI + QRZ credentials (never overwritten)
└── netmap-nodelist.ini       ← your live coordinate data (never overwritten)

License

See LICENSE.