net-ssh 1.1.4 → 2.0.0

data/doc/manual/parts/0014.txt

@@ -1,32 +0,0 @@
-There are various callbacks that may be registered on a channel. Registering a callback is as simple as invoking the corresponding method on the channel and giving it a block that should be invoked when the named action occurs. The following table describes each callback and how it is used.
-
-table(list).
-|_. Name |_. Description |
-|=^. @on_close@ | This callback should accept a single parameter: the channel being closed.  It is called immediately after the channel is removed from the connection. The callback should not send any data through the channel, since at this point the channel is no longer connected to the remote host.|
-|=^. @on_confirm_failed@ | This callback should accept four parameters: the channel instance, the reason code, a description of why the confirm failed, and the language code for the message.  It is called immediately after the server has indicated that a channel could not be opened.|
-|=^. @on_confirm_open@ | This callback should accept a single parameter: the channel being opened.  It is called immediately after the server has confirmed that the channel has been opened. This callback is typically set by a block passed to an @#open_channel@ call.|
-|=^. @on_data@ | This callback is invoked when data is received over the channel from the remote server. This data typically corresponds to the remote process's @stdout@ stream. The channel should accept two parameters: the channel itself, and the data being received.|
-|=^. @on_eof@ | This callback is called when the server indicates that no more data will be sent _from the server_ over this channel. Your program is still welcome to send data to the server, but you are guaranteed at this point that your @on_data@ and @on_extended_data@ callbacks will no longer be called for this channel. The callback should accept a single parameter, the channel itself.|
-|=^. @on_extended_data@ | This callback is called when _extended data_ is received from the server. There are (potentially) many _types_ of extended data. The callback should accept three parameters: the channel, an integer indicating the type of the data, and the data itself.  Right now, you can pretty much count on the data type being a "1", which corresponds to the remote process's @stderr@ stream. Other data types are not defined in the SSH specification, but that does not mean some SSH servers won't try to invent their own.|
-|=^. @on_failure@ | When a request is sent over a channel (via the @send_request@ or @send_request_string@ methods), it may either succeed or fail. If it fails, this callback will be invoked. It should take a single parameter: the channel itself.|
-|=^. @on_request@ | When the server sends a "channel request" to the client, this callback will be invoked. Channel requests from the server typically indicate things like the exit status of a process. This callback should take four parameters: the channel, the type of request (as a string, like "exit-status"), a boolean (indicating whether or not the server wants an explicit reply to this request), and the data from the request, which will be a buffer object (see the API documentation for @Net::SSH::Util::ReaderBufferImpl@).|
-|=^. @on_success@ | When a request is sent over a channel (via the @send_request@ or @send_request_string@ methods), it may either succeed or fail. If it succeeds, this callback will be invoked. It should take a single parameter: the channel itself.|
-|=^. @on_window_adjust@ | When the server asks the client to adjust this channel's window size, this callback will be invoked. It should accept two parameters: the channel, and the number of bytes to add the channel's window size.|
-
-In general, you will never need to register callbacks for @on_failure@, @on_request@, @on_success@, or @on_window_adjust@, unless you are needing to implement support for some subservice or piggy-backed protocol (like SFTP).
-
-Following is an example of registering callbacks on a channel:
-
-{{{lang=ruby,caption=Registering callbacks on a channel,number=true
-Net::SSH.start( 'host' ) do |session|
-  session.open_channel do |channel|
-    channel.on_close do |ch|
-      puts "channel closed successfully."
-    end
-    puts "closing channel..."
-    channel.close
-  end
-
-  session.loop
-end
-}}}

data/doc/manual/parts/0015.txt

