Eclipse multi-user installs

Eclipse provides a number of strategies for supporting multi-user installs. Each strategy satisfies a specific scenario. This document covers these strategies, describing when each one should be used. The intended readers are product engineers configuring an Eclipse-based product for distribution, system administrators setting up Eclipse-based products to be used through a network and developers interested in creating plug-ins that are good citizens in such setups.

Last Modified: June 17th, 2005

Basic concepts


As described in the Eclipse Runtime options article, there are three different locations that are important in the context of deploying Eclipse in a multi-user setup:

Configuration initialization

Before Eclipse has been run for the first time, the configuration area is basically an empty directory. This location is gradually populated by the Eclipse runtime, and other plug-ins, across Eclipse sessions. Most of the metadata kept by the Eclipse runtime (e.g. plug-in dependencies, the extension registry) is written during the shutdown of the first session. If no changes are made to the set of installed plug-ins, no data has to be written during subsequent sessions. We say the configuration is initialized. When the configuration is in this state, it is even possible to make the configuration area read-only. Making the configuration area read-only is useful in scenarios such as shared configurations (more on this later).

The -initialize command-line option allows one to initialize the configuration area without requiring an Eclipse application to run. The initialization procedure forces the creation of any metadata that is written out to the configuration location during the first Eclipse session. However, there are other files kept in the configuration area that are created only when needed. Examples are:

For these cases (and others that 3rd-party plug-ins might introduce), the initialization procedure is not sufficient to fully initialize the configuration area. There will still be need to write to the configuration area although this need tends to disappear as all the execution paths in the application that cause files to be created in the configuration area are visited. Only after that it can be said the configuration area is fully initialized and no write access to it will ever be required in order for Eclipse to run.

Scenario #1 - private install

This is actually a single-user scenario. The Eclipse install is used by a single user, and the user has full access privileges to it. The configuration area location defaults to the configuration directory under the install location.

The procedure to set up this scenario requires just making sure the user has full rights to the install location.

Scenario #2 - shared install

In this scenario, a single install area is shared by many users. The "configuration" directory under the install area is home only to the config.ini as shipped with the product (it is not initialized). Every user has their own local standalone configuration location.

The set up for this scenario requires making the install area read-only for regular users. When users start Eclipse, this causes the configuration area to automatically default to a directory under the user home dir. If this measure is not taken, all users will end up using the same location for their configuration area, which is not supported.

Scenario #3 - shared configuration

Here users share not only an install area but also a master configuration area. Users still have, by default, their own private writable configuration areas. A user's private configuration area is cascaded to the master configuration and will not contain any interesting data if the master configuration has been fully initialized and no changes to the set of plug-ins to be installed has occurred.

In this scenario, the system administrator initializes the master configuration (typically under the install location), and ensures the whole install and configuration areas are read-only to users. When users run the Eclipse-based product from the shared install location, since they do not have write access privileges to the configuration area under the install area, a local configuration area will be automatically computed and initialized.

The more fully initialized the shared configuration is, the less need there is for files to be created under the local configuration.

Setting the private configuration area location

The default location for a private configuration area is:


The user home dir is determined by the user.home Java system property. The product id and version are obtained from the product marker file .eclipseproduct under the Eclipse install.

A non-default configuration area can be defined by setting the osgi.configuration.area system property. This property can be set by the end user, but it is more convenient to set it either in the launcher .ini file or in the config.ini file at the base configuration location.


Shared configuration

Plug-ins can be installed in/removed from the shared configuration. Users will catch up with those changes the next time Eclipse runs. It is necessary to make sure users having the shared configuration as their master configuration are not running Eclipse.

Private configuration

Users can modify their local configuration areas by installing additional plug-ins. This does not cause any changes to the shared configuration, so other users will not see the changes. Note that plug-ins configured at the shared configuration cannot be removed. If they are, they will be reinstalled the next time the platform starts.