Resolver · XB Field Notes

dnsmasq separates forwarded cache entries from configured local names

Sat, 15 Apr 2028 00:00:00 +0000

dnsmasq can forward DNS questions upstream, retain supported answers in a bounded cache, and serve names configured locally. These are different sources of data. A repeated answer may be a cache hit or a local configuration result. Establishing which source supplied it is essential when a hostname disagrees with the authority or continues resolving after a cache flush.

When it breaks

Starting dnsmasq does not automatically make every application use it. Clients must direct their DNS queries through the intended listener, and some applications use other resolvers. Likewise, a correct local listener can forward to the wrong upstream or read unexpected host configuration. Diagnose the actual query path before enlarging the cache or restarting a daemon that never received the failing query.

A local name can deliberately override upstream data. Clearing the forwarding cache does not delete that configured name, so repeated flushing cannot make the upstream address win. Treat a local record as configuration with an owner and purpose. An answer with local TTL zero can still be returned repeatedly because dnsmasq generates it from configuration rather than retaining a forwarded response.

Cache capacity and freshness solve different problems. A larger cache can retain more eligible entries, but it does not extend their valid TTLs or make every possible query answerable during an upstream outage. New names and expired entries still need the appropriate resolution path. Cache-size tuning also does not directly specify the maximum number of simultaneous upstream queries or reserve application-level availability.

Check it quickly

