X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/bdbd93268bb289994126ec46cbf4b66461579b92..fc916a0942e6ef8f63aefb96119d0e4fd7c7efbb:/pkstream/pkstream.1.in diff --git a/pkstream/pkstream.1.in b/pkstream/pkstream.1.in new file mode 100644 index 00000000..c2a391a2 --- /dev/null +++ b/pkstream/pkstream.1.in @@ -0,0 +1,162 @@ +.\" -*-nroff-*- +.\". +.\" Manual for the simple packet streamer +.\" +.\" (c) 2008 Straylight/Edgeware +.\" +. +.\"----- Licensing notice --------------------------------------------------- +.\" +.\" This file is part of Trivial IP Encryption (TrIPE). +.\" +.\" TrIPE 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 2 of the License, or +.\" (at your option) any later version. +.\" +.\" TrIPE 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 TrIPE; if not, write to the Free Software Foundation, +.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +.\"-------------------------------------------------------------------------- +.so ../defs.man.in \" @@@PRE@@@ +. +.\"-------------------------------------------------------------------------- +.TH pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +. +.\"-------------------------------------------------------------------------- +.SH "NAME" +. +pkstream \- forward UDP packets over streams +. +.\"-------------------------------------------------------------------------- +.SH "SYNOPSIS" +. +.B pkstream +.RB [ \-l +.IR port ] +.RB [ \-p +.IR addr ] +.RB [ \-b +.IR addr ] +.RB [ \-c +.IR addr \c +.BR : \c +.IR port ] +.br + +.IB addr : port +.IB addr : port +. +.\"-------------------------------------------------------------------------- +.SH "DESCRIPTION" +. +The +.B pkstream +program forwards UDP packets over some kind of reliable stream. It +understands TCP sockets natively; anything else has to be fudged up +using some kind of port forwarder like +.BR fw (1), +.BR ssh (1), +.BR stunnel (1), +etc. It's intended, among other things, to provide a transport for +.BR tripe (8) +packets where there are annoying firewalls in the way. +.SS "Command-line arguments" +The two +.RI ` addr \c +.BR : \c +.IR port ' +pairs on the command-line are respectively the UDP port that +.B pkstream +should listen on, and the port which it should receive packets from and +send them to. +.PP +By default, +.B pkstream +will parse packets from the stream attached to its standard input and +send them to its UDP peer; and it will write packets it reads from its +UDP port to the stream attached to its standard output. The program +will quit when its input stream closes. +.PP +This behaviour can be modified by passing suitable options: +.TP +.B "\-h, \-\-help" +Writes a brief description of the command-line options available to +standard output and exits with status 0. +.TP +.B "\-v, \-\-version" +Writes +.BR tripe 's +version number to standard output and exits with status 0. +.TP +.B "\-u, \-\-usage" +Writes a brief usage summary to standard output and exits with status 0. +.TP +.BI "\-l, \-\-listen=" port +Listen for connections on the given TCP +.IR port . +Only one connection is allowed at a time. When a connection is +accepted, forward UDP packets over the TCP stream until it closes; then +wait for another connection. +.TP +.BI "\-p, \-\-peer=" addr +Only accept TCP connections from +.IR addr . +This option only makes sense in conjunction with +.BR \-l . +.TP +.BI "\-b, \-\-bind=" addr +When making a connection (see +.B \-c +below), use +.I addr +as the source address rather than letting the kernel choose the address +automatically. This is useful when the other end will only accept +connections from a particular address and you get the wrong one otherwise. +.TP +.BI "\-c, \-\-connect=" addr : port +Connect to the given +.I addr +and +.I port +and forward packets over the TCP connection rather than using stdin and +stdout. +. +.\"-------------------------------------------------------------------------- +.SH "Protocol" +. +The stream protocol is very simple. Each packet is preceded by a +two-octet length field in network byte order. The length is number of +octets in the following packet (i.e., it does +.I not +include the length field itself). There is no padding between packets. +The only way a stream can be invalid is if it stops in the middle of a +packet. +. +.\"-------------------------------------------------------------------------- +.SH "BUGS" +. +The code hasn't been audited. It may contain security bugs. If you +find one, please inform the author +.IR immediately . +. +.\"-------------------------------------------------------------------------- +.SH "SEE ALSO" +. +.BR fw (1), +.BR ssh (1), +.BR stunnel (1), +.BR tripe (8). +. +.\"-------------------------------------------------------------------------- +.SH "AUTHOR" +. +Mark Wooding, +. +.\"----- That's all, folks --------------------------------------------------