Cisco IOS XE REST API Management Reference Guide

Resource Summary for ACL
ACL Resource
All ACL Match Statistics Resource
- Retrieve All ACL Statistics
Single ACL Match Statistics Resource
- Retrieve Statistics for a Single ACL
ACL Associated with an Interface Resource

ACL Requirements for Subnets or IP Ranges

Resource Summary for ACL

		HTTP Method
Resource	URL (BaseURL)	GET	POST	PUT	DELETE
ACL	/api/v1/acl	Y	Y	N	N
	/api/v1/acl/{acl-id}	Y	N	Y	Y
	/api/v1/acl/statistics	Y	N	N	N
	/api/v1/acl/statistics/{acl-id}	Y	Y	N	N
	/api/v1/acl/{acl-id}/interfaces	Y	Y	N	N
	/api/v1/acl/{acl-id}/interfaces/{if-id_direction}	Y	N	N	Y

ACL Resource

History

Release	Modification
IOS XE 3.10	Introduced for the CSR1000V platform
IOS XE 3.11	Added properties: icmp-options icmp-types icmp-code dscp log
IOS XE 3.14	Introduced for ASR1001-X and ASR1002-X platforms

Properties

Property	Type	Required for POST and PUT	Description
kind	string	Optional	Object type. Has the fixed value "object#acl"
acl-id	string	Optional	ACL name (not a number).
description	string	Optional	ACL Description
rules	array	Mandatory	Contains zero or more access control rule objects
rules[ ].sequence	string	Mandatory	Sequence number to order the rules and serves as a rule ID.
rules[ ].protocol	string	Mandatory	A protocol number or any of the keywords "all", "tcp", "udp", "icmp", "ip"
rules[ ].source	cidr_address	Mandatory	Traffic source in cidr format, hostname, host IP, or keyword "any"
rules[ ].destination	cidr_address	Mandatory	Traffic destination in cidr format, hostname, host IP, or keyword "any". The default is "any".
rules[ ].action	string	Mandatory	Allow or deny if traffic matches the rule
rules[ ].l4-options	object	Optional	Options applicable for tcp/udp protocols
– rules[ ].l4-options.src-port-start – rules[ ].l4-options.src-port-end	string	Mandatory	A source port number 0-65535, starting and ending source port-range, or one of the following source ports can be configured: bgp Border Gateway Protocol (179) chargen Character generator (19) cmd Remote commands (rcmd, 514) connectedapps-plain ConnectedApps Cleartext (15001) connectedapps-tls ConnectedApps TLS (15002) daytime Daytime (13) discard Discard (9) domain Domain Name Service (53) echo Echo (7) exec Exec (rsh, 512) finger Finger (79) ftp File Transfer Protocol (21) ftp-data FTP data connections (20) gopher Gopher (70) hostname NIC hostname server (101) ident Ident Protocol (113) irc Internet Relay Chat (194) klogin Kerberos login (543) kshell Kerberos shell (544) login Login (rlogin, 513) lpd Printer service (515) msrpc MS Remote Procedure Call (135) nntp Network News Transport Protocol (119) pim-auto-rp PIM Auto-RP (496) pop2 Post
			Office Protocol v2 (109) pop3 Post Office Protocol v3 (110) smtp Simple Mail Transport Protocol (25) sunrpc Sun Remote Procedure Call (111) syslog Syslog (514) tacacs TAC Access Control System (49) talk Talk (517) telnet Telnet (23) time Time (37) uucp Unix-to-Unix Copy Program (540) whois Nicname (43) www World Wide Web (HTTP, 80)
rules[ ].l4-options.dst-port-end	string	Optional	A destination port number (0-65535), starting and ending destination port-range, or one of the following destination ports can be configured: <0-65535> Port number bgp Border Gateway Protocol (179) chargen Character generator (19) cmd Remote commands (rcmd, 514) connectedapps-plain ConnectedApps Cleartext (15001) connectedapps-tls ConnectedApps TLS (15002) daytime Daytime (13) discard Discard (9) domain Domain Name Service (53) echo Echo (7) exec Exec (rsh, 512) finger Finger (79) ftp File
			Transfer Protocol (21) ftp-data FTP data connections (20) gopher Gopher (70) hostname NIC hostname server (101) ident Ident Protocol (113) irc Internet Relay Chat (194) klogin Kerberos login (543) kshell Kerberos shell (544) login Login (rlogin, 513) lpd Printer service (515) msrpc MS Remote Procedure Call (135) nntp Network News Transport Protocol (119) pim-auto-rp PIM Auto-RP (496) pop2 Post Office Protocol v2 (109) pop3 Post Office Protocol v3 (110) smtp Simple Mail Transport Protocol (25) sunrpc Sun Remote Procedure Call (111) syslog Syslog (514) tacacs TAC Access Control System (49) talk Talk (517) telnet Telnet (23) time Time (37) uucp Unix-to-Unix Copy Program (540) whois Nicname (43) www World Wide Web (HTTP, 80)
