sabatrapdは、ネットワーク機器からSNMP Trapを受け取り、監視サービスMackerelのチェック監視項目として投稿するミドルウェアです。
SNMP Trapとは、ネットワーク機器側からサーバーに状態の変化を報告するpush型の仕組みです。緊急性の高い異常な状態（リンクダウンやオーバーヒートなど）を素早く報告するために使われます。
（MackerelのSNMP対応としてはmackerel-plugin-snmpがありますが、これはネットワーク機器から定期的に情報を取得するpull型のものです。）
- 本プログラムは無保証です。
- プロトコルはSNMP v2cのみに対応しています。
- SNMP Trapの内容はMackerelに投稿され、アラートになります。SNMP Trapの原因が解消されてもsabatrapdでは関知できないので、Mackerel上でアラートを手動で閉じる必要があります。そのため、SNMP Trapの捕捉は最小限に留めることを推奨します。
- 捕捉対象に対してあらかじめ「WARNING」「CRITICAL」「UNKNOWN」のそれぞれのステータスを設定することができます。無指定時には「WARNING」が用いられます。
sabatrapdのリリースアーカイブを使うと、プログラミング環境を用意することなく、すぐに試すことができます。
リリースページから、インストール対象のアーキテクチャ（amd64またはarm64）に合ったtar.gz形式のアーカイブファイルをダウンロードします。
適当なフォルダーを用意し、tarコマンドで展開してください。例として、新規にsabatrapd-distフォルダーを作り、ダウンロードフォルダーにあるファイルをそこに展開する場合の操作を以下に示します。
$ mkdir sabatrapd-dist
$ cd sabatrapd-dist
$ tar xvf ~/Downloads/sabatrapd_linux_amd64.tar.gz
sabatrapd.yml.sample
systemd/sabatrapd.env
...
Mackerel側では、以下の作業をしておいてください。
- 投稿先のMackerelのオーガニゼーションに、チェック監視の投稿先となるスタンダードホストを用意します。
- MackerelのオーガニゼーションからAPI（書き込み権限）を払い出します。
sabatrapdの設定はYAML形式のファイルで行います。
sabatrapd.yml.sampleファイルをsabatrapd.yamlという名前にコピーしてください。
sabatrapd.ymlファイルをエディターで開き、MackerelオーガニゼーションのAPI文字列とホストIDを記述します。
mackerel:
x-api-key: API文字列
host-id: ホストID
次に、snmptrapdがサービスとして監視するIPアドレス、ポート番号、それにSNMPコミュニティ名を指定します。
snmp:
addr: 0.0.0.0
port: 9162
community: public
- 上記の設定では、IPv4アドレスで到達可能な範囲からのアクセスを受け付け（
0.0.0.0）、ポート番号は9162（UDP）を使用、SNMPコミュニティは「public」としています。 - SNMP Trapを送る機器上で送信先ポートを指定できないときには、sabatrapd側の監視ポート番号を標準ポートである「162」にします。ただし、このポートで動作させるには管理者権限で実行する必要があります。
- SNMPコミュニティの名前はSNMP Trapを送る機器に合わせます。コミュニティの異なるSNMP Trapは無視されます。
- SNMPコミュニティ設定は1つのみ指定できます。複数のSNMPコミュニティで運用しなければならないときには、
community行を削除して、コミュニティの名前照合をスキップするようにしてください。
sabatrapd.ymlを保存したら、いよいよsabatrapdを起動します（Ctrl+cキーを押せば終了します）。
./sabatrapd
ネットワーク機器からSNMP Trap（たとえばイーサーネットケーブルの抜き差し）をsnmptrapdに送ってみると、捕捉対象のものだったときにはMackerelに投稿され、Mackerelからすぐにアラートが発報されます。
sabatrapd.ymlのdebug設定をtrueにすると、受け取ったSNMP Trapメッセージや詳細なログが出力されます。SNMP Trapメッセージをうまく処理できないときにご利用ください。
sabatrapdはいくつかのオプションをとることができます。
-conf <設定ファイル>: 設定YAMLファイルを指定します。このオプションを省略したときには、デフォルトでカレントフォルダーにあるsabatrapd.ymlを参照します。-dry-run: Mackerelにメッセージを投稿しないモードで動作します。Mackerelでの本番の監視の前に、SNMP Trapの挙動を確認したいときに指定します。
Linuxのsystemd環境で自動起動させるためのファイルを用意しています。
正常に稼働するsabatrapd.ymlを用意できたら、インストーラーのinstall.shを管理者権限で実行してください。
$ sudo ./install.sh
sabatrapd installation is finished.
/usr/local/etc/sabatrapd.yml will be used.
To check sabatrapd's status, type 'journalctl -u sabatrapd'
デフォルトでは/usr/local/binフォルダーにsabatrapd実行ファイルが、/usr/local/etcフォルダーに設定ファイルが、systemd設定フォルダーにsabatrapd.serviceがコピーされます。
実行ファイルと設定ファイルのインストール先フォルダーを変えたいときには、環境変数DESTBINDIRおよびDESTETCDIRでそれぞれフォルダーを指定してから、sudo -E ./install.shとしてください。
状態やログについてはjournalctl -u sabatrapdで確認できます。
sabatrapdのより高度な設定およびカスタマイズについて説明します。
MIB（Management Information Base）ファイルをsabatrapdに登録すると、SNMP Trapメッセージの項目を抽出して投稿内容に含めることができます。
デフォルトの設定は以下のとおりです。
mib:
directory:
- "/usr/share/snmp/mibs/"
modules:
- SNMPv2-MIB
- IF-MIB
directoryにMIBファイルを格納するフォルダーを指定し、modulesに読み込むMIBファイル名を列挙します。子フォルダーは探索しないので、MIBファイルはdirectoryのフォルダーの直下に置いてください。
MIBファイルはベンダー各社から提供されています。
- Red Hat Enterprise Linuxやその派生ディストリビューションの場合は、net-snmp-libsパッケージをインストールすると、
/usr/share/snmp/mibs/フォルダーにSNMPv2-MIBやIF-MIBなどのMIBファイルが置かれます。 - Debian GNU/Linux・Ubuntuの場合は、snmp-mibs-downloaderパッケージ（non-freeセクション）をインストールすると、
/var/lib/snmp/mibs/ietf/フォルダーにSNMPv2-MIBやIF-MIBなどのMIBファイルが置かれます。
SNMP Trapは内容に応じて「.1.3.6.1.6.3.1.1.5.1」のような固有のOID（Object Identifier）を持ちます。ベンダーごとに独自のものが用意されており、共通のものは最低限です。
デフォルトで記載済みの設定は以下のとおりです。
trap:
- ident: .1.3.6.1.6.3.1.1.5.1
format: '{{ addr }} is cold started'
- ident: .1.3.6.1.6.3.1.1.5.2
format: '{{ addr }} is warm started'
- ident: .1.3.6.1.6.3.1.1.5.3
format: '{{ addr }} {{ read "IF-MIB::ifDescr" }} is linkdown'
- ident: .1.3.6.1.6.3.1.1.5.4
format: '{{ addr }} {{ read "IF-MIB::ifDescr" }} is linkup'
identに捕捉したいSNMP TrapのOID、formatにMackerelへ投稿するメッセージというペアで記述します。format内では以下の2つのプレースホルダーを指定できます。
{{ addr }}: SNMP Trap元のIPアドレスに展開されます。{{ read "MIBモジュール名::MIBオブジェクト名" }}: 読み込み済みのMIBファイル内に記載されているモジュール名およびオブジェクト名に基づき、SNMP Trap内の対応する情報を展開します。
上記の設定の場合、MIBモジュール名IF-MIB（IF-MIBファイル）のオブジェクト名ifDescr（インターフェイスの説明）に相当する値をSNMP Trapから探します。これはたとえば「Intel Corporation 82540EM Gigabit Ethernet Controller」のようになります。インターフェイス番号を示したければ、IF-MIB::ifIndexを使います。
どのようなMIBオブジェクトが利用可能かは、各MIBファイルを参照してください。
SNMP Trapを捕捉しすぎると、無用なアラートがMackerelで多発することになります。緊急性の高い、最小限のもののみ設定するようにすることをお勧めします。
samplesフォルダーには、例としてYAMAHA SWX2220およびSWX3220が発行するSNMP Trapの一覧を用意しています。捕捉したいものをsabatrapd.ymlにコピーするとよいでしょう。
デフォルトでは捕捉対象のアラートのレベルは「WARNING」に設定されていますが、alert-levelを使って特定の捕捉対象について明示的に「CRITICAL」や「UNKNOWN」のレベルを設定することも可能です。
- ident: .1.3.6.1.6.3.1.1.5.3
format: '{{ addr }} {{ read "IF-MIB::ifDescr" }} is linkdown'
alert-level: critical
一部のネットワーク機器では、Shift JISエンコーディングの日本語メッセージを発行することがあります。Mackerelに投稿する際にはUTF-8エンコーディングでなければならないため、ネットワーク機器のIPアドレスを明示して文字エンコーディング変換対象とするようにします。
たとえばIPアドレス「192.168.1.200」のネットワーク機器からのShift JISエンコーディングのメッセージを変換対象とするには、以下のように記載します。
encoding:
- addr: 192.168.1.200
charset: shift-jis
インターネットに接続するのにプロキシーサーバーを利用している場合は、環境変数HTTPS_PROXYにプロキシーサーバーを設定してからsabatrapdを実行してください。
export HTTPS_PROXY=https://proxyserver:8443
sabatrapdをsystemd環境で自動起動している場合は、/usr/local/etc/sabatrapd.envに環境変数を設定する行があるので、そこで指定します。
GitHubリポジトリからビルドする手順を紹介します。
Goの開発環境をインストールした後、本リポジトリを展開した作業フォルダー内で、以下のコマンドでsabatrapdをビルドします。
make
次のコマンドでsabatrapdを直接ビルドすることもできます。
go build
以降の使い方については、「セットアップ手順（リリースアーカイブの利用）」の各項と同じです。
Copyright 2023 yseto and Kenshi Muto
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.