Man Linux: Main Page and Category List

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