Configuring SNMPv3 Agents

• Overview

• Security Levels in SNMPv3

• Default Users of SNMPv3 Agents

• Developing a Sample V3 Agent

• Testing the SNMPv3 Agent with Default Users

• Adding More Users for v3 Agents (USM)

• Enabling Authorization in V3 Using VACM

• Using USM without VACM

• Authenticating Requests from v1/v2c Managers (Co-existence Support).

• Making the Agent Strictly SNMPv3

• Sending Notifications

• To v3 Managers

• To v1/v2c Managers

Overview

The version 3 of Simple Network Management Protocol addresses some of the long pending issues related to the large scale deployment of SNMP. Due to lack of security in using SNMP, system and network administrators were using other means, such as telnet, ASCII, etc. for configuration, accounting, and fault management. The primary goal of SNMP version 3 (SNMPv3) is to define a secure version of the SNMP. SNMPv3 also facilitates remote configuration of the SNMP entities, which make remote administration of SNMP entities a much simpler task. WebNMS has implemented SNMPv3 as defined from RFC3411 to RFC3415 (Obsoletes RFC2570 to RFC2575), RFC 3584 (Obsoletes RFC 2576) and RFC 3826 (AES cipher algorithm in the SNMP USM MIB)

Security Levels in SNMPv3

As explained earlier, SNMP version 3 (SNMPv3) is used to provide a secured environment in managing the systems and networks. The SNMPv3 Agent supports the following set of security levels as defined in the USM MIB (RFC 3414):

• noAuthNoPriv: Communication without authentication and privacy.

• authNoPriv: Communication with authentication and without privacy. The protocols used for Authentication are MD5 and SHA (Secure Hash Algorithm).

• authPriv: Communication with authentication and privacy. The protocols used for Authentication are MD5 and SHA and for Privacy, DES (Data Encryption Standard) protocol and AES (Advanced Encryption Standard) Protocol is used. For Privacy Support, you have to install some privacy packages. Please refer to the following topic for more details.

A framework for definition of different authentication and privacy protocols is available in V3. Currently, the MD5 and SHA authentication protocols and the CBC-DES, CFB-AES-128 (as per RFC 3826) privacy protocols are supported in USM.

Supported Privacy Packages

While creating an SNMPv3 agent with Privacy support, the agent needs additional privacy packages for both CBC-DES, CFB-AES-128 privacy protocols. These packages are required for encryption of SNMPv3 messages and are not bundled along with the Agent Toolkit C Edition product package.

These privacy package can be obtained by sending an email to the product support team cagent-support@webnms.com, along with the following information

• Agent Toolkit C Edition Product Version that is used

• Which Privacy Package (CBC-DES or CFB-AES-128) is needed

Default Users of SNMPv3 Agents

By default, the SNMPv3 Agent provides support for three levels of users, namely

• noAuthUser - Users with security level noAuthNoPriv

• authUser - Users with security level authNoPriv

• privUser - Users with security level authPriv.

The details about the users get stored in snmpumusertable.txt file in <WebNMS>/C-Agent/projects/<Project-Name>/agent/conf/snmp/snmpv3/security directory provided the AGENT_FILE_TO_VECTOR MACRO is defined in the config.h file.

Developing a Sample V3 Agent

Please follow the steps given below to develop a Sample v3 Agent.

• Start the Agent Compiler application from <WebNMS/C-Agent>/bin directory.

• Create a New Project with the name say : snmpproject01.

• Load any MIB from the MIBs directory say : AGENT-SAMPLE-MIB

• Open the Project Settings window, by selecting Settings menu -> Project Settings.

• Go to Protocols -> SNMP -> SNMPv3 -> General window. Make sure the agent version is SNMPv3 option is enabled.

• If you want Privacy support in the agent, then enable the Privacy Support option and choose the Privacy Protocol (DES / AES)

• Generate code for the Agent.

• On successful generation, compile the generated code.

• On successful compilation, a Sample V3 Agent is created.

Testing the SNMPv3 Agent with Default Users

Now that a Sample Agent is created, it has to be tested with the Default Users.

Testing the V3 Agent for noAuth Users

Default entry of noAuthUser in USM Table :

To test the Agent for noAuthUser,

1. Start the MIB Browser application from <WebNMS/C-Agent>/bin directory.

2. Load Agent-Sample-MIB.

3. Click MIB Browser Settings in the toolbar icon.

4. A wizard opens up wherein you have to choose the version of the Manager. Choose v3.

5. Click Add in this wizard.

6. An SNMP Parameter Panel appears wherein the following details need to be filled :

• Target Host : localhost (by default)

• Target Port : 8001

• User Name : noAuthUser

• Security Level : noAuth,noPriv

• Context Name : noAuth

7. Click OK.

8. The entry gets listed in v3 Settings.

9. Select the entry and click OK to close the MIB Browser Settings wizard.

10. Move on to the MIB Browser Main UI.

11. Make sure the Agent is started from <WebNMS/C-Agent>/projects/snmpproject01/agent/bin directory using snmpagent.exe file.

12. Now, test the SNMPv3 Agent by sending a query to the scalar variable agentDescr in the agentSystem group under the demo group. You will receive the response as

Sent get request to localhost : 8001

agentDescr.0 --> agentDescr not initialized

Testing the V3 Agent for authUsers

Default entry of authUser in USM Table :

