Docs: Type Reference


Type Reference

Type Reference

This page is autogenerated; any changes will get overwritten (last generated on Mon Oct 22 17:13:29 -0700 2012)

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 because path is the namevar for file, that string is assigned to the path 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 on file 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 loction PATH
setm <PATH> <SUB> <VALUE>
Sets multiple nodes (matching SUB relative to PATH) to VALUE
rm <PATH>
Removes the node at location PATH
remove <PATH>
Synonym for rm
clear <PATH>
Sets the node at PATH to NULL, creating it if needed
ins <LABEL> (before|after) <PATH>
Inserts an empty node LABEL either before or after PATH.
insert <LABEL> <WHERE> <PATH>
Synonym for ins
mv <PATH> <OTHER PATH>
Moves a node at PATH to the new location OTHER PATH
move <PATH> <OTHER PATH>
Synonym for mv
defvar <NAME> <PATH>
Sets Augeas variable $NAME to PATH
defnode <NAME> <PATH> <VALUE>
Sets Augeas variable $NAME to PATH, creating it with VALUE if needed

If the context parameter is set, that value is prepended to any relative PATHs.

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 the lens 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 the incl 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 context
  • MATCH_PATH is a valid match synatx scoped by the context
  • COMPARATOR is one of >, >=, !=, ==, <=, or <
  • STRING is a string
  • INT is a number
  • AN_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 to absent to delete any computer records with this name Valid values are present, 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 job that matches an existing job in every way except name, then the jobs will be considered equivalent and the new name will be permanently associated with that job. Once this association is made and synced to disk, you can then manage the job normally (e.g., change the schedule of the job).

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'
}

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 the err 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 inside important.tar. If it is ever deleted, the exec will bring it back by re-extracting the tarball. If important.tar does not actually contain myfile, 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 output. Defaults to on_failure, which only logs the output when the command has a non-zero exit code. In addition to the values below, you may set this attribute to any legal log level. Valid values are true, 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 the posix 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 the shell provider on Windows — a command must explicitly invoke the shell: 
exec {'echo foo':
  command => 'cmd.exe /c echo "foo"',
}

If no extension is specified for a command, Windows will use the PATHEXT environment variable to locate the executable.

Note on PowerShell scripts: PowerShell’s default restricted execution policy doesn’t allow it to run saved scripts. To run PowerShell scripts, specify the remotesigned execution policy as part of the command:

exec { 'test':
  path    => 'C:/Windows/System32/WindowsPowerShell/v1.0',
  command => 'powershell -executionpolicy remotesigned -file C:/test.ps1',
}

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 and notify can trigger actions, not require, so it only makes sense to use refreshonly with subscribe or notify. Valid values are true, 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) unless grep 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.

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 files should be backed up before being replaced. The preferred method of backing files up is via a filebucket, which stores files by their MD5 sums and allows easy retrieval without littering directories with backups. You can specify a local filebucket or a network-accessible server-based filebucket by setting backup => bucket-name. Alternatively, if you specify any value that begins with a . (e.g., .puppet-bak), then Puppet will use copy the file in the same directory with that value as the extension of the backup. Setting backup => false disables all backups of the file in question.

Puppet automatically creates a local filebucket named puppet and defaults to backing up there. To use a server-based filebucket, you must specify one in your configuration.

  filebucket { main:
    server => puppet,
    path   => false,
    # The path => false line works around a known issue with the filebucket type.
  }

The puppet master daemon creates a filebucket by default, so you can usually back up to your main server with this configuration. Once you’ve described the bucket in your configuration, you can use it in any file’s backup attribute:

  file { "/my/file":
    source => "/path/in/nfs/or/something",
    backup => main
  }

This will back the file up to the central server.

At this point, the benefits of using a central filebucket are that you do not have backup files lying around on each of your machines, a given version of a file is only backed up once, you can restore any given file manually (no matter how old), and you can use Puppet Dashboard to view file contents. Eventually, transactional support will be able to automatically restore filebucketed files.

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 and target.

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, and directory. Specifying present will match any form of file existence, and if the file is missing will create an empty file. Specifying absent will delete the file (or directory, if recurse => true).

Anything other than the above values will create a symlink; note that symlinks cannot be managed on Windows. In the interest of readability and clarity, symlinks should be created by setting ensure => link and explicitly specifying a target; however, if a target attribute isn’t provided, the value of the ensure attribute will be used as the symlink target. The following two declarations are equivalent:

# (Useful on Solaris)

# Less maintainable:
file { "/etc/inetd.conf":
  ensure => "/etc/inet/inetd.conf",
}

