Product Documentation

Get started, install, and configure the License Server

Feb 26, 2018

Important

We recommend that you run the latest version of the License Server. We do not provide hotfixes for License Server components and don't support older License Servers with newer products. The latest version of the License Server often contains resolutions to issues appearing in earlier versions. When you upgrade or install new Citrix products, upgrade the licensing components as well. New License Servers are backward compatible and support older products and license files. However, new products often require the newest License Server to check out licenses correctly. You can find the latest version from the Citrix Downloads site.

To see the new features in this release, go to What's new.

Licensing your product includes the following steps:

  1. Ensure that you have the latest license server version.
  2. Verify system requirements.
  3. Install licensing.
  4. Obtain license files from My Account or if you have a license code, use Citrix Licensing Manager.
  5. Install your Citrix product (or, if already installed, restart the Citrix products for the new licenses to be recognized)
  6. Configure product-side licensing communication settings that were not set during product installation, if applicable. This configuration includes setting the correct product-edition in the product. Details about these settings are covered in the product documentation.

    Ensure that the product-side edition setting correctly matches the licenses you have purchased. For example, if you purchased Platinum edition licenses, ensure that the edition setting in the product indicates Platinum-not Enterprise or Advanced.

Important

The License Server does not require domain membership. You can install the License Server in a workgroup and still perform all licensing functions on behalf of Citrix products. To manage the License Administration Console or the Citrix Licensing Manager users having Active Directory users or groups, the users must be part of a domain. Otherwise, use local Windows users.

For an overview of the licensing components and process, see Technical overview and Licensing components.  

Ensure that you have the latest license server

  1. When upgrading or installing new Citrix products, always have the latest license server. The new license server is backward compatible and supports older products and license files. However, new products require the newest license server to check out licenses correctly. You can install or upgrade the latest version from the product media.

For more information about version numbers, see Differences in License Server version numbers.

To find your license server version number

If you are unsure if your license server version is current, you can verify it by comparing your version with the number on the Downloads site.

On a license server with the Citrix Licensing Manager

  1. Start the Citrix Licensing Manager.
  2. See the release version in the bar at the top of the page.

On a license server with the License Administration Console

  1. For windows: Start the License Administration Console from the programs menu: Citrix > License Administration Console.

    For License Server VPX and remote systems: Open a web browser and go to https://License Server Name:secureWebPort.

  2. Click Administration and select the System Information tab. See the release version in the information list.

On a License Server using the Registry Editor

  1. Open the Registry Editor (Start > Run > regedit).

    Important: Use Registry Editor to view the license server information only. Editing the Registry can cause serious problems that might require you to reinstall your operating system.

  2. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\LicenseServer\Install.

    The version number appears in the Version key in the format, for example: 11.14.0.1 build 16100.

    On servers running Windows 2008 Server 64-bit, the registry key is

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\LicenseServer\Install

 

Security considerations

We recommend that you upgrade the license server to the latest version when you upgrade or install new Citrix products. New license servers are backward compatible and support older products and license files. Each time a new license server is released, it might contain better security features than in previous versions.

We also recommend the following security considerations when you configure your environment or use the Licensing Administration Console.

  • Configure the license server environment so that only authorized administrators on a trusted network are permitted to access the Licensing Administration Console port. You achieve this outcome with an appropriately configured network or host-based firewall.
  • When using the Licensing Administration Console, avoid visiting untrusted websites or clicking untrusted URLs.

Firewall considerations

Determine if you require a firewall between the license server and any product servers before installing licensing. Firewall considerations can impact where you install the license server.

The License Server VPX has default ports enabled. To change ports, use the Linux iptables command.

If you have hardware firewalls in your environment, you must create the necessary rules manually.

If there is a firewall between your product and the license server, configure port numbers. This configuration process entails:
  • Determining which port numbers to change. You can change port numbers during the installation process or afterward.
  • Opening up the firewall ports. Open any ports on the firewall that you changed so that traffic can flow. Current releases configure the built-in firewall automatically.
  • Changing the product-side settings. Your Citrix product must be configured with the same port numbers as in the License Administration Console. If you do not change the port number referenced in the product, the product cannot contact the license server. You can change the product-side settings during and after installation of the product. See your product documentation for information about these settings.

