Published on MacDevCenter (
 See this if you're having trouble printing code examples

Tiger's Powerful Migration Assistant

by FJ de Kermadec

Transferring information from an old Mac to a new one has always been one of the tasks I have found most painful when upgrading my computer or operating system. Judging by the number of third-party products and tutorials floating around the Web, I am not alone. Despite this, it seems that we Mac users have it easy, thanks to the flexibility of Mac OS X and Apple's use of innovative firmware features like FireWire Target Disk Mode.

Luckily, the dark days are officially over, since the Mac OS X engineers surprised the Mac world by introducing, along with Mac OS X v. 10.3.4, a new Setup Assistant that also integrated migration capabilities. From the day Mac users first saw this reassuring question "Do you already own a Mac?," they knew the use of unreliable scripts, ugly hacks, and Rogaine to activate the growth of the hairs they had pulled was over. OK, I might be exaggerating a bit on that last one.

Tiger brings us some even better news, as it now ships with a stand-alone "Migration Assistant" that allows you to do all that the Setup Assistant did in an Installer-like, easier-to-use interface. This new assistant, because it is located in the Utilities folder, is now easier to find, and it's easier to extract information from other Macs you own that you've kept to store files. This window-mode, as opposed to the Setup Assistant that worked full-screen, also makes for a much smoother upgrade process, as you stay in control of your computer while the process hums along.

Before We Start

Although Mac OS X engineers have written a reliable, robust migration tool, it's important to keep in mind the limitations of the file transferring process. Indeed, one of the most pleasing side effects of purchasing a new computer or clean-installing your operating system is that you end up with a fresh, perfectly "clean" system that stands unaffected by previous hardware failures, application crashes, or any of the glitches that pop up into our computing routine from time to time.

Therefore, the more information you transfer from an old system to a new one, the more chances there are that you will end up transferring corrupted data or incompatible system files. The Migration Assistant is smart enough to perform some checks and refrain from transferring some files, but it obviously cannot know about the health of every file of every application in every format. The chances of one of these transfers causing real damage to your new installation are low and almost inexistent when transferring simple data files--such as your great aunt's cookie recipe in RTF format, your iPhoto library, or your Address Book database. They get higher as you transfer whole applications (some of them may be incompatible or their accompanying DRM software might get confused by the new environment), or system files (that might contain hardware-specific entries that your new computer does not know how to deal with).

For these reasons, I wouldn't recommend using the Migration Assistant if your previous installation was heavily damaged or corrupted. Instead, use a manual file transfer as described in our Installing Mac OS X v. 10.4 Tiger article. This might take more time but will also make for a smoother transition in the long run.

Also, do not expect the Migration Assistant to save you from hardware failures. Should you have doubts about the physical health of your hard drive, bring it to your Apple Authorized Service Provider instead of subjecting it to a read-intensive duplication process.

What the Migration Assistant Is Not

All you need to migrate your data All you need to migrate your data

Even though the Migration Assistant makes it insanely easy to transfer files from your old Mac to your new one, it's not a back-up or synchronization system. Indeed, there are great applications out there that take care of these steps beautifully, like Carbon Copy Cloner, Apple's very own Backup, or the various updated synchronization services that were introduced or enhanced with Tiger. Every application has its specialty and using the right one for the job is essential, especially when dealing with such important files as your own data.

In a nutshell, Migration Assistant copies from, not to...

Taking Care of Your Old Mac

The first step to transferring your data is, of course, to ensure that your old Mac is in shape and ready to be used as a migration source. As usual, the first thing is to ensure that no minor corruption issue or damaged system files could prevent it from performing as well as it should. This article should provide you with some basic ideas and the information you need to conduct the checks effectively. Although it is Panther-specific, most of the concepts it presents are applicable to earlier versions of Mac OS X and, of course, to our beloved Tiger itself.

Related Reading

Mac OS X Tiger Pocket Guide
By Chuck Toporek

While performing your software maintenance, it is especially important that you pay close attention to privileges. While the default privileges settings should be fine, you do not want some strange "read-only" setting to interfere with the transfer process by blocking the Migration Assistant, in which case some of your files might not be transferred. Usually, this boils down to making sure that Ownership on the volume is not ignored (you can set this through the Finder's Get Info window and it should be the default setting), repairing the permissions through Disk Utility and checking any data folders you might have tweaked yourself. Sure, once a Mac is booted into FireWire Target Disk Mode, privileges are ignored but they will become an issue again once the transfer has happened.

Keep in mind that checking your hard drive's S.M.A.R.T. status is also a good idea at this point as the transfer process can be fairly demanding on mechanisms. You might also want to have a spin with the Apple Hardware Test CD that came with your previous computer to ensure that its FireWire ports are up and running, especially if it has been left in a storage room for some time, collecting dust and mice droppings; but you wouldn't do that to a Mac, would you?

In order to avoid any issues during the process, ensure that both computers are plugged into UPS-protected plugs and that their batteries (if applicable) are charging. This will avoid power cuts during the transfer that can lead to data corruption issues. As no deletion is involved in the migration process, it is very unlikely that the Assistant would lose files but file systems never like to be interrupted while in an unstable state--this is especially true if your older Mac does not belong to the generation that makes use of the HFS+ Journaled file system that Apple introduced with Panther.

Also, ensure that your older computer's firmware is up to date and that it is running an updated version of Mac OS X. While Software Update usually detects firmware updates, you might also want to check the AppleCare Knowledge Base as an additional security. Upgrading your computer's firmware is essential as it will allow the process, which relies heavily on the ability of the target machine to boot into FireWire Target Disk Mode, to happen smoothly, and will avoid confusing your newer Mac, which might not know how to react if the other side misbehaves. Failure to upgrade your firmware can lead to issues ranging from the inability to transfer data between the two drives to freezes.

Should the soon-to-be target machine use an open firmware password, keep in mind that you will need to disable it in order to start it up in FireWire Target Disk Mode. In order to do so, you can follow these steps:

1. Restart your Mac while holding the Option-Command-O-F keys--as in "Open Firmware" 2. Keep these keys depressed until you boot into Open Firmware directly. You might even see a line that says "Release keys to continue!". Note that users who use the full security setting won't even have to use the key combination as their Mac will boot into Open Firmware no matter what. 3. Type "setenv security-mode none" at the prompt and enter return 4. Type your password and enter return 5. Type "reset-all", followed by return to end the session and restart

To re-activate the protection once you will be done installing Mac OS X, simply replace "none" in "setenv security-mode none" by the appropriate level--"command" or "full" and repeat these steps. Open Firmware will have kept your password in mind so you won't be asked to enter a new one.

Note that Open Firmware systematically assumes that you are using a US keyboard--it does not have the necessary information at hand to customize your experience--so you might have to do some re-mapping in your head.

Preparing the Process

Before launching the assistant, ensure that both computers are only connected to the required peripherals--that is an Apple Keyboard, Apple Mouse and power adapter--and that any unnecessary hubs or external drives have been ejected, unplugged and disconnected. Indeed, this will avoid interferences between drives, will make the scanning process easier and, in some rare circumstances involving hardware conflicts might prevent crashes from happening.

It is also important to ensure that the FireWire cable you will be using is up to the task. Indeed, although an iPod or iSight cable (these gorgeously thin white ones) might work, it is preferable to use a data-specific cable--these are usually thicker, provide you with better transfer rates and are less prone to these invisible cuts and bends that can lead to data transfer issues. If you own an external FireWire hard drive, chances are it came with a cable that was made just for that, so you can use it safely.

Finally (and I know I may sound overly cautious but it has its importance), ensure that your computers are placed in such a way that you will not to move them while they do their work. Moving computers whose hard drives are spinning is always a bad idea, even though the latest models have been built to better handle these situations.

Drive-to-Drive Transfers

New options for a flexible transfer New options for a flexible transfer

The Setup Assistant also allows you to transfer information between two drives in your computer. So far, we have assumed you were transferring data from one Mac to another but the general idea remains the same, no matter the method you chose.

Actually, transferring data inside one computer can make for a smooth Panther-to-Tiger transition mechanism if you are a lucky PowerMac owner with multiple drives or have multiple partitions to use. Note that the volume you want to transfer information from needs to be a valid Mac OS X boot volume though in order to be properly recognized by the Migration Assistant. What can be seen as a limitation is actually a feature since volumes that do not contain any system files are likely to be data only ones, that already contain just what you need. Since the Mac OS 9 folder structure did not know about the notion of "accounts" (at least in the same sense than Mac OS X) and allowed users to place applications and files in very varied locations on their hard drives, the Migration Assistant cannot help you transfer files from Mac OS 9 installations either. Given the amount of application upgrading and file re-organizing that is usually involved in these, though, it is probably for the best to not automate that process.

A Warning for FileVault Users

FileVault users might be disappointed to hear that they cannot transfer their accounts to their new machine or installation unless they use the Setup Assistant that pops up when they just finished installing Mac OS X to do so. Indeed, the Migration Assistant, the similar but separate application we are talking about now, cannot take care of these accounts and, while it recognizes them, will not let you select them.

This is easily understandable as the structure of a FileVaulted account makes all your files look like one big file (the FileVault sparseimage) instead of the nested folder structure (the Home containing purpose-specific folders) it should be. Also, by requiring that the Assistant mounts a disk image, FileVault would make it harder for it to draw links between applications and files, making the process a lot risky--plus, there is the whole reconfiguring your new account to be FileVault compliant, which would require that you log out, something you obviously cannot to while the assistant is running. If you are curious about the inner workings of FileVault, this article should provide you with a good overview--things have been improved in Tiger over Panther but the general idea and most of the workings remain the same.

This being said, it is about the only limitation you will encounter with the setup assistant that is equally capable of transferring administrative accounts and managed users--these are structurally speaking more or less the same with different preferences and privileges attached to them.

Let the Migration Begin: the Selection Process

A real assistant: step-by-step instructions A real assistant: step-by-step instructions

After all these considerations, we can now safely proceed with the migration procedure. Note that the assistant will ask you to authenticate, even if you just want to transfer a user account, as it will need to perform administrative tasks so that your new installation recognizes the new account as a valid one.

Once authenticated, you will be asked whether you wish to transfer information from another drive in your Mac or from another Mac booted in FireWire Target Disk Mode. Picking the first option will open up a few panes that will guide you through the process of connecting this other Mac to your new one and starting it up properly. Picking "Another volume on this Mac" will simply display a list of the various Mac OS X drives installed on your computer.

Appropriate volumes are instantly recognized, the others ignored Appropriate volumes are instantly recognized, the others ignored

The assistant will then display a list of the accounts you can transfer. Note that, next to every one, you will see how much space this transfer requires, as well as some basic information regarding the account--a user picture and, if appropriate, a line of information about its transferability status. This is quite straightforward although you should avoid to overwrite accounts you have already created on your Mac with an account that uses the same name in the Migration Assistant. Indeed, you might end up involuntarily archiving your existing account and replacing it by the old one--no data will be lost but it can be quite a surprising effect before one understands what happened.

Once your accounts are selected, now comes the trickier part: selecting which applications, files, and folders you wish to migrate. The voice of convenience would tell you to select everything and the voice of reason nothing, so the balance is up to you. As a general rule, Migration Assistant will perform version checks and tries, as much as possible to guide you through the process of transferring preferences--by insisting that you migrate /Library if you choose to migrate your applications, for example. Transferring the files and folders will mostly be needed if you use the root level of your hard drive--or any files/folders that already exist there--to share files between users of the computer. This is especially important to remember if your workflow relies on features such as faxing that involve putting files there.

Tricky, tricky: will you listen to the voice of convenience or the voice of reason? Tricky, tricky: will you listen to the voice of convenience or the voice of reason?

The next step is more system-oriented and will ask you about time zones, network settings, and sharing options. Transferring time settings is definitely recommended as it will make for a smoother upgrade and will ensure that your logs are consistent--although one would hope that the right time zone was already detected by Setup Assistant when you first started your Mac, so you'll probably not even need to select that option. Transferring network and Sharing settings can also speed the setup process up--especially if your ISP prides themselves in giving out the most atrocious mandatory login names and passwords or if you need to join VPNs that all have a separate configuration that you need to type manually. Just keep in mind when migrating from an older system that the Tiger sharing features have evolved and are now refined, so migrating them does not mean you should not visit the Sharing preferences pane in order to ensure that all the fine details are properly set up--you do turn that firewall on, do you?

Clicking on the "Migrate" button will then cause the Migration Assistant to run a number of checks including making sure that you will not accidentally overwrite any existing account, in which case it will prompt you for instructions. A cool feature of the Tiger Migration Assistant is that you can rename accounts on-the-fly if, for some reason, you need to import a user whose name already appears on the new configuration.

Once any conflicts solved, the Assistant will proceed to transfer files and folders step-by-step keeping you updated on the status of the process. Note that now may be a good time to lock your screen and grab a cup of soy milk, as neither the Finder nor the assistant enjoy having to fight with you over the ownership of files or folders they are working on--you might experience punctual but real slowdowns or Finder windows may seem empty when you open them as the assistant is transferring a large number of files to them--purely cosmetic but counterproductive never the less and you need to rehydrate anyway!

One feature that is missing from the Assistant is a log window, like the one that exists for Installer and that keeps you informed, step-by-step of what gets done, copied and installed from within the application.

Once the transfer has completed, Migration Assistant will display a succinct summary of what happened, along with a shiny "Done" button that will, in one swell click, close the window and quit the application. In most cases, you will simply be informed that the transfer was successful. Should it not be the case, the apparent lack of a log might be an issue--more on that later.

Application Extravaganza

Mac OS X has been designed from the ground up so that installing applications is as easy as dropping an icon onto an Applications folder--the Applications folder located at the root of your hard drive or the little known ones located in each user's individual home. From there, applications maintain a cleverly organized hierarchy of .plist files, containing their preferences, store caches in a finite, predictably placed, number of "Caches" folders and, if at all necessary, stick a couple files in the "Application Support" directory. This makes it all easy to transfer applications from computer to computer, from user to user and to put all the files back in place without needing to worry too much.

This was without counting on some developers that decided that this structure wasn't good enough and started creating folders where they shouldn't have--Microsoft Office User Data anyone?--or breaking the user hierarchy and precedence system. Worse, some larger companies invested in some sloppy DRM software that relies on a complex structure of files and folders scattered in invisible locations on your system. Luckily, these cases are relatively uncommon but they do exist. These applications, of course, cannot be transferred with the same degree of confidence and, for the most protected ones, are guaranteed to fail.

This is why Migration Assistant, once its job completed, will attempt to give you a list of the applications it could not transfer, so that you can start re-installing them properly. While this is by no means fool-proof, it's already an excellent start and should allow you to quickly grab the appropriate CDs.

As a general rule, transferring the shared files and folders should transfer a good portion of any system-wide application-specific files. It's up to you to decide whether that's a good thing--will this allow you to get your settings back and start working immediately or will this cause some funky DRM software to go berserk on you and call the legal department of some software manufacturer? (Hint: it is usually the first case but professional users relying on some high-end editing applications might want to exercise caution)

The Magic of Serial Numbers

Most applications, when they quiz you for a serial number, will rely on some embedded engine to decide whether that is or not a valid serial number and grant you access based on that calculation, usually along with displaying a nice thank you dialog. Some others, though, rely on what the developers think are permanent, computer-specific indicators.

While relying on the MAC address of a machine, its hard drive's serial number or some other hardware-based indicator is usually relatively transparent to the user, keep in mind that some applications rely on software markings that your upgrade might well change--unfortunately popular examples are your time zone (what if you move?), the name of your home folder (what if you change your name?), a checksum of some invisible UNIX directories (what if I go Fink-happy?). In that case, you might need to call the developers and explain your situation so be sure to factor that time into your migration process.

Should you use any applications that rely on others, now would be time to look into these dependencies too. For example, Tiger now ships with the awesome QuickTime 7, that brings us drool-worthy new encoding features, along with a slick new interface. Unfortunately, it also brings us a new activation number for the Pro version, that you might need to obtain from the Apple Store before installing some of your other applications. The same applies to other software, like Photoshop plugins, which will obviously need Photoshop to be up and running to do their work.

Post-Migration Healing

Once the migration has completed, you should be able to use your Mac without having to worry too much about setup and configuration--after all, what we have outlined above is more of a worst-case scenario. However, it's important to keep in mind that you might run into some glitches in the unlikely event that Setup Assistant migrated an old component that it shouldn't have transfered or damaged cache files that will cause an application to misbehave.

Luckily, this is all easy to fix. You might want to try following these steps in order to get back on track:

  1. Repair permissions on your boot drive by using the "Disk Utility" located in your "Utilities" folder. This will ensure that all your applications are installed as they should be and will diminish the chances that you will run into the "Access denied" kind of errors that can be easily bothersome. So far, Migration Assistant always did a perfect job permissions-wise for me but, as the saying goes, it cannot hurt...

  2. Run Software Update one last time. In the unlikely event that an optional download (like a Java installer) was reverted to an older state, it might confuse Tiger applications that rely on it. Using Software Update will help ensure that everything is up-to-date. These cases are uncommon, though, given that Migration Assistant does perform some integrity and version checks. A word of caution: deleting the "Receipts" (installer packages) located in (drum roll) /Library/Receipts is unlikely to be of a real help--it can in certain cases trick Software Update into re-applying an installer but is not guaranteed--and is guaranteed to prevent Disk Utility from doing permissions repair properly as it relies on these files. When in doubt, download installers from the Apple Support Downloads site.

  3. Get rid of cache files. Deleting (or moving away in a first time) your various Library/Caches folders can help get rid of potentially unwanted files that might cause applications to misbehave. Should you decide to parse through the "Application Support" directories, keep in mind that these can contain some irreplaceable data like your Address Book database--feel free to peek inside and delete appropriate subdirectories but, unless you have some of that Rogaine left, do not delete the whole directories!

Use the Console, Luke!

While the Migration Assistant does not have a log window and can sometimes be succinct in letting you know what is happening, Console can be of a great help. This utility, located in your "Utilities" folder allows you, as you probably know, to look at your various Mac OS X logs easily. Both the System and Console logs should provide you with valuable information.

For easier viewing, you can enter "Migrat" (Yep, "Migrat") in the filter field, which will catch both references to the "Migration Assistant" and "MigrateTool", the executable located deep down inside the Migration Assistant bundle from which all magic originates. Of course, keep in mind that the Console can be quite verbose and that what appears to be an error message can sometimes be innocuous.

Now comes the meaty part! A very detailed log (get the spectacles and a box of candy) called SystemMigration.log can be found in /Library/Log and, of course, read through Console as well--you will find it listed in the "Logs" list on the left hand side. While very detailed, this log will allow you to know exactly what was transferred, what was skipped, what the UIDs of the new accounts are and just about everything you might need to know. Studying this log will without doubt be of use to system administrators who wish to learn more about how the system works and treats their default configuration before recommending it to their users.

By the way, should you have written any shell scripts that rely on user ID numbers (UIDs), you may want to ensure that your script will work with the new account as Migration Assistant cannot guarantee that accounts will have the same ID on your new system and on the old--as the ID might already be occupied by another account.

Old Mac, Uh?

When Migration Assistant finds applications to migrate to your new Mac, it will try to transfer them in as transparent a way as possible. An application called Cute will be migrated as the exact Cute, which will avoid confusing scripts or processes that might expect to find them.

However, should the Migration Assistant transfer the same application twice (this can happen when you transfer applications multiple times, especially when the applications are contained inside folders, which seems to slightly confuse the migration tool), the second copy will be labeled "From old Mac" (no matter where it actually comes from) and following copies will also be numbered "From old Mac 1,2,3...".

Transferring System Settings

Even system settings can be easily migrated. But is it really a good idea? Even system settings can be easily migrated. But is it really a good idea?

Thanks to the modular .plist architecture that powers Mac OS X, transferring system settings is as easy as transferring the right .plist files for Migration Assistant. Should you have already started to set Tiger up, though, you will want to exercise caution as the transfer can overwrite your existing settings--for example, even though your Panther firewall settings will be transfered, any UDP blocking or logging options you might have on will be lost. These are minor issues, though, as the assistant is likely to be used before you start really setting your Mac up. Security conscious users will definitely want to keep that in mind, though!

Also, be careful when migrating from radically different Macs. For example, your laptop may be set up to display a battery indicator in the menu bar and its Energy Saver preferences pane will allow you to set up sleep delays for both the battery and the adapter. Of course, these are all nonsense to your shiny new desktop Mac. During the transfer process, though, the preferences file that says "display a battery indicator here" might be transfered, causing a strange crossed icon to be displayed--your Mac is basically telling you "I can display it if you want but, dude, it makes no sense whatsoever". These glitches are purely cosmetic as Mac OS X is smart enough to ignore any preferences or applications that do not apply to your hardware--just don't be surprised if you notice a few harmless oddities like these.

Network settings are trickier as your new Mac (or Tiger) might allow you to interact with other devices in more ways than Panther or your old machine did. This is why you will want to have a look at your Network Preferences pane, dismiss any "Hey, this is new!" sheets that appear when your Mac wants to share its joy to have discovered a new port and, if applicable, to set up these new services--or disable them for additional security, battery savings and speed.

The Fun Never Stops

Attention to detail: when your Terminal feels apologetic. Attention to detail: when your Terminal feels apologetic.

Looking into the Setup Assistant's bundle reveals a "migration tool" that can easily be called from command line and displays the cutest little message ("Please don't run me") when launched from Terminal from a non-root user account. As this tool has not been designed to be used from Terminal, it will expect parameters to be passed when launched and will not make efforts to help you find them. Never the less, one rarely encounters such polite applications!

While running the Migration Assistant from the command line is certainly doable, thanks to a mixture of shell scripting, GUI apple scripting, and a sprinkle of Mac magic, system administrators looking to "push" an upgrade onto multiple Macs will more likely benefit from using different technologies such as NetBoot or NetInstall, which provide them with a truly scalable, push-button system. While it is a versatile, powerful application, Migration Assistant has been developed for individual users above all.

Final Thoughts

Migration Assistant is a small utility that doesn't look like much when launched. It is, however, technically brilliant and will solve many of the headaches traditionally associated with migrating from one computer or operating system to another. By following a few simple rules and applying common sense to the process, you will be able to get back to work (or play) in a matter of minutes, with the assurance that, far, far away, in an office in Cupertino, someone made sure your installation is in the best possible shape.

FJ de Kermadec is an author, stylist and entrepreneur in Paris, France.

Return to

Copyright © 2009 O'Reilly Media, Inc.