oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Apache Web Serving with Jaguar, Part 4
Pages: 1, 2

User-Based Configurations

Patti. Dear, dear Patti. The cutest secretary in the world, but also a rabid collector of fax cover sheets. Being on the boss' good side has granted her the privilege of running a personal web site, where she can share the dirt on Californian headers and Alabama footers. We didn't touch upon user-based configurations in the first three articles, but Mac OS X approaches them a bit differently than you'll find in most Apache installations.

In most pre-installed or from-source installations, user-based web serving like is handled generically -- for every user on the system, be it two or two thousand, the same configuration applies. If an administrator wanted to change the capabilities of user "mimi," he'd usually have to create a specific <Directory> block within the httpd.conf file.

Mac OS X makes this a lot easier by creating a config file for each user of the system. These files are located in /etc/httpd/users/ and take the form of username.conf. If I open patti.conf, for instance, I see:

<Directory "/Users/patti/Sites/">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all

Note that this looks very similar to the directory we've been modifying for our GatesMcFarlaneCo site:

<Directory "/Library/WebServer/Documents">
    Options Includes Indexes FollowSymLinks MultiViews
    AllowOverride None
    Order deny,allow
    Deny from all
    Allow from

Because of the similarities, everything we've learned in the previous articles can also be applied to these user-specific directories. Take a look at the modified patti.conf below, which allows SSI and CGI, as well as unrestricted access from the outside world:

<Directory "/Users/patti/Sites/">
    Options Includes Indexes Multiviews
    AllowOverride None
    Order allow,deny
    Allow from all 

ScriptAlias /~patti/cgi-bin/ "/Users/patti/Sites/cgi-bin/"

With the above configuration, Patti can web serve with the best of 'em, adding message boards or discussion groups to each specimen of her faxtastic collection. By modifying only the patti.conf file, we can turn features on or off for only her directory, without affecting the main GatesMcFarlaneCo configuration.

Changing Your Configuration With .htaccess Files

As you've run through these various tweaks and twiddles of the Apache configuration file, one thing has always remained true: to make the changes active, you've had to stop and start Apache after each edit. Not only is this tedious and subject to forgetfulness, it's also avoidable with a little thing called an .htaccess file.

The .htaccess file, when enabled, allows you to control and override a large portion of the Apache configuration without having to stop and start after every change. Once you've instructed Apache to enable .htaccess control, you no longer have to be a privileged user (like an administrator) to enact changes.

Think of .htaccess files as user-modifiable Apache configurations that only affect the directories in which they reside. Let's search through our Apache configuration file and see what we find. Our first result for .htaccess is actually a comment:

# This controls which options the .htaccess files
# in directories can override. Can also be "All",
# or any combination of "Options", "FileInfo", 
# "AuthConfig", and "Limit".

AllowOverride None

By now, this should be old hat to you -- this AllowOverride directive is contained within the <Directory> block we've been messing with for the main GatesMcFarlaneCo intranet. Since .htaccess files can override a large portion of the Apache web server configuration, they're incredibly powerful, but also dangerous. A foolhardy user could easily disable or misconfigure parts of their site due to an incorrect directive. As such, .htaccess files have different levels of control. One of these levels is None -- in other words, .htaccess files have no control over any part of the Apache configuration and are simply ignored. You can find more information about the different levels of control in the AllowOverride documentation at the Apache site.

For now, change the AllowOverride line to:

AllowOverride All

This allows us to override everything available to us within our .htaccess file. In this case, we're changing the AllowOverride line for the /Library/WebServer/Documents directory. If you're looking to give your user directory .htaccess control, be forewarned -- the process is not as perfect as you'd expect. You can turn on the .htaccess feature simply enough, but some directives that rely on Apache's DocumentRoot, like ErrorDocument, will fail. Sometimes, you can cheat -- in the case of ErrorDocument, you can refer to a URL instead of a local file.

For one final time, stop and start the Apache web server. Now what?

.htaccess files are plain text files, placed in the directory in which you want them to be active. We're going to create a quick and dirty example now, so open up a text editor and save an empty .htaccess file into the /Library/WebServer/Documents directory. After you've done that, take a look at the example .htaccess file below, which has been commented for the sake of your childlike innocence:

# override the ErrorDocument defined in our
# main Apache configuration file. use "404.html"
# instead. if this .htaccess file is going to be
# active under a user directory, this line will
# need to be modified to something like (replaced
# with your real domain/IP and username, of course):
# ErrorDocument 404 http://domain.or.ip/~user/404.html
ErrorDocument 404 /404.html

# hey, someone typo'd our contact page, so we'll
# permanently redirect "contct.html" to the correct
# filename, "contact.html". if using this under a
# user directory, modify to "/~user/contct.html",
# and be sure to tweak the URL appropriately.
Redirect /contct.html http://localhost/contact.html

# RedirectMatch's are useful to do mass redirections
# based on certain match criteria. in this
# example, we're redirecting ALL .html files in
# this directory to .shtml files with matching names.
# .htaccess files are read from top to bottom, so if
# someone mistypes "contct.html", they'll be redirected
# to contact.html with the above line, and then
# redirected to contact.shtml with this line. 
RedirectMatch (.*)\.html$ $1.shtml

