Add README file

3 files changed, 107 insertions, 3 deletions

diff --git a/Makefile b/Makefile
index 2db25d6..e10a14c 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ CFLAGS    = -Wall -ggdb
 SOURCES   = rpipe.c net.c mem.c wordsplit.c server.c client.c cq.c runas.c
 HEADERS   = rpipe.h wordsplit.h
 OBJECTS   = $(SOURCES:.c=.o)
-DOCS      = COPYING
+DOCS      = COPYING README
 
 rpipe: $(OBJECTS)
 	$(CC) -orpipe $(OBJECTS) $(LDFLAGS)
diff --git a/README b/README
new file mode 100644
index 0000000..3d3f8d9
--- /dev/null
+++ b/README
@@ -0,0 +1,101 @@
+Overview
+========
+
+Rpipe is a simple tool for forwarding the content of the local file to
+the stdin of a program running on a remote host via TCP. The tool was
+created when I needed to run GNU Mailman[1] in a docker container without
+MTA in it.
+
+It implements a slightly modified version of TCPMUX[2] protocol. The same
+binary (rpipe) serves both as a server (on the remote end) and as a
+client (on the local end). See the Example section below.
+
+Installation
+============
+
+To build the program you will need GNU Make. Unpack the tarball, change
+to the source directory and run
+
+  make
+
+To install the program, run
+
+  make install
+
+as root. The binary will be installed in /usr/local/bin and the manpage in
+/usr/local/share/man/man1. To change this default, use the PREFIX variable.
+E.g. to install everything under /usr run
+
+  make install PREFIX=/usr
+
+A number of variables is available to further fine-tune it:
+
+  BINDIR  Default installation directory for the rpipe binary. Defaults to
+          $(PREFIX)/bin
+  MANDIR  Default root directory for the manual pages. Defaults to
+          $(PREFIX)/share/man
+  MAN1DIR Installation directory for manuals in Section 1. Defaults to
+          $(MANDIR)/man1
+
+Example
+=======
+
+The following configuration allows the system administrator to run mailman
+in a docker container and to distribute messages via the usual list mechanism
+using MTA on the host machine.
+
+Server configuration
+--------------------
+
+The container exposes TCP port 1 and runs the following command:
+
+ /usr/bin/rpipe -s -vv -udaemon -gsmmsp /opt/mailman/mail/mailman
+
+The `-s' option tells it to run as a server. The two `-v' options select
+maximal output verbosity. The diagnostics will be issued to the standard
+error. The `-u' and `-g' options specify the user and group to run mailman
+as. The only non-optional argument supplies the full pathname to the
+binary to run when a request is accepted from the client.
+
+For a detailed description of rpipe command line options, see rpipe(1).
+
+The rpipe utility runs in foreground.
+
+Client configuration
+--------------------
+
+Normally Mailman-based mailing lists are configured as follows (using
+sendmail-style aliases):
+
+ some-list:       "|/opt/mailman/mail/mailman post some-list"
+ some-list-admin: "|/opt/mailman/mail/mailman admin some-list"
+ ...
+
+Just replace the program name after the pipe, so that your list setup
+becomes:
+
+ some-list:       "|/usr/bin/rpipe -a 172.17.0.2 post some-list"
+ some-list-admin: "|/usr/bin/rpipe -a 172.17.0.2 admin some-list"
+ ...
+
+Replace 172.17.0.2 with the actual IP of the container.
+
+License
+=======
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Footnotes
+=========
+[1] https://www.list.org
+[2] https://tools.ietf.org/html/rfc1078
diff --git a/client.c b/client.c
index 82fc792..1942d9a 100644
--- a/client.c
+++ b/client.c
@@ -49,7 +49,7 @@ rpipe_client(struct addrinfo *ap, int argc, char **argv)
 {
 	int fd;
 	FILE *fp;
-	int i, c;
+	int i, c, status;
 	char buf[IO_BUF_SIZE];
 	
 	signal_setup(client_sig_handler, client_sigv, client_sigc);
@@ -97,5 +97,8 @@ rpipe_client(struct addrinfo *ap, int argc, char **argv)
 		error(EX_UNAVAILABLE, 0, "%s", buf + 2);
 	else if (buf[0] != '+')
 		error(EX_UNAVAILABLE, 0, "unexpected response: %s", buf);
-	exit(atoi(buf+2));
+	status = atoi(buf+2);
+	if (status)
+		error(status, 0, "local error; please contact administrator");
+	exit(0);
 }