puppet 2.7.6 → 2.7.8

data/lib/puppet/type/maillist.rb

@@ -1,7 +1,7 @@
 module Puppet
   newtype(:maillist) do
-    @doc = "Manage email lists.  This resource type currently can only create
-      and remove lists, it cannot reconfigure them."
+    @doc = "Manage email lists.  This resource type can only create
+      and remove lists; it cannot currently reconfigure them."
 
     ensurable do
       defaultvalues

data/lib/puppet/type/mcx.rb

@@ -3,7 +3,7 @@ Puppet::Type.newtype(:mcx) do
   @doc = "MCX object management using DirectoryService on OS X.
 
 The default provider of this type merely manages the XML plist as
-reported by the dscl -mcxexport command.  This is similar to the
+reported by the `dscl -mcxexport` command.  This is similar to the
 content property of the file type in Puppet.
 
 The recommended method of using this type is to use Work Group Manager
@@ -53,14 +53,14 @@ MCX settings refer to, the MCX resource will autorequire that user, group, or co
   end
 
   newparam(:ds_name) do
-    desc "The name to attach the MCX Setting to.
-    e.g. 'localhost' when ds_type => computer. This setting is not
-    required, as it may be parsed so long as the resource name is
-    parseable.  e.g. /Groups/admin where 'group' is the dstype."
+    desc "The name to attach the MCX Setting to. (For example, `localhost`
+    when `ds_type => computer`.) This setting is not required, as it can be
+    automatically discovered when the resource name is parseable.  (For
+    example, in `/Groups/admin`, `group` will be used as the dstype.)"
   end
 
   newproperty(:content, :required_features => :manages_content) do
-    desc "The XML Plist.  The value of MCXSettings in DirectoryService.
+    desc "The XML Plist used as the value of MCXSettings in DirectoryService.
     This is the standard output from the system command:
 
         dscl localhost -mcxexport /Local/Default/<ds_type>/ds_name

data/lib/puppet/type/mount.rb

@@ -16,10 +16,11 @@ module Puppet
     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
-        but not mounted (if the filesystem is currently mounted, it will be unmounted).  Set it to `absent` to unmount (if necessary) and remove
+        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
         fstab and mount it. Set to `present` to add to fstab but not change
-        mount/unmount status"
+        mount/unmount status."
 
       #  IS        -> SHOULD     In Sync  Action
       #  ghost     -> present    NO       create

data/lib/puppet/type/notify.rb

@@ -30,7 +30,7 @@ module Puppet
     end
 
     newparam(:withpath) do
-      desc "Whether to not to show the full object path."
+      desc "Whether to show the full object path. Defaults to false."
       defaultto :false
 
       newvalues(:true, :false)

data/lib/puppet/type/package.rb

@@ -7,9 +7,9 @@ module Puppet
   newtype(:package) do
     @doc = "Manage packages.  There is a basic dichotomy in package
       support right now:  Some package types (e.g., yum and apt) can
-      retrieve their own package files, while others (e.g., rpm and sun) cannot.  For those package formats that cannot retrieve
-      their own files, you can use the `source` parameter to point to
-      the correct file.
+      retrieve their own package files, while others (e.g., rpm and sun)
+      cannot.  For those package formats that cannot retrieve their own files,
+      you can use the `source` parameter to point to the correct file.
 
       Puppet will automatically guess the packaging format that you are
       using based on the platform you are on, but you can override it
@@ -17,9 +17,9 @@ module Puppet
       requires in order to function, and you must meet those requirements
       to use a given provider.
 
-      **Autorequires:** If Puppet is managing the files specified as a package's
-      `adminfile`, `responsefile`, or `source`, the package resource will autorequire
-      those files."
+      **Autorequires:** If Puppet is managing the files specified as a
+      package's `adminfile`, `responsefile`, or `source`, the package
+      resource will autorequire those files."
 
     feature :installable, "The provider can install packages.",
       :methods => [:install]
@@ -48,14 +48,14 @@ module Puppet
       passed to the installer command."
 
     ensurable do
-      desc "What state the package should be in.
-        *latest* only makes sense for those packaging formats that can
-        retrieve new packages on their own and will throw an error on
-        those that cannot.  For those packaging systems that allow you
-        to specify package versions, specify them here.  Similarly,
-        *purged* is only useful for packaging systems that support
-        the notion of managing configuration files separately from
-        'normal' system files."
+      desc <<-EOT
+        What state the package should be in. On packaging systems that can
+        retrieve new packages on their own, you can choose which package to
+        retrieve by specifying a version number or `latest` as the ensure
+        value. On packaging systems that manage configuration files separately
+        from "normal" system files, you can uninstall config files by
+        specifying `purged` as the ensure value.
+      EOT
 
       attr_accessor :latest
 
@@ -196,7 +196,7 @@ module Puppet
           # object name.
           package { $ssl:
             ensure => installed,
-            alias => openssl
+            alias  => openssl
           }
 
           . etc. .
