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. These can then be referenced directly using URLs, or downloaded locally then edited to suit prior to running.

Installation

Tweek requires use Ruby 1.8.7 or above and so can be used on all Linux systems within the last five years or so.

When using Ruby 1.8.7 note that using settings file via https URLs can be problematic.

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 several ways:

  • To create a sample settings file that you can edit manually,
  • To check the current system against a desired configuration embodied in a file of settings,
  • To set or reset the current system configuration to a file of settings.
    NOTE set/reset is currently restricted to sysctl parameters only. TBD.

The settings file can be local or remote (using a variety of URL formats). It has a simple text format which is fully documented in a sample file that can be generated using tweek -s.

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.
    Useful when using pssh or mush to execute on multiple machines.

  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) or the letter 's' (when a parameter is skipped due to failing a condition check), followed by a summary line.

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

  4. The summary is written to STDERR.
    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 or previous 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

Example

Given the following input file sysctl.twk:

# Sample test file

SYSCTL

kernel.msgmax = 65536 if k ~> 3.1
kernel.shmmax = 4000000000 if k>2.5 # Crazy high!
kernel.shmall = 4294967296

Querying Current Values

Running the command tweek -o 3 sysctl.twk produces the following output:

Note that red denotes conditions that weren't met, or values that differed from the expected ones. Green denotes conditions that were met, and yellow is used to highlight expected values, that are called out in the comments.

Setting New Values

Running the command tweek -m s -o 3 sysctl.twk produces the following output:

Note that colors have the same meaning, but now the previous values (if different) are recorded in yellow. You can save this format for use in reset mode, if using redirection the --no-color option removes the ANSI escape sequences.

Resetting Values

Running the command tweek -m r -o 3 <above output> produces the following output:

Note that a value will only be reset if it matches!

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.