Setting up

`failoverlb_setup.sh`

The one shot setup. Pulls the code, sets up Docker if it is missing, then hands off to install.sh.

Option	What it does
`-d, --dir <path>`	Where to install. Default `/data/docker/failoverlb`.
`-b, --branch <name>`	Branch to check out. Default `master`.
`-r, --repo <url>`	Where to clone from.
`--git-user`, `--git-token`	Credentials for a private repository.
`--skip-docker`	Do not touch Docker, it is already sorted.

Anything else is handed straight to install.sh, so the options below work here too.

`install.sh`

The per node half. Run it directly if you would rather do things by hand.

Option	What it does
`-n, --name <name>`	What to call this node. Defaults to the hostname.
`-a, --address <ip>`	Address other nodes reach this one on. Guessed if you leave it out, and worth checking the guess.
`-p, --priority <1-255>`	Who wins the election. Higher takes it.
`--join <host:port>`	Join an existing cluster through this node.
`--token <token>`	The join token, made on that node's Cluster page.
`--allowlist <cidrs>`	Networks allowed to load the GUI, comma separated.
`--acme-email <addr>`	Where the certificate authority sends expiry warnings. Optional.
`--upgrade`	Refresh an install that is already here. Never touches `.env`, never asks anything, never joins anything.
`-y, --yes`	Do not ask about anything.

The first node needs no --join. It starts a cluster and becomes its certificate authority. Every node after that needs --join and --token together.

`docker_setup.sh`

Docker CE on Ubuntu 22.04 and newer, done properly. Removes the old unofficial packages, adds Docker's own repository, writes a daemon.json that rotates logs so containers cannot fill the disk, and proves it works with hello-world.

If Docker is already installed it stops and tells you, rather than reinstalling, because on a box with containers running a reinstall can restart the daemon and take everything down with it. --force overrides that, and you should know what is running first.

The nginx build

`nginx-installer.sh`

Command	What it does
`install`	Build and install nginx with OpenSSL and every module.
`revert`	Roll back to the build from before the last install.
`domains`	List the domains in your config and which have certificates.
`autocert <email> [domain]`	Certificate every domain in your config and wire it in.
`cert <domain> <email>`	A new domain with no server block yet, set up end to end.
`renew`	Renew all certificates now.
`status`	Show the version and whether nginx is running.

To build with the WAF module: sudo WITH_MODSECURITY=1 ./nginx-installer.sh install. Turning the WAF on in the GUI does this for you.

Do not install python3-certbot-nginx

It depends on Ubuntu's nginx package, and installing that drops a stock binary on top of this build. You lose every module and the config stops loading. The installer sets up guards against this.

Recovery

Getting an administrator back in

sudo docker exec nginx-fleet-manager \
  python -m app.reset_admin --list

sudo docker exec nginx-fleet-manager \
  python -m app.reset_admin alice --reset-totp

For the case where somebody has lost their phone and used all their recovery codes. It needs root on the machine, which anybody who has it could use to read the database anyway, so it hands out nothing new. Every use is written to the audit log as coming from the console.

Getting local passwords back

sudo ./auth-recovery.sh --allow-local

For when single sign on is the only mode and the provider has stopped answering. Run it from the install directory on any node. It needs a shell on the box, which is the point: the way back in must not depend on the thing that broke.

Looking at what is happening

What	Command
The management screen's log	`sudo docker logs nginx-fleet-manager`
The agent's log	`sudo journalctl -u nginx-mgr-agent -n 50`
nginx's error log	`sudo tail -50 /var/log/nginx/error.log`
nginx's access log	`sudo tail -f /var/log/nginx/access.log`
Whether nginx is happy	`sudo nginx -t`
What nginx was built with	`nginx -V`
Tunnel status, on a workload	`sudo nfm-tunnel status`

Product

Start here

More

Commands