docs
cairnobs.org Demo Source
Esc

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.

2 min read

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:

  1. Put a new key in place.
  2. With obs-beacond stopped, remove the old CA: DELETE FROM meta WHERE k = 'agent_ca' (with sqlite3 <database>, or psql).
  3. Start obs-beacond, and give every agent the new ca_fingerprint (obs-beacond ca prints 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:

  1. Set database and database_password_file to the new, empty PostgreSQL database. Keep state_key_file as it is, and remove snapshot.

  2. 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.db
    

    The SQLite file isn't changed beyond bringing its schema up to date, so it stays as the way back.

  3. Start obs-beacond.