Cisco CSR 1000V Series Cloud Services Router Software Configuration Guide
Configuring Support for Management Using the REST API
Downloads: This chapterpdf (PDF - 306.0KB) The complete bookPDF (PDF - 3.44MB) | Feedback

Table of Contents

Configuring Support for Management Using the REST API

Introduction

Enabling REST API Support During Cisco CSR 1000V OVA Deployment

Enabling REST API Support Using the Cisco IOS XE CLI

Introduction to REST API Configuration Options

Configuring the Shared Management Interface to Support the RESTAPI

Configuring the Dual Management Interface to Support the RESTAPI

Configuring the REST API Local Port and AutoSave Options

Configuring HTTPS Support for the REST API Using the Cisco IOS XE CLI

Disabling REST API Support

Viewing the REST API Container Status

Introduction

You can use the REST API to manage the Cisco CSR 1000V as an alternative to configuring and managing selected features on the router using the Cisco IOS XE CLI. This chapter describes how to configure the Cisco CSR 1000V to enable management using the REST API. For detailed information about using the REST API, see the Cisco CSR 1000V Series Cloud Services Router REST API Management Reference Guide .

Enabling REST API Support During Cisco CSR 1000V OVA Deployment

If you are deploying the Cisco CSR 1000V OVA template, support for REST API is configured in the Bootstrap Properties screen of the OVA Wizard. The required fields are different depending on the Cisco IOS XE release. Table 14-1 and Table 14-2 list the fields required to enable REST API support when deploying the OVA template.

For more information on deploying the OVA template, see the “Deploying the Cisco CSR 1000V OVA Template to the VM” section.

Table 14-1 Cisco CSR 1000V OVA Template Bootstrap Properties Required for REST API Support (Cisco IOS XE Release 3.10S)

Property
Description

Management IPv4 Address/Mask

Sets the management gateway address and mask in IPv4 format for the GigabitEthernet0 management interface.

Management IPv4 Default Gateway

Sets the default management gateway IP address in IPv4 format for the GigabitEthernet0 management interface.

Note The GigabitEthernet0 interface is no longer supported beginning in Cisco IOS XE Release 3.11S.

Enable HTTPS Server

Enables an HTTPS server for system configuration and administration via a web browser. Required if using the REST API to perform system management in Cisco IOS XE Release 3.10S.

Table 14-2 Cisco CSR 1000V OVA Template Bootstrap Properties Required for REST API Support (Cisco IOS XE Release 3.11S and Higher)

Property
Description

Management Interface

Designates the management interface for the Cisco CSR 1000V. The format must be GigabitEthernetx or GigabitEthernetx.xxx.

Management Interface IPv4 Address/Mask

Configures the IPv4 address and subnet mask for the management interface.

Management IPv4 Default Gateway

Configures the IPv4 management default gateway address. If using DHCP, enter “dhcp” in the field.

Remote Management IPv4 Address1

Configures the IP address used for remote management of the Cisco CSR 1000V by the REST API or by Cisco PNSC. The address must be in the same subnet as the management interface address.

1.Not used if configuring the shared management interface to support REST API.

Table 14-3 Cisco CSR 1000V OVA Template Bootstrap Properties Required for REST API Support (Cisco IOS XE Release 3.12S and Later)

Property
Description

Management Interface

Designates the management interface for the Cisco CSR 1000V. The format must be GigabitEthernetx or GigabitEthernetx.xxx.

Management Interface IPv4 Address/Mask

Configures the IPv4 address and subnet mask for the management interface.

Management IPv4 Gateway (Cisco IOS XE Release 3.12S)

Configures the IPv4 management default gateway address. If using DHCP, enter “dhcp” in the field.

Management IPv4 Network (Cisco IOS XE Release 3.12S)

Configures the IPv4 Network (such as “192.168.2.0/24” or “192.168.2.0 255.255.255.0”) that the management gateway should route to. If a default route (0.0.0.0/0) is desired, this may be left blank.

