bfagent.conf 文件存储关于 Build
Forge 代理程序运行方式的设置。该文件与 bfagent 可执行文件位于同一目录中。
该文件列出了所有设置和内部缺省值。不活动的设置已被注释掉。
- 设置
- activity_log path
- 打开活动日志记录。将信息附加到 path 指定的文件中。路径必须存在,并且代理程序用户必须对其具有写许可权。
注: 如果路径不存在或者不能对文件进行写操作,代理程序不会报告错误。
要点: 文件大小没有限制。必须手动删除文件。此设置旨在临时用于调试代理程序。它不应用作工作代理程序的永久日志。
- allow IP-address-or-range [...]
- 此设置仅适用于以下情况:
- 在 Windows 中运行的代理程序
- 以独立方式在 UNIX 或 Linux 上运行的代理程序(启动时使用 -s 选项)
此设置限制到代理程序的连接。只允许来自与 IP-address-or-range 匹配的 IP 地址的连接。
缺省情况下,允许来自所有地址的连接。
指定以下一项或两项:
- IP 地址:标准 IPv4 或 IPv6 地址。例如,对于 IPv4,标准地址为 255.192.192.003。允许特定的 IP 地址。
- IP 地址范围:部分限定 IPv4 或 IPv6 地址。
这些示例(192.168 或 192.168.63)对于 IPv4 是正确的。允许与此限定匹配的所有 IP 地址。
注: 如果正在超级服务器(如 inetd 或 xinetd)上运行代理程序,请使用其他方法来控制访问。您可能希望使用防火墙、TCP 包装器(hosts.allow 和 hosts.deny)或 xinetd 的内置过滤功能。
- bind
- 此设置允许用户为代理程序指定显式绑定地址。此设置与“port”设置共同确定代理程序在使用 -s 命令行选项启动时将如何侦听连接。bfagent.conf 文件中给出的值将强制代理程序绑定到
IPv4 本地主机地址;这样,代理程序只会接收到来自相同计算机上的控制台的连接。示例:bind 255.192.192.003
注: 它对通过系统的服务体系结构启动的 Windows 或 UNIX 代理程序(如 inetd、xinetd 或 launchd)没有影响。
- ccviewroot root-path
- 此设置为此主机指定缺省视图根。请参阅关于 init 的
ClearCase 文档以了解更多信息。内部缺省值如下所示:
- Windows:ccviewroot M:
- UNIX 或 Linux:ccviewroot/view
- cc_suppress_server_root
- 如果设置,那么查看路径为 ccviewroot 设置的路径。如果不设置,那么服务器定义中设置的路径将附加到 ccviewroot 设置的路径。此设置不需要值。如果 bfagent.conf 中存在此设置,将设置该值。
- command_output_cache size
- 此设置使代理程序高速缓存输出,直到达到指定的大小(以字节为单位)。内部缺省值不会存入高速缓存。使用高速缓存可以显著改善代理程序性能并减少网络开销。高速缓存大小取决于命令产生的输出量。
最小值:2048。当设置低于该值时,内部将使用值 2048。
- cygwin
- 此设置仅用于 Windows 上的代理程序。
此设置使得代理程序能在使用 Cygwin、Linux 之类环境的 Windows 主机上工作。使用 Cygwin 时,对代理程序提供了若干 Linux 工具。
使用此设置时,可能还需要设置 cygwin_script_magic 和 shell 设置。示例显示了配置这些设置的一种方法:
cygwin
shell C:\cygwin\bin\bash.exe --login -c "%s"
cygwin_script_magic #!/bin/bash
shell 设置必须与您的 Cygwin 安装相匹配。
- cygwin_script_magic
- 此设置仅用于 Windows 上的代理程序(如果设置了 cygwin)。
此设置指定在执行步骤时要使用的 #! 行。缺省为 #!/bin/bash。
- default_logon_domain
- 用于指定在认证请求不包含域的情况下要使用的域。如果未指定,将使用代理程序计算机的域。
- disable_telnet_support
- 为了得到最佳结果,可使用 telnet 测试代理程序连接。
- 对于该代理程序,存在与处理和正确处理 Telnet 控制序列相关联的某些内置处理开销。
- 使用此设置可禁用代理程序对特殊 telnet 字符代码的处理,因此可以稍微提高性能。在生产环境中,使用此设置可提高性能,从而使您受益。
- disable_transcode
- 当操作系统未在使用 UTF-8 编码时,将关闭代理程序为了转换国际数据而执行的处理。要避免混合编码和数据损坏,请对代理程序操作系统使用 UTF-8。
- 如果操作系统不使用 UTF-8 编码,那么代理程序必须将数据转换为适于操作系统的语言环境设置的正确编码。
- 如果操作不使用 UTF-8,为了获得最佳结果并提高代理程序的性能,请使用此设置。
- enable_agent_dll
- 此设置启用 DLL 进程跟踪(一种调试工具)。
- env_recursion_limit number-of-recursions
- 为预解析设置变量替换递归限制。如果未设置,限值为 32。
- extensions
- 此设置指定函数外部库的路径。
可以将函数用作步骤中的点命令。如果未指定此设置,将不会装入外部库。
在进行解析时,步骤命令中的首个标记将作为函数名。第二个标记是字符串,而第三个标记是整数超时值(以秒为单位)。
需求:操作系统中支持动态装入程序。例如,在 UNIX 或 Linux 中,您需要 /usr/include/dlfcn.h。
在内部使用这些缺省值。
- UNIX 或 Linux:/usr/local/bin/bfextensions.so
- Windows:C:\program files\ibm\build forge\agent\bfextensions.dll
- getaddrinfo_using_addrconfig
- 此设置仅用于将代理程序作为独立的服务在 Unix 或 Linux 操作系统上运行 (bfagent -s)。调用 getaddrinfo() 来选择侦听接口时,此设置可使代理程序使用 AI_ADDRCONFIG。缺省情况下,不使用 AI_ADDRCONFIG。
如果使用此设置,代理程序将忽略未正确配置地址的接口。它仅侦听地址配置正确的接口。
- gsk_ssl_key_location [ <kdb_path> | <SAF_specification>
]
- 指定 kdb 文件的完整路径或 SAF 密钥环规范。
- gsk_ssl_kdb_password <password>
- kdb 文件的密码。可以是纯文本或加密文本。如果使用 SAF 密钥环,请使用 NULL。使用 bfagent
-e <plaintext>,从纯文本创建加密的密码。
- gsk_ssl_protocol <protocol>
- 要使用的协议,是 ALL(缺省值)、SSLV2、SSLV3、TLSV1 或 TLSV1_1 之一
- gsk_ssl_cipher_v2 <seed>
- 用于系统 SSL V2 (SSLV2) 的密码套件。缺省值为 6321,适用于大多数应用程序。请参阅
System z 文档以了解更多信息。
- gsk_ssl_cipher_v3 <seed>
- 用于系统 SSL V3 (SSLV3) 的密码套件。缺省值为 0906030201,适用于大多数应用程序。
请参阅
System z 文档以了解更多信息。
- gsk_keyring_label <label>
- kdb 文件中的密钥标签。
- gsk_password_encrypt [true | false]
- 用于引用加密密码。如果设置为 true,请使用 bfagent
-e <plaintext> 创建加密值并设置 gsk_ssl_kdb_password。缺省情况下,设置为 false。
- gsk_ssl_client_authentication [true | false]
- 指定是否验证客户机证书。缺省是 false
- lang lang-code
- 仅当管理控制台未提供有效语言时使用此设置。
此设置指定代理程序用于写入消息和命令输出的语言。通常,这不是显式设置的,因为代理程序使用管理控制台指定的语言。但是,如果计算机中没有所要的语言环境,那么设置语言可能很有用。如果管理控制台未能以某种语言进行通信,或者以无效语言进行通信,那么此设置作为一种备份也是有用的。
内部缺省值为 en,就象以下列方式对其进行显式设置一样:
- leave_tmp_file
- 此设置仅用于故障诊断。
此设置使得用于存放步骤命令的临时文件得以保留,而不是在命令执行后就删除。故障诊断时,该文件可与出现在管理控制台中的步骤进行比较。
- locale locale-code.charset-code
- 此设置仅用于 UNIX 和 Linux 操作系统。
Windows 以不同的方式处理语言环境。
此设置指定本地化应用程序使用的语言和多字节字符集。此设置通过设置代理程序上下文的 LANG 环境变量起作用。
要将代理程序设置为将命令输出视为美国英语 UTF-8,请对操作系统使用 UTF-8 语言环境。例如,对于 Linux 使用以下表示法。
locale en_US.UTF-8
要为操作系统确定 UTF-8 语言环境的正确表示法,请运行 locale -a 命令。
如果未指定此设置,代理程序将使用操作系统的语言环境。此设置作为方便之用。如果根据代理程序要求更改系统语言环境不太实际,那么此设置将特别有用。如果根据代理程序要求更改系统语言环境不太实际,那么此设置将特别有用。
- magic_login user:encoded-password
- 代理程序通常使用管理特权(例如 root 或 admin)登录至操作系统。magic_login 设置是对标准系统认证的替代。通过此设置,系统可以使用单一用户名和密码来认证登录。
如果代理程序作为 root 或 admin 用户运行,那么将忽略此设置并尝试标准认证。
代理程序使用启动代理程序的用户(而非用于登录的用户名)的许可权来运行所有命令。
此设置仅用于以下情形:
- 无法使用管理特权运行代理程序时。
例如,将此设置用于无法处理 PAM 的 UNIX 系统。
- 由于安全策略而不允许使用管理特权运行代理程序时。
要配置代理程序的登录,请执行以下操作:
- 创建使用用户名和密码的服务器认证。
在管理控制台中,单击。
- 对于此示例,用户名为 build,密码为 MySecretPassword。
- 创建使用代理程序的服务器。在认证字段中将服务器认证与此服务器相关联。
- 为代理程序生成经编码的密码。在代理程序的安装目录中,以选择的密码运行 bfagent -P。
将返回以 SMD5 散列编码的密码,如下所示:
bfagent -P "MySecretPassword"
eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
- 在 BFAgent.conf 中,设置 magic_login 以使用期望的用户名和经编码的密码。
magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
- 启动代理程序。
- 测试服务器连接。在服务器中选择服务器,然后单击测试服务器。
- map drive-and-user-spec[; ...]
- 此设置指定映射的驱动器。有些系统可能需要驱动器映射。例如,由于 shell 是从共享驱动器运行的,因此可能需要驱动器映射。在指定由管理控制台中的环境变量 _MAP 所指定的映射之前,将执行在代理程序上指定的映射。此示例说明了两个驱动器映射:
map X:=//host1/share;Z:=//host2/share(username,password)
- map_drive_is_failure
- 如果已指定此设置,那么在步骤执行前指定了未映射的驱动器将导致该步骤失败。如果未指定此设置,步骤将忽略驱动器故障并尝试执行步骤。在此情况下,请确保故障生成有意义的错误消息。
- no_preparse_command
- 此设置禁用变量扩展解析(代理程序通常在将命令传递给 shell 之前对命令执行此解析)。另请参阅环境变量 _NO_PREPARSE_COMMAND,它用于单个项目或步骤。
- no_pty
- 此设置仅用于在 UNIX 或 Linux 系统上运行的代理程序。
此设置可用于帮助防止系统 shell 在与代理程序的伪终端交互时被锁定。此设置通常用于 HP-UX 和 z/OS。
您还可以使用其他两种方法以帮助防止此种锁定:
- 使用备选 shell
- 使用 nologonshell 设置
no_pty 设置禁用伪终端分配。
注: 使用 no_pty 会影响某些命令。例如,ls 命令以单列而不是以三列返回输出。如果使用此设置,请在将作业部署到生产环境中之前进行彻底的测试。
- nologonshell
- 此设置仅用于在 UNIX 或 Linux 上运行的代理程序。
此设置使代理程序运行的 shell 成为普通 shell,而不是登录 shell。此设置通常在以下情况下很有用:
- 登录 shell 提供详细的输出
- 登录 shell 以意外的方式更改环境设置
- 登录 shell 尝试与用户以交互方式通信
设置后,将使用标准方法请求 shell 应为普通 shell 而不是登录 shell。这可能并非在所有平台上都有效,在这些情况下,也许可以使用 shellflag 设置将标志传递至 shell 以修改其行为。
代理程序不需要这些行为,因为它以用户身份运行,而不是以交互用户身份运行。
注: Mac OS
X 10.5 系统使用 /bin/bash,它不会对 nologonshell 作出响应。使用 shellflag
-l。
注: z/OS 操作系统始终将 /etc/profile 脚本用于登录 shell 和非登录 shell。如果 shell 行为不适用于代理程序,那么您可能需要更改脚本的内容或使用其他 shell。
另请参阅 shellflag 设置。
标志可用于更改登录脚本行为。
- password_encrypt_module dll_path;conf_path
- 这是在代理程序上启用 SSL 所必需的。它指定了 DLL 和配置文件的路径。
- dll_path 是 bfcrypt.dll(通常为 ./bfcyrpt.dll)的路径。
- conf_path 是 bfpwcrypt.conf(通常为 ./bfcrypt.conf)的路径。
- port port-number-or-range [...]
- 此设置仅用于以独立方式在 UNIX 或 Linux 上运行的代理程序(启动时发出 -s 选项)。
此设置指定代理程序用于侦听与管理控制台的连接的端口。
指定代理程序用于侦听与管理控制台的连接的端口。
注: 缺省情况下,该端口被设置为 5555。对于 UNIX 或 Linux,此设置在 /etc/services 中。
- read_timout
- 代理程序在断开连接之前,等待请求的时间(秒)。
缺省值为 1800 秒(30 分钟)。将值设置为 0 则禁用超时。
此伪指令有助于在未收到合法的引擎请求时,防止客户机连接联系人将端口保持打开状态。某些网络端口扫描软件就是这样工作的。
请勿为该伪指令设置太小的值。正常引擎行为在请求之间可能会有几分钟的间隔。
- shell shell_name [options]
- 此设置指定缺省 shell 程序。内部缺省值如下:
- Windows:shell cmd.exe /q /c "%s",除非使用了以下设置:
- 如果使用 cygwin 设置,缺省为 shell
C:\cygwin\bin\bash.exe --login -c "%s"
- 如果不使用 cygwin 设置,缺省为 shell
cmd.exe /u /q /c "%s"
- UNIX 或 Linux:为用户帐户设置的 shell,或 /bin/sh(如果无法确定用户的 shell)。请注意,虽然您无法指定此设置中的参数,但是可使用 shellflag 设置传递这些参数。代理程序会通过插入连字号,自动将缺省值强制设置为登录 shell。例如,将 /bin/ksh 设置为 -ksh。如果显式设置了 shell,那么会隐式设置 nologonshell。请参阅 nologonshell。
- System i:将 shell 值设置为 /bin/sh
可以在步骤内覆盖此设置。用包含 #! 的行开始的步骤会覆盖此 shell 设置,而 nologonshell 设置用于运行步骤命令。
- shell_compatible_undef_vars
- 此设置将未定义的变量强行表示为空字符串。如果未设置,将表示为变量的名称,格式为 $VAR、
${VAR} 或 %VAR%,而 $[VAR] 用于表示空字符串。
- shellarg
- 此设置仅用于在 UNIX 或 Linux 上运行的代理程序。
如果命令出现乱码,请使用此设置。Red Hat Linux Enterprise 上的某些 shell 需要此设置。
此设置将更改命令脚本传给 shell 的方式。通常,通过标准输入传递脚本:
/bin/sh < /tmp/bfshellscript.sh
此设置会将脚本作为参数来传递,从而运行脚本:
/bin/sh /tmp/bfshellscript.sh
- shellflag flag
- 此设置仅用于在 UNIX 或 Linux 上运行的代理程序。
此设置在 shell 正在运行时添加标志。
只能指定一个标志。它通常用于禁用 rc 脚本处理以减少输出或不需要的处理。示例:
- csh 和派生:使用 shellflag -f 来禁用 rc 脚本处理。
- bash:使用 shellflag –-noprofile 来禁用概要脚本处理。
- ssl_ca_location path
- 指定包含认证中心的密钥库文件。如果代理程序作为服务运行,请使用绝对路径。
- ssl_cert_location path
- 指定包含专用证书的密钥库。如果代理程序作为服务运行,请使用绝对路径。
- ssl_client_authentication [true | false]
- 如果设置为 true,那么连接到代理程序时要求进行客户机认证。如果为 true,那么必须将 Build Forge 引擎的证书添加到代理程序的认证中心密钥库中。
- ssl_cipher_group [grouplist | ALL]
- 指定要使用的单独密码组。可以设置为 ALL。
- ssl_cipher_override cyphers
- 覆盖密码组。指定要使用的密码。
- ssl_key_location path
- 指定包含密钥的密钥库文件。如果代理程序作为服务运行,请使用绝对路径。
- ssl_key_password password
- 密钥的密码。缺省情况下,此属性以明文存储。您可以将代理程序配置为使用其自己的密钥或 Build Forge 服务器的密钥加密此密码。
- ssl_protocol protocol
- 要使用的 SSL 握手协议:SSL、SSLv2、SSLv3、SSL_TLS、TLS 或 TLSv1 中的一个。该协议必须与 Build
Forge 服务器使用的协议匹配。
- update_path path
此设置确定 Build Forge 代理程序可执行文件的完整路径。此设置是在安装期间自动建立的。
该目录是操作系统的缺省目录或您指定的安装目录。
注: Windows 代理程序上忽略此设置。更新路径从注册表键中获取。这些键是在代理程序安装期间设置的。
- win_reexec_after_auth
- 如果需要使用 Build Forge 服务器认证凭证在网络共享文件系统中运行代理程序命令,请添加此设置。例如,要在 ClearCase 动态视图中修改文件,代理程序必须在网络共享文件系统上访问 ClearCase 文件。
- Build Forge 代理程序最初将使用 Windows 系统帐户凭证启动。要运行命令,代理程序稍后将通过 Build Forge 服务器认证凭证向 Windows 进行认证。
- 如果没有此设置,网络共享将仅识别初始 Windows 系统帐户凭证,并忽略访问与写入网络共享文件系统上的文件所需的后续服务器认证凭证。
- win_reexec_after_auth 将在使用服务器认证凭证再次向 Windows 认证后启动新的进程,并强制共享文件系统识别更改后的凭证。
- 如果使用 win_reexec_after_auth 设置,那么代理程序将作为服务运行,并且不区别访问网络共享文件的命令和不访问网络共享文件的命令,因此您可能要注意性能影响。
- xstream_allow_ssl_mismatch
- 如果在使用 OpenSSL 编译的代理程序和不是使用 OpenSSL 编译的代理程序之间需要文件传输,那么此设置是必需的。缺省情况下,使用 OpenSSL 编译的代理程序需要由 AES_CBC 加密的文件传输。除非使用此设置,否则它们会拒绝使用 PLAIN 或 PRNG 编码请求的任何文件传输。
- xstream_bind ip_address
- 指定仅用于直接文件传输的 IP 地址。
接收文件的代理程序必须可访问此地址。
缺省情况下,代理程序侦听所有网络接口。另请参阅 bind。
- xstream_conn_timeout seconds
- 代理程序等待连接的时间(秒)。引擎必须将连接请求转发给接收方代理程序,而接收方代理程序在这段时间内必须与发送方代理程序建立连接。缺省情况下,设置为 20 秒。
- xstream_listen_range port-range
- 代理程序用于侦听连接的端口范围。如果连接主机之间有防火墙,那么此设置就很有用。防火墙管理员可以配置防火墙,以允许某些端口(例如 22880-22889)可用于连接。缺省端口范围是 16384-32767。但是,如果使用 xstream_bind,但未使用 xstream_listen_randomize,那么代理程序不会指定范围,而是由操作系统确定使用哪些端口。
- xstream_listen_randomize
- 在 xstream_port_range 内随机选择一个端口。如果未指定,那么代理程序开始检查最小端口号。
强烈建议将此设置作为一种安全措施。
- xstream_recv_timeout seconds
- 等待文件传输的时间。如果在文件传输的任何时候,在该时间段过后接收方代理程序未能从发送方代理程序获得数据,那么传输失败,连接会关闭。缺省值为 20 秒。
- xstream_send_timeout seconds
- 等待文件传输的时间。如果在文件传输的任何时候,在该时间段过后发送方代理程序未能向接收方代理程序写数据,那么传输失败,连接会关闭。缺省值为 20 秒。