feat: add full Zonemaster stack with Docker and Spanish UI

- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-21 08:19:24 +02:00
commit 8d4eaa1489
1567 changed files with 204155 additions and 0 deletions
--- a/zonemaster/docs/public/using/backend/Using-Zonemaster-Backend-JSON-RPC-API.md
+++ b/zonemaster/docs/public/using/backend/Using-Zonemaster-Backend-JSON-RPC-API.md
@@ -0,0 +1,311 @@
+# Using Zonemaster-Backend JSON-RPC API
+
+## Table of contents
+
+* [Introduction](#introduction)
+* [Check that the RPC API daemon is running and answering properly](#check-that-the-json-rpc-api-service-is-running-and-answering-properly)
+* [Run a test of the zonemaster.net zone using zmtest](#run-a-test-of-the-zonemasternet-zone-using-zmtest)
+* [Run a test of the zonemaster.net zone using zmb](#run-a-test-of-the-zonemasternet-zone-using-zmb)
+  * [Enqueue a test](#enqueue-a-test)
+  * [Check the progress](#check-the-progress)
+  * [Fetch the results](#fetch-the-results)
+* [Find available languages](#find-available-languages)
+* [Find previous tests](#find-previous-tests)
+* [Other APIs](#other-apis)
+* [IDN domain names](#idn-domain-names)
+* [Using curl instead](#using-curl-instead)
+
+## Introduction
+
+This is a guide for getting started with the Zonemaster [JSON-RPC API] service
+(running as a daemon).
+
+Note that this guide makes a number of assumptions about your setup:
+
+* That it is a Unix-like environment.
+* That you have Zonemaster-Backend installed according to the
+  [installation guide]
+* That Zonemaster-Backend is running. See [installation guide] for how to start
+  Zonemaster-Backend.
+* If you have changed IP address (default 127.0.0.1) or port (default 5000) then
+  you must specify that in the commands below. Here we assume default.
+
+For this guide we will use the two Zonemaster-Backend tools `zmb` and `zmtest`.
+Both are installed when Zonemaster-Backend is installed. To get more information
+what parameters they expect, run `zmb -h` and `zmtest -h`.
+
+With `zmtest` you can start a domain test and get the result directly. With `zmb`
+you can also do that, but in several steps, but on the other hand, `zmb` offers
+many more possibilities. Actually, `zmtest` uses `zmb` behind the scen.
+
+The `zmb` tool uses the JSON-RPC API to interact with Zonemaster-Backend.
+Zonemaster-GUI also uses the same JSON-RPC API to start tests and fetch the
+test results.
+
+## Check that the JSON-RPC API service is running and answering properly
+
+```sh
+zmb version_info
+```
+
+To get a more readable output, pipe the command through `jq`:
+
+```sh
+zmb version_info | jq
+```
+
+If there is no response from the JSON-RPC API service, go to the
+[installation guide] for how to start or restart it.
+
+Below most commands will be piped through `jq`, but for processing you might want
+to have the JSON on one line, or you might want to look at the options for `jq`
+to extract fields (see `jq -h`).
+
+## Run a test of the zonemaster.net zone using zmtest
+
+To just run a test `zmtest` is the simple tool to use:
+
+```sh
+zmtest zonemaster.net
+```
+
+The tool will also display the result, which will be a large JSON object (here
+truncated).
+
+```
+testid: 879d13569db70fde
+100% done
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "created_at": "2024-10-25T09:28:38Z",
+    "hash_id": "879d13569db70fde",
+    "params": {
+      "domain": "zonemaster.net",
+      "ds_info": [],
+      "ipv4": true,
+      "ipv6": true,
+      "nameservers": [],
+      "priority": 10,
+      "profile": "default",
+      "queue": 0
+    },
+    "results": [
+      {
+        "level": "INFO",
+        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
+        "module": "System",
+        "testcase": "Unspecified"
+      },
+      {
+        "level": "INFO",
+        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n",
+        "module": "Basic",
+        "testcase": "Basic01"
+      },
+      {
+        "level": "INFO",
+        "message": "The zone \"zonemaster.net\" is found.\n",
+        "module": "Basic",
+        "testcase": "Basic01"
+      },
+      {
+        "level": "INFO",
+        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n",
+        "module": "Basic",
+        "testcase": "Basic02"
+      },
+(...)
+```
+
+You will find the meaning of all fields in the outputs in
+[Zonemaster-Backend JSON-RPC API reference][JSON-RPC API].
+
+## Run a test of the zonemaster.net zone using zmb
+
+If we instead use `zmb` then this will be done in three steps (that happen
+behind the scen when using `zmtest`):
+
+1. Enqueue test.
+2. Check if testing has completed (progress) - maybe several times.
+3. Fetch result (maybe several times with different translations).
+
+### Enqueue a test
+
+To enqueue a test of zonemaster.net we run
+`zmb start_domain_test --domain zonemaster.net | jq` and immediately get the
+response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": "879d13569db70fde"
+}
+```
+The `results` field holds the test ID which we need for further steps. It
+always consists of 16 hexadecimal digits.
+
+### Check the progress
+
+To check the progress we run `zmb test_progress --test-id 879d13569db70fde | jq`
+with the test ID from enqueueing, and get the response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": 8
+}
+```
+
+Now the `results` field holds the progress of testing, an integer between 0 and
+100 to mean 0% to 100%. 0% means that testing has not started (maybe many tests
+in the queue) and 100% means that testing has completed.
+
+We have to stay in the check step until the test has reached 100%. In our
+example above, it is 8%, so we run the command again and now we get the
+response
+
+```json
+{
+  "result": 100,
+  "jsonrpc": "2.0",
+  "id": 1
+}
+```
+
+### Fetch the results
+
+When the test has completed the test results can be fetched. The test ID is found
+above and then the language has to be chosen. Here `en` is used. More about
+languages below. Run 
+`zmb get_test_results --test-id 879d13569db70fde --lang en | jq` and get a JSON
+structure with data (as with `zmtest`). Again, the JSON structure is long and is
+truncated here.
+
+```
+{
+  "id": 1,
+  "result": {
+    "results": [
+      {
+        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
+        "testcase": "Unspecified",
+        "level": "INFO",
+        "module": "System"
+      },
+      {
+        "module": "Basic",
+        "level": "INFO",
+        "testcase": "Basic01",
+        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n"
+      },
+      {
+        "message": "The zone \"zonemaster.net\" is found.\n",
+        "module": "Basic",
+        "testcase": "Basic01",
+        "level": "INFO"
+      },
+      {
+        "level": "INFO",
+        "testcase": "Basic02",
+        "module": "Basic",
+        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n"
+      },
+(...)
+```
+
+## Find available languages
+
+The result can be presented in several languages, depending on installation. To
+find out what languages that are available, run `zmb get_language_tags | jq`.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": [
+    "da",
+    "en",
+    "es",
+    "fi",
+    "fr",
+    "nb",
+    "sl",
+    "sv"
+  ]
+}
+```
+
+## Find previous tests
+
+It is possible to find previous tests of a specific domain (zone). Run
+`zmb get_test_history --domain zonemaster.net |jq` to get all tests of
+`zonemaster.net`. The output looks like the following:
+
+```
+{
+  "jsonrpc": "2.0",
+  "result": [
+    {
+      "undelegated": false,
+      "created_at": "2024-10-25T09:54:38Z",
+      "id": "00669309ac7887c3",
+      "overall_result": "ok"
+    },
+    {
+      "overall_result": "ok",
+      "id": "879d13569db70fde",
+      "undelegated": false,
+      "created_at": "2024-10-25T09:28:38Z"
+    }
+  ],
+  "id": 1
+}
+```
+
+Now you can get the results of any of the listed tests by running
+`get_test_results` with selected test ID and language as above.
+
+## Other APIs
+
+There are a few other APIs that can be used throught `zmb`, and can be found by
+`zmb -h` and in [Zonemaster-Backend JSON-RPC API reference][JSON-RPC API]. The APIs for batch
+testing are covered in [Using Zonemaster Backend for batch testing].
+
+## IDN domain names
+
+When enqueuing a test of an IDN domain name with `zmb start_domain_test` it is
+possible to provide the domain name as either A-label or U-label. E.g. both
+"räksmörgås.se" or "xn--rksmrgs-5wao1o.se" (the same domain name) work as well.
+
+The same is also true if using Curl instead (see below).
+
+## Using Curl instead
+
+Instead of using `zmb` it is possible to run the commands by `curl`, which
+requires that the JSON structure is created, but can give greater flexibility.
+The method can also be copied into different programming languages when
+scripting.
+
+The same enqueuing of the zonemaster.net zone as above will then be:
+
+```sh
+curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 2, "method": "start_domain_test", "params": {"domain": "zonemaster.net"}}' http://localhost:5000/ | jq .
+```
+
+And fetching the result, when completed, will be:
+
+```sh
+curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 5, "method": "get_test_results", "params": {"id": "879d13569db70fde", "language": "en"}}' http://localhost:5000/ | jq .
+```
+
+The format of the JSON structure for every method is found in the 
+[Zonemaster-Backend JSON-RPC API reference][JSON-RPC API].
+
+
+[installation guide]:                                 ../../installation/zonemaster-backend.md
+[JSON-RPC API]:                                       rpcapi-reference.md
+[Using Zonemaster Backend for batch testing]:         Using-Zonemaster-Backend-for-batch-testing.md