# More maintainable:
file { "/etc/inetd.conf":
  ensure => link,
  target => "/etc/inet/inetd.conf",
}   Valid values are `absent` (also called `false`), `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 are true, 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, and ignore will just pass it by. When not copying, manage and ignore behave equivalently (because you cannot really ignore links entirely during local recursion), and follow will manage the file to which the link points. Valid values are follow, 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 either a=r,ug+w or ug=rw,o=r. See the manual page for GNU or BSD chmod for more details on numeric and symbolic modes.

On Windows, permissions are translated as follows:

  • Owner and group names are mapped to Windows SIDs
  • The “other” class of users maps to the “Everyone” SID
  • The read/write/execute permissions map to the FILE_GENERIC_READ, FILE_GENERIC_WRITE, and FILE_GENERIC_EXECUTE access rights; a file’s owner always has the FULL_CONTROL right
  • “Other” users can’t have any permissions a file’s group lacks, and its group can’t have any permissions its owner lacks; that is, 0644 is an acceptable mode, but 0464 is not.
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.

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 are true, 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 or content attribute specifies. Setting this to false allows file resources to initialize files without overwriting future changes. Note that this only affects content; Puppet will still manage ownership and permissions. Defaults to true. Valid values are true (also called yes), false (also called no).
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 or SystemHigh. 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.
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 and target.

The available URI schemes are puppet and file. Puppet URIs will retrieve files from Puppet’s built-in file server, and are usually formatted as:

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, the source attribute can be used to recursively copy directories if the recurse attribute is set to true or remote. If a source directory contains symlinks, use the links attribute to specify whether to recreate links or follow them.

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 to all.

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 are first, all.
target
The target for creating a link. Currently, symlinks are the only type supported. This attribute is mutually exclusive with source and content.

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, setting ensure to directory, and setting the links attribute to manage. Valid values are notlink. Values can match /./.

type
A read-only state to check the file type.

filebucket

A repository for backing up files. If no filebucket is defined, then files will be backed up in their current directory, but the filebucket can be either a host- or site-global repository for backing up. It stores files and returns the MD5 sum, which can later be used to retrieve the file if restoration becomes necessary. A filebucket does not do any work itself; instead, it can be specified as the value of backup in a file object.

Currently, filebuckets are only useful for manual retrieval of accidentally removed files (e.g., you look in the log for the md5 sum and retrieve the file with that sum from the filebucket), but when transactions are fully supported filebuckets will be used to undo transactions.

You will normally want to define a single filebucket for your whole network and then use that as the default backup location:

# Define the bucket
filebucket { 'main':
  server => puppet,
  path   => false,
  # Due to a known issue, path must be set to false for remote filebuckets.
}

# Specify it as the default target
File { backup => main }

Puppetmaster servers create a filebucket by default, so this will work in a default configuration.

Parameters

name
The name of the filebucket.
path
The path to the local filebucket. If this is unset, then the bucket is remote. The parameter server must can be specified to set the remote server.
port
The port on which the remote server is listening. Defaults to the normal Puppet port, 8140.
server
The server providing the remote filebucket. If this is not specified then path is checked. If it is set, then the bucket is local. Otherwise the puppetmaster server specified in the config or at the commandline is used.

Due to a known issue, you currently must set the path attribute to false if you wish to specify a server attribute.

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

  • 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 manages aix lam manages members system groups
aix X X  
directoryservice   X  
groupadd     X
ldap      
pw   X  
windows_adsi   X  

Parameters

allowdupe
Whether to allow duplicate GIDs. Defaults to false. Valid values are true, 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.
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/bin/chgroup, /usr/sbin/lsgroup, /usr/sbin/rmgroup, /usr/bin/mkgroup. Default for operatingsystem == aix. Supported features: manages_aix_lam, manages_members.

directoryservice
Group management using DirectoryService on OS X.

Required binaries: /usr/bin/dscl. Default for operatingsystem == darwin. Supported features: manages_members.

groupadd
Group management via groupadd and its ilk. The default for most platforms.

Required binaries: groupmod, groupdel, 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, including ldapbase. You will almost definitely need settings for ldapuser and ldappassword 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.

Required binaries: pw. Default for operatingsystem == freebsd. 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 called no_shutdown), absent (also called shutdown).
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 127.0.0.1
  • IPV4/prefixlength like 127.0.1.1/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 to 644.
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 with uid == 0. AuthorizationServices defaults this attribute to false if not specified. Valid values are true, false.
auth_class
Corresponds to class in the authorization store; renamed due to ‘class’ being a reserved word in Puppet. Valid values are user, evaluate-mechanisms, allow, deny, rule.
auth_type
Type — this can be a right or a rule. The comment type has not yet been implemented. Valid values are right, rule.
authenticate_user
Corresponds to authenticate-user in the authorization store. Valid values are true, 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. If k-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/sw_vers, /usr/bin/security. Default for operatingsystem == 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 are true, 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: /var/lib/mailman/mail/mailman, list_lists, rmlist, newlist.
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 when ds_type => computer.) This setting is not required, as it can be automatically discovered when the resource name is parseable. (For example, in /Groups/admin, group will be used as the dstype.)
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 and ds_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 protected])

Required binaries: /usr/bin/dscl. Default for operatingsystem == 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 or 0. or 2 on FreeBSD, Default is 0. Values can match /(0|1)/, /(0|1)/.
ensure
Control what to do with this mount. Set this attribute to umounted to make sure the filesystem is in the filesystem table but not mounted (if the filesystem is currently mounted, it will be unmounted). Set it to absent to unmount (if necessary) and remove the filesystem from the fstab. Set to mounted to add it to the fstab and mount it. Set to present to add to fstab but not change mount/unmount status. Valid values are defined (also called present), 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: umount, mount. 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 are true, 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.
email
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
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 are keep, 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 specifying purged as the ensure value. Valid values are present (also called installed), 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 the AIX software directory.

Required binaries: /usr/bin/lslpp, /usr/sbin/installp. Default for operatingsystem == aix. Supported features: installable, uninstallable, upgradeable, versionable.

appdmg
Package management which copies application bundles to a target.

Required binaries: /usr/bin/hdiutil, /usr/bin/curl, /usr/bin/ditto. 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 for operatingsystem == 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 to rpm.

Required binaries: apt-get, apt-cache, rpm. 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 uses dpkg and not apt, 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/fink, /sw/bin/apt-cache. 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_add, /usr/sbin/pkg_info, /usr/sbin/pkg_delete. 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 for operatingsystem == 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 the windows provider instead.

Supported features: install_options, installable, uninstall_options, uninstallable.

nim
Installation from NIM LPP source.

Required binaries: /usr/sbin/nimclient. Supported features: installable, uninstallable, upgradeable, versionable.

openbsd
OpenBSD’s form of pkg_add support.

Required binaries: pkg_add, pkg_info, pkg_delete. Default for operatingsystem == openbsd. Supported features: installable, uninstallable, versionable.

pacman
Support for the Package Manager Utility (pacman) used in Archlinux.

Required binaries: /usr/bin/pacman. Default for operatingsystem == 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 for osfamily == solaris and kernelrelease == 5.11. 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/sbin/installer, /usr/bin/hdiutil, /usr/bin/curl. Default for operatingsystem == darwin. Supported features: installable.

pkgin
Package management using pkgin, a binary package manager for pkgsrc.

Required binaries: pkgin. 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/eix, /usr/bin/eix-update, /usr/bin/emerge. Default for operatingsystem == 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 for operatingsystem == 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 for operatingsystem == 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/sbin/pkgadd, /usr/sbin/pkgrm, /usr/bin/pkginfo. Default for osfamily == 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 as blastwave 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 for lsbdistrelease == 2.1, 3, 4 and osfamily == redhat. Supported features: installable, uninstallable, upgradeable.

urpmi
Support via urpmi.

Required binaries: rpm, urpmi, urpmq. Default for operatingsystem == 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 or uninstall_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.

Required binaries: yum, python, rpm. Default for operatingsystem == fedora, centos, redhat. Supported features: installable, purgeable, uninstallable, upgradeable, versionable.

zypper
Support for SuSE zypper package manager. Found in SLES10sp2+ and SLES11

Required 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/ or telnet://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 are hourly, 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 are daily, weekly, monthly, or once.
    • start_time (Required) — The time of day when the trigger should first become active. Several time formats will work, but we suggest 24-hour time formatted as HH:MM.
    • start_date — The date when the trigger should first become active. Defaults to “today.” Several date formats will work, including special dates like “today,” but we suggest formatting dates as YYYY-MM-DD.
  • For daily triggers:
    • every — How often the task should run, as a number of days. Defaults to 1. (“2” means every other day, “3” means every three days, etc.)
  • For weekly triggers:
    • every — How often the task should run, as a number of weeks. Defaults to 1. (“2” means every other week, “3” means every three weeks, etc.)
    • day_of_week — Which days of the week the task should run, as an array. Defaults to all days. Each day must be one of mon, tues, wed, thurs, fri, sat, sun, or all.
  • For monthly-by-date triggers:
    • months — Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.
    • on (Required) — Which days of the month the task should run, as an array. Each day must beeither an integer between 1 and 31, or the special value last, which is always the last day of the month.
  • For monthly-by-weekday triggers:
    • months — Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.
    • day_of_week (Required) — Which day of the week the task should run, as an array with only one element. Each day must be one of mon, tues, wed, thurs, fri, sat, sun, or all.
    • which_occurrence (Required) — The occurrence of the chosen weekday when the task should run. Must be one of first, second, third, fourth, fifth, or last.

Examples:

# Run at 8am on the 1st, 15th, and last day of the month in January, March,
# May, July, September, and November, starting after August 31st, 2011.
trigger => {
  schedule   => monthly,
  start_date => '2011-08-31',   # Defaults to 'today'
  start_time => '08:00',        # Must be specified
  months     => [1,3,5,7,9,11], # Defaults to all
  on         => [1, 15, last],  # Must be specified
}

# Run at 8am on the first Monday of the month for January, March, and May,
# starting after August 31st, 2011.
trigger => {
  schedule         => monthly,
  start_date       => '2011-08-31', # Defaults to 'today'
  start_time       => '08:00',      # Must be specified
  months           => [1,3,5],      # Defaults to all
  which_occurrence => first,        # Must be specified
  day_of_week      => [mon],        # Must be specified
}
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’.
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 are true, 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/setsebool, /usr/sbin/getsebool.

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 the selmodulepath attribute is not specified, Puppet will expect to find the module in <selmoduledir>/<name>.pp, where name is the value of the name 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 to false (the default) the the only check that will be made is if the policy is loaded at all or not. Valid values are true, 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
redhat   X X
runit   X X
service     X
smf   X X
src     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 the controllable 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 called false), running (also called true).
hasrestart
Specify that an init script has a restart command. If this is false and you do not specify a command in the restart attribute, the init script’s stop and start commands will be used. Defaults to true; note that this is a change from earlier versions of Puppet. 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 the status 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 are true, 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 via update-rc.d and the ability to determine enabled status via invoke-rc.d.

Required binaries: /usr/sbin/update-rc.d, /usr/sbin/invoke-rc.d. Default for operatingsystem == debian, ubuntu. Supported features: enableable, refreshable.

freebsd
Provider for FreeBSD. Uses the rcvar argument of init scripts and parses/edits rc files.

Default for operatingsystem == freebsd. 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: /usr/bin/sw_vers, /usr/bin/plutil, /bin/launchctl. Default for operatingsystem == 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: /bin/rc-status, /sbin/rc-update, /sbin/rc-service. Default for operatingsystem == funtoo. Supported features: enableable, refreshable.

redhat
Red Hat’s (and probably many others’) form of init-style service management. Uses chkconfig for service enabling and disabling.

Required binaries: /sbin/service, /sbin/chkconfig. Default for osfamily == 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/bin/svcs, /usr/sbin/svccfg, /usr/sbin/svcadm. Default for osfamily == solaris. Supported features: enableable, refreshable.

src
Support for AIX’s System Resource controller.

Services are started/stopped based on the stopsrc and startsrc commands, and some services can be refreshed with refresh 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/bin/stopsrc, /usr/bin/startsrc, /usr/bin/lssrc, /usr/bin/refresh. Default for operatingsystem == aix. Supported features: refreshable.

systemd
Manages systemd services using /bin/systemctl.

Required binaries: /bin/systemctl. Supported features: enableable, refreshable.

upstart
Ubuntu service management with upstart.

This provider manages upstart jobs, which have replaced initd services on Ubuntu. For upstart documentation, see http://upstart.ubuntu.com/.

Required binaries: /sbin/restart, /sbin/start, /sbin/status, /sbin/initctl, /sbin/stop. Default for operatingsystem == 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 for operatingsystem == 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 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 protected]’) 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 resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
parsed
Parse and generate authorized_keys files for SSH.
target
The absolute filename in which to store the SSH key. This property is optional and should only be used in cases where keys are stored in a non-standard location (i.e. not in ~user/.ssh/authorized_keys`).
type
The encryption type used: ssh-dss or ssh-rsa. Valid values are ssh-dss (also called dsa), ssh-rsa (also called rsa), ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521.
user
The user account in which the SSH key should be installed. The resource will automatically depend on this user.

