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

FreeBSD Manual Pages

  
 
  

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

NAME
       socketpipe - zero overhead remote process plumbing

SYNOPSIS
       socketpipe  [-b]	 [-h host] [-t timeout]	[-i { input generation command
       [args ... ] } ] -l { login command [args	... ] }	-r  {  remote  command
       [args ... ] } [-o { output processing command [args ... ] } ]

DESCRIPTION
       Socketpipe  connects  over a TCP/IP socket the remote command specified
       to the local input generation command and/or the	local output  process-
       ing command.  At	least one of the two local commands must be specified.
       The input and output of the remote command are appropriately redirected
       so  that	the remote command's input will	come from the local input gen-
       eration command and the remote command's	output will be sent to the lo-
       cal  output  processing command.	 The remote command is executed	on the
       machine accessed	through	the login command.  The	socketpipe  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  socketpipe  communication  setup	 is  performed
       through client-server intermediaries such as ssh(1) or rsh(1), the com-
       munication  channel that	socketpipe establishes is a direct socket con-
       nection between the local and the remote	commands.  Without the use  of
       socketpipe, when	piping remote data through ssh(1) or rsh(1), 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
       socketpipe removes the inefficiency of the  multiple  data  copies  and
       context	switches and can in some cases provide dramatic	throughput im-
       provements.  On the other hand, the confidentiality  and	 integrity  of
       the  data  passing  through socketpipe's	data channel is	not protected;
       socketpipe 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; ssh(1) remains secure, rsh(1) continues to	be insecure.)

OPTIONS
       -l { login command [args	... ] }
	      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 socketpipe on the remote host.  Typical ex-
	      amples of	remote login commands are ssh(1) and rsh(1).

       -r { remote command [args ... ] }
	      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 lo-
	      cal commands.

       -i { input generation command [args ... ] }
	      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.

       -o { output processing command [args ...	] }
	      Specify the output processing command  (see  previous  section).
	      The  output  of the remote command is redirected as input	to the
	      output processing	command.

       -b     Execute 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 (ssh(1)) or (horror)	the .rhosts(5) file (rsh(1)).  The op-
	      tion  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 socketpipe instances in the background, stop-
	      ping them	with a tty input signal	(SIGTTIN).  The	-b option 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 lo-
	      gin command and may therefore interfere with any interaction re-
	      quired for the authentication process.

       -h host
	      Specify  the  name  or address of	the local host.	 The specified
	      string is	used by	the remote host	to connect back	to the	origi-
	      nating  local  host.   If	this option is not set,	the local host
	      address with respect to the remote host  is  obtained  automati-
	      cally  by	opening	a connection to	the remote host	and looking at
	      the SSH_CLIENT environment variable.  Setting this option	may be
	      required	when the connection to the remote host is not done via
	      ssh or if	an alternative routing path is preferred.

       -t timeout
	      Specify the time for which the server side  will	wait  for  the
	      client  to  connect.  By default this value is zero, which means
	      that the server side will	wait forever.  Smaller values are use-
	      ful  for	detecting  a  connection problem (e.g. due to incoming
	      connection firewall rules) and exiting with an error.

EXAMPLE
       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	remotehost.

       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)	remotehost.

SEE ALSO
       tcpcat(1), zsh(1)

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

BUGS
       The sockets used	to connect the local and remote	commands may  read  or
       write  only parts of the	data specified in a read(2) or write(2)	opera-
       tion.  Although this is standard	behavior, and is for example correctly
       handled	by  the	 stdio(3) library, some	commands may not expect	it and
       may exhibit strange bugs.  Most examples	in  Stevens's  "Advanced  Pro-
       gramming	 in  the  UNIX	Environment"  (Addison-Wesley 1992) would fail
       reading from sockets; on	the other hand Section 6.6 of Stevens's	 "UNIX
       Network Programming" (Prentice Hall 1990) provides code that deals with
       this problem.

				  5 July 2015			 SOCKETPIPE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLE | SEE ALSO | AUTHOR | BUGS

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

home | help