Backup and Restore

Table of Contents

What to Back Up
Stop the Application First
Restoring

Need help?

Schedule a consultation with an Azul performance expert.

Azul operates no part of your installation, and the product includes no backup mechanism of its own, so backups are yours to plan. One directory, /var/lib/ljvmi, holds everything worth keeping, and you back it up as a whole.

What to Back Up

/var/lib/ljvmi contains four locations that matter:

Location What losing it costs you

Location	What losing it costs you
`events/` (`EVENTS_DB_PATH`, a single `events.duckdb` file)	The history of your estate, and your migration waves. Your inventory, its runs, its tags, and its trends are all computed from this file rather than living anywhere else, so losing it loses all four. Nothing else can rebuild it, unless you still hold the delivered files in `inbox/`, from which you can re-ingest the observations. The `events/tmp/` directory is scratch space for large reads, holds nothing worth keeping, and you can skip it.
`db/` (`APP_DB_PATH`)	Your accounts, your Forwarder registrations and their tags, your wave schedules, your exclusion groups, your audit log, your API tokens, and your quota counters. Recovering without it means re-registering every Forwarder, re-inviting every user, and starting the audit log again.
`inbox/` (`INBOX_DIR`)	The deliveries that have not been ingested yet and, by default, the deliveries that have. See the note below.
`vuln-data/` (`VULN_DATA_DIR`)	The active and the previous vulnerability dataset. The database remembers which one is active, so restore both together. This directory only sits under `/var/lib/ljvmi` when `VULN_DATA_DIR` points there, as in the example env file.

events/ (EVENTS_DB_PATH, a single events.duckdb file)

The history of your estate, and your migration waves. Your inventory, its runs, its tags, and its trends are all computed from this file rather than living anywhere else, so losing it loses all four. Nothing else can rebuild it, unless you still hold the delivered files in inbox/, from which you can re-ingest the observations. The events/tmp/ directory is scratch space for large reads, holds nothing worth keeping, and you can skip it.

db/ (APP_DB_PATH)

Your accounts, your Forwarder registrations and their tags, your wave schedules, your exclusion groups, your audit log, your API tokens, and your quota counters. Recovering without it means re-registering every Forwarder, re-inviting every user, and starting the audit log again.

inbox/ (INBOX_DIR)

The deliveries that have not been ingested yet and, by default, the deliveries that have. See the note below.

vuln-data/ (VULN_DATA_DIR)

The active and the previous vulnerability dataset. The database remembers which one is active, so restore both together. This directory only sits under /var/lib/ljvmi when VULN_DATA_DIR points there, as in the example env file.

If you can protect only one, protect events/. It is the only one that cannot be rebuilt by people doing work again.

Important

The inbox is a delivery queue, and the dataset is the archive. By default INBOX_RETAIN_AFTER_INGEST is true, so delivered files stay in the inbox after ingestion and the directory keeps growing, which can make the inbox the largest part of your archive. That makes the inbox a copy of the input you can debug or re-ingest from. Setting it to false removes each file once its rows reach the dataset, and the inbox then holds only what has not been ingested yet.

Keep these outside the backup, in your usual secret store:

FORWARDER_KEY_SECRET, because the readable copy of each Forwarder access key is recoverable from the database together with this secret and not without it. A backup carrying both hands over the keys.
SESSION_SECRET, on the same reasoning.
/etc/ljvmi/ljvmi.env, because it holds the secrets and the email relay parameters (LJVMI_EMAIL_*), and it lives outside the data directory.
The TLS keystore (TLS_KEYSTORE_FILE) and its password, when the installation serves HTTPS itself. Keep the keystore out of /var/lib/ljvmi, so that one copy of a data backup never yields both your estate and the ability to impersonate your installation.

Stop the Application First

Important

Never copy /var/lib/ljvmi while the application runs. Both databases stay open and partly buffered: the application database, and the DuckDB file with its write-ahead log. A copy taken from under a running process can produce an archive that does not open. You discover that at the moment you need it.

Stop the service, archive the whole data directory, and start the service again:

 sudo systemctl stop ljvmi
sudo tar czf /backup/ljvmi-$(date +%Y%m%d).tar.gz -C /var/lib ljvmi
sudo systemctl start ljvmi

Archive the directory as one unit, so the application database and the DuckDB file, with any write-ahead log beside it, come from the same moment. Keep the copy off the data disk.

The application is unavailable while it is stopped. A running Forwarder keeps delivering, and your installation picks the deliveries up after it starts again. With filesystem storage nothing is lost, and with S3 storage nothing is lost during a window shorter than the upload grant lifetime, 15 minutes by default. Don’t restart Forwarders while your installation is down, because a Forwarder can’t start until your installation is reachable.

Restoring

Stop the application.
Restore the archive over /var/lib/ljvmi.
Start the version that produced the backup. A backup taken before an upgrade belongs with the version it came from, because migrations run forward only. See Going Back.