The CodeSonar Launch Daemon

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

General

The CodeSonar Launch Daemon

A launch daemon is a process that initiates CodeSonar analysis operations as instructed by a hub or build process. Most users will never interact directly with the launch daemon.

Launch daemons are securable resources. The various LAUNCHD_* permissions control access to launch daemon information. For a given role R and launch daemon L, role R may have one or more of these permissions directly assigned to L, resource-inherited from a launchd group that directly or transitively contains L, or any combination of these.

What is a Launch Daemon?
Starting a Launch Daemon
Using a Launch Daemon
Stopping a Launch Daemon
The Launch Daemon Process
Properties
Permissions
Links

What is a Launch Daemon?

A launch daemon is a process that initiates CodeSonar analysis operations as instructed by a hub or build process. Most users will never interact directly with the launch daemon.

Each instruction to the launch daemon has the following elements.

A codesonar command line.
An environment in which to execute the command.
A working directory in which to execute the command.

Each launch daemon is associated with a hub, and has an entry in the hub's analysis cloud register. Launch daemon properties are discussed below.

The remainder of this section uses "appropriate launch daemon" as a shorthand for referring to a launch daemon that is associated with the correct hub and has an identifying property tuple that matches that of the analysis of interest.

Starting a Launch Daemon

CodeSonar SaaS Note: You do not need to explicitly or implicitly start any launch daemons when using CodeSonar SaaS. Launch daemons are provided in your SaaS hub's saas launchd group.

A launch daemon is required whenever a hub is interacting with an analysis. There are several ways to start a launch daemon:

[Recommended] Directly, with the configuration tool.
Directly, with codesonar install-launchd.
Directly, in a Docker container.
Implicitly, with a standard build/analysis command.
If you have installed CodeSonar in a Kubernetes cluster, there is a launch daemon running in each of your analysis pods.
For more information, see:
- Install CodeSonar on a Kubernetes Cluster: From artifacts.codesonar.com
- Install CodeSonar on a Kubernetes Cluster: Building Your Own Images
The codesonar relocate command also implicitly starts a launch daemon.
The CodeSonar hub can start a launch daemon to fulfill a request, but only if the hub and launch daemon are running on the same logical machine and as the same user on that machine.

Important: the hub must be running before the launch daemon is started.

[Recommended] Starting A Launch Daemon with the Configuration Tool

The following main menu options in the configuration tool include steps for configuring and starting a launch daemon to communicate with the specified hub. The hub's analysis cloud register will be updated when the launch daemon connects.

Starting a Launch Daemon with codesonar install-launchd

The general form of the command line for starting a CodeSonar launch daemon is