To test the Agent for authUser,

1. Follow the steps given above (in Testing the Agent for noAuthUser) until setting the Target Port as 8001.

2. Later, specify the User Name as authUserMD5 for this case.

3. Select the Security Level as Auth,noPriv from the combo box.

4. Specify the Authentication password as authUserMD5.

5. You can see the entry added in the Table. Select the entry and click OK to close the MIB Browser Settings wizard.

6. Move on to the MIB Browser main UI.

7. Make sure the Agent is started from <WebNMS/C-Agent>/projects/snmpproject01/agent/bin directory using snmpagent.exe file.

8. Now, test the SNMPv3 Agent by sending a query to the agentDisk group under the demo group. You will receive the relevant value configured for response. If you try accessing the agentDescr of agentSystem group, you will receive the value for the agentDescr scalar variable. If you do not want to provide the access to the agentDescr scalar variable to the authUser group, then you should not provide the access for the authUsers in View Access to that particular scalar variable. To know more on View-based Access, please refer to "Enabling Authorization using VACM" topic in this section.

Testing the Agent for Privacy Users

Default entry of privUser in USM Table if DES is chosen as Priv Protocol

To test the Agent for privUser,

1. Privacy packages obtained from the product support team has been installed.

2. Mib Browser has to started with JDK / JRE 1.5.x and above.

3. Then, follow the steps given in Testing the v3Agent for noAuthUsers until setting the Target Port as 8001.

4. Later, specify the User Name as privUserMD5

5. Select the Security Level as Auth, Priv from the combo box.

6. Specify the Authentication password as privUserMD5 and Privacy password as privUserMD5.

7. Select the Priv Protocol as CBC-DES from the combo box. If the agent is generated for AES encryption, then choose CFB-AES-128 from the list.

8. Specify the Context Name as priv

9. Click OK.

10. You can see the entry added in the Table. Select the entry and click OK to close the MIB Browser Settings wizard.

11. Make sure the Agent is started from <WebNMS/C-Agent>/projects/snmpproject01/agent/bin directory using snmpagent.exe file.

12. Move on to the MIB Browser Main UI.

13. Now, test the SNMPv3 Agent by sending a query to the agentDisk group under the demo group. You will receive the response without any problem.

Adding More Users for v3 Agents (USM)

User-based Security Model (USM) is a default security model defined by SNMPv3. It provides different types of security levels using various authentication and privacy protocols as explained earlier in this section. To add more users for accessing v3 Agents, WebNMS provides a table called the USMTable. User entries can be added to the Table either : (1) Before Agent Startup or (2) During Run Time.

Please note that though user entries are added, these users will not be able to access the Agent unless View Access is given to them. Please refer to Enabling Authorization in V3 using VACM topic in this section for more details.

Before Agent Start-Up

Entries can be added to the USM User Table before Agent start-up using function Calls. To specify the entries before Agent start-up,

Using Function Calls

An entry can be added to the USMUserTable by calling the function AddUSMUserEntry()

This function is defined in <WebNMS>/C-Agent/projects/<ProjectName>/agent/source/protocols/snmp/src/ snmpv3/security/snmpusmtable.c and is called from WebNMS>/C-Agent/projects/<ProjectName>/agent/stubs/submain.c file. By calling the following function with specified parameters, a new entry will be added to the USM table. You can call this function either before Agent startup or during run time.

CHAR AddUSMUserEntry(U_CHAR *userName, INT32 userNameLen, OID *authProtocol, U_CHAR *authPassword, INT32 authPasswordLen, OID *privProtocol, U_CHAR *privPassword, INT32 privPasswordLen)

Example:

AddUSMUserEntry((U_CHAR *)"authUserMD5", 11, gv_usmHMACMD5AuthProtocol, (U_CHAR *)"authUserMD5", 11, gv_usmNoPrivProtocol, (U_CHAR *)"", 0);

During Run Time: From the Manager

New SNMPv3 users can be added to the SNMPv3 Agent dynamically during runtime. It can be done using MIB Browser or through SNMPv3 Administration Tool or through using Command line (Java) applications.

Using WebNMS MIB Browser

To add the entry from the WebNMS MIB Browser or from any GUI based SNMP Manager, follow the steps given below

• Start the SNMPv3 Agent.

• Start the MIB Browser by executing the MIBBrowser.bat / sh file available under "WebNMS/C-Agent/bin/" directory

• Open Settings menu and add an existing user (say authUserMD5) and click OK.

• Load the SNMP-USER-BASED-SM-MIB and query the usmUserSpinLock node. Initially, the agent will return the value as 1.

• Go to View menu -> Display and select "Multi-varbind" option

• Now, do a Get-Next operation by selecting the usmUserSpinLock node. The ObjectID field will be set as given below
  .iso.org.dod.internet.snmpV2.snmpModules.snmpUsmMIB.usmMIBObjects.usmUser.usmUserSpinLock.0

• Enter the value of usmUserSpinLock node as "1" in the "Set Value" field. Add the field using in the Multi-Varbind list by clicking on Add button
  NOTE: According to RFC , to add an user in USM User Table, the spinlock value needs to be set along with the multi-varbind request.

• Do a Get-Next request by selecting the "usmUserStatus" node.  

