An account for the burrow computer cluster maintained by the Computer Science Department will be created for each student in this course. (Undergraduate CS majors may already have one.) Then you can run CGI scripts using your own Apache server process on a burrow machine named silo.
General procedures for this are described in the Silo CGI FAQ page, but what need to know is presented here. In particular, do not register your port number, as a block of ports has been reserved for this class, and the LockFile setting mentioned in the FAQ is taken care of by the setup procedure below.
If you are a CS graduate student, or happen to have a CSD Sharkestra account by special arrangement, you can also run CGI scripts as described by the Sharkestra CGI FAQ page instead of using these instruction.
To setup and manage your server, login in to your server account using an SSH (Secure SHell) client, available on most computers. You can install the free putty SSH program on your personal machine if you don't have one.
After login into host name silo.cs.indiana.edu, with your IU username and password, the SSH program will present you with an operating system shell (command window). All commands that follow are to be run on silo in such a shell. Shells are text-only interfaces, so you cannot use the mouse within the shell window itself (except to highlight text to cut for pasting elsewhere). You just type commands after the command prompt, or use a character-interface editor.
If you haven't used a Unix shell before, you need to become familiar with a few of its commands. This Unix command summary is probably all you need, except for the chmod, tail, and editor commands below, and it includes only a bit you won't need (ignore the sz, sx, and rz commands). If you haven't used a Unix shell before, it is a good idea to play around with these commands until you are familiar with them.
There are any number of online tutorial and books on various flavors of Unix shells. It's a good idea to learn more about Unix if you expect use Unix in the future. Let me know if you find an online resource you really like.
You can start either of the traditional Unix editors with the commands emacs and vi. If you're not already familiar with one of these editors, you don't want to learn just for this course. They were designed for "power editing", not ease of learning. Fortunately the command pico starts an editor with a hopefully self-explanatory interface.
It's much more convenient to develop and test your scripts on your workstation, so you may seldom if ever need to use one of these editors. You do need to move files to, and perhaps from, your server cgi-bin directory (explained below). This is easily done using an SFTP (Secure File Transfer Protocol) client. Most SSH clients will open up an SFTP window with a single command, without having to login again. The SFTP window is a visual file browser for the server's file system and you can drag and drop files between it and a workstation file explorer window.
Before continuing, you need a port number that is reserved exclusively for your use. If you have not yet given you this number, ask for it before proceding with these instructions. These port numbers are all five digits long.
Run the command
/u/chaynes/a290/setup <your port number>
where <your port number> is, of course, the port number you were given. Wait a few seconds for it to print Done after creating a directory named apache in your home directory. This is the standard Apache distribution directory, with a few customizations involving your username and port number. This setup command also adds startserver and stopserver commands to your bin directory.
Adrian German's course A348: Mastering the World Wide Web, provides provides more general instruction on how to build, install, and run an Apache web server in the burrow. For this course all you need to know is on this page, since the above startup script does the installation for you.
You will put your Python cgi scripts in the apache/cgi-bin directory. The apache/logs directory contains files that log all access attempts to your server and all of the server error messages. You do not need to know about, and should not mess with, the rest of your Apache directory.
If you ever have reason to believe your Apache setup is messed up, you can execute this setup script again to reinstall it. But since the setup script first deletes any existing apache directory, first save the scripts in your apache/cgi-bin directory someplace outside of the apache directory and move them back after the reinstall.
Then to start your server with the command startserver, and try it out by pointing your browser to
http://silo.cs.indiana.edu:<your port number>
It should display It works!. If your browser displays a message like Unable to connect you probably forgot to start your server.
The Apache server setup includes a couple of scripts that provide information that is sometimes handy.
http://silo.cs.indiana.edu:<your port number>/cgi-bin/test-cgi
prints some server information and
http://silo.cs.indiana.edu:<your port number>/cgi-bin/printenv
prints the operating system environment information with which your server runs. You might like to give these a try, though it's unlikely you'll need any of this information.
If you are using your server every few days or so, you can leave it running. If not, please stop it with the stopserver command, since it takes some of silo's memory as long as it is running. Of course if for some reason silo is rebooted, you will need to restart your server. If you try to start an already running server, no problem: it will just tell you so.
Your scripts are run in response to URLs of the form
http://silo.cs.indiana.edu:<your port number>/cgi-bin/<script file name>[?<query>]
Here <script file name> must name a file in your apache/cgi-bin directory. With this server, Python cgi script file names may end in .py, but doesn't have to.
The optional ?<query> part of the URL must conform to the URL query string rules. Unless you are using standard tools to parse the query, it will suffice to know that it may contain letter, number, dot, dash, tilde, underscore, and equal-sign characters, but not spaces.
Access permissions of cgi script files are critical. Use the command
ls -l <file name>
to see the permissions. ls is the Unix directory listing command, and its -l argument causes a "long" listing that indicates permissions with the characters between the first and second spaces in each output line. They should be -rwx------+, where the rwx indicates the file has owner read, write, and execute permission. Like Unix shells, the server will only run script files that have owner read and execute permission, and to allow editing of the file you need owner write permission as well. For security reasons, server scripts should never have more permissions than necessary, which in this case means there should not be other r, w, or x characters in the permissions list.
Depending on how the file was created or moved onto the server, the permissions may be different, in which case execute the command
chmod 700 <file name>
to fix them.
If you have moved a script file from a Windows machines, you must run
dos2unix <file name>
before using it as a cgi script. This is necessary because by convention (which originated with DOS at the dawn of PC computing) Windows terminates each line of a text file with a two character sequence, return--newline. Unfortunately this conflicts with the Unix convention of terminating lines with just a newline character. Python handles this difference automatically, but the extra return character at the end of the first line will prevent Unix from interpreting it as a #! line. This is particularly troublesome because in most editors the return character will not show up and cannot be easily removed.
If the server is not able to run the script at all (name wrong, no execute permission, bad #! line, etc.), or the script terminates by throwing an exception, the server returns to the browser an Internal Server Error page. You can find a more helpful error message towards the end of the apache/logs/error_log file. (The last line usually just says Premature end of script header, which is no help at all: look at the few lines before that.) Assuming apache/cgi-bin is the current shell directory, the command
tail ../logs/error_log
lists the last ten lines of the error log ☺
That should be all you need to know. (Let me if not.) Happy hacking!