.\" $Id: muxcat.man,v 1.16 2012/07/06 20:08:28 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -man -tbl %f |${PAGER-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/muxcat.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/muxcat.1*
.TH MUXCAT 1 LOCAL
.SH NAME
muxcat - display a stream from a TCPMUX-like service
.SH SYNOPSIS
.ds PN "muxcat
\fI\*(PN\fP [\fB\-Fux\fP] [\fB\-o\fP\~\fIfile\fP] [\fB\-p\fP\~\fIport\fP] \fIhost\fP \fIservices\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
This program is designed to display a stream of bytes from an
RFC 1078 data source.  The data source is on \fIhost\fP under the
\fItcpmux\fP service (either under \fBinetd\fP(8) or \fBtcpmux\fP(8l)).
A non-standard port may be specified as \fIport\fP.

.PP
As \fI\*(PN\fP provides no in-band credential scheme,
the \fIservice\fP may choose to recognize our client with
\fBgetpeername\fP(2), an RFC 1413 identification request, or any
other metric which is implemented wholly out-of-band by the remote service.
Any authorization action required by this client is beyond the
scope of this program.

.PP
For each \fIservice\fP presented another level of encapsulation
is performed.  This allows a mux service to run nested inside another.
The remote service sees the client socket shutdown (for read) after
the last \fIservice\fP is presented, see \fBshutdown\fP(2).

.PP
Each service must reply with a single line starting with a plus
sign (\fB+\fP) to acknowledge that the service is ready (as per RFC 1078).
The "help" service is exempt from this requirement.  Data after the last
acknowledgment line are copied to the \fIstdout\fP, or the named
\fIfile\fP.

.PP
As an extension a service may respond with:
.RS
.nf
	\fB@\fP[\fIhost\fP]\fB:\fP[\fIport\fP]
.fi
.RE
to redirect \fI\*(PN\fP to a different service.  The client
connects to the new \fIhost\fP on the specified \fIport\fP to
re-request the same service-name.  Either \fIhost\fP or \fIport\fP may
be the empty string to indicate \*(lqno change\*(rq.  If a service
redirects to itself \fI\*(PN\fP fails, but longer loops are not
presently detected.

.PP
When no service is provided the \fBbasename\fP of the program is
used as a default \fIservice\fP.  This is not represented in the
usage message because it is almost never useful.

.SH OPTIONS
.TP
.nf
\fB\-F\fP
.fi
Specify that the final \fIservice\fP specification doesn't offer any
acknowledgment advise, like the "help" service.
This make certain network services easier to query from the command-line.
.TP
.nf
\fB\-h\fP
.fi
Print a brief help message.
.TP
.nf
\fB\-o\fP \fIfile\fP
.nf
The name of the file to record the output stream.
When no file is given \fI\*(PN\fP defaults to \fIstdout\fP.
.TP
.nf
\fB\-p\fP \fIport\fP
.fi
The TPC/IP port \fBtcpmux\fP (cum \fBinetd\fP) listens on for
client connections (per RFC 1078 this should be port 1, our default).
The port may be provided as a service name from \fB/etc/services\fP.
.TP
.nf
\fB\-u\fP
.fi
Use unbuffered output when writing to \fIfile\fP.
.TP
.nf
\fB\-V\fP
.fi
Show only the programs version information and exit.
.TP
.nf
\fB\-x\fP
.fi
Display the success or failure banners from the remote service.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP localhost help
.fi
Request the list of services the local host provides.  This is
special due to RFC 1078's requirement that the token "help"
always succeed (as a terminal state).
.TP
.nf
\fI\*(PN\fP $CENTRAL todo
.nf
Ask the \fICENTRAL\fP server for a "todo" list.  If we really
trust this server we could just pipe the resultant script to
a shell.  We'd be very trusting of the server in that case.
.TP
.nf
\fI\*(PN\fP \-x $CENTRAL hxmd.cf | hxmd \-C \- \fI...\fP
.fi
Use the \fBhxmd\fP configuration file from the \fICENTRAL\fP host
as the configuration for a local instance of \fBhxmd\fP(8l).
Show the chat replies on \fIstderr\fP.
.\" "Temptation will destroy your mind, with never-ending hunger." "Oh! It has!"
.TP
.nf
\fI\*(PN\fP \-F hicks uid ksb
.fi
Ask the "uid" service on \fBhicks\fP to match "ksb".
This service doesn't acknowledge each request,
since it allows multiple requests, so the \fB\-F\fP option allows the
reply to be read as data.  Since \fI\*(PN\fP sends an end of file
(via shutdown(2)) on the socket the "uid" service releases the client.
.TP
.nf
\fI\*(PN\fP \-x sulaco msrcmux local/sbin/level2s auto.cf >/tmp/level2s.tar
.fi
Use \fI\*(PN\fP to invoke an instance of \fBmsrcmux\fP on
the host "sulaco" to get a pre-configured platform version of
the source to \fBlevel2s\fP in \fBtar\fP format.
That makes this program the \*(lqclient\*(rq for \fBmsrcmux\fP(7l),
as well as many other services.

.SH BUGS
None known, other than these services imply a great deal of
trust between the peers.  Since the mux service is normally bound to a
privileged port one might assume that is justified on a local network.
.PP
Be aware that most text services (like help) use network line-breaks
(that is "\er\en") and could require a \fBtr\fP(1) spell to make them
UNIX-pipe friendly (viz. "|tr \-s '\er\en' '\en\en'").
.PP
Better loop detection for redirections should be included.

.SH AUTHOR
Kevin S Braunsdorf
.br
Npcguild.org
.br
tcpmux at ksb.npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), dumpmux(1l), inetd(8), getpeername(2), muxsend(1l), hxmd(8l),
inetd(8) or xinetd(8), msrcmux(7l), tar(1), level2s(8l), recvmux(7l)