Enabling REST API Support Using the Cisco IOS XE CLI

Introduction to REST API Configuration Options

You need to configure the management interface to support REST API using the Cisco IOS XE CLI in the following situations:

  • If you installed the Cisco CSR 1000V using the .iso file.
  • If you deployed the Cisco CSR 1000V using an Amazon Machine Image (AMI).

Note If upgrading a REST API configuration from Cisco IOS XE Release 3.10S to a higher release, you must add your REST API configuration to the IOS configuration.


The REST API management is located in a management virtual services container that is separate from the router components, including the router management interface. You have two choices for configuring the REST API management support, and the configuration steps are different:

(Cisco IOS XE 3.13S and higher) The router management interface and the virtual services management container can share the same IP address. This can be used to save an IP address to be allocated for other purposes.

(Required in Cisco IOS XE 3.11S and 3.12S, optional in later releases.) The router management interface and the virtual services management container use different IP addresses.

Configuring the Shared Management Interface to Support the REST API

SUMMARY STEPS

1. enable

2. configure terminal

3. interface mgmt-interface

4. ip address mgmt-ipv4-addr

5. no shutdown

6. exit

7. virtual-service csr_mgmt

8. no activate

9. ip shared host-interface mgmt-interface

10. activate

11. end

DETAILED STEPS

 

Command or Action
Purpose

Step 1

enable

 

Router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

 

Router# configure terminal

Enters global configuration mode.

Step 3

interface mgmt-interface

 

Router(config)# interface gigabitethernet1

Enters interface configuration mode for the management interface.

Step 4

ip address mgmt-ipv4-addr subnet-mask

 

Router(config-if)# ip address 172.25.29.235 255.255.255.128

Configures the IP address for the management interface.

Step 5

no shutdown

 

Router(config-if)# no shutdown

Enables the management interface.

Step 6

exit

 
Router(config-if)# exit

Exits interface configuration mode.

Step 7

virtual-service csr_mgmt

 

router(config)# virtual-service csr_mgmt

Configures the csr_mgmt virtual services container and enters virtual services configuration mode.

Step 8

no activate

 

router(config-virt-serv)# no activate

Deactivates the csr_mgmt virtual services container.

Step 9

ip shared host-interface mgmt-interface

 
router(config-virt-serv)# ip shared host-interface gigabitethernet 1

Maps the virtual service container to the management interface.

Step 10

activate

 

router(config-virt-serv)# activate

Activates the csr_mgmt virtual services container.

Step 11

end

 

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Configuring the Dual Management Interface to Support the REST API

SUMMARY STEPS

1. enable

2. configure terminal

3. interface mgmt-interface

4. ip address mgmt-ipv4-addr

5. no shutdown

6. exit

7. interface virtualportgroup virtual-port-group-number

8. ip unnumbered management-interface

9. no shutdown

10. exit

11. virtual-service csr_mgmt

12. vnic gateway virtualportgroup virtual-port-group-number

13. guest ip address remote-mgmt-ipv4-addr

14. activate

15. end

16. ip route ip-address subnet-mask virtualportgroup virtual-port-group-number

DETAILED STEPS

 

Command or Action
Purpose

Step 1

enable

 

Router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

 

Router# configure terminal

Enters global configuration mode.

Step 3

interface mgmt-interface

 

Router(config)# interface gigabitethernet1

Enters interface configuration mode for the management interface.

Step 4

ip address mgmt-ipv4-addr subnet-mask

 

Router(config-if)# ip address 172.25.29.235 255.255.255.128

Configures the IP address for the management interface.

Step 5

no shutdown

 

Router(config-if)# no shutdown

Enables the management interface.

Step 6

exit

 
Router(config-if)# exit

Exits interface configuration mode.

Step 7

interface virtualportgroup virtualportgroup-number

 
Router(config)# interface virtualportgroup 0

