From 03ba2bb7c868db36eb3bdbbe0fe3f7035112750a Mon Sep 17 00:00:00 2001 From: Christian Schwarz Date: Wed, 27 Dec 2017 18:34:02 +0100 Subject: [PATCH] docs: move config files + runtime dir doc to new configuration/preface --- docs/configuration.rst | 1 + docs/configuration/logging.rst | 2 ++ docs/configuration/misc.rst | 3 +- docs/configuration/preface.rst | 33 ++++++++++++++++++++ docs/installation.rst | 55 ++++------------------------------ docs/tutorial.rst | 2 +- docs/usage.rst | 32 ++++++++++++++++++++ 7 files changed, 75 insertions(+), 53 deletions(-) create mode 100644 docs/configuration/preface.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index 917c22d..4e84184 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -7,6 +7,7 @@ Configuration .. toctree:: + configuration/preface configuration/jobs configuration/transports configuration/map_filter_syntax diff --git a/docs/configuration/logging.rst b/docs/configuration/logging.rst index da2b46e..d47dfbd 100644 --- a/docs/configuration/logging.rst +++ b/docs/configuration/logging.rst @@ -31,6 +31,8 @@ Check out :sampleconf:`random/logging.yml` for an example on how to configure mu The **first outlet is special**: if an error writing to any outlet occurs, the first outlet receives the error and can print it. Thus, the first outlet must be the one that always works and does not block, e.g. ``stdout``, which is the default. +.. _logging-default-config: + Default Configuration --------------------- diff --git a/docs/configuration/misc.rst b/docs/configuration/misc.rst index 6d892ad..0aaf92b 100644 --- a/docs/configuration/misc.rst +++ b/docs/configuration/misc.rst @@ -13,10 +13,9 @@ zrepl daemon creates various UNIX sockets to allow communicating with it: There is no further authentication on these sockets. Therefore we have to make sure they can only be created and accessed by ``zrepl daemon``. - In fact, ``zrepl daemon`` will not bind a socket to a path in a directory that is world-accessible. -The directories can be configured in the main configuration file: +The directories can be configured in the main configuration file, the defaults are provided below: :: diff --git a/docs/configuration/preface.rst b/docs/configuration/preface.rst new file mode 100644 index 0000000..ed578d5 --- /dev/null +++ b/docs/configuration/preface.rst @@ -0,0 +1,33 @@ + +.. _configuration_preface: + +======= +Preface +======= + +----------------------- +Configuration File Path +----------------------- + +zrepl searches for its main configuration file in the following locations (in that order): + +* If set, the location specified via the global ``--config`` flag +* ``/etc/zrepl/zrepl.yml`` +* ``/usr/local/etc/zrepl/zrepl.yml`` + +The examples in the :ref:`tutorial` or the ``cmd/sampleconf`` directory should provide a good starting point. + +------------------- +Runtime Directories +------------------- + +zrepl requires runtime directories for various UNIX sockets --- they are documented in the :ref:`config file`. +Your package maintainer / init script should take care of creating them. +Alternatively, for default settings, the following should to the trick. + +:: + + mkdir -p /var/run/zrepl/stdinserver + chmod -R 0700 /var/run/zrepl + + diff --git a/docs/installation.rst b/docs/installation.rst index 9f5787e..32c5d34 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -78,56 +78,11 @@ Build results are located in the ``artifacts/`` directory. .. _mainconfigfile: -Configuration Files -------------------- +What next? +---------- -zrepl searches for its main configuration file in the following locations (in that order): +Read the :ref:`configuration chapter` and optionally create the :ref:`runtime directories `. +Afterwards, continue with the :ref:`usage chapter`. -* ``/etc/zrepl/zrepl.yml`` -* ``/usr/local/etc/zrepl/zrepl.yml`` +**Reminder**: If you want a quick introduction, please read the :ref:`tutorial`. -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. - -Runtime Directories -------------------- - -zrepl requires ephemeral runtime directories where control sockets, etc are placed. -Refer to the :ref:`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 :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. - -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 :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: - -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 e6921f3..e41f815 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -153,7 +153,7 @@ Apply Configuration Changes --------------------------- We need to restart the zrepl daemon on **both** ``app-srv`` and ``backup-srv``. -This is :ref:`OS-specific `. +This is :ref:`OS-specific `. Watch it Work ------------- diff --git a/docs/usage.rst b/docs/usage.rst index dfc8648..b65d37e 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,3 +1,5 @@ +.. _usage: + ***** Usage ***** @@ -26,3 +28,33 @@ CLI Overview * - ``zrepl stdinserver`` - see :ref:`transport-ssh+stdinserver` +.. _usage-zrepl-daemon: + +============ +zrepl 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. + +Alternatively, or for running zrepl in the foreground, simply execute ``zrepl daemon``. +Note that you won't see much output with the :ref:`default logging configuration`: + +.. 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 :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. + +.. _usage-zrepl-daemon-restarting: + +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.