Luaスクリプト機能

概要

ヤマハルーターで Lua スクリプト( 参考: lua.org のホームページ )が実行できます。Lua スクリプトにヤマハルーター専用 API を埋め込むことで、ルーターの状態に応じて、ルーターの設定変更やアクションをプログラミングすることが可能になります。例えば、次のようなスクリプトを作成できます。

  • config のプログラム設定
  • 特定のアドレスへ通信できなくなったときに管理者へメールを送信する
  • トンネルがダウンしたときに経路を変更する

なお、ヤマハルーター専用 API はこちらのページで公開しています。API は随時追加していく予定です。また、ヤマハルーターが実装している Lua のバージョンは 5.1.4 または 5.1.5 です。詳細は Lua スクリプト機能バージョンの変更履歴を参照してください。

ヤマハが実装している Lua 言語の仕様については、Lua 言語の文法ライブラリ関数を参照してください。また、Lua チュートリアルはプログラミング初心者向けのチュートリアルです。

オリジナルの Lua 言語の仕様については、Lua 5.1 Reference Manual を参照してください。

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

ヤマハルーターでは以下の機種およびファームウェアで、Lua スクリプト機能をサポートしています。

機種 ファームウェア
RTX5000 Rev.14.00.15以降
RTX820 Rev.11.03.16以降
RTX1200 Rev.10.01.20以降
RTX800 Rev.10.01.20以降

Luaスクリプト機能バージョンの変更履歴

Lua スクリプト機能バージョンの変更履歴と、各機種のファームウェアリビジョンとの対比表です。

_RT_LUA_VERSION 変更内容 対応ファームウェア
RTX5000 RTX820 RTX1200 RTX800
"1.0" 初期リリース Rev.14.00.15
以降
Rev.11.03.16
以降
Rev.10.01.20
以降
Rev.10.01.20
以降
"1.01" 以下の機能を追加した
  • BIGNUM を使用できるようにした
  • ビット演算ライブラリを追加した
  • math ライブラリの一部の関数を使用できるようにした
"1.02" 以下の機能を追加した
  • ハードウェアライブラリを追加した
  • HTTPクライアント機能 ( rt.httprequest 関数 ) を追加した
"1.03" 以下の機能を追加した
  • 正規表現オブジェクトを生成する string.regexp 関数を新設した
    また、正規表現糖衣構文により、string.regexp 関数を呼び出せるようにした
  • 以下の各関数で、パターンとして正規表現オブジェクトを利用できるようにした
    • string.find
    • string.match
    • string.gmatch
    • string.gsub
    • string.split
    • rt.syslogwatch
  • 文字列をパターンで分割する string.split 関数を新設した
  • 引数列あるいは配列の要素を巡回する each 関数を新設した
Rev.10.01.25
以降
Rev.10.01.25
以降
"1.04" ハードウェアライブラリで、USBキーボードやUSBバーコードリーダーの出力を読み取れるようにした Rev.10.01.33
以降
Rev.10.01.33
以降
"1.05" 以下の変更をした
  • ベースとなる Lua をバージョン 5.1.5 にした
  • rt.mail 関数で、メール本文の先頭にルーターの情報を挿入するか否かを指定できるようにした
"1.06" LuaSocketに対応した。 Rev.10.01.55
以降
Rev.10.01.55
以降
"1.07" rt.command 関数で、コマンド実行のログを出力するか否かを指定できるようにした Rev.10.01.66
以降
Rev.10.01.66
以降

Lua スクリプト機能バージョンの新しいファームウェアは、基本的に以前のバージョンでサポートする機能を含みます。詳細は Lua 言語の文法ライブラリ関数を参照してください。

用語の定義

Lua タスク

Lua スクリプトを実行するためにルーターの OS に用意されている専用のタスクです。 lua コマンド用に 8 個、DOWNLOAD ボタンからの実行用に1個、Lua コンパイラ用に1個の計10個(*1)が予め用意されています。それぞれのタスクは独立しているので Lua タスクの最大数まで同時走行が可能です。

詳細

Lua スクリプトの実行方法と実行環境

管理ユーザー権限でルーターにログインして lua コマンドを実行したり、DOWNLOAD ボタンを押すことで指定した Lua スクリプトを開始させることができます。lua コマンド は Lua 標準の lua コマンドオプションのうち、標準入力 ( stdin ) をスクリプトの入力対象とする -i / - オプションや、パラメータなしの実行には対応していません。Lua スクリプトを開始させる手段には次のものがあります。

  • シリアルコンソール、および、TELNET / SSH クライアントからの lua コマンド実行
  • リモートセットアップ機能を利用した lua コマンド実行
  • GUI のコマンド実行画面からの lua コマンド実行
  • schedule at コマンドを利用した lua コマンドの自動実行 (定時実行やルーター起動時の実行など)
  • DOWNLOAD ボタンの長押し

lua コマンドの実行例を下記に挙げます。

(例 1) 外部メモリのスクリプトファイルを実行する。
# lua usb1:/sample.lua
(例 2) コマンドラインに記述したスクリプトを実行する。
# lua -e 'for i = 1, 10 do rt.command("no ip filter " .. i) end'
(例 3) 複数のスクリプトを連続的に実行する。
# lua -e 'rt.command("clear log")' -e 'rt.syslog("info", "スクリプト開始")' usb1:/sample.lua

lua コマンドは、指定した Lua スクリプトを開始させるトリガーに過ぎないため、Lua スクリプトの終了を待たずにコマンドプロンプトが返ります。そのため、同一コンソール上から連続的に同コマンドを実行して複数の Lua スクリプトを立ち上げることが可能です。ただし、同時に走行可能な Lua スクリプトの上限数は 8 です。Lua スクリプト機能では 1 度の lua コマンド実行につき 1 つの Lua タスクが割り当てられるため、同時に走行しているスクリプトの数だけ Lua タスクが使用されることになります。なお、(例 3) のように、1 度の lua コマンドで複数の Lua スクリプトを指定する場合は、複数の Lua スクリプトが 1つの Lua タスク内で指定した順番に実行されます。Lua スクリプトの走行状態や過去の実行状況などは show status lua コマンドから確認できます。また、走行中の Lua スクリプトを強制終了させたいときは、terminate lua コマンド を使用します。

