docs · configuration(5)

Configuration

Reference for the module parameters that control activation behavior, including what each parameter does, when it applies, accepted values, defaults, interactions and validation rules.

disarmed armed

Configuration is applied when the module is loaded and cannot be changed at runtime; changing a parameter requires unloading and reloading the module.

Core parameter

parameter	required	description
`EXEC`	yes	Absolute path to an executable run via `/bin/sh -c` when any trigger fires. Must have execute permission. Max length 4096 bytes; load fails past that.

keyboard trigger

parameter	required	description
`PHRASE`	no	Exact phrase to match, typed in sequence on a US keymap. If unset, the keyboard trigger disables itself at load (logged as a warning, not an error).

make load PHRASE="nuke" EXEC="/path/to/script"

usb trigger

parameter	required	description
`USB_DEVICES`	no	Comma-separated `VID:PID:EVENT` rules (max 16). `EVENT` is `insert`, `eject`, or `any`; defaults to `any` if omitted from a rule. If unset or empty, the USB trigger disables itself.
`WHITELIST`	no	Boolean. `0` (default). Listed devices are blocked/matched as a blacklist, all others trigger `1`. Only listed devices trigger.

# blacklist mode (default): any device other than 1234:5678 triggers on insert/eject
make load USB_DEVICES="1234:5678" EXEC="/path/to/script"

# whitelist mode: only 1234:5678 triggers, on any event
make load USB_DEVICES="1234:5678:any" WHITELIST=1 EXEC="/path/to/script"

# multiple rules
make load USB_DEVICES="1234:5678:insert,abcd:ef00:any" EXEC="/path/to/script"

Look up VID/PID with lsusb. Malformed hex or an unrecognized event string aborts module load with a specific error identifying the bad rule.

network trigger

parameter	required	description
`MATCH_MAC`	no	Source MAC address to match (any separator, or none: `aa:bb:cc:dd:ee:ff`, `aa-bb-cc-dd-ee-ff`, or `aabbccddeeff`).
`MATCH_IP`	no	Source IPv4 address to match, dotted-decimal.
`MATCH_PORT`	no	TCP/UDP source or destination port to match.
`MATCH_PAYLOAD`	no	Substring to search for in the packet payload when `MATCH_PORT` or `MATCH_PAYLOAD` is set. Empty strings are ignored (would otherwise match every packet).
`HEARTBEAT_HOST`	no	IPv4 address to monitor for periodic traffic.
`HEARTBEAT_INTERVAL`	no	Seconds between timeout checks. Default 10.
`HEARTBEAT_TIMEOUT`	no	Seconds without traffic from `HEARTBEAT_HOST` before firing. Default 30.

# MAC match; see the warning on activation-triggers(7) before using on a live network
make load MATCH_MAC='aa:bb:cc:dd:ee:ff' EXEC="/path/to/script"

# magic packet on port 1234
make load MATCH_PORT=1234 MATCH_PAYLOAD='MAGIC' EXEC="/path/to/script"
python3 scripts/whisperer.py 192.168.1.1 1234 "MAGIC"

# heartbeat: fire if 192.168.1.1 goes quiet for 30s, checked every 10s
make load HEARTBEAT_HOST='192.168.1.1' HEARTBEAT_INTERVAL=10 \
    HEARTBEAT_TIMEOUT=30 EXEC="/path/to/script"
python3 scripts/heartbeat.py 192.168.1.1 1234

Combining triggers

All parameters across all three triggers can be set in a single make load invocation; each trigger validates and registers independently. Whichever fires first wins. See the one-shot latch in architecture design.

make load PHRASE="nuke" USB_DEVICES="1234:5678:eject" \
    MATCH_PORT=1234 MATCH_PAYLOAD="MAGIC" EXEC="/path/to/script"

Validation

Missing or empty EXEC aborts load (exec parameter required).
EXEC longer than 4096 bytes aborts load.
A USB_DEVICES rule that fails to parse a VID/PID pair, or uses an unrecognized event name, aborts load.
More than 16 USB_DEVICES rules are truncated with a warning, not an error.
An unparseable MATCH_MAC or MATCH_IP aborts load.
An unparseable HEARTBEAT_HOST aborts load.