Installing Postfix and UW IMAP on Mac OS X Server 10.2

—David O’Donnell, atropos@afp548.com

Updated 25 January 2003

10.2 OK!

Postfix + UW IMAP

We tested a fresh installation of Postfix 1.1.11 with Mac OS X 10.2 (with the latest Developer Tools and BSD SDK) on 5 September 2002 and found no problems installing or running the software.

2003-01-25 Update: Postfix 2.0.0.2 builds seamlessly under Mac OS X 10.2.3 using the ‘make upgrade’ command. Also, the University of Washington have updated their Pine distro to 4.53; this version builds seamlessly under Mac OS X Server 10.2.3 with the ‘build osx’ command, and also includes SSL support. LDAP support is listed, but untested as of this writing.

NOTE: If you have problems using the 4.53 IMAPd and have SSL certificates, rebuild the software without SSL support by executing build clean; build NOSSL osx.

NOTE: Mac OS X Server 10.3 ships with Postfix pre-installed. Do not follow these directions if you have Mac OS X Server 10.3!

The Postfix mail transport agent (MTA) is a powerful, easily configured mail transport agent. It replaces the supplied Sendmail 8.x and Apple Mail Service MTAs that ship with Mac OS X Server. In this article, you will replace all aspects of Apple’s Mail Server with Postfix 1.1.1, and the University of Washington’s IMAP server.

In order to install Postfix, you will need root access. Your Mac OS X Server machine should have the latest build updates (Server and Client 10.1.2 as of this writing) and current Developer Tools (December 2001 as of this writing) installed. In most cases, you will be compiling and installing Postfix while logged in at the server ("at the console"); nevertheless, for greatest continuity, the user and group creation processes are described using command line tools. You will also need access to the Server Admin application, either locally or remotely. You will need to use a version of Server Admin that is version-compatible with the release of Mac OS X Server on which you plan to install Postfix.

I recommend obtaining a copy of Postfix, by Richard Blum, (ISBN 0-672-32114-9) for future configuration and/or extension of the MTA. While the version of Postfix covered in the book is out of date in some ways, it has an excellent introduction to mail service (SMTP) and helps flesh out the somewhat anemic documentation shipping with Postfix.

Conventions for this document:

$HOME

Your home directory, which is normally /Users/your-short-name; for example, if your ‘short name’ login is ‘jdoe’ your home directory will be /Users/jdoe.

$VERSION

Replaced with the actual version number of the referenced software. For example, as of February 2002, the current stable release of Postfix is version 1.1.1, so $VERSION is ‘1.1.1’.

text like this

This text represents command line text—commands you should enter, or the names of important files.

$DATE

The current date, in a format that is familiar to you. For example, if today is 12 February 2002, $DATE could be 12022002.

