Red Hat Enterprise Linux System Roles for SAP

Updated -

Contents

1. Overview

Red Hat Enterprise Linux (RHEL) 7 RHEA-2019:3190 introduced RHEL System Roles for SAP to assist with remotely or locally configuring a RHEL system for the installation of SAP HANA or SAP NetWeaver software. RHEL System Roles for SAP development is based on the Linux System Roles upstream project.

RHEL System Roles is a collection of roles executed by Ansible to assist administrators with server configuration right after the servers have been installed. These roles are provided in the RHEL Extras repository. In contrast, RHEL System Roles for SAP is provided in the RHEL for SAP Solutions subscription and can be used by Ansible Engine, Ansible Tower, and Red Hat Satellite 6.5 and later to manage RHEL systems.

RHEL subscriptions (e.g. Red Hat Enterprise Linux for x86_64) provide support for RHEL System Roles with Ansible Engine, which is available in the Ansible Engine repository (e.g. ansible-2-for-rhel-8-x86_64-rpms). However, if you require full support for the Ansible Engine itself, a separate Red Hat Ansible Automation Subscription is necessary. Additional information is available at Top Support Policies for Red Hat Ansible Automation.

The following RHEL System Roles for SAP are fully supported on control nodes running RHEL 8.3 and later:
- sap-preconfigure
- sap-netweaver-preconfigure
- sap-hana-preconfigure

These roles can be used to configure the local host running RHEL 8.3 or later, or remote hosts (called managed nodes in the context of Ansible) running RHEL 7.6 or later and RHEL 8.0 or later. See the following table for the support status:

Control Node Managed Node Support Status
RHEL 8.3 RHEL 8.0 or later fully supported
RHEL 8.3 RHEL 7.6 or later fully supported
RHEL 8.3 RHEL 7.5 or earlier not supported
RHEL 8.2 or earlier RHEL (any release) not supported(*)


Note: For control nodes running RHEL 7.8, RHEL 7.9, RHEL 8.1, or RHEL 8.2, you can use the previous versions of rhel-system-roles-sap which are in Tech Preview support status. Please find the instructions for these versions here.

See the table below for the supported hardware/virtualization/cloud platforms of the managed node:

Hardware platform Bare Metal/Virtualization/ Cloud platform Support Status
x86_64 bare metal, Red Hat Virtualization/libvirt, VMware ESX, Red Hat Certified Cloud and Service Providers fully supported
ppc64le PowerVM LPARs fully supported
s390x zVM guest fully supported: sap-preconfigure, sap-netweaver-preconfigure


Note: The roles are designed to be used right after the initial installation of a managed node. Do not run these roles against a SAP or other production system. The role will enforce a certain configuration on the managed node(s), which might not be intended.
Note: Before applying the roles on a managed node, verify that the RHEL release on the managed node is supported by the SAP software version that you are planning to install.

2. Installation

Use this procedure to install the Ansible Engine and the RHEL System Roles for SAP.

1) Use subscription-manager to list the available Ansible Engine repositories.
#subscription-manager refresh
#subscription-manager repos --list | grep ansible

2) Permanently enable the Ansible Engine repository and the RHEL for SAP Solutions repository using Red Hat Subscription Manager.
Note: The generic version "2" of the Ansible Engine repository provides the latest release of the 2.X stream but it is also possible to specify a certain minor Ansible Engine version such as 2.9.
#subscription-manager repos
--enable=ansible-2-for-rhel-8-$(uname -m)-rpms
--enable=rhel-8-for-$(uname -m)-sap-solutions-rpms

3) Install Ansible Engine and RHEL System Roles for SAP:
#dnf install ansible rhel-system-roles-sap

The rhel-system-roles-sap package is installed to the following locations where is the name of the individual role; for example, sap-hana-preconfigure. Each role includes a README file that explains all variables and how to use the role.

Documentation: /usr/share/doc/rhel-system-roles-sap/<role>
Ansible Roles: /usr/share/ansible/roles/<role>

3. Known issues

3.1 Roles produce limited output when run in check mode

Running roles in check mode will not show all changes which are performed on a system when running in normal mode, as some Ansible modules have no or just partial support for check mode. For example, tasks will not report the values of kernel parameters. For more information on the Ansible check mode, please refer to https://docs.ansible.com/ansible/latest/user_guide/playbooks_checkmode.html.

