Optimize connectivity to workspaces with the Network Location Service (Technical Preview)

Note:

This feature is currently in Technical Preview. Citrix recommends using technical preview features only in test environments.

With the Network Location Service in Citrix Cloud, you can optimize internal traffic to the apps and desktops you make available to subscribers’ workspaces to make HDX sessions faster. Ordinarily, users on both internal and external networks have to connect to VDAs through an external Gateway. While this is expected for external users, internal users experience slower connections to virtual resources. The Network Location Service allows internal users to bypass the gateway and connect to the VDAs directly, reducing latency for internal network traffic.

To set up the Network Location Service, you configure network locations that correspond to the VDAs in your environment using the Network Location Service PowerShell module that Citrix provides. These network locations include the public IP addresses of the VDAs in your internet network. When subscribers launch Virtual Apps and Desktops sessions from their workspace, Citrix Cloud detects whether subscribers are internal or external to the company network based on the public IP address of the network from which they’re connecting. If a subscriber connects from the internal network, Citrix Cloud routes the connection directly to the VDA, bypassing Citrix Gateway. If a subscriber connects externally, Citrix Cloud routes the subscriber through Citrix Gateway as expected and then redirects the subscriber to the VDA in the internal network.

Supported products

The Network Location Service is supported for the Virtual Apps and Desktops service only. Support for Citrix Managed Desktops and Citrix SD-WAN is in Technical Preview.

Important:

If your environment includes Managed Desktops alongside on-premises VDAs, configuring the Network Location Service causes Managed Desktops launches from the internal network to fail.

Launches of Secure Browser, Citrix Virtual Apps Essentials, and Citrix Virtual Desktops Essentials are always routed through the gateway. So, these launches do not realize any performance improvements from configuring the Network Location Service.

