puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/type/augeas.rb

@@ -116,6 +116,10 @@ Puppet::Type.newtype(:augeas) do
     : Sets the node at `PATH` to `NULL`, creating it if needed
 
 
+    `clearm <PATH> <SUB>`
+    : Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
+
+
     `ins <LABEL> (before|after) <PATH>`
     : Inserts an empty node `LABEL` either before or after `PATH`.
 

data/lib/puppet/type/file/ensure.rb

@@ -68,7 +68,7 @@ module Puppet
       end
       if mode
         Puppet::Util.withumask(000) do
-          Dir.mkdir(@resource[:path], symbolic_mode_to_int(mode, 755, true))
+          Dir.mkdir(@resource[:path], symbolic_mode_to_int(mode, 0755, true))
         end
       else
         Dir.mkdir(@resource[:path])

data/lib/puppet/type/file/group.rb

@@ -1,7 +1,7 @@
 require 'puppet/util/posix'
 
-# Manage file group ownership.
 module Puppet
+  # Manage file group ownership.
   Puppet::Type.type(:file).newproperty(:group) do
     desc <<-EOT
       Which group should own the file.  Argument can be either a group

data/lib/puppet/type/file/mode.rb

@@ -1,6 +1,8 @@
 # Manage file modes.  This state should support different formats
 # for specification (e.g., u+rwx, or -0011), but for now only supports
 # specifying the full mode.
+
+
 module Puppet
   Puppet::Type.type(:file).newproperty(:mode) do
     require 'puppet/util/symbolic_file_mode'

data/lib/puppet/type/file/selcontext.rb

@@ -19,6 +19,7 @@
 #
 # See http://www.nsa.gov/selinux/ for complete docs on SELinux.
 
+
 module Puppet
   require 'puppet/util/selinux'
 

data/lib/puppet/type/group.rb

@@ -145,5 +145,17 @@ module Puppet
 
       defaultto false
     end
+
+    # This method has been exposed for puppet to manage users and groups of
+    # files in its settings and should not be considered available outside of
+    # puppet.
+    #
+    # (see Puppet::Settings#service_group_available?)
+    #
+    # @returns [Boolean] if the group exists on the system
+    # @api private
+    def exists?
+      provider.exists?
+    end
   end
 end

data/lib/puppet/type/mount.rb

@@ -15,7 +15,7 @@ module Puppet
     # call code when sync is called.
     newproperty(:ensure) do
       desc "Control what to do with this mount. Set this attribute to
-        `umounted` to make sure the filesystem is in the filesystem table
+        `unmounted` to make sure the filesystem is in the filesystem table
         but not mounted (if the filesystem is currently mounted, it will be
         unmounted).  Set it to `absent` to unmount (if necessary) and remove
         the filesystem from the fstab.  Set to `mounted` to add it to the
@@ -207,7 +207,7 @@ module Puppet
       newvalues(:true, :false)
       defaultto do
         case Facter.value(:operatingsystem)
-        when "FreeBSD", "Darwin", "AIX"
+        when "FreeBSD", "Darwin", "AIX", "DragonFly"
           false
         else
           true

data/lib/puppet/type/notify.rb

@@ -1,6 +1,6 @@
 #
 # Simple module for logging messages on the client-side
-#
+
 
 module Puppet
   newtype(:notify) do

data/lib/puppet/type/router.rb

@@ -1,6 +1,6 @@
 #
 # Manage a router abstraction
-#
+
 
 module Puppet
   newtype(:router) do

data/lib/puppet/type/service.rb

@@ -4,6 +4,7 @@
 # can only be managed through the interface of an init script
 # which is why they have a search path for initscripts and such
 
+
 module Puppet
 
   newtype(:service) do

data/lib/puppet/type/ssh_authorized_key.rb

@@ -27,7 +27,9 @@ module Puppet
     end
 
     newproperty(:key) do
-      desc "The key itself; generally a long string of hex digits."
+      desc "The public key itself; generally a long string of hex characters. The key attribute 
+      may not contain whitespace: Omit key headers (e.g. 'ssh-rsa') and key identifiers 
+      (e.g. 'joe@joescomputer.local') found in the public key file."
 
       validate do |value|
         raise Puppet::Error, "Key must not contain whitespace: #{value}" if value =~ /\s/

data/lib/puppet/type/user.rb

@@ -355,7 +355,14 @@ module Puppet
       autos
     end
 
