# HG changeset patch
# User Mads Kiilerich <mads@kiilerich.com>
# Date 1565636036 -7200
# Node ID ee4fc2d20d09c0aa03a6304dea71e927c90567ad
# Parent  395f21a36a6b06492569c6aa9007dd1e3328ed42
docs: add high-level description of SSH repository access

In addition to the existing technical documentation about SSH repository
access, add some high-level info about what this means.

(some editing by Thomas De Schampheleire)

diff -r 395f21a36a6b -r ee4fc2d20d09 docs/setup.rst
--- a/docs/setup.rst	Sun Aug 04 01:49:22 2019 +0200
+++ b/docs/setup.rst	Mon Aug 12 20:53:56 2019 +0200
@@ -93,6 +93,31 @@
 ------------------------
 
 Kallithea supports repository access via SSH key based authentication.
+This means:
+
+- repository URLs like ``ssh://kallithea@example.com/name/of/repository``
+
+- all network traffic for both read and write happens over the SSH protocol on
+  port 22, without using HTTP/HTTPS nor the Kallithea WSGI application
+
+- encryption and authentication protocols are managed by the system's ``sshd``
+  process, with all users using the same Kallithea system user (e.g.
+  ``kallithea``) when connecting to the SSH server, but with users' public keys
+  in the Kallithea system user's `.ssh/authorized_keys` file granting each user
+  sandboxed access to the repositories.
+
+- users and admins can manage SSH public keys in the web UI
+
+- in their SSH client configuration, users can configure how the client should
+  control access to their SSH key - without passphrase, with passphrase, and
+  optionally with passphrase caching in the local shell session (``ssh-agent``).
+  This is standard SSH functionality, not something Kallithea provides or
+  interferes with.
+
+- network communication between client and server happens in a bidirectional
+  stateful stream, and will in some cases be faster than HTTP/HTTPS with several
+  stateless round-trips.
+
 
 .. note:: At this moment, repository access via SSH has been tested on Unix
     only. Windows users that care about SSH are invited to test it and report