bfagent.conf reference

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

The file lists all settings and internal defaults. Inactive settings are commented out.

Settings

activity_log path

Turns on activity logging. The information is appended to the file specified by path. The path must exist and the agent user must have write permission for it.

Note: The agent does not report an error if the path does not exist or if it cannot write to the file.

Important: There is no limit on file size. The file must be manually deleted. This setting is intended to be used temporarily for debugging the agent. It is not intended as a permanent log for a working agent.

allow IP-address-or-range [...]

Use this setting for these conditions only:

Agents running on Windows
Agents running in standalone mode on UNIX or Linux when the -s option on startup is used

This setting 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 both of the items:

IP Address: A fully qualified IPv4 or IPv6 address. For example, for IPv4, 255.192.192.003. The specific IP address is allowed.
IP Address range: A partially qualified IPv4 or IPv6 address. These examples are correct 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 such as inetd or xinetd, use another method to control access. You might want to use a firewall, TCP wrappers (hosts.allow and hosts.deny), or the built-in filtering capability of xinetd.

bind

This setting allows the user to specify an explicit bind address for the agent. This, together with the "port" setting, determines how the agent will listen for connections when it is started with the -s command-line option. The value given in the bfagent.conf file will force the agent to bind to the IPv4 localhost address; thus, the agent will only receive connections from a console that is on the same computer. Example: bind 255.192.192.003

Note: It has no effect on Windows or UNIX agents that are started by the system's service architecture, such as inetd, xinetd, or launchd.

ccviewroot root-path

This setting specifies the default view root for this host. See ClearCase documentation on init for more information. The internal defaults are as follows:

Windows: ccviewroot M:
UNIX or Linux: ccviewroot /view

cc_suppress_server_root

If set, then the view path is the path set by ccviewroot. If not set, then the path set in the server definition is appended to the path set by ccviewroot. This setting does not need a value. If it is present in bfagent.conf, then it is set.

command_output_cache size

This setting 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 cache size depends on how much output that commands produce.

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

cygwin

This setting is used only with agents on Windows.

This setting enables the 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 you use this setting, you might need to set cygwin_script_magic and shell settings also. The example shows one way to configure these settings: :

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

This setting is used only with agents on Windows when cygwin is set.

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

default_logon_domain

Specifies the domain to use when an authentication request does not include a domain. If not specified, the agent computer's domain is used.

digest_algorithm SHA2

When password encryption is enabled, the bfagent uses SHA1 by default. To use SHA2, enable this setting. This setting is new in version 8.0.

When the bfagent upgrades to 8.0, this setting is not automatically added to bfagent.conf. You must add this setting to bfagent.conf when you want to use SHA2. If you are installing the bfagent 8.0 directly, bfagent.conf has this setting.

If you have already encrypted the password, after enabling this setting, you must encrypt the password again.

To use SHA2, make sure that the Digest Algorithm system configuration setting on the Build Forge® console is set to SHA2. For information about this setting, refer to the topic System configuration settings.

Note: When you use Secure Hash Algorithm 2 (SHA2) to enable password encryption in the Management Console and the agent, update the password encryption properties file, bfpwcrypt.conf.

Note: The Perl engine does not support Secure Hash Algorithm 2 (SHA2) in the message digest. SHA2 digest support is for the Java MJC from Build Forge 8.0 and the Build Forge Agent 8.0.

If password encryption is not enabled in the configuration properties file, bfpwcrypt.conf, use these steps to enable password encryption for SHA2:

Rename the password encryption configuration properties file. For example, change the name of the bfpwcrypt.conf file to bfpwcrypt.conf.sha1.
Navigate to Administration > System, and change the Digest Algorithm setting to SHA2.
Restart the Management Console. A new bfpwcrypt.conf file is created.
Enable password encryption. Navigate to Administration > Security and set the Password Encryption Enabled setting to Yes. Click Save and click Update Master BFClient.conf.
Optional: Navigate to Administration > Security > Keystore and update the keystore's password. Navigate to Administration > Server > Server Auth, Administration > LDAP, and Administration > User, as appropriate, and update each of the passwords.
If the agent also enables password encryption, copy the newly generated bfpwcrypt.conf file to the server where the agent is located.
If the ssl_key_password was encrypted when it was previously set in the bfagent.conf file, you must re-encrypt the password. For example, enable digest_algorithm SHA2 by removing the # before the line in the bfagent.conf file, then re-encrypt using the command, bfagent -e <your password> , on the command line. This creates a new encrypted password. Reset the ssl_key_password in the bfagent.conf file using this new encrypted password and save it.
Restart the bfagent.

