Moving A Hub

• Relocating The Hub Interface or Port
• Relocating A Primary Hub Directory (Same Machine)
• Relocating A Primary Hub (Different Machine)
• 'Relocating' A Satellite Hub
• IPv4 Note
• Other Hub Sections

Relocating The Hub Interface or Port

Given a hub listening at interface:port with hub directory at hubDir, use the following procedure to move the hub to a new newinterface:newport on the same machine.

1. Shut down the hub.
   codesonar hub-stop interface:port
   (You may be prompted for hub user account credentials to authenticate this command.)
2. Shut down the hub database process, if it is not already shut down.
3. Restart the hub.
   codesonar hub-start [-no-services] hubDir newinterface:newport

Relocating A Primary Hub Directory (Same Machine)

Given a primary hub listening at interface:port with hub directory at oldDir, use the following procedure to move the hub directory to a new location newDir.

1. Make sure newDir is adequately secured.
   1. Ensure that newDir is not located inside the CodeSonar installation directory.
   2. Use file system security controls to restrict access to newDir: users without hub administration privileges should not have access to the directory.
2. Shut down the hub.
   codesonar hub-stop interface:port
   (You may be prompted for hub user account credentials to authenticate this command.)
   This will also shut down any associated satellite hubs.
3. Shut down the hub database process, if it is not already shut down.
4. Move the hub directory from oldDir to newDir.
5. Restart the hub.
   codesonar hub-start [-no-services] newDir interface:port
