Cisco Catalyst 8000V Edge Software Installation And Configuration Guide

PDF

Day 0 Configuration Using Custom Data

Updated: March 5, 2026

Want to summarize with AI?

Log in

Overview

Explains how to perform day 0 configuration using custom data which automates the configuration steps and helps connect to on-premises sites.

After you download the Cisco Catalyst 8000V installation files and deploy the image in your environment, you must manually configure the Cisco Catalyst 8000V instance before the device is fully functional.

To automate the configuration steps or to connect to on-premises sites, upload the Cisco Catalyst 8000V custom data or user data to all the supported public and private clouds.

Summary

The Day 0 bootstrap file enables you to run Cisco IOS XE configuration commands, install Python packages in guestshell, run scripts in guestshell, and provide licensing information to boot the Cisco Catalyst 8000V instance with your chosen technology package.

By uploading the custom data for your cloud service provider or your private cloud, you can automate the Day 0 or bootstrap configuration. Upload or attach a bootstrap configuration file (iosxe_config.txt), or provide the user data to automate these processes and bring the device to a functional state with minimal intervention.

Workflow

To launch a Cisco Catalyst 8000V instance by using custom data, complete these steps.

  1. Configure the IOS configuration property.
  2. Configure the scripts property.
  3. Configure the scripts credential property.
  4. Configure the python package property.
  5. Configure the license property.
  6. Provide the Day 0 configuration file.

Before you get to each of these steps in detail, refer to the sample bootstrap files at https://github.com/csr1000v/customdata-examples.

Configure the IOS configuration property

To configure IOS properties for your Day 0 setup, use the IOS Configuration property as described in this sample configuration.

Section: IOS configuration 
hostname C8000V1
interface  GigabitEthernet1 
description “static IP address config” 
ip address 10.0.0.1 255.255.255.0 
interface GigabitEthernet2
description “DHCP based IP address config” 
ip address dhcp

After the line labeled Section: IOS configuration, enter the Cisco IOS XE configuration commands to be run on the Cisco Catalyst 8000V router.

When you run this command, the specified IOS configuration is applied to the Cisco Catalyst 8000V router on Day 0.

Configure scripts property

The Scripts property helps automate your deployment and enables other automation objectives. To run a Python or Bash script on Day 0 within the guestshell context, provide the public URL and arguments for the script in the Scripts property.

A script must include a shebang (!) character as the first line. This line tells Cisco IOS-XE which script interpreter (Python or Bash) to use for parsing the script. For example, the first line of a python script can contain #!/usr/bin/env python, while the first line of a bash script can contain #!/bin/bash. This line allows the Python or Bash script to run as executable code in a Linux environment.

When you execute the script, it runs in the guestshell container of the Cisco Catalyst 8000V instance. To access the guestshell container, use the guestshell EXEC mode command. For more information on guestshell commands, see the Programmability Configuration Guide.

To configure the Scripts property, follow the format given here:

Section: scripts
public_url <arg1> <arg2>

In this script, the first line of the property should read Section: Scripts.

In the second line of the property, enter the URL of the script and its arguments. The script can be either a Python or a Bash script. The script runs in guestshell during the first boot, after you upload the bootstrap file and create the Cisco Catalyst 8000V instance.

To view more script examples, see the Scripts section in https://github.com/csr1000v/customdata-examples. Also review these two examples.

Sample configuration

Section: Script
https://raw.githubusercontent.com/csr1000v/customdata-
examples/master/scripts/smartLicensingConfigurator.py --idtoken "<token_string>" --throughput <throughput_value>

The two lines in the scripts property retrieve the smartLicensingConfigurator.py script from the customdata-examples repository at the specified URL. The script runs in the guestshell container of the Cisco Catalyst 8000V using the arguments idtoken and throughput.

Sample configuration 2

Section: Scripts 
ftp://10.11.0.4/dir1/dir2/script.py -a arg1 -s arg2

These two lines in the Scripts property retrieve the script.py script from the FTP server with the IP address 10.11.0.4, and runs the script with the ./script.py -a arg1 -s arg2 bash command in the guestshell container of the Cisco Catalyst 8000V instance, using arg1 and arg2 as arguments.

Notes

