management

management

The management clause configures the built-in management interface that exposes operational and configuration management capabilities over HTTP or HTTPS. This includes the REST API and the optional web UI.

management {
    http {
        listen {
            protocol tcp;
            addr "127.0.0.1:8443";

            tls {
                certificate "MGMT_CERT";
                certificate_key "MGMT_KEY";
                require_client_certificate false;
            }
        }
        clients "MGMT_CLIENTS";
        policy "MANAGEMENT";
        resolve_cache_timeout 1m;
    }
}

Keep the management interface restricted (bind to 127.0.0.1 or a dedicated administrative network segment, and use TLS in production).

Session Timeouts

Use session_timeout, maximum_session_timeout and allow_keep_signed_in inside the http block to control authenticated Radiator UI and Management API sessions.

management {
    http {
        session_timeout 30m;
        maximum_session_timeout 8h;

        # ...
    }
}

Both statements accept duration values greater than zero. If maximum_session_timeout is shorter than session_timeout, the maximum timeout expires the session first.

By default, the session cookie has an expiration time, so the session survives a browser restart until it expires. Management API clients can set the optional remember field of POST /api/v1/auth/login to false to get a session cookie without an expiration time, which the browser discards when it closes. The field defaults to true, and refresh keeps the choice made at login. Radiator UI offers the same choice as a sign-in option.

Set allow_keep_signed_in false; to make every session end when the browser closes. Login and refresh then always return a session cookie without an expiration time and ignore remember. Existing sessions follow the setting from their next refresh. The session timeouts apply in all cases.

Radiator UI refreshes its session only after trusted user input, such as a click, keyboard input, pointer input, scrolling, or editing a field. Continuous activity is combined into a bounded refresh cadence. Merely leaving a tab open does not keep the session active.

When the UI loads, regains focus, becomes visible, or resumes, it checks the server-side expiration without extending it. This means that returning from system sleep exposes an expired session instead of reviving it. Tabs for the same Radiator UI origin share one browser cookie and coordinate successful refreshes, so activity in one tab keeps the shared session active without every tab sending its own refresh request. The maximum timeout still uses the original login time and cannot be reset by activity in any tab.

Radiator UI warns the user five minutes before the session expires. A session limited by maximum_session_timeout cannot be extended, and the user must sign in again.

Listener Configuration

Enabled HTTP management requires an explicit listen block inside http. Omit management or set no http; to disable it. no ui; disables only Radiator UI.

Each listen block controls where the management interface binds. Add an addr statement for each IP address and port. One block can contain addresses from both IP families and addresses with different ports. All addresses in the block use the same protocol, TLS settings, and socket options.

Prefer addr when configuring multiple ports because each line contains one complete endpoint. A block can also combine repeated addr statements with a complete ip and port group. Each addr keeps its own port, while all ip statements use the separate port. For compatibility, one addr statement can be combined with additional ip statements without a separate port. In that form, the additional IP addresses use the port from addr.

The following example serves HTTPS on ports 8443 and 9443 over both IPv4 and IPv6:

management {
    http {
        listen {
            protocol tcp;
            addr "0.0.0.0:8443";
            addr "[::]:8443";
            addr "0.0.0.0:9443";
            addr "[::]:9443";

            tls {
                certificate "MGMT_CERT";
                certificate_key "MGMT_KEY";
                require_client_certificate false;
            }
        }
    }
}

IP Access Control

The clients statement inside the http block references a named HTTP client list defined in the top-level clients clause. When set, only connections from matching IP addresses are accepted. Connections from unlisted addresses are rejected at the TCP level — the connection is dropped without sending an HTTP response.

The clients filter is an application-level control and not a substitute for network-level security. Use a firewall rule to restrict access to the management port as the primary defense, and treat clients as an additional layer.

clients {
    http "MGMT_CLIENTS" {
        client "admin-network" {
            source {
                ip 192.168.1.0/24;
                ip 10.0.0.0/8;
            }
        }

        client "localhost" {
            source {
                ip 127.0.0.1;
                ip ::1;
            }
        }
    }
}

