Skip to Content

The store

Where Rookery keeps its state, how to put it in PostgreSQL and encrypt it, and how to move or restore an installation.

Rookery keeps its state in one store. It holds the hosts, their passwords, secrets, Rookery's own SSH key and the rest. An installation can be restored on another machine from the store and its key file alone. By default the store is the SQLite file rookery.db in Rookery's data directory. A Rookery server can keep it in a PostgreSQL database instead.

Choose the store

SettingWhat it is
storeA SQLite file, or a PostgreSQL URL such as postgres://rookery@db.example.org/rookery?sslmode=require. Empty: rookery.db in the data directory
store_keyThe key file that seals the store's values. By default store.key in the configuration directory
store_caA PEM file of certificate authorities to trust as well as the public ones, for a database with a private one
rookery config set store "/srv/rookery/rookery.db"
rookery config set store ""                      # back to rookery.db in the data directory

ROOKERY_STORE, ROOKERY_STORE_KEY and ROOKERY_STORE_CA in the environment take precedence over the settings. These three settings stay in config.json, as Rookery needs them to open the store.

With sslmode=require, Rookery connects over TLS and checks the server's certificate and its host name. verify-ca and verify-full do the same. Without an sslmode, or with any other, the connection is plain. A URL can contain the password, and rookery config set store URL shows it in the process list for a moment. Write it into config.json yourself to avoid that.

Encrypt it

Without a key, every secret, password and key in the store is readable to anyone who can read the database. That matters most on PostgreSQL, where others may run the database. rookery serve says so when it starts on PostgreSQL without a key.

CommandDoes
rookery server store statusSays where the store is, and how many of its values are sealed
rookery server store encryptMakes the key file and seals every value with it
rookery server store rekeySeals the values with a new key, and keeps the previous one beside it as store.key.old
rookery server store decrypt [--yes]Writes the values plain again and moves the key file aside to store.key.old

Stop rookery serve before you run them, as it would go on sealing with the key it loaded. The inbox, the jobs and the key-value store of rookery serve are not sealed.

Back the key file up apart from the database

The database cannot be read without its key file. Keep a copy of store.key somewhere other than the backups of the database, so that one stolen backup doesn't give away the secrets. Keep store.key.old as long as you keep backups from before a rekey.

What is in the store

In the storeKept as a file on the machineMade again
Host profiles, the passwords Rookery generated and the records of the machines it createdconfig.json, the settings of this machine, such as storeThe provisioning source, from the program
Registries, secrets and the other settings, with the SSH and sudo passwords of hostsThe key file, store.keyThe key files in keys/ and serve.token, written from the store
The SSH keys of the key ring, with a key being replaced beside its successorLogins to an OAuth 2.0 issuer, oauth.jsonThe plugin directory, from the store and npm
Each host's SSH host keys and the keys it takesThe known-hosts files in known_hosts/, written from the store
The token of rookery serve and its setup keyThe output of jobs, in jobs/ of the data directoryWhat this Rookery knows of a Rookery server, from its next mirror
Your own plugins, as npm's package.json and lock file, uploaded .tgz files and folders you copied inBuilds and installer ISOs
The inbox, the jobs and the key-value store of rookery serve

Rookery still uses the SSH keys and the token as files, as ssh, Ansible and people read them there. When the store has them, Rookery writes the files from it, each key to keys/NAME of the data directory when ssh needs it. A file that differs is moved aside to keys/NAME.replaced or serve.token.replaced, and Rookery says so.

On a machine whose plugin directory lacks plugins of the store, Rookery writes them back and runs npm ci or npm install there. That happens when rookery serve starts, and before the terminal UI or a command that uses plugins. A plugin installed from a folder or file of another machine is left out, and Rookery names it. Without npm, Rookery says so and goes on without the plugins npm installs.

Move to another database

rookery server store copy copies everything into another store, such as from the SQLite file to PostgreSQL:

rookery server store copy - <<< "postgres://rookery:PASSWORD@db.example.org/rookery?sslmode=require"
rookery server store copy /srv/rookery/rookery.db
rookery server store copy --target-file ~/rookery-database-url

- reads the target from standard input and --target-file from a file's first line. A URL as an argument shows up in the process list. The copy honours store_ca.

  • rookery serve has to be stopped on this machine first.
  • A target that holds anything already is refused. --into-existing adds to it, and keeps the rows it has.
  • Values are copied as they are, sealed or plain, and keep their times.
  • What this Rookery knows of Rookery servers is left out, as their next mirror fills it again.

The copy does not switch. When it's done, switch with rookery config set store TARGET or ROOKERY_STORE. With an encrypted store, the key file has to be wherever the store is used.

Restore on a new machine

Install Rookery

Install Rookery on the new machine as usual, or start the container image.

Put the key file in place

Copy store.key to the new machine, readable by its owner only (chmod 600). Skip this for a store that is not encrypted.

Point Rookery at the store

For PostgreSQL, set store to the database's URL. For SQLite, copy the file and set store to its path. Set store_key to the key file when it is not ~/.config/rookery/store.key.

Start it

Run rookery ls or start rookery serve. The hosts, secrets and settings are there. Rookery writes its SSH key and the token back. It logs in to the hosts with the same key, and clients of rookery serve stay connected. It reinstalls your own plugins with npm.

Without the key file, the encrypted values do not open. The error gives the path of the key file Rookery looked for. The output of jobs stays on the machine that ran them. The new one lists those jobs and says that their output is not there.

In the container

The image keeps the store in /data/rookery/rookery.db. For PostgreSQL with a key, give it these:

Give itAs
ROOKERY_STOREThe database's URL, with sslmode=require for TLS
ROOKERY_STORE_KEYThe path of the key file inside the container, such as /keys/store.key
The key fileA mounted folder, such as -v /srv/rookery/keys:/keys, with the file owned by uid 1000 and mode 0600
ROOKERY_STORE_CAA mounted PEM file, for a database with a private certificate authority
docker run -d --name rookery -p 127.0.0.1:7777:7777 \
  -e ROOKERY_STORE="postgres://rookery:PASSWORD@db.example.org/rookery?sslmode=require" \
  -e ROOKERY_STORE_KEY=/keys/store.key -v /srv/rookery/keys:/keys \
  -v rookery-config:/config -v rookery-data:/data \
  ghcr.io/aiviarium/rookery

The variables are visible to anyone who can inspect the container. To keep the password out of them, write store into /config/rookery/config.json instead. Mount the key's folder rather than the file alone, as a rekey writes beside it. To encrypt a new store, run docker exec rookery rookery server store encrypt with ROOKERY_STORE_KEY set, after stopping the server.

Edit on GitHub

Last updated on

On this page