fergalmoran/DnsServer
1
0
Fork 0
mirror of https://github.com/fergalmoran/DnsServer.git synced 2025-12-22 09:29:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated API docs.

Browse Source
This commit is contained in:
Shreyas Zare
2021-01-02 17:32:00 +05:30
parent d84ca5ebc8
commit 2681ce850f
1 changed files with 216 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
APIDOCS.md
View File

@@ -146,23 +146,38 @@ RESPONSE:
```
{
"response": {
"version": "5.2",
"serverDomain": "server1",
"webServicePort": 5380,
"version": "5.6",
"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,
"tlsCertificatePath": null,
"tlsCertificatePassword": "************",
"dnsTlsCertificatePath": null,
"dnsTlsCertificatePassword": "************",
"preferIPv6": false,
"enableLogging": true,
"logQueries": true,
"useLocalTime": false,
"logFolder": "logs",
"maxLogFileDays": 365,
"allowRecursion": true,
"allowRecursionOnlyForPrivateNetworks": true,
"randomizeName": true,
"serveStale": true,
"serveStaleTtl": 259200,
"cachePrefetchEligibility": 2,
"cachePrefetchTrigger": 9,
"cachePrefetchSampleIntervalInMinutes": 5,
@@ -182,7 +197,8 @@ RESPONSE:
]
},
"forwarders": [
"192.168.10.2"
"https://cloudflare-dns.com/dns-query (1.1.1.1)",
"https://cloudflare-dns.com/dns-query (1.0.0.1)"
],
"forwarderProtocol": "Udp",
"blockListUrls": [
@@ -190,7 +206,9 @@ RESPONSE:
"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"
}
@@ -201,23 +219,34 @@ RESPONSE:
This call allows to change the DNS server settings.
URL:
`http://localhost:5380/api/setDnsSettings?token=x&serverDomain=server1&webServicePort=5380&dnsServerLocalEndPoints=0.0.0.0:53,[::]:53&enableDnsOverHttp=false&enableDnsOverTls=false&enableDnsOverHttps=false&tlsCertificatePath=&tlsCertificatePassword=&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&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`
`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&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.
- `serverDomain` (optional): The primary domain name used by this DNS Server to identify itself.
- `webServicePort` (optional): Specify the TCP port number for the web console and this API web service. The DNS server main service needs to be restarted to apply this setting.
- `dnsServerLocalEndPoints` (optional): Local end points are the network interface IP addresses and ports you want the DNS Server to listen for requests. The DNS server main service needs to be restarted to apply this setting.
- `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.
- `tlsCertificatePath` (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.
- `tlsCertificatePassword` (optional): Enter the certificate (.pfx) password, if any.
- `preferIPv6` (optional): DNS Server will use IPv6 for querying whenever possible with this option enabled.
- `logQueries` (optional): Enable this option to log every query received by this DNS Server and the corresponding response answers into the log file.
- `allowRecursion` (optional): Enable recursion to allow this DNS Server to resolve any domain name.
- `allowRecursionOnlyForPrivateNetworks` (optional): Enable this option if you want to support recursion only on private networks. Any recursive request from public network will be refused.
- `randomizeName` (optional): Enables QNAME randomization [draft-vixie-dnsext-dns0x20-00](https://tools.ietf.org/html/draft-vixie-dnsext-dns0x20-00) when using UDP as the transport protocol.
- `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. Default value is `365`.
- `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](https://tools.ietf.org/html/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.
- `cachePrefetchSampleIntervalInMinutes` (optional): The interval to sample eligible domain names from last hour stats for auto prefetch.
@@ -231,6 +260,71 @@ WHERE:
- `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`].
- `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`.
- `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`
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`.
- `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`.
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.
@@ -244,7 +338,7 @@ URL:
WHERE:
- `token`: The session token generated by the `login` call.
- `type`: The stats type for which valid values are: [`lastHour`, `lastDay`, `lastWeek`, `lastMonth`, `lastYear`]
- `type`: The duration type for which valid values are: [`lastHour`, `lastDay`, `lastWeek`, `lastMonth`, `lastYear`]
RESPONSE:
```
@@ -1204,6 +1298,73 @@ RESPONSE:
}
```
### 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
@@ -2018,6 +2179,42 @@ RESPONSE:
}
```
### 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