ansible.posix.sysctl Module: Set Kernel Parameters Persistently (Guide)

By Luca Berton · Published 2022-01-11 · Category: troubleshooting

How to set Linux kernel parameters with ansible.posix.sysctl module. Configure sysctl settings persistently, network tuning, security hardening.

ansible.posix.sysctl Module: Set Kernel Parameters Persistently (Guide)

How to set the sysctl kernel parameters with Ansible?

ansible.posix.sysctl is the Ansible module for configuring Linux kernel parameters persistently. It modifies /etc/sysctl.conf entries to tune networking (TCP/IP stack), memory (swap, cache), and security settings—with changes that survive system reboots and apply immediately when sysctl_set: true and reload: true are set.

The full name is ansible.posix.sysctl, part of the "ansible.posix" collection for POSIX-compliant systems. The module's purpose is to manage sysctl.conf entries idempotently—ensuring your kernel parameters are always at the desired state, whether you're tuning for performance, security, or container orchestration (Docker/Kubernetes).

Parameters

name string (key) - Parameter name
value string - Parameter value
reload boolean - yes/no
state string - present/absent
sysctl_file string - "/etc/sysctl.conf"
sysctl_set string - no/yes - sysctl -w
ignoreerrors boolean - no/yes

Let me summarize the parameters of sysctl module. The only required is "name", where you specify the parameter name to access or edit. The parameter "value" sets the value of the sysctl parameter. The parameter "reload", default to yes, reload the configuration file if any changes occur. The parameter "state" sets the presence or absence of the parameter in the sysctl file. The parameter "sysctl_file" allows specifying the configuration file for sysctl, default to "/etc/sysctl.conf". The parameter "sysctl_set" allows you to configure a parameter permanently, that survives after reboot. The parameter "ignoreerrors" allow you to ignore errors about unknown keys, default to "no".

Links

https://docs.ansible.com/ansible/latest/collections/ansible/posix/sysctl_module.html

## Playbook

Ansible set sysctl kernel parameters.

code

---
- name: sysctl module Playbook
  hosts: all
  become: true
  vars:
    sysctl_name: "vm.swappiness"
    sysctl_value: "5"
  tasks:
    - name: set sysctl
      ansible.posix.sysctl:
        name: "{{ sysctl_name }}"
        value: "{{ sysctl_value }}"
        state: present
        sysctl_set: true
        reload: true

execution

$ ansible-playbook -i virtualmachines/demo/inventory sysctl/sysctl.yml
PLAY [sysctl module Playbook] *************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [ansible.posix.sysctl] ***********************************************************************
changed: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

idempotency

$ ansible-playbook -i virtualmachines/demo/inventory sysctl/sysctl.yml
PLAY [sysctl module Playbook] *************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [ansible.posix.sysctl] ***********************************************************************
ok: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

before execution

$ ssh devops@demo.example.com
Last login: Fri Jan  7 07:26:29 2022 from 192.168.0.102
[devops@demo ~]$ sudo su
[root@demo devops]# sysctl -a | less
[root@demo devops]# sysctl vm.swappiness
vm.swappiness = 30
[root@demo devops]# cat /etc/sysctl.conf
# sysctl settings are defined through files in
# /usr/lib/sysctl.d/, /run/sysctl.d/, and /etc/sysctl.d/.
#
# Vendors settings live in /usr/lib/sysctl.d/.
# To override a whole file, create a new file with the same in
# /etc/sysctl.d/ and put new settings there. To override
# only specific settings, add a file with a lexically later
# name in /etc/sysctl.d/ and put new settings there.
#
# For more information, see sysctl.conf(5) and sysctl.d(5).
net.ipv6.conf.all.disable_ipv6=1
[root@demo devops]#

after execution

$ ssh devops@demo.example.com
Last login: Tue Jan 11 17:41:18 2022 from 192.168.0.102
[devops@demo ~]$ sudo su
[root@demo devops]# sysctl vm.swappiness
vm.swappiness = 5
[root@demo devops]# reboot
Connection to demo.example.com closed by remote host.
Connection to demo.example.com closed.
ansible-pilot $ ssh devops@demo.example.com
Last login: Tue Jan 11 17:41:44 2022 from 192.168.0.102
[devops@demo ~]$ sudo su
[root@demo devops]# sysctl vm.swappiness
vm.swappiness = 5
[root@demo devops]# cat /etc/sysctl.conf
# sysctl settings are defined through files in
# /usr/lib/sysctl.d/, /run/sysctl.d/, and /etc/sysctl.d/.
#
# Vendors settings live in /usr/lib/sysctl.d/.
# To override a whole file, create a new file with the same in
# /etc/sysctl.d/ and put new settings there. To override
# only specific settings, add a file with a lexically later
# name in /etc/sysctl.d/ and put new settings there.
#
# For more information, see sysctl.conf(5) and sysctl.d(5).
net.ipv6.conf.all.disable_ipv6=1
vm.swappiness=5
[root@demo devops]# uname -a
Linux demo.example.com 4.18.0-348.el8.x86_64 #1 SMP Mon Oct 4 12:17:22 EDT 2021 x86_64 x86_64 x86_64 GNU/Linux
[root@demo devops]#

