| 12 | | '''NOTE:''' The buildslave needs root access to be able to connect to the t_client.sh test servers using OpenVPN. Moreover, anyone who controls the buildmaster can do whatever he wants on the buildslaves by simply modifying the build procedure. For this reason you should only run buildslaves on expendable virtual machines. That said, you can grant limited ''sudo'' privileges to a normal user to run buildbot as a normal user: see section "Running builtdot as non-root user" for details. |
| 13 | | |
| 14 | | = Creating a VM for the buildslave = |
| 15 | | |
| 16 | | A Linux VM will probably need at least 768MB of memory. Some distros such as Fedora 24 suggests 1024MB as the bare minimum. The VM should have at least 8GB of diskspace, but adding a bit more helps avoid problems later on. |
| 17 | | |
| 18 | | = Ensure that OpenVPN builds correctly = |
| 19 | | |
| 20 | | The first step is to ensure you can build OpenVPN on your buildslave VM. On !Debian/Ubuntu this takes care of most of the dependencies (from [https://github.com/Puppet-Finland/openvpn/blob/master/manifests/params.pp here]): |
| 21 | | |
| 22 | | {{{ |
| 23 | | $ apt-get update |
| 24 | | $ apt-get install liblzo2-dev libssl-dev libpam-dev libpkcs11-helper-dev libtool autoconf make cmake |
| 25 | | }}} |
| 26 | | |
| 27 | | On Fedora you'd do |
| 28 | | |
| 29 | | {{{ |
| 30 | | $ dnf install lzo-devel openssl-devel pam-devel pkcs11-helper-devel gnutls-devel autoconf libtool make cmake |
| 31 | | }}} |
| 32 | | |
| 33 | | And on !RedHat/CentOS/Scientific Linux you'd do |
| 34 | | |
| 35 | | {{{ |
| 36 | | $ yum install lzo-devel openssl-devel pam-devel pkcs11-helper-devel gnutls-devel autoconf libtool make cmake |
| 37 | | }}} |
| 38 | | |
| 39 | | On *BSD derivatives the procedure is roughly similar. |
| 40 | | |
| 41 | | On top of this you need to build and install [https://tls.mbed.org/ mbedTLS]. As OpenVPN tends to follow mbedTLS's rapidly changing APIs, installing the latest version is usually the best choice. Follow the instructions in the release package on how to build mbedTLS on your system. |
| 42 | | |
| 43 | | Once you've installed all the build dependencies [wiki:TesterDocumentation#Building try building OpenVPN]. You should test at least |
| 44 | | |
| 45 | | {{{ |
| 46 | | $ ./configure |
| 47 | | }}} |
| 48 | | and |
| 49 | | {{{ |
| 50 | | $ ./configure --with-crypto-library=mbedtls --enable-crypto |
| 51 | | }}} |
| 52 | | The former tests OpenSSL builds and the latter tests mbedTLS builds. If these two builds succeed, there is high probability that your buildslave will not fail miserably when put to work. |
| | 12 | '''NOTE:''' The workers need root access to be able to connect to the t_client.sh test servers using OpenVPN. Moreover, anyone who controls the buildmaster can do whatever he wants on the workers by simply modifying the build procedure. For this reason you should only run workers on expendable virtual machines or containers. That said, you can grant limited ''sudo'' privileges to a normal user to run buildbot as a normal user: see section "Running builtdot as non-root user" for details. |
| | 13 | |
| | 14 | = OpenVPN projects being built by Buildbot = |
| | 15 | |
| | 16 | Currently buildbot builds the following codebases: |
| | 17 | |
| | 18 | * openvpn |
| | 19 | * openvpn3 |
| | 20 | * openvpn3-linux |
| | 21 | * ovpn-dco |
| | 22 | |
| | 23 | You can decide which ones you want your buildbot worker to build. |
| | 24 | |
| | 25 | = Creating a VM for a worker = |
| | 26 | |
| | 27 | A Linux VM will probably need about 1024MB of memory.The VM should have at least 8GB of diskspace, but adding a bit more helps avoid problems later on. |
| | 28 | |
| | 29 | = Ensure that manual building works correctly = |
| | 30 | |
| | 31 | The first step is to ensure you can build all the codebases you need. If manually building does not work, it cannot work in buildbot, either. Please follow the instructions for each codebase on how to build. |
| 56 | | Our buildmaster is accessible only via OpenVPN. The following sections describe what you need to to connect to the VPN. |
| 57 | | |
| 58 | | == Creating the community user account == |
| 59 | | |
| 60 | | First you need an [https://community.openvpn.net/account 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: |
| 61 | | |
| 62 | | {{{ |
| 63 | | <youralias>-<operatingsystem>-<version>-<architecture> |
| 64 | | }}} |
| 65 | | For example: |
| 66 | | {{{ |
| 67 | | cron2-freebsd-103-amd64 |
| 68 | | }}} |
| 69 | | |
| 70 | | There is no need to create a dedicated email account for the buildslave: using your personal email address is just fine. You can use your own firstname and lastname for the account, or just fake them. |
| 71 | | |
| 72 | | == Getting membership in the appropriate community LDAP group == |
| 73 | | |
| 74 | | 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. |
| 75 | | |
| 76 | | == Getting the OpenVPN configuration file == |
| 77 | | |
| 78 | | 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. Place the configuration file to the usual place, e.g. ''/etc/openvpn/buildslave.conf''. |
| 79 | | |
| 80 | | == Starting OpenVPN == |
| 81 | | |
| 82 | | Non-systemd distros typically blindly launch connections for every ''.conf'' file they find under ''/etc/openvpn'' at boot-time. Launching the VPN connection manually is as simple as |
| 83 | | |
| 84 | | {{{ |
| 85 | | $ service openvpn start |
| 86 | | }}} |
| 87 | | |
| 88 | | Systemd distros will not automatically start any single VPN connection without a bit of trickery: |
| 89 | | |
| 90 | | {{{ |
| 91 | | $ ln -s /etc/systemd/system/multi-user.target.wants/openvpn@buildslave.service /usr/lib/systemd/system/openvpn@.service |
| 92 | | }}} |
| 93 | | |
| 94 | | Launching a VPN connection on systemd distros is fairly straightforward: |
| 95 | | |
| 96 | | {{{ |
| 97 | | $ systemctl start openvpn@buildslave |
| 98 | | }}} |
| 99 | | |
| 100 | | Note that the above will only work if the OpenVPN configuration file is in ''/etc/openvpn/buildslave.conf''. |
| | 35 | Our buildmaster is accessible only via the community VPN. Please ask ''mattock'' on IRC for VPN config for your worker. You will get the config in Signal or in an GnuPG-encrypted email. The community VPN server pushes DNS servers as well, so you may want to process those if you want to use DNS names instead of IP addresses. |
| 104 | | A simple ping test should be enough to verify that your buildslave can reach buildmaster: |
| 105 | | |
| 106 | | {{{ |
| 107 | | $ ping 10.7.39.137 |
| 108 | | }}} |
| 109 | | |
| 110 | | = Setting up a buildslave = |
| 111 | | |
| 112 | | 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. Generic setup instructions are available in the [http://docs.buildbot.net/current the buildbot manual]. |
| 113 | | |
| 114 | | == Common setup tasks == |
| 115 | | |
| 116 | | These tasks are out of order and referred to in the setup instructions. Please do not run these right now. |
| 117 | | |
| 118 | | === Setting up a new buildslave instance === |
| 119 | | |
| 120 | | 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. |
| 121 | | |
| 122 | | {{{ |
| 123 | | $ buildslave create-slave /var/lib/buildbot/slaves/openvpn 10.7.39.137:9989 <slavename> |
| 124 | | }}} |
| 125 | | |
| 126 | | The slavename translates to ''slave-<youralias>-<operatingsystem>-<version>-<architecture> <buildslave-password>''. |
| 127 | | |
| 128 | | 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 for !RedHat derivatives as well. |
| 129 | | |
| 130 | | The buildslave directory has a *.tac file with the buildbot config, so the settings can be edited later on. You can get the <buildslave-password> from the buildmaster admins. |
| 131 | | |
| 132 | | === Starting the buildslave at boot-time === |
| 133 | | |
| 134 | | 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 [https://www.mmonit.com/monit/ monit] then you can use this monit fragment: |
| 135 | | |
| 136 | | {{{ |
| 137 | | check process buildslave-openvpn with pidfile /var/lib/buildbot/slaves/openvpn/twistd.pid |
| 138 | | start "/usr/bin/buildslave start /var/lib/buildbot/slaves/openvpn" |
| 139 | | stop "/usr/bin/buildslave stop /var/lib/buildbot/slaves/openvpn" |
| 140 | | }}} |
| 141 | | |
| 142 | | Monit not only starts the buildslave, but also ensures that it is running all the time. |
| 143 | | |
| 144 | | Another approach is to add |
| 145 | | {{{ |
| 146 | | $ buildslave start /var/lib/buildbot/slaves/openvpn |
| 147 | | }}} |
| 148 | | to ''/etc/rc.local'' or similar startup script. Yet another option is to make cron periodically test if buildslave is running, and to launch it if it's not. |
| | 39 | A simple ping test should be enough to verify that your worker can reach buildmaster: |
| | 40 | |
| | 41 | {{{ |
| | 42 | $ ping buildbot-host.openvpn.in |
| | 43 | $ ping 10.18.0.59 |
| | 44 | }}} |
| | 45 | |
| | 46 | If both work, it means your VPN client is properly configured. If pinging by name fails, but by IP works, then your VPN client is not processing DNS settings pushed by the OpenVPN server properly. But you can still point your worker to the IP, so it is not a blocker. |
| | 47 | |
| | 48 | = Setting up a worker = |
| 165 | | == Buildslave setup using distro packages on !Debian/Ubuntu == |
| 166 | | |
| 167 | | Debian and Ubuntu have buildbot-slave in their repositories. First become a root user using ''sudo'' or ''su''. Then install the buildslave application with |
| 168 | | |
| 169 | | {{{ |
| 170 | | $ apt-get update && apt-get install buildbot-slave |
| 171 | | }}} |
| 172 | | |
| 173 | | After the install you have to create the buildslave instance as described above in "Setting up a new buildslave instance" section. |
| 174 | | |
| 175 | | The newly created buildbot instance has to be enabled by editing ''/etc/default/buildslave'': |
| 176 | | |
| 177 | | {{{ |
| 178 | | SLAVE_RUNNER=/usr/bin/buildslave |
| 179 | | |
| 180 | | # NOTE: SLAVE_ENABLED has changed its behaviour in version 0.8.4. Use |
| 181 | | # 'true|yes|1' to enable instance and 'false|no|0' to disable. Other |
| 182 | | # values will be considered as syntax error. |
| 183 | | |
| 184 | | SLAVE_ENABLED[1]=1 |
| 185 | | SLAVE_NAME[1]=openvpn |
| 186 | | # root user is needed, see above for details |
| 187 | | SLAVE_USER[1]=root |
| 188 | | SLAVE_BASEDIR[1]=/var/lib/buildbot/slaves/openvpn |
| 189 | | SLAVE_OPTIONS[1]= |
| 190 | | SLAVE_PREFIXCMD[1]= |
| 191 | | }}} |
| 192 | | |
| 193 | | On non-systemd distros you start the buildslave like this: |
| 194 | | |
| 195 | | {{{ |
| 196 | | $ service buildslave start |
| 197 | | }}} |
| 198 | | On systemctl-enabled distros you'd do this instead: |
| 199 | | {{{ |
| 200 | | $ systemctl start buildslave |
| 201 | | }}} |
| 202 | | |
| 203 | | == Buildslave setup using distro packages on Fedora == |
| 204 | | |
| 205 | | Fedora has buildbot-slave in its repositories, and the installation is a breeze: |
| 206 | | |
| 207 | | {{{ |
| 208 | | $ dnf install buildbot-slave |
| 209 | | }}} |
| 210 | | |
| 211 | | After the install you have to create the buildslave instance as described above in "Setting up a new buildslave instance" section. Then start the buildslave with |
| 212 | | |
| 213 | | {{{ |
| 214 | | $ buildslave start /var/lib/buildbot/slaves/openvpn |
| 215 | | }}} |
| 216 | | |
| 217 | | 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. |
| 218 | | |
| 219 | | == Buildslave setup using easy_install == |
| 220 | | |
| 221 | | A fairly easy and somewhat OS-agnostic way to install buildbot is to use [http://pypi.python.org/pypi/setuptools 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 [http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations not necessary]) to run ''easy_install'' as root: |
| 222 | | |
| 223 | | First switch to root account (e.g. ''sudo'' or ''su''). Then test that easy_install should work as expected: |
| 224 | | |
| 225 | | {{{ |
| 226 | | $ easy_install -n buildbot==0.8.5 |
| 227 | | }}} |
| 228 | | |
| 229 | | If all went well, install buildbot for real: |
| 230 | | |
| 231 | | {{{ |
| 232 | | $ easy_install buildbot==0.8.5 |
| 233 | | }}} |
| 234 | | |
| 235 | | You can install any version that is known to be compatible with our buildmaster (see above) |
| 236 | | |
| 237 | | Next setup a buildslave instance as described in "Setting up a new buildslave instance", and then start the buildslave: |
| 238 | | |
| 239 | | {{{ |
| 240 | | $ buildslave start /var/lib/buildbot/slaves/openvpn |
| 241 | | }}} |
| 242 | | |
| 243 | | Finally you need to ensure that buildslave starts at boot-time; see "Starting the buildslave at boot-time" section, above, for details. |
| | 65 | |