@@ -1,14 +0,0 @@
-There are a variety of operations that may be performed on a channel. Some we've already mentioned, like registering callbacks, or closing the channel. Some of the other more common operations are listed (and described) in the following table.
-
-table(list).
-|_. Operation |_. Description |
-| @#exec@ | Executes a command asynchronously on this channel.|
-| @#request_pty@ | Requests that a pseudo-terminal (pty) be opened for this channel.|
-| @#send_data@ | Sends the given data string to the server via this channel.  This is useful for sending data to a remote process, or sending an SFTP packet to the SFTP subsystem.|
-| @#send_eof@ | Tells the server that no further data will be sent from the client to the server. The client must honor this by not sending any more data (either normal or extended) to the server over this channel.|
-| @#send_extended_data@ | Sends a data string to the server, along with an integer describing its type. This is typically used to send @stderr@ data.|
-| @#send_request@ | Sends a named request to the server for this channel. This is primarily used by implementations of protocols and subsystems that run on top of SSH.|
-| @#send_signal@ | Indicates that the server should send the given signal to the process on the other end of the channel.|
-| @#subsystem@ | Requests that the server start the given subsystem on this channel. This is how (for instance) the SFTP subsystem is invoked. |
-
-See the API documentation for an exhaustive reference of all available channel operations.

data/doc/manual/parts/0016.txt

@@ -1,28 +0,0 @@
-To run multiple processes in parallel, you can access the channel API directly, setting up multiple channels and callbacks in order to process the output from the channel.
-
-Suppose, for example, that you wanted to run multiple "tail" commands on various logs on the remote machine, combining them all into the output on the client. Something like the following would suffice:
-
-{{{lang=ruby,number=true,caption=Running "tail" on multiple remote files
-def do_tail( session, file )
-  session.open_channel do |channel|
-    channel.on_data do |ch, data|
-      puts "[#{file}] -> #{data}"
-    end
-    channel.exec "tail -f #{file}"
-  end
-end
-
-Net::SSH.start( 'host' ) do |session|
-  do_tail session, "/var/log/messages"
-  do_tail session, "/var/log/XFree86.0.log"
-  do_tail session, "/var/log/tomcat/catalina.log"
-  do_tail session, "/var/log/mysql/mysql.err"
-  session.loop
-end
-}}}
-
-As you can see, four different logs are tailed on four separate channels. Each channel registers an @on_data@ callback (which simply displays the data it recieves, together with the name of the log file it came from). The @exec@ method of the channel is then invoked, which simply sends the request to execute the process to the server, and then returns.
-
-The @loop@ method then blocks while packets and processed and callbacks are invoked, completing the program.
-
-This approach works fine for processing data coming from the server, and with a little work and coordination can work well for sending data _to_ the server as well, by calling the @send_data@ method of the channel at the appropriate times. However, it requires a bit of forethought, since you have to come up with a simple state machine to manage most interactive sessions, and many times that's more effort than it is worth.

data/doc/manual/parts/0017.txt

