General

Environment Variables for CodeSonar

CodeSonar behavior is influenced by a number of environment variables, including CodeSonar specific variables.

This page contains information about the environment variables that are most likely to be of interest to users. Summary information about a broader set of variables is available in file env_vars.csv.

Hub

The following environment variables affect the CodeSonar hub.

CSHUB_DUMP_FILE
Value file path
Usage The hub database contents will be temporarily output to the specified file during the hub upgrade process.
Example CSHUB_DUMP_FILE=/my/preferred/dump/file/path
Notes
  • By default, file <hubdir>/UPDUMP is used, where <hubdir> is the hub directory. You only need to set CSHUB_DUMP_FILE if this location is not suitable, for example because there is not sufficient space.
  • Use the appropriate path separator for your operating system.
CSHUB_DANGER_MODE
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Set to 1 to disable many safety features of PostgreSQL, along with fsync.
Example CSHUB_DANGER_MODE=1
Notes Only recommended for throw-away hubs. Enabling danger mode will generally boost performance and reduce wear and tear on disks, but may cause unrecoverable data corruption on power failures, kernel panics, etc.
CSHUB_PASSWORD
Value string
Usage When a hub is started, the password for the hub Administrator account will be set to a new value if any of the following are true:

If CSHUB_PASSWORD is specified, the password will be set to the specified value. Otherwise, CodeSonar will prompt you for the new password.
Example CSHUB_PASSWORD=myinitialadminpasswd1234
Notes You can also change the Administrator account password on the Admin Settings page.
CSHUB_PROCESSES
Value integer
Usage When a new hub is created, the following hub process thresholds are all initialized to the value of CSHUB_PROCESSES.
Example CSHUB_PROCESSES=8
Notes
  • If CSHUB_PROCESSES is not defined, the process thresholds are initialized as follows.
    • Max Processes: 40
    • Min Idle Processes: 10
    • Max Idle Processes: 40
  • Once a hub has started, you can change hub process thresholds on the HTTP tab of the Admin Settings page.
CSHUB_SHMEM_ANON
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that hub server processes should communicate with one another using a SysV shared memory object, rather than an mmap'd file.
This is useful if the hub is stored on a file system that does not implement mmap, or has a broken implementation of mmap (e.g., NFS).
Example CSHUB_SHMEM_ANON=1
Notes
  • Use this feature if a hub starting operation fails with an error message about mmap.
  • PostgreSQL may have further difficulty with broken file systems.
  • SysV shared memoryobjects may not be pageable, and may leak if the hub is not terminated cleanly.
CSHUB_SHOW_PS_DISPLAY
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage [Non-Windows systems only] Enable to specify that hub processes should update their argv in real-time to reflect what they are currently doing (similar to the STATUS column of cshub_inspect output).
Example CSHUB_SHOW_PS_DISPLAY=1
Notes
  • May divulge sensitive information to any user on the computer.
  • This environment variable has no effect on Windows systems.
  • When this feature is enabled you can monitor what individual hub processes are working on using your usual process monitoring tools (such as top or pstree).
CSHUB_SO_REUSEADDR
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that the hub should use SO_REUSEADDR when binding the HTTP port.
Example CSHUB_SO_REUSEADDR=1
Notes Using SO_REUSEADDR is less secure, but useful for restarting the hub quickly.
CSHUB_START_INSPECT
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that the hub process should spin off an additional cshub_inspect process for its lifetime.
Example CSHUB_START_INSPECT=1
Notes
  • The status log is written to <hubdir>/hub_status_snap.log, where <hubdir> is the hub directory.
  • The process is invoked with:
    cshub_inspect <hubdir> 1000 <hubdir>/hub_status_snap.log
