Module: Puppet::Util

Extended by:
POSIX, SymbolicFileMode
Included in:
Puppet, Application, Application, Configurer, Confine, Indirector::Queue, Interface, Network::AuthStore::Declaration, Node::Exec, Parameter, Parameter, Parser::Compiler, Parser::Functions, Parser::Methods, Parser::Resource, Parser::Resource::Param, Parser::TemplateWrapper, Provider, Provider, Rails::Host, Resource::Catalog::Compiler, Transaction, Type, Type, ClassGen, FileParsing, FileParsing::FileRecord, InstanceLoader, Instrumentation::Listener, Log, Log, ProviderFeatures::ProviderFeature, Reference, Storage
Defined in:
lib/puppet/util.rb,
lib/puppet/util/platform.rb,
lib/puppet/util/run_mode.rb,
lib/puppet/util/command_line.rb,
lib/puppet/util/execution_stub.rb,
lib/puppet/util/constant_inflector.rb,
lib/puppet/util/symbolic_file_mode.rb,
lib/puppet/util/command_line/trollop.rb,
lib/puppet/util/command_line/puppet_option_parser.rb

Defined Under Namespace

Modules: Backups, CacheAccumulator, Cacher, Checksums, ClassGen, CollectionMerger, Colors, ConstantInflector, Diff, Docs, Errors, Execution, FileParsing, HttpProxy, IniConfig, InlineDocs, InstanceLoader, Ldap, Libuser, Limits, Logging, MethodHelper, MonkeyPatches, NagiosMaker, POSIX, Package, Platform, Profiler, ProviderFeatures, Pson, Queue, RDoc, ReferenceSerializer, RetryAction, RubyGems, SELinux, SSL, SUIDManager, SymbolicFileMode, Tagging, Terminal, Warnings, Watcher, Windows, Yaml Classes: Autoload, CommandLine, ExecutionStub, Feature, FileType, FileWatcher, Instrumentation, JsonLockfile, Lockfile, Log, Metric, NetworkDevice, Pidlock, Reference, ResourceTemplate, RunMode, Storage, TagSet, UnixRunMode, WatchedFile, WindowsRunMode

Constant Summary collapse

