Evri license server

Introduction

The EVRI License_Server allows monitoring the number of users operating under a given Eigenvector Research, Inc. (EVRI) license. of PLS_Toolbox or Solo. When operating with 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 (this defaults to 20 minutes in the current license server, but can be configured). This license is keyed to the individual’s computer and the IP address of that user.

**Click here to view the "Quick Start" guide**

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 end of the license period). After that time period has passed, the client requests re-issuance 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 re-issuance 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. Users can check a license back in manually by either closing Solo, or issuing a special Matlab command (for PLS_Toolbox).

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.

Choice of Computer

The computer selected to run the license server can not also run the client application (i.e. the Eigenvector product being licensed - PLS_Toolbox, Solo, etc). As such, the computer you select to run the license server must:

1. Be reachable by network
2. Be identified by its network name or by a static (fixed) IP address
3. Not be a computer on which you want to run the client application

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 sub-folder "service" in the License Server main folder contains the additional tools necessary to run the server as a Windows service which will automatically be started without a user logging in. Follow these instructions:

1. copy the application files onto the server computer.
2. copy the evriserverlicense.xml file into the "service" sub-folder (for 32-bit computers) or "service64" sub-folder (for 64-bit computers). When running as a windows service, the evriserverlicense.xml file must be in this sub-folder, not the top-level application folder.
3. run the Install_Service.bat file in the service (or service64) folder to install the service.

Errors and status messages will be reported to the log files stored in the C:/temp/ folder by default. To move logs to a different location, edit the service/conf/service.conf file (or service64/conf/service.conf file if using the 64-bit version). You can also modify the logging behavior in this file (maximum length, number of log backups, etc.)

To uninstall the service, run the Uninstall_Service.bat file.

Running Server as a Unix/Linux Daemon

The sub-folders "daemon_linux" and "daemon_linux64" in the License Server main folder contain the additional tools necessary to run the server as a Linux daemon which will automatically be started without a user logging in. Follow these instructions:

1. Confirm java 1.6 or newer is installed.

   java -version

2. Copy the application files onto the server computer.
3. Copy the evriserverlicense.xml file into the daemon_linux sub-folder (for 32-bit computers) or daemon_linux64 sub-folder (for 64-bit computers) of the server application (same folder as the Install_Daemon file). When running as a daemon, the evriserverlicense.xml file must be in the appropriate daemon_linux folder, not the top-level application folder.
4. Run the Install_Daemon script to install the daemon (this batch file must be run by a user with root privileges).

   ./Install_Daemon

5. Start the daemon.

   /etc/init.d/EVRILicenseServer start

NOTE: In order to execute this script and have the daemon operate correctly, you may have to manually set the "execute" bit on all files in the top-level daemon_linux / daemon_linux64 folder to "on" using the chmod command inside the daemon_linux folder:

chmod 755 *

Errors and status messages will be reported to the log files stored in the ./tmp folder. To move logs to a different location, edit the daemon_linux/conf/wrapper.conf or daemon_linux64/conf/wrapper.conf file. You can also modify the logging behavior in this file (maximum length, number of log backups, etc.)

To uninstall the daemon, run the Uninstall_Daemon script (as root.)

./Uninstall_Daemon

If you have problems, try running the test script:

./Test_Daemon

to see if the server will start when run manually.

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

Client Configuration: PLS_Toolbox

Follow these steps to install and configure PLS_Toolbox for use with the License_Server:

1. Download the ZIP version of PLS_Toolbox, available from your account on Eigenvector.com.
2. Unzip the file onto either a network-accessible drive or a local drive on a given client’s computer.
3. EVRI may supply several additional files, including:

   evrilicense.lic -contains the license code for the license

   evrilm.xml -user-modifiable server configuration

   evrinetwork.lic -eases network installation
   
   If provided, these files should be copied into the PLS_Toolbox/utilities folder (see notes below regarding evrilm.xml file).
   NOTE: If you are using a demo version of PLS_Toolbox, you will require an additional updated file (evriio.p).

4. Start MATLAB and change the working directory to the installation folder.
5. Enter the command:

   evriinstall silent

6. If prompted, enter a license code provided by EVRI.
7. If prompted, enter the IP address (or other DNS-accessible computer name), the port number (2212, unless otherwise specified by EVRI), and Access Code (supplied by EVRI).
   This information can also be included in a file named “evrilm.xml” and placed in the PLS_Toolbox/utilities folder. The format for this file is discussed below.
