Chapter 1. Getting started with RHEL System Roles

This section explains what RHEL System Roles are. Additionally, it describes how to apply a particular role through an Ansible playbook to perform various system administration tasks.

1.1. Introduction to RHEL System Roles

RHEL System Roles is a collection of Ansible roles and modules. RHEL System Roles provide a configuration interface to remotely manage multiple RHEL systems. The interface enables managing system configurations across multiple versions of RHEL, as well as adopting new major releases.

On Red Hat Enterprise Linux 8, the interface currently consists of the following roles:

  • kdump
  • network
  • selinux
  • storage
  • certificate
  • kernel_settings
  • logging
  • metrics
  • nbde_client and nbde_server
  • timesync
  • tlog

All these roles are provided by the rhel-system-roles package available in the AppStream repository.

Additional resources

1.2. RHEL System Roles terminology

You can find the following terms across this documentation:

System Roles terminology

Ansible playbook
Playbooks are Ansible’s configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
Control node
Any machine with Ansible installed. You can run commands and playbooks, invoking /usr/bin/ansible or /usr/bin/ansible-playbook, from any control node. You can use any computer that has Python installed on it as a control node - laptops, shared desktops, and servers can all run Ansible. However, you cannot use a Windows machine as a control node. You can have multiple control nodes.
A list of managed nodes. An inventory file is also sometimes called a “hostfile”. Your inventory can specify information like IP address for each managed node. An inventory can also organize managed nodes, creating and nesting groups for easier scaling. To learn more about inventory, see the Working with Inventory section.
Managed nodes
The network devices, servers, or both that you manage with Ansible. Managed nodes are also sometimes called “hosts”. Ansible is not installed on managed nodes.

1.3. Applying a role

The following procedure describes how to apply a particular role.


  • The rhel-system-roles package is installed on the system that you want to use as a control node:

    # yum install rhel-system-roles
  • The Ansible Engine repository is enabled, and the ansible package is installed on the system that you want to use as a control node. You need the ansible package to run playbooks that use RHEL System Roles.

    • If you do not have a Red Hat Ansible Engine Subscription, you can use a limited supported version of Red Hat Ansible Engine provided with your Red Hat Enterprise Linux subscription. In this case, follow these steps:

      1. Enable the RHEL Ansible Engine repository:

        # subscription-manager refresh
        # subscription-manager repos --enable ansible-2-for-rhel-8-x86_64-rpms
      2. Install Ansible Engine:

        # yum install ansible
    • If you have a Red Hat Ansible Engine Subscription, follow the procedure described in How do I Download and Install Red Hat Ansible Engine?.
  • You are able to create an Ansible playbook.

    Playbooks represent Ansible’s configuration, deployment, and orchestration language. By using playbooks, you can declare and manage configurations of remote machines, deploy multiple remote machines or orchestrate steps of any manual ordered process.

    A playbook is a list of one or more plays. Every play can include Ansible variables, tasks, or roles.

    Playbooks are human-readable, and they are expressed in the YAML format.

    For more information about playbooks, see Ansible documentation.


  1. Create an Ansible playbook including the required role.

    The following example shows how to use roles through the roles: option for a given play:

    - hosts: webservers
         - rhel-system-roles.timesync

    For more information on using roles in playbooks, see Ansible documentation.

    See Ansible examples for example playbooks.


    Every role includes a README file, which documents how to use the role and supported parameter values. You can also find an example playbook for a particular role under the documentation directory of the role. Such documentation directory is provided by default with the rhel-system-roles package, and can be found in the following location:


    Replace SUBSYSTEM with the name of the required role, such as selinux, kdump, network, timesync, or storage.

  2. Verify the playbook syntax:

    # ansible-playbook --syntax-check name.of.the.playbook

    The ansible-playbook command offers a --syntax-check option that you can use to verify the syntax of a playbook.

  3. Execute the playbook on targeted hosts by running the ansible-playbook command:

    # ansible-playbook -i name.of.the.inventory name.of.the.playbook

    An inventory is a list of systems against which Ansible works. For more information on how to create and inventory, and how to work with it, see Ansible documentation.

    If you do not have an inventory, you can create it at the time of running ansible-playbook:

    If you have only one targeted host against which you want to run the playbook, use:

    # ansible-playbook -i host1, name.of.the.playbook

    If you have multiple targeted hosts against which you want to run the playbook, use:

    # ansible-playbook -i host1,host2,....,hostn name.of.the.playbook

Additional resources

  • For more detailed information on using the ansible-playbook command, see the ansible-playbook man page.

1.4. Additional resources