Install licensing components for Windows

You can install licensing components on a separate, dedicated server or on a server they share with another application. Alternatively, you can use a web or application server. However, the locations mentioned below are less resource intensive. If you are running fewer than 50 servers or 10,000 licenses, you can install the License Server on the same server as your product. To determine if relocation of the License Server to another system is necessary, monitor CPU and memory load (lmadmin.exe and CITRIX.exe).

Important

Use the new CitrixLicensing.exe file for all future installations, except for Active Directory deployments. In that case, use the .msi.

Ensure that both .exe and .msi files are present for the installation.

Install the License Server for Windows and console using the graphical interface

  1. Download the License Server from citrix.com and start the License Server installer, CitrixLicensing.exe, as an administrator or a member of the administrators group.
  2. Follow the installer graphical interface to accept the destination folder.

    Licensing components are installed in C:\Program Files\Citrix\Licensing on a 32-bit computer and C:\Program Files (x86)\Citrix\Licensing on a 64-bit computer.

  3. On the Configure page, accept or change the default port numbers used by licensing components. Choose whether to allow the installer to configure the Windows Firewall exception. If needed, you can change the port numbers after the installation. If you choose to finish the installation without configuring the License Server, restart the CitrixLicensing.exe installer. You can also use the License Server Configuration tool to configure the settings after the installation. Open the configuration tool from: C:\Program Files\Citrix\Licensing\LS\resource\Licensing.Configuration.Tool.exe.
    • License server port number is 27000
    • Vendor daemon port number is 7279
    • Management console web port is 8082
    • Web Services for Licensing port is 8083
  4. The License Server adds the default License Administration Console administrator based on how you are logged on. If you are in a domain, the License Server adds the installing user (domain\user) as a default License Administration Console administrator. If you are a local Windows user, the License Server adds the installing user (computer\user) as a default License Administration Console administrator. The BUILTIN\administrator group, which allows any administrator to manage licensing, is added by default. You can remove BUILTIN\administrators to restrict licensing to specified users. Any user that has access to managing the License Administration Console can also manage the Citrix Licensing Manager.
  5. Choose to start the License Administration Console or the Citrix Licensing Manager and whether to join the Citrix Customer Experience Improvement Program.

If you don't choose the Citrix Licensing Manager, or a license from your product administration console, you can still get your licenses. Go to the citrix.com to obtain the license files for your Citrix products. This procedure is detailed in "Obtain your license files" below.

Use the Windows command line to install licensing

When using the CitrixLicensing.exe command to install licensing, set properties by adding Property=value on the command line anywhere except between an option and its argument.

Ensure that you run the command line with administrator privileges. To start the command prompt with elevated privileges, choose Start, right-click Command Prompt, and choose Run as administrator.

Note: The Citrix Service Provider program requires Customer Experience Improvement Program (CEIP) and Call Home. If you are a Citrix Service Provider, you cannot disable CEIP or Call Home.

The following sample command line installs licensing in silent mode. Add the properties you want to set.

Type the command in one line without returns. The following example shows multiple lines due to space limitations.

CitrixLicensing.exe /quiet /l install.log INSTALLDIR=installdirectory WSLPORT=port_number
LSPORT=port_number VDPORT=port_number MCPORT=port_number CEIPOPTIN=value

Where:

  • /quiet specifies a silent (quiet) installation.
  • /l specifies the log file location
  • INSTALLDIR is the location where the License Server executable is stored. Optional parameter. The default is c:\program files\citrix licensing or c:\program files (x86)\citrix\licensing.
  • WSLPORT is the port number used for the Web Services for Licensing. Optional parameter. The default is 8083.
  • LSPORT is the port number used for the License Server. Optional parameter. The default is 27000.
  • VDPORT is the port number used for the vendor daemon. Optional parameter. The default is 7279.
  • MCPORT is the port number used for the console. Optional parameter. The default is 8082.
  • CEIPOPTIN specifies whether, or how, to opt in to Citrix Customer Experience Improvement Program (CEIP) or Call Home. Optional parameter. The default is ANON.
    • DIAG - Call Home
    • ANON - CEIP
    • NONE

    You can modify the CEIP and Call Home choice using the Citrix Licensing Manager.

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

