NSO: Stream と Notification

Akira Iwamoto · ‎2023-07-29

はじめに
Built-in Stream
Streamを読み出す
Alarmでテストを行う
ncs-alarms stream へもデータが送信される
サブスクライバがオフラインだった場合
ユーザ定義 stream と notification
設定完了
vlan-status notificationを送信するためのアプリケーション
LSA と NETCONF notification

はじめに

NSO は内部でメッセージング機能をもっており、NSOのアプリケーションはそのプロバイダーやコンシューマーになることが出来ます。Streamを事前に定義して作成しておき、プロバイダはNotification APIを使用してメッセージを送信することが出来ます。

この例では、Stream A, B, C の 3つの Stream が定義されています。メッセージキューシステムのようなもので、アプリケーションは Notificationを Notification API を使用して送信します。

一方、3つのサブスクライバが存在し、それぞれ違うStreamを購読しています。1つめと2つ目のサブスクライバは、Stream Aを購読しているため、アプリケーションがStream A に notification を送信した際には、両方のサブスクライバがそれを受信します。

Built-in Stream

NSO内部では、3つのビルトインStreamが定義されています。

kicker-events
ncs-alarms
ncs-events

以下のように NSO CLI からそれを確認することが可能です。

admin@lower-nso-1# show notification stream ?
Possible completions:
  kicker-events     - NCS event according to tailf-kicker.yang
  ncs-alarms        - NCS alarms according to tailf-ncs-alarms.yang
  ncs-events        - NCS event according to tailf-ncs-devices.yang
admin@lower-nso-1#

条件がマッチしKicker がトリガーされた際、kicker-events streawm へNotifiationが送信されます。同様に、Alarmが作成された際にも、ncs-alarms stream へ alarm-notification が送信されます。ncs-events stream は、commit-queue の進捗状況が送信されます。

これらStreamは ncs.conf 内で定義されており、同じ様にユーザが独自に定義することが可能です。

<notifications>
    <event-streams>

      <!-- This is the builtin stream used by NCS to generate northbound -->
      <!-- notifications whenever the alarm table is changed. -->
      <!-- See tailf-ncs-alarms.yang -->
      <!-- If you are not interested in NCS northbound netconf notifications -->
      <!-- remove this item since it does consume some CPU -->
      <stream>
        <name>ncs-alarms</name>
        <description>NCS alarms according to tailf-ncs-alarms.yang</description>
        <replay-support>true</replay-support>
        <builtin-replay-store>
          <enabled>true</enabled>
          <dir>./state</dir>
          <max-size>S10M</max-size>
          <max-files>50</max-files>
        </builtin-replay-store>
      </stream>

Streamを読み出す

Streamに送信されたNotificationは、ノースバウンドインターフェースを使用してそれらを購読することで読み出すことが出来ます。

NETCONF
RESTCONF
JSON-RPC
CDB Subscriber

アプリケーションによってNotificationが送信された時に、サブスクライバが接続中であれば、メッセージを受信します。

Alarmでテストを行う

アラームの作成

NSO にはアラーム機能が内蔵されています。例えば、デバイスマネージャは、デバイスが接続不可ということを検知した場合、connection-failure アラームを作成します。

admin@lower-nso-1# devices device ex0 connect
result false
info Failed to connect to device ex0: connection refused
admin@lower-nso-1# *** ALARM connection-failure: Failed to connect to device ex0: connection refused
admin@lower-nso-1#

このアラームは、いつでも show alarm コマンドで確認することが可能です。

admin@lower-nso-1# show alarm
alarms summary indeterminates 0
alarms summary criticals 0
alarms summary majors 1
alarms summary minors 0
alarms summary warnings 0
alarms alarm-list number-of-alarms 1
alarms alarm-list last-changed 2023-07-26T02:14:42.342687+00:00
alarms alarm-list alarm ex0 connection-failure /devices/device[name='ex0'] ""
 is-cleared              false
 last-status-change      2023-07-26T02:14:42.342687+00:00
 last-perceived-severity major
 last-alarm-text         "Failed to connect to device ex0: connection refused"
 status-change 2023-07-26T02:14:42.342687+00:00
  received-time      2023-07-26T02:14:42.342687+00:00
  perceived-severity major
  alarm-text         "Failed to connect to device ex0: connection refused"
admin@lower-nso-1#

ncs-alarms stream へもデータが送信される

内蔵アラームアプリケーションが、アラーム作成時に ncs-alarms stream へ notification の作成を行います。そのため、stream をサブスクライブしておくことで、アラームを外部のシステムで検知することが出来ます。

