faucet
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
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.