# @(#)file      README
# @(#)author    Sun Microsystems, Inc.
# @(#)version   1.32
# @(#)lastedit  04/04/07
#
# Copyright 2004 Sun Microsystems, Inc. All rights reserved.
# SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.


                        SNMP Agent Example
                        ==================


-----------------------------------------------------------------------
1. Overview
-----------------------------------------------------------------------

This example shows how to build a standard SNMP agent, a secure SNMP
agent and a standalone SNMP agent.

Note:
-----

This example is built around a subset of MIB-II (RFC1213) and shows how
the code generated by mibgen can be customized in order to access the
"real-values".

The demonstrated implementation of this MIB-II subset is only given for
the sake of the example: the goal of this example is not to provide
a ready-to-use implementation of MIB-II.

The LinkTrapGenerator class shows how to send a trap using the API.
It simulates linkUp and linkDown conditions on an Ethernet interface.
It does not try to access or bind with any real resource.

This example has been extended to demonstrate SNMP v3 Agents. More
information on the v3 Agents can be found in the file READMEV3.
In the present file, therefore, we will only discuss the v1 and v2 agents.


-----------------------------------------------------------------------
2. File List
-----------------------------------------------------------------------

This example is based on the following source files:

 * Agent.java: Demonstrate a simple v1/v2 Agent.
    - Creates an MBean server.
    - Creates and registers an HTML adaptor server in the MBean server.
    - Creates and registers an SNMP adaptor server in the MBean server.
      The adaptor is bound to a non-standard SNMP port (8085).
      This avoids having to start the agent as root, as is required by
      some operating systems for binding to a standard SNMP port.
    - Creates and initializes an SNMP MIB.
      The whole MIB and every group in the MIB are registered with the
      MBean server. This enables them to be managed through the HTML
      adaptor in the agent.
    - Creates a LinkTrapGenerator object. The LinkTrapGenerator object
      is used to switch the MIB table entry status periodically.
      As a consequence of the switch, the entry will send a trap.
      The Agent can take as optional input the number of traps to send.

 * SecureAgent.java: Demonstrate a v1/v2 agent making use of a customized
        SnmpPduFactory in order to add an additional security layer.
    - Same content as Agent.java showing an example of a simple use of
      the SnmpPduFactory. The SecureAgent can take as optional input a
      list of host names whose request pdus will be rejected.
      This secure agent does not send traps.
      Note that if you need security, you should rather consider
      using a V3 agent rather than implementing custom or proprietary
      mechanisms.

 * StandAloneSnmpAgent.java:
    - Implements a standalone SNMP agent.
      A standalone SNMP agent does not contain the MBean server.
      The only component of the Java DMK required is the SNMP adaptor.
    - Adds an SNMP adaptor server.
      The adaptor is bound to a non-standard SNMP port (8085).
    - Creates and initializes an SNMP MIB.
    - Creates a LinkTrapGenerator object. The LinkTrapGenerator object
      is used to switch the MIB table entry status periodically.
      As a consequence of the switch, the entry will send a trap.
      The StandAloneSnmpAgent can take as optional input the number of
      traps to send.

 * RFC1213_MIB_IMPL.java: Instrumentation of the mibgen generated MIB.
        Demonstrates how to extend the generated MIB in order to provide
        instrumentation code.
    - Extends the RFC1213_MIB class originally generated by mibgen for
      representing the subset MIB II.
    - Redefines the factory methods in order to instantiate InterfacesImpl,
      SnmpImpl and SystemImpl objects instead of Interfaces, Snmp and
      System objects.

 * InterfacesImpl.java: Instrumentation of the mibgen generated Interfaces
        group. Demonstrates how to extend a generated Group in order to
        provide instrumentation code.
    - Is an implementation example of the interfaces group defined in MIB II.
    - Shows how to extend the generated Interfaces class in order to
      plug custom code.
    - Declares TableEntryListenerImpl as listener to add or remove table
      entries.

 * SnmpImpl.java: Instrumentation of the mibgen generated Snmp
        group. Demonstrates how to extend a generated Group in order to
        provide instrumentation code.
    - Is an implementation example of the Snmp group defined in MIB II.
    - Shows how to extend the generated Snmp class in order to
      plug custom code.

 * SystemImpl.java: Instrumentation of the mibgen generated System
        group. Demonstrates how to extend a generated Group in order to
        provide instrumentation code.
    - Is an implementation example of the System group defined in MIB-II.
    - Shows how to extend the generated System class in order to
      plug custom code.

 * IfEntryImpl.java: Instrumentation of the mibgen generated IfEntry
        table entries. Demonstrates how to extend generated table entries
        in order to provide instrumentation code.
    - Is an implementation example of the ifEntry entry defined in MIB-II.
    - Shows how to extend the generated IfEntry class in order to
      plug custom code.
    - Sends SNMP traps.

 * TableEntryListenerImpl.java: Utility class.
    - Is an implementation example of a NotificationListener allowing you to
      receive SnmpTableEntryNotification when an entry is added or removed
      from ifTable table.

 * SnmpPduFactoryImpl.java: Utility class, used to add an extra security
        layer to SecureAgent. Refer to SnmpPduFactorySpec.html for more
        information.
    - Is a simple implementation of the SnmpPduFactory interface which
      rejects the pdus sent by certain hosts.

 * LinkTrapGenerator.java: Utility Class
    - Is an implementation example of an SNMP trap generator for a given
      interface.

 * jdmk.acl: ACL file.
    - Is an ACL file that you must customize to enable the agent to send
      SNMP traps (see Section 4).

 * mib_II.txt: Not used in this example, but provided as a reference in
        order to understand mib_II_subset.txt
    - Contains the standard definition of MIB II.

 * mib_II_subset.txt: Used to generate the MIB with mibgen.
    - Contains the subset of mib_II.txt that defines the system, snmp, and
      interfaces groups.

 Note : For more information on the specification of the SnmpPduFactory
        interface you can refer to SnmpPduFactorySpec.html.

