9.5. Configuring Yum and Yum Repositories

Note

To expand your expertise, you might also be interested in the Red Hat System Administration III (RH254) and RHCSA Rapid Track (RH199) training courses.
The configuration information for yum and related utilities is located at /etc/yum.conf. This file contains one mandatory [main] section, which enables you to set yum options that have global effect, and can also contain one or more [repository] sections, which allow you to set repository-specific options. However, it is recommended to define individual repositories in new or existing .repo files in the /etc/yum.repos.d/ directory. The values you define in individual [repository] sections of the /etc/yum.conf file override values set in the [main] section.
This section shows you how to:
  • set global yum options by editing the [main] section of the /etc/yum.conf configuration file;
  • set options for individual repositories by editing the [repository] sections in /etc/yum.conf and .repo files in the /etc/yum.repos.d/ directory;
  • use yum variables in /etc/yum.conf and files in the /etc/yum.repos.d/ directory so that dynamic version and architecture values are handled correctly;
  • add, enable, and disable yum repositories on the command line; and
  • set up your own custom yum repository.

9.5.1. Setting [main] Options

The /etc/yum.conf configuration file contains exactly one [main] section, and while some of the key-value pairs in this section affect how yum operates, others affect how yum treats repositories. You can add many additional options under the [main] section heading in /etc/yum.conf.
A sample /etc/yum.conf configuration file can look like this: 
[main]
cachedir=/var/cache/yum/$basearch/$releasever
keepcache=0
debuglevel=2
logfile=/var/log/yum.log
exactarch=1
obsoletes=1
gpgcheck=1
plugins=1
installonly_limit=3

[comments abridged]

# PUT YOUR REPOS HERE OR IN separate files named file.repo
# in /etc/yum.repos.d
The following are the most commonly used options in the [main] section:
assumeyes=value
The assumeyes option determines whether or not yum prompts for confirmation of critical actions. Replace value with one of:
0 (default) — yum prompts for confirmation of critical actions it performs.
1 — Do not prompt for confirmation of critical yum actions. If assumeyes=1 is set, yum behaves in the same way as the command-line options -y and --assumeyes.
cachedir=directory
Use this option to set the directory where yum stores its cache and database files. Replace directory with an absolute path to the directory. By default, yum's cache directory is /var/cache/yum/$basearch/$releasever/.
See Section 9.5.3, “Using Yum Variables” for descriptions of the $basearch and $releasever yum variables.
debuglevel=value
This option specifies the detail of debugging output produced by yum. Here, value is an integer between 1 and 10. Setting a higher debuglevel value causes yum to display more detailed debugging output. debuglevel=2 is the default, while debuglevel=0 disables debugging output.
exactarch=value
With this option, you can set yum to consider the exact architecture when updating already installed packages. Replace value with:
0 — Do not take into account the exact architecture when updating packages.
1 (default) — Consider the exact architecture when updating packages. With this setting, yum does not install a package for 32-bit architecture to update a package already installed on the system with 64-bit architecture.
exclude=package_name [more_package_names]
The exclude option enables you to exclude packages by keyword during installation or system update. Listing multiple packages for exclusion can be accomplished by quoting a space-delimited list of packages. Shell glob expressions using wildcards (for example, * and ?) are allowed.
gpgcheck=value
Use the gpgcheck option to specify if yum should perform a GPG signature check on packages. Replace value with:
0 — Disable GPG signature-checking on packages in all repositories, including local package installation.
1 (default) — Enable checking of GPG signature on all packages in all repositories, including local package installation. With gpgcheck enabled, all packages' signatures are checked.
If this option is set in the [main] section of the /etc/yum.conf file, it sets the GPG-checking rule for all repositories. However, you can also set gpgcheck=value for individual repositories instead; that is, you can enable GPG-checking on one repository while disabling it on another. Setting gpgcheck=value for an individual repository in its corresponding .repo file overrides the default if it is present in /etc/yum.conf.
group_command=value
Use the group_command option to specify how the yum group install, yum group upgrade, and yum group remove commands handle a package group. Replace value with on of:
simple — Install all members of a package group. Upgrade only previously installed packages, but do not install packages that have been added to the group in the meantime.
compat — Similar to simple but yum upgrade also installs packages that were added to the group since the previous upgrade.
objects — (default.) With this option, yum keeps track of the previously installed groups and distinguishes between packages installed as a part of the group and packages installed separately. See Example 9.15, “Viewing information on the LibreOffice package group”
group_package_types=package_type [more_package_types]
Here you can specify which type of packages (optional, default or mandatory) is installed when the yum group install command is called. The default and mandatory package types are chosen by default.
history_record=value
With this option, you can set yum to record transaction history. Replace value with one of:
0 — yum should not record history entries for transactions.
1 (default) — yum should record history entries for transactions. This operation takes certain amount of disk space, and some extra time in the transactions, but it provides a lot of information about past operations, which can be displayed with the yum history command. history_record=1 is the default.
For more information on the yum history command, see Section 9.4, “Working with Transaction History”.

