Power On Auto Provisioning (POAP)

The following are the Power On Auto Provisioning (POAP) REST APIs:

Status

The following table details the API Response code, status and, the HTTPS methods.

Status Code
Status
API's HTTPS Method or
HTTPS Method

200

OK

GET

202

Accepted

POST

PUT

DELETE

400

Bad Request

GET

POST

PUT

DELETE

401

Unauthorized

GET

POST

PUT

DELETE

403

Forbidden

GET

POST

PUT

DELETE

404

Not Found

GET

POST

PUT

DELETE

405

Method Not Allowed

GET

POST

PUT

DELETE

500

Internal Server Error

GET

POST

PUT

DELETE

List Servers

Resource Name

/poap/servers

Description

List POAP image/config servers

https Method

GET

URL

https://dcnm-ip/rest/poap/servers

https://dcnm-ip/rest/poap/servers?detail=true

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

poap-servers

 

By default, a list of POAP image/config server names is displayed. If "detail=true"a list of POAP image/config server-objects including server-name and URI is displayed.

Create a Server

Resource Name

/poap/servers

Description

Create a new POAP image/config server

https Method

POST

URL

https://dcnm-ip/rest/poap/servers

Parameter

Parameter
Type
Description

poap-servers

 

POAP image/config server-object includingserver-name,URI,hostname/ipaddress, path,username and password.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

poap-server-name

 

POAP image/config server name.

Get Servers

Resource Name

/poap/servers/server-name

Description

Get the POAP image/config servers

https Method

GET

URL

https://dcnm-ip/rest/poap/servers/server-name

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

poap-server

 

POAP image/config server-object including server-name and URI.

Update Servers

Resource Name

/poap/servers/server-name

Description

Update the POAP image/config servers

https Method

PUT

URL

https://dcnm-ip/rest/poap/servers/server-name

Parameter

Parameter
Type
Description

poap-server

 

POAP image/configserver-object including

server-name,hostname/ipaddress, path,username and password.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Delete Servers

Resource Name

/poap/servers/server-name

Description

Delete the POAP image/config servers

https Method

DELETE

URL

https://dcnm-ip/rest/poap/servers/server-name

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

List Switch Definitions

Resource Name

/poap/switch-definitions

Description

List the POAP switch definitions

https Method

GET

URL

https://dcnm-ip/rest/poap/switch-definitions

https://dcnm-ip/rest/poap/switch-definitions?detail=true https://dcnm-ip/rest/poap/switch-definitions?search-string=<search-string>&start-index=<start-index>&size=<size>

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

Switch-definitions

 

By default, a list of serial- numbers is displayed. If "detail=true", then a list of switch-definition objects including serial-numbers, status(saved and publish later/published/saved and publishing/error), system-image, kick-start-image, image-server-uri, config-server-uri, template-name, parameter-values with a list of name, type, value corresponding to the template is displayed.

Create Switch Definitions

Resource Name

/poap/switch-definitions

Description

Create POAP switch definitions

https Method

POST

URL

https://dcnm-ip/rest/poap/switch-definitions

Parameter

Parameter
Type
Description

Switch-definitions

 

Displays a list of serial-numbers, system-image, kick-start-image, image-server-uri, config-server-uri, template-name, poap-settings-name, parameter-values with a list of name, type, value corresponding to the template, and publish=true/false.

For more information, see the example below.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

switch-numbers

 

List of serial numbers.

Example

Format: JSON

The example below shows how to publish a POAP definition (/rest/poap/published-switch-definitions/<serialNumber>) which are created using the API 1, 2, and 3.

API 1

/rest/poap/switch-definitions (POST)

{
"serialNumber":"example123",
"switchName":" example-123",
"deviceType":"N7K",
"mgmtIp":"5.5.5.5",
"username":"admin",
"password":"test123",
"lanGroup":2,
"configServerId":1,
"imageServerId":1,
"systemImageName":"n7k_sys.bin",
"kickstartImageName":"n7k_kick.bin"
}

 

API 2

/rest/templates/populate-template/Example_Simple (POST)

{
"templateParams":{
"SWITCH_NAME":"example-123",
"ADMIN_USERNAME":"admin",
"ADMIN_PASSWORD":"test123",
"MGMT_IP":"5.5.5.5",
"MGMT_PREFIX":"24",
"DEFAULT_GATEWAY":"5.5.5.1",
"CONSOLE_TIMEOUT":"0",
"CONSOLE_SPEED":"9600"
}
}

 

Note:

  • Use the "id" from /rest/poap/switch-definitions(POST) API's response as "poapDeviceId"
  • Use the "startupConfig" from /rest/templates/populate-template/<templateName> (POST) API's response as "templateContent"

