Home Explore Help
Sign In
SMusatov
/
TechnitiumSoftware-DnsServer
mirror of https://github.com/TechnitiumSoftware/DnsServer.git
1
0
Fork 0
Files
Branch: v6.2.3
Branches Tags
TechnitiumSoftw...
/
APIDOCS.md

APIDOCS.md 71 KB
Permalink History Raw

Technitium DNS Server API Documentation

Technitium DNS Server provides a HTTP API which is used by the web console to perform all actions. Thus any action that the web console does can be performed using this API from your own applications.

The URL in the documentation uses localhost and port 5380. You should use the hostname/IP address and port that is specific to your DNS server instance.

API Response Format

The HTTP API returns a JSON formatted response for all requests. The JSON object returned contains status property which indicate if the request was successful.

The status property can have following values:

  • ok: This indicates that the call was successful.
  • error: This response tells the call failed and provides additional properties that provide details about the error.
  • invalid-token: When a session has expired or an invalid token was provided this response is received.

A successful response will look as shown below. Note that there will be other properties in the response which are specific to the request that was made.

{
	"status": "ok"
}

In case of errors, the response will look as shown below. The errorMessage property can be shown in the UI to the user while the other two properties are useful for debugging.

{
	"status": "error",
	"errorMessage": "error message",
	"stackTrace": "application stack trace",
	"innerErrorMessage": "inner exception message"
}

Name Server Address Format

The DNS server uses a specific text format to define the name server address to allow specifying multiple parameters like the domain name, IP address, port or URL. This format is used in the web console as well as in this API. It is used to specify forwarder address in DNS settings, conditional forwarder zone's FWD record, or the server address in DNS Client resolve query API calls.

  • A name server address with just an IP address is specified just as its string literal with optional port number is as shown: 1.1.1.1 or 8.8.8.8:53. When port is not specified, the default port number for the selected DNS transport protocol is used.
  • A name server address with just a domain name is specified similarly as its string literal with optional port number is as shown: dns.quad9.net:853 or cloudflare-dns.com. When port is not specified, the default port number for the selected DNS transport protocol is used.
  • A combination of domain name and IP address together with optional port number is as shown: cloudflare-dns.com (1.1.1.1), dns.quad9.net (9.9.9.9:853) or dns.quad9.net:853 (9.9.9.9). Here, the domain name (with optional port number) is specified and the IP address (with optional port number) is specified in a round bracket. When port is not specified, the default port number for the selected DNS transport protocol is used. This allows the DNS server to use the specified IP address instead of trying to resolve it separately.
  • A name server address that specifies a DNS-over-HTTPS URL is specified just as its string literal is as shown: https://cloudflare-dns.com/dns-query
  • A combination of DNS-over-HTTPS URL and IP address together is as shown: https://cloudflare-dns.com/dns-query (1.1.1.1). Here, the IP address of the domain name in the URL is specified in the round brackets. This allows the DNS server to use the specified IP address instead of trying to resolve it separately.
  • IPv6 addresses must always be enclosed in square brackets as shown: cloudflare-dns.com ([2606:4700:4700::1111]:853) or [2606:4700:4700::1111]

Authentication API Calls

These API calls allow to login or logout using credentials. Once logged in, a session token is returned which MUST be used with all other API calls.

Login

This call authenticates with the server and generates a session token to be used for subsequent API calls.

URL: http://localhost:5380/api/login?user=admin&pass=admin

WHERE:

  • user: The username. The built-in administrator username on the DNS server is admin.
  • pass: The password for the user. The default password for admin user is admin.

WARNING: It is highly recommended to change the password on first use to avoid security related issues.

RESPONSE:

{
	"status": "ok",
	"token": "932b2a3495852c15af01598f62563ae534460388b6a370bfbbb8bb6094b698e9"
}

WHERE:

  • token: Is the session token generated that MUST be used with all subsequent API calls.

Logout

This call ends the session generated by the login call. The token generated by the login call would no longer be valid after calling logout.

URL: http://localhost:5380/api/logout?token=932b2a3495852c15af01598f62563ae534460388b6a370bfbbb8bb6094b698e9

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"status": "ok"
}

Change Password

This call allows changing the password for the current logged in user.

NOTE: It is highly recommended to change the admin user password on first use to avoid security related issues.

URL: http://localhost:5380/api/changePassword?token=x&pass=password

WHERE:

  • token: The session token generated by the login call.
  • pass: The new password for the currently logged in user.

RESPONSE:

{
	"status": "ok"
}

General DNS API Calls

Check For Update

This call requests the server to check for software update.

URL: http://localhost:5380/api/checkForUpdate?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"updateAvailable": true,
		"displayText": "New version available!",
		"downloadLink": "https://download.technitium.com/dns/DnsServerSetup.zip"
	},
	"status": "ok"
}

Get DNS Settings

This call returns all the DNS server settings.

URL: http://localhost:5380/api/getDnsSettings?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"version": "6.2",
		"dnsServerDomain": "server1",
		"dnsServerLocalEndPoints": [
			"0.0.0.0:53",
			"[::]:53"
		],
		"webServiceLocalAddresses": [
			"0.0.0.0",
			"[::]"
		],
		"webServiceHttpPort": 5380,
		"webServiceEnableTls": false,
		"webServiceHttpToTlsRedirect": false,
		"webServiceTlsPort": 53443,
		"webServiceTlsCertificatePath": null,
		"webServiceTlsCertificatePassword": "************",
		"enableDnsOverHttp": false,
		"enableDnsOverTls": false,
		"enableDnsOverHttps": false,
		"dnsTlsCertificatePath": null,
		"dnsTlsCertificatePassword": "************",
		"preferIPv6": false,
		"enableLogging": true,
		"logQueries": true,
		"useLocalTime": false,
		"logFolder": "logs",
		"maxLogFileDays": 365,
		"maxStatFileDays": 365,
		"allowRecursion": true,
		"allowRecursionOnlyForPrivateNetworks": true,
		"randomizeName": true,
		"serveStale": true,
		"serveStaleTtl": 259200,
		"cachePrefetchEligibility": 2,
		"cachePrefetchTrigger": 9,
		"cachePrefetchSampleIntervalInMinutes": 5,
		"cachePrefetchSampleEligibilityHitsPerHour": 30,
		"proxy": {
			"type": "Socks5",
			"address": "192.168.10.2",
			"port": 9050,
			"username": "username",
			"password": "password",
			"bypass": [
				"127.0.0.0/8",
				"169.254.0.0/16",
				"fe80::/10",
				"::1",
				"localhost"
			]
		},
		"forwarders": [
			"https://cloudflare-dns.com/dns-query (1.1.1.1)",
			"https://cloudflare-dns.com/dns-query (1.0.0.1)"
		],
		"forwarderProtocol": "Udp",
		"useNxDomainForBlocking": false,
		"blockListUrls": [
			"https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts",
			"https://mirror1.malwaredomains.com/files/justdomains",
			"https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt",
			"https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt"
		],
		"blockListUpdateIntervalHours": 24,
		"blockListNextUpdatedOn": "12/20/2020 12:46:27"
	},
	"status": "ok"
}

Set DNS Settings

This call allows to change the DNS server settings.

URL: http://localhost:5380/api/setDnsSettings?token=x&dnsServerDomain=server1&dnsServerLocalEndPoints=0.0.0.0:53,[::]:53&webServiceLocalAddresses=0.0.0.0,[::]&webServiceHttpPort=5380&webServiceEnableTls=false&webServiceTlsPort=53443&webServiceTlsCertificatePath=&webServiceTlsCertificatePassword=&enableDnsOverHttp=false&enableDnsOverTls=false&enableDnsOverHttps=false&dnsTlsCertificatePath=&dnsTlsCertificatePassword=&preferIPv6=false&logQueries=true&allowRecursion=true&allowRecursionOnlyForPrivateNetworks=true&randomizeName=true&cachePrefetchEligibility=2&cachePrefetchTrigger=9&cachePrefetchSampleIntervalInMinutes=5&cachePrefetchSampleEligibilityHitsPerHour=30&proxyType=socks5&proxyAddress=192.168.10.2&proxyPort=9050&proxyUsername=username&proxyPassword=password&proxyBypass=127.0.0.0/8,169.254.0.0/16,fe80::/10,::1,localhost&forwarders=192.168.10.2&forwarderProtocol=Udp&useNxDomainForBlocking=false&blockListUrls=https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts,https://mirror1.malwaredomains.com/files/justdomains,https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt,https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt

WHERE:

  • token: The session token generated by the login call.
  • dnsServerDomain (optional): The primary domain name used by this DNS Server to identify itself.
  • dnsServerLocalEndPoints (optional): Local end points are the network interface IP addresses and ports you want the DNS Server to listen for requests.
  • webServiceLocalAddresses (optional): Local addresses are the network interface IP addresses you want the web service to listen for requests.
  • webServiceHttpPort (optional): Specify the TCP port number for the web console and this API web service. Default value is 5380.
  • webServiceEnableTls (optional): Set this to true to start the HTTPS service to acccess web service.
  • webServiceTlsPort (optional): Specified the TCP port number for the web console for HTTPS access.
  • webServiceTlsCertificatePath (optional): Specify a PKCS #12 certificate (.pfx) file path on the server. The certificate must contain private key. This certificate is used by the web console for HTTPS access.
  • webServiceTlsCertificatePassword (optional): Enter the certificate (.pfx) password, if any.
  • enableDnsOverHttp (optional): Enable this option to accept DNS-over-HTTP requests for both wire and json response formats. It must be used with a TLS terminating reverse proxy like nginx and will work only on private networks.
  • enableDnsOverTls (optional): Enable this option to accept DNS-over-TLS requests.
  • enableDnsOverHttps (optional): Enable this option to accept DNS-over-HTTPS requests for both wire and json response formats.
  • dnsTlsCertificatePath (optional): Specify a PKCS #12 certificate (.pfx) file path on the server. The certificate must contain private key. This certificate is used by the DNS-over-TLS and DNS-over-HTTPS optional protocols.
  • dnsTlsCertificatePassword (optional): Enter the certificate (.pfx) password, if any.
  • preferIPv6 (optional): DNS Server will use IPv6 for querying whenever possible with this option enabled. Default value is false.
  • enableLogging (optional): Enable this option to log error and audit logs into the log file. Default value is true.
  • logQueries (optional): Enable this option to log every query received by this DNS Server and the corresponding response answers into the log file. Default value is false.
  • useLocalTime (optional): Enable this option to use local time instead of UTC for logging. Default value is false.
  • logFolder (optional): The folder path on the server where the log files should be saved. The path can be relative to the DNS server config folder. Default value is logs.
  • maxLogFileDays (optional): Max number of days to keep the log files. Log files older than the specified number of days will be deleted automatically. Recommended value is 365. Set 0 to disable auto delete.
  • maxStatFileDays (optional): Max number of days to keep the dashboard stats. Stat files older than the specified number of days will be deleted automatically. Recommended value is 365. Set 0 to disable auto delete.
  • allowRecursion (optional): Enable recursion to allow this DNS Server to resolve any domain name. Default value is true.
  • allowRecursionOnlyForPrivateNetworks (optional): Enable this option if you want to support recursion only on private networks. Any recursive request from public network will be refused. Default value is true.
  • randomizeName (optional): Enables QNAME randomization draft-vixie-dnsext-dns0x20-00 when using UDP as the transport protocol. Default value is true.
  • serveStale (optional): Enable the serve stale feature to improve resiliency by using expired or stale records in cache when the DNS server is unable to reach the upstream or authoritative name servers. Default value is true.
  • serveStaleTtl (optional): The TTL value in seconds which should be used for cached records that are expired. When the serve stale TTL too expires for a stale record, it gets removed from the cache. Recommended value is between 1-3 days and maximum supported value is 7 days. Default value is 259200.
  • cachePrefetchEligibility (optional): The minimum initial TTL value of a record needed to be eligible for prefetching.
  • cachePrefetchTrigger (optional): A record with TTL value less than trigger value will initiate prefetch operation immediately for itself. Set 0 to disable prefetching & auto prefetching.
  • cachePrefetchSampleIntervalInMinutes (optional): The interval to sample eligible domain names from last hour stats for auto prefetch.
  • cachePrefetchSampleEligibilityHitsPerHour (optional): Minimum required hits per hour for a domain name to be eligible for auto prefetch.
  • proxyType (optional): The type of proxy protocol to be used. Valid values are [None, Http, Socks5].
  • proxyAddress (optional): The proxy server hostname or IP address.
  • proxyPort (optional): The proxy server port.
  • proxyUsername (optional): The proxy server username.
  • proxyPassword (optional): The proxy server password.
  • proxyBypass (optional): A comma separated bypass list consisting of IP addresses, network addresses in CIDR format, or host/domain names to never use proxy for.
  • forwarders (optional): A comma separated list of forwarders to be used by this DNS server. Set this parameter to empty string to remove existing forwarders so that the DNS server does recursive resolution by itself.
  • forwarderProtocol (optional): The forwarder DNS transport protocol to be used. Valid values are [Udp, Tcp, Tls, Https].
  • useNxDomainForBlocking (optional): Enabling this will return NX Domain response instead of 0.0.0.0 address for blocked domains. Default value is false.
  • blockListUrls (optional): A comma separated list of block list URLs that this server must automatically download and use with the block lists zone. DNS Server will use the data returned by the block list URLs to update the block list zone automatically every 24 hours. The expected file format is standard hosts file format or plain text file containing list of domains to block.
  • blockListUpdateIntervalHours (optional): The interval in hours to automatically download and update the block lists. Default value is 24.

RESPONSE: This call returns the newly updated settings in the same format as that of the getDnsSettings call.

Force Update Block Lists

This call allows to reset the next update schedule and force download and update of the block lists.

URL: http://localhost:5380/api/forceUpdateBlockLists?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"status": "ok"
}

Backup Settings

This call returns a zip file containing copies of all the items that were requested to be backed up.

URL: http://localhost:5380/api/backupSettings?token=x&blockLists=true&logs=true&scopes=true&stats=true&zones=true&allowedZones=true&blockedZones=true&dnsSettings=true&logSettings=true

WHERE:

  • token: The session token generated by the login call.
  • blockLists (optional): Set to true to backup block lists cache files. Default value is false.
  • logs (optional): Set to true to backup log files. Default value is false.
  • scopes (optional): Set to true to backup DHCP scope files. Default value is false.
  • apps (optional): Set to true to backup the installed DNS apps. Default value is false.
  • stats (optional): Set to true to backup dashboard stats files. Default value is false.
  • zones (optional): Set to true to backup DNS zone files. Default value is false.
  • allowedZones (optional): Set to true to backup allowed zones file. Default value is false.
  • blockedZones (optional): Set to true to backup blocked zones file. Default value is false.
  • dnsSettings (optional): Set to true to backup DNS settings file. Default value is false.
  • logSettings (optional): Set to true to backup log settings file. Default value is false.

RESPONSE: A zip file with content type application/zip and content disposition set to attachment.

Restore Settings

This call restores selected items from a given backup zip file.

URL: http://localhost:5380/api/restoreSettings?token=x&blockLists=true&logs=true&scopes=true&stats=true&zones=true&allowedZones=true&blockedZones=true&dnsSettings=true&logSettings=true&deleteExistingFiles=true

WHERE:

  • token: The session token generated by the login call.
  • blockLists (optional): Set to true to restore block lists cache files. Default value is false.
  • logs (optional): Set to true to restore log files. Default value is false.
  • scopes (optional): Set to true to restore DHCP scope files. Default value is false.
  • apps (optional): Set to true to restore the DNS apps. Default value is false.
  • stats (optional): Set to true to restore dashboard stats files. Default value is false.
  • zones (optional): Set to true to restore DNS zone files. Default value is false.
  • allowedZones (optional): Set to true to restore allowed zones file. Default value is false.
  • blockedZones (optional): Set to true to restore blocked zones file. Default value is false.
  • dnsSettings (optional): Set to true to restore DNS settings file. Default value is false.
  • logSettings (optional): Set to true to restore log settings file. Default value is false.
  • deleteExistingFiles (optional). Set to true to delete existing files for selected items. Default value is false.

