Built-in types

This page provides a reference guide for Puppet's built-in types: package, file, service, notify, exec, user, and group.

For detailed information about built-in types, see the Resource type reference.

For information on all core types, including supported types in the puppet-agent package, see the Resource types index.

The trifecta: package, file, and service

Package, file, service: Learn it, live it, love it. Even if this is the only Puppet you know, you can get a lot done.

package { 'openssh-server':
  ensure => installed,
}

file { '/etc/ssh/sshd_config':
  source  => 'puppet:///modules/sshd/sshd_config',
  owner   => 'root',
  group   => 'root',
  mode    => '0640',
  notify  => Service['sshd'], # sshd restarts whenever you edit this file.
  require => Package['openssh-server'],
}

service { 'sshd':
  ensure     => running,
  enable     => true,
}

package

Manages software packages.
Attribute Description Notes
name The name of the package, as known to your packaging system. Defaults to title.
ensure Whether the package should be installed, and what version to use. Allowed values:

  • present

  • latest (implies present)

  • Any version string (implies present)

  • absent

  • purged
    CAUTION: purged ensures absent, and deletes configuration files and dependencies, including those that other packages depend on. Provider-dependent.
source Where to obtain the package, if your system’s packaging tools don’t use a repository.
provider Which packaging system to use (such as Yum or Rubygems), if a system has more than one available.

file

Manages files, directories, and symlinks.
Attribute Description Notes
ensure Whether the file should exist, and what it should be. Allowed values:

  • file

  • directory

  • link (symlink)

  • present (anything)

  • absent

path The full path to the file on disk. Defaults to title.
owner By name or UID.
group By name or GID.
mode Must be specified exactly. Does the right thing for directories.
For normal files:
source Where to download contents for the file. Usually a puppet:/// URL.
content The file’s desired contents, as a string. Most useful when paired with templates, but you can also use the output of the file function.
For directories:
source Where to download contents for the directory, when recurse => true.
recurse Whether to recursively manage files in the directory.
purge Whether unmanaged files in the directory should be deleted, when recurse => true.
For symlinks:
target The symlink target. (Required when ensure => link.)
Other notable attributes:

  • backup

  • checksum

  • force

  • ignore

  • links

  • recurselimit

  • replace

service

Manages services running on the node. As with packages, some platforms have better tools than others, so read the relevant documentation before you begin.

You can make services restart whenever a file changes with the subscribe or notify metaparameters. For more info, see Relationships and ordering.
Attribute Description Notes
name The name of the service to run. Defaults to title.
ensure The desired status of the service. Allowed values:

  • running (or true)

  • stopped (or false)

enable Whether the service should start on boot. Doesn’t work on all systems.
hasrestart Whether to use the init script’s restart command instead of stop+start. Defaults to false.
hasstatus Whether to use the init script’s status command. Defaults to true.
Other notable attributes:

If a service has a bad init script, you can work around it and manage almost anything using the status, start, stop, restart, pattern, and binary attributes.

Other built-in types

Beyond package, file, and service, these core types are among the most useful and commonly used.

notify

Logs an arbitrary message, at the notice log level. This appears in the POSIX syslog or Windows Event Log on the agent node and is also logged in reports.
notify { "This message is getting logged on the agent node.": }
Attribute Description Notes
message The message to log. Defaults to title.

exec

Executes an arbitrary command on the agent node. When using execs, you must either make sure the command can be safely run multiple times, or specify that it runs only under certain conditions.

Important attributes Description Notes
command The command to run. If this isn’t a fully-qualified path, use the path attribute. Defaults to title.
path Where to look for executables, as a colon-separated list or an array.
returns Which exit codes indicate success. Defaults to 0.
environment An array of environment variables to set (for example, ['MYVAR=somevalue', 'OTHERVAR=othervalue']).
The following attributes limit when a command runs.
creates A file to look for before running the command. The command only runs if the file doesn’t exist.
refreshonly If true, the command runs only if a resource it subscribes to (or a resource which notifies it) has changed.
onlyif A command or array of commands; if any have a non-zero return value, the command won’t run.
unless The opposite of onlyif.
Other notable attributes: cwd, group, logoutput, timeout, tries, try_sleep, user

user

Manages user accounts; mostly used for system users.
user { "jane":
    ensure     => present,
    uid        => '507',
    gid        => 'admin',
    shell      => '/bin/zsh',
    home       => '/home/jane',
    managehome => true,
}
Important Attributes Description Notes
name The name of the user. Defaults to title.
ensure Whether the user should exist. Allowed values:

  • present

  • absent

  • role

uid The user ID. Must be specified numerically; chosen automatically if omitted. Read-only on Windows.
gid The user’s primary group. Can be specified numerically or by name. Not used on Windows; use groups instead.
groups An array of other groups to which the user belongs. Don’t include the group specified as the gid.
home The user’s home directory.
managehome Whether to manage the home directory when managing the user. If you don’t set this to true, you’ll need to create the user’s home directory manually.
shell The user’s login shell.
Other notable attributes: comment, expiry, membership, password, password_max_age, password_min_age, purge_ssh_keys, salt

group

Manages groups.

Important attributes Description Notes
name The name of the group. Defaults to title.
ensure Whether the group should exist. Allowed values:

  • present

  • absent

gid The group ID; must be specified numerically, and is chosen automatically if omitted. Read-only on Windows.
members Users and groups that are members of the group. Only applicable to certain operating systems; see the full type reference for details.