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


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


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

This example shows how to build a standard SNMP V3 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 SNMP V3 API.
It simulates linkUp and linkDown conditions on an Ethernet interface; it does
not try to access or bind with any real resource.

If you are interested in building non-v3 agents (v1-v2 only agents), you
should refer to the README file provided in this example.

In the present file, we will discuss only v3 enabled agents.


-----------------------------------------------------------------------
2. SNMP V3 security configuration
-----------------------------------------------------------------------

Read the READMEV3_security in the Snmp examples directory to be familiar with
the Java DMK 5.1 user-based security configuration. A user named defaultUser
is used in order to send secure requests.

* Authentication only.
userEntry=0x8000002a05819dcb6e00001f95,defaultUser,,usmHMACMD5AuthProtocol,mypasswd

* Authentication and encryption.
userEntry=0x8000002a05819dcb6e00001f95,defaultUser,,usmHMACMD5AuthProtocol,mypasswd,usmDESPrivProtocol,mypasswd

Entry VALUES:
-------------
* 0x8000002a05819dcb6e00001f95 : Agent engine ID.
* defaultUser : User name.
* usmHMACMD5AuthProtocol : HMAC MD5 as the authentication algorithm.
* mypasswd : Authentication password.
* usmDESPrivProtocol : Privacy algorithm.
* mypasswd : Privacy password.


-----------------------------------------------------------------------
3. File List
-----------------------------------------------------------------------

This example is based on the following source files:

 * AgentV3.java: A simple v3 enabled agent, using authentication and
        no privacy.
    - 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.
      The SNMP V3 adaptor accepts authenticated requests.
    - Creates and initializes an SNMP MIB.
      The whole MIB and every group in the MIB are registered with
      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.

* AgentEncryptV3.java: A simple v3 enabled agent, using authentication and
        privacy.
    - 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.
      The SNMP V3 adaptor is accepting authenticated and encrypted requests.
    - 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.

* MultipleAgentV3.java: Multiple v3 enabled agents in the same JVM, using
        authentication and no privacy.
    - Creates an MBean server.
    - Creates and registers an HTML adaptor server in the MBean server.
    - Creates and registers 2 SNMP adaptor servers in the MBean server.
      First adaptor is bound to a non-standard SNMP port (8085).
      Second adaptor is bound to a non-standard SNMP port (8087).
      First adaptor makes use of the jdmk.security file.
      Second adaptor makes use of the jdmk2.security file.
      The SNMP V3 adaptors accept authenticated requests.
    - Creates and initializes 2 SNMP MIBs.
      Each 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.

 * RFC1213_MIB_IMPL.java: Instrumentation of the mibgen generated MIB.
        Demonstrates how to extend the generated MIB in order to provide
        instrumentation code. Note that the instrumentation of the MIB
        does not depend on whether the agent is v1, v2, or v3. We thus
        reuse the MIB that was developed for the v1/v2 agents with no
        changes.
    - 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.
        Note that the instrumentation of the mibgen generated classes does
        not depend on whether the agent is v1, v2, or v3. We thus
        re-use the innstrumentation that was developed for the v1/v2
        agents with no changes.
    - 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 added/removed table
      entries.

 * SnmpImpl.java: Instrumentation of the mibgen generated Snmp
        group. Demonstrates how to extend a generated Group in order to
        provide instrumentation code.
        Note that the instrumentation of the mibgen generated classes does
        not depend on whether the agent is v1, v2, or v3. We thus
        reuse the innstrumentation that was developed for the v1/v2
        agents with no changes.
    - 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.
        Note that the instrumentation of the mibgen generated classes does
        not depend on whether the agent is v1, v2, or v3. We thus
        reuse the innstrumentation that was developed for the v1/v2
        agents with no changes.
    - 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.
        Note that the instrumentation of the mibgen generated classes does
        not depend on whether the agent is v1, v2, or v3. We thus
        reuse the innstrumentation that was developed for the v1/v2
        agents with no changes.
    - 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 V1 and V3 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.

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

 * jdmk.security : security configuration to receive authenticated
                   only requests.

 * jdmkencrypt.security : security configuration to receive
                          authenticated and encrypted requests.

 * jdmk.acl: ACL file.
    - Is an ACL file that you must customize to enable the agent to send
      SNMP V1, V2 or V3 traps (see Section 6).

 * 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.


-----------------------------------------------------------------------
4. Building the Example
-----------------------------------------------------------------------

To build 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


-----------------------------------------------------------------------
5. Running the Example
-----------------------------------------------------------------------

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:

* Simple agent without encryption:
---------------------------------
    java -Djdmk.security.file=jdmk.security AgentV3 [nb_traps]

 NB : Be sure to launch the agent in the <WORKING_DIR> directory.
      The jdmk.security file is searched in the current directory.

* Simple agent with encryption:
------------------------------
    java -Djdmk.security.file=jdmkencrypt.security AgentEncryptV3 [nb_traps]

 NB : Be sure to launch the agent in the <WORKING_DIR> directory.
      The jdmkencrypt.security file is searched in the current directory.

* Multiple agents without encryption:
-------------------------------------
  A multiple agent is an agent instantiating more than one SnmpV3AdaptorServer.
  One SnmpV3AdaptorServer uses the security file provided with the Java property
  jdmk.security.file. The second adaptor uses a different jdmk2.security file
  that is located in the current directory. The jdmk2.security file is passed
  directly to the SnmpV3AdaptorServer when it is instantiated.

    java -Djdmk.security.file=jdmk.security MultipleAgentV3

 NB : Be sure to launch the agent in the <WORKING_DIR> directory.
      The jdmk.security and jdmk2.security files are searched in the current
      directory.

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/


-----------------------------------------------------------------------
6. Configuring User ACL.
-----------------------------------------------------------------------

A user ACL file jdmk.uacl is located in this examples' directory. It 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.

Launch the agent :

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