BuildForge Help

BFAgent.conf Reference

The BFAgent.conf file stores settings for how the Build Forge agent runs. It is in the same directory as the bfagent executable.

Settings and internal defaults are all listed in the file. Inactive settings are commented out.

Settings
allow IP-address-or-range [...]
Used only with:
  • Agents running on Windows
  • Agents running in standalone mode on UNIX or Linux (-s option on startup).

Limits connections to the agent. Connections are allowed only from the IP addresses that match IP-address-or-range. By default connections are allowed from all addresses.

Specify one or more of the following:
  • IP Address: fully-qualified IPv4 or IPv6 address. For example, for IPv4, 255.192.192.003. The specific IP address is allowed.
  • IP Address range: partially-qualified IPv4 or IPv6 address. For example, for IPv4, 192.168 or 192.168.63. All IP addresses that match this qualification are allowed.
Note: If you are running the agent on a superserver like inetd or xinetd, use another method to control access. You may consider a firewall, TCP wrappers (hosts.allow and hosts.deny), or xinetd's built-in filtering capability.
ccviewroot root-path
Sets the default view root for this host. See ClearCase documentation on init for more information. Internal defaults are as follows:
  • Windows: ccviewroot M:
  • UNIX or Linux: ccviewroot /view
command_output_cache size
Causes the agent to cache output until it reaches the specified size (in bytes). The internal default is not to cache. Using a cache can significantly improve agent performance and reduce network overhead. The best size to use depends on how much output commands produce.

Minimum value: 2048. A value of 2048 is used internally if the setting is less than that.

cygwin
Used only with:
  • Agents on Windows

Enables agent to work on a Windows host using Cygwin, a Linux-like environment. When using Cygwin, a number of Linux tools are available to the agent.

When this setting is use, the cygwin_script_magic and shell settings may also need to be set. Example::
cygwin
shell C:\cygwin\bin\bash.exe --login -c "%s"
cygwin_script_magic #!/bin/bash

The shell setting must match your installation of Cygwin.

cygwin_script_magic
Used only with:
  • Agents on Windows when cygwin is set

Specifies the #! line to use when executing steps. The default is #!/bin/bash.

default_logon_domain
Specifies the domain to use when an authentification request does not include a domain. If not specified, the agent machine's domain is used.
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.
enable_agent_dll
Enables DLL process tracing, a debugging tool.
env_recursion_limit number-of-recursions
Sets the variable-replacement recursion limit for pre-parsing. If not set, the limit is 32.
extensions
Specifies path to external library of functions. The functions can be used as dot commands in a step. If not set, external libraries are not loaded.

During parsing, the first token in the step command is taken as the function name. The second token is a string, and the third is an integer timeout value (in seconds).

Requirement: dynamic loader support in the operating system. For example, /usr/include/dlfcn.h in UNIX or Linux. Default values used internally:
  • UNIX or Linux: /usr/local/bin/bfextensions.so
  • Windows: c:\program files\ibm\build forge\agent\bfextensions.dll
getaddrinfo_using_addrconfig
Used only for running the agent as a standalone service on UNIX or Linux systems (bfagent -s). This setting makes the agent use AI_ADDRCONFIG when calling getaddrinfo() to select a listening interface. By default AI_ADDRCONFIG is not used.

If set, the effect is for the agent to ignore interfaces that do not have a properly configured address. It listens only for interfaces that have a properly configured address.

If not set (the default), the agent attempts to listen on all available interfaces, regardless of whether they are properly configured.

lang lang-code
Used only when:
  • The Management Console does not provide a valid language
Sets the language used by the agent to write messages and command output. Normally it is not set explicitly because the agent uses the language specified by the Management Console. However, it can be useful if the desired locale is not available on the system. It is also useful as a backup, in case the Management Console fails to communicate a lang or communicates an invalid lang.

The internal default is en, as if it were explicitly set as follows:

lang en
leave_tmp_file
Used only with:
  • Troubleshooting
This setting causes the temporary file used to hold step commands to be retained, rather than deleted after command execution. In troubleshooting, the file can be compared to the steps as they appear in the Management Console.
Note: Do not use this setting for normal operations.
locale locale-code.charset-code
Used only with:
  • UNIX and Linux systems. Windows handles locales differently.
Sets the language and multibyte character set to be used by localized applications. This setting works by setting the LANG environment variable for the agent context.
To set up the agent to treat command output as US English UTF-8, use the UTF-8 locale for your operating system. For example, on Linux use the following representation.
locale en_US.UTF-8

To determine the correct representation of the UTF-8 locale for your operating system, run the locale -a command.

If not set, the agent uses the locale of the system. This setting is a convenience. It is especially useful if the default locale of the operating system is not the locale that you want the agent to use, or if changing the system locale to meet agent requirements is not practical.

magic_login user:encoded-password

The agent normally uses administrative privileges (such as root or admin) to log on to the operating system. The magic_login setting is an alternative to standard system authentication. It allows the system to authenticate your login with a single user name and password.

If the agent is run as the root or admin user, this setting is ignored and normal authentication is attempted.

Note: The agent runs all commands using the permissions of the user who started the agent, not the user name used to log in.
Used only with:
  • Situations where running the agent with administrative privileges is not possible (for example, System i with i5/OS, or old UNIX systems that do not work with PAM).
  • Situations where running the agent with administrative privileges is not permissible (due to security policies).
