puppet 2.6.18 → 2.7.1

data/lib/puppet/face/certificate.rb

@@ -0,0 +1,115 @@
+require 'puppet/indirector/face'
+require 'puppet/ssl/host'
+
+Puppet::Indirector::Face.define(:certificate, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Provide access to the CA for certificate management."
+  description <<-'EOT'
+    This subcommand interacts with a local or remote Puppet certificate
+    authority. Currently, its behavior is not a full superset of `puppet
+    cert`; specifically, it is unable to mimic puppet cert's "clean" option,
+    and its "generate" action submits a CSR rather than creating a
+    signed certificate.
+  EOT
+
+  option "--ca-location LOCATION" do
+    summary "Which certificate authority to use (local or remote)."
+    description <<-'EOT'
+      Whether to act on the local certificate authority or one provided by a
+      remote puppet master. Allowed values are 'local' and 'remote.'
+
+      This option is required.
+    EOT
+
+    before_action do |action, args, options|
+      Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
+    end
+  end
+
+  action :generate do
+    summary "Generate a new certificate signing request."
+    arguments "<host>"
+    returns "Nothing."
+    description <<-'EOT'
+      Generates and submits a certificate signing request (CSR) for the
+      specified host. This CSR will then have to be signed by a user
+      with the proper authorization on the certificate authority.
+
+      Puppet agent usually handles CSR submission automatically. This action is
+      primarily useful for requesting certificates for individual users and
+      external applications.
+    EOT
+    examples <<-'EOT'
+      Request a certificate for "somenode" from the site's CA:
+
+      $ puppet certificate generate somenode.puppetlabs.lan --ca-location remote
+    EOT
+
+    when_invoked do |name, options|
+      host = Puppet::SSL::Host.new(name)
+      host.generate_certificate_request
+      host.certificate_request.class.indirection.save(host.certificate_request)
+    end
+  end
+
+  action :list do
+    summary "List all certificate signing requests."
+    returns <<-'EOT'
+      An array of #inspect output from CSR objects. This output is
+      currently messy, but does contain the names of nodes requesting
+      certificates. This action returns #inspect strings even when used
+      from the Ruby API.
+    EOT
+
+    when_invoked do |options|
+      Puppet::SSL::Host.indirection.search("*", {
+        :for => :certificate_request,
+      }).map { |h| h.inspect }
+    end
+  end
+
+  action :sign do
+    summary "Sign a certificate signing request for HOST."
+    arguments "<host>"
+    returns <<-'EOT'
+      A string that appears to be (but isn't) an x509 certificate.
+    EOT
+    examples <<-'EOT'
+      Sign somenode.puppetlabs.lan's certificate:
+
+      $ puppet certificate sign somenode.puppetlabs.lan --ca-location remote
+    EOT
+
+    when_invoked do |name, options|
+      host = Puppet::SSL::Host.new(name)
+      host.desired_state = 'signed'
+      Puppet::SSL::Host.indirection.save(host)
+    end
+  end
+
+  # Indirector action doc overrides
+  find = get_action(:find)
+  find.summary "Retrieve a certificate."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    An x509 SSL certificate. You will usually want to render this as a
+    string (--render-as s).
+
+    Note that this action has a side effect of caching a copy of the
+    certificate in Puppet's `ssldir`.
+  EOT
+
+  destroy = get_action(:destroy)
+  destroy.summary "Delete a certificate."
+  destroy.arguments "<host>"
+  destroy.returns "Nothing."
+  destroy.description <<-'EOT'
+    Deletes a certificate. This action currently only works on the local CA.
+  EOT
+
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
+  get_action(:save).description "Invalid for this subcommand."
+end

data/lib/puppet/face/certificate_request.rb

@@ -0,0 +1,55 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Manage certificate requests."
+  description <<-'EOT'
+    This subcommand retrieves and submits certificate signing requests (CSRs).
+  EOT
+
+  # Per-action doc overrides
+  get_action(:destroy).summary "Invalid for this subcommand."
+
+  find = get_action(:find)
+  find.summary "Retrieve a single CSR."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    A single certificate request. When used from the Ruby API, returns a
+    Puppet::SSL::CertificateRequest object.
+
+    RENDERING ISSUES: In most cases, you will want to render this as a string
+    ('--render-as s').
+  EOT
+  find.examples <<-'EOT'
+    Retrieve a single CSR from the puppet master's CA:
+
+    $ puppet certificate_request find somenode.puppetlabs.lan --terminus rest
+  EOT
+
+  search = get_action(:search)
+  search.summary "Retrieve all outstanding CSRs."
+  search.arguments "<dummy_text>"
+  search.returns <<-'EOT'
+    A list of certificate requests; be sure to to render this as a string
+    ('--render-as s'). When used from the Ruby API, returns an array of
+    Puppet::SSL::CertificateRequest objects.
+  EOT
+  search.short_description <<-EOT
+    Retrieves all outstanding certificate signing requests. Due to a known bug,
+    this action requires a dummy search key, the content of which is irrelevant.
+  EOT
+  search.notes <<-EOT
+    Although this action always returns all CSRs, it requires a dummy search
+    key; this is a known bug.
+  EOT
+  search.examples <<-'EOT'
+    Retrieve all CSRs from the local CA (similar to 'puppet cert list'):
+
+    $ puppet certificate_request search x --terminus ca
+  EOT
+
+  get_action(:save).summary "API only: submit a certificate signing request."
+  get_action(:save).arguments "<x509_CSR>"
+end

data/lib/puppet/face/certificate_revocation_list.rb

@@ -0,0 +1,60 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Manage the list of revoked certificates."
+  description <<-'EOT'
+    This subcommand is primarily for retrieving the certificate revocation
+    list from the CA.
+  EOT
+
+  find = get_action(:find)
+  find.summary "Retrieve the certificate revocation list."
+  find.arguments "<dummy_text>"
+  find.returns <<-'EOT'
+    The certificate revocation list. When used from the Ruby API: returns an
+    OpenSSL::X509::CRL object.
+
+    RENDERING ISSUES: this should usually be rendered as a string
+    ('--render-as s').
+  EOT
+  find.short_description <<-EOT
+    Retrieves the certificate revocation list. Due to a known bug, this action
+    requires a dummy argument, the content of which is irrelevant.
+  EOT
+  find.notes <<-EOT
+    Although this action always returns the CRL from the specified terminus, it
+    requires a dummy argument; this is a known bug.
+  EOT
+  find.examples <<-'EXAMPLES'
+    Retrieve a copy of the puppet master's CRL:
+
+    $ puppet certificate_revocation_list find crl --terminus rest
+  EXAMPLES
+
+  destroy = get_action(:destroy)
+  destroy.summary "Delete the certificate revocation list."
+  destroy.arguments "<dummy_text>"
+  destroy.returns "Nothing."
+  destroy.description <<-'EOT'
+    Deletes the certificate revocation list. This cannot be done over REST, but
+    it is possible to delete the locally cached copy or the local CA's copy of
+    the CRL.
+  EOT
+  destroy.short_description <<-EOT
+    Deletes the certificate revocation list. This cannot be done over REST, but
+    it is possible to delete the locally cached copy or the local CA's copy of
+    the CRL. Due to a known bug, this action requires a dummy argument, the
+    content of which is irrelevant.
+  EOT
+  destroy.notes <<-EOT
+    Although this action always deletes the CRL from the specified terminus, it
+    requires a dummy argument; this is a known bug.
+  EOT
+
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
+  get_action(:save).description "Invalid for this subcommand."
+end

data/lib/puppet/face/config.rb

@@ -0,0 +1,45 @@
+require 'puppet/face'
+
+Puppet::Face.define(:config, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact with Puppet's configuration options."
+
+  action(:print) do
+    summary "Examine Puppet's current configuration settings."
+    arguments "(all | <setting> [<setting> ...]"
+    returns <<-'EOT'
+      A single value when called with one config setting, and a list of
+      settings and values when called with multiple options or "all."
+    EOT
+    description <<-'EOT'
+      Prints the value of a single configuration option or a list of
+      configuration options.
+
+      This action is an alternate interface to the information available with
+      `puppet <subcommand> --configprint`.
+    EOT
+    notes <<-'EOT'
+      By default, this action reads the configuration in agent mode.
+      Use the '--mode' and '--environment' flags to examine other
+      configuration domains.
+    EOT
+    examples <<-'EOT'
+      Get puppet's runfile directory:
+
+      $ puppet config print rundir
+
+      Get a list of important directories from the master's config:
+
+      $ puppet config print all --mode master | grep -E "(path|dir)"
+    EOT
+
+    when_invoked do |*args|
+      options = args.pop
+      Puppet.settings[:configprint] = args.join(",")
+      Puppet.settings.print_config_options
+      nil
+    end
+  end
+end

data/lib/puppet/face/facts.rb

@@ -0,0 +1,81 @@
+require 'puppet/indirector/face'
+require 'puppet/node/facts'
+
+Puppet::Indirector::Face.define(:facts, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Retrieve and store facts."
+  description <<-'EOT'
+    This subcommand manages facts, which are collections of normalized system
+    information used by Puppet. It can read facts directly from the local system
+    (with the default `facter` terminus), look up facts reported by other
+    systems, and submit facts to the puppet master.
+
+    When used with the `rest` terminus, this subcommand is essentially a front-end
+    to the inventory service REST API. See the inventory service documentation at
+    <http://docs.puppetlabs.com/guides/inventory_service.html> for more detail.
+  EOT
+
+  find = get_action(:find)
+  find.summary "Retrieve a node's facts."
+  find.arguments "<node_certname>"
+  find.returns <<-'EOT'
+    A hash containing some metadata and (under the "values" key) the set
+    of facts for the requested node. When used from the Ruby API: A
+    Puppet::Node::Facts object.
+
+    RENDERING ISSUES: Facts cannot currently be rendered as a string; use yaml
+    or json.
+  EOT
+  find.notes <<-'EOT'
+    When using the `facter` terminus, the host argument is ignored.
+  EOT
+  find.examples <<-'EOT'
+    Get facts from the local system:
+
+    $ puppet facts find x
+
+    Ask the puppet master for facts for an arbitrary node:
+
+    $ puppet facts find somenode.puppetlabs.lan --terminus rest
+
+    Query a DB-backed inventory directly (bypassing the REST API):
+
+    $ puppet facts find somenode.puppetlabs.lan --terminus inventory_active_record --mode master
+  EOT
+
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
+
+  action(:upload) do
+    summary "Upload local facts to the puppet master."
+    description <<-'EOT'
+      Reads facts from the local system using the `facter` terminus, then
+      saves the returned facts using the rest terminus.
+    EOT
+    returns "Nothing."
+    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
+    examples <<-'EOT'
+      Upload facts:
+
+      $ puppet facts upload
+    EOT
+
+    render_as :yaml
+
+    when_invoked do |options|
+      Puppet::Node::Facts.indirection.terminus_class = :facter
+      facts = Puppet::Node::Facts.indirection.find(Puppet[:certname])
+      Puppet::Node::Facts.indirection.terminus_class = :rest
+      Puppet::Node::Facts.indirection.save(facts)
+      Puppet.notice "Uploaded facts for '#{Puppet[:certname]}'"
+      nil
+    end
+  end
+end

data/lib/puppet/face/file.rb

@@ -0,0 +1,47 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:file, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Retrieve and store files in a filebucket"
+  description <<-'EOT'
+    This subcommand interacts with objects stored in a local or remote
+    filebucket. File objects are accessed by their MD5 sum; see the
+    examples for the relevant syntax.
+  EOT
+  notes <<-'EOT'
+    To retrieve the unmunged contents of a file, you must call find with
+    --render-as s. Rendering as yaml will return a hash of metadata
+    about the file, including its contents.
+
+    This subcommand does not interact with the `clientbucketdir` (the default
+    local filebucket for puppet agent); it interacts with the primary
+    "master"-type filebucket located in the `bucketdir`. If you wish to
+    interact with puppet agent's default filebucket, you'll need to set
+    the <--bucketdir> option appropriately when invoking actions.
+  EOT
+
+  file = get_action(:find)
+  file.summary "Retrieve a file from the filebucket."
+  file.arguments "md5/<md5sum>"
+  file.returns <<-'EOT'
+    The file object with the specified checksum.
+
+    RENDERING ISSUES: Rendering as a string returns the contents of the
+    file object; rendering as yaml returns a hash of metadata about said
+    file, including but not limited to its contents. Rendering as json
+    is currently broken, and returns a hash containing only the contents
+    of the file.
+  EOT
+  file.examples <<-'EOT'
+    Retrieve the contents of a file:
+
+    $ puppet file find md5/9aedba7f413c97dc65895b1cd9421f2c --render-as s
+  EOT
+
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:destroy).summary "Invalid for this subcommand."
+
+  set_indirection_name :file_bucket_file
+end

data/lib/puppet/face/file/download.rb

@@ -0,0 +1,54 @@
+# Download a specified file into the local filebucket.
+Puppet::Face.define(:file, '0.0.1') do
+  action :download do |*args|
+    summary "Download a file into the local filebucket."
+    arguments "( {md5}<checksum> | <puppet_url> )"
+    returns "Nothing."
+    description <<-EOT
+      Downloads a file from the puppet master's filebucket and duplicates it in
+      the local filebucket. This action's checksum syntax differs from `find`'s,
+      and it can accept a <puppet:///> URL.
+    EOT
+    examples <<-'EOT'
+      Download a file by URL:
+
+      $ puppet file download puppet:///modules/editors/vim/.vimrc
+
+      Download a file by MD5 sum:
+
+      $ puppet file download {md5}8f798d4e754db0ac89186bbaeaf0af18
+    EOT
+
+    when_invoked do |sum, options|
+      if sum =~ /^puppet:\/\// # it's a puppet url
+        require 'puppet/file_serving'
+        require 'puppet/file_serving/content'
+        raise "Could not find metadata for #{sum}" unless content = Puppet::FileServing::Content.indirection.find(sum)
+        file = Puppet::FileBucket::File.new(content.content)
+      else
+        tester = Object.new
+        tester.extend(Puppet::Util::Checksums)
+
+        type    = tester.sumtype(sum)
+        sumdata = tester.sumdata(sum)
+
+        key = "#{type}/#{sumdata}"
+
+        Puppet::FileBucket::File.indirection.terminus_class = :file
+        if Puppet::FileBucket::File.indirection.find(key)
+          Puppet.info "Content for '#{sum}' already exists"
+          return
+        end
+
+        Puppet::FileBucket::File.indirection.terminus_class = :rest
+        raise "Could not download content for '#{sum}'" unless file = Puppet::FileBucket::File.indirection.find(key)
+      end
+
+
+      Puppet::FileBucket::File.indirection.terminus_class = :file
+      Puppet.notice "Saved #{sum} to filebucket"
+      Puppet::FileBucket::File.indirection.save file
+      return nil
+    end
+  end
+end