authentication/lua_based_authentication: Document new lua_path and lu…

…a_config settings

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,12 +87,19 @@ 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 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 +224,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 +259,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

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
+    }
   }