DHCPv2 Module

The DHCPv2 system is built upon the Resource API, so actions relating to DHCP tasks are largely expressed in terms of Resource actions.

This section describes common DHCP tasks and how they are accomplished via the DHCPv2 system.

get all DHCP-enabled resources

Description

Finds all resources from section 'dhcp_module,' which indicates that their parents are DHCP-enabled. Adding in other Resource-Get API parameters can filter this list further.

URL

/api/v1/api.php?target=resource&action=get&type=dhcp_module

Returns

Examples:

SUCCESSFUL:

{"success":1,"message":"Search successful","data":[{"id":"1432", "name":"1392 DHCP Module" ,"slug":"1392-dhcp-module", "type":"dhcp_module", "parent_id":"1392", "category_id":null, "attr":{"_dhcp_attributes":"{\"type\":\"ISC\", \"notes\":\"\", \"username\":\"\", \"port\":\"\", \"config_test\":\"\/etc\/init.d\/dhcpd configtest\", \"server_stop\":\"\/etc\/init.d\/dhcpd stop\", \"server_start\":\"\/etc\/init.d\/dhcpd start\", \"config_path\":\"\", \"option_routers\":\"\", \"option_domain_name_servers\":\"\", \"option_domain_name\":\"\", \"authoritative\":\"1\", \"default_lease_time\":\"600\", \"max_lease_time\":\"7200\", \"local_port\":\"67\", \"log_facility\":\"local7\", \"password\":\"\", \"server_ip\":\"10.0.0.0\", \"freeLines\":0}", "_dhcp_config_id":"33"}}], "result_count":1, "found_count":1}

ERROR:

