Script Context API

The context object provides access to AAA request data through sub-contexts and methods. See scripts for script structure, parameters, and examples.

Root Context

The root context object provides these fields and methods:

Fields

Nested Contexts

Nested contexts are created automatically during tunneled EAP methods like EAP-TTLS, PEAP, and EAP-TEAP. When inner authentication runs inside the TLS tunnel, a child context is created with:

• parent — the outer tunnel's context
• root — the original request context (the outermost context)

For non-tunneled requests, both root and parent are nil.

The vars sub-context is shared between parent and child contexts, allowing data to be passed between outer and inner authentication phases.

Sub-contexts

Methods

count(name)

Increments the statistics counter identified by name. Counters are created dynamically on first increment; no pre-declaration in the statistics block is required.

The name argument controls which namespace the counter is placed in:

• No :: separator — counter is placed under the current pipeline context namespace (e.g. handler::<policy>::<handler>::<name>).
• :: separator — the parts before the last :: form the namespace and the part after is the counter name. Use the custom:: prefix to create counters in the shared custom namespace.

local context, previous = ...

-- Counter in the current handler namespace
context:count("total_requests")

-- Counter in the explicit custom namespace
if context.aaa.result == "accept" then
    context:count("custom::successful_logins")
else
    context:count("custom::failed_logins")
end

return previous

Counter values are readable via the management API at /api/v1/statistics/counter/<namespace>/<name> (e.g. /api/v1/statistics/counter/custom/successful_logins).

Use the statistics block to configure history retention (samples and interval) for counters; this is optional and separate from counter creation.

log(name, message)

Writes message to the AAA logger identified by name. The logger must be declared in the server configuration (log-aaa block). If no logger with that name exists, the script raises a runtime error.

The name parameter is the logger name as configured in the log-aaa block, not a severity level. AAA loggers write structured records that include the request identifier and timestamp automatically.

local context, previous = ...

-- Write to an AAA logger named "AUTHLOG"
context:log("AUTHLOG", "Processing " .. tostring(context.aaa.identity))

-- Conditional logging
local framed_ip = context.radius.request:attr("framed-ip-address")
if framed_ip then
    context:log("AUTHLOG", "Framed-IP: " .. framed_ip)
end

return previous

Configuring the logger in radconf:

log-aaa "AUTHLOG" {
    filename "log/auth.log";
    format json;
}

RADIUS Packet Attribute Methods

RADIUS packet attribute access is through the context.radius.request and context.radius.reply packet objects (see radius sub-context). The key methods for reading attributes are:

Attribute Name Casing

Attribute lookups use lowercase names regardless of how the dictionary file or packet spells them. Always pass lowercase names to all attribute methods.

-- Correct: lowercase
local ip  = context.radius.request:attr("framed-ip-address")
local nas = context.radius.request:attr("nas-identifier")
local mac = context.radius.request:attr("calling-station-id")

-- Wrong: mixed-case silently returns nil
-- local ip = context.radius.request:attr("Framed-IP-Address")  -- nil

This applies only to Lua attribute methods. Radconf condition expressions (radius.request.attr.Framed-IP-Address) and template expansions (%{radius.request.attr.Framed-IP-Address}) are handled by a separate code path and are not affected.

attr(name, tag?)

Returns the first value of the named attribute, or nil if the attribute is not present. The optional tag parameter (integer 1-31) filters tagged attributes; omit it (or pass nil) for untagged lookups.

local username = context.radius.request:attr("user-name")
local ip       = context.radius.request:attr("framed-ip-address")

if not ip then
    -- attribute absent; treat as unknown origin
end

attrs()

Returns a Lua table where each key is a lowercase attribute name (string) and each value is an array (1-based) of all occurrences of that attribute. Even attributes that appear only once are wrapped in a one-element array so callers can iterate uniformly.

Attribute values are mapped to Lua types as follows:

local all = context.radius.request:attrs()

-- Single-valued attribute
local username = all["user-name"] and all["user-name"][1]

-- Multi-valued attribute
local filters = all["filter-id"] or {}
for _, f in ipairs(filters) do
    context:log("AUTHLOG", "Filter: " .. tostring(f))
end

-- Dump every attribute for debugging
for name, values in pairs(all) do
    for _, v in ipairs(values) do
        context:log("AUTHLOG", name .. " = " .. tostring(v))
    end
end