Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HOSE(1)			    General Commands Manual		       HOSE(1)

       hose - the client end of	a BSD network pipe

       netpipes	4.2

       hose  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  lo-
       cal-host] command args

       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-in-
       teractive 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) 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

       --netslave  closes down the connection when it encounters EOF in	either

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

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

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

       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 be-
       havior  should  be unsurprising.	 The flags that	require	separate argu-
       ments follow in the tradition of	tar(1).

       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.

       netpipes	(1), faucet (1), sockdown (1), getpeername  (1),  socket  (2),
       bind (2), connect (2), shutdown (2), services (5), gethostbyaddr	(3)

       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.

       Thanks to Steve Clift <> 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	<> 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 <> finally prodded me into fixing the
       old lame	non-handling of	multi-homed host.

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

       Robert Forsman
	Purple Frog Software

			       October 28, 1998			       HOSE(1)


Want to link to this manual page? Use this URL:

home | help