Module: Puppet::Util::Execution

Included in:
Provider::Exec, Diff
Defined in:
lib/puppet/util/execution.rb

Overview

This module defines methods for execution of system commands. It is intented for inclusion in classes that needs to execute system commands.

Defined Under Namespace

Classes: ProcessOutput

Constant Summary collapse

NoOptionsSpecified =

Default empty options for execute

{}

Class Method Summary collapse

Class Method Details

.execfail(command, exception) ⇒ Object

Wraps execution of execute with mapping of exception to given exception (and output as argument).

Raises:

  • (exception) —

    under same conditions as execute, but raises the given exception with the output as argument



86
87
88
89
90
91
 
# File 'lib/puppet/util/execution.rb', line 86

def self.execfail(command, exception)
  output = execute(command)
  return output
rescue Puppet::ExecutionFailure
  raise exception, output
end

.execpipe(command, failonfail = true) {|pipe| ... } ⇒ String

Executes the provided command with STDIN connected to a pipe, yielding the pipe object. This allows data to be fed to the subprocess.

The command can be a simple string, which is executed as-is, or an Array, which is treated as a set of command arguments to pass through.

In all cases this is passed directly to the shell, and STDOUT and STDERR are connected together during execution.

Parameters:

  • command (String, Array<String>) —

    the command to execute as one string, or as parts in an array. the parts of the array are joined with one separating space between each entry when converting to the command line string to execute.

  • failonfail (Boolean) (defaults to: true) —

    (true) if the execution should fail with Exception on failure or not.

Yields:

  • (pipe) —

    to a block executing a subprocess

Yield Parameters:

  • pipe (IO) —

    the opened pipe

Yield Returns:

  • (String) —

    the output to return

Returns:

  • (String) —

    a string with the output from the subprocess executed by the given block

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/puppet/util/execution.rb', line 53

def self.execpipe(command, failonfail = true)
  # Paste together an array with spaces.  We used to paste directly
  # together, no spaces, which made for odd invocations; the user had to
  # include whitespace between arguments.
  #
  # Having two spaces is really not a big drama, since this passes to the
  # shell anyhow, while no spaces makes for a small developer cost every
  # time this is invoked. --daniel 2012-02-13
  command_str = command.respond_to?(:join) ? command.join(' ') : command

  if respond_to? :debug
    debug "Executing '#{command_str}'"
  else
    Puppet.debug "Executing '#{command_str}'"
  end

  output = open("| #{command_str} 2>&1") do |pipe|
    yield pipe
  end

  if failonfail
    unless $CHILD_STATUS == 0
      raise Puppet::ExecutionFailure, output
    end
  end

  output
end

.execute(command, options = NoOptionsSpecified) ⇒ Puppet::Util::Execution::ProcessOutput Also known as: util_execute

Note:

Unfortunately, the default behavior for failonfail and combine (since 0.22.4 and 0.24.7, respectively) depend on whether options are specified or not. If specified, then failonfail and combine default to false (even when the options specified are neither failonfail nor combine). If no options are specified, then failonfail and combine default to true.

Executes the desired command, and return the status and output. def execute(command, options)

Parameters:

  • command (Array<String>, String) —

    the command to execute. If it is an Array the first element should be the executable and the rest of the elements should be the individual arguments to that executable.

  • options (Hash) (defaults to: NoOptionsSpecified) —

    a Hash of options

Options Hash (options):

  • :failonfail (Boolean) —

    if this value is set to true, then this method will raise an error if the command is not executed successfully.

  • :uid (Integer, String) — default: nil —

    the user id of the user that the process should be run as

  • :gid (Integer, String) — default: nil —

    the group id of the group that the process should be run as

  • :combine (Boolean) —

    sets whether or not to combine stdout/stderr in the output

  • :stdinfile (String) — default: nil —

    sets a file that can be used for stdin. Passing a string for stdin is not currently supported.

  • :squelch (Boolean) — default: true —

    if true, ignore stdout / stderr completely.

  • :override_locale (Boolean) — default: true —

    by default (and if this option is set to true), we will temporarily override the user/system locale to “C” (via environment variables LANG and LC_*) while we are executing the command. This ensures that the output of the command will be formatted consistently, making it predictable for parsing. Passing in a value of false for this option will allow the command to be executed using the user/system locale.

  • :custom_environment (Hash<{String => String}>) — default: {} —

    a hash of key/value pairs to set as environment variables for the duration of the command.

Returns:

Raises:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/puppet/util/execution.rb', line 127

def self.execute(command, options = NoOptionsSpecified)
  # specifying these here rather than in the method signature to allow callers to pass in a partial
  # set of overrides without affecting the default values for options that they don't pass in
  default_options = {
      :failonfail => NoOptionsSpecified.equal?(options),
      :uid => nil,
      :gid => nil,
      :combine => NoOptionsSpecified.equal?(options),
      :stdinfile => nil,
      :squelch => false,
      :override_locale => true,
      :custom_environment => {},
  }

  options = default_options.merge(options)

  if command.is_a?(Array)
    command = command.flatten.map(&:to_s)
    str = command.join(" ")
  elsif command.is_a?(String)
    str = command
  end

  if respond_to? :debug
    debug "Executing '#{str}'"
  else
    Puppet.debug "Executing '#{str}'"
  end

  null_file = Puppet.features.microsoft_windows? ? 'NUL' : '/dev/null'

  stdin = File.open(options[:stdinfile] || null_file, 'r')
  stdout = options[:squelch] ? File.open(null_file, 'w') : Tempfile.new('puppet')
  stderr = options[:combine] ? stdout : File.open(null_file, 'w')

  exec_args = [command, options, stdin, stdout, stderr]

  if execution_stub = Puppet::Util::ExecutionStub.current_value
    return execution_stub.call(*exec_args)
  elsif Puppet.features.posix?
    child_pid = execute_posix(*exec_args)
    exit_status = Process.waitpid2(child_pid).last.exitstatus
  elsif Puppet.features.microsoft_windows?
    process_info = execute_windows(*exec_args)
    begin
      exit_status = Puppet::Util::Windows::Process.wait_process(process_info.process_handle)
    ensure
      Puppet::Util::Windows::Process.CloseHandle(process_info.process_handle)
      Puppet::Util::Windows::Process.CloseHandle(process_info.thread_handle)
    end
  end

  [stdin, stdout, stderr].each {|io| io.close rescue nil}

  # read output in if required
  unless options[:squelch]
    output = wait_for_output(stdout)
    Puppet.warning "Could not get output" unless output
  end

  if options[:failonfail] and exit_status != 0
    raise Puppet::ExecutionFailure, "Execution of '#{str}' returned #{exit_status}: #{output}"
  end

  Puppet::Util::Execution::ProcessOutput.new(output || '', exit_status)
end

.ruby_path ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the path to the ruby executable (available via Config object, even if it’s not in the PATH… so this is slightly safer than just using Puppet::Util.which)

Returns:

  • (String) —

    the path to the Ruby executable



199
200
201
202
203
 
# File 'lib/puppet/util/execution.rb', line 199

def self.ruby_path()
  File.join(RbConfig::CONFIG['bindir'],
            RbConfig::CONFIG['ruby_install_name'] + RbConfig::CONFIG['EXEEXT']).
    sub(/.*\s.*/m, '"\&"')
end