Resource Type: package

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

The package name. This is the name that the packaging system uses internally, which is sometimes (especially on Solaris) a name that is basically useless to humans. If a package goes by several names, you can use a single title and then set the name conditionally:

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

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

...

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

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

(↑ Back to package attributes)

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

The targeted command to use when managing a package:

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

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

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

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

Default: default

Requires features targetable.

(↑ Back to package attributes)

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

What state the package should be in. On packaging systems that can retrieve new packages on their own, you can choose which package to retrieve by specifying a version number or latest as the ensure value. On packaging systems that manage configuration files separately from "normal" system files, you can uninstall config files by specifying purged as the ensure value. This defaults to installed.

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

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

Default: installed

Allowed values:

• present

• absent

• purged

• disabled

• installed

• latest

• /./

(↑ Back to package attributes)

A file containing package defaults for installing packages.

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

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

(↑ Back to package attributes)

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

Allowed values:

• true

• false

• yes

• no

Requires features virtual_packages.

(↑ Back to package attributes)

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

Allowed values:

• true

• false

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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

Default: keep

Allowed values:

• keep

• replace

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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

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

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

Default: false

Allowed values:

• true

• false

• yes

• no

(↑ Back to package attributes)

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

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

Requires features supports_flavors.

(↑ Back to package attributes)

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

Default: false

Allowed values:

• true

• false

• yes

• no

Requires features install_only.

(↑ Back to package attributes)

An array of additional options to pass when installing a package. These options are package-specific, and should be documented by the software vendor. One commonly implemented option is INSTALLDIR:

package { 'mysql':
  ensure          => installed,
  source          => 'N:/packages/mysql-5.5.16-winx64.msi',
  install_options => [ '/S', { 'INSTALLDIR' => 'C:\\mysql-5.5' } ],
}

Each option in the array can either be a string or a hash, where each key and value pair are interpreted in a provider specific way. Each option will automatically be quoted when passed to the install command.

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

Requires features install_options.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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

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

#{mark_doc} Default is "none". Mark can be specified with or without ensure, if ensure is missing will default to "present".

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

Allowed values:

• hold

• none

Requires features holdable.

(↑ Back to package attributes)

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

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

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

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

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

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

Requires features package_settings.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

The specific backend to use for this package resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

Available providers are:

• aix

• appdmg

• apple

• apt

• aptitude

• aptrpm

• blastwave

• dnf

• dnfmodule

• dpkg

• fink

• freebsd

• gem

• hpux

• macports

• nim

• openbsd

• opkg

• pacman

• pip2

• pip3

• pip

• pkg

• pkgdmg

• pkgin

• pkgng

• pkgutil

• portage

• ports

• portupgrade

• puppet_gem

• puppetserver_gem

• rpm

• rug

• sun

• sunfreeware

• tdnf

• up2date

• urpmi

• windows

• yum

• zypper

(↑ Back to package attributes)

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

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

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

Default: false

Allowed values:

• true

• false

(↑ Back to package attributes)

A file containing any necessary answers to questions asked by the package. This is currently used on Solaris and Debian. The value will be validated according to system rules, but it should generally be a fully qualified path.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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

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

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

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

An array of additional options to pass when uninstalling a package. These options are package-specific, and should be documented by the software vendor. For example:

package { 'VMware Tools':
  ensure            => absent,
  uninstall_options => [ { 'REMOVE' => 'Sync,VSS' } ],
}

Each option in the array can either be a string or a hash, where each key and value pair are interpreted in a provider specific way. Each option will automatically be quoted when passed to the uninstall command.

On Windows, this is the only place in Puppet where backslash separators should be used. Note that backslashes in double-quoted strings must be double-escaped and backslashes in single-quoted strings may be double-escaped.

Requires features uninstall_options.

(↑ Back to package attributes)

A read-only parameter set by the package.

(↑ Back to package attributes)

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

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

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

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

• Confined to: operatingsystem == [ :aix ]

• Default for: ["operatingsystem", "aix"] ==

