The agent update and deployment utility requires an XML file to determine the computers on which to update or install agents. This file must also specify login credentials and other items the utility needs.
The file has the following requirements:
The following example shows a single <Target> element and a <Globals> element. The <Globals> element is not useful if it is used with only a single <Target> element. The <Globals> element can be useful when you have multiple <Target> elements.
<?xml version="1.0" encoding="UTF-8"?>
<AgentDeploymentAndUpdate>
<Target id="9.184.112.152">
<Parameter Name="ConnectionType" Value="ssh"/>
<Parameter Name="UserName" Value="root"/>
<Parameter Name="Password" Value="passWord"/>
<Parameter Name="ExistingAgentPath" Value="/usr/local/bin/bfagent"/>
<Parameter Name="GZIPPath" Value="/usr/contrib/bin/"/>
</Target>
<Globals>
<Parameter Name="KeyFile" Value="..\test\keyfile.txt"/>
</Globals>
</AgentDeploymentAndUpdate>
Each <Parameter> element is valid in both <Target> and <Globals> elements. With this flexibility, if the parameters apply to all target computers, you could use <Target> elements to specify only the id attributes and place each <Parameter> element in the <Globals> element.
Specifying a parameter with Value="" is the same as not specifying the parameter.
These tables describe the file syntax.
Target attribute | Value |
---|---|
id | The name or IP address of a target computer. |
Parameter | Value |
---|---|
AgentInstallLocation | For IBM AIX, HP-UX, and Windows systems only
- there is no effect on other platforms Location to place the new agent. If not specified, the system default temporary directory is used. |
BFAgentPort | For IBM AIX and HP-UX systems only The port for the agent to use. Used when the generating response files. |
BFASolarisAdminFile | For Solaris systems only Location on the target system in which to store response files for silent installation. If not specified, the system default temporary directory is used. |
BFASolarisResponseFile | For Solaris systems only Location on the target system in which to store response files. If not specified, the system default temporary directory is used. |
ConnectionType | UNIX or Linux: SSH or RSH Windows: SSH, RSH, SMB, or CIFS (RSH is remote shell. SMB is Server Message Block. CIFS is Common Internet File System.) |
ConnectionPort | (Optional) Port number to use for the type of specified connection (with the ConnectionType parameter) if the target does not use the default port. If the target uses the default port, you do not need to specify this parameter. |
ExistingAgentPath | Required for IBM AIX, HP-UX, and Windows systems. Location of the existing agent on the target computer. The utility creates a backup of the BFAgent.conf file in the location you specify and then restores it after the installation or upgrade is complete. For other systems, the default system installation location is used. |
GZIPPath | IBM AIX, HP-UX, and Solaris systems. Directory where the agent installer can find the gzip command (which extracts the installer). |
IsSudoEnabled | Set to yes if sudo is enabled on the target systems and you intend to use it. Set SudoPassword to the correct sudo password. If it is not set, the utility attempts to use Password for the sudo login. |
KeyFile | File that is on the computer where you run the utility that stores the keys used for encryption and decryption of passwords. |
LocalTempLocation | For IBM AIX, HP-UX, and Windows only. Location on the target system in which to store response files. If not specified, the system default temporary directory is used. For Solaris systems, use BFASolarisResponseFile or BFASolarisAdminFile. |
ManagedScriptsDir | Set to the directory where the utility runs. This directory is on the computer where you run the agentupdate utility. |
SourceDirectory | Directory that stores the installers (in the .exe, .rpm, and .gz forms) for the target computers. This directory is on the computer where you run the agentupdate utility. |
StartCommand | (Optional) The customized command you have for
starting Rational Build Forge agents on the target computer. Ensure the command is included in the PATH/path variable or provide the full path in the XML file. |
StopCommand | (Optional) The customized command you have for
stopping Rational Build Forge agents on the target computer. Ensure the command is included in the PATH/path variable or provide the full path in the XML file. |
SudoPassword | Password to use for sudo. See IsSudoEnabled. |
Password | The password to use for UserName when
logging on to the target computer. Important: You initially
define the Password parameter in cleartext
in the XML file. Encrypt the password using the –encrypt command-line
option as demonstrated in Running the agentupdate utility.
|
TemporaryLocation | Location on the target computer in which to store the installer before you run the utility. |
UseManagedScripts | Set to yes or no. If set to yes, the utility attempts to find StartCommand and StopCommand in the ManagedScriptsDir directory. |
UserName | The user name to use when logging on to the target computer. |
These samples demonstrate how you can use the XML files.
This sample has only one target. The target IP address is 9.164.259.143. The <Target> element does not include the optional parameters SourceDirectory or TemporaryLocation. The <Globals> element, however, has a SourceDirectory parameter. The utility uses that parameter's value for the target.
<?xml version="1.0" encoding="UTF-8"?>
<AgentDeploymentAndUpdate>
<Globals>
<Parameter Name="SourceDirectory" Value="..\test"/>
<Parameter Name="KeyFile" Value="..\test\keyfile.txt"/>
</Globals>
<Target id="9.164.259.143">
<Parameter Name="ConnectionType" Value="ssh"/>
<Parameter Name="UserName" Value="root"/>
<Parameter Name="Password" Value="toor"/>
<Parameter Name="ExistingAgentPath" Value="/usr/local/bin/bfagent"/>
<Parameter Name="AgentInstallLocation" Value="/usr/local/bin/bfagent"/>
</Target>
</AgentDeploymentAndUpdate>
This sample has four targets. However, none of the targets requires parameters specific to it. Therefore all parameters are specified in the <Globals> section, including UserName, Password, and ConnectionType.
<?xml version="1.0" encoding="UTF-8"?>
<AgentDeploymentAndUpdate>
<Globals>
<Parameter Name="SourceDirectory" Value="..\test"/>
<Parameter Name="ConnectionType" Value="ssh"/>
<Parameter Name="UserName" Value="root"/>
<Parameter Name="Password" Value="toor"/>
<Parameter Name="TemporaryLocation" Value="/tmp"/>
<Parameter Name="ExistingAgentPath" Value="/usr/local/bin/bfagent"/>
<Parameter Name="AgentInstallLocation" Value="/usr/local/bin/bfagent"/>
<Parameter Name="KeyFile" Value="..\test\keyfile.txt"/>
</Globals>
<Target id="9.164.259.143">
</Target>
<Target id="9.164.102.169">
</Target>
<Target id="9.164.102.196">
</Target>
<Target id="9.106.189.157">
</Target>
</AgentDeploymentAndUpdate>
You can specify a range of ip adresses for target systems. The following example works on IP addresses 9.184.112.152 to 9.184.112.160 using the same login credentials on each system: login root, password password.
<?xml version="1.0" encoding="UTF-8"?>
<AgentDeploymentAndUpdate>
<Target id=”9.184.112.152-160”>
<Parameter Name="ConnectionType" Value="ssh">
<Parameter Name="ConnectionPort" Value=""/>
<Parameter Name="UserName" Value="root">
<Parameter Name="Password" Value="passWord">
</Target>
</AgentDeploymentAndUpdate>
If all targets have the same properties (connection type, connection port, user name, password), then those properties can be specified in the Globals section of the file.
<?xml version="1.0" encoding="UTF-8"?>
<AgentDeploymentAndUpdate>
<Globals>
<Parameter Name="ConnectionType" Value="ssh">
<Parameter Name="ConnectionPort" Value="">
<Parameter Name="UserName" Value="root">
<Parameter Name="Password" Value="passWord">
</Globals>
<Target id=”9.184.112.152-160”>
</Target>
<Target id=”9.184.80.12-16”>
</Target>
</AgentDeploymentAndUpdate>