Referência do bfagent.conf

O arquivo bfagent.conf armazena as configurações de como o agente do Build Forge é executado. O arquivo está no mesmo diretório que o arquivo executável bfagent.

O arquivo lista todas as configurações e padrões internos. As configurações inativas são definidas como comentários.

Definições
activity_log caminho
Ativa a criação de log de atividades. As informações são anexadas ao arquivo especificado pelo caminho. O caminho deve existir e o usuário do agente deve ter permissão de gravação para ele.
Nota: O agente não reportará um erro se o caminho não existir ou ele não puder gravar no arquivo.
Importante: Não há limite para o tamanho do arquivo. O arquivo deve ser excluído manualmente. Essa configuração foi planejada para ser usada temporariamente na depuração do agente. Ela não foi planejada para ser um log permanente de um agente de trabalho.
permitir IP-address-or-range [...]
Use essa configuração somente nestas condições:
  • Agentes em execução no Windows
  • Agentes em execução no modo independente no UNIX ou Linux quando a opção -s na inicialização é usada

Essa configuração limita as conexões com o agente. São permitidas conexões apenas dos endereços IP que correspondem a IP-address-or-range. Por padrão, as conexões são permitidas a partir de todos os endereços.

Especifique um ou ambos os itens:
  • Endereço IP: um endereço IPv4 ou IPv6 completo. Por exemplo, para IPv4, 255.192.192.003. O endereço IP específico é permitido.
  • Variação de Endereços IP: um endereço IPv4 ou IPv6 parcial. Esses exemplos estão corretos para IPv4, 192.168 ou 192.168.63. Todos os endereços IP que correspondem com esta qualificação são permitidos.
Nota: Se você estiver executando o agente em um superservidor, como inetd ou xinetd, use outro método para controlar o acesso. Convém usar um firewall, wrappers TCP (hosts.allow e hosts.deny) ou o recurso xinetd de filtragem interna.
bind
Essa configuração permite ao usuário especificar um endereço de ligação explícita para o agente. Isso, com a configuração "port", determina como o agente atenderá às conexões quando iniciado com a opção da linha de comandos -s. O valor fornecido no arquivo bfagent.conf forçará o agente a ligar-se ao endereço do host local IPv4; assim, o agente só receberá conexões de um console que estiver no mesmo computador. Exemplo: bind 255.192.192.003
Nota: Não tem efeito sobre os agentes Windows ou UNIX iniciados pela arquitetura de serviço do sistema, como inetd, xinetd ou launchd.
ccviewroot root-path
Essa configuração especifica a raiz da visualização padrão para esse host. Consulte a documentação do ClearCase em init para obter mais informações. Os padrões internos são os seguintes:
  • Windows: ccviewroot M:
  • UNIX ou Linux: ccviewroot /view
cc_suppress_server_root
Se definido, então o caminho da visualização é o caminho definido por ccviewroot. Se não definido, o caminho definido na definição do servidor é anexado ao caminho definido por ccviewroot. Essa configuração não precisa de um valor. Se ela estiver presente em bfagent.conf, então ela é definida.
command_output_cache size
Essa configuração faz com que o agente armazene a saída em cache até que ele atinja o tamanho especificado em bytes. O padrão interno é não armazenar em cache. A utilização de uma cache pode melhorar significativamente o desempenho do agente e reduzir o tempo de processamento de rede. O tamanho do cache depende do número de saídas que os comandos produzem.

Valor mínimo: 2048. Um valor de 2048 será utilizado internamente se a configuração for menor que essa.

cygwin
Essa configuração é usada somente com agentes no Windows.

Essa configuração permite que o agente trabalhe em um host do Windows usando Cygwin, um ambiente semelhante ao Linux. Ao utilizar o Cygwin, várias ferramentas Linux estão disponíveis para o agente.

Ao usar essa configuração, será possível precisar definir cygwin_script_magic e as configurações de shell também. O exemplo mostra uma maneira de configurar essas definições:
cygwin
shell C:\cygwin\bin\bash.exe --login -c "%s"
cygwin_script_magic #!/bin/bash

A configuração do shell deve corresponder com a instalação do Cygwin.

