NSO Always-On Sandbox Build

This repository provides the tools and scripts necessary to build and deploy the Cisco NSO (Network Services Orchestrator) Always-On Sandbox hosted on DevNet. NSO is Cisco's network automation and orchestration platform that enables intent-based networking through service modeling and configuration management.

The sandbox sets up a fully operational NSO instance with sample devices and packages for testing and development purposes. The Always-On Sandbox is read-only.

This repository is publicly available, offering the community insight into part of the sandbox setup process. The remaining steps are handled by a CI/CD pipeline within the sandbox infrastructure, which is not included here.

🚀 Overview

The NSO Always-On Sandbox Build project enables:

• Version management through git tags aligned with NSO releases.
• Automated container builds of NSO with pre-configured services and devices.
• Sandbox deployment with production-ready docker-compose configuration.
• Development environment for testing NSO automation and services.

Important

This repository does not include the NSO container image binary. You must download it separately from software.cisco.com.

📋 Update NSO Version

Most of the time, you will only need to update the NSO version in the sandbox_env_vars.sh file. This file contains environment variables used during the build and deployment process.

1. Update NSO Version

Update the NSO version in sandbox_env_vars.sh:

# NSO Version
NSO_VERSION=6.4.4.1

2. Download NSO Binary

Note

Download the corresponding NSO container image from software.cisco.com and place it in the project root.

# Example filename (version should match sandbox_env_vars.sh)
nso-<version>.container-image-prod.linux.x86_64.signed.bin

3. Configure Environment Variables

Create a .env file in the project root with the required variables:

cat > .env << EOF
# Required: Admin password for NSO
ADMIN_PASSWORD=<admin_password>

# If using tacacs, add the following:
TACACS_SERVER_HOST=<tacacs_server_ip>
TACACS_SERVER_SECRET=<tacacs_server_secret>
TACACS_SERVER_PORT=<tacacs_server_port>
EOF

4. Verify Image Information

Use the check-image-info target to ensure the BASE_IMAGE and NSO_VERSION variables match what you downloaded against the sandbox_env_vars.sh.

If they don't match, the rest of the scripts will fail. Update accordingly.

make check-image-info

5. Validate TACACS Configuration

Ensure your TACACS environment variables are properly configured:

make validate-tacacs

6. Verify Local Build

Make sure your build works.

Extract and load the NSO image:

make extract-nso-image
make load-nso-image

Build and run locally:

make all

Check the logs to make sure NSO starts correctly:

make follow

Tip

Always verify your build before creating tags to ensure everything works correctly.

Access the container:

make cli

7. Create Version Tag

Clean up temporary files:

make cleanup-temp-files

Commit changes and create a git tag with the NSO version:

Note

Replace <version> with the actual NSO version you are updating to, e.g., 6.4.4.1

git tag v<version>
git push origin main --tags

🚀 Sandbox Deployment Workflow

For Sandbox Team

1. Clone the repository with the specific NSO version specified on the sandbox_env_vars.sh file as a tag. You can also find all the tags created on the GitHub tags page.

   git clone --branch v<version> https://github.com/CiscoDevNet/NSO-AlwaysOn-Sandbox-build.git
   cd NSO-AlwaysOn-Sandbox-build

Note

Replace <version> with the actual NSO version you are updating to, e.g., v6.4.4.1

2. Download the corresponding NSO container image from software.cisco.com, look for "Network Services Orchestrator". Once you download it, place it in the project root. The filename should be: nso-<version>.container-image-prod.linux.x86_64.signed.bin.

Note

The docker-compose configuration will automatically mount these certificates to the NSO container.

3. Add the admin password and TACACS configuration

   Add the admin password and TACACS server configuration to a .env file in the root directory:

   cat > .env << EOF
   ADMIN_PASSWORD=<admin_password>
   TACACS_SERVER_HOST=<tacacs_server_ip>
   TACACS_SERVER_PORT=<tacacs_server_port>
   TACACS_SERVER_SECRET=<tacacs_server_secret>
   EOF

   TACACS Authentication Both TACACS_SERVER_HOST and TACACS_SERVER_SECRET are required environment variables.

   The TACACS configuration is automatically created into NSO during build time and loaded at runtime.

   If either TACACS_SERVER_HOST or TACACS_SERVER_SECRET is missing, no tacacs configuration will be built. An error message will be displayed.

