Add and onboard devices

You add a device to the inventory, then onboard it. Onboarding installs the device agent. Images come afterwards, in Assign images and check staging status.

Before you onboard

Each device needs:

• A management type: how the agent reaches the network, on its own address, on your management VLAN, or through the router. See Choose a management type.
• The network fields that management type asks for, such as the VLAN, the agent addresses, or the VirtualPortGroup number.
• A credential profile, so the installer can log in to the device.
• The platform requirements in What a device needs before onboarding.

Prepare the inventory

In Add device, choose the model series and management type first. Agent install lists their compatible choices after the server checks them. For Catalyst 8000 series, choose Router routed or Router NAT for either Guest Shell or IOx. If the check is unavailable, reopen the form to retry.

Add devices one at a time in the Console, or import a CSV file. Use fleet/devices.csv.example as the template. The header row is validated:

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

Every row declares a management_type of routed, inband, router-routed, router-nat, or xr-host. The columns each type fills are listed in Data formats and states. The optional role column sets which group of devices this one shares pieces with; see Control which devices share with each other.

Read the file before you import it. Check the management_type of each row, and for inband rows check that the VLAN, the SVI (switch virtual interface) and the gateway you name already exist.

In Inventory → CSV, choose Import CSV and select the file. The result stays below the toolbar while the table refreshes. Device edits wait until the import finishes. If the result is uncertain, check Inventory before retrying. Export CSV saves your inventory; Download example saves a template.

Assign a credential profile

Open Inventory → Manage credentials to create a profile. Enter its id, device username and password, then choose Save profile. To change a profile, choose Edit and re-enter the device password. New starts another profile. Closing the panel or leaving the tab clears entered passwords.

If the list is unavailable, Refresh profiles checks it again. The last successful list stays visible. An unknown save or delete result means the response was lost or incomplete; refresh and check before trying again.

An imported device cannot be onboarded until you give it a profile.

1. Open Inventory and select the imported rows.
2. Open More actions → Set credential and pick a profile.
3. Check reviewed devices, then press Apply. This list stays fixed while the dialog is open.

The result counts saved changes and names any refusals. If the result is unknown, check the refreshed device rows before trying again. Choosing no credential asks you to confirm clearing these assignments; it keeps the profiles.

A re-import replaces a device's network fields and keeps its credential profile. A CSV that lists a device_id twice is rejected as a whole.

In the Console

1. Open Inventory → Add Device.
2. Choose the Management type: Routed, Inband, Router routed, Router NAT, or XR host. It controls which network fields the form shows.
3. Choose the Model series: IE Switches, Catalyst Routers, Catalyst Switches, NCS, or Cisco 8000 Series. It narrows the Agent install choices. The API and CSV take exact model numbers too.
4. Choose Agent install. On Catalyst 9000 series switches the agent runs in Guest Shell, or in the IOx app on switches with app-hosting storage. Catalyst 8000 series routers offer Guest Shell or IOx. Cisco 8000 series and NCS-540 routers use the IOS-XR appmgr installer; on NCS-540, image staging, telemetry delivery and undeploy are not yet validated. See Supported devices and platforms.
5. For Router routed and Router NAT, fill in the VirtualPortGroup number and the app addressing. Router NAT also asks for the outside interface.
6. Choose a credential profile and press Save device. If the profile list is unavailable, you can save with no credential and assign one later.
7. Select the device and press Onboard. The job starts and streams its progress.

The form keeps your entries during Inventory refreshes. If the save outcome is unknown, check Inventory before saving again. Closing a form does not cancel a save already sent to the server.

A device with no management type reads:

Inventory only: management type not chosen

Edit that row into one of the management types before you onboard it.

A row imported under the deprecated vlan/guest_ip CSV headers can sit unclassified the same way. IRIS onboards it only once its complete historical routed tuple, device_id, device_ip, VLAN, SVI address and mask, and app address, is valid. An incomplete row fails before any onboarding job, enrollment credential or device connection is created; edit it into one of the current management types first.

