NAME

netpipes 4.2

SYNOPSIS

DESCRIPTION

encapsulate implements the Session Control Protocol (SCP) in a limited manner. encapsulate multiplexes several virtual channels over a single socket using SCP. encapsulate transmits the exit status of the local program to the remote end over a reserved SCP channel and receives the remote exit status back. encapsulate provides conversation boundaries without closing the socket.

Flags may appear in any order. The first argument that isn't a flag is the command to spawn (assuming --subproc is specified, an error otherwise).

OPTIONS

--fd n, -#n : specify the file descriptor of the socket we will be multiplexing subprocess channels over. This argument is required

--verbose, -v : Print extra information (including a copyright notice) to stderr.

--subproc, -s : spawn a subprocess. You must supply a command and args. If you omit this flag, then you must not supply a command and args. If you omit this flag, encapsulate will copy input from stdin to an outgoing channel in the SCP–muxed socket and copy to stdout from an incoming channel in the SCP–muxed socket. If you omit this flag, all of the input and output channel flags are illegal.

--infd n, -in : specify an input channel. If there is a subprocess, it will be able to read from descriptor n. If there is no subprocess encapsulate will read from its descriptor n (these are opposite polarities for the SCP channel).

--outfd n, -on : specify an output channel. If there is a subprocess, it will be able to write to descriptor n. If there is no subprocess encapsulate will write to its descriptor n (these are opposite polarities for the SCP channel).

--duplex n, -ion : specify a bidirectional channel. The remote encapsulate will send the SCP SYN packet, and the local will respond with a SYN for the same session. The subprocess will be able to read and write to file descriptor n. The subprocess should use the sockdown(1) program if it must close one direction while leaving the other direction open.

--Duplex n, -dn : specify a bidirectional channel. The --client end of the encapsulate connection sends the SCP SYN packet and --server responds with a SYN for the same session. The subprocess will be able to read and write to file descriptor n. The subprocess should use the sockdown(1) program if it must close one direction while leaving the other direction open.

--DUPLEX n, -oin : specify a bidirectional channel. The local encapsulate will send the SCP SYN packet, and the remote will respond with a SYN for the same session. The subprocess will be able to read and write to file descriptor n. The subprocess should use the sockdown(1) program if it must close one direction while leaving the other direction open.

All of the long forms of the bidirectional channel have an optional =sid component that can be used to specify the SCP Session ID. This is not very useful when connecting encapsulate to another instance of itself, but could be handy when connecting to another piece of software that implements SCP.

--prefer-local, -l : if both the remote and local subprocesses exit with non–zero (erroneous) codes, encapsulate will exit with the same code as the local subprocess. This is the default.

--prefer-remote, -r : if both the remote and local subprocesses exit with non–zero (erroneous) codes, encapsulate will exit with the same code as the remote subprocess.

--local-only, -L : encapsulate exits with the local status and ignores the remote status.

--remote-only, -R : encapsulate exits with the remote status and ignores the local status.

SESSION IDs AND SUBPROCESS CHANNELS

When specifying channels for the subprocess, the order of the flags is very important. Every flag to the local encapsulate must have a corresponding flag on the remote encapsulate that is in the exact same position (in the list of channels). The descriptor numbers need not correspond, but the position and type of each channel must.

A lamentably complicating factor is that the data flow implied by --infd and --outfd are different when you specify a subprocess.

Local	Remote
--infd w/subproc	--outfd w/subproc
--infd w/subproc	--infd
--infd	--infd w/subproc
--infd	--outfd
--outfd w/subproc	--infd w/subproc
--outfd w/subproc	--outfd
--outfd	--outfd w/subproc
--outfd	--infd
--duplex	--DUPLEX
--Duplex	--Duplex
--DUPLEX	--duplex

RIGHT:

l$ encapsulate --infd 0 --duplex 5
r$ encapsulate --outfd 1 --DUPLEX 5

l$ encapsulate --infd 0 --duplex 5
r$ encapsulate --outfd 1 --duplex 5

--duplex must have a corresponding --DUPLEX on the remote end.

l$ encapsulate --infd 0 --duplex 5
r$ encapsulate --DUPLEX 5 --outfd 1

--infd must have a corresponding --outfd on the remote end. It's out of order and the channels will be allocated incorrectly leading to protocol errors.

If you understand the source code for encapsulate, you can violate these guidelines, but it is unnecessary, error–prone, and ill–advised; besides, you don't really understand the source code. Don't do it.

CLIENT -VS- SERVER

