Satellite Hubs

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.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

Satellite Hubs

Every CodeSonar hub is either a primary hub or a satellite hub. This section describes the properties of satellite hubs and provides directions for using them.

Note: satellite hubs can only be set up by the Administrator account (it is not sufficient to use another account with the Administrator role), and can only be attached to primary hubs that are using the database shipped with CodeSonar.

About Satellite Hubs
Command Overview
Starting
Command Line Details
Shutting Down
Troubleshooting
Other Hub Sections

About Satellite Hubs

Every CodeSonar hub is either a primary hub or a satellite hub:

primary hub	A primary hub has its own hub database, located in its hub directory.
satellite hub	A satellite hub exists with respect to a primary hub - instead of having its own hub database, it uses the hub database belonging to the associated primary hub. Satellite hubs have the same functionality as primary hubs, except that: The Administrator password cannot be changed from a satellite hub - only from the primary hub. Changing the Administrator password from the primary hub will cause its satellites to shut down. The Allow satellite hubs? and Use TLS for database communication? settings cannot be modified from a satellite hub - only from the primary hub. Third-party authentication services that apply across all hubs can only be configured on the primary hub.

primary hub

A primary hub has its own hub database, located in its hub directory.

satellite hub

A satellite hub exists with respect to a primary hub - instead of having its own hub database, it uses the hub database belonging to the associated primary hub.

Satellite hubs have the same functionality as primary hubs, except that:

The Administrator password cannot be changed from a satellite hub - only from the primary hub.
Changing the Administrator password from the primary hub will cause its satellites to shut down.
The Allow satellite hubs? and Use TLS for database communication? settings cannot be modified from a satellite hub - only from the primary hub.
Third-party authentication services that apply across all hubs can only be configured on the primary hub.

diagram: primary and satellite hubs and hub directories

Satellite hubs are useful for distributing hub load across multiple computers. The hub database (PostgreSQL) still runs exclusively on the primary hub machine, but the web server processes (cshub) can be spread across arbitrarily many machines.

Starting a Satellite Hub

Follow these instructions to set up a satellite hub, including configuring the associated primary hub to accept satellite connections.

Before You Start

Identify the primary hub you want to use.
- Determine the location and hub directory of the primary hub.
  We will refer to these as primhost:primport and hubdir, respectively.
Decide where you want to run the satellite hub.
Note that even though the satellite hub uses the hub database belonging to the primary hub, it still has its own hub directory. The satellite hub directory is used primarily for storing configuration information.
- Select a suitable location and hub directory for the satellite hub.
  We will refer to these as sathost:satport and sat_dir, respectively.
  In some cases a user might not be permitted to run software that listens on any port. In such cases, an administrator will need to start the hub.
Low network latency between the primary and satellite hubs is more important to overall performance than low network latency between a (primary or satellite) hub and an HTTP hub client (such as a web browser accessing the CodeSonar Web GUI, or the CodeSonar build/analysis). If you have a choice between putting a slow connection between primary and satellite hub, and putting it between a hub and an HTTP client, the latter is better.
Make sure you have credentials for a primary hub account for a primary hub user account with G_HUB_INFO permission.
These credentials are used to authenticate the early stages of the satellite hub-start process. You can use Administrator credentials, since you will need to know them anyway (see the next step), but in some cases you will be able to use a less-privileged user account.
Make sure you have the password for the Administrator account on the primary hub.
You must provide this in order to authorize the database operations involved in starting satellite hub.
(Note in particular that it is not sufficient to use another account with the Administrator role.)

Set Up And Start The Satellite Hub

Is the primary hub running?
- NO: Start it now, using the -allow-satellites option to specify that satellite hubs are permitted:
  codesonar hub-start -allow-satellites [-no-services] hubdir primhost:primport
- YES: Make sure that satellite hubs are permitted:
  1. Update the hub settings.
    - Navigate to the HTTP tab of the Settings page.
    - If the Allow satellite hubs? checkbox is not already selected, click to select it.
    - Click the Update button.
  2. Shut down the primary hub, then start it again to allow the changes to take effect.
    codesonar hub-stop primhost:primport
    codesonar hub-start [-no-services] hubdir primhost:primport
    (You may be prompted for hub user account credentials to authenticate the hub-stop command.)
    You have already configured the primary hub to permit satellite hubs, so you don't need to specify -allow-satellites.
    Depending on your local configuration, your machine may display a security alert because the restarted hub is now allowing satellite connections to its database.
  3. Are you satisfied that your system security will prevent unwanted satellite hub connections?
    - YES: dismiss the alert and continue to the next step.
    - NO: change the hub settings to disallow satellite hubs, then stop (or start over with a different primary hub).
      - Go to the HTTP tab of the Settings page, click the Allow satellite hubs? checkbox to deselect it, and click the Update button.
