xenial (1) encapsulate.1.gz

Provided by: netpipes_4.2-8_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 (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)