Save the script as check-dnsmasq.py and run python3 check-dnsmasq.py with Docker. The pinned environment uses dnsmasq 2.90 and BIND 9.18.49. The test forwarders ignore ambient resolver and hosts files, bind explicit loopback listeners, and forward only to the disposable authority. They publish no host ports and use no DHCP configuration:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid
recipe='FROM python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84\nRUN apt-get update && apt-get install -y --no-install-recommends bind9=1:9.18.49-1~deb12u2 bind9-dnsutils=1:9.18.49-1~deb12u2 dnsmasq-base=2.90-4~deb12u2 python3-dnspython=2.3.0-1 && rm -rf /var/lib/apt/lists/*\nCMD ["/usr/bin/python3"]\n'
program=r"""
from contextlib import ExitStack,contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import json,re,signal,subprocess,time
import dns.exception,dns.message,dns.query,dns.rcode,dns.rdatatype

def run(*args,check=True):
 result=subprocess.run(args,capture_output=True,text=True,timeout=15)
 if check:assert result.returncode==0,(args,result.returncode,result.stdout,result.stderr)
 return result
def query(name,kind='A',port=1053):
 return dns.query.udp(dns.message.make_query(name,kind),'127.0.0.1',port=port,timeout=1)
def values(response,kind='A'):
 wanted=dns.rdatatype.from_text(kind)
 return [item.to_text() for rrset in response.answer if rrset.rdtype==wanted for item in rrset]
def show(response):
 def section(records):return [{'name':str(rr.name),'type':dns.rdatatype.to_text(rr.rdtype),'ttl':rr.ttl,'data':[item.to_text() for item in rr]} for rr in records]
 return {'rcode':dns.rcode.to_text(response.rcode()),'answer':section(response.answer),'authority':section(response.authority)}
def wait(predicate,timeout=15):
 deadline=time.monotonic()+timeout
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except (OSError,dns.exception.Timeout):pass
 time.sleep(.05)
 raise AssertionError('DNS fixture condition did not become true')
def stop(process):
 if process.poll() is None:
 process.terminate()
 try:process.wait(timeout=5)
 except subprocess.TimeoutExpired:process.kill();process.wait(timeout=5)

@contextmanager
def lab(records,soa_ttl=8,minimum=4,extra=''):
 with TemporaryDirectory(prefix='xbcatm-dns-') as directory,ExitStack() as stack:
 root=Path(directory);zone=root/'zone';conf=root/'named.conf';log=root/'named.log';serial=1
 def save(body):
 zone.write_text(f'$ORIGIN lab.test.\n$TTL 30\n@ {soa_ttl} IN SOA ns.lab.test. hostmaster.lab.test. ({serial} 60 60 3600 {minimum})\n@ IN NS ns.lab.test.\nns IN A 127.0.0.1\n'+body+'\n')
 run('named-checkzone','lab.test',str(zone))
 save(records)
 conf.write_text(f'''options {{ directory "{root}"; listen-on port 1053 {{127.0.0.1;}}; listen-on-v6 {{none;}};
recursion no; dnssec-validation no; notify no; querylog yes; max-cache-size 8m; pid-file "{root}/named.pid"; session-keyfile none;
{extra} }};
controls {{}};
zone "lab.test" {{ type primary; file "{zone}"; }};
''')
 run('named-checkconf',str(conf))
 output=stack.enter_context(log.open('w'))
 authority=subprocess.Popen(['named','-g','-c',str(conf),'-n','1','-U','1'],stdout=output,stderr=subprocess.STDOUT)
 stack.callback(stop,authority)
 def ready():
 assert authority.poll() is None,log.read_text()
 response=query('lab.test.','SOA');return response.rcode()==0 and response.answer[0][0].serial==serial
 wait(ready)
 def update(body):
 nonlocal serial
 serial+=1;save(body);authority.send_signal(signal.SIGHUP);wait(ready)
 def cache(port=1054,upstream=1053,size=150,options=()):
 logfile=root/('cache-'+str(port)+'.log');stream=stack.enter_context(logfile.open('w'))
 command=['dnsmasq','--no-daemon','--conf-file=/dev/null','--no-resolv','--no-hosts','--bind-interfaces',
 '--listen-address=127.0.0.1','--port='+str(port),'--server=127.0.0.1#'+str(upstream),
 '--cache-size='+str(size),'--log-queries','--log-facility=-',*options]
 process=subprocess.Popen(command,stdout=stream,stderr=subprocess.STDOUT);stack.callback(stop,process)
 def cache_ready():
 assert process.poll() is None,logfile.read_text()
 return query('lab.test.','SOA',port).rcode()==0
 wait(cache_ready);return process,logfile
 def queries(name,kind='A'):
 return sum(bool(re.search(r'query: '+re.escape(name.rstrip('.'))+r' IN '+kind+r'\b',line)) for line in log.read_text().splitlines())
 yield root,update,cache,queries
with lab('cached 20 IN A 127.0.0.2\nuncached 20 IN A 127.0.0.3\nlocal 20 IN A 127.0.0.4') as (_,update,cache,queries):
 daemon,log=cache(options=('--host-record=local.lab.test,127.0.0.9',))
 for _ in range(3):assert values(query('cached.lab.test.',port=1054))==['127.0.0.2']
 wait(lambda: queries('cached.lab.test')==1)
 cache(port=1055,size=0)
 for _ in range(3):assert values(query('uncached.lab.test.',port=1055))==['127.0.0.3']
 wait(lambda: queries('uncached.lab.test')==3)
 local=query('local.lab.test.',port=1054);assert values(local)==['127.0.0.9'] and local.answer[0].ttl==0
 assert queries('local.lab.test')==0
 authoritative=query('local.lab.test.');assert values(authoritative)==['127.0.0.4']
 wait(lambda: queries('local.lab.test')==1)
 update('cached 20 IN A 127.0.0.8\nuncached 20 IN A 127.0.0.3\nlocal 20 IN A 127.0.0.4')
 stale=query('cached.lab.test.',port=1054);assert values(stale)==['127.0.0.2'] and queries('cached.lab.test')==1
 previous=log.read_text().count('cleared cache');daemon.send_signal(signal.SIGHUP)
 wait(lambda: log.read_text().count('cleared cache')>previous)
 refreshed=query('cached.lab.test.',port=1054);assert values(refreshed)==['127.0.0.8']
 wait(lambda: queries('cached.lab.test')==2)
 retained=query('local.lab.test.',port=1054);assert values(retained)==['127.0.0.9']
 print(json.dumps({'three_lookups_upstream_counts':{'cache_enabled':1,'cache_disabled':3},'local_record':show(local),
 'same_name_authority':show(authoritative),'before_SIGHUP':show(stale),'after_SIGHUP':show(refreshed),
 'configured_local_record_retained':show(retained)},sort_keys=True))
"""
name='xbcatm-dns-'+uuid.uuid4().hex[:10]
def docker(*args,**kwargs):return subprocess.run(['docker',*args],capture_output=True,text=True,timeout=300,**kwargs)
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'Dockerfile').write_text(recipe)
 built=docker('build','-t',name,str(root));assert built.returncode==0,built.stderr
 result=docker('run','--rm','-i','--name',name,'--network','none','--memory','384m','--pids-limit','128',name,
 '/usr/bin/python3','-',input=program)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),sort_keys=True))
finally:
 docker('rm','-f',name);docker('image','rm',name)

Three queries for cached.lab.test through the cache-enabled listener all return 127.0.0.2, while the authoritative log records one query. A second listener uses cache-size=0. Three queries for a separate name through it generate three upstream queries. This directly verifies the cache’s effect on forwarding work; the experiment does not infer hits from response speed or assert a particular latency improvement.