code with ❤️ in GitHub

Conclusion

Now you know how to set or verify sysctl kernel parameters with Ansible.

Set Kernel Parameter

- name: Enable IP forwarding
  ansible.posix.sysctl:
    name: net.ipv4.ip_forward
    value: '1'
    sysctl_set: true
    state: present
    reload: true
  become: true

Common Network Tuning

- ansible.posix.sysctl:
    name: "{{ item.name }}"
    value: "{{ item.value }}"
    sysctl_set: true
    reload: true
  loop:
    - { name: net.ipv4.ip_forward, value: '1' }
    - { name: net.core.somaxconn, value: '65535' }
    - { name: net.ipv4.tcp_max_syn_backlog, value: '65535' }
    - { name: net.core.netdev_max_backlog, value: '65535' }
    - { name: net.ipv4.tcp_fin_timeout, value: '15' }
    - { name: net.ipv4.tcp_keepalive_time, value: '300' }
    - { name: net.ipv4.tcp_tw_reuse, value: '1' }
  become: true

Memory Tuning

- ansible.posix.sysctl:
    name: "{{ item.name }}"
    value: "{{ item.value }}"
    sysctl_set: true
    reload: true
  loop:
    - { name: vm.swappiness, value: '10' }
    - { name: vm.dirty_ratio, value: '60' }
    - { name: vm.dirty_background_ratio, value: '2' }
    - { name: vm.overcommit_memory, value: '1' }  # For Redis
  become: true

Security Hardening

- ansible.posix.sysctl:
    name: "{{ item.name }}"
    value: "{{ item.value }}"
    sysctl_set: true
    reload: true
  loop:
    # Disable ICMP redirects
    - { name: net.ipv4.conf.all.accept_redirects, value: '0' }
    - { name: net.ipv4.conf.default.accept_redirects, value: '0' }
    # Disable source routing
    - { name: net.ipv4.conf.all.accept_source_route, value: '0' }
    # Enable SYN cookies (DDoS protection)
    - { name: net.ipv4.tcp_syncookies, value: '1' }
    # Log martian packets
    - { name: net.ipv4.conf.all.log_martians, value: '1' }
    # Disable IPv6 if not needed
    - { name: net.ipv6.conf.all.disable_ipv6, value: '1' }
  become: true

Docker/Kubernetes Prerequisites

- ansible.posix.sysctl:
    name: "{{ item.name }}"
    value: "{{ item.value }}"
    sysctl_set: true
    reload: true
  loop:
    - { name: net.bridge.bridge-nf-call-iptables, value: '1' }
    - { name: net.bridge.bridge-nf-call-ip6tables, value: '1' }
    - { name: net.ipv4.ip_forward, value: '1' }
    - { name: fs.inotify.max_user_watches, value: '524288' }
  become: true

Custom Config File

- ansible.posix.sysctl:
    name: vm.swappiness
    value: '10'
    sysctl_file: /etc/sysctl.d/99-custom.conf
    reload: true
  become: true

Read Current Value

- command: sysctl net.ipv4.ip_forward
  register: current_value
  changed_when: false

- debug: msg="{{ current_value.stdout }}"

Module Parameters

Parameter	Description
`name`	Sysctl parameter name
`value`	Value to set
`state`	`present` or `absent`
`sysctl_set`	Apply immediately (not just write file)
`reload`	Reload sysctl after change
`sysctl_file`	Config file (default: `/etc/sysctl.conf`)
`ignoreerrors`	Ignore sysctl errors

FAQ

Will changes survive reboot?

Yes — the module writes to /etc/sysctl.conf (or specified file) AND applies immediately when sysctl_set: true and reload: true.

"sysctl: permission denied" error?

You need become: true. Kernel parameters require root access.

How do I revert a change?

Set state: absent to remove from config file, then run sysctl --system to reload:

- sysctl: { name: vm.swappiness, state: absent }
- command: sysctl --system

Category: troubleshooting

Watch the video: ansible.posix.sysctl Module: Set Kernel Parameters Persistently (Guide) — Video Tutorial

Browse all Ansible tutorials · AnsiblePilot Home