Nexus Repository 2 Upgrade and Compatibility Notes

Visit my.sonatype.com for documentation on Nexus Repository version 2.

Verify Your Nexus Repository 2 Upgrade Path

* To upgrade version 1.x to a version greater than 2.7.2 will involve two separate upgrades. First upgrade to 2.7.2. Then upgrade to the latest version.

Sonatype Nexus Repository 2 Upgrade and Compatibility Notes

Please check the update notes for any intermediate upgrade versions to find steps you might need to perform after upgrade.

You should always manually reset your logging configuration on upgrade.

To Release 2.14.8 from 2.14.7

No manual steps required.

To Release 2.14.7 from 2.14.6

No manual steps required.

To Release 2.14.6 from 2.14.5

No manual steps required.

To Release 2.14.5 from 2.14.4

No manual steps required.

To Release 2.14.4 from 2.14.3

No manual steps required.

To Release 2.14.3 from 2.14.2

No manual steps required.

To Release 2.14.2 from 2.14.1

No manual steps required.

To Release 2.14.1 from 2.14.0

No manual steps required.

To Release 2.14.0 from 2.13.0

No manual steps required.

To Release 2.13.0 from 2.12.1

No manual steps required.

To Release 2.12.1 from 2.12.0

No manual steps required.

To Release 2.12.0 from 2.11.4

No manual steps required.

To Release 2.11.4 from 2.11.3

The format of request.log statements has changed such that the elapsed time in milliseconds is included as the last field value. Adjust any log parsers accordingly.

The archived request.log file name pattern has changed. Any 3rd party scripts that rotate out these archived files may need to be updated.

To Release 2.11.3 from 2.11.2

No Manual steps required.

To Release 2.11.2 from 2.11.1

Action is required before upgrading if you rely on accessing .nexus/attributes repository paths over HTTP. This is only needed in exceptional circumstances.

If your load balancer is relying on a session cookie name of JSESSIONID to map UI sessions to Nexus instances, you may need to adjust your configuration.

If you have npm repositories, consider scheduling a Backup npm metadata database scheduled task after upgrade.

To Release 2.11.1 from 2.11.0

No manual steps required.

To Release 2.11.0 from 2.10.0

SSLv3 Disabled By Default For Proxy Repositories

Rarely some Nexus instances may be proxying repositories over HTTPS that are relying on SSLv3. These repositories may become automatically blocked on upgrade with a message about handshake_failure. These days some version of TLS is commonly used instead and ideally the remote server should expose use of a more secure protocol. As a workaround, Nexus Administrators can customize the outbound protocols or change to a plain http remote URL.

RubyGems Support Included

Older versions of nexus-ruby-plugin you may have installed into NEXUS_HOME/nexus/WEB-INF/plugin-repository or sonatype-work/nexus/plugin-repository should not be installed into Nexus 2.11.
Nexus will handle upgrading the previous configuration automatically using the bundled plugin.

YUM Requirements Updated

Nexus instances which use YUM related features should ensure they have at least the following command line tools installed and available to the Nexus process user:

• createrepo version 0.9.9 or greater
• mergerepo version 0.1 or greater

To Release 2.10.0 from 2.9.2

No Manual steps required.

To Release 2.9.2 from 2.9.1

No manual steps required.

To Release 2.9.1 from 2.9.0

No manual steps required when upgrading Nexus.

Maven users should upgrade nexus-staging-maven-plugin to version 1.6.3 and nexus-m2settings-maven-plugin to version 1.6.3.

Ant users should upgrade nexus-staging-ant-tasks to version 1.6.2. 

To Release 2.9.0 from 2.8.1

During upgrade from previous Nexus Repository 2 Professional versions, Nexus Repository 2 will migrate the NuGet feed database to a new format. Therefore as standard practice, it is recommended that users back up this database under $NEXUS_WORK/nuget before upgrading. This should be done while the server is not running. [NEXUS-6700]

Note: This one time database migration may take considerable time for large NuGet databases.

If you have any "Download NuGet Feed" tasks scheduled to run in your Nexus instance Sonatype recommends you remove them, this task isn't needed in 2.9.

To Release 2.8.1 from 2.8.0

Temporary Directory Location Changed

