Cisco Optical Network Controller Installation Guide, Releases 26.x.x

KVM deployment for Cisco Optical Network Controller standalone mode

Updated: May 7, 2026

Want to summarize with AI?

Explains KVM-based standalone deployment, including KVM requirements, network configuration, cloud-init files, virtual machine creation, and access verification for Cisco Optical Network Controller.

A KVM-based standalone installation deploys Cisco Optical Network Controller as a single KVM virtual machine by using a QCOW2 image and a cloud-init ISO that contains the node configuration.

The deployment uses one VM with control-plane, northbound, and eastbound network interfaces.
The cloud-init ISO provides the meta-data, network-config, and user-data files that initialize the system.
The standalone deployment does not require Geo-HA node joining or BGP-based multi-site routing.

Although the control-plane network is not used for standalone service traffic, it must still be defined during KVM deployment.

What to prepare before you start

Before you begin the standalone installation workflow, gather the values and files required to create the VM configuration.

QCOW2 image, VM sizing values, deployment directory, and KVM bridge names for the standalone VM.
Host name, control-plane, northbound, and eastbound IP addresses, DNS values, and the northbound virtual IP.
SSH key pair and the cloud-init values required for the standalone node definition and local users.

Use the standalone installation topics to create the cloud-init files, deploy the VM, verify system status, secure the admin account, and continue with post-installation setup.

KVM deployment requirements

This section lists the software requirements, hardware requirements, and network information for deploying Cisco Optical Network Controller on a KVM host.

Software requirements

This table lists the software and access requirements for the KVM deployment.

Table 1. KVM software requirements
Requirement	Description
`libvirt-client` and `qemu-kvm`	Install these packages on the KVM host.
`cloud-utils`	Use this package to create the cloud-init ISO.
`wget` or `curl`	Use one of these utilities to download the OS image.
SSH key pair	Use the SSH key pair to access the virtual machine.

Hardware requirements

This table lists the host infrastructure requirements for the KVM deployment.

Table 2. KVM hardware requirements
Requirement	Description
KVM host	Use RHEL 8.x or later with KVM and libvirt installed.
UEFI support	Install the OVMF firmware packages on the host.
Storage	Provide at least 100 GB of available disk space.
Memory	Provide at least 16 GB of available RAM.
CPU	Provide at least 8 vCPUs.

Configure networks for standalone deployment

Create the libvirt network definitions required Cisco Optical Network Controller standalone deployment on a KVM host.

Before you begin

Log in to the KVM host with privileges to create libvirt network definitions.
Choose a working directory to store the network XML files.

In a standalone deployment, one eastbound network and one control-plane network are required.

Procedure

	1.	Create the control-plane network definition in a file. The control plane network can be a private network. Example: Example for control.xml `<network> <name>control</name> <forward mode='none'/> <bridge name='virbr-control'/> <ip address='192.168.1.1' netmask='255.255.255.0'/> </network>`
	2.	Create the eastbound network definitions in file named eastbound.xml. The eastbound network can be a private network. Example: Example for eastbound1.xml. `<network> <name>eastbound1</name> <forward mode='none'/> <bridge name='virbr-east1'/> <ip address='172.10.10.1' netmask='255.255.255.0'/> </network>`
	3.	Specify the default northbound interface using the <NORTHBOUND_BRIDGE> parameter for northbound connectivity when running the virt-install command. For example, use bridge0 as the value for <NORTHBOUND_BRIDGE> to assign the northbound interface during deployment.
	4.	Define, start, and enable each network at boot. Example: `virsh net-define <network-file.xml> virsh net-start <network-name> virsh net-autostart <network-name>`
	5.	Verify that all required networks are available. Example: `virsh net-list --all` The network list shows the defined networks and their current state.

The control-plane and eastbound networks are configured and available for KVM deployment.

Install Cisco Optical Network Controller using KVM in standalone mode

Use this supertask to complete the full KVM-based standalone installation workflow for Cisco Optical Network Controller.

Before you begin

Prepare KVM configuration files for standalone deployment.

Procedure

	1.	Create the KVM virtual machine. See Create a KVM virtual machine for standalone deployment.
	2.	Verify the deployment and access the web UI. See Verify and access the standalone deployment.

Cisco Optical Network Controller is installed on KVM in standalone mode.

Prepare KVM configuration files for standalone deployment

Prepare the cloud-init configuration used to deploy Cisco Optical Network Controller on KVM as a standalone instance.

Before you begin

Perform this procedure for one VM.
Have the host name, IP addresses, virtual IP, DNS values, and SSH public key available before you create the files.

Procedure

	1.	Create the SSH public-key file by following Create the meta-data file for a standalone node.
	2.	Create the network definition by following Create the network-config file for a standalone node.
	3.	Create the cluster and user settings by following Create the user-data file for a standalone node.