Note

Yum uses history records to detect modifications to the rpmdb data base that have been done outside of yum. In such case, yum displays a warning and automatically searches for possible problems caused by altering rpmdb. With history_record turned off, yum is not able to detect these changes and no automatic checks are performed.
installonlypkgs=space separated list of packages
Here you can provide a space-separated list of packages which yum can install, but will never update. See the yum.conf(5) manual page for the list of packages which are install-only by default.
If you add the installonlypkgs directive to /etc/yum.conf, ensure that you list all of the packages that should be install-only, including any of those listed under the installonlypkgs section of yum.conf(5). In particular, make sure that kernel packages are always listed in installonlypkgs (as they are by default), and installonly_limit is always set to a value greater than 2 so that a backup kernel is always available in case the default one fails to boot.
installonly_limit=value
This option sets how many packages listed in the installonlypkgs directive can be installed at the same time. Replace value with an integer representing the maximum number of versions that can be installed simultaneously for any single package listed in installonlypkgs.
The defaults for the installonlypkgs directive include several different kernel packages, so be aware that changing the value of installonly_limit also affects the maximum number of installed versions of any single kernel package. The default value listed in /etc/yum.conf is installonly_limit=3, and the minimum possible value is installonly_limit=2.
You cannot set installonly_limit=1 because that would make yum remove the running kernel, which is prohibited. If installonly_limit=1 is used, yum fails.
Using installonly_limit=2 ensures that one backup kernel is available. However, it is recommended to keep the default setting installonly_limit=3, so that you have two backup kernels available.
keepcache=value
The keepcache option determines whether yum keeps the cache of headers and packages after successful installation. Here, value is one of:
0 (default) — Do not retain the cache of headers and packages after a successful installation.
1 — Retain the cache after a successful installation.
logfile=file_name
To specify the location for logging output, replace file_name with an absolute path to the file in which yum should write its logging output. By default, yum logs to /var/log/yum.log.
max_connenctions=number
Here value stands for the maximum number of simultaneous connections, default is 5.
multilib_policy=value
The multilib_policy option sets the installation behavior if several architecture versions are available for package install. Here, value stands for:
best — install the best-choice architecture for this system. For example, setting multilib_policy=best on an AMD64 system causes yum to install the 64-bit versions of all packages.
all — always install every possible architecture for every package. For example, with multilib_policy set to all on an AMD64 system, yum would install both the i686 and AMD64 versions of a package, if both were available.
obsoletes=value
The obsoletes option enables the obsoletes process logic during updates.When one package declares in its spec file that it obsoletes another package, the latter package is replaced by the former package when the former package is installed. Obsoletes are declared, for example, when a package is renamed. Replace value with one of:
0 — Disable yum's obsoletes processing logic when performing updates.
1 (default) — Enable yum's obsoletes processing logic when performing updates.
plugins=value
This is a global switch to enable or disable yum plug-ins, value is one of:
0 — Disable all yum plug-ins globally.

Important

Disabling all plug-ins is not advised because certain plug-ins provide important yum services. In particular, product-id and subscription-manager plug-ins provide support for the certificate-based Content Delivery Network (CDN). Disabling plug-ins globally is provided as a convenience option, and is generally only recommended when diagnosing a potential problem with yum.
1 (default) — Enable all yum plug-ins globally. With plugins=1, you can still disable a specific yum plug-in by setting enabled=0 in that plug-in's configuration file.
For more information about various yum plug-ins, see Section 9.6, “Yum Plug-ins”. For further information on controlling plug-ins, see Section 9.6.1, “Enabling, Configuring, and Disabling Yum Plug-ins”.
reposdir=directory
Here, directory is an absolute path to the directory where .repo files are located. All .repo files contain repository information (similar to the [repository] sections of /etc/yum.conf). Yum collects all repository information from .repo files and the [repository] section of the /etc/yum.conf file to create a master list of repositories to use for transactions. If reposdir is not set, yum uses the default directory /etc/yum.repos.d/.
retries=value
This option sets the number of times yum should attempt to retrieve a file before returning an error. value is an integer 0 or greater. Setting value to 0 makes yum retry forever. The default value is 10.
For a complete list of available [main] options, see the [main] OPTIONS section of the yum.conf(5) manual page.

