Running the agentupdate utility

Installation considerations

• The tool does not support rollback from an installation or upgrade.
• The tool does not check the version of an existing agent against the version to be installed. If the version you specify for installation is lower than the version already installed, the lower version is installed.

Running the utility on the command line

The following examples demonstrate how you can run the utility on the command line. For utility syntax, see agentupdate utility reference.

The following command uses the –preview option. With this option, the utility connects to the target computers and prints the commands that it would run on those targets, without actually running the commands.

java -jar agentupdate.jar -preview -targets agent_deploy_config.xml -keyfile mykeyfile.txt

The next command encrypts all the cleartext passwords in the input XML file. The command does not connect to any remote computers.

java -jar agentupdate.jar -encrypt -targets agent_deploy_config.xml -keyfile mykeyfile.txt -logFile LogFile.txt

This command updates or installs the IBM Rational Build Forge agents on the target computers. The –sourceDir option indicates which directory contains the agent installers for all the targets. If you do not include this option when you run the utility, include the corresponding parameter in the XML file. If the installers are in a common directory for all the targets in the XML file, specify the SourceDirectory parameter in the <Globals> element in the XML file. However, if the source directory for any one of the targets is different, define the SourceDirectory parameter in that computer's <Target> element. For an example, see Sample 2 in Sample XML files.

java -jar agentupdate.jar -sourceDir .\resources –targets agent_deploy_config.xml -logFile LogFile.txt

Running the utility through the BuildForgeAgentUpdateUtilityProject

IBM Rational Build Forge provides the bfagentupdate.xml sample project that demonstrates how you can use the utility.

To use the sample project, import the project by using the import facility in the Management Console or by using the bfimport command. Import the project from C:\Program Files\IBM\Build Forge\samples\agentupdate\BFproject\ (Windows) or /opt/buildforge/samples/agentupdate/BFproject/ (Linux).

A project needs three steps: preview, encrypt, and run. The preview and encrypt steps are not included in the sample project.

• Preview step: The build system connects to the target computers and shows the commands that would run on each target to update or install the agent, without actually running the commands.
• Encrypt step: The build system encrypts all passwords without updating or installing agents on the target computers. This step replaces cleartext passwords in the input XML file with encrypted passwords.
• Run step: The build system connects to the target computers, identifies their operating systems, stops all running agents, checks for temporary space for the installer, copies the installer to the target computer, completes the update or installation, and then removes the installer from the temporary space.

Enable the steps according to your requirements, and then run the project.