In addition the following files show how to instantiate a V3 agent:

 * AgentV3.java:          Simple V3 agent, with authNoPriv. See READMEV3.
 * AgentEncryptV3.java:   Simple V3 agent, with authPriv. See READMEV3.
 * MultipleAgentV3.java:  Two V3 agents in a single application. See READMEV3.


-----------------------------------------------------------------------
3. Building and Running the Example
-----------------------------------------------------------------------

To build and run this example, make sure that your PATH environment variable
is correctly set to use the Java 2 SDK, Standard Edition 1.4 or later.

On J2SE 1.4, your CLASSPATH must contain the jar files for the JMX runtime
(jmx.jar) and the Java DMK runtime (jdmkrt.jar), as well as the current
directory (.) and your PATH must contain the path to the mibgen script
('mibgen' on Unix platforms and 'mibgen.bat' on Windows platforms). The
mibgen script is located in the bin directory in the Java DMK installation.

On J2SE 1.5, your CLASSPATH must contain the jar files for the Java DMK runtime
(jdmkrt.jar), as well as the current directory (.) and your PATH must contain
the path to the mibgen script ('mibgen' on Unix platforms and 'mibgen.bat' on
Windows platforms). The mibgen script is located in the bin directory in the
Java DMK installation.

These instructions assume the classpath is set in an environment variable,
though it may also be given on the command line with the -classpath option.

Copy the example source files to your working directory and type the following
commands:

    cd <WORKING_DIR>

    mibgen -d . mib_II_subset.txt

    javac -d . *.java

To run the version of the example you have just built, type the following
commands:

    # Make sure that no agents are already running
    # and start the agent:

    java Agent [nb_traps]
-or-
    java SecureAgent [refused_hosts]
-or-
    java StandAloneSnmpAgent [nb_traps]

The Java DMK agent is now running on your machine. To manage the agent
through a Web browser, load the following URL: http://localhost:8082/

Note:

    If you want to build and run the V3 agent examples, refer to READMEV3.


-----------------------------------------------------------------------
4. Enabling SNMP traps (optional)
-----------------------------------------------------------------------

To enable SNMP traps, type the following commands:

    # Log in as root or become superuser (for Unix only):
    su

    # Copy the ACL file into the predefined location:

    # Running the example on a Unix platform with Java 2:
    cp jdmk.acl <INSTALL_DIR>/SUNWjdmk/5.1/etc/conf/jdmk.acl
-or-
    # Running the example on a Windows platform with Java 2:
    copy jdmk.acl <INSTALL_DIR>\SUNWjdmk\5.1\etc\conf\jdmk.acl

    # Customize the ACL file by replacing "yourmanager"
    # with the hostname of your manager.

Also, instead of using the default location of the jdmk.acl file,
you can specify it in the command line as follows:

    # Running the example on a Unix platform with Java 2:
    java -Djdmk.acl.file=<WORKING_DIR>/jdmk.acl Agent [nb_traps]
-or-
    # Running the example on a Windows platform with Java 2:
    java -Djdmk.acl.file=<WORKING_DIR>\jdmk.acl Agent [nb_traps]
