diff --git a/doc/howto_backup.rst b/doc/howto_backup.rst new file mode 100644 index 00000000..22bc4392 --- /dev/null +++ b/doc/howto_backup.rst @@ -0,0 +1,116 @@ +.. _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 `). 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 + ``/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. diff --git a/doc/index.rst b/doc/index.rst index cb07b970..e9d53f40 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -28,6 +28,7 @@ You can follow this documentation to learn more on it, or join our official XMPP overview.rst configuration.rst encryption.rst + howto_backup.rst tor.rst components.rst developer.rst diff --git a/doc/libervia-cli/backup.rst b/doc/libervia-cli/backup.rst new file mode 100644 index 00000000..50cb5945 --- /dev/null +++ b/doc/libervia-cli/backup.rst @@ -0,0 +1,79 @@ +.. _libervia-cli_backup: + +=================================== +backup: export/import Libervia data +=================================== + +``backup`` commands allow to export and import Libervia data to/from a portable archive +(``.tar.xz``, optionally GPG encrypted). The format is based on `XEP-0227`_, extended with +Libervia-specific sections, so a backup remains readable by future Libervia versions. + +A backup is made of data *types*, selected with ``-i/--include`` and ``-e/--exclude`` +(repeatable): ``params``, ``private``, ``roster``, ``pep``, ``gpg``, ``files`` and ``db`` +(full copy of the database, included by default on export). A backup is complete by +default (passwords, OMEMO keys, GPG secret keys...), so the archive should be kept +private: it is written with mode 0600, and ``--encrypt`` can be used for untrusted +storage. + +See :ref:`the backup & restore guide ` for the data types details, the +safety notes and the restore procedures. + +.. _libervia-cli_backup_export: + +export +====== + +Export Libervia data to a backup archive. The destination directory is given with +``-o/--output-dir`` (default: ``backup`` in the current directory). The full database +backup (``db`` type) is included by default, use ``--no-db`` to skip it (in this case the +backup is incomplete, e.g. message history is not covered). + +examples +-------- + +Export all data of all profiles, in ``~/backups``:: + + $ li backup export -o ~/backups + +Export a single profile, with an encrypted archive (passphrase asked if not given):: + + $ li backup export -p myprofile --encrypt -o ~/backups + +.. _libervia-cli_backup_import: + +import +====== + +Import Libervia data from a backup archive (optionally GPG encrypted, ``--passphrase`` is +asked if needed). The import is a merge: data is imported per profile and per type, and +nothing is ever deleted. ``--use-db`` restores the full database backup instead (the +database is replaced, see the guide). A confirmation is asked for dangerous operations +(``--force`` skips it). + +examples +-------- + +Import an archive:: + + $ li backup import ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz + +Restore the database (the backend must be stopped, see the guide):: + + $ li backup import --use-db ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz + +.. _libervia-cli_backup_verify: + +verify +====== + +Check a backup archive integrity (checksums, well-formedness) and display its content. For +an encrypted archive, ``--passphrase`` is needed (asked if not given). + +example +------- + +Verify an archive:: + + $ li backup verify ~/backups/libervia-backup-YYYY-MM-DD_HH-MM-SS.tar.xz + +.. _XEP-0227: https://xmpp.org/extensions/xep-0227.html