Skip to content

Latest commit

 

History

History
1123 lines (694 loc) · 27.7 KB

REFERENCE.md

File metadata and controls

1123 lines (694 loc) · 27.7 KB
Raw

Reference

Table of Contents

Classes

Defined types

  • yum::config: This definition manages yum.conf
  • yum::copr: This definition manages Copr (Cool Other Package Repo) repositories.
  • yum::gpgkey: imports/deleted public GPG key for RPM. Key can be stored on Puppet's fileserver or as inline content.
  • yum::group: This definition installs or removes yum package group.
  • yum::install: Installs/removes rpms from local file/URL via yum install command.
  • yum::plugin: This definition installs Yum plugin.
  • yum::post_transaction_action: Creates post transaction configuratons for dnf or yum.
  • yum::versionlock: Locks package from updates.

Resource types

Functions

  • yum::bool2num_hash_recursive: This functions converts the Boolean values of a Hash to Integers, either '0' or '1'. It does this recursively, decending as far as the langu

Data types

Tasks

  • init: Allows you to perform yum functions

Classes

yum

A class to install and manage Yum configuration.

Examples

Enable management of the default repos for a supported OS:
---
yum::manage_os_default_repos: true
Add Hiera data to disable management of the CentOS Base repo:
---
yum::manage_os_default_repos: true
yum::repo_exclusions:
    - 'base'
Ensure the CentOS base repo is removed from the agent system(s):
---
yum::manage_os_default_repos: true
yum::repos:
    base:
        ensure: 'absent'
Add a custom repo:
---
yum::managed_repos:
    - 'example_repo'
yum::repos:
    example_repo:
        ensure: 'present'
        enabled: true
        descr: 'Example Repo'
        baseurl: 'https://repos.example.com/example/'
        gpgcheck: true
        gpgkey: 'file:///etc/pki/gpm-gpg/RPM-GPG-KEY-Example'
        target: '/etc/yum.repos.d/example.repo'
Use a custom baseurl for the CentOS Base repo:
---
yum::manage_os_default_repos: true
yum::repos:
    base:
        baseurl: 'https://repos.example.com/CentOS/base/'
        mirrorlist: '--'
Install a couple of yum::groups.
---
yum::groups:
  'Development Tools':
    ensure: present
  'System Tools':
    ensure: present

Parameters

The following parameters are available in the yum class:

clean_old_kernels

Data type: Boolean

Whether or not to purge old kernel version beyond the keeponly_limit.

Default value: true

keep_kernel_devel

Data type: Boolean

Whether or not to keep kernel devel packages on old kernel purge.

Default value: false

config_options

Data type: Hash[String, Variant[String, Integer, Boolean, Sensitive[String], Hash[String, Variant[String, Integer, Boolean, Sensitive[String]]]]]

A Hash where keys are the names of Yum::Config resources and the values are either the direct ensure value, or a Hash of the resource's attributes.

@note Boolean parameter values will be converted to either a 1 or 0; use a quoted string to get a literal true or false. Sensitive value will disable the show_diff.

Default value: {}

repos

Data type: Hash[String, Optional[Hash[String, Variant[String, Integer, Boolean]]]]

A hash where keys are the names of Yumrepo resources and each value represents its respective Yumrepo's resource parameters. This is used in conjunction with the managed_repos parameter to create Yumrepo resources en masse. Some default data is provided for this using module data. It is configured to deep merge with a knockout_prefix of -- by default, so individual parameters may be overriden or removed via global or environment Hiera data.

@note Boolean parameter values will be converted to either a 1 or 0; use a quoted string to get a literal true or false.

Default value: {}

managed_repos

Data type: Array[String]

An array of first-level keys from the repos hash to include in the catalog. The module uses this list to select Yumrepo resources from the repos hash for instantiation. Defaults are set in the module's Hiera data.

@note This only indicates the managed state of the repos, the ensure state must be managed in the repos data.

Default value: []

manage_os_default_repos

Data type: Boolean

Whether or not to add an operating system's default repos to the managed_repos array.

