ProVision's APIv1 system has been replaced by APIv2, and is now considered deprecated.
Overview
DHCP Management Version 2 integrates DHCP management with ProVision's resource and permissions hierarchy, as well as the IP Management system. Individual DHCP servers can be assigned via Resource Permissions to different internal user groups, to be managed by only the appropriate parties.
Under DHCPv2 there is no distinct “DHCP Server” type or section – instead there is a “DHCP Module” which, when attached as a child to an existing resource, transforms it into a DHCP-enabled device. The most common use is to take the generic “Server” Section and turn it into a DHCP Server by attaching the DHCP Module as a child. This configuration allows users to add functionality to a basic resource and provides a cleaner management interface.
API Updates
The DHCPv1 API operated via calls to the DHCPServer and the DHCPEntry endpoint families. However, now that DHCPv2 is contained entirely within the resource system, most of the API calls to manipulate DHCP data do so using the Resource family of API endpoints to modify specific Resource attributes reserved for DHCP functionality.
DHCP API How-To
Relate with Resources
The DHCPv2 system builds upon the ProVision Resource API. With the exception of a few configuration commands all DHCPv2 API commands use the Resource family of API endpoints.
How to attach the DHCP Module as a child
As described above, DHCPv2 functionality is enabled on a particular resource by attaching a DHCP Module as a child. A command to do this is as follows:
The special resource type “dhcp_module” indicates to ProVision that the DHCP system is enabled for the parent object. The attributes associated with the “dhcp_module” resource govern the DHCP system's behavior.
Updating the attributes of a DHCP Server uses a Resource Update command:
[ProVision root]/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.example.com","option_domain_name":"example.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"}
This command appears rather complicated, but can be broken apart into reasonable pieces. The first section:
is familiar from other parts of ProVision. We are updating a resource of type “dhcp_module” whose resource id is 2178. The second section of the command details the update values, starting with
fields[_dhcp_attributes][]=
which contains a JSON-encoded string of all the fields specific to a DHCP server's function. When expanded into its full object form it is substantially easier to digest:
{
"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.example.com",
"option_domain_name":"example.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"
}
This object describes all the most common DHCP server configuration options. For a full explanation of each of the fields, see the Detailed API Specification later in this document.
Please note that the object above must be passed to the DHCP system as a JSON-encoded string. It must be passed into the special “_dhcp_attributes” attribute for it to be functional, as in the example URL.
Create DHCP IP Aggregates
For details on how to manage IP aggregates using ProVision's IPAM API, see API Module - IPAM.
Of particular interest to DHCP management is the addition of DHCP aggregates, which are sections of IP space marked as available for use by the DHCPv2 system.
The important part to note is that the IP block is being assigned to resourceId 1282, which corresponds to the DHCP Available resource. The DHCP Available resource is a system-level resource which is used to hold all unassigned DHCP IP addresses. Every instance has its own DHCP Available resource, whose id can be found with the following command:
New DHCP subnets and hosts draw their IPs from this pool. If there are no IPs in the DHCP Available pool new subnets and hosts will not be able to be created.
DHCP IP aggregates are fetched, updated, split, and deleted using the standard IPAM management API endpoints. Please see the IPAM API Documentation. for details.
Subnets and Hosts
Every DHCP configuration file consists primarily of Subnet and Host declarations, mapping out what IP addresses are available for what purpose. In DHCPv2, DHCP Pools are reusable components that can be attached to several DHCP Servers in order to build flexible, responsive DHCP configurations.
In ProVision DHCPv2 all DHCP Pools regardless of whether they span Subnets or individual Hosts require that a “dhcp_pool” resource be created to govern them.
How to create DHCP Pools
Similar to how the “dhcp_module” resource was created above, the command to create a DHCP Pool is as follows:
[ProVision root]/api/v1/api.php?target=resource&action=add&meta[type]=dhcp_pool &meta[name]=New Subnet&fields[_dhcp_type][]=subnet&fields[_dhcp_pool_attributes][]={"mac":"","rangeStart":"","rangeEnd":"","freeLines":3,"freeLine1":"Free Line 1","freeLine2":"Free Line 2","freeLine3":"Free Line 3"}
The first half of this command is relatively straightforward:
This section informs the API that we wish to create a new, empty “dhcp_pool” resource whose name is “New Subnet.”
fields[_dhcp_type][]=subnet&fields[_dhcp_pool_attributes][]={"mac":"","rangeStart":"", "rangeEnd":"","freeLines":3,"freeLine1":"Free Line 1","freeLine2":"Free Line 2","freeLine3":"Free Line 3"}
The second half of the command behaves in a similar manner to the “dhcp_module.” The “_dhcp_pool_attributes” field holds a JSON-encoded string which describes the dhcp_pool resource. When expanded, the JSON string becomes the following object:
{
"mac":"",
"rangeStart":"",
"rangeEnd":"",
"freeLines":3,
"freeLine1":"Free Line 1",
"freeLine2":"Free Line 2",
"freeLine3":"Free Line 3"
}
Please note that the object above must be passed to the DHCP system as a JSON-encoded string. It must be passed into the “_dhcp_pool_attributes” attribute for it to be functional, as in the example URL.
Once a dhcp_pool resource is in the system it can be updated with IP data obtained from the IP Management system. Under DHCPv2, the DHCP system uses all the standard IPAM API endpoints and can make use of both the smartAssign and the directAssign methods. Please see the IPAM API documentation for details.
How to smart-assign a DHCP IP range from the DHCP Available resource to a dhcp_pool resource
An example command for smart-assigning a DHCP IP range from the DHCP Available resource to a newly-created dhcp_pool resource is as follows:
In this example we are using the IPAM API endpoint to smart-assign an IPv4 /31 from the DHCP Available resource (resource id 1282) to the newly-created dhcp_pool object (resource id 2180). This action removes this IP range from the available pool and prevents it from being used by other parts of ProVision.
Once an IP block is assigned to a dhcp_pool it should be updated with the proper range start and range end. A Resource Update command is used for this.
The key information here is that the “rangeStart” and the “rangeEnd” fields in the JSON-encoded '_dhcp_pool_attributes' attribute have been populated with the beginning and end of the IP range assigned by smart-assign. Also note that a new field is being populated as '_dhcp_ip_id', which contains the IPAM id of the newly-assigned IP block.
When assigning dhcp_pools covering a single host the steps are much the same, but the 'mac' field in the '_dhcp_pool_attributes' object must be populated with the MAC address of the host in question.
Linking Subnets and Hosts with DHCP Servers
DHCP Pools exist as re-usable components which can be individually assigned to any number of DHCP Servers in order to assemble flexible DHCP Configurations. Once created, a DHCP Pool is not attached to any DHCP Server in the system. DHCP Pools must be linked to a server for the pool to be included in DHCP configuration pushes.
How to link a dhcp_pool and a DHCP Server
An example of building a link between a dhcp_pool and a DHCP Server is:
The Resource Linkage system controls which DHCP Pools are associated with a given DHCP Server. In the case of linking a DHCP Pool to a DHCP Server, the relation used is “dhcpPoolLink”. This is a directional link, so it is important that resource_id1 and resource_id2 do not get confused.
relation: "dhcpPoolLink"
resource_id1: the id of the dhcp_module this pool is being linked to
resource_id2: the id of the dhcp_pool being linked
It is very important that resource_id1 not be confused with resource_id2. The link will not function with the values reversed.
To undo the above and break a DHCP Pool link, use the same command but substitute “deleteLink” for the action “addLink”.
The “id” in the above string is the id of the dhcp_module resource attached to the server you whose configuration is to be pushed. The API return payload will contain success or failure codes, as well as a description of any errors which might have occurred.
When a DHCP configuration file is pushed an SSH connection is opened to the configured server using the user, password, and port supplied to the '_dhcp_attributes' attribute on the dhcp_module resource. If the system successfully connects, it will assemble a DHCP configuration from the information given to the dhcp_module's '_dhcp_attribute' attribute and then parse and add in all linked dhcp_pool resources.
After the assembled file has been transferred to the DHCP server it will be placed in the location given by 'config_path' on the dhcp_module, and then the command described in 'config_test' will be run to determine whether or not this new file parses correctly. If 'config_test' is blank or omitted, this step is skipped.
If the file parses correctly the DHCP will be stopped and restarted according to the 'server_stop' and 'server_start' commands on the DHCP module. If there are errors at any point the system backs out, replaces old config files, and reports the errors via the 'message' return field of the API call.
Detailed API Specification
A detailed listing of API endpoints related to DHCP Servers, Pools, and Links are listed below.
The DHCPv2 system is built upon the Resource API, so actions relating to DHCP tasks are largely expressed in terms of Resource actions.
DHCPv2 Resources
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.
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.
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.example.com","option_domain_name":"example.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"}
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.
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.
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"}
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
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.
{"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.
DHCPv2 Pool Linkages
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.
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.
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.
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.
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.
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.
