Tasks

Restraint doesn’t require tasks to be written in any particular language. In fact, most tests are written in a mixture of shell, python and C code. You do need to provide some metadata in order for things to work best.

Restraint Metadata File

Restraint will look for a file called metadata in the task directory. The format for that file is a simple ini file which most people should be familiar with.

[General]
name=/restraint/env/metadata
owner=User ABC1 <userabc1@example.com>
description=just reports env variables
license=GPLv2
confidential=no
destructive=no

[restraint]
entry_point=./runtest.sh
max_time=5m
dependencies=gcc;emacs
softDependencies=numactl;numactl-devel
environment=META_VAR1=var1value;META_VAR2=var2value;META_VAR3=var3value
repoRequires=general/include;filesystems/include
no_localwatchdog=true
use_pty=false

restraintd does not require any metadata fields to be present. In other words, there are no checks and reporting of errors if metadata is not present. This allows flexibility in your configuration.

The General section is mostly used for informational data. The only element that Restraint will process is the name attribute. If defined, this will overwrite the task name specified from the job XML.

The restraint section has the following elements which can be defined:

entry_point

This tells Restraint how it should start running the task. If you don’t specify a program to run it will default to ‘make run’ which is what legacy RHTS (Red Hat Test System) would do. This would require you provide a Makefile. Other examples of entry points:

* entry_point=autotest-local control-file
* entry_point=STAF local PROCESS START SHELL COMMAND "ps | grep test | wc >testcount.txt"

max_time

The maximum time a task is expected to run. When restraintd runs a task it sets up a localwatchdog which will kill the task after this time has expired. When run in Beaker this is also used for the external watchdog (typically 20-30 minutes later than the local watchdog time). Time units can be specified as follows:

* d for days
* h for hours
* m for minutes
* s for seconds

To set a max run time for 2 days you would use the following:

max_time=2d

dependencies

A semicolon-delimited (;) list of additional packages (needed to run this task) to be installed on the system. The task will abort if the dependencies fail to install.

dependencies=lib-virt;httpd;postgresql;nfs-utils;net-tools;net-snmp;ethereal;wireshark;tcpdump;rusers;bzip2;gcc

environment

A semicolon-delimited (;) list of task environment variables to be set on the system.

environment=META_VAR1=var1value;META_VAR2=var2value;META_VAR3=var3value

softDependencies

A semicolon-delimited (;) list of optional additional packages to be installed on the system. The task will proceed even if the soft dependencies fail to install. This is useful for a task that is intended to run on multiple platforms, and the task can test platform-specific features (e.g., NUMA) if the appropriate support packages are installed, but the task will not abort on the other platforms where the support packages do not exist.

softDependencies=numactl;numactl-devel

repoRequires

A semicolon-delimited (;) list of additional tasks needed for this task to run.

repoRequires=general/include;filesystems/include

Note: When fetching from git (see Fetch), this is the #subdirectory portion of the URL, so do not use a leading / character as was done with RhtsRequires in testinfo.desc for Legacy RHTS tasks.

no_localwatchdog

Normally Restraint will setup a localwatchdog which will attempt to recover from a hung task before the external watchdog (if running under Beaker) triggers. But you can tell Restraint to not setup a localwatchdog monitor by including this key with a value of true. Only true or false are valid values.

no_localwatchdog=true

use_pty

Before version 0.1.24 Restraint would execute all tasks from a pty. This meant that programs thought they were running in an interactive terminal and might produce ANSI codes for coloring and line positioning. Now the default is not to use a pty which will give much cleaner output. If you find your test is failing because it expects a pty you can enable the old behavior by setting this.

use_pty=true

OSMajor Specific Options

Any of the above elements can be overridden with OSMajor specific options. In order for this to work the OSMajor (or “OS family”) attribute must be filled in the job.xml. If the job was run through Beaker this will have been filled in for you. If you run a stand-alone job (with restraint-client) you can set the value in the family attribute of the recipe tag. For example:

<job>
  <recipeSet>
    <recipe family="RedHatEnterpriseLinuxServer5">
      ...

For example, if a task is known to take twice as long on RedHatEnterpriseLinuxServer5 then you could use following:

max_time=5m
max_time[RedHatEnterpriseLinuxServer5]=10m

Another example where we will install RHDB on RedHatEnterpriseLinuxServer5 and PostgreSQL on everything else.

dependencies=postgresql
dependencies[RedHatEnterpriseLinuxServer5]=rhdb

Legacy Metadata File

Prior to the Restraint harness, users defined testinfo.desc file as the metadata file in their job tasks and restraint supported that file. This is being deprecated and the substitute for this file and variables within can be found in Replacement for RHTS testinfo.desc File.