• To add a new user named "testUser", then the relevant Hex value it is "74 65 73 74 75 73 65 72". This has to be specified in the ObjectID field along with the usmUserStatus field after removing the existing user name (in Hex) specified in the Object ID. Changes to be done are as follows
   

For the existing user named "authUserMD5", the Object ID field will look like .iso.org.dod.internet.snmpV2.snmpModules.snmpUsmMIB.usmMIBObjects.usmUser.usmUserTable.usmUserEntry.usmUserStatus. 14.49.50.55.46.48.46.48.46.49.35.56.48.48.49.11.97.117.116.104.85.115.101.114.77.68.53 For adding the new user named "testUser", the Object ID field value has to be changed as follows. .iso.org.dod.internet.snmpV2.snmpModules.snmpUsmMIB.usmMIBObjects.usmUser.usmUserTable.usmUserEntry.usmUserStatus. 14.49.50.55.46.48.46.48.46.49.35.56.48.48.49.08.74.65.73.74.75.73.65.72   The change is done only in the Hex numbers marked in bold

 


• Enter the value of usmUserStatus node as "4" in the "Set Value" field. Add the field using in the Multi-Varbind list by clicking on Add button

• Similarly, add the values for other nodes available in the table.

• Enable "Multivarbind" option and Do a SET request

Using WebNMS SNMPv3 Administration Tool

SNMPv3 Admin tool is an easy to use GUI tool to configure security and administration details of USM and VACM tables.

For more information on How to add new SNMPv3 users to the USM table using this tool, refer to the following help section
Help -> Tools -> SNMPv3 Administration Tool

Using Command line tool

• Make use of the command line tool "snmpUSMRemoteConfigure.java" available in <WebNMS/C-Agent>/examples/snmp/cmd_line_apps/udpapps directory

• Go to run.bat or run.sh from the command prompt (available in the above specified directory)  and specify the following options. A user entry will be added to the USM Table using these options
   

Usage : snmpUSMRemoteConfigure [-d dumps the messages] [-p agent port] [-r retries] [-t timeout][-a auth_protocol] [-w auth_password] [-s priv_password] [-n contextName] [-i contextID] [-y new_auth_password] [-z new_priv_password] userName newUserName host

 


• For better understanding, please refer to the sample entry given below
   

<WebNMS>\C-Agent\examples\snmp\cmd_line_apps\udpapps>run.bat snmpUSMRemoteConfigure -d -p 8001 -a MD5 -w authUserMD5 -n auth  -y newUser authUserMD5 newUser localhost

• Here

• -d: Dumps the SNMP message.

• -p 8001: Represents the Agent Port number.

• -a MD5: Represents the admin user's (template user) and new user's  authProtocol.

• -w adminUser: Represents the admin user's authentication password.

• -n auth: Represents the auth user's context name.

• -y newUser: Represents the new user's authentication password.

• authUser: Represents the existing template's user name.

• newUser: Represents the new user's name.

• localhost: Represents the host in which the Agent is running.

If the user is added to the USMTable successfully "User S u c c e s s f u l l y cloned !!!" can be seen in the command prompt. Else, "Failure in USM Remote configuration" will be displayed.

Changing the Password of an Existing User

The Manager can also change the password of an existing user, using the utility called "snmpUSMKeyChange.java" available in WebNMS/C-Agent/examples/snmp/cmd_line_apps/udpapps directory.

The usage of this utility is as follows:

The password can be changed in the following ways:

• Own AuthKey change

• AuthKey Change on behalf of another user

• Own PrivKey change

• PrivKey Change on behalf of another user

The following is an example for Own AuthKey change. Assuming that View access is given for the user, options are explained.

Here,

• d: Dumps the SNMPmessage.

• -p 8001: Represents Agent port number.

• -a MD5: Represents adminUser's authProtocol.

• -w authUser: Represents the adminUser's authentication password

• -n auth: Represents adminUser's context name.

• -z authUserNew: Represents the new authentication password of the user adminUser.

• auth User: Represents the user whose authentication password will be changed.

• localhost: Represents the host where the agent is running.

The above inputs will modify the authentication password of the user "authUser" from"authUser" to"authUserNew".

The user's authentication protocol is "MD5".

Persistence Storage

Once a new user is added or the authKey, privKey, etc. are modified, then the corresponding entries will be added or modified in the USM user table. Those changes will be used by the agent until it reboots. If the agent is rebooted, then all newly added users and changes will not be in the USM user table. So, for persistence storage AGENT_FILE_TO_VECTOR is supported. This means, once a new user is added or old user's information is modified then those changes will be immediately written into a file called "<WebNMS>/C-Agent/projects/<Project-Name>/agent/conf/snmp/snmpv3/security/snmpusmusertable.txt". The file format is

Since the authKey and privKey are stored in the encrypted format it is not possible to add a new user or modify the existing user's authKey/privKey by editing this file. Any invalid change in this file will affect the functionality of the SNMPv3. So, adding a new user or modifying user information through the agent or manager is advisable.

How to Generate Own EngineID value?

Each  SNMPv3 agent has an engine ID that uniquely identifies the agent in the device and also for the unique identification of the MIB objects within a domain. Clock synchronization in the USM security model depends on the concept of an authoritative engine which is identified by the engine ID.

In SNMPv3 communication, EngineID is used as an identifier for an agent among different agents. By default the agent API generates an EngineID by combining AGENT_ADDRESS + "#" + AGENT_PORT_NUM macros which are defined in

