<!-- ...................................................................... -->
<!-- $Id: plugin_usage.sgml,v 1.10 2009/01/19 07:36:20 subrata_modak Exp $ ........................................ -->
<!-- 
        (C) Copyright IBM Corp. 2003
        (C) Copyright FORCE Computers 2004
 
        Authors:
            Sean Dague
            Thomas Kanngieser
	    Renier Morales

        This material may be distributed only subject to the terms and 
        conditions set forth in the Open Publication License, v1.0 or later 
        (the latest version is currently available at 
        http://www.opencontent.org/openpub/).  Distribution of substantively 
        modified version of this document is prohibited without the explicit 
        permission of the copyright holder.

        Other company, product, or service names may be trademarks or service 
        marks of others.
-->

  <chapter>
  <title>OpenHPI Plugin Usage<anchor id="plugin-usage"></title>
  <para>
    This chapter is an overview of the existing plugins for OpenHPI,
    and how one needs to configured them for usage.  It is expected
    that this will grow over time as new plugins are added.
  </para>
  <sect1>
    <title>General Configuration</title>
    <para>
      To add a plugin for usage by OpenHPI one has to add at least 2
      stanzas to the <literal>/etc/openhpi/openhpi.conf</literal>
      file.  These are a <literal>plugin</literal> and
      <literal>handler</literal> stanza.  An example configuration
      file is shown below.
    </para>
    <para>
  <programlisting role="config">
# Sample /etc/openhpi/openhpi.conf
# comments start with # character

plugin libdummy

handler libdummy {
          entity_root = "{ROOT,0}{SYSTEM_CHASSIS,2}"
}          

plugin libsnmp_bc

handler libsnmp_bc {
	  version = "1"
          community = "mypass"
          host = "10.0.0.1"
          entity_root = "{ROOT,0}{SYSTEM_CHASSIS,0}"
}

handler libsnmp_bc {
	  version = "1"
          community = "mypass"
          host = "10.0.0.21"
          entity_root = "{ROOT,0}{SYSTEM_CHASSIS,1}"
}
  </programlisting>
    </para>
    <para>
      The <literal>plugin</literal> stanza tells OpenHPI that there is
      a plugin file of the name libsnmp_bc.la in the
      LTDL_LIBRARY_PATH that it should load on startup.  This path
      defaults to /usr/lib:/usr/local/lib.
    </para>
    <para>
      The <literal>handler</literal> stanza creates and instance of an
      OpenHPI plugin.  It includes a block stanza which lets the
      plugin take those configuration stanzas that it wishes, and use
      them for instantiation.  At minimum, the entity_root must be
      specified to instruct OpenHPI where in the Entity hierarchy the
      entities discovered by the handler should go.
    </para>
  </sect1>
  <sect1>
    <title>Dummy Plugin</title>
    <para>
      The Dummy Plugin is a test plugin that was first used to test
      the infrastructure.  It is still useful for testing a new
      feature in the infrastructure without having hardware supported
      by OpenHPI.
    </para>
    <sect2>
      <title>Prerequisites</title>
      <para>
        None.  The dummy plugin consists of static data specified
        within the plugin.  It requires no special hardware or
        software to run.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
        There is no required configuration for the dummy plugin (I
        know this isn't true, but I'll leave this for someone else to write).
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>SNMP BladeCenter Plugin</title>
    <para>
      The SNMP BladeCenter plugin is an SNMP based interface to IBM's
      BladeCenter hardware.  Technical information about BladeCenter
      can be found at <ulink
        url="http://www-1.ibm.com/servers/eserver/bladecenter/"
        >the BladeCenter Home Page</ulink>.
      
    </para>
    <para>
      This plugin is called <literal>snmp_bc</literal> in the OpenHPI tree, and is
      referenced by the name <literal>libsnmp_bc</literal> in all
      OpenHPI configuration files.
    </para>
    <sect2>
      <title>Prerequisites</title>
      <para>
        The snmp_bc plugin is built by default in the
        OpenHPI build process.  To disable the building of this plugin,
        add the configure flag
        <literal>--disable-snmp_bc</literal> during the configure
        process.
      </para>
      <para>
        snmp_bc relies on Net-SNMP >= 5.0.  Most testing has
        been done with >= 5.0.7, so the latest version available for
        your distribution is recommended.
      </para>
      <para>
        The BladeCenter's Management Module firmware is required 
        to be at Version 1.08 or later. The latest version of the Management
        Module's firmware can be found at IBM's
        <ulink
          url="http://www-1.ibm.com/servers/eserver/support/xseries/index.html"
          >XSeries Support Page</ulink> under the Downloads link.
        Instructions are included there for upgrading the firmware.
      </para>
      <para>
        Once the firmware is updated, SNMP access must be enabled 
        using the Management Module web interface. 
	Details and up-to-date instruction on setting up BladeCenter SNMP agent can be found at IBM's
        <ulink
          url="http://www-1.ibm.com/servers/eserver/support/xseries/index.html"
          >XSeries Support Page</ulink> under Redbooks link, search for BladeCenter.
	Then look in 
        <ulink
          url="http://www.redbooks.ibm.com/redpapers/pdfs/redp3582.pdf"
          >IBM eServer BladeCenter Systems Management, REDP-3582-00;</ulink> 
	IBM  BladeCenter Management Module Web GUI.
      </para>
      <para>
	SNMP v1 is supported in both BladeCenter Enterprise and BladeCenter Telco.
        For SNMP v1, in the web interface, (a) set MM Control - General Settings.
	(b) Set MM Control - Network Protocols,  there are fields to 
        enable snmpv1, fields to  set the community string (i.e. password) and up
        to 3 allowed hosts per community to connect to the Management Module.
        Ensure that the host running OpenHPI is included in the list
        of allowed hosts.
      </para>
      <para>
	SNMP v3 is supported in BladeCenter Telco.  SNMP v3 is <emphasis>currently not</emphasis> 
	available in BladeCenter Enterprise.
        For snmpv3, in the web interface, (a) set MM Control - General Settings.
	(b) Set MM Control - Login Profiles, select a paticular userid then follow the link
	at the end of user info page to Configure SNMPv3 User. 
	(c) Set MM Control - Network Protocols,  there is field to enable SNMP v3.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
        Below is an example configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libsnmp_bc

handler libsnmp_bc {
        entity_root = "{SYSTEM_CHASSIS,4}" # Required
        host = "bc.ibm.com" # Required
        community = "community" # Version 1 Required.
        version = "1" # Required. SNMP protocol version (1|3)
        security_name = "snmpv3_user" # Version 3 Required.
        passphrase = "opensesame" # Version 3. Required for security_level authNoPriv or authPriv.
        auth_type = "MD5" # Version 3. Passphrase encoding (MD5|SHA)
        security_level = "noAuthNoPriv" # Version 3 (noAuthNoPriv|authNoPriv|authPriv)
}
            </programlisting>
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>SNMP RSA Plugin</title>
    <para>
      The SNMP RSA plugin is an SNMP based interface to IBM's
      Remote Supervisor Adapter hardware.  Technical information about RSA
      is best found at <ulink
        url="http://www-1.ibm.com/support/docview.wss?rs=0&amp;q1=remote+supervisor+adapter&amp;uid=psg1MIGR-4UKSML&amp;loc=en_US&amp;cs=utf-8&amp;cc=us&amp;lang=en"
        >the RSA Overview
        Page</ulink>.
      
    </para>
    <para>
      This plugin is called <literal>snmp_rsa</literal> in the OpenHPI tree, and will be
      referenced by the name <literal>libsnmp_rsa</literal> in all
      OpenHPI configuration files.
    </para>
    <sect2>
      <title>Prerequisites</title>
      <para>
        The snmp_rsa plugin is built by default in the
        OpenHPI build process.  To disable the building of the
        snmp_rsa module, add the configure flag
        <literal>--disable-snmp_rsa</literal> during the configure
        process.
      </para>
      <para>
        snmp_rsa relies on Net-SNMP >= 5.0.  Most testing has
        been done with >= 5.0.7 so the latest version available for
        your distribution is recommended.
      </para>
      <para>
        The snmp_rsa plugin is function complete with this release but has
        not been fully unit tested. If you discover bugs please contact the
        OpenHPI team.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
        Below is an example configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libsnmp_rsa

handler libsnmp_rsa {
          community = "x440public"
          host = "10.0.0.130"
	  entity_root = "{ROOT,0}{SYSTEM_CHASSIS,1}"
}
            </programlisting>
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>Watchdog Timer Plugin</title>
    <para>
      The watchdog timer plugin provides OpenHPI access to the software
      watchdog timer "softdog" in the Linux kernel.
    </para>
    <para>
      The watchdog plugin follows the standard plugin naming conventions.  It
      is called <literal>watchdog</literal> in the OpenHPI tree and should
      be referenced using <literal>libwatchdog</literal> in OpenHPI configuration
      files.
    </para>
    <para>
      The watchdog plugin code can be tested using <literal>examples/list_resources.c
      </literal> as well as <literal>examples/test_watchdog.c</literal> run as root.
    </para>
    <sect2>
      <title>Prerequisites</title>
      <para>
        As with other plugins, the watchdog plugin needs to be enabled during
        the OpenHPI build process via the configure flag <literal>
        --enable-watchdog</literal> when running ./configure.
      </para>
      <para>
        The watchdog plugin relies on the softdog functionality, which must be
        compiled as a module in the Linux kernel (tested with 2.6 kernel).
      </para>
      <para>
        After the watchdog is compiled, it needs to be inserted using <literal>
        insmod softdog [soft_noboot=1]</literal> as root.  The <literal>
        soft_noboot=1</literal> option can be used during testing so that the
        meachine does not reboot.
      </para>
      <para>
	The watchdog module should be created using <literal>mknod /dev/watchdog 
        c 10 130</literal> as root.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
        Below is an example configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libwatchdog

handler libwatchdog {
          name="0"
          addr="/dev/watchdog"
          entity_root = "{ROOT,0}{SYSTEM_CHASSIS,0}"
}
        </programlisting>
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>Sysfs Plugin</title>
    <para>
      The sysfs plugin provides access to the devices on the i2c bus that are
      exposed by sysfs.  This plugin uses libsysfs to access the sysfs data.
    </para>
    <para>
      The sysfs plugin follows the standard plugin naming conventions.  It
      is called <literal>sysfs</literal> in the OpenHPI tree and should
      be referenced using <literal>libsysfs</literal> in OpenHPI configuration
      files.
    </para>
    <para>
      The sysfs plugin code can be tested using <literal>examples/list_resources.c
      </literal> and <literal>examples/set_resources.c</literal>.
    </para>
    <sect2>
      <title>Prerequisites</title>
      <para>
        As with other plugins, the sysfs plugin needs to be enabled during
        the OpenHPI build process via the configure flag <literal>
        --enable-sysfs</literal> when running ./configure.
      </para>
      <para>
        The sysfs plugin in OpenHPI release 0.4 and later relies on libsysfs 
        0.3.0 (found in sysutils 0.3.0) 
        <ulink
          url="http://linux-diag.sourceforge.net/Sysfsutils.html"
          >on the Linux Diagnostic Tools project page</ulink>.
      </para>
      <para>
        The sysfs plugin in release 0.3 relies on libsysfs 0.2.0 (found
        in sysutils 0.2.0) 
        <ulink
          url="http://linux-diag.sourceforge.net/Sysfsutils.html"
          >on the Linux Diagnostic Tools project page</ulink>.
        Source code for the sysfs plugin that works with libsysfs 0.2.0
        can be retrieved from OpenHPI cvs using the tag libsysfs0_2_0.
        libsysfs0.2.0 has two bugs that need to be fixed before using the
	OpenHPI sysfs plugin.  Applying the two patches below (separate, sorry!)
	will fix these.  Both issues are fixed in libsysfs 0.3.0.
	</para>
        <para>
        Patch 1:
        </para>
        <programlisting role="C">
--- sysfsutils-0_2_0/lib/sysfs_device.c.orig    2003-10-17 11:25:37.000000000 -0
700
+++ sysfsutils-0_2_0/lib/sysfs_device.c 2003-10-20 12:41:59.000000000 -0700
@@ -80,6 +80,7 @@
                errno = EINVAL;
                return NULL;
        }