3.2 Role sap-preconfigure fails if DNS domain is not set on the managed node

In case there is no DNS domain set on the managed node, which is typically the case on cloud systems, the role sap-preconfigure will fail in task Verify that the DNS domain is set. To avoid this, set variable sap_domain in file /usr/share/ansible/roles/sap-preconfigure/defaults/main.yml or run the ansible-playbook command with line parameter
-e "sap_domain=example.com" (with the domain name being example.com in this case - please replace it by your domain name).

(sap-preconfigure issue #32)

3.3 Role sap-preconfigure incorrectly attempts to install compat-sap-c++-* packages on managed nodes running RHEL 7 on s390x

When running role sap-preconfigure against a managed node running RHEL 7 on s390x, it will attempt to install packages compat-sap-c++-5, compat-sap-c++-6, compat-sap-c++-7, and compat-sap-c++-9. As these packages are not part of repository rhel-sap-for-rhel-7-for-system-z-rpms, the task Ensure required packages are installed will fail. Use the following option to the ansible-playbook command as a workaround:
-e "{'__sap_preconfigure_packages': ["uuidd", "tcsh", "psmisc"]}"
Example:

#ansible-playbook sap.yml -l host01 -e "{'__sap_preconfigure_packages': ["uuidd", "tcsh", "psmisc"]}"

(sap-preconfigure issue #99)

3.4 Installation of package libssh2 missing from role sap-hana-preconfigure

Despite the initial plans to no longer ship package libssh2 in RHEL 8, this package is still available in RHEL 8 and can still be used to install SAP HANA as a scale out (distributed) configuration. However, the libssh2 package is currently not part of role sap-hana-preconfigure. If you want to configure your RHEL Systems for installation of SAP HANA in a scale out configuration, and if you want to use the default libssh2 instead of the saphostagent connection method when installing SAP HANA, install package libssh2 as part of your playbook or manually, e.g. via ssh. Alternatively, you can specify all packages of variable __sap_hana_preconfigure_packages which are contained in the role's vars/RedHat_8.yml file, plus libssh2, on the command line, similar to the previous example.

(sap-hana-preconfigure issue #118)

4. Quick Start

Use this procedure to configure one or more systems for the installation of SAP NetWeaver or SAP HANA.

4.1 Configure the local system

Prepare the local system for the installation of SAP NetWeaver

1) RHEL System Roles for SAP requires that the Ansible control node uses locale C or en_US.UTF-8 to display system messages in English. Run the following command on the local host to check the current setting:

#locale

The output should display either C or en_US.UTF-8 in the line starting with LC_MESSAGES=. If the locale command does not produce the expected output, run the following command on the local host before executing the ansible-playbook command:

#export LC_ALL=C

Or

#export LC_ALL=en_US.UTF-8

2) Make sure that there is no production software running on the system. The roles will enforce a certain configuration on the system, which typically is intended only right after the installation of RHEL and before the initial installation of SAP software.

3) In case you would like to preserve the original configuration of the server, perform a backup. Typically, these roles are run right after the installation of RHEL, so a backup should not be necessary.

4) Create a YAML file named sap-netweaver.yml with the following content:

- hosts: localhost
  connection: local
  roles:
    - sap-preconfigure
    - sap-netweaver-preconfigure

Note that the correct indentation (e.g. 2 spaces in front of roles:) is essential.

5) Make sure there is at least 20480 MB of swap space configured on the local system.

6) Run the RHEL System Roles sap-preconfigure and sap-netweaver-preconfigure to prepare the managed nodes for the installation of SAP NetWeaver.

#ansible-playbook sap-netweaver.yml

At the end of the playbook run, the command will report that a reboot is required because role sap-preconfigure has changed the SELinux state from enabled to disabled, according to SAP note 2772999.

7) Reboot the managed nodes so that the new SELinux state will become effective.

Note: By changing role variable sap_preconfigure_selinux_state from the default disabled to permissive before or at the time of running the playbook, you can have the role sap-preconfigure set the SELinux state to permissive, which is also allowed for SAP NetWeaver on RHEL 8. See the Examples section in this document for more information on setting role variables.

4.2 Configure remote systems

Prepare the control node and ssh access to all managed nodes

1) Verify that the managed nodes are correctly set up for installing Red Hat software packages from a Red Hat Satellite server or the Red Hat Customer Portal.

