Understanding License Files
Summary
This whitepaper provides you with details about Citrix License files. 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.
Introduction
You can control different aspects of your licensing operations and environment by customizing two files: the options file and the license file.
The options file (Citrix.opt) controls license consumption as well as license server logging. It is a server configuration file that the Citrix vendor daemon reads every time it starts or receives a command to reread the file. The options file controls two aspects of licensing: reserving licenses and controlling license server behavior and operations. For information about the options file, see the Licensing: Controlling Access to Licenses (The Options File) whitepaper in the Citrix Knowledge Center.
The license file is a text file that contains product licensing information as well as the license server name, the License Manager daemon port number, the Subscription Advantage membership renewal date (also known as the Subscription Advantage Expiration date), the license expiration date (if applicable), and other system information. All of this information is encrypted with a digital signature. When you purchase a Citrix product, you go to the MyCitrix Web site to download a license file. The license file resides in the C:\Program Files\Citrix\Licensing\MyFiles directory on a 32-bit server, or C:\Program Files (x86)\Citrix\Licensing\MyFiles directory on a 64-bit server, where it is referenced by the license server. The license server uses the file to determine whether or not to grant a license to a Citrix product.
All license server system files, such as license files, options files, and license administration commands, must reside on the license server in their default locations. License files are specific to the server on which they are stored: you cannot move license files between license servers with different names. The server name that you specify when you generate a license file on the Citrix Activation System in MyCitrix is encrypted in each license file. If you edit the server name, you destroy the license file. If you need to move a license file, you must return the file using the MyCitrix Web site and specify the new server name where the file will reside. You can then generate and download the new file. For information about returning a license file, see the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center.
Important: Any modifications, apart from those mentioned in this whitepaper (changing port numbers), render the license files unusable.
Licensing: Understanding License Files 2
Understanding the License File Format
Understanding the license file format is an essential prerequisite to understanding the number and purchase dates of the licenses you own, setting up firewalls, and customizing license server operations through the options file.
Citrix License files employ the following naming convention: license_20040322134450.lic.
The last part of the file name is a date stamp with the following format: YYYYMMDDHHMMSS. The date stamp corresponds with the date the file is downloaded, and, consequently, lets you distinguish between different licenses you downloaded. You can change the name of the license file but it must have a .lic extension.
License files are composed of lines that list specific information, such as the server name (SERVER) or quantity of licenses (INCREMENT). These lines begin with words denoting their purpose in uppercase letters, such as VENDOR, SERVER, INCREMENT, USE_SERVER, and so on. They are detailed in the following sections.
Understanding the License File Syntax
This section provides in-depth information about the following elements of license file syntax: the SERVER line, VENDOR line, USE_SERVER line, INCREMENT line, and UPGRADE line. Before learning about the syntax, it is important to understand the way in which product licenses are referenced in the options file.
While the term feature is used in the options and license file syntax, in this document, the term product license is used whenever possible for clarity.
1 The SERVER Line
The SERVER line specifies the host name of the license server and the TCP/IP port number of the License Manager daemon (lmgrd). No port number after the host name means it is using the default port number, 27000.
Important: Do not modify the host name on the SERVER line.
Licensing: Understanding License Files 3
Syntax – Citrix (Software Products)
SERVER this_host HOSTNAME=hostid [port]
Example:
SERVER this_host HOSTNAME=license_server1
Syntax – Netscaler (Citrix Hardware Products )
SERVER this_host ETHER=Ethernet MAC address
Parameters
Description
hostid
The name of the computer on which the license server is running. Usually the string returned by the lmhostid command. Do not edit this string.
Ethernet MAC address
The Ethernet MAC address of the device on which the license server is running.
port
TCP/IP port number used by the License Manager daemon. A valid number is any unused port number between 0 and 64000. If no TCP/IP port number is specified, the default port of 27000 is used.
In the example above, there is no port number after the server host name because the license server is using the default port of 27000. If you need to change the port number, place the new port number after the license server name as in the following example:
SERVER this_host HOSTNAME=license_server1 27110
See the Licensing: Firewalls and Security Considerations whitepaper in the Citrix Knowledge Center for additional information about changing port numbers.
2 The VENDOR Line
The VENDOR line specifies the Citrix vendor daemon name, path, options file path, and port number. The License Manager daemon uses this line to start the Citrix vendor daemon, and the Citrix vendor daemon reads this line to find the options file.
Note: If the Citrix daemon is using a random TCP/IP port, which it does by default, the line appears only as VENDOR CITRIX. (That is, the options file path and the port number do not appear beside the words “VENDOR CITRIX.”)
Syntax
VENDOR CITRIX [vendor_daemon_path]\[[options=]options_file_path] [[port=]port]
Licensing: Understanding License Files 4
where:
Field
Description
vendor CITRIX
Name of the Citrix vendor daemon. You cannot edit this name.
vendor_daemon_path
Path to the executable for the Citrix vendor daemon. Citrix recommends that you do not change this path.
options_file_path
Full path to the options file for the Citrix vendor daemon. Citrix recommends that you do not change this path.
port
Citrix vendor daemon TCP/IP port number. By default, the port number is not specified. The operating system chooses it at run-time. Sites with Internet firewalls need to specify the TCP/IP port number the Citrix vendor daemon uses. If a TCP/IP port number is specified on the VENDOR line, there may be a delay restarting the Citrix vendor daemon until all the clients close their connections to the vendor daemon.
Example:
VENDOR CITRIX options=”C:\Program Files\Citrix\Licensing\MyFiles\CITRIX.opt” Port=27900
See the Licensing: Firewalls and Security Considerations whitepaper in the Citrix Knowledge Center for information about configuring Citrix Licensing if you have a firewall.
The USE_SERVER Line
USE_SERVER takes no arguments and has no impact on the server. USE_SERVER tells the product to rely on the Citrix vendor daemon to validate license check outs.
3 The INCREMENT Lines
An INCREMENT line describes the license required to use a product. It specifies information about the product being licensed, the license model (such as concurrent user or named user), the number of licenses, and so on.
Each increment line contains a signature based on the data in that line, the Host Ids specified in the SERVER line(s), and data chosen by Citrix. INCREMENT lines use a backslash ( \ ) to wrap long lines of text.
Syntax
INCREMENT feature vendor SA_expiry_date exp_date num_lic \
SIGN=sign [optional_attributes]
You cannot edit the six fields after the INCREMENT line keyword; they are required and have a fixed order. The following table explains these fields in the order they appear:
Field
Description
feature
The product license.
vendor
Indicates this license is for a Citrix vendor daemon.
Licensing: Understanding License Files 5
SA_expiry_date
Indicates the date until which you are entitled to product version upgrades. If you do not have a Subscription Advantage membership or this is not a Subscription Advantage license, the date indicates when you ordered or redeemed the license.
Note: If you renewed your Subscription Advantage membership and received an upgrade license, two dates are listed.
• The first date is the date when the Subscription Advantage membership was originally purchased
• The second date is the SA_expiry_date
Example:
INCREMENT MPS_ENT_CCU CITRIX 2005.0311 2007.0311 permanent 1000 \
See “UPGRADE Lines” for additional information.
exp_date
Expiration date of license in the format dd-mmm-yyyy, that is, 07-may-2006. Note: If the exp_date field contains the string “permanent,” the license never expires.
num_lic
Number of concurrent licenses for this product license.
SIGN=sign
SIGN= signature to authenticate this INCREMENT line.
INCREMENT lines also determine the grouping of licenses in the License Management Console. These groups are known as license pools. The Citrix vendor daemon creates the license pools based on common attributes, such as product license or version. When a new pool is created, the License Management Console displays and tracks this pool independently from other license pools. When two or more attributes are different, the Citrix vendor daemon creates a new license pool.
Citrix Attributes in INCREMENT Lines
INCREMENT lines can also include additional attributes from Citrix. These attributes provide information about the license, such as the date on which it was issued or that the license is an upgrade license.
Caution: If you edit or delete these attributes, your license file becomes unusable.
Example:
INCREMENT MPS_ENT_CCU CITRIX 2005.0311 permanent 1000 \
VENDOR_STRING=;LT=Retail;GP=96;CL=ENT,ADV,STD;SA=1;ODP=0 \
DUP_GROUP=V ISSUED=12-Mar-2004 NOTICE=”ABCD Corporation” \
SN=LA-0000150712-12345:123 START=11-mar-2004 SIGN=”1234567″
Syntax
keyword=value
Licensing: Understanding License Files 6
The table that follows describes the Citrix attributes. The uppercase letters of the attributes indicate that this attribute is not editable.
Attribute
Description
DUP_GROUP=V
This attribute allows license sharing for the same client device.
ISSUED=dd-mmm-yyyy
Date issued.
ISSUER=”…”
Issuer of the license.
NOTICE=”…”
Your company’s name.
SN=serial_num
A number that is used to identify INCREMENT lines.
START= dd-mmm-yyyy
The date from which you can use a license. The license server cannot use licenses before their start date.
SUPERSEDE=”MPS_ADV_CCU MPS_STD_CCU …”
This appears in the upgrade license file when you move to a higher product edition. If this appears, all licenses issued before the date specified in ISSUED= are superseded by this line and become ineffective.
VENDOR_STRING=”…”
String defined by Citrix.
Optional Attributes in INCREMENT Lines
INCREMENT lines contain several attributes that you can add, edit, or delete. You can add attributes, if desired. For example, you can insert an asset tag or a purchase order number beside each license in a file. Likewise, you can add attributes that indicate a specific group of licenses is dedicated for a department in your organization.
Some of these attributes may be inserted by Citrix or your Value Added Reseller.
Optional attributes are listed in the table that follows. Like the Citrix-specific attributes, the optional attributes have a keyword=value syntax where keyword is in lowercase. You can tell the difference between optional and required attributes by the case of the letters: optional attributes have lowercase letters.
Attribute
Description
asset_info= “…”
Additional information you can add for asset management.
dist_info= “…”
Additional information provided by the software distributor.
user_info= “…”
Additional information provided by the license administrator.
vendor_info= “…”
Additional information provided by Citrix.
Licensing: Understanding License Files 7
UPGRADE Lines
An UPGRADE line indicates the date on which a Subscription Advantage membership was renewed and the date it expires. The UPGRADE line is not editable.
Syntax
UPGRADE feature CITRIX from_Subscription_Advantage_date to_Subscription_Advantage_renewal_date \
exp_date num_lic [options ... ] SIGN=sign
All the data is the same as for an INCREMENT line, with the addition of the from_Subscription_Advantage_date field. An UPGRADE line removes up to the number of licenses specified from any old version (>= from_Subscription_Advantage_date) and creates a new version with that same number of licenses.
For example, the following lines renew the ABCD Corporation’s Subscription Advantage membership for 1000
MPS_ENT_CCU licenses for one year (until March 11, 2006):
INCREMENT MPS_ENT_CCU CITRIX 2005.0311 permanent 1000 \
VENDOR_STRING=;LT=Retail;GP=96;CL=ENT,ADV,STD;SA=1;ODP=0 \
DUP_GROUP=V ISSUED=12-Mar-2004 NOTICE=”ABCD Corporation” \
SN=LA-0000150712-12345:123 START=11-mar-2004 SIGN=”1234567″
UPGRADE MPS_ENT_CCU CITRIX 2005.0311 2006.0311 permanent 1000 \
VENDOR_STRING=;LT=Retail;GP=96;CL=ENT,ADV,STD;SA=1;ODP=0 \
DUP_GROUP=V ISSUED=12-Mar-2005 NOTICE=”ABCD Corporation” \
SN=RE-0000164638-12345:123 START=11-mar-2005 SIGN=”1234567″
An UPGRADE line applies to the closest preceding INCREMENT line with a Subscription Advantage date that is greater than or equal to from_Subscription_Advantage_date, and less than to_Subscription_Advantage_renewal_date.
Upgrade lines use a continuation character ( \ ) to break up long lines. When using license files with an UPGRADE line, you must keep the license files with the original INCREMENT lines in the same folder.
See the Licensing: Licensing and Subscription Advantage whitepaper for additional information about obtaining Subscription Advantage files.
Modifying License Files
Do not edit your license files except to change the daemon port numbers. You can specify port numbers for the License Manager daemon and the Citrix vendor daemon—the latter is necessary if there is a firewall between the product servers and the license server. See the Licensing: Firewalls and Security Considerations whitepaper in the Citrix Knowledge Center for information about changing port numbers when you have a firewall.
Licensing: Understanding License Files 8
Important Notes about Modifying License Files
Before you modify your license files, ensure that you read the following notes:
• Do not edit your license files except to change the daemon port numbers.
• License files are specific to the server on which they are stored: you cannot move license files between license servers with different names. The server name that you specify when you generate a license file on the Citrix Activation System is encrypted in each license file. If you edit the server name, you destroy the license file. Any modifications, apart from those mentioned in this whitepaper, render the license files unusable.
• Any changes you make to a license file must be made in all license files on the license server, including the startup license (citrix_startup.lic).
• After you edit license files, you must force the license server to reread them into memory for changes to take effect.
Downloading Replacement License Files from Citrix
Replacement license files are copies of the license file you originally generated in the Citrix Activation System stored at MyCitrix.com. These license files reference the license server name that you specified when you allocated the licenses for the first time. If you corrupt or delete a license file, you can download a replacement license file from MyCitrix.com.
After you download replacement license files, you must delete old (corrupted or outdated) license files from the license server and replace them with the newly downloaded file.
To download backup license files using the License Management Console
1. From the Welcome page of the License Management Console, click Configure License Server. The License Files page appears.
2. Click Download license file from MyCitrix.com. The MyCitrix page opens.
3. Log on and navigate to the Download License Files page.
4. Select the licenses you want to download again and download the license file. Citrix suggests that you download the file to your desktop, or that you remember where you downloaded the file in case you decide to copy the file manually to the location where you store the license files (the default location where license files are kept is: C:\Program Files\Citrix\Licensing\MyFiles).
5. After downloading the license file, click copy the file to your Citrix license server using the License Management Console. The License Management Console opens to the License Files page.
6. Click Copy license file to this License Server to copy the license file to the license server (if necessary). If you manually copy license files to a license server, force the license server to read the license files; click Update license data on the License Files page
Licensing: Understanding License Files 9
Upgrading to a Higher Product Edition
Some Citrix products allow you to upgrade to a higher edition of the product. To upgrade, you must purchase and obtain an upgrade license. For example, Presentation Server 4.0 requires an exact match of licenses to product editions: you cannot use an Enterprise edition license to license a Standard edition product. As a result, all affected computers running Presentation Server cannot accept new connections until you change their product edition setting in the Access Management Console to the new edition.
To upgrade your licenses after you purchase and install the product upgrade
1. Generate a new license file on MyCitrix that contains the new edition’s license information. See the Getting Started with Citrix Licensing Guide in the Citrix Knowledge Center for information about this process.
2. Place the file in the same directory as the old license files (by default, this directory is C:\Program Files\Citrix\Licensing\MyFiles on a 32-bit server or C:\Program Files (x86)\Citrix\Licensing\MyFiles on a 64-bit server).
3. Reread the files. The license server deactivates the lower-edition licenses after you add the upgrade license to the license server. To reread the files using the License Management Console you must click Update license data on the License Files page. See “Updating License File Data on the License Server” in the Licensing: The Licensing Management Console whitepaper in the Citrix Knowledge Center. To reread the files using the License Administration commands, see “Rereading License and Options Files (lmreread)” in the Licensing: Using License Administration Commands whitepaper in the Citrix Knowledge Center.
4. Set the product-side settings to the new edition (if necessary). For example, Presentation Server has a product side setting where you specify which edition you are using. See your product’s administrator’s guide for information about this setting.
After adding upgrade licenses to the license server, you can still use the older edition software provided you change the edition setting to reflect the lower edition. For example, if you are currently running Presentation Server, Standard Edition and you purchase an upgrade license for Presentation Server, Advanced edition, you can run Presentation Server as though it is the Standard edition version of the product by changing the edition setting to Standard. For information about changing the product-specific settings, see the product’s administrator’s guide.
Citrix recommends that you plan to change the product edition setting during a time when there are not many connections to the affected servers or that you plan to redirect connections to another computer. When you change the product edition setting, you must restart the product server for changes to take effect.
Note: Licenses from old product editions appear on the Complete License Inventory page in the License Management Console. See the Licensing: The License Management Console whitepaper in the Citrix Knowledge Center for information about the License Management Console.
Moving Your License Files
If you need to move your license files to a server with a different name, you cannot use the license files that you downloaded for the old license server. Create new license files that reference the new server name by returning previously allocated licenses on MyCitrix.com and then generating the new file. See the Licensing: Migrating, Upgrading, and Renaming whitepaper in the Citrix Knowledge Center for the procedure for rehosting your license files.
Licensing: Understanding License Files 10
Deleting License Files
You can manually delete license files that are no longer in use from their Windows directory. By default, license files are stored in C:\Program Files\Citrix\Licensing\MyFiles on a 32-bit server or C:\Program Files (x86)\Citrix\Licensing\MyFiles on a 64-bit server.
Before you delete license files, you must stop the Citrix License Management Console service. If you do not stop this service, an error message appears warning you the file is in use. If you are replacing the deleted license files:
• Make sure the replacement license files contain any required changes before you add them to the license server
• Delete the old license files before you add the replacement license files to the MyFiles directory
• Restart the Citrix License Management Console service
Tip: Unless you are deleting license files permanently, always keep back-up copies of the files you are deleting.