@@ -209,8 +209,8 @@ module Puppet
           # Use the alias to specify a dependency, rather than
           # having another selector to figure it out again.
           package { $ssh:
-            ensure => installed,
-            alias => openssh,
+            ensure  => installed,
+            alias   => openssh,
             require => Package[openssl]
           }
 
@@ -221,7 +221,12 @@ module Puppet
     newparam(:source) do
       desc "Where to find the actual package.  This must be a local file
         (or on a network file system) or a URL that your specific
-        packaging type understands; Puppet will not retrieve files for you."
+        packaging type understands; Puppet will not retrieve files for you,
+        although you can manage packages as `file` resources."
+
+      validate do |value|
+        provider.validate_source(value)
+      end
     end
 
     newparam(:instance) do
@@ -260,7 +265,7 @@ module Puppet
 
     newparam(:configfiles) do
       desc "Whether configfiles should be kept or replaced.  Most packages
-        types do not support this parameter."
+        types do not support this parameter. Defaults to `keep`."
 
       defaultto :keep
 
@@ -300,10 +305,6 @@ module Puppet
         installing a package."
     end
 
-    validate do
-      provider.validate_source(self[:source])
-    end
-
     autorequire(:file) do
       autos = []
       [:responsefile, :adminfile].each { |param|

data/lib/puppet/type/router.rb

@@ -7,7 +7,10 @@ module Puppet
     @doc = "Manages connected router."
 
     newparam(:url) do
-      desc "An URL to access the router of the form (ssh|telnet)://user:pass:enable@host/."
+      desc <<-EOT
+        An SSH or telnet URL at which to access the router, in the form
+        `ssh://user:pass:enable@host/` or `telnet://user:pass:enable@host/`.
+      EOT
       isnamevar
     end
   end

data/lib/puppet/type/schedule.rb

@@ -1,27 +1,32 @@
 module Puppet
   newtype(:schedule) do
-    @doc = "Defined schedules for Puppet.  The important thing to understand
-      about how schedules are currently implemented in Puppet is that they
-      can only be used to stop a resource from being applied, they never
-      guarantee that it is applied.
-
-      Every time Puppet applies its configuration, it will collect the
-      list of resources whose schedule does not eliminate them from
+    @doc = <<-EOT
+      Define schedules for Puppet. Resources can be limited to a schedule by using the
+      [`schedule`](http://docs.puppetlabs.com/references/latest/metaparameter.html#schedule)
+      metaparameter.
+
+      Currently, **schedules can only be used to stop a resource from being
+      applied;** they cannot cause a resource to be applied when it otherwise
+      wouldn't be, and they cannot accurately specify a time when a resource
+      should run.
+
+      Every time Puppet applies its configuration, it will apply the
+      set of resources whose schedule does not eliminate them from
       running right then, but there is currently no system in place to
       guarantee that a given resource runs at a given time.  If you
       specify a very  restrictive schedule and Puppet happens to run at a
       time within that schedule, then the resources will get applied;
       otherwise, that work may never get done.
 
-      Thus, it behooves you to use wider scheduling (e.g., over a couple of
+      Thus, it is advisable to use wider scheduling (e.g., over a couple of
       hours) combined with periods and repetitions.  For instance, if you
       wanted to restrict certain resources to only running once, between
       the hours of two and 4 AM, then you would use this schedule:
 
-          schedule { maint:
-            range => \"2 - 4\",
+          schedule { 'maint':
+            range  => "2 - 4",
             period => daily,
-            repeat => 1
+            repeat => 1,
           }
 
       With this schedule, the first time that Puppet runs between 2 and 4 AM,
@@ -30,51 +35,54 @@ module Puppet
       run once that day, and they won't get applied outside that schedule
       because they will be outside the scheduled range.
 
-      Puppet automatically creates a schedule for each valid period with the
-      same name as that period (e.g., hourly and daily).  Additionally,
-      a schedule named *puppet* is created and used as the default,
-      with the following attributes:
+      Puppet automatically creates a schedule for each of the valid periods
+      with the same name as that period (e.g., hourly and daily).
+      Additionally, a schedule named `puppet` is created and used as the
+      default, with the following attributes:
 
-          schedule { puppet:
+          schedule { 'puppet':
             period => hourly,
-            repeat => 2
+            repeat => 2,
           }
 
       This will cause resources to be applied every 30 minutes by default.
-      "
+      EOT
 
     apply_to_all
 
     newparam(:name) do
-      desc "The name of the schedule.  This name is used to retrieve the
+      desc <<-EOT
+        The name of the schedule.  This name is used to retrieve the
         schedule when assigning it to an object:
 
-            schedule { daily:
+            schedule { 'daily':
               period => daily,
-              range => \"2 - 4\",
+              range  => "2 - 4",
             }
-  
-            exec { \"/usr/bin/apt-get update\":
-              schedule => daily
+
+            exec { "/usr/bin/apt-get update":
+              schedule => 'daily',
             }
 
-        "
+        EOT
       isnamevar
     end
 
     newparam(:range) do
-      desc "The earliest and latest that a resource can be applied.  This
-        is always a range within a 24 hour period, and hours must be
-        specified in numbers between 0 and 23, inclusive.  Minutes and
-        seconds can be provided, using the normal colon as a separator.
-        For instance:
-
-            schedule { maintenance:
-              range => \"1:30 - 4:30\"
+      desc <<-EOT
+        The earliest and latest that a resource can be applied.  This is
+        always a hyphen-separated range within a 24 hour period, and hours
+        must be specified in numbers between 0 and 23, inclusive.  Minutes and
+        seconds can optionally be provided, using the normal colon as a
+        separator. For instance:
+
+            schedule { 'maintenance':
+              range => "1:30 - 4:30",
             }
 
         This is mostly useful for restricting certain resources to being
-        applied in maintenance windows or during off-peak hours."
+        applied in maintenance windows or during off-peak hours.
+      EOT
 
       # This is lame; properties all use arrays as values, but parameters don't.
       # That's going to hurt eventually.
@@ -190,24 +198,23 @@ module Puppet
     end
 
     newparam(:period) do
-      desc "The period of repetition for a resource.  Choose from among
-        a fixed list of *hourly*, *daily*, *weekly*, and *monthly*.
-        The default is for a resource to get applied every time that
-        Puppet runs, whatever that period is.
+      desc <<-EOT
+        The period of repetition for a resource. The default is for a resource
+        to get applied every time Puppet runs.
 
         Note that the period defines how often a given resource will get
         applied but not when; if you would like to restrict the hours
         that a given resource can be applied (e.g., only at night during
-        a maintenance window) then use the `range` attribute.
+        a maintenance window), then use the `range` attribute.
 
         If the provided periods are not sufficient, you can provide a
         value to the *repeat* attribute, which will cause Puppet to
         schedule the affected resources evenly in the period the
         specified number of times.  Take this schedule:
 
-            schedule { veryoften:
+            schedule { 'veryoften':
               period => hourly,
-              repeat => 6
+              repeat => 6,
             }
 
         This can cause Puppet to apply that resource up to every 10 minutes.
@@ -218,7 +225,8 @@ module Puppet
         often (e.g., long-running Puppet runs will squash conflictingly scheduled runs).
 
         See the `periodmatch` attribute for tuning whether to match
-        times by their distance apart or by their specific value."
+        times by their distance apart or by their specific value.
+      EOT
 
       newvalues(:hourly, :daily, :weekly, :monthly, :never)
 
@@ -268,8 +276,8 @@ module Puppet
     end
 
     newparam(:repeat) do
-      desc "How often the application gets repeated in a given period.
-        Defaults to 1. Must be an integer."
+      desc "How often a given resource may be applied in this schedule's `period`.
+        Defaults to 1; must be an integer."
 
       defaultto 1
 

data/lib/puppet/type/scheduled_task.rb

@@ -0,0 +1,222 @@
+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
+        }
+      }"
+
+  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."
+
+    newvalue(:true,  :event => :task_enabled)
+    newvalue(:false, :event => :task_disabled)
+
+    defaultto(:true)
+  end
+
+  newparam(:name) do
+    desc "The name assigned to the scheduled task.  This will uniquely
+      identify the task on the system."
+
+    isnamevar
+  end
+
+  newproperty(:command) do
+    desc "The full path to the application to be run, without any
+      arguments."
+
+    validate do |value|
+      raise Puppet::Error.new('Must be specified using an absolute path.') unless absolute_path?(value)
+    end
+  end
+
+  newproperty(:working_dir) do
+    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)
+    end
+  end
+
+  newproperty(:arguments, :array_matching => :all) do
+    desc "The optional arguments to pass to the command."
+  end
+
+  newproperty(:user) do
+    desc "The user to run the scheduled task as.  Please note that not
+      all security configurations will allow running a scheduled task
+      as 'SYSTEM', and saving the scheduled task under these
+      conditions will fail with a reported error of 'The operation
+      completed successfully'.  It is recommended that you either
+      choose another user to run the scheduled task, or alter the
+      security policy to allow v1 scheduled tasks to run as the
+      'SYSTEM' account.  Defaults to 'SYSTEM'."
+
+    defaultto :system
+
+    def insync?(current)
+      provider.user_insync?(current, @should)
+    end
+  end
+
+  newparam(:password) do
+    desc "The password for the user specified in the 'user' property.
+      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
+      to determine if a scheduled task is in sync or not."
+  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)."
+
+    validate do |value|
+      provider.validate_trigger(value)
+    end
+
+    def insync?(current)
+      provider.trigger_insync?(current, @should)
+    end
+
+    def should_to_s(new_value=@should)
+      self.class.format_value_for_display(new_value)
+    end
+
+    def is_to_s(current_value=@is)
+      self.class.format_value_for_display(current_value)
+    end
+  end
+
+  validate do
+    return true if self[:ensure] == :absent
+
+    if self[:arguments] and !(self[:arguments].is_a?(Array) and self[:arguments].length == 1)
+      self.fail('Parameter arguments failed: Must be specified as a single string')
+    end
+  end
+end