TrapWatch on a server (no display)
==================================

The desktop app needs a graphical session. This folder also ships a headless
mode that does not — it receives, decodes, stores and alerts exactly the same
way, and shows the same screen in your browser instead of a window.

What a minimal server still needs
---------------------------------
Headless mode opens no window and contacts no X server, but the program is one
binary and the system loads every library that binary is linked against before
it starts. So GTK, X11, NSS and ALSA have to be installed even though nothing
draws. The .deb package lists them as dependencies and apt installs them for
you. If they are missing anyway, trapwatch-headless says so and prints the
apt / dnf line rather than leaving you with a bare "error while loading shared
libraries".

Try it in the foreground first
------------------------------
    /opt/TrapWatch/trapwatch-headless

It prints the web UI address, including a one-time token:

    web UI   http://127.0.0.1:8162/?token=...

Open that address once; afterwards http://127.0.0.1:8162/ is enough (a cookie
remembers you). Send a test trap from the same machine to see it arrive
(snmptrap is in the net-snmp package: apt-get install snmp / 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.

Run it as a service: see trapwatch-headless.service in this folder — the
commands are at the top of that file.

Options: trapwatch-headless --help
Lost the address: trapwatch-headless --show-url

Port 162
--------
TrapWatch listens on UDP 1162 by default, which any user may open. Devices
that can only send to 162 need the service to bind a privileged port: change
the port to 162 in Settings, then uncomment

    AmbientCapabilities=CAP_NET_BIND_SERVICE

in trapwatch-headless.service and `systemctl daemon-reload && systemctl
restart trapwatch-headless`. If the port cannot be opened, the reason is in the
journal (journalctl -u trapwatch-headless) as well as at the top of the screen.

Reaching the UI from another machine
------------------------------------
By default the UI only listens on 127.0.0.1. Either tunnel to it:

    ssh -L 8162:127.0.0.1:8162 user@server        # then open http://127.0.0.1:8162/

or put an HTTPS reverse proxy (nginx, Caddy) in front and start with
--ui-host 127.0.0.1 --ui-port 8162 as before. Do not expose the plain HTTP
port to an untrusted network: trap contents, community strings and the
Central token pass through it.

Secrets on a server
-------------------
There is no keyring on a server, so the licence key, alert rules and the
Central token are stored as plain files readable only by the service user
(mode 0600) under the data folder. settings.json (community strings) is
written with mode 0600 as well.

Notifications
-------------
There is no desktop to notify. A rule that would have raised a desktop
notification writes one line to the journal instead (journalctl -u
trapwatch-headless). MeshWatch Central works as on the desktop — it is the
intended alert path for a server.

Same data as the desktop app
----------------------------
Headless and desktop use the same folder (~/.config/TrapWatch for the user
that runs it, or TRAPWATCH_DATA_DIR), so a licence activated in one is active
in the other. As a service the folder is /var/lib/trapwatch/TrapWatch.
