fingerpuppet 0.0.1 → 0.0.2

data/README.md

@@ -1,26 +1,53 @@
-Usage : fingerpuppet <commandstring>
+Introduction
+============
 
-        Steps for using the API:
-            1:) fingerpuppet --init --certname my.cert.name --server my.server.name
-                    Builds the config file
-                    Generates the certificate and CSR
-                    Submits the CSR to the Puppetmaster
+`fingerpuppet` is a simple library and commandline tool to interact with Puppet's REST API
+without needing to have Puppet itself installed. This may be integrated, for example,
+into a provisioning tool to allow your provisioning process to remotely sign certificates
+of newly built systems. Alternatively, you could use it to request known facts about
+a node from your Puppet Master, or even to request a catalog for a node to, for example,
+perform acceptance testing against a new version of Puppet before upgrading your
+production master.
 
-            2:) On puppetmaster: puppet cert sign my.cert.name
+Limitations
+============
 
-            3:) restapi.rb --install
-                    Downloads the signed certificate and installs it
+This is still in early development. Features may not work completely as advertised, and will
+certainly be less polished than an established product. Pull requests are welcome!
 
-            4:) ...
 
-            5:) Profit!
+Usage
+============
 
-        Your Puppetmaster must be configured to allow requests other than certificate requests.
-        See http://docs.puppetlabs.com/guides/rest_auth_conf.html for more information.
+`fingerpuppet [commandstring]`
 
-        The certname can be specified with --certname or with optional CERTNAME argument to many options.
+Steps for using the API with fingerpuppet:
 
-        You may want to use the '-dcn' options to print the cURL equivalent command.
+1. `fingerpuppet --init --certname my.cert.name --server my.server.name`
+    * Builds the config file
+    * Generates the certificate and CSR
+    * Submits the CSR to the Puppetmaster
+2. On puppetmaster: `puppet cert sign my.cert.name`
+3. `fingerpuppet --install`
+    * Downloads the signed certificate and installs it
+4. ...
+5. Profit!
+
+Your Puppetmaster must be configured to allow requests other than certificate requests.
+See [http://docs.puppetlabs.com/guides/rest_auth_conf.html](http://docs.puppetlabs.com/guides/rest_auth_conf.html) for more information.
+
+For example, you could add the stanza below as one of the first rules in `auth.conf` to
+allow a single authenticated provisioning system complete access to all endpoints.
+
+    # Allow the provisioner unfettered access to any endpoint
+    path /
+    auth yes
+    allow provision.mycompany.com
+
+
+The certname can be specified with `--certname` or with optional `CERTNAME` argument to many options.
+
+You may want to use the `-dcn` options to print the cURL equivalent command.
 
     -d, --debug                      runs in debug mode
     -h, --help                       Displays this help
@@ -46,7 +73,7 @@ Usage : fingerpuppet <commandstring>
         --certificate [CERTNAME]     Retrieve the certificate for a given certname or 'ca'.
         --cert_status [CERTNAME]     Retrieve the certificate status for a given certname. Set the status by using --state.
         --cert_revocation_list       Retrieve and display the certifiacte revocation list from the master.
-        --sign [CERTNAME]            Instruct the Puppetmaster to sign a certificate. Requires significate privileges in auth.conf.
+        --sign [CERTNAME]            Instruct the Puppetmaster to sign a certificate. Requires significant privileges in auth.conf.
 
         --file_metadata PATH         Retrieve the metadata for a file.
         --getfile PATH               Download a file from the Puppetmaster. Save to --file or output on stdout.
@@ -54,3 +81,35 @@ Usage : fingerpuppet <commandstring>
         --resource RESOURCE          Returns a list of resources (e.g. user) or information about a resource (e.g. 'user/elvis')
         --report [CERTNAME]          Sends a YAML report to the Puppetmaster. Requires --file or --state.
         --status                     Check to make sure the Puppetmaster is alive and well.
+
+Contact
+=======
+
+* Author: Ben Ford
+* Email: ben.ford@puppetlabs.com
+* Twitter: @binford2k
+* IRC (Freenode): binford2k
+
+License
+=======
+
+Copyright (c) 2012 Puppet Labs, info@puppetlabs.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/fingerpuppet

@@ -15,7 +15,7 @@ optparse = OptionParser.new { |opts|
 
             2:) On puppetmaster: puppet cert sign my.cert.name
 
-            3:) restapi.rb --install
+            3:) fingerpuppet --install
                     Downloads the signed certificate and installs it
 
             4:) ...
