Automatic Update, Remote Execution and File Transfer

iTivity™ Deployment Guide

4. Automatic Update, Remote Execution and File Transfer

Table of Contents

4.1 Introduction and Overview

4.2 iAgent Selection

4.3 Automatic File Transfer

4.4 Automatic Remote Program Execution

4.5 Automatic Update

This chapter provides information and recommendations for automatic interactions with the iTivity iAgents connected to the iServer. Starting with the iTivity 7.0 release, the iServer can be configured to a) deploy files and directories to selected iAgents, b) launch programs remotely on the iAgents or c) use the first two items to automatically update the iAgent software.

4.1 Introduction and Overview

The iTivity iServer can be configured to send a file or an entire directory to a selected group of connected iAgents. It also supports remotely executing a command or program on a selected group of iAgents. You can combine these features to implement the automatic update of the iAgent software fro m the iServer.

The iServer uses a central XML file to configure all automation tasks, such as file transfer and remote program execution. In that XML file, you can configure one or more tasks to be performed on one or more iAgents. The selection of the iAgents involves specifying the name or a regular expression match against the iAgent computer name, hostname, operating system or iTivity support domain. The automation XML file supports many features. When you have finished configuring the XML file, you can invoke the iServer automation with a shortcut or from the command line. The results of the automation sequence are recorded in the iServer activity log as well as in the new auto_data directory.

When you launch or invoke automation, the iServer reads the central XML file and assigns one or more packages to execute against the selected (matching) iAgents for each of those packages. The iServer automation subsystem will interact with multiple iAgents simultaneously by using a thread pool. At a minimum, the iServer can start package processing, with five iAgents simultaneously. For every 20 connected iAgents after the first 100, the iServer will add one more simultaneous package handling thread (to the thread pool). With 200 connected iAgents, you would expect up to 10 simultaneous file transfers and/or remote program executions. With 2000 connected iAgents, you would expect up to 100 simultaneous interactions with the selected iAgents.

Since iAgents are not accessible via the iManager during automation interaction with the iServer, Tridia recommends that you invoke automation outside of business hours when the impact to iTivity users will be at a minimum. If an iTivity iManager user is already accessing an iAgent when the automation package is ready, then the interaction is delayed temporarily. The iServer will wait at least 15 minutes before the next retry attempt. It will attempt the interaction 20 times before giving up on that iAgent. So, if an iManager user is connected to a selected iAgent for more than five hours when you launch iServer automation, then that iAgent will not receive the specified package (file transfer and/or remote program launch).

iServer Version Requirements

. iServer Version 7.0.00 or Later

iAgent Version Requirements

. iAgent Version 7.0.00 or Later

XML Configuration File Layout

The iServer uses the XML file:

iTivity/iServer/itivity_data/automate.conf

under the iServer installation directory, for all configuration settings used for automation tasks. Each task has a separate packageConfig and there can be one or more packageConfig sections in the same automate.conf XML file.

XML file layout example:


<automationConfig>

    <packageConfig>

        <packageName>my_package_name_goes_here</packageName>

        <dryRun>YES</dryRun>

        <rules>

            ...
            rules for matching the selected iAgents
            ...

        </rules>

        <deployDir>

            ...
            settings for sending file or directory transfers to iAgents
            ...

        </deployDir>

        <remoteExec>

            ...
            settings for remotely executing a command on the iAgents
            ...

        </remoteExec>

    </packageConfig>

</automationConfig>

automationConfig XML Element

The automationConfig element marks the beginning and end of the iServer automation configuration. Generally, this element should start and finish the iServer automation configuration file.

packageConfig XML Element

The packageConfig element marks the beginning and end of the automation task, aka. the automation package. Each packageConfig element must contain a packageName element that uniquely identifies the task or package for that iServer.

dryRun XML Element

The dryRun element controls whether the task or package is simply scheduled and reported or whether the task is actually implemented. If dryRun is "YES" the the package is scheduled and reported in the log files, but it is not implemented against the selected iAgents. If dryRun is "NO" the the package is scheduled, implemented and reported in the log files against the selected iAgents.

rules XML Element

Every package should have a rules element in order to select which iAgent operating system receives the package. Since most packages are operating system specific, it is generally important to limit the targeted iAgents with a least an operating system match.

deployDir XML Element

The deployDir element describes a file or directory that should be transferred to the selected iAgents. Every package should have either a deployDir element, a remoteExec element or both.

remoteExec XML Element

