Backend server monitoring
The nauthilus_backend module is available in subject sources:
local nauthilus_backend = require("nauthilus_backend")
Subject sources run in the Policy VM. It provides the backend-result functions
apply_backend_result and
remove_from_backend_result, but not the server-selection functions.
A subject source that uses get_backend_servers, select_backend_server, or check_backend_connection is rejected when
the configuration is loaded.
These three functions are documented here because the Lua test framework still
mocks them and scripts from Nauthilus 3 use them. To select the backend server for the nginx Auth-Server and
Auth-Port headers in Nauthilus 4, use a native Go subject source that returns SelectedBackend; see
Result types and
Lua runtimes and capabilities.
nauthilus_backend.get_backend_servers
Retrieves a list of available backend servers.
Not available to subject sources in Nauthilus 4. See the availability note at the top of this page.
Syntax
local backend_servers = nauthilus_backend.get_backend_servers()
Parameters
None
Returns
backend_servers(table): A table of backend server objects, each with the following properties:ip(string): The IP address of the serverport(number): The port number of the serverprotocol(string): The protocol used by the serverhaproxy_v2(boolean): Whether the server supports HAProxy protocol v2tls(boolean): Whether the server uses TLS
Example
local nauthilus_backend = require("nauthilus_backend")
local backend_servers = nauthilus_backend.get_backend_servers()
---@type table
local valid_servers = {}
for _, server in ipairs(backend_servers) do
-- server.ip
-- server.port
-- server.protocol
-- server.haproxy_v2
-- server.tls
-- You may select only HAproxy enabled backends... server.haproxy_v2
table.insert(valid_servers, server)
end
nauthilus_backend.select_backend_server
Selects a backend server for the Nginx endpoint in NAuthilus.
Not available to subject sources in Nauthilus 4. See the availability note at the top of this page.
Syntax
nauthilus_backend.select_backend_server(ip, port)
Parameters
ip(string): The IP address of the backend serverport(number): The port number of the backend server
Returns
None (sets HTTP response headers Auth-Server and Auth-Port)
Example
local nauthilus_backend = require("nauthilus_backend")
-- See nauthilus_backend.get_backend_servers above!
local server = valid_servers[some_number] -- You must define some logic on how to choose a backend server from the list
nauthilus_backend.select_backend_server(server.ip, server.port)
nauthilus_backend.apply_backend_result
Applies backend server information to the result attributes.
Syntax
nauthilus_backend.apply_backend_result(backend_result)
Parameters
backend_result(userdata): A backend result object with attributes
Returns
None
Example
local nauthilus_backend = require("nauthilus_backend")
local b = nauthilus_backend_result:new()
local attributes = {}
attributes["hostip"] = "10.10.10.10" -- A value computed by the subject source
b:attributes(attributes)
nauthilus_backend.apply_backend_result(b)
The result will be available as HTTP-response header X-Nauthilus-Hostip and can easily be parsed in a Dovecot Lua backend.
nauthilus_backend.remove_from_backend_result
Removes attributes from the final result attributes.
Syntax
nauthilus_backend.remove_from_backend_result(attributes)
Parameters
attributes(table): A table of attribute names to remove
Returns
None
Example
local nauthilus_backend = require("nauthilus_backend")
nauthilus_backend.remove_from_backend_result({ "Proxy-Host" })
Removing attributes is always done before adding attributes (from apply_backend_result()-calls)
nauthilus_backend.check_backend_connection
Checks if a connection to a backend server can be established.
Not available to subject sources in Nauthilus 4. See the availability note at the top of this page.
Syntax
local error = nauthilus_backend.check_backend_connection(server_ip, server_port, is_haproxy_v2, uses_tls)
Parameters
server_ip(string): The IP address of the backend serverserver_port(number): The port number of the backend serveris_haproxy_v2(boolean): Whether to use HAProxy protocol v2uses_tls(boolean): Whether to use TLS
Returns
error(string): An error message if the connection fails, nil if successful
Example
local nauthilus_backend = require("nauthilus_backend")
local server_ip = "10.10.10.10"
local server_port = 993
local is_haproxy_v2 = true
local uses_tls = true
local error = nauthilus_backend.check_backend_connection(server_ip, server_port, is_haproxy_v2, uses_tls)
Normally you should not do this, as this will open a connection for each client request!