diff -r 683c5c035a79 -r 445e2cf1c845 components/net-snmp-57/sun/sdk/demo/demo_module_10/README_demo_module_10 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/net-snmp-57/sun/sdk/demo/demo_module_10/README_demo_module_10 Fri Dec 11 03:49:26 2015 -0800 @@ -0,0 +1,247 @@ +# +# Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. +# +# U.S. Government Rights - Commercial software. Government users are subject +# to the Sun Microsystems, Inc. standard license agreement and applicable +# provisions of the FAR and its supplements. +# +# +# This distribution may include materials developed by third parties. Sun, +# Sun Microsystems, the Sun logo and Solaris are trademarks or registered +# trademarks of Sun Microsystems, Inc. in the U.S. and other countries. +# +# + +README for demo_module_10 +*********************************************************************** + +This example demonstrates a module design that handles long running +data collections so that their values can be polled by an SNMP manager. +The example also shows how to implement objects that normally would block +the agent as it waits for external events in such a way that the agent can +continue responding to other requests while this implementation waits. + +This example uses the following features of SMA: + +- Setting the delegated member of the requests structure to 1 to indicate to + the agent that this request should be delayed. The agent queues this request + to be handled later and then is available to handle other requests. The + agent is not blocked by this request. + +- Registering an SNMP alarm to update the results at a later time. + +- Use of a status variable to communicate the status of a data collection to + the polling SNMP manager. + +- Use of a refreshTime variable to return the date and time that the data + collection completed. + + +How to Build the demo_module_10 Code Example +============================================ + +The demo_module_10 code example includes the following files, by default +located in the directory /usr/demo/sma_snmp/demo_module_10. + +Files: + +Makefile - makefile to build the demo_module_10.so shared library file +demo_module_10.c - module source code +demo_module_10.h - module header file +SDK-DEMO10-MIB.txt - MIB file +get_status - Script that gets the value of the status variable +get_refreshtime - Script that gets the date and time of the current data +collection get_data - Script that gets the data returned by the data collection +set_data - Script sets the value of the status variable to 0, which starts a +new data collection + +To set up your build environment for the demo: + +1. Copy the demo code to a directory for which you have write permission. + For example: + + % cp -R /usr/demo/sma_snmp/demo_module_10 /home/username/demo + + +2. Create a lib directory that you can use to store shared object libraries + that you generate from demo code examples, if you have not already done so. + For example: + + % mkdir /home/username/demo/lib + + +3. Create a mibs directory that you can use to store MIB files for the demo + code examples, if you have not already done so. + For example: + + % mkdir /home/username/demo/mibs + + +4. Set the CC environment variable to the location of the C compiler to be + used. + For example, if you are using Sun ONE Studio: + + % setenv CC /opt/SUNWspro/bin/cc + + +5. Set your PATH environment variable to include the appropriate paths, so that + needed binaries can be found during the compilation process. + For example, in the csh: + + % setenv PATH .:/usr/bin:$PATH + + +To build the example: + +1. Change to the directory where you copied the demo module files. + For example: + + % cd /home/username/demo/demo_module_10 + + +2. Use the make command to generate object files. + + If you are running the 64-bit SPARC Solaris kernel, type: + % /usr/ccs/bin/make + + If you are running the 32-bit SPARC Solaris kernel, type: + % /usr/ccs/bin/make ARCH=32 + + If you are running the Solaris x86 kernel, type: + % /usr/ccs/bin/make ARCH=32 + + +3. Copy the module shared library object to the lib directory you created. + For example: + + % cp demo_module_10.so /home/username/demo/lib + + +4. Copy SDK-DEMO10-MIB.txt to the mibs directory you created for the demos. + For example: + + % cp SDK-DEMO10-MIB.txt /home/username/demo/mibs + + + + +Setting Up Agent to Run the demo_module_10 Module +================================================= + +1. As root, edit the agent's configuration file /etc/sma/snmp/snmpd.conf, + and insert a dlmod statement for the module. This statement enables the + agent to load the module. + For example: + + dlmod demo_module_10 /home/username/demo/lib/demo_module_10.so + + +2. As root, start the SMA snmp agent. If the agent is already running, + stop and restart it in debug mode. + For example: + + # /etc/init.d/init.sma stop + # /usr/sbin/snmpd -Ddemo_module_10 + + The optional -Ddemo_module_10 argument sends debugging statements from + demo_module_10 to the /var/log/snmpd.log file. You can also use the -L + and -f options to send debugging statements to the screen instead. + + + +Testing the Code Example +======================== + +1. Set your MIBS and MIBDIRS environment variables to + include the appropriate paths. + For example, in the csh: + + % setenv MIBDIRS .:/home/username/demo/mibs:/etc/sma/snmp/mibs + % setenv MIBS +SDK-DEMO10-MIB + + Note that step 1 is not required, but it enables snmpget to access the MIB + to provide variable names instead of OIDs in its output. + + +2. Run the get_status script to get the default value of + the status variable. + + % get_status + SDK-DEMO10-MIB::status.0 = INTEGER: 2 + + An SNMP manager would typically poll the status variable + of devices that generate long running data collections, until + a value 2 is returned, which indicates that the collection is + complete and the data is ready to get. + + status has a default value of 0, which means no data collection + has been started, so the module starts a new collection. + When the collection completes, status is set to 2. + + +3. Run the get_refreshtime script to get the date and time + of the data collection. + + % get_refreshtime + SDK-DEMO10-MIB::refreshTime.0 = STRING: Fri Jul 18 12:36:56 2003 + + After retrieving the date and time, the SNMP manager can decide whether the + date of the data collection is acceptable. If the manager needs more recent + data, it can set the status variable to 0 to start a new collection. In this + example, the manager wants more recent data. + + +4. Set the status variable to 0 to start a new collection, as follows: + + % set_status + SDK-DEMO10-MIB::status.0 = INTEGER: 0 + + Note that SET requests through this object will take longer, + since the delay is applied to each internal transaction phase, + which could result in delays of up to 4 times the value of this object. + + For example, initially, the default value is + 1 second. Therefore, specify a 3 second timeout value on the + snmpset command line. + + +5. Run the get_status script again to get the status value. + + % get_status + SDK-DEMO10-MIB::status.0 = INTEGER: 2 + +6. Run the get_data script to get the data resulting from + the data collection, for example: + + % get_data + SDK-DEMO10-MIB::longRunScalar.0 = INTEGER: 325 + + +7. Open two terminal windows so you can run two scripts at the same time, as + follows: + + In the first window, run the get_status script: + + % get_status + SDK-DEMO10-MIB::status.0 = INTEGER: 2 + + + In the second window, run the walk_demo_module_10 script: + + % walk_demo_module_10 + + SNMPv2-MIB::sysDescr.0 = STRING: SunOS myhost 5.10 s10_35 sun4u + SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-TC::solaris + DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (497128) 1:22:51.28 + SNMPv2-MIB::sysContact.0 = STRING: "Administrator's Name" + SNMPv2-MIB::sysName.0 = STRING: myhost + SNMPv2-MIB::sysLocation.0 = STRING: My Town + SNMPv2-MIB::sysORLastChange.0 = Timeticks: (8) 0:00:00.08 + SNMPv2-MIB::sysORID.1 = OID: IF-MIB::ifMIB + ... + + This example demonstrates that the agent is not blocked and does respond to + the snmpwalk request, while the snmpget request executed in the first + window is still pending. + +