cygwin_script_magic
Essa configuração é usada somente com agentes no Windows quando cygwin é definido.

Essa configuração especifica a linha #! a ser utilizada durante a execução das etapas. O padrão é #!/bin/bash.

default_logon_domain
Especifica o domínio a ser usado quando um pedido de autenticação não inclui um domínio. Se não estiver especificado, o domínio do computador agente será usado.
disable_telnet_support
Para obter melhores resultados, use telnet para testar a conexão do agente.
Para o agente, há sobrecarga de processamento integrado associada ao processamento e manipulação correta das seqüências de controle telnet.
Use essa configuração para desativar o agente da manipulação de códigos de caracteres telnet especiais, melhorando um pouco o desempenho. Em ambientes de produção, use essa configuração para aproveitar o desempenho melhorado.
disable_transcode
Desativa o processamento que o agente executa para converter dados internacionais quando o sistema operacional não está usando codificação UTF-8. Para evitar codificações mistas e danos aos dados, use UTF-8 para o sistema operacional do agente.
Se o sistema operacional não usar codificação UTF-8, o agente deverá converter os dados na codificação correta para as configurações de código de idioma do sistema operacional.
Se o sistema operacional não usar UTF-8, utilize essa configuração para obter melhores resultados e desempenho aprimorado do agente.
enable_agent_dll
Essa configuração permite rastreio do processo DLL, que é uma ferramenta de depuração.
env_recursion_limit number-of-recursions
Configura o limite de recursão de substituição de variável para pré-análise. Se não estiver configurado, o limite é 32.
extensões
Essa configuração especifica caminhos para bibliotecas externas de funções. As funções podem ser utilizadas como comandos com pontos em uma etapa. Se essa configuração não for especificada, as bibliotecas externas não serão carregadas.

Durante a análise, o primeiro token no comando da etapa é assumido como o nome da função. O segundo token é uma sequência, e o terceiro é um valor inteiro de tempo limite (em segundos).

Requisito: suporte de carregador dinâmico no sistema operacional. Por exemplo, no UNIX ou Linux, é necessário /usr/include/dlfcn.h. Esses valores padrão são usados internamente.
  • UNIX ou Linux: /usr/local/bin/bfextensions.so
  • Windows: C:\program files\ibm\build forge\agent\bfextensions.dll
getaddrinfo_using_addrconfig
Essa configuração é usada somente para executar o agente como um serviço independente nos sistemas operacionais UNIX ou Linux (bfagent -s). Esta configuração faz com que o agente utilize AI_ADDRCONFIG ao chamar getaddrinfo() para selecionar uma interface de atendimento. Por padrão, AI_ADDRCONFIG não é utilizado.

Se você usar essa configuração, o agente ignorará as interfaces que não possuam um endereço configurado corretamente. Ele atende apenas interfaces que possuem um endereço configurado apropriadamente.

gsk_ssl_key_location [ <kdb_path> | <SAF_specification> ]
Especifica um caminho completo para um arquivo kdb ou uma especificação de conjunto de chaves SAF.
gsk_ssl_kdb_password <senha>
Senha para o arquivo kdb. Pode ser em texto simples ou em texto criptografado. Use NULL se um conjunto de chaves SAF for utilizado. Use bfagent -e <plaintext> para criar a senha criptografada a partir de texto simples.
gsk_ssl_protocol <protocolo>
O protocolo que será usado, um de TODOS (o padrão), SSLV2, SSLV3, TLSV1 ou TLSV1_1
gsk_ssl_cipher_v2 <valor inicial>
O conjunto de cifras que será usado para SSL do sistema versão 2 (SSLV2). O valor padrão é 6321, que deverá servir para a maioria dos aplicativos. Consulte a documentação do System z para obter mais informações.
gsk_ssl_cipher_v3 <valor inicial>
O conjunto de cifras que será usado para SSL do sistema versão 3 (SSLV3). O valor padrão é 0906030201, que deverá servir para a maioria dos aplicativos. Consulte a documentação do System z para obter mais informações.
gsk_keyring_label <etiqueta>
A etiqueta principal no arquivo kdb.
gsk_password_encrypt [verdadeiro | falso]
Usado para se referir a uma senha criptografada. Se for configurado para verdadeiro, use bfagent -e <plaintext> para criar um valor criptografado e configurar gsk_ssl_kdb_password. É configurado para falso por padrão.
gsk_ssl_client_authentication [verdadeiro | falso]
Especifica se validar o certificado do cliente. O padrão é false
lang lang-code
Use essa configuração apenas quando o Console de Gerenciamento não fornecer um idioma válido.

