.\" $Id: recvmux.man,v 1.14 2012/08/20 23:17:43 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/recvmux.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/recvmux.7*
.TH RECVMUX 7 LOCAL
.SH NAME
recvmux - receive a stream via tcpmux
.SH SYNOPSIS
.ds PN "recvmux
\fI\*(PN\fP [\fB\-M\fP] [\fB\-D\fP\~\fIspool\fP] [\fB\-m\fP\~\fImode\fP] [\fB\-N\fP\~\fIname\fP] [\fB\-R\fP\~\fIregexp\fP] [\fB\-s\fP\~\fIsubject\fP] [\fIuntrusted\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP


.SH DESCRIPTION
Sometimes you need a straightforward way to store a message under a rock.
Write a file in a directory for each of several hosts, then process
them after all of them have made the dead-drop.  When you need a
place to gather the data \fI\*(PN\fP is your friend.
.PP
Any host that can reach the "drop host" via TCP port 1 can chat
up the \*(PN service (by that name or an alias) to deposit a
stream of bytes in a file named for the client host's IP address.
That file will be overwritten in-place until it is processed
by some external structure.
.PP
Another way to do this would be via e-mail.  And one can use
the \fB\-M\fP option and the \fBprocmail\fP(1) filter to
chain to this service (see the examples below).
.PP
In either case the first line of the stream is matched
against \fIregexp\fP in an attempt to find a better filename
than the IP address of the client host.  If this expression
matches, then the first set of parenthesis sets the name of
the host (which cannot be the empty string).
.PP
In the case where the stream came from an out-of-band
process (not from an client connection) the command-line
may specify a \fIsubject\fP which is matched against the
same \fIregexp\fP to to set the filename.
The first line match, above, supersedes any \fIsubject\fP match.

.SH OPTIONS
.TP
.nf
\fB\-D\fP \fIspool\fP
.fi
This option specifies the directory to store incoming streams.
The default is the home directory of the real uid of the processes.
.TP
.nf
\fB\-h\fP
.fi
Display only a brief help message.
.TP
.nf
\fB\-M\fP
.fi
Notify the program that \fIstdin\fP is not a socket.  This prevents
the service from sending the RFC1078 reply codes back to a
non-existent client.
.TP
.nf
\fB\-m\fP \fImode\fP
.fi
Force the mode on the file to this octal mode, rather than using
just the inherited umask.
.TP
.nf
\fB\-N\fP \fIname\fP
.fi
Force the name of the client host to be \fIname\fP.  This
disables the \fIregexp\fP search for the hostname, but the name
is still filtered for leading dots, slashes, and other security checks.
.TP
.nf
\fB\-R\fP \fIregexp\fP
.fi
Specify a perl regular expression to extract the desired
filename from the first line of the stream, or from \fIsubject\fP.
.TP
.nf
\fB\-s\fP \fIsubject\fP
.fi
scan e-mail subject for default name
.TP
.nf
\fB\-V\fP
.fi
show version information
.TP
.nf
\fIuntrusted\fP
.fi
CIDRs to forbid any mux access


.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output the standard version information, and the default \fIregexp\fP.
.TP
.nf
\fI\*(PN\fP \-h
.fi
Output only a brief help message.
.TP
.nf
tcpmux/storage stream tcp nowait storage:sample /usr/local/libexec/recvmux recvmux \-D /var/storage
.fi
Collect reports for the "storage" tcpmux service in \fI/var/storage\fP under
the login "storage" in group "sample".  The default \fIregexp\fP is
in-place to name incoming files where the first line contains an
\fBmk\fP(1l) marked line with the hostname quoted.
.TP
.nf
tcpmux/diag stream tcp nowait diag /usr/local/libexec/recvmux recvmux 10.0/8 192.168.0.0/16
.fi
Allow local networks that are \fBnot\fP elements of the RFC1918
ten and one-ninty-two spaces to dead-drop diagnostic files in ~diag.
.PP
.nf
# for a hostname on the subject line
:0 HbwE : lock
* ^Subject:[    ]*\e/..*
| /usr/local/libexec/recvmux \-M \-m 0644 \-D $HOME \-R '\es*(.*)' \-s "$MATCH"
.fi
.RS
A sample use as a \fBprocmail\fP(1) filter.  Scan a subject header for
a client hostname, the whole subject line is taken as the hostname.
.RE

.SH BUGS
The inclusion of the marked line in the output is a fine point.
It might be argued that we should consume the line as a parameter,
rather than including it in the output file.  That would be
correct, except that the line is still a valid parameter to
\fBmk\fP(1l) to perform some other task we might require later.
.PP
The composition of the default regular expression doesn't make any
sence at first glance: it is trying to extract the hostname from
an \fBmk\fP(1l) marked line.  For example:
.RS
.nf
# $Which: ${echo-echo} 'nostromo' $$
.fi
.RE
Note that this expression expects the training double-dollar, which
is not supplied in most \fBmk\fP marked lines.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
mux at ksb.npcguild.org

.SH "SEE ALSO"
sh(1), tcpmux(8l) or inetd(8), muxsend(1l), mk(1l), op(1l)