Skip to main content
Jump to: navigation, search


< Equinox‎ | p2
Revision as of 11:41, 25 February 2012 by David (Talk | contribs) (Confirm your p2.mirrorsURL works with p2 operations)

Disclaimer: this page is not authored by a p2 expert, I merely reproduced some information which I found difficult to collect -- Stephan

Enabling your repository to leverage mirrors

The p2.mirrorsURL should be added to your metadata so that p2 will see the list of available mirrors to choose during installation.

Who should add?

Everyone. Every build. At least, everyone at, that is. Other companies or networks may have their own mirroring system and scripts which are similar to this, but these instructions are specific for the Eclipse Foundation infrastructure.

It is true that not each and every build or repository is mirrored (e.g. integration builds usually are not) but having the property there, even if there are no mirrors, should not hurt anything ... p2 knows to simply fall back to the normal "originally requested" location if no mirrors are found (usually '').

It is also true that those mirroring eclipse downloads and repositories have some choice in what they mirror (there are several options, such as "full", "releases only", "platform only" and similar). So, everyone should add the property, since you can never be sure if/when your repository might be mirrored. If it is not mirrored, by anyone, at some point in time, having the property there should not hurt anything ... p2 knows to simply fall back to the normal "originally requested" location if no mirrors are found (usually '').

Where to add?

Adding this property to artifacts.xml is sufficient, since p2 uses a list of mirrors while retrieving artifacts, not the metadata itself. (Hence, no need to have one in content.jar/xml or compositeContent.jar/xml files). Don't forget, artifacts.jar must be updated or replaced after changing artifact.xml. (If both exist, artifacts.jar will always be fetched before artifacts.xml.)

Should composite repos be treated, too, or just their children (leaves)?

Just the leaves. No need to to specify the property in compositeArtifacts.xml/jar.

What to add?

The p2.mirrorsURL property has the following structure:

  <property name="p2.mirrorsURL" 
  • replace {repository_path} with the path where your artifacts.jar sits on,
    e.g., for the {repository_path} would be /eclipse/updates/3.6/R-3.6.2-201102101200
  • yes, &amp; is 5 characters, in this context the escaped version is required.
  • the last part, &amp;protocol=http is important, since it restricts the list of mirrors to those that support http. Monitor bug 349679 for status/progress on p2 working with ftp sites. (In general, such as for zip files linked on download pages, and similar, the 'protocol' parameter is optional for the download.php script and when omitted both http and ftp mirrors are returned).
    bug 349679 seems to have been a red-herring (or some special case) so ftp and http should both work fine, so there is no need to specify the protocol attribute and the mirrors script (download.php) will return a list that contains both types ... and the more there are to try, the better.

This p2.mirrorsURL property will end up giving p2 a list of 0 to 100 or so URLs to try and fetch artifacts from. If your project is not mirrored (or, there is some other problem with mirrors) p2 will fall back automatically to using the originally requested site location (usually '').

How to add?

If you use a site.xml the word goes that this is where you should specify this property. The Equinox/p2/Publisher should automatically transfer this information into your metadata.

If you don't use a site.xml you may consider manually editing artifacts.xml (which of course can be automated using, e.g., an xsl template, like this p2.xsl from the Mylyn project). When manually editing artifacts.xml add the property to the existing list of properties right at the top of the document. Don't forget to update the size attribute of the enclosing <properties> element.

Others have reported that the p2.mirror ant task can be used to insert properties like p2.mirrorsURL while mirroring the build output to the final destination. The following two snippets may serve for inspiration:

<!-- generate template with proper mirror urls -->
        ... specify string substitutions here ...
<!-- mirror to target (but only the bits that really changed) -->
<p2.mirror ...>
  <source location="..."/>
  <destination .../>
        name="${} (Build ${buildId})"

These snippets were extracted from this build.xml from the gyrex project.

How to test?

If you change your artifacts.jar/xml file, you may have to wait a a while, for mirrors to get "in sync" before being able to test, such as a few hours, or at most overnight.

Avoid Mirror invalidation
In some cases, it is easy to temporarily "invalidate" your mirror list; that is, make it appear, temporarily, that there are no mirrors. This happens if you change the directory timestamps that contains the artifact.jar as you edit. It is the directory that is used in p2.mirrorsURL, so it will appear there are no mirrors if the timestamp changes to current time, even though all the mirrors still have your actual artifacts. But -- this is the tip -- the directory's timestamp only changes if files are added or removed, but not if simply the content of a file changes. So, you can avoid temporarily invalidating mirrors by copying the artifact.jar file to some 'temp' directory, unzip it it there, update it, and zip it back to artifacts.jar and then copy it back to the original location (all carefully of course). If you do somehow invalidate the mirrors list temporarily, it should not take too long to get some mirrors back (a few hours, or overnight for sure), since there's no real work to do ... just update the fact that they are in sync.

