From b8d0f83e6cea9640a7ee4402c163ad812237355d Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 10 Dec 2023 11:48:01 +0000 Subject: Initial commit Signed-off-by: Laurent Bercot --- doc/shibari-server-tcp.html | 213 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 doc/shibari-server-tcp.html (limited to 'doc/shibari-server-tcp.html') diff --git a/doc/shibari-server-tcp.html b/doc/shibari-server-tcp.html new file mode 100644 index 0000000..5f36087 --- /dev/null +++ b/doc/shibari-server-tcp.html @@ -0,0 +1,213 @@ + + + + + + shibari: the shibari-server-tcp program + + + + + + +

+shibari
+Software
+skarnet.org +

+ +

The shibari-server-tcp program

+ +

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

+ +
+

Interface

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

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 tipideed 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 charaters; 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

+
+ + + + + -- cgit v1.3.1