net-ssh 0.6.0 → 0.9.0

data/doc/manual/parts/session_key.txt

@@ -16,10 +16,9 @@ The "id_dsa" key is the preferred key (since it uses the stronger DSA encryption
 
 To create these keys, you can use the "ssh-keygen" utility from "OpenSSH":http://www.openssh.org. Alternatively, if you have the Net::SSH::Utilities package installed, you can use the "rb-keygen" utility (which is a pure-Ruby implementation of most of the functionality of ssh-keygen).
 
-<pre>
-  ssh-keygen -t dsa
-</pre>
-
+[!figure lang=shell,caption=Generating an SSH key
+ssh-keygen -t dsa
+!]
 
 (If you would rather use an RSA key, replace "dsa" with "rsa" in the command given above.)
 
@@ -33,19 +32,19 @@ h3. Connecting using public/private keys
 
 Public/private keys are always tried before the explicit password authentication, even if you provide a password. Thus, if you _only_ want to use public/private key authentication, simply remove the password from the argument list. If you can successfully obtain a session handle, then your keys are set up correctly!
 
-<pre>
-  Net::SSH.start( 'host', 'user' ) do |session|
-    ...
-  end
-</pre>
+[!figure lang=ruby,number=true,caption=SSH authentication using keys
+Net::SSH.start( 'host', 'user' ) do |session|
+  ...
+end
+!]
 
 Furthermore, if your @USER@ environment variable is set to the username that you want to log into the remote machine as, you can even leave the @username@ parameter off:
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    ...
-  end
-</pre>
+[!figure lang=ruby,number=true,caption=Authentication with an implicit user name
+Net::SSH.start( 'host' ) do |session|
+  ...
+end
+!]
 
 h3. Using keys with passphrases
 

data/doc/manual/parts/session_options.txt

@@ -7,7 +7,7 @@ The complete list of available options, and their valid values, is given in the
 
 table(list).
 |_. Option |_. Description |
-|^=. @:auth_methods@ | This is the list of authorization methods to try. It defaults to "publickey", "keyboard-interactive", "password", and "hostbased". (These are also the only authorization methods that are supported.) If you want them to be tried in a different order, or if you don't want certain methods to be used, you can specify your own list via this option.|
+|^=. @:auth_methods@ | This is the list of authorization methods to try. It defaults to "publickey", "hostbased", "password", and "keyboard-interactive". (These are also the only authorization methods that are supported.) If you want them to be tried in a different order, or if you don't want certain methods to be used, you can specify your own list via this option.|
 |^=. @:compression@ | The compression algorithm to use when compressing the data stream. Valid values are @none@ and @zlib@. The default is @none@.|
 |^=. @:compression_level@ | This is only used when the compression algorithm is @zlib@. It is an integer value from 0 to 9, representing the quality of the compression. A 0 is no compression, and a 9 is most compression. The default is 6.|
 |^=. @:container@ | This is the dependency injection container to use when registering all of the services that Net::SSH uses internally. If unspecified (the default) a new container will be created. This option allows you to reuse a single container for multiple application components.|
@@ -26,17 +26,17 @@ table(list).
 
 For example, the following code snippet will connect to the given remote host, and requests that the @ssh-rsa@ host key type be used, with the @blowfish-cbc@ cipher algorithm, and requests that the given private key file be used. Also, the data stream will be compressed.
 
-<pre>
-  require 'net/ssh'
-  require 'logger'
+[!figure lang=ruby,number=true,caption=Specifying options when connecting
+require 'net/ssh'
+require 'logger'
 
-  Net::SSH.start(
-    'host', 'user',
-    :host_key => "ssh-rsa",
-    :encryption => "blowfish-cbc",
-    :keys => [ "/tmp/temporary-key" ],
-    :compression => "zlib"
-  ) do |session|
-    ...
-  end
-</pre>
+Net::SSH.start(
+  'host', 'user',
+  :host_key => "ssh-rsa",
+  :encryption => "blowfish-cbc",
+  :keys => [ "/tmp/temporary-key" ],
+  :compression => "zlib"
+) do |session|
+  ...
+end
+!]

data/doc/manual/parts/session_session.txt

@@ -1,14 +1,14 @@
 Alternatively, you can use Net::SSH::Session to start your SSH sessions. The @Net::SSH.start@ interface described above is simply a convenience for creating a new Session object explicitly.
 
-<pre>
-  require 'net/ssh'
+[!figure lang=ruby,number=true,caption=Using Net::SSH::Session
+require 'net/ssh'
 
-  Net::SSH::Session.new(
-    'host', 'username', 'password',
-    :compression => "zlib"
-  ) do |session|
-    ...
-  end
-</pre>
+Net::SSH::Session.new(
+  'host', 'username', 'password',
+  :compression => "zlib"
+) do |session|
+  ...
+end
+!]
 
 Note that Net::SSH::Session#new accepts the same parameters as Net::SSH.start, and may also be called without a block.

data/doc/manual/parts/session_start.txt

@@ -1,46 +1,46 @@
 Before you can do anything with Net::SSH, you need to require the @net/ssh@ module:
 
-<pre>
-  require 'net/ssh'
-</pre>
+[!figure lang=ruby,caption=Requiring Net::SSH
+require 'net/ssh'
+!]
 
 Once you have required the @net/ssh@ module, you can begin an SSH session by calling @Net::SSH.start@.  This may be used in one of two ways. If called without a block, it will return a reference to the new session as an instance of a @Net::SSH::Session@. Used this way, you must explicitly close the session when you are finished with it.
 
-<pre>
-  session = Net::SSH.start( 'host', 'user', 'passwd' )
-  ...
-  session.close
-</pre>
+[!figure lang=ruby,number=true,caption=Opening an SSH session
+session = Net::SSH.start( 'host', 'user', 'passwd' )
+...
+session.close
+!]
 
 The other approach involves attaching a block to the start method. When used this way, the new session is passed to the block, and the session is automatically closed when the block exits.
 
-<pre>
-  Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
-    ...
-  end
-</pre>
+[!figure lang=ruby,number=true,caption=Opening a transactional SSH session
+Net::SSH.start( 'host', 'user', 'passwd' ) do |session|
+  ...
+end
+!]
 
 If you need to specify a different port on the host to connect to (the default is 22), you can specify it immediately after the @host@ parameter, like so:
 
-<pre>
-  Net::SSH.start( 'host', 1234, 'user', 'passwd' ) do |session|
-    ...
-  end
-</pre>
+[!figure lang=ruby,number=true,caption=Specifying the SSH port
+Net::SSH.start( 'host', 1234, 'user', 'passwd' ) do |session|
+  ...
+end
+!]
 
 h3. Using Keyword Arguments
 
 Some people prefer using keyword arguments for functions with more than a couple of parameters. The @start@ method supports this approach as well, although the @host@ parameter is always positional and always comes first.
 
-<pre>
-  Net::SSH.start( 'host',
-                  :password=>'passwd', 
-                  :port=>1234,
-                  :username=>'user',
-                  ... ) do |session|
-    ...
-  end
-</pre>
+[!figure lang=ruby,number=true,caption=Using keyword arguments
+Net::SSH.start( 'host',
+                :password=>'passwd', 
+                :port=>1234,
+                :username=>'user',
+                ... ) do |session|
+  ...
+end
+!]
 
 (More about the "@...@" stuff, later.)
 

data/doc/manual/parts/shells_channels.txt

@@ -0,0 +1,72 @@
+At the lowest level, starting a shell is a matter of sending a "shell" request over a channel.
+
+[!figure 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:
+
+[!figure 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/shells_clients.txt

@@ -0,0 +1,51 @@
+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.)
+
+[!figure 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/shells_intro.txt

@@ -0,0 +1,7 @@
+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/shells_shell.txt

@@ -0,0 +1,50 @@
+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.
+
+[!figure 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:
+
+[!figure 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/shells_sync.txt

@@ -0,0 +1,42 @@
+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.
+
+[!figure 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/{manual.css → stylesheets/manual.css}

@@ -107,12 +107,6 @@ a:hover {
   text-align: justify;
 }
 
-#content pre {
-  background: #FFE;
-  border: 1px dotted #AAA;
-  padding: 1em;
-}
-
 #content h1 {
   background: #005;
   color: #FFF;
@@ -186,7 +180,86 @@ a:hover {
   text-align: center;
 }
 
-table.list td {
-  border-bottom: 1px dotted #005;
+table.list {
+  margin: 2em;
+  border: 1px solid black;
+  background: #FFD;
+  padding: 0px;
+  border-spacing: 0px;
+}
+
+table.list th {
+  border-bottom: 1px solid #005;
   padding-bottom: 5px;
+  background: #008;
+  color: white;
+  padding: 0.5em;
+  text-align: left;
+}
+
+table.list td {
+  padding: 0.2em;
+  text-align: left;
+  vertical-align: top;
+  border-bottom: 1px solid;
+}
+
+.prevnext {
+  padding: 0.5em 1em 0.5em 1em;
+  background: #557;
+  color: #FFF;
+  font-size: small;
+  font-weight: bold;
+  border: 1px solid #000;
+}
+
+.prevnext a {
+  color: #FF0;
+}
+
+.top .prevnext {
+  margin: 0 0 1em 0;
+  text-align: left;
+}
+
+.bottom .prevnext {
+  margin: 1em 0 0 0;
+  text-align: right;
+}
+
+.figure {
+  border: 1px solid black;
+  line-height: normal;
+  background: #FFD;
+  margin: 2em;
+}
+
+.figure .caption {
+  background: #008;
+  color: white;
+  font-weight: bold;
+  font-size: small;
+  padding: 4px 24px 4px 8px;
+  margin-left: -4px;
+  border: 1px dotted #77F;
+}
+
+.figure .body {
+  padding-left: 1em;
+}
+
+.figure pre {
+  padding: 0px;
+  background: transparent;
+  border: none;
+  font-size: small;
+  font-family: mono;
+}
+
+.figure .lineno {
+  text-align: right;
+  color: #B00;
+  font-family: mono;
+  font-size: small;
+  padding-right: 1em;
 }