Parâmetros do usuário

Visão geral

Um parâmetro de usuário permite definir uma chave de item personalizada e o comando usado para obter seu valor quando nenhum item integrado do Zabbix agent fornece os dados necessários. Um parâmetro de usuário é um comando definido pelo usuário referenciado por uma chave de item definida pelo usuário e executado pelo Zabbix agent quando o item correspondente é verificado.

Em sistemas UNIX, o agent executa comandos de parâmetros de usuário usando /bin/sh, sob a conta do sistema operacional que executa o agent (geralmente zabbix). Essa conta deve ter permissões suficientes para executar o comando e acessar todos os arquivos, sockets ou credenciais utilizados por ele.

Há dois tipos de parâmetros de usuário:

  • Parâmetros de usuário simples não aceitam argumentos; eles definem uma chave de item fixa e um comando a ser executado.
  • Parâmetros de usuário flexíveis aceitam argumentos (especificados como parâmetros na chave do item) e os passam para o comando, permitindo que uma única definição seja usada por vários itens.

Configuração de parâmetros de usuário

Um parâmetro de usuário é definido usando o parâmetro de configuração UserParameter.

Um parâmetro de usuário tem a seguinte sintaxe:

UserParameter=<key>,<shell command>

onde:

  • <key> - uma chave de item exclusiva que identifica o parâmetro de usuário.
    Ao configurar um item, especifique essa chave para referenciar o comando definido pelo parâmetro de usuário.
    Para um parâmetro de usuário simples, a chave é fixa e não aceita argumentos. Para um parâmetro de usuário flexível, acrescente [*] à chave (por exemplo, mysql.status[*]) para indicar que ela aceita argumentos. Especifique esses argumentos como parâmetros na chave do item ao configurar o item. O comando pode referenciar os parâmetros usando referências posicionais $1–$9.
  • <shell command> - um comando de shell ou um caminho para um script personalizado que o agent executa para obter o valor do item.
    Para o parâmetro de usuário flexível, o comando pode usar referências posicionais $1–$9 para referenciar os parâmetros correspondentes na chave do item (por exemplo, UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2). O Zabbix analisa os parâmetros incluídos em [] na chave do item (ou seja, mysql.status[zabbix,{$MYSQL.PASSWORD}]) e substitui as referências posicionais no comando de acordo com eles.
    $0 é substituído pelo comando original antes que as referências posicionais sejam expandidas. As referências posicionais são interpretadas independentemente de estarem entre aspas duplas (") ou simples ('). Para usar referências posicionais sem substituição, especifique dois cifrões. Por exemplo, awk '{print $$2}' passa $2 para o comando sem alterações.
    Observe que as referências posicionais precedidas por $ são procuradas e substituídas pelo Zabbix agent somente em parâmetros de usuário flexíveis. Para parâmetros de usuário simples, as referências posicionais não são processadas; portanto, não é necessário escapar $.

Por padrão, determinados caracteres não podem ser passados como argumentos. Para obter a lista completa de caracteres, consulte UnsafeUserParameters.

UserParameter deve ser configurado em cada Zabbix agent que o utiliza:

É possível definir mais de um UserParameter por agent, pois vários arquivos podem ser incluídos com diferentes conjuntos de parâmetros. Cada parâmetro de usuário deve ter uma chave de item exclusiva dentro do host monitorado.

O parâmetro de configuração UserParameterDir permite especificar o diretório de trabalho para executar comandos UserParameter. Se configurado, o agent altera seu diretório de trabalho para o diretório especificado antes de executar um comando. Os comandos podem ser especificados usando um caminho relativo com o prefixo ./, por exemplo, UserParameter=mykey,./myscript.sh.

Para configurar um parâmetro de usuário:

  1. Escreva um script ou comando personalizado para recuperar os dados necessários.
  2. Adicione o comando e sua chave de item exclusiva ao parâmetro de configuração UserParameter no arquivo de configuração do agent do Zabbix (zabbix_agentd.conf).

  3. Recarregue os parâmetros de usuário do arquivo de configuração executando o comando de controle em tempo de execução:

    zabbix_agentd -R userparameter_reload

    Como alternativa, reinicie o agent para aplicar as alterações de configuração.

  4. Crie um novo item no host monitorado com a chave do item definida em UserParameter.
    Defina o tipo do item como Zabbix Agent ou Zabbix Agent (active).
    Certifique-se de que o Type of information do item esteja configurado corretamente; caso contrário, o Zabbix rejeitará o valor retornado.

Consulte Estendendo os Zabbix agents para ver um exemplo de configuração e uso de parâmetros de usuário.

Os parâmetros de usuário estão sujeitos ao tempo limite de verificação do Zabbix agent. Quando o tempo limite é atingido, o processo que executa o parâmetro de usuário é encerrado. Consulte Execução de comandos para obter mais informações.

Observe que scripts de longa duração podem consumir recursos do sistema e atrasar outras verificações.

Resultado do comando

O valor de retorno do comando consiste na saída padrão e no erro padrão produzidos pelo comando.

User parameters que retornam texto (o tipo de informação Character, Log ou Text) também podem retornar espaços em branco. Se o comando produzir um resultado inválido, o item se tornará sem suporte. No entanto, um item com um desses tipos de informação não se tornará sem suporte apenas porque o comando produz uma saída no erro padrão.

O valor de retorno do comando é limitado a 16 MB, incluindo os espaços em branco finais, que são truncados. Esse limite se aplica antes das etapas de pré-processamento do valor do item. Os limites do banco de dados também se aplicam.

Exemplos de parâmetros de usuário

Esta seção fornece exemplos de parâmetros de usuário simples e flexíveis.

Os exemplos abaixo são apenas para fins de demonstração e não devem ser usados em produção sem as devidas medidas de segurança. Os parâmetros de usuário flexíveis definidos usando [*] aceitam argumentos que podem introduzir riscos de injeção de comandos se não forem tratados com segurança.

Exemplos de parâmetros de usuário simples

Exemplo 1: Valor constante

UserParameter=ping,echo 1

Um item com a chave ping sempre retorna 1.

Exemplo 2: Disponibilidade do server MySQL

UserParameter=mysql.ping,mysqladmin ping 2>/dev/null | grep -c alive

Retorna 1 se o server MySQL responder e 0 caso contrário. O redirecionamento 2>/dev/null descarta a saída de erro padrão do mysqladmin. Sem ele, uma mensagem de erro poderia ser retornada junto com 0, fazendo com que um item com o tipo de informação Numeric se tornasse sem suporte (consulte Resultado do comando).
Este exemplo pressupõe que as credenciais de conexão do MySQL estejam configuradas para a conta do sistema operacional que executa o Zabbix agent, por exemplo, em um arquivo de opções do MySQL acessível a essa conta.

Exemplos de parâmetros de usuário flexíveis

Exemplo 1: Retornando um parâmetro

UserParameter=ping[*],echo $1

Você pode definir vários itens usando este parâmetro de usuário, com chaves no formato ping[parameter]:

  • ping[0] - retorna 0.
  • ping[hello] - retorna hello.

Exemplo 2: Disponibilidade do MySQL em um host especificado

Este parâmetro pode ser usado para monitorar a disponibilidade de um server MySQL em um host especificado.

UserParameter=mysql.ping[*],mysqladmin -h "$1" ping 2>/dev/null | grep -c alive

O item com a chave mysql.ping[db1.example.com] retorna 1 se o server MySQL nesse host responder e 0 caso contrário.
Este exemplo pressupõe que as credenciais de conexão do MySQL estejam configuradas para a conta do sistema operacional que executa o Zabbix agent, por exemplo, em um arquivo de opções do MySQL acessível a essa conta.

Exemplo 3: Contagem de linhas que correspondem a um padrão

Este parâmetro pode ser usado para contar o número de linhas em um arquivo.

UserParameter=grep.count[*],grep -c "$2" "$1"

Retorna o número de linhas no arquivo especificado pelo primeiro argumento que correspondem à expressão regular especificada pelo segundo argumento. Por exemplo, grep.count[/etc/passwd,root] retorna o número de linhas em /etc/passwd que correspondem à expressão regular root.