5 ユーザーパラメーター

概要

Zabbix にあらかじめ定義されていないエージェントチェックを実行したい場合があります。 このような場合に役立つのがユーザーパラメータです。

必要なデータを取得するコマンドを記述し、エージェント設定ファイル（UserParameter 設定パラメータ）のユーザーパラメータに含めることができます。

ユーザーパラメータの構文は次のとおりです。

UserParameter=<key>,<command>

ご覧のとおり、ユーザーパラメータにはキーも含まれます。 アイテムを設定するときに、このキーが必要になります。参照しやすい任意のキーを入力してください（ホスト内で一意である必要があります）。

エージェントを再起動するか、エージェントのランタイムコントロールオプションを使用して新しいパラメータを読み込みます。例：

zabbix_agentd -R userparameter_reload

その後、アイテムを設定するときに、実行するユーザーパラメータのコマンドを参照するキーを入力します。

ユーザーパラメータは、Zabbix エージェントによって実行されるコマンドです。 アイテム値の前処理の手順が実行される前に、最大 16MB のデータを返すことができます。

UNIX システムでは、エージェントはエージェントを実行しているオペレーティングシステムのアカウント（通常は zabbix）で、/bin/sh を使用してユーザーパラメータのコマンドを実行します。 このアカウントには、コマンドの実行、およびコマンドが使用するファイル、ソケット、認証情報へのアクセスに必要な権限が付与されている必要があります。

ユーザーパラメータには、エージェントチェックのタイムアウトが適用されます。タイムアウトに達すると、フォークされたユーザーパラメータプロセスは終了します。

関連項目：

シンプルなユーザーパラメータの例

例 1: 固定値

UserParameter=ping,echo 1

キー ping のアイテムは常に 1 を返します。

例 2: MySQLサーバーの可用性

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

MySQLサーバーが応答した場合は 1 を、それ以外の場合は 0 を返します。 2>/dev/null リダイレクトは、mysqladmin の標準エラー出力を破棄します。 これがない場合、0 とともにエラーメッセージが返され、Numeric 情報タイプのアイテムがサポートされない状態になる可能性があります（コマンドの結果を参照）。
この例では、MySQLへの接続認証情報が、Zabbixエージェントを実行するオペレーティングシステムアカウント用に設定されていることを前提としています。たとえば、そのアカウントからアクセスできるMySQLオプションファイルに設定します。

柔軟なユーザーパラメータ

柔軟なユーザーパラメータは、キーにパラメータを指定できます。この方法により、 1つの柔軟なユーザーパラメータを基に複数のアイテムを作成できます。

柔軟なユーザーパラメータの構文は次のとおりです。

UserParameter=key[*],command
パラメータ 説明
Key 一意のアイテムキー。[*] は、このキーが角括弧内のパラメータを受け付けることを定義します。
パラメータは、アイテムの設定時に指定します。
Command キーの値を評価するために実行するコマンド。
柔軟なユーザーパラメータの場合のみ:
コマンド内で位置参照 $1…$9 を使用して、アイテムキー内の対応するパラメータを参照できます。
Zabbixは、アイテムキーの [ ] 内に含まれるパラメータを解析し、それに応じてコマンド内の $1,...,$9 を置換します。
$0 は、実行される元のコマンド（$0,...,$9 の展開前）に置換されます。
位置参照は、二重引用符（"）または単一引用符（'）で囲まれているかどうかにかかわらず解釈されます。
位置参照をそのまま使用するには、ドル記号を2つ指定します。たとえば、awk '{print $$2}' のように指定します。この場合、コマンドの実行時に $$2 は実際には $2 に変換されます。

$ 記号を使用した位置参照の検索と置換は、柔軟なユーザーパラメータの場合にのみZabbixエージェントによって実行されます。 単純なユーザーパラメータでは、このような参照の処理はスキップされるため、$ 記号をエスケープする必要はありません。

デフォルトでは、ユーザーパラメータに使用できない文字があります。 使用できない文字の完全な一覧については、UnsafeUserParametersを参照してください。

柔軟なユーザーパラメータの例

以下の例は説明を目的としたものであり、適切な安全対策なしに本番環境で使用しないでください。 [*] を使用して定義された柔軟なユーザーパラメータは、安全に処理しない場合、コマンドインジェクションのリスクをもたらす引数を受け入れます。

例1: パラメータを返す

UserParameter=ping[*],echo $1

このユーザーパラメータを使用して、キーを ping[parameter] 形式にした複数のアイテムを定義できます。

  • ping[0] - 0 を返します。
  • ping[hello] - hello を返します。

例2: 指定したホスト上のMySQLの可用性

このパラメータを使用すると、指定したホスト上のMySQLサーバーの可用性を監視できます。

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

キー mysql.ping[db1.example.com] のアイテムは、そのホスト上のMySQLサーバーが応答する場合は 1 を返し、それ以外の場合は 0 を返します。
この例では、MySQLへの接続に必要な認証情報が、Zabbixエージェントを実行するオペレーティングシステムアカウント用に設定されていることを前提としています。たとえば、そのアカウントからアクセス可能なMySQLオプションファイルに設定します。

例3: パターンに一致する行のカウント

このパラメータを使用すると、ファイル内の行数をカウントできます。

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

最初の引数で指定したファイル内で、2番目の引数で指定した正規表現に一致する行数を返します。 たとえば、grep.count[/etc/passwd,root] は、正規表現 root に一致する /etc/passwd 内の行数を返します。

コマンド結果

コマンドの戻り値は、標準出力とコマンドによって生成された標準エラー出力です。

テキスト（文字、ログ、またはテキスト型の情報）を返すアイテムは、標準エラー出力があってもサポート対象外にはなりません。

戻り値は 16MB に制限されます（末尾の空白は切り捨てられます）。データベースの制限 も適用されます。

テキスト（文字、ログ、またはテキスト型の情報）を返すユーザーパラメータは、空白も返すことがあります。 無効な結果の場合、アイテムはサポート対象外になります。