SOCKETPIPE(1)		    General Commands Manual		 SOCKETPIPE(1)



1mNAME0m
       socketpipe - zero overhead remote process plumbing

1mSYNOPSIS0m
       1msocketpipe  22m[1m-b22m]  [1m-i  {  4m22minput24m 4mgeneration24m 4mcommand24m [4margs24m ... ] 1m} 22m] 1m-l {0m
       4mlogin24m 4mcommand24m [4margs24m ... ] 1m} -r { 4m22mremote24m 4mcommand24m [4margs24m ...  ]	1m}  22m[1m-o  {0m
       4moutput24m 4mprocessing24m 4mcommand24m [4margs24m ... ] 1m} 22m]

1mDESCRIPTION0m
       4mSocketpipe24m	connects  over a TCP/IP socket the 4mremote24m 4mcommand24m specified
       to the local 4minput24m 4mgeneration24m 4mcommand24m and/or the local 4moutput24m  4mprocess-0m
       4ming24m 4mcommand24m.  At least one of the two local commands must be specified.
       The input and output of the 4mremote24m 4mcommand24m are appropriately redirected
       so  that the remote command's input will come from the local 4minput24m 4mgen-0m
       4meration24m 4mcommand24m and the remote command's output will  be  sent	 to  the
       local 4moutput24m 4mprocessing24m 4mcommand24m.	The remote command is executed on the
       machine accessed through the 4mlogin24m 4mcommand24m.  The 4msocketpipe24m  executable
       should  be  available through the execution path in the remote machine.
       The braces used for delimiting the commands and their arguments	should
       be space-separated and can be nested.  This feature allows you to setup
       complex and efficient  topologies  of  distributed  communicating  pro-
       cesses.

       Although	 the  initial  4msocketpipe24m	communication  setup  is  performed
       through client-server intermediaries such as 4mssh(1)24m or 4mrsh(1)24m, the com-
       munication  channel that 4msocketpipe24m establishes is a direct socket con-
       nection between the local and the remote commands.  Without the use  of
       4msocketpipe24m, when piping remote data through 4mssh(1)24m or 4mrsh(1)24m, each data
       block is read at the local end by the respective client, is sent to the
       remote  daemon and written out again to the remote process.  The use of
       4msocketpipe24m removes the inefficiency of the	multiple  data	copies	and
       context	switches  and  can  in	some cases provide dramatic throughput
       improvements.  On the other hand, the confidentiality and integrity  of
       the  data  passing  through 4msocketpipe24m's data channel is not protected;
       4msocketpipe24m should therefore be used only within a confined LAN environ-
       ment.   (The authentication process uses the protocol of the underlying
       login program and is no more or less vulnerable than using the  program
       in isolation; 4mssh24m(1) remains secure, 4mrsh24m(1) continues to be insecure.)

1mOPTIONS0m
       1m-l { 4m22mlogin24m 4mcommand24m [4margs24m ... ] 1m}0m
	      Specify  the  remote  login command (see previous section).  Use
	      arguments to this command to specify the host and authentication
	      options (e.g. username).	The remote login command should accept
	      as further arguments a command and its arguments and execute  it
	      on the remote host.  The remote login command is used to execute
	      a server instance of 4msocketpipe24m on  the  remote  host.   Typical
	      examples of remote login commands are 4mssh(1)24m and 4mrsh(1)24m.


       1m-r { 4m22mremote24m 4mcommand24m [4margs24m ... ] 1m}0m
	      Specify  the  remote  processing command (see previous section).
	      The remote processing command is executed on the remote  machine
	      with  its	 input,	 output,  or both redirected for processing to
	      local commands.


       1m-i { 4m22minput24m 4mgeneration24m 4mcommand24m [4margs24m ... ] 1m}0m
	      Specify the remote input generation command (see	previous  sec-
	      tion).  The output of the input generation command is redirected
	      as input to the remote command.


       1m-o { 4m22moutput24m 4mprocessing24m 4mcommand24m [4margs24m ... ] 1m}0m
	      Specify the output processing command  (see  previous  section).
	      The  output  of the remote command is redirected as input to the
	      output processing command.


       1m-b	22mExecute the remote login command in	batch  mode.   This  option
	      should  be used when no interaction is needed for authentication
	      purposes with the remote login command.  This is for example the
	      case  when  user authentication is performed by means of private
	      keys (4mssh(1)24m) or (horror) the  4m.rhosts(5)24m  file	 (4mrsh(1)24m).	  The
	      option  circumvents  two problems in OpenSSH_3.5p1 (and possibly
	      also other remote login commands): the setting of	 our  (shared)
	      output  to  non-blocking I/O and attempts to read from the stan-
	      dard input.  The first problem may manifest  itself  through  an
	      error  message of the output processing command such as "stdout:
	      Resource temporarily unavailable".  The second problem will  not
	      allow  you  to put 4msocketpipe24m instances in the background, stop-
	      ping them with a tty input signal (SIGTTIN).  The 1m-b 22moption will
	      close  the  remote  login command's standard output and redirect
	      its standard input from /dev/null solving	 those	problems.   On
	      the  other  hand	this  flag will disable I/O to/from the remote
	      login command and may therefore interfere with  any  interaction
	      required for the authentication process.


1mEXAMPLE0m
       socketpipe  -b  -i  {  tar  cf  -  /  }	-l  { ssh remotehost } -r { dd
       of=/dev/st0 bs=32k }
       Backup the local host on a tape drive located on 4mremotehost24m.

       socketpipe -b -l { ssh remotehost } -r { dd if=/dev/st0 bs=32k }	 -o  {
       tar xpf - /home/luser }
       Restore a directory using the tape drive on the remote host.

       socketpipe  -b  -i { tar cf - / } -l { ssh remotehost } -r { bzip2 -c }
       -o { dd of=/dev/st0 bs=32k }
       Backup the local disk on a local tape,  compressing  the	 data  on  the
       (presumably a lot more powerful) 4mremotehost24m.

1mSEE ALSO0m
       4mtcpcat24m(1), 4mzsh24m(1)

1mAUTHOR0m
       Diomidis Spinellis -- <http://www.spinellis.gr>

1mBUGS0m
       The  sockets  used to connect the local and remote commands may read or
       write only parts of the data specified in a 4mread(2)24m or 4mwrite(2)24m  opera-
       tion.  Although this is standard behavior, and is for example correctly
       handled by the 4mstdio(3)24m library, some commands may not  expect  it	and
       may  exhibit  strange  bugs.  Most examples in Stevens's "4mAdvanced24m 4mPro-0m
       4mgramming24m 4min24m 4mthe24m 4mUNIX24m	 4mEnvironment24m"  (Addison-Wesley  1992)  would  fail
       reading	from sockets; on the other hand Section 6.6 of Stevens's "4mUNIX0m
       4mNetwork24m 4mProgramming24m" (Prentice Hall 1990) provides code that deals with
       this problem.



			       1 September 2003			 SOCKETPIPE(1)