If password encryption is enabled in the configuration properties file, bfpwcrypt.conf, use these steps to re-enable password encryption for SHA2:

Disable password encryption. Navigate to Administration > Security and set the Password Encryption Enabled setting to No. Click Save and click Update Master BFClient.conf to make sure that the bf_keystore_password in the bfclient.conf file is not equal to the {bfcrypt:xxx..}yyy... format.
If the ServerAuth, LDAP, and User passwords have been added or updated since password encryption was initially enabled, navigate to Administration > Security > Keystore, and update each of the passwords.
Rename the password encryption configuration properties file. For example, change the name of the bfpwcrypt.conf file to bfpwcrypt.conf.sha1.
Navigate to Administration > System, and change the Digest Algorithm setting to SHA2.
Restart the Management Console. A new bfpwcrypt.conf file is created.
Enable password encryption. Navigate to Administration > Security and set the Password Encryption Enabled setting to Yes. Click Save and click Update Master BFClient.conf.
Optional: Navigate to Administration > Security > Keystore and update the keystore's password. Navigate to Administration > Server > Server Auth, Administration > LDAP, and Administration > User, as appropriate, and update each of the passwords.
If the agent also enables password encryption, copy the newly generated bfpwcrypt.conf file to the server where the agent is located.
If the ssl_key_password was encrypted when it was previously set in the bfagent.conf file, you must re-encrypt the password. For example, enable digest_algorithm SHA2 by removing the # before the line in the bfagent.conf file, then re-encrypt using the command, bfagent -e <your password>, on the command line. This creates a new encrypted password. Reset the ssl_key_password in the bfagent.conf file using this new encrypted password and save it.
Restart the bfagent.

disable_telnet_support

For best results, use telnet to test the agent connection.

For the agent, there is some built-in processing overhead associated with processing and correctly handling telnet control sequences.

Use this setting to disable the agent from handling special telnet character codes, thereby slightly improving performance. In production environments, use this setting to benefit from the improved performance.

disable_transcode

Turns off processing that the agent performs to convert international data when the operating system is not using UTF-8 encoding. To avoid mixed encodings and data corruption, use UTF-8 for the agent operating system.

If the operating system does not use UTF-8 encoding, the agent must convert data to the correct encoding for the operating system's locale settings.

If your operating does not use UTF-8, use this setting for best results and improved performance of the agent.

enable_agent_dll

This setting enables DLL process tracing, which is 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

This setting specifies paths to external libraries of functions. The functions can be used as dot commands in a step. If this setting is not specified, 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, in UNIX or Linux you need /usr/include/dlfcn.h. These defaults values are used internally.

UNIX or Linux: /usr/local/bin/bfextensions.so
Windows: C:\program files\ibm\build forge\agent\bfextensions.dll

getaddrinfo_using_addrconfig

This setting is used only for running the agent as a standalone service on UNIX or Linux operating 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 you use this setting, the agent ignores interfaces that do not have a properly configured address. It listens only for interfaces that have a properly configured address.

gsk_ssl_key_location [ <kdb_path> | <SAF_specification> ]

Specifies either a full path to a kdb file or a SAF key ring specification.

gsk_ssl_kdb_password <password>

Password for the kdb file. It can be in plain text or encrypted text. Use NULL if a SAF key ring is used. Use

bfagent
-e <plaintext>

to create the encrypted password from plain text.

gsk_ssl_protocol <protocol>

The protocol to use, one of ALL (the default), SSLV2, SSLV3, TLSV1, or TLSV1_1

gsk_ssl_cipher_v2 <seed>

The cipher suite to use for system SSL version 2 (SSLV2). The default value is 6321, which should serve most applications. See the System z documentation for more information.

gsk_ssl_cipher_v3 <seed>

The cipher suite to use for system SSL version 3 (SSLV3). The default value is 0906030201, which should serve most applications. However, in some cases, you need to change the default value to 090604030201. Adjust it according to your actual configurations. See the z Systems documentation for more information.

gsk_keyring_label <label>

The key label in the kdb file.

gsk_password_encrypt [true | false]

Used to refer to an encrypted password. If set to true, use

bfagent
-e <plaintext>

to create an encrypted value and set gsk_ssl_kdb_password. It is set to false by default.

gsk_ssl_client_authentication [true | false]

Specifies whether to validate the client certificate. The default is false

lang lang-code

Use this setting only when the Management Console does not provide a valid language.

