Java Dynamic Management Kit 5.1 Tutorial

17.1.3 Synchronous SNMPv3 Managers

The example synchronous manager application created for SNMPv3 is similar to the SNMPv1/v2 manager, except that it implements SNMPv3 user-based USM mechanisms before making requests.


Example 17–3 SNMPv3 SyncManagerV3 Example

The SyncManagerV3 example is in the examplesDir/current/Snmp/Manager directory.

			//Read the command line parameters
        final String host = argv[0];
        final String port = argv[1];

        try {
            
     		 // Initialize the SNMP Manager API.
            final SnmpOidTableSupport oidTable = new RFC1213_MIBOidTable();
            SnmpOid.setSnmpOidTable(oidTable);
       
      		// Build the session.
            //
			    try {
						session= new SnmpSession("SyncManagerV3 session");
	   			 }catch(SnmpStatusException e) {
						println(e.getMessage());
						java.lang.System.exit(0);
	    		}
	    		catch(IllegalArgumentException e) {
				// If the engine configuration is faulty 
				println(e.getMessage());
				java.lang.System.exit(0);
	    		}
	
	    		// Access the SNMPv3 engine using getEngine
	    		//
	   			final SnmpEngine engine = session.getEngine();
	    
	    		// Create an SnmpUsmPeer object
 				//
			   final SnmpUsmPeer agent = 
				new SnmpUsmPeer(engine, host, Integer.parseInt(port));
	    
	    		// Create USM parameters
 				//
			   final SnmpUsmParameters p = 
				new SnmpUsmParameters(engine, "defaultUser");
	    
	    		// Set the security level 
				//
			 	p.setSecurityLevel(SnmpDefinitions.authNoPriv);

	    		// Contextualize the send request
	 		   //
	   			 p.setContextName("TEST-CONTEXT".getBytes());

	    		// Set the contextEngineId discovered by the peer upon 
				// creation
	   			 p.setContextEngineId(agent.getEngineId().getBytes());
	    
	    		// Associate the parameter with the agent.
	    		//
	    		agent.setParams(p);
	
	    
	    		// Discover time of creation and boot
			   //
			   agent.processUsmTimelinessDiscovery();
	    
	    		// Associate a default peer (agent) to an SnmpSession.
	    		// 
			   session.setDefaultPeer(agent);

	    		// Create a taskServer for processing traps (optional)
	    	    final DaemonTaskServer taskServer = new DaemonTaskServer();
	    		taskServer.start(Thread.NORM_PRIORITY);
	    
	    		// Create a listener and dispatcher for SNMP traps 
	    	   //
	    		final SnmpEventReportDispatcher trapAgent =
				new SnmpEventReportDispatcher(engine, 
					      Integer.parseInt(port) + 1, 
					      taskServer, null);
	    
	    		trapAgent.addTrapListener(new TrapListenerImpl());
           	final Thread trapThread = new Thread(trapAgent);
	    		trapThread.setPriority(Thread.MAX_PRIORITY);
			   	trapThread.start();	    
	    
	    		// Build the list of variables you want to query
	    	    //
	    		final SnmpVarBindList list = 
				new SnmpVarBindList("SyncManagerV3 varbind list");
	    
	    		// Read the "sysDescr" variable
			   //
           list.addVarBind("sysDescr.0");
	    
	    		// Make the SNMP get request and wait for the result
	    		//
	    		final SnmpRequest request = 
				session.snmpGetRequest(null, list);
	   			println("SyncManagerV3::main:" +
				    "Send get request to SNMP agent on " + host + 
				    " at port " + port);
			   final boolean completed = request.waitForCompletion(10000);
	    
	    		// Check for a timeout
	    		//
            if (completed == false) {
                println("SyncManagerV3::main:" + 
						" Request timed out. Check if agent  
						  can be reached");
		
                // Print request.
                //
                println("Request: " + request.toString());
                java.lang.System.exit(0);
            }
	    
            // Check the response for errors 
	    		//
            final int errorStatus = request.getErrorStatus();
            if (errorStatus != SnmpDefinitions.snmpRspNoError) {
                println("Error status = " + 
					 SnmpRequest.snmpErrorToString(errorStatus));
                println("Error index = " + 
					 request.getErrorIndex());
                java.lang.System.exit(0);
            }
       
            // Display the result.
            //
            final SnmpVarBindList result = request.getResponseVarBindList();
            println("Result: \n" + result);
       
            [...]

            // End the session
            //
            session.destroySession();
       
	    	    trapAgent.close();
	    		 taskServer.terminate();
            java.lang.System.exit(0);
     
				[...]
}

The first instantiated session creates an engine. This engine can be accessed using the getEngine method. To avoid excessive engine creation for each instantiated session, the first engine can be shared between SNMP session objects. While sharing is possible, it should be avoided. It represents an unnecessary increase in overhead and limits the security possibilities because only one security file can be associated with an engine.

The engine is used by all the other classes in the application programming interface (API) to access the USM configuration, contained in the jdmk.security file associated with that session. In Example 17–3, when the peer p is created, it discovers its engineId, and then uses it as the SNMPv3 ContextEngineId. When the request is sent, this engine ID is included as a parameter by setContextEngineId.

In this example, the level of security is set as authentication without privacy. Consequently, this level of security is applied to all the requests between this manager and the peers associated with it, via the security parameters. This level of security must match the level specified in the engine's jdmk.security file.

It is also possible to access MIBs that have been registered in the scope of a context (see 16.2.3 Binding the MIB MBeans for details of contextualized MIBs). In this example, the context TEST-CONTEXT is used, and is set as a parameter in the request by setContextName.

Finally, before sending any requests, if authentication is activated, the timeliness parameters of the request are discovered, using processUsmTimelinessDiscovery.