API 3

/rest/poap/templates (POST)

{
"poapDeviceId":24770,
"templateName":"Example_Simple",
"templateContent":"hostname example-123\n\nno password strength-check\nusername admin password test123 role network-admin\n\nsnmp-server user admin network-admin auth md5 test123 priv test123 \n\nvrf context management\n ip route 0.0.0.0/0 5.5.5.1\n\ninterface mgmt0\n vrf member management\n no cdp enable\n no lldp transmit \n no lldp receive \n ip address 5.5.5.5/24\n no shutdown\n\nline console\n\n exec-timeout 0\n\n\n",
"templateNVPairs":"{\"SWITCH_NAME\":\"rajan-123\",\"ADMIN_USERNAME\":\"admin\",\"ADMIN_PASSWORD\":\"test123\",\"MGMT_IP\":\"5.5.5.5\",\"MGMT_PREFIX\":\"24\",\"DEFAULT_GATEWAY\":\"5.5.5.1\",\"CONSOLE_TIMEOUT\":\"0\",\"CONSOLE_SPEED\":\"9600\"}"
}

 

API 4

/rest/poap/published-switch-definitions/example123 (POST)

 
{
 
}

 

API 5

/rest/templates/perform-shallow-discovery (POST)

[
{
"mgmtIp":"5.5.5.5",
"username":"admin",
"password":"test123",
"lanGroup":2
}
]

 

Publish Switch Definitions

Resource Name

/poap/published-switch-definitions/{serial-number}

Description

Publish list of switch-definitions to the Repository server.

https Method

POST

URL

https://dcnm-ip/rest/poap/published-switch-definitions/{serial-number}

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Get a Switch Definition

Resource Name

/poap/switch-definitions/{serial-number}

Description

Get a switch definition.

https Method

GET

URL

https://dcnm-ip/rest/poap/switch-definitions/{serial-number}

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

switch-definition

 

Displays a list of serial-numbers, system-image, kick-start-image, image-server-uri, config-server-uri, template-name and parameter-values with a list of name, type, value corresponding to the template.

Update a Switch Definition

Resource Name

/poap/switch-definitions/serial-number

Description

Update a switch-definition.

https Method

PUT

URL

https://dcnm-ip/rest/poap/switch-definitions/{serial-number}

Parameter

Parameter
Type
Description

switch-definition

 

Displays a list of serial-numbers, system-image, kick-start-image, image-server-uri, config-server-uri, template-name and parameter-values with a list of name, type, value corresponding to the template, and publish=true/false.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Delete a Switch Definition

Resource Name

/poap/switch-definitions/serial-number

Description

Delete a switch-definition.

https Method

DELETE

URL

https://dcnm-ip/rest/poap/switch-definitions/{serial-number}

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Get a POAP Template

Resource Name

/poap/templates/{template-name}

Description

Get a POAP template.

https Method

GET

URL

https://dcnm-ip/rest/poap/templates/{template-name}

Parameter

Parameter
Type
Description

Serial-number

S

Device serial-number

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

Poap-template

O

Poap template object

Create a POAP Template

Resource Name

/poap/templates

Description

Create a POAP template.

https Method

POST

URL

https://dcnm-ip/rest/poap/templates

Parameter

Parameter
Type
Description

Poap-template

O

Poap template object

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

Poap-template-name

O

Poap template name

Update a POAP Template

Resource Name

/poap/templates/{template-name}

Description

Update a POAP template.

https Method

PUT

URL

https://dcnm-ip/rest/poap/templates/{template-name}

Parameter

Parameter
Type
Description

Poap-template

O

Poap template object

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Delete a POAP Template

Resource Name

/poap/templates/{template-name}

Description

Delete a POAP template.

https Method

POST

URL

https://dcnm-ip/rest/poap/templates/{template-name}

Parameter

Parameter
Type
Description

Poap-template-name

S

Poap template name

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Get All Published Templates

Resource Name

/poap/templates?published=true

Description

Get all the published templates.

https Method

GET

URL

https://dcnm-ip/rest/templates?published=true

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

templates

O

Returns all the published template names, if published=true.

Returns all the templates if published=false.

Generate Template Startup Config

Resource Name

/templates/populate-template/{template-name}

Description

Generates template for startup config.

https Method

POST

URL

https://dcnm-ip/rest/templates/populate-template/{template-name}

Example

Request Body:

