kallithea Changeset - ee4fc2d20d09

Changeset - ee4fc2d20d09

Parent rev.

Child rev.

[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:

docs/setup.rst

0 comments (0 inline, 0 general)

docs/setup.rst

➞

Show inline comments

@@ @@ -72,48 +72,73 @@ You are now ready to use Kallithea. To r @@
   settings, as well as edit more advanced options on users and
   repositories.
 Internationalization (i18n support)
 -----------------------------------
 The Kallithea web interface is automatically displayed in the user's preferred
 language, as indicated by the browser. Thus, different users may see the
 application in different languages. If the requested language is not available
 (because the translation file for that language does not yet exist or is
 incomplete), the language specified in setting ``i18n.lang`` in the Kallithea
 configuration file is used as fallback. If no fallback language is explicitly
 specified, English is used.
 If you want to disable automatic language detection and instead configure a
 fixed language regardless of user preference, set ``i18n.enabled = false`` and
 set ``i18n.lang`` to the desired language (or leave empty for English).
 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
 the web interface. The server's ``.ssh/authorized_keys`` file is automatically
 maintained with an entry for each SSH key. Each entry will tell ``sshd`` to run
 ``kallithea-cli`` with the ``ssh-serve`` sub-command and the right Kallithea user ID
 when encountering the corresponding SSH key.
 To enable SSH repository access, Kallithea must be configured with the path to
 the ``.ssh/authorized_keys`` file for the Kallithea user, and the path to the
 ``kallithea-cli`` command. Put something like this in the ``.ini`` file::
     ssh_enabled = true
     ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
     kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
 The SSH service must be running, and the Kallithea user account must be active
 (not necessarily with password access, but public key access must be enabled),
 all file permissions must be set as sshd wants it, and ``authorized_keys`` must
 be writeable by the Kallithea user.

0 comments (0 inline, 0 general)