Server admin

Failover with a standby server.

A standby server is a second install you can switch to if the first one fails. Switching is manual: you restore last night's backup on the standby, start it, and point your server's name at it.

The license

Enterprise licenses include a standby server at no extra cost. The license names two install IDs: the main server's and the standby's. The same license file works on both, and the standby shows Standby in the portal header and on the License page.

The standby is for failover only. Run it while the main server is down, not as a second live server alongside it. See the terms.

Before you start

  • Keep files on S3 or shared storage. A backup holds the database, settings and license, not your files. Use an S3 storage root, or mount the same network share at the same path on both machines (for example /srv/files), so the standby sees every file the main server had.
  • Use a DNS name or a movable IP. Users and clients connect by name, such as files.example.com. Give the record a short TTL, such as 5 minutes, so a change reaches everyone quickly. A floating IP that you can move between machines works too.
  • Run the same Farwing version on both. Upgrade the standby when you upgrade the main server.

Set up the standby

  1. Install Farwing Server on the second machine, the same way as the main one (see Server admin). Start it once and copy its install ID from the License page.
  2. Ask for a license that names both install IDs. Load it on the main server.
  3. Stop the standby and copy the main server's at-rest key to it. The key unlocks stored two-step sign-in secrets and the saved mail, S3 and single sign-on passwords. Backups leave it out on purpose, so a copied backup does not give those away. 
    scp main.example.com:/data/keys/at-rest.key /data/keys/at-rest.key
chown --reference=/data/farwing.sqlite /data/keys/at-rest.key
chmod 600 /data/keys/at-rest.key
  4. Leave the standby stopped. It only needs to run during a failover.

Back up every night

farwing-server backup writes a new folder with a consistent copy of the database, the config file, the license file and a manifest with a checksum for each file. It is safe to run while the server is serving. With no --to, it writes to a new folder under /data/backups.

OptionWhat it does
--to <folder>Where to write the backup. The folder must be new or empty.
--include-keysAlso copy the at-rest key and the portal's certificates. Only use this if the backups are stored as safely as the server itself.

With Docker Compose, from the folder that holds compose.yml:

# /etc/cron.d/farwing-backup on the main server
# Every night at 02:00: back up, copy to the standby, keep 14 nights.
0 2 * * * root cd /opt/farwing && \
  docker compose run --rm -T farwing backup --to /data/backups/nightly-$(date +\%F) && \
  rsync -a /data/backups/nightly-$(date +\%F) standby.example.com:/data/backups/ && \
  find /data/backups -maxdepth 1 -name 'nightly-*' -mtime +14 -exec rm -rf {} +

Without Docker:

# /etc/cron.d/farwing-backup on the main server, without Docker
0 2 * * * farwing farwing-server backup --data /data --to /data/backups/nightly-$(date +\%F) && \
  rsync -a /data/backups/nightly-$(date +\%F) standby.example.com:/data/backups/ && \
  find /data/backups -maxdepth 1 -name 'nightly-*' -mtime +14 -exec rm -rf {} +

Any copy tool works in place of rsync, such as aws s3 sync to a bucket the standby can read. Keep at least one copy off the main machine.

Switch to the standby

  1. Make sure the main server is stopped or unreachable. Two servers must not serve the same files at once.
  2. On the standby, restore the latest backup and start the server: 
    cd /opt/farwing
docker compose stop farwing
docker compose run --rm farwing restore /data/backups/nightly-2026-10-05
docker compose start farwing
    Without Docker: farwing-server restore --data /data /data/backups/nightly-2026-10-05, then start the service.
  3. Move the DNS record or the IP to the standby.
  4. Check the portal: sign in, open a storage root, and confirm the header shows Standby.

Anything that changed after the backup, such as new users, packages or settings, is not on the standby. Transfers that were running are paused and can be resumed from the Transfers page.

What restore does

  • Refuses to run while Farwing Server is running on that data folder.
  • Checks every file against the manifest and the database's own integrity check before changing anything. A backup from a newer Farwing version is refused.
  • Keeps the standby's own install ID, so the standby license applies.
  • Moves the files it replaces to /data/backups/before-restore-<time> instead of deleting them.
  • Stops if the machine does not have the at-rest key the backup needs. --accept-new-key restores anyway; two-step sign-in, the mail password and the S3 and single sign-on secrets then have to be set again.
  • --use-backup-install-id takes the install ID from the backup instead. Use it to rebuild the main server on new hardware, not on the standby.

Each machine keeps its own portal certificate unless the backup was taken with --include-keys. Otherwise, once the name points at the standby, get a certificate in Admin → Network → Certificate, as on the main server. If the config file names your own certificate files (web.tls_cert and web.tls_key), put the same files on the standby at those paths before you restore.

Switch back

  1. On the standby, take a backup: farwing-server backup, or docker compose run --rm farwing backup.
  2. Stop the standby.
  3. Copy the backup to the main server and restore it there. The main server keeps its own install ID.
  4. Start the main server and move the DNS record or IP back.

Farwing docs · farwing.io