Product Documentation

Making Virtual IP Addresses Available to Applications

Apr 28, 2015

Some applications, such as CRM and CTI, use an IP address for addressing, licensing, identification, or other purposes and thus require a unique IP address or a loopback address in sessions. Other applications may bind to a static port, which, because the port is already in use, causes the failure of multiple attempts to launch an application in a multiuser environment. For such applications to function correctly in a XenApp environment, a unique IP address is required for each device.

Use the virtual IP address feature to allow a dynamically-assigned IP address to each session so that configured applications running within that session appear to have a unique address.

Processes require virtual IP if either:

  • They use a hard-coded TCP port number, or
  • They do both of the following:
    • Use Windows sockets, and
    • Require a unique IP address or require a specified TCP port number

Also, this feature lets you configure applications that depend on communication with localhost (127.0.0.1 by default) to use a unique virtual loopback address in the localhost range (127.*).

Processes require virtual loopback if either:

  • They use the Windows socket loopback (localhost) address (127.0.0.1), or
  • They use a hard-coded TCP port number

If the application requires an IP address for identification purposes only, configure your server to use the client IP address.

How Virtual IP Addressing Works

The Microsoft Remote Desktop (RD) IP Virtualization feature works as follows:

  • In Microsoft Server Manager, expand Remote Desktop Services > RD Session Host Connections to enable the RD IP Virtualization feature and configure the settings. For details, refer to Microsoft help and documentation, including the Microsoft TechNet Web site.
    • Once the feature is enabled, at session start-up, the server requests dynamically-assigned IP addresses from the Dynamic Host Configuration Protocol (DHCP) server.
    • Based on your Virtual IP policy and the settings you configure, the RD IP Virtualization feature assigns IP addresses to remote desktop connections on a per session or per program basis. If you assign IP addresses for multiple programs, they share a per-session IP address.
    • After an address is assigned to a session, it uses the virtual address rather than the primary IP address for the system whenever the following calls are made:
       Bind¸closesocket¸connect, WSAConnect, WSAAccept, getpeername, getsockname,  
      sendto, WSASendTo, WSASocketW, gethostbyaddr, getnameinfo, getaddrinfo
  • XenApp extends the Windows virtual IP feature by allowing the gethostbyname API to return the virtual IP address. In addition, XenApp adds virtual loopback to all APIs.
    Note: All processes that require the XenApp feature must be added to the programs list for the Virtual IP policy that you enable. Child processes do not inherit this functionality automatically. Processes can be added with full paths or just the executable name. For security reasons, Citrix recommends that you use full paths.

Binding Applications

Using the Microsoft IP virtualization feature within the Remote Desktop session hosting configuration, applications are bound to specific IP addresses by inserting a “filter” component between the application and Winsock function calls. The application then sees only the IP address it is supposed to use. Any attempt by the application to listen for TCP or UDP communications is bound to its allocated virtual IP address (or loopback address) automatically, and any originating connections opened by the application are originated from the IP address bound to the application.

In functions that return an address such as GetHostByName() (controlled by a XenApp policy) and GetAddrInfo() (controlled by a Windows policy), if the local host IP address is requested, virtual IP looks at the returned IP address and changes it to the virtual IP address of the session. Applications that try to get the IP address of the local server through such name functions see only the unique virtual IP address assigned to that session. This IP address is often used in subsequent socket calls (such as bind or connect).

Often an application requests to bind to a port for listening on the address 0.0.0.0. When an application does this and uses a static port, you cannot launch more than one instance of the application. The virtual IP address feature also looks for 0.0.0.0 in these types of calls and changes the call to listen on the specific virtual IP address. This enables more than one application to listen on the same port on the same computer because they are all listening on different addresses. Note this is changed only if it is in an ICA session and the virtual IP address feature is turned on. For example, if two instances of an application running in different sessions both try to bind to all interfaces (0.0.0.0) and a specific port, such as 9000, they are bound to VIPAddress1:9000 and VIPAddress2:9000 and there is no conflict.

To determine whether an application needs to use virtual IP addresses

Some applications cannot run in multiple sessions on XenApp. For example, if the application binds to a fixed TCP port on a specific IP address such as 0.0.0.0 or 127.0.0.1, this prevents multiple instances of the application from running in multiple sessions because the port is already in use. The virtual IP feature of XenApp can help solve this problem.

To determine whether or not the application needs to use virtual IP addresses:

  1. Obtain the TCPView tool from Microsoft. This tool lists all applications that bind specific IP addresses and ports.
  2. Disable the Resolve IP Addresses feature so that you see the addresses instead of host names.
  3. Launch the application and, using TCPView, note which IP addresses and ports are opened by the application and which process names are opening these ports.

To use the virtual IP address feature, configure any processes that open the IP address of the server, 0.0.0.0, or 127.0.0.1.

