sysctl cookbook

Set sysctl system control parameters via Chef

Requirements

Platforms

• Amazon Linux (Integration tested)
• Debian/Ubuntu (Integration tested)
• RHEL/CentOS (Integration tested)
• openSUSE (Integration tested)
• PLD Linux
• Exherbo
• Arch Linux
• SLES
• FreeBSD

Chef

• 12.5+

Usage

There are two main ways to interact with the cookbook. This is via chef attributes or via the resource.

Cookbook Attributes

• node['sysctl']['params'] - A namespace for setting sysctl parameters.
• node['sysctl']['conf_dir'] - Specifies the sysctl.d directory to be used. Defaults to /etc/sysctl.d on the Debian and RHEL platform families, otherwise nil
• node['sysctl']['allow_sysctl_conf'] - Defaults to false. Using conf_dir is highly recommended. On some platforms that is not supported. For those platforms, set this to true and the cookbook will rewrite the /etc/sysctl.conf file directly with the params provided. Be sure to save any local edits of /etc/sysctl.conf before enabling this to avoid losing them.
• node['sysctl']['restart_procps'] - Defaults to true. Will allow the consumer of the cookbook to control whether or not to notify procps to restart sysctl to load the newly set values.
• node['sysctl']['ignore_error'] - Defaults is not set. If true, this will allow the consumer of the cookbook to control whether or not to utilize '-e' flag within actual sysctl command.

Note: if node['sysctl']['conf_dir'] is set to nil and node['sysctl']['allow_sysctl_conf'] is not set, no config will be written

Setting Sysctl Parameters

Using Attributes

Setting variables in the node['sysctl']['params'] hash will allow you to easily set common kernel parameters across a lot of nodes. All you need to do to have them loaded is to include sysctl::apply anywhere in your run list of the node. It is recommended to do this early in the run list, so any recipe that gets applied afterwards that may depend on the set parameters will find them to be set.

The attributes method is easiest to implement if you manage the kernel parameters at the system level opposed to a per cookbook level approach. The configuration will be written out when sysctl::apply gets run, which allows the parameters set to be persisted during a reboot.

Examples

Set vm.swappiness to 20 via attributes

    node.default['sysctl']['params']['vm']['swappiness'] = 20

    include_recipe 'sysctl::apply'

Using resources

The sysctl_param resource can be called from wrapper or application cookbooks to immediately set the kernel parameter and cue the kernel parameter to be written out to the configuration file.

This also requires that your run_list include the sysctl::default recipe in order to persist the settings.

sysctl_param

Actions

• :apply (default)
• :remove
• :nothing

Properties

• key
• value

Examples

Set vm.swappiness to 20 via sysctl_param resource

    include_recipe 'sysctl::default'

    sysctl_param 'vm.swappiness' do
      value 20
    end

Remove sysctl parameter and set net.ipv4.tcp_fin_timeout back to default

    sysctl_param 'net.ipv4.tcp_fin_timeout' do
      value 30
      action :remove
    end

Ohai Plugin

The cookbook also includes an Ohai plugin that can be installed by adding sysctl::ohai_plugin to your run_list. This will populate node['sys'] with automatic attributes that mirror the layout of /proc/sys.

To see Ohai plugin output manually, you can run ohai -d /etc/chef/ohai/plugins sys on the command line.

Additional Reading

There are a lot of different documents that talk about system control parameters, the hope here is to point to some of the most useful ones to provide more guidance as to what the possible kernel parameters are and what they mean.

• Chef OS Hardening Cookbook
• Linux Kernel Sysctl
• Linux Kernel IP Sysctl
• Linux Performance links by Brendan Gregg
• RHEL 7 Performance Tuning Guide by Laura Bailey and Charlie Boyle
• Performance analysis & tuning of Red Hat Enterprise Linux at Red Hat Summit 2015 (video) slides part 1 by Jeremy Eder, D. John Shakshober, Larry Woodman and Bill Gray
• Performance Tuning Linux Instances on EC2 (Nov 2014) by Brendan Gregg
• Part 1: Lessons learned tuning TCP and Nginx in EC2 (Jan 2014)
• Tuning TCP For The Web at Velocity 2013 (video), slides by Jason Cook
• THE /proc FILESYSTEM (Jun 2009)

Development

We have written unit tests using chefspec and integration tests in serverspec executed via test-kitchen. Much of the tooling around this cookbook is exposed via guard and test kitchen, so it is highly recommended to learn more about those tools. The easiest way to get started is to install the Chef Development Kit

Running tests

The following commands will run the tests:

chef exec bundle install
chef exec cookstyle
chef exec foodcritic .
chef exec rspec
chef exec kitchen test

Please run the tests on any pull requests that you are about to submit and write tests for defects or new features to ensure backwards compatibility and a stable cookbook that we can all rely upon.

Running tests continuously with guard

This cookbook is also setup to run the checks while you work via the guard gem.

bundle install
bundle exec guard start

ChefSpec Resource Matchers

The cookbook exposes a ChefSpec matcher to be used by wrapper cookbooks to test the cookbooks resource. See libraries/matchers.rb for basic usage.