puppet 2.7.11 → 2.7.12

data/lib/puppet/type/cron.rb

@@ -87,7 +87,7 @@ Puppet::Type.newtype(:cron) do
       # if we can lengthen it (e.g., mon => monday).
       if tmp.length == 3
         ary.each_with_index { |name, index|
-          if name =~ /#{tmp}/i
+          if tmp.upcase == name[0..2].upcase
             return index
           end
         }
@@ -352,7 +352,10 @@ Puppet::Type.newtype(:cron) do
 
       The user defaults to whomever Puppet is running as."
 
-    defaultto { Etc.getpwuid(Process.uid).name || "root" }
+    defaultto {
+      struct = Etc.getpwuid(Process.uid)
+      struct.respond_to?(:name) && struct.name or 'root'
+    }
   end
 
   newproperty(:target) do

data/lib/puppet/type/exec.rb

@@ -369,6 +369,10 @@ module Puppet
           return false
         end
 
+        output.split(/\n/).each { |line|
+          self.debug(line)
+        }
+
         status.exitstatus != 0
       end
     end
@@ -412,6 +416,10 @@ module Puppet
           return false
         end
 
+        output.split(/\n/).each { |line|
+          self.debug(line)
+        }
+
         status.exitstatus == 0
       end
     end

data/lib/puppet/type/file.rb

@@ -17,16 +17,18 @@ Puppet::Type.newtype(:file) do
   include Puppet::Util::Backups
   include Puppet::Util::SymbolicFileMode
 
-  @doc = "Manages local files, including setting ownership and
-    permissions, creation of both files and directories, and
-    retrieving entire files from remote servers.  As Puppet matures, it
-    expected that the `file` resource will be used less and less to
-    manage content, and instead native resources will be used to do so.
+  @doc = "Manages files, including their content, ownership, and permissions.
 
-    If you find that you are often copying files in from a central
-    location, rather than using native resources, please contact
-    Puppet Labs and we can hopefully work with you to develop a
-    native resource to support what you are doing.
+    The `file` type can manage normal files, directories, and symlinks; the
+    type should be specified in the `ensure` attribute. Note that symlinks cannot
+    be managed on Windows systems.
+
+    File contents can be managed directly with the `content` attribute, or
+    downloaded from a remote source using the `source` attribute; the latter
+    can also be used to recursively serve directories (when the `recurse`
+    attribute is set to `true` or `local`). On Windows, note that file
+    contents are managed in binary mode; Puppet never automatically translates
+    line endings.
 
     **Autorequires:** If Puppet is managing the user or group that owns a
     file, the file resource will autorequire them. If Puppet is managing any
@@ -37,7 +39,12 @@ Puppet::Type.newtype(:file) do
   end
 
   newparam(:path) do
-    desc "The path to the file to manage.  Must be fully qualified."
+    desc <<-EOT
+      The path to the file to manage.  Must be fully qualified.
+
+      On Windows, the path should include the drive letter and should use `/` as
+      the separator character (rather than `\\`).
+    EOT
     isnamevar
 
     validate do |value|
@@ -191,9 +198,11 @@ Puppet::Type.newtype(:file) do
   end
 
   newparam(:replace, :boolean => true) do
-    desc "Whether or not to replace a file that is
-      sourced but exists.  This is useful for using file sources
-      purely for initialization."
+    desc "Whether to replace a file that already exists on the local system but
+      whose content doesn't match what the `source` or `content` attribute
+      specifies.  Setting this to false allows file resources to initialize files
+      without overwriting future changes.  Note that this only affects content;
+      Puppet will still manage ownership and permissions."
     newvalues(:true, :false)
     aliasvalue(:yes, :true)
     aliasvalue(:no, :false)
@@ -251,11 +260,11 @@ Puppet::Type.newtype(:file) do
 
   newparam(:sourceselect) do
     desc "Whether to copy all valid sources, or just the first one.  This parameter
-      is only used in recursive copies; by default, the first valid source is the
-      only one used as a recursive source, but if this parameter is set to `all`,
-      then all valid sources will have all of their contents copied to the local host,
-      and for sources that have the same file, the source earlier in the list will
-      be used."
+      only affects recursive directory copies; by default, the first valid
+      source is the only one used, but if this parameter is set to `all`, then
+      all valid sources will have all of their contents copied to the local
+      system. If a given file exists in more than one source, the version from
+      the earliest source in the list will be used."
 
     defaultto :first
 

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

