Category: ADC / NetScaler

Native One Time Passwords (OTP) – Citrix Gateway 13

Last Modified: Mar 17, 2023 @ 8:12 am

125 Comments

Navigation

Change Log

Overview

Citrix ADC 13 Native OTP lets you enable two-factor authentication without purchasing any other authentication product. A typical configuration uses Citrix SSO app (mobile VPN Client) to receive push notifications, or Google Authenticator to generate Passcodes. See the following for an overview:

Here are some notes and requirements for Native OTP:

  • Licensing – Citrix ADC Native OTP is part of nFactor, and thus requires Citrix ADC Advanced Edition or Citrix ADC Premium Edition licensing. Citrix ADC Standard Edition licensing is not sufficient.
    • OTP Push Notifications require ADC Premium Edition
  • Workspace app 1809 and newer with Citrix Gateway 12.1 build 49 and newer support nFactor authentication. Older Receivers and older NetScalers don’t support nFactor with Receiver, so you’ll instead have to use a web browser.

  • Citrix Gateway VPN Plug-in 12.1 build 49 and later support nFactor when authenticating from the VPN Plug-in.

  • Push notifications – Citrix ADC 13 and newer supports OTP push notifications of logon request to the mobile (iOS, Android) Citrix SSO app. Other authenticator apps are not supported for OTP Push, but they can be used with OTP Passcode.
  • Authenticator – If not using Citrix SSO app, then Google Authenticator can generate passcodes. Christian in the comments indicated that Microsoft Authenticator also works. Click on plus sign -> other (Google,…).
  • Internet for Push – Push notifications requires the Citrix ADC appliance to be able to send API calls across the Internet to Citrix Cloud.
  • Active Directory attribute – Citrix ADC stores OTP device enrollment secrets in an string-based Active Directory attribute. Citrix’s documentation uses the userParameters Active Directory attribute.
    • The LDAP bind account must have permission to modify this attribute on every user.
    • The userParameters attribute must not be populated. Active Directory Users & Computers might set the userParameters attribute if you modify any of the RDS property pages.
  • Enroll multiple devices – Citrix ADC 13 and newer lets you control the number of devices that a user can enroll.
  • Manageotp is difficult to secure – The manageotp website is usually only protected by single factor authentication so external access must be blocked.
    • Andreas Nick OTPEdit is an out-of-band tool to register OTP devices without using manageotp.

Notes on Citrix ADC Configuration Objects for OTP

Here are some notes on the Citrix ADC OTP configuration objects. Detailed instructions are provided later.

  • Make sure NTP is configured on the Citrix ADC. Accurate time is required.
  • AAA vServer – nFactor requires a AAA vServer, which can be non-addressable. You don’t need any additional public IP for OTP.
    • An Authentication Profile links the AAA vServer to the Citrix Gateway vServer.
  • Citrix Cloud – For Push notifications, create a Citrix Cloud account. No Citrix Cloud licensing needed. Citrix ADC uses Cloud API credentials to authenticate with Citrix Cloud.
  • NSC_TASS cookie – To access the manageotp web page, users add /manageotp to the end of the Gateway URL. Citrix ADC puts this URL path into a cookie called NSC_TASS. You can use this cookie and its value in policy expressions for determining which Login Schema is shown to the user.
  • Login Schema for manageotp – The built-in Login Schema file named SingleAuthManageOTP.xml has hidden fields that enable the manageotp web page. If the Login Schema Policy expression permits the SingleAuthManageOTP.xml Login Schema to be shown to the user, then after authentication the user will be taken to the manageotp web page.

    • LDAP authentication is expected to be bound to the same factor as this SingleAuthManageOTP login schema.
    • The next factor is a LDAP Policy/Server with authentication disabled (unchecked) but with arguments specifying the Active Directory attribute for the OTP Secret and Push Service configuration.

  • Login Schema for OTP authentication – The built-in Login Schema file named DualAuthPushOrOTP.xml performs the two-factor authentication utilizing the push service. There’s a checkbox that lets users choose Passcode instead of Push. This login schema has a Credential called otppush.

    • If you prefer to not use Push, then you can use a normal DualAuth.xml Login Schema file since for passcode authentication there are no special Login Schema requirements other than collecting two password fields.
    • Both methods expect an authenticating LDAP Policy/Server to be bound to the same Factor as the Login Schema.
    • The next factor should be a non-authenticating LDAP Policy/Server that optionally has the the Push Service defined and must have the OTP Secret attribute defined.
  • Single Sign-on to StoreFront – The OTP dual authentication Login Schema essentially collects two passwords (AD password plus push, or AD password plus passcode). Later, Citrix Gateway needs to use the AD password to perform Single Sign-on to StoreFront. To ensure the AD password is used instead of the OTP passcode, configure the OTP dual authentication Login Schema to store the AD password in a AAA attribute and then use a Citrix Gateway Traffic Policy/Profile to utilize the AAA attribute during Single Sign-on to StoreFront.
  • nFactor Visualizer – Citrix ADC 13 has a nFactor Visualizer to simplify the OTP configuration. Or you can manually create the LDAP Policies/Actions, the Login Schema Policies/Profiles, the PolicyLabels, and then bind them to a AAA vServer.

OTP Encryption

ADC 13.0 build 41 and newer let you encrypt the OTP secrets stored in Active Directory.

ADC uses a certificate to encrypt the contents of the Attribute. It currently is not possible to configure the certificate from the GUI, so you’ll need to SSH to the ADC and run the following command:

bind vpn global -userDataEncryptionKey MyCertificate

To enable OTP attribute encryption:

  1. In the ADC menu, go to Security > AAA – Application Traffic.
  2. On the right, click Change authentication AAA OTP Parameter.
  3. Check the box for OTP Secret encryption and then click OK.
  4. If you have a previous implementation of ADC OTP that stored unencrypted OTP secrets, then use the Python OTP encryption tool at /var/netscaler/otptool/OTP_encryption_tool to encrypt the AD attribute using the userDataEncryptionKey certificate. The same tool can be used to change the encryption certificate. More details at OTP encryption tool at Citrix Docs. Also see CTP Julian Jakob Citrix NetScaler – OTP Encryption Tool.

AAA Virtual Server

Create a AAA vServer that is the anchor point for our OTP nFactor configuration.

  1. Make sure the time is correct on the NetScaler. Click the Configuration tab to see the current System Time. Make sure NTP is configured at System > NTP Servers.
  2. Go to Security > AAA – Application Traffic.
  3. If the AAA feature is not enabled, then right-click the AAA node, and click Enable Feature.
  4. Go to Security > AAA – Application Traffic > Virtual Servers.
  5. On the right, click Add.
  6. This AAA vServer is for OTP so name it accordingly.
  7. Change the IP Address Type to Non Addressable. You don’t need to specify any additional IP address.
  8. Click the blue OK button.
  9. Click where it says No Server Certificate.

    1. In the Server Certificate Binding section, click Click to select.
    2. Click the radio button next to a certificate, and then click the blue Select button at the top of the page. You can select the same certificate as the Citrix Gateway Virtual Server.
    3. Click Bind.
  10. Click Continue to close the Certificate section.
  11. In the Advanced Authentication Policies section, don’t bind anything and just click Continue. We’ll bind a nFactor Flow later.
  12. You can optionally improve the SSL ciphers on this AAA Virtual Server but it’s probably not necessary since this AAA vServer is not directly addressable.
  13. Nothing else is needed at this time so click the blue back arrow on the top left.

Push Service

If your Citrix ADC has Internet access, then you can enable OTP Push Authentication. The ADC must be able to reach the following FQDNs:

  • mfa.cloud.com
  • trust.citrixworkspacesapi.net

Create an API Client at citrix.cloud.com:

  1. Go to https://citrix.cloud.com and login. Your cloud account does not need any licensed services.
  2. On the top left, click the hamburger (menu) icon, and then click Identity and Access Management.
  3. Switch to the tab named API Access.
  4. On this page, notice the Customer ID. You’ll need this value later.
  5. Enter a name for a new API client and then click Create Client
  6. Click Download to download the client credentials.

On ADC 13, create the Push Service:

  1. In Citrix ADC 13 management GUI, navigate to the Push Service node. The easiest way to find it is to enter Push in the search box on the top left.
  2. On the right, click Add.
  3. In the Create Push Service page, do the following:
    1. Enter a name for the Push Service.
    2. Enter the Client ID and Client Secret that you downloaded when creating your API Client.
    3. Enter the Customer ID shown on the Create Client web page at cloud.com. Make sure there are no hidden characters or whitespace around the Customer ID.
  4. Click Create.
  5. On the top right, click the refresh icon until the Status changes to COMPLETE. If it won’t go past CCTOKEN, then make sure you entered the API Client info correctly, especially the Customer ID, which might have hidden characters around it.

LDAP Actions/Servers

Create three LDAP Actions (aka LDAP Servers):

  • One LDAP Action for normal LDAP authentication against Active Directory
  • One LDAP Action to set the OTP Active Directory attribute and register with push
  • One LDAP Action to perform push authentication (in a dual-authentication flow)

Create normal LDAP Action

  1. Go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Actions > LDAP.
  2. On the right, click Add.
  3. Create a normal LDAP Server if you don’t have one already. This one has Authentication enabled. There are no special instructions for this LDAP Server.

Create LDAP Action for OTP Device Registration

Create the LDAP Action for OTP device registration that sets the OTP Active Directory attribute and registers with push:

  1. Create another LDAP Action.
  2. Name it according to this goal: used by the manageotp web site to set the OTP authenticator in Active Directory.
  3. On the right, uncheck the box next to Authentication.
  4. Make sure the Administrator Bind DN has permissions to modify the OTP Secret Active Directory attribute for all users. A regular non-admin LDAP Bind account won’t work.
  5. If you cloned an existing LDAP Server, then make sure you re-enter the Administrator Password or the new LDAP Action won’t work.
  6. Click Test LDAP Reachability.
  7. Configure the Server Logon Name Attribute to match the one you configured in the normal authentication LDAP Server.
  8. In the Other Settings section, on the bottom right, find the OTP Secret field. Enter the name of the Active Directory attribute where Citrix ADC will store the user’s OTP secret. You can use the userParameters attribute if that attribute isn’t being used for anything else.
    • userParameters is populated by Active Directory Users & Computers if you set anything on the RDS tabs (e.g. RDS Roaming Profile).
  9. Select the Push Service that you created earlier.
  10. Click Create when done.

Create LDAP Action for OTP Authentication

Create a LDAP Action that performs OTP push authentication or verifies the OTP Passcode. The only difference from the prior LDAP Action is the addition of an LDAP Search Filter.

  1. Create another LDAP Action.
  2. Give the LDAP Action a name.
  3. On the right, uncheck the box next to Authentication.
  4. Make sure the Administrator Bind DN has permissions to read the OTP Secret Active Directory attribute.
  5. If you cloned an existing LDAP Server, then make sure you re-enter the Administrator Password or the new LDAP Action won’t work.
  6. Click Test LDAP Reachability.
  7. In the Other Settings section, configure the Server Logon Name Attribute to match the one you configured in the normal authentication LDAP Server.
  8. In the Search Filter field, enter the text userParameters>=#@. This syntax ensures that only users with enrolled authenticators can login. See George Spiers NetScaler native OTP for more info.
  9. In the Other Settings section, on the bottom right, find the OTP Secret field. Enter the name of the Active Directory attribute containing the user’s OTP secret.
  10. In the Push Service drop-down, select the Push Service that you already created.
  11. Click Create when done.

nFactor Visualizer

We will build a nFactor Flow that looks something like this:

  • First factor on the left chooses either OTP Device Registration or OTP Authentication. If user enters /manageotp, then nFactor Flow takes the top path. Otherwise, nFactor flow takes the bottom path.
    • Login Schema is not needed for the first factor.
  • Second factor for Manage OTP = Login Schema with Manage OTP flag and normal LDAP authentication before allowing users to add devices.
    • Third factor is just an LDAP Policy configured with the OTP Active Directory attribute and Push Service. No Login Schema needed.
  • Second factor for OTP Authentication = Login Schema with OTP Push (or OTP Passcode) and normal LDAP authentication.
    • Third factor is just an LDAP Policy with the OTP Active Directory attribute and Push Service. No Login Schema needed.

nFactor Visualizer notes:

  • nFactor Visualizer is not required. You can instead follow the older manual ADC 12.1 instructions.
  • It doesn’t seem to be possible to rename any part of the flow once it’s created. To rename, you basically remove the entire flow and rebuild it.
  • nFactor Visualizer does not support policy expressions for Login Schemas so the older ADC 12.1 instructions must be modified to support two different branches.

Create Flow and first factor that selects Manage or selects Authenticate

  1. In ADC 13, go to Security > AAA – Application Traffic > nFactor Visualizer > nFactor Flows. Or search the menu for nFactor.
  2. On the right, click Add.
  3. Click the blue plus icon to create a factor.
  4. Name the factor based on this goal: choose manageotp or authenticate based on whether the user entered /manageotp or not. The name of the first factor is also the name of the nFactor Flow.
  5. Click the blue Create button.
  6. The first factor does not need a Schema.
  7. In the first factor, click where it says Add Policy.
  8. In the Choose Policy to Add page, click Add to create an authentication policy.

    1. Name this policy according to this goal: if this policy’s expression is true, then select the manageotp branch (instead of OTP authentication).
    2. For the Action Type drop-down, select NO_AUTHN. This policy is merely a decision point for the next factor so no actual authentication will occur at this time. The next factor is configured later.
    3. In the Expression box, enter something similar to the following. The IP subnet expression restricts the manageotp web page to only internal users. 
      http.req.cookie.value("NSC_TASS").eq("manageotp") && client.IP.SRC.IN_SUBNET(10.2.0.0/16)
    4. In newer ADC 13, you might have to change the expression to eq /manageotp, or change it to contains manageotp. (source = Samuel LEGRAND Native OTP issues on Citrix ADC 13) 💡 
      http.req.cookie.value("NSC_TASS").eq("/manageotp") && client.IP.SRC.IN_SUBNET(10.2.0.0/16)
http.req.cookie.value("NSC_TASS").contains("manageotp") && client.IP.SRC.IN_SUBNET(10.2.0.0/16)
    5. Then click the blue Create button.
  9. Click the blue Add button to bind this policy to the factor.
  10. In the first factor, below the policy you just added, click the blue plus arrow to create another policy.
  11. In the Choose Policy to Add page, click Add to create another policy.

    1. Name the policy according to this goal: select the dual factor OTP authentication branch.
    2. For the Action Type drop-down, select NO_AUTHN. This is a decision point policy without authentication that leads to the next factor that does the actual authentication.
    3. In the Expression box, enter true to capture all OTP users that did not match the prior manageotp policy.
    4. Click the blue Create button.
  12. Click Add to bind this policy to the first factor but after (higher priority number) than the manageotp policy.

Create second factor for manageotp

  1. In the first factor, click the green plus icon to the right of the “SelectManageOTP” policy. If the “SelectManageOTP” policy is true, then this new factor will be evaluated.
  2. Name this factor according to this goal: perform single-factor LDAP authentication before allowing access to the manageotp web page.
  3. Then click the blue Create button.
  4. In the second factor, click where it says Add Schema.
  5. In the Choose Schema page, click Add to create a Login Schema.

    1. Name the Login Schema according to this goal: ask user for one password that will be verified with LDAP (Active Directory) before showing the manageotp web page.
    2. In the Authentication Schema field, click the pencil icon.
    3. The existing window expands to show the Login Schema Files. On the left, click the LoginSchema folder to see the files in that folder.
    4. In the list of files, click SingleAuthManageOTP.xml. This login schema asks for one password and has the special hidden credential to enable the manageotp web page.
    5. To actually select this file, on the top right, click the blue Select button. The Login Schema window will then collapse so that Login Schema Files are no longer shown.
    6. Make sure the Authentication Schema field shows the Login Schema file that you selected.
    7. Then click the blue Create button.
  6. Click OK to bind the Schema to the factor.
  7. In the second factor, below the Schema, click Add Policy.
  8. In the Choose Policy to Add page, if you already have a normal Advanced Expression LDAP policy, then select it.
  9. Otherwise, click Add to create one.

    1. Name this policy according to this goal: perform normal LDAP authentication against an Active Directory domain.
    2. In the Action Type drop-down, select LDAP.
    3. In the Action drop-down, select the LDAP Action/Server you created earlier that performs normal authentication.
    4. In the Expression box, enter true, which is an Advanced Expression.
    5. Click the blue Create button.
  10. Click Add to bind this LDAP Policy to the factor.

Create third factor that registers an OTP device with Active Directory and Push

  1. In the second factor, click the green plus icon to create another factor. This new factor is only evaluated if the LDAP Policy is successful.
  2. Name the factor according to this goal: register the device with Active Directory and optionally Push.
  3. This factor does not need any Schema.
  4. In the third factor, click Add Policy
  5. In the Choose Policy to Add page, click Add to create a policy.

    1. Name the policy according to this goal: Register OTP devices using LDAP Action without authentication that has the OTP Secret Attribute specified.
    2. In the Action Type drop-down, select LDAP.
    3. In the Action drop-down, select the LDAP Action you created earlier that registers new devices. Make sure authentication is disabled in the LDAP Action, and make sure it has OTP Secret and optionally OTP Push configured.
    4. In the Expression field, enter true.
    5. Click the blue Create button.
  6. Click the blue Add button to bind this policy to the factor.

The Factors for manageotp are complete. Now we build the factors for authenticating using OTP.

Create a second factor for LDAP Authentication

  1. Go back to the first factor and click the green plus icon next to the OTP Authentication policy.
  2. Name the factor according to this goal: ask user for one password + push, or two passwords, and then perform LDAP authentication. OTP authentication is performed in the next factor (see below).
  3. In the second factor, click where it says Add Schema.
  4. In the Choose Schema window, click Add.

    1. Name the Login Schema according to this goal: ask for one password + OTP push, or ask for two passwords.
    2. In the Authentication Schema field, click the pencil icon.
    3. The window expands to show Login Schema Files. On the left, click the LoginSchema folder to see the files under it.
    4. On the left, click the DualAuthPushOrOTP.xml file.
    5. Or if you don’t want push, then click a normal two password schema like DualAuth.xml. You can modify the DualAuth.xml file to indicate to the user that the OTP Passcode is expected in the second field.
    6. Then on the top right click the blue Select button. This causes the Login Schema window to collapse and no longer show the Login Schema Files.
    7. In the Authentication Schema field, makes sure the correct file name is selected.
    8. Click More.
    9. At the bottom, in the Password Credential Index field, enter a 1 to save the first password into AAA Attribute 1, which we’ll use later in a Traffic Policy that performs Single Sign-on to StoreFront.
    10. Then click the blue Create button.
  5. Click OK to bind the Schema to the factor.
  6. In the second factor, below the schema, click where it says Add Policy.
  7. In the Select Policy drop-down, select your normal LDAP Active Directory authentication policy. This is the same one you used for the second factor in the manageotp branch.
  8. Click the blue Add button to bind this LDAP policy to the second factor.

Create third factor to perform OTP authentication (Push or Passcode)

  1. In the second factor, click the green plus icon next to the LDAP Policy to create another factor.
  2. Name the factor according to this goal: perform OTP Push or Passcode authentication.
  3. Be aware that the nFactor Visualizer might swap your third factors.
  4. This third factor does not need a Login Schema.
  5. In the new third factor (probably the top one, follow the arrows), click where it says Add Policy.
  6. In the Choose Policy to Add page, click Add to create a policy.

    1. Name this policy according to this goal: perform OTP Push or OTP Passcode authentication.
    2. In the Action Type drop-down, select LDAP.
    3. In the Action drop-down, select the LDAP action you created earlier that verifies the OTP push or passcode. This is the Action that has the LDAP Filter configured.
    4. In the Expression box, enter true.
    5. Click the blue Create button.
  7. Click the blue Add button to bind this policy to the third factor.
  8. Click the blue Done button to close the Flow.

Bind nFactor Flow to AAA Virtual Server

  1. In the nFactor Flows menu node, highlight the nFactor Flow and click the button labelled Bind to Authentication Server.
  2. In the Authentication Server drop-down, select the AAA vServer you created earlier.
  3. Everything else should already be filled in so just click the blue Create button.

Maximum Number of Registered OTP Devices

ADC 13 lets you restrict the number of OTP devices each user can register:

  1. In the ADC menu, go to Security > AAA – Application Traffic.
  2. On the right, click Change authentication AAA OTP Parameter.
  3. Enter the number of devices each user can register and then click OK.
  4. When the user attempts to register more than the max number of devices, the error message is not user friendly.
  5. But you can see the actual error by grepping /var/log/ns.log for otp. which might show <Max permitted otp devices reached>.

Traffic Policy for Single Sign-on to StoreFront

Create Traffic Profile

  1. On the left, go to Citrix Gateway > Policies > Traffic.
  2. On the right, switch to the tab named Traffic Profiles, and click Add.
  3. Name the Traffic Profile according to this goal: use the AAA attribute 1 as password when doing Single Sign-on to StoreFront.
  4. Scroll down.
  5. In the SSO Password Expression box, enter the following which uses the Login Schema Password Attribute specified earlier. 
    AAA.USER.ATTRIBUTE(1)
  6. Click the blue Create button.

Create Traffic Policy

  1. On the right, switch to the tab named Traffic Policies, and click Add.
  2. In the Request Profile field, select the Traffic Profile you just created.
  3. Name the Traffic Policy.
  4. In the Expression box, enter true (Advanced Syntax).
    • If your Citrix Gateway Virtual Server allows full VPN, change the expression to the following. Source = Julien Mooren at NetScaler – Native OTP is breaking SSL VPN. 
      http.req.method.eq(post)||http.req.method.eq(get) && false
  5. Click the blue Create button.

Citrix Gateway, Traffic Policy, and Authentication Profile

Note: ADC 13.0 build 36.27 will perform a core dump if AppFlow is enabled on the appliance so make sure AppFlow is disabled under Advanced Features. The core dump seems to happen even if no AppFlow policies are bound to the Gateway Virtual Server.

Edit an existing Citrix Gateway Virtual Server

  1. Go to Citrix Gateway > Virtual Servers.
  2. Edit an existing Gateway vServer. If you don’t have one, see the other Citrix Gateway topics on this site.

Bind the Traffic Policy

  1. While editing a Gateway Virtual Server, scroll down to the Policies section, and click the plus icon.
  2. Change the Choose Policy drop-down to Traffic, and then click the blue Continue button.
  3. In the Policy Binding section, click Click to select.
  4. Click the radio button next to the Traffic Policy you created earlier, and then click the blue Select button at the top of the page.
  5. Click the blue Bind button.

Create Authentication Profile

Create and bind an Authentication Profile to link the Gateway Virtual Server to the AAA Virtual Server:

  1. While editing a Gateway Virtual Server, on the right, in the Advanced Settings column, click Authentication Profile.
  2. On the left, scroll down to the Authentication Profile section.
  3. Click Add to create one.
  4. Authentication Profile links the Citrix Gateway vServer with the OTP AAA vServer, so name it accordingly.
  5. In the Authentication Virtual Server section, click Click to select.
  6. Click the radio button next to the OTP AAA vServer, and then click the blue Select button at the top of the page.
  7. Click the blue Create button.
  8. Scroll down again to the Authentication Profile section, and click the blue OK button. Your selection isn’t saved until you click OK.
  9. The Portal Theme bound to the Gateway Virtual Server should be X1, RfWebUI, or a derivative.

Update Content Switching Expression for Unified Gateway

If your Citrix Gateway Virtual Server is behind a Unified Gateway (Content Switching Virtual Server), then you must update the Content Switching Expression to include the manageotp paths.

  1. In the Citrix ADC GUI, navigate to Configuration> Traffic Management > Content Switching > Policies.
  2. On the right, select the Unified Gateway Content Switching Policy, and then click Edit.
  3. Append the following expression under the Expression area, and then click OK. 
    || HTTP.REQ.URL.CONTAINS("/manageotp")

Manageotp User Experience

To access the manageotp web page:

  1. Point your browser to https://mygateway.corp.com/manageotp or similar. Add /manageotp to the end of your Gateway URL.
  2. Notice it’s only single-factor authentication. Login using normal LDAP credentials.
  3. Click Add Device.
  4. Enter a device name, and click Go.
  5. For OTP Push, on your phone, install the Citrix SSO app if it’s not already installed. Then launch it.
    1. Switch to the Password Tokens tab and tap Add New Token.
    2. Tap Scan QR Code.
    3. Then scan the QRCode shown in your browser.
    4. You should see the Device Name. Tap Save.
  6. If OTP Passcode, launch the Google Authenticator application on your phone. Click the plus icon in Google Authenticator, and scan the QRCode that is shown on the screen.
    1. Citrix SSO app also supports passcode.
    2. Christian in the comments indicated that Microsoft Authenticator also works. Click on plus sign -> other (Google,…).
  7. If you configured OTP Push, then you won’t see a Test button. To display the Test button, simply refresh your browser page.
  8. Click Test.
  9. Enter the passcode shown in your Authenticator, and click Go.

    1. Citrix SSO app shows the passcode on the main Password Tokens view.
  10. When done, on the top right, click your name and Log Off.
  11. The OTP registration info is stored in the Active Directory attribute. If users need to re-register, then help desk might need permission to clear this Active Directory attribute.

Perform OTP Authentication

  1. If you access your Gateway URL normally, you’ll be prompted for either one password or two passwords. If one password, then enter your normal LDAP credentials and Citrix Gateway will send a push notification to your phone. If two passwords, then enter the OTP passcode in the second field.
  2. The push notification is shown on the phone’s lock screen. Tap it to open the Citrix SSO app.
  3. Tap Allow to allow the authentication request.
  4. Tap OK when prompted with Logon Success.
  5. After Gateway authentication, Gateway should Single Sign-on into StoreFront with no additional password prompts.

CLI Commands

Here’s a complete OTP nFactor Flow (Visualizer) CLI configuration (except encrypted passwords):

# AAA Global Settings
# -------------------
enable ns feature AAA
set aaa otpparameter -maxOTPDevices 1


# Push Service
# ------------

add authentication pushService cloudPush -namespace "https://mfa.cloud.com/" -clientID b6effb5e-b2d3125 -clientSecret 152c84647b -encrypted -encryptmethod ENCMTHD_3 -CustomerID MyCompan -trustService "https://trust.citrixworkspacesapi.net/"

# LDAP Actions
# ------------
add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword a368c -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN

add authentication ldapAction OTPRegisterDevice -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn admin@corp.local -ldapBindDnPassword 1f952a81 -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -pushService cloudPush -OTPSecret userParameters

add authentication ldapAction LDAPOTPAuthentication -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn admin@corp.local -ldapBindDnPassword 4319b4d7 -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -searchFilter "userParameters>=#@" -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -pushService cloudPush -OTPSecret userParameters


# Advanced Authentication Policies
# --------------------------------
add authentication Policy _OTP-AAA_OTPManageOrAuthenticate__root_0 -rule true -action NO_AUTHN

add authentication Policy SelectManageDevices -rule "http.req.cookie.value(\"NSC_TASS\").contains(\"manageotp\") && client.IP.SRC.IN_SUBNET(10.2.0.0/16)" -action NO_AUTHN

add authentication Policy SelectOTPAuthentication -rule true -action NO_AUTHN

add authentication Policy LDAPAdv -rule true -action LDAP-Corp

add authentication Policy OTPRegisterDevice -rule true -action OTPRegisterDevice

add authentication Policy LDAPOTPAuthentication -rule true -action LDAPOTPAuthentication


# Login Schemas
# -------------
add authentication loginSchema SinglePasswordForManageOTP -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthManageOTP.xml"

add authentication loginSchema OTPPushOrPasscode -authenticationSchema "/nsconfig/loginschema/LoginSchema/DualAuthPushOrOTP.xml" -passwordCredentialIndex 1


# Authentication Policy Labels
# ----------------------------
add authentication policylabel OTPManageOrAuthenticate__root -loginSchema LSCHEMA_INT
bind authentication policylabel OTPManageOrAuthenticate__root -policyName SelectManageDevices -priority 100 -gotoPriorityExpression NEXT -nextFactor AuthenticateToManageDevices__OTPManageOrAuthenticate
bind authentication policylabel OTPManageOrAuthenticate__root -policyName SelectOTPAuthentication -priority 110 -gotoPriorityExpression NEXT -nextFactor OTPAuthentication__OTPManageOrAuthenticate

add authentication policylabel AuthenticateToManageDevices__OTPManageOrAuthenticate -loginSchema SinglePasswordForManageOTP
bind authentication policylabel AuthenticateToManageDevices__OTPManageOrAuthenticate -policyName LDAPAdv -priority 100 -gotoPriorityExpression NEXT -nextFactor OTPDeviceRegistration__OTPManageOrAuthenticate

add authentication policylabel OTPAuthentication__OTPManageOrAuthenticate -loginSchema OTPPushOrPasscode
bind authentication policylabel OTPAuthentication__OTPManageOrAuthenticate -policyName LDAPAdv -priority 100 -gotoPriorityExpression NEXT -nextFactor OTPPushOrPasscode__OTPManageOrAuthenticate

add authentication policylabel OTPDeviceRegistration__OTPManageOrAuthenticate -loginSchema LSCHEMA_INT
bind authentication policylabel OTPDeviceRegistration__OTPManageOrAuthenticate -policyName OTPRegisterDevice -priority 100 -gotoPriorityExpression NEXT

add authentication policylabel OTPPushOrPasscode__OTPManageOrAuthenticate -loginSchema LSCHEMA_INT
bind authentication policylabel OTPPushOrPasscode__OTPManageOrAuthenticate -policyName LDAPOTPAuthentication -priority 100 -gotoPriorityExpression NEXT


# Authentication Virtual Servers
# ------------------------------
add authentication vserver OTP-AAA SSL 0.0.0.0
bind authentication vserver OTP-AAA -policy _OTP-AAA_OTPManageOrAuthenticate__root_0 -priority 100 -nextFactor OTPManageOrAuthenticate__root -gotoPriorityExpression NEXT


# Authentication Profiles
# -----------------------
add authentication authnProfile OTP-AAA -authnVsName OTP-AAA


# NetScaler Gateway Session Profiles
# ----------------------------------
add vpn sessionAction AC_OS_10.2.4.120 -transparentInterception OFF -defaultAuthorizationAction ALLOW -SSO ON -icaProxy ON -wihome "https://xdc01.corp.local/Citrix/StoreWeb" -ClientChoices OFF -ntDomain corp.local -clientlessVpnMode OFF -storefronturl "https://xdc01.corp.local"

add vpn sessionAction AC_WB_10.2.4.120 -transparentInterception OFF -defaultAuthorizationAction ALLOW -SSO ON -icaProxy ON -wihome "https://xdc01.corp.local/Citrix/StoreWeb" -ClientChoices OFF -ntDomain corp.local -clientlessVpnMode OFF


# NetScaler Gateway Session Policies
# ----------------------------------
add vpn sessionPolicy PL_OS_10.2.4.120 "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" AC_OS_10.2.4.120

add vpn sessionPolicy PL_WB_10.2.4.120 "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver && REQ.HTTP.HEADER Referer EXISTS" AC_WB_10.2.4.120


# NetScaler Gateway Global Settings
# ---------------------------------
enable ns feature SSLVPN


# NetScaler Gateway Virtual Servers
# ---------------------------------
add vpn vserver gateway2 SSL 10.2.4.220 443 -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -deploymentType ICA_STOREFRONT -authnProfile OTP-AAA -vserverFqdn gateway3.corp.com
bind vpn vserver gateway2 -portaltheme RfWebUI
bind vpn vserver gateway2 -policy LDAP-Corp -priority 100
bind vpn vserver gateway2 -policy PL_OS_10.2.4.120 -priority 100
bind vpn vserver gateway2 -policy PL_WB_10.2.4.120 -priority 100


# SSL Virtual Servers
# -------------------
bind ssl vserver gateway2 -certkeyName WildcardCorpCom.cer_CERT_KEY
bind ssl vserver gateway2 -eccCurveName P_256
bind ssl vserver gateway2 -eccCurveName P_384
bind ssl vserver gateway2 -eccCurveName P_224
bind ssl vserver gateway2 -eccCurveName P_521

bind ssl vserver OTP-AAA -certkeyName WildcardCorpCom.cer_CERT_KEY
bind ssl vserver OTP-AAA -eccCurveName P_256
bind ssl vserver OTP-AAA -eccCurveName P_384
bind ssl vserver OTP-AAA -eccCurveName P_224
bind ssl vserver OTP-AAA -eccCurveName P_521

 