@@ -1,50 +0,0 @@
-The @#process.open@ interface provides a simpler way to manage interactive sessions. It still works via callbacks, and it still requires a kind of state machine in order to process input, but it does simplify things a little bit.
-
-Just open an SSH session. The @#process@ service of the session manages access to convenience methods for handling and communicating with remote processes. In particular the @#open@ method of the @#process@ service allows you to constuct callbacks for dealing with remote processes, more conveniently than using channels directly.
-
-Consider the "bc" command. It is a command-line calculator that accepts expressions on @stdin@ and writes the results to @stdout@. When it encounters the word @quit@ on the input, it exits. Sounds like a great way to demonstrate the @process@ service...
-
-{{{lang=ruby,number=true,caption=Using #process.open
-Net::SSH.start( 'host' ) do |session|
-
-  session.process.open( "bc" ) do |bc|
-    dialog = [ "5+5", "7*12", "sqrt(2.000000)", "quit" ]
-
-    bc.on_success do |p|
-      puts "requesting result of #{dialog.first}"
-      p.puts dialog.shift
-    end
-
-    bc.on_stdout do |p,data|
-      puts "--> #{data}"
-      unless dialog.empty?
-        puts "requesting result of #{dialog.first}"
-        p.puts dialog.shift
-      end
-    end
-
- bc.on_exit do |p, status|
-      puts "process finished with exit status: #{status}"
-    end
-  end
-
-end
-}}}
-
-Notice the progression. First, the session itself is started. Then, while the session is active, the process is invoked (via @#process.open@). After we have a handle to the process (which is yielded to the block, in this case), we set up the callbacks on the process. These are reminiscent of, but different from, the callbacks that we set up on the channel itself in the previous section.
-
-The following callbacks are defined for a process handle:
-
-table(list).
-|_. Name |_. Description |
-|=^. @on_exit@ | This callback is invoked when the process terminates normally. The block should accept two parameters: the process handle itself, and the exit status of the process.|
-|=^. @on_failure@ | This callback is invoked when the process could not be invoked. It should take two parameters: the process handle itself, and a status string (which currently always @nil@).|
-|=^. @on_success@ | This callback is invoked after the process has been successfully started.  The callback should take a single parameter: the process handle itself.|
-|=^. @on_stderr@ | This callback is invoked when data is received from the process's @stderr@ stream. The callback should have two parameters: the process handle, and the data.|
-|=^. @on_stdout@ | This callback is invoked when data is received from the process's @stdout@ stream. The callback should have two parameters: the process handle, and the data.|
-
-Sending data to the process is as simple as calling @puts@ on the process handle. If you don't want a newline appended to your data, use @write@ instead.
-
-Notice that, when sending a block to @#process.open@, you do not have to explicitly invoke @session.loop@. It is implicitly called at the end of the block. If you ever want to set up multiple processes to run in parallel, simply use @#process.open@ without a block. The process handle will be returned, and you will be required to execute @session.loop@ manually.
-
-For more information on the @#process.open@ service, see the API documentation for @Net::SSH::Service::Process::Open@.

data/doc/manual/parts/0018.txt

@@ -1,35 +0,0 @@
-The last approach to interacting with remote processes is the @#popen3@ method of @#process@ service. It is a _synchronous_ approach, meaning that each method call _may_ (potentially) block until data is received; you can't be using other features of the Net::SSH package while using it, but you don't have to mess with callbacks.
-
-If you are familiar with the "popen3" Ruby module, this will seem familiar. It's not a perfect clone of the "popen3" module's functionality, but it's close. What you do is you specify the process to invoke, and then you get three pseudo-IO objects back: the process's input stream, it's output stream, and it's error stream. You can write to the input stream to send data to the process, or read from the output and error streams. Reading from the output or error streams will block until data is available, which makes it very convenient for interacting with a single remote process.
-
-Here's the previous "bc" example, rewritten to use @#popen3@:
-
-{{{lang=ruby,number=true,caption=Using #process.popen3
-Net::SSH.start( 'host' ) do |session|
-
-  input, output, error = session.process.popen3( "bc" )
-
-  [ "5+5", "7*12", "sqrt(2.000000)" ].each do |formula|
-    input.puts formula
-    puts "#{formula}=#{output.read}"
-  end
-
-  input.puts "quit"
-
-end
-}}}
-
-Much more concise, isn't it? One caveat, though: there is no way to kill the process (unless the process can terminate itself, such as through the use of issuing bc's "quit" command as used above) without closing the session. To remedy this, there is also a block version of popen3 that provides an explicit scope for the three data streams:
-
-{{{lang=ruby,number=true,caption=Transactional form of #process.popen3
-Net::SSH.start( 'host' ) do |session|
-  session.process.popen3( "bc" ) do |input, output, error|
-    [ "5+5", "7*12", "sqrt(2.000000)" ].each do |formula|
-      input.puts formula
- puts "#{formula}=#{output.read}"
-    end
-  end
-end
-}}}
-
-The three streams will be closed and process explicitly terminated when the block ends.

data/doc/manual/parts/0019.txt