実行した lua コマンドや Lua スクリプトの中に文法エラーがあった場合は、INFO タイプのエラーメッセージが SYSLOG に出力され、スクリプトの実行が中断されます。

[SYSLOG例]
2009/09/21 12:20:07: lua: mail.lua:26: 'rt.mail': 'text' field value of argument #1 is invalid.

また、スクリプトファイルの重複チェック等は行われないため、同時に同一のスクリプトファイルを指定して lua コマンドを実行した場合は、同一のスクリプトファイルが複数の Lua タスクで走行することになります。操作ミスをした場合は、terminate lua コマンド で不要な Lua タスクを強制終了させてください。

DOWNLOAD ボタンによる実行について

DOWNLOAD ボタンからはスクリプトファイルを 1 つだけ実行させることができます。lua コマンドのような複雑な操作は行えません。

DOWNLOAD ボタンを使用して Lua スクリプトを開始させる場合は 1 つの Lua タスクしか割り当てられません。ただし、lua コマンド の実行時に割り当てられる 8 個の Lua タスクとは別に DOWNLOAD ボタン専用の Lua タスクが用意してあるため、lua コマンド 用の Lua タスクに空きが無くても、DOWNLOAD ボタンから Lua スクリプトを開始させることができます。DOWNLOAD ボタンによる実行方法について下記に述べます。

  • operation button function download コマンドで Lua スクリプトの実行を DOWNLOAD ボタンの機能に割り当てておきます。
  • DOWNLOAD ボタンを 3秒以上押すと Lua スクリプトが開始されます。
    このとき "ピ" とアラームがなり、DOWNLOAD ランプが点滅を始めます。そして、Lua スクリプトが終了したときに "ピポピポ" とアラームがなり、DOWNLOAD ランプが消灯します。
  • Lua スクリプトの走行を途中で停止させたい場合は、DOWNLOAD ボタンを 1 秒以上押します。Lua スクリプトの走行が停止すると DOWNLOAD ランプが消灯します。このとき、DOWNLOAD ボタンを 3秒以上押し続けると再度 Lua スクリプトが開始されてしまうので、DOWNLOAD ランプが消灯したらボタンから手を放してください。
    なお、DOWNLOAD ボタンにより開始されたスクリプトも terminate lua コマンド で停止させることができます。この場合は、Lua スクリプトが停止したときに "ププププ" とアラームがなり、DOWNLOAD ランプが消灯します。
  • Lua スクリプトがエラー終了した場合は、"ププププ" とアラームがなり、DOWNLOAD ランプが点灯します。
    このとき、DOWNLOAD ボタンを 1 秒以上押すとエラー状態が解除され、DOWNLOAD ランプが消灯します。
  • DOWNLOAD ボタンにより開始された Lua スクリプトがまだ走行中のときに operation button function download コマンドを実行した場合は、パラメータ変更の有無に関わらず、走行中の Lua スクリプトは強制終了されます。
常駐型の Lua スクリプトについて

専用の Lua タスクで実行されるため、プログラムに終了がない常駐型の Lua スクリプトを走行させることが可能です。Lua タスクは CPU リソースの使用に制限を設けていますが、実行するスクリプトの内容によっては CPU 使用率が 100% 近く上がることがあります。したがって、スクリプトプログラムの方でも CPU 使用率が高くならないような配慮が必要です(参照 : 注意事項)。

ファイル I / O

スクリプトファイルはルーター内蔵のフラッシュ ROM ( RTFS )、または、外部メモリに保存できます。RTFS とは、ルーター内蔵のフラッシュ ROM 上に構築されているファイルシステムのことです。lua コマンドoperation button function download コマンドでスクリプトファイルを指定する場合は、その格納場所を絶対パス、もしくは、環境変数 PWD からの相対パスで指定します。絶対パス指定では、外部メモリを指すファイルパスには搭載している外部メモリポートに従い "usb1:" 、 "sd1:" というようなプレフィックスを付けます。外部メモリを示すプレフィックスが記述されていない場合は、RTFS を示すファイルパスと判別されます。相対パス指定では、環境変数 PWD により、外部メモリと RTFS のいずれかに判別されます。なお、スクリプトファイルの暗号化には対応していません。

ファイルシステムの操作方法は技術資料 ( RTFS / 外部メモリの利用 ) を参考にしてください。

(例 1) 内蔵フラッシュ ROM のスクリプトファイルを絶対パスで指定する。
# lua /lua/sample.lua
(例 2) 外部メモリのスクリプトファイルを絶対パスで指定する。
# lua usb1:/lua/sample.lua
(例 3) DOWNLOAD ボタンにより実行するスクリプトに外部メモリのスクリプトファイルを絶対パスで設定する。
# operation button function download execute lua usb1:/lua/sample.lua
(例 4) スクリプトファイルを相対パスで指定する。
# lua sample.lua

(例 4) は、PWD に "/lua" が設定されていれば (例 1) と同じ意味になり、"usb1:/lua" が設定されていれば (例 2) と同じ意味になります。

また、Lua 標準関数にあるファイル操作系関数も同様にルーター内蔵のフラッシュ ROM 、または、外部メモリを対象とすることができ、それぞれのデバイス上でファイルの生成と読み書きが行えます。ファイル操作系関数の引数のファイル名にも絶対パスと相対パスが使用できます。なお、フラッシュ ROM への頻繁な書き込みはデバイスの消耗を早めることになるので、繰り返しフラッシュ ROM への書き込みを行うようなスクリプトの実行には注意してください(参照 : 注意事項)。

