Skip to content

DNS-SETUP.md

Latest commit

 

History

History
254 lines (181 loc) · 6.09 KB

DNS-SETUP.md

File metadata and controls

254 lines (181 loc) · 6.09 KB
Raw

DNS Setup Guide

This guide explains how to configure your system or network to resolve .tpt names using the TFEP DNS bridge, and how to deploy the bridge as an authoritative nameserver for the .tpt TLD.

Overview

The TFEP DNS bridge is a lightweight authoritative DNS server embedded in the gateway. It answers queries for .tpt names synthetically from the registry database, and forwards all other queries to an upstream resolver (default: Cloudflare 1.1.1.1:53).

There are two ways to use the bridge:

Mode Use case
Local resolver Point your machine or LAN at the bridge to resolve .tpt names during development or testing
Public authoritative server Delegate the .tpt TLD to the bridge so anyone on the internet can resolve .tpt names

Quick Start (Local Development)

1. Start the gateway with DNS bridge enabled:

# config.yaml
registry:
  enabled: true
  tld: tpt

dns_bridge:
  enabled: true
  listen_addr: ":5353"     # non-privileged port for development
  upstream: "1.1.1.1:53"
  gateway_ip: "127.0.0.1"  # your local gateway IP
tfep-gateway serve

2. Test resolution directly:

# Should return the TFEP TXT record for any registered name
dig @127.0.0.1 -p 5353 alice.tpt TXT
dig @127.0.0.1 -p 5353 _tfep.alice.tpt TXT
dig @127.0.0.1 -p 5353 alice.tpt A

3. Point your OS resolver at the bridge:

Windows

Open Network adapter settings → IPv4 properties → set DNS to 127.0.0.1.

Or for a per-process test:

# Add a custom host entry (not DNS, but works for A records)
Add-Content C:\Windows\System32\drivers\etc\hosts "127.0.0.1 alice.tpt"

For full DNS override, use the gateway on port 53 (requires admin):

dns_bridge:
  listen_addr: ":53"

Then in Network Settings → DNS, set primary DNS to 127.0.0.1.

macOS

# Create a resolver file for the .tpt TLD only
sudo mkdir -p /etc/resolver
echo "nameserver 127.0.0.1
port 5353" | sudo tee /etc/resolver/tpt

Verify:

scutil --dns | grep tpt
dig alice.tpt TXT   # should now work without -p 5353

Linux (systemd-resolved)

# /etc/systemd/resolved.conf.d/tpt.conf
[Resolve]
DNS=127.0.0.1:5353
Domains=~tpt
sudo systemctl restart systemd-resolved
resolvectl dns       # verify
dig alice.tpt TXT

Linux (dnsmasq / Pi-hole)

Add to /etc/dnsmasq.conf:

server=/tpt/127.0.0.1#5353

Restart dnsmasq. All .tpt queries now route to the bridge.

DNS-over-TLS (DoT)

To enable DoT (RFC 7858), provide a TLS cert+key and a DoT listen address:

tls:
  cert_file: "/etc/tfep/cert.pem"
  key_file:  "/etc/tfep/key.pem"

dns_bridge:
  enabled: true
  listen_addr: ":53"
  dot_addr:    ":853"    # standard DoT port
  gateway_ip:  "203.0.113.1"

Test with kdig (from knot-dns):

kdig @127.0.0.1 -p 853 +tls alice.tpt TXT

Or with dog:

dog alice.tpt TXT --tls @127.0.0.1:853

Production Deployment (Public Authoritative Server)

To make .tpt names resolvable globally:

Prerequisites

  • A public IP address for your gateway server
  • A domain under which you'll host the nameserver (e.g. ns1.yourgateway.example)
  • The gateway TLS certificate (for DoT and DNSSEC if applicable)

Step 1 — Configure the bridge for port 53

dns_bridge:
  enabled: true
  listen_addr:  ":53"
  dot_addr:     ":853"
  gateway_ip:   "203.0.113.1"   # your server's public IPv4
  gateway_ipv6: "2001:db8::1"   # your server's public IPv6 (optional)
  ns_hostname:  "ns1.tpt."
  soa_email:    "hostmaster.tpt."
  upstream:     "1.1.1.1:53"

Step 2 — Firewall rules

Allow inbound UDP and TCP on port 53 (and TCP on 853 for DoT):

# iptables
iptables -A INPUT -p udp --dport 53 -j ACCEPT
iptables -A INPUT -p tcp --dport 53 -j ACCEPT
iptables -A INPUT -p tcp --dport 853 -j ACCEPT

Step 3 — Delegation

Contact the IANA or the registrar for the .tpt TLD (or a test TLD you control) to delegate nameserver authority:

tpt.   NS   ns1.tpt.
ns1.tpt.   A    203.0.113.1

For internal/private deployments (e.g. corporate intranet), configure your existing DNS resolver (Bind, Unbound, CoreDNS) to forward .tpt queries to the bridge:

Unbound:

forward-zone:
  name: "tpt."
  forward-addr: 203.0.113.1@53

CoreDNS:

tpt.:53 {
  forward . 203.0.113.1:53
}

BIND (named.conf.local):

zone "tpt" {
  type forward;
  forwarders { 203.0.113.1; };
};

Step 4 — Verify

# From an external machine using a standard resolver
dig alice.tpt TXT @203.0.113.1
dig _tfep.alice.tpt TXT
dig alice.tpt A
dig tpt. SOA

DNSSEC

The current bridge does not sign responses with DNSSEC. Clients that require DNSSEC (identity.require_dnssec: true) will log a warning for .tpt names served by the bridge. This is a known limitation of the reference implementation.

DNSSEC signing is planned for a future release. Until then, the bridge's trust model relies on the DID document's Ed25519 signature chain rather than DNSSEC.

Browser Extension (Automatic .tpt Resolution)

The TPT Identity browser extension handles .tpt navigation automatically by intercepting browser navigation events and querying the registry API. No OS-level DNS changes are required to use the extension.

To configure the extension to use your gateway:

  1. Click the TPT Identity toolbar button
  2. Click Settings
  3. Set Registry / Gateway URL to your gateway address (e.g. https://gateway.example.com)
  4. Click Save Settings

Troubleshooting

Problem Solution
dig returns SERVFAIL Check that the bridge is running and that the port is not blocked by firewall
Name resolves but returns wrong IP Verify gateway_ip in config and reload the gateway
DoT connection refused Ensure dot_addr is set and a valid TLS cert+key is configured
OS ignores custom resolver On macOS, flush the DNS cache: sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
.tpt names not resolving in browser Use the browser extension (see above) or configure OS-level DNS override