migration-assistant has been stagnating for several releases. It will be partially rewritten in Python in order to ease the maintenance burden. It will also be separated from ubiquity, the desktop CD installer, and turned into a D-Bus service.

Release Note

The migration functionality in the installer has been moved into its own application under System -> Administration -> Migration Assistant. It has also been updated to import from the following sources...


  • Being able to carry documents and settings from a previous installation makes the barrier to entry much lower for users coming from Microsoft's Windows or Apple's Mac OS X.
  • migration-assistant's presence in the installer violates its guiding principle of "do only what is necessary to get the operating system up and running". Its code in the installer is complex and difficult to maintain.
  • Making migration-assistant a D-Bus service allows other applications to leverage its facilities. For example, Banshee could use migration-assistant to directly import music from iTunes, rather than relying on the user to run the migration-assistant frontend, or ubiquity could call its methods to find an ideal computer name, timezone, keyboard map, etc.

User stories



  • Since migration-assistant is no longer part of the installer, it can depend on any libraries that are included on the live CD or are small enough and sufficiently well maintained to be promoted to the live CD seed.


Operating Systems

  • Microsoft Windows XP through Windows 7
  • Apple OS X
  • Major Linux distributions


  • Microsoft Outlook, Evolution, Mozilla Thunderbird
    • Contacts
    • Account settings
    • Email messages
    • Calendar events (time permitting)
    • TODO list items (time permitting)
  • Apple iTunes, Banshee, Rhythmbox, Windows Media Player
    • Music
    • Playlists
  • Mozilla Firefox, Microsoft Internet Explorer, Apple Safari, Opera, Google Chrome
    • Bookmarks
    • Homepage
    • History (time permitting)
  • AOL IM, Yahoo! IM, MSN IM, Pidgin IM, ...
    • Accounts
    • Contacts
    • Logs (time permitting)
  • System
    • Wallpaper
    • Documents
    • Desktop files
    • Pictures
    • Fonts
    • Bookmarks (files and folders)
    • WPA/WEP wireless encryption keys (time permitting)
    • IPP network printers (time permitting)

| Select any accounts that you would like to import into Ubuntu.  |
| The documents and settings for these accounts will be available |
| after installation.                                             |
|                                                                 |
| +-------------------------------------------------------------+ |
| | v [X] Evan <small>Microsoft Windows 7 (/dev/sda1)</small> |^| |
| |       [X] (&) iTunes music <small>10 GB</small>           | | |
| |       [ ] (&) Desktop files <small>1.2 GB</small>         | | |
| |       [ ] (&) Wallpaper <small>0.5 MB</small>             | | |
| | > [X] evan <small>Ubuntu 9.04 (/dev/sda2)</small>         |v| |
| +-------------------------------------------------------------+ |
|                                                                 |
|                                             [ Quit ] [ Import ] |

(&) represents an application icon, as grabbed from the source operating system (see implementation notes below).


  1. The existing Windows registry code will be tidied up and wrapped in a Python C module.
  2. Python modules for parsing binary OSX plist, and XML OSX plist files will be written.
    • libplist has been created since we last looked at the binary plist format, and while it cannot be used as a drop in replacement (it just converts from binary to XML and back), we can reuse much of its code.
    • A working implementation of an XML plist parser already exists in Evan's local tree.
  3. migration-assistant will be partially rewritten in Python as a dbus service (see notes below), sufficiently abstracted to allow for importing to Ubuntu and Kubuntu, and sufficiently future proof to allow importing to intermediary storage and to allow use of its methods by other desktop applications.
  4. Code to import from OSX, Windows XP through Windows 7, and Linux sources will be written.

migration-assistant as a D-Bus service

The migration-assistant backend will be exposed to the frontend as a D-Bus service that will present the frontend with methods for importing data.

  • Identifiers will be of the form: /com/ubuntu/migration-assistant/52ffe065-a09a-4ee7-b604-4ef54505e363/Evan/PIDGIN
  • The method for obtaining the icon for a particular import routine will copy the icon to /tmp (if it does not already exist there) and return the full path to the icon.
  • Translation will be up to the frontend, using the item enum (PIDGIN, SAFARI) as a key.
  • The migration-assistant D-Bus service can be left running, or torn down and restarted at import time, with caching of data left up to the backend.

The D-Bus interface is detailed in /DBusService.

Conflict resolution

Copying /media/disk-2/home/evan/Documents/test to /home/evan/Documents/test:
vol_id /dev/sda1 -> 52ffe065-a09a-4ee7-b604-4ef54505e363
md5 52ffe065-a09a-4ee7-b604-4ef54505e363/home/evan/Documents/test -> 78ddc6ae8d1bd5afdd19e0ab61be853a -> $HASH

If $HASH not in /home/evan/Documents/.migration-assistant:
        If test in /home/evan/Documents:
                copy /media/disk-2/home/evan/Documents/test /home/evan/Documents/.migration-assistant/$HASH
                ln /home/evan/Documents/.migration-assistant/$HASH /home/evan/Documents/test$1
                copy /media/disk-2/home/evan/Documents/test /home/evan/Documents/.migration-assistant/$HASH
                ln /home/evan/Documents/.migration-assistant/$HASH /home/evan/Documents/test
        copy O_TRUNC /media/disk-2/home/evan/Documents/test /home/evan/Documents/.migration-assistant/$HASH

Targets of opportunity

These are items that would be nice to have, but should not be considered when evaluating this specification for completeness.

  • migration-assistant should generate a report of what it did copy and what it either could not, or was unable to, copy.

Test/Demo Plan

A test case for migration-assistant already exists. It will be modified to account for migration-assistant becoming a desktop application, and to cover the new features.

Unresolved issues

Future work:

  • Importing to other targets, such as Ubuntu One, for cases where the user is replacing an operating system with Ubuntu. In this scenario, ubiquity will present the following interface:

/!\ If you replace Windows XP with Ubuntu, you will lose all of your
    documents and settings unless you first use the Migration Assistant
    application to import them.  [ Run Migration Assistant ]
  • Continuous importing as an option in the desktop application, for dual boot systems where both operating systems are actively used.


MigrationAssistant/Karmic (last edited 2009-06-04 11:26:00 by cpc3-slam5-2-0-cust447)