DHCP Server and Relay Agent

Resource Summary for DHCP Server and Relay Agent

HTTP Method
Resource
URL (BaseURL)
GET
POST
PUT
DELETE

DHCP servers

/api/v1/dhcp

Y

N

Y

N

DHCP pools

/api/v1/dhcp/pool

Y

Y

N

N

/api/v1/dhcp/pool/{pool-name}

Y

N

Y

Y

Collection of active bindings

/api/v1/dhcp/active/bindings

Y

Y

N

N

Host IP address for the active bindings

/api/v1/dhcp/active/bindings/{host-ip}

Y

N

N

Y

DHCP Server 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

Mandatory

Object type. Has fixed value "object#dhcp-server"

enable

boolean

Mandatory

Enable/disable DHCP server and Relay agent features

excluded-addresses

array

Mandatory

Array of excluded addresses from this DHCP pool

excluded-addresses[ ].low-ip-address

ipaddress

Mandatory

Excluded low IP address in x.x.x.x format.

excluded-addresses[ ].
high-ip-address

ipaddress

Optional

Excluded high IP address in x.x.x.x format.

relay-agent

array

Optional

DHCP server IP address or network address in x.x.x.x format. Destination broadcast or host address to be used when forwarding UDP broadcasts. There can be more than one helper address per interface.

relay-agent interface-name

string

Mandatory

Interface name

relay-agent.address

string

Mandatory

List of DHCP server addresses or network addresses in x.x.x.x format.

JSON Representation

{
"kind": "object#dhcp-server",
"enable":{boolean},
"excluded-addresses": [
{
"kind": "object#dhcp-server-excluded-address",
"low-ip-address":"{ipaddress}",
"high-ip-address":"{ipaddress}"
}
],
"relay-agents": [
{
"kind": "object#dhcp-server-relay-agent",
"interface": "{string}",
"addresses": [ "{string}" ]
}
]
}

Retrieve DHCP Server

Resource URI

Verb
URI

GET

/api/v1/dhcp

Example

JSON Request

GET /api/v1/dhcp
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind": "object#dhcp-server""enable",
"enable": true,
"excluded-addresses": [
{
"kind": "object#dhcp-server-excluded-address",
"low-ip-address": "171.16.1.1",
"high-ip-address": "171.16.1.50"
}
],
"relay-agents": [
{
"kind": "object#dhcp-server-relay-agent",
"interface-name" : "gigabitEthernet1",
"addresses": [ "172.15.15.15" ]
}
]
}

Modify Global DHCP Parameters

HTTP PUT is used to configure one or several DHCP relay-agents. Note that all the relay-agent (interface-name, address) that were previously configured and which the user does not want to delete should re-appear in the HTTP PUT request. Otherwise, they will be deleted. The same holds for the list of excluded-addresses.

Example: Modifying the High-IP Address Excluded Address

JSON Request

PUT /api/v1/dhcp
 
Content-Type: application/json
Accept: application/json
 
{
"enable": true,
"excluded-addresses": [
{
"low-ip-address": "172.16.1.1",
"high-ip-address": "171.16.1.30"
}
],
"relay-agents": [
{
"interface-name" : "gigabitEthernet1",
"addresses": [ "172.15.15.15" ]
}
]
}

JSON Response

204 No Content

DHCP Server Address Pool Resource

Represents a DHCP address pool. An address pool can be a dynamic one where an address range is specified, or a manual binding specification. Only one of the types can exist in a given 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. Has the fixed value “dhcp-server-pool”

pool-name

string

Mandatory

DHCP pool name

dynamic

object

Optional

Dynamic Address pool details. Only one of “dynamic: or “manual” objects must be present.

manual

object

Optional

Manual binding details. Only one of “dynamic” or “manual” objects must be present.

options

object

Mandatory

Pool options.

dynamic address-range

cidr-addr

Mandatory

The subnet network number and prefix length of the DHCP address pool in CIDR format: x.x.x.x/nn

dynamic.lease-duration

