puppet 2.6.18 → 2.7.1

data/lib/puppet/face/man.rb

@@ -0,0 +1,93 @@
+require 'puppet/face'
+require 'puppet/util'
+require 'pathname'
+require 'erb'
+
+Puppet::Face.define(:man, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Display Puppet manual pages."
+
+  description <<-EOT
+    This subcommand displays manual pages for all Puppet subcommands. If the
+    `ronn` gem (<https://github.com/rtomayko/ronn/>) is installed on your
+    system, puppet man will display fully-formated man pages. If `ronn` is not
+    available, puppet man will display the raw (but human-readable) source text
+    in a pager.
+  EOT
+
+  notes <<-EOT
+    The pager used for display will be the first found of `$MANPAGER`, `$PAGER`,
+    `less`, `most`, or `more`.
+  EOT
+
+  action(:man) do
+    summary "Display the manual page for a Puppet subcommand."
+    arguments "<subcommand>"
+    returns <<-'EOT'
+      The man data, in Markdown format, suitable for consumption by Ronn.
+
+      RENDERING ISSUES: To skip fancy formatting and output the raw Markdown
+      text (e.g. for use in a pipeline), call this action with '--render-as s'.
+    EOT
+    examples <<-'EOT'
+      View the manual page for a subcommand:
+
+      $ puppet man facts
+    EOT
+
+    default
+    when_invoked do |name, options|
+      if legacy_applications.include? name then
+        return Puppet::Application[name].help
+      end
+
+      face = Puppet::Face[name.to_sym, :current]
+
+      file = (Pathname(__FILE__).dirname + "help" + 'man.erb')
+      erb = ERB.new(file.read, nil, '-')
+      erb.filename = file.to_s
+
+      # Run the ERB template in our current binding, including all the local
+      # variables we established just above. --daniel 2011-04-11
+      return erb.result(binding)
+    end
+
+
+    when_rendering :console do |text|
+      # OK, if we have Ronn on the path we can delegate to it and override the
+      # normal output process.  Otherwise delegate to a pager on the raw text,
+      # otherwise we finally just delegate to our parent.  Oh, well.
+      ENV['LESS'] ||= 'FRSX'    # emulate git...
+
+      ronn  = Puppet::Util.which('ronn')
+      pager = [ENV['MANPAGER'], ENV['PAGER'], 'less', 'most', 'more'].
+        detect {|x| x and x.length > 0 and Puppet::Util.which(x) }
+
+      if ronn then
+        # ronn is a stupid about pager selection, we can be smarter. :)
+        if pager then ENV['PAGER'] = pager end
+
+        args  = "--man --manual='Puppet Manual' --organization='Puppet Labs, LLC'"
+        IO.popen("#{ronn} #{args}", 'w') do |fh| fh.write text end
+
+        ''                      # suppress local output, neh?
+      elsif pager then
+        IO.popen(pager, 'w') do |fh| fh.write text end
+        ''
+      else
+        text
+      end
+    end
+  end
+
+  def legacy_applications
+    # The list of applications, less those that are duplicated as a face.
+    Puppet::Util::CommandLine.available_subcommands.reject do |appname|
+      Puppet::Face.face? appname.to_sym, :current or
+        # ...this is a nasty way to exclude non-applications. :(
+        %w{face_base indirection_base}.include? appname
+    end
+  end
+end

data/lib/puppet/face/node.rb

@@ -0,0 +1,43 @@
+require 'puppet/indirector/face'
+Puppet::Indirector::Face.define(:node, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "View and manage node definitions."
+  description <<-'EOT'
+    This subcommand interacts with node objects, which are used by Puppet to
+    build a catalog. A node object consists of the node's facts, environment,
+    node parameters (exposed in the parser as top-scope variables), and classes.
+  EOT
+
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
+  get_action(:save).description "Invalid for this subcommand."
+
+  find = get_action(:find)
+  find.summary "Retrieve a node object."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    A hash containing the node's `classes`, `environment`, `expiration`, `name`,
+    `parameters` (its facts, combined with any ENC-set parameters), and `time`.
+    When used from the Ruby API: a Puppet::Node object.
+
+    RENDERING ISSUES: Rendering as string and json are currently broken;
+    node objects can only be rendered as yaml.
+  EOT
+  find.examples <<-'EOT'
+    Retrieve an "empty" (no classes, no ENC-imposed parameters, and an
+    environment of "production") node:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml
+
+    Retrieve a node using the puppet master's configured ENC:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml
+
+    Retrieve the same node from the puppet master:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus rest --render-as yaml
+  EOT
+end

data/lib/puppet/face/parser.rb

@@ -0,0 +1,42 @@
+require 'puppet/face'
+require 'puppet/parser'
+
+Puppet::Face.define(:parser, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact directly with the parser."
+
+  action :validate do
+    summary "Validate the syntax of one or more Puppet manifests."
+    arguments "[<manifest>] [<manifest> ...]"
+    returns "Nothing, or the first syntax error encountered."
+    description <<-'EOT'
+      This action validates Puppet DSL syntax without compiling a catalog or
+      syncing any resources. If no manifest files are provided, it will
+      validate the default site manifest.
+    EOT
+    examples <<-'EOT'
+      Validate the default site manifest at /etc/puppet/manifests/site.pp:
+
+      $ puppet parser validate
+
+      Validate two arbitrary manifest files:
+
+      $ puppet parser validate init.pp vhost.pp
+    EOT
+    when_invoked do |*args|
+      args.pop
+      files = args
+      if files.empty?
+        files << Puppet[:manifest]
+        Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
+      end
+      files.each do |file|
+        Puppet[:manifest] = file
+        Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
+      end
+      nil
+    end
+  end
+end

data/lib/puppet/face/plugin.rb

@@ -0,0 +1,55 @@
+require 'puppet/face'
+Puppet::Face.define(:plugin, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact with the Puppet plugin system."
+  description <<-'EOT'
+    This subcommand provides network access to the puppet master's store of
+    plugins.
+
+    The puppet master serves Ruby code collected from the `lib` directories
+    of its modules. These plugins can be used on agent nodes to extend
+    Facter and implement custom types and providers. Plugins are normally
+    downloaded by puppet agent during the course of a run.
+  EOT
+
+  action :download do
+    summary "Download plugins from the puppet master."
+    description <<-'EOT'
+      Downloads plugins from the configured puppet master. Any plugins
+      downloaded in this way will be used in all subsequent Puppet activity.
+      This action modifies files on disk.
+    EOT
+    returns <<-'EOT'
+      A list of the files downloaded, or a confirmation that no files were
+      downloaded. When used from the Ruby API, this action returns an array of
+      the files downloaded, which will be empty if none were retrieved.
+    EOT
+    examples <<-'EOT'
+      Retrieve plugins from the puppet master:
+
+      $ puppet plugin download
+
+      Retrieve plugins from the puppet master (API example):
+
+      $ Puppet::Face[:plugin, '0.0.1'].download
+    EOT
+
+    when_invoked do |options|
+      require 'puppet/configurer/downloader'
+      Puppet::Configurer::Downloader.new("plugin",
+                                         Puppet[:plugindest],
+                                         Puppet[:pluginsource],
+                                         Puppet[:pluginsignore]).evaluate
+    end
+
+    when_rendering :console do |value|
+      if value.empty? then
+        "No plugins downloaded."
+      else
+        "Downloaded these plugins: #{value.join(', ')}"
+      end
+    end
+  end
+end

data/lib/puppet/face/report.rb

@@ -0,0 +1,56 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:report, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Create, display, and submit reports."
+
+  get_action(:find).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this face."
+  get_action(:destroy).summary "Invalid for this face."
+  save = get_action(:save)
+  save.summary "API only: submit a report."
+  save.arguments "<report>"
+  save.returns "Nothing."
+  save.examples <<-'EOT'
+    From the implementation of `puppet report submit` (API example):
+
+        begin
+          Puppet::Transaction::Report.indirection.terminus_class = :rest
+          Puppet::Face[:report, "0.0.1"].save(report)
+          Puppet.notice "Uploaded report for #{report.name}"
+        rescue => detail
+          puts detail.backtrace if Puppet[:trace]
+          Puppet.err "Could not send report: #{detail}"
+        end
+  EOT
+
+  action(:submit) do
+    summary "API only: submit a report with error handling."
+    description <<-'EOT'
+      API only: Submits a report to the puppet master. This action is
+      essentially a shortcut and wrapper for the `save` action with the `rest`
+      terminus, and provides additional details in the event of a failure.
+    EOT
+    arguments "<report>"
+    examples <<-'EOT'
+      From secret_agent.rb (API example):
+
+          # ...
+          report  = Puppet::Face[:catalog, '0.0.1'].apply
+          Puppet::Face[:report, '0.0.1'].submit(report)
+          return report
+    EOT
+    when_invoked do |report, options|
+      begin
+        Puppet::Transaction::Report.indirection.terminus_class = :rest
+        Puppet::Face[:report, "0.0.1"].save(report)
+        Puppet.notice "Uploaded report for #{report.name}"
+      rescue => detail
+        puts detail.backtrace if Puppet[:trace]
+        Puppet.err "Could not send report: #{detail}"
+      end
+    end
+  end
+end

data/lib/puppet/face/resource.rb

@@ -0,0 +1,53 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:resource, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "API only: interact directly with resources via the RAL."
+  description <<-'EOT'
+    API only: this face provides a Ruby API with functionality similar to the
+    puppet resource (or ralsh) subcommand.
+  EOT
+
+  get_action(:destroy).summary "Invalid for this subcommand."
+
+  search = get_action(:search)
+  search.summary "API only: get all resources of a single type."
+  search.arguments "<resource_type>"
+  search.returns "An array of Puppet::Resource objects."
+  search.examples <<-'EOT'
+    Get a list of all user resources (API example):
+
+        all_users = Puppet::Face[:resource, '0.0.1'].search("user")
+  EOT
+
+  find = get_action(:find)
+  find.summary "API only: get a single resource."
+  find.arguments "<type>/<title>"
+  find.returns "A Puppet::Resource object."
+  find.examples <<-'EOT'
+    Print information about a user on this system (API example):
+
+        puts Puppet::Face[:resource, '0.0.1'].find("user/luke").to_pson
+  EOT
+
+  save = get_action(:save)
+  save.summary "API only: create a new resource."
+  save.description <<-EOT
+    API only: creates a new resource.
+  EOT
+  save.arguments "<resource_object>"
+  save.returns "The same resource object passed as an argument."
+  save.examples <<-'EOT'
+    Create a new file resource (API example):
+
+        my_resource = Puppet::Resource.new(
+          :file,
+          "/tmp/demonstration",
+          :parameters => {:ensure => :present, :content => "some\nthing\n"}
+        )
+
+        Puppet::Face[:resource, '0.0.1'].save(my_resource)
+  EOT
+end

data/lib/puppet/face/resource_type.rb

@@ -0,0 +1,81 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:resource_type, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "View classes, defined resource types, and nodes from all manifests."
+  description <<-'EOT'
+    This subcommand reads information about the resource collections (classes,
+    nodes, and defined types) available in Puppet's site manifest and
+    modules.
+
+    It will eventually be extended to examine native resource types.
+  EOT
+  notes <<-'EOT'
+    The `find` and `search` actions return similar hashes of resource collection
+    info. These hashes will include the following four keys:
+
+    * `file` (a string)
+    * `name` (a string)
+    * `type` (<hostclass>, <definition>, or <node>)
+    * `line` (an integer)
+
+    They may optionally include the following keys:
+
+    * `parent`    (<name_of_resource_collection>)
+    * `arguments` (a hash of parameters and default values)
+    * `doc`       (a string)
+  EOT
+
+  # Action documentation overrides:
+  get_action(:save).summary = "Invalid for this subcommand."
+  get_action(:save).description "Invalid for this subcommand."
+  get_action(:destroy).summary = "Invalid for this subcommand."
+
+  find = get_action(:find)
+  find.summary "Retrieve info about a resource collection."
+  find.arguments "<collection_name>"
+  find.returns <<-'EOT'
+    A hash of info about the requested resource collection. When used from the
+    Ruby API: returns a Puppet::Resource::Type object.
+
+    RENDERING ISSUES: yaml and string output for this indirection are currently
+    unusable; use json instead.
+  EOT
+  find.notes <<-'EOT'
+    If two resource collections share the same name (e.g. you have both a node
+    and a class named "default"), `find` will only return one of them. This can
+    be worked around by using `search` instead.
+  EOT
+  find.examples <<-'EOT'
+    Retrieve info about a specific locally-defined class:
+
+    $ puppet resource_type find ntp::disabled
+
+    Retrieve info from the puppet master about a specific class:
+
+    $ puppet resource_type find ntp --terminus rest
+  EOT
+
+  search = get_action(:search)
+  search.summary "Search for collections matching a regular expression."
+  search.arguments "<regular_expression>"
+  search.returns <<-'EOT'
+    An array of hashes of resource collection info. When used from the Ruby API:
+    returns an array of Puppet::Resource::Type objects.
+
+    RENDERING ISSUES: yaml and string output for this indirection are currently
+    unusable; use json instead.
+  EOT
+  search.examples <<-'EOT'
+    Retrieve all classes, nodes, and defined types:
+
+    $ puppet resource_type search '.*'
+
+    Search for classes related to Nagios:
+
+    $ puppet resource_type search nagios
+  EOT
+
+end

data/lib/puppet/face/secret_agent.rb

@@ -0,0 +1,54 @@
+require 'puppet/face'
+
+Puppet::Face.define(:secret_agent, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Mimics puppet agent."
+  description <<-'EOT'
+    This subcommand currently functions as a proof of concept, demonstrating how
+    the Faces API exposes Puppet's internal systems to application logic;
+    compare the actual code for puppet agent. It will eventually replace puppet
+    agent entirely, and can provide a template for users who wish to implement
+    agent-like functionality with non-standard application logic.
+  EOT
+
+  action(:synchronize) do
+    default
+    summary "Run secret_agent once."
+    description <<-'EOT'
+      Mimics a single run of puppet agent. This action does not currently
+      daemonize, but can download plugins, submit facts, retrieve and apply a
+      catalog, and submit a report to the puppet master.
+    EOT
+    returns <<-'EOT'
+      Verbose logging from the completed run. When used from the Ruby API:
+      returns a Puppet::Transaction::Report object.
+    EOT
+    examples <<-'EOT'
+      Trigger a Puppet run with the configured puppet master:
+
+      $ puppet secret_agent
+    EOT
+    notes <<-'EOT'
+      This action requires that the puppet master's `auth.conf` file allow save
+      access to the `facts` REST terminus. Puppet agent does not use this
+      facility, and it is turned off by default. See
+      <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details.
+    EOT
+
+    when_invoked do |options|
+      Puppet::Face[:plugin, '0.0.1'].download
+
+      Puppet::Face[:facts, '0.0.1'].upload
+
+      Puppet::Face[:catalog, '0.0.1'].download
+
+      report  = Puppet::Face[:catalog, '0.0.1'].apply
+
+      Puppet::Face[:report, '0.0.1'].submit(report)
+
+      return report
+    end
+  end
+end