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:
parent
4ce7c807be
commit
45024d913e
1 changed files with 196 additions and 0 deletions
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