FreeRADIUS InkBridge

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. Not all modules support a trigger subsection.

Trunk connection triggers

The following modules use trunk connections:

  • ldap

  • sql

  • radius

  • tacacs

and these all support the following triggers relating to trunk connection state changes.

Instead of globally configuring these triggers here, they should be configured per module instance by including a trigger section within the module instance pool section. That allows for the ${.:name} and ${.:instance} expansions to reference the correct module name and instance name.

In addition to either enabling the triggers here or within the module pool section, for triggers to be enabled for a specific module instance, the triggers option within the pool section needs to be set to yes.

Define common arguments to use below:

connection_halted

A connection has entered the "halted" state.

All connections start in this state, and return to it after closing.

connection_init

A connection is being initialised

connection_connecting

A connection has started connecting to the remote server

active

A connection has become active (able to service requests)

  *Note:* This trigger should not be configured for SQL since due to the limitation of
one query per connection, every SQL query results in the connection switching from
`active` to `full` and then back again.
connection_closed

A connection has been closed.

connection_full

A connection has become full.

A full connection is one which has reached the maximum number of requests per connection.

  *Note:* This trigger should not be configured for SQL as every query results in the
connection becoming full, due to the limit of one query per connection.
connection_inactive

A connection has become inactive (unable to accept new requests)

connection_inactive_draining

A connection has become inactive and is draining its requests.

connection_draining

A connection is draining its outstanding requests

connection_draining_to_free

A connection is draining its outstanding requests before feeing.

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 {
	}
#	pool {
#		args = "radiusdModuleName s '${.:name}' radiusdModuleInstance s '${.:instance}'"
#		connection_halted = `${snmptrap}::serverModuleConnectionHalted ${args}`
#		connection_init = `${snmptrap}::serverModuleConnectionInit ${args}`
#		connection_connecting = `${snmptrap}::serverModuleConnectionInit ${args}`
#		connection_active = `${snmptrap}::serverModuleConnectionUp ${args}`
#		connection_closed = `${snmptrap}::serverModuleConnectionDown ${args}`
#		connection_full = `${snmptrap}::serverModuleConnectionFull ${args}`
#		connection_inactive = `${snmptrap}::serverModuleConnectionInactive ${args}`
#		connection_inactive_draining = `${snmptrap}::serverModuleConnectionInactiveDraining ${args}`
#		connection_draining = `${snmptrap}::serverModuleConnectionDraining ${args}`
#		connection_draining_to_free = `${snmptrap}::serverModuleConnectionDrainingToFree ${args}`
#	}
}