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

KVM deployment for Cisco Optical Network Controller in Geo-HA mode

Updated: May 7, 2026

Want to summarize with AI?

This section explains what a KVM-based Geo-HA installation includes, why the deployment uses three nodes, and what information you must prepare before installation.

A KVM-based Geo-HA installation deploys Cisco Optical Network Controller as three KVM virtual machines that operate as an active worker node, a standby worker node, and a witness node.

The deployment uses a QCOW2 image for each VM and a cloud-init ISO that provides node-specific configuration.
Each node uses control plane, northbound, and eastbound network interfaces.
The worker nodes use BGP so that traffic can be routed to the northbound virtual IP from different locations.

In the Geo-HA 1+1+1 topology, the witness node participates in cluster coordination while the active and standby worker nodes provide service continuity across sites.

What to prepare before you start

Before starting the Geo-HA installation workflow, gather the values and files required to create the configuration for each node.

You need the QCOW2 image, VM sizing values, deployment directory, and bridge names for the three KVM VMs.
You should gather the host names, control-plane, northbound, and eastbound IP addresses, DNS values, and the shared northbound virtual IP.

Use the Geo-HA installation topics to create the cloud-init files, deploy the VMs, configure BGP, join the nodes, and verify the installation.

Configure networks for Geo-HA deployment

Create the libvirt network definitions required Cisco Optical Network Controller 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 sufficient. In a Geo-HA deployment, use separate networks for the required UCS servers.

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 files named eastbound1.xml, eastbound2.xml, and eastbound3.xml on the respective UCS servers. The eastbound networks can be public networks. 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>` Example for eastbound2.xml. `<network> <name>eastbound1</name> <forward mode='none'/> <bridge name='virbr-east1'/> <ip address='172.10.10.2' netmask='255.255.255.0'/> </network>` Example for eastbound3.xml. `<network> <name>eastbound1</name> <forward mode='none'/> <bridge name='virbr-east1'/> <ip address='172.10.10.3' 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. The northbound network can be a public network.
	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.

Install Cisco Optical Network Controller using KVM in Geo-HA mode

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

Before you begin

Before you begin, Prepare KVM configuration files for Geo-HA.

Procedure

	1.	Create the KVM virtual machines. See Create KVM virtual machines for Geo-HA nodes.
	2.	Configure BGP on the worker nodes. See Configure BGP on the Geo-HA nodes.
	3.	Join the active worker, standby worker, and witness nodes. See Join the Geo-HA nodes.
	4.	Activate the deployment and verify access. See Activate and verify Geo-HA.
	5.	Review the installed applications if required. See View installed applications.
	6.	Continue with network onboarding tasks. See Add network adapters and discover network devices.

Cisco Optical Network Controller is installed on KVM in Geo-HA mode.

Prepare KVM configuration files for Geo-HA deployment

Prepare the cloud-init configuration used to deploy Cisco Optical Network Controller on KVM in a Geo-HA 1+1+1 topology.

Before you begin

Perform this procedure for three VMs: the active worker node, the standby worker node, and the arbitrator node.
Have the node names, IP addresses, virtual IP, join token, DNS values, and BGP settings available before you create the files.

Procedure

	1.	Create the SSH public-key file by following the steps at Create the meta-data file for a Geo-HA node.
	2.	Create the network configuration file by following the steps at Create the network-config file for a Geo-HA node.
	3.	Create the cluster and user settings file by following the steps at Create the user-data file for a Geo-HA node.

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

What to do next

Create KVM virtual machines for Geo-HA nodes.

Create the meta-data file for a Geo-HA node

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

Procedure

	1.	Create a file named meta-data.
	2.	Add the instance ID and the SSH public key for the node. Meta-data file syntax: `instance-id: <instance_id> local-hostname: <node_name> public-keys: - <ssh_public_key>` Use the public key that matches the private key you plan to use for SSH access after the VM boots.

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

Meta-data file example