The SCP has an implicit polarity. One end is the server and the other end is the client. You can specify which end is which using --client and --server. If you do not specify one, then encapsulate will compare the addresses of both ends of the socket (specified with --fd) and use a deterministic algorithm to pick one to be the server and one to be the client. If the remote address of the socket does not correspond to the remote encapsulate (e.g. the packets are being forwarded through a plugged gateway, the addresses are being masqueraded, or are otherwise percieved inconsistently by the two ends) then this algorithm has a good chance of "failing" and assigning both to be server or both to be client.

The only time you should ever let encapsulate choose between client and server is in interactive situations. It is very likely that a software system built around encapsulate will be reused in a situation where the automatic polarity assignment fails.

EXAMPLES

Here's a simple file transfer daemon:

server$ faucet 3001 --once --fd3 \
     sh -c 'while ~/src/netpipes4.0/encapsulate --fd 3 -so5i4 \
                sh -c "fname=`cat 0<&4`; echo \$fname; cat < \$fname 1>&5"; \
                do true; done'
client$ hose server 3001 --retry 10 --delay 1 --fd3 \
        sh -c 'while read fname; do \
                ~/src/netpipes4.0/encapsulate --fd 3 -si4o5 \
                        sh -c "echo $fname 1>&5; exec 5>&-; cat 0<&4" \
                || break; done'

Just type the name of the file you want to retrieve into the hose and press return. It will be dumped to stdout. Repeat until enlightened or bored.

TROUBLESHOOTING

Did you specify --client and --server properly? One side should be server, the other side should be client. If you specify them both as server or both as client, you have made a mistake. Do not rely on the automatic polarity detection. While it is theoretically a very good algorithm, it is fooled very easily.

Do all of your channel assignments (--infd et al) match up? If you get these wrong, encapsulate will freak out and drip spooge all over your shoes.

For deadlock avoidance, make sure you are closing channels when you don't need them anymore. Use the >&- redirection operator in sh or bash. Make sure you close it in all of the background processes as well.

Unable to read stdin from a process that has been backgrounded with & ? Bash closes file descriptor 0 for any subprocess that is backgrounded (e.g. (command&) ). You can get around this by copying 0 onto another descriptor, and then copying it back within the backgrounded process.

( ( cat 0<&3 ) & ) 3<&0

SEE ALSO

The Session Control Protocol document on SunSite was a draft. There is a more recent one that doesn't specify header compression (which I don't use anyway). It may eventually become an RFC. Then again, encapsulate may be the only program which ever implements SCP.

BUGS

encapsulate is not hard to deadlock. Until I add unbounded buffering inside encapsulate, avoid constructing deadlock-vulnerable systems.

The encapsulate included with netpipes 4.0 totally failed to handle the case where no subprocess was specified. No error message would be issued, and the program would do absolutely nothing. The 4.1 version should work.

encapsulate has no other known bugs. I'm sure there are unknown ones because this software is not yet mature; in fact, it's totally wet behind the ears. Break it and send me the pieces.

Well, the command-line argument style is inconsistent with faucet & hose. I'll be updating faucet & hose.

