Installing Network Licenses

• Uncounted: the software may be used by any number of users
• Counted: there is a limit on the maximum number of concurrent users; once this limit is reached additional users will be refused access to the software until someone exits from the application.

Note that other license choices may be made available for some sites, whereby single unrestricted licenses are made available for use on any machine. These do not require installation of FLEXlm on a license server and are considered to be Individual Licenses.

If you are upgrading from an earlier version of GenStat and currently use a FLEXlm license please read here before continuing.

This document is intended as a simple introduction for sites that use Microsoft Windows on their network servers and client workstations. It assumes you do not currently use FLEXlm for other software products. No previous knowledge of FLEXlm is required. Many other configurations are possible: for example a Unix-based license server with client PCs running Windows. Larger networks may already operate FLEXlm for other software products and will need merely to add additional information to their license file in order to run applications from VSN. You should refer to the FLEXlm documentation or contact VSN support (support@vsni.co.uk) for further information.

Full documentation for FLEXlm is provided on your application CD-ROM. It is located in the folder

FLEXlm\License\htmlman\flexuser

A brief guide to installing FLEXlm on Unix license servers can be found in the file

FLEXlm\unix.txt

FLEXlm Basics

The FLEXlm license management software will need to be installed on the license server. This will run constantly in background mode; on Windows NT and later systems it will operate as a system service. You will separately apply for a license key which will contain details of the software application (e.g. GenStat), version control, and number of licenses, as well as details of the license server it can run on. Once this key is installed, the application can be run on any PC on the network. When it starts up it will communicate with FLEXlm and request a license. FLEXlm keeps a record of how many licenses are in use at any time and will refuse requests once the specified limit is reached. When the system is busy, users will have to wait until someone terminates their use of the program, thus releasing a license.

For sites that license a number of applications from VSN International, the license file can contain keys for each application. The one license process will manage licenses for all the applications.

The application itself can be installed on any machine on the network. It can be installed in a public folder on the license server or other file server, on individual users PCs, or any combination of these options. Whichever machine it is run from, it will always contact the specified license server to check out a license.

Each step is numbered in the instructions that follow. Please keep to this sequence; if things go wrong please stop and ask for help from support@vsni.co.uk, quoting the step number and any other information you think is relevant.

Installing FLEXlm on a Windows NT or 2000 Server

• Step 1. Setup FLEXlm on the license server.
  Identify the machine you want to use as a license server. This must be a networked PC, visible to all desktops that will require access to the licensed applications. Login as Administrator to this server. Insert the application CD-ROM in the appropriate drive and from the initial menu select the option "Install FLEXlm license components". This will copy a number of files from the CD to the folder C:\FLEXlm. This folder will be referred to later in this document; you can use another location if you prefer, but remember to change the references that follow.

  The following files will be copied to the server:

  lmgrd.exe	The FLEXlm license manager
  lmtools.exe	A Windows interface to FLEXlm configuration
  lmutil.exe	A command-line interface to FLEXlm
  VSN.exe	The Vendor daemon, controls licenses for VSN products
  VSNLicenseSetup.exe	A program that generates a license request and completes FLEXlm installation
  VSNLicenseSetup.chm	Help for the VSNLicenseSetup program
  htmlman	A folder containg FLEXlm end-user documentation

  If you encounter problems running InstallShield you can copy the above files manually from the CD-ROM or download, from the folder "FLEXlm\License\Bin\i86_n3".

  The InstallShield package will launch the program VSNLicenseSetup.exe before terminating. This will appear on the screen as follows:

  

  If this Setup dialog does not appear on your screen you can start the program yourself by double-clicking on C:\FLEXlm\VSNLicenseSetup.exe.
  
  

• Step 2. Obtaining a license key
  Please complete the license application displayed on the screen, and then Save to a file or Copy to the clipboard, in order to send a license request to support@vsni.co.uk. A license file (VSN.lic) will be returned by email.

  You should now proceed to the second part of the Setup dialog. This will install the FLEXlm service using a dummy license file. Please check the locations of the files are correct, and specify a named log file if you wish to keep a record of any messages generated by FLEXlm. Click "Install Service" to complete this step.

  Note that if a FLEXlm service is already running the Install Service button will be disabled and you will need to configure the service manually (using lmtools.exe).




• Step 3. Set up the license files
  Your license key will normally be sent out by email. The message should contain two attachments: VSN.lic and appname.lic both of which should be saved to the folder C:\FLEXlm. VSN.lic will replace the dummy file created above.

  The license information is repeated within the body of the message in case you are not able to access the attachments, in which case the two files can be produced using Notepad. Each file may contain comment lines prefixed by the # character. In addition, vsn.lic should contain three lines, as follows:

  SERVER
