Intel Corporation 2008 
********************************************************************************
Plugin Extension for CIM v1.0 README
********************************************************************************


    CONTENT
================================================================================ 

    o What is Plugin Extension for CIM
    o Build Pre-requisites
    o Provider Installation
    o Plugins Configuration
    o Test
    o Credits

    
    What is Plugin Extension for CIM  
================================================================================

Plugin Extension for CIM (aka PEC) is an effort to expose Nagios plug-ins
through the Common Information Model (CIM).
This work is based on the presentation done by Rodolfo kohn (Intel Software de
Argentina) and Sebastian Ganame (Nexius) in the Management Developers Conference 
in Santa Clara, in December 2007.
This presentation is included in the distribution.

This solution has a client and an indication provider. The client (pecloader.pl)
checks and loads the parameters of a plug-in by command line. The plug-in 
configuration is stored in the CIM repository by the CIM Server upon creation 
of each instance by the client (pecloader.pl). Each plug-in has parameters
and options to configure the way they are executed. Each 
plug-in could have one or more functionalities. A plug-in running with a 
specific functionality can be used either to detect events and send indications
 or to get a property value of a class (the latter feature is not implemented yet). 
When a subscription is created by a client, the PEC indication provider 
reads the appropriate plug-ins configuration, based on the type of indication 
subscribed to, and executes each plug-in in a different thread. 
The PEC indication provider reads the configuration data for each plug-in and 
executes it using that data.
PEC carries out a validity check in the plug-ins before loading them: it checks
the correctness and completion of all the data.

To let plug-in to subscribe to some of the events, the filter was implemented in
the provider.
These filters can include the following logical operators: AND, OR, NOT, >, <, =. 
The attributes from which it can be filtered are IndicationIdentifier and
SourceClass. An example of a filter can be seen below:

"SELECT * FROM CIM_AlertIndication WHERE IndicationIdentifier>'0xFFE0091' AND
SourceClass='CIM_Process"

The provider is cmpi compliant. However the installation works and is tested only with SBLIM sfcb.

    Build Pre-requisites
================================================================================

Dependent Package Installation:
This provider and it's tools needs the following packages, probed to work with 
at least the following versions.

    1.cURL  tool distribution, version 7.16.1
    2.DMTF CIM Schema version 2.15 
    3.SBLIM sfcc (small footprint CIM client) version 2.1.0 (also tested with 2.2.1)
    4.SBLIM sfcb (small footprint CIM broker) version 1.3.2 (also tested with 1.3.6)
    6.Nagios plugins 1.4.11

These packages should be installed as instructed by the distribution.
In the case of the Nagios software it does not need to be installed ,but is 
required to download the plugins to a selected folder.


CMPI header files need to be installed in a directory accessible in the include
path. For example: /usr/local/include/cmpi
SFCC header files need to be installed and are needed by client files.

You may need to include /usr/local/lib and /usr/local/lib/cmpi in the library 
search path for ld.
----------------------------------------------------------------------------------
THIS IS NECESSARY FOR SFCBD TO LOCATE THE PEC PROVIDER AND FOR CLIENT COMPILATION.
----------------------------------------------------------------------------------

export LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib/cmpi


    Provider Installation
================================================================================ 
1.At the top directory of the distribution, perform the normal install procedure:

    ./configure
    make
    make install
    make postinstall

The configure scripts accept the following parameters in order to manipulate the
installing procedure:

    --enable-debug This parameter instructs the distribution to add debugging
    information in the provider to be displayed in a terminal.
    
    --prefix= 'path' Sets the installation location to 'path'  

Note: by default it installs using prefix /usr/local . PEC has not been tested
with other prefix and this may have errors that need to be fixed.
    
2.For the CIM Server, for example sfcbd, it is necessary to set the environment 
variable "PEC_PLUGIN_PATH" with your path to where the NAGIOS plug-ins have been 
installed. If not set, it takes the default in '/usr/local/bin/plugins'

-------------------------------------------------------------------------------
THIS IS NECESSARY FOR PEC PLUGIN TO LOCATE THE PLUGINS TO EXECUTE. OTHERWISE
IT WILL NOT FIND THE PLUGINS
-------------------------------------------------------------------------------

Example: 
export PEC_PLUGIN_PATH=/usr/local/bin/plugins



3.Create the file /usr/local/etc/pec.conf and edit the configurations of the
client tool.
The available options configure are:
USER: The user used for the connection
PASSWORD: The password related to the current user.
CIM_SERVER: The address of the node where the CIM server runs.

E.g.:

    USER=myuser
    PASSWORD=mypasswd
    CIM_SERVER=localhost

Note: this file is created by default in /usr/loca/etc with 'make install'. You
can edit and modify it.

4.Postinstall (make postinstall) is to install required mof files and registration files in the sfcb repository

    Plugins Configuration
================================================================================ 
    
    Edit and Config pecplugin.conf in /client, above is an example for one
    plugin:
    
    [PLUGIN]
    Name=check_procs
    Optargs="-w 0 -c 30 --metric=CPU"
    Functionality="Check processes processor usage"
    SWElemID=1
    Mode=Indication
    FunctionalityInstanceID=check_procs
    IndicationID=0xFFEF0091
    ProbableCause="Process consuming too much CPU"
    Frequency=5
    SourceClass=CIM_Process

    Is important to have in mind that the same plugin allows multiple functiona-
    lities, because of this the SWElemID must remain the same for each functio-
    nality in the same plugin.
    
    E.g:
    
    [PLUGIN]
    Name=check_procs
    Optargs="-w 0 -c 30 --metric=CPU"
    Functionality="Check processes processor usage 1"
    SWElemID=1
    Mode=Indication
    FunctionalityInstanceID=check_procs_1
    IndicationID=0xFFEF0091
    ProbableCause="Process consuming too much CPU 1"
    Frequency=5
    SourceClass=CIM_Process
    
    [PLUGIN]
    Name=check_procs
    Optargs="-w 2 -c 20 --metric=CPU"
    Functionality="Check processes processor usage 2"
    SWElemID=1
    Mode=Indication
    FunctionalityInstanceID=check_procs_2
    IndicationID=0xFFEF0092
    ProbableCause="Process consuming too much CPU 2"
    Frequency=5
    SourceClass=CIM_Process
    
    
    Test    
================================================================================ 

    1.Each time you run the pectest with different plugins configuration you
      need to kill the sfcb daemon and repos to the sfcb broker to clean the
      previous plugins loaded.
      E.g: killall -9 sfcbd sfcbrepos -f
    2.Restart the sfcb daemon.
      E.g.:sfcbd&
    3.Run ./pecloader.pl script in /client folder to load pecplugin.conf
      plugins and its parameters.
    4.Run ./pectest in /client folder to test the subscription to indications.
 
 
 Credits:
================================================================================ 
 
 Rodolfo Kohn       rodolk@yahoo.com
 Marcelo Lorenzati
 Miriam Estela