8. Verify the correct installation by typing the command

   pls test

   This should return your serial number and today’s date.

Simplified Network Installation

In order to reduce the effort required to install PLS_Toolbox with License_Server on multiple clients, a file named “evrilm.xml” can be created containing the server information. This file, when placed in the PLS_Toolbox/utilities folder will be used for the default server configuration. The file should contain the following XML code:

<info>
<serveraddress>''ip_address''</serveraddress>
<serverport class="numeric">2212</serverport>
<accesscode>''serial_number''</accesscode>
</info>

Where ip_address is replaced with the IP address or DNS-resolvable computer name, 2212 is the port address, and serial_number is the supplied Access Code (usually your site license serial number).

If all three files (evrilm.xml, evrilicense.lic, and evrinetwork.lic) are available and stored in the PLS_Toolbox/utilities folder, the installation of PLS_Toolbox on a new client computer can be reduced to simply:

1. Change the MATLAB working directory to the PLS_Toolbox folder
2. Run the command: evriinstall silent
3. Verify operation using: pls test

If an evrinetowrk.lic file has been stored in the utilities folder and PLS_Toolbox and all sub-folders have been added to the Matlab pathdef.m file stored on a server-mounted copy of Matlab, then the above steps will not be necessary. In this case, Matlab will already have PLS_Toolbox on its path when started by any user and users will not have to run any install procedure. To add PLS_Toolbox to the default path, simply start Matlab as an administrator with write privileges for the folder containing pathdef.m.

Client Configuration: Releasing Licenses in PLS_Toolbox

By default, PLS_Toolbox does not explicitly release a license back to the server (i.e. mark it as available for use by others) because it is called from within MATLAB and the ending of a session may not be clear. The user can, however, “release” a license when done using it by executing the command:

pls release

This command will tell the server that this user is done using the given license (if any.) This command could also be placed into a file named “finish.m” anywhere on the MATLAB path to automatically release a license when the user closes MATLAB. This feature is of particular use when using longer timeout periods on the license server (see Server Configuration options.)

Changing the Server IP Address

After PLS_Toolbox has been configured to access the license server, the IP address for the license server can be changed (if, for example, you need to access the license server from outside a firewall) using the following command:

setpref('EVRI_LM','serveraddress',' aaa.bbb.ccc.ddd ')

Where aaa.bbb.ccc.ddd is the new IP address. Note that this must be done immediately after starting up Matlab and before any PLS_Toolbox commands are used.

If an evrilm.xml file was used to originally configure PLS_Toolbox to locate the server, you can return to the original server IP address using the command:

evriclearlicense

If no evrilm.xml file was used, this command will re-prompt you for a new license code and server information.

Using Reserved, Extended-Period Licenses

If the server has been configured to provide extended-period licenses then PLS_Toolbox on a client computer can access them in any of three ways:

a) use the Workspace Browser menu: "Help > Reset License" then enter new access code

b) use the command: evriclearlicense

c) use the command: setpref('EVRI_LM','accesscode','zzz')

where 'zzz' is the access code for extended-period licenses specified by the administrator, as described above.

Client Configuration: Solo

Follow the standard installation instructions for Solo, however, when the license code is requested, enter the specific code provided by EVRI. You will then be prompted to enter the IP address (or other DNS-accessible computer name), the port number (2212, unless otherwise specified by EVRI), and Access Code (supplied by EVRI).*

Once connection to the server is made and the license is verified, Solo will operate as expected. If Solo sits unused for a period of time, you may lose your license on the server and may have to wait for a new license to become available. Leaving Solo open during this time will allow you to pick up your work where you left off.

As with PLS_Toolbox configuration, an evrilm.xml file can be used to define the default server information. This file should reside in the top-level Solo folder. In addition, any valid evrilicense.lic file can be placed in this folder. (Note that PLS_Toolbox and Solo use different evrilicense.lic files so a separate file must be obtained for each product type.)

Changing the Server IP Address

After Solo has been configured to access the license server, the only way to change the IP address for the license server is to use one of the following:

• If an evrilm.xml file was used to originally configure Solo to locate the server, modify the file to contain the new IP address and restart Solo.

• If no evrilm.xml file was used, restart Solo and you will be re-prompted for a new license code and server information.

Using Reserved, Extended-Period Licenses

If the server has been configured to provide extended-period licenses then Solo on a client computer can access them by:

a) use the Workspace Browser menu: "Help > Reset License" then enter new access code specified by the administrator, as described above.