net-ssh 0.6.0 → 0.9.0

data/doc/manual/parts/channels_loop.txt

@@ -4,11 +4,11 @@ In order to allow the events to be processed in a continuous manner, you need to
 
 The @loop@ method is easy to invoke:
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    ...
-    session.loop
-  end
-</pre>
+[!figure lang=ruby,caption=Session#loop,number=true
+Net::SSH.start( 'host' ) do |session|
+  ...
+  session.loop
+end
+!]
 
 Incidentally, the @loop@ method accepts an optional block, which if specified should return a "false" value when the loop should terminate. In the absense of a block, the loop will continue until there are no more open channels.  Sometimes, however, you only want the loop to continue until some action occurs, at which time you then do some processing and then start the loop again.

data/doc/manual/parts/channels_open.txt

@@ -6,15 +6,15 @@ This behavior is typical of most of the methods in the Net::SSH API; they simply
 
 Here is an example of opening a channel:
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    session.open_channel do |channel|
-      puts "channel successfully opened... closing..."
-      channel.close
-    end
-
-    session.loop
+[!figure lang=ruby,caption=Opening a channel,number=true
+Net::SSH.start( 'host' ) do |session|
+  session.open_channel do |channel|
+    puts "channel successfully opened... closing..."
+    channel.close
   end
-</pre>
+
+  session.loop
+end
+!]
 
 Note the use of the @close@ method for the channel. Just like most methods in the Net::SSH API, it does not immediately close the channel, but instead sends a close request to the server and returns. When the server responds that the channel has been closed, the framework will then call any final callbacks for the channel and then remove it.

data/doc/manual/parts/exec_channels.txt

@@ -2,24 +2,24 @@ To run multiple processes in parallel, you can access the channel API directly,
 
 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:
 
