SHIBARI-SERVER-TCP(8)

NAME
shibari-server-tcp - read DNS queries on standard input, and answer them on standard output

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

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

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 fulfil 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[2] database; the database must use the output format from tinydns-data[3].

The DNS database can be changed at any time via an invocation of tinydns-data[3]. 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[1], 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(8) invocation, make sure your shibari-server-udp(8) 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.

  Common usage
shibari-server-tcp is intended to be run under a TCP super-server such as s6-tcpserver(8). 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.

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 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.

ENVIRONMENT
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(8), 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(8) 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[3] 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(8) rules database.

EXIT STATUS

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[4].

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.

SEE ALSO
s6-tcpserver(8), s6-tcpserver-access(8), shibari-server-udp(8)

[1] https://cr.yp.to/djbdns/axfrdns.html

[2] https://en.wikipedia.org/wiki/Cdb_(software)

[3] https://cr.yp.to/djbdns/tinydns-data.html

[4] https://skarnet.org/lists/#skaware

This man page is ported from the authoritative documentation at: https://skarnet.org/software/shibari/shibari-server-tcp.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)