Citrix Application Delivery Management (ADM) 12.1

Last Modified: Jun 17, 2020 @ 10:15 am

59 Comments

Navigation

The older 12.0 version of NetScaler MAS is detailed in a different post.

💡 = Recently Updated

Change Log

Planning

Why ADM?

Citrix Application Delivery Management (ADM), formerly known as NetScaler Management and Analytics System (MAS), enables every Citrix ADC (formerly known as NetScaler) administrator to achieve the following:

  • Alert notifications – Receive email alerts whenever something goes down. For example, if a Load Balancing service goes down, you can receive an email alert.
    • ADM can email you for any Major SNMP trap produced by any ADC appliance.
  • Automatically backup all Citrix ADC instances.
    • ADM can even transfer the backups to an external system, which is then backed up by a normal backup tool.
  • SSL Certificate Expiration – Alert you when SSL certificates are about to expire.
    • Show you all SSL certificates across all ADC appliances.
  • Configuration Record and Play – Use the Configuration Recorder to configure one ADC appliance, and then push out the same configuration changes to additional appliances. This is the easiest method of managing ADC appliances in multiple datacenters.
  • AppFlow Reporting – Receive ICA AppFlow traffic from ADC and show it in graphs.
    • Integrate ADM with Citrix Director so Help Desk can see the AppFlow data.

Everything listed above is completely free, so there’s no reason not to deploy ADM.

ADM Overview

For an overview of ADM, see Citrix’s YouTube video Citrix NetScaler MAS: Application visibility and control in the cloud.

Cloud vs on-prem

ADM is available both on-premises, and as a Cloud Service. For the Cloud Service, you import a ADM Agent appliance to an on-prem hypervisor, or deploy a ADM Agent to AWS or Azure. The ADM Agent is the broker between the Cloud Service and the on-prem (or cloud hosted) Citrix ADC appliances. For more info on the ADM Cloud Service, see the following:

The rest of this article focuses on the on-premises version, but much of it also applies to the Cloud Service.

On-premises ADM Licensing:

  • Instance management is free (unlimited). This includes Configuration Jobs, Instance Backups, Network Functions/Reporting. Basically everything in the Networks node is free.
  • Analytics and Application monitoring are free for up to 30 Virtual Servers (Load Balancing, Citrix Gateway, Content Switching, etc.).

ADM version – The version/build of Citrix ADM must be the same or newer than the version/build of the Citrix ADC appliances being monitored. ADM 12.1 can monitor 12.0 and older ADC appliances.

HDX Insight

See CTX239748 for a list of HDX Insight Quality Improvements in Citrix Gateway 12.1. These include:

  • NSAP protocol for reduced performance impact on ADC
  • EDT support

HDX Insight Requirements (aka AppFlow Analytics for Citrix ICA traffic):

  • Your ADC appliance must be running Enterprise Edition or Platinum Edition.
  • ADC must be 10.1 or newer.
  • HDX Insight works with the following Receivers:
    • Receiver for Windows must be 3.4 or newer. Or upgrade to Workspace app.
    • Receiver for Mac must be 11.8 or newer. Or upgrade to Workspace app.
    • Receiver for Linux must be 13 or newer. Or upgrade to Workspace app.
    • Notice no mobile Receivers. See the Citrix Receiver Feature Matrix for the latest details.
  • For ICA Session Reliability with AppFlow: NetScaler 10.5 build 54 and newer.
    • For ICA Session Reliability, AppFlow, and ADC High Availability: NetScaler 11.1 build 49 and newer.
  • For EDT (UDT-based ICA), Citrix ADC must be 12.1 build 49 or newer.
  • AppFlow statistics are only generated when ICA traffic flows through a Citrix Gateway. Internally, when a user clicks an icon from StoreFront, an ICA connection is established directly from Receiver to the VDA, thus bypassing the internal ADC. Here are some methods of getting ICA traffic to flow through an internal ADC:
  • A new Receiver / Workspace app Virtual Channel named NetScaler App Experience or NSAP can dramatically reduce the CPU needed on the ADC to process AppFlow. Details at Citrix Blog Post HDX Insight 2.0. NSAP requires the following:
    • VDA 7.17 or newer, including VDA 1903. VDA 7.15 (LTSR) does not include the NSAP functionality.
    • Workspace app or Receiver 4.10 and newer.
    • ADC 12.0 build 57.24 or newer, including ADC 12.1.
  • For ICA round trip time calculations, in a Citrix Policy, enable the following settings:
    • ICA > End User Monitoring > ICA Round Trip Calculation
    • ICA > End User Monitoring > ICA Round Trip Calculation Interval
    • ICA > End User Monitoring > ICA Round Trip Calculation for Idle Connections
  • Citrix CTX215130 HDX Insight Diagnostics and Troubleshooting Guide contains the following contents:
    • Introduction
    • Prerequisites for Configuring HDX Insight
    • Troubleshooting
      • Issues Related to ICA parsing
      • Error Counter details
    • Checklist before Contacting Citrix Technical Support
    • Information to collect before Contacting Citrix Technical support
    • Known Issues

Citrix CTX204274 How ICA RTT is calculated on NetScaler Insight: ICA RTT constitutes the actual application delay. ICA_RTT = 1 + 2 + 3 + 4 +5 +6:

  1. Client OS introduced delay
  2. Client to NS introduced network delay (Wan Latency)
  3. NS introduced delay in processing client to NS traffic (Client Side Device Latency)
  4. NS introduced delay in processing NS to Server (XA/XD) traffic (Server Side Device Latency)
  5. NS to Server network delay (DC Latency)
  6. Server (XA/XD) OS introduced delay (Host Delay)

Multi-Datacenter Deployment Architecture

In a main datacenter, import two Citrix ADM appliances into the same subnet and configure them as an HA pair with a Floating IP address.

In a DR datacenter, import a Citrix ADM appliance, and configure it to replicate with the main datacenter.

For Citrix ADC appliances in additional datacenters, import two ADM Agent appliances into each datacenter, and configure them as remote agents to the main datacenter. Two ADM Agents per datacenter enables HA. The virtual appliance for ADM Agent is different than the normal ADM appliance.

Import ADM Appliance

If you are upgrading an existing MAS, skip to the Upgrade section.

To import a ADM Appliance into vSphere, do the following. The same process is used for DR ADM appliance. The ADM Agent appliance is different from the normal ADM appliances that are detailed in this section.

  1. Go to the ADM 12.1 download page. Expand NetScaler MAS Release 12.1. Expand Product Software. Click the latest release of 12.1.
  2. Download the Citrix ADM image for ESX.
  3. Then extract the .zip file.
  4. In vSphere Web Client, right-click a cluster, and click Deploy OVF Template.
  5. In the Select an OVF Template page, select Local file, and browse to the Citrix ADM .ovf files. If vCenter 6.5+, select all three files. Click Next.

  6. In the Select name and folder page, enter a name for the virtual machine, and select an inventory folder. Then click Next.
  7. In the Select a resource page, select a cluster or resource pool, and click Next.
  8. In the Review details page, click Next.
  9. In the Select storage page, select a datastore. Due to high IOPS requirement, SSD or Flash is recommended.
  10. Change the virtual disk format to Thin Provision. Click Next.
  11. In the Select networks page, choose a valid port group, and click Finish.
  12. In the Ready to Complete page, click Finish.
  13. Before powering on the appliance, you can review its specs. Right-click the virtual machine, and click Edit Settings.
  14. Review the specs. Citrix Docs VMware ESXi Hardware Requirements has recommended specs.
  15. The OVF defaults to 8 vCPU and 32 GB of RAM.
  16. You can add a second hard disk at this time.
  17. Citrix Docs Attach an additional disk to Citrix ADM says that an additional disk must be added before initial deployment.
    • Use the ADM storage calculator to determine the recommended size of the disk. Ask your Citrix Partner for the tool.
    • The new disk must be larger than 120 GB.
    • In ADM 12.1, the new disk can be larger than 2 TB.
    • In ADM 12.1, the new disk can be grown later, and /mps/DiskPartitionTool.py can resize the partition, but only up to 2 TB. If you need more than 2 TB, the initial disk should be larger than 2 TB.
  18. Power on the Virtual Machine.

Appliance IP Address Configuration

  1. Open the console of the virtual machine.
  2. Configure IP address information.
  3. Enter 7 when done.

Second Disk

  1. SSH to the appliance and login as nsrecover/nsroot.
  2. Enter /mps/DiskPartitionTool.py

  3. Enter info to see that there are no existing partitions on the second disk.
  4. Enter create to create partitions on the second disk. A reboot is required.
  5. During the reboot, the database is moved to the second disk.
  6. After the reboot, the Disk Partition Tool info command shows the partition on the second disk.
  7. If you need to increase the size of the disk, reboot the ADM appliance so it detects the larger size. Then use the Disk Partition Tool resize command.

Deployment Modes

HA Pair in the Main Datacenter

First Node:

  1. SSH to the first node and login as nsrecover/nsroot.
  2. Enter deployment_type.py.
  3. Enter 1 for Citrix ADM Server.
  4. Enter no when prompted for Citrix ADM Standalone deployment.
  5. For the First Server Node prompt, enter yes.
  6. Enter yes to Restart the system.

Second Node:

  1. Import another ADM appliance to the same subnet, and configure an IP address.
    • Latency to the HA node must not exceed 10 ms.
    • The HA nodes must be on the same subnet.
  2. If you added a second disk to the first ADM appliance, then you must add the same size second disk to the second ADM appliance.
  3. Configure the new nodes’ IP address.
  4. SSH to the second appliance, login as nsrecover/nsroot, and run the Disk Partition tool.
  5. SSH to the second appliance, login as nsrecover/nsroot, and run deployment_type.py.
  6. Enter 1 for Citrix ADM Server.
  7. Enter no when prompted for Citrix ADM Standalone deployment.
  8. Enter no when prompted is this is First Server Node.
  9. Enter the IP address of the first MAS node.
  10. Enter the nsroot password of the first node. The default password is nsroot.
  11. Enter a new Floating IP address.
  12. Enter yes to restart the system.

Deploy HA Configuration:

  1. Point your browser to the first appliance’s IP address, and login as nsroot/nsroot.
  2. If you see Customer User Experience Improvement Program, click Enable, or click Skip.
  3. The System > Deployment page is displayed. In the top right, click Deploy.
  4. Click Yes to reboot.
  5. After deployment, you can now use the Floating IP to manage the appliance.
  6. After the reboot, login again. You’ll see a Wizard to add instances.

After the add instance wizard is complete, you can manage High Availability.

  1. System > Deployment lets you see the HA nodes.
  2. You can Force Failover from here. Note: HA failover only occurs after three minutes of no heartbeats.
  3. On the top right is a HA Settings button that lets you change the Floating IP.

DR Node

Requirements for the DR node:

  • The main datacenter must have an HA pair of ADM appliances. Standalone in the main datacenter is not supported.
  • Latency from the main datacenter HA pair to the DR node must not exceed 200 ms.

To configure a DR node:

  1. Import another ADM appliance into a remote datacenter, and configure an IP address.
  2. If you added a second disk to the main datacenter ADM appliances, then you must add the same size second disk to the DR ADM  appliance.
  3. After configuring the new nodes’ IP address, SSH to the DR appliance and login as nsrecover/nsroot.
  4. Enter deployment_type.py.
  5. Enter 2 for Remote Disaster Recovery Node.
  6. Enter the Floating IP address of the HA pair in the main datacenter.
  7. Enter the nsroot password, which is nsroot by default.
  8. The DR node registers with the MAS HA Pair.
  9. Point your browser to the Floating IP Address and login.
  10. Go to System > System Administration.
  11. On the right, in the right column, click Disaster Recovery Settings.
  12. The Registered Recovery Node should already be filled in.
  13. Check the box next to Enable Disaster Recovery, and click Apply Settings.
  14. Click Yes to enable DR.
  15. A System Backup is performed and replicated to the DR appliance.
  16. Disaster Recovery is not automatic. See the manual DR procedure at at Citrix Docs.
    • /mps/scripts/pgsql/pgsql_restore_remote_backup.sh

ADM Agents

The virtual appliance for ADM Agent is different than the normal ADM appliance.

  1. Download the ADM Agent from the main ADM download page. Scroll down the page to find the ADM Agent images. Note: The ADM Agent has a newer build number than the ADM image due to a security vulnerability.
  2. Extract the downloaded .zip file.
  3. Import the .ovf to vSphere.

  4. Edit the settings of the virtual machine to see the allocated CPU and Memory.
  5. Power on the ADM Agent virtual machine.
  6. At the virtual machine’s console, configure an IP address.
  7. Login as nsrecover/nsroot.
  8. Run /mps/register_agent_onprem.py
  9. Enter the floating IP address of the main ADM HA Pair. Enter nsroot credentials.
  10. The Agent will be registered and services restarted.
  11. Login to the ADM Floating IP.
  12. Go to Networks > Agents.
  13. On the right, select the ADM Agent, and then click Attach Site.
  14. In the Site drop-down, if you don’t see your site, then you can click the Add button to create a new site.
  15. Enter a name, enter a search location, and click Get Location to get the coordinates. Click Create when done.
  16. Click Save to attach the site.
  17. For HA, import two ADM Agents into the same Site.

ADM Appliance Maintenance

Add Instances

Citrix ADM must discover Citrix ADC instances before they can be managed. Citrix Docs How Citix ADM discovers instances.

  1. Once you’ve built all of the nodes, point your browser to the Citrix ADM Floating IP address, and login as nsroot/nsroot.
  2. Deployment should already be done, so click Next.
  3. On the Add New Instances page, click Add Instance near the top right.
  4. Enter the NSIP address of a Citrix ADC appliance.
    • CItrix ADM supports up to 400 ms latency to the instances.
  5. Click Edit next to ns_nsroot_profile.
  6. Check the box next to Change Password.
  7. Type in the nsroot password, and then scroll down.
  8. The Citrix ADC Profile defaults to using https for instance communication. You can change it by unchecking Use global settings for Citrix ADC communication.
  9. Click OK.
  10. Select the Site for the instance. You can click Add to create a Site.
  11. For remote sites, you can optionally choose a ADM Agent.
  12. Then click OK to add the instance.
  13. A progress window will appear. Click Close when complete.
  14. You can add more instances, or just click Next.
  15. In the Customer Identity page, make your choice, then click Next or Skip.
  16. In the Done page, click Finish.

To add more instances later:

  1. Click the top left hamburger icon.
  2. Go to Networks > Instances > Citrix ADC.
  3. On the right, select a tab (e.g. MPX), and then click Add.
  4. To edit, or create new Admin Profiles, go to Networks > Instances > Citrix ADC, and on the right is a Profiles button.

  5. ADM 12.1 build 49 and newer lets you assign Tags to instances. See How to create tags and assign to instances at Citrix Docs.

  6. You can then search instances based on the Tags.

Citrix ADC SDX

  1. At Networks > Instances > Citrix ADC, on the SDX tab, you can click Add to discover a SDX appliance, and all VPXs on that SDX appliance. You don’t have to discover the VPXs separately.
  2. In the Add Citrix ADC SDX page, click the Edit button next to the Profile Name drop-down to edit nssdx_default_profile. Or you can click the Add button to create a new SDX Profile. Note: SDX profiles are different than VPX profiles.
  3. Enter the credentials for the SDX SVM Management Service.
  4. For Citrix ADC Profile, select an admin profile that has nsroot credentials for the VPX instances. After the VPXs are discovered, ADM uses the ADC Profile to login to each VPX. If you don’t have a VPX Admin Profile in your drop-down list, click the Add button. Note: You can only select one ADC Profile. If each VPX instance has different nsroot credentials, you can fix it after SDX discovery has been performed. The ADC Profile is different than the SDX Profile.

    1. In the Create Citrix ADC Profile page, enter the nsroot credentials for the VPX instances, and then scroll down.
    2. Enter a new SNMP Security Name or Community String.
    3. Then click Create.
  5. Back in the Configure ADC SDX Profile page, enter a new Community string for the SDX SVM. This appears to be SNMP v2 only.
  6. You can uncheck the box for Use global settings for SDX communication, and change the protocol.
  7. Click OK when done.
  8. Back in the Add Citrix ADC SDX page, select a Site, and optionally an Agent.
  9. Click OK to start discovery.
  10. After discovery is complete, switch to the VPX tab. You should automatically see the VPX instances.
  11. To specify the nsroot credentials for a VPX, right-click the VPX, and click Edit.

    1. In the Modify Citrix ADC VPX page, either select an existing Profile Name, or click the Add button to create a new one. Click OK when done. It should start rediscovery automatically.
  12. After fixing the nsroot credentials, right-click the VPX instance, and click Configure SNMP. ADM will configure the VPX to send SNMP Traps to ADM.

Instance management

  • REST API proxy – Citrix ADM can function as a REST API proxy server for its managed instances. Instead of sending API requests directly to the managed instances, REST API clients can send the API requests to Citrix ADM. See Citrix CTX228449 NetScaler MAS as an API Proxy Server
  • Citrix ADC VPX Check-In/Check-Out Licensing – You can allocate VPX licenses to Citrix ADC instances on demand from Citrix ADM. The Licenses are stored and managed by Citrix ADM, which has a licensing framework that provides scalable and automated license provisioning. A Citrix ADC VPX instance can check out the license from the Citrix ADM when a Citrix ADC VPX instance is provisioned, or check back in its license to Citrix ADM when an instance is removed or destroyed. See Citrix CTX228451 NetScaler VPX Check-In/Check-Out Licensing with NMAS

Licenses

Virtual Server License Packs

Without licenses, you can enable analytics features on only 30 Virtual Servers. You can install additional licenses in 100 Virtual Server packs. More info at Licensing at Citrix Docs.

  1. On the left, go to Networks > Licenses.
  2. On the right, notice the Host ID.
  3. At mycitrix.com, allocate your Citrix ADM licenses to this Host ID.
  4. Then use the Browse button to upload the allocated license file.
  5. Click Finish after uploading the license file to apply it.
  6. The License Expiry Information section shows you the number of installed licenses and when they expire.
  7. You can use the Notification Settings section to email you when licenses are almost fully consumed or about to expire.
  8. If you don’t have an Email server setup yet, click the Add button to create one.

Allocate licenses to Virtual Servers

You can manually unassign an automatically-allocated ADM Virtual Server license and reassign it to a different Virtual Server.

  1. Go to Networks> Licenses > System Licenses to see the number of currently installed licenses, and the number of managed virtual servers.
  2. By default, Auto-select Virtual Servers is enabled. If you disable this setting, then the Click to select button appears.
  3. Click the Click to select button.
  4. The top right shows you the number of licensed Virtual Servers.
  5. In the left, select the type of Virtual Server you want to unlicense or license.
  6. On the right, the License Type column indicates if the Virtual Server is licensed or not.
  7. Select a Virtual Server you want to license, and then click the Apply Basic License button. Note: you might have to unlicense a different Virtual Server first.
  8. Click Close when done.

Enable AppFlow / Insight / Analytics

  1. Go to Networks > Instances > Citrix ADC.
  2. On the right, switch to one of the instance type tabs (e.g. VPX).
  3. Select an instance, open the Select Action menu, and click Configure Analytics.
  4. At the top of the page are boxes you can check.
  5. Down the page, in the Application List section, with Load Balancing selected in the View list, select your StoreFront load balancer, and then click Enable AppFlow. If you don’t see your Virtual Server in this list, then you first need to assign a Virtual Server License.
  6. In the Enable AppFlow window, do the following:
    1. In the larger Expression box, type in true.
    2. For newer ADC appliances, change the Transport Mode selection to Logstream instead of IPFIX. Notice the firewall requirement for TCP port 5557.
    3. Select Web Insight.
    4. If App Firewall is enabled on the vServer, then also select Security Insight.
    5. Client Side Measurement injects JavaScript in HTTP responses to measure page load times and can sometimes cause problems in Receiver / Workspace app.
  7. Click OK.
  8. Use the View drop-down to select Citrix Gateway.
  9. Right-click a Citrix Gateway Virtual Server, and click Enable AppFlow.
  10. In the Enable AppFlow window, do the following:
    1. In the Select Expression drop-down, select true.
    2. For newer ADC appliances, change the Transport Mode to Logstream. Notice the firewall warning.
    3. Select both ICA and HTTP. The HTTP option is for Gateway Insight.
    4. The TCP option is for the second appliance in double-hop ICA. If you need double-hop, then you’ll also need to run set appflow param -connectionChaining ENABLED on both appliances. See Enabling Data Collection for NetScaler Gateway Appliances Deployed in Double-Hop Mode at Citrix Docs for more information.
    5. The AppFlow processing impact on the ADC is much reduced if you run VDA 7.16 or newer (including VDA 1903), Workspace app or Receiver 4.10 and newer, and ADC 12.0 build 57.24 or newer (including NetScaler 12.1). VDA 7.15 (LTSR) does not include the new AppFlow NSAP functionality. Details at Citrix Blog Post HDX Insight 2.0.
  11. Click OK.
  12. Login to the Citrix ADC (not ADM), and go to System > Settings.
  13. On the right, click Configure Modes.
  14. If you are using LogStream, then make sure ULFD is checked. Click OK.

    enable mode ulfd
  15. On the right, click Change Global System Settings.
  16. Scroll down to ICA port(s) and enter 1494 and 2598. Click OK. (Source = Citrix Discussions)

    set ns param -icaPort 1494 2598
  17. On the right, click Change HTTP Parameters.
  18. At the top, add 80 and 443 to the Http Ports list. Click OK. (Source = Citrix Discussions)

    set ns param -httpPort 80 443
  19. By default, with AppFlow enabled, if a ADC High Availability pair fails over, all Citrix connections will drop, and users must reconnect manually. NetScaler 11.1 build 49 and newer have a feature to replicate Session Reliability state between both HA nodes.
    1. From Session Reliability on NetScaler High Availability Pair at Citrix Docs: Enabling this feature will result in increased bandwidth consumption, which is due to ICA compression being turned off by the feature, and the extra traffic between the primary and secondary nodes to keep them in sync.
    2. On a NetScaler 11.1 build 49 and newer ADC appliance, go to System > Settings.
    3. On the right, in the Settings section, click Change ICA Parameters.
    4. Check the box next to Session Reliability on HA Failover, and click OK.
  20. In a NetScaler 12 or newer instance, at System > AppFlow > Collectors, you can see if the Collector (ADM) is up or not. However, ADC uses SNIP to verify connectivity, but AppFlow is sent using NSIP, so being DOWN doesn’t necessarily mean that AppFlow isn’t working. Citrix CTX227438 After NetScaler Upgrade to Release 12.0 State of AppFlow Collector Shows as DOWN.

  21. On the ADM appliance, AppFlow for ICA (HDX Insight) information can be viewed MAS under the Analytics > HDX Insight node.

Citrix Blog Post – NetScaler Insight Center – Tips, Troubleshooting and Upgrade

Enable Syslog on Instance

ADM can configure ADC instances to send Syslog to ADM. Note: this will increase disk space consumption on the ADM appliances.

  1. Go to Networks > Instances > Citrix ADC. On the right, select a tab..
  2. On the right, select an instance, open the Select Action drop-down, and click Configure Syslog.
  3. Uncheck All and check the other boxes. You probably don’t want Debug or None. Click OK.

ADM nsroot Password

Changing the nsroot password also changes the nsrecover password.

  1. In ADM , go to System > User Administration > Users.
  2. On the right, select the nsroot account, and click Edit.
  3. Check the box next to Change Password and enter a new password.
  4. You can also specify a session timeout by checking the box next to Configure Session Timeout.
  5. Click OK.

Management Certificate

The certificate to upload must already be in PEM format. If you have a .pfx, you must first convert it to PEM (separate certificate and key files). You can use a ADC to convert the .pfx, and then download the converted certificate from the appliance.

  1. Go to System > System Administration.
  2. On the right, in the Set Up Citrix ADM section, click Install SSL Certificate.
  3. Click Choose File to browse to the PEM format certificate and key files. If the keyfile is encrypted, enter the password. Click OK.
  4. Click Yes to reboot the system.

System Configuration

  1. Go to System > System Administration.
  2. On the right, modify settings (e.g. Change System Time Zone) as desired.

  3. Click Change System Settings.

    1. Check the box next to Enable Session Timeout, and specify a value.
    2. By default, at Networks > Instances > Citrix ADC , if you click a blue IP address link, it opens the instance in a new web page, and logs in automatically using the nsroot credentials. If you want to force ADM users to login using non-nsroot credentials, in Modify System Settings, check the bottom box for Prompt Credentials for Instance Login.

    3. Click OK when done.
  4. Configure SSL Settings lets you disable TLS 1 and TLS 1.1.

    1. Click the Protocol Settings section in the Edit Settings section on the right side of the screen.
    2. On the left, uncheck TLSv1 and TLSv1.1. Then click OK and Close.
    3. A restart is required.

Message of the Day

In ADM 12.1 build 50 and newer, you can configure a Message of the day.

  1. In ADM, on the left, go to System > System Administration.
  2. On the right, in the System Settings section, click Configure message of the day.
  3. Enter a message and click OK.
  4. When you login to ADM, you’ll be shown the message.

Prune Settings

  1. At System > System Administration, on the left are Prune Settings.
  2. System Prune Settings …

    1. …defaults to deleting System Events, Audit Logs, and Task Logs after 15 days. System events are generated by the MAS appliance, which is different than Instance events (SNMP traps) that are generated by ADC appliances.
    2. MAS can initiate a purge automatically as the database starts to get full.
    3. If you click the pencil next to the purge threshold value, you can configure an alarm for when the database gets full.

  3. To see the current database disk usage, go to System > Statistics.
  4. Instance Events prune Settings controls when instance SNMP traps are pruned, which defaults to 40 days.

  5. If you are sending Syslog from instances to MAS, Instance Syslog Purge Settings controls when the log entries are purged.

Backup Settings

  1. In the right column, under Backup Settings, are additional settings.
  2. System Backup Settings defines how many MAS backups you want to keep.

  3. Instance Backup Settings lets you configure how often the instances are backed up.

    1. You probably want to increase the number of instance backups, or decrease the backup interval.
    2. There is an option to perform a backup whenever the ADC configuration is saved.
    3. The Enable External Transfer checkbox lets you transfer the backups to an external system so it can be backed up by your backup tool.

Analytics Settings

  1. There are more settings at Analytics > Settings.
  2. ICA Session Timeout can be configured by clicking the link.

    • If ADM doesn’t receive AppFlow records for a session, it will consider that session has got terminated in ADC and stops monitoring that session further. The time for which ADM needs to wait before considering a session terminated is ICA session timeout. This is configurable in ADM, by default it is set to 15 minutes. (source = Citrix Discussions)
  3. You can configure how the App Score (Application Dashboard) is calculated.

  4. Analytics > Settings > Data Persistence lets you configure how long Analytics data is retained. Adjusting these values could dramatically increase disk space consumption. See CTX224238 How Do I Increase Granularity of Data Points Stored on NetScaler MAS Analytics?.

    • To see the current database disk usage, go to System > Statistics.

NTP Servers

  1. On the left, click System > NTP Servers.
  2. On the right, click Add.
  3. Enter an NTP server, and click Create.

  4. After adding NTP servers, click the NTP Synchronization button.
  5. Check the box next to Enable NTP Synchronization, and click OK.
  6. Click Yes to restart.

Syslog

This is for log entries generated by ADM, and not for log entries generated by instances.

  1. Go to System > Auditing > Syslog Servers.
  2. On the right, click Add.
  3. Enter the syslog server IP address, and select Log Levels. Click Create.
  4. You can click Syslog Parameters to change the timezone and date format.

Email Notification Server

  1. Go to System > Notifications > Email.
  2. On the right, on the Email Servers tab, click Add.
  3. Enter the SMTP server address, and click Create.
  4. On the right, switch to the Email Distribution List tab, and click Add.
  5. Enter an address for a destination distribution list, and click Create.
  6. In ADM 12.1 build 49 and newer, you can highlight a Distribution List and click the Test button.


  7. On the left, click System > Notifications.
  8. On the right, click Change Notification Settings.
  9. Move notification categories (e.g. UserLogin) to the right.
  10. Check the box next to Send Email. Select a notification distribution list. Then click OK.

Authentication

  1. Go to System > Authentication > LDAP.
  2. On the right, click Add.
  3. This is configured identically to ADC.
    1. Enter a Load Balancing VIP for LDAP.
    2. Change the Security Type to SSL, and Port to 636. Scroll down.
    3. Enter the Base DN in LDAP format.
    4. Enter the bind account credentials.
    5. Check the box for Enable Change Password.
    6. Click Retrieve Attributes, and scroll down.
    7. For Server Logon Attribute, select sAMAccountName.
    8. For Group Attribute, select memberOf.
    9. For Sub Attribute Name, select cn.
    10. To prevent unauthorized users from logging in, configure a Search Filter. Scroll down.
    11. If desired, configure Nested Group Extraction.
  4. Click Create.
  5. On the left, go to System > User Administration > Groups.
  6. On the right, click Add.

    1. Enter the case sensitive name of your Citrix ADC Admins AD group.
    2. Move the admin Permission to the right.
    3. The Configure User Session Timeout checkbox lets you configure a session timeout.
    4. Click Next.
    5. On the Authorization Settings page, if you are delegating limited permissions, you can uncheck these boxes and delegate specific entities.
      • All DNS Domain Names (GSLB) is an option for Stylebooks in ADM 12.1 build 49 and newer.
    6. Click Create Group.
    7. In the Assign Users page, click Finish. Group membership comes from LDAP, so there’s no need to add local users.
  7. On the left, go to System > User Administration.
  8. On the right, click User Lockout Configuration.
  9. If desired, check the box next to Enable User Lockout, and configure the maximum logon attempts. Click OK.
  10. On the left, go to System > Authentication.
  11. On the right, click Authentication Configuration.
  12. Change the Server Type to EXTERNAL, and click Insert.
  13. Select the LDAP server you created, and click OK.
  14. Make sure Enable fallback local authentication is checked, and click OK.

Analytics Thresholds

  1. Go to Analytics > Settings > Thresholds.
  2. On the right, click Add.
  3. Enter a name.
  4. Use the Traffic Type drop-down to select HDX, WEB, SECURITY, or APPANALYTICS.
  5. Use the Entity drop-down to select a category of alerts. What you choose here determines what’s available as Metrics when you click Add Rule.
    1. With HDX as the Traffic Type, to add multiple rules for multiple Entity types, simply change the Entity drop-down before adding a new rule.
    2. If the Traffic Type is HDX, and the Entity drop-down is set to Users, on the bottom in the Configure Geo Details section, you can restrict the rule so it only fires for users for a specific geographical location.

  6. In the Notification Settings section, check the box to Enable Treshold.
  7. Check the box to Notify through Email, and select an existing Email Distribution List.
  8. Click Create.

Private IP Blocks

You can define Geo locations for internal subnets.

  1. Go to Analytics > Settings > IP Blocks.
  2. On the right, click Add.
  3. In the Create IP Blocks page:
    1. Enter a name for the subnet.
    2. Enter the starting and ending IP address.
    3. Select a Geo Location (Country, Region, City). As you change the fields, the coordinates are automatically filled in.
  4. Click Create.

Instance Email Alerts (SNMP Traps)

You can receive email alerts whenever a ADC appliance sends a critical SNMP trap.

  1. On the left, go to Networks > Events > Rules.
  2. On the right, click Add.
  3. Give the rule a name.
  4. Move Severity filters (e.g. Major, Critical) to the right by clicking the plus icon next to each Severity.
  5. While scrolling down, you can configure additional alert filters. Leaving them blank will alert you for all categories, objects, and instances.
  6. On the bottom of the page, in the Event Rule Actions section, click Add Action.
  7. In the Add Event Action page:
    1. Select an Action Type (e.g. Send e-mail Action).
    2. Select the recipients (or click the Add button to add recipients).
    3. Optionally, enter a Subject and/or Message.
    4. In ADM 12.1 build 49 and newer, if you enter a Subject, you can check Prefix severity, category, and failure object information to the custom email subject.
    5. Emails can be repeated by selecting Repeat Email Notification until the event is cleared.
  8. Click OK.
  9. Then click Create.
  10. See the Event Management section at All how to articles at Citrix Docs.

Events Digest

ADM can email you a daily digest (PDF format) of system and instance events

To enable the daily digest:

  1. Go to System > Notifications.
  2. On the right, click Configure Event Digest Settings.
  3. Uncheck the box next to Disable Event Digest.
  4. Configure the other settings as desired, and click OK.

