Resource Type Reference (Single-Page)

(Namevar: If omitted, this attribute'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.

Multiple exec resources can use the same command value; Puppet only uses the resource title to ensure execs are unique.

On *nix platforms, the command can be specified as an array of strings and Puppet will invoke it using the more secure method of parameterized system calls. For example, rather than executing the malicious injected code, this command will echo it out:

command => ['/bin/echo', 'hello world; rm -rf /']

(↑ Back to exec attributes)

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.

(↑ Back to exec attributes)

The directory from which to run the command. If this directory does not exist, the command will fail.

(↑ Back to exec attributes)

An array of any additional environment variables you want to set for a command, such as [ 'HOME=/root', 'MAIL=root@example.com']. Note that if you use this to set PATH, it will override the path attribute. Multiple environment variables should be specified as an array.

(↑ Back to exec attributes)

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.

(↑ Back to exec attributes)

Whether to log command output in addition to logging the exit code. Defaults to on_failure, which only logs the output when the command has an exit code that does not match any value specified by the returns attribute. As with any resource type, the log level can be controlled with the loglevel metaparameter.

Valid values are true, false, on_failure.

(↑ Back to exec attributes)

A test command that checks the state of the target system and restricts when the exec can run. If present, Puppet runs this test command first, and only runs the main command if the test has an exit code of 0 (success). For example:

exec { 'logrotate':
  path     => '/usr/bin:/usr/sbin:/bin',
  provider => shell,
  onlyif   => 'test `du /var/log/messages | cut -f1` -gt 100000',
}

This would run logrotate only if that test returns true.

Note that this test command runs with the same provider, path, user, cwd, and group as the main command. If the path isn't set, you must fully qualify the command's name.

Since this command is used in the process of determining whether the exec is already in sync, it must be run during a noop Puppet run.

This parameter can also take an array of commands. For example:

onlyif => ['test -f /tmp/file1', 'test -f /tmp/file2'],

or an array of arrays. For example:

onlyif => [['test', '-f', '/tmp/file1'], 'test -f /tmp/file2']

This exec would only run if every command in the array has an exit code of 0 (success).

(↑ Back to exec attributes)

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.

(↑ Back to exec attributes)

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

• shell

• windows

(↑ Back to exec attributes)

An alternate command to run when the exec receives a refresh event from another resource. By default, Puppet runs the main command again. For more details, see the notes about refresh behavior above, in the description for this resource type.

Note that this alternate command runs with the same provider, path, user, and group as the main command. If the path isn't set, you must fully qualify the command's name.

(↑ Back to exec attributes)

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.

(↑ Back to exec attributes)

(Property: This attribute represents concrete state on the target system.)

The expected exit code(s). An error will be returned if the executed command has some other exit code. Can be specified as an array of acceptable exit codes or a single value.

On POSIX systems, exit codes are always integers between 0 and 255.

On Windows, most exit codes should be integers between 0 and 2147483647.

Larger exit codes on Windows can behave inconsistently across different tools. The Win32 APIs define exit codes as 32-bit unsigned integers, but both the cmd.exe shell and the .NET runtime cast them to signed integers. This means some tools will report negative numbers for exit codes above 2147483647. (For example, cmd.exe reports 4294967295 as -1.) Since Puppet uses the plain Win32 APIs, it will report the very large number instead of the negative number, which might not be what you expect if you got the exit code from a cmd.exe session.

Microsoft recommends against using negative/very large exit codes, and you should avoid them when possible. To convert a negative exit code to the positive one Puppet will use, add it to 4294967296.

(↑ Back to exec attributes)

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.

(↑ Back to exec attributes)

The number of times execution of the command should be tried. This many attempts will be made to execute the command until an acceptable return code is returned. Note that the timeout parameter applies to each try rather than to the complete set of tries.

(↑ Back to exec attributes)

The time to sleep in seconds between 'tries'.

(↑ Back to exec attributes)

Sets the umask to be used while executing this command

(↑ Back to exec attributes)

A test command that checks the state of the target system and restricts when the exec can run. If present, Puppet runs this test command first, then runs the main command unless the test has an exit code of 0 (success). 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 test command runs with the same provider, path, user, cwd, and group as the main command. If the path isn't set, you must fully qualify the command's name.

Since this command is used in the process of determining whether the exec is already in sync, it must be run during a noop Puppet run.

This parameter can also take an array of commands. For example:

unless => ['test -f /tmp/file1', 'test -f /tmp/file2'],

or an array of arrays. For example:

unless => [['test', '-f', '/tmp/file1'], 'test -f /tmp/file2']

This exec would only run if every command in the array has a non-zero exit code.

(↑ Back to exec attributes)

The user to run the command as.

Note: Puppet cannot execute commands as other users on Windows.

Note that if you use this attribute, any error output is not captured due to a bug within Ruby. If you use Puppet to create this user, the exec automatically requires the user, as long as it is specified by name.

The $HOME environment variable is not automatically set when using this attribute.

(↑ Back to exec attributes)

Executes external binaries by invoking Ruby's Kernel.exec. When the command is a string, it will be executed directly, without a shell, if it follows these rules:

• no meta characters

• no shell reserved word and no special built-in

When the command is an Array of Strings, passed as [cmdname, arg1, ...] it will be executed directly(the first element is taken as a command name and the rest are passed as parameters to command with no shell expansion) 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).

If the use of globbing and shell built-ins is desired, please check the shell provider

• Default for feature == posix.

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.

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.

(Namevar: If omitted, this attribute'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 \).

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

Whether the file should exist, and if so what kind of file it should be. Possible values are present, absent, file, directory, and link.

• present accepts any form of file existence, and creates a normal file if the file is missing. (The file will have no content unless the content or source attribute is used.)

• absent ensures the file doesn't exist, and deletes it if necessary.

• file ensures it's a normal file, and enables use of the content or source attribute.

• directory ensures it's a directory, and enables use of the source, recurse, recurselimit, ignore, and purge attributes.

• link ensures the file is a symlink, and requires that you also set the target attribute. Symlinks are supported on all Posix systems and on Windows Vista / 2008 and higher. On Windows, managing symlinks requires Puppet agent's user account to have the "Create Symbolic Links" privilege; this can be configured in the "User Rights Assignment" section in the Windows policy editor. By default, Puppet agent runs as the Administrator account, which has this privilege.

Puppet avoids destroying directories unless the force attribute is set to true. This means that if a file is currently a directory, setting ensure to anything but directory or present will cause Puppet to skip managing the resource and log either a notice or an error.

There is one other non-standard value for ensure. If you specify the path to another file as the ensure value, it is equivalent to specifying link and using that path as the target:

# Equivalent resources:

file { '/etc/inetd.conf':
  ensure => '/etc/inet/inetd.conf',
}

file { '/etc/inetd.conf':
  ensure => link,
  target => '/etc/inet/inetd.conf',
}

However, we recommend using link and target explicitly, since this behavior can be harder to read and is deprecated as of Puppet 4.3.0.

Valid values are absent (also called false), file, present, directory, link. Values can match /./.

(↑ Back to file attributes)

Whether (and how) file content should be backed up before being replaced. This attribute works best as a resource default in the site manifest (File { backup => main }), so it can affect all file resources.

• If set to false, file content won't be backed up.

• If set to a string beginning with ., such as .puppet-bak, Puppet will use copy the file in the same directory with that value as the extension of the backup. (A value of true is a synonym for .puppet-bak.)

• If set to any other string, Puppet will try to back up to a filebucket with that title. Puppet automatically creates a local filebucket named puppet if one doesn't already exist. See the filebucket resource type for more details.

Default value: false

Backing up to a local filebucket isn't particularly useful. If you want to make organized use of backups, you will generally want to use the primary Puppet server's filebucket service. This requires declaring a filebucket resource and a resource default for the backup attribute in site.pp:

# /etc/puppetlabs/puppet/manifests/site.pp
filebucket { 'main':
  path   => false,                # This is required for remote filebuckets.
  server => 'puppet.example.com', # Optional; defaults to the configured primary Puppet server.
}

File { backup => main, }

If you are using multiple primary servers, you will want to centralize the contents of the filebucket. Either configure your load balancer to direct all filebucket traffic to a single primary server, or use something like an out-of-band rsync task to synchronize the content on all primary servers.

Note: Enabling and using the backup option, and by extension the filebucket resource, requires appropriate planning and management to ensure that sufficient disk space is available for the file backups. Generally, you can implement this using one of the following two options:

• Use a find command and crontab entry to retain only the last X days of file backups. For example:

find /opt/puppetlabs/server/data/puppetserver/bucket -type f -mtime +45 -atime +45 -print0 | xargs -0 rm

• Restrict the directory to a maximum size after which the oldest items are removed.

(↑ Back to file attributes)

The checksum type to use when determining whether to replace a file's contents.

The default checksum type is sha256.

Valid values are sha256, sha256lite, md5, md5lite, sha1, sha1lite, sha512, sha384, sha224, mtime, ctime, none.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

The checksum of the source contents. Only md5, sha256, sha224, sha384 and sha512 are supported when specifying this parameter. If this parameter is set, source_permissions will be assumed to be false, and ownership and permissions will not be read from source.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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 or file function.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file ctime. On most modern *nix-like systems, this is the time of the most recent change to the owner, group, permissions, or content of the file.

(↑ Back to file attributes)

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, yes, no.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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.)