9.5.2. Setting [repository] Options

The [repository] sections, where repository is a unique repository ID such as my_personal_repo (spaces are not permitted), allow you to define individual yum repositories. To avoid conflicts, custom repositories should not use names used by Red Hat repositories.
The following is a bare minimum example of the form a [repository] section takes: 
[repository]
name=repository_name
baseurl=repository_url
Every [repository] section must contain the following directives:
name=repository_name
Here, repository_name is a human-readable string describing the repository.
baseurl=repository_url
Replace repository_url with a URL to the directory where the repodata directory of a repository is located:
  • If the repository is available over HTTP, use: http://path/to/repo
  • If the repository is available over FTP, use: ftp://path/to/repo
  • If the repository is local to the machine, use: file:///path/to/local/repo
  • If a specific online repository requires basic HTTP authentication, you can specify your user name and password by prepending it to the URL as username:password@link. For example, if a repository on http://www.example.com/repo/ requires a user name of “user” and a password of “password”, then the baseurl link could be specified as http://user:password@www.example.com/repo/.
Usually this URL is an HTTP link, such as: 
baseurl=http://path/to/repo/releases/$releasever/server/$basearch/os/
Note that yum always expands the $releasever, $arch, and $basearch variables in URLs. For more information about yum variables, see Section 9.5.3, “Using Yum Variables”.
Other useful [repository] directive are:
enabled=value
This is a simple way to tell yum to use or ignore a particular repository, value is one of:
0 — Do not include this repository as a package source when performing updates and installs. This is an easy way of quickly turning repositories on and off, which is useful when you desire a single package from a repository that you do not want to enable for updates or installs.
1 — Include this repository as a package source.
Turning repositories on and off can also be performed by passing either the --enablerepo=repo_name or --disablerepo=repo_name option to yum, or through the Add/Remove Software window of the PackageKit utility.
async=value
Controls parallel downloading of repository packages. Here, value is one of:
auto (default) — parallel downloading is used if possible, which means that yum automatically disables it for repositories created by plug-ins to avoid failures.
on — parallel downloading is enabled for the repository.
off — parallel downloading is disabled for the repository.
Many more [repository] options exist, part of them have the same form and function as certain [main] options. For a complete list, see the [repository] OPTIONS section of the yum.conf(5) manual page.

Example 9.25. A sample /etc/yum.repos.d/redhat.repo file

The following is a sample /etc/yum.repos.d/redhat.repo file: 
#
# Red Hat Repositories
# Managed by (rhsm) subscription-manager
#

[red-hat-enterprise-linux-scalable-file-system-for-rhel-6-entitlement-rpms]
name = Red Hat Enterprise Linux Scalable File System (for RHEL 6 Entitlement) (RPMs)
baseurl = https://cdn.redhat.com/content/dist/rhel/entitlement-6/releases/$releasever/$basearch/scalablefilesystem/os
enabled = 1
gpgcheck = 1
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
sslverify = 1
sslcacert = /etc/rhsm/ca/redhat-uep.pem
sslclientkey = /etc/pki/entitlement/key.pem
sslclientcert = /etc/pki/entitlement/11300387955690106.pem

[red-hat-enterprise-linux-scalable-file-system-for-rhel-6-entitlement-source-rpms]
name = Red Hat Enterprise Linux Scalable File System (for RHEL 6 Entitlement) (Source RPMs)
baseurl = https://cdn.redhat.com/content/dist/rhel/entitlement-6/releases/$releasever/$basearch/scalablefilesystem/source/SRPMS
enabled = 0
gpgcheck = 1
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
sslverify = 1
sslcacert = /etc/rhsm/ca/redhat-uep.pem
sslclientkey = /etc/pki/entitlement/key.pem
sslclientcert = /etc/pki/entitlement/11300387955690106.pem