sshkey

Installs and manages ssh host keys. At this point, this type only knows how to install keys into /etc/ssh/ssh_known_hosts. See the ssh_authorized_key type to manage authorized keys.

Parameters

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.
key
The key itself; generally a long string of hex digits.
name
The host name that the key is associated with.
provider
The specific backend to use for this sshkey resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
parsed
Parse and generate host-wide known hosts files for SSH.
target
The file in which to store the ssh key. Only used by the parsed provider.
type
The encryption type used. Probably ssh-dss or ssh-rsa. Valid values are ssh-dss (also called dsa), ssh-rsa (also called rsa), ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521.

stage

A resource type for specifying run stages. The actual stage should be specified on resources:

class { foo: stage => pre }

And you must manually control stage order:

stage { pre: before => Stage[main] }

You automatically get a ‘main’ stage created, and by default all resources get inserted into that stage.

You can only set stages on class resources, not normal builtin resources.

Parameters

name
The name of the stage. This will be used as the ‘stage’ for each resource.

tidy

Remove unwanted files based on specific criteria. Multiple criteria are OR’d together, so a file that is too large but is not old enough will still get tidied.

If you don’t specify either age or size, then all files will be removed.

This resource type works by generating a file resource for every file that should be deleted and then letting that resource perform the actual deletion.

