tskrtt

commit e73c455e70a9d94eb112089dee6f9d4f7ef37f09
parent bbf8818893746911a3f5bf9eb87428ad1d560005
Author: Santtu Lakkala <inz@inz.fi>
Date:   Sun, 16 May 2021 23:36:10 +0300

Some documentation

Diffstat:
A
README
 | 
76
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
M
main.c
 | 
11
+++++++++++
A
tskrtt.1
 | 
84
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

3 files changed, 171 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,76 @@
+A gopherd for Linux (and possibly others)
+
+Features:
+	* gopher menus (gophermap or gph)
+	* dir listings
+	* CGI support
+	* access logging
+	* TLS using libtls
+
+Usage:
+	tskrtt [-46d] [-t key cert] [-l logfile] [-b rootdir] [-p port]
+	       [-o outport] [-u user] [-g group] [-h host]
+	       [-i listen address]
+	-4		Only listen for IPv4 connections.
+	
+	-6		Only listen for IPv6 connections.
+	
+	-d		Don't fork into background.
+	
+	-l logfile	Location for an access log file (no default).
+	
+	-b rootdir	Root directory of served content
+			(default: /var/gopher).
+	
+	-h host		Hostname used in generated content (default: listen
+			address or system hostname)
+	
+	-p port		Port on which the daemon will listen (default: 70).
+	
+	-o oport	Port shown on generated content (default: same as
+			port).
+	
+	-u user		Change to user after startup.
+	
+	-g group	Change to group after startup.
+	
+	-i address	Listen for incoming connections on given address
+			(default: listen on any address).
+	
+	-t key cert	Allow connections using TLS using the given key and
+			cert (default: only plain text connection).
+
+Requirements:
+	tskrtt is based on libev event loop (tested with 4.25 and 4.33). For
+	TLS support, LibreSSL libtls or libretls is required.
+
+Building:
+	Build using make. If TLS support is not wanted, edit Makefile.
+
+GPH format:
+	tskrtt supports GPH formatting and should be compatible with that
+	of geomyidae. In addition tskrtt allows for server and/or port not
+	to be defined, in which case server's hostname and port (or 70 if
+	server is defined) are used.
+
+Dynamic content:
+	Executable files ending in .cgi are run and the input is forwarded
+	to client as-is. A well behaving .cgi should output well formed
+	gopher data (for text and menu content), including using CR + LF as
+	line ending and ending transmission with a dot on an otherwise
+	empty line, and take care not to have it anywhere else in the output.
+
+	Executable files ending in .dcgi are similarily run, but they should
+	output GPH formatted text instead, which is parsed by tskrtt before
+	passing on to the client.
+
+	Note that while striving to be able to be compatible with HTTP CGI,
+	a major difference is that neither type should print HTTP headers. For
+	example a PHP script should begin with
+
+	#!/usr/bin/php-cgi --no-header
+
+	to avoid HTTP headers in the output.
+
+Reporting bugs:
+	Bugs can be reported to inz@inz.fi via email.
diff --git a/main.c b/main.c
@@ -1330,6 +1330,14 @@ static void listen_cb(EV_P_ ev_io *w, int revents)
 
 static void usage(void)
 {
+	fprintf(stderr,
+		"usage: %s [-46d] "
+#ifdef USE_TLS
+		"[-t key cert] "
+#endif
+		"[-l logfile] [-b rootdir] [-p port] [-o outport] "
+		"[-u user] [-g group] [-h host] [-i listen address]\n",
+		argv0);
 	exit(1);
 }
 
@@ -1401,6 +1409,9 @@ int main (int argc, char *argv[])
 		case 'l':
 			logfile = EARGF(usage());
 			break;
+		default:
+			usage();
+			break;
 	} ARGEND;
 
 	if (!oport)
diff --git a/tskrtt.1 b/tskrtt.1
@@ -0,0 +1,84 @@
+.Dd May 16, 2021
+.Dt TSKRTT 8
+.Os
+.
+.Sh NAME
+.Nm tskrtt
+.Nd a gopher daemon
+.
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Op Fl 4
+.Op Fl 6
+.Op Fl d
+.Op Fl l Ar logfile
+.Op Fl b Ar rootdir
+.Op Fl h Ar host
+.Op Fl p Ar port
+.Op Fl o Ar outport
+.Op Fl u Ar user
+.Op Fl g Ar group
+.Op Fl i Ar listen-address
+.Op Fl t Ar key cert
+.Ek
+.
+.Sh DESCRIPTION
+.Bd -filled
+.Nm
+is a Gopher server.
+.Ed
+.
+.Sh OPTIONS
+tskrtt options and default settings:
+.Bl -tag -width Ds
+.
+.It Fl 4
+Only listen for IPv4 connections.
+.
+.It Fl 6
+Only listen for IPv6 connections.
+.
+.It Fl d
+Don't fork into background.
+.
+.It Fl l Ar logfile
+Location for an access log file (no default).
+.
+.It Fl b Ar rootdir
+Root directory of served content (default: /var/gopher).
+.
+.It Fl h Ar host
+Hostname used in generated content (default: listen address or system hostname)
+.
+.It Fl p Ar port
+Port on which the daemon will listen (default: 70).
+.
+.It Fl o Ar oport
+Port shown on generated content (default: same as port).
+.
+.It Fl u Ar user
+Change to user after startup.
+.
+.It Fl g Ar group
+Change to group after startup.
+.
+.It Fl i Ar listen-address
+Listen for incoming connections on given address (default: listen on any address).
+.
+.If Fl t Ar key cert
+Allow connections using TLS using the given key and cert (default: only plain text connection).
+.
+.Sh KNOWN BUGS
+Served text, gophermap and .gph and .dcgi lines can only have line length of 511 characters, longer lines are wrapped, which may break .gph formatting. This should pose no problems, as any gopher content shouldn't exceed 70 characters.
+.Pp
+If listen address resolves into multiple available addresses, only the first successful one will be listened to.
+.Pp
+Any headers received from CGI/DCGI will be passed onto the client, which is probably not what is wanted.
+.
+.Sh CONFORMING TO
+The daemon strives to conform to RFC 1436 and to be reasonably compatible with geomyidae server
+.
+.Sh SEE ALSO
+.Xr geomyidae 8
+.