VENDOR
FEATURE

  The SERVER line will contain the hostname and hostid information you supplied in the license request. It also specifies the TCP/IP port number that FLEXlm will use, as specified in the request (default 6983). Normally, you should not modify this line, although you can change the port number if required. Note that appname.lic also specifies the port number and the two files must use the same value.

  The VENDOR line specifies the name and location of the VSN license daemon, VSN.exe. If you have used the default location specified above the license file will already contain the correct information in this line, but if you have chosen another location for the files you must change this line to specify the folder you specified in Step 1. Edit the VENDOR line to read as follows:

  VENDOR VSN local-directory-path\VSN.exe

  Take care to ensure that the daemon-name, VSN, is specified as well as the full pathname for VSN.exe.

  The FEATURE line specifies the application name (e.g. GenStat), version control, number of licenses, etc. This line may have been split or reformatted by email software, so please check it is complete, ensuring that any new-lines are immediately preceded by "\". There should be no spaces following the "\" at the end of each line. It should look something like this:

  FEATURE GenStat VSN 0606 permanent 4 PLATFORMS="i86_n" \
SIGN="124C 6B43 0110 89BA B348 0658 8061 26B6 F238 \
B1DB FD17 6529 D8CC C63E FA0A 18A9 1598 5F7B F915 20D2 1A05"

  The important points to note in the FEATURE line are the product name (GenStat), version code (0606), expiry date (permanent) and number of concurrent users (in this case 4). This key is valid for any version of GenStat with a version code less than or equal to 0606. See License Details for a list of codes required for different software versions.

  Appname.lic should not require modification. Its contents are discussed below, in Step 6.




• Step 4. Restart FLEXlm and check that it can read the license file.
  Start the program C:\FLEXlm\lmtools.exe. Ensure that "Configuration Using Services" is selected and then select the tab Start/Stop/ReRead. Press the button ReRead License File to activate the new licenses.

  Check that the license file has been read successfully by switching to "Server Status" and pressing "Perform Status Enquiry". The log output produced by this command should indicate that the VSN daemon is running and the appropriate number of application licenses are available.




• Step 5. Install a copy of the Application on the license server.
  If you have not already done so, you should install the licensed software on the license server, from the CD-ROM. Just insert the CD-ROM and follow the InstallShield wizard. Alternatively, if you have already installed it on a networked file server that will be sufficient for testing purposes.



• Step 6. Check that the application runs on the server.
  When the application starts up it needs to know about the license server so that it can request a license from FLEXlm. Details of the server are specified in the file appname.lic, supplied along with the main license file. The software expects to find this file in one of two main locations:
  1. C:\Program Files\Common Files\VSN International\Licenses
  2. C:\Program Files\appdir\Bin
  The first location is preferred when the software is installed locally, as it will simplify installation of software updates in the future. When a new version is installed it will find the key in "Common Files" and run immediately, if still valid. The application Bin directory is more suitable for copies of the software that are installed on networked drives or file servers so that they can be accessed by multiple users.

  Copy appname.lic to the chosen location. The file should contain just two lines:

  SERVER hostname hostid port
USE_SERVER

  where the server hostname and hostid details relate to your license server, and the port number specifies a TCP/IP port to be used for communication between the application and license manager. This line should be identical to that in VSN.lic.

  Now try running the application, either from Start/Programs or by double-clicking the executable file.

  This should launch the software and go straight into the program. You should try running a small example to ensure that it is operating correctly. The presence of any messages about licenses or demo keys will indicate some kind of error which you should report to support@vsni.co.uk.




• Step 7. Test the application on a client PC
  Go to a client PC - any desktop that is not the license server. Install the software on this PC from the CD-ROM. Copy the appname.lic file from the server to the local PC, into the C:\Program Files\Common Files\VSN International\Licenses folder and check that the program runs successfully on this PC, as in Step 6.

  Alternatively, if you do not want to install the software on individual desktops you can run it from a networked file server. When installing on the server you just need to copy appname.lic into the Bin folder, as above. On the client PC you can create a desktop shortcut that points at N:\...\appdir\Bin\appname.exe.



Step 8. Install software on other PCs
To complete the installation you should repeat Step 7 on each PC that requires access to the application. You can choose whether to install on individual PCs or just set up desktop shortcuts to access a copy on the network, whichever is more convenient. Each PC that has a copy of the software installed will also require a copy of appname.lic in one of the locatioins specified in Step 6.

Troubleshooting

