pi-hole · DL6ER · Oct 28, 2023 · Oct 28, 2023 · Oct 28, 2023 · Oct 28, 2023
diff --git a/.github/workflows/calibreapp-image-actions.yml b/.github/workflows/calibreapp-image-actions.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3.6.0
+        uses: actions/checkout@v4.1.0
 
       - name: Compress Images
         uses: calibreapp/[email protected] # TODO: if they start using a tag like v1, switch to that

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -17,12 +17,12 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.6.0
+      - uses: actions/checkout@v4.1.0
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/[email protected].0
+        uses: actions/[email protected].1
         with:
           python-version: "${{ env.PYTHON_VERSION }}"
           architecture: "x64"

diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -10,10 +10,10 @@ jobs:
     steps:
     -
       name: Checkout repository
-      uses: actions/checkout@v3.6.0
+      uses: actions/checkout@v4.1.0
     -
       name: Spell-Checking
       uses: codespell-project/actions-codespell@master
       with:
         ignore_words_file: .codespellignore
-        skip: ./docs/routers/fritzbox-de.md,./mkdocs.yml,./package.json,./package-lock.json,./.markdownlint.json,./requirements.txt
+        skip: ./docs/routers/fritzbox-de.md,./mkdocs.yml,./package.json,./package-lock.json,./.markdownlint.json,./requirements.txt, ./MathJax-es5/*
diff --git a/.github/workflows/editorconfig-checker.yml b/.github/workflows/editorconfig-checker.yml
@@ -9,6 +9,6 @@ jobs:
     name: editorconfig-checker
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.6.0
+      - uses: actions/checkout@v4.1.0
       - uses: editorconfig-checker/action-editorconfig-checker@main
       - run: editorconfig-checker
diff --git a/docs/abbreviations.md b/docs/abbreviations.md
@@ -1,15 +1,16 @@
 
+*[API]: Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)
 *[DNS]: Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)
-*[FTL]: Pi-hole's Faster Than Light daemon
+*[DnyDNS]: Dynamic DNS record pointing to a frequently changing IP address
 *[DHCP]: Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)
 *[DHCPv6]: Dynamic Host Configuration Protocol version 6 (a network protocol for configuring Internet Protocol version 6 (IPv6) hosts with IP addresses)
+*[FTL]: Pi-hole's Faster Than Light daemon
 *[IPv4]: Internet Protocol version 4 (addresses like 192.168.0.1)
 *[IPv6]: Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)
 *[HTTP]: Hypertext Transfer Protocol (HTTP), an application protocol for distributed, collaborative, and hypermedia information systems
 *[HTTPS]: HTTP Secure (HTTPS), an extension of the Hypertext Transfer Protocol (HTTP) for secure communication over a computer network
 *[TCP]: Transmission Control Protocol (protocol providing reliable, ordered, and error-checked delivery of data between applications running on hosts communicating via an IP network)
 *[UDP]: User Datagram Protocol (a network communications method for sending messages as datagrams)
-*[API]: Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)
 *[PE]: Privacy Extension
 *[PID]: Process identifier (a number used to identify a process)
 *[HOSTS]: The computer file /etc/hosts is an operating system file that maps hostnames to IP addresses
@@ -39,4 +40,6 @@
 *[TFTP]: Trivial File Transfer Protocol is a simple lockstep File Transfer Protocol which allows a client to get a file from or put a file onto a remote host
 *[TTL]: Time-To-Live is a mechanism that limits the lifespan or lifetime of data in a computer or network
 *[NAT]: Network address translation
-*[DnyDNS]: Dynamic DNS record pointing to a frequently changing IP address
+*[UTF-8]: 8-bit Unicode Transformation Format - a character encoding format capable of encoding all known 1,112,064 valid Unicode characters
+*[URL]: Uniform Resource Locator, commonly known as "web address"
+*[REST]: Representational State Transfer - a software architecture for distributed systems like the World Wide Web (WWW)
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,190 @@
+# API Reference
+
+The Pi-hole API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 [JavaScript Object Notation (JSON)-encoded](http://www.json.org/) data for all API responses, and uses standard HTTP response codes and verbs.
+
+Most (but not all) endpoints require authentication. API endpoints requiring authentication will fail with code `401 Unauthorized` if no key is supplied.
+
+## JSON response
+
+The form of replies to successful requests strongly depends on the selected endpoint, e.g.,
+
+<!-- markdownlint-disable code-block-style -->
+???+ success "Example reply: Success"
+
+    Resource: `GET /api/dns/blocking`
+
+    Response code: `HTTP/1.1 200 OK`
+
+    ``` json
+    {
+      "blocking": true
+    }
+    ```
+
+    **Reply type**
+
+    Object or Array
+
+    **Fields**
+
+    Depending on the particular endpoint
+
+In contrast, errors have a uniform style to ease their programmatic treatment:
+
+???+ failure "Example reply: Error (unauthorized access)"
+
+    Resource: `GET /api/domains`
+
+    Response code: `HTTP/1.1 401 Unauthorized`
+
+    ``` json
+    {
+        "error": {
+            "key": "unauthorized",
+            "message": "Unauthorized",
+            "data": null
+        }
+    }
+    ```
+
+    **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.
+
+        Examples for a failed request with `data` being set is (domain is already on this list):
+
+        ``` json
+        {
+            "error":  {
+                "key":  "database_error",
+                "message":  "Could not add to gravity database",
+                "data": {
+                    "argument": "abc.com",
+                    "enabled":  true,
+                    "sql_msg":  "UNIQUE constraint failed: domainlist.domain, domainlist.type"
+                }
+            }
+        }
+        ```
+<!-- markdownlint-enable code-block-style -->
+
+## HTTP methods used by this API
+
+Each HTTP request consists of a method that indicates the action to be performed on the identified resource. The relevant standards is [RFC 2616](https://tools.ietf.org/html/rfc2616). Though, RFC 2616 has been very clear in differentiating between the methods, complex wordings are a source of confusion for many users.
+
+Pi-hole's API uses the methods like this:
+
+Method   | Description
+---------|------------
+`GET`    | **Read** from resource. The resource may not exist.
+`POST`   | **Create** resources
+`PUT`    | **Create or Replace** a resource. This method is commonly used to *update* entries.
+`DELETE` | **Delete** existing resource
+
+<!-- markdownlint-disable code-block-style -->
+??? info "Summarized details from [RFC 2616, Scn. 9](https://tools.ietf.org/html/rfc2616#section-9) (`GET/POST/PUT/DELETE`)"
+    ### `GET`
+
+    The `GET` method means retrieve whatever information (in the form of an entity) that is identified by the URI.
+
+    As `GET` requests do not change the state of the resource, these are said to be **safe methods**. Additionally, `GET` requests are **idempotent**, which means that making multiple identical requests must produce the same result every time until another method (`POST` or `PUT`) has changed the state of the resource on the server.
+
+    For any given HTTP `GET`, if the resource is found on the server, then the API returns HTTP response code `200 (OK)` – along with the response body.
+
+    In case a resource is NOT found on server, then the API returns HTTP response code `404 (Not found)`. Similarly, if it is determined that `GET` request itself is not correctly formed then API will return HTTP response code `400 (Bad request)`.
+
+    ### `POST`
+
+    Use `POST` APIs to **create new subordinate records**, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table. W`POST` methods are used to create a new resource into the collection of resources.
+
+    If a resource has been created on the origin server, the response will be `201 (Created)`.
+    Not all action performed using the `POST` method will result in a resource that can be identified by a URI. In such a case, either `200 (OK)` or `204 (No Content)` is the appropriate response status, depending on whether or not the response includes an entity that describes the result.
+
+    Note that `POST` is **neither safe nor idempotent**, and invoking two identical `POST` requests typically results in an error.
+
+    ### `PUT`
+
+    Use `PUT` primarily to **update existing records** (if the resource does not exist, the API will typically create a new record for it). If a new record has been added at the given URI, or an existing resource is modified, either the `200 (OK)` or `204 (No Content)` response codes are sent to indicate successful completion of the request.
+
+    ### `DELETE`
+
+    As the name applies, `DELETE` APIs are used to **delete records** (identified by the Request-URI).
+
+    A successful response will be `200 (OK)` if the response includes an entity describing the status, `202 (Accepted)` if the action has not yet been enacted, or `204 (No Content)` if the action has been enacted but the response does not include an entity.
+
+    `DELETE` operations are **idempotent**. If you `DELETE` a resource, it’s removed from the collection of resources. Repeatedly calling `DELETE` on that resource will not change the outcome – however, calling `DELETE` on a resource a second time *may* return a 404 (NOT FOUND) since it was already removed.
+
+???+ info "Example"
+    Let’s list down few URIs and their purpose to get better understanding when to use which method:
+
+    Method + URI | Interpretation
+    ---------------------|--------------------
+    `GET /api/groups` | Get all groups
+    `POST /api/groups` | Create a new group
+    `GET /api/groups/abc` | Get the group `abc`
+    `PUT /api/groups/abc` | Update the group `abc`
+    `DELETE /api/groups/abc` | Delete group `abc`
+<!-- markdownlint-enable code-block-style -->
+
+## Error handling
+
+Pi-hole uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, missing authentication, etc.). Codes in the `5xx` range indicate an error with Pi-hole's API (these are rare).
+
+Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported:
+
+Code | Description | Interpretation
+---- | ----------- | --------------
+`200` | `OK` | Everything worked as expected
+`201` | `Content Created` | Added a new item
+`204` | `No Content` | Removed an item
+`400` | `Bad Request` | The request was unacceptable, often due to a missing required parameter
+`401` | `Unauthorized` | No session identity provided for endpoint requiring authorization
+`402` | `Request Failed` | The parameters were valid but the request failed
+`403` | `Forbidden` | The API key doesn't have permissions to perform the request
+`404` | `Not Found` | The requested resource doesn't exist
+`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)
+
+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/core/pihole-command.md b/docs/core/pihole-command.md
@@ -7,7 +7,6 @@ Pi-hole makes use of many commands, and here we will break down those required t
 | Index | Invocation |
  -------------- | --------------
 [Core Script](#pi-hole-core) | `pihole`
-[Web Script](#pi-hole-web) | `pihole -a`
 
 ---
 
@@ -21,7 +20,7 @@ Pi-hole makes use of many commands, and here we will break down those required t
 [Log Flush](#log-flush) | `pihole flush`
 [Reconfigure](#reconfigure) | `pihole reconfigure`
 [Tail](#tail) | `pihole tail`
-[Admin](#admin) | `pihole -a`
+[Set password](#password) | `pihole setpassword`
 [Chronometer](#chronometer) | `pihole chronometer`
 [Gravity](#gravity) | `pihole updateGravity`
 [Logging](#logging) | `pihole logging`
@@ -109,15 +108,6 @@ Example Usage   | [`pihole tail`](https://discourse.pi-hole.net/t/the-pihole-com
 
 Since Pi-hole will log DNS queries by default, using this command to watch the log in real-time can be useful for debugging a problematic site, or even just for sheer curiosities sake.
 
-### Admin
-
-| | |
- -------------- | --------------
-Help Command    | `pihole -a --help`
-Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh)
-Example Usage   | `pihole -a -p secretpassword`
-
-Detailed information on this is [found here](#web-script).
 
 ### Chronometer
 
@@ -261,35 +251,15 @@ Switch Pi-hole subsystems to a different GitHub branch. An admin can specify rep
 
 ---
 
-## Pi-hole Web
-
-| Feature | Invocation |
- -------------- | --------------
-[Web Script](#web-script) | `pihole -a`
-[Password](#password) | `pihole -a password`
-[Teleport](#teleport) | `pihole -a -t`
-[Temperature Unit](#temperature-unit) | `pihole -a celsius`, `pihole -a fahrenheit`, `pihole -a kelvin`
-[Interface](#interface) | `pihole -a interface`
-
-### Web Script
-
-| | |
- -------------- | --------------
-Help Command    | `pihole -a --help`
-Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh)
-Example Usage   | `pihole -a -p secretpassword`
-
-Set options for the Web Interface. This script is used to tie in all Web Interface features which are not already covered by the [Core Script](#core-script).
-
 ### Password
 
 | | |
  -------------- | --------------
 Help Command    | N/A
-Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh)
-Example Usage   | [`pihole -a -p secretpassword`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#web-password)
+Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole)
+Example Usage   | `pihole setpassword`
 
-Set the Web Interface password. Password can be entered as an option (e.g: `pihole -a -p secretpassword`), or separately as to not display on the screen (e.g: `pihole -a -p`).
+Set the Web Interface an API password. Password can be entered as an option (e.g: `pihole setpassword secretpassword`), or separately as to not display on the screen (e.g: `pihole setpassword`).
 
 ### Teleport
 
@@ -300,23 +270,3 @@ Script Location | N/A
 Example Usage   | `pihole -a -t`
 
 Create a configuration backup. The backup will be created in the directory from which the command is run. The backup can be imported using the Settings > Teleport page.
-
-### Temperature Unit
-
-| | |
- -------------- | --------------
-Help Command    | N/A
-Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh)
-Example Usage   | [`pihole -a -c`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#temp-unit)
-
-Set the specified temperature unit as the preferred type. This preference will affect the Web Interface, as well as Chronometer.
-
-### Interface
-
-| | |
- -------------- | --------------
-Help Command    | `pihole -a interface --help`
-Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh)
-Example Usage   | [`pihole -a interface local`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#interface)
-
-Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [Wireguard](../guides/vpn/wireguard/overview.md) to grant your mobile devices access to the Pi-hole.
diff --git a/docs/database/ftl.md b/docs/database/ftl.md
@@ -160,6 +160,7 @@ ID | DNSSEC status is
 2 | `INSECURE`
 3 | `BOGUS`
 4 | `ABANDONED`
+5 | `TRUNCATED`
 
 ### Linking tables