WIFI

Manages a wireless network profile. NetworkManager is the only backend implemented today. ConnMan, wpa_supplicant, and iwd are reserved enum values in the proto so the action can grow other backends without a rename — but the agent currently ignores the backend field and always drives NetworkManager. Selecting another backend does not error; it just gets NetworkManager behaviour (which then fails on hosts that don't run it). Two auth modes: pre-shared key (WPA2 / WPA3-Personal) and EAP-TLS (enterprise 802.1X with client certs).

Parameters

Field	Type	Required	Default	Description
`ssid`	string	yes	—	Network name. 1–255 chars.
`auth_type`	enum	yes	—	`PSK` or `EAP_TLS`.
`psk`	string	yes if PSK	—	Pre-shared key. Max 63 chars.
`ca_cert`	string	yes if EAP_TLS	—	PEM-encoded CA certificate.
`client_cert`	string	yes if EAP_TLS	—	PEM-encoded client certificate.
`client_key`	string	yes if EAP_TLS	—	PEM-encoded client private key.
`identity`	string	no	—	EAP identity (e.g. `user@corp.example`). Max 254 chars.
`auto_connect`	bool	no	`false`	Auto-connect when in range. The web UI pre-checks it.
`hidden`	bool	no	`false`	The network broadcasts no SSID (hidden network).
`priority`	int32	no	`0`	Connection priority. Higher wins when multiple known networks are visible. -1 to 999.
`backend`	enum	no	`NETWORKMANAGER`	`NETWORKMANAGER` is the only implemented value; the agent ignores the field today. `CONNMAN`, `WPA_SUPPLICANT`, and `IWD` are reserved enum slots.

Idempotency

A connection profile named pm-wifi-<actionId> is created in NetworkManager. On each tick, EAP-TLS profiles are diffed against the live settings (including the PEM contents on disk) and only rewritten on change. PSK profiles are always rewritten — NetworkManager can't read the PSK back to diff it, so a PSK action reports changed=true on every apply. The connection isn't activated by the action; it's configuration only. auto_connect controls whether NetworkManager picks it when it sees the SSID.

desired_state: ABSENT deletes the profile and any associated certificate files.

Example

WPA3 office network, auto-connect, high priority:

type: WIFI
ssid: ACME-Corp
auth_type: PSK
psk: "<from password manager>"
auto_connect: true
priority: 100
desired_state: PRESENT

Enterprise EAP-TLS with client certs:

type: WIFI
ssid: ACME-Corp-Secure
auth_type: EAP_TLS
identity: "alice@corp.example"
ca_cert: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
client_cert: |
  -----BEGIN CERTIFICATE-----
  ...
client_key: |
  -----BEGIN PRIVATE KEY-----
  ...
auto_connect: true
desired_state: PRESENT

Gotchas

Certificates and keys land in /var/lib/power-manage/wifi/<actionId>/. The client private key is written 0600; the PSK reaches NetworkManager via a 0600 keyfile under /etc/NetworkManager/system-connections/, never via argv.
psk and client_key are redacted from the audit-log API (ca_cert/client_cert are public material and are not). The action parameters themselves are stored like any other action's — protected by RBAC, not field-level encryption — so treat the control-server database as secret-bearing.
The action configures the profile but doesn't disconnect the current network. If the device is on Ethernet, it stays on Ethernet; the new Wi-Fi is only used when Ethernet drops or the user explicitly switches.
priority maps to NetworkManager's connection.autoconnect-priority and resolves ties when several known networks are in range simultaneously; higher is preferred.