Director Integration

Integrating Citrix ADM with Director adds Network tabs to Director’s Trends and Session Details views. Citrix Blog Post Configure Director with Netscaler Management & Analytics System (MAS)

Requirements:

  • Citrix Virtual Apps and Desktops (CVAD) must be licensed for Platinum Edition. This is only required for the Director integration. Without Platinum, you can still access the HDX Insight data by going visiting the Citrix ADM website.
  • Director must be 7.11 or newer for Citrix ADM support.

To link Citrix Director with Citrix ADM:

  1. On the Director server, run C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /confignetscaler.
  2. Enter the Citrix ADM nsroot credentials.
  3. If HTTPS Connection (recommended), the Citrix ADM certificate must be valid and trusted by both the Director Server and the Director user’s browser.
  4. Enter 1 for Citrix ADM (aka MAS).
  5. Do this on both Director servers.

Use Citrix ADM

Networks

Everything under the Networks node is free.

At Networks > Instances, select an instance, and view its Dashboard.

ADM 12.1 adds a series of tabs to the Instance Dashboard.

Backups are available by selecting an instance, and clicking Backup/Restore.

Infrastructure Analytics. The ADM Cloud Service has an Infrastructure Analytics node under the Networks node. For details, see Infrastructure Analytics at Citrix Docs.

  • On the right, if you click the gear icon above the table, then the right panel changes to the Settings Panel instead of the Summary Panel. In the right panel, you can then switch to the tab named Score Thresholds to adjust how Infrastructure Analytics scores instance CPU, Memory, Disk, etc.
  • You can click the Circle Pack button to change to the Circle Pack view.

Networks > Network Reporting lets you create Dashboards where you can view Instance performance data.

Networks > Network Reporting > Thresholds lets you create thresholds when counters cross a threshold. For example, you might want a notification when Throughput gets close to the licensed limit.

Configuration Record and Play

Use ADM to record a configuration change on one instance, and push to other instances.

  1. Go to Networks > Configuration Jobs.
  2. On the right, click Create Job.
  3. Change the Configuration Source drop-down to Record and Play.
  4. Change the Source Instance drop-down to the instance you want to record.
  5. Click Record.
  6. ADM opens the instance GUI. Make changes as desired.
  7. When done, go back to ADC, and click Stop.
  8. ADC retrieves the changed config.
  9. On the left, you’ll see the changed commands. Drag them to the right.
  10. On the right, you can change instance-specific values to variables by simply highlighting the values. This allows you to change the values for each instance you push this config to.
  11. Proceed through the rest of the Configuration Job wizard like normal. You’ll select instances, specify variable values for each instance, and schedule the job.

Dave Brett Automating Your Netscaler 11.1 Vserver Config Using Netscaler Management and Analytics System uses a Configuration Job to deploy StoreFront load balancing configuration to an instance.

Analytics and Applications

This functionality requires Virtual Server licenses, which can come from your built-in 30 free licenses.

The AppFlow Analysis tools (e.g. HDX Insight) are located under the Analytics node. See Viewing HDX Insight Reports and Metrics at Citrix Docs.

Applications > Dashboard automatically includes all licensed Virtual Servers in the Others section. On the top middle, click Define Custom App to group Virtual Servers together into an application. The grouped Virtual Servers are removed from the Others list.

Applications > Configurations > Stylebooks lets you use Stylebooks to create new ADC configurations.

There are built-in Stylebooks for Exchange, SharePoint, Oracle, ADFS, etc. Or you can create your own Stylebook and use it to create ADC configurations. For details, see Stylebooks at Citrix Docs.

The Applications Node has quite a bit of functionality. See Application Analytics and Management at Citrix Docs for details.

Link:

HDX Insight

HDX Insight Dashboard displays ICA session details including the following:

  • WAN Latency
  • DC Latency
  • RTT (round trip time)
  • Retransmits
  • Application Launch Duration
  • Client Type/Version
  • Bandwidth
  • Licenses in use

Citrix CTX215130 HDX Insight Diagnostics and Troubleshooting Guide contains the following contents:

  • Introduction
  • Prerequisites for Configuring HDX Insight
  • Troubleshooting
    • Issues Related to ICA parsing
    • Error Counter details
  • Checklist before Contacting Citrix Technical Support
  • Information to collect before Contacting Citrix Technical support
  • Known Issues

Gateway Insight

In the Analytics node is Gateway Insight.

This feature displays the following details:

  • Gateway connection failures due to failed EPA scans, failed authentication, failed SSON, or failed application launches.
  • Bandwidth and Bytes Consumed for ICA and other applications accessed through Gateway.
  • # of users
  • Session Modes (clientless, VPN, ICA)
  • Client Operating Systems
  • Client Browsers

More details at Gateway Insight at Citrix Docs.

Security Insight

The Security Insight dashboard uses data from Application Firewall to display Threat Index (criticality of attack), Safety Index (how securely ADC is configured), and Actionable Information. More info at Security Insight at Citrix Docs.

Troubleshooting

Citrix CTX215130 HDX Insight Diagnostics and Troubleshooting Guide: Syslog messages; Error counters; Troubleshooting checklist, Logs

Citrix CTX224502 NetScaler MAS Troubleshooting Guide

Upgrade Citrix ADM

  1. For MAS 12.0 build 56 and older, you must upgrade to MAS 12.0 build 57.24 before you can upgrade to ADM 12.1. (Source = Before you upgrade at Citrix Docs)
  2. Download the latest Citrix Application Delivery Management (NetScaler MAS) Upgrade Package. You want the ADM Upgrade Package, not a ADM image. It’s around halfway down the page.
  3. Login to Citrix ADM Floating IP or Active Node. Upgrading the Active Node automatically upgrades the Passive Node.
  4. Go to System > Deployment and make sure both nodes are online and replicating.
  5. Go to System > System Administration.
  6. On the right, in the right pane, click Upgrade Citrix ADM.
  7. Browse to the build-mas-12.1…tgz Upgrade Package, and click OK. The file name starts with build-mas-12.1.
  8. Click Yes to reboot the appliance.



  9. After it reboots, login.
  10. If you upgraded from a version older than 12.1 build 50 to a version 12.1 build 50 or newer, you might be prompted to Configure Customer Identity. Make your choice.

    • You can return to the Configure Customer Identity screen by clicking the cloud icon next to your username at the top right of the page.
  11. The new firmware version will be displayed by clicking your username in the top right corner.

Upgrade Disaster Recovery Node

After you upgrade the HA pair in the primary datacenter, you can upgrade the DR node.

  1. Use WinSCP or similar to connect to the DR node using the nsrecover credentials.
  2. On the ADM DR node, navigate to /var/mps/mps_images.
  3. Create a new Directory with the same name as the 12.1 build number. Then double-click the new directory to open it.

  4. Upload the file named build-mas-12.1-##.##.tgz to the version-specific directory. This is the regular ADM upgrade file with a name starting with build-mas-12.1. It’s not the Agent upgrade file.
  5. SSH (Putty) to the DR node and login as nsrecover.
  6. Enter the following. Replace the # with the version number. 
    cd /var/mps/mps_images/12.1.##.##
tar xvzf build-mas-12.1-##.##.tgz

  7. Then enter the following. The appliance will reboot automatically. 
    ./installmas

  8. After the reboot, the file /var/mps/log/install_state…
  9. …shows you the installed version.

Upgrade ADM Agents

After you upgrade the ADM HA pair in the primary datacenter, and after you upgrade the DR node, you can then upgrade the ADM Agents.

  1. From the ADM 12.1 download page, at the bottom of the page, download the ADM Agent Upgrade Package. This Agent Upgrade file is different than the regular ADM upgrade file. And it is different than the files to deploy a new Agent. Find it at the bottom of the downloads page. Note that Citrix updated the ADM Agent firmware to build 50.33 or higher to resolve a security vulnerability.
  2. Use WinSCP or similar to connect to the ADM Agent using the nsrecover credentials.
  3. On the ADM Agent, navigate to /var/mps/mps_images.
  4. Create a new Directory with the same name as the 12.1 build number. Then double-click the new directory to open it.

  5. Upload the file named build-masagent-12.1-##.##.tgz to the version-specific directory. This is the ADM Agent upgrade file, and not the regular ADM upgrade file.
  6. SSH (Putty) to the ADM Agent and login as nsrecover.
  7. Enter the following. Replace the # with the version number. 
    cd /var/mps/mps_images/12.1.##.##
tar xvzf build-masagent-12.1-##.##.tgz

  8. Then enter the following. The appliance will reboot automatically. 
    ./installmasagent

  9. After the reboot, the file /var/mps/log/install_state…
  10. …shows you the installed version.
  11. Repeat for any additional ADM Agents.
  12. If you login to ADM and go to Networks > Agents, you should see the new Version. It will take several minutes for the version number to update.

NetScaler SDX 12 / Citrix ADC SDX 12.1

Last Modified: Dec 21, 2018 @ 5:49 pm

65 Comments

Navigation

Change Log

  • 2018 Dec 21 – updated screenshots for SDX 12.1
  • 2018 Mar 20 – updated upgrade instructions for 12.0 build 57
  • 2018 Mar 20 – in Provision VPX section, added Crypto Units info

Overview

Citrix CTX226732 Introduction to Citrix NetScaler SDX.

Citrix ADC SDX is normal Citrix ADC hardware, but runs XenServer hypervisor, and several virtual machines that are listed below:

  • Service VM (aka Management Service, aka SVM) – every SDX comes with this Virtual Machine. This VM enables the SDX Administrator to create additional VMs on XenServer. It’s analogous to vCenter, except each SDX has its own SVM.
    • It’s not possible to build this VM yourself. If it something happens to it, your only choice is to do a factory reset on the physical appliance, which deletes all local virtual machines, and recreates the Service VM.
    • Each Service VM only manages the VMs on the local SDX. Each SDX has its own Service VM. To manage multiple SDXs, use Citrix Application Delivery Management (ADM).
    • XenServer on SDX is a special build. Do not attempt to directly upgrade XenServer, patch XenServer, configure XenServer, etc. Instead, all upgrades and configurations should be performed by the Service VM.
  • Citrix ADC VPX Instances – you create one or more Citrix ADC instances on top of XenServer.
    • The number of Citrix ADC instances you can create is limited by your SDX license. Most models let you buy more instances.
    • The physical resources (CPU, Memory, NICs, SSL Chips, FIPS HSM) of the SDX are partitioned to the different instances.
    • The amount of bandwidth (throughput) available to the VPX instances depends on your license. For example, the 14040 SDX license gives you 40 Gbps of throughput, which is partitioned across the instances.
    • The Citrix ADC instances are created from a normal XenServer .xva template.
    • Each VPX has its own NSIP. Once the VPX is provisioned, you connect to the NSIP, and configure it like a normal Citrix ADC .

If the top left of the window says SDX, then you are logged into the Management Service (aka Service VM, aka SVM). If it says VPX, then you are logged into an instance.

High Availability – Citrix ADC SDX does not have any High Availability capability at the XenServer or SVM layer. In other words, every SDX is completely standalone. To achieve HA, you create Citrix ADC VPX instances on two separate SDXs, and pair the VPX instances in the normal fashion. See Citrix ADC High Availability.

Why Citrix ADC VPX on top of SDX instead of normal hypervisors?

  • VPX on SDX gets physical access to SSL chips. These SSL ASICs are not available on normal hypervisors. SSL Chips provide significantly higher SSL throughput than normal hypervisors.
  • VPX on SDX gets SR-IOV access to the Network interfaces. This enables full 40 Gbps throughput to a single VM.
  • The SDX NICs can filter VLANs to different instances, thus ensuring that VPX instances cannot cross security boundaries by adding the wrong VLANs.
  • Some SDXs have Hardware Security Modules (HSM) for FIPS compliance. The VPXs on SDX can utilize this hardware security resource.

SDX Networking

  • Management port – Every SDX has a 0/1 port.
    • The SVM and XenServer management IP are on this NIC.
    • You need a minimum of two IPs on a management network connected to the 0/1 port.
    • SVM and XenServer cannot use any of the data ports for management.
  • LOM port – Every SDX has a Lights Out Management (LOM) port.
    • The LOM port gives you out-of-band console access to XenServer. Once you’re on XenServer, you can use Xen commands to see the SVM console, and/or VPX consoles.
  • Data ports – The remaining interfaces can be aggregated into port channels. Port channels are configured at XenServer, and not from inside the VPXs. Use the Service VM to create channels, and then connect the VPXs to the channels.
  • VPX networking – When VPXs are created, you specify which physical ports to connect the virtual machine to.
    • If you want the VPX NSIP to be on the same subnet as SVM and XenServer, then connect the VPX to 0/1.
    • Connect the VPX to one or more LA/x interfaces (port channels).
    • Once the VPX is created, log into it, and create VLAN objects in the normal fashion. VLAN tagging is handled by the VPX, not XenServer.
    • On SVM, when creating the VPX instance, you can specify a list of allowed VLANs. The VPX administrator is only allowed to add VLANs that are in this list.
  • SVM to NSIP – SVM must be able to communicate with every VPX NSIP. If VPX NSIP is on a different subnet than SVM, then ensure that routing/firewall allows this connection.

LOM IP Configuration

There are two ways to set the IP address of the Lights Out Module (LOM):

  • ipmitool from the Citrix ADC SDX XenServer command line
    • For MPX, you can run ipmitool from the BSD shell.
  • Crossover Ethernet cable from a laptop with an IP address in the 192.168.1.0 network.

Ipmitool Method:

  1. For SDX, SSH to the XenServer IP address (not the Service VM IP).
    • For MPX, SSH to the Citrix ADC NSIP.
  2. Default XenServer credentials are root/nsroot.
    1. Default MPX credentials are nsroot/nsroot.
  3. If MPX, run shell. XenServer is already in the shell.
  4. Run the following: 
    ipmitool lan set 1 ipaddr x.x.x.x
ipmitool lan set 1 netmask 255.255.255.0
ipmitool lan set 1 defgw ipaddr x.x.x.x

  5. You should now be able to connect to the LOM using a browser.

Laptop method:

  1. Configure a laptop with static IP address 192.168.1.10 and connect it to the Lights Out Module port.
  2. In a Web browser, type the IP address of the LOM port. For initial configuration, type the LOM port’s default address: http://192.168.1.3
  3. In the User Name and Password boxes, type the administrator credentials. The default username and password are nsroot/nsroot.
  4. In the Menu bar, click Configuration, and then click Network.
  5. Under Options, click Network, and type values for the following parameters:
    1. IP Address—The IP address of the LOM port.
    2. Subnet Mask—The mask used to define the subnet of the LOM port.
    3. Default Gateway—The IP address of the router that connects the appliance to the network.
  6. Click Save.
  7. Disconnect the laptop, and instead connect a cable from a switch to the Lights Out Module.

LOM Firmware Upgrade

The LOM firmware at https://www.citrix.com/downloads/netscaler-adc/components/lom-firmware-upgrade differs depending on the hardware platform. The LOM firmware for the 8000 series is different than the 11000 series and the 14000 series. Do not mix them up.

SDX 12.0 build 57 and newer automatically upgrade the LOM firmware when you upgrade the SDX firmware.

Citrix ADC MPX has a new method for updating LOM as detailed at CTX218264 How to Upgrade the LOM Firmware on Any NetScaler MPX Platform

For SDX firmware older than 12.0 build 57, update the LOM firmware separately:

  1. Determine which firmware level you are currently running. You can point your browser to the LOM and login to the see the firmware level. Or you can run ipmitool mc info from the XenServer shell.
  2. If your LOM firmware is older than 3.0.2, follow the instructions at http://support.citrix.com/article/CTX137970 to upgrade the firmware.
  3. If your LOM firmware is version 3.02 or later, follow the instructions at http://support.citrix.com/article/CTX140270 to upgrade the firmware. This procedure is shown below.
  4. Now that the firmware is version 3.0.2 or later, you can upgrade to 3.39. Click the Maintenance menu and then click Firmware Update.
  5. On the right, click Enter Update Mode.
  6. Click OK when prompted to enter update mode.
  7. Click Choose File, and browse to the extracted bin file.
  8. After the file is uploaded, click Upload Firmware.
  9. Click Start Upgrade.
  10. The Upgrade progress will be displayed.
  11. After upgrade is complete, click OK to acknowledge the 1 minute message.
  12. The LOM will reboot.
  13. After the reboot, login and notice that the LOM firmware is now 3.39.

SDX IP Configuration

Default IP for Management Service is 192.168.100.1/16 bound to interface 0/1. Use a laptop with crossover cable to reconfigure the IP. Point your browser to http://192.168.100.1. Default login is nsroot/nsroot.

Default IP for XenServer is 192.168.100.2/16. Default login is root/nsroot.

  • There should be no need to connect to XenServer directly. Instead, all XenServer configuration (e.g. create new VM) is performed through the Management Service (SVM).
  • When you set the SVM’s IP Address, there is also a field to also set the XenServer IP address. XenServer IP and Management Service IP must be on the same subnet.

To change the XenServer IP, make the change through the SVM as detailed below:

  1. Point a browser to http://192.168.100.1, and login as nsroot/nsroot.
  2. When you first login to the SDX Management Service, the Welcome! Wizard appears. Click the first row for Management Network.
  3. Configure the IP addresses.
    1. Appliance Management IP = SVM (Management Service). This is the IP you’ll normally use to manage SDX.
    2. Application supportability IP = XenServer. You’ll almost never connect to this IP.
    3. The bottom has an Additional DNS checkbox that lets you enter more DNS servers.
    4. You can change the nsroot password at this time, or change it later after LDAP is configured.
  4. Click Done.
  5. Click the System Settings box.
  6. Enter a Host Name.
  7. Select the time zone, and click Continue.
  8. Click the Licenses box.
  9. Click Add License File.
  10. Allocate Citrix ADC SDX licenses normally.
    1. The SDX license defines the number of instances you can create.
    2. It also defines the amount of throughput available to the instances.
    3. The SDX license is allocated to ANY, which means you can use the same license on all SDX hardware, assuming all of them are purchased with the same license model.
  11. Click Browse to upload the license file. After uploading, click Finish and it should apply automatically.
  12. Or you can click Apply Licenses.
  13. Then click Continue.

Another way to change the Management Service IP address is through the serial port. This is actually the XenServer Dom0 console. Once logged in to XenServer, run ssh 169.254.0.10 to access the Management Service virtual machine. Then follow instructions at http://support.citrix.com/article/CTX130496 to change the IP.

The console of the Management Service virtual machine can be reached by running the following command in the XenServer Dom0 shell (SSH or console):

xe vm-list params=name-label,dom-id name-label="Management Service VM"

Then run /usr/lib64/xen/bin/xenconsole <dom-id>

SDX Platform Software Bundle

If your Citrix ADC SDX is not version 11 or newer, and if your Citrix ADC SDX is running 10.5 build 57 or later, then do the following:

  1. Go to Management Service > Software Images, and upload the Single Bundle for 12.0 or 12.1. The single bundle is around 1.5 GB.
  2. On the left, click System.
  3. On the right, click Upgrade Management Service. Select the Single Bundle upgrade file you already uploaded.
  4. Management Service will upgrade and reboot. A few minutes after that, XenServer will be upgraded. Be patient as there’s no notification that the box will reboot again.

Starting with SDX 11.0, all updates are bundled together and installed at once.

  1. Make sure your Management Service (SVM) is running SDX 10.5 build 57 or newer.
  2. Download the latest SDX Platform Software bundle from Downloads > Citrix ADC > Release 12.1 (or 12.0) > Service Delivery Appliances.

  3. Login to the SDX Management Service, and go to Configuration > System.
  4. On the right, in the right column, click Upgrade Appliance.
  5. Browse to the build-sdx-12.1.tgz software bundle, and click OK.
  6. It should show you the estimated installation time.
  7. Check boxes next to the instances that need configs saved.
  8. Click Upgrade.
  9. Click Yes to continue with the upgrade.
  10. The Management Service displays installation progress. It will take a while.
  11. Once the upgrade is complete, click Login.

  12. If you click the Configuration tab, the Information page will be displayed showing the version of XenServer, Management Service (Build), etc.

FIPS

If your SDX is a FIPS appliance, see Citrix Blog Post Meet Security Compliance and Be Scalable with NetScaler FIPS SDX for detailed HSM setup instructions:

  1. Zeroize the HSM
  2. Upgrade HSM firmware
  3. Create HSM partitions
  4. Create Citrix ADC instance and attach HSM partition:
    • Only one CPU core
  5. From inside Citrix ADC instance:
    1. Reset FIPS
    2. Initialize FIPS
    3. Create FIPS Key
    4. Create HA Pair and synchronize FIPS

DNS Servers

Older versions of SDX only let you enter one DNS server. To add more, do the following:

  1. In the Management Service, on the left, click System.
  2. On the right, click Network Configuration.
  3. On the bottom, there’s a checkbox for Additional DNS that lets you put in more DNS servers.
  4. Click OK when done.

Management Service NTP

  1. On the Configuration tab, in the navigation pane, expand System, and then click NTP Servers.
  2. To add a new NTP server, in the right pane, click Add.
  3. In the Create NTP Server dialog box, enter the NTP server name (e.g. pool.ntp.org), and click Create.
  4. Click Yes when prompted to restart NTP Synchronization.
  5. In the right pane, click NTP Synchronization.
  6. In the NTP Synchronization dialog box, select Enable NTP Sync. Click OK.
  7. Click Yes when asked to restart the Management Service. This only restarts the SVM. Other instances on the same box won’t be affected.

Licensing

If you haven’t already licensed your SDX, you can upload a license file to the SDX appliance.

  1. Login to http://mycitrix.com and go to Manage Licenses.
  2. In the New Licenses section, find a Citrix ADC SDX license, and allocate it. There is no need to specify a hostname. You can use the same license file on multiple SDX appliances.

  3. On the SDX Configuration tab, in the navigation pane, expand System, and then click Licenses.
  4. In the right pane, click Add License File.
  5. Click Browse and upload the allocated license file.
  6. Click Finish.
  7. If you refresh your browser, the number shown on the top left of the window will indicate your licensed model number.

Management Service Alerting

Syslog

  1. On the Configuration tab, expand System > Auditing, and click Syslog Servers.
  2. In the right pane, click the Add button.

    1. Enter a name for the Syslog server.
    2. Enter the IP address of the Syslog server.
    3. Change the Choose Log Level section to Custom, and select log levels.
  3. Click Create.
  4. On the right is Syslog Parameters.
  5. You can configure the Date Format and Time Zone. Click OK.

Mail Notification

  1. On the Configuration tab, expand System > Notifications, and click Email.
  2. In the right pane, on the Email Servers tab, click Add.
  3. Enter the DNS name of the mail server, and click Create.
  4. In the right pane, switch to the tab named Email Distribution List, and click Add.
  5. In the Create Email Distribution List page:
    1. Enter a name for the mail profile.
    2. Select the Email Server to use.
    3. Enter the destination email address (distribution list).
  6. Click Create.
  7. SDX 12.1 and newer has a Test button for the Distribution List.

System SNMP

  1. Go to System > SNMP.
  2. On the right, click Configure SNMP MIB.
  3. Enter asset information, and click OK. Your SNMP management software will read this information.
  4. Under the SNMP node, configure normal SNMP including: Trap Destinations, Managers, Alarms, etc.

  5. MIBs can be downloaded from the Downloads tab.

Instance SNMP

  1. The instances will send SNMP traps to the Service VM. To get alerted for these traps, in the Configuration page, in the navigation pane, expand Citrix ADC (or NetScaler), expand Events, and click Event Rules.
  2. On the right, click Add.

    1. Give the rule a name.
    2. Move the Major and Critical severities to the right.
    3. Scroll down.
    4. For the other sections, if you don’t configure anything then you will receive alerts for all of the devices, categories, and failure objects. If you configure any of them, then only the configured entities will be alerted.
    5. Scroll down.
    6. Click Save.
  3. Select an Email Distribution List, and click Done.

Management Service nsroot Password and AAA

Change nsroot password

  1. On the Configuration tab, in the navigation pane, expand System, expand User Administration, and then click Users.
  2. On the right, in the Users pane, right-click the nsroot user account, and then click Edit.
  3. In the Configure System User dialog box, check the box next to Change Password.
  4. In Password and Confirm Password, enter the password of your choice.
  5. Scroll down and click OK.

AAA Authentication

To enable LDAP authentication for the Service VM:

  1. Go to Configuration > System > Authentication > LDAP.
  2. In the right pane, click Add.
  3. This is configured identically to Citrix ADC.
    1. Enter a Load Balancing VIP for LDAP servers.
    2. Change the Security Type to SSL, and Port to 636.
    3. Scroll down.
    4. Note: if you want to Validate LDAP Certificate, then there are special instructions for installing the root certificate on the SVM. See Installing CA certificates to the SDX/SVM for LDAPS user authentication at Citrix Discussions for details.
    5. Enter the Base DN in LDAP format.
    6. Enter the bind account in UPN format, or Domain\Username format, or DN format.
    7. Check the box for Enable Change Password.
    8. Click Retrieve Attributes, and scroll down.
    9. For Server Logon Attribute, select sAMAccountName.
    10. For Group Attribute, select memberOf.
    11. For Sub Attribute Name, select CN.
    12. To prevent unauthorized users from logging in, configure a Search Filter as detailed in the LDAP post. Scroll down.
  4. Click Create.
  5. Expand System, expand User Administration, and click Groups.
  6. On the right, click Add.
  7. In the Create System Group page:
    1. Enter the case sensitive name of the Active Directory group.
    2. Check the box next to System Access.
    3. Configure the Session Timeout.
  8. Click Create.
  9. On the left, under System, click User Administration.
  10. On the right, click User Lockout Configuration.

    1. If desired, check the box next to Enable User Lockout, and configure the maximum logon attempts. Click OK.
  11. On the left, under System, click Authentication.
  12. On the right, click Authentication Configuration.

    1. Change the Server Type drop-down to EXTERNAL, and click Insert.
    2. Select the LDAP server you created earlier, and click OK.
    3. Make sure Enable fallback is enabled, and click OK.

SSL Certificate and Encryption

Replace SDX Management Service Certificate

To replace the Management Service certificate:

  1. PEM format: The certificate must be in PEM format. The Management Service does not provide any mechanism for converting a PFX file to PEM. You can convert from PFX to PEM by using the Import PKCS#12 task in a Citrix ADC instance.
  2. On the left, click System.
  3. On the right, in the left column, in the Set Up Appliance section, click Install SSL Certificate.
  4. Select the certificate and key files in PEM format. If the key file is encrypted, enter the password. Then click OK.
  5. The Management Service will restart. Only the SVM restarts; the Citrix ADC instances do not restart.


Force HTTPS to the Management Service

  1. Connect to the SVM using HTTPS. You can’t make this upcoming change if you are connected using HTTP.
  2. On the Configuration tab, click System.
  3. On the right, click Change System Settings.
  4. Check the box next to Secure Access Only, and click OK. This forces you to use HTTPS to connect to the Management Service.

SSL Encrypt Management Service to Citrix ADC Communication

From http://support.citrix.com/article/CTX134973: Communication from the Management Service to the Citrix ADC VPX instances is HTTP by default. If you want to configure HTTPS access for the Citrix ADC VPX instances, then you have to secure the network traffic between the Management Service and Citrix ADC VPX instances. If you do not secure the network traffic from the Management Service configuration, then the Citrix ADC VPX Instance State appears as Out of Service and the Status shows Inventory from instance failed.

  1. Log on to the Management Service .
  2. On the Configuration tab, click System.
  3. On the right, click Change System Settings.
  4. Change the Communication with NetScaler Instance drop-down to https, as shown in the following screen shot:
  5. Run the following command on the Citrix ADC VPX instance, to change the Management Access (-gui) to SECUREONLY: 
    set ns ip ipaddress -gui SECUREONLY
  6. Or in the Citrix ADC instance management GUI, go to Network > IPs, edit the NSIP, and then check the box next to Secure access only.

SDX/XenServer LACP Channels

For an overview of Citrix ADC SDX networking, see Citrix CTX226732 Introduction to Citrix NetScaler SDX

To use LACP, configure Channels in the Management Service, which creates them in XenServer. Then when provisioning an instance, connect it to the Channel.

  1. In the Management Service, on the Configuration tab, expand System, and click Channels.
  2. On the right, click Add.
  3. In the Create Channel page:
    1. Select a Channel ID.
    2. For Type, select LACP or STATIC. The other two options are for switch independent load balancing.
    3. In the Interfaces section, move the Channel Member interfaces to the right by clicking the right arrow.
    4. In the Settings section, for LACP you can select Long or Short, depending on switch configuration. Long is the default.
  4. Click Create when done.
  5. Click Yes when asked to proceed.
  6. The channel will then be created on XenServer.

VPX Instances – Provision

Admin profile

Admin profiles specify the nsroot user credentials for the instances. Management Service uses these nsroot credentials later when communicating with the instances to retrieve configuration data.

The default admin profile for an instance specifies a user name of nsroot, and the password is also nsroot. To specify a different nsroot password, create a new admin profile.

  • You can create a single admin profile that is used by all instances. To delegate administration, don’t give out the nsroot password to the instance administrators. One option is to enable LDAP inside the instance before granting access to a different department.
  • When creating an instance, there’s an option to create a non-nsroot account, which has almost the same permissions as nsroot, but leaves out some SDX specific features (e.g interfaces). This is another option for delegating administration to a different team.
  • Or you can create different admin profiles for different instances, which allows you to inform the different departments the nsroot password for their VPX instances.

Important: Do not change the password directly on the Citrix ADC VPX instance. If you do so, the instance becomes unreachable from the Management Service. To change a password, first create a new admin profile, and then modify the Citrix ADC instance, selecting this profile from the Admin Profile list.

  1. On the Configuration tab, in the navigation pane, expand Citrix ADC (or NetScaler), and then click Admin Profiles.
  2. In the Admin Profiles pane, click Add.
  3. In the Create Admin Profile dialog box, set the following parameters:
    • Profile Name*—Name of the admin profile.
    • User Name—User name used to log on to the Citrix ADC instances. The user name of the default profile is nsroot and cannot be changed.
    • Password*—The password used to log on to the Citrix ADC instance. Maximum length: 31 characters.
    • Confirm Password*—The password used to log on to the Citrix ADC instance.
    • Use global settings for NetScaler communication – you can uncheck this box and change the protocol to https.
  4. Click Create. The admin profile you created appears in the Admin Profiles pane.

Upload a Citrix ADC VPX .xva file

You must upload a Citrix ADC VPX .xva file to the SDX appliance before provisioning the Citrix ADC VPX instances. XVA files are only used when creating a new instance. Once the instance is created, use normal firmware upgrade procedures.

  1. Go to the Citrix ADC VPX download page.
  2. Download the Citrix ADC VPX for XenServer.
  3. After downloading, extract the .gz file (use 7-zip). You can’t upload the .gz file to SVM. You must extract it first.
  4. On the Configuration tab, in the navigation pane, expand Citrix ADC (or NetScaler), and then click Software Images.
  5. On the right, switch to the XVA Files tab, and then click Upload.
  6. In the Upload NetScaler Instance XVA dialog box, click Browse, and select the XVA image file that you want to upload. Click Upload.
  7. The XVA image file appears in the XVA Files pane after it is uploaded.