netconf-console コマンドを使用し、アラーム作成時のテストは以下のようになりました。

$ netconf-console --create-subscription ncs-alarms
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <ok/>
</rpc-reply>
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">      <<<<<<<<< ペイロードは notificatoin タグ内に含まれる
  <eventTime> 2023-07-26T02:14:42.374426+00:00</eventTime>
  <alarm-notification xmlns="http://tail-f.com/ns/ncs-alarms">              <<<<<<<<< データは alarms-notification モデルに含まれる
    <alarm-class>new-alarm</alarm-class>
    <device>ex0</device>
    <type>connection-failure</type>
    <managed-object xmlns:ncs="http://tail-f.com/ns/ncs">
       /ncs:devices/ncs:device[ncs:name='ex0’]
    </managed-object>
    <specific-problem/>
    <event-type>communicationsAlarm</event-type>
    <has-clear>true</has-clear>
    <kind-of-alarm>root-cause</kind-of-alarm>
    <probable-cause>0</probable-cause>
    <event-time>2023-07-26T02:14:42.342687+00:00</event-time>
    <perceived-severity>major</perceived-severity>
    <alarm-text>Failed to connect to device ex0: connection refused</alarm-text>
  </alarm-notification>
</notification>

上記アラームで確認したものと同じデータが、alarm-notification コンテナに埋め込まれ、それがnotification のペイロードに入れられた状態で、データが受信します。eventTime leaf が付加されており、Notificationが送信された時刻が記録されています。

alarm-notification は、以下のYangファイルに記述されたモデルとなっています。

Yangモデルは、NSOのインストールディレクトリにありますので、ご確認頂けます。

<NCS_DIR>/src/ncs/yang/tailf-ncs-alarms.yang

 notification alarm-notification {
    description
      "This notification is used to report a state change for an alarm.  The
       same notification is used for sending a new alarm, a cleared
       alarm or changing the text and/or severity of an existing
       alarm.
       A receiving NETCONF client shall use the 'device', 'type',
       'managed-object' and 'specific-problem' to match against
       existing alarms.";
    leaf alarm-class {
      type enumeration {
        enum new-alarm {
          description
            "The alarm has not yet changed and has not been cleared.";
        }
        enum changed-alarm {
          description
            "The alarm has changed but has not been cleared.";
        }
        enum cleared-alarm {
          description
            "The alarm has been cleared.";
        }
      }
      description
        "Specifies if this notification is a new, changed or cleared alarm,";
      reference
        "3GPP TS 32.111-2 - notificationType";
    }
    uses common-alarm-parameters;
    uses alarm-model-parameters;
    uses alarm-state-change-parameters;
  }

サブスクライバがオフラインだった場合

サブスクライバがメッセージ受信時にオフラインだった場合、それらメッセージを後から受信することは出来ません。これは SNMP Trap を受信する SNMP Manager のような状態です。

これでは不便ですので、NETCONF は Replay 機能を定義しており、NSOもそれを実装しています。

Notificationがディスクに保存される
それにより、サブスクライバは後から古いNotificationを読み出すことが出来る

ビルトイン Stream は、どれもreplay をサポートしているため、古い ncs-alarms notification を後から読み出すことが可能です。

admin@lower-nso-1# show notification stream ncs-alarms
notification
 eventTime 2023-07-26T02:14:42.374426+00:00
 alarm-notification
  alarm-class new-alarm
  device ex0
  type connection-failure
  managed-object /devices/device[name='ex0']
  specific-problem
  event-type communicationsAlarm
  has-clear true
  kind-of-alarm root-cause
  probable-cause 0
  event-time 2023-07-26T02:14:42.342687+00:00
  perceived-severity major
  alarm-text Failed to connect to device ex0: connection refused
 !
!
notification
 eventTime 2023-07-26T02:34:09.136351+00:00

時間の範囲指定

サブスクライバは、取得したいNotificationの時間を範囲で指定することが出来ます。サブスクライバが再起動した場合などに、再起動が発生した時間以降の情報を要求することで、受信出来なかったNotificationをすべて取得することが多いです。

CLI

admin@lower-nso-1# show notification stream ncs-alarms from 2023-07-26T02:20:00.000000+00:00
notification
 eventTime 2023-07-26T02:34:09.136351+00:00
 alarm-notification
  alarm-class new-alarm
  device ex0
  type connection-failure
  managed-object /devices/device[name='ex0']
  specific-problem
  event-type communicationsAlarm
  has-clear true
  kind-of-alarm root-cause
  probable-cause 0
  event-time 2023-07-26T02:34:09.130165+00:00
  perceived-severity major
  alarm-text Failed to connect to device ex0: connection refused
 !
!
notification
 eventTime 2023-07-26T02:36:19.325807+00:00
 alarm-notification

NETCONF

$ netconf-console --port=2023  --create-subscription ncs-alarms --replay-start-time=2023-07-26T02:20:00
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <ok/>
</rpc-reply>
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2023-07-26T02:34:09.136351+00:00</eventTime>
  <alarm-notification xmlns="http://tail-f.com/ns/ncs-alarms">
    <alarm-class>new-alarm</alarm-class>
    <device>ex0</device>
    <type>connection-failure</type>
    <managed-object xmlns:ncs="http://tail-f.com/ns/ncs">/ncs:devices/ncs:device[ncs:name='ex0']</managed-object>
    <specific-problem/>
    <event-type>communicationsAlarm</event-type>
    <has-clear>true</has-clear>
    <kind-of-alarm>root-cause</kind-of-alarm>
    <probable-cause>0</probable-cause>
    <event-time>2023-07-26T02:34:09.130165+00:00</event-time>
    <perceived-severity>major</perceived-severity>
    <alarm-text>Failed to connect to device ex0: connection refused</alarm-text>
  </alarm-notification>
</notification>
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2023-07-26T02:36:19.325807+00:00</eventTime>
  <alarm-notification xmlns="http://tail-f.com/ns/ncs-alarms">

ユーザ定義 stream と notification

以下のテストは、NSOインストール環境に含まれる、LSAの例を使用したものです。以下のディレクトリからユーザが同じテストをすることが可能です。

6.1/examples.ncs/getting-started/developing-with-ncs/22-lsa-single-version-deployment

stream の定義

新たに vlan-notification stream をncs.conf で定義しています。ncs.conf 変更後には、NSOの reload や再起動が必要となりますので、ご注意ください。

  <notifications>
    <event-streams>

      <stream>
        <name>vlan-notification</name>
        <description>VLAN NOTIFICATION</description>
        <replay-support>true</replay-support>
        <builtin-replay-store>
          <enabled>true</enabled>
          <dir>./state</dir>
          <max-size>S10M</max-size>
          <max-files>50</max-files>
        </builtin-replay-store>
      </stream>

    </event-streams>
  </notifications>

vlan-status notification モデルの定義

NotificationはStreamに送信されるメッセージですが、特定のモデルに埋め込んで使用します。ここでは、サンプルにあるrfs-vlan モジュールに以下を追加しています。

module rfs-vlan {
  namespace "http://com/example/rfsvlan";
  prefix rfs-vlan;

...

  notification vlan-status {
    leaf vlan-name {
      type string;
    }
    leaf status {
      type int8;
    }
  }
...

設定完了

StreamとNotificationの設定は、以上です。ただし、後の LSA の例で使用するために、lsa-netconf NED を作成しておきます。

lsa-netconf-ned の作成

NSOに含まれるこの例では、netconf-ned の作成は Makefile 内で定義されているため、手動で作成する必要はありません。ここでは、参考情報として手動で作成する方法を書いています。

$ ncs-make-package --no-netsim --no-java --no-python           \
    --lsa-netconf-ned package-store/rfs-vlan/src/yang        \
    upper-nso/packages/rfs-vlan-ned

ここで作成された rfs-vlan-ned パッケージを、LSAのCFSノードへインストールすることで、今回作成している notification も使用することが可能となります。

vlan-status notificationを送信するためのアプリケーション

ここまで説明した状態で、NSOとしては vlan-notification stream が使用可能となっていますが、vlan-status notification を送信するためのアプリケーションが別途必要です。以下にJavaで作成したサンプルアプリケーションのソースコードを記述します。

$ cat SendVlanNotif.java
import com.tailf.cdb.*;
import com.tailf.conf.*;
import com.tailf.dp.Dp;
import com.tailf.dp.DpNotifStream;
import java.net.Socket;
import java.io.EOFException;
import java.io.IOException;

public class SendVlanNotif {
    public static void main(String[] args){
        Socket ctrlSocket = null;
        try {
            ctrlSocket = new Socket("127.0.0.1", 4570);
        } catch (IOException e) {
            System.out.println("Could not open control socket to ConfD!\n" + e);
            e.printStackTrace();
            System.exit(1);
        }

        DpNotifStream stream = null;
        try {
            Dp dp = new Dp("vlan_daemon", ctrlSocket);
            stream = dp.createNotifStream("vlan-notification");
        } catch (ConfException | IOException e) {
            System.out.println("Could not connect to the DP API!\n" + e);
            e.printStackTrace();
            System.exit(1);
        }

        rfsVlan rv = new rfsVlan();
        try {
          ConfXMLParam[] vals = new ConfXMLParam[] {
            new ConfXMLParamStart(rv.hash(), rv.rfs_vlan_vlan_status),
            new ConfXMLParamValue(rv.hash(), rv.rfs_vlan_vlan_name, new ConfBuf("vlanname1")),
            new ConfXMLParamValue(rv.hash(), rv.rfs_vlan_status, new ConfInt8(4)),
            new ConfXMLParamStop(rv.hash(), rv.rfs_vlan_vlan_status)
          };
          stream.send(ConfDatetime.getConfDatetime(), vals);
          System.out.println("Sent link status NETCONF notification");
        }catch (ConfException|IOException e){
            System.out.println("Semd notification exception:\n" + e);
            e.printStackTrace();
            System.exit(1);
        }
    }
}

Yangをコンパイルし生成された fxs ファイルを使って java ソースコードを生成し、使用されている定数の参照はそのクラスファイルを直接することが出来ます。以下に、ncsc yang コンパイラを使用して、rfsVlan.java を生成するコマンドを記載します。

# ncsc --emit-java rfsVlan.java  package-store/rfs-vlan/load-dir/rfs-vlan.fxs

作成が完了しましたら、これを使用してアプリケーションをコンパイルします。CLASSPATHを定義する方法は多々ありますが、ここでは環境変数からそのまま渡しています。

CLASSPATH=.:$NCS_DIR/java/jar/*  javac SendVlanNotif.java rfsVlan.java

その後実行することが出来ます。

CLASSPATH=.:$NCS_DIR/java/jar/* java SendVlanNotif

LSA と NETCONF notification

LSA環境では、RFSノードはCFSのデバイスとなり、lsa-netconf NED が使用されます。NECONFプロトコルで接続され、NEDを使用してnotification を受信することが可能です。

通常のConfig変更などは、sync 動作となるNETCONF のトランザクションを使用して行われるため、その結果はコミット後に受信します。RFS上の nano service の設定を行う場合など、その結果が async での受信となる場合に、CFSは NETCONF notificationを使用して、RFSから状況の把握を行います。

RFSでの notification

admin@lower-nso-1# show notification stream vlan-notification
notification
 eventTime 2023-07-25T06:02:47.548+00:00
 vlan-status
  vlan-name vlanname1
  status 4
 !
!
notification
 eventTime 2023-07-25T07:57:06.583+00:00
 vlan-status
  vlan-name vlanname1
  status 4
 !
!
notification
 eventTime 2023-07-25T07:57:14.87+00:00
 vlan-status
  vlan-name vlanname1
  status 4
 !
!
notification
 eventTime 2023-07-25T09:51:21.922+00:00
 vlan-status
  vlan-name vlanname2
  status 4
 !
!
admin@lower-nso-1#

CFS で RFS から受信したnotification を確認

received-notifications oper データにそれらが記録されています。

admin@upper-nso# show ncs:devices device lower-nso-1 notifications received-notifications | notab
notifications received-notifications notification 2023-07-25T06:02:47.548+00:00 0
 user          admin
 subscription  vlan-notification
 stream        vlan-notification
 received-time 2023-07-26T03:46:52.88398+00:00
 data vlan-status vlan-name vlanname1
 data vlan-status status 4
notifications received-notifications notification 2023-07-25T07:57:06.583+00:00 0
 user          admin
 subscription  vlan-notification
 stream        vlan-notification
 received-time 2023-07-26T03:46:52.891423+00:00
 data vlan-status vlan-name vlanname1
 data vlan-status status 4
notifications received-notifications notification 2023-07-25T07:57:14.87+00:00 0
 user          admin
 subscription  vlan-notification
 stream        vlan-notification
 received-time 2023-07-26T03:46:52.89852+00:00
 data vlan-status vlan-name vlanname1
 data vlan-status status 4
notifications received-notifications notification 2023-07-25T09:51:21.922+00:00 0
 user          admin
 subscription  vlan-notification
 stream        vlan-notification
 received-time 2023-07-26T03:46:52.903818+00:00
 data vlan-status vlan-name vlanname2
 data vlan-status status 4
admin@upper-nso#