Wakupator

Wakupator is a lightweight daemon designed to wake up machines on the same LAN by exploiting IP spoofing and Wake‑on‑LAN (WOL) magic packets. When a target machine intends to shut down, it registers itself with Wakupator via a JSON payload that includes the IP addresses (IPv4/IPv6) it intends to spoof and the list of ports that should trigger a wake event. Wakupator then temporarily assigns those IPs to the host, monitors traffic on the specified ports, and upon detecting any inbound packet it sends a WOL magic packet to the target’s MAC address. This approach allows home servers or small‑scale infrastructures to conserve energy by keeping services powered off most of the day while still remaining reachable when needed.

Technical Stack

• Language & Runtime: Implemented in Go, leveraging its strong networking primitives and built‑in concurrency model. The binary is statically linked, ensuring minimal runtime dependencies on the host system.
• Networking: Uses raw sockets (CAP_NET_RAW) for crafting WOL packets and the ip command from iproute2 to add/delete spoofed IPs. IPv6 Duplicate Address Detection (DAD) is temporarily disabled via sysctl when spoofing occurs.
• Configuration: YAML/JSON based configuration files describe registered machines, their spoofed IPs, and trigger ports. The daemon watches these files for changes, allowing dynamic reconfiguration without restarts.
• Persistence: A simple embedded key‑value store (BoltDB) keeps a registry of active registrations, ensuring state survives graceful restarts.

Core Capabilities

• IP Spoofing API: Exposes a RESTful endpoint (/register) that accepts JSON payloads describing the machine to be awakened. The payload includes:
  • mac: Target MAC address.
  • spoofed_ips: List of IPs (IPv4/IPv6) to assign temporarily.
  • ports: Network ports that, when hit, trigger a wake event.
• Event Hooks: Webhook support allows external services to be notified when a machine is woken or when a registration expires.
• Health & Metrics: Prometheus‑compatible metrics expose active registrations, packet counts per port, and error rates. A /healthz endpoint provides liveness checks.
• Logging: Structured JSON logs with adjustable verbosity; can be piped to syslog or log aggregation services.

Deployment & Infrastructure

• Self‑Hosting: A single static binary runs on Linux hosts. It requires the CAP_NET_RAW capability and access to iproute2. Running as root is sufficient, but a dedicated system user with the necessary capabilities can be used for tighter security.
• Containerization: The binary is container‑friendly; a minimal Docker image (e.g., alpine + Go runtime) can host Wakupator. The container must run with the NET_RAW capability and privileged networking to manipulate IP tables.
• Scalability: Designed for LAN‑scale deployments. Each registration is isolated; the daemon scales linearly with the number of active registrations, as the underlying Go scheduler handles concurrent packet monitoring efficiently.
• High Availability: For larger environments, multiple instances can be run behind a local load balancer. A shared persistence layer (e.g., a replicated BoltDB or external key‑value store) would be needed to synchronize state.

Integration & Extensibility

• Plugin System: While no external plugin architecture exists yet, the modular design allows developers to inject custom logic by extending the REST API handlers or replacing the packet monitor with a custom implementation.
• Webhooks & Callbacks: External services (e.g., home automation platforms, monitoring dashboards) can subscribe to events via HTTP callbacks, enabling automated actions such as updating a smart‑plug or sending notifications.
• CLI Utilities: A companion command‑line tool can query the registry, list active registrations, or trigger manual wake events, facilitating scripting and automation.

Developer Experience

• Documentation: The README provides comprehensive guidance on prerequisites, registration format, and operational nuances. API contract is clearly defined with example JSON payloads.
• Community & Support: The project is open source under a permissive license (MIT). Issues and pull requests are actively maintained, and contributors can easily add features or fix bugs.
• Configuration Flexibility: Users can adjust the polling interval, timeout thresholds, and logging levels via environment variables or config files, allowing fine‑tuned performance.

Use Cases

• Home Media Servers: Keep a NAS or Plex server powered off overnight, waking only when a client device connects.
• IoT Gateways: Reduce energy consumption on edge devices that only need to be active during specific network events.
• Development Labs: Spin up virtual machines or containers only when a developer’s IDE initiates a connection, saving power on idle hosts.

Advantages

• Low Footprint: A single statically linked binary consumes negligible resources, ideal for embedded or low‑power devices.
• Fine‑Grained Control: IP spoofing combined with port monitoring gives developers precise control over when a machine should wake, unlike traditional WOL triggers that rely solely on magic packets.
• Open & Extensible: Go’s ecosystem and the simple API make it straightforward to integrate Wakupator into existing automation pipelines or custom monitoring stacks.
• Licensing: MIT license allows unrestricted use, modification, and redistribution—perfect for commercial or proprietary deployments.

Wakupator offers