@@ -1,7 +0,0 @@
-A user's _shell_ is the environment in which commands are executed on a remote machine. There are a variety of different shells, including "bash":http://www.gnu.org/software/bash/bash.html, csh, tcsh, "ksh":http://www.kornshell.com/, and many others.
-
-A shell may be executed like any other program, and when run, it (more-or-less) enters a read-execute-prompt cycle in which the user may interactively run commands.
-
-SSH has special support for shells, allowing you to start a shell on a channel and have all subsequent data sent to that channel interpreted as the user's input to the shell. Also, SSH supports pty's (_pseudo-tty_'s, or terminals), which allow the shell to act as if it were running locally on the users own machine.
-
-Because a shell is just a program, you can always start a shell simply by executing it (as described in the previous chapter). However, you can also take advantage of SSH's builtin shell support to execute the user's preferred shell. This chapter will discuss this approach.

data/doc/manual/parts/0020.txt

@@ -1,72 +0,0 @@
-At the lowest level, starting a shell is a matter of sending a "shell" request over a channel.
-
-{{{lang=ruby,caption=Sending a shell request,number=true
-Net::SSH.start( host ) do |session|
-
-  session.open_channel do |channel|
-
-    channel.on_success do
-      puts "shell was started successfully!"
-      channel.send_data "exit\n" # tell the shell to exit
-    end
-    channel.on_failure do
-      puts "shell could not be started!"
-    end
-    channel.on_data do |ch,data|
-      puts "recieved #{data} from shell"
-    end
-    channel.on_close do
-      puts "shell terminated"
-    end
-
-    channel.send_request "shell", nil, true
-
-  end
-
-  session.loop
-
-end
-}}}
-
-The @#send_request@ method accepts three parameters--the name of the request (in this case, "shell"), any additional data to send with the request (none, in this case), and whether or not you want the server to reply with the success or failure of the request. In general, it is a good idea to ask for the server to reply, so that you know when you can start sending data to the shell.
-
-If you want to open a pty before starting the shell, you can use the #request_pty method of the channel:
-
-{{{lang=ruby,number=true,caption=Opening a pty on a channel
-Net::SSH.start( host ) do |session|
-
-  session.open_channel do |channel|
-
-    channel.on_success do
-      puts "pty was requested successfully!"
-
-      channel.on_success do
-        puts "shell was started successfully!"
-        channel.send_data "exit\n" # tell the shell to exit
-      end
-
-      channel.send_request "shell", nil, true
-    end
-
-    channel.on_failure do
-      puts "shell could not be started!"
-    end
-    channel.on_data do |ch,data|
-      puts "recieved #{data} from shell"
-    end
-    channel.on_close do
-      puts "shell terminated"
-    end
-
-    channel.request_pty :want_reply => true
-
-  end
-
-  session.loop
-
-end
-}}}
-
-First, the pty is requested (with an indicator to the server that it should return a "success" or "failure" notification). When the pty is successfully opened, the "on_success" callback is changed, and the shell is then requested.
-
-It's a lot of hoops to jump through, but it gives you the finest-grained control over opening a shell. For most things, though, you can live with less control. For those tasks, there are the _shell_ and _sync_ services.

data/doc/manual/parts/0021.txt

@@ -1,50 +0,0 @@
-To make interacting with shells, simpler, version 0.9 of Net::SSH introduced the _shell service_. This allows you to open a shell (with or without a pty), send a series of commands to the shell, and then wait for the output from the shell.
-
-{{{lang=ruby,number=true,caption=Using the shell service
-Net::SSH.start( 'localhost' ) do |session|
-
-  shell = session.shell.open
-
-  # script what we want to do
-  shell.pwd
-  shell.cd "/"
-  shell.pwd
-  shell.test "-e foo"
-  shell.cd "/really/bogus/directory"
-  shell.send_data "/sbin/ifconfig\n"
-  shell.pwd
-  shell.ruby "-v"
-  shell.cd "/usr/lib"
-  shell.pwd
-  shell.exit
-
-  # give the above commands sufficient time to terminate
-  sleep 0.5
-
-  # display the output
-  $stdout.print shell.stdout while shell.stdout?
-  $stderr.puts "-- stderr: --"
-  $stderr.print shell.stderr while shell.stderr?
-
-end
-}}}
-
-Any unrecognized method that is sent to the shell object is interpreted as a command to send to the server. To explicitly send a command, use the @#send_data@ method (but remember to add a newline!). The @#send_data@ method may also be used to send data to any process running in the shell as that process' @stdin@ stream.
-
-You can also specify that a pty should be allocated for this shell:
-
-{{{lang=ruby,number=true,caption=Allocating a pty for the shell
-Net::SSH.start( 'localhost' ) do |session|
-
-  shell = session.shell.open( :pty => true )
-
-  # or
-
-  shell = session.shell.open( :pty => { ... } )
-
-end
-}}}
-
-If you give a hash for the @:pty@ option, it must be a map of the options that describe the new pty. See the API documentation for the @Channel#request_pty@ method for more information.
-
-Note that this is still an asynchronous approach. You send all the commands through the pipe and then wait for the output. (And be sure to give sufficient time or the processes to terminate!) This is fine for scripts that you just want to throw at the server, but many times you want a more interactive interface, for executing a command and receiving its output before moving on.

data/doc/manual/parts/0022.txt

@@ -1,42 +0,0 @@
-The SyncShell service allows you to execute commands on the shell and block until they finish. It is not fool-proof--it has to use some tricks to accomplish this task, and some commands may foul it up. But for most tasks, it works admirably.
-
-{{{lang=ruby,number=true,caption=Using the SyncShell service
-Net::SSH.start( 'localhost' ) do |session|
-
-  shell = session.shell.sync
-
-  out = shell.pwd
-  p out.stdout
-
-  out = shell.test "-e foo"
-  p out.status
-
-  out = shell.cd "/really/bogus/directory"
-  p out.stderr
-  p out.status
-
-  out = shell.ruby "-v"
-  p out.stdout
-
-  out = shell.cd "/usr/lib"
-
- out = shell.ls "-l"
-  p out.stdout
-
-  out = shell.send_command( "bc", <<CMD )
-5+5
-10*2
-scale=5
-3/4
-quit
-CMD
-  p out.stdout
-
-  p shell.exit
-
-end
-}}}
-
-The result of executing each command is an object that encapsulates the @stdout@ and @stderr@ streams, and the exit status of the command.
-
-To explicitly execute a command, use the @#send_command@ instead of @#send_data@--otherwise, the command will be executed asynchronously, which is not what you want. Also, if you pass a second parameter to the @#send_command@ method, it is interpreted as the @stdin@ data to send to the new process.

data/doc/manual/parts/0023.txt

@@ -1,51 +0,0 @@
-Using the shell service and pty's, you can now create a simple SSH terminal client. (You'll also want to download and install the "ruby-termios":http://arika.org/ruby/termios library so that your input is not interpreted in a linewise fashion.)
-
-{{{lang=ruby,number=true,caption=A simple SSH terminal client in Ruby
-begin
-  require 'termios'
-rescue LoadError
-end
-
-def stdin_buffer( enable )
-  return unless defined?( Termios )
-  attr = Termios::getattr( $stdin )
-  if enable
-    attr.c_lflag |= Termios::ICANON | Termios::ECHO
-  else
-    attr.c_lflag &= ~(Termios::ICANON|Termios::ECHO)
-  end
-  Termios::setattr( $stdin, Termios::TCSANOW, attr )
-end
-
-host = ARGV.shift or abort "You must specify the [user@]host to connect to"
-if host =~ /@/
-  user, host = host.match( /(.*?)@(.*)/ )[1,2]
-else
-  user = ENV['USER'] || ENV['USER_NAME']
-end
-
-Net::SSH.start( host, user ) do |session|
-
- begin
-    stdin_buffer false
-
-    shell = session.shell.open( :pty => true )
-
-    loop do
-      break unless shell.open?
-      if IO.select([$stdin],nil,nil,0.01)
-        data = $stdin.sysread(1)
-        shell.send_data data
-      end
-
-      $stdout.print shell.stdout while shell.stdout?
-      $stdout.flush
-    end
-  ensure
-    stdin_buffer true
-  end
-
-end
-}}}
-
-The above code is also available as an example script in the Net::SSH distribution (@examples/ssh-client.rb@).

data/doc/manual/parts/0024.txt

@@ -1,18 +0,0 @@
-Port forwarding is a feature of the SSH protocol that allows you to specify a port on one of the hosts, and have network connections on that port forwarded to a port on a different host, using the SSH connection as a proxy. There are basically two ways to use this forwarding:
-
-# A port on the local host is forwarded via the remote host to another machine. Any connection to the specified port will cause all subsequent data to be sent over the connection to the remote host, where it will then be forwarded to the requested destination host.
-# A port on the remote host is forwarded over the connection to the local host, and from there to (potentially) some other remote destination. Any connection to the specified port on the remote host is forwarded over the connection to the local host, which then makes a connection to the specified remote destination and sends the data there.
-
-All port forwarding in the Net::SSH library is managed by the @#forward@ service. Just invoke methods on that service to set up any of various port forwarding configurations.
-
-{{{lang=ruby,number=true,caption=Accessing the #forward service
-Net::SSH.start( 'host' ) do |session|
-  forward = session.forward
-  ...
-  session.loop
-end
-}}}
-
-You can define any number of forwards before invoking the main loop, in which case all of those forwards will be handled transparently (and silently) in parallel, over the same connection. (Isn't SSH lovely?)
-
-Naturally, you can also have remote processes, SFTP sessions, and more all working at the same time on the connection.

data/doc/manual/parts/0025.txt

@@ -1,18 +0,0 @@
-Forwarding a local connection to a remote destination is simply a matter of invoking the @#local@ method of the @#forward@ service. The simplest version of the method just takes three parameters: the local port to listen on, and the remote host and port to forward the connection to:
-
-{{{lang=ruby,number=true,caption=Forwarding a local port
-Net::SSH.start( 'host' ) do |session|
-  session.forward.local( 1234, 'www.google.com', 80 )
-  session.loop
-end
-}}}
-
-In the above example, then, any connection received on port 1234 will be forwarded to port 80 on "www.google.com". This means that if you were to point a browser at "http://localhost:1234", it would pull up "Google":http://www.google.com.
-
-By default, only connections _from the local host_ are accepted. This is because the default bind address is 127.0.0.1. You can specify any bind address you want (including 0.0.0.0 to allow connections from anywhere) by specifying that address as the first parameter to @#local@, with the local port number immediately following.
-
-{{{lang=ruby,caption=Specifying the bind address when forwarding a local port
-session.forward.local( '0.0.0.0', 1234, 'www.google.com', 80 )
-}}}
-
-In this configuration, anyone from anywhere can connect to your machine on port 1234 and be forwarded to Google.

data/doc/manual/parts/0026.txt

@@ -1,15 +0,0 @@
-Forwarding remote connections to the local host is also straightforward; simply call the @#remote_to@ method of the @#forward@ service. This takes three (or four) parameters: the local port and host to be forwarded to (in that order), and the remote port to listen on. The fourth parameter is optional, and is the bind address on the remote machine; this defaults to "127.0.0.1".
-
-{{{lang=ruby,number=true,caption=Forwarding a remote port
-Net::SSH.start( 'host' ) do |session|
-  session.forward.remote_to( 80, 'www.google.com', 1234 )
-  session.loop
-end
-}}}
-
-The above example causes any connection on port 1234 of the remote machine (_from_ the remote machine) to be forwarded via the local host to port 80 at www.google.com. To make things a bit more open, you could specify a bind address of 0.0.0.0:
-
-{{{lang=ruby,caption=Specifying the bind address when forwarding a remote port
-session.forward.remote_to( 80, 'www.google.com', 1234, '0.0.0.0' )
-}}}
-