Reference

CLI reference

hollow is a verb and its flags. Everything below is transcribed from hollow <verb> -h against v1.0.1 — nothing is inferred from what a DNS tool ought to have. Go's flag package accepts one dash or two; the double-dash form is used throughout because that is what the README uses.

Exit codes

Part of the command-line contract, so a script can tell a name that does not exist from a resolver that could not find out — without parsing output meant for a person.

0
ExitOK
An answer. The reply carried rcode NOERROR.
1
ExitNXDomain
The name does not exist. The reply carried rcode NXDOMAIN, which is an answer rather than a failure.
2
ExitFailure
Operational failure: a bad flag, an unparseable name, a resolution that could not complete, or any rcode other than the two above.

hollow resolve

Full page →

Walks from the IANA root servers down to the authoritative nameserver and prints the reply in dig-style presentation format. The type defaults to A. With --server it skips the walk and asks one server directly, which is the only mode where the delegation path is not checked.

hollow resolve [flags] <name> [type]

--dns0x20
default true
randomise the case of the query name, and refuse a reply that does not echo it
--hints <string>
root hints in named.root format; default is the compiled-in list
--json
output reply as JSON
--port <uint>
default 53
port to query
--server <string>
ask this server directly instead of resolving from the root
--tcp
query over TCP instead of falling back to it
--timeout <duration>
default 3s
deadline for one exchange with one server
--trace
show the delegation path as it is walked

hollow trace

Full page →

Resolves through the same code path as resolve and renders the delegation chain that walk actually took. Every line comes from a step the resolver emitted as it sent the packet, so a trace and a resolve cannot disagree about what happened.

hollow trace [flags] <name> [type]

--ascii
draw the tree with ASCII instead of box-drawing characters
--cache
cache within this one walk, so a CNAME chain reuses the delegations it already found
--dns0x20
default true
randomise the case of the query name, and refuse a reply that does not echo it
--hints <string>
root hints in named.root format; default is the compiled-in list
--json
output the steps as JSON
--port <uint>
default 53
port to query
--timeout <duration>
default 3s
deadline for one exchange with one server

hollow inspect

Full page →

Prints every octet of a reply with the field the decoder read it as. Compression pointers are resolved to their target offset and to the name they expand to. The annotation column comes from the same parser the resolver uses, so a region nobody can name fails a test rather than being skipped over.

hollow inspect [flags] <name> [type]

hollow inspect --file <message>

--file <string>
read the message from this file instead of sending a query
--hints <string>
root hints in named.root format; default is the compiled-in list
--port <uint>
default 53
port to query
--server <string>
ask this server directly instead of resolving from the root
--tcp
query over TCP instead of falling back to it
--timeout <duration>
default 3s
deadline for one exchange with one server

hollow serve

Full page →

Runs the caching, filtering DNS server on UDP and TCP at once. The default address needs no privileges. Blocklists load once at startup, and the control socket that stats and dash attach to is opt-in: nothing extra binds without --control.

hollow serve [flags]

--addr <string>
default "127.0.0.1:15353"
address to listen on, UDP and TCP
--allow <value>
allowlist file in the same formats, overriding every block; repeatable
--block <value>
blocklist file in hosts, domain-per-line or adblock format; repeatable
--block-mode <string>
default "nxdomain"
how a blocked name is answered: nxdomain, null or nodata
--cache-size <int>
default 100000
answers to hold in the cache; 0 disables caching
--control <string>
address for the control socket that hollow stats and hollow dash attach to, for example 127.0.0.1:15354
--dns0x20
default true
randomise the case of each outgoing query name, and refuse a reply that does not echo it
--forward <value>
resolve by asking this server instead of walking from the root; repeatable, tried in order
--hints <string>
root hints in named.root format; default is the compiled-in list
--rrl <int>
default 20
responses per second to one client network before rate limiting starts; 0 disables
--rrl-slip <int>
default 2
answer every Nth rate-limited response truncated instead of dropping it; 0 drops them all
--rrl-trusted <value>
network exempt from rate limiting; repeatable, and replaces the loopback default
--serve-stale <duration>
how long past expiry an answer may still be served when resolution fails; 0 disables
--timeout <duration>
default 5s
deadline for answering one query
--verbose
log every query answered
--workers <int>
default 64
size of the UDP worker pool

hollow stats

Full page →

Takes one snapshot over the control socket and prints it. Every control socket command reads and none change behaviour, which is what makes an unauthenticated loopback port defensible.

hollow stats [flags]

--json
print the snapshot as JSON
--target <string>
default "127.0.0.1:15354"
control socket of the server to ask
--timeout <duration>
default 5s
deadline for the whole exchange

hollow dash

Full page →

Attaches to a running server over the control socket and redraws on a timer. There is no keyboard interaction and no raw mode on any platform, which is what lets the dashboard run without touching terminal state beyond the alternate screen and the cursor.

hollow dash [flags]

--ascii
draw with ASCII instead of box-drawing characters
--height <int>
frame height; default is $LINES, then 30
--interval <duration>
default 500ms
how often to redraw, and how often to ask for a snapshot
--plain
append a frame per interval instead of redrawing in place, and write no escape sequences
--target <string>
default "127.0.0.1:15354"
control socket of the server to watch
--width <int>
frame width; default is $COLUMNS, then 100