If a script in the Scripts property requires a Python package that is not included in the standard CentOS Linux release, you must include information about the Python package in the Python package property. The standard CentOS Linux release that is used by the guestshell is CentOS Linux release 7.1.1503. For more information, see Configuring the Python package Property.

Prior to uploading the bootstrap file and running the bash or python script, Cisco recommends that you test the URL that you intend to use in the Scripts property. You can test the ftp://10.11.0.4/dir1/dir2/script.py -a arg1 -s arg2 URL by first running the curl software tool to download the script file. In the guestshell, enter the curl command, as illustrated here:

curl -m 30 --retry 5 --user username:password 
ftp://10.11.0.4/dir1/dir2/script_needs_credentials.py.

If the curl command is successful, a copy of the Python script is downloaded, verifying whether the URL is correct.

Configure the script credentials property

If you specify an FTP server in the Script property and the server requires user name and password credentials, provide these credentials using the Script credentials property.

If the FTP server allows anonymous access, you do not need to use the Script credentials property.

Configure the Scripts property with a URL and parameters that match those used in the Script credentials property. To configure the Script credentials property, use this format

Section: Script credentials
public_url <username> <password>

Sample configuration

Here's a sample Script credentials configuration:

Section: Script credentials
ftp://10.11.0.4/dir1/dir2/script1.py userfoo foospass

The second line in the Script credentials property specifies the user name (userfoo) and password (foospass) credentials for the Python script script1.py.

“Include the name of the FTP server as specified in the Scripts property. An example line in the Scripts property is: ftp://10.11.0.4/dir1/dir2/script1.py -a arg1 -s arg2. See example 2 in Configuring the Scripts Property.

Configure Python package property

If a Python package is required by a script in the Scripts property and is not included in the standard CentOS Linux release 7.1.1503, specify the package information in the Python package property. When you add the Python package property to the bootstrap file, the Cisco Catalyst 8000V downloads and installs the required Python package before the script in the Scripts property runs.

Note

Cisco Catalyst 8000V supports only Python3 in guestshell.

Configuring Python package property

To configure the Python package property, use the format specified here:

Section: Python package
package_name [ version ] [ sudo ] { [ pip_arg1 [ ..[ pip_arg9] ] ] }

The arguments version , sudo , and pip_arg1 to pip_arg9 are optional. Place the pip command arguments between the “{“ and “}” braces.

If you specify the version argument, the specific version number is downloaded.

If you specify the sudo argument, the package is downloaded as a sudo user.

Sample configuration for Microsoft Azure

Section: Python package
ncclient 0.5.2

For example, the second line of the Python package property indicates that package_name is ncclient and the version is "0.5.2". When you upload the bootstrap file, version 0.5.2 of the ncclient package installs in the guestshell container of Cisco Catalyst 8000V.

Section: Python package
c8000v_azure_guestshell 1.1.2 sudo {--user}

In this example, the second line of the Python package property specifies that the package_name is "c8000v_azure_guestshell" and the version is "1.1.2". When the bootstrap file is uploaded, version 1.1.2 of the c8000v_azure_guestshell package is installed in the guestshell container of Cisco Catalyst 8000V. This command is executed as a sudo user: sudo pip install c8000v_azure_guestshell==1.1.2 --user.

If you do not specify an argument, --user is used as the default argument.

Sample configuration for GCP

Section: Python package
ncclient 0.5.2

In this example, the second line of the Python package property specifies that the package_name is "ncclient", and the version is "0.5.2". When the bootstrap file is uploaded, version 0.5.2 of the ncclient package is installed in the guestshell container of the Cisco Catalyst 8000V instance.

Section: Python package
c8000v_gcp_ha 3.0.0 sudo {--user}

In this example, the second line of the Python package property specifies that the package_name is "c8000v_gcp_ha", and the version is "3.0.0". When the bootstrap file is uploaded, version 3.0.0 of the c8000v_gcp_ha package is installed in the guestshell container of the Cisco Catalyst 8000V instance. This command is executed as a sudo user: pip3 install c8000v_gcp_ha=3.0.0 --user.

If you do not specify an argument, --user is used as the default argument.

Configure the license property

Configure the license property to specify the license technology level for Cisco Catalyst 8000V.

Procedure

1.

Enter the first line of the property: Section: License.

2.

