NAME¶
encapsulate - multiplex several channels over a single socket with sampling of
remote process exit status, and provide conversation termination without
closing the socket.
netpipes 4.2
SYNOPSIS¶
encapsulate --fd n [
--verbose ] [
--subproc
[
--infd n[
=sid] ] [
--outfd
n[
= sid] ] [
--duplex n[
=sid]
] [
--Duplex n[
=sid] ] [
--DUPLEX
n[
=sid] ] [
--prefer-local ] [
--prefer-remote ] [
--local-only ] [
--remote-only ] ] [
--client ] [
--server ]
-[
#n][
v][
s[
in][
on][
dn][
ion][
oi
n][
l][
r][
L][
R]]
command args ...
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
WRONG:
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¶
netpipes (1),
http://sunsite.unc.edu/ses/scp.html
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¶
Copyright (C) 1997-98 Robert Forsman
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¶
Robert Forsman
thoth@purplefrog.com
Purple Frog Software
http://web.purplefrog.com/~thoth/