<WebNMS>/C-Agent/projects/<Project Name>/agent/source/system/include/config.h header file. The default value for AGENT_ADDRESS is "127.0.0.1" and the value for AGENT_PORT_NUM is 161 or 8001. So the resultant EngineID value is either "127.0.0.1#161" or 127.0.0.1#8001.

If the user wants to generate his own EngineID value, then he has to edit the method called GenEngineId() which is available in <WebNMS>/C-Agent/projects/<ProjectName>/agent/stubs/submain.c file. The agent API will call this method first before generating the default EngineID value. Before assigning the new EngineID value to the variable "engineId", the user has to allocate enough memory. After assigning a new EngineID value, the user has to update the variable "len" with length of the new EngineID value.

For example,

engineId = (U_CHAR *___Calloc(1,6); Memcpy(engineId, (U_CHAR *)"Hello"); *len = 5 //The length of the EngineID

Enabling Authorization in V3 Using VACM

View-based Access Control Model (VACM) is a default access control model defined by SNMPV3 frame work (RFC 3415 (obsoletes RFC 2575)). It is possible to restrict a particular group in accessing an OID in the MIB using VACM. SNMPv3 Agent, has implemented the VACM MIB as a default access control model.

Details for VACM

The details for View-based Access are to be specified in the four tables of VACM MIB namely

• vacmContextTable - This table will have a set of valid context names supported by the SNMPv3 Agent. The context name received will be checked with this table in the access validation phase. It is not configurable through SNMP.

• vacmSecurityToGroupTable - This table will have a set of security to group mappings. If the received context name is valid, then the group name is obtained from this table by giving user (security) name and security model as an input. It is configurable through SNMP.

• vacmAccessTable - This table will have a set of access supported by the Agent. By giving group name, context name, security model, and security level, you can get a view name based on the received request type. It is configurable through SNMP.
• vacmViewTreeFamilyTable - This table will have a set of views supported by the Agent. By giving view name and received OID, you can specify whether the received request has valid view or not. It is configurable through SNMP.

Adding Entries to VACM Tables

A User can be given view access to a MIB by specifying the views in the VACM Tables. Entries can be added to the VACM Tables either : (1) Before Agent Startup or (2) During Run Time. Please note that only when all the VACM tables are configured for a user will the user entry have view access. Let us have a look at the default entries in VACM Tables and move on to the steps involved in adding view access to users.

Default VACM Entries

VACMContextTable 

VACM Group Table

VACM Group Access Table

VACM View Table

Adding Entries Before Agent Start-Up

Entries can be added to the VACM Tables before Agent start-up either using Agent Compiler UI or Text File or Function Calls. To specify the entries before Agent start-up,

1. Using Agent Compiler UI

1. Create a Project and load a MIB. 

2. Choose Settings -> Project Settings from the menu bar of Agent Compiler UI. 

3. Select Protocols -> SNMP ->SNMPv3 -> VACM in the Settings tree.

4. Select the required VACM Table and click Add.

5. A wizard pops up wherein you can specify the user entries.

6. Click OK.
    

Suppose if you want to leave a field empty in the text box, provide the value as empty string "". For example, if you want to leave the vacmAccessWriteViewName column of Vacm Access Table as empty as per RFC 2575, then you can provide empty string ("") in this column. Kindly refer FAQ -> SNMP -> SNMPv3 for more details

2. Text File

The entries configured through Agent Compiler UI get stored in the configuration file under <WebNMS>/C-Agent/projects/<ProjectName>/agent/conf/snmp/acl directory, provided the storage type MACRO is defined in the config.h file as given below :

#define AGENT_FILE_TO_VECTOR

The text files generated are:

• snmpvacmaccesstable.txt

• snmpvacmcontexttable.txt

• snmpvacmsecuritytogrouptable.txt

• snmpvacmviewtreefamilytable.txt

This text file has to be edited for adding new entries. Please note that the Agent has to be restarted for the changes to take effect.

3. Using Function Calls

An entry can be added to the VACM Tables by calling the function CreateAndAddNewSnmp<TableName>Entry(). This function is defined in the following files under <WebNMS>/C-Agent/projects/<ProjectName>/agent/source/protocols/snmp/src /acl directory and is called from <WebNMS>/C-Agent/projects/<ProjectName>/agent/stubs/submain.c file.

• snmpvacmcontexttable.c (for context table)

• snmpvacmsecuritytogrouptable.c (for securitytogroup table)

• snmpvacmaccesstable.c for access table)

• snmpvacmviewtreefamilytable.c (for family table)

By calling the following functions with specified parameters, a new entry will be added to the respective VACM tables. You can call this function either before Agent startup or during run time

VacmContextTable

CreateAndAddNewSnmpVacmContextTableEntry(U_CHAR *snmpVacmContextName, INT32 snmpVacmContextNameLen)

where,

VacmContextName: Refers to the context names supported by the snmpv3 agent.

VacmContextNameLen: Refers to the length of the context name.

Example :

CreateAndAddNewSnmpVacmContextTableEntry((U_CHAR *)"myContext", 9);

VacmSecurityToGroupTable

