From 20ae8f771fa284a69390698ada5ec96ddd6abe6b Mon Sep 17 00:00:00 2001 From: grayhook Date: Sun, 24 Aug 2025 15:37:54 +0700 Subject: [PATCH] add help --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..39ced31 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +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 ` 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.