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