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 via 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 a default configuration
  • To create a sample settings file that you can edit manually
  • To generate a settings file based on the current machine settings
  • To check the current configuration against a file of settings.

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 and check that. The output is self-explanatory.

All the other uses involve the settings file. Documentation is contained within the sample settings and you should read that for a full understanding of what is possible.

Settings File Format

The file is a plain-text file that may contain UTF-8 if you are running Ruby 2.0 and above, or US-ASCII otherwise.

The overall syntax of the file was designed to be Ruby-like so 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 are begun 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 ext4 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 conditions hold true. The list of conditions is 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.

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 the public gem repository, contact the author.

The author will update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

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.