Cisco IOS XE REST API Management Reference Guide

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents
Find Matches in This Book
Available Languages

Results

Updated:
February 21, 2018

Chapter: Network Address Translation (NAT)

Network Address Translation (NAT)

Resource Summary for NAT

The attribute “pat” (port address translation) in the REST API is equivalent to the Cisco IOS NAT term “overload”.

HTTP Method
Resource
URL (BaseURL)
GET
POST
PUT
DELETE

NAT pool

/api/v1/nat-svc/pool

Y

Y

N

N

/api/v1/nat-svc/pool/{nat-pool-id}

Y

N

Y

Y

Static NAT

/api/v1/nat-svc/static

Y

Y

N

N

/api/v1/nat-svc/static/{nat-rule-id}

Y

N

Y

Y

Dynamic NAT

Dynamic NAT

/api/v1/nat-svc/dynamic

Y

Y

N

N

/api/v1/nat-svc/dynamic/{nat-rule-id}

Y

N

Y

Y

NAT translations

/api/v1/nat-svc/translations

Y

Y

N

N

NAT Pool Resource

A NAT Pool models a pool of global IP addresses used during dynamic NAT translation.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

Property
Type
Required for POST and PUT
Description

nat-pool-id

string

Mandatory

Unique NAT pool name.

start-ip-address

string

Mandatory

First IP address of public IP address range in the format x.x.x.x

end-ip-address

string

Mandatory

Last IP address of public IP address range in the format x.x.x.x

prefix-length

number

Mandatory

IP Address prefix length

Retrieve a NAT Pool

Resource URI

Verb
URI

GET

/api/v1/nat-svc/pool/{nat-pool-id}

Properties for Retrieve

Property
Type
Description

kind

string

Object type. Always “object#nat-pool”

nat-pool-id

string

Unique NAT pool name.

start-ip-address

string

First IP address of public IP address range in the format x.x.x.x

end-ip-address

string

Last IP address of public IP address range in the format x.x.x.x

prefix-length

number

IP Address prefix length

Example

JSON Request

GET /api/v1/nat-svc/pool/marketing-nat-pool
Accept: application/json

JSON Response

200 ok
Content-type: application/json
{
"kind": "object#nat-pool"
"nat-pool-id": "marketing-nat-pool",
"start-ip-address": "172.16.10.1",
"end-ip-address": "172.16.10.63",
"prefix-length": 24
}

Retrieve All NAT Pools

Resource URI

Verb
URI

GET

/api/v1/nat-svc/pool

Properties for Retrieve All

Property
Type
Description

kind

string

Object type. Always “collection#nat-pool”

items

array

Collection of NAT pools.

nat-pool-id

string

Unique NAT pool name.

start-ip-address

string

First IP address of public IP address range in the format x.x.x.x

end-ip-address

string

Last IP address of public IP address range in the format x.x.x.x

prefix-length

number

IP Address prefix length

Example

JSON Request

GET /api/v1/nat-svc/pool
Accept: application/json

JSON Response

