local-dns

# local-dns

Add hostname-to-IP mappings for development environments.

## When to use

- Making `api.local` resolve to `127.0.0.1` so local services respond to readable names
- Adding a wildcard `*.dev.local` that catches any subdomain
- Testing that a hostname resolves correctly through the local DNS server
- Looking up what IP a configured hostname returns

## Add a record via hosts.yaml

Edit `hosts.yaml` and add to the `records` array:

```yaml
records:
  # A record - maps hostname to IPv4
  - hostname: api.local
    type: A
    value: 127.0.0.1

  # Wildcard - matches any subdomain of dev.local
  - hostname: "*.dev.local"
    type: A
    value: 127.0.0.1

  # CNAME - alias one hostname to another
  - hostname: www.api.local
    type: CNAME
    value: api.local

  # AAAA record - maps hostname to IPv6
  - hostname: api.local
    type: AAAA
    value: ::1

  # Custom TTL (default is 60 seconds)
  - hostname: cache.local
    type: A
    value: 10.0.0.5
    ttl: 300
```

The server hot-reloads on file change - no restart needed.

## Trigger a manual reload via API

```bash
curl -s -X POST http://127.0.0.1:5380/api/reload
# Response: { "ok": true, "records": 9, "reloadedAt": "2026-03-20T15:53:10Z" }
```

## Test a hostname via CLI

```bash
# Test A record
node dist/dns-server.js test api.local

# Test CNAME resolution
node dist/dns-server.js test www.api.local --type CNAME

# Test using dig (port 5353 if not running on 53)
dig @127.0.0.1 -p 5353 api.local A
dig @127.0.0.1 -p 5353 api.local AAAA
dig @127.0.0.1 -p 5353 www.api.local CNAME
```

## View current records via API

```bash
curl -s http://127.0.0.1:5380/api/config | jq '.records'
```

## Supported record types

| Type  | Value             | Use case                      |
|-------|-------------------|-------------------------------|
| A     | IPv4 (1.2.3.4)    | Map hostname to IPv4          |
| AAAA  | IPv6 (::1)        | Map hostname to IPv6          |
| CNAME | Hostname target   | Alias one hostname to another |

## Wildcard matching rules

- Only `*.prefix.local` form is supported
- A wildcard matches exactly one subdomain level: `*.dev.local` matches `foo.dev.local` but not `a.b.dev.local`
- Exact matches take priority over wildcards

## Troubleshooting

### Hostname still not resolving

Check that `127.0.0.1` (or `127.0.0.1:5353`) is set as your system DNS resolver. The local-dns-override server must be the first resolver consulted.

### Record added but not resolving

1. Check that the server reloaded: `curl http://127.0.0.1:5380/api/config`
2. Check the query log for NXDOMAIN: `curl http://127.0.0.1:5380/api/log?limit=10`
3. Verify YAML syntax is valid: `node dist/dns-server.js config`