Enabling Management by REST API

Introduction

You can use the Cisco IOS XE REST API to manage the Cisco ASR 1001-X and ASR 1002-X as an alternative to configuring and managing selected features on the router using the Cisco IOS XE CLI. This chapter describes how to configure these Cisco ASR routers to enable management using the REST API. For detailed information about using the REST API, see the Cisco IOS XE REST API Management Reference Guide.

Overview of Installation

Installing the Cisco IOS XE REST API involves the following general steps:

1. Download the OVA package from Cisco.com.

a. From the Cisco Routers product page, navigate to the Cisco CSR 1000V Cloud Services Router product page.
http://www.cisco.com/c/en/us/products/routers/cloud-services-router-1000v-series/index.html

b. Click the “Download Software” link.

c. Select the Cisco IOS XE release package and follow the instructions for downloading the software.

2. Install the REST API OVA on the ASR platform.

3. Enable the REST API on the ASR platform. In the Enabling REST API Support Using the Cisco IOS XE CLI section, see:

Enabling REST API Support Using the Cisco IOS XE CLI

Configuring the Data Plane Dual Management Interface to Support the REST API

Beginning with Cisco IOS XE 3.16, it is possible to associate management container IP addresses with either:

  • Data plane interface (see procedure below)

or

Configuration Notes

Management Container IP Addresses in Subnet of Router Management Interface

To allocate the management container IP addresses to be associated with the router’s management interface, ensure that the IP addresses configured for the management container are within the same subnet as the router’s management interface. For example:

Management container IP address: 192.168.5.225

Router management interface: 192.168.5.224

Order of Configuring Gateway Port, Management Interface, and IP Addresses

Configuring the management container details in the following order:

1. vNIC gateway port (vnic gateway virtualportgroup0)

2. Guest IP addresses

The vNIC management interface (vnic management GigabitEthernet0) can be configured after the guest IP addresses.

SUMMARY STEPS

1. enable

2. configure terminal

3. interface GigabitEthernet x

4. ip address ipv4-addr subnet-mask

5. no shutdown

6. exit

7. interface virtualportgroup virtual-port-group-number

8. configure terminal

9. interface virtualportgroup 0

10. ip unnumbered GigabitEthernet0/0/0

11. exit

12. ip route ipv4-address ipv4-subnet-mask VirtualPortGroup0

13. exit

14. ip unnumbered GigabitEthernet x

15. no shutdown

16. exit

17. virtual-service csr_mgmt

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

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

20. exit

21. vnic management GigabitEthernet0

22. exit

23. activate

24. end

25. 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 GigabitEthernet x

 

Router(config)# interface gigabitethernet1

Enters interface configuration mode for the interface designated by x.

The range of GigabitEthernet ports depends on the platform.

Step 4

ip address 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

configure terminal

 

Router(config)# configure terminal

Enter interface configuration mode.

Step 9

interface virtualportgroup 0

 

Router(config)# interface virtualportgroup 0

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

Step 10

ip unnumbered GigabitEthernet0/0/0

 

Router(config)# ip unnumbered GigabitEthernet0/0/0

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

Step 11

exit

 

Router(config)# exit

Exit interface configuration mode.

Step 12

ip route ipv4-address ipv4-subnet-mask VirtualPortGroup0

 

Router# ip route 172.27.208.108 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.

Step 13

exit

 

Router# exit

Exit configuration mode.

Step 14

ip unnumbered GigabitEthernet x

 
router(config-if)# ip unnumbered gigabitethernet1

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

Step 15

no shutdown

 

router(config-if)# no shutdown

Enables the virtual port group interface.

Step 16

exit

 
router(config-if)# exit

Exits virtual port group interface mode.

Step 17

virtual-service csr_mgmt

 

router(config)# virtual-service csr_mgmt

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

Step 18

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 19

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 20

exit

 

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

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

Step 21

vnic management GigabitEthernet0

 

router(config-virt-serv)# vnic management GigabitEthernet0

(Cisco IOS XE 3.16S and later only)

Beginning with Cisco IOS XE 3.16S, it is necessary to configure two vnic interfaces:

  • vnic gateway
  • vnic management

Step 22

exit

 

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

Exits vNIC management mode.

