puppet 2.7.11 → 2.7.12

data/lib/puppet/type/k5login.rb

@@ -19,7 +19,7 @@ Puppet::Type.newtype(:k5login) do
     desc "The path to the `.k5login` file to manage.  Must be fully qualified."
 
     validate do |value|
-      unless value =~ /^#{File::SEPARATOR}/
+      unless absolute_path?(value)
         raise Puppet::Error, "File paths must be fully qualified."
       end
     end

data/lib/puppet/type/package.rb

@@ -115,7 +115,6 @@ module Puppet
       # Override the parent method, because we've got all kinds of
       # funky definitions of 'in sync'.
       def insync?(is)
-        @latest ||= nil
         @lateststamp ||= (Time.now.to_i - 1000)
         # Iterate across all of the should values, and see how they
         # turn out.
@@ -156,7 +155,9 @@ module Puppet
             return true if is == :absent or is == :purged
           when :purged
             return true if is == :purged
-          when is
+          # this handles version number matches and
+          # supports providers that can have multiple versions installed
+          when *Array(is)
             return true
           end
         }
@@ -301,8 +302,25 @@ module Puppet
     end
 
     newparam(:install_options, :required_features => :install_options) do
-      desc "A hash of options to be handled by the provider when
-        installing a package."
+      desc <<-EOT
+        A hash of additional options to pass when installing a package. These
+        options are package-specific, and should be documented by the software
+        vendor. The most commonly implemented option is `INSTALLDIR`:
+
+            package { 'mysql':
+              ensure          => installed,
+              provider        => 'msi',
+              source          => 'N:/packages/mysql-5.5.16-winx64.msi',
+              install_options => { 'INSTALLDIR' => 'C:\\mysql-5.5' },
+            }
+
+        Since these options are passed verbatim to `msiexec`, any file paths
+        specified in `install_options` should use a backslash as the separator
+        character rather than a forward slash. This is the **only** place in Puppet
+        where backslash separators should be used. Note that backslashes in
+        double-quoted strings _must_ be double-escaped and backslashes
+        in single-quoted strings _may_ be double-escaped.
+      EOT
     end
 
     autorequire(:file) do
@@ -313,10 +331,8 @@ module Puppet
         end
       }
 
-      if source = self[:source]
-        if source =~ /^#{File::SEPARATOR}/
-          autos << source
-        end
+      if source = self[:source] and absolute_path?(source)
+        autos << source
       end
       autos
     end

data/lib/puppet/type/scheduled_task.rb

@@ -3,98 +3,16 @@ require 'puppet/util'
 Puppet::Type.newtype(:scheduled_task) do
   include Puppet::Util
 
-  @doc = "Installs and manages Windows Scheduled Tasks.  All fields
-    except the name, command, and start_time are optional; specifying
-    no repetition parameters will result in a task that runs once on
-    the start date.
-
-    Examples:
-
-      # Create a task that will fire on August 31st, 2011 at 8am in
-      # the system's time-zone.
-      scheduled_task { 'One-shot task':
-        ensure    => present,
-        enabled   => true,
-        command   => 'C:\path\to\command.exe',
-        arguments => '/flags /to /pass',
-        trigger   => {
-          schedule   => once,
-          start_date => '2011-08-31', # Defaults to 'today'
-          start_time => '08:00',      # Must be specified
-        }
-      }
-
-      # Create a task that will fire every other day at 8am in the
-      # system's time-zone, starting August 31st, 2011.
-      scheduled_task { 'Daily task':
-        ensure    => present,
-        enabled   => true,
-        command   => 'C:\path\to\command.exe',
-        arguments => '/flags /to /pass',
-        trigger   => {
-          schedule   => daily,
-          every      => 2             # Defaults to 1
-          start_date => '2011-08-31', # Defaults to 'today'
-          start_time => '08:00',      # Must be specified
-        }
-      }
-
-      # Create a task that will fire at 8am Monday every third week,
-      # starting after August 31st, 2011.
-      scheduled_task { 'Weekly task':
-        ensure    => present,
-        enabled   => true,
-        command   => 'C:\path\to\command.exe',
-        arguments => '/flags /to /pass',
-        trigger   => {
-          schedule    => weekly,
-          every       => 3,           # Defaults to 1
-          start_date  => '2011-08-31' # Defaults to 'today'
-          start_time  => '08:00',     # Must be specified
-          day_of_week => [mon],       # Defaults to all
-        }
-      }
-
-      # Create a task that will fire at 8am on the 1st, 15th, and last
-      # day of the month in January, March, May, July, September, and
-      # November starting August 31st, 2011.
-      scheduled_task { 'Monthly date task':
-        ensure    => present,
-        enabled   => true,
-        command   => 'C:\path\to\command.exe',
-        arguments => '/flags /to /pass',
-        trigger   => {
-          schedule   => monthly,
-          start_date => '2011-08-31',   # Defaults to 'today'
-          start_time => '08:00',        # Must be specified
-          months     => [1,3,5,7,9,11], # Defaults to all
-          on         => [1, 15, last],  # Must be specified
-        }
-      }
-
-      # Create a task that will fire at 8am on the first Monday of the
-      # month for January, March, and May, after August 31st, 2011.
-      scheduled_task { 'Monthly day of week task':
-        enabled   => true,
-        ensure    => present,
-        command   => 'C:\path\to\command.exe',
-        arguments => '/flags /to /pass',
-        trigger   => {
-          schedule         => monthly,
-          start_date       => '2011-08-31', # Defaults to 'today'
-          start_time       => '08:00',      # Must be specified
-          months           => [1,3,5],      # Defaults to all
-          which_occurrence => first,        # Must be specified
-          day_of_week      => [mon],        # Must be specified
-        }
-      }"
+  @doc = "Installs and manages Windows Scheduled Tasks.  All attributes
+    except `name`, `command`, and `trigger` are optional; see the description
+    of the `trigger` attribute for details on setting schedules."
 
   ensurable
 
   newproperty(:enabled) do
