Type Reference

This page is autogenerated; any changes will get overwritten (last generated on Wed Dec 17 01:21:05 +0100 2008)

Contents

• Metaparameters
  • Available Metaparameters
• Resource Types
  • augeas
  • computer
  • cron
  • exec
  • file
  • filebucket
  • group
  • host
  • k5login
  • macauthorization
  • mailalias
  • maillist
  • mcx
  • mount
  • nagios_command
  • nagios_contact
  • nagios_contactgroup
  • nagios_host
  • nagios_hostdependency
  • nagios_hostescalation
  • nagios_hostextinfo
  • nagios_hostgroup
  • nagios_service
  • nagios_servicedependency
  • nagios_serviceescalation
  • nagios_serviceextinfo
  • nagios_servicegroup
  • nagios_timeperiod
  • notify
  • package
  • resources
  • schedule
  • selboolean
  • selmodule
  • service
  • ssh_authorized_key
  • sshkey
  • tidy
  • user
  • yumrepo
  • zfs
  • zone
  • zpool

Metaparameters

Metaparameters are parameters that work with any resource type; they are part of the Puppet framework itself rather than being part of the implementation of any given instance. Thus, any defined metaparameter can be used with any instance in your manifest, including defined components.

Available Metaparameters

alias

Creates an alias for the object. Puppet uses this internally when you provide a symbolic name:

file { sshdconfig:
    path => $operatingsystem ? {
        solaris => "/usr/local/etc/ssh/sshd_config",
        default => "/etc/ssh/sshd_config"
    },
    source => "..."
}

service { sshd:
    subscribe => file[sshdconfig]
}

When you use this feature, the parser sets sshdconfig as the name, and the library sets that as an alias for the file so the dependency lookup for sshd works. You can use this parameter yourself, but note that only the library can use these aliases; for instance, the following code will not work:

file { "/etc/ssh/sshd_config":
    owner => root,
    group => root,
    alias => sshdconfig
}

file { sshdconfig:
    mode => 644
}

There's no way here for the Puppet parser to know that these two stanzas should be affecting the same file.

See the language tutorial for more information.

before

This parameter is the opposite of require -- it guarantees that the specified object is applied later than the specifying object:

file { "/var/nagios/configuration":
    source  => "...",
    recurse => true,
    before => Exec["nagios-rebuid"]
}

exec { "nagios-rebuild":
    command => "/usr/bin/make",
    cwd => "/var/nagios/configuration"
}

This will make sure all of the files are up to date before the make command is run.

check

Propertys which should have their values retrieved but which should not actually be modified. This is currently used internally, but will eventually be used for querying, so that you could specify that you wanted to check the install state of all packages, and then query the Puppet client daemon to get reports on all packages.

loglevel

Sets the level that information will be logged. The log levels have the biggest impact when logs are sent to syslog (which is currently the default). Valid values are debug, info, notice, warning, err, alert, emerg, crit, verbose.

noop

Boolean flag indicating whether work should actually be done. Valid values are true, false.

notify

This parameter is the opposite of subscribe -- it sends events to the specified object:

file { "/etc/sshd_config":
    source => "....",
    notify => Service[sshd]
}

service { sshd:
    ensure => running
}

This will restart the sshd service if the sshd config file changes.

require

One or more objects that this object depends on. This is used purely for guaranteeing that changes to required objects happen before the dependent object. For instance:

# Create the destination directory before you copy things down
file { "/usr/local/scripts":
    ensure => directory
}

file { "/usr/local/scripts/myscript":
    source => "puppet://server/module/myscript",
    mode => 755,
    require => File["/usr/local/scripts"]
}

Multiple dependencies can be specified by providing a comma-seperated list of resources, enclosed in square brackets:

require => [ File["/usr/local"], File["/usr/local/scripts"] ]

Note that Puppet will autorequire everything that it can, and there are hooks in place so that it's easy for resources to add new ways to autorequire objects, so if you think Puppet could be smarter here, let us know.

In fact, the above code was redundant -- Puppet will autorequire any parent directories that are being managed; it will automatically realize that the parent directory should be created before the script is pulled down.

Currently, exec resources will autorequire their CWD (if it is specified) plus any fully qualified paths that appear in the command. For instance, if you had an exec command that ran the myscript mentioned above, the above code that pulls the file down would be automatically listed as a requirement to the exec code, so that you would always be running againts the most recent version.

schedule

On what schedule the object should be managed. You must create a schedule object, and then reference the name of that object to use that for your schedule:

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

exec { "/usr/bin/apt-get update":
    schedule => daily
}

The creation of the schedule object does not need to appear in the configuration before objects that use it.

subscribe

One or more objects that this object depends on. Changes in the subscribed to objects result in the dependent objects being refreshed (e.g., a service will get restarted). For instance:

class nagios {
    file { "/etc/nagios/nagios.conf":
        source => "puppet://server/module/nagios.conf",
        alias => nagconf # just to make things easier for me
    }
    service { nagios:
        running => true,
        subscribe => File[nagconf]
    }
}

Currently the exec, mount and service type support refreshing.

tag