STIFFLM_FILE
Value file path
Usage If you are setting up a hub with a standard (i.e. not floating) license and cannot use the CodeSonar GUI to enter your license text, save the license to a file on the hub machine and set STIFFLM_FILE to the path for this file before creating the hub.
Example STIFFLM_FILE=/path/to/mylicensefile.txt
Notes
  • If you save the license text as license.txt in your CodeSonar installation directory, you do not need to set STIFFLM_FILE.
  • It is nearly always better to to set up the license interactively in the CodeSonar GUI rather than using this technique. STIFFLM_FILE is primarily useful for the case where you are automating hub creation.
  • If you have a floating license, see STIFFLM_SERVER.
  • Use the appropriate path separator for your operating system.
  • If both STIFFLM_SERVER and STIFFLM_FILE are specified, the hub license will be constructed by concatenating the two specified licenses.
STIFFLM_SERVER
Value server location, formatted as host:port
Usage If you are setting up a hub with a floating license and cannot use the CodeSonar GUI to specify the license server location (on the License Utilization page), set STIFFLM_SERVER to the location (host and port) of the floating license server before creating the hub.
Example STIFFLM_SERVER=mylicenseserver.example.com:1234
Notes
  • Most CodeSonar licenses are not floating. If you have a standard (i.e. not floating) license, see STIFFLM_FILE.
  • It is nearly always better to to set up the license interactively in the CodeSonar GUI rather than using this technique. STIFFLM_SERVER is primarily useful for the case where you are automating hub creation.
  • Use the appropriate path separator for your operating system.
  • If both STIFFLM_SERVER and STIFFLM_FILE are specified, the hub license will be constructed by concatenating the two specified licenses.

Build/Analysis

The following environment variables affect the CodeSonar build/analysis.

CODESONAR_SHOW_PS_DISPLAY
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that the CodeSonar process command lines available to process monitoring tools (such as top or pstree) will change in real time to show what the process is currently doing.
Example CODESONAR_SHOW_PS_DISPLAY=1
Notes This feature can be a security risk on a multiuser system.
CS_MASTER_WIDE_OPEN
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to instruct the analysis master not to authenticate slave processes. This is only useful if you are running slaves manually.
Example CS_MASTER_WIDE_OPEN=1
Notes Suspending authentication reduces security, so only set CS_MASTER_WIDE_OPEN if you trust every user with access to the address on which the master is listening. Depending on your hub interface and system configuration this may mean that you need to trust every user on the hub machine, or even every user on your network.
CS_SLAVE_WIDE_OPEN
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to instruct the analysis slave processes not to authenticate the analysis master. This is only useful if you are running slaves manually.
Example CS_SLAVE_WIDE_OPEN=1
Notes Suspending authentication reduces security, so only set CS_SLAVE_WIDE_OPEN if you trust every user with access to the address on which the master is listening. Depending on your hub interface and system configuration this may mean that you need to trust every user on the hub machine, or even every user on your network.
CS_VPATH_SOURCE
CS_VPATH_TARGET
Value CS_VPATH_SOURCE: directory path
CS_VPATH_TARGET: directory path
Usage Source file paths that begin with the prefix specified by CS_VPATH_SOURCE will be recorded as if they instead begin with the prefix specified by CS_VPATH_TARGET.

File paths in the CodeSonar Web GUI and in the internal representation accessed by the API will reflect this modification.
Example CS_VPATH_SOURCE=my/ugly/path/to/ProjectX/temporary/build/dir/
CS_VPATH_TARGET=/ProjectX/

If CS_VPATH_SOURCE and CS_VPATH_TARGET have these settings, source file paths that begin with my/ugly/path/to/ProjectX/temporary/build/dir/ will be recorded as beginning with /ProjectX/.
For example,
my/ugly/path/to/ProjectX/temporary/build/dir/main.c
will be recorded as
/ProjectX/main.c
Notes
  • CS_VPATH_SOURCE and CS_VPATH_TARGET are read when compiling/parsing: set them in your compiler process environment or environments to use this feature.
  • In some circumstances, it may be useful to set these variables differently for different translation units.
  • This feature can be useful if compilation takes place in temporary directories with ugly names that you would like to hide in the user interface.
  • Use the appropriate path separator for your operating system.
