path: root/raddb/trigger.conf

# -*- text -*-
##
## trigger.conf -- Events in the server can trigger a hook to be executed.
##
##	$Id$

#
#  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/group" set in radiusd.conf.  The "snmptrap" program
#  may behave differently when run as "root" or as the "radiusd" user.
#
snmp {
	#
	#  Configuration for SNMP traps / notifications
	#
	#  To disable traps, edit "radiusd.conf", and delete the line
	#  which says "$INCUDE trigger.conf"
	#
	trap {
		#
		#  Absolute path for the "snmptrap" command, and
		#  default command-line arguments.
		#
		#  You can disable traps by changing the command to
		#  "/bin/echo".
		#
		cmd = "/usr/bin/snmptrap -v2c"

		#
		#  Community string
		#
		community = "public"

		#
		#  Agent configuration.
		#
		agent = "localhost ''"
	}
}

#
#  The "snmptrap" configuration defines the full command used to run the traps.
#
#  This entry should not be edited.  Instead, edit the "trap" section above.
#
snmptrap = "${snmp.trap.cmd} -c ${snmp.trap.community} ${snmp.trap.agent} FREERADIUS-NOTIFICATION-MIB"

#
#  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.
#
#  However... the traps are just programs which are run when
#  particular events occur.  If you want to replace a 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.  But that will
#  prevent the start/stop SNMP traps from working, of course.
#
trigger {
	#
	# Events in the server core
	#
	server {
		# the server has just started
		start = "${snmptrap}::serverStart"

		# the server is about to stop
		stop = "${snmptrap}::serverStop"

		# The "max_requests" condition has been reached.
		# This will trigger only once per 60 seconds.
		max_requests = "${snmptrap}::serverMaxRequests"

		# For events related to clients
		client {
			#  Added a new dynamic client
			add = "/path/to/file %{Packet-Src-IP-Address}"

			#  There is no event for when dynamic clients expire
		}

		# Events related to signals received.
		signal {
			# a HUP signal
			hup = "${snmptrap}::signalHup"

			# a TERM signal
			term = "${snmptrap}::signalTerm"
		}


		# Events related to the thread pool
		thread {
		       # A new thread has been started
		       start = "${snmptrap}::threadStart"

		       # an existing thread has been stopped
		       stop = "${snmptrap}::threadStop"

		       # an existing thread is unresponsive
		       unresponsive = "${snmptrap}::threadUnresponsive"

		       # the "max_threads" limit has been reached
		       max_threads = "${snmptrap}::threadMaxThreads"
		}
	}

	# When a home server changes state.
	# These traps are edge triggered.
	home_server {
		# common arguments: IP, port, identifier
		args = "radiusAuthServerAddress a %{proxy-request:Packet-Dst-IP-Address} radiusAuthClientServerPortNumber i %{proxy-request:Packet-Dst-Port} radiusAuthServIdent s '%{home_server:instance}'"

		# The home server has been marked "alive"
		alive = "${snmptrap}::homeServerAlive ${args}"

		# The home server has been marked "zombie"
		zombie = "${snmptrap}::homeServerZombie ${args}"

		# The home server has been marked "dead"
		dead = "${snmptrap}::homeServerDead ${args}"
	}

	# When a pool of home servers changes state.
	home_server_pool {
		# common arguments
		args = "radiusdConfigName s %{home_server:instance}"

		# It has reverted to "normal" mode, where at least one
		# home server is alive.
		normal = "${snmptrap}::homeServerPoolNormal ${args}"

		# It is in "fallback" mode, with all home servers "dead"
		fallback = "${snmptrap}::homeServerPoolFallback ${args}"
	}

	#  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.
	modules {
		# Common arguments
		args = "radiusdModuleInstance s ''"

		# The files module
		files {
			# Common arguments
			args = "radiusdModuleName s files ${..args}"

			# The module has been HUP'd via radmin
			hup = "${snmptrap}::serverModuleHup ${args}"

			# Note that "hup" can be used for every module
			# which can be HUP'd via radmin
		}

		# The LDAP module
		# If the server does "bind as user", it will open and close
		# an LDAP connection ofr every "bind as user".  Be aware that
		# this will likely produce a lot of triggers.
		ldap {
			# Common arguments
			args = "radiusdModuleName s ldap ${..args}"

			# A new connection to the DB has been opened
			open = "${snmptrap}::serverModuleConnectionUp ${args}"

			# A connection to the DB has been closed
			close = "${snmptrap}::serverModuleConnectionDown ${args}"

			# The module has been HUP'd via radmin
			hup = "${snmptrap}::serverModuleHup ${args}"
		}

		# The SQL module
		sql {
			# Common arguments
			args = "radiusdModuleName s sql ${..args}"

			# A new connection to the DB has been opened
			open = "${snmptrap}::serverModuleConnectionUp ${args}"

			# A connection to the DB has been closed
			close = "${snmptrap}::serverModuleConnectionDown ${args}"

			# Failed to open a new connection to the DB
			fail = "${snmptrap}::serverModuleConnectionFail ${args}"

			# The module has been HUP'd via radmin
			hup = "${snmptrap}::serverModuleHup ${args}"
		}

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

#
#  The complete list of triggers as generated from the source code is below.
#
#  These are the ONLY traps which are generated.  You CANNOT add new traps
#  by defining them in one of the sections above.  New traps can be created
#  only by edited both the source code to the server, *and* the MIBs.
#  If you are not an expert in C and SNMP, then adding new traps will be
#  difficult to create.
#
# home_server.alive
# home_server.dead
# home_server.zombie
# home_server_pool.fallback
# home_server_pool.normal
# modules.*.hup
# modules.ldap.timeout
# modules.sql.close
# modules.sql.fail
# modules.sql.open
# server.client.add
# server.max_requests
# server.signal.hup
# server.signal.term
# server.start
# server.stop
# server.thread.max_threads
# server.thread.start
# server.thread.stop
# server.thread.unresponsive