.\" $Id: tcpmux.man,v 1.12 2012/10/28 16:47:43 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/tcpmux.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/tcpmux.8*
.TH TCPMUX 8L LOCAL
.SH NAME
tcpmux - implement RFC 1078, for inetd's without built-in support
.SH SYNOPSIS
.ds PN "tcpmux
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
The Internet RFC 1078 specification is one of the shortest and clearest
of the lot.  It allows a local site to implement TCP stream based services
with no "well known port" assigned, and almost no coding, by mapping a
shell command to a name.

.P
This implementation provieds compatibility with the modern BSD inetd's
built-in version.  To enable the generic service install a line in
\fB/etc/inetd.conf\fP:
.RS
.nf
tcpmux stream tcp nowait root  /usr/local/libexec/tcpmux tcpmux
.nf
.RE
and possibly one in \fB/etc/services\fP (if it is not present):
.RS
.nf
tcpmux	1/tcp
.fi
.RE

.P
Define the services to be presented in \fB/etc/tcpmux.conf\fP
exactly as they would be in inetd's config file.  If the service does
\fBnot\fP ouptut the RFC1078 reply code, unless the service name is
prefix with a plus (+).
As an extension to the \fBinetd\fP version a prefix of minux (\-) makes
the service name \fBalways\fP fail.
.P
Two other extensions are allowed.  A service name prefixed with an
commercial at (\fB@\fP) specified that the services has moved, and
the service my chain to an unprivileged account by shifting to
another configuration file with a less-than (\fB<\fP).  See the
EXAMPLES below.

.SH OPTIONS
.TP
.nf
\fB\-h\fP
.fi
Print a help message.
.TP
.nf
\fB\-V\fP
.fi
Show version information.

.SH EXAMPLES
.TP
.nf
pagesize stream tcp nowait nobody /usr/bin/pageszie pagesize
.fi
Output the system pagesize, but do \fBnot\fP include the RFC 1078
positive acknowledgment code.  This is not recommended behavior
for any service.  The \fBmuxcat\fP(1l) client's option \fB\-F\fP
allows clients to connect to such a service.
.TP
.nf
+date stream  tcp   nowait nobody /bin/date date
.fi
Output the system clock as a network service, the hard way.
.TP
.nf
\-uptime stream  tcp   nowait nobody /usr/bin/uptime uptime
.fi
Provide an explicit failure message (\*(lqSorry\*(rq) for the "uptime" service.
.TP
.nf
uptime stream  tcp   nowait nobody /bin/echo echo \-uptime
.fi
Produce a failure message via \fBecho\fP(1).
.TP
.nf
\fB<\fP\fIservice\fP stream tcp nowait \fIlogin\fP \fInew.conf\fP tcpmux
.fi
The process drops uid to the named \fIlogin\fP, then continues processing with
the new configuration file \fInew.conf\fP.
That file is relative to the new login's home directory, and must be
readable by the \fIlogin\fP.  An acknowledgment of \*(lq+\fIservice\fP\*(rq
is sent to the client.
.sp
This is an extension to the configuration file and is only available in
this implementation of the amazing mux.
.TP
.nf
\fB@\fP\fIservice\fP \fInewhost\fP:\fInewport\fP
.fi
The service returns the \*(lq@\fInewhost\fP:\fInewport\fP\*(rq rather than
an acknowledgment code of either plus (\fB+\fP) or minus (\fB\-\fP).
The client should re-attempt the connection to the given host on
the given port, with the same services.  Either value may be the empty,
which should be treated as \*(lqno change\*(rq.
Any circular referals must be trapped by the client.
.sp
This is an extension to the protocol and is only available in
this implementation of the glorious mux.

.SH BUGS
It is trivial to grant access to an unsafe command
(viz. a shell) with this service.
.P
As implied, this only works for TCP streams, and the \fInowait\fP in
the inetd.conf line for the tcpmux makes \fIwait\fP useless for
the beautiful mux itself, so we don't even look.
.P
The output message for explicitly failed services is "Sorry", which is
overused by UNIX\*(TM bigots.
.\" But I just can't help myself. "Nope." looked so inadequate.
.P
The RFC mandated \*(lqhelp\*(rq command always shows every service; it
would be nice to hide services from casual snoopers.  Use the recursive
configurations to do that.

.SH AUTHOR
Kevin Braunsdorf, NPC Guild
.br
mux no_spam-at_thanks ksb.npcguild.org

.SH RFC
At the URI \fBhttp://ietf.org/rfc/rfc1078.txt\fP.
.SH "SEE ALSO"
sh(1), inetd(8), inetd.conf(5), muxsend(1l), muxcat(1l), recvmux(7l),
msrcmux(7l), roapmux(7l)