Migrate your projects_root directory

We recommend that you make a copy of your projects_root directory and migrate the copy. This way, users can continue to use Validate, though they should be instructed not to make any changes, such as changing an issue's status.

To reduce the amount of time required for migration, we also strongly recommend that you delete unneeded projects and failed builds before migration, as detailed in the procedure that follows.

If you are moving to a new major release of the software, ensure that you have a compatible license, as each major release requires a new Validate license. See Licensing for more information.

If you do not use the default server settings, you will need to specify your custom settings prior to beginning the upgrade. Otherwise, during the installation these settings will revert back to the default settings. If you forget, you can always go in and change the settings for each of your environments after you have completed upgrading.

Tomcat server configuration:Validate's Tomcat server configuration (<projects_root>/tomcat/conf/server.template) will be backed up and replaced during migration. The backup file will be named server.template.bak or server.template.bak_X (where X is a number). If your server.template had modifications from the Validate defaults, you can copy them from the backup, ensuring that maxPostSize is set to -1, and re-start the Validate server.

Supported upgrade paths

Find your current version in the chart below and follow the appropriate upgrade path. If you need to upgrade from earlier versions of the product that aren't listed in the table below, use the import method. See Import your existing projects into a new projects_root for more information.

Perforce is also here to help! If you need to move from an older release, you can contact Static Code Analysis Professional Services to discuss assistance via a services engagement.

Interoperability between releases

To take advantage of the latest improvements in Validate, we always recommend you upgrade your Server, Build, and Desktop Analysis plug-ins to the latest version of the product. Validate Server and Build Tools are compatible with the Desktop Analysis plug-ins within each major release.

Validate also provides the ability to load builds from the previous major version of Validate into the current version of Validate. For example, this means you can load Validate builds from any version of Validate 2022 into Klocwork 2024.1 without having to import or migrate data.

Running two versions of the Validate Servers

If you will be running two sets of the Validate Servers, for example to test the Validate 2024.1 Servers while users continue to access your existing servers, you must run them on different projects_root directories (and set the ports appropriately).

To prepare to upgrade:

1. For the projects_root you want to migrate, run the following command:

   validate service --projects-root <projects_root> check 
   

2. Make note of what servers are running and what ports they are running on. After migration to the new version of Validate, the servers will be running on these ports.
3. Stop the servers.
4. To create a restore point, perform a complete backup of any projects_root directories you want to migrate. After you upgrade Validate, you cannot undo the upgrade.
5. If you customized any configuration files (such as kwmysql.ini or kwfilter.conf), back up the <server_install>/config directory.
6. Start the servers.

   Important: To reduce the time required to migrate your data, we strongly recommend that you:

   • Delete any projects from the previous version that you do not need to migrate.
   • Delete any failed project builds from the previous version. You cannot resume a build that failed in a previous release after migrating the project as described in this article. However, you may be able to load the build from tables.

7. Stop the servers.
8. (Optional) To create a second restore point, back up the projects_root directories you have prepared for migration.
9. Store the existing Validate license in a safe place.
10. To prevent confusion, delete the old Validate logs from <projects_root>/logs.

Install the Validate 2024.1 Server package. For instructions, see Installing Validate.

dbvalidate is a tool that checks the consistency of data in your database. Running this tool is mandatory, so that any errors in your database can be corrected before you migrate or import. Use the version of the dbvalidate tool that matches your installed version of software (that is, the version that matches your projects_root directory).

The Database Server from your old installation must be running to validate the database. The Database Server is listed as a separate service from the Validate Server, so ensure that it is running.

Run the following command, for example:

java -jar <server_install>/class/dbvalidate.jar --projects-root <projects_root>

where

• <server_install> is your installation directory
• <projects_root> specifies the location of the old projects root you want to validate

Example

java -jar /local/tools/validate/server/class/dbvalidate.jar --projects-root /local/tools/validate/server/projects_root 

The dbvalidate tool will report any errors between the "validation started" and "validation finished" lines:

Wed Jun 01 07:53:58 CDT 2020 kw_central database (version: 95) validation started
<detected errors appear here>
Wed Jun 01 07:54:28 CDT 2018 Database validation finished.

• If Errors are displayed, please open a support ticket so that we can correct the error prior to import or migration.
• If no errors are displayed, your database was successfully validated.

You can also run dbvalidate with the --rebuildIndex=true option; This enables you to re-create the lucene index for the specified project, which often allows you to decrease the size of the index.

