diff --git a/docs/configuration/transports.rst b/docs/configuration/transports.rst index a3fca9a..36ceab8 100644 --- a/docs/configuration/transports.rst +++ b/docs/configuration/transports.rst @@ -3,24 +3,24 @@ Transports ========== -A transport provides an authenticated [`io.ReadWriteCloser`](https://golang.org/pkg/io/#ReadWriteCloser) to the RPC layer. -(An `io.ReadWriteCloser` is essentially a bidirectional reliable communication channel.) +A transport provides an authenticated `io.ReadWriteCloser `_ to the RPC layer. +(An ``io.ReadWriteCloser`` is essentially a bidirectional reliable communication channel.) -Currently, only the `ssh+stdinserver` transport is supported. +Currently, only the ``ssh+stdinserver`` transport is supported. .. _transport-ssh+stdinserver: -`ssh+stdinserver` ------------------ +``ssh+stdinserver`` Transport +----------------------------- -The way the `ssh+stdinserver` transport works is inspired by [git shell](https://git-scm.com/docs/git-shell) and [Borg Backup](https://borgbackup.readthedocs.io/en/stable/deployment.html). -It is implemented in the Go package `github.com/zrepl/zrepl/sshbytestream`. -The config excerpts are taken from the [tutorial]({{< relref "tutorial/_index.md" >}}) which you should complete before reading further. +The way the ``ssh+stdinserver`` transport works is inspired by `git shell `_ and `Borg Backup `_. +It is implemented in the Go package ``github.com/zrepl/zrepl/sshbytestream``. +The config excerpts are taken from the :ref:`tutorial` which you should complete before reading further. .. _transport-ssh+stdinserver-serve: -`serve` -~~~~~~~ +Serve Mode +~~~~~~~~~~ :: @@ -32,18 +32,18 @@ The config excerpts are taken from the [tutorial]({{< relref "tutorial/_index.md client_identity: backup-srv.example.com ... -The serving job opens a UNIX socket named after `client_identity` in the runtime directory, e.g. `/var/run/zrepl/stdinserver/backup-srv.example.com`. +The serving job opens a UNIX socket named after ``client_identity`` in the runtime directory, e.g. ``/var/run/zrepl/stdinserver/backup-srv.example.com``. -On the same machine, the :code:`zrepl stdinserver $client_identity` command connects to that socket. -For example, `zrepl stdinserver backup-srv.example.com` connects to the UNIX socket `/var/run/zrepl/stdinserver/backup-srv.example.com`. +On the same machine, the ``zrepl stdinserver $client_identity`` command connects to that socket. +For example, ``zrepl stdinserver backup-srv.example.com`` connects to the UNIX socket ``/var/run/zrepl/stdinserver/backup-srv.example.com``. It then passes its stdin and stdout file descriptors to the zrepl daemon via *cmsg(3)*. -zrepl daemon in turn combines them into an `io.ReadWriteCloser`: -a `Write()` turns into a write to stdout, a `Read()` turns into a read from stdin. +zrepl daemon in turn combines them into an ``io.ReadWriteCloser``: +a ``Write()`` turns into a write to stdout, a ``Read()`` turns into a read from stdin. -Interactive use of the `stdinserver` subcommand does not make much sense. +Interactive use of the ``stdinserver`` subcommand does not make much sense. However, we can force its execution when a user with a particular SSH pubkey connects via SSH. -This can be achieved with an entry in the `authorized_keys` file of the serving zrepl daemon. +This can be achieved with an entry in the ``authorized_keys`` file of the serving zrepl daemon. :: @@ -52,24 +52,25 @@ This can be achieved with an entry in the `authorized_keys` file of the serving # for older OpenSSH versions command="zrepl stdinserver CLIENT_IDENTITY",no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,no-user-rc CLIENT_SSH_KEY -* CLIENT_IDENTITY is substituted with `backup-srv.example.com` in our example -* CLIENT_SSH_KEY is substituted with the public part of the SSH keypair specified in the `connect` directive on the connecting host. +* CLIENT_IDENTITY is substituted with ``backup-srv.example.com`` in our example +* CLIENT_SSH_KEY is substituted with the public part of the SSH keypair specified in the ``connect`` directive on the connecting host. .. NOTE:: - You may need to adjust the `PermitRootLogin` option in `/etc/ssh/sshd_config` to `forced-commands-only` or higher for this to work. + + You may need to adjust the ``PermitRootLogin`` option in ``/etc/ssh/sshd_config`` to ``forced-commands-only`` or higher for this to work. Refer to sshd_config(5) for details. -To recap, this is of how client authentication works with the `ssh+stdinserver` transport: +To recap, this is of how client authentication works with the ``ssh+stdinserver`` transport: -* Connections to the `client_identity` UNIX socket are blindly trusted by zrepl daemon. +* Connections to the ``client_identity`` UNIX socket are blindly trusted by zrepl daemon. * Thus, the runtime directory must be private to the zrepl user (checked by zrepl daemon) -* The admin of the host with the serving zrepl daemon controls the `authorized_keys` file. -* Thus, the administrator controls the mapping `PUBKEY -> CLIENT_IDENTITY`. +* The admin of the host with the serving zrepl daemon controls the ``authorized_keys`` file. +* Thus, the administrator controls the mapping ``PUBKEY -> CLIENT_IDENTITY``. .. _transport-ssh+stdinserver-connect: -`connect` -~~~~~~~~~ +Connect Mode +~~~~~~~~~~~~ :: @@ -87,23 +88,23 @@ To recap, this is of how client authentication works with the `ssh+stdinserver` The connecting zrepl daemon -1. Creates a pipe -1. Forks -1. In the forked process +#. Creates a pipe +#. Forks +#. In the forked process - 1. Replaces forked stdin and stdout with the corresponding pipe ends - 1. Executes the `ssh` binary found in `$PATH`. + #. Replaces forked stdin and stdout with the corresponding pipe ends + #. Executes the ``ssh`` binary found in ``$PATH``. - 1. The identity file (`-i`) is set to `$identity_file`. - 1. The remote user, host and port correspond to those configured. - 1. Further options can be specified using the `options` field, which appends each entry in the list to the command line using `-o $entry`. + #. The identity file (``-i``) is set to ``$identity_file``. + #. The remote user, host and port correspond to those configured. + #. Further options can be specified using the ``options`` field, which appends each entry in the list to the command line using ``-o $entry``. -1. Wraps the pipe ends in an `io.ReadWriteCloser` and uses it for RPC. +1. Wraps the pipe ends in an ``io.ReadWriteCloser`` and uses it for RPC. -As discussed in the section above, the connecting zrepl daemon expects that `zrepl stdinserver $client_identity` is executed automatically via an `authorized_keys` file entry. +As discussed in the section above, the connecting zrepl daemon expects that ``zrepl stdinserver $client_identity`` is executed automatically via an ``authorized_keys`` file entry. .. NOTE:: - The environment variables of the underlying SSH process are cleared. `$SSH_AUTH_SOCK` will not be available. + The environment variables of the underlying SSH process are cleared. ``$SSH_AUTH_SOCK`` will not be available. It is suggested to create a separate, unencrypted SSH key solely for that purpose.