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 or an http(s) 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, enable http(s) monitoring and communication or change the location of the OLS files by using the following command: `lic-server -port <port to use> -httpPort <httpPort to use> -useHttps <true or false> -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-17*, 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 and Windows x86_64 architectures. Builds for MacOSX 64bits 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.

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.

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.
It is possible to enable the monitoring API or the HTTP token transport protocol or both (see parameters). If HTTP token transport is enabled, tokens communications will be done on '/ol'.

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.7.0 no more contains the previous SSL transport protocol and introduce a new HTTP transport protocol (enabled when -httpPort is used).
The transport procotol is chosen by the client depending on the decoded port from the connection key or the valued passed with the `-Dfr.obeo.mda.license.protocol.force` system property.

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 17 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* or *2.7.0* version.
If the version is *2.5.0*, you will have to use Java version is Java SE 1.8u261 or newer. The SSL protocol has been disabled.
If the version is *2.6.x*, you can continue to use it.

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:

* -console                      : Open an OSGi console to get the server status. 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.  
* -consoleLog                   : Redirect log to the console
* -httpPort N                   : Specify the port to expose the HTTP api. -1 to not launch the HTTP(s) server. Preferred values: 8086, 80, 8008, 8080. (default: -1)
* -keys PATH/TO/DIR/            : Folder containing the encrypted keys. Default is the user working directory. This folder should be writable for the server process.
* -max N                        : Number of maximum connections the server handles. -1 means as much as possible. (default: -1)
* -monitoringOnHttpPort         : Allow monitoring using the HTTP api. (default: true)
* -port N                       : Specify the port the server should listen to connect to the products (socket connection). -1 to not listen on a socket. (default: 9999)
* -tokenRequestsOnHttpPort      : Allow tokens request using the HTTP api. (default: true)
* -useHttps                     : Force the use of https:// to expose the HTTP api. Dedicated parameters need to be defined in lic-server.ini. Preferred values for -httpPort become  8486 443, 8443, 8446.  (default: false)
* -verbose                      : Increase the level of logging performed by the server, useful for debugging purpose.
* `-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

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.

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 the -vmargs section of 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 (or DNS name) 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.

The client will automatically choose the transport layer to use for the following ports: 
 - socket: 9999
 - http:   8086, 80, 8008, 8080
 - https:  8486 443, 8443, 8446
 
If a custom port is use, the protocole can be forced on the client side by adding the following system property to the -vmargs section of your `eclipse.ini` or `obeodesigner.ini` file:
   `-Dfr.obeo.mda.license.protocol.force=<socket|http|https>`

FAQ
----

Troubleshooting
~~~~~~~~~~~~~~~

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


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

Invalid license message on client when using a proxy with authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The use of a proxy with authentication requires to reenable basic authentication trough system properties in the client vmargs (ini file or command line) or in JRE/JDK's conf/net.properties:

	 `-Djdk.http.auth.tunneling.disabledSchemes=""
	  -Djdk.http.auth.proxying.disabledSchemes=""
     

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



