Freeradius

@shrug/freeradiusv2026.07.12.1· 1d agoMODELS

01README

Manage a FreeRADIUS server wherever it runs (local | ssh | nsenter): write raddb config files atomically with backups, gate every restart on radiusd -C, and roll back on a failed check. Typed methods for clients, modules, VLAN post-auth policy, cert perms, and removing swamp-managed blocks.

02Models1

@shrug/freeradiusv2026.07.12.1freeradius.ts

Global Arguments

Argument	Type	Required	Description
host?	string	no	SSH host — required for transport=ssh\|nsenter
machine?	string	no	systemd-nspawn machine name — required for transport=nsenter
user	string	yes	SSH username (ssh\|nsenter)
port	number	yes	SSH port (ssh\|nsenter)
raddbDir	string	yes	FreeRADIUS config root (raddb) in the target
unit	string	yes	systemd unit (radiusd on EL, freeradius on Debian)
radiusdBin	string	yes	config-check binary in the target (radiusd \| freeradius)
backupDir	string	yes	Where apply copies previous file versions (NEVER alongside config)

fn configCheck()

Run `radiusd -C` in the target and report pass/fail + (tail-bounded) output (read-only). Uses -C, not -CX, to avoid persisting the config dump (which contains secrets).

fn apply(files: array, restart: boolean, checkArgs: array, allowOutsideRaddb: boolean)

Atomically write raddb config files in the target, gate on `radiusd -C`, and (optionally) restart — rolling back all files if the check or restart fails.

Argument	Type	Required	Description
files	array	yes	Whole-file config units to write under raddb
restart	boolean	yes	Restart the unit after a passing check (false = stage + check only)
checkArgs	array	yes	Config-check args. Default -C (quiet). -CX dumps config incl. secrets.
allowOutsideRaddb	boolean	yes	Permit writing files outside raddbDir (e.g. systemd drop-ins).

fn setClient(shortname: string, ipaddr: string, secret: string, nastype?: string, extra?: record, clientsFile?: string, restart: boolean)

Idempotently manage one `client <shortname> { … }` stanza in clients.conf as a swamp-managed block (secret from vault), then gate on `radiusd -C` and optionally restart. Re-running replaces the block; surrounding hand-authored clients are untouched.

Argument	Type	Required	Description
shortname	string	yes	client stanza name (bareword)
ipaddr	string	yes	client ipaddr (e.g. 10.0.0.5 or an FQDN)
secret	string	yes	RADIUS shared secret (wire a vault expression here; never persisted)
nastype?	string	no	optional nastype (e.g. other)
extra?	record	no	additional `key = value` lines (values used verbatim)
clientsFile?	string	no	clients.conf path (default <raddbDir>/clients.conf)
restart	boolean	yes	Restart after a passing check (false = stage + check only)

fn putModule(name: string, content: string, enabled: boolean, restart: boolean)

Write a module file to mods-available/<name> and (by default) enable it via the mods-enabled/<name> symlink — never a copy — then gate on `radiusd -C` and optionally restart. Use this to assert invariants like the ldap pool `start = 0`.

Argument	Type	Required	Description
name	string	yes	module name (bareword, e.g. ldap/eap)
content	string	yes	full module file content
enabled	boolean	yes	Ensure the mods-enabled/<name> symlink (false = write available only)
restart	boolean	yes	Restart after a passing check (false = stage + check only)

fn putSite(rules: array, defaultVlan: number, gate?: string, policyBody?: string, siteFile?: string, policyFile?: string, restart: boolean)

Manage the LDAP-group → VLAN post-auth steering policy as a swamp-owned $INCLUDE'd file, wired into sites-enabled/default's post-auth stanza (idempotent). Gate on `radiusd -C` and optionally restart.

Argument	Type	Required	Description
rules	array	yes	group → VLAN override rules (order = precedence)
defaultVlan	number	yes	VLAN assigned when no override rule matches
gate?	string	no	unlang condition gating the block (default &request:EAP-Message)
policyBody?	string	no	raw policy body override (bypasses rules/defaultVlan generation)
siteFile?	string	no	site file to wire (default <raddbDir>/sites-enabled/default)
policyFile?	string	no	swamp-owned policy file (default <raddbDir>/swamp/vlan-steering.conf)
restart	boolean	yes	Restart after a passing check (false = stage + check only)

fn certPerms(paths: array, owner: string, mode: string)

Idempotently assert owner:group + mode on cert/key files (renewal-safe; certmonger resets these on renewal). Defaults to certs/server.key → root:radiusd 640. Read-only w.r.t. config: no check, no restart.

Argument	Type	Required	Description
paths	array	yes	cert/key paths (relative to raddbDir or absolute)
owner	string	yes	chown owner:group
mode	string	yes	chmod mode

fn removeManaged(kind: string, key: string, file: string, restart: boolean)

Remove a swamp-managed marker block (e.g. a `setClient` client or a `putSite` $INCLUDE) from a raddb file, then gate on `radiusd -C` and optionally restart. Strips ONLY the `# >>> swamp-managed:<kind>:<key> >>> … <<<` region; surrounding hand-authored config keeps its exact bytes. A no-op (no write, no restart) when the block is absent. Does NOT delete any file the block referenced (e.g. an $INCLUDE'd policy stays on disk, unloaded).

Argument	Type	Required	Description
kind	string	yes	Managed-block kind, e.g. 'client' (setClient) or 'include' (putSite)
key	string	yes	Managed-block key, e.g. the client shortname, or the $INCLUDE'd path
file	string	yes	raddb file containing the block (relative to raddbDir or absolute),
restart	boolean	yes	Restart after a passing check when a block was actually removed