(例) 内蔵フラッシュ ROM の in_file.txt の内容を USB メモリの out_file.txt へ書き込む。
-- スクリプト

fdr, err = io.open("/in_file.txt", "r")
if (not fdr) then
	print(err)
	os.exit(-1)
end
fdw, err = io.open("usb1:/out_file.txt", "w")
if (not fdw) then
	print(err)
	fdr:close()
	os.exit(-1)
end
str = fdr:read("*a")
fdw:write(str)
fdr:close()
fdw:close()

定義済みファイルディスクリプタの標準入力 ( stdin ) / 標準出力 ( stdout ) / エラー出力 ( stderr ) には対応していないため、それらを指定することはできません。ただし、Lua 標準関数の print( ) 関数は使用可能です。print( ) 関数の出力先は lua コマンドを実行したルーターコンソールになりますが、Lua スクリプトが schedule at コマンド、または、DOWNLOAD ボタンをトリガーにして実行されたときの print( ) 関数では何も出力されません。

Lua の標準関数

ヤマハルーターが実装している Lua のバージョンは 5.1.4 / 5.1.5 です。Lua 5.1.4 / 5.1.5 がサポートしている標準関数のうち、ヤマハルーターでは使用できない関数や使用方法に制限がある関数があります。ここに挙がっていない関数は標準の仕様で使用可能です。

使用できない関数

math ライブラリの関数 ( math.XXX )
  • _RT_LUA_VERSION が "1.0" のファームウェアでは、すべての関数が使用できません。
  • _RT_LUA_VERSION が "1.01" のファームウェアでは、一部の関数が使用できません。
    詳細はライブラリ関数のページを参照してください。
  • package.loadlib( )
  • io.popen( )
  • io.tmpfile( )
  • file:setvbuf( )
  • file:seek( )
  • os.execute( ) ( rt.command( ) で代用できます )
  • os.setlocale( )
  • os.tmpname( )
  • debug.debug( )

使用方法に制限がある関数

  • dofile( ) / loadfile( )
    標準入力には対応していないため、引数のファイル名は必ず指定してください。
  • require( )
    C のモジュールをロードすることはできないため、引数には Lua で記述されたモジュールの名前を指定してください。
  • string.format( )
    書式フォーマットの型変換指定子に e, E / f, F / g, G を使用することはできません。
  • io ライブラリ ( io.XXX )
    標準入力や標準出力には対応していないため、初期状態ではデフォルト入出力ファイルは設定されていません。デフォルト入出力ファイルに対する操作を行う場合は、io.input( )、および、io.output( ) でデフォルト入出力ファイルを予め設定しておく必要があります。なお、標準入力 ( stdin ) / 標準出力 ( stdout ) / エラー出力 ( stderr ) をファイルハンドルとして使用することはできません。
  • io.open( )
    モードに "r+" / "w+" / "a+" のように "+" を付加することはできません。また、RTFS は追記モードに対応していないため、オープン対象が内蔵フラッシュ ROM にあるファイルの場合、モードに "a" を指定することはできません。
  • io.read( ) / file:read( )
    書式フォーマットに "*n" を使用することはできません。
  • os.date( )
    isdst には対応していないため、フォーマット引数に "*t" が指定されたときに返すテーブルの isdst フィールドは常に false が設定されています。
  • os.time( )
    isdst には対応していないため、引数のテーブルフィールドに isdst があっても無視されます。

Lua のグローバル変数

Lua 標準では "_VERSION" のように予約済みのグローバル変数があり、それらはスクリプト内でその変数名を指定するだけで参照することができます。ここではルーター用に新たに追加している予約済みのグローバル変数について説明します。

_RT_LUA_VERSION
_RT_LUA_VERSION_NUM

ベースとなる Lua のバージョン ( _VERSION ) からさらに、ルーター独自のカスタマイズを加えた当機能のバージョンが設定されています。当機能の初期リリース時は _RT_LUA_VERSION には "1.0" という文字列が設定されており、当機能の仕様拡張やルーター用 API の追加に伴い、バージョン番号が上がっていきます。_RT_LUA_VERSION_NUM はバージョンを数値で表したもので、上一桁でメジャー番号、下二桁でマイナー番号を示す三桁の整数になっています。"1.0" の場合、_RT_LUA_VERSION_NUM == 100 となります。API を新旧のルーターファームウェアで使い分ける必要がある場合などに、当変数で切り分けることができます。

(例) _RT_LUA_VERSION_NUM により処理を分岐する。
-- スクリプト

if (_RT_LUA_VERSION_NUM >= 200) then
    -- 2.0 で対応している API を使う
else
    -- 2.0 より前のバージョンで対応している API を使う
end
_RT_FIRM_REVISION

ルーターファームウェアのリビジョンを示す文字列が設定されています。

(例) 各種バージョンの表示例
-- スクリプト

a = _RT_LUA_VERSION
b = _RT_LUA_VERSION_NUM
c = _RT_FIRM_REVISION
d = _VERSION

print("_RT_LUA_VERSION     : " .. a)
print("_RT_LUA_VERSION_NUM : " .. b)
print("_RT_FIRM_REVISION   : " .. c)
print("_VERSION            : " .. d)
[実行結果]

_RT_LUA_VERSION     : 1.0
_RT_LUA_VERSION_NUM : 100
_RT_FIRM_REVISION   : RTX1200 (China) Rev.10.01.33 (Thu Jul 28 15:25:19 2011)
_VERSION            : Lua 5.1

ルーターの環境変数

よく使うアドレスや文字列、もしくは、ルーターごとに異なる設定値などを、set コマンドで環境変数に設定しておくことができます。設定した環境変数は Lua 標準関数の os.getenv( ) で参照します。Lua スクリプトを各ルーターで共通化したい場合などに便利です。

