IP address auto-discovery – agent and network collector

How it works

Both the agent and the collector send a report to ipmanager with POST /api/v1/agent/report over HTTPS, with an API key in the Authorization header. ipmanager then does the following for each address in the report:

New address: created with status “in use”, and the source is marked as agent or scan.
Known address: “last seen” is updated. A changed hostname or MAC address is updated and written to the audit log.
Address that was free or offline: set back to “in use”.
No change: only “last seen” is updated, with no new audit log entry.

If the organisation has reached its address limit, new addresses are not created. They are counted as limited in the response, while known addresses are still updated.

	Agent	Collector
Runs on	Every machine that should report	One machine in the network
Finds	The machine's own addresses, hostname and MAC	Everything that answers ping, the ARP table, reverse DNS and DHCP leases
Platform	Linux and macOS (shell), Windows (PowerShell)	Python 3 with no dependencies, typically on Linux
Best for	Servers and fixed machines	Printers, IoT, AV equipment and anything you cannot install software on

1. Create an API key

Go to Auto-discovery & API in ipmanager and create a new key with the agent scope. An agent key can only send reports – it cannot read or delete data. The key is shown only once, so store it safely. Consider one key per site or collector, so you can revoke a single key without affecting others.

2a. Agent on Linux and macOS

Download and test

curl -fsSo /usr/local/bin/ipm-agent.sh https://ipmanager.no/api/v1/agent/scripts/ipm-agent.sh
chmod 755 /usr/local/bin/ipm-agent.sh

# Test
IPM_TOKEN=ipm_xxxxxxxx sh /usr/local/bin/ipm-agent.sh

Keep the key in a file only root can read, rather than in the crontab:

Store the key

mkdir -p /etc/ipmanager
echo 'IPM_TOKEN=ipm_xxxxxxxx' > /etc/ipmanager/agent.env
chmod 600 /etc/ipmanager/agent.env

With cron

# /etc/cron.d/ipmanager – report every 15 minutes
*/15 * * * * root . /etc/ipmanager/agent.env && IPM_TOKEN=$IPM_TOKEN sh /usr/local/bin/ipm-agent.sh >/dev/null 2>&1

With a systemd timer

# /etc/systemd/system/ipm-agent.service
[Unit]
Description=ipmanager agent
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/ipmanager/agent.env
ExecStart=/bin/sh /usr/local/bin/ipm-agent.sh

# /etc/systemd/system/ipm-agent.timer
[Unit]
Description=Run ipmanager agent every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min
RandomizedDelaySec=60

[Install]
WantedBy=timers.target

Enable the timer

systemctl daemon-reload
systemctl enable --now ipm-agent.timer

2b. Agent on Windows

Download and test (PowerShell as administrator)

New-Item -ItemType Directory -Force C:\ProgramData\ipmanager | Out-Null
Invoke-WebRequest https://ipmanager.no/api/v1/agent/scripts/ipm-agent.ps1 -OutFile C:\ProgramData\ipmanager\ipm-agent.ps1

# Test
$env:IPM_TOKEN = 'ipm_xxxxxxxx'
powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1

Scheduled task every 15 minutes

[Environment]::SetEnvironmentVariable('IPM_TOKEN', 'ipm_xxxxxxxx', 'Machine')

schtasks /Create /TN "ipmanager agent" /RU SYSTEM /SC MINUTE /MO 15 /F `
  /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1"

3. Collector inside your own network

The collector is a single Python 3 script with no dependencies. It runs on one machine in the network – a server, a virtual machine or a small Linux box – and acts as the go-between: it sees the network from the inside and reports out to ipmanager.

Download and run

curl -fsSO https://ipmanager.no/api/v1/agent/scripts/ipm-collector.py
python3 ipm-collector.py --help

# Sweep two networks and include the ARP table
python3 ipm-collector.py --token ipm_xxxxxxxx --arp 10.20.0.0/24 10.20.3.0/24

The collector pings the addresses in the networks you give it, reads the machine's ARP table to find MAC addresses, looks up reverse DNS for hostnames and can read leases from dnsmasq and ISC DHCP. See --help for all options.

Schedule with cron

# /etc/cron.d/ipmanager-collector – every hour
0 * * * * root . /etc/ipmanager/agent.env && python3 /opt/ipmanager/ipm-collector.py --token "$IPM_TOKEN" --arp 10.20.0.0/16 >/dev/null 2>&1

The ARP table only contains machines in the same layer 2 network as the collector. For networks behind a router you get IP and hostname, but not MAC – unless you read DHCP leases or run a collector in each network.

4. DNS check of internal names

Public IP addresses are checked automatically from ipmanager.no against public DNS once a day. Internal names – such as .local or Active Directory DNS – can only be looked up from the inside. That is why the collector can check them with --dns-check, against the DNS server in your own network.

The collector fetches the registered addresses with hostnames in the networks you give it, looks up the PTR record for each IP and the A/AAAA record for each name, and reports the result. ipmanager sets the status to OK, mismatch or missing (PTR or A/AAAA), and mismatches also appear under Conflicts. With --no-scan the collector skips the ping sweep and only checks DNS.

DNS check only

IPM_TOKEN=ipm_xxxxxxxx python3 ipm-collector.py --dns-check --no-scan 10.20.0.0/16

Schedule with cron

# /etc/cron.d/ipmanager-dns – every night at 03:15
15 3 * * * root . /etc/ipmanager/agent.env && IPM_TOKEN="$IPM_TOKEN" python3 /opt/ipmanager/ipm-collector.py --dns-check --no-scan 10.20.0.0/16 >/dev/null 2>&1

If you use short hostnames, set a DNS suffix in ipmanager so that file01 is checked as file01.corp.local. Addresses without a hostname get a suggestion from the PTR record, which can be applied with one click.

Conflicts from reports

Reports from agents and the collector are also used to find conflicts: duplicate IPs (two MAC addresses on the same IP within a few minutes), a different MAC on a registered IP (the registered MAC is not overwritten), a known MAC on another IP, hosts on addresses registered as free, reserved or deprecated, IPs outside registered subnets, static addresses inside DHCP ranges and changed hostnames. Conflicts resolve automatically when the condition disappears, and administrators get an email about new critical and warning conflicts.

Firewall and network

The agent and collector only need outbound TCP 443 to ipmanager.no. Nothing needs to be opened inbound.
The collector must be able to send ICMP echo (ping) to the networks it sweeps. Machines whose host firewall blocks ping are not found by ping, but may appear via ARP or DHCP.
If outbound traffic goes through a proxy, the scripts can use the standard proxy variables (HTTPS_PROXY).

Security

Use keys with the agent scope. They can only report, not read or delete.
Store the key in a file only root or SYSTEM can read, not in scripts committed to version control.
The API key page shows when each key was last used, and from which IP. Revoke keys that are not in use.
The scripts are plain text. Read through them before you run them.

Troubleshooting

Response	Cause
`401 invalid_token`	Wrong key, or the key has been revoked.
`403 insufficient_scope`	The key does not have the agent scope.
`limited` > 0 in the response	The organisation has reached its address limit. New addresses were not created.
No new addresses from the collector	Check that ping is allowed and that the networks are written in CIDR notation.

See the API documentation for the exact report format.