2) RHEL System Roles for SAP requires that the Ansible control node uses locale C or en_US.UTF-8 to display system messages in English. Run the following command on the Ansible control node to check the current setting:
#locale
The output should display either C or en_US.UTF-8 in the line starting with LC_MESSAGES=. If the locale command does not produce the expected output, run the following command on the Ansible control node before executing the ansible-playbook command:

#export LC_ALL=C

Or

#export LC_ALL=en_US.UTF-8

3) Make sure that you can log in via the ssh command to all managed nodes from the Ansible control node without using a password. See the man pages for ssh-copy-idand man ssh if you need more information about this topic.

Prepare one or more remote servers (managed nodes) for the Installation of SAP HANA

1) Verify that there is no production software running on any of the managed nodes you want to configure.

2) Make sure that the version of SAP HANA you will be installing is supported for the RHEL major and minor release which is installed on the managed nodes. For information on supported RHEL releases for SAP HANA, see SAP note 2235581.

3) In case you would like to preserve the original configuration of any of the servers, perform a backup of the server(s). Typically, these roles are run right after installation, so a backup should not be necessary.

4) Create an inventory file or modify file /etc/ansible/hosts so that it contains the name of a group of hosts and each host which you intend to configure (=managed node) in a separate line (example for three hosts in a host group named sap_hana):

[sap_hana]
host01
host02
host03

5) Use some simple commands to verify that you can log in to all three hosts using ssh without password:
#ssh host01 uname -a
#ssh host02 hostname
#ssh host03 echo test

6) Create a YAML file named sap-hana.yml with the following content:

- hosts: sap_hana
  roles:
    - sap-preconfigure
    - sap-hana-preconfigure

Note that the correct indentation (e.g. 2 spaces in front of roles:) is essential.

7) Run the RHEL System Roles sap-preconfigure and sap-hana-preconfigure to prepare prepare the managed nodes for the installation of SAP HANA.
Note: Do not run these roles against an SAP or other production system. The role will enforce a certain configuration on the managed node(s), which typically is intended only right after the installation of RHEL and before the initial installation of SAP software.

#ansible-playbook sap-hana.yml

At the end of the playbook run, the command will report for each managed node that a reboot is required, for example because role sap-preconfigure has changed the SELinux state from enabled to disabled (as per requirement in SAP notes 2292690 or 2777782).

8) Reboot the managed nodes so that the new SELinux state will become effective.

5. Detailed Description

This chapter describes the RHEL System Roles for SAP in detail.

The purpose of the three roles sap-preconfigure, sap-netweaver-preconfigure, and sap-hana-preconfigure is described in the following table:

System Role Purpose
sap-preconfigure Install software and perform all configuration steps which are required for the installation of SAP NetWeaver and SAP HANA.
sap-netweaver-preconfigure Install software and perform all configuration steps which are required for the installation of SAP NetWeaver only.
sap-hana-preconfigure Install additional software and perform additional configuration steps which are required for SAP HANA only.

5.1 System Roles and SAP Notes

The following table contains the System Role and the corresponding action or SAP Note for the RHEL release of the managed node.

System Role SAP Note for RHEL 7 SAP Note for RHEL 8
sap-preconfigure SAP Note 2002167 SAP Note 2772999
SAP Note 1391070
sap-netweaver-preconfigure SAP Note 2526952 (tuned profiles only) SAP Note 2526952 (tuned profiles only)
sap-hana-preconfigure Install required packages as per documents SAP HANA 2.0 running on RHEL 7.x and SAP HANA SPS 12 running on RHEL 7.x which are attached to SAP Note 2009879 Install required packages for SAP HANA as mentioned in SAP Note 2772999
ppc64le only: Install additional required packages as per https://www14.software.ibm.com/support/customercare/sas/f/lopdiags/home.html ppc64le only: Install additional required packages as per https://www14.software.ibm.com/support/customercare/sas/f/lopdiags/home.html
Perform configuration steps as per documents SAP HANA 2.0 running on RHEL 7.x and SAP HANA SPS 12 running on RHEL 7.x which are attached to SAP Note 2009879
ppc64le only: SAP Note 2055470 ppc64le only: SAP Note 2055470
SAP Note 2292690 SAP Note 2777782
SAP Note 2382421 SAP Note 2382421

5.2 Implemented SAP Notes

The following table contains the SAP Note and its purpose and scope. The RHEL column indicates the specific RHEL releases that the SAP Note supports.