Essa configuração especifica o idioma que o agente usa para gravar mensagens e a saída do comando. Normalmente, não está definido explicitamente porque o agente usa o idioma que o Console de Gerenciamento especifica. Entretanto, a configuração do idioma poderá ser útil se o código do idioma desejado não estiver disponível no computador. A configuração também é útil como backup, caso o Console de Gerenciamento falhe ao comunicar um idioma ou comunique um idioma inválido.

O padrão interno é en, como se fosse definido explicitamente da seguinte forma:

lang en
leave_tmp_file
Use essa configuração somente durante a resolução de problemas.

Essa configuração faz com que o arquivo temporário usado para manter comandos reserva seja retido, em vez de excluído após a execução do comando. Na resolução de problemas, o arquivo pode ser comparado com as etapas conforme elas são exibidas no Console de Gerenciamento.

Nota: Não use essa configuração para operações comuns.
locale locale-code.charset-code
Essa configuração é usada somente com sistemas operacionais UNIX e Linux. O Windows manipula os códigos dos idiomas de modos diferentes.

Essa configuração especifica o idioma e o conjunto de caracteres multibyte que os aplicativos localizados utilizam. Essa configuração funciona configurando a variável de ambiente LANG para o contexto do agente.

Para configurar o agente para tratar a saída do comando como UTF-8 do inglês americano, utilize o código do idioma UTF-8 para o sistema operacional. Por exemplo, no Linux, utilize a seguinte representação.
locale en_US.UTF-8

Para determinar a representação correta do código do idioma UTF-8 para seu sistema operacional, execute o comando locale -a.

Se essa configuração não for especificada, o agente usará o código do idioma do sistema operacional. Esta configuração é uma conveniência. Essa configuração é especialmente útil se o código do idioma padrão do sistema operacional não for o código do idioma que você deseja que o agente use. A configuração será útil especialmente se não for viável alterar o código do idioma do sistema para atender requisitos do agente.

magic_login user:encoded-password
O agente normalmente usa privilégios administrativos, como raiz ou admin, para efetuar logon no sistema operacional. A configuração magic_login é uma autenticação do sistema alternativa a padrão. Com essa configuração, o sistema pode autenticar seu login com um único nome de usuário e senha.

Se o agente for executado como o usuário raiz ou administrador, esta configuração será ignorada e uma autenticação normal será tentada.

O agente executa todos os comandos utilizando as permissões do usuário que iniciou o agente, não o nome de usuário utilizado para efetuar login.

Essa configuração é usada apenas nestas situações:
  • Quando não é possível executar o agente com privilégios administrativos. Por exemplo, use essa configuração com sistemas UNIX que não funcionam com PAM.
  • Quando a execução do agente com privilégios administrativos não é permitida por causa de políticas de segurança.
Para configurar um login para o agente:
  1. Crie uma autenticação de servidor que use um nome de usuário e senha. No Console de Gerenciamento, clique em Servidores > Autenticação de Servidor.
  2. Neste exemplo, o nome de usuário é build e a senha é MySecretPassword.
  3. Crie um servidor que utiliza o agente. Associe a autenticação do servidor a esse servidor no campo Autenticação.
  4. Gere uma senha codificada para o agente. No diretório de instalação do agente, execute bfagent -P com a senha escolhida.

    Uma senha codificada em hash SMD5 é retornada, conforme mostrado:

    bfagent -P "MySecretPassword"
    eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
  5. No BFAgent.conf, configure magic_login para utilizar o nome de usuário e senha codificada desejados.
    magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
  6. Inicie o agente.
  7. Teste a conexão do servidor. Em Servidores, selecione o servidor e, em seguida, clique em Servidor de Teste.
