Video Screencast Help

Client Task Agent 7.x for Unix, Linux and Macintosh

Created: 09 Mar 2009
Language Translations
dougj's picture
+9 9 Votes
Login to vote

Notification Server 7x introduces client tasks. In version 6.2 of the Agent for Unix and Macintosh, everything was essentially a policy and was managed on the client by a command line utility called aex-swdapm, or the Software Delivery Advertised Package Manager.

 

In 7.x, there are still policies for a few specific things, i.e., plug-in installation policies, the default inventory policies, etc. The Unix, Linux and Macintosh command line utility ‘aex-swdapm’ can be still be used to manage them if they are active.

 

However, client tasks are managed by a new command line utility named ‘aex-cta’, which obviously stands for Client Task Agent.

 

The Client Task Agent command line utility is, in all respects, identical for Unix, Linux and Mac clients. Additionaly, the Agent for Macintosh includes a GUI application that provides a nice Apple System Preferences-like interface to manage client tasks, among many other things. This article will discuss both the command line utility and the GUI app. The examples in this document are from a Macintosh computer.

 

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.

 

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, shown below. Policies and tasks do not have this option. Jobs are assigned a unique job id.

 

imagebrowser image

 

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 deferal before this command can be used. The deferal 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 dougj$ 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

$

 



The following image of the Altiris Notification Manager is valid only on a Macintosh client.

imagebrowser image 

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 be desireable 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 information regaring 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 refered 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 to udpating 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.

imagebrowser image

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.

imagebrowser image

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.

 

imagebrowser image

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.

 

imagebrowser image

 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. 

 

       
  imagebrowser image
 
    imagebrowser image

 

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. 

Enjoy the new Unix, Linux and Macintosh utility!