Apache Web-Serving with Mac OS X: Part 2

by Kevin Hemenway
12/14/2001

Editor's note: In his previous article, Apache Web-Serving with Mac OS X: Part 1, Kevin Hemenway showed you how to easily start serving web pages from your Mac OS X computer. In this article, he explores the world of CGI access. To gain the most from what Kevin has to offer here, you'll need some familiarity with the Terminal application. If you haven't explored that feature yet, I recommend that you first read our companion article, Learning the Mac OS X Terminal: Part 1. Once you're comfortable using the command line, you can return here and dig deeper into Apache.

Learning a bit more about Apache

So, after the work we did in the last article, we've got a prettier URL, but still a rather boring site. We need features to impress the boss, and to turn them on we're going to have to start fiddling with Mac OS X's Terminal. We're going to assume you know how to edit and save files via the command line, either through a native shell editor (like vi or emacs) or via a GUI editor such as BBEdit. Our examples below assume BBEdit 6.5 and its shell utility.

Before we turn on features, we need to know where Apache's configuration file lives. To find out, we'll query the Apache web server itself, with the following command line:

httpd -V

This will spit out a screen of information specific to your Apache installation (this will work in any Apache install -- for Mac, Linux, or Windows). On an OS X 10.1.1 machine, we find out that we're using Apache 1.3.20 (in the soon-to-be-released 10.1.2, Apache will be upgraded to 1.3.22.):

    
Server version: Apache/1.3.20 (Darwin)

As well as where the configuration file is located:

    
-D SERVER_CONFIG_FILE="/etc/httpd/httpd.conf"

We'll also score two very helpful bits of information:

    
-D DEFAULT_XFERLOG="/var/log/httpd/access_log"
-D DEFAULT_ERRORLOG="/var/log/httpd/error_log"

These are the log files for Apache -- every request and every error message will show up within these logs. You'll find them insanely useful for debugging, as well as making sure our upcoming features are working correctly.

Learning about CGI access

Apache: The Definitive Guide By Ben Laurie & Peter Laurie Table of Contents Index Sample Chapter Full Description Read Online -- Safari

It's now time to fiddle with the most common feature available to a web server: CGI. Without getting overly esoteric, CGI allows us to install thousands of different scripts that can be accessed through a normal web browser. CGI scripts are often written in Perl (also installed by default) and can allow users to access databases, use interactive forms, chat in bulletin boards, and so on.

Apache comes with two simple scripts that can verify CGI is configured correctly. Before we test them, however, let's see what we can learn from the Apache configuration file. To start, open up your config file in your favorite text editor (the example below assumes BBEdit 6.5):

bbedit /etc/httpd/httpd.conf

Be forewarned: The Apache configuration file is rather large, but also well documented. Take its introductory warning to heart: "Do not simply read the instructions ... without understanding what they do. They're here only as hints or reminders. If you are unsure consult the online docs. You have been warned." For your own reference, the online docs are available at the Apache web site.

The quickest way to find and learn about the Apache configuration file is to search for the feature you want to enable. In our case, we'll start looking for "CGI". The first entry we find is:

LoadModule cgi_module libexec/httpd/mod_cgi.so

Followed shortly by:

AddModule mod_cgi.c

You'll see a number of these lines within the Apache config file. If you've ever worked with a plug-in-based program, you'll easily recognize their intent -- these lines load different features into the Apache web server. Apache calls these "modules", and you'll see a lot of module names start with mod_, such as mod_perl and mod_php. Lines that are commented out (that is to say lines that are prefaced with a # character) are inactive.

Because our CGI lines are already active, we'll continue searching:

ScriptAlias /cgi-bin/ "/Library/WebServer/CGI-Executables/"

  <Directory "/Library/WebServer/CGI-Executables">
     AllowOverride None
     Options None
     Order allow,deny
     Allow from all
  </Directory>

The ScriptAlias directive allows us to map a URL to a location on our hard drive. In this case, Apache is mapping http://127.0.0.1/cgi-bin/ to the /Library/WebServer/CGI-Executables/ folder. If you browse to that folder now, you'll see the two CGI scripts I oft-handedly mentioned above: printenv and test-cgi. The <Directory> isn't that important right now, so we'll move on to our next search result:

# AddHandler cgi-script .cgi

Now that we're in a little deeper, let's talk about your Apache experience on Mac OS X.

Post your comments

This is your first major decision concerning your Apache installation. When a certain directory has been ScriptAlias'ed (as our CGI-Executables directory has, above), the files within that directory are always executed as CGI scripts. If the files were moved out of that directory (say, into our DocumentRoot directory), they'd be served as normal text files.

By uncommenting the above line, you're telling Apache to execute any file that ends in .cgi. This can happen from any directory and from any user, and is often considered a security hazard.

In a default installation of Apache on Mac OS X, CGI scripts are only allowed within /Library/Webserver/CGI-Executables/. Uncommenting the above line (removing the "#" character) allows CGI scripts to be executed from any user directory, such as /Users/morbus/Sites. In our case, because we aren't using the User directories (because they create ugly URLs for GatesMcFarlaneCo's intranet), we're going to leave the line commented.

If CGI access is turned on already, we should be able to reach http://127.0.0.1/cgi-bin/test-cgi and see a happy result, right? If you went to that URL, however, you were probably greeted by a not so joyous response: "FORBIDDEN". Apache screams, "You don't have permission to access /cgi-bin/test-cgi.

Huh? Why didn't this work? Now is a perfect time to prove how useful the Apache web server logs can be. If you recall the results of our httpd -V command above, Apache's access file is located in /var/log/httpd/access_log. Let's look at the very last lines of that file, easily reached with this command:

tail /var/log/httpd/access_log

You'll see that the last line looks similar to:

127.0.0.1 - - [19/Nov/2001:21:59:46-0500]
"GET /cgi-bin/test-cgi HTTP/1.1" 403 292

Quickly, this line shows where the access request came from (127.0.0.1), the time the file was requested, the protocol used (HTTP/1.1), the response code (403), and the size of the response (292 bytes). This is all fine and dandy, but doesn't tell us what went wrong. For this, we'll dip into our error log (also pinpointed by the httpd -V command):

tail /var/log/httpd/error_log

And we see:

[Mon Nov 19 21:59:46 2001] [error] [client 127.0.0.1]
  file permissions deny server execution:
   /Library/WebServer/CGI-Executables/test-cgi

Bingo! This tells us exactly what went wrong -- the file permissions were incorrect. For Apache to run a CGI script, the script in question needs to have "execute" permissions. To give the test-cgi file the correct permissions, we run:

cd /Library/WebServer/CGI-Executables
chmod 755 test-cgi

After doing the above, load the URL again, and you should be happily greeted with gobs of environment information. (To learn more about permissions, the chmod utility, and the server environment, consult your favorite search engine, friendly geek, or O'Reilly-stocked library).

With the basics of CGI out of the way, you can now install CGI-based applications to complement your intranet. Need a content management system for the developers to keep everyone up to date on their coding progress and discussions? Try Movable Type.

Pages: 1, 2

Next Page