Salt can manage software packages via the pkg state module, packages can be set up to be installed, latest, removed and purged. Package management declarations are typically rather simple:
vim:
pkg.installed
A more involved example involves pulling from a custom repository.
base:
pkgrepo.managed:
- humanname: Logstash PPA
- name: ppa:wolfnet/logstash
- dist: precise
- file: /etc/apt/sources.list.d/logstash.list
- keyid: 28B04E4A
- keyserver: keyserver.ubuntu.com
logstash:
pkg.installed
- fromrepo: ppa:wolfnet/logstash
Multiple packages can also be installed with the use of the pkgs state module
dotdeb.repo:
pkgrepo.managed:
- humanname: Dotdeb
- name: deb http://packages.dotdeb.org wheezy-php55 all
- dist: wheezy-php55
- file: /etc/apt/sources.list.d/dotbeb.list
- keyid: 89DF5277
- keyserver: keys.gnupg.net
- refresh_db: true
php.packages:
pkg.installed:
- fromrepo: wheezy-php55
- pkgs:
- php5-fpm
- php5-cli
- php5-curl
Warning
Package names are currently case-sensitive. If the minion is using a
package manager which is not case-sensitive (such as pkgng
), then this state will fail if the proper case is not
used. This will be addressed in a future release of Salt.
salt.states.pkg.
group_installed
(name, skip=None, include=None, **kwargs)¶New in version 2015.8.0.
Changed in version Carbon: Added support in pacman
Ensure that an entire package group is installed. This state is currently
only supported for the yum
and pacman
package managers.
Packages that would normally be installed by the package group ("default" packages), which should not be installed.
Load Balancer:
pkg.group_installed:
- skip:
- piranha
Packages which are included in a group, which would not normally be
installed by a yum groupinstall
("optional" packages). Note that
this will not enforce group membership; if you include packages which
are not members of the specified groups, they will still be installed.
Load Balancer:
pkg.group_installed:
- include:
- haproxy
Changed in version 2016.3.0: This option can no longer be passed as a comma-separated list, it must now be passed as a list (as shown in the above example).
Note
Because this is essentially a wrapper around pkg.install
, any argument which can be passed to
pkg.install may also be included here, and it will be passed on to the
call to pkg.install
.
salt.states.pkg.
installed
(name, version=None, refresh=None, fromrepo=None, skip_verify=False, skip_suggestions=False, pkgs=None, sources=None, allow_updates=False, pkg_verify=False, normalize=True, ignore_epoch=False, reinstall=False, update_holds=False, **kwargs)¶Ensure that the package is installed, and that it is the correct version (if specified).
param str name: The name of the package to be installed. This parameter is ignored if either "pkgs" or "sources" is used. Additionally, please note that this option can only be used to install packages from a software repository. To install a package file manually, use the "sources" option detailed below.
param str version: Install a specific version of a package. This option is ignored if "sources" is used. Currently, this option is supported for the following pkg providers:
apt
,ebuild
,pacman
,win_pkg
,yumpkg
, andzypper
. The version number includes the release designation where applicable, to allow Salt to target a specific release of a given version. When in doubt, using thepkg.latest_version
function for an uninstalled package will tell you the version available.# salt myminion pkg.latest_version vim-enhanced myminion: 2:7.4.160-1.el7
Important
As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the
pkg.latest_version
output above) must have the epoch included when specifying the version number. For example:vim-enhanced: pkg.installed: - version: 2:7.4.160-1.el7In version 2015.8.9, an ignore_epoch argument has been added to
pkg.installed
,pkg.removed
, andpkg.purged
states, which causes the epoch to be disregarded when the state checks to see if the desired version was installed.Also, while this function is not yet implemented for all pkg frontends,
pkg.list_repo_pkgs
will show all versions available in the various repositories for a given package, irrespective of whether or not it is installed.# salt myminion pkg.list_repo_pkgs httpd myminion: ---------- base: |_ ---------- httpd: 2.2.15-29.el6.centos updates: |_ ---------- httpd: 2.2.15-30.el6.centos
The version strings returned by either of these functions can be used as version specifiers in pkg states.
You can install a specific version when using the
pkgs
argument by including the version after the package:common_packages: pkg.installed: - pkgs: - unzip - dos2unix - salt-minion: 2015.8.5-1.el6param bool refresh: This parameter controls whether or not the packge repo database is updated prior to installing the requested package(s).
If
True
, the package database will be refreshed (apt-get update
or equivalent, depending on platform) before installing.If
False
, the package database will not be refreshed before installing.If unset, then Salt treats package database refreshes differently depending on whether or not a
pkg
state has been executed already during the current Salt run. Once a refresh has been performed in apkg
state, for the remainder of that Salt run no other refreshes will be performed forpkg
states which do not explicitly setrefresh
toTrue
. This prevents needless additional refreshes from slowing down the Salt run.param str fromrepo: Specify a repository from which to install
Note
Distros which use APT (Debian, Ubuntu, etc.) do not have a concept of repositories, in the same way as YUM-based distros do. When a source is added, it is assigned to a given release. Consider the following source configuration:
deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise mainThe packages provided by this source would be made available via the
precise
release, thereforefromrepo
would need to be set toprecise
for Salt to install the package from this source.Having multiple sources in the same release may result in the default install candidate being newer than what is desired. If this is the case, the desired version must be specified using the
version
parameter.If the
pkgs
parameter is being used to install multiple packages in the same state, then instead of usingversion
, use the method of version specification described in the Multiple Package Installation Options section below.Running the shell command
apt-cache policy pkgname
on a minion can help elucidate the APT configuration and aid in properly configuring states:root@saltmaster:~# salt ubuntu01 cmd.run 'apt-cache policy ffmpeg' ubuntu01: ffmpeg: Installed: (none) Candidate: 7:0.10.11-1~precise1 Version table: 7:0.10.11-1~precise1 0 500 http://ppa.launchpad.net/jon-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages 4:0.8.10-0ubuntu0.12.04.1 0 500 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main amd64 Packages 500 http://security.ubuntu.com/ubuntu/ precise-security/main amd64 Packages 4:0.8.1-0ubuntu1 0 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 PackagesThe release is located directly after the source's URL. The actual release name is the part before the slash, so to install version 4:0.8.10-0ubuntu0.12.04.1 either
precise-updates
orprecise-security
could be used for thefromrepo
value.param bool skip_verify: Skip the GPG verification check for the package to be installed
param bool skip_suggestions: Force strict package naming. Disables lookup of package alternatives.
New in version 2014.1.1.
param bool allow_updates: Allow the package to be updated outside Salt's control (e.g. auto updates on Windows). This means a package on the Minion can have a newer version than the latest available in the repository without enforcing a re-installation of the package.
New in version 2014.7.0.
Example:
httpd: pkg.installed: - fromrepo: mycustomrepo - skip_verify: True - skip_suggestions: True - version: 2.0.6~ubuntu3 - refresh: True - allow_updates: True - hold: Falseparam bool pkg_verify: New in version 2014.7.0.
For requested packages that are already installed and would not be targeted for upgrade or downgrade, use pkg.verify to determine if any of the files installed by the package have been altered. If files have been altered, the reinstall option of pkg.install is used to force a reinstall. Types to ignore can be passed to pkg.verify. Additionally,
verify_options
can be used to modify further the behavior of pkg.verify. See examples below. Currently, this option is supported for the following pkg providers:yumpkg
.Examples:
httpd: pkg.installed: - version: 2.2.15-30.el6.centos - pkg_verify: Truemypkgs: pkg.installed: - pkgs: - foo - bar: 1.2.3-4 - baz - pkg_verify: - ignore_types: - config - docmypkgs: pkg.installed: - pkgs: - foo - bar: 1.2.3-4 - baz - pkg_verify: - ignore_types: - config - doc - verify_options: - nodeps - nofiledigestparam list ignore_types: List of types to ignore when verifying the package
New in version 2014.7.0.
param list verify_options: List of additional options to pass when verifying the package. These options will be added to the
rpm -V
command, prepended with--
(for example, whennodeps
is passed in this option,rpm -V
will be run with--nodeps
).New in version Carbon.
param bool normalize: Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version.
New in version 2014.7.0.
Example:
gpfs.gplbin-2.6.32-279.31.1.el6.x86_64: pkg.installed: - normalize: Falseparam bool ignore_epoch: When a package version contains an non-zero epoch (e.g.
1:3.14.159-2.el7
, and a specific version of a package is desired, set this option toTrue
to ignore the epoch when comparing versions. This allows for the following SLS to be used:# Actual vim-enhanced version: 2:7.4.160-1.el7 vim-enhanced: pkg.installed: - version: 7.4.160-1.el7 - ignore_epoch: TrueWithout this option set to
True
in the above example, the package would be installed, but the state would report as failed because the actual installed version would be2:7.4.160-1.el7
. Alternatively, this option can be left asFalse
and the full version string (with epoch) can be specified in the SLS file:vim-enhanced: pkg.installed: - version: 2:7.4.160-1.el7New in version 2015.8.9.
MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)
param list pkgs: A list of packages to install from a software repository. All packages listed under
pkgs
will be installed via a single command.Example:
mypkgs: pkg.installed: - pkgs: - foo - bar - baz - hold: True
NOTE:
Forapt
,ebuild
,pacman
,yumpkg
, andzypper
, version numbers can be specified in thepkgs
argument. For example:mypkgs: pkg.installed: - pkgs: - foo - bar: 1.2.3-4 - bazAdditionally,
ebuild
,pacman
andzypper
support the<
,<=
,>=
, and>
operators for more control over what versions will be installed. ForExample:
mypkgs: pkg.installed: - pkgs: - foo - bar: '>=1.2.3-4' - baz
NOTE:
When using comparison operators, the expression must be enclosed in quotes to avoid a YAML render error.With
ebuild
is also possible to specify a use flag list and/or if the given packages should be in package.accept_keywords file and/or the overlay from which you want the package to be installed.For example:
mypkgs: pkg.installed: - pkgs: - foo: '~' - bar: '~>=1.2:slot::overlay[use,-otheruse]' - bazparam list sources: A list of packages to install, along with the source URI or local path from which to install each package. In the example below,
foo
,bar
,baz
, etc. refer to the name of the package, as it would appear in the output of thepkg.version
orpkg.list_pkgs
salt CLI commands.mypkgs: pkg.installed: - sources: - foo: salt://rpms/foo.rpm - bar: http://somesite.org/bar.rpm - baz: ftp://someothersite.org/baz.rpm - qux: /minion/path/to/qux.rpmPLATFORM-SPECIFIC ARGUMENTS
These are specific to each OS. If it does not apply to the execution module for your OS, it is ignored.
param bool hold: Force the package to be held at the current installed version. Currently works with YUM/DNF & APT based systems.
New in version 2014.7.0.
param bool update_holds: If
True
, and this function would update the package version, any packages which are being held will be temporarily unheld so that they can be updated. Otherwise, if this function attempts to update a held package, the held package(s) will be skipped and the state will fail. By default, this parameter is set toFalse
.This option is currently supported only for YUM/DNF.
New in version Carbon.
param list names: A list of packages to install from a software repository. Each package will be installed individually by the package manager.
Warning
Unlike
pkgs
, thenames
parameter cannot specify a version. In addition, it makes a separate call to the package management frontend to install each package, whereaspkgs
makes just a single call. It is therefore recommended to usepkgs
instead ofnames
to install multiple packages, both for the additional features and the performance improvement that it brings.param bool install_recommends: Whether to install the packages marked as recommended. Default is
True
. Currently only works with APT-based systems.New in version 2015.5.0.
httpd: pkg.installed: - install_recommends: Falseparam bool only_upgrade: Only upgrade the packages, if they are already installed. Default is
False
. Currently only works with APT-based systems.New in version 2015.5.0.
httpd: pkg.installed: - only_upgrade: TrueNote
If this parameter is set to True and the package is not already installed, the state will fail.
Parameters: | report_reboot_exit_codes (bool) --
Note The You should only use |
---|
salt.states.pkg.
latest
(name, refresh=None, fromrepo=None, skip_verify=False, pkgs=None, watch_flags=True, **kwargs)¶Ensure that the named package is installed and the latest available package. If the package can be updated, this state function will update the package. Generally it is better for the
installed
function to be used, aslatest
will update the package whenever a new package is available.
- name
- The name of the package to maintain at the latest available version. This parameter is ignored if "pkgs" is used.
- fromrepo
- Specify a repository from which to install
- skip_verify
- Skip the GPG verification check for the package to be installed
- refresh
This parameter controls whether or not the packge repo database is updated prior to checking for the latest available version of the requested packages.
If
True
, the package database will be refreshed (apt-get update
or equivalent, depending on platform) before checking for the latest available version of the requested packages.If
False
, the package database will not be refreshed before checking.If unset, then Salt treats package database refreshes differently depending on whether or not a
pkg
state has been executed already during the current Salt run. Once a refresh has been performed in apkg
state, for the remainder of that Salt run no other refreshes will be performed forpkg
states which do not explicitly setrefresh
toTrue
. This prevents needless additional refreshes from slowing down the Salt run.Multiple Package Installation Options:
(Not yet supported for: FreeBSD, OpenBSD, MacOS, and Solaris pkgutil)
- pkgs
- A list of packages to maintain at the latest available version.
mypkgs: pkg.latest: - pkgs: - foo - bar - baz
- install_recommends
Whether to install the packages marked as recommended. Default is
True
. Currently only works with APT-based systems.New in version 2015.5.0.
httpd: pkg.latest: - install_recommends: False
- only_upgrade
Only upgrade the packages, if they are already installed. Default is
False
. Currently only works with APT-based systems.New in version 2015.5.0.
httpd: pkg.latest: - only_upgrade: TrueNote
If this parameter is set to True and the package is not already installed, the state will fail.
If the installer exits with a recognized exit code indicating that a reboot is required, the module function
win_system.set_reboot_required_witnessed
will be called, preserving the knowledge of this event
for the remainder of the current boot session. For the time being,
3010
is the only recognized exit code, but this
is subject to future refinement. The value of this param
defaults to True
. This paramater has no effect on
non-Windows systems.
New in version Carbon.
ms vcpp installed:
pkg.latest:
- name: ms-vcpp
- report_reboot_exit_codes: False
salt.states.pkg.
mod_aggregate
(low, chunks, running)¶The mod_aggregate function which looks up all packages in the available low chunks and merges them into a single pkgs ref in the present low data
salt.states.pkg.
mod_watch
(name, **kwargs)¶Install/reinstall a package based on a watch requisite
salt.states.pkg.
purged
(name, version=None, pkgs=None, normalize=True, ignore_epoch=False, **kwargs)¶Verify that a package is not installed, calling pkg.purge
if necessary
to purge the package. All configuration files are also removed.
The version of the package that should be removed. Don't do anything if the package is installed with an unmatching version.
Important
As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the example above) must have the epoch included when specifying the version number. For example:
vim-enhanced:
pkg.installed:
- version: 2:7.4.160-1.el7
In version 2015.8.9, an ignore_epoch argument has been added to
pkg.installed
,
pkg.removed
, and
pkg.purged
states, which
causes the epoch to be disregarded when the state checks to see if
the desired version was installed. If ignore_epoch was not set
to True
, and instead of 2:7.4.160-1.el7
a version of
7.4.160-1.el7
were used, this state would report success since
the actual installed version includes the epoch, and the specified
version would not match.
Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version.
New in version 2015.8.0.
When a package version contains an non-zero epoch (e.g.
1:3.14.159-2.el7
, and a specific version of a package is desired,
set this option to True
to ignore the epoch when comparing
versions. This allows for the following SLS to be used:
# Actual vim-enhanced version: 2:7.4.160-1.el7
vim-enhanced:
pkg.purged:
- version: 7.4.160-1.el7
- ignore_epoch: True
Without this option set to True
in the above example, the state
would falsely report success since the actual installed version is
2:7.4.160-1.el7
. Alternatively, this option can be left as
False
and the full version string (with epoch) can be specified in
the SLS file:
vim-enhanced:
pkg.purged:
- version: 2:7.4.160-1.el7
New in version 2015.8.9.
Multiple Package Options:
name
parameter will be ignored if this option is passed. It accepts
version numbers as well.New in version 0.16.0.
salt.states.pkg.
removed
(name, version=None, pkgs=None, normalize=True, ignore_epoch=False, **kwargs)¶Verify that a package is not installed, calling pkg.remove
if necessary
to remove the package.
The version of the package that should be removed. Don't do anything if the package is installed with an unmatching version.
Important
As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the example above) must have the epoch included when specifying the version number. For example:
vim-enhanced:
pkg.installed:
- version: 2:7.4.160-1.el7
In version 2015.8.9, an ignore_epoch argument has been added to
pkg.installed
,
pkg.removed
, and
pkg.purged
states, which
causes the epoch to be disregarded when the state checks to see if
the desired version was installed. If ignore_epoch was not set
to True
, and instead of 2:7.4.160-1.el7
a version of
7.4.160-1.el7
were used, this state would report success since
the actual installed version includes the epoch, and the specified
version would not match.
Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version.
New in version 2015.8.0.
When a package version contains an non-zero epoch (e.g.
1:3.14.159-2.el7
, and a specific version of a package is desired,
set this option to True
to ignore the epoch when comparing
versions. This allows for the following SLS to be used:
# Actual vim-enhanced version: 2:7.4.160-1.el7
vim-enhanced:
pkg.removed:
- version: 7.4.160-1.el7
- ignore_epoch: True
Without this option set to True
in the above example, the state
would falsely report success since the actual installed version is
2:7.4.160-1.el7
. Alternatively, this option can be left as
False
and the full version string (with epoch) can be specified in
the SLS file:
vim-enhanced:
pkg.removed:
- version: 2:7.4.160-1.el7
New in version 2015.8.9.
Multiple Package Options:
A list of packages to remove. Must be passed as a python list. The
name
parameter will be ignored if this option is passed. It accepts
version numbers as well.
New in version 0.16.0.
salt.states.pkg.
uptodate
(name, refresh=False, **kwargs)¶New in version 2014.7.0.
Verify that the system is completely up to date.
Any keyword arguments to pass through to pkg.upgrade
.
New in version 2015.5.0.