The remoteExec element describes a program or command that should be launched on the selected iAgents. Every package should have either a remoteExec element, a deployDir element or both.

4.2 iAgent Selection

iAgents are selected for automation tasks by specifying one or more filters in the rules XML element. When multiple rules are specified, they must all match for a particular iAgent to be selected for the task. Said another way, the rules combine with "and" logic.

In the example below, the selected iAgents must match both the "Linux" operating system and have an iAgent version later than (not including) version 6.0.14.

XML file rules example:


<automationConfig>

    <packageConfig>

        <packageName>my_package_name_goes_here</packageName>

        <dryRun>YES</dryRun>

        <rules>

            <matchComputer></matchComputer>

            <matchHostname></matchHostname>

            <matchOSName>Linux</matchOSName>

            <matchSupportDomain></matchSupportDomain>

            <agentVersionBefore></agentVersionBefore>

            <agentVersionEqual></agentVersionEqual>

            <agentVersionAfter>6.0.14</agentVersionAfter>

            <minimumAvailDisk>18</minimumAvailDisk>

        </rules>

        <deployDir>

            ...
            settings for sending file or directory transfers to iAgents
            ...

        </deployDir>

        <remoteExec>

            ...
            settings for remotely executing a command on the iAgents
            ...

        </remoteExec>

    </packageConfig>

</automationConfig>

Rules XML Element Descriptions

If any rules element is missing or empty, then it automatically matches all iAgents. The agentVersionAfter element below defaults to version 6.0.14 since that release and earlier iAgents are not able to accept automation instructions from the iServer.

When performing automatic upgrade of iAgents, the agentVersionBefore element should be set to the precise version of the new release being deployed. This prevents the iServer from attempting to launch an upgrade of an iAgent that has already been upgraded. Since not all iAgents may be connected during the first automatic upgrade pass, it it often necessary to launch it again later. Additionally, some new deployments or test systems may have been upgraded manually, and should therefore be excluded.

XML Element Name	Description	Common Values
`matchComputer`	Requires that the iTivity computer name of the iAgent, as shown in the iManager, must match the string or regular expression given for this element, if any.	Depends on how you name the iAgents in iTivity.
`matchHostname`	Requires that the iTivity iAgent hostname must match the string or regular expression given for this element, if any.	Depends on how you name the iAgents on the local network.
`matchOSName`	Requires that the operating system name of the iTivity iAgent must match the string or regular expression given for this element, if any.	Windows or Linux
`matchSupportDomain`	Requires that the iTivity support domain of the iTivity iAgent must match the string or regular expression given for this element, if any.	Depends on the support domain names in use.
`agentVersionBefore`	Requires that the iTivity iAgent software version must be earlier than the release given in this element, if any. Commonly set to the version of new upgrades to prevent unnecessary or duplicate upgrade attempts to the same iAgent system.	X.Y.ZZ, Usually the upgrade target version.
`agentVersionEqual`	Requires that the iTivity iAgent software version must be equal to the version given in this element, if any.	X.Y.ZZ
`agentVersionAfter`	Requires that the iTivity iAgent software version must be later than the release given in this element, if any.	X.Y.ZZ, for example: 6.0.14
`minimumAvailDisk`	Only matches iAgents with more free disk space in megabytes than the specified amount (integer). This should include both the transfer size and any additional space needed for the upgrade or remote execution to succeed.	Megabytes disk needed for upgrade.

4.3 Automatic File Transfer

You can specify a file or an entire directory to be automatically transferred (copied) out to any iAgent that matches the package's rules filters. While this is often used to deploy a new iAgent installer during an automatic upgrade, you can use this mechanism to deploy any directory to any selected set of iAgents.

XML file deployDir example:


<automationConfig>

    <packageConfig>

        <packageName>my_package_name_goes_here</packageName>

        <dryRun>YES</dryRun>

        <rules>

            ...
            rules for matching the selected iAgents
            ...

        </rules>

        <deployDir>

            <totalSize>24</totalSize>

            <bandwidthLimit>2048</bandwidthLimit>

            <sourceDirectory>C:\Program Files (x86)\iTivity\iServer\docs
            </sourceDirectory>

            <targetDirectory>/tmp/iServer</targetDirectory>

        </deployDir>

        <remoteExec>

            ...
            settings for remotely executing a command on the iAgents
            ...

        </remoteExec>

    </packageConfig>

</automationConfig>

deployDir XML Element Descriptions

You can use the following XML elements to configure the file transfer or directory deployment to your iAgents from the iServer.

