dns-config

# dns-config

View and validate the local-dns-override hosts.yaml configuration.

## When to use

- Checking what records are currently loaded
- Validating a new hosts.yaml before saving it
- Understanding the full config file format
- Debugging why a hostname is not resolving as expected

## hosts.yaml full format reference

```yaml
# Optional: override the upstream DNS resolver
# Format: host:port
# Default: 8.8.8.8:53
upstream: 8.8.8.8:53

records:
  - hostname: api.local        # required: non-empty string
    type: A                    # required: A | AAAA | CNAME
    value: 127.0.0.1           # required: IPv4 / IPv6 / hostname
    ttl: 60                    # optional: seconds, default 60

  - hostname: "*.dev.local"    # wildcard: quote the string in YAML
    type: A
    value: 127.0.0.1

  - hostname: www.api.local
    type: CNAME
    value: api.local           # CNAME value must be a valid hostname
```

## Show current loaded config via CLI

```bash
node dist/dns-server.js config
node dist/dns-server.js config --config /path/to/hosts.yaml
```

## Show config via API

```bash
# Full config object
curl -s http://127.0.0.1:5380/api/config | jq .

# Just the records array
curl -s http://127.0.0.1:5380/api/config | jq '.records'

# Count of records
curl -s http://127.0.0.1:5380/api/config | jq '.records | length'

# Find all wildcard records
curl -s http://127.0.0.1:5380/api/config | jq '[.records[] | select(.hostname | startswith("*"))]'
```

## Validate before applying

```bash
# Dry-run validation (exit 0 = valid, exit 1 = errors printed)
node dist/dns-server.js config --validate-only --config ./hosts.yaml
```

## Config API response shape

```json
{
  "upstream": "8.8.8.8:53",
  "configPath": "./hosts.yaml",
  "loadedAt": "2026-03-20T15:53:10Z",
  "records": [
    {
      "hostname": "api.local",
      "type": "A",
      "value": "127.0.0.1",
      "ttl": 60,
      "wildcard": false
    },
    {
      "hostname": "*.dev.local",
      "type": "A",
      "value": "127.0.0.1",
      "ttl": 60,
      "wildcard": true
    }
  ]
}
```

## Environment variables that affect config loading

| Variable       | Effect                                  |
|----------------|-----------------------------------------|
| `DNS_CONFIG`   | Path to hosts.yaml (default: ./hosts.yaml) |
| `UPSTREAM_DNS` | Override upstream field in YAML         |

## Common validation errors

| Error message | Fix |
|---|---|
| `record[N].value: not a valid IPv4` | Check IPv4 format - must be 4 octets 0-255 |
| `record[N].hostname: empty` | hostname field is required and non-empty |
| `record[N].type: unknown` | type must be exactly A, AAAA, or CNAME |
| `upstream: invalid format` | upstream must be host:port format |
| `path traversal detected` | config path must not escape the project root |