Ubuntu Manpage: hose - the client end of a BSD network pipe

NAME

       hose - the client end of a BSD network pipe

       netpipes 4.2

SYNOPSIS

       hose   hostname  port  (--in|--out|--err|--fd  n|--slave|--netslave|--netslave1|--netslave2)  [--verbose]
       [--unix]  [--localport  port]  [--localhost  addr]  [--retry  n]  [--delay  n]  [--shutdown  [r|w][a]   ]
       [--noreuseaddr] [-[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 non-interactive access to the  destination
       machine.

OPTIONS

hose creates a BSD socket and, if the --localport option is used, binds it to the port number (or service
name) specified immediately afterwards. If --localhost is also specified 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 --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 perform 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 shutdown(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
connect to, or by renaming the hose program to uhose.

--retry n allows the user to specify that hose 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, 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 applications 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 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 sh -c \
            "unfunky.perl.script | dd of=sample.pgm"

       The socket provides input to the sh command.

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

                                                October 28, 1998                                         HOSE(1)