Provided by: netpipes_4.2-7_amd64 bug

NAME

       faucet - a fixture for a BSD network pipe

       netpipes 4.2

SYNOPSIS

       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

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

OPTIONS

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

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

SHORT FLAGS

       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         │
       │  iin           │
       │  oout          │
       │  eerr          │
       │ #nfdn          │
       │  vverbose      │
       │  1once         │
       │  qquiet        │
       │  uunix         │
       │  ddaemon       │
       │  sserial       │
       │  pforeignport  │
       │  hforeignhost  │
       │  Hlocalhost    │
       └──────┴──────────────┘
       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 equivalent:

       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.

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.

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

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

SEE ALSO

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

BUGS

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

       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.

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.

       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.

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 <consult@cis.ufl.edu> for pointing out
       the sys_errlist[] declaration conflict on FreeBSD.  Sometimes I hate Sun Microsystems.

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

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

       Thanks to Thomas A. Endo <tendo@netcom.com> for dropping an SO_REUSEADDR patch in my  lap.
       Otherwise I wouldn't have gotten to it till 2001.

COPYRIGHT

       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 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://web.purplefrog.com/~thoth/

                                         October 28, 1998                               FAUCET(1)