Installation: Hub Setup: Starting a New Hub

• Overview
• A. Important Decisions
• B. Preliminary Steps
• C. Start The Hub
• Troubleshooting
• IPv4 Note

Overview

Creating a CodeSonar hub involves several major steps.

• A. Decide where to store the hub database and where to run the hub.
• B. Perform any necessary preliminary steps.
• C. Start the hub.

The remainder of this page describes these steps and provides links to further information.

If you need to start a new hub, but prefer to run the hub in a Docker container, follow the instructions in Installation: Hub Setup: Starting a New Hub with Docker images from artifacts.codesonar.com instead.

You can also install CodeSonar on a Kubernetes cluster and run a hub pod:

• Install CodeSonar on a Kubernetes Cluster: Building Your Own Images
• Install CodeSonar on a Kubernetes Cluster: From artifacts.codesonar.com

A. Important Decisions

To configure CodeSonar, you will need to determine where to store the hub database and where to run the hub.

1. Choose a hub machine and interface using the following table.

   Number of Users	Analysis /Result Browsing Machine(s)	Hub Machine	Hub Interface
   one	All analyses take place on one machine, and you will browse analysis results from the same machine.	The same machine as the analyses.	Run the hub on a restricted interface such as ::1. (See the IPv4 note if your system does not support IPv6 addresses.)
   one	Analyses or result browsing (or both) may take place on machines other than the hub.	Choose a hub machine that all analysis machines/users and hub browsing machines/users can access. Ensure, however, that your hub is not visible to the entire internet.	Are the hub machine and all users behind a firewall? YES: Run the hub on :: to listen on all interfaces. NO: Specify a restricted interface such as ::1, and use a VPN to connect. For a detailed example, see Task: ssh Tunnel to a Hub. (See the IPv4 note if your system does not support IPv6 addresses.)
   multiple	All cases.

2. Determine how many hubs you will need.
   Do you have a machine that is accessible to all hub users and can handle the number of connections that this entails? All analysis machines, and all users that will want to use the web GUI, must be able to connect to the hub.
   • YES: You can run a single hub on that machine.
   • NO: you will need to run multiple hubs.
     Do you want all hubs to share a single hub database?
     • YES: Set up an initial ('primary') hub and then add one or more satellite hubs to accommodate all the users.
     • NO: Set up as many separate hubs as required. You may wish to use CodeSonar's annotation import/export functionality to mirror warning annotations across the different hubs.
3. Choose a location for the hub directory (where the hub database will be stored) by considering the number of projects that the hub will manage. The hub directory must be a directory on the hub machine.
   You do not need to create this directory: CodeSonar will create it for you.
   • If the hub has results for only a single project, the hub directory can be located alongside the project code (if desired).
   • If the hub has results for multiple projects, it usually makes more sense to create the hub directory in a "neutral location" than to have it alongside the code for one of those projects.
   • In either case, the hub directory must be located outside the CodeSonar installation directory.
   • Use file system security controls to restrict access to the hub directory: users that will not have hub administration privileges should not have access to the directory.
4. Choose a strong, memorable password for the hub Administrator account. You will be prompted to set a password for this account during the hub setup procedure.
   The Administrator account has a broad range of hub permissions: setting a weak password will substantially undermine hub security.
   By default, the following minimum password requirements apply.
   • Minimum length: 12 characters
   • Minimum number of character classes (e.g. 'upper case', 'lower case', 'digit'): 3
5. As part of the hub setup process, you will be prompted to create an ordinary hub user account. Select a name and password for this account now.
   • You can use the ordinary hub user account for regular CodeSonar tasks, such as running an analysis or browsing analysis results.
   • The password must conform to the requirements provided in the previous step.
   • You can create additional ordinary hub user accounts once the hub is set up.

B. Preliminary Steps

Make sure your user account and machine are ready to start a hub.