XML Element Name	Description	Common Values
`totalSize`	Allows you to specify the total size in Megabytes (MB) of the file or directory being deployed to the iAgent. If the iAgent does not have enough disk space, the transfer will be declined.	MB to transfer
`bandwidthLimit`	Specifies the maximum amount of network bandwidth in KBps (kilobytes per second) that can be used per iAgent transfer. At a minimum, the iServer can start package processing, including file transfer, to five iAgents simultaneously. For every 20 connected iAgents, the iServer will add one more simultaneous package handling thread (in the thread pool). With 200 connected iAgents, you would expect up to 10 simultaneous file transfers, each of which would use up to `bandwidthLimit` KBps of network bandwidth.	2048
`sourceDirectory`	Specifies the file or directory on the iServer that should be transferred to the iAgents selected by the rules filters of this package. The format of the `sourceDirectory` is platform specific and therefore must match the platform where the iServer is running.	Directory or file to send
`targetDirectory`	Location to store the file or directory on the iAgent system. The format of the `targetDirectory` is platform specific and therefore must match the platform where the iAgent is running. This platform is selected by the `matchOSName` rule filter as a best practice.	Destination directory

4.4 Automatic Remote Program Execution

You can use the remoteExec section of any package to specify a program that should be executed on the iAgent system after the file transfer, if any, is completed. This section shows an example remote program execution for a Windows iAgent. Since the remote program execution information is platform specific, you should always specify the matchOSName rule to match.

XML file remoteExec example:


<automationConfig>

    <packageConfig>

        <packageName>my_package_name_goes_here</packageName>

        <dryRun>YES</dryRun>

        <rules>

            ...
            rules for matching the selected iAgents
            ...

        </rules>

        <deployDir>

            ...
            settings for sending file or directory transfers to iAgents
            ...

        </deployDir>

        <remoteExec>

            <workingDirectory>C:\Windows\TEMP\</workingDirectory>

            <targetProgram>cmd.exe</targetProgram>

            <targetParameters>/C "C:\Windows\TEMP\upgrade_iTivity_iAgent.cmd"
            </targetParameters>

        </remoteExec>

    </packageConfig>

</automationConfig>

remoteExec XML Element Descriptions

The following XML elements allow you to configure which program will be launched on the selected iAgents with which parameters.

