Aperi Agent Design R2

Introduction

The Aperi agent is derived from the IBM TotalStorage Productivity Center, TPC, v3.1 agent. The Aperi R1 agent included a subset of the TPC for Data agent functions. It is able to gather host and filesystem data, execute scripts, and generate batch reports. In release R2 we will add TPC for Fabric features to the Aperi agent and make the Data agent extensible. The agent will also be modified to take advantage of the connector and update manager.

Extensibility

It is difficult to extend the functionality of the current Aperi code because it is heavily dependent on switch statements and hard-coded constants. Extending Aperi function often requires modifying multiple files in the Aperi code base. This style of programming is used throughout the product but is predominant in the Data components (server, agent, and GUI).

In this release we will start making the Data agent extensible by replacing the existing logic with extension points. When we started this effort we found it difficult to determine exactly what portions of the code need to be extensible. After all, the Aperi project is still getting started and we don't know what types of features will be added. So, for this release we set out with the goal of adding sufficient agent extension points to allow someone to add a new probe, scan, or discovery job without modifying the Aperi source code.

Note: This document only covers the extensibility of the Data agent functions. It does not cover topics such as adding a new subagent. A new subagent can be added using the extensibility features provided by the Equinox container. See the Aperi Architecture Document for details.

Inband Fabric Agent

In this release we will add the features from the TPC for Fabric 3.1 agent to the Aperi agent.

Connector

The connector is a common component that is used for remote invocation of Aperi services. A complete description of the connector can be found Aperi Connector Design R2. In summary, the connector provides the ability to invoke OSGi services remotely and to create a raw socket connection to an OSGi service.

The Aperi agent will use both services provided by the connector. The Fabric subagent will use OSGi services for remote invocation and the Data subagent will use the SocketHandler extension point to accept secure socket connections.

Update Manager

The patch management infrastructure will be provided as a common component that can be used by the server, agent and GUI. The agent will need to leverage this common component so the user can update agent features. This document will be updated when the Aperi Update Manager Design R2 had been completed.

Features

Inband Fabric Agent

In TPC 3.1 the Fabric agent consists of six services:

Service	Description	Interface
Configuration	The configuration service manages the configuration of Fabric services. Configuration parameters can be retrieved and set using this service.	ISANDBParmsServiceR2
HostQuery	The Host Query service sends a heartbeat to the Device server at a regular interval which indicates that the Fabric agent is running. It also make host information available to the Device server.	IHostQuery
Scanner	Gathers topology and attribute information from the SAN using inband queries	IScanner
Inband Zone control	Configure zones and zonesets on FC switches. The following actions are supported: Create and delete a zone, Create and delete a zoneset, Add and delete zone members, Activate and deactivate a zoneset, Add and remove a zone to/from a zoneset	IZoneControlAgent
Inband change agent	Receives fabric change events and forwards them to the event correlator running on the device server. The change agent subscribes to the following fabric events: LinkUp, LinkDown, LIPReinitalize, LIPReset, RSCN, UnknownEvent	IChangeAgent
Log	Configures the trace and message log configuration	ICliDispatcher

When these services are added to the Aperi agent they will be packaged in the org.eclipse.aperi.agent.fabric plugin and exposed as OSGi services. No major changes should be required to the existing service implementation.

Connector

In this release the Fabric and Data subagents will be modified to use connector. This will allow both subagents to receive incoming requests on the same port and allow the communication to be secured using SSL. See the connector design Aperi Connector Design R2 for details.

Fabric

When the org.eclipse.aperi.agent.fabric plugin registers the fabric services with the container the connector will automatically enable these services to be invoked remotely. However, the connector can only serialize a limited set of objects, by default, and I would like to avoid the use of custom serializers. So, some of the existing data classes used by the fabric services need to be converted into JavaBeans.

The following data classes need to be converted to JavaBeans so they can be serialized by the connector:

Data Class	Interface that uses the Data Class
org.eclipse.aperi.discovery.snmp.scanner.interfaces.Response	IScanner
org.eclipse.aperi.common.ReadLogResponse	IScanner
org.eclipse.aperi.sanmgmt.tsanm.zone.data.ZoneDefinition	IZoneControlAgent
org.eclipse.aperi.sanmgmt.tsanm.zone.interfaces.Control	IZoneControlAgent

Data

In release 0.2 the Data agent will use the connector to receive socket connections. This job was previously performed by the org.eclipse.aperi.agent.svp.AgentService class. This class will be replaced by the org.eclipse.aperi.agent.svp.AgentSocketHandler class, which will implement the org.eclipse.aperi.connector.SocketHandler interface and duplicate the function of the AgentService_ class used in release 0.1.

The AgentSocketHandler class will be implemented as follows:

public class AgentSocketHandler implements SocketHandler
{

   void handleSocket(Socket socket) throws Throwable
   {
      Router router = new Router(socket);
      Agent.breadLine.assign(router);
   }

}

