Support for YUM/DNF
Important
If you feel that Salt should be using this module to manage packages on a minion, and it is using a different module (or gives an error similar to 'pkg.install' is not available), see here.
Note
DNF is fully supported as of version 2015.5.10 and 2015.8.4 (partial support for DNF was initially added in 2015.8.0), and DNF is used automatically in place of YUM in Fedora 22 and newer.
salt.modules.yumpkg.AvailablePackages(*args, **kwargs)
New in version 2014.1.0.
Cleans local yum metadata. Functionally identical to refresh_db().
CLI Example:
salt '*' pkg.clean_metadata
Delete a repo from <basedir> (default basedir: all dirs in reposdir yum option).
If the .repo file in which the repo exists does not contain any other repo configuration, the file itself will be deleted.
CLI Examples:
salt '*' pkg.del_repo myrepo salt '*' pkg.del_repo myrepo basedir=/path/to/dir salt '*' pkg.del_repo myrepo basedir=/path/to/dir,/path/to/another/dir
Return a formatted diff between current files and original in a package. NOTE: this function includes all files (configuration and not), but does not work on binary content.
| Parameters: | path -- Full path to the installed file |
|---|---|
| Returns: | Difference string or raises and exception if examined file is binary. |
CLI example:
salt '*' pkg.diff /etc/apache2/httpd.conf /etc/sudoers
New in version 2015.5.0.
Download packages to the local disk. Requires yumdownloader from yum-utils package.
Note
yum-utils will already be installed on the minion if the package was installed from the Fedora / EPEL repositories.
CLI example:
salt '*' pkg.download httpd salt '*' pkg.download httpd postfix
New in version 2014.1.0.
List the files that belong to a package, grouped by package. Not specifying any packages will return a list of every file on the system's rpm database (not generally recommended).
CLI Examples:
salt '*' pkg.file_list httpd salt '*' pkg.file_list httpd postfix salt '*' pkg.file_list
New in version 2014.1.0.
List the files that belong to a package. Not specifying any packages will return a list of every file on the system's rpm database (not generally recommended).
CLI Examples:
salt '*' pkg.file_list httpd salt '*' pkg.file_list httpd postfix salt '*' pkg.file_list
Display a repo from <basedir> (default basedir: all dirs in reposdir yum option).
CLI Examples:
salt '*' pkg.get_repo myrepo salt '*' pkg.get_repo myrepo basedir=/path/to/dir salt '*' pkg.get_repo myrepo basedir=/path/to/dir,/path/to/another/dir
New in version 2014.1.0.
Changed in version 2016.3.0,2015.8.4,2015.5.10: Environment groups are now supported. The key names have been renamed, similar to the changes made in pkg.group_info.
Lists which of a group's packages are installed and which are not installed
CLI Example:
salt '*' pkg.group_diff 'Perl Support'
New in version 2014.1.0.
Changed in version 2016.3.0,2015.8.4,2015.5.10: The return data has changed. A new key type has been added to distinguish environment groups from package groups. Also, keys for the group name and group ID have been added. The mandatory packages, optional packages, and default packages keys have been renamed to mandatory, optional, and default for accuracy, as environment groups include other groups, and not packages. Finally, this function now properly identifies conditional packages.
Lists packages belonging to a certain group
If the specified group is an environment group, then the group will be expanded and the return data will include package names instead of group names.
New in version 2016.3.0.
CLI Example:
salt '*' pkg.group_info 'Perl Support'
New in version 2014.1.0.
Install the passed package group(s). This is basically a wrapper around pkg.install, which performs package group resolution for the user. This function is currently considered experimental, and should be expected to undergo changes.
Package group to install. To install more than one group, either use a comma-separated list or pass the value as a python list.
CLI Examples:
salt '*' pkg.group_install 'Group 1'
salt '*' pkg.group_install 'Group 1,Group 2'
salt '*' pkg.group_install '["Group 1", "Group 2"]'
Packages that would normally be installed by the package group ("default" packages), which should not be installed. Can be passed either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' skip='foo,bar'
salt '*' pkg.group_install 'My Group' skip='["foo", "bar"]'
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. Can be passed either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' include='foo,bar'
salt '*' pkg.group_install 'My Group' include='["foo", "bar"]'
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 along wholesale.
New in version 2014.1.0.
Lists all groups known by yum on this system
CLI Example:
salt '*' pkg.group_list
New in version 2014.7.0.
Version-lock packages
Note
Requires the appropriate versionlock plugin package to be installed:
yum-versionlock
yum-plugin-versionlock
python-dnf-plugins-extras-versionlock
Multiple Package Options:
name parameter will be ignored if this option is passed.Returns a dict containing the changes.
CLI Example:
salt '*' pkg.hold <package name> salt '*' pkg.hold pkgs='["foo", "bar"]'
New in version 2015.8.1.
Return the information of the named package(s), installed on the system.
| Parameters: | all_versions -- Include information for all versions of the packages installed on the minion. |
|---|
CLI example:
salt '*' pkg.info_installed <package1> salt '*' pkg.info_installed <package1> <package2> <package3> ... salt '*' pkg.info_installed <package1> <package2> <package3> all_versions=True
Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, 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 any yum/dnf commands spawned by Salt when the salt-minion service is restarted. (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.scope, with a value of False (no quotes).
Install the passed package(s), add refresh=True to clean the yum database before package is installed.
The name of the package to be installed. Note that this parameter is ignored if either "pkgs" or "sources" is passed. 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.
32-bit packages can be installed on 64-bit systems by appending the architecture designation (.i686, .i586, etc.) to the end of the package name.
CLI Example:
salt '*' pkg.install <package name>
Specifying reinstall=True will use yum reinstall rather than yum install for requested packages that are already installed.
If a version is specified with the requested package, then yum reinstall will only be used if the installed version matches the requested version.
Works with sources when the package header of the source can be matched to the name and version of an installed package.
New in version 2014.7.0.
--nogpgcheck)Install a specific version of the package, e.g. 1.2.3-4.el5. Ignored if "pkgs" or "sources" is passed.
Changed in version 2018.3.0: version can now contain comparison operators (e.g. >1.2.3, <=2.0, etc.)
If True, and this function would update the package version, any packages held using the yum/dnf "versionlock" plugin will be 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 an error will be raised.
New in version 2016.11.0.
A comma-separated or Python list of key=value options. This list will be expanded and --setopt prepended to each in the yum/dnf command that is run.
CLI Example:
salt '*' pkg.install foo setopt='obsoletes=0,plugins=0'
New in version 2019.2.0.
Repository Options:
yum --disablerepo='*' --enablerepo='somerepo')fromrepo is specified)yum --enablerepo='somerepo')fromrepo is specified)yum --disablerepo='somerepo')Disable exclude from main, for a repo or for everything. (e.g., yum --disableexcludes='main')
New in version 2014.7.0.
Only used when the version of a package is specified using a comparison operator (e.g. >4.1). If set to True, then the epoch will be ignored when comparing the currently-installed version to the desired version.
New in version 2018.3.0.
Multiple Package Installation Options:
A list of packages to install from a software repository. Must be passed as a python list. A specific version number can be specified by using a single-element dict representing the package and its version.
CLI Examples:
salt '*' pkg.install pkgs='["foo", "bar"]'
salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4.el5"}]'
A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.
CLI Example:
salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]'
Normalize the package name by removing the architecture. This is useful for poorly created packages which might include the architecture as an actual part of the name such as kernel modules which match a specific kernel version.
salt -G role:nsd pkg.install gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False
New in version 2014.7.0.
If a list of package attributes is specified, returned value will contain them, eg.:
{'<package>': {
'old': {
'version': '<old-version>',
'arch': '<old-arch>'},
'new': {
'version': '<new-version>',
'arch': '<new-arch>'}}} Valid attributes are: epoch, version, release, arch, install_date, install_date_time_t.
If all is specified, all valid attributes will be returned.
New in version 2018.3.0.
Returns a dict containing the new package names and versions:
{'<package>': {'old': '<old-version>',
'new': '<new-version>'}} If an attribute list in diff_attr is specified, the dict will also contain any specified attribute, eg.:
{'<package>': {
'old': {
'version': '<old-version>',
'arch': '<old-arch>'},
'new': {
'version': '<new-version>',
'arch': '<new-arch>'}}} Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.
If the latest version of a given package is already installed, an empty string will be returned for that package.
A specific repo can be requested using the fromrepo keyword argument, and the disableexcludes option is also supported.
New in version 2014.7.0: Support for the disableexcludes option
CLI Example:
salt '*' pkg.latest_version <package name> salt '*' pkg.latest_version <package name> fromrepo=epel-testing salt '*' pkg.latest_version <package name> disableexcludes=main salt '*' pkg.latest_version <package1> <package2> <package3> ...
New in version 2017.7.0.
List prefetched packages downloaded by Yum in the local disk.
CLI example:
salt '*' pkg.list_downloaded
Changed in version 2016.3.0,2015.8.4,2015.5.10: Function renamed from pkg.get_locked_pkgs to pkg.list_holds.
List information on locked packages
Note
Requires the appropriate versionlock plugin package to be installed:
yum-versionlock
yum-plugin-versionlock
python-dnf-plugins-extras-versionlock
False to return just the name of the package(s) being held.CLI Example:
salt '*' pkg.list_holds salt '*' pkg.list_holds full=False
New in version 2017.7.0.
List installed advisory patches on the system.
CLI Examples:
salt '*' pkg.list_installed_patches
New in version 2017.7.0.
List all known advisory patches from available repos.
CLI Examples:
salt '*' pkg.list_patches
List the packages currently installed as a dict. By default, the dict contains versions as a comma separated string:
{'<package_name>': '<version>[,<version>...]'} If set to true, the versions are provided as a list
{'<package_name>': ['<version>', '<version>']}
If a list of package attributes is specified, returned value will contain them in addition to version, eg.:
{'<package_name>': [{'version' : 'version', 'arch' : 'arch'}]} Valid attributes are: epoch, version, release, arch, install_date, install_date_time_t.
If all is specified, all valid attributes will be returned.
New in version 2018.3.0.
CLI Example:
salt '*' pkg.list_pkgs salt '*' pkg.list_pkgs attr=version,arch salt '*' pkg.list_pkgs attr='["version", "arch"]'
New in version 2014.1.0.
Changed in version 2014.7.0: All available versions of each package are now returned. This required a slight modification to the structure of the return dict. The return data shown below reflects the updated return dict structure. Note that packages which are version-locked using pkg.hold will only show the currently-installed version, as locking a package will make other versions appear unavailable to yum/dnf.
Changed in version 2017.7.0: By default, the versions for each package are no longer organized by repository. To get results organized by repository, use byrepo=True.
Returns all available packages. Optionally, package names (and name globs) can be passed and the results will be filtered to packages matching those names. This is recommended as it speeds up the function considerably.
Warning
Running this function on RHEL/CentOS 6 and earlier will be more resource-intensive, as the version of yum that ships with older RHEL/CentOS has no yum subcommand for listing packages from a repository. Thus, a yum list installed and yum list available are run, which generates a lot of output, which must then be analyzed to determine which package information to include in the return data.
This function can be helpful in discovering the version or repo to specify in a pkg.installed state.
The return data will be a dictionary mapping package names to a list of version numbers, ordered from newest to oldest. If byrepo is set to True, then the return dictionary will contain repository names at the top level, and each repository will map packages to lists of version numbers. For example:
# With byrepo=False (default)
{
'bash': ['4.1.2-15.el6_5.2',
'4.1.2-15.el6_5.1',
'4.1.2-15.el6_4'],
'kernel': ['2.6.32-431.29.2.el6',
'2.6.32-431.23.3.el6',
'2.6.32-431.20.5.el6',
'2.6.32-431.20.3.el6',
'2.6.32-431.17.1.el6',
'2.6.32-431.11.2.el6',
'2.6.32-431.5.1.el6',
'2.6.32-431.3.1.el6',
'2.6.32-431.1.2.0.1.el6',
'2.6.32-431.el6']
}
# With byrepo=True
{
'base': {
'bash': ['4.1.2-15.el6_4'],
'kernel': ['2.6.32-431.el6']
},
'updates': {
'bash': ['4.1.2-15.el6_5.2', '4.1.2-15.el6_5.1'],
'kernel': ['2.6.32-431.29.2.el6',
'2.6.32-431.23.3.el6',
'2.6.32-431.20.5.el6',
'2.6.32-431.20.3.el6',
'2.6.32-431.17.1.el6',
'2.6.32-431.11.2.el6',
'2.6.32-431.5.1.el6',
'2.6.32-431.3.1.el6',
'2.6.32-431.1.2.0.1.el6']
}
} fromrepo is specified)Specify a disabled package repository (or repositories) to enable. (e.g., yum --enablerepo='somerepo')
New in version 2017.7.0.
fromrepo is specified)Specify an enabled package repository (or repositories) to disable. (e.g., yum --disablerepo='somerepo')
New in version 2017.7.0.
When True, the return data for each package will be organized by repository.
New in version 2017.7.0.
When True, the repo information will be retrieved from the cached repo metadata. This is equivalent to passing the -C option to yum/dnf.
New in version 2017.7.0.
A comma-separated or Python list of key=value options. This list will be expanded and --setopt prepended to each in the yum/dnf command that is run.
New in version 2019.2.0.
CLI Examples:
salt '*' pkg.list_repo_pkgs salt '*' pkg.list_repo_pkgs foo bar baz salt '*' pkg.list_repo_pkgs 'samba4*' fromrepo=base,updates salt '*' pkg.list_repo_pkgs 'python2-*' byrepo=True
Lists all repos in <basedir> (default: all dirs in reposdir yum option).
CLI Example:
salt '*' pkg.list_repos salt '*' pkg.list_repos basedir=/path/to/dir salt '*' pkg.list_repos basedir=/path/to/dir,/path/to/another/dir
Check whether or not an upgrade is available for all packages
The fromrepo, enablerepo, and disablerepo arguments are supported, as used in pkg states, and the disableexcludes option is also supported.
New in version 2014.7.0: Support for the disableexcludes option
CLI Example:
salt '*' pkg.list_upgrades
Modify one or more values for a repo. If the repo does not exist, it will be created, so long as the following values are specified:
Key/Value pairs may also be removed from a repo's configuration by setting a key to a blank value. Bear in mind that a name cannot be deleted, and a baseurl can only be deleted if a mirrorlist is specified (or vice versa).
CLI Examples:
salt '*' pkg.mod_repo reponame enabled=1 gpgcheck=1 salt '*' pkg.mod_repo reponame basedir=/path/to/dir enabled=1 salt '*' pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/
List the modified files that belong to a package. Not specifying any packages will return a list of _all_ modified files on the system's RPM database.
New in version 2015.5.0.
Filtering by flags (True or False):
CLI Examples:
salt '*' pkg.modified salt '*' pkg.modified httpd salt '*' pkg.modified httpd postfix salt '*' pkg.modified httpd owner=True group=False
Strips the architecture from the specified package name, if necessary. Circumstances where this would be done include:
noarch.CLI Example:
salt '*' pkg.normalize_name zsh.x86_64
New in version 2014.7.0.
Return the name of the package that owns the file. Multiple file paths can be passed. Like pkg.version, if a single path is passed, a string will be returned, and if multiple paths are passed, a dictionary of file/package name pairs will be returned.
If the file is not owned by a package, or is not present on the minion, then an empty string will be returned for that path.
CLI Examples:
salt '*' pkg.owner /usr/bin/apachectl salt '*' pkg.owner /usr/bin/apachectl /etc/httpd/conf/httpd.conf
Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, 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 any yum/dnf commands spawned by Salt when the salt-minion service is restarted. (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.scope, with a value of False (no quotes).
Package purges are not supported by yum, this function is identical to pkg.remove.
Multiple Package Options:
name parameter will be ignored if this option is passed.New in version 0.16.0.
Returns a dict containing the changes.
CLI Example:
salt '*' pkg.purge <package name> salt '*' pkg.purge <package1>,<package2>,<package3> salt '*' pkg.purge pkgs='["foo", "bar"]'
Check the yum repos for updated packages
Returns:
True: Updates are availableFalse: An error occurredNone: No updates are availableall - disable all excludes - main - disable excludes defined in [main] in yum.conf - repoid - disable excludes defined for that repoA comma-separated or Python list of key=value options. This list will be expanded and --setopt prepended to each in the yum/dnf command that is run.
New in version 2019.2.0.
CLI Example:
salt '*' pkg.refresh_db
Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, 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 any yum/dnf commands spawned by Salt when the salt-minion service is restarted. (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.scope, with a value of False (no quotes).
Remove packages
Multiple Package Options:
name parameter will be ignored if this option is passed.New in version 0.16.0.
Returns a dict containing the changes.
CLI Example:
salt '*' pkg.remove <package name> salt '*' pkg.remove <package1>,<package2>,<package3> salt '*' pkg.remove pkgs='["foo", "bar"]'
New in version 2014.7.0.
Remove version locks
Note
Requires the appropriate versionlock plugin package to be installed:
yum-versionlock
yum-plugin-versionlock
python-dnf-plugins-extras-versionlock
Multiple Package Options:
name parameter will be ignored if this option is passed.Returns a dict containing the changes.
CLI Example:
salt '*' pkg.unhold <package name> salt '*' pkg.unhold pkgs='["foo", "bar"]'
New in version 2019.2.0.
Calls pkg.upgrade with obsoletes=False. Mirrors the CLI behavior of yum update. See pkg.upgrade for further documentation.
salt '*' pkg.update
Run a full system upgrade (a yum upgrade or dnf upgrade), or upgrade specified packages. If the packages aren't installed, they will not be installed.
Changed in version 2014.7.0.
Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, 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 any yum/dnf commands spawned by Salt when the salt-minion service is restarted. (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.scope, with a value of False (no quotes).
Changed in version 2019.2.0: Added obsoletes and minimal arguments
Returns a dictionary containing the changes:
{'<package>': {'old': '<old-version>',
'new': '<new-version>'}} CLI Example:
salt '*' pkg.upgrade salt '*' pkg.upgrade name=openssl
Repository Options:
yum --disablerepo='*' --enablerepo='somerepo')fromrepo is specified)yum --enablerepo='somerepo')fromrepo is specified)yum --disablerepo='somerepo')Disable exclude from main, for a repo or for everything. (e.g., yum --disableexcludes='main')
New in version 2014.7.
The name of the package to be upgraded. Note that this parameter is ignored if "pkgs" is passed.
32-bit packages can be upgraded on 64-bit systems by appending the architecture designation (.i686, .i586, etc.) to the end of the package name.
Warning: if you forget 'name=' and run pkg.upgrade openssl, ALL packages are upgraded. This will be addressed in next releases.
CLI Example:
salt '*' pkg.upgrade name=openssl
New in version 2016.3.0.
A list of packages to upgrade from a software repository. Must be passed as a python list. A specific version number can be specified by using a single-element dict representing the package and its version. If the package was not already installed on the system, it will not be installed.
CLI Examples:
salt '*' pkg.upgrade pkgs='["foo", "bar"]'
salt '*' pkg.upgrade pkgs='["foo", {"bar": "1.2.3-4.el5"}]' New in version 2016.3.0.
Normalize the package name by removing the architecture. This is useful for poorly created packages which might include the architecture as an actual part of the name such as kernel modules which match a specific kernel version.
salt -G role:nsd pkg.upgrade gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False
New in version 2016.3.0.
Use upgrade-minimal instead of upgrade (e.g., yum upgrade-minimal) Goes to the 'newest' package match which fixes a problem that affects your system.
salt '*' pkg.upgrade minimal=True
New in version 2019.2.0.
Controls wether yum/dnf should take obsoletes into account and remove them. If set to False yum will use update instead of upgrade and dnf will be run with --obsoletes=False
salt '*' pkg.upgrade obsoletes=False
New in version 2019.2.0.
A comma-separated or Python list of key=value options. This list will be expanded and --setopt prepended to each in the yum/dnf command that is run.
New in version 2019.2.0.
Note
To add extra arguments to the yum upgrade command, pass them as key word arguments. For arguments without assignments, pass True
salt '*' pkg.upgrade security=True exclude='kernel*'
Check whether or not an upgrade is available for a given package
CLI Example:
salt '*' pkg.upgrade_available <package name>
New in version 2014.1.0.
Runs an rpm -Va on a system, and returns the results in a dict
Pass options to modify rpm verify behavior using the verify_options keyword argument
Files with an attribute of config, doc, ghost, license or readme in the package header can be ignored using the ignore_types keyword argument
CLI Example:
salt '*' pkg.verify salt '*' pkg.verify httpd salt '*' pkg.verify 'httpd postfix' salt '*' pkg.verify 'httpd postfix' ignore_types=['config','doc'] salt '*' pkg.verify 'httpd postfix' verify_options=['nodeps','nosize']
Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.
CLI Example:
salt '*' pkg.version <package name> salt '*' pkg.version <package1> <package2> <package3> ...
New in version 2015.5.4.
Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.
Set to True to ignore the epoch when comparing versions
New in version 2015.8.10,2016.3.2.
CLI Example:
salt '*' pkg.version_cmp '0.2-001' '0.2.0.1-002'
© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.yumpkg.html