-<pre>
-  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}"
+[!figure 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
-</pre>
+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.
 

data/doc/manual/parts/exec_open.txt

@@ -4,33 +4,32 @@ Just open an SSH session. The @#process@ service of the session manages access t
 
 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...
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
+[!figure 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" ]
+  session.process.open( "bc" ) do |bc|
+    dialog = [ "5+5", "7*12", "sqrt(2.000000)", "quit" ]
 
-      bc.on_success do |p|
+    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
-
-      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
 
+    bc.on_exit do |p, status|
+      puts "process finished with exit status: #{status}"
+    end
   end
-</pre>
 
+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.
 

data/doc/manual/parts/exec_popen3.txt

@@ -4,32 +4,32 @@ If you are familiar with the "popen3" Ruby module, this will seem familiar. It's
 
 Here's the previous "bc" example, rewritten to use @#popen3@:
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
+[!figure lang=ruby,number=true,caption=Using #process.popen3
+Net::SSH.start( 'host' ) do |session|
 
-    input, output, error = session.process.popen3( "bc" )
+  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
+  [ "5+5", "7*12", "sqrt(2.000000)" ].each do |formula|
+    input.puts formula
+    puts "#{formula}=#{output.read}"
+  end
 
-    input.puts "quit"
+  input.puts "quit"
 
-  end
-</pre>
+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:
 
-<pre>
-  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
+[!figure 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
-</pre>
+end
+!]
 
 The three streams will be closed and process explicitly terminated when the block ends.

data/doc/manual/parts/forward_direct.txt

@@ -14,24 +14,24 @@ table(list).
 
 For example, the following example pretends to be a client that has connected to the local host on a forwarded port:
 
-<pre>
-  class Handler
-    def on_receive( channel, data )
-      puts "got data: #{data.inspect}"
-      channel.send_data "subsequent request"
-    end
-
-    def process( channel )
-      channel.send_data "initial request"
-    end
+[!figure lang=ruby,number=true,caption=Using a handler object to mimic a forwarded port
+class Handler
+  def on_receive( channel, data )
+    puts "got data: #{data.inspect}"
+    channel.send_data "subsequent request"
   end
 
-  Net::SSH.start( 'host' ) do |session|
-    session.forward.direct_channel( 1234, 'somewhere.else.net',
-      4321, Handler.new )
-
-    session.loop
+  def process( channel )
+    channel.send_data "initial request"
   end
-</pre>
+end
+
+Net::SSH.start( 'host' ) do |session|
+  session.forward.direct_channel( 1234, 'somewhere.else.net',
+    4321, Handler.new )
+
+  session.loop
+end
+!]
 
 The local port number for @#direct_channel@ has no real purpose, other than to report to the SSH server that the "virtual" connection occurred on that port.

data/doc/manual/parts/forward_intro.txt

@@ -5,13 +5,13 @@ Port forwarding is a feature of the SSH protocol that allows you to specify a po
 
 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.
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    forward = session.forward
-    ...
-    session.loop
-  end
-</pre>
+[!figure 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?)
 

data/doc/manual/parts/forward_local.txt

@@ -1,18 +1,18 @@
 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:
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    session.forward.local( 1234, 'www.google.com', 80 )
-    session.loop
-  end
-</pre>
+[!figure 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.
 
-<pre>
-  session.forward.local( '0.0.0.0', 1234, 'www.google.com', 80 )
-</pre>
+[!figure 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/forward_remote.txt

@@ -1,14 +1,14 @@
 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".
 
-<pre>
-  Net::SSH.start( 'host' ) do |session|
-    session.forward.remote_to( 80, 'www.google.com', 1234 )
-    session.loop
-  end
-</pre>
+[!figure 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:
 
-<pre>
-  session.forward.remote_to( 80, 'www.google.com', 1234, '0.0.0.0' )
-</pre>
+[!figure 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' )
+!]

data/doc/manual/parts/intro_getting.txt

@@ -10,9 +10,9 @@ h3. Using "RubyGems":http://rubygems.rubyforge.org
 
 If you have "RubyGems":http://rubygems.rubyforge.org installed, installing Net::SSH is simple:
 
-<pre>
-  gem install net-ssh
-</pre>
+[!figure lang=shell,caption=Using Rubygems to install Net::SSH
+gem install net-ssh
+!]
 
 You still need to make sure you have a working version of Ruby's OpenSSL module, but other than that, you should be good to go!
 
@@ -20,9 +20,9 @@ h3. Using "rpa-base":http://rpa-base.rubyforge.org
 
 If you have "rpa-base":http://rpa-base.rubyforge.org installed:
 
-<pre>
-  rpa install net-ssh
-</pre>
+[!figure lang=shell,caption=Using RPA to install Net::SSH
+rpa install net-ssh
+!]
 
 As with the gem install, you still need to make sure you have a working version of Ruby's OpenSSL module, but other than that, you should be good to go!
 
@@ -32,8 +32,8 @@ If you don't have "RubyGems":http://rubygems.rubyforge.org or "rpa-base":http://
 
 Then, unpack the archive and run the @setup.rb@ script:
 
-<pre>
-  ruby setup.rb config
-  ruby setup.rb setup
-  ruby setup.rb install
-</pre>
+[!figure lang=shell,caption=Using setup.rb to install Net::SSH
+ruby setup.rb config
+ruby setup.rb setup
+ruby setup.rb install
+!]

data/doc/manual/parts/proxy_http.txt

@@ -1,17 +1,17 @@
 If you have an HTTP proxy running, you may be able to use it to your advantage.  The following snippet demonstrates how to tunnel an SSH connection through an HTTP proxy:
 
-<pre>
-  require 'net/ssh'
-  require 'net/ssh/proxy/http'
+[!figure lang=ruby,number=true,caption=Tunnelling an SSH connection over HTTP
+require 'net/ssh'
+require 'net/ssh/proxy/http'
 
-  proxy_host = 'my.proxy.com'
-  proxy_port = 8080
-  proxy = Net::SSH::Proxy::HTTP.new( proxy_host, proxy_port )
+proxy_host = 'my.proxy.com'
+proxy_port = 8080
+proxy = Net::SSH::Proxy::HTTP.new( proxy_host, proxy_port )
 
-  Net::SSH.start( 'host', :proxy => proxy ) do |session|
-    ...
-  end
-</pre>
+Net::SSH.start( 'host', :proxy => proxy ) do |session|
+  ...
+end
+!]
 
 As you can see, you first create an instance of the proxy you want to use. (This flexibility allows for other proxy types to be supported, although at present only HTTP and SOCKS are available.)
 
@@ -21,9 +21,9 @@ Note: If your proxy does not allow connects to be made to other hosts on port 22
 
 For instance, if your proxy disallows connections to any port except (say) 443, you could run the following command on the remote host:
 
-<pre>
-  ssh -gL 443:localhost:22 localhost
-</pre>
+[!figure lang=shell,caption=Forwarding a port using the ssh command
+ssh -gL 443:localhost:22 localhost
+!]
 
 Then, as long as that command is running, port 443 will always be forwarded to port 22.  Naturally, this means that you must run this command while you have access to the box; if you can't access that machine in the first place (ie, because you're behind a firewall), then it does you no good.
 
@@ -31,22 +31,22 @@ h3. Proxy Authentication
 
 Some proxies require authentication. Net::SSH supports these proxies as well. If you specify the user name either as a @:user@ option to the HTTP proxy constructor, or in the @HTTP_PROXY_USER@ or @CONNECT_USER@ environment variables, that name will be used to authenticate with the proxy. Likewise, the password may be given either via the @:password@ constructor option, or via the @HTTP_PROXY_PASSWORD@ or @CONNECT_PASSWORD@ environment variables.
 
-<pre>
-  require 'net/ssh'
-  require 'net/ssh/proxy/http'
+[!figure lang=ruby,number=true,caption=Using HTTP proxy authentication
+require 'net/ssh'
+require 'net/ssh/proxy/http'
 
-  proxy_host = 'my.proxy.com'
-  proxy_port = 8080
-  proxy_user = 'my-name'
-  proxy_password = 'my-password'
+proxy_host = 'my.proxy.com'
+proxy_port = 8080
+proxy_user = 'my-name'
+proxy_password = 'my-password'
 
-  proxy = Net::SSH::Proxy::HTTP.new( proxy_host, proxy_port,
-              :user => proxy_user,
-              :password => proxy_password )
+proxy = Net::SSH::Proxy::HTTP.new( proxy_host, proxy_port,
+            :user => proxy_user,
+            :password => proxy_password )
 
-  Net::SSH.start( 'host', :proxy => proxy ) do |session|
-    ...
-  end
-</pre>
+Net::SSH.start( 'host', :proxy => proxy ) do |session|
+  ...
+end
+!]
 
 Note that currently, only basic authentication is supported; in the future, digest authentication may be added for proxies that support it.

data/doc/manual/parts/proxy_socks.txt

@@ -1,23 +1,23 @@
 In addition to the HTTP proxy, Net::SSH also supports SOCKS proxies (both versions 4 and 5). Their usage is almost identical to the HTTP version (except SOCKS4 does not use passwords, just user names):
 
-<pre>
-  require 'net/ssh'
-  require 'net/ssh/proxy/socks4'
-  require 'net/ssh/proxy/socks5'
+[!figure lang=ruby,number=true,caption=Using SOCKS proxies 
+require 'net/ssh'
+require 'net/ssh/proxy/socks4'
+require 'net/ssh/proxy/socks5'
 
-  proxy_host = 'my.proxy.com'
-  proxy_port = 1080
-  proxy_user = 'my-name'
-  proxy_password = 'my-password'
+proxy_host = 'my.proxy.com'
+proxy_port = 1080
+proxy_user = 'my-name'
+proxy_password = 'my-password'
 
-  socks4 = Net::SSH::Proxy::SOCKS4.new( proxy_host, proxy_port,
-              :user => proxy_user )
+socks4 = Net::SSH::Proxy::SOCKS4.new( proxy_host, proxy_port,
+            :user => proxy_user )
 
-  socks5 = Net::SSH::Proxy::SOCKS5.new( proxy_host, proxy_port,
-              :user => proxy_user,
-              :password => proxy_password)
+socks5 = Net::SSH::Proxy::SOCKS5.new( proxy_host, proxy_port,
+            :user => proxy_user,
+            :password => proxy_password)
 
-  Net::SSH.start( 'host', :proxy => socks4 ) do |session|
-    ...
-  end
-</pre>
+Net::SSH.start( 'host', :proxy => socks4 ) do |session|
+  ...
+end
+!]