.\" $Id: muxsend.man,v 1.19 2012/07/06 20:08:54 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -man -tbl %f | ${PAGER-less}
.\" $Display(*): ${groff-groff} -T%s -man -tbl % f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/muxsend.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/muxsend.1*
.TH MUXSEND 1 LOCAL
.SH NAME
muxsend - send a stream to a TCPMUX-like service
.SH SYNOPSIS
.ds PN "muxsend
\fI\*(PN\fP [\fB\-Oux\fP] [\fB\-f\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 send a stream of bytes to a
simple data collector.  The collector is run on \fIhost\fP under
the \fBtcpmux\fP
service, either under \fIinetd\fP or under \fBtcpmux\fP(8), and
is known as \fIservice\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 ident request, or any
other metric which is implemented wholly in-band by the 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 inside another.
The default service is the basename of our program name.

.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 RFC1078).
The \*(lqhelp\*(rq service is exempt from this requirement.

.PP
As an extension redirections are allowed in the same way as \fBmuxcat\fP(1l).
See also \fBtcpmux\fP(8l).

.SH OPTIONS
.TP
.nf
\fB\-f\fP \fIfile\fP
.fi
The name of the file to pass to the service.
When no file is given \fI\*(PN\fP defaults to \fIstdin\fP.
.TP
.nf
\fB\-h\fP
.fi
Print a brief help message.
.TP
.nf
\fB\-O\fP
.fi
Display any replies (after the initial service negotiation) to \fIstdout\fP.
This actually fork(2)'s a separate process to read replies from the socket.
.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
Under \fB\-O\fP set autoflush on \fIstdout\fP.  This allows a
\fBperl\fP \fBopen2\fP co-process to synchronously push items in
and out of many tcpmux services.
.TP
.nf
\fB\-V\fP
.fi
Show only the programs version information and exit.
.TP
.nf
\fB\-x\fP
.fi
Trace replies from the remote service on \fIstderr\fP.

.SH EXAMPLES
.TP
.nf
\fBsince\fP /var/log/oprules | \fI\*(PN\fP log.my.domain.org opcollect
.fi
Send the list of \fBop\fP rules run since the last collection
to our log host under the \fBopcollect\fP service.
.TP
.nf
echo ksb | \fI\*(PN\fP \-O adm4 uid
.fi
Query the \*(lquid\*(rq service on \*(lqadm4\*(rq for a match on \*(lqksb\*(rq.
The same thing may be accomplished with \fBmuxcat\fP under \fB\-F\fP, but
this is less of a hack.
.TP
.nf
\fI\*(PN\fP \-O svr6 inrr
.fi
Connect to the \*(lqinrr\*(rq service on \fBsvr6\fP to ask about DNS round-robin
records.  Try \*(lqsso30.sac.fedex.com\*(rq or \*(lqwww100.sac.fedex.com\*(rq as
input.  Send an end-of-file to disconnect.
.TP
.nf
date | \fI\*(PN\fP $NOTIFY ack-boot
.fi
Send the present time to the notify host on the \fBack-boot\fP service.
This could be used to record a boot-event record for each node
that boots (or reboots) in a cluster.
The receiver could be as simple as a script that ran
\*(lqcat >>/var/log/boot.txt\*(rq, but might call
getpeername(2) to record which host sent the message.
.TP
.nf
\fI\*(PN\fP \-f /dev/null \-O localhost help
.fi
The same output as \*(lqmuxcat localhost help\*(rq, but far less clear.
.TP
.nf
echo ksb | \fI\*(PN\fP \-Ox  acct uid
.fi
Ask the accounting host for ksb's uid, and show the initial
negotiations on \fIstderr\fP.

.SH BUGS
None known.

.SH AUTHORS
Pete Fritchman, Kevin S Braunsdorf
.br
Databits.net, Npcguild.org
.br
petef at databits.net, tcpmux at ksb.npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), inetd(8), getpeername(2),
dumpmux(1l), muxcat(1l), muxsend(1l), recvmux(7l),
tcpmux(8) or tcpmux(8l)