Evri license server

Introduction

The EVRI License_Server allows limiting the number of individual PLS_Toolbox or Solo users operating under a given Eigenvector Research, Inc. (EVRI) license. When operating under this server, individual copies of PLS_Toolbox or Solo are required to contact a network-mounted server in order to operate.

The license system consists of two parts: a server which must reside on a network-accessible computer and a client that runs on the end-user’s computer. All communication between client and server is done over standard TCP/IP sockets. When an individual starts up Solo or PLS_Toolbox, the client application (Solo or MATLAB) contacts the server to request a license. The server, upon receiving this request, first verifies an Access Code to confirm the validity of the request. Once confirmed, the server identifies the number of allowed licenses and the number of currently issued licenses. If any licenses are available, the server issues a license to the user with a fixed timeout period (fixed at 20 minutes in the current license server). This license is keyed to the individual’s computer and (for the current 20 minute period) the IP address of that user.

Once a valid license is issued, the client will operate independently of the server until the reissue time passes (set at 10 minutes before the license timeout period). After that time period has passed, the client requests reissuance of the license. The server will automatically reissue the license to the original client. If for some reason the license server is not reachable (e.g. network outage), the client will warn the user but continue to operate until the full license timeout period has passed (20 minutes). The client will repeat the request for a license periodically over that time. After the license has expired, the client will stop PLS_Toolbox or Solo from operating.

If a given user does not request reissuance of their license before the license expires (e.g. the user has finished working with the product), the server considers the license use complete and makes it available for another user. Thus, a given license is considered “checked out” for 20 minutes from the last contact with a user.

Note that if a given client changes IP addresses, they will not be able to renew the original license they checked out. However, if there are other seats already available (or after the original license has expired normally), the client’s computer will automatically check out a new license under their new IP address. This behavior depends on the operating system and MATLAB version being used – some systems will be linked to the MAC address of the computer rather than the IP.

Server Configuration

Eigenvector Research, Inc. (EVRI) will provide to you a copy of the EVRI License_Server (requires the Java Runtime Engine version 1.5 or later) and a license file (evriserverlicense.xml). Most operating systems already contain the necessary files to execute the server application. The server can be run either as a background service with no interface, or as a desktop application with a status window. Follow the directions below as appropriate for your operating system and preferred interface.

Running Server as a Windows Desktop Application

Copy the application files onto the computer that will operate as the server (which must be a network accessible computer). Copy the evriserverlicense.xml file into the same folder as the EVRILicenseServer.jar file.

On this computer, either double-click the EVRILicenseServer.jar file, or add it to your system startup folder (operating system dependent location - whatever is appropriate for the OS) to automatically start the server on startup.

Once started, the server can only be stopped by using the Task Manager processes tab (in Windows) or other standard task kill operation (MAC OS X or Linux). EVRI has pre-configured the server so there is no additional configuration necessary.

Running Server as a Windows Service

The server comes with a set of installation BAT files (“Install_Service.bat” and “Uninstall_Service.bat”) which can be used on a Microsoft Windows-based system to install the server as a Windows service which will automatically be started without a user logging in.

To use these utilities, copy the application files onto the server computer and copy the evriserverlicense.xml file into the “service” sub-folder of the server application (same folder as the Install_Service.bat file). NOTE: When running as a windows service, the evriserverlicense.xml file must be in the service folder, not the top-level application folder.

Next, run the Install_Service.bat file as an administrator to install the service. Errors and status will be reported to the log files stored in the service/logs folder. To move logs to a different location, edit the service/conf/service.conf file.

Running Server as a Unix/Linux Service

The server can be run as a Linux or Unix “service” by simply starting the jar file with the additional input –service. For example:

java -jar EVRILicenseServer.jar –service

All output will go to the standard output, thus the output can be sent to a log file using the standard output piping utilities of the operating system. For this mode of operation, the evriserverlicense.xml file should be copied into the main application folder.

Changing the Server Port Number

If the default port number used by the server (2212) is in conflict with another application, the user can modify the port number by editing the evriserverlicense.xml file with a text editor adding the following tag (inside the outer <license> </license> tags):

<port>2212</port>

The value 2212 can be replaced with any valid port number. Note, however, that the server must be shut down and restarted to register the changes to this file.

Configuring the License Expiration Time

By default, the server issues licenses which expire after 20 minutes if the user does not renew it within that time period. Version 2.1 of the License Server introduced the ability to customize this time period. To make this change, the administrator must edit the evriserverlicense.xml file in a text editor adding the following tag to the file:

<timeout>time_in_minutes</timeout>

