Type Reference
Type Reference
This page is autogenerated; any changes will get overwritten (last generated on Fri Jul 19 16:06:17 -0700 2013)
Resource Types
-
The namevar is the parameter used to uniquely identify a type instance. This is the parameter that gets assigned when a string is provided before the colon in a type declaration. In general, only developers will need to worry about which parameter is the
namevar
.In the following code:
file { "/etc/passwd": owner => root, group => root, mode => 644 }
/etc/passwd
is considered the title of the file object (used for things like dependency handling), and becausepath
is the namevar forfile
, that string is assigned to thepath
parameter. -
Parameters determine the specific configuration of the instance. They either directly modify the system (internally, these are called properties) or they affect how the instance behaves (e.g., adding a search path for
exec
instances or determining recursion onfile
instances). -
Providers provide low-level functionality for a given resource type. This is usually in the form of calling out to external commands.
When required binaries are specified for providers, fully qualifed paths indicate that the binary must exist at that specific path and unqualified binaries indicate that Puppet will search for the binary using the shell path.
-
Features are abilities that some providers might not support. You can use the list of supported features to determine how a given provider can be used.
Resource types define features they can use, and providers can be tested to see which features they provide.
augeas
Apply a change or an array of changes to the filesystem using the augeas tool.
Requires:
- Augeas
- The ruby-augeas bindings
Sample usage with a string:
augeas{"test1" :
context => "/files/etc/sysconfig/firstboot",
changes => "set RUN_FIRSTBOOT YES",
onlyif => "match other_value size > 0",
}
Sample usage with an array and custom lenses:
augeas{"jboss_conf":
context => "/files",
changes => [
"set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
"set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
],
load_path => "$/usr/share/jbossas/lenses",
}
Features
- execute_changes: Actually make the changes
- need_to_run?: If the command should run
- parse_commands: Parse the command string
| Provider | execute changes | need to run? | parse commands |
|---|---|---|---|
| augeas | X | X | X |
Parameters
- changes
- The changes which should be applied to the filesystem. This
can be a command or an array of commands. The following commands are supported:
set <PATH> <VALUE>
- Sets the value
VALUE
at loctionPATH
setm <PATH> <SUB> <VALUE>
- Sets multiple nodes (matching
SUB
relative toPATH
) toVALUE
rm <PATH>
- Removes the node at location
PATH
remove <PATH>
- Synonym for
rm
clear <PATH>
- Sets the node at
PATH
toNULL
, creating it if needed clearm <PATH> <SUB>
- Sets multiple nodes (matching
SUB
relative toPATH
) toNULL
ins <LABEL> (before|after) <PATH>
- Inserts an empty node
LABEL
either before or afterPATH
. insert <LABEL> <WHERE> <PATH>
- Synonym for
ins
mv <PATH> <OTHER PATH>
- Moves a node at
PATH
to the new locationOTHER PATH
move <PATH> <OTHER PATH>
- Synonym for
mv
defvar <NAME> <PATH>
- Sets Augeas variable
$NAME
toPATH
defnode <NAME> <PATH> <VALUE>
- Sets Augeas variable
$NAME
toPATH
, creating it withVALUE
if needed
If the
context
parameter is set, that value is prepended to any relativePATH
s. - context
- Optional context path. This value is prepended to the paths of all
changes if the path is relative. If the
incl
parameter is set, defaults to/files + incl
; otherwise, defaults to the empty string. - force
- Optional command to force the augeas type to execute even if it thinks changes
will not be made. This does not overide the
onlyif
parameter. - incl
- Load only a specific file, e.g.
/etc/hosts
. This can greatly speed up the execution the resource. When this parameter is set, you must also set thelens
parameter to indicate which lens to use. - lens
- Use a specific lens, e.g.
Hosts.lns
. When this parameter is set, you must also set theincl
parameter to indicate which file to load. - load_path
- Optional colon-separated list or array of directories; these directories are searched for schema definitions. The agent’s
$libdir/augeas/lenses
path will always be added to support pluginsync. - name
- The name of this task. Used for uniqueness.
- onlyif
- Optional augeas command and comparisons to control the execution of this type.
Supported onlyif syntax:
get <AUGEAS_PATH> <COMPARATOR> <STRING>
match <MATCH_PATH> size <COMPARATOR> <INT>
match <MATCH_PATH> include <STRING>
match <MATCH_PATH> not_include <STRING>
match <MATCH_PATH> == <AN_ARRAY>
match <MATCH_PATH> != <AN_ARRAY>
where:
AUGEAS_PATH
is a valid path scoped by the contextMATCH_PATH
is a valid match synatx scoped by the contextCOMPARATOR
is one of>, >=, !=, ==, <=,
or<
STRING
is a stringINT
is a numberAN_ARRAY
is in the form['a string', 'another']
- provider
- The specific backend to use for this
augeas
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- augeas
- Supported features:
execute_changes
,need_to_run?
,parse_commands
.
- returns
- The expected return code from the augeas command. Should not be set.
- root
- A file system path; all files loaded by Augeas are loaded underneath
root
. - type_check
- Whether augeas should perform typechecking. Defaults to false. Valid values are
true
,false
.
computer
Computer object management using DirectoryService on OS X.
Note that these are distinctly different kinds of objects to ‘hosts’, as they require a MAC address and can have all sorts of policy attached to them.
This provider only manages Computer objects in the local directory service domain, not in remote directories.
If you wish to manage /etc/hosts
file on Mac OS X, then simply use the host
type as per other platforms.
This type primarily exists to create localhost Computer objects that MCX policy can then be attached to.
Autorequires: If Puppet is managing the plist file representing a
Computer object (located at /var/db/dslocal/nodes/Default/computers/{name}.plist
),
the Computer resource will autorequire it.
Parameters
- en_address
- The MAC address of the primary network interface. Must match en0.
- ensure
- Control the existences of this computer record. Set this attribute to
present
to ensure the computer record exists. Set it toabsent
to delete any computer records with this name Valid values arepresent
,absent
. - ip_address
- The IP Address of the Computer object.
- name
- The authoritative ‘short’ name of the computer record.
- provider
- The specific backend to use for this
computer
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- directoryservice
- Computer object management using DirectoryService on OS X.
Note that these are distinctly different kinds of objects to ‘hosts’,
as they require a MAC address and can have all sorts of policy attached to
them.
This provider only manages Computer objects in the local directory service domain, not in remote directories.
If you wish to manage /etc/hosts on Mac OS X, then simply use the host type as per other platforms.
Default for
operatingsystem
==darwin
.
- realname
- The ‘long’ name of the computer record.
cron
Installs and manages cron jobs. Every cron resource requires a command and user attribute, as well as at least one periodic attribute (hour, minute, month, monthday, weekday, or special). While the name of the cron job is not part of the actual job, it is used by Puppet to store and retrieve it.
If you specify a cron resource that duplicates the scheduling and command
used by an existing crontab entry, then Puppet will take no action and
defers to the existing crontab entry. If the duplicate cron resource
specifies ensure => absent
, all existing duplicated crontab entries will
be removed. Specifying multiple duplicate cron resources with different
ensure
states will result in undefined behavior.
Example:
cron { logrotate:
command => "/usr/sbin/logrotate",
user => root,
hour => 2,
minute => 0
}
Note that all periodic attributes can be specified as an array of values:
cron { logrotate:
command => "/usr/sbin/logrotate",
user => root,
hour => [2, 4]
}
…or using ranges or the step syntax */2
(although there’s no guarantee
that your cron
daemon supports these):
cron { logrotate:
command => "/usr/sbin/logrotate",
user => root,
hour => ['2-4'],
minute => '*/10'
}
An important note: the Cron type will not reset parameters that are
removed from a manifest. For example, removing a minute => 10
parameter
will not reset the minute component of the associated cronjob to *
.
These changes must be expressed by setting the parameter to
minute => absent
because Puppet only manages parameters that are out of
sync with manifest entries.
Parameters
- command
- The command to execute in the cron job. The environment
provided to the command varies by local system rules, and it is
best to always provide a fully qualified command. The user’s
profile is not sourced when the command is run, so if the
user’s environment is desired it should be sourced manually.
All cron parameters support
absent
as a value; this will remove any existing values for that field. - ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - environment
- Any environment settings associated with this cron job. They
will be stored between the header and the job in the crontab. There
can be no guarantees that other, earlier settings will not also
affect a given cron job.
Also, Puppet cannot automatically determine whether an existing, unmanaged environment setting is associated with a given cron job. If you already have cron jobs with environment settings, then Puppet will keep those settings in the same place in the file, but will not associate them with a specific job.
Settings should be specified exactly as they should appear in the crontab, e.g.,
PATH=/bin:/usr/bin:/usr/sbin
. - hour
- The hour at which to run the cron job. Optional; if specified, must be between 0 and 23, inclusive.
- minute
- The minute at which to run the cron job. Optional; if specified, must be between 0 and 59, inclusive.
- month
- The month of the year. Optional; if specified must be between 1 and 12 or the month name (e.g., December).
- monthday
- The day of the month on which to run the command. Optional; if specified, must be between 1 and 31.
- name
- The symbolic name of the cron job. This name is used for human reference only and is generated automatically for cron jobs found on the system. This generally won’t matter, as Puppet will do its best to match existing cron jobs against specified jobs (and Puppet adds a comment to cron jobs it adds), but it is at least possible that converting from unmanaged jobs to managed jobs might require manual intervention.
- provider
- The specific backend to use for this
cron
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- crontab
- Required binaries:
crontab
.
- special
- A special value such as ‘reboot’ or ‘annually’. Only available on supported systems such as Vixie Cron. Overrides more specific time of day/week settings.
- target
- The username that will own the cron entry. Defaults to the value of $USER for the shell that invoked Puppet, or root if $USER is empty.
- user
- The user to run the command as. This user must
be allowed to run cron jobs, which is not currently checked by
Puppet.
The user defaults to whomever Puppet is running as.
- weekday
- The weekday on which to run the command. Optional; if specified, must be between 0 and 7, inclusive, with 0 (or 7) being Sunday, or must be the name of the day (e.g., Tuesday).
exec
Executes external commands. It is critical that all commands
executed using this mechanism can be run multiple times without
harm, i.e., they are idempotent. One useful way to create idempotent
commands is to use the checks like creates
to avoid running the
command unless some condition is met.
Note that you can restrict an exec
to only run when it receives
events by using the refreshonly
parameter; this is a useful way to
have your configuration respond to events with arbitrary commands.
Note also that if an exec
receives an event from another resource,
it will get executed again (or execute the command specified in refresh
, if there is one).
There is a strong tendency to use exec
to do whatever work Puppet
can’t already do; while this is obviously acceptable (and unavoidable)
in the short term, it is highly recommended to migrate work from exec
to native Puppet types as quickly as possible. If you find that
you are doing a lot of work with exec
, please at least notify
us at Puppet Labs what you are doing, and hopefully we can work with
you to get a native resource type for the work you are doing.
Autorequires: If Puppet is managing an exec’s cwd or the executable file used in an exec’s command, the exec resource will autorequire those files. If Puppet is managing the user that an exec should run as, the exec resource will autorequire that user.
Parameters
- command
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The actual command to execute. Must either be fully qualified or a search path for the command must be provided. If the command succeeds, any output produced will be logged at the instance’s normal log level (usually
notice
), but if the command fails (meaning its return code does not match the specified code) then any output is logged at theerr
log level. - creates
- A file to look for before running the command. The command will
only run if the file doesn’t exist.
This parameter doesn’t cause Puppet to create a file; it is only useful if the command itself creates a file.
exec { "tar -xf /Volumes/nfs02/important.tar": cwd => "/var/tmp", creates => "/var/tmp/myfile", path => ["/usr/bin", "/usr/sbin"] }
In this example,
myfile
is assumed to be a file insideimportant.tar
. If it is ever deleted, the exec will bring it back by re-extracting the tarball. Ifimportant.tar
does not actually containmyfile
, the exec will keep running every time Puppet runs. - cwd
- The directory from which to run the command. If this directory does not exist, the command will fail.
- environment
- Any additional environment variables you want to set for a
command. Note that if you use this to set PATH, it will override
the
path
attribute. Multiple environment variables should be specified as an array. - group
- The group to run the command as. This seems to work quite haphazardly on different platforms – it is a platform issue not a Ruby or Puppet one, since the same variety exists when running commands as different users in the shell.
- logoutput
- Whether to log command output in addition to logging the
exit code. Defaults to
on_failure
, which only logs the output when the command has an exit code that does not match any value specified by thereturns
attribute. In addition to the values below, you may set this attribute to any legal log level. Valid values aretrue
,false
,on_failure
. - onlyif
- If this parameter is set, then this
exec
will only run if the command returns 0. For example:exec { "logrotate": path => "/usr/bin:/usr/sbin:/bin", onlyif => "test `du /var/log/messages | cut -f1` -gt 100000" }
This would run
logrotate
only if that test returned true.Note that this command follows the same rules as the main command, which is to say that it must be fully qualified if the path is not set.
Also note that onlyif can take an array as its value, e.g.:
onlyif => ["test -f /tmp/file1", "test -f /tmp/file2"]
This will only run the exec if all conditions in the array return true.
- path
- The search path used for command execution. Commands must be fully qualified if no path is specified. Paths can be specified as an array or as a ‘:’ separated list.
- provider
- The specific backend to use for this
exec
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- posix
- Executes external binaries directly, without passing through a shell or
performing any interpolation. This is a safer and more predictable way
to execute most commands, but prevents the use of globbing and shell
built-ins (including control logic like “for” and “if” statements).
Default for
feature
==posix
. - shell
- Passes the provided command through
/bin/sh
; only available on POSIX systems. This allows the use of shell globbing and built-ins, and does not require that the path to a command be fully-qualified. Although this can be more convenient than theposix
provider, it also means that you need to be more careful with escaping; as ever, with great power comes etc. etc.This provider closely resembles the behavior of the
exec
type in Puppet 0.25.x. - windows
- 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 theshell
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 theremotesigned
execution policy as part of the command:exec { 'test': path => 'C:/Windows/System32/WindowsPowerShell/v1.0', command => 'powershell -executionpolicy remotesigned -file C:/test.ps1', }
Default for
operatingsystem
==windows
.
- refresh
- How to refresh this command. By default, the exec is just called again when it receives an event from another resource, but this parameter allows you to define a different command for refreshing.
- refreshonly
- The command should only be run as a
refresh mechanism for when a dependent object is changed. It only
makes sense to use this option when this command depends on some
other object; it is useful for triggering an action:
# Pull down the main aliases file file { "/etc/aliases": source => "puppet://server/module/aliases" } # Rebuild the database, but only when the file changes exec { newaliases: path => ["/usr/bin", "/usr/sbin"], subscribe => File["/etc/aliases"], refreshonly => true }
Note that only
subscribe
andnotify
can trigger actions, notrequire
, so it only makes sense to userefreshonly
withsubscribe
ornotify
. Valid values aretrue
,false
. - returns
- The expected return code(s). An error will be returned if the executed command returns something else. Defaults to 0. Can be specified as an array of acceptable return codes or a single value.
- timeout
- The maximum time the command should take. If the command takes longer than the timeout, the command is considered to have failed and will be stopped. The timeout is specified in seconds. The default timeout is 300 seconds and you can set it to 0 to disable the timeout.
- tries
- The number of times execution of the command should be tried. Defaults to ‘1’. This many attempts will be made to execute the command until an acceptable return code is returned. Note that the timeout paramater applies to each try rather than to the complete set of tries.
- try_sleep
- The time to sleep in seconds between ‘tries’.
- unless
- If this parameter is set, then this
exec
will run unless the command returns 0. For example:exec { "/bin/echo root >> /usr/lib/cron/cron.allow": path => "/usr/bin:/usr/sbin:/bin", unless => "grep root /usr/lib/cron/cron.allow 2>/dev/null" }
This would add
root
to the cron.allow file (on Solaris) unlessgrep
determines it’s already there.Note that this command follows the same rules as the main command, which is to say that it must be fully qualified if the path is not set.
- user
- The user to run the command as. Note that if you
use this then any error output is not currently captured. This
is because of a bug within Ruby. If you are using Puppet to
create this user, the exec will automatically require the user,
as long as it is specified by name.
Please also note that $HOME is not set when using this option.
file
Manages files, including their content, ownership, and permissions.
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 parent directories of a file, the file resource will autorequire them.
Parameters
- backup
- Whether (and how) file content should be backed up before being replaced.
This attribute works best as a resource default in the site manifest
(
File { backup => main }
), so it can affect all file resources.- If set to
false
, file content won’t be backed up. - If set to a string beginning with
.
(e.g.,.puppet-bak
), Puppet will use copy the file in the same directory with that value as the extension of the backup. (A value oftrue
is a synonym for.puppet-bak
.) - If set to any other string, Puppet will try to back up to a filebucket
with that title. See the
filebucket
resource type for more details. (This is the preferred method for backup, since it can be centralized and queried.)
Default value:
puppet
, which backs up to a filebucket of the same name. (Puppet automatically creates a local filebucket namedpuppet
if one doesn’t already exist.)Backing up to a local filebucket isn’t particularly useful. If you want to make organized use of backups, you will generally want to use the puppet master server’s filebucket service. This requires declaring a filebucket resource and a resource default for the
backup
attribute in site.pp:# /etc/puppet/manifests/site.pp filebucket { 'main': path => false, # This is required for remote filebuckets. server => 'puppet.example.com', # Optional; defaults to the configured puppet master. } File { backup => main, }
If you are using multiple puppet master servers, you will want to centralize the contents of the filebucket. Either configure your load balancer to direct all filebucket traffic to a single master, or use something like an out-of-band rsync task to synchronize the content on all masters.
- If set to
- checksum
- The checksum type to use when determining whether to replace a file’s contents.
The default checksum type is md5. Valid values are
md5
,md5lite
,mtime
,ctime
,none
. - content
- The desired contents of a file, as a string. This attribute is mutually
exclusive with
source
andtarget
.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 domain $domain nameserver $nameserver1 nameserver $nameserver2 " file { "/etc/resolv.conf": content => "$str", } }
…but for larger files, this attribute is more useful when combined with the template function.
- ctime
- A read-only state to check the file ctime.
- ensure
- Whether to create files that don’t currently exist.
Possible values are
absent
,present
,file
,directory
, andlink
. Specifyingpresent
will match any form of file existence, and if the file is missing will create an empty file. Specifyingabsent
will delete the file (or directory, ifrecurse => true
andforce => true
). Specifyinglink
requires that you also set thetarget
attribute; note that symlinks cannot be managed on Windows.If you specify the path to another file as the ensure value, it is equivalent to specifying
link
and using that path as thetarget
:# Equivalent resources: file { "/etc/inetd.conf": ensure => "/etc/inet/inetd.conf", } file { "/etc/inetd.conf": ensure => link, target => "/etc/inet/inetd.conf", }
However, we recommend using
link
andtarget
explicitly, since this behavior can be harder to read. Valid values areabsent
(also calledfalse
),file
,present
,directory
,link
. Values can match/./
. - force
- Perform the file operation even if it will destroy one or more directories.
You must use
force
in order to:purge
subdirectories- Replace directories with files or links
- Remove a directory when
ensure => absent
Valid values aretrue
,false
.
- group
- 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.) - ignore
- A parameter which omits action on files matching
specified patterns during recursion. Uses Ruby’s builtin globbing
engine, so shell metacharacters are fully supported, e.g.
[a-z]*
. Matches that would descend into the directory structure are ignored, e.g.,*/*
. - links
- How to handle links during file actions. During file copying,
follow
will copy the target file instead of the link,manage
will copy the link itself, andignore
will just pass it by. When not copying,manage
andignore
behave equivalently (because you cannot really ignore links entirely during local recursion), andfollow
will manage the file to which the link points. Valid values arefollow
,manage
. - mode
- 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 eithera=r,ug+w
orug=rw,o=r
. See the manual page for GNU or BSDchmod
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
, andFILE_GENERIC_EXECUTE
access rights; a file’s owner always has theFULL_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.
- mtime
- A read-only state to check the file mtime.
- owner
- 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.) - path
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
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\\
). - provider
- The specific backend to use for this
file
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- posix
- Uses POSIX functionality to manage file ownership and permissions.
- windows
- Uses Microsoft Windows functionality to manage file ownership and permissions.
- purge
- Whether unmanaged files should be purged. This option only makes
sense when managing directories with
recurse => true
.- When recursively duplicating an entire directory with the
source
attribute,purge => true
will automatically purge any files that are not in the source directory. - When managing files in a directory as individual resources,
setting
purge => true
will purge any files that aren’t being specifically managed.
If you have a filebucket configured, the purged files will be uploaded, but if you do not, this will destroy data. Valid values are
true
,false
. - When recursively duplicating an entire directory with the
- recurse
- Whether and how deeply to do recursive
management. Options are:
inf,true
— Regular style recursion on both remote and local directory structure.remote
— Descends recursively into the remote directory but not the local directory. Allows copying of a few files into a directory containing many unmanaged files without scanning all the local files.false
— Default of no recursion. Valid values aretrue
,false
,inf
,remote
.
- recurselimit
- How deeply to do recursive management. Values can match
/^[0-9]+$/
. - replace
- Whether to replace a file or symlink that already exists on the local system but
whose content doesn’t match what the
source
orcontent
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. Defaults totrue
. Valid values aretrue
(also calledyes
),false
(also calledno
). - selinux_ignore_defaults
- If this is set then Puppet will not ask SELinux (via matchpathcon) to
supply defaults for the SELinux attributes (seluser, selrole,
seltype, and selrange). In general, you should leave this set at its
default and only set it to true when you need Puppet to not try to fix
SELinux labels automatically. Valid values are
true
,false
. - selrange
- What the SELinux range component of the context of the file should be.
Any valid SELinux range component is accepted. For example
s0
orSystemHigh
. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled and that have support for MCS (Multi-Category Security). - selrole
- What the SELinux role component of the context of the file should be.
Any valid SELinux role component is accepted. For example
role_r
. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled. - seltype
- What the SELinux type component of the context of the file should be.
Any valid SELinux type component is accepted. For example
tmp_t
. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled. - seluser
- What the SELinux user component of the context of the file should be.
Any valid SELinux user component is accepted. For example
user_u
. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled. - show_diff
- Whether to display differences when the file changes, defaulting to
true. This parameter is useful for files that may contain passwords or
other secret data, which might otherwise be included in Puppet reports or
other insecure outputs. If the global ``show_diff
configuration parameter is false, then no diffs will be shown even if this parameter is true. Valid values are
true,
false`. - source
- 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
andtarget
.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:
puppet:///modules/name_of_module/filename
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
.Unlike
content
, thesource
attribute can be used to recursively copy directories if therecurse
attribute is set totrue
orremote
. If a source directory contains symlinks, use thelinks
attribute to specify whether to recreate links or follow them.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 { "/etc/nfs.conf": source => [ "puppet:///modules/nfs/conf.$host", "puppet:///modules/nfs/conf.$operatingsystem", "puppet:///modules/nfs/conf" ] }
Alternately, when serving directories recursively, multiple sources can be combined by setting the
sourceselect
attribute toall
. - sourceselect
- Whether to copy all valid sources, or just the first one. This parameter
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. Valid values arefirst
,all
. - target
- The target for creating a link. Currently, symlinks are the
only type supported. This attribute is mutually exclusive with
source
andcontent
.Symlink targets can be relative, as well as absolute:
# (Useful on Solaris) file { "/etc/inetd.conf": ensure => link, target => "inet/inetd.conf", }
Directories of symlinks can be served recursively by instead using the
source
attribute, settingensure
todirectory
, and setting thelinks
attribute tomanage
. Valid values arenotlink
. Values can match/./
. - type
- A read-only state to check the file type.
filebucket
A repository for storing and retrieving file content by MD5 checksum. Can be local to each agent node, or centralized on a puppet master server. All puppet masters provide a filebucket service that agent nodes can access via HTTP, but you must declare a filebucket resource before any agents will do so.
Filebuckets are used for the following features:
- Content backups. If the
file
type’sbackup
attribute is set to the name of a filebucket, Puppet will back up the old content whenever it rewrites a file; see the documentation for thefile
type for more details. These backups can be used for manual recovery of content, but are more commonly used to display changes and differences in a tool like Puppet Dashboard. - Content distribution. The optional static compiler populates the
puppet master’s filebucket with the desired content for each file,
then instructs the agent to retrieve the content for a specific
checksum. For more details,
see the
static_compiler
section in the catalog indirection docs.
To use a central filebucket for backups, you will usually want to declare
a filebucket resource and a resource default for the backup
attribute
in site.pp:
# /etc/puppet/manifests/site.pp
filebucket { 'main':
path => false, # This is required for remote filebuckets.
server => 'puppet.example.com', # Optional; defaults to the configured puppet master.
}
File { backup => main, }
Puppet master servers automatically provide the filebucket service, so
this will work in a default configuration. If you have a heavily
restricted auth.conf
file, you may need to allow access to the
file_bucket_file
endpoint.
Parameters
- name
- The name of the filebucket.
- path
- The path to the local filebucket; defaults to the value of the
clientbucketdir
setting. To use a remote filebucket, you must set this attribute tofalse
. - port
- The port on which the remote server is listening. Defaults to the
value of the
masterport
setting, which is usually 8140. - server
- The server providing the remote filebucket service. Defaults to the
value of the
server
setting (that is, the currently configured puppet master server).This setting is only consulted if the
path
attribute is set tofalse
.
group
Manage groups. On most platforms this can only create groups. Group membership must be managed on individual users.
On some platforms such as OS X, group membership is managed as an attribute of the group, not the user record. Providers must have the feature ‘manages_members’ to manage the ‘members’ property of a group record.
Features
- libuser: Allows local groups to be managed on systems that also use some other remote NSS method of managing accounts.
- manages_aix_lam: The provider can manage AIX Loadable Authentication Module (LAM) system.
- manages_members: For directories where membership is an attribute of groups not users.
- system_groups: The provider allows you to create system groups with lower GIDs.
| Provider | libuser | manages aix lam | manages members | system groups |
|---|---|---|---|---|
| aix | X | X | ||
| directoryservice | X | |||
| groupadd | X | X | ||
| ldap | ||||
| pw | X | |||
| windows_adsi | X |
Parameters
- allowdupe
- Whether to allow duplicate GIDs. Defaults to
false
. Valid values aretrue
,false
. - attribute_membership
- Whether specified attribute value pairs should be treated as the only attributes
of the user or whether they should merely
be treated as the minimum list. Valid values are
inclusive
,minimum
. - attributes
- Specify group AIX attributes in an array of
key=value
pairs. Requires features manages_aix_lam. - auth_membership
- whether the provider is authoritative for group membership.
- ensure
- Create or remove the group. Valid values are
present
,absent
. - forcelocal
- Forces the mangement of local accounts when accounts are also
being managed by some other NSS Valid values are
true
,false
. Requires features libuser. - gid
- 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, this property is read-only and will return the group’s security identifier (SID).
- ia_load_module
- The name of the I&A module to use to manage this user Requires features manages_aix_lam.
- members
- The members of the group. For directory services where group membership is stored in the group objects, not the users. Requires features manages_members.
- name
- 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.
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.
- provider
- The specific backend to use for this
group
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- aix
- Group management for AIX.
Required binaries:
/usr/sbin/lsgroup
,/usr/bin/chgroup
,/usr/sbin/rmgroup
,/usr/bin/mkgroup
. Default foroperatingsystem
==aix
. Supported features:manages_aix_lam
,manages_members
. - directoryservice
- Group management using DirectoryService on OS X.
Required binaries:
/usr/bin/dscl
. Default foroperatingsystem
==darwin
. Supported features:manages_members
. - groupadd
- Group management via
groupadd
and its ilk. The default for most platforms.Required binaries:
lgroupadd
,groupdel
,groupmod
,groupadd
. Supported features:system_groups
. - ldap
- Group management via LDAP.
This provider requires that you have valid values for all of the LDAP-related settings in
puppet.conf
, includingldapbase
. You will almost definitely need settings forldapuser
andldappassword
in order for your clients to write to LDAP.Note that this provider will automatically generate a GID for you if you do not specify one, but it is a potentially expensive operation, as it iterates across all existing groups to pick the appropriate next one.
- pw
- Group management via
pw
on FreeBSD and DragonFly BSD.Required binaries:
pw
. Default foroperatingsystem
==freebsd, dragonfly
. Supported features:manages_members
. - windows_adsi
- Local group management for Windows. Nested groups are not supported.
Default for
operatingsystem
==windows
. Supported features:manages_members
.
- system
- Whether the group is a system group with lower GID. Valid values are
true
,false
.
host
Installs and manages host entries. For most systems, these
entries will just be in /etc/hosts
, but some systems (notably OS X)
will have different solutions.
Parameters
- comment
- A comment that will be attached to the line with a # character.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - host_aliases
- Any aliases the host might have. Multiple values must be specified as an array.
- ip
- The host’s IP address, IPv4 or IPv6.
- name
- The host name.
- provider
- The specific backend to use for this
host
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:parsed :
- target
- The file in which to store service information. Only used by
those providers that write to disk. On most systems this defaults to
/etc/hosts
.
interface
This represents a router or switch interface. It is possible to manage interface mode (access or trunking, native vlan and encapsulation) and switchport characteristics (speed, duplex).
Parameters
- allowed_trunk_vlans
- Allowed list of Vlans that this trunk can forward. Valid values are
all
. Values can match/./
. - description
- Interface description.
- device_url
- The URL at which the router or switch can be reached.
- duplex
- Interface duplex. Valid values are
auto
,full
,half
. - encapsulation
- Interface switchport encapsulation. Valid values are
none
,dot1q
,isl
. - ensure
- The basic property that the resource should be in. Valid values are
present
(also calledno_shutdown
),absent
(also calledshutdown
). - etherchannel
- Channel group this interface is part of. Values can match
/^\d+/
. - ipaddress
- IP Address of this interface. Note that it might not be possible to set
an interface IP address; it depends on the interface type and device type.
Valid format of ip addresses are:
- IPV4, like <IP_ADDRESS>
- IPV4/prefixlength like <IP_ADDRESS>/24
- IPV6/prefixlength like FE80::21A:2FFF:FE30:ECF0/128
- an optional suffix for IPV6 addresses from this list:
eui-64
,link-local
It is also possible to supply an array of values.
- mode
- Interface switchport mode. Valid values are
access
,trunk
. - name
- The interface’s name.
- native_vlan
- Interface native vlan (for access mode only). Values can match
/^\d+/
. - provider
- The specific backend to use for this
interface
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- cisco
- Cisco switch/router provider for interface.
- speed
- Interface speed. Valid values are
auto
. Values can match/^\d+/
.
k5login
Manage the .k5login
file for a user. Specify the full path to
the .k5login
file as the name, and an array of principals as the
principals
attribute.
Parameters
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - mode
- The desired permissions mode of the
.k5login
file. Defaults to644
. - path
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The path to the
.k5login
file to manage. Must be fully qualified. - principals
- The principals present in the
.k5login
file. This should be specified as an array. - provider
- The specific backend to use for this
k5login
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- k5login
- The k5login provider is the only provider for the k5login type.
macauthorization
Manage the Mac OS X authorization database. See the Apple developer site for more information.
Note that authorization store directives with hyphens in their names have been renamed to use underscores, as Puppet does not react well to hyphens in identifiers.
Autorequires: If Puppet is managing the /etc/authorization
file, each
macauthorization resource will autorequire it.
Parameters
- allow_root
- Corresponds to
allow-root
in the authorization store. Specifies whether a right should be allowed automatically if the requesting process is running withuid == 0
. AuthorizationServices defaults this attribute to false if not specified. Valid values aretrue
,false
. - auth_class
- Corresponds to
class
in the authorization store; renamed due to ‘class’ being a reserved word in Puppet. Valid values areuser
,evaluate-mechanisms
,allow
,deny
,rule
. - auth_type
- Type — this can be a
right
or arule
. Thecomment
type has not yet been implemented. Valid values areright
,rule
. - authenticate_user
- Corresponds to
authenticate-user
in the authorization store. Valid values aretrue
,false
. - comment
- The
comment
attribute for authorization resources. - ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - group
- A group which the user must authenticate as a member of. This must be a single group.
- k_of_n
- How large a subset of rule mechanisms must succeed for successful
authentication. If there are ‘n’ mechanisms, then ‘k’ (the integer value
of this parameter) mechanisms must succeed. The most common setting for
this parameter is
1
. Ifk-of-n
is not set, then every mechanism — that is, ‘n-of-n’ — must succeed. - mechanisms
- An array of suitable mechanisms.
- name
- The name of the right or rule to be managed.
Corresponds to
key
in Authorization Services. The key is the name of a rule. A key uses the same naming conventions as a right. The Security Server uses a rule’s key to match the rule with a right. Wildcard keys end with a ‘.’. The generic rule has an empty key value. Any rights that do not match a specific rule use the generic rule. - provider
- The specific backend to use for this
macauthorization
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- macauthorization
- Manage Mac OS X authorization database rules and rights.
Required binaries:
/usr/bin/security
,/usr/bin/sw_vers
. Default foroperatingsystem
==darwin
.
- rule
- The rule(s) that this right refers to.
- session_owner
- Whether the session owner automatically matches this rule or right.
Corresponds to
session-owner
in the authorization store. Valid values aretrue
,false
. - shared
- Whether the Security Server should mark the credentials used to gain
this right as shared. The Security Server may use any shared credentials
to authorize this right. For maximum security, set sharing to false so
credentials stored by the Security Server for one application may not be
used by another application. Valid values are
true
,false
. - timeout
- The number of seconds in which the credential used by this rule will expire. For maximum security where the user must authenticate every time, set the timeout to 0. For minimum security, remove the timeout attribute so the user authenticates only once per session.
- tries
- The number of tries allowed.
mailalias
Creates an email alias in the local alias database.
Parameters
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - name
- The alias name.
- provider
- The specific backend to use for this
mailalias
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:aliases :
- recipient
- Where email should be sent. Multiple values should be specified as an array.
- target
- The file in which to store the aliases. Only used by those providers that write to disk.
maillist
Manage email lists. This resource type can only create and remove lists; it cannot currently reconfigure them.
Parameters
- admin
- The email address of the administrator.
- description
- The description of the mailing list.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
,purged
. - mailserver
- The name of the host handling email for the list.
- name
- The name of the email list.
- password
- The admin password.
- provider
- The specific backend to use for this
maillist
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- mailman
- Required binaries:
rmlist
,newlist
,/var/lib/mailman/mail/mailman
,list_lists
.
- webserver
- The name of the host providing web archives and the administrative interface.
mcx
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
content property of the file type in Puppet.
The recommended method of using this type is to use Work Group Manager
to manage users and groups on the local computer, record the resulting
puppet manifest using the command puppet resource mcx
, then deploy it
to other machines.
Autorequires: If Puppet is managing the user, group, or computer that these MCX settings refer to, the MCX resource will autorequire that user, group, or computer.
Features
- manages_content: The provider can manage MCXSettings as a string.
| Provider | manages content |
|---|---|
| mcxcontent | X |
Parameters
- content
- 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
Note that
ds_type
is capitalized and plural in the dscl command. Requires features manages_content. - ds_name
- The name to attach the MCX Setting to. (For example,
localhost
whends_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.) - ds_type
- The DirectoryService type this MCX setting attaches to. Valid values are
user
,group
,computer
,computerlist
. - ensure
- Create or remove the MCX setting. Valid values are
present
,absent
. - name
- The name of the resource being managed.
The default naming convention follows Directory Service paths:
/Computers/localhost /Groups/admin /Users/localadmin
The
ds_type
andds_name
type parameters are not necessary if the default naming convention is followed. - provider
- The specific backend to use for this
mcx
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- mcxcontent
- MCX Settings management using DirectoryService on OS X.
This provider manages the entire MCXSettings attribute available to some directory services nodes. This management is ‘all or nothing’ in that discrete application domain key value pairs are not managed by this provider.
It is recommended to use WorkGroup Manager to configure Users, Groups, Computers, or ComputerLists, then use ‘ralsh mcx’ to generate a puppet manifest from the resulting configuration.
Original Author: Jeff McCune<EMAIL_ADDRESS>Required binaries:
/usr/bin/dscl
. Default foroperatingsystem
==darwin
. Supported features:manages_content
.
mount
Manages mounted filesystems, including putting mount information into the mount table. The actual behavior depends on the value of the ‘ensure’ parameter.
Note that if a mount
receives an event from another resource,
it will try to remount the filesystems if ensure
is set to mounted
.
Features
- refreshable: The provider can remount the filesystem.
| Provider | refreshable |
|---|---|
| parsed | X |
Parameters
- atboot
- Whether to mount the mount at boot. Not all platforms support this.
- blockdevice
- The device to fsck. This is property is only valid on Solaris, and in most cases will default to the correct value.
- device
- The device providing the mount. This can be whatever device is supporting by the mount, including network devices or devices specified by UUID rather than device path, depending on the operating system.
- dump
- Whether to dump the mount. Not all platform support this.
Valid values are
1
or0
. or2
on FreeBSD, Default is0
. Values can match/(0|1)/
,/(0|1)/
. - ensure
- Control what to do with this mount. Set this attribute to
unmounted
to make sure the filesystem is in the filesystem table but not mounted (if the filesystem is currently mounted, it will be unmounted). Set it toabsent
to unmount (if necessary) and remove the filesystem from the fstab. Set tomounted
to add it to the fstab and mount it. Set topresent
to add to fstab but not change mount/unmount status. Valid values aredefined
(also calledpresent
),unmounted
,absent
,mounted
. - fstype
- The mount type. Valid values depend on the operating system. This is a required option.
- name
- The mount path for the mount.
- options
- Mount options for the mounts, as they would appear in the fstab.
- pass
- The pass in which the mount is checked.
- provider
- The specific backend to use for this
mount
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- parsed
- Required binaries:
mount
,umount
. Supported features:refreshable
.
- remounts
- Whether the mount can be remounted
mount -o remount
. If this is false, then the filesystem will be unmounted and remounted manually, which is prone to failure. Valid values aretrue
,false
. - target
- The file in which to store the mount table. Only used by those providers that write to disk.
nagios_command
The Nagios type command. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_command.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- command_line
- Nagios configuration file parameter.
- command_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_command resource.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - poller_tag
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_command
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_contact
The Nagios type contact. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_contact.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- address1
- Nagios configuration file parameter.
- address2
- Nagios configuration file parameter.
- address3
- Nagios configuration file parameter.
- address4
- Nagios configuration file parameter.
- address5
- Nagios configuration file parameter.
- address6
- Nagios configuration file parameter.
- alias
- Nagios configuration file parameter.
- can_submit_commands
- Nagios configuration file parameter.
- contact_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_contact resource.
- contactgroups
- Nagios configuration file parameter.
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - host_notification_commands
- Nagios configuration file parameter.
- host_notification_options
- Nagios configuration file parameter.
- host_notification_period
- Nagios configuration file parameter.
- host_notifications_enabled
- Nagios configuration file parameter.
- pager
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_contact
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- retain_nonstatus_information
- Nagios configuration file parameter.
- retain_status_information
- Nagios configuration file parameter.
- service_notification_commands
- Nagios configuration file parameter.
- service_notification_options
- Nagios configuration file parameter.
- service_notification_period
- Nagios configuration file parameter.
- service_notifications_enabled
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_contactgroup
The Nagios type contactgroup. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_contactgroup.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- alias
- Nagios configuration file parameter.
- contactgroup_members
- Nagios configuration file parameter.
- contactgroup_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_contactgroup resource.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - members
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_contactgroup
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_host
The Nagios type host. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_host.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- action_url
- Nagios configuration file parameter.
- active_checks_enabled
- Nagios configuration file parameter.
- address
- Nagios configuration file parameter.
- alias
- Nagios configuration file parameter.
- business_impact
- Nagios configuration file parameter.
- check_command
- Nagios configuration file parameter.
- check_freshness
- Nagios configuration file parameter.
- check_interval
- Nagios configuration file parameter.
- check_period
- Nagios configuration file parameter.
- contact_groups
- Nagios configuration file parameter.
- contacts
- Nagios configuration file parameter.
- display_name
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - event_handler
- Nagios configuration file parameter.
- event_handler_enabled
- Nagios configuration file parameter.
- failure_prediction_enabled
- Nagios configuration file parameter.
- first_notification_delay
- Nagios configuration file parameter.
- flap_detection_enabled
- Nagios configuration file parameter.
- flap_detection_options
- Nagios configuration file parameter.
- freshness_threshold
- Nagios configuration file parameter.
- high_flap_threshold
- Nagios configuration file parameter.
- host_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_host resource.
- hostgroups
- Nagios configuration file parameter.
- icon_image
- Nagios configuration file parameter.
- icon_image_alt
- Nagios configuration file parameter.
- initial_state
- Nagios configuration file parameter.
- low_flap_threshold
- Nagios configuration file parameter.
- max_check_attempts
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- notification_interval
- Nagios configuration file parameter.
- notification_options
- Nagios configuration file parameter.
- notification_period
- Nagios configuration file parameter.
- notifications_enabled
- Nagios configuration file parameter.
- obsess_over_host
- Nagios configuration file parameter.
- parents
- Nagios configuration file parameter.
- passive_checks_enabled
- Nagios configuration file parameter.
- poller_tag
- Nagios configuration file parameter.
- process_perf_data
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_host
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- realm
- Nagios configuration file parameter.
- register
- Nagios configuration file parameter.
- retain_nonstatus_information
- Nagios configuration file parameter.
- retain_status_information
- Nagios configuration file parameter.
- retry_interval
- Nagios configuration file parameter.
- stalking_options
- Nagios configuration file parameter.
- statusmap_image
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
- vrml_image
- Nagios configuration file parameter.
nagios_hostdependency
The Nagios type hostdependency. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_hostdependency.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_hostdependency resource.
- dependency_period
- Nagios configuration file parameter.
- dependent_host_name
- Nagios configuration file parameter.
- dependent_hostgroup_name
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - execution_failure_criteria
- Nagios configuration file parameter.
- host_name
- Nagios configuration file parameter.
- hostgroup_name
- Nagios configuration file parameter.
- inherits_parent
- Nagios configuration file parameter.
- notification_failure_criteria
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_hostdependency
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_hostescalation
The Nagios type hostescalation. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_hostescalation.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_hostescalation resource.
- contact_groups
- Nagios configuration file parameter.
- contacts
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - escalation_options
- Nagios configuration file parameter.
- escalation_period
- Nagios configuration file parameter.
- first_notification
- Nagios configuration file parameter.
- host_name
- Nagios configuration file parameter.
- hostgroup_name
- Nagios configuration file parameter.
- last_notification
- Nagios configuration file parameter.
- notification_interval
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_hostescalation
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_hostextinfo
The Nagios type hostextinfo. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_hostextinfo.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - host_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_hostextinfo resource.
- icon_image
- Nagios configuration file parameter.
- icon_image_alt
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_hostextinfo
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- statusmap_image
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
- vrml_image
- Nagios configuration file parameter.
nagios_hostgroup
The Nagios type hostgroup. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_hostgroup.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- action_url
- Nagios configuration file parameter.
- alias
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - hostgroup_members
- Nagios configuration file parameter.
- hostgroup_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_hostgroup resource.
- members
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_hostgroup
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- realm
- Nagios configuration file parameter.
- register
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_service
The Nagios type service. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_service.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_service resource.
- action_url
- Nagios configuration file parameter.
- active_checks_enabled
- Nagios configuration file parameter.
- business_impact
- Nagios configuration file parameter.
- check_command
- Nagios configuration file parameter.
- check_freshness
- Nagios configuration file parameter.
- check_interval
- Nagios configuration file parameter.
- check_period
- Nagios configuration file parameter.
- contact_groups
- Nagios configuration file parameter.
- contacts
- Nagios configuration file parameter.
- display_name
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - event_handler
- Nagios configuration file parameter.
- event_handler_enabled
- Nagios configuration file parameter.
- failure_prediction_enabled
- Nagios configuration file parameter.
- first_notification_delay
- Nagios configuration file parameter.
- flap_detection_enabled
- Nagios configuration file parameter.
- flap_detection_options
- Nagios configuration file parameter.
- freshness_threshold
- Nagios configuration file parameter.
- high_flap_threshold
- Nagios configuration file parameter.
- host_name
- Nagios configuration file parameter.
- hostgroup_name
- Nagios configuration file parameter.
- icon_image
- Nagios configuration file parameter.
- icon_image_alt
- Nagios configuration file parameter.
- initial_state
- Nagios configuration file parameter.
- is_volatile
- Nagios configuration file parameter.
- low_flap_threshold
- Nagios configuration file parameter.
- max_check_attempts
- Nagios configuration file parameter.
- normal_check_interval
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- notification_interval
- Nagios configuration file parameter.
- notification_options
- Nagios configuration file parameter.
- notification_period
- Nagios configuration file parameter.
- notifications_enabled
- Nagios configuration file parameter.
- obsess_over_service
- Nagios configuration file parameter.
- parallelize_check
- Nagios configuration file parameter.
- passive_checks_enabled
- Nagios configuration file parameter.
- poller_tag
- Nagios configuration file parameter.
- process_perf_data
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_service
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- retain_nonstatus_information
- Nagios configuration file parameter.
- retain_status_information
- Nagios configuration file parameter.
- retry_check_interval
- Nagios configuration file parameter.
- retry_interval
- Nagios configuration file parameter.
- service_description
- Nagios configuration file parameter.
- servicegroups
- Nagios configuration file parameter.
- stalking_options
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_servicedependency
The Nagios type servicedependency. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_servicedependency.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_servicedependency resource.
- dependency_period
- Nagios configuration file parameter.
- dependent_host_name
- Nagios configuration file parameter.
- dependent_hostgroup_name
- Nagios configuration file parameter.
- dependent_service_description
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - execution_failure_criteria
- Nagios configuration file parameter.
- host_name
- Nagios configuration file parameter.
- hostgroup_name
- Nagios configuration file parameter.
- inherits_parent
- Nagios configuration file parameter.
- notification_failure_criteria
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_servicedependency
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- service_description
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_serviceescalation
The Nagios type serviceescalation. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_serviceescalation.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_serviceescalation resource.
- contact_groups
- Nagios configuration file parameter.
- contacts
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - escalation_options
- Nagios configuration file parameter.
- escalation_period
- Nagios configuration file parameter.
- first_notification
- Nagios configuration file parameter.
- host_name
- Nagios configuration file parameter.
- hostgroup_name
- Nagios configuration file parameter.
- last_notification
- Nagios configuration file parameter.
- notification_interval
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_serviceescalation
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- service_description
- Nagios configuration file parameter.
- servicegroup_name
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_serviceextinfo
The Nagios type serviceextinfo. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_serviceextinfo.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- _naginator_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_serviceextinfo resource.
- action_url
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - host_name
- Nagios configuration file parameter.
- icon_image
- Nagios configuration file parameter.
- icon_image_alt
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_serviceextinfo
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- service_description
- Nagios configuration file parameter.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_servicegroup
The Nagios type servicegroup. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_servicegroup.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- action_url
- Nagios configuration file parameter.
- alias
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - members
- Nagios configuration file parameter.
- notes
- Nagios configuration file parameter.
- notes_url
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_servicegroup
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- servicegroup_members
- Nagios configuration file parameter.
- servicegroup_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_servicegroup resource.
- target
- The target.
- use
- Nagios configuration file parameter.
nagios_timeperiod
The Nagios type timeperiod. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.
This type generates Nagios configuration statements in Nagios-parseable configuration
files. By default, the statements will be added to /etc/nagios/nagios_timeperiod.cfg
, but
you can send them to a different file by setting their target
attribute.
You can purge Nagios resources using the resources
type, but only
in the default file locations. This is an architectural limitation.
Parameters
- alias
- Nagios configuration file parameter.
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - exclude
- Nagios configuration file parameter.
- friday
- Nagios configuration file parameter.
- monday
- Nagios configuration file parameter.
- provider
- The specific backend to use for this
nagios_timeperiod
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:naginator :
- register
- Nagios configuration file parameter.
- saturday
- Nagios configuration file parameter.
- sunday
- Nagios configuration file parameter.
- target
- The target.
- thursday
- Nagios configuration file parameter.
- timeperiod_name
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
The name of this nagios_timeperiod resource.
- tuesday
- Nagios configuration file parameter.
- use
- Nagios configuration file parameter.
- wednesday
- Nagios configuration file parameter.
notify
Sends an arbitrary message to the agent run-time log.
Parameters
- message
- The message to be sent to the log.
- name
- An arbitrary tag for your own reference; the name of the message.
- withpath
- Whether to show the full object path. Defaults to false. Valid values are
true
,false
.
package
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.
Puppet will automatically guess the packaging format that you are
using based on the platform you are on, but you can override it
using the provider
parameter; each provider defines what it
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.
Features
- holdable: The provider is capable of placing packages on hold such that they are not automatically upgraded as a result of other package dependencies unless explicit action is taken by a user or another package. Held is considered a superset of installed.
- install_options: The provider accepts options to be passed to the installer command.
- installable: The provider can install packages.
- purgeable: The provider can purge packages. This generally means that all traces of the package are removed, including existing configuration files. This feature is thus destructive and should be used with the utmost care.
- uninstall_options: The provider accepts options to be passed to the uninstaller command.
- uninstallable: The provider can uninstall packages.
- upgradeable: The provider can upgrade to the latest version of a package. This feature is used by specifying
latest
as the desired value for the package. - versionable: The provider is capable of interrogating the package database for installed version(s), and can select which out of a set of available versions of a package to install if asked.
| Provider | holdable | install options | installable | purgeable | uninstall options | uninstallable | upgradeable | versionable |
|---|---|---|---|---|---|---|---|---|
| aix | X | X | X | X | ||||
| appdmg | X | |||||||
| apple | X | |||||||
| apt | X | X | X | X | X | X | ||
| aptitude | X | X | X | X | X | X | ||
| aptrpm | X | X | X | X | X | |||
| blastwave | X | X | X | |||||
| dpkg | X | X | X | X | X | |||
| fink | X | X | X | X | X | X | ||
| freebsd | X | X | ||||||
| gem | X | X | X | X | ||||
| hpux | X | X | ||||||
| macports | X | X | X | X | ||||
| msi | X | X | X | X | ||||
| nim | X | X | X | X | ||||
| openbsd | X | X | X | |||||
| opkg | X | X | X | |||||
| pacman | X | X | X | |||||
| pip | X | X | X | X | ||||
| pkg | X | X | X | X | X | |||
| pkgdmg | X | |||||||
| pkgin | X | X | ||||||
| pkgutil | X | X | X | |||||
| portage | X | X | X | X | ||||
| ports | X | X | X | |||||
| portupgrade | X | X | X | |||||
| rpm | X | X | X | X | ||||
| rug | X | X | X | X | ||||
| sun | X | X | X | X | ||||
| sunfreeware | X | X | X | |||||
| up2date | X | X | X | |||||
| urpmi | X | X | X | X | ||||
| windows | X | X | X | X | ||||
| yum | X | X | X | X | X | |||
| zypper | X | X | X | X |
Parameters
- adminfile
- A file containing package defaults for installing packages.
This is currently only used on Solaris. The value will be
validated according to system rules, which in the case of
Solaris means that it should either be a fully qualified path
or it should be in
/var/sadm/install/admin
. - allowcdrom
- Tells apt to allow cdrom sources in the sources.list file.
Normally apt will bail if you try this. Valid values are
true
,false
. - category
- A read-only parameter set by the package.
- configfiles
- Whether configfiles should be kept or replaced. Most packages
types do not support this parameter. Defaults to
keep
. Valid values arekeep
,replace
. - description
- A read-only parameter set by the package.
- ensure
- 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 specifyingpurged
as the ensure value. Valid values arepresent
(also calledinstalled
),absent
,purged
,held
,latest
. Values can match/./
. - flavor
- Newer versions of OpenBSD support ‘flavors’, which are further specifications for which type of package you want.
- install_options
- An array of additional options to pass when installing a package. These
options are package-specific, and should be documented by the software
vendor. One commonly implemented option is
INSTALLDIR
:package { 'mysql': ensure => installed, source => 'N:/packages/mysql-5.5.16-winx64.msi', install_options => [ '/S', { 'INSTALLDIR' => 'C:\mysql-5.5' } ], }
Each option in the array can either be a string or a hash, where each key and value pair are interpreted in a provider specific way. Each option will automatically be quoted when passed to the install command.
On Windows, 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. Requires features install_options.
- instance
- A read-only parameter set by the package.
- name
- The package name. This is the name that the packaging
system uses internally, which is sometimes (especially on Solaris)
a name that is basically useless to humans. If you want to
abstract package installation, then you can use aliases to provide
a common name to packages:
# In the 'openssl' class $ssl = $operatingsystem ? { solaris => SMCossl, default => openssl } # It is not an error to set an alias to the same value as the # object name. package { $ssl: ensure => installed, alias => openssl } . etc. . $ssh = $operatingsystem ? { solaris => SMCossh, default => openssh } # Use the alias to specify a dependency, rather than # having another selector to figure it out again. package { $ssh: ensure => installed, alias => openssh, require => Package[openssl] }
- platform
- A read-only parameter set by the package.
- provider
- The specific backend to use for this
package
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- aix
- Installation from an AIX software directory, using the AIX
installp
command. Thesource
parameter is required for this provider, and should be set to the absolute path (on the puppet agent machine) of a directory containing one or more BFF package files.The
installp
command will generate a table of contents file (named.toc
) in this directory, and thename
parameter (or resource title) that you specify for yourpackage
resource must match a package name that exists in the.toc
file.Note that package downgrades are not supported; if your resource specifies a specific version number and there is already a newer version of the package installed on the machine, the resource will fail with an error message.
Required binaries:
/usr/bin/lslpp
,/usr/sbin/installp
. Default foroperatingsystem
==aix
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - appdmg
- Package management which copies application bundles to a target.
Required binaries:
/usr/bin/ditto
,/usr/bin/hdiutil
,/usr/bin/curl
. Supported features:installable
. - apple
- Package management based on OS X’s builtin packaging system. This is
essentially the simplest and least functional package system in existence –
it only supports installation; no deletion or upgrades. The provider will
automatically add the
.pkg
extension, so leave that off when specifying the package name.Required binaries:
/usr/sbin/installer
. Supported features:installable
. - apt
- Package management via
apt-get
.Required binaries:
/usr/bin/apt-get
,/usr/bin/apt-cache
,/usr/bin/debconf-set-selections
. Default foroperatingsystem
==debian, ubuntu
. Supported features:holdable
,installable
,purgeable
,uninstallable
,upgradeable
,versionable
. - aptitude
- Package management via
aptitude
.Required binaries:
/usr/bin/apt-cache
,/usr/bin/aptitude
. Supported features:holdable
,installable
,purgeable
,uninstallable
,upgradeable
,versionable
. - aptrpm
- Package management via
apt-get
ported torpm
.Required binaries:
apt-get
,rpm
,apt-cache
. Supported features:installable
,purgeable
,uninstallable
,upgradeable
,versionable
. - blastwave
- Package management using Blastwave.org’s
pkg-get
command on Solaris.Required binaries:
pkg-get
. Supported features:installable
,uninstallable
,upgradeable
. - dpkg
- Package management via
dpkg
. Because this only usesdpkg
and notapt
, you must specify the source of any packages you want to manage.Required binaries:
/usr/bin/dpkg-deb
,/usr/bin/dpkg
,/usr/bin/dpkg-query
. Supported features:holdable
,installable
,purgeable
,uninstallable
,upgradeable
. - fink
- Package management via
fink
.Required binaries:
/sw/bin/dpkg-query
,/sw/bin/apt-get
,/sw/bin/apt-cache
,/sw/bin/fink
. Supported features:holdable
,installable
,purgeable
,uninstallable
,upgradeable
,versionable
. - freebsd
- The specific form of package management on FreeBSD. This is an
extremely quirky packaging system, in that it freely mixes between
ports and packages. Apparently all of the tools are written in Ruby,
so there are plans to rewrite this support to directly use those
libraries.
Required binaries:
/usr/sbin/pkg_delete
,/usr/sbin/pkg_info
,/usr/sbin/pkg_add
. Supported features:installable
,uninstallable
. - gem
- Ruby Gem support. If a URL is passed via
source
, then that URL is used as the remote gem repository; if a source is present but is not a valid URL, it will be interpreted as the path to a local gem file. If source is not present at all, the gem will be installed from the default gem repositories.Required binaries:
gem
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - hpux
- HP-UX’s packaging system.
Required binaries:
/usr/sbin/swinstall
,/usr/sbin/swlist
,/usr/sbin/swremove
. Default foroperatingsystem
==hp-ux
. Supported features:installable
,uninstallable
. - macports
- Package management using MacPorts on OS X.
Supports MacPorts versions and revisions, but not variants. Variant preferences may be specified using the MacPorts variants.conf file.
When specifying a version in the Puppet DSL, only specify the version, not the revision. Revisions are only used internally for ensuring the latest version/revision of a port.
Required binaries:
/opt/local/bin/port
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - msi
- Windows package management by installing and removing MSIs.
The
msi
provider is deprecated. Use thewindows
provider instead.Supported features:
install_options
,installable
,uninstall_options
,uninstallable
. - nim
- Installation from an AIX NIM LPP source. The
source
parameter is required for this provider, and should specify the name of a NIMlpp_source
resource that is visible to the puppet agent machine. This provider supports the management of both BFF/installp and RPM packages.Note that package downgrades are not supported; if your resource specifies a specific version number and there is already a newer version of the package installed on the machine, the resource will fail with an error message.
Required binaries:
/usr/bin/lslpp
,rpm
,/usr/sbin/nimclient
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - openbsd
- OpenBSD’s form of
pkg_add
support.Required binaries:
pkg_delete
,pkg_info
,pkg_add
. Default foroperatingsystem
==openbsd
. Supported features:installable
,uninstallable
,versionable
. - opkg
- Opkg packaging support. Common on OpenWrt and OpenEmbedded platforms
Required binaries:
opkg
. Default foroperatingsystem
==openwrt
. Supported features:installable
,uninstallable
,upgradeable
. - pacman
- Support for the Package Manager Utility (pacman) used in Archlinux.
Required binaries:
/usr/bin/pacman
. Default foroperatingsystem
==archlinux
. Supported features:installable
,uninstallable
,upgradeable
. - pip
- Python packages via
pip
.Supported features:
installable
,uninstallable
,upgradeable
,versionable
. - pkg
- OpenSolaris image packaging system. See pkg(5) for more information
Required binaries:
/usr/bin/pkg
. Default forkernelrelease
==5.11
andosfamily
==solaris
. Supported features:holdable
,installable
,uninstallable
,upgradeable
,versionable
. - pkgdmg
- Package management based on Apple’s Installer.app and
DiskUtility.app. This package works by checking the contents of a
DMG image for Apple pkg or mpkg files. Any number of pkg or mpkg
files may exist in the root directory of the DMG file system.
Subdirectories are not checked for packages. See
the wiki docs on this provider
for more detail.
Required binaries:
/usr/bin/hdiutil
,/usr/bin/curl
,/usr/sbin/installer
. Default foroperatingsystem
==darwin
. Supported features:installable
. - pkgin
- Package management using pkgin, a binary package manager for pkgsrc.
Required binaries:
pkgin
. Default foroperatingsystem
==dragonfly
. Supported features:installable
,uninstallable
. - pkgutil
- Package management using Peter Bonivart’s
pkgutil
command on Solaris.Required binaries:
pkgutil
. Supported features:installable
,uninstallable
,upgradeable
. - portage
- Provides packaging support for Gentoo’s portage system.
Required binaries:
/usr/bin/emerge
,/usr/bin/eix
,/usr/bin/eix-update
. Default foroperatingsystem
==gentoo
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - ports
- Support for FreeBSD’s ports. Note that this, too, mixes packages and ports.
Required binaries:
/usr/local/sbin/portupgrade
,/usr/local/sbin/portversion
,/usr/local/sbin/pkg_deinstall
,/usr/sbin/pkg_info
. Default foroperatingsystem
==freebsd
. Supported features:installable
,uninstallable
,upgradeable
. - portupgrade
- Support for FreeBSD’s ports using the portupgrade ports management software.
Use the port’s full origin as the resource name. eg (ports-mgmt/portupgrade)
for the portupgrade port.
Required binaries:
/usr/local/sbin/portupgrade
,/usr/local/sbin/portversion
,/usr/local/sbin/portinstall
,/usr/local/sbin/pkg_deinstall
,/usr/sbin/pkg_info
. Supported features:installable
,uninstallable
,upgradeable
. - rpm
- RPM packaging support; should work anywhere with a working
rpm
binary.Required binaries:
rpm
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - rug
- Support for suse
rug
package manager.Required binaries:
rpm
,/usr/bin/rug
. Default foroperatingsystem
==suse, sles
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - sun
- Sun’s packaging system. Requires that you specify the source for
the packages you’re managing.
Required binaries:
/usr/bin/pkginfo
,/usr/sbin/pkgadd
,/usr/sbin/pkgrm
. Default forosfamily
==solaris
. Supported features:install_options
,installable
,uninstallable
,upgradeable
. - sunfreeware
- Package management using sunfreeware.com’s
pkg-get
command on Solaris. At this point, support is exactly the same asblastwave
support and has not actually been tested.Required binaries:
pkg-get
. Supported features:installable
,uninstallable
,upgradeable
. - up2date
- Support for Red Hat’s proprietary
up2date
package update mechanism.Required binaries:
/usr/sbin/up2date-nox
. Default forlsbdistrelease
==2.1, 3, 4
andosfamily
==redhat
. Supported features:installable
,uninstallable
,upgradeable
. - urpmi
- Support via
urpmi
.Required binaries:
urpmq
,rpm
,urpmi
. Default foroperatingsystem
==mandriva, mandrake
. Supported features:installable
,uninstallable
,upgradeable
,versionable
. - windows
- Windows package management.
This provider supports either MSI or self-extracting executable installers.
This provider requires a
source
attribute when installing the package. It accepts paths paths to local files, mapped drives, or UNC paths.If the executable requires special arguments to perform a silent install or uninstall, then the appropriate arguments should be specified using the
install_options
oruninstall_options
attributes, respectively. Puppet will automatically quote any option that contains spaces.Default for
operatingsystem
==windows
. Supported features:install_options
,installable
,uninstall_options
,uninstallable
. - yum
- Support via
yum
.Using this provider’s
uninstallable
feature will not remove dependent packages. To remove dependent packages with this provider use thepurgeable
feature, but note this feature is destructive and should be used with the utmost care.Required binaries:
yum
,rpm
,python
. Default foroperatingsystem
==fedora, centos, redhat
. Supported features:installable
,purgeable
,uninstallable
,upgradeable
,versionable
. - zypper
- Support for SuSE
zypper
package manager. Found in SLES10sp2+ and SLES11Required binaries:
/usr/bin/zypper
. Supported features:installable
,uninstallable
,upgradeable
,versionable
.
- responsefile
- A file containing any necessary answers to questions asked by the package. This is currently used on Solaris and Debian. The value will be validated according to system rules, but it should generally be a fully qualified path.
- root
- A read-only parameter set by the package.
- source
- 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,
although you can manage packages as
file
resources. - status
- A read-only parameter set by the package.
- uninstall_options
- An array of additional options to pass when uninstalling a package. These
options are package-specific, and should be documented by the software
vendor. For example:
package { 'VMware Tools': ensure => absent, uninstall_options => [ { 'REMOVE' => 'Sync,VSS' } ], }
Each option in the array can either be a string or a hash, where each key and value pair are interpreted in a provider specific way. Each option will automatically be quoted when passed to the uninstall command.
On Windows, 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. Requires features uninstall_options.
- vendor
- A read-only parameter set by the package.
resources
This is a metatype that can manage other resource types. Any
metaparams specified here will be passed on to any generated resources,
so you can purge umanaged resources but set noop
to true so the
purging is only logged and does not actually happen.
Parameters
- name
- The name of the type to be managed.
- purge
- Purge unmanaged resources. This will delete any resource
that is not specified in your configuration
and is not required by any specified resources. Valid values are
true
,false
. - unless_system_user
- This keeps system users from being purged. By default, it
does not purge users whose UIDs are less than or equal to 500, but you can specify
a different UID as the inclusive limit. Valid values are
true
,false
. Values can match/^\d+$/
.
router
Manages connected router.
Parameters
- url
- (Namevar: If omitted, this parameter’s value defaults to the resource’s title.)
An SSH or telnet URL at which to access the router, in the form
ssh://user:pass:enable@host/
ortelnet://user:pass:enable@host/
.
schedule
Define schedules for Puppet. Resources can be limited to a schedule by using the
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 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",
period => daily,
repeat => 1,
}
With this schedule, the first time that Puppet runs between 2 and 4 AM, all resources with this schedule will get applied, but they won’t get applied again between 2 and 4 because they will have already 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 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':
period => hourly,
repeat => 2,
}
This will cause resources to be applied every 30 minutes by default.
Parameters
- name
- The name of the schedule. This name is used to retrieve the
schedule when assigning it to an object:
schedule { 'daily': period => daily, range => "2 - 4", } exec { "/usr/bin/apt-get update": schedule => 'daily', }
- period
- 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.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': period => hourly, repeat => 6, }
This can cause Puppet to apply that resource up to every 10 minutes.
At the moment, Puppet cannot guarantee that level of repetition; that is, it can run up to every 10 minutes, but internal factors might prevent it from actually running that 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. Valid values arehourly
,daily
,weekly
,monthly
,never
. - periodmatch
- Whether periods should be matched by number (e.g., the two times
are in the same hour) or by distance (e.g., the two times are
60 minutes apart). Valid values are
number
,distance
. - range
- 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. Multiple ranges can be applied in array context. As a convenience when specifying ranges, you may cross midnight (e.g.: range => “22:00 - 04:00”).
- repeat
- How often a given resource may be applied in this schedule’s
period
. Defaults to 1; must be an integer. - weekday
- The days of the week in which the schedule should be valid.
You may specify the full day name (Tuesday), the three character
abbreviation (Tue), or a number corresponding to the day of the
week where 0 is Sunday, 1 is Monday, etc. You may pass an array
to specify multiple days. If not specified, the day of the week
will not be considered in the schedule.
If you are also using a range match that spans across midnight then this parameter will match the day that it was at the start of the range, not necessarily the day that it is when it matches. For example, consider this schedule:
schedule { ‘maintenance_window’: range => ‘22:00 - 04:00’, weekday => ‘Saturday’, }
This will match at 11 PM on Saturday and 2 AM on Sunday, but not at 2 AM on Saturday.
scheduled_task
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.
Parameters
- arguments
- Any arguments or flags that should be passed to the command. Multiple arguments should be specified as a space-separated string.
- command
- The full path to the application to run, without any arguments.
- enabled
- Whether the triggers for this task should be enabled. This attribute
affects every trigger for the task; triggers cannot be enabled or
disabled individually. Valid values are
true
,false
. - ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - name
- The name assigned to the scheduled task. This will uniquely identify the task on the system.
- password
- 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 to determine if a scheduled task is in sync or not.
- provider
- The specific backend to use for this
scheduled_task
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- win32_taskscheduler
- 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.
Default for
operatingsystem
==windows
.
- trigger
- 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 aredaily
,weekly
,monthly
, oronce
.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 ofmon
,tues
,wed
,thurs
,fri
,sat
,sun
, orall
.
- 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 valuelast,
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 ofmon
,tues
,wed
,thurs
,fri
,sat
,sun
, orall
.which_occurrence
(Required) — The occurrence of the chosen weekday when the task should run. Must be one offirst
,second
,third
,fourth
,fifth
, orlast
.
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 }
- For all triggers:
- user
- 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’.
Please also note that Puppet must be running as a privileged user in order to manage
scheduled_task
resources. Running as an unprivileged user will result in ‘access denied’ errors. - working_dir
- The full path of the directory in which to start the command.
selboolean
Manages SELinux booleans on systems with SELinux support. The supported booleans
are any of the ones found in /selinux/booleans/
.
Parameters
- name
- The name of the SELinux boolean to be managed.
- persistent
- If set true, SELinux booleans will be written to disk and persist accross reboots.
The default is
false
. Valid values aretrue
,false
. - provider
- The specific backend to use for this
selboolean
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- getsetsebool
- Manage SELinux booleans using the getsebool and setsebool binaries.
Required binaries:
/usr/sbin/getsebool
,/usr/sbin/setsebool
.
- value
- Whether the the SELinux boolean should be enabled or disabled. Valid values are
on
,off
.
selmodule
Manages loading and unloading of SELinux policy modules on the system. Requires SELinux support. See man semodule(8) for more information on SELinux policy modules.
Autorequires: If Puppet is managing the file containing this SELinux
policy module (which is either explicitly specified in the selmodulepath
attribute or will be found at {selmoduledir
}/{name
}.pp), the selmodule
resource will autorequire that file.
Parameters
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - name
- The name of the SELinux policy to be managed. You should not include the customary trailing .pp extension.
- provider
- The specific backend to use for this
selmodule
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- semodule
- Manage SELinux policy modules using the semodule binary.
Required binaries:
/usr/sbin/semodule
.
- selmoduledir
- The directory to look for the compiled pp module file in.
Currently defaults to
/usr/share/selinux/targeted
. If theselmodulepath
attribute is not specified, Puppet will expect to find the module in<selmoduledir>/<name>.pp
, wherename
is the value of thename
parameter. - selmodulepath
- The full path to the compiled .pp policy module. You only need to use
this if the module file is not in the
selmoduledir
directory. - syncversion
- If set to
true
, the policy will be reloaded if the version found in the on-disk file differs from the loaded version. If set tofalse
(the default) the the only check that will be made is if the policy is loaded at all or not. Valid values aretrue
,false
.
service
Manage running services. Service support unfortunately varies widely by platform — some platforms have very little if any concept of a running service, and some have a very codified and powerful concept. Puppet’s service support is usually capable of doing the right thing, but the more information you can provide, the better behaviour you will get.
Puppet 2.7 and newer expect init scripts to have a working status command.
If this isn’t the case for any of your services’ init scripts, you will
need to set hasstatus
to false and possibly specify a custom status
command in the status
attribute.
Note that if a service
receives an event from another resource,
the service will get restarted. The actual command to restart the
service depends on the platform. You can provide an explicit command for
restarting with the restart
attribute, or you can set hasrestart
to
true to use the init script’s restart command; if you do neither, the
service’s stop and start commands will be used.
Features
- controllable: The provider uses a control variable.
- enableable: The provider can enable and disable the service
- refreshable: The provider can restart the service.
| Provider | controllable | enableable | refreshable |
|---|---|---|---|
| base | X | ||
| bsd | X | X | |
| daemontools | X | X | |
| debian | X | X | |
| freebsd | X | X | |
| gentoo | X | X | |
| init | X | ||
| launchd | X | X | |
| openrc | X | X | |
| openwrt | X | X | |
| redhat | X | X | |
| runit | X | X | |
| service | X | ||
| smf | X | X | |
| src | X | X | |
| systemd | X | X | |
| upstart | X | X | |
| windows | X | X |
Parameters
- binary
- The path to the daemon. This is only used for
systems that do not support init scripts. This binary will be
used to start the service if no
start
parameter is provided. - control
- The control variable used to manage services (originally for HP-UX).
Defaults to the upcased service name plus
START
replacing dots with underscores, for those providers that support thecontrollable
feature. - enable
- Whether a service should be enabled to start at boot.
This property behaves quite differently depending on the platform;
wherever possible, it relies on local tools to enable or disable
a given service. Valid values are
true
,false
,manual
. Requires features enableable. - ensure
- Whether a service should be running. Valid values are
stopped
(also calledfalse
),running
(also calledtrue
). - hasrestart
- Specify that an init script has a
restart
command. If this is false and you do not specify a command in therestart
attribute, the init script’sstop
andstart
commands will be used.Defaults to false. Valid values are
true
,false
. - hasstatus
- Declare whether the service’s init script has a functional status
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 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 thestatus
attribute or expect that Puppet will look for the service name in the process table. Be aware that ‘virtual’ init scripts (like ‘network’ under Red Hat systems) will respond poorly to refresh events from other resources if you override the default behavior without providing a status command. Valid values aretrue
,false
. - manifest
- Specify a command to config a service, or a path to a manifest to do so.
- name
- 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.”)
- path
- The search path for finding init scripts. Multiple values should be separated by colons or provided as an array.
- pattern
- The pattern to search for in the process table.
This is used for stopping services on platforms that do not
support init scripts, and is also used for determining service
status on those service whose init scripts do not include a status
command.
Defaults to the name of the service. The pattern can be a simple string or any legal Ruby pattern.
- provider
- The specific backend to use for this
service
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:- base
- The simplest form of Unix service support.
You have to specify enough about your service for this to work; the minimum you can specify is a binary for starting the process, and this same binary will be searched for in the process table to stop the service. As with
init
-style services, it is preferable to specify start, stop, and status commands.Required binaries:
kill
. Supported features:refreshable
. - bsd
- FreeBSD’s (and probably NetBSD’s?) form of
init
-style service management.Uses
rc.conf.d
for service enabling and disabling.Supported features:
enableable
,refreshable
. - daemontools
- Daemontools service management.
This provider manages daemons supervised by D.J. Bernstein daemontools. When detecting the service directory it will check, in order of preference:
/service
/etc/service
/var/lib/svscan
The daemon directory should be in one of the following locations:
/var/lib/service
/etc
…or this can be overriden in the resource’s attributes:
service { "myservice": provider => "daemontools", path => "/path/to/daemons", }
This provider supports out of the box:
- start/stop (mapped to enable/disable)
- enable/disable
- restart
- status
If a service has
ensure => "running"
, it will link /path/to/daemon to /path/to/service, which will automatically enable the service.If a service has
ensure => "stopped"
, it will only shut down the service, not remove the/path/to/service
link.Required binaries:
/usr/bin/svstat
,/usr/bin/svc
. Supported features:enableable
,refreshable
. - debian
- Debian’s form of
init
-style management.The only differences from
init
are support for enabling and disabling services viaupdate-rc.d
and the ability to determine enabled status viainvoke-rc.d
.Required binaries:
/usr/sbin/update-rc.d
,/usr/sbin/invoke-rc.d
. Default foroperatingsystem
==debian, ubuntu
. Supported features:enableable
,refreshable
. - freebsd
- Provider for FreeBSD and DragonFly BSD. Uses the
rcvar
argument of init scripts and parses/edits rc files.Default for
operatingsystem
==freebsd, dragonfly
. Supported features:enableable
,refreshable
. - gentoo
- Gentoo’s form of
init
-style service management.Uses
rc-update
for service enabling and disabling.Required binaries:
/sbin/rc-update
. Supported features:enableable
,refreshable
. - init
- Standard
init
-style service management.Supported features:
refreshable
. - launchd
- This provider manages jobs with
launchd
, which is the default service framework for Mac OS X (and may be available for use on other platforms).For
launchd
documentation, see:This provider reads plists out of the following directories:
/System/Library/LaunchDaemons
/System/Library/LaunchAgents
/Library/LaunchDaemons
/Library/LaunchAgents
…and builds up a list of services based upon each plist’s “Label” entry.
This provider supports:
- ensure => running/stopped,
- enable => true/false
- status
- restart
Here is how the Puppet states correspond to
launchd
states:- stopped — job unloaded
- started — job loaded
- enabled — ‘Disable’ removed from job plist file
- disabled — ‘Disable’ added to job plist file
Note that this allows you to do something
launchctl
can’t do, which is to be in a state of “stopped/enabled” or “running/disabled”.Note that this provider does not support overriding ‘restart’ or ‘status’.
Required binaries:
/bin/launchctl
,/usr/bin/sw_vers
,/usr/bin/plutil
. Default foroperatingsystem
==darwin
. Supported features:enableable
,refreshable
. - openrc
- Support for Gentoo’s OpenRC initskripts
Uses rc-update, rc-status and rc-service to manage services.
Required binaries:
/sbin/rc-service
,/bin/rc-status
,/sbin/rc-update
. Default foroperatingsystem
==funtoo
. Supported features:enableable
,refreshable
. - openwrt
- Support for OpenWrt flavored init scripts.
Uses /etc/init.d/service_name enable, disable, and enabled.
Default for
operatingsystem
==openwrt
. Supported features:enableable
,refreshable
. - redhat
- Red Hat’s (and probably many others’) form of
init
-style service management. Useschkconfig
for service enabling and disabling.Required binaries:
/sbin/chkconfig
,/sbin/service
. Default forosfamily
==redhat, suse
. Supported features:enableable
,refreshable
. - runit
- Runit service management.
This provider manages daemons running supervised by Runit. When detecting the service directory it will check, in order of preference:
/service
/var/service
/etc/service
The daemon directory should be in one of the following locations:
/etc/sv
or this can be overriden in the service resource parameters::
service { "myservice": provider => "runit", path => "/path/to/daemons", }
This provider supports out of the box:
- start/stop
- enable/disable
- restart
- status
Required binaries:
/usr/bin/sv
. Supported features:enableable
,refreshable
. - service
- The simplest form of service support.
Supported features:
refreshable
. - smf
- Support for Sun’s new Service Management Framework.
Starting a service is effectively equivalent to enabling it, so there is only support for starting and stopping services, which also enables and disables them, respectively.
By specifying
manifest => "/path/to/service.xml"
, the SMF manifest will be imported if it does not exist.Required binaries:
/usr/sbin/svcadm
,/usr/bin/svcs
,/usr/sbin/svccfg
. Default forosfamily
==solaris
. Supported features:enableable
,refreshable
. - src
- Support for AIX’s System Resource controller.
Services are started/stopped based on the
stopsrc
andstartsrc
commands, and some services can be refreshed withrefresh
command.Enabling and disabling services is not supported, as it requires modifications to
/etc/inittab
. Starting and stopping groups of subsystems is not yet supported.Required binaries:
/usr/sbin/lsitab
,/usr/bin/refresh
,/usr/sbin/mkitab
,/usr/sbin/rmitab
,/usr/bin/stopsrc
,/usr/sbin/chitab
,/usr/bin/startsrc
,/usr/bin/lssrc
. Default foroperatingsystem
==aix
. Supported features:enableable
,refreshable
. - systemd
- Manages
systemd
services usingsystemctl
.Required binaries:
systemctl
. Default forosfamily
==archlinux
. Supported features:enableable
,refreshable
. - upstart
- Ubuntu service management with
upstart
.This provider manages
upstart
jobs, which have replacedinitd
services on Ubuntu. Forupstart
documentation, see http://upstart.ubuntu.com/.Required binaries:
/sbin/status
,/sbin/initctl
,/sbin/start
,/sbin/stop
,/sbin/restart
. Default foroperatingsystem
==ubuntu
. Supported features:enableable
,refreshable
. - windows
- 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.
Control of service groups (dependencies) is not yet supported, nor is running services as a specific user.
Required binaries:
net.exe
. Default foroperatingsystem
==windows
. Supported features:enableable
,refreshable
.
- restart
- Specify a restart command manually. If left unspecified, the service will be stopped and then started.
- start
- Specify a start command manually. Most service subsystems
support a
start
command, so this will not need to be specified. - status
- Specify a status command manually. This 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 for init script status actions, but
Puppet only considers the difference between 0 and nonzero to be
relevant.
If left unspecified, the status of the service will be determined automatically, usually by looking for the service in the process table.
- stop
- Specify a stop command manually.
ssh_authorized_key
Manages SSH authorized keys. Currently only type 2 keys are supported.
Autorequires: If Puppet is managing the user account in which this
SSH key should be installed, the ssh_authorized_key
resource will autorequire
that user.
Parameters
- ensure
- The basic property that the resource should be in. Valid values are
present
,absent
. - key
- The public key itself; generally a long string of hex characters. The key attribute may not contain whitespace: Omit key headers (e.g. ‘ssh-rsa’) and key identifiers (e.g<EMAIL_ADDRESS>found in the public key file.
- name
- The SSH key comment. This attribute is currently used as a system-wide primary key and therefore has to be unique.
- options
- Key options, see sshd(8) for possible values. Multiple values should be specified as an array.
- provider
- The specific backend to use for this
ssh_authorized_key