*****************************************************************
**                    Standard Input Server                    **
*****************************************************************
 
  #-----------------------------------------------------------#  
  #            TITLE : Standard Input Server (SIS)            #  
  #                   TYPE : Server Utility                   #  
  #                       VERSION : 0.1                       #  
  #               AUTHOR : Gamall Wednesday Ida               #  
  #               E-MAIL : gamall.ida@gmail.com               #  
  #              WEBSITE : http://gamall-ida.com              #  
  #                                                           #  
  #                    FILESIZE : ~1600 Ko                    #  
  #            OS Server: GNU/Linux & other Unixes            #  
  #                      OS Client: Any                       #  
  #                 RELEASE DATE : March 2008                 #  
  #-----------------------------------------------------------#  
 
 
 
+   READ ME! (CONTACT)                                           
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-o          +
 
 Should  you  want to contact me, please do NOT jump on my email 
 or spam filefront  comments  or  anything,  you  won't  get  an 
 answer.  And  if  you  do  it  won't  be  what  you expected... 
                                                                 
 Read the "CONTACT" section near the end of  that  file  instead 
 ;-).                                                            
 
 
+   TECHNICAL DESCRIPTION                                        
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-o          +
 
 
   -   Terse Description                                         
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 SIS is a basic server for telnet clients, which retransmits its 
 standard    input    to   all   connected   clients.   Password 
 authentification can be required. Connections and deconnections 
 are logged by IP (and username when  applicable).  Packets  are 
 not encrypted.                                                  
 
 
   -   Why use it?                                               
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 I  suppose  you  could use it as a very crude instant messaging 
 system or whatnot, but that's not what it  was  written  for... 
 
 Let   S   be  a  server  application  (or  any  other  kind  of 
 application) running on a remote computer (of IP address A).  S 
 prints  useful  information  I  on  its  standard output (or on 
 stderr, or both). You want to be able to read I as it is  being 
 written,  from  a  computer  C. You have at least remote access 
 (SSH for instance) to S. But you want other people, without any 
 kind of access to S, to be able to read I from  anywhere.  That 
 is what SIS is for.                                             
 
 Note: I think this kind of situation is quite common, but oddly 
 enough I couldn't find any software solving that problem when I 
 needed  one.  So  I wrote SIS. Maybe I have just reinvented the 
 wheel, maybe not. If you happen to stumble on a  similar  tool, 
 or  if  I  have missed some standard unix trick doing that job, 
 please tell me.                                                 
 
 
   -   How to use it?                                            
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 Of course, 'sis  --help'  displays  the  command-line  options. 
 You'll get something along those lines:                         
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       $ ./sis --help
       
       usage: sis [options]
       
        -port <int>                 : set the netport of the service    (default 1337)
        -user <str name> <str pass> : add user and activates access restriction
        -name                       : name for the server, displayed to the clients
        -disp                       : stdin is displayed on stdout
        -silent                     : logs will not be displayed on stdout
        -pipe                       : pipe mode (for filter chains)
        -delay    <int>             : waiting time, in microseconds    (default 10000)
        -delaysec <int>             : the same in seconds              (default     1)
        --no-logs                   : logs will not be used at all
        --logs-path <str>           : path to the log file
        --lazy-logs                 : log writing will be buffered
        --help                      : display this help page
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 The  obvious  way to get it running is to use a pipe to connect 
 the standard output of S to the standard input of SIS. Assuming 
 the S and SIS executables are both in the PATH:                 
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       S | sis -port P
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 will open the SIS server on port P. Now, from any  computer,  a 
 telnet client can be connected to A on port P, and will display 
 I.                                                              
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       telnet A P
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 You  can  control  who  has access to I by setting up users and 
 passwords. Then any client  has  to  enter  a  username  and  a 
 password  in  order  to  be  able  to use SIS. That username is 
 logged,   alongside   the   IP   address   of   each    client. 
 
 Example session:                                                
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       ./mess | ./sis -user Gamall test 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       $ telnet localhost 1337
       Trying 127.0.0.1...
       Connected to localhost.
       Escape character is '^]'.
       
       ** Standard Input Server v0.1
       ** by Gamall Wednesday Ida
       ** email : gamall.ida@gmail.com
       ** web   : gamall-ida.com
       
       
       --> SIS Client (127.0.0.1:45200)
       --> SIS Server 'Test SIS' (0.0.0.0:1337).
       
       Authentification is required.
       Please enter your username:
       Gamall
       Please enter your password :
       test
       Access granted (Gamall)
       
       READING DATA:
       ================================================================================
       MESSAGE 8
       MESSAGE 9
       MESSAGE 10
       MESSAGE 11
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 
   -   Some Basic Unix Tips                                      
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 NOTE: Some sample programs and their source code are shipped to 
 let  you  test  SIS  locally:  can  can  just run the following 
 samples and see what happens.                                   
 
 STDERR: You may want  to  use  stderr,  and  not  just  stdout. 
 Depending  on the kind of shell on your system, the syntax will 
 be different. A syntax to get both stdout and stderr  is  this: 
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       ./mess 2>&1| ./sis
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 And  if  you  want  to  get  stderr  alone,  you  can  do this: 
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       ./mess 3>&1 1>&2 2>&3 | ./sis
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 FILTERS: SIS retransmits its standard input  just  the  way  it 
 receives  it.  That  does  not prevent you from controlling the 
 information, though. Just write  a  filter  F  (ie.  a  program 
 taking  its  data from stdin and sending the results to stdout) 
 and put it between S and SIS. ('S | F | sis'). I have  provided 
 tiny filters to illustrate that: see `toup.ml' and `tostar.ml'. 
 
 CHAINED  FILTERS:  You may want to run several SIS servers from 
 the same source, but  offering  content  altered  by  different 
 filters.  SIS  lets  you  chain  several filters very easily by 
 using the  -pipe  option.  The  following  example  runs  three 
 different  servers  offering three distinct views from the same 
 source. (remove line breaks, of course)                         
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       ./mess | ./sis -pipe -p 1337 
              | ./toup | ./sis  -pipe -p 1338 
              | ./tostar | ./sis -p 1339
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 Note that in `real life', you may want  to  use  different  log 
 files  for  these three servers. In this example they all share 
 the default log file, which is messy.                           
 
 
   -   The Source Code                                           
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 The source code for SIS  is  released  under  the  GNU  General 
 Public License.                                                 
 
 SIS  is  written in Objective Caml. Plus three or four lines of 
 C, for good measure...                                          
 
 
   -   The Binaries                                              
   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~o          -
 
 SIS is shipped with statically compiled binaries, which may  or 
 may  not  work  on your own system. If they don't you will just 
 have to compile it from source. You will need an OCaml compiler 
 and a C compiler. In most cases, you will just need to run  the 
 build script in the /src directory.                             
 
 
+   APPLICATION TO JKA & JK2 (AND OTHER GAMES)                   
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-o          +
 
 The  initial  reason  for  which  I  wrote  SIS  was to make it 
 possible for JKA server admins to chat with the players  inside 
 the  server  via RCon. The fact that RCon can send messages but 
 not retrive the answers (or simply allow the admin  to  spy  on 
 their   unsuspecting   flock)   is   a   long-time   annoyance. 
 
 Of course, using SIS requires access to the  dedicated  server, 
 and this server must be some flavour of Unix.                   
 
 Assuming  that,  you either run jampded (or jk2ded or whatever) 
 directly from the command line, or through some kind  of  shell 
 script.  Find  it  and  simply  add  '|  sis'  (or '| ./sis' or 
 whatever path works) at the end of the line launching the  game 
 server.                                                         
 
 Needless  to  say,  if  there  is  already  a  standard  output 
 redirection in this line, probably  for  logs  writing,  use  a 
 'tee' to duplicate the stream.                                  
 
 Then  you  can  use  telnet  to  see  what is happening in your 
 server.                                                         
 
 
+   CONTACT                                                      
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-o          +
 
 If you need  help,  or  have  suggestions,  comments,  insults, 
 praise  or  in  general, anything to say about this program you 
 expect me to read and answer to, please post on  the  program's 
 topic on my website:                                            
 
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
       http://gamall-ida.com/f/viewtopic.php?f=3&t=390
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
 
 
+   END OF FILE                                                  
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-o          +
 




























  +-----------------------------+
  | File generated with 'GaTeX',|
  | an ASCII typesetting system |
  | by  Gamall  Wednesday  Ida. |
  |   http://gamall-ida.com     |
  +-----------------------------+
  Build: Sat Mar 15 16:13:01 2008
  File : F:readme-sis.GaTeX.source
