Kernel Settings Role
This role is used to modify kernel settings. For example, on Linux,
settings in /proc/sys
(using sysctl
), /sys/fs
, and some other
settings. It uses tuned
for its default provider on Enterprise Linux
and derivatives (RHEL and CentOS) and Fedora.
-
tuned
homepage - https://github.com/redhat-performance/tuned
Requirements
This role requires an operating system which has the tuned
package and
service (for the default tuned
provider).
Role Variables
The values for some of the various kernel_settings_GROUP
parameters
are a list
of dict
objects. Each dict
has the following keys:
-
name
- Usually Required - The name the setting, or the name of a file under/sys
for thesysfs
group.name
is omitted when usingreplaced
. -
value
- Usually Required - The value for the setting.value
is omitted when usingstate
orprevious
. Values must not be YAML bool type. One situation where this might be a problem is usingvalue: on
or other YAMLbool
typed value. You must quote these values, or otherwise pass them as a value ofstr
type e.g.value: "on"
. -
state
- Optional - the valueabsent
means to remove a setting with namename
from a group -name
must be provided -
previous
- Optional - the only value isreplaced
- this is used to specify that the previous values in a group should be replaced with the given values.
kernel_settings_sysctl
- A list
of settings to be applied using
sysctl
. The settings are given in the format described above. Note
that the settings are additive - by default, each setting is added to
the existing settings, or replaces the setting of the same name if it
already exists. If you want to remove a specific setting, use
state: absent
instead of giving a value
. If you want to remove all
of the existing sysctl
settings and replace them with the given
settings, specify previous: replaced
as one of the values in the list.
If you want to remove all of the sysctl
settings, use the dict
value
{"state": "empty"}
, instead of a list
, as the only value for the
parameter. See below for examples.
kernel_settings_sysfs
- A list
of settings to be applied to /sys
.
The settings are given in the format described above. Note that the
settings are additive - by default, each setting is added to the
existing settings, or replaces the setting of the same name if it
already exists. If you want to remove a specific setting, use
state: absent
instead of giving a value
. If you want to remove all
of the existing sysfs
settings and replace them with the given
settings, specify previous: replaced
as one of the values in the list.
If you want to remove all of the sysfs
settings, use the dict
value
{"state": "empty"}
, instead of a list
, as the only value for the
parameter. See below for examples.
kernel_settings_systemd_cpu_affinity
- To set the value, specify a
string
in the format specified by
https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html#CPUAffinity=
If you want to remove the setting, use the dict
value
{"state": "absent"}
, instead of a string
, as the value for the
parameter.
kernel_settings_transparent_hugepages
- To set the value, specify one
of the following string
values: always
madvise
never
. This is
the memory subsystem transparent hugepages value. If you want to remove
the setting, use the dict
value {"state": "absent"}
, instead of a
string
, as the value for the parameter.
kernel_settings_transparent_hugepages_defrag
- To set the value,
specify one of the following string
values: always
defer
defer+madvise
madvise
never
. This is the memory subsystem
transparent hugepages fragmentation handling value. The actual supported
values may be different depending on your OS. If you want to remove the
setting, use the dict
value {"state": "absent"}
, instead of a
string
, as the value for the parameter.
kernel_settings_purge
- default false
- If true
, then the existing
configuration will be completely wiped out and replaced with your given
kernel_settings_GROUP
settings.
kernel_settings_reboot_ok
- default false
- If true
, then if the
role detects that something was changed that requires a reboot to take
effect, the role will reboot the managed host. If false
, it is up to
you to determine when to reboot the managed host. The role will return
the variable kernel_settings_reboot_required
(see below) with a value
of true
to indicate that some change has occurred which needs a reboot
to take effect.
Variables Exported by the Role
The role will export the following variables:
kernel_settings_reboot_required
- default false
- if true
, this
means a change has occurred which will require rebooting the managed
host in order to take effect. If you want the role to reboot the managed
host, set kernel_settings_reboot_ok: true
, otherwise, you will need to
handle rebooting the machine.
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 that the list
valued settings are additive. That is, they are
applied in addition to any current settings. For example, if you
already had
kernel_settings_sysctl:
- name: kernel.threads-max
value: 29968
- name: vm.max_map_count
value: 65530
then after applying the above, you would have
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 allows multiple higher level roles or playbooks to use this role to
provide the kernel settings specific to that component. For example, if
you are installing a web server and a database server on the same
machine, and they both require setting kernel parameters, the
kernel_settings
role allows you to set them both.
If you specify multiple settings with the same name in a section, the last one will be used.
If you want to replace all of the settings in a section with your
supplied values, use previous: replaced
as a single, preferably first
element in the list of settings. This indicates that the previous
settings in the system should be replaced
with the given settings. For
example:
kernel_settings_sysctl:
- previous: replaced
- name: kernel.threads-max
value: 30000
- name: vm.max_map_count
value: 50000
This will have the effect of removing all of the existing settings for
kernel_settings_sysctl
, and adding the specified settings. If you want
to remove a single setting, specify state: absent
in the individual
setting, instead of a value
:
kernel_settings_sysctl:
- name: kernel.threads-max
value: 30000
- name: vm.max_map_count
state: absent
This will remove the vm.max_map_count
setting from the
kernel_settings_sysctl
settings. If you want to remove all of the
settings from a group, specify state: empty
as a dict
instead of a
list
:
kernel_settings_sysctl:
state: empty
This will have the effect of removing all of the
kernel_settings_sysctl
settings.
Use {"state":"absent"}
to remove a scalar valued parameter. For
example, to remove all of kernel_settings_systemd_cpu_affinity
,
kernel_settings_transparent_hugepages
, and
kernel_settings_transparent_hugepages_defrag
settings, use this:
kernel_settings_systemd_cpu_affinity:
state: absent
kernel_settings_transparent_hugepages:
state: absent
kernel_settings_transparent_hugepages_defrag:
state: absent
Dependencies
The tuned
package is required for the default provider.
Example Playbook
- 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:
- redhat.rhel_system_roles.kernel_settings
Warnings
The kernel_settings
role will cause other sysctl
settings to be
applied when using the tuned
implementation, which is the default.
This can happen when you manually edit /etc/sysctl.d/
files, or if the
sysctl.d
files are installed by some system package. For example, on
Fedora, installing the libreswan
package provides
/etc/sysctl.d/50-libreswan.conf
. Using the kernel_settings
role will
cause this file to be reloaded and reapplied. If this behavior is not
desired, you will need to edit the tuned
configuration on the managed
hosts in /etc/tuned/tuned-main.conf
and set reapply_sysctl=0
.
The settings you apply with the kernel_settings
role may conflict with
other settings. For example, if you manually run the sysctl
command,
or manually edit /etc/sysctl.d/
files, or if the sysctl.d
files are
installed by some system package, they may set the same values you are
setting with the kernel_settings
role. For sysctl
settings, the
precedence goes like this:
-
sysctl
files have highest precedence -/etc/sysctl.conf
and/etc/sysctl.d/*
will override everything -
kernel_settings
role settings have the next highest precedence -
settings set manually using the
sysctl
command have the lowest precedence
For all other settings such as sysfs
, the settings from
kernel_settings
role have the highest precedence.
License
Some parts related to tuned
are GPLv2+
. These are noted in the
headers of the files. Everything else is MIT
, except where noted. See
the file LICENSE
for more information.
Author Information
Rich Megginson (richm on github, rmeggins at my company)