map drive-and-user-spec[; ...]
Essa configuração especifica uma unidade mapeada. Alguns sistemas poderão exigir mapeamentos de unidade. Por exemplo, um mapeamento de unidade poderá ser necessário porque um shell é executado de uma unidade compartilhada. Os mapeamentos especificados no agente são desempenhados antes dos mapeamentos especificados pelas variáveis de ambiente _MAP no Console de Gerenciamento. Esse exemplo ilustra dois mapeamentos de unidade:
map X:=//host1/share;Z:=//host2/share(username,password)
map_drive_is_failure
Quando especificada, essa configuração faz com que uma etapa falhe em encontrar uma especificação de unidade não mapeada, antes da execução da etapa. Se essa configuração não for especificada, as etapas irão ignorar as falhas de unidade e tentarão executar a etapa. Nesse caso, assegure-se de que a falha gere uma mensagem de erro significativa.
no_preparse_command
Essa configuração desativa a análise de expansão de variável que o agente normalmente executa em um comando antes de analisá-lo para o shell. Consulte também a variável de ambiente _NO_PREPARSE_COMMAND, a qual pode ser utilizada para um único projeto ou etapa.
no_pty
Essa configuração é usada somente com agentes que estão sendo executados em sistemas UNIX ou Linux.
Essa configuração pode ser usada para ajudar a impedir que o shell do sistema seja bloqueado quando interagir com o pseudoterminal do agente. Essa configuração normalmente é usada com HP-UX e z/OS. Você também pode usar dois outros métodos para ajudar a impedir esse tipo de bloqueio:
  • Usar um shell alternativo
  • Usar a configuração nologonshell.
A configuração no_pty desativa a alocação do pseudoterminal.
Nota: O uso de no_pty afeta alguns comandos. Por exemplo, o comando ls retorna a saída em uma única coluna, em vez de três. Se você usar essa configuração, teste exaustivamente antes de implementar a tarefa em um ambiente de produção.
nologonshell
Use essa configuração somente com agentes que estão sendo executados no UNIX ou no Linux.
Essa configuração faz com que o shell executado pelo agente seja um shell normal, não um shell de logon. Essa configuração é muitas vezes útil nestes casos:
  • Os shells de logon fornecem saída detalhada
  • Os shells de logon alteram as configurações do ambiente de maneira indesejada
  • Os shells de logon tentam se comunicar interativamente com o usuário

Quando definida, métodos padrão de solicitação para que seja usado shell normal, em vez de um shell de logon. Isso talvez não funcione em todas as plataformas e, nesses casos, a configuração shellflag poderá ser usada para passar sinalizadores ao shell para modificar seu comportamento.

Esses comportamentos não são desejáveis para o agente, pois ele é executado como um usuário sem ser um usuário interativo.
Nota: O sistema Mac OS X 10.5 usa /bin/bash, que não responde ao nologonshell. Use shellflag -l.
Nota: O sistema operacional z/OS sempre usa o script /etc/profile para shells de logon e não logon. Você poderá precisar alterar o conteúdo do script ou usar outro shell se seu comportamento não funcionar bem com o agente.

Consulte também a configuração shellflag. Sinalizadores podem ser usados para alterar o comportamento do script de logon.

password_encrypt_module dll_path;conf_path
Obrigatório para ativar o SSL no agente. Especifica caminhos para um arquivo de configuração e DLL.
  • dll_path é o caminho para bfcrypt.dll (normalmente, é ./bfcyrpt.dll).
  • conf_path é o caminho para bfpwcrypt.conf (normalmente, é ./bfcrypt.conf).
port port-number-or-range [...]
Essa configuração é usada somente com agentes que estão sendo executados no modo independente no UNIX ou Linux quando você emite a opção -s na inicialização.

Essa configuração especifica a porta que o agente usa para atender às conexões com o Console de Gerenciamento.

Especifica a porta que o agente utiliza para atender conexões com o Console de Gerenciamento.
Nota: A porta é configurada como 5555 por padrão. Para UNIX ou Linux, a configuração está em /etc/services.
read_timout
Tempo em segundos que o agente espera por uma solicitação até ser desconectado. O padrão é 1800 segundos (30 minutos). Configure o valor como 0 para desativar o tempo limite.

