Warning: This document is for an old version of zrepl. The main version is master.

Installation

Tip

Note: check out the Tutorial if you want a first impression of zrepl.

User Privileges

It is possible to run zrepl as an unprivileged user in combination with ZFS delegation. Also, there is the possibility to run it in a jail on FreeBSD by delegating a dataset to the jail. However, until we get around documenting those setups, you will have to run zrepl as root or experiment yourself :)

Packages

zrepl releases are signed & tagged by the author in the git repository. Your OS vendor may provide binary packages of zrepl through the package manager. The following list may be incomplete, feel free to submit a PR with an update:

OS / Distro Install Command Link
FreeBSD pkg install zrepl https://www.freshports.org/sysutils/zrepl/
Others   Install from source, see below

Compile From Source

Go 1.9 or newer and a configured $GOPATH environment variable and a few build dependencies are required to build zrepl. A tutorial is available over at golang.org. If Go 1.9 is not available on your distro consider build in Docker (see below).

The following shell script checks out the zrepl project into your $GOPATH, installs the build dependencies, installs dependencies using dep ensure and does a make release. Build artifacts are placed into $GOPATH/github.com/zrepl/zrepl/artifacts/.

When doing builds afterwards, it should be sufficient to checkout the new revision, run dep ensure and make release. You may want to switch to a tagged commit (we use semver) but master should generally be considered stable.

Note: it is your job to install the apropriate binary in the zrepl users’s $PATH, e.g. /usr/local/bin/zrepl. Otherwise, the examples in the Tutorial may need to be adjusted.

You are encouraged to understand what happens by auditing the script.

curl 'https://raw.githubusercontent.com/zrepl/zrepl/master/clone_and_build.sh' | sh

You can also build in a Docker container if you want an isolated build environment or don’t have a compatible Go version.

git clone https://github.com/zrepl/zrepl.git
cd zrepl
sudo docker run -it --rm \
    -v "${PWD}:/zrepl" \
    --user "$(id -u):$(id -g)" \
    golang:latest bash -c 'export CLONEPATH=/go/src/github.com/zrepl; mkdir -p "$CLONEPATH" && ln -s /zrepl $CLONEPATH/zrepl && ${CLONEPATH}/zrepl/clone_and_build.sh'
#!/bin/sh
set -e

bold=$(tput bold)
normal=$(tput sgr0)

step() {
    echo "${bold}$1${normal}"
}

if [ -z "$GOPATH" ]; then
    step "Make sure you have your GOPATH configured correctly" 1>&2
    exit 1
fi

step "Checkout sources to \$GOPATH/github.com/zrepl/zrepl"
CHECKOUTPATH="${GOPATH}/src/github.com/zrepl/zrepl"
if [ -e "$CHECKOUTPATH" ]; then
    echo "${CHECKOUTPATH} already exists"
    if [ ! -d "$CHECKOUTPATH" ]; then
        echo "${CHECKOUTPATH} is not a directory, aborting" 1>&2
    else
        cd "$CHECKOUTPATH"
    fi
else
    mkdir -p "$GOPATH/src/github.com/zrepl"
    cd "$GOPATH/src/github.com/zrepl"
    git clone https://github.com/zrepl/zrepl.git
    cd zrepl
fi

step "Install build depdencies using 'go get' to \$GOPATH/bin"
go get -u golang.org/x/tools/cmd/stringer
go get -u github.com/golang/dep/cmd/dep
if ! type stringer || ! type dep; then
    echo "Installed dependencies but can't find them in \$PATH, adjust it to contain \$GOPATH/bin" 1>&2
    exit 1
fi

step "Fetching dependencies using 'dep ensure'"
dep ensure

step "Making release"
make release

step "Release artifacts are available in $(pwd)/artifacts"

Configuration Files

zrepl searches for its main configuration file in the following locations (in that order):

  • /etc/zrepl/zrepl.yml
  • /usr/local/etc/zrepl/zrepl.yml

Alternatively, use CLI flags to specify a config location. Copy a config from the Tutorial or the cmd/sampleconf directory to one of these locations and customize it to your setup.

Runtime Directories

zrepl requires ephemeral runtime directories where control sockets, etc are placed. Refer to the configuration documentation for more information.

When installing from a package, the package maintainer should have taken care of setting them up through the init system. Alternatively, for default settings, the following should to the trick.

mkdir -p /var/run/zrepl/stdinserver
chmod -R 0700 /var/run/zrepl

Running the Daemon

All actual work zrepl does is performed by a daemon process. Logging is configurable via the config file. Please refer to the logging documention.

When installating from a package, the package maintainer should have provided an init script / systemd.service file. You should thus be able to start zrepl daemon using your init system.

Alternatively, or for running zrepl in the foreground, simply execute zrepl daemon. Note that you won’t see any output unless you configure stdout logging outlet.

Attention

Make sure to actually monitor the error level output of zrepl: some configuration errors will not make the daemon exit.

Example: if the daemon cannot create the ssh+stdinserver Transport sockets in the runtime directory, it will emit an error message but not exit because other tasks such as periodic snapshots & pruning are of equal importance.

Restarting

The daemon handles SIGINT and SIGTERM for graceful shutdown. Graceful shutdown means at worst that a job will not be rescheduled for the next interval. The daemon exits as soon as all jobs have reported shut down.