ウェブフックの概要

このドキュメントでは、ウェブフックの機能とその導入についての一般的なガイドラインを示します。このドキュメントの目的は以下のとおりです。

  • ウェブフックの概要説明
  • サポートされている主要機能のハイライト
  • ウェブフック設定の導入および管理に関する詳細情報の提供
  • ウェブフックがエクスポートする raw データの確認と表示に関するガイダンスの提供

表記法

ドキュメント表記の詳細は、『Cisco Technical Tips Conventions』を参照してください。

機能の概要

ウェブフック クライアントは WLC 内で実行され、HTTPS 接続を介して情報を外部のサードパーティ サーバに公開します。この情報は「ペイロード」と呼ばれ、各ペイロードには、YANG モデルで定義された固有の情報セットが含まれています。ペイロードには、AP、クライアント、およびシステム レベルの情報を含む、WLC のステータスに関する運用データが含まれています。



設定手順

GUI または CLI を使用してウェブフックを設定できます。まず CLI を使用してデータ公開（DX; Data Externalization）を有効にする必要があります。有効になっていない場合は再起動する必要があります。次のコマンドを使用して DX の状況を確認して有効にします。 

(Cisco Controller) > show dx summary
(Cisco Controller) > config dx enable

ウェブフック サーバに、IP アドレスの代わりに DNS 名を使用することができます。そのため、次のコマンドを使用して、ネットワーク設定で定義されている DNS サーバの IP アドレスが WLC に設定されていることを確認してください。 

(Cisco Controller) > config network dns serverip 208.67.222.222
(Cisco Controller) > show network summary
DNS Server IP............................... 208.67.222.222

CLI によるウェブフック設定

WLC でウェブフック サーバを正常に設定するには、いくつかの CLI コマンドが必要です。すべてのコマンドは「config telemetry webhook」セクションにあります。関連して「show telemetry webhook summary」コマンドも使用します。唯一の例外である、データ公開と DNS に関しては上記に記載しています。



HTTPS の考慮事項

WLC とサードパーティ サーバ間の接続は HTTPS で保護され、証明書が WLC の証明書ストアにインストールされている必要があります。transfer download コマンドを使用して、TFTP または HTTP サーバから証明書を転送することで対応できます。

次のコマンドを使用して webhook-ca-cert 転送を設定します。 

(Cisco Controller) > transfer download datatype webhook-ca-cert
(Cisco Controller) > transfer download filename <CA Cert File Name>
(Cisco Controller) > transfer download mode tftp
(Cisco Controller) > transfer download path /
(Cisco Controller) > transfer download serverip <TFTP server IP>
(Cisco Controller) > transfer download start


転送が成功すると、WLC 上のウェブフック クライアントはウェブフック サーバとのセキュアな接続を確立できます。証明書を使用するために再起動する必要はありませんが、ウェブフック サービスがすでに有効になっている場合は、「config telemetry webhook disable」コマンド実行後に「config telemetry webhook enable」コマンドを実行してサービスを再起動する必要があります。

「Showshow certificate all」コマンドを入力して「webhook-ca cert」を見つけ、証明書がインストールされていることを確認します。



URL 設定

WLC がウェブフック ペイロード データを送信する先の HTTPS URL を設定します。IP または DNS 名で指定でき、ポートの指定は任意です。「SSL 証明書の生成」の項を参照し、必要に応じて、必要な CA 証明書を生成してインストールします。

(Cisco Controller) > config telemetry webhook url https://<IP or DNS name>:<Port>

Auth-Token

この英数字の値を使用して、ウェブフック サーバが WLC のウェブフック クライアントを検証する場合があります。ウェブフック サーバがこの設定を使用するとは限りませんが、サーバが使用するかどうかにかかわらず、WLC に設定する必要があります。この値を WLC のホスト名に設定することを推奨します。 

(Cisco Controller) > config telemetry webhook auth-token <ALPHANUMERIC VALUE>

On-Change

CLI での On-Change 設定では、一定の間隔ですべてのペイロードを送信するか、差分または更新されたペイロードだけを送信するかを定義します。ウェブフック サーバ上でのデータ操作をシンプルにするために、最初は On-Change を無効にしてすべてのペイロードを受信し、差分データセットを効果的に使用するためのロジックがサードパーティのウェブフック サーバに組み込まれてから、有効にすることを推奨します。 

(Cisco Controller) > config telemetry webhook on-change disable / enable

