PRSCript is a script that run a series of builds and tests on a given branch. It was reserved to some developers so they can check the quality of their work before submission. The test builds are run on Suricata buildbot which is composed of some different dedicated hardware system. buildbot is an open-source framework for automating software build, test, and release processes. In the case of Suricata instance, it is set up to run various builds, unit tests as well as functional tests (such as pevma's regression script).
The fact that this script was reserved to some users was a limitation as many contributors are not registered as Suricata buildbot users. As well, the fact that the code has to be public was not convenient as you could have to expose code before it is ready (with shameful TODO inside). Another point is that you were not able to customize your build. For instance, if you were introducing a new library as dependency it was not possible to test it before a global modification of the buildbot.
To get over these limitations, Victor Julien and I have discussed on using Docker to allow developers to simply run a Suricata dedicated buildbot. As you may/should already know Docker is an open platform for distributed applications for developers and sysadmins. It allows you to quickly install install, manage and run containers. In our case, the idea was to start a pre-configured buildbot container using your local git as reference code. This way you can simply start test builds on your private code without even needing.
So, I have worked on this Docker based buildbot installation dedicated to Suricata and it has been merged in Suricata mainstream by Victor Julien.
It is now possible to use the prscript locally via Docker. Installation had been made simple so you should just have a few commands to run before being ready.
The buildbot will run various builds (gcc and clang, different builds options) and run suricata against some pcaps to check against possible crash.
You need to have docker and python-docker installed on your system. Optionally you can install pynotify on your system to get desktop notification capability. On recent Debian based distribution you can use:
sudo apt-get install docker python-docker python-notify
This operation has only to be done once. From the root of
Suricata sources, run:
sudo qa/prscript.py -C
It will take some times as the download is several hundred Mo. The result will be a docker container named 'suri-buildbot'.
When you need to use the buildbot, you can start it from the command line:
sudo qa/prscript.py -s
You can check it is running via:
sudo docker ps
And you can connect to the buildbot web interface via http://localhost:8010
Once the buildbot is active, you can start a build:
qa/prscript.py -d -l YOUR_BRANCH
This will start a build of the local branch YOUR_BRANCH without requiring any connectivity.
To get warned of the result of the builds via a desktop notification:
qa/prscript.py -d -l YOUR_BRANCH -n
When you don't need the buildbot anymore, you can stop it from the command line
sudo qa/prscript.py -S
For further details, check Suricata docker QA page on OISF redmine.
Buildbot will make suricata read all the pcap files available in qa/docker/pcaps/. So you can use this directory to add your own test pcaps.
Buildbot configuration is stored inside your suricata sources. It is the file qa/docker/buildbot.cfg. So, you can change the Buildbot configuration by editing this file. Then stop and start the docker container to get the new version used. This can be for example used when you need to add a flag to the configure command to activate a new feature.
What is great about this docker way of doing things is that it solves easily some complex points. For instance, if the buildbot configuration were coming from the Docker image then it will not be possible to easily edit it. Furthermore developer will loose any changes made in case of image upgrade. Also, the configure flags used by the buildbot will always be related to the current state of the code. So there will be no issue with running builds even if you are working on some older code as your buildbot configuration will be synchronized first.
The docker instance can be accessed via SSH using the admin account (password being 'admin' too). To get the port to use for ssh run the following command to get the port to use:
$ sudo docker port suri-buildbot
22/tcp -> 0.0.0.0:49156
8010/tcp -> 0.0.0.0:8010
and then connect:
ssh admin@localhost -p 49156
This can be used to install new dependencies inside the container. For instance if you are introducing a new library in Suricata, you may have to install the library in the docker instance.
On Docker side, the build recipes is available from GitHub. Feel free to modify it or propose updates and fixes.
Learn more about simplifying your Suricata Deployment.
