NAME

      mxngroup - add, modify, remove, or list system groups in Systems
      Insight Manager


SYNOPSIS

      mxngroup -a -g groupname [-d description] [-n [member...]]
      mxngroup -a -f filename
      mxngroup -m -g groupname [-d description] [-n [member...]] -[u]
      mxngroup -m -f filename
      mxngroup -r -g groupname
      mxngroup -r -f filename
      mxngroup [-l d|f|m|n] [-g groupname...]
      mxngroup [-l d|f|m|n] [-n [member...]]
      mxngroup -lf [-g groupname...] [-b encoding]
      mxngroup -lf [-n [member...]] [-b encoding]


DESCRIPTION

      The mxngroup command allows the user to create, modify, remove, and
      list system groups in Systems Insight Manager. System groups are
      collections of systems that are subsets of all the systems discovered
      by Systems Insight Manager. They may have overlapping memberships such
      that a single system may be a member of more than one group.  The
      system grouping mechanism allows flexible partitioning of systems into
      logical collections that match their use model.

      When a system group is created, its attributes and membership may be
      specified. When it is modified, its attributes may be selectively
      modified, its membership may be reset, and it may be updated based on
      a collection.

      The first two forms of this command allow the user to add system
      groups.

      The second form allows the information regarding one or more system
      groups to be provided in a file. The file must be formatted in the
      eXtensible Markup Language (XML) format defined for Systems Insight
      Manager system groups. See mxngroup(4).

      The third and fourth forms allow the user to modify the information
      stored about a system group. As with adding system groups, the group
      may be specified on the command line or in a file.  The file must be
      formatted as described previously.  Note that when modifying system
      groups, Systems Insight Manager also updates the authorization
      information related to any authorizations associated with the modified
      system group.

      The fifth and sixth forms allows the user to remove a system group.
      The user may either specify an individual system group or a file
      containing multiple system groups. The file must be formatted as
      described previously. When an Systems Insight Manager full rights user
      removes a system group, the Systems Insight Manager also removes all
      of the authorizations associated with the removed system group.

      The seventh and eigth forms allow the user to list system group names
      and attributes.  The -l option indicates that system group information
      is to be listed.	With the n argument, system group names are listed,
      one per line.  The d argument indicates that a detailed listing of
      system group names and attributes is desired.  The f option results in
      a listing that matches the file format used for the -f filename option
      in the add and modify commands.  The m argument gives a combined list
      of members of the system groups, one member per line. The set of
      system groups that gets listed may be constrained in two ways. With
      the -g option, the names of the desired groups may be specified.	The
      -n option lists system groups that contain all of the specified
      members.	By default, all system groups are listed.

      The last two forms allow the user to list the system group information
      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

      Only Systems Insight Manager full rights users may use mxngroup to
      add, modify or remove system groups.  Any Systems Insight Manager user
      may list group information.

    File Processing
      The mxngroup command allows a full rights user to add, modify, or
      remove Systems Insight Manager system groups by specifying an XML file
      containing a list of system groups and system group 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
      system groups to process during the second pass. The first pass
      ensures that the XML file is formatted properly, that the system group
      names are valid, and the system group objects contain valid
      information. During the first pass, if the Systems Insight Manager
      detects an 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, the Systems Insight Manager attempts to process the
      system group list collected during the first pass. During this second
      pass, the Systems Insight Manager processes the system group list
      until it processes the entire list or until the Systems Insight
      Manager encounters a logic error, such as specifying a duplicate
      system group during an add or specifying a non-existent system group
      during a modify or 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 system group 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
      mxngroup recognizes the following options:

	   -a		  Indicates that a group is to be added.

	   -m		  Indicates that a group is to be modified.

	   -r		  Indicates that a group is to be removed.

	   -l d		  Displays a detailed and screen-viewable listing of
			  system group information.

	   -l f		  Displays a file-formatted listing of system group
			  information (see mxngroup(4) ).

	   -l m		  Displays the member systems of the system group.

	   -l n		  Displays the names of the system groups.

	   -f filename	  Specifies the path and name of the input file for
			  an add, modify, or remove operation.

	   -g groupname	  Specifies the name of the group to be added,
			  modified, removed, or listed. System group names
			  must be 80 characters or less, must start with an
			  alphabetic character, and after the first
			  character may contain alphanumeric characters,
			  underscore (_), dash (-), and period (.)
			  characters and embedded blank characters.

	   -n member	  When used with the -a or -m options, this option
			  specifies the complete membership of a group that
			  is added or modified.	 When used in a listing
			  command (-l), this option indicates that the
			  system groups to be listed are the ones that
			  contain the specified members.

	   -d description Specifies the description for a group.


	   -b encoding	  Specifies the character encoding when used in
			  conjunction with the -lf option.

	   -u		  The -u option updates the system group members
			  based on the collection.  It may only be used in
			  conjunction with the -m option as shown below.
			  -m -g	 groupname -u

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

      mxngroup returns one of the following values:

	     0		  Successful completion.
	     1		  Command line syntax error.
	     2		  Error in a file operation.
	     3		  Nonexistent system or system group error.
	     5		  Duplicate name.
	    21		  Invalid name.
	    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.


EXAMPLES

      The following command creates a system group "group1" containing
      systems "systema", "systemb", and "systemc":

	   mxngroup -a -g group1 -d "Example system group" -n systema
	   systemb systemc

      To modify group "group1" to replace system "systemc" with system
      "systemd", the following command may be used:

	   mxngroup -m -g group1 -n systema systemb systemd

      To update group "group1" from the collection, the following command
      may be used:

	   mxngroup -m -g group -u

      The member systems of group "group1" may be listed by using:

	   mxngroup -lm -g group1

      The names of all the system groups that contain member "systemb" may
      be listed by using:

	   mxngroup -ln -n systemb

      or simply:

	   mxngroup -n systemb

      The following is an example of a legal system group XML file based on
      the supported file format. The following example defines a system
      group named "group1" with a description and two member systems,
      system1.corp.com and system2.corp.com.

	   <?xml version="1.0" encoding="UTF-8"?>
	   <node-group-list>
	       <node-group name="group1">
		   <description>This is group1.</description>
		   <member-node value="system1.corp.com" />
		   <member-node value="system2.corp.com" />
	       </node-group>
	   </node-group-list>


WARNINGS

      Only Systems Insight Manager full rights users may use mxngroup to
      add, modify or remove system groups.  Any Systems Insight Manager user
      may display group information.


LIMITATIONS

      This command may only be run on the CMS.


AUTHOR

      mxngroup was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

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


SEE ALSO for Linux

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