Table of Contents

packages

Table of Contents

CFEngine 3.7 and later supports package management through a simple promise interface. Using a small set of attributes you can make promises about the state of software on a host, whether it should be installed, not installed, or at a specific version.

CFEngine 3.6 and older had a different package promise implementation, which is still functional, but considered deprecated. However, it may still be in use by existing policy files, and it may cover platforms which the new implementation does not currently cover. To read about the old package promise, go to the old package promise section.

The actual communication with the package manager on the system is handled by so called package modules, which are specifically written for each type of package manager.

In this example, we want the software package "apache2" to be present on the system, and we want it to be version 2.2.22. If this requirement cannot be fulfilled (for example because the package repository doesn't have it), the promise will fail.

It is also possible to specify a package file name, if the package resides on the local filesystem, like this:

  packages:
      "/mnt/nfs/packages/apache2-2.2.22.x86_64.rpm"
        policy => "present",
        package_module => yum;

The default package module can be globally specified with the package_module attribute in body common control.

Note that if your policy attribute specifies "absent", then the promiser string needs to be a bare package name, you cannot use a file name for this.

Attributes

Common Attributes

Common attributes are available to all promise types. Full details for common attributes can be found in the Common Attributes section of the Promise Types and Attributes page. The common attributes are as follows:

action

classes

comment

depends_on

handle

ifvarclass

architecture

Description: The architecture we want the promise to consider.

The promise will only consider the architecture specified when performing package manipulations, but depending on the underlying package manager, this may indirectly affect other architectures.

Type: string

Allowed input range: (arbitrary string)

Example:

  packages:
    "apache"
        policy => "present",
        package_module => apt_get,
        architecture => "x86_64";

options

Description: Options to pass to the underlying package module.

options is a catchall attribute in order to pass arbitrary data into the package module which is carrying out package operations. It is meant as a rescue solution when a package module has added functionality which is not covered by the package promise API. As such there is no official documentation for this attribute, its usage depends on the package module in question.

Type: slist

Allowed input range: (arbitrary string)

Example:

  packages:
    "apache"
        policy => "present",
        package_module => my_package_module,
        options => { "repository=myrepo" };
    debian::
      "php7.0"
        policy => "present",
        package_module => apt_get,
        options => { "-o", "APT::Install-Recommends=0" };

policy

Description: Whether the package should be present or absent on the system.

Default value: present

Type: string

Allowed input range: present|absent

Example:

  packages:
    "apache"
        policy => "absent",
        package_module => apt_get;

version

Description: The version we want the promise to consider.

Type: string

Allowed input range: (arbitrary string)

Note: When policy present is used version may be set to latest to ensure the latest available version from a repository is installed.

Example:

  packages:
    "apache"
        policy => "absent",
        package_module => apt_get,
        version => "2.2.22";

    "ssh"
        policy => "present",
        package_module => apt_get,
        version => "latest";

package_module

Type: body package_module

The package module body you wish to use for the package promise. The default is platform dependent, see package_module in Components and Common Control. The name of the body is expected to be the same as the name of the package module inside /var/cfengine/modules/packages.

See also: Common Body Attributes

default_options

Description: Options to pass to to the package module by default.

See the options attribute for details on what options do.

Type: slist

Allowed input range: (arbitrary string)

Example:

body package_module apt_get
{
    default_options => { "use_curl=1" };
}

query_installed_ifelapsed

Description: How often to query the system for currently installed packages.

For performance reasons, CFEngine maintains a cache of currently installed packages, to avoid calling the package manager too often. This attribute tells CFEngine how often to update this cache (in minutes).

The cache is always updated when CFEngine makes changes to the system.

Type: int

Allowed input range: (Positive integer)

Example:

body package_module apt_get
{
    # Query the package database only every four hours.
    query_installed_ifelapsed => "240";
}

Note for package_module authors: list-installed will be called when the agent repairs a package using the given package_module, when the lock has expired or when the agent is run without locks.

See Also: Package Modules

query_updates_ifelapsed

Description: How often to query the package manager for new updates.

In order not to query repository servers too often, CFEngine maintains a cache of the currently available package updates. This attribute tells CFEngine how often to update this cache (in minutes).

Even when making package changes to the system, CFEngine will not query this information more often than this attribute specifies, however it may make a local query in order to update the cache from local, already downloaded data.

Type: int

Allowed input range: (Positive integer)

Example:

body package_module apt_get
{
    # Query package updates only every 24 hours.
    query_updates_ifelapsed => "1440";
}

Note for package_module authors: list-updates will be called when the lock has expired or when the agent is run without locks. list-updates-local is called in all other conditions.

See Also: Package Modules

Package modules out-of-the-box

yum

Manage packages using yum.

Example:

Example showing file based package source.

  packages:
      "/mnt/nfs/packages/httpd-2.2.22.x86_64.rpm"
        policy => "present",
        package_module => yum;

Example showing repository based package source.

  packages:
      "httpd"
        policy => "present",
        package_module => yum,
        version => "2.2.22";

Example showing how to enable a specific repository for a specific promise.

bundle agent example
{
  packages:
    "git"
        policy => "present",
        package_module => yum,
        options => { "enablerepo=updates" };
}

Notes:

Supports file path and repository sourced packages.
Requires Python version 2 to be installed on the host.

History:

Added in CFEngine 3.7.0
enablerepo and disablerepo option support added in 3.7.8, 3.10.4, 3.12.0

apt_get

Manage packages using apt-get.

Example:

Example showing file based package source.

  packages:
      "/mnt/nfs/packages/apache2-2.2.22.x86_64.deb"
        policy => "present",
        package_module => apt_get;

Example showing repository based package source.

  packages:
      "apache2"
        policy => "present",
        package_module => apt_get,
        version => "2.2.22",
        options => { "-o", "APT::Install-Recommends=0" };

Notes:

Requires Python version 2 to be installed on the host.
Supports options attribute. Each space separate option must be added as a separate list element. The options are passed directly through to the package manager.

History:

Added in CFEngine 3.7.0

freebsd_ports

Manage packages using FreeBSD Ports.

History:

Added in CFEngine 3.9.0

nimclient

Manage packages using nimclient on AIX.

Example:

  packages:
    aix::
      "expect.base"
        policy => "present",
        package_module => nimclient,
        options => { "lpp_source=lppaix710304" };

Notes:

options attribute support to specify lpp_source. Please note it is REQUIRED to specify an lpp_source when using this package module.

History:

Added in CFEngine 3.9.0

pkg

Manage packages using FreeBSD pkg.

Example:

  packages:
    freebsd::
      "emacs-nox11"
        policy => "present",
        package_module => pkg;

      "emacs"
        policy => "absent",
        package_module => pkg;

History:

Added in CFEngine 3.9.0

pkgsrc

Manage packages using pkgsrc.

History:

Added in CFEngine 3.9.0

snap

Manage packages using snap).

bundle agent main
{
  packages:
    ubuntu::
      "genpw"
        policy => "present",
        package_module => snap;

      "genpw"
        policy => "absent",
        package_module => snap;

       "genpw"
         policy => "present",
         package_module => snap,
         version => "2.0.0";

       "genpw"
         policy => "absent",
         package_module => snap,
         version => "2.0.0";

       "genpw"
         policy => "present",
         package_module => snap,
         version => "latest";
}

History:

Added in CFEngine 3.15.0, 3.12.3, 3.10.7

Notes:

version latest is not supported when promising an absence
list-updates is not implemented, snaps are automatically updated by default

packages

Attributes

Common Attributes

action

classes

comment

depends_on

handle

ifvarclass

meta

architecture

options

policy

version

package_module

default_options

query_installed_ifelapsed

query_updates_ifelapsed

Package modules out-of-the-box

yum

apt_get

freebsd_ports

nimclient

pkg

pkgsrc

snap