mirror of
https://github.com/zrepl/zrepl.git
synced 2024-11-21 16:03:32 +01:00
556fac3002
closes https://github.com/zrepl/zrepl/pull/552 fixes https://github.com/zrepl/zrepl/issues/551 Signed-off-by: Andrew Gunnerson <chillermillerlong@hotmail.com> Co-authored-by: Christian Schwarz <me@cschwarz.com>
102 lines
3.7 KiB
ReStructuredText
102 lines
3.7 KiB
ReStructuredText
.. include:: global.rst.inc
|
|
|
|
.. _quickstart-toc:
|
|
|
|
***********************
|
|
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 :ref:`OS-specific installation instructions <installation_toc>` and come back here.
|
|
|
|
Overview Of How zrepl Works
|
|
============================
|
|
|
|
Check out the :ref:`overview section <job-overview>` 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 :ref:`full config documentation <configuration_toc>` handy if a config snippet is unclear.
|
|
|
|
**Example Use Cases**
|
|
|
|
.. toctree::
|
|
:titlesonly:
|
|
|
|
quickstart/continuous_server_backup
|
|
quickstart/backup_to_external_disk
|
|
quickstart/fan_out_replication
|
|
|
|
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!
|
|
|
|
.. _quickstart-apply-config:
|
|
|
|
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 :ref:`read up carefully <prune>` 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?
|
|
==========
|
|
|
|
* Read more about :ref:`configuration format, options & job types <configuration_toc>`
|
|
* Configure :ref:`logging <logging>` \& :ref:`monitoring <monitoring>`.
|
|
|