Run it · 2 of 4
Its database and backups
SQLite for one server, PostgreSQL for several. What's kept, the state key that seals its secrets, consistent snapshots for your backups, moving to PostgreSQL, and what to do if the key is lost.
database in obs-beacond.yaml is where it keeps everything worth keeping:
sessions, incidents and their history, the audit log, settings saved in
the web interface, accounts, joined hosts and history. With it, a restart
signs nobody out, an open alert is still open, and incident numbers carry
on. Without it, all of that is in memory and a restart forgets it.
| Kind | For |
|---|---|
A SQLite file, such as /var/lib/obs-beacon/beacon.db |
One server. Nothing else to run |
| PostgreSQL 16 or newer, by URL | Several copies sharing one database (Scale and several copies) |
database: postgres://obs_beacon@db.example.org:5432/obs_beacon?sslmode=verify-full
database_password_file: /etc/obs-beacon/db-password # keep it out of the URL
The URL takes libpq's settings (sslmode, sslrootcert,
target_session_attrs and so on); search_path picks a schema. obs-beacond
makes its own tables, so its user must own the schema or be able to create
tables in it. On PostgreSQL, history is split into monthly partitions, and
retention drops whole months instead of running big deletes.
Upgrades bring the schema up to date on start. A release only ever adds to the schema, so the previous release runs on an upgraded database: that's what makes rolling upgrades and going back safe.
The state key
state_key_file is required with database: 32 random bytes, base64. The
packages make it at /etc/obs-beacon/state.key. Sign-in providers' tokens,
channel secrets and the agent CA are sealed with it (AES-256-GCM), and
session cookies are stored only as their SHA-256. So the database alone
signs nobody in and can't stand in for obs-beacond.
Back the key up, apart from the database. Without it obs-beacond refuses to start, rather than quietly make a new agent CA and strand every agent.
If it really is lost:
- Put a new key in place.
- With obs-beacond stopped, remove the old CA:
DELETE FROM meta WHERE k = 'agent_ca'(withsqlite3 <database>, orpsql). - Start obs-beacond, and give every agent the new
ca_fingerprint(obs-beacond caprints it). Agents with a token enroll again by themselves; joined ones need joining again.
Everyone is signed out, and secrets entered in the web interface need entering again.
Backups
SQLite: never copy the live file. Set snapshot, and obs-beacond writes
a consistent copy there at start and every snapshot_every (6 hours). Back
that up:
snapshot: /var/lib/obs-beacon/backup/beacon.db
# snapshot_every: 6h
PostgreSQL: with its own tools: CloudNativePG's backups to object
storage, pg_dump, or whatever already backs the server up.
With either, back up the state key separately, and data_dir
(/var/lib/obs-beacon by default), which holds the agent CA's certificate
and the ACME cache.
Moving from SQLite to PostgreSQL
Once, with obs-beacond stopped:
-
Set
databaseanddatabase_password_fileto the new, empty PostgreSQL database. Keepstate_key_fileas it is, and removesnapshot. -
Copy every row, in one transaction, with the counts checked on both sides:
sudo -u obs-beacon obs-beacond store copy -from /var/lib/obs-beacon/beacon.dbThe SQLite file isn't changed beyond bringing its schema up to date, so it stays as the way back.
-
Start obs-beacond.