NAME

Snmp Server – snmpd

SYNOPSIS

#include <snmp.h>

SNMP server start fucntion. Should be called from separate thread.

snmpd_main(struct snmpd_settings * );

User events functions:

int snmpd_send_trap(char ip_ver, char trap_ver, char trap_type, char* dst_ip, char dst_port, _trap_bind *trap_bind, char trap_bind_cnt, oid* enterprise_id, int enterprise_id_len, char specific_trap_code, char snmpv3_user_number); int snmpd_change_user_config(struct snmpd_new_param *reconfig); int snmpd_ready(); int snmpd_get_auth_key(char user, u_char**key, int *len); int snmpd_get_encrypt_key(char user, u_char**key, int *len);

DESCRIPTION

Simple Network Management Protocol (SNMP) is an Internet-standard protocol for managing devices on IP networks. SNMP operates over protocols such as User Datagram Protocol (UDP), Internet Protocol (IP) and other.

SNMP agent exposes management data on the managed systems as variables. The protocol also permits active management tasks, such as modifying and applying a new configuration through remote modification of these variables. The variables accessible via SNMP are organized in hierarchies. These hierarchies, and other metadata (such as type and description of the variable), are described by Management Information Bases (MIBs).

In typical SNMP uses, one or more administrative computers, called managers, have the task of monitoring or managing a group of hosts or devices on a computer network. Each managed system executes, at all times, a software component called an agent (SNMP Server) which reports information via SNMP to the manager.

MIBs describe the structure of the management data of a device subsystem; they use a hierarchical namespace containing object identifiers (OID). Each OID identifies a variable that can be read or set via SNMP. MIBs use the notation defined by ASN.1.

SNMP Server supports three versions of SNMP protocol:

– SNMPv1;- SNMPv2c;- SNMPv3.

Unison SNMP agent uses different security models for different versions of SNMP protocol.

For SNMPv1 and SNMPv2c Unison SNMP agent uses the Community-based security model. There is a possibility to configurate three different Community groups and set read_community and write_community strings for each group.

For the SNMPv3 Unison SNMP agent uses the User-based security model. There is a possibility to define three different users for the SMNPv3 in Unison SNMP agent. For each user one of the three definite levels of authentication and privacy is set:

– Communication without authentication and privacy (noAuthNoPriv). It is similar to the “Community string” access password, which is transmitted in cleartext and applied in SNMPv1 and SNMPv2c. It is used during the debugging or when SNMP-entities are in protected area.- Communication with authentication and without privacy (AuthNoPriv).- Communication with authentication and privacy (AuthPriv). Not only authentication but cryptographic security of SMNP data. Implementations offered MD5 or SHA for authentication, and DES or AES for encryption.

Unison SNMP agent supports sending of the trap messages. Trap is asynchronous notification from agent to manager. Includes current sysUpTime value, an OID identifying the type of trap and optional variable bindings. Destination addressing for traps is determined in an application-specific manner typically through trap configuration variables in the MIB.

Typical operation for the fat file server involves several steps common in various operating system environments including Linux.

