NSO: RESTCONF API Introduction

[Tomonobu Okada]

• RESTCONF とは
• RESTCONF の準備
• 実行サンプル
• Root リソースの確認
• Capability の取得
• データへのアクセス
• データの更新
• Action の実行
• Query API
• リファレンス

 

RESTCONF とは

NSO 4.4 など比較的新しいバージョンでは RESTCONF API をサポートしています。

RESTCONF は YANG で定義されたデータにアクセスする RESTFul なインターフェースを提供する HTTP をベースにしたプロトコルです。データストアのオペレーションは以下のように NETCONF に似ていますが、NETCONF のトランスポートが SSH であるのに対し RESTCONF は HTTP ベースであること、RESTCONF では JSON 形式もサポートしているなど違いがあります。

また、NSO は元々 REST API をサポートしていて RESTCONF と非常に似ていますが、NSO の REST API が独自の実装であるのに対し RESTCONF は RFC8040 で標準化されたプロトコルという違いがあります。

RESTCONF の準備

RESTCONF を有効にするためには ncs.conf に以下の設定を加えて適用してください。

  <restconf>
    <enabled>true</enabled>
  </restconf>

Root リソースはデフォルトでは /restconf ですが、必要に応じて変更することも可能です。

  <restconf>
    <enabled>true</enabled>
    <root-resource>my_own_restconf_root</root-resource>
  </restconf>

RFC8040 に定義されているとおり、root リソースは以下の方法で取得することが可能です。

curl -s 'http://admin:admin@localhost:8080/.well-known/host-meta'
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
    <Link rel='restconf' href='/my_own_restconf_root'/>
</XRD>

実行サンプル

RESTCONF は HTTP ベースですので、テストには curl や Postman などのツールが使用できます。ここでは curl を使用していくつかのサンプルを実行してみます。

本記事では NSO 4.5.2 と curl 7.54.0 を使用しています。

Root リソースの確認

curl -s 'http://admin:admin@localhost:8080/restconf/'
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <data/>
  <operations/>
  <yang-library-version>2016-06-21</yang-library-version>
</restconf>

コンフィグデータにアクセスする場合は data リソースを、action などの operational リソースにアクセスする場合は operations リソースを使用します。

Capability の取得

RFC8040 に記載されているとおり、RESTCONF サーバの capability を確認するには data/restconf-state/capabilities にアクセスします。

curl -s 'http://admin:admin@localhost:8080/restconf/data/restconf-state/capabilities'
<capabilities xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"  xmlns:rcmon="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
  <capability>urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit</capability>
  <capability>urn:ietf:params:restconf:capability:depth:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:fields:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:with-defaults:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:filter:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:replay:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:yang-patch:1.0</capability>
  <capability>http://tail-f.com/ns/restconf/collection/1.0</capability>
  <capability>http://tail-f.com/ns/restconf/query-api/1.0</capability>
</capabilities>

データへのアクセス

curl -s 'http://admin:admin@localhost:8080/restconf/data/devices/device=router0/config/interface/Loopback'
 
<Loopback xmlns="urn:ios"  xmlns:ios="urn:ios"  xmlns:ncs="http://tail-f.com/ns/ncs">
  <name>0</name>
  <ip>
  <address>
  <primary>
    <address>127.0.0.1</address>
    <mask>255.0.0.0</mask>
  </primary>
</address>
</ip>
</Loopback>

 データの更新

まずは commit dryrun を実行します。

curl -s -X PUT 'http://admin:admin@localhost:8080/restconf/data/devices/device=router0/config/interface/Loopback=0/ip/address/primary?dryrun=cli' -H "Content-Type: application/yang-data+xml" -d '<primary><address>127.0.0.2</address><mask>255.0.0.0</mask></primary>'
<dryrun-result xmlns='http://tail-f.com/ns/rest/dryrun'>
<cli>
<local-node>
<data>
devices {
     device router0 {
         config {
             ios:interface {
                 Loopback 0 {
                     ip {
                         address {
                             primary {
-                                address 127.0.0.1;
+                                address 127.0.0.2;
                             }
                         }
                     }
                 }
             }
         }
     }
}
</data>
</local-node>
</cli>
</dryrun-result>

Commit します。

curl -s -X PUT 'http://admin:admin@localhost:8080/restconf/data/devices/devig/interface/Loopback=0/ip/address/primary' -H "Content-Type: application/yang-data+xml" -d '<primary><address>127.0.0.2</address><mask>255.0.0.0</mask></primary>'

変更を確認します。

curl -s  'http://admin:admin@localhost:8080/restconf/data/devices/device=router0/config/interface/Loopback=0/ip/address/primary'

<primary xmlns="urn:ios"  xmlns:ios="urn:ios"  xmlns:ncs="http://tail-f.com/ns/ncs">
  <address>127.0.0.2</address>
  <mask>255.0.0.0</mask>
</primary>

Action の実行

sync-from を実行する例です。アクションなので operations リソースを使用しています。

curl -s -X POST 'http://admin:admin@localhost:8080/restconf/operations/devices/device=router0/sync-from'
<output xmlns='http://tail-f.com/ns/ncs'>
  <result>true</result>
</output>

IOS NED の live-status exec show コマンドの実行例です。

curl -s -X POST 'http://admin:admin@localhost:8080/restconf/operations/devices/device=router0/live-status/exec/show' -H "Content-Type: application/yang-data+xml" -d '<input><args>version</args></input>'
<output xmlns='urn:ios-stats'>
  <result>
> show version&#13;
Cisco IOS Software, NETSIM&#13;
router0# </result>
</output>

Query API

基本的には REST API と同様です、ただし URI が異なります（tailf/query を指定します）。

http://admin:admin@localhost:8080/restconf/tailf/query

リファレンス

• RFC8040 RESTCONF Protocol: http://www.ietf.org/rfc/rfc8040.txt
• NSO Northbound APIs の Chapter 4. The RESTCONF API のセクション
• examples.ncs/getting-started/developing-with-ncs/13-restconf