faucet

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       faucet - a fixture for a BSD network pipe


SYNOPSIS

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



DESCRIPTION

       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 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 speci-
       fied 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
       -fdn  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 filename
       for a UNIX domain socket.

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

       -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 stan-
       dard ``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, how-
       ever the shutdown of half of the connection  is  automagi-
       cally  done  by certain combinations of the -in, -out, and
       -err flags.  To suppress their automagic behavior you  can
       use (respectively) -fd0, -fd1, and -fd2.

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



SHORT FLAGS

       To  reduce  the  typing requirements for arguments (and to
       pay homage to the age-old tradition of  UNIX  cryptotaxon-
       omy)  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
       be  grouped  into  one argument.  They then grab the argu-
       ments 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 equivalent:

       example$ faucet 3000 -fd0 -fd1 -verbose -once echo blah
       example$ faucet 3000 -#0,1v -once echo blah
       example$ faucet 3000 -1#0,1 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 argu-
       ment.  Also, remember the special shutdown(2) semantics of
       -in and -out.



EXAMPLES

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


       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.



SEE ALSO

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



NOTES

       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.

         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.

       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.



CREDITS

       Thanks to Steve Clift <clift@ml.csiro.au> 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  <fischer@ucet.ufl.edu>  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  <con-
       sult@cis.ufl.edu>  for pointing out the sys_errlist[] dec-
       laration  conflict  on  FreeBSD.   Sometimes  I  hate  Sun
       Microsystems.

       Thanks        to       Daniel       O'Connor       <docon-
       nor@adam.ist.flinders.edu.au> for suggesting the  -pidfile
       flag.



COPYRIGHT

       Copyright (C) 1992,1993,1994,1995,1996 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  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU  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.



AUTHOR

        Robert Forsman
        thoth@purplefrog.com
        Purple Frog Software
        http://www.purplefrog.com/~thoth/
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.