SNMP SERVER INITIALIZATION

	The SNMP Server initialization structure can be found in the file <snmp.h> :

	struct snmpd_settings
	{
		const struct variable *oid_table;
		const struct variable *oid_table_trap;
		
		char 	agent_ip_ver;		// 4 for ipv4, 6 for ipv6
		char 	*trap_community;
		
		char 	*sys_trap_ip;
		uint_16 sys_trap_port;
		char 	sys_trap_enable;
		char 	sys_trap_ver;
		char 	sys_trap_ip_ver;	//default for internal(system) trap
		char 	*our_ip;
		oid 	*entrp;
		int 	entrp_len;
		
		struct community com[3];
		u_short sys_mib_access_level[7];
		
	#if V_3 > 0
		char	*engine_id_data; // max engine_id_data -  32
		struct snmpd_user user[3];
	#endif

		char 	*contact;
		char 	*name;
		char 	*location;
			
	};


	More detailed initialization description is bellow:

	1)Add MIB table
	oid_table – address of User MIB Table (User MIB Table is used in the user application to store variables)

	oid_table_trap – address of Trap MIB Table (Trap MIB Table is used in the user application to store data about traps)


	2)Set the TCP/IP settings of the Unison SNMP:

	agent_ip_ver – TCP/IP version (IPv4 – 4 or IPv6 – 6) which SNMP agent will use

	trap_community – community string for the system trap message.

	3)Set the system trap messages settings

	sys_trap_ip – IP address of the system trap messages receiver

	sys_trap_port – port of the system trap messages receiver

	sys_trap_enable – system trap messages status. 1 – sending of system trap messages are enable;0 – sending of system trap messages are disable 

	sys_trap_ver – version of SNMP protocol by which system trap messages are sending. For the system trap messages it may be only SNMPv1 or SNMPv2c.

	sys_trap_ip_ver – version of TCP/IP protocol by which system trap messages are sending (IPv4 or IPv6)

	our_ip – home IP address. It’s need for the filling SNMP agent IP address in the trap message.

	entrp – enterprise id for the system MIBs

	entrp_len – enterprise id length


	4) Initialize the first community group by the filling the structure.

		struct community{
			char *read_community; //max read_community - 32
			char *write_community;//max write_community - 32
			int active;
		};

	snmpd_init.com[0].read_community – read access community string.

	snmpd_init.com[0]. write_community – write access community string

	snmpd_init.com[0].active – specify the activation status of the SNMP protocol versions for the first community group “0”

	For the snmpd_init.comm.[0].active the following configuration parameters are possible:
			ACTIVE_VERSION_1 – activation only snmpv1 for this group
			ACTIVE_VERSION_2C – activation only snmpv2c for this group
			UNACTIVE_VERSION_1_2C – disable snmpv1 and snmpv2c for this group(for disable this group community)
			ACTIVE_VERSION_1_2C - activate snmpv1 and snmpv2c for this group


	5) Settings for the second and the third community groups are initialized in much the same way

	6) Set the default level access to the group of variables Default MIB table. (Default MIB table is SNMP agent system table according to the RFC1213)
		
		sys_mib_access_level[GROUP_SYSTEM_MIB] =FULL_ACCESS_ALL_VER;
		sys_mib_access_level[GROUP_INTERFACE_MIB] = FULL_ACCESS_ALL_VER;
		sys_mib_access_level[GROUP_IP_MIB] = FULL_ACCESS_V2;
		sys_mib_access_level[GROUP_ICMP_MIB] = FULL_ACCESS_ALL_VER;
		sys_mib_access_level[GROUP_TCP_MIB] = FULL_ACCESS_ALL_VER;
		sys_mib_access_level[GROUP_UDP_MIB] = FULL_ACCESS_V1andV2;
		sys_mib_access_level[GROUP_STATSNMP_MIB] = FULL_ACCESS_V3;

		
	7) Initialize the first SNMPv3 user by filling the structure 
		struct snmpd_user {
			char *login; //max login len  - 32
			char secLevel; 
			char *auth_pass;// max  auth_pass - 32
			char auth_prot;
			char *encrypt_pass;// max encrypt_pass - 32
			char encrypt_prot;
			int active;
			u_char *reload_auth_key;
			u_char *reload_encrypt_key;
			
			/* will filled by snmp agent */
			oid            *authProtocol;
			size_t          authProtocolLen;
			u_char         *authKey;
			size_t          authKeyLen;
			oid            *privProtocol;
			size_t          privProtocolLen;
			u_char         *privKey;
			size_t          privKeyLen;

		};

	snmpd_init.engine_id_data – string for generation Engine Id of the device.
	snmpd_init.user[0].login – login for the first user.
	snmpd_init.user[0].secLevel - Security Level for the first user
		There are three variants of the Security Level:
	SNMP_SEC_LEVEL_NOAUTH		1 – communication without authentication and without encryption. 
	SNMP_SEC_LEVEL_AUTHNOPRIV	2 – communication with authentication and without encryption. 
	SNMP_SEC_LEVEL_AUTHPRIV	3 - communication with authentication and with encryption.

	snmpd_init.user[0].auth_pass – password for the first user authentication. (it is recommended to use minimum 8 symbols for the password)

	snmpd_init.user[0].auth_prot – authentication protocol (SNMPD_SHA or SNMPD_MD5)

	snmpd_init.user[0].encrypt_pass – password for the first user data encryption. (it is recommended to use minimum 8 symbols for the password)

	snmpd_init.user[0].encrypt_prot – protocol for data encryption ( SNMPD_DES or SNMPD_AES)

	snmpd_init.user[0].active – first user status. For the SNMP agent first user is active if user[0] = 1 and not active if user[0] = 0

	snmpd_init.user[0].reload_auth_key – localized authentication key initialization
	if reload_auth_key is NULL then localized authentication key is generated by SNMP Server.

	snmpd_init.user[0].reload_encrypt_key – localized encryption key initialization
	if reload_encrypt_key is NULL then localized encryption key is generated by SNMP Server.

	
	8) Settings for the second and the third SNMPv3 users are initialized in much the same way

USER EVENTS FUNCTIONS

	int snmpd_change_user_config(struct snmpd_new_param *reconfig);
	For the SNMP agent settings reconfiguration API function int change_user_config(struct snmpd_new_param *reconfig) is used:

		struct snmpd_new_param {
			
			int_8 num_community;
			int_8 active_com;
			char 	*read_community;
			char 	*write_community;
			char 	*trap_community;
			int_8 number_user_v3;
			int_8 active_user;
			char *login;
			char secLevel;
			char* auth_pass;
			char auth_prot;
			char *encrypt_pass;
			char encrypt_prot;
			
		};	

	num_community – community group number (from 0 to 2) 

	active_com– current community group status
	(#define UNACTIVE_VERSION_1_2C 0
	#define ACTIVE_VERSION_1 1
	#define ACTIVE_VERSION_2C 2
	#define ACTIVE_VERSION_1_2C 3)

	read_community – read access community string for community group

	write_community – write access community string for community group

	trap_community – system trap community string

	number_user_v3 – SNMPv3 user number (from 0 to 2)

	active_user – current user status (1\0 - enable\disable)

	login – new user login 

	secLevel – user security level
	(#define SNMP_SEC_LEVEL_NOAUTH		1
	#define SNMP_SEC_LEVEL_AUTHNOPRIV	2
	#define SNMP_SEC_LEVEL_AUTHPRIV		3)

	auth_pass – new password for authentication 

	auth_prot – authentication protocol (SNMPD_SHA or SNMPD_MD5)

	encrypt_pass – encryption password

	encrypt_prot – encryption protocol ( SNMPD_DES or SNMPD_AES)


	To check the reconfiguration status the API function snmp_ready can be used.



	int snmpd_ready(); 
	Function checks the SNMP agent initialization status. Returns 1 if initialization is completed and 0 if not completed.

	int snmpd_get_auth_key(char user, u_char**key, int *len);
	Returns 0 if success and (-1) if error

	user – SNMPv3user number
	key – localized authentication key ( method is defined in RFC2274)
	len – length of the key


	int snmpd_get_encrypt_key(char user, u_char**key, int *len);
	Returns 0 if success and (-1) if error

	user – SNMPv3user number
	key – localized privacy key ( method is defined in RFC2274)
	len – length of the key

RETURN VALUES

	In case of successful start up pthread_create will return 0 value.

EXAMPLE

This partial example shows the snmpd creation.

	#include <snmp.h>

	/*************************************************************************
	 *  Subroutine  : snmp_shell
	 *  Purpose     : Task shell for starting device specific SNMP
	 ************************************************************************/
	THREAD snmp_shell()
	{
	int str_len;

	memset(&snmpd_init, 0, sizeof(struct snmpd_settings));
	
	snmpd_init.oid_table 		= oid_table;
	snmpd_init.oid_table_trap	= oid_trap_table;

	snmpd_init.com[0].read_community = malloc(MAX_SIZE_COMMUNITY);
	
	if(snmpd_init.com[0].read_community == NULL){
		return;
	}
	memset(snmpd_init.com[0].read_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 

	snmpd_init.com[1].read_community = malloc(MAX_SIZE_COMMUNITY);

	if(snmpd_init.com[1].read_community == NULL){
		return;
	}
	memset(snmpd_init.com[1].read_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 

	snmpd_init.com[2].read_community = malloc(MAX_SIZE_COMMUNITY);

	if(snmpd_init.com[2].read_community == NULL){
		return;
	}
	memset(snmpd_init.com[2].read_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 


	snmpd_init.com[0].write_community = malloc(MAX_SIZE_COMMUNITY);

	if(snmpd_init.com[0].write_community == NULL){
		return;
	}
	memset(snmpd_init.com[0].write_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 


	snmpd_init.com[1].write_community = malloc(MAX_SIZE_COMMUNITY);

	if(snmpd_init.com[1].write_community == NULL){
		return;
	}
	memset(snmpd_init.com[1].write_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 
	

	snmpd_init.com[2].write_community = malloc(MAX_SIZE_COMMUNITY);

	if(snmpd_init.com[2].write_community == NULL){
		return;
	}
	memset(snmpd_init.com[2].write_community, 0, sizeof(MAX_SIZE_COMMUNITY)); 
	

	strcpy(snmpd_init.com[0].read_community, "public");
	strcpy(snmpd_init.com[0].write_community, "private");
	snmpd_init.com[0].active = ACTIVE_VERSION_1_2C;

	
	strcpy(snmpd_init.com[1].read_community, "xxx");
	strcpy(snmpd_init.com[1].write_community, "qqq");
	snmpd_init.com[1].active = UNACTIVE_VERSION_1_2C;
	
	strcpy(snmpd_init.com[2].read_community, "yyy");
	strcpy(snmpd_init.com[2].write_community, "xxx");
	snmpd_init.com[2].active = ACTIVE_VERSION_1_2C;
	
	snmpd_init.agent_ip_ver 		= SNMPD_IP_VER;
	snmpd_init.trap_community 	= "public";

	//trap
	snmpd_init.sys_trap_ip = SNMPD_TRAP_IP;
	snmpd_init.sys_trap_port = SNMPD_PORT_TRAP;
	snmpd_init.sys_trap_enable 	= SNMPD_ACTIVATE_SYSTEM_TRAPS;
	snmpd_init.sys_trap_ver 	= SNMPD_TRAP_VERSION;
	snmpd_init.sys_trap_ip_ver = TRAP_IP_VER;
	snmpd_init.our_ip			= tcpinit.IPv4.IP_address;
	snmpd_init.entrp 			= enterprise_id;
	snmpd_init.entrp_len 		= enterprise_id_len;



#if V_3 > 0
	snmpd_init.engine_id_data = malloc(MAX_SIZE_ENGINE_ID);

	if(snmpd_init.engine_id_data == NULL){
		return;
	}
	memset(snmpd_init.engine_id_data, 0, sizeof(MAX_SIZE_COMMUNITY)); 
	
	strcpy(snmpd_init.engine_id_data,"test_id_data");
	
	
	/*first user*/
	snmpd_init.user[0].login = malloc(MAX_SIZE_USER_LOGIN);
	if(snmpd_init.user[0].login == NULL){
		return;
	}

	memset(snmpd_init.user[0].login, 0, sizeof(MAX_SIZE_USER_LOGIN)); 
	strcpy(snmpd_init.user[0].login, "user0");
	snmpd_init.user[0].secLevel = SNMP_SEC_LEVEL_AUTHPRIV;


	snmpd_init.user[0].auth_pass = malloc(MAX_SIZE_AUTH_PASS);

	if(snmpd_init.user[0].auth_pass == NULL){
		return;
	}
	memset(snmpd_init.user[0].auth_pass, 0, sizeof(MAX_SIZE_AUTH_PASS)); 
	strcpy(snmpd_init.user[0].auth_pass, "passphrase");
	snmpd_init.user[0].auth_prot = SNMPD_SHA;

	snmpd_init.user[0].encrypt_pass = malloc(MAX_SIZE_ECNR_PASS);

	if(snmpd_init.user[0].encrypt_pass == NULL){
		return;
	}
	memset(snmpd_init.user[0].encrypt_pass, 0, sizeof(MAX_SIZE_ECNR_PASS)); 

	strcpy(snmpd_init.user[0].encrypt_pass,"passphrase1");
	snmpd_init.user[0].encrypt_prot = SNMPD_AES;
	snmpd_init.user[0].active = ACTIVE_OBJ;
	snmpd_init.user[0].reload_auth_key = NULL;
	snmpd_init.user[0].reload_encrypt_key = NULL;

.............................................


	/*set security level for internal system MIB, level set for group of MIB*/

	snmpd_init.sys_mib_access_level[GROUP_SYSTEM_MIB] =FULL_ACCESS_ALL_VER;
	snmpd_init.sys_mib_access_level[GROUP_INTERFACE_MIB] = FULL_ACCESS_ALL_VER;
	snmpd_init.sys_mib_access_level[GROUP_IP_MIB] = FULL_ACCESS_V2;
	snmpd_init.sys_mib_access_level[GROUP_ICMP_MIB] = FULL_ACCESS_ALL_VER;
	snmpd_init.sys_mib_access_level[GROUP_TCP_MIB] = FULL_ACCESS_ALL_VER;
	snmpd_init.sys_mib_access_level[GROUP_UDP_MIB] = FULL_ACCESS_V1andV2;
	snmpd_init.sys_mib_access_level[GROUP_STATSNMP_MIB] = FULL_ACCESS_V3;

#endif



	str_len = strlen("The textual identification of the person");
	snmpd_init.contact = malloc(str_len+1);
	if (!snmpd_init.contact)
		return NULL;
	strcpy(snmpd_init.contact, "The textual identification of the person");

	str_len = strlen( "An administratively-assigned name for this managed node");
	snmpd_init.name = malloc(str_len+1);
	if (!snmpd_init.name)
		return NULL;
	strcpy(snmpd_init.name, "An administratively-assigned name for this managed node");

	str_len = strlen( "An administratively-assigned name for this managed node");
	snmpd_init.location = malloc(str_len+1);
	if (!snmpd_init.location)
		return NULL;
	strcpy(snmpd_init.location, "The physical location of this node");


	snmpd_main(&snmpd_init);
	return 0; //just to avoid warning
	}


	Example shows the snmpd reconfiguration 

	#if RECONFIG_USER > 0 		
		reconfig.num_community = 0;
		reconfig.active_com = ACTIVE_VERSION_1_2C;
		reconfig.read_community = "newpass";
		reconfig.write_community = "newwritepass";
		reconfig.trap_community = "public";
		reconfig.number_user_v3 = 1;
		reconfig.active_user = ACTIVE_OBJ;
		reconfig.login = "newuser";
		reconfig.secLevel = SNMP_SEC_LEVEL_AUTHPRIV;
		reconfig.auth_pass ="zxcvbnmz";
		reconfig.auth_prot = SNMPD_SHA;
		reconfig.encrypt_pass = "qwertyuiop";
		reconfig.encrypt_prot = SNMPD_AES;
		
		change_user_config(&reconfig);
		xprintf("change_user_config load\n");

	#endif //RECONFIG_USER
			

	Example shows the initialization status checking
	ret_ready = snmp_ready();
			
			if (ret_ready){
			........
			........
			

	Example shows how to get  users localize key for authentication and encryption protocol

	snmp_get_auth_key(0, &out_key, &out_len);

	snmp_get_encrypt_key(0, &out_key, &out_len);

NOTES

There is a demo available for the Unison and DSPnano Snmp Server which can be found in installdir/demos.

SEE ALSO

IPv4 only server, IPv4/IPv6 server,