NAME
mxtask - list, execute, remove, create tasks or change task ownership
in Systems Insight Manager
SYNOPSIS
mxtask
mxtask -lt
mxtask -ld taskname
mxtask -lf taskname [-b encoding]
mxtask -r taskname
mxtask -e taskname
mxtask -o taskname taskowner
mxtask -c taskname -q queryname -t toolname -w schedule [ -A toolparms
| -f toolparmsfile ] [ -o taskowner ] [ -i timefiltername ]
mxtask -cf taskxmlfile
mxtask -h
DESCRIPTION
The mxtask command allows a Systems Insight Manager user to list all
tasks, list details for a particular task, list task parameters in xml
format, execute a task, remove a task, change ownership for a
particular task, create a task from the command line, or create a task
from an external xml file.
The first and second form of this command (-lt) provides a tabular
listing showing the major attributes of all Systems Insight Manager
tasks currently registered in the repository. Information shown will
include task name, associated query name, associated tool name and
task type with associated schedule data.
The third form of this command (-ld) allows the user to list the
details for a specified task. Information listed will include task
name, tool name, query name, task owner, last time task was run, next
time task will run, last time task information was modified, type of
task, and any possible tool user parameters (in xml format) that may
be associated with the specified tool.
The fourth form of this command (-lf) allows the user to list the
specified task in task specific xml format. Output from this command
writes to stdout, and may be redirected (via '>') to an external file.
The file can then be modified and then used as the xml input file when
creating a new task via the (-cf) command. See the mxtask(4) man page
for a detailed description of the task specific xml format.
Optionally, the user may specify a character encoding for 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
The fifth form of this command (-r) allows the user to remove the
specified task. The task will be removed immediately. The user must
specify the name of an existing task to be removed. The user must be
authorized to remove the task. (see mxauth(1M))
The sixth form of this command (-e) allows the user to execute (run)
the specified task. The task will execute immediately. The user must
specify the name of an existing task to execute. The user must be
authorized to execute the task against the managed systems that the
associated query is targeted for. (see mxauth(1M))
The seventh form of this command (-o) allows the user to change
ownership for the specified task. The user must specify the name of an
existing task and the desired new owner. The user must be authorized
to change task ownership. (see mxauth(1M))
The eighth form of this command (-c) allows the user to create a new
task. The information regarding the new task is provided directly on
the command line. To create a new task, the user must be a full rights
user.
The ninth form of this command (-cf) allows the user to create a new
task. The information regarding the new task is provided by an
external task specific XML definition file. To create a new task, the
user must be a full rights user. See the mxtask(4) man page for a
detailed description of the task specific xml format.
Options
mxtask recognizes the following options:
-l t Displays a tabular listing of all registered
Systems Insight Manager tasks along with
associated attributes.
-l d taskname Displays a detailed attribute listing of a single
specified Systems Insight Manager task.
-l f taskname Displays an xml file-formatted listing of a
specified Systems Insight Manager task (this
output may be redirected to a file and later used
as input to the -f option when creating a new
task).
-r taskname Indicates that a specified Systems Insight Manager
task is to be removed immediately.
-e taskname Indicates that a specified Systems Insight Manager
task is to be executed (run) immediately.
-o taskname taskowner
Indicates that a specified Systems Insight Manager
task is to be assigned a specified new owner.
-c taskname Indicates that a new Systems Insight Manager task
is to be created. All required task configuration
information must be specified directly on the
command line and follow this option. Additional
required options include the following: -q, -t,
-w, (-A | -f)
-cf taskxmlfile
Indicates that a new Systems Insight Manager task
is to be created. All required task configuration
information must be specified via an external file
containing task specific data in predefined xml
format. See the mxtask(4) man page for a detailed
description of the task specific xml format.
-h Displays extended help for mxtask.
-q queryname An option to specify name of an existing Systems
Insight Manager query.
-w scheduleinfo
An option to specify task schedule data.
'scheduleinfo' is a parameterized string which
defines the schedule data. Details regarding the
format for this string is are given in a section
below.
-t toolname An option to specify name of an existing Systems
Insight Manager tool. Note that using the (-t)
option to specify a tool when creating a task from
the command line, one of the following two options
listed below are also required if the specified
tool does require additional user parameters. If
the specified tool does not require additional
user parameters, then neither of the following two
options (-A | -f) are required.
-A toolparms One of two available options that are required
with the create task (-c) command to specify the
parameter data for a specified tool that requires
user parameters (the other alternate option for
specifying user parameters is the (-f) option in
which an external file contains the user parameter
data in xml format - see below). The tool
parameter string that's provided on the command
line for the (-A) option must be enclosed in
double quotes. Also, if the tool parameter data
includes xml data, with embedded double quote
characters, each double quote character must be
preceded by the backslash escape character.
-f toolparmsfile
One of two available options that are required
with the create task (-c) command to specify the
parameter data for a specified tool that requires
user parameters (the other alternate option for
specifying user parameters is the (-A) option in
which the parameters are provided directly on the
command line. - see above). The tool parameters
for the (-f) option are provided in a specified
external file that contains the tool parameters in
proper xml format.
-o taskowner An optional option that may be used with the
create task (-c) command to specify a task owner
for the new task that will be created. If no
owner is specified, the current logged in user
will be assigned as the task owner.
-i timefiltername
An optional option that may be used with the
create task (-c) command to specify that a an
already existing time filter be associated with
the new task that will be created. If no time
filter name is specified, then the new task will
be created with no associated time filter.
-b encoding Specifies the character encoding of an XML file
when used in conjunction with the -lf option.
The 'schedule' parameterized string format:
When creating a new task directly on the command line via the (-c)
option, the task type/schedule information is required as a
parameterized data string and is preceded by the (-w) option
character. The format for this parameterized string and valid
assignment values are described below.
The schedule parameterized string has the general format as shown
below, and must begin with the 'T' (type) character. Note that the
parameterized string must not contain any spaces and also note how the
period character is used as a parameter separator.
-w T<tasktype>.I<intervaltype>.P<periodic>.D<day|date>.M<time>
The 'T' parameter signifies the task type and is required in all
type/schedule parameterized strings. Valid <tasktype> values are
"add", "remove", "manual" or "schedule". These task type values
determine what type source triggers the task to run.
Tadd -task runs when systems or events meet the list criteria
Tremove -task runs when systems or events no longer meet the list
criteria
Tmanual -task only runs when manually invoked
Tschedule -task runs based off a periodic/day/time schedule)
The 'I' parameter signifies the Interval type and is required only
when the 'T' task type value is "schedule". Valid <intervaltype>
values are "minutes", "hours", "days", "weeks", "months", "daily" or
"runonce".
Tschedule.Iminutes - Task runs every x minutes.
Tschedule.Ihours - Task runs every x hours.
Tschedule.Iweeks - Task runs every x weeks at specified day/time.
Tschedule.Imonths - Task runs every x months at specified day/time.
Tschedule.Idaily - Task runs once a day at specified time.
Tschedule.Irunonce - Task runs once at specified date/time.
The 'P' parameter signifies the Periodic interval (how often the task
will run) and is required only when the 'T' task type value is
"schedule". Valid <periodic> values (n) are any numeric values greater
than zero.
Tschedule.Iminutes.Pn
The 'D' parameter may signify a Day or Date value and is required only
when the 'T' task type value is "schedule" and the 'I' Interval type
is either "weeks", "months" or "runonce". Valid <day|date> values are
dependant on the Interval type specified. If Interval type is "weeks",
then the valid Day values are "sunday", "monday", etc. If Interval
type is "months", then the valid Day value is a numeric value in the
range of 1-31. If Interval type is "runonce", then the valid Date
value is mm/dd/yy.
Tschedule.Iweeks.Pn.Dfriday
Tschedule.Imonths.Pn.D1
Tschedule.Irunonce.Dmm/dd/yy
The 'M' parameter signifies a Time value and is required for all valid
Interval types, except for "minutes" and "hours". This parameter
defines the time at which the task will run and is specified in 24hr
format as follows.
Tschedule.Iweeks.P2.Dfriday.M1:00
EXTERNAL INFLUENCES ON XML DATA
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.
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 contained within the task to execute with on the
target node(s). If creating a scheduled task, this language will be
saved in the scheduled task and used each time it is executed. The
same is true if modifying an existing task. If manually running a
scheduled task, this language will be used to override the language
stored in the task for this single execution.
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
mxtask returns one of the following values:
0 Successful completion.
1 Command line syntax error.
2 Error in a file operation or parsing a file.
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.
250 Remote exception.
EXAMPLES
This command lists all scheduled tasks in tabular format. Listing
includes task name, associated tool name, last run time and schedule
information.
mxtask
This command lists all scheduled tasks in tabular format. Listing
includes task name, associated tool name, last run time and schedule
information.
mxtask -lt
This command lists the details for a specified task. The task
specified (taskname) must already exist in the Systems Insight Manager
repository. The (-lt) command may be used to view the names of all
current tasks residing in the repository.
mxtask -ld taskname
This command lists the descriptive data for a specified task in task
specific xml format. Output from this command may be used to create a
new task requiring the same tool with similar tool (user) parameters.
The output could be redirected to an external file, which in turn
could then be manually edited and then used as an input file to create
a new task with the (-cf) command. See the mxtask(4) man page for a
detailed description of the task specific xml format. The (-lt)
command may be used to view the names of all current tasks residing in
the repository.
mxtask -lf taskname
This command removes the specified task. The task specified (taskname)
must already exist in the Systems Insight Manager repository.
mxtask -r taskname
This command executes (runs) the specified task. The task specified
(taskname) must already exist in the Systems Insight Manager
repository. The (-lt) command may be used to view the names of all
current tasks residing in the repository.
mxtask -e taskname
This command changes task ownership for the specified task. The task
specified (taskname) must already exist in the Systems Insight Manager
repository. The specified task owner (newtaskowner) will have the
format of: "MachineName/User". To view the current owner of a
particular task, use the -ld option to view task details, of which the
task owner will be included in the listing. The (-lt) command may be
used to view the names of all current tasks residing in the
repository.
mxtask -o taskname taskowner
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "add". In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required. The (-lt) command may be used to view the
names of all current tasks residing in the repository.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "remove". In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "manual". In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every 30 minutes. In
this example, there are no tool (user) parameters required for the
tool being specified, thus the (-A) nor the (-f) option are not
required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every 12 hours. In this
example, there are no tool (user) parameters required for the tool
being specified, thus the (-A) nor the (-f) option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every 2 weeks on Sunday
at 2:00 AM. In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every month on the 15th
at 5:00 AM. In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every 7 days on Tuesday
at 6:00 PM. In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) nor the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run every day on Saturday at
1:00 AM. In this example, there are no tool (user) parameters
required for the tool being specified, thus the (-A) or the (-f)
option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "schedule". The task is scheduled to run once at the specfied
date (mm/dd/yy) and time (hh:mm). In this example, there are no tool
(user) parameters required for the tool being specified, thus the (-A)
or the (-f) option are not required.
mxtask -c taskname -q queryname -t
This command creates a task of specified task name with an associated
query (queryname) and tool (toolname) that already exists in the
Systems Insight Manager repository. The task type is specified as of
type "add". Tool (user) parameters are specified for this task via
the (-A) option. The tool parameter string that's provided on the
command line must be enclosed in double quotes. Also, if the tool
parameter data includes xml data with embedded double quote
characters, each double quote character must be preceded by the
backslash escape character.
mxtask -c taskname -q queryname -t
This command creates a new scheduled task of specified task name with
an associated query (queryname) and tool (toolname) that already
exists in the Systems Insight Manager repository. The task type is
specified as of type "add". Tool parameters are specified for this
task via the (-f) option. 'filename' specifies the path and name of a
file that contains the tool (user) parameter data for the specified
tool. The tool parameter data contained in this file must be of the
exact same xml format as stored in the Systems Insight Manager
repository.
mxtask -c taskname -q queryname -t
This command creates a new scheduled task of specified task name with
an associated query (queryname) and tool (toolname) that already
exists in the Systems Insight Manager repository. The task type is
specified as of type "manual". The Task Owner is also specified on the
command line via the -o option. In this example, there are no tool
(user) parameters required for the tool being specified, thus the (-A)
nor the (-f) option are not required.
mxtask -c taskname -q queryname -t
This command creates a new scheduled task of specified task name with
an associated query (queryname) and tool (toolname) that already
exists in the Systems Insight Manager repository. The task type is
specified as of type "add". Tool parameters are specified for this
task via the (-f) option. 'filename' specifies the path and name of a
file that contains the tool (user) parameter data for the specified
tool. The tool parameter data contained in this file must be of the
exact same xml format as stored in the Systems Insight Manager
repository. The Task Owner is also specified on the command line via
the -o option along with specifying the task be associated with a
standard time filter called Business Hours. Note that command line
option arguments that contain spaces, must be enclosed in double
quotes.
mxtask -c taskname -q queryname -t
This command creates a new task based off the XML contents of a
specified external file. All required task configuration information
is specified in a predefined task specific XML format. See the
mxtask(4) man page for a detailed description of the task specific XML
format. The general format is shown below.
mxtask -cf taskxmlfile
General XML format for taskxmlfile:
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task name" type="add|remove|manual|schedule" owner="taskowner" runmode="runnow|runatstartup">
<toolname>tool name</toolname>
<queryname>query name</queryname>
<scheduleinfo interval="x" periodic="x" time="x" day="x" date="x"/>
<timefilter />
<toolparams />
</task>
</task-list>
LIMITATIONS
This command may only be run on the CMS.
AUTHOR
mxtask was developed by the Hewlett-Packard Company.
SEE ALSO for HP-UX
mxauth(1M) mxtask(4).
SEE ALSO for Linux
mxauth(8) mxtask(4).
* 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.