instance-id: iid-nxf-kvm-01
local-hostname: nxf-kvm-01
public-keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKAn33NZjrMWyMJpf7QvrD4vCvEAg4PPdpb3UFXXXXXX

Create the network-config file for a Geo-HA node

Create the network-config file that defines the 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 Geo-HA node.

network-config file syntax

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 Geo-HA node

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

Procedure

Create a file named user-data.

Add the base cloud-init content for the data disk, the optional NTP servers and the Geo-HA 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

Set clusterIndex to 1 for the active worker node, 2 for the standby worker node, and 3 for the witness node. Set clusterRole to worker for the worker nodes and arbitrator for the witness node.

The user-data file is ready to be included in the cloud-init ISO for the 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 KVM virtual machines for Geo-HA nodes

Deploy the three KVM virtual machines that host the Geo-HA nodes for Cisco Optical Network Controller.

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

Before you begin

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

Ensure that each VM uses a unique QCOW2 filename.

Procedure

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

Use a deployment directory such as <PATH_TO_DEPLOY_DIR>/vmConfig/cloud-config/.

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/"

The control-plane network is mandatory even though it is not used for east-west Geo-HA traffic in the 1+1+1 deployment.

This sample shows the syntax of the virt-install command.

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 Geo-HA node 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 nxf-kvm-01   \
  --vcpus 32   \
  --memory 131072   \
  --disk path=/var/lib/libvirt/images/VMs/nxf-kvm-01/CONC-26.1.1.qcow2,format=qcow2   \
  --disk path=/var/lib/libvirt/images/VMs/nxf-kvm-01/CONC-26.1.1-data.qcow2,size=2500,device=disk,bus=virtio,format=qcow2   \
  --disk path=/var/lib/libvirt/images/VMs/nxf-kvm-01/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

Configure BGP on the Geo-HA nodes.

Configure BGP on the Geo-HA nodes

Initialize and verify BGP on the Region 1 and Region 2 worker nodes so that traffic can be routed to the Cisco Optical Network Controller northbound virtual IP from the different sites in the Geo-HA topology.

Before you begin

Deploy the VMs by following Create KVM virtual machines for Geo-HA nodes.
Have the SSH private key that corresponds to the public key defined in the meta-data file.

Procedure

Verify SSH access to each worker node.

Example:

ssh -i <private-key-file> nxf@<hco_management_ip>

If you are prompted for a password, verify the key configuration. If the command times out, verify the IP configuration.

Initialize BGP and add the BGP router on the Region 1 worker node.

Example:

sedo ha bgp init <region1_node_name> <region1_northbound_ip> <BGP_AS_1>
sedo ha bgp router add <region1_node_name> <region1_northbound_gateway> <BGP_AS> <BGP_session_password>

Initialize BGP and add the BGP router on the Region 2 worker node, and then verify the router entries on both worker nodes.

Example:

sedo ha bgp init <region2_node_name> <region2_northbound_ip> <BGP_AS_2>
sedo ha bgp router add <region2_node_name> <region2_northbound_gateway> <BGP_AS> <BGP_session_password>
sedo ha bgp router list <region1_node_name>
sedo ha bgp router list <region2_node_name>

SSH access is confirmed and BGP is configured on the Region 1 and Region 2 worker nodes.

What to do next

Join the Geo-HA nodes.

Join the Geo-HA nodes

Join the Region 1 worker, Region 2 worker, and witness nodes into a Geo-HA 1+1+1 topology.

Before you begin

Verify that BGP is configured on the worker nodes. For details, see Configure BGP on the Geo-HA nodes.

