Installation¶
Getting abgleich¶
abgleich is written in Rust and can be statically linked against musl, allowing self-contained portable binaries, trivial deployment and maximum compatibility. The primary target platforms are Linux and FreeBSD on x86_64. Both x86 (32 bit) and ARM support are theoretically trivial but currently untested territory - pull requests welcome. abgleich does not need to run on any remotely accessed target system, only the box where it actually gets invoked.
Pre-Built Binaries¶
Pre-built binaries for Linux and FreeBSD can be found on the releases page.
You can use the following command on Linux or FreeBSD to download the latest release. Simply replace DEST with the directory where you would like to put abgleich:
curl --proto '=https' --tlsv1.2 -sSf https://abgleich.pleiszenburg.de/install.sh | bash -s -- --to DEST
For example, to install abgleich to ~/bin:
# create ~/bin
mkdir -p ~/bin
# download and extract abgleich to ~/bin/abgleich
curl --proto '=https' --tlsv1.2 -sSf https://abgleich.pleiszenburg.de/install.sh | bash -s -- --to ~/bin
# add `~/bin` to the paths that your shell searches for executables
# this line should be added to your shells initialization file,
# e.g. `~/.bashrc` or `~/.zshrc`
export PATH="$PATH:$HOME/bin"
You can check your installation by running:
abgleich --help
Optional: bash¶
All operations based on pipes require bash present on hosts operating those pipes. It’s usually installed by default on many Linux distributions.
Optional: pv¶
Rate-limiting transfers while synchronizing is achieved with pv on the sending hosts.
sudo apt install pv
Optional: nc¶
Fast, insecure transfers can be performed via nc (netcat).
sudo apt install netcat
Optional: xz¶
If compression beyond what ZFS offers is activated, both the sending and receiving hosts during transfers while synchronizing require xz to be installed.
sudo apt install pxz-utilsv
Optional: SSH¶
ssh may be required if there is the intention of accessing zpools on remote machines.
On Debian/Ubuntu-based systems, the client can be installed as follows:
sudo apt install openssh-client
Similarly, the server can be installed as follows:
sudo apt install openssh-server
For details on its configuration, see help.ubuntu.com and OpenSSH wiki book as well as the ssh man page and the ssh-keygen man page, among other places.
abgleich generally assumes password-less logins with public keys. abgleich can change the user on the target system before performing critical operations - therefore root-logins via SSH are not necessary. Systems accessed via an SSH server are ideally running some form of sh or bash.
User Accounts¶
Warning
It is strongly recommended to operate abgleich with user privileges only.
abgleich relies on the assumption that the zfs command is in PATH for regular users and that operations which do not change data such as zfs list and zfs get can successfully be performed by the same regular users. For “invasive” operations such as synchronizing two zpools, it is recommended to created dedicated user accounts on all involved machines and to grant them specific rights only:
command |
source |
target |
|---|---|---|
|
x |
|
|
x |
|
|
x |
|
|
x |
x |
|
x |
|
|
x |
|
|
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.
Warning
zfs diff comes with a caveat: zfs allow username diff is not enough. The user performing zfs diff on a dataset needs to have execute-permission (x) set on the filesystem at the root of the dataset or else the diff will fail. This can be worked around with group-level permissions. Alternatively, the use of zfs diff can be prohibited by setting the abgleich:diff property to off.
Warning
On Linux, zfs allow has a known fundamental limitation with regard to operations requiring mount our umount. From the man page: “Delegations are supported under Linux with the exception of mount, unmount, mountpoint, canmount, rename, and share. These permissions cannot be delegated because the Linux mount(8) command restricts modifications of the global namespace to the root user.” A deeper discussion can be found on Github. In this case, the only real option is to perform said operations as root.
Through location strings, abgleich can be directed to change user with sudo or sudo -u respectively before performing certain operations. This change is assumed to work without password. A matching entry in /etc/sudoers may look as follows:
regular_user ALL=(privileged_user) NOPASSWD: /usr/sbin/zfs
privileged_user may also be root if mount/umount on Linux is required.
Upgrading abgleich¶
Simply re-install the (latest) pre-build binary as described above.
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.