Sun Microsystems
Products & Services
 
Support & Training
 
 

Previous Previous     Contents     Index     Next Next

19.1.1.3 Format of the Inform Group

The inform group specifies the hosts to which your agent or manager will send informs if the InetAddressAcl mechanism is used. This group contains one or more inform community definitions.

inform = {
   community1
   community2
   ...
   communityN
}

Each community definition defines the association between a set of hosts and the SNMP community string in the informs to be sent to them. Each inform definition has the following format:

{
   inform-community = informCommunityName
   hosts = informHostList
}

The informCommunityName item specifies a single SNMP community string. It will be included in the informs sent to the hosts specified in the hosts item. SNMPv3 does use the community string, so use IP addresses or the context name instead.

The informHostList item specifies a comma-separated list of hosts. Each host must be identified by its name or complete IP address.

When the SNMP protocol adaptor is instructed to send an inform using the InetAddressAcl mechanism, it will send an inform to every host listed in the inform community definitions. If a host is present in more than one list, it will receive more than one inform, each one identified by its corresponding inform community.

19.1.2 Enabling InetAddressAcl

The default InetAddressAcl mechanism provided with the Java DMK relies on an InetAddressAcl file to define the access rights and trap recipients. To enable access control with this mechanism, you must first write an InetAddressAcl file to reflect the access and trap policy of your SNMP agent. Then, there are two ways to enable file-based access control, one way to modify the file in use and one way to disable access control.

The simplest way of enabling access control and traps is to ensure that an InetAddressAcl file exists when the SNMP protocol adaptor MBean is instantiated. To be automatically detected, the InetAddressAcl file must be named jdmk.acl and must be located in the configuration directory of the Java DMK installation. On UNIX systems with a standard installation of the product, the configuration directory is owned by root and requires superuser privileges to write or modify the InetAddressAcl file.

Operating Environment

Configuration Directory

Solaris/Linux/Windows

installDir/SUNWjdmk/5.1/etc/conf/

The other way of enabling file-based access control is to specify a different file through the jdmk.acl.file system property. The filename associated with the property will override any InetAddressAcl file in the configuration directory. This property can be set programmatically, but it is usually done on the command line when starting your agent. For example, if the full pathname of your InetAddressAcl file is MyAclFile, use this command to start the agent with SNMP access control enabled:

$ java -classpath classpath -Djdmk.acl.file=MyAclFile MyAgent

If an InetAddressAcl file exists, the access rights it defines apply to all management applications that access the agent through its SNMP adaptor. This includes managers on the agent's local host: the InetAddressAcl groups must explicitly give permissions to localhost or the host's name or IP address for such managers. If the InetAddressAcl file does not exist when the SNMP adaptor is instantiated, either in the configuration directory or defined as a property, all SNMP requests will be processed, and traps will be sent only to the local host.

The InetAddressAcl file-based mechanism relies on the JdmkAcl class to provide the access control functionality. This is the class that is initialized with the contents of the InetAddressAcl file. This class provides the rereadTheFile method to reset the access control and trap lists with the contents of the InetAddressAcl file. This method will reload the same file that was used originally, regardless of any new property definitions. After you have updated the InetAddressAcl file, call the following methods to update the access control lists:

// assuming mySnmpAdaptor is declared as an SnmpAdaptorServer object
JdmkAcl theAcl = (JdmkAcl)(mySnmpAdaptor.getInetAddressAcl());
theAcl.rereadTheFile();

The JdmkAcl class that is used by default might not be suitable for all environments. For example, it relies on the java.security.acl package that is not available in the PersonalJava™ runtime environment. Therefore, one constructor of the SnmpAdaptorServer class lets you override this default, forcing the adaptor not to use access control, regardless of any existing InetAddressAcl file. If you specify false for the useAcl parameter of this constructor, the SNMP adaptor will not even search for an InetAddressAcl file. In this case, no access control is performed, as if there were no InetAddressAcl file: all SNMP requests will be processed, and traps will be sent only to the local host. For security considerations, the use of access control cannot be toggled once the SNMP adaptor has been instantiated.

19.1.3 Custom Access Control

The JdmkAcl class that relies on an ACL file is the default access control mechanism in the SNMP adaptor. For greater adaptability, the SnmpAdaptorServer class has constructors that let you specify your own access control mechanism. For example, if your agent runs on a device with no file system, you could implement a mechanism that does not rely on the jdmk.acl file.

To instantiate an SNMP adaptor with your own access control, use one of the constructors that takes an acl parameter of the type InetAddressAcl. Note that if this parameter's value is null, or if you use a constructor that does not specify an acl parameter, the SNMP adaptor will use the JdmkAcl class by default. If you want to instantiate an SNMP adaptor without access control, call the constructor with the useAcl parameter set to false.

Your access control mechanism must be a class that implements the InetAddressAcl interface. This interface specifies the methods that the SNMP adaptor uses to check permissions when processing a request. If you instantiate the SNMP adaptor with your access control class, the adaptor will call your implementation of the access control methods. Again, for security reasons, the InetAddressAcl implementation in use cannot be changed once the SNMP adaptor has been instantiated.

The JdmkAcl class implements the default access mechanism that uses the jdmk.acl file. It is also an implementation of the InetAddressAcl interface, and it provides a few other methods, such as rereadTheFile, to control the InetAddressAcl mechanism.

