From 3444681dc35987a80409751c5972e5613767926d Mon Sep 17 00:00:00 2001
From: Markus Valentin <markus.valentin@open-xchange.com>
Date: Wed, 21 Feb 2024 14:14:49 +0100
Subject: [PATCH] authentication/lua_based_authentication: Document new
 lua_path and lua_config settings

---
 .../lua_based_authentication.rst              | 56 ++++++++++++++++---
 .../howto/director_with_lua.rst               | 11 +++-
 2 files changed, 57 insertions(+), 10 deletions(-)

diff --git a/source/configuration_manual/authentication/lua_based_authentication.rst b/source/configuration_manual/authentication/lua_based_authentication.rst
index 0bcf63304..a7d3e9300 100644
--- a/source/configuration_manual/authentication/lua_based_authentication.rst
+++ b/source/configuration_manual/authentication/lua_based_authentication.rst
@@ -29,16 +29,47 @@ For details about Dovecot Lua, see :ref:`lua`.
 When used in authentication, additional module dovecot.auth is added, which
 contains constants for passdb and userdb.
 
+Lua specific passdb/userdb settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. dovecot_core:setting:: userdb_lua_path
+   :values: @string
+
+   Filesystem path to the lua script to be used for this userdb.
+
+
+.. dovecot_core:setting:: passdb_lua_path
+   :values: @string
+
+   Filesystem path to the lua script to be used for this userdb.
+
+
+.. dovecot_core:setting:: userdb_lua_config
+   :values: @strlist
+
+   List of strings which are key value pairs. These are passed as arguments to
+   auth_userdb_init().
+
+
+.. dovecot_core:setting:: passdb_lua_config
+   :values: @strlist
+
+   List of strings which are key value pairs. These are passed as arguments to
+   auth_userdb_init().
+
+
 Initialization
 ^^^^^^^^^^^^^^
 
 .. dovecotadded:: 2.4.0,3.0.0
 
-When passdb or userdb is initialized, there will be a lookup for initialization function.
-This is different from :func:`script_init`` which is called for all Lua scripts. For
-passdb, the function is :func:`auth_passdb_init` and for userdb, it is called
-:func:`auth_userdb_init`. The function is called with a table containing all parameters
-provided in the passdb/userdb args, except file name.
+When passdb or userdb is initialized, there will be a lookup for initialization functions.
+These are different from :func:`script_init`` which is called for all Lua scripts. For
+passdb, the functions are :func:`auth_passdb_init` and :func:`auth_passdb_get_cache_key`
+and for userdb, they are called :func:`auth_userdb_init` and
+:func:`auth_userdb_get_cache_key`. The functions are called with a table
+containing all parameters provided in the passdb/userdb
+:dovecot_core:ref:`userdb_lua_config`/:dovecot_core:ref:`passdb_lua_config`.
 
 This can be used to pass out initialization parameters from Dovecot.
 
@@ -56,11 +87,18 @@ Example
     return dovecot.auth.PASSDB_RESULT_OK, { ["password"]=password }
   end
 
+  function auth_passdb_get_cache_key()
+    return "lua-passdb-1-%u%d"
+  end
+
 
 .. code:: none
 
   passdb lua {
-    args = file=/etc/dovecot/auth.lua password={PLAIN}test
+    lua_path = /etc/dovecot/auth.lua
+    lua_config {
+      password = {PLAIN}test
+    }
   }
 
 
@@ -184,7 +222,8 @@ To configure passdb in dovecot, use
 .. code-block:: none
 
   passdb lua {
-    args = file=/path/to/lua blocking=yes # default is yes
+    lua_path =/path/to/lua
+    use_worker = yes # default is yes
   }
 
 By default, dovecot runs Lua scripts in auth-worker processes. If you do not
@@ -217,7 +256,8 @@ To configure userdb in dovecot, use
 .. code-block:: none
 
   userdb lua {
-    args = file=/path/to/lua blocking=yes # default is yes
+    lua_path = /path/to/lua
+    use_worker = yes # default is yes
   }
 
 Examples
diff --git a/source/configuration_manual/howto/director_with_lua.rst b/source/configuration_manual/howto/director_with_lua.rst
index 1da196d9e..6019c78c9 100644
--- a/source/configuration_manual/howto/director_with_lua.rst
+++ b/source/configuration_manual/howto/director_with_lua.rst
@@ -78,7 +78,11 @@ First, and the most simple, is drop-in replacement for director with no authenti
 .. code::
 
   passdb lua {
-    args = file=/etc/dovecot/director.lua nopassword
+    driver = lua
+    lua_path = /etc/dovecot/director.lua
+    default_fields {
+      nopassword = yes
+    }
     # or password=masterpass
     # you can include other keys here too, they will be
     # included in the response.
@@ -94,7 +98,10 @@ If you wish to do authentication, you can do
 
   passdb lua {
     skip = unauthenticated
-    args = file=/etc/dovecot/director.lua noauthenticate
+    lua_path = /etc/dovecot/director.lua
+    default_fields {
+      noauthenticate = yes
+    }
   }