Commands for other software
Set the address an app advertises, find out which other apps a command recreated, preview a change before you make it, and keep firewall rules, all from a script.
On this page
Tools that run beside LibrePortal, such as LibreAdmin, LibrePost or your own scripts, need a few things a person clicking in the WebUI never does. This page lists them. Every command here works over SSH, prints stable JSON with --json, and goes through the same task list as anything else, so you can watch it in the WebUI.
Run them as the LibrePortal user, for example sudo -u libreportal libreportal app address forgejo.
The address an app advertises#
Some apps put their own address into the links they hand out: clone URLs, sign-in redirects, the links in their emails. When a server is only reached over a VPN or a home network, the address that works is one LibrePortal cannot guess. So you tell it, and it remembers.
libreportal app address forgejo # what is set, and what the app holds now
libreportal app address forgejo set 10.8.0.1 # http, on the app's own web port
libreportal app address forgejo set https://forgejo.home.lan
libreportal app address forgejo set 10.8.0.1 --port 3000 --scheme http
libreportal app address forgejo clear # go back to the address LibrePortal works out
libreportal app address list --json # every app with an address set
The address is kept by LibrePortal, not in the app's files, so it survives a reinstall, an update, a restore and an uninstall. The app is recreated only when its settings would really change. If the address is already in place, the command says so and touches nothing.
Only apps that have an address setting take one: today Forgejo, Gitea and Vaultwarden. For any other app the command says it has none. Apps whose address is part of who they are (Mastodon, Matrix, Stalwart and the like) never take one.
Add --dry-run to see what would change without changing it, and --no-apply to store the address and leave the app alone until it is next rendered.
libreportal app address forgejo set 10.8.0.1 --dry-run --json
libreportal app address <app> --json answers with libreportal.appaddress/1:
{"schema": "libreportal.appaddress/1", "app": "forgejo", "installed": true, "supported": true,
"source": "set",
"address": {"host": "10.8.0.1", "port": 3000, "scheme": "http", "url": "http://10.8.0.1:3000"},
"in_place": true,
"tags": [{"tag": "FORGEJO_DOMAIN_TAG", "now": "10.8.0.1", "wanted": "10.8.0.1", "in_place": true}]}
source is set, vpn or none. New fields may be added; none will be taken away. A key with the apps:read scope can read the same document at GET /api/v1/apps/<app>/address. Setting an address is a command on the server, not something a key can do.
Which other apps a command recreated#
Installing one app can change others. A mail server re-wires every app that can send through it. Authelia re-wires the apps that sign in with it. A script that ran app install stalwart used to have no way to know.
Now the command says so, and with --json the result carries it:
libreportal app install stalwart --json
{"schema": "libreportal.result/1", "schema_version": 1, "ok": true,
"command": "app install", "app": "stalwart", "exit_code": 0,
"recreated_apps": ["forgejo"], "queued_apps": [], "side_effects": [{"app": "forgejo", "action": "recreated", "reason": ""}]}
recreated_apps are apps that were reinstalled, recreated or had their settings written again while the command ran. queued_apps are apps only queued for later; the command does not wait for those. The app you asked about is never listed.
Preview first with --dry-run#
libreportal app install stalwart --dry-run --json
libreportal app uninstall stalwart --dry-run
libreportal app reload forgejo --dry-run
This changes nothing. It lists the other apps LibrePortal knows it would recreate (would_recreate_apps) and, in plan_does_not_cover, the side effects it cannot predict yet, so silence is never mistaken for "nothing else happens". Today it predicts mail and Authelia sign-in re-wiring.
Firewall rules#
Software that needs a firewall rule asks LibrePortal to keep it, rather than running ufw itself. Extra firewall rules has the whole story. The commands for a tool are:
libreportal firewall rule add --owner myapp 'allow tcp 9443 iif wg-hub'
libreportal firewall rule adopt --owner myapp 'allow tcp 9443 iif wg-hub' # a rule someone wrote by hand
libreportal firewall rule list --json --owner myapp
libreportal firewall rule remove --owner myapp
libreportal firewall reload
libreportal firewall batch apply --from-stdin --confirm-within 5m --json # many changes, one reload, all or nothing
libreportal firewall batch confirm --json
libreportal firewall hooks list --json # which hooks exist and how they last did
libreportal firewall hooks run --json # run them now
To check a server supports what you need, read features in libreportal firewall rule list --json: it lists route, to, any, label, adopt, hooks, batch, no-reload and confirm. The batch file format and the JSON are on the Extra firewall rules page. firewall hooks list --json exits 0 on any version that has hooks.
Forwarded traffic uses the same language with route in front: route allow iif wg-hub oif wg-hub. Switching on forwarding in the kernel is still up to you. The folder /etc/libreportal/hooks/firewall-post.d/ is created on install and on every update, with a README. Put an executable in it (owned by root, not writable by others) to be told after every rebuild and every firewall reload; they run in name order, 30 seconds each.