#CITRIX CEIP value

Where value is DIAG, ANON, or NONE

Using the command line to install licensing for an Active Directory deployment

When using the msiexec command to install licensing, set properties by adding Property="value" on the command line anywhere except between an option and its argument. Clustering is not supported in the .msi.

Note: Ensure that you run the command line with administrator privileges. To start the command prompt with elevated privileges, choose Start, right-click Command Prompt, and choose Run as administrator.

The following sample command line installs licensing in silent mode and creates a log file to capture information about this operation. Add the properties you want to set after the switches.

Type the command in one line without returns. The following example shows multiple lines due to space limitations.

msiexec /I ctx_licensing.msi /l*v install.log /qn INSTALLDIR=installdirectory LICSERVERPORT=port_number
VENDORDAEMONPORT=port_number MNGMTCONSOLEWEBPORT=port_number WEBSERVICELICENSINGPORT=port_number CEIPOPTIN=value

Where:

  • /l*v is the location of the setup log. Optional parameter.
  • /qn specifies a silent (quiet) installation.
  • INSTALLDIR is the location where the License Server executable is stored. Optional parameter. The default is c:\program files\citrix licensing or c:\program files (x86)\citrix\licensing.
  • LICSERVERPORT is the port number used for the License Server. Optional parameter. The default is 27000.
  • VENDORDAEMONPORT is the port number used for the vendor daemon. Optional parameter. The default is 7279.
  • MNGMTCONSOLEWEBPORT is the port number used for the console. Optional parameter. The default is 8082.
  • WEBSERVICELICENSINGPORT is the port number used for the Citrix Licensing Manager. Optional parameter. The default is 8083.
  • CEIPOPTIN specifies whether, or how, to opt in to Citrix Customer Experience Improvement Program (CEIP) or Call Home. Optional parameter. The default is ANON.
    • DIAG - Call Home
    • ANON - CEIP
    • NONE

    You can change the CEIP and Call Home choice using the Citrix Licensing Manager.

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

    #CITRIX CEIP value

    Where value is DIAG, ANON, or NONE

Use the command line to disable or enable the License Management Service

The License Management Service operates automatically within the License Server and allows for license management and support. We recommend using the License Management Service for management of your license environment, but you can disable it any time after installation. For more information, see "Citrix License Management Service" in Technical overview.

Syntax:

ctx_license_management_service.exe (-enable|-disable|-query)

Where:

-enable enables license management. The first upload to Citrix occurs seven days after you install the License Server.

-disable disables license management. We recommend that you use the License Management Service to manage your licensing environment.

-query displays the current configuration.

Import and configure the License Server VPX

The Citrix License Server VPX is distributed as a virtual machine system configured in .xva format.

To import License Server VPX using XenCenter

  1. Open XenCenter, click the server on which to import the License Server VPX, and select Import.
  2. Browse to the location of your package and choose the .xva package.
  3. Choose a Home Server for your virtual machine. This Home Server is the server on which the virtual machine starts automatically. Alternately, you can click a XenServer pool and the virtual machine automatically starts on the most suitable host in that pool.
  4. Choose a storage repository for the virtual disk. The repository must have a minimum of 8 GB of free space.
  5. Define network interfaces. The License Server VPX communicates on a single virtual NIC. Choose a network that is accessible to the Citrix Servers to which you want to provide license services.

After you import the virtual machine, it appears inside your XenCenter management console. You can restart the virtual appliance in XenServer by right-clicking on its name and choosing Start.

Configure the License Server VPX for first use

After importing the License Server VPX, you have a fully functional Citrix License Server on your XenServer pool. The first time you start the License Server, a set up wizard opens to configure networking.

  1. After the wizard opens, create a strong root password for administrators.
  2. Specify a hostname for the License Server VPX.

    Note: Most Citrix license files are tied to the case-sensitive hostname of your License Server.

  3. Specify a domain for the License Server VPX.
  4. Specify whether to use DHCP as your network type. Choose y to obtain network information automatically. Otherwise, choose n, and type the required network information.
  5. Specify a License Administration Console user name and password for the licensing service.
  6. Choose whether to enable the Customer Experience Improvement Program and Call Home. For more information, see About the Citrix Customer Experience Improvement Program (CEIP).
  7. Choose whether to add the VPX License Server to Active Directory domain. If you do, after the setup is complete, follow the instructions to generate and install the key tab file to complete the configuration.  

    Important: If you don't configure Active Directory, then Citrix License Manager, Studio, and Director integration are unavailable.