management {
    http {
        clients "MGMT_CLIENTS";
        # ...
    }
}

TLS

Add a tls block to the TCP listener to enable HTTPS. Reference a certificate and key defined in the global certificates block. Without TLS settings, the listener serves plaintext HTTP.

listen {
    protocol tcp;
    addr "127.0.0.1:8443";

    tls {
        certificate "MGMT_CERT";
        certificate_key "MGMT_KEY";
        require_client_certificate false;
    }
}

Browser security headers

Management responses include headers that prevent MIME sniffing and embedding Radiator UI in another page. Radiator UI and the REST API also send a Content Security Policy that permits their required assets.

By default, native HTTPS listeners send Strict-Transport-Security: max-age=31536000; includeSubDomains. Plain HTTP listeners remove this header. Browsers that receive it over HTTPS require HTTPS for the host and its subdomains for 1 year, including services on other ports. Ensure those services support HTTPS before serving Radiator UI from that hostname.

Set strict_transport_security true; in management.http to send this header on every listener. This includes an HTTP listener behind an HTTPS-terminating reverse proxy. The proxy must forward the header on its HTTPS responses because browsers ignore HSTS received over HTTP. You can instead configure HSTS at the proxy.

Set strict_transport_security false; to remove the header on every listener, including native HTTPS listeners. Omitting the setting restores the per-listener default. Removing the header does not clear a policy already cached by a browser; that requires an HTTPS response with Strict-Transport-Security: max-age=0. secure_session_cookie controls cookie attributes separately.

Configuration Backups

Each configuration deployment creates a backup of the active configuration in the backups directory of the configuration directory. Deployments made from Radiator UI or the Management API create backup-* directories, and cluster deployments create cluster-* directories. Use the backups block inside the management block to limit how many of these backups are kept.

management {
    backups {
        keep 10;
        max_age 90d;
    }

    http {
        # ...
    }
}

After each successful deployment, Radiator Server removes every backup that is not one of the newest keep backups and is older than max_age. Deploy and cluster backups are counted together. The backup created by the deployment itself is never removed.

Cleanup uses the backups settings of the configuration that was just deployed, not the running configuration. A change to these settings therefore applies to the deployment that contains it. If the deployed configuration cannot be read, no backups are removed and the server logs a warning.

A zero value disables only its own limit:

• keep 0; removes every backup older than max_age.
• max_age 0s; removes every backup except the newest keep backups, regardless of age.
• keep 0; together with max_age 0s; turns automatic cleanup off and keeps every backup.

Radiator Server removes only directories whose names start with backup- or cluster-. Other files and directories in the backups directory are not removed automatically. A backup that cannot be removed is reported in the server log and does not affect the deployment.

To delete a single backup manually, open Restore from Backup in Radiator UI and select the delete action of the backup. The Management API endpoint DELETE /api/v1/configuration/pending/backups/{name} deletes a backup and requires the write privilege.

Disabling Features

Use no statements inside the management block to disable specific features.

management {
    no ui;
    http {
        listen {
            protocol tcp;
            addr 127.0.0.1:8080;
        }
    }
}

Privilege Model

Each authenticated user is assigned a privilege level that determines which API endpoints and UI operations they can access. Privileges are hierarchical -- a higher level includes all capabilities of lower levels.

If an endpoint requires higher privilege than provided, the request is rejected with a 403 response.

For a detailed breakdown of each privilege level and which API endpoints they control, see Management API Privileges.

Session Authorization Cache

Management sessions can cache the identity and privileges that http_management_authentication loads in its @resolve pipeline. Cookie-authenticated Radiator UI and API requests then reuse the cached result instead of querying the identity backend on every request.

Cache Users Loaded from a Backend

Most installations load management users from one backend query and compare the submitted password with the stored password hash:

management {
    http {
        # ... listen, clients, and TLS settings ...
        policy "MANAGEMENT";

        # Reuse the identity and privileges loaded at login for 1 minute.
        # 1m is the default, so this line is optional.
        resolve_cache_timeout 1m;
    }
}

aaa {
    policy "MANAGEMENT" {
        conditions all {
            aaa.protocol == protocol.MANAGEMENT;
        }

        handler "AUTHENTICATION" {
            @execute {
                # The block form enables the authorization cache.
                http_management_authentication {
                    # @resolve loads the user and sets user.username,
                    # user.password, and user.privilege.
                    # - Login and Basic Auth requests run it every time.
                    # - Cookie requests skip it while the cached result is
                    #   younger than resolve_cache_timeout.
                    # - The first cookie request after the timeout runs it
                    #   again and caches the new result.
                    @resolve {
                        backend {
                            name "MGMT_USERS";
                            query "FIND_USER";
                        }
                    }

                    # @verify checks the credentials of login and Basic Auth
                    # requests. http-basic-auth compares the submitted
                    # password with user.password loaded by @resolve.
                    @verify {
                        http_basic_auth;
                    }
                }
            }
        }
    }
}

A login stores a snapshot of the user. Later cookie requests in the same session use the snapshot until resolve_cache_timeout expires. The timeout is fixed from the time the snapshot was created. Using the session does not extend it.

Verify Credentials Separately

Use a different @verify pipeline when @resolve does not load a password, for example when the password is checked with an LDAP bind:

http_management_authentication {
    # Find the user and map group memberships to user.privilege.
    @resolve {
        backend {
            name "MGMT_LDAP";
            query "FIND_USER";
        }
        # ... map vars.member_of to user.privilege ...
    }

    # Runs after @resolve for login and Basic Auth requests only.
    # Cookie requests, including cache refreshes, never run @verify.
    @verify {
        backend {
            name "MGMT_LDAP";
            query "BIND_USER";
        }
        accept;
    }
}

See Example: LDAP Authentication for the complete configuration.

Disable the Cache

management {
    http {
        listen {
            protocol tcp;
            addr 127.0.0.1:8080;
        }
        policy "MANAGEMENT";

        # Run @resolve for every cookie request and store no snapshot.
        resolve_cache_timeout 0s;
    }
}

Keep an Existing Policy Without Caching

The http_management_authentication; statement form and the legacy credentials block do not use the cache. Setting resolve_cache_timeout alone does not enable caching for them. To enable caching, move the identity lookups and privilege mapping into @resolve.

Treat Provider Outages as Errors

When @resolve rejects the user during a refresh, Radiator removes the session. The user must log in again. HTTP backends return a rejection for every non-success status, so a throttled or unavailable identity provider would also remove sessions. Raise an error instead, so the session stays active:

backends {
    http "IDENTITY" {
        # ... url, authentication, and timeout settings ...
        get "FIND_USER" {
            path "/users/%{aaa.identity | url_escape}";

            # Keep the HTTP status code for the policy.
            mapping head {
                vars.identity_status = status_code;
            }
            mapping json {
                user.username = "$.username";
            }
        }
    }
}

# Inside @resolve:
until end {
    backend { name "IDENTITY"; query "FIND_USER"; }
} when reject {
    if any {
        vars.identity_status == 429;
        vars.identity_status >= 500;
    } then {
        # An error keeps the session and retries after a cooldown.
        error "Identity provider unavailable";
    } else {
        # A rejection removes the session.
        reject;
    }
}

The Entra example includes this classification for its user and group lookups. Connection errors and timeouts already propagate as operational errors unless the policy catches them.

Cache Behavior Reference

