This update is about cleaning up the way Mediabot v3 is started, stopped, restarted and supervised.

Until now, the repository still had a few old root-level helper scripts such as start, stop, daemon, and a cron-style watchdog script. They were useful during development and they followed the old Eggdrop-style “botchk” spirit, but they are no longer the best default way to run a modern long-lived bot process.

Mediabot v3 now has a cleaner and more flexible systemd-based workflow.

Why move to systemd?

The old helper scripts worked, but they had a few limits:

• they assumed a local hardcoded configuration file;
• they were not ideal for multi-instance setups;
• cron watchdogs are coarse and can restart things at awkward times;
• PID-file based checks can become fragile;
• logs are harder to follow consistently;
• restart-loop protection has to be reinvented manually.

systemd already solves most of this properly.

With systemd, Mediabot can run in foreground mode while systemd supervises the process. That means no --daemon is needed for the managed service. The bot stays visible to systemd, logs go to journalctl, and restarts can be handled cleanly with Restart=on-failure.

Multi-instance friendly

The new layout supports both the simple case and more advanced setups.

A typical single-instance installation can still live here:

/home/mediabot/mediabot_v3

with:

/home/mediabot/mediabot_v3/mediabot.conf

But multi-instance setups are also supported. For example:

/home/mediabot/mediabot_v3  -> dev instance,      mediabot.conf
/home/mediabot/mediabot3    -> Undernet instance, mbundernet.conf

Each instance has its own systemd name:

mediabot@dev.service
mediabot@undernet.service

And each one loads a matching environment file:

/etc/default/mediabot-dev
/etc/default/mediabot-undernet

This keeps the configuration flexible without forcing all instances into the same directory layout.

The systemd template

The new recommended service is a template unit:

mediabot@.service

Each instance loads:

/etc/default/mediabot-<instance>

For example:

systemctl start mediabot@dev

loads:

/etc/default/mediabot-dev

A typical environment file looks like this:

BOT_DIR=/home/mediabot/mediabot_v3
BOT_BIN=/home/mediabot/mediabot_v3/mediabot.pl
BOT_CONF=/home/mediabot/mediabot_v3/mediabot.conf

The important point is that the configuration file stays where the instance expects it. There is no forced conf/ directory layout.

Foreground first

For a fresh install or a new instance, the first start should still be done manually in foreground.

Use your actual configuration file:

cd /home/mediabot/mediabot_v3 || exit 1

./mediabot.pl --conf=your_config_file.conf

For a default single-instance setup:

cd /home/mediabot/mediabot_v3 || exit 1

./mediabot.pl --conf=mediabot.conf

For another instance:

cd /home/mediabot/mediabot3 || exit 1

./mediabot.pl --conf=mbundernet.conf

The old ./start helper has been moved to tools/legacy/ and should no longer be used as the main documented startup method.

Daily usage

Once the systemd service is installed, common commands become straightforward:

systemctl start mediabot@dev
systemctl stop mediabot@dev
systemctl restart mediabot@dev
systemctl status mediabot@dev --no-pager
journalctl -u mediabot@dev -f

For another instance:

systemctl restart mediabot@undernet
journalctl -u mediabot@undernet -f

Development helper: mbctl

For day-to-day development, a convenience wrapper is provided:

tools/dev/mbctl

Examples:

tools/dev/mbctl dev status
tools/dev/mbctl dev restart
tools/dev/mbctl dev logs
tools/dev/mbctl undernet status
tools/dev/mbctl undernet pause 10m

This helper does not replace systemd. It simply wraps systemctl, journalctl, and systemd-run with shorter commands.

Temporary pause

Sometimes you do not want the bot to restart immediately, especially during maintenance or debugging.

With systemd, one clean option is:

systemctl stop mediabot@dev

systemd-run \
  --unit=mediabot-resume-dev \
  --on-active=10m \
  /bin/systemctl start mediabot@dev

Or with the helper:

tools/dev/mbctl dev pause 10m

That gives a practical “pause for 10 minutes” workflow without relying on a cron watchdog.

Legacy scripts moved away from the root

The old root-level scripts have been moved under:

tools/legacy/

Possible examples include:

start.legacy
stop.legacy
daemon.legacy
check_alive_cron_script.sh.legacy

They are kept temporarily as references during the transition, but they are not the recommended production supervisor anymore.

The old cron watchdog approach is now considered legacy. It may still be useful as a fallback in some environments, but systemd should be the default recommendation.

ZNC and bouncer setups

systemd does not care whether Mediabot connects directly to an IRC server or through a bouncer such as ZNC.

That remains entirely a configuration-file concern.

Set the IRC server, port, SSL options, credentials and bouncer details in the Mediabot configuration file. The systemd unit only starts the correct instance with the correct config file.

Documentation updated

The wiki documentation now includes a dedicated systemd page and updates to the installation, configuration, troubleshooting and upgrade notes.

The goal is simple:

• keep installation clear for a single-instance user;
• support real multi-instance deployments;
• avoid documenting obsolete root-level helper scripts as the primary workflow;
• make development restarts practical;
• keep production supervision robust.

Result

Mediabot v3 now has a cleaner operational model:

systemd for supervision
journalctl for logs
mbctl for convenience
legacy scripts moved out of the project root
multi-instance support through /etc/default/mediabot-<instance>

This is not a flashy feature, but it makes the project easier to run, easier to debug, and safer to operate over time.

Protego Service.