Configure licenses from a web-based interface, available on port 8082.

If you make a configuration error, log on to the appliance as root with the password you specified. Type the command resetsettings.sh or reset_ceip.sh to rerun the set up wizard.

resetsettings.sh command

resetsettings.sh provides the option to retain or delete historical data files while resetting the Licensing Server VPX configuration. You can fully reset the configuration by deleting all historical data collected until that time or partially reset the configuration by retaining the historical data.

As root, run the following script and make your choices:

# resetsettings.sh


reset_ceip.sh command

reset_ceip.sh provides the option to reset the Customer Experience Improvement Program (CEIP) options you chose during the original configuration. This command resets only the CEIP settings and retains all other settings.

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

#reset_ceip.sh

Export the database for use in a different License Server VPX

Use the migrate_historical_data.sh script to migrate the historical data to a newer Licensing Server VPX. The script provides options to back up and restore historical data.

Run this script as root.

This example procedure migrates the data from VPX_O to VPX_N.

  1. Run the command # migrate_historical_data.sh -b on VPX_O to create a backup file /tmp/historical_data.tar.
  2. When VPX_N is running, copy or move the /tmp/historical_data.tar file to VPX_N using any file transfer protocol. For example, scp.
  3. Run the # migrate_historical_data.sh -r /directory command on VPX_N to restore the data. Where directory is the directory in which historical_data.tar resides.


Generate and install the keytab file

  1. Use the ktpass.exe utility from a Windows server OS (toolkit)that is connected to the same domain. Type the command on one line without returns. The following example shows multiple lines due to space limitations.

    ktpass.exe -princ HTTP/hostFQDN@DOMAINREALM -mapuser domain_account -pass password -out filepath -ptype KRB5_NT_PRINCIPAL
    Where:

    -princ HTTP/hostFQDN@DOMAINREALM specifies the principal name:
           hostFQDN is the Fully Qualified Domain Name of the License Server VPX.
           DOMAINREALM is the Active Directory domain typed in CAPITAL LETTERS.  

-mapuser domain_account specifies a user in the domain that can be used to bind to Active Directory.
Recommendations: Create and use a service account in the domain specifically for keytab creation. Create the account with the name of the VPX server to which the service principal name (SPN) will be mapped.
-pass password specifies any strong password that fulfills the password requirements of your domain.
-out filepath specifies the path where the generated keytab file is saved.
-ptype KRB5_NT_PRINCIPAL specifies the principal type. This is the only supported principal type.

Example:

ktpass.exe -princ HTTP/VPXHOST.example.domain.com@EXAMPLE.DOMAIN.COM –mapuser administrator -pass password –out C:\example.keytab -ptype KRB5_NT_PRINCIPAL

  1. Rename the generated keytab file to ctx_http.keytab.
  2. Securely copy the generated keytab file using secure copy tools (for example, WinSCP or FileZilla) to this path on the License Server VPX:
    /opt/citrix/licensing/LS/conf/ctx_http.keytab
  3. To access the Citrix Licensing Manager, open https://VPXHOST.example.domain.com:8083/
  4. To bind the Active Directory, log on using the user configured in the command in step 1.
  5. To configure and administer other domain users, log on to the Citrix License Administration Console https://VPXHOST.example.domain.com:8082
  6. Add and remove Active Directory users. If you have any issues generating and installing the keytab file, see Troubleshoot.

Important

  • License Server VPX doesn't support Active Directory groups.
  • Because Kerberos authenticates the Active Directory users, the keytab file generation is crucial.
  • As per Kerberos rules, you must map a unique user against the principal name created using ktpass.exe. For more information, see https://technet.microsoft.com/en-us/library/cc753771(v=ws.11).aspx.