(例) WAN 側のゲートウェイアドレスを環境変数に設定しておき、そのアドレスに PING を 5回投げる。
( config )
# set GATEWAY1=172.16.1.100
-- スクリプト

adr = os.getenv("GATEWAY1")
rt.command("ping -c 5 " .. adr)

次に、Lua スクリプト機能の内部で参照される環境変数について説明します。

LUA_INIT(大文字指定)

LUA_INIT には、Lua の開始時に事前に実行させるスクリプトを設定します。LUA_INIT が設定されている場合は、lua コマンド等で指定したスクリプトの開始前に必ずそのスクリプトが実行されるようになります。設定値は、先頭に "@" がある場合はスクリプトファイルを指すパスと認識され、それ以外はスクリプト文字列と認識されます。

(例 1) 初期化用スクリプトファイルを設定しておく。
# set LUA_INIT=@/lua/init.lua
(例 2) 初期化用スクリプトを設定しておく。設定値に特殊文字が入る場合はダブルクォーテーションまたはシングルクォーテーションで括る必要があります。
# set LUA_INIT='rt.command("clear log")'

LUA_INIT のデフォルト値は設定されていません。

LUA_PATH(大文字指定)

LUA_PATH には、Lua 標準関数の require( ) が Lua のモジュールをロードするために使用するパスを設定します。Lua ではモジュール名の置換記号として "?" を使いますが、ルーターコンソールで "?" を入力するとヘルプが表示されてしまうため、"?" を入力する前にエスケープシーケンスの "\" を入力してください。

ロードするモジュールが "usb1:/" 配下にある場合
# set LUA_PATH="usb1:/\?.lua;"

LUA_PATH が設定されていない場合は、" ./?.lua; " がデフォルトのパスとして使用されます。

(注) 当機能では、require( ) で C のモジュールをロードすることはできません。したがって、LUA_CPATH は使用されません。

PWD(大文字指定)

PWD には、スクリプトファイルを指す相対パスの基点となるパスを絶対パスで設定します。lua コマンド等でスクリプトファイルを相対パスで指定する場合、この PWD が基点になります。末尾の " / " はなくても構いません。
PWD が設定されていない場合は、" / " ( RTFS のルート ) がデフォルトのパスとして使用されます。

( 例 ) スクリプトファイルが置かれているパスを設定しておく。
# set PWD="/lua"

ヤマハルーター専用 API

ヤマハルーター専用 API を使用することで、ルーターの操作をプログラミングすることができます。API は随時追加していく予定です。

Lua 向けヤマハルーター専用 API の公開ページ

Lua コンパイラ ( Luac )

luac コマンドを実行することで Lua スクリプトをコンパイルしてバイトコード ( 中間言語 ) を生成できます。標準の luac コマンドオプションのうち、標準入力 ( stdin ) を入力対象とする - オプションには対応していません。Lua コンパイラは同時に 1 つだけ起動することができます。lua コマンドとは違い、コンパイルが終了するまでコマンドプロンプトは返らないため、実行中は "CTRL + C" で強制終了することができます。なお、luac コマンドshcedule at コマンドには指定できません。

( 例 )
# luac -o usb1:/script.out usb1:/script.lua

また、生成されたバイトコードファイルを lua コマンド等の実行対象ファイルに指定して実行することもできます。少しでも Lua スクリプトの実行負荷を下げたい場合や、保存しているスクリプトファイルを一見しただけではその内容がわからないようにしたい場合に有効な方法です。なお、ルーター上で生成したバイトコードだけが実行可能であり、Lua をインストールした PC 等で生成したバイトコードは実行できません。

( 例 )
# lua usb1:/script.out

注意事項

  • ルーター内蔵のフラッシュ ROM ( RTFS ) は実行対象のスクリプトファイルを保存する用途として使用してください。外部メモリやルーター内蔵のフラッシュ ROM への頻繁な書き込みはデバイスの消耗を早めることになるので、それらに繰り返し書き込みを行うようなスクリプトの実行には注意してください。 特にルーター内蔵のフラッシュ ROM については、頻繁にファイル書き込みを行ったことが原因で故障に至った場合、保証期間内であっても無償修理の保証対象外になります。
  • ヤマハルーターが実装している Lua のバージョンは 5.1.4 / 5.1.5 です。Lua 言語の仕様は Lua 5.1.4 / 5.1.5 の仕様に従います。なお、関数名や変数名に日本語 (SJIS 文字) を使用することはできません。
  • Lua スクリプト機能は CPU リソースの使用に制限を設けています。したがって、単純な無限ループをするだけのスクリプトを走行させても CPU 使用率は 100% にはなりません。しかし、負荷の高いコマンドを繰り返し実行するようなスクリプトを同時に多数走行させたりすると CPU 使用率が高くなり、他のルーター機能に影響を及ぼすことがあります。無限ループのように長時間に渡り繰り返し同じ処理を行わせる場合は、適度に rt.sleep( ) を挟むなどして CPU 使用率が高くならないように注意してください。rt.sleep( ) はタスクを休止状態にします。
  • Lua 言語の数値型定義 lua_Number は、標準の double 型 ( 64bit倍精度浮動小数点数型 ) から long 型 ( 32bit符号付整数型 )に変更しています。float 型 や double 型 で表現される数値は ヤマハルーターの Lua では扱えません。同様に、string.format( ) 関数等の書式フォーマットの型変換指定子に e, E / f, F / g, G を使用することはできません
  • 定義済みファイルディスクリプタの標準入力 ( stdin ) / 標準出力 ( stdout ) / エラー出力 ( stderr ) を Lua スクリプト内で使用することはできません。
  • Lua 標準関数の require( ) で C のモジュールをロードすることはできません。したがって、当機能では LUA_CPATH は使用されません。

コマンド

Lua スクリプト機能を有効にするか否かの設定

