yum_repository - Add and remove YUM repositories

New in version 2.1.

Synopsis
Options
Examples
Return Values
Notes
This is an Extras Module

Synopsis

Add or remove YUM repositories in RPM-based Linux distributions.

Options

parameter	required	default	choices	comments
async	no	yes	yes no	If set to `yes` Yum will download packages and metadata from this repo in parallel, if possible.
bandwidth	no			Maximum available network bandwidth in bytes/second. Used with the throttle option. If throttle is a percentage and bandwidth is `0` then bandwidth throttling will be disabled. If throttle is expressed as a data rate (bytes/sec) then this option is ignored. Default is `0` (no bandwidth throttling).
baseurl	no			URL to the directory where the yum repository's 'repodata' directory lives. This or the mirrorlist parameter is required if state is set to `present`.
cost	no	1000		Relative cost of accessing this repository. Useful for weighing one repo's packages as greater/less than any other.
deltarpm_metadata_percentage	no	100		When the relative size of deltarpm metadata vs pkgs is larger than this, deltarpm metadata is not downloaded from the repo. Note that you can give values over `100`, so `200` means that the metadata is required to be half the size of the packages. Use `0` to turn off this check, and always download metadata.
deltarpm_percentage	no	75		When the relative size of delta vs pkg is larger than this, delta is not used. Use `0` to turn off delta rpm processing. Local repositories (with file:// baseurl) have delta rpms turned off by default.
description	no			A human readable string describing the repository. This parameter is only required if state is set to `present`.
enabled	no	yes	yes no	This tells yum whether or not use this repository.
enablegroups	no	yes	yes no	Determines whether yum will allow the use of package groups for this repository.
exclude	no			List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (eg. `*` and `?`) are allowed. The list can also be a regular YAML array.
failovermethod	no	roundrobin	roundrobin priority	`roundrobin` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. `priority` starts from the first baseurl listed and reads through them sequentially.
file	no			File to use to save the repo in. Defaults to the value of name.
gpgcakey	no			A URL pointing to the ASCII-armored CA key file for the repository.
gpgcheck	no	no	yes no	Tells yum whether or not it should perform a GPG signature check on packages.
gpgkey	no			A URL pointing to the ASCII-armored GPG key file for the repository.
group	no			name of the group that should own the file/directory, as would be fed to chown
http_caching	no	all	all packages none	Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. `all` means that all HTTP downloads should be cached. `packages` means that only RPM package downloads should be cached (but not repository metadata downloads). `none` means that no HTTP downloads should be cached.
include	no			Include external configuration file. Both, local path and URL is supported. Configuration file will be inserted at the position of the include= line. Included files may contain further include lines. Yum will abort with an error if an inclusion loop is detected.
includepkgs	no			List of packages you want to only use from a repository. This should be a space separated list. Shell globs using wildcards (eg. `*` and `?`) are allowed. Substitution variables (e.g. `$releasever`) are honored here. The list can also be a regular YAML array.
ip_resolve	no	whatever	4 6 IPv4 IPv6 whatever	Determines how yum resolves host names. `4` or `IPv4` - resolve to IPv4 addresses only. `6` or `IPv6` - resolve to IPv6 addresses only.
keepalive	no	no	yes no	This tells yum whether or not HTTP/1.1 keepalive should be used with this repository. This can improve transfer speeds by using one connection when downloading multiple files from a repository.
keepcache	no	1	0 1	Either `1` or `0`. Determines whether or not yum keeps the cache of headers and packages after successful installation.
metadata_expire	no	21600		Time (in seconds) after which the metadata will expire. Default value is 6 hours.
metadata_expire_filter	no	read-only:present	never read-only:past read-only:present read-only:future	Filter the metadata_expire time, allowing a trade of speed for accuracy if a command doesn't require it. Each yum command can specify that it requires a certain level of timeliness quality from the remote repos. from "I'm about to install/upgrade, so this better be current" to "Anything that's available is good enough". `never` - Nothing is filtered, always obey metadata_expire. `read-only:past` - Commands that only care about past information are filtered from metadata expiring. Eg. yum history info (if history needs to lookup anything about a previous transaction, then by definition the remote package was available in the past). `read-only:present` - Commands that are balanced between past and future. Eg. yum list yum. `read-only:future` - Commands that are likely to result in running other commands which will require the latest metadata. Eg. yum check-update. Note that this option does not override "yum clean expire-cache".
metalink	no			Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl.
mirrorlist	no			Specifies a URL to a file containing a list of baseurls. This or the baseurl parameter is required if state is set to `present`.
mirrorlist_expire	no	21600		Time (in seconds) after which the mirrorlist locally cached will expire. Default value is 6 hours.
mode	no			mode the file or directory should be. For those used to /usr/bin/chmod remember that modes are actually octal numbers (like 0644). Leaving off the leading zero will likely have unexpected results. As of version 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`).
name	yes			Unique repository ID. This parameter is only required if state is set to `present` or `absent`.
owner	no			name of the user that should own the file/directory, as would be fed to chown
params	no			Option used to allow the user to overwrite any of the other options. To remove an option, set the value of the option to `null`.
password	no			Password to use with the username for basic authentication.
priority	no	99		Enforce ordered protection of repositories. The value is an integer from 1 to 99. This option only works if the YUM Priorities plugin is installed.
protect	no	no	yes no	Protect packages from updates from other repositories.
proxy	no			URL to the proxy server that yum should use.
proxy_password	no			Username to use for proxy.
proxy_username	no			Password for this proxy.
repo_gpgcheck	no	no	yes no	This tells yum whether or not it should perform a GPG signature check on the repodata from this repository.
reposdir	no	/etc/yum.repos.d		Directory where the `.repo` files will be stored.
retries	no	10		Set the number of times any attempt to retrieve a file should retry before returning an error. Setting this to `0` makes yum try forever.
s3_enabled	no	no	yes no	Enables support for S3 repositories. This option only works if the YUM S3 plugin is installed.
selevel	no	s0		level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the `range`. `_default` feature works as for seuser.
serole	no			role part of SELinux file context, `_default` feature works as for seuser.
setype	no			type part of SELinux file context, `_default` feature works as for seuser.
seuser	no			user part of SELinux file context. Will default to system policy, if applicable. If set to `_default`, it will use the `user` portion of the policy if available
skip_if_unavailable	no	no	yes no	If set to `yes` yum will continue running if this repository cannot be contacted for any reason. This should be set carefully as all repos are consulted for any given command.
ssl_check_cert_permissions	no	no	yes no	Whether yum should check the permissions on the paths for the certificates on the repository (both remote and local). If we can't read any of the files then yum will force skip_if_unavailable to be `yes`. This is most useful for non-root processes which use yum on repos that have client cert files which are readable only by root.
sslcacert	no			Path to the directory containing the databases of the certificate authorities yum should use to verify SSL certificates.
sslclientcert	no			Path to the SSL client certificate yum should use to connect to repos/remote sites.
sslclientkey	no			Path to the SSL client key yum should use to connect to repos/remote sites.
sslverify	no	yes	yes no	Defines whether yum should verify SSL certificates/hosts at all.
state	no	present	absent present	State of the repo file.
throttle	no			Enable bandwidth throttling for downloads. This option can be expressed as a absolute data rate in bytes/sec. An SI prefix (k, M or G) may be appended to the bandwidth value.
timeout	no	30		Number of seconds to wait for a connection before timing out.
ui_repoid_vars	no	releasever basearch		When a repository id is displayed, append these yum variables to the string if they are used in the baseurl/etc. Variables are appended in the order listed (and found).
username	no			Username to use for basic authentication to a repo or really any url.

Examples

- name: Add repository
  yum_repository:
    name: epel
    description: EPEL YUM repo
    baseurl: http://download.fedoraproject.org/pub/epel/$releasever/$basearch/

- name: Add multiple repositories into the same file (1/2)
  yum_repository:
    name: epel
    description: EPEL YUM repo
    file: external_repos
    baseurl: http://download.fedoraproject.org/pub/epel/$releasever/$basearch/
    gpgcheck: no
- name: Add multiple repositories into the same file (2/2)
  yum_repository:
    name: rpmforge
    description: RPMforge YUM repo
    file: external_repos
    baseurl: http://apt.sw.be/redhat/el7/en/$basearch/rpmforge
    mirrorlist: http://mirrorlist.repoforge.org/el7/mirrors-rpmforge
    enabled: no

- name: Remove repository
  yum_repository:
    name: epel
    state: absent

- name: Remove repository from a specific repo file
  yum_repository:
    name: epel
    file: external_repos
    state: absent

#
# Allow to overwrite the yum_repository parameters by defining the parameters
# as a variable in the defaults or vars file:
#
# my_role_somerepo_params:
#   # Disable GPG checking
#   gpgcheck: no
#   # Remove the gpgkey option
#   gpgkey: null
#
- name: Add Some repo
  yum_repository:
    name: somerepo
    description: Some YUM repo
    baseurl: http://server.com/path/to/the/repo
    gpgkey: http://server.com/keys/somerepo.pub
    gpgcheck: yes
    params: "{{ my_role_somerepo_params }}"

Return Values

Common return values are documented here Common Return Values, the following are the fields unique to this module:

name	description	returned	type	sample
repo	repository name	success	string	epel
state	state of the target, after execution	success	string	present

Notes

Note

All comments will be removed if modifying an existing repo file.

Note

Section order is preserved in an existing repo file.

Note

Parameters in a section are ordered alphabetically in an existing repo file.

Note

The repo file will be automatically deleted if it contains no repository.

This is an Extras Module

For more information on what this means please read Extras Modules

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.