diff --git a/docs/changelog.rst b/docs/changelog.rst index d93dc55..ff30e74 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,6 +1,7 @@ .. |break_config| replace:: **[BREAK]** .. |break| replace:: **[BREAK]** .. |bugfix| replace:: [BUG] +.. |docs| replace:: [DOCS] .. |feature| replace:: [FEATURE] Changelog @@ -40,6 +41,7 @@ Developers should consult the git commit log or GitHub issue tracker. * |bugfix| :issue:`8` and :issue:`56`: ``ssh+stdinserver`` transport properly reaps SSH child processes * |bugfix| :commit:`cef63ac`: ``human`` format now prints non-string values correctly * |bugfix| :issue:`26`: slow TCP outlets no longer block the daemon +* |docs| :issue:`64`: tutorial: document ``known_host`` file entry 0.0.2 ----- diff --git a/docs/configuration/transports.rst b/docs/configuration/transports.rst index 5484666..e1c512a 100644 --- a/docs/configuration/transports.rst +++ b/docs/configuration/transports.rst @@ -104,8 +104,11 @@ The connecting zrepl daemon #. 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. +The ``known_hosts`` file used by the ssh command must contain an entry for the serving host, e.g., ``app-srv.example.com`` in the example above. + .. NOTE:: The environment variables of the underlying SSH process are cleared. ``$SSH_AUTH_SOCK`` will not be available. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 443c022..dc58374 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -94,6 +94,13 @@ It uses the private key specified at ``connect.identity_file`` which we still ne Note that most use cases do not benefit from separate keypairs per remote endpoint. Thus, it is sufficient to create one keypair and use it for all ``connect`` directives on one host. +zrepl uses ssh's default ``known_hosts`` file, which must contain a host identification entry for ``app-srv.example.com``. +If that entry does not already exist, we need to generate it. +Run the following command, compare the host fingerprints, and confirm with yes if they match. +You will not be able to get a shell with the identity file we just generated, which is fine. :: + + ssh -i /etc/zrepl/ssh/identity root@app-srv.example.com + Learn more about :ref:`transport-ssh+stdinserver` transport and the :ref:`pull job ` format. .. _tutorial-configure-app-srv: