Product Documentation

Technical overview

Aug 14, 2017

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 needed to license your product. These files are stored on the License Server.
  • Citrix Licensing Manager. Enables the following:
    • Display details of licenses after they are installed using a license access code or downloaded file. - Build 21103
    • Allocation and installation of license files on a License Server using a GUI.
    • Installation of licenses by using the license access code or a license file (.lic).
    • Configuration of Customer Experience Improvement Program (CEIP) and Call Home.
    • Retry failed usage statistic uploads to Citrix.
    • Automatically or manually checks for Subscription Advantage renewal licenses and notifies you or installs the licenses if found.
    • Enables the creation and exporting of License Server historical usage reports and configuration of historical data retention. Default data retention is 180 days.
    • Notifies you of the License Server state - Missing startup license, time issues, uploader failures.

Not available in License Server VPX.

  • 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 in License Server VPX.

  • Citrix License Management Service. Enables management of your license environment through a license management console within Citrix Insight Services. This service assists with license management and support:
    • Allocating new licenses if you are about to exceed your license capacity
    • Rescinding old licenses after an upgrade
    • Managing duplicate licenses in a Disaster Recovery (DR) environment
  • Product-side settings in your Citrix products that are associated with the License Server.
For more information, see Licensing components and Consoles and services.

Overview of Citrix Licensing

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

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

If 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 might deploy licensing on a server shared with other applications, a dedicated License Server, or multiple License Servers.

License files must be on the License Server that is associated with the product you are licensing. 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. Some Citrix products check out the license when 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.

Citrix tests single license server scalability up to approximately 340,000 concurrent licenses (maximum before the 32-bit CITRIX process runs out of memory) and 1,000,000 user/device licenses.

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. The product then 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. During the grace period, the product uses its local record of the licenses to continue licensing the product. 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. The grace period allows the product servers to continue operations as if they were still in communication with the License Server. After the Citrix product checks out a startup license, the product and the License Server exchange "heartbeat" messages every five minutes. The heartbeat indicates to each that they are still up and running. If the product and the License Server don't send or receive heartbeats, the product lapses into the licensing grace period and licenses itself through cached information.

Citrix sets the grace period. 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.

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.

Supplemental grace period

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

If all licenses are in use, supplemental grace period enables unlimited connections to a product, allowing you to understand and address the issue. This period lasts until 15 days elapses or you install more retail licenses, whichever comes first. We recommend that after the supplemental grace period starts, you allow it to run out rather than adding licenses immediately to clear the warning condition.

After the period expires, normal connection limits are enforced. Users are not disconnected, but as they disconnect, no new connections can occur until license levels return to normal.

Once the supplemental grace period completes, it isn't automatically reenabled. To reenable the supplemental grace period, install another retail license, and then normal license limits are enforced. When you reeneable the supplemental grace period by installing the new retail license, a new 15-day supplemental grace period starts the next time you exceed maximum installed licenses.

Note

If you install licenses while the supplemental grace period is in force, the License Server exits the supplemental grace period. Reenabling the supplemental grace period before determining the reason for the supplemental grace period might cause you to reenter the period after installing new licenses.

Supplemental grace periods are granted per product version and edition and only for retail licenses.
The supplemental grace period is enabled by default when you first install licenses. To disable it, add the following line to the CITRIX.opt file and restart the Citrix licensing services:

#CITRIX SGPOFF

Supplemental Grace Period example:
If you have a maximum count of 1000 licenses installed, and you make another connection (maximum licenses + 1), the supplemental grace period starts. You then have a temporary, 15-day period giving you extra capacity to deal with unforeseen capacity issues.

Important

  • The supplemental grace period and license overdraft are two different features. The supplemental grace period is a feature of the product and the License Server. License overdraft is a feature of the license. For information about license overdraft, see License overdraft.
  • License Server VPX does not support supplemental grace periods.