Beah is using TCP/IP sockets for IPC. In case of failures it is easy to reconnect. (At least easier than simple capturing stdout.)
Events and Commands are JSON-serialized new-line separated messages sent over TCP/IP socket. Easy to extend, easy to ignore parts of message which are not understood. Well supported in many programming languages. Rather effective enconding/decoding.
Single JSON object on a line, is quite robust: in case of message corruption only that message (and eventually next one) will be affected. In case of events, these will not be lost - the lose_item event containing raw data is generated.
Twisted framework is used for handling non-blocking I/O operations.
The source code is available in a git repository here.
(Beware: things are not in place.)
- Default configuration. Update this module from outside
- Independent components - constants, controller, interfaces, basic backends and tasks...
- Additional backend and task adaptors
- Wiring to glue things together
- Twisted wiring (mostly metadata - use this protocol, this implementation, JSON over TCP/IP socket, default cfg,...
- Internal implementation for wirings
- Things which do not fit elsewhere
- I/O filters. LineReceiver, ObjReceiver,...
- Testing harness
- Library to be used from python tasks/tests.
Beah services and their interaction¶
During a test run, several Beah components interact over TCP/IP within the system itself and with the Beaker lab controller.
TCP/IP Server processes¶
When you login to a test system (say, when the /distribution/reservesys is running), you will see that the following Beah specific servers listening:
beah-srv 9714 root 10u IPv6 26970 0t0 TCP *:12432 (LISTEN) beah-srv 9714 root 12u IPv6 26972 0t0 TCP *:12434 (LISTEN) beah-rhts-task 10142 root 7u IPv6 27966 0t0 TCP localhost:7089 (LISTEN)
beah-srv process corresponds to the server started by
beah/wires/internals/twserver.py and it basically starts the
BackendListener, whose presence you can usually see
in the console logs:
2014-03-31 21:58:19,384 beah start_server: INFO Controller: BackendListener listening on :: port 12432 2014-03-31 21:58:19,385 beah start_server: INFO Controller: BackendListener listening on /var/beah/backend12432.socket 2014-03-31 21:58:19,386 beah start_server: INFO Controller: TaskListener listening on :: port 12434 2014-03-31 21:58:19,387 beah start_server: INFO Controller: TaskListener listening on /var/beah/task12434.socket
These servers exist throughout a recipe run on the test system. The
corresponding “client” programs live in
beah-rhts-task process (
main() function in
beah/tasks/rhts_xmlrpc.py) corresponds to the result server
started per task by
beah-srv and exits on a task completion.
Note that on a distro which doesn’t have the right twisted library or the IPv6 support has been disabled otherwise, the servers will only listen on IPv4 interfaces (see Using Beah for IPv6 testing to learn more about the IPv6 testing support in Beah).
The following beah daemons are started at system boot:
beah-fwd-backend: This handles the communication during multi host jobs.
The corresponding source file is
beah-beaker-backend: This talks to the Beaker lab controller’s
beaker-proxy process over XML-RPC. The corresponding source file is
beah-srv: This is the main daemon process we saw above. The corresponding
source file is
Setting up a development environment¶
To set-up development environment source dev-env.sh. Type
in BASH, which will set required environment variables (PATH and PYTHONPATH).
This is not required when package is installed.
After setup, run:
in the same shell, which will start server and backends in separate terminals. Or launch components yourself.
Development environment provides these shell functions:
- beah-srv - controller server
- beah-cmd-backend - backend to issue commands to controller. Enter
helpwhen “beah>” prompt is displayed.
- beah-out-backend - backend to display messages from controller
- beah - command line tool. Use
beah helpto display help. This uses the same command set as beah-cmd-backend
- launcher - wrapper to start these programms in new terminal windows.
beah-out-backend, beah-cmd-backend and beah will wait for controller.
Few auxiliary binaries are provided in bin directory:
mtail_srv - run srv and beah-out-backend in single window (using multitail tool.)
- beat_tap_filter - a filter taking a Perl’s Test::Harness::TAP format on
stdin and producing stream of Events on stdout.
There are few test tasks in examples/tasks directory:
- a_task - a very simple task in python.
- a_task.sh - the same, in bash, with some delays introduced.
- env - a binary displaying environment variables of interest.
- flood - flooding Controller with messges. This task will not finish and has
to be killed (in a
- socket - a task using TCP/IP socket to talk to Controller.
Actually a_task and a_task.sh are a simple demonstration of how the test might look like, though it is not definite and more comfortable API will be provided.
In default configuration server is listenning on localhost:12432 for backends and localhost:12434 for tasks. On POSIX compatible systems unix domain sockets are used for local connections by default.
beah-cmd-backend does not offer history or command line editing features (it is on TODO list) thus it is more convenient to use beah command line tool.
The commands supported are:
- ping [MESSAGE]: ping a controller, response is sent to issuer only.
- PING [MESSAGE]: ping a controller, response is broadcasted to all backends.
- run TASK (r TASK): run a task. TASK must be an executable file.
- kill: kill a controller.
- dump: instruct controller to print a diagnostics message on stdout.
- quit (q): close this backend.
- help(h): print this help message.
Controller’s log is written to
Development and usage in a lab¶
lm-install.sh script can be used to install harness from
working copy on a lab machine. This requires either LABM env.variable
to be defined or passing lab machine’s FQDN as an argument
To change settings, change
lm-install-env.sh file. As this file is tracked by
lm-install-env.sh.tmp exists in current directory it is used with
On a lab machine:
$ mkdir -p /mnt/testarea/lm-install
This is the default. Change
LM_INSTALL_ROOT in lm-install-env.sh.
On the machine where beaker/Harness tree exists:
edit lm-install-env.sh (or eventually lm-install-env.sh.tmp) file. $ export LABM=x.ample.com $ ./lm-install.sh $ 'LABM=x.ample.com ./lm-install.sh'
Or, the following can be used instead of the last two steps:
$ './lm-install.sh x.ample.com'
On a lab machine:
$ cd /mnt/testarea/lm-install $ . lm-package-*.sh
Be careful to choose the correct one to be used.
. /mnt/testarea/lm-install/main.sh can be used anytime to read environment and load
functions. Run lm_main_help and lm_help for more help on available functions.
Writing a patch for Beah¶
Here is a brief overview of how you can submit a patch for Beah.
Clone Beah’s repository¶
git clone git://git.beaker-project.org/beah
Create a local working branch¶
Create a branch (say,
git checkout origin/develop -b
myfeature. Make your changes and once you are happy, commit the
changes. If your patch fixes a bug, please include the Red Hat
Bugzilla number as a footer line in your commit message. For example:
This commit fixes a minor glitch in how Beah handles errors. Bug: 134511