net-ssh-multi 1.2.0

From 0348314d0c7edfe8797a95c1c1e22b4c47cdf913 Mon Sep 17 00:00:00 2001 From: delano Date: Sat, 11 Apr 2015 13:14:37 -0700 Subject: Updated docs --- classes/Net/SSH/Multi.html | 4 +- classes/Net/SSH/Multi/Channel.html | 54 +++++++++---------- classes/Net/SSH/Multi/ChannelProxy.html | 4 +- classes/Net/SSH/Multi/DynamicServer.html | 16 +++--- classes/Net/SSH/Multi/PendingConnection.html | 11 ++-- classes/Net/SSH/Multi/Server.html | 59 ++++++++++---------- classes/Net/SSH/Multi/ServerList.html | 2 +- classes/Net/SSH/Multi/Session.html | 62 +++++++++++----------- classes/Net/SSH/Multi/SessionActions.html | 34 ++++++------ classes/Net/SSH/Multi/Subsession.html | 4 +- classes/Net/SSH/Multi/Version.html | 2 +- created.rid | 30 +++++------ files/CHANGES_txt.html | 21 +++++--- files/README_rdoc.html | 20 +++---- files/lib/net/ssh/multi/channel_proxy_rb.html | 2 +- files/lib/net/ssh/multi/channel_rb.html | 2 +- files/lib/net/ssh/multi/dynamic_server_rb.html | 2 +- files/lib/net/ssh/multi/pending_connection_rb.html | 2 +- files/lib/net/ssh/multi/server_list_rb.html | 2 +- files/lib/net/ssh/multi/server_rb.html | 2 +- files/lib/net/ssh/multi/session_actions_rb.html | 2 +- files/lib/net/ssh/multi/session_rb.html | 2 +- files/lib/net/ssh/multi/subsession_rb.html | 2 +- files/lib/net/ssh/multi/version_rb.html | 2 +- files/lib/net/ssh/multi_rb.html | 2 +- fr_method_index.html | 42 +++++++-------- index.html | 2 +- 27 files changed, 197 insertions(+), 192 deletions(-) diff --git a/classes/Net/SSH/Multi.html b/classes/Net/SSH/Multi.html index c9ae8ee..0e96808 100644 --- a/classes/Net/SSH/Multi.html +++ b/classes/Net/SSH/Multi.html @@ -88,7 +88,7 @@ parallel, and allows commands to be executed on subsets of servers (defined by groups).

-

require 'net/ssh/multi'

Net::SSH::Multi.start do |session|
  # access servers via a gateway
  session.via 'gateway', 'gateway-user'

  # define the servers we want to use
  session.use 'user1@host1'
  session.use 'user2@host2'

  # define servers in groups for more granular access
  session.group :app do
    session.use 'user@app1'
    session.use 'user@app2'
  end

  # execute commands on all servers
  session.exec "uptime"

  # execute commands on a subset of servers
  session.with(:app).exec "hostname"

  # run the aggregated event loop
  session.loop
end

+

require 'net/ssh/multi'
Net::SSH::Multi.start do |session|
  # access servers via a gateway
  session.via 'gateway', 'gateway-user'

  # define the servers we want to use
  session.use 'user1@host1'
  session.use 'user2@host2'

  # define servers in groups for more granular access
  session.group :app do
    session.use 'user@app1'
    session.use 'user@app2'
  end

  # execute commands on all servers
  session.exec "uptime"

  # execute commands on a subset of servers
  session.with(:app).exec "hostname"

  # run the aggregated event loop
  session.loop
end

See Net::SSH::Multi::Session for more documentation.

@@ -135,7 +135,7 @@ href="Multi/Session.html#method-i-close">Net::SSH::Multi::Session#close) when the block finishes. Otherwise, the new session will be returned.

-

Net::SSH::Multi.start do |session|
  # ...
end

session = Net::SSH::Multi.start
# ...
session.close

+

Net::SSH::Multi.start do |session|
  # ...
end
session = Net::SSH::Multi.start
# ...
session.close

Any options are passed directly to Net::SSH::Multi::Session.new diff --git a/classes/Net/SSH/Multi/Channel.html b/classes/Net/SSH/Multi/Channel.html index e535eb3..7718b9b 100644 --- a/classes/Net/SSH/Multi/Channel.html +++ b/classes/Net/SSH/Multi/Channel.html @@ -51,16 +51,16 @@

You typically obtain a Net::SSH::Multi::Channel instance via Net::SSH::Multi::SessionActions#open_channel + href="SessionActions.html#method-i-open_channel">Net::SSH::Multi::Session#open_channel or Net::SSH::Multi::SessionActions#exec, + href="SessionActions.html#method-i-exec">Net::SSH::Multi::Session#exec, though there is nothing stopping you from instantiating one yourself with a handful of Net::SSH::Connection::Channel objects (though they should be associated with connections managed by a Net::SSH::Multi::Session object for consistent behavior).

-

channel = session.open_channel do |ch|
  # ...
end

channel.wait

+

channel = session.open_channel do |ch|
  # ...
end
channel.wait

Methods

@@ -151,13 +151,13 @@