Sync-Interval

CLI での Sync-Interval 設定では、ウェブフック クライアントがウェブフック サーバにデータをパブリッシュする間隔を定義します。[fixed] に設定すると、結果は 5 分ごとにパブリッシュされます。[adaptive] に設定すると、結果は 30 秒以内にパブリッシュされます。更新の受信頻度を上げるには、この値を [adaptive] に設定することをお勧めします。 

(Cisco Controller) > config telemetry webhook sync-interval adaptive / fixed

サブスクリプション

サブスクリプションのトピックおよび CLI で有効にした関連の YANG モデルの詳細については、後述する「サブスクリプションの設定」の項を参照してください。トピックを個別に登録することも、すべて選択して登録することも可能です。

(Cisco Controller) > config telemetry webhook subscribe <all / topic>

Enable または Disable

enable または disable コマンドを使用してウェブフックを有効または無効にします。

(Cisco Controller) > config telemetry webhook enable /disable

GUI によるウェブフック設定

GUI による設定画面には、[Management] タブを選択後、[Cloud Services]、[Webhook] の順に選択すればアクセスできます。URL、Auth-Token および HTTPS URL の設定の説明については、「CLI による設定」の項を参照してください。



ウェブフック データのパブリッシュ

ウェブフックを有効にするには、ドロップダウンを使用して [Enabled] を選択してから [Apply] を選択します。

ウェブフックを無効にするには、[Disabled] に変更します。

差分スナップショットのパブリッシュ

このオプションに対応する CLI コマンドは、「On-Change」です。[Enabled] に設定すると、差分スナップショットがパブリッシュされるため、変更または更新されたペイロードのみが送信されます。ウェブフック サーバ上でのデータ操作をシンプルにするために、On-Change を [Disabled] に設定して、一定間隔ですべてのペイロードを受信することを推奨します。

Interval

このオプションに対応する CLI コマンドは、「Sync-Interval」です。[fixed] に設定すると、結果は 5 分ごとにパブリッシュされます。[adaptive] に設定すると、結果は 30 秒ごとにパブリッシュされます。更新の受信頻度を上げるには、この値を [Adaptive] に設定することをお勧めします。

URL

サードパーティのウェブフック サーバに対する HTTPS URL を設定して、結果をパブリッシュする方法の詳細については、上記を参照してください。

Auth-Token

Auth-Token の必須の設定については、上記を参照してください。

サブスクリプションの設定

公開されるデータは、CCO に 8.7 コードと合わせてリリースされる YANG モデルで定義されます。以下は、YANG モデルと CLI にリストされているサブスクリプション間のマッピングを示しています。これらは、GUI による設定も可能なサブスクリプションです。有効にすることができる 7 つのトピックまたはテーブルがあり、それぞれが異なるデータ セット、具体的には AP、クライアント、干渉源、MapServer、ネットワーク、Rogue、システムに関する運用データセットを定義しています。1 つまたは複数の YANG モデル サブスクリプションを選択すると、WLC のウェブフック クライアントが、関連するデータをウェブフック サーバにポストします。





システム サブスクリプションは wlc-ops-system-stats.yang モデルで定義され、メモリ、タイマー、CPU などの使用率とメトリックの詳細を示します。

ネットワーク サブスクリプションは wlc-ops-network-stats.yang モデルで定義され、各ネットワーク サービスの RADIUS、DHCP、TACACS の統計情報とカウンタの詳細を示します。

AP サブスクリプションは wlc-ops-ap.yang モデルで定義され、AP 名、MAC、接続しているクライアント数などの AP 情報を公開します。

クライアント サブスクリプションは wlc-ops-clients.yang モデルで定義され、クライアントの RSSI、MAC、接続している AP などのクライアントのメトリックと情報を公開します。

干渉源サブスクリプションは wlc-ops-interferers.yang モデルで定義され、さまざまな種類の RF 干渉源の詳細を示します。

MapServer サブスクリプションは wlc-ops-fabric.yang モデルで定義され、マップ サーバの詳細および、関連付けられているファブリック対応ワイヤレス カウンタを示します。このサブスクリプションには、CMX またはロケーション サービスに関する要素は含まれていません。

Rogue サブスクリプションは wlc-ops-rogue.yang モデルで定義され、関連付けられているレポート AP から送信されるさまざまな種類の Rogue と RF 情報の詳細を示します。

Yang モデル

