RHEL System Roles Overview

Red Hat Enterprise Linux (RHEL) 7.4 introduced RHEL System Roles as a collection of Ansible roles and modules that provide a stable and consistent configuration interface to remotely manage RHEL 6.10 and later versions of Red Hat Enterprise Linux. The effort is based on development of the Linux System Roles upstream project. The following roles are provided and supported as follows:

Roles in Technology Preview status are tested as stable but the interface (role inputs) may receive future updates that could be incompatible with the current state.

The RHEL System Roles are provided in the RHEL Extras repository. They can be used by Ansible Engine and Ansible Tower to manage RHEL systems.

Note 1: The RHEL subscription provides support for the implementation of the RHEL System Roles and compatibility with Ansible Engine. The Ansible Engine repositories are made accessible as a convenience for the use of RHEL System Roles, as well as other layered products in the Red Hat product portfolio. However, the RHEL subscription does not include full support for Ansible Engine.

Note 2: A support subscription is required for all other use of Ansible Engine and Ansible Tower. Additional information can be found at Top Support Policies for Red Hat Ansible Automation.

Note 3: Previously, the ansible package was provided in the Extras repository. This version has been deprecated and will no longer receive updates. It is recommended to either uninstall this version and its dependencies, or enable the Ansible Engine repository in order to receive errata updates. More information can be found in the article Ansible deprecated in the Extras repository.

Typically Ansible Engine and the RHEL System Roles only need to be installed on a single, or few, Control node(s) which can then be used to manage or configure client nodes. While the roles will likely work with earlier versions, compatibility is only tested against RHEL 6.10 and later clients.

Getting Started

Installing RHEL System Roles and Ansible

The rhel-system-roles and ansible RPM packages are provided in the RHEL Extras and Ansible Engine repositories respectively.

• Use subscription-manager to list the Ansible Engine repositories available. Note that the generic "2" repository will always provide the latest release of the 2.X stream as opposed to configuring a more specific version such as 2.8.
  NOTE: Ansible Engine 2.8 is recommended even when running on a RHEL 7 control node when managing RHEL 8 managed nodes to properly handle the transition to python3.

  # subscription-manager refresh
  # subscription-manager  repos  --list  | grep ansible
  

• To persistently enable the Ansible Engine repository for RHEL 8 using Red Hat Subscription Manager:

  # subscription-manager repos --enable ansible-2-for-rhel-8-x86_64-rpms
  # yum install  rhel-system-roles  ansible
  

• To persistently enable the RHEL 7 Extras repository and install using Red Hat Subscription Manager (Server is used in this example):

  # subscription-manager  repos --enable=rhel-7-server-extras-rpms   --enable=rhel-7-server-ansible-2-rpms
  # yum install  rhel-system-roles  ansible
  

• To temporarily enable the RHEL 7 Extras and Ansible Engine repositories and install:

  # yum  --enablerepo=rhel-7-server-extras-rpms  --enablerepo=rhel-7-server-ansible-2-rpms \ 
      install  rhel-system-roles  ansible
  

Documentation

The rhel-system-roles package will install by default to the following locations where SUBSYSTEM is the name of the subsystem that contains the individual role manages. Examples may include network, timesync, or other subsystems as they become supported. Each subsystem role will include a README file which documents how to use the role and supported parameter values, as well as the matching README in the linux-system-roles Ansible Galaxy landing space.

• Documentation

      /usr/share/doc/rhel-system-roles-<version>/SUBSYSTEM/
  

• Ansible Roles

      /usr/share/ansible/roles/rhel-system-roles.SUBSYSTEM/
  

Example usage of the rhel-system-roles.network role

This example assumes the following

• Generally, Ansible is not installed on every system, but rather on a single system designated as the Ansible management or control node who's purpose is to manage other systems via Ansible.
• This example is executed from a RHEL 7.5 system used as the Ansible control node.
• A target, or client test system with a hostname of rhel7.5-test
• rhel7.5-test has a primary network interface to access (eth0), and a secondary interface for this example (eth1).
• Either the rhel7.5-test FQDN or IP Address has been added to the Ansible Inventory file /etc/ansible/hosts on the control node.
• The control node user ID running the test playbook has ssh access to, and sudo ability on rhel7.5-test. Alternatively, the -u option can be used to specify a user which does have this ability.
• For further details, see the Ansible Getting Started or Quick Start Video at http://docs.ansible.com/ for further details on how to use Ansible.