CreateAndAddNewSnmpVacmSecurityToGroupTableEntry(INT32 vacmSecurityModel, U_CHAR *vacmSecurityName, INT32 vacmSecurityNameLen, U_CHAR *vacmGroupName, INT32 vacmGroupNameLen, INT32 snmpVacmSecurityToGroupStorageType, INT32 snmpVacmSecurityToGroupStatus)

where,

vacmSecuirtyModel: Refers to the Security Model supported by the snmpv3 agent.

vacmSecurityName: Refers to the name of the user

vacmSecurityNameLen: Refers to the length of the security name

vacmGroupName: Refers to the group name to which the user belongs

vacmGroupNameLen: Refers to the length of the group name

VacmSecurityToGroupStorageType: Denotes the storage type "NON_VOLATILE"

vacmSecurityToGroupStatus: Denotes the Row Status "Active"

Example

CreateAndAddNewSnmpVacmSecurityToGroupTableEntry(USM_SECURITY_MODEL, (U_CHAR *)"myUser", 6,(U_CHAR *)"myGroup", 7, 3, SNMP_ROW_ACTIVE);

VacmAccessTable

CreateAndAddNewSnmpVacmAccessTableEntry(U_CHAR *vacmGroupName, INT32 vacmGroupNameLen, U_CHAR *snmpVacmAccessContextPrefix, INT32 snmpVacmAccessContextPrefixLen, INT32 snmpVacmAccessSecurityModel, INT32 snmpVacmAccessSecurityLevel, INT32 snmpVacmAccessContextMatch, U_CHAR *snmpVacmAccessReadViewName, INT32 snmpVacmAccessReadViewNameLen, U_CHAR *snmpVacmAccessWriteViewName, INT32 snmpVacmAccessWriteViewNameLen, U_CHAR *snmpVacmAccessNotifyViewName, INT32 snmpVacmAccessNotifyViewNameLen, INT32 snmpVacmAccessStorageType, INT32 snmpVacmAccessStatus)

where,

vacmGroupName: Refers to the group to which the user belongs

vacmGroupNameLen: Refers to the length of the group name

snmpVacmAccessContextPrefix: Refers to the context name of the user

snmpVacmAccessContextPrefixLen: Refers to the length of the context name

snmpVacmAccessSecurityModel: Refers to the Security Model supported by the snmpv3 agent - USM

snmpVacmAccessSecurityLevel Refers to the Security level of the user

snmpVacmAccessContextMatch Refers to the Context Match "Exact"

snmpVacmAccessReadViewName: Refers to the read view name provided for the v3 user

snmpVacmAccessReadViewNameLen: Refers to the read view name length

snmpVacmAccessWriteViewName: Refers to the write view name provided for the v3 user

snmpVacmAccessWriteViewNameLen: Refers to the write view name length

snmpVacmAccessNotifyViewName: Refers to the notify view name provided for the v3 user

snmpVacmAccessNotifyViewNameLen: Refers to the notify view name length

snmpVacmAccessStorageType Denotes the storage type "NON_VOLATILE"

snmpVacmAccessStatus Denotes the Row Status "Active"

Example:

CreateAndAddNewSnmpVacmAccessTableEntry((U_CHAR *)"myGroup", 7, (U_CHAR *)"myContext", 9, USM_SECURITY_MODEL, SNMP_SEC_LEVEL_AUTHNOPRIV, 1,(U_CHAR *)"myView", 6, (U_CHAR *)"myView", 6, (U_CHAR *)"myView", 6, 3, 1);

VACMViewTreeFamilyTable

CreateAndAddNewSnmpVacmViewTreeFamilyTableEntry(U_CHAR *snmpVacmViewTreeFamilyViewName, INT32 snmpVacmViewTreeFamilyViewNameLen, CHAR *snmpVacmViewTreeFamilySubtree, U_CHAR *snmpVacmViewTreeFamilyMask, INT32 snmpVacmViewTreeFamilyMaskLen, INT32 snmpVacmViewTreeFamilyType, INT32 snmpVacmViewTreeFamilyStorageType, INT32 snmpVacmViewTreeFamilyStatus)

where,

VacmViewTreeFamilyViewName: The Read/Write/Notify view name provided for the v3 user

VacmViewTreeFamilyViewNameLen: The length of the view name

VacmViewTreeFamilySubtree: The Sub Tree OID for which read/write/notify access is provided

VacmViewTreeFamilyMask: The mask for the OID

VacmViewTreeFamilyMaskLen: The length of the mask/p>

VacmViewTreeFamilyType: "INCLUDED"

VacmViewTreeFamilyStorageType: Denotes the storage type "NON_VOLATILE"

VacmViewTreeFamilyStatus: Denotes the Row Status "Active"

Example:

CreateAndAddNewSnmpVacmViewTreeFamilyTableEntry((U_CHAR *)"myView", 6, ".1.3.6.1.4.1", (U_CHAR *)"ff", 2, INCLUDED, 3, 1);

During Run Time: From the Manager

To configure an entry from the Manager,

1. Start the MIB Browser application.

2. Load SNMP-VIEW-BASED-VACM MIB from <WebNMS/C-Agent>/mibs directory.

3. This MIB contains the four tables in which the View-based Authorization has to be configured.

4. Selecting the respective table and clicking SNMP Table icon in MIB Browser opens up a wizard wherein entries can be added to the required Tables by sending SET requests.

5. Please note that vacm context table is not configurable from the Manager (remotely).

Using USM without VACM

