Create and Install an Analysis Data Server on Microsoft Windows

This page describes how to set up an 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.

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

The instructions below will assume that you are using PowerShell. Many of these tasks can also be performed with a Windows Command Prompt, but you will need to be sure to substitute appropriate syntax and commands. In particular, PowerShell variables are prefixed by a $ character, but Command Prompt variables are enclosed by % characters.

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

Prerequisites

There are three stages:

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 or a virtual machine,
    • 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.
    • 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 analysis data service processes.

    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. When you create the CodeSonar launch daemon you will provide a "quota" to help manage disk space use.

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

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

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

  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.

C. Start a remote analysis launch daemon

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

  2. Start the CodeSonar launch daemon using the Powershell code below.

    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.
    CODESONAR_DATA The analysis data directory you created in part B.
    CODESONAR_ANALYSIS_DATA The home directory for your launch daemon: should be a subdirectory of CODESONAR_DATA. Data for each analysis managed by the launch daemon will be stored under a subdirectory of this directory. The launch daemon will be responsible for creating this directory.
    CODESONAR_ANALYSIS_DATA_MAX_MB The maximum permitted size of CODESONAR_ANALYSIS_DATA.
    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. 
    $CSONAR="C:\Program Files\GrammaTech\CodeSonar"
$CSONAR_HUB="https://codesonar.example.com:7340"
$CSONAR_HUBUSER="cshub_ci"
$CODESONAR_DATA="C:\ProgramData\CodeSonar"
$CODESONAR_ANALYSIS_DATA="$CODESONAR_DATA\AnalysisData"
$CODESONAR_ANALYSIS_DATA_MAX_MB=100000
$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 `
    -launchd-home $CODESONAR_ANALYSIS_DATA `
    -launchd-quota $CODESONAR_ANALYSIS_DATA_MAX_MB `
    $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.

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

Disk management

The data stored on your analysis data server may reach the maximum permitted size you specified when you started the server.

You can delete unwanted analysis data manually from the CodeSonar GUI. You can also configure your hub to automatically delete data from older analyses, using custom criteria to define "older".

See the CodeSonar manual for more information:

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 the first time 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" `