diff --git a/documentation/documentation/typedocs.page b/documentation/documentation/typedocs.page
index 8eebf3c7a..20362dbbe 100644
--- a/documentation/documentation/typedocs.page
+++ b/documentation/documentation/typedocs.page
@@ -1,1601 +1,1603 @@
---
inMenu: true
title: Type Reference
orderInfo: 4
---
# Type Reference
## Table of Contents
1. Meta-Parameters
1. Cron
1. Exec
1. File
1. Filebucket
1. Group
1. Host
1. Mount
1. Package
1. Port
1. Schedule
1. Service
1. Sshkey
1. Symlink
1. Tidy
1. User
1. Yumrepo
1. Zone
Metaparameters are parameters that work with any element; 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.
#### 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.
[language tutorial]: languagetutorial.html
#### 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
States 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. *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"]
}
Note that Puppet will autorequire everything that it can, and
there are hooks in place so that it's easy for elements 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 elements 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]
}
}
#### tag
Add the specified tags to the associated element. While all elements
are automatically tagged with as much information as possible
(e.g., each class and component containing the element), it can
be useful to add your own tags to a given element.
Tags are currently useful for things like applying a subset of a
host's configuration:
puppetd --test --tag mytag
This way, when you're testing a configuration you can run just the
portion you're testing.
## Types
- *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 name 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 states) or they affect
how the instance behaves (e.g., adding a search path for ``exec`` instances
or determining recursion on ``file`` instances).
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.
----------------
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
}
### Cron 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 state that the object 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.
#### 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.
The names can only have alphanumeric characters plus the '-'
character.
#### special
Special schedules only supported on FreeBSD.
#### 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).
----------------
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 *creates* parameter.
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.
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 real Puppet element 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 element type for the work you are doing. In general,
it is a Puppet bug if you need ``exec`` to do your work.
### Exec 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
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`` element. Values are **true**, *false*,
and any legal log level. Valid values are ``true``, ``false``, ``debug``, ``info``, ``notice``, ``warning``, ``err``, ``alert``, ``emerg``, ``crit``.
#### 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.
#### 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.
#### 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`` can trigger actions, not ``require``,
so it only makes sense to use ``refreshonly`` with ``subscribe``. 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.
#### 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.
----------------
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`` element will be used less and less to
manage content, and instead native elements will be used to do so.
If you find that you are often copying files in from a central
location, rather than using native elements, please contact
Reductive Labs and we can hopefully work with you to develop a
native element to support what you are doing.
### File Parameters
#### backup
Whether files should be backed up before
being replaced. If a filebucket is specified, files will be
backed up there; else, they will be backed up in the same directory
with a ``.puppet-bak`` extension,, and no backups
will be made if backup is ``false``.
To use filebuckets, you must first create a filebucket 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 only benefits to doing so 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.
#### force
Force the file operation. Currently only used when replacing
directories with links. Valid values are ``true``, ``false``.
#### 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., ``*/*``.
#### linkmaker
An internal parameter used by the *symlink*
type to do recursive link creation.
#### 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``, ``ignore``.
#### 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. Valid values are ``true``, ``false``.
#### recurse
Whether and how deeply to do recursive
management. Valid values are ``true``, ``false``, ``inf``. Values can also match ``(?-mix:^[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``, ``false``.
----------------
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.
### Filebucket 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.
----------------
Manage groups. This type can only create groups. Group
membership must be managed on individual users. This element type
uses the prescribed native tools for creating groups and generally
uses POSIX APIs for retrieving information about them. It does
not directly modify /etc/group or anything.
For most platforms, the tools used are ``groupadd`` and its ilk;
for Mac OS X, NetInfo is used. This is currently unconfigurable,
but if you desperately need it to be so, please contact us.
### Group 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``.
#### ensure
The basic state that the object should be in. 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.
#### 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:
* **groupadd**: Group management via ``groupadd`` and its ilk. The default
for most platforms Required binaries: ``groupadd``, ``groupdel``, ``groupmod``.
* **netinfo**: Group management using NetInfo. Default for ``operatingsystem`` == ``darwin``. Required binaries: ``nireport``, ``niutil``.
* **pw**: Group management via ``pw``. Only works on FreeBSD. Default for ``operatingsystem`` == ``freebsd``. Required binaries: ``/usr/sbin/pw``.
----------------
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.
### Host 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 state that the object should be in. Valid values are ``absent``, ``present``.
#### ip
The host's IP address.
#### name (*namevar*)
The host name.
----------------
Manages mounted mounts, including putting mount
information into the mount table. The actual behavior depends
on the value of the 'ensure' parameter.
### Mount Parameters
#### atboot
Whether to mount the mount at boot. Not all platforms
support this.
#### blockdevice
The the device to fsck. This is state 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.
#### ensure
Control what to do with this mount. If the value is
``present``, the mount is entered into the mount table,
but not mounted, if it is ``absent``, the entry is removed
from the mount table and the filesystem is unmounted if
currently mounted, if it is ``mounted``, the filesystem
is entered into the mount table and mounted. Valid values are ``absent``, ``present``, ``mounted``.
#### fstype
The mount type. Valid values depend on the
operating system.
#### options
Mount options for the mounts, as they would
appear in the fstab.
#### pass
The pass in which the mount is checked.
#### path (*namevar*)
The mount path for the mount.
----------------
Manage packages. There is a basic dichotomy in package
support right now: Some package types (e.g., yum and apt) can
retrieve their own package files, while others (e.g., rpm and
sun) cannot. For those package formats that cannot retrieve
their own files, you can use the ``source`` parameter to point to
the correct file.
Puppet will automatically guess the packaging format that you are
using based on the platform you are on, but you can override it
using the ``type`` parameter; obviously, if you specify that you
want to use ``rpm`` then the ``rpm`` tools must be available.
### Package Parameters
#### adminfile
A file containing package defaults for installing packages.
This is currently only used on Solaris. The value will be
validated according to system rules, which in the case of
Solaris means that it should either be a fully qualified path
or it should be in /var/sadm/install/admin.
#### allowcdrom
Tells apt to allow cdrom sources in the sources.list file.
Normally apt will bail if you try this. Valid values are ``true``, ``false``.
#### category
A read-only parameter set by the package.
#### description
A read-only parameter set by the package.
#### ensure
What state the package should be in.
*latest* only makes sense for those packaging formats that can
retrieve new packages on their own and will throw an error on
those that cannot. For those packaging systems that allow you
to specify package versions, specify them here. Valid values are ``absent``, ``latest``, ``present`` (also called ``installed``). Values can also match ``(?-mix:.)``.
#### instance
A read-only parameter set by the package.
#### name (*namevar*)
The package name. This is the name that the packaging
system uses internally, which is sometimes (especially on Solaris)
a name that is basically useless to humans. If you want to
abstract package installation, then you can use aliases to provide
a common name to packages:
# In the 'openssl' class
$ssl = $operationgsystem ? {
solaris => SMCossl,
default => openssl
}
# It is not an error to set an alias to the same value as the
# object name.
package { $ssl:
ensure => installed,
alias => openssl
}
. etc. .
$ssh = $operationgsystem ? {
solaris => SMCossh,
default => openssh
}
# Use the alias to specify a dependency, rather than
# having another selector to figure it out again.
package { $ssh:
ensure => installed,
alias => openssh,
require => package[openssl]
}
#### platform
A read-only parameter set by the package.
#### provider
The specific backend for provider to use. You will
seldom need to specify this -- Puppet will usually discover the
appropriate provider for your platform. Available providers are:
* **apple**: Package management based on OS X's builtin packaging system. This is
essentially the simplest and least functional package system in existence --
it only supports installation; no deletion or upgrades. Default for ``operatingsystem`` == ``darwin``. Required binaries: ``/usr/sbin/installer``.
* **apt**: Package management via ``apt-get``. Default for ``operatingsystem`` == ``debian``. Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/apt-get``.
* **aptitude**: Package management via ``aptitude``. Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/aptitude``.
* **blastwave**: Package management using Blastwave.org's ``pkg-get`` command on Solaris. Required binaries: ``pkg-get``.
* **darwinport**: Package management using DarwinPorts on OS X. Required binaries: ``/opt/local/bin/port``.
* **dpkg**: Package management via ``dpkg``. Because this only uses ``dpkg``
and not ``apt``, you must specify the source of any packages you want
to manage. Required binaries: ``/usr/bin/dpkg``, ``/usr/bin/dpkg-query``.
* **freebsd**: The specific form of package management on FreeBSD. This is an
extremely quirky packaging system, in that it freely mixes between
ports and packages. Apparently all of the tools are written in Ruby,
so there are plans to rewrite this support to directly use those
libraries. Required binaries: ``/usr/sbin/pkg_delete``, ``/usr/sbin/pkg_info``, ``/usr/sbin/pkg_add``.
* **gem**: Ruby Gem support. By default uses remote gems, but you can specify
the path to a local gem via ``source``. Required binaries: ``gem``.
* **openbsd**: OpenBSD's form of ``pkg_add`` support. Default for ``operatingsystem`` == ``openbsd``. Required binaries: ``pkg_delete``, ``pkg_info``, ``pkg_add``.
* **portage**: Provides packaging support for Gentoo's portage system. Default for ``operatingsystem`` == ``gentoo``. Required binaries: ``/usr/bin/emerge``, ``/usr/bin/eix``.
* **ports**: Support for FreeBSD's ports. Again, this still mixes packages
and ports. Default for ``operatingsystem`` == ``freebsd``. Required binaries: ``/usr/sbin/pkg_info``, ``/usr/local/sbin/portupgrade``, ``/usr/local/sbin/portversion``, ``/usr/local/sbin/pkg_deinstall``.
* **rpm**: RPM packaging support; should work anywhere with a working ``rpm``
binary. Default for ``operatingsystem`` == ``redhat``. Required binaries: ``rpm``.
* **sun**: Sun's packaging system. Requires that you specify the source for
the packages you're managing. Default for ``operatingsystem`` == ``solaris``. Required binaries: ``/usr/sbin/pkgrm``, ``/usr/bin/pkginfo``, ``/usr/sbin/pkgadd``.
* **sunfreeware**: Package management using sunfreeware.com's ``pkg-get`` command on Solaris.
At this point, support is exactly the same as ``blastwave`` support and
has not actually been tested. Required binaries: ``pkg-get``.
* **up2date**: Support for Red Hat's proprietary ``up2date`` package update
mechanism. Required binaries: ``/usr/sbin/up2date-nox``.
* **yum**: Support via ``yum``. Default for ``operatingsystem`` == ``fedora``. Required binaries: ``rpm``, ``yum``.
#### responsefile
A file containing any necessary answers to questions asked by
the package. This is currently only used on Solaris. The
value will be validated according to system rules, but it should
generally be a fully qualified path.
#### root
A read-only parameter set by the package.
#### source
Where to find the actual package. This must be a local file
(or on a network file system) or a URL that your specific
packaging type understands; Puppet will not retrieve files for you.
#### status
A read-only parameter set by the package.
#### type
Deprecated form of ``provider``.
#### vendor
A read-only parameter set by the package.
----------------
Installs and manages port entries. For most systems, these
entries will just be in /etc/services, but some systems (notably OS X)
will have different solutions.
### Port Parameters
#### alias
Any aliases the port 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.
#### description
The port description.
#### ensure
The basic state that the object should be in. Valid values are ``absent``, ``present``.
#### name (*namevar*)
The port name.
#### number
The port number.
#### protocols
The protocols the port uses. Valid values are *udp* and *tcp*.
Most services have both protocols, but not all. If you want
both protocols, you must specify that; Puppet replaces the
current values, it does not merge with them. If you specify
multiple protocols they must be as an array.
----------------
Defined schedules for Puppet. The important thing to understand
about how schedules are currently implemented in Puppet is that they
can only be used to stop an element from being applied, they never
guarantee that it is applied.
Every time Puppet applies its configuration, it will collect the
list of elements whose schedule does not eliminate them from
running right then, but there is currently no system in place to
guarantee that a given element runs at a given time. If you
specify a very restrictive schedule and Puppet happens to run at a
time within that schedule, then the elements will get applied;
otherwise, that work may never get done.
Thus, it behooves you to use wider scheduling (e.g., over a couple of
hours) combined with periods and repetitions. For instance, if you
wanted to restrict certain elements to only running once, between
the hours of two and 4 AM, then you would use this schedule:
schedule { maint:
range => "2 - 4",
period => daily,
repeat => 1
}
With this schedule, the first time that Puppet runs between 2 and 4 AM,
all elements with this schedule will get applied, but they won't
get applied again between 2 and 4 because they will have already
run once that day, and they won't get applied outside that schedule
because they will be outside the scheduled range.
Puppet automatically creates a schedule for each valid period with the
same name as that period (e.g., hourly and daily). Additionally,
a schedule named *puppet* is created and used as the default,
with the following attributes:
schedule { puppet:
period => hourly,
repeat => 2
}
This will cause elements to be applied every 30 minutes by default.
### Schedule Parameters
#### name (*namevar*)
The name of the schedule. This name is used to retrieve the
schedule when assigning it to an object:
schedule { daily:
period => daily,
range => [2, 4]
}
exec { "/usr/bin/apt-get update":
schedule => daily
}
#### period
The period of repetition for an element. Choose from among
a fixed list of *hourly*, *daily*, *weekly*, and *monthly*.
The default is for an element to get applied every time that
Puppet runs, whatever that period is.
Note that the period defines how often a given element will get
applied but not when; if you would like to restrict the hours
that a given element can be applied (e.g., only at night during
a maintenance window) then use the ``range`` attribute.
If the provided periods are not sufficient, you can provide a
value to the *repeat* attribute, which will cause Puppet to
schedule the affected elements 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 element up to every 10 minutes.
At the moment, Puppet cannot guarantee that level of
repetition; that is, it can run up to every 10 minutes, but
internal factors might prevent it from actually running that
often (e.g., long-running Puppet runs will squash conflictingly
scheduled runs).
See the ``periodmatch`` attribute for tuning whether to match
times by their distance apart or by their specific value. Valid values are ``hourly``, ``daily``, ``weekly``, ``monthly``.
#### periodmatch
Whether periods should be matched by number (e.g., the two times
are in the same hour) or by distance (e.g., the two times are
60 minutes apart). *number*/**distance** Valid values are ``number``, ``distance``.
#### range
The earliest and latest that an element can be applied. This
is always a range within a 24 hour period, and hours must be
specified in numbers between 0 and 23, inclusive. Minutes and
seconds can 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 elements to being
applied in maintenance windows or during off-peak hours.
#### repeat
How often the application gets repeated in a given period.
Defaults to 1. Must be an integer.
----------------
Manage running services. Service support unfortunately varies
widely by platform -- some platforms have very little if any
concept of a running service, and some have a very codified and
powerful concept. Puppet's service support will generally be able
to make up for any inherent shortcomings (e.g., if there is no
'status' command, then Puppet will look in the process table for a
command matching the service name), but the more information you
can provide the better behaviour you will get. Or, you can just
use a platform that has very good service support.
### Service Parameters
#### binary
The path to the daemon. This is only used for
systems that do not support init scripts. This binary will be
used to start the service if no ``start`` parameter is
provided.
#### enable
Whether a service should be enabled to start at boot.
This state behaves quite differently depending on the platform;
wherever possible, it relies on local tools to enable or disable
a given service. *true*/*false*/*runlevels* Valid values are ``true``, ``false``.
#### ensure
Whether a service should be running. **true**/*false* Valid values are ``running`` (also called ``true``), ``stopped`` (also called ``false``).
#### hasrestart
Specify that an init script has a ``restart`` option. Otherwise,
the init script's ``stop`` and ``start`` methods are used. Valid values are ``true``, ``false``.
#### hasstatus
Declare the the service's init script has a
functional status command. Based on testing, it was found
that a large number of init scripts on different platforms do
not support any kind of status command; thus, you must specify
manually whether the service you are running has such a
command (or you can specify a specific command using the
``status`` parameter).
If you do not specify anything, then the service name will be
looked for in the process table.
#### name (*namevar*)
The name of the service to run. This name
is used to find the service in whatever service subsystem it
is in.
#### path
The search path for finding init scripts.
#### pattern
The pattern to search for in the process table.
This is used for stopping services on platforms that do not
support init scripts, and is also used for determining service
status on those service whose init scripts do not include a status
command.
If this is left unspecified and is needed to check the status
of a service, then the service name will be used instead.
The pattern can be a simple string or any legal Ruby pattern.
#### 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:
* **base**: The simplest form of 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. It is preferable to
specify start, stop, and status commands, akin to how you would do
so using ``init``.
* **debian**: Debian's form of ``init``-style management. The only difference
is that this supports service enabling and disabling via ``update-rc.d``. Default for ``operatingsystem`` == ``debian``. Required binaries: ``/usr/sbin/update-rc.d``.
* **init**: Standard init service management. This provider assumes that the
init script has not ``status`` command, because so few scripts do,
so you need to either provide a status command or specify via ``hasstatus``
that one already exists in the init script.
* **redhat**: Red Hat's (and probably many others) form of ``init``-style service
management; uses ``chkconfig`` for service enabling and disabling. Default for ``operatingsystem`` == ``redhatfedorasuse``. Required binaries: ``/sbin/chkconfig``.
* **smf**: Support for Sun's new Service Management Framework. Starting a service
is effectively equivalent to enabling it, so there is only support
for starting and stopping services, which also enables and disables them,
respectively. Default for ``operatingsystem`` == ``solaris``. Required binaries: ``/usr/sbin/svcadm``, ``/usr/bin/svcs``.
#### restart
Specify a *restart* command manually. If left
unspecified, the service will be stopped and then started.
#### running
A place-holder parameter that wraps ``ensure``, because
``running`` is deprecated. You should use ``ensure`` instead
of this, but using this will still work, albeit with a
warning.
#### start
Specify a *start* command manually. Most service subsystems
support a ``start`` command, so this will not need to be
specified.
#### status
Specify a *status* command manually. If left
unspecified, the status method will be determined
automatically, usually by looking for the service in the
process table.
#### stop
Specify a *stop* command manually.
#### type
Deprecated form of ``provder``.
----------------
Installs and manages ssh host keys. At this point, this type
only knows how to install keys into /etc/ssh/ssh_known_hosts, and
it cannot manage user authorized keys yet.
### Sshkey 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.
#### ensure
The basic state that the object should be in. Valid values are ``absent``, ``present``.
#### key
The key itself; generally a long string of hex digits.
#### name (*namevar*)
The host name.
#### type
The encryption type used. Probably ssh-dss or ssh-rsa.
----------------
Create symbolic links to existing files. **This type is deprecated;
use file instead.**
### Symlink Parameters
#### ensure
Create a link to another file. Currently only symlinks
are supported, and attempts to replace normal files with
links will currently fail, while existing but incorrect symlinks
will be removed.
#### path (*namevar*)
The path to the file to manage. Must be fully qualified.
#### recurse
If target is a directory, recursively create
directories (using `file`'s `source` parameter) and link all
contained files. For instance:
# The Solaris Blastwave repository installs everything
# in /opt/csw; link it into /usr/local
symlink { "/usr/local":
ensure => "/opt/csw",
recurse => true
}
Note that this does not link directories -- any directories
are created in the destination, and any files are linked over.
----------------
Remove unwanted files based on specific criteria.
### Tidy Parameters
#### age
Tidy files whose age is equal to or greater than
the specified number of days.
#### backup
Whether files should be backed up before
being replaced. If a filebucket is specified, files will be
backed up there; else, they will be backed up in the same directory
with a ``.puppet-bak`` extension,, and no backups
will be made if backup is ``false``.
To use filebuckets, you must first create a filebucket 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 only benefits to doing so 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.
#### path (*namevar*)
The path to the file or directory to manage. Must be fully
qualified.
#### recurse
If target is a directory, recursively descend
into the directory looking for files to tidy.
#### rmdirs
Tidy directories in addition to files; that is, remove
directories whose age is older than the specified criteria.
#### size
Tidy files whose size is equal to or greater than
the specified size. Unqualified values are in kilobytes, but
*b*, *k*, and *m* can be appended to specify *bytes*, *kilobytes*,
and *megabytes*, respectively. Only the first character is
significant, so the full word can also be used.
#### type
Set the mechanism for determining age.
**atime**/*mtime*/*ctime*.
----------------
Manage users. Currently can create and modify users, but
cannot delete them. Theoretically all of the parameters are
optional, but if no parameters are specified the comment will
be set to the user name in order to make the internals work out
correctly.
This element type uses the prescribed native tools for creating
groups and generally uses POSIX APIs for retrieving information
about them. It does not directly modify /etc/passwd or anything.
For most platforms, the tools used are ``useradd`` and its ilk;
for Mac OS X, NetInfo is used. This is currently unconfigurable,
but if you desperately need it to be so, please contact us.
### User Parameters
#### allowdupe
Whether to allow duplicate UIDs. Valid values are ``true``, ``false``.
#### comment
A description of the user. Generally is a user's full name.
#### ensure
The basic state that the object should be in. Valid values are ``absent``, ``present``.
#### gid
The user's primary group. Can be specified numerically or
by name.
#### groups
The groups of which the user is a member. The primary
group should not be listed. Multiple groups should be
specified as an array.
#### home
The home directory of the user. The directory must be created
separately and is not currently checked for existence.
#### membership
Whether specified groups should be treated as the only groups
of which the user is a member or whether they should merely
be treated as the minimum membership list. Valid values are ``inclusive``, ``minimum``.
#### name (*namevar*)
User name. While limitations are determined for
each operating system, it is generally a good idea to keep to
the degenerate 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:
* **netinfo**: User management in NetInfo. Default for ``operatingsystem`` == ``darwin``. Required binaries: ``nireport``, ``niutil``.
* **pw**: User management via ``pw`` on FreeBSD. Default for ``operatingsystem`` == ``freebsd``. Required binaries: ``pw``.
* **useradd**: User management via ``useradd`` and its ilk. Required binaries: ``useradd``, ``userdel``, ``usermod``.
#### shell
The user's login shell. The shell must exist and be
executable.
#### uid
The user ID. Must be specified numerically. For new users
being created, if no user ID is specified then one will be
chosen automatically, which will likely result in the same user
having different IDs on different systems, which is not
recommended.
----------------
The client-side description of a yum repository. Repository
configurations are found by parsing /etc/yum.conf and
the files indicated by reposdir in that file (see yum.conf(5)
for details)
Most parameters are identical to the ones documented
in yum.conf(5)
Continuation lines that yum supports for example for the
baseurl are not supported. No attempt is made to access
files included with the **include** directive
### Yumrepo Parameters
#### baseurl
The URL for this repository.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### descr
A human readable description of the repository.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### enabled
Whether this repository is enabled or disabled. Possible
values are '0', and '1'.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:(0|1))``.
#### enablegroups
Determines whether yum will allow the use of
package groups for this repository. Possible
values are '0', and '1'.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:(0|1))``.
#### exclude
List of shell globs. Matching packages will never be
considered in updates or installs for this repo.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### failovermethod
Either 'roundrobin' or 'priority'.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:roundrobin|priority)``.
#### gpgcheck
Whether to check the GPG signature on packages installed
from this repository. Possible values are '0', and '1'.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:(0|1))``.
#### gpgkey
The URL for the GPG key with which packages from this
repository are signed.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### include
A URL from which to include the config.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### includepkgs
List of shell globs. If this is set, only packages
matching one of the globs will be considered for
update or install.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### keepalive
Either '1' or '0'. This tells yum whether or not HTTP/1.1
keepalive should be used with this repository.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:(0|1))``.
#### metadata_expire
Number of seconds after which the metadata will expire.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:[0-9]+)``.
#### mirrorlist
The URL that holds the list of mirrors for this repository.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:.*)``.
#### name (*namevar*)
The name of the repository.
#### timeout
Number of seconds to wait for a connection before timing
out.
Set this to 'absent' to remove it from the file completely Valid values are ``absent``. Values can also match ``(?-mix:[0-9]+)``.
----------------
Solaris zones.
### Zone Parameters
#### autoboot
Whether the zone should automatically boot. Valid values are ``true``, ``false``.
#### ensure
The running state of the zone. The valid states directly reflect
the states that ``zoneadm`` provides. The states are linear,
in that a zone must be ``configured`` then ``installed``, and
only then can be ``running``. Note also that ``halt`` is currently
used to stop zones. Valid values are ``absent``, ``configured``, ``installed``, ``running``.
#### id
The numerical ID of the zone. This number is autogenerated
and cannot be changed.
#### inherit
The list of directories that the zone inherits from the global
zone. All directories must be fully qualified.
#### ip
The IP address of the zone. IP addresses must be specified
with the interface, separated by a colon, e.g.: bge0:192.168.0.1.
For multiple interfaces, specify them in an array.
#### name (*namevar*)
The name of the zone.
#### path
The root of the zone's filesystem. Must be a fully qualified
file name. If you include '%s' in the path, then it will be
replaced with the zone's name. At this point, you cannot use
Puppet to move a zone.
#### pool
The resource pool for this zone.
#### realhostname
The actual hostname of the zone.
#### shares
Number of FSS CPU shares allocated to the zone.
#### sysidcfg
The text to go into the sysidcfg file when the zone is first
booted. The best way is to use a template:
+
# $templatedir/sysidcfg
system_locale=en_US
timezone=GMT
terminal=xterms
security_policy=NONE
root_password=<%= password %>
timeserver=localhost
name_service=DNS {domain_name=<%= domain %>
name_server=<%= nameserver %>}
network_interface=primary {hostname=<%= realhostname %>
ip_address=<%= ip %>
netmask=<%= netmask %>
protocol_ipv6=no
default_route=<%= defaultroute %>}
nfs4_domain=dynamic
+
And then call that:
zone { myzone:
ip => "bge0:192.168.0.23",
sysidcfg => template(sysidcfg),
path => "/opt/zones/myzone",
realhostname => "fully.qualified.domain.name"
}
The sysidcfg only matters on the first booting of the zone,
so Puppet only checks for it at that time.
----------------
-*This page autogenerated on Thu Sep 21 14:25:06 CDT 2006*
+*This page autogenerated on Thu Sep 21 14:35:35 CDT 2006*