Creates a virtual port group and enters virtual port group interface configuration mode.

Step 8

ip unnumbered management-interface

 
router(config-if)# ip unnumbered gigabitethernet1

Enables IP processing on an interface without assigning it an explicit IP address.

Step 9

no shutdown

 

router(config-if)# no shutdown

Enables the virtual port group interface.

Step 10

exit

 
router(config-if)# exit

Exits virtual port group interface mode.

Step 11

virtual-service csr_mgmt

 

router(config)# virtual-service csr_mgmt

Configures the csr_mgmt virtual services container and enters virtual services configuration mode.

Step 12

vnic gateway virtualportgroup virtualportgroup_number

 
router(config-virt-serv)# vnic gateway virtualportgroup 0

Creates a vNIC gateway interface for the virtual services container and maps it to the virtual port group.

Step 13

guest ip address remote-mgmt-ipv4-addr

 

router(config-virt-serv-intf)# guest ip address 172.25.29.236

Configures the remote-management IP address for the vNIC gateway interface for the virtual services container.

Step 14

exit

 

router(config-virt-serv-intf)# exit

Exits virtual services interface configuration mode and enters virtual services configuration mode.

Step 15

activate

 

router(config-virt-serv)# activate

Activates the csr_mgmt virtual services container.

Step 16

end

 

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 17

ip route ipaddress subnetmask virtualportgroup virtualportgroupnumber

 
router(config)# ip route 172.25.29.236 255.255.255.255 VirtualPortGroup0

Creates an IP route that maps to the virtual port group. Use the same IP address that was configured using the guest ip address command.

Configuring the REST API Local Port and AutoSave Options

Beginning with Cisco IOS XE 3.13S, you can configure the REST API local port and autosave options.

SUMMARY STEPS

1. remote-management

2. restful-api local port local-port-number

3. restful-api autosave interval

DETAILED STEPS

 

Command or Action
Purpose

Step 1

remote-management

 

router(config)# remote-management

Enters remote-management configuration mode.

Step 2

restful-api local-port local-port-number

 

router(cfg-remote-mgmt)# restful-api local-port 55433

Configures the REST API local port number. The valid range depends on whether the REST API virtual services container uses the same IP address as the management interface, or if it uses a different IP address:

  • Valid range if the dual management interface is configured is from 1 to 61000.
  • Valid range if the shared management interface is configured is from 55001 to 61000.

In both cases, the default value is 55433.

Step 3

restful-api autosave interval

 

Router(cfg-remote-mgmt)# restful-api autosave 60

Configures the REST API autosave interval. The range is from 30-300 seconds, and the default is 30.

Configuring HTTPS Support for the REST API Using the Cisco IOS XE CLI

The Cisco CSR 1000V REST API requires HTTPS server support. Beginning with Cisco IOS XE Release 3.11S, HTTPS server support is enabled by default and no additional configuration is required. However, if using Cisco IOS XE Release 3.10S, you must manually configure HTTPS support for the REST API in the following situations:

  • If you did not specify the Enable HTTPS Server option when deploying the OVA.
  • If you installed the Cisco CSR 1000V using the .iso file.

Note The HTTPS session must have an identity certificate. For more information, see the “HTTPS-HTTP Server and Client with SSL 3.0” section of the HTTP Services Configuration Guide, Cisco IOS XE Release 3S.


SUMMARY STEPS

1. enable

2. configure terminal

3. ip http secure-server

4. transport-map type persistent webui transport-map-name

5. secure-server

6. transport type persistent webui input transport-map-name

DETAILED STEPS

 

Command or Action
Purpose

Step 1

enable

 

router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

 

router# configure terminal

Enters global configuration mode.

Step 3

ip http secure-server

 

router(config)# ip http secure-server

Enables HTTPS on port 443 (the default HTTPS port). A self-signed identity certificate is automatically generated.

Step 4

transport-map type persistent webui transport-map-name

 