To use USM without VACM, just comment or remove the MACRO defined for VACM in the config.h file. Recompile the code to see the changes.

Authenticating Requests from v1/v2c Managers (Co-existence Support)

In a typical deployment scenario, the management applications and applets will be required to communicate with SNMP Agents of different versions. They will also be required to communicate with multi-lingual agents, i.e. SNMP Agents that support all the three SNMP versions (v1, v2c, and v3 ).

The multi-lingual SNMP Agents support multiple SNMP message versions and co-exist with entities which support only a single SNMP message version. So, management applications with SNMPv1 or v2c support alone can communicate with SNMPv3 agents.

This is called co-existence in v3 as defined in RFC 3584. SNMPv3 Agent entities with co-existence support implement the SNMP-COMMUNITY-MIB. This MIB contains objects for mapping between community strings and version-independent SNMP message parameters. Apart from this, a complete implementation of Co-existence Support require the implementation of SNMP-TARGET-MIB. The implementation of this MIB facilitates the source address validation on the incoming requests.

In case the Agent is strictly v3, it will drop the requests sent from v1/v2c Managers. To know how to make an Agent strictly v3, please refer to the next section "Making the Agent strictly SNMPv3".

Enabling Co-existence Support

You can enable the Co-existence Support from the Agent Compiler UI.

Using Agent Compiler UI

The MACRO gets defined even if the Agent Compiler UI options are enabled. To enable the same,

1. Create a Project and Load a MIB.

2. Select Settings -> Project Settings menu from the Agent Compiler UI.

3. From the Protocols -> SNMP -> SNMPv3 -> General Panel, check Co-Existence Support option.

4. This will enable Co-existence Support in the agent.

Details for Co-existence Support

• SnmpCommunityTable : The Community-Based Security Model will attempt to select a row in the snmpCommunityTable. This is done by performing a search through the snmpCommunityTable in lexicographic order. The first entry for which the following matching criteria are satisfied will be selected:
  - The community string is equal to the snmpCommunityName value.
  - If the SnmpCommunityTransportTag is an empty string, it is ignored for the purpose of matching.

• SnmpTargetAddrTable :If the snmpCommunityTransportTag is not an empty string, the transportDomain and transportAddress from which the message was received must match one of the entries in the snmpTargetAddrTable selected by the snmpCommunityTransportTag value.

• SnmpTargetAddrExtTable: The snmpTargetAddrTMask object in the SnmpTargetAddrExtTable is used when checking whether the transportDomain and transportAddress matches a entry in the snmpTargetAddrTable. If no such entry is found, an authentication failure occurs as described in RFC1157, and the snmpInBadCommunityNames counter is incremented. If the entry is found, the SNMPv3 parameters are updated and the request is now processed as a SNMPv3 request.

Default Users of Co-existence Support

The Tables of Community MIB and Target MIB used for co-existence support include SnmpCommunityTable, SnmpTargetAddrTable, and SnmpTargetAddrExtTable. The configurations present by default in these Community tables are as follows:

SnmpCommunityTable

SnmpTargetAddrTable

SnmpTargetAddrExtTable

Adding Managers for Supporting Co-existence

Manager entries can be added to the Community Tables either : (1) Before Agent Startup or (2) During Run time.

Before Agent Startup

Entries can be added to the Community Tables before Agent startup either using Agent Compiler UI or Text File or Function Calls. To specify the entries before Agent startup,

1. Using Agent Compiler UI

1. Create a Project and load a MIB.

2. Choose Settings -> Project Settings menu from the menu bar of Agent Compiler UI.

3. Protocols -> SNMP -> SNMPv3 -> Community Panel

4. Select the required table and click Add, to add entries to the table.

5. A wizard pops up wherein you can specify the communities for Manager entries and click OK

2. Text File

The entries configured through Agent Compiler UI get stored in the configuration text file, under <WebNMS>/C-Agent/projects/<ProjectName>/agent/conf/snmp/snmpv3/co-existence directory, provided the storage type MACRO is defined in the config.h file as given below :

#define AGENT_FILE_TO_VECTOR

The text files generated are

• snmpaoicommunitytable.txt

• snmpapitargetaddrexttable.txt

• snmpapitargetaddrtable.txt

Please note that the Agent has to be restarted for the changes to take effect.

3. Using Function Calls

An entry can be added to the co-existence tables by calling the function CreateAndAddNew<TableName>Entry(). This function is defined in the following files in <WebNMS>/C-Agent/projects/<ProjectName>/agent/source/protocols/snmp/src/snmpv3/co-existence folder and is called from <WebNMS>/C-Agent/projects/<ProjectName>/agent/stubs/submain.c

• snmpaoicommunitytable.txt

• snmpapitargetaddrexttable.txt

• snmpapitargetaddrtable.txt

By calling the following functions with specified parameters, a new entry will be added to the Community tables. You can call this function during Agent startup or during run time

SnmpCommunityTable

CreateAndAddNewSnmpApiCommunityTableEntry( U_CHAR *snmpCommunityIndex, U_CHAR*snmpCommunityName,INT32 snmpCommunityNameLen , U_CHAR *snmpCommunitySecurityName, U_CHAR *snmpCommunityContextEngineID, U_CHAR *snmpCommunityContextName, U_CHAR *snmpCommunityTransportTag,INT32 snmpCommunityStorageType,INT32 snmpCommunityStatus)

