class Net::Telnet

要約

このクラスは telnet のクライアント機能を提供します。

telnet でリモートホストにログインしてシェル経由でコマンドを実行することを考えてみましょう。これを Net::Telnet で実現するためには、まず Net::Telnet.new に "Host" オプションを与えてオブジェクトを作り、 Net::Telnet#login でユーザ名とパスワードを送ってログインし、 Net::Telnet#cmd でコマンドを実行、最後に IO#close で接続を閉じます。 Net::Telnet#waitfor, Net::Telnet#print, Net::Telnet#puts, Net::Telnet#write などといったメソッドはより複雑なことをする場合にのみ使ってください。

Net::Telnet のオブジェクトは SMTP や HTTP のような telnet でないサービスにも利用できます。この場合には Net::Telnet.new に "Port" オプションを与えることでポートを指定する必要があるでしょう。また、 "Telnetmode" オプションに false を渡すことで telnet のコマンド列を解釈しないようにしなければなりません。Net::Telnet#login は普通うまく動かないので、認証をプログラマ自身が実装する必要があります。

通信プロトコルによっては、Net::Telnet.new に"Prompt" を渡しておいて Net::Telnet#cmd をうまく動作させることができるかもしれません。また、Net::Telnet#cmd を呼ぶごとに "Match" を指定しても同様のことができます。また、Net::Telnet#puts や Net::Telnet#waitfor を直接使ってやりとりすることもできます。それでうまくいかない場合は、 IO#sysread を直接呼ぶ必要があるかもしれません。

Net::Telnet.new には "Proxy" オプションで指定したオブジェクトを通して通信をすることができます。 "Proxy" オプションに Net::Telnet のオブジェクトを渡した場合には、通信路が共用されます。Socket のような読み書き可能な IO オブジェクトを渡した場合には、そのオブジェクトを通してやり取りが行われます。この機能はユニットテストをする場合などに便利でしょう。

使用例

ログインしてコマンドを送る例、リモートホストから返ってきた文字列はすべて標準出力に表示する

require 'net/telnet'

# リモートホスト "foobar" に接続
# タイムアウトは 10 秒
localhost = Net::Telnet.new("Host" => "localhost",
                            "Timeout" => 10)

# ログインし、プロンプトが出るまで待ち合わせる
telnet.login("your name", "your password") {|c| print c}

# ls コマンドを実行し、実行後、プロンプトが出るまで待ち合わせる
telnet.cmd("ls") {|c| print c}

# sleep で 5 秒
telnet.cmd("sleep 5 && echo foobar &") {|c| print c}

STDOUT.flush # <- これがないとここまで処理が来てることがわかりにくい

# 前のコマンドの出力を待ち合わせる
telnet.waitfor(/foobar\Z/) {|c| print c}

# ログインセッションの終了
telnet.cmd("exit") {|c| print c}
telnet.close

POP サーバにメールが来ているかどうかを見る。リモートホストからきた文字列はすべて標準出力に表示

require 'net/telnet'

# リモートホスト(POPサーバ) "foobar" に接続
# ポート番号は110(POPのwell-knownポート)、
# "Telnetmode" は off (telnet用の特殊なバイト列を解釈しない)、
# Prompt (コマンドの区切り) は POP の仕様により /^\+OK/n とする
pop = Net::Telnet.new("Host" => "foobar",
                      "Port" => 110,
                      "Telnetmode" => false,
                      "Prompt" => /^\+OK/n)
# 認証をする
# Net::Telnet#login は使えない(ログインのコマンドが異なる)ので
# Net::Telnet#cmd でユーザ名とパスワードを送る
pop.cmd("user " + "your_username") { |c| print c }
pop.cmd("pass " + "your_password") { |c| print c }

# list コマンドで来ているメールを表示する
pop.cmd("list") { |c| print c }

# 終了する
pop.close

目次

特異メソッド

• new

インスタンスメソッド

• binmode
• binmode=
• close
• cmd
• login
• preprocess
• print
• puts
• sock
• telnetmode
• telnetmode=
• waitfor
• write

継承しているメソッド

SimpleDelegatorから継承しているメソッド

• __getobj__
• __setobj__

Delegatorから継承しているメソッド

• !
• !=
• ==
• freeze
• marshal_dump
• marshal_load
• method_missing
• methods
• protected_methods
• public_methods
• respond_to?
• respond_to_missing?

