Create and Install an Analysis Data Server on Linux

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 to set up a separate analysis data server.

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

Prerequisites

Overview

There are three stages:

A. Prepare the hub

  1. Log in 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.
    • It will need plenty of disk space where you can store analysis data files.

  2. Log in to the host machine as root.

    The next few steps assume that you have super user privileges. Depending on your system you may need to use sudo to execute some of the commands.

  3. Create a new CI user account. This account will run the CodeSonar launch daemon process.

    These instructions will assume that the CI user name is csonar_ci.

    CI_USER_UID=1001
CI_USER=csonar_ci
CI_USER_GID=1001
CI_USER_GROUP=csonar_ci
CI_USER_HOME=/home/$CI_USER

groupadd -g $CI_USER_GID $CI_USER_GROUP || true
useradd -g $CI_USER_GROUP -u $CI_USER_UID -d $CI_USER_HOME -ms /bin/bash $CI_USER

  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.

    CI_USER=csonar_ci
CI_USER_GROUP=csonar_ci
CODESONAR_DATA=/srv/codesonar

mkdir -p "$CODESONAR_DATA"
chown $CI_USER:$CI_USER_GROUP "$CODESONAR_DATA"

  5. Install CodeSonar.

    1. Download the CodeSonar install archive (e.g. codesonar-7.3p0.20230330-x86_64-pc-linux.tar.gz).

    2. Extract the archive.

      mkdir -p /opt
cd /opt
tar -xzf /path/to/codesonar-7.3p0.20230330-x86_64-pc-linux.tar.gz

    3. Activate the installation. 

      codesonar-7.3p0/codesonar/bin/codesonar activate

      You will be prompted to accept the CodeSonar license.

C. Start a remote analysis launch daemon

  1. Log in to the host machine as your CI user (csonar_ci).

  2. Start the 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.
    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.

    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=/opt/codesonar-7.3p0
CSONAR_HUB=https://codesonar.example.com:7340
CSONAR_HUBUSER=cshub_ci
CODESONAR_DATA=/srv/codesonar
CODESONAR_ANALYSIS_DATA=$CODESONAR_DATA/analysis_data
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.

  3. Make sure the launch daemon is restarted 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=/opt/codesonar-7.3p0
CSONAR_HUB=https://codesonar.example.com:7340
CODESONAR_DATA=/srv/codesonar
CSONAR_CERTDIR=$CODESONAR_DATA/certificates
CSONAR_HUBUSER=cshub_ci
CSONAR_HUBCERT=$CSONAR_CERTDIR/$CSONAR_HUBUSER.cert
CSONAR_HUBKEY=$CSONAR_CERTDIR/$CSONAR_HUBUSER.key

# If the directory does not already exist, run "mkdir $CSONAR_CERTDIR" first.

$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" \