hose

Hurricane Electric Internet Services: Accounts starting at $9.95/month
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: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.