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 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.
    In the hub GUI:

    1. Click Settings in the quick navigation menu at top right.
      The hub Settings page will open.
    2. Select the Other Links tab.
    3. Click the Analysis Cloud link.
      The hub Analysis Cloud page will open.
    4. Click the Create New Launchd Group link (under the page heading) and use the form to create a new launchd group.
      • These instructions 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.
    In the hub GUI:

    1. Go back to the hub Settings page.
    2. Select the User Administration tab.
    3. Click the Create Account link.
      The hub Create Account page will open.
    4. Use the Create Account form to create a new hub user account.
      • 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.

  2. Log in to the host machine as a user with root access.

    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.

    The user and group IDs are specified in this example since it is often helpful to customize the numbers, however it is possible to omit the UID and GID parameters in the groupadd and useradd commands if you want to let the system decide the ID numbers automatically.

    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-8.0p0.20231117-x86_64-pc-linux.tar.gz).

    2. Extract the archive.

      mkdir -p /opt/codesecure
cd /opt/codesecure
tar -xzf /path/to/codesonar-8.0p0.20231117-x86_64-pc-linux.tar.gz

    3. Make a version-independent symlink so that CodeSonar command is easier to find in pipeline scripts.

      ln -s codesonar-8.0p0 codesonar

    4. Activate the installation.

      codesonar/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 CodeSonar launch daemon.

    Script variables. You may need to adjust one or more variable settings before executing the script.

    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.

    Script. Adjust variable settings as described in the table above, then execute this script to 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/codesecure/codesonar-8.0p0
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 GitHub pipeline to perform CodeSonar analysis, go on to step C to create and install a workflow 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.

    Script variables. You may need to adjust one or more variable settings before executing the script.

    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.

    Script. Adjust variable settings as described in the table above, then execute this script to generate the certificate and private key.

    CSONAR=/opt/codesecure/codesonar
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

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