openvox 7.37.1

data/lib/puppet/reference/configuration.rb

@@ -0,0 +1,97 @@
+config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc => "A reference for all settings") do
+  docs = {}
+  Puppet.settings.each do |name, object|
+    docs[name] = object
+  end
+
+  str = ""
+  docs.sort { |a, b|
+    a[0].to_s <=> b[0].to_s
+  }.each do |name, object|
+    # Make each name an anchor
+    header = name.to_s
+    str << markdown_header(header, 3)
+
+    # Print the doc string itself
+    begin
+      str << Puppet::Util::Docs.scrub(object.desc)
+    rescue => detail
+      Puppet.log_exception(detail)
+    end
+    str << "\n\n"
+
+    # Now print the data about the item.
+    val = object.default
+    if name.to_s == 'vardir'
+      val = 'Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows: C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppetlabs/opt/puppet/cache'
+    elsif name.to_s == 'publicdir'
+      val = 'Unix/Linux: /opt/puppetlabs/puppet/public -- Windows: C:\ProgramData\PuppetLabs\puppet\public -- Non-root user: ~/.puppetlabs/opt/puppet/public'
+    elsif name.to_s == 'confdir'
+      val = 'Unix/Linux: /etc/puppetlabs/puppet -- Windows: C:\ProgramData\PuppetLabs\puppet\etc -- Non-root user: ~/.puppetlabs/etc/puppet'
+    elsif name.to_s == 'codedir'
+      val = 'Unix/Linux: /etc/puppetlabs/code -- Windows: C:\ProgramData\PuppetLabs\code -- Non-root user: ~/.puppetlabs/etc/code'
+    elsif name.to_s == 'rundir'
+      val = 'Unix/Linux: /var/run/puppetlabs -- Windows: C:\ProgramData\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppetlabs/var/run'
+    elsif name.to_s == 'logdir'
+      val = 'Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\ProgramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppetlabs/var/log'
+    elsif name.to_s == 'hiera_config'
+      val = '$confdir/hiera.yaml. However, for backwards compatibility, if a file exists at $codedir/hiera.yaml, Puppet uses that instead.'
+    elsif name.to_s == 'certname'
+      val = "the Host's fully qualified domain name, as determined by Facter"
+    elsif name.to_s == 'srv_domain'
+      val = 'example.com'
+    end
+
+    # Leave out the section information; it was apparently confusing people.
+    #str << "- **Section**: #{object.section}\n"
+    unless val == ""
+      str << "- *Default*: `#{val}`\n"
+    end
+    str << "\n"
+  end
+
+  return str
+end
+
+config.header = <<EOT
+## Configuration settings
+
+* Each of these settings can be specified in `puppet.conf` or on the
+  command line.
+* Puppet Enterprise (PE) and open source Puppet share the configuration settings
+  documented here. However, PE defaults differ from open source defaults for some
+  settings, such as `node_terminus`, `storeconfigs`, `always_retry_plugins`,
+  `disable18n`, `environment_timeout` (when Code Manager is enabled), and the
+  Puppet Server JRuby `max-active-instances` setting. To verify PE configuration
+  defaults, check the `puppet.conf` or `pe-puppet-server.conf` file after
+  installation.
+* When using boolean settings on the command line, use `--setting` and
+  `--no-setting` instead of `--setting (true|false)`. (Using `--setting false`
+  results in "Error: Could not parse application options: needless argument".)
+* Settings can be interpolated as `$variables` in other settings; `$environment`
+  is special, in that puppet master will interpolate each agent node's
+  environment instead of its own.
+* Multiple values should be specified as comma-separated lists; multiple
+  directories should be separated with the system path separator (usually
+  a colon).
+* Settings that represent time intervals should be specified in duration format:
+  an integer immediately followed by one of the units 'y' (years of 365 days),
+  'd' (days), 'h' (hours), 'm' (minutes), or 's' (seconds). The unit cannot be
+  combined with other units, and defaults to seconds when omitted. Examples are
+  '3600' which is equivalent to '1h' (one hour), and '1825d' which is equivalent
+  to '5y' (5 years).
+* If you use the `splay` setting, note that the period that it waits changes
+  each time the Puppet agent is restarted.
+* Settings that take a single file or directory can optionally set the owner,
+  group, and mode for their value: `rundir = $vardir/run { owner = puppet,
+  group = puppet, mode = 644 }`
+* The Puppet executables ignores any setting that isn't relevant to
+  their function.
+
+See the [configuration guide][confguide] for more details.
+
+[confguide]: https://puppet.com/docs/puppet/latest/config_about_settings.html
+
+* * *
+
+EOT

