Upgrading the IQ Server

General Upgrade Instructions

The latest version of IQ Server can be downloaded from the IQ Download and Compatibility page.

Before starting any upgrade, review all upgrade instructions for your current version (see additional sections below), as well as any versions that followed.

Additionally, any process that can interrupt the IQ Server upgrade should be temporarily disabled until the upgrade is complete. In a Kubernetes environment, this includes liveness probes that may restart the IQ Server container during the upgrade. This may require one startup with liveness probes disabled to upgrade to the new version, and then a second startup with the liveness probes reenabled.

To upgrade the IQ Server:

  1. Diff the new config.yml file with your current config.yml file. Manually merge differences from your current file into a copy of the new file.

  2. Stop the IQ Server

  3. Perform a backup , including backing up your current config.yml file. 
  4. Replace the old config.yml with the new config.yml file created in step 1.
  5. Copy the new jar and change the startup scripts to reflect the new jar name
  6. Start the IQ Server.

Optionally you can manually merge the changes from the existing config.yml into the new, but this is not required.

If there is any concern, please feel free to contact our support team: support@sonatype.com.

Release Specific Upgrade Instructions

Upgrading from Release 118 to Release 119 or Later

The sonatype/nexus-iq-server docker image for IQ release 119 has fixed the issue with non-graceful shutdown of the IQ server. For stopping the IQ docker instance prior to release 119 (for the purpose of upgrading to 119 or any other reason) you would need to use 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 or Earlier to Release 118 or Later

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 or Earlier to Release 101 or Later

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 or Earlier to Release 98 or Later

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 or Earlier to Release 69 or Later

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 peristent 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 or Earlier to Release 65 or Later

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 or Earlier to Version 1.45 or Later

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 the IQ Server to Version 1.45.

Upgrading from Version 1.42 or Earlier to Version 1.43 or Later

IQ Server version 1.43 uses a more powerful configuration format (config.yml).

(warning) If you wish to use a configuration file from a prior version, then you must update it. Please 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 prior to or including 1.16.

This is in an effort to streamline future data migrations to improve data storage and its scalability. 

Upgrading from Version 1.35 or Earlier to Version 1.36 or Later

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 our support team: support@sonatype.com 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 or Earlier to Version 1.18 or Later

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 backup 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.

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.

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 or Earlier to Version 1.23 or Later

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.

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 prior to 1.9.x, please contact our support team directly: support@sonatype.com.