home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / unix / volume26 / faucet / part01 / README < prev   
Text File  |  1993-01-29  |  7KB  |  194 lines
  1.  
  2. "Mutant" Bob Forsman and his amazing 43 burner stove present
  3. ------------------------------------------------------------
  4.             "stuff"
  5. ------------------------------------------------------------
  6.  
  7.   This directory contains faucet and hose.
  8.  
  9.  
  10.  
  11. faucet and hose:
  12.  
  13.   These two utilities are useful for connecting arbitrary programs
  14. over sockets.  The power of the '|' characeter in the shell can now be
  15. used over the network.
  16.   As an example of what they can do, compile them and on one machine
  17. type
  18.  
  19. lightning:21 % ./faucet 3000 "tar cf - ." out
  20.  
  21.  and on another type
  22.  
  23. springs:3 % ./hose lightning 3000 "tar tvf -" in
  24.  
  25.   You will get output (from machine springs) that looks like this.
  26.  
  27. rwxr-xr-x771/50      0 Jul  7 11:53 1990 ./
  28. rw-r-----771/50   9266 Jun 30 21:41 1990 ./faucet.c~
  29. rw-r--r--771/50   6086 Mar  6 21:40 1990 ./server.cc
  30. rw-r--r--771/50   1203 Jul  7 11:49 1990 ./Makefile
  31. rw-r-----771/50   9757 Jul  7 11:49 1990 ./faucet.c
  32. rw-r--r--771/50   4241 Jun 23 04:09 1990 ./hose.c~
  33. rwxr-xr-x771/50  24576 Jul  7 11:50 1990 ./hose
  34. rw-r--r--771/50   4041 Jul  7 11:50 1990 ./hose.c
  35. rw-r-----771/50    592 Jul  7 11:48 1990 ./portname.c
  36. rw-r--r--771/50    317 Jul  7 11:48 1990 ./portname.o
  37. rwxr-xr-x771/50  24576 Jul  7 11:50 1990 ./faucet
  38. rw-r--r--771/50   3378 Jul  7 11:50 1990 ./hose.o
  39. rw-r--r--771/50   1069 Jun 23 02:42 1990 ./Makefile~
  40. rw-r--r--771/50   4662 Jul  7 11:50 1990 ./faucet.o
  41. rw-r-----771/50    377 Jul  7 11:53 1990 ./#README#
  42. rw-r-----771/50    371 Jul  7 11:53 1990 ./README
  43. rw-r--r--771/50   2917 Mar  6 22:13 1990 ./client.cc
  44.  
  45.   The 3000 is the port number to connect to.  Normal users can use any
  46. number over 1023.  You can also specify a service name in place of a
  47. number since the program can look it up from the services database.
  48.   The argument in ""s (argv[2] for faucet, argv[3] for hose) is the
  49. command to be connected to the socket.  The flags in, out and err
  50. govorn which file descriptors get connected to the socket after the
  51. connection is successful.
  52.   hose is a one-shot program.  It connects to the foreign server
  53. socket and execs the command.  faucet is an undying server.  Every
  54. time it recieves a connection on its socket it forks and execs a "csh
  55. -c".  faucet can be limited to one-shot by the "once" flag.
  56.  
  57. SYNTAX
  58.  
  59.    faucet <port> <command> (in|out|err)+ [once] [verb(|ose)] [quiet]
  60.         [unix] [foreignport <port>] [foreignhost <host>]
  61.  
  62.    hose <hostname> <port> <command> (in|out|err)+ [unix] [localport <port>]}
  63.  
  64.   Host names can be be the name of the machine or (if no name is
  65. found) the internet number.  The individual numbers are sscanfed with
  66. %i so 0x or 0 prefixes mean hex or octal instead of decimal for that
  67. one byte.
  68.   You must chose at least one of in, out, and err.  The other flags
  69. are optional and listed below
  70.    unix.........causes the program to go into unix-domain socket mode.
  71.         hose can also be forced into unix-domain operation by
  72.         specifying -unix- as the hostname (those dashes are
  73.         part of the arg) or by being run with argv[0] as the
  74.         string "uhose" (possible by hardlinking the binary).
  75.         Port names are then treated as unix domain socket
  76.         addresses (filenames) as opposed to internet port
  77.         numbers.
  78.    localport....(only on hose) asks hose to bind to a specific local
  79.         port.
  80.    once.........(only on faucet) the faucet command will not fork, but
  81.         will exec the command, and when the command exits
  82.         you're done.
  83.    verbose|quiet (only on faucet) enables|disables the printing of
  84.         extra information such as what host and port faucet is
  85.         getting connections from.
  86.    foreignport..(only on faucet) causes faucet to refuse (close
  87.         immediately) any connection from a machine that hasn't
  88.         bound its socket to the port specified immediately
  89.         after the foreignport flag.  This can be used with the
  90.         localport option of hose to perform crude
  91.         authentication.  If the foreignport is <1024 then only
  92.         a foreign root user will be able to connect to your
  93.         faucet because only root can bind to a port number
  94.         below 1024.
  95.    foreignhost..(only on faucet) causes faucet to refuse (close
  96.         immediately) any connection from any machine other
  97.         than the host specified immediately after the
  98.         foreignhost flag.
  99.  
  100.   Be aware that addresses and ports can be spoofed if your network
  101. isn't secure (yours probably isn't).  If you have PCs or other
  102. non-UNIX boxes connected to the network, then it's DISGUSTINGLY easy
  103. for ANYONE to spoof the network.
  104.  
  105.  
  106.  
  107. EXAMPLES
  108.  
  109.     FAUCET                    HOSE
  110.  
  111. reef:100 % ./faucet chat "echo send
  112. $14M and 2 airline stewardesses or
  113. you'll never see Hoffa alive"
  114. foreignhost azalea verbose out
  115.  
  116.                 reef:40 % ./hose reef chat cat in
  117.  
  118. refusing connection from host 128.
  119. 227.224.61(reef.cis.ufl.edu).
  120.  
  121.                 azalea:20 % ./hose reef chat cat in
  122.  
  123. ./faucet: Got connection from 128.
  124. 227.224.55(azalea.cis.ufl.edu) port
  125. 1687
  126. Unmatched '.
  127.                 /* darn, screwed up the shell quoting */
  128. ^C
  129.  
  130. reef:107 % ./faucet /tmp/blah 'echo
  131. send '\'\$14M\'' and 2 airline
  132. stewardesses or you'\\\''ll never
  133. see Hoffa alive' foreignhost azalea
  134. verbose out foreignport /tmp/auth unix
  135. ./faucet: foreignhost parameter makes no
  136. sense with UNIX domain sockets, ignoring.
  137.                 /* %#@)*, bite me */
  138.  
  139.                 reef:41 % ./hose -unix- /tmp/blah cat in
  140.  
  141. ./faucet: refusing connection from port
  142.  
  143.                 reef:43 % ./hose -unix- /tmp/blah cat in
  144.                 localport /tmp/auth
  145.  
  146. ./faucet: Got connection from /tmp/auth
  147.  
  148.                 send $14M and 2 airline stewardesses or
  149.                 you'll never see Hoffa alive
  150.  
  151.  
  152.   Notice the elaborate quoting on that one.  faucet+hose fork a "csh
  153. -c " to interpret the command.  The echo command had to be quoted so
  154. that faucet saw:
  155.  
  156. echo send '$14M' and 2 airline stewardesses or you\'ll never see Hoffa alive
  157.  
  158.   faucet then performed this system call
  159.  
  160. execl("/bin/csh","csh","-c",argv[2],NULL);
  161.  
  162.   and the "$14M" and "you'll" were properly quoted to survive THAT csh
  163. as well.  Commands to hose must be similarly protected.
  164.  
  165.   Why use csh?
  166.    1) This allows you to have pipelines and other fancy stuff inside
  167.     the command, and
  168.    2) I don't have to write code to parse the command!
  169.  
  170.  
  171.  
  172. BUGS
  173.  
  174.   Hoohoohoo, god knows what sort of bugs are waiting to rip your
  175. ankles off.  I'm the only one who's extensively used these.  They were
  176. developed on Sun3s and Sun4s.  They have been compiled (but not
  177. extensively tested) on Sonys, DECstations and HPs.  If your machine
  178. needs different include files, start grepping and mail me the results.
  179.  
  180.   If anything is not crystal clear, check the source and mail me.
  181. I'll try to put it in the README.
  182.  
  183.   I need to dragoon someone into writing a man page for this.
  184.  
  185.  
  186. AUTHOR
  187.  
  188.   Robert H. Forsman Jr.        <thoth@lightning.cis.ufl.edu>
  189.   former underpaid Systems Programmer
  190.   now piddly underpaid Research Assistant
  191.   University of Florida
  192.   Department of Computer
  193.   and Information Science
  194.