+       strcpy(attrname, name);
        dlist_for_each_data(dev->directory->attributes, cur,
        </programlisting>
        <para>
        Patch 2:
        </para>
        <programlisting role="C">
--- sysfs_dir.c.orig    2003-08-29 04:43:27.000000000 -0700
+++ sysfs_dir.c 2003-11-20 11:28:36.000000000 -0800
@@ -274,6 +274,7 @@
             errno = EINVAL;
             return -1;
        }
+       attr->value = malloc(sizeof(value));
        strncpy(attr->value,value,sizeof(value));
        if ((sysfs_write_attribute(attr) != 0 )) {
             dprintf("Error write to attribute %s\n", attrpath)
        </programlisting>
      <para>
        Follow the libsysfs instructions for installing libsysfs.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
        Below is an example configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libsysfs

handler libsysfs {
          name="0"
          addr="0"
          entity_root = "{ROOT,0}{SYSTEM_CHASSIS,0}"
}
        </programlisting>
      </para>
    </sect2>
  </sect1>
  <sect1>
    <title>IPMI Plugin</title>
    <para>
      The IPMI plugin provides access to resources in IPMI capable systems 
      including Management Controllers (MC), sensors and system event log
	(SEL).
    </para>
    <para>
	The openHpi plug-in requires OpenIPMI library be installed since it
	serves as the middle-ware to accessing the IPMI hardware.
	Currently, we're using the CVS up-to-date code of OpenIPMI.
    </para>
    <para>
	The IPMI plug-in can be tested using the <literal>examples/list_resources</literal>
	program as well as the HPI utils in the <literal>util</literal> directory.
	Currently, <literal>GET</literal> functions are enabled and tested for sensors and
	SEL.
    </para>
  <sect2>
      <title>Prerequisites</title>
    <para>
	The IPMI plug-in can be enabled using the <literal>--enable-ipmi</literal> flage 
	to the <literal>./confiure</literal> script.
    </para>
    <para>
	Before compiling the IPMI plug-in, the OpenIPMI library needs to be installed
	and available on the system.
	You can get OpenIPMI from 
	<ulink 
		url="http://openipmi.sourceforge.net/"
	> the OpenIPMI web site.</ulink>  Though, getting the latest code from CVS is advised.
    </para> 
   </sect2>
   <sect2>
      <title>Configuration</title>
      <para>
	  Currently, the OpenHPI IPMI plug-in supports both <literal>"SMI"</literal>
	  and <literal>"LAN"</literal> access methods to IPMI hardware.
        Below is an example "SMI" configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libipmi

handler libipmi {
	name="smi"
	addr="0"
	entity_root = "{ROOT,0}{SYSTEM_CHASSIS,0}"
}
        </programlisting>
      </para>
	<para>
	   And this is an example "LAN" configuration stanza:
	</para>
	<para>
		<programlisting role="config">
plugin libipmi

handler libipmi {
	name = lan
	addr = "IP.ADDRESS.HERE"
	port = "IPMI LAN PORT NUMBER"
	auth_type = "STRAIGHT, MD2 or MD5"
	auth_level= "USER, OPERATOR or ADMIN"
	username = "YOUR_USER_NAME"
	password = "YOUR_PASSWORD"
	entity_root = "{SYSTEM_CHASSIS,0}"
}
		</programlisting>
	</para>
    </sect2>

  </sect1>
  <sect1>
    <title>IPMI Direct Plugin</title>
    <para>
      The IPMI Direct plugin provides OpenHPI access to ATCA and
      IPMI 1.5 systems. The plugin uses multiple threads to
      communicate to the IPMI hardware. RMCP as well as SMI 
      (access to IPMI divice driver) are supported for IPMI access.
      The following features are supported:
    </para>
    <itemizedlist mark='opencircle'>
      <listitem>
        <para>
          <emphasis>Sensors</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>FRU inventory data reading</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>ATCA hotswapping</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>System event log</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>Power and reset states for ATCA</emphasis>
        </para>
      </listitem>
    </itemizedlist>
    <sect2>
      <title>Prerequisites</title>
      <para>
	The IPMI Direct plugin can be enabled using the <literal>--enable-ipmidirect</literal> flage 
	to the <literal>./configure</literal> script. It is build by default.
        A statical linked version of OpenHPI and IPMI Direct can be build with
        <literal>--enable-ipmidirect=static</literal>.
      </para>
      <para>
        For RMCP password cryption MD2 or MD5 OpenSSL is required.
        OpenSSL is available at	<ulink url="http://www.openssl.org" </ulink>.
      </para>
    </sect2>
    <sect2>
      <title>Configuration</title>
      <para>
	The IPMI Direct plugin supports <literal>"SMI"</literal>
	and <literal>"LAN"</literal> access methods to IPMI or ATCA hardware.
        Below is an example "SMI" configuration stanza:
      </para>
      <para>
        <programlisting role="config">
plugin libipmidirect

handler libipmidirect {
	entity_root = "{ROOT,0}{SYSTEM_CHASSIS,0}"
	name="smi"
	addr="0"
}
        </programlisting>
      </para>
      <para>
	The parameter addr is the device number of the IPMI device.
        For the above example the plugin checks /dev/ipmidev0,
        /dev/ipmi/0 and /dev/ipmi0 for an IPMI device.
      </para>
      <para>
	And this is an example "LAN" or RMCP configuration stanza:
      </para>
      <para>
		<programlisting role="config">
plugin libipmidirect

handler libipmidirect {
	entity_root = "{SYSTEM_CHASSIS,0}"
	name = lan
	addr = "IP.ADDRESS.HERE"
	port = "IPMI LAN PORT NUMBER"
	auth_type = "NONE STRAIGHT, MD2 or MD5"
	auth_level= "USER, OPERATOR or ADMIN"
	username = "YOUR_USER_NAME"
	password = "YOUR_PASSWORD"
	IpmiConnectionTimeout = "5000"
	AtcaConnectionTimeout = "1000"
	MaxOutstanding = "3"
	MCC8= "initial_discover poll_alive poll_dead"
	MCCA= "initial_discover poll_alive poll_dead"
}
		</programlisting>
      </para>
      <para>
	ATCA systems are autodetected. The plugin uses different timeouts
        for IPMI 1.5 and ATCA systems. IpmiConnectionTimeout and AtcaConnectionTimeout
        are timouts in miliseconds.
      </para>
      <para>
        The plugin uses one thread per Managment Controller (MC). The
        maximum outstanding IPMI commands can be given by
        MaxOutstanding. When the plugin has send MaxOutstanding IPMI commands
        it will block until it receives a reply for an outstanding command
        or a timeout happens. Then the next command is send.
      </para>
      <para>
        The MCs in ATCA systems are automatic detected.
        For IPMI 1.5 the plugin needs help by the configuration
        file. Given the line MCCA="initial_discover poll_alive poll_dead"
        the plugin checks for an MC at address CA (hexadecimal) at startup.
        When an MC is found it is alive. poll_alive means that the MC is polled
        once a second to check if the MC is already there. This is to
        check for removal of a FRUs. poll_dead is to check insertion of
        FRUs on IPMI 1.5 systems.
      </para>
      <para>
        More than one handler sections for IPMI Direct plugin are
        supported. The plugin is known to work on i386 and PPC platforms
        under linux.
      </para>
    </sect2>
  </sect1>
</chapter>