This setting specifies the language that the agent uses to write messages and command output. Typically it is not set explicitly because the agent uses the language that the Management Console specifies. However, setting the language can be useful if the desired locale is not available on the computer. The setting is also useful as a backup, in case the Management Console fails to communicate a language or communicates an invalid language.

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

lang en

leave_tmp_file

Use this setting only while you are troubleshooting.

This setting causes the temporary file that is 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 are displayed in the Management Console.

Note: Do not use this setting for typical operations.

locale locale-code.charset-code

This setting is used only with UNIX and Linux operating systems. Windows handles locales differently.

This setting specifies the language and multibyte character set that localized applications use. 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 this setting is not specified, the agent uses the locale of the operating system. This setting is a convenience. This setting is especially useful if the default locale of the operating system is not the locale that you want the agent to use. The setting is especially useful if changing the system locale to meet agent requirements is not practical.

magic_login user:encoded-password

The agent typically 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. With this setting, the system can 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.

The agent runs all commands using the permissions of the user who started the agent, not the user name used to log in.

This setting is used in only these situations:

When running the agent with administrative privileges is not possible. For example, use this setting with UNIX systems that do not work with PAM.
When running the agent with administrative privileges is not permissible because of security policies.

To configure a login for the agent:

Create a server authentication that uses a user name and password. In the Management Console, click Servers > Server Auth.
For this example the user name is build, and the password is MySecretPassword.
Create a server that uses the agent. Associate the server authentication with this server in the Authentication field.
Generate an encoded password for the agent. In the installation directory for the agent, run bfagent -P with the password that you choose.
An SMD5 hash-encoded password is returned, as follows:
```
bfagent -P "MySecretPassword"
eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
```
In BFAgent.conf, set magic_login to use the desired user name and encoded password.
```
magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
```
Start the agent.
Test the server connection. In Servers, select the server, and then click Test Server.

map drive-and-user-spec[; ...]

This setting specifies a mapped drive. Some systems might require drive mappings. For example, a drive mapping might be required 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. This example illustrates two drive mappings:

map X:=//host1/share;Z:=//host2/share(username,password)

map_drive_is_failure

When specified, this setting causes a step to fail upon encountering an unmapped drive specification, before step execution. If this setting is not specified, steps ignore drive failures and attempt to run the step. In that case ensure that the failure generates a meaningful error message.

no_preparse_command

This setting disables the variable-expansion parsing that the agent typically performs on a command before passing the command to the shell. See also the _NO_PREPARSE_COMMAND environment variable, which can be used for an single project or step.

no_pty

This setting is used only with agents that are running on UNIX or Linux systems.

This setting can be used to help prevent the system shell from locking up when the shell interacts with the pseudoterminal of the agent. This setting is typically used with HP-UX and z/OS. You can also use two other methods to help prevent this kind of lockup:

Use an alternate shell
Use the nologonshell setting

The no_pty setting disables the pseudoterminal allocation.

Note: Using no_pty affects some commands. For example, the ls command returns output in a single column rather than three columns. If you use this setting, test thoroughly before you deploy the job to a production environment.

nologonshell

Use this setting only with agents that are running on UNIX or Linux.

This setting causes the shell that the agent runs to be a normal shell, not a logon shell. This setting is often useful in these cases:

The logon shells provide verbose output
The logon shells change environment settings in unwanted ways
The logon shells attempt to communicate interactively with the user

When set, standard methods of requesting that the shell be a normal shell rather than a logon shell are used. This might not work on all platforms and in such cases, the shellflag setting can be used to pass flags to the shell to modify its behavior.

Those behaviors are not desirable for the agent, because it runs as a user without being an interactive user.

Note: The z/OS operating system always uses the /etc/profile script for both logon shells and non-logon shells. You might need to change the contents of the script or use another shell if its behavior does not work well with the agent.

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

password_encrypt_module dll_path;conf_path

Required to enable SSL on the agent. It specifies paths to a DLL and configuration file.

dll_path is the path to bfcrypt.dll (it is typically ./bfcyrpt.dll).
conf_path is the path to bfpwcrypt.conf (it is typically ./bfcrypt.conf).

port port-number-or-range [...]

This setting is used only with agents that are running in standalone mode on UNIX or Linux when you issue the -s option on startup.

This setting specifies the port that the agent uses to listen for connections with the Management Console.

Specifies the port that the agent uses to listen for connections with the Management Console.

Note: The port is set to 5555 by default. For UNIX or Linux the setting is in /etc/services.

read_timout

Time in seconds that the agent waits for a request until it disconnects. The default is 1800 seconds (30 minutes). Set the value to 0 to disable the timeout.

