License Installation: Floating License

• Start Here
• Before You Obtain a License
• Obtain and Set Up The License
• Updating Floating Licenses
• License Server Commands
• Troubleshooting
• IPv4 Note
• If You Don't Use the GUI

Start Here

Do you already have a CodeSonar license?

• NO: go on to Before You Obtain A License
• YES: does it contain an attribute of the form "floating":true?
  • NO: you have a standard license. See Hub License: Set Up a Standard License for installation information.
  • YES: your license will be locked to a specific machine. The CodeSonar license server must run on this machine. CodeSonar hubs can run anywhere with access to the license server; analyses can run anywhere. The license installation instructions refer to this machine as serverhost. (If it is no longer suitable, contact CodeSecure for an amended license.)
    
    • Decide whether you want to use server-side or client-side management for the new license. Server-side licensing is generally more straightforward, but client-side licenses can be added or updated without restarting the license server.
      Either:
      • continue with server-side setup, or
      • continue with client-side setup

Before You Obtain A License

1. Make sure CodeSonar is installed. If not, install it now.
2. Decide where you want to run the CodeSonar hub. The Setting Up The Hub section describes the factors that may affect this decision. We will refer to this machine as runhost in the remainder of these instructions.
3. Determine whether or not you require a floating license. You need a floating license if, and only if, you want to run a hub on a machine other than the one the license is locked to. The Setting Up The Hub section describes the factors that may affect your choice of hub location.
   • If you do not need a floating license, follow the instructions in Installation: Hub License: Obtaining a License to obtain and set up a standard license.
   • If you already have a floating license but only want to run a hub on the machine that the license is locked to, you can set it up as if it is a standard license and ignore this section.
4. Decide where you want to run the CodeSonar license server. The floating license will be specific to this machine: it will not work with license servers running on other computers.
   • The license server machine must be accessible from all locations where you will be running a hub.
   • To minimize the need for new licenses, choose a machine that you expect to continue to exist for some time.
   We will refer to this machine as serverhost in the remainder of these instructions.
5. If CodeSonar is not installed on serverhost, install it now.
6. Update the setting of your PATH environment to include $CSONAR/gtr/bin (if it is not already present).
   On Windows systems this is typically c:\Program Files\CodeSecure\CodeSonar\gtr\bin

Obtain and Set Up The License

Once you have determined a serverhost for running the CodeSonar license server:

1. Log into serverhost.
2. Run
   codesonar generate-license
   This command collects a small set of information that will be used to construct your license.
3. Copy the output from codesonar generate-license. It will look (something) like the following.

   {
       "ip addresses" : [ "198.51.100.0" ],
       "lock mutex" : "Global\codesonar_license",
       "mac addresses" : [ "02:00:5e:fe:c6:33:64:00" ],
       "machine" : "alexmachine",
       "name" : "CodeSonar",
       "user" : "alex",
       "version" : 309,
       "volumes" : [ "A438-C3F3" ]
   }
   

4. Open CodeSecure's license request page.
5. Paste the output from codesonar generate-license into the form field provided, and click Submit.
   • If the output contains attributes that you would prefer not to share due to privacy or security concerns, you can remove them before clicking Submit. CodeSecure staff will contact you if too many attributes have been removed for a license to be created.
   CodeSecure will generate a license based on the information you collected and on your licensing terms, then mail the license text to you.

   The license text will resemble an extended version of the codesonar generate-license output you submitted to CodeSecure. In particular, it will include a signature attribute.

6. When you have received the license text from CodeSecure, verify that it is a floating license: it should contain an attribute of the form "floating":true.
   • If you were expecting a floating license but did not receive one, contact CodeSecure support for help.
7. Decide whether you want to use server-side or client-side management for the new license. Server-side licensing is generally more straightforward, but client-side licenses can be added or updated without restarting the license server.
   Either:
   • continue with server-side setup, or
   • continue with client-side setup

Server-Side Setup

1. Save the license text you received from CodeSecure on serverhost, in a location where the license server will be able to read it. We will refer to this location as <path>/<to>/<licensefile>.
2. On serverhost, start the license server.
   • At the default location ([::]:7350):
     stifflm start -f <path>/<to>/<licensefile>
   • At some other <serverhost>:<serverport>:
     stifflm start -a <serverhost>:<serverport> -f <path>/<to>/<licensefile>
     For example, to start a license server at [2001:db8::abcd]:7353 to manage a license stored in /alex/cslicense.txt:
     stifflm start -a [2001:db8::abcd]:7353 -f /alex/cslicense.txt
   (See the IPv4 note if your system does not support IPv6 loopback addresses.)
3. Inform CodeSonar of the license server location.
   1. Navigate to the hub's License Utilization page.
   2. Enter the following text into the Edit License(s) field, replacing any text that was previously present.

      { "server address":"<serverhost>:<serverport>",
        "server side" : true  }
      

      For example, if your license server is running at [2001:db8::abcd]:7350:

      { "server address":"[2001:db8::abcd]:7350",
        "server side" : true }
      

   3. Click Save. The hub will attempt to connect to the license server and obtain a license session.
      • On success, CodeSonar will display a "License successfully updated" message above the text field and update the utilization summary to reflect the current license terms.
      • Otherwise, CodeSonar will display a "License Error" message above the text field, with details of the problem experienced.