REQUEST: This is a POST request call where the request must be multi-part form data with the backup zip file data in binary format.

RESPONSE: This call returns the newly updated settings in the same format as that of the getDnsSettings call.

Get Stats

This call returns the stats that are shown on the web console's dashboard.

URL: http://localhost:5380/api/getStats?token=x&type=lastHour

WHERE:

  • token: The session token generated by the login call.
  • type: The duration type for which valid values are: [lastHour, lastDay, lastWeek, lastMonth, lastYear, custom]
  • start (optional): The start date in UTC. Applies only to custom type.
  • end (optional): The end date in UTC. Applies only to custom type.

RESPONSE:

{
	"response": {
		"stats": {
			"totalQueries": 1857,
			"totalNoError": 1820,
			"totalServerFailure": 0,
			"totalNxDomain": 37,
			"totalRefused": 0,
			"totalAuthoritative": 1358,
			"totalRecursive": 160,
			"totalCached": 228,
			"totalBlocked": 111,
			"totalClients": 831,
			"allowedZones": 6,
			"blockedZones": 1136182
		},
		"mainChartData": {
			"labels": [
				"15:55",
				"15:56",
				"15:57",
				"15:58",
				"15:59",
				"16:00",
				"16:01",
				"16:02",
				"16:03",
				"16:04",
				"16:05",
				"16:06",
				"16:07",
				"16:08",
				"16:09",
				"16:10",
				"16:11",
				"16:12",
				"16:13",
				"16:14",
				"16:15",
				"16:16",
				"16:17",
				"16:18",
				"16:19",
				"16:20",
				"16:21",
				"16:22",
				"16:23",
				"16:24",
				"16:25",
				"16:26",
				"16:27",
				"16:28",
				"16:29",
				"16:30",
				"16:31",
				"16:32",
				"16:33",
				"16:34",
				"16:35",
				"16:36",
				"16:37",
				"16:38",
				"16:39",
				"16:40",
				"16:41",
				"16:42",
				"16:43",
				"16:44",
				"16:45",
				"16:46",
				"16:47",
				"16:48",
				"16:49",
				"16:50",
				"16:51",
				"16:52",
				"16:53",
				"16:54"
			],
			"datasets": [
				{
					"label": "Total",
					"backgroundColor": "rgba(102, 153, 255, 0.1)",
					"borderColor": "rgb(102, 153, 255)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						38,
						55,
						26,
						54,
						38,
						19,
						31,
						19,
						36,
						40,
						18,
						37,
						23,
						30,
						31,
						23,
						17,
						9,
						34,
						55,
						18,
						6,
						13,
						38,
						30,
						47,
						31,
						33,
						52,
						44,
						22,
						30,
						23,
						19,
						37,
						23,
						27,
						24,
						33,
						34,
						21,
						29,
						39,
						36,
						15,
						63,
						49,
						22,
						27,
						25,
						38,
						34,
						32,
						29,
						30,
						39,
						22,
						38,
						24,
						28
					]
				},
				{
					"label": "No Error",
					"backgroundColor": "rgba(92, 184, 92, 0.1)",
					"borderColor": "rgb(92, 184, 92)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						37,
						53,
						24,
						52,
						37,
						19,
						31,
						19,
						36,
						38,
						15,
						35,
						23,
						29,
						31,
						23,
						17,
						9,
						34,
						53,
						17,
						6,
						13,
						37,
						30,
						47,
						31,
						33,
						52,
						42,
						21,
						30,
						23,
						19,
						37,
						23,
						27,
						24,
						33,
						32,
						20,
						29,
						39,
						35,
						15,
						58,
						49,
						22,
						27,
						23,
						37,
						34,
						32,
						29,
						30,
						39,
						22,
						38,
						24,
						26
					]
				},
				{
					"label": "Server Failure",
					"backgroundColor": "rgba(217, 83, 79, 0.1)",
					"borderColor": "rgb(217, 83, 79)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0
					]
				},
				{
					"label": "NX Domain",
					"backgroundColor": "rgba(7, 7, 7, 0.1)",
					"borderColor": "rgb(7, 7, 7)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						1,
						2,
						2,
						2,
						1,
						0,
						0,
						0,
						0,
						2,
						3,
						2,
						0,
						1,
						0,
						0,
						0,
						0,
						0,
						2,
						1,
						0,
						0,
						1,
						0,
						0,
						0,
						0,
						0,
						2,
						1,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						2,
						1,
						0,
						0,
						1,
						0,
						5,
						0,
						0,
						0,
						2,
						1,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						2
					]
				},
				{
					"label": "Refused",
					"backgroundColor": "rgba(91, 192, 222, 0.1)",
					"borderColor": "rgb(91, 192, 222)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0,
						0
					]
				},
				{
					"label": "Authoritative",
					"backgroundColor": "rgba(150, 150, 0, 0.1)",
					"borderColor": "rgb(150, 150, 0)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						23,
						27,
						20,
						29,
						28,
						17,
						19,
						16,
						32,
						35,
						15,
						32,
						17,
						14,
						23,
						20,
						7,
						6,
						17,
						34,
						11,
						3,
						11,
						28,
						12,
						38,
						23,
						29,
						35,
						41,
						18,
						20,
						16,
						10,
						21,
						21,
						22,
						20,
						20,
						24,
						17,
						26,
						28,
						22,
						10,
						46,
						44,
						22,
						15,
						21,
						33,
						28,
						26,
						19,
						24,
						32,
						18,
						34,
						18,
						21
					]
				},
				{
					"label": "Recursive",
					"backgroundColor": "rgba(23, 162, 184, 0.1)",
					"borderColor": "rgb(23, 162, 184)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						6,
						8,
						2,
						7,
						2,
						1,
						2,
						1,
						1,
						2,
						0,
						3,
						2,
						6,
						2,
						0,
						3,
						2,
						9,
						3,
						2,
						1,
						0,
						3,
						6,
						2,
						4,
						1,
						7,
						0,
						0,
						7,
						1,
						5,
						6,
						0,
						2,
						1,
						3,
						3,
						0,
						1,
						2,
						3,
						1,
						7,
						2,
						0,
						6,
						2,
						2,
						3,
						0,
						4,
						2,
						1,
						1,
						3,
						0,
						4
					]
				},
				{
					"label": "Cached",
					"backgroundColor": "rgba(111, 84, 153, 0.1)",
					"borderColor": "rgb(111, 84, 153)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						6,
						14,
						3,
						12,
						6,
						0,
						6,
						1,
						3,
						0,
						2,
						1,
						3,
						6,
						3,
						2,
						6,
						1,
						6,
						6,
						2,
						1,
						0,
						5,
						10,
						5,
						3,
						2,
						6,
						1,
						2,
						2,
						4,
						3,
						8,
						2,
						2,
						2,
						4,
						5,
						2,
						1,
						7,
						8,
						3,
						10,
						2,
						0,
						6,
						1,
						1,
						2,
						5,
						6,
						3,
						5,
						2,
						1,
						5,
						2
					]
				},
				{
					"label": "Blocked",
					"backgroundColor": "rgba(255, 165, 0, 0.1)",
					"borderColor": "rgb(255, 165, 0)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						3,
						6,
						1,
						6,
						2,
						1,
						4,
						1,
						0,
						3,
						1,
						1,
						1,
						4,
						3,
						1,
						1,
						0,
						2,
						12,
						3,
						1,
						2,
						2,
						2,
						2,
						1,
						1,
						4,
						2,
						2,
						1,
						2,
						1,
						2,
						0,
						1,
						1,
						6,
						2,
						2,
						1,
						2,
						3,
						1,
						0,
						1,
						0,
						0,
						1,
						2,
						1,
						1,
						0,
						1,
						1,
						1,
						0,
						1,
						1
					]
				},
				{
					"label": "Clients",
					"backgroundColor": "rgba(51, 122, 183, 0.1)",
					"borderColor": "rgb(51, 122, 183)",
					"borderWidth": 2,
					"fill": true,
					"data": [
						15,
						21,
						13,
						21,
						17,
						15,
						14,
						15,
						22,
						29,
						13,
						21,
						17,
						12,
						18,
						12,
						9,
						6,
						16,
						29,
						11,
						5,
						10,
						26,
						13,
						28,
						20,
						24,
						24,
						31,
						14,
						15,
						12,
						13,
						18,
						15,
						14,
						18,
						15,
						22,
						13,
						18,
						21,
						14,
						11,
						28,
						32,
						18,
						14,
						13,
						22,
						18,
						16,
						15,
						18,
						20,
						13,
						26,
						15,
						17
					]
				}
			]
		},
		"queryResponseChartData": {
			"labels": [
				"Authoritative",
				"Recursive",
				"Cached",
				"Blocked"
			],
			"datasets": [
				{
					"data": [
						1358,
						160,
						228,
						111
					],
					"backgroundColor": [
						"rgba(150, 150, 0, 0.5)",
						"rgba(23, 162, 184, 0.5)",
						"rgba(111, 84, 153, 0.5)",
						"rgba(255, 165, 0, 0.5)"
					]
				}
			]
		},
		"queryTypeChartData": {
			"labels": [
				"A",
				"AAAA",
				"NS",
				"MX",
				"Others"
			],
			"datasets": [
				{
					"data": [
						1430,
						410,
						12,
						2,
						2
					],
					"backgroundColor": [
						"rgba(102, 153, 255, 0.5)",
						"rgba(92, 184, 92, 0.5)",
						"rgba(91, 192, 222, 0.5)",
						"rgba(255, 165, 0, 0.5)",
						"rgba(51, 122, 183, 0.5)"
					]
				}
			]
		},
		"topClients": [
			{
				"name": "192.168.10.5",
				"domain": "server1.local",
				"hits": 236
			},
			{
				"name": "192.168.10.4",
				"domain": "nas1.local",
				"hits": 16
			},
			{
				"name": "192.168.10.6",
				"domain": "server2.local",
				"hits": 14
			},
			{
				"name": "192.168.10.3",
				"domain": "nas2.local",
				"hits": 12
			},
			{
				"name": "217.31.193.175",
				"domain": "condor175.knot-resolver.cz",
				"hits": 10
			},
			{
				"name": "162.158.180.45",
				"hits": 9
			},
			{
				"name": "217.31.193.163",
				"domain": "gondor-resolver.labs.nic.cz",
				"hits": 9
			},
			{
				"name": "210.245.24.68",
				"hits": 8
			},
			{
				"name": "101.91.16.140",
				"hits": 8
			}
		],
		"topDomains": [
			{
				"name": "ns1.technitium.net",
				"hits": 823
			},
			{
				"name": "download.technitium.com",
				"hits": 179
			},
			{
				"name": "go.technitium.com",
				"hits": 171
			},
			{
				"name": "technitium.com",
				"hits": 95
			},
			{
				"name": "www.google.com",
				"hits": 58
			},
			{
				"name": "www.wd2go.com",
				"hits": 28
			},
			{
				"name": "graph.facebook.com",
				"hits": 20
			},
			{
				"name": "dnsclient.net",
				"hits": 17
			},
			{
				"name": "blog.technitium.com",
				"hits": 16
			},
			{
				"name": "profile.accounts.firefox.com",
				"hits": 13
			}
		],
		"topBlockedDomains": [
			{
				"name": "ssl.google-analytics.com",
				"hits": 27
			},
			{
				"name": "www.googleadservices.com",
				"hits": 20
			},
			{
				"name": "incoming.telemetry.mozilla.org",
				"hits": 9
			},
			{
				"name": "s.youtube.com",
				"hits": 7
			},
			{
				"name": "mobile.pipe.aria.microsoft.com",
				"hits": 6
			},
			{
				"name": "in.api.glance.inmobi.com",
				"hits": 6
			},
			{
				"name": "app-measurement.com",
				"hits": 5
			},
			{
				"name": "dc.services.visualstudio.com",
				"hits": 3
			},
			{
				"name": "settings.crashlytics.com",
				"hits": 3
			},
			{
				"name": "register.appsflyer.com",
				"hits": 2
			}
		]
	},
	"status": "ok"
}

