salt.modules.yumpkg¶

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

This module makes use of the repoquery utility, from the yum-utils package. This package will be installed as a dependency if salt is installed via EPEL. However, if salt has been installed using pip, or a host is being managed using salt-ssh, then as of version 2014.7.0 yum-utils will be installed automatically to satisfy this dependency.

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. For these versions, repoquery is available from the dnf-plugins-core package.

salt.modules.yumpkg.check_db(*names, **kwargs)¶

New in version 0.17.0.

Returns a dict containing the following information for each specified package:

A key found, which will be a boolean value denoting if a match was found in the package database.
If found is False, then a second key called suggestions will be present, which will contain a list of possible matches.

The fromrepo, enablerepo and disablerepo arguments are supported, as used in pkg states, and the disableexcludes option is also supported. However, in Fedora 22 and newer all of these but fromrepo is ignored.

New in version 2014.7.0: Support for the disableexcludes option

CLI Examples:

salt '*' pkg.check_db <package1> <package2> <package3>
salt '*' pkg.check_db <package1> <package2> <package3> fromrepo=epel-testing
salt '*' pkg.check_db <package1> <package2> <package3> disableexcludes=main

salt.modules.yumpkg.clean_metadata(**kwargs)¶

New in version 2014.1.0.

Cleans local yum metadata. Functionally identical to refresh_db().

CLI Example:

salt '*' pkg.clean_metadata

salt.modules.yumpkg.del_repo(repo, basedir=None, **kwargs)¶

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

salt.modules.yumpkg.diff(*paths)¶

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

salt.modules.yumpkg.download(*packages)¶

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

salt.modules.yumpkg.file_dict(*packages)¶

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

salt.modules.yumpkg.file_list(*packages)¶

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

salt.modules.yumpkg.get_repo(name, basedir=None, **kwargs)¶

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

salt.modules.yumpkg.group_diff(name)¶

New in version 2014.1.0.

Changed in version Boron,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 packages belonging to a certain group, and which are installed

CLI Example:

salt '*' pkg.group_diff 'Perl Support'

salt.modules.yumpkg.group_info(name, expand=False)¶

New in version 2014.1.0.

Changed in version Boron,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

CLI Example:

salt '*' pkg.group_info 'Perl Support'

salt.modules.yumpkg.group_install(name, skip=(), include=(), **kwargs)¶

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.

name

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"]'

skip

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"]'

include

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.

salt.modules.yumpkg.group_list()¶

New in version 2014.1.0.

Lists all groups known by yum on this system

CLI Example:

salt '*' pkg.group_list

salt.modules.yumpkg.hold(name=None, pkgs=None, sources=None, **kwargs)¶

New in version 2014.7.0.

Version-lock packages

Note

Requires the appropriate versionlock plugin package to be installed:

On RHEL 5: yum-versionlock
On RHEL 6 & 7: yum-plugin-versionlock
On Fedora: python-dnf-plugins-extras-versionlock

name: The name of the package to be held.

Multiple Package Options:

pkgs: A list of packages to hold. Must be passed as a python list. The 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"]'

salt.modules.yumpkg.info_installed(*names)¶

New in version 2015.8.1.

Return the information of the named package(s), installed on the system.

CLI example:

salt '*' pkg.info_installed <package1>
salt '*' pkg.info_installed <package1> <package2> <package3> ...

salt.modules.yumpkg.install(name=None, refresh=False, skip_verify=False, pkgs=None, sources=None, reinstall=False, normalize=True, **kwargs)¶

Changed in version 2015.8.12,2016.3.3,Carbon: 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.

name

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>

refresh

Whether or not to update the yum database before executing.

reinstall

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.

skip_verify

Skip the GPG verification check (e.g., --nogpgcheck)

version

Install a specific version of the package, e.g. 1.2.3-4.el5. Ignored if "pkgs" or "sources" is passed.

Repository Options:

fromrepo: Specify a package repository (or repositories) from which to install. (e.g., yum --disablerepo='*' --enablerepo='somerepo')
enablerepo (ignored if fromrepo is specified): Specify a disabled package repository (or repositories) to enable. (e.g., yum --enablerepo='somerepo')
disablerepo (ignored if fromrepo is specified): Specify an enabled package repository (or repositories) to disable. (e.g., yum --disablerepo='somerepo')
disableexcludes: Disable exclude from main, for a repo or for everything. (e.g., yum --disableexcludes='main')

New in version 2014.7.0.

Multiple Package Installation Options:

pkgs

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"}]'

sources

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

:True

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.

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.yumpkg.latest_version(*names, **kwargs)¶

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> ...

salt.modules.yumpkg.list_holds(pattern='\\w+(?:[.-][^-]+)*', full=True)¶

Changed in version Boron,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:

On RHEL 5: yum-versionlock
On RHEL 6 & 7: yum-plugin-versionlock
On Fedora: python-dnf-plugins-extras-versionlock

pattern: Regular expression used to match the package name
full: Show the full hold definition including version and epoch. Set to False to return just the name of the package(s) being held.

CLI Example:

salt '*' pkg.list_holds
salt '*' pkg.list_holds full=False

