Jaws for BeOS R3.2

Thank you for downloading this PowerPC version of Jaws, The Web-Server for the BeOS.

The Intel version can be found at BeWare or:
http://littlebig.rsn.hk-r.se/jaws/

This is just a preview version of Jaws for BeOS R3, so don't expect too much of the documentation. The lack thereof will be dealt with in the full release. Until then "Share and enjoy"! 

Installation

Just unzip the zipfile, and place Jaws wherever you like. The rest of this documentation will expect Jaws to live in /boot/home/config/bin/ but it really doesn't matter.

Usage

You can start Jaws by either doubleclicking on its icon or by typing Jaws in a Terminal. If you want Jaws to autorestart after each reboot you edit you UserBootScript and add the following line:

Jaws &

Menus

The "Actions" menu contains of six items:
Add virtual host		- Adds a virtual host (more about this later).
Delete selected item	- Deletes the selected item.
DNS-lookup users	- Does a nslookup on all the users that have connected to Jaws.
Stop serving		- Stops everybody from connecting to Jaws.
About Jaws		- Displays an about box.
Quit				- Quits Jaws.

The "Settings" menu contains of four items:
Set WWW root		- Sets the www-root to something different (user-selected) than the
				  default (/boot/home/public_html).
Set Logfile directory	- Sets the logfiles directory to something different (user-selected)
				  than the default (/boot/home/).
Handle CGI		- If checked Jaws will execute CGI-scripts (more about this later).
Handle SSI		- If checked Jaws execute SSI-scripts (more about this later).

The "Log" menu contains two items:
Clear log now			- Clears all logs.
Force save of GUI-log	- Forces a save of the GUI-log (which is separate from the
					  logfile).

Virtual hosts

Jaws supports virtual hosts, just do "Add virtual host" from the "Actions" menu.
You will then be prompted for the name of the virtual host. This will typically be the fully qualified DNS name of the server.
The requested host is the same as the user enters in his webbrowser, and if a computer name maps to the server, and it doesn't exist as a virtual host in jaws, it'll automatically be mapped to the default host. There is no penalty in speed for this, so if you only want one 'host' on your machine then there is no need to bother with virtual hosts.
On  the other hand, you can have lots of cool virtual hosts on the same machine:
12.0.0.7/
194.47.151.32/
littlebig/
littlebig.rsn/
littlebig.rsn.hk-r.se/
...etc...

There is one caveat though! The host 127.0.0.1 does not mean that the only one who can connect to the virtual host must be on the local computer. There is a standardized way to hack this kind of server (that is, be able to browse it on a remote host). We cannot change that since we the would violate the HTTP protocol. So, to be safe from hacks, just don't use 127.0.0.1 as a virtualhost name.
You can remove a virtual host by selecting it and then invoking "Delete selected item" from the menu. All subsequent requests to that virtualhost will be handled by the default host. Note that the logfile on disk is never ever removed. You have to do that manually.


The Common Gateway Interface (CGI)

You can use any CGI program, written in C/C++, Perl, Python, or even a shell script, with Jaws -provided that the checkbox 'Handle CGI' is checked in the Settings menu.
So, how does Jaws identify that a file is a CGI program and executes it instead of just sending the source to the client?
It's easy, it's magic, it's all in the shebang line. I'm not kidding you here. Let me explain further:
In UNIX, they sometimes have to do certain hacks to make things work. These hacks can sometimes remain for a period of time, until they're considered to be Standard. What they did was this; The first line in  a file specified what kind executable environment the file should be executed in. This is known as the shebang line. This is standard in uncompiled CGI programs, so make sure that your shebangline is correct.
The shebang line contains some magic that the operatingsystem (and Jaws) looks at to determine how to execute the program.
For example, the following shell CGI program:

---File: uptime.html---
#!/bin/sh
echo Content-type: text/html
echo
echo "<html>"
echo "<head><title>Uptime on this BeOS system</title></head>"
echo "<body bgcolor="#ffffff">"
echo "<h1>The uptime on this Jaws server is:</h1>"
echo "<h2>"
uptime
echo "</h2>"
echo "</body></html>"
---EndOfFile---