Add the specified tags to the associated resource. While all resources are automatically tagged with as much information as possible (e.g., each class and definition containing the resource), it can be useful to add your own tags to a given resource.

Tags are currently useful for things like applying a subset of a host's configuration:

puppetd --test --tags mytag

This way, when you're testing a configuration you can run just the portion you're testing.

Resource Types

• The namevar is the parameter used to uniquely identify a type instance. This is the parameter that gets assigned when a string is provided before the colon in a type declaration. In general, only developers will need to worry about which parameter is the namevar.

  In the following code:

  file { "/etc/passwd":
      owner => root,
      group => root,
      mode => 644
  }
  

  /etc/passwd is considered the title of the file object (used for things like dependency handling), and because path is the namevar for file, that string is assigned to the path parameter.

• Parameters determine the specific configuration of the instance. They either directly modify the system (internally, these are called properties) or they affect how the instance behaves (e.g., adding a search path for exec instances or determining recursion on file instances).

• Providers provide low-level functionality for a given resource type. This is usually in the form of calling out to external commands.

  When required binaries are specified for providers, fully qualifed paths indicate that the binary must exist at that specific path and unqualified binaries indicate that Puppet will search for the binary using the shell path.

• Features are abilities that some providers might not support. You can use the list of supported features to determine how a given provider can be used.

  Resource types define features they can use, and providers can be tested to see which features they provide.

---

augeas

Apply the changes (single or array of changes) to the filesystem via the augeas tool.

Requires:

• augeas to be installed (http://www.augeas.net)
• ruby-augeas bindings

Sample usage with a string:

augeas{"test1" :
       context => "/files/etc/sysconfig/firstboot",
       changes => "set RUN_FIRSTBOOT YES",
       onlyif  => "match other_value size > 0",
 }

Sample usage with an array and custom lenses:

augeas{"jboss_conf":
    context => "/files",
    changes => [
        "set /etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
        "set /etc/jbossas/jbossas.conf/JAVA_HOME /usr"
    ],
    load_path => "$/usr/share/jbossas/lenses",
}

Features

• execute_changes: Actually make the changes
• need_to_run?: If the command should run
• parse_commands: Parse the command string

Provider	execute_changes	need_to_run?	parse_commands
augeas	X	X	X

Parameters

changes

The changes which should be applied to the filesystem. This can be either a string which contains a command or an array of commands. Commands supported are:

set [PATH] [VALUE]     Sets the value VALUE at loction PATH
rm [PATH]              Removes the node at location PATH
remove [PATH]          Synonym for rm
clear [PATH]           Keeps the node at PATH, but removes the value.
ins [PATH]             Inserts an empty node at PATH.
insert [PATH]          Synonym for ins

If the parameter 'context' is set that that value is prepended to PATH

context

Optional context path. This value is pre-pended to the paths of all changes

load_path

Optional colon separated list of directories; these directories are searched for schema definitions

name

• namevar

The name of this task. Used for uniqueness

onlyif

Optional augeas command and comparisons to control the execution of this type. Supported onlyif syntax:

get [AUGEAS_PATH] [COMPARATOR] [STRING]
match [MATCH_PATH] size [COMPARATOR] [INT]
match [MATCH_PATH] include [STRING]
match [MATCH_PATH] == [AN_ARRAY]

where:

AUGEAS_PATH is a valid path scoped by the context
MATCH_PATH is a valid match synatx scoped by the context
COMPARATOR is in the set [> >= != == <= <]
STRING is a string
INT is a number
AN_ARRAY is in the form ['a string', 'another']

provider

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

• augeas: Supported features: execute_changes, need_to_run?, parse_commands.

returns

The expected return code from the augeas command. Should not be set

root

A file system path; all files loaded by Augeas are loaded underneath ROOT

type_check

Set to true if augeas should perform typechecking. Optional, defaults to false Valid values are true, false.

---

computer

Computer object management using DirectoryService on OS X.

Note that these are distinctly different kinds of objects to 'hosts', as they require a MAC address and can have all sorts of policy attached to them.

This provider only manages Computer objects in the local directory service domain, not in remote directories.

If you wish to manage /etc/hosts on Mac OS X, then simply use the host type as per other platforms.

This type primarily exists to create localhost Computer objects that MCX policy can then be attached to.

Parameters

en_address

The MAC address of the primary network interface. Must match en0.

ensure

Control the existences of this computer record. Set this attribute to present to ensure the computer record exists. Set it to absent to delete any computer records with this name Valid values are absent, present.

ip_address

The IP Address of the Computer object.

name

• namevar

The authoritative 'short' name of the computer record.

provider

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

• directoryservice: Computer object management using DirectoryService on OS X.

  Note that these are distinctly different kinds of objects to 'hosts', as they require a MAC address and can have all sorts of policy attached to them.

  This provider only manages Computer objects in the local directory service domain, not in remote directories.

  If you wish to manage /etc/hosts on Mac OS X, then simply use the host type as per other platforms.

  Default for operatingsystem == darwin.

realname

The 'long' name of the computer record.

---

cron

Installs and manages cron jobs. All fields except the command and the user are optional, although specifying no periodic fields would result in the command being executed every minute. While the name of the cron job is not part of the actual job, it is used by Puppet to store and retrieve it.

If you specify a cron job that matches an existing job in every way except name, then the jobs will be considered equivalent and the new name will be permanently associated with that job. Once this association is made and synced to disk, you can then manage the job normally (e.g., change the schedule of the job).

Example:

cron { logrotate:
    command => "/usr/sbin/logrotate",
    user => root,
    hour => 2,
    minute => 0
}

Note that all cron values can be specified as an array of values:

cron { logrotate:
    command => "/usr/sbin/logrotate",
    user => root,
    hour => [2, 4]
}

Or using ranges, or the step syntax */2 (although there's no guarantee that your cron daemon supports it):

cron { logrotate:
    command => "/usr/sbin/logrotate",
    user => root,
    hour => ['2-4'],
    minute => '*/10'
}

Parameters

command

The command to execute in the cron job. The environment provided to the command varies by local system rules, and it is best to always provide a fully qualified command. The user's profile is not sourced when the command is run, so if the user's environment is desired it should be sourced manually.

All cron parameters support absent as a value; this will remove any existing values for that field.

ensure

The basic property that the resource should be in. Valid values are absent, present.

environment

Any environment settings associated with this cron job. They will be stored between the header and the job in the crontab. There can be no guarantees that other, earlier settings will not also affect a given cron job.

Also, Puppet cannot automatically determine whether an existing, unmanaged environment setting is associated with a given cron job. If you already have cron jobs with environment settings, then Puppet will keep those settings in the same place in the file, but will not associate them with a specific job.

Settings should be specified exactly as they should appear in the crontab, e.g., PATH=/bin:/usr/bin:/usr/sbin.

hour

The hour at which to run the cron job. Optional; if specified, must be between 0 and 23, inclusive.

minute

The minute at which to run the cron job. Optional; if specified, must be between 0 and 59, inclusive.

month

The month of the year. Optional; if specified must be between 1 and 12 or the month name (e.g., December).

monthday

The day of the month on which to run the command. Optional; if specified, must be between 1 and 31.

name

• namevar

The symbolic name of the cron job. This name is used for human reference only and is generated automatically for cron jobs found on the system. This generally won't matter, as Puppet will do its best to match existing cron jobs against specified jobs (and Puppet adds a comment to cron jobs it adds), but it is at least possible that converting from unmanaged jobs to managed jobs might require manual intervention.

provider

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

• crontab: Required binaries: crontab.

special

Special schedules only supported on FreeBSD.

target

Where the cron job should be stored. For crontab-style entries this is the same as the user and defaults that way. Other providers default accordingly.

user

The user to run the command as. This user must be allowed to run cron jobs, which is not currently checked by Puppet.

The user defaults to whomever Puppet is running as.

weekday

The weekday on which to run the command. Optional; if specified, must be between 0 and 6, inclusive, with 0 being Sunday, or must be the name of the day (e.g., Tuesday).

---

exec

Executes external commands. It is critical that all commands executed using this mechanism can be run multiple times without harm, i.e., they are idempotent. One useful way to create idempotent commands is to use the checks like creates to avoid running the command unless some condition is met.

Note also that you can restrict an exec to only run when it receives events by using the refreshonly parameter; this is a useful way to have your configuration respond to events with arbitrary commands.

It is worth noting that exec is special, in that it is not currently considered an error to have multiple exec instances with the same name. This was done purely because it had to be this way in order to get certain functionality, but it complicates things. In particular, you will not be able to use exec instances that share their commands with other instances as a dependency, since Puppet has no way of knowing which instance you mean.

For example:

# defined in the production class
exec { "make":
    cwd => "/prod/build/dir",
    path => "/usr/bin:/usr/sbin:/bin"
}

. etc. .

# defined in the test class
exec { "make":
    cwd => "/test/build/dir",
    path => "/usr/bin:/usr/sbin:/bin"
}

Any other type would throw an error, complaining that you had the same instance being managed in multiple places, but these are obviously different images, so exec had to be treated specially.

It is recommended to avoid duplicate names whenever possible.

Note that if an exec receives an event from another resource, it will get executed again (or execute the command specified in refresh, if there is one).

There is a strong tendency to use exec to do whatever work Puppet can't already do; while this is obviously acceptable (and unavoidable) in the short term, it is highly recommended to migrate work from exec to native Puppet types as quickly as possible. If you find that you are doing a lot of work with exec, please at least notify us at Reductive Labs what you are doing, and hopefully we can work with you to get a native resource type for the work you are doing.

Parameters

command

• namevar

The actual command to execute. Must either be fully qualified or a search path for the command must be provided. If the command succeeds, any output produced will be logged at the instance's normal log level (usually notice), but if the command fails (meaning its return code does not match the specified code) then any output is logged at the err log level.

creates

A file that this command creates. If this parameter is provided, then the command will only be run if the specified file does not exist:

exec { "tar xf /my/tar/file.tar":
    cwd => "/var/tmp",
    creates => "/var/tmp/myfile",
    path => ["/usr/bin", "/usr/sbin"]
}

cwd

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

env

This parameter is deprecated. Use 'environment' instead.

environment

Any additional environment variables you want to set for a command. Note that if you use this to set PATH, it will override the path attribute. Multiple environment variables should be specified as an array.

group

The group to run the command as. This seems to work quite haphazardly on different platforms -- it is a platform issue not a Ruby or Puppet one, since the same variety exists when running commnands as different users in the shell.

logoutput

Whether to log output. Defaults to logging output at the loglevel for the exec resource. Use on_failure to only log the output when the command reports an error. Values are true, false, on_failure, and any legal log level. Valid values are true, false, on_failure.

onlyif

If this parameter is set, then this exec will only run if the command returns 0. For example:

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

This would run logrotate only if that test returned true.

Note that this command follows the same rules as the main command, which is to say that it must be fully qualified if the path is not set.

Also note that onlyif can take an array as its value, eg:

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

This will only run the exec if /all/ conditions in the array return true.

path

The search path used for command execution. Commands must be fully qualified if no path is specified. Paths can be specified as an array or as a colon-separated list.

refresh

How to refresh this command. By default, the exec is just called again when it receives an event from another resource, but this parameter allows you to define a different command for refreshing.

refreshonly

The command should only be run as a refresh mechanism for when a dependent object is changed. It only makes sense to use this option when this command depends on some other object; it is useful for triggering an action:

# Pull down the main aliases file
file { "/etc/aliases":
    source => "puppet://server/module/aliases"
}

# Rebuild the database, but only when the file changes
exec { newaliases:
    path => ["/usr/bin", "/usr/sbin"],
    subscribe => File["/etc/aliases"],
    refreshonly => true
}

Note that only subscribe and notify can trigger actions, not require, so it only makes sense to use refreshonly with subscribe or notify. Valid values are true, false.

returns

The expected return code. An error will be returned if the executed command returns something else. Defaults to 0.

timeout

The maximum time the command should take. If the command takes longer than the timeout, the command is considered to have failed and will be stopped. Use any negative number to disable the timeout. The time is specified in seconds.

unless

If this parameter is set, then this exec will run unless the command returns 0. For example:

exec { "/bin/echo root >> /usr/lib/cron/cron.allow":
    path => "/usr/bin:/usr/sbin:/bin",
    unless => "grep root /usr/lib/cron/cron.allow 2>/dev/null"
}

This would add root to the cron.allow file (on Solaris) unless grep determines it's already there.

Note that this command follows the same rules as the main command, which is to say that it must be fully qualified if the path is not set.

user

The user to run the command as. Note that if you use this then any error output is not currently captured. This is because of a bug within Ruby. If you are using Puppet to create this user, the exec will automatically require the user, as long as it is specified by name.

---

file

Manages local files, including setting ownership and permissions, creation of both files and directories, and retrieving entire files from remote servers. As Puppet matures, it expected that the file resource will be used less and less to manage content, and instead native resources will be used to do so.

If you find that you are often copying files in from a central location, rather than using native resources, please contact Reductive Labs and we can hopefully work with you to develop a native resource to support what you are doing.

Parameters

backup

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

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

filebucket { main:
    server => puppet
}

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

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

This will back the file up to the central server.

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

checksum

How to check whether a file has changed. This state is used internally for file copying, but it can also be used to monitor files somewhat like Tripwire without managing the file contents in any way. You can specify that a file's checksum should be monitored and then subscribe to the file from another object and receive events to signify checksum changes, for instance. Valid values are mtime, nosum, md5, md5lite, time, timestamp. Values can also match /^\{md5|md5lite|timestamp|mtime|time\}/.

content

Specify the contents of a file as a string. Newlines, tabs, and spaces can be specified using the escaped syntax (e.g., n for a newline). The primary purpose of this parameter is to provide a kind of limited templating:

define resolve(nameserver1, nameserver2, domain, search) {
    $str = "search $search
domain $domain
nameserver $nameserver1
nameserver $nameserver2
"

    file { "/etc/resolv.conf":
        content => $str
    }
}

This attribute is especially useful when used with templating.

ensure

Whether to create files that don't currently exist. Possible values are absent, present, file, and directory. Specifying present will match any form of file existence, and if the file is missing will create an empty file. Specifying absent will delete the file (and directory if recurse => true).

Anything other than those values will be considered to be a symlink. For instance, the following text creates a link:

# Useful on solaris
file { "/etc/inetd.conf":
    ensure => "/etc/inet/inetd.conf"
}

You can make relative links:

# Useful on solaris
file { "/etc/inetd.conf":
    ensure => "inet/inetd.conf"
}

If you need to make a relative link to a file named the same as one of the valid values, you must prefix it with ./ or something similar.

You can also make recursive symlinks, which will create a directory structure that maps to the target directory, with directories corresponding to each directory and links corresponding to each file. Valid values are directory, file, link, present, absent (also called false). Values can also match /./.

force

Force the file operation. Currently only used when replacing directories with links. Valid values are true, false.

group

Which group should own the file. Argument can be either group name or group ID.

ignore

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

links

How to handle links during file actions. During file copying, follow will copy the target file instead of the link, manage will copy the link itself, and ignore will just pass it by. When not copying, manage and ignore behave equivalently (because you cannot really ignore links entirely during local recursion), and follow will manage the file to which the link points. Valid values are follow, manage.

mode

Mode the file should be. Currently relatively limited: you must specify the exact mode the file should be.

owner

To whom the file should belong. Argument can be user name or user ID.

path

• namevar

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

purge

Whether unmanaged files should be purged. If you have a filebucket configured the purged files will be uploaded, but if you do not, this will destroy data. Only use this option for generated files unless you really know what you are doing. This option only makes sense when recursively managing directories.

Note that when using purge with source, Puppet will purge any files that are not on the remote system. Valid values are true, false.

recurse

Whether and how deeply to do recursive management. Valid values are true, false, inf. Values can also match /^[0-9]+$/.

replace

Whether or not to replace a file that is sourced but exists. This is useful for using file sources purely for initialization. Valid values are true (also called yes), false (also called no).

selrange

What the SELinux range component of the context of the file should be. Any valid SELinux range component is accepted. For example s0 or SystemHigh. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled and that have support for MCS (Multi-Category Security).

selrole

What the SELinux role component of the context of the file should be. Any valid SELinux role component is accepted. For example role_r. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled.

seltype

What the SELinux type component of the context of the file should be. Any valid SELinux type component is accepted. For example tmp_t. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled.

seluser

What the SELinux user component of the context of the file should be. Any valid SELinux user component is accepted. For example user_u. If not specified it defaults to the value returned by matchpathcon for the file, if any exists. Only valid on systems with SELinux support enabled.

source

Copy a file over the current file. Uses checksum to determine when a file should be copied. Valid values are either fully qualified paths to files, or URIs. Currently supported URI types are puppet and file.

This is one of the primary mechanisms for getting content into applications that Puppet does not directly support and is very useful for those configuration files that don't change much across sytems. For instance:

class sendmail {
    file { "/etc/mail/sendmail.cf":
        source => "puppet://server/module/sendmail.cf"
    }
}

You can also leave out the server name, in which case puppetd will fill in the name of its configuration server and puppet will use the local filesystem. This makes it easy to use the same configuration in both local and centralized forms.

Currently, only the puppet scheme is supported for source URL's. Puppet will connect to the file server running on server to retrieve the contents of the file. If the server part is empty, the behavior of the command-line interpreter (puppet) and the client demon (puppetd) differs slightly: puppet will look such a file up on the module path on the local host, whereas puppetd will connect to the puppet server that it received the manifest from.

See the fileserver configuration documentation for information on how to configure and use file services within Puppet.

If you specify multiple file sources for a file, then the first source that exists will be used. This allows you to specify what amount to search paths for files:

file { "/path/to/my/file":
    source => [
        "/nfs/files/file.$host",
        "/nfs/files/file.$operatingsystem",
        "/nfs/files/file"
    ]
}

This will use the first found file as the source.

You cannot currently copy links using this mechanism; set links to follow if any remote sources are links.

sourceselect

Whether to copy all valid sources, or just the first one. This parameter is only used in recursive copies; by default, the first valid source is the only one used as a recursive source, but if this parameter is set to all, then all valid sources will have all of their contents copied to the local host, and for sources that have the same file, the source earlier in the list will be used. Valid values are first, all.

target

The target for creating a link. Currently, symlinks are the only type supported. Valid values are notlink. Values can also match /./.

type

A read-only state to check the file type.

---

filebucket

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

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

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

# Define the bucket
filebucket { main: server => puppet }

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

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

Parameters

name

• namevar

The name of the filebucket.

path

The path to the local filebucket. If this is not specified, then the bucket is remote and server must be specified.

port

The port on which the remote server is listening. Defaults to the normal Puppet port, 8140.

server

The server providing the filebucket. If this is not specified, then the bucket is local and path must be specified.

---

group

Manage groups. On most platforms this can only create groups. Group membership must be managed on individual users.

On some platforms such as OS X, group membership is managed as an attribute of the group, not the user record. Providers must have the feature 'manages_members' to manage the 'members' property of a group record.

Features

• manages_members: For directories where membership is an attribute of groups not users.

Provider	manages_members
directoryservice	X
groupadd
ldap
netinfo
pw

Parameters

allowdupe

Whether to allow duplicate GIDs. This option does not work on FreeBSD (contract to the pw man page). Valid values are true, false.

auth_membership

whether the provider is authoritative for group membership.

ensure

Create or remove the group. Valid values are absent, present.

gid

The group ID. Must be specified numerically. If not specified, a number will be picked, which can result in ID differences across systems and thus is not recommended. The GID is picked according to local system standards.

members

The members of the group. For directory services where group membership is stored in the group objects, not the users. Requires features manages_members.

name

• namevar

The group name. While naming limitations vary by system, it is advisable to keep the name to the degenerate limitations, which is a maximum of 8 characters beginning with a letter.

provider

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

• directoryservice: Group management using DirectoryService on OS X.

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

• groupadd: Group management via groupadd and its ilk.

  The default for most platforms

  Required binaries: groupmod, groupadd, groupdel.

• ldap: Group management via ldap.

  This provider requires that you have valid values for all of the ldap-related settings, including ldapbase. You will also almost definitely need settings for ldapuser and ldappassword, so that your clients can 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.

• netinfo: Group management using NetInfo.

  Required binaries: nireport, niutil.

• pw: Group management via pw.

  Only works on FreeBSD.

  Required binaries: /usr/sbin/pw. Default for operatingsystem == freebsd.

---

host

Installs and manages host entries. For most systems, these entries will just be in /etc/hosts, but some systems (notably OS X) will have different solutions.

Parameters

alias

Any alias the host might have. Multiple values must be specified as an array. Note that this state has the same name as one of the metaparams; using this state to set aliases will make those aliases available in your Puppet scripts and also on disk.

ensure

The basic property that the resource should be in. Valid values are absent, present.

ip

The host's IP address, IPv4 or IPv6.

name

• namevar

The host name.

provider

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

• netinfo: Host management in NetInfo.

  This provider is highly experimental and is known not to work currently.

  Required binaries: mount, umount, nireport, df, niutil. Default for operatingsystem == darwin.

• parsed:

target

The file in which to store service information. Only used by those providers that write to disk (i.e., not NetInfo).

---

k5login

Manage the .k5login file for a user. Specify the full path to the .k5login file as the name and an array of principals as the property principals.

Parameters

ensure

The basic property that the resource should be in. Valid values are absent, present.

mode

Manage the k5login file's mode

path

• namevar

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

principals

The principals present in the .k5login file.

provider

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

• k5login: The k5login provider is the only provider for the k5login

  type.

---

macauthorization

Manage the Mac OS X authorization database. See: http://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Security_Services/chapter_4_section_5.html for more information.

Parameters

allow_root

Corresponds to 'allow-root' in the authorization store, renamed due to hyphens being problematic. Specifies whether a right should be allowed automatically if the requesting process is running with uid == 0. AuthorizationServices defaults this attribute to false if not specified Valid values are false, true.

auth_class

Corresponds to 'class' in the authorization store, renamed due to 'class' being a reserved word. Valid values are user, evaluate-mechanisms.

auth_type

type - can be a 'right' or a 'rule'. 'comment' has not yet been implemented. Valid values are rule, right.

authenticate_user

Corresponds to 'authenticate-user' in the authorization store, renamed due to hyphens being problematic. Valid values are false, true.

comment

The 'comment' attribute for authorization resources.

ensure

The basic property that the resource should be in. Valid values are absent, present.

group

The user must authenticate as a member of this group. This attribute can be set to any one group.

k_of_n

k-of-n. Built-in rights only show a value of '1' or absent, other values may be acceptable. Undocumented.

mechanisms

an array of suitable mechanisms.

name

• namevar

The name of the right or rule to be managed. Corresponds to 'key' in Authorization Services. The key is the name of a rule. A key uses the same naming conventions as a right. The Security Server uses a rule’s key to match the rule with a right. Wildcard keys end with a ‘.’. The generic rule has an empty key value. Any rights that do not match a specific rule use the generic rule.

provider

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

• macauthorization: Manage Mac OS X authorization database rules and rights.

  Required binaries: /usr/bin/security, /usr/bin/sw_vers. Default for operatingsystem == darwin.

rule

The rule(s) that this right refers to.

session_owner

Corresponds to 'session-owner' in the authorization store, renamed due to hyphens being problematic. Whether the session owner automatically matches this rule or right. Valid values are false, true.

shared

If this is set to true, then the Security Server marks the credentials used to gain this right as shared. The Security Server may use any shared credentials to authorize this right. For maximum security, set sharing to false so credentials stored by the Security Server for one application may not be used by another application. Valid values are false, true.

timeout

The credential used by this rule expires in the specified number of seconds. For maximum security where the user must authenticate every time, set the timeout to 0. For minimum security, remove the timeout attribute so the user authenticates only once per session.

tries

The number of tries allowed.

---

mailalias

Creates an email alias in the local alias database.

Parameters

ensure

The basic property that the resource should be in. Valid values are absent, present.

name

• namevar

The alias name.

provider

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

• aliases:

recipient

Where email should be sent. Multiple values should be specified as an array.

target

The file in which to store the aliases. Only used by those providers that write to disk (i.e., not NetInfo).

---

maillist

Manage email lists. This resource type currently can only create and remove lists, it cannot reconfigure them.

Parameters

admin

The email address of the administrator.

description

The description of the mailing list.

ensure

The basic property that the resource should be in. Valid values are purged, absent, present.

mailserver

The name of the host handling email for the list.

name

• namevar

The name of the email list.

password

The admin password.

provider

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

• mailman: Required binaries: newlist, /var/lib/mailman/mail/mailman, list_lists, rmlist.

webserver

The name of the host providing web archives and the administrative interface.

---

mcx

MCX object management using DirectoryService on OS X. Original Author: Jeff McCune <mccune.jeff@gmail.com> The default provider of this type merely manages the XML plist as reported by the dscl -mcxexport command. This is similar to the content property of the file type in Puppet. The recommended method of using this type is to use Work Group Manager to manage users and groups on the local computer, record the resulting puppet manifest using the command 'ralsh mcx' then deploying this to other machines.

Features

• manages_content: The provider can manage MCXSettings as a string.

Provider	manages_content
mcxcontent	X

Parameters

content

The XML Plist. The value of MCXSettings in DirectoryService. This is the standard output from the system command: dscl localhost -mcxexport /Local/Default/<ds_type>/<ds_name> Note that ds_type is capitalized and plural in the dscl command. Requires features manages_content.

ds_name

The name to attach the MCX Setting to. e.g. 'localhost' when ds_type => computer. This setting is not required, as it may be parsed so long as the resource name is parseable. e.g. /Groups/admin where 'group' is the dstype.

ds_type

The DirectoryService type this MCX setting attaches to. Valid values are user, group, computer, computerlist.

ensure

Create or remove the MCX setting. Valid values are absent, present.

name

• namevar

The name of the resource being managed. The default naming convention follows Directory Service paths:

/Computers/localhost
/Groups/admin
/Users/localadmin

The ds_type and ds_name type parameters are not necessary if the default naming convention is followed.

provider

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

• mcxcontent: MCX Settings management using DirectoryService on OS X.

  This provider manages the entire MCXSettings attribute available to some directory services nodes. This management is 'all or nothing' in that discrete application domain key value pairs are not managed by this provider.

  It is recommended to use WorkGroup Manager to configure Users, Groups, Computers, or ComputerLists, then use 'ralsh mcx' to generate a puppet manifest from the resulting configuration.

  Original Author: Jeff McCune (mccune.jeff@gmail.com)

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

---

mount

Manages mounted filesystems, including putting mount information into the mount table. The actual behavior depends on the value of the 'ensure' parameter.

Note that if a mount receives an event from another resource, it will try to remount the filesystems if ensure is set to mounted.

Features

• refreshable: The provider can remount the filesystem.

Provider	refreshable
parsed	X

Parameters

atboot

Whether to mount the mount at boot. Not all platforms support this.

blockdevice

The device to fsck. This is property is only valid on Solaris, and in most cases will default to the correct value.

device

The device providing the mount. This can be whatever device is supporting by the mount, including network devices or devices specified by UUID rather than device path, depending on the operating system.

dump

Whether to dump the mount. Not all platforms support this. Valid values are 1 or 0. Default is 0. Values can also match /(0|1)/.

ensure

Control what to do with this mount. Set this attribute to present to make sure the filesystem is in the filesystem table but not mounted (if the filesystem is currently mounted, it will be unmounted). Set it to absent to unmount (if necessary) and remove the filesystem from the fstab. Set to mounted to add it to the fstab and mount it. Valid values are mounted, absent, present (also called unmounted).

fstype

The mount type. Valid values depend on the operating system.

name

• namevar

The mount path for the mount.

options

Mount options for the mounts, as they would appear in the fstab.

pass

The pass in which the mount is checked.

path

The deprecated name for the mount point. Please use name now.

provider

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

• parsed: Required binaries: mount, umount. Supported features: refreshable.

remounts

Whether the mount can be remounted mount -o remount. If this is false, then the filesystem will be unmounted and remounted manually, which is prone to failure. Valid values are true, false.

target

The file in which to store the mount table. Only used by those providers that write to disk (i.e., not NetInfo).

---

nagios_command

The Nagios type command. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_command.cfg, but you can send them to a different file by setting their target attribute.

Parameters

command_line

Nagios configuration file parameter.

command_name

• namevar

The name parameter for Nagios type command

ensure

The basic property that the resource should be in. Valid values are absent, present.

provider

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

• naginator:

target

target

use

Nagios configuration file parameter.

---

nagios_contact

The Nagios type contact. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_contact.cfg, but you can send them to a different file by setting their target attribute.

Parameters

address1

Nagios configuration file parameter.

address2

Nagios configuration file parameter.

address3

Nagios configuration file parameter.

address4

Nagios configuration file parameter.

address5

Nagios configuration file parameter.

address6

Nagios configuration file parameter.

alias

Nagios configuration file parameter.

can_submit_commands

Nagios configuration file parameter.

contact_name

• namevar

The name parameter for Nagios type contact

contactgroups

Nagios configuration file parameter.

email

Nagios configuration file parameter.

ensure

The basic property that the resource should be in. Valid values are absent, present.

host_notification_commands

Nagios configuration file parameter.

host_notification_options

Nagios configuration file parameter.

host_notification_period

Nagios configuration file parameter.

host_notifications_enabled

Nagios configuration file parameter.

pager

Nagios configuration file parameter.

provider

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

• naginator:

register

Nagios configuration file parameter.

retain_nonstatus_information

Nagios configuration file parameter.

retain_status_information

Nagios configuration file parameter.

service_notification_commands

Nagios configuration file parameter.

service_notification_options

Nagios configuration file parameter.

service_notification_period

Nagios configuration file parameter.

service_notifications_enabled

Nagios configuration file parameter.

target

target

use

Nagios configuration file parameter.

---

nagios_contactgroup

The Nagios type contactgroup. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_contactgroup.cfg, but you can send them to a different file by setting their target attribute.

Parameters

alias

Nagios configuration file parameter.

contactgroup_members

Nagios configuration file parameter.

contactgroup_name

• namevar

The name parameter for Nagios type contactgroup

ensure

The basic property that the resource should be in. Valid values are absent, present.

members

Nagios configuration file parameter.

provider

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

• naginator:

register

Nagios configuration file parameter.

target

target

use

Nagios configuration file parameter.

---

nagios_host

The Nagios type host. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_host.cfg, but you can send them to a different file by setting their target attribute.

Parameters

action_url

Nagios configuration file parameter.

active_checks_enabled

Nagios configuration file parameter.

address

Nagios configuration file parameter.

alias

Nagios configuration file parameter.

check_command

Nagios configuration file parameter.

check_freshness

Nagios configuration file parameter.

check_interval

Nagios configuration file parameter.

check_period

Nagios configuration file parameter.

contact_groups

Nagios configuration file parameter.

contacts

Nagios configuration file parameter.

display_name

Nagios configuration file parameter.

ensure

The basic property that the resource should be in. Valid values are absent, present.

event_handler

Nagios configuration file parameter.

event_handler_enabled

Nagios configuration file parameter.

failure_prediction_enabled

Nagios configuration file parameter.

first_notification_delay

Nagios configuration file parameter.

flap_detection_enabled

Nagios configuration file parameter.

flap_detection_options

Nagios configuration file parameter.

freshness_threshold

Nagios configuration file parameter.

high_flap_threshold

Nagios configuration file parameter.

host_name

• namevar

The name parameter for Nagios type host

hostgroups

Nagios configuration file parameter.

icon_image

Nagios configuration file parameter.

icon_image_alt

Nagios configuration file parameter.

initial_state

Nagios configuration file parameter.

low_flap_threshold

Nagios configuration file parameter.

max_check_attempts

Nagios configuration file parameter.

notes

Nagios configuration file parameter.

notes_url

Nagios configuration file parameter.

notification_interval

Nagios configuration file parameter.

notification_options

Nagios configuration file parameter.

notification_period

Nagios configuration file parameter.

notifications_enabled

Nagios configuration file parameter.

obsess_over_host

Nagios configuration file parameter.

parents

Nagios configuration file parameter.

passive_checks_enabled

Nagios configuration file parameter.

process_perf_data

Nagios configuration file parameter.

provider

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

• naginator:

register

Nagios configuration file parameter.

retain_nonstatus_information

Nagios configuration file parameter.

retain_status_information

Nagios configuration file parameter.

retry_interval

Nagios configuration file parameter.

stalking_options

Nagios configuration file parameter.

statusmap_image

Nagios configuration file parameter.

target

target

use

Nagios configuration file parameter.

vrml_image

Nagios configuration file parameter.

---

nagios_hostdependency

The Nagios type hostdependency. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_hostdependency.cfg, but you can send them to a different file by setting their target attribute.

Parameters

_naginator_name

• namevar

The name parameter for Nagios type hostdependency

dependency_period

Nagios configuration file parameter.

dependent_host_name

Nagios configuration file parameter.

dependent_hostgroup_name

Nagios configuration file parameter.

ensure

The basic property that the resource should be in. Valid values are absent, present.

execution_failure_criteria

Nagios configuration file parameter.

host_name

Nagios configuration file parameter.

hostgroup_name

Nagios configuration file parameter.

inherits_parent

Nagios configuration file parameter.

notification_failure_criteria

Nagios configuration file parameter.

provider

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

• naginator:

register

Nagios configuration file parameter.

target

target

use

Nagios configuration file parameter.

---

nagios_hostescalation

The Nagios type hostescalation. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_hostescalation.cfg, but you can send them to a different file by setting their target attribute.

Parameters

_naginator_name

• namevar

The name parameter for Nagios type hostescalation

contact_groups

Nagios configuration file parameter.

contacts

Nagios configuration file parameter.

ensure

The basic property that the resource should be in. Valid values are absent, present.

escalation_options

Nagios configuration file parameter.

escalation_period

Nagios configuration file parameter.

first_notification

Nagios configuration file parameter.

host_name

Nagios configuration file parameter.

hostgroup_name

Nagios configuration file parameter.

last_notification

Nagios configuration file parameter.

notification_interval

Nagios configuration file parameter.

provider

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

• naginator:

register

Nagios configuration file parameter.

target

target

use

Nagios configuration file parameter.

---

nagios_hostextinfo

The Nagios type hostextinfo. This resource type is autogenerated using the model developed in Naginator, and all of the Nagios types are generated using the same code and the same library.

This type generates Nagios configuration statements in Nagios-parseable configuration files. By default, the statements will be added to /etc/nagios/nagios_hostextinfo.cfg, but you can send them to a different file by setting their target attribute.

Parameters

ensure

The basic property that the resource should be in. Valid values are absent, present.

host_name

• namevar

The name parameter for Nagios type hostextinfo

icon_image

Nagios configuration file parameter.

icon_image_alt

Nagios configuration file parameter.

notes

Nagios configuration file parameter.

notes_url

Nagios configuration file parameter.

provider

The speci