Installation

Prerequisites

There are anywhere from one to three machines with the following distinct characteristics:

  1. Running abgleich.

  2. The location of the source zpool.

  3. The location of the target zpool.

On the machine that is running abgleich itself, python3 (CPython 3.6 or later) and ssh is required. abgleich can be operated both from the source and the target side but also from a third, otherwise unrelated machine. In addition, both the source and the target side must provide a shell as well as ssh next to ZFS drivers and at least one zpool. source and target can be on the same machine if two local zpools are supposed to be synchronized.

Note

If everything happens on a single machine, no ssh is required.

On Debian/Ubuntu-based systems, all potentially required prerequisites other than ZFS can be installed as follows:

sudo apt install python3 python3-venv openssh

Warning

It is strongly recommended to operate abgleich with user privileges only.

It is recommended to created dedicated user accounts on all involved machines and to grant them specific rights only. If operations must be triggered on remote machines, public key authentication must be configured for ssh for the relevant user accounts on all involved machines. For additional details, see man pages of ssh-keygen and ssh itself.

In addition, the following ZFS operations must be allowed for the user on the following sides:

command

source

target

zfs create

x

zfs destroy

x

zfs diff

x

zfs mount

x

x

zfs receive

x

zfs send

x

zfs snapshot

x

Relevant ZFS operations on the source side can be allowed for user username as follows:

sudo zfs allow username destroy,diff,mount,send,snapshot sourcepool

Relevant ZFS operations on the target side can be allowed for user username as follows:

sudo zfs allow username create,mount,receive targetpool

For more details, see man page for ZFS allow.

Getting abgleich

abgleich can be installed and updated via Python’s package manager pip.

Warning

Installation into a Python virtual environment is strongly recommended. The creation of virtual environments as well as the installation Python packages into them with pip is typically performed with user privileges only.

A basic installation workflow may look as follows:

python3 -m venv env  # create a virtual environment named "env" within CWD
source env/bin/activate  # activate virtual environment named "env" within CWD
pip install -U setuptools pip  # update Python's pip and setuptools
pip install abgleich  # install abgleich itself

An installation also including a GUI can be triggered by running:

pip install abgleich[gui]

You can check your installation by running:

abgleich --help

Note

If abgleich was installed into a virtual environment, this virtual environment must be explicitly activated for each particular shell session prior to using any of abgleich’s commands.

Upgrading abgleich

With the relevant virtual environment activated, run:

pip install -U abgleich

Note

If you are relying on abgleich, please notice that it uses semantic versioning. Breaking changes are indicated by increasing the second version number, the minor version. Going for example from 0.0.x to 0.1.y or going from 0.1.x to 0.2.y therefore indicates a breaking change. For as long as abgleich has development status “alpha”, please expect more breaking changes to come.