Connect a LibrePortal install
Pair an install with your Backup Server using a one-time code, check the certificate fingerprint, and watch its first backup.
On this page
Each LibrePortal you want backed up is connected once, with a one-time code. After that, the Backup Server looks after the rest.
Needs LibrePortal 0.10.8 or newer
Update the install first (Admin → Updates), then connect it.
Before you start#
The Backup Server opens the install's page once, to connect, and then reaches it over SSH every night. So the two have to be able to see each other on a private network, such as the Backup Server's VPN or the same home network.
The install's page also has to be on HTTPS. If it isn't, the Connect window offers to turn that on for you.
Don't make the Backup Server a trusted place
It's tempting to add the Backup Server to the install's trusted places so that it can reach the page. Don't. Trusted places can reach your private apps, and the Backup Server should only ever reach the one read-only door. If the install's page only answers its trusted places, use the command-line way below instead.
Connect from the panel#
- On the install, open Admin → Backups → Locations and press Connect to a Backup Server. It shows an address and a code. The code works once and runs out after 10 minutes. It also shows the install's certificate fingerprint.
- On the Backup Server panel, sign in over the VPN, open Sources and press Add source. Choose LibrePortal.
- Type the install's Address and the Pairing code, then press Connect.
- Check the fingerprint. The Backup Server shows what it found, including the install's LibrePortal version and certificate fingerprint. It must match the one in the install's Connect window. If it doesn't, stop: something is sitting between the two.
- Name the source with lowercase letters, digits and dashes, 3 to 40 characters. Then press Add this source. You don't need the master password for this: the Backup Server makes the source's repository itself, and its first backup starts within a few minutes.
Why you check the fingerprint
The code is only sent after you've confirmed the fingerprint, so a wrong address, or something pretending to be your install, can't pick it up. The install then lets the Backup Server's key read from it, and only from the Backup Server's address.
Or make an invite#
If the Backup Server has a public address, it can make one code that does the whole connection, so the install never has to be typed into the panel.
- On the Backup Server panel, open Sources and press Make an invite.
- Name the new source, set its storage limit, and choose Valid for: 10 minutes (the default), 1 hour, 1 day, 2 days or 7 days. Then press Make an invite.
- Pass the code on. It is shown once. On the other LibrePortal, open Backups → Locations → Have an invite code? and paste it, or run
libreportal backupserver join.
The code works once. The list under the form shows each waiting invite with the time it has left, such as "9 minutes left", and Revoke takes one back at once.
Short on purpose
You usually make an invite while you set things up together, so it closes after 10 minutes unless you choose longer. While an invite is waiting, one port on the Backup Server is open for it and nothing else. The port closes when the invite is used, revoked or runs out. On the command line it is sudo librebackup invite NAME --for 10m|1h|1d|2d|7d. Invites made before this choice existed keep the time they were made with.
When the Backup Server is behind a router#
A Backup Server at home, with no public address, cannot be reached from outside, so it cannot hand out an invite. Use the steps above. If your LibrePortal has a public address, the Backup Server then dials out to it over a private link of its own, and the answer says which way it went ("Path: ..."). On the command line it is the same: sudo librebackup source accept NAME --address HOST:PORT --code CODE --fingerprint FP.
The link is made just for this one Backup Server: its own network card, its own port and no one else's key. Your admin VPN is not touched. Unpairing on the install takes the link and its port away again. "Restore from your Backup Server" is not offered for a source connected this way.
If neither machine can be reached from the internet, a relay is needed. That is not built yet.
What the install does#
When you add the source, the install installs the Backup Server's key as the one key its read-only backup-reader account accepts, tied to the Backup Server's address. It opens SSH to that one address and nothing else, and it sends its backup retention rules along. The source is added already approved, because you confirmed it on both screens. You can follow this on the install's Tasks page.
That account can read what a backup needs and write nothing. The WebUI's own login secrets and logs are left out on purpose, so after a restore from the Backup Server alone, the WebUI shows its first-run page and asks you to make a new admin account. Your apps and their data come back as they were.
From the install's terminal#
If the two machines can't open each other's web pages, pair the other way round. On the Backup Server, run:
sudo librebackup pair start
It shows a code, such as abcd-efgh-ijkl-mnop, and its certificate fingerprint, and listens for 10 minutes. Then, on the install, run:
sudo -u libreportal libreportal backupserver pair
It asks for the Backup Server's address, the fingerprint and the code. It checks the fingerprint before it sends anything. Back on the Backup Server, approve the new source:
sudo librebackup source approve NAME
sudo librebackup vault add-source NAME
source approve lets the Backup Server pull from it, and vault add-source creates its repository. NAME is the source's name.
The first backup#
Every source is backed up every night, at 02:00 plus a moment of its own within the following hour so that sources take turns. If you want to see it work now, open the source in the panel and press Back up now, or run:
sudo librebackup backup NAME
sudo librebackup status
status lists the last backup of every source and says OK or STALE for each. A source's page in the panel shows the same, and keeps its backups in a list on its Backups tab.
Try a restore soon
A backup you've never restored is a hope, not a backup. Once the first one has run, try one restore while nothing is wrong. Everyday use shows a gentle way.
Disconnecting an install#
To stop an install being backed up, open its source on the panel and use the Remove tab. That stops new backups and keeps the data until you also choose to delete it, which asks you to type the name again.
From the install's side, run:
sudo -u libreportal libreportal backupserver unpair
It removes the Backup Server's access to the install and the stored Backup Server settings, and asks you to type a confirmation first. Backups already on the Backup Server aren't touched.