1. Determine whether you have sufficient 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.
   This user must have write permissions for the following, where $CSONAR is the CodeSonar installation directory.

   • $CSONAR/codesonar/template.conf
   • $CSONAR/codesonar/default_presets/
   • $CSONAR/codesonar/presets/
3. You will need to expand the shared memory. See Running a Hub Under Linux.

C. Start The Hub

Once you have made the important decisions and performed the preliminary steps, start the hub.

The hub should be started on the machine you selected in step A.

1. If the CodeSonar configuration tool is not already running on your selected hub machine, start it now.
   codesonar config
   Windows users can also select CodeSonar > CodeSonar Configuration Tool from the Windows Start menu.

   The configuration tool main menu will be displayed. You may need to scroll or enlarge your window in order to see the full menu.

2. Enter 2 at the prompt to select option 2 ("Install, create hub") from the main menu.
3. The configuration tool will ask you for various information about the hub you want to start.
   1. ... the kind of hub you would like to create.
      • Enter 1 at the prompt to select option 1 ("Create new primary hub").
        (If you want to add satellite hubs to this primary hub, you can do so later.)
   2. ... the interface the hub should use.
      • Enter the menu option number corresponding to the hub interface you selected in step A.
      • If necessary, specify the exact interface you have selected.
   3. ... the port number for the hub.
      • Enter the port on which the hub will listen. The default is 7340.
        CodeSonar will check to make sure the port is available.
        • If it is available, the configuration tool will print a "SUCCESS" message and move on to prompting you to specify the hub directory.
        • If it is not available, the configuration tool will print a "FAILURE" message. Go to troubleshooting port availability.
   4. ... the hub directory (see the directory decision notes above).
      • Enter the absolute path to the hub directory.
   5. ... [Windows only] whether the hub should run as a service (see section CodeSonar as a Windows Service for more information).
      • Enter the menu option number corresponding to your preference.
4. The tool will ask for various information in order to determine how you want this CodeSonar installation to interact with the new hub when you perform analyses.
   1. ... a username for a new hub user account.
      • Enter the ordinary hub user account username that you selected in part A.
   2. ... an email address for the new hub user.
      • Enter a suitable email address.
   3. ... whether analyses with this installation should use this hub by default.
      • Enter the menu option number corresponding to your preference.
   4. ... which kinds of C/C++ warnings to detect, that is, which configuration presets you want to define as default presets for all analyses. You may enable or disable one or more presets while creating the new hub. Note that you may choose to run analyses without processing the default presets by specifying -no-default-presets in your command.
      • Enter the menu option number corresponding to your preference.
   5. ... your preferred tradeoff between analysis performance and result quality.
      • Enter the menu option number corresponding to your preference, then confirm your choice.
   6. ... the level of analysis parallelism to use for analyses on the new hub.
      • Enter the menu option number corresponding to your preference.
        Note that this setting pertains to analyses performed by you, on this machine, with this CodeSonar installation, on the new hub.
   7. ... whether analyses should utilize the hub's analysis cloud: that is, whether they should be distributed analyses.
      • Enter the menu option number corresponding to your preference.
   8. ... whether analyses should contribute to the hub's analysis cloud: that is, whether you want to contribute resources (where available) to distributed analyses, including those started on other machines, or by other users, or by other CodeSonar installations.
      If you answered "Yes" to the previous question we strongly recommend that you answer "Yes" to this question. If you answer "No", your launch daemon will not start slaves for any distributed analyses, including your own.
      • Enter the menu option number corresponding to your preference.
   9. ... the parent launchd group for the launch daemon that your analyses will use to communicate with the hub.
      
      • Enter / to specify the root launchd group.
   10. ... [Windows only] whether the launch daemon should run as a service (see section CodeSonar as a Windows Service for more information).
       • Enter the menu option number corresponding to your preference.
