.. _configuration:


Configuration
=============

Dataset Properties
------------------

The behaviour of ``abgleich snap`` and ``abgleich free`` can be controlled through custom properties on ZFS datasets. ZFS's inheritance rules apply. All properties can be overridden for individual operations using environment variables. The most important ones are:

- ``abgleich:diff``: boolean (``on`` / ``off``), defaults to ``on`` if not set. Check diff of dataset for determining if a snapshot is required. If a diff is asked for but this property is set to ``off``, a differences is automatically assumed to exist. Overridden via ``ABGLEICH_DIFF``.
- ``abgleich:format``: string, defaults to ``abgleich_%Y-%m-%dT%H:%M:%S:%f_backup``. See `documentation of chrono`_ for options. Overridden via ``ABGLEICH_FORMAT``.
- ``abgleich:overlap``: integer, defaults to ``2``. Number of overlapping snapshots on source and target. ``0`` is not valid. ``-1`` causes the source to keep all past snapshots, i.e. the overlap is not limited and old snapshots are not removed. Overridden via ``ABGLEICH_OVERLAP``.
- ``abgleich:snap``: string, defaults to ``changed``. Possible values are ``always``, ``changed`` and ``never``. Overridden via ``ABGLEICH_SNAP``.
- ``abgleich:sync``: boolean (``on`` / ``off``), defaults to ``on`` if not set. Dataset is included in ``sync`` and related cleanup operations, i.e. ``free``. Overridden via ``ABGLEICH_SYNC``.
- ``abgleich:threshold``: integer, defaults to ``12582912`` bytes (12 MByte). Only if changes are smaller than this number of bytes, a dataset will be diffed to look for changes. Large diffs tend to be expensive/slow. Overridden via ``ABGLEICH_THRESHOLD``.

.. _documentation of chrono: https://docs.rs/chrono/latest/chrono/format/strftime/index.html

Snapshot Logic
--------------

Whether or not snapshots are generated by ``abgleich snap`` is based on the following sequence of checks on each individual dataset:

1) The value of ``abgleich:snap`` is checked. If set to ``always``, a snapshot is taken. If set to ``never``, no snapshot is taken. If set to ``changed``, further checks are performed to determine if the dataset has been changed since the last snapshot.
2) The number of snapshots on the dataset is checked. If there is none, a snapshot is taken.
3) The ``written`` property of the dataset is checked. If it equals ``0``, no snapshot is taken.
4) The type of dataset is checked. If it is a volume, a snapshot is taken.
5) The value of ``abgleich:threshold`` is checked. If ``written`` exceeds this value, a snapshot is taken.
6) The value of ``abgleich:diff`` is checked. If it is set to ``off``, a snapshot is taken.
7) It is checked whether the dataset is mounted. If it is unmounted, a snapshot is taken.
8) ``zfs diff`` is performed. If it generates output, a snapshot is taken. If there is no output, no snapshot is taken.

Snapshots are named by filling out the format string provided in ``abgleich:format``.

Synchronization Logic
---------------------

Datasets are considered for synchronization if ``abgleich:sync`` is ``on``. At least one common snapshot most be found on source and target as an anchor, else the operation fails. If the target contains any snapshots following the last common snapshot, the operation also fails. If checks succeed, all snapshots after the last common snapshot on the source and transferred to the target.

Location Aliases
----------------

For convenience, entire locations can be given aliases, which must be written into a YAML configuration file.

.. code:: yaml

    apools:
      abc: remotehost:root%some/data/set
      xyz: otherhost:specialuser%meaningful/data/set

The following two command therefore have identical meaning:

.. code:: bash

    abgleich ls abc
    abgleich ls remotehost:root%some/data/set

The YAML configuration file is searched in the following locations in the following sequence, with the first file found being loaded:

- path specified via ``ABGLEICH_CONFIG`` environment variable if set
- ``{CWD}/abgleich.yaml``
- ``{HOME}/.abgleich.yaml``
- ``/etc/abgleich.yaml``