diff --git a/docs/configuration/logging.rst b/docs/configuration/logging.rst index 7591241..f9d75c9 100644 --- a/docs/configuration/logging.rst +++ b/docs/configuration/logging.rst @@ -98,7 +98,7 @@ Formats ``encoding/json.Marshal()``, which is particularly useful for processing in log aggregation or when processing state dumps. -Outlets are ... well ... outlets for log entries into the world. +.. _logging-outlet-stdout: ``stdout`` Outlet ----------------- diff --git a/docs/installation.rst b/docs/installation.rst index bd0a0e1..42176d9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,7 +5,7 @@ Installation .. TIP:: - Note: check out the [tutorial]({{< relref "tutorial/_index.md" >}}) if you want a first impression of zrepl. + Note: check out the :ref:`tutorial` if you want a first impression of zrepl. User Privileges --------------- @@ -15,13 +15,32 @@ It is possible to run zrepl as an unprivileged user in combination with 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 :) -Installation ------------- +Packages +-------- -zrepl is currently not packaged on any operating system. Signed & versioned releases are planned but not available yet. +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: -Check out the sources yourself, fetch dependencies using dep, compile and install to the zrepl user's `$PATH`.
-**Note**: if the zrepl binary is not in `$PATH`, you will have to adjust the examples in the :ref:`tutorial`. +.. list-table:: + :header-rows: 1 + + * - OS / Distro + - Install Command + - Link + * - FreeBSD + - ``pkg install zrepl`` + - ``_ + * - Others + - + - Install from source, see below + +Compile From Source +~~~~~~~~~~~~~~~~~~~ + +Check out the sources yourself, fetch dependencies using ``dep``, compile and install to the zrepl user's ``$PATH``. +You may want to switch to a tagged commit (we use `semver `_) although a checkout of ``master`` branch should generally work. +**Note**: if the zrepl binary is not in ``$PATH``, the examples in the :ref:`tutorial` may need to be adjusted. :: @@ -43,17 +62,20 @@ 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` +* ``/etc/zrepl/zrepl.yml`` +* ``/usr/local/etc/zrepl/zrepl.yml`` Alternatively, use CLI flags to specify a config location. +Copy a config from the :ref:`tutorial` or the ``cmd/sampleconf`` directory to one of these locations and customize it to your setup. -Copy a config from the :ref:`tutorial` or the `cmd/sampleconf` directory to one of these locations and customize it to your setup. +Runtime Directories +------------------- -## Runtime Directories +zrepl requires ephemeral runtime directories where control sockets, etc are placed. +Refer to the :ref:`configuration documentation ` for more information. -Check the the :ref:`configuration documentation ` for more information. -For default settings, the following should to the trick. +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. :: @@ -65,20 +87,20 @@ 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 :ref:`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. - zrepl daemon - -There are no *rc(8)* or *systemd.service(5)* service definitions yet. Note the *daemon(8)* utility on FreeBSD. +Alternatively, or for running zrepl in the foreground, simply execute ``zrepl daemon``. +Note that you won't see any output unless you configure :ref:`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 [stdinserver]({{< relref "configuration/transports.md#stdinserver" >}}) 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. + 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 :ref:`transport-ssh+stdinserver` 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. .. _install-restarting: @@ -86,7 +108,5 @@ 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. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 5b8356f..5b32679 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -160,7 +160,7 @@ Watch it Work A common setup is to ``watch`` the log output and ``zfs list`` of snapshots on both machines. -If you like tmux, here is a handy script that works on FreeBSD::: +If you like tmux, here is a handy script that works on FreeBSD: :: pkg install gnu-watch tmux tmux new-window @@ -168,7 +168,7 @@ If you like tmux, here is a handy script that works on FreeBSD::: tmux split-window "gnu-watch 'zfs list -t snapshot -o name,creation -s creation | grep zrepl_pull_backup_'" tmux select-layout tiled -The Linux equivalent might look like this:: +The Linux equivalent might look like this: :: # make sure tmux is installed & let's assume you use systemd + journald tmux new-window