Service Butler - Quick Start Guide

This script is a "butler" for your services (especially game servers). It saves RAM and CPU by running them only when someone actually wants to connect.

Install

make install

It will place the binary and configs on it's place.

The next step is enable and start service:

systemctl enable port-butler
systemctl start port-butler

How it works

The butler follows a simple loop for each service you configure:

1. Sleeping & Listening: It sits on your service's port, waiting. The real service is offline.
2. Wake Up Call: As soon as someone tries to connect, the butler catches the attempt, tells them to hold on (by closing the connection), and immediately starts waking up the real service.
3. Waking Up: It runs your start_command. After a short startup_delay_sec, it begins watching.
4. Watching: It periodically runs your check_command to see if anyone is using the service. As long as people are active, it does nothing.
5. Going to Sleep: Once the service has been empty for idle_limit_sec, the butler runs the stop_command and goes back to step 1.

If the script is restarted, it uses is_running_command to see if the service is already up, so it can jump straight to the "Watching" step without restarting it.

Configuration

See config.ini for example.

It placed to /etc/butler.ini during installation.

Each service gets its own section, like [minecraft]. Here are the options:

• start_command The shell command to start your service. e.g., systemctl start minecraft.

• stop_command The shell command to stop your service. e.g., systemctl stop minecraft.

• is_running_command A command that checks if the service is already active. This is crucial for when the butler script restarts. It should exit with 0 if running, and non-zero otherwise. The systemctl is-active --quiet <service> command is perfect for this.

• check_command The most important command. It checks if the service is being used. The butler only cares about the exit code: 0 means "active", anything else means "idle".

• listen_port The public port of your service (e.g., 25565 for Minecraft). The butler will listen here when the service is down.

• listen_host The IP to listen on. 0.0.0.0 is what you want 99% of the time, as it means "listen for connections from anywhere."

• check_interval_sec How often (in seconds) to run the check_command while the service is up.

• idle_limit_sec How long (in seconds) the service can be idle before the butler shuts it down.

• startup_delay_sec A short pause (in seconds) after starting the service before the first activity check. This gives your server time to fully load.