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.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

Starting A Hub

This section describes the method for starting a (primary) CodeSonar hub.

Every CodeSonar analysis needs a hub for the results. If a hub is not already running, one must be started before the analysis command is issued.

Preliminaries

Before starting a hub:

  1. Determine a hub directory and hub location for your hub.
  2. Make sure your system user account and machine are ready to start a hub.
    1. Determine whether you have sufficient system user permissions to run software that listens on any port.
      If not, a system administrator will need to start the hub.
    2. Make sure you are logged in as an ordinary user: the hub cannot be run as root.
    3. You will need to expand the shared memory. See Running a Hub Under Linux.
  3. Determine whether you need to set the Administrator password.

Command Line Details

The following is the general form of the command line for starting a CodeSonar primary hub.
(For a satellite hub, see Satellite Hubs: Command Line Details.)

codesonar hub-start [-setadminpw] [-allow-satellites] [-https-redirect] \
[-tls-server-certkey {certpath|disable}] [-tls-client-certkey {certpath|disable}] \
[-permissive] [-no-services] directory [interface:port]

Where the command components are as follows.

-setadminpw Specifies that you wish to set a password for the hub Administrator account. CodeSonar will prompt you for the new password (unless environment variable CSHUB_PASSWORD is defined, in which case the new password will be set to the value of that variable). This will also set the password for special PostgreSQL user cshubuser.

If you are starting an entirely new hub, or the hubdir/dbpass file is missing for any other reason, CodeSonar will always behave as if you have specified -setadminpw.

Changing the Administrator password by this method does not delete existing user sessions associated with the Administrator account. If you want to delete these sessions, you can do so from the User Sessions page for Administrator.
-allow-satellites Permit satellite hubs to connect to this hub.
This is equivalent to setting Allow satellite hubs? in the HTTP tab of the Settings page.

If you don't specify this option, behavior depends on whether or not the hub is new:

  • New hub: satellite connections are not permitted.
  • Existing hub: the previous behavior is retained.
-https-redirect

For HTTPS hubs, specifies that when a user attempts to connect to the hub using an HTTP URL, the hub should redirect the connection to an URL that differs only by specifying https rather than http as the protocol. For example, if a user attempts to connect to http://myhub:7340, the hub will redirect them to https://myhub:7340.
This is equivalent to setting HTTP to redirect to the equivalent HTTPS URL in the Configure HTTPS page.

For non-HTTPS hubs, this option has no effect.

If you don't specify this option, behavior depends on whether or not the hub is new:

  • New hub: http→https redirection is not enabled.
  • Existing hub: the previous behavior is retained.
-tls-server-certkey {certpath|disable} Enable/disable HTTPS on the hub. This is equivalent to enabling/disabling HTTPS in the Configure HTTPS page.

If a command line contains multiple occurrences of -tls-server-certkey, the last occurrence is used.

If you don't specify this option, behavior depends on whether or not the hub is new:

  • New hub: HTTPS disabled; no hub server certificate configured.
  • Existing hub: the previous behavior (including hub server certificate, if any) is retained.
-tls-client-certkey {certpath|disable} Enable/disable certificate-based user authentication on the hub, if the hub has HTTPS enabled.
Setting HTTPS enabled HTTPS disabled
-tls-client-certkey certpath Enable certificate-based user authentication; set the hub client authentication certificate to the certificate located at certpath. See Configure HTTPS: Client Authentication Certificate Configuration for file format and content requirements. The hub-start command will fail with an error message
-tls-client-certkey disable Disable certificate-based user authentication; discard any existing hub client authentication certificate. -tls-client-certkey disable is ignored.

This is equivalent to enabling/disabling certificate-based authentication in the Configure HTTPS page.

The hub is considered to have HTTPS enabled if one of the following is true.

If a command line contains multiple occurrences of -tls-client-certkey, the last occurrence is used.

If you don't specify this option, behavior depends on whether or not the hub is new:

  • New hub: certificate-based user authentication disabled; no hub client authentication certificate configured.
  • Existing hub: the previous behavior (including hub client authentication certificate, if any) is retained.
