The bfagent.conf file stores settings for how the Rational® Build 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 may 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 machine. 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
- 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
wproduce.
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 machine's domain
is used.
- disable_telnet
- 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 which can slightly improve performance. In product
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.
- lang lang-code
This setting specifies the language that the agent uses to
write messages and command output.
The internal default is en,
as if it were explicitly set as follows:
- 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.
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:
- To create a server authentication that uses a user name and password.
- 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 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 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 its behaviour.
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 nologonshell. Use shellflag
-l.
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.
- 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.
For UNIX or Linux the setting is in /etc/services.
- 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 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
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 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.
- 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 enable 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 SSL, SSLv2, SSLv3, SSL_TLS,
TLS, TLSv1. The protocol must match the protocol used by the Build Forge server.
- 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.