
// Gamall Wednesday Ida

\style{FILEFRONT}
\output{F:\README.txt}

\header
Standard Input Server
\end

\modinfos
	TITLE   : Standard Input Server (SIS)		\line
	TYPE    : Server Utility					\line
	VERSION : 0.1					\line
	AUTHOR  : Gamall Wednesday Ida		\line
	E-MAIL  : gamall.ida@gmail.com		\line
	WEBSITE : http://gamall-ida.com		\line
	\line

	FILESIZE          : ~1600 Ko			\line
	OS Server: GNU/Linux & other Unixes \line
  OS Client: Any \line
	RELEASE DATE      : March 2008		\line
\end

\section
  READ ME! (CONTACT)
\end

\body
  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...  \line \line
  Read the "CONTACT"  section  near  the 
  end of that file instead ;-).
\end

\section
	TECHNICAL DESCRIPTION
\end

\subsec
  Terse Description
\end

\body
  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.
\end

\subsec
  Why use it?
\end

\body
  I suppose you could use it as a very crude instant messaging system or whatnot, but that's not what it was written for...
\end

\body
  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.
\end


\body
	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.
\end

\subsec
  How to use it?
\end

\body
  Of course, 'sis --help' displays the command-line options. You'll get something along those lines:
\end

\verb
$ ./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
\end{verb}

\body
  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:
\end
\verb
S | sis -port P
\end{verb}
\body
  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.
\end
\verb
telnet A P
\end{verb}

\body
  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.
\end

\body
  Example session:
\end

\verb
./mess | ./sis -user Gamall test 
\end{verb}

\verb
$ 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
\end{verb}

\subsec
  Some Basic Unix Tips
\end

\body
  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.
\end

\body
  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: 
\end

\verb
./mess 2>&1| ./sis
\end{verb}

\body
  And if you want to get stderr alone, you can do this:
\end

\verb
./mess 3>&1 1>&2 2>&3 | ./sis
\end{verb}

\body
  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'.
\end

\body
  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)
\end

\verb
./mess | ./sis -pipe -p 1337 
       | ./toup | ./sis  -pipe -p 1338 
       | ./tostar | ./sis -p 1339
\end{verb}

\body
  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.
\end

\subsec
  The Source Code
\end

\body
  The source code for SIS is released under the GNU General Public License. 
\end

\body
  SIS is written in Objective Caml. Plus three or four lines of C, for good measure...
\end

\subsec
  The Binaries
\end

\body
  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.
\end

\section
	APPLICATION TO JKA & JK2 (AND OTHER GAMES)
\end
\body
  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.
\end

\body
  Of course, using SIS requires access to the dedicated server, and this server must be some flavour of Unix.
\end

\body
  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.
\end

\body
  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.
\end
\body
  Then you can use telnet to see what is happening in your server.
\end
\section
	CONTACT
\end
\body
	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:
\end
\verb
http://gamall-ida.com/f/viewtopic.php?f=3&t=390
\end{verb}


\section
	END OF FILE
\end
