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
 
@@ -90,12 +90,37 @@ set ``i18n.lang`` to the desired languag
 

	
 

	
 
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
 
    problems, ideally contributing patches that solve these problems.
 

	
 
Users and admins can upload SSH public keys (e.g. ``.ssh/id_rsa.pub``) through
0 comments (0 inline, 0 general)