Tiny Deathstars of Foulness

I don’t believe in upgrading major operating systems for servers in place. There, I said it. If I’m doing an upgrade from Snow Leopard to Lion, I’m about 99.9% of the time going to do so with a clean install. Before I do so, I’m going to export all the data from my old server and when I’m done with the fresh, clean, loving installation, I’m going to import that data back into my server. Actually, before I import the data, I’m going to install all of the point releases, application updates and security patches. That’s my process for production servers. Open Directory isn’t very different. I Archive and Restore servers as often as I reinstall, upgrade or even downgrade Open Directory Masters. I treat Replicas differently: mostly in that I don’t treat them at all. Instead I clean install them and just re-promote them once my Master is back in place. If I have any schema extensions or other mods I’ll just sync those myself prior to promotion. I trust my process, it’s worked for me for more years than I care to admit. Before You Upgrade Archiving Open Directory data is a pretty straight forward process. Open Server Admin from /Applications/Server and then click on the Open Directory service. From here, Click on the Choose… button for Archive in: and select a location to store the Open Directory data. Then, click Archive and provide a password. Pretty easy so far. Now, check your Kerberos Realm, IP address and hostname on the server. For the IP address, you can take screen shots of the Network System Preference pane, or pipe the output of ifconfig to a text file. For the hostname, I don’t trust the GUI of OS X (no offense to the excellent UX developers employed at Apple). Therefore, use scutil for the names. Also, we’ll want that Kerberos information. I usually just grab that from my Server Admin Open Directory screen. Finally, we’re also going to get the OD policies using slapconfig again. In sequence, these commands would be: ifconfig > ~/Desktop/mytextfile scutil --get HostName >> ~/Desktop/mytextfile scutil --get ComputerName >> ~/Desktop/mytextfile scutil --get LocalHostName >> ~/Desktop/mytextfile sudo slapconfig -getmasterconfig >> ~/Desktop/mytextfile sudo slapconfig -getmacosxodpolicy >> ~/Desktop/mytextfile Also, backup any certificates, custom service principals you may have installed or other service data or data data that is needed on the host, if any. Installation Once you’ve got all of the important stuff backed up and know what you’re going to call the server moving forward, it’s time to install the operating system. If the server came with a Lion operating system pre-installed, skip this part. Use a Lion computer to create a recovery partition using the Recovery Disk Assistant. Once you have a valid recovery partition (on a thumb drive for now), boot to it on the server you are upgrading and wipe the system through Disk Utility. This step is probably pretty scary. And it should be. Make sure all your data is backed up before you do it. By the way, if you haven’t copied the mytextfile then think long and hard about whether there’s anything else missing before you start the reformat process on that drive (I seem to have to learn all of my lessons the hard way)… I also like to have a clone of the system as a back-out plan, just in case there are any problems with the upgrade. It adds a little latency but I’ve had to revert a few times with these upgrades, and having that clone sure beats pulling an all nighter… Once wiped, Choose the Reinstall Lion option and install the operating system. Then install all available patches (10.7.3 or higher is very, very important, btw). Once installed, use the App Store to buy Lion Server and install it, but don’t open it just yet. Remember those commands from earlier. When possible, Open Directory upgrades the smoothest when the IP address and host name are the same. Therefore, look at your mytextfile. Setup the IP information the same as it was, verifying against ifconfig and then use the first host name from the scutil output to configure the HostName (using as my example): sudo scutil --set HostName Then the second host name: sudo scutil --set ComputerName And finally, the third: sudo scutil --set LocalHostName mdm Now check changeip: sudo changeip -checkhostname If it gives you the all clear, you’re ready to proceed. Next, download the Server Admin tools from Apple at Provided that the installation is good, the host names match up in scutil and the IP address is the same as it was, open the Server app for the first time (from /Applications). The server will install the various components that complete the installation. Once installed, click on the Next Steps drawer and verify that the host name is good. If it is, you should see a message similar to the one below. Promotion Now promote your server. It’s going to be tempting to use Server Admin or slapconfig. If you use slapconfig you will regret it unless you use the new options supplied by Apple. Why? Because the Server app gracefully creates SSL certificates used in directory services binding; certificates that are not created with the old style slapconfig commands. Given that I’ve not seen complete documentation for slapconfig (many of the options required for correct scripted promotion in Lion aren’t actually in the man page), I’d just use the GUI for now (and if you don’t like using a GUI, then I challenge you to build OpenLDAP, Kerberos and all the other components setup by the Server app from source – that might cure the CLI snobbiness we all have from time to time). Also, be careful with how you promote/demote – this article outlines some reasons not to use slapconfig -destroyldapserver any more. From the Server app, click on Users in the Server sidebar. Here, you’ll notice that all of the accounts that are listed are black busts of users. Groups are similar. So far, all users created are automatically local users. If that’s not what you want, remove any of those accounts prior to continuing. Click on Manage Network Accounts… to bring up the Configure Network Users and Groups wizard. Click Next at the introductory screen. Then provide the Directory Administrator information (e.g. diradmin with a password of diradmin for the security conscious) and click on Next. At the Organization Information enter the information you want on the SSL certificate that is automatically generated for Open Directory. This includes the Organization Name and Admin Email address (this might not be enough information for some SSL providers, but it’s a good start) and click on Next. At the Confirm Settings screen, verify your information is as intended and then click on Set Up. The Open Directory Master is created. Once created, all new users will have the same icon as the local users, with the exception of a globe to indicate they are network accounts. Now check your logs to make sure everything installed smoothly. Importing Users, Groups and Computers Provided that the host name and IP address are the same on your server, importing the data back into Open Directory couldn’t be easier. Open Server Admin and then click on Open Directory and then on Archive in the top icon bar. Here, click on Choose and browse to the dmg you created when backing up the server. Click Restore and enter the password previously supplied. You can also import users from within the Server app. Now that your users are back, it’s time to make sure they’re a member of the groups that provide access to services. These are hidden by default, so in the Server app, use the Show System Accounts option under the View menu or if you’d rather use Workgroup Manager use Show System Records under the View menu to see the groups. Each service has a different group name. For example, Profile Manager is the Profile Manager ACL (or for the short name) group. Add each user into the group that needs access to these services, click Save and you’re ready to bind some clients! Binding Clients Binding clients can be done in a few different ways. You can use a script, a Profile, the Users & Groups System Preference pane or build binding into the imaging process. For the purpose of this example, we’ll use the System Preference pane. To get started, open up the System Preference pane and then click on Users & Groups. From here, click on Login Options and then unlock the lock in the lower left corner of the screen, providing a username and password when prompted. Click on the Edit… button and then the plus sign (“+”). Then, enter the name of the Open Directory Master (the field will expand with options when you enter the host name. It’s probably best not to use the IP address at this point as the master will have an SSL certificate tied to the name. Click OK to accept the certificate (if it’s self-signed) and then the system should finish binding. Once bound, I like to use either id or dscl to verify that directory accounts are properly resolving before I try logging in as an Open Directory user. Provided everything works that’s it. The devil is of course in the details. Good luck!

February 15th, 2012

Posted In: Mac OS X, Mac OS X Server, Mac Security, Mass Deployment

Tags: , , , , , , ,

  • Michael

    > I also like to have a clone of the system as a back-out plan, just in case there are any problems with the upgrade.

    Even better: Pull out the hard drive with the old install on it and replace it with a new one. Label the old one and store it somewhere safe. If anything goes wrong during the fresh install, you can go back within minutes — plus you don’t have to worry about whether you really backed up everything or whether the clone process really was 100% successful. After a few weeks/months of everything working fine and nobody complaining about missing stuff, you can then wipe the old hard drive and use it for doing a fresh install on a different server.

  • In your first set of commands you used a ‘>’ (write-overwrite) rather than a ‘>>’ (write-append) pipeline. Just thought I’d point it out.

    Thanks for the post anyway 😀

  • Shawn

    Thanks for the info. This should go along way toward planning for the future. I am wondering though at what point do we walk away from OD and look at OpenLdap, kerberos etc separately from OSX. I know you made the comment about building it from scratch. There has been a couple people out there trying to make a pure open source alternative to OD and yet still have the compatibility for binding OSX clients.

    • If you have an existing configuration, I wouldn’t walk away from OD unless it’s announced that it’s going away or you outgrow the solution. But that’s just me…

      Now if a good open source alternative that basically spoofs OD and adds the schema extensions in there were to arise then I might change my tune, but I’ve not yet seen a good, solid deployment worth looking into.

  • Pingback: Moving Managed Preferences to Profiles |

  • Followed to the letter. Only before promoting, had to enable DNS and create the DNS zone and records.

    Great info!



    • I had put in “Now, check your Kerberos Realm, IP address and hostname on the server.” That was meant to cover forwards and reverses whether you use DNS on the server or on another box (e.g. in AD). Glad the post was helpful!!! 🙂

  • Carlo

    Hello and many thanks for this detailed article!
    What would be the best upgrade path/strategy to clean re-install your way (that is, clean re-install Lion) for an OD master and its 5 replicas (all 10.6.8) without losing bound clients?

    • Carlo – I would just archive the OD Master, upgrade it (or reinstall since you have an archive). Then import that archive (unless the upgrade worked). Then I’d clean install all the replicas. The bound clients might have a problem during the upgrade but should be fine afterwards provided the names and IPs didn’t change.

      Good luck!

  • unclemac

    Thanks for the steps and info.

    Question: When I import my OD archive, the Users & Groups show and work correctly in WGM, but not in the Server application. Its as though I did not do the import….only the local admin accounts exist.

    Is there a way to get users to be visible with the Server app? Would like to manage Profiles. Am I missing something obvious?


    • I’ve seen this happen before. I just use WGM and manually add users to the ACL groups as needed. In Mountain Lion the ones that were broken in 10.7 appear properly.