extern/zrepl
1
0
Fork 0
mirror of https://github.com/zrepl/zrepl.git synced 2025-01-23 22:58:54 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: adjust implementation article to rst

Browse Source
This commit is contained in:
Christian Schwarz 2017-11-10 13:41:17 +01:00
parent 4f37dccb76
commit 707a189144
4 changed files with 15 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/configuration/logging.rst
View File

@ -1,5 +1,6 @@
.. include:: ../global.rst.inc
.. _conf-logging:
.. _logging:
Logging
=======

2
docs/configuration/transports.rst
View File

@ -1,5 +1,7 @@
.. highlight:: bash
.. _transport:
Transports
==========

18
docs/implementation.rst
View File

@ -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 <transport>` 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 <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.
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 <logging>`, allowing administators to understand what the software is actually doing.

2
docs/installation.rst
View File

@ -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 <conf-logging>`.
Logging is configurable via the config file. Please refer to the :ref:`logging documention <logging>`.
::