Obeo License Server

  1. Obeo License Server
    1. Description
    2. Features
    3. Launching the server
    4. Configuration
    5. Pre-requisites
    6. Recommendations
    7. Upgrading
    8. Performance and Timing
    9. Parameters
    10. Operating on the server files and configuration
    11. Clients Configuration
    12. FAQ

Description

The Obeo License Server is composed of two distinct parts, a stand alone server and a stand alone client which is embedded in Obeo Designer.

Features

The server hosts a collection of Obeo licenses and each instance of the client can request licenses and revoke them. The server can automatically revoke a license from the client if the client has been disconnected abruptly when the next connection of the client will occur. If the server cannot be reached or if they are no more available licenses, Obeo Designer will use any locally registered license.

Launching the server

The server is composed of a single executable file with four files *.ols. Those files are provided by Obeo and they contain the licenses distributed by the server. Those files are encrypted and should not be modified, any single change will destroy the licenses information. If you want to backup the server, those four .ols files and the executables of the server need to be saved while the server is not running or you could corrupt the files.

The server communicates with the client thanks to an encrypted socket connection.

The server can be launched easily with the lic-server executable. By default, the server will be launched on the port 9999 and it will look for its configuration files in the user.dir folder.

You can use java parameters to change the port to use and the location of the OLS files by using the following command: lic-server -port <port to use> -keys <path of the configuration files>, it is recommended to capture those options in the lic-server.ini file.

Configuration

You may use the lic-server.ini file in order to store your configuration. The server will look into this file to retrieve the default values for the settings.
Each parameter name and then value must be on subsequent lines in the .ini file, in order to specify the -keys parameter as an example, add the two following lines in the .ini file

 -keys
 /home/server/ols_folder

You may also update the content of the file message.html. It is included «as is» when serving the page «/» through HTTP.

Pre-requisites

The server requires a JRE matching at least JavaSE-1.8, 128Mo RAM allocated to the JVM process and a minimum of 20Mo of disk space while operating.

The server can be run on the Linux x86_64 architecture. Builds for MacOSX 64bits, Win32 x86_64 are available though not recommended in production.

The server can be run either on a physical or virtualized environment and can be deployed alongside an Obeo Team Server appliance or on its own infrastructure.

Recommendations

A Web status page and json API can be enabled in order to monitor the server status and retrieve usage statistics. It is recommended to enable this API using the -httpPort command-line parameter to specify a port.
This API is restricted to exposing status and tokens/licenses related information, it is not possible to act or change the server configuration through it and is a read-only API.
It is up to the server administrator to decide whether it should be exposed to the network or not, in doubt keep it visible only from the server itself.

Once enabled, the web status pages can be accessed through the urls: http://host:httpPort/status and http://host:httpPort/usage where «host» is to be replaced with your hostname or IP address and «httpPort» with the port you specified.
The corresponding json resources are published at http://host:httpPort/status/json and http://host:httpPort/usage/json enabling scripting or alert automation.

Usage statistics are providing daily granularity and are reset on each startup, you can archive it either by copy/pasting directly into a spreadsheet or by setting up a scheduled job to archive the json resources.

The Obeo License Server is not a resource intensive application though latency in responding to clients will lead to latency in the tool startup.
It is recommended to make sure the clients will have a low network latency when contacting the license server, both being on the same network will help.
Avoid putting the license server behind VPNs which could cause high latencies, public WAN deployment is not recommended neither.

You can split your licenses in different pools by having several collections of .ols files served by several lic-server processes.
In this case it is required to assign a port number for each pool and distribute the connection keys to the clients accordingly.

Upgrading

The license server version 2.6.0 disables the attempt to use the previous transport protocol on the client side in favor of the the activation by default of the new transport protocol introduced in the 2.5.0 version.
The previous transport protocol is still available if needed but disabled by default, it can be enabled by adding the -SSL flag on the server and the -Dfr.obeo.mda.license.check.ssl.protocol.activation=true on the client.

Preparing the upgrade:

Here are the recommended steps to prepare for the upgrade:

  1. Make sure the machine hosting the server provides a JVM matching the latest version requirement: JavaSE 1.8 minimum.
  2. Collect the settings that might have been specified in the lic-server.ini file of the previous installation
  3. Collect the versions currently in use in the client applications by lookup up the filename of the fr.obeo.oo15oo.oo19oo_VERSION.timestamp.jar in the plugins directory (for instance «installation folder/plugins/fr.obeo.oo15oo.oo19oo_2.6.0.202007301546.jar»). If the version is 2.4.0 then you might need to either upgrade the Obeo products with the latest maintenance release which will provide the 2.6.0 version or start the server with the -SSL parameter. If the version is 2.5.0 and if your Java version is Java SE 1.8u261 or newer, the SSL handshake implementation has changed, you will need to keep Java SE 1.8u251 or older to use the SSL protocol.

Upgrading:

Here are the steps to follow to upgrade the license server.

  1. stop the license server which is already deployed: killall lic-server
  2. unzip the new release on the machine
  3. report the custom settings which have been collected when preparing the upgrade in the new lic-server.ini. Note that if you don’t use the -SSL parameter then you don’t need to report the settings to enable specific SSL algorithms
  4. make sure to specify the folder storing the .ols files
  5. start the server

