sysctl

Table of Contents

1. Description
2. Features
3. Puppet resource implementation
4. sysctl precedence
5. Value handling
6. Usage - Configuration options and additional functionality
7. Limitations - OS compatibility, etc.
8. Development - Guide for contributing to the module

Description

Manage sysctl kernel tuning with Puppet.

This is a native type and provider that scans for known sysctl settings in all directories the command scans (see sysctl precedence).

The module has its own naming convention for files in /etc/sysctl.d:

• Prefix files managed by puppet with 80-puppet- and then name of setting used as filename, eg net.ipv4.conf.all.accept_source_route will be saved as /etc/sysctl.d/80-puppet-net.ipv4.conf.all.accept_source_route.conf
• One setting per file, in regular sysctl format, eg:

  net.ipv4.conf.all.accept_source_route=0
  

Features

• Scans system directories for for rules (see sysctl precedence)
• Runs sysctl -w when a rule is added
• Flushes IPv4 and IPv6 rules when a rule matching /ipv4/ or /ipv6/ is updated (can be disabled)
• Rebuild the initrd when any rules updated (can be disabled)
• Supports resource purging for unmanaged rules
• Files created by puppet prefixed 80-puppet- for identification

Puppet resource implementation

It's possible to enumerate the list of current settings using puppet resource sysctl which will give output like this:

sysctl { 'net.ipv4.conf.all.accept_source_route':
  ensure      => 'present',
  defined_in  => ['/etc/sysctl.d/80-puppet-net.ipv4.conf.all.accept_source_route.conf'],
  value       => '0',
  value_saved => '0',
}

In this case:

• net.ipv4.conf.all.accept_source_route is the setting being managed
• There is some form of non-default setting in place (ensure=>present)
• The setting is defined in /etc/sysctl.d/80-puppet-net.ipv4.conf.all.accept_source_route.conf and because this file starts 80-puppet- the module owns the setting
• defined_in lists all .conf file defining the setting (see sysctl precedence)
• value represents the active value on the system, obtained from running sysctl net.ipv4.conf.all.accept_source_route
• valued_saved represents the current winning value saved in .conf files (see sysctl precedence)

sysctl { 'net.ipv4.igmp_qrv':
  ensure      => 'present',
  defined_in  => ['/etc/sysctl.d/megacorp_settings.conf'],
  value       => '2',
  value_saved => '2',
}

The module also manages changes made in files created by the user which will have names that don't match the 80-puppet- naming convention. When the module is commanded to take ownership of such settings, the existing file will be renamed rather then deleted, eg:

sysctl { "net.ipv4.igmp_qrv=2": }

Would result in setting being saved to 80-puppet-net.ipv4.igmp_qrv.conf while megacorp_settings.conf would be moved to megacorp_settings.conf.nouse.

sysctl precedence

According to man sysctl, Several patterns of files are processed with the last definition winning:

