From 35d6a85197cdd8c541b1ce31c99cd5f2e912e5af 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              | 43 +++++++++++++++++--
 .../howto/director_with_lua.rst               | 10 ++++-
 2 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/source/configuration_manual/authentication/lua_based_authentication.rst b/source/configuration_manual/authentication/lua_based_authentication.rst
index e86440c964..318b7a0ae7 100644
--- a/source/configuration_manual/authentication/lua_based_authentication.rst
+++ b/source/configuration_manual/authentication/lua_based_authentication.rst
@@ -29,6 +29,35 @@ 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
 ^^^^^^^^^^^^^^
 
@@ -38,7 +67,8 @@ When passdb or userdb is initialized, there will be a lookup for initialization
 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.
+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.
 
@@ -61,7 +91,10 @@ Example
 
   passdb db1 {
     driver = lua
-    args = file=/etc/dovecot/auth.lua password={PLAIN}test
+    lua_path = /etc/dovecot/auth.lua
+    lua_config {
+      password = {PLAIN}test
+    }
   }
 
 
@@ -186,7 +219,8 @@ To configure passdb in dovecot, use
 
   passdb db1 {
     driver = 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
@@ -220,7 +254,8 @@ To configure userdb in dovecot, use
 
   userdb db1 {
     driver = 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 94e87578fd..319fb572cc 100644
--- a/source/configuration_manual/howto/director_with_lua.rst
+++ b/source/configuration_manual/howto/director_with_lua.rst
@@ -79,7 +79,10 @@ First, and the most simple, is drop-in replacement for director with no authenti
 
   passdb db1 {
     driver = lua
-    args = file=/etc/dovecot/director.lua nopassword
+    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.
@@ -97,7 +100,10 @@ If you wish to do authentication, you can do
   passdb db2 {
     skip = unauthenticated
     driver = lua
-    args = file=/etc/dovecot/director.lua noauthenticate
+    lua_path = /etc/dovecot/director.lua
+    default_fields {
+      noauthenticate = yes
+    }
   }