5. The tool will provide information or functionality for accessing the new hub's License Utilization page.
   The license key setup instructions cover signing into the hub and locating the License Utilization page, so you don't need to open it now.
   • [Windows] The tool will ask whether you want to view the License Utilization page once the hub has been created.
     • Enter n at the prompt.
   • [other systems] The tool will print a message specifying the License Utilization page URL.
6. The tool will prompt you to specify a password for the hub Administrator account.
   • Enter the Administrator password you chose in step A.
   • When prompted, enter the password again for confirmation.

     CodeSonar will now start the hub.

   • When prompted, press Enter to continue.

   [Windows only] If the hub appears to be taking a long time to start, 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.

7. Once the hub has started, the tool will prompt you to specify a password for the new ordinary hub user account.
   • Enter the ordinary hub user password you chose in step A.
8. You will be prompted to provide authentication credentials so that CodeSonar can start a launch daemon to communicate with the hub.
   1. Enter the password for the ordinary hub user account that you have just created.
   2. When prompted, press Enter to continue.
9. If User Account Control is enabled, your system may request permission for CodeSonar to start a launch daemon.

   

   Click Continue to proceed.

10. When prompted, press Enter to continue.
11. The configuration tool main menu will be displayed, and your new hub should appear in the table of known hubs.
12. If there is a firewall on your system, you may need to configure it to permit connections to and from the hub. See FAQ: How do I allow hub access through a firewall?.
13. Go on to Hub Setup: Hub License Key.

Troubleshooting

Troubleshooting Port Availability

If you specify a port that is already in use, the CodeSonar configuration tool will print a "FAILURE" message. A common reason for failure is that you (or someone else) are already running a hub at the port you specified, in which case you may be able to use that hub instead of starting another one.

1. Press Enter to indicate that you have read the message.
   You will be prompted again to specify the interface the hub should use.
2. Type main_menu() and press Enter to abandon hub setup and go back to the configuration tool main menu.
3. Check the table of known hubs. Is there a hub running (status "ONLINE") at the port you specified?
   • YES: there are several possibilities.
     • The hub belongs to a different user on the hub machine. If this hub has already been set up and has a license key, you may wish to use it instead of starting a new one. Otherwise, you will need to try again with a different port: go on to the next step.
     • The hub belongs to you but you haven't finished setting it up yet. Pick up the hub setup process from wherever you left off.
       • If you haven't set up the license key yet, go on to Installation: Hub Setup: Hub License Key.
       • Otherwise, go on to Installation: Finishing Up.
     • The hub belongs to you and needs upgrading. Follow the instructions in Installation: Hub Setup: Upgrading an Existing Hub to upgrade the hub.
     • The hub belongs to you and is ready to use. If the hub is running the current version of CodeSonar and has been completely set up and configured, go on to Installation: Finishing Up.
   • NO: you will need to try again with a different port. Go on to the next step.
4. Enter 1 at the prompt to select option 1 ("Create new primary hub").
5. Press Enter to specify the same interface you specified last time.
6. When prompted for a port, enter a different value (for example, 7341). If a lot of ports are in use, you may need to try several times before you find one that is free.
   If necessary, open a new prompt and run the following command to see the ports that are currently in use.
   netstat -a
7. Once you have specified an available port, the configuration tool will print a "SUCCESS" message. Go on to the next step: specifying the hub directory.

Other Troubleshooting

The following entries from Frequently Asked Questions: Hub and User Accounts are particularly relevant.

• Why won't PostgreSQL start when I try to start a hub?
• I get a "daemonize_start: StartService failed with 1069: The service did not start due to a logon failure." error when I try to start a hub: how can I resolve that?
• I get a "Hub directory dirname is not allowed inside the codesonar installation [...] " error when I try to start a hub: how can I resolve that?
• I can't start a hub and I can't figure out why: what can I do?

IPv4 Note

If your system does not support IPv6 addresses, use IPv4 to specify addresses instead.

• 127.0.0.1 instead of ::1
• 0.0.0.0 instead of ::