Stage your first image
Take one image to one device. Do this once, before you stage a fleet.
Staging means copying an image to the device's flash and checking its hash, then stopping. The device keeps running its current software until you install the image yourself.
Before you start
- A running server and a Console sign-in. See Install IRIS.
- The Ubuntu .deb setup has completed signing and device package preparation. Check Settings > Certificates & keys and Settings > Device packages.
- One device that meets the onboarding requirements.
- The image file, and the Bulk Hash for it, the checksum Cisco publishes for an image.
In the Console
- Publish the image. In Images, upload the file, or choose Import from disk for a file already on the server. The image job finishes and the image appears in the catalog. See Publish and verify images.
- Check the image against the Bulk Hash. Refresh the Bulk Hash feed, or import a feed file when the server has no route to the internet. A mismatch puts the image in quarantine, an image that failed the Cisco hash check and is held back from devices.
- Add the device. In Inventory, choose Add Device. Pick the
platform, the series, and the management type, which is how the agent
reaches the network: on its own address, on your management VLAN, or through
the router. Add a credential profile, the stored account the server uses to
reach the device. Cisco 8000 series routers use
xr-hostandxr-appmgr, with the app address, VLAN, SVI, VPG, and NAT fields empty. NCS-540 uses the same fields; IRIS has validated package transfer and registration on it, not staging or undeploy, so use a Cisco 8000 series router for this first walkthrough if you have one. See Supported devices and platforms for which path your platform uses, and Choose a management type. - Onboard the device. Start onboarding and watch the job to the end. It installs the device agent. Read a failed job before you retry it. See Add and onboard devices.
- Wait for the first heartbeat. Assign nothing until the device has reported in once.
- Assign the image. Select the image for the device. The agent downloads it from the server and from peers, checks it against the catalog hash, and places it in flash.
- Read the staged report. The device reports a staged state for the image. That state, not the transfer counters, is the answer. See Assign images and check staging status.
Warning
If the device already runs an IRIS app, remove it first through its deployment record, not with a forced cleanup. See Undeploy, retire and clean up devices.
With the API
| Step | Route |
|---|---|
| Assign the image | POST /api/v1/devices/{device_id}/assign |
| Read staging status | GET /api/v1/devices/{device_id}/reports |
The ordered image_ids list replaces the device's assignment, so send every
image you still want assigned. See Console API.
When the agent reports verifier_missing
verifier_missing means the device's agent package is missing or has a
damaged copy of the bundled signature verifier. The Guest Shell agent package
carries its own verifier, so redeploy the package to restore signature
checking. The device still stages the image while this is unresolved. Check
signed-instruction status separately from staging status.
When the image never reaches the device
| Symptom | Likely cause | What to do |
|---|---|---|
| Onboarding fails on every device | The server cannot stamp instructions yet | Check Settings > Certificates & keys; finish setup or renew the signing certificate, then retry the job |
| Onboarding fails on one device | The connectivity fields or the credential profile do not match the management type | Read the job output, correct the device entry, then onboard again |
| The device onboards but no report appears | No assignment reached the agent, or the agent cannot reach the server | Confirm the assignment, then check the device's route to the server |
| The image is published but no device gets it | The file failed the Cisco hash check | Refresh the Bulk Hash feed, then compare the published checksum with your file |