To ensure that an application does not open the same IP address on a different port, launch an additional instance of the application.

To make virtual IP addresses available to applications running in sessions

Enable these Virtual IP policy settings to add additional support to the Windows IP Virtualization feature. Virtual IP addresses provide published applications with unique IP addresses for use in sessions. This is especially important for Computer Telephony Integration (CTI) applications that are widely used in call centers. Users can access these applications on a XenApp server in the same way that they access any other published application. For more information, see To determine whether an application needs to use virtual IP addresses.

Before you begin, in Microsoft Server Manager console, enable the Remote Desktop IP Virtualization feature and configure it to dynamically assign IP addresses using the DHCP server on a per-session or per-program basis.

To extend the IP virtualization feature, configure the following Citrix policy settings for Virtual IP:
  • Virtual IP enhanced compatibility. Use this setting if your application uses the GetHostByName API. When enabled, calls to GetHostByName within a session return the virtual IP address for the session (disabled by default). The feature applies only for the applications listed in the virtual IP compatibility programs list.
  • Virtual IP compatibility programs list. Lists the applications that use the virtual IP enhanced compatibility policy.
  • Virtual IP adapter address filtering. Use this setting if your application returns a large number of addresses, which slows down performance. When enabled, the list of addresses returned by GetAdaptersAddresses includes only the session virtual IP address and the loopback address, which can improve performance (disabled by default). The feature is enabled only for the applications listed in the virtual IP filter adapter addresses programs list.
  • Virtual IP filter adapter addresses programs list. Lists the applications that use the IP adaptor address filtering policy.

To make a virtual loopback address available to applications running in sessions

Use the virtual loopback policy for applications that use a loopback address for interprocess communication. Enabling this virtual IP policy setting allows each session to have its own loopback address for communication. When an application uses the localhost address (127.0.0.1) in a Winsock call, the virtual loopback feature simply replaces 127.0.0.1 with 127.X.X.X, where X.X.X is a representation of the session ID + 1. For example, a session ID of 7 is 127.0.0.8. In the unlikely event that the session ID exceeds the fourth octet (more than 255), the address rolls over to the next octet (127.0.1.0) to the maximum of 127.255.255.255.

The virtual loopback feature does not require any additional configuration other than specifying in the programs list which processes use the feature. Virtual loopback has no dependency on Virtual IP, so no Microsoft server configuration is needed to enable virtual loopback.

For more information, see To determine whether an application needs to use virtual IP addresses.

Configure the following Citrix policy settings for Virtual IP:
  • Virtual IP loopback support. Use this setting to allow each session to have its own virtual loopback address for communication (disabled by default). The feature is enabled only for the applications listed in the Virtual IP virtual loopback programs list.
  • Virtual IP virtual loopback programs list. Lists the applications that use the Virtual IP loopback support policy.

To supply client IP addresses to published applications on a server

Use the Client IP Address feature if an application fails because it requires a unique address strictly for identification or licensing purposes, and the application does not require a virtual address for communication. This feature hooks only calls that return a host IP address, such as gethostbyname(). Only use this feature with applications that send the value in this type of call to the server application for identification or licensing.

If you deploy this feature, consider the IP addresses used by each client device. For example, if two remote users use the same IP address, a conflict will arise due to the duplicate address.

When these values are configured, configure either the Virtual IP Processes or Virtual Loopback Processes with the same process names in the Virtual IP compatibility programs list setting or Virtual IP virtual loopback programs list setting for the policy. This function creates and manages the following registry entry, which is still required for the Client IP feature to work: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ CtxHook\AppInit_Dlls\VIPHook\Processname

On XenApp, 32-bit Edition, this entry is: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CtxHook\ AppInit_Dlls\VIPHook\Processname

Note: The virtual IP address feature functions only with applications that load the user32.dll system dynamic link library.

For identification purposes, some applications require the IP address be unique for a session. Such IP addresses are not needed for binding or addressing purposes. In such a case, configure the session to use the IP address of the client device.

  1. On the server on which the applications reside, start regedit.
    Caution: Editing the Registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.
Using regedit, create the following two registry entries:
  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\VIP\

    Name: UseClientIP

    Type: REG_DWORD

    Data: 1 (enable) or 0 (disable, which is the default)

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\VIP\

    Name: HookProcessesClientIP

    Type: REG_MULTI_SZ

    Data: multiple executable names representing application processes that use client IP addresses

    Note: On XenApp, 32-bit Edition, these entries are found in HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\VIP\.
  • Close regedit and restart your server.
  • After making the prescribed registry modifications, add the application process in the programs list for the policy.
    Do not configure the use of client IP addresses if:
    • Plug-ins connect using network protocols other than TCP/IP
    • Plug-ins reconnect to disconnected sessions from different client devices
    • Sessions use a pass-through plug-in