Instantiate a new Net::SSH::Multi::Channel - instance, controlled by the given connection (a connection (a Net::SSH::Multi::Session object) and wrapping the - given channels (Net::SSH::Connection::Channel instances).

+ given channels (Net::SSH::Connection::Channel instances).

You will typically never call this directly; rather, you'll get your multi-channel references via Net::SSH::Multi::SessionActions#open_channel + href="SessionActions.html#method-i-open_channel">Net::SSH::Multi::Session#open_channel and friends.

@@ -178,7 +178,7 @@

Retrieve the property (see properties) with the given - key.

+ key.

host = channel[:host]

@@ -199,7 +199,7 @@

Set the property (see properties) with the given - key to the given value.

+ key to the given value.

channel[:visited] = true

@@ -290,13 +290,13 @@

-

Perform an exec command on all component channels. The block, - if given, is passed to each component channel, so it will (potentially) be +

Perform an exec command on all component channels. The block, if + given, is passed to each component channel, so it will (potentially) be invoked once for every channel in the collection. The block will receive two parameters: the specific channel object being operated on, and a boolean indicating whether the exec succeeded or not.

-

channel.exec "ls -l" do |ch, success|
  # ...
end

+

channel.exec "ls -l" do |ch, success|
  # ...
end

See the documentation in Net::SSH for Net::SSH::Connection::Channel#exec for more information on how to work with @@ -321,7 +321,7 @@ remote server terminates the channel. The callback will be invoked with one argument: the specific channel object being closed.

-

channel.on_close do |ch|
  # ...
end

+

channel.on_close do |ch|
  # ...
end

@@ -339,11 +339,11 @@

Registers a callback on all component channels, to be invoked when the - remote process emits data (usually on its stdout stream). The + remote process emits data (usually on its stdout stream). The block will be invoked with two arguments: the specific channel object, and the data that was received.

channel.on_data do |ch, data|
  puts "got data: #{data}"
end

channel.on_data do |ch, data|
  puts "got data: #{data}"
end

@@ -364,7 +364,7 @@ remote server has no further data to send. The callback will be invoked with one argument: the specific channel object being marked EOF.

channel.on_eof do |ch|
  # ...
end

channel.on_eof do |ch|
  # ...
end

@@ -382,12 +382,12 @@

Registers a callback on all component channels, to be invoked when the - remote process emits "extended" data (typically on its stderr + remote process emits "extended" data (typically on its stderr stream). The block will be invoked with three arguments: the specific channel object, an integer describing the data type (usually a 1 for - stderr) and the data that was received.

+ stderr) and the data that was received.

channel.on_extended_data do |ch, type, data|
  puts "got extended data: #{data}"
end

channel.on_extended_data do |ch, type, data|
  puts "got extended data: #{data}"
end

@@ -410,7 +410,7 @@ description of the error (as a string), and an integer code representing the error.

channel.on_open_failed do |ch, description, code|
  # ...
end

channel.on_open_failed do |ch, description, code|
  # ...
end

@@ -431,7 +431,7 @@ idle portion of the connection event loop. The callback will be invoked with one argument: the specific channel object being processed.

channel.on_process do |ch|
  # ...
end

channel.on_process do |ch|
  # ...
end

@@ -449,12 +449,12 @@

Registers a callback on all component channels, to be invoked when the - remote server sends a channel request of the given type. The + remote server sends a channel request of the given type. The callback will be invoked with two arguments: the specific channel object receiving the request, and a Net::SSH::Buffer instance containing the request-specific data.

channel.on_request("exit-status") do |ch, data|
  puts "exited with #{data.read_long}"
end

channel.on_request("exit-status") do |ch, data|
  puts "exited with #{data.read_long}"
end

@@ -471,14 +471,14 @@

Perform a request_pty command on all component channels. The +

Perform a request_pty command on all component channels. The block, if given, is passed to each component channel, so it will (potentially) be invoked once for every channel in the collection. The block will receive two parameters: the specific channel object being operated on, and a boolean indicating whether the pty request succeeded or not.

channel.request_pty do |ch, success|
  # ...
end

channel.request_pty do |ch, success|
  # ...
end

See the documentation in Net::SSH for Net::SSH::Connection::Channel#request_pty for more information on how to @@ -499,9 +499,9 @@

-

Send the given data to each component channel. It will be sent - to the remote process, typically being received on the process' - stdin stream.

+

Send the given data to each component channel. It will be sent to + the remote process, typically being received on the process' stdin + stream.

channel.send_data "password\n"

diff --git a/classes/Net/SSH/Multi/ChannelProxy.html b/classes/Net/SSH/Multi/ChannelProxy.html index dfa3bb7..9455d54 100644 --- a/classes/Net/SSH/Multi/ChannelProxy.html +++ b/classes/Net/SSH/Multi/ChannelProxy.html @@ -104,7 +104,7 @@

-

Instantiates a new channel proxy with the given on_confirm +

Instantiates a new channel proxy with the given on_confirm callback.

@@ -124,7 +124,7 @@

Instructs the proxy to delegate all further actions to the given - channel (which must be an instance of + channel (which must be an instance of Net::SSH::Connection::Channel). All recorded actions are immediately replayed, in order, against the delegate channel.

diff --git a/classes/Net/SSH/Multi/DynamicServer.html b/classes/Net/SSH/Multi/DynamicServer.html index 376e0b3..dcdadf0 100644 --- a/classes/Net/SSH/Multi/DynamicServer.html +++ b/classes/Net/SSH/Multi/DynamicServer.html @@ -51,11 +51,11 @@

session.use { lookup_ip_address_of_server }

-

This prevents lookup_ip_address_of_server from being invoked +

This prevents lookup_ip_address_of_server from being invoked unless the server is actually needed, at which point it is invoked and the result cached.

-

The callback should return either nil (in which case no new +

The callback should return either nil (in which case no new servers are instantiated), a String (representing a connection specification), an array of Strings, or an array of Net::SSH::Multi::Server instances.

@@ -142,8 +142,8 @@

Create a new DynamicServer record, owned by the given Net::SSH::Multi::Session - master, with the given hash of options, and using - the given Proc callback to lazily evaluate the actual server + master, with the given hash of options, and using the + given Proc callback to lazily evaluate the actual server instances.

@@ -162,9 +162,9 @@

-

Returns the value for the given key in the :properties hash of - the options. If no :properties hash exists in - options, this returns nil.

+

Returns the value for the given key in the :properties hash of the + options. If no :properties hash exists in options, this + returns nil.

@@ -181,7 +181,7 @@

Sets the given key/value pair in the :properties key in the +

Sets the given key/value pair in the :properties key in the options hash. If the options hash has no :properties key, it will be created.

diff --git a/classes/Net/SSH/Multi/PendingConnection.html b/classes/Net/SSH/Multi/PendingConnection.html index e77407a..42a4f2f 100644 --- a/classes/Net/SSH/Multi/PendingConnection.html +++ b/classes/Net/SSH/Multi/PendingConnection.html @@ -132,8 +132,8 @@

Always returns true, so that the pending connection looks - active until it can be truly opened and replaced with a real connection.

Always returns true, so that the pending connection looks active + until it can be truly opened and replaced with a real connection.

@@ -222,7 +222,7 @@

Returns true, and does nothing else.

Returns true, and does nothing else.

@@ -239,7 +239,7 @@

Returns true, and does nothing else.

Returns true, and does nothing else.

@@ -257,8 +257,7 @@

Instructs the pending session to replay all of its recordings against the - given session, and to then replace itself with the given - session.

+ given session, and to then replace itself with the given session.

diff --git a/classes/Net/SSH/Multi/Server.html b/classes/Net/SSH/Multi/Server.html index 61a38cf..43fe049 100644 --- a/classes/Net/SSH/Multi/Server.html +++ b/classes/Net/SSH/Multi/Server.html @@ -97,7 +97,7 @@

The Net::SSH::Gateway instance to use to establish the connection. Will be - nil if the connection should be established without a gateway.

+ nil if the connection should be established without a gateway.

@@ -157,11 +157,10 @@

Creates a new Server instance with the given - connection information. The master argument must be a - reference to the Net::SSH::Multi::Session - instance that will manage this server reference. The options - hash must conform to the options described for Net::SSH::start, with two - additions:

+ connection information. The master argument must be a reference to + the Net::SSH::Multi::Session instance that will + manage this server reference. The options hash must conform to the + options described for Net::SSH::start, with two additions:

:via => a Net::SSH::Gateway instance to use when establishing a connection to this server.
@@ -169,9 +168,9 @@
:user => the name of the user to use when logging into this server.

-

The host argument may include the username and port number, in +

The host argument may include the username and port number, in which case those values take precedence over similar values given in the - options:

+ options:

server = Net::SSH::Multi::Server.new(session, 'user@host:1234')
puts server.user #-> user
puts server.port #-> 1234

@@ -179,7 +178,7 @@ [show source] -

# File lib/net/ssh/multi/server.rb, line 43
def initialize(master, host, options={})
  @master = master
  @options = options.dup

  @user, @host, port = host.match(%r^(?:([^;,:=]+)@|)(.*?)(?::(\d+)|)$/)[1,3]

  user_opt, port_opt = @options.delete(:user), @options.delete(:port)

  @user = @user || user_opt || master.default_user
  port ||= port_opt

  @options[:port] = port.to_i if port

  @gateway = @options.delete(:via)
  @failed = false
end

+

# File lib/net/ssh/multi/server.rb, line 43
def initialize(master, host, options={})
  @master = master
  @options = options.dup

  @user, @host, port = host.match(/^(?:([^;,:=]+)@|)(.*?)(?::(\d+)|)$/)[1,3]

  user_opt, port_opt = @options.delete(:user), @options.delete(:port)

  @user = @user || user_opt || master.default_user
  port ||= port_opt

  @options[:port] = port.to_i if port

  @gateway = @options.delete(:via)
  @failed = false
end

Public Instance methods

@@ -208,9 +207,9 @@

-

Returns the value of the server property with the given key. - Server properties are described via the - :properties key in the options hash when defining the Returns the value of the server property with the given key. Server properties are described via the + :properties key in the options hash when defining the Server.

@@ -228,7 +227,7 @@

-

Sets the given key/value pair in the :properties key in the +

Sets the given key/value pair in the :properties key in the options hash. If the options hash has no :properties key, it will be created.

@@ -247,14 +246,15 @@

-

Returns true if the session has been opened, and the session - is currently busy (as defined by Net::SSH::Connection::Session#busy?).

+

Returns true if the session has been opened, and the session is + currently busy (as defined by Net::SSH::Connection::Session#busy?). Also + returns false if the server has failed to connect.

[show source] -

# File lib/net/ssh/multi/server.rb, line 143
def busy?(include_invisible=false)
  session && session.busy?(include_invisible)
end

+

# File lib/net/ssh/multi/server.rb, line 144
def busy?(include_invisible=false)
  !failed? && session && session.busy?(include_invisible)
end

@@ -272,7 +272,7 @@ [show source] -

# File lib/net/ssh/multi/server.rb, line 149
def close
  session.close if session
ensure
  master.server_closed(self) if session
  @session = nil
end

+

# File lib/net/ssh/multi/server.rb, line 150
def close
  session.close if session
ensure
  master.server_closed(self) if session
  @session = nil
end

@@ -284,8 +284,8 @@

Indicates (by default) that this server has just failed a connection - attempt. If flag is false, this can be used to reset the - failed flag so that a retry may be attempted.

+ attempt. If flag is false, this can be used to reset the failed + flag so that a retry may be attempted.

@@ -302,8 +302,7 @@

Returns true if this server has ever failed a connection - attempt.

Returns true if this server has ever failed a connection attempt.

@@ -320,10 +319,10 @@

Generates a Fixnum hash value for this object. This function - has the property that +a.eql?(b)+ implies +a.hash == b.hash+. The hash - value is used by class Hash. Any hash value that exceeds the - capacity of a Fixnum will be truncated before being used.

Generates a Fixnum hash value for this object. This function has + the property that +a.eql?(b)+ implies +a.hash == b.hash+. The hash value is + used by class Hash. Any hash value that exceeds the capacity of a + Fixnum will be truncated before being used.

@@ -375,11 +374,11 @@

Returns the Net::SSH session object for this - server. If require_session is false and the session has not - previously been created, this will return nil. If - require_session is true, the session will be instantiated if - it has not already been instantiated, via the gateway if one - is given, or directly (via Net::SSH::start) otherwise.

+ server. If require_session is false and the session has not + previously been created, this will return nil. If + require_session is true, the session will be instantiated if it + has not already been instantiated, via the gateway if one is + given, or directly (via Net::SSH::start) otherwise.

if server.session.nil?
  puts "connecting..."
  server.session(true)
end

diff --git a/classes/Net/SSH/Multi/ServerList.html b/classes/Net/SSH/Multi/ServerList.html index d1952f9..70850e5 100644 --- a/classes/Net/SSH/Multi/ServerList.html +++ b/classes/Net/SSH/Multi/ServerList.html @@ -136,7 +136,7 @@

Adds an array (or otherwise Enumerable list) of servers to this list, by calling add for each argument. - Returns self.

+ Returns self.

diff --git a/classes/Net/SSH/Multi/Session.html b/classes/Net/SSH/Multi/Session.html index 7c24957..fe9cb21 100644 --- a/classes/Net/SSH/Multi/Session.html +++ b/classes/Net/SSH/Multi/Session.html @@ -54,13 +54,13 @@ href="../../SSH.html">SSH channels and executing commands, allowing for these operations to be done in parallel across multiple connections.

-

Net::SSH::Multi.start do |session|
  # access servers via a gateway
  session.via 'gateway', 'gateway-user'

  # define the servers we want to use
  session.use 'user1@host1'
  session.use 'user2@host2'

  # define servers in groups for more granular access
  session.group :app do
    session.use 'user@app1'
    session.use 'user@app2'
  end

  # execute commands on all servers
  session.exec "uptime"

  # execute commands on a subset of servers
  session.with(:app).exec "hostname"

  # run the aggregated event loop
  session.loop
end

+

Net::SSH::Multi.start do |session|
  # access servers via a gateway
  session.via 'gateway', 'gateway-user'
  # define the servers we want to use
  session.use 'user1@host1'
  session.use 'user2@host2'

  # define servers in groups for more granular access
  session.group :app do
    session.use 'user@app1'
    session.use 'user@app2'
  end

  # execute commands on all servers
  session.exec "uptime"

  # execute commands on a subset of servers
  session.with(:app).exec "hostname"

  # run the aggregated event loop
  session.loop
end

Note that connections are established lazily, as soon as they are needed. You can force the connections to be opened immediately, though, using the connect! method.

-

Concurrent Connection Limiting

+

Concurrent Connection Limiting

Sometimes you may be dealing with a large number of servers, and if you try to have connections open to all of them simultaneously you'll run into open @@ -71,13 +71,13 @@ then ensure that no more than this number of connections are ever open simultaneously.

-

Net::SSH::Multi.start(:concurrent_connections => 5) do |session|
  # ...
end

+

Net::SSH::Multi.start(:concurrent_connections => 5) do |session|
  # ...
end

Opening channels and executing commands will still work exactly as before, but Net::SSH::Multi will transparently close finished connections and open pending ones.

-

Controlling Connection Errors

+

Controlling Connection Errors

By default, Net::SSH::Multi will raise an exception if a connection error occurs when connecting to a server. This @@ -91,7 +91,7 @@ session to :ignore (or to :warn, if you want a warning message when a connection attempt fails):

-

Net::SSH::Multi.start(:on_error => :ignore) do |session|
  # ...
end

+

Net::SSH::Multi.start(:on_error => :ignore) do |session|
  # ...
end

The default is :fail, which causes the exception to bubble up. Additionally, you can specify a Proc object as the value for -

handler = Proc.new do |server|
  server[:connection_attempts] ||= 0
  if server[:connection_attempts] < 3
    server[:connection_attempts] += 1
    throw :go, :retry
  else
    throw :go, :raise
  end
end

Net::SSH::Multi.start(:on_error => handler) do |session|
  # ...
end

handler = Proc.new do |server|
  server[:connection_attempts] ||= 0
  if server[:connection_attempts] < 3
    server[:connection_attempts] += 1
    throw :go, :retry
  else
    throw :go, :raise
  end
end
Net::SSH::Multi.start(:on_error => handler) do |session|
  # ...
end

Any other thrown value (or no thrown value at all) will result in the failure being ignored.

Lazily Evaluated Server Definitions

+

Lazily Evaluated Server Definitions

Sometimes you might be dealing with an environment where you don't know the names or addresses of the servers until runtime. You can certainly @@ -120,7 +120,7 @@

You can do this by passing a block to use:

-

session.use do |opt|
  lookup_ip_address_of_remote_host
end

+

session.use do |opt|
  lookup_ip_address_of_remote_host
end

See use for more information about this usage.

@@ -195,7 +195,7 @@

The default Net::SSH::Gateway instance to use to connect to the servers. If - nil, no default gateway will be used.

+ nil, no default gateway will be used.

@@ -264,7 +264,7 @@

You can set the concurrent_connections - property in the options. Setting it to nil (the default) will + property in the options. Setting it to nil (the default) will cause Net::SSH::Multi to ignore any concurrent connection limit and allow all defined sessions to be open simultaneously. Setting it to an integer will cause -

Net::SSH::Multi.start(:concurrent_connections => 10) do |session|
  session.use ...
end

Net::SSH::Multi.start(:concurrent_connections => 10) do |session|
  session.use ...
end

@@ -321,7 +321,7 @@ href="Session.html#attribute-i-server_list">server_list array (typically by calling use):

-

server1 = session.use('host1', 'user1')
server2 = session.use('host2', 'user2')
session.group :app => server1, :web => server2
session.group :staging => [server1, server2]
session.group %w(xen linux) => server2
session.group %w(rackspace backup) => [server1, server2]

+

server1 = session.use('host1', 'user1')
server2 = session.use('host2', 'user2')
session.group :app => server1, :web => server2
session.group :staging => [server1, server2]
session.group %w(xen linux) => server2
session.group %w(rackspace backup) => [server1, server2]

Secondly, instead of a mapping of groups to servers, you can just provide a list of group names, and then a block. Inside the block, any calls to

Run the aggregated event loop for all open server sessions, until the given - block returns false. If no block is given, the loop will run - for as long as busy? - returns true (in other words, for as long as there are any - (non-invisible) channels open).

+ block returns false. If no block is given, the loop will run for + as long as busy? returns + true (in other words, for as long as there are any (non-invisible) + channels open).

@@ -394,12 +394,12 @@

Run a single iteration of the aggregated event loop for all open server - sessions. The wait parameter indicates how long to wait for an - event to appear on any of the different sessions; nil (the + sessions. The wait parameter indicates how long to wait for an + event to appear on any of the different sessions; nil (the default) means "wait forever". If the block is given, then it will be used to determine whether process - returns true (the block did not return false), or - false (the block returned false).

+ returns true (the block did not return false), or + false (the block returned false).

@@ -458,11 +458,11 @@ servers to those whose properties do not match). Properties are described when the server is defined (via the :properties key):

session.group :db do
  session.use 'dbmain', 'user', :properties => { :primary => true }
  session.use 'dbslave', 'user2'
  session.use 'dbslve2', 'user2'
end

# return ONLY on the servers in the :db group which have the :primary
# property set to true.
primary = session.servers_for(:db => { :only => { :primary => true } })

session.group :db do
  session.use 'dbmain', 'user', :properties => { :primary => true }
  session.use 'dbslave', 'user2'
  session.use 'dbslve2', 'user2'
end
# return ONLY on the servers in the :db group which have the :primary
# property set to true.
primary = session.servers_for(:db => { :only => { :primary => true } })

You can, naturally, combine these methods:

# all servers in :app and :web, and all servers in :db with the
# :primary property set to true
servers = session.servers_for(:app, :web, :db => { :only => { :primary => true } })

# all servers in :app and :web, and all servers in :db with the
# :primary property set to true
servers = session.servers_for(:app, :web, :db => { :only => { :primary => true } })

@@ -480,17 +480,17 @@

Defines a new server definition, to be managed by this session. The server - is at the given host, and will be connected to as the given - user. The other options are passed as-is to the host, and will be connected to as the given + user. The other options are passed as-is to the Net::SSH session constructor.

If a default gateway has been specified previously (with via) it will be passed to the new server definition. You can override this by passing a different - Net::SSH::Gateway instance (or nil) with the :via key in the - options.

+ Net::SSH::Gateway instance (or nil) with the :via key in the + options.

-

session.use 'host'
session.use 'user@host2', :via => nil
session.use 'host3', :user => "user3", :via => Net::SSH::Gateway.new('gateway.host', 'user')

+

session.use 'host'
session.use 'user@host2', :via => nil
session.use 'host3', :user => "user3", :via => Net::SSH::Gateway.new('gateway.host', 'user')

If only a single host is given, the new server instance is returned. You can give multiple hosts at a time, though, in which case an array of server @@ -502,9 +502,9 @@ href="DynamicServer.html">Net::SSH::Multi::DynamicServer definition, to be evaluated lazily the first time the server is needed. The block will recive any options hash given to use, and should return - nil (if no servers are to be added), a String or an array of - Strings (to be interpreted as a connection specification), or a use, and should return nil + (if no servers are to be added), a String or an array of Strings (to be + interpreted as a connection specification), or a Server or an array of Servers.

@@ -553,7 +553,7 @@ href="Session.html#method-i-servers_for">servers_for for a discussion of how these criteria are interpreted.

-

session.with(:app).exec('hostname')

session.with(:app, :db => { :primary => true }) do |s|
  s.exec 'date'
  s.exec 'uptime'
end

+

session.with(:app).exec('hostname')
session.with(:app, :db => { :primary => true }) do |s|
  s.exec 'date'
  s.exec 'uptime'
end

diff --git a/classes/Net/SSH/Multi/SessionActions.html b/classes/Net/SSH/Multi/SessionActions.html index 78bd4a6..190b376 100644 --- a/classes/Net/SSH/Multi/SessionActions.html +++ b/classes/Net/SSH/Multi/SessionActions.html @@ -45,7 +45,7 @@

This module represents the actions that are available on session collections. Any class that includes this module needs only provide a - servers method that returns a list of servers method that returns a list of Net::SSH::Multi::Server instances, and the rest just works. See Net::SSH::Multi::Session and Net::SSH::Multi::Subsession for consumers of @@ -77,11 +77,11 @@

-

Returns true if any server in the current container has an - open SSH session that is currently processing - any channels. If include_invisible is false (the - default) then invisible channels (such as those created by port forwarding) - will not be counted; otherwise, they will be.

+

Returns true if any server in the current container has an open SSH session that is currently processing any + channels. If include_invisible is false (the default) + then invisible channels (such as those created by port forwarding) will not + be counted; otherwise, they will be.

@@ -127,22 +127,22 @@

If a block is given, it will be invoked whenever data is received across the channel, with three arguments: the channel object, a symbol identifying - which output stream the data was received on (:stdout or - :stderr) and a string containing the data that was received:

+ which output stream the data was received on (:stdout or + :stderr) and a string containing the data that was received:

session.exec("command") do |ch, stream, data|
  puts "[#{ch[:host]} : #{stream}] #{data}"
end

session.exec("command") do |ch, stream, data|
  puts "[#{ch[:host]} : #{stream}] #{data}"
end

If no block is given, all output will be written to +$stdout+ or +$stderr+, as appropriate.

Note that exec will also - capture the exit status of the process in the :exit_status + capture the exit status of the process in the :exit_status property of each channel. Since exec returns all of the channels in a Net::SSH::Multi::Channel object, you can check for the exit status like this:

-

channel = session.exec("command") { ... }
channel.wait

if channel.any? { |c| c[:exit_status] != 0 }
  puts "executing failed on at least one host!"
end

+

channel = session.exec("command") { ... }
channel.wait
if channel.any? { |c| c[:exit_status] != 0 }
  puts "executing failed on at least one host!"
end

@@ -159,9 +159,9 @@

Returns the session that is the "master". This defaults to - self, but classes that include this module may wish to change - this if they are subsessions that depend on a master session.

Returns the session that is the "master". This defaults to self, + but classes that include this module may wish to change this if they are + subsessions that depend on a master session.

@@ -180,8 +180,8 @@

Asks all sessions for all contained servers (see sessions) to open a new - channel. When each server responds, the on_confirm block will - be invoked with a single argument, the channel object for that server. This + channel. When each server responds, the on_confirm block will be + invoked with a single argument, the channel object for that server. This means that the block will be invoked one time for each session.

All new channels will be collected and returned, aggregated into a new Having access to these things lets you more easily report which host (e.g.) data was received from:

session.open_channel do |channel|
  channel.exec "command" do |ch, success|
    ch.on_data do |ch, data|
      puts "got data #{data} from #{ch[:host]}"
    end
  end
end

session.open_channel do |channel|
  channel.exec "command" do |ch, success|
    ch.on_data do |ch, data|
      puts "got data #{data} from #{ch[:host]}"
    end
  end
end

diff --git a/classes/Net/SSH/Multi/Subsession.html b/classes/Net/SSH/Multi/Subsession.html index 7c18b21..6eda395 100644 --- a/classes/Net/SSH/Multi/Subsession.html +++ b/classes/Net/SSH/Multi/Subsession.html @@ -108,8 +108,8 @@

Create a new subsession of the given master session, that - operates on the given server_list.

Create a new subsession of the given master session, that operates + on the given server_list.

diff --git a/classes/Net/SSH/Multi/Version.html b/classes/Net/SSH/Multi/Version.html index fca9924..3b583bf 100644 --- a/classes/Net/SSH/Multi/Version.html +++ b/classes/Net/SSH/Multi/Version.html @@ -95,7 +95,7 @@ TINY = - 0 + 1 diff --git a/created.rid b/created.rid index 1e55898..4c13f52 100644 --- a/created.rid +++ b/created.rid @@ -1,15 +1,15 @@ -Wed, 06 Feb 2013 12:30:08 -0800 -README.rdoc Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/channel.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/channel_proxy.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/dynamic_server.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/pending_connection.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/server.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/server_list.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/session.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/session_actions.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/subsession.rb Wed, 06 Feb 2013 11:04:09 -0800 -lib/net/ssh/multi/version.rb Wed, 06 Feb 2013 12:29:49 -0800 -lib/net/ssh/multi.rb Wed, 06 Feb 2013 11:04:09 -0800 -LICENSE.txt Wed, 06 Feb 2013 11:04:09 -0800 -CHANGES.txt Wed, 06 Feb 2013 12:29:49 -0800 +Sat, 11 Apr 2015 13:14:34 -0700 +README.rdoc Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/channel.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/channel_proxy.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/dynamic_server.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/pending_connection.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/server.rb Sat, 11 Apr 2015 12:58:32 -0700 +lib/net/ssh/multi/server_list.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/session.rb Sat, 11 Apr 2015 12:58:32 -0700 +lib/net/ssh/multi/session_actions.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/subsession.rb Sat, 11 Apr 2015 12:56:28 -0700 +lib/net/ssh/multi/version.rb Sat, 11 Apr 2015 13:14:04 -0700 +lib/net/ssh/multi.rb Sat, 11 Apr 2015 12:56:28 -0700 +LICENSE.txt Sat, 11 Apr 2015 12:56:28 -0700 +CHANGES.txt Sat, 11 Apr 2015 13:14:04 -0700 diff --git a/files/CHANGES_txt.html b/files/CHANGES_txt.html index 516d0fc..0c301bf 100644 --- a/files/CHANGES_txt.html +++ b/files/CHANGES_txt.html @@ -31,42 +31,49 @@

Last Update: - 2013-02-06 12:29:49 -0800 + 2015-04-11 13:14:04 -0700

1.2.0 / 06 Feb 2013

1.2.1 / 11 Apr 2015

+
Fix two problems with :concurrent_connections option (#4) [sersut]
+
+
Replaced test-unit with minitest [juliandunn]
+

1.2.0 / 06 Feb 2013

Added public cert. All gem releases are now signed. See INSTALL in readme.

1.1 / 3 Apr 2011

1.1 / 3 Apr 2011

Rescue Timeout::Error so :on_error works as expected when server is unavailable. [Joel Watson]

1.0.1 / 1 Feb 2009

1.0.1 / 1 Feb 2009

Remove redundant call to block_given? in Session#group [paddor]
Add Channel#on_open_failed callback hook [Jamis Buck]

1.0.0 / 1 May 2008

1.0.0 / 1 May 2008

(no changes since the last preview release)

1.0 Preview Release 2 (0.99.1) / 19 Apr 2008

1.0 Preview Release 2 (0.99.1) / 19 Apr 2008

Don't try to select on closed IO streams [Jamis Buck]

1.0 Preview Release 1 (0.99.0) / 10 Apr 2008

1.0 Preview Release 1 (0.99.0) / 10 Apr 2008

First release of Net::SSH::Multi
diff --git a/files/README_rdoc.html b/files/README_rdoc.html index 95f2884..7a4adee 100644 --- a/files/README_rdoc.html +++ b/files/README_rdoc.html @@ -25,20 +25,20 @@
-
README.rdoc
+
README.rdoc

README.rdoc

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700
-
Net::SSH::Multi
+
Net::SSH::Multi

Docs: net-ssh.github.com/net-ssh-multi
@@ -54,7 +54,7 @@
As of v1.1.1, all gem releases are signed. See INSTALL.
-
DESCRIPTION:
+
DESCRIPTION:

Net::SSH::Multi is a library for controlling multiple Net::SSH @@ -68,7 +68,7 @@ parallel, and allows commands to be executed on subsets of servers (defined by groups).
-
FEATURES:
+
FEATURES:

Easily manage multiple connections

@@ -82,17 +82,17 @@ tunneled, or even specify a different gateway machine for each server

-
SYNOPSIS:
+
SYNOPSIS:

In a nutshell:
-
require 'net/ssh/multi' Net::SSH::Multi.start do |session| # access servers via a gateway session.via 'gateway', 'gateway-user' # define the servers we want to use session.use 'user1@host1' session.use 'user2@host2' # define servers in groups for more granular access session.group :app do session.use 'user@app1' session.use 'user@app2' end # execute commands on all servers session.exec "uptime" # execute commands on a subset of servers session.with(:app).exec "hostname" # run the aggregated event loop session.loop end
+
require 'net/ssh/multi' Net::SSH::Multi.start do |session| # access servers via a gateway session.via 'gateway', 'gateway-user' # define the servers we want to use session.use 'user1@host1' session.use 'user2@host2' # define servers in groups for more granular access session.group :app do session.use 'user@app1' session.use 'user@app2' end # execute commands on all servers session.exec "uptime" # execute commands on a subset of servers session.with(:app).exec "hostname" # run the aggregated event loop session.loop end

See Net::SSH::Multi::Session for more documentation.
-
REQUIREMENTS:
+
REQUIREMENTS:

net-ssh (version 2)

@@ -106,7 +106,7 @@
Mocha (for the tests)

-
INSTALL:
+
INSTALL:

gem install net-ssh-multi

@@ -127,7 +127,7 @@ data signature". If you're still having trouble let me know and I'll give you a hand.
-
LICENSE:
+
LICENSE:

(The MIT License)
diff --git a/files/lib/net/ssh/multi/channel_proxy_rb.html b/files/lib/net/ssh/multi/channel_proxy_rb.html index a7e5e2b..46fc73d 100644 --- a/files/lib/net/ssh/multi/channel_proxy_rb.html +++ b/files/lib/net/ssh/multi/channel_proxy_rb.html @@ -31,7 +31,7 @@
Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700
diff --git a/files/lib/net/ssh/multi/channel_rb.html b/files/lib/net/ssh/multi/channel_rb.html index 54e2b50..fba6043 100644 --- a/files/lib/net/ssh/multi/channel_rb.html +++ b/files/lib/net/ssh/multi/channel_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700
diff --git a/files/lib/net/ssh/multi/dynamic_server_rb.html b/files/lib/net/ssh/multi/dynamic_server_rb.html index 06dda62..9acd3df 100644 --- a/files/lib/net/ssh/multi/dynamic_server_rb.html +++ b/files/lib/net/ssh/multi/dynamic_server_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700
diff --git a/files/lib/net/ssh/multi/pending_connection_rb.html b/files/lib/net/ssh/multi/pending_connection_rb.html index 2f60e49..00eb20f 100644 --- a/files/lib/net/ssh/multi/pending_connection_rb.html +++ b/files/lib/net/ssh/multi/pending_connection_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700

diff --git a/files/lib/net/ssh/multi/server_list_rb.html b/files/lib/net/ssh/multi/server_list_rb.html index 73964f0..33d3846 100644 --- a/files/lib/net/ssh/multi/server_list_rb.html +++ b/files/lib/net/ssh/multi/server_list_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700

diff --git a/files/lib/net/ssh/multi/server_rb.html b/files/lib/net/ssh/multi/server_rb.html index 625acfd..5b21841 100644 --- a/files/lib/net/ssh/multi/server_rb.html +++ b/files/lib/net/ssh/multi/server_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:58:32 -0700

diff --git a/files/lib/net/ssh/multi/session_actions_rb.html b/files/lib/net/ssh/multi/session_actions_rb.html index d5805b0..136068a 100644 --- a/files/lib/net/ssh/multi/session_actions_rb.html +++ b/files/lib/net/ssh/multi/session_actions_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700

diff --git a/files/lib/net/ssh/multi/session_rb.html b/files/lib/net/ssh/multi/session_rb.html index cc118e7..c914684 100644 --- a/files/lib/net/ssh/multi/session_rb.html +++ b/files/lib/net/ssh/multi/session_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:58:32 -0700

diff --git a/files/lib/net/ssh/multi/subsession_rb.html b/files/lib/net/ssh/multi/subsession_rb.html index 52119c7..e00d104 100644 --- a/files/lib/net/ssh/multi/subsession_rb.html +++ b/files/lib/net/ssh/multi/subsession_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700

diff --git a/files/lib/net/ssh/multi/version_rb.html b/files/lib/net/ssh/multi/version_rb.html index ccda021..969f81b 100644 --- a/files/lib/net/ssh/multi/version_rb.html +++ b/files/lib/net/ssh/multi/version_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 12:29:49 -0800 + 2015-04-11 13:14:04 -0700

diff --git a/files/lib/net/ssh/multi_rb.html b/files/lib/net/ssh/multi_rb.html index f7421e1..493eab2 100644 --- a/files/lib/net/ssh/multi_rb.html +++ b/files/lib/net/ssh/multi_rb.html @@ -31,7 +31,7 @@

Last Update: - 2013-02-06 11:04:09 -0800 + 2015-04-11 12:56:28 -0700

diff --git a/fr_method_index.html b/fr_method_index.html index 09b5102..8e0925d 100644 --- a/fr_method_index.html +++ b/fr_method_index.html @@ -4502,27 +4502,27 @@

#callback (Net::SSH::Multi::DynamicServer)
#channels (Net::SSH::Multi::Channel)
#concurrent_connections (Net::SSH::Multi::Session)
#connection (Net::SSH::Multi::Channel)
#default_gateway (Net::SSH::Multi::Session)
#default_user (Net::SSH::Multi::Session)
#gateway (Net::SSH::Multi::Server)
#groups (Net::SSH::Multi::Session)
#host (Net::SSH::Multi::Server)
#master (Net::SSH::Multi::DynamicServer)
#master (Net::SSH::Multi::Subsession)
#master (Net::SSH::Multi::Server)
#on_confirm (Net::SSH::Multi::ChannelProxy)
#on_error (Net::SSH::Multi::Session)
#options (Net::SSH::Multi::Server)
#options (Net::SSH::Multi::DynamicServer)
#properties (Net::SSH::Multi::Channel)
#server (Net::SSH::Multi::PendingConnection)
#server_list (Net::SSH::Multi::Session)
#servers (Net::SSH::Multi::Subsession)
#user (Net::SSH::Multi::Server)
#callback (Net::SSH::Multi::DynamicServer)
#channels (Net::SSH::Multi::Channel)
#concurrent_connections (Net::SSH::Multi::Session)
#connection (Net::SSH::Multi::Channel)
#default_gateway (Net::SSH::Multi::Session)
#default_user (Net::SSH::Multi::Session)
#gateway (Net::SSH::Multi::Server)
#groups (Net::SSH::Multi::Session)
#host (Net::SSH::Multi::Server)
#master (Net::SSH::Multi::DynamicServer)
#master (Net::SSH::Multi::Subsession)
#master (Net::SSH::Multi::Server)
#on_confirm (Net::SSH::Multi::ChannelProxy)
#on_error (Net::SSH::Multi::Session)
#options (Net::SSH::Multi::Server)
#options (Net::SSH::Multi::DynamicServer)
#properties (Net::SSH::Multi::Channel)
#server (Net::SSH::Multi::PendingConnection)
#server_list (Net::SSH::Multi::Session)
#servers (Net::SSH::Multi::Subsession)
#user (Net::SSH::Multi::Server)
::new (Net::SSH::Multi::ChannelProxy)
::new (Net::SSH::Multi::Channel)
::new (Net::SSH::Multi::Subsession)

net-ssh-multi 1.2.0

net-ssh-multi 1.2.1