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

FreeBSD Manual Pages


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

       netpipes	- a package to manipulate BSD TCP/IP stream sockets

       version 4.2

       faucet  port  (--in|--out|--err|--fd n)+	[--once] [--verbose] [--quiet]
       [--unix]	[--foreignhost addr] [--foreignport port]  [--localhost	 addr]
       [--serial]   [--daemon]	 [--shutdown   (r|w)  ]	 [--pidfile  filename]
       [--noreuseaddr]			    [--backlog			    n]
       [-[i][o][e][#3[,4[,5...]]][v][1][q][u][d][s]]   [-p  foreign-port]  [-h
       foreign-host] [-H local-host] command args

       hose  hostname  port  (--in|--out|--err|--fd   n|--slave)   [--verbose]
       [--unix]	 [--localport port] [--localhost addr] [--retry	n] [--delay n]
       [--shutdown	      [r|w][a]		  ]	       [--noreuseaddr]
       [-[i][o][e][#3[,4[,5...]]][s][v][u]]  [-p  local-port]  [-h local-host]
       command args

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

       ssl-auth	--fd n ( --server | --client ) [ --cert	file ] [ --key file  ]
       [  --verbose  ]	[  --verify n ]	[ --CApath path/ ] [ --CAfile file ] [
       --cipher	cipher-list ] [	 --criteria  criteria-expr  ]  [  --subproc  [
       --infd n	] [ --outfd n ]	] [ -[#n][v][s[in][on]]	]

       sockdown	[fd [how] ]

       getpeername [ -verbose ]	[ -sock	] [ fd ]

       getsockname [ -verbose ]	[ -peer	] [ fd ]

       timelimit [ -v ]	[ -nokill ] time command args

       The  netpipes package makes TCP/IP streams usable in shell scripts.  It
       can also	simplify client/server code by allowing	the programmer to skip
       all  the	tedious	programming bits related to sockets and	concentrate on
       writing a filter/service.

       ``Why would anyone want to do that?''
	-- Richard Stallman

       faucet is the server end	of a TCP/IP stream.  It	listens	on a  port  of
       the  local  machine waiting for connections.  Every time	it gets	a con-
       nection it forks	a process to perform  a	 service  for  the  connecting

       hose  is	 the client end	of a TCP/IP stream.  It	actively connects to a
       remote port and execs a process to request a service.

       encapsulate is an implementation	of the Session Control	Protocol.   It
       allows you to multiplex several streams across a	single TCP session and
       also transmits remote exit status.

       ssl-auth	is an encryption filter	that encapsulates stdin/stdout from  a
       subprocess  (or its own stdin/stdout) in	the Secure Socket Layer	proto-
       col as implemented by the SSLeay	library.  It can be used  to  communi-
       cate  with  encrypted  daemons (HTTPS daemons, or SSL IMAP daemons) and
       can sometimes be	used to	jury-rig secure	versions of such services.

       sockdown	is a simple program designed to	shut down part or all  of  the
       socket connection.  It is primarily useful when the processes connected
       to the socket perform both input	and output.

       getpeername and getsockname are two names for  a	 program  designed  to
       print  out  the	addresses of the ends of a socket.  getpeername	prints
       the address of the remote end and getsockname prints the	address	of the
       local end.

       timelimit  limits the amount of foreground wallclock time a process can
       consume.	 After the time	limit runs out it either kills the process  or
       exits and leaves	it in the background.

       Here  is	 a  simple command I often perform to transfer directory trees
       between machines.  (rsh does not	work because one machine is  connected
       using SLIP and .rhosts are out of the question).

       server$ faucet 3000 --out tar cf	- .
       client$ hose server 3000	--in tar xvf -

       Here is a minimal HTTP client.  It is so	minimal	it speaks old HTTP.

       cairo$ hose 80 --in --out \
	    sh -c "(echo 'GET /'; sockdown) & cat > result"

       And of course, there is Nick Trown's metaserver for Netrek

       cairo$ hose	3521 --in cat

       Allow  me to apologize ahead of time for	the convolutedness of the fol-
       lowing example.	It requires an understanding of	Bourne shell file  de-
       scriptor	 redirection  syntax  (and  illustrates	 why csh and tcsh suck
       eggs).  Do not try to type this from your tcsh  command	line.	Get  a
       bash (GNU's Bourne Again	SHell).

       Suppose	you  want to distinguish between stdout	and stderr of a	remote

       remote$ faucet 3000 --fd	3 \
	  encapsulate --fd 3 --infd 0 --outfd 1	--outfd	2 --subproc \
       local$ hose remote 3000 --fd 3 \
	  encapsulate --fd 3 --outfd 3 --infd 4	--infd 5 --subproc \
	    sh -c "cat 0<&4 3>&- & cat 0<&5 1>&2 3>&- &	\
		cat 1>&3 ; exec	3>&-"

       Close all unneeded file descriptors when	you spawn a  background	 task.
       That's why the backgrounded cats	have 3>&-.

       server$ faucet 3000 --in	--out --verbose	enscript -2rGhp	-
       client$ ps aux |	hose server 3000 --in --out \
	    sh -c " (cat <&3; sockdown ) & cat >&4 " 3<&0 4>&1 | \
	    lpr	-Pps422
       #or perhaps this, but I haven't tested it
       client$ ps aux |	hose server 3000 --fd 3	\
	    sh -c " (cat >&3; sockdown 3 ) & cat <&3 " | \
	    lpr	-Pps422

       This  proves  that  hose	can be used as part of a pipeline to perform a
       sort of remote procedure	call (RPC).  After you have figured  out  that
       example,	you will know how to use Bourne	shell to shuffle file descrip-
       tors around.  It	is a handy skill.

       Now we go to the	extreme, but simplify things by	using the --slave  op-
       tion of hose.  The following is a socket	relay

       gateway$	faucet 3000 -io	hose server 4000 --slave

       It's  a	handy little bugger when you want to tunnel through a firewall
       on an occasional	basis.	If you experience ``hanging'' of  the  connec-
       tion, try using the --netslave option instead of	--slave. (telnet prox-
       ies would benefit from this)

       For those of you	who use	ssh, here's how	 to  tunnel  some  information
       through an encrypted SSH	port forward.

       server$ faucet 3000 -1v --fd 1 --foreignhost server echo	blah
       client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
       client$ hose localhost 3000 --fd	0 -retry 10 cat

       The  trick  with	 ssh's port forwarding,	is that	the shutdown(2)	system
       call causes ssh to close	both halves of the full-duplex connection  in-
       stead  of only one half.	 That's	why you	have to	use --fd 1 and --fd 0.
       If you need to be able to close half of the connection while still  us-
       ing the other, use the encapsulate wrapper.

       server$ faucet 3000 -1v --fd 3 --foreignhost server \
	    encapsulate	--fd 3 --server	-si0o1 tr a-z A-Z
       client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
       client$ echo blah | hose	localhost 3000 --fd 3 -retry 10	\
	    encapsulate	--fd 3 --client

       faucet (1),  hose (1),  encapsulate (1),	sockdown (1), getpeername (1),
       timelimit (1), ssl-auth (1)

       Report any bugs or feature requests to

       Thanks to Harbor	Development Inc. for funding some of the netpipes  de-

       Thanks  to  Michal  Jaegermann  <> for
       some bug	fixes and glibc	portability suggestions	against	4.1.1 .

       Big thanks to Joe Traister <> for his signal  handling
       patches,	strerror surrogate, and	other assorted hacks.

       Copyright (C) 1995-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-
       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.

       Export Version:

       U.S./Canada  version with ssl-auth:	, then
       find it in the network/ subdirectory.

       Robert Forsman
	Purple Frog Software

			       October 28, 1997			   NETPIPES(1)


Want to link to this manual page? Use this URL:

home | help