TrapWatch

Community strings

Left blank in Settings → Receiving, community strings are not checked and every trap that reaches the port is accepted. Fill them in and non-matching traps are counted as rejected rather than silently dropped, so the screen can tell you the difference between “nothing is arriving” and “everything is being refused”. Note that in SNMP v1 and v2c the community string travels in clear text — treat it as a filter, not as security.

SNMP versions

v1 and v2c. v3 traps are not accepted: v3 needs per-device engine IDs and credentials, which would require exactly the device registry this product deliberately does without.

Anomaly detection

Runs inside the application on this machine. Nothing is uploaded and no model is downloaded. It reports three things: a link that goes up and down repeatedly (counting direction changes, not trap volume), a device sending a kind of trap far more often than its own history says it should, and a device or trap OID seen for the first time. It stays silent until it has a baseline — about half an hour — because on the first run everything is new and an alert that fires for everything teaches you to ignore alerts.

Alert rules

Rules cover what you already know to look for; detection covers what you do not. A rule matches on source address, trap name or OID, and a minimum severity. Repeat suppression is keyed to the rule and the device, so one noisy switch cannot bury the same event happening on another one.

Unknown traps

Vendor-specific traps are shown by their OID exactly as received. TrapWatch does not invent a description for a trap it does not recognise — a plausible-sounding guess sends you looking in the wrong place.

Retention

Traps are written to this machine, one file per day, and are never deleted to enforce a plan. Settings → Retention is yours to set; 0 means keep everything. Any of it can be exported to CSV.

Language

Settings → Interface language. English, Japanese, Korean and Simplified Chinese, switchable while it runs. What a device sent — its address, the trap OID, the interface name — is never translated.

Where your data lives

Everything TrapWatch records stays on the computer it runs on. None of it is sent to us, to an analytics company or to an advertising network.

Licence keys

The key arrives by email after purchase. It is checked on this computer, so TrapWatch never contacts a licensing server — it activates on a network with no way out. When the 30-day trial ends, traps already received stay readable; only receiving new traps stops. No alerts or Central reports go out while it is stopped; enter a key and receiving starts again straight away.

Try it in the foreground

Install the .deb — apt pulls in the libraries it needs — then start the wrapper installed next to the app:

sudo apt install ./TrapWatch-*-amd64.deb

/opt/TrapWatch/trapwatch-headless

It prints the address of the web UI with a one-time token — http://127.0.0.1:8162/?token=…. Open it once; a cookie remembers you, and afterwards http://127.0.0.1:8162/ is enough. Lost it? trapwatch-headless --show-url prints it again. Send a test trap from the same machine (snmptrap is in the net-snmp tools: apt-get install snmp or dnf install net-snmp-utils):

snmptrap -v 2c -c public 127.0.0.1:1162 '' 1.3.6.1.6.3.1.1.5.3 \
    1.3.6.1.2.1.2.2.1.1.1 i 1 1.3.6.1.2.1.2.2.1.2.1 s "eth0"

That is a linkDown for interface 1; it shows up as “Link down” on eth0.

Open the screen from your own computer

The web UI listens on 127.0.0.1 only. Tunnel to it over SSH, then open the token address in your own browser:

ssh -L 8162:127.0.0.1:8162 user@server

Or put an HTTPS reverse proxy (nginx, Caddy) in front of it. Do not expose the plain HTTP port to an untrusted network: trap contents, community strings and the Central token pass through it.

Run it as a service

A systemd unit is installed next to the wrapper. Create a service user, copy the unit and start it:

sudo useradd --system --home /var/lib/trapwatch --create-home --shell /usr/sbin/nologin trapwatch
sudo cp /opt/TrapWatch/trapwatch-headless.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now trapwatch-headless

The web UI address, with its token, is printed in the journal: sudo journalctl -u trapwatch-headless.

Port 162

TrapWatch listens on UDP 1162 by default, which any user may open. If devices can only send to 162, change the port to 162 in Settings, uncomment the AmbientCapabilities=CAP_NET_BIND_SERVICE line in /etc/systemd/system/trapwatch-headless.service, and restart the service:

sudo systemctl daemon-reload
sudo systemctl restart trapwatch-headless

If the port cannot be opened, the reason is in the journal as well as at the top of the screen.

Where the data lives

As a service: /var/lib/trapwatch/TrapWatch — traps, settings, the licence and the UI token. Run by hand, headless uses the same folder as the desktop app for that user (~/.config/TrapWatch), so a licence activated in one is active in the other. The service runs as its own user, so enter the licence key once in its web UI.

A server has no keyring, so the licence key, alert rules and Central token are stored as files readable only by the service user (mode 0600); settings.json, which holds the community strings, is written with mode 0600 as well. There is no desktop to notify: a rule that would raise a desktop notification writes one line to the journal instead. MeshWatch Central works as on the desktop and is the alert path on a server.

Nothing is arriving

The firewall is the usual reason — see section 4. After that, check that the device is pointed at this computer’s current local IP address; a DHCP lease can move it.

Test connection to Central fails

bad-token means the token is wrong or was revoked — issue a new one. unreachable means the address is wrong or a firewall is in the way; port 8443 must be open on the Central server. Note it is http://, not https://, unless you put a reverse proxy in front of Central. wrong-product means the token was issued for a different product; the message names which one. Issue a token for TrapWatch instead and revoke the other. If the address looks right but Central is still unreachable, check it for a typo: most mistyped addresses are still valid addresses — 127.0.0.01 is read as 127.0.0.1 and 192.168.001.5 as 192.168.1.5 — so the connection quietly goes somewhere else. In the current releases these results are shown as sentences — a token Central refuses is explained as possibly revoked or issued by a different Central — and the code itself appears when you hover over the message.

Central shows this agent as “connected”, but nothing arrives

That is not a failure. connected means the test succeeded and nothing has been sent yet; the row switches to reporting on the first real report, because a product sends only when something happens. TrapWatch switches to reporting when the first trap actually arrives. A row still reading waiting has never reached Central.

It prints Missing X server or $DISPLAY on a Linux server

That is the desktop app asking for a screen; nothing is wrong with the install. Run it from a desktop session, or on a server without one use the headless mode — see section 5.

Problems that affect every product

A blank window after upgrading, Ubuntu 24.04 refusing to start the app, credentials stored as plain text on Linux without a keyring, alert email not being delivered — these are the same on every product and are collected on the support page.

Still stuck

Write to support@meshwatch.app with the version number and what you expected to happen. First reply within two business days, Monday to Friday.