Requirements

  • If you have a corporate network and a guest Wifi network, these networks must have separate public IP addresses. If your corporate and guest networks share the same public IP address, users on the guest network can’t launch Virtual Apps and Desktops sessions.
  • You must use the public IP addresses of the VDAs in your internal network to configure your network locations. Before setting up the Network Location Service, note these public IP addresses. To locate the address, log on to each VDA machine and use a public IP lookup service from a web browser.
  • TLS 1.2 must be enabled in PowerShell to connect to the Network Location Service successfully. To force PowerShell to use TLS 1.2, use the following command:

     [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
  • Users on your internal network must have a direct connection to the VDAs in your environment.
  • You must have a workspace configured in Citrix Cloud, the Virtual Apps and Desktops service is enabled in Workspace Configuration > Service Integrations, and you are using on-premises VDAs to deliver virtual resources to workspace subscribers.

Powershell module and configuration

Download the PowerShell module

Before you set up your network locations, download the Citrix-provided Network Location Service PowerShell module (nls.psm1) from the Citrix Github repository. Using this module, you can set up as many network locations as needed for your VDAs.

  1. In a web browser, go to https://github.com/citrix/sample-scripts/blob/master/workspace/nls.psm1.
  2. Press ALT while clicking the Raw button. Github file view with Raw button highlighted
  3. Select a location on your computer and click Save.

Required configuration details

To set up your network locations, you need the following required information:

  • Citrix Cloud secure client customer ID, client ID, and client secret. To obtain these values, see Create a secure client in this article.
  • Public IP address ranges for your VDAs. To obtain the public IP addresses of your VDAs, see Requirements in this article.

You can create a script to enter these values, as the Example script shows. You can also enter these values through the PowerShell command line, as described in Configure network locations in this article.

Note:

The PowerShell module includes a hardcoded timezone. Although this timezone doesn’t affect the module’s functionality of your network locations, you can change it by modifying Lines 67-71 of the nls.psm1 file.

Example script

Import-Module .\nls.psm1 -Force
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$clientId = "XXXX" #Replace with your clientId
$clientSecret = "YYY"    #Replace with your clientSecret
$customer = "CCCCCC"  #Replace with your customerid


# Connect to Network Location Service
Connect-NLS -clientId $clientId -clientSecret $clientSecret -customer $customer

# Create a new Network Location Service Site (Replace with details corresponding to your VDA locations)
New-NLSSite -name "New York" -tags @("EastCoast") -timezone "America/New_York" -ipv4Ranges @("1.2.3.0/24") -longitude 40.7128 -latitude -74.0060

# Get the existing Network Location Service Sites
Get-NLSSite

# Create and update a Network Location Service Site
$s = (Get-NLSSite)[0]
$s.ipv4Ranges = @("1.2.3.4/32","4.3.2.1/32")
$s | Set-NLSSite

# Remove all Network Location Service Sites
Get-NLSSite | Remove-NLSSite

(Get-NLSSite)[2] | Remove-NLSSite

Create a secure client

  1. Sign in to Citrix Cloud at https://citrix.cloud.com.
  2. From the Citrix Cloud menu, select Identity and Access Management and then select API Access.
  3. On the Secure Clients tab, note your customer ID. Secure Client console with Customer ID highlighted
  4. Enter a name for the client and then select Create Client.
  5. Copy the client ID and client secret. Secure Client ID and Secret dialog

Configure network locations

  1. Open a PowerShell command window and navigate to the same directory where you saved the PowerShell module.
  2. Import the module: Import-Module .\nls.pm1 -Force
  3. Set the required variables with your secure client information from Create a secure client:
    • $clientId = "YourSecureClientID"
    • $customer = "YourCustomerID"
    • $clientSecret = "YourSecureClientSecret"
  4. Connect to the Network Location Service with your secure client credentials:

    Connect-NLS -clientId $clientId -clientSecret $clientSecret -customer $customer
    
  5. Create a network location, replacing the parameter values with the values that correspond to the internal network where your VDAs reside:

    New-NLSSite -name "YourSiteName" -tags @("YourTags") -timezone "YourLocationTimezone" -ipv4Ranges @("ExternalIpsOfYourVdas") -longitude 12.3456 -latitude 12.3456
    
  6. Verify that the network location information you just entered is correct: Get-NLSSite
  7. Repeat Steps 5 and 6 for all your VDA locations.

Verify internal launches are routed correctly

To verify internal launches are accessing VDAs directly, use one of the following methods:

  • View VDA connections through Virtual Apps and Desktops console.
  • Use ICA file logging to verify the correct addressing of the client connection.

Virtual Apps and Desktops service console

Select Manage > Monitor and then search for a user with an active session. In the Session Details section of the console, direct VDA connections display as UDP connections while gateway connections display as TCP connections.

ICA file logging

Enable ICA file logging on the client computer as described in To enable logging of the launch.ica file. After launching sessions, examine the Address and SSLProxyHost entries in the log file.

For direct VDA connections, the Address property contains the VDA’s IP address and port and the SSLProxyHost property contains the VDA’s FQDN and port.

For gateway connections, the Address property contains the STA ticket and the SSLProxyHost property contains the gateway’s FQDN and port.

Modify network locations

  1. From a PowerShell command window, list all existing network locations: Get-NLSSite
  2. To modify the IP range for a specific network location, type

    (Get-NLSSite)[N] -ipv4Ranges @("1.2.3.4/32","4.3.2.1/32") | Set-NLSSite

    where [N] is the number corresponding to the location in the list and "1.2.3.4/32","4.3.2.1/32" are the comma-separated IP ranges you want to use. For example, to modify the first listed location, you type the following command:

    (Get-NLSSite)[0] -ipv4Ranges @("98.0.0.1/32","141.43.0.0/24") | Set-NLSSite

Remove network locations

  1. From a PowerShell command window, list all existing network locations: Get-NLSSite
  2. To remove all network locations, type Get-NLSSite | Remove-NLSSite
  3. To remove specific network locations, type (Get-NLSSite)[N] | Remove-NLSSite, where [N] is the number corresponding to the location in the list. For example, to remove the first listed location, you type (Get-NLSSite)[0] | Remove-NLSSite.

Troubleshooting

Connect-NLS returns an error

If you receive an error when running the Connect-NLS command (Step 2 in Configure network locations), you might need to force PowerShell to use TLS 1.2. To do this, run the following command:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

VDA launch failures

If VDA sessions are failing to launch, verify you are using public IP addresses from the correct network. When configuring your network locations, you must use the public IP addresses of the VDAs on the network where your users are connecting.

To verify the VDA’s public IP address, log on to each VDA machine, visit https://google.com, and enter “what is my ip” in the search bar.

Internal VDA launches still routed through the gateway

If VDA sessions launched internally are still being routed through the gateway as if they were external sessions, verify you are using the correct IP addresses for the VDAs in your configured network locations. You must use the public IP addresses of the VDAs, not the local IP address.

To verify the public IP address, log on to each VDA machine, visit https://google.com, and enter “what is my ip” in the search bar.

Additional help and support

For troubleshooting help, questions, or to provide feedback about the Network Location Service, visit the Network Location Service Technical Preview support forum to talk with Citrix experts and other members of the Citrix Cloud community.