4. Build for sandbox deployment

   make extract-nso-image
   make load-nso-image
   make check-image-info

   make build-deploy-sandbox

5. Clean up temporary files after deployment:

   make cleanup-temp-files

🛠️ Container Build Process

The container is built with the following components to provide a complete NSO automation environment:

Base Configuration

• NSO Version: Dynamically set via sandbox_env_vars.sh.
• Base Image: cisco-nso-prod (extracted from signed binary).
• User: developer with password Services4Ever (read-only access).
• Exposed Ports: 443 (HTTPS), 2024 (SSH), 8080 (HTTP only locally).

Automated Build Steps

The Dockerfile performs the following automation steps:

1. User Setup: Creates a developer user with proper permissions.
2. Configuration: Copies NSO configuration files to correct locations.
3. TACACS Authentication: Injects TACACS+ server configuration from environment variables.
4. NED Installation: Links required Network Element Drivers (NEDs).
5. Package Compilation: Builds the router package with YANG models.
6. Environment Setup: Configures bash aliases and PATH variables.

Pre-installed Components

Network Devices (Netsim)

The container includes the following netsim devices:

Click to view complete device list

admin@ncs# show devices list
NAME             ADDRESS    DESCRIPTION  NED ID               ADMIN STATE
-------------------------------------------------------------------------
core-rtr00       127.0.0.1  -            cisco-iosxr-cli-3.5  unlocked
core-rtr01       127.0.0.1  -            cisco-iosxr-cli-3.5  unlocked
core-rtr02       127.0.0.1  -            cisco-iosxr-cli-3.5  unlocked
dist-rtr00       127.0.0.1  -            cisco-ios-cli-3.8    unlocked
dist-rtr01       127.0.0.1  -            cisco-ios-cli-3.8    unlocked
dist-rtr02       127.0.0.1  -            cisco-ios-cli-3.8    unlocked
dist-sw00        127.0.0.1  -            cisco-nx-cli-3.0     unlocked
dist-sw01        127.0.0.1  -            cisco-nx-cli-3.0     unlocked
dist-sw02        127.0.0.1  -            cisco-nx-cli-3.0     unlocked
edge-firewall00  127.0.0.1  -            cisco-asa-cli-6.6    unlocked
edge-firewall01  127.0.0.1  -            cisco-asa-cli-6.6    unlocked
edge-sw00        127.0.0.1  -            cisco-ios-cli-3.8    unlocked
edge-sw01        127.0.0.1  -            cisco-ios-cli-3.8    unlocked
internet-rtr00   127.0.0.1  -            cisco-ios-cli-3.8    unlocked
internet-rtr01   127.0.0.1  -            cisco-ios-cli-3.8    unlocked
admin@ncs#

NSO Service Packages

Router Package - A complete service package example including:

• DNS server configuration - Automated DNS setup.
• NTP server configuration - Time synchronization services.
• Syslog server configuration - Centralized logging.
• YANG models - Structured configuration templates.
• Service templates - XML templates for device configuration.

Tip

The router package demonstrates NSO best practices for service creation, including YANG modeling, XML templates, and device group targeting.

🔌 Access Information

Go to https://devnetsandbox.cisco.com/DevNet/ for sandbox access, launch the NSO Always-On Sandbox, and connect to the container.

Container Access

• SSH: Port 2024
• HTTPS/GUI: Port 443

Credentials

• Username: developer
• Password: Services4Ever
• Access Level: Read-only.

📋 Development Notes

Note

The NSO configuration file is named ncs.conf.xml (instead of ncs.conf) to enable proper XML syntax highlighting in editors.

• During container build, it's copied to the correct location as ncs.conf.
• All scripts in deploy-to-sandbox/ are designed to be executed in the sandbox environment.
• The project supports both Docker and Podman container engines.

📞 Support

For sandbox-related issues, visit the DevNet Sandbox community.

For NSO-specific questions, refer to the NSO Developer Hub.