Zabbix APIでラクにミスなく大量のホストを登録しよう！

2019年8月6日Zabbix, Zabbix API

はじめまして。プラットフォーム技術部の近藤です。

皆さんはZabbixで監視設定をするとき、通常はZabbixの画面から設定しますよね。でも「ホストを300台追加する」という場合はどうでしょう。ひとつひとつ手で入力していくのは大変だな…と思いませんか？単純な手作業の繰り返しになるので、うっかり設定ミスしそうな気もします。

そんなときはZabbix APIを上手に活用することで、Zabbixの画面で手作業の設定をすることなく、大量の監視設定を流し込むことができます。

今回は、Zabbixの基本的な使い方や簡単なシェルスクリプトの書き方は知っているけれど、まだZabbix APIは使ったことがない方向けに、Zabbix APIを使って大量の監視対象ホストを登録する方法(ついでにAPIでホストグループを登録する方法)を解説します。

「認証トークン取得」「監視設定の順序」「ホストグループのID変換」の部分が、手作業でWeb画面から登録するのとは違うため、分かりづらく、引っ掛かりやすいポイントです。注意して読んでみてください。

Contents

1. Zabbix APIって？
2. 今回のゴール
- 2.1. 作るもの
- 2.2. 設定するもの
3. 事前準備
4. Zabbix APIを使ってみよう
5. 今回のポイント
6. まとめ

Zabbix APIって？

「監視データを見る」「監視対象ホストを登録する」といった操作を、Zabbixの画面を使わずにプログラムで行うための窓口、それがZabbix APIです。

ZabbixはWeb APIであり、Zabbix2.0以降ではWebフロントエンド(Apacheなど)が起動していれば利用可能です。JSON-RPC2.0プロトコルを使ってZabbixのデータを参照したり更新したりします。

そしてZabbix APIにはたくさんのメソッドが揃っています。以下はほんの一例です。

host.get
- ホストの情報を取得するメソッド
host.create
- ホストを作成するメソッド
host.delete
- ホストを削除するメソッド

これらのメソッドを使うことで、ZabbixのWeb画面を使用せずに、Zabbixの設定の変更や収集している監視データの参照などの操作ができます。

どのようなメソッドがあるのかは、公式のドキュメンテーションのリファレンスに書いてあります。今回作るスクリプトを応用して、いろいろ作ってみたくなった方はご覧ください。

Method reference [Zabbix Documentation 4.0]

Method reference [Zabbix Documentation 4.0] skip to content Zabbix Documentation 4.0 3.0 4.0 4.2 ...

https://www.zabbix.com/documentation/4.0/manual/api/referenc...

今回のゴール

作るもの

ホストグループやホスト設定を登録するために必要な情報を列挙したリストファイルから情報を読み取り、Zabbix APIを呼び出して一括追加する処理をシェルスクリプトで作成します。イメージはざっくりとこんな感じ。

これを作っておけば、以降は都度リストファイルを差し替えるだけでホストグループやホストを一括登録できるようになるので手間が省けますし、Zabbix APIの他のメソッドを使って各種監視設定を実装したい場合のテンプレートとしても活用できるようになります。

設定するもの

3つのホストグループに各100台ずつ、合計300台のホストを追加します。ホストグループとホストの関係は下記のとおりです。

今回追加するホストとホストグループの関係 — 今回追加するホストグループとホストの関係

事前準備

検証環境

CentOS 7.5にZabbix4.0をインストールした環境を使います。

環境構築の手順はここでは割愛します。Zabbix4.0のインストール手順は下記の公式サイトにも載っていますので、参考にしてみてください。

1 Red Hat Enterprise Linux/CentOS [Zabbix Documentation 4.0]

1 Red Hat Enterprise Linux/CentOS [Zabbix Documentation 4.0] skip to content Zabbix Documentatio ...

https://www.zabbix.com/documentation/4.0/manual/installation...

作業ユーザー

作業に使うOSのユーザーは、rootです。

Zabbix APIの認証は、Zabbix上のユーザーであるAdminを利用します。

ディレクトリ構成

今回は分かりやすくするために、シェルスクリプトやリストファイルはすべて同じディレクトリに配置することにします。

私は/work/ZabbixAPITestというディレクトリを作り、そこにスクリプトやリストファイルを作りました。

スクリプト・リストファイル

