bfagent.conf 參照

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 位址。以下是 IPv4 正確位址的範例:192.168 或 192.168.63。所有符合此資格的 IP 位址都可被接受。
註: 如果您是在 inetd 或 xinetd 之類的超級伺服器上執行代理程式,請使用其他方法來控制存取權。您可能要使用防火牆、TCP Wrapper(hosts.allow 和 hosts.deny),或是 xinetd 的內建過濾功能。
bind
這項設定可讓使用者指定代理程式明確的連結位址。這項設定加上 "port" 設定會決定在以 -s 指令行選項啟動時,代理程式接聽連線的方式。bfagent.conf 檔中給定的值,會強制代理程式連結至 IPv4 本端主機位址;因此,代理程式只會從同一部電腦上的主控台接收連線。範例:bind 255.192.192.003
註: 它不會影響由系統的服務架構所啟動的 Windows 或 UNIX 代理程式,如:inetd、xinetd 或 launchd。
ccviewroot root-path
這項設定會指定這部主機的預設起始視圖。請參閱 ClearCase 文件,以取得 init 的詳細資訊。內部預設值如下所示:
  • 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
這項設定只能在設定 cygwin 時,用於 Windows 上的代理程式。

這項設定會指定 #! 字行,於執行步驟時使用。預設值是 #!/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 第 2 版 (SSLV2) 的密碼組合。預設值為 6321,可適用於大部分應用程式。如需相關資訊,請參閱 System z 文件。
gsk_ssl_cipher_v3 <seed>
要用於系統 SSL 第 3 版 (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

lang 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 使用者或管理者)來登入作業系統。您可以改用 magic_login 設定,來進行標準的系統鑑別。利用這項設定,系統可以透過單一使用者名稱與密碼來鑑別您的登入。

如果是以 root 或具有管理權的使用者來執行代理程式,會忽略這項設定,並嘗試正常的鑑別。

代理程式在執行任何指令時,所用的是啟動代理程式的使用者(而不是登入時所用的使用者名稱)的許可權。

這項設定只能用於以下情況:
  • 無法以管理專用權執行代理程式。例如,針對未使用 PAM 的 UNIX 系統使用這項設定。
  • 基於安全原則,不允許以管理專用權來執行代理程式。
如果要配置代理程式的登入資訊:
  1. 建立使用使用者名稱和密碼的伺服器鑑別。請在「管理主控台」中,按一下伺服器 > 伺服器鑑別
  2. 以本例來說,使用者名稱為 build,密碼為 MySecretPassword
  3. 建立使用代理程式的伺服器。請將伺服器鑑別與鑑別欄位中的這部伺服器相關聯。
  4. 為代理程式產生一個編碼密碼。在代理程式的安裝目錄中,使用您選擇的密碼執行 bfagent -P

    會傳回一個以 SMD5 雜湊編碼的密碼,如下所示:

    bfagent -P "MySecretPassword"
    eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
  5. BFAgent.conf 中,將 magic_login 設定為使用所需的使用者名稱與編碼密碼。
    magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
  6. 啟動代理程式。
  7. 測試伺服器連線。在伺服器中選取伺服器,然後按一下測試伺服器
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 與代理程式的虛擬終端機互動時,避免系統 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 作業系統對登入 Shell 和非登入 Shell 兩者都一律使用 /etc/profile Script。如果其行為不適用於代理程式,您可能需要變更 Script 的內容或使用另一個 Shell。

另請參閱 shellflag 設定。您可以使用旗標來變更登入 Script 的行為。

password_encrypt_module dll_path;conf_path
在代理程式上啟用 SSL 需要這項設定。其會指定 DLL 和配置檔的路徑。
  • dll_pathbfcrypt.dll 的路徑(其通常是 ./bfcyrpt.dll)。
  • conf_pathbfpwcrypt.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;如果無法判斷使用者的 Shell,則使用 /bin/sh。請注意,您不能在這項設定中指定參數,但您可以使用 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 需要這項設定。

該設定會變更指令 Script 傳給 Shell 的方式。通常 Script 會透過標準輸入來傳送:
   /bin/sh < /tmp/bfshellscript.sh
此設定會以參數形式傳遞 Script 加以執行:
/bin/sh /tmp/bfshellscript.sh
shellflag flag
這項設定只能用於在 UNIX 或 Linux 上執行的代理程式。

此設定會在 Shell 執行時新增旗標。但只能指定一個旗標。它通常用來停用 rc Script 處理,以便降低輸出或不需要的處理。範例:

  • csh 與衍生項:使用 shellflag -f 來停用 rc Script 處理。
  • bash:使用 shellflag –-noprofile 停用設定檔 Script 程序。
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 系統帳戶認證,且會忽略在存取及寫入網路共用檔案系統上的檔案時,所需的後續伺服器鑑別認證。
在使用伺服器鑑別認證再次向 Windows 鑑別之後,win_reexec_after_auth 會啟動新程序,並強制共用檔案系統辨識變更後的認證。
當您使用 win_reexec_after_auth 設定時,代理程式會當成服務來執行,而不會區別指令是否存取網路共用檔案,因此您可能需注意對效能的影響。
xstream_allow_ssl_mismatch
如果使用 OpenSSL 來編譯的代理程式與未使用 OpenSSL 來編譯的代理程式之間需要檔案傳送,則需要此設定。依預設,使用 OpenSSL 來編譯的代理程式需要 AES_CBC 加密的檔案傳送。除非使用此設定,否則它們會拒絕任何使用 PLAIN 或 PRNG 編碼所要求的檔案傳送。
xstream_bind ip_address
指定只用於直接檔案傳送的 IP 位址。接收檔案的代理程式必須可以存取此位址。依預設,代理程式會在所有網路介面上進行接聽。另請參閱連結
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 秒。

意見