-    # Provide an external hook.  Yay breaking out of APIs.
+    # This method has been exposed for puppet to manage users and groups of
+    # files in its settings and should not be considered available outside of
+    # puppet.
+    #
+    # (see Puppet::Settings#service_user_available?)
+    #
+    # @returns [Boolean] if the user exists on the system
+    # @api private
     def exists?
       provider.exists?
     end

data/lib/puppet/util.rb

@@ -185,6 +185,13 @@ module Util
     end
   end
 
+  # Resolve a path for an executable to the absolute path. This tries to behave
+  # in the same manner as the unix `which` command and uses the `PATH`
+  # environment variable.
+  #
+  # @api public
+  # @param bin [String] the name of the executable to find.
+  # @return [String] the absolute path to the found executable.
   def which(bin)
     if absolute_path?(bin)
       return bin if FileTest.file? bin and FileTest.executable? bin
@@ -489,6 +496,7 @@ module Util
   # Executes a block of code, wrapped with some special exception handling.  Causes the ruby interpreter to
   #  exit if the block throws an exception.
   #
+  # @api public
   # @param [String] message a message to log if the block fails
   # @param [Integer] code the exit code that the ruby interpreter should return if the block fails
   # @yield

data/lib/puppet/util/autoload.rb

@@ -19,13 +19,6 @@ class Puppet::Util::Autoload
       @gem_source ||= Puppet::Util::RubyGems::Source.new
     end
 
-    # List all loaded files.
-    def list_loaded
-      loaded.keys.sort { |a,b| a[0] <=> b[0] }.collect do |path, hash|
-        "#{path}: #{hash[:file]}"
-      end
-    end
-
     # Has a given path been loaded?  This is used for testing whether a
     # changed file should be loaded or just ignored.  This is only
     # used in network/client/master, when downloading plugins, to
@@ -205,7 +198,7 @@ class Puppet::Util::Autoload
   end
 
   def load(name, env=nil)
-    self.class.load_file(File.join(@path, name.to_s), env)
+    self.class.load_file(expand(name), env)
   end
 
   # Load all instances that we can.  This uses require, rather than load,
@@ -215,14 +208,18 @@ class Puppet::Util::Autoload
   end
 
   def loaded?(name)
-    self.class.loaded?(File.join(@path, name.to_s))
+    self.class.loaded?(expand(name))
   end
 
   def changed?(name)
-    self.class.changed?(File.join(@path, name.to_s))
+    self.class.changed?(expand(name))
   end
 
   def files_to_load
     self.class.files_to_load(@path)
   end
+
+  def expand(name)
+    ::File.join(@path, name.to_s)
+  end
 end

data/lib/puppet/util/classgen.rb

@@ -3,51 +3,66 @@ module Puppet
   class SubclassAlreadyDefined < Error; end
 end
 
+# This is a utility module for generating classes.
+# @api public
+#
 module Puppet::Util::ClassGen
   include Puppet::Util::MethodHelper
   include Puppet::Util
 
-  # Create a new subclass.  Valid options are:
-  # * <tt>:array</tt>: An array of existing classes.  If specified, the new
-  #   class is added to this array.
-  # * <tt>:attributes</tt>: A hash of attributes to set before the block is
-  #   evaluated.
-  # * <tt>:block</tt>: The block to evaluate in the context of the class.
-  #   You can also just pass the block normally, but it will still be evaluated
-  #   with <tt>class_eval</tt>.
-  # * <tt>:constant</tt>: What to set the constant as.  Defaults to the
-  #   capitalized name.
-  # * <tt>:hash</tt>: A hash of existing classes.  If specified, the new
-  #   class is added to this hash, and it is also used for overwrite tests.
-  # * <tt>:overwrite</tt>: Whether to overwrite an existing class.
-  # * <tt>:parent</tt>: The parent class for the generated class.  Defaults to
-  #   self.
-  # * <tt>:prefix</tt>: The constant prefix.  Default to nothing; if specified,
-  #   the capitalized name is appended and the result is set as the constant.
+  # Create a new class.
+  # @param name [String] the name of the generated class
+  # @param options [Hash] a hash of options
+  # @option options [Array<Class>] :array if specified, the generated class is appended to this array
+  # @option options [Hash<{String => Object}>] :attributes a hash that is applied to the generated class
+  #   by calling setter methods corresponding to this hash's keys/value pairs. This is done before the given
+  #   block is evaluated.
+  # @option options [Proc] :block a block to evaluate in the context of the class (this block can be provided
+  #   this way, or as a normal yield block).
+  # @option options [String] :constant (name with first letter capitalized) what to set the constant that references
+  #   the generated class to.
+  # @option options [Hash] :hash a hash of existing classes that this class is appended to (name => class).
+  #   This hash must be specified if the `:overwrite` option is set to `true`.
+  # @option options [Boolean] :overwrite whether an overwrite of an existing class should be allowed (requires also
+  #   defining the `:hash` with existing classes as the test is based on the content of this hash).
+  # @option options [Class] :parent (self) the parent class of the generated class.
+  # @option options [String] ('') :prefix the constant prefix to prepend to the constant name referencing the
+  #   generated class.
+  # @return [Class] the generated class
+  #
   def genclass(name, options = {}, &block)
     genthing(name, Class, options, block)
   end
 