data/lib/puppet/reference/function.rb

@@ -0,0 +1,17 @@
+function = Puppet::Util::Reference.newreference :function, :doc => "All functions available in the parser" do
+  Puppet::Parser::Functions.functiondocs
+end
+function.header = "
+There are two types of functions in Puppet: Statements and rvalues.
+Statements stand on their own and do not return arguments; they are used for
+performing stand-alone work like importing.  Rvalues return values and can
+only be used in a statement requiring a value, such as an assignment or a case
+statement.
+
+Functions execute on the Puppet master.  They do not execute on the Puppet agent.
+Hence they only have access to the commands and data available on the Puppet master
+host.
+
+Here are the functions available in Puppet:
+
+"

data/lib/puppet/reference/indirection.rb

@@ -0,0 +1,71 @@
+require_relative '../../puppet/indirector/indirection'
+require_relative '../../puppet/util/checksums'
+require_relative '../../puppet/file_serving/content'
+require_relative '../../puppet/file_serving/metadata'
+
+reference = Puppet::Util::Reference.newreference :indirection, :doc => "Indirection types and their terminus classes" do
+  text = ""
+  Puppet::Indirector::Indirection.instances.sort_by(&:to_s).each do |indirection|
+    ind = Puppet::Indirector::Indirection.instance(indirection)
+    name = indirection.to_s.capitalize
+    text << "## " + indirection.to_s + "\n\n"
+
+    text << Puppet::Util::Docs.scrub(ind.doc) + "\n\n"
+
+    Puppet::Indirector::Terminus.terminus_classes(ind.name).sort_by(&:to_s).each do |terminus|
+      terminus_name = terminus.to_s
+      term_class = Puppet::Indirector::Terminus.terminus_class(ind.name, terminus)
+      if term_class
+        terminus_doc = Puppet::Util::Docs.scrub(term_class.doc)
+        text << markdown_header("`#{terminus_name}` terminus", 3) << terminus_doc << "\n\n"
+      else
+        Puppet.warning _("Could not build docs for indirector %{name}, terminus %{terminus}: could not locate terminus.") % { name: name.inspect, terminus: terminus_name.inspect }
+      end
+    end
+  end
+
+  text
+end
+
+reference.header = <<HEADER
+
+## About Indirection
+
+Puppet's indirector support pluggable backends (termini) for a variety of key-value stores (indirections).
+Each indirection type corresponds to a particular Ruby class (the "Indirected Class" below) and values are instances of that class.
+Each instance's key is available from its `name` method.
+The termini can be local (e.g., on-disk files) or remote (e.g., using a REST interface to talk to a puppet master).
+
+An indirector has five methods, which are mapped into HTTP verbs for the REST interface:
+
+* `find(key)` - get a single value (mapped to GET or POST with a singular endpoint)
+* `search(key)` - get a list of matching values (mapped to GET with a plural endpoint)
+* `head(key)` - return true if the key exists (mapped to HEAD)
+* `destroy(key)` - remove the key and value (mapped to DELETE)
+* `save(instance)` - write the instance to the store, using the instance's name as the key (mapped to PUT)
+
+These methods are available via the `indirection` class method on the indirected classes.  For example:
+
+    node = Puppet::Node.indirection.find('foo.example.com')
+
+At startup, each indirection is configured with a terminus.
+In most cases, this is the default terminus defined by the indirected class, but it can be overridden by the application or face, or overridden with the `route_file` configuration.
+The available termini differ for each indirection, and are listed below.
+
+Indirections can also have a cache, represented by a second terminus.
+This is a write-through cache: modifications are written both to the cache and to the primary terminus.
+Values fetched from the terminus are written to the cache.
+
+### Interaction with REST
+
+REST endpoints have the form `/{prefix}/{version}/{indirection}/{key}?environment={environment}`, where the indirection can be singular or plural, following normal English spelling rules.
+On the server side, REST responses are generated from the locally-configured endpoints.
+
+### Indirections and Termini
+
+Below is the list of all indirections, their associated terminus classes, and how you select between them.
+
+In general, the appropriate terminus class is selected by the application for you (e.g., `puppet agent` would always use the `rest`
+terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have `terminus setting` documentation listed with them.
+
+HEADER

data/lib/puppet/reference/metaparameter.rb

@@ -0,0 +1,33 @@
+Puppet::Util::Reference.newreference :metaparameter, :doc => "All Puppet metaparameters and all their details" do
+  str = %{
+
+Metaparameters are attributes that work with any resource type, including custom
+types and defined types.
+
+In general, they affect _Puppet's_ behavior rather than the desired state of the
+resource. Metaparameters do things like add metadata to a resource (`alias`,
+`tag`), set limits on when the resource should be synced (`require`, `schedule`,
+etc.), prevent Puppet from making changes (`noop`), and change logging verbosity
+(`loglevel`).
+
+## Available Metaparameters
+
+}
+  begin
+    params = []
+    Puppet::Type.eachmetaparam { |param|
+      params << param
+    }
+
+    params.sort_by(&:to_s).each { |param|
+      str << markdown_header(param.to_s, 3)
+      str << scrub(Puppet::Type.metaparamdoc(param))
+      str << "\n\n"
+    }
+  rescue => detail
+    Puppet.log_exception(detail, _("incorrect metaparams: %{detail}") % { detail: detail })
+    exit(1)
+  end
+
+  str
+end

data/lib/puppet/reference/providers.rb

@@ -0,0 +1,117 @@
+providers = Puppet::Util::Reference.newreference :providers, :title => "Provider Suitability Report", :depth => 1, :dynamic => true, :doc => "Which providers are valid for this machine" do
+  types = []
+  Puppet::Type.loadall
+  Puppet::Type.eachtype do |klass|
+    next unless klass && klass.providers.length > 0
+    types << klass
+  end
+  types.sort! { |a,b| a.name.to_s <=> b.name.to_s }
+
+  command_line = Puppet::Util::CommandLine.new
+  types.reject! { |type| ! command_line.args.include?(type.name.to_s) } unless command_line.args.empty?
+
+  ret = "Details about this host:\n\n"
+
+  # Throw some facts in there, so we know where the report is from.
+  ["Ruby Version", "Puppet Version", "Operating System", "Operating System Release"].each do |label|
+    name = label.gsub(/\s+/, '')
+    value = Puppet.runtime[:facter].value(name)
+    ret << option(label, value)
+  end
+  ret << "\n"
+
+  count = 1
+
+  # Produce output for each type.
+  types.each do |type|
+    features = type.features
+    ret << "\n" # add a trailing newline
+
+    # Now build up a table of provider suitability.
+    headers = %w{Provider Suitable?} + features.collect { |f| f.to_s }.sort
+
+    table_data = {}
+
+    notes = []
+    default = type.defaultprovider ? type.defaultprovider.name : 'none'
+    type.providers.sort_by(&:to_s).each do |pname|
+      data = []
+      table_data[pname] = data
+      provider = type.provider(pname)
+
+      # Add the suitability note
+      missing = provider.suitable?(false)
+      if missing && missing.empty?
+        data << "*X*"
+        suit = true
+      else
+        data << "[#{count}]_" # A pointer to the appropriate footnote
+        suit = false
+      end
+
+      # Add a footnote with the details about why this provider is unsuitable, if that's the case
+      unless suit
+        details = ".. [#{count}]\n"
+        missing.each do |test, values|
+          case test
+          when :exists
+            details << _("  - Missing files %{files}\n") % { files: values.join(", ") }
+          when :variable
+            values.each do |name, facts|
+              if Puppet.settings.valid?(name)
+                details << _("  - Setting %{name} (currently %{value}) not in list %{facts}\n") % { name: name, value: Puppet.settings.value(name).inspect, facts: facts.join(", ") }
+              else
+                details << _("  - Fact %{name} (currently %{value}) not in list %{facts}\n") % { name: name, value: Puppet.runtime[:facter].value(name).inspect, facts: facts.join(", ") }
+              end
+            end
+          when :true
+            details << _("  - Got %{values} true tests that should have been false\n") % { values: values }
+          when :false
+            details << _("  - Got %{values} false tests that should have been true\n") % { values: values }
+          when :feature
+            details << _("  - Missing features %{values}\n") % { values: values.collect { |f| f.to_s }.join(",") }
+          end
+        end
+        notes << details
+
+        count += 1
+      end
+
+      # Add a note for every feature
+      features.each do |feature|
+        if provider.features.include?(feature)
+          data << "*X*"
+        else
+          data << ""
+        end
+      end
+    end
+
+    ret << markdown_header(type.name.to_s + "_", 2)
+
+    ret << "[#{type.name}](https://puppet.com/docs/puppet/latest/type.html##{type.name})\n\n"
+    ret << option("Default provider", default)
+    ret << doctable(headers, table_data)
+
+    notes.each do |note|
+      ret << note + "\n"
+    end
+
+    ret << "\n"
+  end
+
+  ret << "\n"
+
+  ret
+end
+providers.header = "
+Puppet resource types are usually backed by multiple implementations called `providers`,
+which handle variance between platforms and tools.
+
+Different providers are suitable or unsuitable on different platforms based on things
+like the presence of a given tool.
+
+Here are all of the provider-backed types and their different providers.  Any unmentioned
+types do not use providers yet.
+
+"

data/lib/puppet/reference/report.rb

@@ -0,0 +1,20 @@
+require_relative '../../puppet/reports'
+
+report = Puppet::Util::Reference.newreference :report, :doc => "All available transaction reports" do
+  Puppet::Reports.reportdocs
+end
+
+report.header = "
+Puppet can generate a report after applying a catalog. This report includes
+events, log messages, resource statuses, and metrics and metadata about the run.
+Puppet agent sends its report to a Puppet master server, and Puppet apply
+processes its own reports.
+
+Puppet master and Puppet apply will handle every report with a set of report
+processors, configurable with the `reports` setting in puppet.conf. This page
+documents the built-in report processors.
+
+See [About Reporting](https://puppet.com/docs/puppet/latest/reporting_about.html)
+for more details.
+
+"

data/lib/puppet/reference/type.rb

@@ -0,0 +1,109 @@
+Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource types and all their details" do
+  types = {}
+  Puppet::Type.loadall
+
+  Puppet::Type.eachtype { |type|
+    next if type.name == :component
+    next if type.name == :whit
+    types[type.name] = type
+  }
+
+  str = %{
+
+## Resource Types
+
+- The *namevar* is the parameter used to uniquely identify a type instance.
+  This is the parameter that gets assigned when a string is provided before
+  the colon in a type declaration.  In general, only developers will need to
+  worry about which parameter is the `namevar`.
+
+  In the following code:
+
+      file { "/etc/passwd":
+        owner => "root",
+        group => "root",
+        mode  => "0644"
+      }
+
+  `/etc/passwd` is considered the title of the file object (used for things like
+  dependency handling), and because `path` is the namevar for `file`, that
+  string is assigned to the `path` parameter.
+
+- *Parameters* determine the specific configuration of the instance.  They either
+  directly modify the system (internally, these are called properties) or they affect
+  how the instance behaves (e.g., adding a search path for `exec` instances or determining recursion on `file` instances).
+
+- *Providers* provide low-level functionality for a given resource type.  This is
+  usually in the form of calling out to external commands.
+
+  When required binaries are specified for providers, fully qualified paths
+  indicate that the binary must exist at that specific path and unqualified
+  binaries indicate that Puppet will search for the binary using the shell
+  path.
+
+- *Features* are abilities that some providers might not support.  You can use the list
+  of supported features to determine how a given provider can be used.
+
+  Resource types define features they can use, and providers can be tested to see
+  which features they provide.
+
+  }
+
+  types.sort_by(&:to_s).each { |name,type|
+
+    str << "
+
+----------------
+
+"
+
+    str << markdown_header(name, 3)
+    str << scrub(type.doc) + "\n\n"
+
+    # Handle the feature docs.
+    featuredocs = type.featuredocs
+    if featuredocs
+      str << markdown_header("Features", 4)
+      str << featuredocs
+    end
+
+    docs = {}
+    type.validproperties.sort_by(&:to_s).reject { |sname|
+      property = type.propertybyname(sname)
+      property.nodoc
+    }.each { |sname|
+      property = type.propertybyname(sname)
+
+      raise _("Could not retrieve property %{sname} on type %{type_name}") % { sname: sname, type_name: type.name } unless property
+
+      doc = property.doc
+      unless doc
+        $stderr.puts _("No docs for %{type}[%{sname}]") % { type: type, sname: sname }
+        next
+      end
+      doc = doc.dup
+      tmp = doc
+      tmp = scrub(tmp)
+
+      docs[sname]  = tmp
+    }
+
+    str << markdown_header("Parameters", 4) + "\n"
+    type.parameters.sort_by(&:to_s).each { |type_name, param|
+      docs[type_name] = scrub(type.paramdoc(type_name))
+    }
+
+    additional_key_attributes = type.key_attributes - [:name]
+    docs.sort { |a, b|
+      a[0].to_s <=> b[0].to_s
+    }.each { |type_name, doc|
+      if additional_key_attributes.include?(type_name)
+        doc = "(**Namevar:** If omitted, this parameter's value defaults to the resource's title.)\n\n" + doc
+      end
+      str << markdown_definitionlist(type_name, doc)
+    }
+    str << "\n"
+  }
+
+  str
+end

data/lib/puppet/relationship.rb

@@ -0,0 +1,84 @@
+# subscriptions are permanent associations determining how different
+# objects react to an event
+
+# This is Puppet's class for modeling edges in its configuration graph.
+# It used to be a subclass of GRATR::Edge, but that class has weird hash
+# overrides that dramatically slow down the graphing.
+class Puppet::Relationship
+
+  # FormatSupport for serialization methods
+  include Puppet::Network::FormatSupport
+  include Puppet::Util::PsychSupport
+
+  attr_accessor :source, :target, :callback
+
+  attr_reader :event
+
+  def self.from_data_hash(data)
+    source = data['source']
+    target = data['target']
+
+    args = {}
+    args[:event] = :"#{data['event']}" if data["event"]
+    args[:callback] = :"#{data['callback']}" if data["callback"]
+
+    new(source, target, args)
+  end
+
+  def event=(event)
+    #TRANSLATORS 'NONE' should not be translated
+    raise ArgumentError, _("You must pass a callback for non-NONE events") if event != :NONE and ! callback
+    @event = event
+  end
+
+  def initialize(source, target, options = {})
+    @source, @target = source, target
+
+    options = (options || {}).inject({}) { |h,a| h[a[0].to_sym] = a[1]; h }
+    [:callback, :event].each do |option|
+      value = options[option]
+      send(option.to_s + "=", value) if value
+    end
+  end
+
+  # Does the passed event match our event?  This is where the meaning
+  # of :NONE comes from.
+  def match?(event)
+    if self.event.nil? or event == :NONE or self.event == :NONE
+      return false
+    elsif self.event == :ALL_EVENTS or event == self.event
+      return true
+    else
+      return false
+    end
+  end
+
+  def label
+    result = {}
+    result[:callback] = callback if callback
+    result[:event] = event if event
+    result
+  end
+
+  def ref
+    "#{source} => #{target}"
+  end
+
+  def inspect
+    "{ #{source} => #{target} }"
+  end
+
+  def to_data_hash
+    data = {
+      'source' => source.to_s,
+      'target' => target.to_s
+    }
+    data['event'] = event.to_s unless event.nil?
+    data['callback'] = callback.to_s unless callback.nil?
+    data
+  end
+
+  def to_s
+    ref
+  end
+end

data/lib/puppet/reports/http.rb

@@ -0,0 +1,44 @@
+require_relative '../../puppet'
+require_relative '../../puppet/network/http_pool'
+require 'uri'
+
+Puppet::Reports.register_report(:http) do
+
+  desc <<-DESC
+    Send reports via HTTP or HTTPS. This report processor submits reports as
+    POST requests to the address in the `reporturl` setting. When a HTTPS URL
+    is used, the remote server must present a certificate issued by the Puppet
+    CA or the connection will fail validation. The body of each POST request
+    is the YAML dump of a Puppet::Transaction::Report object, and the
+    Content-Type is set as `application/x-yaml`.
+  DESC
+
+  def process
+    url = URI.parse(Puppet[:reporturl])
+    headers = { "Content-Type" => "application/x-yaml" }
+    # This metric_id option is silently ignored by Puppet's http client
+    # (Puppet::Network::HTTP) but is used by Puppet Server's http client
+    # (Puppet::Server::HttpClient) to track metrics on the request made to the
+    # `reporturl` to store a report.
+    options = {
+      :metric_id => [:puppet, :report, :http],
+      :include_system_store => Puppet[:report_include_system_store],
+    }
+
+    # Puppet's http client implementation accepts userinfo in the URL
+    # but puppetserver's does not. So pass credentials explicitly.
+    if url.user && url.password
+      options[:basic_auth] = {
+        user: url.user,
+        password: url.password
+      }
+    end
+
+    client = Puppet.runtime[:http]
+    client.post(url, self.to_yaml, headers: headers, options: options) do |response|
+      unless response.success?
+        Puppet.err _("Unable to submit report to %{url} [%{code}] %{message}") % { url: Puppet[:reporturl].to_s, code: response.code, message: response.reason }
+      end
+    end
+  end
+end

data/lib/puppet/reports/log.rb

@@ -0,0 +1,14 @@
+require_relative '../../puppet/reports'
+
+Puppet::Reports.register_report(:log) do
+  desc "Send all received logs to the local log destinations.  Usually
+    the log destination is syslog."
+
+  def process
+    self.logs.each do |log|
+      log.source = "//#{self.host}/#{log.source}"
+      Puppet::Util::Log.newmessage(log)
+    end
+  end
+end
+

data/lib/puppet/reports/store.rb

@@ -0,0 +1,68 @@
+require_relative '../../puppet'
+require 'fileutils'
+require_relative '../../puppet/util'
+
+SEPARATOR = [Regexp.escape(File::SEPARATOR.to_s), Regexp.escape(File::ALT_SEPARATOR.to_s)].join
+
+Puppet::Reports.register_report(:store) do
+  desc "Store the yaml report on disk.  Each host sends its report as a YAML dump
+    and this just stores the file on disk, in the `reportdir` directory.
+
+    These files collect quickly -- one every half hour -- so it is a good idea
+    to perform some maintenance on them if you use this report (it's the only
+    default report)."
+
+  def process
+    validate_host(host)
+
+    dir = File.join(Puppet[:reportdir], host)
+
+    if ! Puppet::FileSystem.exist?(dir)
+      FileUtils.mkdir_p(dir)
+      FileUtils.chmod_R(0750, dir)
+    end
+
+    # Now store the report.
+    now = Time.now.gmtime
+    name = %w{year month day hour min}.collect do |method|
+      # Make sure we're at least two digits everywhere
+      "%02d" % now.send(method).to_s
+    end.join("") + ".yaml"
+
+    file = File.join(dir, name)
+
+    begin
+      Puppet::FileSystem.replace_file(file, 0640) do |fh|
+        fh.print to_yaml
+      end
+    rescue => detail
+       Puppet.log_exception(detail, "Could not write report for #{host} at #{file}: #{detail}")
+    end
+
+    # Only testing cares about the return value
+    file
+  end
+
+  # removes all reports for a given host?
+  def self.destroy(host)
+    validate_host(host)
+
+    dir = File.join(Puppet[:reportdir], host)
+
+    if Puppet::FileSystem.exist?(dir)
+      Dir.entries(dir).each do |file|
+        next if ['.','..'].include?(file)
+        file = File.join(dir, file)
+        Puppet::FileSystem.unlink(file) if File.file?(file)
+      end
+      Dir.rmdir(dir)
+    end
+  end
+
+  def validate_host(host)
+    if host =~ Regexp.union(/[#{SEPARATOR}]/, /\A\.\.?\Z/)
+      raise ArgumentError, _("Invalid node name %{host}") % { host: host.inspect }
+    end
+  end
+  module_function :validate_host
+end