From 0b88b491d043e5f281d8e3ae499c4d045da28f28 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:48:59 -0700 Subject: vyos-api: T9087: document commit atomicity for multi-field nodes Each /configure request is validated and committed on its own, so fields of one node (task-scheduler executable+interval, NAT translation, firewall action/protocol before port) must be sent in a single request. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 66e8250c..383b8311 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -439,6 +439,22 @@ The API processes each request in a session and commits it. For components such as DHCP and PPPoE servers, IPsec, VXLAN, and other tunnels, VyOS requires the entire configuration block for a commit. +Because every request is committed immediately, the fields of a single +configuration node cannot be staged across separate requests: everything the +commit validators require must arrive in the same request, passed as a list +of operations (see below). Common examples: + +| Node | Must be set in the same request | +|------|---------------------------------| +| `system task-scheduler task ` | `executable` together with `interval` (or `crontab-spec`) | +| `nat destination rule ` | `translation` together with the other rule fields | +| `firewall ... rule ` | `action` and `protocol` together with `description`, `port`, or `port-group` | + +Sending such fields in separate requests fails validation with errors such as +`Protocol must be defined if specifying a port or port-group` or +`must define either interval or crontab-spec`, because each request is +validated as a complete commit on its own. + The endpoint can process multiple commands if you pass them as a list to the `data` field. -- cgit v1.2.3