This chapter contains a description of various issues related to installation, setup, and usage of the NetX Duo SNMP agent component.
SNMP Agent for NetX Duo is available at https://github.com/eclipse-threadx/netxduo. The package includes four source files, one include file, and a PDF file that contains this document, as follows:
In order to use NetX Duo SNMP, the entire distribution mentioned previously should be copied to the same directory where NetX Duo is installed. For example, if NetX Duo is installed in the directory “\threadx\arm7\green” then the nxd_snmp.h, nxd_snmp.c, nx_md5.c, nx_sha.c and nx_des.c files should be copied into this directory.
The application must have nxd_snmp.c, nx_md5.c, nx_sha.c, and nx_des.c in the build project. The application code must also include nxd_snmp.h after it includes nx_api.h to be able to invoke SNMP services. These files must be compiled in the same manner as other application files and its object form must be linked to the NetX Duo library. This is all that is required to use NetX Duo SNMP.
Note: If NX_SNMP_NO_SECURITY is specified in the build process, the nx_md5.c, nx_sha.c, and nx_des.c files are not needed.
Note: That since NetX Duo SNMP utilizes UDP services, UDP must be enabled with the nx_udp_enable call prior to using SNMP.
An example of how to use NetX Duo SNMP Agent is described below. In this example, the SNMP include file nxd_snmp.h is brought in at line 6. The header file that defines the MIB database elements, demo_snmp_helper.h, is brought in at line 8. The MIB is defined starting on line 32. Next, the SNMP Agent is created in “tx_application_define” at line 129. Note that the SNMP Agent control block “my_agent” was defined as a global variable at line 18 previously. If IPv6 is enabled, the IPv6 addresses are registered with the IP instance in lines 166-223. SNMP Agent is started at line 229. SNMP object callback definitions for SNMP manager GET, GETNEXT and SET requests, as well as username and MIB update requests, are processed starting at line 250. For this example, no authenticate is performed.
Note: The MIB2 table shown below is simply an example. The application may use a different MIB and include it in separate files, as well as define GET, GETNEXT, or SET processing as per their application requirements.
/* This is a small demo of the NetX SNMP Agent on the high-performance NetX TCP/IP
stack. This demo relies on ThreadX and NetX Duo to show simple SNMP
GET/GETNEXT/SET requests on MIB-2 objects. */
#include "tx_api.h"
#include "nx_api.h"
#include "nxd_snmp.h"
#include "demo_snmp_helper.h"
#define DEMO_STACK_SIZE 4096
#define AGENT_PRIMARY_ADDRESS IP_ADDRESS(192, 2, 2, 66)
/* Define the ThreadX and NetX object control blocks... */
TX_THREAD thread_0;
NX_PACKET_POOL pool_0;
NX_IP ip_0;
NX_SNMP_AGENT my_agent;
/* Indicate if using IPv6 to communicate with SNMP servers. Note that
IPv6 must be enabled in the NetX Duo library first. Further, IPv6
and ICMPv6 services are enabled before starting the SNMP agent. */
#define USE_IPV6
/* Define authentication and privacy keys. */
#ifdef AUTHENTICATION_REQUIRED
NX_SNMP_SECURITY_KEY my_authentication_key;
#endif
#ifdef PRIVACY_REQUIRED
NX_SNMP_SECURITY_KEY my_privacy_key;
#endif
/* Define an error counter variable. */
UINT error_counter = 0;
/* This binds a secondary interfaces to the primary IP network interface
if SNMP is required for required for that interface. */
/* #define MULTI_HOMED_DEVICE */
/* Define function prototypes. A generic ram driver is used in this demo. However
to properly run an SNMP agent demo, a real driver should be substituted. */
VOID thread_agent_entry(ULONG thread_input);
VOID _nx_ram_network_driver(NX_IP_DRIVER *driver_req_ptr);
UINT mib2_get_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data);
UINT mib2_getnext_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data);
UINT mib2_set_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data);
UINT mib2_username_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *username);
VOID mib2_variable_update(NX_IP *ip_ptr, NX_SNMP_AGENT *agent_ptr);
UCHAR context_engine_id[] = {0x80, 0x00, 0x0d, 0xfe, 0x03, 0x00, 0x11, 0x23, 0x23,
0x44, 0x55};
UINT context_engine_size = 11;
UCHAR context_name[] = {0x69, 0x6e, 0x69, 0x74, 0x69, 0x61, 0x6c};
UINT context_name_size = 7;
/* Define main entry point. */
int main()
{
/* Enter the ThreadX kernel. */
tx_kernel_enter();
}
/* Define what the initial system looks like. */
void tx_application_define(void *first_unused_memory)
{
UCHAR *pointer;
UINT status;
/* Setup the working pointer. */
pointer = (UCHAR *) first_unused_memory;
status = tx_thread_create(&thread_0, "agent thread", thread_agent_entry, 0,
pointer, DEMO_STACK_SIZE,
4, 4, TX_NO_TIME_SLICE, TX_AUTO_START);
if (status != NX_SUCCESS)
{
return;
}
pointer = pointer + DEMO_STACK_SIZE;
/* Initialize the NetX system. */
nx_system_initialize();
/* Create packet pool. */
status = nx_packet_pool_create(&pool_0, "NetX Packet Pool 0", 2048,
pointer, 20000);
if (status != NX_SUCCESS)
{
return;
}
pointer = pointer + 20000;
/* Create an IP instance. */
status = nx_ip_create(&ip_0, "SNMP Agent IP Instance", AGENT_PRIMARY_ADDRESS,
0xFFFFFF00UL, &pool_0, _nx_ram_network_driver,
pointer, 4096, 1);
if (status != NX_SUCCESS)
{
return;
}
pointer = pointer + 4096;
/* Enable ARP and supply ARP cache memory for IP Instance 0. */
nx_arp_enable(&ip_0, (void *) pointer, 1024);
pointer = pointer + 1024;
/* Enable UPD processing for IP instance. */
nx_udp_enable(&ip_0);
/* Enable ICMP for ping. */
nx_icmp_enable(&ip_0);
/* Create an SNMP agent instance. */
status = nx_snmp_agent_create(&my_agent, "SNMP Agent", &ip_0, pointer, 4096,
&pool_0,
mib2_username_processing, mib2_get_processing,
mib2_getnext_processing,
mib2_set_processing);
if (status != NX_SUCCESS)
{
return;
}
pointer = pointer + 4096;
status = nx_snmp_agent_context_engine_set(&my_agent, context_engine_id,
context_engine_size);
if (status != NX_SUCCESS)
{
error_counter++;
}
return;
}
VOID thread_agent_entry(ULONG thread_input)
{
#ifdef USE_IPV6
UINT iface_index, address_index;
UINT status;
NXD_ADDRESS agent_ipv6_address;
#endif
/* Allow NetX time to get initialized. */
tx_thread_sleep(100);
/* If using IPv6, enable IPv6 and ICMPv6 services and get IPv6 addresses
registered with NetX Duo. */
#ifdef USE_IPV6
/* Enable IPv6 on the IP instance. */
status = nxd_ipv6_enable(&ip_0);
/* Check for enable errors. */
if (status)
{
error_counter++;
return;
}
/* Enable ICMPv6 on the IP instance. */
status = nxd_icmp_enable(&ip_0);
/* Check for enable errors. */
if (status)
{
error_counter++;
return;
}
agent_ipv6_address.nxd_ip_address.v6[3] = 0x101;
agent_ipv6_address.nxd_ip_address.v6[2] = 0x0;
agent_ipv6_address.nxd_ip_address.v6[1] = 0x0000f101;
agent_ipv6_address.nxd_ip_address.v6[0] = 0x20010db8;
agent_ipv6_address.nxd_ip_version = NX_IP_VERSION_V6;
/* Set the primary interface for our DNS IPv6 addresses. */
iface_index = 0;
/* This assumes we are using the primary network interface (index 0). */
status = nxd_ipv6_address_set(&ip_0, iface_index, NX_NULL, 10, &address_index);
/* Check for link local address set error. */
if (status)
{
error_counter++;
return;
}
/* Set the host global IP address. We are assuming a 64
bit prefix here but this can be any value (< 128). */
status = nxd_ipv6_address_set(&ip_0, iface_index, &agent_ipv6_address, 64,
&address_index);
/* Check for global address set error. */
if (status)
{
error_counter++;
return;
}
/* Wait while NetX Duo validates the link local and global address. */
tx_thread_sleep(500);
#endif
#ifdef AUTHENTICATION_REQUIRED
/* Create an authentication key. */
nx_snmp_agent_md5_key_create(&my_agent, "authpassword", &my_authentication_key);
/* Use the authentication key. */
nx_snmp_agent_authenticate_key_use(&my_agent, &my_authentication_key);
#endif
#ifdef PRIVACY_REQUIRED
/* Create a privacy key. */
nx_snmp_agent_md5_key_create(&my_agent, "privpassword", &my_privacy_key);
/* Use the privacy key. */
nx_snmp_agent_privacy_key_use(&my_agent, &my_privacy_key);
#endif
/* Start the SNMP instance. */
nx_snmp_agent_start(&my_agent);
}
/* Define the application's GET processing routine. */
UINT mib2_get_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data)
{
UINT i;
UINT status;
printf("SNMP Manager GET Request For: %s", object_requested);
/* Loop through the sample MIB to see if we have information for the supplied
variable. */
i = 0;
status = NX_SNMP_ERROR;
while (mib2_mib[i].object_name)
{
/* See if we have found the matching entry. */
status = nx_snmp_object_compare(object_requested, mib2_mib[i].object_name);
/* Was it found? */
if (status == NX_SUCCESS)
{
/* Yes it was found. */
break;
}
/* Move to the next index. */
i++;
}
/* Determine if a not found condition is present. */
if (status != NX_SUCCESS)
{
printf(" NO SUCH NAME!\n");
/* The object was not found - return an error. */
return(NX_SNMP_ERROR_NOSUCHNAME);
}
/* Determine if the entry has a get function. */
if (mib2_mib[i].object_get_callback)
{
/* Yes, call the get function. */
status = (mib2_mib[i].object_get_callback)(mib2_mib[i].object_value_ptr,
object_data);
}
else
{
printf(" NO GET FUNCTION!");
/* No get function, return no access. */
status = NX_SNMP_ERROR_NOACCESS;
}
printf("\n");
/* Return the status. */
return(status);
}
/* Define the application's GETNEXT processing routine. */
UINT mib2_getnext_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data)
{
UINT i;
UINT status;
printf("SNMP Manager GETNEXT Request For: %s", object_requested);
/* Loop through the sample MIB to see if we have information for the supplied
variable. */
i = 0;
status = NX_SNMP_ERROR;
while (mib2_mib[i].object_name)
{
/* See if we have found the next entry. */
status = nx_snmp_object_compare(object_requested, mib2_mib[i].object_name);
/* Is the next entry the mib greater? */
if (status == NX_SNMP_NEXT_ENTRY)
{
/* Yes it was found. */
break;
}
/* Move to the next index. */
i++;
}
/* Determine if a not found condition is present. */
if (status != NX_SNMP_NEXT_ENTRY)
{
printf(" NO SUCH NAME!\n");
/* The object was not found - return an error. */
return(NX_SNMP_ERROR_NOSUCHNAME);
}
/* Copy the new name into the object. */
nx_snmp_object_copy(mib2_mib[i].object_name, object_requested);
printf(" Next Name is: %s", object_requested);
/* Determine if the entry has a get function. */
if (mib2_mib[i].object_get_callback)
{
/* Yes, call the get function. */
status = (mib2_mib[i].object_get_callback)(mib2_mib[i].object_value_ptr,
object_data);
/* Determine if the object data indicates an end-of-mib condition. */
if (object_data -> nx_snmp_object_data_type == NX_SNMP_END_OF_MIB_VIEW)
{
/* Copy the name supplied in the mib table. */
nx_snmp_object_copy(mib2_mib[i].object_value_ptr, object_requested);
}
}
else
{
printf(" NO GET FUNCTION!");
/* No get function, return no access. */
status = NX_SNMP_ERROR_NOACCESS;
}
printf("\n");
/* Return the status. */
return(status);
}
/* Define the application's SET processing routine. */
UINT mib2_set_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *object_requested,
NX_SNMP_OBJECT_DATA *object_data)
{
UINT i;
UINT status;
printf("SNMP Manager SET Request For: %s", object_requested);
/* Loop through the sample MIB to see if we have information for the supplied variable. */
i = 0;
status = NX_SNMP_ERROR;
while (mib2_mib[i].object_name)
{
/* See if we have found the matching entry. */
status = nx_snmp_object_compare(object_requested, mib2_mib[i].object_name);
/* Was it found? */
if (status == NX_SUCCESS)
{
/* Yes it was found. */
break;
}
/* Move to the next index. */
i++;
}
/* Determine if a not found condition is present. */
if (status != NX_SUCCESS)
{
printf(" NO SUCH NAME!\n");
/* The object was not found - return an error. */
return(NX_SNMP_ERROR_NOSUCHNAME);
}
/* Determine if the entry has a set function. */
if (mib2_mib[i].object_set_callback)
{
/* Yes, call the set function. */
status = (mib2_mib[i].object_set_callback)(mib2_mib[i].object_value_ptr,
object_data);
}
else
{
printf(" NO SET FUNCTION!");
/* No get function, return no access. */
status = NX_SNMP_ERROR_NOACCESS;
}
printf("\n");
/* Return the status. */
return(status);
}
/* Define the application's authentication routine. */
UINT mib2_username_processing(NX_SNMP_AGENT *agent_ptr, UCHAR *username)
{
printf("Username is: %s\n", username);
/* Update MIB-2 objects. In this example, it is only the SNMP objects. */
mib2_variable_update(&ip_0, &my_agent);
/* No authentication is done, just return success! */
return(NX_SUCCESS);
}
/* Define the application's update routine. */
VOID mib2_variable_update(NX_IP *ip_ptr, NX_SNMP_AGENT *agent_ptr)
{
/* Update the snmp parameters. */
snmpInPkts = agent_ptr -> nx_snmp_agent_packets_received;
snmpOutPkts = agent_ptr -> nx_snmp_agent_packets_sent;
snmpInBadVersions = agent_ptr -> nx_snmp_agent_invalid_version;
snmpInBadCommunityNames = agent_ptr -> nx_snmp_agent_authentication_errors;
snmpInBadCommunityUsers = agent_ptr -> nx_snmp_agent_username_errors;
snmpInASNParseErrs = agent_ptr -> nx_snmp_agent_internal_errors;
snmpInTotalReqVars = agent_ptr -> nx_snmp_agent_total_get_variables;
snmpInTotalSetVars = agent_ptr -> nx_snmp_agent_total_set_variables;
snmpInGetRequests = agent_ptr -> nx_snmp_agent_get_requests;
snmpInGetNexts = agent_ptr -> nx_snmp_agent_getnext_requests;
snmpInSetRequests = agent_ptr -> nx_snmp_agent_set_requests;
snmpOutTooBigs = agent_ptr -> nx_snmp_agent_too_big_errors;
snmpOutNoSuchNames = agent_ptr -> nx_snmp_agent_no_such_name_errors;
snmpOutBadValues = agent_ptr -> nx_snmp_agent_bad_value_errors;
snmpOutGenErrs = agent_ptr -> nx_snmp_agent_general_errors;
snmpOutTraps = agent_ptr -> nx_snmp_agent_traps_sent;
}
There are several configuration options for building SNMP for NetX Duo. Following is a list of all options, where each is described in detail:
| Define | Meaning |
|---|---|
| NX_SNMP_AGENT_PRIORITY | The priority of the SNMP AGENT thread. By default, this value is defined as 16 to specify priority 16. |
| NX_SNMP_TYPE_OF_SERVICE | Type of service required for the SNMP UDP responses. By default, this value is defined as NX_IP_NORMAL to indicate normal IP packet service. This define can be set by the application prior to inclusion of nxd_snmp.h. |
| NX_SNMP_FRAGMENT_OPTION | Fragment enable for SNMP UDP requests. By default, this value is NX_DONT_FRAGMENT to disable SNMP UDP fragmenting. This define can be set by the application prior to inclusion of nxd_snmp.h. |
| NX_SNMP_TIME_TO_LIVE | Specifies the time to live before it expires. The default value is set to 0x80, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_AGENT_TIMEOUT | Specifies the number of ThreadX ticks that internal services will suspend for. The default value is set to 100, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MAX_OCTET_STRING | Specifies the maximum number of bytes allowed in an octet string in the SNMP Agent. The default value is set to 255, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MAX_CONTEXT_STRING | Specifies the maximum number of bytes for a context engine string in the SNMP Agent. The default value is set to 32, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MAX_USER_NAME | Specifies the maximum number of bytes in a username (including community strings). The default value is set to 64, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MAX_SECURITY_KEY | Specifies the number of bytes allowed in a security key string. The default value is set to 64, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_PACKET_SIZE | Specifies the minimum size of the packets in the pool specified at SNMP Agent creation. The minimum size is needed to ensure the complete SNMP payload can be contained in one packet. The default value is set to 560, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_AGENT_PORT | Specifies the UDP port to field SNMP Manager requests on. The default port is UDP port 161, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MANAGER_TRAP_PORT | Specifies the UDP port to send SNMP Agent trap requests to. The default port is UDP port 162, but can be redefined prior to inclusion of nxd_snmp.h. |
| NX_SNMP_MAX_TRAP_NAME | Specifies the size of the array to hold the username sent with trap messages. The default value is 64. |
| NX_SNMP_MAX_TRAP_KEY | Specifies the size of the authentication and privacy keys for trap messages. The default value is 64. |
| NX_SNMP_TIME_INTERVAL | This determines the sleep interval in timer ticks taken by the SNMP thread task between processing received SNMP packets. The default value is 100. During this sleep interval the host application has access to SNMP API services. |
| NX_SNMP_DISABLE_V1 | Defined, this removes all the SNMP Version 1 processing in nxd_snmp.c. By default this is not defined. |
| NX_SNMP_DISABLE_V2 | Defined, this removes all the SNMP Version 2 processing in nxd_snmp.c. By default this is not defined. |
| NX_SNMP_DISABLE_V3 | Defined, this removes all the SNMPv3 processing in nxd_snmp.c. By default this is not defined. |