Procedure

	1.	Run the following command on each node and record the `CLUSTER_ID` value. Example: `sudo sedo supercluster status`
	2.	On the Region 1 node, generate the join command for the Region 2 node. Example: `sudo sedo supercluster wait-for -b <region1_node_eastboundIP>:10443 <region2_node_CLUSTER_ID>`
	3.	On the Region 2 node, run the command generated in the previous step.
	4.	On the Region 1 node, generate the join command for the witness node. Example: `sudo sedo supercluster wait-for -b <region1_node_eastboundIP>:10443 <region3_node_CLUSTER_ID>`
	5.	On the witness node, run the command generated in the previous step.
	6.	On the Region 2 node, generate the join command for the witness node. Example: `sudo sedo supercluster wait-for -b <region2_node_eastboundIP>:10443 <region3_node_CLUSTER_ID>`
	7.	On the witness node, run the command generated in the previous step.
	8.	Run the following command on each node to view the peers. Example: `sudo sedo supercluster status`
	9.	Run the following command to verify Geo-HA connectivity. Example: `sudo sedo supercluster connectivity`

The active worker, standby worker, and witness nodes are joined into the Geo-HA topology.

What to do next

Activate and verify Geo-HA.

Activate and verify Geo-HA

Activate the Geo-HA topology after all three nodes have joined, verify the deployment state, and complete the initial security and access tasks.

Before you begin

Verify that the three nodes have joined successfully. For details, see Join the Geo-HA nodes.

Procedure

	1.	In Region 1, start the Geo-HA deployment. This operation can take a few minutes. Example: `sudo sedo supercluster start Checking Supercluster connectivity...Passed Initiating Supercluster...Done`
	2.	After the connectivity check succeeds, verify that the Geo-HA deployment is started. Example: sudo sedo supercluster status ┌───────────────────────────────────────────────────────────────────────────────────────┐ │ Supercluster Status │ ├──────────────────┬────────────────────────────────────────────────────────────────────┤ │ Cluster ID │ qYfNdRnsPIQWFFhz7KMFLiKZV3OD6rGrfmrUtbMGKk │ │ Cluster Name │ cluster2 │ │ Cluster Role │ worker │ │ Peers │ cluster1 (worker, sgHMamJznknIncWnHp5zda7rPkrt1DepMjqWToNviCc) │ │ │ cluster3 (arbitrator, Ma9nBKkW0GOXzWc3gVjqOjNBNC8oL29SvowBifu36QA) │ │ Mode │ Running │ │ Current Active │ cluster1 │ │ Previous Active │ │ │ Standby Clusters │ cluster2 │ │ Last Switchover │ │ │ Last Failover │ │ │ Last Seen │ controller-0.cluster3: 2024-09-21 12:35:03.073 +0000 UTC │ │ │ controller-0.cluster2: 2024-09-21 12:35:03.109 +0000 UTC │ │ Last Peer Error │ │ │ DB Replication │ connecting │ │ DB Lag │ │ └──────────────────┴────────────────────────────────────────────────────────────────────┘
	3.	Review the BGP state. Example: `sedo ha bgp show`
	4.	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.
	5.	Configure additional local users if required. For more information, see Add local users to Cisco Optical Network Controller.
	6.	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 and the Geo-HA deployment is active.

Image verification for Cisco Optical Network Controller

Image verification for qcow2 and system pack packages is the process of validating the certificate and signature that are provided with a Cisco Optical Network Controller image before installation or upgrade.

qcow2 and system pack packages include the image file, certificate, signature, verification script, and README so that you can verify the package manually.
A successful verification confirms that the downloaded image is signed by Cisco and can be used for installation or upgrade.

Cisco Optical Network Controller image types and verification methods

This reference lists the image types supported by Cisco Optical Network Controller. It describes the verification method for each delivery format. It also specifies the files provided in signed qcow2 and system pack packages.

Table 1. Supported image types and verification methods
Image type	Delivery format	Verification method	When to verify
VMware image	OVA	Verify the publisher information during the vSphere Deploy OVF Template workflow.	Before you complete the OVA deployment.
KVM image	Signed qcow2 package	Extract the package and run the Python verification script.	Before you copy or use the qcow2 image.
Upgrade image	Signed system pack package	Extract the package and run the Python verification script.	Before you copy the system pack file to the Cisco Optical Network Controller node.

