feature: the package installs the Router Manager, which is no longer a package of its own.
Release / release (push) Failing after 4s

This commit is contained in:
slawek committed 2026-11-14 12:52:44 +01:00
1 parent 6d90441bee
commit 8efe21bfa6
129 files changed
+17381 -104

No files matched your search

+421 -29
View File
@@ -769,9 +769,9 @@ address, and `--email ''` removes it. Changing a user's password, disabling, unl
refresh tokens of `/auth` and its codes, tokens and sessions of the OpenID Provider. The exit status is 0 on success, 2 for an invalid request, 3 when the
user does not exist, 4 when the user exists and 1 for any other failure.
When the Router Manager is installed with an administrator (its debconf questions
`vpn-router-manager/admin_username` and `admin_password`), its package leaves the answers in
`/etc/vpn-router-manager/admin.json` (root only). `vpn-router-setup` then creates that user as a
When the package is installed with a Router Manager administrator (the debconf questions
`vpn-router/admin_username` and `admin_password`), it leaves the answers in
`/etc/vpn-router/manager-admin.json` (root only). `vpn-router-setup` then creates that user as a
Manager-only account, adds it to the group `admins`, which it creates when missing, and removes
the file.
@@ -943,7 +943,7 @@ configuration: no key, identity, subnet, or address but the client's. They show
| `status_content` | `/` and `/status` show |
|---|---|
| `basic` (default) | The overall status (`ok` or `degraded`), the time and the Client IP |
| `standard` | Also the `vpn-router` version, the `vpn-router-manager` version or that it is not installed, and the number of active services and of services in any other state, without their names |
| `standard` | Also the `vpn-router` version and the number of active services and of services in any other state, without their names |
| `full` | Also each service and its state, Docker, how many site-to-site connections are set up and how many of them are established (`site_to_site`: `connections` and `established`, `null` when swanctl cannot be asked), IKEv2, OpenVPN and WireGuard |
The Client IP is the address the request came from: the last entry of `X-Forwarded-For` for a
@@ -966,16 +966,16 @@ The service is `/usr/lib/vpn-router/web`, which starts it, and the package
### Bootstrap diagnostics
Until a run of `vpn-router-setup` has succeeded, every run starts `vpn-router-bootstrap`, which
serves diagnostics as plain text on port 17081 of every address, and the firewall opens 17081 and
17080 (the Router Manager's bootstrap) on the internal interface. The first successful run stops
the bootstrap services and closes their ports, and writes `/var/lib/vpn-router/setup.done`, after
which they never run again; a failed run leaves them running, so the reason stays readable until
serves diagnostics as plain text on port 17081 of every address, and the firewall opens 17081
on the internal interface. The first successful run stops
the bootstrap service and closes its port, and writes `/var/lib/vpn-router/setup.done`, after
which it never runs again; a failed run leaves it running, so the reason stays readable until
a later run succeeds. The unit is never enabled.
The page, read again every 10 seconds, shows the state, the step and the failure of the last
setup run (`/run/vpn-router/setup.json`, which setup writes at every step), the state of the
router's services, the failed units, the addresses and routes, `cloud-init status`, and the end of
the logs of `vpn-router-setup` and `vpn-router-web`:
the logs of `vpn-router-setup`, `vpn-router-web` and `vpn-router-manager`:
```bash
curl http://10.0.0.4:17081/
@@ -999,11 +999,10 @@ curl http://10.0.0.4:17081/
The status holds the state of `vpn-router-setup`, `slapd` and each PostgreSQL cluster unit
(`postgresql@<version>-<cluster>`, or `postgresql` as `no cluster` without one), of
`vpn-router-manager` when that package is installed, of `strongswan` when site-to-site or
`vpn-router-manager`, of `strongswan` when site-to-site or
IKEv2 access is configured, of `wg-quick@wg0` when WireGuard is, and of
`openvpn-server@vpn-router` when OpenVPN is; the number of connected
OpenVPN clients, from the server's status file, which OpenVPN rewrites every 5 seconds; the package version and,
as `manager_version`, the installed version of `vpn-router-manager` (`null`, shown as not installed, without it); whether
OpenVPN clients, from the server's status file, which OpenVPN rewrites every 5 seconds; the package version; whether
Docker is installed, and when it is, the state of `docker.service` and of `vpn-router-docker`
(the Docker rules), which do not change `status`; as `site_to_site`, the number of site-to-site
connections that are set up (`connections`) and of those established (`established`, `null` when
@@ -1150,7 +1149,7 @@ vre /etc/vpn-router/vpn-router.json ~/notes.txt
### The /config page
`/config` shows what `/` and `/status` leave out, for a client such as manage-ui:
`/config` shows what `/` and `/status` leave out, for a client such as Cloud Manager:
| Key | Content |
| --- | --- |
@@ -1477,7 +1476,7 @@ and the facts for `/config` from `/run/vpn-router/web.json` (readable by root on
## HTTPS
Caddy serves the status web service on `https.web_port` (7444 by
default), while the Router Manager is installed the manager on `https.manager_port` (7443), and
default), the Router Manager on `https.manager_port` (7443), and
while metrics are enabled the metrics service on `metrics.https_port` (9465), all for `wan.local_fqdn`, while `https.enabled` is `true` and `wan.local_fqdn` is set. It obtains
and renews the certificate from Let's Encrypt with the HTTP challenge, so `wan.local_fqdn` must
resolve to the router's public address and port 80 must be reachable from the internet; the
@@ -1967,10 +1966,9 @@ A backup holds the state that `vpn-router-setup` cannot make again:
| Item | Content |
|---|---|
| `/etc/vpn-router` | `vpn-router.json`, the secrets and `rclone.conf` |
| `/etc/vpn-router` | `vpn-router.json`, the secrets, the Router Manager's settings and `rclone.conf` |
| `/etc/wireguard` | The WireGuard keys and the peers |
| `/etc/ufw`, `/etc/default/ufw` | The firewall rules |
| `/etc/vpn-router-manager` | The Router Manager's settings, when it is installed |
| `files/<path>` | Each `psk_file` outside `/etc/vpn-router` |
| `ldap/vpn-router.ldif` | The user directory, written by `slapcat`: users, groups, service accounts, password hashes and TOTP secrets, and the PKI: the CAs and their keys, the root key while it is on the router, and the certificates issued, with the keys of the router's and the users' certificates |
| `postgresql/vpn-router.dump` | With `backup.metrics`, the database of the metrics and the refresh tokens, written by `pg_dump -Fc` |
@@ -2051,13 +2049,398 @@ What it replaces is kept in `/var/lib/vpn-router/backup/before-restore/<UTC time
## Router Manager
The `vpn-router-manager` package, built in the repository `linux-cloud-router-manager`, is a web
application that shows the state of the router and manages its users, site-to-site
connections, backups and certificates through the status web service. It can be installed on the router or on another Linux system. While it is installed on
the router, `vpn-router-setup` opens its port (`port` in `/etc/vpn-router-manager/manager.json`,
7080 by default, HTTP; HTTPS is Caddy's, on `https.manager_port`) on the internal and the external
interface; restart `vpn-router-setup` after changing it. The manager's `listen` chooses the
interfaces it listens on.
The Router Manager is the package's web application: it shows the state of the router and manages
the users of its OpenVPN and IKEv2 access. Users sign in with their user name, password
and, when enrolled for one-time passwords, the code, or with a passkey they added on their
account page; only members of the router's group `admins`
can use the tabs, as the router decides. Every user has an account page at `/user`, which is the
only page of a user who is not a member of `admins`. Administrators switch between Router (`/`:
the Overview, Metrics, Logs, Backup and System tabs), Identities (`/user-manager`: the Users, Groups and Service
Accounts tabs), Connectivity (`/site-to-site-manager`: the Status, Network and Connections tabs), Remote
Access (`/remote-access-manager`: the IKEv2, OpenVPN and WireGuard tabs), Certificates
(`/ca-manager`), Web Sites (`/sites-manager`: the Sites, Files and DNS tabs) and
Docker (`/docker-manager`) with the page menu at the
right end of the header, a button naming the page shown. The button with the signed-in user's
name, left of Sign out, opens the account page, and the terminal icon left of it the Shell
(`/shell`); pressed on its page, each returns to the page it was opened from.
- **Help** (the question mark in the header between the theme switcher and the page menu, for every
signed-in user): a panel on the right, under
which the page moves left, with the help topic of the page and tab shown. The topics are the
Markdown files of `docs/` (`index.md` and one per page or tab), served by the manager at `/docs`
and rendered in the browser with marked and DOMPurify, in the style of github-markdown-css in
the light or dark scheme. A link to another topic opens it in the panel; Back returns to the
previous one and the house icon to `index.md`. Topics link to SVG and PNG pictures by paths
relative to their folder. The browser keeps whether the panel is open.
- **Settings** (the gear in the header, hidden on the sign-in and the account page): how often the Overview and the Metrics tab read the router
on their own, kept in the browser's localStorage, so each browser has its own. Each tab reads
manually, or every 5, 10 or 30 seconds, 1, 5 or 15 minutes; the Overview tab every 10 seconds and
the Metrics tab every minute by default. Manual reads when the tab opens and on Refresh. A change applies at once, also in the browser's other tabs; Defaults sets both back.
- **Account** (`/user`): the Account and the Passkeys panel side by side, with One-time passwords
and VPN profiles below. The user's name, kind, names, e-mail address, whether they are an
administrator and whether they are enrolled for one-time passwords; Change password in the
Account panel, which opens a dialog and signs the user out after the change; enrolling an authenticator app or replacing it; and the user's passkeys,
each with its label and when it was added, with Add a passkey and a remove icon. Each change but
the removal of a passkey asks for the current password and, for an enrolled user, a code not
already used to sign in. Removing the enrolment is left to an administrator. A VPN user downloads
the own OpenVPN profile (`.ovpn`) and the Apple VPN profile of the router's IKEv2 access
(`.mobileconfig`), each with the current password and the code when enrolled, the Apple profile
also with a password that protects the key in it.
- **Passkeys:** Sign in with a passkey on the sign-in page uses a passkey the browser or the
user's password manager offers for the router's `wan.local_fqdn`, without the user name, the
password or the code. Passkeys work on the Manager's HTTPS address on that name only, not on
another name or in development on `localhost`, and in browsers with the JSON methods of WebAuthn
Level 3. They sign in to the Manager, and open a shell on the Shell page in place of the password
and code.
- **Certificates** (`/ca-manager`, in the page menu of administrators): the router's two-level CA, from its `/ca`, in tabs:
- **Root:** the root CA's subject, expiry, whether its key is on the router, marked with a warning sign, or offline, and its CRL, with Download root CA, the root's certificate alone, and Upload CRL for a root CRL signed offline; the general information: where certificates and CRLs are published, the CA key type, the lifetimes, and the CRL validity; the certificates of the issuing CAs, each active one with a download icon for its CA bundle, and the retired ones.
- **Templates:** the certificate templates with their key, lifetime, subject, usages, alternative names, certificate policies and the CAs that issue them; Add template, Edit on each, Remove on one of the router's own and Reset on a changed built-in one, which brings back its defaults. A template's extended key usages are chosen from those of the next tab, and its certificate policies are OIDs typed in.
- **Extended key usages:** the usages templates may give, with their OIDs and the templates that give them; the built-in ones are shown and not changed, and custom ones are added with a name and an OID, and changed or removed.
- **P2S Issuing CA** and **S2S Issuing CA:** the CA's common name, state (active, or pending while it waits for the offline root), expiry, CRL and templates, and the certificates it issued. An active CA gives its CA bundle, the issuing CA followed by the root, with Download CA bundle; a pending CA gives its CSR with the openssl extensions to sign it with, and takes the certificate signed by the root.
- **Issuing CAs:** the general-purpose CAs with their state, expiry, CRL, templates and ACME directory URL; Add issuing CA, and Edit and Remove on each: its name, fixed once it exists, its common name, the templates it issues and its ACME server; an active CA's download icon gives its CA bundle. A removed CA is retired by the router, which revokes its certificate on the root CRL. Below, their certificates, filtered by CA. - **Certificates:** each with its kind, template, names, expiry and state; a certificate of another system or of the router is revoked after a confirmation with a reason.
- **Issue** (above the tabs): from a CSR, saving the certificate with its chain, or with a key the router makes, saving a PFX file protected by a password; the router keeps no copy of the key.
- **Settings** (above the tabs): the names, lifetimes, key type, CRL validity and publishing endpoints.
- **Warnings** (above the tabs): what the router says needs attention, such as a CRL about to expire.
The root key is exported, removed and imported on the router with `vpn-router-ca`, never through the Manager.
- **Overview**: the router's overall status, ok or degraded, on the title bar of the Status panel;
at the top of that panel, a table of `vpn-router`
with the installed version and, when the repository has a newer one, that version; Check update
is always in its top right corner, and Upgrade is added beside it when an update is found. Then
IKEv2, OpenVPN and WireGuard, read from the router's authenticated `/status/full`, and from its `/config` the status web service and its port, whether HTTPS is on and for which name, with a chip while Caddy takes Let's Encrypt's staging CA and a settings button that switches it (`https.acme_staging`, through the router's `/https/settings`), and Caddy, its HTTPS proxy: its version, whether it comes from Ubuntu or upstream (switched on the router with `vpn-router-caddy use-upstream`) with the configured `https.caddy_source` when that differs, and the state of `caddy.service`. The Services panel shows the state of each of the router's
systemd services and of Caddy, with a chip on its title bar telling whether the router's services are active. The Addresses panel links, opening in a new tab, to the status page over HTTPS and over plain HTTP on the addresses `web.listen` names, and to the Router Manager over HTTPS, and shows the issuer and the discovery URL of the router's OpenID Provider, each with an icon that copies it, or off while the provider is disabled. Further panels
show each PostgreSQL cluster of the
router with its main settings and its databases with their sizes, and one Configuration panel
with a group of rows under a heading for each section the other pages do not show, the status web service (`web`) and HTTPS (`https`) among them, read
every 10 seconds by default (see Settings). Nothing is read, and Refresh is off, while a check
for updates, an upgrade or a reboot runs; the tab reads again when it ends.
- **Panel controls:** each panel folds by its title bar, and every panel but Status hides by its [X]; Panels shows them again.
- **Edit layout:** moves panels by dragging and switches each between one column and both.
- **Layout storage:** kept in the browser.
- **Metrics**: charts of the router's CPU, memory, free disk space in bytes and in percent, the
bytes per second of each interface, the VPN clients and the load averages, and, with a line per
site-to-site connection, Site-to-site up, Site-to-site traffic and Site-to-site packets. They
cover the last hour, day, month or year, each bucket as its average or its maximum. Site-to-site
up is the percentage of time each connection was up, 0 to 100, in slots of 5 minutes for an
hour, 1 hour for a day, 1 day for a month and 1 month for a year, as the router computes it;
Average and Maximum do not change it. The charts are read every minute by default (see
Settings) from the router's `/metrics/history`. The charts fold, hide, move and change width as the Router
tab's panels do, with a layout of their own. A click on a line's legend item hides or shows the
line, for example the 1 and 5 minute load averages to see the 15 minute one; the browser keeps
the hidden lines of each chart. Settings edits the router's `metrics` section through its
`/metrics/settings`: whether the metrics service runs, the interfaces and the ports of
`/metrics`, its service account, the OTLP endpoint with its user name and password, and how long
each level of the history is kept. An empty password keeps the current one.
- **Logs**: the last lines of the router's logs, from its `/logs`. The Journal sub-tab shows the
systemd journal of a unit the router names, or of all units, and the Files sub-tab a log file of
the router's `web.log_files`, set on the router with `vpn-config-edit`. 100, 200, 500 or 1000
lines, up to the router's limit of one read, are read when the unit, the file or the number
changes and on Refresh. While Follow is on, the log is read every 2 seconds and kept scrolled to
its last line, as `tail -f` shows it.
- **Users**: the users with their names and e-mail addresses, without the service accounts, all
of them, the VPN users or the Manager-only accounts, searched by user name, names and e-mail
address, with adding (user name, first
name, last name, e-mail address and password, or, with Manager access only, a Manager-only
account with the user name, the password and an optional e-mail address: no certificate and no
VPN access), editing the names and the e-mail address of VPN users and the e-mail address of
Manager-only accounts,
setting the password, disabling, enabling, unlocking after failed logins, removing and
downloading the OpenVPN client profile, offered only while the router runs OpenVPN, and the Apple VPN profile
(`.mobileconfig`, IKEv2), offered only while the router runs IKEv2 access, whose dialog takes the
password that protects the user's key in it, and whether each is enrolled for TOTP one-time passwords. Enrolling shows a new secret as a QR
code and as text for an authenticator app, and stores it once a code of the app is entered;
the enrolment can be removed. The Passkeys column shows how many passkeys each user has, and
the remove icon removes all of them after a confirmation. The Console column shows the console
login of each member of `admins`: off, the user's own LDAP POSIX account with its uid, or the
local account it runs as, marked as refused while the user is not enrolled for TOTP; root
switches it on the router with `vpn-router-user console`, the Manager does not.
- **Groups**: the groups with their descriptions and members, searched by name, description and
member, with adding a group, editing its
name, description and members in one dialog, and removing it. A group has at least one member;
the members offered are the users and the service accounts but the internal ones.
- **Service Accounts**: the accounts other systems sign in with to use the router's services, such
as an OpenTelemetry Collector reading `/metrics`, from the router's `/service-accounts`; they
cannot sign in to the Manager. Each is shown with its display name, description, kind, e-mail
address, OpenID Provider settings and state, searched by name, display name, description
and e-mail address, with adding one (name, a new GUID unless a user name replaces it, display
name, description, an optional e-mail address, the OpenID Provider settings and a password),
editing the display name, the description, the e-mail address and the OpenID Provider settings,
setting the password, disabling, enabling, unlocking after failed logins and removing after a
confirmation. An account with redirect URIs or grants is a client of the router's OpenID
Provider, its name the client ID and its password the secret; its settings are the redirect URIs
and the post-logout redirect URIs, one per line, the allowed groups, chosen from the router's
groups, whose members alone may sign in to it, the client credentials and device authorization
grants, whether it is a public client without a secret, and the scopes of resources it may ask
for. Every account is also a resource of the provider, with its scopes and its roles, each
assigned to groups, users and service accounts, which the tokens for it carry. While the
provider is enabled, the title of the list has the number of its clients.
Internal accounts, which the router creates and manages for its own services with all their
properties, display name and description included (at present the metrics service's), are
marked Internal and only listed: the router refuses every change of them through its API, so
they have no actions here.
- **Connectivity**, Connections tab: the router's IPsec site-to-site connections with their remote peer, remote
identity, remote and local CIDRs, local identity mode, authentication (whether the pre-shared key
is set, read from a file or missing, or, with certificates, whether the peer's CA is the router's
site-to-site CA or a remote CA) and whether the tunnel is established; with adding a connection,
editing it and removing it after a confirmation. With a pre-shared key, the key is typed as a
password, required while the connection has none and kept when left empty, and is never shown;
with certificates, the PEM certificate of a remote CA is optional. The router applies a change in the
background by running its setup again; the list is read again after each change. The
connection the router was installed with is `remote-site`; Cloud Manager names the one it
deploys with `router_site_to_site_name`, `remote-site` by default.
- **Connectivity**, Status tab: each connection the router set up, with the local and the
remote identity and the subnets it resolved, and how long the connection has been up, and their
IPsec security associations, child SAs, connections and connection children, from the router's
`/config`. The other IPsec connections, IKEv2 access, are on the IKEv2 tab of Remote Access.
- **Connectivity**, Network tab: the external and the internal interface with their addresses, the
internal gateway and the local CIDRs, and the IPv4 routes, from the router's `/config`; the panels
fold, hide, move and change width, and the browser keeps their layout.
- **Remote Access** (`/remote-access-manager`): a tab each for IKEv2,
OpenVPN and WireGuard access, from the router's `/remote-access` and `/status/full`: the
settings, whether the router runs the system, why an enabled one does not run yet, and the
connected clients; for IKEv2 the IPsec security associations, child SAs, connections and
connection children of IKEv2 access, all but the site-to-site ones, from the router's `/config`;
for WireGuard each connection with its user, found by the peer's key (a short
key for a peer added to `wg0.conf` by hand), its IPs, endpoint, handshake and traffic, from the
router's `/config` and `/users`. Edit enables or
disables the system and sets its address pool, for WireGuard the address of `wg0`, for IKEv2 the
DNS domains its clients resolve with the router's DNS, one per line, and the port, with OpenVPN's
protocol; the router applies a change in the background. The WireGuard tab also
lists the peers of the VPN users, each a device with its user, public key and IPs: a peer is
removed with its button after a confirmation, and added with Add peer, whose dialog takes the
user, the device's public key and the IPs, which start as the next free address of the `wg0`
network. The router keeps the peers with their users and checks that keys are unique and
IPs do not overlap. Its Server section shows the router's public key, with a copy button, the
endpoint and the allowed IPs a device needs; Show config opens a device's configuration, ready to
copy, with placeholders for the device's private key and IPs and, while it runs, the router's
resolver as the device's DNS server. The eye of a peer opens its device's
configuration the same way, with the peer's IPs as its address. In both dialogs a switch leaves
out the `[Interface]` and `PrivateKey` lines, which WireGuard for Windows fills in for a new empty
tunnel, so the rest pastes below them; the browser keeps its position with its other settings.
Each peer's configuration downloads as
`<user>-<n>.conf` with them filled in and a placeholder for the device's private key, which the
router never has. IKEv2 and OpenVPN also need `wan.local_fqdn` and the
router's VPN server certificate. A cloud firewall in front of the router, such as an Azure
network security group, must allow the OpenVPN and WireGuard ports itself.
- **Web Sites** (`/sites-manager`): the static web sites the router's Caddy serves, from its
`/sites` and `/dns`, in tabs:
- **Sites:** the Settings panel shows whether the sites are served, the largest upload and
WebDAV with its URL and a copy icon, edited with Settings. The list shows each site with its
URLs, linked, its port, the interfaces whose firewall opens it, its TLS (none, Let's Encrypt,
an issuing CA of the router or a certificate and key) and its editors group, searched by name,
host name and group; Add and Edit take the name, fixed once added, the host names, one per
line, the port, the interfaces, the TLS with the issuing CA or the PEM certificate chain and
key, pasted or read from files, the key kept when left empty, the index file, the single-page
fallback and the editors group. Enable, Disable and Remove, which removes the site's folder too
when asked; the folder icon opens the site on the Files tab.
- **Files:** the files of the chosen site, a folder at a time, with the path linked up to the
site's folder. Upload sends chosen files, or files dropped on the list, into the folder shown,
with a progress bar; while Extract zip archives is on, a `.zip` file is extracted there
instead. New folder, Rename, Remove and Download. A file larger than the router's largest
upload is not sent.
- **DNS:** the router's primary name server: its settings with whether PowerDNS is installed
and runs, the router's FQDN as the primary name server, edited with Settings (enabled,
secondary name server, public IP address, interfaces, TTL); the domains, added with Add
domain (domain, TTL), edited and removed with their icons; and for the selected domain the
records it serves, and its manual records, added with Add record (name, type, content and
TTL) and removed with their icon.
- **Docker** (`/docker-manager`): whether Docker is installed, the state of `docker.service` and of
the router's Docker rules, the ports exposed on the external interface and the rules of the
`VPN-ROUTER-DOCKER` chain, from the router's `/status/full` and `/config`.
- **Shell** (`/shell`, the terminal icon in the header): a login shell on the router in xterm.js, the terminal of VS Code, as the
signed-in user's console account, the user's own LDAP POSIX account or a local account. Opening
it asks for the password and the code again, or Open with a passkey takes one of the user's
passkeys, unlocked with the device's PIN or biometrics, unless the user used a shell within the
router's `web.shell_auth_timeout` minutes. A user without console login sees how root switches it on,
and one not enrolled for one-time passwords that the shell needs the enrolment. The router offers the shell only while its `web.shell` is `true`, set
on the router with `vpn-config-edit`, and closes it after `web.shell_idle_minutes` without a
keystroke; the page then shows the reason and keeps the terminal readable.
- **Editor:** `vre FILE...` (`vpn-router-editor`) in the shell opens the files in a Monaco editor on the page, one tab per file, and returns at once. The router names each file in a text message of the shell's WebSocket, and the page reads and saves it through `/api/shell/editor/<session>/<id>`, as the console account. Saves have a body limit of 2 MiB plus 64 KiB, for a file of up to 1 MiB escaped in JSON; other calls keep 64 KiB.
- **Editor icon:** while a file is open, an icon left of the shell icon switches the page between the terminal and the editor, and the shell keeps running. A button left of Save shows or hides the minimap, remembered by the browser. Save or Ctrl+S writes the file; a file changed on the router since it was read offers Reload or Overwrite. Closing a tab with unsaved changes asks first, and the icon goes when the last tab closes or the shell ends.
- **Loading:** Monaco is bundled with the page, without its language services, and loaded only when the first file opens.
- **Backup**: the router's backups, from its `/backup`:
- **Settings:** whether scheduled backups run, the schedule (hourly, daily or weekly), the target and whether the metrics database is included. For a local folder it also shows the folder, the archives kept and the cloud copy with rclone; for a Proxmox Backup Server, the repository, whether the token secret is set, the fingerprint, the namespace and the encryption key file.
- **Last run:** its result, times, archive or snapshot, size, cloud copy and error, and the next run.
- **Local archives:** with their times and sizes, searched by name and time, and shown 10, 25, 50 or 100 at a time.
- **Edit:** changes the settings in one dialog. Only the retention settings that apply to the schedule are offered. The rclone remote is chosen from the remotes of the router's `/etc/vpn-router/rclone.conf`, with a path and the mode, sync or copy. The token secret is typed as a password and kept when left empty. The router applies a change in the background.
- **Run now:** starts a backup, and the tab reads every 3 seconds until it ends.
- **Warnings:** shown when the PBS client or rclone the settings need is not installed on the router.
Restoring is done on the router with `vpn-router-backup restore`. The Overview tab has a Backup panel with the result of the last run, the next run and Run now.
- **System**: the router's operating system. The System updates panel lists the packages `apt-get upgrade` would upgrade, each with its installed and its new version, from `/api/system-updates`; Check update is always in its top right corner, and Upgrade is added beside it when a package can be upgraded. Upgrade runs `apt-get upgrade -y` after a confirmation and shows its output in a dialog, as Upgrade on the Overview tab does, with Reload page and Reboot when they apply.
### How it works
`vpn-router-manager.service` runs `/usr/lib/vpn-router/manager`, a Python server that
calls the router with `python3-requests` and keeps sessions in PostgreSQL with `python3-psycopg`.
It serves the application from `/usr/share/vpn-router/manager/web`.
- `POST /api/session` with `{"name", "password", "code"}` signs in through the router's `/auth`,
passing the browser's address in `X-Forwarded-For`; on success the manager keeps the user's
access and refresh tokens in the table `sessions` and sets the cookie
`vpn_router_manager_session` (`HttpOnly`, `SameSite=Strict`), which holds a random id of which
only the SHA-256 is stored. `GET /api/session` answers `{"name"}` of the signed-in user, and
`DELETE /api/session` signs out and revokes the refresh token.
- Every other call to `/api/<path>` needs a session and is passed to the router's status web
service at `/<path>` with the session's access token, renewed through `/auth/refresh` when it
expires within 30 seconds. The method, the body and the router's answer pass unchanged. A
session ends when the router refuses to renew it; sessions are kept across restarts.
- `GET`, `HEAD` and `PUT` of a web site's files, `/api/sites/<name>/files/<path>`, pass streamed:
the body of a `PUT` goes to the router as it arrives, with its `Content-Type` and
`Content-Length`, which it needs, and without the limit of 65536 bytes, and the router's answer
comes back with its `Content-Type`, `Content-Length` and `Content-Disposition`, so a download is
not held in memory either. The router's `sites.upload_max_mb` limits an upload.
- `GET /docs/<file>`, with a session, gives a file of the help from
`/usr/share/vpn-router/manager/docs`, which the package installs from the repository's `docs/`:
Markdown (`text/markdown`), SVG or PNG; any other file, or a path outside the folder, is 404.
The answers carry `X-Content-Type-Options: nosniff` and a `Content-Security-Policy` that keeps
an SVG opened on its own from running scripts.
- A WebSocket handshake on `/api/shell`, with a session and an `Origin` of the page's own host,
is passed to the router's `/shell` with the session's access token; after both handshakes the
manager relays the WebSocket's bytes both ways until either side closes. `POST /api/shell`, which
gives the ticket the handshake needs, and `POST /api/shell/passkey`, which begins the passkey
proof it may take, pass as every other call does.
- `/api/info` gives the version of the package and the URL of the router's status page, without a
session. On the router, while `router_url` and `terraform_dir` are not set and the status web
service listens on the address the call came in on, the URL has the name or address the browser
used and `web.port`, for example `http://router.example.com:7081`, and for a page opened over
the router's HTTPS proxy `https` and `https.web_port`, for example
`https://router.example.com:7444`; otherwise it is `router_url`.
- `/api/updates`, with a session, gives the installed and the candidate version of `vpn-router`
from `apt-cache policy`, that is from the repository apt is configured with,
as of apt's last update of its package lists (`/var/lib/apt/periodic/update-success-stamp`,
answered as `checked`), whether an update is available, and as `checking` whether a check for
updates runs. The Overview tab shows it at the top of its Status panel. Where apt cannot be asked, such as
on a workstation, it answers `"available": false`.
- `POST /api/updates`, by a member of `admins`, checks for updates: it runs `apt-get update` in the
transient unit `vpn-router-manager-check` outside the manager's unit, waiting up to 5 minutes for
apt's lock, and touches `update-success-stamp` when it succeeds. The page's Check update button
starts it and reads the versions again until it ends.
It answers 202 when started, 409 while a check, an upgrade or a reboot runs, 403 for a user who
is not an admin, and 503 where apt is missing.
- `/api/system-updates`, with a session, gives the packages `apt-get upgrade` would upgrade, from
its simulation (`apt-get -s upgrade`), each with its installed and its candidate version, in the
shape of `/api/updates`. The System tab shows it; Check update there is `POST /api/updates`.
- `POST /api/upgrade`, by a member of `admins` (the router's `/account` decides), upgrades
`vpn-router`; the page's Upgrade button starts it.
- **Where it runs:** the helper `/usr/lib/vpn-router/upgrade`, in the transient unit `vpn-router-manager-upgrade` (`systemd-run`) outside the manager's unit. The manager's own restart and the router web service's restart during the upgrade do not end it.
- **What it does:** first `dpkg --configure -a`, then `apt-get install --only-upgrade`. It asks nothing, keeps changed configuration files, and waits up to 5 minutes for the dpkg lock.
- **Record:** the state goes to `/var/lib/vpn-router/upgrade.json` and the output to `upgrade.log`.
- **Answers:** 202 when started, 409 while an upgrade or a reboot runs, 403 for a user who is not an admin, 503 where apt is missing.
- `GET /api/upgrade`, with a session, gives that state and the last 200 lines of the output.
- **States:** `idle`, `running`, `succeeded`, `failed`, or `interrupted` when the upgrade ended without recording a result.
- **Reboot information:** whether `/var/run/reboot-required` exists, the packages that ask for it, and whether a reboot is about to happen.
- `POST /api/system-upgrade`, by a member of `admins`, upgrades the system's packages, and `GET /api/system-upgrade` gives its state, as `/api/upgrade` does for `vpn-router`.
- **What it does:** the helper with `--system`, in the transient unit `vpn-router-manager-system-upgrade`: first `dpkg --configure -a`, then `apt-get upgrade -y`, with the same options.
- **Record:** `/var/lib/vpn-router/system-upgrade.json` and `system-upgrade.log`.
- **Answers:** as those of `/api/upgrade`; only one of the two upgrades runs at a time, and either answers 409 while the other runs.
- `POST /api/reboot`, by a member of `admins`, reboots the router 5 seconds later (the transient timer `vpn-router-manager-reboot`), and answers 409 while an upgrade runs. The page offers it when a reboot is required.
| Answer | When |
|--------|------|
| 401 | Not signed in, or the session has ended |
| 403 | The router refuses the user, who is not a member of `admins` |
| 502 | The router cannot be reached |
| 503 | No router or no session database is configured, or the database fails |
| 413 | The request body is larger than 65536 bytes, but for the upload of a site's file |
| 411 | The upload of a site's file has no `Content-Length` |
The router's rate limit of sign-ins counts the browser's address when the manager's address is
in the router's `web.trusted_proxies`; by default that is the router's address the call came in
on, which is the address a manager on the router calls from, so it needs nothing more.
On the router, the router's Caddy serves the manager over HTTPS on `https.manager_port` of
`vpn-router.json` (7443 by default) for `wan.local_fqdn`, with a certificate from Let's Encrypt,
and calls it on `127.0.0.1`, where the manager also listens. For a call from `127.0.0.1` with
`X-Forwarded-For`, the manager takes the browser's address from the last entry of that header.
The service needs nothing else to start and keeps running. Every 30 seconds it works out where to
listen and starts, moves or stops a server on each address to match, so a change of `listen`,
`bind` or `port` takes effect within 30 seconds, or when the service restarts. Each request
reads the settings again.
Before it listens, it creates its sessions database on the router when it is missing and connects
to the sessions database, retrying every 15 seconds and logging each failure, for example while
PostgreSQL is not running yet.
### Settings
`/etc/vpn-router/manager.json` (all optional; see
`/usr/share/doc/vpn-router/manager.json.example`):
| Setting | Meaning | Default |
|---------|---------|---------|
| `router_url` | The router's status web service | `http://<first address of the web service>:<web.port>`, the internal address when it listens on both |
| `database` | A PostgreSQL connection string for the sessions | The `vpn-router-manager` database on the router |
| `listen` | The interfaces to listen on when `bind` is not set: `internal`, `external` or `both`, and always `127.0.0.1` | `both` |
| `bind` | The one address to listen on; the router's HTTPS proxy reaches the manager only when it is `127.0.0.1` | none, `listen` applies |
| `port` | The port to listen on, HTTP | `7080` |
| `terraform_dir` | A Terraform root directory whose outputs give `router_url` when it is not set; `dev.sh` sets it | none |
| `iac_tool` | The tool that reads the outputs of `terraform_dir`: `terraform` or `tofu` | `terraform` |
From the outputs of `<iac_tool> -chdir=<terraform_dir> output -json`, read every 30 seconds at
most, `router_url` is the output `router_web_url`, the status web service's URL on the router's
private address with its port. It needs that tool, the
one the root directory was initialized with, and access to the state.
The addresses
of the interfaces `listen` names are worked out as `general.mode` directs, as the status web
service does, and `vpn-router-setup` opens `port` on the internal and the external interface;
restart `vpn-router-setup` after changing `port`. When `database` is not set, the manager creates the role and the database
`vpn-router-manager` on the router's PostgreSQL on its first run, with a password in
`/etc/vpn-router/manager-database.secret` (root only), and reaches it over TCP on `localhost`.
Make `manager.json` readable by root only when its `database` holds a password.
#### First administrator
The package asks two debconf questions on a fresh installation, `vpn-router/admin_username`
and `vpn-router/admin_password`. With both answered, it writes them to
`/etc/vpn-router/manager-admin.json` (root only) and clears them from debconf;
`vpn-router-setup` creates that user as a Manager-only account in the group `admins`, creating
the group when missing, and removes the file. Without a user name no account and no group is
created. They can be preseeded:
```sh
echo 'vpn-router vpn-router/admin_username string admin' | debconf-set-selections
echo 'vpn-router vpn-router/admin_password password s3cr3t-pass' | debconf-set-selections
```
### Running the application on a workstation
`dev.sh` runs the manager and the Vite development server, which reloads on changes, on the
workstation; the application is at http://localhost:5180. Its first argument is the
`config.json` of the platform that deployed the router. Its `module_root`, relative to the
directory of that file, is the Terraform root module whose outputs give the router's address.
The second argument, optional, is the connection string of a PostgreSQL database for the
sessions; without it the sessions are kept in the database `PGDATABASE` names, or the one named
after the login, and libpq takes the server, port, user, password and SSL mode from the `PG*`
variables of the environment, such as those of the platform's `pg.env.sh`. `dev.sh` writes them
as `terraform_dir` and `database`, with the platform's `iac_tool` and `bind` `127.0.0.1`, to `dev.json` in the repository root, which is not in Git, and
the manager reads that and listens on `127.0.0.1:7080`:
```sh
./dev.sh /path/to/azure-platform/config.json
./dev.sh /path/to/azure-platform/config.json 'host=localhost dbname=manager user=manager password=secret'
```
It creates `.venv` with `psycopg[binary]` and `requests` when they are missing, and installs the npm dependencies
when they are missing or out of date. The manager also takes `--config <file>` in place of
`/etc/vpn-router/manager.json`.
The Vite servers pass `/api` to `VITE_MANAGER` (`http://127.0.0.1:7080` by default), so the built
application runs against any manager, at http://localhost:4180:
```sh
cd web
npm install
npm run build
VITE_MANAGER=http://10.0.0.4:7080 npm run preview
```
## Removal
@@ -2070,8 +2453,9 @@ may be in use by something else.
`apt-get purge` additionally removes the generated files and the firewall rules, restoring
`/etc/ufw/before.rules` to its original content, and hands `vpn-router.json` back to `ucf`
before deleting it so a later reinstall starts clean. It also removes the web service's
signing key and the OpenID Provider's, the password file of the metrics service account, the database of the refresh
tokens and the metrics and those of the web sites and the name server, their roles and their password
signing key and the OpenID Provider's, the password file of the metrics service account, the Router Manager's
settings and the record of its last upgrades, the database of the refresh
tokens and the metrics and those of the web sites, the name server and the Router Manager's sessions, their roles and their password
files when the package created them, Caddy's configuration `/etc/caddy/vpn-router.Caddyfile` and PowerDNS's
`/etc/powerdns/pdns.d/vpn-router.conf`; the certificate in
`/var/lib/caddy` belongs to the `caddy` package. It removes the backup timer's schedule, the
@@ -2086,11 +2470,19 @@ key pair, everything under `/etc/swanctl`, the folders of the web sites in `/var
## Building
```sh
cd debian-package
./build.sh
```
The build runs in a container and writes the package to `debian-package/out/`.
`./publish.sh` uploads it to the component `main` of the distributions `noble` and `resolute` of
the configured repository, skipping a distribution that has the version already;
The build runs in a container from the repository root: a Node.js stage builds the Router
Manager's application in `web/` with Vite, and an Ubuntu stage builds the package from
`debian-package/`, with the application and the help in `docs/`, and writes it to `out/`. The
container runtime is Apple's `container` on macOS and Docker on Linux, or `CONTAINER_RUNTIME`
when set, for example Docker on a remote engine:
```sh
CONTAINER_RUNTIME=docker DOCKER_CONTEXT=build-host ./build.sh
```
`./publish.sh` uploads the package to the component `main` of the distributions `noble` and
`resolute` of the configured repository, skipping a distribution that has the version already;
`DISTRIBUTIONS` names others.