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.

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.

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

The following two command therefore have identical meaning:

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