Parametri utente

Panoramica

Un parametro utente consente di definire una chiave item personalizzata e il comando utilizzato per recuperarne il valore quando nessun item integrato dell'agent Zabbix fornisce i dati necessari. Un parametro utente è un comando definito dall'utente, a cui fa riferimento una chiave item definita dall'utente, ed eseguito dall'agent Zabbix quando viene verificato l'item corrispondente.

Nei sistemi UNIX, l'agent esegue i comandi dei parametri utente utilizzando /bin/sh, con l'account del sistema operativo che esegue l'agent (solitamente zabbix). Tale account deve disporre di autorizzazioni sufficienti per eseguire il comando e accedere a tutti i file, socket o credenziali utilizzati.

Esistono due tipi di parametri utente:

  • I parametri utente semplici non accettano argomenti; definiscono una chiave item fissa e un comando da eseguire.
  • I parametri utente flessibili accettano argomenti (specificati come parametri nella chiave item) e li passano al comando, consentendo a una singola definizione di servire più item.

Configurazione dei parametri utente

Un parametro utente viene definito utilizzando il parametro di configurazione UserParameter.

Un parametro utente ha la sintassi seguente:

UserParameter=<key>,<shell command>

dove:

  • <key> - una chiave item univoca che identifica il parametro utente.
    Quando si configura un item, specificare questa chiave per fare riferimento al comando definito dal parametro utente.
    Per un parametro utente semplice, la chiave è fissa e non accetta argomenti. Per un parametro utente flessibile, aggiungere [*] alla chiave (ad esempio, mysql.status[*]) per indicare che accetta argomenti. Specificare questi argomenti come parametri nella chiave item durante la configurazione dell'item. Il comando può fare riferimento ai parametri utilizzando i riferimenti posizionali $1–$9.
  • <shell command> - un comando shell o il percorso di uno script personalizzato che l'agent esegue per ottenere il valore dell'item.
    Per il parametro utente flessibile, il comando può utilizzare i riferimenti posizionali $1–$9 per fare riferimento ai parametri corrispondenti nella chiave item (ad esempio, UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2). Zabbix analizza i parametri racchiusi tra [] nella chiave item (ovvero mysql.status[zabbix,{$MYSQL.PASSWORD}]) e sostituisce di conseguenza i riferimenti posizionali nel comando.
    $0 viene sostituito con il comando originale prima dell'espansione dei riferimenti posizionali. I riferimenti posizionali vengono interpretati indipendentemente dal fatto che siano racchiusi tra virgolette doppie (") o singole ('). Per utilizzare i riferimenti posizionali senza sostituzione, specificare un doppio simbolo del dollaro. Ad esempio, awk '{print $$2}' passa $2 al comando senza modificarlo.
    Notare che i riferimenti posizionali preceduti da $ vengono cercati e sostituiti dall'agent Zabbix solo nei parametri utente flessibili. Per i parametri utente semplici, i riferimenti posizionali non vengono elaborati, quindi non è necessario eseguire l'escape di $.

Per impostazione predefinita, alcuni caratteri non possono essere passati come argomenti. Per l'elenco completo dei caratteri, vedere UnsafeUserParameters.

UserParameter deve essere configurato su ogni agent Zabbix che lo utilizza:

  • Direttamente nel file di configurazione dell'agent Zabbix (zabbix_agentd.conf o zabbix_agent2.conf).
  • In un file *.conf separato, a condizione che il file sia incluso dalla configurazione dell'agent.

È possibile definire più di un UserParameter per agent, poiché possono essere inclusi più file con set diversi di parametri. Ogni parametro utente deve avere una chiave item univoca all'interno dell'host monitorato.

Il parametro di configurazione UserParameterDir consente di specificare la directory di lavoro per l'esecuzione dei comandi UserParameter. Se configurato, l'agent cambia la directory di lavoro nella directory specificata prima di eseguire un comando. I comandi possono essere specificati utilizzando un percorso relativo con il prefisso ./, ad esempio, UserParameter=mykey,./myscript.sh.

