Install Orb Using ioxclient

Introduction

This guide walks you through deploying the Orb sensor on Cisco IOx devices using ioxclient, the official CLI tool for IOx application management. This method is recommended for Catalyst 9000 Access Points and developers who prefer command-line workflows.

Prerequisites

Before you begin, ensure you have:

• A compatible Cisco device with IOx enabled (see compatibility list)
• Access to the device via SSH or serial console
• The IOx SDE (Software Development Environment) VM
• The ioxclient tool installed (included in IOx SDE)
• Skopeo installed on your workstation
• An Orb deployment token

Building the IOx Package {#building-the-iox-package}

Before deploying Orb to any Cisco IOx device, you must build an IOx package (package.tar) that contains the Orb sensor image and your deployment token. This section covers the complete package building process.

Step 1: Download and Convert the Orb Image

The Orb Docker image must be converted to a format compatible with the IOx SDE. Use Skopeo to download the image for your target architecture.

For ARM64 Devices (Catalyst 9000 APs, IR1101, IE3x00)

skopeo copy \
  --override-arch=arm64 \
  --override-os=linux \
  docker://orbforge/orb-busybox:latest \
  docker-archive:orb-busybox-arm64.tar

For x86_64 Devices (Catalyst 9300/9400/9500, ISR)

skopeo copy \
  --override-arch=amd64 \
  --override-os=linux \
  docker://orbforge/orb-busybox:latest \
  docker-archive:orb-busybox-amd64.tar

Step 2: Transfer Image to IOx SDE

Transfer the image archive to your IOx SDE virtual machine:

scp orb-busybox-arm64.tar root@<ioxsde-ip>:orb/orb-image.tar

Step 3: Create the Package Descriptor

On the IOx SDE, create a working directory and the required configuration files.

Create Working Directory

mkdir -p ~/orb
cd ~/orb

Create package.yaml

Create package.yaml with the following content. Replace YOUR_DEPLOYMENT_TOKEN with your actual Orb deployment token:

descriptor-schema-version: "2.10"
info:
  name: orb
  description: "Orb Sensor"
  version: "1.0"
  author-name: "Orb"
app:
  cpuarch: aarch64
  type: docker
  env:
    PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    ORB_CONFIG_DIR: /data
    ORB_DATA_DIR: /data
    ORB_EPHEMERAL_MODE: 1
    ORB_DEPLOYMENT_TOKEN: YOUR_DEPLOYMENT_TOKEN
  resources:
    profile: custom
    cpu: 400
    memory: 80
    disk: 10
    network:
      - interface-name: eth0
        ports:
          tcp:
            - "7443"
            - "8081"
  startup:
    rootfs: rootfs.img
    target: "/app/orb sensor"
    workdir: /app

Create activate.json

Create activate.json for network activation:

{
  "resources": {
    "network": [
      {
        "interface-name": "eth0",
        "network-name": "iox-nat0",
        "port_map": {
          "mode": "1to1"
        }
      }
    ]
  }
}

Step 4: Build the IOx Package

Load the Docker image and create the IOx package.

Load the Image

docker load -i orb-image.tar

Verify the Image

docker images

You should see output similar to:

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
<none>              <none>    f1ad2bf2ebcc   5 days ago     19 MB

Tag the Image

Tag the image with the hash from the previous command:

docker tag <IMAGE_ID> orb-busybox:latest

Create the Package

Build the IOx package using ioxclient:

ioxclient docker package -p ext2 -r 5 orb-busybox:latest .

This creates package.tar in the current directory. You can now use this package to deploy Orb via ioxclient (continue below), IOx Local Manager, or Catalyst Center.

Deploying with ioxclient

Once you have built your package.tar, you can deploy it to your device using ioxclient.

Step 5: Configure ioxclient Connection

Set up ioxclient to communicate with your target device:

ioxclient profiles create

Follow the prompts to configure:

• Profile name (e.g., catalyst-ap)
• Host IP address
• Port (typically 8443)
• Authentication credentials

Activate the profile:

ioxclient profiles activate catalyst-ap

Step 6: Deploy the Orb Application

Remove Existing Installation (if upgrading)

If you have a previous Orb installation, remove it first:

ioxclient application stop orb
ioxclient application deactivate orb
ioxclient application uninstall orb

Install the Application

ioxclient application install orb package.tar

Activate with Network Configuration

ioxclient application activate orb --payload activate.json

Start the Application

ioxclient application start orb

Step 7: Verify Installation

Check that the Orb sensor is running:

ioxclient application status orb

The status should show RUNNING. Your Orb sensor will automatically register with your account using the deployment token.

View application logs:

ioxclient application logs orb

Troubleshooting

Application Not Starting

If the application fails to start:

• Verify the package was created correctly: ioxclient application info orb
• Check device resources: Ensure sufficient CPU, memory, and disk space
• Review logs: ioxclient application logs orb

Network Connectivity Issues

If the sensor cannot reach the internet:

• Verify the iox-nat0 network exists on the device
• Check that NAT is properly configured on the host device
• Ensure DNS resolution is working within the container

Image Architecture Mismatch

If you see architecture-related errors:

• Verify you downloaded the correct image architecture (ARM64 vs x86_64)
• Check the cpuarch setting in package.yaml matches your device

Package Build Failures

If ioxclient docker package fails:

• Ensure Docker daemon is running on the IOx SDE
• Verify the image is properly loaded: docker images
• Check you have sufficient disk space on the SDE

Updating the Orb Sensor

To update to a newer version of Orb:

1. Download and transfer the new image
2. Load and tag the new image
3. Rebuild the package with ioxclient docker package
4. Stop, deactivate, and uninstall the existing application
5. Install, activate, and start the new package

Your configuration is preserved through updates since the deployment token and settings are embedded in package.yaml.

Additional Resources

• ioxclient Documentation
• IOx Package Descriptor Reference
• Cisco IOx Overview