Client Task Agent 8.x for Unix, Linux and Macintosh Command Lines
Article ID: 177032
Updated On:
Products
Issue/Introduction
Client Task Agent 7.x for Unix, Linux and Macintosh Command Lines
Resolution
The Client Task Agent Command Line Utility
The actual binary can be found in the ‘/opt/altiris/notification/ctagent/bin’ directory. A link to aex-cta is found in the ‘/usr/bin’ directory, which is in most Unix, Linux and Macintosh path environment variables by default. Elevated privileges (sudo, etc.) may be required to see all options.
Depending on agent configuration settings, this command can be ran by non-root users. Certain options, or commands, will require sudo authentication.
This document will cover the options to the aex-cta command itself, the commands, command-options and selectors. All are essentially command line parameters.
Getting Help
Running the command with no options returns the main help information. Any of the following commands will also return the main help information, shown below. Run 'aex-cta help <command>' to learn more information on each command.
$ aex-cta
$ aex-cta -h
$ aex-cta help
$ aex-cta --help
Usage:
aex-cta [options]
aex-cta <command> [command-options]
Command line utility for working with Altiris Client Task Agent for UNIX and Linux.
Options:
--help, -h - Display this usage information and exit immediately.
-v - Display Agent's full version and name.
--version - Display version of the application.
Commands:
defer Defer execution of a client job
flush Immediately send queued task execution status events to the server
help Display help on the specified command
info Get information about tasks
list List current tasks and their execution instances
pending Get information about pending client jobs
refresh Check task server for new tasks
register Force re-registration with task server
run Run client job for which an alert was available
ts Get information about task server the client is registered
Definition of Terms used by the Client Task Agent
Following are a few important terms and information regarding their use and availability.
Task-id: Policies and tasks that run on a client computer are assigned a task id. Task-ids are used by various commands including info, list, etc.
Instance-id: Also referred to as execution instance id. Each time a task is executed on a client, the execution is assigned an instance-id. If a task runs three times, it will have three execution instance ids.
Job-id: Jobs differ from tasks and policies in that only jobs can be deferred in the job scheduling window. Policies and tasks do not have this option. Jobs are assigned a unique job id.
Defer a job on a Client
If an end-user is notified that a job is to be executed on the client computer, the end-user can defer that job, if desired.
$ aex-cta help defer
Usage:
aex-cta defer <job-id>
aex-cta defer <job-id> --maximum
aex-cta defer <job-id> --until <until-time>
aex-cta defer <job-id> --by <by-period>
aex-cta defer <job-id> --info
Defers execution of the specified client job.
Options:
<job-id>
GUID of the client job to be deferred.
--info
It is also possible to get information about the client job without actually deferring it.
Defer options:
By default, the job is deferred by 5 minutes (if job's maximum defer time allows it). There are several ways to specify for how long the job is to be deferred:
--maximum
Use the maximum possible defer period for the job.
--until <until-time>
The exact date and time when the job execution notification is to be
displayed again. The format is: YYYY-MM-DD hh:mm:ss
For example: '2007-10-15 14:34:45'
--by <by-period>
Period of time after which the notification is to be displayed again.
The format is: hh:mm:ss
For example: '4:15:00'
The alternative format is N[dhm] where N is a positive integer and
d refers to days, h -- hours, m -- minutes.
For example, '3h' stands for 3 hours.
If the desired defer period exceeds the maximum allowed, that will be used instead.
Note: A job must be configured to allow for deferral before this command can be used. The deferral option is only available as a scheduling option for jobs – not tasks or policies.
Note: If a job is allowed to be deferred, the client will be notified via command line. On Macintosh client, the notification will be via the command line and the Altiris Notification Manager. These notifications appear as shown here:
$
+=============================================================================+
| Altiris Client Task Agent for UNIX and Linux |
+-----------------------------------------------------------------------------+
| Inventory Client Job is scheduled to run. |
| The scheduled run time is 2009-03-07 13:31:17. |
| To run the job immediately, launch: |
| sudo aex-cta run '{5C981AFD-0A07-4727-BE6C-C56337BD4858}' |
| To defer the job execution, launch: |
| sudo aex-cta defer '{5C981AFD-0A07-4727-BE6C-C56337BD4858}' |
+=============================================================================+
djmbp:bin doug$ sudo aex-cta defer '{5C981AFD-0A07-4727-BE6C-C56337BD4858}'
Password:
WARNING! The specified defer time exceeds the maximum allowed.
Using the maximum allowed: 2009-03-07 13:31:17
$
Send queued task execution status events to the Notification Server
If the client has lacked a connection to the NS for some time, it may bdesirablele to force the transmission of status events to the NS in order to view the current status of the client from an NS reporting point-of-view. The ‘flush’ command will cause this to occur. This command requires elevated privileges and must be run as root or with ‘sudo’.
$ aex-cta flush
Failed to flush the task execution status queue:
2164785193, Client has insufficient privileges in order to have the request processed
$
$ sudo aex-cta flush
Password:
$
Information for Specific Tasks
The ‘info’ command shows specific informatioregardingng a task or one of it’s executions on the client computer. There are many command-options for info, as shown by the following ‘aex-cta info help’ command.
Usage:
aex-cta info <task-id> [selector]
aex-cta info <task-id> <instance-id> [selector]
Get information about status of registered and executed tasks.
Options:
<task-id>
Task which information you are requesting for.
<instance-id>
Specific execution instance of the task.
Selectors:
--summary
Display summary information on the specified task or task instance.
This is the default selector.
--xml
Display the raw XML of the task definition.
--name
Show the name of the specified task.
--description
Show the description of the specified task.
--handler
Show the ID of the plug-in to be invoked for processing the task.
--max-run-time
Maximum time (in minutes) that the task is allowed to run.
--status
Show status of the specified task or its execution instance.
--parent-id
Show parent ID of the specified task instance.
This selector is only available if you specify an execution instance ID.
--job-id
Show job ID of the specified task instance.
This selector is only available if you specify an execution instance ID.
--is-success
Check whether execution of the instance was successful.
Program return code will inform you about the status:
0 - success, 10 - failure, 20 - not applicable (task has not completed yet).
This selector is only available if you specify an execution instance ID.
--return-code
Show return code of the specified task instance.
This selector is only available if you specify an execution instance ID.
--exec-status
Show status string of the specified task execution attempt (instance).
This selector is only available if you specify an execution instance ID.
Example of ‘aex-cta info <task-id>’:
$ aex-cta info {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08}
Property Value
------------------- --------------
Status Succeeded
Task ID {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08}
Name Custom Inventory - UNIX PS List
Description Script for custom inventory to collect running processes information
Task handler Altiris.ScriptTaskAgent
Maximum run time 00:30:00
Execution attempts:
Running 0
Pending 0
Succeeded 3
Failed 0
Unknown 0
TOTAL 3
In some cases, there are options to report information for a single execution instance of a particular task. The instance ID is found by running “aex-cta list <task id>”. This will return one row for each time the task ran, showing date/time, success or failure status, and the task instance id. The task instance id can be used as shown here to get detailed information about a single exeuction of the task.
Example of ‘aex-cta info <task-id> <instance-id>’:
$ aex-cta info {CB33458B-9925-43F3-904A-9FFC63ED6B4D} {5F6EFF2F-C0FB-436A-9219-92C1E1ACFCCD}
Property Value
------------------- --------------------------------------
Status Succeeded
Task ID {CB33458B-9925-43F3-904A-9FFC63ED6B4D}
Execution ID {5F6EFF2F-C0FB-436A-9219-92C1E1ACFCCD}
Parent ID {5F6EFF2F-C0FB-436A-9219-92C1E1ACFCCD}
Job ID {00000000-0000-0000-0000-000000000000}
Task handler Altiris.InventoryAgent
Maximum run time Infinity
Queued time 2009-03-07 14:25:40
Start time 2009-03-07 14:25:40
Completed time 2009-03-07 14:25:49
Return code 0
Status string Operation completed successfully.
$
Example of ‘aex-cta info <task-id> <instance-id> selector’:
$ aex-cta info {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08} {EFAA7F09-0254-4CD1-A057-0C42D40EB12A} --exec-status
Operation completed successfully.
$
List Available and Historical Tasks
The list command can be ran with no options or one of the following two options:
- aex-cta list --show-task-id
- aex-cta list <task-id>
$ aex-cta list
Date/time Status Task Name
------------------- --------- -------------------------------------
2009-02-05 18:05:41 Succeeded Custom Inventory - UNIX PS List
2009-02-10 10:51:36 Succeeded Collect Full Inventory Task
2009-02-19 16:53:18 Succeeded Collect Delta Hardware Inventory Task
2009-02-23 10:52:36 Succeeded Collect Delta Hardware Inventory Task
2009-02-23 18:01:12 Succeeded Collect Full Inventory Task
2009-02-24 09:45:47 Succeeded Collect Full Inventory Task
2009-03-07 12:37:07 Running Collect Full Inventory Task
2009-03-07 12:44:24 Succeeded Inventory Task 3-7-2009 12.42
2009-03-07 12:48:25 Running Inventory Task 3-7-2009 12.47
$
The task id is used by various aex-cta commands, inlcuding list, and is most easily found by running ‘aex-cta list --show-task-id’.
$ aex-cta list --show-task-id
Date/time Status Task Definition Version ID Task Name
------------------- --------- -------------------------------------- -------------------------------------
2009-01-29 12:05:38 Succeeded {813F6ACD-4F61-4C00-818B-EC61DA74DA23} Inventory Task 1-29-2009 12.04
2009-01-29 17:56:07 Succeeded {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08} Custom Inventory - UNIX PS List
2009-02-02 18:01:11 Succeeded {90EFECAF-2820-4C3E-98E5-8C3E0F4CDDBC} Collect Full Inventory Task
2009-02-03 09:32:59 Succeeded {90EFECAF-2820-4C3E-98E5-8C3E0F4CDDBC} Collect Full Inventory Task
2009-02-04 17:55:35 Succeeded {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08} Custom Inventory - UNIX PS List
2009-02-05 18:05:41 Succeeded {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08} Custom Inventory - UNIX PS List
2009-02-10 10:51:36 Succeeded {782630A2-9877-4C27-A228-C92FCE9C2E18} Collect Full Inventory Task
2009-02-19 16:53:18 Succeeded {77A2C5CA-0C65-47FB-9652-632271FDD4B4} Collect Delta Hardware Inventory Task
Note: Running ‘aex-cta list <task-id>’, each execution of the specified task and its Task Execution ID can be viewed. The task execution ID is also referred to as the ‘instance id’ and is used by the ‘aex-cta info’ command.
$ aex-cta list {C0C8A774-CEFB-445F-8C8C-948CCF0C9C08}
Date/time Status Task execution instance ID
--------- --------- --------------------------------------
2009-01-29 17:56:07 Succeeded {019B6CAF-8237-4814-87AA-F937239AD645}
2009-02-04 17:55:35 Succeeded {EFAA7F09-0254-4CD1-A057-0C42D40EB12A}
2009-02-05 18:05:41 Succeeded {71B16CD2-DF3A-4CD2-A995-4A06C2702504}
Note: Running ‘aex-cta list <task id>’ lists the “Task execution instance ID”, which is used by the ‘aex-cta info’ command.
List Pending Tasks
To view a list of tasks that are pending, run the following command. If there are no pending tasks, nothing is returned.
$ aex-cta pending
$
Other options for this command are:
aex-cta pending -short
List only job IDs.
aex-cta pending <job-id>
Display information only about the specified job.
$ aex-cta pending
Job ID: {88DB12AE-1AC6-48FA-86E6-F751C70641A1}
Job name: Inventory Client Job
Scheduled at: 2009-03-07 14:27:15
Prompt message: Inventory Client Job is scheduled to run.
Job description:
Runs through a sequence of client-side tasks
$
Note: This is only available when a job with the deferal option has been set and the client has been notified.
Refresh the Task List on the Client
Refreshing the task list is similar toupdatingg configuration on a Windows machine or refreshing policies on a Unix, Linux or Macintosh client. Nothing is returned whether the refresh succeeds or fails.
$ aex-cta refresh
$
Registering the Client Task Agent
The agent must be registered with the NS server. This happens by default but can be done manually, if needed. If the registration completes successfuly, nothing is returned. If it fails, an error is returned.
$ aex-cta register
$
$ aex-cta register
Failed to request registration with Task Server:
2182086763, Failed to register to task server
$
Running a job on a Client
This command requires the job-id, available from the job deferal notification. Only jobs that can be deferred have a job-id. Not that via such notifications, a job can be deferred and it can be ran.
$ aex-cta help run
Usage:
aex-cta run <job-id>
Allows immediate execution of a pending client job.
Options:
<job-id>
GUID of the client job to be run.
After executing this command, run ‘aex-cta list’ to view the status of the job. The following screen shot of the Altiris Client Job Alert is only valid on Macintosh clients.
Getting Task Server Information
$ aex-cta help ts
Usage:
aex-cta ts
Get information about task server that the client is currently connected to.
Options:
--name
Get name of the task server.
--tickle-port
Port used for tickle notifications.
--reg-time
Date and time when registration on the server occurred.
--last-check
Date and time when check for new tasks was last performed.
$ aex-cta ts
Task Server: NS1.mydom.local
Tickle Port: 50124
Registered: 2009-02-24 16:12:18
Last check: 2009-03-05 23:06:33
$
Altiris Agent for Macintosh GUI
In addition to all the above command line utilities, Symantec provides a System Preferences-like GUI for Macintosh clients. This GUI is installed by default with the Altiris Agent and is found in the /Applications/Utilities directory.
The main screen, shown below, has options for many of the command line utilities included in the client installation, including aex-sendbasicinv, aex-refreshpolicies, aex-swdapm, aex-cta, etc. The GUI’s main screen is shown here.
The ‘General’ pane provides for viewing basic information about the agent, the NS server the client is configured for, the client’s GUID, sending basic inventory and for refreshing policies from the Notification Server.
The ‘Client Task Agent’ pane in the Task Management section, provides general information regarding the connection status, the Task Server, allows for registering the client with the Task Server and for checking for new tasks.
Many of the options in these Client Task panes run the same commands as those found in the aex-cta utility, e.g., list, refresh, register, etc.
The ‘Client Tasks’ pane in the Task Management section shows ‘Active Tasks’. It is possible to check for new tasks on this pane as well as the main Client Task Agent pane. Generally, this pane will be empty since most tasks are not currently active. However, the ‘Show Tasks History’ button will open a new pane with the history of tasks performed on the client. Highlighting a task in this pane will show details for that task.
 |
|||
 |
|||
Many of the commands for the aex-cta command line utility have not been illustrated here in this document. Those not listed can be as helpful as those that are. For example, 'aex-cta info --xml', as well as the --summary, --is-success, --return-code, etc., provide very useful information regarding what a client has and has not ran.
Feedback
