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. |
|
...
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' |
|
...
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 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. |
|
...