The Linux kernel from the beginning of time up through version 2.0.29 has a problem with sockets being shut down "too fast". This results in loss of data at the end of a stream and an "Error: connection reset by peer" during reads. 2.0.30 supposedly fixes this. This state machine flaw is very likely present in many other OSes, because the strange conditions that exercise it are almost nonexistent in normal applications, but happen all the time in some applications of the NetPipes package. encapsulate can be used to work around this bug in some cases because encapsulate does not perform a shutdown on the network socket ever (it doesn't even do a "close").

CREDITS

Hi Mom! Hi Dad!

COPYRIGHT

This program 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.

This program 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 this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

AUTHOR

tar -cf - . | rsh other "cd destdir; tar -xf -"

setsockopt(fd, SOL_SOCKET, SO_REUSEADDR...)

example$ faucet 3000 --out --verbose --once --foreignhost client echo blah

example$ faucet 3000 -ov1h client echo blah

example$ faucet 3000 -hpHov1 client 2999 example-le2 echo blah

example$ faucet 3000 --fd 0 --fd 1 --verbose --once echo blah
example$ faucet 3000 -#0,1v --once echo blah
example$ faucet 3000 -v1#0,1 echo blah
example$ faucet 3000 -#0,1v1 echo blah

example$ faucet 3000 --out --verbose tar -cf - .

tar -cf - .

example$ faucet u-socket --out --err --once --unix csh -c \
	"dd if=angio.pgm | funky.perl.script" 

faucet 3000 -1v --fd 3 sh -c 'cat <&3 & cat >&3 ; sockdown 3'

faucet: Address 3000 in use, sleeping 10.
faucet: Trying again . . .

client$ hose mail.cise.ufl.edu smtp --in ./getpeername
25
128.227.205.210

client$ hose mail.cise.ufl.edu smtp --in ./getpeername -v
Internet
Port
25
Host
128.227.205.210
fireant.cise.ufl.edu

client$ hose web.cise.ufl.edu 80 -in ./getpeername
./getpeername: getpeername failed on descriptor 0: Socket is not connected

client$ hose web.cise.ufl.edu 80 -fd0 ./getpeername -v
Internet
Port
80
Host
128.227.205.206
flood.cise.ufl.edu

client$ hose web.cise.ufl.edu 80 -fd0 sh -c " ./getpeername -v | \
	tail +5 | egrep -v '^[0-9.]*$' | head -1"
flood.cise.ufl.edu

tar -cf - . | rsh other "cd destdir; tar -xf -"

 setsockopt(fd, SOL_SOCKET, SO_REUSEADDR...)

example$ hose reef 3000 --in tar -xf - .

tar -xf - .

example$ hose --unix- u-socket --in sh -c \
	"unfunky.perl.script | dd of=sample.pgm"

server$ faucet 3000 --out tar cf - .
client$ hose server 3000 --in tar xvf -

cairo$ hose www.cis.ufl.edu 80 --in --out \
	sh -c "(echo 'GET /'; sockdown) & cat > result"

cairo$ hose metaserver.ecst.csuchico.edu 3521 --in cat

remote$ faucet 3000 --fd 3 \
   encapsulate --fd 3 --infd 0 --outfd 1 --outfd 2 --subproc \
	remote-app
local$ hose remote 3000 --fd 3 \
   encapsulate --fd 3 --outfd 3 --infd 4 --infd 5 --subproc \
	sh -c "cat 0<&4 3>&- & cat 0<&5 1>&2 3>&- & \
	    cat 1>&3 ; exec 3>&-"

server$ faucet 3000 --in --out --verbose enscript -2rGhp -
client$ ps aux | hose server 3000 --in --out \
	sh -c " (cat <&3; sockdown ) & cat >&4 " 3<&0 4>&1 | \
	lpr -Pps422
#or perhaps this, but I haven't tested it
client$ ps aux | hose server 3000 --fd 3 \
	sh -c " (cat >&3; sockdown 3 ) & cat <&3 " | \
	lpr -Pps422

gateway$ faucet 3000 -io hose server 4000 --slave

server$ faucet 3000 -1v --fd 1 --foreignhost server echo blah 
client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
client$ hose localhost 3000 --fd 0 -retry 10 cat

server$ faucet 3000 -1v --fd 3 --foreignhost server \
	encapsulate --fd 3 --server -si0o1 tr a-z A-Z
client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
client$ echo blah | hose localhost 3000 --fd 3 -retry 10 \
	encapsulate --fd 3 --client

server$ faucet 3000 --in --out enscript -2rGhp -

client$ hose server 3000 -in -out \
	sh -c " cat blah.txt & cat > blah.ps "

client$ hose server 3000 -in -out \
	sh -c " ( cat blah.txt ; sockdown ) & cat > blah.ps "

client$ hose server 3000 -slave < blah.txt > blah.ps

bash# sockdown 1 2 > /proc/991/fd/5

function make-ssl-cert-link {
    hash=`x509 -noout -hash < $1`
    ln -s $1 $hash.0
}

server$ ssleay x509 -md5 -fingerprint -in certificate.pem -out /dev/null
MD5 Fingerprint=F6:0A:A2:D1:A3:12:5A:41:49:C7:56:0B:4E:67:1D:3C

#!/bin/sh

exec > /dev/null
exec 2>&1

exec /usr/local/bin/ssl-auth --fd 0 --server \
        --cert /usr/local/ssl/certs/imapd.cert \
        --key  /usr/local/ssl/private/imapd.key \
        --CApath /usr/local/ssl/certs/ \
        -si0o1 /usr/local/sbin/imapd

993     stream  tcp     nowait  root    /usr/local/sbin/ssl-imapd

imap stream tcp nowait root /usr/local/sbin/ssl-proxy imap.remote.com

#!/bin/sh

exec > /dev/null
exec 2>&1

exec hose "$1" 993 --fd 3 \
	ssl-auth --fd 3 --client \
        --CApath /usr/local/ssl/certs/ --verify 1 >&0

$ hose web.purplefrog.com 443 --fd 3 ssl-auth --fd 3 --client

$ hose web.purplefrog.com 443 --fd 3 ssl-auth --fd 3 --client \
        --CApath /usr/local/ssl/certs/ \
	--verify 1 --criteria --write-pem-cert tmp.cert \
	-si0o1 /bin/true

timelimit 5m faucet 3000 --out cat time-sensitive-info