特異メソッド

new(opts) -> Net::Telnet[permalink][rdoc]

new(opts) {|message| ... } -> Net::Telnet

Telnet オブジェクトを生成します。

このときリモートホストへの接続も行います("Proxy"を指定しない場合)。 opts には Telnet オブジェクトに設定する以下のオプションをハッシュで指定します。オプションは省略時にはそれぞれ右に示すデフォルト値が適用されます。

"Host"       => "localhost"
"Port"       => 23
"Prompt"     => /[$%#>] \z/n
"Timeout"    => 10  # 接続待ちタイムアウト値(sec)
"Waittime"   => 0   # Prompt を待ち合わせる時間。この値を nil にしてはいけません
"Binmode"    => false
"Telnetmode" => true
"Output_log" => nil # ログの出力ファイル名
"Dump_log"   => nil # 出力ファイル名
"Proxy"      => nil # Net::Telnet または IO のオブジェクトを指定する

それぞれの意味は以下の通りです。

"Host" 接続するホストのホスト名もしくはIPアドレスを文字列で指定します。デフォルトは "localhost" です。

"Port" 接続するポート番号です。デフォルトは23です。

"Binmode" これを偽にすると、改行を変換します。ホストへの LF は CRLF に変換され、ホストからの CRLF は LF に変換されます。これを真にすると、変換をしません。この変換は Net::Telnet#binmode でも無効化できます。ホストへ送る文字列の変換は Net::Telnet#puts と Net::Telnet#puts に適用され、Net::Telnet#write には適用されません。改行の変換に関しては telnet の SGA と BIN オプションにも影響されることに注意してください。

"Prompt" コマンドライン上のプロンプトを表わす正規表現を指定します。これはホストからの出力が終了し、ホストが新しい入力を待っているかどうかを判断するために必要となります。

"Output_log" 接続状態メッセージや受け取った通信を記録するファイル名を指定します。通常の Telnet セッションでは、ログにはサーバ側からエコーされたクライアントからの入力を含みます。エコーがないようなプロトコルの場合はクライアントからの入力はログに含まれません。ログは指定したファイルの後ろに追記されます。デフォルトではログは出力されません。

"Dump_log" "Output_log"と同様にログを出力するファイル名を指定します。ただしこのログは hexdump 形式 (1行に 16byte の 16進文字列と、対応する ASCII 文字列)。ログの各行の1行目には以下のような文字が付加されます。ステータスメッセージの前には「#」、クライアントからサーバへの通信の前には「>」、サーバからクライアントへの通信の前には「<」が出力されます。

"Telnetmode" これに真を指定した場合には、ホストからの通信を解釈して telnet の特殊なバイト列をエスケープします。 Net::Telnet#puts や Net::Telnet#print で送られる文字列もエスケープされます。Net::Telnet#write ではエスケープされません。 Net::Telnet を telnet プロトコル以外(SMPTやPOPなど)で利用したい場合には、この値を偽にしてエスケープを止めてください。この値は Net::Telnet#telnetmode でも指定できます。

"Timeout" 接続時やホストからのデータの読み込みを待つときに、ここで指定した秒数でタイムアウト(TimeoutErrorが発生)します (Net::Telnet#login、Net::Telnet#waitfor、Net::Telnet#cmdで有効になります)。デフォルトは10(秒)です。 falseを指定することでタイムアウトが無効になります。その場合には接続できない場合には connect(2) で Errno::ETIMEOUT が出て止まります(通常数分待つことになりますが)が、それ以外の点ではホストからデータが来ないといつまでも待ちつづけることになります。

"Waittime" は Net::Telnet#waitfor メソッドの "Waittime" のデフォルト値になります。Net::Telnet#waitfor メソッドのプロンプト待ち合わせの処理は、リモートホストからの出力が "Prompt" で指定した正規表現にマッチしてから "Waittime" 秒待っても出力がないかどうかで判断されます。 "Prompt" で指定した正規表現が本当のプロンプト以外の文字列にマッチしてしまう場合にこの値が意味を持ちます。 Net::Telnet#waitfor メソッドは Net::Telnet#cmd や Net::Telnet#login の内部でも使用されています。デフォルトは0(秒)で、正規表現にマッチしたら直ちに待合せ処理に入ります。

"Proxy" ホストに直接接続するかわりにこれで指定したオブジェクトを経由して通信します。IOオブジェクトか Net::Telnet のオブジェクトを指定しなければなりません。Net::Telnetオブジェクトを指定した場合にはそれが持っているソケットを経由して通信します。IOオブジェクトを指定した場合には、それを直接使って通信します。それ以外のオブジェクトを指定するとエラーとなります。

ブロックを指定した場合、サーバに繋ぐときに表示されるステータスメッセージをそのブロックに渡します。通常は、接続前に

"Trying #{ホスト名} ...\n"

接続後に

"Connected to #{ホスト名}.\n"

という文字列がブロックに渡されます。

[PARAM] opts:

各種オプションを指定します。全てのオプションをデフォルト値で指定したい場合には、{}(空のハッシュ)を指定してください。

[EXCEPTION] TimeoutError:

接続時にタイムアウトすると発生します。タイムアウトの時間はオプションで指定します。

インスタンスメソッド

binmode(mode=nil) -> bool[permalink][rdoc]

引数を指定しない場合には"Binmode"の値を返します。引数を与えた場合は"Binmode"の値を変更します。

これは改行文字の変換をするかどうかを意味します。

[PARAM] mode:

設定する値をtrue/falseで与えます

[SEE_ALSO] Net::Telnet.new

binmode=(mode)[permalink][rdoc]

"Binmode" を設定します。これは改行文字の変換をするかどうかを意味します。

[PARAM] mode:

設定する値をtrue/falseで与えます

[SEE_ALSO] Net::Telnet.new, Net::Telnet#binmode

close -> ()[permalink][rdoc]

通信路を閉じます。

cmd(opts) -> String[permalink][rdoc]

cmd(opts) {|mesg| ...} -> String

コマンドをホストに送ります。

より正確にいうと、文字列をホストに送り、プロンプト、もしくは指定した正規表現にマッチするまでホストからのデータを読み込みます。

ブロックを指定した場合、ホストからの文字列を引数にブロックを逐次実行します。

ホストから受け取った文字列を返します。

opts が文字列であれば、その文字列をホストに送り、デフォルトオプションでプロンプトを待ちます。

opts がハッシュである場合には、送る文字列とオプションを指定することができます。その場合には以下の

"String" 送る文字列です。必ず指定する必要があります。

"Match" ホストからのデータをどこまで読みこむかを指定する正規表現を指定します。デフォルトは Net::Telnet.new で "Prompt" で指定した正規表現となります。

"Timeout" タイムアウトまでの時間です。デフォルトは Net::Telnet.new で指定した値となります。

コマンド文字列には改行が付加されてホストに送られます。

[PARAM] opts:

ホストに送るコマンドを文字列で指定します。もしくは送る文字列とオプションをハッシュで指定します。

[EXCEPTION] TimeoutError:

タイムアウトしたときに発生します。

login(opts, password=nil) -> String[permalink][rdoc]

login(opts, password=nil) {|mesg| ...} -> String

指定したユーザ名とパスワードでログインします。

opts が文字列である場合は、 それをユーザ名、passwordをパスワードとしてログインします。 opts がハッシュである場合には、"Name" と "Password" をキーとする文字列をユーザ名、パスワードとしてログインします。また、opts がハッシュの場合には以下のオプションが利用できます。

"LoginPrompt" ログインプロンプトを正規表現で指定します。デフォルト値は /[Ll]ogin[: ]*\z/n です。

"PasswordPrompt" パスワード入力プロンプトを正規表現で指定します。デフォルト値は /[Pp]ass(?:word|phrase)[: ]*\z/n です。

パスワードを省略した場合には、パスワード入力プロンプトを待ちません。Net::Telnet.newの"Prompt"で指定した正規表現でプロンプトを待ちます。

ログイン処理が終わるまでにホストから送られた文字列を返します。通常はユーザ名はエコーされるためそこに含まれているはずです。またパスワードはエコーされないため含まれいはずです。

ブロックを指定した場合、ホストからの文字列を引数にブロックを逐次実行します。

例

# 1つめの引数が文字列の場合
telnet.login("your name", "your password")
# 1つめの引数がハッシュの場合
telnet.login("Name" => "your name", "Password" => "your password")

preprocess(string) -> String[permalink][rdoc]

ホストから受け取った文字列の前処理をします。

受け取った文字列に改行の変換とtelnetコマンドの検出をします。通常は Net::Telnet#waitfor から呼びだされます。 "Telnetmode" を利用している場合、 IO#sysread などで直接ホストからのデータを読みこんだ場合にのみこのメソッドを呼ぶ必要があるでしょう。

前処理の内容は Net::Telnet#telnetmode や Net::Telnet#binmode によって変わります。

[PARAM] string:

前処理対象の文字列

[RETURN]

変換後の文字列

[SEE_ALSO] Net::Telnet.new, Net::Telnet#telnetmode, Net::Telnet#binmode

print(string) -> ()[permalink][rdoc]

ホストに文字列を送ります。

改行は付加されません。文字列中の改行は変換されます。telnetコマンドはエスケープされます。これらの変換はNet::Telnet#telnetmode, Net::Telnet#binmode, およびホストから設定された telnet オプションによって(変換するしないなどが) 制御されます。

[PARAM] string:

ホストに送る文字列

[SEE_ALSO] Net::Telnet#write, Net::Telnet#puts

puts(string) -> ()[permalink][rdoc]

改行を付加した文字列をホストに送ります。

改行の付加以外は Net::Telnet#print と同じです。

[PARAM] string:

ホストに送る文字列

[SEE_ALSO] Net::Telnet#write, Net::Telnet#print

sock -> IO[permalink][rdoc]

リモートホストに接続している IO オブジェクトを返します。

Telnet オブジェクトのメソッドはこのオブジェクトに移譲されているので、Telnetオブジェクトは IO オブジェクトオブジェクトのメソッドを持ち、それらを呼ぶと IO オブジェクトに転送されます。

telnetmode(mode=nil) -> bool|()[permalink][rdoc]

引数を指定しない場合には"Telnetmode"の値を返します。引数を与えた場合は"Telnetmode"の値を変更します。

これは telnet の特殊なバイト列を解釈するかどうかを意味します。

[SEE_ALSO] Net::Telnet.new

telnetmode=(mode)[permalink][rdoc]

"Telnetmode" を設定します。これは telnet の特殊なバイト列を解釈するかどうかを意味します。

[PARAM] mode:

設定する値を真偽値で与えます

[SEE_ALSO] Net::Telnet#new

waitfor(opt) -> String|nil[permalink][rdoc]

waitfor(opt) {|buf| ...} -> String|nil

指定した正規表現にマッチする文字列がホストから来るまでデータを読み込みます。

opt に正規表現を指定した場合には、それにマッチするまで読みこみます。 opt にハッシュを指定した場合には、以下のオプションを指定できます。

"Match" 待ち合わせたい正規表現を指定します。

"Prompt" "Match"と同じです。"Match"が指定されなかった場合にのみ使われます。

"String" "Match"と似ていますが、与えられた String のインスタンスに完全に一致するデータを待ち合わせます。"Match"も"Prompt"も指定されなかった場合にのみ利用されます。

"Timeout" タイムアウトの秒数を指定します。指定しない場合は Net::Telnet.new で指定した"Timeout"の値をデフォルト値として利用します。

"Waittime" 指定した正規表現にマッチしてからこれで指定した秒数だけホストからの通信がない場合にこのメソッドが終わります。指定しない場合は Net::Telnet.new で指定した"Waittime"の値をデフォルト値として利用します。

"FailEOF" これを真にすると、ホスト側から接続を切られた場合には例外 IOError が発生するようになります。偽だとホスト側から接続を切られた場合にはブロックに nil が渡されます。さらにこのオプションが偽で、ホストからのデータが一切来なかった場合には nil を返します。デフォルトは偽です。

"Match" "Prompt" "String" のいずれかは必ず指定する必要があります。

ブロックを指定した場合、ホストからの文字列を引数にブロックを逐次呼びだします。

[PARAM] opt:

待ち合わせに必要な情報を指定します。正規表現を指定するとそれにマッチするデータまで待ち、ハッシュを指定すると正規表現とオプションを指定できます。

[EXCEPTION] TimeoutError:

タイムアウトした場合に発生します

[SEE_ALSO] Net::Telnet.new

write(string) -> ()[permalink][rdoc]

ホストに文字列を送ります。文字列に変換は一切施しません。

[PARAM] string:

ホストに送る文字列

[SEE_ALSO] Net::Telnet#print, Net::Telnet#puts