DNS Documentation

This section contains product documentation for TitaniumGuard DNS.

For authoritative zone setup, see DNS Zone Hosting. For policy syntax and examples, see DNS Rule Engine Policy.

Run with Docker

The DNS image is published as:

• ghcr.io/titaniumguardlabs/source/dns:latest

The DNS process accepts --config <path> (or first positional path). Without an explicit path, it loads config.json from the current directory when present; otherwise it starts with local defaults. A missing explicit path and an invalid configuration fail startup.

The no-config profile listens on 127.0.0.1:5353, with health endpoints on 127.0.0.1:8081. It permits recursion only for loopback clients and disables audit logging. Query it with dig -p 5353 @127.0.0.1 example.com. The --allow-default-config flag remains accepted for compatibility but is no longer required for this local mode.

1. Create a local config file

Example ./dns-config.json:

{
  "listen_addr": "0.0.0.0:8080",
  "resolvers": ["1.1.1.1", "8.8.8.8"],
  "zones": []
}

2. Run container and mount config

Publish both UDP and TCP for DNS queries:

docker run --rm \
  -p 8080:8080/udp \
  -p 8080:8080/tcp \
  -v "$PWD/dns-config.json:/etc/titaniumguard/dns-config.json:ro" \
  ghcr.io/titaniumguardlabs/source/dns:latest \
  --config /etc/titaniumguard/dns-config.json --allow-open-policy

3. Query it

dig @127.0.0.1 -p 8080 example.com
dig @127.0.0.1 -p 8080 example.com +tcp

If UDP queries time out but TCP works, check that -p <host>:<container>/udp is present.