(↑ Back to file attributes)

A parameter which omits action on files matching specified patterns during recursion. Uses Ruby's builtin globbing engine, so shell metacharacters such as [a-z]* are fully supported. Matches that would descend into the directory structure are ignored, such as */*.

(↑ Back to file attributes)

How to handle links during file actions. During file copying, follow will copy the target file instead of the link and manage will copy the link itself. When not copying, manage will manage the link, and follow will manage the file to which the link points.

Valid values are follow, manage.

(↑ Back to file attributes)

In case the resource is a directory and the recursion is enabled, puppet will generate a new resource for each file file found, possible leading to an excessive number of resources generated without any control.

Setting max_files will check the number of file resources that will eventually be created and will raise a resource argument error if the limit will be exceeded.

Use value 0 to log a warning instead of raising an error.

Use value -1 to disable errors and warnings due to max files.

Values can match /^[0-9]+$/, /^-1$/.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

The desired permissions mode for the file, in symbolic or numeric notation. This value must be specified as a string; do not use un-quoted numbers to represent file modes.

If the mode is omitted (or explicitly set to undef), Puppet does not enforce permissions on existing files and creates new files with permissions of 0644.

The file type uses traditional Unix permission schemes and translates them to equivalent permissions for systems which represent permissions differently, including Windows. For detailed ACL controls on Windows, you can leave mode unmanaged and use the puppetlabs/acl module.

Numeric modes should use the standard octal notation of <SETUID/SETGID/STICKY><OWNER><GROUP><OTHER> (for example, "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.

• The setuid/setgid/sticky digit is also a sum, where setuid = 4, setgid = 2, and sticky = 1.

• The setuid/setgid/sticky digit is optional. If it is absent, Puppet will clear any existing setuid/setgid/sticky permissions. (So to make your intent clear, you should use at least four digits for numeric modes.)

• When specifying 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 any combination of u (user), g (group), and o (other), 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. However, symbolic modes are more expressive than numeric modes: a mode only affects the specified bits, so mode => 'ug+w' will set the user and group write bits, without affecting any other bits.

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.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file mtime. On *nix-like systems, this is the time of the most recent change to the content of the file.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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.)

(↑ Back to file attributes)

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

• windows

(↑ Back to file attributes)

Whether unmanaged files should be purged. This option only makes sense when ensure => directory and 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.

Unless force => true is set, purging will not delete directories, although it will delete the files they contain.

If recurselimit is set and you aren't using force => true, purging will obey the recursion limit; files in any subdirectories deeper than the limit will be treated as unmanaged and left alone.

Valid values are true, false, yes, no.

(↑ Back to file attributes)

Whether to recursively manage the contents of a directory. This attribute is only used when ensure => directory is set. The allowed values are:

• false --- The default behavior. The contents of the directory will not be automatically managed.

• remote --- If the source attribute is set, Puppet will automatically manage the contents of the source directory (or directories), ensuring that equivalent files and directories exist on the target system and that their contents match.

  Using remote will disable the purge attribute, but results in faster catalog application than recurse => true.

  The source attribute is mandatory when recurse => remote.

• true --- If the source attribute is set, this behaves similarly to recurse => remote, automatically managing files from the source directory.

  This also enables the purge attribute, which can delete unmanaged files from a directory. See the description of purge for more details.

  The source attribute is not mandatory when using recurse => true, so you can enable purging in directories where all files are managed individually.

By default, setting recurse to remote or true will manage all subdirectories. You can use the recurselimit attribute to limit the recursion depth.

Valid values are true, false, remote.

(↑ Back to file attributes)

How far Puppet should descend into subdirectories, when using ensure => directory and either recurse => true or recurse => remote. The recursion limit affects which files will be copied from the source directory, as well as which files can be purged when purge => true.

Setting recurselimit => 0 is the same as setting recurse => false --- Puppet will manage the directory, but all of its contents will be treated as unmanaged.

Setting recurselimit => 1 will manage files and directories that are directly inside the directory, but will not manage the contents of any subdirectories.

Setting recurselimit => 2 will manage the direct contents of the directory, as well as the contents of the first level of subdirectories.

This pattern continues for each incremental value of recurselimit.

Values can match /^[0-9]+$/.

(↑ Back to file attributes)

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.

Valid values are true, false, yes, no.

(↑ Back to file attributes)

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.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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).

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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.

(↑ Back to file attributes)

Whether to display differences when the file changes, defaulting to true. This parameter is useful for files that may contain passwords or other secret data, which might otherwise be included in Puppet reports or other insecure outputs. If the global show_diff setting is false, then no diffs will be shown even if this parameter is true.

Valid values are true, false, yes, no.

(↑ Back to file attributes)

A source file, which will be copied into place on the local system. This attribute is mutually exclusive with content and target. Allowed values are:

• puppet: URIs, which point to files in modules or Puppet file server mount points.

• Fully qualified paths to locally available files (including files on NFS shares or Windows mapped drives).

• file: URIs, which behave the same as local file paths.

• http(s): URIs, which point to files served by common web servers.

The normal form of a puppet: URI is:

puppet:///modules/<MODULE NAME>/<FILE PATH>

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/code/modules, the example above would resolve to /etc/puppetlabs/code/modules/<MODULE NAME>/files/<FILE PATH>.

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.

HTTP URIs cannot be used to recursively synchronize whole directory trees. You cannot use source_permissions values other than ignore because HTTP servers do not transfer any metadata that translates to ownership or permission details.