Update Manager

Work in progress. This document will be updated when the Aperi Update Manager Design R2 has been completed.

Extensibility

Handlers

All requests received by the Data agent are processed by request handlers. When the server sends a request to the agent is includes an subType integer that indicates what handler needs to be used to process the request. The agent relies on a hard-coded array of handler classes to lookup the appropriate handler. This design makes it impossible to add handlers dynamically because the hardcoded handler array in the Router class to be updated each time a new handler is added.

In this release the org.eclipse.aperi.agent.requesthandler extension point will be added to the org.aperi.eclipse.agent.data plugin. It will be used to locate the appropriate handler class instead of the hard-coded handler array. The Request object sent by the server will be modified to contain an extension point ID (String) instead of the subType integer. The Router class will use the extension point ID sent by the server to lookup the appropriate AgentRequestHandler implementation in the extension registry. The Router will instantiate the request handler using the getExtensionImpl(String extensionId) method of the AbstractExtensionMgr. Request handlers must provide a default no-arg constructor or implement the org.eclipse.core.runtime.IExecutableExtensionFactory interface.

The schema of org.eclipse.aperi.agent.requesthandler is:

<?xml version='1.0' encoding='UTF-8'?>
<!-- Schema file written by PDE -->
<schema targetNamespace="org.eclipse.aperi.agent.data">
<annotation>
      <appInfo>
         <meta.schema plugin="org.eclipse.aperi.agent.data" id="requesthandler" name="Request Handler"/>
      </appInfo>
      <documentation>
         [Enter description of this extension point.]
      </documentation>
   </annotation>

   <element name="requestHandler">
      <complexType>
         <attribute name="impl" type="string" use="required">
            <annotation>
               <documentation>
                  
               </documentation>
               <appInfo>
                  <meta.attribute kind="java" basedOn="org.eclipse.aperi.agent.svp.AgentRequestHandler"/>
               </appInfo>
            </annotation>
         </attribute>
      </complexType>
   </element>

   <element name="extension">
      <complexType>
         <sequence>
            <element ref="requestHandler" minOccurs="1" maxOccurs="unbounded"/>
         </sequence>
         <attribute name="point" type="string" use="required">
            <annotation>
               <documentation>
                  
               </documentation>
            </annotation>
         </attribute>
         <attribute name="id" type="string">
            <annotation>
               <documentation>
                  
               </documentation>
            </annotation>
         </attribute>
         <attribute name="name" type="string">
            <annotation>
               <documentation>
                  
               </documentation>
               <appInfo>
                  <meta.attribute translatable="true"/>
               </appInfo>
            </annotation>
         </attribute>
      </complexType>
   </element>
</schema>

The Aperi agent will provide approximately fifteen extensions to the "org.eclipse.aperi.agent.requesthandler" extension point.

org.eclipse.aperi.agent.svp.AgentLogConfigHandler
org.eclipse.aperi.agent.svp.DaemonLogFileHandler
org.eclipse.aperi.agent.svp.GetAgentHomeHandler
org.eclipse.aperi.agent.svp.JavaJobHandler
org.eclipse.aperi.agent.svp.JobLogFileHandler
org.eclipse.aperi.agent.svp.ReadConfigHandler
org.eclipse.aperi.agent.svp.ReadLogFileHandler
org.eclipse.aperi.agent.svp.RunScriptHandler
org.eclipse.aperi.agent.svp.StatusHandler
org.eclipse.aperi.Nas.agent.LoginAdminHandler
org.eclipse.aperi.Nas.agent.ManNasConfigHandler
org.eclipse.aperi.Nas.agent.NasLogHandler
org.eclipse.aperi.TStorm.agent.DiscoveryHandler
org.eclipse.aperi.TStorm.agent.probe.RunProbeHandler
org.eclipse.aperi.Nas.agent.NasLoginHandler

Jobs

The core features provided by the Data agent are implemented as jobs. This includes filesystem probe, batch reports, and network discovery. All job requests are processed by the org.eclipse.aperi.agent.svp.JavaJobHandler handler which performs all the tasks necessary to display the job in the GUI and performs job specific function using helper classes.

In release R2 the org.eclipse.aperi.agent.job extension point will be added to the JavaJobHandler class and it will be used to locate job specific function. The Data server will continue to send job requests to JavaJobHandler and JavaJobHandler will perform the tasks that are common to all jobs (creating job logs, tracking job status, etc). However, it will perform job specific function by executing the exec method on the appropriate implementation of org.eclipse.aperi.jobs.IExecutable. JavaJobHandler will locate the IExecutable implementation using the extension ID that was sent as part of the job request. The Java job handler will instantiate the extension and invoke the exec() method of the new object.

The extension Point schema of org.eclipse.aperi.agent.job is:

<?xml version='1.0' encoding='UTF-8'?>
<!-- Schema file written by PDE -->
<schema targetNamespace="org.eclipse.aperi.agent.data">
<annotation>
      <appInfo>
         <meta.schema plugin="org.eclipse.aperi.agent.data" id="job" name="Job"/>
      </appInfo>
      <documentation>
         [Enter description of this extension point.]
      </documentation>
   </annotation>

   <element name="job">
      <complexType>
         <attribute name="impl" type="string" use="required">
            <annotation>
               <documentation>
                  
               </documentation>
               <appInfo>
                  <meta.attribute kind="java" basedOn="org.eclipse.aperi.jobs.IExecutable"/>
               </appInfo>
            </annotation>
         </attribute>
      </complexType>
   </element>

   <element name="extension">
      <complexType>
         <sequence>
            <element ref="job"/>
         </sequence>
         <attribute name="point" type="string" use="required">
            <annotation>
               <documentation>
                  
               </documentation>
            </annotation>
         </attribute>
         <attribute name="id" type="string">
            <annotation>
               <documentation>
                  
               </documentation>
            </annotation>
         </attribute>
         <attribute name="name" type="string">
            <annotation>
               <documentation>
                  
               </documentation>
               <appInfo>
                  <meta.attribute translatable="true"/>
               </appInfo>
            </annotation>
         </attribute>
      </complexType>
   </element>

</schema>

The org.eclipse.aperi.agent.job extension point requires extensions to implement the org.eclipse.aperi.jobs.Executable interface.

The org.eclipse.aperi.jobs.Executable interface is defined as:

package org.eclipse.aperi.jobs;

public interface Executable
{
   public int exec(StartedJob startedJob, String[] args);
}

The Aperi agent will provide three jobs as org.eclipse.aperi.agent.job extensions:

Job	Implementation
Filesystem Probe	org.eclipse.aperi.TStorm.agent.probe.ExecProbe
Batch Reports	org.eclipse.aperi.TStorm.agent.batch.ExecReport
Network Discovery	org.eclipse.aperi.TStorm.agent.ExecDiscovery

Packaging

Java Changes

The following packages will be moved from the org.eclipse.aperi.common plugin to the org.eclipse.aperi.agent.data plugin.

org.eclipse.aperi.agent.svp
org.eclipse.aperi.agent.svp.unixscripts
org.eclipse.aperi.agent.svp.worker
org.eclipse.aperi.agent.jobs
org.eclipse.aperi.Nas.agent.netapp
org.eclipse.aperi.TStorm.agent
org.eclipse.aperi.TStorm.agent.batch
org.eclipse.aperi.TStorm.agent.probe
org.eclipse.aperi.TStorm.agent.scan

Native Libraries

Currently native libraries used by the Data agent are separated into Common and TStorm function. This organization exists for purely historical reasons and there is no need to maintain this structure. Instead, native libraries will be organized by plugin. Native methods called from the org.eclipse.aperi.common plugin will be placed in the DataCommon native library and native methods called from the org.eclipse.aperi.agent.data plugin will be placed in the DataAgent native library. The org.eclipse.aperi.common plugin and the DataCommon native library will be used by both the Data server and Data agent.

The Data native libraries we be rearranged as follows:

DataAgent r0.1	DataCommon r0.2	DataAgent r0.2
Agent		X
AuthChecker		X
AutoParser	X
CmdExecer		X
EnvUtil		X
growable		X
HardwareID	X
LockManager	X
LogFileReader	X
MessageLog	X
Pipe		X
RegistryUtil	X
SingleInstance	X
SubprocessRegistry		X
SuperUserWin32		X
ThreadDumper	X
UpgradeHandlerWin32	X
Win32Loader	X
WindowsScriptReaper		X
WindowsScriptRunner		X

DataAgent2 r0.1	DataCommon r0.2	DataAgent r0.2
AssertPrivilege		X
ExecProbe		X
grwbl		X
hash		X
identify		X
LanManagerDiscovery		X
Mounts		X
MSCSUtil		X
NasUtil		X
NetWareLoader		X
pathmatch		X
Probe		X
probeutil		X
ProbeWin32		X
regcomp		X
regerror		X
regexec		X
regfree		X
RemoteMountInfo		X
scuzzy		X
WWNviaHBAAPI		X

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Aperi Agent Design R2

Contents

Introduction

Extensibility

Inband Fabric Agent

Connector

Update Manager

Features

Inband Fabric Agent

Connector

Fabric

Data

Update Manager

Extensibility

Handlers

Jobs

Packaging

Java Changes

Native Libraries

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Aperi Agent Design R2

Contents

Introduction

Extensibility

Inband Fabric Agent

Connector

Update Manager

Features

Inband Fabric Agent

Connector

Fabric

Data

Update Manager

Extensibility

Handlers

Jobs

Packaging

Java Changes

Native Libraries