Please review pull request #474: Ticket/2.7.x/11535 windows provider docs opened by (nfagerlund)
Description:
This series of description string edits integrates information in the windows wiki page (https://projects.puppetlabs.com/projects/puppet/wiki/Puppet_Windows/) into the configuration, type, and provider docs. It fixes some outdated info, adds details about some Windows-specific quirks, generalizes some things that were Unix-specific, and makes other minor edits.
This series also contains a commit that documents symbolic permission modes for the file type (added in issue #2927).
- Opened: Wed Feb 08 17:20:41 UTC 2012
- Based on: puppetlabs:2.7.x (50e0863212bc02ff02467ce7c2a27ba6da225758)
- Requested merge: nfagerlund:ticket/2.7.x/11535_windows_provider_docs (31630e9368149b856ea3f411dc9089496178f121)
Diff follows:
diff --git a/lib/puppet/defaults.rb b/lib/puppet/defaults.rb
index e4c11e5..71d04df 100644
--- a/lib/puppet/defaults.rb
+++ b/lib/puppet/defaults.rb
@@ -1,10 +1,10 @@
-# The majority of the system configuration parameters are set in this file.
+# The majority of Puppet's configuration settings are set in this file.
module Puppet
setdefaults(:main,
- :confdir => [Puppet.run_mode.conf_dir, "The main Puppet configuration directory. The default for this parameter is calculated based on the user. If the process
+ :confdir => [Puppet.run_mode.conf_dir, "The main Puppet configuration directory. The default for this setting is calculated based on the user. If the process
is running as root or the user that Puppet is supposed to run as, it defaults to a system directory, but if it's running as any other user,
it defaults to being in the user's home directory."],
- :vardir => [Puppet.run_mode.var_dir, "Where Puppet stores dynamic and growing data. The default for this parameter is calculated specially, like `confdir`_."],
+ :vardir => [Puppet.run_mode.var_dir, "Where Puppet stores dynamic and growing data. The default for this setting is calculated specially, like `confdir`_."],
:name => [Puppet.application_name.to_s, "The name of the application, if we are running as one. The
default is essentially $0 without the path or `.rb`."],
:run_mode => [Puppet.run_mode.name.to_s, "The effective 'run mode' of the application: master, agent, or user."]
@@ -42,18 +42,16 @@ module Puppet
sense when used interactively. Takes into account arguments specified
on the CLI."],
:configprint => ["",
- "Print the value of a specific configuration parameter. If a
- parameter is provided for this, then the value is printed and puppet
+ "Print the value of a specific configuration setting. If the name of a
+ setting is provided for this, then the value is printed and puppet
exits. Comma-separate multiple values. For a list of all values,
- specify 'all'. This feature is only available in Puppet versions
- higher than 0.18.4."],
+ specify 'all'."],
:color => {
:default => (Puppet.features.microsoft_windows? ? "false" : "ansi"),
:type => :setting,
- :desc => "Whether to use colors when logging to the console.
- Valid values are `ansi` (equivalent to `true`), `html` (mostly
- used during testing with TextMate), and `false`, which produces
- no color.",
+ :desc => "Whether to use colors when logging to the console. Valid values are
+ `ansi` (equivalent to `true`), `html`, and `false`, which produces no color.
+ Defaults to false on Windows, as its console does not support ansi colors.",
},
:mkusers => [false,
"Whether to create the necessary user and group that puppet agent will
@@ -94,9 +92,9 @@ module Puppet
$LOAD_PATH << value
end
},
- :ignoreimport => [false, "A parameter that can be used in commit
- hooks, since it enables you to parse-check a single file rather
- than requiring that all files exist."],
+ :ignoreimport => [false, "If true, allows the parser to continue without requiring
+ all files referenced with `import` statements to exist. This setting was primarily
+ designed for use with commit hooks for parse-checking."],
:authconfig => [ "$confdir/namespaceauth.conf",
"The configuration file that defines the rights to the different
namespaces and methods. This can be used as a coarse-grained
@@ -107,10 +105,13 @@ module Puppet
is used to find modules and much more. For servers (i.e., `puppet master`) this provides the default environment for nodes
we know nothing about."
},
- :diff_args => ["-u", "Which arguments to pass to the diff command when printing differences between files."],
+ :diff_args => ["-u", "Which arguments to pass to the diff command when printing differences between
+ files. The command to use can be chosen with the `diff` setting."],
:diff => {
:default => (Puppet.features.microsoft_windows? ? "" : "diff"),
- :desc => "Which diff command to use when printing differences between files.",
+ :desc => "Which diff command to use when printing differences between files. This setting
+ has no default value on Windows, as standard `diff` is not available, but Puppet can use many
+ third-party diff tools.",
},
:show_diff => [false, "Whether to log and report a contextual diff when files are being replaced. This causes
partial file contents to pass through Puppet's normal logging and reporting system, so this setting should be
@@ -118,7 +119,8 @@ module Puppet
This feature currently requires the `diff/lcs` Ruby library."],
:daemonize => {
:default => (Puppet.features.microsoft_windows? ? false : true),
- :desc => "Send the process into the background. This is the default.",
+ :desc => "Whether to send the process into the background. This defaults to true on POSIX systems,
+ and to false on Windows (where Puppet currently cannot daemonize).",
:short => "D",
:hook => proc do |value|
if value and Puppet.features.microsoft_windows?
@@ -424,12 +426,12 @@ module Puppet
uses that configuration file to determine which keys to sign."},
:allow_duplicate_certs => [false, "Whether to allow a new certificate
request to overwrite an existing certificate."],
- :ca_days => ["", "How long a certificate should be valid.
- This parameter is deprecated, use ca_ttl instead"],
+ :ca_days => ["", "How long a certificate should be valid, in days.
+ This setting is deprecated; use `ca_ttl` instead"],
:ca_ttl => ["5y", "The default TTL for new certificates; valid values
must be an integer, optionally followed by one of the units
'y' (years of 365 days), 'd' (days), 'h' (hours), or
- 's' (seconds). The unit defaults to seconds. If this parameter
+ 's' (seconds). The unit defaults to seconds. If this setting
is set, ca_days is ignored. Examples are '3600' (one hour)
and '1825d', which is the same as '5y' (5 years) "],
:ca_md => ["md5", "The type of hash used in certificates."],
@@ -507,7 +509,7 @@ module Puppet
:ca => [true, "Wether the master should function as a certificate authority."],
:modulepath => {
:default => "$confdir/modules#{File::PATH_SEPARATOR}/usr/share/puppet/modules",
- :desc => "The search path for modules as a list of directories separated by the '#{File::PATH_SEPARATOR}' character.",
+ :desc => "The search path for modules, as a list of directories separated by the system path separator character. (The POSIX path separator is ':', and the Windows path separator is ';'.)",
:type => :setting # We don't want this to be considered a file, since it's multiple files.
},
:ssl_client_header => ["HTTP_X_CLIENT_DN", "The header containing an authenticated
@@ -758,7 +760,7 @@ module Puppet
:main,
:factpath => {:default => "$vardir/lib/facter#{File::PATH_SEPARATOR}$vardir/facts",
:desc => "Where Puppet should look for facts. Multiple directories should
- be colon-separated, like normal PATH variables.",
+ be separated by the system path separator character. (The POSIX path separator is ':', and the Windows path separator is ';'.)",
:call_on_define => true, # Call our hook with the default value, so we always get the value added to facter.
:type => :setting, # Don't consider it a file, because it could be multiple colon-separated files
@@ -844,10 +846,10 @@ module Puppet
:main,
:external_nodes => ["none",
- "An external command that can produce node information. The output
- must be a YAML dump of a hash, and that hash must have one or both of
- `classes` and `parameters`, where `classes` is an array and
- `parameters` is a hash. For unknown nodes, the commands should
+ "An external command that can produce node information. The command's output
+ must be a YAML dump of a hash, and that hash must have a `classes` key and/or
+ a `parameters` key, where `classes` is an array or hash and
+ `parameters` is a hash. For unknown nodes, the command should
exit with a non-zero exit code.
This command makes it straightforward to store your node mapping
diff --git a/lib/puppet/provider/exec/windows.rb b/lib/puppet/provider/exec/windows.rb
index 76ca1b3..ee12680 100644
--- a/lib/puppet/provider/exec/windows.rb
+++ b/lib/puppet/provider/exec/windows.rb
@@ -6,9 +6,31 @@
confine :operatingsystem => :windows
defaultfor :operatingsystem => :windows
- desc "Execute external binaries directly, on Windows systems.
-This does not pass through a shell, or perform any interpolation, but
-only directly calls the command with the arguments given."
+ desc <<-EOT
+ Execute external binaries on Windows systems. As with the `posix`
+ provider, this provider directly calls the command with the arguments
+ given, without passing it through a shell or performing any interpolation.
+ To use shell built-ins --- that is, to emulate the `shell` provider on
+ Windows --- a command must explicitly invoke the shell:
+
+ exec {'echo foo':
+ command => 'cmd.exe /c echo "foo"',
+ }
+
+ If no extension is specified for a command, Windows will use the `PATHEXT`
+ environment variable to locate the executable.
+
+ **Note on PowerShell scripts:** PowerShell's default `restricted`
+ execution policy doesn't allow it to run saved scripts. To run PowerShell
+ scripts, specify the `remotesigned` execution policy as part of the
+ command:
+
+ exec { 'test':
+ path => 'C:/Windows/System32/WindowsPowerShell/v1.0',
+ command => 'powershell -executionpolicy remotesigned -file C:/test.ps1',
+ }
+
+ EOT
# Verify that we have the executable
def checkexe(command)
diff --git a/lib/puppet/provider/file/posix.rb b/lib/puppet/provider/file/posix.rb
index 480bbe4..5ab84b4 100644
--- a/lib/puppet/provider/file/posix.rb
+++ b/lib/puppet/provider/file/posix.rb
@@ -1,5 +1,5 @@
Puppet::Type.type(:file).provide :posix do
- desc "Uses POSIX functionality to manage file's users and rights."
+ desc "Uses POSIX functionality to manage file ownership and permissions."
confine :feature => :posix
diff --git a/lib/puppet/provider/file/windows.rb b/lib/puppet/provider/file/windows.rb
index 254fba3..bb31df9 100644
--- a/lib/puppet/provider/file/windows.rb
+++ b/lib/puppet/provider/file/windows.rb
@@ -1,5 +1,5 @@
Puppet::Type.type(:file).provide :windows do
- desc "Uses Microsoft Windows functionality to manage file's users and rights."
+ desc "Uses Microsoft Windows functionality to manage file ownership and permissions."
confine :operatingsystem => :windows
diff --git a/lib/puppet/provider/group/windows_adsi.rb b/lib/puppet/provider/group/windows_adsi.rb
index 83dd00b..6d086da 100644
--- a/lib/puppet/provider/group/windows_adsi.rb
+++ b/lib/puppet/provider/group/windows_adsi.rb
@@ -1,7 +1,7 @@
require 'puppet/util/adsi'
Puppet::Type.type(:group).provide :windows_adsi do
- desc "Group management for Windows"
+ desc "Local group management for Windows. Nested groups are not supported."
defaultfor :operatingsystem => :windows
confine :operatingsystem => :windows
diff --git a/lib/puppet/provider/package/msi.rb b/lib/puppet/provider/package/msi.rb
index c2ab37d..86b5eac 100644
--- a/lib/puppet/provider/package/msi.rb
+++ b/lib/puppet/provider/package/msi.rb
@@ -1,7 +1,13 @@
require 'puppet/provider/package'
Puppet::Type.type(:package).provide(:msi, :parent => Puppet::Provider::Package) do
- desc "Package management by installing and removing MSIs."
+ desc "Windows package management by installing and removing MSIs.
+
+ This provider requires a `source` attribute, and will accept paths to local
+ files or files on mapped drives.
+
+ This provider cannot uninstall arbitrary MSI packages; it can only uninstall
+ packages which were originally installed by Puppet."
confine :operatingsystem => :windows
defaultfor :operatingsystem => :windows
diff --git a/lib/puppet/provider/scheduled_task/win32_taskscheduler.rb b/lib/puppet/provider/scheduled_task/win32_taskscheduler.rb
index a3d8084..3e8f2bc 100644
--- a/lib/puppet/provider/scheduled_task/win32_taskscheduler.rb
+++ b/lib/puppet/provider/scheduled_task/win32_taskscheduler.rb
@@ -6,8 +6,12 @@
end
Puppet::Type.type(:scheduled_task).provide(:win32_taskscheduler) do
- desc 'This uses the win32-taskscheduler gem to provide support for
- managing scheduled tasks on Windows.'
+ desc %q{This provider uses the win32-taskscheduler gem to manage scheduled
+ tasks on Windows.
+
+ Puppet requires version 0.2.1 or later of the win32-taskscheduler gem;
+ previous versions can cause "Could not evaluate: The operation completed
+ successfully" errors.}
defaultfor :operatingsystem => :windows
confine :operatingsystem => :windows
diff --git a/lib/puppet/provider/service/windows.rb b/lib/puppet/provider/service/windows.rb
index e773fa5..717e585 100644
--- a/lib/puppet/provider/service/windows.rb
+++ b/lib/puppet/provider/service/windows.rb
@@ -5,11 +5,12 @@
Puppet::Type.type(:service).provide :windows do
desc <<-EOT
- Support for Windows Service Control Manager (SCM).
+ Support for Windows Service Control Manager (SCM). This provider can
+ start, stop, enable, and disable services, and the SCM provides working
+ status methods for all services.
- Services are controlled according to the capabilities of the `win32-service`
- gem. All SCM operations (start/stop/enable/disable/query) are supported.
- Control of service groups (dependencies) is not yet supported.
+ Control of service groups (dependencies) is not yet supported, nor is running
+ services as a specific user.
EOT
defaultfor :operatingsystem => :windows
diff --git a/lib/puppet/provider/user/windows_adsi.rb b/lib/puppet/provider/user/windows_adsi.rb
index 045a84b..e3d323d 100644
--- a/lib/puppet/provider/user/windows_adsi.rb
+++ b/lib/puppet/provider/user/windows_adsi.rb
@@ -1,7 +1,7 @@
require 'puppet/util/adsi'
Puppet::Type.type(:user).provide :windows_adsi do
- desc "User management for Windows."
+ desc "Local user management for Windows."
defaultfor :operatingsystem => :windows
confine :operatingsystem => :windows
diff --git a/lib/puppet/type/file.rb b/lib/puppet/type/file.rb
index a7608c9..fe08082 100644
--- a/lib/puppet/type/file.rb
+++ b/lib/puppet/type/file.rb
@@ -17,16 +17,18 @@
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 @@ def self.title_patterns
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 @@ def self.title_patterns
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 @@ def self.title_patterns
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
diff --git a/lib/puppet/type/file/checksum.rb b/lib/puppet/type/file/checksum.rb
index 5586b13..3fd37d4 100755
--- a/lib/puppet/type/file/checksum.rb
+++ b/lib/puppet/type/file/checksum.rb
@@ -5,9 +5,9 @@
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"
diff --git a/lib/puppet/type/file/content.rb b/lib/puppet/type/file/content.rb
index 8f3b8b4..b1009a2 100755
--- a/lib/puppet/type/file/content.rb
+++ b/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.
diff --git a/lib/puppet/type/file/ensure.rb b/lib/puppet/type/file/ensure.rb
index b7614f3..9979f76 100755
--- a/lib/puppet/type/file/ensure.rb
+++ b/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:
diff --git a/lib/puppet/type/file/group.rb b/lib/puppet/type/file/group.rb
index 4310a10..a904996 100755
--- a/lib/puppet/type/file/group.rb
+++ b/lib/puppet/type/file/group.rb
@@ -3,8 +3,16 @@
# 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 != ""
diff --git a/lib/puppet/type/file/mode.rb b/lib/puppet/type/file/mode.rb
index 8c7020b..b5dd2e2 100755
--- a/lib/puppet/type/file/mode.rb
+++ b/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)
diff --git a/lib/puppet/type/file/owner.rb b/lib/puppet/type/file/owner.rb
index 2eda3c4..3b61b40 100755
--- a/lib/puppet/type/file/owner.rb
+++ b/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
diff --git a/lib/puppet/type/file/source.rb b/lib/puppet/type/file/source.rb
index 5d4fb9b..6912853 100755
--- a/lib/puppet/type/file/source.rb
+++ b/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|
diff --git a/lib/puppet/type/file/target.rb b/lib/puppet/type/file/target.rb
index 017b4f4..e1dbdea 100644
--- a/lib/puppet/type/file/target.rb
+++ b/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
diff --git a/lib/puppet/type/group.rb b/lib/puppet/type/group.rb
index 8fd5761..93146b7 100755
--- a/lib/puppet/type/group.rb
+++ b/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 @@ def change_to_s(currentvalue, newvalue)
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)
diff --git a/lib/puppet/type/package.rb b/lib/puppet/type/package.rb
index 18ee854..bfd6e42 100644
--- a/lib/puppet/type/package.rb
+++ b/lib/puppet/type/package.rb
@@ -302,8 +302,25 @@ def should_to_s(newvalue = @should)
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
diff --git a/lib/puppet/type/scheduled_task.rb b/lib/puppet/type/scheduled_task.rb
index d83adcb..8eff926 100644
--- a/lib/puppet/type/scheduled_task.rb
+++ b/lib/puppet/type/scheduled_task.rb
@@ -3,98 +3,16 @@
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 @@
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 @@
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 @@
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 @@ def insync?(current)
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 @@ def insync?(current)
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)
diff --git a/lib/puppet/type/service.rb b/lib/puppet/type/service.rb
index 2a89f66..9f70ff1 100644
--- a/lib/puppet/type/service.rb
+++ b/lib/puppet/type/service.rb
@@ -118,8 +118,14 @@ def sync
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
diff --git a/lib/puppet/type/user.rb b/lib/puppet/type/user.rb
index 71c2080..caadf91 100755
--- a/lib/puppet/type/user.rb
+++ b/lib/puppet/type/user.rb
@@ -113,8 +113,10 @@ def retrieve
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 @@ def sync
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 @@ def should_to_s( newvalue )
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
-- You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to [email protected].
For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.