Table 2. Files in a signed qcow2 or system pack package
File	Typical extension or name	Purpose	Usage
Image file	`.qcow2` or `.tar.gz`	Contains the software image that you deploy or upgrade.	Use this file only after verification succeeds.
Certificate file	`.pem`	Contains the public certificate that is used during verification.	Pass this file to the verification script.
Signature file	`.signature`	Contains the signature for the image file.	Pass this file to the verification script.
Verification script	`cisco_x509_verify_release.py3`	Runs certificate-chain and signature validation.	Execute the script from the extracted package directory.
README file	`CONC.readme`	Lists package requirements, command syntax, and example output.	Review this file before you run the verification command.

Verify a signed qcow2 or system pack image

Confirm the authenticity and integrity of signed qcow2 and system pack packages before deploying or upgrading Cisco Optical Network Controller.

Signed qcow2 and system pack packages include these files you can use to validate the image before deployment or upgrade:

a certificate,
a signature file,
a verification script, and
a README.

Before you begin

Ensure that Python 3.4 or later is installed. The system must support running openssl and grep command-line calls.
Download the signed qcow2 or system pack package from Software Download and extract it.
Review the requirements and command syntax listed in the CONC.readme file.

Follow these steps to verify a signed qcow2 or system pack image.

Procedure

	1.	Change to the directory that contains the extracted image verification files.
	2.	Open the `CONC.readme` file and review the requirements and command syntax.
	3.	Verify that the verification script has execute permission.
	4.	Run the verification script on the extracted image file. Use the certificate, image, and signature files that were included in the extracted package. `./cisco_x509_verify_release.py3 -e <certificate-file>.pem -i <image-file> -s <signature-file>.signature -v dgst --algo sha512 --failExpiredCerts`
	5.	Review the output and confirm that the verification completed successfully. A successful run verifies the certificate chain and ends with a message that states that the signature was verified successfully.

The qcow2 or system pack image is verified and ready to use.

This example command shows how to verify a qcow2 image.

./cisco_x509_verify_release.py3 -e 25.4.1-2.pem -i 25.4.1-2.tar.gz -s 25.4.1-2.signature -v dgst --algo sha256 --failExpiredCerts
25.4.1-2.pem expiration date is Jan 10 18:46:37 2099 GMT

CA chain genecc384 chosen based on finding '//www.cisco.com/security/pki/certs/cgsiscap384.cer' string in eecert
Using cert chain 'genecc384' (csircap384.cer and cgsiscap384.cer)
Retrieving rootCA certificate from https://www.cisco.com/security/pki/certs/csircap384.cer ...
Success in downloading https://www.cisco.com/security/pki/certs/csircap384.cer
Using downloaded rootCA cert /var/folders/nc/70t5lkk50mlfd95t3l2vq6_00000gn/T/tmp1pfoov5u/csircap384.cer
Retrieving subCA certificate from https://www.cisco.com/security/pki/certs/cgsiscap384.cer ...
Success in downloading https://www.cisco.com/security/pki/certs/cgsiscap384.cer
Using downloaded subCA cert /var/folders/nc/70t5lkk50mlfd95t3l2vq6_00000gn/T/tmp1pfoov5u/cgsiscap384.cer
csircap384.cer expiration date is Jan 10 18:46:39 2099 GMT

cgsiscap384.cer expiration date is Jan 10 18:46:38 2099 GMT

Successfully verified root, subca and end-entity certificate chain.
Decoded Base64 signature 25.4.1-2.signature → 25.4.1-2.signature.der
Successfully fetched a public key from 25.4.1-2.pem
Successfully verified the signature of 25.4.1-2.tar.gz using 25.4.1-2.pem

What to do next

Table 3. Next action after verification
If...	Then...
You verified a qcow2 image	Copy or place the qcow2 file where it is needed for the KVM installation workflow.
You verified a system pack image	Copy the extracted system pack file to the Cisco Optical Network Controller node and continue with the upgrade procedure.

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.