License Management

A short intro

The Gravity license system is based around a public key infrastructure. The provided infrastructure gives Remain the means to supply licenses in a secure and user friendly manner. Gravity licensing consists of two licensing parts, the Gravity license (also mentioned as product license) and the Gravity license Confirm Key. The Gravity product license contains information regarding the actual license, for example the name of the Gravity product being licensed and the number of users that can use the license. The Gravity license Confirm Key contains information on how license details can be extracted from the Gravity license.

With respect to licensing Gravity can run in either trial or non-trial mode. The difference being that a trial mode with a trial license is usually short lived. The default mode for Gravity is trial. In this mode Gravity does not require you to import a Confirm key or Base license simplifying setup and use of Gravity. In trial mode it is sufficient to import a trial Work-management license to get Gravity up and running.

A non-trial Gravity system requires a Base license and a commercial Work-management license. The Base license fully enables the Gravity licensing system. If no Base license and/or product related licenses are imported then only the initial Admin can log-in and use the Gravity system.

Requesting a License

Most Base and commercial licenses will be generated for a specific system id. This system id can be made visible by clicking the small-key-in-document icon which is used to import the base and commercial license. Copy this text and send it over to your license supplier.

1. Open the License Dialog

2. Copy the System id

Importing a license confirm key and product licenses

After you have received the license files, they can be imported by pressing the appropriate toolbar button. As shown below, the large single key icon depicts the button to press when importing a license Confirm Key file and the small-key-in-document icon depicts the button to press when 1 or more licensed product files are to be imported. These tool buttons are only available in the Gravity Admin product.

Pressing either button will evoke a wizard dialog that will prompt for a location of either the license confirm key file or the product license file(s). However, order of import is of importance here. As the license confirm key is used to extract information from a product license, a confirm key must already exist in the system before any product license files can be imported.

First import the confirm key
Then import the license keys

Import a license Confirm Key file

Press the toolbar button to start the 'License Key file' import:

By pressing the <Browse> button a file dialog will be shown where you can select the license confirm key file, from the location where it was saved (after receiving it by email or by other means). The browse option will only show files that match the file extension of the Gravity license confirm key file, in this case it expects to find a file with the extension 'glk' (Gravity License Key). For example :

Selecting the appropriate file and pressing enter or clicking on the <Open> button will set the file as the license confirm key file to be imported:

At this point pressing <Finish> will load the license confirm key into the Gravity system. This will be confirmed by a pop-up info panel, for example:

Failed import of a license confirm key file

Importing a license key can fail if the licensing system detects that the key file being imported is not a Gravity license key file (possibly corrupt) or is not a valid (revoked) license key file. If this is detected an error message will be displayed that states the problem at hand, for example:

Recovery from this type of error is only possible by requesting a new confirm key from your distributor.

Import 1 or more product license files

A similar procedure is to be followed for the import of 1 or more product license files. To start the 'Product License file' import, press the icon.

Major difference with the previous import wizard is that with this import 1 or more files with the extension 'gpl' (Gravity Product License) are to be selected for the import, for example:

By selecting both gravity-base.gpl and gravity-work-management.gpl and pressing enter or clicking on <Open> will set the 2 licenses as the product licenses to be imported. Pressing finish on the next dialog will finalize the import request. A pop-up info panel will confirm that the licenses were successfully imported:

Failed import of a product license file

Importing a product license file can fail if the licensing system detects that the file being imported is not a Gravity license file (possibly corrupt) or cannot be validated against the current license confirm key. If this is detected an error message will be displayed that states the problem at hand.

The above error occurred due a to corrupt product license file, but an error can also occur if the imported license confirm key is not compatible with the offered product license file. There is an enforced incompatibility between trial and commercial keys and licenses, it is not possible to interchange a commercial license with a trial key and visa versa.

Recovery from most errors is only possible by requesting a new product license from your distributor.

License administration

The license administration, i.e. to register or deregister a user to or from a product license, is performed by the Admin from the User Admin perspective. By opening the 'Users' container and by right clicking on an available user, the menu option 'Manage Licenses' will appear:

Selecting 'Manage License' will show the Manage User Licenses dialog. Based on previously import license products this will show for example:

By ticking the check box the user can be registered to a license and by unticking, deregistered from a license. In the example above the selected user will be registered to the work-management license. Pressing <Finish> confirms the (de)registration request and the request is processed by the licensing system.

Product license details

As can be seen in the 'Manage user licenses' dialog a license product consists of a number of licensing related fields, some fields are informative of nature but others influence the usability and availability of a license.

License Unit

The license unit is the product unique name. During license import the unit unlocks or makes available specific Gravity features to a registered user or in the case of the Gravity base license the unlocking of the Gravity user licensing system.

License type

Gravity Licensing supports to license types, they are:

Named license.
Floating license.

Named license

