wake-on-lan-service/README.md

# 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](https://www.home-assistant.io/) 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.


## Example

### Running the service

```bash
$ sudo docker run --detach --name wake-on-lan-service --host network \
    --env PORT=18888
    witten/wake-on-lan-service
```

Or, with Docker Compose:

```yaml
services:
  wake-on-lan-service:
    image: 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:

```bash
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.

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

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

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


## 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.