MacDevCenter    
 Published on MacDevCenter (http://www.macdevcenter.com/)
 See this if you're having trouble printing code examples


Setting up a Site Server with Jaguar

by James Duncan Davidson, presenter of sesssions and tutorials at the O'Reilly Mac OS X Conference
08/24/2002

You probably know that Mac OS X ships with a built-in Web server, and you might even know that it's of the famed Apache variety.

But did you know that almost all of the software to set up a heavyweight, full-fledged site server -- a machine that not only serves Web pages, but handles DNS and mail as well -- is already on your machine? With a little bit of tweaking, and the compilation of one piece of software, you can turn any Mac OS X machine you happen to have lying around into a first-class server. All that's needed is a little time and a roadmap -- and this article will provide you the roadmap.

What You Need

Very little is actually needed to make Mac OS X into a full-fledged site server. Here is the short list of things that you'll need for working through these instructions:

Jaguar is the latest release of Mac OS X (10.2). I've picked it because it contains the latest bits from Apple, and I want to make sure that this article stays current for as long as possible. In addition, Apple has been quite good about releasing security updates for Mac OS X, including updates for Apache, OpenSSL, OpenSSH, and many other critical pieces of software. Using the latest version of OS X ensures that you'll be able to take advantage of any updates that will come out in the future.

Related Article:

Configuring sendmail on Jaguar -- Sendmail is powerful, but at times appears complicated too. James Duncan Davidson helps you unravel the sendmail knot so you can configure this awesome mail server on your Mac OS X system.

You don't need a very beefy machine to run your site. The primary machine for my own domain is a Pismo series PowerBook G3 with a 400MHz processor. Why did I use a PowerBook? The answer is simple: laptops come with their own built-in UPS, in the form of their batteries. With two batteries installed, I figure I've got a runtime well in excess of 10 hours -- especially since the screen is off most of the time. Of course, my DSL modem is on an external UPS as well, so that connectivity to the net doesn't suffer when a California blackout strikes. In any case, the PowerBook was just lying there, so I used it. Any old Mac that you have around, as long as it will run Mac OS X, will work, even if it's too slow to really serve as a primary machine any more.

As far as memory and disk space goes, I successfully run my server with 192MB of RAM and a 6GB hard drive. Pretty modest by today's standards to be sure, but I've not upgraded the memory in my server because, well, after several months I haven't had to. Maybe one of these days I'll get around to buying some of that cheap memory that is out there, but it's not a priority.

The next item on the list that you need to have is some familiarity with the Unix shell in order to follow these instructions. Don't worry, I'm not going to assume that you are a rocket scientist with the shell in order to complete the steps presented in this article, but if terms such as sudo, vi, or emacs sound alien to you, then you'll want to read a couple of other articles and get some command-line experience. Here's a series of tutorials to help you with this.

Related Reading

Learning Unix for Mac OS X
By Dave Taylor, Jerry Peek

The last item on the requirement list is a broadband connection. You'll want to have an "always-on" connection to the Internet. I suggest that you get a connection with a static IP address, but you can use DynDNS.org to help people find your site if you don't have a static IP. More on this later in the article.

The Road Ahead

Here's the list of steps that we are going to take to turn your Mac OS X machine into a site server:

  1. Set up Name Services.
  2. Set up Apache for serving Web pages.
  3. Set up Sendmail for handling incoming and outgoing mail.
  4. Set up UW Imapd to let you access your mail.

Without further ado, let's get going!

First Stop: Name Services

The very first thing you need to do is determine how you, as well as other people, are going to find your site. For example, to browse this site, you simply type "www.macdevcenter.com" into your browser, and the site pops up for your viewing pleasure. Under the covers, the Domain Name System is used to translate the name that you can understand, www.macdevcenter.com, to the IP address, 208.201.239.36, that is used by the underlying software to connect to, and download content from, the site.

If you have never seen this before, it is useful to take a look at how this works. Pop open the Terminal.app (double-click on /Applications/Utilities/Terminal) and enter in the following command:

[Titanium:~/] duncan% nslookup www.sun.com

This command will output something like the following:

Server: fraggle.speakeasy.net
Address: 216.254.0.9

Name:   www.sun.com
Addresses: 64.124.140.181

The first two lines of data tell you the server you're making the request from, and the second two lines give you the information you're requesting. Another command you can use instead of nslookup is host, which gives you a simple one-line answer to your request. If you really want to have some fun, use the dig command to see additional information, such as who has authority over the domain you're inquiring about.

So, the question remains: How will people get to your site? In part, this question depends on whether your Internet provider has provided you with a static or dynamic IP address.

Dynamic IP Address Options

If you have a dynamic IP, then you really only have one option. You should use DynDNS.org's Dynamic DNS service to set up a DNS name that will map to your IP address. This will allow you to alias a dynamic IP address to a static hostname. For more information about this, see Alan Graham's "Homemade Dot-Mac with OS X."

You can use your own domain name (to be covered in part 2 of Alan Graham's upcoming Homemade Dot-Mac article), but if you want to forgo the registration fee and save a few bucks, you can use one of the many domains that DynDNS manages. For example, you could have a hostname of something.dyndns.org, someone.is-a-geek.net, or even macosx.kicks-ass.net. There are 34 choices (at the time of this article's writing) to choose from, so it shouldn't be too hard to find something that works for you and suits your personality.

DynDNS provides this service for free, and it's quite easy to set up. All you need to do is to follow the directions at their Web site to set up an account, map your IP address to the hostname you choose, and then download the DNSUpdate client to run on your server, which will update DynDNS every time your IP address changes.

Static IP Address Options

If you have a static IP from your Internet provider, then you have several choices.

If you want to follow step three, there are many companies that are more than willing to help you out with the process. Your ISP is probably one of these companies. I personally use Register.com to manage all of my domains and to point them at my servers, and have had good luck with them.

For the truly self-reliant, there is actually a fourth choice. You can actually serve your domain from your machine with BIND. BIND ships with Jaguar as /usr/sbin/named and is the same software most of the Internet uses to resolve domain names. However, setting up BIND can be a bit of a pain, and can be a security risk as well. It is much simpler to just let a domain registrar, such as Register.com, take care of this for you.

If you really want to go this route, I recommend that you get DNS and Bind, by Paul Albitz and Cricket Liu.

Second Stop: Setting up Apache

Apache is one of the most popular, if not the most popular, Web server available today. It has support for literally anything you want to do. Jaguar ships with version 1.3.26 of Apache, and all you need to do to start it up is to click a single button in your System Preferences application. Here's how.

Open up the System Preferences application. If it's not on your Dock, then you can find it in the /Applications folder of your hard drive. Once launched, click on the Sharing button, then click on the "Personal Web Sharing" checkbox, as shown. Don't let the name "Personal Web Sharing" fool you. This is the full-strength Apache Web server running, no matter how innocent it sounds in the preference panel.


Screen shot.
Firing up Jaguar's Apache Web server is as simple as click on the Sharing button in System Preferences.

That's it. You can now point a Web browser at your machine's IP address or hostname and see the default Apache home page -- yes, the one with the big "Seeing this instead of the Web site you expected?" caption. This home page is located in your filesystem in the /Library/WebServer/Documents folder. Just change the files located there and your Web site visitors will see them. Easy huh?

Kevin Hemenway talks more about this in his excellent article, "Apache Web-Serving with Mac OS X: Part 1."

Behind the Scenes: The Configuration Files

But what's really going on here? Let's look behind the scenes and see what the Unix core of Mac OS X is doing.

When you click that innocent looking "Personal Web Sharing" button in the System Preferences application, what happens is that a flag gets changed in the /etc/hostconfig file. This file tells Mac OS X which services should be started. Mine looks like the following:

% more hostconfig
##
# /etc/hostconfig
##
# This file is maintained by the system control panels
##

# Network configuration
HOSTNAME=-AUTOMATIC-
ROUTER=-AUTOMATIC-

# Services
AFPSERVER=-NO-
APPLETALK=-NO-
AUTHSERVER=-NO-
AUTOMOUNT=-YES-
CONFIGSERVER=-NO-
CUPS=-YES-
IPFORWARDING=-NO-
IPV6=-YES-
MAILSERVER=-NO-
NETBOOTSERVER=-NO-
NETINFOSERVER=-AUTOMATIC-
NISDOMAIN=-NO-
RPCSERVER=-AUTOMATIC-
TIMESYNC=-NO-
QTSSERVER=-NO-
SSHSERVER=-YES-
WEBSERVER=-YES-
SMBSERVER=-NO-
DNSSERVER=-NO-
CRASHREPORTER=-YES-
APPLETALK_HOSTNAME=Titanium

By looking at this file and seeing the line WEBSERVER=-YES-, Mac OS X knows that Apache should be on. If you are observant, you'll have noticed that in the System Preferences screen shot above, I have my Remote Login service turned on, as well as Personal Web Sharing. This corresponds to the -YES- flag being set for the SSHSERVER entry. We'll be back to this file later as we set up the mail services for our server.

The other file of interest is Apache's main configuration file, found at /etc/httpd/httpd.conf. The default file in Jaguar is sufficient for most people. But, if you need to do something with Apache that isn't enabled by default, all you need to do is edit this file and restart the Web server.

If you want to dig deeper into Apache on Mac OS X, I recommend Kevin Hemenway's Apache Web Serving with Mac OS X series. A couple of books that will help you learn more about Apache in general are Apache: The Definitive Guide and the Apache Pocket Reference.

Next Stop: Setting up Sendmail

Sendmail. It's a program that makes many shudder at the thought of complexity. And it's true, Sendmail does have a reputation for being hard to configure. It is literally the swiss-army knife of mail servers. It can do anything you tell it to do, as long as you know how. Fortunately, we don't have to do too much with Sendmail to get things working. And since it comes built into Mac OS X, it's the best choice for us.

Starting up Sendmail

First, we'll need to edit the MAILSERVER line in /etc/hostconfig so that Sendmail starts automatically.

To do this, you'll need to use a text editor, such as emacs, vi, or pico. Our directions will show pico, as it's easy to use. Enter the following command at a command line prompt:

% sudo pico /etc/hostconfig

The file will load. Use the arrow keys to navigate the file and edit the MAILSERVER line to look like the following:

MAILSERVER=-YES-

Exit pico by hitting Control-X. Pico will ask you if you want to save; tell it yes and hit return to save the file.

Second, we need to edit the startup script that Mac OS X uses to launch Sendmail. This file is located in the /System/Library/StartupItems/Sendmail directory. Before editing it, though, we are going to create a copy of it so that it can be restored.

% sudo cp /System/Library/StartupItems/Sendmail/Sendmail.orig
% sudo pico /System/Library/StartupItems/Sendmail/Sendmail

You're going to need to add one line to the sendmail startup entry. Edit the file to appear as follows, the boldface section is the only thing you need to add to this file. Oh, and be careful. A mistake here can really hurt your OS installation. Double and triple check before saving the file:

#!/bin/sh

##
# Sendmail
##

. /etc/rc.common

StartService ()
{
     if [ "${MAILSERVER:=-NO-}" = "-YES-" ]; then
         # if ! pid=$(GetPID sendmail); then
             ConsoleMessage "Starting mail services"

             ##
             # Remove junk from the outbound mail queue directory and
start up
             # the sendmail daemon. /usr/spool/mqueue is assumed here
even though
             # it can be changed in the sendmail configuration file.
             ##
             queue=/var/spool/mqueue
             rm -f ${queue}/nf* ${queue}/lf*

                 chmod g-w / /Users
             /usr/sbin/sendmail -bd -q1h
             /usr/sbin/sendmail -C /etc/mail/submit.cf -q1h
         # fi
     fi
}

StopService ()
{
     if pid=$(GetPID sendmail); then
         ConsoleMessage "Stopping mail services"
         kill -TERM "${pid}"
     else
         echo "sendmail is not running."
     fi
}

RestartService ()
{
     if pid=$(GetPID sendmail); then
         ConsoleMessage "Restarting mail services"
         kill -HUP "${pid}"
     else
         StartService
     fi
}

We have to add this extra line to Sendmail's startup script because Apple ships Mac OS X with a root directory that is writable by any user in the admin group. Presumably, this is so that people that want to install applications on their hard drive in this location can, but Sendmail really doesn't like to run with a group writable root directory. There are ways to get Sendmail to run without this change, but they all can introduce security risks that might be determintal to your sanity.

Apple's updaters also have a nasty habit of changing the permissions on this directory back to group writable. To ensure that any changes to these permissions get changed back as soon as possible, you can add an entry to root's crontab.

% sudo sh
% export EDITOR=/usr/bin/pico
% crontab -e

Edit the crontab to look like this (Replace userid with your userid on the machine):

MAILTO=userid
0 * * * * chmod g-w / /Users /

Exit pico and save the file. Setting this up means that every hour, cron will fire off a job to make sure that the permissions of your root directory are set up correctly.

Quit your editing session, making sure that you save the file. Now, restart your machine to make sure that you edited the file properly. Normally, I hate to give the advice "reboot your machine," but its necessary in this case, where we want to be sure that Sendmail will start on every reboot. After your machine starts up, you can verify that Sendmail is running properly by entering in the following at the console:

% telnet localhost 25
Trying 127.0.0.1...
Connected to dsl092-007-021.sfo1.dsl.speakeasy.net.
Escape character is '^]'.
220 dsl092-007-021.sfo1.dsl.speakeasy.net ESMTP Sendmail 8.12.2/8.12.2; Sat, 10 Aug 2002 00:43:35 -0700 (PDT)
QUIT
221 2.0.0 dsl092-007-021.sfo1.dsl.speakeasy.net closing connection
Connection closed by foreign host.

Simply type "QUIT" to exit out. If you don't see the above, it means that something wasn't edited correctly in the /System/Library/StartupItems/Sendmail/Sendmail script. Go back and check things very carefully. If nothing else works, copy the original file back over the file you edited and try again.

Sendmail is now up and running. It will accept mail addressed to any user at the local host. fully-qualified reversed hostname. For example, on my server, Sendmail will accept any mail addressed to duncan@dsl092-007-021.sfo1.dsl.speakeasy.net, but not duncan@somehost.dyndns.org. This is a good start, and shows that the mail server isn't an "open-relay" that will possibly spread spam, but we need to do a little more configuration to allow us to accept mail to our desired hostname.

Telling Sendmail which Hostnames are Valid to Accept Mail To

To have Sendmail accept mail to your machine's hostname, all you need to do is edit the /etc/mail/local-host-names file. To do so, enter in the following command:

% sudo pico /etc/mail/local-host-names

Simply add the hostnames that you want to receive mail for, one line at a time, to this file. For example:

somemachine.dyndns.org 
66.92.7.21

For this to take effect, you'll need to restart Sendmail. Instead of rebooting, we're simply going to stop and restart Sendmail. Use the following commands to do so:

% ps -ax | grep sendmail
358  ??  Ss     0:00.34 /usr/sbin/sendmail -bd -q1h
361  ??  Ss     0:00.02 /usr/sbin/sendmail -C
/etc/mail/submit.cf
-q1h
735 std  S+     0:00.00 grep sendmail

% sudo kill -HUP 358

In short, we are sending the HUP signal, telling Sendmail to reload its configuration. Make sure to send the HUP to the process with the -bd -q1h arguments. Now, Sendmail will accept mail for users on your machine. This mail is delivered to the file /var/mail/[username]. For example, mail on my machine is delivered to the file /var/mail/duncan.

Setting Up Aliases

You probably want to have the ability to have more than one email address for each user on your machine. For example, I like to have the email address webmaster@mymachine. To do this, we need to use NetInfo Manager to edit the aliases that are used by the system. To launch NetInfo Manager, double click on its icon in the /Applications/Utilties folder. You'll be greeted with the following window:

Screen shot.
Use NetInfo Manager to edit the aliases that are used by the system.

To add a new alias, simply:

  1. Click the lock to make changes. You'll need to use your administrator password to unlock it.
  2. Click on the aliases entry.
  3. Click the New Folder button (the leftmost one), or use the Directory - New Subdirectory menu item.
  4. In the bottom editor window, click on the value for the name entry and enter in the name of the alias, such as "webmaster."
  5. Insert a new property by using the Directory - New Property menu item.
  6. Change the name of the new property to "members" and the value to the user you want. In my case, I made this "duncan."
  7. Save your changes (Command-S, or Domain - Save Changes). You will be asked to confirm your changes.

The NetInfo Manager window should look something like this now:

Screen shot.
Mail addressed to webmaster will be delivered to duncan.

Now, any mail addressed to webmaster will be delivered to user duncan. You can add as many aliases as you want.

Obviously there's much more to Sendmail than I have time to cover today. However, I've given you enough to get set up a site server. A more advanced article on using the advanced configuration options of Sendmail on Mac OS X is in the works and will show up here on the Mac DevCenter. In the meantime, you might want to peruse sendmail, 2nd Edition.

Last Stop: Setting up IMAPd

The last thing we need to do to have a fully-functional site server is to set up a POP and IMAP server so that we can get our mail. Unfortunately, software for these mail servers doesn't ship by default on Mac OS X. Fortunately, it's easy to get, compile, and set up. We're going to use the University of Washington IMAP server. It's been widely tested, is stable, and is easy to use. It also works well with OpenSSL, which is installed as part of Mac OS X.

This integration with OpenSSL is very important, because you have to have a password to log in to your IMAP server, and you do not want others to be able to see this password while it is in transmission. To make sure that your passwords stay secure, I'm going to give you instructions on how to build the IMAP server to use OpenSSL only. This configuration will be compatible with any mail client that understands SSL -- this includes Mail.app and Entourage.

Setting up the Developer Tools

But, before we can build the IMAP server, we need to have the developer tools installed with the optional BSD SDK on the system. If you haven't already installed the developer tools, or neglected to install the BSD SDK, grab the Developer Tools CD that came with Mac OS X, insert it into your computer, and double click on the Developer.mpkg file in the window that appears. Proceed through the installation wizard until just after you have selected the disk to install onto. When you see the announcement "Click Install to perform a basic installation of this software package," clike the Customize button instead. Make sure that the BSD SDK checkbox is clicked, and then click "Install."

The installer will chug on for a while. Do something else while it works, as it is not a quick install. Grab some coffee. Or water.

Download and Build the IMAP Server

Next, we need to download and build the IMAP server. This is a relatively straightforward process when you know exactly what to type. All you need to do is follow this script and you will have a built and functional SSL-enabled IMAP server ready to be set up. As you type most of these commands in, output on what is happening will scroll by, but as long as you don't make a mistake, everything should be fine.

% curl ftp://ftp.cac.washington.edu/imap/imap.tar.Z > imap.tar.Z
% uncompress imap.tar.Z
% tar xf imap.tar
% cd imap-2002.RC2/
% make osx SSLTYPE=nopwd SSLDIR=/usr SSLCERTS=/etc/sslcerts
% sudo mkdir -p /usr/local/bin
% sudo cp imapd/imapd /usr/local/bin/imapd

There. That wasn't so bad, was it? You now have a fully-functional IMAP server just waiting to be used.

Configure the IMAP Server

There are two things we need to do to configure the IMAP server. The first is to set up the SSL certificate that will be used by the server. The second is to enable the server to handle requests.

To install a self-signed certificate (perfectly adequate for our needs), use the following commands. You will be asked a few questions as part of the process of making this certificate. The answers I used are highlighted in bold.

% sudo mkdir -p /etc/sslcerts
% sudo openssl req -new -x509 -nodes -out /etc/sslcerts/imapd.pem -keyout /etc/sslcerts/imapd.pem -days 3650
Using configuration from /System/Library/OpenSSL/openssl.cnf
Generating a 1024 bit RSA private key
...................................................++++++
...........................++++++
writing new private key to '/etc/sslcerts/imapd.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Francisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]:x180
Organizational Unit Name (eg, section) []:Home Mail
Common Name (eg, YOUR name) []:James Duncan Davidson
Email Address []:duncan@x180.net

The last thing we need to do is configure Mac OS X to start up the IMAP server when it sees requests to the IMAP over SSL port (port 993). To do this, we need to edit the /etc/inetd.conf file.

% sudo pico /etc/inetd.conf

Add the following line to the very end of the file:

imaps stream tcp nowait root /usr/libexec/tcpd /usr/local/bin/imapd

Now, we just need to restart the inetd deamon:

%  ps -ax | grep inetd
  323  ??  Ss     0:00.01 inetd
  4798 std  R+     0:00.00 grep inetd
% sudo kill -HUP 323

Congratulations. You're done. Now it's time to set up your mail client to use it. Besides setting up your mail client to use the host, username, and password for your mail account, you'll want to make sure that you enable the SSL option. This is shown in the following configuration panel from Mail.app.

Screen shot.
The Mail.app configuration panel.

Also, notice that I've setup an IMAP path prefix. This is the directory in my home directory on the server in which my IMAP mailboxes will be kept. If you don't specify this, then your home directory will be used, and you'll see them show up in your Mail application.

Conclusion

We've just set up everything needed to have a full-fledged site server on the Internet with Mac OS X. There are many other things that can be tweaked, configured, and added to this foundation. You can find instructions for many of these here on the O'Reilly Network. Another great resource to use is Stepwise.

There's one last important thing to say before we're done. Now that you have a server up and running, you'll want to make sure that it doesn't automatically go to sleep on you. Just go into the System Preferences, click on Energy Saver, and make the appropriate selections.

Related Resources:

"Learning the Mac OS X Terminal" -- Chris Stone, contributor to Mac OS X: The Missing Manual, shows you how to get comfortable using the Terminal application in Mac OS X. His hands-on tutorials will have you punching out command lines in no time at all.

"Homemade Dot-Mac with OS X" -- So you don't want to pony up the $99 annual fee for .Mac? No problem if you've switched to Mac OS X, because everything is built-in for you to set up your own .Mac suite of services. Alan Graham shows you how.

"Apache Web Serving with Mac OS X" -- There's a powerful Apache Web server built in to every Mac OS X computer. Kevin Hemenway shows you how to start serving Web pages within minutes, then gives you the tools for advanced techniques that seasoned system administrators use every day.

Apache: The Definitive Guide -- Written and reviewed by key members of the Apache group, this book is the only complete guide on the market that describes how to obtain, set up, and secure the Apache software.

Apache Pocket Reference -- Provides a summary of Apache command-line options, configuration directives, and modules, and covers Apache support utilities.

sendmail, 2nd Edition -- covers sendmail version 8.8 from Berkeley and the standard versions available on most systems. This cross-referenced edition offers an expanded tutorial and solution-oriented examples, plus topics such as the #error delivery agent, sendmail's exit values, MIME headers, and how to set up and use the user database, mailertable, and smrsh.

James Duncan Davidson is a freelance author, software developer, and consultant focusing on Mac OS X, Java, XML, and open source technologies. He currently resides in San Francisco, California.


Return to the Mac DevCenter.


Copyright © 2009 O'Reilly Media, Inc.