Source: Licensing: Troubleshooting
Licensing: Troubleshooting
By the Citrix Publications Department
Citrix® Systems, Inc.
Notice
The information in this publication is subject to change without notice.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. CITRIX SYSTEMS, INC. (“CITRIX”), SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR DIRECT, INCIDENTAL, CONSEQUENTIAL OR ANY OTHER DAMAGES RESULTING FROM THE FURNISHING, PERFORMANCE, OR USE OF THIS PUBLICATION, EVEN IF CITRIX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.
This publication contains information protected by copyright. Except for internal distribution, no part of this publication may be photocopied or reproduced in any form without prior written consent from Citrix.
The exclusive warranty for Citrix products, if any, is stated in the product documentation accompanying such products. Citrix does not warrant products other than its own.
Product names mentioned herein may be trademarks and/or registered trademarks of their respective companies.
Copyright © 2006 Citrix Systems, Inc., 851 W Cypress Creek Rd, Ft. Lauderdale, Florida 33309 U.S.A. All rights reserved.
Version History
Sept. 7, 1006
Tammy Jones
Original version
Licensing: Troubleshooting ii
Table of Contents
TROUBLESHOOTING………………………………………………………………………………………………………………………………………….1
SUMMARY…………………………………………………………………………………………………………………………………………………………….1
INTRODUCTION……………………………………………………………………………………………………………………………………………………..1
INSTALLATION ISSUES…………………………………………………………………………………………………………………………………………….2
Prompted to Upgrade the License Server……………………………………………………………………………………………………………..2
Unable to Check Out a License……………………………………………………………………………………………………………………………2
LICENSE ALLOCATION PROBLEMS……………………………………………………………………………………………………………………………3
Allocated Wrong Number of Licenses…………………………………………………………………………………………………………………..3
Moving from a Test Environment to a Production Environment………………………………………………………………………………..3
Wrong License Server Name……………………………………………………………………………………………………………………………….3
GENERAL LICENSING PROBLEMS……………………………………………………………………………………………………………………………..4
License Server Stops Checking out Licenses………………………………………………………………………………………………………….4
LICENSE MANAGEMENT CONSOLE PROBLEMS……………………………………………………………………………………………………………5
Unable to Authenticate……………………………………………………………………………………………………………………………………….5
Renaming the License Server………………………………………………………………………………………………………………………………7
Error Messages…………………………………………………………………………………………………………………………………………………7
Error Message Numbers…………………………………………………………………………………………………………………………………….7
Alerts……………………………………………………………………………………………………………………………………………………………….7
Historical Usage Reports……………………………………………………………………………………………………………………………………8
LICENSE FILE PROBLEMS………………………………………………………………………………………………………………………………………..8
Deleted or Corrupt Files…………………………………………………………………………………………………………………………………….8
TOOLS TO HELP YOU WHILE TROUBLESHOOTING………………………………………………………………………………………………………8
License Administration Commands………………………………………………………………………………………………………………………8
Debug Logs………………………………………………………………………………………………………………………………………………………8
SUGGESTED READING…………………………………………………………………………………………………………………………………………..10 Licensing: Troubleshooting iii
Troubleshooting
Summary
This whitepaper provides you with details about issues that you may encounter using Citrix Licensing. It is one of a series of whitepapers designed to provide you with more detailed information for tasks that extend beyond the scope of installing your licensing components and is designed to complement the Getting Started with Citrix Licensing Guide.
For a complete listing of the whitepapers, see the Getting Started with Citrix Licensing Guide in the Citrix Knowledge Center.
For additional help troubleshooting your Citrix Licensing issues, see the Licensing Information page in the Citrix Knowledge Center.
Introduction
Citrix Licensing allows you to quickly and easily license your Citrix products; however, at some point, you may need to troubleshoot licensing issues. This can occur in the following scenarios:
• You experience problems during the installation of the licensing system
• The licensing system stops working after it’s been running for some time
• A computer running a Citrix product cannot communicate with the license server and returns an error message
In many cases, the first indication of licensing issues is the appearance of an error message when a user tries to connect to a product. Typically, this error message indicates that a server exceeded its licensed logon limit. The error occurs when the product cannot obtain licenses from the license server.
Another sign of licensing issue
s is a Windows Event log entry on the product’s server that indicates the connection to the license server was lost. In this scenario, an error message is logged every hour to indicate the status of the grace period.
When the license server fails, or if there is a power failure, the Citrix product does not stop working immediately. As long as the product has communicated with the license server at least once, it enters a grace period automatically. The grace period allows the user to continue using the product for a specific period of time until the product can re-establish communication with the license server. When the product is in the grace period, it has access to all licenses stored on the license server. See your Citrix product’s administrator’s guide for the length of time allowed for the grace period.
Licensing: Troubleshooting 1
Installation Issues
The following section answers installation questions that you might have.
Prompted to Upgrade the License Server
Why am I prompted to upgrade my license server after I upgrade a Citrix product?
While it is always a good practice to upgrade the license server when you upgrade your Citrix product, certain releases require that you upgrade the license server for the product to work. For example, Presentation Server 4.5 release requires that you upgrade the license server. New versions of the license server are compatible with your existing license files.
You can find the most recent license server software on the product’s installation CD or on the Citrix Web site. See the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for help upgrading your license server.
Unable to Check Out a License
What should I do if I allocated licenses and downloaded the files to my license server but I’m unable to check out a license?
This procedure is designed to help you troubleshoot licensing problems that occur immediately following installation but before the product checks out licenses from the license server successfully.
• When you allocate licenses, you must enter the hostname of the license server in a case-sensitive format. It is possible that the hostname of the license server does not EXACTLY match the hostname entered in the license file. See the “To verify that the hostname is correct” procedure below.
• Verify that the product-side setting referencing the license server contains the right license server name. This setting can be at a farm-wide or server-specific level. Because this setting is product-specific, see the Administrator’s guide for your Citrix product to determine how to access it.
• Verify that the product is using the same port number as the license server. In addition, if there is a firewall between the product and the license server, a static port must be assigned and you must open both ports on the firewall. See the “Modifying Port Numbers” section in the Licensing: Firewalls and Security Considerations whitepaper in the Citrix Knowledge Center for information about port numbers.
• Ensure that the license file contains licenses for the desired product. For example, Presentation Server Enterprise edition works only if the license file specifies the Enterprise edition. See the “Understanding the License File Syntax” section in the Licensing: Understanding License Files whitepaper in the Citrix Knowledge Center.
Licensing: Troubleshooting 2
To verify that the hostname is correct
1. Open the license file you downloaded from MyCitrix to make sure that the hostname of your license server matches the hostname listed in your license file. You can open the license file with any text editor. By default, license files are stored in C:Program FilesCitrixLicensingMyFiles. License files end with the .lic extension.
2. Check the hostname listed in your license file.
3. Check the host name of your license server by typing HOSTNAME at a command prompt. The host name of the license server and the host name in your license files must match exactly in spelling and case. For example, if the name of your license server is LicenseServer1 and the host name in your license file is License server 1, the license server cannot use the license file. If the hostname of your license server and the name referenced in your license files do not match, you must return and reallocate the licenses into a different license file that references the correct license server name (or rename your license server). See the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for information about this process.
License Allocation Problems
The following section answers questions that you might have about allocation.
Allocated Wrong Number of Licenses
What should I do if I allocated too many licenses?
If you inadvertently allocated too many licenses and you want some of those licenses for a different license server, you can reallocate the extra licenses in a file that references a different license server name. For example, if you are entitled to 50 licenses and you want to allocate 25 licenses now, but you accidentally allocate 30 licenses instead and generated the license file, you must return and reallocate the extra licenses into a different license file that references the new license server name. This procedure is called rehosting your licenses. The extra licenses remain associated with the original license file until you rehost them.
See the “Moving or Renaming a License Server” section in the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for this procedure.
Moving from a Test Environment to a Production Environment
What should I do if I used some of my license entitlement for a test environment and now I want to use those licenses in a production environment?
Assuming that the license server in your test environment and the license server in your production environment have two different host names, you must return and reallocate the licenses into a different license file that references the new license server name. This procedure is called rehosting your licenses.
See the “Moving or Renaming a License Server” section in the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for this procedure.
Wrong License Server Name
What should I do if I entered the wrong license server name when I was generating a license file?
You must return and reallocate the licenses into a different license file that references the new license server name. This procedure is called rehosting your licenses. If you added the defective license file to the license server, you
Licensing: Troubleshooting 3
must delete the file before adding the newly generated corrected license file.
See the “Deleting License Files” and “Moving or Renaming a License Server” sections in the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for this procedure.
General Licensing Problems
The following section answers general licensing questions that you might have.
License Server Stops Checking out Licenses
What should I do if the license server stops checking out licenses?
This procedure assumes that your license server was successfully distributing licenses to the products before you began experiencing licensing issues.
Licensing problems can occur:
• On the license server
• On the product server
• With the connection between the product server and the license server
The following sections provide general troubleshooting procedures for licensing problems.
When you begin troubleshooting licensing problems, check for problems on the license server in the following order.
To check for problems on
the license server
1. Check for alerts in the License Management Console. Alerts can include warnings related to license usage and/or Subscription Advantage expiration dates. For information about checking for alerts, see the “Setting Alerts” section in the Licensing: The License Management Console whitepaper in the Citrix Knowledge Center.
2. If you are using evaluation licenses, make sure that they have not expired. See the “Understanding the License File Syntax” section in the Licensing: Understanding License Files whitepaper in the Citrix Knowledge Center.
3. Check to make sure the following services are running:
• The CitrixLicensing and the Citrix License Management Console services—you can find these services in the Windows Services panel
• The Web service (Internet Information Services or Apache)
If any of these services are not running, restart them. If restarting the services does not resolve the problem, look at the Event Log entries on the computer running the license server.
Tip: You can also run the lmstat command to see license usage. If you receive an error message saying that the Citrix vendor daemon or the License Manager daemon is not running, continue following these troubleshooting procedures.
4. If you still cannot detect the problem, open the debug log using any text editor. The debug log, lmgrd_debug.log, shows errors and events that occurred on the license server. By default, the log is stored at C:Program FilesCitrixLicensingLS.
5. After you ensure the licensing problem is not with the license server, check for problems on the computer
Licensing: Troubleshooting 4
running the Citrix product that stopped accepting connections.
To check for problems on the computer running the Citrix product
1. Verify that the following settings are correct. (Because the location of these settings differs depending on which product you have, see the administrator’s guide for your product to locate these product-side settings.):
• The license server settings matches the name and port number of your license server. Tip: If you are pointing to the license server by name, try entering the IP address.
• The product edition selected in the product matches the product edition in the Current Usage page in the License Management Console.
2. Check the event log entries on the computer running the product that stopped accepting connections. The event log may contain entries that indicate that you have ran out of licenses, the grace period expired, the number of hours left in the grace period, and so on.
3. Check the product’s readme file to make sure your problem is not the result of a known issue.
Important: If you change the system clock on either the computer running the product or the computer running the license server, your product’s requests for licenses are denied and the product stops accepting connections.
You can make sure there are no network problems affecting communication by:
• Running Netstat
• Pinging by name and IP address
To use Netstat to troubleshoot connectivity issues
1. Before running Netstat, locate and record the Citrix vendor daemon port number listed in the debug log. The Citrix vendor daemon port number changes every time the CitrixLicensing service is restarted, unless the port number is specified in the license file.
2. On the license server, type netstat – a at a command prompt. The output shows whether or not the License Manager daemon port and the Citrix vendor daemon port are listening. The line looks similar to the following example: Citrix Using TCP port #### . The output also lists all computers running a Citrix product that are connected to the license server.
3. Run Netstat on the computer running the Citrix product. The output indicates the state of the product’s connection. If the output does not list an established connection between the Citrix product and the Citrix vendor daemon port, there is no communication between the product and the license server.
License Management Console Problems
The following section answers License Management Console questions that you might have.
Unable to Authenticate
What should I do if I cannot authenticate to the License Management Console?
This issue occurs when logging on to and/or authenticating to the License Management Console. It happens because your license server is running in a different zone than the computer from which you are trying to authenticate.
Authentication to the License Management Console over a Windows network is based on Windows NT LAN Manager (NTLM) authentication. NTLM authentication is a challenge/response-based method of authentication. When the License Management Console prompts you for credentials as you log on from a remote computer, do the
Licensing: Troubleshooting 5
following:
• Make sure that you added the license server to your browser’s list of safe intranet sites.
• Try entering the domain name. That is, if you installed the license server in the HR domain, enter HRjoeuser.
Important: Unless you add other user accounts to the License Management Console, you can only access it using the credentials you used when you installed it on the license server. If you installed the License Management Console using your credentials for your local computer, you must use network credentials to add one or more additional user accounts to log on remotely.
I am unable to log on to the License Management Console from a Web browser that is running on a Windows 2003 Server. The license administrator, domain administrator, domain user, or local computer administrator credentials are not accepted.
Possible Cause 1
Internet Explorer’s security settings are not configured to allow local credentials to be passed through to servers listed in the Trusted Sites security realm.
See the CTX103835 technical note in the Citrix Knowledge Center for information about changing the settings.
Possible Cause 2
The administrator used a domain administrator account when installing the License Management Console and the domain administrator is the only user in the tomcat-users.xml file. As a result, the domain “user” account can never log on to the License Management Console. You must add additional users to the License Management Console. See the “Controlling Access to the License Management Console” section in the Licensing: The License Management Console whitepaper in the Citrix Knowledge Center.
Possible Cause 3
You could be running a Web browser that does not support NTLM. See the “Software Requirements” section in the Getting Started with Citrix Licensing Guide in the Citrix Knowledge Center for supported browsers.
Why don’t I see any options (besides language choices) on the Welcome screen?
You do not have access to the License Management Console. By default, only the user account that installed the console has access. To allow others to access the console, the user accounts need to be added to the User Administration section of the console. See the “Controlling Access to the License Management Console” section in the Licensing: The License Management Console whitepaper in the Citrix Knowledge Center.
How do I find out which user accounts have access to the License Management Console?
To see what accounts have access to the License Management Console, open C:Program filesCitrixLicensingLMCTomcatconftomcat-users.xml.
Licensing: Troubleshooting 6
Renaming the License Server
What should I do if the License Management Console does not work after renaming the license server?
If the License Management Console does not work after renaming the license server, you must uninstall licensing and reinstall it.
Error Messages
Why
do I see the following error message when I’m trying to view the Current Usage page: Alert: Can’t Connect to License Server. Verify that the License Server is running.
The CitrixLicensing service is not running. See the CTX104720 technical note in the Citrix Knowledge Center.
Error Message Numbers
Why do I see any of the following errors when I launch the License Management Console using a Web browser:
Address already in use
Address is being used by another process
You installed IIS and MetaFrame on the same server and you installed IIS after Presentation Server. The Citrix XML Service uses port 80 by default and IIS also uses port 80. This causes a conflict. Change the port that either the IIS or the XML Service is listening on, or share the XML Service with IIS. See the CTX104063 technical note in the Citrix Knowledge Center for information about modifying these ports.
Why do I see the following error message when I launch the License Management Console using a web browser: Error 404 page could not be found
You typed the URL incorrectly. The URL is case-sensitive. Retype the URL using the correct syntax and case.
Alerts
Why am I seeing red (critical) alerts on the Current Usage page of the License Management Console?
Red alerts are seen when the percentage of licenses in use, and Subscription Advantage and license file expiration dates approach the critical warning level.
You can foresee potential license logon rejections by regularly monitoring two report sources:
• Current Usage page of the License Management Console. The Current Usage page displays the number of licenses that are available for use on a license server. Because the Current Usage page provides real-time information, you use it in conjunction with Historical Usage reports to foresee problems.
• Historical Usage Reports. Run historical usage reports to see license availability and consumption information over time. By running reports over a quarter, for example, can indicate if license consumption is increasing. In large environments, Citrix recommends that you run licensing reports when you are planning upgrades and equipment acquisitions.
See the Licensing: The License Management Console whitepaper in the Citrix Knowledge Center for additional information.
Licensing: Troubleshooting 7
Historical Usage Reports
What should I do if I pressed Esc while the report was generating and the report froze?
Closing the reporting window or attempting to stop the report before it finishes could cause the reporting engine to hang. Restart the Citrix License Management Console Service.
License File Problems
The following section answers license file questions that you might have.
Deleted or Corrupt Files
What should I do if I accidentally deleted a license file?
If you corrupt or delete license files, you can download a replacement license file from MyCitrix. See the “Downloading Replacement License Files from Citrix” section in the Licensing: Understanding License Files whitepaper for this procedure. The license file that you download must have the same hostname as the license server you allocated the file to originally.
Tools to Help You While Troubleshooting
The following tools are useful for troubleshooting Citrix Licensing. These utilities are run at a command line after browsing to the C:Program FilesCitrixlicensingls directory.
License Administration Commands
The following Licensing Administration Commands can help you troubleshoot licensing problems:
lmdiag -c path to license file. Diagnoses whether or not the license file can be checked out.
lmstat -a -c path to license file. Shows which licenses, contained in the specified license file, are checked out to the product.
lmreread -c path to license file. Reloads the license file without restarting the CitrixLicensing service.
lmhostid -hostname. Displays the host name of the license server.
See Licensing: Using License Administration Commands whitepaper in the Citrix Knowledge Center for additional commands.
Debug Logs
When you need to troubleshoot a licensing problem, the debug log is one of your main sources of information. The debug log file contains status and error messages useful for debugging the license server. Examples of debug log output include events such as license request rejections and license removal requests, as well as status messages, such as time stamps indicating date roll-overs.
You can open the debug log file, lmgrd_debug.log, with any text editor. By default, the log is stored at C:Program FilesCitrixLicensingLS, where C: is the drive on which you installed licensing. The debug log location is set in the LMGRD_LOG_FILE registry entry (HKEY_LOCAL_MACHINESOFTWAREFlexlm License ManagerCitrixLicensing. You can redirect the debug log output to a different location, provided it is on the same disk, by permanently editing the path. You can also temporarily change the location of the debug file to capture errors that may be happening at a particular moment in time. See the “Temporarily Rotating Report Logs (lmswitchr)” section in the Licensing: Using License Administration Commands whitepaper in the Citrix Knowledge
Licensing: Troubleshooting 8
Center.
The output describes events specific to the License Manager daemon and to the Citrix vendor daemon. Messages are written to the debug log each time the license server is started or shut down and when licenses are checked in or out.
Citrix Licensing daemons generate debug log files in the following format: HH:MM:SS (daemon) message
where:
HH:MM:SS is the time that the message is logged.
daemon represents either the License Manager daemon (lmgrd) or the Citrix vendor daemon.
Message is the text of the message.
Over time, the volume of the debug log output increases. You can remove the outdated content from the debug log and either archive or delete it.
Both the Citrix vendor daemon and the lmgrd output to the debug log. You can redirect the debug log output to a different location, provided it is on the same disk, by permanently editing the path specified in the LMGRD_LOG_FILE registry entry.
Tip: For better performance, keep the debug log file on a disk that is local to the computer running the License Manager daemon and the Citrix vendor daemon.
By default, the number of events logged in the debug log is limited. For example, license checkins and checkouts are not logged: the NOLOG options keyword, which prevents checkins and checkouts from being logged, is set by default in the options file. You can increase the number of events that are logged by removing the NOLOG option. See the “Controlling Debug Log Output (NOLOG)” section in the Licensing: Controlling Access to Licenses (the Options File) whitepaper in the Citrix Knowledge Center. By default, the debug log is overwritten automatically when you restart the license server. You can prevent this by editing the registry.
Caution: Using Registry Editor incorrectly can cause serious problems that can require you to reinstall the operating system. Citrix cannot guarantee that problems resulting from incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Make sure you back up the registry before you edit it. If you are running Windows NT, make sure you also update your Emergency Repair Disk.
To prevent the debug log from being overwritten
1. On the computer running the license server, run regedit.
2. Find the subkey: HKEY_LOCAL_MACHINESOFTWAREFLEXlm LicenseManagerCitrixLicensing.
3. Add a plus sign to the beginning of the path in the Value Data for the following entry: LMGRD_LOG_FILE For example, if the entry for the Value Data is C:Program FilesCitrixLicensingLSlmgrd_debug_log,
edit the path so that it reads as follows: +C:Program FilesCitrixLicensingLSlmgrd_debug_log.
4. Restart the CitrixLicensing service to apply your change.
When you are troubleshooting using the debug log, you might want to capture additional details, such as license checkins and checkouts, in the debug log. By default, the options file contains instructions not to record license checkins and checkouts.
To include license checkins and checkouts in the debug log
1. Open the options file using any text editor. The options file (Citrix.opt) is found in the following directory: C:Program FilesCitrixLicensingMyFiles.
2. Comment out the following lines in the options file by adding the pound sign or hash mark (#) in front of the values:
Licensing: Troubleshooting 9
NOLOG IN
NOLOG OUT
3. Reread the options file after making these changes.
To suppress output for the debug log
1. On the computer running the license server, run regedit.
2. Find the subkey: HKEY_LOCAL_MACHINESOFTWAREFLEXlm LicenseManagerCitrixLicensing.
3. Delete the path for the Value Data for the following entry: LMGRD_LOG_FILE.
4. Leave the Value Data field blank.
5. Restart the CitrixLicensing service to apply your change.
You can change the location of the debug log by editing the LMGRD_LOG_FILE registry entry on the license server. The registry entry is stored at HKEY_LOCAL_MACHINESOFTWAREFLEXlm LicenseManagerCitrixLicensing. You can also suppress debug log output by deleting the entry for this string.
Note: If you change the location of the debug log, you cannot access the debug log from the License Management Console.
To change the output location for the debug log
1. On the computer running the license server, run regedit.
2. Find the subkey: HKEY_LOCAL_MACHINESOFTWAREFLEXlm LicenseManagerCitrixLicensing.
3. Change the path for the Value Data for the following entry: LMGRD_LOG_FILE.
4. Restart the CitrixLicensing service to apply your change.
Suggested Reading
The following whitepapers provide more detailed information about some of the topics discussed in this paper:
Licensing: Getting Started with Citrix Licensing Guide
Licensing: Using License Administration Commands
Licensing: The License Management Console
Licensing: Migrating, Upgrading, and Renaming
Licensing: Troubleshooting 10