Client-Side Setup

As an alternative to specifying server-side licenses with -f licensefile at license server startup, it is sometimes more convenient to use a client-side license. Client-side licenses are still managed by the license server, but are stored on the client machine.

To set up a client-side license managed by the license server at <serverhost>:<serverport>:

1. On serverhost, start the license server.
   • At the default location ([::]:7350):
     stifflm start
   • At some other <serverhost>:<serverport>:
     stifflm start -a <serverhost>:<serverport>
     For example, to start a license server at [2001:db8::abcd]:7353:
     stifflm start -a [2001:db8::abcd]:7353
   (See the IPv4 note if your system does not support IPv6 loopback addresses.)
2. Connect your hub to the license server.
   1. Navigate to the hub's License Utilization page.
   2. Paste the license text you received from CodeSecure into the Edit License(s) field, replacing any text that was previously present.
   3. If necessary, edit the file so that it conforms to client-side requirements:
      1. If attribute "server address":"<serverhost>:<serverport>" is not present, add it. Make sure there is a comma between this attribute and the one before it, and place a comma after the attribute if it is not the last one in the license.
      2. Delete any conflicting "server address":"..." attributes.
      (Note that changes to these attributes are allowed for in the CodeSonar licensing mechanism and will not affect license validation.)
   4. Click Save. The hub will attempt to connect to the license server and obtain a license session.
      • On success, CodeSonar will display a "License successfully updated" message above the text field and update the utilization summary to reflect the current license terms.
      • Otherwise, CodeSonar will display a "License Error" message above the text field, with details of the problem experienced.

Updating Floating Licenses

If you receive an updated license from CodeSecure, perhaps because you have purchased an amendment to allow additional licensed resources , you will need to apply the updates.

Updating Server-Side Licenses

To update a server-side license managed by a license server running on <serverhost>:<serverport>:

1. Shut down the hub.
2. Stop the license server on <serverhost>.
   • If the license server is running at the default location ([::]:7350):
     stifflm stop
   • If it is running at some other <serverhost>:<serverport>:
     stifflm stop -a <serverhost>:<serverport>
     For example, to stop a license server that is running at at [2001:db8::abcd]:7353:
     stifflm stop -a [2001:db8::abcd]:7353
   (See the IPv4 note if your system does not support IPv6 loopback addresses.)
3. Replace your old license file path/to/licensefile with the new license file.
   cp updatedlicense path/to/licensefile
4. Restart the license server. Include any <other_flags> that your license server requires. In particular, use -f directives to specify any other server-side licenses to be managed by the server.
   • At the default location ([::]:7350):
     stifflm start -f path/to/licensefile [<other_flags>]
   • At some other <serverhost>:<serverport>:
     stifflm start -a <serverhost>:<serverport> -f path/to/licensefile [<other_flags>]
     For example, to start a license server at [2001:db8::abcd]:7353:
     stifflm start -a [2001:db8::abcd]:7353 -f path/to/licensefile [<other_flags>]
5. Restart the hub.

Updating Client-Side Licenses

To update a client-side license:

1. Prepare the updated license file as described above.
2. Navigate to the hub's License Utilization page.
3. Paste the contents of your edited file into the Edit License(s) field, replacing any text that was previously present.
4. Click Save.
   • On success, CodeSonar will display a "License successfully updated" message above the text field and update the utilization summary to reflect the current license terms.
   • Otherwise, CodeSonar will display a "License Error" message above the text field, with details of the problem experienced.

License Server Commands

This section contains detailed information about starting and stopping the license server.

Starting the License Server

Start the license server in the following situations:

• as part of installing CodeSonar with a floating license,
• if you have stopped the license server and want to resume using CodeSonar

To start a license server as a background process:

where:

To start a license server in the foreground use stifflm server, which has the same set of options as stifflm start.

Stopping the License Server

Stop the license server in the following situations:

• before you upgrade CodeSonar,
• before you delete or overwrite the stifflm executable.

To stop a license server:

where <serverhost>:<serverport> is the location at which the license server is running (default id localhost:7350).

Note that stopping the license server will usually cause any hubs licensed through that server to shut down.

Troubleshooting

If CodeSonar encounters problems in processing your license, it will display an error message.

The following are some common error message types.

If You Don't Use the GUI

If you don't use the CodeSonar GUI, you can specify a license server for your hub by saving the relevant license information in a file on the hub machine (runhost).

We do not recommend using this approach if you have the option of using the GUI.

1. Decide whether you want to use server-side or client-side license management.
2. Create a text file with contents as described above (server-side | client-side).
3. Save the file in an appropriate location on runhost. There are two options.
   • Save it as license.txt in your CodeSonar installation directory: $CSONAR/license.txt
   • Save it in an arbitrary location path/to/licensefile and set environment variable STIFFLM_FILE=path/to/licensefile.

IPv4 Note

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

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

If you have not yet configured the hub, go on to Hub Setup: Hub Configuration.
Otherwise, go on to Installation: Finishing Up.