Migrate your projects_root directory

You can migrate your projects_root directory and configuration settings over to your new Validate installation by using the validate service --migrate command. Typically, this process involves:

  • stopping your server and backing up your existing projects root folder and configuration settings
  • installing the new Validate server package by specifying the existing projects root folder, server, and port settings
  • re-validating your database
  • testing your installation

Before you begin

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.

If you're using Validate version Then follow this upgrade path
2024.2 latest Validate 2024.3 latest
2024.1 latest Validate 2024.3 latest
2023.4 latest Validate 2024.3 latest
2023.3 latest Validate 2024.3 latest
2023.2 latest Validate 2024.3 latest
2023.1 latest Validate 2024.3 latest
2022.4 latest Validate 2024.3 latest
2022.3 latest Validate 2024.3 latest
2022.2 latest Validate 2024.3 latest

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.3 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.3 Servers while users continue to access your existing servers, you must run them on different projects_root directories (and set the ports appropriately).

Prepare to upgrade

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.
    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 Server package

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

Validate your database (mandatory)

Using the 2023.1-2024.2 versions of the dbvalidate cleanup tool can result in data loss. If you run a database validation prior to upgrading and there are errors displayed, please open a support ticket.

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.

Put your new license in the correct directory

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.

Migrate your Validate data

Since using the 2023.1-2024.2 versions of the dbvalidate cleanup tool can result in data loss, it is not recommended to run dbvalidate or dbvalidate cleanup. When upgrading from a previous version, it is suggested that you migrate using the documented procedure. If an issue arises after the upgrade, please raise a support ticket.
If your previous Validate Server was using a FlexLM license, ensure the license host and license port settings point to a Reprise server before starting migration, for example:
<path to old installation>/kwservice --projects-root <old_projects_root> stop
<path to installation>/kwservice --projects-root <old_projects_root> set-service-property license host <reprise server host>
<path to installation>/kwservice --projects-root <old_projects_root> set-service-property license port <reprise server port>

To migrate a projects_root, run the following command from <Validate_2024.3_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.3 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).

Exclude individual projects from migration

You can specify projects to exclude in the migration.

To run a migration with an excluded projects list:

  1. Prepare a text file (for example, excluded.txt) containing a list of excluded project names separated by a new line. For example:

    Project_1
    Project_2
    Project_3
  2. Run the migration command with an --exclude-projects-file flag and a path to the excluded file:

    kwservice start -r <project_root_dir> --migrate --exclude-projects-file C:/Users/excluded.txt
    validate service start -r <project_root_dir> --migrate --exclude-projects-file C:/Users/excluded.txt

Projects in the excluded list will not be migrated, and will appear in the migrated projects list in a "disabled" state.

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:

    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 start -r <project_root_dir> --migrate --priority-projects-file C:/Users/priority.txt

    or

    validate service start -r <project_root_dir> --migrate --priority-projects-file C:/Users/priority.txt

Resume migration for inactive projects

If projects failed to migrate due to errors or were listed in the excluded projects list, they will assume an inactive state after the migration is completed.

To resume migration for inactive projects:

  1. Fix the errors in the project, or remove it from the excluded projects list.

  2. Without stopping the server, rerun migration:

    kwservice --migrate or validate service --migrate

If you customized configuration or metrics files

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

Test your upgrade

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.

Repeat upgrade steps on other projects_root directories

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.

Before your first integration build analysis using Validate 2024.3

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.3 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.3 analysis on identical source code, and then comparing the two builds. This allows you to assess changes in the analysis engine.