NAME
mxtoolbox - add, modify, remove, or list toolboxes in Systems Insight
Manager
SYNOPSIS
mxtoolbox -a toolboxname [-d description] [-e t|f]
mxtoolbox -a [-f filename]
mxtoolbox -m toolboxname [-N new_toolboxname] [-d description] [-e t|f]
mxtoolbox -m [-f filename]
mxtoolbox -r toolboxname
mxtoolbox -r [-f filename]
mxtoolbox [-l n|t]
mxtoolbox -lf [-b encoding]
DESCRIPTION
The mxtoolbox command allows a Systems Insight Manager full rights
user to add, rename, describe, disable, enable, remove, and list
Systems Insight Manager toolboxes. The Master ToolBox is a special
Systems Insight Manager toolbox, added by the system, that may not be
modified in any way.
The first form of the command allows a full rights user to add a
single Systems Insight Manager toolbox and optionally provide a
toolbox description and enable or disable the toolbox. To add a
toolbox, a full rights user must provide a toolbox name. The toolbox
name must start with an alphabetic character followed by alphanumeric
characters, embedded blank characters, underscore (_) or dash (-); and
must be less than or equal to 16 characters in length. full rights
users may add up to 32 toolboxes. toolboxes are enabled by default. To
explicitly enable a toolbox, the full rights user may enter t after
the -e option. To disable a toolbox, the full rights user enters f
after the -e option. When the toolbox is enabled, Systems Insight
Manager tools associated with the toolbox may be authorized using the
toolbox. When the toolbox is disabled, Systems Insight Manager tools
associated with the toolbox cannot be authorized using the toolbox.
The second form of the command allows a full rights user to add
multiple toolboxes based on information provided in a file. The file
must be formatted in the eXtensible Markup Language (XML) format
defined for Systems Insight Manager toolboxes. See mxtoolbox(4).
The third form of the command allows a full rights user to modify a
single Systems Insight Manager toolbox. A full rights user may modify
the name, description, and enablement of the toolbox. The Master
ToolBox may not be modified.
The fourth form of the command allows a full rights user to modify
multiple toolboxes based on information provided in a file. The file
must be formatted in the eXtensible Markup Language (XML) format
defined for Systems Insight Manager toolboxes. See mxtoolbox(4).
The fifth form of the command allows a full rights user to remove a
single toolbox from the Systems Insight Manager repository. The
Master ToolBox may not be removed from the Systems Insight Manager
repository.
The sixth form of the command allows a full rights user to remove
multiple toolboxes based on information provided in a file. The file
must be formatted in the eXtensible Markup Language (XML) format
defined for Systems Insight Manager toolboxes. See mxtoolbox(4).
The seventh form allows a full rights user to list the Systems Insight
Manager toolboxnames or to view the details of all Systems Insight
Manager toolboxes. When invoked with no options, mxtoolbox gives a
columnar listing of the names of all the Systems Insight Manager
toolboxes. This is the same as invoking the command with the n
argument. When invoked with the t argument, the system lists the
toolboxes in tabular format displaying the toolbox name, its
enablement value, and the toolbox description.
The last form allows a full rights user to list the Systems Insight
Manager toolboxes in an XML file format. Optionally the user may
specify the character encoding of 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
Only Systems Insight Manager full rights users may use mxtoolbox to
add, modify, or remove Systems Insight Manager toolboxes. Any Systems
Insight Manager user may display Systems Insight Manager toolbox
information.
ToolBox Attributes
The following ToolBox Attributes define an Systems Insight Manager
toolbox:
toolboxname The name of the Systems Insight Manager toolbox
must start with an alphabetic character and may
have embedded spaces and its maximum length is 16
characters. Systems Insight Manager toolboxnames
are not case sensitive.
description The Systems Insight Manager-specific description
for this Systems Insight Manager toolbox. Its
maximum length is 128 characters.
enablement The state of enablement of the Systems Insight
Manager toolbox. A disabled Systems Insight
Manager toolbox prevents execution of any Systems
Insight Manager tool on behalf of the Systems
Insight Manager toolbox.
File Processing
The mxtoolbox command allows a full rights user to add, modify, or
remove Systems Insight Manager toolboxes by specifying an XML file
containing a list of toolboxes and toolbox attributes.
The Systems Insight Manager processes the input file data in two
passes.
The first pass attempts to parse the XML file and generate a list of
toolboxes to process during the second pass. The first pass ensures
that the XML file is formatted properly, that the toolbox names are
valid, and the toolbox objects contain valid information. During the
first pass, if the Systems Insight Manager detects a error, the
Systems Insight Manager interrupts the process, issues an error
message describing the error, and leaves the Systems Insight Manager
repository unchanged.
If the Systems Insight Manager successfully processes the XML file in
the first pass, then the Systems Insight Manager attempts to process
the toolbox list collected during the first pass. During this second
pass, the Systems Insight Manager processes the toolbox list until it
processes the entire list or until the Systems Insight Manager
encounters a logic error, such as specifying a duplicate toolbox
during an add, specifying a non-existent toolbox during a modify, or
attempting to remove the Master ToolBox during a remove.
If an error occurs during the second pass, the Systems Insight Manager
interrupts processing at that point and issues an error message. If
the input file contains valid toolbox data prior to the invalid data,
the Systems Insight Manager processes that data completely and
modifies the Systems Insight Manager repository appropriately. The
Systems Insight Manager ignores all data subsequent to the invalid
data.
Options
mxtoolbox recognizes the following options:
-a Indicates that a toolbox is to be added.
-d description Specifies the description to be associated with
the Systems Insight Manager toolbox.
-e t|f Specifies that the Systems Insight Manager toolbox
enablement is to be set in the indicated manner -
t (indicating enabled) or f (indicating disabled).
-f filename Indicates that information regarding users to be
added, modified or removed is provided in the XML
file specified by filename (see mxuser(4) ).
-l n Produces a columnar list of the names of all
enabled and disabled Systems Insight Manager
toolboxes. This produces the same result as not
specifying any options with the command.
-l t Indicates that a tabular display of Systems
Insight Manager toolbox attributes, for all
Systems Insight Manager toolboxes, is to be
presented.
-l f Indicates that the system should generate the
toolbox information in XML format.
-b encoding Used in conjunction with the -lf option to specify
the character encoding for the XML file.
-m toolboxname Indicates the Systems Insight Manager toolbox that
is to be modified.
-N new_toolboxname
Defines the new Systems Insight Manager
toolboxname for the specified Systems Insight
Manager toolbox.
-r Indicates that the toolbox is to be completely
removed.
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
mxtoolbox returns one of the following values:
0 Successful completion.
1 Command line syntax error.
2 Error in a file operation.
3 Nonexistent toolbox error.
5 Duplicate toolbox error.
21 Invalid name.
22 Invalid description.
26 Unsupported operation.
50 Unauthorized user.
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.
253 Duplicate name.
LIMITS
Valid toolbox names may not exceed a length of 16 characters but may
be as short as a single character. The initial character of a toolbox
name must be an upper- or lower-case letter.
Digits, underscores, dashes and white space are legal toolbox name
elements. Trailing whitespace is trimmed.
EXAMPLES
Add the "HP ASE" Systems Insight Manager toolbox.
mxtoolbox -a "HP ASE" -c "HP account support engineer."
Add a file of toolboxes.
mxtoolbox -a -f toolboxlist.xml
Disable the "HP ASE" Systems Insight Manager toolbox.
mxtoolbox -m "HP ASE" -e f
Modify a file of toolboxes.
mxtoolbox -m -f toolboxlist.xml
Remove the "HP ASE" toolbox.
mxtoolbox -r "HP ASE"
Remove a file of toolboxes.
mxtoolbox -r -f toolboxlist.xml
List the names of all Systems Insight Manager toolboxes.
mxtoolbox -l n
The output might look like the following:
lvmadmin
operator
webadmin
dbadmin
Master ToolBox
List the attributes for all Systems Insight Manager toolboxes. Systems
Insight Manager toolboxes that have never been modified are shown as
well.
mxtoolbox -l t
The output might look like the following:
NAME ENABLED? DESCRIPTION
lvmadmin true A toolbox for LVM Administrators
operator true A read-only toolbox for operators
webadmin true A toolbox for WEB Server
Administrators
dbadmin true A toolbox for Database Administrators
Master ToolBox true The Systems Insight Master ToolBox
List all Systems Insight Manager toolboxes to an XML file.
mxtoolbox -l f
The output might look like the following:
<?xml version="1.0" encoding="UTF-8"?>
<toolbox-list>
<toolbox name="webadmin"
guid="00000000864162de0eea403317500000">
<enabled value="true" />
<description>WEB Server Administrator</description>
</toolbox>
<toolbox name="Master ToolBox"
guid="00000000864162de0eea4032a2a00000">
<enabled value="true" />
<description>Master ToolBox added by Systems Insight
Manager.</description>
</toolbox>
<toolbox name="operator"
guid="00000000864162de0eea40331bf00000">
<enabled value="true" />
<description>A read-only toolbox for operators</description>
</toolbox>
<toolbox name="dbadmin"
guid="00000000864162de0eea403301600000">
<enabled value="true" />
<description>Database Administrator</description>
</toolbox>
<toolbox name="lvmadmin"
guid="00000000864162de0eea403323000000">
<enabled value="true" />
<description>LVM Administrator</description>
</toolbox>
</toolbox-list>
LIMITATIONS
This command may only be run on the CMS.
There is a limit of 32 Systems Insight Manager toolboxes, of which all
but the Master ToolBox may be modified in or removed from the Systems
Insight Manager repository. The Master ToolBox is a special Systems
Insight Manager toolbox that may not modified in any way, nor may this
Systems Insight Manager toolbox be removed from an Systems Insight
Manager tool's Systems Insight Manager toolbox authorizations.
AUTHOR
mxtoolbox was developed by the Hewlett-Packard Company.
SEE ALSO for HP-UX
mxtoolbox(4), mxauth(1M), mxtool(1M).
SEE ALSO for Linux
mxtoolbox(4), mxauth(8), mxtool(8).