Note
On minions running systemd>=205, as of version 2015.8.12, 2016.3.3, and
2016.11.0, systemd-run(1) is now used to isolate commands which modify
installed packages from the salt-minion
daemon's control group. This is
done to keep systemd from killing the package manager commands spawned by
Salt, when Salt updates itself (see KillMode
in the systemd.kill(5)
manpage for more information). If desired, usage of systemd-run(1) can
be suppressed by setting a config option
called systemd.use_scope
, with a value of False
(no quotes).
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:
- 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:
- 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.
downloaded
(name, version=None, pkgs=None, fromrepo=None, ignore_epoch=None, **kwargs)¶New in version 2017.7.0.
Ensure that the package is downloaded, and that it is the correct version (if specified).
Currently supported for the following pkg providers:
yumpkg
, zypper
and zypper
Parameters: |
|
---|
CLI Example:
zsh:
pkg.downloaded:
- version: 5.0.5-4.63
- fromrepo: "myrepository"
salt.states.pkg.
group_installed
(name, skip=None, include=None, **kwargs)¶New in version 2015.8.0.
Changed in version 2016.11.0: 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).
Parameters: |
|
---|
MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)
Parameters: |
|
---|
PLATFORM-SPECIFIC ARGUMENTS
These are specific to each OS. If it does not apply to the execution module for your OS, it is ignored.
Parameters: |
|
---|---|
Returns: | A dictionary containing the state of the software installation |
Rtype dict: |
Note
The pkg.installed
state supports the usage of reload_modules
.
This functionality allows you to force Salt to reload all modules. In
many cases, Salt is clever enough to transparently reload the modules.
For example, if you install a package, Salt reloads modules because some
other module or state might require the package which was installed.
However, there are some edge cases where this may not be the case, which
is what reload_modules
is meant to resolve.
You should only use reload_modules
if your pkg.installed
does some
sort of installation where if you do not reload the modules future items
in your state which rely on the software being installed will fail. Please
see the Reloading Modules documentation for more
information.
See also
unless and onlyif
You can use the unless or onlyif syntax to skip a full package run. This can be helpful in large environments with multiple states that include requisites for packages to be installed.
# Using file.file_exists for a single-factor check
install_nginx:
pkg.installed:
- name: nginx
- unless:
- fun: file.file_exists
args:
- /etc/nginx/nginx.conf
# Using file.search for a two-factor check
install_nginx:
pkg.installed:
- name: nginx
- unless:
- fun: file.search
args:
- /etc/nginx/nginx.conf
- 'user www-data;'
The above examples use two different methods to reasonably ensure
that a package has already been installed. First, with checking for a
file that would be created with the package. Second, by checking for
specific text within a file that would be created or managed by salt.
With these requisists satisfied, unless will return True
and the
pkg.installed
state will be skipped.
# Example of state run without unless used
salt 'saltdev' state.apply nginx
saltdev:
----------
ID: install_nginx
Function: pkg.installed
Name: nginx
Result: True
Comment: All specified packages are already installed
Started: 20:11:56.388331
Duration: 4290.0 ms
Changes:
# Example of state run using unless requisite
salt 'saltdev' state.apply nginx
saltdev:
----------
ID: install_nginx
Function: pkg.installed
Name: nginx
Result: True
Comment: unless condition is true
Started: 20:10:50.659215
Duration: 1530.0 ms
Changes:
The result is a reduction of almost 3 seconds. In larger environments, small reductions in waiting time can add up.
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 package 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.
param str cache_valid_time: New in version 2016.11.0.
This parameter sets the value in seconds after which the cache is marked as invalid, and a cache update is necessary. This overwrites the
refresh
parameter's default behavior.Example:
httpd: pkg.latest: - refresh: True - cache_valid_time: 300In this case, a refresh will not take place for 5 minutes since the last
apt-get update
was executed on the system.Note
This parameter is available only on Debian based distributions and has no effect on the rest.
param bool resolve_capabilities: Turn on resolving capabilities. This allow one to name "provides" or alias names for packages.
New in version 2018.3.0.
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 parameter has no effect on
non-Windows systems.
New in version 2016.11.0.
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
Note
This state exists to support special handling of the watch
requisite. It should not be called directly.
Parameters for this function should be set by the state being triggered.
salt.states.pkg.
patch_downloaded
(name, advisory_ids=None, **kwargs)¶New in version 2017.7.0.
Ensure that packages related to certain advisory ids are downloaded.
Currently supported for the following pkg providers:
yumpkg
and zypper
CLI Example:
preparing-to-fix-issues:
pkg.patch_downloaded:
- advisory_ids:
- SUSE-SLE-SERVER-12-SP2-2017-185
- SUSE-SLE-SERVER-12-SP2-2017-150
- SUSE-SLE-SERVER-12-SP2-2017-120
salt.states.pkg.
patch_installed
(name, advisory_ids=None, downloadonly=None, **kwargs)¶New in version 2017.7.0.
Ensure that packages related to certain advisory ids are installed.
Currently supported for the following pkg providers:
yumpkg
and zypper
CLI Example:
issue-foo-fixed:
pkg.patch_installed:
- advisory_ids:
- SUSE-SLE-SERVER-12-SP2-2017-185
- SUSE-SLE-SERVER-12-SP2-2017-150
- SUSE-SLE-SERVER-12-SP2-2017-120
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.purged:
- 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.removed:
- 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, pkgs=None, **kwargs)¶New in version 2014.7.0.
Changed in version 2018.3.0: Added support for the pkgin
provider.
Verify that the system is completely up to date.
Parameters: |
|
---|
Any keyword arguments to pass through to pkg.upgrade
.
New in version 2015.5.0.
Docs for previous releases are available on readthedocs.org.
Latest Salt release: latest_release