AbsolutePathWindows = 
%r!^(?:(?:[A-Z]:#{slash})|(?:#{slash}#{slash}#{label}#{slash}#{label})|(?:#{slash}#{slash}\?#{slash}#{label}))!io
AbsolutePathPosix = 
%r!^/!
DEFAULT_POSIX_MODE =

Replace a file, securely. This takes a block, and passes it the file handle of a file open for writing. Write the replacement content inside the block and it will safely replace the target file.

This method will make no changes to the target file until the content is successfully written and the block returns without raising an error.

As far as possible the state of the existing file, such as mode, is preserved. This works hard to avoid loss of any metadata, but will result in an inode change for the file.

Arguments: ‘filename`, `default_mode`

The filename is the file we are going to replace.

The default_mode is the mode to use when the target file doesn’t already exist; if the file is present we copy the existing mode/owner/group values across. The default_mode can be expressed as an octal integer, a numeric string (ie ‘0664’) or a symbolic file mode.

0644
DEFAULT_WINDOWS_MODE = 
nil

Constants included from POSIX

POSIX::LOCALE_ENV_VARS, POSIX::USER_ENV_VARS

Constants included from SymbolicFileMode

SymbolicFileMode::SetGIDBit, SymbolicFileMode::SetUIDBit, SymbolicFileMode::StickyBit, SymbolicFileMode::SymbolicMode, SymbolicFileMode::SymbolicSpecialToBit

Class Method Summary collapse

Methods included from POSIX

get_posix_field, gid, idfield, methodbyid, methodbyname, search_posix_field, uid

Methods included from SymbolicFileMode

normalize_symbolic_mode, symbolic_mode_to_int, valid_symbolic_mode?

Class Method Details

.absolute_path?(path, platform = nil) ⇒ Boolean

Returns:

  • (Boolean) 


224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/puppet/util.rb', line 224

def absolute_path?(path, platform=nil)
  # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
  # library uses that to test what platform it's on.  Normally in Puppet we
  # would use Puppet.features.microsoft_windows?, but this method needs to
  # be called during the initialization of features so it can't depend on
  # that.
  platform ||= Puppet::Util::Platform.windows? ? :windows : :posix
  regex = case platform
          when :windows
            AbsolutePathWindows
          when :posix
            AbsolutePathPosix
          else
            raise Puppet::DevError, "unknown platform #{platform} in absolute_path"
          end

  !! (path =~ regex)
end

.activerecord_version ⇒ Object 



26
27
28
29
30
31
32
 
# File 'lib/puppet/util.rb', line 26

def self.activerecord_version
  if (defined?(::ActiveRecord) and defined?(::ActiveRecord::VERSION) and defined?(::ActiveRecord::VERSION::MAJOR) and defined?(::ActiveRecord::VERSION::MINOR))
    ([::ActiveRecord::VERSION::MAJOR, ::ActiveRecord::VERSION::MINOR].join('.').to_f)
  else
    0
  end
end

.benchmark(*args) ⇒ Object

Raises:



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
 
# File 'lib/puppet/util.rb', line 137

def benchmark(*args)
  msg = args.pop
  level = args.pop
  object = nil

  if args.empty?
    if respond_to?(level)
      object = self
    else
      object = Puppet
    end
  else
    object = args.pop
  end

  raise Puppet::DevError, "Failed to provide level to :benchmark" unless level

  unless level == :none or object.respond_to? level
    raise Puppet::DevError, "Benchmarked object does not respond to #{level}"
  end

  # Only benchmark if our log level is high enough
  if level != :none and Puppet::Util::Log.sendlevel?(level)
    seconds = Benchmark.realtime {
      yield
    }
    object.send(level, msg + (" in %0.2f seconds" % seconds))
    return seconds
  else
    yield
  end
end

.binread(file) ⇒ Object

Because IO#binread is only available in 1.9



336
337
338
339
 
# File 'lib/puppet/util.rb', line 336

def binread(file)
  Puppet.deprecation_warning("Puppet::Util.binread is deprecated. Read the file without this method as it will be removed in a future version.")
  File.open(file, 'rb') { |f| f.read }
end

.chuser ⇒ Object

Change the process to a different user



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/puppet/util.rb', line 65

def self.chuser
  if group = Puppet[:group]
    begin
      Puppet::Util::SUIDManager.change_group(group, true)
    rescue => detail
      Puppet.warning "could not change to group #{group.inspect}: #{detail}"
      $stderr.puts "could not change to group #{group.inspect}"

      # Don't exit on failed group changes, since it's
      # not fatal
      #exit(74)
    end
  end

  if user = Puppet[:user]
    begin
      Puppet::Util::SUIDManager.change_user(user, true)
    rescue => detail
      $stderr.puts "Could not change to user #{user}: #{detail}"
      exit(74)
    end
  end
end

.classproxy(klass, objmethod, *methods) ⇒ Object

Proxy a bunch of methods to another object.



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/puppet/util.rb', line 115

def self.classproxy(klass, objmethod, *methods)
  classobj = class << klass; self; end
  methods.each do |method|
    classobj.send(:define_method, method) do |*args|
      obj = self.send(objmethod)

      obj.send(method, *args)
    end
  end
end

.deterministic_rand(seed, max) ⇒ Object 



506
507
508
509
510
511
512
513
514
515
 
# File 'lib/puppet/util.rb', line 506

def deterministic_rand(seed,max)
  if defined?(Random) == 'constant' && Random.class == Class
    Random.new(seed).rand(max).to_s
  else
    srand(seed)
    result = rand(max).to_s
    srand()
    result
  end
end

.execfail(command, exception) ⇒ Object 



529
530
531
532
 
# File 'lib/puppet/util.rb', line 529

def execfail(command, exception)
  Puppet.deprecation_warning("Puppet::Util.execfail is deprecated; please use Puppet::Util::Execution.execfail")
  Puppet::Util::Execution.execfail(command, exception)
end

.execpipe(command, failonfail = true, &block) ⇒ Object

Deprecated methods relating to process execution; these have been moved to Puppet::Util::Execution



523
524
525
526
 
# File 'lib/puppet/util.rb', line 523

def execpipe(command, failonfail = true, &block)
  Puppet.deprecation_warning("Puppet::Util.execpipe is deprecated; please use Puppet::Util::Execution.execpipe")
  Puppet::Util::Execution.execpipe(command, failonfail, &block)
end

.execute(*args) ⇒ Object 



535
536
537
538
539
 
# File 'lib/puppet/util.rb', line 535

def execute(*args)
  Puppet.deprecation_warning("Puppet::Util.execute is deprecated; please use Puppet::Util::Execution.execute")

  Puppet::Util::Execution.execute(*args)
end

.exit_on_fail(message, code = 1) { ... } ⇒ Object

Executes a block of code, wrapped with some special exception handling. Causes the ruby interpreter to

exit if the block throws an exception.

Parameters:

  • message (String) —

    a message to log if the block fails

  • code (Integer) (defaults to: 1) —

    the exit code that the ruby interpreter should return if the block fails

Yields:



487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
 
# File 'lib/puppet/util.rb', line 487

def exit_on_fail(message, code = 1)
  yield
# First, we need to check and see if we are catching a SystemExit error.  These will be raised
#  when we daemonize/fork, and they do not necessarily indicate a failure case.
rescue SystemExit => err
  raise err

# Now we need to catch *any* other kind of exception, because we may be calling third-party
#  code (e.g. webrick), and we have no idea what they might throw.
rescue Exception => err
  ## NOTE: when debugging spec failures, these two lines can be very useful
  #puts err.inspect
  #puts Puppet::Util.pretty_backtrace(err.backtrace)
  Puppet.log_exception(err, "Could not #{message}: #{err}")
  Puppet::Util::Log.force_flushqueue()
  exit(code)
end

.logmethods(klass, useself = true) ⇒ Object

Create instance methods for each of the log levels. This allows the messages to be a little richer. Most classes will be calling this method.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/puppet/util.rb', line 92

def self.logmethods(klass, useself = true)
  Puppet::Util::Log.eachlevel { |level|
    klass.send(:define_method, level, proc { |args|
      args = args.join(" ") if args.is_a?(Array)
      if useself

        Puppet::Util::Log.create(
          :level => level,
          :source => self,
          :message => args
        )
      else

        Puppet::Util::Log.create(
          :level => level,
          :message => args
        )
      end
    })
  }
end

.memory ⇒ Object 



303
304
305
306
307
308
309
310
311
312
 
# File 'lib/puppet/util.rb', line 303

def memory
  unless defined?(@pmap)
    @pmap = which('pmap')
  end
  if @pmap
    %x{#{@pmap} #{Process.pid}| grep total}.chomp.sub(/^\s*total\s+/, '').sub(/K$/, '').to_i
  else
    0
  end
end

.path_to_uri(path) ⇒ Object

Convert a path to a file URI



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/puppet/util.rb', line 245

def path_to_uri(path)
  return unless path

  params = { :scheme => 'file' }

  if Puppet.features.microsoft_windows?
    path = path.gsub(/\\/, '/')

    if unc = /^\/\/([^\/]+)(\/.+)/.match(path)
      params[:host] = unc[1]
      path = unc[2]
    elsif path =~ /^[a-z]:\//i
      path = '/' + path
    end
  end

  params[:path] = URI.escape(path)

  begin
    URI::Generic.build(params)
  rescue => detail
    raise Puppet::Error, "Failed to convert '#{path}' to URI: #{detail}", detail.backtrace
  end
end

.pretty_backtrace(backtrace = caller(1)) ⇒ Object

utility method to get the current call stack and format it to a human-readable string (which some IDEs/editors will recognize as links to the line numbers in the trace)



344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/puppet/util.rb', line 344

def self.pretty_backtrace(backtrace = caller(1))
  backtrace.collect do |line|
    _, path, rest = /^(.*):(\d+.*)$/.match(line).to_a
    # If the path doesn't exist - like in one test, and like could happen in
    # the world - we should just tolerate it and carry on. --daniel 2012-09-05
    # Also, if we don't match, just include the whole line.
    if path
      path = Pathname(path).realpath rescue path
      "#{path}:#{rest}"
    else
      line
    end
  end.join("\n")
end

.proxy(klass, objmethod, *methods) ⇒ Object

Proxy a bunch of methods to another object.



127
128
129
130
131
132
133
134
135
 
# File 'lib/puppet/util.rb', line 127

def self.proxy(klass, objmethod, *methods)
  methods.each do |method|
    klass.send(:define_method, method) do |*args|
      obj = self.send(objmethod)

      obj.send(method, *args)
    end
  end
end

.replace_file(file, default_mode, &block) ⇒ Object

Raises:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
 
# File 'lib/puppet/util.rb', line 382

def replace_file(file, default_mode, &block)
  raise Puppet::DevError, "replace_file requires a block" unless block_given?

  if default_mode
    unless valid_symbolic_mode?(default_mode)
      raise Puppet::DevError, "replace_file default_mode: #{default_mode} is invalid"
    end

    mode = symbolic_mode_to_int(normalize_symbolic_mode(default_mode))
  else
    if Puppet.features.microsoft_windows?
      mode = DEFAULT_WINDOWS_MODE
    else
      mode = DEFAULT_POSIX_MODE
    end
  end

  begin
    file     = Puppet::FileSystem.pathname(file)
    tempfile = Puppet::FileSystem::Uniquefile.new(Puppet::FileSystem.basename_string(file), Puppet::FileSystem.dir_string(file))

    # Set properties of the temporary file before we write the content, because
    # Tempfile doesn't promise to be safe from reading by other people, just
    # that it avoids races around creating the file.
    #
    # Our Windows emulation is pretty limited, and so we have to carefully
    # and specifically handle the platform, which has all sorts of magic.
    # So, unlike Unix, we don't pre-prep security; we use the default "quite
    # secure" tempfile permissions instead.  Magic happens later.
    if !Puppet.features.microsoft_windows?
      # Grab the current file mode, and fall back to the defaults.
      effective_mode =
      if Puppet::FileSystem.exist?(file)
        stat = Puppet::FileSystem.lstat(file)
        tempfile.chown(stat.uid, stat.gid)
        stat.mode
      else
        mode
      end

      if effective_mode
        # We only care about the bottom four slots, which make the real mode,
        # and not the rest of the platform stat call fluff and stuff.
        tempfile.chmod(effective_mode & 07777)
      end
    end

    # OK, now allow the caller to write the content of the file.
    yield tempfile

    # Now, make sure the data (which includes the mode) is safe on disk.
    tempfile.flush
    begin
      tempfile.fsync
    rescue NotImplementedError
      # fsync may not be implemented by Ruby on all platforms, but
      # there is absolutely no recovery path if we detect that.  So, we just
      # ignore the return code.
      #
      # However, don't be fooled: that is accepting that we are running in
      # an unsafe fashion.  If you are porting to a new platform don't stub
      # that out.
    end

    tempfile.close

    if Puppet.features.microsoft_windows?
      # Windows ReplaceFile needs a file to exist, so touch handles this
      if !Puppet::FileSystem.exist?(file)
        Puppet::FileSystem.touch(file)
        if mode
          Puppet::Util::Windows::Security.set_mode(mode, Puppet::FileSystem.path_string(file))
        end
      end
      # Yes, the arguments are reversed compared to the rename in the rest
      # of the world.
      Puppet::Util::Windows::File.replace_file(FileSystem.path_string(file), tempfile.path)

    else
      File.rename(tempfile.path, Puppet::FileSystem.path_string(file))
    end
  ensure
    # in case an error occurred before we renamed the temp file, make sure it
    # gets deleted
    if tempfile
      tempfile.close!
    end
  end


  # Ideally, we would now fsync the directory as well, but Ruby doesn't
  # have support for that, and it doesn't matter /that/ much...

  # Return something true, and possibly useful.
  file
end

.safe_posix_fork(stdin = $stdin, stdout = $stdout, stderr = $stderr, &block) ⇒ Object 



289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/puppet/util.rb', line 289

def safe_posix_fork(stdin=$stdin, stdout=$stdout, stderr=$stderr, &block)
  child_pid = Kernel.fork do
    $stdin.reopen(stdin)
    $stdout.reopen(stdout)
    $stderr.reopen(stderr)

    3.upto(256){|fd| IO::new(fd).close rescue nil}

    block.call if block
  end
  child_pid
end

.symbolizehash(hash) ⇒ Object 



314
315
316
317
318
319
320
321
 
# File 'lib/puppet/util.rb', line 314

def symbolizehash(hash)
  newhash = {}
  hash.each do |name, val|
    name = name.intern if name.respond_to? :intern
    newhash[name] = val
  end
  newhash
end

.thinmark ⇒ Object

Just benchmark, with no logging.



325
326
327
328
329
330
331
 
# File 'lib/puppet/util.rb', line 325

def thinmark
  seconds = Benchmark.realtime {
    yield
  }

  seconds
end

.uri_to_path(uri) ⇒ Object

Get the path component of a URI



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/puppet/util.rb', line 272

def uri_to_path(uri)
  return unless uri.is_a?(URI)

  path = URI.unescape(uri.path)

  if Puppet.features.microsoft_windows? and uri.scheme == 'file'
    if uri.host
      path = "//#{uri.host}" + path # UNC
    else
      path.sub!(/^\//, '')
    end
  end

  path
end

.which(bin) ⇒ String

Resolve a path for an executable to the absolute path. This tries to behave in the same manner as the unix ‘which` command and uses the `PATH` environment variable.

Parameters:

  • bin (String) —

    the name of the executable to find.

Returns:

  • (String) —

    the absolute path to the found executable.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/puppet/util.rb', line 178

def which(bin)
  if absolute_path?(bin)
    return bin if FileTest.file? bin and FileTest.executable? bin
  else
    ENV['PATH'].split(File::PATH_SEPARATOR).each do |dir|
      begin
        dest = File.expand_path(File.join(dir, bin))
      rescue ArgumentError => e
        # if the user's PATH contains a literal tilde (~) character and HOME is not set, we may get
        # an ArgumentError here.  Let's check to see if that is the case; if not, re-raise whatever error
        # was thrown.
        if e.to_s =~ /HOME/ and (ENV['HOME'].nil? || ENV['HOME'] == "")
          # if we get here they have a tilde in their PATH.  We'll issue a single warning about this and then
          # ignore this path element and carry on with our lives.
          Puppet::Util::Warnings.warnonce("PATH contains a ~ character, and HOME is not set; ignoring PATH element '#{dir}'.")
        elsif e.to_s =~ /doesn't exist|can't find user/
          # ...otherwise, we just skip the non-existent entry, and do nothing.
          Puppet::Util::Warnings.warnonce("Couldn't expand PATH containing a ~ character; ignoring PATH element '#{dir}'.")
        else
          raise
        end
      else
        if Puppet.features.microsoft_windows? && File.extname(dest).empty?
          exts = ENV['PATHEXT']
          exts = exts ? exts.split(File::PATH_SEPARATOR) : %w[.COM .EXE .BAT .CMD]
          exts.each do |ext|
            destext = File.expand_path(dest + ext)
            return destext if FileTest.file? destext and FileTest.executable? destext
          end
        end
        return dest if FileTest.file? dest and FileTest.executable? dest
      end
    end
  end
  nil
end

.withenv(hash) ⇒ Object

Run some code with a specific environment. Resets the environment back to what it was at the end of the code.



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/puppet/util.rb', line 37

def self.withenv(hash)
  saved = ENV.to_hash
  hash.each do |name, val|
    ENV[name.to_s] = val
  end

  yield
ensure
  ENV.clear
  saved.each do |name, val|
    ENV[name] = val
  end
end

.withumask(mask) ⇒ Object

Execute a given chunk of code with a new umask.



53
54
55
56
57
58
59
60
61
 
# File 'lib/puppet/util.rb', line 53

def self.withumask(mask)
  cur = File.umask(mask)

  begin
    yield
  ensure
    File.umask(cur)
  end
end