1. Using a text editor, create a file containing contents similar to the following:

   $ vim example-network-playbook.yml
   ---
   - hosts: rhel7.5-test
     vars:
       network_connections:
         - name: DBnic
           state: up
           type: ethernet
           interface_name: eth1
           autoconnect: yes
           ip:
             dhcp4: yes
             auto6: no
     roles:
       - role: rhel-system-roles.network
   

2. Test that we have access to the machine. If not, refer to the Ansible documentation on how to enable Ansible to access a remote system.

   $ ansible -m ping rhel7.5-test
   rhel7.5-test | SUCCESS => {
       "changed": false, 
       "ping": "pong"
   }
   

3. Query the Ansible Facts to see the guests network configuration.

   $ ansible rhel7.5-test -m setup -a 'gather_subset=network filter=ansible_interfaces' 
   
   rhel7.5-test | SUCCESS => {
       "ansible_facts": {
           "ansible_interfaces": [
               "lo", 
               "eth1", 
               "eth0"
           ]
       }, 
       "changed": false
   }
   

4. Query the Ansible Facts to see the characteristics of eth1

   $ ansible rhel7.5-test -m setup -a 'gather_subset=network filter=ansible_eth1' 
   rhel7.5-test | SUCCESS => {
       "ansible_facts": {
           "ansible_eth1": {
               "active": true, 
               "device": "eth1", 
               "features": {
                   "busy_poll": "off [fixed]", 
                   "fcoe_mtu": "off [fixed]", 
                   "generic_receive_offload": "on", 
                   "generic_segmentation_offload": "on", 
                   "highdma": "on [fixed]", 
                   "hw_tc_offload": "off [fixed]", 
                   "l2_fwd_offload": "off [fixed]", 
                   "large_receive_offload": "off [fixed]", 
                   "loopback": "off [fixed]", 
                   "netns_local": "off [fixed]", 
                   "ntuple_filters": "off [fixed]", 
                   "receive_hashing": "off [fixed]", 
                   "rx_all": "off [fixed]", 
                   "rx_checksumming": "on [fixed]", 
                   "rx_fcs": "off [fixed]", 
                   "rx_vlan_filter": "on [fixed]", 
                   "rx_vlan_offload": "off [fixed]", 
                   "rx_vlan_stag_filter": "off [fixed]", 
                   "rx_vlan_stag_hw_parse": "off [fixed]", 
                   "scatter_gather": "on", 
                   "tcp_segmentation_offload": "on", 
                   "tx_checksum_fcoe_crc": "off [fixed]", 
                   "tx_checksum_ip_generic": "on", 
                   "tx_checksum_ipv4": "off [fixed]", 
                   "tx_checksum_ipv6": "off [fixed]", 
                   "tx_checksum_sctp": "off [fixed]", 
                   "tx_checksumming": "on", 
                   "tx_fcoe_segmentation": "off [fixed]", 
                   "tx_gre_segmentation": "off [fixed]", 
                   "tx_gso_robust": "off [fixed]", 
                   "tx_ipip_segmentation": "off [fixed]", 
                   "tx_lockless": "off [fixed]", 
                   "tx_mpls_segmentation": "off [fixed]", 
                   "tx_nocache_copy": "off", 
                   "tx_scatter_gather": "on", 
                   "tx_scatter_gather_fraglist": "off [fixed]", 
                   "tx_sctp_segmentation": "off [fixed]", 
                   "tx_sit_segmentation": "off [fixed]", 
                   "tx_tcp6_segmentation": "on", 
                   "tx_tcp_ecn_segmentation": "on", 
                   "tx_tcp_segmentation": "on", 
                   "tx_udp_tnl_segmentation": "off [fixed]", 
                   "tx_vlan_offload": "off [fixed]", 
                   "tx_vlan_stag_hw_insert": "off [fixed]", 
                   "udp_fragmentation_offload": "on", 
                   "vlan_challenged": "off [fixed]"
               }, 
               "macaddress": "52:54:00:e1:c2:4c", 
               "module": "virtio_net", 
               "mtu": 1500, 
               "pciid": "virtio4", 
               "promisc": false, 
               "type": "ether"
           }
       }, 
       "changed": false
   }
   

