Skip to content

Commit ffd83e2

Browse files
Jonathan D.A. Jewellclaude
Jonathan D.A. Jewell
and
claude
committed
feat: initial scaffolding for Hesiod DNS service discovery
- Add README.adoc with HS-class DNS architecture - Define example Hesiod records - Part of FlatRacoon Network Stack 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
0 parents  commit ffd83e2

1 file changed

Lines changed: 208 additions & 0 deletions

File tree

‎README.adoc‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
// SPDX-License-Identifier: AGPL-3.0-or-later
2+
// SPDX-FileCopyrightText: 2025 Hyperpolymath <hyperpolymath@proton.me>
3+
= hesiod-dns-map
4+
:icons: font
5+
:toc: left
6+
:toclevels: 3
7+
8+
== Purpose
9+
10+
HS-class DNS zone files, Hesiod naming, and resource mapping for the FlatRacoon Network Stack.
11+
12+
Implements the Hesiod naming system (RFC 1535 adjacent) for service discovery and resource location within the private network.
13+
14+
Part of the link:https://github.com/hyperpolymath/flatracoon-netstack[FlatRacoon Network Stack].
15+
16+
== Architecture
17+
18+
[source]
19+
----
20+
┌─────────────────────────┐
21+
│ Hesiod DNS Server │
22+
│ (This Module) │
23+
│ ───────────────── │
24+
│ • HS class records │
25+
│ • Service location │
26+
│ • User/group mapping │
27+
└───────────┬─────────────┘
28+
│
29+
┌──────────────────┼──────────────────┐
30+
│ │ │
31+
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
32+
│ Services │ │ Users │ │ Resources │
33+
│ .service │ │ .passwd │ │ .filsys │
34+
└─────────────┘ └─────────────┘ └─────────────┘
35+
----
36+
37+
== What is Hesiod?
38+
39+
Hesiod is a DNS-based naming system developed at MIT's Project Athena. It uses the HS (Hesiod) DNS class to provide:
40+
41+
* **Service discovery** - Locate services by name
42+
* **User information** - passwd/group lookups via DNS
43+
* **Resource mapping** - Mount points, printers, etc.
44+
* **Configuration distribution** - Centralized config via DNS
45+
46+
== Components
47+
48+
* **HS-class zone files** - Hesiod DNS records
49+
* **Service registry** - FlatRacoon service locations
50+
* **User/group mapping** - Integration with authentication
51+
* **Resource definitions** - Storage, compute, network resources
52+
* **Dynamic updates** - RFC 2136 compliant updates
53+
54+
== Directory Structure
55+
56+
[source]
57+
----
58+
hesiod-dns-map/
59+
├── zones/
60+
│ ├── flatracoon.hs # Main Hesiod zone
61+
│ ├── service.hs # Service locations
62+
│ ├── passwd.hs # User mappings
63+
│ ├── group.hs # Group mappings
64+
│ └── filsys.hs # Filesystem mappings
65+
├── configs/
66+
│ ├── named.ncl # BIND/Knot configuration
67+
│ ├── hesiod.ncl # Hesiod-specific settings
68+
│ └── dynamic.ncl # Dynamic update policies
69+
├── scripts/
70+
│ ├── generate-zones.sh # Zone file generation
71+
│ ├── update-service.sh # Service registration
72+
│ └── sync-users.sh # User sync from LDAP/AD
73+
├── manifests/
74+
│ ├── deployment.yaml
75+
│ └── service.yaml
76+
├── Justfile
77+
├── README.adoc
78+
├── STATE.scm
79+
├── META.scm
80+
└── ECOSYSTEM.scm
81+
----
82+
83+
== Inputs
84+
85+
[cols="1,2,1"]
86+
|===
87+
| Input | Description | Source
88+
89+
| Service registry
90+
| Service name → address mappings
91+
| FlatRacoon modules
92+
93+
| User database
94+
| User/group information
95+
| LDAP/AD or local
96+
97+
| Resource definitions
98+
| Storage and compute resources
99+
| Infrastructure config
100+
101+
| Zone configuration
102+
| DNS zone parameters
103+
| configs/hesiod.ncl
104+
|===
105+
106+
== Outputs
107+
108+
[cols="1,2"]
109+
|===
110+
| Output | Description
111+
112+
| HS-class DNS server
113+
| Hesiod-enabled DNS resolver
114+
115+
| Service discovery
116+
| `host -t TXT twingate.service.flatracoon HS`
117+
118+
| User lookups
119+
| `hesinfo username passwd`
120+
121+
| Resource mapping
122+
| Mount points, printers, etc.
123+
|===
124+
125+
== Example Hesiod Records
126+
127+
=== Service Location
128+
[source,dns]
129+
----
130+
; Service: twingate
131+
twingate.service HS TXT "twingate-connector.default.svc.cluster.local:443"
132+
133+
; Service: ipfs-gateway
134+
ipfs-gateway.service HS TXT "ipfs-gateway.ipfs.svc.cluster.local:8080"
135+
136+
; Service: zerotier-api
137+
zerotier-api.service HS TXT "zerotier-api.zerotier.svc.cluster.local:9993"
138+
----
139+
140+
=== User Information
141+
[source,dns]
142+
----
143+
; User: admin
144+
admin.passwd HS TXT "admin:*:1000:1000:Admin User:/home/admin:/bin/bash"
145+
146+
; Group: operators
147+
operators.group HS TXT "operators:*:1001:admin,user1,user2"
148+
----
149+
150+
=== Filesystem Mapping
151+
[source,dns]
152+
----
153+
; Mount: ipfs-data
154+
ipfs-data.filsys HS TXT "AFS /afs/flatracoon/ipfs rw"
155+
----
156+
157+
== Integration Points
158+
159+
=== With FlatRacoon Stack
160+
161+
* **All modules** - Service discovery via Hesiod
162+
* **twingate-helm-deploy** - Registered as service
163+
* **ipfs-overlay** - Bootstrap nodes via Hesiod
164+
* **network-dashboard** - DNS health monitoring
165+
166+
=== Machine-Readable Manifest
167+
168+
[source,json]
169+
----
170+
{
171+
"module": "hesiod-dns-map",
172+
"version": "0.1.0",
173+
"layer": "naming",
174+
"requires": ["bind", "kubernetes"],
175+
"provides": ["hesiod-dns", "service-discovery", "user-lookup"],
176+
"config_schema": "configs/schema.ncl",
177+
"health_endpoint": "/dns/health",
178+
"metrics_endpoint": "/dns/metrics"
179+
}
180+
----
181+
182+
== Quick Start
183+
184+
[source,bash]
185+
----
186+
# 1. Generate zone files from registry
187+
just generate-zones
188+
189+
# 2. Deploy Hesiod DNS server
190+
just deploy
191+
192+
# 3. Test service discovery
193+
just query twingate.service
194+
195+
# 4. Register new service
196+
just register-service myapp 10.0.0.50:8080
197+
----
198+
199+
== Status
200+
201+
[horizontal]
202+
Phase:: Scaffolding
203+
Completion:: 5%
204+
Next:: Zone file templates and BIND configuration
205+
206+
== License
207+
208+
AGPL-3.0-or-later

0 commit comments

Comments
 (0)