-  # Create a new module.  Valid options are:
-  # * <tt>:array</tt>: An array of existing classes.  If specified, the new
-  #   class is added to this array.
-  # * <tt>:attributes</tt>: A hash of attributes to set before the block is
-  #   evaluated.
-  # * <tt>:block</tt>: The block to evaluate in the context of the class.
-  #   You can also just pass the block normally, but it will still be evaluated
-  #   with <tt>class_eval</tt>.
-  # * <tt>:constant</tt>: What to set the constant as.  Defaults to the
-  #   capitalized name.
-  # * <tt>:hash</tt>: A hash of existing classes.  If specified, the new
-  #   class is added to this hash, and it is also used for overwrite tests.
-  # * <tt>:overwrite</tt>: Whether to overwrite an existing class.
-  # * <tt>:prefix</tt>: The constant prefix.  Default to nothing; if specified,
+  # Creates a new module.  
+  # @param name [String] the name of the generated module
+  # @param optinos [Hash] hash with options
+  # @option options [Array<Class>] :array if specified, the generated class is appended to this array
+  # @option options [Hash<{String => Object}>] :attributes a hash that is applied to the generated class
+  #   by calling setter methods corresponding to this hash's keys/value pairs. This is done before the given
+  #   block is evaluated.
+  # @option options [Proc] :block a block to evaluate in the context of the class (this block can be provided
+  #   this way, or as a normal yield block).
+  # @option options [String] :constant (name with first letter capitalized) what to set the constant that references
+  #   the generated class to.
+  # @option options [Hash] :hash a hash of existing classes that this class is appended to (name => class).
+  #   This hash must be specified if the `:overwrite` option is set to `true`.
+  # @option options [Boolean] :overwrite whether an overwrite of an existing class should be allowed (requires also
+  #   defining the `:hash` with existing classes as the test is based on the content of this hash).
   #   the capitalized name is appended and the result is set as the constant.
+  # @option options [String] ('') :prefix the constant prefix to prepend to the constant name referencing the
+  #   generated class.
+  # @return [Module] the generated Module
   def genmodule(name, options = {}, &block)
     genthing(name, Module, options, block)
   end
 
-  # Remove an existing class
+  # Removes an existing class.
+  # @param name [String] the name of the class to remove
+  # @param options [Hash] options
+  # @option options [Hash] :hash a hash of existing classes from which the class to be removed is also removed
+  # @return [Boolean] whether the class was removed or not
+  #
   def rmclass(name, options)
     options = symbolize_options(options)
     const = genconst_string(name, options)
@@ -68,7 +83,8 @@ module Puppet::Util::ClassGen
 
   private
 
-  # Generate the constant to create or remove.
+  # Generates the constant to create or remove.
+  # @api private
   def genconst_string(name, options)
     unless const = options[:constant]
       prefix = options[:prefix] || ""
@@ -80,6 +96,7 @@ module Puppet::Util::ClassGen
 
   # This does the actual work of creating our class or module.  It's just a
   # slightly abstract version of genclass.
+  # @api private
   def genthing(name, type, options, block)
     options = symbolize_options(options)
 
@@ -128,6 +145,8 @@ module Puppet::Util::ClassGen
   # of which class hierarchy it polls for nested namespaces
   #
   # See http://redmine.ruby-lang.org/issues/show/1915
+  # @api private
+  #
   def is_constant_defined?(const)
     if ::RUBY_VERSION =~ /1.9/
       const_defined?(const, false)
@@ -137,6 +156,8 @@ module Puppet::Util::ClassGen
   end
 
   # Handle the setting and/or removing of the associated constant.
+  # @api private
+  #
   def handleclassconst(klass, name, options)
     const = genconst_string(name, options)
 
@@ -155,6 +176,8 @@ module Puppet::Util::ClassGen
   end
 
   # Perform the initializations on the class.
