カスタムGUI

$Date: 2024/03/29 17:41:10 $

概要
対応機種とファームウェアリビジョン
詳細
コマンド
SYSLOGメッセージ一覧

概要

カスタムGUIとは、ルーターの設定を行うためのGUI (WWWブラウザに対応するユーザインタフェース) をユーザが独自に設計し組み込むことができる機能です。ルーターにはホストからHTTPで設定を転送するためのインタフェースが用意されており、ユーザはJavaScriptを使用してGUIを作成します。

ヤマハルーターにはWeb GUIが搭載されていますが、ユーザごとに設定画面を変更することはできませんでした。本機能では、カスタムGUIを複数組み込み、ログインするユーザによって画面を切り替えることが可能です。

本ドキュメントでは、最初にGUIデータの保存先について記述し、保存した複数のデータをログインユーザごとに切り替えるための設定方法を解説します。続いて、具体的なカスタムGUIの作成方法について説明し、最後に本機能で使用するコマンド一覧を掲載します。

対応機種とファームウェアリビジョン

ヤマハRTシリーズでは以下の機種およびファームウェアで、カスタムGUIをサポートしています。

機種	ファームウェア
RTX1300	すべてのリビジョン
RTX1220
RTX830
NVR510
NVR700W
RTX1210
FWX120
RTX810
NVR500
RTX1200	Rev.10.01.16以降
SRT100	Rev.10.00.52以降

本機能では、作成したGUIデータ (HTMLファイルなど) の保存先としてルーターの内蔵フラッシュROM (RTFS) または外部メモリを使用することができます。httpd custom-gui userコマンドでユーザごとに基点となるディレクトリを設定する場合、絶対パスもしくは環境変数PWDを用いた相対パスを入力します。絶対パスと相対パスの具体的な指定方法についてはRTFSの外部仕様書を参照してください。

ログインユーザによるGUIの切り替え

WWWブラウザからルーターのトップページにアクセスするとBasic認証のダイアログが表示されます。ここで入力するユーザ名に応じてブラウザに出力するGUIを変更させることができます。以下では、具体例を挙げてルーターの設定方法と動作を解説します。

設定の概要

カスタムGUIを使用するユーザとしてuser1、user2、user3、無名ユーザの4名を登録し、各ユーザの基点となるディレクトリを以下の表のように設定します。

ユーザ名	メディア	基点となるディレクトリ
user1	内蔵フラッシュROM (RTFS)	/gui/user1
user2	内蔵フラッシュROM (RTFS)	/gui/user2
user3	USBメモリ	usb1:/gui/user3
無名ユーザ	内蔵フラッシュROM (RTFS)	/gui/anonymous

ルーターの設定

最初にlogin userコマンドでログインユーザの登録を行います。無名ユーザを登録する必要はありません。

# login user user1 user1
# login user user2 user2
# login user user3 user3

次に、各ユーザが使用するGUIデータをhttpd custom-gui userコマンドで設定します。

ユーザuser1は内蔵フラッシュROM (RTFS) の/gui/user1を使用するので、directoryに/gui/user1を指定します。indexには「/ (スラッシュ)」止めのURLでアクセスした場合に表示するファイル名を指定します。ここではdefault.htmlとしておきます。

# httpd custom-gui user user1 directory=/gui/user1 index=default.html

ユーザuser2の場合も同様に設定します。

# httpd custom-gui user user2 directory=/gui/user2 index=default.html

無名ユーザの場合はユーザ名を省略します。

# httpd custom-gui user directory=/gui/anonymous index=default.html

setコマンドを使用してディレクトリに相対パスを指定する場合は以下のようになります。

# set PWD=/gui
# httpd custom-gui user user1 directory=user1 index=default.html
# httpd custom-gui user user2 directory=user2 index=default.html
# httpd custom-gui user directory=anonymous index=default.html

ユーザuser3はUSBメモリ内のデータを使用するので、以下のようになります。

# httpd custom-gui user user3 directory=usb1:/gui/user3 index=default.html

以上に加えて、以下の設定が必要となります。

httpd serviceコマンドで、HTTPサーバ機能が有効になっていること
httpd hostコマンドで、ホストからルーターへのアクセスが許可されていること
user attributeコマンドで、各ユーザのconnection属性にHTTPが含まれていること。
CUIのコマンドで管理者権限が必要な操作をカスタムGUIから行う場合、user attributeコマンドで各ユーザのadministrator属性が以下になっていること。

administrator = 2(RTX1300)
administrator = on(上記以外)

httpd custom-gui useコマンドがonになっていること。

動作