SAP Note RHEL Title Purpose and scope
7 8
2002167 X Red Hat Enterprise Linux 7.x: Installation and Upgrade General RHEL 7 installation and configuration steps before installing SAP NetWeaver
1391070 X Linux UUID solutions Installation and configuration of uuidd
2772999 X Red Hat Enterprise Linux 8.x: Installation and Configuration General RHEL 8 installation and configuration steps, including uuidd, before installing SAP NetWeaver or SAP HANA
2526952 X X Red Hat Enterprise Linux for SAP Solutions Description of RHEL for SAP Solutions, including tuned-profiles
2009879 X SAP HANA Guidelines for Red Hat Enterprise Linux (RHEL) Operating System Kernel and OS settings for SAP HANA on RHEL 6.x and RHEL 7.x
2055470 X X HANA on POWER Planning and Installation Specifics - Central Note Specific installation and configuration steps for SAP HANA on POWER
2292690 X SAP HANA DB: Recommended OS settings for RHEL 7 Specific package requirements, Kernel and OS settings for SAP HANA on RHEL 7.x
2777782 X SAP HANA DB: Recommended OS Settings for RHEL 8 Specific package requirements, Kernel and OS settings for SAP HANA on RHEL 8.x
2382421 X X Optimizing the Network Configuration on HANA- and OS-Level Network-related kernel settings for SAP HANA

5.3 Role variables

In each role, default variable settings can be modified to change the behavior of the role. The README.md file of each role, located in directory /usr/share/ansible/roles/<role>, describes the purpose of these variables as well as their default settings. The variables are defined and can be changed in each role's file main.yml in directory /usr/share/ansible/roles/<role>/defaults. They can also be set by using the ansible-playbook command line parameter --extra-vars or -e. See the next section for examples.

Some of the variables are described in more detail below to explain their behavior and dependencies:

Kernel related variables in sap-hana-preconfigure

Kernel variables can be set either in the kernel command line via grub, or using tuned profile sap-hana. Use the following combinations of these variables in /usr/share/ansible/roles/sap-hana-preconfigure/defaults/main.yml for the cases described below:

Case 1: Use tuned profile sap-hana only

In case you would like to use tuned profile sap-hana only, leave the default settings in place:

sap_hana_preconfigure_switch_to_tuned_profile_sap_hana: yes
sap_hana_preconfigure_use_tuned_where_possible: yes
sap_hana_preconfigure_modify_grub_cmdline_linux: yes
sap_hana_preconfigure_run_grub2_mkconfig: yes

(You can also set sap_hana_preconfigure_modify_grub_cmdline_linux and sap_hana_preconfigure_run_grub2_mkconfig to no. However, these two variables do not not influence the role behavior in case sap_hana_preconfigure_use_tuned_where_possible is set to yes. So you can just leave these variables untouched.)

Case 2: Modify the kernel command line and also use tuned

In case you would like to modify the kernel command line and use tuned profile sap-hana for all other settings, change sap_hana_preconfigure_use_tuned_where_possible: from yes to no:

sap_hana_preconfigure_switch_to_tuned_profile_sap_hana: yes
sap_hana_preconfigure_use_tuned_where_possible:no
sap_hana_preconfigure_modify_grub_cmdline_linux: yes
sap_hana_preconfigure_run_grub2_mkconfig: yes

Case 3: Modify the kernel command line and not switch to tuned profile sap-hana

In case you would like to modify the kernel command line and not switch to tuned profile sap-hana (for example because you would like to configure all settings manually), change sap_hana_preconfigure_switch_to_tuned_profile_sap_hana and sap_hana_preconfigure_use_tuned_where_possible: from yes to no:

sap_hana_preconfigure_switch_to_tuned_profile_sap_hana:no
sap_hana_preconfigure_use_tuned_where_possible:no
sap_hana_preconfigure_modify_grub_cmdline_linux: yes
sap_hana_preconfigure_run_grub2_mkconfig: yes

6. Examples

As a preparation step for these examples, follow the instructions in section Quick Start, chapter Prepare the control node and ssh access to all managed nodes of this document.

6.1 Example for SAP NetWeaver