[red-hat-enterprise-linux-scalable-file-system-for-rhel-6-entitlement-debug-rpms]
name = Red Hat Enterprise Linux Scalable File System (for RHEL 6 Entitlement) (Debug RPMs)
baseurl = https://cdn.redhat.com/content/dist/rhel/entitlement-6/releases/$releasever/$basearch/scalablefilesystem/debug
enabled = 0
gpgcheck = 1
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
sslverify = 1
sslcacert = /etc/rhsm/ca/redhat-uep.pem
sslclientkey = /etc/pki/entitlement/key.pem
sslclientcert = /etc/pki/entitlement/11300387955690106.pem

9.5.3. Using Yum Variables

You can use and reference the following built-in variables in yum commands and in all yum configuration files (that is, /etc/yum.conf and all .repo files in the /etc/yum.repos.d/ directory):
$releasever
You can use this variable to reference the release version of Red Hat Enterprise Linux. Yum obtains the value of $releasever from the distroverpkg=value line in the /etc/yum.conf configuration file. If there is no such line in /etc/yum.conf, then yum infers the correct value by deriving the version number from the redhat-releaseproduct package that provides the redhat-release file.
$arch
You can use this variable to refer to the system's CPU architecture as returned when calling Python's os.uname() function. Valid values for $arch include: i586, i686 and x86_64.
$basearch
You can use $basearch to reference the base architecture of the system. For example, i686 and i586 machines both have a base architecture of i386, and AMD64 and Intel 64 machines have a base architecture of x86_64.
$YUM0-9
These ten variables are each replaced with the value of any shell environment variables with the same name. If one of these variables is referenced (in /etc/yum.conf for example) and a shell environment variable with the same name does not exist, then the configuration file variable is not replaced.
To define a custom variable or to override the value of an existing one, create a file with the same name as the variable (without the “$” sign) in the /etc/yum/vars/ directory, and add the desired value on its first line.
For example, repository descriptions often include the operating system name. To define a new variable called $osname, create a new file with “Red Hat Enterprise Linux” on the first line and save it as /etc/yum/vars/osname: 
~]# echo "Red Hat Enterprise Linux 7" > /etc/yum/vars/osname
Instead of “Red Hat Enterprise Linux 7”, you can now use the following in the .repo files: 
name=$osname $releasever

9.5.4. Viewing the Current Configuration

To display the current values of global yum options (that is, the options specified in the [main] section of the /etc/yum.conf file), execute the yum-config-manager command with no command-line options: 
yum-config-manager
To list the content of a different configuration section or sections, use the command in the following form: 
yum-config-manager section…
You can also use a glob expression to display the configuration of all matching sections: 
yum-config-manager glob_expression…

Example 9.26.  Viewing configuration of the main section

To list all configuration options and their corresponding values for the main section, type the following at a shell prompt: 
~]$ yum-config-manager main \*
Loaded plugins: langpacks, product-id, subscription-manager
================================== main ===================================
[main]
alwaysprompt = True
assumeyes = False
bandwith = 0
bugtracker_url = https://bugzilla.redhat.com/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%206&component=yum
cache = 0
[output truncated]

9.5.5. Adding, Enabling, and Disabling a Yum Repository

Note

To expand your expertise, you might also be interested in the Red Hat System Administration III (RH254) training course.
Section 9.5.2, “Setting [repository] Options” describes various options you can use to define a yum repository. This section explains how to add, enable, and disable a repository by using the yum-config-manager command.

Important

When the system is registered with Red Hat Subscription Management to the certificate-based Content Delivery Network (CDN), the Red Hat Subscription Manager tools are used to manage repositories in the /etc/yum.repos.d/redhat.repo file.

Adding a Yum Repository

To define a new repository, you can either add a [repository] section to the /etc/yum.conf file, or to a .repo file in the /etc/yum.repos.d/ directory. All files with the .repo file extension in this directory are read by yum, and it is recommended to define your repositories here instead of in /etc/yum.conf.

Warning

Obtaining and installing software packages from unverified or untrusted software sources other than Red Hat's certificate-based Content Delivery Network (CDN) constitutes a potential security risk, and could lead to security, stability, compatibility, and maintainability issues.
Yum repositories commonly provide their own .repo file. To add such a repository to your system and enable it, run the following command as root: 
yum-config-manager --add-repo repository_url
…where repository_url is a link to the .repo file.

Example 9.27. Adding example.repo

To add a repository located at http://www.example.com/example.repo, type the following at a shell prompt: 
~]# yum-config-manager --add-repo http://www.example.com/example.repo
Loaded plugins: langpacks, product-id, subscription-manager
adding repo from: http://www.example.com/example.repo
grabbing file http://www.example.com/example.repo to /etc/yum.repos.d/example.repo
example.repo                                             |  413 B     00:00
repo saved to /etc/yum.repos.d/example.repo