SnmpTargetAddressTable

CreateAndAddSnmpApiTargetAddrTableEntry(OID *instance, INT32 instanceLen, U_CHAR *snmpTargetAddrName, CHAR *snmpTargetAddrTDomain, U_CHAR *snmpTargetAddrTAddress, INT32 snmpTargetAddrTimeout, INT32 snmpTargetAddrRetryCount, U_CHAR *snmpTargetAddrTagList, U_CHAR *snmpTargetAddrParams, INT32 snmpTargetAddrStorageType, INT32 snmpTargetAddrRowStatus)

SnmpTargetAddressExtTable

CreateAndAddSnmpApiTargetAddrExtTableEntry(OID *instance, INT32 instanceLen, U_CHAR *snmpTargetAddrName, U_CHAR *snmpTargetAddrTMask,INT32 snmpTargetAddrTMaskLen, INT32 snmpTargetAddrMMS)

During Run Time: From the Manager

To add an entry to the aclTable from the Manager,

1. Start the MIB Browser application.

2. Load SNMP-COMMUNITY-MIB from <WebNMS/C-Agent>/mibs directory.

3. This MIB contains the SnmpCommunityTable, SnmpTargetAddrTable, and SnmpTargetAddrExtTable in which the Community Authentication has to be configured.

4. Selecting the respective table and clicking SNMP Table icon in MIB Browser will open up a wizard wherein entries can be added to the required Tables by sending SET requests.

Testing the Agent for Co-existence Support

1. Start the MIB Browser application.

2. In the MibBrowser Settings General panel, specify the SNMP version as v1 or v2c.

3. Load the MIB with which v3 Agent is developed.

4. Start the v3 Agent.

5. Send a v1/v2c request to a variable in the MIB.

6. The v3 agent will respond for a v1/v2c request from the Manager.

Making the Agent Strictly SNMPv3

Normally a V3 Agent accepts requests from V1 and V2c Managers. But if you do not want to provide SNMPv1 or SNMPv2c access to the v3 Agent, please follow the steps given below and this would restrict the access making the SNMPv3 Agent strictly V3 :

• Select Settings -> Project Settings option from the menu bar of the Agent Compiler.

• In the Settings Tree, select Protocols -> SNMP -> SNMPv3 -> General. The SNMPv3 General Panel is displayed.

• Select the option "Drop V1/V2 Packets".

• This will add the following macro in the config.h file.

#define DROP_V1_AND_V2C_REQUESTS

• Compile the code for SNMPv3 Agent.

• Now it is not possible to access the Agent through SNMPv1 or SNMPv2c requests. The PDU packet will be dropped. You can test the V3 Agent by sending a v2c request.

• Dropping of the v1/v2 request in the v3 agent is only a proprietary implementation.

Sending Notifications

SNMPv3 Notification PDU though similar to SNMPv2 Notification PDU, differs in the message format. It contains SNMPv3 message headers, such as message ID, version, security level, maximum supported size, security model, etc. and security parameters depending upon the security model and scoped PDU parameters, such as context name, context engine ID, varbinds, etc. Notifications can be sent to both v3 Managers (using the Manager information in v3Trap ForwardingTable) and v1/v2c Managers (using Notification Filtering Mechanism). Please go through the following topics for more details.

In SNMPv3, sending a Notification from an entity is not a simple process. The Agent should find out the targets, pass the filtering mechanism and access its validation. To put it in steps,

• The agent requires a mechanism for identifying the management targets to which notifications should be sent.

• Filtering mechanism should be applied to determine whether the notification should be sent to the management target or not.

• IsAccessAllowed abstract interface must be called for each variable binding OID and for the trap OID value (present in the second variable binding as a value).

SNMPv3 by itself is not clear as to how filtering has to be done before sending Notifications. This may again depend on the individual instrumentation of the agent. Hence we provide an interface function called DoFilteringForSnmpTraps present in <WebNMS/C-Agent>/projects/<ProjectName>/agent/stubs/inform.c. This function will provide informations about the Manager (Target), Notification details, such as Trap OID, and Variable Bindings. Thus, the user can decide whether the notification needs to be sent to the specified target or not.

The IsAccessAllowed() method is called according to the VACM MIB, for each variable binding OID and Trap OID. Any failure in step 2 or step3 will stop the Agent in sending the notification to the specified target.

Notifications to v3 Managers

SNMPv3 frame work recommends SNMP-TARGET-MIB to identify the targets for sending Notifications, which is implementation specific. WebNMS Toolkit has a proprietary table called the V3 Trap Forwarding Table that contains all the information of the target. For more information about this table, please refer to "Sending Traps, Notifications and Informs " section. This section explains how Traps can be sent from v3 Agents to v3 Managers using v3 Trap Forwarding Table.

Notifications to v1/v2c Managers

Notifications can also be sent to v1/v2c Managers from a v3 Agent. To support this feature, Agent Toolkit has implemented the Notification Filtering Mechanism as per RFC 3413 (obsoletes RFC 2573).

Enabling Notification Filtering Support

Notification Filtering support can be enabled using Agent Compiler UI

Using Agent Compiler UI

1. Create a Project and Load a MIB.

2. Select Settings -> Project Settings menu from the menu bar of Agent Compiler UI.

