Upgrading Thunderbird in the Enterprise

This page is not complete.

This is an Upgrade Guide intended to help large organizations (also referred to as "enterprises") that use Thunderbird to upgrade to Thunderbird version 3. This initial draft is a summary of the draft author's knowledge regarding auto-sync / offline settings (bug 562589) and Thunderbird 3 migration issues relevant to administrators (bug 562589#c7) (as of 2010/05/06).


This Migration Guide makes some assumptions about the typical enterprise environment:

  • IMAP accounts and folders
  • High mail data volume
  • "Roaming profiles" or something similar are common (to support backup/recovery and mobile users)

(The above requirements may not be compatible with the fact that the new global search (Gloda) is enabled by default on upgrade and IMAP folder automatic synchronization is enabled by default on upgrade. This is discussed further below.)

Enterprise environments typically need to perform mass software upgrades rather than upgrade software for individual users. The goals of such an an upgrade may be:

  • To resolve bugs that exist in earlier versions
  • To gain improvements in stability and reliability
  • To gain improvements in performance
  • To gain improvements in usability
  • To minimize or make user training as simple as possible
  • To minimize manpower needed to support the new, updated application

Related information:

Migration Guide (Thunderbird 2 To Thunderbird 3.0)

The major changes in Thunderbird 3.0 that are relevant to enterprise administrators include:

  • Gloda (Global Search and Indexer). Enabled by default.
  • Auto-sync of IMAP folders. Enabled by default.
  • Per-folder "offline use" setting of all IMAP folders is changed to "offline use=On" by default upon migration.
  • "Smart Folders" is default folder pane view, even if "All Folders" is user's choice in Thunderbird 2.

For more detailed information about the changes between Thunderbird 2 and Thunderbird 3, see:

As a general rule, administrators should deal with the process of upgrading Thunderbird and enabling new features separately. That is, they should try to keep the user setup as similar as possible between Thunderbird 2 and 3 and wait until the Thunderbird 3 upgrade is complete and stable before enabling Thunderbird 3 features.

Disable Add-on prior to migration for safe upgrade

Problems due to add-on are known. For example;

  • Bug 562589 Kaspersky Anti-Spam Extension causes blank main window on to 3.0 upgrade
  • Bug 543076 TB 3.0.1 does not handle IMAP Attachments correctly (bug of "Attachment size" add-on or some others)

To avoid such unwanted problems due to add-ons, next upgrade procedure is recommended for safe migration.

  1. Start Tb 2 with -safe-mode to make all add-ons disabled before upgrade.
  2. Keep backup of profile directory before upgrade.
  3. If possible, do uninstall of Thunderbird 2 and clean install of Thunderbird 3, instead of upgrade by software update by Thunderbird 2, for both safe migration and reducing of network traffic.

Disable Migration Assistant

Enterprise sites that perform mass upgrades generally want to prevent users from performing Thunderbird upgrades on their own. An upgrade dialogue in the Thunderbird Migration Assistant should be disabled.


Disable Gloda (Global Search and Indexer) to avoid indexing just after migration

Initail purpose of Gloda was solution of of problem like Bug 383895 (slowness in body text search of local mail data). With enhancements and many improvements by Thuderbird 3 on auto-sync of IMAP folder, Gloda can be used also for IMAP folders very easily. So, gloda is very useful for everyday usage even for IMAP users: It can search messages very fast, much faster than an IMAP server can, and so notably increase productivity. Also, it will in the future have increased functionality in other areas.

