Planning and applying changes

Every change goes through two steps. forti plan reads the device, validates the change and stores it as a plan; it never changes the device. forti apply <id> executes a stored plan once. Between the two, you (or a person you trust) read exactly what will be sent.

Writing a plan

The convenience forms plan one operation:

1forti plan set <resource> [key] attr=value... [--clear attr]2forti plan create <resource> --object JSON|@file3forti plan delete <resource> <key>4forti plan action <monitor/path> [--body JSON|@file]

1forti plan set firewall/address LAN comment="office LAN" --clear color2forti plan set system/global hostname=fw-lab                   # a singleton takes no key3forti plan create firewall/address --object '{"name":"web","subnet":"192.0.2.10 255.255.255.255"}'4forti plan delete firewall/address web5forti plan action monitor/system/external-resource/dynamic       # --body defaults to {}

attr=value is JSON when the value parses as JSON (a number, boolean, array, object, null or a "quoted" string), else literal text: status=disable and subnet=192.0.2.0/24 are text, color=3 is a number and name='"123"' is the string 123. --clear attr (repeatable) resets an attribute to its default. @file reads JSON from a file, @- from standard input.

Plan files

Several operations go in one plan with --file (- reads standard input). The file holds a request object, or just the array of operations:

1{2  "profile": "fw01",3  "vdom": "root",4  "operations": [5    {"op": "create", "resource": "firewall/address", "object": {"name": "web1", "subnet": "192.0.2.10 255.255.255.255"}},6    {"op": "update", "resource": "firewall/policy", "key": "12", "set": {"status": "disable"}, "clear": ["comments"]},7    {"op": "delete", "resource": "firewall/address", "key": "old-web"},8    {"op": "action", "resource": "monitor/system/external-resource/dynamic", "body": {}}9  ]10}

1forti plan --file changes.json2forti plan --profile fw01 --file - < changes.json

Any other field is a usage error. Which operation fits which resource:

What planning checks

Before the first device read, each operation is checked against the catalog: the resource exists, it supports the operation, and each object appears at most once in the plan. Then forti reads every object the plan touches and builds each change through the SDK's typed models, so unknown or read-only attributes and values that do not decode are refused (validation) before anything is stored. It also refuses:

• creating an object that already exists (use an update), and updating or deleting one that does not (not_found);
• changing a table's key attribute through an update (that would write to another object);
• the value "<redacted>" anywhere in a plan. Reads show secrets that way; leave a secret attribute out to keep its current value.

The plan

1Plan 20261015-142233-a1b2c3  risk low2Device fw01  fw01.example.net:443  serial FGT60F...  v7.4.831 operation on fw01 (fw01.example.net): 1 update; risk low4 51. update firewall/address "LAN"  [low]6     comment  "" → "office LAN"7     color    3 → 0  (cleared to default)8     PUT cmdb/firewall/address/LAN {"color":0,"comment":"office LAN"}9 10digest 4c1f...11mode   guarded12note   guarded mode: a human must run `forti plan approve 20261015-142233-a1b2c3` before apply13approve  forti plan approve 20261015-142233-a1b2c314apply    forti apply 20261015-142233-a1b2c3

The plan is stored as ~/.forti/state/plans/<id>.json (mode 0600). It records the device identity (profile, host, port, VDOM, serial number, FortiOS version), and for each operation the before-state and its SHA-256 digest, the after-state, a field diff, the exact request (method, path and body) and the risk tier. The plan's digest is a SHA-256 over the device identity and the operations. Plan ids look like 20261015-142233-a1b2c3 (UTC time and six random hex digits).

1forti plan list                      # stored plans, newest first, with their state2forti plan show <id>                 # the plan, its before/after, approval and applied state

Operating modes

A mode is set with forti configure --mode or forti profile mode, is stored in config.json, and cannot be changed through forti-mcp.

Approving a plan (guarded)

1forti plan approve <id>

At a terminal, approve prints the plan and asks [y/N]; --yes, --json, or standard output that is not a terminal skip the question. The approval is written to ~/.forti/state/approvals/<id>.json: it names the plan's digest, is recorded as cli:$USER, expires after 24 hours, and is used up by the apply it allows. Approving a plan of a read-only profile, or one already applied, is refused (policy_denied); for an autonomous profile nothing is written and forti says no approval is needed.

Approval exists only in the CLI. forti-mcp never writes approvals: in guarded mode its apply tool answers approval_required with the forti plan approve <id> command for the person to run.

Applying a plan

1forti apply <id>

Apply takes only the plan id; the operations come from the stored plan. In order, it:

1. verifies the plan file (its format, its digest, and that every operation's shape, risk tier and request match what the catalog says), refusing a tampered plan;
2. refuses a plan that was already applied: a plan runs at most once;
3. checks the mode, and in guarded mode a valid, unexpired approval for this digest;
4. checks that the profile still points at the planned host and port, re-reads every before-state, and checks the device's serial number. Anything that moved makes the plan stale (stale_plan): plan again from fresh reads;
5. checks that the audit log can be appended to, and refuses before any change if not (config);
6. for a critical-risk plan, saves a configuration backup (below);
7. writes a provisional rollback plan, so even a crash mid-apply leaves one;
8. executes the operations in order, without retries, and stops at the first failure;
9. verifies each operation by re-reading the object, and after each critical-risk operation probes management connectivity;
10. rewrites the rollback plan from what actually happened, and appends the record to audit.jsonl.

Each operation ends with one status:

An apply that stopped returns partial_failure, outcome_unknown or management_connectivity_lost (exit 8) with the full execution record in error.details; in text mode the record is printed first.

Rollback plans

Every apply that may have changed the device writes a rollback plan: the inverse operations, in reverse order, built from the recorded before-states.

The rollback plan is an ordinary stored plan (kind: rollback, rollback_of: <id>). Review it with forti plan show and run it with forti apply <rollback id>, under the same mode rules: a guarded profile needs an approval for it too. It is checked for drift like any plan.

Configuration backups before critical plans

Before a plan with a critical-risk operation runs, forti downloads a full configuration backup to ~/.forti/state/backups/<plan id>.conf (0600, in a 0700 directory). It is streamed to disk, never printed or logged, and the 20 most recent backups are kept (older ones are deleted after each new backup). If the backup cannot be taken, the plan does not run (policy_denied, reason backup_failed). Setting "backup_before_critical": false on the profile in config.json turns the backup off.

Management connectivity probe

After each critical-risk operation that may have reached the device (critical monitor actions included), forti opens a fresh connection and reads monitor/system/status, checking the serial number. If that fails, execution stops with management_connectivity_lost, and the result carries the rollback plan id, the backup reference and the before-state of the operation that lost the path.

Recovery aids are not guaranteed recovery

Risk tiers

discover and plan report a risk tier for every resource and operation; a plan's tier is that of its riskiest operation.

Audit log

Every apply attempt, refused or not, and every approval is appended to ~/.forti/state/audit.jsonl (0600), one JSON object per line: the event, plan id and digest, profile, host, serial, mode, risk, each operation's resource, key, status and the names of the attributes it changed, the rollback plan, the backup status and the outcome. Values are not recorded. If the record cannot be written after the changes were made, the result says so (audit_error) rather than dropping it.