Parameters

age
Tidy files whose age is equal to or greater than the specified time. You can choose seconds, minutes, hours, days, or weeks by specifying the first letter of any of those words (e.g., ‘1w’).

Specifying 0 will remove all files.

backup
Whether tidied files should be backed up. Any values are passed directly to the file resources used for actual file deletion, so consult the file type’s backup documentation to determine valid values.
matches
One or more (shell type) file glob patterns, which restrict the list of files to be tidied to those whose basenames match at least one of the patterns specified. Multiple patterns can be specified using an array.

Example:

tidy { "/tmp":
  age     => "1w",
  recurse => 1,
  matches => [ "[0-9]pub*.tmp", "*.temp", "tmpfile?" ]
}

This removes files from /tmp if they are one week old or older, are not in a subdirectory and match one of the shell globs given.

Note that the patterns are matched against the basename of each file – that is, your glob patterns should not have any ‘/’ characters in them, since you are only specifying against the last bit of the file.

Finally, note that you must now specify a non-zero/non-false value for recurse if matches is used, as matches only apply to files found by recursion (there’s no reason to use static patterns match against a statically determined path). Requiering explicit recursion clears up a common source of confusion.

path
(Namevar: If omitted, this parameter’s value defaults to the resource’s title.)

The path to the file or directory to manage. Must be fully qualified.

