# Operating pilcrow

## Upgrades

The `pilcrow` server will automatically upgrade its database on startup. Before doing so, it will create a backup of your database (at `pilcrow.db.backup`, or controlled by `--backup-database-url`). If the migration process succeeds, this backup will be deleted automatically. If the migration process _fails_, however, `pilcrow` will attempt to restore your existing database from the backup before exiting. If the restore process also fails, then both the backup database and the suspected-broken database will be left in place.

To avoid destroying backups that may still be needed, `pilcrow` will not start if the backup database already exists. **There is no catch-all advice on how to proceed**, but you can try the following:

- Start the server with **a copy** of the backup database, and determine if any data has been lost. If not, shut it down, replace your main database by copying the backup, and carry on.

The `pilcrow` database is an ordinary file. While the server is not running, it can be freely copied or renamed without invalidating the data in it.

## Permissions

The Pilcrow database (`pilcrow.db` by default) should have restricted permissions, as it contains data that is either confidential (such as users' conversations), sensitive (such as the service's configuration), or both. At minimum, it should not be world-readable on the server where Pilcrow is installed.

By default, the `pilcrow` command will set the process' umask to a value that prevents the creation of world-readable or world-writeable files, so that the Pilcrow database will be created with appropriate filesystem permissions. This behaviour can be controlled using the `--umask` startup option, which takes the following values:

- `masked`, the default, which takes the inherited umask and additionally sets the world-readable, world-writeable, and world-executable bits;
- `inherit`, which takes the inherited umask as-is, requiring the operator to set a sensible value here; or
- any octal value corresponding to a valid umask, such as `0027`.

Pilcrow does not check or change the permissions of the database after creation. Changing the umask of the server after the database has been created has no effect on the database's filesystem permissions.

## VAPID keys

Pilcrow uses [VAPID] to identify itself to public Web Push brokers, which then deliver notifications to Pilcrow's users of interesting events, such as messages. VAPID uses cryptographic signatures to authenticate the server.

[VAPID]: https://datatracker.ietf.org/doc/html/rfc8292

The key is stored in the `pilcrow` database. Pilcrow will create its key automatically, and will rotate the key every 30 days.

If the `pilcrow` database is accessed inappropriately or leaked, then the key can be used to send push notifications to Pilcrow users as if from the Pilcrow server. If this happens, the key _must_ be rotated to prevent misuse.

The key can be rotated at any time running `pilcrow […options…] rotate-vapid-key`, as the same user Pilcrow normally runs as. This does not require that the server be shut down or restarted. The `[…options…]` must be set to the same values as used by the running server.

When the key is rotated, no further push messages will be sent from the Pilcrow server using that key. Unfortunately, the Web Push protocol doesn't allow Pilcrow to proactively invalidate clients' push subscriptions, but Pilcrow will inform clients when the key is rotated so that they can invalidate the affected subscriptions themselves.