BuildForge Help

Documentation Additions for the Build Forge Agent

This section describes information about the Build Forge agent that was added to the Build Forge Installation Guide after the 7.0.2 documentation was shipped.

Configuring the Agent: Running Agent Commands on a Network Share File System (Windows)

This section describes new functionality for the Build Forge agent that was added after the Build Forge Installation Guide for 7.0.2 was shipped.

The Build Forge agent initially starts up with Windows system account credentials. To run commands, the agent later authenticates with Windows using Build Forge server auth credentials.

The server auth credentials are accepted for local commands but may fail for some commands that the agent must run on external, networked shared drives. For example, to modify files in a ClearCase dynamic view, the agent must access ClearCase files on a network shared drive.

The commands fail because the external file system ignores the agent server auth credentials; it only recognizes the agent's initial system account credentials.

If you experience problems running commands on a network shared drive, you have the following options:

Run commands using a server auth
To run commands using a Build Forge server auth with access to network shares, add the win_reexec_after_auth setting to the BFagent.conf file.
This is your only option if you want to use Build Forge server auth credentials to establish access to a network share.
The win_reexec_after_auth setting causes the agent to start a new process after authenticating with Windows. This forces the shared file system to recognize that the user credentials have changed by the agent.
When win_rexec_after_auth is set, the agent runs as a service and does not distinguish between commands that access network shares and those that do not, so you might notice a performance impact.
Run the agent in single user mode
During agent installation, set up the agent to run commands in single user mode (without Build Forge server auth credentials). Select the Install User Mode Agent option.
If the specified user is a member of the Administrator group, then the user's credentials must be specified using a server auth.
If the user is not an administrator, then use the magic_login setting in BFagent.conf to prevent unauthorized access to the agent.
When you log on to the Management Console, the agent starts up and runs as the user name you provide, which immediately authorizes access to the network shares using that user's credentials.
Run the agent as a service with a dedicated user account
Set up the agent to run as a Windows service with a dedicated user account. This option restricts you to running as a single user account but does not require the agent to start a new process to re-authenticate, so there is no performance impact.
  1. On the Build Forge server, open the Windows Control panel to access the list of services (Administration Tools > Services).
  2. Open the service for the IBM Rational Build Forge Agent.
  3. Provide the user account information for the user you want to use to run agent commands. For example, the ClearCase admin user or other user with access to ClearCase dynamic views and VOBs).

Configuring the Agent: BFAgent.conf Reference

The following new settings were added to the BFAgent.conf file in 7.0.2.

win_reexec_after_auth
Add this setting if you need to run agent commands on a network share file system using Build Forge server auth credentials. For example, to modify files in a ClearCase dynamic view, the agent must access ClearCase files on a networked shared file system.
The Build Forge agent initially starts up with Windows system account credentials. To run commands, the agent later authenticates with Windows using Build Forge server auth credentials.
Without this setting, the network share only recognizes the initial Windows system account credentials and ignores the subsequent server auth credentials needed to access and write to files on the network share file system.
The win_reexec_after_auth starts a new process after authenticating with Windows again using the server auth credentials and forces the shared file system to recognize the changed credentials.
When win_rexec_after_auth is set, the agent runs as a service and does not distinguish between commands that access network shares and those that do not, so you might notice a performance impact.
disable_telnet
Using telnet is recommended to test the agent connection.
For the agent, there is some built-in processing overhead associated with processing and correctly handling telnet control sequences.
This setting allows you to disable the agent’s normal internal handling of special telnet character codes which can slightly improve performance. (This setting is recommend for production environments.)
disable_transcode
Turns off processing the agent performs to convert international data if the operating system is not using UTF-8 encoding. (UTF-8 is recommended for the agent operating system to avoid mixed encodings and data corruption)
If the operating sytem does not use UTF-8 encoding, to correctly communicate with other applications, the agent must convert data to the correct encoding for the operating system's locale settings.
For operating systems that do not use UTF-8 this setting is recommended and can significantly improve the performance of the agent.