Method: Mixlib::ShellOut#initialize

Defined in:

lib/mixlib/shellout.rb

#initialize(*command_args) ⇒ ShellOut

Arguments:

Takes a single command, or a list of command fragments. These are used as arguments to Kernel.exec. See the Kernel.exec documentation for more explanation of how arguments are evaluated. The last argument can be an options Hash.

Options:

If the last argument is a Hash, it is removed from the list of args passed to exec and used as an options hash. The following options are available:

• user: the user the commmand should run as. if an integer is given, it is used as a uid. A string is treated as a username and resolved to a uid with Etc.getpwnam

• group: the group the command should run as. works similarly to user

• cwd: the directory to chdir to before running the command

• umask: a umask to set before running the command. If given as an Integer, be sure to use two leading zeros so it’s parsed as Octal. A string will be treated as an octal integer

• returns: one or more Integer values to use as valid exit codes for the subprocess. This only has an effect if you call error! after run_command.

• environment: a Hash of environment variables to set before the command is run.

• timeout: a Numeric value for the number of seconds to wait on the child process before raising an Exception. This is calculated as the total amount of time that ShellOut waited on the child process without receiving any output (i.e., IO.select returned nil). Default is 600 seconds. Note: the stdlib Timeout library is not used.

• input: A String of data to be passed to the subcommand. This is written to the child process’ stdin stream before the process is launched. The child’s stdin stream will be a pipe, so the size of input data should not exceed the system’s default pipe capacity (4096 bytes is a safe value, though on newer Linux systems the capacity is 64k by default).

• live_stream: An IO or Logger-like object (must respond to the append operator <<) that will receive data as ShellOut reads it from the child process. Generally this is used to copy data from the child to the parent’s stdout so that users may observe the progress of long-running commands.

• login: Whether to simulate a login (set secondary groups, primary group, environment variables etc) as done by the OS in an actual login

Examples:

Invoke find(1) to search for .rb files:

find = Mixlib::ShellOut.new("find . -name '*.rb'")
find.run_command
# If all went well, the results are on +stdout+
puts find.stdout
# find(1) prints diagnostic info to STDERR:
puts "error messages" + find.stderr
# Raise an exception if it didn't exit with 0
find.error!

Run a command as the www user with no extra ENV settings from /tmp

cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
cmd.run_command # etc.

# File 'lib/mixlib/shellout.rb', line 169

def initialize(*command_args)
  @stdout, @stderr, @process_status = "", "", ""
  @live_stdout = @live_stderr = nil
  @input = nil
  @log_level = :debug
  @log_tag = nil
  @environment = {}
  @cwd = nil
  @valid_exit_codes = [0]
  @terminate_reason = nil
  @timeout = nil
  @elevated = false
  @sensitive = false

  if command_args.last.is_a?(Hash)
    parse_options(command_args.pop)
  end

  @command = command_args.size == 1 ? command_args.first : command_args
end