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.