Configuration Guide for Cisco NCS 1004, IOS XR Release 25.x.x

PDF

Configuration Guide for Cisco NCS 1004, IOS XR Release 25.x.x

Application hosting features

Updated: July 31, 2026

Want to summarize with AI?

Log in

Explains how application hosting features enable third-party and Cisco internal applications to run natively on NCS 1004 devices using IOS-XR.

Application hosting features are IOS-XR infrastructure capabilities that

  • allow third-party applications to run directly on NCS 1004 devices,

  • enable extension of device functionality to complement IOS-XR features, and

  • provide native support for containerized applications through Docker.

The Docker daemon is packaged with IOS-XR software on the base Linux OS. This provides native support for running applications inside docker containers on IOS-XR. Docker is the preferred way to run TPAs on IOS-XR.

App Manager

The App Manager is the infra on IOS-XR tasked with the responsibility of managing the life cycle of all container apps (third part and Cisco internal) and process scripts. App Manager runs natively on the host as an IOS-XR process. App Manager leverages the functionalities of docker, systemd and RPM for managing the lifecycle of third-party applications.

Caution: Do not use MPLS packets on Linux interfaces in Docker containers

MPLS packets are not supported on Linux interfaces used for application hosting in Docker containers. You must not attempt to configure or use MPLS on these interfaces, as doing so may lead to operational instability or traffic disruption.

Docker container application hosting architectures

A Docker container application hosting architecture is a platform solution that

  • utilizes Docker containers to deploy and manage applications,

  • enables the App Manager to interact with containers through the Docker client and daemon, and

  • facilitates application isolation and resource management across network devices.

Figure 1. Docker on IOS XR

Cisco IOS XR employs Docker to enable application hosting through a structured architecture. The App Manager internally uses the Docker client, which communicates with Trusted Platform Applications (TPAs) such as Docker 1 and Docker 2 by sending Docker commands.

The Docker client transmits commands to the Docker daemon, which then executes them. The Docker daemon uses the docker.sock Unix socket to communicate with the Docker containers.

When the docker run command is executed, a Docker container is created and started from a Docker image. Docker containers can operate within the global-vrf namespace, providing networking isolation.

Docker relies on overlayfs, located under the /var/lib/docker directory, for managing container directories and files

For detailed instructions on how to host an application in Docker containers on Cisco IOS XR, see: Hosting an Application in Docker Containers.

Recommendation: Follow hosting guidelines for Docker containers

Use the host paths listed below when specifying the --mount and --volume options with docker run:

  • "/var/run/netns"

  • "/var/lib/docker"

  • "/misc/disk1"

  • "/disk0"

  • "/misc/config/grpc"

  • "/etc"

  • "/dev/net/tun"

  • "/var/xr/config/grpc"

  • "/opt/owner"

TP application resource configurations

A TP application resource configuration is a system resource management feature that

  • limits the allocation of CPU, RAM, and disk space to third party applications (TPAs),

  • enforces these limits through the IOS XR application manager (appmgr), and

  • ensures platform security and operational integrity by monitoring application traffic and supporting application signing.

Third party applications (TPAs): Applications packaged as Docker containers and managed by the IOS XR operating system.

IOS XR is equipped with inherent safeguards to prevent third party applications from interfering with its role as a Network OS.

  • Although IOS XR doesn't impose a limit on the number of TPAs that can run concurrently, it does impose constraints on the resources allocated to the Docker daemon, based on the following parameters:

    • CPU: By default, ¼ of the CPU per core available in the platform.

      You can hard limit the default CPU usage in the range between 25-75% of the total system CPU using the appmgr resources containers limit cpu value command. This configuration restricts the TPAs from using more CPU than the set hard limit value irrespective of the CPU usage by other XR processes.

      This example provides the CPU hard limit configuration. 

      RP/0/RSP0/CPU0:ios(config)#appmgr resources containers limit cpu ?
  <25-75>  In Percentage
RP/0/RSP0/CPU0:ios(config)#appmgr resources containers limit cpu 25

    • RAM: By default, 1 GB of memory is available.

      You can hard limit the default memory usage in the range between 1-25% of the overall system memory using the appmgr resources containers limit memory value command. This configuration restricts the TPAs from using more memory than the set hard limit value.

      This example provides the memory hard limit configuration. 

      RP/0/RSP0/CPU0:ios(config)#appmgr resources containers limit memory ?
  <1-25>  In Percentage
