Skip to content

Prepare Cisco 8000 and NCS routers for IOS-XR appmgr

Onboard a Cisco 8000 series router, or an NCS-540 router, running IOS-XR. The agent runs as an appmgr application and stages images on harddisk:. On an NCS-540, package delivery, checksum verification, registration and app startup are validated; heartbeat delivery depends on catalog reachability from the app's VRF, and image staging, telemetry, and undeploy are not yet validated on this platform. Confirm each before you rely on it.

Skip this page for Catalyst 9000 series switches (Guest Shell, or IOx on switches with app-hosting storage) and Catalyst 8000 series routers; see Prepare Industrial Ethernet, Catalyst 9000 and 8000 devices for the IOx app and Supported devices and platforms.

Before you start

  • A current iris-xr.rpm prepared by the Ubuntu .deb setup. Check it in Settings > Device packages.
  • SSH access to the router and a saved credential profile.
  • On the router: bash, curl with HTTPS, and SHA-256 tools.
  • A route to the artifact server, normally TCP port 8000. See Open the required ports.
  • Free space on harddisk: for the package and every image you stage. See What a device needs before onboarding.

Set the management type and platform

Use the xr-host management type with the xr-appmgr platform. Leave every address, VLAN, SVI (switch virtual interface), VirtualPortGroup, and NAT field empty. See Choose a management type.

Make sure the router can reach the catalog

Establish a path from the router to the artifact server, the tracker, and the seeder. See Network ports and flows.

Warning

A route that reaches the catalog only from another VRF or a different source address will not work.

Onboard the router

  1. Add the router to your inventory with the xr-host management type, the xr-appmgr platform, and a credential profile.
  2. Start onboarding from the Console, or call POST /api/v1/devices/{device_id}/onboard. Result: the server installs iris-xr.rpm on harddisk: and starts the iris application.
  3. Follow the job until it reports that onboarding completed.
  4. Wait for a heartbeat before you assign an image.

What onboarding puts on the router

On harddisk: What it is
iris-xr.rpm The appmgr package that carries the device agent.
iris-catalog.pem The certificate the agent trusts.
iris-work/ The agent's own working directory.
peer-tls/ The peer identity and public certificate generations when peer TLS is required.
Staged images and sidecar files Each assigned image and its transfer files.

The agent writes only to harddisk:. Undeploy removes the application, package, runtime certificate, working files, active peer identity and transfer sidecars. It preserves staged images and public peer-certificate generations. A later onboarding enrolls a fresh peer identity with the selected deployment. See Undeploy, retire and clean up devices.

How the transfer is verified

The server supplies the public catalog certificate through SSH with host-key verification. The router uses that certificate to fetch iris-xr.rpm and the encrypted bootstrap instruction over authenticated HTTPS. Before registering the package, it checks both downloads against SHA-256 values from server-side snapshots. A corrupted or tampered transfer is refused instead of installed.

Verify

  • The job's last result says onboarding completed.
  • A fresh heartbeat confirms the agent reached the catalog.
  • On the router, the iris application is active and harddisk: holds iris-catalog.pem and iris-work/.

Next steps