A diretiva ajuda a evitar que os contatos de conexão do cliente mantenham a porta aberta se uma solicitação de mecanismo legítima não for recebida. Algum software de varredura de porta de rede se comporta assim.

Não configure valores muito baixos para essa diretiva. O comportamento normal do mecanismo pode incluir diferenças de vários minutos entre as solicitações.

shell shell_name [options]
Essa configuração especifica o shell padrão. Os padrões internos são os seguintes:
  • Windows: shell cmd.exe /q /c "%s", a não ser que as seguintes configurações sejam utilizadas:
    • Se a configuração cygwin for utilizada, o padrão será shell C:\cygwin\bin\bash.exe --login -c "%s"
    • Se a configuração cygwin não for utilizada, o padrão será shell cmd.exe /u /q /c "%s"
  • UNIX ou Linux: o shell definido para a conta do usuário, ou /bin/sh, se o shell do usuário não puder ser determinado. Observe que não é possível especificar parâmetros nesta configuração, mas é possível utilizar a configuração shellflag para transmiti-los. O agente força automaticamente o padrão a ser um shell de logon inserindo um hífen. Por exemplo, /bin/ksh é enviado como -ksh. Se shell for explicitamente configurado, então nologonshell será implicitamente configurado. Consulte nologonshell.
  • System i: Configure o valor do shell para /bin/sh

É possível substituir essa configuração em uma etapa. Uma etapa que inicia com uma linha contendo #! substitui a configuração de shell e a configuração nologonshell é usada para executar os comandos da etapa.

shell_compatible_undef_vars
Essa configuração faz com que a representação de variáveis indefinidas seja uma sequência vazia. Se não for configurado, a representação será o nome da variável para variáveis no formato $VAR, ${VAR} ou %VAR% e a sequência vazia para $[VAR].
shellarg
Essa configuração é usada somente com agentes que estão sendo executados em UNIX ou Linux.

Utilize essa configuração se parecer que está havendo mistura de comandos. Alguns shells no Red Hat Linux Enterprise requerem essa configuração.

A configuração altera a forma que um script de comando é transmitido para o shell. Normalmente, o script é transmitido por meio da entrada padrão:
   /bin/sh < /tmp/bfshellscript.sh
Essa configuração faz com que os scripts sejam executados passando-os como parâmetros:
/bin/sh /tmp/bfshellscript.sh
shellflag flag
Essa configuração é usada somente com agentes que estão sendo executados em UNIX ou Linux.

Essa configuração inclui um sinalizador quando um shell está sendo executado. Apenas um sinalizador pode ser especificado. Normalmente, ele é usado para desativar o processamento do script rc para reduzir saída ou processamento indesejado. Exemplos:

  • csh e derivados: utilize shellflag -f para desativar o processamento do script rc.
  • bash: utilize shellflag –-noprofile para desativar o processamento do script de perfil.
