Create and Install a Relocating Analysis Data Server on Microsoft Windows (CodeSonar 7.2 and earlier)

This page describes how to set up a relocating analysis data server to manage your CodeSonar analysis files after the analysis has completed. The analysis data server will store these files and use them to service hub requests for information such as source file listings and procedure-granularity metrics.

These instructions are designed for use with CodeSonar 7.2 and earlier. If you are using CodeSonar 7.3 or later, we recommend that you use a standard analysis data server in combination with codesonar analyze -remote-archive instead.

If you are using CodeSonar SaaS, or if your hub already has suitable associated remote analysis launch daemons, you do not need to set up a separate analysis data server.

We also provide instructions to create and install a relocating analysis data server on other systems:

• Linux (without Docker)
• Linux with Docker

Prerequisites

• A CodeSonar hub.
• A suitable machine for running the analysis data server.

Overview

There are three stages:

• A. Prepare the hub
• B. Prepare the analysis data server host machine
• C. Start a remote analysis launch daemon and a GitLab Runner instance

A. Prepare the hub

1. Log on to your hub as Administrator, or as another user with administrative privileges.

2. Create a new launchd group to contain the launch daemons that you will create for your analysis data server.

   For details, see the manual: Settings > Other Links > Analysis Cloud > Create New Launchd Group.

   The steps below will assume that the launchd group path name is '/analysis-data-server'.

3. Create a hub user account that you can use to run the launch daemons and associated pipeline jobs. Make sure the user has sufficient permissions: with factory settings, it is sufficient to assign the User and Enabled roles

   These instructions will assume that the hub user name is cshub_ci.

B. Prepare the analysis data server host machine

1. If you have not already done so, identify a suitable host machine for the analysis data server.

   • This can be a physical machine, a virtual machine, or a container.
   • It will not need to listen on any ports, and does not need a stable host name.
   • It will make outgoing network connections to your CodeSonar hub and to your GitLab server.
   • It will need plenty of disk space where you can store analysis data files.

2. Log in to the new host machine as Administrator.

   The next few steps assume that you have Administrator privileges.

3. Create a local Windows user account to run pipeline job commands.

   We will refer this new CI user account as the "CI user account" or $DATA_CI_USER in the subsequent instructions.

4. Create a base directory for saving analysis data.

   Analysis data can take plenty of space depending on the size of your code. You will need to clean up old data periodically using the Windows Task Scheduler or similar.

   For example, create a directory at C:\ProgramData\CodeSonar.

   The following instructions will refer to this directory as $DATA_ROOT_DIR.

5. Make sure that your new Windows user account ($DATA_CI_USER) has write access on the directory you just created ($DATA_ROOT_DIR).

6. Install CodeSonar.

   1. Download the CodeSonar Windows installer (e.g. codesonar-7.3p0.20230331-x86_64-pc-win64.exe).

      Make sure you download the correct installer for your operating system: there are both 32-bit and 64-bit versions.

   2. Execute the installer to install CodeSonar.

      Make a note of the directory where you have installed CodeSonar. We will refer to this directory as $CSONAR.

7. Install Git.

   Although you won't use Git for analysis data server tasks, it is required by the GitLab Runner.

   Git is available for download from https://git-scm.com.

8. Download and install GitLab Runner.

   Official instructions: https://docs.gitlab.com/runner/install/.

   Save the gitlab-runner.exe executable to an appropriate directory path on your machine.

   We will register the runner with your GitLab instance in the steps that follow. The remainder of these instructions will refer to the gitlab-runner.exe install location as $CI_RUNNER.

C. Start a remote analysis launch daemon and a GitLab Runner instance

1. Log in to the analysis data server machine as $DATA_CI_USER.

