diff --git a/docs/api/dns/blocking.md b/docs/api/dns/blocking.md index 60b41df..222df37 100644 --- a/docs/api/dns/blocking.md +++ b/docs/api/dns/blocking.md @@ -1,24 +1,16 @@ # DNS - Status -## GET: Obtain current blocking status +## Obtain current blocking status -Resource: `GET /admin/api/dns/blocking` - -Requires authorization: No - -### Parameters - -None - -### Examples +- `GET /api/dns/blocking` -!!! example "Request" +???+ example "Request" === "cURL" ``` bash - curl -X GET http://pi.hole:8080/admin/api/dns/blocking + curl -X GET http://pi.hole:8080/api/dns/blocking ``` === "Python 3" @@ -26,14 +18,18 @@ None ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/blocking' + URL = 'http://pi.hole:8080/api/dns/blocking' response = requests.get(URL) print(response.json()) ``` -!!! success "Response" + **Parameters** + + None + +??? success "Response" Response code: `HTTP/1.1 200 OK` @@ -55,33 +51,37 @@ None } } ``` + + **Fields** + + ??? info "Status (`"blocking": boolean`)" + Current blocking status. + + ??? info "Timer details (`"timer": [object|null]`)" + Additional information about a possibly temporary blocking mode. If no timer is running (the current blocking mode is permanent), `null` is returned instead of an object. + + ??? info "Remaining time (`"delay": number`)" + Seconds until the blocking status indicated by `"blocking_target"` is applied. + + ??? info "Remaining time (`"blocking_target": boolean`)" + Status applied after the timer elapsed. + -## `POST`: Set/change blocking status +## Change blocking status -Resource: `POST /admin/api/dns/blocking` - -Requires authorization: Yes - -### Parameters - -Name | Required | Type | Description | Example ----- | -------- | ---- | ----------- | ------- -`blocking` | Yes | Boolean | Requested status | `true` -`delay` | Optional | Number | Requested delay until opposite status is active, running timer can be disabled by setting delay to `-1` | `100` (seconds) - -### Example +- `POST /api/dns/blocking` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" ``` bash - curl -X POST http://pi.hole:8080/admin/api/dns/blocking \ + curl -X POST http://pi.hole:8080/api/dns/blocking \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ - -d '{"blocking":false, "delay":30}' + -d '{"blocking": false, "delay": 30}' ``` === "Python 3" @@ -89,17 +89,29 @@ Name | Required | Type | Description | Example ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/blocking' + URL = 'http://pi.hole:8080/api/dns/blocking' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} - data = {"blocking":False, "delay":30} + data = {"blocking": False, "delay": 30} response = requests.post(URL, json=data, headers=HEADERS) print(response.json()) ``` -!!! success "Response" + **Required parameters** + + ??? info "Status (`"blocking": boolean`)" + Blocking status to be applied. When requesting the same status as is already set, a possibly running timer is disabled. + + **Optional parameters** + + ??? info "Timer delay (`"delay": number`)" + Delay until the previous blocking status is re-applied. This can be used to disable Pi-hole's blocking temporarily. Subsequent requests overwrite previous timers. When omitting this value, a possibly running timer is disabled. + + This setting has no effect when requesting the same blocking state that is already active. + +??? success "Response" Response code: `HTTP/1.1 200 OK` @@ -113,7 +125,9 @@ Name | Required | Type | Description | Example } ``` - Remember that `timer` may be `null` if there is no active timer. + **Fields** + + See description of the `GET` request above. Remember that `timer` may be `null` if there is no active timer. {!abbreviations.md!} diff --git a/docs/api/dns/cache.md b/docs/api/dns/cache.md index 58726ff..b84cecc 100644 --- a/docs/api/dns/cache.md +++ b/docs/api/dns/cache.md @@ -1,24 +1,16 @@ # DNS - Cache Info -## GET: Obtain information about Pi-hole's DNS cache +## Obtain information about Pi-hole's DNS cache -Resource: `GET /admin/api/dns/cache` - -Requires authorization: No - -### Parameters - -None - -### Example +- `GET /api/dns/cache` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" ``` bash - curl -X GET http://pi.hole:8080/admin/api/dns/cacheinfo \ + curl -X GET http://pi.hole:8080/api/dns/cacheinfo \ -H "Authorization: Token " ``` @@ -27,7 +19,7 @@ None ``` python import requests - URL = 'http://pi.hole:8080/admin/api/dns/cacheinfo' + URL = 'http://pi.hole:8080/api/dns/cacheinfo' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -36,7 +28,11 @@ None print(response.json()) ``` -!!! success "Response" + **Parameters** + + None + +??? success "Response" Response code: `HTTP/1.1 200 OK` @@ -47,9 +43,33 @@ None "cache_evicted": 0 } ``` - -See [DNS cache details](../../ftldns/dns-cache.md) for further information about the returned quantities. + **Reply type** + + Object + + **Fields** + + ??? info "DNS cache size (`"cache_size": number`)" + Size of the DNS domain cache, defaulting to 10,000 entries. You typically specify this number directly in `/etc/dnsmasq.d/01-pihole.conf`. It is the number of entries that can be actively cached at the same time. There is no benefit in enlarging this number *except* if the DNS cache evictions count is larger than zero. + + This information may also be queried using `dig +short chaos txt cachesize.bind` + + ??? info "DNS cache insertions (`"cache_inserted": number`)" + + Number of total insertions into the cache. This number can be substantially larger than DNS cache size as expiring cache entries naturally make room for new insertions over time. Each lookup with a non-zero TTL will be cached. + + This information may also be queried using `dig +short chaos txt insertions.bind` + + ??? info "DNS cache evictions (`"cache_evicted": number`)" + + The number of cache entries that had to be removed although the corresponding entries were **not** expired. Old cache entries get removed if the cache is full to make space for more recent domains. + + The cache size should be increased when the number of evicted cache entries is larger than zero. + + This information may also be queried using `dig +short chaos txt evictions.bind` + + This endpoint cannot fail. diff --git a/docs/api/domainlists.md b/docs/api/domainlists.md index fe07cdb..575a01e 100644 --- a/docs/api/domainlists.md +++ b/docs/api/domainlists.md @@ -1,29 +1,19 @@ # DNS - Domain Lists -## GET: List all items +## List all items -Resources: - -- `GET /admin/api/whitelist/exact` -- `GET /admin/api/whitelist/regex` -- `GET /admin/api/blacklist/exact` -- `GET /admin/api/blacklist/regex` - -Requires authorization: Yes - -### Parameters - -None - -### Example +- `GET /api/whitelist/exact` +- `GET /api/whitelist/regex` +- `GET /api/blacklist/exact` +- `GET /api/blacklist/regex` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" ``` bash - curl -X GET http://pi.hole:8080/admin/api/whitelist/exact \ + curl -X GET http://pi.hole:8080/api/whitelist/exact \ -H "Authorization: Token " ``` @@ -32,7 +22,7 @@ None ``` python import requests - URL = 'http://pi.hole:8080/admin/api/whitelist/exact' + URL = 'http://pi.hole:8080/api/whitelist/exact' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -41,7 +31,11 @@ None print(response.json()) ``` -!!! success "Success response" + **Parameters** + + None + +??? success "Success response" Response code: `HTTP/1.1 200 OK` @@ -59,12 +53,33 @@ None "enabled": false, "date_added": 1589104951, "date_modified": 1589104951, - "comment": "" + "comment": null } ] ``` -!!! failure "Error response (database not available)" + **Reply type** + + Array of objects (may be empty if no item of the requested flavor exist) + + **Fields** + + ??? info "Domain/regular expression (`"domain": string`)" + Item depending on the list type. + + ??? info "Enabled (`"enabled": boolean`)" + Whether this item is enabled or disabled. + + ??? info "Addition time (`"date_added": number`)" + Unix timestamp of addition of this item to Pi-hole's database. + + ??? info "Modification time (`"date_modified": number`)" + Unix timestamp of modification of this item in Pi-hole's database. + + ??? info "Comment (`"comment": [null|string]`)" + User-provided free-text comment for this item. May be `null` if not specified. + +??? failure "Error response" Response code: `HTTP/1.1 402 - Request failed` @@ -81,30 +96,20 @@ None ``` -## GET: List specific item +## List specific item -Resources: - -- `GET /admin/api/whitelist/exact/` -- `GET /admin/api/whitelist/regex/` -- `GET /admin/api/blacklist/exact/` -- `GET /admin/api/blacklist/regex/` - -Requires authorization: Yes - -### Parameters - -The domain/regex to be listed is specified through the URL (``). - -### Example +- `GET /api/whitelist/exact/` +- `GET /api/whitelist/regex/` +- `GET /api/blacklist/exact/` +- `GET /api/blacklist/regex/` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" ``` bash - curl -X GET http://pi.hole:8080/admin/api/whitelist/exact/whitelisted.com \ + curl -X GET http://pi.hole:8080/api/whitelist/exact/whitelisted.com \ -H "Authorization: Token " ``` @@ -113,7 +118,7 @@ The domain/regex to be listed is specified through the URL (``). ``` python import requests - URL = 'http://pi.hole:8080/admin/api/whitelist/exact/' + URL = 'http://pi.hole:8080/api/whitelist/exact/' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -123,7 +128,11 @@ The domain/regex to be listed is specified through the URL (``). print(response.json()) ``` -!!! success "Success response" + **Parameters** + + Specify the requested item through the URL (``) + +??? success "Success response" Response code: `HTTP/1.1 200 OK` @@ -139,7 +148,11 @@ The domain/regex to be listed is specified through the URL (``). ] ``` -!!! failure "Error response (database not available)" + **Fields** + + See description of the `GET` request above. + +??? failure "Error response" Response code: `HTTP/1.1 402 - Request failed` @@ -156,46 +169,32 @@ The domain/regex to be listed is specified through the URL (``). ``` -## POST/PATCH: Add item - -Resources: +## Add/update item **Create new entry (error on existing identical record)** -- `POST /admin/api/whitelist/exact` -- `POST /admin/api/whitelist/regex` -- `POST /admin/api/blacklist/exact` -- `POST /admin/api/blacklist/regex` +- `POST /api/whitelist/exact` +- `POST /api/whitelist/regex` +- `POST /api/blacklist/exact` +- `POST /api/blacklist/regex` **Create new or update existing entry (no error on existing record)** -- `PATCH /admin/api/whitelist/exact` -- `PATCH /admin/api/whitelist/regex` -- `PATCH /admin/api/blacklist/exact` -- `PATCH /admin/api/blacklist/regex` - -Requires authorization: Yes - -### Parameters - -Name | Required | Type | Description | Default | Example ----- | -------- | ---- | ----------- | ------- | ------- -`domain` | Yes | String | Domain to be added | |`whitelisted.com` -`enabled` | Optional | Boolean | Should this domain be used? | `true` | `true` -`comment` | Optional | String | Comment for this domain | `null` | `Some text` - -### Example +- `PATCH /api/whitelist/exact` +- `PATCH /api/whitelist/regex` +- `PATCH /api/blacklist/exact` +- `PATCH /api/blacklist/regex` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" ``` bash - curl -X POST http://pi.hole:8080/admin/api/whitelist/exact \ + curl -X POST http://pi.hole:8080/api/whitelist/exact \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ - -d '{"domain":"whitelisted.com", "enabled":true, "comment":"Some text"}' + -d '{"domain": "whitelisted.com", "enabled": true, "comment": "Some text"}' ``` === "Python 3" @@ -203,17 +202,30 @@ Name | Required | Type | Description | Default | Example ``` python import requests - URL = 'http://pi.hole:8080/admin/api/whitelist/exact' + URL = 'http://pi.hole:8080/api/whitelist/exact' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} - data = {"domain":"whitelisted.com", "enabled":True, "comment":"Some text"} + data = {"domain": "whitelisted.com", "enabled": True, "comment": "Some text"} response = requests.post(URL, json=data, headers=HEADERS) print(response.json()) ``` -!!! success "Success response" + **Required parameters** + + ??? info "Domain/regular expression (`"domain": string`)" + Domain or (JSON-escaped) regular expression to be added to the database. + + **Optional parameters** + + ??? info "Enabled (`"enabled": boolean`)" + Whether this item should be added as enabled or disabled. + + ??? info "Comment (`"comment": string`)" + User-provided free-text comment for this item. + +??? success "Success response" Response code: `HTTP/1.1 201 Created` @@ -229,7 +241,11 @@ Name | Required | Type | Description | Default | Example ] ``` -!!! failure "Error response (duplicated domain)" + **Fields** + + See description of the `GET` request above. + +??? failure "Error response" Response code: `HTTP/1.1 402 - Request failed` @@ -248,30 +264,21 @@ Name | Required | Type | Description | Default | Example } ``` - When using `PATCH` instead of `POST`, duplicate domains are silently replaced without triggering an error. + !!! hint "Hint: Use `PATCH` instead of `POST`" + When using `PATCH` instead of `POST`, duplicate domains are silently replaced without issuing an error. --- -## DELETE: Remove item +## Remove item -Resources: - -- `DELETE /admin/api/whitelist/exact/` -- `DELETE /admin/api/whitelist/regex/` -- `DELETE /admin/api/blacklist/exact/` -- `DELETE /admin/api/blacklist/regex/` - -Requires authorization: Yes - -### Parameters - -The domain/regex to be removed is specified through the URL (``). - -### Example request +- `DELETE /api/whitelist/exact/` +- `DELETE /api/whitelist/regex/` +- `DELETE /api/blacklist/exact/` +- `DELETE /api/blacklist/regex/` -!!! example "Request" +???+ example "Request (required authorization)" === "cURL" @@ -279,7 +286,7 @@ The domain/regex to be removed is specified through the URL (``). ``` bash domain="whitelisted.com" - curl -X DELETE http://pi.hole:8080/admin/api/whitelist/exact/${domain} \ + curl -X DELETE http://pi.hole:8080/api/whitelist/exact/${domain} \ -H "Authorization: Token " ``` @@ -287,7 +294,7 @@ The domain/regex to be removed is specified through the URL (``). ``` bash regex="$(echo -n "(^|\\.)facebook.com$" | jq -sRr '@uri')" - curl -X DELETE http://pi.hole:8080/admin/api/whitelist/exact/${regex} \ + curl -X DELETE http://pi.hole:8080/api/whitelist/exact/${regex} \ -H "Authorization: Token " ``` @@ -298,7 +305,7 @@ The domain/regex to be removed is specified through the URL (``). ``` python import requests - URL = 'http://pi.hole:8080/admin/api/whitelist/exact/' + URL = 'http://pi.hole:8080/api/whitelist/exact/' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -314,7 +321,7 @@ The domain/regex to be removed is specified through the URL (``). import requests import urllib - URL = 'http://pi.hole:8080/admin/api/whitelist/exact/' + URL = 'http://pi.hole:8080/api/whitelist/exact/' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -324,11 +331,15 @@ The domain/regex to be removed is specified through the URL (``). print(response.json()) ``` -!!! success "Success response" + **Parameters** + + Specify the requested item through the URL (``) + +??? success "Success response" Response code: `HTTP/1.1 204 No Content` -!!! failure "Error response (database permission error)" +??? failure "Error response (database permission error)" Response code: `HTTP/1.1 402 - Request failed` diff --git a/docs/api/index.md b/docs/api/index.md index d2429bc..a82cdf0 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -13,12 +13,12 @@ The Pi-hole API uses API keys to authenticate requests. You can view your API ke The Authorization HTTP header can be specified with `Token ` to authenticate as a user and have the same permissions that the user itself. -!!! example active "Example request" +???+ example active "Example request" === "cURL" ``` bash - curl -X GET http://pi.hole/admin/api/dns/status \ + curl -X GET http://pi.hole/api/dns/status \ -H "Authorization: Token " ``` @@ -27,7 +27,7 @@ The Authorization HTTP header can be specified with `Token ` ``` python import requests - URL = 'http://pi.hole/admin/api/dns/status' + URL = 'http://pi.hole/api/dns/status' TOKEN = '' HEADERS = {'Authorization': f'Token {TOKEN}'} @@ -36,17 +36,17 @@ The Authorization HTTP header can be specified with `Token ` print(response.json()) ``` -!!! success "Example reply: Success" +??? success "Example reply: Success" Response code: `HTTP/1.1 200 OK` ``` json { - "status": "enabled" + "blocking": true } ``` -!!! failure "Example reply: Error (unauthorized access)" +??? failure "Example reply: Error (unauthorized access)" Response code: `HTTP/1.1 401 Unauthorized` @@ -61,7 +61,7 @@ The Authorization HTTP header can be specified with `Token ` ``` -Most but not all endpoints require authentication. API requests requiring authentication will also fail if no key is supplied. +Most but not all endpoints require authentication. API endpoints requiring authentication will fail with code `401 Unauthorized` if no key is supplied. ## Errors @@ -69,7 +69,7 @@ Pi-hole uses conventional HTTP response codes to indicate the success or failure Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported. -### HTTP code summary +## HTTP code summary Code | Description | Interpretation ---- | ----------- | -------------- @@ -84,12 +84,12 @@ Code | Description | Interpretation `429` | `Too Many Requests` | Too many requests hit the API too quickly `500`, `502`, `503`, `504` | `Server Errors` | Something went wrong on Pi-hole's end (These are rare) -### JSON response +## JSON response The form of replies to successful requests strongly depends on the selected endpoint, e.g., -!!! success "Example reply: Success" +???+ success "Example reply: Success" Response code: `HTTP/1.1 200 OK` @@ -99,9 +99,9 @@ The form of replies to successful requests strongly depends on the selected endp } ``` -In contrast, errors have a uniform appearance to ease a programatic treatment: +In contrast, errors have a uniform style to ease their programatic treatment: -!!! failure "Example reply: Error (unauthorized access)" +???+ failure "Example reply: Error (unauthorized access)" ``` json { @@ -112,18 +112,52 @@ In contrast, errors have a uniform appearance to ease a programatic treatment: } } ``` + + **Reply type** + + Object + + **Fields** + + ??? info "Key describing the error (`"key": string`)" + This string may be used for internal categorization of error types + + Examples for `key` are: + + - `bad_request` + + Possible reason: Payload is invalid for this endpoint + + - `database_error` + + Possible reason: Failed to read/write to the database + + ??? info "Human-readable description of the error (`"message": string`)" + This string may be shown to the user for troubleshooting + + Examples for `messages` are: + + - `Could not read domains from database table` + + Possible reason: Database is not readable + + - `No request body data` + + Possible reason: Payload is empty + + - `Invalid request body data` + + Possible reason: Payload is not valid JSON + + - `No "domain" string in body data` + + Possible reason: The required field `domain` is missing in the payload + + ??? info "Additional data (`"data": [object|null]`)" + + The field `data` may contain a JSON object. Its content depends on the error itself and may contain further details such as the interpreted user data. If no additional data is available for this endpoint, `null` is returned instead of an object. -The items of the `error` object are always as follows: - -Field | Type | Description ------ | ---- | ----------- -`key` | String | Standardized key describing the error -`message` | String | Description of the error, may be shown to the user - - -In addition, `data` may contain a JSON object. This depends on the error itself and may contain further details such as the interpreted user data. If no additional data is available for this endpoint, `null` is returned instead of an object. - -We recommend writing code that gracefully handles all possible API exceptions. +We recommend writing code that gracefully handles all possible API exceptions. The Pi-hole API is designed to support this by standardized error messages and human-readable hints for errors. {!abbreviations.md!} diff --git a/docs/ftldns/dns-cache.md b/docs/ftldns/dns-cache.md deleted file mode 100644 index e2ed3bd..0000000 --- a/docs/ftldns/dns-cache.md +++ /dev/null @@ -1,39 +0,0 @@ -`pihole-FTL` offers an efficient DNS cache that helps speed up your Internet experience. This DNS cache is part of the embedded `dnsmasq` server. Setting the cache size to zero disables caching. The DNS TTL value is used for determining the caching period. `pihole-FTL` clears its cache on receiving `SIGHUP`. - - -!!! warning Some warning about the DNS cache size - **There is no benefit in increasing this number *unless* the number of DNS cache evictions is greater than zero.** - - A larger cache *will* consume more memory on your node, leaving less memory available for other caches of your Pi-hole. If you push this number to the extremes, it may even be that your Pi-hole gets short on memory and does not operate as expected. - - You can not reduce the cache size below `150` when DNSSEC is enabled because the DNSSEC validation process uses the cache. - - -### Cache metrics - -The Settings page (System panel, FTL table) gives live information about the cache usage. It obtains its information from `http://pi.hole/admin/api.php?getCacheInfo`. - -#### DNS cache size - -Size of the DNS domain cache, defaulting to 10,000 entries. It is the number of entries that can be actively cached at the same time. -This information may also be queried using `dig +short chaos txt cachesize.bind` - -The cache size is set in `/etc/dnsmasq.d/01-pihole.conf`. However, note that this setting does not survive Pi-hole updates. If you want to change the cache size permanently, add a setting - -```plain -CACHE_SIZE=12345 -``` - -in `/etc/pihole/setupVars.conf` and run `pihole -r` (Repair) to get the cache size changed for you automatically. - -#### DNS cache insertions - -Number of total insertions into the cache. This number can be substantially larger than DNS cache size as expiring cache entries naturally make room for new insertions over time. Each lookup with a non-zero TTL will be cached. - -This information may also be queried using `dig +short chaos txt insertions.bind` - -#### DNS cache evictions - -The number of cache entries that had to be removed although the corresponding entries were **not** expired. Old cache entries get removed if the cache is full to make space for more recent domains. The cache size should be increased when this number is larger than zero. - -This information may also be queried using `dig +short chaos txt evictions.bind` diff --git a/mkdocs.yml b/mkdocs.yml index c93651d..46f14ee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -119,13 +119,11 @@ nav: - 'Examples': database/gravity/example.md - 'Pi-hole API': - 'Overview': api/index.md - - 'DNS Information': - - '/dns/blocking': api/dns/blocking.md - - '/dns/cache': api/dns/cache.md + - 'Blocking status': api/dns/blocking.md + - 'Cache information': api/dns/cache.md - 'Domain Lists': api/domainlists.md - - 'FTL': - - 'Network': api/tbd.md - - 'Logs': api/tbd.md + - 'Network': api/tbd.md + - 'Logs': api/tbd.md - 'Statistics': - 'Summary': api/tbd.md - 'Over time': api/tbd.md @@ -140,7 +138,6 @@ nav: - 'Configuration': ftldns/configfile.md - 'Interfaces': ftldns/interfaces.md - 'DNS resolver': ftldns/dns-resolver.md - - 'DNS cache': ftldns/dns-cache.md - 'Blocking mode': ftldns/blockingmode.md - 'Privacy levels': ftldns/privacylevels.md - 'dnsmasq warnings': ftldns/dnsmasq_warn.md