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         # When a home server changes state.
 147         # These traps are edge triggered.
 148         home_server {
 149                 # common arguments: IP, port, identifier
 150                 args = "radiusAuthServerAddress a %{proxy-request:Packet-Dst-IP-Address} radiusAuthClientServerPortNumber i %{proxy-request:Packet-Dst-Port} radiusAuthServIdent s '%{home_server:instance}'"
 151
 152                 # The home server has been marked "alive"
 153                 alive = "${snmptrap}::homeServerAlive ${args}"
 154
 155                 # The home server has been marked "zombie"
 156                 zombie = "${snmptrap}::homeServerZombie ${args}"
 157
 158                 # The home server has been marked "dead"
 159                 dead = "${snmptrap}::homeServerDead ${args}"
 160         }
 161
 162         # When a pool of home servers changes state.
 163         home_server_pool {
 164                 # common arguments
 165                 args = "radiusdConfigName s %{home_server:instance}"
 166
 167                 # It has reverted to "normal" mode, where at least one
 168                 # home server is alive.
 169                 normal = "${snmptrap}::homeServerPoolNormal ${args}"
 170
 171                 # It is in "fallback" mode, with all home servers "dead"
 172                 fallback = "${snmptrap}::homeServerPoolFallback ${args}"
 173         }
 174
 175         #  Triggers for specific modules.  These are NOT in the module
 176         #  configuration because they are global to all instances of the
 177         #  module.  You can have module-specific triggers, by placing a
 178         #  "trigger" subsection in the module configuration.
 179         modules {
 180                 # The SQL module
 181                 sql {
 182                         # Common arguments
 183                         args = "radiusdModuleName s 'sql' radiusdModuleInstance s ''"
 184
 185                         # A new connection to the DB has been opened
 186                         open = "${snmptrap}::serverModuleConnectionUp ${args}"
 187
 188                         # A connection to the DB has been closed
 189                         close = "${snmptrap}::serverModuleConnectionDown ${args}"
 190                         # There are no DB handles available.
 191                         none = "${snmptrap}::serverModuleConnectionNone ${args}"
 192                 }
 193         }
 194 }
 195
 196 #
 197 #  The complete list of triggers as generated from the source code is below.
 198 #
 199 #  These are the ONLY traps which are generated.  You CANNOT add new traps
 200 #  by defining them in one of the sections above.  New traps can be created
 201 #  only by edited both the source code to the server, *and* the MIBs.
 202 #  If you are not an expert in C and SNMP, then adding new traps will be
 203 #  difficult to create.
 204 #
 205 # home_server.alive
 206 # home_server.dead
 207 # home_server.zombie
 208 # home_server_pool.fallback
 209 # home_server_pool.normal
 210 # modules.sql.close
 211 # modules.sql.none
 212 # modules.sql.open
 213 # server.client.add
 214 # server.max_requests
 215 # server.signal.hup
 216 # server.signal.term
 217 # server.start
 218 # server.stop