+  # @api private
+  #
   def initclass(klass, options)
     klass.initvars if klass.respond_to? :initvars
 
@@ -178,11 +201,13 @@ module Puppet::Util::ClassGen
   end
 
   # Convert our name to a constant.
+  # @api private
   def name2const(name)
     name.to_s.capitalize
   end
 
   # Store the class in the appropriate places.
+  # @api private
   def storeclass(klass, klassname, options)
     if hash = options[:hash]
       if hash.include? klassname and ! options[:overwrite]

data/lib/puppet/util/command_line.rb

@@ -10,125 +10,168 @@ if not defined? ::Bundler
 end
 
 require 'puppet'
+require 'puppet/util'
 require "puppet/util/plugins"
 require "puppet/util/rubygems"
 
 module Puppet
   module Util
+    # This is the main entry point for all puppet applications / faces; it
+    # is basically where the bootstrapping process / lifecycle of an app
+    # begins.
     class CommandLine
+      OPTION_OR_MANIFEST_FILE = /^-|\.pp$|\.rb$/
 
+      # @param zero [String] the name of the executable
+      # @param argv [Array<String>] the arguments passed on the command line
+      # @param stdin [IO] (unused)
       def initialize(zero = $0, argv = ARGV, stdin = STDIN)
-        @zero  = zero
-        @argv  = argv.dup
-        @stdin = stdin
-
-        @subcommand_name, @args = subcommand_and_args(@zero, @argv, @stdin)
+        @command = File.basename(zero, '.rb')
+        @argv = argv
         Puppet::Plugins.on_commandline_initialization(:command_line_object => self)
       end
 
-      attr :subcommand_name
-      attr :args
+      # @return [String] name of the subcommand is being executed
+      # @api public
+      def subcommand_name
+        return @command if @command != 'puppet'
 
-      def appdir
-        File.join('puppet', 'application')
+        if @argv.first =~ OPTION_OR_MANIFEST_FILE
+          nil
+        else
+          @argv.first
+        end
       end
 
+      # @return [Array<String>] the command line arguments being passed to the subcommand
+      # @api public
+      def args
+        return @argv if @command != 'puppet'
+
+        if subcommand_name.nil?
+          @argv
+        else
+          @argv[1..-1]
+        end
+      end
+
+      # @api private
+      # @deprecated
       def self.available_subcommands
-        # Eventually we probably want to replace this with a call to the
-        # autoloader.  however, at the moment the autoloader considers the
-        # module path when loading, and we don't want to allow apps / faces to
-        # load from there.  Once that is resolved, this should be replaced.
-        # --cprice 2012-03-06
-        #
-        # But we do want to load from rubygems --hightower
-        search_path = Puppet::Util::RubyGems::Source.new.directories + $LOAD_PATH
-        absolute_appdirs = search_path.uniq.collect do |x|
-          File.join(x,'puppet','application')
-        end.select{ |x| File.directory?(x) }
-        absolute_appdirs.inject([]) do |commands, dir|
-          commands + Dir[File.join(dir, '*.rb')].map{|fn| File.basename(fn, '.rb')}
-        end.uniq
+        Puppet.deprecation_warning('Puppet::Util::CommandLine.available_subcommands is deprecated; please use Puppet::Application.available_application_names instead.')
+        Puppet::Application.available_application_names
       end
+
       # available_subcommands was previously an instance method, not a class
       # method, and we have an unknown number of user-implemented applications
       # that depend on that behaviour.  Forwarding allows us to preserve a
       # backward compatible API. --daniel 2011-04-11
+      # @api private
+      # @deprecated
       def available_subcommands
-        self.class.available_subcommands
-      end
-
-      def require_application(application)
-        require File.join(appdir, application)
+        Puppet.deprecation_warning('Puppet::Util::CommandLine#available_subcommands is deprecated; please use Puppet::Application.available_application_names instead.')
+        Puppet::Application.available_application_names
       end
 
-      # This is the main entry point for all puppet applications / faces; it
-      # is basically where the bootstrapping process / lifecycle of an app
-      # begins.
+      # Run the puppet subcommand. If the subcommand is determined to be an
+      # external executable, this method will never return and the current
+      # process will be replaced via {Kernel#exec}.
+      #
+      # @return [void]
       def execute
-        # Build up our settings - we don't need that until after version check.
         Puppet::Util.exit_on_fail("intialize global default settings") do
-          Puppet.settings.initialize_global_settings(args)
+          Puppet.initialize_settings(args)
         end
 