object

Optional

Duration of the lease for address assignment to host. The default is one-day lease.

dynamic.lease-duration.
infinite

boolean

Mandatory

Specifies if lease duration never expires.

dynamic.lease-duration.
days

number

Optional

Days part of the duration. If not specified, default of 1 day is used.

dynamic.lease-duration.
hours

number

Optional. Days part is mandatory if hours is specified.

Hours part of the duration.

dynamic.lease-duration.
minutes

number

Optional. Hours part is mandatory if minutes is specified.

Minutes part of the duration.

manual.host-ip-address

ipaddress

Mandatory

IP address to be assigned to the host in x.x.x.x format.

manual.mac-address

string

Mandatory

Host Mac address xx:xx:xx:xx:xx:xx in hex format.

manual.client-name

string

Optional

Name of the client in any standard ASCII character. The client name should not include the domain name. For example, the name mars should not be specified as mars.cisco.com.

options.domain-name

string

Optional

Domain name for a DHCP client.

options.default-gateway

ipaddress

Optional

Default router for a DHCP client: IP address in x.x.x.x format. Up to 8 can be configured.

options.dns-servers

array

Mandatory

Array of IP addresses. Each element of the array should be an IP address in the format x.x.x.x. Up to 8 can be configured.

options.netbios-name-servers

array

Mandatory

Array of NETBIOS name server (WINS) IP addresses. Each element of the array should be an IP address in the format x.x.x.x. Up to 8 can be configured.

options.netbios-node-type

string

Mandatory

Netbios node type for windows hosts

JSON Representation

{
"kind": "object#dhcp-server-pool"
"poolName": "{string}",
"dynamic": {
"address-range":"{cidr_addr}",
"lease-duration":
{
"infinite" : {boolean},
"days": {number},
"hours": {number},
"minutes": {number}
},
}
"manual": {
"host-ip-address":"{ipaddress}",
"mac-address": "{string}",
"client-name": "{string}"
}
"options": {
"domain-name": "{string}",
"default-gateway": "{ipaddress}",
"dns-servers": ["{ipaddress}","{ipaddress}"],
"netbios-name-servers": ["{ipaddress}","{ipaddress}"],
"netbios-node-type": "{string}"
}
}

Retrieve Address Pool

Resource URI

 

Verb
URI

GET

/api/v1/dhcp/pool/{pool-name}

Example

JSON Request

GET /api/v1/dhcp/pool/myDhcpPool
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind": "object#dhcp-server-pool"
"poolName": "myDhcpPool",
"dynamic": {
"address-range": "172.16.1.0/24",
"lease-duration":
{
"days": 30
},
}
"options": {
"default-gateway": ["172.16.1.100", "172.16.1.101"]
}
}

Retrieve All DHCP Address Pools

Resource URI

Verb
URI

GET

/api/v1/dhcp/pool

Properties for Retrieve All

Property
Type
Description

kind

string

Object type. Has fixed value "collection#dhcp-server-pool"

items

array

Array of DHCP pool objects.

Example

JSON Request

GET /api/v1/dhcp/pool
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
Accept: application/json
 
{
"kind": "collection#dhcp-server-pool",
"items": [
{
"poolName": "myDynamicDhcpPool",
"dynamic":{"address-range": "172/16.0.0/16"},
"options": {
"domain-name": "cisco.com",
"dns-servers": [
"172.16.1.102",
"172.16.2.102"
],
"netbios-name-servers":[
"172.16.1.103",
"172.16.2.103"
],
"netbios-node-type": "h-node"
}
},
{
"poolName": "myManualBinding",
"manual": {
"host-ip-address": "172.16.2.254",
"mac-address": "02c7.f800.0422",
"client-name": "Mars",
}
}
]
}

Modify a DHCP Address Pool

Resource URI

Verb
URI

PUT

/api/v1/dhcp/pool/{pool-name}

Example: Modifying the Lease Days to 60

JSON Request

PUT /api/v1/dhcp/pool/myDhcpPool
 
