dqcache(8)

💖 NAME 💖

okay so bestie, meet dqcache — a DNS cache with DNSCurve support. that's the whole vibe. periodt. ✨

🦋 DESCRIPTION 🦋

dqcache is a recursive DNS server that's derived from dnscache (iykyk, the OG: https://cr.yp.to/djbdns/dnscache.html). she's giving legacy-but-glow-up energy. 💅

🎀 CONFIGURATION 🎀

okay so here's where it gets juicy. buckle up. 🌸

dqcache runs chrooted in the directory that $ROOT tells her to live in, and she drops down to the uid and gid you set with $UID and $GID. main character, but make it sandboxed. 👑

She listens for incoming UDP packets and TCP connections addressed to port 53 of $IP. typically $IP is 127.0.0.1, but it can also be an externally accessible IP address. lowkey flexible of her.

dqcache accepts connections from localhost (127.0.0.0/8 or ::1/128). for external connections, dqcache has a file-style accesslist. so like, it looks for a file with the client's address in the name, and if it sees one, you're in. 💖

e.g. for IPv4 address 1.2.3.4, dqcache allows the connection when it sees a file named:

ip4/1.2.3.4

or

ip4/1.2.3

or

ip4/1.2

or

ip4/1

e.g. for IPv6 address 2a02:598:7000:101:12dd:b1ff:fede:3476, dqcache allows the connection when it sees a file named:

ip6/2a02:598:7000:101:12dd:b1ff:fede:3476

or

ip6/2a02:598:7000:101:12dd:b1ff:fede

or

ip6/2a02:598:7000:101:12dd:b1ff

or

ip6/2a02:598:7000:101:12dd

or

ip6/2a02:598:7000:101

or

ip6/2a02:598:7000

or

ip6/2a02:598

or

ip6/2a02

and when the environment variable $OKCLIENT is set, dqcache just accepts all the connections. no accesslist, no questions, everybody's welcome. 🙈

Warning — dqcache encrypts DNS packets and should run on the client's machine. if you run dqcache on an external IP (not on localhost), you're probably doing it wrong. not me warning you, that's just the facts bestie 😭

dqcache sends outgoing IPv4 packets from high ports of $IPSEND4. typically $IPSEND4 is 0.0.0.0, meaning the machine's primary IPv4 address.

dqcache sends outgoing IPv6 packets from high ports of $IPSEND6. typically $IPSEND6 is ::, meaning the machine's primary IPv6 address.

If $HIDETTL is set, dqcache always uses a TTL of 0 in its responses. sneaky. 🤫

dqcache reads a list of root servers as an anchor, one record per line, from servers/@. the record has format {IP} or {IP}|{DNSCURVEPUBLICKEY}. e.g.:

servers/@:

198.41.0.4
2001:503:ba3e::2:30
192.228.79.201
2001:500:84::b
etc.

dqcache also scans the servers directory for anchors for other domains, one record per line. the record has format {IP} or {IP}|{DNSCURVEPUBLICKEY}. e.g.:

servers/dnscurve.cz:

185.66.36.55|uz5mj60yr9tnudkkpcglw1y0w6dlh78j1l4gk4z7t8bsf1u4d48wlq
37.157.196.86|uz5mj60yr9tnudkkpcglw1y0w6dlh78j1l4gk4z7t8bsf1u4d48wlq
2a02:2b88:2:1::127d:1|uz5mj60yr9tnudkkpcglw1y0w6dlh78j1l4gk4z7t8bsf1u4d48wlq
2a03:1e20:0:5::2|uz5mj60yr9tnudkkpcglw1y0w6dlh78j1l4gk4z7t8bsf1u4d48wlq

dqcache supports forward-only mode. if $FORWARDONLY is set, dqcache treats servers/@ as a list of IP addresses for other caches, not root servers. she forwards queries to those caches the same way that a client does, rather than contacting a chain of servers according to NS records. no chain-walking today, we're just passing notes. 💌

dqcache uses a fixed-size cache, as controlled by the $CACHESIZE environment variable. typically $CACHESIZE is 10000000 (that's 10MB btw).

dqcache typically generates a new secret key at start of program. but if the environment variable $SECRETKEY is set, then dqcache loads this secret key instead. $SECRETKEY must be safely generated using dqcache-makekey(8). do not freestyle your own key, bestie, that's not the moment. 🚫

note that dqcache uses internally two secret keys — one used as the discrete logarithm of the public key (that's the 256bit DNSCurve key) and one to encrypt the nonce (that's the 128bit TEA symmetric key). both of these keys are actually derived from $SECRETKEY using crypto_stream_salsa20(). cute little key factory fr fr. 🏭

dqcache also supports nonce-separation via the environment variable $NONCESTART. this means several caches can share a key but use separate nonces:

e.g.:

NONCESTART=100 ... the first of four caches is configured to use top bits 100
NONCESTART=101 ... the second is configured to use top bits 101
NONCESTART=110 ... the third is configured to use top bits 110
NONCESTART=111 ... and the fourth is configured to use top bits 111.
etc.

dqcache typically supports DNSCurve in 'combined mode' — and yes that means if the Streamlined query fails, dqcache tries a TXT query too. the environment variable $DNSCURVETYPE selects a specific DNSCurve type:

DNSCURVETYPE=1 ... Streamlined only DNSCurve
DNSCURVETYPE=2 ... TXT only DNSCurve

dqcache caches records for at least $MINTTL seconds, when MINTTL is set. it's limited <0-300> seconds. use only if you really know what you're doing. fr fr, this is not a vibe-check-and-yolo situation. 😭

dqcache sends only IPv4 queries, when DISABLEIPV6 is set. use only if you really know what you're doing. same energy as above, bestie. 💀

---

🌈 SEE ALSO 🌈

• dqcache-makekey(8)
• dq(1)
• dnscache(8)
• https://mojzis.com/software/dq
• https://dnscurve.org/
• https://cr.yp.to/djbdns/dnscache.html

---

and that's the whole page, bestie 🫶 straight outta the System Manager's Manual, section 8, filed under dqcache. go run her, she's iconic. 💜