RESTCONF プロトコルの前提条件
-
RESTCONF に対して Cisco IOS-HTTP サービスを有効にします。詳細については、『RESTCONF RPC の例』を参照してください。
この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章では、HTTP ベースの Representational State Transfer コンフィギュレーション プロトコル(RESTCONF)を設定する方法を説明します。RESTCONF は、設定データ、状態データ、データ モデルに固有のリモート プロシージャ コール(RPC)操作、および YANG モデルで定義されているイベントにアクセスするための、標準的なメカニズムに基づく、プログラミングが可能なインターフェイスを提供します。
RESTCONF に対して Cisco IOS-HTTP サービスを有効にします。詳細については、『RESTCONF RPC の例』を参照してください。
RESTCONF プロトコルには、次の制約事項が適用されます。
通知およびイベント ストリーム
YANG パッチ
フィルタ、開始時、停止時、再生、アクションなどのオプションのクエリ パラメータ
RESTCONF 機能は、デュアル IOSd 設定またはソフトウェア冗長性を実行しているデバイスではサポートされていません。
RESTCONF プログラマブル インターフェイスについて
このセクションでは、構成をネットワーク デバイスにプログラムを使用して書き込めるようにする、プロトコルおよびモデリング言語について説明します。
RESTCONF:構造化データ(XML または JSON)および YANG を使用して REST ライクな API を提供します。これによりさまざまなネットワーク デバイスにプログラムを使用してアクセスできます。RESTCONF API は HTTPs メソッドを使用します。
YANG:モデル構成および操作機能に使用されるデータ モデリング言語。YANG は、NETCONF および RESTCONF API によって実行できる関数の有効範囲と種類を決定します。
Cisco IOS XE Fuji 16.8.1 よりも前のリリースでは、運用データ マネージャ(ポーリングに基づく)が個別に有効になっていました。Cisco IOS XE Fuji 16.8.1 以降のリリースでは、運用データは、NETCONF を実行しているプラットフォームで動作し(設定データの仕組みと同様)、デフォルトで有効になっています。運用データのクエリまたはストリーミングに対応するコンポーネントの詳細については、GitHub リポジトリで命名規則の *-oper を参照してください。
ステートレス プロトコルである HTTPS ベースの RESTCONF プロトコル(RFC 8040)は、セキュアな HTTP メソッドを使用して、YANG 定義データが含まれる概念データストア(NETCONF データストアを実装するサーバと互換性がある)で CREATE、READ、UPDATE、および DELETE(CRUD)操作を提供します。
次の表では、RESTCONF 操作に NETCONF プロトコル操作を関連付ける方法を示しています。
オプション |
サポートされているメソッド |
---|---|
GET |
読み取り |
PATCH |
更新 |
PUT |
作成または置換 |
POST |
作成または操作(リロード、デフォルト) |
DELETE |
ターゲット リソースの削除 |
HEAD |
ヘッダー メタデータ(応答本文なし) |
RESTCONF デバイスは、RESTCONF 属性を含むリンク要素である /.well-known/host-meta リソースにより、RESTCONF API のルートを決定します。
RESTCONF デバイスは、要求 URI のパスの最初の部分として RESTCONF API ルート リソースを使用します。
例:
Example returning /restconf:
The client might send the following:
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond as follows:
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
URI の例:
GigabitEthernet0/0/2:https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2
fields=name:https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2?fields=name
depth=1:https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet?depth=1
Name と IP:https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet/ip/address/primary;name
MTU(フィールド):https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet(mtu)
MTU:https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/mtu
ポートチャネル:https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/Port-channel
「Char」から「Hex」への変換チャート:http://www.columbia.edu/kermit/ascii.html
API リソースは、+restconf に位置する上位リソースです。これは次のメディア タイプをサポートします。
(注) |
メディアは、RESTCONF サーバ(XML または JSON)に送信される YANG 形式 RPC のタイプです。 |
application/yang-data+xml または application/yang-data+json
API リソースには、RESTCONF DATASTORE および OPERATION リソースの RESTCONF ルート リソースが含まれます。次に例を示します。
The client may then retrieve the top-level API resource, using the
root resource "/restconf".
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}
詳細については、RFC 3986 を参照してください
メソッドは、ターゲット リソースで実行される HTTPS 操作(GET/PATCH/POST/DELETE/OPTIONS/PUT)です。YANG 形式 RPC は、RESTCONF サーバに存在するターゲット YANG モデルに関連する指定のリソースに対して、特定のメソッドを呼び出します。Uniform Resource Identifier(URI)は指定されたリソースのロケーション ID として機能するため、クライアントの RESTCONF メソッドは、その特定のリソースを探して、HTTPS のメソッドまたはプロパティで指定されたアクションを実行することができます。
詳細については、 「RFC 8040:RESTCONF プロトコル」を参照してください。
RESTCONF プログラマブル インターフェイスの設定方法
NETCONF 接続と RESTCONF 接続は、認証、許可、およびアカウンティング(AAA)を使用して認証する必要があります。その結果、権限レベル 15 のアクセスで定義された RADIUS または TACACS + ユーザに、システムへのアクセスが許可されます。
コマンドまたはアクション | 目的 | |
---|---|---|
ステップ 1 |
enable 例:
|
特権 EXEC モードをイネーブルにします
|
ステップ 2 |
configure terminal 例:
|
グローバル コンフィギュレーション モードを開始します。 |
ステップ 3 |
aaa new-model 例:
|
AAA をイネーブルにします。 |
ステップ 4 |
aaa group server radius server-name 例:
|
RADIUS サーバを追加し、サーバ グループ RADIUS コンフィギュレーション モードを開始します。
|
ステップ 5 |
server-private ip-address key key-name 例:
|
プライベート RADIUS サーバの IP アドレスと暗号キーを設定します。 |
ステップ 6 |
ip vrf forwarding vrf-name 例:
|
AAA RADIUS または TACACS+ サーバ グループの Virtual Route Forwarding(VRF)参照情報を設定します。 |
ステップ 7 |
exit 例:
|
サーバ グループ RADIUS コンフィギュレーション モードを終了し、グローバル コンフィギュレーション モードに戻ります。 |
ステップ 8 |
aaa authentication login default group group-namelocal 例:
|
ログイン時に、指定されたグループ名をデフォルトのローカル AAA 認証として設定します。 |
ステップ 9 |
aaa authentication login list-name none 例:
|
システムへのログイン中に認証が不要であることを指定します。 |
ステップ 10 |
aaa authorization exec default group group-namelocal 例:
|
許可を実行して、EXEC シェルの実行がユーザに許可されているかどうかを確認します。 |
ステップ 11 |
aaa session-id common 例:
|
指定のコールに対して送信されたセッション ID 情報が同じになるようにします。 |
ステップ 12 |
line console number 例:
|
設定する特定の回線を識別し、ライン コンフィギュレーション モードを開始します。 |
ステップ 13 |
login authentication authentication-list 例:
|
ログインに対する AAA 認証をイネーブルにします。 |
ステップ 14 |
end 例:
|
回線コンフィギュレーション モードを終了します。続いて、特権 EXEC モードに戻ります。 |
RESTCONF インターフェイスを使用するには、次の作業を行います。
コマンドまたはアクション | 目的 | |
---|---|---|
ステップ 1 |
enable 例:
|
特権 EXEC モードを有効にします。
|
ステップ 2 |
configure terminal 例:
|
グローバル コンフィギュレーション モードを開始します。 |
ステップ 3 |
restconf 例:
|
ネットワーク デバイスで RESTCONF インターフェイスを有効にします。 |
ステップ 4 |
ip http secure-server 例:
|
セキュア HTTP(HTTPS)サーバをイネーブルにします。 |
ステップ 5 |
end 例:
|
グローバル コンフィギュレーション モードを終了し、特権 EXEC モードを開始します。 |
スタートアップ コンフィギュレーションを使用してデバイスが起動すると、 nginx プロセスが実行中になります。ただし、DMI プロセスは有効にはなりません。
Device# show platform software yang-management process monitor
COMMAND PID S VSZ RSS %CPU %MEM ELAPSED
nginx 27026 S 332356 18428 0.0 0.4 01:34
nginx 27032 S 337852 13600 0.0 0.3 01:34
NGINX は、プロキシ Web サーバとして機能する内部 Web サーバで、Transport Layer Security(TLS)ベースの HTTPS を提供します。HTTPS を介して送信された RESTCONF 要求は、最初に NGINX プロキシ Web サービスによって受信され、さらに要求が構文/セマンティックチェックのために confd Web サーバに転送されます。
Device# show platform software yang-management process
confd : Not Running
nesd : Not Running
syncfd : Not Running
ncsshd : Not Running
dmiauthd : Not Running
nginx : Running
ndbmand : Not Running
pubd : Not Running
restconf コマンドが設定されている場合、nginx プロセスが再起動され、DMI プロセスが起動されます。
次の show platform software yang-management process コマンドの出力例は、nginx プロセス と DMI プロセスが起動して実行中であることを示しています。
Device# show platform software yang-management process
confd : Running
nesd : Running
syncfd : Running
ncsshd : Not Running ! NETCONF-YANG is not configured, hence ncsshd process is in not running.
dmiauthd : Running
vtyserverutild : Running
opdatamgrd : Running
nginx : Running ! nginx process is up due to the HTTP configuration, and it is restarted when RESTCONF is enabled.
ndbmand : Running
Device#show platform software yang-management process monitor
COMMAND PID S VSZ RSS %CPU %MEM ELAPSED
confd 28728 S 860396 168496 42.2 4.2 00:12
confd-startup.s 28448 S 19664 4496 0.2 0.1 00:12
dmiauthd 29499 S 275356 23340 0.2 0.5 00:10
ndbmand 29321 S 567232 65564 2.1 1.6 00:11
nesd 29029 S 189952 14224 0.1 0.3 00:11
nginx 29711 S 332288 18420 0.6 0.4 00:09
nginx 29717 S 337636 12216 0.0 0.3 00:09
pubd 28237 S 631848 68624 2.1 1.7 00:13
syncfd 28776 S 189656 16744 0.2 0.4 00:12
AAA と RESTCONF インターフェイスが設定され、nginx プロセスと関連する DMI プロセスが実行中になった後、デバイスは RESTCONF 要求を受信できる状態になります。
Device# show netconf-yang sessions
R: Global-lock on running datastore
C: Global-lock on candidate datastore
S: Global-lock on startup datastore
Number of sessions : 1
session-id transport username source-host global-lock
--------------------------------------------------------------------------------
19 netconf-ssh admin 2001:db8::1 None
Device# show netconf-yang sessions detail
R: Global-lock on running datastore
C: Global-lock on candidate datastore
S: Global-lock on startup datastore
Number of sessions : 1
session-id : 19
transport : netconf-ssh
username : admin
source-host : 2001:db8::1
login-time : 2018-10-26T12:37:22+00:00
in-rpcs : 0
in-bad-rpcs : 0
out-rpc-errors : 0
out-notifications : 0
global-lock : None
RESTCONF プログラマブル インターフェイスの設定例
root:~# curl -i -k -X "OPTIONS" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity" \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 15:27:57 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Allow: DELETE, GET, HEAD, PATCH, POST, PUT, OPTIONS >>>>>>>>>>> Allowed methods
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Accept-Patch: application/yang-data+xml, application/yang-data+json
Pragma: no-cache
root:~#
POST 操作では、ターゲット デバイスに存在しないコンフィギュレーションが作成されます。
(注) |
実行コンフィギュレーションで logging monitor コマンドを使用できないことを確認してください。 |
次の POST 要求の例では logging monitor alerts コマンドを使用しています。
Device:~# curl -i -k -X "POST" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "alerts"
> }'
HTTP/1.1 201 Created
Server: nginx
Date: Mon, 23 Apr 2018 14:53:51 GMT
Content-Type: text/html
Content-Length: 0
Location: https://10.85.116.30/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 14:53:51 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495231-97239
Pragma: no-cache
Device:~#
指定されたコマンドがデバイスに存在しない場合は、POST 要求によって作成されます。ただし、実行コンフィギュレーションにすでに存在する場合は、この要求によってコマンドが置き換えられます。
次の PUT 要求の例では logging monitor warnings コマンドを使用しています。
Device:~# curl -i -k -X "PUT" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "warnings"
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 14:58:36 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 14:57:46 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495466-326956
Pragma: no-cache
Device:~#
次の PATCH 要求の例では logging monitor informational コマンドを使用しています。
Device:~# curl -i -k -X "PATCH" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "native": {
> "logging": {
> "monitor": {
> "severity": "informational"
> }
> }
> }
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 15:07:56 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 15:07:56 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-496076-273016
Pragma: no-cache
Device:~#
次の GET 要求の例では logging monitor informational コマンドを使用しています。
Device:~# curl -i -k -X "GET" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity" \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 15:10:59 GMT
Content-Type: application/yang-data+json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
{
"Cisco-IOS-XE-native:severity": "informational"
}
Device:~#
Device:~# curl -i -k -X "DELETE" "https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 15:26:05 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 15:26:05 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-497165-473206
Pragma: no-cache
linux_host:~#
関連項目 |
マニュアル タイトル |
---|---|
IOS-XE、IOS-XR、および NX-OS プラットフォームのさまざまなリリースの YANG データ モデル |
開発者にわかりやすい方法で Cisco YANG モデルにアクセスするには、GitHub リポジトリを複製し、vendor/cisco サブディレクトリに移動します。ここでは、IOS XE、IOS-XR、および NX-OS プラットフォームのさまざまなリリースのモデルを使用できます。 |
標準/RFC |
タイトル |
---|---|
RFC 6020 |
YANG:Network Configuration Protocol(NETCONF)向けデータ モデリング言語 |
RFC 8040 |
Representational State Transfer Configuration Protocol(RESTCONF) |
説明 |
リンク |
---|---|
シスコのサポート Web サイトでは、シスコの製品やテクノロジーに関するトラブルシューティングにお役立ていただけるように、マニュアルやツールをはじめとする豊富なオンライン リソースを提供しています。 お使いの製品のセキュリティ情報や技術情報を入手するために、Cisco Notification Service(Field Notice からアクセス)、Cisco Technical Services Newsletter、Really Simple Syndication(RSS)フィードなどの各種サービスに加入できます。 シスコのサポート Web サイトのツールにアクセスする際は、Cisco.com のユーザ ID およびパスワードが必要です。 |
The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
機能名 |
リリース |
機能情報 |
---|---|---|
RESTCONF プロトコル |
Cisco IOS XE Everest 16.6.1 |
RESTCONF は、YANG モデルで定義されている設定データ、状態データ、データモデル固有の RPC の操作およびイベント通知にアクセスするための、標準メカニズムに基づくプログラマチック インターフェイスを提供します。 この機能が次のプラットフォームで追加されました。
次のコマンドが導入または変更されました:ip http server および restconf |
Cisco IOS XE Fuji 16.8.1a |
Cisco IOS XE Fuji 16.8.1a では、この機能は次のプラットフォームに実装されていました。
|
|
Cisco IOS XE Fuji 16.9.2 |
Cisco IOS XE Fuji 16.9.2 では、この機能は次のプラットフォームに実装されていました。
|
|
Cisco IOS XE Gibraltar 16.11.1 |
Cisco IOS XE Gibraltar 16.11.1 では、この機能は次のプラットフォームに実装されていました。
|