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.
License Key Installation: Floating License Key
This section explains how to manage floating CodeSonar
license keys.
Note that most CodeSonar license keys are not
floating.
If you do not have a floating license key, see Hub Setup: Hub License Key for
information on setting up a license key.
Do you already have a CodeSonar license key?
- NO: go on to Before You Obtain A License
Key
- YES: does it contain an attribute of the form "floating":true?
- NO: you have a standard license key. See
Hub License Key: Set
Up a Standard License Key
for installation information.
- YES: your license key will be locked to a specific machine.
The CodeSonar license key server must run on this
machine.
CodeSonar hubs can run anywhere with access to the
license key server; analyses can run anywhere.
The license key installation instructions refer to this
machine as serverhost. (If it is no longer suitable,
contact CodeSecure for an amended license key.)
- Decide whether you want to use server-side or
client-side management for the new license key. Server-side
management is generally more straightforward, but
client-side license keys can be added or updated without
restarting the license key server.
Either:
- Make sure CodeSonar is installed. If not, install it now.
- 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.
- Determine whether or not you require a floating license key.
You need a floating license key if, and only if, you want to run
a hub
on a machine other than the one the license key is locked to.
The Setting Up The Hub section
describes the factors that may affect your choice of hub
location.
- Decide where you want to run the CodeSonar license key
server. The floating license key will be specific to this machine:
it will not work with license key servers running on other
computers.
- The license key 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.
- If CodeSonar is not installed on serverhost,
install it now.
- Update the setting of your PATH environment to include $CSONAR/gtr/bin (if it is
not already present).
Once you have determined a serverhost for running the
CodeSonar license key server:
- Log into serverhost.
- Run
codesonar generate-license
This command collects a small set of information that will be
used to construct your license key.
- 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" ]
}
- Open CodeSecure's license key request page.
- 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 key to be created.
CodeSecure will generate a license key based on the information
you collected and on your licensing terms, then mail the license
key text to you.
The license key text will resemble an extended version of the
codesonar
generate-license output you submitted to CodeSecure. In
particular, it will include a signature attribute.
- When you have received the license key text from CodeSecure,
verify that it is a floating license key: it should contain an
attribute of the form "floating":true.
- If you were expecting a floating license key but did not
receive one, contact CodeSecure support for help.
- Decide whether you want to use server-side or client-side
management for the new license key. Server-side management is
generally more straightforward, but client-side license keys can be
added or updated without restarting the license key server.
Either:
- Save the license key text you received from CodeSecure on
serverhost, in a location where the license key server will
be able to read it. We will refer to this location as <path>/<to>/<licensekeyfile>.
- On serverhost, start the license
key server.
- At the default location ([::]:7350):
stifflm start -f
<path>/<to>/<licensekeyfile>
- At some other <serverhost>:<serverport>:
stifflm start -a
<serverhost>:<serverport> -f
<path>/<to>/<licensekeyfile>
For example, to start a license key server at [2001:db8::abcd]:7353 to manage a
license key stored in /alex/cslicensekey.txt:
stifflm start -a [2001:db8::abcd]:7353 -f
/alex/cslicensekey.txt
(See the IPv4 note if your system does not
support IPv6 loopback addresses.)
-
Inform
CodeSonar of the license key server location.
- Navigate to the
hub's License Utilization page.
- 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 key server is running at
[2001:db8::abcd]:7350:
{ "server address":"[2001:db8::abcd]:7350",
"server side" : true }
- Click Save. The hub will
attempt to connect to the license key 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 key terms.
- Otherwise, CodeSonar will display a
"License Error" message above the
text field, with details of the problem experienced.
As an alternative to specifying server-side license keys with
-f
licensekeyfile at license
key server startup, it is sometimes more convenient to use a
client-side license key. Client-side licenses are still managed by
the license key server, but are stored on the client machine.
To set up a client-side license key managed by the license key
server at <serverhost>:<serverport>:
- On serverhost, start the license
key server.
(See the IPv4 note if your system does not
support IPv6 loopback addresses.)
- Connect your hub to the license key server.
- Navigate to the
hub's License Utilization page.
- Paste the license key text you received from
CodeSecure into the Edit
License(s) field, replacing any text that
was previously present.
- If necessary, edit the file so that it conforms
to client-side requirements:
- 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 key.
- Delete any conflicting "server address":"..."
attributes.
(Note that changes to these attributes are allowed for in the
CodeSonar license key mechanism and will not affect license key
validation.)
- Click Save. The hub will
attempt to connect to the license key 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 key terms.
- Otherwise, CodeSonar will display a
"License Error" message above the
text field, with details of the problem experienced.
If you receive an updated license key from CodeSecure, perhaps
because you have purchased an amendment to allow additional
licensed
resources
, you will need to apply the updates.
Updating Server-Side License Keys
To update a server-side license key managed by a license key
server running on <serverhost>:<serverport>:
-
Shut down the hub.
-
Stop the license key server on
<serverhost>.
(See the IPv4 note if your system does not
support IPv6 loopback addresses.)
- Replace your old license key file path/to/licensekeyfile
with the new license key file.
cp updatedlicensekey
path/to/licensekeyfile
-
Restart the license key server.
Include any <other_flags> that your
license key server requires. In particular, use -f directives to specify any other
server-side license keys to be managed by the server.
- At the default location ([::]:7350):
stifflm start -f
path/to/licensekeyfile
[<other_flags>]
- At some other <serverhost>:<serverport>:
stifflm start -a
<serverhost>:<serverport> -f
path/to/licensekeyfile
[<other_flags>]
For example, to start a license key server at [2001:db8::abcd]:7353:
stifflm start -a [2001:db8::abcd]:7353 -f
path/to/licensekeyfile
[<other_flags>]
-
Restart the hub.
Updating Client-Side License Keys
To update a client-side license key:
- Prepare the updated license key file as described
above.
- Navigate to the
hub's License Utilization page.
- Paste the contents of your edited file into
the Edit
License(s) field, replacing any text that
was previously present.
- 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 key terms.
- Otherwise, CodeSonar will display a
"License Error" message above the
text field, with details of the problem experienced.
This section contains detailed information about starting and stopping
the license key server.
Start the license key server in the following situations:
To start a license key server as a background process:
stifflm start [-a <host>:<port>] [-m
<max_sockets>] [-f <licensekey_file>]
where:
| -a
<host>:<port>: |
specifies the location at which the license key server will
run. Default is [::]:7350. |
| -m
<max_sockets>: |
specifies the maximum number of connections (
hub
to license key server) permitted. Default is 62. |
| -f
<licensekey_file>: |
specifies a license key file that should be managed by the
server. The license keys specified in this way are referred to as
server-side license keys.
The stifflm start
command can specify multiple -f
values. There is no default value. |
To start a license key server in the foreground use stifflm server, which has the same set
of options as stifflm
start.
Stop the license key server in the following situations:
- before you upgrade CodeSonar,
- before you delete or overwrite the stifflm executable.
To stop a license key server:
stifflm stop [-a
<serverhost>:<serverport>]
where <serverhost>:<serverport> is the
location at which the license key server is running (default id
localhost:7350).
Note that stopping the license key server will usually cause any
hubs licensed through that server to shut down.
If CodeSonar encounters problems in processing your
license key, it will display an error message.
The following are some common error message types.
[...]
Found network interface {...} with hardware address
02:00:5e:fe:c6:33:64:00. Not present in license.
None of the MAC addresses in the license were present on this
computer.
None of the MAC (hardware) addresses of the NICs (network
interface controllers) on the machine correspond to any of the
addresses listed in the license key.
Connecting to <serverhost>:<serverport>
for license download.
Resolved to
<IPaddress>:<serverport>.
Connection to <IPaddress>:<serverport>
failed: Connection timed out.
First, check that the license key server machine
(
serverhost) is running and is connected to your network.
If serverhost is available on the network and you are
still seeing this problem, access to
serverhost:serverport may be blocked by a firewall
or other network security measure. Resolution will depend on your
platform and on your network policies: you may need to consult
your system administrator to determine the best approach, which
in general will involve either:
- running the license key server on a different port (one
that is not blocked), or
- configuring your firewall (or similar) to permit access to
serverhost:serverport from
your hub machine or machines.
License does not parse: CS_INVALID_DATA_FORMAT
Perhaps the license was not transcribed accurately.
The text you have provided does not have correct license key
syntax.
- Make sure you have copied and pasted the entire license key
text (and only the license key text) that you received from
CodeSecure. It should start with { and end with }.
- If you have added a "server
address" attribute to the license key, make sure
that it is correctly comma-separated from the attributes before
and after it.
License verification failed.
Perhaps the license was not transcribed accurately.
Note that licenses are case sensitive.
Some attribute of the license key is inconsistent with its
signature.
Almost all of the license key text is validated against the
signature: "server
address" is the only attribute that can be added,
removed, or edited.
- If you have added a attribute to the license key, make sure
the spelling (including case) is exactly as shown here.
- If you have made any other changes to the license key text,
undo those changes. It may be simpler to make a new copy of the
signed license key text that you received from CodeSecure.
License verification failed.
The license is not signed.
The license key does not contain a
signature attribute.
You may have accidentally used the output from codesonar generate-license
rather than the signed license key you received from
CodeSecure.
- Make a new copy of the signed license key text that you
received from CodeSecure, and try again.
[...]
License already in use by another process
(Global\codesonar_license is locked).
or
License already in use by process with PID pid
(/tmp/codesonar_license.lock is locked).
The maximum number of CodeSonar
hubs
permitted by the license key are already running, so the current
hub
cannot be licensed. This can occur with both server-side and
client-side license keys.
- Identify the currently-running
hubs.
- To identify
hubs
on a specific machine, use the top command .
Hub processes are named cshub.
-
To identify all
hubs
(on any machine) that are using the license key server
at serverhost:serverport, do the
following.
- Run netstat on
serverhost.
netstat -ano
Examine the output. All connections whose Local
Address has port serverport are
connections to the license key server. The machine on
which each connecting
hub
is running is shown in the Foreign Address
column; the
hub's
PID on that machine is shown in the PID
column.
- Make a note of the Foreign Address machine
and PID for each
hub
connected to the license key server.
Note that the port shown in the Foreign Address
column (if any) is not generally the hub port, so you
will need to perform another step to identify the port.
- For each Foreign Address machine
hubmachine that is running a hub with PID
P connected to the license key server, run
netstat on
hubmachine.
netstat -ano | grep P
The output will show the interface and port of the
hub.
-
Either
- switch to using one of the existing
hubs
, or
- shut down one of the existing
hubs
so that there is an available license slot for your
current one, or
- contact CodeSecure if you want to license additional
resources.
For a hub located at <hostname>:<port>, navigate
to the License
Utilization page as follows.
- Set up and start the
hub, if necessary.
- If the CodeSonar Web GUI is not already open,
open it now.
http://<hostname>:<port>/
- If you are not already signed in as Administrator,
sign in now.
- Click the Sign In link (at the top right of
the page).
CodeSonar will open a page for you to
enter credentials.
- Enter Administrator
in the Username field.
- Enter the Administrator password
in the Password field.
(If you have just started a new hub, you will have set a
password for Administrator
as part of that process.)
- Click Sign In.
If this is the first time the Administrator account has been
used, you will be asked to specify an email address for
the account.
- Click the see
licensing details link in the GUI footer.
The License Utilization page will open.
Directly under the page heading will be
a text field labeled Edit License(s).
If you don't use the
CodeSonar GUI, you can specify a license key
server for your hub by saving the relevant license key
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.
- Decide whether you want to use server-side or
client-side license key management.
- Create a text file with contents as described
above (server-side |
client-side).
- 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/licensekeyfile and set
environment variable STIFFLM_FILE=path/to/licensekeyfile.
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.