Migrate your projects_root directory
Migrate your projects_root directory
You can migrate your projects_root directory and configuration settings over to your new Klocwork installation by using the kwservice --migrate command. Typically, this process involves:
- stopping your server and backing up your existing projects root folder and configuration settings
- installing the new Klocwork 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 Klocwork Static Code Analysis, 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 Klocwork 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.
To avoid losing issues, status changes or comments from the last release in your first Klocwork 2022.2 analysis run, make sure you read Before your first Klocwork integration build analysis.
Tomcat server configuration:Klocwork Static Code Analysis'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 Klocwork Static Code Analysis defaults, you can copy them from the backup, ensuring that maxPostSize is set to -1, and re-start the Klocwork Static Code Analysis 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 Klocwork version||Then follow this upgrade path|
|2022.1 latest||Klocwork 2022.2 latest|
|2021.4 latest||Klocwork 2022.2 latest|
|2021.3 latest||Klocwork 2022.2 latest|
|2021.2 latest||Klocwork 2022.2 latest|
|2021.1 latest||Klocwork 2022.2 latest|
|2020.4 latest||Klocwork 2022.1 latest --> 2022.2 latest|
Interoperability between releases
To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Server, Build, and Desktop Analysis plug-ins to the latest version of the product. Klocwork Server and Build Tools are compatible with the Desktop Analysis plug-ins within each major release.
Klocwork also provides the ability to load builds from the previous major version of Klocwork into the current version of Klocwork. For example, this means you can load Klocwork builds from any version of Klocwork 2021 into Klocwork 2022.2 without having to import or migrate data. For more information, see Cross-version support for builds.
Running two versions of the Klocwork Servers
If you will be running two sets of the Klocwork Servers, for example to test the Klocwork 2022.2 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:
- For the projects_root you want to migrate, run the following command:
kwservice --projects-root <projects_root> check
- Make note of what servers are running and what ports they are running on. After migration to the new version of Klocwork, the servers will be running on these ports.
- Stop the servers.
- To create a restore point, perform a complete backup of any projects_root directories you want to migrate. After you upgrade Klocwork, you cannot undo the upgrade. For information, see Backing up Klocwork data.
- If you customized any configuration files (such as kwmysql.ini or kwfilter.conf), back up the <server_install>/config directory.
- Start the servers.
- IMPORTANT: To reduce the time required to migrate your Klocwork data, we strongly recommend that you:
- Delete any projects from the previous version that you do not need to migrate. See kwadmin delete-project.
- 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. See kwadmin delete-build.
- Stop the servers.
- (Optional) To create a second restore point, back up the projects_root directories you have prepared for migration.
- Store the existing Klocwork license in a safe place.
- To prevent confusion, delete the old Klocwork logs from <projects_root>/logs.
Install the Klocwork Server package
Install the Klocwork 2022.2 Server package. For instructions, see Installing Klocwork.
Validate your database (mandatory)
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).
java -jar <server_install>/class/dbvalidate.jar --projects-root <projects_root>
- <server_install> is your installation directory
- <projects_root> specifies the location of the old projects root you want to validate
java -jar /local/tools/klocwork/server/class/dbvalidate.jar --projects-root /local/tools/klocwork/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.Cleanup203 --projects-root <projects_root_folder> --project <project_name> --rebuildIndex=true
Put your new license in the correct directory
If you received a new license file from Customer Support, copy it to <projects_root>/licenses.
Migrate your Klocwork data
To migrate a projects_root, run the following command from <Klocwork_2022.2_Server_install>/bin:
kwservice --projects-root <old_projects_root> start --migrate
If the projects_root migrates successfully, the Klocwork Servers start on the port numbers picked up from the migrated projects_root.
- If you imported a custom taxonomy in a previous release, you need to re-import the new taxonomy file to pick up changes. See What's new for a list of changes to the taxonomies.
- If you will be running the Klocwork Servers as Windows services, after starting the servers with the --migrate option, stop the servers with kwservice --projects-root <migrated_projects_root> stop. Then start the Klocwork 2022.2 services in Windows Services Administration.
- You can manage the Klocwork 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). External configuration files are those listed in Configuration files you can edit.
If you customized configuration or metrics files
- If you modified the MariaDB configuration file located at <old_Klocwork_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 Klocwork installation. Instead, make the same customizations to the newly installed configuration files.
- If you modified the compiler mapping file located at <old_Klocwork_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 Klocwork installation. Instead, make the same customizations to the newly installed configuration files.
- If you added custom metrics reports to Klocwork Static Code Analysis, 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_Klocwork_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.
- The metrics.xml file applies to a projects_root directory, not to an entire Klocwork 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 Klocwork Server after customizing the metrics.xml file.
Test your upgrade
Upgrade all Desktop Analysis plug-ins
To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Desktop Analysis plug-ins to the latest version of the product.
Repeat upgrade steps on other projects_root directories
To migrate another projects_root, carry out the steps in this chapter again (except for installing Klocwork).
Summary of upgrade steps for second or later projects_root directory:
- Prepare to upgrade.
kwservice --projects-root <projects_root> start --migrate
- Re-create any compiler configuration files you had customized.
- If you added custom metrics reports to Klocwork Static Code Analysis, edit the custom metrics report configuration file (metrics.xml).
- Test your upgrade.
Before your first integration build analysis using Klocwork 2022.2
New releases of Klocwork 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. See What's New for a list of updated checkers, then make any changes to your checker 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.
We recommend running your final pre-upgrade integration build analysis and your first Klocwork 2022.2 analysis on identical source code, and then comparing the two builds. This allows you to assess changes in the analysis engine. For details on improved, added, and removed checkers in this version, see What's New.