Man Linux: Main Page and Category List

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.

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