@note This only works for operating systems with data in the module's data directory. Currently the module only contains data for for CentOS 6 & 7.

Default value: false

os_default_repos

Data type: Array[String]

A list of default repos to add to managed_repos if manage_os_default_repos is enabled. Normally this should not be modified.

Default value: []

repo_exclusions

Data type: Array[String]

An array of first-level keys from the repos hash to exclude from management via this module. Values in this array will be subtracted from the managed_repos array as a last step before instantiation.

Default value: []

gpgkeys

Data type: Hash[String, Hash[String, String]]

A hash of yum::gpgkey types, which will be automatically included if they are referenced by a managed_repo. This will use the same merging behavior as repos.

Default value: {}

utils_package_name

Data type: String

Name of the utils package, e.g. 'yum-utils', or 'dnf-utils'.

Default value: 'yum-utils'

groups

Data type: Stdlib::CreateResources

A hash of yum::group instances to manage.

Default value: {}

yum::clean

A $(yum clean all) Exec to be notified if desired.

yum::plugin::post_transaction_actions

Class to install post_transaction plugin

Examples

Enable post_transaction_action plugin
class{'yum::plugin::post_transaction_actions':
  ensure => present,
}

Parameters

The following parameters are available in the yum::plugin::post_transaction_actions class:

ensure

Data type: Enum['present', 'absent']

Should the post_transaction actions plugin be installed

Default value: 'present'

yum::plugin::versionlock

This class installs versionlock plugin

Examples

Sample usage:
class { 'yum::plugin::versionlock':
  ensure      => present,
}

Parameters

The following parameters are available in the yum::plugin::versionlock class:

ensure

Data type: Enum['present', 'absent']

specifies if versionlock should be present or absent

Default value: 'present'

clean

Data type: Boolean

specifies if yum clean all should be called after edits. Defaults false.

Default value: false

path

Data type: String

filepath for the versionlock.list, default based on your system.

yum::settings

Simple settings to use

Parameters

The following parameters are available in the yum::settings class:

mainconf

Data type: Enum['/etc/yum.conf','/etc/dnf/dnf.conf']

Augeas location of the dnf or yum configuration file. The default is set into hiera according to the package_provider being yum or dnf.

Defined types

yum::config

This definition manages yum.conf

Examples

configure installonly limit
yum::config { 'installonly_limit':
  ensure => 2,
}
remove a configuration
yum::config { 'debuglevel':
  ensure => absent,
}

Parameters

The following parameters are available in the yum::config defined type:

ensure

Data type: Variant[Boolean, Integer, Enum['absent'], String, Sensitive[String]]

specifies value or absent keyword

key

Data type: String

alternative conf. key (defaults to name)

Default value: $title

yum::copr

This definition manages Copr (Cool Other Package Repo) repositories.

Examples

add and enable COPR restic repository
yum::copr { 'copart/restic':
  ensure  => 'enabled',
}

Parameters

The following parameters are available in the yum::copr defined type:

copr_repo

Data type: String

Name of repository, defaults to title.

Default value: $title

manage_prereq_plugin

Data type: Boolean

Wheter required plugin for dnf/yum should be installed by this resource.

Default value: true

ensure

Data type: Enum['enabled', 'disabled', 'removed']

Specifies if repo should be enabled, disabled or removed.

Default value: 'enabled'

yum::gpgkey

imports/deleted public GPG key for RPM. Key can be stored on Puppet's fileserver or as inline content.

Examples

Sample usage:
yum::gpgkey { '/etc/pki/rpm-gpg/RPM-GPG-KEY-puppet-smoketest1':
  ensure  => 'present',
  content => '-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----';
}

Parameters

The following parameters are available in the yum::gpgkey defined type:

path

Data type: String

alternative file location (defaults to name)

Default value: $name

ensure

Data type: Enum['present', 'absent']

specifies if key should be present or absent

Default value: 'present'

content

Data type: Optional[String]

the actual file content

Default value: undef

source

Data type: Optional[String]