Testing the upgrade:

  1. if you enabled the HTTP api using -httpPort then you can connect to the server on the http://serverIP:httpPort/status URL and see if it responds.
  2. start Obeo Designer which should be able to connect to the new license server considering the IP and port haven’t changed.

Performance and Timing

The server communicates with the clients using TCP on through the port 9999 (by default). Traffic is encrypted and can go through corporate proxies.

The server response time will vary depending on the number of tokens it is hosting, the server CPU and the server disk speed.

Considering a 1Ghz class CPU with SSD disks, a client request will take at most 100ms to be served by the server.

Clients are programmatically throttled and will not send requests to the server more frequently than once every minute. This throttling
means some of the client actions might have a delay before being distributed to the server, for instance if one user stops using a given
feature, 2 minutes of delay at most can be necessary for another user to be able to get the token.

The client/server communication is request based, no connection is kept alive for longer than just a request.

Parameters

Here is the complete list of parameters:

  • -consoleLog : Redirect log to the console
  • -keys PATH/TO/DIR/ : Folder containing the encrypted keys. Default is the user working directory. This folder should be writable for the server process.
  • -port N : Specify the port the server should listen to connect to the products. Default is 9999.
  • -httpPort N : Enables the HTTP API on the given port. This API allows the monitoring of the server status and usage, it is disabled by default.
  • -SSL : Enables the SSL transport. The SSL transport was deprecated with version 2.5 of the server, this parameter should only be enabled in order to be compatible with already deployed clients, it is recommended to upgrade the clients instead.
  • -verbose : Increase the level of logging performed by the server, useful for debugging purpose.
  • -console : Opens an OSGi console. This console can be used to inspect the current server state. In particular the tokens command will return a dump of the latest licenses status captured by the server and the usage command the daily usage statistics. Starting with version 2.5, using the HTTP API is RECOMMENDED instead in order to retrieve the server status.
  • -Dosgi.logfile PATH/TO/FILE : to use this file to store the log.
  • @-vm PATH/TO/JVM/BIN : to specify the Java Virtual Machine the server should use.

You can store your parameters in the lic-server.ini file, then they will be automatically used on startup.

Operating on the server files and configuration

The server configuration and more especially the .ols files should not be modified, moved or even accessed while the server is operating. Stop the license server before doing such operation.

Clients Configuration

In order to connect your Eclipse instance with the server, you should use the eclipse.ini or obeodesigner.ini file in order to enter the configuration of the server. Add the following line to define the configuration of the server to your eclipse.ini or obeodesigner.ini file:
-DOBEO_LICENSE_SERVER_CONFIGURATION=<connection key>

The connection key is provided by Obeo in order to indicate to Obeo Designer the address and the port that should be used by the client to connect with the server. In order to obtain this key, please contact Obeo and provide the IP address and port to use to connect to the machine that will host the server in your local network.

A license is retrieved at the launch of Obeo Designer and it is revoked when Obeo Designer closes. This license is verified from times to times with the server while you are using Obeo Designer.

If you want to use the previous protocol, you need to add -Dfr.obeo.mda.license.check.ssl.protocol.activation=true to activate the SSL protocol.

FAQ

Troubleshooting

In case of inconsistent behavior from the server, run lic-server with -consoleLog and -verbose to see what’s happening.

No appropriate protocol (protocol is disabled or cipher suites are inappropriate)

Starting with version 2.5 you should not get this error unless you use the -SSL option on the server. This option is provided only to ease the migration of already deployed tools waiting for an upgrade, it is recommended to upgrade the tools once this is possible.

The license server and clients are establishing an SSL connection using specific ciphers, it might be the case that your JVM installation has this cipher disabled.
You should be able to work around it be enabling the cipher specifically for the license server.

  1. Create a file named security.properties with the following content: jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, NULL
  2. In the lic-server.ini file add the following line -vmargs -Djava.security.properties=security.properties
  3. do the same operation on every product which will connect to the server to retrieve license tokens.

javax.net.ssl.SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled

This problem can occur if you don’t have an SSL certificate for your server. In order to create one, you will need to create a keystore and reference it while launching the server. To create the keystore, you can use the following command in the folder containing the server executable:

keytool -genkeypair -alias KeyStoreCertName -keyalg RSA -validity 7 -keystore KeyStoreFileName

Then update the lic-server.ini file to reference the freshly generated keystore file:

 -Djavax.net.ssl.keyStore=KeyStoreFileName
 -Djavax.net.ssl.keyStorePassword=<key store password>

As the lic-server.ini file contains the keyword password then you should make sure the read access of this file doesn’t not introduce a vulnerability in your infrastructure.

‹Encrypted keys are corrupted› message

If the server displays this message, you should stop the process and re-initialize the *.ols files with the ones given to you by Obeo.

Performance Issue

If connecting to a CDO server is taking more time to launch or if some operations are slower, it may be caused by an unreachable license server as the use of this feature might trigger the communication with the server.
The license system, using a socket connection will try to connect with the server a few time before dropping the connection. If the server can’t be reached, remove the settings from the settings file obeodesigner.ini or eclipse.ini. By keeping an invalid server location in the file obeodesigner.ini or eclipse.ini, the connection could be up to 6 seconds slower. Subsequent checks are done in an asynchronous way and will not impact the tool operation.

Contact

Feel free to contact Obeo’s support if you have any question regarding the server or its operation.