Puppet determines if file content is synchronized by computing a checksum for the local file and comparing it against the checksum_value parameter. If the checksum_value parameter is not specified for puppet and file sources, Puppet computes a checksum based on its Puppet[:digest_algorithm]. For http(s) sources, Puppet uses the first HTTP header it recognizes out of the following list: X-Checksum-Sha256, X-Checksum-Sha1, X-Checksum-Md5 or Content-MD5. If the server response does not include one of these headers, Puppet defaults to using the Last-Modified header. Puppet updates the local file if the header is newer than the modified time (mtime) of the local file.

HTTP URIs can include a user information component so that Puppet can retrieve file metadata and content from HTTP servers that require HTTP Basic authentication. For example https://<user>:<pass>@<server>:<port>/path/to/file.

When connecting to HTTPS servers, Puppet trusts CA certificates in the puppet-agent certificate bundle and the Puppet CA. You can configure Puppet to trust additional CA certificates using the Puppet[:ssl_trust_store] setting.

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.

(↑ Back to file attributes)

Whether (and how) Puppet should copy owner, group, and mode permissions from the source to file resources when the permissions are not explicitly specified. (In all cases, explicit permissions will take precedence.) Valid values are use, use_when_creating, and ignore:

• ignore (the default) will never apply the owner, group, or mode from the source when managing a file. When creating new files without explicit permissions, the permissions they receive will depend on platform-specific behavior. On POSIX, Puppet will use the umask of the user it is running as. On Windows, Puppet will use the default DACL associated with the user it is running as.

• use will cause Puppet to apply the owner, group, and mode from the source to any files it is managing.

• use_when_creating will only apply the owner, group, and mode from the source when creating a file; existing files will not have their permissions overwritten.

Valid values are use, use_when_creating, ignore.

(↑ Back to file attributes)

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.

(↑ Back to file attributes)

When rendering a file first render it to this location. The default location is the same path as the desired location with a unique filename. This parameter is useful in conjuction with validate_cmd to test a file before moving the file to it's final location. WARNING: File replacement is only guaranteed to be atomic if the staging location is on the same filesystem as the final location.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

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 /./.

(↑ Back to file attributes)

(Property: This attribute represents concrete state on the target system.)

A read-only state to check the file type.

(↑ Back to file attributes)

A command for validating the file's syntax before replacing it. If Puppet would need to rewrite a file due to new source or content, it will check the new content's validity first. If validation fails, the file resource will fail.

This command must have a fully qualified path, and should contain a percent (%) token where it would expect an input file. It must exit 0 if the syntax is correct, and non-zero otherwise. The command will be run on the target system while applying the catalog, not on the primary Puppet server.

Example:

file { '/etc/apache2/apache2.conf':
  content      => 'example',
  validate_cmd => '/usr/sbin/apache2 -t -f %',
}

This would replace apache2.conf only if the test returned true.

Note that if a validation command requires a % as part of its text, you can specify a different placeholder token with the validate_replacement attribute.

(↑ Back to file attributes)

The replacement string in a validate_cmd that will be replaced with an input file name.

(↑ Back to file attributes)

Uses POSIX functionality to manage file ownership and permissions.

• Supported features: manages_symlinks.

Uses Microsoft Windows functionality to manage file ownership and permissions.

• Supported features: manages_symlinks.

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

The name of the filebucket.

(↑ Back to filebucket attributes)

The path to the local filebucket; defaults to the value of the clientbucketdir setting. To use a remote filebucket, you must set this attribute to false.

(↑ Back to filebucket attributes)

The port on which the remote server is listening.

This setting is only consulted if the path attribute is set to false.

If this attribute is not specified, the first entry in the server_list configuration setting is used, followed by the value of the serverport setting if server_list is not set.

(↑ Back to filebucket attributes)

The server providing the remote filebucket service.

This setting is only consulted if the path attribute is set to false.

If this attribute is not specified, the first entry in the server_list configuration setting is used, followed by the value of the server setting if server_list is not set.

(↑ Back to filebucket attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

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.

(↑ Back to group attributes)

(Property: This attribute represents concrete state on the target system.)

Create or remove the group.

Valid values are present, absent.

(↑ Back to group attributes)

Whether to allow duplicate GIDs.

Valid values are true, false, yes, no.

(↑ Back to group attributes)

AIX only. Configures the behavior of the attributes parameter.

• minimum (default) --- The provided list of attributes is partial, and Puppet ignores any attributes that aren't listed there.

• inclusive --- The provided list of attributes is comprehensive, and Puppet purges any attributes that aren't listed there.

Valid values are inclusive, minimum.

(↑ Back to group attributes)

(Property: This attribute represents concrete state on the target system.)

Specify group AIX attributes, as an array of 'key=value' strings. This parameter's behavior can be configured with attribute_membership.

Requires features manages_aix_lam.

(↑ Back to group attributes)

Configures the behavior of the members parameter.

• false (default) --- The provided list of group members is partial, and Puppet ignores any members that aren't listed there.

• true --- The provided list of of group members is comprehensive, and Puppet purges any members that aren't listed there.

Valid values are true, false, yes, no.

(↑ Back to group attributes)

Forces the management of local accounts when accounts are also being managed by some other Name Switch Service (NSS). For AIX, refer to the ia_load_module parameter.

This option relies on your operating system's implementation of luser* commands, such as luseradd , lgroupadd, and lusermod. The forcelocal option could behave unpredictably in some circumstances. If the tools it depends on are not available, it might have no effect at all.

Valid values are true, false, yes, no.

Requires features manages_local_users_and_groups.

(↑ Back to group attributes)

(Property: This attribute represents concrete state on the target system.)

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).

(↑ Back to group attributes)

The name of the I&A module to use to manage this group. This should be set to files if managing local groups.

Requires features manages_aix_lam.

(↑ Back to group attributes)

(Property: This attribute represents concrete state on the target system.)

The members of the group. For platforms or directory services where group membership is stored in the group objects, not the users. This parameter's behavior can be configured with auth_membership.

Requires features manages_members.

(↑ Back to group attributes)

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

• directoryservice

• groupadd

• ldap

• pw

• windows_adsi

(↑ Back to group attributes)

Whether the group is a system group with lower GID.

Valid values are true, false, yes, no.

(↑ Back to group attributes)

Group management for AIX.

• Required binaries: /usr/bin/chgroup, /usr/bin/mkgroup, /usr/sbin/lsgroup, /usr/sbin/rmgroup.

• Default for operatingsystem == aix.

• Supported features: manages_aix_lam, manages_local_users_and_groups, manages_members.

Group management using DirectoryService on OS X.

• Required binaries: /usr/bin/dscl.

• Default for operatingsystem == darwin.

• Supported features: manages_members.

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

To use the forcelocal parameter, you need to install the libuser package (providing /usr/sbin/lgroupadd and /usr/sbin/luseradd).

• Required binaries: groupadd, groupdel, groupmod, lgroupadd, lgroupdel, lgroupmod.

• Supported features: system_groups.

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.

Group management via pw on FreeBSD and DragonFly BSD.

• Required binaries: pw.

• Default for operatingsystem == freebsd, dragonfly.

• Supported features: manages_members.

Local group management for Windows. Group members can be both users and groups. Additionally, local groups can contain domain users.

• Default for operatingsystem == windows.

• Supported features: manages_members.

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

An arbitrary tag for your own reference; the name of the message.

(↑ Back to notify attributes)