source (e.g.: puppet:///)

Default value: undef

owner

Data type: String

file owner

Default value: 'root'

group

Data type: String

file group

Default value: 'root'

mode

Data type: String

file mode

Default value: '0644'

yum::group

This definition installs or removes yum package group.

Examples

Sample usage:
yum::group { 'X Window System':
  ensure  => 'present',
}

Parameters

The following parameters are available in the yum::group defined type:

ensure

Data type: Enum['present', 'installed', 'latest', 'absent', 'purged']

specifies if package group should be present (installed) or absent (purged)

Default value: 'present'

timeout

Data type: Optional[Integer]

exec timeout for yum groupinstall command

Default value: undef

install_options

Data type: Array[String[1]]

options provided to yum groupinstall command

Default value: []

yum::install

Installs/removes rpms from local file/URL via yum install command.

  • Note This can be better than using just the rpm provider because it will pull all the dependencies.

Examples

Sample usage:
yum::install { 'epel-release':
  ensure => 'present',
  source => 'https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm',
}

Parameters

The following parameters are available in the yum::install defined type:

source

Data type: String

file or URL where RPM is available

ensure

Data type: Enum['present', 'installed', 'absent', 'purged']

the desired state of the package

Default value: 'present'

timeout

Data type: Optional[Integer]

optional timeout for the installation

Default value: undef

require_verify

Data type: Boolean

optional argument, will reinstall if rpm verify fails

Default value: false

yum::plugin

This definition installs Yum plugin.

Examples

Sample usage:
yum::plugin { 'versionlock':
  ensure  => 'present',
}

Parameters

The following parameters are available in the yum::plugin defined type:

ensure

Data type: Enum['present', 'absent']

specifies if plugin should be present or absent

Default value: 'present'

pkg_prefix

Data type: Optional[String]

the package prefix for the plugins

Default value: undef

pkg_name

Data type: Optional[String]

the actual package name

Default value: undef

yum::post_transaction_action

Creates post transaction configuratons for dnf or yum.

Examples

Touch a file when ssh is package is updated, installed or removed.
yum::post_transaction_action{'touch file on ssh package update':
  key     => 'openssh-*',
  state   => 'any',
  command => 'touch /tmp/openssh-installed',
}

Parameters

The following parameters are available in the yum::post_transaction_action defined type:

action

Data type: String[1]

Name variable a string to label the rule

Default value: $title

key

Data type: Variant[Enum['*'],Yum::RpmNameGlob,Stdlib::Unixpath]

Package name, glob or file name file glob.

state

Data type: Enum['install', 'update', 'remove', 'any', 'in', 'out']

Can be install, update, remove or any on YUM based systems. Can be in, out or any on DNF based systems.

Default value: 'any'

command

Data type: String[1]

The command to run

yum::versionlock

Locks package from updates.

  • Note The resource title must use the format By default on CentOS 7 the following format is used. "%{EPOCH}:%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}". This can be retrieved via the command `rpm -q --qf '%{EPOCH}:%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}'. If "%{EPOCH}" returns as '(none)', it should be set to '0'. Wildcards may be used within token slots, but must not cover seperators, e.g., '0:bsh-4.1.2-9.' covers Bash version 4.1.2, revision 9 on all architectures. By default on CentOS 8 and newer the resource title to just set the package name. If a version is set on CentOS 7 then it behaves like CentOS 8

  • See also

Examples

Sample usage on CentOS 7
yum::versionlock { '0:bash-4.1.2-9.el7.*':
  ensure => present,
}
Sample usage on CentOS 8
yum::versionlock { 'bash':
  ensure => present,
  version => '4.1.2',
  release => '9.el8',
  epoch   => 0,
  arch    => 'noarch',
}
Sample usage on CentOS 7 with new style version, release, epoch, name parameters.
yum::versionlock { 'bash':
  ensure => present,
  version => '3.1.2',
  release => '9.el7',
  epoch   => 0,
  arch    => 'noarch',
}

Parameters

The following parameters are available in the yum::versionlock defined type:

ensure

Data type: Enum['present', 'absent', 'exclude']

Specifies if versionlock should be present, absent or exclude.

Default value: 'present'

version

Data type: Optional[Yum::RpmVersion]

Version of the package if CentOS 8 mechanism is used. This must be set for dnf based systems (e.g CentOS 8). If version is set then the name var is assumed to a package name and not the full versionlock string.

Default value: undef

release

Data type: Yum::RpmRelease

Release of the package if CentOS 8 mechanism is used.

Default value: '*'

arch

Data type: Variant[Yum::RpmArch, Enum['*']]

Arch of the package if CentOS 8 mechanism is used.

Default value: '*'

epoch

Data type: Integer[0]

Epoch of the package if CentOS 8 mechanism is used.

Default value: 0

Resource types

dnf_module_stream

This type allows Puppet to enable/disable streams via DNF modules

Examples

Enable MariaDB default stream
dnf_module_stream { 'mariadb':
  stream => default,
}
Enable MariaDB 10.5 stream
dnf_module_stream { 'mariadb':
  stream => '10.5',
}
Disable MariaDB streams
dnf_module_stream { 'mariadb':
  stream => absent,
}

Properties

The following properties are available in the dnf_module_stream type.

stream

Valid values: present, default, absent, %r{.+}

  Module stream that should be enabled

String - Specify stream present - Keep current enabled stream if any, otherwise enable default one default - Enable default stream absent - No stream (resets module)

Parameters

The following parameters are available in the dnf_module_stream type.

module

Valid values: %r{.+}

DNF module to be managed

provider

The specific backend to use for this dnf_module_stream resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

title

Valid values: %r{.+}

Resource title

Functions

yum::bool2num_hash_recursive

Type: Puppet Language

This functions converts the Boolean values of a Hash to Integers, either '0' or '1'. It does this recursively, decending as far as the language implemenation will allow. Note that Structs and Arrays will be ignored, even if they contain Hashes.

Examples

Usage
Hash $foo = {
  bar => { 'a' => true, 'b' => 'b' },
  baz => false,
  qux => [{ 'c' => true }, { 'd' => false }],
}

yum::bool2num_hash_recursive($foo)

The above would return:

{
  bar => { 'a' => 1, 'b' => 'b' },
  baz => 0,
  qux => [{ 'c' => true }, { 'd' => false }],
}

yum::bool2num_hash_recursive(Hash $arg)

This functions converts the Boolean values of a Hash to Integers, either '0' or '1'. It does this recursively, decending as far as the language implemenation will allow. Note that Structs and Arrays will be ignored, even if they contain Hashes.

Returns: Hash

Examples
Usage
Hash $foo = {
  bar => { 'a' => true, 'b' => 'b' },
  baz => false,
  qux => [{ 'c' => true }, { 'd' => false }],
}

yum::bool2num_hash_recursive($foo)

The above would return:

{
  bar => { 'a' => 1, 'b' => 'b' },
  baz => 0,
  qux => [{ 'c' => true }, { 'd' => false }],
}
arg

Data type: Hash

The hash on which to operate

Data types

Yum::RpmArch

Output of rpm -q --queryformat '%{arch}\n' package

Alias of Enum['noarch', 'x86_64', 'i386', 'aarch64', 'arm', 'ppc64', 'ppc64le', 'sparc64', 'ia64', 'alpha', 'ip', 'm68k', 'mips', 'mipsel', 'mk68k', 'mint', 'ppc', 'rs6000', 's390', 's390x', 'sh', 'sparc', 'xtensa']

Yum::RpmName

Can be alphanumeric or contain . _ + % { } -. Output of rpm -q --queryformat '%{name}\n package Examples python36-foobar, netscape

Alias of Pattern[/\A([0-9a-zA-Z\._\+%\{\}-]+)\z/]

Yum::RpmNameGlob

Can be alphanumeric or contain . _ + % { } - *. Examples python36-*, *netscape

Alias of Pattern[/\A([*0-9a-zA-Z\._\+%\{\}-]+)\z/]

Yum::RpmRelease

It may not contain a dash. Output of rpm -q --queryformat '%{release}\n' package. Examples 3.4 3.4.el6, 3.4.el6_2

Alias of Pattern[/\A([^-]+)\z/]

Yum::RpmVersion

It may not contain a dash. Output of rpm -q --queryformat '%{version}\n' package. Examples 3.4, 2.5.alpha6

Alias of Pattern[/\A([^-]+)\z/]

Yum::VersionlockString

This type matches strings appropriate for use with yum-versionlock. Its basic format, using the rpm(8) query string format, is %{EPOCH}:%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}. As a Regex, it breaks down into five distinct parts, plus the seperators.

EPOCH: An unsigned integer type Yum::PackageEpoch = Regexp[/[0-9]*]+/]

NAME: Any valid package name (see https://github.com/rpm-software-management/rpm/blob/master/doc/manual/spec) type Yum::PackageName = Regexp[/[0-9a-zA-Z._+%{}*-]+/]

VERSION: Any valid version string. The only limitation here, according to the RPM manual, is that it may not contain a dash (-). type Yum::PackageVersion = Regexp[/[^-]+/]

RELEASE: Any valid release string. Only limitation is that it is not a dash (-) type Yum::PackageRelease = Regexp[/[^-]+/]

lint:ignore:140chars ARCH: Matches a string such as el7.x86_64. This is actuall two sub-expressions. See below. type Yum::PackageArch = Regexp[/([0-9a-zZ-Z_*]+)(?:.(noarch|x86_64|i386|arm|ppc64|ppc64le|sparc64|ia64|alpha|ip|m68k|mips|mipsel|mk68k|mint|ppc|rs6000|s390|s390x|sh|sparc|xtensa|*))?/] lint:endignore

The %{ARCH} sub-expression is composed of two sub-expressions separated by a dot (.), where the second part is optional. The RPM specification calls the first field the DistTag, and the second the BuildArch.

DistTag: Any string consiting of only letters, numbers, or an underscore, e.g., el6, sl7, or fc24. type Yum::PackageDistTag = Regexp[/[0-9a-zZ-Z_*]+/]

lint:ignore:140chars BuildArch: Any string from the list at https://github.com/rpm-software-management/rpm/blob/master/rpmrc.in. Strings are roughly listed from most common to least common to improve performance. type Yum::PackageBuildArch = Regexp[/noarch|x86_64|i386|arm|ppc64|ppc64le|sparc64|ia64|alpha|ip|m68k|mips|mipsel|mk68k|mint|ppc|rs6000|s390|s390x|sh|sparc|xtensa/] lint:endignore

wildcard characters may not span the fields, may not cover the seperators. This is an undocumented but tested limitation of yum-versionlock.

lint:ignore:140chars

  • Note Each field may contain wildcard characters (*), but the

Examples

A complete, well-formed string: `0:bash-4.1.2-9.el6_2.x86_64'


A well-formed string that has dropped the optional BuildArch sub-field: 0:bash-4.1.2-9.el6_2




A well-formed string using wildcards: *0:bash*-4.*-*.*




An invalid string (wildcard spans the VERSION and RELEASE fields): `0:bash-4.*-el6.x86_64




An invlaid string (wildcard spans the VERSION, RELEASE, and ARCH fields): 0:bash-*




Alias of Pattern[/^([0-9\*]+):([0-9a-zA-Z\._\+%\{\}\*-]+)-([^-]+)-([^-]+)\.(([0-9a-zZ-Z_\*]+)(?:\.(noarch|x86_64|i386|arm|ppc64|ppc64le|sparc64|ia64|alpha|ip|m68k|mips|mipsel|mk68k|mint|ppc|rs6000|s390|s390x|sh|sparc|xtensa|\*))?)$/]


Tasks


init


Allows you to perform yum functions


Supports noop? false


Parameters


action


Data type: Enum[update, upgrade, 'list updates']


Action to perform


quiet


Data type: Optional[Boolean]


Run without output