shibari
Software
skarnet.org

The shibari-server-udp program

shibari-server-udp is a long-lived process. It binds to a UDP socket, then answers DNS queries it receives, until it is killed.

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

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

• 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 database; it must use the output format from tinydns-data.

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.

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.

-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 readiness notification 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: 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, see description of -i above. -i and -x are equivalent; you can switch between rulesdir and rulesfile via the s6-accessrules-cdb-from-fs and s6-accessrules-fs-from-cdb 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.

shibari-server-udp ignores client location information given as %lo:ipprefix lines in the file created by tinydns-data. 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. 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, 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 program in your shibari-server-tcp service. You don't want to give different permissions, or different location information, depending on whether a query is made over TCP or UDP.