wol

How it works

wake builds a 102-byte magic packet — six bytes of 0xFF followed by the target MAC repeated 16 times — and sends it once as a UDP broadcast to 255.255.255.255 on the given port (default 9). It has no way to know whether the target actually powered on, which is why check exists as a companion action. check is a pure reachability probe: it tries unprivileged ICMP echo first (native on every OS — IcmpSendEcho on Windows, an unprivileged ping socket on POSIX), and only spends a TCP connect on port 443 once ICMP has failed to prove reachability. classify_check() (wol_check_plan.hpp) is the single place that turns raw probe facts into a verdict, and it deliberately distinguishes “checked and got nothing” (checked_no_reply) from “neither mechanism could even be attempted” (unavailable) — the latter degrades honestly to CONSTRAINED/PARTIAL rather than being reported as a fabricated unreachable. Neither action shells out to an external binary; the historic ping/popen implementation was removed in favour of the native probes. wol is deliberately not a reachability-history or scheduling plugin — each check call is one point-in-time read, with polling left to the caller.

flowchart LR
  OP[Operator / workflow] --> SRV[Server<br/>authz: Infrastructure.Write wake<br/>Infrastructure.Read check]
  SRV -- gRPC mTLS --> HOST[Agent plugin host] --> EX[wol.execute]
  EX --> WAKE[wake: build magic packet<br/>UDP broadcast :9]
  EX --> CHK[check: ICMP echo<br/>IcmpSendEcho / ping socket]
  CHK -- no reply --> TCP[TCP connect :443 fallback]
  WAKE & CHK & TCP --> ROWS[rows + typed result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• check / Linux — requires net.ipv4.ping_group_range to admit the process group for ICMP; falls back to a TCP connect on port 443, and reports CONSTRAINED if neither mechanism is usable

Privileges and prerequisites

No subprocess is spawned by either action — the historic ping/popen shell-out was removed (changelog.d/20260818-wave2-network-actions-wol-services-native-argv.changed.md). wake opens a UDP datagram socket; check opens an unprivileged ICMP ping socket (POSIX) or calls IcmpSendEcho (Windows), plus a TCP connect socket on port 443 as fallback. Network only — no filesystem or registry access.

Data contract

Inputs

Outputs

Every action writes pipe-delimited rows via write_output(); field 0 is a literal discriminator matching the action name. wake’s field count is not constant — an error row carries only status|message; port and bytes_sent are appended only on the success path, never padded with -. check additionally emits a second, separate row discriminated mechanism — a real output field that is not declared in result.columns below (see Caveats).

device.wol.check — host|status|count

device.wol.wake — status|message|port|bytes_sent

Supplementary mechanism row. check always emits a second row, mechanism|<label>, immediately after the check row. <label> is one of icmp, tcp-fallback, tcp-refused, icmp+tcp-fallback (both mechanisms genuinely attempted, neither succeeded), or unavailable (neither could be attempted) — wol_check_plan.hpp:96-113.

Result status

Every other outcome — wake’s success/error paths, and check’s reachable/unreachable/checked_no_reply verdicts — never calls set_result_status; the agent records UNDECLARED/UNKNOWN, which is what every captured sample shows below, including a genuine reachable check.

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics — grepping the server tree for wol finds only the capability-declaration rows in plugin_action_catalogue_c.hpp; nothing else reads this plugin’s output.
• Sensitivity. check’s host row echoes back the caller-supplied hostname or IP address being probed — a device identifier. wake has no declared identifying column, though its uncaptured success-path message text likely names the target MAC address as confirmation text (see Caveat 3 — never observed in a sample). Neither action’s rows carry a person’s identity or installed-software information.
• Siblings: network.probe.icmp / network.probe.tcp (netprobe.yaml) share check’s underlying icmp_probe.hpp mechanism for their own reachability probes.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("device.wol.wake"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash dcc02549b1eb

== action=wake
wake|error|Missing required parameter: mac
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=check host=127.0.0.1
check|127.0.0.1|reachable|3
mechanism|icmp
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash dcc02549b1eb

== action=wake
wake|error|Missing required parameter: mac
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=check host=127.0.0.1
check|127.0.0.1|reachable|3
mechanism|icmp
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash dcc02549b1eb

== action=wake
wake|error|Missing required parameter: mac
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=check host=127.0.0.1
check|127.0.0.1|reachable|3
mechanism|icmp
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. wake needs no elevated privilege. The plugin opens a plain SOCK_DGRAM/IPPROTO_UDP broadcast socket on every OS (wol_plugin.cpp:215) — no SOCK_RAW, so no cap_net_raw or root; docs/agent-privilege-model.md:120 states the same. Earlier revisions of that row claimed a cap_net_raw grant; treat any remaining reference to it elsewhere as stale.
2. check’s timeout_ms is reset, not clamped, outside 100-5000. The code reads timeout_ms (default 1000 ms; a value outside 100-5000, or one that does not parse, is replaced by 1000; wol_plugin.cpp:290-298). content/definitions/wol.yaml declares it with the range 100-5000, so a call through POST /api/instructions/{id}/execute gets a 400 for an out-of-range value instead of the silent reset; a caller that bypasses that route still gets the reset.
3. wake’s success-path output was never captured. Both fixture runs deliberately rejected wake for a missing mac (an Irreversible, AdminOrApproval-gated action), so the port/bytes_sent field shapes in this README are derived from source (wol_plugin.cpp:248-249), not observed in any sample — the Outputs table marks those examples as such rather than showing a captured value.
4. The Linux sample ran as root, not the unprivileged path check’s fallback exists for. linux.txt was captured at euid 0 in a container, so the ICMP-denied → TCP-fallback branch (net.ipv4.ping_group_range) was never actually exercised by any sample; every OS sample shows the same plain-ICMP-succeeds path.
5. The historic shelled-out ping is gone; do not reintroduce it. check used to spawn a system ping via popen (rung 3); the migration to native ICMP + TCP-connect fallback removed the last subprocess spawn from this plugin (changelog.d/20260818-wave2-network-actions-wol-services-native-argv.changed.md). icmp_probe.hpp’s own header comment (lines 6-10) is stale — it still describes wol.check as an unmigrated shell-out that “still spawns the system ping binary”; the plugin’s actual behaviour is the native path in wol_plugin.cpp.

Source and tests

• Plugin: agents/plugins/wol/src/wol_check_plan.hpp · agents/plugins/wol/src/wol_plugin.cpp
• Definitions: content/definitions/wol.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_c.hpp
• Tests: tests/unit/test_wol_check_plan.cpp
• Privilege row: docs/agent-privilege-model.md