YANG モデルを分析することで、モデルに含まれ、公開されるデータの詳細を把握できます。WLC-Ops-Network-stats.yang モデルの概要を次に示します。



このモデルでは、Radius、TACACS、DHCP、CDP 情報に関するカウンタと統計情報を含む、ネットワーク サブスクリプションの詳細が示されています。

ウェブフック ステータスの確認

ウェブフックのステータスは、CLI コマンド「show telemetry webhook summary」を使用して確認できます。GUI では、[Management] タブのウェブフック設定画面にある [Data Publishing Status] でも確認できます。[Last Success] の時刻が [Last Error] の時刻よりも新しいことを確認します。その場合は、ウェブフックがウェブフック サーバにデータを正常にポストできていることになります。





Logstash および Python Flask 用の SSL 証明書の生成

WLC とウェブフック サーバ間の HTTPS 接続を保護するために、SSL 証明書を作成する必要があります。証明書は、認証局（CA）で署名することも、自己署名することもできます。

次の 2 つのコマンドを使用して、Logstash、Python Flask、および WLC のそれぞれで使用可能な自己署名 SSL 証明書を生成できます。プロンプトに従い、「What is your first and last name」というプロンプトが表示されたら、ウェブフック サーバの IP アドレスまたは DNS 名を入力します。 

$ keytool -genkey -alias webhook -keyalg RSA -validity 365 -keystore /tmp/webhook.jks -keysize 2048


$ keytool -export -rfc -alias webhook -keystore /tmp/webhook.jks -file /tmp/webhook.crt -storepass password


Python Flask で使用する証明書を生成するには、次の追加コマンドを実行

$ keytool -importkeystore -srckeystore /tmp/webhook.jks -destkeystore /tmp/webhook.p12 -deststoretype PKCS12 -srcalias webhook -deststorepass password -destkeypass password
$ openssl pkcs12 -in /tmp/webhook.p12  -nokeys -out /tmp/webhook.crt
$ openssl pkcs12 -in /tmp/webhook.p12  -nodes -nocerts -out /tmp/webhook.key


最終的には、次の 4 つのファイルが出力されます。

Webhook.crt は WLC に転送されます。

Webhook.jks は Logstash で使用できます。

Webhook.crt と webhook.key は Python Flask で使用できます。

Webhook.p12 は使用されていないため、削除してかまいません。

.crt および .key ファイルは次のような内容になります。





Python を使用した Linux ウェブフック サーバ

ここでは、Flask ウェブフック フレームワークを使用してウェブフック サーバとして機能し、WLC からデータを受信する Python コードの例をいくつか示します。Linux サーバ IP でウェブフック URL を指定した後、Linux で次のコードを実行します。WLC から「config telemetry webhook url http://<IP_OF_LINUX_SERVER>」コマンドを入力し、「config telemetry webhook enable」コマンドを使用してサービスが有効になっていることを確認します。

Flash ウェブフックの詳細は、Github（https://ogma-dev.github.io/posts/simple-flask-webhook/）で確認できます。以下は最も基本的なウェブフック サーバの例です。必要に応じて SSL 証明書へのパスを更新してください。 

from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/', methods=['POST'])
def webhook():
    if request.method == 'POST':
        print(request.json)
        return '', 200
    else:
        abort(400)

if __name__ == '__main__':
    app.run(ssl_context=('/tmp/webhook.crt', '/tmp/webhook.key'),host='0.0.0.0', port=443)

Linux で Python Flask ウェブフックを開始する例は次のとおりです。



最初のペイロードが受信され、ウェブフック クライアントとサーバの設定が正しいことが確認されます。ウェブフック サーバが、ウェブフック クライアントに HTTP POST コード 200 を返します。

受信した別のペイロードも参考までに以下に示します。

ウェブフック サーバがセットアップされ、正常に動作していることが確認されました。

Elastic（ELK）スタックの Kibana を使用したウェブフック データの表示

Kibana は、データ表示に特化した、有名な無償のオープンソース ソフトウェア パッケージで、多くの場合 Logstash および Elasticsearch と一緒に使用して、「ELK」または「Elastic スタック」を構成します。ELK スタックをインストールする手順を説明しているガイドがオンライン上に多数ありますので、このドキュメントでは扱っていません。ELK スタックの保守担当者向けのドキュメントは、詳細なインストール プロセスが記載されているサイト（https://www.elastic.co/guide/en/elastic-stack/current/installing-elastic-stack.html）に用意されています。Ubuntu Linux 16.04 を使用している場合は、サマリー ガイドも https://www.rosehosting.com/blog/install-and-configure-the-elk-stack-on-ubuntu-16-04/ で入手できます。手順 6「Nginx をリバース プロキシとしてインストールする」をスキップし、代わりにデフォルト ポート の 5601 で Kibana に直接アクセスすることを推奨します。

