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 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.
In addition, the value of a kernel_settings_GROUP
may be specified not
as a list
, but as the dict
value {"state":"empty"}
. This means to
remove all of the settings for a group. See below for examples
See below for examples.
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
- A space delimited list of cpu
numbers. See
https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html#CPUAffinity=
kernel_settings_systemd_cpu_affinity_state
- Set this to absent
to
remove the setting kernel_settings_systemd_cpu_affinity
, which will be
reverted back to the system default value upon reboot.
kernel_settings_transparent_hugepages
- One of the following values:
always
madvise
never
. This is the memory subsystem transparent
hugepages value.
kernel_settings_transparent_hugepages_state
- Set this to absent
to
remove the setting kernel_settings_transparent_hugepages
, which will
be reverted back to the system default value upon reboot.
kernel_settings_transparent_hugepages_defrag
- One of these 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.
kernel_settings_transparent_hugepages_defrag_state
- Set this to
absent
to remove the setting
kernel_settings_transparent_hugepages_defrag
, which will be reverted
back to the system default value upon reboot.
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_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.
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_transparent_hugepages: madvise
kernel_settings_transparent_hugepages_defrag: defer
roles:
- 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)