Issue the hub-start command for the satellite hub.
(Full details of the command line for starting a satellite hub are provided below.)
- On the satellite hub machine, run the following.
  codesonar hub-start [-no-services]
  [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
  -satellite-of [protocol://]primhost:primport sat_dir sathost:satport
  - Use the authorization options to provide credentials for a primary hub user account with G_HUB_INFO permission. These credentials are used to authenticate the early stages of the satellite hub-start process.
  - sat_dir must be located outside the CodeSonar installation directory, otherwise the hub-start command will fail.
When prompted, provide the Administrator password for the primary hub.
If prompted to do so, copy the primary hub's TLS certificates and keys to the satellite hub directory.
You will only be prompted to do this if the primary hub is configured to use TLS for database communication. Otherwise, you can skip this step.
1. Copy the following files to sat_dir/:
  - hubdir/client.crt
  - hubdir/client.key
  - hubdir/root.crt
2. Set access permissions on the copies so that the files are only read/writable by their owner, and are not executable by any user.
Wait for the hub-start command to finish.
- If User Account Control is enabled, your system may request permission for CodeSonar to start a hub.
  
  Click Continue to proceed.
- If the codesonar hub-start command appears to be taking a long time to finish, it may be waiting for services authentication. (If you are working in other windows while running CodeSonar those windows might be obscuring the authentication dialog: if you don't see a dialog, move the other windows to check underneath). See CodeSonar as a Windows Service for more information.
Restart the primary hub and all its satellites.
1. Stop the newly-created satellite hub and any other satellites of the primary hub.
  codesonar hub-stop sathost:satport
2. Stop and restart the primary hub.
  codesonar hub-stop primhost:primport
  codesonar hub-start [-no-services] hubdirprimhost:primport
3. Restart the newly created satellite hub and any other satellites of the primary hub.
  codesonar hub-start [-no-services]
  [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
  -satellite-of [protocol://]primhost:primport sat_dir sathost:satport
  - Use the authorization options to provide credentials for a primary hub user account with G_HUB_INFO permission. These credentials are used to authenticate the early stages of the satellite hub-start process.
  - When prompted, enter the primary hub's Administrator password. This is used to authenticate the database operations involved in starting a satellite hub.
Use the satellite hub.
You will now be able to connect to the satellite hub at http://sathost:satport.

Identifying a Satellite Hub

To determine whether or not a particular hub is a satellite, check the Satellite field in the hub information.

Satellite:True indicates a satellite hub.
Satellite:False indicates a primary hub.

Command Line Details

The general form of the command line for starting a satellite hub is shown below. This command must be run on the satellite hub machine.

codesonar hub-start [-no-services]
[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
-satellite-of [protocol://]primhost:primport sat_dir sathost:satport

Where

-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).
[-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. Use these options to provide credentials for a primary hub user account with G_HUB_INFO permission.
[protocol://]primhost:primport	is the location of the primary hub with which the satellite will be associated. 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.
sat_dir	is the path to the hub directory for the satellite hub. If sat_dir does not already exist, CodeSonar will create it and populate it with the appropriate files. If sat_dir exists and is empty, CodeSonar will populate it with the appropriate files. If sat_dir 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 that are already stored in sat_dir. If the appropriate files are not present, the hub-start command will fail. If sat_dir was previously the hub directory for a primary hub, the hub-start command will fail.
sathost:satport	is the location of the satellite hub.

Shutting Down a Satellite Hub

Shutting down a satellite hub is accomplished in the same ways as shutting down a primary hub. For details, see Shutting Down A Hub.

Note also that a satellite hub will automatically shut down if its associated primary hub is shut down.

Troubleshooting

I am getting "out of connections" errors.

Increase the number of connections permitted by the hub database.

Shut down the hub.
Open the PostgreSQL configuration file for your hub:
<hubdir>/pgdata/postgresql.conf
where <hubdir> is the primary hub directory.
Edit the configuration file to increase the max_connections setting. Save and close the file.
Restart the hub.

See the PostgreSQL documentation for more information.