200 ok
Content-type: application/json
{
"kind": "collection#nat-pool"
"items": [
{
"kind": "object#nat-pool",
"nat-pool-id": "marketing",
"start-ip-address": "172.16.10.1",
"end-ip-address": "172.16.10.63",
"prefix-length": 24
},
{
"kind": "object#nat-pool",
"nat-pool-id": "engineering",
"start-ip-address": "172.16.10.63",
"end-ip-address": "172.16.10.100",
"prefix-length": 24
}
]

Modify a NAT Pool

When updating the NAT pool, the old pool is deleted and a new NAT pool is created with the same pool-id, using new parameters.

Resource URI

Verb
URI

PUT

/api/v1/nat-svc/pool/{nat-pool-id}

Example

JSON Request

PUT /api/v1/nat-svc/pool/marketing-nat-pool
Accept: application/json
Content-type: application/json
{
"nat-pool-id": "marketing-nat-pool",
"start-ip-address": "172.16.10.1",
"end-ip-address": "172.16.10.57",
"prefix-length": 24
}

JSON Response

204 No Content
 

Delete a NAT Pool

Resource URI

 

Verb
URI

DELETE

/api/v1/nat-svc/pool/{nat-pool-id}

Example

JSON Request

DELETE /api/v1/nat-svc/pool/marketing-nat-pool
Accept: application/json

JSON Response

204 No Content

Create a NAT Pool

Resource URI

Verb
URI

POST

/api/v1/nat-svc/pool

Example

JSON Request

POST /api/v1/nat-svc/pool
Content-type: application/json
Accept: application/json
{
"nat-pool-id": "marketing-nat-pool",
"start-ip-address": "172.16.10.1",
"end-ip-address": "172.16.10.63",
"prefix-length": 24
}

JSON Response

201 Created
Location: http://host/api/v1/nat-svc/pool/marketing-nat-pool

Static NAT Rule Resource

A static NAT resource models static address translation where there is a one-to-one mapping between local and global IP addresses.

There are three types of one-to-one mapping NAT: static NAT, port static NAT, and network static NAT.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

Property
Type
Description

kind

string

Object type. Always “nat-static-rule”

nat-rule-id

string

Unique NAT rule id

mode

string

Indicates the source/destination IP field and the direction of traffic to apply NAT to. Allowed values are: “inside-source” and “outside-source”.

  • “inside-source” refers to translating the source IP address for packets that enter the router from the inside interface, or to translating the destination address for packets that enter the router from the outside interface.
  • “outside-source” refers to translating the source IP address for packets that enter the router through the outside interface, or to translating the destination IP address of packets that enter the router from the inside interface.

“mode” is optional for ip-network-mapping as the mode can only be “inside-source”.

ip-mapping

object

Specifies IP address based static NAT mapping. Mutually exclusive with ip-port-mapping and network-nat-mapping

ip-mapping-local-ip

ipaddress

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x

ip-mapping-global-ip

ipaddress

Establishes the globally unique IP address of an inside host as it appears to outside world. Specified in the x.x.x.x format

ip-port-mapping

object

Specifies IP address based static NAT mapping. Mutually exclusive with ip-port-mapping and network-nat-mapping.

ip-port-mapping-local-ip

ipaddress

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x

ip-port-mapping-global-ip

ipaddress

Establishes the globally unique IP address of an inside host as it appears to outside world. Specified in the x.x.x.x format

ip-port-mapping-protocol

ipaddress

Protocol used. One of “TCP” or “UDP”. If protocol is not used, this property can be absent.

ip-port-mapping-local-
port

number

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x

ip-port-mapping-global-
port

number

Global TCP/UDP port in the range 1-65535. Mandatory when local-port is used

ip-network-mapping

object

Specifies the subnet/network based static NAT translation

ip-network-mapping-local-network

string

Specifies the local subnet translation.

ip-network-mapping-
global-network

string

Specifies the global subnet translations.

ip-network-mapping-
mask

string

Specifies the IP network mask to be used with subnet translations.

Retrieve a Static NAT Rule

Resource URI

 

Verb
URI

GET

/api/v1/nat-svc/static/{nat-pool-id}

Example

JSON Request

GET /api/v1/nat-svc/static/eng-nat
Accept: application/json

JSON Response of a Static NAT

200 OK
Content-Type: application/json
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "eng-nat",
"mode": "inside-source",
"ip-mapping": {
"local-ip" : "172.16.50.8",
"global-ip" : "172.16.10.8"
}
}

JSON Response of a Port Static NAT Rule

200 OK
Content-Type: application/json
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "eng-nat",
"mode": "inside-source",
"ip-port-mapping":{
"protocol": "tcp",
"local-ip" : "172.16.10.8",
"local-port": 8080,
"global-ip" : "172.16.10.8",
"global-port": 80
}
}

JSON Response of a Network Static NAT

200 OK
Content-Type: application/json
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "eng-nat",
"mode": "outside-source",
"ip-network-mapping":{
"local-network": "10.10.10.0",
"global-network": "172.19.32.0",
"mask": "255.255.255.0"
}
}

Retrieve All Static NAT Rules

Resource URI

 

Verb
URI

GET

/api/v1/nat-svc/static

Properties for Retrieve All

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. Always “collection#nat-static-rule”

items

array

Mandatory

Collection of static NAT rules with objects of type “object#nat-static-rule”

nat-rule-id

string

Mandatory

Unique NAT rule id

mode

string

Mandatory

Indicates the source/destination IP field and the direction of traffic to apply NAT to. Allowed values are: “inside-source” and “outside-source”.

“inside-source” refers to translating source address for packets that enter router through inside.

“outside-source” refers to translating source address for packets that enter router through outside.

ip-mapping

object

Mandatory

Specifies IP address based static NAT mapping. Mutually exclusive with ip-port-mapping and network-nat-mapping.

ip-mapping-local-ip

ipaddress

Mandatory

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x.

ip-mapping-global-ip

ipaddress

Mandatory

Establishes the globally unique IP address of an inside host as it appears to outside world. Specified in the x.x.x.x format.