recurse
If target is a directory, recursively descend into the directory looking for files to tidy. Valid values are true, false, inf. Values can match /^[0-9]+$/.
rmdirs
Tidy directories in addition to files; that is, remove directories whose age is older than the specified criteria. This will only remove empty directories, so all contained files must also be tidied before a directory gets removed. Valid values are true, false.
size
Tidy files whose size is equal to or greater than the specified size. Unqualified values are in kilobytes, but b, k, m, g, and t can be appended to specify bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively. Only the first character is significant, so the full word can also be used.
type
Set the mechanism for determining age. Default: atime. Valid values are atime, mtime, ctime.

user

Manage users. This type is mostly built to manage system users, so it is lacking some features useful for managing normal users.

This resource type uses the prescribed native tools for creating groups and generally uses POSIX APIs for retrieving information about them. It does not directly modify /etc/passwd or anything.

Autorequires: If Puppet is managing the user’s primary group (as provided in the gid attribute), the user resource will autorequire that group. If Puppet is managing any role accounts corresponding to the user’s roles, the user resource will autorequire those role accounts.

Features

  • allows_duplicates: The provider supports duplicate users with the same UID.
  • manages_aix_lam: The provider can manage AIX Loadable Authentication Module (LAM) system.
  • manages_expiry: The provider can manage the expiry date for a user.
  • manages_homedir: The provider can create and remove home directories.
  • manages_password_age: The provider can set age requirements and restrictions for passwords.
  • manages_passwords: The provider can modify user passwords, by accepting a password hash.
  • manages_solaris_rbac: The provider can manage roles and normal users
  • system_users: The provider allows you to create system users with lower UIDs.
Provider allows duplicates manages aix lam manages expiry manages homedir manages password age manages passwords manages solaris rbac system users
aix   X X X X X    
directoryservice           X    
hpuxuseradd X     X        
ldap           X    
pw X   X X   X    
user_role_add X     X X X X  
useradd X   X X X X   X
windows_adsi       X   X    

Parameters

allowdupe
Whether to allow duplicate UIDs. Defaults to false. Valid values are true, false.
attribute_membership
Whether specified attribute value pairs should be treated as the complete list (inclusive) or the minimum list (minimum) of attribute/value pairs for the user. Defaults to minimum. Valid values are inclusive, minimum.
attributes
Specify AIX attributes for the user in an array of attribute = value pairs. Requires features manages_aix_lam.
auth_membership
Whether specified auths should be considered the complete list (inclusive) or the minimum list (minimum) of auths the user has. Defaults to minimum. Valid values are inclusive, minimum.
auths
The auths the user has. Multiple auths should be specified as an array. Requires features manages_solaris_rbac.
comment
A description of the user. Generally the user’s full name.
ensure
The basic state that the object should be in. Valid values are present, absent, role.
expiry
The expiry date for this user. Must be provided in a zero-padded YYYY-MM-DD format — e.g. 2010-02-19. Requires features manages_expiry.
gid
The user’s primary group. Can be specified numerically or by name.

Note that users on Windows systems do not have a primary group; manage groups with the groups attribute instead.

groups
The groups to which the user belongs. The primary group should not be listed, and groups should be identified by name rather than by GID. Multiple groups should be specified as an array.
home
The home directory of the user. The directory must be created separately and is not currently checked for existence.
ia_load_module
The name of the I&A module to use to manage this user. Requires features manages_aix_lam.
key_membership
Whether specified key/value pairs should be considered the complete list (inclusive) or the minimum list (minimum) of the user’s attributes. Defaults to minimum. Valid values are inclusive, minimum.
keys
Specify user attributes in an array of key = value pairs. Requires features manages_solaris_rbac.
managehome
Whether to manage the home directory when managing the user. Defaults to false. Valid values are true, false.
membership
Whether specified groups should be considered the complete list (inclusive) or the minimum list (minimum) of groups to which the user belongs. Defaults to minimum. Valid values are inclusive, minimum.
name
The user name. While naming limitations vary by operating system, it is advisable to restrict names to the lowest common denominator, which is a maximum of 8 characters beginning with a letter.