The first listener also has host-record=local.lab.test,127.0.0.9. Its answer is 127.0.0.9 with TTL zero, and no upstream query is logged for that lookup. A direct authoritative query for the same name returns 127.0.0.4 and increments the authority’s counter. The differing results show an explicit local override, with a positive control confirming that the query counter detects real upstream traffic.

Next, the authority changes cached.lab.test to 127.0.0.8. The cache still returns its earlier 127.0.0.2 answer within the remaining TTL. The script sends SIGHUP to this specific dnsmasq process and waits for its cache-cleared log entry. The following query reaches the authority and returns 127.0.0.8, increasing the corresponding authoritative count from one to two.

After that same signal, local.lab.test continues returning the configured 127.0.0.9 value. The signal clears forwarded cache state while leaving the explicitly configured local record available. This is why “flush DNS” is incomplete troubleshooting advice: the expected result depends on which process owns which data, and whether that data is cached, configured, or stored somewhere else entirely.

Operate the listener and its data sources deliberately

Inspect the effective configuration, listener address, upstream destinations, and client settings together. Avoid creating a forwarding loop between two local resolvers. The example removes ambient inputs to isolate behavior; a real installation may intentionally use hosts files, DHCP leases, or resolver-management software. Record those dependencies so an automatic rewrite or a local override is visible during troubleshooting.

For dnsmasq, SIGHUP clears its cache and reloads certain data sources described by the manual, but it does not generally reread the main configuration file. Use the documented service procedure for the kind of change being made. A successful cache clear cannot be treated as proof that edited listener, forwarding, or other startup configuration has been activated.

Limit listener exposure to intended clients, especially when forwarding recursion on a reachable network. DHCP, DNSSEC validation, and encrypted upstream transport require their own configuration and verification; none is demonstrated by this cache experiment. Query logging is useful during diagnosis but can reveal client naming activity, so select its scope and retention according to the environment rather than leaving detailed logs indefinitely by habit.

Finally, compare cached answers with the authority when it is the expected source. For a configured local name, compare against its configuration. Track upstream failures, hits, and entry churn separately. Identify whether the discrepancy concerns capacity, lifetime, the upstream service, or a local naming rule.

Sources

dnsmasq manual, forwarding, cache-size, host-record, local TTL, and SIGHUP behavior, checked 2026-09-12.
RFC 1035 domain names, DNS resource records and cached lifetimes, checked 2026-09-12.

DNS TTL trades repeated upstream queries against retained answers

Wed, 01 Mar 2028 00:00:00 +0000

A DNS TTL is a lifetime attached to cached data, not a refresh job scheduled for every second. A cache can reuse a valid answer while it retains that entry. After expiry, a subsequent request usually requires fresh resolution unless another configured behavior applies. An idle record need not produce an upstream query merely because its TTL has reached zero.

When it breaks

Shortening TTL increases potential upstream work when clients keep asking for the same data. It does not multiply all authoritative traffic by one universal factor: query frequency, resolver sharing, cache capacity, prefetching, and record diversity affect the result. A short TTL on one popular name behaves differently from a large stream of names that are each queried only once.

A long TTL permits continued use of an answer after the authority changes its data. That cached answer may still be valid under the lifetime originally received even though it no longer matches the newest zone content. Calling every mismatch an expired or broken cache obscures the actual contract. TTL expresses permitted retention; it does not promise continuous synchronization with the authority.

Multiple forwarding layers do not ordinarily receive a fresh copy of the original TTL at every hop. A cache returns remaining lifetime, which the next cache then ages. Adding full TTLs per layer invents a propagation delay that ordinary compliant forwarding does not create. Local TTL overrides and serve-stale policies are separate behaviors that should be identified explicitly when present.

Check it quickly