IPアドレスが192.168.100.1であるルーターのトップページ (http://192.168.100.1/) にアクセスし、各ユーザ名でログインした場合の動作を解説します。

トップページの認証ダイアログからユーザuser1でログインすると、http://192.168.100.1/custom/user1/にリダイレクトされ、/gui/user1/default.htmlが出力されます。

/custom/user1以下の他のURLにアクセスした場合は、/gui/user1を基点としてファイルが参照されます。以下に例を挙げます。

URL	参照されるファイルパス
http://192.168.100.1/custom/user1/nat/	/gui/user1/nat/default.html
http://192.168.100.1/custom/user1/tunnel/template.html	/gui/user1/tunnel/template.html

ユーザuser2、user3の場合も同様となります。なお、無名ユーザの場合のURLはhttp://192.168.100.1/custom/anonymous.user/となります。

httpd custom-gui userコマンドが設定されているユーザがルーターに内蔵されている通常のGUIにアクセスすることはできません。URLを直接入力して通常のGUIにアクセスしても、カスタムGUIへはリダイレクトされず認証エラーとなります。

ログインユーザの権限

ユーザごとのカスタムGUIを表示するには一般権限 (ユーザ名+ログインパスワード) でログインする必要があります。管理権限 (ユーザ名+管理パスワード) では表示することができません。

CUIのコマンドで管理権限が必要な操作をカスタムGUIから行う場合は、一般権限でのログインに続いて管理権限でログインする必要があります。詳しくは、ホストからルーターへの設定転送で解説します。

GUIの作成方法

ルーターの設定を行うためのGUIを作成する方法について解説します。なお、HTTPプロトコルやHTML、JavaScriptについて基本的な知識を持っていることが前提となります。

ホストからルーターへの設定転送

PCなどのホストからルーターへの設定転送は、/custom/executeに対してPOSTメソッドをリクエストすることで行います。設定内容はPOSTメソッドのコンテント部分に記述します。データ形式は、CUIで使用するルーターのコマンドを1つずつ改行コードで区切ったものとなります。改行コードはCRLFです。

Internet Explorer 8からルーターにリクエストを送信した場合の例を以下に示します。

POST /custom/execute HTTP/1.1
Accept: */*
Accept-Language: ja
Referer: http://192.168.100.1/custom/anonymous.user/
Content-Type: text/plain
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; .NET4.0E; InfoPath.3)
Host: 192.168.100.1
Content-Length: 69
Connection: Keep-Alive
Cache-Control: no-cache
Authorization: Basic Og==

#2450035272
ip lan2 address 10.0.0.1/8
syslog debug on
show config

コンテント部分の1行目はセッションIDです。これはGUIデータの取得時にルーターから提供される値で、セキュリティ上の理由 (CSRF対策) から必ずコンテント部分の先頭行に記述しなければなりません。この値が存在しなかったり、ルーターの保持する値と一致しなかったりした場合は設定が反映されず、506 CGI Permission Deniedがサーバから返されます。この値の取得方法についてはGUIのサンプルで解説します。

管理者権限が必要なコマンドを含むリクエストを送信した場合コマンドは実行されず、認証ダイアログが表示されます。ここで改めて管理者権限でログインする必要があります。

実行結果の取得

コマンドを実行した結果はPOSTリクエストのリプライとして、テキスト形式でルーターから送信されます。内容は、CUIからコマンドを入力した場合に出力されるメッセージと同一です。例えば、show configを実行すれば設定されているコマンド一覧が表示されます。また、間違ったコマンドを入力すればエラーメッセージが表示されます。

実行結果を取得する際にエコーバックのON/OFFを選択することができます。エコーバックONの場合には入力したコマンドと実行結果の両方が出力されます。エコーバックOFFの場合には実行結果のみ出力されます。エコーバックOFFで、実行結果として表示する内容が無い場合は何も出力されません。

エコーバックはデフォルトでOFFになっています。ONにする場合は、POSTリクエストのコンテント部分2行目 (セッションIDの次の行) に#echoback=onと記述します。

ホストからルーターへの設定転送で例として送信したリクエストに対するリプライを、エコーバックON/OFFそれぞれの場合で以下に示します。

エコーバックONの場合

入力したコマンドと出力内容がすべて転送されます。

HTTP/1.0 200 OK
Date: Sun, 18 Oct 2009 21:40:42 GMT
Expires: Sun, 18 Oct 2009 21:40:42 GMT
Server: YAMAHA-RT
Allow: HEAD, GET, POST
Content-Type: text/plain;charset=shift_jis

# ip lan2 address 10.0.0.1/8
# syslog debug on
# show config
# RTX1200 Rev.10.01.16 (Tue Sep 29 15:44:22 2009)
# MAC Address : 00:a0:de:37:b5:04, 00:a0:de:37:b5:05, 00:a0:de:37:b5:06
# Memory 128Mbytes, 3LAN, 1BRI
# main:  RTX1200 ver=b0 serial=D26009558 MAC-Address=00:a0:de:37:b5:04 MAC-Address=00:a0:de:37:b5:05 MAC-Address=00:a0:de:37:b5:06
# Reporting Date: Oct 19 06:40:42 2009
login password *
administrator password *
login user user1 *
ip lan1 address 192.168.0.1/24
ip lan2 address 10.0.0.1/8
syslog debug on
httpd custom-gui user user1 directory=/gui/user1 index=default.html
#

エコーバックOFFの場合

show configの出力内容のみが転送されます。

HTTP/1.0 200 OK
Date: Sun, 18 Oct 2009 21:40:42 GMT
Expires: Sun, 18 Oct 2009 21:40:42 GMT
Server: YAMAHA-RT
Allow: HEAD, GET, POST
Content-Type: text/plain;charset=shift_jis

# RTX1200 Rev.10.01.16 (Tue Sep 29 15:44:22 2009)
# MAC Address : 00:a0:de:37:b5:04, 00:a0:de:37:b5:05, 00:a0:de:37:b5:06
# Memory 128Mbytes, 3LAN, 1BRI
# main:  RTX1200 ver=b0 serial=D26009558 MAC-Address=00:a0:de:37:b5:04 MAC-Address=00:a0:de:37:b5:05 MAC-Address=00:a0:de:37:b5:06
# Reporting Date: Oct 19 06:40:42 2009
login password *
administrator password *
login user user1 *
ip lan1 address 192.168.0.1/24
ip lan2 address 10.0.0.1/8
syslog debug on
httpd custom-gui user user1 directory=/gui/user1 index=default.html

ログアウト

ヤマハルーターのHTTPサーバでは、同一のIPアドレスから複数のユーザが同時にログインできないようになっています。このため、一旦あるユーザがログインした後に同一のホストから他のユーザがログインするためには、ログインタイマが満了するまで待つかログアウトの処理を行わなければなりません。

カスタムGUIでログアウト処理を行うには、コンテント部分の1行目にセッションIDを、2行目に#logoutと記述したPOSTリクエストを/custom/executeに送信します。正しくログアウトできれば、200 OKがサーバから返されます。

注意点として、ログアウト処理後はすぐにブラウザを終了させてください。続けて他のページにアクセスすると、再びログインの処理が行われてしまいます。

カスタムGUIから実行できないコマンド

以下のコマンドをカスタムGUIから実行することはできません。

administrator
administrator password
administrator password encrypted
copy
copy config
copy exec
delete
execute batch
exit
'|' でgrepを連結したコマンド
'|' でlessを連結したコマンド
lessで始まるコマンド
login password
login password encrypted
make directory
password reenter
ping
ping6
quit
remote setup
rename
rtfs format
rtfs garbage collect
scp
show techinfo
ssh
sshd host key generate
telnet
traceroute
traceroute6

統計情報のグラフ

カスタムGUIはCUIのコマンドを利用することが前提となっているため、ルーターのほぼすべての機能に関して設定や状態参照をすることが可能です。しかし、統計情報についてはCUIのコマンドではデータを取得できず、Web GUIの「統計情報」のページからグラフを表示するか、外部メモリにデータを書き出す必要があります。

このような事情から、インラインフレームなどを使ってカスタムGUIに組み込むことを想定した専用の統計情報ページを用意しています。Web GUIの「統計情報」ページでは複数のグラフが一度に表示されますが、カスタムGUI専用の統計情報ページではURLパラメータを指定することで、特定のグラフのみを取得することができます。

URLの指定方法は以下のようになります。

http://(ルーターのIPアドレス)/custom/stat_graph.html?type=type[&span=SPAN][&if=INTERFACE][&class=CLASS]

typeパラメータにはグラフの種類を指定します。設定値と意味は以下の通りです。

設定値	意味
cpu	CPU利用率
memory	メモリー利用率
flow	ファストパスのフロー数
route	経路数
nat	NATエントリー数
filter	ポリシーフィルターまたは動的フィルターのセッション数
traffic	トラフィック統計
qos	QoS統計

spanパラメータにはデータの取得間隔を指定します。取得できるデータの最大数は一定なので、間隔を指定することで取得期間も決定されます。設定値と意味は以下の通りです。

設定値	意味
1s	1秒間隔、過去2分間
1m	1分間隔、過去2時間
12m	12分間隔、過去1日間
6h	6時間間隔、過去30日間

ifパラメータにはlan1、pp1、tunnel1などのインタフェース名を指定します。

classパラメータにはQoSのクラスを指定します。

span、if、classの各パラメータについては、typeパラメータの設定値によって指定しなければならないものが変わります。対応関係は以下の通りです。

typeパラメータの設定値	必要となるパラメータ
cpu、memory、flow、route、filter	span
nat、traffic	span、if
qos	if、class

typeがQoS統計の場合の取得期間は10秒間隔、過去20分間固定となります。

通信のシーケンス

ルーターのトップページにアクセスしてから、設定を転送し、実行結果を取得するまでのシーケンスは以下のようになります。

+----------+                                          +----------+
|  ホスト  |                                          | ルーター |
+-----+----+                                          +-----+----+
      |                                                     |
      |     http://192.168.100.1/にアクセスし、ログイン     |
      |---------------------------------------------------->|
      |                                                     |
      |   http://192.168.100.1/custom/user/にリダイレクト   |
      |<----------------------------------------------------|
      |                                                     |
      |     /custom/executeに設定をPOST                     |
      |---------------------------------------------------->|
      |                                                     |
      |     実行結果を送信                                  |
      |<----------------------------------------------------|
      |                                                     |

GUIのサンプル

カスタムGUIのサンプルを紹介します。なお、JavaScriptやHTMLについての詳しい情報は、参考書や解説サイトなどを参照してください。

ルーターの設定コマンドをコンテント部分に記したPOSTリクエストを送信するには、JavaScriptのXMLHttpRequestオブジェクトを使用します。ルーターから送信される実行結果はresponseTextプロパティにセットされます。
セッションIDを取得するには、/custom/custom_gui_lib.jsを外部ファイルとして読み込み、getSessionId()メソッドを呼び出します。このメソッドの戻り値がセッションIDとなります。

サンプルファイルはこちらです。シナリオとしては、拠点側ルーターをPPPoEでインターネットに接続し、センター側ルーターとIPsecでトンネルを張るというものです。

設定用APIをブラウザ以外のHTTPクライアントから利用する

/custom/execute (REST API) に設定をPOSTするには、CSRF対策のためにセッションIDを付加しなければなりません。PerlやRubyなどの言語を使って作成した簡易的なHTTPクライアントからルーターの設定を行おうとする場合、セッションIDを取得するためにJavaScriptのエンジンを搭載する必要がありますが、これは容易ではありません。

本機能ではWWWブラウザ以外のHTTPクライアントから設定を行うことを考慮して、セッションIDを付加する必要のないREST APIを別途用意しています。URLは/custom/apiとなります。

このAPIを使用するには、以下の設定が必要となります。

httpd custom-gui api useコマンドがonになっていること。
httpd custom-gui api passwordコマンドでパスワードが設定されていること。

HTTPクライアントが/custom/apiに対してルーターの設定コマンドをPOSTする場合には、httpd custom-gui api passwordコマンドで設定したパスワードをURLパラメータで指定します。

例としてパスワードがdoremiの場合のURLは以下のようになります。

http://(ルーターのIPアドレス)/custom/api?password=doremi

このURLにアクセスする場合、Basic認証は必要ありません。また、前述の通りセッションIDを必要とせずCSRF対策が行われていないため、ブラウザからはアクセスしないでください。

なお、/custom/apiに対するリクエストでエコーバックをONにするには、コンテント部分の1行目に#echoback=onと記述します。

日本語について

/custom/executeに対して日本語などのマルチバイト文字を含むコマンド (descriptionコマンドなど) をPOSTした場合、下記の表に記載のリビジョン以降のファームウェアでないとコマンドが正しく実行されない可能性があります。これは、XMLHttpRequestを使用してマルチバイト文字を送信する場合の文字コードは通常UTF-8になりますが、下記の表に記載のリビジョン以前のファームウェアではPOSTされたデータをShift_JISとして処理してしまうためです。

機種	ファームウェア
NVR500	Rev.11.00.16以降
RTX1200	Rev.10.01.32以降
SRT100	Rev.10.00.60以降

なお、上記の表に記載されていない機種については、対応機種とファームウェアリビジョンに記載のリビジョンから、POSTされたマルチバイト文字をUTF-8として処理するようになっており、この問題が発生することはありません。

/custom/apiに対して日本語などのマルチバイト文字を含むコマンド (descriptionコマンドなど) をPOSTする場合は、クライアント側で文字コードがShift_JISとなるように設定してください。

外部メモリのファイル操作では日本語を含むファイル名やディレクトリ名を指定することが可能ですが、本機能ではURLに日本語が含まれている場合、正しく動作しません。

コマンド

環境変数の設定
[書式]

set NAME=VALUE

no set NAME[=VALUE]

[設定値]
- NAME ... 環境変数名
- VALUE ... 設定値
[説明]
ルーターの環境変数を設定する。

環境変数名の命名規則は次の通りである。
- 半角の英数字とアンダースコア '_' が使用できるが、アンダースコアまたは数字を最初の文字にすることはできない。
- 変数名の長さに制限はないが、setコマンドはコマンドラインの最大長 (4095文字) を超えて実行できない。
- 英字の大文字、小文字を区別する。例えば、abcと Abcは別の変数として扱われる。
[ノート]

環境変数 "PWD" の設定値がファイル操作コマンドにおける相対パスの基点となる。"PWD" が設定されていない場合、相対パスの基点はフラッシュROM (RTFS) のルートディレクトリ '/' となる。
カスタムGUIを使用するか否かの設定
[書式]

httpd custom-gui use USE

no httpd custom-gui use [USE]

[設定値]
- USE
  - on ... 使用する
  - off ... 使用しない
[説明]

カスタムGUIを使用するか否かを設定する。

[初期値]

off
カスタムGUIを使用するユーザの設定
[書式]

httpd custom-gui user [USER] directory=PATH [index=NAME]

no httpd custom-gui user [USER...]

[設定値]
- USER ... ユーザ名
- PATH ... 基点となるディレクトリの絶対パスまたは相対パス
- NAME ... スラッシュ '/' 止めのURLでアクセスした場合に出力するファイル名
[説明]

カスタムGUIを使用するユーザを設定する。http://(ルーターのIPアドレス)/にアクセスし、本コマンドで登録されているユーザ名でログインするとhttp://(ルーターのIPアドレス)/custom/USER/にリダイレクトされる。

USERを省略した場合には無名ユーザに対する設定となる。この場合のURLはhttp://(ルーターのIPアドレス)/custom/anonymous.user/となる。

PATHには基点となるディレクトリを絶対パス、もしくはsetコマンドを用いた相対パスで指定する。NAMEにはブラウザから '/' 止めのURLでアクセスした場合に表示するファイル名を指定する。

[ノート]

本コマンドを設定する場合、無名ユーザ以外は事前にlogin userコマンドでユーザを登録しておく必要がある。登録されていないユーザに対して本コマンドを設定するとエラーになる。

外部メモリにおいて自動検索機能は使用できない。また、NAMEにスラッシュ '/' を含む文字列を指定することはできない。

本コマンドが設定されているユーザは、ルーターに内蔵されている通常のGUIにアクセスすることができない。

[初期値]

index=index.html
カスタムGUIのAPIを使用するか否かの設定
[書式]

httpd custom-gui api use USE

no httpd custom-gui api use [USE]

[設定値]
- USE
  - on ... 使用する
  - off ... 使用しない
[説明]

API用のURL "http://(ルーターのIPアドレス)/custom/api" に対するPOSTリクエストを受け付けるか否かを設定する。

[ノート]

API用のURLを使用するには、本コマンドに加えてhttpd custom-gui use onが設定されている必要がある。

本コマンドをonにしてもhttpd custom-gui api passwordコマンドを設定しなければAPI用のURLを使用することはできない。

[初期値]

off
カスタムGUIのAPIにアクセスするためのパスワードの設定

[書式]

httpd custom-gui api password PASSWORD

no httpd custom-gui api password [PASSWORD]

[設定値]

PASSWORD ... パスワード

[説明]

API用のURLへPOSTリクエストを送信する際のパスワードを設定する。32文字以内で半角英数字を使用することができる。

例えば、本コマンドでパスワードとしてdoremiを設定した場合、URLはhttp://(ルーターのIPアドレス)/custom/api?password=doremiとなる。

SYSLOGメッセージ一覧

レベル	出力メッセージ	意味
INFO	Login succeeded for HTTP: IP_ADDR USER_NAME	IPアドレスがIP_ADDRであるユーザUSER_NAMEがルーターのHTTPサーバにログインした。
	'administrator' succeeded for HTTP: IP_ADDR USER_NAME	IPアドレスがIP_ADDRであるユーザUSER_NAMEが管理ユーザに昇格した。
	Logout from HTTP: IP_ADDR USER_NAME	IPアドレスがIP_ADDRであるユーザUSER_NAMEがルーターのHTTPサーバからログアウトした。
DEBUG	[CUSTOM_GUI] Execute 'COMMAND'	カスタムGUI機能でコマンドCOMMANDを実行した。