Obtain license files with the License Administration Console
  1. From a web browser, go to https://ls:8082.
  2. Click Administration and Vendor Daemon Configuration.
  3. Click Import License.
  4. Click the citrix.com link.
  5. On the My Account page, type your user ID and password.
  6. Select All Licensing Tools.
  7. From the main menu, select Allocate.
  8. Follow the process to allocate and generate your file.
  9. Select the licenses you want to download, click Download, and save the file to and save the file to a temporary directory.
  10. In the License Administration Console on the Import License File page, browse to the license file.
  11. If you copied the file directly to the MyFiles directory, or if a file having the same name exists on the License Server, select Overwrite License File on License Server.
  12. Click Import License.
  13. Click Vendor Daemon Configuration and click Administer in the Citrix vendor daemon line.
  14. Click Reread License Files to allow the license server to recognize the new file.

    Users can begin using these licenses when the License Server reads the licenses.

Move license files from an older License Server VPX version

This procedure moves only the license files. Reconfigure all the users on the new License Server. Ensure that the license files that you move have the correct ownership and permissions.

  1. Back up the license files from the old Citrix License Server VPX to a network share. You can use the script located in /usr/local/bin.
    All the *.lic license files from: /opt/citrix/licensing/myfiles except citrix_startup.lic
  2. Close the old License Server
  3. Spin up the new Citrix License Server VPX using the same binding as the older one.
    The binding might be a MAC address or hostname or IP Address specified in the SERVER line of the license files.
  4. Restore the backed-up license files from the Network Share to the new License Server. Restore the files to: /opt/citrix/licensing/myfiles with the file ownership as ctxlsuser:lmadmin (user:group) and permission as 644.
  5. Run this command as ctxlsuser: /opt/citrix/licensing/LS/lmreread -c @localhost

Manually install a certificate used by the Citrix Licensing Manager and Web Services for Licensing

Note

Use this procedure if you are a Director or Studio administrator who doesn't want to use the self-signed certificate that is generated during installation.

To install a certificate, there are three steps:

  1. Obtain a .pfx file, which contains the certificate and private key. You can use one of two methods to obtain the .pfx file.
  2. Extract the certificate and private key from the .pfx file.
  3. Install the certificate and private key on to the License Server.

Step 1, method 1 - Obtain the .pfx file using a domain certificate

Log on to a server in the domain, open the MMC, and follow these steps:

  1. Create a directory c:\ls_cert to hold the exported .pfx file.
  2. Add the Certificate snap-in by selecting File > Add/Remove Snap-in > Certificates > Computer account > Local computer.
  3. In the left pane under Certificates, right-click Personal and choose All Tasks > Request New Certificate, and then click Next.
  4. In the Certificate Enrollment Policy wizard, choose Active Directory Enrollment Policy, and click Next. Select the check box next to Computer, and select Details to the right.
  5. Select Properties and on the General tab, type a friendly name and description.
  6. On the Subject tab, under Subject Type, choose Common name from the Type drop-down menu. Type a friendly name in the text box, click Add, and then click Apply.
  7. On the Extensions tab, choose Key usage from the drop-down menu, add Digital signature and Key encipherment to the Selected options box.
  8. On the Extended Key Usage drop-down menu, add Server Authentication and Client Authentication to the Selected options box.
  9. On the Private Key tab and under the Key options drop-down menu, ensure that the Key size is 2048. Select the Key Exportable check box, and then click Apply.
  10. On the Certification Authority tab, ensure that the CA check box is selected, and click OK > Enroll > Finish.
  11. In the Certificates console, select Personal > Certificates, click the certificate you built. Select All Tasks > Export > Next, and select the Yes, Export the Private Key radio button and Next.
  12. Under Personal Information Exchange - PKCS #12(.PFX), select the check box to include all certificates, click Next, create a password, and click Next.
  13. Click Browse, navigate to C:\ls_cert and type server.PFX, and then follow the wizard to finish.

Step 1, method 2 - Obtain the .pfx file sending a request to a Certificate Authority (CA)

