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.

.. note:: The ``authorized_keys`` file will be rewritten from scratch on

    each update. If it already exists with other data, Kallithea will not

    overwrite the existing ``authorized_keys``, and the server process will

    instead throw an exception. The system administrator thus cannot ssh

    directly to the Kallithea user but must use su/sudo from another account.

    If ``/home/kallithea/.ssh/`` (the directory of the path specified in the

    ``ssh_authorized_keys`` setting of the ``.ini`` file) does not exist as a

    directory, Kallithea will attempt to create it. If that path exists but is

    *not* a directory, or is not readable-writable-executable by the server

    process, the server process will raise an exception each time it attempts to

    write the ``authorized_keys`` file.

.. warning:: The handling of SSH access is steered directly by the command

    specified in the ``authorized_keys`` file. There is no interaction with the

    web UI.  Once SSH access is correctly configured and enabled, it will work

    regardless of whether the Kallithea web process is actually running. Hence,

    if you want to perform repository or server maintenance and want to fully

    disable all access to the repositories, disable SSH access by setting

    ``ssh_enabled = false`` in the correct ``.ini`` file (i.e. the ``.ini`` file

    specified in the ``authorized_keys`` file.)

The ``authorized_keys`` file can be updated manually with ``kallithea-cli

ssh-update-authorized-keys -c my.ini``. This command is not needed in normal

operation but is for example useful after changing SSH-related settings in the