SHIBARI-SERVER-UDP(8)

NAME
shibari-server-udp - bind to a UDP socket, then answers DNS queries until killed

SYNOPSIS
shibari-server-udp [-U] [-v verbosity] [-d notif] [-f tdbfile] [-w wtimeout] [-i rulesdir] [-x rulesfile] [-p port] ip

DESCRIPTION
The goal of shibari-server-udp, at the moment, is to be a drop-in replacement for the tinydns[1] program, while being more maintainable.

shibari-server-udp creates a UDP socket and binds it to address ip on port 53. ip can be IPv4 or IPv6.

It listens to non-recursive DNS queries, sent by DNS caches, and, if appropriate, answers with data it reads from its data file.

It reloads its data file on SIGHUP, and exits 0 on SIGTERM.

The data file is a cdb[2] database; it must use the output format from tinydns-data[3].

  Client location
shibari-server-udp ignores client location information given as ‘%lo:ipprefix’ lines in the file created by tinydns-data[3]. Instead, it reads client location information in LOC definitions present in the rulesdir or rulesfile access rules database. For instance, if you have a ‘%lo:1.2.3’ line in your text data file, meaning that clients whose IP address is in the ‘1.2.3.0/24’ IPv4 range are identified with the ‘lo’ location and that DNS data entries ending with ‘:lo’ are visible to them, you need to translate this information into the accessrules format. Your rulesdir must contain the following files:

•   ip4/1.2.3.0_24/allow ( may be empty)

•   ip4/1.2.3.0_24/env/LOC containing ‘lo’

( To use the -x option instead, you'd do the same, then run ‘s6-accessrules-cdb-from-fs rulesfile rulesdir’ to compile the information into rulesfile.)

The DNS database can be changed at any time via an invocation of tinydns-data[3]. shibari-server-udp will keep using the old data until it receives a SIGHUP, at which point it will reopen its database.

shibari-server-udp is a drop-in replacement for tinydns[1], with the caveat of the client location mechanism.

If you are using the -i or -x option, the access rules database can, and should, be the same one that is used by the s6-tcpserver-access(8) program in your shibari-server-tcp(8) service. You don't want to give different permissions, or different location information, depending on whether a query is made over TCP or UDP.

OPTIONS

-U  Drop privileges. shibari-server-udp will expect the UID and GID environment variables to contain a suitable uid and gid, and will change to this uid and gid after binding its socket.

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

-d notif
    Write a newline to file descriptor notif, then close it, when shibari-server-udp has bound its socket, opened its file, and is ready to serve. This is the s6-notifywhenup(7) mechanism. By default, when this option isn't given no readiness notification is sent.

-f tdbfile
    Read DNS data from tdbfile. The default is data.cdb, in the current working directory of the shibari-server-udp process.

-w wtimeout
    Write timeout. If shibari-server-udp is unable to send its answer in wtimeout milliseconds, which means the network is congested, give up and go back to listening to other queries. The default is 0, which means infinite: shibari-server-udp will wait forever until the network decongests in order to send its answer ( which may prevent it from servicing other queries).

-i rulesdir
    Use rulesdir as a filesystem-based access rules database[4]: ignore any message whose originating IP address isn't explicitly allowed. The access rules database is also used to get client location information. If something in rulesdir changes while shibari-server-udp is running, it will immediately pick up the change.

-x rulesfile
    Use rulesfile as a cdb access rules database[4], see description of -i above. -i and -x are equivalent; you can switch between rulesdir and rulesfile via the s6-accessrules-cdb-from-fs(8) and s6-accessrules-fs-from-cdb(8) programs. The cdb format is more efficient but more static than the filesystem format. If rulesfile changes while shibari-server-udp is running, it will continue to use the old data until it receives a SIGHUP.

-p port
    Binds to port port. Default is 53.

EXIT STATUS

0   Clean exit. shibari-server-udp received a SIGTERM and exited.

100 Bad usage. shibari-server-udp was run in an incorrect way: typically bad command line options.

101 Cannot happen. This signals a bug in shibari-server-udp, and comes with an error message asking you to report the bug. Please do so, on the skaware mailing-list[5].

102 Misconfiguration. shibari-server-udp 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-notifywhenup(7), s6-accessrules-cdb-from-fs(8), s6-accessrules-fs-from-cdb(8), s6-tcpserver-access(8), shibari-server-tcp(8)

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

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

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

[4] https://skarnet.org/software/s6/libs6/accessrules.html

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

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

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