Get Top Stats

This call returns the top stats data for specified stats type.

URL: http://localhost:5380/api/getStats?token=x&type=lastHour&statsType=TopClients&limit=1000

WHERE:

  • token: The session token generated by the login call.
  • type (optional): The duration type for which valid values are: [lastHour, lastDay, lastWeek, lastMonth, lastYear]. Default value is lastHour.
  • statsType: The stats type for which valid values are : [TopClients, TopDomains, TopBlockedDomains]
  • limit (optional): The limit of records to return. Default value is 1000.

RESPONSE: The response json will include the object with definition same in the getStats response depending on the statsType. For example below is the response for TopClients:

{
	"response": {
		"topClients": [
			{
				"name": "192.168.10.5",
				"domain": "server1.local",
				"hits": 236
			},
			{
				"name": "192.168.10.4",
				"domain": "nas1.local",
				"hits": 16
			},
			{
				"name": "192.168.10.6",
				"domain": "server2.local",
				"hits": 14
			},
			{
				"name": "192.168.10.3",
				"domain": "nas2.local",
				"hits": 12
			},
			{
				"name": "217.31.193.175",
				"domain": "condor175.knot-resolver.cz",
				"hits": 10
			},
			{
				"name": "162.158.180.45",
				"hits": 9
			},
			{
				"name": "217.31.193.163",
				"domain": "gondor-resolver.labs.nic.cz",
				"hits": 9
			},
			{
				"name": "210.245.24.68",
				"hits": 8
			},
			{
				"name": "101.91.16.140",
				"hits": 8
			}
		],
	},
	"status": "ok"
}

DNS Cache API Calls

Flush DNS Cache

This call clears all the DNS cache from the server forcing the DNS server to make recursive queries again to populate the cache.

URL: http://localhost:5380/api/flushDnsCache?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"status": "ok"
}

List Cached Zones

List all cached zones.

URL: http://localhost:5380/api/listCachedZones?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain (Optional): The domain name to list records. If not passed, the domain is set to empty string which corresponds to the zone root.
  • direction (Optional): Allows specifying the direction of browsing the zone. Valid values are [up, down] and the default value is down when parameter is missing. This option allows the server to skip empty labels in the domain name when browsing up or down.

RESPONSE:

{
	"response": {
		"domain": "google.com",
		"zones": [],
		"records": [
			{
				"name": "google.com",
				"type": "A",
				"ttl": "283 (4 mins 43 sec)",
				"rData": {
					"value": "216.58.199.174"
				}
			}
		]
	},
	"status": "ok"
}

Delete Cached Zone

Deletes a specific zone from the DNS cache.

URL: http://localhost:5380/api/deleteCachedZone?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name to delete cached records from.

RESPONSE:

{
	"status": "ok"
}

Allowed Zones API Calls

List Allowed Zones

List all allowed zones.

URL: http://localhost:5380/api/listAllowedZones?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain (Optional): The domain name to list records. If not passed, the domain is set to empty string which corresponds to the zone root.
  • direction (Optional): Allows specifying the direction of browsing the zone. Valid values are [up, down] and the default value is down when parameter is missing. This option allows the server to skip empty labels in the domain name when browsing up or down.

RESPONSE:

{
	"response": {
		"domain": "google.com",
		"zones": [],
		"records": [
			{
				"name": "google.com",
				"type": "NS",
				"ttl": "14400 (4 hours)",
				"rData": {
					"value": "server1"
				}
			},
			{
				"name": "google.com",
				"type": "SOA",
				"ttl": "14400 (4 hours)",
				"rData": {
					"primaryNameServer": "server1",
					"responsiblePerson": "hostadmin.server1",
					"serial": 1,
					"refresh": 14400,
					"retry": 3600,
					"expire": 604800,
					"minimum": 900
				}
			}
		]
	},
	"status": "ok"
}