CSURF_HOOK_RECURSIVE
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage [C/C++ build and analysis only] Enable to specify that the compiler modeling applied to each compiler invocation in the regular software build should also be recursively applied to compiler subprocesses of the modeling process.
Example CSURF_HOOK_RECURSIVE=1
Notes This feature is only useful in a few rare cases with atypical native compiler behavior. In most cases, setting CSURF_HOOK_RECURSIVE=1 will only capture compiler invocations from within the compiler model (for example, invoking the native compiler to obtain its macro settings).
GT_DEBUG_SOURCE_PATCH
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage [C and C++ only] When enabled, the native compilation details log will contain additional debugging information about problems encountered by the source file patching module. When disabled, the log will contain a brief message for each such case.
Example GT_DEBUG_SOURCE_PATCH=1
Notes The native compilation details log will only contain information (brief or otherwise) about patch failures if the VERBOSITY setting for the build/analysis is 6 or higher.
GT_DPFE_ARCHIVE
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage When enabled, CodeSonar will archive SMT problems to the analysis directory instead of deleting them after solving.
Example GTR_DPFE_ARCHIVE=1
Notes CodeSonar uses an SMT solver to inform the Refining Warnings analysis phase.
GTHTTP_DONT_VERIFY_HTTPS_CERTS
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that HTTPS hub clients should accept all hub server certificates, regardless of validity.
Example GTHTTP_DONT_VERIFY_HTTPS_CERTS=1
Notes This feature reduces security: in most cases it is better to use the existing mechanisms for interactively inspecting and (if appropriate) approving certificates that may not be valid.
  • See TLS Certificates: Trusted Certificates for more information on establishing client trust in a certificate.
  • For automated interaction with an HTTPS hub whose certificate may not be valid, one option is to manually run codesonar hub-info once, accept the hub server certificate interactively, then use automation for subsequent operations.
GTHTTP_DONT_VERIFY_HTTPS_HOSTNAME
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that HTTPS hub clients should accept hub server certificates whose Subject Name does not match the host name in the URL.
Example GTHTTP_DONT_VERIFY_HTTPS_HOSTNAME=1
Notes This feature reduces security: in most cases it is better to use the existing mechanisms for interactively inspecting and (if appropriate) approving certificates that may not be valid.
  • See TLS Certificates: Trusted Certificates for more information on establishing client trust in a certificate.
  • For automated interaction with an HTTPS hub whose certificate may not be valid, one option is to manually run codesonar hub-info once, accept the hub server certificate interactively, then use automation for subsequent operations.
GTHTTP_ERROR_FILE
Value file path
Usage When specified, HTTP client errors will be logged to this file.
Example GTHTTP_ERROR_FILE=path/to/errorfile.txt
Notes Use the appropriate path separator for your operating system.

Various Processes

The following environment variables affect various kinds of CodeSonar process.

CODESONAR_HUB
Value hub location: one of the following forms
  • host:port
  • http://host:port
  • https://host:port
Usage Specifies a default hub location to be associated with codesonar commands.
The setting of this variable will only be used if:
  • the command does not explicitly specify a hub location,
    and
  • [command line only] the HUB_ADDRESS configuration file parameter is not defined
Example CODESONAR_HUB=http://myhub.example.com:7340
Notes See Hub Location: How CodeSonar Determines Hub Location for more information.
CS_FORCE_PRIMITIVE_STDIN
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to prevent certain interative prompts (e.g., authentication prompts) from attempting to use advanced terminal features, like non-echoed characters.
Example CS_FORCE_PRIMITIVE_STDIN=1
Notes This feature may be useful if you are experiencing terminal incompatibility problems, or if you are redirecting stdin from a file.
CS_USER_HOME
Value directory path
Usage [Non-Windows systems only] If specified, the user preferences (.csurf) directory will be a child of this directory. Otherwise, the user preferences directory will be a child of $HOME.
Example CS_USER_HOME=/home/alex/codesonarhome

