Product Documentation

Technical overview

Jul 08, 2016

Before you can use your Citrix product, you must install Citrix Licensing. Citrix Licensing is a system of components that function together. This system includes:

  • License server - A system that allows licenses to be shared across the network.
  • License files - The files that you need to license your product. These files are stored on the License Server.
  • License Administration Console - The interface you use to manage your license files and your License Server.
  • Web Services for Licensing - Enables Studio, Director, and the Licensing Administration PowerShell Snap-in to communicate with the License Server and manage users, allocate and install licenses, display License Server health, license usage, and other alert messages. Not available with License Server VPX.
  • Citrix Licensing Manager - Enables allocation and installation of license files on a License Server using a GUI and enables the creation and exporting of License Server historical usage reports. Not available with License Server VPX.
  • Product-side settings in your Citrix products that are associated with the License Server. 
 

Overview of Citrix Licensing

Every Citrix product environment must have at least one shared or dedicated License Server. License servers are computers that are either partly or completely dedicated to storing and managing licenses. Citrix products request licenses from a License Server when users attempt to connect.

Servers running Citrix products contact the License Server to obtain licenses.

When users connect to a Citrix product, it draws licenses from the License Server. That is, the Citrix product requests to check out a license from the License Server on behalf of the user or client device. When the license is successfully checked out, the user can run the product.

Depending on the size and configuration of your product deployment, you may deploy licensing on a server shared with other applications, a dedicated License Server, or multiple License Servers.

License files must be located on the License Server that is associated with the product you are licensing and the product must be configured to communicate with that specific License Server. The License Administration Console lets you manage and monitor your Citrix licenses by providing a user interface to the License Server. You can view a dashboard of licenses and alerts, import license files, and manage License Server settings.

Licensing operations overview

Typically, the first time a user connects to a Citrix product, the product requests a license from the License Server. When the License Server grants a license request, the Citrix product reserves a license for its use. Reserving licenses for this purpose is known as checking out licenses. When the user logs off from the product server, the product returns the license to the License Server. This process is known as checking in licenses. With some Citrix products the license is checked out as soon as a user connects to the product, and the license remains checked out for a predetermined amount of time.

Each time a Citrix product starts, it opens a connection to the License Server by checking out the startup license. The startup license is a Citrix system file that enables Citrix products to maintain a continuous connection to the License Server. The following figure shows that each product forms its own constant connection to the License Server.

The Citrix product makes a continuous connection to the License Server. The License Server can support up to 10,000 continuous connections.

For example, when a server running XenDesktop requests a license, the product retrieves the License Server name and port number information from the data store and establishes a connection to acquire the appropriate licenses.

There are three stages of the license checkout process.

A Citrix product goes through a three-step process to check out licenses:

  1. At startup, a computer running a Citrix product checks out a startup license.
  2. A client device connects to the product server.
  3. The product requests a license from the License Server.

Citrix products, such as XenDesktop, store a replica of the licensing information from the License Server, including the number and type of licenses. If a Citrix product server loses its connection to the License Server, or the License Server does not respond in a timely manner, the product enters a grace period and uses its local record of the licenses to continue licensing the product during the grace period. Citrix products update this record every hour.

Grace periods

If product servers lose communication with the License Server, the users and the products are protected by a grace period that allows the product servers to continue operations as if they were still in communication with the License Server. After a startup license is checked out by the Citrix product, the product and the License Server exchange "heartbeat" messages every five minutes to indicate to each other that they are still up and running. If the product and the License Server fail to send or receive heartbeats, the product lapses into the licensing grace period and licenses itself through cached information.

The grace period is set by Citrix. It is typically 30 days but can vary depending upon the product. The Windows Event Log, and other in-product messages, indicate if the product has entered the grace period, the number of hours remaining in the grace period. If the grace period runs out, the product stops accepting connections. After communication is re-established between the product and the License Server, the grace period is reset.

The grace period takes place only if the product has successfully communicated with the License Server at least once.

Note: For products that operate in disconnected mode, the grace period takes effect after the preconfigured time specified for the license check-out expires.

Grace period example - two sites, both using the same License Server

The connection between Site 1 and the License Server goes down causing Site 1 to go into the grace period, continuing operation and making connections. For Concurrent licenses, they can connect up to the maximum concurrent licenses installed. For User/Device licenses, they have unlimited connections. When Site 1 reestablishes communication with the License Server, connections are reconciled and no new connections are allowed until they are within normal license limits. Site2 is unaffected and operates as normal.

If the License Server goes down, both sites go into the grace period. Each site allows up to the maximum number of licenses installed. As above, the User/Device licenses have no limit.

Disconnected mode

Some Citrix products can operate in a disconnected mode (not connected to the server). These products allow a user to check out a license and operate the product for a preconfigured period of time that is set by the administrator. In this case, heartbeat messages are not exchanged. For products that operate in disconnected mode, the grace period takes effect after the preconfigured time specified for the license check-out expires.

Supplemental grace period

For the supplemental grace period to be available, you must be using a minimum of  XenApp 7.6 and/or XenDesktop 7.6.

License Server VPX does not support supplemental grace periods.

If all licenses are in use, the supplemental grace period enables users to connect to a product for a limited period of time allowing you to address the issue. The default supplemental grace period is 15 days. During this period there is no limit on connections. After it expires, normal (to the extent of license availability) connection limits are enforced. Users are not disconnected, but as they disconnect, no new connections occur until license levels return to normal.

Supplemental grace periods are granted per product and edition and per Subscription Advantage Eligibility date (per product) and only for Retail licenses. For example, if you have two clients requesting XenDesktop Enterprise Concurrent, with different Subscription Advantage Eligibility dates, two supplemental grace periods are granted.

Rearming the supplemental grace period - When you take corrective action (for example, installing an additional Retail license), the supplemental grace period is rearmed, and normal license limits are enforced again. If you take action while the supplemental grace period is in force, the License Server exits the supplemental grace period before rearming. When the supplemental grace period is rearmed, you can trigger a new 15 day supplemental grace period the next time you go over the license limit.

Citrix recommends that when the supplemental grace period starts, allow it to run rather than adding licenses immediately to remove the warning condition. 

The supplemental grace period is enabled by default. To disable it, enter the following line in the options file:

#CITRIX SGPOFF

Note

The only way to disarm the supplemental grace period is by either adding more licenses or disabling the supplemental grace period feature.

License server components

The License Server comprises several licensing components:

  • Citrix vendor daemon
  • License Administration Console
  • License files
  • Options file
  • Startup license
  • Web Services for Licensing
  • Citrix Licensing Manager
Figure 1. License Server Components. This diagram shows the Citrix product using TCP/IP to connect to License Server components.
localized image

Citrix vendor daemon
Licenses are granted by the Citrix vendor daemon (CITRIX), a process that runs on the License Server. The Citrix vendor daemon tracks the number of licenses that are checked out and which product has them. Citrix products communicate with the Citrix vendor daemon using TCP/IP. By default, the Citrix vendor daemon uses TCP/IP port 7279.

License files
License files are text files created by Citrix that store licensing data. They contain information about the product licenses and the number of licenses, as well as system information such as the name of the License Server. The License Server uses these files to determine whether to grant a license to a Citrix product.

Startup license
The startup license (citrix_startup.lic) allows Citrix products to communicate with the License Server using a continuous open connection. The startup license:

  • Tracks which product servers are connected to the License Server
  • Stores licensing system information
  • Does not affect your license count

Caution: Do not edit the startup license file, or any other license files.

Citrix License Server Diagnostics License|Server
The License Server uses Citrix License Server Diagnostics License|Server for internal diagnostics and alert message notifications displayed in Studio and Director. It is available by default with the startup license in the citrix_startup.lic file.