Follow these steps to install Postfix:

  1. Login to an account with administrator access. If you choose to login as ‘root', you can omit all references to ‘sudo’ later on in these instructions.
  2. Launch the Terminal (/Applications/Utilities/Terminal.app).
  3. Create a directory in which to store source files, such as $HOME/src.
  4. Change to your source files directory.
  5. Obtain the latest stable build of the Postfix source from ftp.cis.fed.gov/pub/postfix/official. The current release is postfix-1.1.1.tar.gz.
  6. Run gunzip and tar xvf on the source tarball.
  7. Change to the postfix-$VERSION/auxiliary/Mac OSX/ directory (postfix-1.1.1/auxiliary/Mac OSX/ in this release)
  8. Execute the niscript shell script with sudo ./niscript. This script creates a Postfix user and group using user and group IDs that are not already present in your system.
  9. Create the postdrop group:
    1. sudo niutil -create / /groups/postdrop
    2. sudo niutil -createprop / /groups/postdrop name postdrop
    3. sudo niutil -createprop / /groups/postdrop gid 54321
      Note: I’ve chosen ‘54321’ for convenience. You should choose a group ID that does not exist on your system.
    4. sudo niutil -createprop / /groups/postdrop passwd ‘*'
      Note: Postfix’ documentation states that a postdrop group containing no members is now required for proper execution of the MTA. The Mac OS X build process does not actually make use of that group, but another memberless one; nevertheless, in the event the group is silently used internally, or will be used by a future Mac OS X setup, we will still create it here.
  10. Create backups of the existing Sendmail binaries by executing the sudo ./backup-sendmail-binaries script.
  11. Change to the Postfix source root and execute sudo make.
  12. Change to the superuser for the next few steps—it will be much easier than prefixing everything with ‘sudo'.
  13. Run make install. When prompted, answer the “Install_root” question with slash ("/") and the “Readme_directory” question with “/etc/postfix". The default suggestions are otherwise fine.
  14. Change to the /etc/postfix directory.
  15. Copy the main.cf file to main.cf.$DATE to preserve the initial installation defaults and comments.
  16. Edit the main.cf file. Any of the command line editors (emacs, vi, pico, etc.) is recommended over, e.g., TextEdit or BBEdit.
    1. Find the section, “INTERNET HOST AND DOMAIN NAMES"
    2. Uncomment one of the #myhostname lines and set it to: myhostname = your-fqdn (For example, if your computer’s hostname is ‘myserver.foo.net', you would use myhostname = myserver.foo.net. Use the command echo $host to see what Mac OS X Server thinks your hostname is.)
    3. Uncomment the #mydomain line and set it to: mydomain = your-domain (Using the example above, your-domain would be ‘foo.net')
    4. Find the section “SENDING MAIL"
    5. Uncomment one of the #myorigin lines and set it to: myorigin = $myhostname
      Note: If your machine is going to be the primary mail server for a domain, you should use myorigin = $mydomain instead.
    6. Find the section “RECEIVING MAIL"
    7. Uncomment one of the #mydestination lines and set it to: mydestination = $myhostname
    8. Find the section “TRUST AND RELAY CONTROL"
    9. Uncomment one of the #mynetworks lines and set it to: mynetworks = my_cidr_list
      Note: my_cidr_list is a comma-separated list of host/CIDR-mask entities. If you don’t know your CIDR value, check out the utility “whatmask". The host/CIDR-mask entity is in the format IP_ADDRESS/CIDR. It is common to include the entity 127.0.0.1/24 as the last entity, to ensure localhost can relay and originate e-mail.
    10. Find the section “ALIAS DATABASE"
    11. Uncomment one of the #alias_maps lines and set it to: alias_maps = hash:/etc/postfix/aliases, netinfo:/aliases
      Note: Notice that Postfix understands NetInfo’s aliases format as well as many other database formats.
    12. Uncomment one of the #alias_database lines and set it to: alias_database = hash:/etc/postfix/aliases
    13. Find the section “DELIVER TO MAILBOX"
    14. Uncomment the #mail_spool_directory = /var/mail line.
    15. Uncomment the #mailbox_command line and set it to: mailbox_command = /usr/bin/procmail if you want to make use of Procmail, a powerful e-mail filtering and management tool.
      Note that if you choose to use procmail, you should make certain that your /var/mail permissions are correct (sudo chmod 1777 /var/mail)
    16. Note: I have not edited any of the JUNK MAIL CONTROLS settings. These are covered in greater detail in another article.
    17. Find the section “SHOW SOFTWARE VERSION OR NOT"
    18. Uncomment one of the #smtpd_banner lines and set it to: smtpd_banner = $myhostname ESMTP $mail_name ($mail_version) [NO UCE, NO UBE, C=your_country_code, L=your_local_code]
      Note: your_country_code and your_local_code are two-letter abbreviations corresponding to your nation and local (state, province, etc.) area. In the USA, the country code is US and the local code is the two-letter state abbreviation.
    19. Save the edited file.
  17. Drop back to normal user access.
  18. Change back to the postfix-$VERSION/auxiliary/Mac OSX/ directory (postfix-1.1.1/auxiliary/Mac OSX/ in this release)
  19. As super-user, edit the file “defines” and change the instances of /System/Library to /Library. This will reset the location of the Postfix item to the non-Apple-supplied StartupItems location.
  20. Back up the Postfix binary files by executing sudo ./backup-postfix-binaries.
  21. Enable Postfix as the MTA by executing sudo ./activate-postfix.
  22. As super-user, edit the /etc/hostconfig file and make sure that MAILSERVER is set to -YES- (e.g., MAILSERVER=-YES- should be how the line appears)
  23. Execute the command sudo newaliases (omit the sudo if you are still super-user) to build your aliases database file.
  24. Reboot the machine.
  25. Test that Postfix is running by executing telnet localhost smtp. Use the quit command to close the telnet session.

