DHCP Management Version 2
Warning |
---|
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.
Expand |
---|
title | 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: Code Block |
---|
[ProVision root]/api/v1/api.php?target=resource&action=add
data:
meta[type]: dhcp_module
meta[name]: [parent resource id] DHCP Module
meta[parent_id]: [parent resource id] |
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:
Code Block |
---|
[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.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"} |
This command appears rather complicated, but can be broken apart into reasonable pieces. The first section:
Code Block |
---|
target=resource&action=update&meta[id]=2178&meta[type]=dhcp_module |
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 Code Block |
---|
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:
Code Block |
---|
{
"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"
}
|
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.
Expand |
---|
title | How to add a DHCP Aggregate |
---|
|
An example command to add a DHCP Aggregate is:
Code Block |
---|
[ProVision root]/api/v1/api.php?target=ipam&action=add&block=192.168.0.0/24&rir= 1918&vlan=&tags=®ion=&resourceId=1282&allowSubAssignments=true |
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:
Code Block |
---|
[ProVision root]/api/v1/api.php?target=resource&action=get&slug=dhcp-available |
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.
Expand |
---|
title | 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: Code Block |
---|
[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:
Code Block |
---|
target=resource&action=add&meta[type]=dhcp_pool&meta[name]=New Subnet |
This section informs the API that we wish to create a new, empty “dhcp_pool” resource whose name is “New Subnet.” Code Block |
---|
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: Code Block |
---|
{
"mac":"",
"rangeStart":"",
"rangeEnd":"",
"freeLines":3,
"freeLine1":"Free Line 1",
"freeLine2":"Free Line 2",
"freeLine3":"Free Line 3"
} |
For a full explanation of each of the fields, see the Detailed API Specification.
Note |
---|
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. |
Expand |
---|
title | 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: Code Block |
---|
[ProVision root]/api/v1/api.php?target=ipam&action=smartAssign&resourceId=2180& type=ipv4&mask=31&rir=1918&assignedResourceId=1282 |
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.
Code Block |
---|
[ProVision root] |
|
DHCP Server Control
...
get
...
Examples:
SUCCESSFUL: | {"success":1,"message":"Search Successful.","data":[{"DHCPId":"1","DHCPServer": "trace.foo.com","DHCPPort":"22","DHCPUsername":"benner","DHCPPassword": "h}kc))jwqhgd","DHCPType":"ISC","DHCPConfigPath":"\/usr\/local\/dhcp\/etc \/dhcpd.conf","DHCPServerStop":"sudo kill -9 `cat \/var\/run\/dhcpd.pid`", "DHCPServerStart":"sudo \/usr\/local\/dhcp\/sbin\/dhcpd -p 75","DHCPDefaultLease" :null,"DHCPMaxLease":null,"DHCPAuthoritative":"1","DHCPLogFacility":"local7", "DHCPDomainName":null,"DHCPNameServers":null,"DHCPUseText":"0","DHCPConfigText":null}]} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Description |
---|
DHCPId | INT | The ID of the DHCP Server entry. |
DHCPServer | STRING | The address of the DHCP Server |
DHCPPort | INT | The port the DHCP Server can be reached on. |
DHCPUsername | STRING | The user name required to access the DHCP Server |
DHCPPassword | STRING | The password required to access the DHCP Server |
DHCPType | STRING | The type of DHCP Server |
DHCPConfigPath | STRING | Path to DHCP Configuration file |
DHCPServerStop | STRING | Commandto stop the DHCP Server |
DHCPServerStart | STRING | Command to start the DHCP Server |
DHCPDefaultLease | STRING | Default lease time for this server |
DHCPMaxLease | STRING | Maximum lease time for this server |
DHCPAuthoritative | BOOL | Whether or not this server is authoritative |
DHCPLogFacility | STRING | Logging facility for this server |
DHCPDomainName | STRING | Domain names servers used by this server |
DHCPNameServers | STRING | Name servers used by this server |
DHCPUseText | BOOL | Whether or not to use the entry builder or a config text file |
DHCPConfigText | STRING | The text of the config text file |
...
Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
generalFlag | BOOL | 1 | When 1, searches over the provided parameters using OR. If 0 or omitted, uses AND. |
Name | Type | Example | Description |
---|
DHCPId | INT | 123 | The DHCP Server ID to search for. |
DHCPServer | STRING | IP/domain | The Server Name to search for. |
DHCPPort | STRING | 43 | The Port to search for. |
DHCPUsername | STRING | kjennings | The Username to search for. |
DHCPType | STRING | MSDHCP | The DHCP Server Type to search for. |
DHCPConfigPath | STRING | /where/is/it/ | The Config Path to search for. |
DHCPServerStop | STRING | /path/to/server/stop | Search by server stop command. |
DHCPServerStart | STRING | /path/to/server/start | Search by server start command. |
DHCPDefaultLease | INT | 64000 | Search by default lease. |
DHCPMaxLease | INT | 128000 | Search by max lease. |
DHCPAuthoritative | BOOL | 1 | Search by whether the server is authoritative. |
DHCPLogFacility | STRING | local7 | Search by logging facility. |
DHCPDomainName | STRING | domain.name.server | Search by domain name servers. |
DHCPNameServers | STRING | ns.domain.com | Search by name servers. |
DHCPUseText | BOOL | 1 | Search by using text configs or not. |
DHCPConfigText | STRING | Text File | Search by text file contents. |
update |
---|
URL | /api/v1/api.php?target=DHCPServer&action=update |
Description | First performs a search based on the submitted DHCP Server criteria, then performs an Update across those entries based on new values. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"Update Successful."} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
Name | Type | Example | Description |
---|
SearchId | INT | 123 | The DHCP Server ID to search for. | SearchServer | STRING | IP/domain | The Server Name to search for. | SearchPort | STRING | 43 | The Port to search for. | SearchUsername | STRING | kjennings | The Username to search for. | SearchType | STRING | MSDHCP | The DHCP Server Type to search for. | SearchConfigPath | STRING | /where/is/it/ | The Config Path to search for. | SearchServerStop | STRING | /path/to/server/stop | Search by server stop command. | SearchServerStart | STRING | /path/to/server/start | Search by server start command. | SearchDefaultLease | INT | 64000 | Search by default lease. | SearchMaxLease | INT | 128000 | Search by max lease. | SearchAuthoritative | BOOL | 1 | Search by whether the server is authoritative. | SearchLogFacility | STRING | local7 | Search by logging facility. | SearchDomainName | STRING | domain.name.server | Search by domain name servers. | SearchNameServers | STRING | ns.domain.com | Search by name servers. | SearchUseText | BOOL | 1 | Search by using text configs or not. | SearchConfigText | STRING | Text File | Search by text file contents. |
Name | Type | Example | Description |
---|
UpdateServer | STRING | IP/domain | The new server address. | UpdatePort | STRING | 43 | The new port. | UpdateUsername | STRING | kjennings | The new username. | UpdatePassword | STRING | ******** | The new password. | UpdateType | STRING | ISC | The new server type. | UpdateConfigPath | STRING | /where/is/it/ | The new config path. | UpdateServerStop | STRING | /path/to/server/stop | The new server stop command. | UpdateServerStart | STRING | /path/to/server/start | The new server start command. | UpdateDefaultLease | INT | 64000 | The new default lease. | UpdateMaxLease | INT | 128000 | The new max lease. | UpdateAuthoritative | BOOL | 1 | The new Authoritative status. | UpdateLogFacility | STRING | local7 | The new logging facility. | UpdateDomainName | STRING | domain.name.server | The new domain name servers. | UpdateNameServers | STRING | ns.domain.com | The new name servers. | UpdateUseText | BOOL | 1 | The new use text file setting. | UpdateConfigText | STRING | Text File | The new use text file content. |
|
...
add
...
Examples:
SUCCESSFUL: | {"success":1,"message":"Add Successful.","data":123} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Description |
---|
data | INT | The ID of the new DHCP Server. |
...
Name | Type | Example | Description |
---|
DHCPServer | STRING | IP/domain | The new server address. |
DHCPPort | STRING | 43 | The new port. |
DHCPUsername | STRING | kjennings | The new username. |
DHCPPassword | STRING | ******** | The new password. |
DHCPType | STRING | ISC | The new server type. |
...
Name | Type | Example | Description |
---|
DHCPConfigPath | STRING | /where/is/it/ | The new config path. |
DHCPServerStop | STRING | /path/to/server/stop | The new server stop command. |
DHCPServerStart | STRING | /path/to/server/start | The new server start command. |
DHCPDefaultLease | INT | 64000 | The new default lease. |
DHCPMaxLease | INT | 128000 | The new max lease. |
DHCPAuthoritative | BOOL | 1 | The new Authoritative status. |
DHCPLogFacility | STRING | local7 | The new logging facility. |
DHCPDomainName | STRING | domain.name.server | The new domain name servers. |
DHCPNameServers | STRING | ns.domain.com | The new name servers. |
DHCPUseText | BOOL | 1 | The new use text file setting. |
DHCPConfigText | STRING | Text File | The new use text file content. |
delete |
---|
URL | /api/v1/api.php?target=DHCPServer&action=delete |
Description | Performs a search over the DHCP Servers dataset and deletes all found matches. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"DHCPServer(s) Deleted."} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. | generalFlag | BOOL | 1 | When 1, searches over the provided paramenters using OR. If 0 or omitted, uses AND. |
Name | Type | Example | Description |
---|
DHCPId | INT | 123 | The DHCP Server ID to search for. | DHCPServer | STRING | IP/domain | The Server Name to search for. | DHCPPort | STRING | 43 | The Port to search for. | DHCPUsername | STRING | kjennings | The Username to search for. | DHCPType | STRING | MSDHCP | The DHCP Server Type to search for. | DHCPConfigPath | STRING | /where/is/it/ | The Config Path to search for. | DHCPServerStop | STRING | /path/to/server/stop | Search by server stop command. | DHCPServerStart | STRING | /path/to/server/start | Search by server start command. | DHCPDefaultLease | INT | 64000 | Search by default lease. | DHCPMaxLease | INT | 128000 | Search by max lease. | DHCPAuthoritative | BOOL | 1 | Search by whether the server is authoritative. | DHCPLogFacility | STRING | local7 | Search by logging facility. | DHCPDomainName | STRING | domain.name.server | Search by domain name servers. | DHCPNameServers | STRING | ns.domain.com | Search by name servers. | DHCPUseText | BOOL | 1 | Search by using text configs or not. | DHCPConfigText | STRING | Text File | Search by text file contents. |
|
testConnection |
---|
URL | /api/v1/api.php?target=DHCPServer&action=testConnection |
Description | Performs a search over the DHCP Servers dataset and tests the login/password combo for each one returned. Returns a status array with three elements: a 1 or 0 for success/failure, the server in question, and the failure/success message. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"Pushes Attempted.","data":[[1,"foo.fun.com", "Successfully authenticated on DHCP Server 'foo.fun.com'."],[0,"foo.fun .com","Could not authenticate on server 'foo.fun.com'. Connection refused."] ,[0,"28.39.106.129","Could not connect to server '28.39.106.129'. Connection refused."]]} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. | generalFlag | BOOL | 1 | When 1, searches over the provided paramenters using OR. If 0 or omitted, uses AND. |
Name | Type | Example | Description |
---|
DHCPId | INT | 123 | The DHCP Server ID to search for. | DHCPServer | STRING | IP/domain | The Server Name to search for. | DHCPPort | STRING | 43 | The Port to search for. | DHCPUsername | STRING | kjennings | The Username to search for. | DHCPType | STRING | MSDHCP | The DHCP Server Type to search for. | DHCPConfigPath | STRING | /where/is/it/ | The Config Path to search for. | DHCPServerStop | STRING | /path/to/server/stop | Search by server stop command. | DHCPServerStart | STRING | /path/to/server/start | Search by server start command. | DHCPDefaultLease | INT | 64000 | Search by default lease. | DHCPMaxLease | INT | 128000 | Search by max lease. | DHCPAuthoritative | BOOL | 1 | Search by whether the server is authoritative. | DHCPLogFacility | STRING | local7 | Search by logging facility. | DHCPDomainName | STRING | domain.name.server | Search by domain name servers. | DHCPNameServers | STRING | ns.domain.com | Search by name servers. | DHCPUseText | BOOL | 1 | Search by using text configs or not. | DHCPConfigText | STRING | Text File | Search by text file contents. |
|
push |
---|
URL | /api/v1/api.php?target=DHCPServer&action=push |
Description | Performs a search over the DHCP Servers dataset and pushes the current config file before restarting the servers. Returns a status array with three elements: a 1 or 0 for success/failure, the server in question, and the failure/success message. A response code of '2' indicates that the push went smoothly, but the configuration file itself contains errors. In this case the error return will be the actual error output from the DHCP server. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"Pushes Attempted.","data":[[1,"trace.bind.com", "Successfully pushed DHCP Config to server 'trace.bind.com'. Server Restarted."] ,[0,"trace.bind.com","Could not authenticate on server 'trace.bind.com'. Connection refused. "],[0,"208.39.106.169","Could not connect to server '208.39.106.169'. Connection refused."]]} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. | generalFlag | BOOL | 1 | When 1, searches over the provided paramenters using OR. If 0 or omitted, uses AND. |
Name | Type | Example | Description |
---|
DHCPId | INT | 123 | The DHCP Server ID to search for. | DHCPServer | STRING | IP/domain | The Server Name to search for. | DHCPPort | STRING | 43 | The Port to search for. | DHCPUsername | STRING | kjennings | The Username to search for. | DHCPType | STRING | MSDHCP | The DHCP Server Type to search for. | DHCPConfigPath | STRING | /where/is/it/ | The Config Path to search for. | DHCPServerStop | STRING | /path/to/server/stop | Search by server stop command. | DHCPServerStart | STRING | /path/to/server/start | Search by server start command. | DHCPDefaultLease | INT | 64000 | Search by default lease. | DHCPMaxLease | INT | 128000 | Search by max lease. | DHCPAuthoritative | BOOL | 1 | Search by whether the server is authoritative. | DHCPLogFacility | STRING | local7 | Search by logging facility. | DHCPDomainName | STRING | domain.name.server | Search by domain name servers. | DHCPNameServers | STRING | ns.domain.com | Search by name servers. | DHCPUseText | BOOL | 1 | Search by using text configs or not. | DHCPConfigText | STRING | Text File | Search by text file contents. |
|
DHCP Entry Control
...
get
...
Examples:
SUCCESSFUL: | {"EntryId":"27","EntryParent":null,"EntryServerId":"1","EntryName":"mike","EntryType": "host","EntryNetmask":"255.255.255.0","EntryIPCount":"1","EntryPercent":"1","Options": [{"OptionId":"46","OptionSubnetId":"27","OptionKey":"hardware ethernet","OptionValue": "11:23:45:67:89:ab"},{"OptionId":"47","OptionSubnetId":"27","OptionKey":"fixed-address", "OptionValue":"10.20.30.158"}]}]} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Description |
---|
EntryId | INT | The ID of the DHCP Entry. |
EntryParent | INT | The parent Entry of this one |
EntryServerId | INT | The DHCP Server to which this entry belongs. |
EntryType | STRING | The Entry type. Either 'host' or 'subnet'. |
EntryName | STRING | The name of this entry. In the case of a Host, it is the hostname. In the case of a subnet, it is the subnet address. |
EntryNetmask | STRING | The subnet mask. Empty on type 'host' |
EntryIPCount | INT | The number of IPs in this Entry. |
EntryPercent | INT | Percentage of this Entry currently assigned. |
Options | STRING | If present, this array contains objects enumerating each option and its type. |
OptionId | STRING | The ID of this Option |
OptionSubnetId | INT | The ID of the parent. Identical to EntryId. |
OptionKey | STRING | The key portion of the option key-value pairing. |
OptionValue | STRING | The value portion of the option key-value pairing. |
...
Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
generalFlag | BOOL | 1 | When 1, searches over the provided parameters using OR. If 0 or omitted, uses AND. |
Name | Type | Example | Description |
---|
EntryId | INT | 123 | The ID of the DHCP Entry to search for. |
EntryParent | INT | 123 | The parent Entry to search for. |
EntryServerId | INT | 123 | The DHCP Server to search for. |
EntryType | STRING | subnet | The Entry type to search for. |
EntryName | STRING | 30.20.10.1 | The name to search for. |
EntryNetmask | STRING | 255.255.255.0 | The subnet mask to search for. |
OptionId | STRING | 123 | The Option ID to search for. |
OptionKey | STRING | range | The key portion of the option key-value pairing to search for. |
OptionValue | STRING | 30.20.10.10 30.20.10.40 | The value portion of the option key-value pairing to search for. |
update |
---|
URL | /api/v1/api.php?target=DHCPEntry&action=update |
Description | First performs a search based on the submitted DHCP Entry criteria, then performs an Update across those entries and all found Options based on new values. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"Update Successful."} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
Name | Type | Example | Description |
---|
SearchId | INT | 123 | The ID of the DHCP Entry to search for. | SearchParent | INT | 123 | The parent Entry to search for. | SearchServerId | INT | 123 | The DHCP Server to search for. | SearchType | STRING | subnet | The Entry type to search for. | SearchName | STRING | 30.20.10.1 | The name to search for. | SearchNetmask | STRING | 255.255.255.0 | The subnet mask to search for. | SearchId | STRING | 123 | The Option ID to search for. | SearchKey | STRING | range | The key portion of the option key-value pairing to search for. | SearchValue | STRING | 30.20.10.10 30.20.10.40 | The value portion of the option key-value pairing to search for. |
Name | Type | Example | Description |
---|
UpdateParent | INT | 123 | The new parent data. | UpdateServerId | INT | 123 | The new DHCP Server ID. | UpdateType | STRING | subnet | The new Entry type. | UpdateName | STRING | 30.20.10.1 | The new name. | UpdateNetmask | STRING | 255.255.255.0 | The new subnet mask. | UpdateKey | STRING | range | The new key portion of the option key-value pairing. | UpdateValue | STRING | 30.20.10.10 30.20.10.40 | The new value portion of the option key-value pairing. |
|
updateOption |
---|
URL | /api/v1/api.php?target=DHCPEntry&action=updateOption |
Description | First performs a search based on the submitted DHCP Entry criteria, then performs an Update across all found Options, without altering found Entries. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"Update Successful."} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
Name | Type | Example | Description |
---|
SearchId | INT | 123 | The ID of the DHCP Entry to search for. | SearchParent | INT | 123 | The parent Entry to search for. | SearchServerId | INT | 123 | The DHCP Server to search for. | SearchType | STRING | subnet | The Entry type to search for. | SearchName | STRING | 30.20.10.1 | The name to search for. | SearchNetmask | STRING | 255.255.255.0 | The subnet mask to search for. | SearchId | STRING | 123 | The Option ID to search for. | SearchKey | STRING | range | The key portion of the option key-value pairing to search for. | SearchValue | STRING | 30.20.10.10 30.20.10.40 | The value portion of the option key-value pairing to search for. |
Name | Type | Example | Description |
---|
UpdateKey | STRING | range | The new key portion of the option key-value pairing. | UpdateValue | STRING | 30.20.10.10 30.20.10.40 | The new value portion of the option key-value pairing. |
|
...
add
...
Examples:
SUCCESSFUL: | {"success":1,"message":"Add Successful.","data":123} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Description |
---|
data | INT | The ID of the new DHCP Entry. |
...
Name | Type | Example | Description |
---|
EntryServerId | INT | 123 | The DHCP Server this new Entry belongs to. |
EntryType | STRING | subnet | The Entry type of this new Entry. |
EntryName | STRING | 30.20.10.1 | The name of this new Entry. |
EntryNetmask | STRING | 255.255.255.0 | The subnet mask of this new Entry. |
...
Name | Type | Example | Description |
---|
EntryParent | INT | 123 | The parent Entry to search for. |
...
addOption
...
...
Examples:
SUCCESSFUL: | {"success":1,"message":"Add Successful.","data":123} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Description |
---|
data | INT | The ID of the new DHCP Option. |
...
Name | Type | Example | Description |
---|
OptionSubnetId | INT | 123 | The DHCP Entry this Option belongs to. |
OptionKey | STRING | range | The key portion of the option key-value pairing to search for. |
OptionValue | STRING | 30.20.10.10 30.20.10.40 | The value portion of the option key-value pairing to search for. |
delete |
---|
URL | /api/v1/api.php?target=DHCPEntry&action=delete |
Description | Performs a search over the DHCP Entry dataset and deletes all found matches, along with their associated Options. |
Returns | Examples: SUCCESSFUL: | {"success":1,"message":"DHCPEntries(s) Deleted."} | ERROR: | {"success":0, "message":"error message"} |
|
Optional Parameters | Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
Name | Type | Example | Description |
---|
EntryId | INT | 123 | The ID of the DHCP Entry to search for. | EntryParent | INT | 123 | The parent Entry to search for. | EntryServerId | INT | 123 | The DHCP Server to search for. | EntryType | STRING | subnet | The Entry type to search for. | EntryName | STRING | 30.20.10.1 | The name to search for. | EntryNetmask | STRING | 255.255.255.0 | The subnet mask to search for. | OptionId | STRING | 123 | The Option ID to search for. | OptionKey | STRING | range | The key portion of the option key-value pairing to search for. | OptionValue | STRING | 30.20.10.10 30.20.10.40 | The value portion of the option key-value pairing to search for. |
|
...
deleteOption
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]=2180 |
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.
Expand |
---|
title | 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:
Code Block |
---|
[ProVision root]/api/v1/api.php?target=resource&action=addLink&resource_id1=2178& resource_id2=1452&relation=dhcpPoolLink |
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. Code Block |
---|
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 |
Note |
---|
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”.
Code Block |
---|
[ProVision root]/api/v1/api.php?target=resource&action=deleteLink&resource_id1=2178& resource_id2=2179&relation=dhcpPoolLink |
|
Pushing Configurations
Pushing configuration files and restarting a DHCP server is a fairly straightforward process.
Expand |
---|
title | How to push configuration files |
---|
|
Once the server has been configured according to the previous sections, hitting the following API endpoint will trigger a DHCP push:
Code Block |
---|
[ProVision root] |
|
...
/api/v1/api.php?target=dhcp&action= |
|
...
...
...
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 can be found here:
...
Examples:
SUCCESSFUL: | {"success":1,"message":"DHCP Option(s) Deleted."} |
ERROR: | {"success":0, "message":"error message"} |
...
Name | Type | Example | Description |
---|
likeFlag | BOOL | 1 | When 1, string searches are done via LIKE with wildcards at both ends. When 0, strict comparison is used. |
...