Note that Puppet considers user names to be case-sensitive, regardless of the platform’s own rules; be sure to always use the same case when referring to a given user.

password
The user’s password, in whatever encrypted format the local system requires.
  • Most modern Unix-like systems use salted SHA1 password hashes. You can use Puppet’s built-in sha1 function to generate a hash from a password.
  • Mac OS X 10.5 and 10.6 also use salted SHA1 hashes.
  • Mac OS X 10.7 (Lion) uses salted SHA512 hashes. The Puppet Labs stdlib module contains a str2saltedsha512 function which can generate password hashes for Lion.
  • Windows passwords can only be managed in cleartext, as there is no Windows API for setting the password hash.

Be sure to enclose any value that includes a dollar sign ($) in single quotes (‘) to avoid accidental variable interpolation. Requires features manages_passwords.

password_max_age
The maximum number of days a password may be used before it must be changed. Requires features manages_password_age.
password_min_age
The minimum number of days a password must be used before it may be changed. Requires features manages_password_age.
profile_membership
Whether specified roles should be treated as the complete list (inclusive) or the minimum list (minimum) of roles of which the user is a member. Defaults to minimum. Valid values are inclusive, minimum.
profiles
The profiles the user has. Multiple profiles should be specified as an array. Requires features manages_solaris_rbac.
project
The name of the project associated with a user. Requires features manages_solaris_rbac.
provider
The specific backend to use for this user resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
aix
User management for AIX.

Required binaries: /usr/sbin/lsgroup, /bin/chpasswd, /usr/bin/chuser, /usr/sbin/lsuser, /usr/sbin/rmuser, /usr/bin/mkuser. Default for operatingsystem == aix. Supported features: manages_aix_lam, manages_expiry, manages_homedir, manages_password_age, manages_passwords.

directoryservice
User management using DirectoryService on OS X.

Required binaries: /usr/bin/dscl. Default for operatingsystem == darwin. Supported features: manages_passwords.

hpuxuseradd
User management for HP-UX. This provider uses the undocumented -F switch to HP-UX’s special usermod binary to work around the fact that its standard usermod cannot make changes while the user is logged in.

Required binaries: /usr/sam/lbin/usermod.sam, /usr/sam/lbin/userdel.sam, /usr/sbin/useradd. Default for operatingsystem == hp-ux. Supported features: allows_duplicates, manages_homedir.

ldap
User management via LDAP.

This provider requires that you have valid values for all of the LDAP-related settings in puppet.conf, including ldapbase. You will almost definitely need settings for ldapuser and ldappassword in order for your clients to write to LDAP.

Note that this provider will automatically generate a UID for you if you do not specify one, but it is a potentially expensive operation, as it iterates across all existing users to pick the appropriate next one.

Supported features: manages_passwords.

pw
User management via pw on FreeBSD.

Required binaries: pw. Default for operatingsystem == freebsd. Supported features: allows_duplicates, manages_expiry, manages_homedir, manages_passwords.

user_role_add
User and role management on Solaris, via useradd and roleadd.

Required binaries: roleadd, roledel, usermod, userdel, rolemod, passwd, useradd. Default for osfamily == solaris. Supported features: allows_duplicates, manages_homedir, manages_password_age, manages_passwords, manages_solaris_rbac.

useradd
User management via useradd and its ilk. Note that you will need to install Ruby’s shadow password library (often known as ruby-libshadow) if you wish to manage user passwords.

Required binaries: usermod, userdel, chage, useradd. Supported features: allows_duplicates, manages_expiry, manages_homedir, system_users.

windows_adsi
Local user management for Windows.

Default for operatingsystem == windows. Supported features: manages_homedir, manages_passwords.

role_membership
Whether specified roles should be considered the complete list (inclusive) or the minimum list (minimum) of roles the user has. Defaults to minimum. Valid values are inclusive, minimum.
roles
The roles the user has. Multiple roles should be specified as an array. Requires features manages_solaris_rbac.
shell
The user’s login shell. The shell must exist and be executable.

This attribute cannot be managed on Windows systems.

system
Whether the user is a system user, according to the OS’s criteria; on most platforms, a UID less than or equal to 500 indicates a system user. Defaults to false. Valid values are true, false.
uid
The user ID; must be specified numerically. If no user ID is specified when creating a new user, then one will be chosen automatically. This will likely result in the same user having different UIDs on different systems, which is not recommended. This is especially noteworthy when managing the same user on both Darwin and other platforms, since Puppet does UID generation on Darwin, but the underlying tools do so on other platforms.

