doc/snmp.texi

@node SNMP Support
@chapter SNMP Support

SNMP (Simple Network Managing Protocol) is a widely implemented feature for
collecting network information from router and/or host. Quagga itself does not
support SNMP agent (server daemon) functionality but is able to connect to a
SNMP agent using the SMUX protocol (RFC1227) and make the routing protocol MIBs
available through it.

@menu
* Getting and installing an SNMP agent::
* SMUX configuration::
* MIB and command reference::
@end menu

@node Getting and installing an SNMP agent
@section Getting and installing an SNMP agent

There are several SNMP agent which support SMUX. We recommend to use the latest
version of @code{net-snmp} which was formerly known as @code{ucd-snmp}.
It is free and open software and available at @uref{http://www.net-snmp.org/}
and as binary package for most Linux distributions.
@code{net-snmp} has to be compiled with @code{--with-mib-modules=smux} to
be able to accept connections from Quagga.

@node SMUX configuration
@section SMUX configuration

To enable SMUX protocol support, Quagga must have been build with the
@code{--enable-snmp} option.

A separate connection has then to be established between between the SNMP agent
(snmpd) and each of the Quagga daemons. This connections each use different OID
numbers and passwords. Be aware that this OID number is not the one that is
used in queries by clients, it is solely used for the intercommunication of the
daemons.

In the following example the ospfd daemon will be connected to the snmpd daemon
using the password "quagga_ospfd". For testing it is recommending to take
exactly the below snmpd.conf as wrong access restrictions can be hard to debug.

@example
/etc/snmp/snmpd.conf:
	#
	# example access restrictions setup
	#
	com2sec readonly default public
	group MyROGroup v1 readonly
	view all included .1 80
	access MyROGroup "" any noauth exact all none none
	#
	# the following line is relevant for Quagga
	#
	smuxpeer .1.3.6.1.4.1.3317.1.2.5 quagga_ospfd

/etc/quagga/ospf:
	! ... the rest of ospfd.conf has been omitted for clarity ...
	!
	smux peer .1.3.6.1.4.1.3317.1.2.5 quagga_ospfd
	!
@end example

After restarting snmpd and quagga, a successful connection can be verified in
the syslog and by querying the SNMP daemon:

@example
snmpd[12300]: [smux_accept] accepted fd 12 from 127.0.0.1:36255 
snmpd[12300]: accepted smux peer: \
	oid GNOME-PRODUCT-ZEBRA-MIB::ospfd, quagga-0.96.5

# snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1
OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109
@end example

Be warned that the current version (5.1.1) of the Net-SNMP daemon writes a line
for every SNMP connect to the syslog which can lead to enormous log file sizes.
If that is a problem you should consider to patch snmpd and comment out the
troublesome @code{snmp_log()} line in the function
@code{netsnmp_agent_check_packet()} in @code{agent/snmp_agent.c}.

@node MIB and command reference
@section MIB and command reference

The following OID numbers are used for the interprocess communication of snmpd and
the Quagga daemons. Sadly, SNMP has not been implemented in all daemons yet.
@example
            (OIDs below .iso.org.dod.internet.private.enterprises)
zebra	.1.3.6.1.4.1.3317.1.2.1 .gnome.gnomeProducts.zebra.zserv
bgpd	.1.3.6.1.4.1.3317.1.2.2 .gnome.gnomeProducts.zebra.bgpd
ripd	.1.3.6.1.4.1.3317.1.2.3 .gnome.gnomeProducts.zebra.ripd
ospfd	.1.3.6.1.4.1.3317.1.2.5 .gnome.gnomeProducts.zebra.ospfd
ospf6d	.1.3.6.1.4.1.3317.1.2.6 .gnome.gnomeProducts.zebra.ospf6d
@end example

The following OID numbers are used for querying the SNMP daemon by a client:
@example
zebra	.1.3.6.1.2.1.4.24   .iso.org.dot.internet.mgmt.mib-2.ip.ipForward
ospfd	.1.3.6.1.2.1.14	    .iso.org.dot.internet.mgmt.mib-2.ospf
bgpd	.1.3.6.1.2.1.15	    .iso.org.dot.internet.mgmt.mib-2.bgp 
ripd	.1.3.6.1.2.1.23	    .iso.org.dot.internet.mgmt.mib-2.rip2
ospf6d	.1.3.6.1.3.102	    .iso.org.dod.internet.experimental.ospfv3
@end example

The following syntax is understood by the Quagga daemons for configuring SNMP:
@deffn {Command} {smux peer @var{oid}} {}
@deffnx {Command} {no smux peer @var{oid}} {}
@end deffn

@deffn {Command} {smux peer @var{oid} @var{password}} {}
@deffnx {Command} {no smux peer @var{oid} @var{password}} {}
@end deffn