[書式]
lua use SWITCH
no lua use [SWITCH]
[設定値]
  • SWITCH
    • on ... 有効にする
    • off ... 無効にする
[説明]
  • Lua スクリプト機能を有効にするか否かを設定をする。
  • Lua スクリプトの走行中に当コマンドで Lua スクリプト機能を無効にした場合、走行中のすべての Lua スクリプトは強制終了される。
[初期値]
on

Lua スクリプトの実行

[書式]
lua [-e STAT] [-l MODULE] [-v] [--] [SCRIPT_FILE [ARGS ...]]
[設定値]
  • STAT ... スクリプト文字列
  • MODULE ... ロード ( require ) するモジュール名
  • SCRIPT_FILE ... スクリプトファイル名またはバイトコードファイル名を絶対パスもしくは相対パスで指定する
  • ARGS ... SCRIPT_FILE に渡す可変個引数
[説明]
  • Lua スクリプトを実行する。
    基本的な文法は Lua 標準の lua コマンドと同じであるが、標準入力 ( stdin ) をスクリプトの入力対象とする -i / - オプションと、パラメータなしの実行には対応していない。-v オプションはバージョン情報を出力する。-- オプションは記述したポイントでオプション処理を終了することを表し、SCRIPT_FILE や ARGS に "-" で始まるファイル名および文字列を指定できるようになる。なお、-e / -l / -v の各オプションは繰り返して複数個指定できるが SCRIPT_FILE よりも後に指定することはできない。SCRIPT_FILE は 1 つしか指定できず、SCRIPT_FILE を記述したポイント以降のパラメータはすべて無視される。このとき、エラーメッセージは出力されない。
  • SCRIPT_FILE に相対パスを指定した場合、環境変数 PWD を基点としたパスと解釈される。PWD は set コマンドで変更可能であり、初期値は "/" である。
[ノート]
  • 環境変数 LUA_INIT が設定されている場合は、そのスクリプトが最初に実行される。
  • SCRIPT_FILE にバイトコードファイルを指定する場合、ルーター上で生成したバイトコードだけが実行可能であり、Lua をインストールした PC 等で生成したバイトコードは実行できない。

Lua コンパイラの実行

[書式]
luac [-l] [-o OUTPUT_FILE] [-p] [-s] [-v] [--] SCRIPT_FILE [SCRIPT_FILE ..]
[設定値]
  • OUTPUT_FILE ... バイトコードの出力先のファイル名を絶対パスもしくは相対パスで指定する
  • SCRIPT_FILE ... コンパイル対象のスクリプトファイル名を絶対パスもしくは相対パスで指定する
[説明]
  • Lua コンパイラを実行し、バイトコードを生成する。
    基本的な文法は Lua 標準の luac コマンドと同じであるが、- オプションは指定できない。-l オプションは生成したバイトコードをリスト表示する。-p オプションは構文解析のみを行う。-s オプションはコメント等のデバッグ情報を取り除く。-v オプションはバージョン情報を出力する。-- オプションは記述したポイントでオプション処理を終了することを表し、SCRIPT_FILE に "-" で始まるファイル名を指定できるようになる。なお、SCRIPT_FILE を複数指定して、一つのバイトコードファイルにまとめることもできる。
  • SCRIPT_FILE / OUTPUT_FILE に相対パスを指定した場合、環境変数 PWD を基点としたパスと解釈される。PWD は set コマンドで変更可能であり、初期値は "/" である。
[初期値]
OUTPUT_FILE = luac.out ( 相対パス )

Lua スクリプトの走行状態の表示

[書式]
show status lua [INFO]
[設定値]
  • INFO ... 表示する情報の種類
    • running ... 走行中のスクリプトに関する情報
    • history ... 過去に走行したスクリプトに関する情報
    • 省略時、すべての情報を表示する
[説明]

現在の Lua スクリプトの走行状態や過去の走行履歴を表示する。この情報は lua use コマンドで Lua スクリプト機能を無効にするとクリアされる

  • Lua のバージョン情報
  • 走行中のスクリプト [ running ]
    • Lua タスク番号
    • 走行状態
      • RUN ... 走行中
      • SLEEP ... スリープ中
      • WATCH ... SYSLOG 監視中 ( Lua タスクはスリープしている )
      • COMMUNICATE ... 通信中 ( _RT_LUA_VERSION が "1.02" 以降のファームウェアで表示 )
      • TERMINATE ... 強制終了中
    • トリガー
      • lua コマンド
      • luac コマンド
      • スケジュール
      • DOWNLOAD ボタン
    • コマンドライン
    • スクリプトファイル名
    • 監視文字列 ( SYSLOG 監視中のとき)
    • 開始日時 / 走行時間
  • 過去に走行したスクリプト [ history ] ( 最新10種類まで新しい順に表示 )
    • トリガー
      • lua コマンド
      • luac コマンド
      • スケジュール
      • DOWNLOAD ボタン
    • コマンドライン
    • スクリプトファイル名
    • 走行回数 / エラー発生回数 / エラー履歴( 最新5回分まで新しい順に表示 )
    • 前回の開始日時 / 終了時間 / 走行結果
[表示例]
# show status lua
Luaライブラリバージョン:        Lua 5.1.4
Luaスクリプト機能バージョン:    1.0

[running]
LuaタスクID (状態):  1  (RUN)
走行トリガー:        'lua' コマンド
コマンドライン:      lua test.lua
スクリプトファイル:  /lua/test.lua
開始日時:            2009/09/21 16:41:01
経過時間:            6秒
-------------------------------------------------------------------------------
LuaタスクID (状態):  9  (SLEEP)
走行トリガー:        DOWNLOADボタンからの実行
スクリプトファイル:  usb1:/lua/test2.lua
開始日時:            2009/09/21 16:40:32
経過時間:            35秒

