Provided by: netpipes_4.2-8build1_amd64 bug

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

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/

                                          June 19, 1997                            ENCAPSULATE(1)