From 283cc2aa8661588f336291f78fd53113790bca9d Mon Sep 17 00:00:00 2001
From: Max Kellermann <max.kellermann@ionos.com>
Date: Mon, 23 Oct 2023 08:34:59 +0200
Subject: [PATCH] doc: a few words about the translation server

---
 doc/index.rst | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/doc/index.rst b/doc/index.rst
index bc42b40..4b223eb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -17,9 +17,9 @@ Lukko loads the configuration file
 
 The following top-level settings are recognized:
 
-- ``translation_server``: consult this translation server to configure
-  child processes; must start with :file:`/` (absolute path) or
-  :file:`@` (abstract socket).
+- ``translation_server``: consult this :ref:`translation server <ts>`
+  to configure child processes; must start with :file:`/` (absolute
+  path) or :file:`@` (abstract socket).
 
 
 Listener
@@ -68,3 +68,27 @@ Known attributes:
 
 - ``zeroconf_interface``: publish the Zeroconf service only on the
   given interface.
+
+
+.. _ts:
+
+Translation Server
+==================
+
+Lukko can delegate certain decisions (user database, how to execute
+commands) to a different process running on the same computer, called
+a "translation server".  This translation server may, for example,
+consult a database to look up user accounts instead of reading
+:file:`/etc/passwd` and can make complex decicions based on that data.
+Only the translation server has access to all of Lukko's process
+spawner features, which includes a light-weight container engine.
+
+Information about the translation protocol can be found here:
+
+- `documentation
+  <https://beng-proxy.readthedocs.io/en/latest/translation.html#login-translation>`__
+
+- `definitions for C++ <https://github.com/CM4all/libcommon/blob/master/src/translation/Protocol.hxx>`__
+
+- `asynchronous framework for C++
+  <https://github.com/CM4all/libcommon/tree/master/src/translation/server>`__