Wakupator - GitLite

KO | EN

gitlite — search

#hacktoberfest #go #android #rust #linux #java #windows #vue #awesome-list #security #pytorch #mcp #openai #open-source

Wakupator

(★ 179)

Automatically starts machines based on incoming traffic, using smart local IP spoofing and Wake-on-LAN.

파일 탐색기

최종 버전 다운로드 (.zip)

- - wakupator.service
- - register.service
  - register_to_wakupator.py
- - client.c
  - core.c
  - manager.c
  - monitor.c
- - log.c
- - parser.c
- - bpf.c
  - net.c
  - utils.c
- main.c
- - LICENSE.txt
.gitignore
CMakeLists.txt
LICENCE
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/Gibus21250/Wakupator

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd Wakupator

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. CMake

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
CMake 빌드 설정을 생성하는 도구입니다.
C/C++ 컴파일러 Windows는 Visual Studio(Community 무료), macOS는 Xcode Command Line Tools, Linux는 gcc/g++ 패키지가 필요합니다.

cmake -B"build" -DCMAKE_BUILD_TYPE=Release

이 명령어를 터미널에 그대로 입력해 실행하세요.

cmake --build build

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ build 폴더 안에 실행 파일이 생성됐는지 확인하고, 직접 실행해보세요 (예: ./build/앱이름).

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Wakupator

A service that allow machines on the same LAN to be automatically woken up, using IP address spoofing for a good cause.
Lightweight, no dependencies, non-intrusive, and easy to integrate.

