.. _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.