3. From the General Panel of Protocols -> SNMP -> SNMPv3, check Notification Support option.

4. This will enable the Notification Filtering Support.

Default Users for Notification Filtering Support

The Tables of Notification MIB and Target MIB used for Filtering Mechanism support include SnmpTargetParamsTable, SnmpNotifyTable, SnmpNotifyFilterProfileTable, and SnmpNotifyFilterTable. The default configurations present in these Notification Filtering Tables are as follows:

SnmpTargetParamsTable

SnmpNotifyTable

SnmpNotify FilterProfileTable

SnmpNotify FilterTable

Adding Managers to the Notification Tables

After enabling Notification Filtering Support, it is required to specify the v1/v2c Managers to whom these Notifications should be sent. Manager Entries can be added to the Notification tables either : (1) Before Agent Startup or (2) During Run Time.

Before Agent Startup

Entries can be added to the Notification Tables before Agent startup either using Agent Compiler UI or Text File or Functional Calls. To specify the entries before Agent start-up,

1. Using Agent Compiler UI

1. Create a Project and load a MIB>

2. Choose Settings -> Project Settings menu from the menu bar of Agent Compiler UI>

3. Select Target and Notification Tables under Protocols -> SNMP -> SNMPv3.

4. Now, Click Add.

5. A wizard pops up wherein you can specify the communities for Manager entries and click OK.

2. Text File

The entries configured through Agent Compiler UI get stored in the configuration text file under <WebNMS>/C-Agent/projects/<ProjectName>/agent/conf/snmp directory, provided the storage type MACRO is defined in the config.h file as given below :

#define AGENT_FILE_TO_VECTOR

Please note that the Agent has to be restarted for the changes to take effect.

3. Using Function Calls

The functions defined in <WebNMS>/C-Agent/projects/<ProjectName>/agent/source/protocols/snmp/ src/snmpv3/co-existence folder is called from <WebNMS>/C-Agent/projects/<ProjectName>/agent/ stubs/submain.c file. By calling the following functions with specified parameters, a new entry will be added to the Notification tables. You can call this function either before Agent startup or during run time.

SnmpTargetAddrTable

CreateAndAddNewSnmpApiTargetAddrTableEntry( U_CHAR *snmpTargetAddrName, CHAR *snmpTargetAddrTDomain, U_CHAR *snmpTargetAddrTAddress, INT32 snmpTargetAddrTimeout, INT32 snmpTargetAddrRetryCount, U_CHAR *snmpTargetAddrTagList, U_CHAR *snmpTargetAddrParams, INT32 snmpTargetAddrStorageType, INT32 snmpTargetAddrRowStatus)

SnmpTargetParamsTable

CreateAndAddNewSnmpApiTargetParamsTableEntry( U_CHAR *snmpTargetParamsName, INT32 snmpTargetParamsMPModel, INT32 snmpTargetParamsSecurityModel, U_CHAR *snmpTargetParamsSecurityName, INT32 snmpTargetParamsSecurityLevel, INT32 snmpTargetParamsStorageType, INT32 snmpTargetParamsRowStatus) CreateAuthenticationEntry()

SnmpNotifyTable

CreateAndAddNewSnmpApiNotifyTableEntry( U_CHAR *snmpNotifyName, U_CHAR *snmpNotifyTag, INT32 snmpNotifyType, INT32 snmpNotifyStorageType, INT32 snmpNotifyRowStatus)

SnmpNotifyFilterTable

CreateAndAddNewSnmpApiNotifyFilterTableEntry( U_CHAR *snmpNotifyFilterProfileName, CHAR *snmpNotifyFilterSubtree, U_CHAR *snmpNotifyFilterMask, INT32 snmpNotifyFilterMaskLen, INT32 snmpNotifyFilterType, INT32 snmpNotifyFilterStorageType, INT32 snmpNotifyFilterRowStatus)

SnmpNotifyFilterProfileTable

CreateAndAddNewSnmpApiNotifyFilterProfileTableEntry( U_CHAR *snmpTargetParamsName, U_CHAR *snmpNotifyFilterProfileName, INT32 snmpNotifyFilterProfileStorType, INT32 snmpNotifyFilterProfileRowStatus)

During Run Time: From the Manager

To configure an entry from the Manager,

1. Start the MIB Browser Application.

2. Load SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB from WebNMS/C-Agent/mibs directory.

3. SnmpTargetAddrTable, SnmpTargetParamsTable     SnmpNotifyTable, SnmpNotifyFilterTable, and SnmpNotifyFilterProfileTable in which Notification Filtering Support is to be configured.

4. When you select the respective table and click SNMP Table icon (View SNMP Table Data icon), MIB browser opens up a wizard wherein entries can be added to the required Tables.

5. Click OK and you can see the entries added to the Table.

6. Check for the same by sending a GET request to the Table.

Testing Notification Filtering Support

Now that you have enabled this feature and added entries to the Notification Table, the next step is checking whether the Agent works with this support. To ensure the same, follow these steps:

• Start the MIB Browser application.

• Load the MIB with which v3 Agent is developed.

• Configure the MIB Browser settings. The Manager has to be of v1 or v2c type for testing purpose.

• Start the v3 Agent.

• Send a SET Request to a variable in the MIB for which Notification is defined.

• Values should be set and Notification should be generated.

• Notifications can be viewed in the Trap Viewer of MIB Browser application.