Web Interface & API

DNSvizor exposes a web-based management interface and a DNS-over-HTTPS (DoH) resolver.

Authentication

Access to sensitive endpoints (like the blocklist or configuration) requires authentication.

Password Setup: Sensitive dashboard pages (for example, configuration updates) are protected by a password. Start the unikernel with the --password argument to set the password required to access those endpoints See below which endpoints are password protected.
Method: The interface uses HTTP Basic Auth.

Dnsvizor web authentication

Any username will work, but the password must the be same password you provided as argument (--password) to the unikernel.

The web server listens on the configured HTTPS port (default 443).

/ or /dashboard
- method: GET
- description: Displays statistics such as query rates etc.
- authenticated: false

Dnsvizor dashboard web interface

/querylog
- method: GET
- description: Displays a log of recent DNS queries processed by the resolver. This doesn’t work at the moment.
- authenticated: false

Dnsvizor qeury log web interface

/configuration
- method: GET
- description: Displays the current configuration state.
- authenticated: true
/configuration/upload
- method: POST
- description: Allows uploading a new dnsmasq configuration file (multipart form data).
- authenticated: true
- Parameters:
- dnsmasq_config: The file field containing the configuration text.
- Example with curl:
```
curl -u user:password -F "dnsmasq_config=@/path/to/your/dnsmasq.conf"  https://<unikernel-ip>/configuration/upload
```
You can upload a Dnsmasq configuration file (txt file), and the contents of this file will be automatically loaded in the textarea where you can make modifications if necessary. When you are satisfied with the configuration, you can click on the “Save configuration” button to effect the changes.

Dnsvizor configuration web interface

DNSvizor allows managing blocked domains via the web interface. All endpoints related to the blocklist require authentication

Dnsvizor blocklist web interface

The block list page displays information about blocked domains.

At the top are the domains “manually” blocked either through boot arguments (see DNSvizor options) or via the web interface.
Each blocked domain can be unblocked by the “delete” button.
Below that is another list of remote block lists. There you find what block lists are used as well as the number of domains blocked through that block list source.
Finally, at the top you find a text input field where you can type in domains you want to block.
Next to the input field is a refresh button (“⟳”) that can be clicked to refresh the remote domain block lists. This operation may take some time.

Endpoint	Method	Description
`/blocklist`	`GET`	Lists all currently blocked domains.
`/blocklist/add`	`POST`	Adds a domain to the blocklist. Expects multipart form data with field `domain`.
`/blocklist/delete/<domain>`	`POST`	Removes `<domain>` from the blocklist.
`/blocklist/update`	`POST`	Triggers an immediate update of the blocklists from the configured URLs.

The unikernel implements a compliant DNS-over-HTTPS resolver RFC 8484.

Endpoint: /dns-query
Supported Methods:
- GET: Expects a base64url-encoded DNS query in the ?dns= query parameter.
- POST: Expects the raw DNS query in the body with content-type: application/dns-message.
  - GET example (Base64url encoded): This method uses a base64url-encoded DNS query string.
```
# Query for 'robur.coop' (A record) encoded in base64url
curl "https://<unikernel-ip>/dns-query?dns=cm9idXIuY29vcA"
```
  - POST example assuming ‘query.bin’ contains a raw DNS query packet
```
curl -X POST -H "Content-Type: application/dns-message" --data-binary @query.bin https://<unikernel-ip>/dns-query
    ```
```