Chapter 5

SNMP Monitoring and Management

The Simple Network Management Protocol (SNMP) is an industry standard for network management. Objects managed by SNMP are arranged in management information bases (MIBs). The SNMP agent publishes the standard MIB for the Java virtual machine (Java VM) instrumentation. The standard MIB for monitoring and management of the Java VM is available for download at http://docs.oracle.com/javase/6/docs/jre/api/management/JVM-MANAGEMENT-MIB.mib.

Enabling the SNMP Agent

To monitor a Java VM with SNMP you must first enable an SNMP agent when you start the Java VM. You can enable the SNMP agent for either a single-user environment or a multiple-user environment. Then, you can monitor the Java VM with an SNMP-compliant tool.

For general information on setting system properties when you start the Java VM, see Setting System Properties in Chapter 2, Monitoring and Management Using JMX Technology. How to enable the SNMP agent in single and multiple-user environments is described below. The process is the same for both environments, but the actions performed are slightly different.

Access Control List File

An Access Control List (ACL) template file is provided with the Java Platform, Standard Edition (Java SE platform) in JRE_HOME/lib/management/snmp.acl.template, where JRE_HOME is the directory in which the Java Runtime Environment (JRE) implementation is installed. You will copy this file to either JRE_HOME/lib/management/snmp.acl or to your home directory, depending on whether you are operating in a single or a multiple-user environment. Ensure that only you have read permissions, since the file contains non-encrypted SNMP community strings. For security reasons, the system checks that only the owner has read permissions on the file and exits with an error if this is not the case. Thus, in a multiple-user environment, you should put this file in private location, such as your home directory.

Example 5-1 shows some possible entries in an ACL file.

Example 5-1 Sample ACL Entries

#The communities public and private are allowed access from the local host.
acl = {
        {
          communities = public, private
          access = read-only
          managers = localhost
        }
      }
# Traps are sent to localhost only
trap = {
          {
            trap-community = public
            hosts = localhost
          }
        }

To Enable the SNMP Agent in a Single-user Environment

Set the following system property when you start the Java VM.
```
com.sun.management.snmp.port=portNum
```
In the property above, portNum is the port number to use for monitoring. Setting this property starts an SNMP agent that listens on the specified port number for incoming SNMP requests.
Create an ACL File.
Copy the ACL template file from JRE_HOME/lib/management/snmp.acl.template to JRE_HOME/lib/management/snmp.acl.
Set the permissions on the ACL file.
Make sure the ACL file is readable by only the owner, and add community strings as needed.

To Enable the SNMP Agent in a Multiple-user Environment

Set the following system properties when you start the Java VM.
```
com.sun.management.snmp.port=portNum
com.sun.management.snmp.acl.file=ACLFilePath
```
Where ACLFilePath is the path to the ACL file.
Create an ACL File.
Copy the ACL template file from JRE_HOME/lib/management/snmp.acl.template to a file named snmp.acl in your home directory.
Set the permissions on the ACL file.
Make sure the ACL file is readable by only the owner, and add community strings as needed.

SNMP Monitoring and Management Properties

You can set SNMP monitoring and management properties in a configuration file or on the command line. Properties specified on the command line override properties in a configuration file. The default location for the configuration file is JRE_HOME/lib/management/management.properties. The Java VM reads this file if the command-line property com.sun.management.snmp.port is set.

You can specify a different location for the configuration file with the following command-line option.

com.sun.management.config.file=ConfigFilePath

In the property above, ConfigFilePath is the path to the configuration file.

You must specify all system properties when you start the Java VM. After the Java VM has started, any changes to system properties (for example, via the setProperty method), to the password file, to the ACL file, or to the configuration file will have no effect.

Table 5-1 describes all the SNMP management properties.

Table 5-1 SNMP monitoring and management Properties

Property Name	Description	Default
`com.sun.management.snmp.trap`	Remote port to which the SNMP agent sends traps.	162
`com.sun.management.snmp. interface`	Optional. The local host `InetAddress,` to force the SNMP agent to bind to the given `InetAddress`. This is for multi-home hosts if one wants to listen to a specific subnet only.	Not applicable
`com.sun.management.snmp.acl`	Enables or disables SNMP ACL checks.	`true`
`com.sun.management.snmp. acl.file`	Path to a valid ACL file. After the Java VM has started, modifying the ACL file has no effect.	`JRE_HOME/lib/management/snmp.acl`

Configuration Errors

If any errors occur during start up of the SNMP agent, the Java VM will throw an exception and exit. Configuration errors include the following.

Failure to bind to the port number.
The password file is readable by anyone other than the owner.
Invalid SNMP ACL file.

If your application runs a security manager, then additional permissions are required in the security permissions file.