Author: Carl Stalhood

Citrix Federated Authentication Service (SAML) 2407

Last Modified: Aug 20, 2024 @ 8:55 am

1,084 Comments

Navigation

This article applies to Federated Authentication Service (FAS) versions 2407, 2402 LTSR CU1, 2203 LTSR CU5, 1912 LTSR CU9, and all other versions 7.9 and newer.

Change Log

Overview

Citrix Federated Authentication Service (FAS) enables users to log in to Citrix Gateway and Citrix StoreFront using SAML authentication.

With SAML, Citrix Gateway and StoreFront do not have access to the user’s password and thus cannot perform single sign-on to the VDA. FAS works around this limitation by using issuing certificates that can be used to logon to the VDA.

  • StoreFront asks Citrix Federated Authentication Service (FAS) to use a Microsoft Certificate Authority to issue Smart Card certificates on behalf of users.
  • The certificates are stored on the FAS server.
  • The VDA requests the user’s certificate from FAS so it can complete the VDA Windows logon process.

FAS can be used for any authentication scenario where the user’s password is not provided.

Requirements:

  • Microsoft Certification Authority (CA) in Enterprise mode.
    • When configuring FAS, you tell it what CA server to use.
    • You can build a new CA server just for FAS.
    • You can install CA on the FAS server.
  • Domain Controllers must have Domain Controller certificates. See CTX218941 FAS – Request not supported.
    • The certificates on the Domain Controllers must support smart card authentication. Certificates created using the Microsoft CA certificate template named Domain Controller Authentication supports smart cards. Manually created Domain Controller certificates might not work. See CTX270737 for the Domain Controller certificate requirements.

  • Citrix Virtual Apps and Desktops or XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • Citrix Gateway.
    • StoreFront 3.9 and newer also support SAML authentication natively without Citrix ADC.
  • SAML in an nFactor (Authentication Virtual Server) configuration works in both browsers and Workspace app.
  • For multiple domains, see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.

Configuration overview:

  1. Build one or more FAS servers.
    • For security reasons, FAS should be its own server and not installed on a Delivery Controller.
  2. Upload Certificate Templates to Active Directory and configure a CA server to issue certificates using the new templates.
    • Enterprise Admin permissions are needed to upload the Certificate Templates.
    • One of the Certificate Templates is for Smart Card logon to Citrix VDA.
    • The other two Certificate Templates are to authorize FAS as a certificate registration authority.
    • The registration authority certificate does not renew automatically so be prepared to renew it manually every two years. See Renew registration authority certificates at Citrix Docs.
  3. Install the Citrix FAS group policy .admx template into PolicyDefinitions.
  4. Create a group policy object (GPO) and configure the GPO with the addresses of the FAS servers.
    • The GPO must apply to FAS servers, StoreFront servers, and every VDA. It does not need to apply to Delivery Controllers, but there’s no harm in applying it to the Delivery Controllers.
  5. Authorize FAS to request certificates from a Microsoft CA server.
  6. Configure FAS Rules to permit StoreFront servers to request FAS to generate certificates for users and permit VDA machines to retrieve the certificates from FAS.
  7. Configure StoreFront to use FAS for VDA single sign-on.

Links:

From Citrix CTX225721 Federated Authentication Service High Availability and Scalability: you can build multiple FAS servers. Enter all FAS server FQDNs in the Group Policy. StoreFront will then use a hashing algorithm on the username to select a FAS server.

  1. If you have less than 10K users, one FAS server with 4 vCPUs (2.5Ghz) should be sufficient.
  2. You will require a minimum of one FAS server (with 8 vCPUs) per 25,000 users if all users expect to be able to logon under cold start conditions (no keys or certificates cached) within 60-90 minutes.
  3. A single FAS server can handle greater than 50K users under warm start conditions (keys and certificates pre-cached)
  4. One reserve FAS server for every four FAS servers for “Day 1” cold start (Users get new keys/certificates) & disaster recovery scenarios
  5. Split the FAS Certificate Authority from Certificate Authority that performs other tasks for both security and scalability purposes.

Michael Shuster explains the Group Policy configuration for FAS in multiple datacenters at HowTo: Active-Active Multi-Datacenter Citrix FAS.

Also see the Citrix Federated Authentication Service Scalability whitepaper.

Federated Authentication Service Versions

The most recent Federated Authentication Service Current Release is version 2407.

For LTSR versions of Citrix Virtual Apps and Desktops (CVAD) and StoreFront, install the version of FAS that comes with the CVAD LTSR version.

Install/Upgrade Federated Authentication Service

The service should be installed on a secure, standalone server that does not have any other Citrix components installed. The FAS server stores user authentication keys, and thus security is paramount.

  1. On the Federated Authentication Service server, go to the Citrix Virtual Apps and Desktops, or XenDesktop 7.9, or newer ISO, and run AutoSelect.exe. Or you can download the standalone installer and run that.
  2. In the lower half of the window, click Federated Authentication Service.
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  4. In the Core Components page, click Next.
  5. In the Firewall page, click Next.
  6. In the Summary page, click Install.
  7. The installer will probably ask for a restart.

    1. After the reboot, and after logging in again, you might see a Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window. Don’t click anything yet.
    2. Go to the Citrix_Virtual_Apps_and_Desktops_7_2407_iso file and mount it.
    3. Go back to the Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window.
    4. On the left, expand This PC, and click the DVD Drive.
    5. Click Select Folder.
  8. Click Finish.

FAS Group Policy

Configure a Group Policy that instructs StoreFront servers and VDAs on how to locate the FAS servers.

  1. On the Federated Authentication Service server, browse to C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions. Copy the files and folder.
  2. Go to \\domain.com\SYSVOL\domain.com\Policies\PolicyDefinitions and paste the files and folder. If PolicyDefinitions doesn’t exist in SYSVOL, then copy them to C:\Windows\PolicyDefinitions instead.
  3. Edit a GPO that applies to all StoreFront servers, all Federated Authentication Service servers, and all VDAs.
  4. Navigate to Computer Configuration > Policies > Administrative Templates > Citrix Components > Authentication.
  5. Edit the setting Federated Authentication Service.
  6. Enable the setting and click Show.
  7. Enter the FQDN of the Federated Authentication Service server. You can add more than one Federated Authentication Service server.
  8. Click OK twice.
  9. On the Federated Authentication Service server, and VDAs, run gpupdate.
  10. On the FAS server, and on VDAs, look in the registry at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses. Make sure this key and value exists. The number one cause why FAS doesn’t work is because this key is missing from VDAs. The FAS Address GPO must apply to VDAs too.
  11. If the VDAs and Users are in different domains, see CTX220497 Users from one AD Domain not able to get FAS user certificates from another trusted domain: add the Citrix StoreFront Servers, FAS server and VDA servers to the Windows Authorization Access Group in the users’ domain. Also see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.
  13. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable CRL checking by configuring HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors (DWORD) = 1 as detailed at CTX217150 Unable to login using the FAS Authentication – Getting Stuck on Please wait for local session manager.
  14. If your VDAs have third party credential providers (e.g., Duo), then it might interfere with FAS Single Sign-on.

FAS 1909+ Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

FAS 1909 and newer have a different configuration GUI than FAS 1906 and older.

Here are 1909 and newer GUI configuration instructions:

  1. Log into the FAS server as an Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. In the tab named Initial Setup, in the row named Deploy certificate templates, click Deploy.
  4. Click OK to deploy the templates to Active Directory.
  5. In the row named Set up a certificate authority, click Publish.
  6. Select an Enterprise Certificate Authority that will be issue the FAS certificates and click OK.
  7. In the row named Authorize this service, click Authorize.
  8. Select a CA that will issue this FAS server a Registration Authority certificate. Later, you will need to open the Certificate Authority console on the chosen server. Click OK.
  9. The row named Authorize this service has a new icon indicating it is waiting on the registration authority certificate to be approved.
  10. Open the Certification Authority console and point it to the CA server. In the Pending Requests node, find the certificate request for the FAS server and Issue it.
  11. Back in the FAS Administration Console, on the top right, click Refresh.
  12. The row named Authorize this service should now have a green check mark.
  13. In the row named Create a rule, click Create.
  14. In the Rule name page, leave it set to Create the default rule and click Next.
  15. In the Template page, click Next.
  16. In the Certificate authority page, select the CA that has the issuing templates configured and click Next. You can select more than one CA server.
  17. In the In-session use page, click Next.
  18. In the Access control page, click the link to Manage StoreFront access permissions.
  19. In the Permission for StoreFront Servers page, add your StoreFront servers and give them the permission Assert Identity. Click OK.
  20. Back in the Create Rule wizard, click Next.
  21. In the Restrictions page, you can optionally reduce the VDAs that are authorized to use FAS. Click Next.
  22. In the Summary page, click Create.
  23. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • In the row named Authorize this service, you can click the link for authorization certificate to see when it expires. Before expiration, use the Reauthorize button on the right of the same row.
  24. Jump ahead to Certificate Templates.

FAS 1906 and older Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

Here are GUI configuration instructions for FAS 1906 and older:

  1. Log into the FAS server as a Domain Administrator or Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  4. In Step 1: Deploy certificate templates, click Start.
  5. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  6. In Step 2: Setup Certificate Authority, click Start.
  7. Select a Certificate Authority to issue the certificates, and click Ok.
  8. In Step 3: Authorize this Service, click Start.

    • Step 3 automatically submits an online request for the Registration Authority certificate to the CA and stores the non-exportable private key in the standard Microsoft Enhanced RSA and AES Cryptographic Provider.
    • Alternatively, you can submit the certificate request manually, and store the private key in TPM or HSM as detailed at Federated Authentication Service private key protection at Citrix Docs. When running New-FasAuthorizationCertificateRequest, the -UseTPM switch is optional.
  9. Select the issuing Certificate Authority, and click OK.

    • Authorize this Service only lets you select one Certificate Authority. If you want to load balance certificate requests against multiple Certificate Authorities, then see Set up multiple CA servers for use in FAS at Citrix Docs. 
      Set-FasCertificateDefinition -Name default_Definition -CertificateAuthorities @("ca1.corp.local\CA1.corp.local", "ca2.corp.local\ca2.corp.local")
  10. Step 3 is now yellow.
  11. On the Microsoft CA server, go to the Certification Authority Console > Pending Requests. Find the pending request, and Issue it.
  12. In a minute or two, Federated Authentication Service will recognize the issued certificate and Step 3 will turn green.
  13. After FAS authorization with the CA, in the FAS Configuration tool, switch to the User Rules tab.
  14. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  15. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  16. Click Edit next to List of StoreFront servers that can use this rule.
  17. Remove Domain Computers from the top half, and instead add your StoreFront servers. You could add an Active Directory security group instead of individual StoreFront servers.
  18. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  19. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  20. When done, click Apply.
  21. Click OK when you see Rule updated successfully.
  22. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • To see the expiration date of the authorization certificate, run the following PowerShell command after running add-pssnapin Citrix.Authentication.FederatedAuthenticationService.V1: 
      Get-FasAuthorizationCertificate -FullCertInfo -address myFASServer

Certificate Templates

The deployed FAS Certificate Templates from older versions of FAS have Autoenroll enabled. Newer versions of FAS (e.g., 2203) no longer have Autoenroll enabled.

  1. Open the Certificate Templates console. One option is to open the Certification Authority console, right-click Certificate Templates, and then click Manage.
  2. There should be three templates with names starting with Citrix_. Open the properties on each one.
  3. On the Security tab, highlight each group assigned to the template.
  4. On the bottom half, uncheck the box in the Autoenroll row but leave Enroll checked. Perform this step for every group assigned to this template. Then click OK.
  5. Repeat disabling autoenroll for the other two templates.

The Registration Authority certificate templates are permitted to all Domain Computers. You might want to change that.

  1. Open the Properties of one of the Citrix_RegistrationAuthority certificate templates.
  2. On the Security tab, remove Domain Computers.
  3. Add your FAS servers and enable the Enroll permission.
  4. Repeat for the other Registration Authority certificate.

To further restrict who can be issued certificates, go to your Certificate Authority’s Properties and use the Enrollment Agents tab to restrict enrollment agents.

StoreFront Configuration

Once FAS is enabled on a StoreFront store, it applies to all connections through that store, including password-based authentications. One option is to create a new store just for FAS users.

  1. Check the registry at at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses to confirm that the group policy with FAS addresses has been applied to the StoreFront servers.
  2. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command: 
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  3. Run the following commands. Adjust the store name as required. 
    $StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
  4. If you have multiple StoreFront servers, Propagate Changes.
  5. In Web Studio (CVAD 2212 and newer), go to Settings and Enable XML Trust.

    • Or on a Citrix Delivery Controller, run the following PowerShell command: 
      Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

If you ever need to disable FAS on StoreFront, run the following commands. Adjust the store name as required.

$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""

SAML Configuration

SAML Flow

SAML flows like this:

  1. (Optional) User goes to the web application aka Service Provider (e.g. Citrix Gateway).
    • The Service Provider (SP) redirects the user’s browser to the Identity Provider’s (IdP) SAML Single Sign-on (SSO) URL and includes an authentication request in the Redirect. The IdP SSO URL might be different for each Service Provider.
    • The Authentication Request from the Service Provider includes a Service Provider Entity ID. The IdP matches the SP Entity ID with an entry in its database so it knows which SP is making the authentication request. The Entity ID must match on both the SP and the IdP.
    • If the Authentication Request is signed by the Service Provider’s certificate private key, then the IdP will verify the signature using the Service Provider’s certificate public key. In this scenario, the Service Provider’s certificate (without private key) must be loaded into the IdP.
  2. The user authenticates to the IdP, typically using Multi-factor Authentication.
    • If the user was redirected from the SP, then the IdP already knows which SP to authenticate with.
    • If the user went directly to the IdP, then the user typically needs to click an icon representing the web application (Service Provider).
  3. IdP generates a SAML Assertion containing the user’s userPrincipalName or email address.
    • Configure the IdP to include the user’s UPN or email address in the NameID field of the assertion. SAMAccountName won’t work with Citrix FAS.
    • The SAML Assertion also includes the Service Provider’s Entity ID. The ID in the Assertion must match the ID configured on the SP.
    • IdP signs the SAML Assertion using an IdP certificate private key.
    • IdP has a configuration for the SP that includes a SAML Assertion Consumer Service (ACS) URL. IdP redirects the user’s browser to the SP’s ACS URL and POST’s the SAML Assertion.
      • The ACS URL on Citrix Gateway ends in /cgi/samlauth
  4. SP uses the IdP certificate’s public key to verify the signature on the SAML Assertion.
    • The IdP’s certificate (without private key) is installed on the Citrix ADC so it can verify the Assertion’s signature.
  5. SP extracts the user’s userPrincipalName from the Assertion and uses the UPN for Single Sign-on to StoreFront and the rest of the Citrix components.
    • Note that the SP does not have access to the user’s password and thus that’s why we need Citrix FAS to generate certificates for each user.

Configure the SAML IdP

You typically start the configuration on the Identity Provider (IdP). Every IdP has unique instructions. Search Google for your IdP and Citrix ADC and you might find a IdP-specific guide. After IdP configuration, you download the IdP’s certificate and copy the IdP’s SSO URL so you can configure them on Citrix ADC.

Azure AD as SAML IdP

  1. In Azure Portal, go to Azure Active Directory.
  2. On the left, click Enterprise applications.
  3. In the new blade that appears, on the All applications page, on the right, click New application.
  4. In the All Categories view of the gallery, on the top right, click Non-gallery application.
  5. Give the application a descriptive name. Azure AD shows this name in the myapps portal. Click Add.
  6. After the application is created, on the left, in the Manage section, click Single sign-on.
  7. On the right, click the big button for SAML.
  8. In section 1 labelled Basic SAML Configuration, click the pencil icon.
  9. In the Identifier (Entity ID) field, enter an identifier in URI format. Usually it matches the FQDN of the Citrix Gateway and can be entered in https://gateway.corp.com format. You’ll later need to specify the exact same Identifier on the Citrix ADC.
  10. In the Reply URL (Assertion Consumer Service URL) field, enter a URL similar to https://mygateway.company.com/cgi/samlauth. The path must be /cgi/samlauth. The scheme should be https. And the FQDN is your Citrix Gateway’s FQDN.
  11. Click Save. Then you might have to click the x on the top right to make it go away.
  12. In section 2 labelled User Attributes & Claims, notice that it defaults to sending the userprincipalname. You can click the pencil to change the attribute used for the Name identifier value. Whatever value you send will need to match the userPrincipalNames of local Active Directory accounts (aka shadow accounts).


  13. In section 3 labelled SAML Signing Certificate, click the Download link in the Certificate (Base64) line.
  14. Citrix ADC 12.1 and newer support SAML metadata so feel free to copy the App Federation Metadata Url field.
  15. If you are running NetScaler 12.0 or older, then you will need to copy the Login URL field from section 4 labelled Set up gateway5.corp.com
  16. On the left, under Manage, click Users and groups.
  17. Use the normal process to assign Azure AD users and groups to this application. Click Assign.
  18. Jump to the section named Citrix ADC SAML Configuration.

ADFS as SAML IdP

The screenshots in this section use ADFS as an example IdP. Your IdP will be different.

  1. In your SAML IdP, create a Relying Party Trust (aka service provider trust) or new Application.
  2. Since we’re configuring the IdP before we configure Citrix ADC and thus don’t have access to the SP metadata, select the option to Enter data about the relying party manually.
  3. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your Citrix Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  4. Enter a Relying party trust identifier in URI format. You must specify the same identifier (Issuer Name) on the Citrix ADC as detailed in the next section.
  5. Configure the SAML IdP to send email address or User-Principal-name as Name ID. Citrix ADC receives the Name ID and sends it to StoreFront. StoreFront will look in Active Directory for an account with userPrincipalName that matches the Name ID.
  6. Citrix ADC will sign the authentication requests it sends to the IdP. On the Citrix ADC, you will soon configure the Citrix ADC SAML SP signing certificate with private key that signs the authentication requests that are sent to the IdP. In your SAML IdP, import the same Citrix ADC SAML SP signing certificate but without the private key.
  7. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML IdP. You’ll need to enter this same URL on your Citrix ADC later.
  8. Export the IdP Token-signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping, etc.

Citrix ADC SAML Configuration