Import Allowed Zones

Imports domain names into the Allowed Zones.

URL: http://localhost:5380/api/importAllowedZones?token=x

WHERE:

  • token: The session token generated by the login call.

REQUEST: This is a POST request call where the content type of the request must be application/x-www-form-urlencoded and the content must be as shown below:

allowedZones=google.com,twitter.com

WHERE:

  • allowedZones: A list of comma separated domain names that are to be imported.

RESPONSE:

{
	"status": "ok"
}

Export Allowed Zones

Allows exporting all the zones from the Allowed Zones as a text file.

URL: http://localhost:5380/api/exportAllowedZones?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE: Response is a downloadable text file with Content-Type: text/plain and Content-Disposition: attachment.

Delete Allowed Zone

Allows deleting a zone from the Allowed Zones.

URL: http://localhost:5380/api/deleteAllowedZone?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name for the zone to be deleted.

RESPONSE:

{
	"status": "ok"
}

Allow Zone

Adds a domain name into the Allowed Zones.

URL: http://localhost:5380/api/allowZone?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name for the zone to be added.

RESPONSE:

{
	"status": "ok"
}

Blocked Zones API Calls

List Blocked Zones

List all blocked zones.

URL: http://localhost:5380/api/listBlockedZones?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain (Optional): The domain name to list records. If not passed, the domain is set to empty string which corresponds to the zone root.
  • direction (Optional): Allows specifying the direction of browsing the zone. Valid values are [up, down] and the default value is down when parameter is missing. This option allows the server to skip empty labels in the domain name when browsing up or down.

RESPONSE:

{
	"response": {
		"domain": "google.com",
		"zones": [],
		"records": [
			{
				"name": "google.com",
				"type": "NS",
				"ttl": "14400 (4 hours)",
				"rData": {
					"value": "server1"
				}
			},
			{
				"name": "google.com",
				"type": "SOA",
				"ttl": "14400 (4 hours)",
				"rData": {
					"primaryNameServer": "server1",
					"responsiblePerson": "hostadmin.server1",
					"serial": 1,
					"refresh": 14400,
					"retry": 3600,
					"expire": 604800,
					"minimum": 900
				}
			}
		]
	},
	"status": "ok"
}

Import Blocked Zones

Imports domain names into Blocked Zones.

URL: http://localhost:5380/api/importBlockedZones?token=x

WHERE:

  • token: The session token generated by the login call.

REQUEST: This is a POST request call where the content type of the request must be application/x-www-form-urlencoded and the content must be as shown below:

blockedZones=google.com,twitter.com

WHERE:

  • blockedZones: A list of comma separated domain names that are to be imported.

RESPONSE:

{
	"status": "ok"
}

Export Blocked Zones

Allows exporting all the zones from the Blocked Zones as a text file.

URL: http://localhost:5380/api/exportBlockedZones?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE: Response is a downloadable text file with Content-Type: text/plain and Content-Disposition: attachment.

Delete Blocked Zone

Allows deleting a zone from the Blocked Zones.

URL: http://localhost:5380/api/deleteBlockedZone?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name for the zone to be deleted.

RESPONSE:

{
	"status": "ok"
}

Block Zone

Adds a domain name into the Blocked Zones.

URL: http://localhost:5380/api/blockZone?token=x&domain=google.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name for the zone to be added.

RESPONSE:

{
	"status": "ok"
}

Authoritative Zone API Calls

List Zones

List all authoritative zones hosted on this DNS server.

URL: http://localhost:5380/api/listZones?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"zones": [
			{
				"name": "0.in-addr.arpa",
				"type": "Primary",
				"internal": true,
				"disabled": false
			},
			{
				"name": "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa",
				"type": "Primary",
				"internal": true,
				"disabled": false
			},
			{
				"name": "127.in-addr.arpa",
				"type": "Primary",
				"internal": true,
				"disabled": false
			},
			{
				"name": "255.in-addr.arpa",
				"type": "Primary",
				"internal": true,
				"disabled": false
			},
			{
				"name": "localhost",
				"type": "Primary",
				"internal": true,
				"disabled": false
			},
			{
				"name": "example.com",
				"type": "Primary",
				"disabled": false
			}
		]
	},
	"status": "ok"
}

Create Zone

Creates a new authoritative zone.

URL: http://localhost:5380/api/createZone?token=x&domain=example.com&type=Primary

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name for creating new zone. The value can be valid domain name, an IP address, or an network address in CIDR format. When value is IP address or network address, a reverse zone is created.
  • type: The type of zone to be created. Valid values are [primary, secondary, stub, forwarder].
  • primaryNameServerAddresses (optional): List of comma separated IP addresses of the primary name server. This optional parameter is used only with Secondary and Stub zones. If this parameter is not used, the DNS server will try to recursively resolve the primary name server addresses automatically.
  • protocol (optional): The DNS transport protocol to be used by the conditional forwarder zone. This optional parameter is used with Conditional Forwarder zones. Valid values are [Udp, Tcp, Tls, Https]. Default UDP protocol is used when this parameter is missing.
  • forwarder (optional): The address of the DNS server to be used as a forwarder. This optional parameter is requred to be used with Conditional Forwarder zones. A special value this-server can be used as a forwarder which when used will forward all the requests internally to this DNS server such that you can override the zone with records and rest of the zone gets resolved via This Server.

RESPONSE:

{
	"response": {
		"domain": "example.com"
	},
	"status": "ok"
}

WHERE:

  • domain: Will contain the zone that was created. This is specifically useful to know the reverse zone that was created.

Delete Zone

Deletes an authoritative zone.

URL: http://localhost:5380/api/deleteZone?token=x&domain=example.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to be deleted.

RESPONSE:

{
	"status": "ok"
}

Enable Zone

Enables an authoritative zone.

URL: http://localhost:5380/api/enableZone?token=x&domain=example.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to be enabled.

RESPONSE:

{
	"status": "ok"
}

Disable Zone

Disables an authoritative zone. This will prevent the DNS server from responding for queries to this zone.

URL: http://localhost:5380/api/disableZone?token=x&domain=example.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to be disabled.

RESPONSE:

{
	"status": "ok"
}

Add Record

Adds an resource record for an authoritative zone.

URL: http://localhost:5380/api/addRecord?token=x&domain=example.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to add record.
  • type: The DNS resource record type. Supported record types are [A, AAAA, MX, TXT, NS, PTR, CNAME, SRV, CAA] and proprietory types [ANAME, FWD, APP].
  • value: The value for the resource record. This parameter is shared among different types of resource records and thus will mean different values as per the type of record. Example, for type A and AAAA record, the value will be an IP address while for type MX, the value will be the exchange domain name and for type TXT the value will be the text data. The APP record uses this value as the app name.
  • ttl: The DNS resource record TTL value. This is the value in seconds that the DNS resolvers can cache the record for.
  • overwrite (optional): This option when set to true will overwrite existing resource record set for the selected type with the new record. Default value of false will add the new record into existing resource record set.
  • ptr (optional): Add a reverse PTR record for the IP address in the A or AAAA record. This option is used only for A and AAAA records.
  • createPtrZone (optional): Create a reverse zone for PTR record. This option is used for A and AAAA records.
  • preference (optional): This is the preference value for MX record type. This option is required for adding MX record.
  • glue (optional): This is the glue address for the name server in the NS record. This optional parameter is used for adding NS record.
  • priority (optional): This parameter is required for adding the SRV record.
  • weight (optional): This parameter is required for adding the SRV record.
  • port (optional): This parameter is required for adding the SRV record.
  • flags (optional): This parameter is required for adding the CAA record.
  • tag (optional): This parameter is required for adding the CAA record.
  • protocol (optional): This parameter is required for adding the FWD record. Valid values are [Udp, Tcp, Tls, Https].
  • classPath (optional): This parameter is required for adding the APP record.
  • recordData (optional): This parameter is used for adding the APP record as per the DNS app requirements.

RESPONSE:

{
	"status": "ok"
}

Get Records

Gets all records for a given authoritative zone.

URL: http://localhost:5380/api/getRecords?token=x&domain=example.com

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to get records.

