Note: This guide is targeted at OS X Snow Leopard Server, not Lion nor Mountain Lion. Lion setup is quite different, and the Server Admin has been (mostly) superseded by Server.app which provides far less features. I would not recommend upgrading to Lion unless you need the new features or is setting up a new server. The reason I am not upgrading yet is that the web-server administration in Lion is too simplistic for my needs and that MySQL has been replaced by PostgreSQL, so if I upgraded I’d have to set up and manage everything manually, essentially providing the same inferior user experience as Linux for me.
A couple days ago I wrote about how I set up my Mac Mini Server, or, that is, I really only wrote about how I set up the hardware. In this post I’ll describe how I have set up the software.
I use the server for several purposes. For some purposes a dedicated may seem a bit like overkill (especially since I also have a Time Capsule, which is able to do basic network configuration and file serving), but for some purposes a dedicated server is necessary. Basically, I used my old server to act as
- DHCP server,
- DNS server,
- Mail server,
- database (MySQL) server,
- subversion server, and
In addition to these, it turned out to be so simple to set up, I also use the new server as
- directory server,
- address book server,
- calendar (iCal) server, and
- VPN end-point.
Let’s take these in the order I set them up.
Server Admin and Workgroup Manager
For the setup we are going to use (mostly) Server Admin and the Workgroup Manager from the Server Administration Tools. These can run directly on the server or from a remote machine. I’m going to do the latter as I have hooked my computer up to an ancient 15″ CRT monitor, which makes an annoying sound when it is turned on.
When you start up the Server Admin, you get a picture like the one to the right (click for larger version). We basically have an overview of servers (to the left) and a bunch of things we can do the currently selected server or service (along the top) and a pane to actually set the things (right area). Right now, I have selected the server, and get a view of generic information about the hardware, software, and enabled services. At the bottom I get a couple of graphs showing the load of the server in the last 24 hours (configurable), both the CPU load, the network traffic (it has a 1 Gbps network adapter) and the amount of free disk.
Let’s first set up the services, we wish – we go to the Settings pane and select Services (below). We can now simply check the services we want. Some will already be selected depending on which task you select for your server during installation/first boot of the server). We select the desired services as well as AFS (file server, so it is easier to move files to the server) and Xgrid (so I can experiment with grids). Windows users may also want to switch on SMB (Windows file serving).
Address Book and Calendar
The first order of business is Address Book and Calendar. Mostly because I got these without setting anything up myself. All I did was removing any quota (as I only will be using this myself) and setting both up to use encrypted connections.
Next up is the Mail server. This was also mostly set up automatically, and I only had to tweak a few options. I disabled SMTP (as I just use my ISP’s mail server), Junk mail filtering (I use client-side filtering), and quotas. Furthermore I set it up to only use IMAP (nobody uses POP anymore) and allow connections using SSL (by setting a certificate).
A really neat feature is that you can monitor the connections to the server by selecting Connections at the top. On my server, currently two clients have connected:
Now that a couple of basic services are set up, let us start the Workgroup Manager and create a group and a user. First, we create the group. You probably need to log in as diradmin instead of using your normal administrator username to access the Workgroup Manager, so just start it up and log in. Simply click New Group (top middle) in the Workgroup Manager. You then get a fresh group that you can just fill in:
Now, we have a group, and want to add a member. This is the same procedure; select the users tab and click New User and fill in any required details. I also add the user to the newly created group and set up mail.
Interlude: Server Preferences
Now we have set up a bunch of services, and I think I should also mention the Server Preferences tool, which is an easier overview to the simple settings. Below, you can see the Server Preferences overview, settings for Address Book (they are nearly the same for iCal), settings for Mail and various panels for setting up groups and users:
I decided to set up the “real” services bottom up, so that the most essential services were migrated first. This also happens to be in order of increasing complexity. My DHCP server basically serves IP-addresses to unregistered computers from the network 10.0.100.0/16 and static addresses from 10.0.0.0/16 – 10.0.4.0/16 (depending on the type: 10.0.0.0 being servers, 10.0.1.0 my clients, 10.0.2.0 other clients, 10.0.3.0 mobile units, and 10.0.4.0 work computers).
First, setting up the subnets from which to hand out addresses is really easy; go to DHCP and Subnets and click on the plus. Then fill in information about the subnet (as well as you gateway to the internet), and switch to the DNS tab to set the DNS server. The picture shows the Mac Mini as DNS server, but during setup this was set to my old server and later changed once DNS was moved. LDAP settings were ok and I don’t have any Windows machines, and therefore does not care about WINS. The domain option of the DNS tab is for allowing machines to access each other as just coherent rather than coherent.westergaard.eu.
Then comes the static maps. There is the easy and the cumbersome way to do this. I went with the cumbersome way, as I wasn’t aware of the easy one until after the fact. The cumbersome way is to go to Static Maps and click Add Computer near the bottom and input the MAC address and the desired IP address.
The easy way involves going to the Clients tab, where you’ll see all machines assigned a dynamic IP address. Simply click on a host and select Create Static Map near the bottom and, bam, it is created automatically.
Setting up the DNS server is also easy, though a bit annoying for large registrations. My DNS server only resolves a few internal domains and delegates the rest. It also inly serves as internal DNS server, so I allow zone transfers, which probably shouldn’t be allowed on a server facing the internet. To create a zone, go to DNS, Zones and click add zone. You then select whether to create a primary or secondary zone from the drop down. I only have primary zones. You just need to set the name, administrator, name-servers, and MX records.
I don’t really care too much about expiration of the zone as it is internal. Next up is adding machines to the zone. Select the zone and click Add Record and select Add Machine from the Dropdown. You can associate one or more IP addresses with each machine. Also, the name can be relative (to the zone) or fully qualified, which is needed to give an address to the domain represented by the zone itself (so people can go to westergaard.eu instead of typing all of www.westergaard.eu). Unfortunately there seems to be no data sharing between the DHCP and DNS server setup, so as soon as you want to change one, you are guaranteed to forget the other.
Finally, we need to add some Aliases. I usually give my machines meaningful names (to me, they’re chosen from concepts of category theory) and create aliases for services. In this case, my web-server (www) is hosted on coherent, and my subversion server is hosted on the same as the rest of my web-server. This is very useful for migrating services.
Next up is the reverse mapping creation, or, not really, because the tool automatically creates these. If multiple names map to a single IP, you may need to select the correct one, however.
The default settings for forwarding are reasonable (accept recursive lookups from local machines, forward to the root server). I suppose you could add your ISP to the list of forwarder addresses.
Database (MySQL) Server
Next up is the database server. OS X ships with MySQL and as I have been using that until now, this was an easy choice. The actual setup was easy – as soon as it is switched on in Services and started, it is running. The only setup I has to do was setting it up to allow network connections:
The rest is just loading the data and using the new server. This was also the problem, since all the users of the database (PHP scripts) had been hardcoded to use localhost, which, of course, is a problem when that is no longer true.
I set up a mapping for mysql.westergaard.eu. Then I modified MySQL’s settings to allow connections from % (connecting to localhost and connecting to mysql.westergaard.eu is not the same even if they are the same machine, as it is possible to use Unix pipes in the first case, whereas TCP needs to be used in the second). Then I went thru all my PHP-scripts and changed them to use the new name. Testing that all still ran.
Next up is the migration of data. Here mysqldump is your friend. It dumps an entire database into SQL code that can be loaded, at least, on another MySQL server. Most likely also on other servers as long as it is not too complex. I used the program Stor (left) to see which databases to dump (as I got it cheaply from ). Stor also comes with a dump mechanism, but it doesn’t seem to work very well, so I don’t recommend using it yet. As I had been running the database in 8-9 years, it did contain some stale data, and this was a nice opportunity to clean up a bit (only migrating 11 of 31 databases and cleaning up a couple gigabytes of cache stored in some of the remaining databases).
Of course, the layout of the permissions table had changed slightly, so a bit of MacVim regular expressions were needed before being able to load the user and db tables into the mysql database, but after that (and a quick DNS update), the database was migrated.
Next up was the last major task, the web-server. It hosts quite a few domains and uses some rather weird settings. This is due to the fact that my old server has been running using a configuration file that has slowly evolved over 11 or so years. Basically, new things have been added and old things have just been allowed to survive, while redirects have been added to direct people to new or old stuff appropriately. Also, the server hosts around 10 domains (or used to, at least). Let’s first look at the generic server settings.
I need to set up the server to handle .php3 files as PHP scripts as, when I started , this was how you named PHP scripts. Then a couple years later, PHP4 emerged making the trend a bit old-fashioned. I do this by adding a content handler under Web, Settings, MIME Types (right).
Next up is configuration of modules. It is imperative that you do not disable the HTTP proxy modules, as the server depends on these and fails miserably if you do. Basically, only turn things on unless you know what you do and are prepared to handle a few misfits with the server.
Now we want to configure our sites. See, this is fun. “Kick-me-in-the-groin and call me Hitler” kind of fun. The configurator works most of the time for most of the things you’d want. But it has bugs and some times fails miserably. Let’s go thru the things that work first and mention some pitfalls when they are relevant. I’ll mention some troubleshooting tools after going thru the basic setup.
Co to Sites. An old default site mat already exist. We don’t need that so just delete that by clicking on the minus. Then click on the plus to create a new site. If you’ll host more than one site, you need to enter a meaningful Host Name, otherwise default will do. Choose where you put your files (Web Folder). Most of the General settings should be fine. Not that the Error Document is crucially important and so is the Document Root. The server will silently fail unless you set them. Fun, huh?
Next up is the Options. Chances are you need to tweak these. Folder Listing is generally a bad idea (unless you also want WebDAV, which you wont unless you know what it is or use FrontPage). CGI and SSI you’ll not need. If you do, you’re doing something wrong. Allow All Overrides should most likely not be turned on, unless you happen to use WordPress, which relies on this setting. My settings are:
Let’s ship Realms and go to Logging. I’ve enabled both error and access logs. The error log is needed for error-finding (duh 😉 ) and the access log is neat for generating visitor statistics, e.g., using Awstats. I keep my access log forever (have done so for years) and archive the error log every 7 days (if I don’t discover a problem before, it’s not worth going thru old logs for).
Next we can enable SSL. You’ll need to make a copy of your web-site for this (in the Server Admin, not the files), so we won’t do this now. You can use the two windows-thingy next to the minus to clone a site configuration.
Next up is the bix bag of hurt, the Aliases settings (below, left). They are used to assign more than one name to a server, to integrate another namespace into your server and to direct users to other servers. The web-server aliases can contain alternate names. To improve your ranking for search machines, I suggest not adding anything here (I’ll show later how to do instead). Server Admin may, however, insist on adding an alias *, which matches everything, causing all below servers to not work. Nice, huh?
Aliases allow you to share files between sites. Server Admin automatically inserts 3 aliases, collaboration, icons, and error. I haven’t investigated what collaboration does, but icons contains file type icons used for directory listings and error contains error documents, and do no harm.
Next comes a bunch of custom redirects, which directs old liks to appropriate new or old pages. I prefer RedirectMatch as it allows me to use regular expressions. I basically write the old URL and the new URL. For simple examples, refer to the screenshot to the left, for some more intricate rules, see below:
I don’t use the proxy settings, so I won’t go thru them, but the web-services are interesting. They allow you to set up some basic services on your web-site, sich as wikis, blogs, a web-calendar and a web-mail. Simply tick the one you want, and click the little arrow to have the tool take you directly to your new service.
Troubleshooting the Web Server
I have mentioned a couple problems (on the general tab and the aliases tab). These I encountered problems with myself, and it was great fun. The reason is that the web-server doesn’t notice this. As soon as you click save, the web-server is automatically restarted. You can also manually restart the web-server by clicking on Stop Web near the bottom left and then Start Web, which appears in the same place. all may seem fine, but your server will not necessarily respond because Server Admin has generated code that Apache (the web-server included) will not accept.
I suggest that after making a change to your web-configuration, you go to a command line on your server (the easier way to do this is to click on the gear near the bottom left and choose Share Server’s Screen. Then open a terminal (from Applications, Utillities) and type apachectl -t like this:
coherent:wp-content admin$ apachectl -t Syntax OK coherent:wp-content admin$
If there is a problem, you may be able to figure out what causes it by examining the output of apachectl.
It may also be interesting to know that the PHP settings hide errors rather than showing them (which surprised me, as I’ve always had it report the errors) and it has turned off short tags, causing some PHP code to break (that one was fun debugging without any error reports 😉 ). If you want to change it, look at /etc/php.ini, in particular the settings display_errors, error_reporting, and short_open_tag.
More Advanced Web Server topics
If your site is known using multiple names, it is wise to collect them under a single name, as all links will be counted as going to the same site by search engines. Therefore all the other names should redirect to this name rather than just serving up pages. For this, I create a separate site with no enabled services:
The idea is to make the Aliases take care of everything for us, so we add web server aliases for all possible names for the server. We can use wildcards (*) as desired. We then add a RedirectMatch rule forwarding any page to the corresponding page to on the primary name. that way, hello.world.klafbang.eu/2009/11/setting-up-mac-mini-server-for-basic-operation/ is directed to westergaard.eu/2009/11/setting-up-mac-mini-server-for-basic-operation/. In my setup, I spell out all alternate names for ny server and add a wildcard domain at the end directing everything. This is just to allow me to easily move the wildcard domain to another site if needed, as the other names will still work.
For setting up Subversion, I used this (archived) guide as starting point. Is basically says enable all modules with svn in their names and create a site with a realm for your subversion repository.
Unfortunately, subversion does not play nice with the redirection rules of WordPress, so I instead set up a blank site, svn, for this. I added redirects from the old server to the new server for /phd, /subversion, and /kurser (the three last redirects above before troubleshooting). The settings are like for the alias site just above, except we enable WebDAV (right), and fiddle with the realms. The guide proposes adding a realm for your subversion repository. Unfortunately my setup is a bit more complicated, and I have more repositories and slightly more involved settings. Rather that mucking about with that, I created three Realms:
Then I save the configuration – I don’t bother with setting users/groups (you may want to add the users to have an example to go by). Then you manually need to edit your site configuration in /etc/apache2/sites. The name depends on the order you created your sites, but contains the name of the site and should be recognizable – mine’s called 0008_any_80_svn.westergaard.eu.conf. Modify the <Location …> section(s) created. I have modified my /phd location to:
<Location "/phd"> AuthType Digest DAV svn SVNPath /Library/WebServer/Subversion/phd/ <LimitExcept GET OPTIONS PROPFIND REPORT> Require user michael michael@COHERENT.WESTERGAARD.EU </LimitExcept> AuthName "westergaard.eu phd svn" Order allow,deny Allow from all </Location> <Location "/phd/trunk/review"> Require user michael michael@COHERENT.WESTERGAARD.EU Order allow,deny Allow from all </Location> <Location "/phd/trunk/old"> Require user michael michael@COHERENT.WESTERGAARD.EU Order allow,deny Allow from all </Location>
I have added DAV svn (Server Admin is going to change that to DAV Off every time you make a change, so you’ll need to change that manually each time – fun) and SVNPath. I have put my Subversion repositories in /Library/WebServer/Subversion, next to the web-sites, but you are free to put them where you want, I guess. There was a >Limit …> directive, which I replaced by LimitExcept. This construction allows everybody to read my repository without a password. Adding the Order and Allow seemed to be neeccesary as well for me. The two additional <Location …> sections requires a password even for reading the specified locations (not everybody should be able to read my reviews or old stuff).
This concludes my brief overview of setting up a Mac Mini Server for basic operation. I have gone thru most basic setting many will need and some settings few will need. I have not gone thru my VPN and Xgrid settings as they are quite specialized and I have not even started using either yet, so I don’t know if they are set up correctly. The server is also able to act as a firewall and as a Time Machine backup server, but I don’t have use for that (I have devices for both of these), so I haven’t investigated too thoroughly.
In conclusion, I can say that the Mac Mini Server is quite nice and fast for the price, and additionally it’s quite and uses relatively little power (110 W). Also, It’s fairly cool that I’m able to transfer files from the server to my iMac at 40-50 MB/s 🙂
Edit: If you came here looking for information on setting up a VPN end-point or a file server, I’ve written a post on that as well.
Time person of the year 2006, Nobel Peace Prize winner 2012.