Tweek

Tweek is a command line utility that allows multiple aspects of a Linux configuration to be recorded and checked against a file of settings. Think of it as a series of configuration tests that can be executed, with the results being presented as a number of passes and failures. The number of failures is returned as the exit code of the process which allows it's use in scripts. This is particularly useful when checking multiple machines using a utility like pssh or mush.

Although existing configuration management systems such as Puppet, Chef or Ansible can perform the same checks, they tend to require a high level of support infrastructure to be useful. The purpose of Tweek is to check that after these more sophisticated systems have done their thing, that the performance-important settings are actually correct.

Another benefit is that the configuration test syntax is extremely simple text, and by abstracting the actual commands used, it is much easier for a relatively unsophisticated user to check obscure settings without actually knowing the commands needed.

One of the objectives of the Tweek GitHub repository is to serve as a repository for sets of configuration parameters that have been found by the community to be useful in maximizing performance for certain machines and workloads. It is hoped people will submit pull requests to add settings files to the settings subdirectory of this project.

Installation

Tweek has been written to use Ruby 1.8.7 or above which is available on all Linux systems within the last five years or so. It also requires rubygems.

Do I need to be the 'root' user?

The utility will work fine as a non-root user, although some settings may not be accessible, and so the tests will fail.

Installing Ruby

Depending on your distribution issuing the following commands:

  • On Debian (eg. Ubuntu) systems run: apt-get install ruby rubygems
  • On RPM (eg. RedHat, CentOS) systems run: yum install ruby rubygems

Then to install the Tweek gem run this command:

gem install tweek

Depending on the setup of the system's Ruby, you may need to run sudo for this to be successful. You should now be able to type tweek -? to see the available options.

Usage

Tweek can be used in the following modes:

  • To check the current system against a default configuration
  • To create a sample settings file that you can edit manually
  • To generate a settings file based on the current system configuration
  • To check the current system configuration against a file of settings.
  • To set the current system configuration to a file of settings.
    NOTE this is currently restricted to sysctl parameters only. TBD.

In the first case Tweek uses a built-in set of defaults. To check using these simply run:

tweek

Tweek will read the sample settings from the default file settings/sample.set (which is installed as part of the Gem) and check them. The output is self-explanatory.

All the other uses involve the settings file. Documentation is contained within the sample settings and you should read them for a full understanding of what is possible. Use tweek -s to show them.

Output

The output of Tweek is controlled by the output option, which takes the following values (default 1):

  1. No output, just a return code.

  2. Summary output only is written to STDERR. It consists of a string of dots (when a parameter is OK) or the letter 'F' (when a parameter doesn't match) followed by a summary line.

  3. Only the settings that didn't match are written to STDOUT in a form that can be reused as input. The summary is written to STDERR

  4. All the settings are written to STDOUT in a form that can be reused as input.

The latter formats differ slightly depending on whether the utility is operating in query mode, set mode or reset mode. See below.

Note that the output is colorized by default. Disable this with --no-color.

  • red: a value that doesn't match or conditions that are not met
  • yellow: expected values
  • green: conditions that are met
  • bold: emphasis

Operating Mode

The actions of Tweek are controlled by the mode option, which takes the following values (default query):

query
the settings are checked against the actual values and mismatches are highlighted and noted in a comment with the syntax '[expected xxx]'
set
the settings are set to the given value, mismatches are highlighted and noted in a trailing comment with the syntax '[was xxx]'
reset
action as above but the settings are taken from the '[was xxx]' comments

Settings File Format

The settings file is a plaintext file encoded in UTF-8 (if you are running Ruby 2.0 or above) or US-ASCII otherwise. Although settings files can have any name, please observe the convention of using a file extension of .twk.

The overall syntax of the file was designed to be Ruby-like so that enabling syntax highlighting (using Ruby as the language) makes it very readable.

Comments

Comments are of two sorts:

  • Inline: after the first # on any line
  • Block: Following the Ruby convention these begin with =begin and end with =end

Sections

The file is split into sections, each of which starts with one of several predefined keywords (in capitals) followed by an optional parameter narrowing the scope of the keyword. The keywords are:

  • BLKDEV - Lists block devices and their configuration parameters. This must be followed by a block device name, which may be a wildcard.
  • CLOCKSOURCE - Establishes the desired clocksource. No parameter is required.
  • KERNEL - Parameters passed to the Kernel at boot time (usually using Grub). No parameter required.
  • SYSCTL - Various system settings. No parameter required.
  • NET - Settings appropriate to a particular network device. This must be followed by a network device name eg. eth0. Wildcards are allowed.
  • EXT4 - Settings for EXT4 filesystems. This must be followed by a parameter containing either a block device or filesystem path corresponding to a mounted ext4 filesystem. Wildcards are allowed.
  • XFS - Settings for XFS filesystems. This must be followed by a parameter containing either a block device or filesystem path corresponding to a mounted xfs filesystem. Wildcards are allowed.

Parameters

After a section all lines up to the next section (or end of file) are interpreted as parameter lines. These take the form:

parameter_name = parameter_value [if condition[,condition...]]

For a discussion of which parameters are supported please see the sample settings file.

Conditionals

Parameter lines can be suffixed by the word if and one or more conditions. These are used to limit the scope of the parameter check to those systems where the condition(s) hold true. The list of conditions is logically AND'ed together. A condition takes the form:

[k|d|v] op value

Where:

  • k is the Kernel Version, d is the Distro name, and v is the Distro version.
  • The operator op can be: equality ==, regex equality =~ or a version comparator as per the Rubygems specification.
  • The value is one of: a plain string in ' quotes (for equality), a regex between / delimiters, or a plain version string (eg. 4.3.1).

NOTE: The determination of the current Distro, Distro Version and Kernel Version is done using the lsb_release and uname commands. Since these may not be installed on all systems, you can specify these as command line options. This is also useful in testing. An example for Redhat 7 is:

tweek --distro=RedHatEnterpriseServer --distro-ver=7.4 --kernel-ver=3.10.0

Development

Tweek was developed using the gem bundler. Ensure you have both this and rake installed using:

gem install bundler rake

After checking out the repo, run bundle install to install dependencies. Make your code changes, then run bundle exec rake test to run the tests. When ready to test on a machine use the built-in Rake tasks. For a list of these type rake -T.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version to rubygems.org please contact the author.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/townsen/tweek. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Tweek project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.