The cidata.iso file is created and is ready to be attached when you deploy the standalone Cisco Optical Network Controller VM.

What to do next

Create a KVM virtual machine for standalone deployment.

Create the meta-data file for a standalone node

Create the meta-data cloud-init file for a standalone Cisco Optical Network Controller node.

Procedure

	1.	Create a file named meta-data.
	2.	Add the instance ID, local host name, and SSH public key. Meta-data file syntax: `instance-id: <instance_id> local-hostname: <node_name> public-keys: - <ssh_public_key>`

The meta-data file is ready to be included in the cloud-init ISO.

Meta-data file example

instance-id: iid-conc-sa-kvm-1
local-hostname: conc-sa-kvm-1
public-keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKAn33NZjrMWyMJpf7QvrD4vCvEAg4PPdpb3UFXXXXXX

Create the network-config file for a standalone node

Create the network-config file that defines the standalone node IP addresses, default gateway, and DNS settings.

Procedure

Create a file named network-config.

Define the control-plane, northbound, and eastbound interfaces.

network-config file syntax.

version: 2
ethernets:
  enp1s0:
    dhcp4: <false-or-true>
    addresses:
      - <control_plane_ip/subnet_mask>
  enp2s0:
    dhcp4: <false-or-true>
    addresses:
      - <northbound_ip/subnet_mask>
    gateway4: <gateway_ip>
    nameservers:
      addresses:
        - <dns_server_ip>
  enp3s0:
    dhcp4: <false-or-true>
    addresses:
      - <eastbound_ip/subnet_mask>

The network-config file is ready for use by the standalone node.

network-config file example

version: 2
ethernets:
  enp1s0:
    dhcp4: false
    dhcp6: false
    addresses:
      - 192.168.119.10/24
  enp2s0:
    dhcp4: false
    dhcp6: false
    addresses:
      - 10.58.231.119/22
    gateway4: 10.58.228.1
    nameservers:
      addresses:
        - 144.254.71.184
  enp3s0:
    dhcp4: false
    dhcp6: false
    addresses:
      - 172.10.10.10/24

Create the user-data file for a standalone node

Create the user-data cloud-init file for a standalone Cisco Optical Network Controller node.

Procedure

Create a file named user-data.

Add the base cloud-init content for the data disk, optional NTP servers, and the standalone cluster configuration for the node.

user-data file syntax

fs_setup:
  - label: data
    device: /dev/vdb
    filesystem: ext4
mounts:
  - ["/dev/vdb", "/data"]
ntp:
  enabled: true
  ntp_client: chrony
  servers:
    - <ntp_server>
nxf:
  minControlPlaneCount: 1
  clusterIndex: <cluster_index>
  clusterName: <cluster_name>
  node:
    name: <node_name>
    initiator: <control_plane_ip>
    joinToken: <join_token>
    controlPlaneInterface: enp1s0
    eastboundInterface: enp3s0
    vip:
      northbound:
        interface: enp2s0
  initiator:
    vip:
      northbound:
        ip: <vip>
        type: L3
    kafka:
      enabled: true
    joinToken: <join_token>
    arbitratorNode: my-node3
    clusterRole: <worker-or-arbitrator>
    security:
      localUsers:
        - username: admin
          displayName: NxF Admin
          description: NextFusion Default Administrator
          locked: true
          mustChangePassword: false
          expiresInDays: 0
          access:
            - permission/admin

Use a valid DNS name for both clusterName and node_name.

The user-data file is ready to be included in the cloud-init ISO for the standalone node.

user-data file example

#cloud-config
#NxF User Data
fs_setup:
- label: data
  device: /dev/vdb
  filesystem: ext4

mounts:
- ["/dev/vdb", "/data"]
ntp:
  enabled: true
  ntp_client: chrony
  servers:
  - ntp.esl.cisco.com,10.58.228.1

nxf:
  minControlPlaneCount: 1
  clusterIndex: 1
  clusterName: cluster1
  node:
    name: node1
    #Should be same as control plane 
    initiator: 192.168.119.10
    joinToken: z9wfwl.ye6pmu6pr27aogjk
    controlPlaneInterface: enp1s0
    eastboundInterface: enp3s0
    vip:
      northbound:
        interface: enp2s0
  initiator:
    vip:
      northbound:
        ip: 10.58.231.119
        type: L3
    kafka:
      enabled: true
    joinToken: z9wfwl.ye6pmu6pr27aogjk
    arbitratorNode: node3
    #should be arbitrator for cluster3
    clusterRole: worker
    security:
      localUsers:
      - username: admin
        displayName: NxF Admin
        description: NextFusion Default Administrator
        locked: true
        mustChangePassword: false
        expiresInDays: 0
        access:
        - permission/admin