RESPONSE:

{
	"response": {
		"zone": {
			"name": "example.com",
			"type": "Primary",
			"internal": false,
			"disabled": true
		},
		"records": [
			{
				"disabled": false,
				"name": "example.com",
				"type": "A",
				"ttl": 3600,
				"rData": {
					"value": "127.0.0.1"
				}
			},
			{
				"disabled": false,
				"name": "example.com",
				"type": "NS",
				"ttl": 14400,
				"rData": {
					"value": "server1"
				}
			},
			{
				"disabled": false,
				"name": "example.com",
				"type": "SOA",
				"ttl": 14400,
				"rData": {
					"primaryNameServer": "server1",
					"responsiblePerson": "hostadmin.server1",
					"serial": 7,
					"refresh": 14400,
					"retry": 3600,
					"expire": 604800,
					"minimum": 900
				}
			},
			{
				"disabled": false,
				"name": "example.com",
				"type": "MX",
				"ttl": 3600,
				"rData": {
					"preference": 1,
					"value": "mail.example.com"
				}
			},
			{
				"disabled": false,
				"name": "example.com",
				"type": "TXT",
				"ttl": 3600,
				"rData": {
					"value": "v=spf1 include:mail.example.com -all"
				}
			},
			{
				"disabled": false,
				"name": "example.com",
				"type": "AAAA",
				"ttl": 3600,
				"rData": {
					"value": "::1"
				}
			},
			{
				"disabled": false,
				"name": "mail.example.com",
				"type": "A",
				"ttl": 3600,
				"rData": {
					"value": "127.0.0.1"
				}
			},
			{
				"disabled": false,
				"name": "www.example.com",
				"type": "CNAME",
				"ttl": 3600,
				"rData": {
					"value": "example.com"
				}
			}
		]
	},
	"status": "ok"
}

Delete Record

Deletes a record from an authoritative zone.

URL: http://localhost:5380/api/deleteRecord?token=x&domain=example.com&type=A&value=127.0.0.1

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to delete the record.
  • type: The type of the resource record to delete.
  • value: The value in the record to delete. This is the same value that was read in the Get Record call.
  • port (optional): This is the port parameter in the SRV record. This parameter is required when deleting the SRV record.
  • flags (optional): This is the flags parameter in the CAA record. This parameter is required when deleting the CAA record.
  • tag (optional): This is the tag parameter in the CAA record. This parameter is required when deleting the CAA record.
  • protocol (optional): This is the protocol parameter in the FWD record. Valid values are [Udp, Tcp, Tls, Https]. This parameter is optional and default value Udp will be used when deleting the FWD record.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Update Record

Updates an existing record in an authoritative zone.

URL: http://localhost:5380/api/updateRecord?token=x&domain=mail.example.com&type=A&value=127.0.0.1&newValue=127.0.0.2&ptr=false

WHERE:

  • token: The session token generated by the login call.
  • domain: The domain name of the zone to update the record.
  • type: The type of the resource record to update.
  • newDomain (optional): The new domain name to be set for the record. To be used to rename sub domain name of the record.
  • ttl (optional): The TTL value of the resource record. Default value of 3600 is used when parameter is missing.
  • value: The value in the record to be updated. This is the same value that was read in the Get Record call.
  • newValue (optional): The new value to be updated into the record. When this parameter is missing, the value in the value parameter is used.
  • disable (optional): Specifies if the record should be disabled. The default value is false when this parameter is missing.
  • ptr (optional): Specifies if the PTR record associated with the A or AAAA record must also be updated. This option is used only for A and AAAA records.
  • createPtrZone (optional): Create a reverse zone for PTR record. This option is used only for A and AAAA records.
  • preference (optional): The preference value in an MX record. This parameter when missing will default to 1 value. This parameter is used only when updating MX record.
  • glue (optional): The comma separated list of IP addresses set as glue for the NS record. This parameter is used only when updating NS record.
  • primaryNameServer (optional): This is the primary name server parameter in the SOA record. This parameter is required when updating the SOA record.
  • responsiblePerson (optional): This is the responsible person parameter in the SOA record. This parameter is required when updating the SOA record.
  • serial (optional): This is the serial parameter in the SOA record. This parameter is required when updating the SOA record.
  • refresh (optional): This is the refresh parameter in the SOA record. This parameter is required when updating the SOA record.
  • retry (optional): This is the retry parameter in the SOA record. This parameter is required when updating the SOA record.
  • expire (optional): This is the expire parameter in the SOA record. This parameter is required when updating the SOA record.
  • minimum (optional): This is the minimum parameter in the SOA record. This parameter is required when updating the SOA record.
  • primaryAddresses (optional): This is a comma separated list of IP addresses of the primary name server. This parameter is to be used with secondary and stub zones where the primary name server address is not directly resolveable.
  • port (optional): This is the port parameter in the SRV record. This parameter is required when updating the SRV record.
  • priority (optional): This is the priority parameter in the SRV record. This parameter is required when updating the SRV record.
  • weight (optional): This is the weight parameter in the SRV record. This parameter is required when updating the SRV record.
  • newPort (optional): This is the new value of the port parameter in the SRV record. This parameter is used to update the port parameter in the SRV record.
  • flags (optional): This is the flags parameter in the CAA record. This parameter is required when updating the CAA record.
  • tag (optional): This is the tag parameter in the CAA record. This parameter is required when updating the CAA record.
  • newFlags (optional): This is the new value of the flags parameter in the CAA record. This parameter is used to update the flags parameter in the CAA record.
  • newTag (optional): This is the new value of the tag parameter in the CAA record. This parameter is used to update the tag parameter in the CAA record.
  • protocol (optional): This is the protocol parameter in the FWD record. Valid values are [Udp, Tcp, Tls, Https]. This parameter is optional and default value Udp will be used when updating the FWD record.
  • classPath (optional): This parameter is required for updating the APP record.
  • recordData (optional): This parameter is used for updating the APP record as per the DNS app requirements.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

DNS Apps API Calls

List Apps

Lists all installed apps on the DNS server. If the DNS server has internet access and is able to retrieve data from DNS App Store, the API call will also return if a store App has updates available.

URL: http://localhost:5380/api/apps/list?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"apps": [
			{
				"name": "Split Horizon",
				"version": "1.1",
				"details": [
					{
						"classPath": "SplitHorizon.SimpleAddress",
						"description": "Returns A or AAAA records with different set of IP addresses for clients querying over public and private networks.",
						"recordDataTemplate": "{\r\n  \"public\": [\r\n    \"1.1.1.1\", \r\n    \"2.2.2.2\"\r\n  ],\r\n  \"private\": [\r\n    \"192.168.1.1\", \r\n    \"::1\"\r\n  ]\r\n}"
					},
					{
						"classPath": "SplitHorizon.SimpleCNAME",
						"description": "Returns different CNAME record for clients querying over public and private networks. Note that the app will return ANAME record for an APP record at zone apex.",
						"recordDataTemplate": "{\r\n  \"public\": \"api.example.com\",\r\n  \"private\": \"api.example.corp\"\r\n}"
					}
				]
			},
			{
				"name": "What Is My Dns",
				"version": "1.1",
				"updateVersion": "1.1",
				"updateUrl": "https://download.technitium.com/dns/apps/WhatIsMyDnsApp.zip",
				"updateAvailable": false,
				"details": [
					{
						"classPath": "WhatIsMyDns.App",
						"description": "Returns the IP address of the user's DNS Server for A, AAAA, and TXT queries.",
						"recordDataTemplate": null
					}
				]
			}
		]
	},
	"status": "ok"
}

List Store Apps

Lists all available apps on the DNS App Store.