Provision a Citrix ADC instance

  1. On the SDX Management Service, go to the Dashboard page.
  2. On the bottom right, the System Resource Utilization pane shows you the amount of physical resources that are available for allocation.
  3. Click Core Allocation to see the number of cores available for assignment.

    1. In 12.0 build 57 and newer, click Crypto Capacity to see SSL capacity.
  4. On the Configuration tab, in the navigation pane, expand Citrix ADC (or NetScaler), and then click Instances.
  5. In the NetScaler Instances pane, click Add.
  6. In the Provision NetScaler section, enter a name for the instance.
  7. Enter the NSIP, mask, and Gateway.
  8. Nexthop to Management Service – If the instance’s NSIP is on a different subnet than the SVM IP, and if the instance’s default gateway is on a different network than the NSIP, then enter a next hop router address on the instance’s NSIP network, so the instance can respond to the SDX Management Service.
  9. In the XVA File field, you can Browse > Local to select an XVA file on your local machine that hasn’t been uploaded to SDX yet. Or you can Browse > Appliance, and select an XVA file that has already been uploaded to SDX.
  10. Select an Admin Profile created earlier. Or you can click the Add button or plus icon to create a new Admin Profile.
  11. Enter a Description. Scroll down.
  12. In the License Allocation section, change the Feature License to Platinum.
  13. For Throughput, partition your licensed bandwidth. If you are licensed for 40 Gbps, make sure the total of all VPX instances does not exceed that number.
  14. For Allocation Mode, Burstable is also an option. Fixed bandwidth can’t be shared with other instances. Burstable can be shared. See Bandwidth Metering in NetScaler SDX at Citrix Docs.
  15. If SDX 12.0 build 57 or newer, in the Crypto Allocation field, allocate at least one multiple of Asymmetric Crypto Units. Clicking the up arrow should increment in the correct multiple. See Managing Crypto Capacity at Citrix Docs. You can find the minimum by dividing the total Asymmetric Crypto Units by the Crypto Virtual Interfaces. Enter in a multiple of this result.

    1. On newer Citrix ADC hardware (e.g SDX 8900), you can also specif the Symmetric Crypto Units. Again, enter a multiple of the minimum.
    2. Citrix ADC SDX older than build 57 will instead ask for SSL Chips. Some SSL/TLS features require at least one chip.
  16. In the Resource Allocation section, consider changing the Total Memory to 4096.
  17. For CPU, for production instances, select one of the Dedicated options. Dev/Test instances can use Shared CPU. Then scroll down.
  18. In the Instance Administration section, you can optionally add an instance administrator. Enter a new local account that will be created on the VPX. This instance admin is in addition to the nsroot user. Note, networking functionality is not available to this account. Scroll down.

  19. In the Network Settings section, if the VPX NSIP is on the same network as the SDX SVM, then leave 0/1 selected, and deselect 0/2.
  20. Click Add to connect the VPX to more interfaces.
  21. If you have Port Channels, select one of the LA interfaces.
  22. If you configure any VLAN settings here, then XenServer filters the VLANs available to the VPX instance. Changing the VLAN filtering settings later probably requires a reboot. Click Add. Note: VLAN tagging is configured inside the instance, and not here.
  23. In the Management VLAN Settings section, do not configure anything in this section unless you need to tag the NSIP VLAN.
  24. Click Done.
  25. After a couple minutes the instance will be created. Look in the bottom right of Chrome to see the status.
  26. Click Close when it’s done booting.
  27. If you go to the Dashboard page…
  28. If you click an instance name, you can see how the instance is connected to the physical NICs.
  29. Back in Configuration > Citrix ADC > Instances, in your Instances list, click the blue IP address link to launch the VPX management console. Or, simply point your browser to the NSIP and login.
  30. Do the following at a minimum (instructions are in the NetScaler System Configuration article):
    1. Create Policy Based Route for the NSIP – System > Settings > Network > PBRs
    2. Add SNIPs for each VLAN – System > Network > IPs
    3. Add VLANs and bind to SNIPs – System > Network > VLANs
    4. Create Static Routes for internal networks – System > Network > Routes
    5. Change default gateway – System > Network > Routes > 0.0.0.0
    6. Create another instance on a different SDX, and High Availability pair them together – System > High Availability

VPX Instances – Manage

You may login to the VPX instance and configure everything normally. SDX also offers the ability to manage IP addresses, and SSL certificates, from SDX, rather than from inside the VPX instance. The SDX Management Service does not have the ability to create certificates, so it’s probably best to do that from within the VPX instance.

View the console of a Citrix ADC instance

  1. Connect to the SDX Management Service using https.
    1. Viewing the virtual machine console might not work unless you install a valid certificate for the SDX Management Service.
  2. In the Management Service, go to Configuration > Citrix ADC > Instances.
  3. On the right, right-click an instance, and click Console.
  4. The instance console then appears.
  5. Another option is to use the Lights Out Module, and the xl console command, as detailed at Citrix Blog Post SDX Remote Console Access of VIs.

Start, stop, delete, or restart a Citrix ADC instance

  1. On the Configuration tab, in the navigation pane, expand Citrix ADC (or NetScaler), and click Instances.
  2. On the right, in the Instances pane, right-click the Citrix ADC instance on which you want to perform the operation, and then click Start or Shut Down or Delete or Reboot.
  3. In the Confirm message box, click Yes.

Create a Subnet IP Address on a Citrix ADC Instance

  1. On the Configuration tab, in the navigation pane, click Citrix ADC.
  2. On the right, in the Citrix ADC Configuration pane, click Create IP.
  3. In the Create Citrix ADC IP dialog box, specify values for the following parameters.
    • IP Address* – Specify the IP address assigned as the SNIP address.
    • Netmask* – Specify the subnet mask associated with the SNIP address.
    • Type* – Specify the type of IP address. Possible values: SNIP.
    • Save Configuration* – Specify whether the configuration should be saved on the Citrix ADC . Default value is false.
    • Instance IP Address* – Specify the IP address of the Citrix ADC instance on which this SNIP will be created.
  4. Click Create.

Create a VLAN on a Citrix ADC instance

  1. Go to Citrix ADC > Instances.
  2. On the right, right-click an instance, and click VLAN Bindings.
  3. Click Add.
  4. Enter a VLAN ID, and select an interface.
  5. Check the box for Tagged if needed.
  6. Notice there’s no way to bind a SNIP to the VLAN. You do that inside the instance. Click Create.

Save the configuration of a Citrix ADC instance

  1. On the Configuration tab, in the navigation pane, click Citrix ADC.
  2. On the right, in the Citrix ADC pane, click Save Configuration.
  3. In the Save Configuration dialog box, in Instance IP Address, select the IP addresses of the Citrix ADC instances whose configuration you want to save.
  4. Click OK.

Change NSIP of VPX Instance

The best way to change the NSIP is to edit the instance. Go to Configuration > Citrix ADC > Instances, right-click an instance, and click Edit.

Then change the IPv4 Address at the top of the page. Click Done. SVM will push the configuration change to the instance.

If you change NSIP inside of VPX instead of Editing the Instance in the Management Service, see article CTX139206 How to Change NSIP of VPX Instance in SDX to adjust the XenServer settings.

Enable Call Home

  1. On the Configuration tab, in the navigation pane, click the Citrix ADC node.
  2. On the right, click Call Home.
  3. Enter an email address to receive communications regarding Citrix ADC Call Home.
  4. Check the box next to Enable Call Home.
  5. Click Add.
  6. Select the instances to enable Call Home by moving them to the right, and click OK.
  7. You can view the status of Call Home by expanding Citrix ADC, and clicking Call Home.
  8. The right pane indicates if it’s enabled or not. You can also configure Call Home from here.

VPX Instance – Firmware Upgrade

Upload Citrix ADC Firmware Build Files

To upgrade a VPX instance from the Management Service, first upload the firmware build file.

  1. Download the Citrix ADC firmware using the normal method. It’s in the Build section.
  2. On the SDX, in the Configuration tab, on the left, expand Citrix ADC (or NetScaler), and click Software Images.
  3. On the right, in the Software Images tab, click Upload.
  4. Browse to the build…tgz file, and click Open.

Upgrade Multiple NetScaler VPX Instances

You can upgrade multiple instances at the same time:

  1. To prevent any loss of the configuration running on the instance that you want to upgrade, save the configuration on the instance before you upgrade the instance.
  2. On the Configuration tab, in the navigation pane, expand Citrix ADC (or NetScaler), and click Instances.
  3. Right-click an instance, and click Upgrade.
  4. In the Upgrade Citrix ADC Instance dialog box, in Build File, select the Citrix ADC upgrade build file of the version you want to upgrade to. Click OK.
  5. Click Close when done.

Management Service Monitoring

  1. To view syslog, in the navigation pane, expand System, click Auditing, and then click Syslog Message in the right pane.
  2. To view the task log, in the navigation pane, expand Diagnostics, and then click Task Log.
  3. To view Management Service events, on the Configuration tab, in the expand System and click Events.
  4. Citrix ADC > Entities lets you see the various Load Balancing entities configured on the instances. You might have to click Poll Now to get them to show up.
  5. To view instance alerts, go to Citrix ADC > Events > All Events.
  6. There is also event reporting.

Management Service Backups

The SDX appliance automatically keeps three backups of the Management Service configuration that are taken daily at 12:30 am.

Backups in NetScaler SDX contain the following:

  • Single bundle image
  • NetScaler XVA image
  • NetScaler upgrade image
  • Management Service image
  • Management Service configuration
  • NetScaler SDX configuration
  • NetScaler configuration

You can go to Management Service > Backup Files to backup or restore the SDX appliance’s configuration. And you can download the backup files.

You can configure the number of retained backups by clicking System on the left, and then clicking Backup Policy in the right pane.

You can even transfer the backup files to an external system.

VMware Horizon Load Balancing – NetScaler / Citrix ADC

Last Modified: Aug 11, 2023 @ 3:33 pm

106 Comments

Navigation

Use this procedure to load balance VMware Unified Access Gateway.

Change Log

Overview

To simplify this post, this post is focused on Unified Access Gateway, which is the replacement for Horizon Security Servers.

For load balancing of other Horizon components:

  • Internal Horizon Connection Servers – This is standard load balancing on SSL_BRIDGE protocol, port 443, and Source IP persistence. See the CLI commands for a sample configuration.
    • If you enabled the Secure Gateways (PCoIP, Blast) on the Connection Servers, then load balance the Connection Servers using the same procedure as load balancing UAGs.

UAG appliances vs Horizon Security Servers

There are two VMware-provided remote access solutions for Horizon View:

Unified Access Gateway appliances are preferred over Horizon Security Servers for the following reasons:

  • No need to pair with internal Connection Servers, which simplifies the configuration.
  • Linux appliance instead of Windows server.
  • Authentication can be offloaded to the Unified Access Gateway. This includes: Smart Cards, RSA, and RADIUS.
  • Blast Extreme Adaptive Transport (BEAT) in Horizon 7.1 and newer only works with Unified Access Gateway 2.9 and newer. Security Server and older Access Points don’t work.
    • VMware Blog Post Deep Dive into VMware Horizon Blast Extreme Adaptive Transport – Blast Extreme Adaptive Transport is enabled by default in VMware Horizon View 7.1 and Horizon Client 4.4. If the clients are connecting from outside the demilitarized zone (DMZ), you would also need to have VMware Unified Access Gateway (not Security Server) to take full advantage of the new transport. The adaptive transport will automatically sense the network for UDP availability and will fallback to legacy Blast TCP if UDP is not available.

Here is a typical Unified Access Gateway architecture:

  • Two Internal Connection Servers – these need to be load balanced on an internal VIP on TCP 443. Internal users connect to the internal VIP.
    • Instructions for load balancing the internal Connection Servers are not detailed in this post. Instead, see the CLI Commands.
  • Two DMZ Unified Access Gateway (Access Point) appliances – these need to be load balanced on a DMZ VIP on several ports. External users connect to the DMZ VIP.
    • Unified Access Gateway appliances connect to the internal Load Balancing VIP for the internal Connection Servers using HTTPS protocol
    • Unified Access Gateway appliances connect directly to Horizon Agents using Blast or PCoIP protocol.

During UAG configuration, you specify the address of the internal Connection Servers. The address you enter should be a DNS name that resolves to an internal load balancing VIP for the Connection Servers.

If you have split DNS, you can use the same DNS name for both external UAG access, and for internal Connection Server load balancing. Externally, configure the DNS name to resolve to the UAG Load Balancing VIP. Internally, configure the DNS name to resolve to the internal VIP that load balances the Connection Servers.

For Cloud Pod Architecture, configure separate VIPs in each datacenter. Then configure NetScaler Citrix ADC GSLB to resolve a single DNS name to multiple VIPs.

Protocols/Ports

To support Blast Extreme, PCoIP, and HTML Blast connectivity, the following ports must be load balanced to the UAGs:

  • TCP 443
  • UDP 443
  • TCP 4172
  • UDP 4172
  • TCP 8443
  • UDP 8443

The initial connection to UAG is always TCP 443 (HTTPS). If a user is load balanced on port 443 to a particular UAG, then the connection on UDP 4172 must go the same UAG. Normally load balancing persistence only applies to a single port number, so whatever UAG was selected for port 443, won’t be considered for the 4172 connection. But in NetScaler Citrix ADC, you can configure a Persistency Group to use a single persistency across multiple load balancing Virtual Servers with different port numbers. In F5, you configure Match Across Services, as detailed by Aresh Sarkari at Persistence Profile – F5 LTM Load Balancing for VMware Unified Access Gateway Appliance.

This topic primarily focuses on NetScaler Citrix ADC GUI configuration. Alternatively, you can skip directly to the CLI commands.

Load Balancing Monitors

Users connect to Unified Access Gateway appliances on multiple ports: TCP 443, UDP 443, TCP 8443, UDP 8443, TCP 4172, and UDP 4172. Create Load Balancing Monitors for each port number. Since UDP can’t be easily monitored, use TCP monitors as substitutes for UDP. That means you only need four monitors:

  • TCP 443 – HTTPS
    • HEAD /favicon.ico or GET /favicon.ico. This string can detect if UAG is in Quiesce mode, or if Connection Server is disabled in Horizon Console. See VMware 56636 for supported monitoring strings.
  • TCP 4172
  • TCP 8443

The procedure for configuring monitors changed in NetScaler 12.0 build 56 and newer.

SSL (443) Monitor for Connection Server Health

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-SSL or similar.
  4. In the Type field, click where it says Click to select.
  5. In the Monitor Types list, click the circle next to HTTP.
  6. Scroll up and click the blue Select button.
  7. To reduce UAG CPU, VMware recommends setting the Interval to 30 seconds.
  8. In the HTTP Request field, enter GET /favicon.ico. See VMware 56636 for supported health monitoring requests.
  9. Check the box next to Secure.
  10. Scroll down and click Advanced Parameters to expand it.
  11. In the Advanced Parameters section, in the Destination Port field, enter 443.
  12. Scroll down to the TROFS Code field and enter 503. When UAG is in Quiesce mode, TROFS will cause the service to transition to out of service allowing existing connections instead of directly going down and killing existing sessions. (h/t Henry Heres)
  13. Scroll down, and click Create.

PCoIP (4172) Monitor

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-PCoIP or similar.
  4. For the Type field, click where it says Click to select and select TCP from the Monitor Types list.
  5. Scroll down to Advanced Parameters, click Advanced Parameters to expand it, and then enter 4172 in the Destination Port field. This forces the monitor to connect to port 4172 even if the monitor is bound to a service group that is configured for a different port number.
  6. Scroll down, and click Create.

Blast (8443) Monitor

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-Blast or similar.
  4. For the Type field, click where it says Click to select and select TCP from the Monitor Types list.
  5. Scroll down to Advanced Parameters, click Advanced Parameters to expand it, and then enter 8443 in the Destination Port field. This forces the monitor to connect to port 8443 even if the monitor is bound to a service group that is configured for a different port number.
  6. Scroll down, and click Create.

UAG DDoS

NetScaler Citrix ADC Monitors might trigger UAG’s DDoS protection. To stop this: (source = UAG breaks after a few days. They break 100% of the time. at VMware Discussions)

  1. Point your browser to the UAG appliance’s admin interface using https, port 9443 and path /admin.
  2. Login to the admin interface.
  3. On the right, under Configure Manually, click Select.
  4. In the Advanced Settings section, click the gear icon for System Configuration.
  5. Scroll down.
  6. Change Request Timeout to 0.
  7. Change Body Receive Timeout to 0.
  8. Click Save.

Load Balancing Servers

Create Load Balancing Server Objects for the DMZ Unified Access Gateway appliances.

  1. On the left, expand Traffic Management, expand Load Balancing, and click Servers.
  2. On the right, click Add.
  3. Enter a descriptive server name, usually it matches the actual appliance name.
  4. Enter the IP address of a Unified Access Gateway appliance.
  5. Enter comments to describe the server. Click Create.
  6. Continue adding Unified Access Gateway appliances.

Load Balancing Service Groups

Overview

Since there are six protocol/ports to UAG, there will be six service groups – one for each protocol/port:

  • TCP 443 – SSL_BRIDGE
  • UDP 443
  • UDP 4172
  • TCP 4172
  • TCP 8443 – SSL_BRIDGE
  • UDP 8443

Users will initially connect to TCP port 443, and then must be redirected to one of the other ports on the same UAG appliance that was initially used for the TCP 443 connection. If TCP 443 is up, but UDP 4172 is down on the same appliance, then you probably TCP 443 to go down too. To facilitate this, bind all three port number monitors to the TCP 443 service. If any of the bound monitors goes down, then TCP 443 is also taken down.

  • Only the TCP 443 service group needs to monitor all port numbers.
  • Other port number service groups only need to monitor that specific port number. For example, the TCP 8443 Service Group should monitor port TCP 8443.
  • Since UDP is difficult to monitor, the UDP Service Groups will monitor the equivalent TCP port. For example, the UDP 4172 Service Group will monitor TCP 4172. This isn’t the best option, but it’s better than ping.

TCP 443 Load Balancing Service Group

  1. On the left, expand Traffic Management, expand Load Balancing, and click Service Groups.
  2. On the right, click Add.
  3. Give the Service Group a descriptive name (e.g. svcgrp-Horizon-SSL).
  4. Change the Protocol to SSL_BRIDGE.
  5. Click OK to close the Basic Settings section.
  6. On the left, in the Service Group Members section, click where it says No Service Group Member.

    1. Change the selection to Server Based.
    2. In the Select Server field, click where it says Click to select.
    3. Select the Unified Access Gateway appliances you created earlier, and then at the top of the page click the blue Select button.
    4. In the Port field, enter 443, and click Create.
  7. Click OK to close the Service Group Members section.
  8. On the right, in the Advanced Settings column, click Monitors to move it to the left.
  9. On the left, at the bottom of the page, in the Monitors section, click where it says No Service Group to Monitor Binding.

    1. In the Select Monitor field, click where it says Click to select.
    2. Click the circle next to the Horizon-SSL monitor, and then at the top of the page click the blue Select button.
    3. Click Bind.
  10. For load balancing UAGs, this Service Group should monitor all port numbers so that if any of the port numbers are down then the entire server should no longer receive connections. If load balancing internal Connection Servers, then you don’t need to bind any more monitors since the PCoIP Gateway and Blast Gateway are usually disabled. To bind more monitors, on the left, click where it says 1 Service Group to Monitor Binding.

    1. Click Add Binding.
    2. In the Select Monitor field, click where it says Click to select.
    3. Click the circle next to the Horizon-PCoIP monitor, and then at the top of the page click the blue Select button.
    4. Then click Bind.
    5. Repeat these steps to bind the Horizon-Blast monitor. Unfortunately you can only bind one monitor at a time.
      • If any of these monitors goes down, then the UAG is taken offline.
    6. Click Close.
  11. To verify the monitors, on the left, higher up the page in the Service Group Members section, click the line that says # Service Group Members.

    1. Right-click one of the members, and click Monitor Details.
    2. The Last Response should indicate Success. If you bound multiple monitors to the Service, then the member will only be UP if all monitors succeed.

      • UAG has a Quiesce mode, which tells the load balancer to stop sending it connections. You can enable Quiesce mode in the UAG’s System Configuration menu.
      • Connection Servers can be disabled.
      • If Quiesce mode is enabled on the UAG, or if the Connection Server is disabled, then the member of the service group will show Going Out of Service. You can see this by right-clicking on the Server Group and clicking Manage Members.

    3. Click Close when done.
  12. Then click Done to finish creating the Service Group.

Other Ports Load Balancing Service Groups

Here are general instructions for the other Horizon UAG load balancing service groups.

  1. On the left, go to Traffic Management > Load Balancing > Service Groups.
  2. On the right, click Add.
  3. Name it svcgrp-Horizon-UDP443 or similar.
  4. Change the Protocol to UDP. Click OK to close the Basic Settings section.
  5. On the left, click where it says No Service Group Member.

    1. Change the selection to Server Based, and then click Click to select.
    2. Select your multiple Unified Access Gateway appliances, and then at the top of the page click the blue Select button.
    3. Enter 443 as the Port. Click Create.
  6. Click OK to close the Service Group Members section.
  7. On the right, in the Advanced Settings column, click Monitors to move it to the left.

    1. On the left, in the Monitors section, click where it says No Service Group to Monitor Binding.
    2. For the Select Monitor field, click where it says Click to select.
    3. Select the Horizon-SSL monitor, click Select, and then click Bind. Since we don’t have a UDP monitor, we’re binding the TCP monitor instead.
  8. Click Done to finish creating the Service Group for UDP 443.
  9. Add another Service Group for PCoIP on TCP 4172.
    1. Name = svcgrp-Horizon-PCoIPTCP or similar.
    2. Protocol = TCP
    3. Members = multiple Unified Access Gateway appliances.
    4. Port = 4172.
    5. Monitors = Horizon-PCoIP. You can add the other monitors if desired.
  10. Add another Service Group for PCoIP on UDP 4172.
    1. Name = svcgrp-Horizon-PCoIPUDP or similar.
    2. Protocol = UDP
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 4172.
    5. Monitors = Horizon-PCoIP. You can add the other monitors if desired.
  11. Add another Service Group for SSL_BRIDGE 8443.
    1. Name = svcgrp-Horizon-TCP8443 or similar.
    2. Protocol = SSL_BRIDGE
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 8443.
    5. Monitors = Horizon-Blast. You can add the other monitors if desired.
  12. Add another Service Group for UDP 8443 (Blast Extreme in Horizon 7).
    1. Name = svcgrp-Horizon-UDP8443 or similar.
    2. Protocol = UDP
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 8443.
    5. Monitors = Horizon-Blast. You can add the other monitors if desired.
  13. The six service groups should look something like this:

Load Balancing Virtual Servers

Unified Access Gateway appliances listen on multiple ports so you will need separate load balancers for each port number. Here is a summary of their Virtual Servers, all listening on the same Virtual IP address:

  • Virtual Server on SSL_BRIDGE 443 – bind the SSL_BRIDGE 443 service group.
  • Virtual Server on UDP 443 (Horizon 7) – bind the UDP 443 service group.
  • Virtual Server on UDP 4172 – bind the PCoIP UDP service group.
  • Virtual Server on TCP 4172 – bind the PCoIP TCP service group.
  • Virtual Server on SSL_BRIDGE 8443 – bind the SSL_BRIDGE 8443 service group.
  • Virtual Server on UDP 8443 (Horizon 7) – bind the UDP 8443 service group.

Do the following to create the Virtual Servers:

  1. On the left, under Traffic Management > Load Balancing, click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section:
    1. Name it lbvip-Horizon-SSL or similar.
    2. Change the Protocol to SSL_BRIDGE.
    3. Specify a new VIP. This one VIP will be used for all of the Virtual Servers.
    4. Enter 443 as the Port.
  4. Click OK to close the Basic Settings section.
  5. On the left, in the Services and Service Groups section, click where it says No Load Balancing Virtual Server ServiceGroup Binding.

    1. Click where it says Click to select.
    2. Click the circle next to the Horizon-SSL Service Group, and then at the top of the page click the blue Select button.
    3. Click Bind.
  6. Click Continue to close the Services and Service Groups section.
  7. Then click Done to finish creating the Load Balancing Virtual Server. Persistence will be configured later.
  8. Create another Load Balancing Virtual Server for UDP 443. You can right-click the existing Load Balancing Virtual Server and click Add to copy some settings.

    1. Name = lbvip-Horizon-UDP443
    2. Same VIP as the TCP 443 Load Balancer.
    3. Protocol = UDP, Port = 443
    4. Service Group Binding = the UDP 443 Service Group

  9. Create another Load Balancing Virtual Server for PCoIP UDP 4172:
    1. Name = lbvip-Horizon-PCoIPUDP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = UDP, Port = 4172
    4. Service Group Binding = the PCoIP UDP Service Group.

  10. Create another Load Balancing Virtual Server for PCoIP TCP 4172:
    1. Name = lbvip-Horizon-PCoIPTCP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = TCP, Port = 4172
    4. Service Group Binding = the PCoIP TCP Service Group

  11. Create another Load Balancing Virtual Server for SSL_BRIDGE 8443:
    1. Name = lbvip-Horizon-8443SSL
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = SSL_BRIDGE, Port = 8443
    4. Service Group Binding = the TCP 8443 SSL_BRIDGE Service Group

  12. Create another Load Balancing Virtual Server for UDP 8443:
    1. Name = lbvip-Horizon-8443UDP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = UDP, Port = 8443
    4. Service Group Binding = the UDP 8443 Service Group

  13. This gives you six Load Balancing Virtual Servers on the same VIP, but different protocols and port numbers.

Persistency Group

Users will first connect to SSL_BRIDGE 443 and be load balanced. Subsequent connections to the other port numbers must go to the same load balanced appliance. Create a Persistency Group to facilitate this.

  1. On the left, under Traffic Management, expand Load Balancing, and click Persistency Groups.
  2. On the right, click Add.
  3. Give the Persistency Group a name (e.g. Horizon).
  4. Change the Persistence drop-down to SOURCEIP.
  5. Enter a Time-out that is equal to, or greater than the timeout in Horizon View Administrator, which defaults to 10 hours (600 minutes).
  6. In the Virtual Server Name section, click Add.
  7. Move all six Horizon Load Balancing Virtual Servers to the right. Click Create.

Horizon Connection Server Locked.properties File

Horizon Connection Server’s default security settings might prevent you from connecting to load balanced Connection Servers and/or Unified Access Gateways. On the Connection Servers, go to C:\Program Files\VMware\VMware View\Server\sslgateway\conf, edit or create locked.properties file, and enter the following:

allowUnexpectedHost=true
checkOrigin=false
enableCORS=false

More details at VMware 2144768 Accessing the Horizon View Administrator page displays a blank error window in Horizon and 85801 Cross-Origin Resource Sharing (CORS) with Horizon 8 and loadbalanced HTML5 access. allowUnexpectedHost defaults to false in Horizon 2306 and Horizon 2212.1 and newer. Another option is to add portalHost entries as detailed at Allow HTML Access Through a Gateway at VMware Docs.

Load Balancing CLI Commands

Internal Connection Server Load Balancing

add server VCS01 10.2.2.19
add server VCS02 10.2.2.20
add serviceGroup svcgrp-VCS-SSL SSL_BRIDGE
add lb vserver lbvip-Horizon-SSL SSL_BRIDGE 10.2.5.203 443 -persistenceType SOURCEIP -timeout 600
bind lb vserver lbvip-Horizon-SSL svcgrp-VCS-SSL
add lb monitor Horizon-SSL HTTP -respCode 200 -httpRequest "GET /favicon.ico" -destPort 443 -secure YES
bind serviceGroup svcgrp-VCS-SSL VCS01 443
bind serviceGroup svcgrp-VCS-SSL VCS02 443
bind serviceGroup svcgrp-VCS-SSL -monitorName Horizon-SSL

Unified Access Gateway load balancing with Blast and PCoIP

add server UAG01 10.2.2.187
add server UAG02 10.2.2.188
add serviceGroup svcgrp-Horizon-SSL SSL_BRIDGE
add serviceGroup svcgrp-Horizon-UDP443 UDP
add serviceGroup svcgrp-Horizon-PCoIPTCP TCP
add serviceGroup svcgrp-Horizon-PCoIPUDP UDP
add serviceGroup svcgrp-Horizon-TCP8443 SSL_BRIDGE
add serviceGroup svcgrp-Horizon-UDP8443 UDP
add lb vserver lbvip-Horizon-SSL SSL_BRIDGE 10.2.5.204 443
add lb vserver lbvip-Horizon-UDP443 UDP 10.2.5.204 443
add lb vserver lbvip-Horizon-PCoIPUDP UDP 10.2.5.204 4172
add lb vserver lbvip-Horizon-PCoIPTCP TCP 10.2.5.204 4172
add lb vserver lbvip-Horizon-8443SSL SSL_BRIDGE 10.2.5.204 8443
add lb vserver lbvip-Horizon-8443UDP UDP 10.2.5.204 8443
bind lb vserver lbvip-Horizon-SSL svcgrp-Horizon-SSL
bind lb vserver lbvip-Horizon-UDP443 svcgrp-Horizon-UDP443
bind lb vserver lbvip-Horizon-PCoIPTCP svcgrp-Horizon-PCoIPTCP
bind lb vserver lbvip-Horizon-PCoIPUDP svcgrp-Horizon-PCoIPUDP
bind lb vserver lbvip-Horizon-8443SSL svcgrp-Horizon-TCP8443
bind lb vserver lbvip-Horizon-8443UDP svcgrp-Horizon-UDP8443
add lb group Horizon -persistenceType SOURCEIP -timeout 600
bind lb group Horizon lbvip-Horizon-SSL
bind lb group Horizon lbvip-Horizon-UDP443
bind lb group Horizon lbvip-Horizon-PCoIPUDP
bind lb group Horizon lbvip-Horizon-PCoIPTCP
bind lb group Horizon lbvip-Horizon-8443SSL
bind lb group Horizon lbvip-Horizon-8443UDP
set lb group Horizon -persistenceType SOURCEIP -timeout 600
add lb monitor Horizon-SSL HTTP -respCode 200 -httpRequest "GET /favicon.ico" -destPort 443 -secure YES -trofscode 503
add lb monitor Horizon-PCoIP TCP -LRTM DISABLED -destPort 4172 -secure YES
add lb monitor Horizon-Blast TCP -LRTM DISABLED -destPort 8443 -secure YES
bind serviceGroup svcgrp-Horizon-SSL UAG01 443
bind serviceGroup svcgrp-Horizon-SSL UAG01 443
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-SSL
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-Blast
bind serviceGroup svcgrp-Horizon-UDP443 UAG01 443
bind serviceGroup svcgrp-Horizon-UDP443 UAG01 443
bind serviceGroup svcgrp-Horizon-UDP443 -monitorName Horizon-SSL
bind serviceGroup svcgrp-Horizon-PCoIPTCP UAG01 4172
bind serviceGroup svcgrp-Horizon-PCoIPTCP UAG02 4172
bind serviceGroup svcgrp-Horizon-PCoIPTCP -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-PCoIPUDP UAG01 4172
bind serviceGroup svcgrp-Horizon-PCoIPUDP UAG02 4172
bind serviceGroup svcgrp-Horizon-PCoIPUDP -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-TCP8443 UAG01 8443
bind serviceGroup svcgrp-Horizon-TCP8443 UAG02 8443
bind serviceGroup svcgrp-Horizon-TCP8443 -monitorName Horizon-Blast
bind serviceGroup svcgrp-Horizon-UDP8443 UAG01 8443
bind serviceGroup svcgrp-Horizon-UDP8443 UAG02 8443
bind serviceGroup svcgrp-Horizon-UDP8443 -monitorName Horizon-Blast

Citrix Director Load Balancing – Citrix ADC

Last Modified: Mar 9, 2022 @ 4:21 pm

24 Comments

Navigation

Change Log

  • 2018 Dec 20 – updated screenshots for ADC 12.1 build 50.
  • 2017 Dec 25 – updated entire article for 12.0 build 56. Monitor section has new 12.0 build 56 instructions.

Monitor

12.0 build 56 and newer

Instructions for creating the monitor changed in 12.0 build 56 and newer. If your build is older, skip to the older instructions.

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Director or similar.
  4. In the Type field, click where it says Click to select.
  5. Scroll down and click the circle next to HTTP.
  6. At the top of the window, click the blue Select button.
  7. Scroll down the Basic  Parameters section, and check the box next to Secure. This checkbox instructs the monitor to connect to the Director Servers using https/SSL/TLS instead of http.
  8. In the HTTP Request box, enter GET /Director/LogOn.aspx?cc=true.
  9. If Single Sign-on (Windows Integrated Authentication) is enabled on Director, then you might have to add 302 as a Response Code.
  10. Scroll down, and click Create.
  11. Jump to the Servers section.

12.0 older than build 56

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Director or similar.
  4. Change the Type drop-down to HTTP.
  5. If you will use SSL to communicate with the Director servers, then on the Standard Parameters tab, scroll down, and check the box next to Secure.
  6. Scroll up, and switch to the Special Parameters tab.
  7. In the HTTP Request field, enter GET /Director/LogOn.aspx?cc=true
    1. If Single Sign-on is enabled on Director, then you might have to add 302 as a Response Code.
  8. Scroll down, and click Create.

Servers

  1. On the left, expand Traffic Management, expand Load Balancing, and click Servers.
  2. On the right, click Add.
  3. Enter a descriptive server name. Usually it matches the actual server name.
  4. Enter the IP address of the Director server.
  5. Enter comments to describe the server. Click Create.
  6. Continue adding Director servers.

