puppet 5.1.0 → 5.2.0

data/lib/puppet.rb

@@ -21,51 +21,7 @@ require 'puppet/util/run_mode'
 require 'puppet/external/pson/common'
 require 'puppet/external/pson/version'
 require 'puppet/external/pson/pure'
-
-# When running within puppetserver, the gettext-setup gem might not be available, so
-# we need to skip initializing i18n functionality and stub out methods normally
-# supplied by gettext-setup. Can be removed in Puppet 5. See PUP-7116.
-begin
-  require 'gettext-setup'
-  require 'locale'
-
-  # e.g. ~/code/puppet/locales. Also when running as a gem.
-  local_locale_path = File.absolute_path('../locales', File.dirname(__FILE__))
-  # e.g. /opt/puppetlabs/puppet/share/locale
-  posix_system_locale_path = File.absolute_path('../../../share/locale', File.dirname(__FILE__))
-  # e.g. C:\Program Files\Puppet Labs\Puppet\puppet\share\locale
-  win32_system_locale_path = File.absolute_path('../../../../../puppet/share/locale', File.dirname(__FILE__))
-
-  if File.exist?(local_locale_path)
-    locale_path = local_locale_path
-  elsif Puppet::Util::Platform.windows? && File.exist?(win32_system_locale_path)
-    locale_path = win32_system_locale_path
-  elsif !Puppet::Util::Platform.windows? && File.exist?(posix_system_locale_path)
-    locale_path = posix_system_locale_path
-  else
-    # We couldn't load our locale data.
-    raise LoadError, "could not find locale data, skipping Gettext initialization"
-  end
-
-  Puppet::LOCALE_PATH = locale_path
-  Puppet::GETTEXT_AVAILABLE = true
-rescue LoadError
-  def _(msg)
-    msg
-  end
-
-  def n_(*args, &block)
-    # assume two string args (singular and plural English form) and the count
-    # to pluralize on
-    plural = args[2] == 1 ? args[0] : args[1]
-    # if a block is passed, prefer that over the string selection above
-    block ? block.call : plural
-  end
-
-  Puppet::LOCALE_PATH = nil
-  Puppet::GETTEXT_AVAILABLE = false
-end
-
+require 'puppet/gettext/config'
 
 
 #------------------------------------------------------------
@@ -86,14 +42,11 @@ module Puppet
   require 'puppet/environments'
 
   class << self
-    if Puppet::GETTEXT_AVAILABLE && Puppet::LOCALE_PATH
-      if GettextSetup.method(:initialize).parameters.count == 1
-        # Will load translations from PO files only
-        GettextSetup.initialize(Puppet::LOCALE_PATH)
-      else
-        GettextSetup.initialize(Puppet::LOCALE_PATH, :file_format => :mo)
-      end
-      FastGettext.locale = GettextSetup.negotiate_locale(Locale.current.language)
+    gettext_config_file = Puppet::GettextConfig.puppet_locale_path
+    unless Puppet::GettextConfig.initialize(gettext_config_file, Puppet::GettextConfig.translation_mode(gettext_config_file))
+      # Stub out gettext's `_` and `n_()` methods, which attempt to load translations,
+      # with versions that do nothing
+      require 'puppet/gettext/stubs'
     end
 
     include Puppet::Util

data/lib/puppet/application.rb

@@ -339,23 +339,23 @@ class Application
     # I don't really like the names of these lifecycle phases.  It would be nice to change them to some more meaningful
     # names, and make deprecated aliases.  --cprice 2012-03-16
 
-    exit_on_fail(_("get application-specific default settings")) do
+    exit_on_fail(_("Could not get application-specific default settings")) do
       initialize_app_defaults
     end
 
     Puppet::ApplicationSupport.push_application_context(self.class.run_mode)
 
-    exit_on_fail(_("initialize"))                                   { preinit }
-    exit_on_fail(_("parse application options"))                    { parse_options }
-    exit_on_fail(_("prepare for execution"))                        { setup }
+    exit_on_fail(_("Could not initialize"))                { preinit }
+    exit_on_fail(_("Could not parse application options")) { parse_options }
+    exit_on_fail(_("Could not prepare for execution"))     { setup }
 
     if deprecated?
       Puppet.deprecation_warning(_("`puppet %{name}` is deprecated and will be removed in a future release.") % { name: name })
     end
 
-    exit_on_fail(_("configure routes from %{route_file}") % { route_file: Puppet[:route_file] }) { configure_indirector_routes }
-    exit_on_fail(_("log runtime debug info"))                       { log_runtime_environment }
-    exit_on_fail(_("run"))                                          { run_command }
+    exit_on_fail(_("Could not configure routes from %{route_file}") % { route_file: Puppet[:route_file] }) { configure_indirector_routes }
+    exit_on_fail(_("Could not log runtime debug info"))                       { log_runtime_environment }
+    exit_on_fail(_("Could not run"))                                          { run_command }
   end
 
   def main