As mentioned, you can use most directives that you've learned throughout this series. For example, if you wanted to turn on SSI, stop Apache from autogenerating indexes, and allow access to only people from, you could add the following:

Options Includes -Indexes
Order deny,allow
Deny from all
Allow from

.htaccess files apply to the current directory and all subdirectories, as long as none of the subdirectories have their own .htaccess file. If one does exist, the contents of that .htaccess file are used instead. Be aware, however, that creating an .htaccess file under OS X may be harder than you think. Since "dot files" are considered special, you'll be hard pressed to actually create one using the Finder -- you'll be admonished that they're reserved for system use. As such, you should either create them through the Terminal with touch .htaccess, or else work on a file named htaccess and then mv htaccess .htaccess when you're ready.

Password Authentication

One of the most common uses of .htaccess files is password-protecting a directory. When protected directories are accessed, a visitor's browser will prompt for a username and password. If the visitor authenticates correctly, they're allowed in -- if not, an error 401 is triggered, and the visitor is denied.

So yes, Dan from Marketing, we did get your email (and its annoying and frequent follow-ups), and yes, we're going to password protect the "super-secret ad campaign" directory you've been working oh-so-hard on (snicker, snicker, Reese's Pieces).

Mac OS X Hacks

Related Reading

Mac OS X Hacks
100 Industrial-Strength Tips & Tricks
By Rael Dornfest, Kevin Hemenway

To start the process, we're first going to create the user database. This database will contain all of the usernames and passwords that will be authenticated against -- they're not keyed to any specific directory, so you could use one database for three hundred users spread across two dozen directories. To create the database, get into your Terminal and gaze blurry-eyed at the command below:

htpasswd -c /Library/WebServer/.htpasswd dan

It's nice and innocent, right? htpasswd is the name of the utility that creates and modifies this user database of ours. The -c says "if this database doesn't exist, create it." /Library/WebServer/.htpasswd is the full path to our database file, and you'll want to take special notice that it's outside of Apache's DocumentRoot (which, in OS X, is defined as /Library/WebServer/Documents). Sticking the file outside of the DocumentRoot ensures that no one can view this database from the Web. Finally, dan is the user that you want to add to the database. An output of this command is below:

htpasswd -c /Library/WebServer/.htpasswd dan
New password: ********
Re-type new password: ********
Adding password for user dan

You'll want to make sure that when you add new users to an existing database file that you do not use the -c flag. Doing so will overwrite your existing file with a brand new one. Not so good, bub. Adding another user is a simple process (note the lack of the -c flag):

htpasswd /Library/WebServer/.htpasswd mishka
New password: *********
Re-type new password: *********
Adding password for user mishka

If you look at /Library/WebServer/.htpasswd, you'll see the added users:


Next, it's really just a matter of telling Apache what directory we want to secure. Open (or create) your .htaccess file, and add the following:

AuthName "Uber Goober Ad Campaign"
AuthType Basic
AuthUserFile /Library/WebServer/.htpasswd
require valid-user

AuthName will be shown as the title or description of the password box that a visitor's browser will show and, in Apache lingo, is called a "realm." AuthType is set to the standard Basic authentication. (A Digest authentication exists, but is outside of the scope of this article.) AuthUserFile should be self-explanatory.

The require line deserves some discussion. With it, you can tell Apache to allow any user in the AuthUserFile access (as we've done above), or you can tell Apache to allow only certain people access. In the example below, only the users "dan" and "mishka" can authenticate to realms with the name "Uber Goober Ad Campaign." Any other users in the AuthUserFile will be denied:

require user dan mishka

Users can also be defined by groups -- for example, you could place "dan," "mishka," and "morbus" into a group called "Marketing," and "themadman," "ashcraft," and "sprocket" into a group called "Design." From there, you could restrict access by group instead of username. For these configurations and more about digest authentication, refer to Apache's Authentication, Authorization, and Access Control docs.

Tomcat and Secure Servers

Some of the smarmier developers at GatesMcFarlaneCo (Matt and Jeff, particularly) are fans of Java servlets secured with SSL technology. I could cover those here, but Apple has already released some rather good articles on the subject over at their Internet Developer site. I heartily recommend you check out "Using mod_ssl" and "Java and Tomcat" (parts I and II).


A lot of rather nifty things can be done with a stock Apache install, and we've only touched on a few of the more common features above. We haven't played with how to modify the appearance of Apache's auto-indexes, how to use the mod_speling module to duplicate our spelling Redirect, or even how to set up fake virtual hosts to more adequately mimic ISP environments.

Yet, we must move on. As we look at the list of requests for the GatesMcFarlaneCo intranet, only two or three remain, and they all involve something spooky called a "database." What is this monstrosity? What's EssQueueEll? Juan es muy guapo! (Bonus points to those who figure out the tenuous connection between this and the Hitchhiker trilogy joke.) How do I install it, and even worse, what do I do upon success? Find out in part five of our Web Serving trilogy, available a few scant days after you start sweating with impatience.

Kevin Hemenway is the coauthor of Mac OS X Hacks, author of Spidering Hacks, and the alter ego of the pervasively strange Morbus Iff, creator of, which bills itself as "content for the discontented."

Return to the Mac DevCenter.