Service Group

  1. On the left, expand Traffic Management, expand Load Balancing, and click Service Groups.
  2. On the right, click Add.
  3. Give the Service Group a descriptive name (e.g. svcgrp-Director-SSL).
  4. Change the Protocol to HTTP or SSL, depending on if IIS on the Director server is enabled for https or not.
    • If the protocol is SSL, ensure the Monitor for Director has Secure enabled, as detailed earlier.
  5. Scroll down, and click OK.

  6. On the left, in the Service Group Members section, click where it says No Service Group Member.

    1. Change the selection to Server Based, and then Click to select the Director server objects.

    2. Enter 80 or 443 as the port. Then click Create.
  7. Click OK to close the Service Group Members section.
  8. On the right, under Advanced Settings, click Monitors.
  9. On the left, in the Monitors section, click where it says No Service Group to Monitor Binding.

    1. Click where it says to Click to select.
    2. Click the circle next to the Director monitor you created earlier. The monitor might be on Page 2.
      • The circle must be clicked exactly (no room for error). If you click outside the circle, then the monitor will open for editing. If this happens, click Close to return to the selection screen.
    3. At the top of the window, click the blue Select button.
    4. Then click Bind.
  10. To verify that the monitor is working, on the left, in the Service Group Members section, click the Service Group Members line.
  11. Right-click a member, and click Monitor Details.
  12. The Last Response should be Success – HTTP response code 200 received. Click Close twice.
  13. Then click Done.

Responder

Create a Responder policy to redirect users from the root page to /Director.

  1. Go to AppExpert > Responder, and enable the feature if it isn’t already enabled.
  2. Go to AppExpert > Responder > Actions.
  3. On the right, click Add.

    1. Give the Action a name (e.g. Director_Redirect).
    2. Change the Type to Redirect.
    3. In the Expression box, enter "/Director", including the quotes.
  4. On the bottom, click Create.
  5. Go to AppExpert > Responder > Policies.
  6. On the right, click Add.

    1. Give the Policy a name (e.g. Director_Redirect).
    2. Select the previously created Action.
    3. In the Expression box, enter HTTP.REQ.URL.PATH.EQ("/")
  7. On the bottom, click Create.

Load Balancing Virtual Server

  1. Create or install a certificate that will be used by the SSL Virtual Server. This certificate must match the DNS name for the load balanced Director servers.
  2. On the left, under Traffic Management > Load Balancing, click Virtual Servers.
  3. On the right, click Add.
  4. Do the following in the Basic Settings section:
    1. Name it lbvip-Director-SSL or similar.
    2. Change the Protocol to SSL.
    3. Specify a new internal VIP.
    4. Enter 443 as the Port.
    5. Click OK to close the Basic Settings section.
  5. On the left, in the Services and Service section, click where it says No Load Balancing Virtual Server ServiceGroup Binding.

    1. Click where it says Click to select.
    2. Click the circle next to a previously created Service Group. It might be on page 2.
      • The circle must be clicked exactly (no room for error). If you click outside the circle, then the Service Group will open for editing. If this happens, click the x on the top right, or the Done button on the bottom, to return to the selection screen.
    3. At top of the screen, click the blue Select button.
    4. Click Bind.
  6. Click Continue to close the Services and Service Groups section.
  7. Click where it says No Server Certificate.

    1. Click where it says Click to select.
    2. Click the circle next to a certificate that matches the FQDN that resolves to this VIP. It might be on page 2.
    3. At the top of the window, click the blue Select button.
    4. Click Bind.
  8. Click Continue to close the Certificate section.
  9. On the right, in the Advanced Settings column, click Persistence.
  10. On the left, in the Persistence section, do the following:
    1. Change the Persistence drop-down to COOKIEINSERT. The Persistence section in 12.0 build 56 and newer is slightly different than older builds.
    2. Set the Time-out to 0 minutes. This makes it a session cookie instead of a persistent cookie.
    3. Set the Backup Persistence to SOURCEIP.
    4. Set the Backup Time-out to match the timeout of Director. The default timeout for Director is 245 minutes.
    5. The IPv4 Netmask should default to 32 bits.
    6. Click OK to close the Persistence section.
  11. On the right, in the Advanced Settings section, add the Policies section.
  12. On the left, in the Policies section, click the plus icon.

    1. Change the Choose Policy drop-down to Responder, and click Continue.
    2. Click to select the previously created Director_Redirect policy.

      • The circle next to the Responder policy must be clicked exactly (no room for error). If you click outside the circle, then the policy will open for editing. If this happens, click Close to return to the selection screen.
    3. After selecting, click Bind.
  13. If you haven’t enabled the Default SSL Profile, then perform other normal SSL configuration including: disable SSLv3, bind a Modern A+ Cipher Group, and enable Strict Transport Security.

SSL Redirect

Do one of the following to configure a redirect from HTTP to HTTPS:

SSL Warning

  1. If you are doing SSL Offload (SSL on front end, HTTP on back end), when connecting to Director, it might complain about “You are not using a secure connection”.
  2. To turn off this warning, login to the Director servers, and run IIS Manager.
  3. On the left, navigate to Server > Sites > Default Web Site > Director.
  4. In the middle, double-click Application Settings.
  5. Change UI.EnableSslCheck to false.

CLI Commands

Here is a list of NetScaler CLI commands for Director Load Balancing:

# SSL Global Parameters
set ssl parameter -denySSLReneg NONSECURE

# Certs
add ssl certKey WildcardCorpLocal -cert WildcardCorpLocal.pfx -key WildcardCorpLocal.pfx -inform PFX -passcrypt "Passw0rd"

# SSL Cipher Group
add ssl cipher custom-ssllabs-cipher
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-ECDHE-RSA-AES256-GCM-SHA384 -cipherPriority 1
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-ECDHE-RSA-AES128-GCM-SHA256 -cipherPriority 2
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-ECDHE-RSA-AES-256-SHA384 -cipherPriority 3
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-ECDHE-RSA-AES-128-SHA256 -cipherPriority 4
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-ECDHE-RSA-AES256-SHA -cipherPriority 5
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-ECDHE-RSA-AES128-SHA -cipherPriority 6
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-DHE-RSA-AES256-GCM-SHA384 -cipherPriority 7
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1.2-DHE-RSA-AES128-GCM-SHA256 -cipherPriority 8
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-DHE-RSA-AES-256-CBC-SHA -cipherPriority 9
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-DHE-RSA-AES-128-CBC-SHA -cipherPriority 10
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-AES-256-CBC-SHA -cipherPriority 11
bind ssl cipher custom-ssllabs-cipher -cipherName TLS1-AES-128-CBC-SHA -cipherPriority 12

# Responder Actions
add responder action Director_Redirect redirect "\"/Director\"" -responseStatusCode 302

# Responder Policies
add responder policy Director_Redirect "HTTP.REQ.URL.PATH.EQ(\"/\")" Director_Redirect

# Load Balancing Global Parameters
enable ns mode FR L3 Edge USNIP PMTUD ULFD
set ns param -cookieversion 1
set ns tcpParam -WS ENABLED -SACK ENABLED
set ns httpParam -dropInvalReqs ON

# Monitors
add lb monitor Director HTTP -respCode 200 302 -httpRequest "GET /Director/LogOn.aspx?cc=true" -LRTM DISABLED -secure YES

# Servers
add server Director01 xdc01.corp.local
add server Director02 xdc02.corp.local

# Service Groups
add serviceGroup svcgrp-Director-SSL SSL -maxClient 0 -maxReq 0 -cip DISABLED -usip NO -useproxyport YES -cltTimeout 180 -svrTimeout 360 -CKA NO -TCPB NO -CMP YES
bind serviceGroup svcgrp-Director-SSL Director01 443
bind serviceGroup svcgrp-Director-SSL Director02 443
bind serviceGroup svcgrp-Director-SSL -monitorName Director

# Load Balancing Virtual Servers
add lb vserver lbvip-Director-SSL SSL 10.2.5.210 443 -persistenceType COOKIEINSERT -timeout 0 -persistenceBackup SOURCEIP -backupPersistenceTimeout 245 -cltTimeout 180 -redirectFromPort 80 -httpsRedirectUrl "https://director.corp.com"
bind lb vserver lbvip-Director-SSL svcgrp-Director-SSL
bind lb vserver lbvip-Director-SSL -policyName Director_Redirect -priority 100 -gotoPriorityExpression END -type REQUEST

# SSL Virtual Servers
set ssl vserver lbvip-Director-SSL -ssl3 DISABLED -HSTS ENABLED -maxage 157680000
unbind ssl vserver lbvip-Director-SSL -cipherName ALL
bind ssl vserver lbvip-Director-SSL -cipherName custom-ssllabs-cipher
bind ssl vserver lbvip-Director-SSL -certkeyName WildcardCorpLocal
bind ssl vserver lbvip-Director-SSL -eccCurveName P_256
bind ssl vserver lbvip-Director-SSL -eccCurveName P_384
bind ssl vserver lbvip-Director-SSL -eccCurveName P_224
bind ssl vserver lbvip-Director-SSL -eccCurveName P_521

SSL VPN – Citrix Gateway

Last Modified: May 5, 2021 @ 7:53 am

138 Comments

Navigation

💡 = Recently Updated

Change Log

Overview

Here’s an overview of the Citrix Gateway connection process:

  1. Users use SSL/TLS to connect to a Citrix Gateway Virtual Server (VIP).
  2. Citrix Gateway prompts the user for authentication.
  3. Once the user is authenticated, Citrix Gateway uses Session Policies/Profiles to determine what happens next.

Citrix Gateway supports six different connection methods:

  • ICA Proxy to Citrix Virtual Apps and Desktops (CVAD) (aka XenApp/XenDesktop) and StoreFront – the client is built into Citrix Workspace app (aka Citrix Receiver)
  • SSL VPN – requires installation of Citrix Gateway plug-in (VPN client)
  • Clientless – browser only, no VPN client, uses rewrite
  • Secure Browse – from MDX-wrapped mobile applications (Citrix Endpoint Management aka XenMobile), uses rewrite
  • RDP Proxy – only RDP client is needed
  • PCoIP Proxy – only VMware Horizon Client is needed

You can configure Citrix Gateway Session Policies/Profiles to only use one of the connection methods. Or Citrix Gateway can be configured to let users choose between ICA Proxy, Clientless, and SSL VPN connection methods. Here’s a sample Client Choices screen using the RfWebUI theme:

  • The Clientless Access option opens a portal page that has icons from Citrix StoreFront (ICA Proxy), icons for RDP Proxy, icons for PCoIP Proxy, and links to websites.
    • The website links can be proxied through Citrix Gateway. Proxy methods include: clientless rewrite, SSL VPN, and traditional load balancing.
    • Citrix Gateway can optionally Single Sign-on to the websites.
  •  The Virtual App and Desktop Access option only displays icons from Citrix StoreFront (ICA Proxy). For other types of icons, you’ll need Clientless Access.
  • The Connect with Citrix Gateway Plug-in option launches the VPN tunnel. After the tunnel is established, a portal page is displayed. This can be the Clientless Access portal, or a user defined website URL (e.g. intranet).

Session Policies/Profiles have several settings that control the behavior seen after authentication:

  • ICA Proxy – ON or OFF
    • If ON, then ICA Proxy is the only connection method allowed, overriding the other connection methods.
    • ICA Proxy does not launch the VPN client. It only needs Citrix Workspace app.
    • ICA Proxy shows the Webpage that’s configured in the Web Interface Address field of the Session Profile. This is typically the StoreFront Receiver for Web page, but technically it can be any internal website.
    • If OFF, that doesn’t mean ICA Proxy doesn’t work. You can still send ICA traffic to the Citrix Gateway Virtual Server, and the Citrix Gateway Virtual Server will still proxy it to internal VDAs.
    • Setting it to OFF allows the other connection methods to function. For example, Clientless Access can show both Citrix Gateway Bookmarks and StoreFront published apps. If VPN is launched, then the portal page shown to the user after the tunnel is established can contain the StoreFront published applications.
  • Clientless Access – On, Off, Disabled
    • If On, then Clientless is the only connection method allowed, assuming ICA Proxy is not set to ON. After the user logs in, the user is presented with a portal page that contains a list of Gateway bookmarks and/or StoreFront published icons. The VPN Client is not launched.
    • The Home Page setting in the Session Profile allows you to display an internal website instead of displaying the Citrix Gateway Portal Page.
    • Bookmarks are configured at Citrix Gateway > Resources > Bookmarks. You can bind the Bookmarks (Urls) to the Citrix Gateway Virtual Server, or to AAA Groups.
    • Only Bookmarks configured for Clientless Access will work without a VPN. The internal websites are rewritten so they are proxied through Citrix Gateway. For example, if the internal website is http://intranet.corp.local, then Gateway rewrites them to https://gateway.corp.com/cvpn/http/internal.corp.local. This causes the web browser to send the HTTP Request to Citrix Gateway, which then forwards the HTTP Request to the internal web server. No VPN needed.
  • Plug-in Type – Windows/MAC OS X
    • If both Clientless and ICA Proxy are set to Off, then the VPN Client will be downloaded and launched.
    • Once the VPN tunnel is established, the webpage configured in the Home Page setting is displayed. Or the Citrix Gateway Portal Page (Clientless Access) is displayed if no Home Page is configured. The Bookmarks in the Portal Page can link to internal websites that are only accessible through a VPN tunnel. Or Bookmarks can be configured for Clientless Access.
    • Additional Gateway objects control VPN behavior including: DNS Suffix, Intranet Applications, Intranet IPs, and Authorization Policies.
  • Client Choices – checked or unchecked
    • If Client Choices is checked, then it displays a page containing up to three buttons allowing the user to choose between VPN, Clientless, or StoreFront. The Network Access with the Citrix Gateway Plug-in (VPN) button is always displayed. The Clientless Access button is displayed if Clientless Access is set to On or Off (not Disabled). The Virtual App and Desktop Access button is displayed if a Web Interface Address is configured.

Here are some characteristics of Session Policies:

  • Citrix Gateway > Global Settings > Change Global Settings has the same settings as a Session Profile. However, all Session Policies/Profiles override the settings configured in Global Settings. That’s the whole point of the Override Global checkboxes in the Session Profiles.
  • Session Policy Expression – If the Session Policy Expression is true, then the settings contained in the Session Profile are applied.
    • Action = Session Profile – The Session Profile is also sometimes called the Action. That’s because all Citrix ADC policies follow a standard structure – if the expression evaluates to True, then perform the Action. For Session Policies in particular, the policy Action = Session Profile.
    • EPA – The Session Policy Expression in Classic Syntax could include an Endpoint Analysis (EPA) expression.
  • Default Syntax Expressions vs Classic Syntax Policy Expressions – Citrix ADC 12 and newer supports Default (Advanced) Syntax Expressions on Session Policies, in addition to the older Classic Syntax.
    • No syntax mixing – All Session Policies bound anywhere must be either Default or Classic. You cannot mix the two types.
    • EPA is Classic only – EPA Scans are only supported in Classic Expressions.
    • AD Group in Default Syntax – Default Syntax allows expressions for AD Group Membership like HTTP.REQ.USER.IS_MEMBER_OF("MyADGroup"). This could eliminate AAA Groups in some circumstances.
  • Policy Bind Points – Session Policies can be bound to three different bind points – Citrix Gateway Virtual Server, AAA Groups, and AAA User.
    • When bound to a Citrix Gateway Virtual Server, the Session policy/profile applies to all users that log into that Virtual Server.
    • When bound to a AAA Group, the Session policy/profile only applies to members of the AAA group (Active Directory group or local group)
    • When bound to a AAA User, the Session policy/profile only applies to the AAA user (Active Directory user or local user)
  • Profile Conflicts – Multiple Session Policies/Profiles could apply to a single session. In this case, the Profile settings are merged. But if there’s a conflict (e.g. one Session Profile enables Clientless access, but another Session Profile disables Clientless access), then which one wins?
    • Priority number – When you bind a Session Policy to a bind point, you specify a priority number. This priority number usually defaults to 100.
    • Lowest priority number wins – The Session Policy binding that has the lowest priority number, wins. Session Policies bound with a priority of 80 will win over Session Policies bound with a priority of 100. Remember, for settings that don’t conflict, the two Profiles merge, but for settings that do conflict, the lower priority number policy/profile settings win.
    • Classic Policy Priority and multiple bind points – for Classic Session Policies the bind point location doesn’t matter. If you bind a Session Policy to a AAA Group with a priority of 100, and you also bind a Session Policy to the Citrix Gateway Virtual Server with a priority of 80, then the conflicting settings in the Session Policy bound to the Citrix Gateway Virtual Server will win because it has the lower priority number. You might think that AAA-bound policies always override Virtual Server-bound policies, but that is not the case.
    • Advanced Policy Priority and multiple AAA Groups – see CTX289931 AAA group session policies are not applying based on priority. The first created AAA Group overrides AAA Groups created later unless you specify the weight parameter when creating the AAA Group from the CLI.
  • Global Settings vs Virtual Server Settings – When you bind a Session Policy to a Citrix Gateway Virtual Server, the settings in the Session Profile only apply to connections through that particular Citrix Gateway Virtual Server.
    • Settings in Citrix Gateway > Global Settings > Change Global Settings apply to every Gateway Virtual Server.
    • Settings in AAA Group > Policies > Session Policy/Profile apply to every Gateway Virtual Server.
    • If you want a particular Gateway Virtual Server to override AAA or Global, your only choice is to bind a Session Policy to the Gateway Virtual Server with a lower priority number than the AAA Bind Points.

AAA Groups are a critical component of Citrix Gateway VPN configuration:

  • Group extraction – Make sure the LDAP Policy/Server is configured to extract to the user’s Active Directory Groups.
  • Create AAA Groups on the Citrix ADC that match exactly (case sensitive) with the user’s Active Directory Group Name.
    • Default Syntax and AD Groups – An alternative to AAA Groups is to use HTTP.REQ.USER.IS_MEMBER_OF("MyADGroup") Default Syntax expressions. However, Default Syntax does not support Endpoint Analysis. And Default Syntax only applies to Session Policies and Authorization Policies, so you might still need AAA Groups for Bookmarks, Intranet Applications, and Intranet IPs.
  • You can bind policies and other Gateway objects to the AAA Group, and these bindings only affect that particular AAA Group. These bindings include:
  • If the user belongs to multiple AAA Groups, then policies are applied as follows:
    • Session Policies – the settings are merged, unless there’s a conflict. If a conflict, then the policy with the lowest priority number wins.
    • Bookmarks, Intranet Applications, and Authorization Policies are merged.
    • Intranet IPs (IP Pool) are probably random allocation. It’s probably best to make sure a user only belongs to one AAA Group that assigns Intranet IPs.
  • You can also create local AAA Groups that are unrelated to Active Directory groups. There are several ways of getting users into these local AAA groups:
    • Create local AAA Users and assign them to the AAA Group
    • Configure Session Policy/Profile with a Client Security Check String (EPA Scan). If the scan succeeds, users are placed into local Authorization AAA Groups. If the scan fails, then users are placed into a local Quarantine AAA Group, and removed from all other AAA Groups.
    • When users are authenticated with a particular authentication server, the authentication server can be configured to place users into a Default Authentication Group. This lets you apply different Session Policy/Profiles (and other Gateway objects) depending on how the user authenticated.

Citrix Gateway supports Client Security Expressions (Endpoint Analysis expressions) at four different locations:

  • nFactor (Authentication Virtual Server) Advanced EPA Policy and EPA Action – this is the preferred method in ADC 13 and newer since Classic EPA is supposed to be removed in ADC 13.1 and newer. See nFactor EPA for details.
  • Classic Preauthentication Policy Expression
    • If the EPA Scan succeeds, then the user is allowed to login.
    • If the EPA Scan fails, then the user is not allowed to login.
    • Preauthentication Policies are bound to Citrix Gateway Virtual Servers only, and thus applies to all users of that Virtual Server.
  • Classic Session Policy Expression – Note: Advanced Session Policies do not support EPA expressions. Use nFactor instead.
    • This type of EPA Scan is configured in the Session Policy Expression, not the Session Profile.
    • If the EPA Scan succeeds, then the settings in the Session Profile are applied to the session.
    • If the EPA Scan fails, then the Session Profile is ignored. Other Session Policies expressions are still evaluated. Remember, Session Policy/Profiles merge, so all applicable Session Policies must be considered.
    • A limitation of this EPA method is that nothing negative happens. Instead, you typically design higher priority number (lower priority) Session Policies with restrictive settings so that if the EPA Scans fail, then users still get something. For example, you can configure your highest priority number Session Policy/Profile with StoreFront (ICA Proxy) only. In the lower priority number Session Policies/Profiles, VPN might be enabled, but only if the EPA scan succeeds. More restrictive Session Profiles usually uncheck Client Choices, and enable Clientless Access or ICA Proxy.
    • This method of EPA Scans is used in SmartAccess and SmartControl configurations.
    • EPA expressions are not supported in Default Syntax, so you’ll need to use Classic Syntax instead.
  • Session Profile > Security tab > Advanced Settings > Client Security Check String
    • If the EPA Scan succeeds, add the user to the listed Authorization AAA Groups.
    • If the EPA Scan fails, add the user to the selected Quarantine Group, and remove the user from all other AAA Groups.
    • If Quarantine Group is not defined, then prevent SSL VPN. Other methods of connecting (Clientless, StoreFront), still work.
  • Assigning EPA scans to Session Policies and Session Profiles is also known as Post-Authentication EPA Scans.
  • If Endpoint Analysis is configured anywhere, then an Endpoint Analysis plug-in is downloaded to the Windows or Mac client.

Prerequisites

Gateway Universal Licenses

Except for ICA Proxy, all Citrix Gateway connection methods require a Citrix Gateway Universal License for each concurrent session. Go to System > Licenses.

On the right, make sure Maximum Citrix Gateway User licenses are installed. Most Citrix ADC Editions come with built-in licenses. For example, Citrix ADC Premium Edition comes with Unlimited Gateway licenses.

DNS Name Servers

DNS usually needs to function across the VPN tunnel. Go to Traffic Management > DNS > Name Servers to add DNS servers.

In ADC 13.0 build 71.44 and newer, VPN plug-in for Windows supports Secure DNS update. This feature is disabled by default. To enable it, create the following on the client device: (source = 13.0-71.44 release notes) 💡

  • HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Secure Access Client\secureDNSUpdate value of type REG_DWORD and set it to 1.
    • When you set the value to 1, the VPN plug-in tries the unsecure DNS update first. If the unsecure DNS update fails, the VPN plug-in tries the secure DNS update.
    • To try only the secure DNS update, you can set the value to 2.

AAA Groups

  1. Edit your LDAP Policy/Server, and make sure Group Extraction is configured. Configure the Group Attribute and the Sub Attribute Name. This causes Citrix ADC to extract the user’s AD groups when the user logs in using LDAP.
  2. Go to Citrix Gateway > User Administration > AAA Groups.
  3. On the right, click Add.
  4. Enter a case sensitive group name that matches the group name in Active Directory. Click OK.
  5. On the right, in the Advanced Settings column, you can see the types of objects that can be bound to AAA Groups. These objects are detailed later in this post.

Create Session Profile

To enable SSL VPN: first create the Session Profile. Then create a Session Policy.

You can create multiple Session Policies/Profiles with different settings. Then you can bind these Session Policies to AAA groups and/or Citrix Gateway Virtual Servers. The Session Profiles are merged, and if conflicts, lower priority bind points win.

To enable SSL VPN in a Session Profile:

  1. On the left, expand Citrix Gateway, expand Policies, and click Session.
  2. On the right, switch to the Session Profiles tab, and click Add.
  3. Name the profile VPN or similar.
  4. In Session Profiles, every field has an Override Global checkbox to the right of it. If you check this box next to a particular field, then you can configure that field, and the field in this session profile will override settings configured globally (Citrix Gateway > Global Settings > Change Global Settings), or in a lower priority (higher priority number) session policy.

Network Configuration tab

  1. In the Session Profile, switch to the Network Configuration tab.
  2. You will find a setting that lets you select a DNS Virtual Server. Or if you don’t select anything, then the tunnel will use the DNS servers configured under Traffic Management > DNS > Name Servers.

