SNMP Agent

Latest revision as of 13:28, 4 November 2013

This module provides SNMP support for YATE. It handles SNMP requests for OIDs defined in the NULL-TEAM-MIB and YATE-MIB definitions files (found in the YATE source directory in the share/data folder).

This module can handle on its own SNMP requests directly or it can be used with Net-SNMP by having the NULL-TEAM OIDs proxied by the Net-SNMP server to YATE.

There are 2 ways in which you can run the YATE SNMP agent:

• you can set it to listen on port 161, but please notice that it only handle YATE OIDs and cannot give system information.
• you can run it in parallel with Net-SNMP by configuring the YATE SNMP module to listen on another port and by:
  • either configuring the Net-SNMP server to proxy all YATE SNMP requests to the port where the module is listening
  • or by directing all requests to the configured listening port set to the module.

IMPORTANT: The monitoring module must be loaded and configured as it provides the actual data for the answers. If the module is not loaded ysnmpagent will return 2 hardcoded values: yateMIBRevision and version. Supplementary, the cpuload module is needed for the status.engine.cpuLoad values.

[edit] Configuration

This module uses for configuration ysnmpagent.conf.

[edit] Configuring the agent

In the file ysnmpagent.conf, in section [general], configure the listening port

       ; port on which the module listens for SNMP messages. Defaults to 161.
	port=16001

If you're not running YATE as root, you should set a port greater than 1024. Also you might change the port in case you have another server running on port 161 (like Net-SNNMP).

• SNMP v2c

For using SNMP v2c, in section [snmp_v2], the community strings must be set:

       [snmp_v2]
	; SNMPv2 configuration

	; read only access community string
	ro_community=testsnmp
	; read write access community string
	rw_community=testwrite
	; read create access community string
	rc_community=testcreate

• SNMP v3

For using SNMP v3, first you must set the data for generating the snmpEngineID in section [snmp_v3] of ysnmpagent.conf:

	[snmp_v3]
	; SNMPv3 configuration

	; format for generating the snmpEngineID
	; values are
	;	1 		= IPv4 address format,
	;	2		= IPv6 address format,
	;	3		= MAC address format,
	;	4		= TEXT format,
	;	5		= OCTETS format,
	;	128 		= ENTERPRISE specific format
	; Defaults to 4 (TEXT)
	;engine_format=4

	; information for generating the snmpEngineID. Must correspond to the format set
	; (i.e. if engine_format=1, engine_info must be a IPv4 address)
	; NOTE! IPv6 address must not use the IPv6 short format. Mandatory.
	; NOTE! OCTETS format must be a hexified string
	engine_info=

Because the snmpEngineID for YATE is generated from parameters set in this section, the generated value for the engine ID will be found in the snmp_data.conf file after YATE has started or has run at least one time.

Running SNMP v3 requires a section defining a SNMP v3 user:

	[userV3]
	; Configure a section for a SNMPv3 user. The name of the user is the name of
	; the section.
 	; To allow SNMPv3 interrogation, at least one SNMPv3 user must be configured 
 
 	; authentication pass phrase. If it is not set, authentication will not be required
 	;auth_password=
 
 	; authentication method ( MD5 | SHA1 ) in case it is used.
 	;auth_protocol=MD5
 
 	; privacy pass phrase. If it is not set, encryption will not be required
 	;priv_password=
  
	; privacy encryption method ( DES | AES). Default is DES.
  	;priv_protocol=DES
 
 	; user access level. Mandatory. Acceptable values are: readonly, readwrite, readcreate.
  	;access=

[edit] Configuring Net-SNMP to proxy SNMP requests to YATE

• Setting up the proxy

To enable the interaction between Net-SNMP and YATE we have to configure Net-SNMP to act as a proxy for the YATE specific OIDs.

For this, we must edit snmpd.conf ( found usually in /etc/snmp) like this:

• SNMP v2c

	proxy -v 2c -c testsnmp 127.0.0.1:16001 .1.3.6.1.4.1.34501

    where:
	- -v 2c specifies the use of SNMPv2c protocol
	- -c testsnmp is the community string used by the agent where the requests are proxied
	- the IP address and port where the agent to which the requests are proxied is
	- the subtree of OIDs to proxy (in this case the NULL-TEAM subtree)

• SNMP v3

	proxy -v 3 -u username -a MD5|SHA -A authPassPhrase -x AES|DES -X privPassPhrase 
	-l authPrivLevel  .1.3.6.1.4.1.34501

     where:
	- -v 3 specifies the use of SNMPv3 protocol
	- -u sets the username used for SNMPv3 agent where the requests are proxied
	- -a MD5|SHA authentication protocol used for the user and -A the authentication
	pass phrase
	- -x AES|DES privacy protocol used for the user and -X the encryption pass phrase
	- -l authPrivLevel : the security level according to the authentication and
	encryption level (noAuthNoPriv|authNoPriv|authPriv)
	- IP:port - the IP address and port where the agent is
	- the subtree of OIDs to proxy

This tells the daemon that all requests comming with an OID belonging in the .1.3.6.1.4.1.34501 subtree (the Null Team tree) should be proxied to localhost port 16001. After modifying the configuration file, the snmpd daemon must be restarted.
Note: snmpd must start with the following command line parameter -Iproxy to ensure that that daemon enables proxying.

• Loading the YATE MIB into Net-SNMP

If you want to load the YATE OIDs into Net-SNMP so that it can translate the OID names the following steps must be taken:

• Copy the NULL-TEAM-MIB file and the YATE-MIB file found int share/data to the directory from where Net-SNMP loads the MIBs (/usr/share/snmp/mibs or ~/.snmp/mibs on Ubuntu or you can find them by running net-snmp-config --default-mibdirs).
• Edit the snmp.conf file of Net-SNMP (/etc/snmp/snmp.conf) and add the following lines:

	mibs +NULL-TEAM-MIB
	mibs +YATE-MIB

[edit] Configuring SNMP traps

• Configuring YATE to send SNMP traps

To configure the module to send traps, in section [traps] of ysnmpagent.conf you should first check that the sending of SNMP traps is enabled and that a remote IP and port have been set:

	[traps]
	; SNMP traps configuration

	;enable or disable all notifications. Defaults to true.
	;enable_traps=true

	; list traps to disable. Must be separated by ','.
	; An entire substree of traps can be disabled by ending the name of the trap
	;with ".*"
	; (e.g. disable the whole database status traps by adding database.*) 
	disable_traps=

	; IP address to which the traps are sent. Defaults to localhost.
	;remote_ip=localhost

	; port for the remote IP. Defaults to 162.
	;remote_port=162

Also you can disable entire subtrees of notifications by listing them in the value of disable_traps= configuration.

• Configuring YATE to send SNMP v2c traps

To send SNMP v2c traps, you must specify in the [traps] section the SNMP protocol version used for sending traps and the community string for the remote SNMP entity which catches the traps:

;SNMP protocol version to use for sending traps (values are SNMPv2c or SNMPv3). ;Defaults to SNMPv2c. ;proto_version=SNMPv2c

; if SNMPv2 is used, set the community string used for the remote SNMP entity. ;Mandatory if SNMPv2c traps are used. community=

Example

	proto_version=SNMPv2c

	; if SNMPv2 is used, set the community string used for the remote SNMP entity
	community=yateSNMP 

• Configuring YATE to send SNMP v3 traps

To send SNMP v3 traps, you must specify in the [traps] section the SNMP protocol version used for sending traps and the SNMP v3 user for the remote SNMP entity which catches the traps:

	;SNMP protocol version to use for sending traps (values are SNMPv2c or SNMPv3).
  	;Defaults to SNMPv2c.
 	;proto_version=SNMPv3
  	
	; if SNMPv3 is used, specify which configured user should be used for sending 
	;traps (there must be a section named like the given value to trap_user)
	; see the example bellow (section [userV3]) for configuring a SNMPv3 user
	; the specified user will not allowed to interrogate this SNMP agent, it will
	;only be used to send traps to the configured traps receiver
	trap_user=

Also you must have a section named like the value set to trap_user=which defines a user for sending the traps.

Example

	;SNMP protocol version to use for sending traps (values are SNMPv2c or SNMPv3)
	proto_version=SNMPv3
	
	; name of user used for sending traps
	trap_user=testuser
	
	[testuser]
 	; authentication encryption method ( MD5 | SHA1 ) 
	auth_protocol=SHA1
	; authentication pass phrase
	auth_password=testuser
	; encryption method ( DES | AES ) 
	priv_protocol=DES
	; encryption pass phrase
	priv_password=testuser

• Configuring Net-SNMP to receive SNMP traps from YATE

• SNMP v2c

To configure Net-SNMP to receive SNMP v2c traps from YATE the following steps must be taken:

• Open snmptrapd.conf (on Ubuntu, you'll find it in /etc/snmp).
• Add in the file the following line:

	authCommunity log,execute,net yateSNMP

where:

• authCommunity is a mandatory token telling the @@snmptrap daemon@@ to authorize the processing of traps with the specified community string
• log,execute,net - specifies the type of processing for the received trap. log will tell @@snmptrapd@@ to log the details of the notification (to sderr, syslog or a file - usually syslog), execute passes the details of the trap to a specified handler program, net tells it to forward the trap to another notification receiver.

The line above will tell to snmptrapd to log (by default to syslog) all SNMP traps coming with the "yateSNMP" community string (this is the community string we set in the SNMPv2c traps configuration example above).

• SNMP v3

To configure Net-SNMP to receive SNMP v3 traps from YATE add the following lines In snmptrapd.conf (on Ubuntu, you'll find it in /etc/snmp)

	createUser -e yateEngineID username MD5 | SHA digestPassPhrase AES | DES
	privPassPhrase
	authuser log username

where:

• yateEngineID should have the value of the snmpEngineID YATE uses. Because the snmpEngineID for YATE is generated from parameters set in the ysnmpagent.conf file, the generated value for the engine ID will be found in the snmp_data.conf file after YATE has started or has run at least one time.
• username should be the username with which the traps are sent
• MD5 | SHA digestPassPhrase should be the method used for digest and the pass phrase used for it
• AES | DES privPassPhrase should be the method used for encryption and the pass phrase used for it

For the SNMP v3 configuration set above for YATE, the snmptrapd.conf should contain the following lines:

 	createUser -e 0x800086c504796174655465737454657874 testuser SHA testuser DES testuser
 	authuser log testuser

where 0x800086c504796174655465737454657874 is the generated snmpEngineId.

If you want to execute a command upon receiving a SNMP trap, you can add a line like this:

	traphandle OID|default COMMAND [ARGS].

If you want to forward it to another destination:

	forward OID|default DESTINATION

Please see Net-SNMP documentation for further details.