-permissive Behavior depends on whether or not the hub is new.
  • New hub: the built in Anyone role is assigned a broader range of permissions, consistent with the default behavior in CodeSonar 7.1 and earlier. Because all users have the Anyone role, including special user Anonymous, this will allow users to perform operations such as analyzing a project and viewing analysis results without authentication.
    For full details of default role-permission assignments with and without this option, see Default Role-Permissions and Immutable Role-Permissions.
  • Restarting an existing hub with upgraded CodeSonar (and therefore database upgrade): for resources that were present before the upgrade, the built in Anyone role retains its existing permissions. For new resources added by the upgrade, Anyone is assigned the broader set of default permissions described in Default Role-Permissions and Immutable Role-Permissions.
  • Restarting existing hub with no database upgrade: this option has no effect.
-no-services (Windows only) specifies that the hub should not be run as a service (see section CodeSonar as a Windows Service for more information).
directory is the path to the directory where the hub files will be created (the "hub directory").
  • If directory is located under the CodeSonar installation directory, the hub-start command will fail.
  • If directory does not already exist, CodeSonar will create it and populate it with the appropriate hub files.
  • If directory exists and is empty, CodeSonar will populate it with the appropriate hub files.
  • If directory exists and is nonempty, it must contain appropriate hub files (from a previous invocation of codesonar hub-start). In this case, the hub will be started with the settings and database that are already stored in directory. If the appropriate files are not present, the hub-start command will fail.
interface:port Specifies the hub location.
  • interface is the network interface on which the hub will listen.
  • port is the port on interface on which the hub will listen.
If it is not specified on the command line, CodeSonar will attempt to determine a location as described in the Hub Location section. If no location can be determined, the hub start command will fail.
authentication note Any authentication options are ignored. (Only satellite hubs require authorization to start.)

Start The Hub

The process for starting a primary hub is as follows.
(For a satellite hub, see Satellite Hubs: Starting a Satellite Hub.)

  1. Construct and issue a suitable hub-start command.
    For example, suppose you want to start an entirely new hub on port 8002 of your local Windows machine with hub files saved in the my_hub subdirectory of your working directory, and you do not want to run the hub as a Windows service.
    Then the hub-start command would be:
    codesonar hub-start -no-services my_hub [::]:8002
    (See the IPv4 note if your system does not support IPv6 addresses.)
  2. If you are starting an entirely new hub, or are restarting a hub and have specified the -setadminpw option, CodeSonar will prompt you to set a password for the Administrator account (unless environment variable CSHUB_PASSWORD is defined).
    1. At the prompt, enter the new password you have selected for the Administrator account.
    2. Re-enter the new password at the confirmation prompt.
  3. If you haven't already accepted the CodeSonar license, CodeSonar will print the text of the license agreement and ask you to accept it.
    1. You will need to accept the license agreement before proceeding.
      If your window history is not long enough to scroll over the entire text of the license agreement, you can examine the agreement file at $CSONAR/EULA.txt.
  4. If you haven't already specified whether you want to upload anonymized usage statistics to CodeSecure, CodeSonar will ask "Send anonymous usage statistics to CodeSecure?" now.
    1. Press y to opt in; n to opt out.
    You can change this setting at any time.

Troubleshooting

See Starting a New Hub: Troubleshooting.

IPv4 Note

If your system does not support IPv6 addresses, use IPv4 to specify addresses instead. For example, specify 0.0.0.0 instead of ::.

The next step is to check that the hub has started succesfully.

  1. Check that the hub is installed correctly with a codesonar hub-info command:
    codesonar hub-info interface:port
  2. If CodeSonar prompts you for user name and password, enter the username and password for Administrator (or another hub user account with G_HUB_INFO permission).
  3. If the hub is running at interface:port, CodeSonar will print a table of hub information. If the values in the table are as you expected, the hub should be running correctly.
  4. If this is a new hub, follow the instructions in Hub Setup: Hub Configuration to configure it.

Other Hub Sections

 

To report problems with this documentation, please visit https://support.codesecure.com/.