Create a KVM virtual machine for standalone deployment

Deploy a KVM virtual machine that hosts a standalone Cisco Optical Network Controller instance.

Run this task on the KVM host after you create the cidata.iso file for the standalone node.

Before you begin

Complete Prepare KVM configuration files for standalone deployment.
Verify the qcow image package before use. Each package contains all required files for verification. For detailed steps, see Verify a signed qcow2 or system pack image.

Use a unique QCOW2 filename for the VM.

Procedure

Copy the three configuration files to a designated folder and generate the ISO.

Example:

cp network-config user-data meta-data <PATH_TO_DEPLOY_DIR>/vmConfig/cloud-config/
mkisofs -o "<PATH_TO_DEPLOY_DIR>/vmConfig/cidata.iso" -r -J -V cidata "<PATH_TO_DEPLOY_DIR>/vmConfig/cloud-config/"

Deploy the standalone node by running the virt-install command with the values for that VM.

For the standalone and geo-ha deployment, specify bridge0 as the <NORTHBOUND_BRIDGE> bridge interface to connect to the northbound interface using the north bridge interface.

virt-install command syntax

virt-install \
--name <HOST_NAME> \
--vcpus <CPUs> \
--memory <MEMORY> \
--disk path=<PATH_TO_DEPLOY_DIR>/<QCOW2_FILE_NAME>.qcow2,format=qcow2 \
--disk path=<PATH_TO_DEPLOY_DIR>/<QCOW2_FILE_NAME>-data.qcow2,size=<SIZE>,device=disk,bus=virtio,format=qcow2 \
--disk path=<PATH_TO_DEPLOY_DIR>/vmConfig/cidata.iso,device=cdrom \
--osinfo debian12 \
--network bridge=<CONTROL_PLANE_BRIDGE>,model=virtio \
--network bridge=<NORTHBOUND_BRIDGE>,model=virtio \
--network bridge=<EASTBOUND_BRIDGE>,model=virtio \
--boot loader=/usr/share/edk2/ovmf/OVMF_CODE.fd,loader.readonly=yes,loader_secure=no,nvram.template=/usr/share/edk2/ovmf/OVMF_VARS.fd,hd,uefi \
--serial pty \
--console pty,target_type=serial \
--noautoconsole

Wait for the VM to finish booting. SSH access is available after the VM is started.

The standalone VM is created with the QCOW2 system disk, the data disk, the cloud-init ISO, and the required control-plane, northbound, and eastbound interfaces.

virt-install command example

virt-install   \
  --name conc-sa-kvm-1   \
  --vcpus 32   \
  --memory 131072   \
  --disk path=/var/lib/libvirt/images/VMs/conc-sa-kvm-1/CONC-26.1.1.qcow2,format=qcow2   \
  --disk path=/var/lib/libvirt/images/VMs/conc-sa-kvm-1/CONC-26.1.1-data.qcow2,size=2500,device=disk,bus=virtio,format=qcow2   \
  --disk path=/var/lib/libvirt/images/VMs/conc-sa-kvm-1/cidata.iso,device=cdrom   \
  --osinfo debian12   \
  --network bridge=virbr-control,model=virtio   \
  --network bridge=bridge0,model=virtio   \
  --network bridge=virbr-east1,model=virtio   \
  --boot loader=/usr/share/edk2/ovmf/OVMF_CODE.fd,loader.readonly=yes,loader_secure=no,nvram.template=/usr/share/edk2/ovmf/OVMF_VARS.fd,hd,uefi   \
  --serial pty   \
  --console pty,target_type=serial   \
  --autostart \
  --noautoconsole

What to do next

Verify and access the standalone deployment.

Verify and access the standalone deployment

Confirm that the standalone Cisco Optical Network Controller VM is operational and complete the initial access and security tasks.

Before you begin

Deploy the VM by following Create a KVM virtual machine for standalone deployment.

Procedure

	1.	Verify SSH access to the standalone VM. Example: `ssh -i <private-key_file> nxf@<hco_management_ip>` If you are not prompted for a password, there is probably a problem with the key. If the command times out, verify the IP setting.
	2.	Check the system status. Example: `sedo system status`
	3.	Change the default password and access string of the admin user. Example: `sedo security user set --access role/admin --password admin` You are prompted to enter the new password.
	4.	Configure additional local users if required. For more information, see Add local users to Cisco Optical Network Controller.
	5.	Open the Cisco Optical Network Controller web UI by browsing to the northbound virtual IP on port 8443. Example: `https://<northbound-virtual-ip>:8443/`

Cisco Optical Network Controller is installed on KVM as a standalone instance.

Need help?

Open a support case

(Requires a Cisco Service Contract)

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.