You want to configure the three RHEL 7.7 x86_64 systems (managed nodes) sap-test, sap-qa, and sap-prod (test, QA, and production) and RHEL 8.2 s390x system (managed node) sap-test-z for the installation of SAP NetWeaver. For system sap-test-z, you do not have access to the root user but to a user with id 0 and with name root2. You need to run the roles sap-preconfigure and sap-netweaver-preconfigure.

The default behavior of the role sap-preconfigure is to not update the managed node to the latest RHEL software level but you would really like to update all four managed nodes to the latest RHEL software level. You do not want to fail the roles due to less than 20480 MB of swap space being configured, and you do not want to fail the roles in case a reboot is required. Use the following steps:

1) Verify that there is no other production software running on any of the four managed nodes.

2) In case you would like to preserve the original configuration of any of the serves, perform a backup of the managed nodes(s). Typically, these roles are run right after RHEL installation, so a backup should not be necessary.

3) Create an inventory file or modify file /etc/ansible/hosts so that it contains the following lines:

[sap_netweaver]
sap-test
sap-qa
sap-prod
sap-test-z ansible_user=root2

4) Use some simple commands to verify that you can log in to all four managed nodes using ssh without password:
#ssh sap-test uname -a
#ssh sap-qa uname -a
#ssh sap-prod uname -a
#ssh root2@sap-test-z uname -a

5) Create a YAML file named sap-netweaver.yml with the following content:

- hosts: sap_netweaver
  roles:
    - sap-preconfigure
    - sap-netweaver-preconfigure

Note that the correct indentation (e.g. 2 spaces in front of roles:) is essential.

6) Run the following ansible-playbook command to configure the four managed nodes as described above:

#ansible-playbook sap-netweaver.yml -e "{'sap_preconfigure_update': yes,
'sap_preconfigure_fail_if_reboot_required': no,
'sap_netweaver_preconfigure_fail_if_not_enough_swap_space_configured': no}"

7) Reboot all four managed nodes to make sure all required configuration changes are in effect.

6.2 Example for SAP HANA

You want to configure RHEL 7.6 x86_64 server (managed node) hana-x-76 and RHEL 8.1 ppc64le (POWER9) PowerVM LPAR (managed node) hana-p-81 for the installation of SAP HANA. You have already verified in SAP note 2235581 that these RHEL releases are supported for the SAP HANA version you want to install, and you have also verified that your hardware vendor has certified the hardware for this SAP HANA version. You need to run the roles sap-preconfigure and sap-hana-preconfigure.

You would like the role sap-hana-preconfigure to enable the required repositories for SAP HANA and also set the RHEL minor release to the currently installed level (7.6 and 8.1) so a yum update will not cause the managed nodes to be updated beyond these minor releases. You also want the role to update to the latest software level of that minor RHEL release. Instead of the default behavior of the role, which is to not modify grub but only use tuned to set kernel and other parameters, you would like to have the boot command line modified for SAP HANA and also use tuned profile sap-hana for setting kernel parameters.

Use the following steps:

1) Verify that there is no production software running on any of the two managed nodes.

2) In case you would like to preserve the original configuration of any of the managed nodes, perform a backup of the server(s). Typically, these roles are run right after RHEL installation, so a backup should not be necessary.

3) Create an inventory file or modify file /etc/ansible/hosts so that it contains the following lines (in this example, the hosts have not been made part of a specific host group):

hana-x-76
hana-p-81

4) Use some simple commands to verify that you can log in to all three hosts using ssh without password:
#ssh hana-x-76 uname -a
#ssh hana-p-81 uname -a

5) Create a YAML file named sap-hana.yml with the following content:

- hosts: all
  roles:
    - sap-preconfigure
    - sap-hana-preconfigure

Note that the correct indentation (e.g. 2 spaces in front of roles:) is essential.

6) Modify file /usr/share/ansible/roles/sap-hana-preconfigure/defaults/main.yml to contain the following lines instead of the defaults:

sap_hana_preconfigure_enable_sap_hana_repos:yes

sap_hana_preconfigure_set_minor_release:yes

sap_hana_preconfigure_use_tuned_where_possible:no

7) Run the following ansible-playbook command to configure the two managed nodes. Note that in this example, - hosts: all is used in the playbook and there is no group name for the hosts in file /etc/ansible/hosts, so the names of the hosts have to be specified after the -l command line parameter:

# ansible-playbook -l hana-x-76,hana-p-81 sap-hana.yml

8) Reboot all managed nodes to make sure all required configuration changes are in effect.