hose
Hurricane Electric Internet Services
NAME
hose - the client end of a BSD network pipe
SYNOPSIS
hose hostname port (-in|-out|-err|-fdn|-slave) [-verbose]
[-unix] [-localport port] [-localhost addr] [-retry n]
[-delay n] [-shutdown [r|w][a] ]
[-[i][o][e][#3[,4[,5...]]][s][v][u]] [-p local-port] [-h
local-host] command args
DESCRIPTION
hose attempts to provide the functionality of pipes over
the network. It behaves as the client end of a
server-client connection. When used with faucet(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 machine.
hose creates a BSD socket and, if the -localport option is
used, binds it to the port number (or service name) speci-
fied immediately afterwards. If -localhost is also speci-
fied then its argument is a local address to bind to. (
-localhost is only useful on machines with multiple IP
addresses.)
hose then tries to connect to the foreign machine hostname
with foreign port port.
If successful hose redirects the socket to stdin, stdout,
stderr, and/or arbitrary file descriptors according to the
-in -out -err -fdn flags. hose 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.
hose then exec(2)s a command with args.
However, the -slave flag turns hose into a primitive sort
of telnet. The command is ignored. Instead, hose goes
into a loop where it copies bytes from stdin to the
socket, and bytes from the socket to stdout. This is
actually more useful than telnet because telnet tries to
perform interpretation on the byte stream and generally
gets in your way. hose just passes bytes without mucking
with them.
The -verbose flag specifies that hose should print infor-
mation about the host it connects to. This information
includes the numeric host address, host names, and foreign
port numbers.
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. This option may be simulated by
using -unix- as the host name to connect to, or by renam-
ing the hose program to uhose.
-retry n allows the user to specify that should retry the
connect(2) call for n times (or forever if n is negative).
-delay n specifies how many seconds to delay between
tries.
-shutdown is used to control two behaviors. The first set
is controlled by the `r' and `w' flags.
If the `r' is present, then hose will close half the
connection to make it a read-only socket. If the child
tries 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 hose will close the
other half of the connection to make it a write-only
socket. If the child tries to read, it 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.
The other behavior is controlled by the `a' flag. If the
`a' flag is present then hose will fork(2) before execcing
the command and when the child exits it will perform a
shutdown(2) with how=2. This closes both halves of the
connection. This option is not necessary for most appli-
cations since the closing of the file descriptors is
detected by the remote process, but some less sophisti-
cated network devices (such as printers) require a shut-
down(2) for proper operation.
To make things perfectly clear, the list of acceptable
arguments to the -shutdown option are `r', `w', `ra',
`wa', `a'.
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
s slave
v verbose
q quiet
u unix
p localport
h localhost
See faucet(1) for a more detailed discussion of short
flags. Their behavior should be unsurprising. The flags
that require separate arguments follow in the tradition of
tar(1).
EXAMPLES
This will connect to port 3000 on the machine reef and
connect the socket to the stdin of a tar command.
example$ hose reef 3000 -in tar -xf - .
The command actually exec(2)ed by the hose program is
tar -xf - .
The -in option means that the input of the child process
will have been redirected into the socket connected to
reef.
This connects to a UNIX domain socket in the current
directory
example$ hose -unix- u-socket -in csh -c \
"unfunky.perl.script | dd of=sample.pgm"
The socket provides input to the csh command.
SEE ALSO
netpipes(1), faucet(1), sockdown(1), getpeername(1),
socket(2), bind(2), connect(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. -foreignport
authentication was weakened by this inadequacy so I beefed
up the algorithms. -foreignport
will accept a connection from any of the internet numbers
associated with the host name.
3.1 added the single-character flags.
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.
Thanks to Sten Drescher <smd@hrt213.brooks.af.mil> for the
-retry and -delay patches and giving me the idea for the
-shutdown option. Evidently some printer doesn't appreci-
ate the socket being close(2)d.
Randy Fischer <fischer@ucet.ufl.edu> finally prodded me
into fixing the old lame non-handling of multi-homed host.
COPYRIGHT
Copyright (C) 1992,1993,1994,1995 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@cis.ufl.edu
Purple Frog Software
http://www.purplefrog.com/~thoth/
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.