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.
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.
zrepl is configured through a YAML configuration file in
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
zrepl configcheck to validate your configuration.
No output indicates that everything is fine.
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.
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.
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¶
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
- Read more about configuration format, options & job types
- Configure logging & monitoring.