Send wake-on-LAN packets on behalf of other containers.
Go to file
2023-04-29 15:20:26 -07:00
Dockerfile Upgrade Alpine. 2023-02-24 16:18:00 -08:00
LICENSE Add license. 2023-04-29 15:20:26 -07:00
push.sh Switch to self-hosted container registry. 2022-08-01 23:20:45 -07:00
README.md Fix image URL. 2023-02-24 15:48:16 -08:00
run.sh Documentation updates. 2022-06-12 18:26:05 -07:00

wake-on-lan-service

Remotely wake up your servers ... as-a-service!

The problem: Docker prevents bridge-networked containers from sending wake-on-LAN packets outside of the Docker network. That means standard Docker containers can't wake up remote machines. As a work-around, you can put them on the Docker host network, but that has security and interoperability implications—you may not want to expose your containers that way.

The solution: wake-on-lan-service runs on Docker's host network and sends wake-on-LAN packets on behalf of other containers running on a standard bridge network. This allows them to wake up remote machines—without themselves having to be on the host network.

You might find this service useful for use cases like running Home Assistant in a Docker container without putting it on the host network—while still allowing it to wake up remote machines.

Source at https://projects.torsion.org/witten/wake-on-lan-service

How it works

This service listens on a port for TCP requests containing a MAC address to send a wake-on-LAN packet to. It expects plain TCP requests, not HTTP.

Environment variables

  • PORT: The TCP port to listen on for wake-on-LAN requests, defaults to 18888. Don't forget to open this port in your firewall.

Example

Running the service

$ sudo docker run --detach --name wake-on-lan-service --host network \
    --env PORT=18888
    projects.torsion.org/witten/wake-on-lan-service

Or, with Docker Compose:

services:
  wake-on-lan-service:
    image: projects.torsion.org/witten/wake-on-lan-service
    restart: always
    network_mode: host
    environment:
      PORT: 18888

Using the service

From within another container running on a Docker bridge network (so, no need to run on the host network), execute:

echo 00:00:0a:bb:28:fc | nc -N host.docker.internal 18888

This example uses the OpenBSD netcat variant to send a TCP packet containing the requested MAC address to wake. The packet is sent to port 18888 on the host, where this container should be listening.

For this to work, you may need to configure your client container (the one running the echo command) to support the special host.docker.internal host. E.g., docker run --add-host host.docker.internal:host-gateway .... Or, with Docker Compose:

extra_hosts:
  - "host.docker.internal:host-gateway"

Alternatively, on Linux, you can try using the IP 172.17.0.1.

Home Assistant

If you happen to be using Home Assistant in Docker, here's how you might request wake-on-LAN of a remote server via wake-on-lan-service. This example is of an automation action in your Home Assistant configuration:

automation:
  - alias: my automation
    trigger: ...
    action:
      - service: shell_command.wake_my_server

shell_command:
  wake_my_server: "echo 00:00:0a:bb:28:fc | nc host.docker.internal 18888"

(Home Assistant's Docker image includes netcat from busybox instead of OpenBSD netcat, so omit the -N flag.)

Security

Note that no authorization is performed on the service request, so be aware that anyone with network access to this service can wake arbitrary hosts by MAC address.