With this setting, the preferences directory path will be /home/alex/codesonarhome/.csurf
Notes
DAEMONIZE_NO_DAEMON
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage [Non-Windows systems only] By default, CodeSonar uses daemon() to start launch daemon and hub processes in the background.
Enable DAEMONIZE_NO_DAEMON to specify that daemon() should not be used to start these processes.
Example DAEMONIZE_NO_DAEMON=1
Notes
  • This environment variable has no effect on Windows.
  • Enable DAEMONIZE_NO_DAEMON if you want to run launch daemon and hub processes as non-background processes, or if you dislike a particular behavior of daemon().
GT_BADFS_NOSLEEP
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage By default, CodeSonar provides an opportunity for the user to stop a command that would lead to saving files on a file system that could cause reliability or performance problems.
Enable GT_BADFS_NOSLEEP to specify that CodeSonar should skip providing this opportunity.
Example GT_BADFS_NOSLEEP=1
Notes
GT_DISABLE_IPV6
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to specify that CodeSonar should use IPv4 only.
Example GT_DISABLE_IPV6=1
Notes
GT_SKIP_GTLM_TELEMETRY
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage Enable to suppress the "Send anonymous usage statistics to CodeSecure?" prompt that appears during CodeSonar installation, and opt out of uploading anonymized usage statistics to CodeSecure.
Example GT_SKIP_GTLM_TELEMETRY=1
Notes You can opt in or out of submitting usage statistics at any time.
GTENV_NO_RESETERRORMODE
Value Set to 1 to enable; leave unset to disable.
Behavior for other values is unspecified.
Usage [Windows only] By default, CodeSonar invokes SetErrorMode() on Windows, resetting the error mode to the typical default. Problems that cause CodeSonar processes to die will therefore result in a Windows Error Reporting (WER) dialog.
Enable GTENV_NO_RESETERRORMODE to specify that the error mode should be inherited from the parent process instead.
Example GTENV_NO_RESETERRORMODE=1
Notes
  • This environment variable has no effect on Non-Windows systems.
  • Disable this feature if you want to be alerted to failures encountered when running inside process trees. In particular, Cygwin process trees typically set the mode so that many critical errors result in silent failure.
  • You may want to enable this feature if a WER dialog would cause problems (for example, because you are running CodeSonar in an automated process and cannot accommodate interaction with dialogs).

Deprecated Environment Variables

The following CodeSonar-specific environment variables are deprecated.

Deprecated Variable Notes
CS_PREPROCESS_ALWAYS Use the PREPROCESS_ALWAYS configuration parameter.
CS_PREPROCESS_IF_FAIL Use the PREPROCESS_IF_FAIL configuration parameter.

Other Documentation Related to Environment Variables

Configuration parameters CSHARP_ANALYSIS_TRUST_ENVIRONMENT Configuration parameter that specifies whether or not the C# taint analysis should trust data that originates from the environment or from system properties, rather than treating it as tainted.
  DISABLED_TAINT_KINDS Configuration parameter that specifies a set of taint kinds that should be ignored by the C/C++ taint analysis; these taint kinds include environment taint.
  FORCE_ENVIRONMENT Configuration parameter that specifies whether or not to prevent the software build system (for example, make) from writing over environment variables necessary for proper process hooking on POSIX systems.
  JAVA_ANALYSIS_TRUST_ENVIRONMENT Configuration parameter that specifies whether or not the Java taint analysis should trust data that originates from the environment or from system properties, rather than treating it as tainted.
Warning Classes Tainted Environment Variable A value that may have network taint is used to set an environment variable.
Compiler Models Many compiler models make use of environment variables that are used by the corresponding native compiler.
$CSONAR Various sample command line examples in this manual use $CSONAR to indicate the CodeSonar installation directory. CodeSonar does not automatically set the CSONAR environment variable, but you can set it yourself for convenience.
  • If you have defined environment variable CSONAR to the location of the CodeSonar installation directory, you can use $CSONAR directly in your command lines. On Windows systems, use %CSONAR% in place of $CSONAR.
  • If you don't want to use environment variables, replace $CSONAR with the path to your CodeSonar installation directory before using the command lines.