wiki:SettingUpBuildslave

Version 55 (modified by Samuli Seppänen, 8 years ago) (diff)

Cleanup and improvements, not yet finished

Introduction

OpenVPN project uses Buildbot (current version 0.8.5) to help increase code quality. Buildbot is a Python application that can work in either master or slave mode. The buildmaster is the core server which accepts connections from buildslaves and tells them what they should do. Typically the clients fetch latest sources and reports any build problems to buildbot which in turn informs developers via email. In software engineering this is called Continous integration and helps prevent build problems go unnoticed for extended time periods. The clients (buildslaves) can and should run on a variety of hardware / OS platforms. For the server (buildmaster) the OS choice is largely irrelevant. Buildbot is described in more detail in the Buildbot manual.

As the number of buildslaves can easily get out of hand, the OpenVPN project can make use of your help. If you're interested in donating a buildslave please contact the buildmaster admins:

  • Gert (cron2 on IRC)
  • Samuli (mattock on IRC)

Setting up the VPN connection

Our buildmaster is accessible only via OpenVPN. The three things you need are listed in the following sections.

Creating the community user account

First you need an OpenVPN community services user account. Please use a dedicated community user account with a strong password for your buildslave. For clarity, you should use the following naming convention:

<youralias>-<operatingsystem>-<version>-<architecture>

For example:

cron2-freebsd-103-amd64

There is no need to create a dedicated email account for the buildslave: using your personal email address is just fine. You can also fake the firstname and lastname fields.

Getting membership in the appropriate community LDAP group

Once you have created the community account for your buildslave, let the buildmaster maintainers know what it is called, so that they can add it to the correct LDAP group. Without proper group membership your buildslave's OpenVPN instance will not be able to connect to the community VPN server.

Getting the OpenVPN configuration file

Buildmaster maintainers will provide you with an OpenVPN configuration with inlined ca.crt and ta.key. You can use pretty much any semi-recent OpenVPN version to connect to the community VPN server.

Testing OpenVPN connectivity

A simple ping test should be enough to verify that your buildslave can reach buildmaster:

$ ping 10.177.36.101

Setting up a buildslave

Buildbot versions 0.7.x and 0.8.x are known to work with our current (0.8.5) buildmaster. Buildbot 0.9.x is known _not_ to work.

Common setup tasks

These tasks are out of order and referred to in the setup instructions. Please do not run these right now.

Setting up a new buildslave instance

This command is the same regardless of how you install or setup the buildslave, so it is shown here. You need to run this command after you have installed buildbot-slave, or it will fail:

buildslave create-slave /var/lib/buildbot/slaves/openvpn 10.177.36.101:9989 slave-<youralias>-<operatingsystem>-<version>-<architecture> <buildslave-password>

This will create a buildslave instance to /var/lib/buildbot/slaves/openvpn. You do not need to use that directory, but Debian and Ubuntu use it by default, and it seems like a reasonable place on RedHat? derivatives as well.

Starting the buildslave at boot-time

Debian and Ubuntu bundle a buildslave init script with their buildbot-slave package. On other distributions (or when you installed using easy_install) you need to take care of starting buildslave on boot yourself. If you happen to be using monit then you can use this monit fragment:

check process buildslave-openvpn with pidfile /var/lib/buildbot/slaves/openvpn/twistd.pid
    start "/usr/bin/buildslave start /var/lib/buildbot/slaves/openvpn"
    stop "/usr/bin/buildslave stop /var/lib/buildbot/slaves/openvpn"

A more common approach is to add

$ buildslave start /var/lib/buildbot/slaves/openvpn

to /etc/rc.local or similar startup script. Yet another option is to make cron test if buildslave is running, and to launch it if it's not.

Installation and setup using distro packages on Debian/Ubuntu?

Debian and Ubuntu have buildbot-slave in their repositories. First become a root user using sudo or su. Then install the buildslave application with

$ apt-get update && apt-get install buildbot-slave

After the install you have to create the buildslave instance as described above in "Setting up a new buildslave instance" section.

Then enable this particular buildbot instance by editing /etc/default/buildslave:

SLAVE_RUNNER=/usr/bin/buildslave

# NOTE: SLAVE_ENABLED has changed its behaviour in version 0.8.4. Use
# 'true|yes|1' to enable instance and 'false|no|0' to disable. Other
# values will be considered as syntax error.