-    desc "Whether the triggers for this task are enabled.  This only
-      supports enabling or disabling all of the triggers for a task,
-      not enabling or disabling them on an individual basis."
+    desc "Whether the triggers for this task should be enabled. This attribute
+      affects every trigger for the task; triggers cannot be enabled or
+      disabled individually."
 
     newvalue(:true,  :event => :task_enabled)
     newvalue(:false, :event => :task_disabled)
@@ -110,8 +28,7 @@ Puppet::Type.newtype(:scheduled_task) do
   end
 
   newproperty(:command) do
-    desc "The full path to the application to be run, without any
-      arguments."
+    desc "The full path to the application to run, without any arguments."
 
     validate do |value|
       raise Puppet::Error.new('Must be specified using an absolute path.') unless absolute_path?(value)
@@ -119,8 +36,7 @@ Puppet::Type.newtype(:scheduled_task) do
   end
 
   newproperty(:working_dir) do
-    desc "The full path of the directory in which to start the
-      command"
+    desc "The full path of the directory in which to start the command."
 
     validate do |value|
       raise Puppet::Error.new('Must be specified using an absolute path.') unless absolute_path?(value)
@@ -128,7 +44,8 @@ Puppet::Type.newtype(:scheduled_task) do
   end
 
   newproperty(:arguments, :array_matching => :all) do
-    desc "The optional arguments to pass to the command."
+    desc "Any arguments or flags that should be passed to the command. Multiple arguments
+      can be specified as an array or as a space-separated string."
   end
 
   newproperty(:user) do
@@ -149,7 +66,7 @@ Puppet::Type.newtype(:scheduled_task) do
   end
 
   newparam(:password) do
-    desc "The password for the user specified in the 'user' property.
+    desc "The password for the user specified in the 'user' attribute.
       This is only used if specifying a user other than 'SYSTEM'.
       Since there is no way to retrieve the password used to set the
       account information for a task, this parameter will not be used
@@ -157,43 +74,72 @@ Puppet::Type.newtype(:scheduled_task) do
   end
 
   newproperty(:trigger, :array_matching => :all) do
