Backups

Knocknoc keeps its data in files on disk and in a database, so back up both. Backing up the whole machine or VM covers everything on this page.

Which database you are on decides which of the next two sections to follow. Recent installations use PostgreSQL, and installations from before version 8.5 (September 2025) may still be on SQLite. To check, look at /opt/knocknoc/etc/knocknoc.conf for whichever of DBURL (PostgreSQL) or DBFile (SQLite) is set, ignoring the commented-out examples.

If the setup wizard installed HAProxy in front of Knocknoc, keep /etc/haproxy/haproxy.cfg and the certificate it points at under /etc/ssl/private/ as well.

Server: backing up PostgreSQL

The server can stay running.

sudo install -d -o knocknoc -g knocknoc -m 750 /var/backups/knocknoc
sudo -u knocknoc pg_dump -Fc knocknoc -f /var/backups/knocknoc/knocknoc-db-$(date +%F).dump
sudo tar -czf /var/backups/knocknoc/knocknoc-files-$(date +%F).tar.gz \
  -C / opt/knocknoc/etc opt/knocknoc/var/knocknoc.crt opt/knocknoc/var/knocknoc.key

Create the backup directory as shown. The knocknoc user has to be able to write the dump into it.

If your database is external or managed (see BYO PostgreSQL), use the backup tooling that comes with it.

Server: backing up SQLite

Only for older installations. See Moving from SQLite to PostgreSQL if you would like to migrate.

sudo install -d -o knocknoc -g knocknoc -m 750 /var/backups/knocknoc
sudo /opt/knocknoc/bin/knocknoc -backup-db -backup-db-dest /var/backups/knocknoc

The server can stay running. Knocknoc prints the file it wrote, for example /var/backups/knocknoc/knocknoc_backup_20260731_053828.db. Use this command rather than copying knocknoc.db yourself, which can produce an unusable backup.

Agent: what to back up

On Windows the agent's key file is written to C:\Windows\System32\keys.json, not to the install directory, unless you set KeysFile in the agent configuration.

Restoring a server running PostgreSQL

Install Knocknoc first, ideally the same version the backup came from. See Updates and upgrades.

1. Stop the server.

   sudo systemctl stop knocknoc

2. Put the configuration and certificate back.

   sudo tar -xzf /var/backups/knocknoc/knocknoc-files-<date>.tar.gz -C /
   sudo chown -R knocknoc:knocknoc /opt/knocknoc

3. Recreate the database empty.

   sudo -u postgres dropdb --if-exists knocknoc
   sudo -u postgres createdb -O knocknoc knocknoc

4. Load the dump.

   sudo -u knocknoc pg_restore -d knocknoc /var/backups/knocknoc/knocknoc-db-<date>.dump

5. Start the server.

   sudo systemctl start knocknoc

Restoring a server running SQLite

1. Stop the server.

   sudo systemctl stop knocknoc

2. Remove the current database and its two companion files.

   sudo rm -f /opt/knocknoc/var/knocknoc.db \
              /opt/knocknoc/var/knocknoc.db-wal \
              /opt/knocknoc/var/knocknoc.db-shm

3. Copy the backup into place and give it back to the knocknoc user.

   sudo cp /var/backups/knocknoc/knocknoc_backup_<timestamp>.db /opt/knocknoc/var/knocknoc.db
   sudo chown knocknoc:knocknoc /opt/knocknoc/var/knocknoc.db
   sudo chmod 600 /opt/knocknoc/var/knocknoc.db

4. Start the server.

   sudo systemctl start knocknoc

Restoring an agent

sudo tar -xzf /var/backups/knocknoc-agent-<date>.tar.gz -C /
sudo chown -R knocknoc-agent:knocknoc-agent /opt/knocknoc-agent
sudo systemctl restart knocknoc-agent

Give the agent a minute to reconnect before deciding it hasn't worked.

Checking that a restore worked

• Log in to the admin portal with the credentials you used before the backup, and confirm your users, groups and knocs are listed.
• Open Agents and check each one has been seen recently.
• Have a test user log in and grant themselves access to one knoc, then confirm the entry appears on the firewall or service behind it.

Still Having Issues?

We can help you out, contact us at [email protected].