2. Register the GitLab Runner instance.

   The runner instance must be registered exactly once. If the host machine is restarted, the runner will not need to be re-registered. Note that you can have many runners on a single machine, but each runner must have a separate home directory.

   You will need to modify some or all of the variable settings.

   Variable	Setting
   CI_RUNNER	Your GitLab Runner binary.
   CI_SERVER_URL	GitLab server URL.
   CI_RUNNER_REG_TOKEN	Provided by your GitLab site under the "CI/CD" Runner settings.
   CI_RUNNER_DESCRIPTION	Name of runner to display in GitLab UI.
   CI_RUNNER_TAGS	Used by the pipeline to identify the runner. In this example, the tags "Windows" and "MSVC" indicate that this runner has Microsoft Visual C++ installed on a Windows platform.
   CI_RUNNER_HOMEDIR	Base directory where runner files should be stored on the local machine.
   CI_RUNNER_WORKDIR	Directory where runner will execute jobs.
   CI_RUNNER_CONFIGDIR	Directory where runner configuration files will be saved.
   CI_RUNNER_CONFIG	Path to runner configuration file. This file stores the runner instance settings.

   $CI_RUNNER="$Env:ProgramFiles\GitLab\gitlab-runner"
   $CI_SERVER_URL="https://gitlab.example.com"
   $CI_RUNNER_REG_TOKEN="abc123def"
   $CI_RUNNER_DESCRIPTION="windows_ci_runner_01"
   $CI_RUNNER_TAGS="Windows,codesonar_analysis_server"
   $CI_RUNNER_HOMEDIR="$Env:USERPROFILE\gitlab-runner_01"
   $CI_RUNNER_WORKDIR="$CI_RUNNER_HOMEDIR\work"
   $CI_RUNNER_CONFIGDIR="$CI_RUNNER_HOMEDIR\config"
   $CI_RUNNER_CONFIG="$CI_RUNNER_CONFIGDIR\config.toml"
   
   mkdir $CI_RUNNER_CONFIGDIR
   mkdir $CI_RUNNER_WORKDIR
   
   & "$CI_RUNNER" register `
       --config $CI_RUNNER_CONFIG `
       --non-interactive `
       --url $CI_SERVER_URL `
       --registration-token $CI_RUNNER_REG_TOKEN `
       --description $CI_RUNNER_DESCRIPTION `
       --tag-list $CI_RUNNER_TAGS `
       --executor shell `
       --shell powershell `
       --output-limit 10000
   

3. Start the CodeSonar launch daemon.

   You will need to modify some or all of the variable settings.

   Variable	Setting
   CSONAR	The path to your CodeSonar installation.
   CSONAR_HUB	The location of your CodeSonar hub (protocol://host:port).
   CSONAR_HUBUSER	The hub user account you created in part A.
   CSLAUNCHD_GROUP	The launch daemon group you created in part A.
   CSLAUNCHD_KEY	A unique identifier to distinguish this launch daemon from any others you may wish to start on the analysis data server.

   The following command will start a launch daemon with password-based authentication. If you prefer to use certificate-based authentication, you will need to modify this step.

   $CSONAR="C:\Program Files\GrammaTech\CodeSonar"
   $CSONAR_HUB=https://codesonar.example.com:7340
   $CSONAR_HUBUSER=cshub_ci
   $CSLAUNCHD_GROUP="/analysis-data-server"
   $CSLAUNCHD_KEY="remote-archive"
   
   # This command may prompt you to trust the hub's HTTPS certificate the first time you run it.
   & "$CSONAR\codesonar\bin\codesonar" install-launchd `
      -auth password -hubuser $CSONAR_HUBUSER `
      -launchd-group $CSLAUNCHD_GROUP `
      -launchd-key $CSLAUNCHD_KEY `
      $CSONAR_HUB
   

   • You will be prompted for a password for the specified hub user account.

   • You will also be prompted for Windows credentials to authorize a Windows Service for the launch daemon.

     Running the launch daemon as a service will ensure that it is started whenever the system starts.

4. Start the GitLab Runner instance.

   You will need to arrange for the GitLab Runner to be started whenever the system starts.

   For simplicity, we show how to start a simple runner process below, but you will eventually want to install the runner as a service. The gitlab-runner program provides the runner install and runner start subcommands which can be used to create a runner service. See the GitLab documentation for more information: https://docs.gitlab.com/runner/install/windows.html.

   It is important that the same $DATACIUSER that runs the CodeSonar launchd also runs the GitLab runner service. If you use the install subcommand, be sure the service runs as your $DATACIUSER.

   The following commands will start the runner as "foreground" process in the current console. To stop the runner, press CTRL-C.

   $CI_RUNNER="$Env:ProgramFiles\GitLab\gitlab-runner"
   $CI_RUNNER_HOMEDIR="$Env:USERPROFILE\gitlab-runner_01"
   $CI_RUNNER_WORKDIR="$CI_RUNNER_HOMEDIR/work"
   $CI_RUNNER_CONFIGDIR="$CI_RUNNER_HOMEDIR/config"
   $CI_RUNNER_CONFIG="$CI_RUNNER_CONFIGDIR/config.toml"
   
   & "$CI_RUNNER" run --config $CI_RUNNER_CONFIG --working-directory $CI_RUNNER_WORKDIR
   

Next Steps

If you are setting up a GitLab pipeline to perform CodeSonar analysis, go on to step C to create and install a pipeline build runner.

Notes

Modifications for certificate authentication (HTTPS hubs only)

If you need to authenticate your launch daemon with a certificate instead of with a password in part C, make the following changes.

1. Before you start the launch daemon, generate a hub user certificate and private key.

   • If you already have a suitable hub user certificate and private key, you do not need to generate new ones. Make sure that CSONAR_HUBCERT and CSONAR_HUBKEY are set to the locations of the certificate and key, respectively, and then go on to the next step.

   Make any necessary changes to variable settings before executing.

   Variable	Setting
   CSONAR	Your CodeSonar installation.
   CSONAR_HUB	Your hub location.
   CODESONAR_DATA	The analysis data directory you created in part B.
   CSONAR_CERTDIR	The directory where your generated certificates will be saved. This directory must already exist.
   CSONAR_HUBUSER	Your hub user account. Note that the command below uses this as both the username of the account that is authorizing certificate generation and the username of the account that is the subject of the certificate.
   CSONAR_HUBCERT, CSONAR_HUBKEY	Output files for the user authentication certificate and private key, respectively. These files will become inputs to codesonar install-launchd in the following step.

   $CSONAR="C:\Program Files\GrammaTech\CodeSonar"
   $CSONAR_HUB=https://codesonar.example.com:7340
   $CODESONAR_DATA="C:\ProgramData\CodeSonar"
   $CSONAR_CERTDIR=$CODESONAR_DATA\certificates
   $CSONAR_HUBUSER=cshub_ci
   $CSONAR_HUBCERT=$CSONAR_CERTDIR\$CSONAR_HUBUSER.cert
   $CSONAR_HUBKEY=$CSONAR_CERTDIR\$CSONAR_HUBUSER.key
   
   & "$CSONAR\codesonar\bin\codesonar" generate-hub-cert `
      -foruser "$CSONAR_HUBUSER" `
      -auth password -hubuser "$CSONAR_HUBUSER" `
      -out "$CSONAR_HUBCERT" `
      -outkey "$CSONAR_HUBKEY" `
      "$CSONAR_HUB"
   

   When prompted, enter the hub user account password.

2. When you run the codesonar install-launchd command to start the launch daemon, replace

   -auth password -hubuser "$CSONAR_HUBUSER" `
   

   with

   -auth certificate -hubcert "$CSONAR_HUBCERT" -hubkey "CSONAR_HUBKEY" `
   

---