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" ?>

      <!-- The tool-list element may contain zero or more of either
	   ssa-command-tool elements, msa-command-tool elements,
	   web-launch-tool elements, automation-tool elements or
	   app-launch-tool elements.-->
      <!ELEMENT tool-list ( ssa-command-tool |
			    msa-command-tool |
			    web-launch-tool  |
			    automation-tool  |
			    app-launch-tool )* >

      <!-- The ssa-command-tool element specifies a single-system aware
	   tool. The ssa-command-tool element may optionally specify a
	   category element, a description element, a comment element, an
	   owner element, a default-target element, an execute-as-user
	   element, a job-display-handler element, a toolbox-enabled
	   element, zero or more toolbox elements, zero or more
	   include-filter elements, or zero or more env-variable elements.
	   (NOTE: The role-enabled and role elements are deprecated
	   elements and should not be used with this product. These
	   are provided for backward compability with previous
	   products. The toolbox-enabled element and the toolbox
	   element should be used in their stead.)
	   If more than one of these elements are specified, the element
	   must appear in the order as listed in this definition. The
	   ssa-command-tool element must contain an ssa-block element. The
	   ssa-block element must appear after the previously described
	   optional elements, if any of the optional elements are
	   specified. Following the ssa-block element, one may specify zero
	   or more attribute elements.-->
      <!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* ) >

      <!-- In addition to the previously described elements, the
	   ssa-command-tool element specifies the following attributes. The
	   name attribute specifies the tool name and must be specified in
	   the ssa-command-tool element. The visible attribute specifies
	   whether the tool is visible for running. By default tools are
	   visible. The max-targets attribute specifies the maximum number
	   of targets against which a tool may run. The revision attribute
	   allows a tool author to specify a revision for the tool. Note
	   that this is for information only. The job-log attribute
	   specifies whether the results of the command will be kept in this
	   system's job log. This attribute applies only to tools when they
	   are run as scheduled tasks, not when they are run as "run now"
	   tasks. When job-log="true" the job and target status for the tool
	   will be kept for a relatively lengthy system-defined period in
	   the database after the job completes. When job-log="false" only
	   the last completed copy of the job and target status for the task
	   will be kept in the cache for a much shorter period of time, and
	   will not be written to the database.	 Job logging is enabled by
	   default. The schedulable attribute specifies whether the tool can
	   be run as a scheduled task. When schedulable="false" the tool can
	   only run as a "run now" task.  Tools are schedulable by default.
	   The guid attribute specifies a globally unique identifier (GUID)
	   for the tool. Because the system generates a GUID for a tool
	   during the add operation, this field should only be specified
	   during a modify operation. The accepts-targets attribute specifies
	   whether the tool accepts targets for execution. The
	   accepts-targets attribute is true by default. -->
      <!ATTLIST ssa-command-tool name	     CDATA   #REQUIRED
				 visible     (true | false) "true"
				 max-targets NMTOKEN #IMPLIED
				 revision    CDATA   #IMPLIED
				 job-log     (true | false) "true"
				 schedulable (true | false) "true"
				 guid	     NMTOKEN #IMPLIED
				 accepts-targets (true|false) "true" >

      <!-- The ssa-block specifies the elements specific to a single-system
	   aware tool. The ssa-block may specify a command or copy-block or
	   both. Only one command should be specified but up to 16 multiple
	   copy-blocks may be specified. After the command and/or
	   copy-blocks, one may specify the parameters for the command
	   and/or copy-block. -->
      <!ELEMENT ssa-block (( command | copy-block )+, parameter*) >

      <!-- The copy-block specifies a source file path and a destination
	   file path for a copy operation. -->
      <!ELEMENT copy-block ( source, destination )+ >

      <!-- The source element specifies the source file path for a copy
	   operation. -->
      <!ELEMENT source (#PCDATA) >

      <!-- The destination element specifies the destination file path for a
	   copy operation. -->
      <!ELEMENT destination (#PCDATA) >

      <!-- The msa-command-tool element specifies a multiple-system aware
	   tool. The msa-command-tool element may optionally specify a
	   category element, a description element, a comment element, an
	   owner element, a default-target element, an execute-as-user
	   element, a job-display-handler element, a toolbox-enabled
	   element, zero or more toolbox elements, zero or more
	   include-filter elements, or zero or more env-variable elements.
	   (NOTE: The role-enabled and role elements are deprecated
	   elements and should not be used with this product. These
	   are provided for backward compability with previous
	   products. The toolbox-enabled element and the toolbox
	   element should be used in their stead.)
	   If more than one of these elements are specified, the element
	   must appear in the order as listed in this definition. The
	   msa-command-tool element must contain an msa-block element. The
	   msa-block element must appear after the previously described
	   optional elements, if any of the optional elements are
	   specified. Following the msa-block element, one may specify zero
	   or more attribute elements.-->
      <!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* ) >

      <!-- In addition to the previously described elements, the
	   msa-command-tool element specifies the following attributes. The
	   name attribute specifies the tool name and must be specified in
	   the msa-command-tool element. The visible attribute specifies
	   whether the tool is visible for running. By default tools are
	   visible. The max-targets attribute specifies the maximum number
	   of targets against which a tool may run.  The revision attribute
	   allows a tool author to specified a revision for the tool. Note
	   that this is for information only. The job-log attribute
	   specifies whether the results of the command will be kept in this
	   systems job log. When job-log="true" the job and target status
	   for the tool will be kept for a relatively lengthy system-defined
	   period in the database after the job completes. When
	   job-log="false" only the last completed copy of the job and
	   target status for the tool will be kept in the cache for a much
	   shorter period of time, and will not be written to the database.
	   Job logging is enabled by default. The schedulable attribute
	   specifies whether the tool can be run as a scheduled task. When
	   schedulable="false" the tool can only run as a "run now" task.
	   Tools are schedulable by default.  The guid attribute specifies a
	   globally unique identifier (GUID) for the tool. Because the
	   system generates a GUID for a tool during the add operation, this
	   field should only be specified during a modify operation.  The
	   accepts-targets attribute specifies whether the tool
	   accepts targets for execution. The accepts-targets attribute is
	   true by default. -->
      <!ATTLIST msa-command-tool name	     CDATA   #REQUIRED
				 visible     (true | false) "true"
				 max-targets NMTOKEN #IMPLIED
				 revision    CDATA   #IMPLIED
				 job-log     (true | false) "true"
				 schedulable (true | false) "true"
				 guid	     NMTOKEN #IMPLIED
				 accepts-targets (true|false) "true" >

      <!-- The msa-block specifies the elements specific to a
	   multiple-system aware (MSA) tool. The msa-block may specify an
	   MSA command, the parameters for the command and an execution node
	   on which the command executes. -->
      <!ELEMENT msa-block ( command, parameter*, execution-node ) >

      <!-- The command element specifies the command for an SSA or an MSA
	   tool. If the command accepts parameters, it must be specified as
	   a parameterized string. -->
      <!ELEMENT command ( #PCDATA ) >

      <!-- The command element may have two attributes. The command-type
	   attribute specifies whether the command is an x-window, stdout,
	   restart, launch, or an unknown command type. The default command
	   type is stdout. The log attribute specifies whether the results
	   of the command will be output to this system's audit log. When
	   log="true" the stdout and stderr results of the command will be
	   output to the system's audit log. Command output is not logged
	   by default. -->
      <!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 ) >

      <!-- The web-launch-tool element specifies a web launch tool. The
	   web-launch-tool element may optionally specify a category
	   element, a description element, a comment element, an owner
	   element, a default-target element, an execute-as-user element, a
	   job-display-handler element, a toolbox-enabled element, zero or
	   more toolbox elements,  zero or more include-filter elements, or
	   zero or more env-variable elements.
	   (NOTE: The role-enabled and role elements are deprecated
	   elements and should not be used with this product. These
	   are provided for backward compability with previous
	   products. The toolbox-enabled element and the toolbox
	   element should be used in their stead.)
	   If more than one of these elements are specified, the element
	   must appear in the order as listed in this definition. The
	   web-launch-tool element must contain a web-block element. The
	   web-block element must appear after the previously described
	   optional elements, if any of the optional elements are
	   specified. Following the web-block element, one may specify zero
	   or more attribute elements.-->
      <!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* ) >

      <!-- In addition to the previously described elements, the
	   web-launch-tool element specifies the following attributes. The
	   name attribute specifies the tool name and must be specified in
	   the web-launch-tool element. The visible attribute specifies
	   whether the tool is visible for running. By default tools are
	   visible. The max-targets attribute specifies the maximum number
	   of targets against which a tool may run.  The revision attribute
	   allows a tool author to specified a revision for the tool. Note
	   that this is for information only. The job-log attribute
	   specifies whether the results of the command will be kept in this
	   systems job log. When job-log="true" the job and target status
	   for the tool will be kept for a relatively lengthy system-defined
	   period in the database after the job completes. When
	   job-log="false" only the last completed copy of the job and
	   target status for the tool will be kept in the cache for a much
	   shorter period of time, and will not be written to the database.
	   Job logging is enabled by default.  The schedulable attribute
	   specifies whether the tool can be run as a scheduled task. When
	   schedulable="false" the tool can only run as a "run now" task.
	   Tools are schedulable by default. The guid attribute specifies a
	   globally unique identifier (GUID) for the tool. Because the
	   system generates a GUID for a tool during the add operation, this
	   field should only be specified during a modify operation. -->
      <!ATTLIST web-launch-tool name	    CDATA #REQUIRED
				visible	    (true | false) "true"
				max-targets NMTOKEN #IMPLIED
				revision    NMTOKEN #IMPLIED
				job-log	    (true | false) "true"
				schedulable (true | false) "true"
				guid	    NMTOKEN #IMPLIED >

      <!-- The web-block specifies the elements specific to a web launch
	   tool. The web-block must specify a main-url element. Optionally,
	   the web-block may specify a side-url element, a status-url
	   element, and a current-url element. Additionally, the web-block
	   may specify the parameters for the URLs. Finally, the web-block
	   may optionally specify a target format to describe how targets
	   are passed to a web launch aware tool. -->
      <!ELEMENT web-block (main-url, (side-url?, status-url?, current-url?),
			   parameter*, target-format? ) >

      <!-- In addition to the above elements, the web-block element has one

	   attribute. The accepts-targets attribute specifies whether the
	   web launch tool accepts targets for execution. The
	   accepts-targets attribute is true by default. -->
      <!ATTLIST web-block accepts-targets (true|false) "true">

      <!-- The main-url specifies the URL to launch the tool. If the URL
	   accepts parameters, the URL must be specified as a parameterized
	   string. -->
      <!ELEMENT main-url ( #PCDATA ) >

      <!-- The status-url specifies a URL at which one might find the status
	   of this web launch tool during execution. -->
      <!ELEMENT status-url ( #PCDATA ) >

      <!-- The current-url specifies the current URL. -->
      <!ELEMENT current-url ( #PCDATA ) >

      <!-- The side-url specifies a set-aside URL. -->
      <!ELEMENT side-url ( #PCDATA ) >

      <!-- The target-format defines the format of targets in a web launch
	   tool and is specified as a parameterized string.-->
      <!ELEMENT target-format ( #PCDATA ) >

      <!-- The automation tool performs an action on the CMS which
	   involves accessing the target nodes. The automation-tool element
	   may optionally specify a category element, a menu-category
	   element, a description element, a comment element, an owner
	   element, a default-target element, an execute-as-user element, a
	   job-display-handler element, a default-parameter element, a
	   role-enabled element, zero or more  role elements,  zero or more
	   include-filter elements, or zero or more env-variable elements.
	   If more than one of these elements are specified, the element
	   must appear in the order as listed in this definition. The
	   automation-tool element must contain an automation-block element.
	   The automation-block element must appear after the previously
	   described optional elements, if any of the optional elements are
	   specified. Following the automation-block element, one may
	   specify zero or more attribute elements. -->
      <!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* ) >

      <!-- In addition to the previously described elements, the
	   automation-tool element specifies the following attributes. The
	   name attribute specifies the tool name and must be specified in
	   the automation-tool element. The visible attribute specifies
	   whether the tool is visible for running. By default tools are
	   visible. The max-targets attribute specifies the maximum number
	   of targets against which a tool may run. The revision attribute
	   allows a tool author to specify a revision for the tool. Note
	   that this is for information only.  The job-log attribute
	   specifies whether the results of the command will be kept in this
	   systems job log. When job-log="true" the job and target status
	   for the tool will be kept for a relatively lengthy system-defined
	   period in the database after the job completes. When
	   job-log="false" only the last completed copy of the job and
	   target status for the tool will be kept in the cache for a much
	   shorter period of time, and will not be written to the database.
	   Job logging is enabled by default. The schedulable attribute
	   specifies whether the tool can be run as a scheduled task. When
	   schedulable="false" the tool can only run as a "run now" task.
	   Tools are schedulable by default.  The guid attribute specifies a
	   globally unique identifier (GUID) for the tool. Because the
	   system generates a GUID for a tool during the add operation, this
	   field should only be specified during a modify operation. The
	   accepts-targets attribute specifies whether the tool
	   accepts targets for execution. The accepts-targets attribute is
	   true by default. -->
      <!ATTLIST automation-tool	 name	     CDATA   #REQUIRED
				 visible     (true | false) "true"
				 max-targets NMTOKEN #IMPLIED
				 revision    CDATA   #IMPLIED
				 job-log     (true | false) "true"
				 schedulable (true | false) "true"
				 guid	     NMTOKEN #IMPLIED
				 accepts-targets (true|false) "true" >

      <!-- The automation-block specifies the elements specific to an
	   automation tool. The automation-block must specify a
	   message-id. -->
      <!ELEMENT automation-block (message-id) >

      <!-- The message-id is the internal string represention of the message
	   sent by the Automation engine to cause the tool to run. -->
      <!ELEMENT message-id ( #PCDATA ) >

      <!-- The app-launch-tool element specifies a application launch
	   tool. The app-launch-tool element may optionally specify a
	   category element, a menu-category element, a description element,
	   a comment element, an owner element, a default-target element, an
	   execute-as-user element, a job-display-handler element, a
	   default-parameter element, a role-enabled element, zero or more
	   role elements,  zero or more include-filter elements, or zero or
	   more env-variable elements. If more than one of these elements
	   are specified, the element must appear in the order as listed in
	   this definition. The app-launch-tool element must contain an
	   app-launch-block element. The app-launch-block element must
	   appear after the previously described optional elements, if any
	   of the optional elements are specified. Following the
	   app-launch-block element, one may specify zero or more attribute
	   elements. -->
      <!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* ) >

      <!-- In addition to the previously described elements, the
	   app-launch-tool element specifies the following attributes. The
	   name attribute specifies the tool name and must be specified in
	   the app-launch-tool element. The visible attribute specifies
	   whether the tool is visible for running. By default tools are
	   visible. The max-targets attribute specifies the maximum number
	   of targets against which a tool may run. The revision attribute
	   allows a tool author to specify a revision for the tool. Note
	   that this is for information only.  The job-log attribute
	   specifies whether the results of the command will be kept in this
	   systems job log. When job-log="true" the job and target status
	   for the tool will be kept for a relatively lengthy system-defined
	   period in the database after the job completes. When
	   job-log="false" only the last completed copy of the job and
	   target status for the tool will be kept in the cache for a much
	   shorter period of time, and will not be written to the database.
	   Job logging is enabled by default. The schedulable attribute
	   specifies whether the tool can be run as a scheduled task. When
	   schedulable="false" the tool can only run as a "run now" task.
	   Tools are schedulable by default.  The guid attribute specifies a
	   globally unique identifier (GUID) for the tool. Because the
	   system generates a GUID for a tool during the add operation, this
	   field should only be specified during a modify operation. The
	   accepts-targets attribute specifies whether the tool
	   accepts targets for execution. The accepts-targets attribute is
	   true by default. -->
      <!ATTLIST app-launch-tool	 name	     CDATA   #REQUIRED
				 visible     (true | false) "true"
				 max-targets NMTOKEN #IMPLIED
				 revision    CDATA   #IMPLIED
				 job-log     (true | false) "true"
				 schedulable (true | false) "true"
				 guid	     NMTOKEN #IMPLIED
				 accepts-targets (true|false) "true" >

      <!-- The app-launch-block specifies the elements specific to a
	   application launch tool. The app-launch-block specifies a
	   required command element. -->
      <!ELEMENT app-launch-block (command, app-parameters?) >
      <!-- In addition to the previously described elements, the
	   app-launch-block element specifies the following attribute. The
	   alert-driven attribute specifies whether the alert list or the
	   node list is used to determine the target nodes to run the tool
	   on. -->
      <!ATTLIST app-launch-block alert-driven (true | false) "false" >

      <!-- The app-parameters element is an application parameters
	   definition string whose value is a string -->
      <!ELEMENT app-parameters ( #PCDATA ) >

      <!-- The env-variable element is an environment variable definition
	   string whose value is a string -->
      <!ELEMENT env-variable ( #PCDATA ) >

      <!-- In addition to the previously described elements, the
	   env-variable element specifies the following attribute. The
	   name attribute specifies the name of the environment variable.
	   -->
      <!ATTLIST env-variable name CDATA #REQUIRED >

      <!-- The owner element specifies the tool owner. When the owner field
	   is specified, the tool is only associated with the All Tools toolbox.
	   When the owner field is not specified, tool is enabled in all
	   of its associated toolboxes. When a limited-rights user adds or
	   modifies a tool, the owner field contains the name of the
	   limited-rights user. Only a full-rights user may add or modify a
	   tool without the owner specified. -->
      <!ELEMENT owner ( #PCDATA ) >

      <!-- The comment field specifies additional information about the
	   tool. It is usually more verbose that the description. -->
      <!ELEMENT comment ( #PCDATA ) >

      <!-- The parameter element specifies the first to the tenth parameter
	   of a tool. -->
      <!ELEMENT parameter EMPTY >

      <!-- The parameter element has three attributes. The index attributes
	   specifies which argument in a parameterized string this parameter
	   substitutes. Parameters may be indexed from 1 to 10 with a
	   default index of 1. Tools cannot contain parameters with
	   duplicate indexes. If more than one parameter in a tool
	   definition contains the same index, only the first parameter added
	   to the tool with the duplicate index remains in the tool. The
	   prompt attribute provides information about the parameter that
	   may be displayed in a GUI for assistance. The required attribute
	   specifies whether this parameter must be specified when the tool
	   is executed. By default, parameters are not required.  The private
	   attribute specifies whether this parameter is encoded and stored
	   securely.  By default, parameters are not private. -->
      <!ATTLIST parameter index	 (1|2|3|4|5|6|7|8|9|10) "1"
			  prompt CDATA #REQUIRED
			  required (true|false) "false"
			  private (true|false) "false" >

      <!-- The toolbox-enabled element specifies whether the toolboxes
	   associated with a tool are enabled. -->
      <!ELEMENT toolbox-enabled EMPTY >

      <!-- The toolbox-enabled element has one attribute. The value
	   attribute specifies whether the tool within the toolboxes is enabled.
	   This allows a full-rights user to explicitly disable the tools in
	   a toolbox though the tool is always enabled in the All Tools
	   toolbox.  By default, the tool is enabled in all the toolboxes that
	   it is in.  If a tool is disabled within a toolbox, it cannot be
	   executed. -->
      <!ATTLIST toolbox-enabled value (true|false) "true">

      <!-- The role-enabled element specifies whether the roles associated
	   with a tool are enabled. This is an obsolete element. The
	   toolbox-enabled element should be used instead.
	   -->
      <!ELEMENT role-enabled EMPTY >

      <!-- See description of toolbox-enabled element attributes. -->
      <!ATTLIST role-enabled value (true|false) "true">

      <!-- The default-target element specifies a target on which the tool
	   may run if no targets are specified at run time. One may specify
	   a node, CMS to run on the CMS by default, or ALL to run on all
	   authorized nodes by default. -->
      <!ELEMENT default-target ( #PCDATA ) >

      <!-- The category element specifies the category with which to
	   associate the tool. By default, tools are associated with the
	   "Local Tools" category. -->
      <!ELEMENT category ( #PCDATA ) >

      <!-- The description element specifies a simple description of the
	   tool. To specify more verbose information such as how to run the
	   tool, use the comment element. -->
      <!ELEMENT description ( #PCDATA ) >

      <!-- For SSA and MSA command tools, the execute-as-user element
	   specifies the user name that the tool will run as or under whose
	   account the tool will run on the target nodes. For Web-launch
	   tools the execute-as-user is passed to the URL for its use. -->
      <!ELEMENT execute-as-user ( #PCDATA ) >

      <!-- The job display hander element specifies the fully-qualified
	   name of a class implementing the JobDisplayHander interface,
	   used to display the results of a job created by running this
	   tool. -->
      <!ELEMENT job-display-handler ( #PCDATA ) >

      <!-- The toolbox element specifies a toolbox to associate with the
	   tool. To run a tool the user must be authorized with one of the
	   specified toolboxes. -->
      <!ELEMENT toolbox EMPTY >

      <!-- The toolbox element has one attribute to specify the toolbox
	   name. -->
      <!ATTLIST toolbox toolbox-name CDATA #REQUIRED >

      <!-- The role element specifies a role to associate with the tool. To
	   run a tool the user must be authorized with one of the specified
	   roles. This element is obsolete. The toolbox element should be
	   used instead. -->
      <!ELEMENT role EMPTY >

      <!-- See the toolbox element attribute description. -->
      <!ATTLIST role role-name CDATA #REQUIRED >

      <!-- The include-filter element specifies node attributes against
	   which to filter a tool for execution. A specified include-filter
	   element must contain one or more node-filter elements. When
	   filtering a tool each include-filter block is "OR"ed together to
	   get the final filter result. Each node-filter element within an
	   include-filter block is "AND"ed together. -->
      <!ELEMENT include-filter (node-filter)+ >

      <!-- The include-filter elements has one attribute. The type attribute
	   specifies the type of include filter to execute. Four types are
	   currently recognized.  Three of them are os (operating system), hardware,
	   protocol filtering. The fourth type is called other which will
	   allow all other node attributes to be filtered upon.-->
      <!ATTLIST include-filter type (os | hardware | protocol | other) "os" >

      <!-- The node-filter element is an empty element that contains
	   attributes used to specify the node attributes against which to
	   filter a tool for execution. -->
      <!ELEMENT node-filter EMPTY >

      <!-- The node-filter element is specified with three attributes. The
	   name attribute specifies the node attribute name to filter
	   against. The operator attribute specifies whether to filter
	   against an equal value, a less than value, a greater than or
	   equal value, a contains value, a not equals value or a not
	   contains value. The operator name is case-insensitive. The
	   value attribute specifies the value of the node attribute to
	   filter against. -->
      <!ATTLIST node-filter name CDATA #REQUIRED
			    operator (EQ | GE | LT | CT | NEQ | NCT |
				      eq | ge | lt | ct | neq | nct |
				      Eq | Ge | Lt | Ct | Neq | Nct |
				      eQ | gE | lT | cT | nEQ | nCT ) "EQ"
			    value CDATA #REQUIRED >

      <!-- The attribute element specifies the name value pairs that
	   comprise client attributes. The client attribute name is
	   specified using the name attribute and the client attribute value
	   is specified as the PCDATA of the element. -->
      <!ELEMENT attribute ( #PCDATA ) >
      <!ATTLIST attribute name CDATA #REQUIRED >

    Revision attribute
      The revision attributes has a value that is interpreted as a version
      number 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"

    XML Header Line
      The first line of a tool XML file should be in the following format:

      <?xml version="1.0" encoding="encoding-value" ?>

      where the user substitutes a recognized encoding value for the
      encoding-value parameter.	 The recognized encoding values may be found
      at the following web site:

      http://www.iana.org/assignments/character-sets

      If no XML header line is specified, the system defaults encoding to
      "UTF-8".


    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. See examples for special
		treatment in a web-launch aware 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
	  %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).
	  %b	Device type of the target node.
	  %c	Device sub-type of the target node.
      %r%{rt[.attribute]%}  Substitutes the related node that has the
		relationship type as specified in the parameter "rt".
		Valid relationship type strings are those that are
		stored in the associationTypeNumber column in the
		device_associations table. If the [.attribute] is
		specified, then one of the named node attributes
		would be returned for the related nodeIn addition
		the common attributes such as Network name (.a) also
		work. For example, to get the server's management
		processor's IP address use %r{MgmtProcToServer.a%} to
		get the contact use %r{MgmtProcToServer.Contact%} .
		If the related nodes attribute is omitted
		then for each node, the network name and IP address
		is returned. The network name and IP address is
		returned in the form "network name|ip address" if
		more than one node is returned, then they are
		comma-delimited. Note that the relationship type
		"MgmtProcToServer" can be used to return related
		node information for all management processor
		relationship types.
      %{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

      For Web Launch Aware tools that use the %s parameter, it will be
      substituted with the CMS host name specified in the browser.

	  https://%s:2381/pmp/AdminHome.htm

      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" />
      or
      <node-filter name="attribute-name" operator="ct" value="attribute-value" />
      or
      <node-filter name="attribute-name" operator="neq" value="attribute-value" />
      or
      <node-filter name="attribute-name" operator="nct" 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. The "ct" operator specifies that a node the
      tool can run on must have an attribute that contains the value
      specified.  The "neq" operator specifies that a node the tool can run
      on must not have the exact attribute value specified. It applies to
      any attribute name allowed in a node filter expression. The "nct"
      operator specifies that a node the tool can run on must have the
      attribute that does not contain the value specified.  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).

      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
      Protocol Support	  protocol	any protocol name

      Other		  other		See mxnode(1M) or mxnode(4) for
					the list of pre-defined system
					attributes.

      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 the "os" filter type, 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" attributes specified by a tool filter will be assumed
      capable of running the tool. For the hardware filter type, the above
      statement is true in the case of the Model attribute.  But for the
      DeviceType and DeviceSubType attributes, the tool filter will
      apply only for known values on the selected nodes.  The "protocol"
      filter type requires that the protocol must exist on the node before
      the operators can be applied. This means that the neq and nct
      operators also depend on the node to have that protocol.	The other
      filter also works like the protocol filter such that the attribute
      being filtered upon must exist on the node before the operators can be
      applied.	If a tool uses the other and/or protocol filters, then
      at least one node must contain the filterable attributes for the tool
      to be displayed in the GUI.


    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 "<!--" and end 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 specifies multiple
      relationship types as parameterized substitutions.

      <?xml version="1.0" encoding="UTF-8"?>
      <tool-list>
	<msa-command-tool name="PingTest" revision="1.0">
	  <category>General Tools</category>
	  <description>Test management path parameter expansion</description>
	  <msa-block>
	      <command command-type="stdout" log="true">ping %r%{MgmtProcToServer.a%} %r%{ServerToEnclosure%} %r%{EnclosureToRack%}</command>
	      <execution-node>CMS</execution-node>
	  </msa-block>
	</msa-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.


SEE ALSO for HP-UX

      mxtool(1M), mxexec(1M).


SEE ALSO for Linux

      mxtool(8), mxexec(8).