The BKGo Web System =================== This is documentation on how to set up a web server to host a web-hosted Go-playing system. The Theory ---------- Although bkgo runs quite well a standalone client/server Java application, it seems a lot to ask each potential user to locate, download, and install a full Java Runtime Environment. Instead, why not let them use the runtime environment already installed in their web-browser? Everyone has a web browser, and thus everyone has a Java virtual machine. It's easy enough to run the BKGo client as a Java applet: simply embed an appropriate tag into an HTML document and make the "bkgo.jar" archive available as a URL. Web surfers can head to your site and launch clients as they please. Applets, however, are only allowed to establish network connections back to the web-server they came from. Therefore the BKGo server *must* run on the web-server machine. And furthermore, because the BKGo server must communicate with many different IP addresses, it cannot run as a Java "applet", but as a full application. This is where the perl scripts come in: they allow web surfers to examine, launch, and shutdown BKGo servers on your web-server. Once they see a BKGo server that interests them, they can point their BKGo client-applet at it. Voila, a complete, self-contained, web-hosted Go-playing system. Security -------- Keep in mind that anytime you allow anonymous strangers to launch processes on your machine, you're opening the door for potential trouble. Please know that you're doing this at your own risk! These perl scripts are provided as a convenience to you only, and the authors assume *no* responsibility for anything that may happen by using them. That said, there is a simple security scheme. It would be ridiculous to allow surfers to launch a potentially infinite number of BKGo servers, ultimately bringing your box to a halt; therefore, these scripts define a "range" of ports on which BKGo servers can be launched. If someone tries to enter a CGI URL by hand which would launch a BKGo server on an unapproved port number, a security violation is returned. To start, the authors recommend making only 5 ports available. You probably don't want more than 5 BKGo servers running on your machine at once. Authentication -------------- When a BKGo server is launched, it is said to be "unowned". The first time a black-player and white-player connect to it, it asks them to choose passwords for themselves. The server then caches these passwords forever, and the server now has two "owners". (The server also holds the state of the game-in-progress, making it safe for clients to disconnect indefinitely.) If the players disconnect and reconnect later, the server will challenge them for either the black or white owner-password. Likewise, these passwords are required to clear the gameboard, load a game from disk, or shutdown the server. This authentication scheme prevents malicious strangers from doing exactly those things to other people's games. Of course, passwords can always be shared with others, allowing friends to play black or white as teams. Also, keep in mind that anyone can connect to a BKGo server as an "observer". No password is required, but observers can't do anything but watch the game and chat in the chat-window. Requirements ------------ A web-server: * running on a Unixy-OS (i.e. Apache on Linux) * which will allow you to run CGI scripts * which has Perl >= 5.004 installed * which has a Java 1.1 runtime environment installed To Install ---------- 1. Put bkgo.jar and the bkgo *.class/jpg files in places visible to web surfers. 2. Put the perl scripts together in a valid CGI directory. 3. Customize the variables at the top of each script; the script comments will tell you what to do. Our own setup looks something like this: ../bkgo/index.html images / scripts / *.pl client / bkgo.jar server / *.class, *.jpg Testing ------- Point a web browser at: http://yourhost.domain/cgi-bin/list_servers.pl (or wherever you installed the perl scripts). Description of the Scripts -------------------------- * list_servers.pl This script is the entry point for the user. It scans a pre-specified range of TCP/IP ports on the web-server, looking for any running BKGo servers. It presents the results in a table, giving the user the options to create a new server on an unused port, destroy a server, or connect to an existing one. * start_server.pl This script launches a GoServer on a specified port. * start_applet.pl This script executes the BKGo client as an embedded Java applet. * verify_shutdown.pl This script displays a CGI textfield, so that the user can enter a server-owner password. The "submit" button passes this password to shutdown_server.pl. * shutdown_server.pl This script terminates a GoServer on a specified port, using a specified password from verify_shutdown.pl. Questions & Feedback -------------------- Please e-mail bkgo-devel@red-bean.com. Also visit red-bean's website at http://www.red-bean.com