ip-port-mapping

object

Mandatory

Specifies IP address based static NAT mapping. Mutually exclusive with ip-port-mapping and network-nat-mapping.

ip-port-mapping-local-ip

ipaddress

Mandatory

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x

ip-port-mapping-global-ip

ipaddress

Mandatory

Establishes the globally unique IP address of an inside host as it appears to outside world. Specified in the x.x.x.x format

ip-port-mapping-protocol

ipaddress

Mandatory

Protocol used. One of “TCP” or “UDP”. If protocol is not used, this property can be absent.

ip-port-mapping-local-
port

number

Mandatory

Local IP address assigned to host on the inside network. Specified in the format x.x.x.x

ip-port-mapping-global-
port

number

Mandatory when local-port is used

Global TCP/UDP port in the range 1-65535.

ip-network-mapping

object

Mandatory

Specifies the subnet/network based static NAT translation

ip-network-mapping-local-network

string

Mandatory

Specifies the local subnet translation.

ip-network-mapping-
global-network

N/A

Mandatory

Specifies the global subnet translations.

ip-network-mapping-
mask

string

Mandatory

Specifies the IP network mask to be used with subnet translations.

JSON Representation

{
"kind": "object#nat-static-rule",
"nat-rule-id" : "{string}",
"mode": "{string}",
"ip-mapping": {
"local-ip" : "{ipaddress}",
"global-ip" : "{ipaddress}"
},
"ip-port-mapping":{
"protocol" : "{string}",
"local-ip" : "{ipaddress}",
"local-port": {number},
"global-ip" : "{ipaddress}",
"global-port": {number}
},
"ip-network-mapping":{
"local-network": "{string}",
"global-network": "{string}",
"mask": "{string}"
}
}

Example

JSON Request

GET /api/v1/nat-svc/static
Accept: application/json

JSON Response

200 ok
Content-type: application/json
{
"kind": "collection#nat-static-rule,
"items": [
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "eng-nat",
"mode": "inside-source",
"ip-mapping": {
"local-ip" : "172.16.50.8",
"global-ip": "172.15.15.1"
}
},
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "doc-nat",
"mode": "inside-source",
"ip-port-mapping":{
"protocol": "tcp",
"local-ip" : "172.16.10.7",
"local-port": 8080,
"global-ip" : "172.16.10.8",
"global-port":80
}
},
{
"kind": "object#nat-static-rule",
"nat-rule-id" : "finance-nat",
"mode": "outside-source",
"ip-network-mapping":{
"local-network": "10.10.20.0",
"global-network": "172.19.32.0",
"mask": "255.255.255.0"
}
}
]
}

Modify a Static NAT Rule

Resource URI

 

Verb
URI

PUT

/api/v1/nat-svc/static/{nat-pool-id}

Example Request of a Static NAT Rule

JSON Request

PUT /api/v1/nat-svc/static/eng-nat
Content-type: application/json
Accept: application/json
{
"nat-rule-id" : "eng-nat",
"mode": "inside-source",
"ip-mapping": {
"local-ip" : "172.16.50.8",
"global-ip" : "172.15.15.1"
}
}

Example Request of a Port Static NAT Rule

JSON Request

{
"kind": "object#nat-static-rule",
"nat-rule-id" : "doc-nat",
"mode": "inside-source",
"ip-port-mapping":{
"protocol": "tcp",
"local-ip" : "172.16.10.7",
"local-port": 8080,
"global-ip" : "172.16.10.8",
"global-port": 80
}
}

Example Request of a Network Static NAT

JSON Request

{
"kind": "object#nat-static-rule",
"nat-rule-id" : "finance-nat",
"mode": "outside-source",
"ip-network-mapping":{
"local-network": "10.10.20.0",
"global-network": "172.19.32.0",
"mask": "255.255.255.0"
}
}

JSON Response

204 No Content

Delete a Static NAT Rule

Resource URI

 

Verb
URI

DELETE

/api/v1/nat-svc/static/{nat-pool-id}

Example

JSON Request

DELETE /api/v1/nat-svc/static/marketing-nat-pool
Accept: application/json

JSON Response

204 No Content
 

Create a Static NAT Rule

Resource URI

Verb
URI

POST

/api/v1/nat-svc/static

Example Request of a Static NAT Rule

JSON Request

POST /api/v1/nat-svc/static
Content-type: application/json
Accept: application/json
{
"nat-rule-id" : "eng-nat",
"mode": "inside-source",
"ip-mapping": {
"local-ip" : "172.16.50.8",
"global-ip" : "172.15.15.1"
}
}

