doc (howto backup, cli/backup): document the new backup mechanism:
Add a "How-To" for backup, and document the new `backup` commands fix 480
This commit is contained in:
Goffi
parent
4ce7c807be
commit
45024d913e
3 changed files with 196 additions and 0 deletions
116
doc/howto_backup.rst
Normal file
116
doc/howto_backup.rst
Normal file
|
|
@ -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 <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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
79
doc/libervia-cli/backup.rst
Normal file
79
doc/libervia-cli/backup.rst
Normal file
|
|
@ -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 <howto_backup>` 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
|
||||
Loading…
Reference in a new issue