These steps might vary based on your Certificate Authority.

  1. Log on to the License Server, open the MMC, and follow these steps:
    1. Add the Certificate snap-in by selecting File > Add/Remove Snap-in > Certificates > Computer account > Local computer.
    2. In the left pane under Certificates, right-click Personal and choose All Tasks > Advance Operations > Create Custom Request, and click Next.
    3. In the Certificate Enrollment Policy wizard, choose Proceed without enrollment policy under Custom Request, and click Next.
    4. On the Custom request screen, choose (No template) CNG key from the drop-down menu and PKCS#10 for the Request format, and click Next.
    5. On the Certificate Information screen, choose Details and click Properties.
    6. On the General tab, type a friendly name and description.
    7. On the Subject tab, under Subject name, choose Common name and type a value in the text box.
    8. On the Extensions tab, choose Key usage from the drop-down menu, add Digital signature and Key encipherment.
    9. On the Extensions tab, choose Extended Key usage from the drop-down menu, add Server Authentication and Client Authentication.
    10. On the Private Key tab, under Cryptographic Service Provider, choose RSA, Microsoft Software Key Storage Provider (the default). From the Key options drop-down menu, ensure that the key size is 2048,  select the Key Exportable check box, and then click Apply.
    11. Save the file to a .req file, submit the .req file to a Certificate Authority (CA), and save the .cer file.
  2. In the MMC, under Certificates, right-click Personal and choose All Tasks > Import. In the Import wizard, select the .cer file.
  3. Create a directory c:\ls_cert to hold the exported .pfx file.
  4. In the Certificates console, select Personal > Certificates, and click the certificate you just imported. Select All Tasks > Export > Next, and select the Yes, Export the Private Key radio button and Next.
  5. Under Personal Information Exchange - PKCS #12(.PFX), select the check box to include all certificates, click Next, create a password, and then click Next.
  6. Click Browse, navigate to C:\ls_cert and type server.PFX, and then follow the wizard to finish.

Step 2 - Extract the certificate and private key

This step requires OpenSSL or another tool that allows you to extract the certificate and private key from a .pfx file.

Important: The version of OpenSSL shipped with the License Server does not support extracting certificates and private keys. For information about downloading OpenSSL, go to www.openssl.org. Citrix recommends installing OpenSSL on a separate workstation to perform these steps:
  1. Navigate to the <openssl directory>\bin folder.
  2. Run openssl pkcs12 -in C:\ls_cert\server.pfx -out server.crt -nokeys
    Note: The License Server uses only the .crt certificate format.
  3. Type the password created during the export process (password).
  4. Run openssl pkcs12 -in C:\ls_cert\server.pfx -out server.key -nocerts -nodes
  5. Type the password created during the export process (password).

Step 3 - Install the .crt and .key files on the License Server

Windows - Web Services for Licensing:

  1. Copy the server.crt and server.key created above to cd \program files (x86)\citrix\licensing\WebServicesForLicensing\Apache\conf\.
  2. Restart the Citrix Web Services for Licensing service.

Windows - License Administration Console:

  1. Copy the server.crt and server.key created above to c:\Program Files (x86)\Citrix\Licensing\LS\conf.
  2. Restart the Citrix Licensing service.

VPX:

  1. Copy the server.crt and server.key created above to /opt/citrix/licensing/LS/conf/ and /opt/citrix/licensing/WebServicesForLicensing/Apache/conf/.
  2. etc/init.d/citrixlicensing stop
  3. etc/init.d/citrixlicensing start

Configure a proxy server for use with Citrix Licensing Manager, Customer Experience Improvement Program (CEIP), and Call Home

You can use a proxy with the Citrix Licensing Manager, CEIP, and Call Home. When you configure a proxy server, requests to download licenses and upload Call Home data are sent through a proxy server.

Important

Citrix Licensing components requiring outward bound web communications can inherit network proxy settings using Windows automatic proxy detection. We do not support authenticated proxies. For more information about Windows automatic proxy detection, see WinHTTP AutoProxy Functions.

Configure a proxy server manually

  1. Edit the SimpleLicenseServiceConfig.xml file, which is in the <citrix Licensing>\WebServicesForLicensing directory.
  2. Add a line of xml to the file in the format <Proxy>proxy server name:port number</Proxy>
    Important: The .xml tags are case-sensitive.
Sample Copy

<Configurations>

  <EncoreConfiguration>

    <SamplingPeriod>15</SamplingPeriod>

    <RetentionTime>180</RetentionTime>

    <Enabled>true</Enabled>

  </EncoreConfiguration>

  <Proxy>10.211.55.5:808</Proxy>

</Configurations>