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 --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.
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.
--pidfilefilename 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.
--backlogn 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:
|lw(0.4i)|lw(1.2i)|
|cBw(0.4i)|lBw(1.2i)|.
Short Long
iinoouteerr#nfdnvverbose1onceqquietuunixddaemonsserialpforeignporthforeignhostHlocalhost
For example, the following command
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.
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
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.
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/