Prototype: packageupdatesmatching(package_regex, version_regex, arch_regex, method_regex)

Return type: data

Description: Return a data container with the list of available packages matching the parameters.

This function searches for the anchored regular expressions in the list of currently available packages.

The return is a data container with a list of package descriptions, looking like this:

code
[
   {
      "arch":"default",
      "method":"dpkg",
      "name":"syncthing",
      "version":"0.12.8"
   }
]

Arguments:

  • package_regex: string - Regular expression (unanchored) to match package name - in the range: .*
  • version_regex: string - Regular expression (unanchored) to match package version - in the range: .*
  • arch_regex: string - Regular expression (unanchored) to match package architecture - in the range: .*
  • method_regex: string - Regular expression (unanchored) to match package method - in the range: .*

Argument Descriptions:

  • package_regex - Regular expression matching packge name
  • version_regex - Regular expression matching package version
  • arch_regex - Regular expression matching package architecutre
  • method_regex - Regular expression matching package method (apt-get, rpm, etc ...)

IMPORTANT: The data source used when querying depends on policy configuration. When package_inventory in body common control is configured, CFEngine will record the packages installed and the package updates available for the configured package modules. In the Masterfiles Policy Framework package_inventory will be configured to the default for the hosts platform. Since only one body common control can be present in a policy set any bundles which use these functions will typically need to execute in the context of a full policy run. If there is no package_inventory attribute such as on package module unsupported platforms or when a policy entry file other than promises.cf is selected with the --file -f argument then the legacy package methods data will be used. At no time will both standard and legacy data be available to these functions.

Example:

code
"all_package_updates" data => packageupdatesmatching(".*", ".*", ".*", ".*");

Refresh rules: * updates cache used by packageupdatesmatching() is refreshed at the end of each agent run in accordance with constraints defined in the relevant package module body. * updates cache is refreshed every time repo type package is installed or removed * updates cache is refreshed if no local cache exists. This means a reliable way to force a refresh of CFEngine's internal package cache is to simply delete the local cache:

code
$(sys.statedir)/packages_updates_<package_module>.lmdb*

Or in the case of legacy package methods:

code
$(sys.statedir)/software_patches_avail.csv

History: Introduced in CFEngine 3.6

See also: packagesmatching(), Package information cache tunables in the MPF