diff --git a/ADR.md b/ADR.md index 7d6dcaa..4c7bc82 100644 --- a/ADR.md +++ b/ADR.md @@ -13,16 +13,16 @@ router. Decision: The package secures Docker itself. A `docker` configuration section has `mode` (`auto`, `on`, `off`) and `exposed_ports`. In `auto` mode the rules are applied when `docker.service` is installed, which is what the package looks up; `on` requires Docker and -`off` removes the rules. The rules are in a chain of their own, `VPN-ROUTER-DOCKER`, entered by +`off` removes the rules. The rules are in a chain of their own, `LINUX-MANAGER-DOCKER`, entered by one jump at the top of `DOCKER-USER`. For traffic from the external interface they accept IPsec protected traffic, TCP to `exposed_ports` and established connections, and drop the rest. The -`vpn-router-docker` unit applies them after `docker.service` starts and removes them when it -stops; `vpn-router-setup` restarts it while Docker runs. +`linux-manager-docker` unit applies them after `docker.service` starts and removes them when it +stops; `linux-manager-setup` restarts it while Docker runs. Consequences: Installing Docker first is recommended; `auto` mode then finds it as soon as the package is configured. When Docker is installed after the package, the rules are applied by -restarting `vpn-router-setup`, a reboot or a restart of Docker, not by Docker's first start, -because `vpn-router-docker` is already active. A published +restarting `linux-manager-setup`, a reboot or a restart of Docker, not by Docker's first start, +because `linux-manager-docker` is already active. A published port is reachable from the external interface only when it is in `exposed_ports`. Other rules in `DOCKER-USER` are not touched, because the package owns only its own chain. Restarting Docker restores the rules. The rules cover IPv4 only. @@ -31,28 +31,28 @@ restores the rules. The rules cover IPv4 only. Status: Accepted -Context: The router has no way to see its state without a shell. A check from the protected +Context: The server has no way to see its state without a shell. A check from the protected network, by a person or by a monitor, needs a page or an endpoint, and so does the platform that -deploys the router, which reaches it on its public address. The router is an internet-facing +deploys the server, which reaches it on its public address. The server is an internet-facing host, so what the service shows and where it listens matter. -Decision: The `vpn-router-web` unit runs one Python script on the standard library's +Decision: The `linux-manager-web` unit runs one Python script on the standard library's `http.server`, with the package's own modules and the Python packages of the Ubuntu archive that the package depends on, and no web framework. It listens on `web.port`, 7081 by default, on the address of the internal interface, of the external interface or of both, as `web.listen` sets (`internal`, `external` or `both`, the default), with a server for each address, and is on unless `web.enabled` is `false` (ADR-7). `/` is for people, in plain text for `curl` and `wget` and as a Tailwind CSS page for a browser, and `/status` is the same status as JSON. Both show as -much as `web.status_content` says, since the router is reachable from the internet and the +much as `web.status_content` says, since the server is reachable from the internet and the operator decides how much it tells strangers: `basic`, the default because it tells the least, the overall status and the Client IP, `standard` also the package versions and the number of active and other services, and `full` also each service and the state of the site-to-site, IKEv2, OpenVPN and WireGuard features. The Client IP is the address the request came from, through the trusted -proxies, so a person can see the address the router sees. Nothing comes from the configuration. -`/status` names its content, so clients such as Cloud Manager and the Router Manager show what it -has. `vpn-router-setup` opens the +proxies, so a person can see the address the server sees. Nothing comes from the configuration. +`/status` names its content, so clients such as Cloud Manager and the Manager show what it +has. `linux-manager-setup` opens the port on both interfaces in UFW, so the choice of `web.listen` is made by the service alone, and -writes the features and the facts it resolves to `/run/vpn-router/web.json`. +writes the features and the facts it resolves to `/run/linux-manager/web.json`. Consequences: By default the service is reachable from the internet on the external address; `web.listen` set to `internal` keeps it to the internal network. It serves plain HTTP itself; @@ -64,29 +64,29 @@ read only and show no configuration. It runs as root, because `swanctl` and `wg` `ProtectSystem=strict`, `ProtectHome` and `PrivateTmp`. The Tailwind style comes from a CDN, so a browser on a network without internet shows the unstyled page, and `curl` is unaffected. -## ADR-3: The protected paths take JWTs that only the router signs +## ADR-3: The protected paths take JWTs that only the server signs Status: Accepted -Context: Clients such as the Router Manager, and people with `curl`, need the configuration, -the users and the groups of the router, which `/` and `/status` must not show. Both people and +Context: Clients such as the Manager, and people with `curl`, need the configuration, +the users and the groups of the server, which `/` and `/status` must not show. Both people and programs sign in with a user of the directory. A secret shared with the platform that deploys -the router would let whoever holds it, and every copy of the deployment's state, make tokens. +the server would let whoever holds it, and every copy of the deployment's state, make tokens. The service listens on plain HTTP. Decision: `/config`, `/users` and `/groups` need a JWT in an `Authorization: Bearer` header, HS256, verified with `hmac` and `hashlib`; no other algorithm is accepted. The key is -`/etc/vpn-router/web.key`, random, made by the web service on its first run and readable by root -only; it is never configured or output. The router itself issues +`/etc/linux-manager/web.key`, random, made by the web service on its first run and readable by root +only; it is never configured or output. The server itself issues the tokens: `POST /auth` checks a user's password and TOTP code with a bind (ADR-14) and answers an access token naming the user in `sub`, valid for 5 minutes, and a refresh token valid for 8 -hours (ADR-15); `vpn-router-token` makes tokens with the `admin` claim (ADR-13). A token without +hours (ADR-15); `linux-manager-token` makes tokens with the `admin` claim (ADR-13). A token without `admin` must expire within ten minutes, so a leaked one is of little use. Without the key the paths and `/auth` are not served. The configuration shown has no secret options (ADR-8). -Consequences: Nothing outside the router can make a token, so a token is either issued to a -user who signed in or made by root on the router. A client keeps the refresh token to stay -signed in. A token of `vpn-router-token` can be revoked only by replacing the key, which ends +Consequences: Nothing outside the server can make a token, so a token is either issued to a +user who signed in or made by root on the server. A client keeps the refresh token to stay +signed in. A token of `linux-manager-token` can be revoked only by replacing the key, which ends every token. Tokens, passwords and answers cross the network unencrypted, so the API is for a trusted internal network; HTTPS would need a certificate that the package does not have. @@ -95,25 +95,25 @@ trusted internal network; HTTPS would need a certificate that the package does n Status: Accepted Context: OpenVPN needs user accounts with passwords, and the users are meant to cover every P2S -system of the router, including IKEv2 EAP-TLS and WireGuard, which an OIDC provider cannot -authenticate. Everything the router runs comes from the Ubuntu archive. slapd, its Python module +system of the server, including IKEv2 EAP-TLS and WireGuard, which an OIDC provider cannot +authenticate. Everything the server runs comes from the Ubuntu archive. slapd, its Python module `python3-ldap` and the OpenVPN plugin `openvpn-auth-ldap` are all in the archive; the plugin -checks a password by binding as the user, so the hash scheme is slapd's alone. The router's own +checks a password by binding as the user, so the hash scheme is slapd's alone. The server's own OpenID Provider (ADR-37) signs the directory's users in to other systems. Decision: The users are entries in slapd. The package keeps its own database, -`dc=vpn-router,dc=local` in `/var/lib/ldap/vpn-router` (the path the slapd AppArmor profile +`dc=linux-manager,dc=local` in `/var/lib/ldap/linux-manager` (the path the slapd AppArmor profile allows), next to the database the slapd package creates from the host's domain, so the package does not depend on the debconf answers of slapd. Its root DN is root's peer-credential DN on the -local socket, so `vpn-router-setup` manages it with SASL EXTERNAL and no administrator password +local socket, so `linux-manager-setup` manages it with SASL EXTERNAL and no administrator password exists. Users are changed by `cn=user-manager,ou=services`, whose ACLs allow writing `ou=users` and setting passwords (`=wx`) but not reading them. Passwords are hashed with ARGON2, and the ppolicy overlay locks a disabled user (`pwdAccountLockedTime`, effective with `pwdLockout`). slapd listens on the local socket only. Provisioning checks every step before changing it, so it -runs at every start of `vpn-router-setup`. +runs at every start of `linux-manager-setup`. Consequences: The package depends on `slapd`, `python3-ldap`, `openvpn` and -`openvpn-auth-ldap`, and `vpn-router-setup` and `vpn-router-user` import `python3-ldap`. The +`openvpn-auth-ldap`, and `linux-manager-setup` and `linux-manager-user` import `python3-ldap`. The service account's password is a root-only file. The directory is user data: it is kept on purge, and it is backed up with `slapcat`, not by copying files. @@ -135,7 +135,7 @@ the user name equals the certificate's common name. `openvpn-issuer`, as `tls-ve the certificate at depth 1 only when its SHA-256 fingerprint, which OpenVPN gives the script, is the P2S CA's. OpenVPN calls all of them and needs all to pass. A user's certificate has the user name as its common name, is issued with the template `vpn-user`, client authentication -only, when the user is added, and revoked when the user is removed. The server uses the router's +only, when the user is added, and revoked when the user is removed. The server uses the server's VPN server certificate, whose common name is `wan.local_fqdn`; the client profile checks that name (`verify-x509-name`). @@ -146,26 +146,26 @@ expires after the days of `vpn-user` and is renewed by removing and adding the u expired root CRL stops every OpenVPN client, so an offline root needs its CRL renewed in time (ADR-28). -## ADR-6: The web service and vpn-router-user share one module for users +## ADR-6: The web service and linux-manager-user share one module for users Status: Accepted Context: Users are managed from the command line, by an operator at a terminal, and through -`/users` of the web service, by the Router Manager. Both must apply the same rules to names, +`/users` of the web service, by the Manager. Both must apply the same rules to names, passwords and person attributes, and both change the directory and the PKI, whose CRL numbers and CRLs two changes must not write at the same time. The web unit is sandboxed with `ProtectSystem=strict`. -Decision: `vpnrouter_users.py` holds the user operations, the checks and a session that takes a +Decision: `linuxmanager_users.py` holds the user operations, the checks and a session that takes a lock and the connection of the user manager account. The web service imports it and maps a -`Failure` to the HTTP status; `vpn-router-user` imports it and adds the argument parsing and +`Failure` to the HTTP status; `linux-manager-user` imports it and adds the argument parsing and the output, text for people and JSON with `--json`. The web unit allows writing the paths the -operations need: `/run/vpn-router` for the lock, its `RuntimeDirectory`, which systemd creates +operations need: `/run/linux-manager` for the lock, its `RuntimeDirectory`, which systemd creates before the service starts, also before setup has run, and keeps when it stops, as setup's state files are there too, and `/etc/swanctl/x509crl`, `/etc/openvpn/server` and -`/var/lib/vpn-router/pki-publish` for the copies of the CRLs a revocation signs; the PKI itself is -in the directory (ADR-32). The PKI module, `vpnrouter_pki.py`, works the same way for `/ca`, -`vpn-router-ca` and `vpn-router-setup`, and its lock is the users' lock, as adding and removing +`/var/lib/linux-manager/pki-publish` for the copies of the CRLs a revocation signs; the PKI itself is +in the directory (ADR-32). The PKI module, `linuxmanager_pki.py`, works the same way for `/ca`, +`linux-manager-ca` and `linux-manager-setup`, and its lock is the users' lock, as adding and removing a user issue and revoke a certificate. Consequences: The rules exist once. A request starts no process but `swanctl --load-creds` after @@ -177,21 +177,21 @@ and the holders of an admin token manage users. Status: Accepted -Context: The status page is the tool to see a problem of `vpn-router-setup`, so it must run +Context: The status page is the tool to see a problem of `linux-manager-setup`, so it must run whatever state setup is in, also before setup has run and while it fails. The addresses, `web.listen`, `web.port` and `web.enabled` can change at any time. Decision: The service depends on nothing to start and does not end on its own. A discovery thread works out, every 30 seconds, the addresses of the interfaces `web.listen` names from -`vpn-router.json` as `general.mode` directs, with the discovery code in `vpnrouter_net.py`, -which `vpnrouter.py` uses too, and `web.port` and `web.enabled` from the same file. It runs an +`linux-manager.json` as `general.mode` directs, with the discovery code in `linuxmanager_net.py`, +which `linuxmanager.py` uses too, and `web.port` and `web.enabled` from the same file. It runs an HTTP server in a thread of its own at each address and the port, stops one and starts a new one when they change, and runs none while the service is disabled or no address is known; an address that cannot be bound is tried again the next round. Each request -reads the signing key and `vpn-router.json`, and the features and resolved facts from +reads the signing key and `linux-manager.json`, and the features and resolved facts from `web.json`, which setup writes when it applies the configuration, so the service shows what setup -applied; while that file is missing the router shows no features. The unit is not -ordered after `vpn-router-setup`, and setup does not restart it. +applied; while that file is missing the server shows no features. The unit is not +ordered after `linux-manager-setup`, and setup does not restart it. Consequences: The status page answers as soon as an address exists, whatever state setup is in, and follows a changed address, `web.listen`, port or `web.enabled` within 30 seconds without a @@ -202,10 +202,10 @@ seconds, which costs a few `ip` commands. Status: Accepted -Context: A secret has no use outside the router, so a client never needs it, and showing even +Context: A secret has no use outside the server, so a client never needs it, and showing even that a secret is set tells a reader more than it needs. -Decision: The configuration that `vpn-router-setup` writes for the web service has no secret +Decision: The configuration that `linux-manager-setup` writes for the web service has no secret options at all. They are recognised by name: `psk`, `database`, whose connection string may hold a password, and options with `secret`, `password`, `token` or a `_key` ending in the name. The names are checked at every level, so the settings of each site-to-site connection lose their @@ -217,45 +217,46 @@ Consequences: No secret reaches the web service's state file or any answer of th connection has a key (ADR-25), as an admin managing connections needs to know. A new secret option needs a name that matches. -## ADR-9: The Router Manager is a separate package with a small Python server +## ADR-9: The Manager is a React application behind a small Python server Status: Accepted -Context: The router needs a web application to manage it, which may run on the router or on -another Linux system. The router's web service issues tokens through `/auth` (ADR-3) and sends +Context: The server needs a web application to manage it, which may run on the server or on +another Linux system. The server's web service issues tokens through `/auth` (ADR-3) and sends no CORS headers, so a browser cannot call it directly, and tokens kept in the page could be read by its scripts. -Decision: `vpn-router-manager` is a Debian package of its own, built in the repository -`linux-cloud-router-manager`. A React and MUI application in the style of Cloud Manager is built +Decision: The Manager is part of the `linux-manager` package (ADR-56) and runs as +`linux-manager-ui.service`. A React and MUI application in the style of Cloud Manager is built with Vite when the package is built and shipped as static files. A Python server, using the Ubuntu packages `python3-requests` and `python3-psycopg`, serves them, signs users in through the -router's `/auth`, keeps their tokens in a server-side session in PostgreSQL behind an -`HttpOnly` cookie, and passes every other `/api/` call to the router's `/` with the -session's access token, refreshing it as needed; it holds no logic of the router's own and no -key of it. It reads its settings from `/etc/vpn-router-manager/manager.json` at each request; on -the router the settings not given come from `vpn-router.json`, and it listens on the internal +server's `/auth`, keeps their tokens in a server-side session in PostgreSQL behind an +`HttpOnly` cookie, and passes every other `/api/` call to the server's `/` with the +session's access token, refreshing it as needed; it holds no logic of the server's own and no +key of it. It reads its settings from `/etc/linux-manager/manager.json` at each request; on +the server the settings not given come from `linux-manager.json`, and it listens on the internal address, the external address or both, as its own `listen` sets, like the status web service, -with the same discovery thread. `vpn-router-setup` opens the manager's port on the internal and -the external interface while the manager is installed, so the firewall stays in one place. +with the same discovery thread. `linux-manager-setup` opens the manager's port on the internal and +the external interface, so the firewall stays in one place. -Consequences: The router needs no Node.js; the package needs only `python3` and packages of the +Consequences: The server needs no Node.js; the package needs only `python3` and packages of the Ubuntu archive. Tokens never reach the browser, and sessions survive a restart of the manager. -The router decides what a user may do; the manager only signs in. The application checks the -shape of every answer of the router. The router's firewall depends on whether the manager is -installed, and a changed manager port needs `vpn-router-setup` to run again. +The server decides what a user may do; the manager only signs in. The application checks the +shape of every answer of the server. A changed manager port needs `linux-manager-setup` to run +again. ## ADR-10: Users and their certificates do not depend on a P2S system being enabled Status: Accepted -Context: Users are prepared before a P2S system is switched on, and the Router Manager manages +Context: Users are prepared before a P2S system is switched on, and the Manager manages them on any configured router, with or without one. -Decision: Once a platform is chosen, `vpn-router-setup` always provisions the user directory in -slapd and the PKI (ADR-27) with its CRLs; the router's certificates follow once `wan.local_fqdn` -is set. `/users` and `vpn-router-user` rely only on the directory and the P2S CA. Only the -OpenVPN client profile needs OpenVPN to be enabled. +Decision: Once a platform is chosen, `linux-manager-setup` always provisions the user directory in +slapd and the PKI (ADR-27) with its CRLs; the server's certificates follow once `wan.local_fqdn` +is set. `/users` and `linux-manager-user` rely only on the directory and, while the VPN is on, the +P2S CA; with the VPN off a VPN user is created without a certificate, which it gets when the VPN +is switched on (ADR-57). Only the OpenVPN client profile needs OpenVPN to be enabled. Consequences: slapd always holds the directory and the CAs exist on a configured router, even when no P2S system uses them; with an offline root the P2S CA, and so the users' certificates, @@ -271,12 +272,12 @@ router reads them. LDAP clients that read groups, such as `openvpn-auth-ldap` an connectors of OIDC providers, expect `groupOfNames` with member DNs, and OpenLDAP's core schema requires a `groupOfNames` to have at least one `member`. -Decision: A group is `cn=,ou=groups,dc=vpn-router,dc=local`, a `groupOfNames` with the +Decision: A group is `cn=,ou=groups,dc=linux-manager,dc=local`, a `groupOfNames` with the DNs of its members and an optional `description`. A group is created with at least one member, and taking out its last member is refused; such a group is removed instead. Removing a user takes it out of its groups and is refused while the user is the last member of one. The group -operations are in `vpnrouter_users.py` with the user operations, so they share the session and -its lock; `vpn-router-group` is a tool of its own beside `vpn-router-user`, and the web service +operations are in `linuxmanager_users.py` with the user operations, so they share the session and +its lock; `linux-manager-group` is a tool of its own beside `linux-manager-user`, and the web service serves them under `/groups`. Group names follow the rules of user names. Consequences: A group always satisfies the schema without a placeholder member, and an empty @@ -306,29 +307,29 @@ router answers the URI; the client renders the QR code. Consequences: Removing a user removes its token. One check covers OpenVPN and `/auth`, and an enrolled user types the code after the password in the OpenVPN client. The secret passes -through the client between `otp_new` and `otp_enrol`, so the router keeps no pending state; +through the client between `otp_new` and `otp_enrol`, so the server keeps no pending state; enrolling again replaces the secret only once a code of the new one verifies. -## ADR-13: Members of admins manage the router; only CLI tokens change admins +## ADR-13: Members of admins manage the server; only CLI tokens change admins Status: Accepted Context: Signing in through `/auth` (ADR-3) is open to every user of the directory, most of whom only use OpenVPN. Finer permissions per operation are not needed. Somebody must be able to -manage the router before any administrator exists and after every administrator lost access, +manage the server before any administrator exists and after every administrator lost access, and administrators must not be able to grant themselves or others the administrator role over the API. Decision: A token naming a user in `sub` may call the protected paths only while the user is a -member of the group `admins`, read at each request; other users get 403. `vpn-router-token`, run -as root on the router, makes tokens with the claim `admin: true` and a lifetime given at -creation, without a maximum, signed with the router's key; `/auth` never issues the claim. An +member of the group `admins`, read at each request; other users get 403. `linux-manager-token`, run +as root on the server, makes tokens with the claim `admin: true` and a lifetime given at +creation, without a maximum, signed with the server's key; `/auth` never issues the claim. An admin token may call everything, and only an admin token may change `admins`: create it, rename a group to it, change or remove it, add or take out its members, or remove a user who is a member -of it. The first member is added with `vpn-router-group` on the router, which acts as root. +of it. The first member is added with `linux-manager-group` on the server, which acts as root. Consequences: Removing a user from `admins` takes effect at the next request, without waiting -for the user's tokens to expire. Membership of `admins` changes only through root on the router. +for the user's tokens to expire. Membership of `admins` changes only through root on the server. An admin token is as powerful as root over the API and is revoked only by replacing the key, so it is given a short lifetime unless it is meant for automation. @@ -339,20 +340,20 @@ Status: Accepted Context: `/auth` is open to the internal network and checks passwords, so it invites guessing; OpenVPN checks passwords from the internet. Both check with a bind, so slapd sees every attempt. ppolicy locks an account after a number of failed binds for a fixed time; it has no growing -lockout. A Router Manager signs all its users in from one address. +lockout. A Ubuntu Linux Manager signs all its users in from one address. Decision: The default password policy locks an account for 15 minutes after 5 failed binds -within 15 minutes; a successful bind clears the count; `vpn-router-user unlock` and +within 15 minutes; a successful bind clears the count; `linux-manager-user unlock` and `POST /users//unlock` end a lockout and clear the count, and leave a disabled user disabled. `/auth` answers the same 401 for a wrong name, password or code and for a locked or disabled user. `/auth` and `/auth/refresh` allow 10 calls a minute per client address, counted in memory, and answer 429 with `Retry-After` beyond that. The client address is the peer, or the last `X-Forwarded-For` entry for a peer in `web.trusted_proxies`, by default the address the call came -in on, which is the address a manager on the router calls from. +in on, which is the address a manager on the server calls from. Consequences: One lockout covers OpenVPN and `/auth`, kept by slapd alone. Someone who knows a user name can lock the user out for 15 minutes at a time. The rate limit restarts with the -service. A manager elsewhere than on the router has its address added to `web.trusted_proxies`, +service. A manager elsewhere than on the server has its address added to `web.trusted_proxies`, or its users share one limit. ## ADR-15: Refresh tokens are kept in PostgreSQL @@ -361,14 +362,14 @@ Status: Accepted Context: An access token lives 5 minutes, and a client stays signed in with a refresh token for 8 hours; refresh tokens must be revocable when a user signs out, is disabled, changes the -password or is removed, and must survive a restart of the service. The Router Manager keeps its +password or is removed, and must survive a restart of the service. The Manager keeps its sessions in PostgreSQL too. Decision: Refresh tokens are random strings, stored as their SHA-256 with the user name and the expiry in the table `refresh_tokens`, through psycopg 3 (`python3-psycopg`). The database is -`web.database`, or by default the database and role `vpn-router` on the router, which the web +`web.database`, or by default the database and role `linux-manager` on the server, which the web service creates on its first run (ADR-16) with `runuser -u postgres -- psql` and a random password in -`/etc/vpn-router/database.secret`, reached over TCP on `localhost`, as Ubuntu's `pg_hba.conf` +`/etc/linux-manager/database.secret`, reached over TCP on `localhost`, as Ubuntu's `pg_hba.conf` takes peer authentication on the local socket. A refresh token is used once: refreshing deletes it and issues a new one, after checking that the user is neither disabled nor locked. @@ -381,20 +382,20 @@ signing out, end the user's sessions at once; an access token already issued liv Status: Accepted -Context: The package manager configures packages in an order of its own; on a new VM the Router +Context: The package manager configures packages in an order of its own; on a new VM the Manager was configured before the PostgreSQL server, so a database created at installation was missing. PostgreSQL may also start after the services at boot. Decision: The web service makes its signing key and creates the refresh tokens' database itself, -and the Router Manager its sessions database; neither `vpn-router-setup` nor a maintainer script +and the Manager its sessions database; neither `linux-manager-setup` nor a maintainer script creates them. Each service does it before it listens, retrying every 15 seconds and logging each -failure, then listens. `vpnrouter_auth` turns every failure of the database into -`DatabaseError`, the only database exception the web service and `vpn-router-user` handle. +failure, then listens. `linuxmanager_auth` turns every failure of the database into +`DatabaseError`, the only database exception the web service and `linux-manager-user` handle. psycopg (Ubuntu ships only its pure-Python implementation) finds libpq through the dynamic linker cache, which dpkg refreshes with its deferred `ldconfig` only at the end of an installation, so a service started during the installation cannot import it yet; a failed import cannot be repeated -in the same process either, as psycopg caches the lookup. The services and `vpn-router-setup` +in the same process either, as psycopg caches the lookup. The services and `linux-manager-setup` therefore import psycopg plainly, and their units wait instead: `ExecStartPre=wait-for-libpq`, a shell script of each package, waits until `ldconfig -p` lists `libpq.so.5`, within `TimeoutStartSec=5min`. The maintainer scripts start the units with `systemctl --no-block` (debhelper's start is turned off), @@ -403,7 +404,7 @@ because a start that waited would hold dpkg before its `ldconfig`. Consequences: The order of installation and of the start of PostgreSQL and of the linker cache does not matter; a database that cannot be created is retried until the cause is gone, and the reason is in the service's log. Outside an installation the wait ends at once. The web unit may -write `/etc/vpn-router` for the key and the database password. +write `/etc/linux-manager` for the key and the database password. ## ADR-17: Bootstrap diagnostics run only until the first setup succeeds @@ -413,18 +414,18 @@ Context: A new VM is reachable only once its setup has worked, and the reason of be readable from the internal network before an SSH session is possible. A service that reports the setup cannot be one of the services being set up: those import packages that may not load yet (psycopg could not find libpq before `ldconfig` ran), and they would fail before reporting -anything. Once the router has been set up, SSH is the way to diagnose it. The more a diagnostic +anything. Once the server has been set up, SSH is the way to diagnose it. The more a diagnostic page does, the more ways it has to fail itself. Decision: Each package ships a bootstrap service of the Python standard library alone, a script that answers every request with the plain-text output of a fixed list of commands: the setup -state, the services, the failed units, the addresses and the end of the logs. The router's -listens on 17081 and the Router Manager's on 17080, beside the ports of the services, 7081 and +state, the services, the failed units, the addresses and the end of the logs. The server's +listens on 17081 and the Manager's on 17080, beside the ports of the services, 7081 and 7080, on every address. The units are never enabled and not started at installation; -`vpn-router-setup` starts them while `/var/lib/vpn-router/setup.done` does not exist, and opens +`linux-manager-setup` starts them while `/var/lib/linux-manager/setup.done` does not exist, and opens their ports on the internal interface. The first successful run writes that file, closes the ports and stops them; a failed run leaves them running, so the reason stays readable. Setup records its -state, step and failure in `/run/vpn-router/setup.json` at every step; `vpnrouter.fail` ends with +state, step and failure in `/run/linux-manager/setup.json` at every step; `linuxmanager.fail` ends with a `SystemExit` carrying its message, so setup records it. Consequences: The diagnostics need nothing the setup provides and cannot collide with the real @@ -435,59 +436,60 @@ The page shows log lines to whoever reaches the internal network during the firs Status: Accepted -Context: The Router Manager needs a first administrator before anyone has added users, as other +Context: The Manager needs a first administrator before anyone has added users, as other packages create a default user from their debconf answers. Such an account, and others that only -manage the router, have no person behind them and need no VPN access. A VPN user is an +manage the server, have no person behind them and need no VPN access. A VPN user is an `inetOrgPerson`, which requires a last name and a common name, and its certificate needs the -names. The Manager is configured before the router's directory exists during an installation. +names. The Manager is configured before the server's directory exists during an installation. Decision: A user is one of two kinds in `ou=users`, fixed when it is added: a VPN user, an `inetOrgPerson` with the three person attributes and a certificate, or a Manager-only account, -an `account`, `simpleSecurityObject` and `vpnRouterAccount` (ADR-19) with the name, the password, +an `account`, `simpleSecurityObject` and `linuxManagerAccount` (ADR-19) with the name, the password, an optional e-mail address for notifications, and no certificate. `add` with all three person attributes adds a VPN user and without the first and the last name a Manager-only account; one name without the rest is refused. The CLI and the API add both kinds; the Manager's dialog requires the names unless Manager access only is chosen, which offers the e-mail address only. Answers carry `manager_only`, and `update` changes only the e-mail address of a Manager-only account. The Manager's package asks `admin_username` and `admin_password`; with both -it writes them to a root-only file, clears the answers, and `vpn-router-setup` creates the account +it writes them to a root-only file, clears the answers, and `linux-manager-setup` creates the account after it provisions the directory, adds it to `admins` (creating the group when missing) and -removes the file. Without a name nothing is created. `vpnrouter_users` knows only the directory, -so setup can use it before PostgreSQL's driver can be loaded; `web` and `vpn-router-user` revoke -refresh tokens after the operations of `vpnrouter_auth.REVOKING`. +removes the file. Without a name nothing is created. `linuxmanager_users` knows only the directory, +so setup can use it before PostgreSQL's driver can be loaded; `web` and `linux-manager-user` revoke +refresh tokens after the operations of `linuxmanager_auth.REVOKING`. Consequences: A Manager-only account cannot become a VPN user, as LDAP cannot change an entry's structural class and its password hash cannot be copied; it is removed and added again instead. It has no certificate, so OpenVPN and IKEv2 access refuse it. The administrator's password is on disk only until setup has run. -## ADR-19: The package has an LDAP schema of its own under a UUID OID +## ADR-19: The package's LDAP schema is under the delegated arc 1.3.6.1.4.1.67380.10.1.2 Status: Accepted Context: A Manager-only account (ADR-18) is an `account`, which allows no `mail`, yet notifications need an address for it; no standard auxiliary class allows `mail` except `extensibleObject`, which allows every attribute. Authorization scopes for users of both kinds may follow. An attribute or -class of its own needs an OID, and the package has no registered arc. +class of its own needs an OID. The Private Enterprise Number 67380 delegates the arc +`1.3.6.1.4.1.67380.10.1` to the package, whose allocations are listed in `OID-REGISTRY.txt`. -Decision: The package defines its schema, `cn=vpn-router,cn=schema,cn=config`, which -`vpnrouter_ldap.provision` adds when missing and keeps as `SCHEMA_ATTRIBUTE_TYPES` and -`SCHEMA_OBJECT_CLASSES`. Its OID is `2.25.98477352595735834532404256531620013001`, made from a -random UUID under the arc 2.25 (ITU-T X.667), which needs no registration; attribute types are -under `.1` and object classes under `.2`. It has the attribute `vpnRouterScope` (multi-valued, -case-insensitive strings) and the auxiliary class `vpnRouterAccount`, -`MAY ( mail $ vpnRouterScope $ displayName $ description )`; `displayName` and `description`, the +Decision: The package defines its schema, `cn=linux-manager,cn=schema,cn=config`, which +`linuxmanager_ldap.provision` adds when missing and keeps as `SCHEMA_ATTRIBUTE_TYPES` and +`SCHEMA_OBJECT_CLASSES`. Its OID is `1.3.6.1.4.1.67380.10.1.2`, the LDAP arc of the package's +delegated arc; attribute types are under `.1` and object classes under `.2`, and each is listed in +`OID-REGISTRY.txt` before it is used. It has the attribute `linuxManagerScope` (multi-valued, +case-insensitive strings) and the auxiliary class `linuxManagerAccount`, +`MAY ( mail $ linuxManagerScope $ displayName $ description )`; `displayName` and `description`, the standard attributes, are the display name and the description of a service account, which `account` cannot hold. Manager-only accounts have the class from their creation, so an e-mail address can be added later without changing their classes; VPN users get it once scopes are used. -`vpnrouter_ldap.provision` replaces the definitions in `cn=config` that differ, so an extended class -reaches an existing directory at the next setup run. The structural class `vpnRouterRole`, +`linuxmanager_ldap.provision` replaces the definitions in `cn=config` that differ, so an extended class +reaches an existing directory at the next setup run. The structural class `linuxManagerRole`, `MUST cn MAY ( description $ member )`, is a role of a resource of the OpenID Provider (ADR-37), an entry `cn=:` of `ou=roles`, which provision makes; the manager account manages that subtree, and every account reads it. Consequences: The schema check stays strict. New attributes of accounts extend -`vpnRouterAccount`, and their OIDs continue the arcs. The scope `service` marks a service account +`linuxManagerAccount`, and their OIDs continue the arcs. The scope `service` marks a service account (ADR-23). The OID must never be reused for anything else. ## ADR-20: Users manage their own account through /account, proving who they are again @@ -506,7 +508,7 @@ and whether they are a member of `admins`, `PUT /account/password`, and `POST` a Each change sends the current password and, for an enrolled user, a current code, checked with a bind as the user like `/auth`, so it counts toward the lockout (ADR-14); a wrong one is 403. A new password is checked before the bind, so an invalid one does not use up a code. A user cannot -remove their own enrolment; `/users` and `vpn-router-user` do. Tokens of `vpn-router-token` name +remove their own enrolment; `/users` and `linux-manager-user` do. Tokens of `linux-manager-token` name no user and get 403 there. Consequences: slapd's `otp` overlay accepts each code once, so a change right after signing in @@ -518,15 +520,15 @@ needs an administrator. Status: Accepted -Context: The status web service and the Router Manager are reachable from the internet (ADR-2), +Context: The status web service and the Manager are reachable from the internet (ADR-2), and `/auth` and the Manager's sign-in carry passwords. Both are small servers on the standard library's `http.server`, which would need certificates, their renewal and a TLS setup of their -own. Browsers trust a public CA, not the router's. +own. Browsers trust a public CA, not the server's. Decision: Caddy, the `caddy` package of the Ubuntu archive, is the HTTPS proxy. While -`https.enabled` is `true` (the default) and `wan.local_fqdn` is set, `vpn-router-setup` writes -`/etc/caddy/vpn-router.Caddyfile`: a site for `wan.local_fqdn` on `https.web_port` (7444) for the -web service and, while the Router Manager is installed, one on `https.manager_port` (7443) for +`https.enabled` is `true` (the default) and `wan.local_fqdn` is set, `linux-manager-setup` writes +`/etc/caddy/linux-manager.Caddyfile`: a site for `wan.local_fqdn` on `https.web_port` (7444) for the +web service and, while the Manager is installed, one on `https.manager_port` (7443) for the manager, each passing calls to the service on `127.0.0.1`. Caddy obtains and renews the certificate from Let's Encrypt with the HTTP challenge on port 80, which the firewall opens on the external interface; `auto_https disable_redirects` keeps port 80 to the challenge. The @@ -539,30 +541,31 @@ names, which routers rebuilt for tests reach; `https.acme_staging` sets Caddy's to Let's Encrypt's staging directory, which replaces Caddy's default CAs for every site, so no test certificate comes from a production CA. `PUT /https/settings` changes `acme_staging` alone: the other settings of the section switch HTTPS off or move its ports, which would end the -connection the Router Manager makes the change on. +connection the Manager makes the change on. -Consequences: HTTPS needs `wan.local_fqdn` in public DNS pointing at the router and port 80 +Consequences: HTTPS needs `wan.local_fqdn` in public DNS pointing at the server and port 80 reachable from the internet; until then Caddy retries and the HTTPS ports do not answer. The certificate and the ACME account are in `/var/lib/caddy`. A router on the staging CA has a certificate no client trusts. Plain HTTP stays as the `listen` settings set it, so `internal` keeps passwords off the internet. Caddy's admin endpoint listens on `localhost:2019`, which `caddy reload` uses. Port 80 and the HTTPS ports are not available -to Docker containers while HTTPS is on. The Manager's HTTPS port is a setting of the router, not +to Docker containers while HTTPS is on. The Manager's HTTPS port is a setting of the server, not of the manager. ## ADR-22: Metrics are kept in PostgreSQL and served in the Prometheus format, pushed with OTLP Status: Accepted -Context: The router should keep its CPU, memory, disk, network, load and VPN client metrics for +Context: The server should keep its CPU, memory, disk, network, load and VPN client metrics for hour, day, month and year views, as Proxmox VE does, and expose them to OpenTelemetry. Ubuntu -noble has no OpenTelemetry Python SDK and no OpenTelemetry Collector package. OTLP itself is +resolute packages the OpenTelemetry Python SDK (1.39.1) in universe only, and no OpenTelemetry +Collector. OTLP itself is push-only; a collector reads a scraped endpoint in the Prometheus format with its `prometheus` -receiver. The router already runs PostgreSQL for the refresh tokens (ADR-15). +receiver. The server already runs PostgreSQL for the refresh tokens (ADR-15). -Decision: A service of its own, `vpn-router-metrics`, takes a sample every minute with `psutil` -(`python3-psutil`) and the VPN readers it shares with the web service (`vpnrouter_status`). It -keeps the samples in the router's database, in four detail tables (`metrics_system`, +Decision: A service of its own, `linux-manager-metrics`, takes a sample every minute with `psutil` +(`python3-psutil`) and the VPN readers it shares with the web service (`linuxmanager_status`). It +keeps the samples in the server's database, in four detail tables (`metrics_system`, `metrics_network`, `metrics_vpn`, `metrics_site_to_site`, see ADR-25). Each detail table has hourly, daily, monthly and yearly summary tables, with the average and the maximum of each value per period, written when the clock passes a period from the level below with `INSERT ... ON CONFLICT DO NOTHING`, so a stopped service catches @@ -571,7 +574,7 @@ older than the retention of their level, `metrics.keep_*`, PostgreSQL intervals. the last sample as `/metrics` in the Prometheus text format with `prometheus_client` (`python3-prometheus-client`) and pushes it as OTLP/HTTP JSON, built with the standard library, to `metrics.otlp_endpoint`. The names follow the OpenTelemetry semantic conventions. The web service -answers the views from the tables at `/metrics/history`, protected like `/config`, for the Router +answers the views from the tables at `/metrics/history`, protected like `/config`, for the Manager. Consequences: The metrics live in the database of the refresh tokens and are dropped with it on @@ -579,79 +582,79 @@ purge. A view shows only what its level keeps, so a shorter retention empties th view. A month view needs the hourly rows and a year view the monthly rows. `/metrics` has only the last sample; history is not scraped. -## ADR-23: /metrics takes HTTP Basic authentication of an internal service account the router manages +## ADR-23: /metrics takes HTTP Basic authentication of an internal service account the server manages Status: Accepted Context: An OpenTelemetry Collector's `prometheus` receiver authenticates with HTTP Basic, not with -the router's tokens, which last minutes (ADR-3). The scraper should not be able to sign in to the +the server's tokens, which last minutes (ADR-3). The scraper should not be able to sign in to the API or the Manager, and its password should be checked and locked out like any other. The account -belongs to the package's metrics, not to the people using the router. +belongs to the package's metrics, not to the people using the server. -Decision: A service account is a Manager-only account (ADR-18) with `vpnRouterScope` `service`, +Decision: A service account is a Manager-only account (ADR-18) with `linuxManagerScope` `service`, which another system signs in with to use a router service. Administrators add service accounts -with `vpn-router-user add --service` and the web service's `/service-accounts`. +with `linux-manager-user add --service` and the web service's `/service-accounts`. `/service-accounts` is a path of its own, apart from `/users`, which does not list or serve them: a service account has no names, certificate, profile or TOTP, and is not a person an administrator manages with the users. A service account has a display name and a description besides its name, so an administrator can tell what each is for. Internal service accounts are -those the router creates and manages for its own services (`vpnrouter_users.internal_accounts`), +those the server creates and manages for its own services (`linuxmanager_users.internal_accounts`), with every property, display name and description included, so the system, not an administrator, owns them; at present that is the metrics service's, which setup names Metrics. `/service-accounts` marks them as `internal` and only lists them: every other request on one, and putting one in or taking -one out of a group at `/groups`, gets 403, whatever the token. The router changes them through the -directory's user-manager account, not the API, and root may still with `vpn-router-user`. For the -metrics service, `vpn-router-setup` adds the account `metrics.service_account` names, `metrics` by +one out of a group at `/groups`, gets 403, whatever the token. The server changes them through the +directory's user-manager account, not the API, and root may still with `linux-manager-user`. For the +metrics service, `linux-manager-setup` adds the account `metrics.service_account` names, `metrics` by default, while metrics are enabled, with a random password it writes to -`/etc/vpn-router/metrics.secret` (root only), and sets a new random password, ending a lockout, +`/etc/linux-manager/metrics.secret` (root only), and sets a new random password, ending a lockout, when the file is missing or no longer holds the password. `/auth` refuses every service account with the message of a wrong password. `/metrics` accepts HTTP Basic only for that account, and only when it is a service account; the password is checked with a bind as the account, so the password policy's lockout applies (ADR-14). TLS is Caddy's, on `metrics.https_port` (ADR-21); plain HTTP is served on the interfaces `metrics.listen` names, `internal` by default. Consequences: Every scrape binds to slapd once. The collector's operator copies the password from -the router; deleting the file and running setup changes it. A user who already has the name is not +the server; deleting the file and running setup changes it. A user who already has the name is not taken over; setup fails until `metrics.service_account` names another. An account root disabled stays disabled. A scraper on the external interface over plain HTTP sends the password in the clear, so `metrics.listen` stays `internal` unless HTTPS is used. -## ADR-24: The Router Manager upgrades the router's packages in a transient unit outside its own +## ADR-24: The Manager upgrades the server's packages in a transient unit outside its own Status: Accepted -Context: An admin should upgrade `vpn-router` and `vpn-router-manager` from the Router Manager. The +Context: An admin should upgrade `linux-manager` and `linux-manager-ui` from the Manager. The upgrade restarts the process that starts it: the manager's postinst restarts -`vpn-router-manager.service`, and the router's restarts `vpn-router-web` and `vpn-router-setup`. A +`linux-manager-ui.service`, and the server's restarts `linux-manager-web` and `linux-manager-setup`. A child of the manager would be stopped with the manager's cgroup in the middle of dpkg, leaving packages half configured, and the manager's unit cannot run apt at all, since `ProtectSystem=strict` makes `/usr` and `/var/lib/dpkg` read-only. Ubuntu's `apt-daily` timer updates the package lists twice a day, so a release newer than its last run is not seen until the next one. -Decision: The manager starts the helper `/usr/lib/vpn-router-manager/upgrade` with `systemd-run` as -the transient unit `vpn-router-manager-upgrade`, of its own cgroup and without a sandbox, and does +Decision: The manager starts the helper `/usr/lib/linux-manager/upgrade` with `systemd-run` as +the transient unit `linux-manager-ui-upgrade`, of its own cgroup and without a sandbox, and does not wait for it. The helper: - finishes an interrupted dpkg run with `dpkg --configure -a`; - runs `apt-get install --only-upgrade` of the two packages, non-interactive, keeping changed configuration files, with `needrestart` suspended, and waiting for the dpkg lock that `apt-daily` or `unattended-upgrades` may hold; -- records the state and the result in `/var/lib/vpn-router-manager/upgrade.json`, replaced by a rename, and the output in `upgrade.log`. +- records the state and the result in `/var/lib/linux-manager/upgrade.json`, replaced by a rename, and the output in `upgrade.log`. -A restarted manager reads them again. A state of running without an active unit is shown as interrupted. The manager reboots the router the same way, as a transient timer `vpn-router-manager-reboot` 5 seconds later, so the answer reaches the browser first. It checks for updates the same way too: Check update runs `apt-get update` in the transient unit `vpn-router-manager-check`, which touches apt's update stamp when it succeeds, so an admin need not wait for the `apt-daily` timer. Only members of `admins`, as the router's `/account` answers, may start any of them. +A restarted manager reads them again. A state of running without an active unit is shown as interrupted. The manager reboots the server the same way, as a transient timer `linux-manager-ui-reboot` 5 seconds later, so the answer reaches the browser first. It checks for updates the same way too: Check update runs `apt-get update` in the transient unit `linux-manager-ui-check`, which touches apt's update stamp when it succeeds, so an admin need not wait for the `apt-daily` timer. Only members of `admins`, as the server's `/account` answers, may start any of them. Consequences: The fixed unit name allows one upgrade at a time. The page loses the manager and the -router's web service for a while during an upgrade and reads again until they answer. Sessions +server's web service for a while during an upgrade and reads again until they answer. Sessions survive in PostgreSQL. The manager can upgrade only the system it runs on, so a manager on another -host upgrades that host's packages, not the router's. The operating system's other packages are +host upgrades that host's packages, not the server's. The operating system's other packages are left to unattended-upgrades. ## ADR-25: Site-to-site connections are a map of named connections, edited through the API and applied by setup Status: Accepted -Context: The router had one IPsec site-to-site tunnel, the `remote` section, run as the swanctl +Context: The server had one IPsec site-to-site tunnel, the `remote` section, run as the swanctl connection `remote-site`, with the local identity mode in `wan` and the local subnets in `local`. A router often links more than one site, each with its own peer, subnets and key, and an admin should add them without a shell. The install answers and Cloud Manager describe one -connection, and the platform rewrites `vpn-router.json` when it rebuilds the VM. +connection, and the platform rewrites `linux-manager.json` when it rebuilds the VM. Decision: `site_to_site` maps a connection name to its settings: `addrs`, `id`, `cidrs`, `local_cidrs`, `local_id_mode`, `psk` and `psk_file`. `remote` and `wan.local_id_mode` are gone, @@ -663,19 +666,19 @@ one, so its name is the one the tunnel always had. - **Local settings per connection:** each connection has its own `local_cidrs` and `local_id_mode`, as each peer expects its own traffic selectors and identity. `wan.local_fqdn` - stays the router's one name, used by the `fqdn` mode, resolved once for the `public_ip` mode, - and used by HTTPS, IKEv2 and OpenVPN. `local.cidrs` stays the subnets the router + stays the server's one name, used by the `fqdn` mode, resolved once for the `public_ip` mode, + and used by HTTPS, IKEv2 and OpenVPN. `local.cidrs` stays the subnets the server routes, masquerades and offers to IKEv2 and OpenVPN clients. -- **One file:** `vpn-router-setup` writes every connection that is ready to +- **One file:** `linux-manager-setup` writes every connection that is ready to `/etc/swanctl/conf.d/site-to-site.conf`, with the proposals and timers the one tunnel had, and removes the file when none is. The NAT exemptions pair each connection's `local_cidrs` with its `cidrs`. - **Editing:** the status web service serves `/site-to-site` to members of `admins` and admin tokens, like `/users`. It never returns a key, only whether one is set, and takes a new key only - when one is given. `vpn-config-edit` edits the same map. Both read, check with the validation - of `vpn-router-setup` and write `vpn-router.json` holding one lock, replacing the file in one + when one is given. `linux-manager-config-edit` edits the same map. Both read, check with the validation + of `linux-manager-setup` and write `linux-manager.json` holding one lock, replacing the file in one step, so neither loses the other's change. -- **Applying:** the web service restarts `vpn-router-setup` without waiting for it, the one +- **Applying:** the web service restarts `linux-manager-setup` without waiting for it, the one place that renders, loads and opens the firewall, so a change through the API takes the same path as a change by hand. - **Metrics per connection:** the metrics service keeps, per connection, whether it is up, the @@ -692,7 +695,7 @@ Consequences: A configuration with `remote` is refused, so the package and a con the new format go together. The status shows each connection. A rate across a rekey misses the traffic of the old child SA since the previous sample. A renamed connection starts a new series. A connection added through the API lives in -`vpn-router.json` only; Cloud Manager's rebuild of the VM writes the file again with its +`linux-manager.json` only; Cloud Manager's rebuild of the VM writes the file again with its one connection, dropping the others. A change through the API is answered before setup has applied it, so a configuration that setup cannot apply shows in the setup state, not in the answer. A connection with a key file keeps it until a key is given through the API, which then @@ -704,20 +707,20 @@ Status: Accepted Context: An image backup of the VM, such as Azure Backup, restores the whole disk. It cannot be exported as a file, read on another system, or restored onto a new VM. The state that matters is -small, but it is spread over several places: `vpn-router.json` and the secrets, the PKI, the +small, but it is spread over several places: `linux-manager.json` and the secrets, the PKI, the WireGuard keys and peers, the firewall rules, the slapd directory and, optionally, the PostgreSQL database. Only part of it can be made again: the CA, the password hashes and the TOTP secrets cannot. The API and the command-line tools change the configuration, the PKI and the -directory while the router runs. +directory while the server runs. -Decision: `vpn-router-backup run`, started by a timer on `backup.schedule`, stages a copy of that +Decision: `linux-manager-backup run`, started by a timer on `backup.schedule`, stages a copy of that state in one directory and then archives or sends it. - **Consistency:** the files are copied and the directory is written with `slapcat` while the configuration lock and the users lock are held, the locks every change of the API and the tools takes, so a user, their certificate and the CRL are copied together. `slapcat` reads the MDB database consistently while slapd runs (ADR-4), and `pg_dump` reads a snapshot. Files that - `vpn-router-setup` regenerates are left out. + `linux-manager-setup` regenerates are left out. - **Local target:** a tar archive compressed with zstd, both from the Ubuntu archive, so a local backup needs nothing else and the archive can be read on any Linux system. A `pxar` archive would need Proxmox's client and is not compressed. @@ -725,8 +728,8 @@ state in one directory and then archives or sends it. settings mean the same for both targets and can be checked with Proxmox's prune simulator. Settings finer than the schedule do not apply. - **Cloud copy:** rclone, from the Ubuntu archive, copies the archives to any storage it - supports. The remote is defined in `/etc/vpn-router/rclone.conf` with `rclone config`, since - each backend has its own settings. `vpn-router.json` names only the remote, and the + supports. The remote is defined in `/etc/linux-manager/rclone.conf` with `rclone config`, since + each backend has its own settings. `linux-manager.json` names only the remote, and the configuration file is part of the backup. `sync` makes retention apply to the remote as well; `copy` leaves it to the storage's lifecycle rules. Only this host's archives are included, so a shared remote path is safe. @@ -736,12 +739,12 @@ state in one directory and then archives or sends it. The client is a suggestion, not a dependency, because it comes from Proxmox's repository, which an Ubuntu system does not know. Without it, only a PBS backup fails. - **Restore:** only on the command line, as root. It replaces the directory and the database, so - it stops their services, keeps what it replaces and lets `vpn-router-setup` rebuild the rest. - The API offers no restore, so a stolen admin session cannot replace the router's keys. + it stops their services, keeps what it replaces and lets `linux-manager-setup` rebuild the rest. + The API offers no restore, so a stolen admin session cannot replace the server's keys. -Consequences: A backup holds every secret of the router, including the keys of the issuing CAs -and the root key while it is on the router, in plain form -unless a PBS key file encrypts it, so where it is kept must be as safe as the router. A restore +Consequences: A backup holds every secret of the server, including the keys of the issuing CAs +and the root key while it is on the server, in plain form +unless a PBS key file encrypts it, so where it is kept must be as safe as the server. A restore onto another VM brings back the old interface names and addresses, which may need changing. The timer's schedules are systemd's shorthands, so all backups of one schedule start at the same moment. A change of the users between the end of the copy and the next backup is in no backup @@ -751,26 +754,26 @@ until then. Status: Accepted -Context: One self-signed CA signed every certificate of the router with the same server and +Context: One self-signed CA signed every certificate of the server with the same server and client purposes, so a certificate for any use was also a VPN client certificate, and the key -that signed everything had to stay on the router. The router needs CAs for the VPN clients, for +that signed everything had to stay on the server. The server needs CAs for the VPN clients, for site-to-site certificates and for the administrator's own uses, and a root whose key can be kept elsewhere. The `simple-ca` script handled one level and ran as a separate process with its own state file. Decision: The root signs only issuing CAs, path length 1; the issuing CAs, path length 0, sign -the certificates. `p2s` signs the router's VPN server certificate and the users' certificates, +the certificates. `p2s` signs the server's VPN server certificate and the users' certificates, `s2s` the site-to-site certificates, and the CAs of `pki.issuing_cas` what their templates allow. A template fixes the key, the lifetime, the key usages, the extended key usages, the kind of common name and the subject alternative names a certificate may have; `vpn-server` and -`vpn-user` are issued by the router only, so no certificate for another use comes from the P2S -CA. The module `vpnrouter_pki.py`, with `python3-cryptography` from the Ubuntu archive, builds +`vpn-user` are issued by the server only, so no certificate for another use comes from the P2S +CA. The module `linuxmanager_pki.py`, with `python3-cryptography` from the Ubuntu archive, builds the keys, certificates, CSRs and CRLs in the processes that need them, as the user module does -(ADR-6); the settings are the `pki` section of `vpn-router.json`, and the CAs and the -certificates are kept in the router's directory (ADR-32). Keeping the root key off the router is recommended, not required: while it is -on the router a new issuing CA is signed at once, and while it is not the CA gets its key and a -CSR, signed offline and imported with `vpn-router-ca` or `/ca`. The root key itself crosses -neither the API nor the Manager. For a certificate of something other than the router, the router +(ADR-6); the settings are the `pki` section of `linux-manager.json`, and the CAs and the +certificates are kept in the server's directory (ADR-32). Keeping the root key off the server is recommended, not required: while it is +on the server a new issuing CA is signed at once, and while it is not the CA gets its key and a +CSR, signed offline and imported with `linux-manager-ca` or `/ca`. The root key itself crosses +neither the API nor the Manager. For a certificate of something other than the server, the server signs the requester's CSR, or makes the key and returns it once in a PKCS#12 file, keeping only the certificate, so a key it gave away cannot leak from it later. The PKCS#12 file uses 3DES and SHA-1 MACs, the encryption the key stores of Windows and macOS import. strongSwan reads only the @@ -779,22 +782,22 @@ IKEv2 access and site-to-site name their CA in `cacerts`, which restricts the tr Consequences: The P2S CA's certificates are accepted by IKEv2 and OpenVPN only, the site-to-site CA's by site-to-site only. With an offline root, new issuing CAs and the root CRL need the offline step, -and a router whose P2S CA waits has no VPN server certificate and so no P2S access. The router +and a router whose P2S CA waits has no VPN server certificate and so no P2S access. The server keeps the users' keys, as the OpenVPN profile embeds them. ## ADR-28: CA certificates and CRLs are published at configurable endpoints, and CRLs are short-lived Status: Accepted -Context: Clients outside the router, such as Windows and servers using the general-purpose CAs, +Context: Clients outside the server, such as Windows and servers using the general-purpose CAs, find the issuer's certificate and the CRL through the AIA and CRL distribution point extensions, -and cache a CRL until its next update. The router's CRLs were valid for ten years and published +and cache a CRL until its next update. The server's CRLs were valid for ten years and published nowhere. Caddy serves files itself, and the web service already answers on the status port. Decision: `pki.publish` lists the endpoints, in the order the URLs appear in the certificates: plain HTTP on the status port, served by the web service; plain HTTP on port 80, HTTPS on the status HTTPS port and HTTPS on port 443, served by Caddy's `file_server`. The files are DER, as -RFC 5280 asks of these URLs, copied to `/var/lib/vpn-router/pki-publish`, outside the 0700 PKI +RFC 5280 asks of these URLs, copied to `/var/lib/linux-manager/pki-publish`, outside the 0700 PKI directory, so that Caddy's user reads them. Ports 80 and 443 serve only the CA files and are opened on both interfaces when chosen. The CRLs of the issuing CAs are valid for `pki.crl_days`, a week by default, signed again at every revocation and by a daily timer once half their validity has @@ -805,7 +808,7 @@ Consequences: A client that caches a CRL sees a revocation within a week. The UR certificate when it is signed, so a change of the endpoints or of `wan.local_fqdn` applies to certificates signed afterwards. HTTPS URLs are offered for clients that cannot use plain HTTP, although a client checking the revocation of the HTTPS server's own certificate cannot use them; -Caddy's certificate is Let's Encrypt's, so the router's endpoints do not depend on themselves. +Caddy's certificate is Let's Encrypt's, so the server's endpoints do not depend on themselves. ## ADR-29: Site-to-site connections authenticate with a pre-shared key or certificates @@ -821,12 +824,12 @@ router presents one site-to-site certificate of its `s2s` CA, whose names are `w the local identities the connections with `certificate` use, the public or the internal address of their `local_id_mode`, and no address no connection presents, such as an internal address the peers never see; the peer's -certificate must name the connection's `id` and be issued by the router's `s2s` CA or, when the +certificate must name the connection's `id` and be issued by the server's `s2s` CA or, when the connection has `remote_ca`, by that CA, its PEM certificate kept in the connection and copied to -`/etc/swanctl/x509ca/s2s-.pem`. A peer without a PKI gets its certificate from the router. +`/etc/swanctl/x509ca/s2s-.pem`. A peer without a PKI gets its certificate from the server. Consequences: The connection Azure's gateway needs stays `psk`, so the platform writes nothing -new. The router's site-to-site certificate is issued again when the set of names it needs changes, +new. The server's site-to-site certificate is issued again when the set of names it needs changes, such as when a connection's `local_id_mode` or its address changes. The router does not check a remote CA's revocations unless strongSwan can fetch the CRL its certificates name. @@ -836,7 +839,7 @@ certificates name. Status: Accepted Context: Servers that use a general-purpose CA need their certificates renewed, which ACME clients -automate. Caddy, which the router runs for HTTPS, has an ACME server built on a CA of its `pki` +automate. Caddy, which the server runs for HTTPS, has an ACME server built on a CA of its `pki` app. Caddy 2.6.2 of the Ubuntu archive needs the key file of that CA's root, never renews an intermediate given to it, keeps no CRL and takes only the CA in the `acme_server` directive, issuing certificates valid for 12 hours. Its ACME handler answers every path under `/acme/`. @@ -844,56 +847,56 @@ issuing certificates valid for 12 hours. Its ACME handler answers every path und Decision: An issuing CA of `pki.issuing_cas` with `acme` makes Caddy serve an ACME server for it at `/acme//` of the HTTPS status port, each in a `handle` block of its own. The issuing CA's certificate and key are given to Caddy as both the root and the intermediate of a `pki` CA, copied -to `/etc/caddy/vpn-router-pki//` for Caddy's group, so that the router's root key never +to `/etc/caddy/linux-manager-pki//` for Caddy's group, so that the server's root key never reaches Caddy and may be offline. -Consequences: The certificates Caddy issues chain to the router's root through the issuing CA, are -not in the router's inventory, follow no template and are not revoked; their short lifetime takes +Consequences: The certificates Caddy issues chain to the server's root through the issuing CA, are +not in the server's inventory, follow no template and are not revoked; their short lifetime takes the place of revocation. An issuing CA waiting for the offline root has no ACME server. -## ADR-31: vpn-router-setup installs Caddy from the Ubuntu archive or from Caddy's repository +## ADR-31: linux-manager-setup installs Caddy from the Ubuntu archive or from Caddy's repository Status: Accepted Context: Caddy 2.6.2 of the Ubuntu archive lacks later features, such as a pki root without its key and the settings of the ACME server. Caddy's own repository has current versions of the package of -the same name. A dependency on `caddy` installs the archive's package with `vpn-router`. apt cannot -run inside `vpn-router-setup` when the package's installation runs setup, as dpkg holds its lock. +the same name. A dependency on `caddy` installs the archive's package with `linux-manager`. apt cannot +run inside `linux-manager-setup` when the package's installation runs setup, as dpkg holds its lock. -Decision: `vpn-router` only suggests `caddy`. While HTTPS is on, setup has -`vpn-router-caddy.service` install it from `https.caddy_source`: `ubuntu`, or `upstream`, for +Decision: `linux-manager` only suggests `caddy`. While HTTPS is on, setup has +`linux-manager-caddy.service` install it from `https.caddy_source`: `ubuntu`, or `upstream`, for which the unit writes the deb822 source and the key it downloads over HTTPS from Caddy's repository. The unit waits for dpkg's lock and runs setup again when Caddy is in place. -`vpn-router-caddy use-upstream` switches an installed router. Upstream's versions sort above the +`linux-manager-caddy use-upstream` switches an installed router. Upstream's versions sort above the archive's, so once the repository is configured apt keeps upstream's Caddy without a pin, and `ubuntu` has no effect; nothing downgrades Caddy on its own, as a downgrade may break the -configuration and is the administrator's decision. Only the CLI switches the source; the Router +configuration and is the administrator's decision. Only the CLI switches the source; the Manager shows which one is in effect. Consequences: The first setup run with HTTPS starts the installation and serves HTTPS on the run that follows it. The key of Caddy's repository is trusted as downloaded over HTTPS, the way Caddy's installation instructions do it. Going back to the archive's Caddy is a manual downgrade. -## ADR-32: The PKI is kept in the router's directory +## ADR-32: The PKI is kept in the server's directory Status: Accepted Context: The CAs, their keys and CRLs, the inventory of the certificates issued and their -revocations, and the router's and the users' certificates and keys need a store. Files with a +revocations, and the server's and the users' certificates and keys need a store. Files with a JSON state file cannot be searched, and are copied apart from the users the certificates belong -to. The router runs slapd, which holds the users and is provisioned on every +to. The server runs slapd, which holds the users and is provisioned on every configured router (ADR-10), and PostgreSQL, which holds the refresh tokens and the metrics, may be another server (`web.database`) and is in a backup only with `backup.metrics`. RFC 4523 defines `pkiCA` with `cACertificate` and `certificateRevocationList`, and `userCertificate`, which OpenLDAP's core schema includes. -Decision: The PKI is held in `ou=pki` of the router's directory. A CA is an entry of the package's -class `vpnRouterAuthority` with `cACertificate` and `certificateRevocationList`, its key, its CSR, +Decision: The PKI is held in `ou=pki` of the server's directory. A CA is an entry of the package's +class `linuxManagerAuthority` with `cACertificate` and `certificateRevocationList`, its key, its CSR, its CRL number, the source of the root CRL and the time it was retired; a certificate is an entry -of `vpnRouterCertificate` named by its serial number under its CA, with `userCertificate`, its +of `linuxManagerCertificate` named by its serial number under its CA, with `userCertificate`, its kind, template, names, expiry and revocation, and the key of a router or user certificate. A user's certificate is also the `userCertificate` of the user's entry. An ACL lets no account read -`vpnRouterPrivateKey`; only root, the database's root DN, does, through the local socket. A +`linuxManagerPrivateKey`; only root, the database's root DN, does, through the local socket. A retired CA keeps its entry, renamed, so its certificates stay in the inventory. A root supplied from outside, by cloud-init or by hand, is placed as files before the first setup with a platform, which imports and removes them. strongSwan, OpenVPN, Caddy and the system's trust store read files, @@ -905,15 +908,15 @@ restore brings both back together. The PKI depends on slapd, as the users alread PostgreSQL. The directory holds the CA keys, so it is as sensitive as the CA itself. The schema grows by the package's PKI attributes and classes, which setup adds to slapd's configuration. -## ADR-33: The web service opens a shell for the Router Manager over a WebSocket +## ADR-33: The web service opens a shell for the Manager over a WebSocket -Context: The Router Manager's Shell page gives an administrator a terminal on the router in the +Context: The Manager's Shell page gives an administrator a terminal on the server in the browser, with xterm.js, the terminal of VS Code. A terminal needs a full-duplex channel, which xterm.js expects as a WebSocket. The web service runs in a sandbox (`NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome`) that a shell must not inherit, and as root, which a shell in a browser should not be. A stolen session cookie or access token alone must not give a shell. -Decision: `/shell` of the web service is off until `web.shell` is set on the router; the Router +Decision: `/shell` of the web service is off until `web.shell` is set on the server; the Manager cannot set it. The shell runs as the console account of the signed-in user (ADR-34), so it is never root and each administrator's shell is the administrator's own; a user without console login gets none. `POST /shell` signs the user in again with the password @@ -931,34 +934,34 @@ keeps the sign-in at every opening. The WebSocket of RFC 6455 is implemented on web service's `http.server`, server side only, without extensions. `systemd-run --pty` starts the shell in a transient unit with a PAM login session, outside the sandbox, and `setsid --ctty` makes the terminal its controlling terminal so window sizes reach the shell. A shell idle for -`web.shell_idle_minutes` is closed, and the journal records every opening, end and refusal. The Router -Manager checks the session and the WebSocket's origin, and relays the bytes to the router after +`web.shell_idle_minutes` is closed, and the journal records every opening, end and refusal. The +Manager checks the session and the WebSocket's origin, and relays the bytes to the server after both handshakes. Consequences: Who can sign in as a member of `admins` and knows the password and the current code, -or holds one of the user's passkeys and unlocks it, can get a shell when the router allows one and +or holds one of the user's passkeys and unlocks it, can get a shell when the server allows one and the user's console login is on; a session alone cannot. A failed passkey proof is refused but not counted as a failed login, as with the passkey sign-in. The ticket travels in the URL and appears in request logs, used up. The shell's sessions -show up as `vpn-router-shell-` units and logind sessions of the console account. The shell's -traffic is as protected as the Router Manager's: HTTPS to Caddy, plain HTTP on the internal +show up as `linux-manager-shell-` units and logind sessions of the console account. The shell's +traffic is as protected as the Manager's: HTTPS to Caddy, plain HTTP on the internal network to the web service. ## ADR-34: Console login maps an administrator to a POSIX account Context: A shell, SSH and sudo need a POSIX account. One shared system account for every administrator hides who did what and shares one set of rights. The administrators are users of -the router's directory, with their passwords, TOTP tokens and lockout there; a second set of +the server's directory, with their passwords, TOTP tokens and lockout there; a second set of local accounts would duplicate them. slapd listens on its local socket only. SSSD authenticates only over TLS or LDAPS and has no `ldapi://`; nslcd talks `ldapi://` and checks a password by binding as the user. -Decision: Console login is a property of a member of `admins`, `vpnRouterConsoleLogin`, that -only root on the router sets, as for the group `admins`. It runs the console as an existing local -account (`vpnRouterConsoleAccount`), or as the user's own POSIX account: the user's entry becomes a -`posixAccount` with a uid from 20000 up and the local group `vpn-router-console` as its group. +Decision: Console login is a property of a member of `admins`, `linuxManagerConsoleLogin`, that +only root on the server sets, as for the group `admins`. It runs the console as an existing local +account (`linuxManagerConsoleAccount`), or as the user's own POSIX account: the user's entry becomes a +`posixAccount` with a uid from 20000 up and the local group `linux-manager-console` as its group. nslcd serves the POSIX accounts with console login on, and PAM checks their passwords with a bind, -so slapd's otp overlay and password policy apply as for the Router Manager: the password followed -by the code, and the lockout. Members of `vpn-router-console` get sudo with that password. SSH +so slapd's otp overlay and password policy apply as for the Manager: the password followed +by the code, and the lockout. Members of `linux-manager-console` get sudo with that password. SSH accepts it only while `ssh.ldap_login` is set, in a `Match Group` drop-in of sshd. Switching console login off keeps the `posixAccount`, hidden by nslcd's filter, so the uid and the home stay the user's; leaving `admins` switches it off. A console reaches root through sudo, so a password alone @@ -977,48 +980,48 @@ are not removed with the user. A password is changed through the directory, not ## ADR-35: WireGuard peers are the devices of the VPN users, kept in the directory -Context: The WireGuard endpoint could be switched on from the Router Manager, but its peers were +Context: The WireGuard endpoint could be switched on from the Manager, but its peers were written by hand into `wg0.conf`, so nobody could connect without SSH. A peer is a P2S client like an OpenVPN or IKEv2 user, and one person may have several devices. Decision: A VPN user's entry holds the user's WireGuard peers in the multi-valued attribute -`vpnRouterWireGuardPeer`, one value ` [,...]` per device; the router never +`linuxManagerWireGuardPeer`, one value ` [,...]` per device; the server never sees a private key. `PUT /users/` replaces a user's peers after checking the keys, which -are unique, and the IPs, which do not overlap another peer's or cover the router's address. Setup +are unique, and the IPs, which do not overlap another peer's or cover the server's address. Setup reads the peers of the users who are not disabled from the directory and writes them as a marked block of `[Peer]` sections into `wg0.conf`; sections outside the block, added by hand, stay. A change of the peers, and disabling, enabling or removing a user with peers, restart setup. The -Router Manager adds and removes peers on the WireGuard tab of Remote access management, where the +Ubuntu Linux Manager adds and removes peers on the WireGuard tab of Remote access management, where the endpoint is, choosing the user for each. Consequences: Peers follow their users: disabling a user drops the user's devices, and the directory's backup holds them. A peer cannot exist without a VPN user. A change restarts `wg-quick@wg0` through setup, which briefly interrupts the other peers. -## ADR-36: Passkeys sign in to the Router Manager and the OpenID Provider, verified by the router with python3-fido2 +## ADR-36: Passkeys sign in to the Manager and the OpenID Provider, verified by the server with python3-fido2 -Context: Typing the password and a TOTP code at every sign-in to the Router Manager is tedious. +Context: Typing the password and a TOTP code at every sign-in to the Manager is tedious. WebAuthn needs a browser, HTTPS and a domain name; OpenVPN, IKEv2, WireGuard, SSH and sudo have no -browser, and the sudo PAM module for security keys needs the key at the router. The router signs +browser, and the sudo PAM module for security keys needs the key at the server. The server signs users in (`/auth`) and keeps them in its directory. The standard library cannot read CBOR or COSE -keys; Ubuntu packages Yubico's python-fido2 in noble (1.1) and resolute (2.0), whose server API is -the same once the JSON mapping of WebAuthn Level 3 is switched on, which 2.0 always uses. +keys; Ubuntu resolute packages Yubico's python-fido2 2.0 in universe, which always uses the JSON +mapping of WebAuthn Level 3. Decision: A passkey is a discoverable credential with user verification of the relying party -`wan.local_fqdn`, with the user name as its user handle, so the sign-in needs no name. The router -registers and verifies passkeys with python3-fido2 in `vpnrouter_passkeys`; the origin must be +`wan.local_fqdn`, with the user name as its user handle, so the sign-in needs no name. The server +registers and verifies passkeys with python3-fido2 in `linuxmanager_passkeys`; the origin must be HTTPS on that name, which python-fido2 checks. Each passkey is a JSON value of the multi-valued -`vpnRouterPasskey` on the user's entry, with the public key only. Registration needs the current +`linuxManagerPasskey` on the user's entry, with the public key only. Registration needs the current password and code, so a session alone cannot add a lasting way in; removal needs neither. A -passkey sign-in gives the same tokens as `/auth`; as it binds no password, the router checks that +passkey sign-in gives the same tokens as `/auth`; as it binds no password, the server checks that the user is enabled, not locked and not a service account. The begun steps are kept in the web service's memory for 2 minutes. The browser converts the options and answers with `PublicKeyCredential.parseCreationOptionsFromJSON`, `parseRequestOptionsFromJSON` and `toJSON`. The OpenID Provider's sign-in page (ADR-37) takes a passkey the same way. -Consequences: Passkeys are a convenience for the Router Manager and the OpenID Provider; the +Consequences: Passkeys are a convenience for the Manager and the OpenID Provider; the password and code stay for everything else, the shell included. A changed `wan.local_fqdn` orphans every passkey. The -Router Manager on another name, or in development on `localhost`, cannot use them. Failed passkey +Ubuntu Linux Manager on another name, or in development on `localhost`, cannot use them. Failed passkey sign-ins do not count towards the directory's lockout, but the sign-in calls are rate limited. Browsers without the JSON methods of WebAuthn Level 3 cannot add or use passkeys. @@ -1028,34 +1031,33 @@ Status: Accepted Context: -- **What is needed:** other systems, such as dashboards, should sign the router's users in with the +- **What is needed:** other systems, such as dashboards, should sign the server's users in with the directory's passwords, TOTP codes and passkeys, without a second user store. Programs on hosts without a browser, and jobs without a user, need tokens as well. Services such as an S3 gateway should learn from a token what its holder may do there, as resources of Entra ID do with app roles and scopes. - **What the archive has:** no packaged identity provider. `python3-oauthlib` and `python3-jwt` - are in main for noble and resolute; `python3-authlib` and `python3-jwcrypto` are in universe - only. + are in main; `python3-authlib` and `python3-jwcrypto` are in universe only. - **What oauthlib does:** it implements the OAuth 2.0 and OpenID Connect flows, including the client credentials grant, and leaves the checks, the storage and the signatures to the - application. Noble's 3.2.2 has no device authorization grant (RFC 8628). Resolute's 3.3.1 has - one, as has the current 4.0.0, but it checks no device code and never answers + application. Resolute's 3.3.1 has a device authorization grant (RFC 8628), as has the current + 4.0.0, but it checks no device code and never answers `authorization_pending` or `slow_down`. - **What the web service has:** it already checks passwords and passkeys, rate limits sign-ins and keeps tokens in PostgreSQL, and Caddy serves it over HTTPS on `wan.local_fqdn`. ADR-3's HS256 - key must not leave the router, but a relying party or a resource verifies a token itself. + key must not leave the server, but a relying party or a resource verifies a token itself. Decision: -- **Where it runs:** the web service is the OpenID Provider, in `vpnrouter_oidc`, while +- **Where it runs:** the web service is the OpenID Provider, in `linuxmanager_oidc`, while `oidc.enabled` is true. Its issuer is its HTTPS site, `https://:`, without the port on 443, and it answers the provider's paths only on `127.0.0.1`, where Caddy passes them. - **Clients:** - A client is a service account with redirect URIs or grants, kept with the account in - attributes of `vpnRouterAccount`: `vpnRouterRedirectUri`, `vpnRouterPostLogoutRedirectUri`, - `vpnRouterAllowedGroup`, `vpnRouterGrantType`, `vpnRouterPublicClient` and - `vpnRouterClientScope`. + attributes of `linuxManagerAccount`: `linuxManagerRedirectUri`, `linuxManagerPostLogoutRedirectUri`, + `linuxManagerAllowedGroup`, `linuxManagerGrantType`, `linuxManagerPublicClient` and + `linuxManagerClientScope`. - Its name is the client ID and its password the secret, checked with a bind; a public client has none. - Allowed groups limit who may sign in; without them every user may. @@ -1065,16 +1067,16 @@ Decision: - the device code; - the refresh token for the first and the last. - The device grant is the router's own grant class on oauthlib's token endpoint, with its + The device grant is the server's own grant class on oauthlib's token endpoint, with its authorization endpoint and pages, so it works the same with every oauthlib release. A loopback redirect URI matches with any port (RFC 8252). - **Consent:** a registered client is trusted, so there is no consent page, except for a device: the user who enters its code is asked to allow it, as RFC 8628 advises against remote phishing. - **The sign-in page:** the web service's own, a Jinja2 template with the password, the code and a - passkey, so the provider works without the Router Manager. + passkey, so the provider works without the Manager. - **Resources, as Entra ID:** - - Every service account is a resource. Its scopes are in `vpnRouterResourceScope`, and its roles - are `vpnRouterRole` entries (ADR-19) whose members are groups and accounts. + - Every service account is a resource. Its scopes are in `linuxManagerResourceScope`, and its roles + are `linuxManagerRole` entries (ADR-19) whose members are groups and accounts. - A token request names its resource with `resource` (RFC 8707) or by the resource's scopes, `:`, which the client's scopes must allow. - Without a resource, the tokens are for the client. @@ -1082,16 +1084,16 @@ Decision: resource only. - **Tokens:** - Both kinds are RS256 JWTs, signed with an RSA key the web service makes on its first run - (`/etc/vpn-router/oidc.key`), published as a JWK named by its RFC 7638 thumbprint; `sub` is + (`/etc/linux-manager/oidc.key`), published as a JWK named by its RFC 7638 thumbprint; `sub` is the entry's `entryUUID`. - An ID token is for the client and carries the user's roles of the client. - An access token follows RFC 9068: it is for the resource and carries the holder's roles there - and the scopes granted, so a resource needs nothing from the router but the JWKS. + and the scopes granted, so a resource needs nothing from the server but the JWKS. - Roles are read at every issue. - **Storage:** - Codes, device codes, access and refresh tokens and sessions are kept as their SHA-256 in the database of the refresh tokens. - - They are defined in `/usr/share/vpn-router/sql/oidc.sql`, with the procedures and functions + - They are defined in `/usr/share/linux-manager/sql/oidc.sql`, with the procedures and functions the module calls; a process loads the file at its first connection. - The operations that revoke the refresh tokens of `/auth`, of users and of service accounts, also revoke them, and every use of a code, a device code or a token checks the user and the @@ -1102,13 +1104,13 @@ Consequences: - **Requirements:** the package depends on `python3-oauthlib` and `python3-jwt`. The provider needs HTTPS, a public name and the web service. - **Management:** clients, resources and their roles are managed like service accounts, by the - CLI, `vpn-router-role`, `/service-accounts` and the Router Manager. + CLI, `linux-manager-role`, `/service-accounts` and the Manager. - **The directory keeps itself consistent:** - a group a client allows cannot be removed, and renaming it renames it in the clients and the roles; - a resource scope a client may ask for cannot be removed. - **Revocation:** an access token, a JWT, is valid at a resource until it expires, 5 minutes after - issue, whatever the router revokes. The signing key does not rotate; replacing it invalidates + issue, whatever the server revokes. The signing key does not rotate; replacing it invalidates every token issued. - **Lockout:** wrong client secrets lock the client like any account. - **Not offered:** the implicit and hybrid flows, the password grant and dynamic client @@ -1118,14 +1120,13 @@ Consequences: Status: Accepted -Context: The `vpn-*` commands have many subcommands, options and names (users, groups, issuing +Context: The `linux-manager-*` commands have many subcommands, options and names (users, groups, issuing CAs, templates, settings) that are hard to remember. bash-completion's README recommends its `completionsdir`, `/usr/share/bash-completion/completions` on Ubuntu, whose files it loads on the first Tab of their command, and calls the eagerly loaded `/etc/bash_completion.d` not -recommended; it prefers the name `.bash`, which noble's 2.11 and resolute's 2.16 both -look up. +recommended; it prefers the name `.bash`, which resolute's 2.16 looks up. -Decision: The package installs `.bash` for each `vpn-*` command into +Decision: The package installs `.bash` for each `linux-manager-*` command into `/usr/share/bash-completion/completions` and recommends `bash-completion`. The completions read the names they offer from the commands themselves (`--json list`) or the package's Python modules (the schema, the configuration, the PKI's templates and reasons), not from copies, and @@ -1140,45 +1141,45 @@ completions directory. Status: Accepted -Context: The Router Manager should show the router's logs without SSH. The web service runs as -root, so a path or a unit taken from a request could expose any file or journal on the router, +Context: The Manager should show the server's logs without SSH. The web service runs as +root, so a path or a unit taken from a request could expose any file or journal on the server, and a log of gigabytes cannot be sent whole to a browser. Decision: `/logs` serves the journal of a fixed list of units, the package's own and the services it runs, or the whole journal, read with `journalctl`, and the files `web.log_files` lists, -which `vpn-config-edit` sets; a unit or a path outside the lists is refused. A request answers +which `linux-manager-config-edit` sets; a unit or a path outside the lists is refused. A request answers at most 1000 lines, 200 by default, and a file is read from its last MiB only. The answer is read at each request; nothing is followed or kept. Consequences: Only administrators read logs, and only those listed. Showing a new file needs a configuration change, not code. Long histories stay with SSH and `journalctl`. -## ADR-40: Static web sites are served by the router's Caddy and defined in their own PostgreSQL database +## ADR-40: Static web sites are served by the server's Caddy and defined in their own PostgreSQL database Status: Accepted -Context: The router should host static web sites, each on its own port, with its own TLS and host -names told apart by SNI. Caddy already runs as the router's HTTPS proxy, configured by setup from a -template, and serves several hosts on one port by SNI. The configuration file holds the router's -settings; sites are many rows that change often and are edited by people who are not the router's +Context: The server should host static web sites, each on its own port, with its own TLS and host +names told apart by SNI. Caddy already runs as the server's HTTPS proxy, configured by setup from a +template, and serves several hosts on one port by SNI. The configuration file holds the server's +settings; sites are many rows that change often and are edited by people who are not the server's administrators. A separate role per database keeps a feature's data apart from the refresh tokens and metrics. -Decision: A site is a row of the `sites` table in the database `vpn-router-sites`, created by the -web service like `vpn-router` with its own role and password file, and changed through -`vpnrouter_sites` only, by `/sites`, `vpn-router-site` and the Router Manager; the table and its -procedures are in `/usr/share/vpn-router/sql/sites.sql`. `sites.enabled` and the upload limit stay +Decision: A site is a row of the `sites` table in the database `linux-manager-sites`, created by the +web service like `linux-manager` with its own role and password file, and changed through +`linuxmanager_sites` only, by `/sites`, `linux-manager-site` and the Manager; the table and its +procedures are in `/usr/share/linux-manager/sql/sites.sql`. `sites.enabled` and the upload limit stay in the configuration file. Setup reads the enabled sites at each run and adds a block per site to -the Caddyfile, served from `/var/lib/vpn-router/sites/`, with TLS none, Let's Encrypt, an +the Caddyfile, served from `/var/lib/linux-manager/sites/`, with TLS none, Let's Encrypt, an issuing CA of `pki.issuing_cas` through Caddy's internal issuer, or a certificate and key kept with the site; it opens each site's port on the interfaces of its `listen`. Caddy runs while HTTPS -is ready or a site is served. A site may not take a port of the router's own services or +is ready or a site is served. A site may not take a port of the server's own services or `wan.local_fqdn`; sites sharing a port need host names, the same `listen` and the same kind of TLS. A site's `editors` group may change its files besides the admins; renaming the group renames it in the sites, and a group a site has cannot be removed. Consequences: Sites need no change of the configuration file and are backed up as a database dump -with their folders. A site of Let's Encrypt needs its names to resolve to the router and port 80 +with their folders. A site of Let's Encrypt needs its names to resolve to the server and port 80 open, which setup opens on the external interface. While the database cannot be read, setup leaves the Caddyfile as it is. A site's folder is kept when the site is removed, unless asked otherwise. @@ -1191,16 +1192,16 @@ neither Ubuntu's nor Caddy's packages include; a custom build would leave apt. S a plain folder are rclone 1.65 and later (`serve s3`; noble has 1.60) and versitygw, which has no package. Azurite keeps blobs in its own format, which Caddy cannot serve. rclone 1.60 in the archive serves WebDAV with an auth proxy program and combines folders into one tree. The web -service and the Router Manager pass small JSON bodies only. +service and the Manager pass small JSON bodies only. Decision: The web service serves a site's files under `/sites//files/`: listing, download, upload of a raw body streamed to disk up to `sites.upload_max_mb`, extraction of a zip archive that refuses absolute paths, `..`, links and oversize content before writing, folders, renaming and removal, every path resolved inside the site's folder. While `sites.webdav` is true, -`vpn-router-webdav.service` runs `rclone serve webdav` on `127.0.0.1:7446` behind Caddy at +`linux-manager-webdav.service` runs `rclone serve webdav` on `127.0.0.1:7446` behind Caddy at `https://:`; its auth proxy, `webdav-auth`, binds as the user and gives an admin all sites and any other user the sites of its editors groups, one folder each. -rclone and PowerDNS are installed on demand from the archive by `vpn-router-install@`, +rclone and PowerDNS are installed on demand from the archive by `linux-manager-install@`, like Caddy. Consequences: Uploads and WebDAV use the directory's passwords, a TOTP code appended for an @@ -1211,8 +1212,8 @@ later. S3 and Azure Blob clients are not served. Status: Accepted -Context: The router hosts authoritative domains as their primary, with a secondary name server, and -a domain can give the sites their records without a registrar change per site. The router's own +Context: The server hosts authoritative domains as their primary, with a secondary name server, and +a domain can give the sites their records without a registrar change per site. The server's own name, `wan.local_fqdn`, belongs to a domain of its own, wherever that is hosted. Ubuntu has BIND, Knot and PowerDNS; only PowerDNS's gpgsql backend reads records from PostgreSQL, so changes are rows, without zone files or reloads. systemd-resolved's stub holds @@ -1221,22 +1222,22 @@ addresses, the addresses an authoritative server needs. The clients reach the in just as well, through the tunnel when it is in `local.cidrs` (ADR-43). Decision: While `dns.enabled` is true, setup runs `pdns.service` with -`/etc/powerdns/pdns.d/vpn-router.conf`, written before the packages are installed, on the -addresses of `dns.listen`, with the gpgsql backend on the database `vpn-router-dns` and PowerDNS's -own schema, and `primary=yes`. The domains and their manual records are rows of the router's tables -in that database, like the sites in `vpn-router-sites`, not settings of `vpn-router.json`: they are +`/etc/powerdns/pdns.d/linux-manager.conf`, written before the packages are installed, on the +addresses of `dns.listen`, with the gpgsql backend on the database `linux-manager-dns` and PowerDNS's +own schema, and `primary=yes`. The domains and their manual records are rows of the server's tables +in that database, like the sites in `linux-manager-sites`, not settings of `linux-manager.json`: they are many and change through the web service. The name servers are settings, the same for every domain: -`wan.local_fqdn`, the router's one name, is the primary, and `dns.secondary` the secondary. Setup +`wan.local_fqdn`, the server's one name, is the primary, and `dns.secondary` the secondary. Setup writes each domain as a MASTER zone through the procedure `dns_apply` of -`/usr/share/vpn-router/sql/dns.sql`: SOA with `wan.local_fqdn`, NS of `wan.local_fqdn` and +`/usr/share/linux-manager/sql/dns.sql`: SOA with `wan.local_fqdn`, NS of `wan.local_fqdn` and `dns.secondary`, an A or AAAA record of every host name of a site with `dns` `router` whose closest -domain it is, with the router's address the site chooses (`wan.public_address`, the internal or the +domain it is, with the server's address the site chooses (`wan.public_address`, the internal or the external interface's), and the manual records; the serial grows only when the records change, which makes PowerDNS notify. `wan.local_fqdn` gets no record in the domains: its A record is in the DNS of -its own domain, which the router does not manage. A site of `dns` `user` gets no records, as its +its own domain, which the server does not manage. A site of `dns` `user` gets no records, as its names are served elsewhere. The addresses `dns.secondary` resolves to at each run go to every domain's `ALSO-NOTIFY` and `ALLOW-AXFR-FROM` metadata, so the global `allow-axfr-ips` stays the -loopback default. The public address is a setting, since the router sees only private addresses on +loopback default. The public address is a setting, since the server sees only private addresses on its interfaces behind a cloud's NAT and resolving `wan.local_fqdn` would answer from its own DNS when it hosts that name. `dns.nameserver` and `dns.addresses` of an earlier configuration are left out when it is read, so that it loads; a missing `dns.secondary` makes setup warn, not fail, so that @@ -1255,22 +1256,22 @@ domain has the same two name servers. Status: Accepted -Context: IKEv2 and OpenVPN clients were given the router as their DNS server, answered by +Context: IKEv2 and OpenVPN clients were given the server as their DNS server, answered by systemd-resolved through a `DNSStubListenerExtra` drop-in. resolved synthesizes records for the machine's own host name, all its addresses, the Docker bridge and the tunnel addresses included, and for `_gateway` and `localhost`, on every stub, and systemd 255 has no setting that turns this off. Its extra stub also took port 53 of the addresses PowerDNS needs. dnsmasq-base is in main, a single binary without a service of its own, and forwards to one upstream server. -Decision: `vpn-router-resolver.service` runs dnsmasq, bound to the addresses of `p2s.dns_listen` +Decision: `linux-manager-resolver.service` runs dnsmasq, bound to the addresses of `p2s.dns_listen` only (`bind-interfaces`), forwarding to resolved's stub on 127.0.0.53, without `/etc/hosts` and without forwarding names that have no dot (`domain-needed`). resolved keeps its loopback stubs -only and stays the router's own resolver, with the upstream servers of the platform. Setup writes -`/etc/vpn-router/dnsmasq.conf` while IKEv2, OpenVPN or WireGuard runs, opens port 53 there for +only and stays the server's own resolver, with the upstream servers of the platform. Setup writes +`/etc/linux-manager/dnsmasq.conf` while IKEv2, OpenVPN or WireGuard runs, opens port 53 there for their client networks, and removes the earlier drop-in. Consequences: Clients resolve the names resolved resolves, Azure's internal names included, but -not the router's synthesized ones. The package depends on dnsmasq-base. PowerDNS and the clients' +not the server's synthesized ones. The package depends on dnsmasq-base. PowerDNS and the clients' resolver share no address. ## ADR-44: Apple VPN profiles are unsigned IKEv2 profiles with a PKCS#12 encrypted by a password given per download @@ -1278,7 +1279,7 @@ resolver share no address. Status: Accepted Context: macOS, iOS and iPadOS connect to the IKEv2 access with their built-in IKEv2 client, -configured by a configuration profile. The router keeps each user's certificate and key. Apple's +configured by a configuration profile. The server keeps each user's certificate and key. Apple's clients read a PKCS#12 only when it is encrypted with 3DES and SHA-1, send one proposal per SA, and show an unsigned profile as unverified. @@ -1297,31 +1298,31 @@ profile too. WireGuard is not part of it. Status: Accepted Context: The IKEv2 access is a split tunnel. macOS and iOS use the DNS server an IKEv2 VPN -pushes only for queries scoped to the tunnel, so names only the router resolves, such as Azure's +pushes only for queries scoped to the tunnel, so names only the server resolves, such as Azure's internal names, fail. RFC 8598 defines INTERNAL_DNS_DOMAIN (attribute 25): the client resolves the listed domains and their subdomains with the VPN's servers. strongSwan's pools take numeric attributes with string values; Apple profiles name such domains in `SupplementalMatchDomains`. Decision: The setting `p2s.dns_domains` lists the domains; setup pushes each as attribute 25 of the -IKEv2 address pool, and the Apple VPN profile gives them as match domains of the router's resolver, +IKEv2 address pool, and the Apple VPN profile gives them as match domains of the server's resolver, the addresses setup records for the web service. Consequences: Clients resolve the listed domains through the tunnel and everything else with their own resolvers. Clients that ignore attribute 25 keep the scoped behaviour; the Apple profile covers Apple devices. A changed list reaches an Apple device with a newly installed profile. -## ADR-46: vre opens files in the Shell page's editor over a socket checked by the peer's uid +## ADR-46: lme opens files in the Shell page's editor over a socket checked by the peer's uid Status: Accepted -Context: Administrators edit the router's files from the Router Manager's Shell page, in an editor +Context: Administrators edit the server's files from the Manager's Shell page, in an editor of the page rather than a terminal editor. The command that names a file runs in the shell, as the console account. The web service runs as root, sandboxed with `ProtectHome=yes`, so it cannot see the accounts' home folders. Reading and writing as root would also bypass the account's permissions. -Decision: Each shell has a random session in `VPN_ROUTER_SHELL`. `vpn-router-editor` (`vre`) sends -the session and an absolute path to the web service on `/run/vpn-router/editor.sock`, which anyone +Decision: Each shell has a random session in `LINUX_MANAGER_SHELL`. `linux-manager-editor` (`lme`) sends +the session and an absolute path to the web service on `/run/linux-manager/editor.sock`, which anyone may connect to. The web service accepts a request only when the peer's uid (`SO_PEERCRED`) is the uid of the session's console account. It then tells the shell's client over the shell's WebSocket, and the page reads and saves the file through `/shell/editor//`. Files are read and @@ -1330,10 +1331,10 @@ shell is. A save carries the SHA-256 of the content it replaces and is refused w changed since. Files open only while their shell lives. Consequences: The editor edits only what the console account may; a file only root may write is -edited in the terminal. `vre` run under sudo is refused, as its uid is not the console account's. +edited in the terminal. `lme` run under sudo is refused, as its uid is not the console account's. Each read and save starts a transient unit. Files are limited to 1 MiB of UTF-8 text. -## ADR-47: The web service is the package vpnrouter_web, with one module per family of paths +## ADR-47: The web service is the package linuxmanager_web, with one module per family of paths Status: Accepted @@ -1341,8 +1342,8 @@ Context: The web service answers about twenty families of paths: the status, the identities, the connections, backups, the PKI, logs, web sites, DNS, metrics and the shell with its editor. Kept in one script, the code of unrelated paths is read and changed together. -Decision: `/usr/lib/vpn-router/web` only initializes and serves. The package -`/usr/lib/vpn-router/vpnrouter_web/` holds the rest, laid out next to `vpnrouter_platforms/`: +Decision: `/usr/lib/linux-manager/web` only initializes and serves. The package +`/usr/lib/linux-manager/linuxmanager_web/` holds the rest, laid out next to `linuxmanager_platforms/`: - `handler`: the `Handler` class, which reads a request, checks its token and routes it. - One module per family of paths (`status`, `auth`, `identities`, `connectivity`, `backup`, `pki`, @@ -1373,9 +1374,9 @@ Decision: The code handles the exceptions it can expect where they occur, and an them with their reason in one line. An exception left unhandled is a defect to be fixed. As the last line of defence, every server replaces the default reports: -- `vpnrouter_serve.serve`, which the web service and the metrics service run, sets the servers' +- `linuxmanager_serve.serve`, which the web service and the metrics service run, sets the servers' `handle_error`, `threading.excepthook` and `sys.excepthook`. -- `vpnrouter_manager.serve`, which the Router Manager runs, does the same. +- `linuxmanager_ui.serve`, which the Manager runs, does the same. - The bootstrap server sets its server's `handle_error` and `sys.excepthook`. A `ConnectionError` of a client that went away is not logged; any other exception is logged in @@ -1402,14 +1403,14 @@ rewrapped later still matches the commit of its release. Status: Accepted -Context: The Router Manager's pages were explained only in its README. Help should be written as +Context: The Manager's pages were explained only in its README. Help should be written as plain files next to the code, shipped with the package, readable only after signing in, and able to show pictures. serve-markdown renders Markdown in the browser with marked, DOMPurify and github-markdown-css. Google Cloud's console shows its Learn panel on the right and moves the page left, so the help never covers what it explains. Decision: The help is the Markdown files of `docs/` (plain Markdown, no MDX), with SVG and PNG -pictures, installed to `/usr/share/vpn-router/manager/docs` and served by the manager at +pictures, installed to `/usr/share/linux-manager/manager/docs` and served by the manager at `/docs/` behind the session, with no-sniff and a CSP that keeps an SVG from running scripts. The browser renders them with marked (GFM) and DOMPurify, styled with github-markdown-css in the Manager's light or dark scheme, without syntax highlighting or @@ -1425,15 +1426,15 @@ help is not reachable without a session. Status: Accepted -Context: The Web Sites page uploads and downloads the files of the router's web sites, up to the -router's `sites.upload_max_mb`, by default 512 MiB. The manager's proxy reads a request body of at +Context: The Web Sites page uploads and downloads the files of the server's web sites, up to the +server's `sites.upload_max_mb`, by default 512 MiB. The manager's proxy reads a request body of at most 64 KiB into memory, sends it as JSON and holds the whole answer; the API helper of the page parses every answer as JSON. Encoding files in JSON would grow them by a third and still need the whole file in memory. Decision: `GET`, `HEAD` and `PUT` of `/api/sites//files/...` take their own route in the -manager: the request body is passed to the router as it is read, with its `Content-Type` and -`Content-Length`, and the router's answer is passed back as it arrives, with its `Content-Type`, +manager: the request body is passed to the server as it is read, with its `Content-Type` and +`Content-Length`, and the server's answer is passed back as it arrives, with its `Content-Type`, `Content-Length` and `Content-Disposition`. The page uploads with `XMLHttpRequest`, whose upload events give the progress `fetch` does not, sending the file as the raw body, a zip archive with `?unzip=true`, and downloads with `fetch` into a blob. Folders, renaming and removal stay JSON @@ -1443,49 +1444,49 @@ Consequences: Large files cross the manager without filling its memory. An uploa `Content-Length`, which browsers send for a file. Dropped folders are not uploaded as trees; a zip archive carries a tree. -## ADR-52: On a workstation, the router's URL is the Terraform output router_web_url +## ADR-52: On a workstation, the server's URL is the Terraform output router_web_url Status: Accepted Context: With `terraform_dir`, the manager built `http://:7081`. -The port of the router's web service is `web.port` and the interfaces it listens on are `web.listen`, +The port of the server's web service is `web.port` and the interfaces it listens on are `web.listen`, which the platform sets from its variables; the manager that `dev.sh` runs on a workstation cannot read them. Decision: `router_url` is the output `router_web_url` of the platform, which derives the URL from -the same variables that configure the router. +the same variables that configure the server. -Consequences: The manager follows the router's port and interfaces without settings of its own; a +Consequences: The manager follows the server's port and interfaces without settings of its own; a state written before the platform had the output gives no `router_url` until the next deploy. -## ADR-53: The system's packages are upgraded with apt-get upgrade, apart from the router's package +## ADR-53: The system's packages are upgraded with apt-get upgrade, apart from the server's package Status: Accepted -Context: The Overview tab upgrades only `vpn-router`. The router's +Context: The Overview tab upgrades only `linux-manager`. The server's operating system needs its other packages upgraded too, from the same page. An upgrade restarts services, the manager among them, so it cannot run inside the manager's unit. Decision: The System tab lists what `apt-get -s upgrade` would upgrade and runs `apt-get upgrade --y` through the same helper as the router's package, with `--system`, in its own transient unit +-y` through the same helper as the server's package, with `--system`, in its own transient unit and with its own state and log files, so each tab shows its own last upgrade. `upgrade`, not `dist-upgrade` or `full-upgrade`, so nothing is installed or removed; a package that needs a new dependency is kept back. The manager refuses an upgrade while the other runs; the check for updates is the same `apt-get update` for both. Consequences: Kept-back packages, a new kernel series among them, stay until upgraded on the -router. An upgrade of the system also upgrades the router's package when it is newer, which +router. An upgrade of the system also upgrades the server's package when it is newer, which the Overview tab's state does not record. -## ADR-54: The Shell page's editor is Monaco, opened by vre and loaded on demand +## ADR-54: The Shell page's editor is Monaco, opened by lme and loaded on demand Status: Accepted -Context: Administrators edit files on the router from the Shell page. The page needs no file +Context: Administrators edit files on the server from the Shell page. The page needs no file browser: the shell names the files, as `$EDITOR` would. Monaco is VS Code's editor component and is published as the ESM package `monaco-editor`. Its full entry point brings the language services of CSS, HTML, JSON and TypeScript, each with a worker, and its bundle is several megabytes. -Decision: The router's `vre` names a file in a text message over the shell's WebSocket, which the +Decision: The server's `lme` names a file in a text message over the shell's WebSocket, which the manager relays unchanged. The page reads and saves the file through the JSON proxy, whose body limit is raised for `/api/shell/editor/` alone to hold a file of up to 1 MiB escaped in JSON. Monaco 0.57 is bundled from npm through its tree-shakeable entry points: `monaco-editor/editor` @@ -1515,29 +1516,57 @@ system against a stored light or dark choice. Consequences: A page in the dark theme is dark from its first paint. The script depends on the storage key and class names of MUI's defaults, which `colorSchemeSelector: 'class'` uses. -## ADR-56: The Router Manager is part of the vpn-router package +## ADR-56: One package, linux-manager, installs every component Status: Accepted -Context: The Router Manager runs only on the router: it imports `vpnrouter_net`, `vpn-router-setup` -opens its ports and creates its first administrator, Caddy proxies it and the status reports it. -As a package of its own it would pin the router's version and the router its, and a change of the -router's API would need two repositories and two changelogs. +Context: The server is a directory, a PKI, an OpenID Provider, a web server, a name server, a +metrics and backup service and the Manager, and may also be a router and a VPN server. The Manager +runs only on the server: it imports `linuxmanager_net`, `linux-manager-setup` opens its ports and +creates its first administrator, Caddy proxies it and the status reports it. Packages of their +own would pin each other's versions, and a change of the server's API would need several +repositories and changelogs. -Decision: One package, `vpn-router`, installs the manager with the router. The manager's programs -are in `/usr/lib/vpn-router`, its application and help in `/usr/share/vpn-router/manager`, its -settings and secrets in `/etc/vpn-router` (`manager.json`, `manager-database.secret`, -`manager-admin.json`) and the state of its upgrades in `/var/lib/vpn-router`. The unit -`vpn-router-manager.service`, its transient units and its database keep their names. The debconf -questions of its first administrator are `vpn-router/admin_username` and `admin_password`. The -router's bootstrap page shows the manager, and the manager has no bootstrap service of its own. -The package carries no migration from the separate package: it has no relation to -`vpn-router-manager`, and dpkg refuses to install it beside that package, since both have -`vpn-router-manager.service`. `dev.sh` still runs the manager on a workstation, with -`terraform_dir` and `bind`. +Decision: One package, `linux-manager`, installs every component, the Manager included. The +router and the VPN are switched on in the configuration (ADR-57), not by installing packages. The +programs are in `/usr/lib/linux-manager`, the Manager's application and help in +`/usr/share/linux-manager/manager`, the settings and secrets in `/etc/linux-manager` +(`linux-manager.json`, `manager.json`, `manager-database.secret`, `manager-admin.json`) and the +state of the upgrades in `/var/lib/linux-manager`. The Manager's unit is +`linux-manager-ui.service`. The debconf questions of its first administrator are +`linux-manager/admin_username` and `admin_password`. The server's bootstrap page shows the +Manager, which has no bootstrap service of its own. `dev.sh` runs the Manager on a workstation, +with `terraform_dir` and `bind`. -Consequences: A router with the separate package is moved to this one by hand: remove -`vpn-router-manager` without purging it, move its files to the new paths, then install -`vpn-router`. A backup made before the merge restores the manager's files to -`/etc/vpn-router-manager`, where the manager no longer reads them. The repository holds the -manager's `web/` and `docs/`, and its build runs from the root. +Consequences: The repository holds the Manager's `web/` and `docs/`, and its build runs from the +root. A server that runs neither the router nor the VPN still has their programs and +dependencies installed. + +## ADR-57: The router and the VPN are components switched in the configuration + +Status: Accepted + +Context: The server is used without its routing and VPN features, as a directory, PKI and web +server on one network interface. Routing between two interfaces and site-to-site IPsec need two +interfaces; remote access needs only one, if its clients reach the server's networks from the +server's own address. + +Decision: `router.enabled` and `vpn.enabled`, both false by default, switch the two components. +With the router off, `site_to_site` must be empty, only `interfaces.external` is used, and it is +also the internal side of the services' `listen` choices; no route, forward rule or `rp_filter` +setting is written. With the VPN off, `p2s.enabled`, `openvpn.enabled` and `wireguard.enabled` +must be false, users get no VPN certificate, WireGuard peers and VPN profiles are refused, and the +Manager hides the Remote Access page. With the router off and the VPN on, setup masquerades each +ready VPN pool out of the external interface, so the clients reach `local.cidrs` from the +server's address. `linux-manager-setup` writes `/etc/sysctl.d/99-linux-manager.conf` while +either component is on: forwarding for both, a loose `rp_filter` for the router; it removes the +file while both are off and leaves the running values alone, as Docker also needs forwarding. The +built-in issuing CAs follow their component: `p2s` the VPN and `s2s` the router; they are created +when their component is first switched on and kept when it is switched off. Switching the VPN on +issues a certificate to each VPN user that has none. The firewall is written once any core +listener (web, HTTPS, metrics, DNS, sites) or component is configured; the IPsec rules only while +site-to-site or IKEv2 is ready. + +Consequences: A core-only server needs one interface and gets its firewall at its first setup +run. The readiness checks (`routing_ready`, `s2s_ready`, `p2s_ready`, `wg_ready`, +`openvpn_ready`) carry the switches, so every consumer of them follows the components. diff --git a/Dockerfile b/Dockerfile index ca46b45..0b6b284 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ ARG NODE_VERSION=24 -ARG UBUNTU_VERSION=24.04 +ARG UBUNTU_VERSION=26.04 FROM node:${NODE_VERSION}-bookworm-slim AS web WORKDIR /web diff --git a/OID-REGISTRY.txt b/OID-REGISTRY.txt new file mode 100644 index 0000000..aea1a10 --- /dev/null +++ b/OID-REGISTRY.txt @@ -0,0 +1,298 @@ +Private Enterprise Number 67380 S. Koszewski +Category: Registry November 2026 + + + OID Registry for the Linux Manager Arc 1.3.6.1.4.1.67380.10.1 + +Abstract + + This document is the registry of Object Identifiers (OIDs) under the + arc 1.3.6.1.4.1.67380.10.1, which the registry of the Private + Enterprise Number 67380 delegates to Linux Manager. It defines the + tree of the arc, the rules for allocating OIDs in it, and lists every + allocation. + +Table of Contents + + 1. Introduction + 2. Root + 3. Rules + 4. Tree + 5. Statuses + 6. Assignments + 7. Requesting an OID + 8. References + Author's Address + +1. Introduction + + The tree of the arc follows the layout of the root registry of the + Private Enterprise Number 67380 [PEN-REGISTRY]: it is split by + function at its top level, and another arc holds experimental + definitions. + + In this document, an OID written with a leading dot, such as ".2.1", + is relative to the OID root given in Section 2. + +2. Root + + +===========================+==========================+ + | Item | Value | + +===========================+==========================+ + | OID root | 1.3.6.1.4.1.67380.10.1 | + +---------------------------+--------------------------+ + | Parent registry entry | .10.1 linux-manager | + +---------------------------+--------------------------+ + + Table 1: Root + +3. Rules + + * A number is used once among its siblings. Arcs and leaves are + never reused or renumbered. + + * An allocated OID is never deleted. A retired OID is marked + deprecated and stays listed. + + * A frozen arc takes no new children. Its existing children keep + their status. + + * Leaves under an arc are assigned in order, starting from 1. + + * Function arc numbers have the same meaning as in the root + registry, both under the root of this arc and under its + experimental arc ".99". + + * Every leaf is listed in this document before it is used in + released software. + + * An experimental OID under ".99" is never used in released + software or in production. A definition that leaves the + experimental arc gets a new OID; the experimental OID is not + moved. + + * LDAP descriptors (short names) of schema elements under ".2" + carry the prefix "linuxManager". + + * Documentation and test examples use "1.3.6.1.4.1.32473" [RFC5612] + or "2.999", never this arc. + +4. Tree + + 1.3.6.1.4.1.67380.10.1 Linux Manager + .0 reserved, never allocated + .1 SNMP (reserved) + .2 LDAP / directory + .2.1 attribute types + .2.2 object classes + .3 PKI / X.509 + .3.1 certificate policies + .3.2 extended key usages (KeyPurposeId) + .99 Experimental: mirrors the function arcs + + Figure 1: Tree + +5. Statuses + + The statuses are those of the root registry [PEN-REGISTRY]: + reserved, active, frozen and deprecated. + +6. Assignments + + Each entry gives the OID and its name, followed by its fields. The + owner of every entry is "Slawomir Koszewski Org.". + +6.1. Arcs + + .0 reserved + Description: Never allocated + Status: reserved + Allocated: 2026-11-21 + Reference: none + + .1 snmp + Description: SNMP MIB modules, held for later use + Status: reserved + Allocated: 2026-11-21 + Reference: [RFC2578] + + .2 ldap + Description: The LDAP schema of the package + Status: active + Allocated: 2026-11-21 + Reference: [RFC4512] + + .2.1 ldap-attribute-types + Description: LDAP attribute types + Status: active + Allocated: 2026-11-21 + Reference: [RFC4512], Section 4.1.2 + + .2.2 ldap-object-classes + Description: LDAP object classes + Status: active + Allocated: 2026-11-21 + Reference: [RFC4512], Section 4.1.1 + + .3 pki + Description: PKI and X.509 + Status: active + Allocated: 2026-11-21 + Reference: [RFC5280] + + .3.1 pki-certificate-policies + Description: Certificate policies + Status: active + Allocated: 2026-11-21 + Reference: [RFC5280], Section 4.2.1.4 + + .3.2 pki-extended-key-usages + Description: Extended key usages (KeyPurposeId) + Status: active + Allocated: 2026-11-21 + Reference: [RFC5280], Section 4.2.1.12 + + .99 experimental + Description: Experimental definitions, never in + production + Status: active + Allocated: 2026-11-21 + Reference: [RFC4520], Section 3.1 + +6.2. LDAP Attribute Types + + Every attribute type below has the status active, was allocated on + 2026-11-21, and is defined in "linuxmanager_ldap.py" of this + repository. + + .2.1.1 linuxManagerScope + An authorization scope of the account + + .2.1.2 linuxManagerPrivateKey + A private key, PEM + + .2.1.3 linuxManagerCertificateRequest + The CSR of a CA, PEM + + .2.1.4 linuxManagerCRLNumber + The number of the last CRL of a CA + + .2.1.5 linuxManagerCRLSource + Signed or uploaded, where the CRL of a CA came from + + .2.1.6 linuxManagerRetired + When a CA was retired + + .2.1.7 linuxManagerKind + Ca, router, user or external, the kind of a certificate + + .2.1.8 linuxManagerTemplate + The template of a certificate + + .2.1.9 linuxManagerSubjectAltName + A subject alternative name of a certificate + + .2.1.10 linuxManagerNotAfter + When a certificate expires + + .2.1.11 linuxManagerRevoked + When a certificate was revoked + + .2.1.12 linuxManagerRevocationReason + Why a certificate was revoked + + .2.1.13 linuxManagerConsoleLogin + Whether the user may use a console + + .2.1.14 linuxManagerConsoleAccount + The local account the console of the user runs as + + .2.1.15 linuxManagerWireGuardPeer + A WireGuard peer of the user, its public key and IPs + + .2.1.16 linuxManagerPasskey + A passkey of the user, its credential as JSON + + .2.1.17 linuxManagerRedirectUri + A redirect URI of an OpenID Connect client + + .2.1.18 linuxManagerPostLogoutRedirectUri + A post-logout redirect URI of an OpenID Connect client + + .2.1.19 linuxManagerAllowedGroup + A group whose members may sign in to an OpenID Connect + client + + .2.1.20 linuxManagerGrantType + A grant an OpenID Connect client may use besides the + authorization code + + .2.1.21 linuxManagerPublicClient + Whether an OpenID Connect client has no secret + + .2.1.22 linuxManagerClientScope + A scope of a resource an OpenID Connect client may ask for + + .2.1.23 linuxManagerResourceScope + A scope of a resource of the OpenID Provider + +6.3. LDAP Object Classes + + Every object class below has the status active, was allocated on + 2026-11-21, and is defined in "linuxmanager_ldap.py" of this + repository. + + .2.2.1 linuxManagerAccount + Auxiliary: properties of a user or a Manager-only account + + .2.2.2 linuxManagerAuthority + Structural: a CA of the PKI + + .2.2.3 linuxManagerCertificate + Structural: a certificate a CA of the PKI issued + + .2.2.4 linuxManagerRole + Structural: a role of a resource of the OpenID Provider + +7. Requesting an OID + + An allocation is a change to this document. The change adds an + entry to Section 6 with every field filled in, and for a new arc + also updates Figure 1. A new function arc is first allocated in the + root registry [PEN-REGISTRY]. + +8. References + + [PEN-REGISTRY] + Koszewski, S., "OID Registry for Private Enterprise + Number 67380", November 2026. + + [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. + Schoenwaelder, Ed., "Structure of Management Information + Version 2 (SMIv2)", STD 58, RFC 2578, + DOI 10.17487/RFC2578, April 1999, + . + + [RFC4512] Zeilenga, K., Ed., "Lightweight Directory Access Protocol + (LDAP): Directory Information Models", RFC 4512, + DOI 10.17487/RFC4512, June 2006, + . + + [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) + Considerations for the Lightweight Directory Access + Protocol (LDAP)", BCP 64, RFC 4520, DOI 10.17487/RFC4520, + June 2006, . + + [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., + Housley, R., and W. Polk, "Internet X.509 Public Key + Infrastructure Certificate and Certificate Revocation List + (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, + . + + [RFC5612] Eronen, P. and D. Harrington, "Enterprise Number for + Documentation Use", RFC 5612, DOI 10.17487/RFC5612, + August 2009, . + +Author's Address + + Slawomir Koszewski diff --git a/README.md b/README.md index 8603fac..dc99b02 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,25 @@ -# vpn-router +# linux-manager -A Debian package that configures a Linux host or virtual machine as a VPN router: +A Debian package that configures a Linux host or virtual machine as a server managed by the +Ubuntu Linux Manager. Every component is installed; the router (`router.enabled`) and the VPN +(`vpn.enabled`) are switched on in the configuration, and the rest is the core. Without the +router the server needs one network interface, and the VPN clients reach the server's networks +through NAT from its address. The package provides: -- site-to-site IKEv2 IPSec with pre-shared key or certificate authentication (strongSwan swanctl) +- site-to-site IKEv2 IPSec, with the router on, with pre-shared key or certificate authentication (strongSwan swanctl) - IKEv2 access using EAP-TLS - a two-level certificate authority: a root, which may be kept offline, and issuing CAs for the VPN clients, for site-to-site and for general use, with certificate templates, published certificates and CRLs, and an optional ACME server - OpenVPN access with a certificate and a password per user, the users kept in a local - LDAP directory and managed with `vpn-router-user` or the web service + LDAP directory and managed with `linux-manager-user` or the web service - optional WireGuard endpoint - routing and NAT for a protected subnet, TCP MSS clamping, and UFW firewall rules - firewall rules for the ports Docker publishes, when Docker is installed -- metrics of the router kept in PostgreSQL, served for an OpenTelemetry Collector and pushed +- metrics of the server kept in PostgreSQL, served for an OpenTelemetry Collector and pushed over OTLP - static web sites served by Caddy, uploaded through the web service or WebDAV, and an optional - primary name server (PowerDNS) of the router's domains, with a secondary and records for the sites + primary name server (PowerDNS) of the server's domains, with a secondary and records for the sites Nothing in the package is specific to a cloud provider. It is built on the external and internal NIC names, and a `mode` setting says how much of the rest you are supplying and @@ -34,8 +38,8 @@ supported equally, and both end up with the same two things: a configuration fil service that applies it. ``` -/etc/vpn-router/vpn-router.json the configuration -systemctl restart vpn-router-setup apply it +/etc/linux-manager/linux-manager.json the configuration +systemctl restart linux-manager-setup apply it ``` If the host runs Docker, the recommended order is Docker first and the package second. The @@ -45,45 +49,44 @@ host that already runs Docker, and for installing Docker later, are under [Docke ### By hand ```sh -apt-get install vpn-router # answer "none" to the platform question -$EDITOR /etc/vpn-router/vpn-router.json -systemctl restart vpn-router-setup +apt-get install linux-manager # answer "none" to the platform question +$EDITOR /etc/linux-manager/linux-manager.json +systemctl restart linux-manager-setup ``` Answering `none` to the platform question defers everything: no further questions are -asked and nothing on the machine is configured. The only change an install makes is the -package's own `/etc/sysctl.d/` drop-in, which enables IP forwarding and relaxes -`rp_filter` as a router needs. Set `platform` in the file when you are ready. +asked and nothing on the machine is configured. Set `platform` in the file when you are +ready. ### Automated -Preseed the answers and the router comes up configured, with no follow-up command. Note +Preseed the answers and the server comes up configured, with no follow-up command. Note that `platform` must be something other than `none`, and `mode` says how much you are supplying: ```shell debconf-set-selections <<'EOF' -vpn-router vpn-router/platform select generic -vpn-router vpn-router/mode select manual -vpn-router vpn-router/external_interface string eth0 -vpn-router vpn-router/internal_interface string eth1 -vpn-router vpn-router/int_addr string 10.1.1.4 -vpn-router vpn-router/int_gateway_ip string 10.1.1.1 -vpn-router vpn-router/local_fqdn string router.example.com -vpn-router vpn-router/local_cidrs string 10.0.0.0/24 -vpn-router vpn-router/remote_addrs string peer.example.net -vpn-router vpn-router/remote_id string peer.example.net -vpn-router vpn-router/remote_cidrs string 192.168.0.0/24 -vpn-router vpn-router/psk password s3cr3t +linux-manager linux-manager/platform select generic +linux-manager linux-manager/mode select manual +linux-manager linux-manager/external_interface string eth0 +linux-manager linux-manager/internal_interface string eth1 +linux-manager linux-manager/int_addr string 10.1.1.4 +linux-manager linux-manager/int_gateway_ip string 10.1.1.1 +linux-manager linux-manager/local_fqdn string router.example.com +linux-manager linux-manager/local_cidrs string 10.0.0.0/24 +linux-manager linux-manager/remote_addrs string peer.example.net +linux-manager linux-manager/remote_id string peer.example.net +linux-manager linux-manager/remote_cidrs string 192.168.0.0/24 +linux-manager linux-manager/psk password s3cr3t EOF -DEBIAN_FRONTEND=noninteractive apt-get install -y vpn-router +DEBIAN_FRONTEND=noninteractive apt-get install -y linux-manager ``` With mode `interfaces` the `int_addr` and `int_gateway_ip` lines are dropped and read from the internal NIC instead; with mode `auto` the interface names go too. -Alternatively write `/etc/vpn-router/vpn-router.json` directly before or after installing. -A configuration-management tool should do that and then restart `vpn-router-setup`. +Alternatively write `/etc/linux-manager/linux-manager.json` directly before or after installing. +A configuration-management tool should do that and then restart `linux-manager-setup`. See [examples/](examples/) for a cloud-init template and a shell installer, and [examples/azure/](examples/azure/) / [examples/gcp/](examples/gcp/) for full Terraform examples @@ -91,12 +94,12 @@ that deploy a router on Azure or GCP. ## Configuration -`/etc/vpn-router/vpn-router.json` is JSON, mode 0600, and is created on first install. It +`/etc/linux-manager/linux-manager.json` is JSON, mode 0600, and is created on first install. It is managed with `ucf`, so it is yours to edit: a later `dpkg-reconfigure` applies the answers given and asks before touching anything you altered by hand, and an upgrade asks no questions and leaves the file as it is. Settings the file leaves out take their defaults when it is read, so a file written by cloud-init or by hand needs only the settings that differ. A complete example is -installed at `/usr/share/doc/vpn-router/vpn-router.json.example`. +installed at `/usr/share/doc/linux-manager/linux-manager.json.example`. The file is an object of sections, each an object of settings. A section or setting that is left out takes its default, and an empty string or empty list means unset. Every value @@ -106,20 +109,22 @@ must have the type shown below; an unknown section or setting is an error. |---|---|---|---|---| | `general` | `platform` | string | `none` | `none`, `generic`, `azure` or `gcp`. `none` defers configuration entirely | | `general` | `mode` | string | `manual` | How much you supply: `manual`, `interfaces` or `auto` | +| `router` | `enabled` | boolean | `false` | The router component: routing between the two NICs and site-to-site. Off, the server needs only `interfaces.external`, and `site_to_site` must be empty | +| `vpn` | `enabled` | boolean | `false` | The VPN component: IKEv2, OpenVPN and WireGuard. Off, `p2s.enabled`, `openvpn.enabled` and `wireguard.enabled` must be false. With the router off, the VPN clients reach `local.cidrs` through NAT from the server's address | | `interfaces` | `external` | string | | Name of the NIC facing the untrusted network | | `interfaces` | `internal` | string | | Name of the NIC facing the protected network | -| `wan` | `local_fqdn` | string | | This router's name or IP address: its IKE identity in `fqdn` mode, the name resolved in `public_ip` mode, the name of HTTPS, IKEv2 and OpenVPN, and the primary name server of its domains | -| `wan` | `public_address` | string | | The router's public IP address, which its own interfaces do not show behind a cloud's NAT: the address of the records of the sites with `dns_address` `public` | +| `wan` | `local_fqdn` | string | | This server's name or IP address: its IKE identity in `fqdn` mode, the name resolved in `public_ip` mode, the name of HTTPS, IKEv2 and OpenVPN, and the primary name server of its domains | +| `wan` | `public_address` | string | | The server's public IP address, which its own interfaces do not show behind a cloud's NAT: the address of the records of the sites with `dns_address` `public` | | `local` | `cidrs` | list | | Local subnets routed via the internal side, masqueraded to the external one, and offered to IKEv2 and OpenVPN clients | | `local` | `int_addr` | string | | This host's address on the internal network | | `local` | `int_gateway_ip` | string | | Next hop on the internal side | | `site_to_site` | | object | | The site-to-site connections, each a name and an object of the settings below | | `p2s` | `enabled` | boolean | `false` | IKEv2 access | | `p2s` | `address_pool` | string | | CIDR assigned to IKEv2 clients | -| `p2s` | `dns_domains` | list | | The domains IKEv2 clients resolve with the router's resolver (INTERNAL_DNS_DOMAIN, RFC 8598, and the match domains of the Apple VPN profile), at most 16 | +| `p2s` | `dns_domains` | list | | The domains IKEv2 clients resolve with the server's resolver (INTERNAL_DNS_DOMAIN, RFC 8598, and the match domains of the Apple VPN profile), at most 16 | | `p2s` | `dns_listen` | string | `internal` | The addresses of the resolver the IKEv2, OpenVPN and WireGuard clients are given: `internal`, `external` or `both` | | `wireguard` | `enabled` | boolean | `false` | WireGuard endpoint | -| `wireguard` | `address` | string | | The router's own address on `wg0` with the prefix of the peers' network, for example `192.168.200.1/24`; the network and the broadcast address of a network larger than /31 are refused | +| `wireguard` | `address` | string | | The server's own address on `wg0` with the prefix of the peers' network, for example `192.168.200.1/24`; the network and the broadcast address of a network larger than /31 are refused | | `wireguard` | `listen_port` | integer | `51820` | UDP port | | `openvpn` | `enabled` | boolean | `false` | OpenVPN access for users | | `openvpn` | `address_pool` | string | | IPv4 CIDR assigned to OpenVPN clients | @@ -130,7 +135,7 @@ must have the type shown below; an unknown section or setting is an error. | `web` | `enabled` | boolean | `true` | The status web service | | `web` | `listen` | string | `both` | The interfaces the status web service listens on: `internal`, `external` or `both` | | `web` | `port` | integer | `7081` | TCP port of the status web service | -| `web` | `database` | string | | A PostgreSQL connection string for the refresh tokens; without it, the `vpn-router` database on this host that the web service creates | +| `web` | `database` | string | | A PostgreSQL connection string for the refresh tokens; without it, the `linux-manager` database on this host that the web service creates | | `web` | `trusted_proxies` | list | the address the call came in on | Addresses whose `X-Forwarded-For` header names the client for the `/auth` rate limit and the Client IP of the status | | `web` | `status_content` | string | `basic` | What `/` and `/status` show: `basic`, `standard` or `full` (see Status web service) | | `web` | `shell` | boolean | `false` | `/shell` opens a login shell for a member of `admins` with console login (see The shell) | @@ -138,10 +143,10 @@ must have the type shown below; an unknown section or setting is an error. | `web` | `log_files` | list | | Absolute paths of the log files `/logs` shows, at most 32 (see The /logs API) | | `web` | `shell_auth_timeout` | integer | `15` | Minutes after the last use of a shell in which a new shell opens without signing in again, 0 (always sign in) to 1440 | | `ssh` | `ldap_login` | boolean | `false` | sshd accepts the directory password of the console accounts in the directory (see Console login and SSH) | -| `https` | `enabled` | boolean | `true` | Caddy serves the status web service and the Router Manager over HTTPS for `wan.local_fqdn` | +| `https` | `enabled` | boolean | `true` | Caddy serves the status web service and the Manager over HTTPS for `wan.local_fqdn` | | `https` | `email` | string | | The e-mail address of the Let's Encrypt account | | `https` | `web_port` | integer | `7444` | HTTPS port of the status web service | -| `https` | `manager_port` | integer | `7443` | HTTPS port of the Router Manager | +| `https` | `manager_port` | integer | `7443` | HTTPS port of the Manager | | `https` | `acme_staging` | boolean | `false` | Caddy takes its certificates from Let's Encrypt's staging environment alone, whose certificates no browser trusts and whose rate limits are higher, for routers rebuilt often (see HTTPS) | | `https` | `caddy_source` | string | `ubuntu` | Where Caddy is installed from: `ubuntu`, the Ubuntu archive, or `upstream`, Caddy's own repository (see HTTPS) | | `oidc` | `enabled` | boolean | `false` | The OpenID Provider at the status web service's HTTPS site, which needs `web.enabled`, `https.enabled` and `wan.local_fqdn` (see OpenID Provider) | @@ -149,28 +154,28 @@ must have the type shown below; an unknown section or setting is an error. | `sites` | `upload_max_mb` | integer | `512` | The largest upload of a site's file or zip archive, in MiB, 1 to 10240 | | `sites` | `webdav` | boolean | `false` | WebDAV of the sites' folders, which needs `https.enabled` and `wan.local_fqdn` (see WebDAV) | | `sites` | `webdav_port` | integer | `7445` | HTTPS port of WebDAV | -| `dns` | `enabled` | boolean | `false` | The primary name server of the router's domains, `wan.local_fqdn`, which must then be a DNS name (see Name server) | +| `dns` | `enabled` | boolean | `false` | The primary name server of the server's domains, `wan.local_fqdn`, which must then be a DNS name (see Name server) | | `dns` | `secondary` | string | | The secondary name server of every domain, a host name other than `wan.local_fqdn`; it may transfer the domains | | `dns` | `listen` | string | `external` | The interfaces the name server answers on: `internal`, `external` or `both` | | `dns` | `ttl` | integer | `300` | TTL of the records, 60 to 86400 seconds | -| `pki` | `root_name` | string | `VPN Router Root CA` | Common name of the root CA, when the router creates it | +| `pki` | `root_name` | string | `Linux Manager Root CA` | Common name of the root CA, when the server creates it | | `pki` | `root_days` | integer | `7300` | Days the root CA's certificate is valid | | `pki` | `ca_days` | integer | `3650` | Days an issuing CA's certificate is valid | | `pki` | `key` | string | `rsa-4096` | Key of the root and the issuing CAs: `rsa-2048`, `rsa-3072`, `rsa-4096`, `ec-p256` or `ec-p384` | | `pki` | `crl_days` | integer | `7` | Days the CRLs of the issuing CAs are valid | -| `pki` | `root_crl_days` | integer | `180` | Days the root CRL is valid, when the router signs it | +| `pki` | `root_crl_days` | integer | `180` | Days the root CRL is valid, when the server signs it | | `pki` | `publish` | list | `http` | Where the CA certificates and CRLs are published: `http`, `http-80`, `https`, `https-default` (see Certificates) | -| `pki` | `p2s_name` | string | `VPN Router P2S CA` | Common name of the P2S issuing CA | -| `pki` | `s2s_name` | string | `VPN Router Site-to-Site CA` | Common name of the site-to-site issuing CA | +| `pki` | `p2s_name` | string | `Linux Manager VPN CA` | Common name of the P2S issuing CA | +| `pki` | `s2s_name` | string | `Linux Manager Site-to-Site CA` | Common name of the site-to-site issuing CA | | `pki` | `issuing_cas` | object | | The general-purpose issuing CAs, each a name and `{name, templates, acme}` (see Certificates) | | `pki` | `templates` | object | | Certificate templates, each a name and the options it changes or defines (see Certificates) | | `pki` | `extended_key_usages` | object | | Custom extended key usages templates may give, each a name and its OID in dotted form (see Certificates) | -| `pki` | `root_key_warning` | boolean | `true` | `vpn-router-ca status` and `/ca` warn while the root key is on the router; `false` silences that warning | +| `pki` | `root_key_warning` | boolean | `true` | `linux-manager-ca status` and `/ca` warn while the root key is on the server; `false` silences that warning | | `metrics` | `enabled` | boolean | `true` | The metrics service: collection, history and `/metrics` | | `metrics` | `listen` | string | `internal` | The interfaces `/metrics` is served on: `internal`, `external` or `both` | | `metrics` | `port` | integer | `9464` | TCP port of `/metrics` | | `metrics` | `https_port` | integer | `9465` | HTTPS port of `/metrics`, served by Caddy while `https.enabled` is true | -| `metrics` | `service_account` | string | `metrics` | The service account `/metrics` takes, which `vpn-router-setup` adds and keeps | +| `metrics` | `service_account` | string | `metrics` | The service account `/metrics` takes, which `linux-manager-setup` adds and keeps | | `metrics` | `otlp_endpoint` | string | | An OTLP/HTTP URL the metrics are pushed to every minute, for example `https://collector.example.com:4318/v1/metrics` | | `metrics` | `otlp_username` | string | | The user name of HTTP Basic authentication at the OTLP endpoint | | `metrics` | `otlp_password` | string | | Its password | @@ -182,14 +187,14 @@ must have the type shown below; an unknown section or setting is an error. | `backup` | `enabled` | boolean | `false` | Scheduled backups (see Backups) | | `backup` | `schedule` | string | `daily` | `hourly`, `daily` or `weekly` | | `backup` | `target` | string | `local` | `local`, an archive in `backup.path`, or `pbs`, a Proxmox Backup Server | -| `backup` | `path` | string | `/var/backups/vpn-router` | The folder of local archives, an absolute path | +| `backup` | `path` | string | `/var/backups/linux-manager` | The folder of local archives, an absolute path | | `backup` | `keep_hourly` | integer | `24` | Hourly local archives kept, with the hourly schedule | | `backup` | `keep_daily` | integer | `7` | Daily local archives kept, with the hourly and the daily schedule | | `backup` | `keep_weekly` | integer | `4` | Weekly local archives kept | | `backup` | `keep_monthly` | integer | `12` | Monthly local archives kept | | `backup` | `keep_yearly` | integer | `0` | Yearly local archives kept | | `backup` | `metrics` | boolean | `false` | The backup holds the database of the metrics and the refresh tokens | -| `backup` | `rclone_remote` | string | | `remote:path` of `/etc/vpn-router/rclone.conf` the local archives are copied to | +| `backup` | `rclone_remote` | string | | `remote:path` of `/etc/linux-manager/rclone.conf` the local archives are copied to | | `backup` | `rclone_mode` | string | `sync` | `sync` mirrors the archives, `copy` deletes nothing in the cloud | | `backup` | `pbs_repository` | string | | `user@realm!token@host[:port]:datastore` | | `backup` | `pbs_password` | string | | The secret of the API token | @@ -202,8 +207,8 @@ must have the type shown below; an unknown section or setting is an error. `site_to_site` maps a connection name to its settings. A name starts with a lowercase letter and has at most 31 lowercase letters, digits and hyphens; it names the strongSwan connection, its child and its secret (`ike-psk-`). The install answers fill the connection -`remote-site`; more are added in the file, with `vpn-config-edit`, or through `/site-to-site` -of the status web service, which the Router Manager uses. +`remote-site`; more are added in the file, with `linux-manager-config-edit`, or through `/site-to-site` +of the status web service, which the Manager uses. | Setting | Type | Default | Meaning | |---|---|---|---| @@ -211,23 +216,23 @@ of the status web service, which the Router Manager uses. | `id` | string | | Remote IKE identity, an FQDN or an IPv4 or IPv6 address | | `cidrs` | list | | Remote subnets reachable through the tunnel | | `local_cidrs` | list | | Local subnets advertised into the tunnel | -| `local_id_mode` | string | `fqdn` | The router's IKE identity: `fqdn` is `wan.local_fqdn`, `public_ip` the address it resolves to, `internal_ip` the internal address | +| `local_id_mode` | string | `fqdn` | The server's IKE identity: `fqdn` is `wan.local_fqdn`, `public_ip` the address it resolves to, `internal_ip` the internal address | | `auth` | string | `psk` | How both sides authenticate: `psk`, a pre-shared key, or `certificate` | | `psk` | string | | Pre-shared key, with `auth` `psk` | | `psk_file` | string | | Path to a file holding the key; wins over `psk` | -| `remote_ca` | string | | With `auth` `certificate`, the PEM certificate of the CA that issued the peer's certificate; without it the router's site-to-site CA | +| `remote_ca` | string | | With `auth` `certificate`, the PEM certificate of the CA that issued the peer's certificate; without it the server's site-to-site CA | A connection is set up once all of `addrs`, `id`, `cidrs`, `local_cidrs` and its local -identity are known, with `psk` the key, and with `certificate` the router's site-to-site +identity are known, with `psk` the key, and with `certificate` the server's site-to-site certificate; all such connections are written to `/etc/swanctl/conf.d/site-to-site.conf`. Traffic from a connection's `local_cidrs` to its `cidrs` is not masqueraded. -With `auth` `certificate`, the router authenticates with its site-to-site certificate, which the +With `auth` `certificate`, the server authenticates with its site-to-site certificate, which the site-to-site issuing CA signs for `wan.local_fqdn` and for the public or the internal address that a connection with `auth` `certificate` uses as its identity (`local_id_mode` `public_ip` or `internal_ip`); it is issued again when that set of names changes. The peer's certificate must name `id` and be issued -by the router's site-to-site CA, or by the CA of `remote_ca`. A peer with no PKI of its own gets -its certificate from the router (template `site-to-site`, see Certificates), with the root and +by the server's site-to-site CA, or by the CA of `remote_ca`. A peer with no PKI of its own gets +its certificate from the server (template `site-to-site`, see Certificates), with the root and the site-to-site CA certificates as its trust anchors. A minimal site-to-site configuration in `auto` mode: @@ -249,18 +254,18 @@ A minimal site-to-site configuration in `auto` mode: } ``` -The router's IKE identity (`wan.local_fqdn` in `fqdn` mode) and the remote one (`id`) are +The server's IKE identity (`wan.local_fqdn` in `fqdn` mode) and the remote one (`id`) are an FQDN or an IPv4 or IPv6 address. They are written to the strongSwan configuration as given; strongSwan reads an address as an IP identity and a name as an FQDN, so a leading `@` is not needed and is refused. IKEv2 and OpenVPN access need a name in `wan.local_fqdn`. -WireGuard peers are VPN users' devices: a VPN user of the router's directory may have up to 16 +WireGuard peers are VPN users' devices: a VPN user of the server's directory may have up to 16 peers, each with its public key and its IPs, IPv4 addresses or networks, kept in the user's -entry (`vpnRouterWireGuardPeer`) and set with `PUT /users/` (`wireguard_peers`) or on the -WireGuard tab of the Router Manager's Remote access management. A key is used by one peer only, -the IPs of two peers may not overlap, and no peer's IPs cover the router's own address of +entry (`linuxManagerWireGuardPeer`) and set with `PUT /users/` (`wireguard_peers`) or on the +WireGuard tab of the Manager's Remote access management. A key is used by one peer only, +the IPs of two peers may not overlap, and no peer's IPs cover the server's own address of `wireguard.address`. The package owns the `[Interface]` section of `/etc/wireguard/wg0.conf` and, -between the lines `# BEGIN` and `# END WireGuard peers of the users of the router's directory`, a +between the lines `# BEGIN` and `# END WireGuard peers of the users of the server's directory`, a `[Peer]` section for each peer of a user who is not disabled; setup rewrites them when the settings or the peers change, and a change of a user's peers, disabling, enabling or removing a user with peers restarts setup. Every other `[Peer]` section, added by hand, is carried across @@ -306,28 +311,28 @@ Docker when `docker.service` is installed, and does nothing otherwise. Installing Docker first is the recommended order. After installing the package: -1. Set `general.platform` in `/etc/vpn-router/vpn-router.json`. While it is `none`, nothing is +1. Set `general.platform` in `/etc/linux-manager/linux-manager.json`. While it is `none`, nothing is configured, the Docker rules included. 2. List the TCP ports the running containers must expose to the internet, for example `"docker": { "exposed_ports": ["443"] }`. The default is none: once the rules are applied, every published port that is not listed is unreachable from the external interface, and remains reachable through the IPsec tunnel. -3. Apply the configuration with `systemctl restart vpn-router-setup`. Docker is running, so - this also restarts `vpn-router-docker`, which installs the rules. +3. Apply the configuration with `systemctl restart linux-manager-setup`. Docker is running, so + this also restarts `linux-manager-docker`, which installs the rules. 4. Check the result: ```sh - iptables -S DOCKER-USER # "-j VPN-ROUTER-DOCKER" is the first rule - iptables -S VPN-ROUTER-DOCKER # the rules of the external interface + iptables -S DOCKER-USER # "-j LINUX-MANAGER-DOCKER" is the first rule + iptables -S LINUX-MANAGER-DOCKER # the rules of the external interface ``` ### When Docker is installed after the package The Docker rules are not applied when Docker starts for the first time, so run -`systemctl restart vpn-router-setup` after installing Docker, then check as above. A reboot or a +`systemctl restart linux-manager-setup` after installing Docker, then check as above. A reboot or a restart of Docker applies them as well. -The rules sit in their own chain, `VPN-ROUTER-DOCKER`, entered by one jump at the top of +The rules sit in their own chain, `LINUX-MANAGER-DOCKER`, entered by one jump at the top of `DOCKER-USER`; other rules in `DOCKER-USER` are left alone. For traffic that arrives on the external interface, in this order: @@ -339,26 +344,26 @@ external interface, in this order: Traffic from every other interface, including the internal one and the Docker bridges, is not affected. The rules cover IPv4 only. -`vpn-router-setup` starts after `docker.service`, so Docker is up when it looks for it; the -ordering has no effect on a host without Docker. The `vpn-router-docker` service applies the +`linux-manager-setup` starts after `docker.service`, so Docker is up when it looks for it; the +ordering has no effect on a host without Docker. The `linux-manager-docker` service applies the rules after `docker.service` starts and removes them when Docker stops, so restarting Docker restores them. `systemctl restart -vpn-router-setup` applies a changed configuration while Docker runs. With `docker.mode` set to +linux-manager-setup` applies a changed configuration while Docker runs. With `docker.mode` set to `on`, the service fails when Docker is not installed or its daemon is not running; with `off` it removes the rules. ## Editing the configuration -`vpn-config-edit`, run as root, shows and changes `/etc/vpn-router/vpn-router.json`: +`linux-manager-config-edit`, run as root, shows and changes `/etc/linux-manager/linux-manager.json`: ```sh -vpn-config-edit show -vpn-config-edit set web.status_content standard -vpn-config-edit set web.port 7082 -vpn-config-edit set web.trusted_proxies 127.0.0.1,10.0.0.4 -vpn-config-edit set site_to_site.branch.addrs branch.example.net -vpn-config-edit remove site_to_site.branch -vpn-config-edit set --restart oidc.enabled true +linux-manager-config-edit show +linux-manager-config-edit set web.status_content standard +linux-manager-config-edit set web.port 7082 +linux-manager-config-edit set web.trusted_proxies 127.0.0.1,10.0.0.4 +linux-manager-config-edit set site_to_site.branch.addrs branch.example.net +linux-manager-config-edit remove site_to_site.branch +linux-manager-config-edit set --restart oidc.enabled true ``` `show` prints the file as indented JSON and does not change it. `set` takes a setting as @@ -366,34 +371,34 @@ vpn-config-edit set --restart oidc.enabled true creates with the defaults when it does not exist, and converts the value to the setting's type: a whole number, `true` or `false`, a list separated by commas (an empty value is an empty list), or a string; an unknown setting is refused. `remove site_to_site.NAME` removes a connection. It -checks the whole configuration as `vpn-router-setup` does, and only then writes the file, -indented, with mode 0600, and reminds that `vpn-router-setup` applies it; with `--restart`, `set` -and `remove` restart `vpn-router-setup` and wait until it has applied the change, and exit with +checks the whole configuration as `linux-manager-setup` does, and only then writes the file, +indented, with mode 0600, and reminds that `linux-manager-setup` applies it; with `--restart`, `set` +and `remove` restart `linux-manager-setup` and wait until it has applied the change, and exit with status 1 when it fails. The status web service writes the file the same way, and a lock keeps the two from overwriting each other's change. A refused request exits with status 2, any other failure with 1. ## Bash completion -Bash completes the commands, options and arguments of `vpn-router-user`, `vpn-router-group`, -`vpn-router-role`, `vpn-router-token`, `vpn-config-edit`, `vpn-router-backup`, `vpn-router-ca`, `vpn-router-caddy` -and `vpn-router-site` with the Tab key. The package installs a file per command in +Bash completes the commands, options and arguments of `linux-manager-user`, `linux-manager-group`, +`linux-manager-role`, `linux-manager-token`, `linux-manager-config-edit`, `linux-manager-backup`, `linux-manager-ca`, `linux-manager-caddy` +and `linux-manager-site` with the Tab key. The package installs a file per command in `/usr/share/bash-completion/completions`, which the `bash-completion` package, recommended by -`vpn-router`, loads on the first Tab after the command. For root, who can read them, the +`linux-manager`, loads on the first Tab after the command. For root, who can read them, the completions also offer the users and groups of the directory, the settings and site-to-site -connections of `vpn-router.json` with `true` and `false` for a boolean setting, the issuing CAs and +connections of `linux-manager.json` with `true` and `false` for a boolean setting, the issuing CAs and certificate templates, and the web sites; for other users only the fixed words. ```sh sudo -i -vpn-config-edit set oidc. -vpn-router-user passwd +linux-manager-config-edit set oidc. +linux-manager-user passwd ``` ## Applying changes ```sh -systemctl restart vpn-router-setup +systemctl restart linux-manager-setup ``` The service also runs at boot. With platform `none` it does nothing and says so. @@ -401,7 +406,7 @@ Otherwise it regenerates the configuration files, resolves the interfaces and th addresses as `mode` directs, applies routes, generates WireGuard keys and injects firewall rules. It provisions the user directory in `slapd` while OpenVPN or IKEv2 access is configured. It then starts `strongswan`, `wg-quick@wg0` and -`openvpn-server@vpn-router` if the corresponding feature is configured, reloading or +`openvpn-server@linux-manager` if the corresponding feature is configured, reloading or restarting them only when their inputs changed, and restarts the remote access clients' resolver only when its configuration changed. Turning a feature off in the configuration stops its service and removes its files. Every step is @@ -411,37 +416,37 @@ To regenerate the configuration files and PKI without starting, stopping or relo anything: ```sh -/usr/lib/vpn-router/configure +/usr/lib/linux-manager/configure ``` This does still write to the system: it renders into `/etc/swanctl/`, `/etc/systemd/resolved.conf.d/` and `/etc/wireguard/`, creates what the PKI is missing and adds the root CA to the host trust store. What it leaves alone is routes, firewall rules and -services - that is what `systemctl restart vpn-router-setup` adds. +services - that is what `systemctl restart linux-manager-setup` adds. ## Certificates -The router has a two-level certificate authority, kept by `vpn-router-setup` and managed with -`vpn-router-ca`, `vpn-router-user` and `/ca` of the status web service, which the Router Manager -uses. It is held in `ou=pki,dc=vpn-router,dc=local` of the router's directory, next to the users: +The server has a two-level certificate authority, kept by `linux-manager-setup` and managed with +`linux-manager-ca`, `linux-manager-user` and `/ca` of the status web service, which the Manager +uses. It is held in `ou=pki,dc=linux-manager,dc=local` of the server's directory, next to the users: ``` -cn=root the root CA; without vpnRouterPrivateKey while the root is offline -cn= an issuing CA; with vpnRouterCertificateRequest while it waits for the offline root -cn=-