Release specific upgrade instructions
Upgrading to release 169 and later release
Release 169 includes several database changes to complete our transition to using the term Legacy Violations. Users may experience longer upgrade times (around an hour), regardless of the backend, i.e. H2 or PostgreSQL.
Upgrading from release 151 and earlier to a later release
This upgrade can initially take much longer to perform. This is due to the schema expansion introduced for enhanced product experience.
Upgrading from release 118 and earlier to a later release
The IQ Server Docker image for IQ release 119 has fixed the issue with the non-graceful shutdown of the IQ server.
Halting the container before release 119 requires the following command.
docker exec -ti $(docker container list -a | grep nexus-iq | head -n 1 | awk '{print$1}') bash -c 'kill -TERM "$(cat /sonatype-work/lock | cut -d"@" -f1)"'Where the portion of the command surrounded by $(docker ...) returns the docker container_id of the IQ server. If you have already identified the container_id of the running IQ server, you can alternatively run the below command by replacing the container_id with the id of the container you have identified:
docker exec -ti container_id bash -c 'kill -TERM "$(cat /sonatype-work/lock | cut -d"@" -f1)"'
Upgrading from release 117 and earlier to a later release
The sonatype/nexus-iq-server docker image for IQ release 118 changed the UID of the nexus user from 997 to 1000, and changed it from a system account to a user account. This is to minimize the chance of a future collision with other UIDs. If you use this image with a persistent data volume you will need to change the owner in order for the new image to start up successfully.
Here is one example of a way to change the peristent storage owner:
docker run -it -u=0 -v sonatype-work:/sonatype-work sonatype/nexus-iq-server:1.118.0 chown -R nexus:nexus /sonatype-work docker run -it -u=0 -v sonatype-logs:/var/log/nexus-iq-server sonatype/nexus-iq-server:1.118.0 chown -R nexus:nexus /var/log/nexus-iq-server
This will start up release 118 of an IQ server container with root as the user, allowing it to chown the sonatype-work and other persistent directories and its files to the correct nexus user.
Upgrading from release 100 and earlier to a later release
The sonatype/nexus-iq-server docker image for IQ release 101 changed the base image from Red Hat UBI (Universal Base Image) to a different Red Hat UBI that includes OpenJDK 1.8. As a result, the UID of the nexus user has changed from uid=998 to uid=997. If you use this image with a persistent data volume you will need to change the owner in order for the new image to start up successfully.
Here is one example of a way to change the peristent storage owner:
docker run -it -u=0 -v sonatype-work:/sonatype-work sonatype/nexus-iq-server:1.101.0 chown -R nexus:nexus /sonatype-work
This will start up release 101 of an IQ server container with root as the user, allowing it to chown the sonatype-work directory and its files to the correct nexus user.
Upgrading from release 97 and earlier to a later release
The SAML implementation in IQ Server was updated in Release 98 and requires the "Destination" field to be set, if the SAML messages (request/response) are signed. This is in accordance with the SAML specification and if not done you may encounter an authentication error. See Error during SSO login "Authentication failed due to SAML error" after upgrading Nexus Repository 3 or IQ Server for more information.
Upgrading from release 68 and earlier to a later release
The sonatype/nexus-iq-server docker image for IQ release 69 changed the base image from CentOS to RedHat UBI (Universal Base Image). As a result, the UID of the nexus user has changed from uid=999 to uid=998. If you use this image with a persistent data volume you will need to change the owner in order for the new image to start up successfully.
Here is one example of a way to change the persistent storage owner:
docker run -it -u=0 -v sonatype-work:/sonatype-work sonatype/nexus-iq-server:1.69.0 chown -R nexus:nexus /sonatype-work
This will start up release 69 of an IQ server container with root as the user, allowing it to chown the sonatype-work directory and its files to the correct nexus user.
Upgrading from release 64 and earlier to a later release
Release 65 of IQ Server introduces a new policy-centric UI for Application Composition Report.
There are some differences that might not be obvious and are worth mentioning:
The threat level counters in the old Application Composition Report counted the number of violating components, while the similar counters in the new version of the report count violations.
In Aggregated mode, the "waived" and "grandfathered" indicators in the policy violations table are displayed when all of the violations for the given component are waived or grandfathered. In the Summary mode of the old Application Composition Report, which is analogous to the current Aggregated mode, the "waived" and "grandfathered" indicators never appeared.
Upgrading from version 1.44 and earlier to a later release
Version 1.45 of IQ Server introduces a more compact format to store the policy violation data of your applications. Upgrading to this version and the new storage format can take notable time. To properly prepare for this upgrade, refer to our detailed instructions on upgrading to version 1.45 below:
Warning
If you have been directed here from your IQ Server's error log and this is the first time you see these upgrade instructions, we suggest you abort the server upgrade you were about to commence and revert to your previous IQ Server version.
The upgrade procedure outlined below requires preparation and should not be rushed. Read these instructions carefully and only retry the server upgrade once you have had a chance to make the necessary preparations.
Starting with version 1.45 or greater, IQ Server uses a more effective and condensed format to store policy violation data. Depending on the database size of your installation and the hardware you use, upgrading your database to this new format can take notable time (up to hours in worst case scenarios). These instructions are meant to help you plan and reduce the downtime of your IQ Server while the upgrade is carried out.
Preparing for the Upgrade
Upgrade to IQ Server 1.44 First
If your current installation is several versions behind and not already running IQ Server version 1.44 you should update to that version first. This reduces the number and duration of upgrade tasks both the server and its administrator have to consider when later upgrading to version 1.45 or greater. In particular, you should perform the update to version 1.44 during a different maintenance window than the update to version 1.45 or greater.
Ensure Sufficient Free Disk Space
Until the upgrade is fully completed, the IQ Server's database will temporarily contain policy violation data in both the old and new storage format. As a result, the database will generally grow while the upgrade is in progress. To avoid running out of disk space during the upgrade, we recommend having at least as much free space as the database currently occupies on the disk hosting it. You can determine the amount needed by looking at how large the database file is, e.g. sonatype-work/clm-server/data/ods.h2.db (see your server's config.yml and its sonatypeWork option for the path applicable to your installation).
Perform a Test Run of the Upgrade to 1.45 or greater in a Staging Environment
Given the number of unknown variables about your particular installation, it is impossible to predict the duration of the upgrade and the maintenance time you should expect. By performing a test run of the upgrade in a non-production environment, you can learn about its approximate duration and plan your maintenance for the real upgrade accordingly.
For that test run to be representative, it should be executed using a recent backup/clone of your installation and on hardware closely comparable to your production system. Especially the I/O performance of the storage holding the server's database (sonatype-work/clm-server/data) is a key factor for the upgrade duration.
The test run also helps you estimate the resulting database size and verify that your storage system has enough free space to accommodate it.
Compact the Database Before the Upgrade
A long-lived database contains some percentage of empty space to support its efficient growth. If your server's database (sonatype-work/clm-server/data/ods.h2.db) is several gigabytes large, this percentage of empty space can amount to gigabytes as well. Removing this empty space, a process called compacting, can reduce the upgrade duration for IQ Server 1.45 or greater.
To compact your server's database:
Shut down your IQ Server
Execute the command
java -jar nexus-iq-server-1.44.0-01.jar compact-db config.ymlor equivalent for your environmentYou may restart your IQ Server once the above command has finished
Compacting the database is an I/O heavy operation and, depending on the size of your database and the storage performance, can take several minutes or longer. To help plan the needed maintenance window, we suggest you perform a test run of this process in a staging environment on comparable hardware using a recent backup of your installation.
Over time and with continued use of IQ Server, the database will again accumulate some empty space. In order to benefit the upgrade to IQ Server 1.45 or greater, compacting the database should therefore be done not too far in advance of the upgrade, e.g. within a week prior to the 1.45 or greater upgrade. If easier for you to implement, you can perform this step right before upgrading to version 1.45 or greater. We primarily mention it as a separate preparation step to allow you to organize the upgrade over several smaller maintenance windows instead of one long maintenance if desired.
Use a Fast Disk/Storage
The upgrade to IQ Server 1.45 or greater is an I/O intensive task. The performance of the storage device holding the server's database (sonatype-work/clm-server/data) is a key factor for the upgrade duration. Depending on your environment, it can be beneficial to at least temporarily employ a faster disk for IQ Server and its upgrade.
Internal Reference Numbers
Our internal benchmarks may provide some rough guidance on expected upgrade times, though as noted above the upgrade complexity is highly dependant on your particular installation.
Database Size | Upgrade Time SSD | Upgrade Time HDD |
|---|---|---|
3.3 GB | ~ 1 minute | ~ 10 minutes |
7.2 GB | ~ 2 minutes | ~ 15 minutes |
8.9 GB | ~ 3 minutes | ~ 40 minutes |
19.0 GB | ~ 5 minutes | ~ 60 minutes |
67.0 GB | ~ 60 minutes | ~ 15 hours |
Performing the Upgrade
Take a Fresh Backup Before the Upgrade
This should be second nature for the diligent reader of our general upgrade instructions but is worth emphasizing: Backing up the IQ Server before the upgrade ensures you have something to fall back to in the unlikely event something goes haywire.
Update the Server's config.yml to Consent to the Upgrade
To save unsuspecting administrators from surprises, IQ Server 1.45 or greater requires a change to the configuration file to signal the implications of the upgrade are understood and the necessary preparations have been made. So for the aforementioned test runs and the actual upgrade of your production system, the following line needs to be inserted into the config.yml file used to launch IQ Server 1.45 or greater:
# Confirm you have read the upgrade instructions and come prepared consentToUpgradeToVersion_1_45: true
If the line is missing, IQ Server will refuse to start with an error in its log, directing to these upgrade instructions.
Once the upgrade to version 1.45 or greater has completed, you can remove that line from the config.yml again.
Compact the Database After the Upgrade
Once IQ Server has completed the upgrade to 1.45 and is up and running again, its database will still roughly have the same size as before. To cash in on its more efficient storage format for policy violation data, its database needs to be compacted (again) as described earlier. This task can be done at a later time like the next available maintenance window or right after the upgrade, whatever works best with your maintenance schedule.
To compact your server's database:
Shut down your IQ Server
Execute the command
java -jar nexus-iq-server-1.45.0-01.jar compact-db config.ymlor equivalent for your environment or version.You may restart your IQ Server once the above command has finished
You might choose to skip compacting the database before the upgrade, e.g. because your test run found the upgrade was already sufficiently quick, but we strongly recommend to compact the database after the upgrade to 1.45 or greater. In our testing, we observed size reductions of 50% and more.
Upgrading from version 1.42 and earlier to a later release
IQ Server version 1.43 uses a more powerful configuration format (config.yml).
If you wish to use a configuration file from a prior version, then you must update it. Refer to our configuration update guide for more information.
Upgrading to version 1.42 or later requires version 1.16 or later
IQ Server version 1.42 or later will no longer perform data migrations for versions before or including 1.16.
This is to streamline future data migrations to improve data storage and its scalability.
Upgrading from version 1.35 and earlier to a later release
IQ Server version 1.36 replaces the Security Vulnerability present policy condition with the Security Vulnerability Severity greater than or equal to 0 policy condition and removes the Security Vulnerability absent policy condition. The upgrade to 1.36 or later will fail if you have any policies relying on the Security Vulnerability absent policy condition. Before attempting to upgrade, we highly recommend that you perform a backup. If the upgrade fails, then you can still start the previous version against this backup. In the meantime, you can contact the support team or your customer success representative directly for assistance in changing any of your policies that rely on the Security Vulnerability absent policy condition.
Upgrading from version 1.17 and earlier to a later release
IQ Server version 1.18 introduces the Root Organization—a new entity at the top of the system hierarchy that allows you to set policy globally across all organizations and applications. After you update the IQ Server to version 1.18, you should configure and create the Root Organization. It’s a one-time process and occurs when the server is restarted. The process makes a permanent change to the system hierarchy that cannot be undone. It is strongly recommended that you back up the IQ Server and read "Introducing the Root Organization" before proceeding.
In IQ Server version 1.21, the Sonatype CLM for Hudson and Jenkins plugin has been updated and rebranded to Nexus IQ for Hudson/Jenkins 1.x. If you have a prior version of the plugin installed, then you must uninstall the older version before installing the newer rebranded one. For installation instructions, see the Nexus IQ for Hudson/Jenkins 1.x chapter.
IQ Server version 1.26 introduces CSRF protection for all available plugins that use reverse proxy authentication. This new protection is enabled by default. If you want to upgrade to IQ Server version 1.26 and use reverse proxy authentication in your plugins, you should upgrade your plugins to their latest versions first.
Note
If you would like to upgrade to IQ Server version 1.26 and use reverse proxy authentication with older plugin versions, you will need to disable CSRF protection for reverse proxy authentication. See the section on Reverse Proxy Authentication for more information.
Note
Both Nexus Repository version 2.14.3 and older and Nexus Repository version 3.2.1 and earlier 3.x versions do not support CSRF protection when using reverse proxy authentication. If you want to use reverse proxy authentication with these Nexus Repository versions and IQ Server 1.26 or later, you will need to disable CSRF protection for reverse proxy authentication. See the section on Reverse Proxy Authentication for more information.
Upgrading from version 1.15 and earlier to a later release
Due to data migrations, you will need to upgrade to version 1.16 first before proceeding to upgrade to version 1.23 or later versions of IQ Server.
Upgrading from version 1.16 or earlier
In version 1.17 a rebranding of the Sonatype CLM product took place and is now known as Nexus IQ. As part of this rebranding two of the binaries also changed during this release:
Server
From: sonatype-clm-server
To: nexus-iq-server
CLI
From: sonatype-clm-scanner
To: nexus-iq-cli
If you have any scripts utilizing the previous names, you will want to update these given the change above.
Note
In the example above, only the server name is given. The full binary name would look like nexus-iq-server-1.27.0-01.jar
Upgrading from versions earlier than 1.9.x
While Sonatype only supports the previous two releases, we are happy to help direct any upgrade needs you may have. If you are upgrading from a version before 1.9.x, contact the support team.