The Bol Processor interface runs on a local web server: Apache, installed with MAMP on MacOS or XAMPP on Linux. If this server crashes or gets stuck, for instance because a process running for a page has entered a loop, no page answers any more, and the server must be restarted by hand. The watchdog is a small program, started automatically by the interface, that checks the server every minute and restarts it when needed.
This page describes how it works, what Linux users need to do once, how to check that it works, and its limits. It is written for users who want to understand what happens on their machine, and for programmers who maintain the code.
The code lives in three places:
php/watchdog.sh, the watchdog itself, a shell script (no compilation needed);php/_basic_tasks.php, which containswatchdog_start(), called when any page is loaded, andwatchdog_notice(), the warning displayed on Linux when the watchdog lacks a permission.php/watchdog_ping.phpis the tiny page the watchdog loads to check the server;watchdog_allow.sh, one of the Linux installation and update scripts, which gives the watchdog the permission to restart XAMPP's Apache.
Where it runs
The watchdog is started only when the page is served by Apache from MAMP on MacOS (its PHP is in /Applications/MAMP/), or by Apache from XAMPP on Linux (the page is in /opt/lampp/).
It is never started:
- in the standalone application BolProcessor.app (based on PHP Desktop), which has its own web server and its own PHP, even if MAMP is installed on the same machine. The application is a single program: if it gets stuck, it is simply quit and opened again;
- on Windows, which is not covered at the moment;
- when PHP is run from the command line.
XAMPP on MacOS is not supported by the Bol Processor, because its installer is not notarized.
How it starts
Every page of the interface includes _basic_tasks.php, which calls watchdog_start(). Since pages are loaded very often (some of them are polled repeatedly during a performance), this function must cost almost nothing when the watchdog is already running. It therefore starts no process to find out: it only reads the date of the file temp_bolprocessor/watchdog.txt, which the watchdog touches at every check. If this date is less than 150 seconds old, the watchdog is running and nothing else is done.
Otherwise, watchdog_start() touches the file itself (so that pages loaded in the meantime don't start another one), then starts watchdog.sh in the background with three arguments: the kind of server (mamp or xampp), the address of watchdog_ping.php (built from the port of the current page and the path of the php folder in the server), and the folder temp_bolprocessor where the watchdog keeps its files.
The watchdog must survive the server it watches. A process started by a page is normally a descendant of the server, and it may receive the signals sent to the server when it stops. The script is therefore started in a new session, detached from the server: with setsid on Linux, and on MacOS (which has no setsid command) with a one-line Perl call to the same system function. Its input and outputs go to /dev/null, and it closes the other file descriptors it may have inherited from the server.
Only one watchdog may run for a given installation. At start, the script creates the folder temp_bolprocessor/watchdog.lock and writes its process number in it. Creating a folder is an atomic operation: if two watchdogs start at the same time, only one succeeds. If the folder already exists, the script checks whether the process it names is still a running watchdog. If so, it quits; if not (the previous watchdog was killed, or the machine restarted), it takes over the lock. When the watchdog quits, it deletes the lock and the file watchdog.txt, so that the next page loaded starts a new one at once.
The check
Every 60 seconds, the watchdog loads watchdog_ping.php with curl, waiting at most 30 seconds for the answer. This page only answers "ok": it does not include _basic_tasks.php, so that it answers quickly. Loading a PHP page rather than just connecting to the port tests both Apache and PHP: a server that accepts connections but can no longer run PHP is not working either.
The watchdog also reads the pid file of Apache, in which the server writes the number of its main process: /Applications/MAMP/Library/logs/httpd.pid for MAMP, /opt/lampp/logs/httpd.pid for XAMPP. When Apache is stopped normally, it deletes this file. When it crashes, the file stays, but the process it names no longer exists. This tells apart a server stopped on purpose from a server that crashed.
At each check, the watchdog decides in this order:
- The pid file exists, but its process is gone: Apache crashed. It is restarted at once. This test comes first because the worker processes of a killed main process may go on answering pages for a while. They are no longer replaced, though, so the server would eventually fail.
- The page answers "ok": everything is fine.
- No answer, and no pid file: Apache was stopped on purpose, for instance with the Stop button of MAMP. The watchdog quits. The next page loaded after the server restarts will start a new watchdog.
- No answer, and (MAMP only) Apache does not listen on the port of the address: the address is not served by this Apache, for instance because the port of MAMP was changed. The watchdog quits rather than restart a server that is not the one it watches. The next page starts a watchdog with the new address.
- No answer from a running Apache: it may be stuck. The watchdog counts the failures, and restarts the server after 3 failures in a row. With 30 seconds of waiting and 60 seconds between checks, a stuck server is restarted after about 4 minutes. A single failure is not enough, because a very busy machine may delay an answer.
The restart
MacOS (MAMP)
With MAMP, Apache runs under the user's own account, so the watchdog (which runs under the same account) can stop and start it without any special permission:
- It runs
/Applications/MAMP/Library/bin/apachectl stop, which sends the stop signal to the main process, and waits up to 20 seconds for this process to end. - Processes of Apache and PHP still running after that (those of a stuck server, or the workers left by a crashed main process) are killed:
httpd, the FastCGI process manager, andphp-cgi, identified by their path in/Applications/MAMP/. The pid file is deleted. - It runs
apachectl start, then waits 5 seconds and loads the test page again.
Apache is started with the environment of the user's session: HOME, USER, TMPDIR and a standard PATH. This matters because the environment that PHP passes to the programs it starts is almost empty. A server started from that environment would in turn run the console, Csound or SuperCollider without a home folder or a temporary folder.
Linux (XAMPP)
With XAMPP, the main process of Apache belongs to root (it needs to listen to port 80), while the pages, and thus the watchdog, run under the user daemon. The watchdog cannot stop or start the server by itself. It uses sudo to run two commands of XAMPP, and only these two:
/opt/lampp/lampp stopapache /opt/lampp/lampp startapache
The permission is given by a rule that watchdog_allow.sh creates (see below). Each command has a time limit, 30 seconds to stop and 60 seconds to start, after which it is interrupted. Without it, a frozen server could freeze the watchdog with it. Between the two commands, the watchdog kills the worker processes left by a main process that crashed: they belong to daemon, like the watchdog, and would otherwise keep port 80 busy, so that the new server could not start.
After the restart
If the test page answers after the restart, the watchdog goes on checking. If it doesn't, it tries again at the following checks, and gives up after 3 restarts without answer: something is wrong that a restart cannot fix, and restarting forever would only fill the log.
A restart interrupts whatever the server was doing, including a production or a performance in progress. This is why the watchdog waits for 3 failed checks before restarting a server that is still running.
When it quits
Apart from a server stopped on purpose and an address served by another server (see above), the watchdog quits:
- when the content of
watchdog.shchanges, which happens when the interface is updated. The next page starts the new version. The script compares a checksum of its content taken at start, not the date of the file: a file unpacked from a zip made in another time zone may have a date in the future, which made every new watchdog believe that the file had just changed; - when its folder
temp_bolprocessorno longer exists (the installation was moved or deleted); - after 3 restarts without answer.
Linux: the permission to restart XAMPP
The script watchdog_allow.sh, run with sudo, creates the file /etc/sudoers.d/bolprocessor-watchdog:
Defaults:daemon !requiretty daemon ALL=(root) NOPASSWD: /opt/lampp/lampp stopapache, /opt/lampp/lampp startapache
The rule is checked with visudo before it is installed. It allows nothing else: /opt/lampp/lampp belongs to root, and only these two arguments are accepted.
Users don't need to run this script themselves. It is one of the Linux scripts, which are copied to the /home folder during the installation, and it is run at the end of get_ready_bp3.sh and install_bp3.sh (installation), of the update scripts update_console.sh, update_interface.sh and update_data.sh, and of change_permissions.sh. These scripts are distributed separately from the interface, so updating the interface does not update them: before updating, users should get their latest version. The ReadMe of the scripts gives these commands, to be pasted into the terminal:
cd ~/Downloads &&
rm -rf linux-scripts linux-scripts*.zip &&
wget https://bolprocessor.org/misc/linux-scripts.zip &&
unzip -o linux-scripts.zip &&
chmod -R 775 linux-scripts &&
sudo cp -a linux-scripts/. /home/ &&
sudo chmod +x /home/*.sh
The scripts are downloaded with wget rather than the web browser, which may give an older version kept in its cache. Each line ends with &&, so the commands work whether they are pasted as several lines or joined into one, and the whole sequence stops at the first error.
At every check, the watchdog asks sudo whether the rule exists (sudo -n -l, which runs nothing). If it doesn't, the watchdog writes it once in its log, skips the restarts it could not do, and creates the file temp_bolprocessor/watchdog_needs_sudo. While this file exists, the grammar and data pages and the folder lists display a warning telling the user to download the latest Linux scripts and type sudo /home/watchdog_allow.sh. The watchdog deletes the file as soon as the rule exists, so the warning disappears within a minute.
The log
The watchdog writes its events, with their date, to temp_bolprocessor/watchdog_log.txt in the bolprocessor folder. When the file exceeds 100 kB, only its last 300 lines are kept. Normal checks are not written, only these events:
Started (pid ...), checking ...: a watchdog started, with the address it checks.Apache crashed: restarting Apache: the main process of the server is gone.No answer from Apache (1/3): a failed check of a running server. After(3/3):Apache is stuck: restarting Apache.Killing the remaining processes of Apache and PHP(MAMP) orKilling the remaining processes of Apache(XAMPP): processes left after the stop.Apache restarted, orApache is not answering after restart, and after 3 of the latterGiving up after 3 restarts.'lampp stopapache' did not end within 30 seconds(Linux): the time limit was reached.Not allowed to restart Apache: run 'sudo /home/watchdog_allow.sh' (Linux scripts)(Linux): thesudorule is missing.Apache was stopped: quitting,Apache is not listening on port ...: quitting,watchdog.sh was changed: quitting: the watchdog quit, for the reasons given above.
The messages printed by MAMP's or XAMPP's commands during a restart, such as XAMPP: Starting Apache...ok., appear between these lines.
Checking that it works
Load any page of the Bol Processor, then look at the end of the log. On MacOS:
tail -5 /Applications/MAMP/htdocs/bolprocessor/temp_bolprocessor/watchdog_log.txt
On Linux:
tail -5 /opt/lampp/htdocs/bolprocessor/temp_bolprocessor/watchdog_log.txt
The last line should be Started ..., unless the watchdog was already running. To simulate a crash, kill the main process of Apache. On MacOS:
kill -9 $(cat /Applications/MAMP/Library/logs/httpd.pid)
On Linux (the whole command must run as root):
sudo sh -c 'kill -9 $(cat /opt/lampp/logs/httpd.pid)'
Within about a minute, without loading any page, the log should show Apache crashed: restarting Apache, Killing the remaining processes... and Apache restarted, and pages load again.
To check that a server stopped on purpose is left alone, stop Apache with MAMP (or sudo /opt/lampp/lampp stopapache on Linux): the log should end with Apache was stopped: quitting, and Apache stays stopped.
Limits
- The watchdog is started by a page. After the machine restarts, or after the server was stopped on purpose, nothing watches the server until a page of the Bol Processor is loaded.
- On Linux, the main process of Apache belongs to
root, so the watchdog cannot kill it if it is frozen. It then relies onlampp stopapache; if this fails within its time limit, the watchdog logs the failure and gives up after 3 restarts. A crash, and frozen worker processes, are handled. - A restart interrupts productions and performances in progress. A server that doesn't answer for 3 minutes or more is considered stuck, even if it is only very busy.
- Windows is not covered, and neither is MySQL, which the Bol Processor doesn't use.
Note: This page was entirely composed by Claude Opus 5.5 on 22 November 2026.