Example Request of a Port Static NAT Rule

JSON Request

POST /api/v1/nat-svc/static
Content-type: application/json
Accept: application/json
{
"nat-rule-id" : "doc-nat",
"mode": "inside-source",
"ip-port-mapping":{
"protocol": "tcp",
"local-ip" : "172.16.10.7",
"local-port": 8080,
"global-ip" : "172.16.10.8",
"global-port": 80
}
}

Example Request of a Network Static NAT

JSON Request

POST /api/v1/nat-svc/static
Content-type: application/json
Accept: application/json
{
"nat-rule-id" : "finance-nat",
"mode": "outside-source",
"ip-network-mapping":{
"local-network": "10.10.20.0",
"global-network": "172.19.32.0",
"mask": "255.255.255.0"
}
}

JSON Response

201 Created
Location: http://host/api/v1/nat-svc/static/finance-nat

Dynamic NAT Rule Resource

Packets with source and/or destination addresses that pass the access list are dynamically translated using global addresses from the named pool.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

Property
Type
Required for POST and PUT
Description

kind

string

Mandatory

Object type. Always “object#nat-dynamic-rule”

nat-rule-id

string

Mandatory

Unique NAT rule id

mode

string

Mandatory

Indicates the source/destination IP field and the direction of traffic to apply NAT to. Allowed values are: “inside-source” and “outside-source” & “inside-destination”

“inside-source” refers to translating source address for packets that enter router through inside.

“outside-source” refers to translating source address for packets that enter router through outside.

“inside-destination” refers to translating destination address for packets that enter router through inside

acl-id

name

Mandatory

ACL resource id that defines the ACL for this dynamic NAT

nat-pool-id

string

Mandatory

NAT pool to use. Refers to the NAT pool resource id.

pat-enabled

boolean

Optional

Specifies if Port Address translation to be enabled.

JSON Representation

{
"kind": "object#nat-dynamic-rule",
"nat-rule-id" : "{string}",
"mode": "{string}",
"acl-id" : {number},
"nat-pool-id" : "{string}",
"pat-enabled": {boolean}
}

Retrieve a Dynamic NAT Rule

Resource URI

 

Verb
URI

GET

/api/v1/nat-svc/dynamic/{nat-rule-id}

Example

JSON Request

GET /api/v1/nat-svc/dynamic/dyn-nat
Accept: application/json

JSON Response

200 ok
Content-type: application/json
{
"kind" : "object#nat-dynamic-rule"
"nat-rule-id" : "dyn-nat",
"mode" : "outside-source",
"acl-id" : "natacl",
"nat-pool-id" : "nat-pool",
"pat-enabled" : false
}

Retrieve All Dynamic NAT Rules

Resource URI

Verb
URI

GET

/api/v1/nat-svc/dynamic

Properties for Retrieve All

Property
Type
Required for POST and PUT
Description

kind

string

Mandatory

Object type. Always “collection#nat-dynamic-rule”

items

array

Mandatory

Collection of nat-dynamic-rule objects

nat-rule-id

string

Mandatory

Unique NAT rule id

mode

string

Mandatory

Indicates the source/destination IP field and the direction of traffic to apply NAT to. Allowed values are: “inside-source” and “outside-source” & “inside-destination”

“inside-source” refers to translating source address for packets that enter router through inside.

“outside-source” refers to translating source address for packets that enter router through outside.

“inside-destination” refers to translating destination address for packets that enter router through inside

acl-id

name

Mandatory

ACL resource id that defines the ACL for this dynamic NAT

nat-pool-id

string

Mandatory

NAT pool to use. Refers to the NAT pool resource id.

pat-enabled

boolean

Optional

Specifies if Port Address translation to be enabled.

JSON Representation

{
"kind" : "collection#nat-dynamic-rule"
"items" :
[
{dynamic nat rule json object}+
]
}

Example

JSON Request

GET /api/v1/nat-svc/dynamic
Accept: application/json

JSON Response

200 OK
Content-type: application/json
{
"kind": "collection#nat-dynamic-rule",
"items": [
{
"kind": "object#nat-dynamic-rule",
"nat-rule-id" : "dyn-nat1",
"mode": "outside-source",
"acl-id" : "eng-acl",
"nat-pool-id" : "nat-pool",
"pat-enabled": true
},
{
"kind": "object#nat-dynamic-rule",
"nat-rule-id" : "dyn-nat2",
"mode": "outside-source",
"acl-id" : "mktg-acl",
"nat-pool-id" : "natPool",
"pat-enabled": false
}
]
}