-    desc "This is a hash defining the properties of the trigger used
-      to fire the scheduled task.  The one key that is always required
-      is 'schedule', which can be one of 'daily', 'weekly', or
-      'monthly'.  The other valid & required keys depend on the value
-      of schedule.
-
-      When schedule is 'daily', you can specify a value for 'every'
-      which specifies that the task will trigger every N days.  If
-      'every' is not specified, it defaults to 1 (running every day).
-
-      When schedule is 'weekly', you can specify values for 'every',
-      and 'day_of_week'.  'every' has similar behavior as when
-      specified for 'daily', though it repeats every N weeks, instead
-      of every N days.  'day_of_week' is used to specify on which days
-      of the week the task should be run.  This can be specified as an
-      array where the possible values are 'mon', 'tues', 'wed',
-      'thurs', 'fri', 'sat', and 'sun', or as the string 'all'.  The
-      default is 'all'.
-
-      When schedule is 'monthly', the syntax depends on whether you
-      wish to specify the trigger using absolute, or relative dates.
-      In either case, you can specify which months this trigger
-      applies to using 'months', and specifying an array of integer
-      months.  'months' defaults to all months.
-
-      When specifying a monthly schedule with absolute dates, 'on'
-      must be provided as an array of days (1-31, or the special value
-      'last' which will always be the last day of the month).
-
-      When specifying a monthly schedule with relative dates,
-      'which_occurrence', and 'day_of_week' must be specified.  The
-      possible values for 'which_occurrence' are 'first', 'second',
-      'third', 'fourth', 'fifth', and 'last'.  'day_of_week' is an
-      array where the possible values are 'mon', 'tues', 'wed',
-      'thurs', 'fri', 'sat', and 'sun'.  These combine to be able to
-      specify things like: The task should run on the first Monday of
-      the specified month(s)."
+    desc <<-EOT
+      One or more triggers defining when the task should run. A single trigger is
+      represented as a hash, and multiple triggers can be specified with an array of
+      hashes.
+
+      A trigger can contain the following keys:
+
+      * For all triggers:
+          * `schedule` **(Required)** --- The schedule type. Valid values are
+            `daily`, `weekly`, `monthly`, or `once`.
+          * `start_time` **(Required)** --- The time of day when the trigger should
+            first become active. Several time formats will work, but we
+            suggest 24-hour time formatted as HH:MM.
+          * `start_date` ---  The date when the trigger should first become active.
+            Defaults to "today." Several date formats will work, including
+            special dates like "today," but we suggest formatting dates as
+            YYYY-MM-DD.
+      * For daily triggers:
+          * `every` --- How often the task should run, as a number of days. Defaults
+            to 1. ("2" means every other day, "3" means every three days, etc.)
+      * For weekly triggers:
+          * `every` --- How often the task should run, as a number of weeks. Defaults
+            to 1. ("2" means every other week, "3" means every three weeks, etc.)
+          * `day_of_week` --- Which days of the week the task should run, as an array.
+            Defaults to all days. Each day must be one of `mon`, `tues`,
+            `wed`, `thurs`, `fri`, `sat`, `sun`, or `all`.
+      * For monthly-by-date triggers:
+          * `months` --- Which months the task should run, as an array. Defaults to
+            all months. Each month must be an integer between 1 and 12.
+          * `on` **(Required)** --- Which days of the month the task should run,
+            as an array. Each day must beeither an integer between 1 and 31,
+            or the special value `last,` which is always the last day of the month.
+      * For monthly-by-weekday triggers:
+          * `months` --- Which months the task should run, as an array. Defaults to
+            all months. Each month must be an integer between 1 and 12.
+          * `day_of_week` **(Required)** --- Which day of the week the task should
+            run, as an array with only one element. Each day must be one of `mon`,
+            `tues`, `wed`, `thurs`, `fri`, `sat`, `sun`, or `all`.
+          * `which_occurrence` **(Required)** --- The occurrence of the chosen weekday
+            when the task should run. Must be one of `first`, `second`, `third`,
+            `fourth`, `fifth`, or `last`.
+
+      Examples:
+
+          # Run at 8am on the 1st, 15th, and last day of the month in January, March,
+          # May, July, September, and November, starting after August 31st, 2011.
+          trigger => {
+            schedule   => monthly,
+            start_date => '2011-08-31',   # Defaults to 'today'
+            start_time => '08:00',        # Must be specified
+            months     => [1,3,5,7,9,11], # Defaults to all
+            on         => [1, 15, last],  # Must be specified
+          }
+
+          # Run at 8am on the first Monday of the month for January, March, and May,
+          # starting after August 31st, 2011.
+          trigger => {
+            schedule         => monthly,
+            start_date       => '2011-08-31', # Defaults to 'today'
+            start_time       => '08:00',      # Must be specified
+            months           => [1,3,5],      # Defaults to all
+            which_occurrence => first,        # Must be specified
+            day_of_week      => [mon],        # Must be specified
+          }
+
+    EOT
 
     validate do |value|
       provider.validate_trigger(value)

