Wake-on-LAN API

Send a Wake-on-LAN (WOL) magic packet to power on your homelab server.

Endpoint

POST /api/wol

Authentication

Requires bearer token in Authorization header.

Authorization: Bearer <token>

Request

No request body required. The target MAC address is configured via environment variables.

Response

Success (200 OK)

{
  "success": true,
  "message": "Wake-on-LAN packet sent"
}

Unauthorized (401)

{
  "error": "Invalid or expired token"
}

Server Error (500)

{
  "error": "Failed to send WOL packet: ..."
}

How It Works

1. articwake constructs a WOL magic packet:
   • 6 bytes of 0xFF
   • 16 repetitions of the target MAC address
2. Sends the packet via UDP port 9 to the broadcast address
3. Your server’s NIC receives the packet and powers on the system

Configuration

The target MAC and broadcast address are configured via environment variables:

ARTICWAKE_HOMELAB_MAC="aa:bb:cc:dd:ee:ff"
ARTICWAKE_HOMELAB_BROADCAST="255.255.255.255"

Example

curl

curl -X POST http://localhost/api/wol \
  -H "Authorization: Bearer $TOKEN"

JavaScript (fetch)

const response = await fetch('http://localhost/api/wol', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
});

const result = await response.json();
console.log(result.message);

After Sending

After sending a WOL packet:

1. Wait ~10-30 seconds for the server to power on
2. Poll /api/status to check when the server becomes reachable
3. Once initrd_ssh_open is true, you can send the unlock command

# Send WOL
curl -X POST http://localhost/api/wol -H "Authorization: Bearer $TOKEN"

# Wait and check status
sleep 15
curl http://localhost/api/status -H "Authorization: Bearer $TOKEN"

Troubleshooting

WOL packet sent but server doesn’t wake

1. BIOS settings: Ensure Wake-on-LAN is enabled in BIOS/UEFI
2. Network configuration: Some NICs need WOL enabled in the OS before shutdown
3. Broadcast address: Try setting ARTICWAKE_HOMELAB_BROADCAST to your subnet’s broadcast (e.g., 192.168.1.255)
4. Same subnet: WOL typically requires the sender to be on the same subnet as the target
5. Power state: Server must be in S5 (soft-off) state, not hard powered off

Testing WOL manually

# Install wakeonlan tool
apt install wakeonlan

# Send test packet
wakeonlan aa:bb:cc:dd:ee:ff