pve_sdn_lock_acquire
Acquire the global SDN configuration lock to block other writers. Use confirm=True to get a lock token; dry-run by default returns a plan.
Instructions
MUTATION: acquire the global SDN configuration lock (RISK_MEDIUM).
Blocks every OTHER legitimate SDN writer cluster-wide until released via pve_sdn_lock_release (or automatically by pve_sdn_apply/pve_sdn_rollback's own release_lock param) — a self-inflicted-DoS risk if you forget to release. Dry-run by default (returns a PLAN — there is no read-only way to check if the lock is already held, so the plan is a pure preview, not a live check). confirm=True acquires the lock and returns {"status": "ok", "result": ""}.
SECRET HANDLING: the token is a capability handle, not a password — it is returned ONCE in
result and is NEVER written to the audit ledger (mirrors pve_token_create's own secret
handling). Pass it as lock_token to subsequent SDN mutations, and to pve_sdn_lock_release /
pve_sdn_apply / pve_sdn_rollback to release it. If the token is lost (session death, forgotten
release), the only recovery is pve_sdn_lock_release(force=True) — HIGH risk, since it releases
without proof of ownership.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | False (default) returns a dry-run PLAN only; True acquires the lock. | |
| allow_pending | No | True bypasses PVE's own default refusal to lock over already-dirty pending state. Never default this on. | |
| proximo_target | No | Which configured Proxmox target to run this call against — a target name from your multi-target config (a specific PVE/PBS/PMG/PDM box). Omit to use the single/default target from the environment; the selection applies only to this call. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |