Created Date: 02/03/2009
Updated Date: N/A
XenDesktop Client Identity Utilities provides ways to obtain information on a XenDesktop virtual desktop machine relating to the identity of the client machine (if any) that is connected to the desktop using ICA
There are several circumstances, such as for a script relating to printing, when it is useful for components running on a virtual desktop machine to discover the identity (IP address or name) of the endpoint client device that is being used to connect to the desktop machine. This document provides some alternatives for discovering this information. All the mechanisms end up using the WFAPI dynamic library that is installed on each virtual desktop machine to obtain the data; the WFAPI must be used from the context of a user session connected to using an ICA client in order to retrieve the required data.
The WFAPI can be called with a PowerShell script, and scripts that do this can produce output that can be used directly or to set up session environment variables for later consultation. Alternatively, an unmanaged executable can be used to retrieve expose the client name value in an environment variable.
Note: The values of client name and client IP address provided by these tools have not been authenticated, and security-critical decisions should not be made based on the values.
Minimum supported operating system: Windows XP.
If the PowerShell scripts are to be used, PowerShell version 1.0 or later is required.
Installing XenDesktop Client Identity Utilities
Extract the Zip files and place in a directory. No further installation is required, although to make use of the native tool or PowerShell scripts the location of the directory must be known to the script or shell using the tool, or the tool directories must be present in the PATH environment variable.
How to Use XenDesktop Client Identity Utilities
To use the PushClientName unmanaged tool:
The PushClientName.exe utility appears in the PushClientName directory.
1. Arrange for PushClientName.exe to be run in an ICA connected user session.
2. ICA Connected user launches a new command prompt (Start > Run cmd.exe).
3. Enter “set Citrix” into the command prompt to check that the variable has been set; the values shown should include the environment variable “CitrixClientName” which should show the name of the client machine that the user is connected from.
The following screenshot shows two command windows; one (in the background) in which the PushClientName.exe utility has been run, and a second (foreground) command window which shows the “CitrixClientName” is set:
To Use the getClientIpAddr PowerShell script.
The getClientIpAddr.ps1 script appears in the wfapi_psaccess directory.
1. Arrange for getClientIpAddr.ps1 script to be run in an ICA connected user session.
2. The value output from the script will be a string containing either "Not an ICA session" or the string form of the dotted IP address of the client machine that the user is connected from.
The following screenshot shows a PowerShell shell window in which the getClientIpAddr has been run:
To Use the getClientName PowerShell script.
The getClientName.ps1 script appears in the wfapi_psaccess directory.
1. Arrange for getClientName.ps1 script to be run in an ICA connected user session.
2. The value output from the script will be a string containing either "Not an ICA session" or the name of the client machine that the user is connected from.
The following screenshot shows a PowerShell shell window in which the getClientName has been run:
Security Permissions Required by XenDesktop Client Identity Utilities
Each of the tools must be run from the context of a user session that is connected over ICA in order to obtain useful information.
Data Modified by XenDesktop Client Identity Utilities
Only files extracted from the zip are created or changed by the install process. No registry or database changes are directly made either at install or later run time of the tools.
The PushClientName.exe tool changes the environment variable value in the user’s session. The volatile environment variable should disappear when the user logs out.
How to Undo the Changes Made by XenDesktop Client Identity Utilities
Uninstalling XenDesktop Client Identity Utilities
Delete the files extracted from the zip during install.
Use WFAPI directly:
The WFAPI can be called directly from a native or VB application. See the WFAPI SDK as downloadable direct from the website and describe by CTX114195 - [Document Not Found] The API that should be used is WFQuerySessionInformation, and the information items to be queried are WFClientAddress for the endpoint client IP address value and WFClientName for the endpoint client machine name.
Contact Supporttools@citrix.com to report any bugs or provide feedback for this tool.
The above mentioned sample code is provided to you as is with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the sample code. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Although the copyright in the code belongs to Citrix, any distribution of the code should include only your own standard copyright attribution, and not that of Citrix. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.