NAME

      mxexec - run a Systems Insight Manager tool


SYNOPSIS

      mxexec -t toolname [-A argvalue ...] ...	[-h | -O filename | -
      o directory ] [-n target ... | -q queryname] ...

      mxexec -c [-k] -j job_ID
      mxexec [-l n|t] [-i task_name ... | -j job_ID... ] [-d date]
      mxexec -l d [-h] -j job_ID ...


DESCRIPTION

      The mxexec command is used to execute a Systems Insight Manager tool,
      with associated arguments, on specific Systems Insight managed nodes
      and/or node groups.  An Systems Insight Manager tool and its
      arguments, specified to run on one or more nodes, is called a task.
      An instance of the task running at a particular time is called a job.

      The first form of the command allows the user to run Systems Insight
      Manager tools.  The toolname is required by mxexec to run the tool.
      In addition, depending upon the tool being run, the argument values
      and the targets may also be required.  The results returned by the
      tool may be optionally saved in one file or a series of files, one per
      Systems Insight managed node. Additionally, the operator may specify
      the option to suppress the job header information and send the job's
      standard output to stdout and the job's standard error to stderr. Note
      that the option to suppress the job header information is mutually
      exclusive with the options to send the job output to a file or
      directory.

      The second form allows a specific job to be cancelled (and the command
      execution optionally killed). Only a Full Rights user or the user that
      initiated the job can cancel or kill the job.

      The last two forms allow the user to list information about one or
      more running jobs.  All jobs can be listed, specific jobs can be
      listed by job_ID and all the jobs for a specific task_name can be
      listed. All jobs that completed after a specific date can be listed
      with the -d option. The date is specified as:
		       month/day/year hour:minute AM|PM
      The string specifying the date should be enclosed in quotation marks
      (") to ensure the date specification string is interpreted as a single
      argument including the embedded spaces.

      Invoked with no options, mxexec displays a list of the Systems Insight
      Manager user's jobs which have not completed.  The capability to
      display several levels of detail for a specific job is supported.
      Systems Insight Manager users may see details for any job regardless
      of whether they ran them or not. When viewing the job details, the
      Systems Insight Manager user may specify the option to suppress job
      headers and send the job output to stdout or stderr.

    Tool Execution Authorization
      Systems Insight Manager verifies that the user that invokes the mxexec
      command is authorized to execute the tool on the specified Systems
      Insight managed node(s). If the user is not authorized to execute the
      tool on all nodes specified, a message indicating this is displayed to
      stderr, logged to the Systems Insight Manager log file and the job is
      aborted.	The default location of the Systems Insight Manager log file
      is /var/opt/mx/logs/mx.log.

      A user is authorized to run a tool on a node if all the following are
      true:

	   the user is a valid Systems Insight Manager user (see
	   mxuser(1M));

	   the tool has been assigned to a Systems Insight Manager toolbox
	   (see mxtool(1M));

	   the user has been authorized (see mxauth(1M)) to have that
	   toolbox on that node.

      Tool authorization is 'all or none', meaning tool execution will fail
      if the user is not authorized to run the tool on all nodes in the
      target list.

    Default Target Node Influence on Tool
      The value of the default targets tool attribute defTargets (see
      mxtool(4)) allows different tool execution behavior if no targets are
      specified on the command line.  The following table describes behavior
      of tool execution for all values of defTargets if no target list is
      specified on the command line:

	   ALL		  use all of the user's authorized nodes as the
			  target list

	   CMS		  the Systems Insight Manager Central Management
			  Server (CMS) is used as the only node in the
			  target list

	   [empty]	  error.  The user must specify a target list

	   user-specified the target list specified in the tool definition
			  file is used as the target list

      The value of defTargets is ignored if a target list is specified on
      the command line.	 Authorization for each target node will be verified
      before the tool is executed.

    Target Execution Environment
      When a job is executing on a node, its environment will contain
      information gathered on the CMS and sent to the Systems Insight
      Manager agent on the target nodes.  These variables will be placed in
      the environment in which the tool command runs:

	   MX_USER
		This contains the UNIX login name of the user running the
		job.

	   MX_JOBID
		This is the job ID assigned to the job.

	   MX_TOOL
		This is the Systems Insight Manager toolname (may not be the
		same as the tool script name).

	   MX_TARGETS
		This contains a space-separated list of target nodes for
		this job.  The target nodes will be sorted in lexicographic
		order.

	   MX_CMS
		This is the Systems Insight Manager CMS hostname.

	   MX_REPOSITORY
		This is the hostname of the system containing the SQL Server
		Service Repository; same as $MX_CMS.

	   DISPLAY
		This is set to the value copied from the user's environment
		so that tools that use an X Window GUI are able to contact
		the correct X server.

	   HOME This is set to the home directory of the execution user
		specified in the tool definition.  The home directory is
		looked up on the target node.

	   SHELL
		This is set to /usr/bin/sh.

      These variables are set to the empty string:

	   CLASSPATH

	   ENV

	   JAVA_HOME

	   SHLIB_PATH

      In addition to the above, the following environment variables are
      inherited from the init(1m) process that spawns the agent.  They are
      default values and are typically not very useful.

	   INIT_STATE

	   PATH

      Finally, a number of environment variables are set by the POSIX shell
      (/usr/bin/sh) automatically.  See the sh-posix(1) man page for more
      information on automatically set environment variables.

    Tool Execution States
      For every target node, a job goes through a set of states that track
      the progress of the job on each node.  The states are: Pending,
      Copying files, Running tool, and Complete.

	   Pending	  Nothing regarding the specific target has started.
			  This state is used when there are a very large
			  number of target nodes and the CMS Distributed
			  Task Facility (DTF) is only able to run a job in
			  parallel on a smaller number of nodes.  Those
			  targets that are waiting to start are in the
			  Pending state.

	   Copying files  If there are any files to copy, the job then
			  enters this state wherein the contents of the
			  files are transmitted to the target and the target
			  writes the files and sets their ownership and
			  permissions.	The maximum number of files that may
			  be copied is 16.

	   Running tool	  If there is a command line to execute (the command
			  line is optional for a tool), the job begins the
			  Running tool state.  During this state, the target
			  forks a process to run the command and establishes
			  a clean process environment (see Target Execution
			  Environment above).	It then exec's (see
			  execl(1)) the POSIX shell with the command line as
			  the argument (see sh-posix(1)). The command line
			  is run from the HOME directory (as defined by
			  getpwuid(3C) on the target) of the execution user
			  specified by the "user" keyword in the tool
			  definition.  If the user does not exist on the
			  target, / is used instead.  The stdin for the
			  process is set to /dev/null. If the tool is a
			  launch-only tool, as soon as the shell has
			  successfully exec'ed the command line, the agent
			  on the target moves to the next state.  If not,
			  the target agent waits while the command executes
			  and after it exits, it gathers up the stdout,
			  stderr, and exit code of the process to be
			  returned to the DTF.	After the tool has completed
			  its execution of the command, any results are
			  returned to the DTF and the connection is closed.

	   Complete	  The job has completed and any results are made
			  available to the user interface by the DTF and is
			  also logged to the Systems Insight Manager log
			  file.

    Task Termination
      Tasks may be terminated after they have been started via mxexec if
      they have not yet reached the Running tool state.	 On target nodes in
      the Running tool state, termination does nothing - execution continues
      unaffected.  On target nodes in the Complete state, termination also
      does nothing as the job has completed.  Terminating a job is done via
      a separate execution of mxexec with the -c option (and optionally the
      -k option).  The job_ID of the job to be cancelled must be specified
      using the -i option.

      A job that is cancelled performs no further processing on the target
      node.  If a file is being copied at the time of the cancellation, the
      copy is stopped and any contents already copied are removed.  If a
      previous file existed before, it is restored.  Files already copied to
      the target are left as is - they are not returned to the state prior
      to job execution.

      The effect of killing a job is that, in addition to the cancellation
      steps described above, the shell process invoked to run the command
      line associated with the tool is killed.	This is done by sending the
      SIGKILL signal (see kill(1)) to the process group.  Killing a running
      process can be a dangerous operation.  It is possible (although
      unlikely) that killing a running process might leave the system in an
      inconsistent state.  Caution must be taken in killing a job.

    Limits On Simultaneous Task Execution
      The Systems Insight Manager has three separate limits that affect the
      maximum number of simultaneous job executions.

      The DTF has a limit of ten (10) simultaneous job executions.  That is,
      if ten jobs are already executing and another is requested (either via
      mxexec or the portal), the new job will pause until one of the
      currently executing jobs complete.  If the currently executing jobs
      all take a long time to complete (they are doing lengthy tasks such as
      installing a large software package using SD or creating a recovery
      image using I/UX), the new job could pause a long time.  This limit is
      global to the DTF and is not a per user limit.

      The DTF also has a limit of sixteen (16) simultaneous agent
      connections.  This means that at any point in time, no more than
      sixteen agents are executing jobs sent out by the DTF.  Therefore, if
      a job is started that references more than sixteen target nodes, only
      the first sixteen will be immediately started.  The remaining targets
      will wait in the Pending state until one of the running targets finish
      execution.  This limit is global to the DTF and is not a per job or
      per user limit.  Therefore if a job is currently executing on twelve
      targets and a new job is requested that references six targets, only
      the first four targets will start immediately and the others will wait
      in the Pending state until earlier targets finish execution.

      The agent has a limit of four (4) simultaneous job executions.  This
      limits the number of simultaneous commands that can be executed by the
      agent to four.  If four jobs are already executing on a given target
      and a new job is started that references that target, when the DTF
      contacts the agent on that target to run the new job, it will get an
      agent busy exception.  The DTF will continue contacting any other
      referenced targets until the only ones remaining are those that are
      busy.  It then periodically contacts the busy agent until one of the
      executing jobs completes and the agent accepts the new job.

    Options
      mxexec recognizes the following options:

	   -t toolname	  Specifies the name of the Systems Insight Manager
			  tool to execute.  The toolname may contain
			  embedded spaces or other characters interpreted by
			  the shell, and therefore may need to be enclosed
			  in quotes.

	   -A argvalue	[ argvalue...]
			  Specifies the arguments required for the intended
			  tool execution.  The values are matched to the
			  arguments by order: first specified to first
			  argument, second specified to second argument, and
			  so on.  Some argument values may contain embedded
			  spaces or other characters interpreted by the
			  shell, and therefore may need to be enclosed in
			  quotes.  Argument values are separated by white
			  space.  When specifying argument values, the user
			  must provide any necessary white space.  When
			  building the command line for an executable tool,
			  Systems Insight Manager does not add any
			  additional white space to that defined in the tool
			  definition or in the argument value.	For optional
			  arguments for which the user wishes not to specify
			  a value, specify "" to indicate a place holder.
			  Note for security reasons Systems Insight Manager
			  prohibits the following special characters from
			  being entered as part of an argvalue: grave
			  accents ('`'), semi-colon (';'), ampersand ('&'),
			  bar ('|'), left parenthesis ('('), hash mark
			  ('#'), greater than sign ('>'), less than sign
			  ('<'), and the new line character.

	   -h		  Indicates to suppress the job information headers
			  and send the job output directly to stdout or
			  stderr as appropriate. Exception information is
			  also sent to stderr.

	   -O filename	  Indicates all the stdout and stderr produced by
			  the execution of the Systems Insight Manager tool
			  is to be saved in the file indicated by filename.
			  The file pathname may be either absolute or
			  relative to the current directory. If the file
			  already exists, it will be replaced.	If it does
			  not exist, it will be created.  If the output file
			  cannot be created in the given path, Systems
			  Insight Manager will attempt to write the file to
			  the /var/tmp directory.  If that fails, the output
			  will be sent to stdout.

	   -o directory	  Indicates all the stdout and stderr produced by
			  the execution of the Systems Insight Manager tool
			  is to be saved, one results file per target node,
			  in the location indicated by directory. The name
			  of each results file in the directory is of the
			  form: "nodename.job_ID".

	   -n target [ target...]
			  Specifies the names of Systems Insight managed
			  nodes and/or node groups on which to execute the
			  tool.	 This collection of nodes and/or node groups
			  is known as the target list.	The targets are
			  space separated.  The node groups are identified
			  by the "g:" prefix.

	   -q queryname	  Specifies the name of an existing Systems Insight
			  Manager query on which to execute the tool.

	   -i task_name [ task_name...]
			  Specifies the existing tasks on which to perform a
			  specified operation.

	   -j job ID [ job ID...]
			  Specifies the currently executing jobd on which to
			  perform a specified operation.

	   -d date	  Specifies that only jobs that completed after a
			  specific date be listed.  The date is specified
			  as:
				 month/day/year hour:minute AM|PM
			  The string specifying the date should be enclosed
			  in quotation marks (") to ensure the date
			  specification string is interpreted as a single
			  argument including the embedded spaces.

	   -c		  Cancels a job.

	   -k		  Kills any still running commands associated with a
			  job.

	   -l d		  Specifies that detailed information, including
			  stdout, stderr, and completion status per target,
			  for the specified job is to be displayed.  It is
			  an error to not specify a job ID with this option.
			  Only one job ID may be specified with this option.
			  Only one -l option may be specified.

	   -l n		  List job IDs only.  The -l n option is the default
			  for listing; it behaves the same as if no options
			  are specified.  Normally -l n is not specified
			  with any job_ID values and lists all jobs in that
			  case.	 Otherwise it just repeats the job ID values
			  specified on the command line if and only if they
			  currently exist.  Only one -l option may be
			  specified.

	   -l t		  List jobs in long format, giving task name, job
			  ID, Systems Insight Manager user, Systems Insight
			  Manager toolname, and state for each job ID
			  specified, or for all jobs if no job IDs are
			  specified.  Only one -l option may be specified.


EXTERNAL INFLUENCES ON TARGET EXECUTION ENVIRONMENT

      The language setting of the command shell in which you execute this
      command will be used as the preferred language that you want the
      command line tool to execute with on the target node(s).

      For Windows, the current Code Page setting of the Command Prompt
      window will be used to determine the preferred language.	For example,
      if the "chcp" command returns "932" the language is japanese.  The
      "chcp" command can be used to change the Code Page setting if the
      operating system has the language installed and is configured to allow
      its use.

      For Linux and HP-UX, the LANG environment variable describes the
      locale that will be used to determine the preferred language.  Valid
      settings for the LANG variable can be listed with the "locale -a"
      command.	However, in order to view the output, the terminal window
      running the command shell where you list the output of this command
      must support the language and encoding defined by the LANG variable.

      If the operating system on the target node does not support the
      language setting or encoding selected by the CMS, the command shell on
      the target node will use the default language and encoding for that
      target's operating system.

      (see lang (5)) (see environ (5)) (see local (1))


RETURN VALUE

      mxexec returns one of the following values:

	     0		  Successful completion.
	     1		  Command line syntax error.
	     2		  Error in a file operation.
	     3		  Nonexistent tool error.
	     6		  Nonexistent user error.
	     7		  Nonexistent node error.
	     8		  Nonexistent node group error.
	     9		  Nonexistent job ID or task name error.
	    21		  Invalid name.
	    27		  Invalid operation.
	    28		  Invalid tool.
	    29		  Invalid runnable tool.
	    50		  Unauthorized user.
	    51		  Unauthorized or disabled toolbox
	    52		  Unauthorized node.
	   102		  Systems Insight Manager Repository error.
	   222		  CMS is not initialized.
	   245		  Unable to connect to the job manager.
	   249		  Unable to connect to the session manager.
	   250		  Remote exception.
	   254		  Systems Insight Manager Properties file error.


EXAMPLES

      Assume that a user wishes to check disk space on a Systems Insight
      Manager database node group, "dbgroup".  This node group is comprised
      of the nodes "db1", "db2", and "db3". This simple tool accepts no
      arguments.

	   mxexec -t "bdf" -n g:dbgroup

      Output from this command might have the form:

	   Running tool bdf with job id 143
	   Job ID	: 4
	   Tool Name	: bdf
	   Job State	: Some Failures
	   User Name	: root
	   Start Time	: Wednesday, March 15, 2000 3:18:46 PM MST
	   End Time	: Wednesday, March 15, 2000 3:18:47 PM MST
	   Elapsed Time : 500 milliseconds
	   Node		: db1.myco.com
	   Status	: Complete
	   Exit Code	: 0
	   STDOUT	:
	   Filesystem	       kbytes	 used	avail %used Mounted on
	   /dev/vg00/lvol1     119637	18192	89481	17% /stand
	   /dev/vg00/lvol3	86016	29545	53251	36% /
	   /dev/vg00/lvol4    1048576  347477  658305	35% /home
	   /dev/vg00/lvol5     786432  604051  171001	78% /opt
	   /dev/vg00/lvol7     524288	76726  419856	15% /var
	   /dev/vg00/lvol8     339968  291563	45670	86% /usr
	   /dev/vg00/lvol6     131072	 2507  120594	 2% /tmp
	   Node		: db3.myco.com
	   Status	: Failed
	   Exit Code	: 0
	   EXCEPTION	: Exec failure - Not enough memory
	   Node		: db2.myco.com
	   Status	: Complete
	   Exit Code	: 0
	   STDOUT	:
	   Filesystem	       kbytes	 used	avail %used Mounted on
	   /dev/vg00/lvol3	83733	18455	56904	24% /
	   /dev/vg00/lvol1	47829	 8974	34072	21% /stand
	   /dev/vg00/lvol8     480341  109209  323097	25% /var
	   /dev/vg00/lvol7     466709  329650	90388	78% /usr
	   /dev/vg00/lvol4	30597	12523	15014	45% /tmp
	   /dev/vg00/lvol6     652619  505087	82270	86% /opt
	   /dev/vg00/lvol5	19861	   17	17857	 0% /home

      A user can get a listing of all tasks by using:

	   mxexec -lt

      The output might look like the following:

	   TASKID  USER	   TOOL NAME	     STATE
	   839	   tedr	   Process Status    Complete
	   123	   peterk  Install PHCO92874 Running

      To view more detail for job "123", on a node-by-node basis, a user
      could use:

	   mxexec -ld -j 123

      The output might look like the following:

	   Task Name	: defRunNowTaskId_10
	   Job ID	: 4
	   Tool Name	: Install Software
	   Job State	: Complete
	   User Name	: root
	   Start Time	: Wednesday, March 15, 2000 3:18:46 PM MST
	   End Time	: Wednesday, March 15, 2000 3:18:47 PM MST
	   Elapsed Time : 12 minutes 17 seconds 261 milliseconds
	   Node		: machine2.myco.com
	   Status	: Complete

	   Exit Code	: 1
	   STDOUT	:
	   =======  09/15/99 16:19:56 MDT  BEGIN swinstall SESSION
		    (non-interactive)
		  * Session started for user "bozo@machine2.myco.com".
		  * Beginning Selection
		  * Target connection failed for
		    "depotsys.myco.com:/patches/PHCO_98765".
		  * Selection had errors.
	   =======  09/15/99 16:19:56 MDT  END swinstall SESSION (non-
	   interactive)
	   STDERR   :
	   ERROR:   More information may be found in the daemon logfile on
		    this target (default location is
		    machine2.myco.com:/var/adm/sw/swagentd.log).
	   Node	    : machine3.myco.com
	   Status   : Pending

      Note that even though the command executed on "machine2.myco.com"
      failed (exit code of 1), mxexec considers it complete because the
      command executed without any errors associated with mxexec or the
      agent on "machine2.myco.com".  There is no reliable way to determine
      if a failure has occurred based solely upon the return value of the
      command.


LIMITATIONS

      This command may only be run on the CMS.


AUTHOR

      mxexec was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

      mxtool(1M), mxtool(4), sh-posix(1).


SEE ALSO for Linux

      mxtool(8), mxtool(4), sh-posix(1).


      * Note: Care must be taken when specifying passwords on the command-
      line. This makes them available in the command history, in the process
      list while executing, and in the audit log if executed as part of a
      task. Be sure to clear your command history, or use alternate methods
      for specifying passwords, e.g. prompt, input file.