Client Experience Tab

  1. In the Session Profile, switch to the Client Experience tab. This tab contains most of the Citrix Gateway VPN settings.
  2. Override Plug-in Type, and set it to Windows/Mac OS X.
  3. On the Client Experience tab, override Split Tunnel and make your choice. Setting it to OFF will force all traffic to use the tunnel. Setting it to ON will require you to create Intranet Applications so the Citrix Gateway Plug-in will know which traffic goes through the tunnel, and which traffic goes directly out the client NIC (e.g. to the Internet). REVERSE means all traffic goes through the tunnel except for the addresses defined in Intranet Applications.
  4. On the Client Experience tab, there are timers that can be configured. Global Settings contains default timers, so you might want to configure this Session Profile to override the defaults and increase the timeouts. See Configuring Time-Out Settings at Citrix Docs for details.
    1. Client Idle Time-out is a Citrix Gateway Plug-in timer that disconnects the session if there is no user activity (mouse, keyboard) on the client machine.
    2. Session Time-out is a Citrix Gateway timer that disconnects the session if there is no network activity for this duration.
    3. In addition to these two timers, on the Network Configuration tab, under Advanced Settings…
    4. There’s a Forced Timeout setting.
  5. By default, once the VPN tunnel is established, a portal page appears containing Gateway Bookmarks, and StoreFront published icons. An example of the portal page in the RfWebUI theme is shown below:

    1. The X1 theme is shown below:
  6. On the Client Experience tab, the Home Page field lets you override the the default portal page, and instead display a different webpage (e.g. Intranet). This homepage is displayed after the VPN tunnel is established (or immediately if connecting using Clientless Access).
  7. Citrix Gateway can automatically start the VPN tunnel whenever the user is remote. This method only starts the VPN Tunnel after the user is logged into Windows.
    1. On the Client Experience tab, click the plus icon next to AlwaysON Profile Name.
    2. Give the profile name. Hover over the question marks to see what each of them does.
    3. Then click Create.
    4. More info at AlwaysON at Citrix Docs.
  8. Citrix Gateway 12.1 build 51 and newer also support the VPN Client establishing a tunnel before the user logs into Windows. The pre-logon AlwaysOn Service feature requires certificate-based authentication and registry keys on the client device. See AlwaysOn service for Windows at Citrix Docs. 💡
  9. Additional VPN settings can be found by clicking Advanced Settings near the bottom of the Client Experience tab.
  10. Under Client Experience > Advanced Settings, on the General tab, there are settings to run a login script at login, enable/disable Split DNS, and enable Local LAN Access. Use the question marks to see what they do.
  11. Note: if Split Tunnel is OFF, and if Split DNS is set to REMOTE, Citrix Gateway only returns one IP address to DNS queries. This behavior can be changed by following Citrix CTX200243 DNS Query Responds with Only One IP to Client PC When Connected Through NetScaler Gateway Full VPN.
  12. Under Client Experience > Advanced Settings, on the General tab, is a checkbox for Client Choices. This lets the user decide if they want VPN, Clientless, or ICA Proxy (StoreFront). Without Client Choices, one of the connection methods will occur automatically, depending on what’s enabled.
  13. An example of Client Choices is shown below:

    • On the main Client Experience tab, if you enabled Client Choices, you can set Clientless Access to Off to add Clientless to the list of available connection methods in the Client Choices screen.
    • Clientless Access is difficult to remove from the Client Choices page since you need Clientless Access for StoreFront integration. The following removal instructions were confirmed on a custom Portal Theme based on RfWebUI:
      1. WinSCP to the Citrix ADC.
      2. Navigate to /var/netscaler/logon/themes/<yourThemeName>/css.
      3. Edit the file theme.css.
      4. At the bottom of the file, add the following code: (source = CTP Sam Jacobs at NetScaler Gateway Client Choices – hide/remove Virtual Apps and Desktops at Citrix Discussions. 
        div.box:nth-child(2) {
 display:none;
}
      5. When you refresh the Client Choices page, the Clientless box should be hidden.
  14. The Client Experience > Advanced Settings section has additional tabs. A commonly configured tab is Proxy, which allows you to enable a proxy server for VPN users.

Security Tab

  1. Back in the main Session Profile, switch to the Security tab.
  2. Set the default authorization to Allow or Deny. If Deny (recommended), you will need to create authorization policies to allow traffic across the tunnel. You can later create different authorization policies for different groups of users.

Published Applications Tab

  1. On the Published Applications tab, set ICA Proxy to Off. This ensures VPN is used instead of ICA Proxy.
  2. Configure the Web Interface Address to embed StoreFront into the default Clientless Access portal page.
    • Note: for X1 theme, additional iFrame configuration is required on the StoreFront side as detailed below. RfWebUI theme does not need any StoreFront changes.
    • From Michael Krasnove: if you configured the Session Policy to direct users to StoreFront, but aren’t using RfWebUI, then placing the following code in c:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js will cause StoreFront to end the VPN tunnel when the user logs off of StoreFront. 
      var LOGOFF_REDIRECT_URL = 'https://YourGatewayFQDN.com/cgi/logout';
 
// Prevent the default "logoff" screen from being displayed
CTXS.Controllers.LogoffController.prototype._handleLogoffResult = $.noop;
 
CTXS.Extensions.afterWebLogoffComplete = function () {
 window.location.href = LOGOFF_REDIRECT_URL;
};
  3. See the ICA Proxy post for more information on integrating StoreFront with Citrix Gateway.

Other Tabs

  1. The Remote Desktop tab is detailed in the RDP Proxy post.
  2. The PCoIP tab is detailed in the PCoIP Proxy post.
  3. Click Create when you’re done creating the Session Profile.

Create Session Policy

Once the Session Profile is created, you need a Session Policy linked to it. The Session Policy contains an expression, where if true, then the Session Profile is applied.

If multiple Session Policies apply to a particular connection, then the settings in the policies are merged. For conflicting settings, the Session Policy with the highest priority (lowest priority number) wins. Session Policies bound to AAA groups only override Session Policies bound to Citrix Gateway Virtual Servers if the AAA group bind point has a lower priority number. In other words, priority numbers are evaluated globally no matter where the Session Policy is bound. You can run the command nsconmsg –d current –g pol_hits to see which Session Policies are applying to a particular connection. See CTX214588 Understanding Session Policy Priority on Different Bind Points.

You can also include Endpoint Analysis expressions in a Session Policy, so that the Session Policy only applies to machines that pass the Endpoint Analysis scan. However, EPA Scans are only supported with Classic Syntax policy expressions, and not with Default Syntax.

To create a Session Policy that is linked to a Session Profile:

  1. On the left, go to Citrix Gateway > Policies > Session.
  2. In the right pane, switch to the Session Policies tab, and click Add.
  3. Give the policy a descriptive name.
  4. Change the Profile drop-down to the VPN Profile you just created.
  5. The Expression box has an option for switching to Default Syntax.

    1. If Default Syntax, enter true in the Expression box so it always evaluates to true. If Classic Syntax, it would be ns_true instead of true.
    2. If Default Syntax, you can enter HTTP.REQ.USER.IS_MEMBER_OF("MyADGroup") to restrict the Session Profile to members of a specific AD group. In Classic Syntax, this isn’t possible in an expression, and instead you must assign the Session Policy to a AAA Group.
  6. If Classic Syntax, you can add Endpoint Analysis scans to the Expression box. If the Endpoint Analysis scan succeeds, then the session policy is applied. If the Endpoint Analysis scan fails, then this session policy is skipped, and the next one is evaluated. This is how you can allow VPN if EPA scan succeeds, but all failed EPA scans will get a different session policy that only has ICA Proxy enabled.
    1. To add an Endpoint Analysis scan, use one of the Editor links on the right.
    2. Configure OPSWAT scans in the OPSWAT EPA Editor.
    3. Configure Client Security Expressions in the Expression Editor.
    4. You can combine multiple Endpoint Analysis scan expressions using Booleans (&&, ||, !).
  7. Click Create when done.

Bind Session Policy

Most of the Citrix Gateway configuration objects can be bound to a Citrix Gateway Virtual Server, AAA Groups, or both. This section details binding of Session Policies, but the other Citrix Gateway objects (e.g. Authorization Policies) can be bound using similar instructions.

  • Objects bound directly to the Citrix Gateway Virtual Server are evaluated for every user of that Gateway Virtual Server.
  • Objects bound to a AAA Group are only evaluated for members of that AAA Group.
    • Polices bound to AAA Groups usually have lower priority numbers than policies bound to Gateway Virtual Servers, so the AAA binding can override the Gateway binding.
    • However, objects/policies bound to a AAA Group are applied to every Gateway Virtual Server on the same appliance. To override AAA bindings at a specific Gateway, you can bind lower priority number policies to the Gateway Virtual Server.

Bind the new Session Policy to a Citrix Gateway Virtual Server, or a AAA group.

To bind to a Citrix Gateway Virtual Server

  1. Edit a Citrix Gateway Virtual Server (or create a new one).
  2. To make sure ICA Only is unchecked:
    1. Click the pencil icon for the Basic Settings section.
    2. Click More.
    3. Make sure ICA Only is unchecked, and click OK to close the Basic Settings section.
    4. Note: with this box unchecked, Gateway Universal licenses are now required for all users connecting through this Gateway Virtual Server.
  3. While editing the Gateway Virtual Server, consider changing the Portal Theme to RfWebUI. This changes the default portal page to look identical to StoreFront.
  4. Scroll down to the Policies section, and click the Plus icon.
  5. In the Choose Type page, ensure the Choose Policy drop-down is set to Session.
  6. Ensure the Choose Type drop-down is set to Request, and click Continue.
  7. Click where it says Click to select.

    1. If you already have Session Policies bound to this Gateway Virtual Server, then you might have to click Add Binding first.
  8. Click the radio button next to the previously created Session Policy, and click Select.
  9. Note: you cannot mix Classic Syntax Policies and Default Syntax Policies.
  10. In the Priority field, adjust the priority number. If you want this Session Policy to override other Session Policies, then set the priority number to a low value. See CTX214588 Understanding Session Policy Priority on Different Bind Points.
  11. Click Bind.
  12. If you already have Session Policies bound to the Gateway Virtual Server, then the list of Policies is displayed. If you don’t see this list, on the left, in the Policies section, click the line that says Session Policies.
  13. From this list, you can right-click the policies to Edit Binding (priority number), or Edit Profile.
  14. If your Citrix Gateway Virtual Server is configured with a Traffic Policy for Native OTP (One Time Passwords), change the Traffic Policy expression to the following. Source = Julien Mooren at NetScaler – Native OTP is breaking SSL VPN. 
    http.req.method.eq(post)||http.req.method.eq(get) && false

Bind to AAA Group

  1. To bind to a AAA Group, go to Citrix Gateway > User Administration > AAA Groups.
  2. On the right, add a AAA group with the same name (case sensitive) as the Active Directory group name. This assumes your LDAP policies/server are configured for group extraction (Group Attribute, and Sub Attribute).
  3. Edit the AAA Group.
  4. On the right, in the Advanced Settings column, add the Policies section.
  5. Click the plus icon to bind one or more Session Policies.
  6. If you want these Session Policies to override the Session Policies bound to the Citrix Gateway Virtual Server, then make sure the Session Policies bound to the AAA Group have lower priority numbers. See CTX214588 Understanding Session Policy Priority on Different Bind Points.


  7. If a user belongs to multiple groups, then for Advanced Session Policies, see CTX289931 AAA group session policies are not applying based on priority. Classic Policies in multiple AAA Groups are lumped together and evaluated based on bind point priority number. Advanced Policies are no longer lumped together and instead each AAA Group is evaluated separately. The first AAA Group created has higher priority than later created AAA Groups unless you specify the weight when creating the AAA Group from the CLI. 💡

Citrix Gateway Plug-in

Upgrade Citrix Gateway Plug-in

Citrix ADC pushes the Gateway Plug-in (aka VPN client) to client machines. In newer builds of Citrix ADC 13.0, you can upgrade the VPN plugin on the ADC without upgrading the ADC firmware.

  1. Download the latest plugin .tgz file from https://www.citrix.com/downloads/citrix-gateway/plug-ins/citrix-gateway-windows-plug-in-clients.html.
  2. In Citrix ADC, on the left click the Citrix Gateway node. On the right, click Upgrade EPA Libraries or EPA/VPN plugins.
  3. This page shows you the versions of the currently installed plugins.
  4. Click Choose File and select the win_vpn.tgz file. Click Upgrade.
  5. Click OK when prompted that the upgrade completed successfully.
  6. Go back to the Upgrade plug-in or EPA Libraries page to see the new versions.

Citrix Gateway Plug-in Installation

Here is what the user sees when launching the VPN session for the first time. This assumes the user is an administrator of the local machine.

  1. Wait for 10 seconds for the webpage to not detect Gateway Plug-in, and then click the Download button.
  2. Run the downloaded AGEE_setup.exe.
  3. In the Please read the Citrix Gateway Plug-in License Agreement page, click Install.
  4. In the Complete the Citrix Gateway Plug-in Setup Wizard page, click Finish.
  5. Click Yes to restart your system.
  6. In ADC 13.0 build 71.44 and newer, VPN plug-in for Windows supports Secure DNS update. This feature is disabled by default. To enable it, create the following on the client device: (source = 13.0-71.44 release notes) 💡
    • HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Secure Access Client\secureDNSUpdate value of type REG_DWORD and set it to 1.
      • When you set the value to 1, the VPN plug-in tries the unsecure DNS update first. If the unsecure DNS update fails, the VPN plug-in tries the secure DNS update.
      • To try only the secure DNS update, you can set the value to 2.

Only administrators can install the Citrix Gateway Plug-in. You can download the Gateway plug-in from the NetScaler appliance at /var/netscaler/gui/vpns/scripts/vista and push it to corporate-managed machines. Or you can download VPN clients from Citrix.com. The VPN client version must match the Citrix ADC firmware version.

To deploy the Gateway Plug-in using Group Policy, see CTX124649 How to Deploy NetScaler Gateway Plug-in and Endpoint Analysis Installer Packages for Windows by Using Active Directory Group Policy.

While a VPN tunnel is established, you can open the Gateway Plug-in to see status. If the Gateway Plug-in is merged with Workspace app, right-click Workspace app, click Advanced Preferences, click Citrix Gateway Settings, and click Open.

Or, if the Gateway Plug-in icon is separated from Workspace app, then right-click the Gateway Plug-in icon, and click Open.

The hamburger menu on the left lets you see more info about the VPN tunnel.

If the Gateway VPN session isn’t established, you can open the Gateway plug-in, and login. No browser needed.

  • Gateway Plug-in 12.1 build 49 with Citrix ADC 12 build 49 support nFactor authentication (e.g. Native OTP) in the Gateway Plug-in. Older versions do not support nFactor.  💡

The Configuration page lets you enable Logging. Then the Logging page lets you collect the logs. See Citrix CTX138155 How to Collect Client VPN Logs for NetScaler Gateway.

VPN Client (Citrix Gateway Plug-in) Session Profile Settings

Separate Icons for Workspace app and Gateway

  1. By default, if Workspace app, and Citrix Gateway Plug-in, are installed on the same machine, then the icons are merged. To see the Citrix Gateway Plug-in Settings, you right-click Workspace app, open Advanced Preferences, and then click Citrix Gateway Settings. This makes it difficult to log off.

  2. You can configure the Session Profile to prevent the Citrix Gateway Plug-in from merging with Workspace app. Edit your VPN Session Policy/Profile. On the Client Experience tab…
  3. Scroll down, and check the box next to Advanced Settings.
  4. At the bottom of the General tab, check the box next to Show VPN Plugin-in icon with Receiver.
  5. This setting causes the two icons to be displayed separately thus making it easier to access the Citrix Gateway Plug-in settings, including Logoff.

Cleanup

  1. When the user logs off of VPN, a Cleanup page is displayed. This can be enabled or disabled in a Session Profile on the Client Experience tab.

  2. The cleanup options can be forced in a Session Profile on the Client Experience tab…
  3. Under Advanced Settings > Client Cleanup.

VPN Client Upgrades

  1. Whenever Citrix ADC firmware is upgraded, all users will be prompted to upgrade their VPN clients. You can edit a Session Policy/Profile, and on the Client Experience tab…
  2. Use the Upgrade drop-downs to disable the automatic upgrade.
  3. The Plugin Upgrade settings are also configurable in the Gateway Virtual Server…
  4. In the Basic Settings > More section.


Authorization Policies

If your Session Profile has Security tab > Default Authorization Action set to Deny (recommended), then create Authorization Policies to allow access across the tunnel.

  1. On the left, under Citrix Gateway, expand Policies, and click Authorization.
  2. On the right, click Add.
  3. Name the Authorization Policy.
  4. Select Allow or Deny.
  5. For the Expression, Citrix Gateway supports both Classic Syntax and Default Syntax.
    • Default Syntax gives you much greater flexibility in matching the traffic that should be allowed or denied. Hit Control+Space on your keyboard to begin building a Default Syntax expression. You typically want to identify traffic based on Destination IP Address, Destination Port Number, HTTP Request URL, HTTP Host Header, etc. Common expressions include:
      • CLIENT.IP.DST.IN_SUBNET()
      • CLIENT.TCP.DSTPORT.EQ()
      • You can also use HTTP.REQ.USER.IS_MEMBER_OF("MyADGroup") in your expressions.
    • CTX232237 NetScaler Unified Gateway Advanced Authorization Policy Support for UDP/ICMP/DNS Traffic explains new types of Authorization Policies in NetScaler 12.0 build 56 and newer.
      • CLIENT.UDP.DSTPORT.EQ(2080)
      • CLIENT.IP.PROTOCOL.EQ(ICMP)
      • CLIENT.UDP.DNS.DOMAIN.CONTAINS("citrix")
    • Note: you cannot mix both Classic Syntax and Default Syntax. You must unbind every Classic Syntax Authorization Policy before you can bind Default Syntax Authorization Policies.
  6. Click Create when done.
  7. Authorization Policies are usually bound to AAA groups. This allows different groups to have different access across the tunnel.
    1. Or, you can use HTTP.REQ.USER.IS_MEMBER_OF("MyADGroup") in your Default Syntax expressions.
  8. Edit a AAA Group at Citrix Gateway > User Administration > AAA Groups.
  9. On the right, in the Advanced Settings column, add the Authorization Policies section.
  10. Then click where it says No Authorization Policy to bind policies.

Intranet Applications

If you enabled Split Tunnel, then you’ll need to create Intranet Applications to specify which traffic goes through the tunnel.

  1. On the left, under Citrix Gateway, expand Resources, and click Intranet Applications.
  2. On the right, click Add.

    1. Enter a name for the Internal subnet.
    2. Change the Interception Mode to TRANSPARENT.
    3. Enter an IP subnet. Only packets destined for this network go across the tunnel.
      1. You typically specify a summary address for all internal subnets (e.g. 10.0.0.0/8).
      2. Alternatively, you can define minimal Intranet Application destinations as a security mechanism (assuming Split Tunnel is enabled), but Authorization Policies are more appropriate for that task.
  3. Click Create.
  4. Create additional Intranet applications for each internal subnet.
  5. Intranet Applications are usually bound to the Gateway Virtual Server, but you can also bind them to AAA Groups.
  6. On the right, in the Advanced Settings column, add the Intranet Applications section.
  7. On the left, click No Intranet Application to bind Intranet Applications.

DNS Suffix

Specify a DNS Suffix for Split DNS to function with single label DNS names. Citrix Gateway adds these DNS suffixes to DNS queries across the VPN tunnel.

  1. On the left, under Citrix Gateway, expand Resources, and click DNS Suffix.
  2. On the right, click Add.
  3. Enter the DNS Suffix, and click Create. You can add multiple suffixes.

Bookmarks

Bookmarks are the links that are displayed in the default portal interface. They can point to websites, or RDP addresses. PCoIP bookmarks come from VMware Horizon Connection Server. ICA bookmarks come from Citrix StoreFront.

  1. Under Citrix Gateway, expand Resources, and click Bookmarks.
  2. On the right, click Add.

    1. Give the bookmark a name, and display text.
    2. Enter a website or RDP address.
    3. Optionally browse to an Icon file.
    4. You typically need to check Use Citrix Gateway As a Reverse Proxy, especially for Clientless Access (rewrite without VPN) to an internal website.
    5. The other fields are for Single Sign-on through Unified Gateway.
  3. Click Create.
  4. Bookmarks (aka Published Applications > Url) are usually bound to AAA groups so different groups can have different bookmarks. But it’s also possible to bind Bookmarks to Citrix Gateway Virtual Servers.
  5. If Citrix Gateway Virtual Server, add the Published Applications section to bind Bookmarks (Url).
  6. For AAA Group, it’s the Bookmarks section.
  7. On the left, find the Published Applications section, and click No Url to bind Bookmarks.

VPN Client IP Pools (Intranet IPs)

By default, Citrix Gateway VPN clients use Citrix ADC SNIP as their source IP when communicating with internal resources. To support IP Phones or endpoint management, you must instead assign IP addresses to VPN clients.

Any IP pool you add to Citrix Gateway must be reachable from the internal network. Configure a static route on the upstream router. The reply traffic to VPN Client IPs should be routed through a Citrix ADC SNIP. Or the Citrix ADC can participate in OSPF.

When a client is assigned a client IP, this IP address persists across multiple sessions until the appliance reboots, or until the appliance runs out of IPs in the pool.

  1. Edit a Citrix Gateway Virtual Server, or a AAA group.
  2. On the right, in the Advanced Settings section, click the plus icon next to Intranet IP Addresses.
  3. On the left, click where it says No Intranet IP.
  4. Enter a subnet and netmask. Click Bind.
  5. In a Session Profile, on the Network Configuration tab, check the box next to Advanced Settings.
  6. Use the Intranet IP drop-down to configure the behavior when there are more VPN clients than available IPs in the address pool.

    1. If you set it to NOSPILLOVER, then users can only have one VPN session, as described in CTX218066 How to Limit One Session Per User on NetScaler Gateway?.


  7. To see the Client IP address, on the client side, after the tunnel is established, right-click the Citrix Gateway Plug-in, and click Open.
  8. See the Internal network address.
  9. To see the client IP on the Citrix ADC, go to Citrix Gateway, and on the right is Active user sessions.
  10. Select one of the views, and click Continue.
  11. The right column contains the Intranet IP.

StoreFront in Gateway Clientless Access Portal

If you enabled the RfWebUI theme, then no StoreFront configuration is necessary.

But if you want to embed StoreFront in the other Gateway themes (X1, Default, Green Bubble), then follow these instructions.

  1. On StoreFront, edit the file C:\Inetpub\wwwroot\Citrix\StoreWeb\web.config.
    1. On the bottom, there are three sections containing X-Frame-Options. Change all three of them from deny to allow.
    2. Also change frame-ancestors from none to self.
  2. In Citrix ADC, go to Citrix Gateway > Global Settings, and click Configure Domains for Clientless Access.
  3. Change the selection to Allow Domains, enter your StoreFront FQDN, and click the plus icon.
  4. Click OK.
  5. In a Session Policy/Profile:
    1. On the Client Experience tab, make sure Single Sign-on to Web Applications is enabled.
    2. On the Published Applications tab, configure the Web Interface Address to point to the StoreFront Receiver for Web page.
    3. Configure the Single Sign-on domain to match what’s configured in StoreFront.
    4. You might have to override the Web Interface Portal Mode.
  6. The Applications page of the 3-page portal (e.g. X1 theme) should automatically show the StoreFront published icons.

Quarantine Group

Citrix Gateway can be configured so that if Endpoint Analysis scans fail, then the user is placed into a Quarantine Group. You can bind session policies, authorization policies, etc. to this quarantine group. Policies bound to other AAA groups are ignored.

  1. Go to Citrix Gateway > User Administration > AAA Groups.

    1. Add a new local group for your Quarantined Users. This group is local, and does not need to exist in Active Directory.
    2. Bind session policies, authorization policies, etc. to your quarantine AAA group. These policies typically allow limited access to the internal network so users can remediate. Or, it might simply display a webpage telling users how to become compliant.
    3. The Session Policy bound to the Quarantine Group is usually different than the Session Policies bound to other AAA groups. You can use the variation in Session Policy names for SmartAccess.
      1. One option is to configure the Delivery Groups > Access Policy so that icons are shown for Session Policies bound to non-quarantine AAA Groups, but not for the Session Policy that is bound to the Quarantine Group.
      2. Another option is to configure Citrix Policies > Access Control to disable functionality for the Quarantine Group Session Policy, but not for other AAA Group Session Policies.
  2. Create or edit a Session Profile to include a Client Security Expression that checks for compliance.
    1. In the Session Profile, on the Security tab, check the box next to Advanced Settings.
    2. Scroll down, and check the box to the right of Client Security Check String.
    3. Use the Editor links to add an Endpoint Analysis expression.
    4. Just below the Client Security Check String, select the previously created Quarantine Group. If the Client Security Check String EPA Scan fails, then the failed users are added to the Quarantine Group and removed from all other AAA Groups.
  3. Click Create when done creating or editing the Session Profile.
  4. Create a Session Policy for the Session Profile that contains the Client Security Check String.
    1. Enter ns_true as the expression.
    2. Then click Create.
  5. Edit your Gateway Virtual Server, and bind the Session Policy/Profile that has the Client Security Check String configured.


  6. To troubleshoot Quarantine policies, use the command nsconmsg –d current –g pol_hits.
  7. Citrix ADM Gateway Insight shows users that failed EPA scans, and their quarantine status.

Related Pages

RDP Proxy – Citrix Gateway

Last Modified: Apr 16, 2021 @ 2:23 pm

88 Comments

This article applies to Citrix Gateway 13.0, Citrix Gateway 12.1, and NetScaler Gateway 12.0. Citrix ADC is the new name for NetScaler. Citrix Gateway is the new name for NetScaler Gateway.

Navigation

💡 = Recently Updated

Change Log

RDP Proxy Overview

Citrix ADC supports RDP Proxy through Citrix Gateway. No VPN required. RDP can connect through Citrix Gateway on port 443.

There are several ways of launching RDP sessions through Citrix Gateway RDP Proxy:

  • Bookmarks on the Clientless Access portal page.
    • Bookmarks can be defined by the administrator.
    • Or users can add their own RDP bookmarks.
  • After logging in, change the URL in the browser to /rdpproxy/MyRDPServer. MyRDPServer can be IP or DNS.
  • In the RfWebUI Portal Theme, the Bookmark link lets users enter an RDP address, and click Go.

Links:

Requirements

Here are some requirements for RDP Proxy:

  • Citrix ADC Advanced Edition or Premium Edition.
    • Citrix Gateway Enterprise VPX is not sufficient. It must be a full ADC license.
  • Citrix Gateway Universal Licenses for each user.
    • Most Citrix ADC Editions come with built-in Gateway Universal licenses: Citrix ADC Standard Edition = 500 licenses, Citrix ADC Advanced Edition = 1000 licenses, and Citrix ADC Premium Edition = unlimited licenses. See Feature Licensing in the Gateway Tweaks post.
  • TCP 443 opened to the Citrix Gateway Virtual Server.
  • TCP 3389 opened from the Citrix ADC SNIP to the RDP Servers.

Configuration

Enable RDP Proxy Feature

  1. Go to System > Settings, and click Configure Advanced Features.
  2. In the left column, near the bottom, check the box for RDP Proxy and click OK.

Create RDP Server Profile

You do not need a RDP Server Profile if the machines you want to RDP to are not members of any RDS Connection Broker Infrastructure. Skip to the next section to create the RDP Client Profile.

If you want Citrix Gateway to RDP Proxy to a RDSH machine that is part of an RDS Connection Broker Infrastructure (aka RDS Collection, or member of RDS Broker Farm), then you’ll need the following:

  • Citrix ADC 12.1 or newer
    • NetScaler 12.0 does not support RDSH machines connected to RDS Connection Broker.
  • RDP Server Profile to enable the 3389 listener on your Gateway Virtual Server.

RDP connections through Citrix Gateway to RDP Connection Broker members requires that the Remote Desktop Session Hosts are configured to disable the GPO setting Use IP Address Redirection located in a GPO at Computer Configuration | Policies | Administrative Templates | Windows Components | Remote Desktop Services | Remote Desktop Session Host | RD Connection Broker. Disable this setting on the RDSH machines, not the Connection Broker machine. Disabling this setting enables token-based redirection instead of IP-based redirection, which is required by RDP Proxy in Citrix Gateway.

To create the RDP Session Profile on Citrix ADC:

  1. Expand Citrix Gateway, expand Policies, and click RDP.
  2. On the right, on the Server Profiles tab, click Add.
  3. In the Create RDP Server Profile window:
    1. Give the RDP Server Profile a name.
    2. If you don’t enter an RDP IP, then it will use the Gateway VIP.
    3. If you don’t enter a RDP Port, then it will default to 3389. This is an additional port that must be opened on the firewall.
    4. Enter a new Pre Shared Key.
    5. Change RDP Redirection to ENABLE. This is a new feature in ADC 12.1. This setting enables RDS Infrastructure to work.
  4. Click Create.

Create RDP Proxy Client Profile

All RDP Proxy configurations need an RDP Client Profile.

  1. Expand Citrix Gateway, expand Policies, and click RDP.
  2. On the right, switch to the Client Profiles tab, and click Add.

    1. Give the RDP Client Profile a name, and configure the client device mappings as desired. Scroll down.
    2. For the RDP Cookie Validity field, Citrix CTX233207 says that after a HA failover, RDP Proxy session will not reconnect if the cookie has expired.
    3. If you are running ADC 12.1 or newer and need to allow RDP connections to RDS Infrastructure member machines, then enter the same Pre Shared Key that you configured in the RDP Server Profile. If you don’t need to RDP to any member of any RDS Infrastructure, then you don’t need these settings.
      • Also, for RDP Host, enter the FQDN of the Gateway Virtual Server. This is only needed for RDP Server Profiles.
    4. Click Create.

Create RDP Bookmarks

You can create administrator-defined bookmarks that can be assigned to everybody or can be assigned to specific Active Directory groups. Another option is to let each user create their own bookmarks.

  1. On the left, expand Citrix Gateway, expand Resources, and click Bookmarks.

  2. On the right, click Add.

    1. Give the Bookmark a name.
    2. For the URL, enter rdp://MyRDPServer using IP or DNS (FQDN).
      • For RDS Collections, enter the address of any RDP member of the collection. The RDP server will ask the Connection Broker to load balance across the Collection and then redirect the RDP connection to the least busy RDP server in the Collection.
      • For RemoteApp, see Citrix Discussions. Example URL: 
        rdp://rdshost1.comtoso.com?alternate shell:s:||win32calc&remoteapplicationprogram:s:||win32calc&remoteapplicationname:s:Calculator&remoteapplicationcmdline:s:&remoteapplicationmode:i:1
    3. Check the box next to Use Citrix Gateway As a Reverse Proxy,
  3. Click Create.
  4. Create more bookmarks as desired.

Edit a Session Profile

  1. Create or edit a Gateway Session Profile (Session Profiles tab).
  2. On the Security tab, set Default Authorization Action to ALLOW. Or you can use Authorization policies to control access.

  3. On the Remote Desktop tab, check Override Global, and select the RDP Client Profile you created earlier.
  4. On the Client Experience tab, set Clientless Access to On. This enables the clientless access portal that can display administrator-defined bookmarks and lets users add their own bookmarks.
  5. On the Client Experience tab of the Session Profile, decide if you want Single Sign-on to Web Applications or not. It’s required for RDS Collections but optional for RDP machines that are not members of an RDS Infrastructure. If not checked then the user will be prompted to login again when launching an RDP session.
  6. On the Published Applications tab, make sure ICA Proxy is OFF so the clientless portal is displayed.
  7. Click OK when done.

Edit Citrix Gateway Virtual Server

  1. Edit or Create your Gateway Virtual Server.
  2. In the Basic Settings section, click the pencil icon on the top right to edit it.
  3. Click More to show more settings.

    1. If the machines you are RDPing to are not members of an RDS Collection, then don’t configure RDP Server Profile. With no RDP Server Profile configured the RDP connections will be 443 to the Gateway. If you instead configure an RDP Server Profile then the RDP Connections will be 3389 or whatever port number you put in the RDP Server Profile.
    2. If you want to allow RDP to RDS Collection members, then select the RDP Server Profile that you created earlier. The RDP Server Profile enables port 3389 on the Gateway VIP. If you don’t select a RDP Server Profile, then RDP is proxied through 443 on the Gateway, but this won’t work for RDS Collection members.
    3. Scroll down. Make sure ICA Only is not checked. This means you’ll need Citrix Gateway Universal licenses for each user that connects through this Gateway.
    4. Click OK to close the Basic Settings section.
  4. Bind a certificate.
  5. Bind authentication policies.
  6. In the Policies section, bind the Session Policy that has the RDP Client Profile configured. Be mindful of policy priority.


  7. You can bind RDP Bookmarks to either the Citrix Gateway Virtual Server, or to a AAA group. To bind to the Citrix Gateway Virtual Server, on the right, in the Advanced Settings section, click Published Applications.
  8. On the left, in the Published Applications section, click where it says No Url.
  9. Bind your Bookmarks.
  10. While editing your Gateway vServer, you can also set the Portal Theme to RfWebUI. This is strongly recommended for the clientless access portal that displays the RDP bookmarks.

Configure DNS

  1. If you want to connect to RDP servers using DNS, make sure DNS servers are configured on the appliance (Traffic Management > DNS > Name Servers).
  2. If you want to use the short names instead of FQDNs, add a DNS Suffix (Traffic Management > DNS > DNS Suffix).

Use RDP Proxy

  1. Connect to your Citrix Gateway and login.
  2. If you configured Bookmarks, if RfWebUI theme, on the Apps tab, click Web and SaaS Apps.

    1. If X1 theme, the bookmarks are on the Web Apps page.
  3. If RfWebUI theme, you can click Details to mark the Bookmark as a Favorite.

  4. Or you can change the address bar to /rdpproxy/MyRDPServer. You can enter an IP address (e.g. rdpproxy/192.168.1.50) or a DNS name (/rdpproxy/myserver).
  5. If you edit the downloaded .rdp file, notice that it’s connecting on port 443.
  6. Then open the downloaded .rdp file.
  7. You can view the currently connected RDP users by going to Citrix Gateway > Policies > RDP, and on the right is the Connections tab.

Personal Bookmarks

  1. If using the RfWebUI theme, another way to launch RDP sessions is to click the Bookmark link, enter a destination DNS/IP, check the box next to RDP Link, and click Go.
  2. You can also give the Bookmark a name and Save it.
  3. Then access the saved bookmark from Apps > Personal Bookmarks.

  4. Personal bookmarks are stored in /var/vpn/bookmark on the appliance. You might want to back these up and replicate them to other Gateway appliances participating in GSLB. See NetScaler 11.1 Personal Bookmarks at Citrix Discussions.
  5. The X1 theme has an Add button on the Web Apps page.
  6. But there is no Go button. Instead, you save the Bookmark and launch it from the list.

SmartAccess / SmartControl – Citrix Gateway

Last Modified: Aug 15, 2023 @ 5:42 am

50 Comments

This article applies to NetScaler Gateway 14.1, Citrix Gateway 13.x, Citrix Gateway 12.1, and NetScaler Gateway 12.0.

Navigation

💡 = Recently Updated

Change Log

SmartAccess / SmartControl

SmartAccess and SmartControl let you change ICA connection behavior (e.g. disable client device mappings, hide icons) based on how users connect to Citrix Gateway. Decisions are based on Citrix Gateway Virtual Server name, Session Policy name, and Endpoint Analysis scan success or failure.

SmartAccess vs SmartControl:

  • SmartAccess lets you control visibility of published icons, while SmartControl does not.
  • SmartControl is configured exclusively on Citrix Gateway, while SmartAccess requires configuration on both Citrix Gateway, and inside Citrix Studio.
  • SmartControl requires Citrix ADC Premium Edition licensing, while SmartAccess is available in all Citrix ADC Editions.
    • Both features require Citrix Gateway Universal licenses for every concurrent connection.

Prerequisites

Both SmartAccess and SmartControl have the same prerequisites. You can configure SmartAccess in Citrix Virtual Apps and Desktops (CVAD) at any time, but it won’t work, until you do the following:

  1. Citrix ADC appliance license: See Feature Licensing in the Gateway Tweaks post. In summary:
    • SmartAccess is available in all editions of Citrix ADC appliances.
    • SmartControl is available only in Citrix ADC Premium Edition.
  2. Citrix Gateway Universal Licenses – On the Citrix ADC, go to System > Licenses, and make sure you have Citrix Gateway Universal Licenses allocated to the appliance.
    1. Most Citrix ADC Editions (except Citrix Gateway Enterprise VPX) come with built-in Gateway Universal licenses: Citrix ADC Standard Edition = 500 licenses, Citrix ADC Advanced Edition = 1,000 licenses, and Citrix ADC Premium Edition = unlimited licenses.
    2. Additional Citrix Gateway Universal licenses can be acquired through other means. See Feature Licensing in the Gateway Tweaks post for details.
    3. The Universal licenses are allocated to the hostname of the appliance (click the gear icon to change it), not the MAC address. In a High Availability pair, if each node has a different hostname, then you can allocate the licenses to one hostname, then reallocate to the other hostname. See Feature Licensing in the Gateway Tweaks post for details.
  3. Citrix Gateway must have ICA Only unchecked.
    1. On the Citrix ADC, go to Citrix Gateway > Virtual Servers, and edit your Gateway Virtual Server.
    2. In the Basic Settings section, click the pencil icon.
    3. Click More.
    4. Uncheck the box next to ICA Only, and click OK. This tells Citrix Gateway to start using Universal licenses and enables the SmartAccess and SmartControl features.
  4. Enable Trust XML on the Citrix Virtual Apps and Desktops (CVAD) Site/Farm:
    1. On a CVAD Controller, run PowerShell as Administrator.
    2. Run asnp citrix.* to load the snapins.
    3. Run Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true to enable Trust XML.
  5. Configure Callback URL in StoreFront:
    1. In StoreFront Console, right-click the Stores node, and click Manage Citrix Gateways.
    2. Edit a Gateway.
    3. On the Authentication Settings page, make sure a Callback URL is configured. The Callback URL must resolve to a Citrix Gateway VIP on the same appliance that authenticated the user. The Callback Gateway’s certificate must match the FQDN entered here. If you are configuring Single FQDN for internal and external, then the Callback FQDN must be different than the Single FQDN.

Once the prerequisites are in place, do the following as detailed below:

Endpoint Analysis

Endpoint Analysis (EPA) scans are completely optional. You can configure SmartControl and SmartAccess without implementing any Endpoint Analysis.

Endpoint Analysis is supported on Windows and Mac devices. Other devices, like iOS and Android, do not support Endpoint Analysis. If you want to allow mobile device connectivity, then make sure you have an access mechanism (e.g. ICA Proxy) that works if the Endpoint Analysis scan fails.

Citrix ADC 12.1 and newer support two methods of doing EPA: nFactor EPA, or Classic EPA. Classic EPA will no longer be supported in ADC 13.1 and newer so you should eventually switch to nFactor EPA.

Workspace app on Windows supports EPA when configured using nFactor EPA. Workspace app does not support Classic EPA.

nFactor EPA

EPA can be one of the factors of an nFactor flow. EPA can be performed before authentication, or after authentication.

EPA doesn’t work on iOS/Android. To skip those platforms, see CTX572334 Eliminate Advanced Endpoint Analysis scans on Mobile devices/iOS.

  1. Create an nFactor EPA Action.
    1. The easiest way to find EPA is to use the Search box on the top of the left menu. Or, navigate to Security > AAA > Policies > Authentication > Advanced Policies > EPA.
    2. The EPA Editor link on the right-side of the Expression box lets you configure EPA Expressions. See OPSWAT EPA Expressions below for more details on how to configure an Opswat expression.
    3. For SmartAccess based on the results of the EPA scan, configure the Default Group field with a new group name (doesn’t exist in Active Directory). You’ll later use the Group name in a Session Policy and use the Session Policy name in your Citrix Policy Access Filters or Delivery Group Access Control. Default Group probably only works if the EPA Factor is performed after authentication.
  2. After creating an EPA Action, create an Advanced Authentication Policy of type EPA and select the EPA Action you created earlier.
    1. The expression is either true, or an expression that defines who needs EPA scanning. If you are configuring post-authentication EPA, then you can use group membership (e.g. AAA.User.Is_Member_Of()) expressions.

  3. Create a Policy Label for the EPA Factor. Login Schema should be LSCHEMA_INT.

    1. Bind the EPA Policy to your Policy Label.
    2. If you don’t bind any other policies, then if EPA fails, then the user shown the Access Denied page. If you want authentication to continue even with a failed EPA scan, then bind another policy to the Policy Label.
    3. Create an Advanced Authentication Policy named similar to NoAuth and change Action Type to NO_AUTHN. Expression = true. Bind the NoAuth policy to the Policy Label.
    4. The final Policy Label should have an EPA Factor with Goto = NEXT and the second policy as NoAuth.
  4. In earlier factors that authenticate the user, when binding an authentication policy, click in the Select Next Factor field and select your EPA Policy Label.

    • In the earlier authentication factor, edit the Login Schema Profile, click More, and check the box next to Enable Single Sign On Credentials. EPA as later factor overrides the password collected in earlier factors causing Single Sign-on to StoreFront to fail and this checkbox fixes that problem.
  5. Create a Citrix Gateway Session Policy that is applied when the EPA factor succeeds.
    1. Go to Citrix Gateway > Policies > Session.
    2. On the tab named Session Profiles, click Add.
    3. Name it FullAccess or similar and click Create. The Session Profile does not need any settings.
    4. Switch to the tab named Session Policies and click Add.
    5. Select the Profile you just created.
    6. If you are doing Advanced Policies, then the Expression is AAA.USER.IS_MEMBER_OF(“GroupName”) where “GroupName” is the name of the Default Group you specified when you created the EPA Action. Click Create. If you are doing Classic Policies, then the expression is ns_true.
  6. If your session policy is Advanced syntax, then bind the Session Policy to your Gateway vServer.
    1. Go to Citrix Gateway > Virtual Servers and edit an existing vServer.
    2. Scroll all the way down to the Policies section and click the Session Policies line.
    3. Add Binding and select the Session Policy you will use for SmartAccess. Priority doesn’t matter.
  7. For both Advanced Session Policies and Classic Session Policies, create a AAA Group that matches the Default Group you specified in the EPA Action. CTX278960 says this is also required for IS_MEMBER_OF expressions.
  8. If you are doing Classic Session Policies, then create bind the Session Policy to the AAA Group. If you are doing Advanced Session Policies bound directly to the Gateway Virtual Server, then you don’t need to bind anything to the AAA Group.
  9. You can now use the Session Policy in your SmartAccess configuration. See the SmartAccess section below for more details.

Classic EPA Policies

There are two methods of Classic Endpoint Analysis: pre-authentication and post-authentication. For pre-authentication, configure an Endpoint Analysis expression in a Preauthentication Policy. For post-authentication, configure the Endpoint Analysis expression on one or more Session Policies.

  • With a Preauthentication Policy, if the Endpoint Analysis scan fails, then users can’t login.
  • With a Postauthentication Policy, Endpoint Analysis doesn’t run until after the user logs in. Typically, you create multiple Session Policies. One or more Session Policies have Endpoint Analysis expressions. Leave one policy without an Endpoint Analysis expression so there’s a fallback in case the client device doesn’t support Endpoint Analysis (e.g. mobile devices). The name of the Session Policy is then used later in Citrix Policies and Citrix Delivery Groups.
    • Inside the Session Profile is a field for Client Security expression, which supports an EPA expression. This field is for VPN only, and does not affect SmartAccess.

Preauthentication Policies and Profiles are configured at Citrix Gateway > Policies > Preauthentication.

  1. On the right, switch to the Preauthentication Profiles tab, and create a Preauthentication Profile to allow access.

  2. Switch to the Preauthentication Policies tab, and create a Preauthentication Policy with an EPA expression. Select the Request Action that allows access.

  3. The right side of the Expression box has links to create EPA expressions, as detailed below.

Classic Post-authentication Policies and Profiles are configured at Citrix Gateway > Policies > Session.

  1. When creating a Session Policy, the right side of the Expression box has links to create EPA expressions, as detailed below.
  2. Classic Syntax vs Default Syntax – EPA expressions can only be added to Classic Syntax Policies. If you click Switch to Default Syntax, then the OPSWAT EPA Editor disappears. Use nFactor EPA instead.
  3. If you edit a Session Profile, on the Security tab…
  4. Under Advanced Settings, you will see a Client Security Check String box that lets you enter an EPA Expression. This field applies only to VPN and does not affect SmartAccess. Also, this field does not function if your Session Policy is Advanced instead of Classic.

EPA Expressions

Citrix ADC has two Endpoint Analysis engines: the original Client Security engine, and the newer OPSWAT EPA engine.

OPSWAT EPA Expressions

To configure OPSWAT EPA expressions:

  1. When creating an nFactor EPA Action, click the EPA Editor link.

    • When creating a Classic Preauthentication Policy, or Session Policy, click the OPSWAT EPA Editor link.
  2. Use the drop-down menus to select the scan criteria.
  3. You will see some fields with a plus icon that lets you configure more details for the scan.

    • Note: the text in these policy expressions is case sensitive.
  4. Then click Done.

Additional OPSWAT EPA Info

See the following links for more Advanced EPA information:

Original Client Security Expressions

To configure the original Client Security expressions:

  1. When creating a Classic Preauthentication Policy or Classic Session Policy, click the Expression Editor link.
  2. Change the Expression Type to Client Security.
  3. Use the Component drop-down to select a component.
    1. A common configuration is to check for domain membership as detailed at Citrix CTX128040 How to Configure a Registry-Based Scan Expression to Look for Domain Membership.
    2. Citrix CTX128039 How to Configure a Registry-Based EPA Scan Expression on NetScaler to Look for the Active Device or Computer Name of an Explicit Workstation

Once the Classic Preauthentication and/or Classic Session Policies are created, bind them to your Citrix Gateway Virtual Server:

  1. Edit a Citrix Gateway Virtual Server.
  2. Scroll down to the Policies section, and click the plus icon.
  3. Select either Preauthentication or Session, and select the policy you already created. Then click Bind.
  4. Session Policies with EPA Expressions are typically higher in the list (lower priority number) than non-EPA Session Policies.

EPA Libraries

In NetScaler 12.0 build 57 and newer, the EPA Libraries are updated out-of-band.

  1. Download the latest EPA libraries.
  2. In the Citrix ADC menu, click the Citrix Gateway node.
  3. On the right, in the left column, click Upgrade EPA Libraries.
  4. Click Choose File
  5. Browse to one of the .tgz library files, and click Open.
  6. Click Upgrade.
  7. Click OK when prompted that EPA Library upgraded successfully.
  8. Click Upgrade EPA Libraries again.
  9. Click Choose File.
  10. Browse to the other .tgz EPA library file, and click Open.
  11. Click Upgrade.
  12. Click OK when prompted that upgraded successfully.
  13. To see the versions, click Upgrade EPA Libraries.

EPA Plug-in

The EPA plug-in is automatically deployed when the user connects to Citrix Gateway – either before the logon page, or after the logon page.

To pre-deploy EPA plug-in, see CTX124649 How to Deploy NetScaler Gateway Plug-in and Endpoint Analysis Installer Packages for Windows by Using Active Directory Group Policy. This article describes how to extract the plug-in .msi file, and deploy using Group Policy.

EPA and Portal Themes

The webpages displayed to the user when downloading the EPA plug-in and running the EPA plug-in can be customized by editing a Portal Theme.

Look in the Advanced Settings column on the right for the three EPA pages. Citrix CTX222812 How to Customize Custom Error Messages for NetScaler Gateway EPA Scans.

EPA Troubleshooting

From Citrix CTX209148 Understanding/Configuring EPA Verbose Logging Feature:

  1. Go to Citrix Gateway > Global Settings.
  2. On the right, click Change Global Settings.
  3. On the Security tab, click Advanced Settings.
  4. Scroll down, check the box next to Enable Client Security Logging, and click OK.
  5. When the scan fails, the user is presented with a Case ID.
  6. You can then grep /var/log/ns.log for the Case ID. Or search your syslog.

For client-side logging, on the client machine, go to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Secure Access Client.

  • Make a DWORD value named “EnableEPALogging“, and set the value to 1.
  • After attempting the scan again, you’ll find the file %localappdata%\Citrix\AGEE\epaHelper_epa_plugin.txt with details for each scan expression.

NetscalerAssasin EPA OPSWAT Packet flow and Troubleshooting shows a Wireshark trace of an EPA scan.

SmartAccess

Links:

Make sure the prerequisites are completed. This includes:

  • ICA Only unchecked on Citrix Gateway Virtual Server
  • Gateway Universal licenses installed
  • Callback URL configured at StoreFront
  • Trust XML enabled on Delivery Controllers

SmartAccess is configured in two places:

  • Delivery Group > Access Policy page
  • Citrix Policy (user half only) > filters > Access control

In both cases, you enter the name of a matching Gateway Virtual Server, and the name of a matching Session Policy (or Preauthentication Policy).

  • Set AG farm name or Site or Farm name to the name of the Citrix Gateway Virtual Server.
  • Set Access condition or Filter to the name of the Citrix Gateway Session Policy (or Preauthentication Policy).
  • You can use * as a wildcard in either field.
  • The matching Citrix Gateway Session Policy typically has an EPA Expression configured in the Policy Rule. That way the Session Policy only applies to connections that match the EPA Expression.

Icon visibility – Access Control at the Delivery Group controls visibility of icons published from that Delivery Group.

  • Access Control on a Delivery Group is Allow only. Icons are hidden from non-matching connections.
  • You can uncheck Connections through Citrix Gateway to hide the published icons from all Citrix Gateway connections.
  • It’s not possible to hide individual published applications. You can hide all applications from a single Delivery Group, or none of them. If you need more granularity, then you’ll have to split the applications onto different Delivery Groups.
  • App Groups do not have an Access Control option. It’s Delivery Groups only.

Citrix Policy Settings – Access Control filter on a Citrix Policy determines if the Policy settings apply or not.

  • Access Control filter applies to User Settings only. It’s not configurable for Computer Settings.
  • You typically configure the Unfiltered Citrix Policy to block all client device mappings. Then you configure a higher priority Citrix Policy with Access Control filter to re-enable client device mappings for endpoint machines that match the Session Policy and EPA Expression.

When connected to a session, Director shows SmartAccess Filters on the Session Details page. Notice the Farm Name (Gateway Virtual Server name) and Filter Name (Session Policy name)

SmartControl

The SmartControl feature lets you configure some of the SmartAccess functionality directly on the appliance. See Configuring SmartControl at Citrix Docs for detailed instructions.

  • Note: SmartControl requires Citrix ADC Premium Edition. If you don’t have Premium Edition, you can instead configure SmartAccess.
  • SmartControl cannot hide published icons. If you need that functionality, configure SmartAccess, either as a replacement for SmartControl, or as an addition to SmartControl.

To configure SmartControl:

  1. Make sure the Prerequisites are completed. This includes: ICA Only unchecked and Gateway Universal licenses installed. Callback URL and Trust XML are not needed.
  2. If you are using a Preauthentication Policy to run an Endpoint Analysis scan:
    1. Edit the Preauthentication Profile.
    2. Configure the Default EPA Group with a new group name. You’ll use this group name later.
  3. If you are instead using a Session Policy to run the post-authentication Endpoint Analysis scan:
    1. Edit the Session Profile
    2. On the Security tab, use the Smartgroup field to define a new group name for users that pass the scan. You’ll use this group name later.
  4. On the left, expand Citrix Gateway, expand Policies, and click ICA.
  5. On the right, switch to the Access Profiles tab, and click Add.

    1. Configure the restrictions as desired, and click Create.
  6. Switch to the ICA Action tab, and click Add.

    1. Give the ICA Action a name.
    2. Select the ICA Access Profile.
    3. Click Create.
  7. Switch to the ICA Policies tab, and click Add.
  8. In the Create ICA Policy page, do the following:
    1. Give the ICA Policy a name.
    2. Select the previously created ICA Action.
    3. Enter an expression. You can use HTTP.REQ.USER.IS_MEMBER_OF(“MyGroup”).NOT where MyGroup is the name of the SmartGroup you configured in the session profile or preauth scan.
  9. Click Create when done.
  10. Edit your Gateway Virtual Server.
    1. Scroll down to the Policies section, and click the plus icon.
    2. Change the Choose Type drop-down to ICA, and click Continue.
    3. Select the SmartControl policy you created earlier, and click Bind.

Related Pages

Global Server Load Balancing (GSLB) – Citrix ADC

Last Modified: Mar 30, 2023 @ 10:18 am

231 Comments

Navigation

💡 = Recently Updated

Change Log

GSLB Planning

GSLB is nothing more than DNS. GSLB receives a DNS query, and then GSLB sends back an IP address, which is exactly how a DNS server works. The user then connects to the returned IP, which doesn’t even need to be on a NetScaler ADC.

GSLB can do some things that DNS servers can’t do:

  • Don’t give out an IP address unless it is UP (monitoring)
    • If the active IP address is down, then give out the passive IP address (active/passive) instead
  • Give out the IP address that is closest to the user (proximity load balancing)
  • Give out different IPs for internal users vs external users (DNS View)

GSLB is only useful if you have a single DNS name that could resolve to two or more IP addresses. If there’s only one IP address, then use normal DNS instead.

Citrix Blog Post Global Server Load Balancing: Part 1 explains how DNS queries work and how GSLB fits in.

Citrix has a good DNS and GSLB Primer.

When configuring GSLB, don’t forget to ask “where is the data?”. See Citrix Blog Post XenDesktop, GSLB & DR – Everything you think you know is probably wrong!

GSLB Configuration Overview

GSLB Configuration can be split between one-time steps for GSLB infrastructure, and repeatable steps for each GSLB-enabled DNS name.

One-time GSLB Infrastructure configuration

  1. Create ADNS listener on each ADC pair – DNS clients send DNS queries to the ADNS listeners. GSLB resolves a DNS query into an IP address, and returns the IP address in the DNS response.
  2. Create GSLB Sites (aka MEP Listener) – GSLB Sites usually correspond to different datacenters. GSLB Sites are also the IP address endpoints for Citrix ADC’s proprietary Metric Exchange Protocol (MEP), which is used by GSLB to transmit proximity, persistence, and monitoring information.
  3. Import Static Proximity Database – Citrix ADC includes a database that can be used to determine the geographical location of an IP address. Or you can subscribe to a geolocation service, and import its database.
  4. Delegate DNS sub-zone to ADC ADNS – in the original DNS zone, create a new sub-zone (e.g. gslb.company.com), and delegate the sub-zone to all ADNS listeners.

Repeatable GSLB Configuration for each DNS name:

  1. Create one or more GSLB Services per DNS name, and per IP address response – each GSLB Service corresponds to a single IP address that can be returned in response to a DNS Query.
    • Optionally, bind a Monitor to each GSLB Service. Monitors determine if the GSLB Service is up or not.
  2. Create a GSLB Virtual Server per DNS name
    • Bind a DNS name to the GSLB Virtual Server.
    • For active/active – bind multiple GSLB Services to the GSLB Virtual Server, configure a load balancing method (e.g. proximity), and configure site persistence.
    • For active/passive – bind the active GSLB Service. Create another GSLB Virtual Server with passive GSLB Service and configure as Backup Virtual Server.
      • Alternatively, NetScaler ADC 13.1 and newer let you bind GSLB Services in priority order. See Citrix Docs for details.
  3. Create CNAME records for each delegated DNS name – in the main DNS zone, create a CNAME that maps the original DNS name to the delegated sub-zone. For example, CNAME citrix.company.com to citrix.gslb.company.com.

You will create separate GSLB Services, separate GSLB Virtual Servers, and separate CNAMEs for each DNS name. If you have a bunch of DNS names that you want to GSLB-enable, then you’ll repeat these steps for each GSLB-enabled DNS name.

Each datacenter has a separate ADNS listener IP address. DNS is delegated to all GSLB ADNS Listener IPs, and any one of them can respond to the DNS query. Thus, all ADC pairs participating in GSLB should have the same Per-DNS name configuration.

One ADC appliance for both public DNS/GSLB and internal DNS/GSLB?

GSLB can be enabled both publically and internally. For public GSLB, configure it on DMZ ADC appliances, and expose the DNS listener to the Internet. For internal GSLB, configure it on separate internal ADC appliances/instances, and create an internal DNS listener.

Each ADC appliance only has one DNS table, so if you try to use the same ADC for both public DNS and internal DNS, then be aware that external users can query for internal GSLB-enabled DNS names.

  • As described by Phil Bossman in the comments, you can use a Responder policy to prevent external users from reading internal DNS names. 
    add policy patset GSLB_INTERNAL
bind policy patset GSLB_INTERNAL internalHostname.gslb.domain.com -index 1
add responder action DNS_Empty_Response respondwith DNS.NEW_RESPONSE
add responder policy GSLB_DNS_Empty_Response "(!(CLIENT.IP.SRC.IN_SUBNET(10.0.0.0/8)||CLIENT.IP.SRC.IN_SUBNET(192.0.0.0/16)||CLIENT.IP.SRC.IN_SUBNET(172.0.0.0/12)) && DNS.REQ.QUESTION.DOMAIN.CONTAINS_ANY(\"GSLB_INTERNAL\"))" DNS_Empty_Response
bind responder global GSLB_DNS_Empty_Response 100 END -type DNS_REQ_DEFAULT

One appliance resolving a single DNS name differently for internal and public

Let’s say you have a single DNS name citrix.company.com. When somebody external resolves the name, it should resolve to a public IP. When somebody internal resolves the name, it should resolve to an internal IP.

For internal GSLB and external GSLB of the same DNS name on the same ADC appliance, you can use DNS Policies and DNS Views to return different IP addresses depending on where users are connecting from. See Citrix CTX130163 How to Configure a GSLB Setup for Internal and External Users Using the Same Host Name.

If the Internet circuit in the remote datacenter goes down, then this should affect public DNS, since you don’t want to give out a public IP that isn’t reachable. But do you also want an Internet outage to affect internal DNS? Probably not. In that case, you would need different GSLB monitoring configurations for internal DNS and external DNS. However, if you have only a single GSLB Virtual Server with DNS Views, then you can’t configure different monitoring configurations for each DNS View.

To work around this limitation, create two separate GSLB Virtual Servers with different monitoring configurations. Internal DNS uses a CNAME record to reach the GSLB Virtual Server configured for internal monitoring:

  • External citrix.company.com:
    • Configure ADC GSLB for citrix.company.com.
    • On public DNS, delegate citrix.company.com to the ADC DMZ ADNS services.
  • Internal citrix.company.com:
    • Configure ADC GSLB for citrixinternal.company.com or something like that.
    • On internal DNS, create CNAME for citrix.company.com to citrixinternal.company.com
    • On internal DNS, delegate citrixinternal.company.com to ADC internal ADNS services.

Remote Internet Monitoring

For public DNS/GSLB, you don’t want to give out a remote public IP address if that remote public IP address is not reachable. That means the local ADC will need to somehow determine if the remote datacenter has Internet connectivity or not. Here are some methods of verifying the remote Internet connection:

  • Route GSLB Metric Exchange Protocol (MEP) across the Internet. If MEP goes down, then all IP addresses associated with the remote GSLB Site are assumed to be down, and thus the local ADC will stop giving out those remote IP addresses.
  • Bind explicit monitors to each GSLB Service, and ensure the monitoring is routed across the Internet.

GSLB IP Addresses

GSLB is separate from data traffic. The GSLB IP addresses are separate from the IP addresses needed for data.

Some GSLB-specific IP Addresses are needed on each ADC pair:

  • ADNS Listener IP: An ADC IP that listens for DNS queries.
    • The ADNS listener IP is typically an existing SNIP on the appliance.
    • For external DNS, create a public IP for the ADNS Listener IP, and open UDP 53 and TCP 53, so Internet-based DNS servers can access it.
    • A single ADC appliance can have multiple ADNS listeners – typically one ADNS listener for public, and another ADNS listener for internal.
  • GSLB Site IP / MEP listener IP: An ADC IP that will be used for ADC-to-ADC GSLB communication. This communication is called MEP or Metric Exchange Protocol. MEP transmits the following between GSLB-enabled ADC pairs: load balancing metrics, proximity, persistence, and monitoring.
    • GSLB Sites – On ADC, you create GSLB Sites. GSLB Sites are the endpoints for the MEP communication. Each ADC pair is configured with the MEP endpoints for the local appliance pair, and all remote appliance pairs.
    • TCP Ports – MEP uses port TCP 3009 or TCP 3011 between the ADC pairs. TCP 3009 is encrypted.
    • The ADNS IP address can be used as the MEP endpoint IP.
    • MEP endpoint can be any IP – The MEP endpoint IP address can be any IP address and does not need to be a SNIP or ADNS.
    • One MEP IP per appliance – there can only be one MEP endpoint IP address on each ADC pair.
    • Route MEP across Internet? – If you route MEP across the Internet, and if the MEP connection is interrupted, then Internet at one of the locations is probably not working. This is an easy way to determine if remote Internet is up or not. If you don’t route MEP across the Internet, then you’ll need to configure every remote-site GSLB Service with a monitor to ensure that the remote Internet is up.
      • Public IPs for MEP Enpoints – if you route MEP across the Internet, then you’ll need public IPs for each publically-accessible MEP endpoint IP address.
      • Public Port for MEP: Open port TCP 3009 between the MEP Public IPs. Make sure only the MEP IPs can access this port on the other ADC . Do not allow any other device on the Internet to access this port. Port 3009 is encrypted.
    • GSLB Sync Ports: To use GSLB Configuration Sync, open ports TCP 22 and TCP 3008 (secure) from the NSIP (management IP) to the remote public MEP IP. The GSLB Sync command runs a script in BSD shell and thus NSIP is always the Source IP.
  • Public IP Summary: In summary, for public GSLB, if MEP and ADNS are listening on the same IP, then you need one new public IP that is NAT’d to the DMZ IP that is used for ADNS and MEP (GSLB Site IP).
    • Each datacenter has a separate public IP.
    • DNS is delegated to all public ADNS IP listeners.

GSLB Wizard

NetScaler 12 and Citrix ADC 12.1 and newer have a GSLB Wizard at Traffic Management > GSLB.

However, the wizard doesn’t really save any time or steps, so it won’t be documented here.

ADNS Listener

  1. At System > Network > IPs, identify a Citrix ADC-owned IP that you will use as the ADNS listener. This is typically a SNIP.
  2. Create a public IP for the ADNS Service IP and configure firewall rules. UDP 53 and TCP 53 need to be opened from the Internet to the public IP that NATs to the ADNS Listener IP address.
  3. On the left, expand Traffic Management > Load Balancing, and click Services.
  4. On the right, click Add.

    1. In the Basic Settings section, do the following:
      1. Name the service ADNS or similar.
      2. In the IP Address field, enter an appliance SNIP.
      3. In the Protocol drop-down, select ADNS.
    2. Click OK.
    3. No other configuration is needed so scroll down and click Done to close the Load Balancing Service properties.
  5. Highlight the ADNS service you just added and then click Add to create another Service while copying some of the settings from the previously created Service.

    1. Change the Service Name to ADNS_TCP or similar.
    2. Change the Protocol drop-down to ADNS_TCP.
    3. Click OK to close the Basic Settings section.
    4. No other configuration is needed so scroll down and click Done to close the Load Balancing Service properties.
  6. You should have two ADNS services on the same IP address: one for ADNS, and one for ADNS_TCP.
  7. On the left of the console in the menu, expand System, expand Network, and then click IPs.
  8. On the right, you’ll see the SNIP is now marked as the ADNS svc IP.
  9. Repeat the ADNS configuration on the other appliance pair in the other datacenter. Except the other appliance will use its own SNIP as the ADNS Service listener IP address.
  10. Your ADC appliances are now DNS servers.

DNS Security

  1. Citrix ADC includes DNS Security Options, at Security > DNS Security, which can protect your ADNS service.
  2. To protect ADNS, set the Profile to All DNS Endpoints.

Metric Exchange Protocol

This section details MEP configuration between two GSLB Sites. See Citrix Docs for larger Parent-Child Topology Deployment Using the MEP Protocol.

GSLB Sites

  1. The local GSLB Site IP can be any IP, including the same SNIP that you used for ADNS.
  2. Open the firewall rules for Metric Exchange Protocol. The GSLB Site IP on this appliance pair uses TCP 3009 to communicate with the GSLB Site IP on the other appliance pair.
  3. On the left, expand Traffic Management, right-click GSLB, and enable the feature.
  4. Expand GSLB, and click Sites.
  5. On the right, click Add.
  6. In the Create GSLB Site page, do the following:
    1. We’re adding the local site first. Enter a descriptive name for the local site.
    2. In the Site Type drop-down, select LOCAL.
    3. In the Site IP Address field, enter an IP that this appliance will listen for MEP traffic. This is typically a SNIP and can the same as your ADNS IP.
    4. For Internet-routed GSLB MEP, in the Public IP Address field, enter the public IP that is NAT’d to the GSLB Site IP.
    5. For internal GSLB MEP, there is no need to enter anything in the Public IP field.
  7. Scroll down, and click Create, to close the Create GSLB Site page.

  8. Go back to System > Network > IPs, and notice that the IP is now marked as a GSLB site IP.
  9. If you want to use the GSLB Sync Config feature, then you’ll need to edit the GSLB site IP, and enable Management Access.

    1. Scroll down, and enable Management Access. SSH is all you need.
  10. Go to the other appliance pair, and also create the Local GSLB site using its GSLB site IP, and its public IP that is NAT’d to the GSLB site IP.

    1. In System > Network > IPs on the remote appliance, there should now be a GSLB site IP. If GSLB Sync is desired, enable management access on that IP and ensure SSH is enabled.
  11. Now on each appliance, add another GSLB Site, which will be the Remote GSLB site.
  12. In the Create GSLB Site page, do the following:
    1. Enter a descriptive name for the remote site.
    2. Select REMOTE as the Type.
    3. Enter the other appliance’s actual GSLB Site IP as configured on the appliance. This IP does not need to be reachable.
    4. In the Public IP Address field, enter the public IP that is NAT’d to the GSLB Site IP on the other appliance. For MEP, TCP 3009 must be open from the local GSLB Site IP, to the remote public Site IP. For GSLB sync, TCP 22, and TCP 3008, must be open from the local NSIP, to the remote public Site IP.
  13. Click Create.
  14. Repeat on the other appliance.

RPC

MEP defaults to unencrypted on TCP 3011. To fix that:

  1. On the left, expand System, expand Network, and click RPC.
  2. On the right, right-click the new RPC address (the other site’s GSLB Site IP), and click Edit.
  3. On the bottom, check the box next to Secure. In ADC 13.0 64.x and 12.1 build 61.x onwards, Secure is enabled by default. (source = Citrix CTX292743 Configuration Sync, Propagation and MEP Propagation Might Fail After Upgrade to 13.0 64.x\12.1 61.x)

    • If your local GSLB Site IP is not a SNIP, then you’ll need to change the RPC Node to use the local GSLB Site IP as the source IP. In the Source IP Address field, enter the local GSLB Site IP.
  4. Click OK when done.
  5. Do the same thing on the other appliance.
  6. If you go back to GSLB > Sites, you should see it as active.

See Citrix Tech Zone Troubleshooting Citrix GSLB MEP Cheat Sheet

If your MEP connection between GSLB Sites flaps, it might be useful to introduce a delay before remote GSLB Services are marked as Down.

  1. You can do this at Traffic Management > GSLB > Dashboard.
  2. On the right, click Change GSLB settings.
  3. In the GSLB Service State Delay Time (secs) field, enter a delay before the GSLB Services are marked as down when MEP goes down.

    set gslb parameter -GSLBSvcStateDelayTime 15

Static Proximity Geo Location Database

If you want to use DNS Policies, or Static Proximity GSLB Load Balancing, or Responders based on user’s location, import a geo location database.

Citrix ADC has a built-in database at /var/netscaler/inbuilt_db/ that you can use. Or you can download a database. Common free databases are:

For IP2Location, see the blog post Add IP2Location Database as NetScaler’s Location File for instructions on how to import.

CTX235799 NetScaler data formats for Location Database Import

Citrix Github has a Citrix-ADC-GSLB-GeoIP-Conversion-Tool that can convert Maxmind GeoIP City database to Citrix ADC (NetScaler) format.

Import the Built-in Geo database:

  1. In the Citrix ADC GUI, on the left, expand Traffic Management, expand GSLB, expand Database and Entries, and click Static Databases.
  2. On the right, click Add.
  3. Change the Import From selection to File.
  4. Click Choose File.
  5. Browse to /var/netscaler/inbuilt_db/. To browse to the directory, select var, and then click Open.
  6. Repeat for each directory until you reach /var/netscaler/inbuilt_db.
  7. In ADC 12.1, you can select the file named Citrix_Netscaler_InBuild_GeoIP_DB_IPv4. In NetScaler 12.0, select the only file shown. Then click Open.
  8. In the Location Format field, if using the built-in database, select netscaler, and click Create.
  9. After you later create a GSLB Service, when you open the GSLB Service, the public IP will be translated to a location based on the contents of the static proximity database.

Private IP Blocks

Geo Location databases only contain entries for Public IPs. For Private IPs, do the following:

  1. On the left, expand Traffic Management, expand GSLB, expand Database and Entries, and click Custom Entries.
  2. On the right, click Add.
  3. Enter a range of IP addresses for a particular location.
  4. Enter a Location Name in Geo Location format, which is typically six location words separated by periods. You can look in the static proximity database for examples.
  5. Make sure you enter coordinates. Google can find you coordinates for cities.
  6. Click Create.
  7. Continue creating Custom Entries for other private IP blocks.

Use Geo Locations

You can use the Geo locations in a DNS Policy, static proximity GSLB Load Balancing, Responders, and Rewrites:

Prior to Citrix ADC 12.1 build 50, the only option in policy expressions is to match a known location.

Citrix ADC 12.1 build 50 and newer lets you extract the user’s location and use it in policy expressions.

GSLB Services

GSLB Services represent the IP addresses that are returned in DNS Responses. The IP addresses represented by GSLB Services do not need to be hosted on a Citrix ADC, but Citrix ADC-owned IP addresses (e.g. load balancing VIPs) have additional GSLB Site Persistence options (e.g. cookie-based persistence).

  • Each potential IP address in a DNS response is a separate GSLB Service.
  • GSLB Services are associated with GSLB Sites.
  • GSLB Service configuration is identical for active/active and active/passive. GSLB Virtual Server configuration defines active/active or active/passive, not GSLB Services.

GSLB should be configured identically on all Citrix ADC pairs that are responding to DNS queries. Since you have no control over which Citrix ADC will receive the DNS query, you must ensure that both Citrix ADC pairs are giving out the same DNS responses.

To create a GSLB Service:

  1. On the left, expand Traffic Management > GSLB, and click Services.
  2. On the right, click Add.
  3. The service name should be similar to the DNS name that you are trying to GSLB. Include the site name in the service name.
  4. Select one of the GSLB Sites. The IP address you’re configuring in this GSLB Service should be geographically located in the selected GSLB Site.
  5. On the bottom part, if the IP address is owned by this Citrix ADC, then select Virtual Servers, and select a Virtual Server that is already defined on this appliance. It should automatically fill in the other fields. This option is only available when creating a GSLB Service in the Local GSLB Site.

    1. If the IP address is not owned by this Citrix ADC, then change the selection to New Server, and enter the remote IP address in the Server IP field.
    2. The Server IP field is the IP address that Citrix ADC will monitor for reachability.
    3. If the remote IP is owned by a different Citrix ADC that is reachable by MEP, then enter the actual VIP configured on that remote Citrix ADC. The Server IP does not need to match what is returned to the DNS Query.
  6. In the Public IP field, enter the IP address that will be returned to the DNS Query. If you leave Public IP blank, then Citrix ADC will copy the Server IP to the Public IP field. For Public GSLB, the Public IP field is usually a Public IP address. For internal GSLB, the Public IP field is usually an internal IP, and probably matches the Server IP.
  7. Scroll up, and make sure the Service Type is SSL. It’s annoying that Citrix ADC doesn’t set this drop-down correctly.
  8. Scroll down, and click OK, to close the Basic Settings section.
  9. GSLB Service Monitoring – on the right, in the Advanced Settings column, you can click Monitors to bind a monitor to this GSLB Service. Review the following notes before you bind a monitor.

    • Local Citrix ADC VIP – If the GSLB Service IP is a VIP on the local appliance, then GSLB will simply use the state of the local traffic Virtual Server (Load Balancing, Content Switching, or Gateway). There’s no need to bind a monitor to the GSLB Service.
    • Remote Citrix ADC VIP – If the GSLB Service IP is a VIP on a remote appliance, then GSLB will use MEP to ask the other appliance for the state of the remote traffic Virtual Server. In both cases. There’s no need to bind a monitor to the GSLB Service.
    • GSLB Monitor overrides other Monitoring methods – If you bind a monitor to the GSLB Service, then MEP and local Virtual Server state are ignored (overridden).
    • Here are some reasons for binding a monitor to the GSLB Service:
      • IP is not on a Citrix ADC– If the GSLB Service IP is not hosted on a Citrix ADC, then only a monitor can determine if the Service IP is up or not.
      • Monitor remote Internet – For Public DNS, if MEP is not routed through the Internet, then you need some method of determining if the remote Internet circuit is up or not. In that case, you’ll need to bind monitors directly to the GSLB Service. The route of the Monitor should go across the Internet. Or you can ping the Internet router in the remote datacenter to make sure it’s reachable.
      • Traffic Domains – If the GSLB Service IP is in a non-default Traffic Domain, then you will need to attach a monitor, since GSLB cannot determine the state of Virtual Servers in non-default Traffic Domains.
      • TCP monitor – for TCP services (not UDP), a simple TCP monitor is probably all you need. The TCP monitor tries to connect to the GSLB Service Public IP address using the SNIP of the local appliance. Make sure firewall on both sides allows this connection.
  10. Active/Active Site Persistence – If you intend to do GSLB active/active, and if you need site persistence, then on the right you can add Site Persistence and enable Connection Proxy or HTTP Redirect. See Citrix Blog Post Troubleshooting GSLB Persistence with Fiddler for more details. This only works with GSLB Service IPs that match Virtual Server VIPs on Citrix ADC appliances reachable through MEP.

  11. Scroll down, and click Done, to finish creating the GSLB Service.
  12. Create additional GSLB Services for each IP address that will be returned to a DNS query. There should be at least two for each DNS name.
  13. When creating a GSLB Service, select the correct Site, and make sure Service Type = SSL.
  14. The State will probably be down until the other ADC is configured.

Manually Synchronize GSLB Configuration

Copy the GSLB Service Configuration to the remote Citrix ADC pair. You can either repeat the GUI steps listed above. Or you can do the following:

  1. On the left, expand Traffic Management, expand GSLB, and click Dashboard.
  2. On the right, click View GSLB Configuration.
  3. This shows you all of the CLI commands for GSLB. Look for add gslb service commands. You can copy them, and run them (SSH) on other Citrix ADC pairs that are participating in GSLB.

GSLB Virtual Server

GSLB Virtual Server is the entity that links a DNS name with GSLB Services.

For Active/Passive GSLB in NetScaler ADC 13.1 or newer, GSLB Services can be bound in priority order. GSLB will give out the IP address of the lowest order GSLB Service. If that GSLB Service is down, then GSLB will give out the IP address of the next order GSLB Service.

  1. Create a GSLB Virtual Server.
  2. Bind the active GSLB Service but set the Order to 1.
  3. Bind the passive GSLB Service but set the Order to 2.
  4. Bind a DNS name to the GSLB Virtual Server.
  5. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  6. Delegate the DNS name to Citrix ADC ADNS.

For Active/Passive GSLB, the Active GSLB Virtual Server will give out a single IP address if that IP address up. If the GSLB Service is down, then it will fail over to a Backup GSLB Virtual Server that gives out a different IP address.

  1. Create a GSLB Virtual Server for the Passive IP address.
    1. Bind the Passive GSLB Service to the Passive GSLB Virtual Server.
  2. Create another GSLB Virtual Server for the Active IP address.
    1. Bind the Active GSLB Service to the Active GSLB Virtual Server.
    2. Configure Backup Virtual Server pointing to the Passive GSLB Virtual Server.
    3. Bind a DNS name to the Active GSLB Virtual Server.
  3. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  4. Delegate the DNS name to Citrix ADC ADNS.

For Active/Active GSLB, a single GSLB Virtual Server gives out multiple IP addresses based on load balancing method and site persistence.

  1. Create one GSLB Virtual Server.
    1. Bind two or more GSLB Services to the Virtual Server.
    2. Configure the GSLB Virtual Server Load Balancing Method – e.g., Proximity
    3. Configure Site Persistence:
      1. Source IP persistence is configured on the GSLB Virtual Server.
      2. Cookie Persistence is configured on the GSLB Services.
    4. Bind a DNS name to the GSLB Virtual Server.
  2. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  3. Delegate the DNS name to Citrix ADC ADNS.

Configure Active/Passive GSLB in NetScaler ADC 13.1 and newer

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Sevices you intend to bind.

      add gslb vserver <gslb_vserver_name> SSL
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to the active GSLB Service and click Select.
    3. In the Order box, enter 1. Click Bind.
  6. To add another GSLB Service Binding, on the left, click where it says 1 GSLB Virtual Server to GSLB Service Binding.

    1. Click Add Binding.
    2. Click where it says Click to select.
    3. Check the box next to a passive GSLB Service and then click Select at the top of the page.
    4. In the Order box, enter 2 so that this GSLB Service is only used if all Order 1 GSLB Services are down. Click Bind.
  7. Click OK to close the GSLB Services and GSLB Service Group Binding section.
  8. On the left, click where it says No GSLB Virtual Server Domain Binding.

    1. Enter the FQDN that this GSLB Virtual Server will resolve.
    2. Click Bind.
    3. If you are doing CNAME (e.g., citrix.corp.com CNAME to citrix.gslb.corp.com, then add domain bindings for both the main FQDN and the CNAME FQDN. Click Close when done.
  9. Click OK to close the GSLB Virtual Server Domain Binding section.
  10. Click OK to close the ADNS Service section.
  11. With GSLB Services assigned to different Order numbers, it is not necessary to configure Backup Virtual Server.
  12. If you bound multiple GSLB Services to a single Order number, then you might want to adjust Method and Persistence.
  13. Click Done to finish creating the GSLB Virtual Server.
  14. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  15. You’ll see a new DNS record for the GSLB domain you just configured. Notice it is marked as GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  16. Configure an identical GSLB Virtual Server on the other NetScaler ADC appliance pair. Both NetScaler ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other NetScaler ADC appliances.


Configure Active/Passive GSLB in NetScaler ADC 13.0 and older

Passive Virtual Server

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the Passive GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Services that you will bind to this Virtual Server.
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to an existing Passive GSLB Service, and then click the blue Select button at the top of the screen.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. Click OK to close the GSLB Virtual Server Domain Binding section. The DNS name is bound to the Active Virtual Server, not the Passive Virtual Sever.
  8. Click OK to close the ADNS Service section.
  9. Click Done to finish creating the Passive GSLB Virtual Server.

Active Virtual Server

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the Active GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Services that you will bind to this Virtual Server.
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to an existing Active GSLB Service, and click Select.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. On the left, click where it says No GSLB Virtual Server Domain Binding.
  8. In the Domain Binding page, do the following:
    1. Enter the FQDN that GSLB will resolve.
    2. Click Bind.
  9. Click OK to close the GSLB Virtual Server Domain Binding section.
  10. Click OK to close the ADNS Service section.
  11. On the right, in the Advanced Settings section, click Backup Virtual Server to add it to the left.
  12. On the left, in the Backup Virtual Server section, select the Passive GSLB Virtual Server, and click OK.
  13. Click Done when done creating the Active GSLB Virtual Server.
  14. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  15. On the right, you’ll see a new DNS record for the GSLB domain you just configured. Notice the Type is GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  16. Configure identical GSLB Virtual Servers on the other Citrix ADC appliance pair. Both Citrix ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other Citrix ADC appliances.

Configure Active/Active GSLB

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Sevices you intend to bind.
    3. You can optionally check the box for Send all “active” service IPs in response (MIR). By default, GSLB only gives out one IP address per DNS query. This checkbox always returns all IPs, but the IPs are ordered based on the GSLB Load Balancing Method and/or GSLB Persistence.
    4. A new DNS feature called ECS will contain the actual DNS client IP. This dramatically improves the accuracy of determining a user’s location. Without this setting, GSLB can only see the IP address of the user’s configured DNS server instead of the real client IP. Check the box next to Respond with ECS option to enable ECS for site persistence.

      set gslb vserver <gslb_vserver> -ECS ENABLED
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the boxes next to multiple existing GSLB Services, and click Select.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. On the left, click where it says No GSLB Virtual Server Domain Binding.

    1. Enter the FQDN that this GSLB Virtual Server will resolve.
    2. Click Bind.
  8. Click OK to close the GSLB Virtual Server Domain Binding section.
  9. Click OK to close the ADNS Service section.
  10. On the left, in the Method section, click the pencil icon.

    1. For poximity load balancing, change the Choose Method drop-down to RTT with STATICPROXIMITY as backup.
      1. RTT = Round Trip Time. Each ADC appliance sends a ping to the user’s DNS server. Whichever ADC appliance gets the fastest response determines the site of the GSLB Service. RTT requires that ADC be able to ping anything on the Internet so adjust firewall rules accordingly.
      2. STATICPROXIMITY requires that the Geo Location database has already been installed on the appliance.
    2. Click OK to close the Method section.
  11. On the right, in the Advanced Settings column, click Persistence to add it to the left.

    1. On the left, at the bottom of the page in the Persistence section, change the Persistence drop-down to Source IP.
    2. Enter a Persistence Id.
      1. The Persistence ID signifies the persistence table that each ADC pair shares across the MEP connection.
      2. Each active/active GSLB Virtual Server should have a different Persistence ID (different persistence table).
      3. When you configure the same GSLB Virtual Server on each Citrix ADC pair, specify the same Persistence ID so every Citrix ADC has the same persistence information for this particular GSLB Virtual Server.
    3. In the Time-out field, enter the Persistence Time-out. This is typically the same or longer than the webpage timeout.
    4. Click OK to close the Persistence section.
  12. Click Done to finish creating the GSLB Virtual Server.
  13. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  14. You’ll see a new DNS record for the GSLB domain you just configured. Notice it is marked as GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  15. Configure an identical GSLB Virtual Server on the other Citrix ADC appliance pair. Both Citrix ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other Citrix ADC appliances.


GSLB Configuration Synchronization Script

Manual GSLB Synchronization

  1. The synchronization script requires SSH to be enabled on your GSLB Site IPs.

  2. Ports TCP 3008, TCP 3010, and TCP 22 must be opened from the local NSIP to the remote GSLB Site IP. The source IP is NSIP, not SNIP.
  3. To manually run the script that syncs GSLB configuration from one GSLB Site to another, on the left, expand Traffic Management, expand GSLB, and click Dashboard.
  4. On the right, click the button labelled Auto Synchronization GSLB.
  5. Use the check boxes on the top, if desired. It’s usually a good idea to Preview the changes before applying them.
  6. Then click Run to begin synchronization.
  7. Click Close.
  8. You can Run it again without previewing it. It seems to take several seconds to complete.

Automatic GSLB Synchronization

  1. There is an automatic GSLB Configuration Sync feature, which automatically syncs the GSLB config every 15 seconds. To enable it on the master appliance, go to Traffic Management > GSLB > Dashboard. On the right, click Change GSLB settings.
  2. Check the box next to Automatic Config Sync. Only enable this on the one appliance where you are configuring GSLB, and want that GSLB config synced to other appliance.
  3. The automatic sync log can be found at /var/netscaler/gslb/periodic_sync.log.

Some notes regarding GSLB Sync:

  • When syncing GSLB Services, it tries to create Load Balancing Server objects on the remote appliance. If the GSLB Service IP matches an existing Load Balancing Server object, then the GSLB sync will fail. Check the Sync logs for details. You’ll have to delete the conflicting Load Balancing Server object before GSLB Sync works correctly.
  • GSLB Sync runs as a script on the BSD shell and thus always uses the NSIP as the source IP.
  • GSLB Sync connects to the remote GSLB Site IP on TCP 3008 (if RPC is Secure) and TCP 22.

Test GSLB

  1. You can test GSLB DNS name resolution from the GUI by going to Traffic Management > GSLB > Dashboard, and on the right, click the button labelled Test GSLB.

  2. Select a GSLB Domain Name.
  3. Select an ADNS Service IP to test it from, and click Test.
  4. The test performs a dig against the ADNS IP. Verify that the response contains the IP address you expected.
  5. Another method of testing GSLB is to simply point nslookup to the ADNS services and submit a DNS query for one of the DNS names bound to a GSLB vServer. Run the query multiple times to make sure you’re getting the response you expect.
    • The syntax is “nslookup <DNS_name> <ADNS_IP>”. The second argument specifies the DNS server that you send the DNS Query to.
  6. The Citrix ADC ADNS services at both GSLB sites should be giving the same response.
  7. To simulate a failure, if the GSLB Service IP is a Citrix ADC Load Balancing, Content Switching, or Citrix Gateway IP, you can disable the Virtual Server.
  8. Then the responses should change. Verify on both ADNS services.
  9. Re-enable the Virtual Server, and the responses should return to normal.

DNS Delegation

If you are enabling GSLB for the domain gateway.corp.com, you’ll need to create a delegation at the server that is hosting the corp.com DNS zone. For public GSLB, you need to edit the public DNS zone for corp.com.

DNS Delegation instructions will vary depending on what product is hosting the public DNS zone. This section details Microsoft DNS, but it should be similar in BIND or web-based DNS products.

There are two ways to delegate GSLB-enabled DNS names to Citrix ADC ADNS:

  • Delegate the individual record –  For example, delegate gateway.corp.com.
  • Delegate an entire subzone – For example, delegate the subzone gslb.corp.com. Then create a CNAME record in the parent DNS zone for gateway.corp.com that is aliased to gateway.gslb.corp.com. For additional delegations, simply create more CNAME records.
    • The incoming DNS query to the ADNS listener is for gateway.gslb.corp.com and not gateway.corp.com. You’ll need to bind gateway.gslb.corp.com to your GSLB Virtual Server. You can bind multiple FQDNs to a single GSLB Virtual Server.

A delegation consists of the following DNS records:

  • A records (host records) that resolve to each Citrix ADC ADNS IP address. If you have two ADC pairs participating in GSLB, then you’ll need one A record for each ADC pair.
    • The A record names are typically something like ns1.corp.com and ns2.corp.com, just like you would name any other DNS server.
    • You only create the A records once. The A records for ADNS services can be used by multiple delegations.
    • These A records for ADNS are sometimes called glue records.
  • NS records for each delegation. The NS records point to the A records that resolve to the ADC ADNS IP addresses. If you have two ADC ADNS IP addresses, then you need two NS records for each delegation.
    • When delegating individual records, you create separate NS records for each delegation. If you have two ADNS listeners, then you need two NS records for each delegation.
    • When delegating a subzone, you only need NS records for the subzone. To GSLB-enable a DNS name, you create a CNAME that aliases to a record under the subzone.

Delegate an individual DNS record

  1. Run DNS Manager.
  2. First, create Host Records pointing to the ADNS services running on the Citrix ADC pairs in each data center. These host records for ADNS are used for all GSLB delegations no matter how many GSLB delegations you need to create. These are sometimes called glue records.
  3. The first Host record is gslb1, (or similar) and should point to the ADNS service (Public IP) on one of the Citrix ADC appliances.
  4. The second Host record is gslb2, and should point to the ADNS Service (public IP) on the other Citrix ADC appliance.
  5. If you currently have a host record for the service that you are delegating to GSLB (e.g. gateway.corp.com), delete it.
  6. Right-click the parent DNS zone, and click New Delegation.
  7. In the Welcome to the New Delegation Wizard page, click Next.
  8. In the Delegated Domain Name page, enter the left part of the DNS record that you are delegating (e.g. gateway for gateway.corp.com). Click Next.
  9. In the Name Servers page, click Add.
  10. This is where you specify gslb1.corp.com and gslb2.corp.com as delegated name servers. Enter gslb1.corp.com, and click Resolve. Then click OK. If you see a message about the server not being authoritative for the zone, ignore the message. Note: you only add one name server at a time.
  11. Then click Add to add the other GSLB ADNS server.
  12. Once both ADNS servers are added to the list, click Next.
  13. In the Completing the New Delegation Wizard page, click Finish.
  14. The delegation is shown in the DNS Manager console.
  15. For proper delegation, the Name Server records should also be added to Citrix ADC. (source = Citrix CTX241493 Citrix Response on DNS Flag Day)
    1. On the GSLB Citrix ADC appliances, expand Traffic Management, expand DNS, expand Records, and click Name Server Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the name of the delegated DNS name (e.g. gateway.corp.com).
    4. In the Name Server field, leave it set to –<< New >>–, and enter one of the FQDNs for your GSLB ADNS services. This is one of the glue records you created earlier.
    5. Click Create.
    6. Add another Name Server Record for the same domain name. But this time, enter the second GSLB ADNS FQDN. Repeat this process until all GSLB ADNS FQDNs are specified.

  16. Also add an SOA record for the delegation. If you are delegating individual records, then you will need an SOA for each record. If you are delegating a subzone, you only need an SOA record for the subzone.
    1. On the left, in the menu, go to Traffic Management > DNS > Records > SOA Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the FQDN that you delegated to NetScaler. This can be an individual record, or a sub-zone.
    4. In the Origin Server field, leave it set to –<< New >> — and then enter the FQDN that resolves to one of your ADNS listeners. It doesn’t matter which one you enter.
    5. In the Contact field, enter an email address that is publicly viewable. Replace the @ symbol with a period.
    6. Click Create.
    7. Repeat this on the other ADCs that are participating in GSLB for this delegated DNS name.
  17. If you run nslookup against your Microsoft DNS server, it will respond with Non-authoritative answer. That’s because it got the response from Citrix ADC, and not from the original DNS server that you send the request to.

Delegate a Sub-zone

  1. Run DNS Manager.
  2. First, create Host Records pointing to the ADNS services running on the Citrix ADC pairs in each data center. These are sometimes called glue records.

    1. The first Host record is gslb1 (or similar), and should point to the ADNS service (Public IP) on one of the Citrix ADC appliances.
    2. The second Host record is gslb2, and should point to the ADNS Service (public IP) on the other Citrix ADC appliance.
  3. Right-click the parent DNS zone, and click New Delegation.
  4. In the Welcome to the New Delegation Wizard page, click Next.
  5. In the Delegated Domain Name page, enter the left part of the DNS sub-zone that you are delegating (e.g. gslb for gslb.corp.com). Click Next.
  6. In the Name Servers page, click Add.
  7. This is where you specify gslb1.corp.com and gslb2.corp.com. Enter gslb1.corp.com, and click Resolve. Then click OK. If you see a message about the server not being authoritative for the zone, ignore the message. Note: you only add one name server at a time.
  8. Then click Add to add the other GSLB ADNS server.
  9. Once both ADNS servers are added to the list, click Next.
  10. In the Completing the New Delegation Wizard page, click Finish.
  11. The sub-zone delegation is shown in the DNS Manager console.
  12. For proper delegation, the Name Server records should also be added to Citrix ADC. (source = Citrix CTX241493 Citrix Response on DNS Flag Day)
    1. On the GSLB Citrix ADC appliances, expand Traffic Management, expand DNS, expand Records, and click Name Server Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the name of the delegated sub-domain (e.g. gslb.corp.com).
    4. In the Name Server field, leave it set to –<< New >>–, and enter one of the FQDNs for your GSLB ADNS services. This is one of the glue records you created earlier.
    5. Click Create.
    6. Add another Name Server Record for the same domain name. But this time, enter the second GSLB ADNS FQDN.

    7. Repeat this process until all GSLB ADNS FQDNs are specified.
  13. Also add an SOA record for the delegation. If you are delegating individual records, then you will need an SOA for each record. If you are delegating a subzone, you only need an SOA record for the subzone.
    1. On the left, in the menu, go to Traffic Management > DNS > Records > SOA Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the FQDN that you delegated to NetScaler. This can be an individual record, or a sub-zone.
    4. In the Origin Server field, leave it set to –<< New >> — and then enter the FQDN that resolves to one of your ADNS listeners. It doesn’t matter which one you enter.
    5. In the Contact field, enter an email address that is publicly viewable. Replace the @ symbol with a period.
    6. Click Create.
    7. Repeat this on the other ADCs that are participating in GSLB for this delegated DNS name.

Each GSLB-enabled DNS name must be CNAME’d to GSLB:

  1. In Citrix ADC, go to Traffic Management > GSLB > Virtual Servers, and edit your GSLB Virtual Server.
  2. On the left, click in the GSLB Virtual Server Domain Binding section.
  3. Click Add Binding.
  4. Add a domain binding for the CNAME’d DNS name. For example, if the original DNS name is gateway.corp.com, then enter gateway.gslb.corp.com. gslb.corp.com matches the sub-zone that you delegated to Citrix ADC. Click OK.
  5. Repeat the Domain Binding on the other Citrix ADC appliances.
  6. In DNS Manager, if you currently have a host record for the service that you are delegating to GSLB (gateway.corp.com), delete it.
  7. Right-click the DNS zone, and click New Alias (CNAME).
  8. In the Alias name field, enter the left part of the original DNS name. For gateway.corp.com, enter gateway.
  9. In the Fully qualified domain name (FQDN) for target host field, enter the CNAME’d DNS name that is delegated to Citrix ADC. For example, if you delegated gslb.corp.com to Citrix ADC, then enter gateway.gslb.corp.com. The GSLB Virtual Server must be configured to match this longer DNS name.
  10. Click OK.
  11. If you run nslookup for the delegated DNS name, it will first CNAME to the longer name, and then respond with the IP address returned by Citrix ADC GSLB.
  12. You can repeat these steps to delegate (CNAME) additional DNS names to Citrix ADC GSLB.

RADIUS Authentication – Citrix Gateway

Last Modified: Mar 29, 2021 @ 11:28 am

195 Comments

This article applies to Citrix Gateway 13.0, Citrix Gateway 12.1, and NetScaler Gateway 12.0. Citrix ADC is the new name for NetScaler. Citrix Gateway is the new name for NetScaler Gateway.

Navigation

Change Log

RADIUS Overview

One method of two-factor authentication to Citrix Gateway is the RADIUS protocol with a two-factor authentication product (tokens) that has RADIUS enabled.

  • Another common two-factor authentication method is SAML to an Identity Provider, like Azure Active Directory or Okta. SAML is detailed in the Federated Authentication Service article.

RADIUS Clients and Source IP – On your RADIUS servers, you’ll need to add the ADC appliances as RADIUS Clients. When ADC uses a local (same appliance) load balanced Virtual Server for RADIUS authentication, the traffic is sourced from the ADC SNIP (Subnet IP). When ADC uses a direct connection to a RADIUS Server without going through a load balancing Virtual Server, or uses a remote (different appliance) Load Balancing Virtual Server, the traffic is sourced from the ADC NSIP (ADC Management IP). Use the correct IP(s) when adding the ADC appliances as RADIUS Clients. And adjust firewall rules accordingly.

  • For High Availability pairs, if you locally load balance RADIUS, then you only need to add the SNIP as a RADIUS Client, since the SNIP floats between the two appliances. However, if you are not locally load balancing RADIUS, then you’ll need to add the NSIP of both appliances as RADIUS Clients. Use the same RADIUS Secret for both appliances.

Links:

Some two-factor products (e.g. SMS Passcode) require you to hide the 2nd password field. Receiver 4.4 and newer supports hiding the 2nd field if you configure a Meta tag in index.html.

Two-factor Policies Summary

ADC has two methods of configuring multi-factor authentication:

  • Citrix Gateway Virtual Server has bind points for Primary and Secondary authentication. This functionality is available in all ADC Editions and is detailed in this post.
    • This is the older method of configuring authentication also known as Classic authentication policies. One challenge with Classic policies is that Citrix Workspace app requires the LDAP and RADIUS fields to be swapped.
  • nFactor Authentication supports unlimited factors, but requires ADC Advanced Edition (formerly known as Enterprise Edition) or ADC Platinum Edition.
    • nFactor is the newer authentication configuration method also known as Advanced authentication policies. With nFactor, there’s no need to swap the LDAP and RADIUS fields for Citrix Workspace app.

Workspace app authentication with a Classic Policy configuration looks like a Window that is very difficult to customize.

Workspace app authentication with an nFactor configuration looks like a webpage that is fully customizable.

See the ADC menu page for additional authentication mechanisms supported by Citrix Gateway. Some require nFactor.

When configuring the Citrix Gateway Virtual Server, you can specify both a Primary authentication policy, and a Secondary authentication policy. Users are required to successfully authenticate against both policies before being authorized for Citrix Gateway.

For browser-based StoreFront, you need two authentication policies:

  • Primary = LDAPS authentication policy pointing to Active Directory Domain Controllers.
  • Secondary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.

For Citrix Workspace app, the classic authentication policies need to be swapped. There’s no need to swap them if doing nFactor (Advanced) policies.

  • Primary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.
  • Secondary = LDAPS authentication policy pointing to Active Directory Domain Controllers.

With Classic Authentication Policies, if you need to support two-factor authentication from both web browsers and Citrix Workspace app, then you’ll need at least four authentication policies as shown below.

Primary:

  • Priority 90 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

Secondary:

  • Priority 90 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

LDAP Server/Action

See the LDAP post for instructions to create an LDAP Server/Action. Only the LDAP server/action is needed. The Policies will be created later.

RADIUS Server/Action

Create a RADIUS Server/Action:

  1. On the left, expand Authentication, and click Dashboard.
  2. On the right, click Add.
  3. Change Choose Server Type to RADIUS.
  4. Give the server a name.
  5. Specify the IP address of the RADIUS load balancing Virtual Server.
  6. Enter the secret key specified when you added the ADCs as RADIUS clients on the RADIUS server. Click Test RADIUS Reachability.
  7. Scroll down, and click More.
  8. Find the Password Encoding drop-down. Change it to mschapv2 if your RADIUS server supports it, c. Microsoft NPS requires mschapv2 to support changing expired Active Directory passwords. 💡
  9. If you want ADC to receive AAA Group information from RADIUS, see CTX222260 Radius Group Extraction from Windows Server 2008/2012 with NetScaler/CloudBridge.
    • RADIUS attribute = 26 (Vendor-Specific)
    • Vendor Code = 3845 (Citrix)
    • Vendor-assigned attribute number = any number (e.g. 1). Configure RADIUS policy on ADC with same attribute number.
    • Attribute value = Group Name
  10. Click Create.

    add authentication radiusAction RSA -serverIP 10.2.2.210 -serverPort 1812 -authTimeout 60 -radKey Passw0rd -passEncoding mschapv2

Advanced Authentication (nFactor) Policies for LDAP and RADIUS

For the older Classic Authentication policies, jump ahead to the Classic Policies section.

Create Advanced Authentication Policies:

  1. In the left menu, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy.
  2. On the right, click Add.
  3. In the Create Authentication Policy window:
    1. Change the Action Type to RADIUS.
    2. Select your RADIUS Action.
    3. Give the policy a name.
    4. Expression = true.
  4. Click Create.
  5. Create another Authentication Policy.
    1. Set Action Type to LDAP.
    2. Select your LDAP Action/Server.
    3. Give the policy a name.
    4. Expression = true.
  6. Click Create.

Create a Policy Label for the second factor, which is typically the RADIUS policy. The first factor (LDAP) does not need a Policy Label.

  1. In the left menu, click Policy Label.
  2. On the right, click Add.
  3. Give the Policy Label a name.
  4. Leave Login Schema set to LSCHEMA_INT. The Login Schema in the first factor will collect both password and passcode in one form so there’s no need for the second factor to collect it again.
  5. Click Continue.
  6. In the Select Policy field, select your RADIUS policy.
  7. Click Bind at the bottom of the page.
  8. Click Done to finish creating the Policy Label.

Create a Login Schema to collect the password and passcode on the same form.

  1. In the left menu, click Login Schema.
  2. On the right, switch to the tab named Profiles and then click Add.
  3. Give the Login Schema a name (e.g. DualAuth).
  4. Click the pencil icon and then open the LoginSchema folder.
  5. Click the DualAuth.xml file on the left. On the right, make sure you click the blue Select button. It’s too easy to miss this step.
    • See my nFactor article for some info on how to customize the Login Schema.
  6. Then click Create.
  7. On the right, switch to the tab named Policies.
  8. Give the Login Schema Policy a name.
  9. Select the Login Schema Profile you just created.
  10. Set the Rule field to true.
  11. Click Create.

Create an Authentication (AAA) Virtual Server to link the factors together.

  1. In the left menu, under AAA – Application Traffic, click Virtual Servers.
  2. On the right, click Add.
  3. Change the IP Address Type to Non Addressable.
  4. Give the AAA vServer a name and then click OK.
  5. In the Certificate section, you can optionally bind a certificate. It doesn’t matter what certificate you choose (typically the Gateway cert). The only thing this certificate binding does is make the AAA vServer show as UP instead of DOWN. Otherwise it has no effect on functionality. Click Continue.
  6. In the Advanced Authentication Policies section, click where it says No Authentication Policy.
  7. In the Select Policy field at the top of the window, select the LDAP policy.
  8. Near the bottom, in the Select Next Factor field, click where it says Click to select.
  9. Select your RADIUS Policy Label and then click Bind. After LDAP is done, nFactor will then move to your RADIUS Policy Label.
  10. Click Continue.
  11. On the right, in the Advanced Settings column, click Login Schemas.
  12. On the bottom left, click where it says No Login Schema.
  13. Select the DualAuth Login Schema you created earlier and then click Bind.
  14. Click Done at the bottom of the page.

Link the AAA vServer to your Gateway vServer:

  1. In the left menu, expand Citrix Gateway and then click Virtual Servers.
  2. On the right, edit your Gateway vServer.
  3. On the right, in the Advanced Settings column, click Authentication Profile.
  4. On the bottom left, in the Authentication Profile section, click the Add button.
  5. Select the AAA vServer you created earlier.
  6. Give the Profile a name and then click Create.
  7. Back in the Gateway vServer, make sure you click OK in the Authentication Profile section. If you forget to click OK then the Authentication Profile won’t be bound.

If you point your Workspace app to the Gateway that has nFactor configured, the authentication window will look like a web page.

Classic Authentication Policies for LDAP and RADIUS

For Advanced Authentication (nFactor) policies, jump back to the Advanced Policies section.

  1. Go to Citrix Gateway > Policies > Authentication > RADIUS.
  2. On the right, in the Policies tab, click Add.
  3. In the Create Authentication RADIUS Policy page:
    1. Name the policy RSA-ReceiverSelfService or similar.
    2. Select the RADIUS server created earlier.
    3. Enter an expression. You will need two policies with different expressions. The expression for Receiver Self-Service is REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver.
      Note: Citrix Gateway 12.1 does not natively support binding of Advanced Authentication Policies so you’ll have to create them as Basic Policies (classic expressions). You can only bind Advanced Authentication Policies using nFactor.
  4. Click Create.
  5. If you see a warning about deprecation, click OK, and ignore it.
  6. Create another RADIUS policy to match the ones shown below. Both RADIUS policies are configured with the same RADIUS server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS):
    Name Expression Server
    RSA-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver RSA
    RSA-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver RSA

  7. Go to the Citrix Gateway\Policies\Authentication\LDAP node.
  8. On the Policies tab, create two policies with the expressions shown below. Both LDAP policies are configured with the same LDAP server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS).
    Name Expression Server
    LDAP-Corp-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver LDAP-Corp
    LDAP-Corp-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver LDAP-Corp 

