Gateway troubleshooting¶
Symptom first. Every entry ends with something to run.
The terminal button does not appear¶
The panel renders nothing at all when the device is not an enabled target — most devices in an estate never will be, and a permanent "not configured" box on every device page would be noise.
./lnms webterm:target:enable --device=core-sw-01 --principal=netops
./lnms webterm:why --user=you --device=core-sw-01
If webterm:why says device_not_visible, the problem is LibreNMS's own device permissions, not WebTerm.
"Could not open a terminal"¶
Run the authoritative check:
It runs the real authorization path and prints the exact command that fixes the failing step.
It connects, then disconnects after about a minute¶
proxy_read_timeout in nginx defaults to 60 seconds. The gateway pings every 20 seconds, but the proxy has to allow the connection to stay open:
See reverse proxy.
Output arrives in bursts, or the terminal feels laggy¶
Proxy buffering. The terminal is an interactive stream, and buffering it defeats the point:
The browser network tab shows 403 with X-WebTerm-Reject: origin¶
WEBTERM_ALLOWED_ORIGINS does not include the origin your browser is using. Use the exact value, scheme included, then restart the gateway.
origin not permitted
The gateway will not start¶
shared secret matches a value published in documentation
Someone copy-pasted an example. Generate a real one:
Then make sure LibreNMS reads the same file.
refusing to bind a non-loopback address
The control plane has no transport security. Bind loopback and proxy to it. Only inside a container with no published ports is WEBTERM_INSECURE_CONTROL_PLANE=true appropriate.
reading shared secret ... no such file or directory
"gateway.secret exists but is not readable"¶
The gateway installs the secret as root:librenms-webterm mode 0640, so
LibreNMS reads it via group membership. Do not regenerate the secret --
the file is fine, the permissions are not.
# as root
usermod -a -G librenms-webterm librenms
chown root:librenms-webterm /etc/librenms-webterm/gateway.secret
chmod 0640 /etc/librenms-webterm/gateway.secret
systemctl restart php-fpm # or php8.2-fpm, php-fpm74, ... on your distro
Then start a fresh shell before re-running doctor -- group membership does not reach processes that are already running, including your current login:
Installs from 1.0.4 onward add the LibreNMS user to that group automatically.
"The gateway rejected our credentials"¶
LibreNMS and the gateway are reading different secrets.
# on the gateway host
sha256sum /etc/librenms-webterm/gateway.secret
# as the librenms user
./lnms webterm:config get gateway.secret_file
sha256sum "$(./lnms webterm:config get gateway.secret_file)"
The two hashes must match. If LibreNMS cannot read the file at all, add the web user to the librenms-webterm group and restart php-fpm — group changes do not affect running processes.
The host key was rejected¶
The device presented a different SSH host key than the one pinned
This is either a legitimate key change or an interception. Do not clear the pin reflexively. Compare the fingerprint against the device itself first:
If the change is expected:
./lnms webterm:hostkey-reset --device=core-sw-01 --reason="firmware upgrade 2026-09-06"
./lnms webterm:hostkey-scan --device=core-sw-01
The reason is written to the audit trail, because clearing a pin is exactly what an attacker would want done after substituting a device.
An old device will not connect at all¶
The gateway uses Go's x/crypto/ssh, which does not implement aes192-cbc, aes256-cbc or hmac-md5. No configuration can enable them — they are absent from the library. Try the legacy profile first:
If that does not help, the device is out of reach and should stay on your existing ssh:// links or a console server. See compatibility.
Sessions show as live in LibreNMS but not on the gateway¶
The reconciler is not running.
If that fixes it, Laravel's scheduler is not firing. Check your LibreNMS cron.