以降では、順を追って下記のスクリプト・リストファイルの書き方・使用方法を解説します。

zabbix_token_get.sh
- 認証トークンを取得するスクリプト
hostgroup_create_list
- ホストグループのリストファイル
hostgroup_create.sh
- ホストグループを追加するスクリプト
host_create_list
- ホストのリストファイル
hostgroup_name_to_ID.sh
- ホストグループ名をホストグループIDに変換するスクリプト
host_create.sh
- ホストを追加するスクリプト

Zabbix APIを使ってみよう

Zabbix APIがどんなものなのかイメージはついたと思いますが、公式リファレンスを読んでも説明が少ない上に日本語翻訳がされていなかったりするので、初心者にはわかりづらいと思います。

なので、まずはじめにZabbix APIにおいて基本かつ必須となる認証トークンの取得方法について説明します。

認証トークンの取得

Zabbix APIでZabbix内のデータを参照したり更新したりするには、「認証トークン」が必要です。

いきなり聞き慣れない言葉が出てきましたね。ここでの「認証トークン」とは何かを簡単に説明すると「Zabbix APIで、ユーザーのIDとパスワードでログイン認証する代わりに必要な32文字の文字列」で、Zabbix APIの「user.loginメソッド」を使って取得します。

通常は、ZabbixのWeb画面にブラウザでアクセスして、ユーザーIDとパスワードを画面入力してログイン認証し、Zabbixの監視設定画面にアクセスしますよね。Zabbix APIではユーザーのIDとパスワードを入力する代わりに、JSONクエリの ”auth”パラメーターにユーザーの認証トークンを指定することで「このユーザーでログインして操作しますよ」という認証をしているイメージです。

認証トークン取得コマンドを取得してみる

今回はZabbixにデフォルトで存在する最高権限のユーザー「Admin」の認証トークンを取得します。curlコマンドでJSONクエリを投げます。そして前述のとおり、Zabbix APIのuser.loginメソッドを使います。

Zabbixサーバーにrootでログインし、下記のコマンドを実行します。(Adminのパスワード、ZabbixサーバーのIPアドレスは環境に合わせてください。)

curl -s -d '{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "user": "Admin",
        "password": "Adminのパスワード"
    },
    "id": 1,
    "auth": null
}' -H "Content-Type: application/json-rpc" http://ZabbixサーバーのIPアドレス/zabbix/api_jsonrpc.php

すると、こんな結果が返ってきます。

{"jsonrpc":"2.0","result":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","id":1}

“result”パラメーターに返ってきた32文字の文字列が、このZabbixのAdminユーザーの認証トークンです。Zabbix APIをのメソッドを呼び出してAdminユーザーで使うときは、この認証トークンを”auth”パラメーターに入力する必要があります。

認証トークン取得スクリプト

ここで1つ目のポイントです。

【ポイント１】認証トークン取得スクリプトを作っておくと便利！

前項では認証トークンの取得をcurlコマンドで行いました。でも、Zabbix APIを呼び出す毎に認証トークンをJSONクエリの中にコピー＆ペーストするのって、手間ですよね。

なので、認証トークンだけが実行結果として標準出力されるzabbix_token_get.shを作っておくと便利です。後述のホストグループ追加スクリプトやホスト追加スクリプトでも使いまわしできます。

zabbix_token_get.sh

下記はAdminユーザーの例ですが、"user"パラメータ、"password"パラメータを変えれば他のユーザーの認証トークンも取得できます。

#!/bin/bash
 
#########################################
## Zabbix token get                    ##
#########################################
 
curl -s -d '{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "user": "Admin",
        "password": "Adminのパスワード"
    },
    "id": 1,
    "auth": null
}' -H "Content-Type: application/json-rpc" http://ZabbixサーバのIPアドレス/zabbix/api_jsonrpc.php | gawk -F'"' '{print $8}'

実行結果

実行するとこうなります。

[root@zabbixserver]# ./zabbix_token_get.sh
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx　　　←認証トークンの文字列

ホストグループの追加

Zabbixでは、監視対象ホスト作成時に所属先ホストグループを1つ以上選択しなければならないという決まりがありますね。これは言い換れば「ホストを作成するときにはあらかじめ所属先ホストグループを作成しておく必要がある」ということです。ホスト作成時に所属先ホストグループがないとエラーになってしまいホストを登録できません。