JSON Response

204 No Content

Modify a Dynamic NAT Rule

Resource URI

 

Verb
URI

PUT

/api/v1/nat-svc/dynamic/{nat-rule-id}

Example

JSON Request

PUT /api/v1/nat-svc/dynamic/dyn-nat
Content-type: application/json
Accept: application/json
{
"nat-rule-id" : "dyn-nat",
"mode": "outside-source",
"acl-id" : "natacl",
"nat-pool-id" : "nat-pool",
"pat-enabled": true
}

JSON Response

204 No Content

Delete a Dynamic NAT Rule

Resource URI

 

Verb
URI

DELETE

/api/v1/nat-svc/dynamic/{nat-rule-id}

Example

JSON Request

DELETE /api/v1/nat-svc/dynamic/dyn-nat
Accept: application/json

JSON Response

204 No Content

Create a Dynamic NAT Rule

Resource URI

 

Verb
URI

POST

/api/v1/nat-svc/dynamic

Example

JSON Request

POST /api/v1/nat-svc/dynamic
Accept: application/json
Content-type: application/json
{
"nat-rule-id" : "dyn-nat1",
"mode": "outside-source",
"acl-id" : "qa-acl",
"nat-pool-id" : "nat-pool",
"pat-enabled": true
}

JSON Response

201 Created
Location: http://host/api/v1/nat-svc/dynamic/dyn-nat-1

NAT Translations Resource

NAT Translation resource represents the active NAT translations.

This resource supports only:

  • Retrieve all NAT translations: All relevant properties are shown in the tables below.
  • Clear all NAT translations: Uses the POST operation and an action property described in Clear All NAT Translations .

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

Property
Type
Description

kind

string

Object type. Always “collection#nat-translation”

items [ ]

array

Collection of NAT translation objects

Property
Type
Description

kind

string

Object type. Always “object#nat-translation”

protocol

string

Protocol of the port identifying the address.

inside-global-address

ipaddress

The legitimate IP address that represents one or more inside local IP addresses to the outside world.

inside-local-address

ipaddress

The IP address assigned to a host on the inside network

inside-global-port

number

The port identifying the inside global address.

inside-local-port

number

The port identifying the inside local address

outside-local-address

ipaddress

IP address of an outside host as it appears to the inside network

outside-global-address

ipaddress

The port identifying the outside local address.

outside-local-port

number

The port identifying the outside local address.

outside-global-port

number

The port identifying the outside global address.

JSON Representation

{
"kind": "collection#nat-translation"
"items": [
{
"kind" : "object#nat-translation",
"protocol" : "{string}",
"inside-global-address" : "{ipaddress}",
"inside-global-port" : {number},
"inside-local-address" : "{ipaddress}",
"inside-local-port" : {number},
"outside-global-address" : "{ipaddress}",
"outside-global-port" : {number},
"outside-local-address" : "{ipaddress}",
"outside-local-port" : {number}
},
]
}

Retrieve All NAT Translations

Resource URI

 

Verb
URI

GET

/api/v1/nat-svc/translations

Example

JSON Request

GET /api/v1/nat-svc/translations
Accept: application/json

JSON Response

200 ok
Content-type: application/json
{
"kind": "collection#nat-translation",
"items": [
{
"kind": "object#nat-translation",
"protocol": "TCP",
"inside-global-address" : "172.16.223.288",
"inside-global-port" : 0,
"inside-local-address" : "192.168.1.95",
"inside-local-port" : 0,
"outside-global-address" : "",
"outside-global-port" : 0,
"outside-local-address" : "",
"outside-local-port" : 0
},
{
"kind": "object#nat-translation",
"protocol": "TCP",
"inside-global-address" : "172.16.233.209",
"inside-global-port" : 11012,
"inside-local-address" : "192.168.1.89",
"inside-local-port" : 11012,
"outside-global-address" : "172.16.1.220",
"outside-global-port" : 23,
"outside-local-address" : "172.16.1.220",
"outside-local-port" : 23
},
]
}

Clear All NAT Translations

The NAT translations resource supports the clearing of active translations and all automatic bindings on the router. Use POST as shown below.

Note The action property is applicable only for this operation.

Properties for the POST Operation

Property
Type
Required for POST and PUT
Description

action

string

Mandatory

“clear”

Clears active translations and automatic bindings on the router.

Example

JSON Request

POST /api/v1/nat-svc/translations
Accept: application/json
{
"action": "clear"
}

JSON Response

204 No Content

Was this Document Helpful?

FeedbackFeedback

Contact Cisco