ユーザーパラメーター

概要

ユーザーパラメータを使用すると、必要なデータを提供する組み込みのZabbixエージェントアイテムがない場合に、カスタムアイテムキーと、その値を取得するために使用するコマンドを定義できます。 ユーザーパラメータは、ユーザー定義のアイテムキーから参照されるユーザー定義コマンドであり、対応するアイテムのチェック時にZabbixエージェントによって実行されます。

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

ユーザーパラメータには、次の2種類があります。

  • 単純ユーザーパラメータは引数を受け付けず、固定のアイテムキーと実行するコマンドを定義します。
  • 柔軟なユーザーパラメータは引数（アイテムキーのパラメータとして指定）を受け付け、それらをコマンドに渡します。これにより、1つの定義で複数のアイテムに対応できます。

ユーザーパラメータの設定

ユーザーパラメータは、UserParameter 設定パラメータを使用して定義します。

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

UserParameter=<key>,<shell command>

ここで、

  • <key> - ユーザーパラメータを識別する一意のアイテムキー。
    アイテムを設定する際に、このキーを指定してユーザーパラメータで定義したコマンドを参照します。
    シンプルなユーザーパラメータの場合、キーは固定され、引数を受け付けません。 フレキシブルなユーザーパラメータの場合、キーに [*] を追加して（例: mysql.status[*]）、引数を受け付けることを示します。 アイテムの設定時に、アイテムキーのパラメータとしてこれらの引数を指定します。 コマンドでは、位置参照 $1～$9 を使用してパラメータを参照できます。
  • <shell command> - アイテムの値を取得するためにエージェントが実行するシェルコマンドまたはカスタムスクリプトへのパス。
    フレキシブルなユーザーパラメータの場合、コマンドでは位置参照 $1～$9 を使用して、アイテムキー内の対応するパラメータを参照できます（例: UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2）。 Zabbixは、アイテムキー内の [] で囲まれたパラメータ（例: mysql.status[zabbix,{$MYSQL.PASSWORD}]）を解析し、それに応じてコマンド内の位置参照を置き換えます。
    位置参照が展開される前の元のコマンドには、$0 が置き換えられます。 位置参照は、二重引用符（"）または単一引用符（'）で囲まれているかどうかにかかわらず解釈されます。 置換せずに位置参照を使用するには、ドル記号を2つ指定します。 例えば、awk '{print $$2}' と指定すると、$2 が変更されずにコマンドへ渡されます。
    $ が前に付いた位置参照は、フレキシブルなユーザーパラメータの場合にのみZabbixエージェントによって検索および置換されることに注意してください。 シンプルなユーザーパラメータでは位置参照は処理されないため、$ をエスケープする必要はありません。

デフォルトでは、引数として渡せない文字があります。 文字の完全な一覧については、UnsafeUserParametersを参照してください。

UserParameter は、それを使用する各Zabbixエージェントで設定する必要があります。

  • Zabbix エージェント設定ファイル（zabbix_agentd.conf または zabbix_agent2.conf）に直接設定する。
  • 別の *.conf ファイルに設定する。ただし、そのファイルがエージェント設定によってインクルードされている必要があります。

複数のファイルに異なるパラメータセットを指定してインクルードできるため、1つのエージェントに複数の UserParameter を定義できます。 監視対象のホスト内で、各ユーザーパラメータには一意のアイテムキーを指定する必要があります。

UserParameterDir 設定パラメータを使用すると、UserParameter コマンドを実行する作業ディレクトリを指定できます。 設定されている場合、エージェントはコマンドを実行する前に、指定されたディレクトリへ作業ディレクトリを変更します。 コマンドには、./ プレフィックスを付けた相対パスを指定できます。例えば、UserParameter=mykey,./myscript.sh のように指定します。

ユーザーパラメータを設定するには、次の手順に従います。

  1. 必要なデータを取得するカスタムスクリプトまたはコマンドを作成します。
  2. コマンドとその一意のアイテムキーを、Zabbix エージェント設定ファイル（zabbix_agentd.conf）の UserParameter 設定パラメータに追加します。

  3. ランタイムコントロールコマンドを実行して、設定ファイルからユーザーパラメータを再読み込みします。

    zabbix_agentd -R userparameter_reload

    または、エージェントを再起動して設定変更を適用します。

  4. UserParameter で定義したアイテムキーを使用して、監視対象のホストに新しいアイテムを作成します。
    アイテムのタイプを Zabbix Agent または Zabbix Agent (active) に設定します。
    アイテムの Type of information が正しく設定されていることを確認してください。正しく設定されていない場合、Zabbixは返された値を拒否します。

ユーザーパラメータの設定および使用例については、Zabbixエージェントの拡張を参照してください。

ユーザーパラメータには、Zabbixエージェントのチェックタイムアウトが適用されます。 タイムアウトに達すると、ユーザーパラメータを実行しているプロセスは終了します。 詳細については、コマンドの実行を参照してください。

実行時間の長いスクリプトはシステムリソースを消費し、他のチェックを遅延させる可能性があることに注意してください。

コマンドの結果

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

テキスト（Character、Log、または Text タイプの情報）を返すユーザーパラメータは、空白文字も返すことができます。 コマンドが無効な結果を生成した場合、アイテムはサポート対象外になります。 ただし、これらの情報タイプのいずれかを持つアイテムは、コマンドが標準エラーに出力を生成しただけではサポート対象外になりません。

コマンドの戻り値は、末尾の空白文字を含めて16 MBに制限され、超過分は切り捨てられます。 この制限は、アイテム値の前処理の手順より前に適用されます。 データベースの制限も適用されます。

ユーザーパラメータの例

このセクションでは、単純なユーザーパラメータと柔軟なユーザーパラメータの例を示します。

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

単純なユーザーパラメータの例

例 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=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 内の行数を返します。