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 {start cross reference}Cisco IOS XE REST API Management Reference Guide{end cross reference}.

Overview of Installation

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

  1. Download the OVA package from Cisco.com.
    1. From the Cisco Routers product page, navigate to the Cisco CSR 1000V Cloud Services Router product page.{start hypertext}http://www.cisco.com/c/en/us/products/routers/cloud-services-router-1000v-series/index.html{end hypertext}
    2. Click the “Download Software” link.
    3. 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.

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

  • Management plane interface (see {start cross reference}Configuring the Management Plane Dual Management Interface to Support the REST API{end cross reference})

Configuration Notes

{start blocklabel}Management Container IP Addresses in Subnet of Router Management Interface{end blocklabel}

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

{start blocklabel}Order of Configuring Gateway Port, Management Interface, and IP Addresses{end blocklabel}

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 virtualportgroup-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 virtualportgroup_number
  19. guest ip address remote-mgmt-ipv4-addr
  20. exit
  21. vnic management GigabitEthernet0
  22. exit
  23. activate
  24. end
  25. ip route ipaddress subnetmask virtualportgroup virtualportgroupnumber

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.
Step 2

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 3

interface GigabitEthernet x

Example:

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

Example:

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

Example:

Router(config-if)# no shutdown

Enables the management interface.

Step 6

exit

Example:

Router(config-if)# exit

Exits interface configuration mode.

Step 7

interface virtualportgroup virtualportgroup-number

Example:

Router(config)# interface virtualportgroup 0

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

Step 8

configure terminal

Example:

Router(config)# configure terminal

Enter interface configuration mode.

Step 9

interface virtualportgroup 0

Example:

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

Example:

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

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

Step 11

exit

Example:

Router(config)# exit

Exit interface configuration mode.

Step 12

ip route ipv4-address ipv4-subnet-mask VirtualPortGroup0

Example:

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

Example:

Router# exit

Exit configuration mode.

Step 14

ip unnumbered GigabitEthernet x

Example:

router(config-if)# ip unnumbered gigabitethernet1

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

Step 15

no shutdown

Example:

router(config-if)# no shutdown

Enables the virtual port group interface.

Step 16

exit

Example:

router(config-if)# exit

Exits virtual port group interface mode.

Step 17

virtual-service csr_mgmt

Example:

router(config)# virtual-service csr_mgmt

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

Step 18

vnic gateway virtualportgroup virtualportgroup_number

Example:

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

Example:

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

Example:

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

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

Step 21

vnic management GigabitEthernet0

Example:

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

Example:

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

Exits vNIC management mode.

Step 23

activate

Example:

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

Activates the csr_mgmt virtual services container.

Step 24

end

Example:

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 25

ip route ipaddress subnetmask virtualportgroup virtualportgroupnumber

Example:

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

  • Data plane interface (see {start cross reference}Configuring the Data Plane Dual Management Interface to Support the REST API){end cross reference}

Configuration Notes

{start blocklabel}Management Container IP Addresses in Subnet of Router Management Interface{end blocklabel}

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

{start blocklabel}Order of Configuring Gateway Port, Management Interface, and IP Addresses{end blocklabel}

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 virtualportgroup-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 virtualportgroup_number
  17. exit
  18. vnic management GigabitEthernet0
  19. guest ip address guest-mgmt-ipv4-address
  20. exit
  21. activate
  22. end
  23. ip route ipaddress subnetmask virtualportgroup virtualportgroupnumber

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.
Step 2

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 3

interface GigabitEthernet x

Example:

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

Example:

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

Example:

Router(config-if)# no shutdown

Enables the management interface.

Step 6

exit

Example:

Router(config-if)# exit

Exits interface configuration mode.

Step 7

interface virtualportgroup virtualportgroup-number

Example:

Router(config)# interface virtualportgroup 0

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

Step 8

configure terminal

Example:

Router(config)# configure terminal

Enter interface configuration mode.

Step 9

interface virtualportgroup 0

Example:

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

Example:

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

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

Step 11

exit

Example:

Router(config)# exit

Exit interface configuration mode.

Step 12

ip unnumbered GigabitEthernet x

Example:

router(config-if)# ip unnumbered gigabitethernet1

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

Step 13

no shutdown

Example:

router(config-if)# no shutdown

Enables the virtual port group interface.

Step 14

exit

Example:

router(config-if)# exit

Exits virtual port group interface mode.

Step 15

virtual-service csr_mgmt

Example:

router(config)# virtual-service csr_mgmt

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

Step 16

vnic gateway virtualportgroup virtualportgroup_number

Example:

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

Example:

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

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

Step 18

vnic management GigabitEthernet0

Example:

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

Example:

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

Example:

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

Exits vNIC management mode.

Step 21

activate

Example:

router(config-virt-serv)# activate

Activates the csr_mgmt virtual services container.

Step 22

end

Example:

router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 23

ip route ipaddress subnetmask virtualportgroup virtualportgroupnumber

Example:

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

Example:


router(config)# remote-management

Enters remote-management configuration mode.

Step 2

restful-api local-port local-port-number

Example:


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

Example:


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

Example:


asr1k#conf t

Example:


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

Enters configuration mode.

Step 2

onep

Example:


asr1k(config)#onep

Enters onep mode.

Step 3

service set vty

Example:


asr1k(config-onep)#service set vty

Select the vty service set.

Step 4

end

Example:


asr1k(config-onep)#end

Example:


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

Example:


router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.
Step 2

configure terminal

Example:


router# configure terminal

Enters global configuration mode.

Step 3

remote-management

Example:


router(config)# remote-management

Enters remote-management configuration mode.

Step 4

no restful-api

Example:


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

Disables support for the REST API.

Step 5

end

Example:


router(cfg-remote-mgmt)# end

Exits remote-management configuration mode and enters configuration mode.

What to do next


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.