@@ -474,5 +474,12 @@ class Application
   def help
     _("No help available for puppet %{app_name}") % { app_name: name }
   end
+
+  # The description used in top level `puppet help` output
+  # If left empty in implementations, we will attempt to extract
+  # the summary from the help text itself.
+  def summary
+    ""
+  end
 end
 end

data/lib/puppet/application/agent.rb

@@ -75,10 +75,14 @@ class Puppet::Application::Agent < Puppet::Application
     options[:job_id] = arg
   end
 
+  def summary
+    _("The puppet agent daemon")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-agent(8) -- The puppet agent daemon
+puppet-agent(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/apply.rb

@@ -31,10 +31,14 @@ class Puppet::Application::Apply < Puppet::Application
     exit 1
   end
 
+  def summary
+    _("Apply Puppet manifests locally")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-apply(8) -- Apply Puppet manifests locally
+puppet-apply(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/cert.rb

@@ -99,10 +99,14 @@ class Puppet::Application::Cert < Puppet::Application
     options[:yes] = true
   end
 
+  def summary
+    _("Manage certificates and requests")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-cert(8) -- Manage certificates and requests
+puppet-cert(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/describe.rb

@@ -178,10 +178,14 @@ class Puppet::Application::Describe < Puppet::Application
   option("--list", "-l")
   option("--meta","-m")
 
+  def summary
+    _("Display help about resource types")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-describe(8) -- Display help about resource types
+puppet-describe(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/device.rb

@@ -62,59 +62,66 @@ class Puppet::Application::Device < Puppet::Application
     options[:target] = arg.to_s
   end
 
-    def help
-      <<-'HELP'
+  def summary
+    _("Manage remote network devices")
+  end
+
+  def help
+      <<-HELP
 
-puppet-device(8) -- Manage remote network devices
+puppet-device(8) -- #{summary}
 ========
 
 SYNOPSIS
 --------
-Retrieves all configurations from the puppet master and apply
-them to the remote devices configured in /etc/puppetlabs/puppet/device.conf.
+Retrieves catalogs from the Puppet master and applies them to remote devices. 
+
+This subcommand can be run manually; or periodically using cron,
+a scheduled task, or a similar tool.
 
-Currently must be run out periodically, using cron or something similar.
 
 USAGE
 -----
   puppet device [-d|--debug] [--detailed-exitcodes] [--deviceconfig <file>]
                 [-h|--help] [-l|--logdest syslog|<file>|console]
                 [-v|--verbose] [-w|--waitforcert <seconds>]
-                [-t|--target <device>] [-V|--version]
+                [-t|--target <device>] [--user=<user>] [-V|--version]
 
 
 DESCRIPTION
 -----------
-Once the client has a signed certificate for a given remote device, it will
-retrieve its configuration and apply it.
+Devices require a proxy Puppet agent to request certificates, collect facts,
+retrieve and apply catalogs, and store reports.
+
 
 USAGE NOTES
 -----------
-One need a /etc/puppetlabs/puppet/device.conf file with the following content:
+Devices managed by the puppet-device subcommand on a Puppet agent are 
+configured in device.conf, which is located at $confdir/device.conf by default, 
+and is configurable with the $deviceconfig setting. 
+
+The device.conf file is an INI-like file, with one section per device:
 
-[remote.device.fqdn]
-type <type>
-url <url>
+[<DEVICE_CERTNAME>]
+type <TYPE>
+url <URL>
+debug
 
-where:
- * type: the current device type (the only value at this time is cisco)
- * url: an url allowing to connect to the device
+The section name specifies the certname of the device. 
 
-Supported url must conforms to:
- scheme://user:password@hostname/?query
+The values for the type and url properties are specific to each type of device.
+
+The optional debug property specifies transport-level debugging,
+and is limited to telnet and ssh transports.
+
+See https://docs.puppet.com/puppet/latest/config_file_device.html for details.
 
- with:
-  * scheme: either ssh or telnet
-  * user: username, can be omitted depending on the switch/router configuration
-  * password: the connection password
-  * query: this is device specific. Cisco devices supports an enable parameter whose
-  value would be the enable password.
 
 OPTIONS
 -------
-Note that any setting that's valid in the configuration file
-is also a valid long argument.  For example, 'server' is a valid configuration
-parameter, so you can specify '--server <servername>' as an argument.
+Note that any setting that's valid in the configuration file is also a valid 
+long argument. For example, 'server' is a valid configuration parameter, so 
+you can specify '--server <servername>' as an argument.
 
 * --debug:
   Enable full debugging.
@@ -147,6 +154,10 @@ parameter, so you can specify '--server <servername>' as an argument.
   Target a specific device/certificate in the device.conf. Doing so will perform a
   device run against only that device/certificate.
 
+* --user:
+  The user to run as. '--user=root' is required, even when run as root,
+  for runs that create device certificates or keys.
+
 * --verbose:
   Turn on verbose reporting.
 
@@ -155,8 +166,8 @@ parameter, so you can specify '--server <servername>' as an argument.
   and it is enabled by default, with a value of 120 (seconds).  This causes
   +puppet agent+ to connect to the server every 2 minutes and ask it to sign a
   certificate request.  This is useful for the initial setup of a puppet
-  client.  You can turn off waiting for certificates by specifying a time
-  of 0.
+  client.  You can turn off waiting for certificates by specifying a time of 0.
+
 
 EXAMPLE
 -------

data/lib/puppet/application/doc.rb

@@ -48,10 +48,14 @@ class Puppet::Application::Doc < Puppet::Application
     options[:references] << arg.intern
   end
 
+  def summary
+    _("Generate Puppet references")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-doc(8) -- Generate Puppet references
+puppet-doc(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/filebucket.rb

@@ -12,10 +12,14 @@ class Puppet::Application::Filebucket < Puppet::Application
 
   attr :args
 
+  def summary
+    _("Store and retrieve files in a filebucket")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-filebucket(8) -- Store and retrieve files in a filebucket
+puppet-filebucket(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/lookup.rb

@@ -95,10 +95,14 @@ class Puppet::Application::Lookup < Puppet::Application
     setup_terminuses
   end
 
+  def summary
+    _("Interactive Hiera lookup")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-lookup(8) -- Interactive Hiera lookup
+puppet-lookup(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/master.rb

@@ -25,10 +25,14 @@ class Puppet::Application::Master < Puppet::Application
     exit 1
   end
 
+  def summary
+    _("The puppet master daemon")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-master(8) -- The puppet master daemon
+puppet-master(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/application/resource.rb

@@ -28,10 +28,14 @@ class Puppet::Application::Resource < Puppet::Application
     @extra_params << arg.to_sym
   end
 
+  def summary
+    _("The resource abstraction layer shell")
+  end
+
   def help
-    <<-'HELP'
+    <<-HELP
 
-puppet-resource(8) -- The resource abstraction layer shell
+puppet-resource(8) -- #{summary}
 ========
 
 SYNOPSIS

data/lib/puppet/face/catalog.rb

@@ -4,7 +4,7 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do
   copyright "Puppet Inc.", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Compile, save, view, and convert catalogs."
+  summary _("Compile, save, view, and convert catalogs.")
   description <<-'EOT'
     This subcommand deals with catalogs, which are compiled per-node artifacts
     generated from a set of Puppet manifests. By default, it interacts with the

data/lib/puppet/face/certificate_request.rb

@@ -4,7 +4,7 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
   copyright "Puppet Inc.", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Manage certificate requests."
+  summary _("Manage certificate requests.")
   description <<-EOT
     This subcommand retrieves and submits certificate signing requests (CSRs).
   EOT

data/lib/puppet/face/certificate_revocation_list.rb

@@ -4,7 +4,7 @@ Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
   copyright "Puppet Inc.", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Manage the list of revoked certificates."
+  summary _("Manage the list of revoked certificates.")
   description <<-EOT
     This subcommand is primarily for retrieving the certificate revocation
     list from the CA.

data/lib/puppet/face/help.rb

@@ -153,25 +153,29 @@ MSG
           result << [ "! #{appname}", _("! Subcommand unavailable due to error. Check error logs.") ]
         end
       else
-        result << [appname, horribly_extract_summary_from(appname)]
+        begin
+          summary = Puppet::Application[appname].summary
+          if summary.empty?
+            summary = horribly_extract_summary_from(appname)
+          end
+          result << [appname, summary]
+        rescue StandardError, LoadError
+          result << ["! #{appname}", _("! Subcommand unavailable due to error. Check error logs.")]
+        end
       end
     end
   end
 
   def horribly_extract_summary_from(appname)
-    begin
-      help = Puppet::Application[appname].help.split("\n")
-      # Now we find the line with our summary, extract it, and return it.  This
-      # depends on the implementation coincidence of how our pages are
-      # formatted.  If we can't match the pattern we expect we return the empty
-      # string to ensure we don't blow up in the summary. --daniel 2011-04-11
-      while line = help.shift do
-        if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
-          return md[1]
-        end
+    help = Puppet::Application[appname].help.split("\n")
+    # Now we find the line with our summary, extract it, and return it.  This
+    # depends on the implementation coincidence of how our pages are
+    # formatted.  If we can't match the pattern we expect we return the empty
+    # string to ensure we don't blow up in the summary. --daniel 2011-04-11
+    while line = help.shift do
+      if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
+        return md[1]
       end
-    rescue StandardError, LoadError
-      return _("! Subcommand unavailable due to error. Check error logs.")
     end
     return ''
   end