router(config)# transport-map type persistent webui https-webui

Creates and names a persistent web user interface transport map.

Step 5

secure-server

 

router(config)# secure-server

Enables the secure HTTPS server.

Step 6

transport type persistent webui input transport-map-name

 

router(config)# transport type persistent webui input https-webui

Enables the transport map to support HTTPS.

Disabling REST API Support

Beginning with Cisco IOS XE Release 3.11S, you can disable REST API support on the remote management interface. Support for the REST API is enabled by default.

SUMMARY STEPS

1. enable

2. configure terminal

3. remote-management

4. no restful-api

5. end

DETAILED STEPS

 

Command or Action
Purpose

Step 1

enable

 

router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

 

router# configure terminal

Enters global configuration mode.

Step 3

remote-management

 

router(config)# remote-management

Enters remote-management configuration mode.

Step 4

no restful-api

 

router(cfg-remote-mgmt)# no restful-api

Disables support for the REST API.

Step 5

end

 

router(cfg-remote-mgmt)# end

Exits remote-management configuration mode and enters configuration mode.


Note When REST API support is disabled using the no restful-api command, the REST API PUT, POST and DELETE operations are disabled. However, the GET operation is still available.


Viewing the REST API Container Status

The following example shows the enabled status of the REST API container, along with the detailed guest status with a list of processes, status showing when these processes are up and running, and the number of restarts:

Router# show virtual-service detail
 
Virtual service csr_mgmt detail
State : Activated
Package information
Name : csrmgmt.1_2_1.20131010_134115.ova
Path : bootflash:/csrmgmt.1_2_1.20131010_134115.ova
Application
Name : csr_mgmt
Installed version : 1.2.1
Description : CSR-MGMT
Signing
Key type : Cisco development key
Method : SHA-1
Licensing
Name : Not Available
Version : Not Available
 
Detailed guest status
----------------------------------------------------------------------
Process Status Uptime # of restarts
----------------------------------------------------------------------
nginx UP 0Y 0W 0D 0: 1: 1 0
climgr UP 0Y 0W 0D 0: 1: 1 0
restful_api UP 0Y 0W 0D 0: 1: 1 0
fcgicpa UP 0Y 0W 0D 0: 0:13 0
pnscag UP 0Y 0W 0D 0: 0:13 0
pnscdme UP 0Y 0W 0D 0: 0:12 0
----------------------------------------------------------------------
Feature Status Configuration
----------------------------------------------------------------------
Restful API Enabled, UP port: 443
(GET only) auto-save-timer: 8 seconds
socket: unix:/usr/local/nginx/csrapi-fcgi.sock;
 
PNSC Enabled, UP host: 172.25.223.233
port: 8443
socket: unix:/usr/local/cpa-fcgi.sock;
 
Network stats:
eth0: RX packets:38, TX packets:6
eth1: RX packets:87, TX packets:80
 
Coredump file(s):
 
Activated profile name: None
Resource reservation
Disk : 540 MB
Memory : 512 MB
CPU : 30% system CPU
 
Attached devices
Type Name Alias
---------------------------------------------
Serial/Trace serial3
Serial/Syslog serial2
Serial/aux serial1
Serial/shell serial0
Disk /opt/var
Disk _rootfs
NIC dp_2_0 net2
NIC ieobc_2 ieobc
 
Network interfaces
MAC address Attached to interface
------------------------------------------------------
00:1E:BD:DE:F8:BA VirtualPortGroup0
54:0E:00:0B:0C:03 ieobc_2
 
Guest interface
---
Interface: eth1
ip address: 172.25.223.147/25
 
---
 
Guest routes
---
Address/Mask Next Hop Intf.
-------------------------------------------------------------------------------
0.0.0.0/0 172.25.223.137 eth1
 
---
 
Resource admission (without profile) : passed
Disk space : 540MB
Memory : 512MB
CPU : 30% system CPU
VCPUs : Not specified