encapsulate - Online in the Cloud

PROGRAM:

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][oin][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

Use encapsulate online using onworks.net services