wol-socket-proxy

A socket proxy with wake-on-lan and IPMI power control feature.

It can forward TCP(bidirectional) and UDP(send-only) traffic from local machine to remote machine, and:

• send a magic packet to wake it (wake-on-lan)
• invoke IPMI power on to wake it

before forwarding traffic if the remote machine does not respond to ICMP ping or some HTTP URL.

Requirements

Python 3.12+

The remote machine must accept and respond to ICMP ping requests if you use ping method.

Usage

You can install it from PyPI or use a prebuilt docker image.

Install from PyPI

Simply install it:

pip install wolsocketproxy

Then create a config file:

cp wolsocketproxy.conf.example /etc/wolsocketproxy.conf

Modify the config file as your requirements.

Finally, run it:

wolsocketproxy

Use prebuilt docker image

See docker/docker-compose.yml for more details.

Config

The wolsocketproxy.conf has the following structure:

{// NOTE: Comments are not allowed in actual config file// Define machines"machines": {"some-server": {"ip_address": "192.168.1.124",// the IP address of this machine, optional"mac_address": "11:22:33:44:55:66",// The MAC address of this machine, optional"wake_up_method": "ipmi",// How to wake up this machine// "ipmi" - You must specify "ipmi_config_name"// "wol" - You must specify "mac_address""ipmi_config_name": "some-server-ipmi",// IPMI config of this machine, must match what defined in "ipmi_configs""online_check_method": "http",// How to check this machine is online// "http" - You must specify "online_check_http_url"// "ping" - You must specify "ip_address""online_check_http_url": "http://192.168.1.124/health",// The URL used to check if machine is online, optional"online_check_timeout": 300,// Timeout when checking machine is online, seconds, optional, default is 60"online_check_http_expected_code": 200,// Expected HTTP status code when using "http" method, optional, default is 200"ipmi_force_reset_if_power_up_failed": true,// Use IPMI power reset if this machine is not online after timeout, optional, default is false"ipmi_max_reset_try_count": 3,// Max IPMI power reset retry count before giving-up, optional, default is 3"keep_alive_mode": true,// Indicates whether this machine has a keep-alive daemon, optional, default is false// If you enable this, wolsocketproxy will send a request when there is any traffic"keep_alive_mode_base_url": "http://192.168.1.124:8080",// Keep-alive daemon provided URL, optional"scheduled_power_up_times": [// Scheduled power-up times, optional{"cron": "0 7 * * 1-5",// Cron expression for auto power-up"keep_alive_time": 7200// Send keep-alive requests for N seconds after power-up}]},// ... more machines ...},// Define forwarding routes"routes": [{"local_address": "0.0.0.0",// The local address to listen"local_port": 12345,// The local port to listen"target_machine_name": "some-server",// The target machine name, must match what defined in "machines""target_address": "192.168.1.124",// The target address forwarding to"target_port": 12345,// The target port forwarding to"protocol": "tcp"// The protocol to use, can choose "tcp" or "udp"},// ... more routes ...],// Define IPMI configs, optional"ipmi_configs": [{"name": "some-server-ipmi",// IPMI config name"redfish_url": "https://192.168.1.123/",// IPMI Redfish API base URL (should not contain /redfish/v1)"username": "admin",// IPMI Redfish API login username"password": "123456"// IPMI Redfish API login password},// ... more IPMI configs ...]}

Additional modes

Keep-alive daemon mode

This mode is used for running on target machine with auto-suspend (e.g. running circadian or similar), to keep the target machine from auto suspending when running tasks.

Use the following command on the target machine to enter this mode:

wolsocketproxy -k

The config file wolsocketproxy.conf should look like the following:

// Keep-alive daemon mode{"listen_address": "0.0.0.0",// The address to listen for HTTP server, default is 127.0.0.1"listen_port": 18080,// The port to listen for HTTP server, default is 18080"watchdog_feed_interval": 60,// Watchdog feed interval, seconds, default is 600"keep_alive_method": "special_process",// How to keep target machine alive, default is "special_process"// "special_process" - Fork a child process with specified name"special_process_name": "wsp-keepalive",// The display name of the forked child process, default is "wsp-keepalive"}

You need to periodically send an HTTP GET request to /watchdog/feed at the listen_port in watchdog_feed_interval time, or the special process will be killed. You can combine this mode with circadian's process_block config to keep it from auto-suspending.

If you enable keep_alive_mode in proxy mode's config, the proxy will send requests to /watchdog/feed of this machine whenever there is any traffic towards this machine through it.

Scheduled power-up

You can configure scheduled_power_up_times in each machine entry to automatically power up the machine at specified times using a cron expression. After the machine comes online, the proxy sends keep-alive requests to the machine's keep-alive daemon (for the duration specified by keep_alive_time) to prevent it from auto-suspending during the expected usage window.

Each entry in scheduled_power_up_times contains:

• cron: A standard 5-field cron expression (e.g. "0 7 * * 1-5" for weekdays at 7:00)
• keep_alive_time: Duration in seconds to send keep-alive requests after power-up (e.g. 7200 for 2 hours)

If multiple entries overlap in time, the keep-alive period is automatically extended to cover the longest window, and no duplicate keep-alive requests are sent.