From 50dbfbb685ef10561e61460b815cc64d4636d453 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 19:38:03 +0100 Subject: [PATCH 01/16] Fix keepalive, port table, and info path in buildbot worker docs --- testing/new-buildbot-worker.rst | 41 +++++++++++++++++---------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 8c3f99acb..858bc4953 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -274,9 +274,10 @@ machine reboots: service as described in the `buildbot documentation `__. -To start the worker running for your initial testing, you can do:: +If you have not already started the worker through a service manager, you +can start it manually for initial testing:: - buildbot-worker start buildarea + buildbot-worker start /path/to/workerdir Then you can either wait for someone to make a commit, or you can pick a builder associated with your worker from the `list of builders @@ -289,11 +290,11 @@ only of failures on your builders, so doing periodic spot checks is also a good idea. .. note:: - If your buildbot worker is disconnecting regularly, it may be a symptom of the - default ``keepalive`` value (``600`` for 10 minutes) being `set - `__ - too high. You can change it to a lower value (for example, ``180`` for 3 minutes) - in the ``buildbot.tac`` file found in your build area. + The buildmaster uses a ``keepalive`` interval of ``60`` seconds. Ensure + the ``keepalive`` setting in your ``buildbot.tac`` matches (the default + of ``600`` is too high and can cause spurious disconnections). It is + also recommended to set ``delete_leftover_dirs = 1`` so that build + directories the master no longer needs are cleaned up automatically. Latent workers @@ -357,7 +358,7 @@ Necessary tasks include, obviously, keeping the buildbot running. Currently the system for notifying buildbot owners when their workers go offline is not working; this is something we hope to resolve. So currently it is helpful if you periodically check the status of your worker. We will also contact you -via your contact address in ``buildarea/info/admin`` when we notice there is a +via your contact address in ``info/admin`` when we notice there is a problem that has not been resolved for some period of time and you have not responded to a posting on the python-buildbots list about it. @@ -386,19 +387,19 @@ a table listing all of the outbound ports used by the buildbot and the python test suite (this list may not be complete as new tests may have been added since this table was last vetted): -======= =================== ================================================ -Port Host Description -======= =================== ================================================ -20, 21 ftp.debian.org test_urllib2net -53 your DNS server test_socket, and others implicitly -80 python.org (several tests) +======= ========================== ================================================ +Port Host Description +======= ========================== ================================================ +20, 21 ftp.debian.org test_urllib2net +53 your DNS server test_socket, and others implicitly +80 python.org (several tests) example.com -119 news.gmane.org test_nntplib (Python versions < 3.13) -443 (various) test_ssl -465 smtp.gmail.com test_smtpnet -587 smtp.gmail.com test_smtpnet -9020 python.org connection to buildmaster -======= =================== ================================================ +119 news.gmane.org test_nntplib (Python versions < 3.13) +443 (various) test_ssl +465 smtp.gmail.com test_smtpnet +587 smtp.gmail.com test_smtpnet +9020 buildbot-api.python.org connection to buildmaster +======= ========================== ================================================ Many tests will also create local TCP sockets and connect to them, usually using either ``localhost`` or ``127.0.0.1``. From 97ab6dbc0bf710a50a48d2fba9743c81a2c378a5 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 19:49:16 +0100 Subject: [PATCH 02/16] Update buildbot worker intro and info file paths --- testing/new-buildbot-worker.rst | 41 +++++++++++++++++---------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 858bc4953..695bb4ff2 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -60,13 +60,15 @@ Setting up the buildbot worker Conventional always-on machines ------------------------------- -You need a recent version of the `buildbot `__ software, -and you will probably want a separate 'buildbot' user to run the buildbot -software. You may also want to set the buildbot up using a virtual -environment, depending on how you manage your system. We won't cover how to that -here; it doesn't differ from setting up a virtual environment for any other -software, but you'll need to modify the sequence of steps below as appropriate -if you choose that path. +You need a recent version of the `buildbot `__ worker +software. On most platforms the distribution's package manager provides the +``buildbot-worker`` package, which also creates a dedicated service account, +systemd unit (or equivalent), and the necessary directories. For platforms +where no package exists, ``pip install buildbot-worker`` is the fallback, but +you will need to create the service account, directories, and service unit +manually. You may also want to set the buildbot up using a virtual +environment, depending on how you manage your system; you'll need to adjust +the steps below as appropriate if you choose that path. .. tab:: Linux @@ -132,11 +134,18 @@ if you choose that path. buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd -Once this initial worker setup completes, you should edit the files -``buildarea/info/admin`` and ``buildarea/info/host`` to provide your contact -info and information on the host configuration, respectively. This information -will be presented in the buildbot web pages that display information about the -builders running on your worker. +The ``info/admin`` file in the worker directory should contain your contact +information, and ``info/host`` should describe the host configuration. This +information is displayed on the buildbot web interface. Since these pages are +publicly visible, consider obfuscating your email address (for example, +``user AT example.com``) to avoid spam from web scrapers. + +The recommended ``buildbot.tac`` settings are: + +* ``keepalive = 60`` -- the buildmaster uses a 60-second keepalive interval; + the default of ``600`` is too high and can cause spurious disconnections. +* ``delete_leftover_dirs = 1`` -- automatically cleans up build directories + that the master no longer needs. You will also want to make sure that the worker is started when the machine reboots: @@ -289,14 +298,6 @@ by tests that fail. Unfortunately we do not currently have a way to notify you only of failures on your builders, so doing periodic spot checks is also a good idea. -.. note:: - The buildmaster uses a ``keepalive`` interval of ``60`` seconds. Ensure - the ``keepalive`` setting in your ``buildbot.tac`` matches (the default - of ``600`` is too high and can cause spurious disconnections). It is - also recommended to set ``delete_leftover_dirs = 1`` so that build - directories the master no longer needs are cleaned up automatically. - - Latent workers -------------- From e981fd66c9868695188e3d1ab460cd73346555bd Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 20:49:52 +0100 Subject: [PATCH 03/16] Rewrite Linux installation tab with per-distro nested tabs --- testing/new-buildbot-worker.rst | 146 +++++++++++++++++++++++++++++--- 1 file changed, 136 insertions(+), 10 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 695bb4ff2..3780eb16b 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -72,18 +72,144 @@ the steps below as appropriate if you choose that path. .. tab:: Linux - * If your package manager provides the buildbot worker software, that is - probably the best way to install it; it may create the buildbot user for - you, in which case you can skip the next step. Otherwise, do ``pip install - buildbot-worker`` or ``pip3 install buildbot-worker``. - * Create a ``buildbot`` user (using, eg: ``useradd``) if necessary. - * Log in as the buildbot user. + .. tab:: Fedora / RHEL / CentOS - In a terminal window for the buildbot user, issue the following commands (you - can put the ``buildarea`` wherever you want to):: + **Fedora**:: - mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + dnf install buildbot-worker + + **RHEL 8** (requires EPEL):: + + subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms + dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm + dnf install buildbot-worker + + **RHEL 9** (requires EPEL):: + + subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms + dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm + dnf install buildbot-worker + + **CentOS Stream 9 / 10** (requires CRB + EPEL):: + + dnf config-manager --set-enabled crb + dnf install epel-release epel-next-release + dnf install buildbot-worker + + The RPM creates a ``buildbot-worker`` system user (nologin shell, home + at ``/var/lib/buildbot/worker``), installs a templated systemd unit + ``buildbot-worker@.service``, and creates ``/var/lib/buildbot/worker/``. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot-worker buildbot-worker create-worker \ + /var/lib/buildbot/worker/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + systemctl enable --now buildbot-worker@WORKERNAME.service + + .. tab:: Debian / Ubuntu + + :: + + apt install buildbot-worker + + The package creates a ``buildbot`` system user, installs a templated + systemd unit ``buildbot-worker@.service``, and creates + ``/var/lib/buildbot/workers/``. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot buildbot-worker create-worker \ + /var/lib/buildbot/workers/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + systemctl enable --now buildbot-worker@WORKERNAME.service + + .. tab:: FreeBSD + + :: + + pkg install devel/py-buildbot-worker + + The port creates a ``buildbot`` system user (nologin shell, home at + ``/var/db/buildbot``) and installs an ``rc.d`` script at + ``/usr/local/etc/rc.d/buildbot-worker`` with profile support. + The default base directory is ``/var/db/buildbot/workers``. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + su -m buildbot -c "buildbot-worker create-worker \ + /var/db/buildbot/workers/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service. The rc.d script uses profile names as + shell variable identifiers, so pick a short name without hyphens + (it does not need to match the worker name):: + + sysrc buildbot_worker_enable=YES + sysrc buildbot_worker_profiles="myworker" + sysrc buildbot_worker_myworker_enable=YES + sysrc buildbot_worker_myworker_basedir=/var/db/buildbot/workers/WORKERNAME + service buildbot-worker start + + .. tab:: Other / pip + + For distros without a ``buildbot-worker`` package, install via pip:: + + pip install buildbot-worker + + **NixOS** users should use the built-in ``services.buildbot-worker`` + NixOS module; see the + `nixpkgs module source `__ + for available options. + + **Arch Linux** has buildbot packages in the AUR, but they are + currently unmaintained. Using pip is more reliable. + + pip does **not** create a system user, directories, or service unit. + Set these up manually. On distros with ``useradd``:: + + useradd --system --shell /sbin/nologin \ + --home-dir /var/lib/buildbot/worker --create-home buildbot-worker + + On Alpine Linux (BusyBox):: + + adduser -S -D -H -h /var/lib/buildbot/worker -s /sbin/nologin buildbot-worker + + Then create the directories:: + + mkdir -p /var/lib/buildbot/worker + chown buildbot-worker:buildbot-worker /var/lib/buildbot/worker + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot-worker buildbot-worker create-worker \ + /var/lib/buildbot/worker/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + On systemd-based distros, a service unit must also be installed; see + the service management section below. .. tab:: macOS From a9246e651e859c4952113cce913c6fbeac08d9bf Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 21:10:07 +0100 Subject: [PATCH 04/16] Rewrite Linux service management with modern systemd unit --- testing/new-buildbot-worker.rst | 136 ++++++++++++++++---------------- 1 file changed, 67 insertions(+), 69 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 3780eb16b..bf16110e2 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -273,80 +273,78 @@ The recommended ``buildbot.tac`` settings are: * ``delete_leftover_dirs = 1`` -- automatically cleans up build directories that the master no longer needs. +Service management +~~~~~~~~~~~~~~~~~~ + You will also want to make sure that the worker is started when the machine reboots: .. tab:: Linux - * For systemd based distributions, you can create a systemd unit file in order - to manage the service. Create the unit file named ``buildbot-worker.service`` - under ``/home/buildbot/.config/systemd/user/`` and change the paths according to where the - buildbot-worker binary resides. You can verify its location by running - ``which buildbot-worker``. - If you installed the buildbot-worker through - your package manager it would be:: - - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target - - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/bin/buildbot-worker start - ExecReload=/usr/bin/buildbot-worker restart - ExecStop=/usr/bin/buildbot-worker stop - Restart=always - User=buildbot - - [Install] - WantedBy=multi-user.target - - - If you installed the buildbot-worker through pip, the systemd unit - file should look like this:: - - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target - - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/local/bin/buildbot-worker start - ExecReload=/usr/local/bin/buildbot-worker restart - ExecStop=/usr/local/bin/buildbot-worker stop - Restart=always - User=buildbot - - [Install] - WantedBy=multi-user.target - - - Then enable lingering for the buildbot user via the - ``loginctl enable-linger buildbot`` command and you can start - the service through a login shell of the buildbot user - via the ``systemctl --user enable --now buildbot-worker.service`` - command. - - Note that using a systemd unit file, might produce some SELinux warnings on systems - where the enforcing mode is enabled, usually related to the ``twistd.pid`` file. - If the service fails to start, you should check the output of - ``systemctl status buildbot-worker.service`` as well as the - ``/var/log/audit/audit.log`` file (for example, through - ``sealert -a /var/log/audit/audit.log``) for potential issues and remedies. - - * Alternatively you can create a cronjob. Add the following line to ``/etc/crontab``:: - - @reboot buildbot-worker restart /path/to/buildarea - - Note that we use ``restart`` rather than ``start`` in case a crash has - left a ``twistd.pid`` file behind. - + If you installed via a distro package (Fedora, RHEL, CentOS, Debian, + Ubuntu, or FreeBSD), the service was already enabled in the installation + step above. + + **Manual systemd setup (pip installs)** + + If you installed via pip, you need to install a systemd unit yourself. + The upstream buildbot project provides a + `contributed template unit `__ + along with + `sysusers.d and tmpfiles.d configs `__. + + Create ``/etc/systemd/system/buildbot-worker@.service`` with the + following contents:: + + [Unit] + Description=Buildbot Worker %I + Documentation=man:buildbot-worker(1) https://docs.buildbot.net/ + After=network.target + ConditionDirectoryNotEmpty=/var/lib/buildbot/worker/%i + ConditionFileNotEmpty=/var/lib/buildbot/worker/%i/buildbot.tac + + [Service] + Type=simple + User=buildbot-worker + Group=buildbot-worker + WorkingDirectory=/var/lib/buildbot/worker/ + StateDirectory=buildbot/worker + ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %I + Restart=always + ProtectSystem=full + ProtectHome=yes + PrivateDevices=yes + PrivateTmp=yes + + [Install] + WantedBy=multi-user.target + + Adjust ``User``, ``Group``, ``WorkingDirectory``, and the + ``ExecStart`` path to match your setup. Then:: + + systemctl daemon-reload + systemctl enable --now buildbot-worker@WORKERNAME.service + + **SysV init (non-systemd distros)** + + For distros without systemd (such as Alpine Linux with OpenRC), upstream + provides a + `SysV init script `__ + with a + `default configuration file `__. + Install these as ``/etc/init.d/buildbot-worker`` and + ``/etc/default/buildbot-worker`` respectively, then configure the worker + instances in the default file. + + **Cronjob alternative** + + If neither systemd nor a SysV init script is practical, you can use a + cronjob. Add the following line to ``/etc/crontab``:: + + @reboot buildbot-worker restart /path/to/workerdir + + Note that ``restart`` is used rather than ``start`` in case a crash has + left a ``twistd.pid`` file behind. .. tab:: macOS From 7bb9c87331e35f8c976664068042e01f643896f8 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 21:24:39 +0100 Subject: [PATCH 05/16] Add filesystem layout and disk space tips --- testing/new-buildbot-worker.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index bf16110e2..5e7fc654f 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -273,6 +273,23 @@ The recommended ``buildbot.tac`` settings are: * ``delete_leftover_dirs = 1`` -- automatically cleans up build directories that the master no longer needs. +.. tip:: + + If your system has most of its disk space on ``/home`` rather than on the + root partition, create the worker data under ``/home`` and symlink it so + the packaged systemd unit still works:: + + mkdir -p /home/buildbot-worker/worker + ln -s /home/buildbot-worker/worker /var/lib/buildbot/worker + + Adjust ownership and paths to match your distro's conventions. + +.. tip:: + + Build directories and ``twistd.log`` rotations can accumulate over time. + Monitor free disk space on the partition that holds the worker directory, + even with ``delete_leftover_dirs`` enabled. + Service management ~~~~~~~~~~~~~~~~~~ From 3d6583784c4016caa31a1a8114afb2c6b67f4348 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Sun, 8 Mar 2026 22:20:34 +0100 Subject: [PATCH 06/16] Fix macOS framework path and consistent placeholder capitalization --- testing/new-buildbot-worker.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 5e7fc654f..edcabeaa7 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -223,7 +223,7 @@ the steps below as appropriate if you choose that path. can put the ``buildarea`` wherever you want to):: mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD .. tab:: Windows @@ -257,7 +257,7 @@ the steps below as appropriate if you choose that path. .. code-block:: mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD The ``info/admin`` file in the worker directory should contain your contact @@ -372,14 +372,11 @@ machine reboots: * Place the following script, named ``run_worker.sh``, into that directory:: #!/bin/bash - export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH + export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH export LC_CTYPE=en_US.utf-8 cd /Users/buildbot/buildarea twistd --nodaemon --python=buildbot.tac --logfile=buildbot.log --prefix=worker - If you use pip with Apple's system python, add '/System' to the front of - the path to the Python bin directory. - * Place a file with the following contents into ``/Library/LaunchDaemons``: .. code-block:: xml From 042c944122c9f90f773c466829fb4ed59ed788da Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:28:12 +0100 Subject: [PATCH 07/16] Fix systemd %I specifier to %i for hyphenated worker names --- testing/new-buildbot-worker.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index edcabeaa7..130ede53c 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -314,7 +314,7 @@ machine reboots: following contents:: [Unit] - Description=Buildbot Worker %I + Description=Buildbot Worker %i Documentation=man:buildbot-worker(1) https://docs.buildbot.net/ After=network.target ConditionDirectoryNotEmpty=/var/lib/buildbot/worker/%i @@ -326,7 +326,7 @@ machine reboots: Group=buildbot-worker WorkingDirectory=/var/lib/buildbot/worker/ StateDirectory=buildbot/worker - ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %I + ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %i Restart=always ProtectSystem=full ProtectHome=yes From a412442980c8141824291979569d93a499a7341b Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:29:18 +0100 Subject: [PATCH 08/16] Note ProtectHome conflict with /home symlink layout --- testing/new-buildbot-worker.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 130ede53c..0a95f201b 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -337,7 +337,10 @@ machine reboots: WantedBy=multi-user.target Adjust ``User``, ``Group``, ``WorkingDirectory``, and the - ``ExecStart`` path to match your setup. Then:: + ``ExecStart`` path to match your setup. If your worker data is + symlinked from ``/home`` (see the filesystem layout tip above), + change ``ProtectHome=yes`` to ``ProtectHome=no`` so systemd can + follow the symlink. Then:: systemctl daemon-reload systemctl enable --now buildbot-worker@WORKERNAME.service From 9c608778a7fc2925eafd3498c1950700dbdbbd60 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:32:38 +0100 Subject: [PATCH 09/16] Clarify resource requirements for minimal builders --- testing/new-buildbot-worker.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 0a95f201b..1cd8d4933 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -560,9 +560,9 @@ buildbot are at least: * 30 GB free disk space Many tests won't run in this configuration, since they require -substantially more memory, but these resources should be sufficient to ensure -that Python compiles correctly on the platform and can run part of the test -suite. +substantially more memory, but these resources should be sufficient. +Builders with minimal settings might need more maintenance: they check +that Python's resource-hungry tests are tagged and skipped correctly. Security considerations From 395e686928a1d4ea8d5736dc7da04c810debfee5 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:35:28 +0100 Subject: [PATCH 10/16] Add nested tabs for Linux service management options --- testing/new-buildbot-worker.rst | 136 ++++++++++++++++---------------- 1 file changed, 69 insertions(+), 67 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 1cd8d4933..a3a7517c7 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -298,73 +298,75 @@ machine reboots: .. tab:: Linux - If you installed via a distro package (Fedora, RHEL, CentOS, Debian, - Ubuntu, or FreeBSD), the service was already enabled in the installation - step above. - - **Manual systemd setup (pip installs)** - - If you installed via pip, you need to install a systemd unit yourself. - The upstream buildbot project provides a - `contributed template unit `__ - along with - `sysusers.d and tmpfiles.d configs `__. - - Create ``/etc/systemd/system/buildbot-worker@.service`` with the - following contents:: - - [Unit] - Description=Buildbot Worker %i - Documentation=man:buildbot-worker(1) https://docs.buildbot.net/ - After=network.target - ConditionDirectoryNotEmpty=/var/lib/buildbot/worker/%i - ConditionFileNotEmpty=/var/lib/buildbot/worker/%i/buildbot.tac - - [Service] - Type=simple - User=buildbot-worker - Group=buildbot-worker - WorkingDirectory=/var/lib/buildbot/worker/ - StateDirectory=buildbot/worker - ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %i - Restart=always - ProtectSystem=full - ProtectHome=yes - PrivateDevices=yes - PrivateTmp=yes - - [Install] - WantedBy=multi-user.target - - Adjust ``User``, ``Group``, ``WorkingDirectory``, and the - ``ExecStart`` path to match your setup. If your worker data is - symlinked from ``/home`` (see the filesystem layout tip above), - change ``ProtectHome=yes`` to ``ProtectHome=no`` so systemd can - follow the symlink. Then:: - - systemctl daemon-reload - systemctl enable --now buildbot-worker@WORKERNAME.service - - **SysV init (non-systemd distros)** - - For distros without systemd (such as Alpine Linux with OpenRC), upstream - provides a - `SysV init script `__ - with a - `default configuration file `__. - Install these as ``/etc/init.d/buildbot-worker`` and - ``/etc/default/buildbot-worker`` respectively, then configure the worker - instances in the default file. - - **Cronjob alternative** - - If neither systemd nor a SysV init script is practical, you can use a - cronjob. Add the following line to ``/etc/crontab``:: - - @reboot buildbot-worker restart /path/to/workerdir - - Note that ``restart`` is used rather than ``start`` in case a crash has - left a ``twistd.pid`` file behind. + .. tab:: Distro package + + If you installed via a distro package (Fedora, RHEL, CentOS, Debian, + or Ubuntu), the service was already enabled in the installation + step above. + + .. tab:: Manual systemd + + If you installed via pip, you need to install a systemd unit yourself. + The upstream buildbot project provides a + `contributed template unit `__ + along with + `sysusers.d and tmpfiles.d configs `__. + + Create ``/etc/systemd/system/buildbot-worker@.service`` with the + following contents:: + + [Unit] + Description=Buildbot Worker %i + Documentation=man:buildbot-worker(1) https://docs.buildbot.net/ + After=network.target + ConditionDirectoryNotEmpty=/var/lib/buildbot/worker/%i + ConditionFileNotEmpty=/var/lib/buildbot/worker/%i/buildbot.tac + + [Service] + Type=simple + User=buildbot-worker + Group=buildbot-worker + WorkingDirectory=/var/lib/buildbot/worker/ + StateDirectory=buildbot/worker + ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %i + Restart=always + ProtectSystem=full + ProtectHome=yes + PrivateDevices=yes + PrivateTmp=yes + + [Install] + WantedBy=multi-user.target + + Adjust ``User``, ``Group``, ``WorkingDirectory``, and the + ``ExecStart`` path to match your setup. If your worker data is + symlinked from ``/home`` (see the filesystem layout tip above), + change ``ProtectHome=yes`` to ``ProtectHome=no`` so systemd can + follow the symlink. Then:: + + systemctl daemon-reload + systemctl enable --now buildbot-worker@WORKERNAME.service + + .. tab:: SysV init + + For distros without systemd (such as Alpine Linux with OpenRC), + upstream provides a + `SysV init script `__ + with a + `default configuration file `__. + Install these as ``/etc/init.d/buildbot-worker`` and + ``/etc/default/buildbot-worker`` respectively, then configure the + worker instances in the default file. + + .. tab:: Cronjob + + If neither systemd nor a SysV init script is practical, you can use + a cronjob. Add the following line to ``/etc/crontab``:: + + @reboot buildbot-worker restart /path/to/workerdir + + Note that ``restart`` is used rather than ``start`` in case a crash + has left a ``twistd.pid`` file behind. .. tab:: macOS From 28617754800a54e902ca611be4c145420bce3daa Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:41:05 +0100 Subject: [PATCH 11/16] Add visual separator before latent workers section --- testing/new-buildbot-worker.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index a3a7517c7..be7121400 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -441,6 +441,8 @@ by tests that fail. Unfortunately we do not currently have a way to notify you only of failures on your builders, so doing periodic spot checks is also a good idea. +---- + Latent workers -------------- From 598fde9b8527a71a6b60935d77e95da95c87ba41 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:46:48 +0100 Subject: [PATCH 12/16] Move FreeBSD to its own top-level Unix tab --- testing/new-buildbot-worker.rst | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index be7121400..21cc5badc 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -138,37 +138,6 @@ the steps below as appropriate if you choose that path. systemctl enable --now buildbot-worker@WORKERNAME.service - .. tab:: FreeBSD - - :: - - pkg install devel/py-buildbot-worker - - The port creates a ``buildbot`` system user (nologin shell, home at - ``/var/db/buildbot``) and installs an ``rc.d`` script at - ``/usr/local/etc/rc.d/buildbot-worker`` with profile support. - The default base directory is ``/var/db/buildbot/workers``. - - Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with - the credentials provided to you from your buildmaster-config issue):: - - su -m buildbot -c "buildbot-worker create-worker \ - /var/db/buildbot/workers/WORKERNAME \ - buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" - - Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker - directory (see below for recommended settings). - - Enable and start the service. The rc.d script uses profile names as - shell variable identifiers, so pick a short name without hyphens - (it does not need to match the worker name):: - - sysrc buildbot_worker_enable=YES - sysrc buildbot_worker_profiles="myworker" - sysrc buildbot_worker_myworker_enable=YES - sysrc buildbot_worker_myworker_basedir=/var/db/buildbot/workers/WORKERNAME - service buildbot-worker start - .. tab:: Other / pip For distros without a ``buildbot-worker`` package, install via pip:: @@ -212,6 +181,40 @@ the steps below as appropriate if you choose that path. the service management section below. +.. tab:: Unix + + .. tab:: FreeBSD + + :: + + pkg install devel/py-buildbot-worker + + The port creates a ``buildbot`` system user (nologin shell, home at + ``/var/db/buildbot``) and installs an ``rc.d`` script at + ``/usr/local/etc/rc.d/buildbot-worker`` with profile support. + The default base directory is ``/var/db/buildbot/workers``. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + su -m buildbot -c "buildbot-worker create-worker \ + /var/db/buildbot/workers/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service. The rc.d script uses profile names as + shell variable identifiers, so pick a short name without hyphens + (it does not need to match the worker name):: + + sysrc buildbot_worker_enable=YES + sysrc buildbot_worker_profiles="myworker" + sysrc buildbot_worker_myworker_enable=YES + sysrc buildbot_worker_myworker_basedir=/var/db/buildbot/workers/WORKERNAME + service buildbot-worker start + + .. tab:: macOS * Create a buildbot user using the macOS control panel user admin. It From b1a99eebefb35dfee35ec7584edf33a258d7a138 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 03:58:52 +0100 Subject: [PATCH 13/16] Move filesystem layout tip into per-distro tabs --- testing/new-buildbot-worker.rst | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 21cc5badc..231c26ea9 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -100,6 +100,17 @@ the steps below as appropriate if you choose that path. at ``/var/lib/buildbot/worker``), installs a templated systemd unit ``buildbot-worker@.service``, and creates ``/var/lib/buildbot/worker/``. + .. tip:: + + If your system has most of its disk space on ``/home`` rather than + on the root partition, create the worker data under ``/home`` and + symlink it so the packaged systemd unit still works:: + + mkdir -p /home/buildbot-worker/worker + ln -s /home/buildbot-worker/worker /var/lib/buildbot/worker + + Adjust ownership and paths to match your distro's conventions. + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with the credentials provided to you from your buildmaster-config issue):: @@ -124,6 +135,17 @@ the steps below as appropriate if you choose that path. systemd unit ``buildbot-worker@.service``, and creates ``/var/lib/buildbot/workers/``. + .. tip:: + + If your system has most of its disk space on ``/home`` rather than + on the root partition, create the worker data under ``/home`` and + symlink it so the packaged systemd unit still works:: + + mkdir -p /home/buildbot/workers + ln -s /home/buildbot/workers /var/lib/buildbot/workers + + Adjust ownership and paths to match your distro's conventions. + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with the credentials provided to you from your buildmaster-config issue):: @@ -276,17 +298,6 @@ The recommended ``buildbot.tac`` settings are: * ``delete_leftover_dirs = 1`` -- automatically cleans up build directories that the master no longer needs. -.. tip:: - - If your system has most of its disk space on ``/home`` rather than on the - root partition, create the worker data under ``/home`` and symlink it so - the packaged systemd unit still works:: - - mkdir -p /home/buildbot-worker/worker - ln -s /home/buildbot-worker/worker /var/lib/buildbot/worker - - Adjust ownership and paths to match your distro's conventions. - .. tip:: Build directories and ``twistd.log`` rotations can accumulate over time. From acd3f86d3d05c6bc459f92d74362a2f324979a47 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 04:06:27 +0100 Subject: [PATCH 14/16] Add Unix service management tab with rc.d --- testing/new-buildbot-worker.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 231c26ea9..bed0d4f1e 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -382,6 +382,16 @@ machine reboots: Note that ``restart`` is used rather than ``start`` in case a crash has left a ``twistd.pid`` file behind. +.. tab:: Unix + + .. tab:: rc.d + + If you installed via a package on FreeBSD (or another BSD), the + service was already enabled in the installation step above. + + If you installed via pip, you will need to write an ``rc.d`` script + or use the cronjob approach described in the Linux tab. + .. tab:: macOS * Create a bin directory for your buildbot user:: From 2402078ed7a71f618791fa22dffd4ab61421da86 Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 19:33:40 +0100 Subject: [PATCH 15/16] Standardize some distro descriptions --- testing/new-buildbot-worker.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index bed0d4f1e..76bc39d80 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -96,9 +96,10 @@ the steps below as appropriate if you choose that path. dnf install epel-release epel-next-release dnf install buildbot-worker - The RPM creates a ``buildbot-worker`` system user (nologin shell, home - at ``/var/lib/buildbot/worker``), installs a templated systemd unit - ``buildbot-worker@.service``, and creates ``/var/lib/buildbot/worker/``. + The RPM creates a ``buildbot-worker`` system user, installs a + templated systemd unit ``buildbot-worker@.service``, and creates + ``/var/lib/buildbot/worker/`` as the base directory for worker + instances. .. tip:: @@ -133,7 +134,8 @@ the steps below as appropriate if you choose that path. The package creates a ``buildbot`` system user, installs a templated systemd unit ``buildbot-worker@.service``, and creates - ``/var/lib/buildbot/workers/``. + ``/var/lib/buildbot/workers/`` as the base directory for worker + instances. .. tip:: @@ -211,10 +213,10 @@ the steps below as appropriate if you choose that path. pkg install devel/py-buildbot-worker - The port creates a ``buildbot`` system user (nologin shell, home at - ``/var/db/buildbot``) and installs an ``rc.d`` script at - ``/usr/local/etc/rc.d/buildbot-worker`` with profile support. - The default base directory is ``/var/db/buildbot/workers``. + The package creates a ``buildbot`` system user, installs an + ``rc.d`` service with profile support, and creates + ``/var/db/buildbot/workers/`` as the base directory for worker + instances. Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with the credentials provided to you from your buildmaster-config issue):: From 7c721c22c828b58ffce06a0903946caa1e75045b Mon Sep 17 00:00:00 2001 From: Charalampos Stratakis Date: Tue, 10 Mar 2026 19:49:26 +0100 Subject: [PATCH 16/16] Add OpenBSD tab --- testing/new-buildbot-worker.rst | 51 +++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 76bc39d80..441083382 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -238,6 +238,42 @@ the steps below as appropriate if you choose that path. sysrc buildbot_worker_myworker_basedir=/var/db/buildbot/workers/WORKERNAME service buildbot-worker start + .. tab:: OpenBSD + + :: + + pkg_add buildbot-worker + + The package creates a ``_buildslave`` system user, installs an + ``rc.d`` service, and creates ``/var/buildslave/`` as the default + worker directory. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + su -m _buildslave -c "buildbot-worker create-worker \ + /var/buildslave \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + rcctl enable buildbot_worker + rcctl start buildbot_worker + + The ``rc.d`` script supports a single worker. To run multiple + workers, create each in a subdirectory and point the service flags + at the desired one (or create additional ``rc.d`` scripts):: + + su -m _buildslave -c "buildbot-worker create-worker \ + /var/buildslave/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + rcctl enable buildbot_worker + rcctl set buildbot_worker flags /var/buildslave/WORKERNAME + rcctl start buildbot_worker + .. tab:: macOS @@ -388,8 +424,19 @@ machine reboots: .. tab:: rc.d - If you installed via a package on FreeBSD (or another BSD), the - service was already enabled in the installation step above. + If you installed via a package on FreeBSD or OpenBSD, the service + was already enabled in the installation step above. To manage it + manually: + + On FreeBSD:: + + service buildbot-worker status + service buildbot-worker restart + + On OpenBSD:: + + rcctl check buildbot_worker + rcctl restart buildbot_worker If you installed via pip, you will need to write an ``rc.d`` script or use the cronjob approach described in the Linux tab.