# salt.states.pkg

## Installation of packages using OS package managers such as yum or apt-get

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

Make sure the package name has the correct case for package managers which are case-sensitive (such as `pkgng`).

salt.states.pkg.downloaded(name, version=None, pkgs=None, fromrepo=None, ignore_epoch=None, **kwargs)

  Added 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: `yum`, `zypper` and `apt`

  Parameters:

    - name (str) -- The name of the package to be downloaded. This parameter is ignored if either "pkgs" is used. Additionally, please note that this option can only be used to download packages from a software repository.

    - version (str) --

      Download a specific version of a package.

      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 must have the epoch included when specifying the version number. For example:

          vim-enhanced:
            pkg.downloaded:
              - version: 2:7.4.160-1.el7

      An ignore_epoch argument has been added to which causes the epoch to be disregarded when the state checks to see if the desired version was installed.

      You can install a specific version when using the `pkgs` argument by including the version after the package:

          common_packages:
            pkg.downloaded:
              - pkgs:
                - unzip
                - dos2unix
                - salt-minion: 2015.8.5-1.el6

    - resolve_capabilities (bool) --

      Turn on resolving capabilities. This allow one to name "provides" or alias names for packages.

      Added in version 2018.3.0.

  CLI Example:

      zsh:
        pkg.downloaded:
          - version: 5.0.5-4.63
          - fromrepo: "myrepository"

