# telnet.rb

Path: | net/telnet.rb
Last Update: | Sat Oct 25 02:54:55 GMT+10:00 2003

# net/telnet.rb - simple telnet client library

Wakou Aoyama <wakou@ruby-lang.org>

## Overview

This file holds the class Net::Telnet, which provides client-side telnet functionality.

The telnet protocol allows a client to login remotely to a user account on a server and execute commands via a shell. The equivalent is done by creating a Net::Telnet class with the Host option set to your host, calling login() with your user and password, issuing one or more cmd() calls, and then calling close() to end the session. The waitfor(), print(), puts(), and write() methods, which cmd() is implemented on top of, are only needed if you are doing something more complicated.

A Net::Telnet object can also be used to connect to non-telnet services, such as SMTP or HTTP. In this case, you normally want to provide the Port option to specify the port to connect to, and set the Telnetmode option to false to prevent the client from attempting to interpret telnet command sequences. Generally, login() will not work with other protocols, and you have to handle authentication yourself. For some protocols, it will be possible to specify the Prompt option once when you create the Telnet object and use cmd() calls; for others, you will have to specify the response sequence to look for as the Match option to every cmd() call, or call puts() and waitfor() directly; for yet others, you will have to use sysread() instead of waitfor() and parse server responses yourself.

It is worth noting that when you create a new Net::Telnet object, you can supply a proxy IO channel via the Proxy option. This can be used to attach the Telnet object to other Telnet objects, to already open sockets, or to any read-write IO object. This can be useful, for instance, for setting up a test fixture for unit testing.

## Examples of use.

### Log in and send a command, echoing all output to stdout.

      localhost = Net::Telnet::new({"Host" => "localhost",
                                    "Timeout" => 10,
                                    "Prompt" => /[$%#>] \z/n})
      localhost.login("username", "password"){|c| print c }
      localhost.cmd("command"){|c| print c }
      localhost.close

### Check a POP server to see if you have mail.

      pop = Net::Telnet::new({"Host" => "your_destination_host_here",
                              "Port" => 110,
                              "Telnetmode" => false,
                              "Prompt" => /^\+OK/n})
      pop.cmd("user " + "your_username_here"){|c| print c}
      pop.cmd("pass " + "your_password_here"){|c| print c}
      pop.cmd("list"){|c| print c}

## References.

There are a large number of RFCs relevant to the Telnet protocol. RFCs 854-861 define the base protocol. For a complete listing of relevant RFCs, see www.omnifarious.org/~hopper/technical/telnet-rfc.html

## Required files

socket delegate timeout English

## Classes and Modules

Module Net
::Class Net::Telnet

[Validate]