1 #

     2 # Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

     3 #

     4 # U.S. Government Rights - Commercial software. Government users are subject

     5 # to the Sun Microsystems, Inc. standard license agreement and applicable

     6 # provisions of the FAR and its supplements.

     7 #

     8 #

     9 # This distribution may include materials developed by third parties. Sun,

    10 # Sun Microsystems, the Sun logo and Solaris are trademarks or registered

    11 # trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

    12 #

    13 #

    14 

    15 README for demo_module_10

    16 ***********************************************************************

    17 

    18 This example demonstrates a module design that handles long running

    19 data collections so that their values can be polled by an SNMP manager.  

    20 The example also shows how to implement objects that normally would block 

    21 the agent as it waits for external events in such a way that the agent can 

    22 continue responding to other requests while this implementation waits.

    23 

    24 This example uses the following features of SMA:

    25 

    26 - Setting the delegated member of the requests structure to 1 to indicate to 

    27   the agent that this request should be delayed.  The agent queues this request

    28   to be handled later and then is available to handle other requests.  The

    29   agent is not blocked by this request.

    30 

    31 - Registering an SNMP alarm to update the results at a later time. 

    32 

    33 - Use of a status variable to communicate the status of a data collection to

    34   the polling SNMP manager.

    35 

    36 - Use of a refreshTime variable to return the date and time that the data 

    37   collection completed.

    38 

    39 

    40 How to Build the demo_module_10 Code Example

    41 ============================================

    42 

    43 The demo_module_10 code example includes the following files, by default 

    44 located in the directory /usr/demo/sma_snmp/demo_module_10.

    45 

    46 Files:

    47 

    48 Makefile - makefile to build the demo_module_10.so shared library file

    49 demo_module_10.c  - module source code

    50 demo_module_10.h - module header file

    51 SDK-DEMO10-MIB.txt - MIB file

    52 get_status - Script that gets the value of the status variable

    53 get_refreshtime - Script that gets the date and time of the current data 

    54 collection get_data - Script that gets the data returned by the data collection

    55 set_data - Script sets the value of the status variable to 0, which starts a 

    56 new data collection

    57 

    58 To set up your build environment for the demo:

    59 

    60 1. Copy the demo code to a directory for which you have write permission.

    61    For example:

    62 

    63    % cp -R /usr/demo/sma_snmp/demo_module_10  /home/username/demo

    64 

    65 

    66 2. Create a lib directory that you can use to store shared object libraries 

    67    that you generate from demo code examples, if you have not already done so. 

    68    For example:

    69    

    70    % mkdir /home/username/demo/lib

    71 

    72     

    73 3. Create a mibs directory that you can use to store MIB files for the demo 

    74    code examples, if you have not already done so. 

    75    For example:

    76 

    77    % mkdir /home/username/demo/mibs

    78 

    79 

    80 4. Set the CC environment variable to the location of the C compiler to be 

    81    used.

    82    For example, if you are using Sun ONE Studio:

    83    

    84    % setenv CC /opt/SUNWspro/bin/cc

    85 

    86 

    87 5. Set your PATH environment variable to include the appropriate paths, so that

    88    needed binaries can be found during the compilation process. 

    89    For example, in the csh: 

    90     

    91    % setenv PATH .:/usr/bin:$PATH

    92    

    93    

    94 To build the example:

    95 

    96 1. Change to the directory where you copied the demo module files. 

    97    For example:

    98 

    99    % cd /home/username/demo/demo_module_10

   100    

   101 

   102 2. Use the make command to generate object files.

   103   

   104    If you are running the 64-bit SPARC Solaris kernel, type:

   105    % /usr/ccs/bin/make

   106    

   107    If you are running the 32-bit SPARC Solaris kernel, type:

   108    % /usr/ccs/bin/make ARCH=32

   109    

   110    If you are running the Solaris x86 kernel, type:

   111    % /usr/ccs/bin/make ARCH=32

   112    

   113 

   114 3. Copy the module shared library object to the lib directory you created. 

   115    For example:

   116 

   117    % cp demo_module_10.so /home/username/demo/lib

   118 

   119    

   120 4. Copy SDK-DEMO10-MIB.txt to the mibs directory you created for the demos.

   121    For example:

   122   

   123    % cp SDK-DEMO10-MIB.txt /home/username/demo/mibs

   124    

   125        

   126 

   127 

   128 Setting Up Agent to Run the demo_module_10 Module

   129 =================================================

   130 

   131 1. As root, edit the agent's configuration file /etc/sma/snmp/snmpd.conf,

   132    and insert a dlmod statement for the module. This statement enables the 

   133    agent to load the module.

   134    For example:

   135    

   136    dlmod demo_module_10 /home/username/demo/lib/demo_module_10.so

   137     

   138     

   139 2. As root, start the SMA snmp agent. If the agent is already running, 

   140    stop and restart it in debug mode.

   141    For example:

   142    

   143    # /etc/init.d/init.sma stop

   144    # /usr/sbin/snmpd -Ddemo_module_10

   145     

   146    The optional -Ddemo_module_10 argument sends debugging statements from 

   147    demo_module_10 to the /var/log/snmpd.log file. You can also use the -L 

   148    and -f options to send debugging statements to the screen instead.   

   149 

   150 

   151    

   152 Testing the Code Example

   153 ========================

   154 

   155 1. Set your MIBS and MIBDIRS environment variables to

   156    include the appropriate paths.  

   157    For example, in the csh: 

   158     

   159    % setenv MIBDIRS .:/home/username/demo/mibs:/etc/sma/snmp/mibs

   160    % setenv MIBS +SDK-DEMO10-MIB

   161    

   162    Note that step 1 is not required, but it enables snmpget to access the MIB

   163    to provide variable names instead of OIDs in its output.

   164    

   165    

   166 2. Run the get_status script to get the default value of 

   167    the status variable.

   168    

   169    % get_status

   170    SDK-DEMO10-MIB::status.0 = INTEGER: 2

   171 

   172    An SNMP manager would typically poll the status variable

   173    of devices that generate long running data collections, until

   174    a value 2 is returned, which indicates that the collection is 

   175    complete and the data is ready to get.

   176 

   177    status has a default value of 0, which means no data collection

   178    has been started, so the module starts a new collection.

   179    When the collection completes, status is set to 2.

   180 

   181 

   182 3. Run the get_refreshtime script to get the date and time

   183    of the data collection.

   184    

   185    % get_refreshtime

   186    SDK-DEMO10-MIB::refreshTime.0 = STRING: Fri Jul 18 12:36:56 2003

   187    

   188    After retrieving the date and time, the SNMP manager can decide whether the

   189    date of the data collection is acceptable. If the manager needs more recent

   190    data, it can set the status variable to 0 to start a new collection. In this

   191    example, the manager wants more recent data.

   192 

   193 

   194 4. Set the status variable to 0 to start a new collection, as follows:

   195 

   196    % set_status

   197    SDK-DEMO10-MIB::status.0 = INTEGER: 0

   198 

   199    Note that SET requests through this object will take longer, 

   200    since the delay is applied to each internal transaction phase,

   201    which could result in delays of up to 4 times the value of this object.

   202 

   203    For example, initially, the default value is

   204    1 second. Therefore, specify a 3 second timeout value on the

   205    snmpset command line.

   206    

   207 

   208 5. Run the get_status script again to get the status value.

   209 

   210    % get_status

   211    SDK-DEMO10-MIB::status.0 = INTEGER: 2

   212 

   213 6. Run the get_data script to get the data resulting from

   214    the data collection, for example:

   215 

   216    % get_data

   217    SDK-DEMO10-MIB::longRunScalar.0 = INTEGER: 325

   218 

   219 

   220 7. Open two terminal windows so you can run two scripts at the same time, as

   221    follows:

   222 

   223    In the first window, run the get_status script:

   224    

   225    % get_status

   226    SDK-DEMO10-MIB::status.0 = INTEGER: 2

   227    

   228    

   229    In the second window, run the walk_demo_module_10 script:

   230 

   231    % walk_demo_module_10

   232    

   233    SNMPv2-MIB::sysDescr.0 = STRING: SunOS myhost 5.10 s10_35 sun4u

   234    SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-TC::solaris

   235    DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (497128) 1:22:51.28

   236    SNMPv2-MIB::sysContact.0 = STRING: "Administrator's Name"

   237    SNMPv2-MIB::sysName.0 = STRING: myhost

   238    SNMPv2-MIB::sysLocation.0 = STRING: My Town

   239    SNMPv2-MIB::sysORLastChange.0 = Timeticks: (8) 0:00:00.08

   240    SNMPv2-MIB::sysORID.1 = OID: IF-MIB::ifMIB

   241    ...

   242 

   243    This example demonstrates that the agent is not blocked and does respond to

   244    the snmpwalk request, while the snmpget request executed in the first 

   245    window is still pending.

   246 

   247