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 GigabitEthernetx

    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 GigabitEthernetx

    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 ActionPurpose
    Step 1enable


    Example:
    Router> enable
     

    Enables privileged EXEC mode.

    • Enter your password if prompted.
     
    Step 2configure terminal


    Example:
    Router# configure terminal
     

    Enters global configuration mode.

     
    Step 3interface GigabitEthernetx


    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 4ip 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 5no shutdown


    Example:
    Router(config-if)# no shutdown
     

    Enables the management interface.

     
    Step 6exit


    Example:
    Router(config-if)# exit
     

    Exits interface configuration mode.

     
    Step 7interface virtualportgroup virtualportgroup-number


    Example:
    Router(config)# interface virtualportgroup 0
     

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

     
    Step 8configure terminal


    Example:
    Router(config)# configure terminal
     

    Enter interface configuration mode.

     
    Step 9interface virtualportgroup 0


    Example:
    Router(config)# interface virtualportgroup 0
     

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

     
    Step 10ip 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 11exit


    Example:
    Router(config)# exit
     

    Exit interface configuration mode.

     
    Step 12ip 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 13exit


    Example:
    Router# exit
     

    Exit configuration mode.

     
    Step 14ip unnumbered GigabitEthernetx


    Example:
    router(config-if)# ip unnumbered gigabitethernet1
     

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

     
    Step 15no shutdown


    Example:
    router(config-if)# no shutdown
     

    Enables the virtual port group interface.

     
    Step 16exit


    Example:
    router(config-if)# exit
     

    Exits virtual port group interface mode.

     
    Step 17virtual-service csr_mgmt


    Example:
    router(config)# virtual-service csr_mgmt
     

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

     
    Step 18vnic 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 19guest 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 20exit


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

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

     
    Step 21vnic 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 22exit


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

    Exits vNIC management mode.

     
    Step 23activate


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

    Activates the csr_mgmt virtual services container.

     
    Step 24end


    Example:
    router(config-virt-serv)# end
     

    Exits virtual services configuration mode and enters global configuration mode.

     
    Step 25ip 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 GigabitEthernetx

      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 GigabitEthernetx

      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 ActionPurpose
      Step 1enable


      Example:
      Router> enable
       

      Enables privileged EXEC mode.

      • Enter your password if prompted.
       
      Step 2configure terminal


      Example:
      Router# configure terminal
       

      Enters global configuration mode.

       
      Step 3interface GigabitEthernetx


      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 4ip 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 5no shutdown


      Example:
      Router(config-if)# no shutdown
       

      Enables the management interface.

       
      Step 6exit


      Example:
      Router(config-if)# exit
       

      Exits interface configuration mode.

       
      Step 7interface virtualportgroup virtualportgroup-number


      Example:
      Router(config)# interface virtualportgroup 0
       

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

       
      Step 8configure terminal


      Example:
      Router(config)# configure terminal
       

      Enter interface configuration mode.

       
      Step 9interface virtualportgroup 0


      Example:
      Router(config)# interface virtualportgroup 0
       

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

       
      Step 10ip 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 11exit


      Example:
      Router(config)# exit
       

      Exit interface configuration mode.

       
      Step 12ip unnumbered GigabitEthernetx


      Example:
      router(config-if)# ip unnumbered gigabitethernet1
       

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

       
      Step 13no shutdown


      Example:
      router(config-if)# no shutdown
       

      Enables the virtual port group interface.

       
      Step 14exit


      Example:
      router(config-if)# exit
       

      Exits virtual port group interface mode.

       
      Step 15virtual-service csr_mgmt


      Example:
      router(config)# virtual-service csr_mgmt
       

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

       
      Step 16vnic 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 17exit


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

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

       
      Step 18vnic 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 19guest 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 20exit


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

      Exits vNIC management mode.

       
      Step 21activate


      Example:
      router(config-virt-serv)# activate
       

      Activates the csr_mgmt virtual services container.

       
      Step 22end


      Example:
      router(config-virt-serv)# end
       

      Exits virtual services configuration mode and enters global configuration mode.

       
      Step 23ip 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 ActionPurpose
        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 ActionPurpose
          Step 1 conf t

          Example:
          asr1k#conf t


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

          Enters configuration mode.

           
          Step 2onep


          Example:
          asr1k(config)#onep
           

          Enters onep mode.

           
          Step 3service set vty


          Example:
          asr1k(config-onep)#service set vty
           

          Select the vty service set.

           
          Step 4end


          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 ActionPurpose
            Step 1enable


            Example:
            router> enable
             

            Enables privileged EXEC mode.

            • Enter your password if prompted.
             
            Step 2configure terminal


            Example:
            router# configure terminal
             

            Enters global configuration mode.

             
            Step 3remote-management


            Example:
            router(config)# remote-management
             

            Enters remote-management configuration mode.

             
            Step 4no restful-api


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

            Disables support for the REST API.

             
            Step 5end


            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.