6. Restart the associated satellite hub or hubs (if any).
   codesonar hub-start [-no-services]
   [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
   -satellite-of interface:port 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.

Relocating A Primary Hub (Different Machine)

Given a hub listening at interface:port with hub directory at hubDir on machine A, use the following procedure to move the hub to a new newinterface:newport on machine B with new hub directory newHubDir.

Windows note: perform these steps in a command prompt (not Cygwin).

1. Make sure newHubDir is adequately secured.
   1. Ensure that newHubDir is not located inside the CodeSonar installation directory.
   2. Use file system security controls to restrict access to newHubDir: users without hub administration privileges should not have access to the directory.
2. Determine the port on machine A that the current hub database is listening on:
   1. Navigate to http://interface:port/command/info/
   2. Find the line that reads Database: postgres://[::1]:42xxx/cshub
      (See the IPv4 note if your system does not support IPv6 addresses.)
   3. Make a note of the 42xxx part. We will call this listenA.
3. On machine A, back up the hub database. You have a choice of methods:

   Option 1:	$CSONAR/third-party/postgresql/inst/bin/pg_dump -U cshubuser -h ::1 -p listenA -Z 9 -COx -F c -f BACKUP cshub You will be prompted for a password. Enter the hub Administrator password at the prompt. This will create a file called BACKUP in the working directory.
   Option 2:	Click the Backup Hub link on the Settings: Other Links tab, and use your browser's download controls to specify a suitable location for the backup file. Call it BACKUP.

4. On machine B, create a new hub at newinterface:newport with hub directory newHubDir:
   codesonar hub-start newHubDir newinterface:newport
   You will be prompted to set the Administrator password for the new hub.
   • Set the same Administrator password as you used on the old hub. This is important for the database transition steps. (You can always change it later.)
5. This creates a new hub database: the remaining steps explain how to replace this with the hub database in BACKUP.
6. On machine B, create a new, empty file:
   newHubDir/pgdata/pg_hba.conf.csignore
7. On machine B, edit newHubDir/pgdata/pg_hba.conf to append the following line.

   host    postgres    cshubuser    ::1/32    md5
   

8. On machine B, restart the new hub so your changes can take effect.
   1. codesonar hub-stop newinterface:newport
   2. codesonar hub-start newHubDir newinterface:newport
9. Determine the port on machine B that the new hub database is listening on:
   1. Visit http://newinterface:newport/command/info/
   2. Find the line that reads Database: postgres://[::1]:42yyy/cshub
   3. Make a note of the 42yyy part. We will call this listenB.
10. On machine B, kill the cshub process (or processes) — but none of its subprocesses — so that you can drop and restore the database.
    • On Windows, use a command line tool such as tskill or taskkill.
      tskill cshub
      • Avoid using the Task Manager to stop the cshub process: it may shut down the database process that you need to interact with in later steps.
    • On other systems, locate and kill cshub with kill -9 or your system's equivalent. There will typically be several cshub processes, so you may need to repeat this step several times until they are all stopped.
      • Do not specify alternate kill signals that shut down the entire process tree: this will shut down the database process that you need to interact with in later steps.
11. Copy the BACKUP file to machine B.
12. On machine B, drop the newly-created cshub database.
    $CSONAR/third-party/postgresql/inst/bin/dropdb
    -U cshubuser -h ::1 -p listenB cshub
    You will be prompted for a password.
    • Enter the hub Administrator password at the prompt. See the troubleshooting note if your password is not accepted.
13. On machine B, restore the cshub database from BACKUP.
    $CSONAR/third-party/postgresql/inst/bin/pg_restore
    -U cshubuser -h ::1 -p listenB -COxe -d postgres -F c BACKUP
    
    Did you create BACKUP from a hub running the same version of CodeSonar that you are using to restore?
    • YES: The command should run successfully.
    • NO: Did you create BACKUP from a hub running CodeSonar version 5.3 or earlier but are restoring with CodeSonar version 5.4 or later?
      • YES: You will see an error message like the following: this is expected, and is due to the PostgreSQL upgrade in CodeSonar 5.4.

        pg_restore: error: could not execute query: ERROR:  schema "public" already exists
        Command was: CREATE SCHEMA public;
        

        Provided that this is the only error, it is safe to re-run the pg_restore command without the -e flag to so that it completes even though an error is present. That is:
        $CSONAR/third-party/postgresql/inst/bin/pg_restore
        -U cshubuser -h ::1 -p listenB -COx -d postgres -F c BACKUP
      • NO: The command should run successfully

    You will be prompted for a password.

    • Enter the hub Administrator password at the prompt. See the troubleshooting note if your password is not accepted.
14. On machine B, edit newHubDir/pgdata/pg_hba.conf to remove the line you appended in step 6.
15. On machine B, remove file newHubDir/pgdata/pg_hba.conf.csignore
16. Restart the hub on machine B, using the same location and hub directory as before:
    codesonar hub-start newHubDir newinterface:newport
17. Navigate to http://newinterface:newport/ on machine B to verify that the transfer worked as expected.
18. License key configuration information will have been transferred along with the other hub information. In most cases the transferred information will not be suitable, because hub license keys are usually locked to a specific machine.
    • If you already have a license key for your new hub location, set it up now.
    • Otherwise, start by obtaining a license key.
19. Shut down and restart any satellite hubs associated with the hub you moved, pointing them to the new hub location.
    1. Shut down:
       codesonar hub-stop sathost:satport
       (You may be prompted for hub user account credentials to authenticate the hub-stop commands.)
    2. Restart:
       codesonar hub-start [-no-services]
       [-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]
       -satellite-of newinterface:newport 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.

Troubleshooting

If your Administrator password is not accepted at step 12 or 13, the problem may be caused by PostgreSQL having created an additional database. To work around this, go back to step 7 and amend your changes to newHubDir/pgdata/pg_hba.conf to replace postgres with all:

host    all    cshubuser    ::1/32    md5
  

Then continue from step 8 as before.

Related Topics

If you also wish to relocate the files associated with one or more analyses on this hub, see the instructions in Task: Relocate Analysis Files.

'Relocating' A Satellite Hub

The notion of 'relocation' does not really apply to satellite hubs, because their hub directories do not contain any information that needs to be preserved across different locations. Instead:

1. Shut down the unwanted satellite hub.
2. Start a new satellite hub at the new location, associated with the same primary hub as before.

IPv4 Note

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

• 127.0.0.1 instead of ::1 (including in the PostgreSQL command lines and newHubDir/pgdata/pg_hba.conf file).
• 0.0.0.0 instead of ::

Other Hub Sections

• The CodeSonar Hub
• Hub Location
• Getting Hub Information
• Starting a Hub
• Shutting Down a Hub
• Satellite Hubs
• The Hub Directory and Database
• The Hub Process
• GUI: Settings