SAML Server/Action

  1. Instructions for Citrix ADC 13.0, Citrix ADC 12.1, NetScaler 12.0, and NetScaler 11.1 are essentially the same.
    • Citrix ADC 12.1 and newer support SAML Metadata while older versions of NetScaler do not support SAML Metadata.
    • NetScaler 11 is very similar, except Certificates are in a different place in the NetScaler menu tree.
  2. Workspace app support – If you bind a SAML Authentication Policy directly to the Gateway Virtual Server (no nFactor/AAA), then Workspace app and Gateway VPN plug-in won’t work. To support SAML with Workspace app and Gateway VPN plug-in, configure nFactor (Authentication Virtual Server with Authentication Profile) instead of directly on the Gateway Virtual Server.
  3. IdP Signing Certificate – On Citrix ADC, if you are not importing IdP metadata, then manually import the IdP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. Citrix ADC uses this certificate to verify the signature of the SAML assertion from the IdP.
    Note: when you later create the SAML Action on Citrix ADC, there’s a place to add a SAML certificate. Unfortunately, the SAML Action is trying to import the wrong type of certificate since it wants the private key, which you don’t have access to. If you import the certificate here under CA Certificates, then there’s no prompt for private key.


    • SAML IdP certificates are shown in the Unknown Certificates node.
  4. If you want ADC to sign the authentication requests it sends to the IdP, then do the following:
    1. Move up two nodes to Server Certificates and Import or create a SP SAML signing certificate with private key. This can be the same certificate used on Citrix Gateway. Or a more common practice is to create a self-signed certificate.

    2. You’ll also need to import this SAML SP signing certificate (without private key) to your SAML IdP so it can verify the SAML authentication request signature from the Citrix ADC.
  5. Go to Citrix Gateway > Policies > Authentication > SAML. The quickest way to get here is to enter SAML in the search box on top of the menu.
  6. On the right, switch to the tab labelled Servers, and click Add.
  7. In the Name field, give the SAML Action a name that indicates the IdP’s name.
  8. If your Citrix ADC is 12.1 or newer, then get the SAML Metadata URL (or file) from the IdP.

    1. In the SAML Server on Citrix ADC, in the SAML IDP Metadata URL field, paste in the URL. ADC should be able to extract the IdP’s certificate from the Metadata URL.
    2. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    3. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. To avoid relay state “does not match” error, make sure users enter the Gateway URL instead of using a bookmark. 💡 
      AAA.LOGIN.RELAYSTATE.EQ("https://gateway5.corp.com/")

    4. Scroll down and click More.
    5. You can optionally check Force Authentication to prevent users from doing SAML authentication using cached credentials. This prompts for MFA every time the user accesses Citrix Gateway.
    6. Scroll down and click Create.
    7. Edit the SAML Server again.
    8. If you uncheck the box next to Import Metadata, you can see the fields that it filled in for you. Unfortunately, other fields must be configured manually as detailed soon.
  9. Configure the SAML Server based on the data provided by your IdP. If you imported Metadata, then some of the fields might already be populated.
    1. For IDP Certificate Name, select the SAML IdP’s certificate that was exported from the SAML IdP and imported to Citrix ADC. Citrix ADC will use this IdP certificate to verify SAML assertions from the IdP.
      Note: the Add button here does not work correctly. Instead, if you need to import the SAML IDP certificate, then do it at the CA Certificates node as detailed earlier in this section.
    2. For Redirect URL, enter the URL to the SAML IdP’s authentication page. Citrix Gateway will redirect users to this URL. For ADFS, enter your ADFS URL appended with /adfs/ls (e.g. https://adfs.corp.com/adfs/ls). For other IdP’s, get the URL from your IdP.
    3. For User Field, enter the name of the SAML Claim from the IdP that contains the value that matches the userPrincipalName of your local Active Directory users (aka shadow accounts). This defaults to the NameID field, but you might have to use a different claim, like emailaddress.
    4. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    5. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. 💡
    6. Optionally, for Signing Certificate Name, select the SAML SP certificate (with private key) that Citrix ADC will use to sign authentication requests to the IdP. This same certificate (without private key) must be imported to the IdP, so the IdP can verify the authentication request signature. This field usually isn’t needed by most IdPs.
    7. Scroll down and click More.
    8. Citrix ADC defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
    9. Review the other settings as needed by your IdP. Click Create when done.

SAML Policy – Advanced (nFactor) Method

Workspace app and Gateway Plugin (i.e. VPN plugin) require nFactor (Advanced Authentication Policies) to support SAML authentication.

Licensing – nFactor requires NetScaler ADC Advanced Edition or NetScaler ADC Premium Edition. The newest builds of NetScaler ADC 13 have added nFactor support for NetScaler ADC Standard Edition, but the configuration of an Authentication Virtual Server is not directly accessible from the main menu. If you only have Standard Edition, then do the following to get to the Authentication Virtual Server:

  1. Go to Citrix Gateway > Virtual Servers and edit one.
  2. On the right, add the Authentication Profile section.
  3. On the left, in the Authentication Profile section, click Add to create an Authentication Profile.
  4. In the Authentication Virtual Server row, click Add to create an Authentication Virtual Server.
  5. The rest of the nFactor configuration is similar to what’s detailed below.

If you prefer to configure the older Classic Method, which doesn’t work with Workspace app, then skip to the Classic Method.

Do the following to create an Advanced Authentication Policy, an Authentication Virtual Server, and bind it to the Gateway Virtual Server:

  1. In the left menu, expand Security, expand AAA – Application Traffic, expand Policies, expand Authentication, expand Advanced Policies, and then click Policy.
  2. On the right, click the button labelled Add.

    1. Change the drop-down for Action Type to SAML.
    2. Change the drop-down for Action to the SAML Action you created earlier.
    3. In the box labelled Expression, enter true.
    4. Give the policy a name and click Create.
  3. In the left menu, expand Security, expand AAA – Application Traffic and then click Virtual Servers.
  4. On the right, click the button labelled Add.

    1. Change the drop-down named IP Address Type to Non Addressable and then click OK.
  5. You can optionally bind a Server Certificate. If you don’t bind a certificate, then the AAA vServer will be down but it will still work. It doesn’t matter what certificate you choose. Click Continue when done.
  6. On the left, in the section named Advanced Authentication Policies, click the row that says No Authentication Policy.

    1. Click where it says Click to select.
    2. Click the small circle to the left of the SAML Policy that you created earlier. Then click the blue button labelled Select at the top of the screen.
    3. There’s no need to configure Select Next Factor unless you want to bind an LDAP Policy with Authentication Disabled so you can extract groups from Active Directory and use those groups for Gateway authorization. This configuration procedure is detailed in the next section.
    4. Click the blue button labelled Bind at the bottom of the window.
  7. Click Continue,
  8. At the bottom of the page, click Done to finish creating the AAA vServer.
  9. In the left menu, expand Citrix Gateway and click Virtual Servers.
  10. On the right, edit your existing Gateway Virtual Server.
  11. On the right side of the screen, in the Advanced Settings column, click Authentication Profile.
  12. On the left side of the screen, find the Authentication Profile section and then click the button labelled Add.
  13. Click where it says Click to Select and then select your AAA vServer.
  14. Give the Authentication Profile a name and then click the blue button named Create.
  15. Make sure you click the blue OK button before you click Done. If you don’t click OK then your changes won’t be saved.

Here are some sample CLI commands for this nFactor SAML configuration.

# SAML Actions
# ------------
add authentication samlAction "Azure AD" -samlIdPCertName AzureADSAML -samlSigningCertName WildcardCorpCom -samlRedirectUrl "https://login.microsoftonline.com/815e26a9-4a9b/saml2" -samlIssuerName gateway5.corp.com -Attribute1 emailaddress -logoutURL "https://login.microsoftonline.com/815e26a9/saml2" -logoutBinding REDIRECT -relaystateRule "aaa.LOGIN.RELAYSTATE.EQ(\"https://gateway5.corp.com/\")"

# SAML Authentication Policies
# ----------------------------
add authentication samlPolicy "Azure AD" ns_true "Azure AD"

# Advanced Authentication Policies
# --------------------------------
add authentication Policy "Azure AD Advanced" -rule true -action "Azure AD"

# Authentication Virtual Servers
# ------------------------------
add authentication vserver nFactor-AzureAD-SAML SSL 0.0.0.0
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -gotoPriorityExpression NEXT

# Authentication Profiles
# -----------------------
add authentication authnProfile nFactor-AzureAD-SAML -authnVsName nFactor-AzureAD-SAML

# Citrix Gateway Virtual Servers
# ------------------------------
set vpn vserver gateway5.corp.com -authnProfile nFactor-AzureAD-SAML

SAML nFactor LDAP Group Extraction

If you use AAA Groups with Citrix Gateway, then be aware that SAML usually does not provide the user’s group membership. Instead, configure a LDAP Policy to get the user’s groups from Active Directory so the groups can be later used by Citrix Gateway.

If you don’t need LDAP Group Extraction, then skip ahead to the StoreFront section.

Do the following to configure LDAP Group Extraction.

  1. Create a new LDAP Action.
    1. Use the Search in Menu to find LDAP then pick any of the results.
    2. Check the box next to an existing LDAP policy and click Add to copy its configuration. Or create a new one.
    3. Change the name of the LDAP Action.
    4. On the top right, uncheck the box next to Authentication.
    5. Scroll down a bit and in the right side re-enter the Administrator Password. Copying an existing LDAP Action does not copy the Bind password.
    6. Scroll down to the Other Settings section.
    7. On the left, change Server Logon Name Attribute to –<< New >>–.
    8. Enter userPrincipalName. The UPN is extracted from the SAML Assertion.
    9. Scroll down and click Create.
  2. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy and click Add to create a new Policy.

    1. Change Action Type to LDAP.
    2. Expression = true.
    3. Click Create.
  3. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy Label. On the right, click Add.

    1. Give the Policy Label a name and click Continue. The Login Schema should be LSCHEMA_INT.
    2. Select your LDAP Group Extract policy and then on the bottom click Bind.
    3. Click Done to close the Policy Label.
  4. On the left, go to Security > AAA – Application Traffic > Virtual Servers. On the right, edit your SAML AAA vServer.

    1. Click where it says 1 Authentication Policy.
    2. Right-click the Authentication Policy and then click Edit Binding.
    3. In the Select Next Factor field, click where it says Click to select.
    4. Select your LDAP Group Extract Policy Label and then click Bind.
  5. Skip ahead to the StoreFront section.

Here are some sample CLI commands for this nFactor SAML LDAP Group Extract configuration.

# LDAP Actions
# ------------
add authentication ldapAction LDAP-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword ****** -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

# LDAP Policies
# -------------
add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp

# Authentication Policy Labels
# ----------------------------
add authentication policylabel LDAP-GroupExtract -loginSchema LSCHEMA_INT
bind authentication policylabel LDAP-GroupExtract -policyName LDAP-GroupExtract -priority 100 -gotoPriorityExpression NEXT

# Authentication Virtual Servers
# ------------------------------
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -nextFactor LDAP-GroupExtract -gotoPriorityExpression NEXT

Configure StoreFront for SAML Citrix Gateway

  1. In StoreFront 3.6 or newer, in the StoreFront Console, go to Stores, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from Citrix Gateway is selected.
  3. Click the bottom gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to Citrix Gateway and click OK twice.
  5. In StoreFront, add a Citrix Gateway object that matches the FQDN of the Citrix Gateway Virtual Server that has SAML enabled.
  6. On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.
  7. Then assign (Configure Remote Access Settings) the Gateway to your Store.

  8. Next step: create Active Directory Shadow Accounts

Native SAML on StoreFront without Citrix ADC

StoreFront 3.9 and newer have native support for SAML Authentication without Citrix ADC. Notes:

  • SAML overrides Explicit and Pass-through authentication.
  • SAML in StoreFront without Citrix ADC seems to work in Workspace app and Receiver Self-Service for Windows.

For an example configuration using StoreFront PowerShell commands and SAML metadata, see CTX232042 Configure StoreFront with OKTA.

To configure native SAML in StoreFront 3.9 or newer:

  1. Export the signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping Identity, etc.
  2. In StoreFront 3.9 or newer console, right-click a Store, and click Manage Authentication Methods.
  3. Check the box next to SAML Authentication. If you don’t see this option (because you upgraded from an older version), click the Advanced button on the bottom of the window, and install the authentication method.
  4. On the right, click the gear icon for SAML, and click Identity Provider.
  5. Change the SAML Binding to the method your IdP expects.
  6. Enter the IdP token issuance endpoint URL. For example, in ADFS, the path is /adfs/ls.
  7.  Click Import.
  8. Browse to the signing certificate exported from your IdP, and click Open.
  9. Then click OK to close the Identity Provider window.
  10. On the right, in the SAML Authentication row, click the gear icon, and then click Service Provider.
  11. Click the first Browse button.
  12. Give the Signing certificate a name, and save it somewhere.
  13. Click the second Browse button.
  14. Give the Encryption certificate a name, and save it somewhere.
  15. Copy the Service Provider Identifier. Or you can change it to your desired value. Then click OK.
  16. In your IdP (e.g. ADFS), create a Relying Party Trust.
  17. Import the Encryption certificate that you exported from StoreFront.
  18. Enable SAML 2.0.
  19. For the Assertion Consumer Service (ACS) path, enter something similar to https://storefront.corp.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService. The hostname portion of the URL is equivalent to your StoreFront Base URL. /Citrix/StoreAuth matches your Store name with Auth on the end. The rest of the path must be /SamlForms/AssertionConsumerService. You can get this ACS value by looking in the SAML metadata at the bottom of https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata.

  20. For the Relying party trust identifier, enter the identifier you copied from the Service Provider window in StoreFront.
  21. Configure the Claim Rules to send the user’s email address or userPrincipalName as Name ID.
  22. Edit the Relying Party Trust. Import the Signing certificate that you exported from StoreFront.

  23. Create Active Directory Shadow Accounts. Federated users must be userPrincipalName mapped to local Active Directory accounts.
  24. If you point your browser to https://<storefront-host>/Citrix/<storename>Auth/SamlTest, it should perform a SAML Login, and then show you the assertion that was returned from the IdP. See Citrix CTX220639 How to configure SAML Authentication-Test Configuration.
  25. See Citrix CTX220682 Storefront SAML Troubleshooting Guide for event logs, SAML Metadata, Active Directory account mapping, Trust XML, etc.
  26. When you go to your Receiver for Web page, it should automatically redirect you to your IdP. After authentication, it should redirect you back to StoreFront and show you your icons.
  27. ADFS also works in Receiver 4.6 and newer, and Workspace app.
  28. When you logoff, it won’t let you log on again unless you close your browser and reopen it.

  29. To fix this problem, see CTP Sacha Thomet StoreFront – Allow relogin without browser close. Edit the file C:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js, and add the following line: 
    CTXS.allowReloginWithoutBrowserClose = true

  30. Now when you logoff, you’re given an option to log on again.

Active Directory Shadow Accounts

To login to Windows (Citrix VDA), every user must have an Active Directory account in a domain trusted by the VDA. For Federated Users, you typically need to create shadow accounts for each Federated user in your local Active Directory. These Shadow accounts need a userPrincipalName that matches the SAML attribute (usually email address) provided by the SAML IdP.

If the email address provided by the SAML IdP does not match the UPN suffix for your domain, then do the following:

  1. Open Active Directory Domains and Trust.
  2. Right-click the top left node (not a domain node), and click Properties.
  3. In the UPN Suffixes tab, add a UPN suffix that matches the email suffix provided by the SAML IdP.
  4. When creating a shadow account in your Active Directory, the new UPN suffix is available in the drop-down list. Note that the pre-Windows 2000 logon name can’t conflict with any other user in the domain.
  5. The password for these Shadow accounts can be any random complex password since the Federated users never need the Shadow account’s password.
  6. If the shadow account is already created, edit the account, and on the Account tab, use the drop-down to select the new UPN suffix.
  7. Create a shadow account for every federated user. There are third party Identity Management tools that can automate this. Or get an export from the IdP and use PowerShell scripting to create the acccounts.

Verify FAS

When FAS is enabled on StoreFront, every user that logs into StoreFront (local or remote) causes a user certificate to be created on the FAS server. You can see these user certificates by running the following PowerShell commands:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Get-FasUserCertificate -address fas01.corp.local

Citrix uses these certificates to logon to the VDA as the user. No password needed.

Virtual Delivery Agent (VDA) 7.6.9000 (LTSR CU9)

Last Modified: Nov 7, 2020 @ 6:35 am

31 Comments

Navigation:

💡 = Recently Updated

Change Log

Hardware

  1. For virtual desktops, give the virtual machine: 2+ vCPU and 2+ GB of RAM
  2. For Windows 2008 R2 RDSH, give the virtual machine 4 vCPU and 12-24 GB of RAM
  3. For Windows 2012 R2 RDSH, give the virtual machine 8 vCPU, and 24-48 GB of RAM
  4. If using PvS RAM caching, add more RAM for the cache
  5. Remove the floppy drive
  6. Remove any serial or LPT ports
  7. If vSphere:
    1. To reduce disk space, reserve memory. Memory reservations reduce or eliminate the virtual machine .vswp file.
    2. The NIC should be VMXNET3.
  8. If this VDA will boot from Provisioning Services:
    1. Do not enable Memory Hot Plug
    2. For vSphere, the NIC must be VMXNET3.
    3. For vSphere, configure the CD-ROM to boot from IDE instead of SATA. SATA comes with VM hardware version 10. SATA won’t work with PvS.
  9. Install the latest version of drivers (e.g. VMware Tools)
    1. If Windows 7 on vSphere, don’t install the VMware SVGA driver. For more details, see CTX201804 Intermittent Connection Failures/Black Screen Issues When Connecting from Multi-Monitor Client Machines to Windows 7 VDA with VDA 7.x on vSphere/ESXi.

If vSphere, disable NIC Hotplug

  1. Users could use the systray icon to Eject the Ethernet Controller. Obviously this is bad.
  2. To disable this functionality, power off the virtual machine.
  3. Once powered off, right-click the virtual machine and click Edit Settings.
  4. On the VM Options tab, expand Advanced and then click Edit Configuration.
  5. Click Add Row.
  6. On the left, enter devices.hotplug. On the right, enter false.
  7. Then click OK a couple times to close the windows.
  8. The VM can then be powered on.

Windows Preparation

  1. Computer Group Policy – Make sure the Master VM is in the same OU as the Linked Clones so the Master VM will get the computer-level GPO settings in its registry. Run gpupdate on the master after moving the VM to the correct OU. When Clones are created from the Master, the computer-level GPO settings will already be applied, thus eliminating a timing issue.  💡
  2. If RDSH, disable IE Enhanced Security Configuration in Server Manager > Local Server.
  3. Optionally, go to Action Center (Windows 8.1 or 2012 R2) or Security and Maintenance (Windows 10) to disable User Account Control and enable SmartScreen .
  4. Run Windows Update.
  5. Add your Citrix Administrators group to the local Administrators group on the VDA. Computer Management.
  6. The Remote Desktop Services “Prompt for Password” policy prevents Single Sign-on to the Virtual Delivery Agent. Check registry key HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services. If fPromptForPassword = 1 then you need to fix group policy. The following GPO setting will prevent Single Sign-on from working.
    Computer Configuration | Policies | Administrative templates | Windows Components | Remotes Desktop Services | Remote desktop Session Host | Security | Always prompt for password upon connection
    Or set the registry value HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ PorticaAutoLogon (DWORD) = 0x10.
  7. For Windows 7 VDAs that will use Personal vDisk, install Microsoft hotfix 2614892 – A computer stops responding because of a deadlock situation in the Mountmgr.sys driver. This hotfix solved a Personal vDisk Image update issue detailed at Citrix Discussions.
  8. If this VDA is Windows Server 2008 R2, request and install the Windows hotfixes recommended by Citrix CTX129229. Scroll down to see the list of recommended Microsoft hotfixes for Windows Server 2008 R2. Ignore the XenApp 6.x portions of the article. Also see https://www.carlstalhood.com/windows-server-2008-r2-post-sp1-hotfixes/.
  9. To remove the built-in apps in Windows 10, see Robin Hobo How to remove built-in apps in Windows 10 Enterprise.
  10. For Remote Assistance in Citrix Director, configure the GPO setting Computer Configuration | Policies | Administrative Templates | System | Remote Assistance | Offer Remote Assistance. See Jason Samuel – How to setup Citrix Director Shadowing with Remote Assistance using Group Policy for more details.
  11. If you intend to use Citrix’s SCOM Management Packs for XenApp/XenDesktop, make sure WinRM is enabled on the VDA by running winrm quickconfig. Or you can enable WinRM using Group Policy.

Install/Upgrade Virtual Delivery Agent 7.6.9000

  1. Console – For virtual desktops, make sure you are logged into the console. The VDA won’t install if you are connected using RDP.
  2. Windows 10: VDA 7.6.9000 is not compatible with Windows 10. Instead install VDA 7.15 Update 6. Delivery Controllers must remain on 7.6.9000.
  3. 8.3 file names – Make sure 8.3 file name generation is not disabled. If so, see CTX131995 – User Cannot Launch Application in Seamless Mode to fix the AppInit_DLLs registry keys.
  4. .NET Framework – Make sure .NET Framework 4.5.2 is installed.
  5. Download – Go to the downloaded XenApp/XenDesktop 7.6.9000 and run AutoSelect.exe. Or you can use one of the standalone installers from the same download link.
  6. Click one of the XenApp or XenDesktop buttons. It doesn’t matter which one you click.
  7. Click one of the middle Virtual Delivery Agent boxes depending on which OS type you’re installing this on.
  8. In the Environment page, select Create a Master Image, and click Next. Master Image includes Profile Management, while the other option does not.
  9. For virtual desktops, in the HDX 3D Pro page, if you don’t have a GPU, select standard VDA, and click Next.
  10. In the Core Components page, if you don’t need Citrix Receiver installed on your VDA, then uncheck the box. Receiver is usually only needed for double-hop connections (connect to first VDA, and then from there, connect to second VDA). Click Next.
  11. In the Delivery Controller page, select Do it manually. Enter the FQDN of each Controller. Click Test connection. And then make sure you click Add. Click Next when done.
  12. In the Features page, click Next. 7.6.9000 VDA does not include Personal vDisk.
  13. In the Firewall page, click Next.
  14. In the Summary page, click Install.
  15. For RDSH, click Close when you are prompted to restart.
  16. After the machine reboots twice, login, and installation should continue.
  17. If you see a Locate ‘XenDesktop LTSR CU9’ installation media window, click Cancel.

    1. Mount the XenApp_and_XenDesktop_7_6_8000.iso.
    2. Run AutoSelect.exe.
    3. Click the Virtual Desktop Agent box to resume installation.
  18. Installation will continue.
  19. After installation, click Finish to restart the machine again.
  20. If 8.3 file name generation is disabled, see CTX131995 User Cannot Launch Application in Seamless Mode to fix the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Windows\AppInit_DLLs registry value.

VDA Components

VDA 7.6.9000 includes the following component versions. These components are on a different LTSR program.

Connection Quality Indicator

The Connection Quality Indicator tells the user the quality of the connection. For example:

Position of the indicator is configurable by the user. Thresholds are configurable through group policy.

Download it from CTX220774 Connection Quality Indicator and install it. The article is very detailed.

Group Policy templates are located at C:\Program Files (x86)\Citrix\Connection Quality Indicator\Configuration. Copy the files and folder to <Sysvol>\Policies\PolicyDefinitions, or C:\Windows\PolicyDefinitions.

Find the settings under Computer Config | Policies | Admin Templates | Citrix Components | Virtual Desktop Agent | CQI

Controller Registration Port

Some environments will not accept the default port 80 for Virtual Delivery Agent registration, even though registration is authenticated and encrypted on port 80. To change the port, do the following on the Virtual Delivery Agent:

  1. Open Programs and Features.
  2. Find Citrix 7.6 LTSR CU9 – Virtual Delivery Agent, and click Change.
  3. Click Customize Virtual Delivery Agent settings.
  4. Edit the Delivery Controllers, and click Next.
  5. On the Configure Delivery Controller page, change the port number, and click Next.
  6. In the Summary page, click Reconfigure.
  7. In the Finish page, click Finish. The machine automatically restarts.
  8. You must also change the VDA registration port on the Delivery Controllers by running BrokerService.exe /VDAPort.

Controller Registration – Verify

  1. If you restart the Virtual Delivery Agent machine, or restart the Citrix Desktop Service…
  2. In Windows Logs \ Application, you should see an event 1012 from Citrix Desktop Service saying that it successfully registered with a controller. If you don’t see this then you’ll need to fix the ListOfDDCs registry key.
  3. You can also run Citrix’s Health Assistant on the VDA.
  4. See CTX220772 Technical Primer: VDA Registration for a very detailed explanation of the VDA Registration process.

Citrix PDF Printer 7.11.0 for Receiver for HTML5/Chrome

  1. To allow printing from Receiver for HTML5/Chrome, install Citrix PDF Printer. Get it from the Receiver for HTML5 download page in the Additional Components section. Note: this PDF Printer is only used by Receiver for HTML5 and Receiver for Chrome.
  2. Go to the extracted CitrixPDFPrinter_7.11.0 and run CitrixPDFPrinter64.msi.
  3. In the Please read the Citrix PDF printer License Agreement page, check the box next to I accept the terms and click Install.
  4. In the Completed the Citrix PDF Universal Driver Setup Wizard page, click Finish.
  5. In Programs and Features, it is shown as version 7.11.0.11.
  6. Configure a Citrix Policy to enable the PDF printer. The setting is called Auto-create PDF Universal Printer in the user half of a Citrix Policy GPO.

Citrix File Access 2.0.3 for Receiver for Chrome

  1. If you support Receiver for Chrome (Chromebook) and want to open files on Google Drive using published applications, install Citrix File Access on the VDAs. Get it from the Receiver for Chrome download page, in the Additional Components section.
  2. Go to the extracted Citrix_File_Access_2.0.3, and run FileAccess.msi.
  3. In the Please read the File Access License Agreement page, check the box next to I accept the terms and click Install.
  4. In the Completed the File Access Setup Wizard page, click Finish.
  5. File Access is listed in Programs and Features as version 2.0.3.33.
  6. File Access has a default list of supported file extensions. The list can be expanded by editing the registry on the VDA. See CTX219983 Receiver for Chrome Error: Invalid command line arguments: Unable to open the file as it has an unsupported extension.
  7. To open a file from Google Drive, right-click and and open the file using Citrix Receiver.

Framehawk Configuration

To enable Framehawk, see https://www.carlstalhood.com/citrix-policy-settings/#framehawkconfig

Remote Desktop Licensing Configuration

On 2012 R2 RDSH, the only way to configure Remote Desktop Licensing is using group policy (local or domain). This procedure also works for 2008 R2 RDSH. This procedure is not needed on virtual desktops.

  1. For local group policy, run gpedit.msc. Alternatively, you can configure this in a domain GPO.
  2. Go to Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Licensing.
  3. Double-click Use the specified Remote Desktop license servers. Change it to Enabled and enter the names of the RDS Licensing Servers (typically installed on XenDesktop Controllers). Click OK.
  4. Double-click Set the Remote Desktop licensing mode. Change it to Enabled and select Per User. Click OK.
  5. Optionally, you can install the Remote Desktop Licensing Diagnoser Tool. In the Server Manager > Add Roles and Features Wizard, on the Features page, expand Remote Server Administration Tools, expand Role Administration Tools, expand Remote Desktop Services Tools, and select Remote Desktop Licensing Diagnoser Tool. Then Finish the wizard.
  6. In Server Manager, open the Tools menu, expand Terminal Services and click RD Licensing Diagnoser.
  7. The Diagnoser should find the license server and indicate the licensing mode. If you’re configured for Per User licenses, then it’s OK if there are no licenses installed on the Remote Desktop License Server.

Several people in Citrix Discussions reported the following issue: If you see a message about RD Licensing Grace Period has expired even though RD Licensing is properly configured, see Eric Verdumen No remote Desktop Licence Server availible on RD Session Host server 2012. The solution was to delete the REG_BINARY in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server\RCM\GracePeriod only leaving the default. You must take ownership and give admin users full control to be able to delete this value.

C: Drive Permissions

This section is more important for shared VDAs like RDSH Windows 2008 R2 and RDSH Windows 2012 R2.

The default permissions allow users to store files on the C: drive in places other than their profile.

  1. Open the Properties dialog box for C:\.
  2. On the Security tab, click Advanced.
  3. If UAC is enabled, click Change permissions.
  4. Highlight the line containing Users and Create Folders and click Remove.
  5. Highlight the line containing Users and Create files and click Remove. Click OK.
  6. Click Yes to confirm the permissions change.
  7. If you see any of these Error Applying Security windows, click Continue. This window should appear multiple times.
  8. Click OK to close the C: drive properties.

Pagefile

If this image will be converted to a Provisioning Services vDisk, then you must ensure the pagefile is smaller than the cache disk. For example, if you allocate 20 GB of RAM to your Remote Desktop Session Host, and if the cache disk is only 15 GB, then Windows will have a default pagefile size of 20 GB and Provisioning Services will be unable to move it to the cache disk. This causes Provisioning Services to cache to server instead of caching to your local cache disk (or RAM).

  1. Open System. In 2012 R2, you can right-click the Start button and click System.
  2. Click Advanced system settings.
  3. On the Advanced tab, click the top Settings button.
  4. On the Advanced tab, click Change.
  5. Uncheck the box next to Automatically manage paging file size for all drives. Then either turn off the pagefile, or set the pagefile to be smaller than the cache disk. Don’t leave it set to System managed size. Click OK several times.

Direct Access Users

When Citrix Virtual Delivery Agent is installed on a machine, non-administrators can no longer RDP to the machine. A new local group called Direct Access Users is created on each Virtual Delivery Agent. Add your non-administrator RDP users to this local group so they can RDP directly to the machine.

Windows Profiles v3/v4/v5

Roaming Profiles are compatible only between the following client and server operating system pairs. The profile version is also listed.

  • v6 = Windows 10 (1607) and Windows Server 2016
  • v5 = Windows 10 (1511 and older)
  • v4 = Windows 8.1 and Windows Server 2012 R2
  • v3 = Windows 8 and Windows Server 2012
  • v2 = Windows 7 and Windows Server 2008 R2
  • v2 = Windows Vista and Windows Server 2008

Windows 8.1 and 2012 R2 don’t properly set the profile version. To fix this, ensure update rollup 2887595 is installed. http://support.microsoft.com/kb/2890783. After you apply this update, you must create a registry key before you restart the computer.

  1. Run regedit.
  2. Locate and then tap or click the following registry subkey:
    HKEY_LOCAL_MACHINE\System\CurrentControlset\Services\ProfSvc\Parameters
  3. On the Edit menu, point to New, and then tap or click DWORD Value.
  4. Type UseProfilePathExtensionVersion.
  5. Press and hold or right-click UseProfilePathExtensionVersion, and then tap or click Modify.
  6. In the Value data box, type 1, and then tap or click OK.
  7. Exit Registry Editor.

Then, Windows 8.1 creates a user profile and appends the suffix “.v4” to the profile folder name to differentiate it from version 2 of the profile in Windows 7 and version 3 of the profile in Windows 8.

Registry

Published Explorer

From Citrix CTX128009 Explorer.exe Fails to Launch: When publishing the seamless explorer.exe application, the session initially begins to connect as expected. After the loading, the dialog box disappears, and the Explorer application fails to appear. On the VDA, use the following registry change to set the length of time a client session waits before disconnecting the session:

  • Key = HKLM\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\TWI
    • Value = LogoffCheckerStartupDelayInSeconds (DWORD) = 10 (Hexadecimal)

Screen Saver

From Citrix CTX205214 Screensaver Not Working in XenDesktop: By default, Screen Saver doesn’t work on Desktop OS. To enable it, on the VDA, configure the following registry value:

  • Key = HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Graphics
    • Value = SetDisplayRequiredMode (DWORD) = 0

Logon Disclaimer Window Size

From XenApp 7.8 – Session Launch Security/Warning Login Banner at Citrix Discussions: If your logon disclaimer window has scroll bars, set the following registry values:

  • Key = HKEY_LOCAL_MACHINE\Software\Wow6432node\Citrix\CtxHook\AppInit_DLLS\Multiple Monitor Hook
    • Value = LogonUIWidth (DWORD) = 300
    • Value = LogonUIHeight (DWORD) = 200

Login Timeout

From Citrix CTX203760 VDI Session Launches Then Disappears: XenDesktop, by default, only allows 180 seconds to complete a logon operation. The timeout can be increased by setting the following:

  • Key = HKLM\SOFTWARE\Citrix\PortICA
    • Value = AutoLogonTimeout ( DWORD) = decimal 240 or higher (up to 3600).

Also see Citrix Discussions Machines in “Registered” State, but VM closes after “Welcome” screen.

From Citrix CTX138404 Application Connection Starts but Disappears after Timeout: after loading the application, the dialog box disappears and the application fails to appear.

  •  Key = HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\TWI
    • Value =ApplicationLaunchWaitTimeoutMS (DWORD) = decimal 60000

HDX Flash

From Citrix Knowledgebase article CTX139939 – Microsoft Internet Explorer 11 – Citrix Known Issues: The registry key value IEBrowserMaximumMajorVersion is queried by the HDX Flash service to check for maximum Internet Explorer version that HDX Flash supports. For Flash Redirection to work with Internet Explorer 11 set the registry key value IEBrowserMaximumMajorVersion to 11 on the machine where HDX flash service is running. In case of XenDesktop it would be the machine where VDA is installed.

  • Key = HKLM\SOFTWARE\Wow6432Node\Citrix\HdxMediaStreamForFlash\Server\PseudoServer
    • Value = IEBrowserMaximumMajorVersion (DWORD) = 00000011 (Decimal)

From Citrix Discussions: Add the DWORD ‘FlashPlayerVersionComparisonMask=0’ on the VDA under HKLM\Software\Wow6432Node\Citrix\HdxMediaStreamForFlash\Server\PseudoServer.  This disables the Flash major version checking between the VDA and Client Device.

Mfaphook – 8.3 File Names

  1. Open a command prompt.
  2. Switch to C:\ by running cd \
  3. Run dir /x program*
  4. If you don’t see PROGRA~1 then 8.3 is disabled. This will break Citrix.
  5. If 8.3 is disabled, open regedit and go to HKLM\Software\Microsoft\Windows NT\CurrentVersion\Windows.
  6. On the right is AppInit_DLLs. Edit it and remove the path in front of MFAPHOOK64.DLL.


Receiver for HTML5/Chrome Enhanced Clipboard

From About Citrix Receiver for Chrome 1.9 at Citrix Docs: To enable enhanced clipboard support, set registry value HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\Virtual Clipboard\Additional Formats\HTML Format\Name=”HTML Format”. Create any missing registry keys. This applies to both virtual desktops and Remote Desktop Session Hosts.

Receiver for HTML5/Chrome Upload Folder

The Receiver for HTML5 (or Chrome) lets upload files.

By default, the user is prompted to select a upload location. If you use the Upload feature multiple times, the last selected folder is not remembered.

Citrix CTX217351 How to Customize File Upload and Download Using Receiver for HTML5 and Receiver for Chrome. You can specify a default uploads location by editing HKLM\Software\Citrix\FileTransfer\UploadFolderLocation on the VDA. Environment variables are supported. When this value is configured, users are no longer prompted to select an upload location. The change takes effect at next logon.

Note: HTML5/Chrome Receiver also adds a Save to My Device location to facilitate downloads.

4K Monitors

Citrix CTX201696 – Citrix XenDesktop and XenApp – Support for Monitors Including 4K Resolution and Multi-monitors: Up to eight 4K monitors are supported with the Std-VDA and RDS VDA irrespective of underlying GPU support, provided the required policies and/or registry keys are correctly configured. Currently the Std-VDA for XenDesktop and RDS-VDA for XenApp does not support resolutions higher than 4094 in any dimension.

Framehawk currently does not support 4K monitors. At the time of writing, the number of monitors supported is 1, the use of more monitors will cause the graphics mode to change from Framehawk to Thinwire to support multi-monitor.  The maximum resolution supported by Framehawk is currently 2048×2048.

From CTX200257 – Screen Issues Connecting to 4K Resolution Monitors: Symptom: A blank or corrupt screen is displayed when connecting to Windows 7 or 8.1 Standard XenDesktop Virtual Delivery Agents on a client which has one or more 4K resolution monitors.

  1. Calculate the video memory that is required for 4K monitor using the following formula:
    Sum of total monitors (Width * height * 4 * X) where width and height are resolution of the monitor.
    X = 2 if VDA is Windows 7 OR X = 3 if VDA is Windows 8\8.1
    Suppose a Windows 7 VDA is connecting to a client that has dual 4K monitors (3840×2160), then video buffer should be: (3840 x 2160 x 4 x 2) + (3840 x 2160 x 4 x 2) = ~132MB
  2. CTX115637 Citrix Session Graphics Memory Reference describes how multi-monitor resolution is determined.
  3. Open the registry (regedit) and navigate to: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\vd3v
  4. Increase the value of “MaxVideoMemoryBytes” REG_DWORD value to the above calculated memory.
  5. Reboot the VDA.

Citrix Policies also control graphics performance.

Legacy Client Drive Mapping

Citrix CTX127968 How to Enable Legacy Client Drive Mapping Format on XenApp: Citrix Client Drive Mapping no longer uses drive letters and instead they appear as local disks. This is similar to RDP drive mapping.

The old drive letter method can be enabled by setting the registry value:

  • Key = HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\UncLinks (create the key)
    • Value = UNCEnabled (DWORD) = 0

When you reconnect, the client drives will be mapped as drive letters (starts with V: and goes backwards).

COM/LPT Port Redirection

To signal Citrix’ intention to deprecate COM and LPT support in a future major release, policy settings for COM Port and LPT Port Redirection have moved from Studio to the registry, and are now located under HKLM\Software\Citrix\GroupPolicy\Defaults\Deprecated on either your Master VDA image or your physical VDA machines. The registry values are detailed in Citrix Docs.

Print Driver for Non-Windows Clients

This section applies to Windows 2012 R2, Windows 8.1, and Windows 10 VDAs.

From Mac Client Printer Mapping Fix for Windows 8/8.1 and Windows Server 2012/2012R2. By default, Non-Windows clients cannot map printers due to a missing print driver on the VDA machine.

  1. Requirements:
    • Internet Access
    • Windows Update service enabled
  2. Click Start and run Devices and Printers.
  3. In the Printers section, highlight a local printer (e.g. Microsoft XPS Document Writer). Then in the toolbar click Print server properties.
  4. Switch to the Drivers tab. Click Change Driver Settings.
  5. Then click Add.
  6. In the Welcome to the Add Printer Driver Wizard page, click Next.
  7. In the Processor Selection page, click Next.
  8. In the Printer Driver Selection page, click Windows Update. The driver we need won’t be in the list until you click this button. Internet access is required.
  9. Once Windows Update is complete, highlight HP on the left and then select HP Color LaserJet 2800 Series PS (Microsoft) on the right. Click Next.
  10. In the Completing the Add Printer Driver Wizard page, click Finish.
  11. Repeat these instructions to install the following additional drivers:
    • HP LaserJet Series II
    • HP Color LaserJet 4500 PCL 5

SSL for VDA

If you intend to use HTML5 Receiver internally, install certificates on the VDAs so the WebSockets (and ICA) connection will be encrypted. Internal HTML5 Receivers will not accept clear text WebSockets. External users don’t have this problem since they are SSL-proxied through NetScaler Gateway. Notes:

  • Each Virtual Delivery Agent needs a machine certificate that matches the machine name. This is feasible for a small number of persistent VDAs. For non-persistent VDAs, you’ll need some automatic means for creating machine certificates every time they reboot.
  • As detailed in the following procedure, use PowerShell on the Controller to enable SSL for the Delivery Group. This forces SSL for every VDA in the Delivery Group, which means every VDA in the Delivery Group must have SSL certificates installed.

The Citrix blog post How To Secure ICA Connections in XenApp and XenDesktop 7.6 using SSL has a method for automatically provisioning certificates for pooled virtual desktops by enabling certificate auto-enrollment and setting up a task that runs after the certificate has been enrolled. Unfortunately this does not work for Remote Desktop Session Host.

The following instructions can be found at Configure SSL on a VDA using the PowerShell script at Citrix Docs.

  1. On the VDA machine, run mmc.exe.
  2. Add the Certificates snap-in.
  3. Point it to Local Computer.
  4. Request a certificate from your internal Certificate Authority. You can use either the Computer template or the Web Server template.

    You can also use group policy to enable Certificate Auto-Enrollment for the VDA computers.
  5. Browse to the XenApp/XenDesktop 7.6.9000 ISO. In the \Support\Tools\SslSupport folder, shift+right-click the Enable-VdaSSL.ps1 script and click Copy as path.
  6. Run PowerShell as administrator (elevated).
  7. Run the command Set-ExecutionPolicy unrestricted. Enter Y to approve.
  8. In the PowerShell prompt, type in an ampersand (&), and a space.
  9. Right-click the PowerShell prompt to paste in the path copied earlier.
  10. At the end of the path, type in -Enable
  11. If there’s only one certificate on this machine, press Enter.
  12. If there are multiple certificates, you’ll need to specify the thumbprint of the certificate you want to use. Open the Certificates snap-in, open the properties of the machine certificate you want to use, and copy the Thumbprint from the Details tab.

    In the PowerShell prompt, at the end of the command, enter ‑CertificateThumbPrint, add a space, and type quotes (").
    Right-click the PowerShell prompt to paste the thumbprint.
    Type quotes (") at the end of the thumbprint. Then remove all spaces from the thumbprint. The thumbprint needs to be wrapped in quotes.
  13. If this VDA machine has a different service already listening on 443 (e.g. IIS), then the VDA needs to use a different port for SSL connections. At the end of the command in the PowerShell prompt, enter -SSLPort 444 or any other unused port.
  14. Press <Enter> to run the Enable-VdaSSL.ps1 script.
  15. Press <Y> twice to configure the ACLs and Firewall.
  16. You might have to reboot before the settings take effect.
  17. Login to a Controller and run PowerShell as Administrator (elevated).
  18. Run the command asnp Citrix.*
  19. Enter the command: 
    Get-BrokerAccessPolicyRule -DesktopGroupName '<delivery-group-name>' | Set-BrokerAccessPolicyRule ‑HdxSslEnabled $true

    where <delivery-group-name> is the name of the Delivery Group containing the VDAs.

  20. You can run Get-BrokerAccessPolicyRule -DesktopGroupName '<delivery-group-name>' to verify that HDX SSL is enabled.
  21. Also run the following command: 
    Set-BrokerSite –DnsResolutionEnabled $true

You should now be able to connect to the VDA using the HTML5 Receiver from internal machines.

Anonymous Accounts

If you intend to publish apps anonymously then follow this section.

  1. Anonymous accounts are created locally on the VDAs. When XenDesktop creates Anon accounts it gives them an idle time as specified at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\AnonymousUserIdleTime. The default is 10 minutes. Adjust as desired.
  2. You can pre-create the Anon accounts on the VDA by running “C:\Program Files\Citrix\ICAConfigTool\CreateAnonymousUsersApp.exe”. If you don’t run this tool then Virtual Delivery Agent will create them automatically when users log in.
  3. You can see the local Anon accounts by opening Computer Management, expanding System Tools, expand Local Users and Groups and clicking Users.
  4. If you open one of the accounts, on the Sessions tab, notice that idle timeout defaults to 10 minutes. Feel free to change it.

Group Policy for Anonymous Users

Since Anonymous users are local accounts on each Virtual Delivery Agent, domain-based GPOs will not apply. To work around this limitation, you’ll need to edit the local group policy on each Virtual Delivery Agent.

  1. On the Virtual Delivery Agent, run mmc.exe.
  2. Open the File menu and click Add/Remove Snap-in.
  3. Highlight Group Policy Object Editor and click Add to move it to the right.
  4. In the Welcome to the Group Policy Wizard page, click Browse.
  5. On the Users tab, select Non-Administrators.
  6. Click Finish.
  7. Now you can configure group policy to lockdown sessions for anonymous users. Since this is a local group policy, you’ll need to repeat the group policy configuration on every Virtual Delivery Agent image. Also, Group Policy Preferences is not available in local group policy.

Antivirus

Install antivirus using your normal procedure. Instructions vary for each Antivirus product.

Microsoft’s virus scanning recommendations (e.g. exclude group policy files) – http://support.microsoft.com/kb/822158.

Citrix’s Recommended Antivirus Exclusions

Citrix Blog Post Citrix Recommended Antivirus Exclusions: the goal here is to provide you with a consolidated list of recommended antivirus exclusions for your Citrix virtualization environment focused on the key processes, folders, and files that we have seen cause issues in the field:

  • Set real-time scanning to scan local drives only and not network drives
  • Disable scan on boot
  • Remove any unnecessary antivirus related entries from the Run key
  • Exclude the pagefile(s) from being scanned
  • Exclude Windows event logs from being scanned
  • Exclude IIS log files from being scanned

See the Blog Post for exclusions for each Citrix component/product including: StoreFront, VDA, Controller, and Provisioning Services. The Blog Post also has links to additional KB articles on antivirus.

Symantec

Symantec links:

Trend Micro

Citrix CTX136680 – Slow Server Performance After Trend Micro Installation. Citrix session hosts experience slow response and performance more noticeable while users try to log in to the servers. At some point the performance of the servers is affected, resulting in issues with users logging on and requiring the server to be restarted. This issue is more noticeable on mid to large session host infrastructures.

Trend Micro has provided a registry fix for this type of issue. Create the following registry on all the affected servers. Add new DWORD Value as:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TmFilter\Parameters] “DisableCtProcCheck”=dword:00000001

Trend Micro Links:

Sophos

Best Practice for running Sophos on virtual systems: we’ve amassed the following practical information about how you can optimize our software to work with this technology.

Sophos Anti-Virus for Windows XP+: Installation and configuration considerations for Sophos Anti-Virus on a Remote Desktop Services server: It maybe desirable to disable the Sophos AutoUpdate shield icon

Sophos Anti-Virus for Windows 2000+: incorporating current versions in a disk image, including for use with cloned virtual machines: This procedure will make sure that the produced target/cloned computers:

  • Get their distinct identity with Enterprise Console, under which they can be subsequently managed.
  • Have the desired version of Sophos Anti-Virus already installed and configured on the created image.

Optimize Performance

VDA Optimizer

Installation of the VDA might have already done this but there’s no harm in doing it again. This tool is only available if you installed VDA in Master Image mode.

  1. On the master VDA, go to C:\Program Files\Citrix\PvsVm\TargetOSOptimizer and run TargetOSOptimizer.exe.
  2. Then click OK. Notice that it disables Windows Update.
  3. See CTX125874 How to Optimize XenDesktop Machines for the list of registry values changed by the TargetOSOptimizer tool. You can use Group Policy Preferences to set these values.  💡

Windows 10 / Windows 2012 R2 / Windows 2016 and newer

Optimization Notes:

  • If this machine is provisioned using Provisioning Services, do not disable the Shadow Copy services.
  • Windows 8 detects VDI and automatically disables SuperFetch. No need to disable it yourself.
  • Windows 8 automatically disables RSS and TaskOffload if not supported by the NIC.

RDSH 2008 R2

Citrix CTX131577 XenApp 6.x (Windows 2008 R2) – Optimization Guide is a document with several registry modifications that are supposed to improve server performance. Ignore the XenApp 6 content and instead focus on the Windows content.

Citrix CTX131995 User Cannot Launch Application in Seamless Mode in a Provisioning Services Server when XenApp Optimization Best Practices are Applied. Do not enable NtfsDisable8dot3NameCreation

Citrix CTX213540 Unable To View Printers In Devices And Printers Win 2012 R2 – don’t disable Device Setup Manager Service

Norskale has Windows 2008 R2 Remote Desktop and XenApp 6 Tuning Tips Update.

Windows 7

Microsoft has compiled a list of links to various optimization guides.

It’s a common practice to optimize a Windows 7 virtual machine (VM) template (or image) specifically for VDI use. Usually such customizations include the following.

  • Minimize the footprint, e.g. disable some features and services that are not required when the OS is used in “stateless” or “non-persistent” fashion. This is especially true for disk-intensive workloads since disk I/O is a common bottleneck for VDI deployment. (Especially if there are multiple VMs with the same I/O patterns that are timely aligned).
  • Lock down user interface (e.g. optimize for specific task workers).

With that said the certain practices are quite debatable and vary between actual real-world deployments. Exact choices whether to disable this or that particular component depend on customer requirements and VDI usage patterns. E.g. in personalized virtual desktop scenario there’s much less things to disable since the machine is not completely “stateless”. Some customers rely heavily on particular UI functions and other can relatively easily trade them off for the sake of performance or standardization (thus enhance supportability and potentially security). This is one of the primary reasons why Microsoft doesn’t publish any “VDI Tuning” guide officially.

Though there are a number of such papers and even tools published either by the community or third parties. This Wiki page is aimed to serve as a consolidated and comprehensive list of such resources.

Daniel Ruiz XenDesktop Windows 7 Optimization and GPO’s Settings –

Microsoft Whitepaper Performance Optimization Guidelines for Windows 7 Desktop Virtualization

Seal and Shut Down

If this session host will be a master image in a Machine Creation Services or Provisioning Services catalog, after the master is fully prepared (including applications), do the following:

  1. Go to the properties of the C: drive and run Disk Cleanup.
  2. On the Tools tab, click Optimize to defrag the drive.
    `
  3. Run slmgr.vbs /dlv and make sure it is licensed with KMS and has at least one rearm remaining. It is no longer necessary to manually rearm licensing. XenDesktop will do it automatically.
  4. Run Delprof2 to clean up local profiles. Get it from http://helgeklein.com/download/.
  5. Machine Creation Services and Provisioning Services require DHCP.
  6. Session hosts commonly have DHCP reservations.
  7. Base Image Script Framework (BIS-F) automates many image sealing tasks. The script is configurable using Group Policy.  💡
  9. Shut down the master image. You can now use Studio or Provisioning Services to create a catalog of linked clones.

Troubleshooting – Graphics

If Windows 7 on vSphere, don’t install the VMware SVGA driver. For more details, see CTX201804 Intermittent Connection Failures/Black Screen Issues When Connecting from Multi-Monitor Client Machines to Windows 7 VDA with VDA 7.x on vSphere/ESXi.

For Citrix Policies that control graphics codecs, see https://www.carlstalhood.com/citrix-policy-settings/#graphics

From Citrix Knowledgebase article CTX200257 – Screen Issues Connecting to 4K Resolution Monitors in DCR Mode:

  1. Calculate the video memory that is required for 4K monitor using the following formula:
    Sum of total monitors (Width * height * 4 * X) where width and height are resolution of the monitor.
    X = 2 if VDA is Windows 7 OR X = 3 if VDA is Windows 8\8.1\10
    Example: Suppose a Windows 7 VDA is connecting to a client that has dual 4K monitors (3840×2160), then video buffer should be: (3840×160 x 4 x 2) + (3840 x 2160 x 4 x 2) = ~115MB
  2. CTX115637 Citrix Session Graphics Memory Reference describes how multi-monitor resolution is determined.
  3. Open the registry (regedit) and navigate to:
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\vd3v
  4. Increase the value of “MaxVideoMemoryBytes” REG_DWORD value to the above calculated memory.
  5. Reboot the VDA

From Citrix Discussions: To exclude applications from Citrix 3D rendering, create a REG_DWORD registry value “app.exe” with value 0 or a registry value “*” with value 0.

  • XD 7.1 and XD 7.5:
    • x86: reg add hklm\software\citrix\vd3d\compatibility /v * /t REG_DWORD /f /d 0
    • x64: reg add hklm\software\Wow6432Node\citrix\vd3d\compatibility /v * /t REG_DWORD /f /d 0
  • XD 7.6 both x86 and x64:
    • reg add hklm\software\citrix\vd3d\compatibility /v * /t REG_DWORD /f /d 0

Wildcards are not supported. The asterisk * here has a special meaning “all apps” but is not a traditional wildcard. To blacklist multiple apps e.g. both appa.exe and appb.exe must be done by creating a registry value for each app individually.

This is most problematic in Remote PC since most physical PCs have GPUs. I recently had to blacklist Internet Explorer to prevent lockup issues when switching back to physical.

Uninstall VDA

Uninstall the VDA from Programs and Features.

Then see CTX209255 VDA Cleanup Utility.

To run the VDA Cleanup Tool silently:

  1. Execute VDACleanupUtility.exe /silent /noreboot to suppress reboot.
  2. Once the VDACleanupUtility has finished executing, setup Auto logon for the current user.
  3. Reboot.
  4. After reboot, tool will launch automatically to continue Cleanup.

Another option is to delete CitrixVdaCleanup value under HKLM\Software\Microsoft\Windows\CurrentVersion\RunOnce. Then after reboot, run VDACleanupUtility.exe /silent /reboot to indicate that it’s running after the reboot.

Related Pages

Delivery Controller 7.6.9000 / LTSR CU9

Last Modified: Nov 20, 2020 @ 8:10 am

45 Comments

Navigation

💡 = Recently Updated

Change Log

Preparation

Citrix Licensing – If you are going to use an existing Citrix Licensing Server, upgrade it to 11.15.0.0 build 27000.

 SQL Databases

  • Citrix CTX209080 Database Sizing Tool for XenDesktop 7
  • Citrix article CTX114501 – Supported Databases for Citrix Products
  • XenApp and Desktop typically connect to three databases: one for the Site (aka farm), one for Logging (audit log) and one for Monitoring (Director).
    • The monitoring database name must not have any spaces in it. See CTX200325 Database Naming Limitation when Citrix Director Accesses Monitoring Data Using OData APIs
    • If you want Citrix Studio to create the SQL databases automatically, then the person running Studio must be a sysadmin on the SQL instances. No lesser role will work.
    • As an alternative, you can use Citrix Studio to create SQL scripts and then run those scripts on the SQL server. In that case you only need the dbcreator and securityadmin roles.
    • It is possible to create the databases in advance. However, you must use the non-default Latin1_General_100_CI_AS_KS collation. Then use Citrix Studio to configure the database tables.
  • Citrix recommends SQL Mirroring because it has the fastest failover.
    • SQL Mirroring requires two SQL Standard Edition servers and one SQL Express for the witness server.
    • You can setup SQL Mirroring either before installing XenDesktop or after installing XenDesktop. If after, then see Citrix CTX140319 to manually change XenDesktop’s database connection strings How to Migrate XenDesktop Database to New SQL Server.
    • To setup SQL Mirroring, see Rob Cartwright: Configure SQL Mirroring For Use With XenDesktop, XenApp, and PVS Databases.
    • If you try to stretch the mirror across datacenters, the SQL witness must be placed in a third datacenter that has connectivity to the other two datacenters. However, stretching a single XenApp/XenDesktop site/farm and corresponding SQL mirror across datacenters is not recommended.
  • AlwaysOn Availability Groups and SQL Clustering are also supported. However, these features require the much more expensive SQL Enterprise Edition.

 Windows Features

  • Installing Group Policy Management on the Delivery Controller lets you edit GPOs and have access to the Citrix Policies node in the GPO Editor. Or you can install Studio on a different machine that has GPMC installed.
  • vSphere Web Client – if you will connect to vSphere Web Client from the Controller machine, Flash Player is only available for IE if you install the Desktop Experience feature. Or you can use Google Chrome.

 vSphere

Delivery Controller – Upgrade to 7.6.9000

  1. Media – The latest update for 7.6 is 7.6 LTSR Cumulative Update 9, which is also known as 7.6.9000. You can do a fresh, full install of 7.6.9000 or you can upgrade 7.6.x to 7.6.9000. Download LTSR CU9 (7.6.9000).
  2. LTSR compliance – To remain compliant with LTSR (5 years of support), you must install the exact versions detailed at Cumulative Update 9 (CU9) at Citrix Docs. If you upgrade a single component beyond LTSR, then you must upgrade all components to the latest release. Citrix LTSR Assistant can determine your LTSR compliance.
    • LTSR Assistant downloads its configuration from ctxsym.citrix.com, so you don’t have to update LTSR Assistant after installing a new Cumulative Update.
  3. SQL Permissions – During the upgrade of Delivery Controller, you will be prompted to upgrade the database. Ask a DBA to grant your AD account (the account doing the upgrade) temporary sysadmin Server Role on the SQL Server. If the DBA is unwilling, then immediately after the upgrade, use Citrix Studio to generate SQL scripts, and ask the DBA to run those SQL scripts.
  4. Other Users – Use Task Manager > Users tab to logoff any other user currently logged into the machine.
  5. On one of your existing Controllers, run AutoSelect.exe from the XenApp and XenDesktop 7.6 LTSR CU9 (7.6.9000) media.
  6. On the top left, click Studio and Server Components to begin the upgrade.
  7. In the Software License Agreement page, select I have read, understand, and accept the terms, and click Next.
  8. In the Ensure a Successful Upgrade page, check the box next to I’m ready to continue, and click Next.
  9. In the Firewall page, click Next.
  10. In the Summary page, click Upgrade.
  11. In the Finish page, check the box to Launch Studio, and click Finish.
  12. When Studio launches, you will be prompted to upgrade the database. If you have sysadmin permissions on SQL, then you can click Start the automatic Site upgrade. If you don’t have sysadmin permissions, then you need to click Manually upgrade this site, generate SQL scripts, and get a DBA to run the SQL scripts.
  13. Once the database is upgraded, you can then upgrade the remaining Delivery Controllers.

Other XenApp/XenDesktop components can also be in-place upgraded:

Delivery Controller 7.6.9000  – New Install

  1. Sizing – A typical size for the Controller VMs is 2-4 vCPU and 8 GB of RAM.
  2. Media – The latest update for 7.6 is LTSR Cumulative Update 9, which is also known as 7.6.9000. You can perform a fresh, full install of 7.6.9000, or you can upgrade 7.6.x to 7.6.9000. Download 7.6 LTSR CU9 (7.6.9000).
  3. LTSR compliance – To remain compliant with LTSR (5 years of support), you must install the exact versions detailed at Cumulative Update 9 (CU9) at Citrix Docs. If you upgrade a single component beyond LTSR, then you must upgrade all components to the latest release. Citrix LTSR Assistant can determine your LTSR compliance.
    • LTSR Assistant downloads its configuration from ctxsym.citrix.com, so you don’t have to update LTSR Assistant after installing a new Cumulative Update.
  4. On two Controllers, install the Delivery Controller software from the XenApp/XenDesktop 7.6 LTSR CU9 media. Go to the downloaded XenDesktop 7.6.9000 ISO, and run AutoSelect.exe.
  5. Click Start next to either XenApp or XenDesktop. The only difference is the product name displayed in the installation wizard.
  6. On the top left, click Delivery Controller.
  7. In the License Agreement page, select I have read, understand, and accept the terms, and click Next.
  8. In the Core Components page, you can leave everything checked to install all components on one server. Or you can install different components on different servers. StoreFront, Director, and Licensing are typically installed on separate servers so they can more easily support multiple sites/farms.
  9. In the Features page, uncheck the box next to Install Microsoft SQL Server 2012 SP3 Express, and click Next.
  10. In the Firewall page, click Next.
  11. In the Summary page, click Install.
  12. In the Finish page, click Finish. Studio will automatically launch.
  13. Ensure the two Controller VMs do not run on the same hypervisor host. Create an anti-affinity rule.

Create Site – Create Databases

There are several methods of creating the databases for XenApp/XenDesktop:

  • If you have sysadmin permissions to Microsoft SQL, let Citrix Studio create the databases automatically.
  • If you don’t have sysadmin permissions to Microsoft SQL, then do one of the following:
    • Use Citrix Studio to generate SQL scripts and send them to a DBA.
    • Use PowerShell to generate SQL scripts and send them to a DBA.

Database Mirroring

If you are not using database mirroring then skip to the next section.

You can setup SQL Mirroring either before configuring XenDesktop or after configuring XenDesktop.

  • If before, then the empty databases (Site, Logging, Monitoring) must use the Latin1_General_100_CI_AS_KS collation, which is not the default.
  • If SQL Mirroring is already setup then XenDesktop will detect it and set the database connection strings accordingly. Or you can manually change the database connection strings later as detailed at Citrix CTX140319 How to Migrate XenDesktop Database to New SQL Server.
  • If you use Citrix Studio to create SQL scripts that populate the databases, then there will be separate SQL scripts for the Primary and Partner.

To verify mirroring after the XenDesktop configuration has completed, run the PowerShell cmdlet get-configdbconnection and ensure that the Failover Partner has been set in the connection string to the mirror.

Use PowerShell to Create SQL Scripts

From Sinisa Sokolic XenDesktop 7.x DB creation with locked SQL Servers: Citrix Studio 7.6 only creates one SQL Script at a time. In a typical two-Controller configuration, that means you need 4 SQL scripts: one for each Controller, one for Monitoring, and one for Logging. That’s four round trips between you and the DBA. You can instead use PowerShell Commands to generate three of the SQL scripts now rather that doing one at a time:

Get-XDDatabaseSchema -SiteName SITENAME -DataStore Site -DatabaseName DBNAME -DatabaseServer DBSERVERNAME -ScriptType FullDatabase > c:\prep\dev_create_site_script.sql

Get-XDDatabaseSchema -SiteName SITENAME -DataStore Logging -DatabaseName DBNAME -DatabaseServer DBSERVERNAME -ScriptType FullDatabase > c:\prep\dev_create_logging_script.sql

Get-XDDatabaseSchema -SiteName SITENAME -DataStore Monitor -DatabaseName DBNAME -DatabaseServer DBSERVERNAME -ScriptType FullDatabase > c:\prep\dev_create_monitor_script.sql

Use Studio to Create the Database

Or use Citrix Studio to create the SQL Scripts:

  1. Launch Citrix Studio. After it loads, click Deliver applications and desktops to your users.
  2. In the Introduction page, select An empty, unconfigured site. This reduces the number of pages in the Setup wizard. The other Setup Wizard pages will be configured later.
  3. Enter a Site Name (aka farm name) and click Next. Only administrators see the farm name.
  4. In the Database page, enter the name of the SQL server where the database will be created. Enter a name for the new Database. No spaces in the database name.
  5. If the person running Studio is a sysadmin on the SQL server then you can click Test Connection and click Yes when asked to automatically create the database.
  6. If you are not a sysadmin, then click Generate database script.
  7. A folder will open with two scripts. The top script needs to be sent to a DBA.
  8. On the Principal SQL Server, open the query file (Script_For_Database…sql).

  9. At the top of the script, is a commented line that creates the database. Either uncomment it or copy it to a second query window and execute it. Or in the case of mirroring, the database is already created so there’s no need to create the database again.
  10. Open the Query menu and click SQLCMD Mode.
  11. Then execute the rest of the script.
  12. If SQLCMD mode was enabled properly then the output should look something like this:
  13. If you have a mirrored database, run the second script on the mirror SQL instance. Make sure SQLCMD mode is enabled.
  14. The person running Citrix Studio must be added to the SQL Server as a SQL Login, and granted the public server role.

  15. Back in Citrix Studio, click the Test connection button.
  16. Click Close once the tests have passed. Then click Next.
  17. On the Licensing page, enter the name of the Citrix License Server, and click Connect.
  18. If the Certificate Authentication appears, select Connect me, and click Confirm.
  19. Then select your license, and click Next.
  20. In the Summary page, make your selection for Customer Experience Improvement Program, and click Finish.

Verify Database Mirroring

If your database is mirrored, when you run get-brokerdbconnection, you’ll see the Failover Partner in the database connection string.

Second Controller

There are several methods of adding a second Controller to the databases for XenApp/XenDesktop:

  • If you have sysadmin permissions to SQL, let Citrix Studio modify the databases automatically.
  • If you don’t have sysadmin permissions to SQL then do one of the following:
    • Use Citrix Studio to generate SQL scripts and send them to a DBA.
    • Use PowerShell to generate SQL scripts and send them to a DBA.

From Sinisa Sokolic XenDesktop 7.x DB creation with locked SQL Servers: The PowerShell Commands to generate the SQL scripts that add a Controller to the databases are shown below:

Get-XDDatabaseSchema -AdminAddress CONTROLLERNAME-SiteName SITENAME -DataStore Site -DatabaseName DBNAME-DatabaseServer DBSERVERNAME -ScriptType AddController > C:\prep\dev_add_controller_site_script.sql

Get-XDDatabaseSchema -AdminAddress CONTROLLERNAME-SiteName SITENAME -DataStore Logging -DatabaseName DBNAME-DatabaseServer DBSERVERNAME -ScriptType AddController > C:\prep\dev_add_controller_logging_script.sql

Get-XDDatabaseSchema -AdminAddress CONTROLLERNAME-SiteName SITENAME -DataStore Monitor -DatabaseName DBNAME-DatabaseServer DBSERVERNAME -ScriptType AddController > C:\prep\dev_add_controller_monitor_script.sql

Or use Citrix Studio to create the SQL Scripts:

  1. On the first Delivery Controller, if desired, delete the default StoreFront store (/Citrix/Store) and recreate it with your desired Store name (e.g. /Citrix/CompanyStore).
  2. On the second Delivery Controller, install XenDesktop as detailed earlier.
  3. After running Studio, click Connect this Delivery Controller to an existing Site.
  4. Enter the name of the first Delivery Controller, and click OK.
  5. If you don’t have elevated SQL permissions, click No when asked if you want to update the database automatically.
  6. Click Generate scripts.
  7. A folder will open with two scripts. The top script needs to be sent to a DBA.
  8. On the SQL Server, open the query (Script_For_Database…sql).

  9. Open the Query menu, and click SQLCMD Mode.
  10. Then execute the XenDesktop script.
  11. If SQLCMD mode was enabled properly then the output should look something like this:
  12. Back in Citrix Studio, click OK.
  13. In the Studio, under Configuration > Controllers, you should see both controllers.
  14. You can also test the site again if desired.

Other LTSR CU9 Updates

The components installed on the 7.6.9000 Delivery Controllers should already be at their .9000 versions.

Studio

If Citrix Studio 7.6.x is installed on separate machines, upgrade it to 7.6.9000. You can run the installer from the 7.6.9000 ISO’s AutoSelect.exe program, and then click Studio and Server Components.

StoreFront

If StoreFront 3.0.x is installed on separate servers, upgrade it to 3.0.9000. You can run the installer from the 7.6.9000 ISO’s AutoSelect.exe program, or from the 7.6.9000 ISO under \x64\StoreFront.


Director

If Director 7.6.x is installed on separate servers, upgrade it to 7.6.9000. You can run the installer from the 7.6.9000 ISO’s AutoSelect.exe program, or from the 7.6.9000 ISO under \x64\DesktopDirector.


After upgrading Director, run the following command from an elevated command prompt:

C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /upgrade

Also upgrade Citrix Group Policy Management on the Director server to 2.5.9000 (aka 7.6.9000). Find CitrixGroupPolicyManagement_x64.msi on the 7.6.9000 ISO under \x64\Citrix Policy

Other Components

Other upgradeable components on the 7.6.9000 ISO include:

  • Virtual Delivery Agent 7.6.9000 – Upgrade this on all master images and all persistent machines.
  • Citrix Group Policy Management 2.5.9000 – Upgrade this on any Microsoft Group Policy Management machine that is used to manage Citrix Policies in Microsoft GPOs.
  • Universal Print Server 7.6.9000 – Upgrade this on any Print Server that has Citrix Universal Print Server installed.
  • Citrix License Server 11.15.0.0 build 27000

Platinum Components

Other upgradeable components on separate ISOs include the following. Download them from XenDesktop 7.6 LTSR Cumulative Update 7 – Platinum Edition.

  • Citrix Provisioning Services 7.6.10
  • Citrix Session Recording 7.6.9000

There is no longer an LTSR version of Citrix AppDNA, so you can upgrade the latest version Citrix AppDNA 1906.

 

Receiver 4.9.7000 qualify for a different LTSR program. See Citrix Docs for the minimum Receiver versions.

 

For Windows 10 VDAs, VDA 7.9 is “compatible” with LTSR, but VDA 7.9 doesn’t receive LTSR benefits (5 years of support). See Citrix Blog Post Adding Windows 10 Compatibility to XenApp and XenDesktop 7.6 LTSR. If you need Windows 10 support, you should be installing VDA 7.15.1000, or whatever the latest version is.

Studio – Slow Launch

From B.J.M. Groenhout at Citrix Discussions: The following adjustments can be made if Desktop Studio (and other Citrix management Consoles) will start slowly:

  • Within Internet Explorer, go to Tools – Internet Options – Tab Advanced – Section Security and uncheck the option Check for publisher’s certificate revocation

After adjustment Desktop Studio (MMC) will be started immediately. Without adjustment it may take some time before Desktop Studio (MMC) is started.

Registry setting (can be deployed using Group Policy Preferences):

  • HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\WinTrust\Trust Providers\Software Publishing
    • “State“=dword:00023e00

Database Maintenance

Split the Databases

Once the site is configured, split the Monitoring and Log data into separate databases.

  1. In Citrix Studio, on the left click the Configuration node.
  2. In the middle, click the Monitoring datastore to highlight it. On the right, click Change Database.
  3. Repeat for the Logging datastore.

 View Logging Database

To view the contents of the Logging Database, in Studio, click the Logging node. On the right is Create Custom Report. See Citrix article CTX138132 Viewing Configuration Logging Data Not Shown for more info.

 Enable Read-Committed Snapshot

The XenDesktop Database can become heavily utilized under load in a large environment. Therefore Citrix recommends enabling the Read_Committed_Snapshot option on the XenDesktop databases to remove contention on the database from read queries. This can improve the interactivity of Studio and Director. It should be noted that this option may increase the load on the tempdb files. See Citrix article CTX137161 How to Enable Read-Committed Snapshot in XenDesktop for configuration instructions.

 Change Database Connection Strings

Sometimes the database connection strings need to be modified:

  • When moving the SQL databases to a different SQL server
  • When enabling mirroring after the databases have already been configured in Studio.

From Citrix Docs Update database connection strings when using SQL Server high availability solutions: Citrix offers several PowerShell scripts that update XenApp and XenDesktop database connection strings when you are using SQL Server high availability database solutions such as AlwaysOn and mirroring. The scripts, which use the XenApp and XenDesktop PowerShell API, are:

  • DBConnectionStringFuncs.ps1: The core script that does the actual work. This script contains common functions that the other scripts use.
  • Change_XD_Failover_Partner_v1.ps1: Updates (adds, changes, or removes) the failover partner. This script prompts for the failover partner location (FQDN) for each database. (Providing a blank failover partner removes the failover partner. You can also use the ClearPartner option to remove a partner.) Do not set the failover partner to the same location as the principal database server.
  • Change_XD_To_ConnectionString.ps1: Uses the provided connection strings to update the connection strings to the databases. This script ensures that certain Citrix services are up and running, and then updates those services in the correct order on all Controllers in the site. Enclose connection string information for each database in quotes.
  • Change_XD_To_MultiSubnetFailover.ps1: Toggles the addition and removal of MultiSubnetFailover=true. If you use AlwaysOn Availability Groups, Microsoft recommends that the connection string include MultiSubnetFailover=true. This option speeds up recovery when a high availability event occurs, and is recommended for both single and multi-subnet environments. Run this script once to add the option. Run the script again to remove it.
  • Change_XD_To_Null.ps1: Resets all the connection strings on the localhost because something has gone wrong. By resetting the connection strings to null, this script places the Controller into an “initial” state. If you run Studio after running this script, you’ll be asked if you want to create a site or join an existing site. This is useful if something has gone wrong and a reset is needed. After the reset, you can try again to set the connection strings.

Director Grooming

If XenDesktop is not Platinum Edition then all historical Director data is groomed at 7 days.

For XenDesktop/XenApp Platinum Edition, by default, most of the historical Director data is groomed at 90 days. This can be adjusted up to 367 days by running a PowerShell applet.

  1. On a Delivery Controller, run PowerShell and run asnp Citrix.*

  2. Run Get-MonitorConfiguration to see the current grooming settings.
  3. Run Set-MonitorConfiguration to change the grooming settings.

Studio Administrators

Full Administrators

  1. In the Studio, under Configuration, click the Administrators node. The first time you access the node you’ll see a Welcome page. Feel free to check the box and then click Close.
  2. On the Administrators tab, right-click, and click Create Administrator.
  3. In the Administrator and Scope page, specify a group (e.g. Citrix Admins or Help Desk) that will have permissions to Studio and Director. Click Next.
  4. On the Role page, select a role and then click Next. For example:
    • Full Administrator for the Citrix Admins group
    • Help Desk Administrator for the Help Desk group
    • Machine Catalog Administrator for the desktop team
  5. In the Summary page, click Finish.

Help Desk

  1. In the Studio, under Configuration, click the Administrators node. On the Administrators tab, right-click and click Create Administrator.
  2. In the Administrator and Scope page, specify a Help Desk group that will have permissions to Studio and Director. Click Next.
  3. On the Role page, select the Help Desk Administrator role and then click Next.
  4. In the Summary page, click Finish.
  5. When administrators in the Help Desk role log into Director, all they see is this.

    To jazz it up a little, add the Help Desk group to the read-only role.
  6. Right-click the Help Desk Administrator and click Edit Administrator.
  7. Click Add.
  8. In the Scope page, select a scope and click Next.
  9. In the Role page, select Read Only Administrator and click Next.
  10. In the Summary page, click Finish.
  11. Then click OK. Now Director will display the dashboard.

Provisioning Services w/Personal vDisk

From Citrix docs.citrix.com: The Provisioning Services Soap Service account must be added to the Administrator node of Studio and must have the Machine Administrator or higher role. This ensures that the PvD desktops are put into the Preparing state when the Provisioning Services (PVS) vDisk is promoted to production.

vCenter Connection

XenDesktop uses an Active Directory service account to log into vCenter. This account needs specific permissions in vCenter. To facilitate assigning these permissions, create a new vCenter role and assign it to the XenDesktop service account. The permissions should be applied at the datacenter or higher level. CTX214389 How to Define VMware vSphere User Privileges for XenApp and XenDesktop defines the minimum permissions needed for various activities in XenDesktop: MCS, PvS, Power Management, and AppDisks.  💡

Import vCenter Certificate

If you replaced the certificates on your vCenter server, then skip this section.

If vCenter is using a self-signed certificate, in order for Delivery Controller to trust the vCenter certificate, you must import the vCenter certificate on both Delivery Controllers.

  1. On each Delivery Controller, run mmc.exe. Open the File menu and click Add/Remove Snap-in.
  2. Move the Certificates snap-in to the right by highlighting it and clicking Add.
  3. Select Computer account and click Next.
  4. Select Local computer and click Finish.
  5. Click OK.
  6. After adding the snap-in, right-click the Trusted People node, expand All Tasks and click Import.
  7. In the Welcome to the Certificate Import Wizard page, click Next.
  8. In the File to Import page, browse to \\vcenter01\c$\ProgramData\VMware\VMware VirtualCenter\SSL and select crt. Click Next.
  9. In the Certificate Store page, click Next.
  10. In the Completing the Certificate Import Wizard page, click Finish.
  11. Click OK to acknowledge that the import was successful.
  12. Repeat these steps on the second Controller. It is important that you do both Controllers before adding the vCenter connection.

Hosting Resources

A Hosting Resource = vCenter + Cluster (Resource Pool) + Storage + Network. When you create a machine catalog, you select a previously defined Hosting Resource and the Cluster, Storage, and Network defined in the Hosting Resource object are automatically selected. If you need some desktops on a different Cluster+Storage+Network then you’ll need to define more Hosting Resources in Studio.

  1. In Studio, expand Configuration and click Hosting. Right-click it and click Add Connection and Resources.
  2. In the Connection page, select VMware vSphere as the Host type.
  3. Enter https://vcenter01.corp.local/sdk as the vCenter URL. The URL must contain the FQDN of the vCenter server. If the vCenter certificate is self-signed, ensure it is added to the Trusted People certificate store on all Delivery Controllers. Ensure the entered URL has /sdk on the end.
  4. Enter credentials of a service account. Click Next.
  5. Enter a name for the hosting resource. Since each hosting resource is a combination of vCenter, Cluster, Network, and Datastore, include those names in this field (e.g. vCenter01-Cluster01-Network01-Datastore01).
  6. In the Cluster page, click Browse and select a cluster or resource pool.
  7. Select a network and click Next.
  8. On the Storage page, select a datastore for the virtual machines.
  9. If desired, change the selection for personal vDisk to use a different storage. Click Next.
  10. In the Summary page, click Finish.

Citrix Director 7.6.9000

Director on Standalone Server

If you are installing Director 7.6.9000 on a standalone server, see Citrix CTX142260 Installing or Upgrading to Citrix Director 7.6.200

  1. If you intend to install Director on a standalone server, start with running AutoSelect.exe from the XenApp/XenDesktop 7.6.9000 media.
  2. On the top right, click Citrix Director.
  3. It will ask you for the location of one Controller in the farm. If you have multiple Director servers, point each Director server to a different Controller in the same farm. From Citrix Docs: Director automatically discovers all other Controllers in the same Site and falls back to those other Controllers if the Controller you specified fails. Then finish the installation wizard.
  4. If you upgraded an existing Director installation the upgrade, run the following command from an elevated command prompt: 
    C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /upgrade

  5. Also install Citrix Group Policy Management 2.5.9000 (aka 7.6.9000) on the Director server. Find CitrixGroupPolicyManagement_x64.msi on the 7.6.9000 ISO under \x64\Citrix Policy

Director Tweaks

Prepopulate the domain field

From http://www.xenblog.dk/?p=33: On the Controllers having the Director role installed, locate and edit the ‘LogOn.aspx’ file. By default you can find it at “C:\inetpub\wwwroot\Director\Logon.aspx”

In line 328 or line 358 you will have the following. To find the line, search for ID=”Domain”. Note: onblur and onfocus attributes were added in newer versions of Director.

<asp:TextBox ID="Domain" runat="server" CssClass="text-box" onfocus="showIndicator(this);" onblur="hideIndicator(this);"></asp:TextBox>

In the ID=”Domain” element, insert a Text attribute and set it to your domain name. Don’t change or add any other attributes. Save the file.

<asp:TextBox ID="Domain" runat="server" Text="Corp" CssClass="text-box" onfocus="showIndicator(this);" onblur="hideIndicator(this);"></asp:TextBox>

This will prepopulate the domain field text box with your domain name and still allow the user to change it, if that should be required.

Session timeout

By default the idle time session limit of the Director is 245 min. If you wish to change the timeout, here is how to do it.

  1. Log on to the Director Server as an administrator
  2. Open the ‘IIS Manager’
  3. Browse to ‘\Sites\Default Web Site\Director’ in the left hand pane.
  4. Open ‘Session State’ in the right hand pane
  5. Change the ‘Time-out (in minutes)’ value under ‘Cookie Settings’
  6. Click ‘Apply’ in the Actions list

SSL Check

From http://euc.consulting/blog/citrix-desktop-director-2-1: If you are not securing Director with an SSL certificate you will get this error at the logon screen.

To stop this:

  1. Log on to the Director Server as an administrator
  2. Open the ‘IIS Manager’
  3. Browse to ‘\Sites\Default Web Site\Director’ in the left hand pane.
  4. Open ‘Application Settings’ in the right hand pane
  5. Set EnableSslCheck to false.

Disable Activity Manager

From docs.citrix.com: By default, the Activity Manager in Director displays a list of all the running applications and the Windows description in the title bars of any open applications for the user’s session. This information can be viewed by all administrators that have access to the Activity Manager feature in Director. For Delegated Administrator roles, this includes Full administrator, Delivery Group administrator, and Help Desk Administrator.

To protect the privacy of users and the applications they are running, you can disable the Applications tab from listing running applications.

  • On the VDA, modify the registry key located at HKLM\Software\Citrix\Director\TaskManagerDataDisplayed. By default, the key is set to 1. Change the value to 0, which means the information will not be displayed in the Activity Manager.
  • On the server with Director installed, modify the setting that controls the visibility of running applications. By default, the value is true, which allows visibility of running applications in the Applications Change the value to false, which disables visibility. This option affects only the Activity Manager in Director, not the VDA. Modify the value of the following setting:
    UI.TaskManager.EnableApplications = false

Large Active Directory

From CTX133013 Desktop Director User Account Search Process is Slow or Fails: By default, all the Global Catalogs for the Active Directory Forest are searched using Lightweight Directory Access Protocol (LDAP). In a large Active Directory environment, this query can take some time or even time out.

  1. In Information Server (IIS) Management, under the Desktop Director site, select Application Settings and add a new value called Connector.ActiveDirectory.ForestSearch. Set it to False. This disables searching any domain except the user’s domain and the server’s domain.
  2. To search more domains, add the searchable domain or domains in the Connector.ActiveDirectory.Domains field.

Site Groups

From Citrix Blog Post Citrix Director 7.6 Deep-Dive Part 4: Troubleshooting Machines:

If there are a large number of machines, the Director administrator can now configure site groups to perform machine search so that they can narrow down searching for the machine inside a site group. The site groups can be created on the Director server by running the configuration tool via command line by running the command:

C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /createsitegroups

Then provide a site group name and IP address of the delivery controller of the site to create the site group.

Director – Multiple XenDesktop Sites

  1. Run IIS Manager. You can launch it from Server Manager (Tools menu) or from the Start Menu or by running inetmgr.
  2. On the left, expand Sites, expand Default Web Site, and click Director.
  3. In the middle pane, double-click Application Settings.
  4. Find the entry for AutoDiscoveryAddresses and double-click it.
  5. If Director is installed on a Controller, localhost should already be entered.
  6. Add a comma and the NetBIOS name of one of the controllers in the 2nd XenDesktop Site (farm). Only enter one Controller name. If you have multiple Director servers, you can point each Director server to a different Controller in the 2nd XenDesktop Site (farm). From Citrix Docs: Director automatically discovers all other Controllers in the same Site and falls back to those other Controllers if the Controller you specified fails.
  7. According to Citrix CTX200543 Desktop Director Access Fails After XenDesktop 7.5 is Upgraded to 7.6, the addresses should be NetBIOS names, not FQDN. Click OK.

Director – Saved Filters

From Scott Osborne and Jarian Gibson at Citrix Discussions: In Director, you can create a filter and save it.

The saved filter is then accessible from the Filters menu structure.

The saved filters are stored on each Director server at C:\Inetpub\wwwroot\Director\UserData. Observations:

  • Each user has their own saved filters.
  • The saved filters are not replicated across Director servers. You can schedule a robocopy script to do this automatically.
  • When upgrading Director, the saved filters are deleted?

You can instead configure multiple Director servers to store the filters on a shared UNC path: (h/t CTP Jarian Gibson)

  1. Create and share a folder (e.g. DirectorData).
  2. The Director server computer accounts need Modify permission to the share.
  3. On each Director server, run IIS Manager.
  4. Go to Sites > Default Web Site > Director. In the middle, double-click Application Settings.
  5. Change the Service.UserSettingsPath setting to the UNC path of the new share.
  6. Repeat this on other load balanced Director servers.

Director – Custom and Scheduled Reports

The Monitoring database contains more data than is exposed in Director. To view this data, the Monitoring service has an OData Data Feed that can be queried.

You can use Excel to pull data from the OData Data feed. See Citrix Blog Post – Citrix Director – Analyzing the Monitoring Data by Means of Custom Reports. This particular blog post shows how to use an Excel PivotChart to display the connected Receiver versions.

Or for Linqpad, see Citrix Blog Post – Creating Director Custom reports for Monitoring XenDesktop using Linqpad

Go to Citrix Blog Post Obtain XenDesktop Custom report through Citrix Director and download the tool. Once installed you can create custom reports from within Director.

Citrix Licensing Server

Upgrade

If you installed the Licensing Server that came with XenApp 7.6.9000, then it is already 11.15.0.0 build 27000.

If you have a standalone Licensing Server, then install or upgrade it to 11.15.0.0 build 27000.

  1. Go to the 7.6.9000 ISO, and run AutoSelect.exe.
  2. Click Studio and Server Components to begin the upgrade.
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms, and click Next.
  4. In the Ensure a successful upgrade page, check the box next to I’m ready to continue, and click Next.
  5. In the Firewall page, click Next.
  6. In the Summary page, click Upgrade.
  7. In the Finish page, click Finish.
  8. If you login to the License Administration Console, on the Administration tab, it shows it as version 11.15.0.0 build 27000.
  9. You can also view the version in the registry at HKLM\Software\Wow6432Node\Citrix\LicenseServer\Install.

Licensing Server HA using GSLB

From Dane Young – Creating a Bulletproof Citrix Licensing Server Infrastructure using NetScaler Global Server Load Balancing (GSLB) and CtxLicChk.ps1 PowerShell Scripts. Here is a summary of the configuration steps. See the blog post for detailed configuration instructions.

  1. Build two License Servers in each datacenter with identical server names. Since server names are identical, they can’t be domain-joined.
  2. Install identical licenses on all License Servers.
  3. Set the DisableStrictNameChecking registry key on all Citrix Licensing servers.
  4. Synchronize the certificate files located at C:\Program Files (x86)\Citrix\Licensing\WebServicesForLicensing\Apache\conf. They must be identical on all Licensing Servers.
  5. Download CtxLicChk.exe from http://support.citrix.com/article/CTX123935 and place on all Licensing Servers.
  6. Schedule the PowerShell script CtxLicChk.ps1 on all Licensing Servers. Get this script from the blog post linked above.
  7. Configure NetScaler:
    1. Configure GSLB ADNS services.
    2. Add wildcard Load Balancing service for each Citrix Licensing Server.
    3. Configure service TCP monitoring for ports 27000, 7279, 8082, and 8083.
    4. Create Load Balancing Virtual Server for each Licensing Server.
    5. Set one Load Balancing Virtual Server as backup for the other.
    6. Repeat in second datacenter.
    7. Configure GSLB Services and GSLB Monitoring.
    8. Configure GSLB Virtual Servers. Set one GSLB Virtual Server as backup for the other.
  8. Delegate the Citrix Licensing DNS name to the ADNS services on the NetScaler appliances.
  9. Configure Citrix Studio to point to the GSLB-enabled DNS name for Citrix Licensing.

Citrix License Server Monitoring

Citrix Licensing 11.13.1 and newer has historical usage reporting:

  1. Run Citrix Licensing Manager from the Start Menu. Or use a browser to connect to https://MyLicenseServer:8083
  2. Use the drop-down menus to select a license type, select dates, and export to a .csv file.
  3. The Update Licenses tab lets you check for renewals and download them.
  4. On the top right is a gear icon where you can set the historical retention period.

http://www.jonathanmedd.net/2011/01/monitor-citrix-license-usage-with-powershell.html.

Lal Mohan – Citrix License Usage Monitoring Using Powershell

Jaroslaw Sobel – Monitoring Citrix Licenses usage – Graphs using WMI, Powershell and RRDtool. This script generates a graph similar to the following:

Remote Desktop Licensing Server

Install Remote Desktop Licensing Server

Do the following on your XenDesktop Controllers:

  1. In Server Manager, open the Manage menu and click Add Roles and Features.
  2. Click Next until you get to the Server Roles Check the box next to Remote Desktop Services and click Next.
  3. Click Next until you get to the Role Services Check the box next to Remote Desktop Licensing and click Next.
  4. Click Add Features if prompted.
  5. Then finish the wizard to install the role service.

Activate Remote Desktop Licensing

  1. After RD Licensing is installed, in Server Manager, open the Tool menu, expand Terminal Services and click Remote Desktop Licensing Manager.
  2. The tool should find the local server. If it does not, right-click All servers, click Connect and type in the name of the local server. Once the local server can be seen in the list, right-click the server and click Activate Server.
  3. In the Welcome to the Activate Server Wizard page, click Next.
  4. In the Connection Method page, click Next.
  5. In the Company Information page, enter the required information and click Next.
  6. All of the fields on the Company Information page are optional so you do not have to enter anything. Click Next.
  7. In the Completing the Activate Server Wizard page, uncheck the box next to Start Install Licenses Wizard now and click Finish. Since the session hosts will be configured to pull Per User licenses, there is no need to install licenses on the RD Licensing Server.
  8. In RD Licensing Manager, right-click the server and click Review Configuration.
  9. Ensure you have green check marks. If the person installing Remote Desktop Licensing does not have permissions to add the server to the Terminal Server License Servers group in Active Directory, ask a domain admin to do it manually. If you have the proper permissions, click Add to Group.
  10. Click Continue when prompted that you must have Domain Admins privileges.
  11. Click OK when prompted that the computer account has been added.
  12. Click OK to close the window.

Health Check

Sacha Tomet Finally 1.0 – but never finalized!: XenApp & XenDesktop 7.x Health Check script has now Version 1.0.

Andrew Morgan – New Free Tool: Citrix Director Notification Service: The Citrix Director Notification service sits on an edge server as a service (or local to the delivery controller) and periodically checks the health of:

  • Citrix Licensing.
  • Database Connections.
  • Broker Service.
  • Core Services.
  • Hypervisor Connections.

And if any of these items fall out of bounds, an SMTP alert is sent to the mailbox of your choice for action. The tool will also send “All Clear” emails when these items are resolved, ensuring you are aware when the service has resumed a healthy state.

Related Pages

EUC Weekly Digest – May 28, 2016

Last Modified: Dec 18, 2018 @ 8:49 am

3 Comments
Here are some EUC items I found interesting last week:

Citrix – General

  • Marius Sandbu has a summary of the Synergy announcements – Day 1, Day 2
  • Microsoft’s Brad Anderson explains the Citrix – Microsoft partnership – Win10 VDI on Azure with Citrix XenDesktop, XenMobile Worx apps in Intune MAM, Skype for Business 2016
  • Many Citrix Synergy videos on Synergy TV. Also several on Youtube.
  • For instant notification of Citrix downloads and KB articles, follow @Citrixbot by Nicolas Ignoto
  • New Citrix Technology Advocates – many familiar names – Citrix Blog Post

XenApp/XenDesktop

Citrix Profile Management

NetScaler

Provisioning Services

XenMobile

XenServer

VMware

Other

EUC Weekly Digest – May 21, 2016

Last Modified: Sep 2, 2018 @ 7:53 am

4 Comments
Here are some pre-Synergy EUC items I found interesting last week.

XenApp/XenDesktop

Receiver

NetScaler

XenMobile

Other Citrix

Microsoft

VMware

Other

EUC Weekly Digest – May 14, 2016

Last Modified: Sep 2, 2018 @ 7:53 am

Leave a comment
Here are some EUC items I found interesting last week.

XenApp/XenDesktop

Receiver

NetScaler

XenMobile

VMware

Other

  • Unidesk 4.0 is now available – layers stored in file share instead of VMFS. Export fully composed image to Citrix Provisioning Services on vSphere. Also Azure. 2012 R2 RDSH only.

NetScaler 11.1 System Configuration

Last Modified: Jan 15, 2021 @ 6:23 am

46 Comments

Navigation

💡 = Recently Updated

Change Log

VPX Hardware

NetScaler VPX Release 11.1 supports new VPX models on ESXi. These new models include: VPX 25, VPX 5G, VPX 25G, etc. See the NetScaler VPX datasheet for more info.

NetScaler VPX Release 11.1 also supports changing the NIC type to VMXNET3 or SR-IOV. The imported appliance comes with E1000 NICs so you’ll have to remove all of the existing virtual NICs and add new VMXNET3 NICs.

Power On VPX and configure NSIP

  1. After swapping out the NICs to VMXNET3, power on the NetScaler VPX appliance.
  2. Configure the management IP from the VM’s console.
  3. Then point your browser to the management IP using either http or https and login as nsroot with password nsroot.

Auto-Provision IP Address

When importing VPX into a hypervisor, you can use VM advanced configuration parameters to set the NSIP. See CTX128250 How to Auto-Provision NetScaler VPX Appliance on a VMware ESX or ESXi Host, and CTX128236 How To Auto-Provision NetScaler VPX on XenServer.

Customer User Experience Improvement Program

  1. You might be prompted to enable the Customer User Experience Improvement Program. Either click Enable, or click Skip.

  2. You can also enable or disable the Customer Experience Improvement Program by going to System > Settings.
  3. On the right is Change CUXIP Settings.
  4. Make your selection and click OK.
  5. See https://www.carlstalhood.com/delivery-controller-7-15-ltsr-and-licensing/#ceip for additional places where CEIP is enabled.
set system parameter -doppler ENABLED

Welcome Wizard

NetScaler has a Welcome! Wizard that lets you set the NSIP, hostname, DNS, licensing, etc. It appears automatically the first time you login.

  1. Click the Subnet IP Address box.
  2. You can either enter a SNIP for one of your production interfaces, or you can click Do it later, and add SNIPs later after you configure Port Channels and VLANs. Note: If you have a dedicated management network, to prevent it from being used for outgoing traffic, don’t put a SNIP on it.

    add ns ip 10.2.2.60 255.255.255.0 -type SNIP
  3. Click the Host Name, DNS IP Address, and Time Zone box.
  4. Enter a hostname. Your NetScaler Gateway Universal licenses are allocated to this hostname. In a High Availability pair each node can have a different hostname. You typically create a DNS record that resolves the hostname to the NSIP (management IP).
  5. Enter one or more DNS Server IP addresses. Use the plus icon on the right to add more servers.
  6. Change the time zone to GMT-05:00-CDT-America/Chicago or similar.
  7. Click Done.

    set ns hostname ns02

add dns nameServer 10.2.2.11

set ns param -timezone "GMT-05:00-CDT-America/Chicago"
  8. Click Yes to save and reboot.
  9. Click the Licenses box.
  10. On the far right side of the screen, you’ll see the Host ID. You’ll need this to allocate your licenses at citrix.com. See below for detailed instructions on how to allocate the license to this Host ID.
  11. On the left, select Upload license files, and click Browse.
  12. Browse to the license file, open it, and click Reboot when prompted.
  13. After the reboot and logging in, a box will pop up showing you the installed license.
  14. Also look in the top left corner to make sure it doesn’t say NetScaler VPX (1). The number in the parentheses should match the MPX or VPX model number.

    License files are stored in /nsconfig/license.

Licensing – VPX Mac Address

To license a NetScaler VPX appliance, you will need its MAC address.

  1. Go to the Configuration tab.
  2. In the right pane, look down for the Host Id field. This is the MAC address you need for license allocation.
  3. Another option is to SSH to the appliance and run shell.
  4. Then run lmutil lmhostid. The MAC address is returned.

Licensing – Citrix.com

  1. Login to http://mycitrix.com.
  2. On the left, click All Licensing Tools.
  3. On the right, in the top right horizontal menu, click Activate and Allocate Licenses.
  4. If you are activating an eval license, click Don’t see your product near the top, and enter the eval license key.

  5. Otherwise, check the box next to a Citrix NetScaler VPX or MPX license, and click Continue.
  6. If this is a NetScaler MPX license then there is no need to enter a host ID for this license. so just click Continue.
  7. If this is a NetScaler VPX license, enter the VPX MAC address into the Host ID field. It’s not obvious, but you can enter text in this drop-down field.
  8. If you have more than one VPX license, change the Quantity field to 1, and then click Continue.

    For a VPX appliance, you can get the Host ID by looking at the System Information page. Click the System node to see this page.
  9. Click Confirm.
  10. Click OK when asked to download the license file.
  11. Click Download.
  12. Click Save and put it somewhere where you can get to it later.
  13. If you are running NetScaler 11.1 build 51 or newer, then 500 or more NetScaler Gateway Universal Licenses are already included in your NetScaler platform license. NetScaler Standard comes with 500 Gateway Universal, NetScaler Enterprise comes with 1,000 Gateway Universal, and NetScaler Platinum comes with unlimited Gateway Universal.
  14. If you need more Gateway Universal licenses on your NetScaler, you can allocate them now. These licenses can come from XenMobile Enterprise, XenApp/XenDesktop Platinum Edition, NetScaler Platinum Edition, or a la carte.
  15. Enter your appliance hostname as the Host ID for all licenses. If you have two appliances in a HA pair, allocate these licenses to the first appliance hostname, then reallocate them to the second appliance hostname.
  16. Click Confirm.
  17. Click OK when prompted to download your license file.
  18. Click Download.
  19. Click Save.
  20. If you have two appliances in a High Availability pair with different hostnames then you will need to return the NetScaler Gateway Universal licenses and reallocate them to the other hostname. The top right horizontal menu bar has a Reallocate option.

Install Licenses on Appliance

If you haven’t already installed licenses on your appliance, then do the following:

  1. In the NetScaler Configuration GUI, on the left, expand System and click Licenses.
  2. On the top right, click Manage Licenses.
  3. Click Add New License.
  4. If you have a license file, select Upload license files from a local computer and then click Browse. Select the license file and click Open.

    License files are stored in /nsconfig/license.
  5. Click Reboot when prompted. Login after the reboot.
  6. After rebooting, the Licenses node should look something like this. Notice that Maximum ICA Users Allowed is set to Unlimited.
  7. Maximum NetScaler Gateway Users Allowed will vary depending on your NetScaler Edition.
  8. Note: the NetScaler SNMP counter allnic_tot_rx_mbits must remain less than the licensed bandwidth or packets will drop.

Upgrade Firmware

Citrix CTX220371 Must Read Articles Before and After Upgrading NetScaler

Citrix CTX127455 How to Upgrade Software of the NetScaler Appliances in a High Availability Setup

  1. Download firmware. Ask your Citrix Partner or Citrix Support TRM for recommended versions and builds. At the very least, watch the Security Bulletins to determine which versions and builds resolve security issues. You can also subscribe to the Security Bulletins at http://support.citrix.com by clicking the Alerts (bell) link on the top right after logging in.
  2. Make sure you Save the config before beginning the upgrade.
  3. Transferring the firmware upgrade file to the appliance will be slow unless you license the appliance first. An unlicensed appliance will reduce the maximum speed to 1 Mbps.
  4. When upgrading from 10.5 or older, make sure the NetScaler Gateway Theme is set to Default or Green Bubbles. After the upgrade, you’ll have to create a new Portal Theme and bind it to the Gateway vServers.
  5. Start with the Secondary appliance.
  6. Before upgrading the appliance, consider using WinSCP or similar to back up the /flash/nsconfig directory.
  7. In the NetScaler GUI, with the top left node (System) selected, on the right, click System Upgrade.
  8. Click Choose File and browse to the build…tgz file. If you haven’t downloaded firmware yet then you can click the Download Firmware link.
  9. Click Upgrade.
  10. The firmware will upload.
  11. You should eventually see a System Upgrade window with text in it. Click Yes when prompted to reboot.
  12. Once the Secondary is done, login and failover the pair.
  13. Then upgrade the firmware on the former Primary.

 

To install firmware by using the command-line interface

  1. To upload the software to the NetScaler Gateway, use a secure FTP client (e.g. WinSCP) to connect to the appliance.
  2. Create a version directory under /var/nsinstall (e.g. /var/nsinstall/11.1.47).
  3. Copy the software from your computer to the /var/nsinstall/<version> (e.g. /var/nsinstall/11.1.47) directory on the appliance.
  4. Open a Secure Shell (SSH) client (e.g. Putty) to open an SSH connection to the appliance.
  5. At a command prompt, type shell.
  6. At a command prompt, type cd /var/nsinstall/<version> to change to the nsinstall directory.
  7. To view the contents of the directory, type ls.
  8. To unpack the software, type tar -xvzf build_X_XX.tgz, where build_X_XX.tgz is the name of the build to which you want to upgrade.
  9. To start the installation, at a command prompt, type ./installns.
  10. When the installation is complete, restart NetScaler.
  11. When the NetScaler restarts, at a command prompt type what or show version to verify successful installation.

High Availability

Configure High Availability as soon as possible so almost all configurations are synchronized across the two appliances. The Synchronization exceptions are mainly network interface configurations.

High Availability will also sync files between the two appliances. See CTX138748 File Synchronization in NetScaler High Availability Setup for more information.

  1. Prepare the secondary appliance:
    1. Configure a NSIP.
    2. Don’t configure a SNIP. In Step 2, Subnet IP Address, you can click Do It Later to skip the wizard. You’ll get the SNIP later when you pair it.
    3. Configure Hostname and Time Zone. Don’t configure DNS since you’ll get those addresses when you pair it.

    4. License the secondary appliance.
    5. Upgrade firmware on the secondary appliance. The firmware of both nodes must be identical.
  2. On the secondary appliance, go to System > High Availability, double-click the local node, and change High Availability Status to STAY SECONDARY. If you don’t do this then you run the risk of losing your config when you pair the appliances. See Terence Luk Creating a Citrix NetScaler High Availability pair without wiping out an existing configuration for more information.


    set ha node -hastatus STAYSECONDARY
  3. On the primary appliance, on the left, expand System, expand Network and click Interfaces.
  4. On the right, look for any interface that is currently DOWN.
  5. You need to disable those disconnected interfaces before enabling High Availability. Right-click the disconnected interface, and click Disable. Repeat for the remaining disconnected interfaces.

    show interface
disable interface 1/1
  6. On the left, expand System and click High Availability.
  7. On the right, double-click node 0 to edit it.
  8. Change the High Availability Status to STAY PRIMARY, and click OK.
  9. On the right, click Add.
  10. Enter the other NetScaler’s IP address.
  11. Enter the other NetScaler’s login credentials, and click Create.

    add ha node 1 192.168.123.14
    Note: this CLI command must be run separately on each appliance.
  12. If you click the refresh icon near the top right, Synchronization State will probably say IN PROGRESS.
  13. Eventually it will say SUCCESS.
  14. To enable Fail-safe mode, edit Node ID 0 (the local appliance).

    1. Change High Availability State back to ENABLED.
    2. Under Fail-safe Mode, check the box next to Maintain one primary node even when both nodes are unhealthy. Scroll down, and click OK.

      set ha node -failSafe ON
  15. If you login to the Secondary appliance, you might see a message warning you against making changes. Always apply changes to the Primary appliance.
  16. On the secondary appliance, go to System > High Availability, edit the local node, and change it from STAY SECONDARY to ENABLED.
  17. Go to System > Network > Routes, and make sure you don’t have two 0.0.0.0 routes. Joining an appliance to an HA pair causes the default route on the primary appliance to sync to the secondary appliance. But, it doesn’t delete the default gateway that was formerly configured on the secondary appliance.
  18. From the NetScaler CLI (SSH), run “sh ha node” to see the status. You should see heartbeats on all interfaces. If not, configure VLANs as detailed in the next section.
  19. You can also disable HA heartbeats on specific interfaces.
    1. Note: Make sure HA heartbeats are enabled on at least one interface/channel.
    2. Note: this is an interface configuration, so this configuration change is not propagated to the other node.
  20. You can force failover of the primary appliance by going to System > High Availability, opening the Actions menu, and clicking Force Failover.

    force ha failover
    If your firewall (e.g. Cisco ASA) doesn’t like Gratuitous ARP, see CTX112701 – The Firewall Does not Update the Address Resolution Protocol Table

Port Channels on Physical NetScaler MPX

If you are configuring a NetScaler MPX (physical appliance), and if you plugged in multiple cables, and if more than one of those cables is configured on the switch for the same VLAN(s), then you must bond the interfaces together by configuring a Port Channel. On the switch, create a Port Channel, preferably with LACP enabled. The Port Channel can be an Access Port (one VLAN), or a Trunk Port (multiple VLANs). On the NetScaler, configure LACP on the network interfaces, or create a Channel manually. Both are detailed below.

Also see Webinar: Troubleshooting Common Network Related Issues with NetScaler.

LACP Port Channel

To configure Port Channels on a NetScaler, you can either enable LACP, or you can configure a Channel manually. If your switch is configured for LACP, do the following on NetScaler to enable LACP on the member interfaces.

  1. Go to System > Network > Interfaces.
  2. On the right, edit one of the Port Channel member interfaces.
  3. Scroll down.
  4. Check the box next to Enable LACP.
  5. In the LACP Key field, enter a number. The number you enter here becomes the channel number. For example, if you enter 1, NetScaler creates a Channel named LA/1. All member interfaces of the same Port Channel must have the same LACP Key. Click OK when done.
  6. Continue enabling LACP on member interfaces and specifying the key (channel number). If you are connected to two port channels, one set of member interfaces should have LACP Key 1, while the other set of member interfaces should have LACP Key 2.
  7. Note: in an HA pair, you must perform this interface configuration on both nodes. The LACP commands are not propagated across the HA pair.
  8. If you go to System > Network > Channels.
  9. You’ll see the LACP Channels on the right. These were created automatically.
  10. If you edit a Channel, there’s a LACP Details tab that shows you the member interfaces.

Manual Channel

If your switch is not configured for LACP, then you can instead create a Channel manually.

  1. Go to System > Network > Channels.
  2. On the right, click Add.
  3. At the top, choose an unused Channel ID (e.g. LA/2).
  4. On the bottom, click Add.
  5. Click the plus icon next to each member interface to move it to the right. Then click Create.

Redundant Interface Set

You can also configure the NetScaler for switch-independent teaming. Create a Channel manually, but select a Channel ID starts with LR instead of LA. This is called Link Redundancy or Redundant Interface Set.

Channel Minimum Throughput

Channels can be configured so that a High Availability failover occurs when the Channel throughput drops below a configured value. For example, if you have four members in a Channel, you might want a High Availability failover to occur when two of the member interfaces fail.

  1. Go to System > Network > Channels, and edit a Channel.
  2. Near the top, enter a minimum threshold value in the Throughput field. If the total bonded throughput drops below this level, a High Availability failover will occur.

Trunk Port and High Availability

If you are trunking multiple VLANs across the channel, and if every VLAN is tagged (no native VLAN), then a special configuration is needed to allow High Availability heartbeats across the channel.

  1. Go to System > Network > VLAN.
  2. Add VLAN objects, and bind to the channel (e.g. LA/1).
  3. To bind multiple VLANs to a single interface/channel, the VLANs must be tagged.
  4. Configure one of the VLANs as untagged. Only untag one of them. Which one you untag doesn’t matter, except that the same VLAN should be untagged on the other HA node. If your switch doesn’t allow untagged packets, don’t worry, we’ll fix that soon.
  5. If your switch doesn’t allow untagged packets, go to System > Network > Channels, and edit the channel.
  6. Scroll down. On the Settings tab, set Tag all VLANs to ON. This causes NetScaler to tag all packets, including the VLAN you formerly marked as untagged. This special configuration is necessary to also tag High Availability heartbeat packets.
  7. Note: in an HA pair, you must perform this Tagall configuration on both nodes. The Tagall command is not propagated across the HA pair.

Common physical interface configuration

Here is a common NetScaler networking configuration for a physical NetScaler MPX that is connected to both internal and DMZ.

Note: If the appliance is connected to both DMZ and internal, then be aware that this configuration essentially bypasses (straddles) the DMZ-to-internal firewall. That’s because if a user connects to a public/DMZ VIP, then NetScaler could use an internal SNIP to connect to the internal server: in other words, traffic comes into a DMZ VLAN, but goes out an internal VLAN. A more secure approach is to have different appliances for internal and DMZ. Or use NetScaler SDX, partitioning, or traffic domains.

  • 0/1 connected to a dedicated management network. NSIP is on this network.
    • 0/1 is not optimized for high throughput so don’t put data traffic on this interface. If you don’t have a dedicated management network, then put your NSIP on one of the other interfaces (1/1, 10/1, LA/1, etc.) and don’t connect any cables to 0/1.
    • To prevent NetScaler from using this dedicated management interface for outbound data traffic, don’t put a SNIP on this management network, and configure the default gateway (route 0.0.0.0) to use a router on a different data network (typically the DMZ VLAN). However, if there’s no SNIP on this VLAN, and if the default gateway is on a different network, then there will be asymmetric routing for management traffic, since inbound management traffic goes in 0/1, but reply traffic goes out LA/1 or LA/2. To work around this problem, enable Mac Based Forwarding, or configure Policy Based Routing. Both of these options are detailed in the next section.
    • It’s easiest if the switch port for this dedicated management interface is an Access Port (untagged). If VLAN tagging is required, then NSVLAN must be configured on the NetScaler.
  • 10/1 and 10/2 in a LACP port channel (LA/1) connected to internal VLAN(s). Static routes to internal networks through a router on one of these internal VLANs.
    • If only one internal VLAN, configure the switch ports/channel as an Access Port.
    • If multiple internal VLANs, configure the switch ports/channel as a Trunk Port. Set one of the VLANs as the channel’s Native VLAN so it doesn’t have to be tagged.
    • If the networking team is unwilling to configure a Native VLAN on the Trunk Port, then NetScaler needs special configuration (tagall) to ensure HA heartbeat packets are tagged.
  • 1/1 and 1/2 in a LACP port channel (LA/2) connected to DMZ VLAN(s). The default gateway (route 0.0.0.0) points to a router on a DMZ VLAN so replies can be sent to Internet clients.
    • If only one DMZ VLAN, configure the switch ports/channel as an Access Port.
    • If multiple DMZ VLANs, configure the switch ports/channel as a Trunk Port. Set one of the VLANs as the channel’s Native VLAN so it doesn’t have to be tagged.
    • If the networking team is unwilling to configure a Native VLAN on the Trunk Port, then NetScaler needs special configuration (tagall) to ensure HA heartbeat packets are tagged.

Dedicated Management Subnet

Dedicated Management Subnet implies that your NetScaler is connected to multiple VLANs. If you have a subnet that is for NSIP only, and don’t want to use the NSIP subnet for data traffic, then you’ll want to move the default route to a different subnet, which breaks the NSIP. To work around this problem, create a PBR for the NSIP to handle replies from NSIP, and to handle traffic sourced by the NSIP.

  1. Go to System > Network > PBRs.
  2. On the right, click Add.
  3. Give the PBR a name (e.g. NSIP)
  4. Set the Next Hop Type drop-down to New.
  5. In the Next Hop field, enter the router IP address that is on the same network as the NSIP.
  6. In the Configure IP section, set the first Operation drop-down to =.
  7. In the Source IP Low field, enter the NSIP. This causes the PBR to match all traffic with NSIP as the Source IP address.
  8. You don’t need anything else.
  9. Scroll down, and click Create.
  10. To handle DNS traffic sourced by the NSIP, create another PBR by right-clicking the existing one, and clicking Add.
  11. Change the name to NSIP-DNS or similar.
  12. Change the Action drop-down to DENY. This prevents the PBR from overriding normal DNS behavior.
  13. Change the Priority to a lower number than the original PBR. Scroll down.
  14. In the Configure Protocol section, click the Protocol drop-down, and select UDP (17).
  15. In the Destination section, change the Operation to =.
  16. In the Destination port Low field, enter 53.
  17. Scroll down, and click Create.
  18. Make sure the DENY PBR is higher in the list (lower priority number) than the ALLOW PBR.
  19. Then open the Action menu, and click Apply.

    add ns pbr NSIP-DNS DENY -srcIP = 10.2.2.126 -destPort = 53 -nextHop 10.2.2.1 -protocol UDP -priority 5
add ns pbr NSIP ALLOW -srcIP = 10.2.2.59 -nextHop 10.2.2.1
apply ns pbrs

If you want a floating management IP that is always on the Primary appliance, here’s a method of granting management access without adding a SNIP to the management subnet:

  1. Create a Load Balancing Service on HTTP 80 on IP address 127.0.0.1. You might already have one called AlwaysUp that is used with SSL Redirects. Note: NetScaler doesn’t allow creating a Load Balancing service on IP address 127.0.0.1 and port 443 (SSL).
    1. The IP address you enter is 127.0.0.1. When you view the Load Balancing Service, it shows the local NSIP. After a HA failover, the IP Address will change to the other NSIP.
  2. Create a Load Balancing Virtual Server using a VIP on the management subnet. Protocol = SSL. Port number = 443.

    1. Bind the AlwaysUp:80 or loopback:80 service to the Load Balancing Virtual Server. In summary: the front end is 443 SSL, while the LB Service is 80 HTTP.
  3. Add the new VIP to the PBRs so the replies go out the correct interface.
  4. You should then be able to point your browser to https://Step2VIP to manage the appliance.
  5. You can perform the same loopback trick for 22 SSH. Create a Load Balancing Service on TCP 22 on IP address 127.0.0.1.
  6. Create a Load Balancing Virtual Server using the management VIP specified earlier. Protocol = TCP. Port number = 22.

    1. Bind the loopback:TCP:22 service to the Load Balancing Virtual Server.
  7. You should then be able to point your SSH Client to <Step2VIP> to manage the appliance.
  8. CLI Commands for the floating management VIP: 
    add service AlwaysUp 127.0.0.1 HTTP 80
add service mgmt-SSH 127.0.0.1 TCP 22
add lb vserver mgmt-SSL SSL 10.2.2.128 443
add lb vserver mgmt-SSH TCP 10.2.2.128 22
bind lb vserver mgmt-SSL AlwaysUp
bind lb vserver mgmt-SSH mgmt-SSH
set ns pbr NSIP-DNS DENY -srcIP = 10.2.2.126-10.2.2.128 -destPort = 53 -nextHop 10.2.2.1 -protocol UDP -priority 5
set ns pbr NSIP ALLOW -srcIP = 10.2.2.126-10.2.2.128 -nextHop 10.2.2.1
apply ns pbrs

Multiple Subnets / Multiple VLANs

Citrix CTX214033 Networking and VLAN Best Practices for NetScaler discusses many of the same topics detailed in this section.

If this is a physical MPX appliance, see the previous Port Channel section first.

If you only connected NetScaler to one subnet (one VLAN) then skip ahead to DNS servers.

Configuration Overview

The general configuration process for multiple subnets is this:

  1. Create a SNIP for each subnet/VLAN.
  2. Create a VLAN object for each subnet/VLAN.
    1. Bind the VLAN object to the SNIP for the subnet.
    2. Bind the VLAN object to the Port Channel or single interface that is configured for the VLAN/subnet.

SNIPs for each VLAN

You will need one SNIP for each connected subnet/VLAN. VLAN objects (tagged or untagged) bind the SNIPs to particular interfaces. NetScaler uses the SNIP’s subnet mask to assign IP addresses to particular interfaces.

NSIP Subnet

The NSIP subnet is special so you won’t be able to bind it to a VLAN. Use the following SNIP/VLAN method for any network that does not have the NSIP. The remaining interfaces will be in VLAN 1, which is the VLAN that the NSIP is in. VLAN 1 is only locally significant so it doesn’t matter if the switch is configured with it or not. Just make sure the switch has a native VLAN configured, or configure the interface as an access port. If you require trunking of every VLAN, including the NSIP VLAN, then additional configuration is required (NSVLAN or Tagall).

Configure Subnets/VLANs

To configure NetScaler with multiple connected subnets:

  1. Add a subnet IP for every network the NetScaler is connected to, except the dedicated management network. Expand System, expand Network, and click IPs.
  2. On the right, click Add.

    1. Enter the Subnet IP Address for this network/subnet. This SNIP will be the source IP address the NetScaler will use when communicating with any other service/server on this network. The Subnet IP is also known as the Interface IP for the network. You will need a separate SNIP for each connected network (VLAN).
    2. Enter the netmask for this network.
    3. Ensure the IP Type is set to Subnet IP. Scroll down.

      add ns ip 172.16.1.11 255.255.255.0 -type SNIP
    4. Under Application Access Controls, decide if you want to enable GUI management on this SNIP. This is particularly useful for High Availability pairs, because when you point your browser to the SNIP, only the primary appliance will respond. However, enabling management access on the SNIP can be a security risk, especially if this is a SNIP for a DMZ network.
    5. Click Create when done.
  3. Continue adding SNIPs for each connected network (VLAN).

    set ns ip 172.16.1.11 -mgmtAccess ENABLED -telnet DISABLED -ftp DISABLED
  4. On the left, expand System, expand Network, and click VLANs.
  5. On the right, click Add.
  6. Enter a descriptive VLAN ID. The actual VLAN ID only matters if you intend to tag the traffic. If not tagged, then any ID (except 1) will work.
  7. Check the box next to one physical interface or channel (e.g. LA/1) that is connected to the network.
  8. If this is a trunk port, select Tagged if the switch port/channel is expecting the VLAN to be tagged.
  9. If you don’t tag the VLAN, then the NetScaler interface/channel is removed from VLAN 1, and instead put in this VLAN ID.
  10. Switch to the IP Bindings tab.
  11. Check the box next to the Subnet IP for this network. This lets NetScaler know which interface is used for which IP subnet. Click Create when done.

    add vlan 50
bind vlan 50 -ifnum LA/1 -IPAddress 172.16.1.11 255.255.255.0
  12. On the left, expand System, expand Network, and click Routes.
  13. On the right, click Add.

    1. Internal networks are usually only accessible through an internal router. Add a static routes to the internal networks, and set the Gateway (next hop) to an internal router.
    2. Make sure NULL Route is set to No.
    3. Set the Gateway (Next Hop) to an internal router.
    4. Then click Create.

      add route 10.2.0.0 255.255.0.0 10.2.2.1
  14. The default route should be changed to use a router on the DMZ network (towards the Internet). Before deleting the existing default route, either enable Mac Based Forwarding, or create a Policy Based Route, so that the replies from NSIP can reach your machine. You usually only need to do this for dedicated management networks.
    1. Note: PBR is recommended over MBF, because PBR can handle traffic sourced by NSIP (e.g Syslog traffic), while MBF cannot.
    2. Mac Based Forwarding sends replies out the same interface they came in on. However, MBF ignores the routing table, and doesn’t handle traffic sourced by the NSIP (e.g. LDAP traffic). To enable MBF:
      1. On the left, expand System, and click Settings.
      2. On the right, in the left column, click Configure modes.
      3. Check the box next to MAC Based Forwarding (MBF), and click OK. More info on MAC Based Forwarding can be found at Citrix CTX1329532 FAQ: Citrix NetScaler MAC Based Forwarding (MBF).
  15. Go back to System > Network > Routes. On the right, delete the 0.0.0.0 route. Don’t do this unless the NetScaler has a route, PBR, or MBF to the IP address of the machine you are running the browser on.

    rm route 0.0.0.0 0.0.0.0 10.2.2.1
  16. Then click Add.
  17. Set the Network to 0.0.0.0, and the Netmask to 0.0.0.0.
  18. Make sure NULL Route is set to No.
  19. Enter the IP address of the DMZ (or data) router, and click Create.

    add route 0.0.0.0 0.0.0.0 172.16.1.1

DNS Servers

  1. To configure DNS servers, expand Traffic Management, expand DNS, and click Name Servers.
  2. On the right, click Add.
  3. Enter the IP address of a DNS server, and click Create.
  4. Note: The NetScaler must be able ping each of the DNS servers or they will not be marked as UP. The ping originates from the SNIP.

    add dns nameServer 10.2.2.11
  5. NetScaler 11.1 build 51 and newer includes DNS Security Options, which are useful if you use this NetScaler to provide DNS services to clients (e.g. DNS Proxy/Load Balancing, GSLB, etc.).

NTP Servers

  1. On the left, expand System, and click NTP Servers.
  2. On the right, click Add.
  3. Enter the IP Address of your NTP Server (or pool.ntp.org) and click Create.

    add ntp server pool.ntp.org
  4. Open the Action menu and click NTP Synchronization.
  5. Select ENABLED and click OK.

    enable ntp sync
  6. You can click the System node to view the System Time.
  7. If you need to manually set the time, SSH (Putty) to the NetScaler appliances. Run date to set the time. Run date –help to see the syntax.
  8. Ntpdate –u pool.ntp.org will cause an immediate NTP time update.

SYSLOG Server

Citrix CTX120609 NetScaler Log Rotation and Configuration Using Newsyslog

The NetScaler will by default store a few syslogs on the local appliance. You can create a syslog policy to also send the syslog entries to an external server, like Citrix Command Center.

  1. On the left, expand System, expand Auditing, and click Syslog.
  2. On the right, switch to the Servers tab and click Add.
  3. Enter a name for the Syslog server.
  4. If 11.1-49 or newer, you can change Server Type to Server Domain Name and enter a FQDN.
  5. Enter the IP Address or FQDN of the SYSLOG server, and 514 as the port.
  6. Configure the Log Levels you’d like to send to it.
  7. Check the box for TCP Logging if you want the client IP. Note: TCP Logging requires significant disk space on the Syslog server.
  8. Select your desired Time Zone and then click Create.

    add audit syslogAction MySyslogServer 10.2.2.12 -logLevel ALL -timeZone LOCAL_TIME
add audit syslogAction MySyslogServer syslog.corp.local -logLevel ALL -timeZone LOCAL_TIME
  9. On the right, switch to the Policies tab, and then click Add.
  10. Give the policy a descriptive name, select the Syslog server, and then click Create.

    add audit syslogPolicy MySyslogServer ns_true MySyslogServer
  11. While still on the Policies tab, open the Actions menu, and click Classic Policy Global Bindings or Advanced Policy Global Bindings, depending on which one you chose when creating the Syslog policy.
  12. Click the arrow next to Click to select.
  13. Select the Syslog policy you want to bind and click Select.
  14. If you don’t select anything in Global Bind Type, then it defaults to SYSTEM_GLOBAL.
  15. Click Bind.
  16. Click Done.

    bind audit syslogGlobal -policyName MySyslogServer -priority 100
bind system global MySyslogServer -priority 100

SNMP – MIB, Traps, and Alarms

  1. On the left, expand System, and click SNMP.
  2. On the right, click Change SNMP MIB.
  3. Change the fields as desired. Your SNMP tool (e.g. NetScaler Management and Analytics System) will read this information. Click OK.
  4. This configuration needs to be repeated on the other node.

    set snmp mib -contact NSAdmins@corp.com -name ns02 -location Corp
  5. Expand System, expand SNMP, and click Community.
  6. On the right, click Add.
  7. Specify a community string and the Permission and click Create.

    add snmp community public GET
  8. On the left, under SNMP, click Traps.
  9. On the right, click Add.
  10. Specify a trap destination and Community Name and click Create.

    add snmp trap generic 10.2.2.12 -communityName public
add snmp trap specific 10.2.2.12 -communityName public
  11. On the left, under SNMP, click Managers.
  12. On the right, click Add. Note: if you do not add a manager then the NetScaler will accept SNMP queries from all SNMP Managers on the network.
  13. Change the selection to Management Network.
  14. Specify the IP of the Management Host and click Create.

    add snmp manager 10.2.2.12
  15. The Alarms node allows you to enable SNMP Alarms and configure thresholds.
  16. You can open an alarm to set thresholds. For example, CPU-USAGE can be set to 90% alarm and 50% normal with a Critical severity.

    set snmp alarm CPU-USAGE -thresholdValue 90 -normalValue 50 -severity Critical
  17. You can also configure the MEMORY alarm.

    set snmp alarm MEMORY -thresholdValue 90 -normalValue 50 -severity Critical

From http://www.slideshare.net/masonke/net-scaler-tcpperformancetuningintheaolnetwork: In addition to the usual OIDs, we have found these very useful to warn of potential problems.

  • ifTotXoffSent – .1.3.6.1.4.1.5951.4.1.1.54.1.43
  • ifnicTxStalls – .1.3.6.1.4.1.5951.4.1.1.54.1.45
  • ifErrRxNoBuffs – .1.3.6.1.4.1.5951.4.1.1.54.1.30
  • ifErrTxNoNSB – .1.3.6.1.4.1.5951.4.1.1.54.1.31

Call Home

Citrix Blog Post – Protect Your NetScaler From Disaster With Call Home!: If you have a physical NetScaler (MPX or SDX) with an active support contract, you many optionally enable Call Home to automatically notify Citrix Technical Support of hardware and software failures.

  1. On the left, expand System and click Diagnostics.
  2. On the right, in the left column, in the Technical Support Tools section, click Call Home.
  3. Check the box next to Enable Call Home.
  4. Optionally enter an email address to receive notifications from Citrix Technical Support. Click OK.
  5. If you go back into Call Home, it should indicate if registration succeeded or failed. Successful registration requires an active support contract.

Change nsroot Password

  1. If you want to force strong passwords for local accounts, go to System > Settings, on the right, click Change Global System Settings
  2. Scroll down to the Command Line Interface (CLI) section.
  3. You can change Strong Password to Enable, and also specify a Min Password Length. Click OK.
  4. Expand System, expand User Administration and click Users.
  5. On the right, select nsroot, and click Change Password.
  6. Specify a new password and click OK.

    set system user nsroot Passw0rd

TCP, HTTP, SSL, and Security Settings

Citrix Whitepaper Secure Deployment Guide for NetScaler MPX, VPX, and SDX Appliances

Citrix Knowledgebase articles:

 

  1. On the left, expand System and click Settings.
  2. On the right side of the right pane, click Change TCP parameters.

    1. Check the box for Window scaling (near the top).
    2. Scroll down and check the box for Selective Acknowledgement. Click OK.

      set ns tcpParam -WS ENABLED -SACK ENABLED
  3. On the right, click Change HTTP parameters.

    1. Under Cookie, change the selection to Version1. This causes NetScaler to set Cookie expiration to a relative time instead of an absolute time.

      set ns param -cookieversion 1
    2. Check the box next to Drop invalid HTTP requests.
    3. Scroll down and click OK.

      set ns httpParam -dropInvalReqs ON
  4. From Citrix CTX232321 Recommended TCP Profile Settings for Full Tunnel VPN/ICAProxy from NetScaler Gateway 11.1 Onwards:  💡
    1. Expand System, and click Profiles.
    2. On the right, on the TCP Profiles tab, edit the nstcp_default_profile.
    3. Enable Window Scaling with a factor of 8.
    4. Set Minimum RTO (in millisec) = 600.
    5. Set TCP Buffer Size (bytes) = 600000
    6. Set TCP Send Buffer Size (bytes) = 600000
    7. Change TCP Flavor = BIC.
    8. Enable Use Nagle’s algorithm.
    9. Click OK when done.
  5. You can run the following command to see statistics on the dropped packets: 
    nsconmsg -g http_err_noreuse_ -d stats
  6. See CTX209398 Addressing false positives from CBC and MAC vulnerability scans of SSHD to harden SSHD by editing /nsconfig/sshd_config with the following. Then run kill -HUP `cat /var/run/sshd.pid` to restart SSHD. 
    Ciphers aes128-ctr,aes192-ctr,aes256-ctr
MACs hmac-sha1,hmac-ripemd160
  7. Implement Responder policies to prevent Shellshock attack against back-end web servers. See Citrix CTX200277 NetScaler Defends Against Shellshock Attack. 
    add audit messageaction ShellShock_Log CRITICAL "\"The request was sent from \" +CLIENT.IP.SRC + \" Bash Code Injection Vulnerability\"" -bypassSafetyCheck YES

add responder policy ShellShock_policy "HTTP.REQ.FULL_HEADER.REGEX_MATCH(re/\(\)\s*{/) || HTTP.Req.BODY(1000).REGEX_MATCH(re/\(\)\s*{/) || HTTP.REQ.URL.QUERY.REGEX_MATCH(re/\(\)(\s*|\++){/) || HTTP.REQ.BODY(1000).REGEX_MATCH(re#%28%29[+]*%7B#)" DROP ‑logAction ShellShock_Log

bind responder global ShellShock_policy 10 END -type REQ_DEFAULT

The following security configurations are detailed by Jason Samuel at Mitigating DDoS and brute force attacks against a Citrix Netscaler Access Gateway:

  • Maximum logon attempts on NetScaler Gateway Virtual Server
  • Rate Limiting for IP.SRC and HTTP.REQ.URL.
  • nstcp_default_XA_XD_profile TCP profile on the NetScaler Gateway Virtual Server.
  • Syslog logging
  • External website monitoring
  • Obfuscate the Server header in the HTTP response
  • Disable management access on SNIPs
  • Change nsroot strong password, use LDAP authentication, audit local accounts
  • Don’t enable Enhanced Authentication Feedback
  • SSL – disable SSLv3, deny SSL renegotiation, enable ECDHE ciphers, disable RC4 ciphers. Also see Anton van Pelt Make your NetScaler SSL VIPs more secure (Updated) .
  • 2-factor authentication
  • Command Center and Insight Center
  • Review IPS/IDS & Firewall logs

Management Authentication

Load balancing of authentication servers is strongly recommended since during an authentication attempt only one LDAP server is chosen. If you instead bound multiple LDAP servers it would try all of them and for incorrect passwords will lock out the user sooner than expected.

  1. Expand System, expand Authentication, and then click LDAP.
  2. On the right, switch to the Servers tab. Then click Add.
  3. Enter LDAPS-Corp-Mgmt or similar as the name. If you have multiple domains, you’ll need a separate LDAP Server per domain so make sure you include the domain name. Also, the LDAP policy used for management authentication will be different than the LDAP policy used for NetScaler Gateway.
  4. Change the selection to Server IP. Enter the VIP of the NetScaler load balancing vServer for LDAP.
  5. Change the Security Type to SSL.
  6. Enter 636 as the Port. Scroll down.
  7. In the Connection Settings section, enter your Active Directory DNS domain name in LDAP format as the Base DN.
  8. Enter the credentials of the LDAP bind account in userPrincipalName format.
  9. Check the box next to BindDN Password and enter the password. Click Test Connection. Scroll down.
  10. In the Other Settings section, use the drop-down next to Server Logon Name Attribute, Group Attribute, and Sub Attribute Name to select the default fields for Active Directory.
  11. On the right, check the box next to Allow Password Change.
  12. It is best to restrict access to only members of a specific group. In the Search Filter field, enter memberOf=<GroupDN>. See the example below:
    memberOf=CN=NetScaler Administrators,OU=Citrix,DC=corp,DC=local
    You can add :1.2.840.113556.1.4.1941: to the query so it searches through nested groups. Without this users will need to be direct members of the filtered group.
    memberOf:1.2.840.113556.1.4.1941:=CN=NetScaler Administrators,OU=Citrix,DC=corp,DC=local

    Citrix 132802 How to Use the ldapsearch Utility on the NetScaler Gateway Enterprise Edition Appliance to Validate a Search Filter
    An easy way to get the full distinguished name of the group is through Active Directory Administrative Center. Double-click the group object and switch to the Extensions page. On the right, switch to the Attribute Editor tab.
    Scroll down to distinguishedName, double-click it and then copy it to the clipboard.

    Back on the NetScaler, in the Search Filter field, type in memberOf= and then paste the Distinguished Name right after the equals sign. Don’t worry about spaces.
  13. Scroll down and click More to expand it.
  14. For Nested Group Extraction, if desired, change the selection to Enabled.
  15. Set the Group Name Identifier to samAccountName.
  16. Set Group Search Attribute to –<< New >>– and enter memberOf.
  17. Set Group Search Sub-Attribute to –<< New >>– and enter CN.
  18. Example of LDAP Nested Group Search Filter Syntax

  19. Scroll down and click Create.

    add authentication ldapAction Corp-Mgmt -serverIP 10.2.2.210 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword Passw0rd -ldapLoginName samaccountname -searchFilter "memberOf=CN=NetScaler Admins,CN=Users,DC=corp,DC=local" -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
  20. Switch to the Policies tab and click Add.
  21. Enter the name LDAPS-Corp-Mgmt or similar.
  22. Select the previously created LDAPS-Corp-Mgmt server.
  23. On the bottom, in the Expressions area, type in ns_true.
  24. Click Create.

    add authentication ldapPolicy Corp-Mgmt ns_true Corp-Mgmt
  25. Click Global Bindings in the right pane.
  26. Click where it says Click to select.
  27. Select the newly created LDAP policy, and click Select.
  28. Click Bind.
  29. Click Done.

    bind system global Corp-Mgmt
  30. Under System, expand User Administration and click Groups.
  31. On the right, click Add.
  32. In the Group Name field, enter the case sensitive name of the Active Directory group containing the NetScaler administrators.
  33. In the Command Policies section, click Insert.
  34. Select the superuser policy, and click Insert.
  35. Click Create.

    add system group "NetScaler Admins" -timeout 900
bind system group "NetScaler Admins" -policyName superuser 100
  36. If you logout:
  37. You should be able to login to NetScaler using an Active Directory account.

CLI Prompt

  1. When you connect to the NetScaler CLI prompt, by default, the prompt is just a >.
  2. You can run set cli prompt %u@%h to make it the same as a UNIX prompt. See Citrix Docs for the cli prompt syntax.

Backup and Restore

  1. Go to System > Backup and Restore.

  2. On the right, click the Backup button.
  3. Give the backup file a name.
  4. For Level, select Full and click Backup.
  5. Once the backup is complete, you can download the file.

For a PowerShell script, see John Billekens Create offline backups of the NetScaler config

To restore:

  1. If you want to restore the system and if the backup file is not currently on the appliance, you click the Backup button. Yes, this seems backwards.
  2. Change the selection to Add.
  3. Browse Local to the previously downloaded backup file.
  4. Then click Backup. This uploads the file to the appliance and adds it to the list of backup files.
  5. Now you can select the backup and click Restore.

Next Steps

Return to NetScaler Procedures list

EUC Weekly Digest – May 7, 2016

Last Modified: Sep 2, 2018 @ 7:52 am

3 Comments
Here are some EUC items I found interesting last week.

 Citrix

VMware

Other

 

EUC Weekly Digest – April 30, 2016

Last Modified: Sep 2, 2018 @ 7:53 am

1 Comment

Here are some EUC items I found interesting last week.

Citrix

VMware

Other

EUC Weekly Digest – April 23, 2016

Last Modified: Sep 2, 2018 @ 7:53 am

1 Comment

Here are some EUC items that interested me last week.

Citrix

VMware

Other