19.2 SNMPv3 User-Based Access Control

The user-based access control implemented by SNMPv3 is based on contexts and user names, rather than on IP addresses and community strings. It is a partial implementation of the view-based access control model (VACM) defined in SNMP RFC 2575.

The users, contexts and associated security information controlling access to the agents in an SNMP session are defined in the jdmk.uacl file, as shown in the following example, taken from the examplesDir/current/Snmp/Agent directory.

Example 19-2 jdmk.uacl File

acl = {
{ 
context-names = TEST-CONTEXT
access = read-write
security-level=authNoPriv
users = defaultUser
}

} 

In the jdmk.uacl file, you define the following:

  • A list of context names, separated by commas; this example uses TEST-CONTEXT defined in 16.2.3 Binding the MIB MBeans. You can define a null context by declaring context-names = NULL

  • The access level, which can be either read-write or read-only

  • The security level, as follows:
    noAuthNoPriv

    No security mechanisms activated

    authNoPriv

    Authentication activated, with no privacy

    authPriv

    Both authentication and privacy activated

  • A list of authorized users, separated by commas; an asterisk (*) opens access to all users

The user ACL file allows any request from defaultUser, in the scope of TEST-CONTEXT, with a minimum of authNoPrivacy to be authorized. Any other request will be rejected.

19.2.1 Enabling User-Based Access Control

To enable user-based access control, you must create a UserAcl file. You must then direct the agent applying the access control to look in this file.

The simplest way of enabling access control and traps is to ensure that a user-based access control file UserAcl file exists when the SNMP protocol adaptor MBean is instantiated. To be automatically detected, the UserAcl file must be named jdmk.uacl and must be located in the configuration directory of the Java DMK installation. On UNIX systems with a standard installation of the product, the configuration directory is owned by root and requires superuser privileges to write or modify the UserAcl file.

Operating Environment

Configuration Directory

Solaris/Linux/Windows

installDir/SUNWjdmk/5.1/etc/conf/

The other way of enabling file-based access control is to specify a different file through the jdmk.uacl.file system property. The filename associated with the property will override any UserAcl file in the configuration directory. This property can be set programmatically, but it is usually done on the command line when starting your agent. For example, if the full pathname of your UserAcl file is MyUaclFile, use this command to start the agent with SNMP access control enabled:

$ java -classpath classpath -Djdmk.uacl.file=MyUaclFile MyAgent

If a UserAcl file exists, the access rights it defines apply to all management applications that access the agent through its SNMP adaptor. If the UserAcl file does not exist when the SNMP adaptor is instantiated, either in the configuration directory or defined as a property, all SNMP requests will be accepted.

The UserAcl file-based mechanism relies on the SnmpEngineParameters class to provide the access control functionality. This is the class that is initialized with the contents of the UserAcl file. This class provides the rereadTheFile method to reset the access control and trap lists with the contents of the UserAcl file. This method will reload the same file that was used originally, regardless of any new property definitions. After you have updated the UserAcl file, call the following method to update the access control lists:

Uacl.rereadTheFile

The following procedure demonstrates how to enable Uacl, using the example of the simple synchronous manager we saw in 17.1.3 Synchronous SNMPv3 Managers and the simple SNMPv3 agent from Example 16-2.

ProcedureTo Run a Simple Manager with Access Control

  1. If you have not already done so, build and compile the AgentV3 example in examplesDir/current/Snmp/Agent.

    Type the following commands:

    $ mibgen -mo -d . mib_II.txt
    $ javac -classpath classpath -d . *.java

  2. Start the AgentV3 example in its Agent directory, this time pointing it to its associated jdmk.uacl file, as well as to its jdmk.security file.

    $ java -classpath classpath 
    -Djdmk.security.file=jdmk.security -Djdmk.uacl.file=jdmk.uacl AgentV3

  3. If you have not already done so, in a separate window, compile the SyncManagerV3 example in examplesDir/current/Snmp/Manager.

    $ javac -classpath classpath -d . *.java

  4. Start the SyncManagerV3 SNMP manager in its Manager directory, specifying the agent's host and port.

    This is the manager we configured to communicate with AgentV3 in To Run the SyncManagerV3 Example. As before, we set the host to localhost and the port to 8085.

    $ java -classpath classpath 
    -Djdmk.security.file=jdmk.security SyncManagerV3 localhost 8085

    You should see the following error message:

    SyncManagerV3::main:Send get request to SNMP agent 
    on localhost at port 8085
    Error status = authorizationError
    Error index = -1

    The agent refuses the manager's request because the level of security for this agent in the manager's jdmk.security file does not match the level of security set in the agent's jdmk.uacl file.

  5. Press Control-C to stop the manager.

  6. Start the SyncManagerV3 SNMP manager again

    $ java -classpath classpath 
    -Djdmk.security.file=jdmk.security SyncManagerV3 localhost 8085

    You should now see the manager sending requests to the agent.

    $ SyncManagerV3::main:Send get request to SNMP agent 
    on localhost at port 8085
    Result: 
    [Object ID : 1.3.6.1.2.1.1.1.0  (Syntax : String)
    Value : SunOS sparc 5.8]
    >> Press Enter if you want to stop this SNMP manager.

Previous Previous     Contents     Index     Next Next