On Windows, this property is read-only and will return the user’s security identifier (SID).

vlan

Manages a VLAN on a router or switch.

Parameters

description
The VLAN’s name.
device_url
The URL of the router or switch maintaining this VLAN.
ensure
The basic property that the resource should be in. Valid values are present, absent.
name
The numeric VLAN ID. Values can match /^\d+/.
provider
The specific backend to use for this vlan 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 vlans.

yumrepo

The client-side description of a yum repository. Repository configurations are found by parsing /etc/yum.conf and the files indicated by the reposdir option in that file (see yum.conf(5) for details).

Most parameters are identical to the ones documented in the yum.conf(5) man page.

Continuation lines that yum supports (for the baseurl, for example) are not supported. This type does not attempt to read or verify the exinstence of files listed in the include attribute.

Parameters

baseurl
The URL for this repository. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
cost
Cost of this repository. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /\d+/.
descr
A human-readable description of the repository. This corresponds to the name parameter in yum.conf(5). Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
enabled
Whether this repository is enabled, as represented by a 0 or 1. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /(0|1)/.
enablegroups
Whether yum will allow the use of package groups for this repository, as represented by a 0 or 1. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /(0|1)/.
exclude
List of shell globs. Matching packages will never be considered in updates or installs for this repo. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
failovermethod
The failover methode for this repository; should be either roundrobin or priority. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /roundrobin|priority/.
gpgcheck
Whether to check the GPG signature on packages installed from this repository, as represented by a 0 or 1. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /(0|1)/.
gpgkey
The URL for the GPG key with which packages from this repository are signed. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
http_caching
What to cache from this repository. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /packages|all|none/.
include
The URL of a remote file containing additional yum configuration settings. Puppet does not check for this file’s existence or validity. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
includepkgs
List of shell globs. If this is set, only packages matching one of the globs will be considered for update or install from this repo. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
keepalive
Whether HTTP/1.1 keepalive should be used with this repository, as represented by a 0 or 1. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /(0|1)/.
metadata_expire
Number of seconds after which the metadata will expire. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /[0-9]+/.
mirrorlist
The URL that holds the list of mirrors for this repository. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
name
The name of the repository. This corresponds to the repositoryid parameter in yum.conf(5).
priority
Priority of this repository from 1-99. Requires that the priorities plugin is installed and enabled. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /[1-9][0-9]?/.
protect
Enable or disable protection for this repository. Requires that the protectbase plugin is installed and enabled. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /(0|1)/.
proxy
URL to the proxy server for this repository. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
proxy_password
Password for this proxy. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
proxy_username
Username for this proxy. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
sslcacert
Path to the directory containing the databases of the certificate authorities yum should use to verify SSL certificates. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
sslclientcert
Path to the SSL client certificate yum should use to connect to repos/remote sites. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
sslclientkey
Path to the SSL client key yum should use to connect to repos/remote sites. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /.*/.
sslverify
Should yum verify SSL certificates/hosts at all. Possible values are ‘True’ or ‘False’. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /True|False/.
timeout
Number of seconds to wait for a connection before timing out. Set this to absent to remove it from the file completely. Valid values are absent. Values can match /[0-9]+/.

zfs

Manage zfs. Create destroy and set properties on zfs instances.

Autorequires: If Puppet is managing the zpool at the root of this zfs instance, the zfs resource will autorequire it. If Puppet is managing any parent zfs instances, the zfs resource will autorequire them.

Parameters

aclinherit
The aclinherit property. Valid values are discard, noallow, restricted, passthrough, passthrough-x.
aclmode
The aclmode property. Valid values are discard, groupmask, passthrough.
atime
The atime property. Valid values are on, off.
canmount
The canmount property. Valid values are on, off, noauto.
checksum
The checksum property. Valid values are on, off, fletcher2, fletcher4, sha256.
compression
The compression property. Valid values are on, off, lzjb, gzip, gzip-[1-9], zle.
copies
The copies property. Valid values are 1, 2, 3.
dedup
The dedup property. Valid values are on, off.
devices
The devices property. Valid values are on, off.
ensure
The basic property that the resource should be in. Valid values are present, absent.
exec
The exec property. Valid values are on, off.
logbias
The logbias property. Valid values are latency, throughput.
mountpoint
The mountpoint property. Valid values are <path>, legacy, none.
name
The full name for this filesystem (including the zpool).
nbmand
The nbmand property. Valid values are on, off.
primarycache
The primarycache property. Valid values are all, none, metadata.
provider
The specific backend to use for this zfs resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
zfs
Provider for zfs.

Required binaries: zfs.

