net-ssh 1.0.0 → 1.0.1

data/doc/manual/parts/{intro_author.txt → 0005.txt}

@@ -1 +1 @@
-Net::SSH was written by "Jamis Buck":mailto:jgb3@email.byu.edu. Feel free to send him compliments, candy, money, praise, or new feature patches--he likes all those things. You can send him questions and suggestions, too, if you really want to. However, for bug reports and general feature requests, please use the trackers on the "Net::SSH project page":http://rubyforge.org/projects/net-ssh.
+Net::SSH was written by "Jamis Buck":mailto:jamis_buck@byu.edu. Feel free to send him compliments, candy, money, praise, or new feature patches--he likes all those things. You can send him questions and suggestions, too, if you really want to. However, for bug reports and general feature requests, please use the trackers on the "Net::SSH project page":http://rubyforge.org/projects/net-ssh.

data/doc/manual/parts/{session_start.txt → 0006.txt}

@@ -1,46 +1,46 @@
 Before you can do anything with Net::SSH, you need to require the @net/ssh@ module:
 
-[!figure lang=ruby,caption=Requiring Net::SSH
+{{{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.
 
-[!figure lang=ruby,number=true,caption=Opening an SSH session
+{{{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.
 
-[!figure lang=ruby,number=true,caption=Opening a transactional SSH session
+{{{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:
 
-[!figure lang=ruby,number=true,caption=Specifying the SSH port
+{{{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.
 
-[!figure lang=ruby,number=true,caption=Using keyword arguments
+{{{lang=ruby,number=true,caption=Using keyword arguments
 Net::SSH.start( 'host',
                 :password=>'passwd', 
                 :port=>1234,
                 :username=>'user',
-                ... ) do |session|
+       ... ) do |session|
   ...
 end
-!]
+}}}
 
 (More about the "@...@" stuff, later.)
 

data/doc/manual/parts/{session_key.txt → 0007.txt}

@@ -16,9 +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).
 
-[!figure lang=shell,caption=Generating an SSH key
+{{{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.)
 
@@ -32,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!
 
-[!figure lang=ruby,number=true,caption=SSH authentication using keys
+{{{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:
 
-[!figure lang=ruby,number=true,caption=Authentication with an implicit user name
+{{{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 → 0008.txt}

@@ -1,6 +1,5 @@
 There are various additional options that you can specify when connecting. These options allow you to specify such things as the cipher algorithm to use, whether or not the data stream will be compressed, or explicit paths to the private keys to use.
 
-
 Options are specified as a hash in the last parameter to the @start@ method. If using the keyword parameters version of the @start@ method, the options hash is whatever is left after processing the @:username@, @:password@, and @:port@ options.
 
 The complete list of available options, and their valid values, is given in the following table.
@@ -26,7 +25,7 @@ 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.
 
-[!figure lang=ruby,number=true,caption=Specifying options when connecting
+{{{lang=ruby,number=true,caption=Specifying options when connecting
 require 'net/ssh'
 require 'logger'
 
@@ -39,4 +38,4 @@ Net::SSH.start(
 ) do |session|
   ...
 end
-!]
+}}}

data/doc/manual/parts/0009.txt

@@ -0,0 +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.
+
+{{{lang=ruby,number=true,caption=Using Net::SSH::Session
+require 'net/ssh'
+
+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/{channels_loop.txt → 0011.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:
 
-[!figure lang=ruby,caption=Session#loop,number=true
+{{{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 → 0013.txt}

@@ -6,7 +6,7 @@ This behavior is typical of most of the methods in the Net::SSH API; they simply
 
 Here is an example of opening a channel:
 
-[!figure lang=ruby,caption=Opening a channel,number=true
+{{{lang=ruby,caption=Opening a channel,number=true
 Net::SSH.start( 'host' ) do |session|
   session.open_channel do |channel|
     puts "channel successfully opened... closing..."
@@ -15,6 +15,6 @@ Net::SSH.start( 'host' ) do |session|
 
   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/{channels_callbacks.txt → 0014.txt}

@@ -5,7 +5,7 @@ table(list).
 |=^. @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_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.|
@@ -17,7 +17,7 @@ In general, you will never need to register callbacks for @on_failure@, @on_requ
 
 Following is an example of registering callbacks on a channel:
 
-[!figure lang=ruby,caption=Registering callbacks on a channel,number=true
+{{{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|
@@ -29,4 +29,4 @@ Net::SSH.start( 'host' ) do |session|
 
   session.loop
 end
-!]
+}}}

data/doc/manual/parts/{channels_operations.txt → 0015.txt}

@@ -11,5 +11,4 @@ table(list).
 | @#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.
+See the API documentation for an exhaustive reference of all available channel operations.

data/doc/manual/parts/{exec_channels.txt → 0016.txt}

@@ -2,7 +2,7 @@ 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:
 
-[!figure lang=ruby,number=true,caption=Running "tail" on multiple remote files
+{{{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|
@@ -19,7 +19,7 @@ Net::SSH.start( 'host' ) do |session|
   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 → 0017.txt}

@@ -4,7 +4,7 @@ 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...
 
-[!figure lang=ruby,number=true,caption=Using #process.open
+{{{lang=ruby,number=true,caption=Using #process.open
 Net::SSH.start( 'host' ) do |session|
 
   session.process.open( "bc" ) do |bc|
@@ -23,13 +23,13 @@ Net::SSH.start( 'host' ) do |session|
       end
     end
 
-    bc.on_exit do |p, status|
+ 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.
 

data/doc/manual/parts/{exec_popen3.txt → 0018.txt}

@@ -4,7 +4,7 @@ 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@:
 
-[!figure lang=ruby,number=true,caption=Using #process.popen3
+{{{lang=ruby,number=true,caption=Using #process.popen3
 Net::SSH.start( 'host' ) do |session|
 
   input, output, error = session.process.popen3( "bc" )
@@ -17,19 +17,19 @@ Net::SSH.start( 'host' ) do |session|
   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:
 
-[!figure lang=ruby,number=true,caption=Transactional form of #process.popen3
+{{{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}"
+ 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/{shells_channels.txt → 0020.txt}

@@ -1,6 +1,6 @@
 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
+{{{lang=ruby,caption=Sending a shell request,number=true
 Net::SSH.start( host ) do |session|
 
   session.open_channel do |channel|
@@ -26,13 +26,13 @@ Net::SSH.start( host ) do |session|
   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
+{{{lang=ruby,number=true,caption=Opening a pty on a channel
 Net::SSH.start( host ) do |session|
 
   session.open_channel do |channel|
@@ -65,8 +65,8 @@ Net::SSH.start( host ) do |session|
   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.
+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_shell.txt → 0021.txt}

@@ -1,6 +1,6 @@
 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
+{{{lang=ruby,number=true,caption=Using the shell service
 Net::SSH.start( 'localhost' ) do |session|
 
   shell = session.shell.open
@@ -27,13 +27,13 @@ Net::SSH.start( 'localhost' ) do |session|
   $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
+{{{lang=ruby,number=true,caption=Allocating a pty for the shell
 Net::SSH.start( 'localhost' ) do |session|
 
   shell = session.shell.open( :pty => true )
@@ -43,8 +43,8 @@ Net::SSH.start( 'localhost' ) do |session|
   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.
+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.
+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 → 0022.txt}

@@ -1,6 +1,6 @@
 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
+{{{lang=ruby,number=true,caption=Using the SyncShell service
 Net::SSH.start( 'localhost' ) do |session|
 
   shell = session.shell.sync
@@ -20,7 +20,7 @@ Net::SSH.start( 'localhost' ) do |session|
 
   out = shell.cd "/usr/lib"
 
-  out = shell.ls "-l"
+ out = shell.ls "-l"
   p out.stdout
 
   out = shell.send_command( "bc", <<CMD )
@@ -35,8 +35,8 @@ CMD
   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.
+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/{shells_clients.txt → 0023.txt}

@@ -1,6 +1,6 @@
 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
+{{{lang=ruby,number=true,caption=A simple SSH terminal client in Ruby
 begin
   require 'termios'
 rescue LoadError
@@ -26,7 +26,7 @@ end
 
 Net::SSH.start( host, user ) do |session|
 
-  begin
+ begin
     stdin_buffer false
 
     shell = session.shell.open( :pty => true )
@@ -46,6 +46,6 @@ Net::SSH.start( host, user ) do |session|
   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/{forward_intro.txt → 0024.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.
 
-[!figure lang=ruby,number=true,caption=Accessing the #forward service
+{{{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 → 0025.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:
 
-[!figure lang=ruby,number=true,caption=Forwarding a local port
+{{{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.
 
-[!figure lang=ruby,caption=Specifying the bind address when forwarding a local port
+{{{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.