extern/zrepl
1
0
Fork 0
mirror of https://github.com/zrepl/zrepl.git synced 2025-02-03 12:09:19 +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 .. include:: ../global.rst.inc
.. _conf-logging:
.. _logging:
Logging Logging
======= =======

2
docs/configuration/transports.rst
View File

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

18
docs/implementation.rst
View File

@ -7,7 +7,7 @@ Implementation Overview
Incomplete / under construction 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 Testability & Performance
------------------------- -------------------------
@ -23,12 +23,14 @@ software engineering.
RPC protocol 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. * The snapshot streams need to be compatible.
* Communication is still unidirectional. Thus, you will most likely * Communication is still unidirectional. Thus, you will most likely
* either not take advantage of features such as *compressed send & recv* * 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. * Advanced logic in shell scripts is ugly to read, poorly testable and a pain to maintain.
zrepl takes a different approach: zrepl takes a different approach:
@ -37,12 +39,12 @@ zrepl takes a different approach:
* Establish an encrypted, authenticated, bidirectional communication channel... * Establish an encrypted, authenticated, bidirectional communication channel...
* ... with zrepl running at both ends of it. * ... 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. * No blank root shell access is given to the other side.
* Instead, an *authenticated* peer can *request* filesystem lists, snapshot streams, etc. * 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. * 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 Protocol Implementation
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
@ -50,11 +52,11 @@ Protocol Implementation
zrepl implements its own RPC protocol. 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. 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 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. 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>`.
:: ::