Skip to content

Commit

Permalink
authentication/lua_based_authentication: Document new lua_path and lu…
Browse files Browse the repository at this point in the history
…a_config settings
  • Loading branch information
vmo69 committed Feb 21, 2024
1 parent 2398b9e commit 42eb4ac
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 10 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -61,7 +92,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
}
}
Expand Down Expand Up @@ -186,7 +220,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
Expand Down Expand Up @@ -220,7 +255,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
Expand Down
10 changes: 8 additions & 2 deletions source/configuration_manual/howto/director_with_lua.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
}
}
Expand Down

0 comments on commit 42eb4ac

Please sign in to comment.