URL: http://localhost:5380/api/apps/listStoreApps?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"storeApps": [
			{
				"name": "Geo Continent",
				"version": "1.1",
				"description": "Returns A or AAAA records, or CNAME record based on the continent the client queries from using MaxMind GeoIP2 Country database. This app requires MaxMind GeoIP2 database and includes the GeoLite2 version for trial. To update the MaxMind GeoIP2 database for your app, download the GeoIP2-Country.mmdb file from MaxMind and zip it. Use the zip file with the manual Update option.",
				"url": "https://download.technitium.com/dns/apps/GeoContinentApp.zip",
				"size": "2.01 MB",
				"installed": false
			},
			{
				"name": "Geo Country",
				"version": "1.1",
				"description": "Returns A or AAAA records, or CNAME record based on the country the client queries from using MaxMind GeoIP2 Country database. This app requires MaxMind GeoIP2 database and includes the GeoLite2 version for trial. To update the MaxMind GeoIP2 database for your app, download the GeoIP2-Country.mmdb file from MaxMind and zip it. Use the zip file with the manual Update option.",
				"url": "https://download.technitium.com/dns/apps/GeoCountryApp.zip",
				"size": "2.01 MB",
				"installed": false
			},
			{
				"name": "Geo Distance",
				"version": "1.1",
				"description": "Returns A or AAAA records, or CNAME record of the server located geographically closest to the client using MaxMind GeoIP2 City database. This app requires MaxMind GeoIP2 database and includes the GeoLite2 version for trial. To update the MaxMind GeoIP2 database for your app, download the GeoIP2-City.mmdb file from MaxMind and zip it. Use the zip file with the manual Update option.",
				"url": "https://download.technitium.com/dns/apps/GeoDistanceApp.zip",
				"size": "28.6 MB",
				"installed": false
			},
			{
				"name": "Split Horizon",
				"version": "1.1",
				"description": "Returns different set of A or AAAA records, or CNAME record for clients querying over public and private networks.",
				"url": "https://download.technitium.com/dns/apps/SplitHorizonApp.zip",
				"size": "11.1 KB",
				"installed": true,
				"installedVersion": "1.1",
				"updateAvailable": false
			},
			{
				"name": "What Is My Dns",
				"version": "1.1",
				"description": "Returns the IP address of the user's DNS Server for A, AAAA, and TXT queries.",
				"url": "https://download.technitium.com/dns/apps/WhatIsMyDnsApp.zip",
				"size": "8.79 KB",
				"installed": true,
				"installedVersion": "1.1",
				"updateAvailable": false
			}
		]
	},
	"status": "ok"
}

Download And Install App

Download an app zip file from given URL and installs it on the DNS Server.

URL: http://localhost:5380/api/apps/downloadAndInstall?token=x&name=app-name&url=https://example.com/app.zip

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to install.
  • url: The URL of the app zip file. URL must start with https://.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Download And Update App

Download an app zip file from given URL and updates an existing app installed on the DNS Server.

URL: http://localhost:5380/api/apps/downloadAndUpdate?token=x&name=app-name&url=https://example.com/app.zip

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to install.
  • url: The URL of the app zip file. URL must start with https://.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Install App

Installs a DNS application on the DNS server.

URL: http://localhost:5380/api/apps/install?token=x&name=app-name

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to install.

REQUEST: This is a POST request call where the request must be multi-part form data with the DNS application zip file data in binary format.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Update App

Allows to manually update an installed app using a provided app zip file.

URL: http://localhost:5380/api/apps/update?token=x&name=app-name

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to update.

REQUEST: This is a POST request call where the request must be multi-part form data with the DNS application zip file data in binary format.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Uninstall App

Uninstall an app from the DNS server. This does not remove any APP records that were using this DNS application.

URL: http://localhost:5380/api/apps/uninstall?token=x&name=app-name

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to uninstall.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Get App Config

Retrieve the DNS application config from the dnsApp.config file in the application folder.

URL: http://localhost:5380/api/apps/getConfig?token=x&name=app-name

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to retrieve the config.

RESPONSE:

{
	"response": {
		"config": "config data or `null`"
	},
	"status": "ok"
}

Set App Config

Saves the provided DNS application config into the dnsApp.config file in the application folder.

URL: http://localhost:5380/api/apps/setConfig?token=x&name=app-name

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the app to retrieve the config.

REQUEST: This is a POST request call where the content type of the request must be application/x-www-form-urlencoded and the content must be as shown below:

config=query-string-encoded-config-data

RESPONSE:

{
	"response": {},
	"status": "ok"
}

DNS Client API Calls

Resolve Query

URL: http://localhost:5380/api/resolveQuery?token=x&server=this-server&domain=example.com&type=A&protocol=UDP

WHERE:

  • token: The session token generated by the login call.
  • server: The name server to query using the DNS client.
  • domain: The domain name to query.
  • type: The type of the query.
  • protocol (optional): The DNS transport protocol to be used to query. Valid values are [Udp, Tcp, Tls, Https]. The default value of Udp is used when the parameter is missing.
  • import (optional): This parameter when set to true indicates that the response of the DNS query should be imported in the an authoritative zone on this DNS server. Default value is false when this parameter is missing. If a zone does not exists, a primary zone for the domain name is created and the records from the response are set into the zone. Import can be done only for primary and forwarder type of zones. When type is set to AXFR, then the import feature will work as if a zone transfer was requested and the complete zone will be updated as per the zone transfer response. Note that any existing record type for the given type will be overwritten when syncing the records. It is recommended to use recursive-resolver or the actual name server address for the server parameter when importing records.

RESPONSE:

{
	"response": {
		"result": {
			"Metadata": {
				"NameServer": "server1:53 (127.0.0.1:53)",
				"Protocol": "Udp",
				"DatagramSize": "45 bytes",
				"RoundTripTime": "1.42 ms"
			},
			"Identifier": 60127,
			"IsResponse": true,
			"OPCODE": "StandardQuery",
			"AuthoritativeAnswer": true,
			"Truncation": false,
			"RecursionDesired": true,
			"RecursionAvailable": true,
			"Z": 0,
			"AuthenticData": false,
			"CheckingDisabled": false,
			"RCODE": "NoError",
			"QDCOUNT": 1,
			"ANCOUNT": 1,
			"NSCOUNT": 0,
			"ARCOUNT": 0,
			"Question": [
				{
					"Name": "example.com",
					"Type": "A",
					"Class": "IN"
				}
			],
			"Answer": [
				{
					"Name": "example.com",
					"Type": "A",
					"Class": "IN",
					"TTL": "86400 (1 day)",
					"RDLENGTH": "4 bytes",
					"RDATA": {
						"IPAddress": "127.0.0.1"
					}
				}
			],
			"Authority": [],
			"Additional": []
		}
	},
	"status": "ok"
}

Log API Calls

List Logs

Lists all logs files available on the DNS server.

URL: http://localhost:5380/api/listLogs?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"logFiles": [
			{
				"fileName": "2020-09-19",
				"size": "8.14 KB"
			},
			{
				"fileName": "2020-09-15",
				"size": "5.6 KB"
			},
			{
				"fileName": "2020-09-12",
				"size": "18.4 KB"
			},
			{
				"fileName": "2020-09-11",
				"size": "1.78 KB"
			},
			{
				"fileName": "2020-09-10",
				"size": "2.03 KB"
			}
		]
	},
	"status": "ok"
}

Download Log

Downloads the log file.

URL: http://localhost:5380/log/{fileName}?token=x&limit=2

WHERE:

  • {fileName}: The fileName returned by the List Logs API call.
  • token: The session token generated by the login call.
  • limit (optional): The limit of number of mega bytes to download the log file. Default value is 0 when parameter is missing which indicates there is no limit.

RESPONSE: Response is a downloadable file with Content-Type: text/plain and Content-Disposition: attachment;filename=name

Delete Log

Permanantly deletes a log file from the disk.

URL: http://localhost:5380/api/deleteLog?token=x&log=2020-09-19

WHERE:

  • token: The session token generated by the login call.
  • log: The fileName returned by the List Logs API call.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Delete All Logs

Permanantly delete all log files from the disk.

URL: http://localhost:5380/api/deleteAllLogs?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Delete All Stats

Permanantly delete all hourly and daily stats files from the disk and clears all stats stored in memory. This call will clear all stats from the Dashboard.

URL: http://localhost:5380/api/deleteAllStats?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

DHCP API Calls

List DHCP Scopes

Lists all the DHCP scopes available on the server.