For its first contact the agent uses an enrollment token the server mints for that one device, then obtains a credential of its own. Wait for an agent heartbeat before you assign an image to it.

With the API

Payloads and conflict checks are in Console API.

What you see

An onboard job reports the same progress for Guest Shell, IOx and IOS-XR: Prepare → Deploy/remove IRIS agent → Finalize. The heading names the series and the installer. A finished job reads Onboard completed. or Undeploy completed.

For installer steps, timings and command output, select Detailed logs before starting Onboard or Undeploy, or send {"log": true} through the API. The job confirms Detailed logs enabled., and aria2c.log is turned on for IOx and IOS-XR. Guest Shell logging is set through iris_log; see Device agent configuration.

The Onboard and Undeploy dialogs keep the devices you reviewed when you opened them. Expand reviewed devices to check the list. Start uses those devices and the options shown, even if the table selection changes.

Device activity

Inventory → Activity opens recent jobs in a side panel. Choose log on a job to read its output. Active jobs refresh every two seconds while Inventory is visible. Returning to a hidden tab refreshes the list; choose Reconnect log to resume output. Close or Esc closes the viewer and leaves jobs running.

Cancel queued asks for confirmation and cancels only queued jobs in the displayed list. Abort asks for confirmation, then cancels a queued job or requests a stop for a running installer. During connection checks, it waits for those checks to finish and prevents the installer from starting. Stopping an installer can leave the agent partly configured: onboard the device again or undeploy it. Wait for the job's final status before another action. If a request's outcome is unknown, close and reopen Activity to check the job before trying again.

Deployment logs

Monitoring → Deployment logs keeps the installer output of every finished onboard and undeploy job on the server. The newest 200 are kept.

The table lists each log's finish time, device, action, result and size. A histogram bins them over the window you pick: 24h, 7d (the default), 30d or 90d. Drag a range across it to filter the table, narrow it further with the search box and the Action and Result pickers, and choose view to read a log. Widen the range if a job you expect is missing. The same list, filtered to one device, sits on that device's panel; see Work with many devices at once.

You can also focus the graph and use arrow keys to move the time selection, or Shift + arrow to change its width. Clear removes the selection.

Each line starts with its elapsed offset from the start of the job:

[+   42.3s] [4/7] waiting for Guest Shell

Onboard many devices at once

Preflight runs when the job runs, so a large batch returns a job per device promptly. Router preflight adds read-only collision, identity and NAT checks. A failure fails that job only; the other queued jobs keep running.

A router's deployment record additionally binds the management IP and the processor-board identity, and owns only collision-free named globals and the guest-share resources it created. That binding is how IRIS proves what it owns on a shared router without touching your existing configuration.

The server limits how many onboard jobs run at the same time. The limit and its variable are in Server configuration.

To onboard a group of devices inside a maintenance window, see Schedule maintenance windows.

When a device cannot be reached

Every installer probes the device first, and a device IRIS cannot reach fails the job at once:

cannot reach device <ip> — ping/SSH probe failed; check the device IP and credentials

Every rejection is shown in the Console and recorded in Audit.

More symptoms: Troubleshoot: symptoms and first steps.

First install of a new package version

This applies to IOx. The first time a device sees a given package, the IOx runtime loads its docker layers into the image cache before the app can activate. A package the device has run before activates in seconds. The controller allows 300 seconds for each install, activation and start phase by default, inside a session deadline of 7,200 seconds. A failed wait names the step it was waiting on in the job log.

An onboard that fails at activation leaves the app-hosting configuration in place. Press Onboard again, or submit POST /api/v1/devices/<id>/onboard: the installer removes the incomplete app and tries again. An app that is RUNNING is a live deployment and needs an undeploy first.

Related

• What a device needs before onboarding
• Choose a management type
• Assign images and check staging status
• Work with many devices at once
• Undeploy, retire and clean up devices