Soma2 v 0.02 README April 13, 2003 Rob Linwood (rcl211@nyu.edu, rob@greenninja.com) I. Intro Soma2 is a Java 1.4-based HTTP server being developed as Open Source. Soma2 is based on the earlier Soma server, but is being re-designed and re-written to take advantage of new APIs in J2SE 1.4. Quick run: Under unix, run the `soma2' program. Win32, and others, read on. II. Configuring Currently, all configuration information is stored in an XML file. By default, the file is called "config.xml", although you can use any name you want by passing it on the command line. Although the configuration file is stored in XML, it is not necessary to know XML to be able to configure Soma2. Although knowledge of XML or HTML will help, most of the configuration consists of filling in values in a pre-written file. Additionally, many of the options expect values in regular expression form. Regular expressions, or regexs, are used to match a string of characters against some pattern. Soma2 uses Java regexs, which are compatible with those used in Perl and Unix (with minor exceptions). A full explanation of regexs are well beyond the scope of this document. A reference for Java regexs can be found at http://java.sun.com/j2se/1.4/docs/api/java/util/regex/Pattern.html Sun also has a tutorial chapter on Java regexs for Java developers. It can be located at http://java.sun.com/docs/books/tutorial/extra/regex/index.html The configuration file consists of a "" tag, which contains global configuration information. Below that level are "" tags, which define options specific to a server zone. A zone represents a portion of the server's URL space (for example, "/cgi-bin", or "/scripts/python"). Each zone can have a different set of options, allowing you to customize behavior based on need. There is a stock config.xml file, which loads the server on 127.0.0.1, port 8080. It uses Web-Root/ as the document root, and supports CGI under the Web-Root/cgi-bin/ directory. III. Running Soma2 Assuming you are in the soma2 directory, the following command will run Soma2: java -cp bin -ea -Djava.library.path=bin/jni soma2.webserver.WebServer Alternately, Unix users can run the 'soma2' shell script, which does the exact same thing. Soma2 makes use of assertions, which can be controlled via use of the -ea (enable assertions) and -da (disable assertions) options to the `java' program. I reccomend leaving them on for the time being so as to catch any errors which may occur. If something does happen, please let me know through email (rcl211@nyu.edu), or a bug report on the SourceForge.Net project page (http://sf.net/projects/soma-server/) IV. What does and doesn't work Soma2 v0.03 is almost as featureful as the last release of the original Soma web server. Here's a list of what's supported: o Static file serving o Configurable MIME types o HTTP POST and GET methods o CGI (both POST and GET supported) o Configurable index files (ie, http://example.com/ goes to http://example.com/index.html) o Dynamic Directory listings + Sorting, both ascending and descending, on file name, last modified, and size + MIME type icons (can be turned off) + Can filter certain file name patterns out of a directory list o HTTP Error Display o Can choose alternate handlers for both directory listing and error display o Out of the box support for eruby and eperl (scripting languages embedded in HTML) o Can support Unix home directories (ie, using getpwnam(3)) What's missing from the original Soma: o Logging o URL corrector/HTTP 300 multiple choices support o HTTP HEAD support o Support for old-style "mime.types" file instead of the new XML format What's broken: o ePerl/eRuby support. V. Building Soma2 Soma2 comes with an Ant buildfile. To get Ant, go to http://jakarta.apache.org/ To re-compile, just run "ant". If you want to support Unix user directories (ie, you have "true" somewhere in your config.xml file), do the following: 1) From the Soma2 directory (ie, where you opened the Soma2 jar archive), type "cd mkdir bin/jni" 2) type "cd src/jni" 3) Type "make install" Assuming there were no errors reported in the last step, everything should work fine. VI. CGI and Dynamic Content In version 0.02, Soma2 supports CGI. CGI programs can be written as normal, and placed in the Web-Root/cgi-bin/ directory. VII. Everything else To keep up to date on Soma2 development, watch http://soma-server.sf.net/