• Supported features: versionable

Package management which copies application bundles to a target.

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

• Confined to: operatingsystem == darwin, feature == cfpropertylist

Package management based on OS X's built-in packaging system. This is essentially the simplest and least functional package system in existence -- it only supports installation; no deletion or upgrades. The provider will automatically add the .pkg extension, so leave that off when specifying the package name.

• Required binaries: /usr/sbin/installer

• Confined to: operatingsystem == darwin

Package management via apt-get.

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

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

• Default for: ["osfamily", "debian"] ==

• Supported features: versionable, install_options, virtual_packages

Package management via aptitude.

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

• Supported features: versionable

Package management via apt-get ported to rpm.

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

• Supported features: versionable

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

• Required binaries: pkgget

• Confined to: osfamily == solaris

Support via dnf.

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

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

• Required binaries: dnf, rpm

• Default for: ["operatingsystem", "fedora"] == , ["osfamily", "redhat"] ==

• Supported features: install_options, versionable, virtual_packages, install_only

• Required binaries: /usr/bin/dnf

• Supported features: installable, uninstallable, versionable, supports_flavors, disableable

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

• Supported features: holdable, virtual_packages

Package management via fink.

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

• Supported features: versionable

The specific form of package management on FreeBSD. This is an extremely quirky packaging system, in that it freely mixes between ports and packages. Apparently all of the tools are written in Ruby, so there are plans to rewrite this support to directly use those libraries.

• Required binaries: /usr/sbin/pkg_info, /usr/sbin/pkg_add, /usr/sbin/pkg_delete

• Confined to: operatingsystem == freebsd

Ruby Gem support. If a URL is passed via source, then that URL is appended to the list of remote gem repositories; to ensure that only the specified source is used, also pass --clear-sources via install_options. If source is present but is not a valid URL, it will be interpreted as the path to a local gem file. If source is not present, the gem will be installed from the default gem repositories. Note that to modify this for Windows, it has to be a valid URL.

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

• Supported features: versionable, install_options, uninstall_options, targetable, version_ranges

HP-UX's packaging system.

• Required binaries: /usr/sbin/swinstall, /usr/sbin/swlist, /usr/sbin/swremove

• Confined to: operatingsystem == hp-ux

• Default for: ["operatingsystem", "hp-ux"] ==

Package management using MacPorts on OS X.

Supports MacPorts versions and revisions, but not variants. Variant preferences may be specified using the MacPorts variants.conf file.

When specifying a version in the Puppet DSL, only specify the version, not the revision. Revisions are only used internally for ensuring the latest version/revision of a port.

• Confined to: operatingsystem == darwin

• Supported features: installable, uninstallable, upgradeable, versionable

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

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

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

• Confined to: exists == /etc/niminfo

• Supported features: versionable

OpenBSD's form of pkg_add support.

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

• Required binaries: pkg_info, pkg_add, pkg_delete

• Confined to: operatingsystem == openbsd

• Default for: ["operatingsystem", "openbsd"] ==

• Supported features: versionable, install_options, uninstall_options, upgradeable, supports_flavors

Opkg packaging support. Common on OpenWrt and OpenEmbedded platforms

• Required binaries: opkg

• Confined to: operatingsystem == openwrt

• Default for: ["operatingsystem", "openwrt"] ==

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

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

• Required binaries: /usr/bin/pacman

• Confined to: operatingsystem == [:archlinux, :manjarolinux]

• Default for: ["operatingsystem", "[:archlinux, :manjarolinux]"] ==

• Supported features: install_options, uninstall_options, upgradeable, virtual_packages

Python packages via pip.

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

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

Python packages via pip2.

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

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

Python packages via pip3.

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

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

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

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

• Required binaries: /usr/bin/pkg

• Confined to: osfamily == solaris

• Default for: ["osfamily", "solaris"] == ["kernelrelease", "['5.11', '5.12']"]

• Supported features: versionable, upgradable, holdable, install_options

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