/run/sysctl.d/*.conf
/etc/sysctl.d/*.conf
/usr/local/lib/sysctl.d/*.conf
/usr/lib/sysctl.d/*.conf
/lib/sysctl.d/*.conf
/etc/sysctl.conf

Despite the symlink /etc/sysctl.d/99-sysctl.conf existing, /etc/sysctl.conf is still processed separately and in accordance with the above list.

The module keeps track of settings that occur in any of the above files in the defined_in property. If asked to manage a setting that is already defined and not managed by the module Puppet will disable all existing .conf files containing the offending definition by appending .nouse to the filename and will then create a new file obeying the 80-puppet- naming convention if ensure=>present.

Value handling

It's possible for value to differ from value_saved and this would indicate that sysctl -w was run at some point after the sysctl rules were processed.

Puppet detects when value != value_saved and will sync the resource on detection.

Usage

You must include sysctl::initrd to gain support for rebuilding the initrd after all rules are set

Simple (long form)

include sysctl::initrd
sysctl { "net.ipv4.conf.all.accept_source_route":
  ensure => present,
  value  => 0,
}

• Runs sysctl -w net.ipv4.conf.all.accept_source_route=0
• Writes the setting to /etc/net.ipv4.conf.all.accept_source_route.conf for activation on boot
• Flushes the IPv4 rules
• Rebuilds initrd

Simple (short form)

include sysctl::initrd
sysctl { "net.ipv4.conf.all.accept_source_route=0":
  ensure => present,
}

• Functionally equivalent to long form but handly shortened syntax using only title
• title must match key=value

Resource purging

resources { "sysctl":
  purge => true,
}

include sysctl::initrd
sysctl { "net.ipv4.conf.all.accept_source_route":
  value => 0,
}

Puppet will purge all unmanaged settings from all scanned file patterns (see sysctl precedence):

• Only valid settings can be purged (visible in sysctl -a)
• Existing puppet managed files will be removed
• Existing non-puppet managed files will be renamed
• Only the sysctl settings in the catalog will continue to exist
• You must reboot to restore default settings
• Only sysctl rules managed by puppet will exist if this technique is used

Stop managing a setting

include sysctl::initrd
sysctl { "net.ipv4.conf.all.accept_source_route":
  ensure => absent,
}

• Removes the .conf file from /etc/sysctl.d
• initrd will be rebuilt
• You must reboot to restore default settings

Don't flush IPv4 on rule change (per resource)

include sysctl::initrd
sysctl { "net.ipv4.conf.all.accept_source_route=1":
  autoflush_ipv4 => false,
}

• To avoid flushing the IPv4 rules for this resource, set autoflush_ipv4 false

Don't flush IPv6 on rule change (per resource)

include sysctl::initrd
sysctl { "net.ipv6.conf.default.disable_ipv6=1":
  autoflush_ipv6 => false,
}

• To avoid flushing the IPv6 rules for this resource, set autoflush_ipv6 false

Don't rebuild initrd on rule change (per resource)

# include sysctl::initrd <--- comment or remove
sysctl { "net.ipv6.conf.default.disable_ipv6=1": }

• To avoid rebuilding initrd with dracut for this resource, set rebuild_initrd false

Use an alternate command to rebuild initrd

class { "sysctl::initrd":
  rebuild_initd_cmd => "/bin/echo custom > /tmp/testcase/initrd_cmd"
}

Reference

generated documentation.

Reference documentation is generated directly from source code using puppet-strings. You may regenerate the documentation by running:

bundle exec puppet strings

Limitations

• Tested on RHEL/CentOS 7 so far. You might be able to support other systems by passing the appropriate command to rebuild initrd on your platform

Development

PRs accepted :)

Testing

This module supports testing using PDQTest.

Test can be executed with:

bundle install
make

See .travis.yml for a working CI example

Reference

Classes

• sysctl::initrd: Rebuild initrd after all sysctl rules applied

Resource types

• sysctl: Manage sysctl parameter with Puppet

Classes

sysctl::initrd

Puppet types an providers are currently unable to batch operations. Easiest way to make sure the initrd is only updated once is therefore to put something in the catalogue and refer to it which leads to this workaround. Make sure to include this class to satisfy the redhat requirement to rebuild the initrd when sysctl settings change.

• See also https://access.redhat.com/solutions/2798411

Parameters

The following parameters are available in the sysctl::initrd class.

rebuild_initrd_cmd

Data type: String

Command to run to rebuild initrd

Default value: "/usr/sbin/dracut -v -f"

enabled

Data type: Boolean

Set false to disable the initrd rebuild

Default value: true

Resource types

sysctl

Manage sysctl parameter with Puppet

Properties

The following properties are available in the sysctl type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

The value the kernel tuning parameter to

defined_in

File containing this settings definition

value_saved

The value the kernel tuning parameter should be set to (from file)

Parameters

The following parameters are available in the sysctl type.

autoflush_ipv4

run sysctl -w net.ipv4.route.flush=1 when needed

Default value: true

autoflush_ipv6

run sysctl -w net.ipv6.route.flush=1 when needed

Default value: true

name

namevar

The name of the kernel tuning parameter to set