Content-Type: application/json
Accept: application/json
 
{
"poolName": "myDhcpPool",
"dynamic": {
"address-range": "172.16.1.0/24",
"lease-duration":
{
"days": 60
},
},
"options": {
"default-gateway": ["172.16.1.100", "172.16.1.101"]
}
}

JSON Response

204 No Content

Delete Address Pool

Resource URI

Verb
URI

DELETE

/api/v1/dhcp/pool/{pool-name}

Example

JSON Request

DELETE /api/v1/dhcp/pool/myDhcpPool

JSON Response

204 No Content

Create a DHCP Address Pool

Resource URI

Verb
URI

POST

/api/v1/dhcp/pool

Example

JSON Request

POST /api/v1/dhcp/pool
 
Content-Type: application/json
Accept: application/json
 
{
"poolName": "myDhcpPool",
"dynamic": {
"address-range": "172.16.1.0/24",
"lease-duration": { "days": 30 }
},
"options": {
"default-gateway": ["172.16.1.100", "172.16.1.101"]
}
}

JSON Response

201 Created
Location: http://host/api/v1/dhcp/pool/myDhcpPool

DHCP Server Binding Resource

Represents a single DHCP active address binding. Includes both manual/automatic.

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#dhcp-server-binding"

host-ip-address

ipaddress

IP address assigned to host

mac-address

string

Host’s mac address in xxxx.xxxx.xxxx format

lease-expiration-time

string

Lease expiration time in the format YYYY:MM:DD HH:MM or "infinite"

type

string

Binding type with values "Automatic" or "Manual"

JSON Representation

{
"kind" : "object#dhcp-server-binding"
"host-ip-address" : "{ipaddress}",
"mac-address" : "{string}",
"lease-expiration-time": "{datetime}",
"type" : "{string}"
}

Retrieve a Host Binding

Resource URI

Verb
URI

GET

/api/v1/dhcp/active/bindings/{host-ip}

Example

JSON Request

GET /api/v1/dhcp/active/bindings/172.16.1.11
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind": "object#dhcp-server-binding"
"host-ip-address": "172.16.1.11",
"mac-address": "00a0.9802.32de",
"lease-expiration-time": "2013:02:01 01:00",
"type": "automatic"
}

Clear an Active Binding

Resource URI

Verb
URI

DELETE

/api/v1/dhcp/active/bindings/{host-ip}

Example

JSON Request

DELETE /api/v1/dhcp/active/bindings/172.16.1.11

JSON Response

204 No Content

Retrieve All Active Bindings

Resource URI

Verb
URI

GET

/api/v1/dhcp/active/bindings

Properties for Retrieve All

Property
Type
Description

kind

string

Object type. Has fixed value "collection#dhcp-server-bindings"

items

array

Array of DHCP binding objects with the kind "object#dhcp-server-binding"

JSON Representation

{
"kind": "collection#dhcp-server-bindings"
"items": [
{DHCP binding json object}*
]
}

Example

JSON Request

GET /api/v1/dhcp/active/bindings
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind": "collection#dhcp-server-bindings"
"items": [
{
"kind": "object#dhcp-server-binding",
"host-ip-address": "172.16.1.11",
"mac-address": "00a0.9802.32de",
"lease-expiration-time": "2013:02:01 01:00",
"type": "automatic"
},
{
"kind": "object#dhcp-server-binding"
"host-ip-address": "172.16.2.254",
"mac-address": "02c7.f800.0422",
"lease-expiration-time": "infinite",
"type": "manual"
}
]
}

Clear Active Binding

This resource also supports clearing of all automatic bindings. Use POST on the resource with the following request message.

note.gif

Noteblank.gif 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 all active bindings.

Resource URI

Verb
URI

POST

/api/v1/dhcp/active/bindings

JSON Representation

{
"action": "clear"
}

Example

JSON Request

POST /api/v1/dhcp/active/bindings
Accept: application/json
 
{
"action": "clear"
}

JSON Response

204 No Content