• Invalid license key (inconsistent authentication code)
  This message is generated by FLEXlm when it reads the license file. It usually means that there is a problem with the FEATURE line. Please compare what you have specified in the FEATURE line with the original email containing the license key. Ensure that if the line is wrapped on screen the separate fragments are joined into a single line in the license file.



• Cannot find SERVER hostname in network database This may also be accompanied by "winsock: host not found (HOST_NOT_FOUND)". FLEXlm produces these messages if the operating system cannot provide a proper translation for the server named in the appname.lic file. This can often arise on just one or two PCs on a network because of incorrect configuration of their network software and can be solved by amending the \etc\hosts file on the PC or by trying more explicit specification of the server name in appname.lic. For example, the fully-qualified domain name (e.g. server.company.com) or the IP address can be used instead on the SERVER line.



• License File does not support this version
  This means that you need to update the FEATURE line in the license file (C:\FLEXlm\vsn.lic). If you have already done this you may need to run lmtools and re-read the license file. If this does not solve the problem you should use the Windows Control Panel to Stop and then restart the FLEXlm license service.

  This error can also occur if there are multiple FEATURE lines for the same software product in the license file. Only the first FEATURE line for a product is used so you should ensure that any old FEATUREs are deleted or made into comments by prefixing with the "#" character.




• I keep getting the License Manager Dialog
  If you have installed FLEXlm correctly but keep getting the initial license dialog offering the choice of a trial key or license registration this means that you have not set up the server information on the client PC. To do this you must copy appname.lic into one of the locations specified in Step 6 (or set one of the environment variables listed below).



• License server does not support this feature
  If you receive this message when starting up it means that FLEXlm is running but has not loaded a FEATURE line for the application. This may be due to an error in the license file, or you may need to re-read the file or restart the service.

Frequently Asked Questions

• FAQ 1. Do I need a new license for a software upgrade
  The license key (FEATURE line of VSN.lic) includes a code based on the expiry of your product support. For example, if your support expires during November 2005 the code will be 0511. The key will then be valid for any software version or upgrade issued before the end of November 2005. Note, this support expiry code is different to the license expiry date, which may be a specific date (e.g. 22-mar-2006) or "permanent". If the key contains a specific expiry date it will not be valid after that, for any version of the software.

  The current list of product date codes is given in License Details. The minimum support date required for future updates or service packs will be indicated on the relevant download pages.

  When you renew support you will get a replacement VSN.lic with new support expiry code, thus providing access to future upgrades.

  Some older software versions, e.g. GenStat 7.1 or earlier, ASReml 1.x, SAMM 1.x, used different license systems and will require a new key. See Updating FLEXlm for details of updating old GenStat FLEXlm licenses.




• FAQ 2. What happens if the number of licenses is exceeded
  Once the number of concurrent users reaches the limit specified in the license no more users are allowed to use the application. If they try to start the program they will see receive a warning message and the software will then exit. The user should then try again later, when hopefully, one of their colleagues will have released a license. If this situation arises sufficiently often you may want to consider increasing the number of licenses.



• FAQ 3. What happens if the server is changed or reconfigured?
  If you reconfigure your server, e.g. new network card, or change your server you will need to apply for a new license key. To generate a new license request, please run the program C:\FLEXlm\VSNLicenseSetup.exe on the new or reconfigured server, as described above in Step 1.

  When you receive the new key you will have to update the license file on the server as described in Step 3. You will also need to update the appname.lic files on the client PCs to include the new server details.

  If you have changed your server you will also need to re-install FLEXlm as outlined in Step 1.




• FAQ 4. Can I use older NAG license keys as well as my new key?
  Older GenStat license keys that refer to the NAG vendor daemon are not valid for versions of GenStat beyond 7.1. However, older Windows versions of GenStat can use a VSN FLEXlm key if they have their license component upgraded. The upgrade can be found in the folder FLEXlm\License\old_genstat, along with the file Readme.txt which explains how to install the patch.

  Older versions (1.x) of ASReml and SAMM cannot be patched for the new style license keys. If you wish to install a network license you will have to upgrade to version 2.0 or higher.

Using GenStat with other license-managed software

IMPORTANT NOTE: VSN applications are configured to use FLEXlm in the following way. On startup they will look for a license file in the following locations, in order:

1. C:\Program Files\Common Files\VSN International\Licenses\appname.lic
2. appdir\Bin\appname.lic
3. appname_LICENSE_FILE environment variable
4. VSN_LICENSE_FILE environment variable
5. LM_LICENSE_FILE environment variable

Further help

This document may be revised from time to time. Updates will be posted on the VSN International web site http://www.vsni.co.uk