@@ -5,9 +5,9 @@ require 'puppet/util/checksums'
 Puppet::Type.type(:file).newparam(:checksum) do
   include Puppet::Util::Checksums
 
-  desc "The checksum type to use when checksumming a file.
+  desc "The checksum type to use when determining whether to replace a file's contents.
 
-    The default checksum parameter, if checksums are enabled, is md5."
+    The default checksum type is md5."
 
   newvalues "md5", "md5lite", "mtime", "ctime", "none"
 

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

@@ -15,27 +15,32 @@ module Puppet
 
     attr_reader :actual_content
 
-    desc "Specify the contents of a file as a string.  Newlines, tabs, and
-      spaces can be specified using standard escaped syntax in
-      double-quoted strings (e.g., \\n for a newline).
+    desc <<-EOT
+      The desired contents of a file, as a string. This attribute is mutually
+      exclusive with `source` and `target`.
 
-      With very small files, you can construct strings directly...
+      Newlines and tabs can be specified in double-quoted strings using
+      standard escaped syntax --- \n for a newline, and \t for a tab.
+
+      With very small files, you can construct content strings directly in
+      the manifest...
 
           define resolve(nameserver1, nameserver2, domain, search) {
-              $str = \"search $search
+              $str = "search $search
                   domain $domain
                   nameserver $nameserver1
                   nameserver $nameserver2
-                  \"
+                  "
 
-              file { \"/etc/resolv.conf\":
-                content => $str
+              file { "/etc/resolv.conf":
+                content => "$str",
               }
           }
 
       ...but for larger files, this attribute is more useful when combined with the
       [template](http://docs.puppetlabs.com/references/latest/function.html#template)
-      function."
+      function.
+    EOT
 
     # Store a checksum as the value, rather than the actual content.
     # Simplifies everything.

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

@@ -10,11 +10,12 @@ module Puppet
       Possible values are *absent*, *present*, *file*, and *directory*.
       Specifying `present` will match any form of file existence, and
       if the file is missing will create an empty file. Specifying
-      `absent` will delete the file (and directory if `recurse => true`).
+      `absent` will delete the file (or directory, if `recurse => true`).
 
-      Anything other than those values will create a symlink. In the interest
-      of readability and clarity, you should use `ensure => link` and
-      explicitly specify a target; however, if a `target` attribute isn't
+      Anything other than the above values will create a symlink; note that
+      symlinks cannot be managed on Windows. In the interest of readability
+      and clarity, symlinks should be created by setting `ensure => link` and
+      explicitly specifying a target; however, if a `target` attribute isn't
       provided, the value of the `ensure` attribute will be used as the
       symlink target. The following two declarations are equivalent:
 

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

@@ -3,8 +3,16 @@ require 'puppet/util/posix'
 # Manage file group ownership.
 module Puppet
   Puppet::Type.type(:file).newproperty(:group) do
-    desc "Which group should own the file.  Argument can be either group
-      name or group ID."
+    desc <<-EOT
+      Which group should own the file.  Argument can be either a group
+      name or a group ID.
+
+      On Windows, a user (such as "Administrator") can be set as a file's group
+      and a group (such as "Administrators") can be set as a file's owner;
+      however, a file's owner and group shouldn't be the same. (If the owner
+      is also the group, files with modes like `0640` will cause log churn, as
+      they will always appear out of sync.)
+    EOT
 
     validate do |group|
       raise(Puppet::Error, "Invalid group name '#{group.inspect}'") unless group and group != ""

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

@@ -6,24 +6,52 @@ module Puppet
     require 'puppet/util/symbolic_file_mode'
     include Puppet::Util::SymbolicFileMode
 
-    desc "Mode the file should be.  Currently relatively limited:
-      you must specify the exact mode the file should be.
-
-      Note that when you set the mode of a directory, Puppet always
-      sets the search/traverse (1) bit anywhere the read (4) bit is set.
-      This is almost always what you want: read allows you to list the
-      entries in a directory, and search/traverse allows you to access
-      (read/write/execute) those entries.)  Because of this feature, you
-      can recursively make a directory and all of the files in it
-      world-readable by setting e.g.:
-
-          file { '/some/dir':
-            mode    => 644,
-            recurse => true,
-          }
-
-      In this case all of the files underneath `/some/dir` will have
-      mode 644, and all of the directories will have mode 755."
+    desc <<-EOT
+      The desired permissions mode for the file, in symbolic or numeric
+      notation. Puppet uses traditional Unix permission schemes and translates
+      them to equivalent permissions for systems which represent permissions
+      differently, including Windows.
+
+      Numeric modes should use the standard four-digit octal notation of
+      `<setuid/setgid/sticky><owner><group><other>` (e.g. 0644). Each of the
+      "owner," "group," and "other" digits should be a sum of the
+      permissions for that class of users, where read = 4, write = 2, and
+      execute/search = 1. When setting numeric permissions for
+      directories, Puppet sets the search permission wherever the read
+      permission is set.
+
+      Symbolic modes should be represented as a string of comma-separated
+      permission clauses, in the form `<who><op><perm>`:
+
+      * "Who" should be u (user), g (group), o (other), and/or a (all)
+      * "Op" should be = (set exact permissions), + (add select permissions),
+        or - (remove select permissions)
+      * "Perm" should be one or more of:
+          * r (read)
+          * w (write)
+          * x (execute/search)
+          * t (sticky)
+          * s (setuid/setgid)
+          * X (execute/search if directory or if any one user can execute)
+          * u (user's current permissions)
+          * g (group's current permissions)
+          * o (other's current permissions)
+
+      Thus, mode `0664` could be represented symbolically as either `a=r,ug+w` or
+      `ug=rw,o=r`. See the manual page for GNU or BSD `chmod` for more details
+      on numeric and symbolic modes.
+
+      On Windows, permissions are translated as follows:
+
+      * Owner and group names are mapped to Windows SIDs
+      * The "other" class of users maps to the "Everyone" SID
+      * The read/write/execute permissions map to the `FILE_GENERIC_READ`,
+        `FILE_GENERIC_WRITE`, and `FILE_GENERIC_EXECUTE` access rights; a
+        file's owner always has the `FULL_CONTROL` right
+      * "Other" users can't have any permissions a file's group lacks,
+        and its group can't have any permissions its owner lacks; that is, 0644
+        is an acceptable mode, but 0464 is not.
+    EOT
 
     validate do |value|
       unless value.nil? or valid_symbolic_mode?(value)

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

@@ -2,8 +2,16 @@ module Puppet
   Puppet::Type.type(:file).newproperty(:owner) do
     include Puppet::Util::Warnings
 
-    desc "To whom the file should belong.  Argument can be user name or
-      user ID."
+    desc <<-EOT
+      The user to whom the file should belong.  Argument can be a user name or a
+      user ID.
+
+      On Windows, a group (such as "Administrators") can be set as a file's owner
+      and a user (such as "Administrator") can be set as a file's group; however,
+      a file's owner and group shouldn't be the same. (If the owner is also
+      the group, files with modes like `0640` will cause log churn, as they
+      will always appear out of sync.)
+    EOT
 
     def insync?(current)
       # We don't want to validate/munge users until we actually start to

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

@@ -13,55 +13,42 @@ module Puppet
 
     attr_accessor :source, :local
     desc <<-EOT
-      Copy a file over the current file.  Uses `checksum` to
-      determine when a file should be copied.  Valid values are either
-      fully qualified paths to files, or URIs.  Currently supported URI
-      types are *puppet* and *file*.
-
-      This is one of the primary mechanisms for getting content into
-      applications that Puppet does not directly support and is very
-      useful for those configuration files that don't change much across
-      sytems.  For instance:
-
-          class sendmail {
-            file { "/etc/mail/sendmail.cf":
-              source => "puppet://server/modules/module_name/sendmail.cf"
-            }
-          }
+      A source file, which will be copied into place on the local system.
+      Values can be URIs pointing to remote files, or fully qualified paths to
+      files available on the local system (including files on NFS shares or
+      Windows mapped drives). This attribute is mutually exclusive with
+      `content` and `target`.
+
+      The available URI schemes are *puppet* and *file*. *Puppet*
+      URIs will retrieve files from Puppet's built-in file server, and are
+      usually formatted as:
 
-      You can also leave out the server name, in which case `puppet agent`
-      will fill in the name of its configuration server and `puppet apply`
-      will use the local filesystem.  This makes it easy to use the same
-      configuration in both local and centralized forms.
+      `puppet:///modules/name_of_module/filename`
 
-      Currently, only the `puppet` scheme is supported for source
-      URL's. Puppet will connect to the file server running on
-      `server` to retrieve the contents of the file. If the
-      `server` part is empty, the behavior of the command-line
-      interpreter (`puppet apply`) and the client demon (`puppet agent`) differs
-      slightly: `apply` will look such a file up on the module path
-      on the local host, whereas `agent` will connect to the
-      puppet server that it received the manifest from.
+      This will fetch a file from a module on the puppet master (or from a
+      local module when using puppet apply). Given a `modulepath` of
+      `/etc/puppetlabs/puppet/modules`, the example above would resolve to
+      `/etc/puppetlabs/puppet/modules/name_of_module/files/filename`.
 
-      See the [fileserver configuration documentation](http://docs.puppetlabs.com/guides/file_serving.html)
-      for information on how to configure and use file services within Puppet.
+      Unlike `content`, the `source` attribute can be used to recursively copy
+      directories if the `recurse` attribute is set to `true` or `remote`. If
+      a source directory contains symlinks, use the `links` attribute to
+      specify whether to recreate links or follow them.
 
-      If you specify multiple file sources for a file, then the first
-      source that exists will be used.  This allows you to specify
-      what amount to search paths for files:
+      Multiple `source` values can be specified as an array, and Puppet will
+      use the first source that exists. This can be used to serve different
+      files to different system types:
 
-          file { "/path/to/my/file":
+          file { "/etc/nfs.conf":
             source => [
-              "/modules/nfs/files/file.$host",
-              "/modules/nfs/files/file.$operatingsystem",
-              "/modules/nfs/files/file"
+              "puppet:///modules/nfs/conf.$host",
+              "puppet:///modules/nfs/conf.$operatingsystem",
+              "puppet:///modules/nfs/conf"
             ]
           }
 
-      This will use the first found file as the source.
-
-      You cannot currently copy links using this mechanism; set `links`
-      to `follow` if any remote sources are links.
+      Alternately, when serving directories recursively, multiple sources can
+      be combined by setting the `sourceselect` attribute to `all`.
     EOT
 
     validate do |sources|

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

@@ -1,9 +1,10 @@
 module Puppet
   Puppet::Type.type(:file).newproperty(:target) do
     desc "The target for creating a link.  Currently, symlinks are the
-      only type supported.
+      only type supported. This attribute is mutually exclusive with `source`
+      and `content`.
 
-      You can make relative links:
+      Symlink targets can be relative, as well as absolute:
 
           # (Useful on Solaris)
           file { \"/etc/inetd.conf\":
@@ -11,10 +12,9 @@ module Puppet
             target => \"inet/inetd.conf\",
           }
 
-      You can also make recursive symlinks, which will create a
-      directory structure that maps to the target directory,
-      with directories corresponding to each directory
-      and links corresponding to each file."
+      Directories of symlinks can be served recursively by instead using the
+      `source` attribute, setting `ensure` to `directory`, and setting the
+      `links` attribute to `manage`."
 
     newvalue(:notlink) do
       # We do nothing if the value is absent

data/lib/puppet/type/group.rb

@@ -34,12 +34,13 @@ module Puppet
     end
 
     newproperty(:gid) do
-      desc "The group ID.  Must be specified numerically.  If not
-        specified, a number will be picked, which can result in ID
-        differences across systems and thus is not recommended.  The
-        GID is picked according to local system standards.
+      desc "The group ID.  Must be specified numerically.  If no group ID is
+        specified when creating a new group, then one will be chosen
+        automatically according to local system standards. This will likely
+        result in the same group having different GIDs on different systems,
+        which is not recommended.
 
-        On Windows, the property will return the group's security
+        On Windows, this property is read-only and will return the group's security
         identifier (SID)."
 
       def retrieve
@@ -91,13 +92,16 @@ module Puppet
     newparam(:name) do
       desc "The group 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 group 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 group."
       isnamevar
     end
 
     newparam(:allowdupe, :boolean => true) do
-      desc "Whether to allow duplicate GIDs.  This option does not work on
-        FreeBSD (contract to the `pw` man page)."
+      desc "Whether to allow duplicate GIDs. Defaults to `false`."
 
       newvalues(:true, :false)
 
@@ -120,7 +124,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