Save this as check-ttl-cost.py and run python3 check-ttl-cost.py with Docker. The pinned container uses BIND 9.18.49 and dnsmasq 2.90, with no external runtime network. The authoritative server logs actual queries. One forwarder initially serves two names, and the script later starts a second forwarder behind the first to inspect the TTL handed downstream:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid
recipe='FROM python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84\nRUN apt-get update && apt-get install -y --no-install-recommends bind9=1:9.18.49-1~deb12u2 bind9-dnsutils=1:9.18.49-1~deb12u2 dnsmasq-base=2.90-4~deb12u2 python3-dnspython=2.3.0-1 && rm -rf /var/lib/apt/lists/*\nCMD ["/usr/bin/python3"]\n'
program=r"""
from contextlib import ExitStack,contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import json,re,signal,subprocess,time
import dns.exception,dns.message,dns.query,dns.rcode,dns.rdatatype

def run(*args,check=True):
 result=subprocess.run(args,capture_output=True,text=True,timeout=15)
 if check:assert result.returncode==0,(args,result.returncode,result.stdout,result.stderr)
 return result
def query(name,kind='A',port=1053):
 return dns.query.udp(dns.message.make_query(name,kind),'127.0.0.1',port=port,timeout=1)
def values(response,kind='A'):
 wanted=dns.rdatatype.from_text(kind)
 return [item.to_text() for rrset in response.answer if rrset.rdtype==wanted for item in rrset]
def show(response):
 def section(records):return [{'name':str(rr.name),'type':dns.rdatatype.to_text(rr.rdtype),'ttl':rr.ttl,'data':[item.to_text() for item in rr]} for rr in records]
 return {'rcode':dns.rcode.to_text(response.rcode()),'answer':section(response.answer),'authority':section(response.authority)}
def wait(predicate,timeout=15):
 deadline=time.monotonic()+timeout
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except (OSError,dns.exception.Timeout):pass
 time.sleep(.05)
 raise AssertionError('DNS fixture condition did not become true')
def stop(process):
 if process.poll() is None:
 process.terminate()
 try:process.wait(timeout=5)
 except subprocess.TimeoutExpired:process.kill();process.wait(timeout=5)

@contextmanager
def lab(records,soa_ttl=8,minimum=4,extra=''):
 with TemporaryDirectory(prefix='xbcatm-dns-') as directory,ExitStack() as stack:
 root=Path(directory);zone=root/'zone';conf=root/'named.conf';log=root/'named.log';serial=1
 def save(body):
 zone.write_text(f'$ORIGIN lab.test.\n$TTL 30\n@ {soa_ttl} IN SOA ns.lab.test. hostmaster.lab.test. ({serial} 60 60 3600 {minimum})\n@ IN NS ns.lab.test.\nns IN A 127.0.0.1\n'+body+'\n')
 run('named-checkzone','lab.test',str(zone))
 save(records)
 conf.write_text(f'''options {{ directory "{root}"; listen-on port 1053 {{127.0.0.1;}}; listen-on-v6 {{none;}};
recursion no; dnssec-validation no; notify no; querylog yes; max-cache-size 8m; pid-file "{root}/named.pid"; session-keyfile none;
{extra} }};
controls {{}};
zone "lab.test" {{ type primary; file "{zone}"; }};
''')
 run('named-checkconf',str(conf))
 output=stack.enter_context(log.open('w'))
 authority=subprocess.Popen(['named','-g','-c',str(conf),'-n','1','-U','1'],stdout=output,stderr=subprocess.STDOUT)
 stack.callback(stop,authority)
 def ready():
 assert authority.poll() is None,log.read_text()
 response=query('lab.test.','SOA');return response.rcode()==0 and response.answer[0][0].serial==serial
 wait(ready)
 def update(body):
 nonlocal serial
 serial+=1;save(body);authority.send_signal(signal.SIGHUP);wait(ready)
 def cache(port=1054,upstream=1053,size=150,options=()):
 logfile=root/('cache-'+str(port)+'.log');stream=stack.enter_context(logfile.open('w'))
 command=['dnsmasq','--no-daemon','--conf-file=/dev/null','--no-resolv','--no-hosts','--bind-interfaces',
 '--listen-address=127.0.0.1','--port='+str(port),'--server=127.0.0.1#'+str(upstream),
 '--cache-size='+str(size),'--log-queries','--log-facility=-',*options]
 process=subprocess.Popen(command,stdout=stream,stderr=subprocess.STDOUT);stack.callback(stop,process)
 def cache_ready():
 assert process.poll() is None,logfile.read_text()
 return query('lab.test.','SOA',port).rcode()==0
 wait(cache_ready);return process,logfile
 def queries(name,kind='A'):
 return sum(bool(re.search(r'query: '+re.escape(name.rstrip('.'))+r' IN '+kind+r'\b',line)) for line in log.read_text().splitlines())
 yield root,update,cache,queries
with lab('short 1 IN A 127.0.0.2\nlong 20 IN A 127.0.0.3\nchain 6 IN A 127.0.0.4') as (_,update,cache,queries):
 cache();samples=[]
 for i in range(3):
 pair={name:show(query(name+'.lab.test.',port=1054)) for name in ('short','long')};samples.append(pair)
 if i<2:time.sleep(1.2)
 wait(lambda: queries('short.lab.test')==3 and queries('long.lab.test')==1)
 first=query('chain.lab.test.',port=1054);assert first.answer[0].ttl==6
 wait(lambda: queries('chain.lab.test')==1)
 time.sleep(2.2);cache(port=1055,upstream=1054)
 downstream=query('chain.lab.test.',port=1055);upstream=query('chain.lab.test.',port=1054)
 assert values(downstream)==['127.0.0.4'] and 0<downstream.answer[0].ttl<6
 assert abs(downstream.answer[0].ttl-upstream.answer[0].ttl)<=1
 assert queries('chain.lab.test')==1
 update('short 1 IN A 127.0.0.2\nlong 20 IN A 127.0.0.3\nchain 6 IN A 127.0.0.5')
 wait(lambda: values(query('chain.lab.test.',port=1055))==['127.0.0.5'],timeout=8)
 wait(lambda: queries('chain.lab.test')==2)
 print(json.dumps({'three_lookups_each':samples,'authority_query_counts':{'short':queries('short.lab.test'),'long':queries('long.lab.test')},
 'cache_chain':{'original':show(first),'downstream_first':show(downstream),'upstream_remaining':show(upstream),'authority_queries_after_expiry':queries('chain.lab.test')}},sort_keys=True))
"""
name='xbcatm-dns-'+uuid.uuid4().hex[:10]
def docker(*args,**kwargs):return subprocess.run(['docker',*args],capture_output=True,text=True,timeout=300,**kwargs)
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'Dockerfile').write_text(recipe)
 built=docker('build','-t',name,str(root));assert built.returncode==0,built.stderr
 result=docker('run','--rm','-i','--name',name,'--network','none','--memory','384m','--pids-limit','128',name,
 '/usr/bin/python3','-',input=program)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),sort_keys=True))