Confirm your artifacts site is being mirrored

The first test you do should be with a browser, to confirm the download.php script does indeed return some mirrors for your site. To do this, paste the full URL you specified as the value in the p2.mirrorsURL attribute into your browser (now collapse &amp; to &). The result should be an XML file in your browser with a list of mirror URLs. For an example, you can paste the following URL into your browser, to see who is mirroring the Indigo SR2 artifacts:

Pasting one of these resulting URLs into the browser should in turn take you to the directory holding your artifacts.jar and its peers. (You may have to add "artifacts.jar" or "content.jar", etc, to the URL, if directory browsing is not allowed on a mirror).

Note: note all "builds" (or repositories) are mirrored. For for example, integration builds, staging sites, etc. See IT Wiki page for details.

Confirm your p2.mirrorsURL works with p2 operations

To test whether install successfully uses mirrors (and which ones) you may use the following options file (stored, e.g., as /tmp/p2options or simply placed in .options file in 'eclipse' directory (the default location)):


(The first line generally enables debugging p2, the second line selects specific tracing for mirror selection)

Then you may want to unpack a fresh Eclipse package and change into the eclipse directory.

Finally, use the normal Eclipse UI to do an "update" or for more focus, you can use the p2 Director application to install your feature using a command line similar to the following:

 ./eclipse -consoleLog -noSplash -debug /tmp/p2options -application org.eclipse.equinox.p2.director \
       -repository \

This should install your feature and print to the console where each artifact was downloaded from. If p2.mirrorsURL is not properly configured no such messages will be shown.

You may want to "capture" the console results in a separate file by adding something like the following to the end of your 'eclipse' command (at least on Linux):

2>&1 | tee fulllog.txt

Once "mirror selection tracing" is in such a log file, you can produce a quick "histogram" of frequencies of what mirrors are being selected with a command similar to

grep Selected fulllog.txt | cut -d ":" -f 5- | cut -d "(" -f 2 | cut -d "/" -f 1,2,3 |  sort | uniq -c | sort -r -n 

If things are working well, you should see few, if any, times that "" is selected. As one example, here are the results of one run, updating Indigo SR1 Java EE IDE to SR2 from the built-in repositories:


Avoiding mirrors, even when using p2.mirrorsURL

You can disable the automatic mirror selection mechanism by setting the VM argument eclipse.p2.mirrors to false (remember that vm args have to be last on the command line preceded by the switch -vmargs). Normally this is not desired or recommended since it may be slower or, if many people did it, all the time, cause Eclipse Infrastructure to slow down for everyone and overuse bandwidth. But, it can be used occasionally for tests if you suspect a problem with mirroring (for example, if it appears you are getting old or stale content you might want to try by-passing mirrors temporarily, to test that.

Moving a repo to

Another situation where redirected downloads are desirable is when a repo is moved from to For files references using the Find a Mirror script ( moving to archive is transparently handled by that script. This section is exploring how the same effect can be achieved for p2 repositories.

The obvious way might be through the use of p2.mirrorsURL, however, I couldn't get this to work -- Stephan.

The following strategy seems to do the job (although admittedly, not a candidate for beauty contests):

  • when moving everything to keep a copy of all metadata (artifacts.jar and all those) on
  • extract the .xml files and edit like so:
    for composite repositories
    Ok green.gif edit both compositeContent.xml and compositeArtifacts.xml:
    • simply change all relative paths to absolute paths pointing to
    for leaf repositories
    Warn.gif edit artifacts.xml (this is the ugly, unofficial approach - use at your own risk):
    • remove any p2.mirrorsURL property (and decrease the size of the enclosing <properties> element accordingly).
    • in the <mappings> element replace all occurrences of ${repoUrl} with the archive path to your repo, like
    • to be on the safe side increment the p2.timestamp value in the top list of properties

After editing put the .xml files back into their respective jar.

An alternative, cleaner strategy for leaf repositories has been discussed in bug 349141#c3:

Ok green.gif redirect using a composite repository as a proxy:
  • move repository as-is to archive (maybe should remove p2.mirrorsURL at this point? No need to remove p2.mirrorsURL. When queried, if no longer mirrored, it returns a list of zero length and p2 then knows to use originally requested location URL.)
  • create new composite repository pointing to

Back to the top