[history]
(1)
走行トリガー:        DOWNLOADボタンからの実行
スクリプトファイル:  usb1:/lua/mail.lua
走行回数:            1
エラー発生回数:      1
エラー履歴:
  2009/09/21 16:37:51: lua: mail.lua:36: 'rt.mail': 'smtp_address' field of arg
ument #1 doesn't exist.
初回の開始日時:      2009/09/21 16:37:51
前回の開始日時:      2009/09/21 16:37:51
前回の終了日時:      2009/09/21 16:37:51
前回の走行結果:      エラー終了
-------------------------------------------------------------------------------
(2)
走行トリガー:        'lua' コマンド
コマンドライン:      lua -e "print(rt.command(\"show environment\"))"
走行回数:            3
エラー発生回数:      0
初回の開始日時:      2009/09/21 16:35:47
前回の開始日時:      2009/09/21 16:36:57
前回の終了日時:      2009/09/21 16:36:57
前回の走行結果:      正常終了

Lua スクリプトの強制終了

[書式]
terminate lua TASK_ID
terminate lua file SCRIPT_FILE
[設定値]
  • TASK_ID ... 強制終了する Lua タスクの番号
    • all ... すべての Lua タスク番号
    • Lua タスクの番号 (1 .. 10)
  • SCRIPT_FILE ... 強制終了するスクリプトファイル名またはバイトコードファイル名を絶対パスもしくは相対パスで指定する
[説明]

指定した Lua タスク、または、Lua スクリプトを強制終了する。

  • 第1書式では、TASK_ID で指定された Lua タスクを強制終了する。Lua タスクの番号や実行しているスクリプトについては show status lua コマンドで確認できる。
  • 第2書式では、SCRIPT_FILE で指定されたパスとファイル名が完全に一致するスクリプトを実行しているすべての Lua タスクを強制終了する。SCRIPT_FILE に相対パスを指定した場合、環境変数 PWD を基点とする絶対パスに置換された後で対象の Lua タスクの検索が行われる。
  • lua コマンドの -e オプションを使用して、スクリプトファイルを使用せずに実行されているような Lua スクリプトを強制終了させる場合は、第1書式を使用する。

環境変数の設定

[書式]
set NAME=VALUE
no set NAME[=VALUE]
[設定値]
  • NAME ... 環境変数名
  • VALUE ... 設定値
[説明]

ルーターの環境変数を設定する。
環境変数名の命名規則は次の通りである。

  • 半角の英数字とアンダースコア "_"が使用できるが、アンダースコアまたは数字を最初の文字にすることはできない。
  • 変数名の長さに制限はないが、set コマンドはコマンドラインの最大長 4095 文字を超えて実行できない。
  • 英字の大文字 / 小文字を区別する。例えば、abc と Abc は別の変数として扱われる。

Lua スクリプト機能に関連するアラーム音を鳴らすか否かの設定

[書式]
alarm lua SWITCH
no alarm lua [SWITCH]
[設定値]
  • SWITCH
    • on ... 鳴らす
    • off ... 鳴らさない
[説明]

Lua スクリプト機能に関連するアラーム音を鳴らすか否かを選択する。

[初期値]
on

DOWNLOAD ボタンを押した時に実行する機能の設定 (仕様拡張)

[書式]
operation button function download FUNCTION [SCRIPT_FILE [ARGS ...]]
no operation button function download [FUNCTION] [SCRIPT_FILE [ARGS ...]]
[設定値]
  • FUNCTION ... DOWNLOADボタンを押した時に実行する機能
    • http revision-up ... HTTPリビジョンアップ
    • execute batch ... バッチファイルの実行
    • mobile signal-strength ... 携帯端末の電波の受信レベルの取得
    • execute lua ... Lua スクリプトの実行
  • SCRIPT_FILE ... スクリプトファイル名またはバイトコードファイル名を絶対パスもしくは相対パスで指定する
  • ARGS ... SCRIPT_FILE に渡す可変個引数
[説明]
  • DOWNLOAD ボタンを押した時に実行する機能を設定する。機能実行中は DOWNLOAD ボタンの下のランプが点灯し、機能の実行が完了すると消灯する。
  • FUNCTION に execute lua を設定した場合、SCRIPT_FILE を必ず指定する必要がある。SCRIPT_FILE に相対パスを指定した場合、環境変数 PWD を基点としたパスと解釈される。PWD は set コマンドで変更可能であり、初期値は "/" である。
[ノート]

Lua スクリプトを実行させる場合、環境変数 LUA_INIT が設定されていれば SCRIPT_FILE よりも先に LUA_INIT のスクリプトが実行される。

[初期値]
http revision-up

スケジュールの設定 (仕様拡張)

