This is the sixth in a series of posts I’m writing about my upgrade to Mac OS X 10.2 “Jaguar”.
This posting is a continuation of yesterday’s discussion, covering the post-installation work I had to do to get my most important Unix tools working when I upgraded to Jaguar. Just to recap, here are the tasks I had to work through to get this weblog publishing system working again:
- Restore MySQL to working order
- Change the MySQL user and group IDs back to their original IDs
- Restore (or rewrite) the Startup Item that starts the MySQL data server at boot time
- Re-add the MySQL startup flag to my
/etc/hostconfigfile - Re-enable PHP in my Apache configuration file,
/etc/httpd/httpd.conf - Restore my
php.iniPHP configuration file - Restore my custom user-level Apache configuration file,
/etc/httpd/users/_username_
Yesterday covered the first four items, concerning MySQL. Today we’ll look at the last three, covering Apache and PHP issues.
Re-Enable PHP in Apache Configuration File
The web server at the heart of Mac OS X’s “Personal Web Sharing” feature is an Open Source project called Apache. To call Apache “Personal Web Sharing” is something of a misnomer; Apache is truly an industrial-strength web server, and proves it by being the number one web server on the Internet, with more than 63% market share (in August 2002). Apple has made Apache incredibly easy to use for Mac OS X users, but they’ve done it by hiding much of Apache’s power and flexibility. To really take advantage of it, especially to add new “modules” to it, you have to fiddle with Apache’s configuration file, /etc/httpd/httpd.conf.
Apache is the most popular web server, and the most popular add-in, or “module” in Apache parlance, is a powerful web scripting language called PHP. PHP is actually included with Mac OS X by default, but it’s deactivated in the Apache configuration file. PHP is the intelligence, the programming language that this weblog application is written in, so I have to have PHP activated.
Which I had done in Mac OS X 10.1, However, as part of the Archive and Install method of upgrading to Jaguar, the entire contents of the /etc directory was archived, which means the changes to my Apache configuration got deactivated.
For most of my other configuration files which were archived, I simply copied them back into place. But for the Apache httpd.conf file, first I compared my old file with the version that Apple included in Jaguar. There were enough changes, all the way through the file, that I decided I didn’t want to replace the new file. That meant I needed to re-apply the various changes I had made, primarily to activate PHP.
All of this is preamble to what is actually a very simple task, made slightly more difficult by the fact that /etc is an invisible directory, and the fact that /etc/httpd/httpd.conf is owned by root, to protect it from accidental mangling which would prevent Apache from working. Not a big deal if you have BBEdit. Dealing with permissions issues so gracefully, by making a Unix complexity into a Mac OS experience, is what makes BBEdit such a joy to use.
A friend of mine, Joe Lewis, has written instructions for activating PHP in Apache on Mac OS X. He wrote the instructions for version 10.1, but they pretty much hold true in Jaguar. His instructions are thorough and include plenty of screen shots, so my instructions here will be brief.
First I uncommented two lines, fairly early in the file. The lines I needed to uncomment originally looked like this (ellipses means lots of lines between things):
...
#LoadModule php4_module libexec/httpd/libphp4.so
...
#AddModule mod_php4.c
...
All you need to do is remove the “#” from the beginning of each line.
The second part is to add a couple lines further down in the file. I put them right after the line AddType application/x-tar .tgz, but you could just add them to the bottom of the file. I added this whole block, but only the last two lines matter:
# Enable the use of the PHP4 module (not part of the Apache
# distribution - see http://www.php.net/):
#
AddType application/x-httpd-php .html .htm .php .php3
AddType application/x-httpd-php-source .phps
Note that this will activate PHP parsing in all files that end with any of the four extensions above, which includes regular HTML files. You might not want this, but I certainly do. It lets me use the ubiquitous .html extension for all of my files, static and programmatic. This way, if I change from, say, PHP to JSP, I don’t have to rename all the files on my server.
To make the changes take effect, you need to restart Apache; the simplest way is to go to the Sharing system preference panel, and stop and start Personal Web Sharing.
Restore or Properly Set Up the php.ini Configuration File for PHP
PHP, like a great many Unix tools, has multiple ways to configure it. At the most basic level, there are defaults that are built into the software by the programmer. Then there are “flags” you can configure the software with before you compile it. These can replace the default settings the developer created. You can also “pass in” new settings, via command line options — all that extra gobbledygook you see in those long Unix commands. And then there’s the easiest way to work with normally, the configuration file.
Like Apache, PHP has a configuration file. Unlike Apache on Mac OS X, there’s no default configuration file for the version of PHP which Apple includes in Mac OS X, including Jaguar. (I would imagine the reason is mostly marketing, like the lack of MySQL in Mac OS X client; it makes the Server version more “server-like”.)
And the fact is, most people don’t need this configuration file; the defaults in PHP are all very reasonable, and you’re less likely to need to muck with it than you are with Apache. (Even when I was programming in PHP every day, I needed to fiddle with the Apache configuration file 10 times more often than the PHP configuration file on my Unix server.)
In my case, though, the way I compiled MySQL originally, the “socket” where MySQL was “listening” for connections locally (on the same machine) was different from the PHP default “socket” where PHP would try to talk to MySQL. Basically, PHP had one telephone number for MySQL, and MySQL had changed numbers to a new location. Which meant that by default they couldn’t connect to each other. My php.ini configuration file, located at /usr/lib/local/php.ini, corrected this, but it got archived. So I needed to move it back. This required administrator privileges, which made it easier to do on the command line. In Terminal (this is one line, even if it’s wrapped in your browser):
sudo cp /Previous\ Systems/Previous\ System\ 1/usr/lib/php.ini /usr/lib/php.ini
Note: You may need to change the name of the second directory to have the right number for your system archive (“1” in the example), if you’ve done the Archive and Install upgrade more than once.
You will be prompted for your Administrator password, required to perform the operation because /usr/lib is a protected directory.
If for some reason you don’t have an archived php.ini configuration file, but now need one, the normal way to get it would be to download and unarchive the entire PHP source code, and locate the one file you need. Kind of a pain in the ass. In case you’re in that situation, I’ve made available two php.ini files, with my changes applied to move the socket to the right place.
Restore User-Level Configuration Files
Every user on a Mac OS X system (like on many other Unix systems) has a special folder in their home directory. On Mac OS X, that folder is named “Sites”, and everything in it is served up at the URL http://your-server-name/~username/, where “username” is the short login for the user (you can also use http://localhost/~username/ as a shortcut to your server, if your web browser and web server are on the same machine). This is each user’s personal web site (Personal Web Sharing needs to be turned on for anyone to see it).
Mac OS X is set up, out of the box, to allow each user to tweak the behavior of Apache when serving their own site. The very last line of the Mac OS X Apache configuration file does something kind of magic. It’s an “include” command, which is able to read in other files, and Apache treats the commands in those files as if they were in the Apache configuration file itself. But what’s particularly interesting about the command, in the Mac OS X version of the file, is it includes a whole directory. This will read in any and every file in that directory.
The purpose of this is to give each user on the Mac OS X system a mechanism for altering the behavior of Apache when sharing their part of the web site. Each user writes a few Apache configuration commands, and saves them in a file in /etc/httpd/users. Apache reads them in and uses them.
Most people don’t need to do this. It’s far-out enough to be editing the main Apache configuration file! However, for my weblog I needed to change the way Apache treated files slightly, to make the URLs to my blog prettier (and, not coincidentally, more search engine-friendly). But I didn’t want to change the behavior everywhere, just for my site. So I had my custom configuration file, /etc/httpd/users/_username_, which gave Apache the necessary instructions.
You guessed it, another item that got archived during my upgrade. Once again, the command line is the easiest way to fix this. In Terminal (this is one line, even if wrapped in your browser):
sudo cp /Previous\ Systems/Previous\ System\ 1/etc/httpd/users/_username_ /etc/httpd/users
Note: You will need to use your actual username in the command, not the string _username_. You may also need to change the name of the second directory to have the right number for your system archive (“1” in the example), if you’ve done the Archive and Install upgrade more than once.
You will be prompted for your Administrator password, required to perform the operation, because /usr/lib is a protected directory.
Wow, that’s a lot of ground in the last couple days! Tomorrow I’ll write up a few last odds and ends about my upgrade process, and do some wrap up.