sabatrapd

sabatrapd

概要

sabatrapdは、ネットワーク機器からSNMP Trapを受け取り、監視サービスMackerelのチェック監視項目として投稿するミドルウェアです。

SNMP Trapとは、ネットワーク機器側からサーバーに状態の変化を報告するpush型の仕組みです。緊急性の高い異常な状態（リンクダウンやオーバーヒートなど）を素早く報告するために使われます。

（MackerelのSNMP対応としてはmackerel-plugin-snmpがありますが、これはネットワーク機器から定期的に情報を取得するpull型のものです。）

制約

• 本プログラムは無保証です。
• プロトコルはSNMP v2cのみに対応しています。
• SNMP Trapの内容は「WARNING」としてMackerelに投稿され、アラートになります。SNMP Trapの原因が解消されてもsabatrapdでは関知できないので、Mackerel上でアラートを手動で閉じる必要があります。そのため、SNMP Trapの捕捉は最小限に留めることを推奨します。

セットアップ手順（リリースアーカイブの利用）

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側では、以下の作業をしておいてください。

1. 投稿先のMackerelのオーガニゼーションに、チェック監視の投稿先となるスタンダードホストを用意します。
2. MackerelのオーガニゼーションからAPI（書き込み権限）を払い出します。

sabatrapd.ymlの作成

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の用意

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捕捉メッセージの設定

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にコピーするとよいでしょう。

ネットワーク機器ごとの文字エンコーディング設定

一部のネットワーク機器では、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リポジトリの利用）

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.

使用ライブラリ

• https://github.com/sleepinggenius2/gosmi/
• https://github.com/gosnmp/gosnmp