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

FreeBSD Manual Pages


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

       faucet -	a fixture for a	BSD network pipe

       netpipes	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

       faucet attempts to provide the functionality of pipes over the network.
       It  behaves as the server end of	a server-client	connection.  When used
       with hose(1) it can function as a replacement for

       tar -cf - . | rsh other "cd destdir; tar	-xf -"

       faucet and hose are especially useful when you don't have easy  non-in-
       teractive  access  to  the  destination account (such as	a root account
       where .rhosts are a bad idea).

       faucet creates a	BSD socket, binds it to	the port specified on the com-
       mand line, and listens for connections.

       Every  time  faucet  gets a connection it exec(2)s command and its args
       with stdin, stdout, stderr, and/or  arbitrary  file  descriptors	 redi-
       rected according	to the --in --out --err	--fd n flags.  faucet also au-
       tomagically shuts down the unused half of the connection	if  only  --in
       is  specified  or  if  only  --out and/or --err are specified.  See the
       --shutdown option for more information.

       If the --once flag is specified,	faucet will exec(2)  the  command  in-
       stead of	fork(2)ing and exec(2)ing.  --once means that the network pipe
       is only good for	one shot.

       The --verbose flag specifies that faucet	should print information about
       connecting  hosts.  This	information includes the numeric host address,
       host names, and foreign port numbers.  The --quiet flag specifies  that
       faucet should NOT print such info.  --quiet is the default.

       The  --unix flag	specifies that the port	is not an internet port	number
       or service name,	but instead it is  a  file  name  for  a  UNIX	domain

       The  --foreignhost  option specifies that faucet	should reject all con-
       nections	that do	not come from the host machine.	 Similarly  --foreign-
       port  specifies	that faucet should reject all connections that are not
       bound on	their local machine to the port	argument.  The above  two  op-
       tions  allow a crude form of authentication.  Note that on UNIX systems
       only root can bind a socket to a	port number below 1024.

       Please do not be	fooled into thinking this makes	faucet secure.	 There
       are  ways  to spoof IP numbers that have	been known for years (but only
       publicized recently).  I	do think that this method  is  safe  from  DNS
       spoofs, but you probably	should have  nospoof on	in /etc/host.conf any-

       --localhost specifies that the listening	socket should be  bound	 to  a
       specific	 internet  address on this host.  This is only useful on hosts
       with several internet numbers.

       --daemon	specifies that the faucet should disassociate  from  the  con-
       trolling	terminal once it has started listening on the socket.  This is
       done using the setsid() system call.  If	you don't have setsid on  your
       system,	it uses	the standard ``close all file descriptors, ioctl TIOC-
       NOTTY, fork() and parent	exit'' sequence.

       --shutdown is used to turn the (normally) bi-directional	socket into  a
       uni-directional	one If the `r' is present, then	faucet will close half
       the connection to make it a read-only socket.  If we try	to  write,  it
       will  fail.   If	 the remote connection tries to	read, it will percieve
       the socket as closed.  If instead the `w' is present, then faucet  will
       close  the other	half of	the connection to make it a write-only socket.
       If we try to read, we will percieve the socket as closed.  If  the  re-
       mote  connection	tries to write,	it will	fail.  The default behavior is
       to leave	both halves open, however the shutdown of half of the  connec-
       tion  is	automagically done by certain combinations of the --in,	--out,
       and --err flags.	 To suppress their automagic behavior you can use (re-
       spectively) --fd	0, --fd	1, and --fd 2.

       --shutdown  may not be used with	some internet servers (such as certain
       httpds) because they interpret the closing of one half of  the  connec-
       tion  as	 a  close  on  the entire connection.  This warning applies to
       --in, --out, and	--err.

       --serial	causes faucet to wait for one child to finish before accepting
       any  more  connections.	 Serialization	is a very crude	form of	criti-
       cal-section management.

       --pidfile filename commands faucet to write its process id  into	 file-
       name.  This is useful when faucet is part of a larger system and	a con-
       trolling	process	might want to kill the	faucet.	  --pidfile  functions
       properly	when using the --daemon	 option.

       By default, faucet performs a

       setsockopt(fd, SOL_SOCKET, SO_REUSEADDR...)

       which prevents the ``Address in use'' problem that ``plagued'' netpipes
       versions	4.0 and	earlier.  --noreuseaddr	tells faucet to	skip that sys-
       tem  call,  and	revert	to  pre-4.1  behavior.	Without	this call, the
       socket is not always available for immediate reuse after	the faucet ex-

       --backlog n allows you to specify the second parameter to the listen(2)
       system call.  The default is 5.

       To reduce the typing requirements for arguments (and to pay  homage  to
       the  age-old  tradition of UNIX cryptotaxonomy) I have added some short
       forms of	the flags.  Here is a correspondence chart:

       |      |		     |
       |Short |	Long	     |
       |  i   |	in	     |
       |  o   |	out	     |
       |  e   |	err	     |
       | #n   |	fdn	     |
       |  v   |	verbose	     |

       |  1   |	once	     |
       |  q   |	quiet	     |
       |  u   |	unix	     |
       |  d   |	daemon	     |
       |  s   |	serial	     |
       |  p   |	foreignport  |
       |  h   |	foreignhost  |
       |  H   |	localhost    |

       For example, the	following command

       example$	faucet 3000 --out --verbose --once --foreignhost client	echo blah

       could be	written

       example$	faucet 3000 -ov1h client echo blah

       The -p, -h, and -H flags	take an	argument, but the flags	may be grouped
       into  one  argument.   They  then grab the arguments they need from the
       command line in the order the flags appear.

       example$	faucet 3000 -hpHov1 client 2999	example-le2 echo blah

       Whereas each --fd word flag required an individual descriptor,  the  -#
       character flag can take multiple	descriptors.  The following are	equiv-

       example$	faucet 3000 --fd 0 --fd	1 --verbose --once echo	blah
       example$	faucet 3000 -#0,1v --once echo blah
       example$	faucet 3000 -v1#0,1 echo blah
       example$	faucet 3000 -#0,1v1 echo blah

       Note that you have to pay attention when	using the  -#  character  flag
       and  the	 -1  character	flag in	the same argument.  Also, remember the
       special shutdown(2) semantics of	-in and	-out.

       This creates a TCP-IP socket on the local machine bound to port 3000.

       example$	faucet 3000 --out --verbose tar	-cf - .

       Every time some process (from any machine) attempts to connect to  port
       3000  on	this machine the faucet	program	will fork(2) a process and the
       child will exec(2) a

       tar -cf - .

       The --out option	means that the output of the child process  will  have
       been  redirected	 into  the new socket retrieved	by the accept(2) call.
       --verbose means that faucet will	print information about	each new  con-

       This creates a UNIX domain socket in the	current	directory

       example$	faucet u-socket	--out --err --once --unix csh -c \
	     "dd if=angio.pgm |	funky.perl.script"

       The  --out --err	option means that stdout and stderr will be redirected
       in the child process.  The --once option	means that the faucet will not
       fork(2),	 but  exec(2)  the  process so that only the first process can
       connect to the u-socket before the faucet becomes unavailable.

       This example listens on a  socket  until	 the  first  connection	 comes
       through.	  It  then spawns a bidirectional copy that is similar to hose

       faucet 3000 -1v --fd 3 sh -c 'cat <&3 & cat >&3 ; sockdown 3'

       netpipes	(1), hose (1), sockdown	(1), getpeername (1), socket (2), bind
       (2),  listen (2), accept	(2), shutdown (2), services (5), gethostbyaddr

       There is	a problem with almost every OS I have used faucet  on.	 Ports
       are  sometimes not recycled swiftly enough.  If you kill	one faucet and
       try to start another that wants to listen on the	same port you will of-
       ten  see	 pre-4.1  faucets  print  the  following warning over and over

       faucet: Address 3000 in use, sleeping 10.
       faucet: Trying again . .	.

       but you won't actually  be  able	 to  connect(2)	 to  that  port	 (with
       hose(1),	for example) because you'll get	a ``connection refused''.

       There  was  also	an experimental	Linux kernel that NEVER	recycled ports
       (I quickly switched back	to my old kernel).

       I have been informed that this is a side-effect of the  TCP  specifica-
       tion  and  that I should	use the	SO_REUSEADDR option to work around it,
       so I do.

       Doubtless there are bugs	in this	program, especially in the unix	domain
       socket  portions.   I  welcome  problem	reports	and would like to make
       these programs as "clean" (no leftover files, sockets) as possible.

       4.1 added --backlog and --noreuseaddr.  --noreuseaddr reflects the fact
       that 4.1	also added the SO_REUSEADDR socket option as the default.

       4.0  made  the full-word	arguments use -- like many GNU programs.  They
       are still available with	a single - for backward-compatibility.

       3.1 added the single-character flags and	the -pidfile option.  It  also
       switched	to the setsid(2) system	call to	detach itself from the process
       group for the -daemon flag.  I've been hacking at UNIX for  years,  but
       there  are  still  some	things that I never really learned, and	others
       that have been changing.	 I need	to buy a book.

       Release 2.3 added support for multi-homed hosts:	 hosts	with  multiple
       internet	 numbers  (such	as gateways).  Before this faucet assumed that
       the first internet number that gethostbyname returned was the only one.
       --foreignhost  authentication  was  weakened  by	 this  inadequacy so I
       beefed up the algorithms.  --foreignhost	will accept a connection  from
       any of the internet numbers associated with the host name.

       Thanks to Steve Clift <> for SGI (SysV)	patches.

       Many  people  complained	 about	the old	way of specifying the command.
       Thanks to whoever gave me the alternative which is now implemented.  It
       is much better.

       Randy Fischer <> finally prodded me into fixing the
       old lame	non-handling of	multi-homed host.

       Thanks to all who suggested I use setsid() for -daemon mode.

       Thanks to the Spring 1996 UF CIS	consulting staff <>
       for  pointing  out  the	sys_errlist[] declaration conflict on FreeBSD.
       Sometimes I hate	Sun Microsystems.

       Thanks to Daniel	O'Connor <> for  sug-
       gesting the -pidfile flag.

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

       Thanks to Thomas	A. Endo	<> for dropping	 an  SO_REUSE-
       ADDR  patch  in	my  lap.   Otherwise I wouldn't	have gotten to it till

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

       Robert Forsman
	Purple Frog Software

			       October 28, 1998			     FAUCET(1)


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

home | help