Kernel Settings Role

This role is for changing kernel settings on your system. It modifies settings found in locations like /proc/sys (using the sysctl command), /sys/fs, and others. On Enterprise Linux, such as RHEL and CentOS, it utilizes the tuned system.

• Visit tuned homepage - here

Requirements

Collection requirements

To manage rpm-ostree systems with this role, you'll need to install extra collections. Run this command to do so:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Role Variables

The kernel_settings_GROUP parameters contain settings defined as a list of dictionaries. Each dictionary has these keys:

• name - Usually Required - The name of the setting or the file under /sys for the sysfs group. Skip name if using replaced.
• value - Usually Required - The value assigned to that setting. Skip value if using state or previous. Make sure that values do not get interpreted as YAML boolean types. Quote these values, e.g., value: "on".
• state - Optional - Use absent to remove a setting identified by name.
• previous - Optional - Only replaced can be used to indicate previous values should be replaced with the new values.

kernel_settings_sysctl

A list of settings to apply using sysctl. These settings are additive by default, adding to existing settings or replacing those with the same name. To remove a specific setting, use state: absent instead of providing a value. Use previous: replaced to replace existing settings with new ones. To remove all sysctl settings, use {"state": "empty"} instead of a list. See examples below.

kernel_settings_sysfs

Similar to kernel_settings_sysctl, this is a list that applies settings to /sys with the same rules: additive unless specified otherwise.

kernel_settings_systemd_cpu_affinity

Set the CPU affinity value as specified here. To remove this setting, use {"state": "absent"}.

kernel_settings_transparent_hugepages

To set the value, choose from always, madvise, or never. To remove, use {"state": "absent"} in place of the string.

kernel_settings_transparent_hugepages_defrag

Set this with one of these values: always, defer, defer+madvise, madvise, or never. To remove it, use the dict value {"state": "absent"}.

kernel_settings_purge

Default is false. If set to true, this will wipe all existing configuration and replace it with your specified settings.

kernel_settings_reboot_ok

Default is false. If true, the role will reboot the host if it detects changes requiring a reboot. If false, you must manage when to reboot. A variable, kernel_settings_reboot_required, will be returned indicating if a reboot is necessary.

kernel_settings_transactional_update_reboot_ok

Use this variable for managing reboots from transactional updates. If set to true, a reboot will automatically occur. If false, the user will be alerted for manual handling. If not set, the role will ensure that reboot needs are not overlooked.

Variables Exported by the Role

The role will export the variable:

kernel_settings_reboot_required - default false. If true, a reboot is necessary for the changes to take effect.

Examples of Settings Usage

kernel_settings_sysctl:
  - name: fs.epoll.max_user_watches
    value: 785592
  - name: fs.file-max
    value: 379724
kernel_settings_sysfs:
  - name: /sys/kernel/debug/x86/pti_enabled
    value: 0
  - name: /sys/kernel/debug/x86/retp_enabled
    value: 0
  - name: /sys/kernel/debug/x86/ibrs_enabled
    value: 0
kernel_settings_systemd_cpu_affinity: "1,3,5,7"
kernel_settings_transparent_hugepages: madvise
kernel_settings_transparent_hugepages_defrag: defer

Note: The settings are additive. This means they are added to existing settings. For example, if you initially set:

kernel_settings_sysctl:
  - name: kernel.threads-max
    value: 29968
  - name: vm.max_map_count
    value: 65530

After applying the previous example, you would get:

kernel_settings_sysctl:
  - name: kernel.threads-max
    value: 29968
  - name: vm.max_map_count
    value: 65530
  - name: fs.epoll.max_user_watches
    value: 785592
  - name: fs.file-max
    value: 379724

This lets multiple roles or playbooks collaborate to set kernel settings as needed. If both a web server and database server need kernel settings, this role can be used for both.

When you specify multiple settings with the same name, the last one will take precedence.

To replace all settings in a group with new ones, start the list with previous: replaced:

kernel_settings_sysctl:
  - previous: replaced
  - name: kernel.threads-max
    value: 30000
  - name: vm.max_map_count
    value: 50000

To remove a single setting, use state: absent:

kernel_settings_sysctl:
  - name: kernel.threads-max
    value: 30000
  - name: vm.max_map_count
    state: absent

To clear all settings from a group, use:

kernel_settings_sysctl:
  state: empty

To remove a scalar parameter, use:

kernel_settings_systemd_cpu_affinity:
  state: absent
kernel_settings_transparent_hugepages:
  state: absent
kernel_settings_transparent_hugepages_defrag:
  state: absent

Example Playbook

- name: Manage kernel settings
  hosts: all
  vars:
    kernel_settings_sysctl:
      - name: fs.epoll.max_user_watches
        value: 785592
      - name: fs.file-max
        value: 379724
      - name: kernel.threads-max
        state: absent
    kernel_settings_sysfs:
      - name: /sys/kernel/debug/x86/pti_enabled
        value: 0
      - name: /sys/kernel/debug/x86/retp_enabled
        value: 0
      - name: /sys/kernel/debug/x86/ibrs_enabled
        value: 0
    kernel_settings_systemd_cpu_affinity: "1,3,5,7"
    kernel_settings_transparent_hugepages: madvise
    kernel_settings_transparent_hugepages_defrag: defer
  roles:
    - linux-system-roles.kernel_settings

Warnings

The kernel_settings role may cause conflicts with other sysctl settings that are manually set or configured via system packages, which can override or conflict with their own settings.

The precedence for sysctl settings is:

1. Settings from sysctl files (/etc/sysctl.conf and /etc/sysctl.d/*)
2. Settings from the kernel_settings role
3. Manually set sysctl commands

For other settings like sysfs, the kernel_settings role takes the highest precedence.

rpm-ostree

Refer to README-ostree.md.

License

Parts related to tuned are licensed under GPLv2+, noted in file headers. Everything else is under MIT unless otherwise specified. Check the LICENSE file for details.

Author Information

Rich Megginson (GitHub: richm, Email: rmeggins@mycompany)