Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 6. Managing versions of Application Stream content

Content in the AppStream repository can be available in multiple versions, corresponding to module streams.

In the following sections, learn operations you must perform when changing existing enabled module streams:

6.1. Modular dependencies and stream changes

Traditionally, packages providing content depend on further packages, and usually specify the desired dependency versions. For packages contained in modules, this mechanism applies as well, but the grouping of packages and their particular versions into modules and streams provides further constraints. Additionally, module streams can declare dependencies on streams of other modules, independent of the packages contained and provided by them.

After any operations with packages or modules, the whole dependency tree of all underlying installed packages must satisfy all the conditions the packages declare. Additionally, all module stream dependencies must be satisfied.

As a result:

  • Enabling a module stream can require enabling streams of further modules.
  • Installing a module stream profile or installing packages from a stream can require enabling streams of further modules and installing further packages.
  • Disabling a stream of a module can require disabling other module streams. No packages will be removed automatically.
  • Removing a package can require removing further packages. If these packages were provided by modules, the module streams remain enabled in preparation for further installation, even if there are no packages installed from these streams anymore. This mirrors the behavior of an unused YUM repository.
Important

You cannot enable a stream of a module when another stream of the same module is already enabled. To switch streams, follow the procedure in Switching to a later stream. Alternatively, reset the module, and then enable the new stream.

Removing all packages installed from a stream before switching to a different stream prevents the system from reaching states where packages could be installed with no repository or stream that provides them.

Technically, resetting module does not automatically change any installed packages. Removing the packages provided by the previous stream and any packages that depend on them is an explicit manual operation.

6.2. Interaction of modular and non-modular dependencies

Modular dependencies are an additional layer on top of regular RPM dependencies. Modular dependencies behave similarly to hypothetical dependencies between repositories. This means that installing different packages requires not only resolution of the RPM dependencies, but also the modular dependencies must be resolved beforehand.

The system always retains the module and stream choices, unless explicitly instructed to change them. A modular package receives updates contained in the currently enabled stream of the module that provides this package, but does not upgrade to a version contained in a different stream.

6.3. Resetting module streams

Resetting a module is an action that returns all of its streams to their initial state - neither enabled nor disabled. If the module has a default stream, this stream becomes active as a result of resetting the module.

Procedure

  • Reset the module state: 

    # yum module reset module-name

    Replace module-name with the name of the module that you want to reset.

    The module is returned to the initial state. Information about an enabled stream and installed profiles is erased but no installed content is removed.

6.4. Disabling all streams of a module

Modules that have a default stream always have one stream active. In situations where the content from all the module streams must not be accessible, it is possible to disable the whole module.

Prerequisites

Procedure

  • Disable the module: 

    # yum module disable module-name

    Replace module-name with the name of the module that you want to disable.

    The yum command asks for confirmation and then disables the module with all its streams. All of the module streams become inactive. No installed content is removed.

6.5. Switching to a later stream

When you switch to a later module stream, all packages from the module are replaced with their later versions.

Important

This procedure is feasible only under the conditions described in the Prerequisites section.

Prerequisites

  • The system is fully updated.
  • No packages installed on the system are newer than the packages available in the repository.

Procedure

  1. Determine if your system is prepared for switching to a later stream: 

    # yum distro-sync

    This command must finish with the message Nothing to do. Complete! If it instead proposes changes and asks for confirmation, carefully review these changes and consider whether you want to proceed. Run the yum distro-sync command repeatedly if necessary. Alternatively, you can refuse the suggested changes and manually modify your system to a state where the command returns Nothing to do. Complete!

    Note

    By checking the yum distro-sync result before switching the streams, you prevent making changes to the system that are unrelated to the stream switching because the same command is required as the last step of this procedure.

  2. Change the active stream to the later one: 

    # yum module reset module-name
# yum module enable module-name:new-stream

  3. Synchronize installed packages to perform the change between streams: 

    # yum distro-sync

    If this action suggests changes to content outside the streams, review them carefully.

    Note
    • If certain installed packages depend on the earlier stream, and there is no compatible version in the later stream, yum reports a dependency conflict. In this case, use the --allowerasing option to remove such packages because they cannot be installed together with the later stream due to missing dependencies.
    • When switching Perl modules, you must always use the --allowerasing option because certain packages in the base RHEL 8 installation depend on Perl 5.26.
    • Binary extensions (typically written in C or C++) for interpreted languages need to be reinstalled after the new stream is enabled; for example, certain packages installed by the gem command from the ruby module, the npm command from the nodejs module, the cpan command from the perl module, or the pecl command from the php module. For more information, see How to switch Ruby streams in RHEL 8.

Alternatively, remove all the module’s content installed from the current stream, reset the module, and install the new stream.

6.6. Overriding module default streams

By default, the YUM utility uses the module default streams defined in the repository that contains the modules. You can override the default stream in the /etc/dnf/modules.defaults.d/ directory.

Important

Always consider the module stream’s life cycle.

Prerequisites

Procedure

  1. Create a YAML configuration file in the /etc/dnf/modules.defaults.d/ drop-in directory. 

    ---
document: modulemd-defaults
version: 1
data:
  module: postgresql
  stream: "10"
  profiles:
    10: [server]
    12: [server]
    13: [server]
    15: [server]
    9.6: [server]
…​

    The preceding output represents the default definition present for the postgresql module at the time of this writing.

    Example 6.1. Example postgresql module with original defaults

    The following is an example of how to configure the stream 13 of the postgresql module as the default stream.

    1. Examine the postgresql module: 

      # yum module list postgresql
(…​)
Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
Name             Stream       Profiles                Summary
postgresql       9.6          client, server [d]      PostgreSQL server and client module
postgresql       10 [d]       client, server [d]      PostgreSQL server and client module
postgresql       12           client, server [d]      PostgreSQL server and client module
postgresql       13           client, server [d]      PostgreSQL server and client module
postgresql       15           client, server [d]      PostgreSQL server and client module
…​
Hint: [d]efault, [e]nabled, [x]disabled, [i]nstalled

    2. To set the default stream to 13, implement the following YAML file configuration in the /etc/dnf/modules.defaults.d/postgresql.yaml file. 

      ---
document: modulemd-defaults
version: 1
data:
  module: postgresql
  stream: "13"
  profiles:
    10: [server]
    12: [server]
    13: [server]
    15: [server]
    9.6: [server]
…​

    3. Examine the postgresql module again: 

      # yum module list postgresql
(…​)
Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
Name             Stream       Profiles                Summary
postgresql       9.6          client, server [d]      PostgreSQL server and client module
postgresql       10           client, server [d]      PostgreSQL server and client module
postgresql       12           client, server [d]      PostgreSQL server and client module
postgresql       13 [d]       client, server [d]      PostgreSQL server and client module
postgresql       15           client, server [d]      PostgreSQL server and client module
…​
Hint: [d]efault, [e]nabled, [x]disabled, [i]nstalled