@astrofoundry/pi-astro 0.40.17 → 0.40.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/agents/dns.md
CHANGED
|
@@ -16,7 +16,7 @@ Rules:
|
|
|
16
16
|
|
|
17
17
|
- Read before you write: list the zone's records, then add, update, or delete exactly the record the task names. Never create duplicates.
|
|
18
18
|
- Internal changes go to the Technitium primary only; the other nodes follow through the catalog zone and the cluster. After a write, read the same zone from every node with `node <fqdn>` and report whether each has caught up.
|
|
19
|
-
- New internal zones are Primary zones in the
|
|
19
|
+
- New internal zones are Primary zones in the cluster catalog; confirm with `zone-options` afterwards.
|
|
20
20
|
- Public records for the front door point at the VPS address with TTL 300 and `proxied: false`. Add the hostname to the VPS nginx allowlist (edge specialist) before the public record exists.
|
|
21
21
|
- Deleting a zone or a record is only for tasks that name it explicitly; state what would disappear before you do it.
|
|
22
22
|
- Report facts from the JSON output, including the record ids Cloudflare returns.
|
|
@@ -35,8 +35,8 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
|
|
|
35
35
|
// Every UniFi write, on either console.
|
|
36
36
|
network: [/^unifi\s+\S+\s+write\b/],
|
|
37
37
|
dns: [
|
|
38
|
-
/^technitium\s+primary\s+(zone-create|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
|
|
39
|
-
/^technitium\s+node\s+\S+\s+server-domain\b/,
|
|
38
|
+
/^technitium\s+primary\s+(zone-create|zone-catalog|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
|
|
39
|
+
/^technitium\s+node\s+\S+\s+(server-domain|stale-zone-delete)\b/,
|
|
40
40
|
/^technitium\s+join\b/,
|
|
41
41
|
/^cloudflare\s+record-(add|update|delete)\b/,
|
|
42
42
|
],
|
package/package.json
CHANGED
package/skills/dns/SKILL.md
CHANGED
|
@@ -5,7 +5,7 @@ description: How the dns specialist operates the Technitium cluster (internal re
|
|
|
5
5
|
|
|
6
6
|
# DNS specialist
|
|
7
7
|
|
|
8
|
-
The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary node `technitium1` on Synapse (`10.0.40.53`), and the Secondary nodes `technitium2` (LXC 107 on Pulsar, `10.0.40.54`) and `technitium3` (LXC 100 on SPACE-X at Mira, `10.1.40.53`). The primary owns every zone; the
|
|
8
|
+
The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary node `technitium1` on Synapse (`10.0.40.53`), and the Secondary nodes `technitium2` (LXC 107 on Pulsar, `10.0.40.54`) and `technitium3` (LXC 100 on SPACE-X at Mira, `10.1.40.53`). The primary owns every zone; the cluster catalog zone `cluster-catalog.dns.home.arpa` replicates them, and the cluster syncs settings, blocklists, allowed and blocked zones, apps, and users to the other nodes. Every call goes to the primary; `node <fqdn>` makes the primary run it on another node. Public names live in Cloudflare zones `37pla.net` and `monadeo.com`. The `dns` tool has two families; `["--help"]` lists everything.
|
|
9
9
|
|
|
10
10
|
## `technitium primary <command>` and `technitium node <fqdn> <command>`
|
|
11
11
|
|
|
@@ -18,7 +18,8 @@ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary
|
|
|
18
18
|
| `stats [LastHour\|LastDay\|LastWeek\|LastMonth\|LastYear]` | dashboard counters |
|
|
19
19
|
| `cluster-state` | cluster domain, nodes with id, type, state, and last seen, and the server's addresses |
|
|
20
20
|
| `settings` | all server settings; secrets are redacted |
|
|
21
|
-
| `zone-create <zone>` (primary) | Primary zone in the catalog |
|
|
21
|
+
| `zone-create <zone>` (primary) | Primary zone in the cluster catalog |
|
|
22
|
+
| `zone-catalog <zone>` (primary) | make an existing Primary zone a member of the cluster catalog |
|
|
22
23
|
| `zone-delete <zone>` (primary) | deletes the zone and every record |
|
|
23
24
|
| `record-add <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/add` |
|
|
24
25
|
| `record-update <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/update` |
|
|
@@ -27,6 +28,7 @@ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary
|
|
|
27
28
|
| `cluster-delete` (primary) | remove the cluster from the primary; refused while Secondary nodes exist |
|
|
28
29
|
| `cluster-remove <secondaryNodeId>` (primary) | ask a Secondary node (id from `cluster-state`) to leave |
|
|
29
30
|
| `server-domain <name>` (primary or node) | set that node's DNS Server Domain |
|
|
31
|
+
| `stale-zone-delete <zone>` (node only) | delete a Secondary zone no catalog manages (checked first), so the cluster catalog recreates it |
|
|
30
32
|
|
|
31
33
|
Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `newIpAddress`); `CNAME` `cname`; `TXT` `text`; `MX` `exchange`, `preference`; `SRV` `priority`, `weight`, `port`, `target`; `NS` `nameServer`; `PTR` `ptrName`. `ttl=<seconds>` and `comments=<text>` apply to all; `overwrite=true` replaces the record set on add.
|
|
32
34
|
|
package/specialists/README.md
CHANGED
|
@@ -73,7 +73,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
|
|
|
73
73
|
"homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" }
|
|
74
74
|
{ "unifi37HostId": "<from: specialist-cli network -- unifi cloud /v1/hosts>", "unifi37LocalUrl": "https://10.0.10.1/proxy/network/integration", "unifi37CertSha256": "<from: specialist-cli network -- unifi 37 fingerprint>",
|
|
75
75
|
"unifiMiraHostId": "<the same>", "unifiMiraLocalUrl": "https://192.168.1.1/proxy/network/integration", "unifiMiraCertSha256": "<the same>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
|
|
76
|
-
{ "technitiumPrimaryUrl": "http://10.0.40.53:5380"
|
|
76
|
+
{ "technitiumPrimaryUrl": "http://10.0.40.53:5380" }
|
|
77
77
|
{ "gcloud": "/usr/local/libexec/specialist-gcloud/current/bin/gcloud", "gcloudPython": "/usr/local/libexec/specialist-python/current/bin/python3",
|
|
78
78
|
"project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com",
|
|
79
79
|
"iapLocalPort": 22337, "sshUser": "spc-edge", "publicIp": "35.237.66.101", "probeHost": "auth.37pla.net",
|
package/specialists/dns/run.ts
CHANGED
|
@@ -11,11 +11,12 @@ const SERVICE = "dns";
|
|
|
11
11
|
interface DnsConfig extends Record<string, string> {
|
|
12
12
|
/** API of the cluster primary; every other node is reached through it with the `node` parameter. */
|
|
13
13
|
technitiumPrimaryUrl: string;
|
|
14
|
-
/** Catalog zone new primary zones join, so the other nodes receive them. */
|
|
15
|
-
technitiumCatalog: string;
|
|
16
14
|
}
|
|
17
15
|
|
|
18
|
-
const SHAPE = { technitiumPrimaryUrl: "string"
|
|
16
|
+
const SHAPE = { technitiumPrimaryUrl: "string" } as const;
|
|
17
|
+
|
|
18
|
+
/** Commands that need the cluster catalog, which the primary's cluster state names. */
|
|
19
|
+
const CATALOG_COMMANDS = new Set(["zone-create", "zone-catalog"]);
|
|
19
20
|
|
|
20
21
|
const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
|
|
21
22
|
const TIMEOUT_MS = 30_000;
|
|
@@ -47,7 +48,8 @@ export const TECHNITIUM_READS: Readonly<Record<string, { args: [number, number];
|
|
|
47
48
|
|
|
48
49
|
/** Technitium writes; zone and cluster writes on the primary only, the other nodes follow through the catalog and the cluster. */
|
|
49
50
|
export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]; help: string }>> = {
|
|
50
|
-
"zone-create": { args: [1, 1], help: "zone-create <zone> Primary zone, member of the
|
|
51
|
+
"zone-create": { args: [1, 1], help: "zone-create <zone> Primary zone, member of the cluster catalog" },
|
|
52
|
+
"zone-catalog": { args: [1, 1], help: "zone-catalog <zone> make an existing Primary zone a member of the cluster catalog" },
|
|
51
53
|
"zone-delete": { args: [1, 1], help: "zone-delete <zone> delete a zone and every record in it" },
|
|
52
54
|
"record-add": { args: [3, 40], help: "record-add <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 ttl=300" },
|
|
53
55
|
"record-update": { args: [3, 40], help: "record-update <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 newIpAddress=10.0.40.98" },
|
|
@@ -56,6 +58,7 @@ export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]
|
|
|
56
58
|
"cluster-delete": { args: [0, 0], help: "cluster-delete remove the cluster from the primary (only without Secondary nodes)" },
|
|
57
59
|
"cluster-remove": { args: [1, 1], help: "cluster-remove <secondaryNodeId> ask a Secondary node to leave the cluster" },
|
|
58
60
|
"server-domain": { args: [1, 1], help: "server-domain <name> DNS Server Domain of the target node (also with node)" },
|
|
61
|
+
"stale-zone-delete": { args: [1, 1], help: "stale-zone-delete <zone> (node only) delete a Secondary zone that no catalog manages, so the cluster catalog recreates it" },
|
|
59
62
|
};
|
|
60
63
|
|
|
61
64
|
const HELP = `dns specialist
|
|
@@ -133,6 +136,8 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
|
|
|
133
136
|
}
|
|
134
137
|
case "zone-create":
|
|
135
138
|
return { path: "/api/zones/create", params: { zone: assertName(rest[0], "zone"), type: "Primary", catalog }, primaryOnly: true };
|
|
139
|
+
case "zone-catalog":
|
|
140
|
+
return { path: "/api/zones/options/set", params: { zone: assertName(rest[0], "zone"), catalog }, primaryOnly: true };
|
|
136
141
|
case "zone-delete":
|
|
137
142
|
return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: true };
|
|
138
143
|
case "record-add":
|
|
@@ -164,6 +169,8 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
|
|
|
164
169
|
case "cluster-remove":
|
|
165
170
|
if (!NODE_ID.test(rest[0])) throw new UsageError("cluster-remove needs the numeric Secondary node id from cluster-state");
|
|
166
171
|
return { path: "/api/admin/cluster/primary/removeSecondary", params: { secondaryNodeId: rest[0] }, primaryOnly: true };
|
|
172
|
+
case "stale-zone-delete":
|
|
173
|
+
return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: false };
|
|
167
174
|
case "server-domain":
|
|
168
175
|
return { path: "/api/settings/set", params: { dnsServerDomain: assertName(rest[0], "server domain") }, primaryOnly: false };
|
|
169
176
|
default:
|
|
@@ -255,6 +262,14 @@ async function join(config: DnsConfig, args: string[]): Promise<number> {
|
|
|
255
262
|
return 0;
|
|
256
263
|
}
|
|
257
264
|
|
|
265
|
+
/** The cluster catalog zone, `cluster-catalog.<clusterDomain>`, from the primary's cluster state. */
|
|
266
|
+
async function clusterCatalog(config: DnsConfig): Promise<string> {
|
|
267
|
+
const state = await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/cluster/state", {}, readSecret(SERVICE, "TECHNITIUM_TOKEN"), "primary");
|
|
268
|
+
const domain = (state.response as { clusterDomain?: string } | undefined)?.clusterDomain;
|
|
269
|
+
if (domain === undefined) throw new ServiceError("the primary reports no initialized cluster");
|
|
270
|
+
return `cluster-catalog.${domain}`;
|
|
271
|
+
}
|
|
272
|
+
|
|
258
273
|
/** Splits `primary <command>` or `node <fqdn> <command>` into the target node (undefined for the primary) and the command. */
|
|
259
274
|
export function technitiumTarget(args: string[]): { node: string | undefined; rest: string[] } {
|
|
260
275
|
if (args[0] === "primary") return { node: undefined, rest: args.slice(1) };
|
|
@@ -269,11 +284,21 @@ export function technitiumTarget(args: string[]): { node: string | undefined; re
|
|
|
269
284
|
async function technitium(config: DnsConfig, args: string[]): Promise<number> {
|
|
270
285
|
if (args[0] === "join") return join(config, args.slice(1));
|
|
271
286
|
const { node, rest } = technitiumTarget(args);
|
|
272
|
-
const
|
|
287
|
+
const catalog = CATALOG_COMMANDS.has(rest[0] ?? "") ? await clusterCatalog(config) : "";
|
|
288
|
+
const request = technitiumRequest(catalog, rest);
|
|
273
289
|
if (node !== undefined && request.primaryOnly) throw new UsageError("zone and cluster writes go to the primary; the other nodes follow through the catalog zone and the cluster");
|
|
274
290
|
const params = node === undefined ? request.params : { ...request.params, node };
|
|
275
291
|
const target = node ?? "primary";
|
|
276
|
-
const
|
|
292
|
+
const token = readSecret(SERVICE, "TECHNITIUM_TOKEN");
|
|
293
|
+
if (rest[0] === "stale-zone-delete") {
|
|
294
|
+
if (node === undefined) throw new UsageError("stale-zone-delete needs node <fqdn>; delete a primary zone with zone-delete");
|
|
295
|
+
const options = await technitiumCall(config.technitiumPrimaryUrl, "/api/zones/options/get", { zone: params.zone, node }, token, target);
|
|
296
|
+
const zone = options.response as { type?: string; catalog?: string | null } | undefined;
|
|
297
|
+
if (!["Secondary", "SecondaryCatalog"].includes(zone?.type ?? "") || (zone?.catalog ?? null) !== null) {
|
|
298
|
+
throw new UsageError(`${params.zone} on ${node} is ${zone?.type ?? "unknown"} in catalog ${zone?.catalog ?? "none"}; only a Secondary zone outside any catalog is stale`);
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
const parsed = await technitiumCall(config.technitiumPrimaryUrl, request.path, params, token, target);
|
|
277
302
|
printJson({ node: target, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
|
|
278
303
|
return 0;
|
|
279
304
|
}
|
|
@@ -195,6 +195,12 @@ describe("dns wrapper", () => {
|
|
|
195
195
|
primaryOnly: true,
|
|
196
196
|
});
|
|
197
197
|
expect(technitiumRequest("c", ["cluster-delete"]).params).toEqual({ forceDelete: "false" });
|
|
198
|
+
expect(technitiumRequest("c", ["stale-zone-delete", "pdf.37pla.net"])).toEqual({ path: "/api/zones/delete", params: { zone: "pdf.37pla.net" }, primaryOnly: false });
|
|
199
|
+
expect(technitiumRequest("cluster-catalog.dns.home.arpa", ["zone-catalog", "pdf.37pla.net"])).toEqual({
|
|
200
|
+
path: "/api/zones/options/set",
|
|
201
|
+
params: { zone: "pdf.37pla.net", catalog: "cluster-catalog.dns.home.arpa" },
|
|
202
|
+
primaryOnly: true,
|
|
203
|
+
});
|
|
198
204
|
expect(technitiumRequest("c", ["cluster-remove", "811905692"]).params).toEqual({ secondaryNodeId: "811905692" });
|
|
199
205
|
expect(technitiumRequest("c", ["server-domain", "technitium1"])).toEqual({ path: "/api/settings/set", params: { dnsServerDomain: "technitium1" }, primaryOnly: false });
|
|
200
206
|
});
|