b51b942103
pdate the gateway how-to to follow changes in configuration: - configure the component with the simplifiedi configuration (`[component.email_gateway]`) - remove the "supported features" section (redundant with email gateway documentation in `components.rst`)
116 lines
4.8 KiB
ReStructuredText
116 lines
4.8 KiB
ReStructuredText
.. _howto_backup:
|
|
|
|
========================
|
|
How-To: Backup & Restore
|
|
========================
|
|
|
|
This document explains how to back up and restore your Libervia data with the ``li
|
|
backup`` command (see :ref:`the CLI reference <libervia-cli_backup>`). The export format
|
|
is based on XEP-0227 (Portable Import/Export Format), extended with Libervia-specific
|
|
sections. The result is a single archive (``.tar.xz``, optionally GPG encrypted) that you
|
|
can keep, transfer or store elsewhere.
|
|
|
|
Data types
|
|
----------
|
|
|
|
A backup is made of data *types*, included or excluded with ``-i/--include`` and
|
|
``-e/--exclude`` (repeatable):
|
|
|
|
- ``params``: profile parameters (including passwords)
|
|
- ``private``: private storage: PEP-like client data, OMEMO crypto keys, PGP trust state
|
|
- ``roster``: contact lists (from the roster cache in the database, kept up to date on
|
|
every connection)
|
|
- ``pep``: client PEP nodes and items (nick, avatar metadata, …)
|
|
- ``gpg``: GPG home per profile (public and secret keys)
|
|
- ``files``: shared files (the blobs of ``~/.sat/files/``)
|
|
- ``db``: full copy of the database (not portable, SQLite only)
|
|
|
|
``db`` is included by default on export: it is the only type covering *all* the data,
|
|
including what is not portable yet (notably message history). Use ``--no-db`` to skip it,
|
|
but **a backup without it is incomplete**. On import, the database must be requested
|
|
explicitly (``--use-db``), as it is destructive.
|
|
|
|
A backup is by default **complete**: it contains all your data, so treat the archive
|
|
accordingly (use ``--encrypt`` when storing or sending it somewhere you do not control).
|
|
|
|
Export
|
|
------
|
|
|
|
Export all data of all profiles::
|
|
|
|
$ li backup export -o ~/backups
|
|
|
|
The archive is written in the given directory (default: the ``backup`` directory of the
|
|
current directory) with the name ``libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz``. The
|
|
export works while the backend is running, and the RAM usage stays low (the operation is
|
|
disk-based, it needs a few hundred MB of temporary disk space).
|
|
|
|
Useful variants::
|
|
|
|
# a single profile
|
|
$ li backup export -p myprofile -o ~/backups
|
|
|
|
# encrypt the archive with GPG (passphrase asked if not given)
|
|
$ li backup export --encrypt -o ~/backups
|
|
|
|
Verify
|
|
------
|
|
|
|
Check that an archive is not corrupted and display its content::
|
|
|
|
$ li backup verify ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz
|
|
|
|
For an encrypted archive, use ``--passphrase`` (or it will be asked).
|
|
|
|
Import
|
|
------
|
|
|
|
Import into an existing installation::
|
|
|
|
$ li backup import ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz
|
|
|
|
The import is a **merge**: data is imported per profile and per type, unrelated rows are
|
|
never touched, and nothing is ever deleted. The roster section itself is not imported yet
|
|
(it needs a server connection): the roster cache in the database is restored with the
|
|
``private`` or ``db`` types, and the server is synced on the next connection.
|
|
|
|
Options:
|
|
|
|
- ``-p PROFILE``: import only the given profile(s);
|
|
- ``-i``/``-e``: include/exclude types (e.g. ``-i params -i pep``);
|
|
- ``--use-db``: full restore from the database backup (see below);
|
|
- ``--passphrase``: for encrypted archives;
|
|
- ``--force``: skip the confirmation of dangerous operations.
|
|
|
|
GPG keyrings are imported as a **union merge**: keys present only in the current keyring
|
|
are kept, nothing is ever deleted. If the current keyring has keys **absent from the
|
|
backup** (e.g. a key generated after the backup was taken), the keyring of this profile is
|
|
skipped (the report lists the concerned fingerprints), relaunch with ``--force`` to merge
|
|
anyway (it still never deletes).
|
|
|
|
Restore on a new machine
|
|
------------------------
|
|
|
|
1. **Full database backup** (the default export): copy the archive to the new machine
|
|
(install Libervia first, with the same or a newer version: the database is migrated
|
|
automatically if needed), **stop the backend**, then restore::
|
|
|
|
$ li backup import --use-db ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz
|
|
|
|
The restore is destructive (a confirmation is asked, ``--force`` skips it): the data
|
|
stored in the database (params, private, roster, pep) comes from the restore itself,
|
|
only the data not stored in it (gpg keys, files) is imported on top of it. The previous
|
|
database file (if any) is kept as
|
|
``<local-dir>/libervia.db.pre-restore-YYYY-MM-DD_HH-MM-SS``.
|
|
|
|
2. **Portable export only** (exported with ``--no-db``): install Libervia first, then run
|
|
a plain import as above. Only the portable types are restored, the not-yet-portable
|
|
ones (e.g. message history) need a backup with the full database.
|
|
|
|
What is not included
|
|
--------------------
|
|
|
|
- local caches, logs, temporary files (regenerable);
|
|
- email gateway maildir, PubSub *service* data (components): planned for a later release;
|
|
- server configuration (``~/libervia.toml``): machine/server specific, not part of the
|
|
user data.
|