Enter the second line of the property: TechPackage:tech_level .

Specifies the tech level of the license.

There must be no spaces between TechPackage: and tech_level. Valid tech_level values are ax, security, appx, and ipbase.

Enter the tech_level value in lowercase.

 
Section: License
TechPackage:security

Provide the Day 0 bootstrap file

Provide the Day 0 bootstrap file. This file creates a Cisco Catalyst 8000V VM by executing the CLI commands for Microsoft Azure deployments.

Procedure

1.

Run this command in the CLI.

az vm create --name C8000V-name --resource-group resource-group { [ arg1 [ ..[ arg9] ] ] } --custom-data bootstrap-file

For further information on the az vm create command, see: https://docs.microsoft.com/en-us/cli/azure/vm?view=azure-cli-latest#az-vm-create.

Example:

az vm create -n c8000V-VM-Name -g MyResourceGroup --image cisco:cisco-c8000V-1000v:16_6:16.6.120170804 --data-disk-sizes-gb 8 --availability-set myAvlSet --nics nic1 nic2 nic3 nic4 --admin-username azureuser --admin-password "+Cisco123456" --authentication-type password -l westus --size Standard_DS4_v2 --custom-data bootstrap.txt.

When you execute this command, a Cisco Catalyst 8000V VM is created. The router is configured using the commands in the bootstrap.txt file.
2.

Use the Cisco C8000V Settings option to provide the custom data bootstrap config file.

For more information on managing Linux VMs, see Tutorial: Create and Manage Linux VMs with the Azure CLI 2.0.

Verify the custom data configuration in Microsoft Azure

After you upload the Day 0 bootstrap file, the VM is created and configuration commands are executed. Run the commands in this task to verify the configuration of each property.

Procedure

1.

To help determine if the license property worked, in Cisco IOS XE CLI on Cisco Catalyst 8000V, run the show version command.

Example:

Router#show version
Cisco IOS XE Software, Version 
Copyright (c) 1986-2020 by Cisco Systems, Inc.

Cisco IOS-XE software, Copyright (c) 2005-2020 by cisco Systems, Inc.
All rights reserved.  Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0.  The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY.  You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0.  For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.


ROM: IOS-XE ROMMON

Router uptime is 1 minute
Uptime for this control processor is 7 minutes
System returned to ROM by reload
System image file is "bootflash:packages.conf"
Last reload reason: Unknown reason



This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.

A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html

If you require further assistance please contact us by sending email to
export@cisco.com.

License Level: ipbase
License Type: N/A(Smart License Enabled)
Next reload license Level: ipbase

The current throughput level is 250000 kbps


Smart Licensing Status: Registration Not Applicable/Not Applicable

cisco C8000V (VXE) processor (revision VXE) with 2271486K/3075K bytes of memory.
Processor board ID 9MUG8CATY8R
Router operating mode: Controller-Managed
1 Gigabit Ethernet interface
32768K bytes of non-volatile configuration memory.
8106756K bytes of physical memory.
11530240K bytes of virtual hard disk at bootflash:.

Configuration register is 0x2102

[guestshell@guestshell ~]$ pip3 freeze | grep  gpg==1.10.0
gpg==1.10.0
[guestshell@guestshell ~]$
2.

To see if errors occurred after running the commands in the scripts property, look at the customdata.log file in the /home/guestshell/customdata directory. The scriptname.log file stores output sent to STDOUT by the script.
3.

To check if the Python property worked, enter the pip freeze | greppackage-name command to view the currently installed python packages. Search for the package package-namethat you are looking for.
4.

To check if the Cisco IOS XE commands were successful in the IOS Configuration property, enter the show running-configuration command.

Example:

Router#show running-config
Building configuration...

Current configuration : 6982 bytes
!
! Last configuration change at 14:34:36 UTC Fri Nov 6 2020 by NETCONF
!
version 17.3
service timestamps debug datetime msec
service timestamps log datetime msec
service password-encryption
! Call-home is enabled by Smart-Licensing.
service call-home
platform qfp utilization monitor load 80
platform punt-keepalive disable-kernel-core
platform console serial
!
hostname Router
!
boot-start-marker
boot-end-marker
!
vrf definition 65528
 !
 address-family ipv4
 exit-address-family
