HOSE(1)HOSE(1)NAMEhose - the client end of a BSD network pipe
netpipes 4.2
SYNOPSIShose hostname port (--in|--out|--err|--fd n|--slave|--netslave|--net‐
slave1|--netslave2) [--verbose] [--unix] [--localport port] [--local‐
host addr] [--retry n] [--delay n] [--shutdown [r|w][a] ] [--noreuse‐
addr] [-[i][o][e][#3[,4[,5...]]][s][v][u]] [-p local-port] [-h
local-host] command args
DESCRIPTIONhose 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
non-interactive access to the destination machine.
OPTIONShose creates a BSD socket and, if the --localport option is used, binds
it to the port number (or service name) specified immediately after‐
wards. If --localhost is also specified then its argument is a local
address to bind to. ( --localhost is only useful on machines with mul‐
tiple 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
--fd n 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 per‐
form interpretation on the byte stream and generally gets in your way.
hose just passes bytes without mucking with them.
The --netslave* options are variants on the --slave theme. Whereas
--slave will continue to forward data in one direction even after the
other has encountered EOF, --netslave variants are more aggressive in
closing the entire socket. Before closing the socket, it attempts to
flush any data already in its own buffer. --slave performs the shut‐
down(2) system call when it encounters EOF on one direction, but the
--netslave variants don't because some network daemons are confused by
it.
--netslave closes down the connection when it encounters EOF in either
direction.
--netslave1 closes down the connection when it encounters EOF while
reading stdin. Any data unread on the socket will be ignored. If it
merely encounters EOF on the socket, it will continue to read from
stdin.
--netslave2 closes down the connection when it encounters EOF while
reading from the socket. Any data unread on stdin will be ignored. If
it merely encounters EOF on stdin, it will continue to read from the
socket. This mode can be useful with some web servers.
The --verbose flag specifies that hose should print information 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 con‐
nect to, or by renaming the hose program to uhose.
--retry n allows the user to specify that hose should retry the con‐
nect(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 con‐
trolled 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, 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.
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 sophisticated network devices (such as
printers) require a shutdown(2) for proper operation. To make things
perfectly clear, the list of acceptable arguments to the --shutdown
option are `r', `w', `ra', `wa', `a'.
By default, hose performs a
which prevents the ``Address in use'' problem that ``plagued'' netpipes
versions 4.0 and earlier. --noreuseaddr tells hose to skip that system
call, and revert to pre-4.1 behavior. Without this call, the port is
not always available for immediate reuse after the hose exits.
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 │
│ 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 argu‐
ments 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 sh -c \
"unfunky.perl.script | dd of=sample.pgm"
The socket provides input to the sh 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.
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.
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.
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. Evi‐
dently some printer doesn't appreciate 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-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 MER‐
CHANTABILITY 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 HOSE(1)
