Lightweight, minimal dependencies and non-intrusive machine awakener service using IP spoofing for the good cause.

1. Introduction

   • Overview
   • Advantages
   • Limitations

2. Precautions

   • Client machine side
   • Wakupator host side
   • Recommendations

3. Get Started

   • Compile Project
   • Pre-compiled Binaries

4. How to Use

   • Launch Wakupator
   • Register a Machine

5. Example

   • Context
   • Launch Wakupator
   • Prepare the JSON
   • Automate Machine Registration
   • Register the Machine
   • Final Test

6. Contributing

7. License

8. Third-party Libraries

This service allows other machines on the same LAN to be woken up when specific traffic is detected. Before shutdown, machines can request to spoof their IP address(es) and associate zero or more ports to each of them. When network traffic is detected, the registered machine is woken up via a Wake-on-LAN (IEEE 802.3) magic packet.

The main goal of this project is to reduce energy wasting by sacrificing availability.

This is ideal for home servers, small infrastructure which are hosting services that are not in use 24 hours a day.

Only works on Linux.

• No firewall configuration required
  Wakupator reads packets before they reach the host firewall or local services.

• Works with any IP-based service
  Wakupator does not depend on application-layer protocols and can wake machines based on low-level network traffic.

• Designed for self-hosted environments
  Lightweight, minimal dependencies, non-intrusive and easy to integrate into an existing network.

• Sensitive to unsolicited traffic and bot scans
  Services exposed to the internet, especially HTTP/HTTPS or IPv4, may receive frequent scans.
  These packets can trigger Wakupator and cause machines to wake up more often than expected.

Some strategies to reduce unwanted wake-ups:

• Filter or block bot traffic higher in your network (router or hardware firewall)

Wakupator relies on raw network traffic and IP spoofing. To ensure correct operation, please follow these precautions.

• Your router or L3 hardware must not have static IP/MAC bindings on IP addresses that could be spoofed by Wakupator.
• When a machine registers with Wakupator, it must do so shortly before shutdown.
• On the user side, when accessing a stopped service, the first connection attempt may time out or reset. It depends on the machine's startup time and the service's behavior.

The monitored machine must support Wake-On-LAN (IEEE 802.3). Enable this feature in both BIOS/UEFI and the operating system.

sysctl -w net.ipv6.conf.{interface/all}.accept_dad=0

When the monitored machine boots manually, it initializes its network interface and sends ICMPv6 Neighbor Solicitation probes to check if its IP is already in use. As Wakupator is running simultaneously, the Linux kernel on the host might respond to these probes before Wakupator finishes removing spoofed IPs, causing the machine to mark its address as a duplicate. Disabling DAD prevents this race condition.

Wakupator requires the following capabilities to run:

• Capability cap_net_raw to create raw sockets.
• Capability cap_net_admin to manage IP on the machine.

You can add these capabilities with the command:

sudo setcap cap_net_raw,cap_net_admin+eip /path/to/wakupator

Alternatively, if you run Wakupator as a service, you can assign capabilities as shown in example/host/wakupator.service

These recommendations improve reliability and reduce side effects but are not strictly required:

1. Keep Wakupator internal
   Only machines inside the host’s LAN should be allowed to register. Do not expose Wakupator to the Internet.

2. Bind host services to real IPs
   Avoid binding host services to 0.0.0.0 or ::, which can conflict with spoofed IPs.
   Example: SSH on port 22 should bind only to the host’s actual IP.

3. Firewall rules
   Accept only packets destined for the host’s real IPs and drop all others. This prevents unwanted RST packets and conflicts with spoofed IPs.

This is an example of firewall rules:

table ip6 global {
        chain input {
                [...]
                tcp dport 13717 ip6 saddr 2001:0db8:3c4d:c202:1::/80 accept #only accept packet from same LAN for Wakupator
                tcp dport 22 ip6 daddr 2001:0db8:3c4d:c202:1::1234 accept #only accept SSH(22) packet for real host IPv6
                [...]
        }
}
table ip global4 {
        chain input {
                [...]
                tcp dport 13717 ip saddr 192.168.0.0/24 accept #only accept packet from same LAN for Wakupator
                tcp dport 22 ip daddr 192.168.0.37 accept #only accept SSH(22) packet for real host IP
                [...]
      }
}

Clone the project, go to the folder of the freshly cloned project, and generate build files with CMake:

cmake -B"build" -DCMAKE_BUILD_TYPE=Release
cmake --build build

And then, the executable is located in build/wakupator.

You can download precompiled binaries from the release tab.

To run Wakupator, specify the host IP address using the -H (or --host) option:

wakupator -H <IPv4/v6>

For testing, you can run Wakupator manually. Make sure to set the required capabilities as described in the Required section.

Service example:

[Unit]
Description=Wakupator server
After=network-online.target

[Service]
Type=simple

StandardOutput=journal
StandardError=journal

User=wakupator              #Verify user
Group=wakupator             #Verify group

AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN

ExecStart=/path/to/wakupator -H 2001:0db8:3c4d:4d58:1::1234 #Change to your IPv4/IPv6 and verify path

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/wakupator

Restart=on-failure
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

You can customize Wakupator behavior using the following options

Examples:

wakupator -H 192.168.0.37 -p 12345 -if eth2 -nb 5 -t 15 -kc 1
wakupator --host 2001:0db8:3c4d:c202:1::2222 --port 54321 --interface-name enp4s0 --number-attempt 6 --time-between-attempt 10 --keep-client 0

