Triggers

Triggers are events in the server can cause a hook to be executed.

The triggers are named as type.subtype.value. These names refer to subsections and then configuration items in the trigger section below. When an event occurs, the trigger is executed. The trigger is simply a program that is run, with optional arguments.

The server does not wait when a trigger is executed. It is simply a one-shot event that is sent.

The trigger names should be self-explanatory.

SNMP configuration

For now, this is only for SNMP traps.

They are enabled by uncommenting (or adding) $INCLUDE trigger.conf in the main radiusd.conf file.

The traps require that the files in the "mibs" directory be copied to the global mibs directory, usually /usr/share/snmp/mibs/. If this is not done, the snmptrap program has no idea what information to send, and will not work. The MIB installation is not done as part of the default installation, so that step must be done manually.

The global MIB directory can be found by running the following command:

snmptranslate -Dinit_mib .1.3 2>&1 | grep MIBDIR | \
    sed "s/' .*//;s/.* '//;s/.*://"

Or maybe just:

snmptranslate -Dinit_mib .1.3 2>&1 | grep MIBDIR

If you have copied the MIBs to that directory, you can test the FreeRADIUS MIBs by running the following command:

snmptranslate -m +FREERADIUS-NOTIFICATION-MIB -IR -On serverStart

It should print out:

.1.3.6.1.4.1.11344.4.1.1

As always, run the server in debugging mode after enabling the traps. You will see the snmptrap command being run, and it will print out any errors or issues that it encounters. Those need to be fixed before running the server in daemon mode.

We also suggest running in debugging mode as the radiusd user, if you have "user" or "group" set in radiusd.conf. The snmptrap program may behave differently when run as root rather than the radiusd user.

Configuration for SNMP traps / notifications, used in the "snmptrap" option below.

To disable traps, edit radiusd.conf and delete the line which says $INCLUDE trigger.conf.

cmd: Absolute path for the snmptrap command, and default command-line arguments.

You can also temporarily disable traps by changing the command to /bin/echo.

community: The SNMP community string
agent: Agent configuration
snmptrap: Define the full command used to run the traps.

This entry should not be edited. Instead, edit the "trap" section above.

Trigger definitions

The individual triggers are defined here. You can disable one by deleting it, or by commenting it out. You can disable an entire section of traps by deleting the section.

The entries below should not be edited. For example, the double colons must immediately follow the ${snmptrap} reference. Adding a space before the double colons will break all SNMP traps.

The triggers just programs which are run when particular events occur. If you want to replace an SNMP trap with another program, you can. Just edit the definitions below, so that they run a program of your choice.

For example, you can leverage the "start/stop" triggers to run a program when the server starts, or when it stops. However, only one program will be executed per trigger.

Server core triggers

The 'server' section is for events that happen in the server core

start: The server has just started.
stop: The server is about to stop.
max_requests: The "max_requests" condition has been reached.

This will trigger only once per 60 seconds.

Module triggers

Triggers for specific modules. These are not in the module configuration because they are global to all instances of the module. You can have module-specific triggers, by placing a "trigger" subsection in the module configuration.

rlm_ldap: The LDAP module

If the server does "bind as user", it will open and close an LDAP connection every time it binds as a user. Be aware that this will likely produce a lot of triggers.

Define common arguments to use below:

open: A new connection to the directory has been opened.
close: A connection to the directory has been closed.
min: Connection was released too quickly.
max: Connection was held for too long.

rlm_sql: The SQL module

args: Define common arguments to use below:
open: A new connection to the database has been opened.
close: A connection to the database has been closed.
fail: Failed to open a new connection to the database.
min: A connection was released too quickly.
max: A connection was held for too long.

You can also use connection pool’s start/stop/open/close triggers for any module which uses the pool section, both here and under pool.trigger in module configuration.

Creating new triggers

Triggers are defined in the server source code. Those are the only traps which are generated.

You cannot add new traps by defining them in one of the sections in this file. New traps can be created only by editing both the source code of the server and the MIBs. If you are not an expert in C and SNMP, then creating new traps will be difficult.

Default Configuration

snmp {
	trap {
		cmd = "/usr/bin/snmptrap -v2c"
		community = "public"
		agent = "localhost ''"
	}
}
snmptrap = "${snmp.trap.cmd} -c ${snmp.trap.community} ${snmp.trap.agent} FREERADIUS-NOTIFICATION-MIB"
trigger {
	server {
		start = "${snmptrap}::serverStart"
		stop = "${snmptrap}::serverStop"
		max_requests = "${snmptrap}::serverMaxRequests"
	}
	modules {
		ldap {
			args = "radiusdModuleName s '${.:name}' radiusdModuleInstance s '${.:instance}'"
			open = "${snmptrap}::serverModuleConnectionUp ${args}"
			close = "${snmptrap}::serverModuleConnectionDown ${args}"
			min = "${snmptrap}::serverModuleConnectionReservedPeriodMin ${args}"
			max = "${snmptrap}::serverModuleConnectionReservedPeriodMax ${args}"
		}
		sql {
			args = "radiusdModuleName s '${.:name}' radiusdModuleInstance s '${.:instance}'"
			open = "${snmptrap}::serverModuleConnectionUp ${args}"
			close = "${snmptrap}::serverModuleConnectionDown ${args}"
			fail = "${snmptrap}::serverModuleConnectionFail ${args}"
			min = "${snmptrap}::serverModuleConnectionReservedPeriodMin ${args}"
			max = "${snmptrap}::serverModuleConnectionReservedPeriodMax ${args}"
		}
	}
}