salt.modules.yumpkg.list_pkgs(versions_as_list=False, **kwargs)¶

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.yumpkg.list_repo_pkgs(*args, **kwargs)¶

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.

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 is a dictionary of repo names, with each repo containing a dictionary in which the keys are package names, and the values are a list of version numbers. Here is an example of the return data:

{
    '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: Only include results from the specified repo(s). Multiple repos can be specified, comma-separated.

CLI Example:

salt '*' pkg.list_repo_pkgs
salt '*' pkg.list_repo_pkgs foo bar baz
salt '*' pkg.list_repo_pkgs 'samba4*' fromrepo=base,updates

salt.modules.yumpkg.list_repos(basedir=None)¶

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

salt.modules.yumpkg.list_upgrades(refresh=True, **kwargs)¶

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. However, in Fedora 22 and newer all of these but fromrepo is ignored.

New in version 2014.7.0: Support for the disableexcludes option

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.yumpkg.mod_repo(repo, basedir=None, **kwargs)¶

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:

repo: name by which the yum refers to the repo
name: a human-readable name for the repo
baseurl: the URL for yum to reference
mirrorlist: the URL for yum to reference

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/

salt.modules.yumpkg.modified(*packages, **flags)¶

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):

size: Include only files where size changed.
mode: Include only files which file's mode has been changed.
checksum: Include only files which MD5 checksum has been changed.
device: Include only files which major and minor numbers has been changed.
symlink: Include only files which are symbolic link contents.
owner: Include only files where owner has been changed.
group: Include only files where group has been changed.
time: Include only files where modification time of the file has been changed.
capabilities: Include only files where capabilities differ or not. Note: supported only on newer RPM versions.

CLI Examples:

salt '*' pkg.modified
salt '*' pkg.modified httpd
salt '*' pkg.modified httpd postfix
salt '*' pkg.modified httpd owner=True group=False

salt.modules.yumpkg.normalize_name(name)¶

Strips the architecture from the specified package name, if necessary. Circumstances where this would be done include:

If the arch is 32 bit and the package name ends in a 32-bit arch.
If the arch matches the OS arch, or is noarch.

CLI Example:

salt '*' pkg.normalize_name zsh.x86_64

salt.modules.yumpkg.owner(*paths)¶

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 <salt.modules.yumpkg.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

salt.modules.yumpkg.purge(name=None, pkgs=None, **kwargs)¶

Package purges are not supported by yum, this function is identical to pkg.remove.

name: The name of the package to be purged

Multiple Package Options:

pkgs: A list of packages to delete. Must be passed as a python list. The 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"]'

salt.modules.yumpkg.refresh_db(**kwargs)¶

Check the yum repos for updated packages

Returns:

True: Updates are available
False: An error occurred
None: No updates are available

repo: Refresh just the specified repo
disablerepo: Do not refresh the specified repo
enablerepo: Refesh a disabled repo using this option
branch: Add the specified branch when refreshing
disableexcludes: Disable the excludes defined in your config files. Takes one of three options: - all - disable all excludes - main - disable excludes defined in [main] in yum.conf - repoid - disable excludes defined for that repo

CLI Example:

salt '*' pkg.refresh_db

salt.modules.yumpkg.remove(name=None, pkgs=None, **kwargs)¶

Remove packages

name: The name of the package to be removed

Multiple Package Options:

pkgs: A list of packages to delete. Must be passed as a python list. The 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"]'

salt.modules.yumpkg.unhold(name=None, pkgs=None, sources=None, **kwargs)¶

New in version 2014.7.0.

Remove version locks

Note

Requires the appropriate versionlock plugin package to be installed:

On RHEL 5: yum-versionlock
On RHEL 6 & 7: yum-plugin-versionlock
On Fedora: python-dnf-plugins-extras-versionlock

name: The name of the package to be unheld

Multiple Package Options:

pkgs: A list of packages to unhold. Must be passed as a python list. The 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"]'

salt.modules.yumpkg.upgrade(refresh=True, skip_verify=False, **kwargs)¶

Changed in version 2014.7.0.

Run a full system upgrade, a yum upgrade

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

Repository Options:

fromrepo: Specify a package repository (or repositories) from which to install. (e.g., yum --disablerepo='*' --enablerepo='somerepo')
enablerepo (ignored if fromrepo is specified): Specify a disabled package repository (or repositories) to enable. (e.g., yum --enablerepo='somerepo')
disablerepo (ignored if fromrepo is specified): Specify an enabled package repository (or repositories) to disable. (e.g., yum --disablerepo='somerepo')
disableexcludes: Disable exclude from main, for a repo or for everything. (e.g., yum --disableexcludes='main')

salt.modules.yumpkg.upgrade_available(name)¶

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.yumpkg.verify(*names, **kwargs)¶

New in version 2014.1.0.

Runs an rpm -Va on a system, and returns the results in a dict

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.modules.yumpkg.version(*names, **kwargs)¶

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> ...

salt.modules.yumpkg.version_cmp(pkg1, pkg2, ignore_epoch=False)¶

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.

ignore_epoch: 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'

Generated on November 28, 2016 at 06:44:15 MST.

You are viewing docs for the previous stable release, 2015.8.12. Switch to docs for the latest stable release, 2016.3.4, or to a recent doc build from the develop branch.

saltstack.com