quota
The quota property. Valid values are <size>, none.
readonly
The readonly property. Valid values are on, off.
recordsize
The recordsize property. Valid values are powers of two between 512 and 128k.
refquota
The refquota property. Valid values are <size>, none.
refreservation
The refreservation property. Valid values are <size>, none.
reservation
The reservation property. Valid values are <size>, none.
secondarycache
The secondarycache property. Valid values are all, none, metadata.
setuid
The setuid property. Valid values are on, off.
shareiscsi
The shareiscsi property. Valid values are on, off, type=<type>.
sharenfs
The sharenfs property. Valid values are on, off, share(1M) options
sharesmb
The sharesmb property. Valid values are on, off, sharemgr(1M) options
snapdir
The snapdir property. Valid values are hidden, visible.
version
The version property. Valid values are 1, 2, 3, 4, current.
volsize
The volsize property. Valid values are <size>
vscan
The vscan property. Valid values are on, off.
xattr
The xattr property. Valid values are on, off.
zoned
The zoned property. Valid values are on, off.

zone

Manages Solaris zones.

Autorequires: If Puppet is managing the directory specified as the root of the zone’s filesystem (with the path attribute), the zone resource will autorequire that directory.

Parameters

autoboot
Whether the zone should automatically boot. Valid values are true, false.
clone
Instead of installing the zone, clone it from another zone. If the zone root resides on a zfs file system, a snapshot will be used to create the clone; if it resides on a ufs filesystem, a copy of the zone will be used. The zone from which you clone must not be running.
create_args
Arguments to the zonecfg create command. This can be used to create branded zones.
dataset
The list of datasets delegated to the non-global zone from the global zone. All datasets must be zfs filesystem names which are different from the mountpoint.
ensure
The running state of the zone. The valid states directly reflect the states that zoneadm provides. The states are linear, in that a zone must be configured, then installed, and only then can be running. Note also that halt is currently used to stop zones. Valid values are absent, configured, installed, running.
id
The numerical ID of the zone. This number is autogenerated and cannot be changed.
inherit
The list of directories that the zone inherits from the global zone. All directories must be fully qualified.
install_args
Arguments to the zoneadm install command. This can be used to create branded zones.
ip
The IP address of the zone. IP addresses must be specified with the interface, separated by a colon, e.g.: bge0:192.168.0.1. For multiple interfaces, specify them in an array.
iptype
The IP stack type of the zone. Valid values are shared, exclusive.
name
The name of the zone.
path
The root of the zone’s filesystem. Must be a fully qualified file name. If you include %s in the path, then it will be replaced with the zone’s name. Currently, you cannot use Puppet to move a zone. Consequently this is a readonly property.
pool
The resource pool for this zone.
provider
The specific backend to use for this zone resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
solaris
Provider for Solaris Zones.

Required binaries: /usr/sbin/zoneadm, /usr/sbin/zonecfg. Default for osfamily == solaris.

realhostname
The actual hostname of the zone.
shares
Number of FSS CPU shares allocated to the zone.
sysidcfg
The text to go into the sysidcfg file when the zone is first booted. The best way is to use a template: 
# $confdir/modules/site/templates/sysidcfg.erb
system_locale=en_US
timezone=GMT
terminal=xterms
security_policy=NONE
root_password=<%= password %>
timeserver=localhost
name_service=DNS {domain_name=<%= domain %> name_server=<%= nameserver %>}
network_interface=primary {hostname=<%= realhostname %>
  ip_address=<%= ip %>
  netmask=<%= netmask %>
  protocol_ipv6=no
  default_route=<%= defaultroute %>}
nfs4_domain=dynamic

And then call that:

zone { myzone:
  ip           => "bge0:192.168.0.23",
  sysidcfg     => template("site/sysidcfg.erb"),
  path         => "/opt/zones/myzone",
  realhostname => "fully.qualified.domain.name"
}

The sysidcfg only matters on the first booting of the zone, so Puppet only checks for it at that time.

zpool

Manage zpools. Create and delete zpools. The provider WILL NOT SYNC, only report differences.

Supports vdevs with mirrors, raidz, logs and spares.

Parameters

disk
The disk(s) for this pool. Can be an array or a space separated string.
ensure
The basic property that the resource should be in. Valid values are present, absent.
log
Log disks for this pool. This type does not currently support mirroring of log disks.
mirror
List of all the devices to mirror for this pool. Each mirror should be a space separated string: 
mirror => ["disk1 disk2", "disk3 disk4"],
pool
(Namevar: If omitted, this parameter’s value defaults to the resource’s title.)

The name for this pool.

provider
The specific backend to use for this zpool resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform. Available providers are:
zpool
Provider for zpool.

Required binaries: zpool.

raid_parity
Determines parity when using the raidz parameter.
raidz
List of all the devices to raid for this pool. Should be an array of space separated strings: 
raidz => ["disk1 disk2", "disk3 disk4"],
spare
Spare disk(s) for this pool.

This page autogenerated on Mon Oct 22 17:13:30 -0700 2012

↑ Back to top