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).