• resolve_cache_timeout accepts a duration. The default is 1m. 0s disables the cache.
• The snapshot contains the username, backend, groups, roles, RadiatorDB roles, and HTTP privilege. It does not contain passwords, Basic Auth credentials, tokens, policy conditions, or callback functions.
• HTTP Basic Auth requests always run @resolve and the credential check. They do not read the snapshot.
• When the snapshot expires, one request refreshes it through the configured policy. Concurrent requests for the same session wait for that refresh and use its result. A refresh that does not finish within 30 seconds fails.
• When @resolve rejects the user during a refresh, Radiator removes the session. Revoked privileges, such as removal from a management group, take effect within one resolve_cache_timeout period. A revoked session cookie does not query the backend again.
• When a refresh ends with an operational error, the session remains active, but its requests fail for 5 seconds without another backend lookup. The next request after this cooldown retries. Operational errors include an error action, a backend connection failure, a timeout, and a @resolve pipeline that does not set user.username. Expired privileges are not used during the cooldown.
• When Radiator preserves management sessions across an in-process restart, it discards their snapshots. The first cookie request after the restart refreshes authorization.

Management Authentication Policies

Authentication and authorization are handled by an AAA policy referenced with the policy statement inside the http block, see execution pipelines for details.

1. A management HTTP request arrives (API call or web UI login).
2. The policy's conditions block matches on aaa.protocol == protocol.MANAGEMENT.
3. The handler's @execute block runs the authentication logic:
   • Call http_management_authentication with an @resolve pipeline that loads the user and assigns privileges.
   • Configure an @verify pipeline for password, bind, or multi-factor authentication.
   • Let the action restore fresh session authorization or perform one stale-session refresh.
4. On success, the request proceeds. On failure, a 401 or 403 response is returned.

http_management_authentication Action

The block form owns the identity resolution and credential verification pipelines:

• @resolve is required in the block form. It loads the user and assigns fields such as user.privilege and user.radiatordb_role.
• @verify is required in the block form. It verifies login and Basic Auth credentials after resolution. Use @verify { http_basic_auth; } to compare the submitted password with user.password loaded by @resolve.
• Fresh cookie sessions restore their sanitized snapshot without running either pipeline.
• Stale cookie sessions run only @resolve. One request performs the refresh, and concurrent requests wait for its result.
• A stale session whose @resolve pipeline rejects the user is removed.
• When caching is disabled, every cookie request runs @resolve without creating a snapshot.
• Invalid or expired sessions return reject.
• Single sign-on callbacks run only @resolve, because the identity provider verified the credentials. @resolve must set user.username.

Use the statement form to retain an existing policy without authorization caching:

backend {
    name "MGMT_USERS";
    query "FIND_USER";
}
http_management_authentication;

The statement form runs Basic Auth against the user loaded by the surrounding policy. For cookie requests, it validates the session and confirms that the loaded username matches the session username. It does not accept single sign-on callbacks.

This action does not create session cookies. The /auth/login, /auth/refresh, and /auth/logout endpoints manage session lifecycle.

Example: JSON File Authentication

Authenticate management users against a JSON file. The backend query maps user.username, user.password, and user.privilege from the file.

backends {
    jsonfile "MGMT_USERS" {
        filename "users.json";

        query "FIND_USER" {
            mapping {
                user.username = doc | jsonpath("$.users[?(@.username == $aaa.identity)].username");
                user.password = doc | jsonpath("$.users[?(@.username == $aaa.identity)].password");
                user.privilege = doc | jsonpath("$.users[?(@.username == $aaa.identity)].privilege");
            }
        }
    }
}

aaa {
    policy "MANAGEMENT" {
        conditions all {
            aaa.protocol == protocol.MANAGEMENT;
        }

        handler "AUTHENTICATION" {
            @execute {
                http_management_authentication {
                    @resolve {
                        backend {
                            name "MGMT_USERS";
                            query "FIND_USER";
                        }
                    }

                    @verify {
                        http_basic_auth;
                    }
                }
            }
        }
    }
}

The JSON file must contain user objects with username, password, and privilege fields. See Password Hashing for supported hash formats.

Example: LDAP Authentication

