NAME

      mxtool - Systems Insight Manager Tool definition file

SYNOPSIS

      mxtool

DESCRIPTION

The mxtool command supports reading and writing tool definitions in
the eXtensible Markup Language (XML) format. You may use this
capability to share tool definitions between different Systems Insight
Manager environments and to modify tool definitions in an Systems
Insight Manager environment. Each file may contain the definitions of
one or more tools.

To run an Systems Insight Manager tool on multiple target nodes, the
Systems Insight Manager Distributed Task Facility (DTF) executes the
tool on each target node.

Tool Types
There are five basic types of Systems Insight Manager tools, single-
system aware (SSA) tools, multiple-system aware (MSA) tools, web
launch aware (WLA) tools, automation tools and application launch
tools.

SSA tools are executed on a target node and are only aware of the
target node environment. When executing an SSA tool, therefore, the
DTF sends the tool information to each Systems Insight Manager agent
to execute the tool. An example of an SSA tool would be a tool that
wraps a common UNIX command, such as ls, cat, or cp.

MSA tools are executed on a central node, sometimes the Central
Management Server (CMS), and know how to handle a list of target
nodes. An example of an MSA tool would be a tool that wraps the
functionality of Ignite-UX on HP-UX systems.

WLA tools are tools that are generally executed in a browser and are
specified by a universal resource location (URL).

Automation tools are executed on the CMS and perform some action such
as discovery on the target nodes.

Application launch tools are executed on the CMS. One instance of the
tool is started for each target node.

Document Type Definition
The Document Type Definition (DTD) file defines the constraints for an
XML file. These constraints include the valid element tags,
attributes, and the cardinality of elements in an XML file. The tool
DTD file is named toollist.dtd and is included in the following
paragraph. Note that due to man page formatting, the DTD contents may
not appear the same as in the file.
<?xml version="1.0" encoding="UTF-8" ?>

<!ELEMENT tool-list ( ssa-command-tool |
msa-command-tool |
web-launch-tool |
automation-tool |
app-launch-tool )* >

<!ELEMENT ssa-command-tool (category?, description?, comment?,
owner?, default-target?, execute-as-user?,
job-display-handler?,
toolbox-enabled?, toolbox*,
role-enabled?, role*,
include-filter*, env-variable*,
ssa-block, attribute* ) >

<!ATTLIST ssa-command-tool name CDATA #REQUIRED
visible (true | false) "true"
max-targets NMTOKEN #IMPLIED
revision CDATA #IMPLIED
guid NMTOKEN #IMPLIED >

<!ELEMENT ssa-block (( command | copy-block )+, parameter*) >

<!ELEMENT copy-block ( source, destination )+ >