[書式]
schedule at ID [DATE] TIME * COMMAND ..
schedule at ID [DATE] TIME pp PEER_NUM COMMAND ..
schedule at ID [DATE] TIME tunnel TUNNEL_NUM COMMAND ..
no schedule at ID [[DATE] ..]
[設定値]
  • ID ... スケジュール番号
  • DATE ... 日付 (省略可)
    • 月/日
    • 省略時は */* とみなす
  • TIME ... 時刻
    • hh:mm[:ss] ... 時(0..23 または *) : 分(0..59 または *) : 秒(0..59)、秒は省略可
    • startup ... 起動時
    • usb-attached ... USB デバイス認識時
  • PEER_NUM
    • 相手先情報番号
    • anonymous
  • TUNNEL_NUM ... トンネルインターフェイスの番号
  • COMMAND ... 実行するコマンド (制限あり)
[説明]
  • TIME で指定した時刻に COMMAND で指定されたコマンドを実行する。
    第2、第3書式で指定された場合には、それぞれあらかじめ指定された相手先情報番号 / トンネル番号での、 pp select / tunnel select コマンドが発行済みであるように動作する。
    schedule at コマンドは複数指定でき、同じ時刻に指定されたものは id の小さな順に実行される。
  • TIME は hh:mm 形式で指定されたときは秒指定なしとみなされ、hh:mm:ss 形式で指定されたときは秒指定ありとみなされる。秒数に "-" を用いた範囲指定や "*" による全指定をすることはできない。
  • 以下のコマンドは指定できない。
    administrator、 administrator password、 cold start、 console info と console prompt を除く console で始まるコマンド、 date、 exit、 help、 http revision-up go、 INTERFACE reset、 less で始まるコマンド、 login password、 login timer、 luac、 ping、 ping6、 pp select、 provider interface dns server、provider INTERFACE name、 quit、 remote setup、 save、 schedule at、 show で始まるコマンド、 telnet、time、 timezone、 traceroute、 traceroute6、 tunnel select
[ノート]
  • 入力時、 COMMAND パラメータに対して TAB キーによるコマンド補完は行うが、シンタックスエラーなどは実行時まで検出されない。schedule at コマンドにより指定されたコマンドを実行する場合には、何を実行しようとしたかを INFO タイプの SYSLOG に出力する。
  • DATE に数字と曜日を混在させて指定はできない。
  • startup を指定したスケジュールはルーター起動時に実行される。電源を入れたらすぐ発信したい場合などに便利。
[設定例]

ウィークデイの 8:00 ~ 17:00 だけ接続を許可する

# schedule at 1 */mon-fri 8:00 pp 1 isdn auto connect on
# schedule at 2 */mon-fri 17:00 pp 1 isdn auto connect off
# schedule at 3 */mon-fri 17:05 * disconnect 1

毎時 0 分から 15 分間だけ接続を許可する

# schedule at 1 *:00 pp 1 isdn auto connect on
# schedule at 2 *:15 pp 1 isdn auto connect off
# schedule at 3 *:15 * disconnect 1

今度の元旦にルーティングを切替える

# schedule at 1 1/1 0:0 * ip route NETWORK gateway pp 2

毎日 12 時から 13 時の間だけ 20 秒間隔で Lua スクリプトを実行する

# schedule at 1 12:*:00 * lua script.lua
# schedule at 2 12:*:20 * lua script.lua
# schedule at 3 12:*:40 * lua script.lua

設定例

ルーターの再起動時にリブート情報をメールで送信する

[config に必要な設定]
schedule at 1 startup * lua /lua/restart.lua

ルーターの起動時に Lua スクリプトを実行するスケジュールを設定します。その他、基本的な経路設定などは既に設定されているものとします。

[Lua スクリプト]
-- ### restart.lua ###

------------------------------------------------------------
-- ルーターコマンドを実行し、出力結果を整形して返す関数   --
------------------------------------------------------------
function exec_command(cmd)
	local rtn, str
	local text

	rtn, str = rt.command(cmd)
	if (rtn) and (str) then
		text = string.format("\"%s\"の実行結果\r\n\r\n%s\r\n", cmd, str)
	else
		text = string.format("\"%s\"の実行失敗\r\n\r\n", cmd)
	end

	return text
end

------------------------------------------------------------
-- メイン部分                                             --
------------------------------------------------------------
mail_table = {
	smtp_address = "smtp.xxxx.co.jp",            -- 適宜変更
	from = "rt-admin@xxxx.co.jp",                -- 適宜変更
	to = "rt-admin@xxxx.co.jp",                  -- 適宜変更
	subject = "ルーターが再起動しました"
}

-- 情報収集
mail_table.text = exec_command("show status boot all")
mail_table.text = mail_table.text .. exec_command("show log")

-- メール送信
rt.mail(mail_table)

上記の restart.lua というテキストファイルを作成し、RTFS の /lua 配下に保存しておきます。保存方法はこちらを参照してください。

[スクリプトの説明]
  • /lua/restart.lua
    "show status boot all" と "show log" の実行結果を管理者にメールで送信するスクリプトです。このスクリプトを起動時に実行させるようにスケジュールの設定をしておけば、ルーターが再起動したことをすぐに知ることができ、解析に必要な情報も一緒に得られます。

WAN の通信状況に応じて QoS を設定し、一定間隔で監視状況をメールで送信する

[ネットワーク構成]
  • 本社-東京支社間でIPsec-VPN接続
  • 東京支社はプロバイダへ端末型接続
  • パケットロスが多い時間帯だけ QoS をかける
ネットワーク構成
[東京支社ルーターの config 例 ]
set GATEWAY=172.16.10.254
set LUA_INIT=@/lua/init.lua
set PWD=/lua/tokyo
 
ip route default gateway 172.16.10.254
ip route 192.168.1.0/24 gateway tunnel 1
ip lan1 address 192.168.2.1/24
ip lan2 address 172.16.10.1/24
ip lan2 nat descriptor 1
 
tunnel select 1
 ipsec tunnel 101
  ipsec sa policy 101 1 esp aes-cbc sha-hmac anti-replay-check=off
  ipsec ike always-on 1 on
  ipsec ike pre-shared-key 1 text PASSWORD
  ipsec ike remote address 1 172.16.2.1
 tunnel enable 1
ipsec auto refresh on
 
nat descriptor type 1 masquerade
nat descriptor address outer 1 primary
nat descriptor masquerade static 1 1 192.168.2.1 udp 500
nat descriptor masquerade static 1 2 192.168.2.1 esp
[config の説明]
set GATEWAY=172.16.10.254
set LUA_INIT=@/lua/init.lua
set PWD=/lua/tokyo

スクリプトで使用する環境変数の設定です。

[Lua スクリプト]
-- ### init.lua ###

rt.command("clear log")
rt.syslog("info", "[スクリプト開始]")

上記の init.lua というテキストファイルを作成し、RTFS の /lua 配下に保存しておきます。
保存方法はこちらを参照してください。

-- ### ping.lua ###

