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 情報タイプのアイテムがサポート対象外になる可能性があります(コマンドの結果を参照)。
この例では、Zabbixエージェントを実行するオペレーティングシステムアカウントに対して、MySQL接続認証情報が設定されていることを前提としています。たとえば、そのアカウントからアクセス可能なMySQLオプションファイルに設定します。

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

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

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

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] は、/etc/passwd 内で正規表現 root に一致する行数を返します。

コマンドの結果

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

テキスト(character、log、または text 型の情報)を返すアイテムは、標準エラー出力があっても未サポートにはなりません。

戻り値は 16MB に制限されます(切り捨てられる末尾の空白文字を含む)。また、データベースの制限 も適用されます。

テキスト(character、log、または text 型の情報)を返すユーザーパラメータは、空白文字のみを返すこともできます。 結果が無効な場合、アイテムは未サポートになります。