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.
This chapter contains the following sections:
Installing Cisco XNC
There is no direct upgrade path from Cisco XNC Release 1.0 to Cisco XNC Release 1.6. If you have Cisco XNC Release 1.0 installed and you want to update to Cisco XNC Release 1.6, you must first upgrade to Cisco XNC Release 1.5. See the Cisco Extensible Network Controller Deployment Guide, Release 1.5for the procedure.
Step 1 | In a web browser, navigate to Cisco.com. | ||||||
Step 2 | Under Support, click All Downloads. | ||||||
Step 3 | In the center pane, click Cloud and Systems Management. | ||||||
Step 4 | If prompted, enter your Cisco.com username and password to log in. | ||||||
Step 5 | In the right pane, click Network Controllers and Applications, and then click Cisco Extensible Network Controller (XNC). | ||||||
Step 6 | Download the Cisco XNC application bundle and any additional applications that you have purchased. | ||||||
Step 7 | Create a directory
in your Linux machine where you plan to install
Cisco
XNC.
For example, in your Home directory, create CiscoXNC. | ||||||
Step 8 | Copy the Cisco XNC zip file into the directory that you created. | ||||||
Step 9 | Unzip the
Cisco
XNC zip file.
The Cisco XNC software is installed in a directory called xnc. The directory contains the following:
|
You can use the upgrade command to upgrade a Cisco XNC Release 1.5 installation to Cisco XNC Release 1.6. This upgrade is called an in-place upgrade, which means that the product bits are replaced. A backup archive is created to restore your original installation, if necessary.
When you execute the upgrade command, the installation and the configuration are upgraded. However, any changes you made to the shell scripts or configuration files, for example,runxnc.sh and config.ini, are overwritten. After you complete the upgrade process, you must manually reapply your changes to those files.
Step 1 | In a web browser, navigate to Cisco.com. | ||||||||||||||||||
Step 2 | Under Support, click All Downloads. | ||||||||||||||||||
Step 3 | In the center pane, click Cloud and Systems Management. | ||||||||||||||||||
Step 4 | In the right pane, click Network Controllers and Applications, and then click Cisco Extensible Network Controller (XNC). | ||||||||||||||||||
Step 5 | Download the Cisco Extensible Network Controller (XNC) Release 1.6 application bundle and any additional applications that you currently have installed. | ||||||||||||||||||
Step 6 | Create a
temporary directory in your Linux machine where you plan to upgrade
Cisco
XNC.
For example, in your Home directory, create CiscoXNC_Upgrade. | ||||||||||||||||||
Step 7 | Extract the Cisco XNC Release 1.6 zip file into the temporary directory that you created. | ||||||||||||||||||
Step 8 | Navigate to the xnc directory that was created when you installed the Cisco XNC Release 1.5 software. | ||||||||||||||||||
Step 9 | Stop all running Cisco XNC Release 1.5 processes. | ||||||||||||||||||
Step 10 | Backup the Cisco XNC Release 1.5 installation using your standard backup procedures. | ||||||||||||||||||
Step 11 | Navigate to the xnc/bin directory in the temporary directory that you created for the Release 1.6 upgrade software. | ||||||||||||||||||
Step 12 | Upgrade the
application by entering the
./xnc upgrade --perform
--target-home {xnc_directory_to_be_upgraded}
[--verbose] [--backupfile
{xnc_backup_location_and_zip_filename}]
command.
You can use one of the following options:
| ||||||||||||||||||
Step 13 | Navigate to the xnc directory where you originally installed Cisco XNC. | ||||||||||||||||||
Step 14 | Start the
Cisco
XNC processes
that you previously stopped.
| ||||||||||||||||||
Step 15 | If you have
any upgrade-related issues, perform the following tasks:
|
You must purchase additional Cisco XNC applications and download the .zip files from Cisco.com. We recommend that you backup your configuration before you install new applications.
Step 1 | Open a command window where you installed Cisco XNC. |
Step 2 | Navigate to the xnc directory that was created when you installed the software. |
Step 3 | Verify that XNC is
running by entering the
./runxnc.sh
-status command.
The controller outputs the following, which indicates that the controller is running the Java process with PID 21680: Controller with PID:21680 -- Running! |
Connect the switches to the controller. For more information, see the configuration guide for your switches.
Managing TLS Certificate, KeyStore, and TrustStore Files
![]() Note | To support onePK devices, all connections to Cisco XNC that use onePK or OpenFlow agents require Transport Layer Security (TLS). |
Enabling the TLS connections between Cisco XNC and the OpenFlow or onePK switches requires TLS KeyStore and TrustStore files. The TLS KeyStore and TLS TrustStore files are password protected.
Cisco Nexus 3000 and 3100 Series switches require additional credentials, including Private Key, Certificate, and Certificate Authority (CA).
If TLS connections are required in your Cisco XNC implementation, all of the connections in the network must be TLS encrypted, and you must run Cisco XNC with TLS enabled (see Starting Cisco XNC with TLS Enabled). After Cisco XNC is started with TLS, you must run the TLS KeyStore password configuration command (see Providing the TLS KeyStore and TrustStore Passwords) to provide the passwords for Cisco XNC to unlock the KeyStore files.
OpenFlow and Cisco onePK switches require cryptographic configuration to enable TLS.
![]() Caution | Self-signed certificates are appropriate only for testing in small deployments. For additional security, as well as more granular controls over individual certificate use and revocation, you should use certificates generated by your organization's Certificate Authority. In addition, you should never use the keys and certificates generated by this procedure in a production environment. |
Ensure that OpenSSL is installed on the Linux host where these steps will be performed.
Step 1 | Create a TLS
directory, and then navigate to it:
mkdir -p TLS cd TLS |
Step 2 | Create three
directories under
mypersonalca and two prerequisite files:
mkdir -p mypersonalca/certs mkdir -p mypersonalca/private mkdir -p mypersonalca/crl echo "01" > mypersonalca/serial touch mypersonalca/index.txt |
Step 3 | Create the CA
configuration file (ca.cnf).
The following is an example of the content of the ca.cnf file: [ ca ] default_ca = mypersonalca [ mypersonalca ] # # WARNING: if you change that, change the default_keyfile in the [req] section below too # Where everything is kept dir = ./mypersonalca # Where the issued certs are kept certs = $dir/certs # Where the issued crl are kept crl_dir = $dir/crl # database index file database = $dir/index.txt # default place for new certs new_certs_dir = $dir/certs # # The CA certificate certificate = $dir/certs/ca.pem # The current serial number serial = $dir/serial # The current CRL crl = $dir/crl/crl.pem # WARNING: if you change that, change the default_keyfile in the [req] section below too # The private key private_key = $dir/private/ca.key # private random number file RANDFILE = $dir/private/.rand # The extentions to add to the cert x509_extensions = usr_cert # how long to certify for default_days = 365 # how long before next CRL default_crl_days= 30 # which md to use; people in comments indicated to use sha1 here default_md = sha1 # keep passed DN ordering preserve = no # Section names policy = mypolicy x509_extensions = certificate_extensions [ mypolicy ] # Use the supplied information commonName = supplied stateOrProvinceName = optional countryName = optional emailAddress = optional organizationName = optional organizationalUnitName = optional [ certificate_extensions ] # The signed certificate cannot be used as CA basicConstraints = CA:false [ req ] # same as private_key default_keyfile = ./mypersonalca/private/ca.key # Which hash to use default_md = sha1 # No prompts prompt = no # This is for CA subjectKeyIdentifier=hash authorityKeyIdentifier=keyid:always,issuer string_mask = utf8only basicConstraints = CA:true distinguished_name = root_ca_distinguished_name x509_extensions = root_ca_extensions [ root_ca_distinguished_name ] # EDIT THOSE commonName = Controller stateOrProvinceName = Mass countryName = US emailAddress = root_ca_userid@cisco.com organizationName = Cisco [ root_ca_extensions ] basicConstraints = CA:true |
Create the TLS certificate file.
Complete the steps in Preparing to Generate the TLS Credentials.
Step 1 | Generate the
TLS private key and Certification Authority (CA) files by entering the
openssl req -x509 -nodes
-days 3650 -newkey rsa:2048 -out mypersonalca/certs/ca.pem -outform PEM -keyout
mypersonalca/private/ca.key
command.
This step generates the TLS private key in PEM format with a key length of 2048 bits, and the CA file. | ||
Step 2 | Generate the
certificate key and certificate request files by entering the
openssl req -newkey rsa:2048
-keyout cert.key -keyform PEM -out cert.req -outform PEM
command.
This step
generates the controller key (cert.key) and certificate request (cert.req)
files in PEM format.
| ||
Step 3 | Generate the
certificate file by entering the
openssl ca -batch -notext -in
cert.req -out cert.pem -config ca.cnf
command.
This step
generates the certificate (cert.pem) file in PEM format using the certificate
request (cert.req) and the certificate configuration (ca.cnf) files as inputs,
and creates the certificates file (cert.pem) as output.
The following is an example of the console response: Using configuration from ca.cnf Check that the request matches the signature Signature ok The Subject's Distinguished Name is as follows countryName :PRINTABLE:'AU' stateOrProvinceName :ASN.1 12:'Some-State' organizationName :ASN.1 12:'Internet Widgits Pty Ltd' commonName :ASN.1 12:'localhost' |
Generate and import the certificate files on your Cisco Nexus 3000 or 3100 Series switch.
Create the TLS certificate.
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 | switch(config)# ip domain-name domain-name |
Configures the domain name for the switch. | ||
Step 2 | switch(config)# crypto key generate rsa label myKey2 exportable modulus 2048 |
Generates the cryptographic key. | ||
Step 3 | switch(config)# crypto ca trustpoint myCA |
Enters the trustpoint configuration mode and installs the trustpoint file on the switch. | ||
Step 4 | switch(config-trustpoint)# rsakeypair myKey2 |
Installs the key files on the switch. | ||
Step 5 | switch(config-trustpoint)# exit |
Exits trustpoint configuration mode. | ||
Step 6 | switch# show crypto ca trustpoints | (Optional)
Verifies creation of the trustpoint files. | ||
Step 7 | switch# show crypto key mypubkey rsa | (Optional)
Verifies creation of the key files. | ||
Step 8 | From the console, enter the cat mypersonalca/certs/ca.pem command. |
Displays the certificate file on the machine hosting the generated TLS certificates. | ||
Step 9 | switch(config)# crypto ca authenticate myCA |
Copies the CA certificate (ca.pem) to the switch to use as input.
| ||
Step 10 | switch(config)# crypto ca enroll myCA |
Generates the certificate request on the switch. | ||
Step 11 | From the console, enter the openssl ca -in n3k-cert.req -out newcert.pem -config ./ca.cnf command. |
Copies the certificate request from the switch to the file n3k-cert.req on your Linux machine, and then uses it to generate the switch certificate. | ||
Step 12 | switch(config)# crypto ca import myCA certificate |
Copies the certificate (newcert.pem) to the switch. | ||
Step 13 | From the console, enter the cat newcert.pem command. |
Displays the certificate on the Linux console. | ||
Step 14 | switch# show crypto ca certificates |
Displays the certificates on the switch. |
Enable TLS for Cisco onePK and OpenFlow switches.
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 | switch(config)# onep |
Enters onePK configuration mode on the switch. | ||
Step 2 | switch(config-onep)# transport type tls |
Enables TLS for onePK switches. | ||
Step 3 | switch# exit |
Exits onePK configuration mode. | ||
Step 4 | switch# show onep status | (Optional)
Displays the onePK configuration. | ||
Step 5 | switch(config)# openflow |
Enters OpenFlow agent configuration mode on the switch. | ||
Step 6 | switch(config-ofa)# switch 1 |
Enters OpenFlow agent configuration mode for switch 1. | ||
Step 7 | switch(config-ofa)# tls trust-point local myCA remote myCA |
Enables TLS certificate authority on the switch. | ||
Step 8 | switch(config-ofa-switch)# pipeline {201} |
Configures the pipeline. Enter 201 for Cisco Nexus 3000 and 3100 Series switches. | ||
Step 9 | switch(config-ofa-switch)# controller ipv4 {A.B.C.D} port 6653 vrf management security tls |
Enables TLS for OpenFlow switches. A.B.C.D is the IP address of the controller.
|
Create the TLS KeyStore file.
![]() Note | The TLS KeyStore file should be placed in the configuration directory of Cisco XNC. |
Complete the steps in Configuring the Cryptographic Keys on the Switch.
Step 1 | Copy cert.key to
xnc-privatekey.pem.
This command copies the cert.key file that was generated in the "Creating the TLS Private Key, Certificate, and Certificate Authority" section. This file contains the Cisco XNC private key. | ||
Step 2 | Copy
mpersponal/certs/cert.pem to xnc-cert.pem.
This command makes a copy of the cert.pem file that was generated in the "Creating the TLS Private Key, Certificate, and Certificate Authority" section. This file contains the Cisco XNC certificate. | ||
Step 3 | Create the xnc.pem file, which contains the Cisco XNC private key and certificate, by entering the cat xnc-privatekey.pem xnc-cert.pem > xnc.pem command. | ||
Step 4 | Convert the PEM file xnc.pem to the PKCS#12 file xnc.p12 file by entering the openssl pkcs12 -export -out xnc.p12 -in xnc.pem command. | ||
Step 5 | Enter a password
at the prompt.
The xnc.pem file is converted to a password-protected .p12 file. | ||
Step 6 | Convert the
xnc.p12 to a Java KeyStore (tslTrustStore) file by entering the
keytool -importkeystore
-srckeystore xnc.p12 -srcstoretype pkcs12 -destkeystore tlsKeyStore
-deststoretype jks command.
This command converts the xnc.p12 file to a password-protected tlsTrustStore file | ||
Step 7 | Enter a password
at the prompt.
|
![]() Note | The TLS TrustStore file should be placed in the configuration directory of Cisco XNC. |
Step 1 | Copy the ca.pem file to sw-cacert.pem. | ||
Step 2 | Convert the sw-cacert.pem file to a Java TrustStore (tlsTrustStore) file by entering the keytool -import -alias swca1 -file xnc-cert.pem -keystore tlsTrustStore command. | ||
Step 3 | Enter a password
at the prompt.
The xnc-cert.pem file is converted into a password-protected Java TrustStore (tlsTrustStore) file.
| ||
Step 4 | If the switches in your network use more than one CA certificate, repeat Step 1 through Step 3 for each CA certificate required. |
The TLS KeyStore and TrustStore passwords are sent to the Cisco Extensible Network Controller (XNC) so that it can read the password-protected TLS KeyStore and TrustStore files.
Step 1 | Open a command window where you installed Cisco XNC. |
Step 2 | Navigate to the xnc/bin directory. |
Step 3 | Provide the TLS KeyStore and TLS TrustStore passwords by entering the ./xnc config-keystore-passwords [--user {user} --password {password} --url {url} --verbose --prompt --keystore-password {keystore_password} --truststore-password {truststore_password}] command. |
Step 4 | Enter the following information: |
You must log into the Cisco XNC GUI using HTTPS.
Configuring Cisco XNC
Cisco Extensible Network Controller (XNC) supports high availability clustering in active/active mode with up to five controllers. To use high availability clustering with Cisco XNC, you must edit the config.ini file for each instance of Cisco XNC.
Step 1 | Ensure that Cisco XNC is not running on any of the instances in the cluster. |
Step 2 | Open a command window on one of the instances in the cluster. |
Step 3 | Navigate to the xnc/configuration directory that was created when you installed the software. |
Step 4 | Use any text editor to open the config.ini file. |
Step 5 | Locate the
following text:
# HA Clustering configuration (colon-separated IP addresses of all controllers that are part of the cluster.) # supernodes=<ip1>:<ip2>:<ip3>:<ipn> |
Step 6 | Remove the
comments on the # supernodes line, and replace
<ip1>:<ip2><ip3>:<ipn> with the IP addresses for each
instance of
Cisco
XNC in the cluster. You can enter from two to five IP addresses.
Example: # HA Clustering configuration (colon-separated IP addresses of all controllers that are part of the cluster.) supernodes=10.1.1.1:10.2.1.1:10.3.1.1:10.4.1.1:10.5.1.1 |
Step 7 | Save the file and exit the editor. |
Step 8 | Repeat Step 3 through Step 7 for each instance of Cisco XNC in the cluster. |
Step 9 | Restart Cisco XNC. |
You can password protect your HA clusters with the xncjgroups.xml file. This file must be exactly the same for each instance of Cisco Extensible Network Controller (XNC).
Step 1 | Ensure that Cisco XNC is not running on any of the instances in the cluster. |
Step 2 | Open a command window on one of the instances in the cluster. |
Step 3 | Navigate to the xnc/configuration directory. |
Step 4 | Use any text editor to open the xncjgroups.xml file. |
Step 5 | Locate the
following text:
<!-- <AUTH auth_class="org.jgroups.auth.MD5Token" auth_value="ciscoXNC" token_hash="MD5"></AUTH> --> |
Step 6 | Remove the
comments from the AUTH line.
Example: <AUTH auth_class="org.jgroups.auth.MD5Token" auth_value="ciscoXNC" token_hash="MD5"></AUTH> |
Step 7 | (Optional)Change the password in the auth_value attribute. By default, the cluster is protected with the password "ciscoXNC". You can change this password to whatever value you want, if you make the same change on all machines in the cluster. |
Step 8 | Save the file and exit the editor. |
Step 9 | Repeat Step 4 through Step 8 for each instance of Cisco XNC in the cluster. |
Step 10 | Restart Cisco XNC. |
The following configuration settings can improve scalability when connecting to Cisco Nexus 3000 or 3100 Series switches.
Step 1 | Navigate to the xnc/configuration directory that was created when you installed the software. | ||||||||||||||||||||||||||||||||||||||
Step 2 | Use any text editor to open the config.ini file. | ||||||||||||||||||||||||||||||||||||||
Step 3 | Update the
following parameters:
| ||||||||||||||||||||||||||||||||||||||
Step 4 | Save the file and exit the editor. | ||||||||||||||||||||||||||||||||||||||
Step 5 | Restart Cisco XNC. |
Step 1 | Open a command window where you installed Cisco XNC. |
Step 2 | Navigate to the xnc/bin directory that was created when you installed the software. |
Step 3 | Back up the
configuration by entering the
./xnc config --backup
command.
The --backup option creates a backup archive (in .zip format) of the startup configuration in the current xnc distribution. The backup archive is stored in {xncHome}/backup/. A new archive is created each time that the backup command is entered using a filename with the current timestamp. |
Step 4 | Restore the
configuration by entering the
./xnc config --restore
--backupfile {zip_filename} command.
The --restore option restores the startup configuration of the current xnc distribution from an existing backup archive. The restore action requires the absolute path of the backup archive. |
Step 5 | If you are restoring a configuration, stop and restart Cisco XNC for the restored configuration to take effect. |
![]() Note | The controller may or may not be running when this command is used. If the controller is not running, the password reset takes effect the next time that it is run. |
Step 1 | Open a command window where you installed Cisco XNC. | ||
Step 2 | Navigate to the xnc/bin directory that was created when you installed the software. | ||
Step 3 | Reset the
administrative password by entering the
./xnc
reset-admin-password [--wait-seconds
{wait_time}
--password
{password}]
command.
Resets the admin password to the default or specified password by restarting the user manager.
|
Ensure that your Cisco Extensible Network Controller (XNC) application is stopped before proceeding.