5. Execute your example playbook. Note: You may safely ignore the warning message for now that the “wait for activation” feature is not yet implemented.

   $ ansible-playbook -l rhel7.5-test example-network-playbook.yml
   PLAY [rhel7.5-test] *********************************************************************
   
   TASK [Gathering Facts] *********************************************************
   ok: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Check which services are running] ************
   ok: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Check which packages are installed] **********
   ok: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Install packages] ****************************
   skipping: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Enable network service] **********************
   ok: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Print network provider] **********************
   ok: [rhel7.5-test] => {
       "msg": "Using network provider: nm"
   }
   
   TASK [rhel-system-roles.network : Configure networking connection profiles] ****
    [WARNING]: [003] <info>  #0, state:up persistent_state:present, 'DBnic': add
   connection DBnic, b62a7ea6-f1a4-408a-843e-ea292aa58b44
   
    [WARNING]: [004] <info>  #0, state:up persistent_state:present, 'DBnic': up
   connection DBnic, b62a7ea6-f1a4-408a-843e-ea292aa58b44 (is-modified)
   
   changed: [rhel7.5-test]
   
   TASK [rhel-system-roles.network : Re-test connectivity] ************************
   ok: [rhel7.5-test]
   
   PLAY RECAP *********************************************************************
   rhel7.5-test : ok=7    changed=1    unreachable=0    failed=0   
   

6. Query again to see that eth1 is now online and has a IP Address assigned.

   $ ansible rhel7.5-test -m setup -a 'gather_subset=network filter=ansible_eth1' 
   
   rhel7.5-test | SUCCESS => {
       "ansible_facts": {
           "ansible_eth1": {
               "active": true, 
               "device": "eth1", 
               "features": {
                   "busy_poll": "off [fixed]", 
                   "fcoe_mtu": "off [fixed]", 
                   "generic_receive_offload": "on", 
                   "generic_segmentation_offload": "on", 
                   "highdma": "on [fixed]", 
                   "hw_tc_offload": "off [fixed]", 
                   "l2_fwd_offload": "off [fixed]", 
                   "large_receive_offload": "off [fixed]", 
                   "loopback": "off [fixed]", 
                   "netns_local": "off [fixed]", 
                   "ntuple_filters": "off [fixed]", 
                   "receive_hashing": "off [fixed]", 
                   "rx_all": "off [fixed]", 
                   "rx_checksumming": "on [fixed]", 
                   "rx_fcs": "off [fixed]", 
                   "rx_vlan_filter": "on [fixed]", 
                   "rx_vlan_offload": "off [fixed]", 
                   "rx_vlan_stag_filter": "off [fixed]", 
                   "rx_vlan_stag_hw_parse": "off [fixed]", 
                   "scatter_gather": "on", 
                   "tcp_segmentation_offload": "on", 
                   "tx_checksum_fcoe_crc": "off [fixed]", 
                   "tx_checksum_ip_generic": "on", 
                   "tx_checksum_ipv4": "off [fixed]", 
                   "tx_checksum_ipv6": "off [fixed]", 
                   "tx_checksum_sctp": "off [fixed]", 
                   "tx_checksumming": "on", 
                   "tx_fcoe_segmentation": "off [fixed]", 
                   "tx_gre_segmentation": "off [fixed]", 
                   "tx_gso_robust": "off [fixed]", 
                   "tx_ipip_segmentation": "off [fixed]", 
                   "tx_lockless": "off [fixed]", 
                   "tx_mpls_segmentation": "off [fixed]", 
                   "tx_nocache_copy": "off", 
                   "tx_scatter_gather": "on", 
                   "tx_scatter_gather_fraglist": "off [fixed]", 
                   "tx_sctp_segmentation": "off [fixed]", 
                   "tx_sit_segmentation": "off [fixed]", 
                   "tx_tcp6_segmentation": "on", 
                   "tx_tcp_ecn_segmentation": "on", 
                   "tx_tcp_segmentation": "on", 
                   "tx_udp_tnl_segmentation": "off [fixed]", 
                   "tx_vlan_offload": "off [fixed]", 
                   "tx_vlan_stag_hw_insert": "off [fixed]", 
                   "udp_fragmentation_offload": "on", 
                   "vlan_challenged": "off [fixed]"
               }, 
               "ipv4": {
                   "address": "192.168.122.216", 
                   "broadcast": "192.168.122.255", 
                   "netmask": "255.255.255.0", 
                   "network": "192.168.122.0"
               }, 
               "ipv6": [
                   {
                       "address": "fe80::5054:ff:fee1:c24c", 
                       "prefix": "64", 
                       "scope": "link"
                   }
               ], 
               "macaddress": "52:54:00:e1:c2:4c", 
               "module": "virtio_net", 
               "mtu": 1500, 
               "pciid": "virtio4", 
               "promisc": false, 
               "type": "ether"
           }
       }, 
       "changed": false
   }
   

More examples

The roles carry their own example playbooks under their respective documentation directories (see above).