Striker Agent API

AN!Wiki :: Striker Agent API

This is the Striker Agent API definition.

Striker Agents are stand-alone agents that scan and monitor specific hardware or software associated with Anvil! clusters and foundation pack equipment.

Version

Name:	Striker-Agent_API
Version:	1.0.0
Date:	2014-09-17

The Striker Agent API version structure is 'x.y.z' where:

x	Major revisions.	Striker Agents are not required to support previous major revisions.
y	Minor revisions.	Existing specifications may be extended and new, optional features may be added. Existing specifications will not be changes and compatibility will not be broken.
z	Minor	Releases to fix bugs, no new features added.

Overview

This document describes how a striker agent is expected to operate as part of the "Striker Scanner" monitoring program. Programs that conform to this API are known as "Striker Agents".

General Conventions

Striker Agents can have any name the author wishes. However, it is recommended that the name reflects the purpose of the agent. By convention, the name if Striker Agents is in the format '<subsystem>_<component>'. Examples are:

storage_mdadm	Provides monitoring for "mdadm" (software) RAID arrays
storage_lsi	Provides monitoring for LSI (Avago) based hardware RAID controllers.
storage_hp	Provides monitoring for HP based hardware RAID controllers.
software_drbd	Provides monitoring of LINBIT's "Distributed, Replicated Block Device" software application.
software_rgmanager	Provides monitoring of Red Hat's "Resource Group Manager" cluster software.
network_bond	Provides monitoring of bonded network interfaces.
network_brocade	Provides monitoring of Brocade based ethernet network switches.

There is no official list of subsystem prefixes. If you plan to develop a Striker Agent, you are free to select any subsystem name you wish. However, it is requested that you consult the Anvil! community to help decide what subsystem your agent might best fit.

Scanner Agents may have associated libraries, reference SQL schemas, READMEs and so on. These files MUST have the same name as the Striker Agent, plus a file extension. There are no requirements on what the extension(s) can be. By convention, certain extensions are common:

.lib	Library of functions, subroutines or similar.
.sql	Reference SQL schema
.xml	File containing language "strings".
.README	Document describing your Striker Agent.

Programming language specific shared libraries are allowed. These shared libraries must be named:

scan-common-<language>.<library_extension>

For example, the shared perl library is named:

scan-common-perl.lib

New functions can be relatively easily added to existing shared language libraries and new language libraries are welcome to be added to Striker. To contribute, simply contact the community and all reasonable additions and improvements will be accommodated.

Command Line Switches

All Striker Agents MUST support the following list of command line arguments. The supported output of the argument will be described along with the command line switch. All acceptable return codes will be specified. If a switch will return output, it must be XML formatted.

Command line switches will be passed independently and will not be merged. Some Some switches will have a short version with a single hyphen prefix. All switches will have a long form with a double-hyphen prefix. Where switches take values, the switch's value will follow with either a space or use an equal sign without a space. Examples;

Equal command line switches, short and long form:

-f, --foo

Equal command line switch with variable:

--foo bar, --foo=bar

A bare double-hyphen will mark the end of string processing. Anything read in after a bare '--' can be ignored.

Striker Agents must exit with return code '0' on success. Unless specified, any non-0 return code will be treated as a failure, regardless of textual output.

v, version

-v, --version

Agents must return the numerical Striker-Agent_API version they conform to. Output must be a single XML element named 'striker-scanner' with variable name of 'SA API' and a value in the format 'x.y', where 'x' and 'y' are integers representing the API major and minor versions supported by the agent, respectively.

Example output:

<striker-scanner variable="SA API" value="1.0" />

s, sql

-s, --sql

Agents must return the SQL schema the agent will require in XML format defined below. The Striker Scanner will create or modify tables as needed before calling the agent to run.

Note: New tables, and new columns for existing tables, may be added, but existing columns may not be modified. If an agent provides a schema that would cause an existing table's column to be changed, and error alert email will be generated and the agent will not be run. An administrator will need to manually adjust the table's columns to conform to the schema returned by this call for the agent to be used again. The scanner will examine the schema compatibility on every pass, though only one alert email will be sent. If the schema is later found to be compatible, a follow up alert will be dispatched and any future compatibility issue will again trigger an alert.

Schema format:

<striker-scanner>
	<sql>
		<table name="x" type="sequence" />
		<table name="y" type="data">
			<column name="sm_id" type="int" is_id="true">
				<primary_key table="storage_mdadm_sequence" value="nextval" />
			</column>
			<column name="x" type="y" not_null="true" default="true" />
			<column name="sm_md_created" type="text" />
			<column name="sm_md_raid_level" type="text" />
			<column name="sm_md_uuid" type="text" comment="delete ':'" />
			<column name="sm_md_device" type="text" />
			<column name="sm_md_size" type="bigint" comment="Store in bytes, provided as both base 2 and 10" />
			<column name="sm_md_state" type="text" />
			<column name="sm_md_devices_raid" type="int" />
			<column name="sm_md_devices_total" type="int" />
			<column name="sm_md_devices_active" type="int" />
			<column name="sm_md_devices_working" type="int" />
			<column name="sm_md_devices_failed" type="int" />
			<column name="sm_md_devices_spare" type="int" />
		</table>
		<table name="storage_mdadm_device" type="data">
			<column name="smd_id" type="int">
				<primary_key table="storage_mdadm_device_sequence" value="nextval" />
			</column>
			<column name="smd_sm_id">
				<foreign_key name="smd_sm_id" table="storage_mdadm" column="sm_id" />
			</column>
			<column name="smd_md_raid_level" type="text" />
			<column name="smd_md_uuid" type="text" comment="delete ':'" />
			<column name="smd_md_device" type="text" />
			<column name="smd_md_size" type="bigint" comment="Store in bytes, provided as both base 2 and 10" />
			<column name="smd_md_state" type="text" />
			<column name="smd_md_devices_active" type="int" />
			<column name="smd_md_devices_working" type="int" />
			<column name="smd_md_devices_failed" type="int" />
			<column name="smd_md_devices_spare" type="int" />
		</table>
	</sql>
</striker-scanner>

General:

All 'table' and 'column' elements must have a unique 'name' attribute. This attribute name must be a valid table or column name in PostgreSQL.