Wake-on-LAN: wake sleeping clients before scheduled backups (#326)

Per-client setting on the Edit form: enable toggle, MAC address
(prefilled from the agent, which now reports its primary interface MAC
in system info), broadcast address (prefilled from the client's IP —
needed for Dockerized servers, where the LAN's directed broadcast
routes out of the container but 255.255.255.255 does not), and a wake
timeout. Only works when the BBS server is on the same network as the
client.

Due schedules for offline WoL-enabled clients now queue normally
instead of becoming missed-schedule notifications. A scheduler step
sends a magic-packet burst each minute (plain UDP via stream sockets —
no extension or helper changes) while the job waits; the waking agent
picks the job up through normal polling. If the client doesn't
heartbeat within the timeout, the job fails with a clear error through
the standard notification path, as does a WoL job with no MAC on file.

Author: marcpope

agent/bbs-agent.py

@@ -392,6 +392,34 @@ def set_borg_source(source):
         logger.warning("Failed to save borg source: {}".format(e))
 
 
+def get_primary_mac():
+    """Best-effort MAC address of the primary network interface — the
+    server uses it to prefill the client's Wake-on-LAN MAC field.
+    Linux: interface of the default route. Elsewhere (and as fallback):
+    uuid.getnode(), skipped when it returns a random node rather than a
+    real hardware address (multicast bit set)."""
+    try:
+        if not IS_WINDOWS and platform.system().lower() == "linux":
+            with open("/proc/net/route") as f:
+                for line in f.readlines()[1:]:
+                    parts = line.split()
+                    if len(parts) > 1 and parts[1] == "00000000":  # default route
+                        with open("/sys/class/net/{}/address".format(parts[0])) as af:
+                            mac = af.read().strip().lower()
+                        if mac and mac != "00:00:00:00:00:00":
+                            return mac
+    except Exception:
+        pass
+    try:
+        import uuid
+        node = uuid.getnode()
+        if not (node >> 40) & 0x01:  # multicast bit set = randomly generated
+            return ":".join("{:02x}".format((node >> i) & 0xFF) for i in range(40, -8, -8))
+    except Exception:
+        pass
+    return None
+
+
 def get_system_info():
     """Gather system information for registration."""
     info = {
@@ -418,6 +446,7 @@ def get_system_info():
 
     # Platform and architecture info (for borg binary matching)
     info["platform"] = platform.system().lower()  # linux, darwin, freebsd, windows
+    info["mac_address"] = get_primary_mac()
     arch = platform.machine()
     if arch in ("aarch64", "arm64"):
         info["architecture"] = "arm64"

migrations/092_wake_on_lan.sql

@@ -0,0 +1,11 @@
+-- Wake-on-LAN client setting (#326). The server sends a magic packet to
+-- wake a sleeping client when backup work is queued for it. mac_address
+-- is agent-reported (prefills the WoL MAC field); wol_mac is the value
+-- the admin confirmed/entered. Only works when the BBS server is on the
+-- same network as the client.
+ALTER TABLE agents
+    ADD COLUMN mac_address VARCHAR(17) DEFAULT NULL AFTER ip_address,
+    ADD COLUMN wol_enabled TINYINT(1) NOT NULL DEFAULT 0 AFTER server_host_override,
+    ADD COLUMN wol_mac VARCHAR(17) DEFAULT NULL AFTER wol_enabled,
+    ADD COLUMN wol_broadcast VARCHAR(45) DEFAULT NULL AFTER wol_mac,
+    ADD COLUMN wol_timeout_minutes INT NOT NULL DEFAULT 5 AFTER wol_broadcast;

scheduler.php

@@ -230,6 +230,83 @@
     echo date('Y-m-d H:i:s') . " Auto-failed: job #{$zj['id']} ({$zj['task_type']}) — running >24h on online agent \"{$zj['agent_name']}\"\n";
 }
 
+// Step 2b-wol: Wake-on-LAN — queued backup work for sleeping clients (#326).
+// SchedulerService queues due backups for offline agents when WoL is enabled
+// (instead of marking the schedule missed). This step sends a magic packet
+// burst every minute until the agent's heartbeat brings it online (the job
+// then dispatches normally) or the per-client timeout expires, at which
+// point the job fails with a clear error. Only works when the BBS server
+// is on the same network as the client.
+$wolJobs = $db->fetchAll("
+    SELECT bj.id, bj.queued_at, bj.status_message, bj.backup_plan_id,
+           a.id AS agent_id, a.name AS agent_name, a.ip_address,
+           a.wol_mac, a.mac_address, a.wol_broadcast, a.wol_timeout_minutes
+    FROM backup_jobs bj
+    JOIN agents a ON a.id = bj.agent_id
+    WHERE bj.status = 'queued' AND bj.task_type = 'backup'
+      AND a.wol_enabled = 1 AND a.status = 'offline'
+");
+foreach ($wolJobs as $wj) {
+    $wolFail = function (string $error) use ($db, $wj, &$notificationService) {
+        $db->update('backup_jobs', [
+            'status' => 'failed',
+            'completed_at' => date('Y-m-d H:i:s'),
+            'error_log' => $error,
+        ], 'id = ?', [$wj['id']]);
+        $db->insert('server_log', [
+            'agent_id' => $wj['agent_id'],
+            'backup_job_id' => $wj['id'],
+            'level' => 'error',
+            'message' => "Job #{$wj['id']} failed — {$error} (client \"{$wj['agent_name']}\")",
+        ]);
+        $notificationService = $notificationService ?? new NotificationService();
+        $notificationService->notify(
+            'backup_failed',
+            $wj['agent_id'],
+            $wj['backup_plan_id'] ? (int) $wj['backup_plan_id'] : null,
+            "Backup failed on client \"{$wj['agent_name']}\" — {$error}",
+            'critical'
+        );
+        echo date('Y-m-d H:i:s') . " Failed: job #{$wj['id']} — {$error}\n";
+    };
+
+    $mac = $wj['wol_mac'] ?: $wj['mac_address'];
+    if (empty($mac)) {
+        $wolFail('Wake-on-LAN is enabled but no MAC address is configured for this client');
+        continue;
+    }
+
+    $timeoutSecs = max(1, (int) $wj['wol_timeout_minutes']) * 60;
+    $elapsed = time() - strtotime($wj['queued_at']);
+    if ($elapsed > $timeoutSecs) {
+        $wolFail("Client did not wake within {$wj['wol_timeout_minutes']} minute(s) after Wake-on-LAN");
+        continue;
+    }
+
+    $broadcast = $wj['wol_broadcast']
+        ?: \BBS\Services\WakeOnLanService::defaultBroadcast($wj['ip_address'])
+        ?: '255.255.255.255';
+    $sent = \BBS\Services\WakeOnLanService::send($mac, $broadcast);
+
+    $remaining = (int) ceil(($timeoutSecs - $elapsed) / 60);
+    $db->update('backup_jobs', [
+        'status_message' => $sent
+            ? "Wake-on-LAN sent — waiting for client to wake ({$remaining}m left)"
+            : "Wake-on-LAN send failed — retrying ({$remaining}m left)",
+    ], 'id = ?', [$wj['id']]);
+
+    if (empty($wj['status_message'])) {
+        // First attempt for this job — log once, not every minute
+        $db->insert('server_log', [
+            'agent_id' => $wj['agent_id'],
+            'backup_job_id' => $wj['id'],
+            'level' => 'info',
+            'message' => "Wake-on-LAN magic packet sent to {$mac} via {$broadcast} for client \"{$wj['agent_name']}\"",
+        ]);
+    }
+    echo date('Y-m-d H:i:s') . " WoL: magic packet " . ($sent ? 'sent' : 'send FAILED') . " to {$mac} via {$broadcast} (job #{$wj['id']}, {$remaining}m left)\n";
+}
+
 // Step 2c: Fail stale management tasks (update_borg, update_agent) after 7 days
 // unpicked. These are excluded from Step 2 so they don't fail the moment the
 // client's laptop goes to sleep, but we still need a safety valve — if an agent

schema.sql

@@ -98,6 +98,7 @@ CREATE TABLE agents (
     name VARCHAR(100) NOT NULL,
     hostname VARCHAR(255) DEFAULT NULL,
     ip_address VARCHAR(45) DEFAULT NULL,
+    mac_address VARCHAR(17) DEFAULT NULL,
     api_key VARCHAR(64) DEFAULT NULL,
     api_key_hash CHAR(64) DEFAULT NULL,
     api_key_encrypted TEXT DEFAULT NULL,
@@ -116,6 +117,10 @@ CREATE TABLE agents (
     ssh_private_key_encrypted TEXT DEFAULT NULL,
     ssh_home_dir VARCHAR(255) DEFAULT NULL,
     server_host_override VARCHAR(255) DEFAULT NULL,
+    wol_enabled TINYINT(1) NOT NULL DEFAULT 0,
+    wol_mac VARCHAR(17) DEFAULT NULL,
+    wol_broadcast VARCHAR(45) DEFAULT NULL,
+    wol_timeout_minutes INT NOT NULL DEFAULT 5,
     ssh_port_override INT DEFAULT NULL,
     status ENUM('setup', 'online', 'offline', 'error') NOT NULL DEFAULT 'setup',
     last_heartbeat DATETIME DEFAULT NULL,

src/Controllers/Api/AgentApiController.php

@@ -116,6 +116,9 @@ public function register(): void
         $data = [];
         if (!empty($input['hostname']))             $data['hostname'] = substr($input['hostname'], 0, 255);
         if (!empty($input['ip_address']))           $data['ip_address'] = substr($input['ip_address'], 0, 45);
+        if (!empty($input['mac_address']) && preg_match('/^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$/', $input['mac_address'])) {
+            $data['mac_address'] = strtolower($input['mac_address']);
+        }
         if (!empty($input['os_info']))              $data['os_info'] = substr($input['os_info'], 0, 255);
         if (!empty($input['borg_version']))         $data['borg_version'] = substr($input['borg_version'], 0, 20);
         if (!empty($input['agent_version']))        $data['agent_version'] = substr($input['agent_version'], 0, 20);
@@ -1040,6 +1043,9 @@ public function info(): void
         if (!empty($input['agent_version']))        $data['agent_version'] = substr($input['agent_version'], 0, 20);
         if (!empty($input['hostname']))             $data['hostname'] = substr($input['hostname'], 0, 255);
         if (!empty($input['ip_address']))           $data['ip_address'] = substr($input['ip_address'], 0, 45);
+        if (!empty($input['mac_address']) && preg_match('/^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$/', $input['mac_address'])) {
+            $data['mac_address'] = strtolower($input['mac_address']);
+        }
         if (!empty($input['borg_install_method']))  $data['borg_install_method'] = substr($input['borg_install_method'], 0, 20);
         if (!empty($input['borg_source']))          $data['borg_source'] = substr($input['borg_source'], 0, 20);
         if (!empty($input['borg_binary_path']))     $data['borg_binary_path'] = substr($input['borg_binary_path'], 0, 255);

src/Controllers/ClientController.php

@@ -1682,6 +1682,23 @@ public function update(int $id): void
             $port = trim($_POST['ssh_port_override']);
             $data['ssh_port_override'] = ($port !== '' && (int) $port > 0 && (int) $port <= 65535) ? (int) $port : null;
         }
+        if ($this->isAdmin() && array_key_exists('wol_enabled', $_POST)) {
+            $data['wol_enabled'] = !empty($_POST['wol_enabled']) ? 1 : 0;
+
+            $mac = \BBS\Services\WakeOnLanService::normalizeMac(trim($_POST['wol_mac'] ?? ''));
+            $data['wol_mac'] = $mac;
+            if ($data['wol_enabled'] && $mac === null && trim($_POST['wol_mac'] ?? '') !== '') {
+                $this->flash('danger', 'Invalid MAC address — use the form aa:bb:cc:dd:ee:ff.');
+                $this->redirect("/clients/{$id}");
+                return;
+            }
+
+            $broadcast = trim($_POST['wol_broadcast'] ?? '');
+            $data['wol_broadcast'] = ($broadcast !== '' && filter_var($broadcast, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) ? $broadcast : null;
+
+            $timeout = (int) ($_POST['wol_timeout_minutes'] ?? 5);
+            $data['wol_timeout_minutes'] = min(60, max(1, $timeout));
+        }
 
         if (!empty($data)) {
             $this->db->update('agents', $data, 'id = ?', [$id]);

src/Services/SchedulerService.php

@@ -40,7 +40,8 @@ public function run(): array
               AND s.next_run IS NOT NULL
               AND s.next_run <= ?
               AND bp.enabled = 1
-              AND a.status IN ('online', 'setup')
+              AND (a.status IN ('online', 'setup')
+                   OR (a.status = 'offline' AND a.wol_enabled = 1))
         ", [$now]);
 
         $created = [];
@@ -111,6 +112,7 @@ public function run(): array
               AND s.next_run <= ?
               AND bp.enabled = 1
               AND a.status = 'offline'
+              AND a.wol_enabled = 0
         ", [$now]);
 
         foreach ($overdueSchedules as $sched) {

src/Services/WakeOnLanService.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace BBS\Services;
+
+/**
+ * Sends Wake-on-LAN magic packets to sleeping clients (#326).
+ *
+ * A magic packet is 6 bytes of 0xFF followed by the target's MAC address
+ * repeated 16 times, sent as a UDP broadcast (conventionally port 9).
+ * Only works when the BBS server is on the same network as the client.
+ * Uses PHP's stream wrappers (with the so_broadcast socket option) so no
+ * sockets extension is required.
+ */
+class WakeOnLanService
+{
+    /**
+     * Normalize a MAC address to aa:bb:cc:dd:ee:ff. Accepts :, - or .
+     * separators, or 12 bare hex digits. Returns null if invalid.
+     */
+    public static function normalizeMac(string $mac): ?string
+    {
+        $hex = strtolower(preg_replace('/[^0-9a-fA-F]/', '', $mac));
+        if (strlen($hex) !== 12) {
+            return null;
+        }
+        return implode(':', str_split($hex, 2));
+    }
+
+    /**
+     * Guess the LAN's directed broadcast address from a client IP,
+     * assuming a /24 (192.168.1.50 -> 192.168.1.255). Editable in the
+     * client settings when the network is subnetted differently.
+     */
+    public static function defaultBroadcast(?string $ip): ?string
+    {
+        if (empty($ip) || !filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
+            return null;
+        }
+        $parts = explode('.', $ip);
+        $parts[3] = '255';
+        return implode('.', $parts);
+    }
+
+    /**
+     * Send a burst of magic packets. Returns true if at least one packet
+     * was handed to the network stack.
+     */
+    public static function send(string $mac, string $broadcast, int $port = 9, int $count = 3): bool
+    {
+        $mac = self::normalizeMac($mac);
+        if ($mac === null || empty($broadcast)) {
+            return false;
+        }
+
+        $macBytes = '';
+        foreach (explode(':', $mac) as $octet) {
+            $macBytes .= chr((int) hexdec($octet));
+        }
+        $packet = str_repeat("\xff", 6) . str_repeat($macBytes, 16);
+
+        $ctx = stream_context_create(['socket' => ['so_broadcast' => true]]);
+        $sock = @stream_socket_client(
+            "udp://{$broadcast}:{$port}",
+            $errno,
+            $errstr,
+            2,
+            STREAM_CLIENT_CONNECT,
+            $ctx
+        );
+        if (!$sock) {
+            return false;
+        }
+
+        $sent = false;
+        for ($i = 0; $i < $count; $i++) {
+            if (@fwrite($sock, $packet) === strlen($packet)) {
+                $sent = true;
+            }
+        }
+        fclose($sock);
+        return $sent;
+    }
+}

src/Views/clients/detail.php

@@ -200,6 +200,39 @@
                             <label class="form-label fw-semibold small">SSH Port Override</label>
                             <input type="number" class="form-control form-control-sm" name="ssh_port_override" value="<?= htmlspecialchars($agent['ssh_port_override'] ?? '') ?>" placeholder="e.g. 22222" min="1" max="65535">
                         </div>
+                        <hr class="my-3">
+                        <div class="form-check mb-2">
+                            <input type="hidden" name="wol_enabled" value="0">
+                            <input class="form-check-input" type="checkbox" name="wol_enabled" id="wolEnabled" value="1" <?= !empty($agent['wol_enabled']) ? 'checked' : '' ?>>
+                            <label class="form-check-label fw-semibold small" for="wolEnabled">Wake-on-LAN</label>
+                            <div class="form-text">Wake this client with a magic packet when a backup is due. Only works when the BBS server is on the same network as the client.</div>
+                        </div>
+                        <div class="mb-2">
+                            <label class="form-label fw-semibold small">MAC Address</label>
+                            <input type="text" class="form-control form-control-sm" name="wol_mac"
+                                   value="<?= htmlspecialchars($agent['wol_mac'] ?: ($agent['mac_address'] ?? '')) ?>"
+                                   placeholder="aa:bb:cc:dd:ee:ff" pattern="[0-9a-fA-F:.\-]{12,17}">
+                            <?php if (empty($agent['wol_mac']) && !empty($agent['mac_address'])): ?>
+                            <div class="form-text">Detected from the agent.</div>
+                            <?php elseif (empty($agent['wol_mac']) && empty($agent['mac_address'])): ?>
+                            <div class="form-text">Auto-fills once the agent checks in while awake, or enter it manually.</div>
+                            <?php endif; ?>
+                        </div>
+                        <div class="row g-2">
+                            <div class="col-7">
+                                <label class="form-label fw-semibold small">Broadcast Address</label>
+                                <input type="text" class="form-control form-control-sm" name="wol_broadcast"
+                                       value="<?= htmlspecialchars($agent['wol_broadcast'] ?? '') ?>"
+                                       placeholder="<?= htmlspecialchars(\BBS\Services\WakeOnLanService::defaultBroadcast($agent['ip_address'] ?? null) ?? 'e.g. 192.168.1.255') ?>">
+                            </div>
+                            <div class="col-5">
+                                <label class="form-label fw-semibold small">Wake Timeout</label>
+                                <div class="input-group input-group-sm">
+                                    <input type="number" class="form-control" name="wol_timeout_minutes" value="<?= (int) ($agent['wol_timeout_minutes'] ?? 5) ?>" min="1" max="60">
+                                    <span class="input-group-text">min</span>
+                                </div>
+                            </div>
+                        </div>
                         <?php endif; ?>
                     </div>
                     <div class="modal-footer">