To register a machine with Wakupator, establish a TCP connection to Wakupator and send a JSON payload.
Wakupator will wait for the machine to shut down after responding with the message OK..

Once the machine is offline, Wakupator will monitor and spoof all provided IPs/ports.

Here are two examples of JSON payloads for registering a machine:

Single monitored IPv4 address:

{
    "mac": "be:ef:fa:ce:c0:de",
    "name": "MyMachineName",
    "monitor": [
        {
            "ip": "192.168.0.12",
            "port": [25565]
        }
    ]
}

Multiple monitored IPs (IPv4 and IPv6):

{
    "mac": "be:ef:fa:ce:c0:de",
    "name": "MyMachineName",
    "monitor": [
        {
            "ip": "192.168.0.12",
            "port": [22, 25565]
        },
        {
          "ip": "2001:0db8:3c4d:c202:1::2222",
          "port": [25565, 1234]
        }
    ]
}

In this example, Wakupator runs on my Raspberry PI (raspberrypi). I have another machine (tartiflette) hosting services such as a Minecraft server bound to the IPv6 address (2001:0db8:3c4d:4d58:1::2222).

I don’t want this machine to run 24/7, wasting electricity most of the time.

My goal with Wakupator:

• Wake up the machine (tartiflette) when traffic is detected on:
  • IP 2001:0db8:3c4d:4d58:1::2222 on ports 25565 (Minecraft) or 22 (SSH).
  • IP 192.168.0.37 on port 22 (SSH).
• The machine may also be started externally, and Wakupator will detect it automatically.

First, we need to launch Wakupator on a machine. In this example, it runs on raspberrypi, and we will use the release version.

For demonstraton purposes, we can launch Wakupator directly as a command:

./wakupator -H 192.168.0.84

At this point, with Wakupator running, you should see this log:

[INFO] Ready to register clients!

Retrieve the MAC address of the network interface on tartiflette that will be monitored.

For this, you can use the command ip link:

    nathanj@tartiflette:~$ ip link
    [...]
    2: enp4s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether d8:cb:8a:39:be:a1 brd ff:ff:ff:ff:ff:ff
    # here ->  ^^^^^^^^^^^^^^^^^

Now, for each IP and its associated port(s) of the services you want to monitor, construct a JSON object as follows:

Here's how my JSON looks:

{
    "mac": "d8:cb:8a:39:be:a1",
    "name": "Tartiflette",
    "monitor": [
        {
          "ip": "2001:0db8:3c4d:4d58:1::2222",
          "port": [25565, 22]
        },
        {
          "ip": "192.168.0.37",
          "port": [22]
        }
    ]
}

Create a simple Python script to send this JSON payload.
Place the script in /etc/wakupator/register_to_wakupator.py.

Create a systemd service on tartiflette to execute this Python script just before shutdown.
Place the service file in /etc/systemd/system/register.service.

Then execute these commands to enable the service:

systemctl daemon-reload
systemctl enable register.service

#Verify the status
systemctl status register
 register.service - Register the system to Wakupator
     Loaded: loaded (/etc/systemd/system/register.service; enabled; preset: enabled)
     Active: inactive (dead) # <-- It is normal that the service is inactive at this point, as it will run only during shutdown.

To resume, when the machine shuts down, a Python script that sends the JSON payload to Wakupator is automatically executed by the service.

To register the tartiflette machine, it must be turned off gracefully.

For this demonstration, we will shut it down manually using the command:

/sbin/shutdown now

After shutting down the machine, you should see logs similar to these:

[INFO] New client registered: Tartiflette (d8:cb:8a:39:be:a1)
                              - IP: 2001:0db8:3c4d:4d58:1::2222, port: [25565, 22]
                              - IP: 192.168.0.37, port: [22]
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Waiting for the machine to stop completely before proceeding with the monitoring...
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Using the IP 2001:0db8:3c4d:4d58:1::2222 as representative to check if the machine is off.
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): ICMPv6 NS Request sent to 2001:0db8:3c4d:4d58:1::2222. (#1)
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): The machine seems to be off in approximately 8s.
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Start spoofing and monitoring IP addresses.

Now, we can test Wakupator's behavior by triggering one of your rules.

I'll test it by initiating a TCP connection to IP 192.168.0.37 on port 22 (SSH).

You can also use netcat to simulate a TCP connection on a specific port:

nc -zv 192.168.0.37 22

The machine should start immediately, and Wakupator records each attempt, the apparent startup time, and the total monitoring time:

[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): traffic detected.
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Packet Info: From 192.168.0.148:57794 to 192.168.0.37:22.
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Wake-On-Lan sent. (#1)
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): the machine has been started successfully. (20s)
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Has been removed from monitoring. Total monitoring duration: 2m 13s

You can also start the machine manually by pressing the power button, or with a external WoL service.

Wakupator will see it, and log this message:

[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): the machine has been started manually.
[INFO] Client Tartiflette (D8:CB:8A:39:be:a1): Has been removed from monitoring. Total monitoring duration: 51s

Contributions are welcome! Please feel free to submit a pull request or open an issue on the repository.

This project is licensed under the MIT License. See the LICENSE file for details.

This project uses the following third-party libraries:

• cJSON - A JSON parsing library in C.
  • License: MIT
  • You can find the full license text in the file lib/cJSON/LICENSE.txt.