doc/snmp.texi

   1 @node SNMP Support
   2 @chapter SNMP Support
   3
   4 @acronym{SNMP,Simple Network Managing Protocol} is a widely implemented
   5 feature for collecting network information from router and/or host.
   6 Frr itself does not support SNMP agent (server daemon) functionality
   7 but is able to connect to a SNMP agent using the SMUX protocol
   8 (@cite{RFC1227}) or the AgentX protocol (@cite{RFC2741}) and make the
   9 routing protocol MIBs available through it.
  10
  11 Note that SNMP Support needs to be enabled at compile-time and loaded as
  12 module on daemon startup.  Refer to @ref{Loadable Module Support} on
  13 the latter.
  14
  15 @menu
  16 * Getting and installing an SNMP agent::
  17 * AgentX configuration::
  18 * SMUX configuration::
  19 * MIB and command reference::
  20 * Handling SNMP Traps::
  21 @end menu
  22
  23 @node Getting and installing an SNMP agent
  24 @section Getting and installing an SNMP agent
  25
  26 There are several SNMP agent which support SMUX or AgentX. We recommend to use the latest
  27 version of @code{net-snmp} which was formerly known as @code{ucd-snmp}.
  28 It is free and open software and available at @uref{http://www.net-snmp.org/}
  29 and as binary package for most Linux distributions.
  30 @code{net-snmp} has to be compiled with @code{--with-mib-modules=agentx} to
  31 be able to accept connections from Frr using AgentX protocol or with
  32 @code{--with-mib-modules=smux} to use SMUX protocol.
  33
  34 Nowadays, SMUX is a legacy protocol. The AgentX protocol should be
  35 preferred for any new deployment. Both protocols have the same coverage.
  36
  37 @node AgentX configuration
  38 @section AgentX configuration
  39
  40 To enable AgentX protocol support, Frr must have been build with the
  41 @code{--enable-snmp} or @code{--enable-snmp=agentx} option. Both the
  42 master SNMP agent (snmpd) and each of the Frr daemons must be
  43 configured. In @code{/etc/snmp/snmpd.conf}, @code{master agentx}
  44 directive should be added. In each of the Frr daemons, @code{agentx}
  45 command will enable AgentX support.
  46
  47 @example
  48 /etc/snmp/snmpd.conf:
  49         #
  50         # example access restrictions setup
  51         #
  52         com2sec readonly default public
  53         group MyROGroup v1 readonly
  54         view all included .1 80
  55         access MyROGroup "" any noauth exact all none none
  56         #
  57         # enable master agent for AgentX subagents
  58         #
  59         master agentx
  60
  61 /etc/frr/ospfd.conf:
  62         ! ... the rest of ospfd.conf has been omitted for clarity ...
  63         !
  64         agentx
  65         !
  66 @end example
  67
  68 Upon successful connection, you should get something like this in the
  69 log of each Frr daemons:
  70
  71 @example
  72 2012/05/25 11:39:08 ZEBRA: snmp[info]: NET-SNMP version 5.4.3 AgentX subagent connected
  73 @end example
  74
  75 Then, you can use the following command to check everything works as expected:
  76
  77 @example
  78 # snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1
  79 OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109
  80 [...]
  81 @end example
  82
  83 The AgentX protocol can be transported over a Unix socket or using TCP
  84 or UDP. It usually defaults to a Unix socket and depends on how NetSNMP
  85 was built. If need to configure Frr to use another transport, you can
  86 configure it through @code{/etc/snmp/frr.conf}:
  87
  88 @example
  89 /etc/snmp/frr.conf:
  90         [snmpd]
  91         # Use a remote master agent
  92         agentXSocket tcp:192.168.15.12:705
  93 @end example
  94
  95 @node SMUX configuration
  96 @section SMUX configuration
  97
  98 To enable SMUX protocol support, Frr must have been build with the
  99 @code{--enable-snmp=smux} option.
 100
 101 A separate connection has then to be established between the
 102 SNMP agent (snmpd) and each of the Frr daemons. This connections
 103 each use different OID numbers and passwords. Be aware that this OID
 104 number is not the one that is used in queries by clients, it is solely
 105 used for the intercommunication of the daemons.
 106
 107 In the following example the ospfd daemon will be connected to the
 108 snmpd daemon using the password "frr_ospfd". For testing it is
 109 recommending to take exactly the below snmpd.conf as wrong access
 110 restrictions can be hard to debug.
 111
 112 @example
 113 /etc/snmp/snmpd.conf:
 114         #
 115         # example access restrictions setup
 116         #
 117         com2sec readonly default public
 118         group MyROGroup v1 readonly
 119         view all included .1 80
 120         access MyROGroup "" any noauth exact all none none
 121         #
 122         # the following line is relevant for Frr
 123         #
 124         smuxpeer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd
 125
 126 /etc/frr/ospf:
 127         ! ... the rest of ospfd.conf has been omitted for clarity ...
 128         !
 129         smux peer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd
 130         !
 131 @end example
 132
 133 After restarting snmpd and frr, a successful connection can be verified in
 134 the syslog and by querying the SNMP daemon:
 135
 136 @example
 137 snmpd[12300]: [smux_accept] accepted fd 12 from 127.0.0.1:36255
 138 snmpd[12300]: accepted smux peer: \
 139         oid GNOME-PRODUCT-ZEBRA-MIB::ospfd, frr-0.96.5
 140
 141 # snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1
 142 OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109
 143 @end example
 144
 145 Be warned that the current version (5.1.1) of the Net-SNMP daemon writes a line
 146 for every SNMP connect to the syslog which can lead to enormous log file sizes.
 147 If that is a problem you should consider to patch snmpd and comment out the
 148 troublesome @code{snmp_log()} line in the function
 149 @code{netsnmp_agent_check_packet()} in @code{agent/snmp_agent.c}.
 150
 151 @node MIB and command reference
 152 @section MIB and command reference
 153
 154 The following OID numbers are used for the interprocess communication of snmpd and
 155 the Frr daemons with SMUX only.
 156 @example
 157             (OIDs below .iso.org.dod.internet.private.enterprises)
 158 zebra   .1.3.6.1.4.1.3317.1.2.1 .gnome.gnomeProducts.zebra.zserv
 159 bgpd    .1.3.6.1.4.1.3317.1.2.2 .gnome.gnomeProducts.zebra.bgpd
 160 ripd    .1.3.6.1.4.1.3317.1.2.3 .gnome.gnomeProducts.zebra.ripd
 161 ospfd   .1.3.6.1.4.1.3317.1.2.5 .gnome.gnomeProducts.zebra.ospfd
 162 ospf6d  .1.3.6.1.4.1.3317.1.2.6 .gnome.gnomeProducts.zebra.ospf6d
 163 @end example
 164
 165 Sadly, SNMP has not been implemented in all daemons yet. The following
 166 OID numbers are used for querying the SNMP daemon by a client:
 167 @example
 168 zebra   .1.3.6.1.2.1.4.24   .iso.org.dot.internet.mgmt.mib-2.ip.ipForward
 169 ospfd   .1.3.6.1.2.1.14     .iso.org.dot.internet.mgmt.mib-2.ospf
 170 bgpd    .1.3.6.1.2.1.15     .iso.org.dot.internet.mgmt.mib-2.bgp
 171 ripd    .1.3.6.1.2.1.23     .iso.org.dot.internet.mgmt.mib-2.rip2
 172 ospf6d  .1.3.6.1.3.102      .iso.org.dod.internet.experimental.ospfv3
 173 @end example
 174
 175 The following syntax is understood by the Frr daemons for configuring SNMP using SMUX:
 176 @deffn {Command} {smux peer @var{oid}} {}
 177 @deffnx {Command} {no smux peer @var{oid}} {}
 178 @end deffn
 179
 180 @deffn {Command} {smux peer @var{oid} @var{password}} {}
 181 @deffnx {Command} {no smux peer @var{oid} @var{password}} {}
 182 @end deffn
 183
 184 Here is the syntax for using AgentX:
 185 @deffn {Command} {agentx} {}
 186 @deffnx {Command} {no agentx} {}
 187 @end deffn
 188
 189 @include snmptrap.texi