NAME

      mxauth - add, remove, or list authorizations in Systems Insight
      Manager


SYNOPSIS

      mxauth -a|r -u username -R toolboxname -n nodename
      mxauth -a|r -u username -R toolboxname -g groupname
      mxauth -a|r -f filename
      mxauth [-lt]
      mxauth -lf [-b encoding ]


DESCRIPTION

      mxauth is used by a Systems Insight Manager full rights user to manage
      Systems Insight Manager authorizations. These associations between
      users, toolboxes and nodes or node groups may only be added or removed
      by the Systems Insight Manager full rights user, but any Systems
      Insight Manager user may list authorizations. Authorizations formed
      from users, toolboxes, and nodes are called node authorizations.

      The first form of the command enables a full rights user to add or
      remove one node authorization. All options and associated parameters
      are required to completely specify a node authorization. Asterisks are
      supported for the node parameter. The Systems Insight Manager
      recognizes the asterisk as a wildcard to indicate adding the node
      authorization for all nodes currently configured in the Systems
      Insight Manager. Note that when using the wildcard character on the
      command line, the user must enclose the wildcard character in either
      double quotes("*") or single quotes('*') to prevent the shell
      interpreter from preprocessing the wildcard character. An error
      results if any option or its data is missing.

      The second form of the command enables a full rights user to add or
      remove one node group authorization. All options and associated
      parameters are required to completely specify a node group
      authorization. Asterisks are supported for the node group parameter.
      The Systems Insight Manager recognizes the asterisk as a wildcard to
      indicate adding the node group authorization for all node groups
      currently configured in the Systems Insight Manager.  An error results
      if any option or its data is missing.

      The third form of the command allows a full rights user to add or
      remove multiple authorizations by specifying an input file containing
      node and node group authorizations. The file must be formatted in the
      eXtensible Markup Language (XML) format defined for Systems Insight
      Manager. See mxauth(4).

      The fourth form of the command allows information about one or more
      authorizations to be listed in either simple or table formats.

      When invoked with no options, mxauth lists all authorization names in
      compact form with the authorization fields separated by colons (:).
      Node authorizations display as
      user:toolboxname:n:nodename
      Node group authorizations display as user:toolboxname:g:groupname
      When using the -l t option, mxauth lists all authorization in a
      tabular format with column headings identifying each field.

      The last form of the command outputs the authorization information in
      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

    File Processing
      The mxauth command allows a full rights user to add or remove Systems
      Insight Manager authorizations by specifying an XML file containing a
      list of authorizations.

      The Systems Insight Manager processes the input file data in three
      passes.

      The first pass attempts to parse the XML file and generate a list of
      authorizations to process during the second pass. The first pass
      ensures that the XML file is formatted properly, that the
      authorization objects contain syntactically 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.

      During the second pass, the command tries to resolve the components in
      each authorization from the first pass to real objects in the Systems
      Insight Manager repository. The command determines if the user name
      represents a existing Systems Insight Manager user, if the toolboxname
      represents a valid Systems Insight Manager toolbox, if the node name
      represents a valid Systems Insight Manager node, and if the node group
      name represents a valid Systems Insight Manager node group. If the
      command encounters a logic error, such as specifying a non-existent
      user, toolbox, node, or node group, the command issues an error
      message, interrupts processing, and leaves the Systems Insight Manager
      repository unchanged.

      During the third pass, the command performs the requested add or
      delete of the authorization list and updates the Systems Insight
      Manager repository appropriately. During an add, the command ignores
      duplicate authorizations. During a remove, the command ignores
      undefined authorizations.


    Options
      mxauth recognizes the following options:

	   -a		  Add authorization(s). The wildcard character (*)
			  is supported for the node and group name
			  arguments.

	   -r		  Remove authorization(s). The wildcard character
			  (*) is supported for the node and group name
			  arguments.

	   -f filename	  Indicates that authorizations to be added or
			  removed are specified in filename.

	   -l  t	  List all authorizations in the tabular format.

	   -l  f	  List all authorization names in the XML file
			  format. This option may be used to edit
			  authorizations that have been saved to a file.
			  This file may subsequently be used in conjunction
			  with the -f option to add or remove
			  authorizations.

	   -b encoding	  Used in conjunction with the -lf option to specify
			  the character encoding for the XML file.

    Authorization Attributes
	   -u username|UID
			  Specifies the user for the authorization.  Note:
			  This option does not currently support user
			  groups.

	   -R toolboxname Specifies the toolbox name for the authorization.
			  Toolbox names with embedded spaces must be
			  enclosed in quotes.

	   -n nodename	  Specifies the node name for the authorization. The
			  wildcard character (*) is supported for the node
			  name argument.

	   -g groupname	  Specifies the node group name for the
			  authorization. The wildcard character (*) is
			  supported for the node group name argument.  Note:
			  This option does not currently support user
			  groups.

      Note: When duplicate options are specified (for example, -f file1 -
      f file2), the last instance of the option will be used by mxauth (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

      mxauth returns one of the following values:

	     0		  Successful completion.
	     1		  Command line syntax error.
	     2		  Error in a file operation.
	     3		  Nonexistent user, toolbox, node, or node group
			  error.
	    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.


DIAGNOSTICS

      mxauth writes to stdout, stderr and the Systems Insight Manager log
      file.


EXAMPLES

      Add the authorizations defined in the file "my_auths.xml".

	   mxauth -a -f my_auths.xml

      The contents of "my_auths.xml" might look like:


	   <?xml version="1.0" encoding="UTF-8"?>
	   <auth-list>
	       <node-authorization user-name="user1"
				   toolbox-name="webadmin"
				   node-name="node1.corp.com" />
	       <node-authorization user-name="user2"
				   toolbox-name="operator"
				   node-name="node1.corp.com" />
	       <node-authorization user-name="user3"
				   toolbox-name="dbadmin"
				   node-name="node2.corp.com" />
	   </auth-list>

      The first line above gives user "user1" the toolbox of "webadmin" on
      the node "node1.corp.com".  The second line gives user "user2" the
      toolbox of "operator" on node "node1.corp.com". The third line gives
      user "user3" the toolbox of operator on node "node2.corp.com".
      Add the node authorization to allow user "bill" to execute any tools
      assigned to the "webadmin" toolbox on node "web01".

	   mxauth -a -u bill -R webadmin -n web01

      Use the wildcard character to add the node authorizations that allow
      user "jane" to execute any tools assigned to the "webadmin" toolbox on
      all nodes configured on the Systems Insight Managed cluster at the
      time the command is executed.

	   mxauth -a -u jane -R webadmin -n "*"

      Remove the node authorization for user "martha" to execute any tools
      assigned to the "sapadmin" toolbox on node "sap01".

	   mxauth -r -u martha -n sap01 -R sapadmin

      Use the wildcard character to remove the node authorizations that
      allow user "wilma" to execute any tools assigned to the "webadmin"
      toolbox on all nodes configured on the Systems Insight Managed cluster
      at the time the command is executed.

	   mxauth -r -u wilma -R webadmin -n '*'

      Add the node group authorization to allow user "sue" to execute any
      tools assigned to the "webadmin" toolbox on nodegroup "webGroup".

	   mxauth -a -u sue -R webadmin -g webGroup

      Use the wildcard character to add the node group authorizations that
      allow user "jane" to execute any tools assigned to the "operator"
      toolbox on all node groups configured on the Systems Insight Managed
      cluster at the time the command is executed.

	   mxauth -a -u jane -R operator -g "*"

      Remove the node group authorization for user "john" to execute any
      tools assigned to the "dbadmin" toolbox on nodegroup "dbGroup".

	   mxauth -r -u john -R dbadmin -g dbGroup

      Remove the node group authorizations that allow user "john" to execute
      any tools assigned to the "dbadmin" toolbox on all node groups
      currently configured on the Systems Insight Managed cluster.

	   mxauth -r -u john -R dbadmin -g '*'

      List, in a tabular format, all authorizations assigned to all users in
      the Systems Insight Managed Cluster.


	   mxauth -l t


LIMITATIONS

      This command may only be run on the CMS.

    Removing Nonexistent Authorizations
      It is not an error to remove an authorization that does not exist in
      the Systems Insight Manager. This operation results in an exit code of
      zero being returned by this command.

      An authorization is nonexistent if all of its attributes (user name,
      toolbox name, node or node group name) are valid Systems Insight
      Manager objects, but they are not associated as an authorization.

    Adding Duplicate Authorizations
      It is not an error to add an authorization that already exists in the
      Systems Insight Manager. This operation results in an exit code of
      zero being returned by this command.


AUTHOR

      mxauth was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

      mxauth(4), mxuser(1M), mxngroup(1M), mxnode(1M), mxtoolbox(1M).


SEE ALSO for Linux

      mxauth(4), mxuser(8), mxngroup(8), mxnode(8), mxtoolbox(8).