{
"templateParams":{
"SWITCH_NAME":"r-123",
"ADMIN_USERNAME":"admin",
"ADMIN_PASSWORD":"test123",
"MGMT_IP":"10.0.0.0",
"MGMT_PREFIX":"24",
"DEFAULT_GATEWAY":"10.0.0.1",
"CONSOLE_TIMEOUT":"0",
"CONSOLE_SPEED":"9600"
}
}

Response Body:

{
"startupConfig":"hostname r-123\n\nno password strength-check\nusername admin password test123 role network-admin\n\nsnmp-server user admin network-admin auth md5 test123 priv test123 \n\nvrf context management\n ip route 0.0.0.0/0 10.0.0.1\n\ninterface mgmt0\n vrf member management\n no cdp enable\n no lldp transmit \n no lldp receive \n ip address 10.0.0.0/24\n no shutdown\n\nline console\n\n exec-timeout 0\n"
}

Parameter

Parameter
Type
Description

templateParams

O

Template parameters with values. You will get the templateParams in get template data API response. It returns the template parameters with default values.

The object should contain key-value pairs whose keys align with the Parameters field in the Get Configuration Template method.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

startupConfig

S

Return startup config

Get Group Navigation

Resource Name

/templates/groups

Description

Get all the groups.

https Method

GET

URL

https://dcnm-ip/rest/templates/groups

Parameter

Parameter
Type
Description

 

 

 

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

memDbId, name, navType

S

Return group/scope details

Perform Shallow Discovery

Resource Name

/templates/perform-shallow-discovery

Description

All the devices provided in payload will be discovered into DCNM.

https Method

POST

URL

https://dcnm-ip/rest/templates/perform-shallow-discovery

Parameter

Parameter
Type
Description

POAP

A

Serial Number, Management IP, Lan Group, User Name and Password need to provide in payload.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

 

 

 

Create Multiple POAP Definitions

Resource Name

/poap/definitions

Description

Simple and Single API to create multiple POAP definitions w/ discovery.

if you use this single API, the following separate APIs are not required.

  • Create the switch definition without template— /rest/poap/switch-definitions (POST)
  • Generate the startup configuration— /rest/templates/populate-template/<template-name> (POST)
  • Associate the template and startup configuration with the switch definition— /rest/poap/templates (POST)
  • Publish the switch definition— /rest/poap/published-switch-definitions/<serial-number> (POST)
  • Discover the switch in Cisco DCNM— /rest/templates/perform-shallow-discovery (POST)

https Method

POST

URL

https://dcnm-ip/rest/poap/definitions

Parameter

Parameter
Type
Description

Request Payload

A

Array of switchDetails and templateDetails.

Return Value

Format: JSON

Type: Object

Attribute Name
Type
Description

Response Object

O

POAP Device Serial Number and the Status

Example

The following example shows how to create two POAP definitions using this API:

Request: {

"switchDetails":[
{
"serialNumber":"SerialNo1",
"switchName":"Switch-1",
"systemImageName":"sys.bin",
"kickstartImageName":"kick.bin",
"imageServerId":1,
"configServerId":1,
"deviceType":"N9K",
"mgmtIp":"80.0.0.10",
"username":"admin",
"password":"cisco123",
"lanGroup":2,
"publish":"true"
},
{
"serialNumber":"SerialNo2",
"switchName":"Switch-2",
"systemImageName":"sys.bin",
"kickstartImageName":"kick.bin",
"imageServerId":1,
"configServerId":1,
"deviceType":"N9K",
"mgmtIp":"80.0.0.11",
"username":"admin",
"password":"cisco123",
"lanGroup":2,
"publish":"true"
}
],
"templateDetails":[
{
"templateParams":{
"SWITCH_NAME":"Switch-1",
"ADMIN_USERNAME":"admin",
"ADMIN_PASSWORD":"cisco123",
"MGMT_IP":"80.0.0.10",
"MGMT_PREFIX":"24",
"DEFAULT_GATEWAY":"80.0.0.1",
"CONSOLE_TIMEOUT":"0",
"CONSOLE_SPEED":"9600"
},
"templateName":"Example_Simple_v6"
},
{
"templateParams":{
"SWITCH_NAME":"Switch-2",
"ADMIN_USERNAME":"admin",
"ADMIN_PASSWORD":"cisco123",
"MGMT_IP":"80.0.0.11",
"MGMT_PREFIX":"24",
"DEFAULT_GATEWAY":"80.0.0.1",
"CONSOLE_TIMEOUT":"0",
"CONSOLE_SPEED":"9600"
},
"templateName":"Example_Simple_v6"
}
]
}
 

Response:

{
"SerialNo2": "Success",
"SerialNo1": "Success"
}