Backing up the server itself
Instance backups cover the instances. They do not cover the server's own state: the users, the instance configurations, the schedules, the alert rules and every stored credential, which live in the master database, and the key ring those credentials are encrypted under. An update that changes the master database's schema cannot be undone without a copy of it from before.
Take this backup before every update and after any large change to the server's configuration.
The stored credentials - the backup targets' passwords and keys, the SMTP password, the GeoIP key,
the git tokens, and from 0.24.0 the console accounts' authenticator secrets - are encrypted under the
management API's key ring, which is kept in the Docker
volume ohm-api-keys, not in the master database. So is the private key of the server's encrypted
backups. A master database restored without its key ring holds credentials nobody can read, and every
one of them has to be entered again. Its console accounts' authenticator codes are not checked
either: sign in with a recovery code, or run ohm user totp-disable on the server. An export with a passphrase keeps the two together, from the same
moment.
What to keep
| What | Where | How |
|---|---|---|
| The master database | In the shared PostgreSQL container, or the external SQL Server it was moved to | An export from Master data, below |
| The key ring | The Docker volume ohm-api-keys | In the same export, sealed under its passphrase |
| The license files | /root/.local/share/ohm/license/ | A copy of the directory |
| The master database's connection | /root/.local/share/ohm/conf/appsettings.json | A copy of the file, when the master database runs on an external SQL Server |
Each of them carries credentials or password hashes. Keep the copies where you keep secrets, and off the server.
Export the master database and its key ring
- Open Master data in the menu.
- Under Export, leave Target engine on the engine this server's master database runs on.
- Type a Passphrase of at least 16 characters, twice.
- Press Export now. The export is a job; the file is listed under the button when it ends.
- Download it with the download button on its row. Downloading needs the Administrator role.
With a passphrase the export is one .zip: the database script, and the key ring sealed under the
passphrase. Only the key ring is sealed. The script inside stays readable, and holds account hashes
and encrypted credentials, so treat the file as a secret all the same. The seal also records a digest
of the script, so a script changed after the export was written is refused on import.
The passphrase is never stored. Without it the sealed key ring cannot be opened, and the credentials in that export can never be read on another server. Keep it where you keep secrets, apart from the export.
Leave the passphrase empty for a plain .sql script without the keys. The Key ring column of the
list shows it as No key ring: its stored credentials cannot be read on another server, so it is
for reading, for running by hand, or for carrying to a server on another engine. It is not a backup
of the server on its own.
The file is kept on the server in /root/.local/share/ohm/data/master-export/ as well, which does
not survive the loss of the server: copy the download somewhere else.
From the command line, over a connection, --with-keys asks for the passphrase, or
--passphrase-file reads it from a file. It is never a value on the command line. -o downloads the
result:
ohm system database export --with-keys -o master-bundle.zip --server pelmo
Check the copy
The export's row on Master data shows its size; a file of a few kilobytes on a server with instances is not a whole database. Its Key ring column says Included.
What an update writes by itself
An update that upgrades the master database's schema writes an export of it first, before anything changes:
sudo ohm installwrites it to/var/lib/odoo/backup/schema/;sudo ohm database upgradewrites it to the backup directory,/var/lib/odoo/backup/, or to the directory--export-tonames.
That export is on the server's own disk and holds no key ring. It does not replace the backup above.
Putting it back
Master data > Import restores an export written for this server's engine, a .zip or a .sql.
The file is checked when it is uploaded and again by the job, and anything unusable is refused with
the database untouched. That includes a .zip whose script no longer matches the digest its seal
records: the job refuses it as soon as the passphrase has opened the seal, before anything is
written. A .zip from a release that did not record the digest yet is imported, and the job's
result notes that its script could not be checked.
- Drop the export on the page.
- For an export that carries its key ring, type its Passphrase. A wrong one changes nothing.
- Type the confirmation word
IMPORT, and press Replace the master database with this file.
The job writes a safety export of the current content first, sealed under the same passphrase when one was given, and says where it was stored. It then adds the export's keys beside the server's own, so what was readable here stays readable, replaces the database, and restarts the console and the API by itself. You may have to sign in again.
From the command line, over a connection:
ohm system database import master-bundle.zip --server pelmo
An export with a key ring cannot be imported without its passphrase. If it is lost, unzip the file
and import its master.sql: the stored credentials cannot be read then, and have to be entered
again.
An export from an older release
Import refuses an export from an older schema, and says which command to use, because older releases are no longer published. Bring the file forward on the server first:
sudo ohm database upgrade-export master-bundle.zip
It runs on the server only. It loads the export into a scratch database beside the live one, brings
it forward, and writes a new file next to the original, or to --output. The live database is not
touched, and the scratch database is dropped afterwards. An export with a key ring asks for its
passphrase, or reads it from --passphrase-file, and the new file carries the same key ring under
the same passphrase. A script changed since the export was written is refused here too, so it is
never sealed again as if the export had written it; an export from a release that did not record
the digest is brought forward with a warning that its script could not be checked. Then import the
new file as above.
To roll back an update, see Updating Antelao.