## Table of Contents
1. [Introduction](#introduction)
   - [Overview](#overview)
   - [Advantages](#advantages)
   - [Limitations](#limitations)

2. [Precautions](#precautions)
   - [Client machine side](#client-machine-side)
   - [Wakupator host side](#wakupator-host-side)
   - [Recommendations](#recommendations)

3. [Get Started](#get-started)
   - [Compile Project](#compile-project)
   - [Pre-compiled Binaries](#pre-compiled-binaries)

4. [How to Use](#how-to-use)
   - [Launch Wakupator](#launch-wakupator)
   - [How to register a Machine](#how-to-register-a-machine)

5. [Example](#example)
   - [Context](#context)
   - [Launch Wakupator](#launch-wakupator)
   - [Prepare the JSON](#prepare-the-json)
   - [Automate Machine Registration](#automate-machine-registration-during-shutdown-process)
   - [Register the Machine](#register-the-machine)
   - [Final Test](#final-test)

6. [Contributing](#contributing)

7. [License](#license)

8. [Third-party Libraries](#third-party-libraries)

## Introduction

### Overview

Wakupator allows other machines on the **same local network (LAN)** to automatically wake up when defined traffic is detected.

1) Before shutdown, machines can request to spoof their IP addresses and associate zero or more ports to each of them.
2) Wakupator checks and spoofs these IP addresses when the machine is turned off, then monitors the requested traffic.
3) When specific traffic is detected, the registered machine is woken up by Wakupator 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.

> [!NOTE]
> - Wakupator runs only on Linux systems.
> - Wakupator can wake up any type of system compatible with Wake On Lan.

### Advantages

- **No firewall configuration required**
  - Wakupator reads packets before they reach the host firewall or local services.
- **Works with any IP-based service**
  - IPv4 and IPv6 compatible.
  - Monitor UDP and TCP traffic.
- **Very Lightway, no dependencies and easy to integrate**

### Limitations

**Sensitive to unsolicited traffic and bot scans**

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

> [!TIP]
> Some strategies to reduce unwanted wake-ups:
> - Filter or block bot traffic higher in your network (router or hardware firewall)

> [!CAUTION]
>
> Your router or L3 hardware **must** not have static IP/MAC bindings on IP addresses that could be spoofed by Wakupator.

### Client machine side

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

> [!WARNING]
> If you plan to monitor an `IPv6` address **and** the machine can be started manually (With an external WoL service, or even manually), you **must** disable Duplicate Address Detection (DAD) on the client's machine:
>
>`````bash
>sysctl -w net.ipv6.conf.{interface/all}.accept_dad=0
>`````
>Replace `{interface/all}` with the name of the relevant interface (e.g., `eth0`), or use `all` to apply globally.
> 
> ###### 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 already spoofed these IPs, his host machine 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 host side

#### Required

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:**
`````bash
sudo setcap cap_net_raw,cap_net_admin+eip /path/to/wakupator
`````

Alternatively, if you run Wakupator as a service, you can add these capabilities as:

```shell
[Service]
(...)
AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN
```

#### Recommendations

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

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

2. **Bind original 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 directly.

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.
   - These measures prevent the host machine from accidentally responding to clients on spoofed IPs, which could otherwise close connections or refresh network caches.

This is an example of firewall rules:
````bash
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
                [...]
      }
}
````
___

## Get started

### Compile project

Clone the project, go to the folder of the freshly cloned project, and generate build files with CMake:
`````bash
cmake -B"build" -DCMAKE_BUILD_TYPE=Release
cmake --build build
`````
And then, the executable is located in `build/wakupator`.

### Pre-compiled binaries

You can download precompiled binaries from the release tab.

## How to use

### Launch Wakupator

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.

>[!TIP]
>For production, it is recommended to run Wakupator as a service.

**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

| Option                           | Description                                                                                                                  |
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| **(Required)**                   |                                                                                                                              |
| `-H, --host <ip_address>`        | Set the host IP address. (IPv4 or IPv6)                                                                                      |
| General parameters               |                                                                                                                              |
| `-p, --port <port_number>`       | Set the port number (0-65535, **DEFAULT**: 13717)                                                                            |
| `-if, --interface-name <name>`   | Specify the network interface name. (**DEFAULT**: eth0)                                                                      |
| Shutdown control parameters      |                                                                                                                              |
| `-st, --shutdown-timeout <s>`    | Maximum time (seconds) to wait for a clean shutdown before canceling IP spoofing and monitoring. (**DEFAULT**: 600, -1: inf) |
| `-pd, --probe-delay <s>`         | Define the delay (seconds) between ARP (IPv4) and NS (IPv6) probes. (**DEFAULT**: 4)                                         |
| Wake-up control parameters       |                                                                                                                              |
| `-nb, --number-attempt <number>` | Set the number of Wake-On-LAN attempts. (**DEFAULT**: 3)                                                                     |
| `-t, --time-between-attempt <s>` | Set the time in seconds between attempts. (**DEFAULT**: 30)                                                                  |
| `-kc, --keep-client <0\|1>`      | Keep the client monitored if it doesn't start after <nb> attempt(s). (0: No, 1: Yes, **DEFAULT**: 1)                         |
| `-help`                          | Display help message and examples.                                                                                           |

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

___

### How to register a machine

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

> [!IMPORTANT]
> Any other response indicates an error, and Wakupator will not go any further and will display information about the error.

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

> [!TIP]
> The client must register itself shortly before shutting down.  
> An example systemd service and a Python script for registration are available in `example/machine`.  
> Use the `-st, --shutdown-timeout <seconds>` option with Wakupator if the default value (10 min) is not sufficient.

### Examples JSON payload

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

**Single monitored IPv4 address:**
`````json
{
    "mac": "be:ef:fa:ce:c0:de",
    "name": "MyMachineName",
    "monitor": [
        {
            "ip": "192.168.0.12",
            "port": [25565]
        }
    ]
}
`````

**Multiple monitored IPs (IPv4 and IPv6):**
`````json
{
    "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]
        }
    ]
}
`````
___

## Example

### Context

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.

### Launch Wakupator

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

> [!WARNING]
> Ensure that the port (default: 13717) is allowed in the host's firewall if necessary.

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

```bash
./wakupator -H 192.168.0.84
```

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

```bash
[INFO] Ready to register clients!
```

### Prepare the JSON

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

For this, you can use the command `ip link`:

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

`````json
{
    "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]
        }
    ]
}
`````

### Automate machine registration during shutdown process

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

> [!TIP]
> All related files are in `example/machine/`.

Then execute these commands to enable the service: 
```bash
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.

### Register the machine

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

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

```bash
/sbin/shutdown now
```

> [!TIP]
> In production, you should create a custom shutdown script that executes the registration under certain conditions, e.g., when there is no network activity.

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

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

### Final test

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:

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

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

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

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

___

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

## Third-party libraries

This project uses the following third-party libraries:

- [**cJSON**](https://github.com/DaveGamble/cJSON) - A JSON parsing library in C.
   - License: MIT
   - You can find the full license text in the file `lib/cJSON/LICENSE.txt`.