adr = os.getenv("GATEWAY")

------------------------------------------------------------
-- n 回 PING を実行し、ロス率を返す関数                   --
------------------------------------------------------------
function exec_ping(n)
	local ping_cmd
	local rtn, str
	local loss

	ping_cmd = string.format("ping -c %s -w 0.5 %s", n, adr)
	rtn, str = rt.command(ping_cmd)
	if (not rtn) or (not str) then
		-- エラー
		return -1
	end

	loss = string.match(str, "(%d+)%.%d+%%")     -- パケットロス率(NNN.N%)の整数部を抽出
	if (not loss) then
		loss = -1
	else
		loss = tonumber(loss)
	end

	return loss
end

------------------------------------------------------------
-- IPsec パケットを優先するための QoS を設定/解除する関数 --
------------------------------------------------------------
function set_qos(set)
	local no = ""

	if (not set) then
		no = "no "
	end

	rt.command(no .. "queue class filter 1 4 ip * * udp 500")
	rt.command(no .. "queue class filter 2 4 ip * * esp")
	rt.command(no .. "queue lan2 class filter list 1 2")
	rt.command(no .. "speed lan2 80m")           -- 上り速度を考慮した値で
	rt.command(no .. "queue lan2 type priority")
	rt.command("save")
end

------------------------------------------------------------
-- メイン部分                                             --
------------------------------------------------------------
local rtn, str

cnt = 1
qos = false
show_cmd = "show status qos all"
mail_table = {
	smtp_address = "smtp.xxxx.co.jp",            -- 適宜変更
	from = "admin-tokyo@xxxx.co.jp",             -- 適宜変更
	to = "admin-tokyo@xxxx.co.jp",               -- 適宜変更
	subject = "Ping Status",
	text = ""
}

while (1) do
	set_qos_flag = false

	-- 10分間休止
	rt.sleep(600)

	text = os.date("%Y年%m月%d日 %H時%M分%S秒: PING 実行結果\r\n")

	loss = exec_ping(arg[1])

	if (loss < 0) then
		text = text .. "PING 実行エラー"
	else
		text = text .. string.format("宛先:%s パケットロス率:%d%%", adr, loss)

		if (loss >= 10) then
			if (not qos) then
				set_qos(true)
				set_qos_flag = true
				qos = true
				text = text .. "\r\nQoS を設定しました"
			end
		elseif (loss == 0) then
			if (qos) then
				set_qos(false)
				qos = false
				text = text .. "\r\nQoS を解除しました"
			end
		end
	end

	-- SYSLOG へ記録
	rt.syslog("info", text)
	text = text .. "\r\n"

	-- 6 回分をまとめてメール通知
	mail_table.text = mail_table.text .. text .. "\r\n"
	if (cnt < 6) then
		cnt = cnt + 1
	else
		-- QoS の設定がある場合だけ"show status qos"の出力結果をメール本文に追加
		-- ただし、QoS設定直後は意味がないので除く
		if (qos) and (not set_qos_flag) then
			rtn, str = rt.command(show_cmd)
			if (rtn) and (str) then
				text = string.format("# %s\r\n%s", show_cmd, str)
				mail_table.text = mail_table.text .. text
			end
		end

		-- メール送信
		if (not rt.mail(mail_table)) then
			rt.syslog("info", "Failed rt.mail by Lua")
		end

		-- メール送信が終わったらリセット
		cnt = 1
		mail_table.text = ""
	end
end

上記の ping.lua というテキストファイルを作成し、RTFS の /lua/tokyo 配下に保存しておきます。
保存方法はこちらを参照してください。

[スクリプトの説明]
  • /lua/init.lua
    LUA_INIT に設定する 初期化用スクリプトです。SYSLOG を初期化します
  • /lua/tokyo/ping.lua
    メインのスクリプトです。スクリプトの内容は次の通りです。
    無限ループするスクリプトなので、rt.sleep( ) が入っていることに注意してください。
    • 10 分おきに WAN 側ゲートウェイアドレスへ任意の回数 PING を送信する。
    • PING のパケットロス率が 10 % 以上のとき、IPsec パケットを優先するための QoS を設定する。
    • PING のパケットロス率が 1 % 未満のとき、QoS の設定を解除する。
    • 毎回の PING の実行結果を SYSLOG に記録する。
    • 一定回数分の PING の実行結果をまとめて管理者へメールで送信する。
    • メール送信時に QoS の設定があったときは、"show status qos all" の出力結果をメール本文に追加する。
[スクリプトの実行例]
# lua ping.lua 30

東京支社ルーターにシリアルや TELNET 経由でログインし、仮に PING の送信回数を 30 回とするなら、コマンド入力画面で上記のように入力します。PWD に "/lua/tokyo" が設定されているため、ファイルパスは "/lua/tokyo/ping.lua" と解釈されます。ping.lua は無限ループをするので、途中で終了させたい場合は terminate lua コマンドを使います。

SYSLOG メッセージ

本機能において出力される SYSLOG メッセージを以下に示します。実際に出力されるメッセージには "[LUA]" というプレフィックスが付加されます。ヤマハルーター専用 API で出力される SYSLOG メッセージについては、Lua 向けヤマハルーター専用 APIのページを参照してください。

レベル 出力メッセージ 意味
INFO Lua script function was enabled. Lua スクリプト機能を有効にした。
Lua script function was disabled. Lua スクリプト機能を無効した。
DEBUG created Lua Task(N) Lua タスク番号 N の Lua タスクを生成した。
terminated Lua Task(N) Lua タスク番号 N の Lua タスクを強制終了した。
closed Lua Task(N): success Lua タスク番号 N の Lua タスクを終了した。実行したスクリプトは正常に終了した。
closed Lua Task(N): failure Lua タスク番号 N の Lua タスクを終了した。実行したスクリプトはエラー終了した。

関連文書

ページトップへ戻る