The shibari-server-tcp program

shibari-server-tcp reads DNS queries on its standard input, and answers them on its standard output.

The goal of shibari-server-tcp is, at the moment, to be a drop-in replacement for the axfrdns program, while following the DNS specifications more closely and being more maintainable.

Interface

     shibari-server-tcp [ -v verbosity ] [ -f tdbfile ] [ -r rtimeout ] [ -w wtimeout ]

shibari-server-tcp reads a stream of DNS queries on its stdin (encoded in the TCP DNS way, i.e. 2 bytes of length then the payload), and tries to fulfill them, sending answers to stdout. It logs its actions to stderr.
It supports normal queries and AXFR queries.
It reads DNS data information from a cdb database; the database must use the output format from tinydns-data.

Common usage

shibari-server-tcp is intended to be run under a TCP super-server such as s6-tcpserver. It delegates to the super-server the job of binding and listening to the socket, accepting connections, and spawning a separate process to handle a given connection.

As such, a command line for shibari-server-tcp, running as user dns, listening on address ${ip}, would typically look like this:

     s6-envuidgid dns s6-tcpserver -U -- ${ip} 53 s6-tcpserver-access -x rules.cdb -- shibari-server-tcp

Most users will want to run these command lines as services, i.e. daemons run in the background when the machine starts. The examples/ subdirectory of the shibari package provides service templates to help you run shibari-server-tcp under OpenRC, s6 and s6-rc.

Exit codes

0: Clean exit. There was a successful series of DNS exchanges and shibari-server-tcp received EOF, or timed out while the client was idle.
1: Invalid DNS query. The client spoke garbage.
100: Bad usage. shibari-server-tcp was run in an incorrect way: bad command line options, or missing environment variables, etc.
101: Cannot happen. This signals a bug in shibari-server-tcp, and comes with an error message asking you to report the bug. Please do so, on the skaware mailing-list.
102: Misconfiguration. shibari-server-tcp found something in its DNS data file that it does not like.
111: System call failed. This usually signals an issue with the underlying operating system.

Environment variables

shibari-server-tcp expects the following variables in its environment, and will exit with an error message if they are undefined. When run under s6-tcpserver, these variables are automatically set by the super-server. This is the way shibari-server-tcp gets its network information without having to perform network operations itself.

TCPLOCALIP: The local IP address that the super-server is listening on.
TCPLOCALPORT: The local port that the super-server is listening on. In normal usage this will be 53.
TCPREMOTEIP: The IP address of the client.
TCPREMOTEPORT: The remote port that the client is connecting from.

The following variables are optional, but will inform shibari-server-tcp's behaviour. They are typically set by s6-tcpserver-access with the -i or -x option, when the access rules database defines environment variables depending on client IP ranges.

AXFR: If this variable is set, it controls what zones the client is allowed to make AXFR queries for. A value of * (star) means the client is allowed to make AXFR queries for any zone, same as when the variable is not defined. Else, the value needs to be a space-, comma-, semicolon-, or slash-separated list of zones; these are the allowed zones.
LOC: If this variable is set, it defines a client location that is used to implement views. A client location is at most two characters; if the value is lo, then the client will be granted access to DNS data guarded by a %lo location indicator in the tinydns-data file. Note that shibari-server-tcp ignores client IP prefix matching compiled in the database via %lo:ipprefix lines: it only takes its location information from the LOC variable, and will use the contents of LOC to match lines ending with :%lo. The idea is to only have one place centralizing what clients are authorized to do depending on their IP, and that place is the s6-tcpserver-access rules database.

Options

-v verbosity: Be more or less verbose. A verbosity of 0 means no warnings, no logs, only error messages. 1 means warnings and terse logs. 2 or more means more logs. Default is 1.
-f tdbfile: Read DNS data from tdbfile. The default is data.cdb, in the current working directory of the shibari-server-tcp process.
-r rtimeout: Read timeout. If rtimeout milliseconds elapse while shibari-server-tcp is waiting for a DNS query, just exit. The default is 0, meaning infinite: shibari-server-tcp will never close the connection until it receives EOF.
-w wtimeout: Write timeout. If shibari-server-tcp is unable to send its answer in wtimeout milliseconds, which means the network is congested, give up and close the connection. The default is 0, which means infinite: shibari-server-tcp will wait forever until the network decongests in order to send its answer.

Notes

The DNS database can be changed at any time via an invocation of tinydns-data. shibari-server-tcp will keep using the old data until its current stream ends and it exits. The next instance of shibari-server-tcp, spawned by the super-server, will use the new data.
shibari-server-tcp is a drop-in replacement for axfrdns, with one caveat: client location information needs to be migrated from the DNS database to LOC definitions in the TCP access rules database. For instance, if you have a %lo:1.2.3 line in your text data file, you need to add the following entries to your TCP access rules database:
- ip4/1.2.3.0_24/allow (may be empty)
- ip4/1.2.3.0_24/env/LOC containing lo
If you are using such an access rules database via an s6-tcpserver-access invocation, make sure your shibari-server-udp service is using the same database via the -i or -x option. You don't want to give different permissions, or different location information, depending on whether a query is made over TCP or UDP.