Enabling Management by REST API

Introduction

You can use the Cisco IOS XE 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 Cisco IOS XE REST API Management Reference Guide.


Note

REST API is not supported from the IOS-XE 16.7.x release onwards. If you are using the 16.7.x version or above, Cisco recommends that you use Restconf. For more information on using Restconf, see the Restconf documentation.

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. The tables below 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 to the VM section in this guide.

Table 1. 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.

Table 2. Cisco CSR 1000v OVA Template Bootstrap Properties Required for REST API Support (Cisco IOS XE Release 3.11S 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 Default Gateway

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

Remote Management IPv4 Address(not used if configuring the shared management interface to support REST API).

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.

Table 3. 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.

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 if you installed the Cisco CSR 1000v in either of the following ways:

  • 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 later release, you must add your REST API configuration to the IOS configuration.

Before configuring the shared management interface, perform the steps in Enabling REST API Support.

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 steps for each of these are in the following two sections:

The remainder of this section contains information about:

Enabling REST API Support

Beginning with Cisco IOS XE Release 3.11S, and including IOS XE Denali 16.3.1 and later, you can enable REST API support on the remote management interface. To disable REST API support, see Disabling REST API Support. To enable the REST API, perform the following steps.

SUMMARY STEPS

  1. enable
  2. configure terminal
  3. remote-management
  4. 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

restful-api

Example:


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

Enables support for the REST API.

Step 5

end

Example:


router(cfg-remote-mgmt)# end

Exits remote-management configuration mode and enters configuration mode.

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 subnet-mask
  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

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 mgmt-interface

Example:


Router(config)# interface gigabitethernet1

Enters interface configuration mode for the management interface.

Step 4

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

virtual-service csr_mgmt

Example:


router(config)# virtual-service csr_mgmt

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

Step 8

no activate

Example:


router(config-virt-serv)# no activate

Deactivates the csr_mgmt virtual services container.

Step 9

ip shared host-interface mgmt-interface

Example:


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

Maps the virtual service container to the management interface.

Step 10

activate

Example:


router(config-virt-serv)# activate

Activates the csr_mgmt virtual services container.

Step 11

end

Example:


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 GigabitEthernet x
  4. ip address ipv4-addr subnet-mask
  5. no shutdown
  6. exit
  7. interface virtualportgroup virtualportgroup-number
  8. ip unnumbered GigabitEthernet x
  9. no shutdown
  10. exit
  11. virtual-service csr_mgmt
  12. vnic gateway virtualportgroup virtualportgroup_number
  13. guest ip address remote-mgmt-ipv4-addr
  14. exit
  15. end
  16. 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

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 9

no shutdown

Example:


router(config-if)# no shutdown

Enables the virtual port group interface.

Step 10

exit

Example:


router(config-if)# exit

Exits virtual port group interface mode.

Step 11

virtual-service csr_mgmt

Example:


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

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 13

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 14

exit

Example:


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

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

Step 15

end

Example:


router(config-virt-serv)# end

Exits virtual services configuration mode and enters global configuration mode.

Step 16

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 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 HTTPS Support for the REST API Using the Cisco IOS XE CLI

The 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

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

ip http secure-server

Example:


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

Example:


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

Creates and names a persistent web user interface transport map.

Step 5

secure-server

Example:


router(config)# secure-server

Enables the secure HTTPS server.

Step 6

transport type persistent webui input transport-map-name

Example:


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, and including IOS XE Denali 16.3.1 and later, you can disable REST API support on the remote management interface. To enable REST API support, see Enabling REST API Support. To disable the REST API, perform the following steps.

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.

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