Installation: Hub Setup: Upgrading an Existing Hub

• Overview
• A. Identify the hub to be upgraded
• B. Preliminary Steps
• C. Upgrade the Hub
• Troubleshooting

Overview

Upgrading a CodeSonar hub involves several major steps.

• A. Identify the hub to be upgraded.
• B. Perform any necessary preliminary steps.
• C. Perform the upgrade.

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

A. Identify the Hub

Identify the hub you would like to upgrade. You will need the following information:

• The machine on which the hub is running.
• The hub location: its network host and port.
• The hub directory.

B. Preliminary Steps

1. If you have not already upgraded the CodeSonar installation on the hub machine, follow the Installing or Upgrading CodeSonar instructions to upgrade it before proceeding.
2. In certain upgrade cases, the hub upgrade procedure will include a phase in which you are prompted to specify a 'new' password for the hub Administrator account. The previous Administrator password will be discarded.
   The upgrade cases that will require you to specify a 'new' Administrator password are as follows. Note that you can respecify your previous Administrator password if you wish, provided it is sufficiently strong.
   • Upgrading from a CodeSonar version before 4.2 to version 4.2 or later.
   • Upgrading from a CodeSonar version before 4.5 to version 4.5 or later.
   If your upgrade situation matches one of these cases:
   • Choose a strong, memorable password now. The Administrator account has a broad range of hub permissions: setting a weak password will substantially undermine hub security.
   (For other upgrade cases, your current Administrator password will be preserved.)
3. Check that users without hub administration privileges do not have access to the hub directory. If necessary, use file system security controls to adjust the relevant permissions.
4. If your hub is set up to perform streaming replication, follow the instructions in Task: Back Up and Restore a Hub Database: When You Upgrade CodeSonar to move your current backup to a new location.
5. During the upgrade process, the hub database contents will be temporarily output to file UPDUMP in the hub directory (this is independent of any streaming replication you may be performing). If this is not a suitable location, for example because there is not sufficient space in that location, set environment variable CSHUB_DUMP_FILE=/your/preferred/file/path in the environment from which you will run codesonar config.

   If you wish to make this change:

   1. Exit from the configuration tool if it is currently running.
   2. Set environment variable CSHUB_DUMP_FILE and run codesonar config.
      (Windows note: run from a command prompt, rather than from the start menu or the desktop.)

C. Upgrade the Hub

Once you have identified the hub and upgraded the CodeSonar installation on the hub machine, perform the hub upgrade as follows.

1. If the CodeSonar configuration tool is not already running on the 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.

2. Windows-Enter 7 at the prompt to select option 7 ("Upgrade hub") from the main menu.
   Linux-Enter 6 at the prompt to select option 6 ("Upgrade hub") from the main menu.
3. The configuration tool will ask you which hub you want to upgrade.
   • If one of the presented options corresponds to the hub you identified in step A, enter the option number at the prompt.
   • Otherwise, select the option number corresponding to "Specify hub directory", then enter the absolute path to the hub directory when prompted.
   If the hub is currently running, CodeSonar will shut it down. It will then upgrade and restart the hub.
4. As the hub restarts, the tool may prompt you to specify a password for the hub Administrator account.
   • Enter the password you chose earlier.
   • When prompted, enter the password again for confirmation.
   [Windows only] If the restart 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.
5. When prompted, press Enter to continue.
6. The configuration tool main menu will be displayed, and your upgraded hub should appear in the table of known hubs.
7. 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?.
8. If you want to back up your hub, follow the instructions in Task: Back Up and Restore a Hub Database: Unencrypted Communication or Task: Back Up and Restore a Hub Database: TLS Communication to set up a new standby database.
9. Go on to Hub Setup: Hub License.

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?