Java セキュリティ設定

次の設定では Logstash プロセスが特権ポート 443 を使用するため、Java プロセスがポート 443 を使用できるようにするには手順を追加する必要があります。https://serverfault.com/questions/133415/how-to-allow-non-root-user-to-listen-on-privileged-port にあるガイドに従って次のコマンドを実行し、Java がポート 443 を使用できるようにします。 

sudo setcap 'cap_net_bind_service=+ep' <path to Java executable>
Ensure the <path to Java> is to the binary executable, not a symbolic link.
For Ubuntu 16 with Java 8, the complete command is:
$ sudo setcap 'cap_net_bind_service=+ep' /usr/lib/jvm/java-8-oracle/jre/bin/java

Logstash 設定

ELK スタックの運用準備が完了したら、ウェブフック データを受信するために必要な手順がいくつかあります。前述のように、ウェブフックの受信には、Python Flask ウェブフックではなく Logstash を使用します。

/etc/logstash/logstash.conf ファイルを設定して、入力と出力の設定用に次の 2 行だけが含まれるようにします。この設定では、Logstash はポート 443 で HTTPS ウェブフック サーバとして機能し、解析結果をローカルで実行されている Elasticsearch に出力します。 

input { http { ssl => "true" keystore => "/tmp/webhook.jks" keystore_password => "password"  port => 443 } }
output { elasticsearch {} }

設定が完了したら、logstash.conf ファイルは次のようになります。



必ず、JKS 証明書キーストア ファイルへの正しいパスとキーストア パスワードを使用してください。

Logstash を再起動し、結果が http://localhost:5601 の Kibana に表示されることを確認します。

Kibana

Kibana インターフェイスはデフォルトでは HTTP ポート 5601 上で実行され、最初の接続時には [Discover] ビューが表示されます。[Discover] ビューには、Logstash によってウェブフック クライアントから収集/処理され、Elasticsearch データストアにインデックス付きで保存されたデータが表示されます。WLC のウェブフック クライアントが送信したさまざまなペイロードとデータを含む



フィールドが表示されます。

表示設定の作成

左側の [Visualize] タブをクリック後、[+] 記号をクリックして新しい表示設定を作成します。[Pie] グラフを選択します。



「logstash-*」インデックスを選択するか、すでに [Discover] タブに検索条件を作成して保存している場合は、保存済みの検索条件を選択します。



例として次のスクリーンショットを使用し、WLC に参加している AP 名を示す円グラフを作成します。この設定の場合、[Field] には「payload.wlc.ops.wireless.aps.general.name.keyword」を設定します。



右上の右矢印アイコンをクリックすると、以下のように結果が円グラフで表示されます。右上にある [Save] リンクを選択し、表示設定の名前を付けます。



表示設定を追加する場合は、この手順を繰り返します。[Discover] タブを使用して、さまざまなペイロードに使用するフィールド名を決定します。AP およびクライアントのサブスクリプションの例を次に示します。

payload.wlc.ops.wireless.aps.general.name.keyword
payload.wlc.ops.wireless.aps.mac.keyword
payload.wlc.ops.wireless.clients.mac.keyword
payload.wlc.ops.wireless.clients.measurements.rf.rssi
payload.wlc.ops.wireless.clients.measurements.traffic.tx-bytes
payload.wlc.ops.wireless.clients.measurements.traffic.rx-bytes

ダッシュボードの作成

[Dashboard] タブを使用すると、複数の表示設定をダッシュボードに追加して簡単にデータを表示できます。左側のパネルから [Dashboard] リンクを選択後、[+] アイコンを選択して新しいダッシュボードを作成し、[Add] を選択して前に作成したデータ表示設定を追加します。



ダッシュボードにデータ表示設定を追加して、右上にある [Save] を選択すると、後で簡単に再表示できます。

まとめ

このベータ版ガイドの情報を活用することで、WLC でのウェブフック クライアントの設定、Python Flask ウェブフック コードによる設定の検証、Kibana でのウェブフック データの表示が可能になります。