wiki:BashTestTutorial
Last modified 6 years ago Last modified on 09/05/08 12:58:01

A simple tutorial to write your test in bash

Prologue

Tests consists of two files:

  • source file "myName.sh", which is usually located in /usr/share/sectool/tests/
  • description file "09_myName.dsc", the number before underline specifies an order in which sectool starts the tests. Usual location /etc/sectool/tests.

Description file

The purpose of description file is that it creates an abstraction layer between sectool and the scripts source, so the tests might be more simply implemented in different languages. Let's have a look at its syntax.

The description file consists of at least of two sections: header and default. This is an example of a header section

[HEADER]
NAME="selinux"
FILE_NAME="someName.sh"
DESCRIPTION="Example test. It only checks if you have selinux enabled."
LEVELS="2 3 4 5"
GROUPS="selinux"
DEPS="getenforce"
REQUIRES="selinux-policy"

As you could guess,

  • NAME - defines test name,
  • FILE_NAME - is the name of source file,
  • DESCRIPTION - describes what the test does,
  • LEVELS - specify in which levels is the test enabled in by default,
  • GROUPS - tests may be grouped in one or more groups,
  • DEPS - test depends on these binaries (separated by spaces), in case they are not available on the system, the test won't be able execute.
  • REQUIRES - packages, which a test requires to run (separated by spaces). If they are not found (by rpm -q), the test will be disabled - grey in sectool-gui

In default section we specify test settings via environment variables that are set up by sectool before tests starts. For example:

[DEFAULT]
MODE=Enforcing

The last, not mandatory, part of description file is set of [LEVEL_{12345}] sections. In this part, we can override the default settings in certain levels.

[LEVEL_2]
MODE=Permissive

Source file

Bash test source begins with:

#!/usr/bin/env sh
. "${INCL_DIR}/bash.defs"

bash.defs is a bash library that provides functions for unified output, which can be easily parsed by sectool test runner.

The rest of the test is its body. We should use these functions in it:

  • report - to report errors and warnings that were discovered by test,
  • test_exit - to finish the test.

report syntax: report type id msg

  • type:
    • ERROR - issues that should be fixed
    • WARNING - theoretical problem discovered, let admin know
    • HINT - advice, how to fix error or warning
    • INFO - info message
  • id - purpose of id is to pair error - hint or warning - hint
  • msg - the message text

test_exit syntax: test_exit ${E_OK}|${E_FAIL}|${E_FATAL} [message]

  • E_OK - test runs without problems
  • E_FAIL - something unexpected happened, test couldn't be finished
  • E_FATAL - something unexpected happened, all tests in queue are cancelled

E_FAIL and E_FATAL are followed by an explanation message

example text body:

SELINUX_MODE=$(getenforce)
if [ $SELINUX_MODE != $MODE ] && [ $SELINUX_MODE != "Enforcing" ]; then
    report ERROR 1 "Selinux is disabled or running in wrong mode"
    report HINT 1 "see man selinux"
fi
test_exit ${E_OK}

Epilog

When you merge these example you get 09_someName.dsc and someName.sh. Place them in "/usr/share/sectool/tests", set root owner and enjoy sectool :-).

Usage examples:

# getenforce
Permissive

# sectool -i selinux
Name         : selinux
Script name  : someName.sh
Groups       : selinux
Levels       : 2 3 4 5
Description  : Example test. It only checks if you have selinux enabled.

# sectool -n -r selinux
Test Name: selinux                                            Test Result: ERROR
        Error(01)     Selinux is disabled or running in wrong mode
        Hint(01)      see man selinux

# sectool -L 2 -r selinux
Test Name: selinux                                             Test Result: PASS

Attachments