Build note
Wake on Lan Proxy server for triggering remote wakes
The music server sleeps. When I want to listen while I am on the road, it needs to wake up. A plain Wake-on-LAN request is a UDP broadcast, so it only reaches the local network. The router is already on the way to the home server, so I made the router do the work.
The idea is a small Rust program on the Raspberry Pi 4 that listens for a request and sends the magic packet. The README sketch is the whole design:
Mobile --> Router --> Wol Proxy --> Server
The phone sends a signed request to the proxy. The proxy sends the magic packet to the sleeping server. The server wakes up.
The project is wol-proxy in my Rust playground. It is built on Actix Web, and
the whole thing is a few hundred lines, so it is a good first example of a Rust
program that talks to a network.
The magic packet is a broadcast, not a packet for the server
A magic packet is a small, fixed UDP packet. It starts with six bytes of 0xFF
and then repeats the target’s MAC address 16 times. That is 102 bytes in total.
The code is the whole definition:
fn create_magic_packet(mac_address: &str) -> Vec<u8> {
let mut magic_packet = vec![0; 102];
for i in 0..6 {
magic_packet[i] = 0xff;
}
// ...then the MAC address, 16 times, from offset 6
magic_packet
}
The six bytes are not a header. They are the marker. The packet goes to
255.255.255.255:9, so the network card has to be able to see it before the
machine is awake. The card checks the marker and the MAC address, and the MAC
address is the only thing that tells the machine the packet is for it.
The packet is not addressed to the server, because the server is asleep and its address is not in the network. The socket is set to broadcast so the kernel sends it, and the MAC address in the body is the target. The network card is the one part that stays powered while the machine sleeps, and the whole trick works because that card is the one listening.
The cookie says the request is really mine
The proxy sits on the public internet, so a request has to prove who sent it. The cookie is that proof. It is a value plus a signature, and the signature is a hash of the value computed with a secret key that only the proxy knows.
The check is HMAC-SHA256. The secret key is the key, the cookie value is the message, and the signature is the result:
let secret_key = std::env::var("COOKIE_SECRET_KEY")?;
let cookie_value = std::env::var("COOKIE_SECRET_VALUE")?;
let mut mac = Hmac::<Sha256>::new_from_slice(secret_key.trim().as_bytes())?;
mac.update(cookie_value.trim().as_bytes());
let computed_signature_hex = hex::encode(mac.finalize().into_bytes());
The secret lives in the environment, not in the code. scripts/cookie.sh
generates it, signs the cookie, and writes both to .env, which is not
committed. The client sends the cookie and the server recomputes the signature.
If the two match, the request is allowed.
The cookie can travel on the wire, because the secret is not in it. That is the point of a signature. You can hand it to anyone, and only the holder of the key can produce a valid one.
Two ways to ask if the server is already awake
Waking a machine that is already running does nothing harmful, but sending a
packet and hoping is not the same as knowing. So there is a second endpoint,
POST /status, that opens a TCP connection to the server’s port and reports
whether it is open:
fn is_port_open(addr: &SocketAddr, timeout: Duration) -> Result<bool> {
Ok(TcpStream::connect_timeout(addr, timeout).is_ok())
}
If the connection succeeds, something is listening and the server is up. If it times out, the machine is asleep or the port is blocked. The timeout matters, because without one a sleeping host can hold the request for two minutes before the operating system gives up.
The endpoint takes the same cookie, so a stranger cannot use it to probe which ports your home network has open.
The JSON field that silently did nothing
The request body has three fields: mac_address, bind_addr and
broadcast_addr. The last two are optional, and both fall back to sensible
defaults when they are missing.
The first example script sent something else:
PAYLOAD='{"mac_address": "F4:93:9F:F4:04:5B",
"bind_address": "0.0.0.0",
"broadcast_address": ""}'
Serde matches field names exactly, so bind_address and broadcast_address were
never read. The request still worked, because the defaults covered for them, and
that is what made the bug hard to see. Nothing failed. The only sign was that a
change to the address had no effect.
The fix was to make the names match on both sides. The lesson is that an optional field with a default hides a typo, and a default that is right every time you try it is the best disguise a wrong field name can have.
What the proxy taught me
Three things stayed with me after this project.
A protocol with no configuration is a protocol you can implement from memory. Wake-on-LAN is 102 bytes and a port number, so the packet code is five lines.
Defaults are dangerous in a request body. Every optional field needs a test where the field is present and set to a value that is wrong on purpose. That way the default cannot cover for it.
Actix Web makes the TLS part almost free. bind_openssl takes a builder, so the
same handler serves plain HTTP and HTTPS behind a flag. The certificate path is
still the awkward part, not the server code.
The proxy has been running on the Pi since the new year, and I press the button from my phone more often than I check the logs. That is the sign it is done.