Obeo License Server
===================

Description
-----------

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

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, the Obeo commercial product 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 using 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 the `ols` files in the `user.dir` folder.

You can use program 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.

To stop the server send the `SIG_TERM` event to the process or CTRL+C.

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 and `-useHttps` to accept only https requests.
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/status/json and http://host/usage/json enabling scripting or alert automation.
If `useHttps` is specified, the urls have to be modified to use https:// instead of http://. http:// requests will be denied.

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.5.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/status` URL and see if it responds or on `https://serverIP/status` if you decided to enable https with `useHttps`.
2. start the Obeo product 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.
* `-useHttps`          : Forces the use of https:// to expose the monitoring API. Dedicated parameters need to be defined in lic-server.ini. 
* `-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 the 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

When the `useHttps` is  `-httpPort`is specified with `-  , the keystore needs to be specified in the `-vmargs` section of the `lic-server.ini` file with the following properties:

* -Dorg.eclipse.jetty.ssl.keystore.path=PATH_TO_KEYSTORE   : The path to the keystore, it can be relative to the lic-server executable or absolute.
* -Dorg.eclipse.jetty.ssl.password=PASSWORD                : (optional) The password of the keystore.
* -Dorg.eclipse.jetty.ssl.keypassword=KEY_MANAGER_PASSWORD : (optional) The password of the key manager.
* -Dorg.eclipse.jetty.ssl.keystore.type=JKS                : (optional) The keystore type.
* -Dorg.eclipse.jetty.ssl.protocol=TLS                     : (optional) The SSL protocol

More information about keystore and certificates can be found in Eclipse Jetty's dedicated documentation: https://www.eclipse.org/jetty/documentation/jetty-9/index.html#configuring-jetty-for-ssl

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's product 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's product and it is revoked when the product closes. This license is verified from times to times with the server while you are using the product.

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.

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. 


Feel free to contact Obeo's support if you have any question regarding the server.
