NAME
mxtool - add, list, modify, or remove tools in Systems Insight Manager
SYNOPSIS
mxtool -a -f filename
mxtool -m [-i] -f filename [-x force]
mxtool -s -f filename
mxtool -r [-f filename |-c category | -t toolname ] [-x force]
mxtool -l d|f|n|t [-c category ... | -t toolname ...]
mxtool -lf [-b encoding] [-c category ... | -t toolname ...]
mxtool
DESCRIPTION
The mxtool command allows a Systems Insight Manager user to add, list,
modify or remove tools in Systems Insight Manager.
The first form of this command allows the user to add tools. The
information regarding the tool is provided in a tool definition file
(see mxtool(4)) and allows the user to add one or more Systems Insight
Manager tools.
When adding a tool, if the user is a full rights user (see mxuser(1)),
Systems Insight Manager will accept the owner value specified for a
given tool in the tool definition file. If the owner field is not
specified, then the tool's owner field is empty and this tool is
enabled in all toolboxes that it is in. If the user is not a full
rights user, however, Systems Insight Manager will ignore the owner
specification for the given tool and set the tool's owner field to the
user's id only. Additionally, if the user is not a full rights user,
Systems Insight Manager only allows the "All Tools" toolbox to be
defined in a tool definition. Systems Insight Manager ignores the
value of the toolbox enabled flag and only enables the "All Tools"
toolbox.
When the owner field is specified, that is not empty, Systems Insight
Manager ignores the toolbox enabled flag and disables the tool in all
of the specified toolboxes with the exception of the "All Tools". To
enable the tool in all of the specified toolboxes, a full rights user
must modify the tool's definition. Specifically, a full rights user
must remove the owner field from the tool. By default, when a full
rights user removes the owner field, Systems Insight Manager sets the
toolbox enabled flag to "true". A full rights user may set the toolbox
enabled flag to "false" to explicitly disable the tool in all of the
toolboxes except the "All Tools".
During an add operation, Systems Insight Manager will only add tools
whose names do not reference tools currently in Systems Insight
Manager. If Systems Insight Manager detects a duplicate tool, Systems
Insight Manager will inform the operator of the add operation, but
will continue to add all non-duplicate tools. Skipping duplicate tools
in this case does not affect the exit code. During the add operation,
Systems Insight Manager assigns the "All Tools" toolbox to every tool
by default.
The second form of mxtool allows the user to modify the definition of
one or more Systems Insight Manager tools. The information regarding
the tool is provided in a tool definition file. When modifying a
tool, the user must either be the tool's owner or be a full rights
user. If the user is a full rights user, the user may modify the
entire tool definition. If the user is the owner but is not a full
rights user, the user may modify most attributes of the tool but may
not modify the owner attribute or the tool's toolboxes. Systems
Insight Manager ignores the value of the toolbox enabled flag in the
input file and sets the toolbox enabled flag in the tool to "false".
By specifying the -i option, the full rights user directs Systems
Insight Manager to ignore changes to toolboxes in the modified tool
definitions.
If the owner field of the tool is not set and a non-full rights user
wishes to modify the tool, a full rights user must modify the tool's
definition to set the tool's owner field to the user name of the non-
full rights user. Additionally, mxtool will ignore any changes to a
tool's toolboxes made by a non-full rights user.
Systems Insight Manager will not allow the user to add tools using the
modify option. During the modify operation, if Systems Insight Manager
finds a tool in the tool definition file that does not exist in
Systems Insight Manager, Systems Insight Manager will notify the user
of the modify operation, but will continue to modify the tools
specified in the tool definition file that do exist in Systems Insight
Manager. Skipping undefined tools in this case does not affect the
exit code.
During the modify operation, Systems Insight Manager will not permit
the user to remove the "All Tools" toolbox from any tool.
Only a full rights user is allowed to add or modify and tool which is
multiple-system aware, such as Ignite. Only a full rights user is
allowed to delete a tool.
All tools must contain the revision attribute. The revision attribute
is used to confirm that the tool defined in the tool definition file
is of a greater revision than the one in Systems Insight Manager. The
tool revision attribute is used while modifying a tool. If it is not
provided, then a revision of 1.0 is assigned to the tool in Systems
Insight Manager when it is added. By specifying the -x force option,
Systems Insight Manager is directed to ignore the tool revision
attribute in the modified tool definitions.
The third form of mxtool allows the user to scan a tool definition
file without changing the Systems Insight Manager domain, i.e. adding
or modifying an Systems Insight Manager tool. This form allows the
user to check a tool definition file for syntax errors.
The fourth form of mxtool allows the user to remove Systems Insight
Manager tools. Only a full rights user may remove a tool. If the
user specifies a tool name that does not correspond to a tool in
Systems Insight Manager, Systems Insight Manager will notify the user
that it cannot find the tool and will attempt to remove the next
designated tool. Skipping undefined tools in this case does not affect
the exit code. If a task has been created using the tool, then
attempts to remove it are not successful. By specifying the -x force
option, Systems Insight Manager is directed to ignore the task
dependencies of the tool and remove it. The user may specify the
tools as a list of tool names, a list of categories, or a tool
definition file.
The fifth form of mxtool allows the user to list Systems Insight
Manager tools or to view the definitions of specific Systems Insight
Manager tools. With no qualifiers, mxtool lists the names of all
registered Systems Insight Manager tools. With the d qualifier, mxtool
provides a detailed screen-viewable listing of Systems Insight Manager
tools. With the f qualifier, mxtool writes to stdout a complete
Systems Insight Manager tool definition (see mxtool(4)) for each
Systems Insight Manager tool. With the n qualifier, mxtool provides a
list of all Systems Insight Manager toolnames (the same as no
qualifier). With the t qualifier, mxtool gives a tabular listing
showing some of the attributes of all registered Systems Insight
Manager tools. The -c option allows the Systems Insight Manager user
to constrain the output to one or more tool categories. The -t
option allows the Systems Insight Manager user to constrain the output
to specific Systems Insight Manager tools.
The sixth form of mxtool lists the Systems Insight Manager tools in an
XML file format. Optionally, the user may specify the character
encoding in the XML file. The value for the character encoding must
match a valid character encoding. If no encoding is specified, the
system attempts to write the file in the encoding currently defined
for the given system. The list of valid character encodings is
maintained at the following web site.
http://www.iana.org/assignments/character-sets
The last form of mxtool lists the names of all Systems Insight Manager
tools currently configured in the Systems Insight Manager domain.
Options
mxtool recognizes the following options:
-a Indicates that one or more Systems Insight Manager
tools, specified in a tool definition file, are to
be added.
-r Indicates that one or more Systems Insight Manager
tools are to be removed.
-m Indicates that one or more Systems Insight Manager
tool definitions are to be replaced by the
definition in the specified tool definition file.
-i Directs Systems Insight Manager to ignore changes
to toolboxes in the tool definitions. This option
is only valid with the -m modify option.
-s Indicates that the specified tool definition file
should be scanned for syntax errors without
performing any other operations.
-c category Specifies a tool category. Specification of an
undefined category name results in mxtool
returning an empty tool list and an exit code of
SUCCESS. Specification of an invalid category
name, i.e. one that violates the rules for
category names (see mxtool(4)), results in an
invalid name exit code.
-t toolname Specifies the name of the Systems Insight Manager
tool to be removed or listed. Specification of an
undefined tool name results in mxtool operating on
zero tools and an exit code of SUCCESS.
Specification of an invalid tool name, i.e. one
that violates the rules for tool names (see
mxtool(4)), results in an invalid name exit code.
-f filename Specifies the path and name of a file that
contains the definition of one or more Systems
Insight Manager tools to be added or modified.
This option must also be specified with the scan
option, -s. See mxtool(4).
-l d Displays a detailed and screen-viewable listing of
Systems Insight Manager tools.
-l f Displays a file-formatted listing of Systems
Insight Manager tools (this output may be used as
input to the -f option).
-l n Displays the names of Systems Insight Manager
tools.
-l t Displays a tabular list of Systems Insight Manager
tools and tool attributes.
-b encoding Specifies the character encoding of an XML file
when used in conjunction with the -lf option.
-x Specifies an extended option value. This is used
in conjuction with the following keywords.
force Specifies to force a tool into the system when
used in conjuction with the -mf option. Or,
specifies the forced confjunction with the -rf
option.
Note: When duplicate options are specified (for example, -f file1 -
f file2), the last instance of the option will be used by mxtool (in
this example, file2).
EXTERNAL INFLUENCES
For HP-UX or Linux, LANG determines the default encoding that the
system will use to output XML data if no encoding is specified on the
command line. If LANG is not specified or null or LANG does not
correspond to a recognized encoding, it defaults to C (see lang (5)).
In this case, the user should use the -b option to specify the desired
encoding of the XML data.
RETURN VALUE
mxtool returns one of the following values:
0 Successful completion.
1 Command line syntax error.
2 Error in a file operation or parsing a file.
21 Invalid name.
102 Systems Insight Manager Repository error.
222 Central Management Server (CMS) is not
initialized.
249 Unable to connect to the session manager.
250 Remote exception.
EXAMPLES
This command adds the tools defined in the Systems Insight Manager
tool definition file named "/home/user1/defs/mytooldef".
mxtool -a -f /home/user1/defs/mytooldef
This command modifies tools based on the Systems Insight Manager tool
definition file named "/home/user1/defs/mytoolmods".
mxtool -m -f /home/user1/defs/mytoolmods
This command forcefully modifies the tools based on the Systems
Insight Manager tool definition file named
"/home/user1/defs/mytoolmods".
mxtool -m -f /home/user1/defs/mytoolmods -x force
This command removes the Systems Insight Manager tool called
"badtool".
mxtool -r -t badtool
This command displays the list of Systems Insight Manager toolnames.
mxtool -ln
This command displays a detailed, screen-viewable listing of the
Systems Insight Manager tools.
mxtool -ld
This command displays a tabular listing of the Systems Insight Manager
tools with column headings.
mxtool -lt
This command displays the Systems Insight Manager tools in XML file
format.
mxtool -lf
LIMITATIONS
This command may only be run on the CMS.
AUTHOR
mxtool was developed by the Hewlett-Packard Company.
SEE ALSO for HP-UX
mxexec(1M), mxtool(4).
SEE ALSO for Linux
mxexec(8), mxtool(4).