<!ELEMENT source (#PCDATA) >

<!ELEMENT destination (#PCDATA) >

<!ELEMENT msa-command-tool (category?, description?, comment?, owner?,
default-target?, execute-as-user?,
job-display-handler?,
toolbox-enabled?, toolbox*,
role-enabled?, role*,
include-filter*, env-variable*,
msa-block, attribute* ) >

<!ATTLIST msa-command-tool name CDATA #REQUIRED
visible (true | false) "true"
max-targets NMTOKEN #IMPLIED
revision CDATA #IMPLIED
guid NMTOKEN #IMPLIED >

<!ELEMENT msa-block ( command, parameter*, execution-node ) >

<!ELEMENT command ( #PCDATA ) >

<!ATTLIST command command-type (x-window |
stdout |
restart |
launch |
unknown) "stdout"
log (true | false) "false" >

<!-- The execution-node element specifies the node on which an MSA

tool will execute. -->
<!ELEMENT execution-node ( #PCDATA ) >

<!ELEMENT web-launch-tool (category?, description?, comment?, owner?,
default-target?, execute-as-user?,
job-display-handler?,
toolbox-enabled?, toolbox*,
role-enabled?, role*,
include-filter*, web-block, attribute* ) >

<!ATTLIST web-launch-tool name CDATA #REQUIRED
visible (true | false) "true"
max-targets NMTOKEN #IMPLIED
revision NMTOKEN #IMPLIED
guid NMTOKEN #IMPLIED >

<!ELEMENT web-block (main-url, (side-url?, status-url?, current-url?),
parameter*, target-format? ) >

<!ATTLIST web-block accepts-targets (true|false) "true">

<!ELEMENT main-url ( #PCDATA ) >

<!ELEMENT status-url ( #PCDATA ) >

<!ELEMENT current-url ( #PCDATA ) >

<!ELEMENT side-url ( #PCDATA ) >

<!ELEMENT target-format ( #PCDATA ) >

<!ELEMENT automation-tool (category?, description?, comment?, owner?,
default-target?, execute-as-user?,
job-display-handler?,
toolbox-enabled?, toolbox*,
role-enabled?, role*,
include-filter*, automation-block,
attribute* ) >

<!ATTLIST automation-tool name CDATA #REQUIRED
visible (true | false) "true"
max-targets NMTOKEN #IMPLIED
revision CDATA #IMPLIED
guid NMTOKEN #IMPLIED >

<!ELEMENT automation-block (message-id) >

<!ELEMENT message-id ( #PCDATA ) >

<!ELEMENT app-launch-tool (category?, description?, comment?, owner?,
default-target?, execute-as-user?,
job-display-handler?,
role-enabled?, role*,
toolbox-enabled?, toolbox*,
include-filter*, env-variable*,
app-launch-block, attribute* ) >

<!ATTLIST app-launch-tool name CDATA #REQUIRED
visible (true | false) "true"
max-targets NMTOKEN #IMPLIED
revision CDATA #IMPLIED
guid NMTOKEN #IMPLIED >

<!ELEMENT app-launch-block (command, app-parameters?) >

<!ATTLIST app-launch-block alert-driven (true | false) "false" >

<!ELEMENT app-parameters ( #PCDATA ) >

<!ELEMENT env-variable ( #PCDATA ) >

<!ATTLIST env-variable name CDATA #REQUIRED >

<!ELEMENT owner ( #PCDATA ) >

<!ELEMENT comment ( #PCDATA ) >

<!ELEMENT parameter EMPTY >

<!ATTLIST parameter index (1|2|3|4|5|6|7|8|9|10) "1"
prompt CDATA #REQUIRED
required (true|false) "false" >

<!ELEMENT toolbox-enabled EMPTY >

<!ATTLIST toolbox-enabled value (true|false) "true">

<!ELEMENT role-enabled EMPTY >

<!ATTLIST role-enabled value (true|false) "true">

<!ELEMENT default-target ( #PCDATA ) >

<!ELEMENT category ( #PCDATA ) >

<!ELEMENT description ( #PCDATA ) >

<!ELEMENT execute-as-user ( #PCDATA ) >

<!ELEMENT job-display-handler ( #PCDATA ) >

<!ELEMENT toolbox EMPTY >

<!ATTLIST toolbox toolbox-name CDATA #REQUIRED >

<!ELEMENT role EMPTY >

<!ATTLIST role role-name CDATA #REQUIRED >

<!ELEMENT include-filter (node-filter)+ >

<!ATTLIST include-filter type (os | hardware | protocol) "os" >

<!ELEMENT node-filter EMPTY >

<!ATTLIST node-filter name CDATA #REQUIRED
operator (EQ | GE | LT |
eq | ge | lt |
Eq | Ge | Lt |
eQ | gE | lT) "EQ"
value CDATA #REQUIRED >

<!ELEMENT attribute ( #PCDATA ) >
<!ATTLIST attribute name CDATA #REQUIRED >

Parameterized Strings
In order to create tools properly, the tool developer must understand
how URLs and command lines are formed. Both the various view URL
attributes and target format in a Web Launch tool and the command line
attribute in a Command Line tool are parameterized strings.

Parameterized strings are strings which contain replacement fields,
similar to the format strings used in the popular printf() function in
the standard C library. These fields can be replaced by values entered
by the user at runtime (as defined by the tool parameters attribute),
by some standard task properties supplied by the Task Controller,
values related to the selected target nodes or node groups, or by
property values retrieved from a global tool properties file. This
allows a very specific URL or command line to be generated.

Parameterized Strings Substitution Table
The following parameters provide substitution of global
attribute values:

Parameter Description
%t Task ID for the task being executed.
%u Name of user running this tool.
%e Name of the user to execute this tool as.
%s Management server hostname of the core CMS
running the tool.
%# (where # is a positive integer) Substitute the
value input by the user for the parameter
referenced by the number (#) provided, as a
list index position (one-based... %1, %2, %3,
etc.).
%y SOAP logon token, for use with SOAP single
sign-on web apps.

The following parameters provide substitution of the
current selected target:

Parameter Description
%x Do not substitute anything, but switch the list
of selected targets to use the "raw" selection
list, instead of the expanded list of target
nodes. The "raw" list is the original list of
selected nodes and/or node groups. This toggle
parameter must be included BEFORE using any of
the following substitution parameters. If node
groups appear in the selection list, only the
"%f" and "%g" parameters will expand to any
value. All other substitution parameters will
have a zero-length string substituted.
%f The database name of the target node (or node
group, if the "%x" toggle was in the string).
%n Network name (hostname, IP address, IPX address,
or node name, in that order).
%a Network address (IP address, or IPX address, in
that order).
%l Link name in format specified by Node Link
Configuration setting (name, IP address,
or full DNS name).
%p IP address of WBEM proxy, if any, for this target.
This is in the form <ip address>:<port#>
%g Database GUID of the target node (or node group,
if the "%x" toggle was in the string).
%m MAC address of the target node.
%b Device type of the target node.
%c Device sub-type of the target node.
%{attribute%} The value of the named attribute of the
target node.

The following parameters provide repetition to support
multiple selected target nodes:

Parameter Description
%( ... %) Repeated pattern (only repeats if a current
selection exists). If a current target
selection does NOT exist, the text between the
delimiters is removed on expansion. This allows
the text to be optional and dependent upon the
target selection list.
%i Selection index (one-based).
%z Don't substitute anything, but increment the
selection index to the next integer and the
referenced target node to the next target in the
selected target list.
%< ... %> Encrypted text (encrypt after all other
parameters have been substituted)
%% Allows you to retain a % in the command/URL
after substitution.

Parameterized Strings Examples
Web Launch Aware tool's URL strings will need to be provided as
absolute URLs beginning with "http://" or "https://". For example,

https://%n:1188/kcweb/
https://%l:2381/

Web Launch Aware tools that always run on the Management Server must
be relative URLs beginning with "/". For example,

/propertypages/Identify.jsp?device=%n

Multiple selections can be substituted into the URL. A selection
index is used during the substitution process to keep track of the
"current" selection. The selection index will initially be set to
one, and the first selection of the list of selected target nodes will
remain current until a "%z" parameter is encountered in the URL (an
exception to this exists in the repeat block, discussed later), at
which time the next selection becomes current and the selection index
is incremented by one, and so on. For example,

http://server/app/doit.jsp?name=%n%z&addr=%a

where the "doit.jsp" page will be invoked with the network name of the
first selected node assigned to the "name" parameter and the IP
address of the second selected target assigned to the "addr"
parameter.

Any number of selected targets may be substituted by using the repeat
block construct, "%( ... %)". Anything inside the repeat block
delimiters will be repeated until the selection list is exhausted,
starting with what is then the current selection and selection index.
For example,

https://%[deploy.server%]/deploy/deployimage.jsp?device1=%n%z%(&device%i=%n%z%)

Note the use of the "%i" parameter. The current selection index
(1,2,3,etc) will be substituted for this parameter during the
substitution process.

Note: If the end of the repetition clause is reached and no "%z"
parameter has been encountered, then the selection index and current
selection will be automatically incremented to avoid an infinite loop
during the substitution phase.

If we have 2 selected target nodes in the above example, the expanded
URL string would look like this:

https://deploy.hp.com:280/deploy/deployimage.jsp?device1=nodea.hp.com&device2=nodeb.hp.com

If we have only 1 selected target node in the above example, the
expanded URL string would look like this:

https://deploy.hp.com:280/deploy/deployimage.jsp?device1=nodea.hp.com

Since there is no current selection when we get to the repeat block,
the entire repeat block is suppressed during the substitution process.

Tool Filtering
Tool filtering is a facility allowing the tool writer to control
whether the tool is visible in the Tools menu when one or more nodes
are selected. Most tools are platform dependent in that their
successful execution depends on commands that are provided on some
platforms but not on others. For example, the "bdf" tool depends on
the "bdf" command, which is provided on HP-UX platforms, but is not
available under that name on Linux platforms. A tool should only be
visible in the Tools menu when the commands it requires to run are
available on all the nodes selected. To do this, the tool specifies
in a node filter expression the node attributes that must be possessed
by all nodes it can run on.

The node attributes required for a tool to run are specified by node
filter expressions having the form:

<node-filter name="attribute-name" operator="eq" value="attribute-value" />
or
<node-filter name="attribute-name" operator="ge" value="attribute-value" />
or
<node-filter name="attribute-name" operator="lt" value="attribute-value" />

The "eq" operator specifies that a node the tool can run on must have
exactly the attribute value specified. It applies to any attribute
name allowed in a node filter expression. The "ge" operator specifies
that a node the tool can run on must have at least the attribute value
specified. The "lt" operator specifies that a node the tool can run on
must have a less than the value specified. The idea of a "greater
than or equal to" or a "less than" relation only has meaning for
numeric valued attributes. For nodes, the numeric valued attributes
the filter expression can specify include the OSRevision and Protocol
Support attributes, whose values are version numbers. The values
permitted for version numbers and how they are compared is described
in the Version Numbers section below. The attribute-name is one of the
values listed in the tables below, or a protocol name from the
ProtocolSupport attribute of a node. The attribute-value is one of the
possible node attribute values for attribute-name.

Attribute values are based on the Distributed Task Force (DMTF) Common
Information Model (CIM). Usually these values are defined during the
node identification process, which uses WBEM and SNMP to determine
node attributes. For this release, valid OSName values are "HPUX" and
"LINUX". For an OSName value of "HPUX", the OSRelease attribute
values have the leading alphabetic field removed (for example B.11.11
is stored as 11.11). Valid ProcessorFamily values are "pa-risc",
"ia32" and "ia64". The ProccessorFamily attribute for a node may be
empty if SNMP or WBEM returns a value that is not recognized.

A node filter expression is used as part of an include filter
expression. There are three types of include filter expressions, each
allowing a different category of attribute names to be filtered on.

Category Filter Type Attributes Names Allowed
Operating System os OSName, OSVendor,
OSRevision
Hardware hardware DeviceType, DeviceSubType,
Model, ProcessorFamily
Protocol Support protocol any protocol name

An include filter includes one or more node filter expressions using
the attributes names allowed for it. For example, an "os" filter could
consist of:

<include-filter type="os">
<node-filter name="OSName" operator="eq" value="LINUX" />
<node-filter name="OSVendor" operator="eq" value="RedHat" />
<node-filter name="OSRevision" operator="ge" value="7.2" />
</include-filter>

The include filter need not include all attributes allowed. If more
than one attribute is included, the conditions are logically "and"ed
together. An attribute may not appear in an include filter more than
once, except that an attribute having a version number value may
appear twice if one operator is "lt" and the other operator is "ge".
For example:

<include-filter type="protcol">
<node-filter name="WBEM" operator="lt" value="2.6" />
<node-filter name="WBEM" operator="ge" value="2.4" />
</include-filter>

This would specify that the tool should be shown for any collection of
nodes supporting the WBEM protocol version 2.4 or higher, but less
than 2.6.

If a tool contains more than one include filter of different types,
the conditions of the filters are logically "and"ed together. A tool
with both Operating System and Hardware dependencies could use the
filter:

<include-filter type="os">
<node-filter name="OSName" operator="eq" value="LINUX" />
</include-filter>
<include-filter type="hardware">
<node-filter name="DeviceSubType" operator="eq" value="HPVectra" />
</include-filter>

If a tool contains more than one include filter of the same type, the
conditions of the filters are logically "or"ed together. A tool
available on two different Operating Systems could specify:

<include-filter type="os">
<node-filter name="OSName" operator="eq" value="LINUX" />
</include-filter>
<include-filter type="os">
<node-filter name="OSName" operator="eq" value="HPUX" />
</include-filter>

This tool would be visible on any collection of nodes using either
Linux or HP-UX.

Tool filtering depends on the attributes being filtered having a value
defined on the nodes selected. For "os" and " hardware" filter types,
if any attributes being filtered on are not defined for a node, the
node is assumed to have the value required by the filter. Thus a node
with none of the "os" or "hardware" attributes specified by a tool
filter will be assumed capable of running the tool. The "protocol"
filter type differs from this in that a missing attribute on a node
will not allow the filter to pass.

Version Numbers
The OSRevision and Protocol Support node attributes have values that
are interpreted as version numbers if possible. A version number is a
series of non-negative decimal numbers separated by period (.)
characters. When comparing version numbers, the following rules are
used:

The leftmost numbers in the series are most significant,
so "1.0" is greater than "0.1".

Leading zeroes on the numbers are disregarded,
so "003" is equal to "3".

Two adjacent period characters are interpreted as if they
delimited the number zero,
so "1.0.3" is equal to "1..3".

A beginning period character is interpreted as if
preceeded by a zero,
so ".9" is equal to "0.9".

Trailing zero numbers are disregarded,
so "1.0.0" is equal to "1"

Commenting
Comments may be included in XML files. The comment must begin with
the characters "". Comments may
span multiple lines within the beginning and ending character tags.

Other Requirements
SSA command tools must contain either an execute statement (execStmt),
or a file copy statement (copyStmt), or both. If only the execute
statement is specified, no files are copied prior to executing the
command. If only a file copy statement is specified, after the
file(s) are copied, no command is executed. If they are both
specified, the files are copied first and then the command is
executed.

MSA command tools must specify a command and the node on which the
command will execute.

Tool names must be at least one character in length, and no more than
256 characters in length. The first character of the name must be
alphabetic. Characters after the first may be letters, digits,
spaces. or any of the characters "-", ".", "(", ")" or "_".

Web launch aware tools must specify a main URL.

When specifying file copy pairs, the destination file paths for each
file copy pair within a singe tool definition must be unique.
Specifying the same destination file path for multiple source file
paths will result in a file parsing error.

An error occurs when running a tool that copies a file if the file
doesn't exist or is unreadable. The source file path is not checked
at the time the tool is created or modified, but must exist at the
time the tool is executed.
When the log element is set to true, standard out and standard error
output from the execution of the tool is logged in the Central
Management Server (CMS) log file /var/opt/mx/logs/mx.log. When it is
set to false, only summary task log information, such as start and end
times and task status is logged.

Default Values
Some of the tool attributes have non-null default values. They are:

category "Local Tools"
log true (for SSA and MSA tools only)
user current Systems Insight Manager user at
runtime
toolboxes All Tools

LIMITS

      The length of a tool name is limited to 256 characters.
      The length of a tool category name is limited to 80 characters.
      The length of a tool description is limited to 128 characters.
      The length of a tool owner is limited only by the operating system.
      The length of toolbox names is limited to 16 characters.
      The maximum number of files that may be copied is 16.
      There is no limit to the number of tools that can be registered.

EXAMPLES

      This example is of a SSA tool that returns the output of ps(1) for a
      specified set of parameters:

      <?xml version="1.0" encoding="UTF-8"?>
      <tool-list>
	  <ssa-command-tool name="ps" revision="1.0">
	      <category>General Tools</category>
	      <description>ps &lt;options&gt;</description>
	      <comment>Must specify options, such as -ef</comment>
	      <include-filter>
		  <node-filter name="OSName" operator="eq" value="HPUX" />
	      </include-filter>
	      <include-filter>
		  <node-filter name="OSName" operator="eq" value="LINUX" />
	      </include-filter>
	      <ssa-block>
		  <command command-type="stdout" log="false">ps %1</command>
		  <parameter index="1" prompt="Specify all of the ps args: &lt;options&gt;" required="true" />
	      </ssa-block>
	  </ssa-command-tool>
      </tool-list>


      The following listing describes a tool that copies the crontab on the
      CMS to the target and executes it with the crontab(1) command.
      <?xml version="1.0" encoding="UTF-8"?>
      <tool-list>
	<ssa-command-tool name="Replace root crontab" revision="2.1">
	  <category>General Tools</category>
	  <description>Replace the root crontab with the one from the CMS</description>
	  <owner>root</owner>
	  <execute-as-user>root</execute-as-user>
	  <ssa-block>
	    <copy-block>
	      <source>/var/spool/cron/crontabs/root</source>
	      <destination>/var/tmp/root_crontab</destination>
	    </copy-block>
	    <command log="true">
		      /usr/bin/crontab -l &gt; ~root/.crontab.old;
		      /usr/bin/crontab /var/tmp/root_crontab;
		      rm /var/tmp/root_crontab
	     </command>
	   </ssa-block>
	</ssa-command-tool>
      </tool-list>


      The following listing describes a tool that launches the SAM
      management tool GUI.

      <?xml version="1.0" encoding="UTF-8"?>
      <tool-list>
	<ssa-command-tool name="SAM">
	  <category>General Tools</category>
	  <description>Run SAM</description>
	  <comment>This tool requires that the DISPLAY environment
		   variable be set so that the GUI can be redirected to
		   the appropriate X server.  Since this is a launch
		   tool, failure to set the DISPLAY variable properly
		   will result in nothing happening even though Systems Insight Manager
		   indicates that the tool has completed normally.
	  </comment>
	  <execute-as-user>root</execute-as-user>
	  <toolbox toolbox-name="lvmadmin" />
	  <ssa-block>
	      <command command-type="x-window">/usr/sbin/sam</command>
	  </ssa-block>
	</ssa-command-tool>
      </tool-list>


      The following listing describes a tool that invokes shutdown(1m). Note
      that this tool is launched so that when the agent is killed by
      shutdown(1m), the task has already completed and there are no
      resources on the CMS awaiting its response.

      <?xml version="1.0" encoding="UTF-8"?>
      <tool-list>
	<ssa-command-tool name="Shutdown the system">
	  <category>General Tools</category>
	  <description>Shutdown the system</description>
	  <comment>This tool is launched.  As a result, if it fails for
		   some reason, there will be no indication of it.  The
		   Systems Insight Manager user must have permission to execute shutdown(1m)
		   - see /etc/shutdown.allow.
	  </comment>
	  <ssa-block>
	    <command command-type="restart">/usr/sbin/shutdown %1 %2</command>
	    <parameter index="1"
		       prompt="Enter desired options, such as -r, -h, or -y"
		       required="false" />
	    <parameter index="2"
		       prompt="Enter the grace period in seconds or &quot;now&quot;"
		       required="false" />
	  <ssa-block>
	</ssa-command-tool>
      </tool-list>

LIMITATIONS

      This command may only be run on the CMS.

AUTHOR

      mxtool was developed by the Hewlett-Packard Company.