Changeset - ee4fc2d20d09
[Not reviewed]
default
0 1 0
Mads Kiilerich - 6 years ago 2019-08-12 20:53:56
mads@kiilerich.com
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)
1 file changed with 25 insertions and 0 deletions:
0 comments (0 inline, 0 general)
docs/setup.rst
Show inline comments
 
@@ -93,6 +93,31 @@ Using Kallithea with SSH
 
------------------------
 

	
 
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
0 comments (0 inline, 0 general)