Step 23

activate

 

router(config-virt-serv-vnic)# activate

Activates the csr_mgmt virtual services container.

Step 24

end

 

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 25

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 Management Plane Dual Management Interface to Support the REST API

Beginning with Cisco IOS XE 3.16, it is possible to associate management container IP addresses with either:

  • Management plane interface (see procedure below)

or

Configuration Notes

Management Container IP Addresses in Subnet of Router Management Interface

To allocate the management container IP addresses to be associated with the router’s management interface, ensure that the IP addresses configured for the management container are within the same subnet as the router’s management interface. For example:

Management container IP address: 192.168.5.225

Router management interface: 192.168.5.224

Order of Configuring Gateway Port, Management Interface, and IP Addresses

Configuring the management container details in the following order:

1. vNIC gateway port (vnic gateway virtualportgroup0)

2. vNIC management interface (vnic management GigabitEthernet0)

3. Guest IP addresses

In contrast to the related procedure that uses the data plane interface, in this case, the vNIC management interface must be configured before configuring guest IP addresses.

SUMMARY STEPS

1. enable

2. configure terminal

3. interface GigabitEthernet x

4. ip address ipv4-addr subnet-mask

5. no shutdown

6. exit

7. interface virtualportgroup virtual-port-group-number

8. configure terminal

9. interface virtualportgroup 0

10. ip unnumbered GigabitEthernet0/0/0

11. exit

12. ip unnumbered GigabitEthernet x

13. no shutdown

14. exit

15. virtual-service csr_mgmt

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

17. exit

18. guest ip address guest-mgmt-ipv4-address

19. vnic management GigabitEthernet0

20. exit

21. activate

22. end

23. 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 GigabitEthernet x

 

Router(config)# interface gigabitethernet1

Enters interface configuration mode for the interface designated by x.

The range of GigabitEthernet ports depends on the platform.

Step 4

ip address 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

configure terminal

 

Router(config)# configure terminal

Enter interface configuration mode.

Step 9

interface virtualportgroup 0

 

Router(config)# interface virtualportgroup 0

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

Step 10

ip unnumbered GigabitEthernet0/0/0

 

Router(config)# ip unnumbered GigabitEthernet0/0/0

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

Step 11

exit

 

Router(config)# exit

Exit interface configuration mode.

Step 12

ip unnumbered GigabitEthernet x

 
router(config-if)# ip unnumbered gigabitethernet1

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

Step 13

no shutdown

 

router(config-if)# no shutdown

Enables the virtual port group interface.

Step 14

exit

 
router(config-if)# exit

Exits virtual port group interface mode.

Step 15

virtual-service csr_mgmt

 

router(config)# virtual-service csr_mgmt

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

Step 16

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 17

exit

 

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

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

Step 18

vnic management GigabitEthernet0

 

router(config-virt-serv)# vnic management GigabitEthernet0

(Cisco IOS XE 3.16S and later only)

Beginning with Cisco IOS XE 3.16S, it is necessary to configure two vnic interfaces:

  • vnic gateway
  • vnic management

Step 19

guest ip address guest-mgmt-ipv4-address

 

guest ip address 172.27.141.225

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

Step 20

exit

 

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

Exits vNIC management mode.

Step 21

activate

 

router(config-virt-serv)# activate

Activates the csr_mgmt virtual services container.

Step 22

end

 

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 23

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 Release 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 55443

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 55443.

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 onep

The Open Network Environment Programming Interface (onep) is used to define the service set for Cisco IOS and the REST API. Configure onep as follows.

SUMMARY STEPS

1. conf t

2. onep

3. service set vty

4. end

DETAILED STEPS

 

Command or Action
Purpose

Step 1

conf t

 

asr1k# conf t

Enter configuration commands, one per line. End with CNTL/Z.

Enters configuration mode.

Step 2

onep

 

asr1k(config)#onep

Enters onep mode.

Step 3

service set vty

 

asr1k(config-onep)#service set vty

Select the vty service set.

Step 4

end

 

asr1k(config-onep)#end

asr1k#

Exit onep mode.

Disabling REST API Support

Support for the REST API is enabled by default. The following procedure disables the REST API.

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

Use the show virtual-service detail command to view the REST API container status.