From 707a189144aaed2d53c62065c7ae032669ed9418 Mon Sep 17 00:00:00 2001 From: Christian Schwarz Date: Fri, 10 Nov 2017 13:41:17 +0100 Subject: [PATCH] docs: adjust implementation article to rst --- docs/configuration/logging.rst | 3 ++- docs/configuration/transports.rst | 2 ++ docs/implementation.rst | 18 ++++++++++-------- docs/installation.rst | 2 +- 4 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/configuration/logging.rst b/docs/configuration/logging.rst index 2be7d1d..7591241 100644 --- a/docs/configuration/logging.rst +++ b/docs/configuration/logging.rst @@ -1,5 +1,6 @@ .. include:: ../global.rst.inc -.. _conf-logging: + +.. _logging: Logging ======= diff --git a/docs/configuration/transports.rst b/docs/configuration/transports.rst index 36ceab8..98a7643 100644 --- a/docs/configuration/transports.rst +++ b/docs/configuration/transports.rst @@ -1,5 +1,7 @@ .. highlight:: bash +.. _transport: + Transports ========== diff --git a/docs/implementation.rst b/docs/implementation.rst index 6a83e96..bc9b1f9 100644 --- a/docs/implementation.rst +++ b/docs/implementation.rst @@ -7,7 +7,7 @@ Implementation Overview Incomplete / under construction -The following design aspects may convince you that `zrepl` is superior to a hacked-together shell script solution. +The following design aspects may convince you that ``zrepl`` is superior to a hacked-together shell script solution. Testability & Performance ------------------------- @@ -23,12 +23,14 @@ software engineering. RPC protocol ------------ -While it is tempting to just issue a few `ssh remote 'zfs send ...' | zfs recv`, this has a number of drawbacks: +While it is tempting to just issue a few ``ssh remote 'zfs send ...' | zfs recv``, this has a number of drawbacks: * The snapshot streams need to be compatible. * Communication is still unidirectional. Thus, you will most likely + * either not take advantage of features such as *compressed send & recv* - * or issue additional `ssh` commands in advance to figure out what features are supported on the other side. + * or issue additional ``ssh`` commands in advance to figure out what features are supported on the other side. + * Advanced logic in shell scripts is ugly to read, poorly testable and a pain to maintain. zrepl takes a different approach: @@ -37,12 +39,12 @@ zrepl takes a different approach: * Establish an encrypted, authenticated, bidirectional communication channel... * ... with zrepl running at both ends of it. - This has several obvious benefits: +This has several obvious benefits: * No blank root shell access is given to the other side. * Instead, an *authenticated* peer can *request* filesystem lists, snapshot streams, etc. * Requests are then checked against job-specific ACLs, limiting a client to the filesystems it is actually allowed to replicate. -* The {{< zrepl-transport "transport mechanism" >}} is decoupled from the remaining logic, keeping it extensible. +* The :ref:`transport mechanism ` is decoupled from the remaining logic, keeping it extensible. Protocol Implementation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,11 +52,11 @@ Protocol Implementation zrepl implements its own RPC protocol. This is mostly due to the fact that existing solutions do not provide efficient means to transport large amounts of data. -Package [`github.com/zrepl/zrepl/rpc`](https://github.com/zrepl/zrepl/tree/master/rpc) builds a special-case handling around returning an `io.Reader` as part of a unary RPC call. +Package `github.com/zrepl/zrepl/rpc `_ builds a special-case handling around returning an ``io.Reader`` as part of a unary RPC call. -Measurements show only a single memory-to-memory copy of a snapshot stream is made using `github.com/zrepl/zrepl/rpc`, and there is still potential for further optimizations. +Measurements show only a single memory-to-memory copy of a snapshot stream is made using ``github.com/zrepl/zrepl/rpc``, and there is still potential for further optimizations. Logging & Transparency ---------------------- -zrepl comes with [rich, structured and configurable logging]({{< relref "configuration/logging.md" >}}), allowing administators to understand what the software is actually doing. +zrepl comes with :ref:`rich, structured and configurable logging `, allowing administators to understand what the software is actually doing. diff --git a/docs/installation.rst b/docs/installation.rst index 64270e9..bd0a0e1 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -66,7 +66,7 @@ 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 `. +Logging is configurable via the config file. Please refer to the :ref:`logging documention `. ::