SLAVE_ENABLED[1]=1
SLAVE_NAME[1]=openvpn
SLAVE_USER[1]=root
SLAVE_BASEDIR[1]=/var/lib/buildbot/slaves/openvpn
SLAVE_OPTIONS[1]=
SLAVE_PREFIXCMD[1]=

On non-systemd distros you start the buildslave like this:

$ service buildslave start

On systemctl-enabled distros you'd do this instead:

$ systemctl start buildslave

Installation and setup using distro packages on Fedora

Fedora has buildbot-slave in its repositories, and the installation is a breeze:

$ dnf install buildbot-slave

After the install you have to create the buildslave instance as described above in "Setting up a new buildslave instance" section.

Unfortunately there is no startup script in the buildbot-slave Fedora package, so you will have to create a startup script yourself. See "Starting the buildslave at boot-time" section (above) for details.

Installation and setup using easy_install

A fairly easy and somewhat OS-agnostic way to install buildbot is to use easy_install: it should be available your OS'es software repository. By using easy_install the buildslave is isolated from your OS'es package management, but dependencies are taken care for you. It is easiest (but not necessary) to run easy_install as root:

First switch to root account (e.g. sudo or su). Then test that easy_install should work as expected:

$ easy_install -n buildbot==0.8.5

If all went well, install buildbot for real:

$ easy_install buildbot==0.8.5

You can install any version that is known to be compatible with our buildmaster - see above for details. Once buildslave is installed you can and should switch to an ordinary user account.

Buildslave configuration is covered thoroughly in the the buildbot manual. Basically you just step through the "Creating a buildslave" section in the buildbot manual except that you could skip step 1 ("Set up the account") because the connectivity tests require root access.

Step-by-step, the following is needed:

  1. create a user ("buildbot")
  2. create a buildslave configuration, in a subdirectory of buildbot's home directory
    user$ sudo su - buildbot
    buildbot$ buildslave create-slave ~/build-openvpn 10.177.36.101:9989 <buildbot name> <buildbot pass>
    

this will create a subdirectory "build-openvpn/" which has a *.tac file with the buildbot config (so, username, buildmaster, etc. can be edited later on). <buildbot-name> and <buildbot-pass> need to be coordinated with the buildmaster admins (mattock).

  1. ensure the community VPN is up (ping 10.177.36.101 works)
  2. start the buildslave
    buildbot$ buildslave start ~/build-openvpn
    
  3. ensure that community VPN and buildslave get started at boot time...

In case you need to run the buildslave as a limited user you may follow these steps:

  • create the user, e.g. 'buildbot'.
  • uncomment the RUN_SUDO=sudo line in t_client.rc.
  • create a sudoers snippet in /etc/sudoers.d with the command 'visudo -f /etc/sudoers.d/buildbot'.

The buildbot user needs to run two commands as root: 'kill' and the 'openvpn' executable inside the various directories of the buildslave project.

An example visudo line would be:

buildbot ALL=(root) NOPASSWD: /usr/bin/kill,/home/buildbot/<build_slave_dir>/*/build/src/openvpn/openvpn

Installing OpenSSL/PolarSSL development files

We test building OpenVPN with both OpenSSL and PolarSSL backends, so you need to both of them installed on your buildslave:

  • For OpenSSL you can typically use whatever development package (e.g. libssl-dev) you operating system provides, because it's APIs are fairly stable.
  • With PolarSSL the best bet is to get latest stable version from the PolarSSL homepage, because the APIs change quite often and OpenVPN tends to track the latest one.

Configuring the buildslave for connectivity tests

OpenVPN project's buildslaves run connectivity tests against several OpenVPN test servers once per on every commit. Due to these tests the openvpn instances launched by buildbot need to run as root.

As the tests connect to remote OpenVPN servers you will need test certificates and a t_client.rc config file from the buildmaster admins (see above). Once you've have the files, put them to /home/buildbot:

$ tree /home/buildbot
/home/buildbot
├── t_client.rc
├── test-ca.crt
├── test-client.crt
├── test-client.key
└── test-ta.key

0 directories, 5 files

Now make sure that the files

  • are named exactly as shown above or buildbot won't find them and will fail
  • are readable by root
  • have strict enough permissions to keep OpenVPN happy
    • 600 for test-client.key
    • 644 for other files

Finally install fping and fping6, which the tests use to test for basic connectivity.

Once you're finished doing all of this, contact the buildmaster admins so that they can force a build (and the associated connectivity tests) on your buildslave. The first build is expected to fail, because the t_client.rc you were given first is a generic one. After the first build you can fix the values in t_client.rc file by looking at client test logs in <buildslave-dir/build/<buildername>/tests/t_client_<buildername>-<id>. For example, for the Ubuntu 12.04 buildslave the build logs were in this directory:

  • /var/lib/buildbot/slaves/openvpn/build-ubuntu-1204-i386-stable-master/build/tests/t_client-ubuntu-1204-i386-20141217-160636

Look into files 1:ifconfig_route.txt and 2:ifconfig_route.txt to see which IPv4 and IPv6 addresses the test VPN servers gave to the OpenVPN client and adjust t_client.rc to match those values. After that ask somebody to trigger a new build and see if all works as expected. Rinse and repeat as necessary.

List of existing buildslaves

Here's a comprehensive list of Buildslaves already running (as of Apr 2014). There can be several buildslaves that have the same OS/architecture combination, but this is seldom necessary.

Operating systemVersionArchitecture24/7Connection testsProvided byNotes
Debian7 (wheezy)i386YesYes1mattock
Ubuntu12.04i386YesYes1mattock
Ubuntu14.04amd64YesYes1mattock
Ubuntu16.04amd64YesYes1mattock
CentOS6amd64NoYes1mattock
Fedora24amd64NoYes1mattock
FreeBSD7.4amd64YesYescron2
FreeBSD9.3amd64YesYescron2
FreeBSD10.3amd64YesYescron2
OpenBSD4.9i386YesYescron2
OpenBSD6.0i386YesYescron2
NetBSD5.1amd64YesYescron2
NetBSD7.0.1amd64YesYescron2
Opensolaris10i386YesYescron2
MacOS Xamd64NoYesplaisthos

Notes:

  1. These buildslaves run tests 1-6 without the "a" variants. In practice this means that proxy and IPv6 transport are untested.

List of build permutations

Each commit triggers several builds of OpenVPN, each with a different set of configure options:

config_opt_combos = [
    "",
    "--disable-crypto",
    "--disable-crypto --disable-lzo",
    "--disable-crypto --disable-lzo --disable-management",
    "--disable-crypto --disable-management",
    "--disable-lz4",
    "--disable-lzo",
    "--disable-lzo --disable-lz4 --enable-comp-stub",
    "--disable-lzo --disable-management",
    "--disable-management",
    "--disable-server --enable-small",
    "--enable-small",
    "--with-crypto-library=mbedtls --enable-crypto",
]

Most of the builds just build OpenVPN to ensure the buildsystem works. However, two of them also trigger a suite of t_client.sh connectivity tests:

  • ./configure
  • ./configure --with-crypto-library=mbedtls --enable-crypto

The connectivity tests help ensure that basic functionality in OpenVPN is never completely broken.

Troubleshooting

In case your build fails, try running the same build steps manually to see what the problem is.

Source checkout

If you're running into odd problems with buildslave Git checkouts you can try manually running the same commands the buildslave would run. The exact steps can be found from the buildslave's Git logs (in the buildmaster web interface), but they should be similar to these:

$ mkdir /tmp/openvpntest
$ cd /tmp/openvpntest
$ git init
$ git fetch -t git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn.git +master
$ git reset --hard FETCH_HEAD
$ git branch -M master

If you're unable to run these commands manually then the buildslave won't be able to do it either.

Additional Enviroment variables

Add this to buildbot.tac, a bit hackish but works fine:

for e in  ['LZO_CFLAGS=-I/usr/local/include', 
           'LZO_LIBS=-llzo2 -L/usr/local/lib',
	   'MBEDTLS_CFLAGS=-I/usr/local/Cellar/mbedtls/2.3.0_1/include',
	   'MBEDTLS_LIBS=-L/usr/local/Cellar/mbedtls/2.3.0_1/lib/ -lmbedtls -lmbedx509 -lmbedcrypto',
	   'OPENSSL_CFLAGS=-I/usr/local/Cellar/openssl/1.0.2h_1/include/',
	   'OPENSSL_LIBS=-L/usr/local/Cellar/openssl/1.0.2h_1/lib/ -lcrypto -lssl']:
	   var, value = e.split('=',1)
	   os.environ[var]=value