userapps/opensource/net-snmp/man/snmptrapd.8.def

   1 .\" /***********************************************************
   2 .\"     Copyright 1989 by Carnegie Mellon University
   3 .\"
   4 .\"                       All Rights Reserved
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software and its
   7 .\" documentation for any purpose and without fee is hereby granted,
   8 .\" provided that the above copyright notice appear in all copies and that
   9 .\" both that copyright notice and this permission notice appear in
  10 .\" supporting documentation, and that the name of CMU not be
  11 .\" used in advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\"
  14 .\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  15 .\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  16 .\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  17 .\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  18 .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  19 .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  20 .\" SOFTWARE.
  21 .\" ******************************************************************/
  22 .TH SNMPTRAPD 8 "07 Feb 2002" VVERSIONINFO "Net-SNMP"
  23 .UC 4
  24 .SH NAME
  25 snmptrapd - Receive and log SNMP trap messages.
  26 .SH SYNOPSIS
  27 .BR snmptrapd " [OPTIONS] [LISTENING ADDRESSES]"
  28 .SH DESCRIPTION
  29 .B snmptrapd
  30 is an SNMP application that receives and logs SNMP TRAP and INFORM
  31 messages.
  32 .PP
  33 Note: the default is to listen on UDP port 162 on all IPv4 interfaces.
  34 Since 162 is a privileged port,
  35 .B snmptrapd
  36 must be typically be run as root.
  37 .SH OPTIONS
  38 .TP 8
  39 .B -a
  40 Ignore authenticationFailure traps.
  41 .TP
  42 .BI "-c" " FILE"
  43 Read
  44 .I FILE
  45 as a configuration file.
  46 .TP
  47 .B -C
  48 Do not read any configuration files except the one optionally specified by the
  49 .B -c
  50 option.
  51 .TP
  52 .B -d
  53 Dump (in hexadecimal) the sent and received SNMP packets.
  54 .TP
  55 .BI -D " TOKEN[,...]"
  56 Turn on debugging output for the given
  57 .IR "TOKEN" "(s)."
  58 Try
  59 .IR ALL
  60 for extremely verbose output.
  61 .TP
  62 .B -e
  63 Print event numbers (rising/falling alarm etc.).
  64 .TP
  65 .B -f
  66 Do not fork() from the calling shell.
  67 .TP
  68 .BI -F " FORMAT"
  69 When logging to standard output, use the format in the string
  70 .IR FORMAT .
  71 See the section
  72 .B FORMAT SPECIFICATIONS
  73 below for more details.
  74 .TP
  75 .B -h, --help
  76 Display a brief usage message and then exit.
  77 .TP
  78 .B -H
  79 Display a list of configuration file directives understood by the
  80 trap daemon and then exit.
  81 .TP
  82 .BR -l " d|0-7"
  83 Specifies the syslog facility to use when logging to syslog.  'd' means
  84 .B LOG_DAEMON
  85 and 0 through 7 mean
  86 .BR LOG_LOCAL0 " through " LOG_LOCAL7 ".  " LOG_LOCAL0 " is the default."
  87 .TP
  88 .BR -m " \fIMIBLIST"
  89 Specifies a colon separated list of MIB modules to load for this
  90 application.  This overrides the environment variable MIBS.
  91 .TP
  92 .BR -M " \fIDIRLIST"
  93 Specifies a colon separated list of directories to search for MIBs.
  94 This overrides the environment variable MIBDIRS.
  95 .TP
  96 .BR -n
  97 Do not attempt to translate source addresses of incoming packets into
  98 hostnames.
  99 .TP
 100 .BI -o " FILE"
 101 Log formatted incoming traps to
 102 .IR FILE .
 103 Upon receipt of a SIGHUP, the daemon will close and re-open
 104 the log file.  This feature is useful when rotating the log file with
 105 other utilities such as logrotate.
 106 .TP
 107 .B -P
 108 Print formatted incoming traps to stderr.
 109 .TP
 110 .B -s
 111 Log formatted incoming traps to syslog.  These syslog messages are
 112 sent with a level of
 113 .B LOG_WARNING
 114 and facility as determined by the
 115 .BR -l " flag (" LOG_LOCAL0
 116 by default).  This is the default unless the
 117 .BR -o " or " -P
 118 flag is used.
 119 .TP
 120 .BI -u " FILE"
 121 Save the process ID of the trap daemon in
 122 .IR FILE "."
 123 .TP
 124 .B -v, --version
 125 Print version information for the trap daemon and then exit.
 126 .PP
 127 In addition,
 128 .B snmptrapd
 129 takes the same output formatting
 130 .BR "" ( -O )
 131 options as the other Net-SNMP commands.  See the section
 132 .B OUTPUT OPTIONS
 133 in the
 134 .I snmpcmd(1)
 135 manual page.
 136 .SH FORMAT SPECIFICATIONS
 137 .PP
 138 .B snmptrapd
 139 interprets format strings similarly to
 140 .IR printf(3) .
 141 It understands the following formatting sequences:
 142 .RS 4
 143 .TP 4
 144 .B %%
 145 a literal %
 146 .TP
 147 .B %t
 148 decimal number of seconds since the operating system's epoch (as
 149 returned by
 150 .IR time(2) )
 151 .TP
 152 .B %y
 153 current year on the local system
 154 .TP
 155 .B %m
 156 current (numeric) month on the local system
 157 .TP
 158 .B %l
 159 current day of month on the local system
 160 .TP
 161 .B %h
 162 current hour on the local system
 163 .TP
 164 .B %j
 165 current minute on the local system
 166 .TP
 167 .B %k
 168 current second on the local system
 169 .TP
 170 .B %T
 171 the value of the sysUpTime.0 varbind in seconds
 172 .TP
 173 .B %Y
 174 the year field from the sysUpTime.0 varbind
 175 .TP
 176 .B %M
 177 the numeric month field from the sysUpTime.0 varbind
 178 .TP
 179 .B %L
 180 the day of month field from the sysUpTime.0 varbind
 181 .TP
 182 .B %H
 183 the hour field from the sysUpTime.0 varbind
 184 .TP
 185 .B %J
 186 the minute field from the sysUpTime.0 varbind
 187 .TP
 188 .B %K
 189 the seconds field from the sysUpTime.0 varbind
 190 .TP
 191 .B %a
 192 the contents of the agent-addr field of the PDU (v1 TRAPs only)
 193 .TP
 194 .B %A
 195 the hostname corresponding to the contents of the agent-addr field of
 196 the PDU, if available, otherwise the contents of the agent-addr field
 197 of the PDU (v1 TRAPs only).
 198 .TP
 199 .B %b
 200 PDU source address (Note: this is not necessarily an IPv4
 201 address)
 202 .TP
 203 .B %B
 204 PDU source hostname if available, otherwise PDU source address (see
 205 note above)
 206 .TP
 207 .B %N
 208 enterprise string
 209 .TP
 210 .B %w
 211 trap type (numeric, in decimal)
 212 .TP
 213 .B %W
 214 trap description
 215 .TP
 216 .B %q
 217 trap sub-type (numeric, in decimal)
 218 .TP
 219 .B %P
 220 security information from the PDU (community name for v1/v2c,
 221 user and context for v3)
 222 .TP
 223 .B %v
 224 list of trap's variable-bindings
 225 .RE
 226 .PP
 227 In addition to these values, you may also specify an optional field
 228 width and precision, just as in
 229 .IR printf(3) ,
 230 and a flag value. The following flags are legal:
 231 .RS 4
 232 .TP 4
 233 .B -
 234 left justify
 235 .TP
 236 .B 0
 237 use leading zeros
 238 .TP
 239 .B #
 240 use alternate form
 241 .RE
 242 .PP
 243 The "use alternate form" flag changes the behavior of some format
 244 flags. Normally, the fields that display time information base it on
 245 the local timezone, but this flag tells them to use GMT instead.
 246 Also, the variable-binding list is normally a tab-separated list, but
 247 this flag changes it to a comma-separated one. The alternate form for
 248 the uptime is similar to "3 days, 0:14:34.65"
 249 .SS Examples:
 250 .PP
 251 To get a message like "14:03 TRAP3.1 from humpty.ucd.edu" you
 252 could use something like this:
 253 .PP
 254 .RS
 255 .nf
 256 snmptrapd -P -F "%02.2h:%02.2j TRAP%w.%q from %A\en"
 257 .fi
 258 .RE
 259 .PP
 260 If you want the same thing but in GMT rather than local time, use
 261 .PP
 262 .RS
 263 .nf
 264 snmptrapd -P -F "%#02.2h:%#02.2j TRAP%w.%q from %A\en"
 265 .fi
 266 .RE
 267 .SH LISTENING ADDRESSES
 268 By default,
 269 .B snmptrapd
 270 listens for incoming SNMP TRAP and INFORM packets on UDP port 162 on
 271 all IPv4 interfaces.  However, it is possible to modify this behaviour
 272 by specifying one or more listening addresses as arguments to
 273 .BR snmptrapd .
 274 See the
 275 .I snmpd(8)
 276 manual page for more information about the format of listening
 277 addresses.
 278 .SH NOTIFICATION-LOG-MIB SUPPORT
 279 As of net-snmp 5.0, the snmptrapd application supports the
 280 NOTIFICATION-LOG-MIB.  It does this by opening an AgentX subagent
 281 connection to the master snmpd agent and registering the notification
 282 log tables.  As long as the snmpd application is started first, it
 283 will attach itself to it and thus you should be able to view the last
 284 recorded notifications via the nlmLogTable and nlmLogVariableTable.
 285 See the snmptrapd.conf file and the "dontRetainLogs" token for turning
 286 off this support.  See the NOTIFICATION-LOG-MIB for more details about
 287 the MIB itself.
 288 .SH EXTENSIBILITY AND CONFIGURATION
 289 See the
 290 .I snmptrapd.conf(5)
 291 manual page.
 292 .SH "SEE ALSO"
 293 snmpcmd(1), snmpd(8), printf(3), snmptrapd.conf(5), syslog(8), variables(5)