README

An in-browser SSH terminal for LibreNMS devices, opened straight from the device page — replacing the ssh:// link that hands you off to a local client.

Credentials come from HashiCorp Vault (short-lived signed SSH certificates) or from encrypted rows in the LibreNMS database, whichever suits your shop.

Status: released and in use. Installed from a signed package repository; see the roadmap for what is deliberately not here yet.

Read this before you install

This plugin turns your monitoring system into a jump host.

LibreNMS, by construction, has network reachability to every device it monitors — the broadest ACL in most organisations — and it is a public-facing PHP web application. Putting an interactive shell behind that front door is a real, deliberate increase in your attack surface. We think it can be done responsibly, which is why the defaults are closed and the threat model is published rather than buried.

Do not install this if:

You cannot commit to keeping LibreNMS itself patched.
LibreNMS is reachable from the public internet without an additional access control layer.
You have no out-of-band access path (console server, OOB management) to your devices. This plugin fails closed when its credential backend is unreachable — precisely during the incidents when you want it most.

Read docs/security/index.md — the "should you enable this?" guide — before enabling anything.

How it works

Two processes:

The plugin (PHP, installed into LibreNMS). Decides who may connect to what, resolves credentials, and mints a single-use ticket. It never opens an SSH connection.
The gateway (librenms-webterm-gw, a single static Go binary). Terminates the WebSocket, dials SSH, verifies host keys. It holds no database credentials, no Vault token, and no LibreNMS session.

Browser ──WSS──> gateway ──SSH──> device
   │                ▲
   └──HTTPS──> LibreNMS ─┘  (loopback only, HMAC-signed)

The plugin always initiates. The gateway never calls back into LibreNMS, so there is no credential-vending endpoint on your public vhost. The private key for a certificate-based session is generated inside the gateway and never crosses a process boundary; the only message on any wire carrying secret material travels over loopback.

Full detail: protocol/PROTOCOL.md and docs/architecture/.

Requirements


LibreNMS	v2 plugin system (see compatibility)
PHP	8.2+ (matches LibreNMS core)
Gateway host	linux/amd64 or linux/arm64
Credentials	HashiCorp Vault, or nothing extra for the database driver

Install

One command, on the LibreNMS server, as root:

curl -fsSLO https://github.com/AdaptiveDataNetworks/librenms-webterm/releases/latest/download/install.sh
less install.sh          # read it before you run it
sh install.sh

It shows you a plan and does nothing until you say yes. Then it:

adds the package repository, after checking its signing key against the published fingerprint, and installs the gateway from it — so later releases arrive with your normal package updates
installs and migrates the LibreNMS plugin as the librenms user, never as root
adds the WebSocket proxy to your nginx or Apache vhost, behind a marked and reversible include, restoring your config untouched if the web server rejects it
offers the SELinux boolean the gateway needs on RHEL-family hosts
proves the whole path end to end before it exits

It asks for one thing it cannot work out: the URL your operators use to reach LibreNMS. APP_URL is unset on a stock install, base_url is legitimately a bare path, and server_name knows nothing about a TLS terminator in front of it — and a wrong guess there means every terminal is refused with a 403 and nothing in the logs to explain it.

Every prompt has a flag, so --origin ... -y runs it unattended. --dry-run prints the plan and exits.

Prefer to do it by hand?

Add the repository and install the two halves yourself — see installing on bare metal. The setup helper ships in the package as librenms-webterm-setup, so you can install the gateway however you like and run just the configuration half.

Nothing can open a shell yet — the plugin ships default-deny. The 10-minute quickstart takes you from here to a working terminal.

Documentation


Quickstart	Zero to a working terminal on one device
HashiCorp Vault	The enterprise path, end to end
Security & hardening	Including "should you enable this?"
RBAC	Who may open a shell on what
Reverse proxy	nginx and Apache recipes
Troubleshooting	Symptom → cause → fix
LibreNMS updates	Read this before your next LibreNMS update

Roadmap

v1.0 — SSH. Vault (signed certificates + KV v2) and encrypted-database credential drivers. Per-device and per-group RBAC with deny precedence. TOTP step-up. Host-key pinning. Audit to the LibreNMS eventlog and off-box syslog.

Deferred, deliberately — session recording, RDP/VNC via Guacamole, just-in-time access approvals, per-user Vault identity. See the threat model and FAQ for why each was cut rather than rushed.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Security issues should not go in a public issue; see SECURITY.md.

License

GPL-3.0-or-later, matching LibreNMS. See LICENSE.

This project is not affiliated with or endorsed by the LibreNMS project or HashiCorp.

adaptivedatanetworks / librenms-webterm

Package info

Security

Statistics