!
no logging buffered
no logging rate-limit
!
aaa new-model
!
aaa authentication login default local
aaa authentication enable default enable
aaa authorization console
aaa authorization exec default local
!
aaa session-id common
fhrp version vrrp v3
!
no ip dhcp use class
!
no ip igmp ssm-map query dns
login on-success log
ipv6 unicast-routing
!
subscriber templating
!
multilink bundle-name authenticated
!
crypto pki trustpoint TP-self-signed-2465303444
 enrollment selfsigned
 subject-name cn=IOS-Self-Signed-Certificate-2465303444
 revocation-check none
 rsakeypair TP-self-signed-2465303444
!
crypto pki trustpoint SLA-TrustPoint
 enrollment pkcs12
 revocation-check crl
!
!
crypto pki certificate chain TP-self-signed-2465303444
 certificate self-signed 01
  30820330 30820218 A0030201 02020101 300D0609 2A864886 F70D0101 05050030
  31312F30 2D060355 04031326 494F532D 53656C66 2D536967 6E65642D 43657274
  69666963 6174652D 32343635 33303334 3434301E 170D3230 31313036 31343333
  35345A17 0D333031 31303631 34333335 345A3031 312F302D 06035504 03132649
  4F532D53 656C662D 5369676E 65642D43 65727469 66696361 74652D32 34363533
  30333434 34308201 22300D06 092A8648 86F70D01 01010500 0382010F 00308201
  0A028201 0100B02F AD33A0FF 0C50D3F2 D06CFDC6 F3CB73BB 4070D649 E07D16CE
  E6271C90 34E86882 822C8D71 E4BAC29D 85285258 51E748E1 8C9FB2C5 12242A22
  7FB71551 02CB4DBC 64089D2F 8DBB6C4A D3E2F112 8E16E71F FE70D102 F59862A3
  E920E77E 52E62E02 1979F800 3D13601F 27C42F81 483BFB34 697F1C20 3952626A
  CA1F5805 26D50A39 33F264D6 1AD485A0 8EB45882 FC97DCA2 106C8FAD 8CDBC0E6
  FF609188 B4677AB0 FBBE77F2 359EA002 E1A5D37D EA895FF3 92732A2B 63465DFD
  4A2A277C 17E7F720 2007A6B6 A7C7296F D0CD2707 8C7C9690 F86B0642 1BA9F28C
  F729157B 8C472E40 78A4E6BE 70471018 4B62EE36 48193FCA 062DB09F 38BC420B
  687E5866 DFA10203 010001A3 53305130 0F060355 1D130101 FF040530 030101FF
  301F0603 551D2304 18301680 14ABBD00 3D02C6E1 7706FA96 29B037A8 583E7B2E
  69301D06 03551D0E 04160414 ABBD003D 02C6E177 06FA9629 B037A858 3E7B2E69
  300D0609 2A864886 F70D0101 05050003 82010100 40C60BF0 2184CF86 08CACB66
  73E74D63 E87A6661 DC839037 D0DB08D0 33C4993C EC326432 E3573D1B EC3B42AF
  F410BF72 2AAB6D8F 1406B352 FE6B5365 CCA7E094 96980FC7 A4B77A02 49CB8C01
  3EC87F01 58BFEE33 0DA222DB 0A1BA130 0AC01F1F FDBF2085 D41EFA45 7A4C7F5E
  2D004D04 D11433BF 69337D90 117A86ED 2CF57A49 AD7DA227 129E53DF 55E12E03
  4D8E0097 A29DC365 11E8B386 891C310E F19EDF6D D9B3EA1E E26ABDBD EF82D8E9
  B0484E26 C0FC1D71 91B19B70 221E1A1A 090F8EA1 3A5FC4FD A4EF36CD EFD2F1F4
  6056C87D 8A76ED1A 68FB76F5 956C6B50 7EFA9D8C 90EA910F 187EBD13 0BF76E5A
  0B9CE20E AA5927C4 7AD13C28 58C6E920 76E36475
        quit
