raddb/trigger.conf

   1 # -*- text -*-
   2 ##
   3 ## trigger.conf -- Events in the server can trigger a hook to be executed.
   4 ##
   5 ##      $Id$
   6
   7 #
   8 #  The triggers are named as "type.subtype.value".  These names refer
   9 #  to subsections and then configuration items in the "trigger"
  10 #  section below.  When an event occurs, the trigger is executed.  The
  11 #  trigger is simply a program that is run, with optional arguments.
  12 #
  13 #  The server does not wait when a trigger is executed.  It is simply
  14 #  a "one-shot" event that is sent.
  15 #
  16 #  The trigger names should be self-explanatory.
  17 #
  18
  19 #
  20 #  SNMP configuration.
  21 #
  22 #  For now, this is only for SNMP traps.
  23 #
  24 #  They are enabled by uncommenting (or adding) "$INCLUDE trigger.conf"
  25 #  in the main "radiusd.conf" file.
  26 #
  27 #  The traps *REQUIRE* that the files in the "mibs" directory be copied
  28 #  to the global mibs directory, usually /usr/share/snmp/mibs/.
  29 #  If this is not done, the "snmptrap" program has no idea what information
  30 #  to send, and will not work.  The MIB installation is *NOT* done as
  31 #  part of the default installation, so that step *MUST* be done manually.
  32 #
  33 #  The global MIB directory can be found by running the following command:
  34 #
  35 #       snmptranslate -Dinit_mib .1.3 2>&1 | grep MIBDIR | sed "s/' .*//;s/.* '//;s/.*://"
  36 #
  37 #  Or maybe just:
  38 #
  39 #       snmptranslate -Dinit_mib .1.3 2>&1 | grep MIBDIR
  40 #
  41 #  If you have copied the MIBs to that directory, you can test the
  42 #  FreeRADIUS MIBs by running the following command:
  43 #
  44 #       snmptranslate -m +FREERADIUS-NOTIFICATION-MIB -IR -On  serverStart
  45 #
  46 #  It should print out:
  47 #
  48 #       .1.3.6.1.4.1.11344.4.1.1
  49 #
  50 #  As always, run the server in debugging mode after enabling the
  51 #  traps.  You will see the "snmptrap" command being run, and it will
  52 #  print out any errors or issues that it encounters.  Those need to
  53 #  be fixed before running the server in daemon mode.
  54 #
  55 #  We also suggest running in debugging mode as the "radiusd" user, if
  56 #  you have "user/group" set in radiusd.conf.  The "snmptrap" program
  57 #  may behave differently when run as "root" or as the "radiusd" user.
  58 #
  59 snmp {
  60         #
  61         #  Configuration for SNMP traps / notifications
  62         #
  63         #  To disable traps, edit "radiusd.conf", and delete the line
  64         #  which says "$INCUDE trigger.conf"
  65         #
  66         trap {
  67                 #
  68                 #  Absolute path for the "snmptrap" command, and
  69                 #  default command-line arguments.
  70                 #
  71                 #  You can disable traps by changing the command to
  72                 #  "/bin/echo".
  73                 #
  74                 cmd = "/usr/bin/snmptrap -v2c"
  75
  76                 #
  77                 #  Community string
  78                 #
  79                 community = "public"
  80
  81                 #
  82                 #  Agent configuration.
  83                 #
  84                 agent = "localhost ''"
  85         }
  86 }
  87
  88 #
  89 #  The "snmptrap" configuration defines the full command used to run the traps.
  90 #
  91 #  This entry should not be edited.  Instead, edit the "trap" section above.
  92 #
  93 snmptrap = "${snmp.trap.cmd} -c ${snmp.trap.community} ${snmp.trap.agent} FREERADIUS-NOTIFICATION-MIB"
  94
  95 #
  96 #  The individual triggers are defined here.  You can disable one by
  97 #  deleting it, or by commenting it out.  You can disable an entire
  98 #  section of traps by deleting the section.
  99 #
 100 #  The entries below should not be edited.  For example, the double colons
 101 #  *must* immediately follow the ${snmptrap} reference.  Adding a space
 102 #  before the double colons  will break all SNMP traps.
 103 #
 104 #  However... the traps are just programs which are run when
 105 #  particular events occur.  If you want to replace a trap with
 106 #  another program, you can.  Just edit the definitions below, so that
 107 #  they run a program of your choice.
 108 #
 109 #  For example, you can leverage the "start/stop" triggers to run a
 110 #  program when the server starts, or when it stops.  But that will
 111 #  prevent the start/stop SNMP traps from working, of course.
 112 #
 113 trigger {
 114         #
 115         # Events in the server core
 116         #
 117         server {
 118                 # the server has just started
 119                 start = "${snmptrap}::serverStart"
 120
 121                 # the server is about to stop
 122                 stop = "${snmptrap}::serverStop"
 123
 124                 # The "max_requests" condition has been reached.
 125                 # This will trigger only once per 60 seconds.
 126                 max_requests = "${snmptrap}::serverMaxRequests"
 127
 128                 # For events related to clients
 129                 client {
 130                         #  Added a new dynamic client
 131                         add = "/path/to/file %{Packet-Src-IP-Address}"
 132
 133                         #  There is no event for when dynamic clients expire
 134                 }
 135
 136                 # Events related to signals received.
 137                 signal {
 138                         # a HUP signal
 139                         hup = "${snmptrap}::signalHup"
 140
 141                         # a TERM signal
 142                         term = "${snmptrap}::signalTerm"
 143                 }
 144
 145
 146                 # Events related to the thread pool
 147                 thread {
 148                        # A new thread has been started
 149                        start = "${snmptrap}::threadStart"
 150
 151                        # an existing thread has been stopped
 152                        stop = "${snmptrap}::threadStop"
 153
 154                        # an existing thread is unresponsive
 155                        unresponsive = "${snmptrap}::threadUnresponsive"
 156
 157                        # the "max_threads" limit has been reached
 158                        max_threads = "${snmptrap}::threadMaxThreads"
 159                 }
 160         }
 161
 162         # When a home server changes state.
 163         # These traps are edge triggered.
 164         home_server {
 165                 # common arguments: IP, port, identifier
 166                 args = "radiusAuthServerAddress a %{proxy-request:Packet-Dst-IP-Address} radiusAuthClientServerPortNumber i %{proxy-request:Packet-Dst-Port} radiusAuthServIdent s '%{home_server:instance}'"
 167
 168                 # The home server has been marked "alive"
 169                 alive = "${snmptrap}::homeServerAlive ${args}"
 170
 171                 # The home server has been marked "zombie"
 172                 zombie = "${snmptrap}::homeServerZombie ${args}"
 173
 174                 # The home server has been marked "dead"
 175                 dead = "${snmptrap}::homeServerDead ${args}"
 176         }
 177
 178         # When a pool of home servers changes state.
 179         home_server_pool {
 180                 # common arguments
 181                 args = "radiusdConfigName s %{home_server:instance}"
 182
 183                 # It has reverted to "normal" mode, where at least one
 184                 # home server is alive.
 185                 normal = "${snmptrap}::homeServerPoolNormal ${args}"
 186
 187                 # It is in "fallback" mode, with all home servers "dead"
 188                 fallback = "${snmptrap}::homeServerPoolFallback ${args}"
 189         }
 190
 191         #  Triggers for specific modules.  These are NOT in the module
 192         #  configuration because they are global to all instances of the
 193         #  module.  You can have module-specific triggers, by placing a
 194         #  "trigger" subsection in the module configuration.
 195         modules {
 196                 # Common arguments
 197                 args = "radiusdModuleName s ldap' radiusdModuleInstance s ''"
 198
 199                 # The files module
 200                 files {
 201                         # The module has been HUP'd via radmin
 202                         hup = "${snmptrap}::serverModuleHup ${..args}"
 203
 204                         # Note that "hup" can be used for every module
 205                         # which can be HUP'd via radmin
 206                 }
 207
 208                 # The LDAP module
 209                 ldap {
 210                         # Failed to open a new connection to the DB
 211                         fail = "${snmptrap}::serverModuleConnectionFail ${..args}"
 212
 213                         # There are no "open", "close", or "none" setting.
 214                         # This is because the LDAP module re-connects and closes
 215                         # the connection for every "bind as user" query.
 216                 }
 217
 218                 # The SQL module
 219                 sql {
 220                         # A new connection to the DB has been opened
 221                         open = "${snmptrap}::serverModuleConnectionUp ${..args}"
 222
 223                         # A connection to the DB has been closed
 224                         close = "${snmptrap}::serverModuleConnectionDown ${..args}"
 225
 226                         # Failed to open a new connection to the DB
 227                         fail = "${snmptrap}::serverModuleConnectionFail ${..args}"
 228
 229                         # There are no DB handles available.
 230                         none = "${snmptrap}::serverModuleConnectionNone ${..args}"
 231                 }
 232         }
 233 }
 234
 235 #
 236 #  The complete list of triggers as generated from the source code is below.
 237 #
 238 #  These are the ONLY traps which are generated.  You CANNOT add new traps
 239 #  by defining them in one of the sections above.  New traps can be created
 240 #  only by edited both the source code to the server, *and* the MIBs.
 241 #  If you are not an expert in C and SNMP, then adding new traps will be
 242 #  difficult to create.
 243 #
 244 # home_server.alive
 245 # home_server.dead
 246 # home_server.zombie
 247 # home_server_pool.fallback
 248 # home_server_pool.normal
 249 # modules.*.hup
 250 # modules.ldap.fail
 251 # modules.sql.close
 252 # modules.sql.fail
 253 # modules.sql.none
 254 # modules.sql.open
 255 # server.client.add
 256 # server.max_requests
 257 # server.signal.hup
 258 # server.signal.term
 259 # server.start
 260 # server.stop