salt.states.pkg.group_installed(name, skip=None, include=None, **kwargs)

  Added in version 2015.8.0.

  Changed in version 2016.11.0: Added support in `pacman`

  Changed in version 3006.2: For RPM-based systems, support for `fromrepo`, `enablerepo`, and `disablerepo` (as used in `pkg.install`) has been added. This allows one to, for example, use `enablerepo` to perform a group install from a repo that is otherwise disabled.

  Ensure that an entire package group is installed. This state is currently only supported for the `yum` and `pacman` package managers.

  skip

    Packages that would normally be installed by the package group ("default" packages), which should not be installed.

        Load Balancer:
          pkg.group_installed:
            - skip:
              - piranha

  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.

        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

  The below options are only supported on RPM-based systems

  fromrepo

    Restrict `yum groupinfo` to the specified repo(s). (e.g., `yum --disablerepo='*' --enablerepo='somerepo'`)

        MyGroup:
          pkg.group_installed:
            - fromrepo: base,updates

    Added in version 3006.2.

  enablerepo (ignored if `fromrepo` is specified)

    Specify a disabled package repository (or repositories) to enable. (e.g., `yum --enablerepo='somerepo'`)

        MyGroup:
          pkg.group_installed:
            - enablerepo: myrepo

    Added in version 3006.2.

  disablerepo (ignored if `fromrepo` is specified)

    Specify an enabled package repository (or repositories) to disable. (e.g., `yum --disablerepo='somerepo'`)

        MyGroup:
          pkg.group_installed:
            - disablerepo: epel

    Added in version 3006.2.

  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.held(name, version=None, pkgs=None, replace=False, **kwargs)

  Added in version 3005.

  Set package in 'hold' state, meaning it will not be changed.

  Parameters:

    - name (str) -- The name of the package to be held. This parameter is ignored if `pkgs` is used.

    - version (str) --

      Hold a specific version of a package. Full description of this parameter is in installed function.

      Note

      This parameter make sense for Zypper-based systems. Ignored for YUM/DNF and APT

    - pkgs (list) --

      A list of packages to be held. All packages listed under `pkgs` will be held.

          mypkgs:
            pkg.held:
              - pkgs:
                - foo
                - bar: 1.2.3-4
                - baz

      Note

      For Zypper-based systems the package could be held for the version specified. YUM/DNF and APT ingore it.

    - replace (bool) -- Force replacement of existings holds with specified. By default, this parameter is set to `False`.

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)

  Changed in version 3007.0.

  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.

  Note

  In Windows, some packages are installed using the task manager. The Salt minion installer does this. In that case, there is no way to know if the package installs correctly. All that can be reported is that the task that launches the installer started successfully.

  Parameters:

    - name (str) -- 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.

    - version (str) --

      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`, `pkgin`, `win_pkg`, `yum`, and `zypper`. 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 the `pkg.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.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.

      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 bash
          myminion:
          ----------
              bash:
                  - 4.2.46-21.el7_3
                  - 4.2.46-20.el7_2

      This function was first added for `pkg.list_repo_pkgs` in 2014.1.0, and was expanded to `Debian/Ubuntu` and `Arch Linux`-based distros in the 2017.7.0 release.

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

      If the version given is the string `latest`, the latest available package version will be installed à la `pkg.latest`.

      WILDCARD VERSIONS

      As of the 2017.7.0 release, this state now supports wildcards in package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu, RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be useful for packages where the release name is built into the version in some way, such as for RHEL/CentOS which typically has version numbers like `1.2.34-5.el7`. An example of the usage for this would be:

          mypkg:
            pkg.installed:
              - version: '1.2.34*'

      Keep in mind that using wildcard versions will result in a slower state run since Salt must gather the available versions of the specified packages and figure out which of them match the specified wildcard expression.

    - refresh (bool) --

      This parameter controls whether or not the package 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 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.

    - cache_valid_time (str) --

      Added 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.installed:
              - fromrepo: mycustomrepo
              - skip_verify: True
              - skip_suggestions: True
              - version: 2.0.6~ubuntu3
              - refresh: True
              - cache_valid_time: 300
              - allow_updates: True
              - hold: False

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

    - fromrepo (str) --

      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 main

      The packages provided by this source would be made available via the `precise` release, therefore `fromrepo` would need to be set to `precise` 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 using `version`, 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 Packages

      The 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` or `precise-security` could be used for the `fromrepo` value.

    - skip_verify (bool) -- Skip the GPG verification check for the package to be installed

    - skip_suggestions (bool) --

      Force strict package naming. Disables lookup of package alternatives.

      Added in version 2014.1.1.

    - resolve_capabilities (bool) --

      Turn on resolving capabilities. This allow one to name "provides" or alias names for packages.

      Added in version 2018.3.0.

    - allow_updates (bool) --

      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.

      Added 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: False

    - pkg_verify (bool) --

      Added in version 2014.7.0.

      Use pkg.verify to check if already installed packages require reinstallion. Requested packages that are already installed and not targeted for up- or downgrade are verified with pkg.verify to determine if any file installed by the package have been modified or if package dependencies are not fulfilled. `ignore_types` and `verify_options` can be passed to pkg.verify. See examples below. Currently, this option is supported for the following pkg providers: `yum`, `zypperpkg`.

      Examples:

          httpd:
            pkg.installed:
              - version: 2.2.15-30.el6.centos
              - pkg_verify: True

          mypkgs:
            pkg.installed:
              - pkgs:
                - foo
                - bar: 1.2.3-4
                - baz
              - pkg_verify:
                - ignore_types:
                  - config
                  - doc

          mypkgs:
            pkg.installed:
              - pkgs:
                - foo
                - bar: 1.2.3-4
                - baz
              - pkg_verify:
                - ignore_types:
                  - config
                  - doc
                - verify_options:
                  - nodeps
                  - nofiledigest

    - ignore_types (list) --

      List of types to ignore when verifying the package

      Added in version 2014.7.0.

    - verify_options (list) --

      List of additional options to pass when verifying the package. These options will be added to the `rpm -V` command, prepended with `--` (for example, when `nodeps` is passed in this option, `rpm -V` will be run with `--nodeps`).

      Added in version 2016.11.0.

    - normalize (bool) --

      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.

      Added in version 2014.7.0.

      Example:

          gpfs.gplbin-2.6.32-279.31.1.el6.x86_64:
            pkg.installed:
              - normalize: False

    - ignore_epoch (bool) --

      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.

      Added 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 INSTALLATION OPTIONS:

  Parameters:

    - pkgs (list) --

      A list of packages to install from a software repository. All packages listed under `pkgs` will be installed via a single command.

          mypkgs:
            pkg.installed:
              - pkgs:
                - foo
                - bar
                - baz
              - hold: True

      `NOTE:` For `apt`, `ebuild`, `pacman`, `winrepo`, `yum`, and `zypper`, version numbers can be specified in the `pkgs` argument. For example:

          mypkgs:
            pkg.installed:
              - pkgs:
                - foo
                - bar: 1.2.3-4
                - baz

      Additionally, `ebuild`, `pacman`, `zypper`, `yum/dnf`, and `apt` support the `<`, `<=`, `>=`, and `>` operators for more control over what versions will be installed. For example:

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

    - sources (list) --

      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 the `pkg.version` or `pkg.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.rpm

  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:

    - hold (bool) --

      Force the package to be held at the current installed version.

      Supported on YUM/DNF & APT based systems.

      Added in version 2014.7.0.

      Supported on Zypper-based systems.

      Added in version 3003.

    - update_holds (bool) --

      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 to `False`.

      Supported on YUM/DNF & APT based systems.

      Added in version 2016.11.0.

      Supported on Zypper-based systems.

      Added in version 3003.

    - names (list) --

      A list of packages to install from a software repository. Each package will be installed individually by the package manager.

      Warning

      Unlike `pkgs`, the `names` parameter cannot specify a version. In addition, it makes a separate call to the package management frontend to install each package, whereas `pkgs` makes just a single call. It is therefore recommended to use `pkgs` instead of `names` to install multiple packages, both for the additional features and the performance improvement that it brings.

    - install_recommends (bool) --

      Whether to install the packages marked as recommended. Default is `True`. Currently only works with APT-based systems.

      Added in version 2015.5.0.

          httpd:
            pkg.installed:
              - install_recommends: False

    - only_upgrade (bool) --

      Only upgrade the packages, if they are already installed. Default is `False`. Currently only works with APT-based systems.

      Added in version 2015.5.0.

          httpd:
            pkg.installed:
              - only_upgrade: True

      Note

      If this parameter is set to True and the package is not already installed, the state will fail.

    - report_reboot_exit_codes (bool) --

      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.

      Added in version 2016.11.0.

          ms vcpp installed:
            pkg.installed:
              - name: ms-vcpp
              - version: 10.0.40219
              - report_reboot_exit_codes: False

  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.

  Unless Requisite