codesonar install-launchd \
[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile] \
[-launchd-group ldgroup] [-launchd-key ldkey] [-launchd-home ldhomedir] [-launchd-quota ldquota] \
[-max-processes proclimit] [-foreground] [-no-services] [[protocol://]address:port]

Where the command components are as follows.

-no-services	(Windows only) specifies that the launch daemon should not be run as a service (see section CodeSonar as a Windows Service for more information).
-foreground	Execute the cslaunchd process in the foreground instead of spinning off a background process. If successful, the codesonar install-launchd command will run forever, or at least until the hub shuts down.
[-auth authtype], [-hubuser username], [-hubpwfile pwfile], [-hubbearerfile bearerfile], [-hubcert certfile], [-hubkey privatekeyfile]	Specify how CodeSonar should attempt to authenticate this command. For details, see Hub Authentication: Authenticated codesonar Subcommands. The username of the authorizing Hub User is recorded as a property of the launch daemon.
[-launchd-group ldgroup]	If this is a new launch daemon (that is, its identifying tuple does not correspond to an existing entry in the hub's analysis cloud register), its Parent LDGroup will be set to the launch daemon group G that is specified by ldgroup. The value of ldgroup can be either a string or an integer. string S: G is the launchd group whose LDGroup Path is S. integer I: G is the launchd group whose LDGroup ID is I. G must already exist on the hub, and the authorizing user must have LAUNCHDGROUP_ADD_CHILD permission for G. If the analysis launch daemon is not new, this option has no effect. You can change the parent launchd group for an existing launch daemon from the corresponding Launchd Group page.
[-launchd-key ldkey]	Specify the launch daemon key.
[-launchd-home ldhomedir]	Specify the launch daemon Home Directory.
[-launchd-quota ldquota]	Specify the launch daemon Space Quota: the maximum permitted size (in MB) of the Home Directory.
[-max-processes proclimit]	Specify the launch daemon process limit: either a non-negative integer, or auto.
[[protocol://]address:port]	The launch daemon will connect to the hub at this location. If protocol:// is specified, CodeSonar will only try the specified URL. In particular, if http:// is specified then CodeSonar will not try the equivalent https:// URL even if directed to do so by the hub. If protocol:// is not specified, CodeSonar will try http:// first, then redirect to the equivalent https:// URL if directed to do so by the hub. If address:port is not specified, CodeSonar will determine a hub location using the steps described in Hub Location: How CodeSonar Determines Hub Location The codesonar install-launchd command will fail without starting a new launch daemon if no hub is running at the specified location, or if a hub is running but a launch daemon with the same identifying property tuple is already connected. The hub's analysis cloud register will be updated when the launch daemon connects.

The launch daemon will be connected to the specified hub.

Starting a Launch Daemon with the Official cso/codesonar-launchd Docker Image

If you haven't already done so, obtain your artifacts.codesonar.com CLI secret.
1. Navigate to https://artifacts.codesonar.com/.
2. Sign in with your CodeSonar Support credentials.
3. Select User Profile from the menu at top right.
  Your User Profile page will open.
4. Make a note of the Username.
5. Click the copy icon on the CLI secret line to copy the CLI secret to your clipboard.
Note. Your CLI secret will expire after a month. If necessary, repeat these steps obtain a new secret from https://artifacts.codesonar.com/.
Log in to the registry.
docker login artifacts.codesonar.com

Provide your credentials when prompted.
- User name is your artifacts.codesonar.com Username.
- Password is your artifacts.codesonar.com CLI secret.
Will the launch daemon be used to manage remote-managed analyses?
- YES:
  1. Create a Docker volume.
    Use a separate volume for each launch daemon.
    
    docker volume create codesonar-launchd
  2. Run the following command to start the launch daemon.
    docker run -d https://artifacts.codesonar.com/cso/codesonar-launchd \
    -v codesonar-launchd:/home/codesonar \
    -launchd-home /home/codesonar/analysisdata -launchd-quota 81920 -max-processes auto \
    [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile] \
    [-launchd-group ldgroup] [-launchd-key ldkey] \
    [-foreground] [-no-services] [[protocol://]address:port]
    Notes:
    - See codesonar install-launchd, above, for option descriptions.
    - You can set -launchd-home to a different subdirectory of /home/codesonar/ if you prefer.
    - Set -launchd-quota to be about 80% of the amount of disk space you’re comfortable with being used to store the launch daemon Home Directory.
    - It is usually most convenient to set -max-processes auto as shown here, but you can specify a concrete value if you prefer.
- NO:
  1. Run the following command to start the launch daemon.
    docker run -d https://artifacts.codesonar.com/cso/codesonar-launchd \
    -max-processes auto \
    [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile] \
    [-launchd-group ldgroup] [-launchd-key ldkey] \
    [-foreground] [-no-services] [[protocol://]address:port]
    Notes:
    - See codesonar install-launchd, above, for option descriptions.
    - It is usually most convenient to set -max-processes auto as shown here, but you can specify a concrete value if you prefer.

Letting codesonar analyze Start a Launch Daemon Implicitly

A standard project build/analysis command of the form

codesonar analyze pfilesname [other_options] [protocol://]host:port [command]

(or its Windows build wizard equivalent) can start a launch daemon implicitly if a hub was already running at [protocol://]host:port before the build/analysis command was executed. The hub's analysis cloud register will be updated when the launch daemon connects.

Special cases:

Remote-managed analysis: the specified remote launch daemon must already be running. A remote-managed analysis will never start a launch daemon.
Foreground analysis: if the analysis command specifies the -foreground option, the analysis phase will not use a launch daemon: the analysis phase is managed directly by the analysis process.
If you perform a foreground analysis and subsequently wish to use the web GUI to view or browse code from the analysis, you will need to manually start a launch daemon as described above. Other GUI functionality, such as viewing warning reports reports for the analysis, does not require a launch daemon.

Using a Launch Daemon

There are three situations in which a launch daemon is needed.

During Results Browsing	Pages requested by the user may require results generated by a codesonar command. The hub issues the necessary command to the appropriate launch daemon.
During Build/Analysis	The analysis phase of the build/analysis is initiated by a launch daemon. If an appropriate launch daemon is not running, CodeSonar will start one.
Distributed Analyses	Launch daemons in the hub's analysis cloud register are used to start new analysis slaves and daemon slaves requested by remote-requesting masters.

The Role of the Launch Daemon in Results Browsing

If any user is viewing or browsing source code from a specific analysis on a hub, the hub must be connected to a launch daemon that is:

owned by the user who ran the analysis, and
running on the same machine as the analysis.

If no such launch daemon is running, the hub is not able to start one. The user who ran the analysis must start a launch daemon on the appropriate machine as described above.

The Role of the Launch Daemon in The Build/Analysis

The CodeSonar build/analysis uses a launch daemon to start the analysis phase, as shown in the diagram in section Build/Analysis Steps.

The Role of the Launch Daemon in Distributed Analysis

A remote-requesting master requests additional distributed slaves from the hub when it needs them; the hub then instructs each eligible launch daemon in its analysis cloud register to start a new slave. For full details, see section Distributed Analysis.

Stopping a Launch Daemon

In normal usage you will not usually need to manually stop a launch daemon.

Some hub operations require that all daemons are disconnected from the hub. The close_all hub command is provided for this use case.
If you do need to stop a launch daemon, use your standard system functionality for shutting down a process.
(Windows only) see CodeSonar as a Windows Service for additional information about managing launch daemon services.

The Launch Daemon Process

The launch daemon process is called cslaunchd.exe on Windows systems, cslaunchd otherwise. It is run as the user that executes the build/analysis (which may not be the same user as the one that started the hub).

On Windows systems the launch daemon runs as a service by default. For more information, see CodeSonar as a Windows Service.

Properties

The following table describes each of the properties of a launch daemon. The full list of properties is (in alphabetical order):

Address
Current Processes
Derived Name
Home Directory
Hub User
Installation
Key
Launch Daemon ID
LDPath

Machine
Parent LDGroup
Process Limit
Protocol Version
Space Quota
Space Used
Status
System User
System User ID

A launch daemon is always associated with a hub. Information about the launch daemon properties is managed in the hub's analysis cloud register.

Name	Description
Machine	The name of the machine on which the launch daemon is running.
Address	The IP address of the launch daemon Machine.
System User	The system user who is running the launch daemon. If the launch daemon was started explicitly from the command line, this is the system user who ran the codesonar install-launchd command. If the launch daemon was started from the configuration tool, this is the system user who invoked the configuration tool. If the launch daemon was started implicitly by the CodeSonar build/analysis, this is the system user who ran the analysis. Command line: the system user who ran the build/analysis command. Windows build wizard: the system user who invoked the wizard. If the launch daemon was started implicitly by a codesonar relocate command, this is the system user who ran that command. Note that this is a user on the launch daemon Machine, not on the hub. In particular, it does not need to match the launch daemon Hub User (although it may do so, whether deliberately or coincidentally).
System User ID	The system-assigned unique identifier of the System User. On Windows systems, this is the user SID. On non-Windows systems, it is the user UID.
Derived Name	The string sysuser@machine, where sysuser is the System User, and machine is the Machine. This string provides a somewhat human-readable identifier for use in the CodeSonar GUI; it can also be used (in combination with the Parent LDGroup path) to specify values for configuration parameters REMOTE_ANALYSIS_SLAVES_LAUNCHDS and REMOTE_DAEMON_SLAVES_LAUNCHDS. Note that it is not a unique identifier: all launch daemons with the same System User and Machine will have the same Derived Name.
Hub User	The username of the hub user account that authorized the launch daemon's connection to the hub. If the launch daemon was started explicitly from the command line, this is the hub user who authorized the codesonar install-launchd command. If the launch daemon was started from the configuration tool, this is the user that was specified in response to the corresponding tool prompt. If the launch daemon was started implicitly by the CodeSonar build/analysis, this is the hub user who authorized the analysis. If the launch daemon was started implicitly by a codesonar relocate command, this is the hub user who authorized that command. This does not need to match the launch daemon System User (although it may do so, whether deliberately or coincidentally). CodeSonar always behaves as if the Hub User has all LAUNCHD_* permissions for the launch daemon.
Installation	The absolute pathname (on Machine) of the root directory for the CodeSonar installation the launch daemon is running from.
Key	A user-specified identifying string. The Key is included in the identifying tuple in order to permit distinction between multiple launch daemons with the same Machine, System User, Hub User, and Installation. For any command that starts or is otherwise associated with a launch daemon, the launch daemon Key is determined as follows. If -launchd-key ldkey is specified in the command, Key is ldkey. If you are using the Visual Studio plug-in, you can specify the Launchd Key on the Project Properties dialog. Builds and analyses carried out through the Windows build wizard or Eclipse plug-in do not have an analogous option: use the LAUNCHD_KEY parameter as described below. Otherwise, if configuration parameter LAUNCHD_KEY is defined, Key is the value of that parameter. For build, analysis, and relocate commands, LAUNCHD_KEY may be defined in either the general template configuration file or the general project configuration file. For all other cases, LAUNCHD_KEY may be defined in the general template configuration file only. Otherwise, Key is the empty string.
Protocol Version	The protocol version for the CodeSonar installation that is running the launch daemon. A remote-requesting analysis master will only be able to obtain slaves from launch daemons with the same protocol version.
Process Limit	The maximum number of analysis slaves and daemon slaves that the launch daemon can be cloud associated with at a time: either a non-negative integer, or "auto". When a launch daemon process starts, its process limit is determined as follows. If the launch daemon is started with codesonar install-launchd and the command line includes the -max-processes proclimit option, its process limit is set to proclimit. Otherwise, if the launch daemon is started with the configuration tool, its process limit is set as specified by the user when prompted by the tool. The following configuration tool main menu options will start a launch daemon if necessary. 1 Install, connect to existing hub 2 Install, create hub Otherwise, if the launch daemon has an existing entry in the analysis cloud register, the process limit is not changed from the existing setting. Otherwise, the process limit is 0. This limit can be modified on the hub's Analysis Cloud page. For information about how the process limit is applied for distributed analyses, see Distributed Analysis: Analysis Cloud Register: Process Limit.
Current Processes	The set of analysis slaves and daemon slaves that are currently cloud associated with the launch daemon. For information about how the set is managed in distributed analyses, see Distributed Analysis: Analysis Cloud Register: Current Processes.
Status	An online/offline designation indicating whether the launch daemon is connected to the hub.
Launch Daemon ID	A unique numeric identifier for the launch daemon.
Parent LDGroup	The launchd group that directly contains the launch daemon. The Parent LDGroup for a new launch daemon (that is, a launch daemon whose identifying property tuple does not match an existing entry in the analysis cloud register) is determined as follows. If -launchd-group ldgroup is specified in the command that starts the launch daemon, Parent LDGroup is as specified by ldgroup. For full details, see the -launchd-group documentation for the the CodeSonar install-launchd command. The configuration tool will prompt you for a parent launchd group before starting a launch daemon. In the Eclipse plug-in, the equivalent functionality is provided by the Launchd Group setting in the Project Properties dialog. In the Visual Studio plug-in, the equivalent functionality is provided by the Launchd Group setting in the Project Properties dialog. The Windows build wizard does not have an analogous option: use the LAUNCHD_GROUP parameter as described below. Otherwise, if configuration parameter LAUNCHD_GROUP is defined, Parent LDGroup is the launchd group specified by that parameter. For launch daemons started implicitly for a build, analysis, or relocate command, LAUNCHD_GROUP may be defined in either the general template configuration file or the general project configuration file. For all other cases, LAUNCHD_GROUP may be defined in the general template configuration file only. Otherwise, Parent LDGroup is the root launchd group. If a launch daemon is not new, -launchd-group options and LAUNCHD_KEY definitions will be ignored: the daemon will stay in the same parent launchd group.
LDPath	Derived from the launch daemon's Parent LDGroup, System User, and Name: the full path from the hub's root launchd group to the launch daemon. The LDPath for a launch daemon L is always displayed and specified as a /-separated sequence of the form ldgrouppath/sysuser@machine, where: ldgrouppath is L.Parent LDGroup.LDGroup Path. sysuser is L.System User. machine is L.Machine. (We refer to the string sysuser@machine as the Derived Name for L.) For example, suppose we have a launch daemon L whose System User is alex, Machine is alex-w, and parent launchd group G is named Gname. If G is the root launchd group, the LDPath for L is /alex@alex-w. If G is a child of the root launchd group, the LDPath Path for L is /Gname/alex@alex-w. If G is a child of a launchd group named Fname that is itself a child of the root launchd group, the LDPath Path for L is /Fname/Gname/alex@alex-w.
Home Directory	The directory on Machine under which the launch daemon will store project analysis directories for all of the remote-managed analyses that it manages. If the codesonar install-launchd command specifies -launchd-home ldhomedir, Home Directory is ldhomedir. Otherwise, the launch daemon has no Home Directory. For a remote-managed analysis A, the analysis directory path is ald-home/aid/pfilesname.prj_files, where ald-home is the Home Directory for A.Analysis Launch Daemon aid is A.Analysis ID pfilesname is specified in the build/analysis command A launch daemon with no Home Directory cannot be the analysis launch daemon for a remote-managed analysis.
Space Quota	The maximum permitted size of the Home Directory. If the codesonar install-launchd command specifies -launchd-quota ldquota, Space Quota is ldquota MB. Otherwise, there is no bound on permitted size. If Space Used exceeds Space Quota, the launch daemon cannot be the Analysis Launch Daemon for a remote-managed analysis.
Space Used	The total disk space currently used by the Home Directory.

Identifying Property Tuple

CodeSonar uses a tuple of launch daemon properties to identify launch daemons and determine their association with build and analysis processes. The tuple properties are:

[Machine, System User, Hub User, Installation, Key]

The hub uses this tuple to uniquely identify the launch daemons connected to it. In particular, if a launch daemon stops and is later restarted, the hub will consider the new process to be 'the same' launch daemon as the previous one.

The section on distributed analysis discusses the various situations in which this tuple is used.

Permissions

CodeSonar permissions apply to launch daemons as follows.

Permissions Required

Launch daemon operations are governed by various LAUNCHD_* and LAUNCHDGROUP_* permissions.

Operation	Permissions Required
Start a launch daemon	Requirements depend on whether or not the launch daemon is already present in the hub's analysis cloud register. YES: The authenticated user authorizing the command that (implicitly or explicitly) starts the launch daemon must match the launch daemon Hub User. No additional permissions are required in this case. NO: The launch daemon will need to be registered as a child of an existing launchd group G, which requires LAUNCHDGROUP_ADD_CHILD permission for G. Launch daemon tokens. Once the launch daemon is authorized, the authorization persists indefinitely. To manage this persistent authorization, CodeSonar stores a special launch daemon token in the user certificates and keys directory. Each launch daemon token applies to a single launch daemon, as specified by its identifying property tuple and associated hub. The token filename has the following form. <hubmachine>_<hubport>.<tuplehash>.cslaunchd.txt Once the launch daemon is authorized, it will remain authorized even if the password or permissions of the authorizing user are changed. In general, we do not recommend deleting launch daemon tokens. In particular, a launch daemon service will only be able to restart if its corresponding token is present. If you delete a token accidentally, execute one of the commands that implicitly or explicitly starts a launch daemon. CodeSonar will create a new token when the launch daemon has started and connected to the hub.
Automatically add an analysis slave or daemon slave by requesting from launch daemon L (remote-requesting; local-requesting)	The authenticated user authorizing the analysis command must have LAUNCHD_START_SLAVE permission for L.
Manually add an analysis slave or daemon slave from launch daemon L	Manually adding an analysis slave or daemon slave is only possible when environment variable CS_MASTER_WIDE_OPEN is set to 1 in the environment in which the analysis master is running. When this variable is defined, permissions are not checked, and the master will not authenticate slaves. See Parallelism In CodeSonar: Manually Started Slaves for a full discussion.
Change the process limit for launch daemon L	LAUNCHD_EXISTS and LAUNCHD_WRITE for L.
View/modify launch daemon settings	Permission requirements for pages that provide access to launch daemon information are detailed in the GUI reference: Settings Analysis Cloud/Launchd Group Analysis Cloud Active Jobs Launchd Group Role-Permissions

Permissions Assigned

Suppose a new launch daemon L is started in launchd group G, authorized by Hub User U. No explicit role-permissions are initially applied to L, but the following permissions will apply through other means.

All LAUNCHD_* role-permissions that (implicitly or explicitly) apply to G will implicitly apply to L.
CodeSonar will behave as if U has all LAUNCHD_* permissions for L, even if U's assigned roles would not otherwise confer those permissions.

There are initially no other role-permissions applied to L. To add further permissions, use the Resource Role-Permissions page for L (or G, any of G's ancestor Launchd Groups).