This new tag should appear above the ending </license> tag. The value specified as time_in_minutes must be greater than 10 and will define how long the server will reserve a license for a user without hearing back from that user.

Note that, unless a user explicitly releases a license, the server will reserve that license for the entire timeout time period. As such, it is recommended that long timeout periods be used in conjunction with a procedure to explicitly release a license when done (see Releasing Licenses in PLS_Toolbox in the Client Configuration section of this manual.)

NOTE: Changing of license expiration time is only compatible with PLS_Toolbox and Solo versions 5.0 or later. Contact EVRI for a patch to use this feature with earlier versions (<=4.2).

Configuring Reserved, Extended-Period Licenses

The license server can also be configured to create a separate pool of licenses which can be checked out for extended periods (or, in general, a period of time different from the standard timeout period described above). Users access these licenses by supplying a separate access code different from the standard access code used to access the standard licenses.

The administrator can specify:

1. The access code users must use to access the extended licenses
2. How many of the total license seats are eligible to be used as extended licenses
3. The time period extended licenses are valid for, and
4. How many of the total license seats are reserved for extended license use (cannot be checked out as standard licenses)

To access these features, the following XML code should be added to the evriserverlicense.xml file just before the </license> tag at the end of the file:

<license>

    …(all EVRI-supplied tags remain here)…

    <extended>

        <accesscode>extended_access_code </accesscode>

        <allowedseats>number_of_seats</allowedseats>

        <reservedseats>number_of_seats</reservedseats>

        <timeout>time_in_minutes</timeout>

    </extended>

</license>

Note that these additional tags are enclosed by the <extended></extended> tag pair indicating that these settings are for the special extended licenses only and that the <extended> tags are inside the <license> tags.

The <accesscode> tag is required to be a non-empty string which the users will use in place of the standard access code (see Client Configuration below) to access this separate extended license pool. The standard access code will still be used to access the standard license pool.

The <allowedseats> tag specifies how many of the total allowed license seats (specified by EVRI) can be checked out as extended licenses. This number cannot be greater than the number specified earlier in the file in the main <allowedseats> tag.

The <timeout> tag specifies the amount of time (in minutes) an extended license is valid for.

The <reservedseats> tag is optional and, if specified, defines the number of license seats that can only be checked out as extended licenses. The default value is zero, meaning that all license seats are available as standard licenses.

NOTE: Changing of license expiration time is only compatible with PLS_Toolbox and Solo versions 5.0 or later. Contact EVRI for a patch to use this feature with earlier versions (<=4.2).

These settings can be used to limit the total number of licenses in a number of ways. For example, if the basic site license includes a total of eight seats, the following configuration file limits four of the licenses to extended checkout of 24 hours (1440 minutes) but all eight can also be checked out as standard licenses:

<license>

    …(all EVRI-supplied tags remain here)…

    <allowedseats>8</allowedseats>     (as supplied by EVRI)

    <extended>

        <accesscode>myaccesscode</accesscode>

        <allowedseats>4</allowedseats>

        <timeout>1440</timeout>

    </extended>

</license>

Thus the following would be a “map” of the eight licenses and their valid uses:

Checkout Map

	1	2	3	4	5	6	7	8
Standard	x	x	x	x	x	x	x	x
Extended					x	x	x	x

Note that four of the licenses can only be checked out as standard licenses. The other four licenses can be either standard or extended licenses. If <allowedseats> in the extended tag segment of the file had been set to “8”, all eight licenses could be checked out as either standard or extended licenses.

The <reservedseats> tag forces the server to reserve some licenses for use only as extended licenses. For example, if we add the tag:

<reservedseats>2</reservedseats>

to the <extended> section of the XML file, the server will be forced to reserve two of the eight licenses as extended licenses. Thus four licenses can be only checked out as standard licenses, two can be checked out as only extended licenses, and the other two can be checked out as either. The map of valid uses is shown below:

Checkout Map

	1	2	3	4	5	6	7	8
Standard	x	x	x	x	x	x
Extended					x	x	x	x

NOTE: The total number of allowed seats (set in the main license tag segment of the file) and the main access code cannot be modified by the user. This value is fixed and is specific to the license issued by Eigenvector Research. To change the total number of license seats, contact Eigenvector Research.

In general, the server will handle inappropriate settings by defaulting to the un-modified behavior, but if the settings you have chosen are invalid or the file is not valid XML format, the server will return an error on startup. It is recommended that you make a copy of the original license file supplied by Eigenvector Research in order to recover from such mistakes.

Under no circumstances should the user modify the top-level values for <accesscode> <licensecode> or <allowedseats> (the tags at the top level of the <licenses> tag, not those in the user-modifiable <extended> tag). Changing these values will cause the server to fail.