{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the dhcp_module resource
name	STRING	The name of the dhcp_module
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_module
parent_id	INTEGER	The resource to which the dhcp_module is attached
category_id	INTEGER	The category to which this dhcp_module is associated
result_count	INTEGER	How many dhcp_modules are returned in this search.
found_count	INTEGER	How many dhcp_modules were found in this query, without pagination.

Attributes:

Key	Type	Description
_dhcp_attributes	JSON	A JSON-encoded string containing all the specific configuration parameters which govern this DHCP server. An expansion of the JSON object is given below in the Data Attributes section.
_dhcp_config_id	INTEGER	A reference to the DHCP Config file written within the system. This field is maintained by the DHCPv2 system itself and should not be set externally.

create a new DHCP-enabled resource

Description

A resource becomes a DHCP-enabled by adding a special "dhcp_module" resource as a child. This action is identical to a normal Resource Create command.

URL

/api/v1/api.php?target=resource&action=add&meta[type]=dhcp_module&meta[name]=2163 DHCP Module&meta[parent_id]=2163

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Resource added","data":{"id": 2165,"name" :"2163 DHCP Module","slug": "2163-dhcp-module-2","type" :"dhcp_module","parent_id": 2163,"category_id": null,"attr":[]}}
ERROR:	{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the newly created dhcp_module
name	STRING	The name of the dhcp_module
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_module'
parent_id	INTEGER	The resource to which the dhcp_module is attached
category_id	INTEGER	The category to which this dhcp_module is associated

update a DHCP-enabled resource with new configuration info

Description

Modifying an existing dhcp_module uses the identical commands as all other Resource-Update actions. An example of configuring a DHCP server is given below.

URL

/api/v1/api.php?target=resource&action=update&meta[id]=2178 &meta[type]=dhcp_module&fields[_dhcp_attributes][]={"type":"ISC","notes":"notes go here","username":"username","port":"port","config_test":"/etc/init.d/dhcpd configtest","server_stop":"/etc/init.d/dhcpd stop","server_start":"/etc/init.d/dhcpd start","config_path":"/tmp/dhcpd.conf","option_routers":"192.168.0.0","option_domain_name_servers":"ns1.6connect.com","option_domain_name":"6connect.com","authoritative":"1","default_lease_time":"600","max_lease_time":"7200","local_port":"67","log_facility":"local7","password":"password","server_ip":"192.168.0.1","freeLines":3,"freeLine1":"free line 1","freeLine2":"free line 2","freeLine3":"free line 3"}

Returns

Examples:

SUCCESSFUL:

{"success": 1,"message": "Resource Updated","data": {"id":"2166" ,"name":"2163 DHCP Module", "slug":"2163-dhcp-module-3" ,"type":"dhcp_module", "parent_id":"2163", "category_id":null ,"attr":{"_dhcp_attributes": "{\"type\":\"ISC\", \"notes\":\"notes go here\", \"username\":\"username\", \"port\":\"port\", \"config_test\":\"\\\/etc\\\/init.d\\\/dhcpd configtest\" ,\"server_stop\":\"\\\/etc\\\/init.d\\\/dhcpd stop\" ,\"server_start\":\"\\\/etc\\\/init.d\\\/dhcpd start\",\"config_path\":\"\\\/tmp\\\/dhcpd.conf\", \"option_routers\":\"192.168.0.0\", \"option_domain_name_servers\":\"ns1.6connect.com\", \"option_domain_name\":\"6connect.com\", \"authoritative\":\"1\", \"default_lease_time\":\"600\", \"max_lease_time\":\"7200\", \"local_port\":\"67\", \"log_facility\":\"local7\" ,\"password\":\"**********\", \"server_ip\":\"192.168.0.1\", \"freeLines\":3, \"freeLine1\":\"free line 1\", \"freeLine2\":\"free line 2\", \"freeLine3\":\"free line 3\"}"}}}

ERROR:

{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the newly created dhcp_module
name	STRING	The name of the dhcp_module
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_module'
parent_id	INTEGER	The resource to which the dhcp_module is attached
category_id	INTEGER	The category to which this dhcp_module is associated

Attributes:

Key	Type	Description
_dhcp_attributes	JSON	A JSON-encoded string containing all the specific configuration parameters which govern this DHCP server. An expansion of the JSON object is given below in the Data Attributes section.

remove DHCP functionality from a resource

Description

To remove DHCP functionality, delete the dhcp_module child resource. This operation uses general Resource->Delete functionality.

URL

/api/v1/api.php?target=resource&action=delete&id=2166

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Deleted 2163-dhcp-module-3 (#2166)"}
ERROR:	{"success":0, "message":"error message"}

get all DHCP Pools

Description

As with the dhcp_module commands, the API endpoints governing DHCP IP Pools use the general Resource system. All the modifiers that can be applied to a Resource-Get can be used to filter this query.

URL

/api/v1/api.php?target=resource&action=get&type=dhcp_pool

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Search successful","data":[{"id":"1482","name":"Blah","slug":"blah","type":"dhcp_pool","parent_id":"1","category_id":null,"attr":{"_dhcp_type":"subnet","_dhcp_pool_attributes":"{\"mac\":\"\",\"rangeStart\":\"13.0.0.0\",\"rangeEnd\":\"13.0.0.255\",\"freeLines\":0}","_dhcp_ip_id":"80902"}}],"result_count":1,"found_count":1}
ERROR:	{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the dhcp_pool resource
name	STRING	The name of the dhcp_pool
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_pool'
parent_id	INTEGER	The resource to which the dhcp_pool is attached
category_id	INTEGER	The category to which this dhcp_pool is associated
result_count	INTEGER	How many dhcp_pools are returned in this search.
found_count	INTEGER	How many dhcp_pools were found in this query, without pagination.

Attributes:

Key	Type	Description
_dhcp_type	STRING	Either 'subnet' or 'host'. Determines whether this DHCP Pool is describing a Subnet or a Host.
_dhcp_pool_attributes	JSON	A JSON-encoded string containing all the specific configuration parameters which govern this DHCP Pool. An expansion of the JSON object is given below in the Data Attributes section.
_dhcp_ip_id	INTEGER	The id of the IPAM subnet or host which is assigned to this DHCP Pool

create a new DHCP Pool resource

Description

Uses the general Resource-Add endpoint to create a DHCP Pool resource.

URL

/api/v1/api.php?target=resource& action=add& meta[type]=dhcp_pool& meta[name]=New Subnet& fields[_dhcp_type][]=host& fields[_dhcp_pool_attributes][]={"mac":"aa:bb:cc:dd:ee:ff", "rangeStart":"", "rangeEnd":"", "freeLines":3, "freeLine1":"Free Line 1", "freeLine2":"Free Line 2", "freeLine3":"Free Line 3"}

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Resource added","data":{"id":2167,"name":"New Subnet","slug":"new-subnet","type":"dhcp_pool ","parent_id":1,"category_id":null,"attr":[]}}
ERROR:	{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the newly created dhcp_pool
name	STRING	The name of the dhcp_pool
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_pool'
parent_id	INTEGER	The parent resource; by default the TLR.
category_id	INTEGER	The category to which this dhcp_pool is associated

update a DHCP Pool

Description

Modifying an existing dhcp_pool uses the identical commands as all other Resource-Update actions.

URL

/api/v1/api.php?target=resource& action=update& meta[type]=dhcp_pool& meta[name]=Another Test& fields[_dhcp_type][]=subnet& fields[_dhcp_pool_attributes][]={"mac":"", "rangeStart":"10.10.10.4", "rangeEnd":"10.10.10.5", "freeLines":3, "freeLine1":"example1", "freeLine2":"example2", "freeLine3":"example3"}&fields[_dhcp_ip_id][]=92430&meta[id]=2165

Returns

Examples:

SUCCESSFUL:

{"success":1, "message":"Resource Updated", "data":{"id":"2165", "name":"Another Test", "slug":"2163-dhcp-module-2", "type":"dhcp_module", "parent_id":"2163", "category_id":null,"attr":{"_dhcp_type":"subnet" ,"_dhcp_pool_attributes":"{\"mac\":\"\", \"rangeStart\":\"10.10.10.4\", \"rangeEnd\":\"10.10.10.5\", \"freeLines\":3, \"freeLine1\":\"example1\", \"freeLine2\":\"example2\", \"freeLine3\":\"example3\"}", "_dhcp_ip_id":"92430"}}}

ERROR:

{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	ID of the newly created dhcp_module
name	STRING	The name of the dhcp_module
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_module'
parent_id	INTEGER	The resource to which the dhcp_module is attached
category_id	INTEGER	The category to which this dhcp_module is associated

Attributes:

Key	Type	Description
_dhcp_type	STRING	Either 'subnet' or 'host'. Determines whether this DHCP Pool is describing a Subnet or a Host.
_dhcp_pool_attributes	JSON	A JSON-encoded string containing all the specific configuration parameters which govern this DHCP Pool. An expansion of the JSON object is given below in the Data Attributes section.
_dhcp_ip_id	INTEGER	The id of the IPAM subnet or host which is assigned to this DHCP Pool

delete a DHCP Pool

Description

To delete a DHCP Pool, use the standard Resource-Delete functionality

URL

/api/v1/api.php?target=resource&action=delete&id=2165

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Deleted 2165-another-subnet-3 (#2165)"}
ERROR:	{"success":0, "message":"error message"}

assigning an IP address or blocks to a DHCP Pool

Description

Assigning IP addresses or blocks to a DHCP Pool resource removes them from the available pool so they cannot be assigned out again. This procedure uses all the standard IPAM assignment functions, so long as the resource assigned from is the DHCP Available resource.

URL

/api/v1/api.php?target=ipam&action=smartAssign&resourceId=2162&type=ipv4&mask=31&rir=1918&assignedResourceId=1282

Returns

Examples:

SUCCESSFUL:

{"success":1,"message":"Assigned 10.8.1.4\/31 to 208.39.104.106 (2162) via Smart Assign","id":94468,"data":{"id":94468,"type":"ipv4","top_aggregate":44616,"cidr":"10.8.1.4\/31","formatted_ip":"10.8.1.4\/31","address":"168296708","end_address":"168296709","mask":31,"netmask":"255.255.255.254","child1":null,"child2":null,"is_assigned":1,"is_swipped":0,"is_aggregate":1,"custid":2162,"resource_id":2162,"resource_name":null,"last_updated_time":"2015-03-15 20:17:32","description":null,"parent":80882,"rir":"1918","lir_id":null,"notes":null,"generic_code":null,"code":null,"region":"Quito","region_name":"Quito","vlan":null,"arin_net_id":null,"arin_cust_id":null,"org_id":null,"arin_swip_time":null,"assigned_time":"2015-03-15 20:17:32","asn":null,"allowSubAssignments":false,"permissions":[],"range":"10.8.1.4 - 10.8.1.5","tags":["DHCP"]}}

ERROR:

{"success":0, "message":"error message"}

Return Detail:

For a detailed breakdown of this endpoint's return data, please see the IPAM documentation.

get all DHCP Pool linkages

Description

The association between DHCP Pools and DHCP Modules belongs to the Resource Linkage family of endpoints. The 'relation' field should be set to the 'dhcpPoolLink' type to pull only DHCP Pool linkage information.

URL

/api/v1/api.php?target=resource&action=getLink&relation=dhcpPoolLink

Returns

Examples:

SUCCESSFUL:	{"success":1 ,"message":"Search successful", "data":{"meta":{"totalRecords":"3", "retrieved":3}, "0":{"id":"22", "resource_id1":"1292", "resource_id2":"1302", "relation":"dhcpPoolLink"}, "1":{"id":"2", "resource_id1":"1292", "resource_id2":"1452", "relation":"dhcpPoolLink"}, "2":{"id":"12", "resource_id1":"1422", "resource_id2":"1482", "relation":"dhcpPoolLink"}}}
ERROR:	{"success":0, "message":"error message"}

Return Detail:

Name	Type	Description
id	INTEGER	Id of the pool-module linkage
resource_id1	INTEGER	The id of the dhcp_module resource
resource_id2	INTEGER	The id of the dhcp_pool resource
relation	STRING	The relation type. Always 'dhcpPoolLink'

Meta Attributes:

Name	Type	Description
totalRecords	INTEGER	How many records were found by this query, without pagination.
retrieved	INTEGER	How many records were returned by this query, with pagination.

Optional Attributes:

Name	Type	Description
resultsPerPage	INTEGER	How many records to include per page display.*
page	INTEGER	Which page to display, when used with "resultsPerPage"*
*Example pagination: api.php?target=resource&action=getLink&relation=dhcpPoolLink&resultsPerPage=100&page=2

add a new DHCP Pool linkage

Description

Adds a new link between a DHCP Pool and a dhcp_module resource. A single pool can be linked to many dhcp_modules, and a single dhcp_module can have any number of linked pools.

URL

/api/v1/api.php?target=resource&action=addLink&resource_id1=1292&resource_id2=2162&relation=dhcpPoolLink

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Resource link added"}
ERROR:	{"success":0, "message":"error message"}

Data Detail:

Name	Type	Description
resource_id1	INTEGER	The id of the dhcp_module resource
resource_id2	INTEGER	The id of the dhcp_pool resource
relation	STRING	The relation type being added. Always 'dhcpPoolLink'

delete DHCP Pool linkages

Description

Deletes a link between a dhcp_module and a dhcp_pool. Uses the standard Resource Linkage endpoints.

URL

/api/v1/api.php?target=resource&action=deleteLink&id=22

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Resource link(s) deleted."}
ERROR:	{"success":0, "message":"error message"}

push a DHCP config

Description

Builds a DHCP configuration from the attributes assigned to a dhcp_module and all of the linked dhcp_pools. Pushes that config to the configured DHCP server, tests it against the config parsing function, then restarts the server with the new configuration.

URL

/api/v1/api.php?target=dhcp&action=push&id=1292

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Pushes Attempted.","data":[[1,"1292","381 DHCP Module","Configuration successfully pushed."]]}
ERROR:	{"success":0, "message":"error message"}

Data Detail

Name	Type	Description
id	INTEGER	The id of the dhcp_module resource whose configuration is to be pushed.

DHCP search

Description

Searches DHCP information by name, mac, or IP.

URL

/api/v1/api.php?target=dhcp&action=search&searchType=name&searchValue=Blah

/api/v1/api.php?target=dhcp&action=search&searchType=mac&searchValue=22:

/api/v1/api.php?target=dhcp&action=search&searchType=ip&searchValue=13.0.0.255

Returns

Examples:

SUCCESSFUL:	{"success":1,"message":"Search Successful","data":[{"id":"1482","name":"BlahBlah","slug":"blah","type":"dhcp_pool","parent_id":"1","category_id":null,"attr":{"_dhcp_type":"subnet","_dhcp_pool_attributes":"{\"mac\":\"\",\"rangeStart\":\"13.0.0.0\",\"rangeEnd\":\"13.0.0.255\",\"freeLines\":0}","_dhcp_ip_id":"80902"},"dhcp_links":["1422","3673"]}]}
ERROR:	{"success":0, "message":"error message"}

Return Detail

Name	Type	Description
id	INTEGER	ID of the dhcp_module resource
name	STRING	The name of the dhcp_module
slug	STRING	The unique reference string for this resource
type	STRING	Always 'dhcp_pool'
parent_id	INTEGER	The resource to which the dhcp_module is attached
category_id	INTEGER	The category to which this dhcp_module is associated

Attributes

Key	Type	Description
_dhcp_type	STRING	Either 'subnet' or 'host'. Determines whether this DHCP Pool is describing a Subnet or a Host.
_dhcp_pool_attributes	JSON	A JSON-encoded string containing all the specific configuration parameters which govern this DHCP Pool. An expansion of the JSON object is given below in the Data Attributes section.
_dhcp_ip_id	INTEGER	The id of the IPAM subnet or host which is assigned to this DHCP Pool.
_dhcp_links	INTEGER	The id of dhcp links.

Required Parameters

Name

Type

Example

Description

searchType

STRING

name

Type of search performing. Valid values are 'name', 'mac', and 'ip'.

searchValue

STRING

Blah

If searchType is 'IP': searchValue must be a valid IP address or IP Block.

if searchType"is 'mac': searchValue must be a full or partial mac address.

Not required if searchType is 'name', but is recommended to filter results.

Optional Parameters

Name	Type	Example	Description
selectOffset	INTEGER	10	Start number for the first result to show on the page to set pagination. For example, a selectOffset=15 with a selectCount=10 would return result numbers 15 through 25 on the page. Default value is 0 if not specified.
selectCount	INTEGER	5	The number of results to return on the page, if return results exceed the number of selectCount. Default value is 10
linkedTo	INTEGER	1422	The ID of the resource's DHCP link(s)

Data Attributes

_dhcp_attributes

Description

The _dhcp_attributes data attribute holds the specific settings used to generate a DHCP configuration file, place it on a server via SCP, and restart that server via a SSH session.

Example:

{"type":"ISC", "notes":"notes here", "username":"username", "port":"22", "config_test":"/etc/init.d/dhcpd configtest", "server_stop":"/etc/init.d/dhcpd stop", "server_start":"/etc/init.d/dhcpd start", "config_path":"/tmp/dhcpd.conf", "option_routers":"", "option_domain_name_servers":"", "option_domain_name":"", "authoritative":"1", "default_lease_time":"600", "max_lease_time":"7200", "local_port":"67", "log_facility":"local7", "password":"", "server_ip":"10.0.0.0", "freeLines":0}

Data Description

Name	Type	Description
type	STRING	The type of DHCP server being administered. Currently only 'ISC' is supported.
notes	STRING	Notes associated with this DHCP server
server_ip	STRING	The IP address of the DHCP server
username	STRING	The SSH username employed when transferring the DHCP configuration file to the server.
password	STRING	The SSH password employed when transferring the DHCP configuration file to the server.
port	INTEGER	The SSH port employed when transferring the DHCP configuration file to the server.
config_test	STRING	The command to test if a configuration file parses correctly. ex: /etc/init.d/dhcpd configtest
server_stop	STRING	The command to stop the DHCP server. ex: /etc/init.d/dhcpd stop
server_start	STRING	The command to start the DHCP server. ex: /etc/init.d/dhcpd start
config_path	STRING	Where to place the configuration file on the server.
authoritative	BOOL	Whether or not this DHCP server is authoritative.
default_lease_time	INTEGER	The default lease time for IPs distributed by this DHCP server.
max_lease_time	INTEGER	The max lease time for IPs distributed by this DHCP server.
local_port	INTEGER	The port on which this DHCP server listens
option_routers	STRING	The information which populates the "routers" option in the DHCP configuration
option_domain_name_servers	STRING	The information which populates the "domain_name_servers" option in the DHCP configuration
option_domain_name	STRING	The information which populates the "domain_name" option in the DHCP configuration
log_facility	STRING	The log facility to which this DHCP Server sends its logging information
freeLines	INTEGER	As this system cannot hope to support all the thousands of different DHCP configurations, ProVision's DHCPv2 system includes a mechanism for adding "free lines" to the end of certain DHCP config sections so that administrators can customize their DHCP config file to their needs. The "freeLines" field indicates how many of these lines exist to be inserted after the general server definition section but before the subnets and hosts are enumerated.
freeLine#	STRING	Free line data to be inserted after the general server definition section but before the subnets and hosts are enumerated. There can be multiple instances of this attribute, numbered appropriately. ex: "freeLine1", "freeLine2", "freeLine3", etc. The number of freeLine# entries must match the number in the "freeLines" attribute.

_dhcp_pool_attributes

Description

A JSON-encoded string containing all the specific configuration parameters which govern this DHCP Pool.

Example:

{"mac":"ab:cc:de:ff:aa:bc","rangeStart":"13.0.0.0","rangeEnd":"13.0.0.255","freeLines":1,"freeLines1":"free line"}

Data Description

Name	Type	Description
mac	STRING	Only used when setting up a DHCP Host-type Pool. Holds the MAC address of the system to which the IP will be associated.
rangeStart	STRING	Only used when setting up a DHCP Subnet-type Pool. Holds the beginning of the Subnet range being allocated.
rangeEnd	STRING	Only used when setting up a DHCP Subnet-type Pool. Holds the end of the Subnet range being allocated.
freeLines	INTEGER	As this system cannot hope to support all the thousands of different DHCP configurations, ProVision's DHCPv2 system includes a mechanism for adding "free lines" to the end of certain DHCP config sections so that administrators can customize their DHCP config file to their needs. The "freeLines" field indicates how many of these lines exist to be inserted within the DHCP Pool declaration.
freeLine#	STRING	Free line data to be inserted after the general server definition section but before the subnets and hosts are enumerated. There can be multiple instances of this attribute, numbered appropriately. ex: "freeLine1", "freeLine2", "freeLine3", etc. The number of freeLine# entries must match the number in the "freeLines" attribute.

Page tree

API Module - DHCPv2

DHCPv2 Module

get all DHCP-enabled resources

create a new DHCP-enabled resource

update a DHCP-enabled resource with new configuration info

remove DHCP functionality from a resource

get all DHCP Pools

create a new DHCP Pool resource

update a DHCP Pool

delete a DHCP Pool

assigning an IP address or blocks to a DHCP Pool

get all DHCP Pool linkages

add a new DHCP Pool linkage

delete DHCP Pool linkages

push a DHCP config

DHCP search

Data Attributes

_dhcp_attributes

_dhcp_pool_attributes