XML Element Name	Description	Common Values
`workingDirectory`	Specifies the working directory on the iAgent system where the remote program will be launched. Many filenames and paths are relative to the working directory.	`C:\Windows\TEMP\` on Windows `/tmp/` on Linux
`targetProgram`	Specifies the program or binary that should be invoked, launched or executed on the iAgent system in the current package.	`cmd.exe` on Windows `/bin/bash` on Linux
`targetParameters`	Specifies the command line parameters or options that are passed to the target program when it is launched. Generally, these parameters are used to configure the program and control how it runs on the iAgent system.	Depends on the program
`trackProgress`	Configures whether the iServer will store the standard output (aka stdout) from the remote program in a subdirectory on the iServer. Sometimes the standard output from the remote program can be very useful in either troubleshooting the remote program or for collecting the results of having run the program. This feature is more often useful on Linux than on Windows, however, there are some Windows console programs with interesting standard output. Unfortunately, the Windows installer, `msiexec.exe`, does not record anything useful to standard out.	YES or NO

When running the windows installer, msiexec.exe, it can be useful to specify the log file name on the command line. Then you can used a command file or powershell script to stop the iAgent, launch msiexec.exe with a logfile name and then type the log so that it is captured by standard out.

4.5 Automatic Update

You can combine a file transfer with a remote program execution to automatically upgrade the iAgent version via the iServer. The general approach is to create a script that runs on the iAgent. The script and the iAgent installer are both transferred to the iAgent first. Then the iServer remotely executes the script. The script first stops the running iAgent, then launches the installer to accomplish the upgrade. When the installer finishes, the script restarts the newly upgrade iAgent.

Example `automate.conf` for Auto-Upgrade to Windows iAgents

The following automatic upgrade example shows transferring a command script and an MSI. The MSI size plus the extra space needed to install the software is less than 24MB. Any iAgent with less that 24MB of free disk space will be excluded from the upgrade.


<automationConfig>

    <packageConfig>

        <packageName>Win32_to_Win32_iagent_upgrade_example_msi</packageName>

        <dryRun>YES</dryRun>

        <rules>

            <matchComputer></matchComputer>

            <matchHostname></matchHostname>

            <matchOSName>Windows</matchOSName>

            <matchSupportDomain></matchSupportDomain>

            <agentVersionBefore>7.1.00</agentVersionBefore>

            <agentVersionEqual></agentVersionEqual>

            <agentVersionAfter>6.0.14</agentVersionAfter>

            <minimumAvailDisk>24</minimumAvailDisk>

        </rules>

        <deployDir>

            <totalSize>24</totalSize>

            <bandwidthLimit>2048</bandwidthLimit>

            <sourceDirectory>
                C:\Program Files (x86)\iTivity\iServer\itivity_data\
                    iTivity_Unattended_iAgent_v7100.msi
            </sourceDirectory>

            <targetDirectory>C:\Windows\TEMP\</targetDirectory>

        </deployDir>

    </packageConfig>

    <packageConfig>

        <packageName>Win32_to_Win32_iagent_upgrade_example_cmd</packageName>

        <dryRun>YES</dryRun>

        <rules>

            <matchComputer></matchComputer>

            <matchHostname></matchHostname>

            <matchOSName>Windows</matchOSName>

            <matchSupportDomain></matchSupportDomain>

            <agentVersionBefore>7.1.00</agentVersionBefore>

            <agentVersionEqual></agentVersionEqual>

            <agentVersionAfter>6.0.14</agentVersionAfter>

            <minimumAvailDisk>24</minimumAvailDisk>

        </rules>

        <deployDir>

            <totalSize>24</totalSize>

            <bandwidthLimit>2048</bandwidthLimit>

            <sourceDirectory>
                C:\Program Files (x86)\iTivity\iServer\itivity_data\
                    upgrade_unattended_iagent.cmd
            </sourceDirectory>

            <targetDirectory>C:\Windows\TEMP\</targetDirectory>

        </deployDir>

        <remoteExec>

            <workingDirectory>C:\Windows\TEMP\</workingDirectory>

            <targetProgram>cmd.exe</targetProgram>

            <targetParameters>/C "C:\Windows\TEMP\upgrade_iTivity_iAgent.cmd"
            </targetParameters>

            <trackProgress>YES</trackProgress>

        </remoteExec>

    </packageConfig>

</automationConfig>

`upgrade_iTivity_iAgent.cmd` Upgrade Script

The automate.conf example shown above relies on a command script, named upgrade_iTivity_iAgent.cmd, to launch the iAgent installer on the Windows iAgent.


cd "C:\Windows\TEMP\"

REM Stop the running Unattended iAgent.

"C\Program Files (x86)\iTivity\Unattended iAgent\bin\connector_rc.exe"
   -stopHostMode -perMachine

REM Launch the MSI installer in silent mode with not user interface.

msiexec.exe /I "C:\Windows\TEMP\iTivity_Unattended_iAgent_v7100.msi"
   /qn /L*v "C:\Windows\TEMP\iTivity_Unattended_iAgent_v7100_install_log.txt"
   AUTHENTICATION="ntlm" VERIFYCERTS=0
   PUBCERTURL="http://www.tridia.com/public_keys/ad732b5c.0"
   LAUNCHAGENT=0 PROMPTNAME=0
   REGURL="http://testsite.tridia.com/brian/WBB_Cust_iAgent.reg"
   CGRP1NAME="ACME Flagship iServer" CGRP1HOSTS="iserver.us.acme.com"
   CGRP1PORTS="23800"

REM Restart the Unattended iAgent.

"C\Program Files (x86)\iTivity\Unattended iAgent\bin\connector_rc.exe"
   -startConnectIAS -perMachine

REM Display the log file output for capture.

type "C:\Windows\TEMP\iTivity_Unattended_iAgent_v7100_install_log.txt"

Table of Contents

webmaster@tridia.com
sales@tridia.com
Technical Support

4.1 Introduction and Overview

iServer Version Requirements

iAgent Version Requirements

XML Configuration File Layout

automationConfig XML Element

packageConfig XML Element

dryRun XML Element

rules XML Element

deployDir XML Element

remoteExec XML Element

4.2 iAgent Selection

Rules XML Element Descriptions

4.3 Automatic File Transfer

deployDir XML Element Descriptions

4.4 Automatic Remote Program Execution

remoteExec XML Element Descriptions

4.5 Automatic Update

Example automate.conf for Auto-Upgrade to Windows iAgents

upgrade_iTivity_iAgent.cmd Upgrade Script

Example `automate.conf` for Auto-Upgrade to Windows iAgents

`upgrade_iTivity_iAgent.cmd` Upgrade Script