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(+) (limited to 'docs') 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 From ca902d4eebd49697f476d538eadfcaeb8ebb2232 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:49:22 -0700 Subject: vyos-api: T9088: document /show configuration commands export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /show endpoint can return the running config as flat set commands (op-mode 'show configuration commands' equivalent) — the natural way to mirror or back up a router over the API; previously undocumented. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 383b8311..1c51cc01 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -381,6 +381,27 @@ response: } ``` +The endpoint can also export the running configuration as flat `set` +commands, equivalent to the operational mode command +`show configuration commands`. This is convenient for mirroring, diffing, +or backing up a configuration: + +```none +curl -k --location --request POST 'https://vyos/show' \ +--form data='{"op": "show", "path": ["configuration", "commands"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response (shortened): +{ + "success": true, + "data": "set interfaces ethernet eth0 address 'dhcp'\n + set interfaces ethernet eth0 hw-id '50:00:00:01:00:00'\n + set system host-name 'vyos'\n + ...", + "error": null +} +``` + ### /generate -- cgit v1.2.3 From 3a952350bf5b5b38a7db1208ed3c910ded7b4b24 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:49:48 -0700 Subject: vyos-api: T9089: document /retrieve showConfig on empty paths showConfig returns HTTP 400 'Configuration under specified path is empty' for schema-valid but unconfigured paths; recommend probing with exists or treating that error as an empty subtree. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 1c51cc01..c7f30842 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -266,6 +266,27 @@ response: } ``` +Note that `showConfig` returns an error (HTTP 400) for a path that is valid +in the schema but has no configuration under it: + +```none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": ["firewall", "ipv4", "forward"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": false, + "data": null, + "error": "Configuration under specified path is empty" +} +``` + +Automation that compares a desired state against a fresh or partially +configured system should either probe the path with `exists` first, or +treat this specific error as "no configuration present" rather than as a +failed request. + ### /reset -- cgit v1.2.3 From f002549a5fe3ae782be8fe02160fa2796e7e0471 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:50:15 -0700 Subject: vyos-api: T9090: T9091: batched /configure semantics; save via /config-file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that an operation list commits as one transaction whose error may not identify the failing op (bisect / one-op fallback), and that /configure rejects {"op": "save"} — persistence goes through /config-file. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index c7f30842..3c3d16f3 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -513,6 +513,19 @@ response: } ``` +A list of operations is applied and committed as a single transaction: if +any operation fails, nothing is committed. The error message may not +identify which operation in the list failed, so if a large list fails +validation, retry the operations in smaller lists (or one per request) to +locate the offending one. + +:::{note} +The `/configure` endpoint commits changes to the running configuration but +does not save them to disk, and it does not accept `{"op": "save"}` (that +returns HTTP 400). To persist changes across reboots, send +`{"op": "save"}` to the `/config-file` endpoint. +::: + ### /config-file -- cgit v1.2.3 From af04731c74b0383bc36c66addd6cc22ba41c55e0 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:50:41 -0700 Subject: vyos-api: T9092: add bulk configuration guidance Batch sizing, geoip/remote-group commit cost, the 1 MB request-body-size-limit, and commit-confirm as a remote safety net. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 3c3d16f3..1342a124 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -610,6 +610,24 @@ response: ``` +## Bulk configuration + +Large applies over the API (initial provisioning, firewall migrations with +hundreds of operations) benefit from a few precautions: + +- Prefer several requests of moderate size over one very large list of + operations, and retry per operation on failure. A very large single + commit can run longer than the HTTP gateway allows and return a timeout + even though the commit itself eventually succeeds. +- Commits that reference `geoip` country codes or `remote-group` URLs are + significantly more expensive than plain set operations, because they + trigger database or remote-list processing. Apply those one per request. +- The request body size is limited by + `service https request-body-size-limit` (1 MB by default); a very large + operation list or `config-file` string can exceed it. +- Consider commit-confirm (below) as a safety net when reconfiguring a + remote system. + ## Commit-confirm For the previous two endpoints, a `commit` command is executed automatically -- cgit v1.2.3 From 9e90088827c53f8d61e82e2e29910a9346009e87 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 14:00:18 -0700 Subject: vyos-api: T9087: tighten firewall same-request wording (review feedback) Only port/port-group require protocol in the same request; description alone is fine on an existing rule but fails on a rule no request has created yet. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 1342a124..8007a75b 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -490,12 +490,14 @@ of operations (see below). Common examples: |------|---------------------------------| | `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` | +| `firewall ... rule ` | `action` in the request that creates the rule; `protocol` together with `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. +validated as a complete commit on its own. Likewise, setting an attribute +such as `description` on a rule that no request has created yet fails with +`Configuration path ... is not valid`. The endpoint can process multiple commands if you pass them as a list to the `data` field. -- cgit v1.2.3 From 2510eefadc8e7520e7f85f45a2b29fdab634474a Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 14:08:40 -0700 Subject: vyos-api: T9087: T9092: apply review feedback (line length, retry safety) Convert the multi-field-node table to wrapped list items per the 80-char docs guideline, and rework the bulk-apply bullet to reconcile state before retrying after a timeout instead of recommending blind retries. Co-Authored-By: Claude Fable 5 --- docs/automation/vyos-api.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 8007a75b..627a7901 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -486,11 +486,12 @@ 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` in the request that creates the rule; `protocol` together with `port` or `port-group` | +- `system task-scheduler task `: `executable` together with + `interval` (or `crontab-spec`). +- `nat destination rule `: `translation` together with the other rule + fields. +- `firewall ... rule `: `action` in the request that creates the rule; + `protocol` together with `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 @@ -618,9 +619,11 @@ Large applies over the API (initial provisioning, firewall migrations with hundreds of operations) benefit from a few precautions: - Prefer several requests of moderate size over one very large list of - operations, and retry per operation on failure. A very large single - commit can run longer than the HTTP gateway allows and return a timeout - even though the commit itself eventually succeeds. + operations. A very large single commit can run longer than the HTTP + gateway allows and return a timeout even though the commit itself + eventually succeeds — after a timeout, reconcile the configuration + state (for example with `/retrieve`) before retrying, so an + already-applied change is not replayed. - Commits that reference `geoip` country codes or `remote-group` URLs are significantly more expensive than plain set operations, because they trigger database or remote-list processing. Apply those one per request. -- cgit v1.2.3