For example, you can run the following:

java -cp dbvalidate.jar com.klocwork.dbvalidate.Cleanup231 --projects-root <projects_root_folder> --project <project_name> --rebuildIndex=true

If you are using a remote license server, convert it to Reprise before migrating.

If you received a new license file from Customer Support, copy it to your new <projects_root>/licenses folder.

To migrate a projects_root, run the following command from <Validate_2024.1_Server_install>/bin:

validate service --projects-root <old_projects_root> start --migrate

If the projects_root migrates successfully, the Validate Servers start on the port numbers picked up from the migrated projects_root.

Notes

• If you imported a custom taxonomy in a previous release, you need to re-import the new taxonomy file to pick up changes.
• If you will be running the Validate Servers as Windows services, after starting the servers with the --migrate option, stop the servers with validate service --projects-root <migrated_projects_root> stop. Then start the Validate 2024.1 services in Windows Services Administration.
• You can manage the Validate servers remotely on Unix with SSH, or on Windows with Windows Services administration. Otherwise, you must issue the start, restart, and stop commands locally.
• The above command converts all external configuration files in the projects_root to UTF-8. All external configuration files must be UTF-8 encoded if they contain multibyte characters (for example, Japanese).

Prioritize migration of specific projects

You can include a priority list when running a regular migration, or when resuming a migration after failure.

To run a migration with a priority list:

1. Prepare a text file (for example, priority.txt) containing a list of project names separated by a new line. The migration will run in the order of projects specified in the file, and the rest of the projects that are not on the list would be migrated afterward in an alphabetical order. For example:

   Project_c
   Project_a
   Project_b

2. Run the migration command with a --priority-projects-file flag and a path to the priority file:

   Important: Without a priority-projects-file, projects will be migrated in the order of project id, which is based off of the original project name and cannot be changed.

   kwservice --migrate --priority-projects-file C:/Users/priority.txt

   or

   validate service --migrate --priority-projects-file C:/Users/priority.txt

• If you modified the MariaDB configuration file located at <old_Validate_install>/config/kwmysql.ini, make the same changes to kwmysql.ini in the new installation.
  Important: Do not copy your customized configuration files into the new Validate installation. Instead, make the same customizations to the newly installed configuration files.

• If you modified the compiler mapping file located at <old_Validate_install>/config/kwfilter.conf

  Make the same changes to kwfilter.conf in the new installation.

  Important: Do not copy your customized configuration files into the new Validate installation. Instead, make the same customizations to the newly installed configuration files.

• If you added custom metrics reports to Validate, you need to edit the custom metrics report configuration file (metrics.xml). The metrics.xml file is located at: <projects_root>/config
• If you modified the memory allocation file located at <old_Validate_install>/config/java_wrappers_memory.conf, verify that you still need these modifications, and make the same changes to java_wrappers_memory.conf in the new installation.

Notes

• The metrics.xml file applies to a projects_root directory, not to an entire Validate installation. Therefore, if you have multiple projects_root directories, you will need to copy your customized metrics.xml file to each of your projects_roots.
• You need to restart the Validate Server after customizing the metrics.xml file.

Ensure that you can see your projects and builds in Validate.

If you installed a new license file, ensure that it was installed correctly by checking that the number of licenses is correct.

To migrate another projects_root, carry out the steps in this chapter again (except for installing Validate).

Summary of upgrade steps for second or later projects_root directory:

1. Prepare to upgrade.
2. Run:

   validate service --projects-root <projects_root> start --migrate
   

3. Re-create any compiler configuration files you had customized.
4. If you added custom metrics reports to Validate, edit the custom metrics report configuration file (metrics.xml).
5. Test your upgrade.

New releases of Validate normally have changes to the checker configuration to keep up with current events and respond to customer requests. These changes may mean that your checker configuration from the previous release isn't the same in the new release.

Make sure that you have the right checkers enabled to match your old configuration. After you're satisfied with your configuration, re-generate your build specification to capture the latest changes and perform your integration build analysis on unmodified source code.

If you've already run your first Validate2024.1 analysis and you're missing some issues or status changes, delete that build, reconfigure your checkers, and run a new analysis.

We recommend running your final pre-upgrade integration build analysis and your first Validate 2024.1 analysis on identical source code, and then comparing the two builds. This allows you to assess changes in the analysis engine.