finally:
 docker('rm','-f',name);docker('image','rm',name)

The short.lab.test record has TTL 1 and long.lab.test has TTL 20. The program queries each three times, waiting 1.2 seconds between rounds. The authoritative log records three queries for the short-lived record and one for the long-lived record. Both produce successful answers on every round. The difference is upstream work under this controlled request schedule, not a measured application-latency improvement.

The returned TTL for the long-lived record decreases across rounds, while each refreshed short-lived answer starts at 1 again. The script checks the server log rather than assuming a fast response means a cache hit. On loopback, even an uncached query can be quick, so response time alone would not establish whether the authority was contacted or the answer came from memory.

For the layered case, the first forwarder caches chain.lab.test with TTL 6. After 2.2 seconds, a newly started second forwarder queries through it. The recorded downstream answer has TTL 3, matching the upstream remaining value within integer-second timing. It does not regain TTL 6. The authoritative count remains one, confirming that this downstream fill reused the first forwarder’s cached answer.

The authority then changes the chain record’s address. Queries through the second forwarder eventually receive the new address, and the authoritative count rises to two. This checks successful refresh through both layers after the retained data expires. The exact expiry fraction is implementation-dependent; the asserted properties are preserved remaining lifetime, no premature extra authoritative query, and eventual acquisition of the changed value.

Choose TTL from observed demand and change needs

Use expected change frequency and acceptable old-answer overlap alongside query volume. A busy shared resolver can amortize one answer across many clients, whereas isolated caches duplicate fills. Eviction can make an entry disappear before its TTL, so a long configured lifetime does not guarantee a hit. Measure hits, misses, upstream requests, and available capacity instead of treating TTL as a cache-size control.

For a planned move, lower TTL early enough for earlier longer-lived copies to expire. Keep the destination overlap aligned with the actual retained data. Raising TTL after stability reduces repeated resolution for busy records, but it also extends the next change’s ordinary waiting window. The relevant unit is the RRset: records of the same name, class, and type should have a consistent TTL.

Finally, compare answer data and remaining lifetime at each resolver actually used by the application. A direct authoritative query and a cached recursive answer reveal different states. Application caches and existing connections may add their own behavior outside this DNS experiment. Separate those lifetimes before estimating how quickly users will discover a changed endpoint or how much authoritative capacity a TTL adjustment requires.

Sources

RFC 1035 domain names, TTL as a cache lifetime and treatment of cached records, checked 2026-09-12.
RFC 2181 DNS clarifications, TTL limits and consistent lifetime within an RRset, checked 2026-09-12.
dnsmasq manual, cache sizing, forwarding, and TTL options, checked 2026-09-12.