Options file
The options file (Citrix.opt) is a License Server configuration file that the Citrix vendor daemon reads every time it restarts or receives a command to reread the file. This configuration file defines licensing behavior—the number of licenses a product server can use, the location of the system logs, and other user-defined customizations.

Web Services for Licensing
License Server VPX does not support Web Services for Licensing.

Studio, Director, and the Licensing Administration PowerShell Snap-in use Web Services for Licensing to communicate with the License Server and manage users, allocate and install licenses, display License Server health, license usage, and other alert messages. The Citrix Licensing Manager also uses it.

Citrix Licensing Manager

The Citrix Licensing Manager enables the following features on a License Server using a simple GUI interface:

  • Allocation and installation of license files.
  • Creating and exporting historical usage reports from the License Server on which the tool is installed. You can specify a date range for the historical usage data and export it to a CSV file.  The CSV file provides daily usage information including the number of licenses in overdraft.
  • Important notifications of license availability, expiration, and other conditions. Use the bell icon at the top of the Citrix Licensing Manager screen to display notifications.

The Citrix Licensing Manager is on by default.

Important

License Server VPX does not support the Citrix Licensing Manager.

The License request process

When a product requests a license from the License Server, the Citrix vendor daemon determines whether a license is available for the request.

The license request process has two phases: the product startup phase and the user connection phase.

Product Start-Up Phase
  • When a Citrix product starts, it retrieves the License Server location from its data store
  • The product connects to the Citrix vendor daemon
  • The product checks out a startup license
User connection phase
  • A user connects to a computer running the Citrix product
  • The product requests a license from the License Server
  • The Citrix vendor daemon checks to see if any licenses are available and grants or denies the product's request
  • The license module in the product grants or denies the use of the product based on the response from the Citrix vendor daemon

Citrix Licensing Customer Experience Improvement Program (CEIP) and Call Home

The Citrix Licensing CEIP and Call Home usage and analytics programs are voluntary data collection programs designed to improve your product experience. After installing License Server 11.13.1, you can participate in the programs anonymously or choose to be identified.

You can change your participation in the program at any time.

Note: Because the Citrix Service Provider program requires CEIP and Call Home, if you have Citrix Service Provider licenses installed, you cannot disable CEIP or Call Home.  

When installing licensing on the command line, you can use CEIPOPTIN to specify whether, or how, to opt-in to Citrix Customer Experience Improvement Program (CEIP) or Call Home Optional parameter. The default is None.
Diagnostic - Call Home
Anonymous - CEIP
None

For more command line installation information, see the "Use the command line to install licensing" section under Install licensing components for Windows.

You can modify the choice made at installation by editing the CITRIX.opt file:

#CITRIX CEIP value

where value is DIAG, ANON, or NONE

On VPX, do not modify the CITRIX.opt file. As root, execute the following command and make your choice of CEIP [1.DIAG 2.ANON 3.NONE]

# reset_ceip.sh

Citrix Licensing Customer Experience Improvement Program (CEIP)

CEIP is voluntary. When you opt-in, the CEIP services running in Citrix products gather anonymous configuration and usage data from your deployment, and automatically sends the data to Citrix. CEIP collects these classes of data:

  • Configuration data
  • Performance and reliability data

How your privacy is protected:

  • Citrix does not collect any personally identifiable data.
  • Random identifier is created at install time, which tracks data transfers over time.
  • Citrix does not record information such as IP addresses, server names, or domain names.
  • All data is sent using HTTPS directly to Citrix servers - no third party data hosting services.
  • All data is secured on Citrix servers and is accessible only by authorized individuals.

Citrix Call Home

Call Home is voluntary. When you opt-in, Call-home performs periodic collection of system and product configuration, performance, errors, and more. The data identifies you as a customer. This information is transmitted to Citrix Insight Services for Citrix support and product teams to resolve issues proactively.