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.