Now that Postfix is running as the MTA, we’ll install the University of Washington’s IMAP server. We’ll also install their POP3 server and Pine, a top-notch character-mode e-mail client. U-Washington packages IMAP, POP3, Pine and Pico (another text editor; Mac OS X ships with version 2.3 installed) together.

  1. Obtain the U-Washington package from this link: ftp://ftp.cac.washington.edu/pine/pine.tar.Z (from the command line, type: curl -O ftp://ftp.cac.washington.edu/pine/pine.tar.Z). The current version as of 12 February 2002 is Pine 4.44.
  2. Put the package in your source directory. StuffIt Expander may have expanded the tarball already; discard the folder it created, it so. There have been reports of StuffIt products not properly working with tarballs, so we’ll stick with the Unix commands instead.
  3. Uncompress the pine.tar.Z file with uncompress pine.tar.Z
  4. Run tar xvf on the tarball to expand its contents.
  5. Change to the expanded pine$VERSION directory (pine4.44/ in the current release)
  6. Run the command sudo ./build NOSSL osx
    Note: If you have already configured SSL certificates on your Server, omit ‘NOSSL’ from above.
  7. When the compilations is complete, you will have binaries for Pine, Pico, IMAPd, POP3d, POP2d and mtest:
    Links to executables are in bin directory:
    __TEXT __DATA __OBJC others dec hex
    3485696 258048 0 2670592 6414336 61e000 bin/pine
    643072 12288 0 724992 1380352 151000 bin/mtest
    679936 20480 0 761856 1462272 165000 bin/imapd
    245760 12288 0 319488 577536 8d000 bin/pico
    245760 12288 0 319488 577536 8d000 bin/pilot
    size: can’t open file: bin/rpdump (No such file or directory)
    size: can’t open file: bin/rpload (No such file or directory)
    638976 12288 0 724992 1376256 150000 bin/ipop2d
    647168 12288 0 729088 1388544 153000 bin/ipop3d
  8. Move the appropriate binaries into their final destination. We’ll put them in /usr/local/bin, which is a fairly standard location. You may have to create /usr/local/bin prior to issuing the mv commands:
    mv pi* /usr/local/bin
    mv ip* /usr/local/bin
    mv imapd /usr/local/bin
    Note: We’re not moving mtest; its only use is to ensure that the daemons work, and needn’t be installed anywhere for it to function.

Now we need to make sure Mac OS X Server knows where to find the daemons. First, use the Server Admin program to disable the Server’s extant Mail Services. Do this by logging into your server via Server Admin and clicking the Internet tab. Select the Mail Service icon, and select the Configure Mail Service menu item. Click the Protocols tab and select “None” in the Use [ ... ] for message transfer drop-down. Close the window. Click the Mail Service icon and select Stop Mail Service.

After disabling Apple’s Mail Service item, we need to enable the new daemons. To do this, edit /etc/inetd.conf as super-user. Find the lines referencing pop3 and imap4 and replace them with the following:

# 
# Enabling UW IMAPd and POP3d 
# 
pop3 stream tcp nowait root /usr/local/bin/ipop3d ipop3d 
imap4 stream tcp nowait root /usr/local/bin/imapd imapd

Also, make sure that the pop3 and imap lines in your /etc/services file are uncommented. Reboot the machine to restart inetd (kill -HUP on inetd’s process ID does not seem to work properly). Test to make sure IMAPd is running by executing telnet localhost imap. You should see output similar to the following:

Trying 127.0.0.1... 
Connected to localhost. 
Escape character is ‘^]'. 
* OK [CAPABILITY IMAP4REV1 LOGIN-REFERRALS AUTH=LOGIN] localhost IMAP4rev1 2001.313 at Wed, 13 Feb 2002 12:07:00 -0500 (EST)

Quit the telnet session by typing 001 logout and hitting Return.

You are all set to send and receive e-mail using Postfix, and retrieve it from your server using e-mail clients that support IMAP or POP3.