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. Don't forget to open this port in your firewall.


## Example

### Running the service

```bash
$ 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:

```yaml
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:

```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, 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:

```yaml
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:

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