Per configurare un parametro utente:

  1. Scrivere uno script o un comando personalizzato per recuperare i dati richiesti.
  2. Aggiungere il comando e la relativa chiave item univoca al parametro di configurazione UserParameter nel file di configurazione dell'agent Zabbix (zabbix_agentd.conf).

  3. Ricaricare i parametri utente dal file di configurazione eseguendo il comando di controllo runtime:

    zabbix_agentd -R userparameter_reload

    In alternativa, riavviare l'agent per applicare le modifiche alla configurazione.

  4. Creare un nuovo item sull'host monitorato con la chiave item definita in UserParameter.
    Impostare il tipo dell'item su Zabbix Agent o Zabbix Agent (active).
    Assicurarsi che il campo Type of information dell'item sia configurato correttamente; in caso contrario, Zabbix rifiuterà il valore restituito.

Vedere Estensione degli agent Zabbix per un esempio di configurazione e utilizzo dei parametri utente.

I parametri utente sono soggetti al timeout dei controlli dell'agent Zabbix. Se viene raggiunto il timeout, il processo che esegue il parametro utente viene terminato. Per ulteriori informazioni, vedere Esecuzione dei comandi.

Notare che gli script di lunga durata possono consumare risorse di sistema e ritardare altri controlli.

Risultato del comando

Il valore restituito dal comando è costituito dall'output standard e dall'errore standard prodotti dal comando.

I parametri utente che restituiscono testo (il tipo di informazione Character, Log o Text) possono restituire anche spazi bianchi. Se il comando produce un risultato non valido, l'item diventa non supportato. Tuttavia, un item con uno di questi tipi di informazione non diventa non supportato esclusivamente perché il comando produce un output sull'errore standard.

Il valore restituito dal comando è limitato a 16 MB, inclusi gli spazi bianchi finali, che vengono troncati. Questo limite si applica prima dei passaggi di preprocessing del valore dell'item. Si applicano anche i limiti del database.

Esempi di parametri utente

Questa sezione fornisce esempi di parametri utente semplici e flessibili.

Gli esempi riportati di seguito hanno esclusivamente scopo dimostrativo e non devono essere utilizzati in produzione senza adeguate misure di sicurezza. I parametri utente flessibili definiti utilizzando [*] accettano argomenti che possono introdurre rischi di command injection se non gestiti in modo sicuro.

Esempi di parametri utente semplici

Esempio 1: Valore costante

UserParameter=ping,echo 1

Un item con la chiave ping restituisce sempre 1.

Esempio 2: Disponibilità del server MySQL

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

Restituisce 1 se il server MySQL risponde e 0 in caso contrario. La redirezione 2>/dev/null scarta l'output degli errori standard di mysqladmin. Senza di essa, potrebbe essere restituito un messaggio di errore insieme a 0, facendo sì che un item con tipo di informazione Numeric diventi non supportato (vedere Risultato del comando).
Questo esempio presuppone che le credenziali di connessione a MySQL siano configurate per l'account del sistema operativo che esegue lo Zabbix agent, ad esempio in un file delle opzioni MySQL accessibile a tale account.

Esempi di parametri utente flessibili

Esempio 1: restituzione di un parametro

UserParameter=ping[*],echo $1

È possibile definire più item utilizzando questo parametro utente, con chiavi nel formato ping[parameter]:

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

Esempio 2: disponibilità di MySQL su un host specificato

Questo parametro può essere utilizzato per monitorare la disponibilità di un server MySQL su un host specificato.

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

L'item con la chiave mysql.ping[db1.example.com] restituisce 1 se il server MySQL su quell'host risponde e 0 in caso contrario.
Questo esempio presuppone che le credenziali di connessione a MySQL siano configurate per l'account del sistema operativo che esegue l'agent Zabbix, ad esempio in un file delle opzioni MySQL accessibile a tale account.

Esempio 3: conteggio delle righe corrispondenti a un pattern

Questo parametro può essere utilizzato per contare il numero di righe in un file.

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

Restituisce il numero di righe nel file specificato dal primo argomento che corrispondono all'espressione regolare specificata dal secondo argomento. Ad esempio, grep.count[/etc/passwd,root] restituisce il numero di righe in /etc/passwd che corrispondono all'espressione regolare root.