The directive helps prevent client connection contacts from holding the port open if a legitimate engine request is not received. Some network port-scanning software behaves this way.

Do not set very small values for this directive. Normal engine behavior might include gaps between requests of several minutes.

shell shell_name [options]

This setting 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 account, or /bin/sh if the user's shell cannot 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

You can override this setting from within a step. A step that starts with a line containing #! overrides the shell setting, and the nologonshell setting is used to run the step commands.

shell_compatible_undef_vars

This setting forces the 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

This setting is used only with agents that are running on UNIX or Linux.

Use this setting if it seems 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 run by passing them as parameters:

/bin/sh /tmp/bfshellscript.sh

shellflag flag

This setting is used only with agents that are running on UNIX or Linux.

This setting adds a flag when a shell is running. Only one flag can be specified. It is typically used to disable rc script processing 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.

ssl_ca_location path

Specifies the keystore file that contains the certificate authority. If the agent runs as a service, use an absolute path.

ssl_cert_location path

Specifies the keystore that contains the private certificate. If the agent runs as a service, use an absolute path.

ssl_client_authentication [true | false]

Set to true to require client authentication when a connection is made to the agent. If true, the Build Forge engine's certificate must be added to the agent's certificate authority keystore.

ssl_cipher_group [grouplist | ALL]

Specifies individual cipher groups to use. Can be set to ALL.

ssl_cipher_override cyphers

Overrides the cipher group. Specify the ciphers to use.

ssl_key_location path

Specifies the keystore file that contains the key. If the agent runs as a service, use an absolute path.

ssl_key_password password

Password for the key. This property is stored in clear text by default. You can configure the agent to encrypt this password using its own key or the Build Forge server's key.

ssl_protocol protocol

The SSL handshake protocol to use, one of TLSv1, TLSv1.1, TLSv1.2. The protocol must match the protocol used by the Build Forge^® server. When enabled, TLSv1, TLSv1.1, or TLSv1.2, it only accepts the corresponding connection. For example, when TLSv1.2 is enabled, the bfagent only accepts a TLSv1.2 connection.

update_path path

This setting identifies the full path to the Build Forge agent executable. The setting is established automatically during installation. The directory is a default directory for the operating system or the installation directory that you specify.

Note: This setting is 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 authentication 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 authentication credentials.; Without this setting, the network share recognizes only the initial Windows system account credentials and ignores the subsequent server authentication credentials that are 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 by using the server authentication credentials and forces the shared file system to recognize the changed credentials.; When you use the win_reexec_after_auth setting, the agent runs as a service and does not distinguish between commands that access network share files and those that do not, so you might notice a performance impact.

xstream_allow_ssl_mismatch: Required if file transfer is needed between an agent compiled with OpenSSL and an agent compiled without OpenSSL. By default agents compiled with OpenSSL require AES_CBC encrypted file transfers. They reject any file transfers requested using PLAIN or PRNG encoding unless this setting is used.

xstream_bind ip_address: Specifies an IP address to be used only for direct file transfers. The address must be accessible by the agents that receive the files. By default an agent listens on all network interfaces. See also bind.

xstream_conn_timeout seconds: Time in seconds that an agent waits for a connection. The engine must forward the connection request to the receiving agent and the receiving agent must establish a connection with the sending agent within this time. By default it is set to 20 seconds.

xstream_listen_range port-range: The range of ports an agent listens on for connections. This setting is useful when there is a firewall between the connecting hosts. The firewall administer can configure the firewall to allow the ports permitted for connections, for example 22880-22889. The default port-range is 16384-32767. However, if xstream_bind is used and xstream_listen_randomize is not used, then the agent does not specify a range and the operating system determines what ports to use.

xstream_listen_randomize: Causes random selection of a port within xstream_port_range. If not specified, the agent starts checking with the lowest port number. This setting is highly recommended as a security measure.

xstream_recv_timeout seconds: Time to wait for file transfer. If during any time in the file transfer this period passes without the receiving agent getting data from the sending agent, then the transfer fails and the connection is closed. The default is 20 seconds.

xstream_send_timeout seconds: Time to wait for file transfer. If during any time in the file transfer this period passes without the sending agent being able to write data to the receiving agent, then the transfer fails and the connection is closed. The default is 20 seconds.

env_output_buffer_size: Specifies the output buffer size of the environment in Build Forge. Use this setting for the Build Forge agent to avoid the java.lang.IndexOutOfBoundsException: Index: xxx, Size: xxx exception when the agent is expanding the environment. The buffer size depends on how many environment variables are set in Build Forge.; The default is 16384. If the specified value is less than 16384, the default value is used.