# Net::Telnet (Class)

In: | net/telnet.rb
Parent: | SimpleDelegator

Provides telnet client functionality.

This class also has, through delegation, all the methods of a socket object (by default, a TCPSocket, but can be set by the Proxy option to new()). This provides methods such as close() to end the session and sysread() to read data directly from the host, instead of via the waitfor() mechanism. Note that if you do use sysread() directly when in telnet mode, you should probably pass the output through preprocess() to extract telnet command sequences.

See the documentation to the telnet.rb file for an overview and examples of usage.

## Methods

binmode binmode= cmd login new preprocess print puts telnetmode telnetmode= waitfor write

## Attributes

sock | [R] | The socket the Telnet object is using. Note that this object becomes a delegate of the Telnet object, so normally you invoke its methods directly on the Telnet object.

## Public Class methods

new(options) {|mesg| ...}

Creates a new Net::Telnet object.

Attempts to connect to the host (unless the Proxy option is provided: see below). If a block is provided, it is yielded status messages on the attempt to connect to the server, of the form:

      Trying localhost...
      Connected to localhost.

`options` is a hash of options. The following example lists all options and their default values.

      host = Net::Telnet::new({
               "Host"       => "localhost",  # default: "localhost"
               "Port"       => 23,           # default: 23
               "Binmode"    => false,        # default: false
               "Output_log" => "output_log", # default: nil (no output)
               "Dump_log"   => "dump_log",   # default: nil (no output)
               "Prompt"     => /[$%#>] \z/n, # default: /[$%#>] \z/n
               "Telnetmode" => true,         # default: true
               "Timeout"    => 10,           # default: 10
                 # if ignore timeout then set "Timeout" to false.
               "Waittime"   => 0,            # default: 0
               "Proxy"      => proxy         # default: nil
                               # proxy is Net::Telnet or IO object
             })

The options have the following meanings:

Host: | the hostname or IP address of the host to connect to, as a String. Defaults to "localhost".
Port: | the port to connect to. Defaults to 23.
Binmode: | if false (the default), newline substitution is performed. Outgoing LF is converted to CRLF, and incoming CRLF is converted to LF. If true, this substitution is not performed. This value can also be set with the binmode() method. The outgoing conversion only applies to the puts() and print() methods, not the write() method. The precise nature of the newline conversion is also affected by the telnet options SGA and BIN.
Output_log: | the name of the file to write connection status messages and all received traffic to. In the case of a proper Telnet session, this will include the client input as echoed by the host; otherwise, it only includes server responses. Output is appended verbatim to this file. By default, no output log is kept.
Dump_log: | as for Output_log, except that output is written in hexdump format (16 bytes per line as hex pairs, followed by their printable equivalent), with connection status messages preceded by ’#’, sent traffic preceded by ’>’, and received traffic preceded by ’<’. By default, not dump log is kept.
Prompt: | a regular expression matching the host’s command-line prompt sequence. This is needed by the Telnet class to determine when the output from a command has finished and the host is ready to receive a new command. By default, this regular expression is /[$%#>] \z/n.
Telnetmode: | a boolean value, true by default. In telnet mode, traffic received from the host is parsed for special command sequences, and these sequences are escaped in outgoing traffic sent using puts() or print() (but not write()). If you are using the Net::Telnet object to connect to a non-telnet service (such as SMTP or POP), this should be set to "false" to prevent undesired data corruption. This value can also be set by the telnetmode() method.
Timeout: | the number of seconds to wait before timing out both the initial attempt to connect to host (in this constructor), and all attempts to read data from the host (in waitfor(), cmd(), and login()). Exceding this timeout causes a TimeoutError to be raised. The default value is 10 seconds. You can disable the timeout by setting this value to false. In this case, the connect attempt will eventually timeout on the underlying connect(2) socket call with an Errno::ETIMEDOUT error (but generally only after a few minutes), but other attempts to read data from the host will hand indefinitely if no data is forthcoming.
Waittime: | the amount of time to wait after seeing what looks like a prompt (that is, received data that matches the Prompt option regular expression) to see if more data arrives. If more data does arrive in this time, Net::Telnet assumes that what it saw was not really a prompt. This is to try to avoid false matches, but it can also lead to missing real prompts (if, for instance, a background process writes to the terminal soon after the prompt is displayed). By default, set to 0, meaning not to wait for more data.
Proxy: | a proxy object to used instead of opening a direct connection to the host. Must be either another Net::Telnet object or an IO object. If it is another Net::Telnet object, this instance will use that one’s socket for communication. If an IO object, it is used directly for communication. Any other kind of object will cause an error to be raised.

[Source]

    # File net/telnet.rb, line 269
        def initialize(options) # :yield: mesg

          @options = options
          @options["Host"]       = "localhost"   unless @options.has_key?("Host")
          @options["Port"]       = 23            unless @options.has_key?("Port")
          @options["Prompt"]     = /[$%#>] \z/n  unless @options.has_key?("Prompt")
          @options["Timeout"]    = 10            unless @options.has_key?("Timeout")
          @options["Waittime"]   = 0             unless @options.has_key?("Waittime")
          unless @options.has_key?("Binmode")
            @options["Binmode"]    = false
          else
            unless (true == @options["Binmode"] or false == @options["Binmode"])
              raise ArgumentError, "Binmode option required true or false"
            end
          end

          unless @options.has_key?("Telnetmode")
            @options["Telnetmode"] = true
          else
            unless (true == @options["Telnetmode"] or false == @options["Telnetmode"])
              raise ArgumentError, "Telnetmode option required true or false"
            end
          end

          @telnet_option = { "SGA" => false, "BINARY" => false }

          if @options.has_key?("Output_log")
            @log = File.open(@options["Output_log"], 'a+')
            @log.sync = true
            @log.binmode
          end

          if @options.has_key?("Dump_log")
            @dumplog = File.open(@options["Dump_log"], 'a+')
            @dumplog.sync = true
            @dumplog.binmode
            def @dumplog.log_dump(dir, x)  # :nodoc:

              len = x.length
              addr = 0
              offset = 0
              while 0 < len
                if len < 16
                  line = x[offset, len]
                else
                  line = x[offset, 16]
                end
                hexvals = line.unpack('H*')[0]
                hexvals += ' ' * (32 - hexvals.length)
                hexvals = format("%s %s %s %s  " * 4, *hexvals.unpack('a2' * 16))
                line = line.gsub(/[\000-\037\177-\377]/n, '.')
                printf "%s 0x%5.5x: %s%s\n", dir, addr, hexvals, line
                addr += 16
                offset += 16
                len -= 16
              end
              print "\n"
            end
          end

          if @options.has_key?("Proxy")
            if @options["Proxy"].kind_of?(Net::Telnet)
              @sock = @options["Proxy"].sock
            elsif @options["Proxy"].kind_of?(IO)
              @sock = @options["Proxy"]
            else
              raise "Error; Proxy is Net::Telnet or IO object."
            end
          else
            message = "Trying " + @options["Host"] + "...\n"
            yield(message) if block_given?
            @log.write(message) if @options.has_key?("Output_log")
            @dumplog.log_dump('#', message) if @options.has_key?("Dump_log")

            begin
              if @options["Timeout"] == false
                @sock = TCPSocket.open(@options["Host"], @options["Port"])
              else
                timeout(@options["Timeout"]) do
                  @sock = TCPSocket.open(@options["Host"], @options["Port"])
                end
              end
            rescue TimeoutError
              raise TimeoutError, "timed-out; opening of the host"
            rescue
              @log.write($ERROR_INFO.to_s + "\n") if @options.has_key?("Output_log")
              @dumplog.log_dump('#', $ERROR_INFO.to_s + "\n") if @options.has_key?("Dump_log")
              raise
            end
            @sock.sync = true
            @sock.binmode

            message = "Connected to " + @options["Host"] + ".\n"
            yield(message) if block_given?
            @log.write(message) if @options.has_key?("Output_log")
            @dumplog.log_dump('#', message) if @options.has_key?("Dump_log")
          end

          super(@sock)
        end

## Public Instance methods

telnetmode(mode = nil)

Set telnet command interpretation on (`mode` == true) or off (`mode` == false), or return the current value (`mode` not provided). It should be on for true telnet sessions, off if using Net::Telnet to connect to a non-telnet service such as SMTP.

[Source]

    # File net/telnet.rb, line 378
        def  telnetmodetelnetmode(mode = nil)
          case mode
          when nil
            @options["Telnetmode"]
          when true, false
            @options["Telnetmode"] = mode
          else
            raise ArgumentError, "required true or false"
          end
        end

telnetmode=(mode)

Turn telnet command interpretation on (true) or off (false). It should be on for true telnet sessions, off if using Net::Telnet to connect to a non-telnet service such as SMTP.

[Source]

    # File net/telnet.rb, line 392
        def telnetmode=(mode)
          if (true == mode or false == mode)
            @options["Telnetmode"] = mode
          else
            raise ArgumentError, "required true or false"
          end
        end

binmode(mode = nil)

Turn newline conversion on (`mode` == false) or off (`mode` == true), or return the current value (`mode` is not specified).

[Source]

    # File net/telnet.rb, line 402
        def binmode(mode = nil)
          case mode
          when nil
            @options["Binmode"]
          when true, false
            @options["Binmode"] = mode
          else
            raise ArgumentError, "required true or false"
          end
        end

binmode=(mode)

Turn newline conversion on (false) or off (true).

[Source]

    # File net/telnet.rb, line 414
        def binmode=(mode)
          if (true == mode or false == mode)
            @options["Binmode"] = mode
          else
            raise ArgumentError, "required true or false"
          end
        end

preprocess(string)

Preprocess received data from the host.

Performs newline conversion and detects telnet command sequences. Called automatically by waitfor(). You should only use this method yourself if you have read input directly using sysread() or similar, and even then only if in telnet mode.

[Source]

    # File net/telnet.rb, line 428
        def preprocess(string)
          # combine CR+NULL into CR

          string = string.gsub(/#{CR}#{NULL}/no, CR) if @options["Telnetmode"]

          # combine EOL into "\n"

          string = string.gsub(/#{EOL}/no, "\n") unless @options["Binmode"]

          string.gsub(/#{IAC}(
                       [#{IAC}#{AO}#{AYT}#{DM}#{IP}#{NOP}]|
                       [#{DO}#{DONT}#{WILL}#{WONT}]
                         [#{OPT_BINARY}-#{OPT_NEW_ENVIRON}#{OPT_EXOPL}]|
                       #{SB}[^#{IAC}]*#{IAC}#{SE}
                     )/xno) do
            if    IAC == $1  # handle escaped IAC characters

              IAC
            elsif AYT == $1  # respond to "IAC AYT" (are you there)

              self.write("nobody here but us pigeons" + EOL)
              ''
            elsif DO[0] == $1[0]  # respond to "IAC DO x"

              if OPT_BINARY[0] == $1[1]
                @telnet_option["BINARY"] = true
                self.write(IAC + WILL + OPT_BINARY)
              else
                self.write(IAC + WONT + $1[1..1])
              end
              ''
            elsif DONT[0] == $1[0]  # respond to "IAC DON'T x" with "IAC WON'T x"

              self.write(IAC + WONT + $1[1..1])
              ''
            elsif WILL[0] == $1[0]  # respond to "IAC WILL x"

              if    OPT_BINARY[0] == $1[1]
                self.write(IAC + DO + OPT_BINARY)
              elsif OPT_ECHO[0] == $1[1]
                self.write(IAC + DO + OPT_ECHO)
              elsif OPT_SGA[0]  == $1[1]
                @telnet_option["SGA"] = true
                self.write(IAC + DO + OPT_SGA)
              else
                self.write(IAC + DONT + $1[1..1])
              end
              ''
            elsif WONT[0] == $1[0]  # respond to "IAC WON'T x"

              if    OPT_ECHO[0] == $1[1]
                self.write(IAC + DONT + OPT_ECHO)
              elsif OPT_SGA[0]  == $1[1]
                @telnet_option["SGA"] = false
                self.write(IAC + DONT + OPT_SGA)
              else
                self.write(IAC + DONT + $1[1..1])
              end
              ''
            else
              ''
            end
          end
        end

waitfor(options) {|recvdata| ...}

Read data from the host until a certain sequence is matched.

If a block is given, the received data will be yielded as it is read in (not necessarily all in one go), or nil if EOF occurs before any data is received. Whether a block is given or not, all data read will be returned in a single string, or again nil if EOF occurs before any data is received. Note that received data includes the matched sequence we were looking for.

`options` can be either a regular expression or a hash of options. If a regular expression, this specifies the data to wait for. If a hash, this can specify the following options:

Match: | a regular expression, specifying the data to wait for.
Prompt: | as for Match; used only if Match is not specified.
String: | as for Match, except a string that will be converted into a regular expression. Used only if Match and Prompt are not specified.
Timeout: | the number of seconds to wait for data from the host before raising a TimeoutError. If set to false, no timeout will occur. If not specified, the Timeout option value specified when this instance was created will be used, or, failing that, the default value of 10 seconds.
Waittime: | the number of seconds to wait after matching against the input data to see if more data arrives. If more data arrives within this time, we will judge ourselves not to have matched successfully, and will continue trying to match. If not specified, the Waittime option value specified when this instance was created will be used, or, failing that, the default value of 0 seconds, which means not to wait for more input.

[Source]

    # File net/telnet.rb, line 518
        def waitfor(options) # :yield: recvdata

          time_out = @options["Timeout"]
          waittime = @options["Waittime"]

          if options.kind_of?(Hash)
            prompt   = if options.has_key?("Match")
                         options["Match"]
                       elsif options.has_key?("Prompt")
                         options["Prompt"]
                       elsif options.has_key?("String")
                         Regexp.new( Regexp.quote(options["String"]) )
                       end
            time_out = options["Timeout"]  if options.has_key?("Timeout")
            waittime = options["Waittime"] if options.has_key?("Waittime")
          else
            prompt = options
          end

          if time_out == false
            time_out = nil
          end

          line = ''
          buf = ''
          rest = ''
          until(prompt === line and not IO::select([@sock], nil, nil, waittime))
            unless IO::select([@sock], nil, nil, time_out)
              raise TimeoutError, "timed-out; wait for the next data"
            end
            begin
              c = @sock.sysread(1024 * 1024)
              @dumplog.log_dump('<', c) if @options.has_key?("Dump_log")
              if @options["Telnetmode"]
                c = rest + c
                if Integer(c.rindex(/#{IAC}#{SE}/no)) <
                   Integer(c.rindex(/#{IAC}#{SB}/no))
                  buf = preprocess(c[0 ... c.rindex(/#{IAC}#{SB}/no)])
                  rest = c[c.rindex(/#{IAC}#{SB}/no) .. -1]
                elsif pt = c.rindex(/#{IAC}[^#{IAC}#{AO}#{AYT}#{DM}#{IP}#{NOP}]?\z/no)
                  buf = preprocess(c[0 ... pt])
                  rest = c[pt .. -1]
                else
                  buf = preprocess(c)
                  rest = ''
                end
             else
               # Not Telnetmode.

               #

               # We cannot use preprocess() on this data, because that

               # method makes some Telnetmode-specific assumptions.

               buf = c
               buf.gsub!(/#{EOL}/no, "\n") unless @options["Binmode"]
               rest = ''
              end
              @log.print(buf) if @options.has_key?("Output_log")
              line += buf
              yield buf if block_given?
            rescue EOFError # End of file reached

              if line == ''
                line = nil
                yield nil if block_given?
              end
              break
            end
          end
          line
        end

write(string)

Write `string` to the host.

Does not perform any conversions on `string`. Will log `string` to the dumplog, if the Dump_log option is set.

[Source]

    # File net/telnet.rb, line 590
        def write(string)
          length = string.length
          while 0 < length
            IO::select(nil, [@sock])
            @dumplog.log_dump('>', string[-length..-1]) if @options.has_key?("Dump_log")
            length -= @sock.syswrite(string[-length..-1])
          end
        end

print(string)

Sends a string to the host.

This does not automatically append a newline to the string. Embedded newlines may be converted and telnet command sequences escaped depending upon the values of telnetmode, binmode, and telnet options set by the host.

[Source]

    # File net/telnet.rb, line 605
        def print(string)
          string = string.gsub(/#{IAC}/no, IAC + IAC) if @options["Telnetmode"]

          if @options["Binmode"]
            self.write(string)
          else
            if @telnet_option["BINARY"] and @telnet_option["SGA"]
              # IAC WILL SGA IAC DO BIN send EOL --> CR

              self.write(string.gsub(/\n/n, CR))
            elsif @telnet_option["SGA"]
              # IAC WILL SGA send EOL --> CR+NULL

              self.write(string.gsub(/\n/n, CR + NULL))
            else
              # NONE send EOL --> CR+LF

              self.write(string.gsub(/\n/n, EOL))
            end
          end
        end

puts(string)

Sends a string to the host.

Same as print(), but appends a newline to the string.

[Source]

    # File net/telnet.rb, line 627
        def puts(string)
          self.print(string + "\n")
        end

cmd(options) {|recvdata| ...}

Send a command to the host.

More exactly, sends a string to the host, and reads in all received data until is sees the prompt or other matched sequence.

If a block is given, the received data will be yielded to it as it is read in. Whether a block is given or not, the received data will be return as a string. Note that the received data includes the prompt and in most cases the host’s echo of our command.

`options` is either a String, specified the string or command to send to the host; or it is a hash of options. If a hash, the following options can be specified:

String: | the command or other string to send to the host.
Match: | a regular expression, the sequence to look for in the received data before returning. If not specified, the Prompt option value specified when this instance was created will be used, or, failing that, the default prompt of /[$%#>] \z/n.
Timeout: | the seconds to wait for data from the host before raising a Timeout error. If not specified, the Timeout option value specified when this instance was created will be used, or, failing that, the default value of 10 seconds.

The command or other string will have the newline sequence appended to it.

[Source]

    # File net/telnet.rb, line 658
        def cmd(options) # :yield: recvdata

          match    = @options["Prompt"]
          time_out = @options["Timeout"]

          if options.kind_of?(Hash)
            string   = options["String"]
            match    = options["Match"]   if options.has_key?("Match")
            time_out = options["Timeout"] if options.has_key?("Timeout")
          else
            string = options
          end

          self.puts(string)
          if block_given?
            waitfor({"Prompt" => match, "Timeout" => time_out}){|c| yield c }
          else
            waitfor({"Prompt" => match, "Timeout" => time_out})
          end
        end

login(options, password = nil) {|recvdata| ...}

Login to the host with a given username and password.

The username and password can either be provided as two string arguments in that order, or as a hash with keys "Name" and "Password".

This method looks for the strings "login" and "Password" from the host to determine when to send the username and password. If the login sequence does not follow this pattern (for instance, you are connecting to a service other than telnet), you will need to handle login yourself.

The password can be omitted, either by only provided one String argument, which will be used as the username, or by providing a has that has no "Password" key. In this case, the method will not look for the "Password:" prompt; if it is sent, it will have to be dealt with by later calls.

The method returns all data received during the login process from the host, including the echoed username but not the password (which the host should not echo). If a block is passed in, this received data is also yielded to the block as it is received.

[Source]

    # File net/telnet.rb, line 700
        def login(options, password = nil) # :yield: recvdata

          if options.kind_of?(Hash)
            username = options["Name"]
            password = options["Password"]
          else
            username = options
          end

          if block_given?
            line = waitfor(/login[: ]*\z/n){|c| yield c }
            if password
              line += cmd({"String" => username,
                           "Match" => /Password[: ]*\z/n}){|c| yield c }
              line += cmd(password){|c| yield c }
            else
              line += cmd(username){|c| yield c }
            end
          else
            line = waitfor(/login[: ]*\z/n)
            if password
              line += cmd({"String" => username,
                           "Match" => /Password[: ]*\z/n})
              line += cmd(password)
            else
              line += cmd(username)
            end
          end
          line
        end

[Validate]