URL: http://localhost:5380/api/listDhcpScopes?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"scopes": [
			{
				"name": "Default",
				"enabled": false,
				"startingAddress": "192.168.1.1",
				"endingAddress": "192.168.1.254",
				"subnetMask": "255.255.255.0",
				"networkAddress": "192.168.1.0",
				"broadcastAddress": "192.168.1.255"
			}
		]
	},
	"status": "ok"
}

List DHCP Leases

Lists all the DHCP leases.

URL: http://localhost:5380/api/listDhcpLeases?token=x

WHERE:

  • token: The session token generated by the login call.

RESPONSE:

{
	"response": {
		"leases": [
			{
				"scope": "Default",
				"type": "Reserved",
				"hardwareAddress": "00-00-00-00-00-00",
				"address": "192.168.1.5",
				"hostName": "server1.local",
				"leaseObtained": "08/25/2020 17:52:51",
				"leaseExpires": "09/26/2020 14:27:12"
			},
			{
				"scope": "Default",
				"type": "Dynamic",
				"hardwareAddress": "00-00-00-00-00-00",
				"address": "192.168.1.13",
				"hostName": null,
				"leaseObtained": "06/15/2020 16:41:46",
				"leaseExpires": "09/25/2020 12:39:54"
			},
			{
				"scope": "Default",
				"type": "Dynamic",
				"hardwareAddress": "00-00-00-00-00-00",
				"address": "192.168.1.15",
				"hostName": "desktop-ea2miaf.local",
				"leaseObtained": "06/18/2020 12:19:03",
				"leaseExpires": "09/25/2020 12:17:11"
			},
		]
	},
	"status": "ok"
}

Get DHCP Scope

Gets the complete details of the scope configuration.

URL: http://localhost:5380/api/getDhcpScope?token=x&name=Default

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.

RESPONSE:

{
	"response": {
		"name": "Default",
		"startingAddress": "192.168.1.1",
		"endingAddress": "192.168.1.254",
		"subnetMask": "255.255.255.0",
		"leaseTimeDays": 7,
		"leaseTimeHours": 0,
		"leaseTimeMinutes": 0,
		"offerDelayTime": 0,
		"domainName": "local",
		"dnsTtl": 900,
		"serverAddress": "192.168.1.1",
		"serverHostName": "tftp-server-1",
		"bootFileName": "boot.bin",
		"routerAddress": "192.168.1.1",
		"useThisDnsServer": false,
		"dnsServers": [
			"192.168.1.5"
		],
		"winsServers": [
			"192.168.1.5"
		],
		"ntpServers": [
			"192.168.1.5"
		],
		"staticRoutes": [
			{
				"destination": "172.16.0.0",
				"subnetMask": "255.255.255.0",
				"router": "192.168.1.2"
			}
		],
		"vendorInfo": [
			{
				"identifier": "substring(vendor-class-identifier,0,9)==\"PXEClient\"",
				"information": "06:01:03:0A:04:00:50:58:45:09:14:00:00:11:52:61:73:70:62:65:72:72:79:20:50:69:20:42:6F:6F:74:FF"
			}
		],
		"exclusions": [
			{
				"startingAddress": "192.168.1.1",
				"endingAddress": "192.168.1.10"
			}
		],
		"reservedLeases": [
			{
				"hostName": null,
				"hardwareAddress": "00-00-00-00-00-00",
				"address": "192.168.1.10",
				"comments": "comments"
			}
		],
		"allowOnlyReservedLeases": false
	},
	"status": "ok"
}

Set DHCP Scope

Sets the DHCP scope configuration.

URL: http://localhost:5380/api/setDhcpScope?token=x&name=Default&startingAddress=192.168.1.1&endingAddress=192.168.1.254&subnetMask=255.255.255.0&leaseTimeDays=7&leaseTimeHours=0&leaseTimeMinutes=0&offerDelayTime=0&domainName=local&dnsTtl=900&serverAddress=&serverHostName=&bootFileName=&routerAddress=192.168.1.1&useThisDnsServer=false&dnsServers=192.168.1.5&winsServers=192.168.1.5&ntpServers=192.168.1.5&staticRoutes=172.16.0.0;255.255.255.0;192.168.1.2&exclusions=192.168.1.1;192.168.1.10&reservedLeases=00-00-00-00-00-00;192.168.1.10;comments&allowOnlyReservedLeases=false

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.
  • newName (optional): The new name of the DHCP scope to rename an existing scope.
  • startingAddress: The starting IP address of the DHCP scope.
  • endingAddress: The ending IP address of the DHCP scope.
  • subnetMask: The subnet mask of the network.
  • leaseTimeDays (optional): The lease time in number of days.
  • leaseTimeHours (optional): The lease time in number of hours.
  • leaseTimeMinutes (optional): The lease time in number of minutes.
  • offerDelayTime (optional): The time duration in milli seconds that the DHCP server delays sending an DHCPOFFER message.
  • domainName (optional): The domain name to be used by this network. The DHCP server automatically adds forward and reverse DNS entries for each IP address allocations when domain name is configured.
  • dnsTtl (optional): The TTL value used for forward and reverse DNS records.
  • serverAddress (optional): The bootstrap TFTP server IP address to be used by the clients. If not specified, the DHCP server's IP address is used.
  • serverHostName (optional): The optional bootstrap TFTP server host name to be used by the clients to identify the TFTP server.
  • bootFileName (optional): The boot file name stored on the bootstrap TFTP server to be used by the clients.
  • routerAddress (optional): The default gateway or router IP address to be used by the clients.
  • useThisDnsServer (optional): Tells the DHCP server to use this DNS server's IP address to configure the DNS Servers DHCP option for clients.
  • dnsServers (optional): A comma separated list of DNS server IP addresses to be used by the clients. This parameter is ignored when useThisDnsServer is set to true.
  • winsServers (optional): A comma separated list of NBNS/WINS server IP addresses to be used by the clients.
  • ntpServers (optional): A comma separated list of Network Time Protocol (NTP) server IP addresses to be used by the clients.
  • staticRoutes (optional): A | separated list of static routes in format {destination network address}|{subnet mask}|{router/gateway address} to be used by the clients for accessing specified destination networks.
  • vendorInfo (optional): A | separated list of vendor information in format {vendor class identifier}|{vendor specific information} where {vendor specific information} is a colon separated hex string.
  • exclusions (optional): A | separated list of IP address range in format {starting address}|{ending address} that must be excluded or not assigned dynamically to any client by the DHCP server.
  • reservedLeases (optional): A | separated list of reserved IP addresses in format {host name}|{MAC address}|{reserved IP address}|{comments} to be assigned to specific clients based on their MAC address.
  • allowOnlyReservedLeases (optional): Set this parameter to true to stop dynamic IP address allocation and allocate only reserved IP addresses.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Enable DHCP Scope

Enables the DHCP scope allowing the server to allocate leases.

URL: http://localhost:5380/api/enableDhcpScope?token=x&name=Default

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Disable DHCP Scope

Disables the DHCP scope and stops any further lease allocations.

URL: http://localhost:5380/api/disableDhcpScope?token=x&name=Default

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Delete DHCP Scope

Permanently deletes the DHCP scope from the disk.

URL: http://localhost:5380/api/deleteDhcpScope?token=x&name=Default

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Convert To Reserved Lease

Converts a dynamic lease to reserved lease.

URL: http://localhost:5380/api/convertToReservedLease?token=x&name=Default&hardwareAddress=00:00:00:00:00:00

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.
  • hardwareAddress: The MAC address of the device bearing the dynamic lease.

RESPONSE:

{
	"response": {},
	"status": "ok"
}

Convert To Dynamic Lease

Converts a reserved lease to dynamic lease.

URL: http://localhost:5380/api/convertToDynamicLease?token=x&name=Default&hardwareAddress=00:00:00:00:00:00

WHERE:

  • token: The session token generated by the login call.
  • name: The name of the DHCP scope.
  • hardwareAddress: The MAC address of the device bearing the reserved lease.

RESPONSE:

{
	"response": {},
	"status": "ok"
}