https://github.com/darksworm/go-wol-proxy
A Wake-on-LAN reverse-proxy service that automatically wakes up servers when requests are made to them.
https://github.com/darksworm/go-wol-proxy
Last synced: 5 months ago
JSON representation
A Wake-on-LAN reverse-proxy service that automatically wakes up servers when requests are made to them.
- Host: GitHub
- URL: https://github.com/darksworm/go-wol-proxy
- Owner: darksworm
- License: gpl-3.0
- Created: 2025-06-06T12:31:47.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-07T13:32:27.000Z (6 months ago)
- Last Synced: 2025-09-21T06:46:49.570Z (6 months ago)
- Language: Go
- Homepage:
- Size: 72.3 KB
- Stars: 117
- Watchers: 0
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-repositories - darksworm/go-wol-proxy - A Wake-on-LAN reverse-proxy service that automatically wakes up servers when requests are made to them. (Go)
README
# Go WOL Proxy
A Wake-on-LAN proxy service written in Go that automatically wakes up servers when requests are made to them.
## Features
- Proxies HTTP requests to configured target servers
- Automatically sends Wake-on-LAN packets to wake up offline servers
- Monitors server health with configurable intervals
- Caches health status to minimize latency for frequent requests
- Packaged as a Docker container for easy deployment
- :star: new :star: Supports graceful shutdown of servers after a period of inactivity
## Configuration
The service is configured using a TOML file. Here's an example configuration:
```toml
port = ":8080" # Port to listen on
timeout = "1m" # How long to wait for server to wake up
poll_interval = "5s" # How often to check health during wake-up
health_check_interval = "30s" # Background health check frequency
health_cache_duration = "10s" # How long to trust cached health status
# Optional SSL configuration Do not add these values unless you plan to use TLS/HTTPS
ssl_certificate = "/path/to/cert.pem" # Path to your SSL certificate
ssl_certificate_key = "/path/to/key.pem" # Path to your SSL private key
[[targets]]
name = "service"
hostname = "service.host.com" # The "external" hostname - what this server receives as a Host header
destination = "http://service.local" # The actual url to the server
health_endpoint = "http://service.local/ping" # url to check health
mac_address = "7c:8b:ad:da:be:51" # MAC address for WOL
broadcast_ip = "10.0.0.255" # Broadcast IP for WOL
wol_port = 9 # Port for WOL packets
# Optional: Graceful shutdown configuration (SSH or HTTP)
inactivity_threshold = "1h" # Shut down after 1 hour of inactivity
# Option A: SSH-based shutdown (use either Option A or Option B, not both)
ssh_host = "service.local:22" # SSH host:port for shutdown
ssh_user = "wol-proxy" # SSH username for shutdown
ssh_key_path = "/app/private_key" # Path to SSH private key
shutdown_command = "sudo systemctl suspend" # Command to execute for shutdown
# ^ take care - wake from suspend / shutdown can be flaky on some systems.
# if your machine doesnt wake from your chosen "sleep" mode, try another.
# Option B: HTTP-based shutdown (use either Option A or Option B, not both)
#shutdown_http_url = "http://service.local/api/shutdown" # URL to trigger shutdown (final response validated)
#shutdown_http_method = "POST" # Optional; defaults to POST
#shutdown_http_ok_status = 0 # Optional; 0=accept any 2xx (default). Set e.g. 202 to require specific code
[[targets]]
name = "service2"
hostname = "service2.host.com"
destination = "http://service2.local"
health_endpoint = "http://service2.local/ping"
mac_address = "c9:69:45:d2:1e:12"
broadcast_ip = "10.0.0.255"
wol_port = 9
```
## Docker Usage
### Pull the Docker Image
```bash
docker pull ghcr.io/darksworm/go-wol-proxy:latest
```
### Run the Docker Container
```bash
# Note: network mode "host" is required for Wake-on-LAN packets to be sent correctly
docker run --network host -v /path/to/config.toml:/app/config.toml ghcr.io/darksworm/go-wol-proxy:latest
```
### Build the Docker Image Locally
```bash
docker build -t go-wol-proxy .
```
### Run the Locally Built Image
```bash
# Note: network mode "host" is required for Wake-on-LAN packets to be sent correctly
docker run --network host -v /path/to/config.toml:/app/config.toml go-wol-proxy
```
### Docker Compose Usage
Create a `docker-compose.yml` file with the following content:
```yaml
version: '3'
services:
go-wol-proxy:
image: ghcr.io/darksworm/go-wol-proxy:latest
# Note: network mode "host" is required for Wake-on-LAN packets to be sent correctly
network_mode: host
restart: unless-stopped
volumes:
- ./config.toml:/app/config.toml
# Optional: SSH private key for graceful shutdown
- ./private_key:/app/private_key
```
Run the container with Docker Compose:
```bash
docker-compose up -d
```
## Graceful Shutdown Options
- Trigger a shutdown after a period of inactivity using SSH or HTTP.
- Exactly one mechanism must be configured per target: SSH or HTTP, not both.
### SSH-based Shutdown
- Use `ssh_host`, `ssh_user`, `ssh_key_path`, and `shutdown_command`.
- The proxy executes the command over SSH when the target is inactive.
### HTTP-based Shutdown
- Use `shutdown_http_url` to enable HTTP shutdown.
- `shutdown_http_method` defaults to `POST` if not specified.
- By default, any 2xx status code counts as success; set `shutdown_http_ok_status` to require a specific code.
- The HTTP client follows redirects and validates the final response code.
- The shutdown HTTP request uses a 10s timeout.
### Validation Rules
- You cannot set both `shutdown_http_url` and `shutdown_command` for the same target.
- If `shutdown_http_method` and/or `shutdown_http_ok_status` are set, `shutdown_http_url` must also be set.
### Similar projects:
1. traefik-wol: [traefiklabs](https://plugins.traefik.io/plugins/642498d26d4f66a5a8a59d25/wake-on-lan), [github](https://github.com/MarkusJx/traefik-wol)
2. caddy-wol: [github](https://github.com/dulli/caddy-wol)
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and commit conventions.