Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ENCAPSULATE(1)		    General Commands Manual		ENCAPSULATE(1)

NAME
       encapsulate - multiplex several channels	over a single socket with sam-
       pling of	remote process exit status, and	provide	conversation  termina-
       tion 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	other-
       wise).

OPTIONS
       --fd n, -#n : specify the file descriptor of the	socket we will be mul-
       tiplexing 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  en-
       capsulate  will	read from its descriptor n (these are opposite polari-
       ties 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  polari-
       ties for	the SCP	channel).

       --duplex	 n, -ion : specify a bidirectional channel.  The remote	encap-
       sulate 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	direc-
       tion open.

       --Duplex	n, -dn : specify a bidirectional channel.  The --client	end of
       the  encapsulate	 connection  sends the SCP SYN packet and --server re-
       sponds 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 encapsu-
       late 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	direc-
       tion 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  it-
       self,  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 ig-
       nores 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	corre-
       sponding	flag on	the remote encapsulate that is in the exact same posi-
       tion (in	the list of channels).	The descriptor numbers need not	corre-
       spond, 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 pro-
       tocol 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,  en-
       capsulate 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 is-
       sued, 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  be-
       hind 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 applica-
       tions, 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 MER-
       CHANTABILITY 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SESSION IDs AND SUBPROCESS CHANNELS | CLIENT -VS- SERVER | EXAMPLES | TROUBLESHOOTING | SEE ALSO | BUGS | CREDITS | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=encapsulate&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help