(Property: This attribute represents concrete state on the target system.)

The message to be sent to the log. Note that the value specified must be a string.

(↑ Back to notify attributes)

Whether to show the full object path.

Valid values are true, false.

(↑ Back to notify attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

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 a package goes by several names, you can use a single title and then set the name conditionally:

# In the 'openssl' class
$ssl = $operatingsystem ? {
  solaris => SMCossl,
  default => openssl
}

package { 'openssl':
  ensure => installed,
  name   => $ssl,
}

...

$ssh = $operatingsystem ? {
  solaris => SMCossh,
  default => openssh
}

package { 'openssh':
  ensure  => installed,
  name    => $ssh,
  require => Package['openssl'],
}

(↑ Back to package attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

The targeted command to use when managing a package:

package { 'mysql': provider => gem, }

package { 'mysql-opt': name => 'mysql', provider => gem, command => '/opt/ruby/bin/gem', }

Each provider defines a package management command; and uses the first instance of the command found in the PATH.

Providers supporting the targetable feature allow you to specify the absolute path of the package management command; useful when multiple instances of the command are installed, or the command is not in the PATH.

Requires features targetable.

(↑ Back to package attributes)

(Secondary namevar: This resource type allows you to manage multiple resources with the same name as long as their providers are different.)

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

• appdmg

• apple

• apt

• aptitude

• aptrpm

• blastwave

• dnf

• dnfmodule

• dpkg

• fink

• freebsd

• gem

• hpux

• macports

• nim

• openbsd

• opkg

• pacman

• pip2

• pip3

• pip

• pkg

• pkgdmg

• pkgin

• pkgng

• pkgutil

• portage

• ports

• portupgrade

• puppet_gem

• puppetserver_gem

• rpm

• rug

• sun

• sunfreeware

• tdnf

• up2date

• urpmi

• windows

• yum

• zypper

(↑ Back to package attributes)

(Property: This attribute represents concrete state on the target system.)

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. This defaults to installed.

Version numbers must match the full version to install, including release if the provider uses a release moniker. For example, to install the bash package from the rpm bash-4.1.2-29.el6.x86_64.rpm, use the string '4.1.2-29.el6'.

On supported providers, version ranges can also be ensured. For example, inequalities: <2.0.0, or intersections: >1.0.0 <2.0.0.

Valid values are present (also called installed), absent, purged, disabled, latest. Values can match /./.

(↑ Back to package attributes)

A file containing package defaults for installing packages.

This attribute is only used on Solaris. Its value should be a path to a local file stored on the target system. Solaris's package tools expect either an absolute file path or a relative path to a file in /var/sadm/install/admin.

The value of adminfile will be passed directly to the pkgadd or pkgrm command with the -a <ADMINFILE> option.

(↑ Back to package attributes)

Specifies if virtual package names are allowed for install and uninstall.

Valid values are true, false, yes, no.

Requires features virtual_packages.

(↑ Back to package attributes)

Tells apt to allow cdrom sources in the sources.list file. Normally apt will bail if you try this.

Valid values are true, false.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

Whether to keep or replace modified config files when installing or upgrading a package. This only affects the apt and dpkg providers.

Valid values are keep, replace.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

Tells dnf module to only enable a specific module, instead of installing its default profile.

Modules with no default profile will be enabled automatically without the use of this parameter.

Conflicts with the flavor property, which selects a profile to install.

Valid values are true, false, yes, no.

(↑ Back to package attributes)

(Property: This attribute represents concrete state on the target system.)

OpenBSD and DNF modules support 'flavors', which are further specifications for which type of package you want.

Requires features supports_flavors.

(↑ Back to package attributes)

It should be set for packages that should only ever be installed, never updated. Kernels in particular fall into this category.

Valid values are true, false, yes, no.

Requires features install_only.

(↑ Back to package attributes)

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.

With Windows packages, note that file paths in an install option must use backslashes. (Since install options are passed directly to the installation command, forward slashes won't be automatically converted like they are in file resources.) Note also that backslashes in double-quoted strings must be escaped and backslashes in single-quoted strings can be escaped.

Requires features install_options.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

(Property: This attribute represents concrete state on the target system.)

Set to hold to tell Debian apt/Solaris pkg to hold the package version

Valid values are: hold/none Default is "none". Mark can be specified with or without ensure, if ensure is missing will default to "present".

Mark cannot be specified together with "purged", or "absent" values for ensure.

Valid values are hold, none.

Requires features holdable.

(↑ Back to package attributes)

(Property: This attribute represents concrete state on the target system.)

Settings that can change the contents or configuration of a package.

The formatting and effects of package_settings are provider-specific; any provider that implements them must explain how to use them in its documentation. (Our general expectation is that if a package is installed but its settings are out of sync, the provider should re-install that package with the desired settings.)

An example of how package_settings could be used is FreeBSD's port build options --- a future version of the provider could accept a hash of options, and would reinstall the port if the installed version lacked the correct settings.

package { 'www/apache22':
  package_settings => { 'SUEXEC' => false }
}

Again, check the documentation of your platform's package provider to see the actual usage.

Requires features package_settings.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

Whether this resource should respond to refresh events (via subscribe, notify, or the ~> arrow) by reinstalling the package. Only works for providers that support the reinstallable feature.

This is useful for source-based distributions, where you may want to recompile a package if the build options change.

If you use this, be careful of notifying classes when you want to restart services. If the class also contains a refreshable package, doing so could cause unnecessary re-installs.

Valid values are true, false.

(↑ Back to package attributes)

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.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

Where to find the package file. This is mostly used by providers that don't automatically download packages from a central repository. (For example: the yum provider ignores this attribute, apt provider uses it if present and the rpm and dpkg providers require it.)

Different providers accept different values for source. Most providers accept paths to local files stored on the target system. Some providers may also accept URLs or network drive paths. Puppet will not automatically retrieve source files for you, and usually just passes the value of source to the package installation command.

You can use a file resource if you need to manually copy package files to the target system.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

Installation from an AIX software directory, using the AIX installp command. The source parameter is required for this provider, and should be set to the absolute path (on the puppet agent machine) of a directory containing one or more BFF package files.

The installp command will generate a table of contents file (named .toc) in this directory, and the name parameter (or resource title) that you specify for your package resource must match a package name that exists in the .toc file.

Note that package downgrades are not supported; if your resource specifies a specific version number and there is already a newer version of the package installed on the machine, the resource will fail with an error message.

• Required binaries: /usr/bin/lslpp, /usr/sbin/installp.

• Default for operatingsystem == aix.

• Supported features: installable, uninstallable, upgradeable, versionable.

Package management which copies application bundles to a target.

• Required binaries: /usr/bin/curl, /usr/bin/ditto, /usr/bin/hdiutil.

• Supported features: installable.

Package management based on OS X's built-in 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.

Package management via apt-get.

This provider supports the install_options attribute, which allows command-line flags to be passed to apt-get. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/apt-cache, /usr/bin/apt-get, /usr/bin/apt-mark, /usr/bin/debconf-set-selections.

• Default for osfamily == debian.

• Supported features: holdable, install_options, installable, purgeable, uninstallable, upgradeable, versionable, virtual_packages.

Package management via aptitude.

• Required binaries: /usr/bin/apt-cache, /usr/bin/aptitude.

• Supported features: holdable, installable, purgeable, uninstallable, upgradeable, versionable.

Package management via apt-get ported to rpm.

• Required binaries: apt-cache, apt-get, rpm.

• Supported features: installable, purgeable, uninstallable, upgradeable, versionable.

Package management using Blastwave.org's pkg-get command on Solaris.

• Required binaries: pkg-get.

• Supported features: installable, uninstallable, upgradeable.

Support via dnf.

Using this provider's uninstallable feature will not remove dependent packages. To remove dependent packages with this provider use the purgeable feature, but note this feature is destructive and should be used with the utmost care.

This provider supports the install_options attribute, which allows command-line flags to be passed to dnf. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: dnf, rpm.

• Default for operatingsystem == fedora. Default for osfamily == redhat.

• Supported features: install_only, install_options, installable, purgeable, uninstallable, upgradeable, versionable, virtual_packages.

• Required binaries: /usr/bin/dnf.

• Supported features: disableable, installable, purgeable, supports_flavors, uninstallable, upgradeable, versionable.

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-query, /usr/bin/dpkg.

• Supported features: holdable, installable, purgeable, uninstallable, upgradeable, virtual_packages.

Package management via fink.

• Required binaries: /sw/bin/apt-cache, /sw/bin/apt-get, /sw/bin/dpkg-query, /sw/bin/fink.

• Supported features: holdable, installable, purgeable, uninstallable, upgradeable, versionable.

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_delete, /usr/sbin/pkg_info.

• Supported features: installable, purgeable, uninstallable, upgradeable.

Ruby Gem support. If a URL is passed via source, then that URL is appended to the list of remote gem repositories; to ensure that only the specified source is used, also pass --clear-sources via install_options. If 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, the gem will be installed from the default gem repositories. Note that to modify this for Windows, it has to be a valid URL.

This provider supports the install_options and uninstall_options attributes, which allow command-line flags to be passed to the gem command. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: gem.

• Supported features: install_options, installable, targetable, uninstall_options, uninstallable, upgradeable, version_ranges, versionable.

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.

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.

Installation from an AIX NIM LPP source. The source parameter is required for this provider, and should specify the name of a NIM lpp_source resource that is visible to the puppet agent machine. This provider supports the management of both BFF/installp and RPM packages.

Note that package downgrades are not supported; if your resource specifies a specific version number and there is already a newer version of the package installed on the machine, the resource will fail with an error message.

• Required binaries: /usr/bin/lslpp, /usr/sbin/nimclient, rpm.

• Supported features: installable, uninstallable, upgradeable, versionable.

OpenBSD's form of pkg_add support.

This provider supports the install_options and uninstall_options attributes, which allow command-line flags to be passed to pkg_add and pkg_delete. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: pkg_add, pkg_delete, pkg_info.

• Default for operatingsystem == openbsd.

• Supported features: install_options, installable, purgeable, supports_flavors, uninstall_options, uninstallable, upgradeable, versionable.

Opkg packaging support. Common on OpenWrt and OpenEmbedded platforms

• Required binaries: opkg.

• Default for operatingsystem == openwrt.

• Supported features: installable, uninstallable, upgradeable.

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

This provider supports the install_options attribute, which allows command-line flags to be passed to pacman. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/pacman.

• Default for operatingsystem == archlinux, manjarolinux.

• Supported features: install_options, installable, uninstall_options, uninstallable, upgradeable, virtual_packages.

Python packages via pip.

This provider supports the install_options attribute, which allows command-line flags to be passed to pip. These options should be specified as an array where each element is either a string or a hash.

• Supported features: install_options, installable, targetable, uninstallable, upgradeable, version_ranges, versionable.

Python packages via pip2.

This provider supports the install_options attribute, which allows command-line flags to be passed to pip2. These options should be specified as an array where each element is either a string or a hash.

• Supported features: install_options, installable, targetable, uninstallable, upgradeable, versionable.

Python packages via pip3.

This provider supports the install_options attribute, which allows command-line flags to be passed to pip3. These options should be specified as an array where each element is either a string or a hash.

• Supported features: install_options, installable, targetable, uninstallable, upgradeable, versionable.

OpenSolaris image packaging system. See pkg(5) for more information.

This provider supports the install_options attribute, which allows command-line flags to be passed to pkg. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/pkg.

• Default for kernelrelease == 5.11, 5.12 and osfamily == solaris.

• Supported features: holdable, install_options, installable, uninstallable, upgradeable, versionable.

Package management based on Apple's Installer.app and DiskUtility.app.

This provider 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, and Puppet will install all of them. Subdirectories are not checked for packages.

This provider can also accept plain .pkg (but not .mpkg) files in addition to .dmg files.

Notes:

• The source attribute is mandatory. It must be either a local disk path or an HTTP, HTTPS, or FTP URL to the package.

• The name of the resource must be the filename (without path) of the DMG file.

• When installing the packages from a DMG, this provider writes a file to disk at /var/db/.puppet_pkgdmg_installed_NAME. If that file is present, Puppet assumes all packages from that DMG are already installed.

• This provider is not versionable and uses DMG filenames to determine whether a package has been installed. Thus, to install new a version of a package, you must create a new DMG with a different filename.

• Required binaries: /usr/bin/curl, /usr/bin/hdiutil, /usr/sbin/installer.

• Default for operatingsystem == darwin.

• Supported features: installable.

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

• Required binaries: pkgin.

• Default for operatingsystem == smartos, netbsd.

• Supported features: installable, uninstallable, upgradeable, versionable.

A PkgNG provider for FreeBSD and DragonFly.

• Required binaries: /usr/local/sbin/pkg.

• Default for operatingsystem == freebsd, dragonfly.

• Supported features: install_options, installable, uninstallable, upgradeable, versionable.

Package management using Peter Bonivart's pkgutil command on Solaris.

• Required binaries: pkgutil.

• Supported features: installable, uninstallable, upgradeable.

Provides packaging support for Gentoo's portage system.

This provider supports the install_options and uninstall_options attributes, which allows command-line flags to be passed to emerge. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/eix-update, /usr/bin/eix, /usr/bin/emerge, /usr/bin/qatom.

• Default for osfamily == gentoo.

• Supported features: install_options, installable, purgeable, reinstallable, uninstall_options, uninstallable, upgradeable, versionable, virtual_packages.

Support for FreeBSD's ports. Note that this, too, mixes packages and ports.

• Required binaries: /usr/local/sbin/pkg_deinstall, /usr/local/sbin/portupgrade, /usr/local/sbin/portversion, /usr/sbin/pkg_info.

• Supported features: installable, purgeable, uninstallable, upgradeable.

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/pkg_deinstall, /usr/local/sbin/portinstall, /usr/local/sbin/portupgrade, /usr/local/sbin/portversion, /usr/sbin/pkg_info.

• Supported features: installable, uninstallable, upgradeable.

Puppet Ruby Gem support. This provider is useful for managing gems needed by the ruby provided in the puppet-agent package.

• Required binaries: /opt/puppetlabs/puppet/bin/gem.

• Supported features: install_options, installable, uninstall_options, uninstallable, upgradeable, versionable.

Puppet Server Ruby Gem support. If a URL is passed via source, then that URL is appended to the list of remote gem repositories which by default contains rubygems.org; To ensure that only the specified source is used also pass --clear-sources in via install_options; 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: /opt/puppetlabs/bin/puppetserver.

• Supported features: install_options, installable, uninstall_options, uninstallable, upgradeable, versionable.

RPM packaging support; should work anywhere with a working rpm binary.

This provider supports the install_options and uninstall_options attributes, which allow command-line flags to be passed to rpm. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: rpm.

• Supported features: install_only, install_options, installable, uninstall_options, uninstallable, upgradeable, versionable, virtual_packages.

Support for suse rug package manager.

• Required binaries: /usr/bin/rug, rpm.

• Supported features: installable, uninstallable, upgradeable, versionable.

Sun's packaging system. Requires that you specify the source for the packages you're managing.

This provider supports the install_options attribute, which allows command-line flags to be passed to pkgadd. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/pkginfo, /usr/sbin/pkgadd, /usr/sbin/pkgrm.

• Default for osfamily == solaris.

• Supported features: install_options, installable, uninstallable, upgradeable.

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.

Support via tdnf.

This provider supports the install_options attribute, which allows command-line flags to be passed to tdnf. These options should be spcified as a string (e.g. '--flag'), a hash (e.g. {'--flag' => 'value'}), or an array where each element is either a string or a hash.

• Required binaries: rpm, tdnf.

• Default for operatingsystem == PhotonOS.

• Supported features: install_options, installable, purgeable, uninstallable, upgradeable, versionable, virtual_packages.

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.

Support via urpmi.

• Required binaries: rpm, urpme, urpmi, urpmq.

• Default for operatingsystem == mandriva, mandrake.

• Supported features: installable, purgeable, uninstallable, upgradeable, versionable.

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 to local files, mapped drives, or UNC paths.

This provider supports the install_options and uninstall_options attributes, which allow command-line flags to be passed to the installer. These options should be specified as an array where each element is either a string or a hash.

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, versionable.

Support via yum.

Using this provider's uninstallable feature will not remove dependent packages. To remove dependent packages with this provider use the purgeable feature, but note this feature is destructive and should be used with the utmost care.

This provider supports the install_options attribute, which allows command-line flags to be passed to yum. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: rpm, yum.

• Default for operatingsystem == amazon. Default for operatingsystemmajrelease == 4, 5, 6, 7 and osfamily == redhat.

• Supported features: install_only, install_options, installable, purgeable, uninstallable, upgradeable, versionable, virtual_packages.

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

This provider supports the install_options attribute, which allows command-line flags to be passed to zypper. These options should be specified as an array where each element is either a string or a hash.

• Required binaries: /usr/bin/zypper.

• Default for operatingsystem == suse, sles, sled, opensuse.

• Supported features: install_options, installable, uninstallable, upgradeable, versionable, virtual_packages.

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

The name of the type to be managed.

(↑ Back to resources attributes)

Whether to purge unmanaged resources. When set to true, this will delete any resource that is not specified in your configuration and is not autorequired by any managed resources. Note: The ssh_authorized_key resource type can't be purged this way; instead, see the purge_ssh_keys attribute of the user type.

Valid values are true, false, yes, no.

(↑ Back to resources attributes)

This keeps system users from being purged. By default, it does not purge users whose UIDs are less than the minimum UID for the system (typically 500 or 1000), but you can specify a different UID as the inclusive limit.

Valid values are true, false. Values can match /^\d+$/.

(↑ Back to resources attributes)

This keeps specific uids or ranges of uids from being purged when purge is true. Accepts integers, integer strings, and arrays of integers or integer strings. To specify a range of uids, consider using the range() function from stdlib.

(↑ Back to resources attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

The name of the schedule. This name is used when assigning the schedule to a resource with the schedule metaparameter:

schedule { 'everyday':
  period => daily,
  range  => '2 - 4',
}

exec { '/usr/bin/apt-get update':
  schedule => 'everyday',
}

(↑ Back to schedule attributes)

The period of repetition for resources on this schedule. The default is for resources 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 (for instance, 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, the resource can applied up to every 10 minutes, but internal factors might prevent it from actually running that often (for instance, if a Puppet run is still in progress when the next run is scheduled to start, that next run will be suppressed).

See the periodmatch attribute for tuning whether to match times by their distance apart or by their specific value.

Tip: You can use period => never, to prevent a resource from being applied in the given range. This is useful if you need to create a blackout window to perform sensitive operations without interruption.

Valid values are hourly, daily, weekly, monthly, never.

(↑ Back to schedule attributes)

Whether periods should be matched by a numeric value (for instance, whether two times are in the same hour) or by their chronological distance apart (whether two times are 60 minutes apart).

Valid values are number, distance.

(↑ Back to schedule attributes)

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 can cross midnight (for example, range => "22:00 - 04:00").

(↑ Back to schedule attributes)

How often a given resource may be applied in this schedule's period. Must be an integer.

(↑ Back to schedule attributes)

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 (as a string or as an integer) corresponding to the day of the week where 0 is Sunday, 1 is Monday, and so on. Multiple days can be specified as an array. 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.

(↑ Back to schedule attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

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.")

(↑ Back to service attributes)

(Property: This attribute represents concrete state on the target system.)

Whether a service should be running. Default values depend on the platform.

Valid values are stopped (also called false), running (also called true).

(↑ Back to service attributes)

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.

(↑ Back to service attributes)

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.

(↑ Back to service attributes)

(Property: This attribute represents concrete state on the target system.)

Whether a service should be enabled to start at boot. This property behaves differently depending on the platform; wherever possible, it relies on local tools to enable or disable a given service. Default values depend on the platform.

If you don't specify a value for the enable attribute, Puppet leaves that aspect of the service alone and your operating system determines the behavior.

Valid values are true, false, manual, mask, delayed.

Requires features enableable.

(↑ Back to service attributes)

(Property: This attribute represents concrete state on the target system.)

Specify a string of flags to pass to the startup script.

Requires features flaggable.

(↑ Back to service attributes)

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.

Valid values are true, false.

(↑ Back to service attributes)

Declare whether the service's init script has a functional status command. 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.

(↑ Back to service attributes)

(Property: This attribute represents concrete state on the target system.)

Specify an account for service logon

Requires features manages_logon_credentials.

(↑ Back to service attributes)

Specify a password for service logon. Default value is an empty string (when logonaccount is specified).

Requires features manages_logon_credentials.

(↑ Back to service attributes)

Specify a command to config a service, or a path to a manifest to do so.

(↑ Back to service attributes)

The search path for finding init scripts. Multiple values should be separated by colons or provided as an array.

(↑ Back to service attributes)

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, including regular expressions (which should be quoted without enclosing slashes).

(↑ Back to service attributes)

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

• bsd

• daemontools

• debian

• freebsd

• gentoo

• init

• launchd

• openbsd

• openrc

• openwrt

• rcng

• redhat

• runit

• service

• smf

• src

• systemd

• upstart

• windows

(↑ Back to service attributes)

Specify a restart command manually. If left unspecified, the service will be stopped and then started.

(↑ Back to service attributes)

Specify a start command manually. Most service subsystems support a start command, so this will not need to be specified.

(↑ Back to service attributes)

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.

(↑ Back to service attributes)

Specify a stop command manually.

(↑ Back to service attributes)

Specify an optional minimum timeout (in seconds) for puppet to wait when syncing service properties

Requires features configurable_timeout.

(↑ Back to service attributes)

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.

Generic BSD form of init-style service management with rc.d.

Uses rc.conf.d for service enabling and disabling.

• Supported features: enableable, refreshable.

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 overridden 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/svc, /usr/bin/svstat.

• Supported features: enableable, refreshable.

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/invoke-rc.d, /usr/sbin/service, /usr/sbin/update-rc.d.

• Default for operatingsystem == cumuluslinux and operatingsystemmajrelease == 1, 2. Default for operatingsystem == debian and operatingsystemmajrelease == 5, 6, 7. Default for operatingsystem == devuan.

• Supported features: enableable, refreshable.

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

• Default for operatingsystem == freebsd, dragonfly.

• Supported features: enableable, refreshable.

Gentoo's form of init-style service management.

Uses rc-update for service enabling and disabling.

• Required binaries: /sbin/rc-update.

• Supported features: enableable, refreshable.

Standard init-style service management.

• Supported features: refreshable.

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 more information, see the launchd man page:

• https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man8/launchd.8.html

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'

• Required binaries: /bin/launchctl.

• Default for operatingsystem == darwin.

• Supported features: enableable, refreshable.

Provider for OpenBSD's rc.d daemon control scripts

• Required binaries: /usr/sbin/rcctl.

• Default for operatingsystem == openbsd.

• Supported features: enableable, flaggable, refreshable.

Support for Gentoo's OpenRC initskripts

Uses rc-update, rc-status and rc-service to manage services.

• Required binaries: /bin/rc-status, /sbin/rc-service, /sbin/rc-update.

• Default for operatingsystem == gentoo. Default for operatingsystem == funtoo.

• Supported features: enableable, refreshable.

Support for OpenWrt flavored init scripts.

Uses /etc/init.d/service_name enable, disable, and enabled.

• Default for operatingsystem == openwrt.

• Supported features: enableable, refreshable.

RCng service management with rc.d

• Default for operatingsystem == netbsd, cargos.

• Supported features: enableable, refreshable.

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

• Required binaries: /sbin/chkconfig, /sbin/service.

• Default for osfamily == redhat. Default for operatingsystemmajrelease == 10, 11 and osfamily == suse.

• Supported features: enableable, refreshable.

Runit service management.

This provider manages daemons running supervised by Runit. When detecting the service directory it will check, in order of preference:

• /service

• /etc/service

• /var/service

The daemon directory should be in one of the following locations:

• /etc/sv

• /var/lib/service

or this can be overridden 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.

The simplest form of service support.

• Supported features: refreshable.

Support for Sun's new Service Management Framework.

When managing the enable property, this provider will try to preserve the previous ensure state per the enableable semantics. On Solaris, enabling a service starts it up while disabling a service stops it. Thus, there's a chance for this provider to execute two operations when managing the enable property. For example, if enable is set to true and the ensure state is stopped, this provider will manage the service using two operations: one to enable the service which will start it up, and another to stop the service (without affecting its enabled status).

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/svcadm, /usr/sbin/svccfg.

• Default for osfamily == solaris.

• Supported features: enableable, refreshable.

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/lssrc, /usr/bin/refresh, /usr/bin/startsrc, /usr/bin/stopsrc, /usr/sbin/chitab, /usr/sbin/lsitab, /usr/sbin/mkitab, /usr/sbin/rmitab.

• Default for operatingsystem == aix.

• Supported features: enableable, refreshable.

Manages systemd services using systemctl.

Because systemd defaults to assuming the .service unit type, the suffix may be omitted. Other unit types (such as .path) may be managed by providing the proper suffix.

• Required binaries: systemctl.

• Default for osfamily == archlinux. Default for operatingsystemmajrelease == 7, 8, 9 and osfamily == redhat. Default for operatingsystem == fedora and osfamily == redhat. Default for osfamily == suse. Default for osfamily == coreos. Default for operatingsystem == amazon and operatingsystemmajrelease == 2. Default for operatingsystem == debian. Default for operatingsystem == LinuxMint. Default for operatingsystem == ubuntu. Default for operatingsystem == cumuluslinux and operatingsystemmajrelease == 3, 4.

• Supported features: enableable, maskable, refreshable.

Ubuntu service management with upstart.

This provider manages upstart jobs on Ubuntu. For upstart documentation, see http://upstart.ubuntu.com/.

• Required binaries: /sbin/initctl, /sbin/restart, /sbin/start, /sbin/status, /sbin/stop.

• Default for operatingsystem == ubuntu and operatingsystemmajrelease == 10.04, 12.04, 14.04, 14.10. Default for operatingsystem == LinuxMint and operatingsystemmajrelease == 10, 11, 12, 13, 14, 15, 16, 17.

• Supported features: enableable, refreshable.

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.

• Default for operatingsystem == windows.

• Supported features: configurable_timeout, delayed_startable, enableable, manages_logon_credentials, manual_startable, refreshable.

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

The name of the stage. Use this as the value for the stage metaparameter when assigning classes to this stage.

(↑ Back to stage attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

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

(↑ Back to tidy attributes)

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 (for example, '1w' represents one week).

Specifying 0 will remove all files.

(↑ Back to tidy attributes)

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.

(↑ Back to tidy attributes)

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). Requiring explicit recursion clears up a common source of confusion.

(↑ Back to tidy attributes)

In case the resource is a directory and the recursion is enabled, puppet will generate a new resource for each file file found, possible leading to an excessive number of resources generated without any control.

Setting max_files will check the number of file resources that will eventually be created and will raise a resource argument error if the limit will be exceeded.

Use value 0 to disable the check. In this case, a warning is logged if the number of files exceeds 1000.

Values can match /^[0-9]+$/.

(↑ Back to tidy attributes)

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]+$/.

(↑ Back to tidy attributes)

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, yes, no.

(↑ Back to tidy attributes)

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.

(↑ Back to tidy attributes)

Set the mechanism for determining age.

Valid values are atime, mtime, ctime.

(↑ Back to tidy attributes)

(Namevar: If omitted, this attribute's value defaults to the resource's title.)

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.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The basic state that the object should be in.

Valid values are present, absent, role.

(↑ Back to user attributes)

Whether to allow duplicate UIDs.

Valid values are true, false, yes, no.

(↑ Back to user attributes)

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.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

Specify AIX attributes for the user in an array or hash of attribute = value pairs.

For example:

['minage=0', 'maxage=5', 'SYSTEM=compat']

or

attributes => { 'minage' => '0', 'maxage' => '5', 'SYSTEM' => 'compat' }

Requires features manages_aix_lam.

(↑ Back to user attributes)

Whether specified auths should be considered the complete list (inclusive) or the minimum list (minimum) of auths the user has. This setting is specific to managing Solaris authorizations.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The auths the user has. Multiple auths should be specified as an array.

Requires features manages_solaris_rbac.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

A description of the user. Generally the user's full name.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The expiry date for this user. Provide as either the special value absent to ensure that the account never expires, or as a zero-padded YYYY-MM-DD format -- for example, 2010-02-19.

Valid values are absent. Values can match /^\d{4}-\d{2}-\d{2}$/.

Requires features manages_expiry.

(↑ Back to user attributes)

Forces the management of local accounts when accounts are also being managed by some other Name Service Switch (NSS). For AIX, refer to the ia_load_module parameter.

This option relies on your operating system's implementation of luser* commands, such as luseradd , and lgroupadd, lusermod. The forcelocal option could behave unpredictably in some circumstances. If the tools it depends on are not available, it might have no effect at all.

Valid values are true, false, yes, no.

Requires features manages_local_users_and_groups.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The user's primary group. Can be specified numerically or by name.

This attribute is not supported on Windows systems; use the groups attribute instead. (On Windows, designating a primary group is only meaningful for domain accounts, which Puppet does not currently manage.)

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

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.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The home directory of the user. The directory must be created separately and is not currently checked for existence.

(↑ Back to user attributes)

The name of the I&A module to use to manage this user. This should be set to files if managing local users.

Requires features manages_aix_lam.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

This is the number of iterations of a chained computation of the PBKDF2 password hash. This parameter is used in OS X, and is required for managing passwords on OS X 10.8 and newer.

Requires features manages_password_salt.

(↑ Back to user attributes)

Whether specified key/value pairs should be considered the complete list (inclusive) or the minimum list (minimum) of the user's attributes.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

Specify user attributes in an array of key = value pairs.

Requires features manages_solaris_rbac.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The name of login class to which the user belongs.

Requires features manages_loginclass.

(↑ Back to user attributes)

Whether to manage the home directory when Puppet creates or removes the user. This creates the home directory if Puppet also creates the user account, and deletes the home directory if Puppet also removes the user account.

This parameter has no effect unless Puppet is also creating or removing the user in the resource at the same time. For instance, Puppet creates a home directory for a managed user if ensure => present and the user does not exist at the time of the Puppet run. If the home directory is then deleted manually, Puppet will not recreate it on the next run.

Note that on Windows, this manages creation/deletion of the user profile instead of the home directory. The user profile is stored in the C:Users<username> directory.

Valid values are true, false, yes, no.

(↑ Back to user attributes)

If minimum is specified, Puppet will ensure that the user is a member of all specified groups, but will not remove any other groups that the user is a part of.

If inclusive is specified, Puppet will ensure that the user is a member of only specified groups.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The user's password, in whatever encrypted format the local system requires. Consult your operating system's documentation for acceptable password encryption formats and requirements.

• Mac OS X 10.5 and 10.6, and some older Linux distributions, use salted SHA1 hashes. You can use Puppet's built-in sha1 function to generate a salted SHA1 hash from a password.

• Mac OS X 10.7 (Lion), and many recent Linux distributions, use salted SHA512 hashes. The Puppet Labs stdlib module contains a str2saltedsha512 function which can generate password hashes for these operating systems.

• OS X 10.8 and higher use salted SHA512 PBKDF2 hashes. When managing passwords on these systems, the salt and iterations attributes need to be specified as well as the password.

• Windows passwords can be managed only in cleartext, because there is no Windows API for setting the password hash.

Enclose any value that includes a dollar sign ($) in single quotes (') to avoid accidental variable interpolation.

To redact passwords from reports to PuppetDB, use the Sensitive data type. For example, this resource protects the password:

user { 'foo':
  ensure   => present,
  password => Sensitive("my secret password")
}

This results in the password being redacted from the report, as in the previous_value, desired_value, and message fields below.

    events:
    - !ruby/object:Puppet::Transaction::Event
      audited: false
      property: password
      previous_value: "[redacted]"
      desired_value: "[redacted]"
      historical_value:
      message: changed [redacted] to [redacted]
      name: :password_changed
      status: success
      time: 2017-05-17 16:06:02.934398293 -07:00
      redacted: true
      corrective_change: false
    corrective_change: false

Requires features manages_passwords.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The maximum number of days a password may be used before it must be changed.

Requires features manages_password_age.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The minimum number of days a password must be used before it may be changed.

Requires features manages_password_age.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The number of days before a password is going to expire (see the maximum password age) during which the user should be warned.

Requires features manages_password_age.

(↑ Back to user attributes)

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.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The profiles the user has. Multiple profiles should be specified as an array.

Requires features manages_solaris_rbac.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The name of the project associated with a user.

Requires features manages_solaris_rbac.

(↑ Back to user attributes)

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

• directoryservice

• hpuxuseradd

• ldap

• openbsd

• pw

• user_role_add

• useradd

• windows_adsi

(↑ Back to user attributes)

Whether to purge authorized SSH keys for this user if they are not managed with the ssh_authorized_key resource type. This parameter is a noop if the ssh_authorized_key type is not available.

Allowed values are:

• false (default) --- don't purge SSH keys for this user.

• true --- look for keys in the .ssh/authorized_keys file in the user's home directory. Purge any keys that aren't managed as ssh_authorized_key resources.

• An array of file paths --- look for keys in all of the files listed. Purge any keys that aren't managed as ssh_authorized_key resources. If any of these paths starts with ~ or %h, that token will be replaced with the user's home directory.

Valid values are true, false.

(↑ Back to user attributes)

Whether specified roles should be considered the complete list (inclusive) or the minimum list (minimum) of roles the user has.

Valid values are inclusive, minimum.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The roles the user has. Multiple roles should be specified as an array.

Requires features manages_roles.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

This is the 32-byte salt used to generate the PBKDF2 password used in OS X. This field is required for managing passwords on OS X >= 10.8.

Requires features manages_password_salt.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

The user's login shell. The shell must exist and be executable.

This attribute cannot be managed on Windows systems.

Requires features manages_shell.

(↑ Back to user attributes)

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. This parameter is only used when the resource is created and will not affect the UID when the user is present.

Valid values are true, false, yes, no.

(↑ Back to user attributes)

(Property: This attribute represents concrete state on the target system.)

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).

(↑ Back to user attributes)

User management for AIX.

• Required binaries: /bin/chpasswd, /usr/bin/chuser, /usr/bin/mkuser, /usr/sbin/lsuser, /usr/sbin/rmuser.

• Default for operatingsystem == aix.

• Supported features: manages_aix_lam, manages_expiry, manages_homedir, manages_local_users_and_groups, manages_password_age, manages_passwords, manages_shell.

User management on OS X.

• Required binaries: /usr/bin/dscacheutil, /usr/bin/dscl, /usr/bin/dsimport, /usr/bin/uuidgen.

• Default for operatingsystem == darwin.

• Supported features: manages_password_salt, manages_passwords, manages_shell.

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. New functionality provides for changing trusted computing passwords and resetting password expirations under trusted computing.

• Required binaries: /usr/sam/lbin/useradd.sam, /usr/sam/lbin/userdel.sam, /usr/sam/lbin/usermod.sam.

• Default for operatingsystem == hp-ux.

• Supported features: allows_duplicates, manages_homedir, manages_passwords.

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, manages_shell.

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

• Required binaries: passwd, useradd, userdel, usermod.

• Default for operatingsystem == openbsd.

• Supported features: manages_expiry, manages_homedir, manages_shell, system_users.

User management via pw on FreeBSD and DragonFly BSD.

• Required binaries: pw.

• Default for operatingsystem == freebsd, dragonfly.

• Supported features: allows_duplicates, manages_expiry, manages_homedir, manages_passwords, manages_shell.

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

• Required binaries: passwd, roleadd, roledel, rolemod, useradd, userdel, usermod.

• Default for osfamily == solaris.

• Supported features: allows_duplicates, manages_homedir, manages_password_age, manages_passwords, manages_roles, manages_shell, manages_solaris_rbac.

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.

To use the forcelocal parameter, you need to install the libuser package (providing /usr/sbin/lgroupadd and /usr/sbin/luseradd).

• Required binaries: chage, chpasswd, lchage, luseradd, luserdel, lusermod, useradd, userdel, usermod.

• Supported features: allows_duplicates, manages_expiry, manages_homedir, manages_shell, system_users.

Local user management for Windows.

• Default for operatingsystem == windows.

• Supported features: manages_homedir, manages_passwords, manages_roles.