Note: Do not use special characters (e.g. %, $, [, ], {, }, ", or ') when creating passwords.
To configure a login for the agent:
  1. Create a server authentication to use a user name and password. In the Management Console, go to Servers > Server Auth.

    For this example the user name is build and the password is MySecretPassword.

  2. Create a server that uses the agent. Associate the server authentication with this server (Authentication field).
  3. Generate an encoded password for the agent. In the installation directory for the agent, execute bfagent -P with the desired password.

    An SMD5 hash-encoded password is returned, as follows:

    bfagent -P "MySecretPassword"
    eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
    
  4. In BFAgent.conf, set magic_login to use the desired user name and encoded password.
    magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
  5. Start the agent.
  6. Test the server connection. In Servers, select the server, then click Test Server.
map drive-and-user-spec[; ...]
Specifies a mapped drive. Some systems may require drive mappings, for example because a shell is run from a shared drive. Mappings specified on the agent are performed before mappings specified by _MAP environment variables in the Management Console. Example of two drive mappings:
map X:=//host1/share;Z:=//host2/share(username,password)
map_drive_is_failure
If set, causes a step to fail upon encountering an unmapped drive specification, before step execution. If not set, steps ignore drive failures and attempt to execute the step. In that case you may need to take care that the failure generates a meaningful error message.
monitor_pipe path

Reserved. Do not uncomment this setting.

no_preparse_command
Disables the variable-expansion parsing that the agent normally performs on a command before passing it to the shell. See also the _NO_PREPARSE_COMMAND environment variable, which can be used for an single project or step.
no_pty
Used only with:
  • Agents running on UNIX or Linux systems.
Can be used as an alternate method for fixing the tendency of the system shell to deadlock when interacting with the agent's pseudo-terminal. Commonly used with HP/UX and z/OS. Other methods are:
  • Using an alternate shell
  • Using the nologonshell setting
The no_pty setting disables pseudo-terminal allocation.
Note: Using no_pty has side effects on some commands. For example, the ls command returns output in a single column rather than three. If you use this setting, test thoroughly before deploying the job to a production environment.
nologonshell
Used only with:
  • Agents running on UNIX or Linux.
Uses standard methods of requesting that the shell be a normal shell rather than a logon shell. This may not work on all platforms and in such cases, the shellflag setting may be used to pass flags to the shell in order to modify itss behavior. Often used when logon shells provide verbose output, change environment settings in undesired ways, or attempt to communicate interactively with the user. Those behaviors are not desirable for the agent, because it runs as a user without being an interactive user.
Note: The Mac OS X 10.5 system uses /bin/bash, which does not respond to the presence or absence of nologonshell. Use shellflag -l to force it to use a login shell.
Note: The z/OS system always sources the /etc/profile script for both logon shells and non-logon shells. You may need to alter its contents or use another shell if its behavior does not work well with the agent.

See also the shellflag setting. Flags can be used to alter logon script behavior.

port port-number-or-range [...]
Used only with:
  • Agents running in standalone mode on UNIX or Linux (-s option on startup).
Specifies the port that the agent uses to listen for connections with the Management Console.
Note: The port is set to 5555 by default. It is set for UNIX or Linux in /etc/services.
shell shell_name [options]
Specifies the default shell. Internal defaults are as follows:
  • Windows: shell cmd.exe /q /c "%s" unless the following settings are used:
    • If the cygwin setting is used, the default is shell C:\cygwin\bin\bash.exe --login -c "%s"
    • If the cygwin setting is not used, the default is shell cmd.exe /u /q /c "%s"
  • UNIX or Linux: the shell set for the user's account, or /bin/sh if the user's shell can not be determined. Note that you cannot specify parameters in this setting, but you can use the shellflag setting to pass them. The agent automatically forces the default to be a logon shell by inserting a hyphen. For example, /bin/ksh is sent as -ksh. If shell is set explicitly, then nologonshell is set implicitly. See nologonshell.
  • System i: Set the shell value to /bin/sh

This setting can be overridden from within a step. A step that starts with a line containing #! overrides the shell setting and the nologonshell setting is used to execute the step commands.

shell_compatible_undef_vars
Forces representation of undefined variables to be an empty string. If not set, the representation is the variable name for variables of format $VAR, ${VAR}, or %VAR% and the empty string for $[VAR].
shellarg
Used only with:
  • Agents running on UNIX or Linux.

Use this setting if it appears that commands are being scrambled. Some shells on Red Hat Linux Enterprise require this setting.

The setting changes the way a command script is passed to the shell. Normally the script is passed through standard input:
   /bin/sh < /tmp/bfshellscript.sh
This setting causes scripts to be executed by passing them as parameters:
/bin/sh /tmp/bfshellscript.sh
shellflag flag
Used only with:
  • Agents running on UNIX or Linux.
Adds a flag when running a shell. Only one flag can be specified. It is commonly used to disable rc script processing in order to reduce output or undesired processing. Examples:
  • csh and derivatives: use shellflag -f to disable rc script processing.
  • bash: use shellflag –-noprofile to disable profile script processing.
update_path path
Identifies the full path to the Build Forge agent executable. It is set automatically during installation. The directory is a default for the specific operating system or the installation directory you specify.
Note: Ignored on Windows agents. The update path is taken from registry keys. The keys are set during agent installation.
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_reexec_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.