ssl_ca_location caminho
Especifica o arquivo keystore que contém a autoridade de certificação. Se o agente for executado como um serviço, use um caminho absoluto.
ssl_cert_location caminho
Especifica o keystore que contém o certificado privado. Se o agente for executado como um serviço, use um caminho absoluto.
ssl_client_authentication [true | false]
Defina como true para exigir autenticação de cliente quando for feita uma conexão com o agente. Se true, o certificado do mecanismo do Build Forge deverá ser incluído no keystore da autoridade de certificação do agente.
ssl_cipher_group [grouplist | ALL]
Especifica grupos de códigos individuais a serem usados. Pode ser definido como ALL.
ssl_cipher_override códigos
Substitui o grupo de código. Especifique os códigos a serem usados.
ssl_key_location caminho
Especifica o arquivo keystore que contém a chave. Se o agente for executado como um serviço, use um caminho absoluto.
ssl_key_password senha
A senha da chave. Essa propriedade é armazenada em texto não criptografado por padrão. É possível configurar o agente para criptografar essa senha usando sua própria chave ou a chave do servidor Build Forge.
ssl_protocol protocolo
O protocolo handshake SSL a ser usado, um de SSL, SSLv2, SSLv3, SSL_TLS, TLS, TLSv1. O protocolo deve corresponder ao usado pelo servidor Build Forge.
update_path path
Essa configuração identifica o caminho completo para o executável do agente Build Forge. A configuração é estabelecida automaticamente durante a instalação. O diretório é um padrão para o sistema operacional ou o diretório de instalação especificado.
Nota: Essa configuração é ignorada em agentes do Windows. O caminho de atualização é obtido nas chaves de registro. As chaves são configuradas durante a instalação do agente.
win_reexec_after_auth
Inclua essa configuração se precisar executar comandos do agente em um sistema de arquivo de compartilhamento de rede usando as credenciais de autenticação do servidor Build Forge. Por exemplo, para modificar arquivos em uma visualização dinâmica do ClearCase, o agente deverá acessar os arquivos do ClearCase em um sistema de arquivo compartilhado em rede.
O agente Build Forge é inicializado com as credenciais de conta do sistema Windows. Para executar os comandos, o agente posteriormente será autenticado no Windows usando as credenciais de autenticação do servidor Build Forge.
Sem essa configuração, o compartilhamento de rede reconhece apenas as credenciais iniciais da conta do sistema Windows e ignora as credenciais de autenticação subsequentes do servidor que são necessárias para acessar e gravar em arquivos no sistema de arquivo de compartilhamento de rede.
O win_reexec_after_auth inicia um novo processo após autenticação novamente no Windows usando as credenciais de autenticação do servidor e força o sistema de arquivo compartilhado a reconhecer as credenciais alteradas.
Quando você usa a configuração win_reexec_after_auth, o agente é executado como um serviço e não distingue entre comandos que acessam arquivos de compartilhamento de rede e aqueles que não acessam, de modo que você talvez note um impacto no desempenho.
xstream_allow_ssl_mismatch
Requerida se a transferência de arquivos for necessária entre um agente compilado com OpenSSL e um agente compilado sem OpenSSL. Por padrão, os agentes compilados com OpenSSL requerem transferências de arquivos criptografadas com AES_CBC. Eles rejeitam as transferências de arquivos solicitadas usando a codificação PLAIN ou PRNG, a não ser que essa configuração seja usada.
xstream_bind ip_address
Especifica um endereço IP a ser usado apenas para transferências de arquivos diretas. O endereço deve ser acessível pelos agentes que recebem os arquivos. Por padrão, um agente atende em todas as interfaces de rede. Consulte também bind.
xstream_conn_timeout seconds
Tempo em segundos que um agente espera por uma conexão. O mecanismo deve encaminhar a solicitação de conexão para o agente de recebimento, que deve estabelecer uma conexão com o agente de envio dentro desse tempo. Por padrão, é configurado como 20 segundos.
xstream_listen_range port-range
O intervalo de portas que um agente atende para conexões. Essa configuração é útil quando há um firewall entre os hosts de conexão. O administrador do firewall pode configurar o firewall para permitir as portas permitidas para conexões, por exemplo, 22880-22889. O intervalo de portas padrão é 16384-32767. No entanto, se xstream_bind for usado e xstream_listen_randomize não for usado, o agente não especificará um intervalo e o sistema operacional determinará quais portas serão usadas.
xstream_listen_randomize
Causa seleção aleatória de uma porta dentro de xstream_port_range. Se não especificada, o agente iniciará a verificação pelo número de porta mais baixo. Essa configuração é bastante recomendada como medida de segurança.
xstream_recv_timeout seconds
Tempo de espera pela transferência de arquivos. Se durante qualquer momento na transferência de arquivos esse período passar sem que o agente de recebimento obtenha dados do agente de envio, a transferência falhará e a conexão será encerrada. O padrão é 20 segundos.
xstream_send_timeout seconds
Tempo de espera pela transferência de arquivos. Se durante qualquer momento na transferência de arquivos esse período passar sem que o agente de envio grave dados no agente de recebimento, a transferência falhará e a conexão será encerrada. O padrão é 20 segundos.

Feedback