This prints the current length of time since the computer last was booted, through the commandline program "uptime". 
The CGI script works like this:
1) Look how the magic on the shebang line tells Jaws that it should execute this CGI
    program like "/bin/sh nameOfCGIprogram".
2) Notice the empty "echo" statement on row #3. This is mandatory, and separates the
    header from the content of the page that the CGI program generates.

Note: "uptime" is not a Be supplied program. You can find a copy of "uptime" in BeWare at: http://www.be.com/beware/Utilities/uptime.html

If you want the same thing as ASP (Microsoft's Active Server Pages), look no further than Perl. It can do the same thing, consult a Perl book for information on how to do it.

Note that Jaws has no such notion as a cgi-bin directory that is visible from the www-root. Instead, it is recommended that you place all your CGI programs somewhere outside the www-root and create a symlink to the right program wherever you want it. Let's say that Jaws is installed under /boot/apps/LittleBig/Jaws then you can put all your CGI programs under /boot/apps/LittleBig/Jaws/cgi-bin/ (it is not important where you place this folder, just remember that it's no good to place it where it can be publicly accessed). Symlinks are great since you can have the same CGI program under several names in your web-structure. Your guestbook.cgi that you have downloaded from the Internet can be symlinked to www-root/guestbook/guestbook.cgi for example.

TIP:
Since Jaws doesn't (normally) look at fileendings, your can make your site even more professional looking by creating a CGI program that is called index.html. There is no reason why you should wave a banner and say "hi this page is dynamically created with CGI" when you can impress the users with your speedy webpage updates!
Also note that due to current limitations in Jaws your CGI program must produce textual content. It'll not work with images or other raw data.

Server Side Includes (SSI)

The SSI interface in Jaws will help you create some really cool and dynamic HTML pages,  and it'll also help you creating layered HTML pages that can be included in each other. All in all, SSI will not only help you create cool pages for the enduser, it'll also get you there faster and with less fuss.
SSI pages are identified with the file ending in .shtml and are thus violating the rule that Jaws only looks at the file's mimetypes. The reason to this will be explained later.
When a user requests a SSI file from Jaws, the file is preprocessed before being sent away.
What you do is embed small commands inside HTML comments. Let's say that you have a index.html that looks like this:

<html>
<body>
<!--#include file="/boot/home/private_html/sidebar.html"-->
Hi there!
These pages are under construction. See you later.
<!--#include file="/boot/home/private_html/footer.html"-->
</body>
</html>

Everytime a user requests the above index.html, Jaws will insert the files sidebar.html and footer.html into index.html, and then send it to the enduser. The enduser will not see the comments, and will thus think that you have some very extensive pages when in fact you're only reusing common features.

The following SSI commands are recognized by Jaws:

<!--#include file="filename"-->
<!--#include virtual="filename"-->
<!--#exec cgi="/full/path/to/CGIprogram"-->

Note that no matter if you use the virtual or actual filename, there is no access violation checks when dealing with SSI. This is a feature; it allows you to include files (and execute CGI programs) that are completely separated from your www-root so that there is no way ever that the user can download "parts" of a page. Remember that the user will never see the SSI statements.

Other aspects

The order in wich Jaws searches a directory contents for a file (unless specified what the filename is) is this:
1) index.html
2) index.shtml
3) Fail, and give the user a 404 File not found error.
Note that currently, if you want a directorylisting to be generated in a directory, you have to create a CGI script named index.html to do just that. This will be remedied in the future.

The errorpages are customizable

Whenever an error occurs, Jaws will search the directory JawsErrorPages (living directly under the affected www-root).
When a 404 error occurs, Jaws will send the file named 404.html, and if no such file exists, it'll send a default errorpage describing the error.

Jaws will be renamed for the R4 version. Look at http://littlebig.rsn.hk-r.se for the latest information (aswell as the latest version of this manual).

Remember, Share and Enjoy! You are allowed to use Jaws for aslong as you like, but please email us with comments, cheers, flames, or questions at:

info@littlebig.rsn.hk-r.se

___________________________________________________________________
Legal aspects
Jaws is copyright © 1997-1998 by LittleBig Software Engineering.
"Share and enjoy" is a commercial slogan owned by the Sirius Cybernetics Corporation.
BeOS is a registered trademark by Be Inc.
All other trademarks are owned by their respective owners..