ですから、あらかじめ所属先のホストグループを作成してからホストを追加する、という設定順序にします。これが２つ目のポイントです。

【ポイント２】API使用時はホストグループ→ホストの順で設定する！

※Web画面上から監視対象ホストを登録する場合は、ホスト作成とホストグループ作成がいっぺんにできるので、気にする必要はありません。Zabbix APIを使用する場合は順序に気をつけてください。

ホストグループ追加スクリプト

ということで、ホストグループを追加するシェルスクリプトを作ります。

「ホストグループ3個だけだし手動設定じゃダメなの？」という声が聞こえてきそうですが、実際の監視設定ではもっとたくさんのホストグループを追加する場合もありますし、APIを使う練習を兼ねてシェルスクリプトにします。

ホストグループを追加するのはhostgroup.createメソッド。公式のドキュメンテーションではこのページに使用例が書かれています。今回はホストグループ名のリストファイルを作って、それを一行ずつ読み込んでホストグループを作成するスクリプトを書きます。

hostgroup_create_list

追加するホストグループを一行ずつ書きます。

Test_Linux_Servers
Test_Windows_Servers
Test_Network_Devices

hostgroup_create.sh

hostgroup_create_listからホストグループ名を読み込んで、Zabbix APIのhostgroup.createメソッドの”name”パラメーターに渡し、繰り返しホストグループの追加を行うシェルスクリプトです。

20行目のauth=～では、先ほど作ったzabbix_token_get.shを使って認証トークンを取得しています。

#!/bin/bash
#####################################################################################
### ファイルから読み取ったホストグループを作成する                                    ###
#####################################################################################
### 使い方
###  ./hostgroup_create.sh "読み込むファイル"
###
### 使用例
###  ./hostgroup_create.sh "/work/ZabbixAPITest/hostgroup_create_list"
###
#####################################################################################
### 変数定義                                                                      ###
#####################################################################################
####ZabbixWeb画面のURL。環境に合わせて要修正
ZabbixWeb=http://ZabbixサーバーのIPアドレス/zabbix/
###ZabbixAPIの認証
auth=`bash zabbix_token_get.sh`
###csv読み取りのための設定。修正不要
PRE_IFS=$IFS
IFS=$'\n'
#####################################################################################
###csvから一行ずつ読み取る
for line in `cat "$1" | grep -v ^#`
do
  HostGroupName=`echo ${line} | cut -d ';' -f 1`
### ホストグループを追加する
curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "hostgroup.create",
    "params": {
        "name": "'$HostGroupName'"
    },
    "auth": "'${auth}'",
    "id": 1
}
' -H "Content-Type: application/json-rpc" ${ZabbixWeb}api_jsonrpc.php
 echo ""
done
IFS=$PRE_IFS

実行結果

ではこのスクリプトを実行してみます。下記のように引数でホストグループのリストのファイル名を指定すると…

[root@zabbixserver]# ./hostgroup_create.sh "/work/ZabbixAPITest/hostgroup_create_list"
{"jsonrpc":"2.0","result":{"groupids":["20"]},"id":1}
{"jsonrpc":"2.0","result":{"groupids":["21"]},"id":1}
{"jsonrpc":"2.0","result":{"groupids":["22"]},"id":1}

ホストグループ追加が成功しました！Zabbixの画面上でも、追加した3つのホストグループが確認できます。

※ちなみに追加に失敗した場合は”error”が返ってきます。以下は”Test_Linux_servers”というホストがすでに存在しているので追加できませんでした、というエラーです。

{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params.","data":"Host group \"Test_Linux_Servers\" already exists."},"id":1}

ホストグループ追加スクリプトを使って設定流し込みができました。このスクリプトがあればホストグループが1000個あったとしても、コマンドひとつで設定できちゃいますね。

ホストの追加

続いて、ホスト追加スクリプトを作ります。

ホストを追加するのはhost.createメソッド。公式ではこのページに使用例が書かれています。ホストグループの追加スクリプトと同じように、リストファイルを読み込んで繰り返しホストを追加していくことにします。

host_create_list

ホストの情報を列挙したリストを作ります。

ホストグループ作成の際はホストグループ名だけ指定すれば良いのですが、ホスト作成は設定必須のパラメーターが複数あるため、それを踏まえてリストファイルを作ります。必須のパラメーターは公式のAPIリファレンスに書いてあるので詳しく知りたい方は読んでみてください。

