Data formats and states

Field names, file formats, and state values used by the Console, the API, and the device agent.

Catalog entry fields

Catalog state is written as small JSON documents, atomically, under an advisory lock, so a Console write and a CLI write at the same time cannot corrupt it.

Policy and heartbeat fields

POST /api/v1/devices/<id>/assign writes the policy; the agent reads it from GET /v1/devices/<device_id>/policy.

The heartbeat reports staging progress:

For one image, current_image_id and stage_state report its staging status; the two lists are omitted. An image in both lists shows its current error, not the older staged flag. See Assign images and check staging status.

Inventory CSV columns

fleet/devices.csv is a named-header CSV:

device_id,device_ip,management_type,iris_vlan,svi_ip,svi_mask,app_ip,app_mask,app_gateway,inband_vlan,ios_ssh_host,model,vpg_number,nat_interface,svi_igp,role,platform

The Console and the API accept only these fields plus credential_profile_id. A write with any other field name is rejected, not silently stored. schema_version, registered_at, registration_id, and os_family are set by the server. registration_id distinguishes a device deleted and re-added under the same device_id within the same second. Two older CSV headers, vlan and guest_ip, are still accepted on import.

Import and export this CSV from Add and onboard devices. Roles and schedules have their own templates: fleet/roles.csv.example and fleet/schedules.csv.example; see Control which devices share with each other and Schedule maintenance windows.

Instruction state vocabulary

An instruction is the signed message the server sends a device saying which images to stage and how. Each tick, the agent reports one raw state; the server derives a display state from that, report age, and revocation.

Raw agent states: none, applied, lkg, stale_expired, allowlist_expired, rollback_rejected, floor_reset, audience_mismatch, key_rejected, tamper_rejected, verifier_missing, lkg_rejected, lkg_unreadable, oversize, reasserted, instr_unavailable, instr_pending, instr_forbidden, tracker-only.

Server display states: applied, lkg, stale, rejected, tracker-only, pre-instructions, unknown, unavailable, pending, forbidden, floor_reset, none, revoked.

lkg means the device fell back to its last accepted policy (LKG, last known good; see Glossary). The Guest Shell agent package bundles its own signature verifier, so every device checks instruction signatures. verifier_missing means the device's agent package is outdated or damaged; redeploy the package to fix it. A device whose instr_protocol: 1 marker is absent displays as pre-instructions; an instr_protocol value that is invalid displays as unknown. A durable revoked display overrides the agent's own state, and the underlying agent evidence stays visible beneath it. Missing/corrupt evidence reads as null/unknown and must never become healthy zero. The server measures report age itself: an old report is marked stale while the underlying agent state and its evidence stay visible.

Each device row, and the per-device QoS response, carries one instruction object:

/api/v1/peer-policy adds fleet_rollup, an instruction_status summary, and instruction_keys. See Roles and sharing-policy API and How instructions are signed and trusted.

Instruction failures and recovery

A fetch or verification failure affects only that step: heartbeat and staging continue on usable LKG or defaults. An aria2 RPC apply failure still sends a heartbeat but skips staging that tick. A rejection can coexist with a complete older accepted identity.

The instruction and keylist endpoints share a per-device rate limit: a burst of 2 requests, refilling at one every 10 seconds. A 429 response carries a bounded Retry-After hint.

Deployment records

IRIS records three parts of each device deployment:

A deployment record's lifecycle is fail-closed:

planned → applying → active → (applying) → removed
                 ↘ unknown / needs-reconcile / drifted / superseded

A controller restart converts any non-terminal record (planned or applying) to unknown; in-flight device work is never silently resumed. A device has exactly one live deployment, so when a new deployment record becomes active, any previous active record for that device is retired to the terminal superseded state.

Setup-status states

GET /api/v1/settings/setup-status reports one state each for admin, telemetry, packages, and image_verification.

Where server state lives

These files live on the server host:

Every per-device store under IRIS_STATE is keyed state, split over 256 shard files.

The peer endpoint map holds one row per principal, in peer-endpoints.d/, split over 256 shard files. An announce locks, parses, and rewrites only its own principal's shard, recording the announce's socket source as the address.

report-attribution.json

<state>/report-attribution.json pins, per exported device report, the peer-attribution classification (origin, device, or unknown) of that report's rows. The server classifies a report once, at first export, and reuses the same classification if the same report is re-exported under the same event.id after a server restart, so a downstream system that deduplicates by event.id never sees two different records with one id. If the pin is lost, a later replay can classify the same rows differently, using whatever peer-identity view is current at replay time.

If that durable write fails, the entry is queued in memory and retried on the following reconcile passes rather than dropped. The device keeps participating in the swarm meanwhile, but the reported enforcement status degrades until the write lands, because the derived deny set is computed from durable state.