Authenticate management users against an LDAP directory. A single search retrieves the user's DN and all group memberships in one round-trip. Privilege is then assigned in the policy based on whether the admin group DN appears in vars.member_of.

backends {
    ldap "MGMT_LDAP" {
        server "ldap-server" {
            url "ldaps://ldap.example.com/";
            timeout 3s;
            authentication {
                dn "cn=radiator-svc,ou=service-accounts,dc=example,dc=org";
                password "servicepassword";
            }
        }

        # Find the user and collect all group memberships in a single search.
        search "FIND_USER" {
            base "ou=people,dc=example,dc=org";
            scope sub;
            filter "(&(uid=%{aaa.identity})(objectClass=inetOrgPerson))";

            mapping {
                vars.dn = entry::dn;
                user.username = uid;
                vars.member_of += memberOf;
            }
        }

        bind "BIND_USER" {
            dn vars.dn;
            password http.authorization.password;
        }
    }
}

aaa {
    policy "MANAGEMENT" {
        conditions all {
            aaa.protocol == protocol.MANAGEMENT;
        }

        handler "AUTHENTICATION" {
            @execute {
                http_management_authentication {
                    @resolve {
                        backend {
                            name "MGMT_LDAP";
                            query "FIND_USER";
                        }

                        if any {
                            vars.member_of == "CN=radiator-admins,OU=groups,DC=example,DC=org";
                        } then {
                            user.privilege = "all";
                        } else {
                            user.privilege = "monitor";
                        }
                    }

                    @verify {
                        # Cookie refreshes never run this LDAP bind.
                        backend {
                            name "MGMT_LDAP";
                            query "BIND_USER";
                        }
                        accept;
                    }
                }
            }
        }
    }
}

vars.member_of += memberOf accumulates all values of the multi-valued memberOf attribute into a list. The == condition checks whether any item in the list matches the admin group DN exactly, including the full OU path. The comparison is case-sensitive, so the DN in the condition must match the case returned by the LDAP server.

Active Directory note: AD does not populate the uid attribute by default. When connecting to an AD domain controller, replace both occurrences of uid with sAMAccountName:

filter "(&(sAMAccountName=%{aaa.identity})(objectClass=user))";
mapping {
    vars.dn = entry::dn;
    user.username = sAMAccountName;
    vars.member_of += memberOf;
}

Without user.username = sAMAccountName, the mapping leaves user.username empty. Login (POST /api/v1/auth/login) will return an error indicating that user.username is empty — check the server log for the exact attribute name to use.

Audit Logging

Add audit logging to management authentication using the @final_execute block.

handler "AUTHENTICATION" {
    @execute {
        # ... authentication logic ...
    }

    @final_execute {
        log "MANAGEMENT" {
            json {
                "User-Name" aaa.identity;
                "Reason" aaa.reason;
                "Result" "%{aaa.result}";
                "Method" http.method;
                "Path" http.path;
                "Code" http.status;
                "Ip" http.client.ip;
            }
        }
    }
}

OpenID Connect Providers

oidc blocks enable an experimental feature. Its behavior and configuration may change in a later release. About experimental features.

oidc blocks inside the http block let users sign in to Radiator UI with an OpenID Connect identity provider. Radiator UI Single Sign-On with OpenID Connect describes identity provider TLS, the choice of the identity claim, the sign-in flow, mapping claims to privileges, and sign-out.

management {
    http {
        # ... listen, clients, and TLS settings ...
        policy "MANAGEMENT";

        oidc "entra" {
            title "Microsoft";
            issuer "https://login.microsoftonline.com/TENANT_ID/v2.0";
            client_id "APPLICATION_CLIENT_ID";
            client_secret env.ENTRA_CLIENT_SECRET;
            redirect_url "https://radiator.example.com:8443/api/v1/auth/oidc/entra/callback";
            identity_claim "oid";
        }
    }
}