rules[ ].l4-options.src-port-op rules[ ].l4-optionsdest-port-op	string	Mandatory	Indicates how the port number should be matched. One of the keywords "eq", "gt", "lt". If omitted, defaults to "eq"
rules[].icmp-options	object	Optional	Options applicable for ICMP protocol based rules
– icmp-type	string or number	Mandatory	ICMP message type (echo, echo-reply, fragment, etc) http://www.nthelp.com/icmp.html
– icmp-code	number	Mandatory	ICMP message code
– dscp	string or number	Optional	Differentiated Services Codepoint value.
– log	boolean	Optional	This is for debugging.

JSON Representation

{

"kind": "object#acl",

"acl-id": "{string}",

"description": "{string}",

"rules": [

/* ace/rule */

"sequence" : {number},

"protocol": "{string}",

"source": "{string}",

"destination": "{string}",

"action": "{string}",

"l4-options" : {

"src-port-start": "{string}",

"src-port-end": "{string}",

"src-port-op" : "{string}",

"dest-port-start": "{string}",

"dest-port-end" : "{string}",

"dest-port-op": "{string}",

"log": {boolean},

"icmp-options" : {

"icmp-type" : {string or number},

"icmp-code" : {number}

"dscp": "{string or number}"

ICMP Options

Option	ICMP Message Type	Type
{0-255}
administratively-prohibited	Administratively prohibited
alternate-address	Alternate address	6
conversion-error	Datagram conversion	31
dod-host-prohibited	Host prohibited
dod-net-prohibited	Net prohibited
dscp	Match packets with given dscp value
echo	Echo (ping)	8
echo-reply	Echo reply	0
fragments	Check non-initial fragments
general-parameter-problem	Parameter problem
host-isolated	Host isolated
host-precedence-unreachable	Host unreachable for precedence
host-redirect	Host redirect
host-tos-redirect	Host redirect for TOS
host-tos-unreachable	Host unreachable for TOS
host-unknown	Host unknown

DSCP Values

DSCP Option	Differentiated Service	Codepoint Value	Decimal Value
{0-63}
default	Match packets with default dscp	000000	0
af11	Match packets with AF11 dscp	001010	10
af12	Match packets with AF12 dscp	001100	12
af13	Match packets with AF13 dscp	001110	14
af21	Match packets with AF21 dscp	010010	18
af22	Match packets with AF22 dscp	010100	20
af23	Match packets with AF23 dscp	010110	22
af31	Match packets with AF31 dscp	011010	26
af32	Match packets with AF32 dscp	011100	28
af33	Match packets with AF33 dscp	011110	30
af41	Match packets with AF41 dscp	100010	34
af42	Match packets with AF42 dscp	100100	36
af43	Match packets with AF43 dscp	100110	38
cs1	Match packets with CS1(precedence 1) dscp	001000	8
cs2	Match packets with CS2(precedence 2) dscp	010000	16
cs3	Match packets with CS3(precedence 3) dscp	011000	24
cs4	Match packets with CS4(precedence 4) dscp	100000	32
cs5	Match packets with CS5(precedence 5) dscp	101000	40
cs6	Match packets with CS6(precedence 6) dscp	110000	48
cs7	Match packets with CS7(precedence 7) dscp	111000	56
ef	Match packets with EF dscp	101110	46

Modify an ACL

Resource URI

Verb	URI
PUT	/api/v1/acl/{acl-id}

Example

JSON Request

PUT /api/v1/acl/abc

Content-type: application/json

Accept: application/json

{

"kind": "object#acl",

"rules": [

{ /* ace/rule */

"sequence" : 1,

"protocol": "tcp",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit",

"l4-options" : {

"src-port-start" : "ftp",

"src-port-op" : "eq",

"dest-port-start" : "ftp",

"dest-port-op": "eq"

}

]

}

JSON Response

200 OK

Retrieve an ACL

Resource URI

Verb	URI
GET	/api/v1/acl/{acl-id}

Example

JSON Request

GET /api/v1/acl/in_to_out

Accept: application/json

JSON Response

200 OK

Content-type: application/json

Accept: application/json

{

"kind": "object#acl",

"acl-id": "in_to_out",

"rules": [

{ /* ace/rule */

"sequence" : 20,

"protocol": "tcp",

"source": "10.1.1.2/32",

"destination": "172.16.1.1/32",

"action": "permit",

"l4-options" : {

"dest-port" : "telnet",

"dest-port-op": "eq"

}

]

}

Delete an ACL

Resource URI

Verb	URI
DELETE	/api/v1/acl/{acl-id}

Example

JSON Request

DELETE /api/v1/acl/abc

Accept: application/json

JSON Response

204 No Content

Configure an ACL

Resource URI

Verb	URI
POST	/api/v1/acl

Example

JSON Request

POST /api/v1/acl

Content-type: application/json

Accept: application/json

{

"kind": "object#acl",

"rules": [

{ /* ace/rule */

"sequence" : 1,

"protocol": "ip",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit"

}

JSON Response

201 Created

Location: http://host/api/v1/acl/test

Retrieve All ACLs

Note When many ACLs are configured on the router, the Retrieve All ACLs operation produces a very long list. To retrieve a smaller set of ACLs, use ACL Batching.

Resource URI

Verb	URI
GET	/api/v1/acl

Example

JSON Request

GET /api/v1/acl

Accept: application/json

JSON Response

200 OK

Content-type: application/json

{

"kind": "collection#acl",

"items": [

{

"kind": "object#acl",

"acl-id": "test",

"rules": [

{ /* ace/rule */

"sequence" : 10,

"protocol": "ip",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit"

{ /* ace/rule */

"sequence" : 100,

"protocol": "ip",

"source": "any",

"destination": "any",

"action": "permit"

}

]

{

"kind": "object#acl",

"acl-id": "xyc",

"rules": [

{ /* ace/rule */

"sequence" : 10,

"protocol": "ip",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit"

{ /* ace/rule */

"sequence" : 100,

"protocol": "ip",

"source": "any",

"destination": "any",

"action": "permit"

}

]

}

]

}

ACL Batching

When many ACLs are configured on the router, the Retrieve All ACLs operation produces a very long list. To retrieve a smaller set of ACLs, use ACL batching. ACL batching retrieves a limited number of ACLs, as defined by count in the operation.

Resource URI

Verb	URI
GET	/api/v1/acl?start-index=0&count=2

Example

JSON Request

GET /api/v1/acl?start-index=0&count=2

JSON Response

200 ok

Content-type: application/json

{

"kind": collection#acl",

"items": [

{

"kind": "object#acl",

"acl-id": "test",

"rules": [

{ /* ace/rule */

"sequence" : 10,

"protocol": "ip",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit"

{ /* ace/rule */

"sequence" : 100,

"protocol": "ip",

"source": "any",

"destination": "any",

"action": "permit"

}

]

{

"kind": "object#acl",

"acl-id": "xyc",

"rules": [

{ /* ace/rule */

"sequence" : 10,

"protocol": "ip",

"source": "192.168.10.0/24",

"destination": "192.168.200.0/24",

"action": "permit"

{ /* ace/rule */

"sequence" : 100,

"protocol": "ip",

"source": "any",

"destination": "any",

"action": "permit"

}

]

}

]

}

All ACL Match Statistics Resource

The all ACL match statistics resource represents ACL match statistics (match counters for rules of ACLs).

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. Has fixed value "collection#acl-statistics"
items	array	Collection of ACL statistics objects

JSON Representation

{

"kind": "collection#acl-statistics"

"items" : [

{single ACL statistics JSON}*

]

}

This resource also supports clearing of all statistics by doing a POST on the resource with the following request message. See Resource specific operations for more details & examples.

JSON Representation

{

"action": "clear"

}

Retrieve All ACL Statistics

Resource URI

Verb	URI
GET	/api/v1/acl/statistics

Example

JSON Request

GET /api/v1/acl/statistics

Accept: application/json

JSON Response

200 OK

Content-type: application/json

{

"kind": "collection#acl-statistics",

"items": [

{

"kind": "object#acl-statistics",

"acl-id": "test1",

"rules": [

{

"sequence": 10,

"protocol": "ip",

"source": "any",

"destination": "any",

"action": "deny",

"match-count": 65951975

{

"sequence": 20,

"protocol": "tcp",

"source": "10.10.10.10",

"destination": "any",

"action": "deny",

"match-count": 65

}

]

{

"kind": "object#acl-statistics",

"acl-id": "test2",

"rules": [

{

"sequence": 10,

"protocol": "tcp",

"source": "192.168.35.1",

"destination": "any",

"action": "permit",

"match-count": 0

}

]

}

Single ACL Match Statistics Resource

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	Optional	Object type. Has fixed value "collection#acl-statistics".
acl-id	string	Mandatory	Unique ACL ID, name of the ACL resource.
rules	array	Mandatory	Contains zero or more access control rule objects.
rules[ ].sequence	string	Mandatory	Sequence number to order the rules and serves as a rule ID.
rules[ ].source	cidr_address	Mandatory	Traffic source in cidr format, hostname, host IP, or keyword "any".
rules[ ].destination	cidr_address	Mandatory	Traffic destination in cidr format, hostname, host IP, or keyword "any".
rules[ ].action	string	Mandatory	Allow or deny if traffic matches the rule.
rules[ ].l4-options		Mandatory	Options applicable for tcp/udp protocols.
rules[ ].l4-options.src- port-start rules[ ].l4-options.src- port-end	string	Optional	Source Port Number 0-65535, or a port range, or one of the following: bgp Border Gateway Protocol (179) chargen Character generator (19) cmd Remote commands (rcmd, 514) connectedapps-plain ConnectedApps Cleartext (15001) connectedapps-tls ConnectedApps TLS (15002) daytime Daytime (13) discard Discard (9) domain Domain Name Service (53) echo Echo (7) exec Exec (rsh, 512) finger Finger (79) ftp File Transfer Protocol (21) ftp-data FTP data connections (20) gopher Gopher (70) hostname NIC hostname server (101) ident Ident Protocol (113) irc Internet Relay Chat (194) klogin Kerberos login (543) kshell Kerberos shell (544) login Login (rlogin, 513) lpd Printer service (515) msrpc MS Remote Procedure Call (135) nntp Network News Transport

			Protocol (119) pim-auto-rp PIM Auto-RP (496) pop2 Post Office Protocol v2 (109) pop3 Post Office Protocol v3 (110) smtp Simple Mail Transport Protocol (25) sunrpc Sun Remote Procedure Call (111) syslog Syslog (514) tacacs TAC Access Control System (49) talk Talk (517) telnet Telnet (23) time Time (37) uucp Unix-to-Unix Copy Program (540) whois Nicname (43) www World Wide Web (HTTP, 80)
rules[ ].l4-options.dst- port-start rules[ ].l4-options.dst- port-end		Optional	Destination Port Number (1-65535), destination port range, or one of the following destination ports can be configured: bgp Border Gateway Protocol (179) chargen Character generator (19) cmd Remote commands (rcmd, 514) connectedapps-plain ConnectedApps Cleartext (15001) connectedapps-tls ConnectedApps TLS (15002) daytime Daytime (13) discard Discard (9) domain Domain Name Service (53) echo Echo (7) exec Exec (rsh, 512) finger Finger (79) ftp File Transfer Protocol (21) ftp-data FTP data connections (20) gopher Gopher (70) hostname NIC hostname server (101) ident Ident Protocol (113) irc Internet Relay Chat (194) klogin Kerberos login (543) kshell Kerberos shell (544) login Login (rlogin, 513) lpd Printer service (515) msrpc MS Remote Procedure Call (135) nntp Network News Transport
			Protocol (119) pim-auto-rp PIM Auto-RP (496) pop2 Post Office Protocol v2 (109) pop3 Post Office Protocol v3 (110) smtp Simple Mail Transport Protocol (25) sunrpc Sun Remote Procedure Call (111) syslog Syslog (514) tacacs TAC Access Control System (49) talk Talk (517) telnet Telnet (23) time Time (37) uucp Unix-to-Unix Copy Program (540) whois Nicname (43) www World Wide Web (HTTP, 80)
rules[ ].l4-options.src- port-op rules[ ].l4-optionsdest- port-op	string	Mandatory	Indicates how the port number should be matched. One of the keywords "eq", "gt", "lt", or "range". If omitted, defaults to "eq".
rules[ ].match-count	number	Mandatory	Rule match counters.

JSON Representation

{

"kind": "object#acl-statistics"

"acl-id": "{string}",

"rules": [

{

"sequence": {number},

"protocol": "{string}",

"source": "{string}",

"destination": "{string}",

"action": "{string}",

"ip-options" : {

"src-port-start" : {number},

"src-port-op" : "{string}",

"dest-port-start" : {number},

"dest-port-op": "{string}"

"match-count": {number}

}

]

}

The single ACL match statistics resource also supports clearing of ACL statistics by doing a POST on the resource with the following request message. See Resource specific operations for more details and examples.

JSON Representation for Clearning ACL Statistics

{

"action": "clear"

}

Retrieve Statistics for a Single ACL

Resource URI

Verb	URI
GET	/api/v1/acl/statistics/{acl-id}

Example

JSON Request

GET /api/v1/acl/abc/interfaces/gigabitEthernet1_inside

Accept: application/json

JSON Response

200 OK

Accept: application/json

{

"kind": "object#acl-statistics",

"acl-id": "abc",

"rules": [

{

"sequence" : 10,

"protocol" : "ip",

"source" : "any",

"destination" : "any",

"action" : "deny",

"match-count" : 65951975

{ … }

]

}

ACL Associated with an Interface Resource

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. Has fixed value "collection#acl-"
if-id	string	Interface to which the ACL is applied.
direction	string	Direction of traffic to which the ACL is applied. Valid values are "inside" and "outside". The interface is viewed as “inside” or “outside” from NAT point of view.

JSON Representation

{

"kind" : "object#acl-interface"

"if-id" : "{string}",

"direction" : "{string}"

}

Retrieve ACL Associated with an Interface

Resource URI

Verb	URI
GET	/api/v1/acl/{acl-id}/interfaces/{if-id_direction}

Example

JSON Request

GET /api/v1/acl/abc/interfaces/gigabitEthernet1_inside

Accept: application/json

JSON Response

200 OK

Content-type: application/json

{

"kind" : "object#acl-interface",

"acl-id" : "abc",

"if-id" : "gigabitEthernet1",

"direction" : "inside"

}

Retrieve All ACL Interfaces

Resource URI

Verb	URI
GET	/api/v1/acl/{acl-id}/interfaces

Properties for Retrieve All

Property	Type	Description
kind	string	Object type. Has fixed value "collection#acl-interface"
items	array	Array of ACL objects with the kind "object#acl-interface"

JSON Representation

{

"kind" : "collection#acl-interface"

"items" : [

{JSON object with kind "object#acl-interface"}*

]

}

Example

JSON Request

GET /api/v1/acl/abc/interfaces

Accept: application/json

JSON Response

200 OK

Content-type: application/json

{

"kind": "collection#acl-interface",

"items": [

{

"kind": "object#acl-interface",

"acl-id": "abc",

"if-id": "gigabitEthernet1",

"direction": "inside"

{

"kind": "object#acl-interface",

"acl-id": "abc",

"if-id": "gigabitEthernet2",

"direction": "inside"

}

]

}

Delete ACL Associated with an Interface

Resource URI

Verb	URI
DELETE	/api/v1/acl/{acl-id}/s/{if-id_direction}

Example

JSON Request

DELETE /api/v1/acl/abc/interfaces/gigabitEthernet1_inside

Accept: application/json

JSON Response

204 No Content

Apply an ACL to Interfaces

ACL is applied to an interface by doing a POST on this resource with the following request content.

{

"if-id" : "{string}",

"direction" : "{string}"

}

Resource URI

Verb	URI
POST	/api/v1/acl/{acl-id}/interfaces

Example

JSON Request

POST /api/v1/acl/abc/interfaces

Accept: application/json

{

"if-id": "gigabitEthernet1",

"direction": "inside"

}

JSON Response

201 Created

Location: http://host/api/v1/acl/abc/interfaces/gigabitEthernet1_inside

Bias-Free Language

Results

Chapter: ACL Requirements for Subnets or IP Ranges

ACL Requirements for Subnets or IP Ranges

Resource Summary for ACL

ACL Resource

History

Properties

JSON Representation

ICMP Options

DSCP Values

Modify an ACL

Resource URI

Example

Retrieve an ACL

Resource URI

Example

Delete an ACL

Resource URI

Example

Configure an ACL

Resource URI

Example

Retrieve All ACLs

Resource URI

Example

ACL Batching

Resource URI

Example

All ACL Match Statistics Resource

History

Properties

JSON Representation

JSON Representation

Retrieve All ACL Statistics

Resource URI

Example

Single ACL Match Statistics Resource

History

Properties

JSON Representation

JSON Representation for Clearning ACL Statistics

Retrieve Statistics for a Single ACL

Resource URI

Example

ACL Associated with an Interface Resource

History

Properties

JSON Representation

Retrieve ACL Associated with an Interface

Resource URI

Example

Retrieve All ACL Interfaces

Resource URI

Properties for Retrieve All

JSON Representation

Example

Delete ACL Associated with an Interface

Resource URI

Example

Apply an ACL to Interfaces

Resource URI

Example

Was this Document Helpful?

Contact Cisco