Method: Capistrano::Configuration::Actions::Invocation#run

Defined in:
lib/capistrano/configuration/actions/invocation.rb

#run(cmd, options = {}, &block) ⇒ Object

Execute the given command on all servers that are the target of the current task. If a block is given, it is invoked for all output generated by the command, and should accept three parameters: the SSH channel (which may be used to send data back to the remote process), the stream identifier (:err for stderr, and :out for stdout), and the data that was received.

The options hash may include any of the following keys:

  • :hosts - this is either a string (for a single target host) or an array of strings, indicating which hosts the command should run on. By default, the hosts are determined from the task definition.

  • :roles - this is either a string or symbol (for a single target role) or an array of strings or symbols, indicating which roles the command should run on. If :hosts is specified, :roles will be ignored.

  • :only - specifies a condition limiting which hosts will be selected to run the command. This should refer to values set in the role definition. For example, if a role is defined with :primary => true, then you could select only hosts with :primary true by setting :only => { :primary => true }.

  • :except - specifies a condition limiting which hosts will be selected to run the command. This is the inverse of :only (hosts that do not match the condition will be selected).

  • :on_no_matching_servers - if :continue, will continue to execute tasks if no matching servers are found for the host criteria. The default is to raise a NoMatchingServersError exception.

  • :once - if true, only the first matching server will be selected. The default is false (all matching servers will be selected).

  • :max_hosts - specifies the maximum number of hosts that should be selected at a time. If this value is less than the number of hosts that are selected to run, then the hosts will be run in groups of max_hosts. The default is nil, which indicates that there is no maximum host limit. Please note this does not limit the number of SSH channels that can be open, only the number of hosts upon which this will be called.

  • :shell - says which shell should be used to invoke commands. This defaults to “sh”. Setting this to false causes Capistrano to invoke the commands directly, without wrapping them in a shell invocation.

  • :data - if not nil (the default), this should be a string that will be passed to the command’s stdin stream.

  • :pty - if true, a pseudo-tty will be allocated for each command. The default is false. Note that there are benefits and drawbacks both ways. Empirically, it appears that if a pty is allocated, the SSH server daemon will not read user shell start-up scripts (e.g. bashrc, etc.). However, if a pty is not allocated, some commands will refuse to run in interactive mode and will not prompt for (e.g.) passwords.

  • :env - a hash of environment variable mappings that should be made available to the command. The keys should be environment variable names, and the values should be their corresponding values. The default is empty, but may be modified by changing the default_environment Capistrano variable.

  • :eof - if true, the standard input stream will be closed after sending any data specified in the :data option. If false, the input stream is left open. The default is to close the input stream only if no block is passed.

Note that if you set these keys in the default_run_options Capistrano variable, they will apply for all invocations of #run, #invoke_command, and #parallel.



149
150
151
152
153
154
155
156
 
# File 'lib/capistrano/configuration/actions/invocation.rb', line 149

def run(cmd, options={}, &block)
  if options[:eof].nil? && !cmd.include?(sudo)
    options = options.merge(:eof => !block_given?)
  end
  block ||= self.class.default_io_proc
  tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
  run_tree(tree, options)
end