The provider name, such as entra, may contain ASCII letters, digits, _, and -. Single sign-on requires a management policy that uses the block form of http_management_authentication.

issuer must use https://. Radiator accepts http:// only for localhost, 127.0.0.1, and [::1]. Radiator compares issuer exactly with the issuer in the provider metadata, so configure it exactly as the provider reports it, including any trailing /.

Microsoft Entra ID is supported as a single-tenant application with a tenant-specific issuer, such as https://login.microsoftonline.com/TENANT_ID/v2.0. The multi-tenant common and organizations issuers are not supported.

Legacy: Credentials Block

The credentials block is supported for backward compatibility. For production deployments, use policy-based authentication instead.

When policy is not set, the management interface falls back to the credentials block. It supports static user definitions and backend references directly inside the http block.

management {
    http {
        listen {
            protocol tcp;
            addr "127.0.0.1:8443";

            tls {
                certificate "MGMT_CERT";
                certificate_key "MGMT_KEY";
                require_client_certificate false;
            }
        }

        credentials {
            user "admin" {
                password "{argon2}$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG";
                privilege all;
            }
            user "monitor" {
                password "{argon2}$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG";
                privilege monitor;
            }
        }
    }
}

Each user block requires password and privilege (any privilege level from the Privilege Model above; use all for administrators). Passwords can be plain text or hashed with {argon2} or {crypt-sha256} prefixes — argon2 is recommended. See Password Hashing for how to generate hashes.

Optional Static Users

Set omit_if_password_empty true on a static user to omit that user when its password expression resolves to an empty string while loading the configuration. This is useful for optional accounts whose passwords come from environment variables:

credentials {
    user "monitor" {
        omit_if_password_empty true;
        password env.MONITOR_PASSWORD | default("");
        privilege monitor;
    }
}

When MONITOR_PASSWORD is unset or empty, the monitor user is not added and cannot log in. When it contains a value, the user is added and that value is used as its password; use a supported prefixed password hash for deployments. The statement defaults to false; without it, an empty password retains the existing static-user behaviour. It does not omit a user whose password is non-empty, and it does not enforce password strength or a minimum password length.

Authentication Order

For each incoming request, the credentials block authenticates as follows:

1. Session cookie — if a valid session cookie is present and matches the username, the request is accepted immediately without checking credentials.
2. Static users — the username from the Authorization: Basic header is looked up in the user blocks. If a matching entry is found, the password is verified. If it matches, the request is accepted with that user's privilege.
3. Backends — only reached if no matching static user was found. Backends are queried in alphabetical order by name. The first backend that returns a user with a non-empty username and a password is used to verify the submitted password. Remaining backends are not queried once a match is found.

If none of the above steps succeed, the request is rejected with a 401 response.

Session Cookie Security

Session cookies use the HttpOnly and SameSite=Strict attributes. Browsers do not send these cookies when a request originates from another site. Cookies sent by a TLS management listener also use the Secure attribute. Each listener uses its own transport policy when the same management service has both HTTP and HTTPS listeners.

Set secure_session_cookie true; in the management.http block when a reverse proxy terminates HTTPS and connects to Radiator over HTTP. This setting forces login, refresh, and logout cookies to use Secure on every listener. The default is false, so HTTP-only deployments continue to work.

management {
    http {
        listen {
            protocol tcp;
            addr "127.0.0.1:8080";
        }

        # The reverse proxy exposes this listener through HTTPS.
        secure_session_cookie true;
        policy "MANAGEMENT";
    }
}

Related

• Management API Privileges - Detailed breakdown of privilege levels and which endpoints they control
• Health check /live and /ready - Health check endpoints served by the management interface
• Radiator UI Single Sign-On with OpenID Connect - Sign-in flow, identity provider TLS, and mapping claims to privileges
• Configuration Import and Export - How to upload certificates and configuration packages
• assistant - AI assistant in Radiator UI (experimental)
• ui - Web UI customization (sidebar navigation)
• certificates - TLS certificate configuration