P IPENET PIPENET VISION FLEXlm LICENSING ADDITIONAL TROUBLESHOOTING S U N R I S E S Y S T E M S L I M I T E D, 2 0 0 7
T A B L E O F C O N T E N T S 1 TROUBLESHOOTING...4 2 FLEXLM SERVER...5 2.1 FLEXlm Server...5 2.2 FLEXlm Using The Host MAC Address...5 2.3 FLEXlm Using A Hasp USB Security Key... 6 2.4 The Licence File...6 2.5 Checking The Correct Server Name And Host Id... 6 2.6 Checking The Installation Of The Hasp Security Drivers...7 2.7 Checking The Licence Server Is Running...8 2.8 Firewalls... 8 2.9 Multiple Domains... 9 2.10 The Log File... 9 2.11 Check Summary... 9 3 CLIENT COMPUTERS... 11 3.1 Check Summary... 12 4 COMMON ERROR MESSAGES... 13 4.1 Licence Manager Errors -2, -8, -11, -13, -16:...13 4.2 Licence Manager Error -3: Cannot Connect To Licence Server... 13 4.3 Licence Manager Error -4: Licenced Number Of Users Already Reached... 13 4.4 Licence Manager Error -5: No Such Feature Exists...13 4.5 Licence Manager Error -9: Invalid Host... 14 4.6 Licence Manager Error -10:Feature Has Expired...14 4.7 Licence Manager Error -12: Invalid Returned Data From Server...14 4.8 Licence Manager Error -14: Cannot Find Server... 14 4.9 Licence Manager Error -15: Cannot Connect To Licence Server... 15 August 1, 2007 Page 2 SSL/UI/0009/04
4.10 Licence Manager Error -18: Licence Server Does Not Support This Feature...15 4.11 Licence Manager Error -31: Feature Not Yet Available... 15 4.12 Licence Manager Error -88: Licence Checkout Failed... 15 4.13 Licence Manager Error -92: Feature Removed During Lmreread, Or Wrong Server Line Hostid...16 4.14 Licence Manager Error -96: Checkout Failed Server Node Is Down Or Not Responding...16 4.15 Licence Manager Error -97: The Desired Vendor Daemon (sunrise.exe) Is Down... 17 5 COMMON LOG FILE MESSAGES...18 5.1 Retrying Socket Bind... 18 5.2 License Manager: Can't Initialize: Error -1: Cannot Find License File...18 5.3 Invalid License Key Error -8: Inconsistent Encryption Code... 18 5.4 Multiple Sunrise Servers Running... 18 5.5 Cannot Find SERVER Hostname In The Network Database Error -14?...18 August 1, 2007 Page 3 SSL/UI/0009/04
1 T R O U B L E S H O O T I N G To function, a FLEXlm environment involves correct configuration of the licence server and one or more client computers. Th following information is supplied as supplementary material to that provided in the FLEXlm installation guide and may assist in resolving installation issues. There are some issues that cannot be covered here, such as issues arising out of the customer's network configuration, firewalls, multiple domains and TCP port restrictions for example. For these issues the customer should refer to the FLEXlm end user guide supplied on the Network CD. Additional information may be available from the Macrovision website www.macrovision.com. In general Sunrise Systems will only recommend changing the licence file by editing the server name on the SERVER line. Other changes are possible, for example changing port numbers, daemon names, etc. If other changes are made then it may be difficult to resolve any issues arising, since Sunrise Systems is usually unable to visit client premises. Therefore the additional information provided in this document should only be used by distributors and clients with knowledge of Windows and network administration. Since PIPENET is a Windows program it is naturally assumed that client computers are running some version of a Windows operating system. The licence server however, could be running either Windows or Unix/Linux. The information provided here is generally applicable to both systems, except that for Unix/Linux systems the equivalent command line tools will be used instead of LMTOOLS, for example lmstat, lmdiag, etc. Before proceeding further please ensure that you have the current version of the second Network CD. This is labelled 'Network Configuration (CD 2)' and will have been supplied with the main PIPENET installation disk. Attempting to use an older version of this CD may result in failures. The current the version number of the CD is SSL/MC/0013/07. Customers using a Unix/Linux server should download the appropriate server programs from the Macrovision website, but they will still require the Sunrise Network CD for the NetUtil program August 1, 2007 Page 4 SSL/UI/0009/04
2 F L E X L M S E R V E R 2.1 FLEXlm Server The FLEXlm server refers to the computer that is running the FLEXlm programs and where the licence file(s) is/are stored. The FLEXlm server can be any computer in the customer network, it does not have to be a server in the context of being a Windows or Unix server. No part of FLEXlm requires root services and we would recommend that lmgrd.exe is run as a non-privileged user. There are four or five main components to the successful installation of a FLEXlm server: 1. An encrypted licence file supplied by Sunrise Systems. Instructions for obtaining this licence file are provided in the installation guide. 2. The FLEXlm licence manager daemon program lmgrd.exe, supplied on the second network CD. This program is common to all products that are licenced using FLEXlm. 3. The Sunrise Systems vendor daemon sunrise.exe. This program is specific to PIPENET licenced products. 4. An encrypt/decrypt key to be used by the lmgrd.exe program for decrypting the licence file. 5. Depending on the source of the encrypt/decrypt key to be used for decrypting the licence file, a HASP security key and its associated drivers may be required. The source of the encrypt/decrypt key will either be the Ethernet MAC address of the host computer or a HASP USB security key supplied by Sunrise Systems. 2.2 FLEXlm Using The Host MAC Address Usually FLEXlm licenced products will use the Ethernet MAC address of the host computer as part of the encrypt/decrypt key. Sunrise Systems have used this method in the past, and may continue to use it for short-term evaluation licences. One problem with this approach, is that if the customer wishes to move the FLEXlm server to another computer a new licence file is required and this can only be obtained from Sunrise Systems. FLEXlm will detect multiple Ethernet cards on the host computer, any of these may be used as the hostid, preferably the first in the list of cards. August 1, 2007 Page 5 SSL/UI/0009/04
2.3 FLEXlm Using A Hasp USB Security Key Sunrise Systems now use an alternative source for the encrypt/decrypt key, one stored in a Hasp USB security key, such as is used for licencing PIPENET on single computers. The licence file is obtained from Sunrise Systems in the same way, but it will be encrypted using an encrypt/decrypt key stored in the Hasp key. The Hasp security key and its associated drivers must be installed on the same host computer as the FLEXlm server. Instructions for achieving this are provided in the user installation guide. The main advantage of this approach is that the customer can move the FLEXlm server to another computer simply by installing the FLEXlm server software, the licence file and the Hasp security key on the new computer, it is only necessary to change the server name on the first line of the licence file. The licence file is a simple text file that can be edited using Windows Notepad for example. A typical first line would appear as: SERVER MYSERVER SunHostid=29D2E4D060FC9BE97C433B54AC6C where the server name is MYSERVER. Do not attempt to edit any other contents of this file, since this will almost certainly render the file unusable. It is important to note that the Hasp security key only exists to provide the encrypt/decrypt key in place of a MAC address, it does not include any licencing information. 2.4 The Licence File It is usual for a single read-only copy of the licence file to be accessible from all client computers, however, some FLEXlm environments may be set-up with each client having their own copy of the licence file. This is perfectly valid except that care must be taken to ensure that customer copies are updated at the same time. 2.5 Checking The Correct Server Name And Host Id If FLEXlm licencing is based on the use of the Host MAC address then the server name and MAC address can be checked using the LMTOOLS utility provided on the second network CD. Run LMTOOLS, select the System Settings tab and the host information will be displayed. August 1, 2007 Page 6 SSL/UI/0009/04
The server name and MAC address can be checked with that found on the first line of the licence file. If they do not agree, then the server name can be changed but not the MAC address. If the MAC address is incorrect please notify Sunrise systems by email to licencing@sunrise-sys.com, attaching a copy of the licence file. If FLEXlm licencing is based on the use of a Hasp security key then only the information that is relevant is the server name and this can be inspected or changed as specified above. The licence file is generated automatically by Sunrise Systems and it is extremely unlikely that the encrypt/decrypt key stored in the security key differs from that used to produce the licence file. Note that server names should not contain spaces or the '.' (stop) character, otherwise the server name and host id on the SERVER line of the licence file will not be correctly recognized. 2.6 Checking The Installation Of The Hasp Security Drivers If FLEXlm licencing is being used with a Hasp security key it is essential that the key is fitted to the FLEXlm server and that the key drivers are correctly installed. The security key drivers must be installed on the FLEXlm licence server computer. Installation of the key drivers is achieved by running the program KEYSETUP.EXE which can be found in the directory KeyCheck on either the main installation disk or the second network CD. This facility is also available via a tab in the NetUtil utility program, also provided on the second Network CD. Running this program produces the display: August 1, 2007 Page 7 SSL/UI/0009/04
Select the Install key drivers button to install the key drivers. Selecting the Check key drivers button will display the status of the key drivers, which if correctly installed will display the date of installation and other information on version number of driver etc. Selecting the Remove key drivers button will un-install the drivers. The most common reason for failure of the key driver installation is lack of sufficient administrator rights. The Remove key drivers button will un-install the key drivers and the Check key button will display the number and customer name in any fitted key, assuming the key drivers are installed and working. 2.7 Checking The Licence Server Is Running Use LMTOOLS and the Server status tab to check if the server is operational and that the licence file is being accesses. Selecting the Perform Status Enquiry will display the server and licence status. 2.8 Firewalls If your site has an Internet firewall you should specify the TCP port number to be used by the program sunrise.exe. This is the FLEXlm vendor daemon installed on the license server computer and used to communicate with each PIPENET application. The port number can be any unused port number in the range 1025 48000. An alternative port number is specified in the licence file on the VENDOR line as VENDOR sunrise port=xxxxx Please refer to the end-use guide for further information on port numbers and network issues. Port numbers in use can be checked using the netstat command. August 1, 2007 Page 8 SSL/UI/0009/04
2.9 Multiple Domains FLEXlm can be used successfully in situations where there are multiple domains, with the FLEXlm server and one or more client computers being in different domains. Refer to the end-user guide for further information, as this will require knowledge of networking. Essentially you will need to ensure that: a fully qualified host name is provided on the SERVER line of the license file all client computers, as well as the server node, are able to connect to the host for example by using 'telnet' to the fully-qualified host name. 2.10 The Log File The log file may provide useful information on failures and can be found in the location specified during the installation, specifically in the Config Services section of LMTOOLS. In the event of any failures this file should be emailed with any supporting information to licencing@sunrise-sys.com. See section 5 for details of some common error messages to be found in this file. 2.11 Check Summary 1. The necessary programs are installed on the host computer according to the installation instructions. 2. The Sunrise Daemon sunrise.exe is in the same directory as the lmgrd.exe file. It can be in another directory but this requires changes to the VENDOR line in the licence file refer to the FLEXlm end-user guide for further information. 3. The licence file is installed on the host computer and has the correct server name. 4. The licence file resides in a directory accessible to client computers. 5. Issues with port numbers and firewalls have been resolved (see section 2.7) 6. LMTOOLS has been correctly configured (Config services tab) to point to the correct file locations. 7. The Licence server is running the server is started using LMTOOLS and the Start/Stop Reread tab. 8. Licences are available use LMTOOLS and the Server Status to display the status of the server and the licences. August 1, 2007 Page 9 SSL/UI/0009/04
9. Check that network connection between the client computer and the FLEXlm server computer. A simple approach is to use the ping hostname command from the client computer to check connection to the licence server. 10. Confirm that the licences available (LMTOOLS Server Status tab) agree with what is expected. Occasionally the person installing the software will not be aware of which PIPENET modules are licenced and may attempt to perform a test using a module for which no licence is available. August 1, 2007 Page 10 SSL/UI/0009/04
3 C L I E N T C O M P U T E R S In addition to installing the PIPENET software on a client computer, the NetUtil utility must be run Each client computer must be configured so that it can find the licence file this is achieved using the NetUtil utility provided on the second Network CD. Running this utility displays: It is only necessary to select the FLEXlm option, specify the location of the FLEXlm licence directory, and select OK. The information is stored in the Windows System Registry at the location: HKEY_CURRENT_USER\Software\Sunrise PIPENET\PIPENET\Settings-Paths Note the FLEXlm license directory field may not be blank. If the directory specified is incorrect then one of the following will occur when an attempt is made to run a PIPENET module: 1. If there are other FLEXlm licensed products on the workstation and the directory where the licenses for these programs is stored is the same as that for PIPENET then the module should run using information contained in the System Registry or: 2. The execution of PIPENET will stop at the point it attempts to obtain the license and you will be prompted to supply the name of either the FLEXlm li August 1, 2007 Page 11 SSL/UI/0009/04
cense server or the license directory this information should be supplied by the customer's IT department. Note the Install Key Driver and Install license Manager tabs are not used on client computers for FLEXlm licencing, and the customer name field has no relevance to FLEXlm licencing. Note the location of the licence file may be on a shared drive, so that every client computer has read-only access to the file. It is also possible for each client to have their own copy of the file, but doing this could result in licence files becoming out of step. 3.1 Check Summary 1. Confirm that NetUtil has been run and correctly configured to use FLEXlm licencing and that the reference to the licence file is correct. 2. Confirm that the licences available (LMTOOLS Server Status tab) agree with what is expected. Occasionally the person installing the software will not be aware of which PIPENET modules are licenced and may attempt to perform a test using a module for which no licence is available. 3. Check that the client computer can access the licence file 4. Check that licences are available, it is possible that the maximum concurrent users count has been reached and no more licences are available. 5. Check that no local Sunrise systems security key is fitted to the client computer. If it is, then PIPENET will attempt to use the key and ignore FLEXlm licencing. August 1, 2007 Page 12 SSL/UI/0009/04
4 C O M M O N E R R O R M E S S A G E S A complete list of error messages is provided in the end-user guide, however, the following are the most common that are likely to occur when using PIPENET. Error message numbers are made up from a negative number followed by a positive number of the form -mmm, nnn - we are only interested in the negative number. 4.1 Licence Manager Errors -2, -8, -11, -13, -16: All of these errors point to a corrupted, incorrectly edited, or otherwise invalid, licence file send a copy of the licence file together with any supporting information to licencing@sunrise-sys.com. Supporting information should include the name of your server and a copy of the FLEXlm log file. 4.2 Licence Manager Error -3: Cannot Connect To Licence Server This error can occur if the SERVER line in your License File is incorrect or missing. Also check if there are multiple vendor daemons (sunrise.exe) running on the server. If there are, stop the licence manager, kill the vendor daemon processes and restart the licence manager. The presence of multiple vendor daemons can be confirmed by inspecting the FLEXlm log file and seeing if the message: is present. Multiple Sunrise Servers Running" 4.3 Licence Manager Error -4: Licenced Number Of Users Already Reached The maximum number of concurrent users for a particular feature (licence) has been reached. The user should check with the appropriate authority to determine how many concurrent users are allowed for a feature, and whether additional licences should be ordered. 4.4 Licence Manager Error -5: No Such Feature Exists This is usually because a user is trying to use a feature for which no licence is available, for example, they may be attempting to run the PIPENET Transient module but only have a licence for the Standard module. This can occur if the software is being installed by and IT department who may not be aware that there are separate PIPENET modules and each has to be licenced separately. August 1, 2007 Page 13 SSL/UI/0009/04
A less likely alternative is that the customer has edited the licence file and inserted extra carriage returns the licence file should not contain blank lines. 4.5 Licence Manager Error -9: Invalid Host This indicates a problem with the server installation, specifically that the hostid in the licence file does not match that host computer - the customer's IT department should check the installation. For installations using a Hasp security key to source the hostid make sure that the key is fitted to the licence server and that the associated drivers are correctly installed (see section 2.5). For customers who are using the MAC address of the host computer check that this agrees with the address in the SERVER line of the licence file. 4.6 Licence Manager Error -10:Feature Has Expired A PIPENET module for which a licence has been obtained has expired, that is the current date is after the expiry date which can be found on the FEATURE line in the licence file. In the first instance the user should confirm the availability of licences with the necessary authority, who will then contact Sunrise Systems if a new licence is to be purchased. If none of the product licences has expired check that the system time and data are correct. 4.7 Licence Manager Error -12: Invalid Returned Data From Server This may be a problem with port numbers on the licence server try stopping and restarting the licence server. Port numbers in use can be checked using the netstat command. This problem can also be due to the way in which the network has been setup and the solution may depend on whether or not all client computers are experiencing this problem. If they are then than change the server name on the SERVER line in the licence file to the fully qualified file name (e.g. server.mycompany.com). If only some users are experiencing problems then it is probably an issue with the TCP/IP hosts file. 4.8 Licence Manager Error -14: Cannot Find Server This probably indicates that the server name on SERVER line of the licence file does not match the name of the server where FLEXlm is installed. August 1, 2007 Page 14 SSL/UI/0009/04
4.9 Licence Manager Error -15: Cannot Connect To Licence Server This usually indicates that the licence server is not running, or that a client computer cannot connect to the server computer. The customer's network administrator should check for both of these conditions. The command ping hostname can be used from the client computer to check connection to the licence server. This error can also occur when a lookup for the host name on the SERVER line in the license file failed. This often happens when NIS (Sun's Network Information Services) or DNS or the hosts file is incorrect. This can be confirmed by substituting the IP address of the FLEXlm server (e.g., 123.456.789.124) for the host name on the SERVER line of the licence file 4.10 Licence Manager Error -18: Licence Server Does Not Support This Feature Most likely cause is changing the licence file without re-starting the licence server. It is usual for the single read-only licence file to be accessible from all clients, however, some FLEXlm environments may be setup with each client having their own copy of the licence file. This is perfectly valid except that care must be taken to ensure that customer copies are updated at the same time. 4.11 Licence Manager Error -31: Feature Not Yet Available Licences issued by Sunrise Systems have both a start date and an expiry date. If a licence file is issued as a replacement for an existing licence file, the start date may be in advance of when the customer receives the licence file, allowing a few days overlap with the original licence. Attempting to use the licence before the start date will produce this error. 4.12 Licence Manager Error -88: Licence Checkout Failed If you are fortunate this probably indicates that the system time is set incorrectly on the host computer it may have been set back reset the clock to the correct time and everything should work. A more serious situation can arise when the clock is inadvertently set to a date in advance of the current date and subsequently the administrator detects the error and sets the system clock back to the correct time. If the FLEXlm server has not been started in the period between setting the clock forward and setting it back, then again there should be no problem when the FLEXlm server is started. August 1, 2007 Page 15 SSL/UI/0009/04
For both of the above situations, if you are still getting this error then the next thing to try is to restart the host computer and try again, before considering the following possibility. If you set the clock in advance of the correct time, start the FLEXlm server and then set the clock back to the correct time then this is a serious error and it may require a major effort to recover. Never do this: always check, double check and re-check the system date and time before starting the FLEXlm server. If you have made this error then: 1. Use the Windows Explorer Search facility to locate all of the files on the host computer with the incorrect time/date stamp, that is one in advance of the correct date. 2. Identify all the files that may be related to FLEXlm in some way, licence file, log file, files in the FLEXlm directory, etc. 3. Copy the files to a new directory - this will give the copied versions a correct date 4. Replace the original files with the coped versions 5. Try again. 4.13 Licence Manager Error -92: Feature Removed During lmreread, Or Wrong Server Line Hostid Lmreread, which is executed on the licence server, either directly or via the LMTOOLS Start/Stop Reread tab, has re-read the licence file and discovered that a feature (licence) was removed, but the client computer is still referencing an old version of the licence file. Check: That the licence file is installed on the server correctly and has not been corrupted, re-install if necessary. Check that the client computer is referencing the same licence file by running the NetUtil utility. An alternative cause of this error is that the SERVER line in the licence file has been changed for a different host and all licences have therefore been removed. 4.14 Licence Manager Error -96: Checkout Failed Server Node Is Down Or Not Responding May simply be that the FLEXlm server is not running, check for lmgrd.exe active on server. Another possibility is that there is a conflict with the host name or port August 1, 2007 Page 16 SSL/UI/0009/04
check that the host server name is the same as that specified on the SERVER line of the licence file. 4.15 Licence Manager Error -97: The Desired Vendor Daemon (sunrise.exe) Is Down Ensure that the file sunrise.exe is installed and in the same directory as lmgrd.exe. It can be another directory but this would require changes to the SERVER line in the licence file (see section 2.10 item 2). Indicates that the FLEXlm daemon lmgrd.exe is running but not the vendor daemon sunrise.exe. This could be because the vendor daemon is running from a previous attempt to start the licence manager: 1. Use LMTOOLS to stop the licence manager 2. Use the Windows task manager to kill any sunrise.exe processes that are running 3. Restart the FLEXlm licence manager If this doesn't work try re-booting the host computer, if this still doesn't work it could be a problem with the vendor daemon attempting to use an occupied port. By default the vendor daemon will use a port in the range 27000 to 27009, try using another port (see section 2.7), for example one in the range 1700 to 1711. Port numbers in use can be checked using the netstat command. August 1, 2007 Page 17 SSL/UI/0009/04
5 C O M M O N L O G F I L E M E S S A G E S The following sub-sections provide information on some of the error messages in the log file. Many other messages may appear in this file, but these are mainly informative messages indication that a licence has been checked out/in, a licence has expired, server has been restarted, etc. 5.1 Retrying Socket Bind This means the TCP port number is already in use. Almost always, this means the lmgrd is already running, and an attempt has been made to start it a second time. It can also mean that the port number is in use by another program, but this is much less likely 5.2 License Manager: Can't Initialize: Error -1: Cannot Find License File This means you've specified a non-existent file when using LMTOOLS Setup Config. 5.3 Invalid License Key Error -8: Inconsistent Encryption Code This almost certainly indicates a problem with the licence file a copy of the licence file together with the log file should be emailed to licencing@sunrise-sys.com. 5.4 Multiple Sunrise Servers Running There are two lmgrd and sunrise daemons running for this license file. Only one process per vendor-daemon/per node is allowed by FLEXlm to run. Sometimes this can occur because the lmgrd process was killed, leaving the sunrise process still running. 5.5 Cannot Find SERVER hostname In The Network Database Error -14? This may be a problem with DNS -see section 4.9 for further information. August 1, 2007 Page 18 SSL/UI/0009/04