However, the new Thunderbird 3 search and index functionality initially impacts performance. (The indexer runs when Thunderbird 3 is first started and will continue to work until all the user's email is indexed. The more messages a user has, the longer the indexer will run.) Also, it uses diskspace on the client (about 1/2 (?) of mailbox size), which is a problem for roaming profiles.

Gloda can be enabled by only single action after upgrade - check an option at Tools/Options/Advanced/General tab. So, to minimize user support workload after migration, we  recommend you to disable automatic enabling of Gloda durng migration by Thunderbird 3.

But how? Is it possible? Enhancement is needed?

Disable Auto-Sync, Keep Per Folder "Offline Use" Setting, to avoid download of all mails in huge IMAP folder just after migration

Auto-sync of IMAP folders is enabled by default for all IMAP accounts. The per folder "offline use" setting of all IMAP folders is changed to "offline use=On" when Thunderbird 3 is launched the first time. To keep same settings as Thunderbird 2, disable the auto-sync and offline-use settings upon upgrade.

To disable auto-sync completely:

lockPref("mail.server.default.autosync_offline_stores", false);
lockPref("mail.server." + serverFromAccount + ".autosync_offline_stores", false);

To disable per folder "offline use" setting change upon migration (Tb 3.0.5 to Tb 3.1rc1):

lockPref("mail.server." + serverFromAccount + ".offline_download", false);

To disable per folder "offline use" setting change upon migration (Tb 3.1rc2 or later):



  • mail.server.serverX.offline_download (default=true) of Tb 3.
    • When an IMAP folder is created or subscribed, set offline use=off if false, set offline use=on if true.
      i.e. This setting is for default of offline use=on/off of an IMAP folder.
  • Enhancement of mail.server.serverX.offline_download=flase prior to upgrade to Tb 3(from Tb 3.0.5 to Tb 3.1rc1).
    • Upon first use of Tb 3, if mail.server.serverX.offline_download=false is set before upgrade, IMAP folder's "offline use" is not touched by Migration code of Tb 3 .
    • It's enhanced by bug 562589. This enhancement is already landed on Tb3.1pre and Tb3.2pre, and the enhancement has been landed on Tb 3.0.5pre(As of 2010/5/10).
  • Above enhancement of mail.server.serverX.offline_download=false prior to migration of bug 562589 has been removed by Bug 569161.
    • Code which changes offline-use=on/off of IMAP folders upon migration is moved to Migration Assistant by bug 569161. So, if Migration Assistant is disabled, offline-use setting of any IMAP folder is never touched upon migration to Tb 3.1 and Tb 3.2.
    • Patch of bug 569161 is landed on Tb3.1rc2 and Tb3.2a1(As of 2010/06/07).

How to enable auto-sync after migration

Account Settings/Synchronization & Disk Space

  • [ ? ] Keep messages of this account on this computer

Current behavior of UI for auto-sync setting.

  • Unchecked->Checked
    1. Set mail.server.serverX.offline_download=true
    2. Set offline use=on of all folders of the IMAP account
    3. Enable "Advanced" button to change offline-use setting of IMAP folders
  • Checked->Unchecked
    1. Set mail.server.serverX.offline_download=false
    2. Set offline use=off of all folders of the IMAP account
    3. Disable "Advanced" button to change offline-use setting of IMAP folders

Note: There is a request for a design change in bug 537943.

Gloda and auto-sync/offline-use are possibly independent, although relevant.

  • "Download Now" button downloads mail to offline-use regardless of offline-use=On/Off.
  • "Download Now" button seems to be intercepted and discarded if auto-sync is enabled and offline-use=On. It looks due to already started schedule based automatic downloading.
  • Auto-sync automatically downloads mail data to offline-store if auto-sync is enabled and if offline-use=On is set in an IMAP folder.
  • "Work Offline" automatcally downloads mail data to offline-store automatically, if per folder offline-use=On is set in an IMAP folder.
  • Gloda indexes mail data in offline-store, if mail data is saved in offline-store, perhaps regardless of auto-sync is enabled/disabled and offline-use=On/Off and Working Online/Working Offline.

Change folder pane view to "All Folders" from "Smart Folders"

By default, Thunderbird 3 displays "Smart Folders" in the folder pane. (Smart Folders combine the messages in similarly named folders in multiple accounts, for example grouping Inbox messages from all accounts into a single Inbox on the Smart Folder pane.) If you want to preserve the default Thunderbird 2 behavior of showing "All Folders", advice users to select View | Folders | All from the menu.

Can "forcing Smart Folders view" upon migration be stopped? How? Is it possible? Enhancement is needed?

Note: "Smart Folders" is renamed to "Unified Folders" by Tb 3.1, and Tb 3.1 won't force it upon migration from Tb2 any more.


Account definition by autoconfig

When new accounts are created, the new "autoconfig" functionality is automatically invoked. Unless users have the correct account definition parameters, it may be confusing for them to configure their own accounts (if this is permitted).

IMAP folder file location

By default, the IMAP folder file is located in each user's profile directory. If the user is storing a lot of messages for off-line access, this can result in too much data for a roaming profile. Regardless of whether or not there is a roaming profile, there may be if the profile is located on a network resource or if Microsoft Window's Offline File (CSC) is used for the offline storage file.

If that is the case, you have two options:

If the Gloda search and index is mandatory for IMAP mail data:

  1. Locate mail directory for IMAP account at location with which remote/network access won't happen(e.g. "Local Settings" of MS Win)
  2. Enable auto-sync, and set offline use=on of IMAP folders.
  3. Accept download of all mails to any PC which uses the IMAP account.
  4. Accept per PC thread pane column setting of the IMAP accout.
      As thread pane column setting is currently saved in .msf file, and as you selected folder location other than profile directory, data in .msf can not be shared among PCs, even when you use Roaming Profile.

When Gloda is not needed for IMAP mail data:

  1. Locate IMAP folder file at any place you want.
  2. Disable auto-sync, and/or set offline use=off of all IMAP folders.
      As new feature of "Disk Cache for mail in IMAP folder of offline-use=off" is added to Tb 3, mail data of viewed mail is held in far larger Disk Cache than very small memory cache of Thunderbird 2. So, frequency of problem like "repeatedly downloaded big attachment data" is reduced very much compared to Thunderbird 2.

As Gloda is first solution of problem of Bug 383895 (slowness in body text search of local mail data), and as many IMAP servers have excellent body text search functionality, consider utilizing of online search first for IMAP mail data. If online search is usable, enabling of auto-sync/offline-use merely for Gloda can be avoided.

Online search of IMAP folder

There is known with regards to online search (documented in Bug 546925 "Run search on server" of Edit/Find/Search Messages doesn't work). For now, users must use Quick Search or Virtual Folder (Saved Search folder) for online searches.

Search, auto-sync, offline-use, and "Smart Folders"

If IMAP folder of offline-use=off, full text search by Gloda won't work because of offline-use=off.

And, if not all mails of IMAP folder of offline-use=on is downloaded into local offline-store file because of your setting for offline-store file size limitation, Gloda can't find not-downloaded mails of the IMAP folder.

And, as "Smart Folder" is internally Virtual Folder(Saved Search Folder), a "Smart Folder" can be Virtual Folder with multiple search target folders in mixture of local mail folders, IMAP folders of offline-use=on(all mails are sync'ed), IMAP folders of offline-use=on(not all mails are sync'ed), and IMAP folders of offline-use=off.

Never open bug at bugzilla.mozilla.org for "Search can't find my mail!" without sufficient checking of "what mail at what kind of folder is not hit by what kind of search at where", please.

Migration Guide (Thunderbird 2 To Thunderbird 3.1)

(content needed)

Migration Guide (Thunderbird 3.0 To Thunderbird 3.1)

(content needed)

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, ethertank, wsmwk, AnthonyMilan, WADA, BenB, jenzed
 Last updated by: chrisdavidmills,