add authentication radiusPolicy RSA-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" RSA

add authentication radiusPolicy RSA-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" RSA

add authentication ldapPolicy Corp-Gateway-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" Corp-Gateway

add authentication ldapPolicy Corp-Gateway-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" Corp-Gateway

Bind Two-factor Policies to Gateway

  1. When you create or edit a Citrix Gateway Virtual Server, bind the Basic Authentication Policies as shown in the following table. Priority doesn’t matter because they are mutually exclusive.
    Policy Name Type Bind Point
    LDAP-Corp-ReceiverForWeb LDAP Primary
    RSA-ReceiverSelfService RADIUS Primary
    LDAP-Corp-ReceiverSelfService LDAP Secondary
    RSA-ReceiverForWeb RADIUS Secondary 

    bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverForWeb -priority 100

bind vpn vserver gateway.corp.com -policy RSA-ReceiverSelfService -priority 110

bind vpn vserver gateway.corp.com -policy RSA-ReceiverForWeb -priority 100 -secondary

bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverSelfService -priority 110 -secondary
  2. The Session Policy/Profile for Receiver Self-Service needs to be adjusted to indicate which authentication field contains the Active Directory password. On the Client Experience tab is Credential Index. This needs to be changed to SECONDARY. Leave the session policy for Web Browsers set to Primary.

    set vpn sessionAction "Receiver Self-Service" -ssoCredential SECONDARY
  3. On the StoreFront server, when creating the Citrix Gateway object, on the Authentication Settings page, change the Logon type to Domain and security token. This instructs Receiver / Workspace app to properly handle two-factor authentication. If you change this setting after Receiver / Workspace app has already performed discovery, then users might have to remove the Account from Receiver / Workspace app and re-add it.