@@ -30,7 +30,7 @@ optparse = OptionParser.new { |opts|
         You may want to use the '-dcn' options to print the cURL equivalent command.
 
 "
- 
+
     options[:show]=false
     opts.on("-d", "--debug", "runs in debug mode") do
         options[:debug] = true
@@ -193,7 +193,7 @@ begin
         when 'delete'
             restAPI.delete(options[:certname])
         when 'file_metadata'
-            restAPI.file_metadata(options[:argument])           
+            restAPI.file_metadata(options[:argument])
         when 'getfile'
             restAPI.getfile(options[:argument])
         when 'certificate'
@@ -210,7 +210,8 @@ begin
             restAPI.report(options[:certname], options[:filename], options[:state])
         else
             puts 'Use -h/--help for usage documentation.'
-    end     
+    end
 rescue Exception => e
     puts e
 end
+

data/lib/fingerpuppet/restapi.rb

@@ -4,14 +4,14 @@ require "net/https"
 module Fingerpuppet
   class RestAPI
       attr_accessor :server, :certname
-  
+
       def initialize( options={} )
           @debug = options[:debug]
           @curl = options[:curl]
           @nop = options[:nop]
           @output = options[:output]
           @configdir = File.expand_path('~/.fingerpuppet')
-  
+
           begin
               config = YAML.load_file("#{@configdir}/config.yaml")
               @server   = config['server']
@@ -20,19 +20,19 @@ module Fingerpuppet
               puts 'Initializing API...'
           end
       end
-  
+
       # a helper that allows one to use either commandline curl or Net::HTTP
       # this is useful mostly with -dcn to just print out the curl commandline
       # you would use to accomplish what you're trying to do
       def command( opts={} )
           # this allows a global @output var, but to also override that per call
           opts[:output] ||= @output
-  
+
           if @curl
               curl(opts)
           else
               data = rest(opts)
-  
+
               if opts[:output]
                   save(opts[:output], data)
               else
@@ -42,36 +42,36 @@ module Fingerpuppet
               end
           end
       end
-  
+
       def save(path, data)
           file = File.new(path, 'w')
           file.syswrite(data)
           file.close
       end
-  
+
       def rest( opts={} )
           opts[:type] ||= 'yaml'
           uri = "/production/#{opts[:action]}/#{opts[:argument]}"
-  
+
           http = Net::HTTP.new(@server, 8140)
           http.use_ssl = true
-  
+
           unless opts[:noauth]
               http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-  
+
               store = OpenSSL::X509::Store.new
               store.add_cert(OpenSSL::X509::Certificate.new(File.read("#{@configdir}/ca_crt.pem")))
               http.cert_store = store
-  
+
               http.key = OpenSSL::PKey::RSA.new(File.read("#{@configdir}/#{@certname}.key"))
               http.cert = OpenSSL::X509::Certificate.new(File.read("#{@configdir}/#{@certname}.pem"))
           end
-  
+
           case opts[:method]
               when 'PUT'
                   request = Net::HTTP::Put.new(uri)
                   request["Content-Type"] = "text/#{opts[:type]}"
-  
+
                   if opts[:file]
                       # set the body to the binary contents of :file
                       file = File.open(opts[:file], 'rb')
@@ -80,7 +80,7 @@ module Fingerpuppet
                       # set the body to the string value of :data
                       request.body = opts[:data]
                   end
-  
+
               when 'DELETE'
                   request = Net::HTTP::Delete.new(uri)
               when 'HEAD'
@@ -89,44 +89,44 @@ module Fingerpuppet
                   # default to a GET request
                   request = Net::HTTP::Get.new(uri)
           end
-  
+
           request["Accept"] = opts[:type]
-  
+
           if @debug
               puts '------ HTTP Request ------'
               puts request.to_yaml
               puts '--------------------------'
           end
-  
+
           return @nop ? '' : http.request(request).body
       end
-  
+
       #def command(action, argument='', method='GET', type='yaml', output=false, file=false, data=false)
       def curl( opts={} )
           opts[:type] ||= 'yaml'
-  
+
           if opts[:noauth]
               auth = '-k '
           else
               auth = "--cert #{@configdir}/#{@certname}.pem --key #{@configdir}/#{@certname}.key --cacert #{@configdir}/ca_crt.pem"
           end
-  
+
           output = opts[:output] ? "-o #{opts[:output]}" : ''
           header = "-H 'Accept: #{opts[:type]}'"
-          
+
           case opts[:method]
               when 'PUT'
                   methodstr = '-X PUT'
                   header = "-H 'Content-Type: text/#{opts[:type]}'"
-  
+
                   if opts[:file]
                       filestr   = "--data-binary @#{opts[:file]}"
                   end
-  
+
                   if opts[:data]
                       datastr   = "--data '#{opts[:data]}'"
                   end
-  
+
               when 'DELETE'
                   methodstr = '-X DELETE'
               when 'HEAD'
@@ -135,7 +135,7 @@ module Fingerpuppet
                   # default to a GET request
                   methodstr = ''
           end
-  
+
           uri = "https://#{@server}:8140/production/#{opts[:action]}/#{opts[:argument]}"
           cmd = "curl #{auth} #{methodstr} #{output} #{filestr} #{datastr} #{header} \"#{uri}\"" #quoted uri for fact ampersands
           if @debug
@@ -147,50 +147,50 @@ module Fingerpuppet
               puts # newline after curl output
           end
       end
-  
+
       def init(certname, server)
           if certname == nil || server == nil
               puts "Must set server and certname to initialize API"
               exit
           end
-  
+
           @certname = certname
           @server = server
-  
+
           if File::directory?( @configdir )
               require 'fileutils'
               FileUtils.rm_rf( @configdir )
           end
-  
+
           Dir.mkdir( @configdir )
           configfile = File.new("#{@configdir}/config.yaml", 'w')
               configfile.syswrite("version: 0.1\n")
               configfile.syswrite("certname: #{@certname}\n")
               configfile.syswrite("server: #{@server}\n")
           configfile.close
-  
+
           begin
               if not system("openssl genrsa -out #{@configdir}/#{@certname}.key 1024")
                   raise StandardError, 'Certificate generation failed.'
               end
-  
+
               if not system("openssl req -new -key #{@configdir}/#{@certname}.key -subj '/CN=#{@certname}' -out #{@configdir}/#{@certname}.csr")
                   raise StandardError, 'CSR generation failed.'
               end
-  
+
               self.command( { :action => 'certificate_request',
                               :argument => @certname,
                               :file => "#{@configdir}/#{@certname}.csr",
                               :type => 'plain',
                               :method => 'PUT',
                               :noauth => true } )
-  
+
               puts "CSR submitted. Now go sign it on the server and rerun this with --install."
           rescue Exception => e
               puts "Failure: #{e.message}"
           end
       end
-  
+
       def install
           begin
               self.command( { :action => 'certificate',
@@ -198,134 +198,134 @@ module Fingerpuppet
                               :output => "#{@configdir}/#{@certname}.pem",
                               :type => 's',
                               :noauth => true } )
-  
+
               self.command( { :action => 'certificate',
                               :argument => 'ca',
                               :output => "#{@configdir}/ca_crt.pem",
                               :type => 's',
                               :noauth => true } )
-  
+
               puts "Certificate installed. API ready for use."
           rescue Exception => e
               puts "Failure: #{e.message}"
           end
       end
-  
+
       def catalog
-          self.command( { :action => 'catalog', 
+          self.command( { :action => 'catalog',
                           :argument => @certname } )
       end
-  
+
       def status
-          self.command( { :action => 'status', 
+          self.command( { :action => 'status',
                           :argument => 'no_key' } )
       end
-  
+
       def facts(node)
-          self.command( { :action => 'facts', 
+          self.command( { :action => 'facts',
                           :argument => node } )
       end
-  
+
       def search(query)
           query.map!{ |item| "facts.#{item}"}
-          self.command( { :action => 'facts_search', 
+          self.command( { :action => 'facts_search',
                           :argument => "search?#{query.join('&')}" } )
       end
-  
+
       def node(node)
-          self.command( { :action => 'node', 
+          self.command( { :action => 'node',
                           :argument => node } )
       end
-  
+
       def insert(node, path)
-          self.command( { :action => 'facts', 
-                          :argument => node, 
-                          :method => 'PUT', 
+          self.command( { :action => 'facts',
+                          :argument => node,
+                          :method => 'PUT',
                           :file => path } )
       end
-  
+
       def file_metadata(path)
           self.command( { :action => 'file_content',
                           :argument => path,
                           :type => 'yaml' } )
       end
-  
+
       def getfile(path)
           self.command( { :action => 'file_content',
                           :argument => path,
                           :type => 'raw' } )
       end
-  
+
       def delete(node)
           self.certificate_status(node, 'revoked')
-          self.command( { :action => 'certificate_status', 
-                          :argument => node, 
-                          :method => 'DELETE', 
+          self.command( { :action => 'certificate_status',
+                          :argument => node,
+                          :method => 'DELETE',
                           :type => 'pson' } )
       end
-  
+
       def certificate(node)
-          self.command( { :action => 'certificate', 
-                          :argument => node, 
+          self.command( { :action => 'certificate',
+                          :argument => node,
                           :type => 's' } )
       end
-  
+
       def sign(node)
-          self.command( { :action => 'certificate_status', 
-                          :argument => node, 
-                          :method => 'PUT', 
+          self.command( { :action => 'certificate_status',
+                          :argument => node,
+                          :method => 'PUT',
                           :type => 'pson',
-                          :noauth => true, 
                           :data => "{\"desired_state\":\"signed\"}" } )
       end
-  
+
       def certificate_revocation_list
-          self.command( { :action => 'certificate_revocation_list', 
-                          :argument => 'ca', 
+          self.command( { :action => 'certificate_revocation_list',
+                          :argument => 'ca',
                           :type => 's' } )
       end
-  
+
       def certificate_status(node, state=nil)
           if node == nil
-              self.command( { :action => 'certificate_statuses', 
-                              :action => 'no_key', 
+              self.command( { :action => 'certificate_statuses',
+                              :action => 'no_key',
                               :type => 'pson' } )
           elsif state == nil
-              self.command( { :action => 'certificate_status', 
-                              :argument => node, 
+              self.command( { :action => 'certificate_status',
+                              :argument => node,
                               :type => 'pson' } )
           else
-              self.command( { :action => 'certificate_status', 
-                              :argument => node, 
-                              :method => 'PUT', 
-                              :type => 'pson', 
+              self.command( { :action => 'certificate_status',
+                              :argument => node,
+                              :method => 'PUT',
+                              :type => 'pson',
                               :data => "{\"desired_state\":\"#{state}\"}" } )
           end
       end
-  
+
       def resource(resource)
-          self.command( { :action => 'resource', 
+          self.command( { :action => 'resource',
                           :argument => resource } )
       end
-  
+
       def report(node, file, data=nil)
           if data
-              self.command( { :action => 'report', 
-                              :argument => node, 
-                              :method => 'PUT', 
+              self.command( { :action => 'report',
+                              :argument => node,
+                              :method => 'PUT',
                               :data => data } )
           else
-              self.command( { :action => 'report', 
-                              :argument => node, 
-                              :method => 'PUT', 
+              self.command( { :action => 'report',
+                              :argument => node,
+                              :method => 'PUT',
                               :file => file } )
           end
       end
-  
+
       def debug
           puts "@configdir: #{@configdir}"
           puts "   @server: #{@server}"
           puts " @certname: #{@certname}"
       end
   end
-end
+end
+

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Ben Ford
@@ -14,11 +14,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-03-28 00:00:00 -07:00
+date: 2013-03-28 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: "  A simple library and tool to interact with Puppet's REST API without needing Puppet itself installed.\n"
+description: |
+  `fingerpuppet` is a simple library and commandline tool to interact with Puppet's REST API
+  without needing to have Puppet itself installed. This may be integrated, for example,
+  into a provisioning tool to allow your provisioning process to remotely sign certificates
+  of newly built systems. Alternatively, you could use it to request known facts about
+  a node from your Puppet Master, or even to request a catalog for a node to, for example,
+  perform acceptance testing against a new version of Puppet before upgrading your
+  production master.
+
 email: binford2k@gmail.com
 executables: 
 - fingerpuppet