In previous releases, it was possible that the temporary directory used by Nexus Repository 2 (${NEXUS_WORK}/tmp) was not consistently set for some operations. Nexus Repository 2 now defaults the temporary directory used as ${NEXUS_HOME}/tmp. See the article discussing the temporary directory for more information [NEXUS-6595].

Notable: Turn on strict URI matching in restlet

Nexus Repository 2 restlet now uses strict URI matching as the default.  This may impact the functionality of some third-party plugins.  If you are using plugins not supplied by Sonatype you should test these against 2.8.1 before upgrading, it is possible (although unlikely) that REST endpoints in these plugins may not work correctly in 2.8.1 (NEXUS-6630).

To Release 2.8.0 from 2.7.2

Upgrade from Nexus 1.x Requires an Additional Step

Users upgrading from 1.x versions of Nexus must first upgrade to the latest 2.7.x version, then upgrade to Nexus 2.8 or newer. Direct upgrade of any Nexus 2.x version to 2.8.0 continues to be supported.

Third-Party Plugin Compatibility

If you have developed (or make use of) a Nexus plugin that is not distributed with Nexus you should validate that it works with the 2.8.0 release before upgrading.

Jetty Configuration

Jetty configuration has changed.  Users who add additional capabilities into their Jetty configuration may now do so by simply adding additional lines to the wrapper.conf file which reference the additional configuration. For instance, to add JMX support you can add a line into the wrapper.conf as follows:

# These lines ship with Nexus 2.8
 wrapper.app.parameter.1=./conf/jetty.xml
 wrapper.app.parameter.2=./conf/jetty-requestlog.xml

 # This line enables JMX support.
 wrapper.app.parameter.3=./conf/jetty-jmx.xml

Some of these require additional properties to be set in $NEXUS_HOME/conf/nexus.properties.  The example above needs:

jmx-host=<hostname>
jmx-port=<port>

More information can be found in NEXUS-6153.

To Release 2.7.2 from 2.7.1

New Behaviour: 401 responses to web browser User-Agent do not include WWW-Authenticate header

NEXUS-6189 introduces a side effect in how Nexus responds with 401 which may affect some external tooling. See the article for more information.

To Release 2.7.1 from 2.7.0

A critical security vulnerability which affects all versions of Nexus (CVE-2014-0792) has been discovered by Sonatype. This vulnerability has been fixed in the 2.7.1 release.

A patch is also available which fixes this issue for all 2.x versions of Nexus.  Information about this can be found in  Nexus Security Vulnerably article.

This fix may cause some 3rd party plugins to malfunction.  If you are using plugins which are not supplied by Sonatype please test them on a staging instance before putting 2.7.1 into production.  If you encounter any problems see here for instructions on how to solve them.

To Release 2.7.0 from 2.6.4

If your Nexus previously used the optional nexus-custom-metadata-plugin, then after upgrade you need to explicitly enable it by going to Administration -> Capabilities, and adding the Custom Metadata capability.

If your Nexus had proxy repository Mirrors configured, Nexus 2.7 has removed support of this feature. There is no action required at upgrade, however all files will be retrieved directly from the proxy remote URL now. The hosted repository mirrors tab remains for now, but will be removed in a future release.

Nexus instances using custom plugins should be tested for compatibility. Many APIs that could have been used by custom plugins have been deprecated or removed in Nexus 2.7.

If you have developed any Nexus upgrade scripts, please be aware:

• the conf/jetty.xml file has been changed in 2.7. Using an earlier jetty.xml may prevent Nexus from starting.
• custom logback-nexus.xml modifications should be reviewed and updated as Nexus 2.7 has introduced a logback-overrides.xml file and new Logging UI that should be used instead
• the optional-plugins directory has been removed and all shipped plugins are installed by default. 

Ensure that you only use the shipped 2.7 versions of Sonatype Nexus plugins. This is especially relevant for the branding plugin, since using an old branding plugin can prevent Nexus startup.

The old startup scripts (located under $NEXUS_HOME/bin/jsw/$ARCH in the installation directory) have finally been removed.  These have been deprecated since Nexus 2.0. Users should use the new startup scripts introduced in Nexus 2.0, located in $NEXUS_HOME/bin (NEXUS-5781). The 'clickable' Windows batch files (*-nexus.bat) have remained, but the only use case for these are to be 'clicked' to perform a specific named action.

Old versions of the nexus-m2settings-maven-plugin are not compatible with Nexus 2.7.  You will need to use version 1.5.1 or higher if you are using this plugin.

To Release 2.6.4 from 2.6.3

No manual steps required.

To Release 2.6.3 from 2.6.2

No manual steps required.

To Release 2.6.2 from 2.6.1

No manual steps required.

To Release 2.6.1 from 2.6.0

No manual steps required.

To 2.6.0 Release from 2.5.0

Nexus 2.6 requires Java 7 to run.  If you were previously using Java 6 you will need to install a new JRE to run Nexus.

To 2.5.0 Release from 2.4.0

No manual steps required.

To 2.4.0 Release from 2.3.1

Users of the Nexus Professional Staging Suite features should carefully review the release notes for 2.4.0 before upgrading.

To 2.3.1 Release from 2.3.0

No manual steps required.

To 2.3.0 Release from 2.2.1

Internet Explorer Compatibility

As of version 2.3.0 Nexus no longer works with IE7.  This change can also impact users of IE8 and IE9, see here for information on how to fix this if you are affected:

https://support.sonatype.com/entries/22926682

Third Party Plugin Compatibly

A focus of the 2.3.0 release was updating the versions of libraries shipped with Nexus to pick up bug fixes, security fixes, and performance improvements. As a result there have been significant changes in versions of libraries shipped with Nexus 2.3.0, and also a few plugin API changes. If you have developed (or make use of) a Nexus plugin which is not distributed with Nexus you should validate that it works with the 2.3.0 release before upgrading.

Yum Plugin Migration

The new Yum repository support in Nexus 2.3.0 is not compatible with the old open source Yum repository implementation. If you were using the old plugin you will need to manually convert hosted and group Yum repositories into regular Maven 2 repositories. To do this edit "sonatype-work/nexus/conf/nexus.xml" and change these lines:

<providerHint>maven2yum</providerHint>

To this:

<providerHint>maven2</providerHint>

If you were using Yum staging support you will also need to edit "sonatype-work/nexus/conf/nexus.xml" and change there lines:

<repositoryTemplateId>maven2yum_hosted_release</repositoryTemplateId>

To this:

<repositoryTemplateId>default_hosted_release</repositoryTemplateId>

After restarting you can add Yum metadata creation to these repositories as described in the documentation.

To 2.2 Release from 2.1.2

The contents of the jetty.xml and nexus.properties files have changed significantly from the 2.1.2 release. You will need to manually re-apply any changes you've made to the 2.1.2 jetty.xml to the 2.2 jetty.xml.

To 2.1.2 Release from 2.1.1

No manual steps required.

To 2.1.1 Release from 2.1

No manual steps required.

To 2.1 Release from 2.0.6

The contents of the jetty.xml file have changed significantly from the 2.0.6 release. You will need to manually re-apply any changes you've made to the 2.0.6 jetty.xml to the 2.1 jetty.xml.

The Nexus Professional Smart Proxy communication protocol has changed. If you are making use of this feature you will need to upgrade all nodes from 2.0.x to 2.1. In future releases we will do everything we can to maintain backwards compatibility.

The Nexus Professional Trial Edition is no longer identical to the regular Nexus Professional edition. When upgrading Nexus Professional be sure to download it from the customer support site (log in using your support account credentials).

To 2.06 Release from 2.0.5

No manual steps required.

To 2.05 Release from 2.0.4-1

No manual steps required.

To 2.0.4-1 Release from 2.0.4

No manual steps required.

To 2.0.4 Release from 2.0.3

No manual steps required.

To 2.0.3 Release from 2.0.2

No manual steps required.

To 2.0.2 Release from 2.0.1

No manual steps required.

To 2.0.1 Release from 2.0

No manual steps required.

To 2.0 Release from 1.9.2.4

Conf Folder Changes

There have been significant layout changes in the Nexus bundle in the 2.0 release. This means that the configuration files under "<nexus_root>/conf" and "<nexus_root">/bin/jsw/conf should not be copied to the new version. Re-apply changes you have made to these files (if any) to the versions which ship with Nexus 2.0.

Note that plexus.properties has been superseded by nexus.properties

In order to keep the heap usage in check it is recommended that you schedule an "optimize indexes" task to run weekly. This can be done under "administration/scheduled tasks" in the Web UI.

Unified Startup Scripts

Controlling Nexus from the command line has been made simpler. Rather than executing a platform specific executable under <nexus_app_dir>/bin/jsw/<platform_name>/, you can use either one of the <nexus_app_dir>/bin/nexus or<nexus_app_dir>/bin/nexus.bat which will delegate to a suitable platform specific script.

The previous platform specific scripts are left in place for backwards compatibility and to allow forcing a specific platform executable - but we expect that most customers will prefer the unified control scripts for simplicity.

If you have copied the startup scripts from "<nexus_root>/bin/jsw/<arch-dir>" to "/etc/init.d" or similar be sure to replace these with the new scripts which ship with Nexus 2.0 and don't forget to adjust commonly set things like piddir, runasuser, etc.

wrapper-override.conf NOT SUPPORTED IN FUTURE VERSIONS

Additions to the "<nexus_root>/bin/jsw/conf/wrapper.conf" file can now optionally be placed in "<nexus_root>/conf/wrapper-override.conf".

To 1.9.2.4 Release from 1.9.2.3

No manual steps required.

To 1.9.2.3 Release from 1.9.2.2

No manual steps required.

To 1.9.2.2 Release from 1.9.2

Important: Nexus 1.9.2 contains a bug (NEXUS-4483) which can cause the system feed database to grow very large, resulting in poor performance. If you are currently running 1.9.2 you are likely affected by this issue, and we recommend that you perform the following steps during upgrade:

1. Shut down Nexus 1.9.2
2. Remove or rename "sonatype-work/nexus/timeline"
3. Start Nexus 1.9.2.2

Note that if you are upgrading from a previous version of Nexus (prior to 1.9.2) then the steps above are not necessary.

To 1.9.2 Release from 1.9.1.1

No manual steps required.

To 1.9.1.1 Release from 1.9.1

No manual steps required.

To 1.9.1 Release from 1.9.0.2

No manual steps required.

To 1.9.0.2 Release from 1.9.0.1

Republish group indexes.
Note: If upgrading from a pre 1.9 release you can skip this step.

To 1.9.0.1 Release from 1.9

No manual steps required.

To 1.9 Release from 1.8.0.1

Sonatype has changed how the lucene indexes are stored on disk, it is required that users reindex all repositories in their nexus server to start benefitting from the changes (and for search to work properly).

To 1.8.0.1 Release from 1.8.0

No manual steps required.

To 1.8.0 Release from 1.7

No manual steps required.

To the 1.7 Release from any earlier Release

Sonatype has changed the local format of the lucene indexes, it is required that users reindex all repositories in their nexus server to start benefitting from the changes (and for search to work properly).

To the 1.6 Release from a 1.4 or 1.5 Release

Sonatype has changed the location of configuration files for the Java Service Wrapper startup scripts. If you are upgrading from a Nexus 1.5 instance to a Nexus 1.6 instance you will need to make sure that you are using the latest "nexus" script in the appropriate platform folder. If you previously installed Nexus on a Linux system and copied the ./bin/jsw/(platform)/nexus startup script to the /etc/init.d directory you will need to make sure that you copy the newer version of this nexus script (or create a symbolic link to the newer version of the script).

NOTE: It is not appropriate copy your existing wrapper.conf over the new wrapper.conf in 1.6.0. Sonatype has made significant changes to the configuration parameters and paths which are configured in the new wrapper.conf. If you have a customized wrapper.conf file, Sonatype recommends that you compare the existing file with the new wrapper.conf file shipped with Nexus 1.6.0 and merge each customization manually.

In addition to this simple configuration change, you should also take note of the additional platform now available in the ./bin/jsw directory: macosx-universal-64. If you are running Nexus on a 64-bit OSX platform, you should start using this startup script instead of macosx-universal-32.

To Releases after 1.0.0

There are no significant changes to system and upgrade is relatively easy. Simply unpack the bundle in the same folder that contains your nexus-webapp-xxx-bundle and sonatype-work folders. This will create a new folder called nexus-webapp-yyyy-bundle. Shutdown the old Nexus, switch any symlinks you may have and start Nexus from the new folder. That's it.

To Release 1.0.1 from 1.0.0

There are no significant changes to system and upgrade is relatively easy. Simply unpack the bundle in the same folder that contains your nexus-webapp-1.0.0-bundle and sonatype-work folders. This will create a new folder called nexus-webapp-1.0.1-bundle. Shutdown the old Nexus, switch any symlinks you may have and start Nexus from the new folder. That's it.

If you currently modify the host, ports or context in plexus.xml, these are now settable via environment properties. Simply set plexus-application-port, plexus-application-host or plexus-webapp-context-path in the env before starting Nexus. More details are shown on the FAQ page.

To Release 1.0.0 from 1.0.0-beta-5/5.1

In the Nexus betas, the configuration was stored in $basedir/runtime/apps/nexus/conf/nexus.xml and the configuration pointed to the nexus work folder, which had a default of $basedir/runtime/work/nexus. This made upgrades between versions troublesome as the work folder and config were located inside the path of the bundle and required manual moving of that data. 

In 1.0+, this has been greatly simplified. The work folder has a new default of $basedir/../sonatype-work/nexus. That is, it is now a sibling of the bundle folder by default. The location can be overridden two ways: 1st by setting the PLEXUS_NEXUS_WORK environment variable to the work folder, or by editing the $basedir/conf/plexus.properties nexus-work variable. The first method is preferred as it eliminates the manual file moving/editing that was present in pre 1.0 betas. 

The nexus.xml file is now located in the $nexus-work/conf/ folder. This means that it should actually be very easy in the future to upgrade as you can unpack the new bundle. Shutdown the old version and startup the new version without moving any files around. 

If you are upgrading from an earlier beta version, you will need to take a few steps to get to the new 1.0 layout.

The default recommended configuration would look like this:/Nexus
+--/nexus-1.0.0
+/runtime/apps/nexus

+--/sonatype-work
+/nexus
+/storage
+/conf/nexus.xml

If this acceptable to you, then you would perform the following steps.

1. Make a folder that will contain the work folder and the bundles (if you don't already have one). We will refer to this as $nexus_home in the instructions. We will refer to the current location of your nexus bundle as $nexus-beta-bundle
2. Move (or copy) the contents of $nexus-beta-bundle/runtime/work/nexus to $nexus_home/sonatype-work/nexus
3. When this is done you should have $nexus_home/sonatype-work/nexus/conf and $nexus_home/sonatype-work/nexus/storage etc.
4. Move (or copy) the $nexus-beta-bundle/runtime/apps/nexus/conf/nexus.xml to $nexus_home/sonatype-work/nexus/conf
5. Unpack the new 1.0 bundle in $nexus_home. This should produce a folder called nexus-1.0.0-webapp-bundle in $nexus_home.
6. The startup scripts will be located in $nexus_home/nexus-1.0.0-webapp-bundle/bin/jsw/NX:os folder
7. You can now startup the new installation and it should find the work folder and upgrade the configuration.

If you want to specify another location for your work folder, perform the following steps.

We will refer to the current location of your nexus bundle as $nexus-beta-bundle 

1. define the environment variable PLEXUS_NEXUS_WORK to contain the value of your existing nexus-work folder. (this would be the location you previously specified in your nexus.xml file).
2. Move (or copy) the $nexus-beta-bundle/runtime/apps/nexus/conf/nexus.xml to $PLEXUS_NEXUS_WORK/sonatype-work/nexus/conf
3. Unpack the new 1.0 bundle in $nexus_home. This should produce a folder called nexus-1.0.0-webapp-bundle in $nexus_home.
4. The startup scripts will be located in $nexus_home/nexus-1.0.0-webapp-bundle/bin/jsw/[NX:os folder]
5. You can now startup the new installation and it should find the work folder and upgrade the configuration.

To Release 1.0.0-beta-5/5.1 from 1.0.0-beta-4/4.2

The user passwords are stored with a new hash algorithm that is not compatible with earlier betas. This means that you must reset your admin and deployment passwords after upgrading. In this beta, you must login as the deployment user (default password "deployment123") to change its password.

Also note that if using Apache httpd, please review the httpd section of the Nexus FAQ

To Release 1.0.0-beta-4 to 1.0.0-beta-3

No manual steps required.

To Release 1.0.0-beta-3 from 1.0.0-beta-2

After starting the system, run "rebuild attributes" on all hosted repositories. This is done to migrate the checksums to the proper location in the repository data.

To Release 1.0.0-beta-2 From 1.0.0-beta-1

No manual steps required