crypto pki certificate chain SLA-TrustPoint
 certificate ca 01
  30820321 30820209 A0030201 02020101 300D0609 2A864886 F70D0101 0B050030
  32310E30 0C060355 040A1305 43697363 6F312030 1E060355 04031317 43697363
  6F204C69 63656E73 696E6720 526F6F74 20434130 1E170D31 33303533 30313934
  3834375A 170D3338 30353330 31393438 34375A30 32310E30 0C060355 040A1305
  43697363 6F312030 1E060355 04031317 43697363 6F204C69 63656E73 696E6720
  526F6F74 20434130 82012230 0D06092A 864886F7 0D010101 05000382 010F0030
  82010A02 82010100 A6BCBD96 131E05F7 145EA72C 2CD686E6 17222EA1 F1EFF64D
  CBB4C798 212AA147 C655D8D7 9471380D 8711441E 1AAF071A 9CAE6388 8A38E520
  1C394D78 462EF239 C659F715 B98C0A59 5BBB5CBD 0CFEBEA3 700A8BF7 D8F256EE
  4AA4E80D DB6FD1C9 60B1FD18 FFC69C96 6FA68957 A2617DE7 104FDC5F EA2956AC
  7390A3EB 2B5436AD C847A2C5 DAB553EB 69A9A535 58E9F3E3 C0BD23CF 58BD7188
  68E69491 20F320E7 948E71D7 AE3BCC84 F10684C7 4BC8E00F 539BA42B 42C68BB7
  C7479096 B4CB2D62 EA2F505D C7B062A4 6811D95B E8250FC4 5D5D5FB8 8F27D191
  C55F0D76 61F9A4CD 3D992327 A8BB03BD 4E6D7069 7CBADF8B DF5F4368 95135E44
  DFC7C6CF 04DD7FD1 02030100 01A34230 40300E06 03551D0F 0101FF04 04030201
  06300F06 03551D13 0101FF04 05300301 01FF301D 0603551D 0E041604 1449DC85
  4B3D31E5 1B3E6A17 606AF333 3D3B4C73 E8300D06 092A8648 86F70D01 010B0500
  03820101 00507F24 D3932A66 86025D9F E838AE5C 6D4DF6B0 49631C78 240DA905
  604EDCDE FF4FED2B 77FC460E CD636FDB DD44681E 3A5673AB 9093D3B1 6C9E3D8B
  D98987BF E40CBD9E 1AECA0C2 2189BB5C 8FA85686 CD98B646 5575B146 8DFC66A8
  467A3DF4 4D565700 6ADF0F0D CF835015 3C04FF7C 21E878AC 11BA9CD2 55A9232C
  7CA7B7E6 C1AF74F6 152E99B7 B1FCF9BB E973DE7F 5BDDEB86 C71E3B49 1765308B
  5FB0DA06 B92AFE7F 494E8A9E 07B85737 F3A58BE1 1A48A229 C37C1E69 39F08678
  80DDCD16 D6BACECA EEBC7CF9 8428787B 35202CDC 60E4616A B623CDBD 230E3AFB
  418616A9 4093E049 4D10AB75 27E86F73 932E35B5 8862FDAE 0275156F 719BB2F0
  D697DF7F 28
        quit
!
license udi pid C8000V sn 9MUG8CATY8R
diagnostic bootup level minimal
memory free low-watermark processor 69848
!
!
username admin privilege 15 secret 9 $14$vKLj$yfnFjRidlKJg9.$4obKgKyy4TsoUs0sJ2t3HXPnA3XjYWRBnnYKBwVeJrw
!
redundancy
!
interface Loopback65528
 vrf forwarding 65528
 ip address 192.168.1.1 255.255.255.255
!

Verify the custom data configuration in Google Cloud Platform

After you run the custom data script, the VM is created and the configuration commands are executed. To verify the same, use the commands and scripts mentioned in this task.

Procedure

1.

Run the show version command.

This command displays information about the device, including details about the license property as used in Cisco IOS XE CLI on the Cisco Catalyst 8000V instance.
2.

Check the customdata.log file in the /bootflash/<cloud>/ directory to determine if any errors occurred after executing commands in the scripts property. The scriptname.log file contains the output sent to STDOUT by the script.
3.

Enter the pip freeze | grep <package-name> command in the Guestshell to view the currently installed Python packages and verify whether the Python property worked. In this command, package-name refers to the package that you want to locate.
4.

To verify the Cisco IOS XE commands in the IOS Configuration property, run the show running-configuration command.