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