RP/0/RSP0/CPU0:ios(config)#appmgr resources containers limit memory 20

    • Disk space is restricted by the partition size, which varies by platform and can be checked by executing "run df -h" and examining the size of the /misc/app_host or /var/lib/docker mounts.

  • All traffic to and from the application is monitored by the XR control protection, LPTS.

  • Signed Applications are supported on IOS XR. Users have the option to sign their own applications by onboarding an Owner Certificate (OC) through Ownership Voucher-based workflows as described in RFC 8366. Once an Owner Certificate is onboarded, users can sign applications with GPG keys based on the Owner Certificate, which can then be authenticated during the application installation process on the router.

This table shows the various functions performed by appmgr.

Package Manager

Lifecyle Manager

Monitoring and Debugging

  • Handles installation of docker images packaged as RPMs.

  • Syncs the required state to standby to restart apps in cases of switchover, etc

  • Handles application start/stop/kill operations.

  • Handles automatic application reload on:

    • Router reboot

    • Container crash

    • Switchover

  • Logging, stats, application health check.

  • Forwards docker deamon logs to XR syslog.

  • Allows to execute into docker shell of running application.

TP application bring-up methods

A TP application bring-up is a deployment process that

  • allows TP container applications to be launched and initialized for operational readiness,

  • provides multiple configuration approaches to match different deployment needs, and

  • ensures flexibility in integration with system models and container management tools.

There are four main approaches for bringing up TP applications, each offering distinct deployment and management strategies.

he four recommended methods for TP application bring-up are:

  • App Config: Use the application configuration files to define startup parameters.
  • UM Model: Employ the Unified Management model for standardized operational controls.
  • Native Yang Model: Leverage native YANG data models for direct integration and configuration.
  • gNOI Containerz: Use gNOI Containerz for streamlined container orchestration and lifecycle management.

Configure a TPA using application configuration

Activate and configure a TPA by specifying docker runtime settings to control process resources and verify the configuration.
Configuring a TPA with application configuration allows you to manage its runtime options, such as limiting the number of process IDs, ensuring efficient operation and resource management.

Follow these steps to configure the docker run time options.

Procedure

1.

Configure the docker run time option.

Use --pids-limit to limit the number of process IDs using appmgr.

Example:

This example shows the configuration of the docker run time option --pids-limit to limit the number of process IDs using appmgr. 

RP/0/RP0/CPU0:ios#appmgr application alpine_app activate type docker source alpine docker-run-opts "-it –pids-limit 90" docker-run-cmd "sh"

The number of process IDs is limited to 90.
2.

Verify the docker run time option configuration.

Use the show running-config appmgr command to verify the run time option.

Example:

This example shows how to verify the docker run time option configuration.

RP/0/RP0/CPU0:ios#show running-config appmgr
Thu Mar 23 08:22:47.014 UTC
appmgr
 application alpine_app
  activate type docker source alpine docker-run-opts "-it –pids-limit 90" docker-run-cmd "sh"
 !
!
The TPA is activated using the specified docker runtime options, and the configuration is verified to ensure resource limits are correctly applied.

Configure TPAs with the UM model

Limit the number of process IDs (PIDs) available to a TPA (Third Party Application) running in Docker using Netconf.
Use this task to apply resource limits to Docker-based TPAs managed through Cisco's Unified Model (UM). Limiting PIDs prevents runaway processes and supports system reliability.

Follow these steps to configure the docker run time options.

Procedure

Configure the docker run time option.

Use --pids-limit to limit the number of process IDs using Netconf.

Example:

This example shows the configuration of the docker run time option --pids-limit to limit the number of process IDs using Netconf. 

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <config>
      <appmgr xmlns=http://cisco.com/ns/yang/Cisco-IOS-XR-um-appmgr-cfg>                     
        <applications>
          <application>
            <application-name>alpine_app</application-name>
            <activate>
              <type>docker</type>
                  <source-name>alpine</source-name>
                  <docker-run-cmd>/bin/sh</docker-run-cmd>
                  <docker-run-opts>-it --pids-limit=90</docker-run-opts>
            </activate>
          </application>
        </applications>
      </appmgr>
    </config>
  </edit-config>

The number of process IDs for the specified TPA is limited as configured. For example, with --pids-limit=90, the application will not spawn more than 90 processes.

Native model deployment for TPAs

The native deployment model for Third Party Applications (TPAs) offers direct integration and performance benefits for supported applications. This model enables users to configure advanced options, such as limiting process IDs for containerized applications using the Native YANG model.

