Catalyst 4500 Series Switch Software Configuration Guide, IOS XE 3.9.xE and IOS 15.2(5)Ex

Overview

Programmability is the capability to configure and manage networking devices using protocols that are specifically designed to be consumed by software, that is, machine to machine interfaces.

The traditional way of configuring and managing Cisco networking devices, has been manual configuration, through the command line interface (CLI). As deployments become more complex, programmability of devices has enabled a shift from manual to automatic network provisioning and configuration.

Managing device configuration programmatically enables you to:

• Configure and control at scale—You can automate network configuration while also overcoming difficulties posed by multiple platforms, multiple operating systems, and multiple vendor devices in your network.
• Check to make sure that dependencies are satisfied before committing a change; and also easily roll-back changes when they are not consistently compatible across the network.

To address configuration and monitoring issues, the Internet Engineering Task Force (IETF) has defined these standards in network management:

• Yet Another Next Generation (YANG) data modeling— RFC 6020.
• Network Configuration Protocol (NETCONF)— RFC 6241
• Representational State Transfer Configuration Protocol (RESTCONF)–uses the same data models as defined for NETCONF using YANG ( https://tools.ietf.org/html/draft-ietf-netconf-restconf-04).

On Catalyst 4500 Series Switches, the Programmability feature provides the use of NETCONF and RESTCONF interfaces. They reside in a container on the switch and provide interfaces that enable remote management. The YANG data models available with these interfaces determine the scope of functions or actions that can be performed. See Figure 6-1.

Programmability Components

This section describes the components involved in the setup of the feature. See the Configuring Programmability Components for information about how to configure individual components.

• The Virtual Services Container—Also referred to as a virtual machine (VM), virtual service, or container, is a virtual environment on the switch.

You can install an application within a virtual services container. The application then runs in the virtual services container of the operating system of a switch. The application is delivered as an open virtual application (OVA), which is a tar file with a.ova extension. The OVA package is installed and enabled on the switch through the device CLI.

• The Data Model Interface (DMI)—A container solution that provides the NETCONF and RESTCONF programmable interfaces. You must install and activate this container on the switch. After you activate it, the YANG models and APIs are available for use.
• The Network Bootloader—Network boot loaders support booting from a network-based source.

On the Catalyst 4500 series switches, the Preboot Execution Environment (PXE) feature, also called PXE boot, enables the switch to retrieve the software image, configuration files, scripts, and ova files from a remote server, without end-user intervention, that is, Zero-Touch Provisioning. The remote server can be an HTTP or a TFTP server.

PXE boot requires the configuration of a DHCP server, and the boot field set to one of the autoboot options in the ROMMON.

Throughout the document, PXE boot is used to refer to the method of booting from a network-based source.

Protocols and Data Models for Programmatic Device Configuration

This section describes the protocols and modeling languages that enable a programmatic way of writing configurations to a network device.

• NETCONF—An XML-based protocol that you can use to request information from and make configuration changes to the switch. NETCONF Application Programming Interfaces (APIs) use Secure Shell Version 2 (SSHv2).
• RESTCONF— Uses structured data (XML or JSON) and YANG to provide a REST-like APIs, enabling you to programmatically access different network devices. RESTCONF APIs use HTTPs methods.
• YANG—A data modeling language that is used to model configuration and operational features on the switch. YANG determines the scope and the kind of functions that can be performed by NETCONF and RESTCONF APIs. The following data models are supported:

– The ned.yang model—A Cisco-specific configuration data model that enables to you perform write (SET) operations.

– The Operational Data Manager (ODM)—Enables you to read operational state data (GET operations) using YANG models.

Figure 6-1 shows how the different components of Programmability come together.

Figure 6-1 Programmability Components

Default Configuration

Programmability is not enabled.

Prerequisites for Configuring Programmability

• Prerequisites for NETCONF and RESTCONF:

Your access to the switch is configured with privilege level 15. This is required to start working with NETCONF and RESTCONF interfaces. See Providing Privilege Access to Use NETCONF and RESTCONF.

• To use the programmability feature, you must use the Universal Crypto Image. See section “Orderable Product Numbers” in the corresponding release notes:

– Release Notes for the Catalyst 4500-X Series Switches

– Release Notes for the Catalyst 4500-E Series

• Prerequisites for using PXE boot:

– The boot capability is set to autoboot and the bootfield is set to 04, 05, or 06. PXE boot is supported only if you have enabled autoboot.

Note For PXE boot, the boot capability is set to autoboot by default.

– The required ROMMON version is installed:

On Catalyst 4500-X Series Switches, ROMMON version 15.0(1r)SG14 applies.

On Catalyst 4500-E Series Switches, ROMMON version 15.1(1r)SG8 applies.

With the above ROMMON versions, the factory default setting for the configuration register value is 0x2106 (boot field 06). This is also the recommended setting if you are using an existing device and upgrading to these ROMMON versions.

Note If you are not using PXE boot, you do not have to upgrade the ROMMON version.

Restrictions and Limitations for Configuring Programmability

• Data model related restrictions:

– Only a subset of the IETF, or common data models are supported.

– Only the Cisco device-specific ned.yang model is supported.

– When using ODM models, you must stop and restart the ODM control process if the crypto keys are regenerated. See Activating and Deactivating the ODM

• DMI solution related restrictions:

– IPv6 is not supported.

– Switches operating in the VSS mode are not supported.

– It is not ISSU-capable.

• Only up to 4 simultaneous NETCONF sessions are supported. Further, a session that is idle for more than 180 seconds will timeout.
• Requests coming on an EtherChannel that is part of a Layer 3 Switched Virtual Interface (SVI), and is sharing its IP with the DMI container, is not supported
• AAA remote authentication is not supported.

Zero-Touch Provisioning Requirements

Zero-Touch Provisioning is achieved by using the PXE boot feature. Ensure that you have completed the following:

• Set the boot field value. See Boot Field
• Configured the DHCP server and an HTTP or TFTP server. See PXE Boot Requirements —Configuring the DHCP Server and PXE Boot Process Flow
• Entered the following global configuration commands in the start-up configuration file. This refers to the < filename >.config file and is downloaded during the PXE boot process. This is required if you want NETCONF and RESTCONF to be available for use from Day 0.

– The virtual-service DMI command (The virtual service name must be DMI if one opts for Zero-Touch Provisioning).

– The activate command

– The ip shared host-interface interface-id command

– The onep command

– The service set vty command

– The username name privilege level password password command

To use NETCONF

– The netconf-yang command

To use RESTCONF

– The restconf command

– The ip http server or the ip http secure-server command

– The ip http authentication local command

The following is a sample output of the show running-config command. It displays the commands that are configured as part of start-up configuration

Boot Field

To use PXE boot, you must enable autoboot, and set the boot field 04, 05, or 06. This automatically sets the corresponding configuration register value.

The PXE boot feature requires ROMMON version 15.0(1r)SG14 on Catalyst 4500-X Series Switches, and ROMMON version 15.1(1r)SG8 on Catalyst 4500-E Series Switches.

For detailed information about the various boot fields, see table Explanation of Boot Field (Configuration Register Bits 00 to 03) ” in chapter “Configuring the Switch for the First Time” in this book.

PXE Boot Requirements —Configuring the DHCP Server

To send switch startup configuration files, scripts, and ova file in addition to the bootable image, you must configure the DHCP server.

Depending on your existing DHCP server setup (whether on Microsoft Windows or Linux), ensure that you have made the corresponding, requisite settings. See DHCP Server Settings on Linux or Microsoft Windows DHCP Server Configuration, whichever applies.

Note After completing DHCP server configuration, manually assign an IP to the switch and ping to check the switch-to-server connectivity.

Observe the following DHCP server configuration guidelines:

• You must provide the gateway, subnet mask, server IP address, and the client IP address. This information is not permanently stored on switch. They are used only to download files and are deleted when the activity is complete.
• Specifics for the start-up configuration file, script file and ova files (applies to DHCP server configuration for Microsoft Windows and Linux):

– Complete the DHCP Option 43 list with information about the location of configuration, script and ova file to be downloaded.

– You can specify an HTTP server or a TFTP server location from which to download. Depending on your requirement, specify one or more options— the boot image name, the start-up configuration file name and path, the script file name and path, and the ova file name and path. Ensure that the configuration, script and ova file extensions are <config-file>.config,<script-file>.script,<container-file>.ova respectively.

– If you are opting for Zero-Touch Provisioning, the ova file name must include _dmi_. For example, example_dmi_container.ova

– These files should be saved in the root folder.

– If you are using HTTP to download, you must configure the DNS server information.

• When the DHCP server responds successfully, the output displays Received DHCP_ACK.
• If you receive a TFTP timeout error, increase the DHCP timeout by using the ROMMON variable DhcpTimeout. The default DHCP timeout is 5 seconds. You can increase it by a maximum of 30 seconds. For example, if DhcpTimeout=20, the DHCP timeout increases by 20 seconds. Enter the set command to verify the change.

• The DHCP options list that the DHCP server sends should not be greater than 255 bytes. If it is, the following error message is displayed:

• The PXE process ignores network information that you configure on the ROMMON, such as IP, gateway, subnet mask etc.
• You can interrupt the autoboot process at any point, by pressing Control +C (switches to the ROMMON mode).

– For sample output of the autoboot process, using HTTP, see Autoboot Process Output—Using HTTP.

– For sample output of the autoboot process using TFTP, see Autoboot Process Output—Using TFTP

PXE Boot Process Flow

This section outlines the communication process between the DHCP server and the switch and provides the sequence of events followed during the PXE boot (network boot loading) process. This assumes that autoboot is enabled.

1. The switch sends a DHCP discovery packet.

2. The DHCP server responds with an offer containing the TFTP or HTTP server IP address, the offered IP address for the client, the gateway IP address, the boot file name, and the path and names of the OVA, script, and switch configuration files.

3. The switch sends the DHCP request for the IP address.

4. The switch receives the DHCP acknowledgment packet from the server, downloads the image specified in the filename variable in the DHCP server, and then boots up with downloaded image.
While booting, the switch receives the Option 43 list from the DHCP server with information about the location of configuration file, script file and ova file to be downloaded.

5. After POST is complete, the switch looks for the startup configuration files, script files, and ova files as mentioned in the Option 43 list received in Step 4. If the files mentioned the Option 43 list are present in the specified location, the switch downloads them.
The script file is downloaded to— bootflash:pxe/scripts folder
The ova file is downloaded to— bootflash:pxe/ova folder.

Figure 6-2 PXE Boot Process Flow

Installing and Activating the DMI Container

This task is mandatory if you have opted for the standard configuration method.

Before you begin, ensure that you have completed the following:

• Downloaded an OVA package that is compatible with the device operating system. The OVA package is available for download in the same location as your system image (.bin) file.
• Ensured that the minimum required disk space - 512 MB, and memory - 256 MB RAM is available on the device for installation and deployment of the DMI container.

To install and activate the DMI by using the virtual services container CLI, perform the following task:

Configuring One Platform Kit (OnePK)

OnePK is a software development kit. It enables you to create applications with which to interact directly with Cisco networking devices, and also use a set of controlled API to access networking services.

In the context of Programmability, it is used to enable the VTY service set. The VTY Service allows a onePK application to communicate with a network element, through a virtual terminal.

This task is mandatory if you have opted for the standard configuration method. To enable the requisite, internal OnePK infrastructure, perform the following task:

Providing Privilege Access to Use NETCONF and RESTCONF

This task is mandatory for both zero touch provisioning, and the standard configuration method.

To start working with NETCONF and RESTCONF APIs you must be a user with privilege level 15. To provide this, perform the following task:

Enabling the NETCONF Interface

This task is mandatory if you want to use the NETCONF interface and have opted for the standard configuration method:

See Examples for NETCONF RPCs.

Enabling Cisco IOS HTTP Services for RESTCONF

This task is mandatory if you want to use the RESTCONF interface and have opted for the standard configuration method.

See Examples for RESTCONF RPCs.

Examples for NETCONF RPCs

Get the running-configuration of the switch by sending the following RPC:

Change the description of an interface by sending the following RPC

Remove the description from an interface by sending the following RPC

Examples for RESTCONF RPCs

Get the TFTP source interface by sending the following RPC:

Configure the TFTP source interface by sending the following RPC:

Enter an HTTP delete request by sending the following RPC:

Note For the HTTP delete request do not use: http://10.106.30.33:80/restconf/api/running/native/ip/tftp/source-interface/

Enabling SSHv2

For information about configuring SSHv2, see http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/sec_usr_ssh/configuration/xe-3e/sec-usr-ssh-xe-3e-book.html

Activating and Deactivating the ODM

This section contains sample RPCs to check the current status of the ODM, to activate it, and to deactivate it.

Example: Checking the Current Status of the ODM.

In the example below, the ODM is active (value set to true).

Input

Output

Example: Activating or Starting the ODM

In the example below, the RPC reply (ok) indicates that the ODM is activated successfully.

Input

Output

To deactivate or stop the ODM, send the following RPC:

Input

Output

Enabling the Polling Mode

This section contains sample RPCs to check the current polling mode, to enable or change it, and to change the polling interval.

Example: Verifying the Currently Polling Mode of the ODM Models

In the example below, polling is enabled. (In the output section, the polling-enable parameter is set to true).

Input

Output

Example: Enabling or Changing the Polling Mode of the ODM Models

Input

Output

Example: Changing the Polling Interval of a Parser

In the example below, the polling interval of parser parse.showArchive is changed to 110000 miliseconds:

Input

Output

Displaying Supported Parsers and Polling Intervals

To retrieve information about all the supported parsers and their polling intervals, send the following RPC:

Input

Output

DHCP Server Settings on Linux

The following is sample configuration that is saved in the dhcpd.conf file. Use it as a point of reference when you configure DHCP server settings on Linux.

This sample output covers a scenario where different files are sent to multiple devices of the same vendor specific class, but each one of the devices has a different MAC address.

Comments throughout the sample configuration provide guidelines for important steps (sentence starting with #).

Note You must restart the DHCP service every time you make a change in the dhcpd.conf file.

Depending on whether you are using HTTP or TFTP to download files, refer to the corresponding sample configuration file:

• Using HTTP
• Using TFTP

Using HTTP

Using TFTP

Configuring DHCP Option 43 (for Microsoft Windows)

DHCP Option 43 is used by clients and servers to exchange vendor-specific information. (RFC 2132).

This section describes the DHCP Option 43 configuration information that pertains to sending device configuration files, script files, and.ova files to the switch. It is applicable only if you use OpenDhcpServer as the DHCP server, with Microsoft Windows. Other DHCP servers have their own methods to configure this option and the information is available on the Internet.

To send any file, you must convert the file name along with the extension, to a hexadecimal format and the files must be stored in the TFTP root directory.

< File code >< length of filename.ext in hexadecimal value >< hex value of the filename.ext >

Use the relevant codes to specify the type of file you want to send

• code 01—A configuration file. For example, to send file example-config.config :
  43=01:15:65:78:61:6d:70:6c:65:2d:63:6f:6e:66:69:67:2e:63:6f:6e:66:69:67:
• code 02—A script file. For example to send file example-script.py :
  43=02:11:65:78:61:6d:70:6c:65:2d:73:63:72:69:70:74:2e:70:79
• code 03—An ova file. For example, to send file example_dmi_container.ova :
  43=03:19:65:78:61:6d:70:6c:65:5f:64:6d:69:5f:63:6f:6e:74:61:69:6e:65:72:2e:6f:76:61

Concatenating all three file names

Microsoft Windows DHCP Server Configuration

The following example shows how to configure the DHCP Server on Microsoft Windows.

Note The example uses OpenDhcpServer and Solarwinds TFTP server. Information about configuring both is available on the Internet. The use of both applications here is only meant to serve as an example for configuration, and are not product recommendations.

Figure 6-3 Solarwinds TFTP Server

The important sections of this sample configuration are highlighted bold :

Autoboot Process Output

Autoboot Process Output—Using HTTP

Autoboot Process Output—Using TFTP

Autoboot Process Output—Using HTTP

The following is sample output of the autoboot process on Catalyst 4500-X Series Switches..

• The HTTP server from which the files are being downloaded is example-httpserver-url.com.
• The image, configuration, script, and ova files being downloaded are example-ios-image.bin, example-config.config, example-script.py, and example_dmi_container.ova respectively.

Autoboot Process Output—Using TFTP

The following is sample output of the autoboot process on Catalyst 4500-E Series Switches with Supervisor Engine 8-E.

• The TFTP server from which the files are being downloaded is 198.51.100.2.
• The image, configuration, script and, ova files being downloaded are example2-ios-image.bin, example2-config.config, example2-script.py, and example2_dmi_container.ova respectively.