Test_Linux_Servers;Test_Lin_00;1;1;1;192.168.60.101;;10051
Test_Linux_Servers;Test_Lin_01;1;1;1;192.168.60.102;;10051
Test_Linux_Servers;Test_Lin_02;1;1;1;192.168.60.103;;10051
Test_Linux_Servers;Test_Lin_03;1;1;1;192.168.60.104;;10051
Test_Linux_Servers;Test_Lin_04;1;1;1;192.168.60.105;;10051
Test_Linux_Servers;Test_Lin_05;1;1;1;192.168.60.106;;10051
～～以下略～～

パラメーターの意味は、左から順に下記の通りとなります。各パラメーターの数字の意味など詳しくはAPIリファレンスを参照ください。

ホストグループ名
- 監視対象ホストを所属させるホストグループ名を記載する。
ホスト名
- 監視対象ホストの名前を記載する。
インターフェースタイプ
- 1:Zabbixエージェント、2:SNMP、3:IPMI、4:JMX
インターフェースをデフォルトで使用するか否か？
- 0:使用しない、1:使用する。
接続にDNSとIPアドレスのどちらを使用するか？
- 0:DNSに接続して監視を行う、1:IPアドレスで監視を行う。
IPアドレス
- 「接続にDNSとIPアドレスのどちらを使用するか？」で「1」を選択した場合、ここにホストのIPアドレスを記述する。
ホストのDNS名
- 接続にDNSとIPアドレスのどちらを使用するか？」で「0」を選択した場合、ここにホストのDNS名を記述する。今回は使用しないのでなにも設定しない。
インターフェースが使用するポート
- Zabbixエージェントで監視する場合は「10051」を指定する。SNMPの監視は「161」。

※パラメータの区切り文字は「;」にします。理由は、カンマやスペースといった区切り文字はIPアドレスやホスト名などに含まれることがあり、うまく区切れないためです。

※リストファイルの作り方はいろいろありますが、私はExcelとフリーのテキストエディタ(サクラエディタ)を使いました。Excelに設定値を列挙して選択・コピーし、サクラエディタにペーストして、タブを「;」に置換します。

ホストグループID変換スクリプト

ここで３つ目のポイントです。

【ポイント３】ホストグループID変換スクリプトを作っておくと便利！

公式のAPIリファレンスに書かれている通り、host.createメソッドでホストを追加する際には、ホストグループ名での指定はできません。ホストグループIDを指定する必要があります。

ホストグループIDとは、Zabbixがホストグループを内部的に管理するために割り振られている番号です。Web画面には表示されない番号なので馴染みがないかもしれませんが、hostgroup.getメソッドを使うとホストグループ名に対応するホストグループIDがわかります。

※ちなみに、ホストグループIDはWeb画面のURLから推測したりデータベースを参照するといった方法でも確認できます。でもあまりスマートではないので、やはりAPIを使うのが良いと思います。

hostgroup_name_to_ID.sh

ホストグループの情報を取得できるhostgroup.getメソッドを使い、ホストグループ名をホストグループIDに変換するスクリプトhostgroup_name_to_ID.shを作ります。

#!/bin/bash
 
#####################################################################################
### ホストグループ名をホストグループIDに変換する                                      ###
#####################################################################################
### 使い方
###  ./hostgroup_name_to_ID.sh "ホストグループ名"
###
### 使用例
###  ./hostgroup_name_to_ID.sh "Zabbix servers"
###
#####################################################################################
### 変数定義                                                                       ###
#####################################################################################
 
####ZabbixWeb画面のURL。環境に合わせて要修正
ZabbixWeb=http://ZabbixサーバーのIPアドレス/zabbix/
 
###ZabbixAPIの認証
auth=`bash zabbix_token_get.sh`
 
###csv読み取りのための設定。修正不要
PRE_IFS=$IFS
IFS=$'\n'
 
#####################################################################################
 
### ホストグループ名をホストグループIDに変換する
 
curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "hostgroup.get",
    "params": {
        "output": "extend",
        "filter": {
            "name": [
                "'$1'" 
                  ]
        }
    },
    "auth": "'${auth}'",
    "id": 1
}
' -H "Content-Type: application/json-rpc" ${ZabbixWeb}api_jsonrpc.php | gawk -F'"' '{print $10}'

実行結果

