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).
Note
Any argument which is either a) not explicitly defined for this state,
or b) not a global state argument like saltenv, or
reload_modules, will be passed through to the call to
pkg.install to download the package(s). For example, you can include
a disablerepo argument on platforms that use yum/dnf to disable
that repo:
mypkg:
pkg.downloaded:
- disablerepo: base,updates
To see what is supported, check this page to find
the documentation for your platform's pkg module, then look at the
documentation for the install function.
Any argument that is passed through to the install function, which
is not defined for that function, will be silently ignored.
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=None, reinstall=False, update_holds=False, **kwargs)¶Ensure that the package is installed, and that it is the correct version (if specified).
Note
Any argument which is either a) not explicitly defined for this state,
or b) not a global state argument like saltenv, or
reload_modules, will be passed through to the call to
pkg.install to install the package(s). For example, you can include
a disablerepo argument on platforms that use yum/dnf to disable
that repo:
mypkg:
pkg.installed:
- disablerepo: base,updates
To see what is supported, check this page to find
the documentation for your platform's pkg module, then look at the
documentation for the install function.
Any argument that is passed through to the install function, which
is not defined for that function, will be silently ignored.
| 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
If running pkg commands together with aggregate isn't an option, you can use the creates, 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 creates for a simple single-factor check
install_nginx:
pkg.installed:
- name: nginx
- creates:
- /etc/nginx/nginx.conf
# 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 unless with a shell test
install_nginx:
pkg.installed:
- name: nginx
- unless: test -f /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 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, creates/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, as latest will update the package
whenever a new package is available.
Note
Any argument which is either a) not explicitly defined for this state,
or b) not a global state argument like saltenv, or
reload_modules, will be passed through to the call to
pkg.install to install the package(s). For example, you can include
a disablerepo argument on platforms that use yum/dnf to disable
that repo:
mypkg:
pkg.latest:
- disablerepo: base,updates
To see what is supported, check this page to find
the documentation for your platform's pkg module, then look at the
documentation for the install function.
Any argument that is passed through to the install function, which
is not defined for that function, will be silently ignored.
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 a
pkg state, for the remainder of that Salt run no other refreshes
will be performed for pkg states which do not explicitly set
refresh to True. This prevents needless additional refreshes
from slowing down the Salt run.
| Parameters: |
|
|---|
Multiple Package Installation Options:
(Not yet supported for: FreeBSD, OpenBSD, MacOS, and Solaris pkgutil)
mypkgs:
pkg.latest:
- pkgs:
- foo
- bar
- baz
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 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: True
Note
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_beacon(name, **kwargs)¶Create a beacon to monitor a package or packages based on a beacon state argument.
Note
This state exists to support special handling of the beacon
state argument for supported state functions. It should not be called directly.
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.
Note
Any argument which is either a) not explicitly defined for this state,
or b) not a global state argument like saltenv, or
reload_modules, will be passed through to the call to
pkg.install to install the patch(es).
To see what is supported, check this page to find
the documentation for your platform's pkg module, then look at the
documentation for the install function.
Any argument that is passed through to the install function, which
is not defined for that function, will be silently ignored.
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=None, **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.
If this option is not explicitly set, and there is no epoch in the
desired package version, the epoch will be implicitly ignored. Set this
argument to True to explicitly ignore the epoch, and False to
strictly enforce it.
New in version 2015.8.9.
Changed in version 3001: In prior releases, the default behavior was to strictly enforce
epochs unless this argument was set to True.
Multiple Package Options:
A list of packages to purge. 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.removed(name, version=None, pkgs=None, normalize=True, ignore_epoch=None, **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.
If this option is not explicitly set, and there is no epoch in the
desired package version, the epoch will be implicitly ignored. Set this
argument to True to explicitly ignore the epoch, and False to
strictly enforce it.
New in version 2015.8.9.
Changed in version 3001: In prior releases, the default behavior was to strictly enforce
epochs unless this argument was set to True.
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: 3004.1