This configuration uses the docker runtime option --pids-limit to restrict the number of process IDs for an application called alpine_app. This ensures resource control and operational stability in environments with multiple TPAs.

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <config>
      <appmgr xmlns=http://cisco.com/ns/yang/Cisco-IOS-XR-appmgr-cfg>
        <applications>
          <application>
            <application-name>alpine_app</application-name>
            <activate>
              <type>docker</type>
               <source-name>alpine</source-name>
               <docker-run-cmd>/bin/sh</docker-run-cmd>
               <docker-run-opts>-it --pids-limit=90</docker-run-opts>
            </activate>
          </application>
        </applications>
      </appmgr>
    </config>
  </edit-config>

Key benefits of using the native deployment model:

  • Enables direct integration for TPAs.
  • Provides better resource management through advanced container options.
  • Improves performance and operational reliability for supported applications.

gNOI Containerz for TPA onboarding and lifecycle management

The gNOI Containerz service on the NCS 1004 device enables the onboarding and management of third-party applications (TPAs) using standardized gNOI remote procedure calls (RPCs). This approach offers:

  • A streamlined workflow for onboarding TPAs onto the device.

  • Standardized methods for managing the full lifecycle of containers, including deployment, start/stop, and removal.

  • Simplified and consistent administration of application containers on the device.

The Containerz - gNOI Container Service on NCS 1004 device is a workflow to onboard and manage third-party applications using gNOI RPCs.

For more information, see gNOI Containerz.

Docker run options

A Docker run option is a container configuration parameter that

  • controls resource allocation such as CPU, memory, and networking,
  • enables fine-tuning of security, health checks, and process behavior, and
  • allows customization during container launch for precise operation.

Docker run options are used in IOS-XR environments through the Application Manager (AppMgr). These options can be configured during the launch of a docker containerized application using the appmgr activate command. AppMgr oversees these containers and ensures runtime options can override default configurations for aspects like CPU, security, and health checks. Configuration is flexible: you can use CLI or Netconf, but all runtime options must be added under docker-run-opts as needed.

Table 1. Docker run options

Docker run option

Description

--cpus

Number of CPUs

--cpuset-cpus

CPUs in which to allow execution (0-3, 0,1)

--cap-drop

Drop Linux capabilities

--user, -u

Sets the username or UID

--group-add

Add additional groups to run

--health-cmd

Run to check health

--health-interval

Time between running the check

--health-retries

Consecutive failures needed to report unhealthy

--health-start-period

Start period for the container to initialize before starting health-retries countdown

--health-timeout

Maximum time to allow one check to run

--no-healthcheck

Disable any container-specified HEALTHCHECK

--add-host

Add a custom host-to-IP mapping (host:ip)

--dns

Set custom DNS servers

--dns-opt

Set DNS options

--dns-search

Set custom DNS search domains

--domainname

Container NIS domain name

--oom-score-adj

Tune host's OOM preferences (-1000 to 1000)

--shm-size

Option to set the size of /dev/shm

--init

Run an init inside the container that forwards signals and reaps processes

--label, -l

Set meta data on a container

--label-file

Read in a line delimited file of labels

--pids-limit

Tune container pids limit (set -1 for unlimited)

--work-dir

Working directory inside the container

--ulimit

Ulimit options

--read-only

Mount the container's root filesystem as read only

--volumes-from

Mount volumes from the specified container(s)

--stop-signal

Signal to stop the container

--stop-timeout

Timeout (in seconds) to stop a container

--cap-addNET_RAW

Enable NET_RAW capabilities

--publish

Publish a container's port(s) to the host

--entrypoint

Overwrite the default ENTRYPOINT of the image

--expose

Expose a port or a range of ports

--link

Add link to another container

--env

Set environment variables

--env-file

Read in a file of environment variables

--network

Connect a container to a network

--hostname

Container host name

--interactive

Keep STDIN open even if not attached

--tty

Allocate a pseudo-TTY

--publish-all

Publish all exposed ports to random ports

--volume

Bind mount a volume

--mount

Attach a filesystem mount to the container

--restart

Restart policy to apply when a container exits

--cap-add

Add Linux capabilities

--log-driver

Logging driver for the container

--log-opt

Log driver options

--detach

Run container in background and print container ID

--memory

Memory limit

--memory-reservation

Memory soft limit

--cpu-shares

CPU shares (relative weight)

--sysctl

Sysctl options