Web development requires the hardware and software to accommodate a wide variety of client needs and web technologies. Apple has provided web developers with an enormously flexible development environment in Mac OS X. By including Apache, the world’s most widely used web server, along with a host of related technologies (PHP, OpenSSL, SSI, etc) Apple has provided a perfect compliment to popular tools such as BBEdit, Adobe Photoshop, and Macromedia Dreamweaver.

This tutorial will show you how to enable one of the most important technologies included with the standard installation of Apache on Mac OS X, mod_ssl. The mod_ssl module lets Apache use OpenSSL, thereby enabling cryptographically protected connections to web servers via the Secure Sockets Layer (SSL) and Transport Layer Security. Though this is not a comprehensive tutorial on system security, if you enable mod_ssl you will add a layer of security to a Mac OS X machine’s Web Sharing feature.

For more on security in Mac OS X, see An Introduction to Mac OS X Security.

Why SSL?

Adding Apache support for mod_ssl is a great development step. You will be able to test scripts and applications in the most realistic environment possible prior to deployment to a staging or production server. This will help cut development time. It also permits access to your computer that is encrypted. Web applications served off of your Macintosh will be accessible in a secure way. So passwords passed to your machine via web-based forms will be hidden from packet sniffers. Data transmitted to a browser will also be encrypted during transit.

Definition of SSL

The Draft Specification for the SSL Protocol contains a good definition of SSL.

… Secure Sockets Layer(SSL V3.0) protocol [is] a security protocol that provides communications privacy over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery.

In other words, SSL enables client/server communications that are encrypted, providing security and privacy in communications. Additionally, with SSL, every server has a “fingerprint”, a means of identifying a specific server as being the source of any information returned through an SSL request.

SSL uses Public Key Cryptography, which uses Key Pairs — one private key, kept on the server, and one public key, distributed to clients requesting it. Data encrypted or “locked” with one key can only be decrypted, or “unlocked” with the matching key in the key pair.

What’s There and What’s Needed

To establish secure communications over the web via SSL you need the Apache server compiled with the Enhanced Apache API (EAPI), OpenSSL, and the mod_ssl module. Thankfully, Apple has provided all of the needed ingredients in Mac OS X. Moreover, you can find documentation for these products on a standard Mac OS X installation:

• The Apache Manual (http://localhost/manual)
• mod_ssl User Manual (file://localhost/Library/Documentation/Services/apache_mod_ssl/index.html)
• OpenSSL “man” pages (type man openssl in the terminal).

The one item you need to add is the sign.sh script that is distributed with the mod_ssl distribution. You can find more information on this on the FAQ.

If you know how to start the Terminal, run sudo, and edit the httpd.conf file that configures Apache, you’ll be in good shape. I like using emacs for editing text files, and have included the commands needed for working with emacs. Feel free to use pico, TextEdit, BBEdit, or whatever you know how to use.

The sudo command lets you temporarily become a “superuser”. Using it requires that you know the password of a member of the admin group. You can see the members of the admin group by checking NetInfo Manager (under /groups/admin).

Finally, as cryptography is an acronym-rich subject, it might be helpful to keep a good glossary of terms used in cryptography close at hand. In this article, you’ll come across the following acronyms:

• RSA: A commonly used Public Key encryption system developed by Rivest, Shamir, and Adelman.
• DES: Data Encryption Standard. A cipher commonly used in commerce. Triple DES (3DES) describes the process of encrypting data three times with two or three DES keys.
• PEM: Privacy Enhanced Mail. An e-mail cryptography protocol from the IETF.

Configuring SSL

The first thing you need to do is generate the keys and certifications for the server. This requires using the Terminal. For sanity’s sake, create a directory (Folder) on the desktop called KeyGen and change into that directory.

cd ~/Desktop/KeyGen

You can now create an RSA private key and a CSR (Certificate Signing Request) for your server. An important part of private key cryptography is making sure that the parties involved in a transaction are who they say they are. This is accomplished through a third party — a trusted Certificate Authority (CA). The CA issues certificates that identify the parties, and confirms that the keys are correct and are cryptographically “signed.” Generating the CSR is the cryptographical equivalent to filling out a passport application. The CA will return the certificate (like a passport) which is used for identification and authentication.

You’re going to be self-signing the keys, so you’ll also be creating a CA key for the signature. The keys and certificates you create are purely for testing purposes. If you need to set up a production server, you should send your CSR to a proper CA, such as Verisign, for signing.

To create the RSA private key, issue the following command:

openssl genrsa -des3 -out server.key 1024

You will be asked for a passphrase in the creation of this key. Do not forget this passphrase! You’ll have to do this all over if you forget the passphrase. You will need this passphrase later on in the process.

You have just created the “SSLCertificateKeyFile”, as it is called in the httpd.conf — a 1024 bit RSA key encrypted with Triple-DES in PEM format. You’ll be plugging this into the configuration file for Apache soon.

Now you’re ready to create a CSR (Certificate Signing Request), which is what you would normally send to a CA for signing. You’re going to sign it yourself.

openssl req -new -key server.key -out server.csr

You’ll be asked for some information when you start this. Most of it is pretty self explanatory, but one item, in particular, is not. Here’s what you’ll be asked for:

Country Name (2 letter code) [AU]: (enter your country code here)
State or Province Name (full name) [Some-State]: (Enter your state here)
Locality Name (eg, city) []: (enter your city here)
Organization Name (eg, company) [Internet Widgits Pty Ltd]: (enter something here)
Organizational Unit Name (eg, section) []: (enter something here)
Common Name (eg, YOUR name) []: (this is the important one)
Email Address []: (your e-mail address)

The entry for “Common Name” is the one that seems like it should be one thing, but is, in fact, another. For this entry, you want to enter your “Server Name” as it appears in your httpd.conf (which you’ll be modifying soon). As this is just a development environment, you can enter 127.0.0.1, which is the default IP for “localhost”. Now, keep in mind that using 127.0.0.1 is not the same as using “localhost”. The strings either match, or they don’t — Unix is like that.

Looking at your KeyGen directory, you should have this:

[localhost:~/Desktop/KeyGen] bob% ls -la
total 12
drwxr-xr-x    5 bob      staff         126 Sep 14 17:01 .
drwx------   38 bob      staff        1248 Sep 14 16:57 ..
-rw-r--r--    1 bob      staff         729 Sep 14 17:01 server.csr
-rw-r--r--    1 bob      staff         963 Sep 14 16:59 server.key

Now you need to create a CA for signing the key. The process is similar to what you’ve just done, but there are some differences.

The first thing you need to do is create a key for your CA. It’s just like your server.key – a Triple-DES encrypted, 1024 bit RSA key.

openssl genrsa -des3 -out ca.key 1024

Again, you’ll be asked for a passphrase, which, again, you should not forget.

Now you will create a self-signed CA Certificate using the RSA key you just made.

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

You’ll be asked for the passphrase for the key you just made, and, again, you’ll be asked to enter information about yourself. The main difference is that here, when you are asked for your “Common Name”, you want to enter your name — not the server name or IP address. This certificate is not associated with your server — it’s associated with you. It should look something like this:

Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Texas
Locality Name (eg, city) []:San Antonio
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bogus CA
Organizational Unit Name (eg, section) []:Bogus CA for Dev
Common Name (eg, YOUR name) []:Bob Davis
Email Address []:bobdavis@mac.com

Now you have 4 files in your directory — a CA key and certificate, and a server key and certificate signing request.

The next step is the important one. This is where you sign the server.key with your ca.crt. This will provide the security assurance that browsers need to establish a secure connection. It provides the identification and verification part of the public key encryption system where the keys themselves provide the mechanism for the encryption and decryption.

The easiest way to do this is to use the sign.sh script contained in the mod_ssl source you downloaded (it’s in the pkg.contrib sub-directory) or wherever you put.

Copy the script to your working directory, make it executable, and then run it by issuing the following commands:

chmod +x sign.sh
./sign.sh server.csr

You should get something like this, but with the information you entered for the server.csr:

CA signing: server.csr -> server.crt:
Using configuration from ca.config
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName            RINTABLE:'US'
stateOrProvinceName    RINTABLE:'Texas'
localityName           RINTABLE:'San Antonio'
organizationName       RINTABLE:'Testing'
organizationalUnitName:PRINTABLE:'Testing'
commonName             RINTABLE:'127.0.0.1'
emailAddress          :IA5STRING:'bobdavis@mac.com'
Certificate is to be certified until Sep 14 23:09:20 2002 GMT (365 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
CA verifying: server.crt <-> CA cert
server.crt: OK

For the questions “Sign the certificate?” and “1 out of 1 certificate requests certified, commit?”, you just need to type “y” (without quotes) and hit enter/return.

Looking at your working directory now, you’ll see that you have a number of new files and directories in KeyGen.

[localhost:~/Desktop/KeyGen] bob% ls -la
total 36
drwxr-xr-x   12 bob      staff         364 Sep 14 18:16 .
drwx------   38 bob      staff        1248 Sep 14 18:12 ..
-rw-r--r--    1 bob      staff        1298 Sep 14 17:55 ca.crt
drwxr-xr-x    3 bob      staff          58 Sep 14 18:09 ca.db.certs
-rw-r--r--    1 bob      staff         111 Sep 14 18:09 ca.db.index
-rw-r--r--    1 bob      staff           3 Sep 14 18:09 ca.db.serial
-rw-r--r--    1 bob      staff         963 Sep 14 17:52 ca.key
-rw-r--r--    1 bob      staff        2679 Sep 14 18:09 server.crt
-rw-r--r--    1 bob      staff         729 Sep 14 17:01 server.csr
-rw-r--r--    1 bob      staff         963 Sep 14 16:59 server.key
-rwxr-xr-x    1 bob      staff        1784 Sep 14 17:59 sign.sh

Now, make a directory in your /etc/httpd called ssl.key

sudo mkdir /etc/httpd/ssl.key

You’ll be prompted for your login password (you have to be in the admin group to use sudo), and the directory will be created.

Move all of the contents of your working directory to the ssl.key directory you just made. In a production system, it would be a very, very bad idea to keep your CA keys, certs and such on the server. If the security of the server is compromised, the ca.crt could be used to “sign” certificate signing requests on any machine. In other words, it gives anyone the power to impersonate you on the internet. Since you’re just using this for testing, and the certificates have bogus information in them, it’s not so terribly important. It is worth noting that this practice would be considered irresponsible on a server accessible to the outside world.

sudo cp -r * /etc/httpd/ssl.key/

One more step — and it’s another step that would not have a place in a production environment, but definitely makes life with your development system better: you’re going to remove the passphrase requirement from the server key by removing its encryption.

As things stand, when you start Apache, you will be prompted for a passphrase to read the private key. While this is fine for those who start and stop Apache manually from the command line every time, it does create some problems for those of us who have Apache (a.k.a. Web Sharing) start up automatically every time the system reboots. The system will hang on startup, patiently waiting for a passphrase that will never come — because there’s no way to enter the passphrase you’ve given the key! You’ll have to either boot into Mac OS 9 or boot into verbose mode to clear this problem if you forget.

Removing the pass phrase requirement is dangerous in a production environment, but acceptable for testing (especially if you enter information in your certificate request that makes it clear that this is a testing certificate, and not for production use).

Enter the following:

cd /etc/httpd/ssl.key
sudo cp server.key server.key.original
sudo openssl rsa -in server.key.original -out server.key

You’ll be asked for your passphrase for both the sudo command (your system passphrase) and the RSA command (the passphrase for the key). Comparing the two files server.key and server.key.original will show that they are now very different and that server.key.original contains a line stating, “Proc-Type: 4,ENCRYPTED”, that the decrypted file lacks.

Now, you have all of the files you need to make mod_ssl work with Apache. But you still need to configure the Apache server to use mod_ssl. Apple’s engineers have thoughtfully provided Apache compiled with EAPI, which allows modules to be included in Apache without recompiling the server. It makes it a lot easier to enable various modules as you need them.

Stop your web server if you haven’t already, either by using the Sharing control panel or through the command line using:

sudo apachectl stop

The file you want to edit is /etc/httpd/httpd.conf. The first thing you want to do is make a backup of the file. Keeping in mind that this directory is owned by root, you will have to use sudo for all of these commands. So, change directories to /etc/httpd and then make a copy of your httpd.conf.

cd /etc/httpd
sudo cp httpd.conf httpd.conf.backup

Now edit your httpd.conf file using the editor of your choice. I use emacs, so the instructions here are for emacs.

sudo emacs httpd.conf

First, you need to comment out the “Port” directive by placing a “#” in front of the line.

Port 80 should be changed to #Port 80. You will need to add the following just below where the Port directive was:

## SSL Support
##
## When we also provide SSL we have to listen to the
## standard HTTP port (see above) and to the HTTPS port
##

<IfModule mod_ssl.c>
		Listen 443
		Listen 80
</IfModule>

Adding these lines tells the server to be aware of traffic on port 80 (the standard HTTP port) and port 443 (the HTTPS port). This allows your SSL aware Apache installation to serve non-secure documents on port 80, while it is serving secure documents on 443.

Continuing on in the httpd.conf file, find the lines that reads:

#LoadModule ssl_module         libexec/httpd/libssl.so

and a little further down:

#AddModule mod_ssl.c

You need to remove the comments (#) to activate these lines. You can quickly search for these lines by using CTRL + s (in emacs) and typing “ssl”.

The two lines should now look like this:

LoadModule ssl_module         libexec/httpd/libssl.so

AddModule mod_ssl.c

Now find the “ServerName” directive and make sure it has 127.0.0.1 for it’s entry.

ServerName 127.0.0.1

Finally, just below the last line of the current httpd.conf, enter the following information which covers some of the global SSL directives and the specific directives for the port based virtual hosts.

<IfModule mod_ssl.c>
# Some MIME-types for downloading Certificates and CRLs
  AddType application/x-x509-ca-cert .crt
  AddType application/x-pkcs7-crl .crl

# inintial Directives for SSL

  # enable SSLv3 but not SSLv2
  SSLProtocol all -SSLv2
  SSLPassPhraseDialog builtin
  SSLSessionCache dbm:/var/run/ssl_scache
  SSLSessionCacheTimeout 300
  SSLMutex file:/var/run/ssl_mutex
  SSLRandomSeed startup builtin
  SSLLog /var/log/httpd/ssl_engine_log
  SSLLogLevel info
##
## SSL Virtual Host Context
##
<VirtualHost 127.0.0.1:80>
  #Just to keep things sane...
    DocumentRoot "/Library/WebServer/Documents"
    ServerName 127.0.0.1
    ServerAdmin bobdavis@mac.com
    SSLEngine off
</VirtualHost>
<VirtualHost 127.0.0.1:443>
  # General setup for the virtual host
    DocumentRoot "/Library/WebServer/Documents"
  #ServerName has to match the server you entered into the CSR
    ServerName 127.0.0.1
    ServerAdmin bobdavis@mac.com
    ErrorLog /var/log/httpd/error_log
    TransferLog /var/log/httpd/access_log
  # SSL Engine Switch:
  # Enable/Disable SSL for this virtual host.
    SSLEngine on
    # enable SSLv3 but not SSLv2
	SSLProtocol all -SSLv2
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
  # Path to your certificates and private key
    SSLCertificateFile /etc/httpd/ssl.key/server.crt
    SSLCertificateKeyFile /etc/httpd/ssl.key/server.key
    <Files ~ ".(cgi|shtml|phtml|php3?)$">
      SSLOptions +StdEnvVars
    </Files>
    <Directory "/Library/WebServer/CGI-Executables">
      SSLOptions +StdEnvVars
    </Directory>
# correction for browsers that don't always handle SSL connections well
    SetEnvIf User-Agent ".*MSIE.*"
    nokeepalive ssl-unclean-shutdown
    downgrade-1.0 force-response-1.0
# Per-Server Logging:
# The home of a custom SSL log file. Use this when you want a
# compact non-error SSL logfile on a virtual host basis.
    CustomLog /var/log/httpd/ssl_request_log
    "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x "%r" %b"
</VirtualHost>
</IfModule>

At this point, save your document (CTRL-x CTRL-s) and close emacs (CTRL-x CTRL-c).

There are many directives you can add to the SSL configuration for your machine, including extended logging, restrictions on ciphers used, encryption levels, etc. Full documentation is included in the Apache documents provided with Mac OS X (/Library/Documentation/Services/apache_mod_ssl/index.html) or on-line at http://www.modssl.org/.

Now it’s time to start your SSL enabled web server. You have the option of using either the command line or the Sharing control panel to start your web server. Since you have removed the passphrase requirement from your server key, it’s very simple. Either start Web Sharing from the control panel, or type either of the following lines into the command line:

sudo httpd -D SSL
sudo apachectl start

You will be asked for your system password, and you’ll get the output of Apache starting. It’s that simple. If you have Web Sharing set to start at startup it will start normally (this is why we removed the passphrase requirement).

Now test your installation using the browser of your choice by trying to access https://127.0.0.1/. Netscape 6 and Safari provide more information and allow you to accept unknown Certificate Authorities very easily. Microsoft’s Internet Explorer 5.x still has issues with unknown certificate issuers and will fail authentication.

Using Netscape, you’ll see the little open lock in the right corner has become a closed, illuminated lock. Success! You have enabled mod_ssl in your Mac OS X development environment.

Mention of non-Apple products or services is for informational purposes only. Apple assumes no responsibility with regard to the selection, performance, or use of these products.

Of the many options out there, many people choose to run their own blogging software as opposed to a managed service like Blogger or TypePad. On the software side, there are many decent tools available, such as Six Apart’s Movable Type (we have a tutorial for installing MT as well). WordPress is another mature, capable and free blogging engine that is very popular with many bloggers (like its founding developer, Matt Mullenweg) and rapidly gaining in popularity across the Web. WordPress is an excellent choice for a personal or professional blog, and the price is right, too. This tutorial will show you how to install WordPress 1.5.1.3 on OS X 10.4 Tiger.

Note: The most recent version of WordPress is 1.5.1.3, which contains a security patch among other improvements. This tutorial is fully compatible with the most recent version of WordPress. Version 1.5.1.3 is recommended for all WordPress users (upgrade instructions).

If you have installed another blog engine such as WordPress or Movable Type already, you may already have MySQL and/or PHP configured. If this is the case, you can skip right down to step 4.

Before we get started, let’s summarize what we’ll be going over in the installation:

1. Downloading and Installing WordPress 1.5.1.3
2. Enabling Personal Web Sharing
3. Downloading and Installing MySQL
4. Configuring MySQL
5. Enabling and Testing PHP
6. Configuring WordPress
7. ???
8. Profit!

Downloading and Installing WordPress 1.5.1.3

If we’re going to blog our way to stardom, we’ll need some blogging software, right? The first step we’ll take will be to download the latest stable version of WordPress, version 1.5.1.3. The compressed file should be about 250KB, and OS X will decompress it for you.

Once it’s decompressed, we’ll move the wordpress directory to OS X’s Web hosting directory in /Library/WebServer/Documents. By default, all requests for the domain’s root directory (like http://maczealots.com/) will go to this directory. This can be changed in Apache’s httpd.conf file, which we’ll cover later. If you like, you can also change the name of the wordpress directory to something else, like blog. This way the URL of the blog would change to http://www.yoursite.com/blog/ Additionally, if you want the blog itself to be at the root directory, delete all the items from the /Library/WebServer/Documents directory and move the contents of the wordpress directory to the now-empty Documents folder.

Enabling Personal Web Sharing

“Personal Web Sharing” (PWS) is Apple’s marketing name for Apache, the industrial-strength, tried-and-true Web server du jour. When you enable PWS, OS X starts up Apache, registers the modules, opens ports, etc. Since we’ll be serving the blog, we’ll need to have Apache running.

To enable Personal Web Sharing, open the Sharing preference pane in System Preferences. Check the box labeled “Personal Web Sharing”, and that’s it. (You may have to authenticate as an administrator before it will let you enable anything.) Go ahead and close System Preferences; you’re ready to install MySQL now.

Note: We are working on a version of this tutorial that includes the ability to host the database with SQLite, which is prepackaged in OS X 10.4. However, support for SQLite in WordPress is still being fully developed, so for now MySQL is still the way to go. If you’d like to see such an article, let us know.

Downloading and Installing MySQL

MySQL is the database backend that WordPress (and other blogging packages like Movable Type) can use to store blog entries, users, comments, etc. MySQL is free for personal use. First, download MySQL (4.0.24 at the time of publication). It will come as disk image with two packages and a readme. We will be installing both packages. First, open the main MySQL installer. It will install all the necessary components to run MySQL onto your OS X volume. After that installer has completed, run the startup item installer, which will automatically start up MySQL after any computer restarts.

Note: One of the most common problems reported is that people install MySQL 4.1 instead of 4.0. I can understand the desire to be on the bleeding edge of software, but WordPress (and most other blog/CMS engines) use an older authentication scheme that is incompatible with MySQL 4.1 and greater. There are hacks and workarounds out there, but for the easiest installation, stick to MySQL 4.0.

Configuring MySQL

Now that you have installed MySQL, let’s configure it so WordPress can access it. Open a new terminal session (found in /Applications/Utilities/Terminal.app) and type the following commands to navigate, make some changes, and start the MySQL daemon:

cd /usr/local/mysql
sudo chown -R mysql data/
sudo echo
sudo ./bin/mysqld_safe &

Next, let’s launch MySQL and use the test database (called test, even) to make sure everything’s running correctly:

/usr/local/mysql/bin/mysql test

If everything’s running correctly, you should see output similar to this:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1 to server version 4.0.24-standard

Type 'help;' or '\h' for help.  Type '\c' to clear the buffer.

mysql>

Once you’ve verified that MySQL is running correctly, use the command quit to return to the console prompt.

Now that MySQL is running, we’ll change the root password of MySQL so that WordPress (and you) can access it later. Use this command (where yourpasswordhere is replaced by your chosen password):

/usr/local/mysql/bin/mysqladmin -u root password yourpasswordhere

The last thing we’ll have to do in MySQL is to create a table for WordPress to store its data. We’ll call it wordpress to keep things simple. To accomplish this, we’ll enter MySQL, create the table, and allow WordPress to edit it.

/usr/local/mysql/bin/mysql -u root -p
CREATE DATABASE wordpress;
quit

Enabling and Testing PHP

Now that MySQL is ready to go, let’s fire up PHP. OS X ships with PHP installed, but not activated. Fortunately, this is really easy to do. The only file we’ll need to edit is httpd.conf, which Apache uses for its configuration.

Open the config file in your favorite editor (I’ll be using pico):

sudo pico /etc/httpd/httpd.conf

Mosey on down to the Dynamic Shared Object (DSO) Support section. It’s the one with all the LoadModule listings. The one for PHP 4 is towards the bottom of that list. Look for the line and uncomment it to activate it. You can uncomment a line by removing the pound symbol (“#”) from the beginning of the line. The new line should look as such:

LoadModule php4_module

We’ll also need to uncomment the PHP 4 entry in the AddModule listings, so that it looks as such:

AddModule mod_php4.c

Once those two lines are edited you can save the httpd.conf file and quit the editor. Since we’ve edited Apache’s load setup, we need to restart Apache so it will recognize the changes:

sudo apachectl graceful

With that out of the way, let’s make sure that PHP is indeed running. Create a new text file in your favorite editor (stay away from RTF-happy TextEdit, though – SubEthaEdit gets my vote) and fill it with the following text:

<?php
phpinfo();
?>

Save the file as test.php in the root directory (/Library/WebServer/Documents/) and load the address of the page (usually http://localhost/test.php) into a Web browser. If PHP was correctly enabled, the phpinfo(); command should output page after page about the PHP installation. If not, retrace your steps – it can be easy to make a mistake.

Configuring WordPress

Now for the last step: configuring WordPress. First, you’ll need to edit WordPress’ default configuration file wp-config-sample.php. You’ll find it in the root folder of the WordPress installation. This is where you’ll set up the database information. Edit the following settings:

define('DB_NAME', 'wordpress'); – Change ‘wordpress‘ to the name of the database you created in MySQL (in the example we named it wordpress).
define('DB_USER', 'username'); – change ‘username‘ to root.
define('DB_PASSWORD', 'password'); – change ‘password‘ to the MySQL password you chose.

Once you’ve made the changes, save the file as wp-config.php in the same directory and delete wp-config-sample.php.

Now, open a Web browser window and start the WordPress installer, found at http://localhost/blog/wp-admin/install.php. (Remember that if you chose to install WordPress in a different directory, such as the root directory, the address will be different for you.) WordPress will take you through the install process and set up the database with all the tables it needs to run.

After it completes, it will give you the login (admin) and password to log in to WordPress. The password is randomly generated and not recoverable so please write it down!

After you log in, there are two things you need to immediately do. First, change your password to something you can remember. You can find it in the Users tab of WordPress’ controls. Also, to avoid posting entries as “Administrator”, you can either create another account with a posting name, or simply enter a nicknaame in the admin account. But whatever you do, change the password and remember it — once you lose it, your data is hard to get back.

Now comes the moment you’ve been waiting for. Click View site » in WordPress’ controls or open a Web browser and go to http://localhost/blog and watch your blog appear! Roll up your sleeves, perfect the CSS, and wax poetic, serving it to the free world without spending a dime on extra software. Happy blogging!

by Joel Rennich, mactroll@afp548.com

The purpose of this article is to give you an idea of what you can do with SSL in Mac OS X Server and how you can use that to secure as many services as possible. So, first we’ll talk some about SSL in general and how to create the certificates, then we’ll discuss what to do with those certificates.

SSL certificate creation

Before we start I’d like to point out that we are going to be creating home-rolled SSL certificates here. As such you will run into problems when connecting to your Server using applications like a Web browser. Most applications will allow you to ignore the fact that your certificate hasn’t been validated by one of the internationally recognized certificate authorities, but it’s still a pain.

I’ll show you how to get around that by importing in your own certificate authority onto your client machines. This presumes that you have control over all of your clients, so for internal use where you control both the server and the client setups being your own certificate authority is great. If you plan on doing business with the general public, such as using it for credit card processing on a Web page, I would strongly recommend that you invest the money in a “real” certificate.

If you do buy one at least take a look at www.qualityssl.com. They have really good prices and are Mac-based, so you can keep it in the family.

Also all of the openSSL work, such as generating and signing certificates, can be done on Mac OS X client.

1. Make a certificate authority (CA).

This should be done in a secure place, since if your CA gets compromised then all of your security goes out the window. A decent place for this would be on your most secure server or on your own machine.

It doesn’t matter where on the filesystem you do this; however, I personally prefer to create a CA directory in /etc:

sudo mkdir -p /etc/certs
cd /etc/certs

Right now this folder has fairly relaxed permissions on it. As soon as were done we’ll change that to greatly limit access to the folder. Now that we have our place we need to begin generatng the CA. We do this by making a certificate signing request (CSR). This example will generate a 3DES encrypted 2048 bit key. This is a rather high security key which means it takes longer to process. So if you feel the need you can scale it down to 1024 bits if you like. Although I haven’t had any problems using this with Mac OS X 10.2 and Windows 2000.

openssl genrsa -des3 -out ca.key 2048

You will be asked for a passphrase for this key. You need to both remember this phrase and keep it secure. Your entire SSL system will depend on this passphrase being secure.

Now that you have the request you can sign it into a CA.

openssl req -new -x509 -days 4096 -key ca.key -out ca.crt

You’ll be asked for the passphrase that you just set up. After that your certificate authority will be valid for 4096 days.

You now have a full blown certificate authority for your machine. From this we will base all of your other certificates from it.

2. Generate a certificate for your server.

You will need one for each domain that you have; i.e., mail.afp548.com and www.afp548.com will each need one if you want to secure both sites.

So first we will generate a new private key.

openssl genrsa -des3 -out server.key 1024

You will be prompted for a password here also. This should be different from the password for the CA. Just remember it because you will need to enter it into Server Admin to get SSL running.

Now you need to generate a request with the private key.

openssl req -new -key server.key -out server.csr

Again you will be asked for a password. This is the one you entered in the step above. Then you will get a bunch of questions. They all really don’t matter except for common name. This needs to be the fully qualified name of your Web server, like www.afp548.com. If this is wrong you will get errors in the browser. Also: leave the challenge password blank.

Now we need to set up a few folders so that we can actually sign the certificate.

mkdir -p demoCA/private
cp ca.key demoCA/private/cakey.pem
cp ca.crt demoCA/cacert.pem
mkdir demoCA/newcerts
touch demoCA/index.txt

            echo “01” > demoCA/serial

You can now actually sign the server certificate with your newly minted CA.

openssl ca -policy policy_anything -in server.csr -out server.crt

The password you are prompted for is the password you assigned to the CA, the first one, not to the certificate itself. If you need to create more certificates you will only need to do the last three steps for each.

Finally to keep things secret and to keep things safe, change the permissions on this folder.

sudo chmod 700 /etc/certs

Now you can take all of your pieces and make the sites secure.

3. Securing your web site.

Go into Server Admin and make sure that the SSL module is enabled in the modules pane under settings.

Then go to the site that you want to secure. Change the port to 443, click on the security button, and enable SSL by checking the box at the top. Then you need to open up some of the files that you have created in TextEdit, or any text editor, and copy and paste them into the three appropriate spots. Copy server.crt into “Certificate File.” Copy server.key into “Key File,” and copy ca.crt into “CA File.”

Finally, you’ll want to enter the passphrase for the server certificate into the “Pass Phrase” field or else you’ll have to be at the server everytime it starts up.

A few parting thoughts about securing Web connections. You will need a separate IP address for every SSL site that you have. There’s a complicated reason for this, but it involves how SSL connections begin and I don’t know of any way around this. In 10.2 you had to edit the httpd_macosxserver.conf file to get higher level encryption. This requirement seems to be gone in 10.3 as it defaults to using all ciphers.

When you are done your certificates will be stored in /etc/httpd/ssl.crt and /etc/httpd/ssl.key. Your site’s specific config is stashed in /etc/httpd/sites/your site’s name. So look in there for any specific info. Also the passphrase that you used is stashed in /etc/httpd/servermgr_web_httpd_config.plist, which is root-readable only.

4. Securing LDAP

We run into a bit of a problem here. OpenLDAP doesn’t like a server key that has a passpharse associated with it. Postfix and Cyrus are going to be the same way. So remove the passphrase.

openssl rsa -in server.key -out serverno.key

Now go back into Server Admin. Select the Open Directory settings and go to the “Protocols” tab. Check the “Use SSL” box and then put the path to your certificates in the three fields.

Certificate: /etc/certs/server.crt
SSL Key: /etc/certs/serverno.key
CA Certificate: /etc/certs/ca.crt

OpenSSL runs as root, so it will be able to get into /etc/certs without any issues. As soon as you save this config Server Admin will restart OpenLDAP with SSL support.

The SSL configuration for OpenLDAP is stored in /etc/openldap/slapd_macosxserver.conf.

5. Securing SMTP

Postfix can be setup to use the same certificate as the one you established for openLDAP. However, it wants to have both the key and the certificate in the same file. This is easily done.

sudo cat /etc/certs/serverno.key /etc/certs/server.crt > /etc/certs/server.pem

Now link that file to what Postfix is looking for.

ln -s /etc/certs/server.pem /etc/postfix/

Now reload Postfix through the GUI or by doing this from the command line.

sudo postfix reload

And start using encrypted SMTP services.

The SSL configuration for Postfix is kept in /etc/postfix/main.cf.

6. Securing POP/IMAP

Cyrus can use the same certificate as Postfix, but it needs to be accessible by the cyrus user. That requires relaxing the permission a bit on the certificate store.

sudo chown :mail /etc/certs
sudo chmod 750 /etc/certs
sudo chmod -R 700 /etc/certs/demoCA

Now you can link the server.pem file into where Cyrus POP and IMAP want to find it.

ln -s /etc/certs/server.pem /var/imap/server.pem

Now go into Server Admin and set up POP/IMAP to use SSL in the Advanced button of the Mail Server settings.

Set your mail client accordingly and securely read your mail.

The SSL configuration for Cyrus is stored in /etc/imap.conf.

7. Enable your clients

Since your CA is self-signed all of your Mac OS X applications and services will yell at you for using it. You can get around this by adding the cert to the client’s x509 Anchors keychain. Essentially this is the root CA file for your machine.

Do this by copying over to the client machine the ca.crt file that you created in the first step. Then install it by doing

sudo certtool i ca.crt v k=/System/Library/Keychains/x509Anchors

Your client will now trust certificates that you have signed into being with this CA. If you do this right, you’ll use the same CA for all of your servers and their services. That way you’ll only have to import one file into the clients x509Anchors.

8. E-mail certs

This bit is for bonus points, but all the cool kids are doing it and so should you. Mail.app in 10.3 allows the use of s/mime certificates. These are PKI certificates that act similar to SSL certificates and can sign and or encrypt e-mail.

The easiest way for a personal user to get a certificate is to head over to www.thawte.com and sign up for their free community mail certificate. Really good instructions for this can be found here:

http://joar.com/certificates/

However, if for some reason you feel like making your own, read on. Note that this is mostly an exercise in what you can do with OpenSSL. Since the Thawte certificates are free and easily available you’re probably better off using them. However, if you want to outfit your entire organization with home rolled certificates, well here you go. Just be careful to only use this between users that have imported your root CA that you created.

To do this you need to first generate a certificate for your e-mail user. This is pretty much the same thing as generating one for a server.

openssl genrsa -des3 -out mail.key 1024

Give it a pass phrase to lock it up.

openssl req -new -key mail.key -out mail.csr

Here, you’ll want to use your real name for the Common Name. Joel Rennich is what I would use. Then make sure that you fill out the e-mail field with what you have set up in Mail.app as your e-mail address. Capitalization is important here. I would use “mactroll@afp548.com”.

Now sign this cert with your CA.

openssl ca -policy policy_anything -in mail.csr -out mail.crt

You’ll enter in your CA password and then commit the signature.

Finally you can convert the signed certificate into the format that is used for s/mime. When you do this it will first ask you for your mail certificate password that you set up a few commands before. Then it will ask you for an export password. This can be the same of different, it doesn’t matter, but you will need to use the export password when importing this certificate into your Keychain so you can use it with mail.

openssl pkcs12 -export -inkey mail.key -certfile mail.crt -in mail.crt -out mactroll.p12

This is your “official” e-mail certificate. Copy this over to your client machine and double-click. Keychain Access should launch and ask you for your export password. The certificate will then be imported into your keychain and immediately usable by Mail.app for the account that you specified in the e-mail field when you generated it.

9. Other odds and ends

When you sign your certificates with your CA openssl uses a default config file which can be found at /System/Library/OpenSSL/openssl.cnf. If you want to change any of the defaults go here. For example, certificates that you sign will only be valid for 1 year, unless you edit this file to change that.

Okay, so this was very much a case of fumbling around in the dark until stuff worked, lot’s of Googling and breaking stuff. The end result is a dev server on OS X that is running Textpattern with clean URLs and a copy of WordPress for good measure. These notes are primarily so I don’t forget how I did it, if they are useful to someone else, great! Be warned, though, I have no idea how secure this set up is and what flaws it has, so you follow these instructions at your own risk! Also, I am using OS 10.3.9 so I don’t know if this would work on Tiger.

Turn off Personal Web Sharing

OS X does, as you probably know, ship with Apache and it’s real easy to switch on and for a while I did use it. I am quite interested in learning a bit more about the whole serving up websites business, so first job is to do away with all the pre-installed Mac stuff.

Go to System Preferences > Sharing and make sure Personal Web Sharing is stopped.

Software

I started off with Mamp and that is probably good enough for a basic set up but I wanted to run Textpattern with clean URLs. Getting mod_rewrite to work on Mamp just wouldn’t happen for me. So after a bit of Googling I came up with these downloads in preparation for my mission… gulp!

• Complete MySQL
• Complete Apache2
• Complete PHP4
• CocoaMySQL
• Web Control (Scroll down the page a bit)

Terminal

You will need to have at hand Terminal in order to do some of the stuff. This is located in Applications > Utilities. This is the best bit actually because you get to feel like Neo for five minutes! Be careful though, I am told you can do some serious damage with Terminal.

Show hidden files

Having already had a play with Mamp, I noticed that I couldn’t see .htaccess files. Also when installing Complete MySQL there was another hidden file I needed to get to. Eventually I found a note on Apple’s developer site that describes how to show hidden files. It’s gonna make your Mac look at little messier than before but it’s kind of essential:

Open up Terminal and type in the following:

defaults write com.apple.Finder AppleShowAllFiles true

And that should be that.

Complete installs

The links to the three Complete packages are self explanatory. Each comes with a detailed Install document, follow them and you can’t go wrong, much.

The only problem I ran into was creating a .bash_profile document in the home directory. With hidden files now showing I could see that my home directory (the house with my name on it) had no .bash_profile in it, so I created one with TextEdit. Again, something to watch out for is TextEdit saving it with an extension e.g. .bash_profile.rdf. If this happens click on the file and press COMMAND + I which will bring up the File Info panel and you can simply delete the .rdf from the Name & Extensions panel

In truth this had little effect for me when trying to access mysql via Terminal, unless I used the complete path i.e. /Library/MySQL/bin/mysql. Given that I have no intention of using Terminal for accessing MySQL I didn’t worry about it and it has not had any impact on this setup thus far. Note: If anyone does know why I was getting a command not found error, I’d love to know.

One other note with these complete installs is the location they end up in. Obvious now but it caused me a bit of confusion, they are in the root library file and not the library file in you home directory. To find this spot open up your hard drive and look for the Library folder

phpMyAdmin versus CocoaMySQL

I had a bash at installing phpMyAdmin but to be honest they may as well have written the instructions in Wookie. I stumbled across CocoaMySQL after a bit of Googling, opened it up, it found the path to my MySQL server and within five minutes I had created a database as was running a local copy of Joshuaink. I thoroughly recommend it for the less technically minded.

Also worth noting is that which ever way you access MySQL, you can use your root account and the password you set when setting up MySQL for all your databases which is pretty damn convenient.

Httpd.config

Certainly if you are going to be experimenting, the httpd.config file will come into play. I started off with the Web Control app because it makes back ups, reverts easily back to the original file if you mess it up and it can check your syntax for you and if you aren’t feeling confident it’s a great way to start. It soon started to get a bit frustrating though because I couldn’t do a find search to locate bits of the document.

I ended up going back to TextEdit but found I could no longer save the file from that app (though I could from Web Control). I am not sure if this happens by default or whether Web Control did it when it first ran but it turned out that the conf directory, located at /Library/Apache2/conf was locked, so again clicking on the directory and COMMAND + I brings up the info and I changed the Ownership & Permissions details from Owner: system to Owner: [my username]. I also did the same to the httpd.conf file for good measure and made sure they were both set to Read & Write for owners.

Virtual hosts

Virtual hosts were one of the big things I wanted to get done and I found two tutorials. One over at Mezzoblue and one over at SitePoint (scroll down the tutorial a bit). In the end I opted for the SitePoint one because it was getting late and my head seemed to manage with it a little better, though the URLs it produces are no where near as cool as Dave’s. Again something to consider if you do use the SitePoint one, be careful with your naming conventions because it can impact how you use the web. For example I had a directory called joshuaink and where I used to just type joshuaink — as opposed to the full URL — into Firefox to reach my live site, I was now being taken to my localhost.

DirectoryIndex

It wasn’t until I opened up the WordPress admin that I noticed I was getting a directory listing and had to manually click on index.php to get to the login page. This seems to be something to do with the DirectoryIndex bit of httpd.conf. Initially I was dropping the .htaccess file that ships with Textpattern into each and every directory with an index.php as it’s starting point and it did solve the problem but that was getting a bit tiresome. Eventually I found out that there is something called DirectoryIndex in the httpd.conf file and having located it I changed it to this so that Apache recognises an index.php:

DirectoryIndex index.html index.htm index.php index.html.var

I really don’t know if that is correct but it seems to have solved the problem.

Deleting .htaccess files

My final problem was deleting those .htaccess files I had spread everywhere and OS X wouldn’t let me because it is a hidden file. To solve this I renamed it to .htaccess.txt and then I could delete it.

Conclusions

I have got a lot to learn about Apache but it was an interesting start and well worth the effort. With my iBook mostly offline, security is not a big deal for me. No doubt I will continue to fiddle until it breaks. If you have any tips or see something very wrong with the way I have setup, please do say.

Apple’s WebObjects is a comprehensive suite of tools and frameworks for quickly developing Java server applications. The release of WebObjects 5.2 allows developers to add standards-based web services to these applications, as well.

WebObjects gives you the ability to build or use web services without writing low-level SOAP, XML or WSDL documents. The WebObjects tools enable code-free generation, configuration and testing of web services from existing data assets. Because these web services can interoperate with clients written in many languages, including Java, AppleScript, and Perl, you can quickly create integrated solutions that would otherwise require a lot of coding.

This article shows you how to take an existing database and publish assets as web services, including a service description, all without writing any code.

Installation

If you don’t own your own copy of WebObjects 5.2, it is
available in a free trial version for Mac OS X version 10.2
or later at Apple
Developer Connection. Directions on how to find the
download are on the
href=”http://www.apple.com/webobjects/getting_started.html”>

WebObjects – Getting Started page. We will be working
with Mac OS X 10.3 and Xcode so you will also need the Xcode
Tools for Mac OS X, available for download at the Apple
Developer Connection web site, in the Developer Tools
section. After you download everything, install the
WebObjects_X_Developer package in the Developer
folder and restart your system. You must upgrade to
WebObjects 5.2.2 via Software Update or you can get the
manual update at the page
href=”http://docs.info.apple.com/article.html?artnum=107649″
>About the WebObjects 5.2.2 Update.

If you don’t want to build the project by hand and just want to run it, you can download the example used in this article.

The Data Model

Installing WebObjects installs a sample database in addition to the WebObjects tools. Navigate to /Library/Frameworks/JavaRealEstate.framework/Resources/ and open the RealEstate.eomodeld file. This launches EOModeler and opens the model file of a ficticious real estate database of houses in Silicon Valley. EOModeler is used to reverse-engineer databases, automatically finding all tables, columns and relationships. At runtime the WebObjects persistence engine automatically maps and generates Java objects from JDBC databases. You don’t need to write any SQL code.

The image below shows the tables found in the real estate database on the left; however, EOModeler refers to them as entities. We’re going to work with two of them, Listing and ListingAddress. On the right are the attributes (columns) of a Listing. You may quit EOModeler. We don’t need it anymore.

Building the Server Application

The model can now be used to automatically generate a web services-enabled server application. First, launch Xcode, located in /Developer/Applications. Choose File > New Project. In the New Project Assistant, select Direct to Web Services Application. Name the project Houses. Accept the defaults until you see the Choose EOModels pane. Add the RealEstate.eomodeld model file at /Library/Frameworks/JavaRealEstate.framework/Resources. In the Build and Launch Project pane, deselect “Build and launch project now” and click Finish.

In the Xcode main window, click the triangle next to Resources. Select the Properties file and edit it so it looks like this:

WOAutoOpenInBrowser=false

WOPort=55555

Click the Build and Run button in the Xcode toolbar to build and run the application. When you see the message Waiting for requests..., the WebObjects server application is running.

Everything should look like the image below:

Configuring the Web Service

To customize a Direct to Web Services application you use the Web Services Assistant. It’s located in /Developer/Applications.

After you launch the Assistant, the Connect dialog appears. Enter http://localhost:55555 in the text input field and click Connect.

Most web services define a service with one or more operations, or methods. We’ll build a service HouseSearch and define an operation searchByPrice, which finds all house listings under a certain price. In addition to searching, WebObjects can generate Web service operations that let you insert, delete or update entries in a database.

In the Web Services Assistant main window, select http://localhost:55555 in the left-hand side list. Click the New Service toolbar button. Enter HouseSearch in the Service Name text field. Select Listing in the Available list of the Public Entities pane and add it by clicking the left-pointing arrow. Repeat for ListingAddress, making sure that the Enabled option is selected.

Now you add an operation to the HouseSearch Web service and define the calling arguments:

Click New Operation in the toolbar.

Enter searchByPrice in the Name text field.

Choose Listing from the Entity pop-up menu. Make sure the Type is search. Click OK.

In the main window, select askingPrice in the Available list in the Arguments pane and click the left-arrow button.

Choose “<=” from the Operator pop-up menu.

Select Return SOAP Struct.

Everything should look like the image below:

Now, define the return values for this operation:

In the Return Values pane, select askingPrice from the Available list and click the left-arrow button.

Click the triangle next to address. Select address.street and click the left-arrow button. Repeat for address.city, address.state and address.zip.

Click the Save toolbar button.

You have now defined the HouseSearch service with the searchByPrice operation that finds all houses with an asking price less than or equal to its askingPrice argument and returns an array of listings, each with their asking price and address.

Everything should look like the image below:

Testing the Service

Select searchByPrice under HouseSearch under http://localhost:55555.

Click the Test toolbar button. A test window is automatically generated with the appropriate user interface to test the searchByPrice operation.

Enter 250000 in the text input field and click Test. An empty list is returned. That is because a quarter of a million dollars won’t buy a home in Silicon Valley. Try again, entering 300000. This time three entries should be returned with their asking price and address.

See the image below:

Generating WSDL Documents

Web Services Definition Language or WSDL is an XML format for describing web services and the operations they provide.

In the test window, click the WSDL tab. The WSDL document describing the HouseSearch Web service and its searchByPrice operation appears.

The WSDL document can also be retrieved directly from the server via the URL http://localhost:55555/cgi-bin/WebObjects/Houses.woa/ws/HouseSearch?wsdl. If you want to download the WSDL document and look at it, using the curl command is a convenient way to do so. In Terminal, execute the following command:

curl 'http://localhost:55555/cgi-bin/WebObjects/Houses.woa/ws/HouseSearch?wsdl' -o mywsdl.txt

Conclusion

You have developed, configured and tested a working Web
service with WebObjects without writing any SOAP, XML or
Java code. In addition, you learned how to obtain the WSDL
description that you can publish so client applications can
be built that use the service.

For more information about web services and WebObjects,
please refer to the manual titled “Web Services”
on the WebObjects Documentation site.

Editor’s note: WebObjects can do a lot more than web
services, including dynamic Web pages and distributed Java
Client applications. To find out more about WebObjects,
visit the
href=”http://www.apple.com/WebObjects/”>Web Objects page.

A single Xserve is ideally suited for smaller scale Web hosting, where the task is to host a handful of moderate-traffic sites. (With a fleet of Xserves, you could host an eBay or an Apple.com, but that’s a topic for another article.) The Xserve’s Apache Web server software has a multitude of configuration options. In this article, I will go over how to set up Apache to serve multiple Web sites from the same machine—so-called “virtual hosting.” I will also look at ways to optimize the server’s setup for fast, robust Web hosting. This article assumes that you have already followed the steps in the Mac OS X Server Administrator’s Guide to start Web service. (You can find the Guide on the Mac OS X Server Manuals page.)

Hosting Multiple Domains on One Server

The out-of-the-box behavior of Apache is to have one IP address and to serve one domain. However, it is quite easy to transparently host thousands of domains on a single Xserve, and the users need never know that it’s one machine behind the scenes and not a whole farm. There are two approaches to this sort of “virtual hosting”—IP-based and name-based. With IP-based hosting, each domain name is mapped to its own individual IP address. Name-based hosting uses a little trickery so that many domains can be served from the same IP address. IP-based hosting is a little more robust—it allows for secured HTTPS transactions, which are important for Web commerce, reverse DNS, and some other features; but IP addresses are scarce, so name-based hosting, which works perfectly well, is probably preferable for most applications. Name-based hosting depends on a certain header sent by the browser, and as a result it doesn’t work with some browsers released before 1997, but that is less and less of an issue as those browsers become increasingly scarce. I will go over how to set up both kinds of virtual hosting.

IP-Based Hosting

Assuming you have already acquired the domain names and IP addresses you’ll be using, the first step in creating an IP-based hosting setup is to configure the Xserve to have multiple IP addresses on the same Ethernet card. This can be done from System Preferences on the Xserve. Open the Network Preferences pane. Select “Active Network Ports” from the Show drop-down menu. Choose the port corresponding to the Ethernet card that you want to assign multiple IP addresses to, and click “Duplicate.” Then simply change the duplicate configuration to reflect the second IP address. It is necessary also to make sure that the Subnet Mask setting for all but one of the ports is 255.255.255.255. This will prevent conflicts in the routing tables.

On a headless Xserve, the same thing can be accomplished with the IPAliases startup item. If the file /etc/IPAliases.conf doesn’t exist, create it. For each additional IP address, this file should contain one line of the form

interface:IPaddress:netmask

For example, to add the IP address 192.168.50.210 to the en0 network interface, the following line would be used:

en0:192.168.50.210:255.255.255.255

The netmask should always be 255.255.255.255.

In addition, IP aliases must be turned on, by adding to /etc/hostconfig the line

IPALIASES=-YES-

Every time the system is booted, the aliases listed in /etc/IPAliases.conf will be added. The file can contain any number of aliases.

With multiple IP addresses configured, the next step is to add DNS entries. For each domain that you want mapped to an IP address, create an A record in the DNS pointing the address to the site. In BIND, the A record might look like this:

firstdomain.com.   A   10.151.90.2

All of the records for the various domains can be in the same DNS file or in different ones, depending on the preferences of your users and whether you host your own DNS or not.

Finally, tell Apache how to deal with requests for the various addresses. In Server Settings, click Web in the Internet tab. Choose “Configure Web Service” from the drop-down menu. In the Sites tab, you can add as many sites as you like, just by entering the domain name and IP address for each one. The content for each site should be placed in the folder you specify in the “Web folder” field here.

Name-Based Hosting

Setting up name-based hosting is a bit simpler. Add DNS records for each domain to be hosted, such that each domain name resolves to the same single IP address—the one associated with your Xserve. When a user’s browser makes a request for one of the domains, it will send an HTTP Host header indicating which domain it is requesting. Apache interprets this header and returns the appropriate content.

After the DNS is configured, go to Server Settings’ Internet tab, and choose “Configure Web Service” from the Web drop-down menu. Go to the Sites tab. Here you can create an entry for each site you want to serve. Give each one the same IP address but different domain names. Content will be served from the location specified in the “Web folder” field.

If desired, name-based and IP-based hosting can co-exist.

Handling A Lot Of Domains

If you are hosting quite a few domains, or adding new ones frequently, it can be inconvenient to add an entry for each one in Server Settings. The process can be automated to a degree, so that simply adding a DNS entry and creating a new directory for content on the Xserve is sufficient to launch each new domain. NOTE that this method and that of adding sites via Server Settings are mutually exclusive—new domains added in this way will not be reflected in Server Settings, and adding or editing sites in Server Settings will alter the configuration of the automatically created domains with unpredictable results. This method also precludes turning the performance cache on and off on a per-domain basis. That said, here are the basic steps.

First, configure a single site in Server Settings, with the correct IP address. The domain name you give it doesn’t matter. Save the changes.

Edit /etc/httpd/httpd.conf to uncomment the two lines beginning:

LoadModule vhost_alias_module

and

AddModule vhost_alias_module

Also, change the line

UseCanonicalName On

to

UseCanonicalName Off

Next, edit /etc/httpd/httpd_macosXserver.conf. There should be a long comment section starting with the line:

## The section below contains a block for each site (virtual host).

Below this comment section is the stanza to edit. It looks something like this:

#<RAdmin 100>NameVirtualHost 192.168.0.25:80

Listen 192.168.0.25:80

<VirtualHost 192.168.0.25:80>

#WebPerfCacheEnable Off

#SiteAutomaticallyDisabled Off

ServerName example.com

ServerAdmin webmaster@example.com

DocumentRoot "/Library/WebServer/Documents/"

DirectoryIndex index.html index.php

CustomLog "/private/var/log/httpd/access_log" "%{PC-Remote-Addr}i %l %u %t \"%r\" %>s %b"

ErrorLog "/private/var/log/httpd/error_log"

and so on.

The stanza may look somewhat different if performance caching is enabled.

There are just a few changes to make to this. First, on the ServerName line, you can place the fallback domain to which users of pre-1997 browsers will be sent. This line has to exist, but for users of modern browsers, it will be ignored.

Then modify the DocumentRoot line to look like this:

VirtualDocumentRoot /Library/WebServer/Documents/%0

and the CustomLog line to include %v :

CustomLog "/private/var/log/httpd/access_log" "%v %{PC-Remote-Addr}i %l %u %t \"%r\" %>s %b"

Save the file and restart Apache.

The VirtualDocumentRoot directive tells Apache to interpolate information from the server name, which in this case is read on the fly from the user’s browser, into the pathname. “%0” is a specifier representing the requested domain name. Thus, a browser request for http://domain-ten.com/index.html will be answered with the file at /Library/WebServer/Documents/domain-ten.com/index.html.

As a result, to host a new domain, all that has to be done is to create a new directory corresponding to the domain name in /Library/WebServer/Documents, and to place content to be served in that directory.

The various specifiers understood by the VirtualDocumentRoot directive are explained on the apache.org website. For example, if you have hundreds of domains hosted, they can be sorted into 36 directories based on their first alphanumeric character with the following directive:

VirtualDocumentRoot /Library/WebServer/Documents/%1.1/%0

A side-effect of this aliasing technique is that log data for all the virtual domains is sent to the same file. Adding the “%v” specifier to the CustomLog line prepends the name of the domain to each log line. A simple script can be used to parse this master log file into individual files for each domain, if so desired. More information on CustomLog specifiers is available on the apache.org website.

Tuning Web Server Performance

When setting up an Xserve for use as a Web server, there are a number of things you can do to improve performance. Some of these techniques improve the performance of the machine in general; others involve examining where bottlenecks may be occurring and tuning the Web server to work around them.

First, it is important to make sure the hardware is up to speed. Even a low-end Xserve has a very nice feature set, including fast disk access, fast Ethernet, and a minimum of 256MB of RAM out of the box. The RAM allotment can be increased to 2 gigs: if the Web server at full-throttle seems to be using a lot of memory, buying more RAM could speed things up considerably. In terms of hardware, there are several options that will increase reliability, including IP failover to a second server, which is described in detail in the Admin Guide, and adding an Xserve RAID for ultra-fast and reliable storage.

In addition to the hardware approaches, there are a number of software-based strategies for optimizing a Web server. I will detail some of these below.

Apple’s Performance Cache

Included in the OS X Server installation is Apple’s performance cache. This acts as an intermediary between the Apache Web server and the user: the cache stores a copy of commonly requested pages from the sites served, and, upon receiving a user request for one of these pages, sends it along. This involves much less overhead than invoking Apache each time the page is requested. Apache is still kept busy serving dynamic and less common pages. The cache can be enabled and disabled individually for each of the sites served from the machine. In general, the cache is very helpful for highish-traffic sites that consist primarily of static HTML pages. The total size of the site’s popularly requested static pages should be small enough to fit in the machine’s RAM; otherwise caching may actually slow things down. For sites with primarily dynamic content, the cache will not be helpful.

To turn the performance cache for a particular site on or off, go to the Internet tab in Server Settings and click Web. Choose “Configure Web Service,” and then select the Sites tab. Edit the site you want to change, and go to the Options tab. Check or uncheck “Enable performance cache” and save. The changes take effect when the Web server is restarted from the Web drop-down menu. Note that this cannot be done with a server configured with dynamic site addressing, as explained above.

Aspects of the behavior of the cache can be configured in the file /etc/webperfcache/webperfcache.conf. The default settings seem to work quite well, but they can be adjusted to make the cache work better with tweaked Apache settings (see below) or unusual server configurations.

Tweaking Apache

Apache has various settings which control how it handles requests. Tuning these can make a big difference in the performance of the server.

Apache’s performance can be monitored by viewing yourhosteddomain.com/server-status in a browser. Configure the <Location /server-status> section in /etc/httpd/httpd_macosXserver.conf to control who can view the status: it’s set by default to deny all but localhost.

Eliminating Unnecessary Modules

The first step in speeding up Apache is to remove any unnecessary modules. To see which modules are compiled in, do the following:

In httpd.conf, there is a section that looks like this:

#<Location /server-info>#    SetHandler server-info

#    Order deny,allow

#    Deny from all

#    Allow from .your-domain.com

#</Location>

Remove the # from the beginning of each line to uncomment the directive. Change “.your-domain.com” to the actual domain(s) that you wish to access server information from, and then restart Apache.

Now http://yoursite.com/server-info should display a variety of detailed information about the server, including which modules are compiled in, and configuration information for each module.

Modules that are compiled in statically can’t be removed without recompiling the Web server. The out-of-the-box configuration of Apache on Xserve has almost every module compiled as dynamically loadable, so it is easy to turn off unnecessary ones without recompiling the Web server. Dynamic modules are loaded when Apache starts, according to the LoadModule and AddModule directives in the file /etc/httpd/httpd.conf.

The base installation of Apache that ships with OS X Server loads quite a few dynamic modules by default. Each of these takes up some memory, and some of them, such as mod_status, cause Apache to do extra work with every request. Any modules that aren’t necessary to the functioning of the sites you host should not be loaded. This can be controlled by commenting out (by prefixing a # on each line) the relevant LoadModule and AddModule directives for each module in /etc/httpd/httpd.conf. Every module has both a LoadModule and and AddModule directive—be sure to comment out both when disabling a module. Mod_include and mod_rewrite, among others, are notorious performance hogs.

Adjusting Processes

There are several directives that can be adjusted to modify how Apache handles traffic. Apache will spawn new versions of itself to handle requests. MaxClients sets the maximum number of these that will be spawned. The more of these there are, the faster Apache can handle a large number of requests—up to the limitations of the machine’s memory. The default is 500. Figure on about 1 MB of RAM for each httpd instance, and set MaxClients accordingly in Server Settings (or /etc/httpd/httpd_macosXserver.conf).

The MinSpareServers and MaxSpareServers directives, in /etc/httpd/httpd.conf, set how many spare server processes are running to handle sudden requests. StartServers sets how many are created when Apache first starts. You may want to increase StartServers and MaxSpareServers if Apache seems to be slowing down when it has to create new processes. When Apache spawns more than four child processes per second—a sign that it may need more spare servers—it logs that fact to its error log. Keep an eye on the log and tune if necessary.

MaxRequestsPerChild keeps a lid on potential memory leaks by killing off each child process after it has served a certain number of requests. The default setting on OS X Server is 100,000, which is reasonable. A setting of 0 means that Apache’s children are never killed.

The KeepAlive settings in /etc/httpd/httpd_macosXserver.conf control how each server process listens for new requests on a connection that has been established. Increasing KeepAlive requests reduces traffic from new connections, but increases server load with many Apache processes waiting around for orders.

Removing Extra Steps

Another key to speeding up Apache’s behavior is to minimize the number of things it has to do for each request. If the Web server is receiving a lot of requests, these extra tasks can bog it down tremendously.

HostnameLookups causes Apache to perform a DNS lookup for every incoming request, so it can log the domain name as well as the IP address in the access log. This should be turned off, as it is by default, if performance is an issue. The DNS lookups can be performed after the fact, on another machine, using a tool such as logresolve.

If AllowOverride is turned on, then Apache checks for the presence of .htaccess files containing overriding directives at every level of the hierarchy. This repetitive checking eats up server resources. For maximum performance, set AllowOverride None. (This is the default setting for OS X Server.)

FollowSymLinks is a directive that instructs Apache to follow symbolic links without performing an additional security check on them. If this is turned off, Apache slows down to check each symbolic link.

Finally, logging is very important for 95 percent of Web-hosting activities, but if you are not using it, turning it off will improve performance. All that file access slows things down considerably. Set TransferLog /dev/null in /etc/httpd/httpd.conf.

Temporary Adjustments

Sometimes, if you’re lucky, you have advance warning of a peak in Web traffic; say, a well-read news site is planning to link to one of the domains you host tomorrow. There are a few emergency preparations that can be made to allow for that kind of situation.

First, free up memory and CPU by offloading everything you can. If the Xserve is acting as a mail server, database server, or what-have-you, as well as a Web server, move those duties to another machine if possible. If there are other medium-traffic domains that could be hosted elsewhere temporarily, do it. Shut down unnecessary processes and cron jobs.

Second, make sure you have enough bandwidth. If you use a firewall, you may want to reconfigure its socket handling to maximize throughput.

If it is possible, making changes to the content of the
domain to be served can be very effective. Remove images, reduce
their file sizes, or simply move them to another server and
serve them from there.

Apache’s MaxClients limit is hard-coded at 2048 in OS X
Server. For peak traffic, you may want far more clients than
this. It is necessary to recompile Apache to make this change.
You will have to download the source code from the
href=”http://httpd.apache.org/download.cgi”>apache.org website. In the source file src/include/httpd.h,
change the line

#define HARD_SERVER_LIMIT 2048

to

#define HARD_SERVER_LIMIT 4096

Or whatever number seems appropriate. Note that the number given here is usually a factor of 2.

Then recompile according to the instructions in the INSTALL file included with the source.

Careful deployment of all of these tips should significantly improve the way the Xserve handles Web serving. If, after all of the above, your server simply can’t handle the load it’s getting, that’s when you should consider adding a second machine to share the burden.

You don’t need to be an experienced webmaster to host your own home page, website, or Web 2.0 application with Mac OS X Server. With its intuitive administrative interface, you can immediately start up a static website or deploy even the most sophisticated of sites.

Powered by Apache.

Included in Mac OS X Server is Apache, the most widely used HTTP server on the Internet. Apache is preconfigured with default settings, so deployment is as simple as starting the Web service. Any HTML content saved to the server’s default web folder will be served over the Internet automatically. Mac OS X Server offers experienced webmasters support for using either Apache 2.2 or Apache 1.3 from within the Server Admin application.

Deploy the Web 2.0.

Everything you need to develop, deploy, and host reliable Web 2.0 applications is included. Mac OS X Server ships with a full complement of server applications and frameworks including Apache 2, Ruby on Rails, Tomcat 5, and WebObjects 5.4. For hosting enterprise-class applications, Mac OS X Server includes a 64-bit Java VM optimized for the latest generation of Intel multicore processors.

Hosting multiple websites.

Support for virtual hosting in Mac OS X Server allows you host multiple websites on a single server. Using Server Admin, you can configure each website on your server to have a different domain name (using virtual domains) and even a different IP address. In addition, each website can be configured with unique security options and separate log files for tracking and reporting.

Apache Performance

Up to 50% improvement over Tiger Server^*

Leopard Server Xserve Quad Xeon

1.56x

Tiger Server Xserve Quad Xeon

Baseline

Apache performance

Be dynamic.

Apache is extremely flexible, so you can add dynamic content for a more interactive Internet solution. Dynamic content enables you to host stores, auctions, shared calendars, portal systems, polls, and other database-driven services. The robust server-side architecture in Apache supports dynamic content generated by server-side includes (SSIs), PHP, Perl, Apache modules, and custom CGIs — as well as by JavaServer Pages (JSPs) and Java Servlets.

Secure web services.

Mac OS X Server integrates OpenSSL with the Apache web server, providing support for strong 128-bit encryption and public key infrastructure (PKI) authentication using X.509 digital certificates. This high-grade security architecture protects credit card information and other confidential personal and business data transmitted during web transactions.