Man Linux: Main Page and Category List


       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-interactive  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
       command 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
       redirected according to the --in --out --err --fd n flags.  faucet also
       automagically 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
       instead  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
       connections  that  do  not  come  from  the  host  machine.   Similarly
       --foreignport  specifies that faucet should reject all connections that
       are not bound on their local machine to the port argument.   The  above
       two  options  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

       --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
       controlling 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
       TIOCNOTTY, 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
       remote  connection  tries to write, it will fail.  The default behavior
       is to leave both halves open, however  the  shutdown  of  half  of  the
       connection  is  automagically done by certain combinations of the --in,
       --out, and --err flags.  To suppress their automagic behavior  you  can
       use (respectively) --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
       connection  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
       critical-section management.

       --pidfile filename  commands  faucet  to  write  its  process  id  into
       filename.   This is useful when faucet is part of a larger system and a
       controlling 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
       system  call,  and  revert to pre-4.1 behavior.  Without this call, the
       socket is not always available for immediate  reuse  after  the  faucet

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

       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

       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
       often  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
       specification  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
       suggesting 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_REUSEADDR  patch  in my lap.  Otherwise I wouldn’t have gotten to it
       till 2001.


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


       Robert Forsman
        Purple Frog Software

                               October 28, 1998