This provider works by checking the contents of a DMG image for Apple pkg or mpkg files. Any number of pkg or mpkg files may exist in the root directory of the DMG file system, and Puppet will install all of them. Subdirectories are not checked for packages.

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

Notes:

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

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

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

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

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

• Confined to: operatingsystem == darwin, feature == cfpropertylist

• Default for: ["operatingsystem", "darwin"] ==

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

• Required binaries: pkgin

• Default for: ["operatingsystem", "[ :smartos, :netbsd ]"] ==

• Supported features: installable, uninstallable, upgradeable, versionable

A PkgNG provider for FreeBSD and DragonFly.

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

• Confined to: operatingsystem == [:freebsd, :dragonfly]

• Default for: ["operatingsystem", "[:freebsd, :dragonfly]"] ==

• Supported features: versionable, upgradeable, install_options

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

• Confined to: osfamily == solaris

Provides packaging support for Gentoo's portage system.

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

• Confined to: osfamily == gentoo

• Default for: ["osfamily", "gentoo"] ==

• Supported features: install_options, purgeable, reinstallable, uninstall_options, versionable, virtual_packages

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

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

Support for FreeBSD's ports using the portupgrade ports management software. Use the port's full origin as the resource name. eg (ports-mgmt/portupgrade) for the portupgrade port.

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

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

• Confined to: true == Puppet.runtime[:facter].value(:aio_agent_version)

• Supported features: versionable, install_options, uninstall_options

Puppet Server Ruby Gem support. If a URL is passed via source, then that URL is appended to the list of remote gem repositories which by default contains rubygems.org; To ensure that only the specified source is used also pass --clear-sources in via install_options; if a source is present but is not a valid URL, it will be interpreted as the path to a local gem file. If source is not present at all, the gem will be installed from the default gem repositories.

• Confined to: feature == hocon, fips_enabled == false

• Supported features: versionable, install_options, uninstall_options

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

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

• Required binaries: rpm

• Supported features: versionable, install_options, uninstall_options, virtual_packages, install_only

Support for suse rug package manager.

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

• Confined to: operatingsystem == [:suse, :sles]

• Supported features: versionable

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

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

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

• Confined to: osfamily == solaris

• Default for: ["osfamily", "solaris"] ==

• Supported features: install_options

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

• Confined to: osfamily == solaris

Support via tdnf.

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

• Required binaries: tdnf, rpm

• Default for: ["operatingsystem", "PhotonOS"] ==

• Supported features: install_options, versionable, virtual_packages

Support for Red Hat's proprietary up2date package update mechanism.

• Required binaries: /usr/sbin/up2date-nox

• Confined to: osfamily == redhat

• Default for: ["osfamily", "redhat"] == ["lsbdistrelease", "["2.1", "3", "4"]"]

Support via urpmi.

• Required binaries: urpmi, urpmq, rpm, urpme

• Default for: ["operatingsystem", "[:mandriva, :mandrake]"] ==

• Supported features: versionable

Windows package management.

This provider supports either MSI or self-extracting executable installers.

This provider requires a source attribute when installing the package. It accepts paths to local files, mapped drives, or UNC paths.

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

If the executable requires special arguments to perform a silent install or uninstall, then the appropriate arguments should be specified using the install_options or uninstall_options attributes, respectively. Puppet will automatically quote any option that contains spaces.

• Confined to: operatingsystem == windows

• Default for: ["operatingsystem", "windows"] ==

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

Support via yum.

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

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

• Required binaries: yum, rpm

• Default for: ["operatingsystem", "amazon"] == , ["osfamily", "redhat"] == ["operatingsystemmajrelease", "(4..7).to_a"]

• Supported features: install_options, versionable, virtual_packages, install_only

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

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

• Required binaries: /usr/bin/zypper

• Confined to: operatingsystem == [:suse, :sles, :sled, :opensuse]

• Default for: ["operatingsystem", "[:suse, :sles, :sled, :opensuse]"] ==

• Supported features: versionable, install_options, virtual_packages