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 the+sysfs+
group.+name+
is omitted when using+replaced+
. -
+value+
- Usually Required - The value for the setting.+value+
is omitted when using+state+
or+previous+
. Values must not be YAML bool type. One situation where this might be a problem is using+value: on+
or other YAML+bool+
typed value. You must quote these values, or otherwise pass them as a value of+str+
type e.g.+value: "on"+
. -
+state+
- Optional - the value+absent+
means to remove a setting with name+name+
from a group -+name+
must be provided -
+previous+
- Optional - the only value is+replaced+
- 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:
- fedora.linux_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)