A named license is a license that is registered to a user. The number of users that can be registered to a named license is determined by the license unit count (above displayed as the column Available#). A named license is hard-wired to a user and cannot be shared amongst users in the way possible with a floating license. That being said, a license can be re-used by re-assigning it to another user. With a named license the amount of available licenses determines the maximum number of users that can be assigned to a unit. The column 'Assigned#' displays the number of users currently registered to the license.

Floating license

With a Floating license there is a pool of Gravity users that can make use of an available unit. As with the named license, each user is registered to a unit but the difference here is that with a floating license the amount of licenses available (within a unit) does not determine the number users that can be registered to a license. The blocking factor here is the number of concurrent (logged-in) registered licensees. With a floating license the number of logged in users cannot exceed the available unit count. In our example we can have 100 users registered to the work-management license but only 10 users can log-in and use it. If user 11 attempts to login then the login will be rejected and a notification message will be displayed.

Note.

If a user tries to log-in with a license that has log-in capabilities (Allow log-in) but the use count has already reached its maximum then the log-in request will be rejected. In this case a notification message will be displayed with the reason of rejection.

License activation and expiration

A license has a start and an end date. The start date is the date from which a license can be actively used and the end date is the date the license can no longer be used. In 'Manage user licenses' only the end date is displayed as 'Expiration'. Technically the license expires at midnight of the displayed date.

Base license system-id

The base license system-id is the hardware id of a system that will run a Gravity server installation. The system-id is requested from the user and tied into a product base license, specific to the user's Gravity Server installation. The system-id that is used to create a base license can be retrieved by running the command gSHI from the Gravity Server osgi console.

Switching from a trial license to a commercial license

If you have engaged in a Gravity trial license and you of course want to use Gravity commercially then a switch from trial to commercial is a trivial task. After receiving the appropriate key and licenses from your distributor the switch can begin.

If the product licenses are the same as the trial licenses (unit names are the same) then perform the following steps:

import the commercial license confirm key
import the commercial base product license
import the rest of the commercial product licenses

If the trial product licenses are not the same then you will have to first delete the trial licenses before importing the new commercial licenses, in this case the steps to be performed are:

delete all product licenses
import the commercial license confirm key
import the commercial base product license
import the rest of the commercial product licenses
optionally re-assign users to appropriate licenses

As you can see you don't necessarily have to remove users or definitions already applied in Gravity during the trial period. You can continue without data loss when switching from trial to commercial use of Gravity.

To delete a product license the Admin must go to the User Admin perspective and on the 'Users' container right click and select the menu option 'Delete Licenses'. Of course once a license is deleted then license registration will also be cleaned-up and users will no longer be able use the license,. If the license had the 'Allow log-in' attribute set then at this point only Admin can use the Gravity system, all other users will be locked out.

Managing license sessions

A side effect of actively managing licenses is that there are situations that a user log-out cannot be tracked and license usage not properly updated to reflect an up-to-date license usage count. This for example happens when a user is logged-in to Gravity and the system the user is working on crashes unexpectedly. In this case the license registration system cannot be updated to reflect the fact that the user is not using a specific license anymore. If this situation occurs to often then the license use count can inappropriately reach its use limit prohibiting a user from logging-in to Gravity or from using specific license related Gravity features.

To help manage and cleanup inactive license usage there is a menu option 'Manage Licenses'. This menu option is available at the same level as the previously mentioned 'Manage Licenses'. Selecting this menu option displays the following dialog:

The dialog will display license sessions for the selected user. A user can only see his/her own license sessions and cannot see sessions of other users (although the Admin does have the privilege to manage sessions for others). By ticking the check box under the 'User' column and pressing <Finish> license session will be removed from the license registry system(freeing up precious license resources).

There is 1 important effect of removing a session s that if the session is a live session (the user is currently logged in more than once) then removing the session will have the effect of a remote log-out for that session. The running Gravity instance for that session will be requested to log-out , if the user does not respond within a certain time limit then the selected Gravity instance will be automatically logged out (freeing up the license usage).

As already stated users can only manage there own sessions and only the Admin user has the ability to manage all sessions (Admin can right click on the 'User' container, select 'Manage sessions' and see all sessions).

Manage license sessions when logging in

The possibility to manage a user's own session has been added to the User log-in process. If at time of log-in the licensing system detects that there are insufficient license resources to allow the user to log-in but it also detects that there are registered license sessions for this user, then the user is given the opportunity to manage his/her sessions at time of a log-in. At this point removing 1 or more license sessions should allow the user to log in to Gravity.

If a user cannot log in to Gravity because the user has no license assigned or license usage has reached a maximum then the Admin must assign a license to the user or clean-up in-active license usage as shown above. If clean-up is not possible then you must wait for a license to become available or consider acquiring extra licenses. The following notification will pop-up in the right hand corner of the display:

If a user cannot log in because the 'base' license has not been imported then the following notification will pop-up in the right hand corner of the display:

License notifications

Gravity has built in functionality to notify users about the state of registered licenses. A notification will occur when a license is pending expiration or when a license has been invalidated. For a pending license expiration the period and interval of when to be notified can be set in the License section of the General Settings configuruation (Gravity Admin RCP). The notification of a license that has been invalidated due to tampering or server relocation will always be sent out the moment the invalidation is detected. For invalidated licenses the License 'Notify repeat interval' in the Gerneral settings configuration will be used to repeat the notification (see GR:Gravity/Views/ConfigurationAdmin/GeneralConfig). Licensing checking is performed when the server is started and from there on on a daily basis.

Viewing licensing messages

To view logged license messages you can use the Query Audit Log functionality to display audit messages logged by the license maintenance service. The Query Audit Log dialog can be opened by clicking on the appropriate toolbar icon;

Select a period over which the to view logged messages by setting a From date: and To date: and by setting the Process to: 'License-Maintenance'. Suggested is to select a period that is quite a few hours before the current date and time.

The result of the Qeury Audit Log will be shown in the Log Viewer (which will automatically be opened if it wasn't already open), for example:

2017-02-06 14:00:46,832  INFO AuditLog: 17-02-06 14:43 [License-Maintenance] ERROR [$userSystem$@RIDDW-PC@172.17.2.108]: Invalidated license: 'work-management', expired on 19-01-2017
2017-02-06 14:00:46,832  INFO AuditLog: 17-02-06 14:43 [License-Maintenance] ERROR [$userSystem$@RIDDW-PC@172.17.2.108]: Invalidated license: 'gravity-base', expired on 19-01-2017