[root@zabbixserver]# ./hostgroup_name_to_ID.sh "Test_Linux_Servers"
20

ホストグループは「Test_Linux_Servers」のIDは「20」ということですね。

ホスト追加スクリプト

host_create.sh

あともう少しです。ホスト追加のシェルスクリプトhost_create.shを作ります。リストファイルから一行ずつ読み込み、;で区切って、”host”、”groupid”などといったそれぞれのパラメーターに値を渡しています。

#!/bin/bash
 
#####################################################################################
### ファイルから読み取ったホストをホストグループに追加する                             ###
#####################################################################################
### 使い方
###  ./host_create.sh "読み込むファイル"
###
### 使用例
###  ./host_create.sh "/work/ZabbixAPITest/host_create_list"
###
#####################################################################################
### 変数定義                                                                      ###
#####################################################################################
 
####ZabbixWeb画面のURL。環境に合わせて要修正
ZabbixWeb=http://ZabbixサーバーのIPアドレス/zabbix/
 
###ZabbixAPIの認証
auth=`bash zabbix_token_get.sh`
 
###csv読み取りのための設定。修正不要
PRE_IFS=$IFS
IFS=$'\n'
 
#####################################################################################
###csvから一行ずつ読み取る
for line in `cat "$1" | grep -v ^#`
 
do
 
  HostGroupName=`echo ${line} | cut -d ';' -f 1`
  HostName=`echo ${line} | cut -d ';' -f 2`
  IFType=`echo ${line} | cut -d ';' -f 3`
  IFdefaultORnot=`echo ${line} | cut -d ';' -f 4`
  UseIP=`echo ${line} | cut -d ';' -f 5`
  IPaddress=`echo ${line} | cut -d ';' -f 6`
  DNSname=`echo ${line} | cut -d ';' -f 7`
  Port=`echo ${line} | cut -d ';' -f 8`
 
### ホストグループ名をホストIDに変換する
HostGroupID=`bash hostgroup_name_to_ID.sh "$HostGroupName"`
 
### ホストを追加する
 
curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "host.create",
    "params": {
        "host": "'$HostName'",
        "interfaces": [
            {
                "type": '$IFType',
                "main": '$IFdefaultORnot',
                "useip": '$UseIP',
                "ip": "'$IPaddress'",
                "dns": "'$DNSname'",
                "port": "'$Port'"
            }
        ],
        "groups": [
            {
                "groupid": "'$HostGroupID'"
            }
        ]
    },
    "auth": "'${auth}'",
    "id": 1
}
' -H "Content-Type: application/json-rpc" ${ZabbixWeb}api_jsonrpc.php
 
 
 echo ""
 
done
 
IFS=$PRE_IFS

実行結果

それではこのスクリプトと先ほど作ったホストのリストを使って、一気にホストを作成してみます。

[root@zabbixserver]# ./host_create.sh "/work/ZabbixAPITest/host_create_list"
{"jsonrpc":"2.0","result":{"hostids":["10272"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10273"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10274"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10275"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10276"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10277"]},"id":1}
{"jsonrpc":"2.0","result":{"hostids":["10278"]},"id":1}
～～以下略～～

300台のホスト追加ができました！スクリプトを実行した後は処理が終わるのを待っているだけなので、手作業で設定していくよりも断然ラクにできました。

今回のポイント

Zabbix APIを使ったシェルスクリプトで設定リストファイルを読み込み、ホストグループ作成とホスト作成を行いました。その過程で、ポイントとなることを3つご紹介しました。

【ポイント1】認証トークン取得スクリプトを作っておくと便利

【ポイント2】 API使用時はホストグループ→ホストの順で設定する

【ポイント3】ホストグループID変換スクリプトを作っておくと便利

まとめ

監視設定のリストファイルとZabbix APIを使用したシェルスクリプトで、300台のホストを一気に作成することができました。このようなスクリプトを使えば、大量の監視設定をコマンドひとつでラクにミスなく行うことができます。

Zabbix APIは、ホストグループとホストの作成以外にもあらゆる操作ができるので、スクリプト内で呼び出すメソッドやJSONクエリの部分をカスタマイズすれば使い方はもっと広がります。

初心者にはとっつきにくいけれど、便利なZabbix APIを皆さんもぜひ活用してみてはいかがでしょうか。

プラットフォーム技術部

Posted by kondo