salt.states.pkg.latest(name, refresh=None, fromrepo=None, skip_verify=False, pkgs=None, watch_flags=True, **kwargs)

  Changed in version 3007.0.

  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.

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

    - cache_valid_time (str) --

      Added 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: 300

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

    - resolve_capabilities (bool) --

      Turn on resolving capabilities. This allow one to name "provides" or alias names for packages.

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

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

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

  report_reboot_exit_codes

    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.

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

  Added in version 2017.7.0.

  Ensure that packages related to certain advisory ids are downloaded.

  Currently supported for the following pkg providers: `yum` 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)

  Added 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: `yum` 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.

  name

    The name of the package to be purged.

  version

    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.

  normalizeTrue

    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.

    Added in version 2015.8.0.

  ignore_epochNone

    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.

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

  pkgs

    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.

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

  name

    The name of the package to be removed.

  version

    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.

  normalizeTrue

    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.

    Added in version 2015.8.0.

  ignore_epochNone

    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.

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

  pkgs

    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.

    Added in version 0.16.0.

salt.states.pkg.unheld(name, version=None, pkgs=None, all=False, **kwargs)

  Added in version 3005.

  Unset package from 'hold' state, to allow operations with the package.

  Parameters:

    - name (str) -- The name of the package to be unheld. This parameter is ignored if `pkgs` is used.

    - version (str) --

      Unhold a specific version of a package. Full description of this parameter is in installed function.

      Note

      This parameter make sense for Zypper-based systems. Ignored for YUM/DNF and APT

    - pkgs (list) --

      A list of packages to be unheld. All packages listed under `pkgs` will be unheld.

          mypkgs:
            pkg.unheld:
              - pkgs:
                - foo
                - bar: 1.2.3-4
                - baz

      Note

      For Zypper-based systems the package could be held for the version specified. YUM/DNF and APT ingore it. For `unheld` there is no need to specify the exact version to be unheld.

    - all (bool) -- Force removing of all existings locks. By default, this parameter is set to `False`.

salt.states.pkg.uptodate(name, refresh=False, pkgs=None, **kwargs)

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

  :param str name

    The name has no functional value and is only used as a tracking reference

  :param bool refresh

    refresh the package database before checking for new upgrades

  :param list pkgs

    list of packages to upgrade

  Parameters:

    resolve_capabilities (bool) --

    Turn on resolving capabilities. This allow one to name "provides" or alias names for packages.

    Added in version 2018.3.0.

  :param kwargs

    Any keyword arguments to pass through to the `pkg` module.

    For example, for apt systems: dist_upgrade, cache_valid_time, force_conf_new

    Added in version 2015.5.0.