You're reading an old version of this documentation. If you want up-to-date information, please have a look at stable.

Quick Start by Use Case

The goal of this quick-start guide is to give you an impression of how zrepl can accomodate your use case.

Install zrepl

Follow the OS-specific installation instructions and come back here.

Overview Of How zrepl Works

Check out the overview section to get a rough idea of what you are going to configure in the next step, then come back here.

Configuration Examples

zrepl is configured through a YAML configuration file in /etc/zrepl/zrepl.yml. We have prepared example use cases that show-case typical deployments and different functionality of zrepl. We encourage you to read through all of the examples to get an idea of what zrepl has to offer, and how you can mix-and-match configurations for your use case. Keep the full config documentation handy if a config snippet is unclear.

Example Use Cases

Use zrepl configcheck to validate your configuration. No output indicates that everything is fine.

Note

Please open an issue on GitHub if your use case for zrepl is significantly different from those listed above. Or even better, write it up in the same style as above and open a PR!

Apply Configuration Changes

We hope that you have found a configuration that fits your use case. Use zrepl configcheck once again to make sure the config is correct (output indicates that everything is fine). Then restart the zrepl daemon on all systems involved in the replication, likely using service zrepl restart or systemctl restart zrepl.

Warning

Please read up carefully on the pruning rules before applying the config. In particular, note that most example configs apply to all snapshots, not just zrepl-created snapshots. Use the following keep rule on sender and receiver to prevent this:

- type: regex
  negate: true
  regex: "^zrepl_.*" # <- the 'prefix' specified in snapshotting.prefix

Watch it Work

Run zrepl status on the active side of the replication setup to monitor snaphotting, replication and pruning activity. To re-trigger replication (snapshots are separate!), use zrepl signal wakeup JOBNAME. (refer to the example use case document if you are uncertain which job you want to wake up).

You can also use basic UNIX tools to inspect see what’s going on. If you like tmux, here is a handy script that works on FreeBSD:

pkg install gnu-watch tmux
tmux new -s zrepl -d
tmux split-window -t zrepl "tail -f /var/log/messages"
tmux split-window -t zrepl "gnu-watch 'zfs list -t snapshot -o name,creation -s creation'"
tmux split-window -t zrepl "zrepl status"
tmux select-layout -t zrepl tiled
tmux attach -t zrepl

The Linux equivalent might look like this:

# make sure tmux is installed & let's assume you use systemd + journald
tmux new -s zrepl -d
tmux split-window -t zrepl  "journalctl -f -u zrepl.service"
tmux split-window -t zrepl "watch 'zfs list -t snapshot -o name,creation -s creation'"
tmux split-window -t zrepl "zrepl status"
tmux select-layout -t zrepl tiled
tmux attach -t zrepl

What Next?