GUIDES › TrafficWatch

Other languages English · 日本語 · 한국어 · 简体中文

TrafficWatch

Per-device DNS visibility on your own network — 1.1.8

In this version

Full release notes

1. Install

Pick the build for the machine you are installing on. Every file below is the current release; older versions are listed on the release notes page.

Verify what you downloaded. The published checksums are at TrafficWatch-SHA256SUMS.txt

On macOS or Linux:

shasum -a 256 TrafficWatch-1.1.8-arm64.dmg

On Windows:

Get-FileHash -Algorithm SHA256 TrafficWatch-1.1.8-win.zip

The macOS build is notarised by Apple, so it opens without a warning. The Windows installer is Authenticode-signed and timestamped. The certificate is new, so SmartScreen may still show a warning until it has built reputation — if it does, choose More info → Run anyway.

2. First run

  1. Tell the people who share your network before you start. TrafficWatch becomes the DNS server for the network, and it records which device asked for which domain.
  2. It needs port 53. macOS and Linux reserve that port and will ask for an administrator password. Windows does not.
  3. On Linux, systemd-resolved usually holds port 53 already. Disable its stub listener, or grant the binary CAP_NET_BIND_SERVICE rather than running the whole app as root.
  4. Then open your router’s admin page and set the DHCP DNS server to this computer’s local IP address. Devices pick it up when they reconnect.

Every install starts with a 30-day trial of the paid edition. Nothing is asked for up front — no card, no account, no email address.

3. Administration

What is recorded

Queries from every device are written to the log on this computer. The free tier limits what is shown, never what is recorded, and history is never deleted to enforce a plan — upgrading reveals what was already there.

Naming devices

Devices arrive as IP addresses. Naming them makes the log readable and makes alert rules worth writing.

Alerts and delivery

The Alerts button opens Alerts & delivery: the rules, email delivery, and the MeshWatch Central connection.

Pro

Pro is US$99 per year and adds alert rules, the MeshWatch Central connection, CSV/JSON export and unlimited device history. A licence key is emailed after checkout and is verified on this computer — TrafficWatch never contacts a licensing server.

Where your data lives

Everything TrafficWatch 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 TrafficWatch never contacts a licensing server. When the 30-day trial ends, or a subscription lapses, TrafficWatch keeps answering and logging every query on Free, and shows up to 3 devices and the last 24 hours. Alert rules and the MeshWatch Central connection are part of Pro.

4. Firewall

5. Run on a server without a desktop (headless)

The desktop app needs a graphical session. On a Linux server without one it does not start and prints Missing X server or $DISPLAY. For that case the Linux .deb also includes a headless mode: it answers and records DNS queries the same way, with the same screen served to your browser instead of a window. The AppImage does not include it. The install path contains a space, so quote it as below.

Try it in the foreground

Install the .deb — apt pulls in the libraries it needs. Port 53 is privileged, so for a first look use a high port on the loopback address; no root is needed:

sudo apt install ./TrafficWatch-*-linux-amd64.deb
"/opt/Network TrafficWatch/trafficwatch-headless" --dns-port 5353 --dns-host 127.0.0.1

It prints the address of the web UI with a one-time token — http://127.0.0.1:8053/?token=…. Open it once; a cookie remembers you, and afterwards http://127.0.0.1:8053/ is enough. Lost it? --show-url prints it again. Send a query from the same machine to see it appear: dig @127.0.0.1 -p 5353 example.com — the Send a test query button on the screen does the same.

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 8053:127.0.0.1:8053 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: every device’s lookups, SMTP credentials and the Central token pass through it.

Run it as a service on port 53

A systemd unit is installed next to the wrapper. Unlike SyslogWatch and TrapWatch, it needs one line edited before it starts:

sudo useradd --system --home /var/lib/trafficwatch --create-home --shell /usr/sbin/nologin trafficwatch
sudo cp "/opt/Network TrafficWatch/trafficwatch-headless.service" /etc/systemd/system/
sudoedit /etc/systemd/system/trafficwatch-headless.service

In the ExecStart line, replace 192.168.1.10 after --dns-host with this server’s own LAN address (ip -4 addr shows it). On Ubuntu, systemd-resolved already holds 127.0.0.53:53, so binding every address fails with EADDRINUSE; binding only the LAN address lets the two coexist. Leave the AmbientCapabilities=CAP_NET_BIND_SERVICE line in place — it is what lets the service user open port 53.

sudo systemctl daemon-reload
sudo systemctl enable --now trafficwatch-headless

The web UI address, with its token, is printed in sudo journalctl -u trafficwatch-headless. Then point your router’s DHCP DNS setting at that LAN address; devices start sending their lookups here as they renew their lease. Setting DNSStubListener=no in /etc/systemd/resolved.conf also works, but then the server’s own /etc/resolv.conf needs attention.

Where the data lives — and the licence key

As a service: /var/lib/trafficwatch/.trafficwatch — the query log, settings, the licence and the UI token. If you ran the Linux desktop app with sudo, its data is in /root/.trafficwatch, a different folder, so the licence key is not carried over: enter it again in the web UI (the plan badge in the title bar). The same key may be active in both places.

A server has no keyring, so the licence key, SMTP password and Central token are stored as files readable only by the service user (mode 0600). There is no desktop to notify: a rule that would raise a desktop notification writes one line to the journal instead. Email alerts and MeshWatch Central work as on the desktop.

The full notes are in README-headless.txt next to the wrapper; --help lists the options.

6. Connect to MeshWatch Central

Optional, and part of Pro — on the Free plan the alert settings say so. Central gathers alerts from several products into one inbox and correlates them by device. Only alert summaries are sent to Central. Domains and per-device query history stay on this computer.

  1. In Central, open Agents, choose TrafficWatch, type any label you like — it is just a name to tell installations apart — and press Issue token. The token is shown once.
  2. Pick TrafficWatch in that dropdown. A token belongs to the product it was issued for, and Central files every report under that product rather than under the application that sent it. A TrafficWatch installation given another product’s token connects and reports successfully, and its data appears under the other product while the TrafficWatch view stays empty — with no error at either end.
  3. In TrafficWatch, open the MeshWatch Central settings and enter Central’s address as http://<central-server>:8443 and the token. Use the server’s address, not localhost, unless Central runs on this same machine.
  4. Tick the box that sends alerts to Central, save, then press Test connection. It should report success.

Alerts raised from then on appear in Central. Past alerts are not backfilled. The full walkthrough is in the MeshWatch Central guide.

7. Troubleshooting

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 TrafficWatch 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. TrafficWatch switches to reporting when a traffic rule first fires. 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.