-        # OK, now that we've processed the command line options and the config
-        # files, we should be able to say that we definitively know where the
-        # libdir is... which means that we can now look for our available
-        # applications / subcommands / faces.
+        find_subcommand.run
+      end
 
-        if subcommand_name and available_subcommands.include?(subcommand_name) then
-          require_application subcommand_name
-          # This will need to be cleaned up to do something that is not so
-          #  application-specific (i.e.. so that we can load faces).
-          #  Longer-term, use the autoloader.  See comments in
-          #  #available_subcommands method above.  --cprice 2012-03-06
-          app = Puppet::Application.find(subcommand_name).new(self)
-          Puppet::Plugins.on_application_initialization(:application_object => self)
+      # @api private
+      def external_subcommand
+        Puppet::Util.which("puppet-#{subcommand_name}")
+      end
 
-          app.run
-        elsif ! execute_external_subcommand then
-          unless subcommand_name.nil? then
-            puts "Error: Unknown Puppet subcommand '#{subcommand_name}'"
-          end
+      private
 
-          # If the user is just checking the version, print that and exit
-          if @argv.include? "--version" or @argv.include? "-V"
-            puts Puppet.version
-          else
-            puts "See 'puppet help' for help on available puppet subcommands"
-          end
+      def find_subcommand
+        if subcommand_name.nil?
+          NilSubcommand.new(self)
+        elsif Puppet::Application.available_application_names.include?(subcommand_name)
+          ApplicationSubcommand.new(subcommand_name, self)
+        elsif path_to_subcommand = external_subcommand
+          ExternalSubcommand.new(path_to_subcommand, self)
+        else
+          UnknownSubcommand.new(subcommand_name, self)
         end
       end
 
-      def execute_external_subcommand
-        external_command = "puppet-#{subcommand_name}"
+      # @api private
+      class ApplicationSubcommand
+        def initialize(subcommand_name, command_line)
+          @subcommand_name = subcommand_name
+          @command_line = command_line
+        end
+
+        def run
+          # For most applications, we want to be able to load code from the modulepath,
+          # such as apply, describe, resource, and faces.
+          # For agent, we only want to load pluginsync'ed code from libdir.
+          # For master, we shouldn't ever be loading per-enviroment code into the master's
+          # ruby process, but that requires fixing (#17210, #12173, #8750). So for now
+          # we try to restrict to only code that can be autoloaded from the node's
+          # environment.
+          if @subcommand_name != 'master' and @subcommand_name != 'agent'
+            Puppet::Node::Environment.new.each_plugin_directory do |dir|
+              $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
+            end
+          end
 
-        require 'puppet/util'
-        path_to_subcommand = Puppet::Util.which(external_command)
-        return false unless path_to_subcommand
+          app = Puppet::Application.find(@subcommand_name).new(@command_line)
+          Puppet::Plugins.on_application_initialization(:application_object => @command_line)
 
-        exec(path_to_subcommand, *args)
+          app.run
+        end
       end
 
-      private
+      # @api private
+      class ExternalSubcommand
+        def initialize(path_to_subcommand, command_line)
+          @path_to_subcommand = path_to_subcommand
+          @command_line = command_line
+        end
+
+        def run
+          Kernel.exec(@path_to_subcommand, *@command_line.args)
+        end
+      end
 
-      def subcommand_and_args(zero, argv, stdin)
-        zero = File.basename(zero, '.rb')
-
-        if zero == 'puppet'
-          case argv.first
-            # if they didn't pass a command, or passed a help flag, we will
-            # fall back to showing a usage message.  we no longer default to
-            # 'apply'
-            when nil, "--help", "-h", /^-|\.pp$|\.rb$/
-              [nil, argv]
-            else
-              [argv.first, argv[1..-1]]
+      # @api private
+      class NilSubcommand
+        def initialize(command_line)
+          @command_line = command_line
+        end
+
+        def run
+          if @command_line.args.include? "--version" or @command_line.args.include? "-V"
+            puts Puppet.version
+          else
+            puts "See 'puppet help' for help on available puppet subcommands"
           end
-        else
-          [zero, argv]
         end
       end
 
+      # @api private
+      class UnknownSubcommand < NilSubcommand
+        def initialize(subcommand_name, command_line)
+          @subcommand_name = subcommand_name
+          super(command_line)
+        end
+
+        def run
+          puts "Error: Unknown Puppet subcommand '#{@subcommand_name}'"
+          super
+        end
+      end
     end
   end
 end