Enabling a Yum Repository

To enable a particular repository or repositories, type the following at a shell prompt as root: 
yum-config-manager --enable repository…
…where repository is the unique repository ID (use yum repolist all to list available repository IDs). Alternatively, you can use a glob expression to enable all matching repositories: 
yum-config-manager --enable glob_expression…

Example 9.28. Enabling repositories defined in custom sections of /etc/yum.conf.

To enable repositories defined in the [example], [example-debuginfo], and [example-source]sections, type: 
~]# yum-config-manager --enable example\*
Loaded plugins: langpacks, product-id, subscription-manager
============================== repo: example ==============================
[example]
bandwidth = 0
base_persistdir = /var/lib/yum/repos/x86_64/7Server
baseurl = http://www.example.com/repo/7Server/x86_64/
cache = 0
cachedir = /var/cache/yum/x86_64/7Server/example
[output truncated]

Example 9.29. Enabling all repositories

To enable all repositories defined both in the /etc/yum.conf file and in the /etc/yum.repos.d/ directory, type: 
~]# yum-config-manager --enable \*
Loaded plugins: langpacks, product-id, subscription-manager
============================== repo: example ==============================
[example]
bandwidth = 0
base_persistdir = /var/lib/yum/repos/x86_64/7Server
baseurl = http://www.example.com/repo/7Server/x86_64/
cache = 0
cachedir = /var/cache/yum/x86_64/7Server/example
[output truncated]
When successful, the yum-config-manager --enable command displays the current repository configuration.

Disabling a Yum Repository

To disable a yum repository, run the following command as root: 
yum-config-manager --disable repository…
…where repository is the unique repository ID (use yum repolist all to list available repository IDs). Similarly to yum-config-manager --enable, you can use a glob expression to disable all matching repositories at the same time: 
yum-config-manager --disable glob_expression…

Example 9.30. Disabling all repositories

To disable all repositories defined both in the /etc/yum.conf file and in the /etc/yum.repos.d/ directory, type: 
~]# yum-config-manager --disable \*
Loaded plugins: langpacks, product-id, subscription-manager
============================== repo: example ==============================
[example]
bandwidth = 0
base_persistdir = /var/lib/yum/repos/x86_64/7Server
baseurl = http://www.example.com/repo/7Server/x86_64/
cache = 0
cachedir = /var/cache/yum/x86_64/7Server/example
[output truncated]
When successful, the yum-config-manager --disable command displays the current configuration.

9.5.6. Creating a Yum Repository

To set up a yum repository:
  1. Install the createrepo package: 
    # yum install createrepo
  2. Copy all packages for your new repository into one directory, such as /tmp/local_repo/: 
    cp /your/packages/*.rpm /tmp/local_repo/
  3. To create the repository run: 
    createrepo /tmp/local_repo/
    This creates the necessary metadata for the yum repository and places metadata in a newly created subdirectory repodata.
    The repository is now ready to be consumed by yum. This repository can be shared over the HTTP or FTP protocol, or refered directly from the local machine. See the Section 9.5.2, “Setting [repository] Options” section for more details on how to configure a yum repository.

    Note

    When constructing the URL for a repository, refer to the /mnt/local_repo not to /mnt/local_repo/repodata, as this directory contains only metadata. Actual yum packages are in /mnt/local_repo.

9.5.6.1. Adding packages to an already created yum repository

To add packages to an already created yum repository:
  1. Copy the new packages to your repository directory, such as /tmp/local_repo/: 
    cp /your/packages/*.rpm /tmp/local_repo/
  2. To reflect the newly added packages in the metadata, run: 
    createrepo --update /tmp/local_repo/
  3. Optional: If you have already used any yum command with newly updated repository, run: 
    yum clean expire-cache

9.5.7. Adding the Optional and Supplementary Repositories

The Optional and Supplementary subscription channels provide additional software packages for Red Hat Enterprise Linux that cover open source licensed software (in the Optional channel) and proprietary licensed software (in the Supplementary channel).
Before subscribing to the Optional and Supplementary channels see the Scope of Coverage Details. If you decide to install packages from these channels, follow the steps documented in the article called How to access Optional and Supplementary channels, and -devel packages using Red Hat Subscription Manager (RHSM)? on the Red Hat Customer Portal.