data/lib/puppet/type/service.rb

@@ -105,6 +105,12 @@ module Puppet
         command; defaults to `true`. This attribute's default value changed in
         Puppet 2.7.0.
 
+        The init script's status command must return 0 if the service is
+        running and a nonzero value otherwise. Ideally, these exit codes
+        should conform to [the LSB's specification][lsb-exit-codes] for init
+        script status actions, but Puppet only considers the difference
+        between 0 and nonzero to be relevant.
+
         If a service's init script does not support any kind of status command,
         you should set `hasstatus` to false and either provide a specific
         command using the `status` attribute or expect that Puppet will look for
@@ -118,8 +124,14 @@ module Puppet
       defaultto :true
     end
     newparam(:name) do
-      desc "The name of the service to run.  This name is used to find
-        the service in whatever service subsystem it is in."
+      desc <<-EOT
+        The name of the service to run.
+
+        This name is used to find the service; on platforms where services
+        have short system names and long display names, this should be the
+        short name. (To take an example from Windows, you would use "wuauserv"
+        rather than "Automatic Updates.")
+      EOT
       isnamevar
     end
 
@@ -160,14 +172,16 @@ module Puppet
     newparam(:status) do
       desc "Specify a *status* command manually.  This command must
         return 0 if the service is running and a nonzero value otherwise.
-        Ideally, these return codes should conform to
-        [the LSB's specification for init script status actions](http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html),
-        but Puppet only considers the difference between 0 and nonzero
-        to be relevant.
+        Ideally, these exit codes should conform to [the LSB's
+        specification][lsb-exit-codes] for init script status actions, but
+        Puppet only considers the difference between 0 and nonzero to be
+        relevant.
 
-        If left unspecified, the status method will be determined
+        If left unspecified, the status of the service will be determined
         automatically, usually by looking for the service in the process
-        table."
+        table.
+
+        [lsb-exit-codes]: http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html"
     end
 
     newparam(:stop) do

data/lib/puppet/type/user.rb

@@ -113,8 +113,10 @@ module Puppet
     end
 
     newproperty(:gid) do
-      desc "The user's primary group.  Can be specified numerically or
-        by name."
+      desc "The user's primary group.  Can be specified numerically or by name.
+
+        Note that users on Windows systems do not have a primary group; manage groups
+        with the `groups` attribute instead."
 
       munge do |value|
         if value.is_a?(String) and value =~ /^[-0-9]+$/
@@ -156,14 +158,28 @@ module Puppet
 
     newproperty(:shell) do
       desc "The user's login shell.  The shell must exist and be
-        executable."
+        executable.
+
+        This attribute cannot be managed on Windows systems."
     end
 
     newproperty(:password, :required_features => :manages_passwords) do
       desc %q{The user's password, in whatever encrypted format the local
-        machine requires. Be sure to enclose any value that includes a dollar
-        sign ($) in single quotes (') to avoid accidental variable
-        interpolation.}
+        system requires.
+
+        * Most modern Unix-like systems use salted SHA1 password hashes. You can use
+          Puppet's built-in `sha1` function to generate a hash from a password.
+        * Mac OS X 10.5 and 10.6 also use salted SHA1 hashes.
+        * Mac OS X 10.7 (Lion) uses salted SHA512 hashes. The Puppet Labs [stdlib][]
+          module contains a `str2saltedsha512` function which can generate password
+          hashes for Lion.
+        * Windows passwords can only be managed in cleartext, as there is no Windows API
+          for setting the password hash.
+
+        [stdlib]: https://github.com/puppetlabs/puppetlabs-stdlib/
+
+        Be sure to enclose any value that includes a dollar sign ($) in single
+        quotes (') to avoid accidental variable interpolation.}
 
       validate do |value|
         raise ArgumentError, "Passwords cannot include ':'" if value.is_a?(String) and value.include?(":")
@@ -240,7 +256,11 @@ module Puppet
     newparam(:name) do
       desc "The user name. While naming limitations vary by operating system,
         it is advisable to restrict names to the lowest common denominator,
-        which is a maximum of 8 characters beginning with a letter."
+        which is a maximum of 8 characters beginning with a letter.
+
+        Note that Puppet considers user names to be case-sensitive, regardless
+        of the platform's own rules; be sure to always use the same case when
+        referring to a given user."
       isnamevar
     end
 
@@ -450,7 +470,7 @@ module Puppet
       end
 
       validate do |value|
-        raise ArgumentError, "Key/value pairs must be seperated by an =" unless value.include?("=")
+        raise ArgumentError, "Key/value pairs must be separated by an =" unless value.include?("=")
       end
     end
 
@@ -484,7 +504,7 @@ module Puppet
       end
 
       validate do |value|
-        raise ArgumentError, "Attributes value pairs must be seperated by an =" unless value.include?("=")
+        raise ArgumentError, "Attributes value pairs must be separated by an =" unless value.include?("=")
       end
     end
 

data/lib/puppet/util.rb

@@ -120,28 +120,6 @@ module Util
     end
   end
 
-  # XXX this should all be done using puppet objects, not using
-  # normal mkdir
-  def self.recmkdir(dir,mode = 0755)
-    if FileTest.exist?(dir)
-      return false
-    else
-      tmp = dir.sub(/^\//,'')
-      path = [File::SEPARATOR]
-      tmp.split(File::SEPARATOR).each { |dir|
-        path.push dir
-        if ! FileTest.exist?(File.join(path))
-          Dir.mkdir(File.join(path), mode)
-        elsif FileTest.directory?(File.join(path))
-          next
-        else FileTest.exist?(File.join(path))
-          raise "Cannot create #{dir}: basedir #{File.join(path)} is a file"
-        end
-      }
-      return true
-    end
-  end
-
   # Execute a given chunk of code with a new umask.
   def self.withumask(mask)
     cur = File.umask(mask)
@@ -270,7 +248,14 @@ module Util
   end
   module_function :uri_to_path
 
-  # Execute the provided command in a pipe, yielding the pipe object.
+  # Execute the provided command with STDIN connected to a pipe, yielding the
+  # pipe object.  That allows data to be fed to that subprocess.
+  #
+  # The command can be a simple string, which is executed as-is, or an Array,
+  # which is treated as a set of command arguments to pass through.#
+  #
+  # In all cases this is passed directly to the shell, and STDOUT and STDERR
+  # are connected together during execution.
   def execpipe(command, failonfail = true)
     if respond_to? :debug
       debug "Executing '#{command}'"
@@ -278,7 +263,14 @@ module Util
       Puppet.debug "Executing '#{command}'"
     end
 
-    command_str = command.respond_to?(:join) ? command.join('') : command
+    # Paste together an array with spaces.  We used to paste directly
+    # together, no spaces, which made for odd invocations; the user had to
+    # include whitespace between arguments.
+    #
+    # Having two spaces is really not a big drama, since this passes to the
+    # shell anyhow, while no spaces makes for a small developer cost every
+    # time this is invoked. --daniel 2012-02-13
+    command_str = command.respond_to?(:join) ? command.join(' ') : command
     output = open("| #{command_str} 2>&1") do |pipe|
       yield pipe
     end
@@ -333,8 +325,7 @@ module Util
       part.include?(' ') ? %Q["#{part.gsub(/"/, '\"')}"] : part
     end.join(" ") if command.is_a?(Array)
 
-    process_info = Process.create( :command_line => command, :startup_info => {:stdin => stdin, :stdout => stdout, :stderr => stderr} )
-    process_info.process_id
+    Puppet::Util::Windows::Process.execute(command, arguments, stdin, stdout, stderr)
   end
   module_function :execute_windows
 
@@ -371,13 +362,13 @@ module Util
       child_pid = execute_posix(*exec_args)
       exit_status = Process.waitpid2(child_pid).last.exitstatus
     elsif Puppet.features.microsoft_windows?
-      child_pid = execute_windows(*exec_args)
-      exit_status = Process.waitpid2(child_pid).last
-      # $CHILD_STATUS is not set when calling win32/process Process.create
-      # and since it's read-only, we can't set it. But we can execute a
-      # a shell that simply returns the desired exit status, which has the
-      # desired effect.
-      %x{#{ENV['COMSPEC']} /c exit #{exit_status}}
+      process_info = execute_windows(*exec_args)
+      begin
+        exit_status = Puppet::Util::Windows::Process.wait_process(process_info.process_handle)
+      ensure
+        Process.CloseHandle(process_info.process_handle)
+        Process.CloseHandle(process_info.thread_handle)
+      end
     end
 
     [stdin, stdout, stderr].each {|io| io.close rescue nil}