Session State Monitor Tool - XenApp/XenDesktop

Session State Monitor Tool - XenApp/XenDesktop

book

Article ID: CTX127491

calendar_today

Updated On:

Description

 

Where to download ?

Certain legacy Citrix tools are now available on request only. Please submit the request here - https://forms.gle/obA39PEz5qpDiSPq8

Once we verify your request, we will provide access to the download location.

 

Description

The Session State Monitor Utility actively monitors remote connections and disconnections in the session for which it’s running. The utility provides the ability to specify custom commands for Disconnect, Reconnect, and Startup. The utility also has the ability to allow the endpoint (client) name to smooth roam in double-hop sessions to the second hop. The utility does this by disconnecting the session from first hop to second hop, updating the appropriate registry key for ‘clientname’, and then reconnecting the disconnected first hop to second hop session.

Prerequisites

Caution! When using this tool to update the clientname on a Pass-through XenApp session, the full 12.x client plug-in must be installed on the first hop and the client must have fix 215510. The public ICA client version 12.3 contains fix 215510.

Note: If using Windows Receiver 3.0/13.0 (or greater) and performing clientname Pass-through, Virtual Channel Driver must be used instead of Session State Monitor. Due to design changes in the receiver disallowing ‘reconnects’, Virtual Channel Driver has been released to allow real-time querying of clientname over a custom virtual channel. VCD does not disconnect and reconnect the session as Session State Monitor does with a 12.x client. VCD does require additional setup and configuration on both the client and server. See http://support.citrix.com/article/CTX129961 for additional information on this utility.

 

Installing Session State Monitor Utility

This fix requires you to edit the registry. Using Registry Editor 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 the Registry Editor at your own risk. Be sure to back up the registry before you edit it.

 
  1. Extract the contents of the zip file to a folder.
    The zip contains two files:
    SessionStateMonitor.exe runs as a background process for the current user to monitor connections and disconnections to the VDA from any endpoint.
    SessionStateMonitor.reg installs the registry values utilized by the utility to run custom commands during any specified state.
  • Import the SessionStateMonitor.reg file or manually add the following registry keys:

    Create the following key for x86:
    HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SessionStateMonitor
  • the following key for x64:
    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Citrix\SessionStateMonitor

    Add the following values:
    Name: DisconnectCommands
    Type: REG_MULTI_SZ
    Value Data: <custom command> (can be left blank)
    Definition: Add all commands one per line that need to run at session disconnect. Command should be wrapped in quotes.

    Name: ReconnectCommands
    Type: REG_MULTI_SZ
    Value Data: <custom command> (can be left blank)
    Definition: Add all commands one per line that need to run at session reconnect. Command should be wrapped in quotes.

    Name: PassthroughReconnectCommands
    Type: REG_MULTI_SZ
    Value Data: <custom command> (can be left blank)
    Definition: Add all commands one per line that need to run at session reconnect if pass-through sessions were detected at disconnect. Command should be wrapped in quotes.

    Name: PassthroughDisconnectCommands
    Type: REG_MULTI_SZ
    Value Data: <custom command> (can be left blank)
    Definition: Add all commands one per line that need to run at session reconnect if pass-through sessions were detected at disconnect. Command should be wrapped in quotes.

    Name: StartupCommands
    Type: REG_MULTI_SZ
    Value Data: <custom command> (can be left blank)
    Definition: Add all commands one per line that need to run at session startup. Command should be wrapped in quotes.

    Name: UseHKLM
    Type: REG_SZ
    Value Data: 0 (recommended, as 0 will use HKCU instead)
    Definition: determines whether HKLM or HKCU hive is used for writing updated ‘clientname’ to registry.

    Name: EnablePassthroughCommands
    Type: REG_SZ
    Value Data: 1 (0 will disable)
    Definition: determines whether or not passthrough commands are processed.

    Name: LogFileName
    Type: REG_SZ
    Value Data: (path and file name for log file)
    Definition: If populated, will enable logging to the provided file and path. Do not use quotes. This value can have environment variables in path. Example: ‘%temp%\ssm.log’

    Name: SetClientName
    Type: REG_SZ
    Value Data: 1 (0 will disable)
    Definition: determines whether registry and environment variables for ‘clientname’ should be updated.
  • Add the SessionStateMonitor.exe to the Startup programs for all users or in the ‘Run’ key in the registry so that it runs as a background process inside the user session.

Using the Session State Monitor to pass through the endpoint’s client name to a XenApp application running within the VDA ICA session

 
  1. You must add the following commands in the registry values created above:
    Edit the “EnablePassthroughCommands” string and set the value to ‘1’.
    Note:     When set to 1 the utility will attempt to populate the below commands if they are not populated but requires write permissions to HKLM.

    Edit the “PassthroughDisconnectCommands” string and add the value data:
    Note:    Verify path to pnagent.exe
    Example:"c:\program files\citrix\ica client\pnagent.exe" /disconnect

    Edit the “PassthroughReconnectCommands” string and add the value data:
    Example:"c:\program files\citrix\ica client\pnagent.exe" /reconnect
  • Create the following Registry Key for x86:
    HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Pass Through

    Create the following Registry Key for x64:
    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Citrix\ICA Client\Pass Through

    Add the following values:
    Name: PASS THROUGH
    Type: REG_DWORD
    Value Data: 1

Known Issues

 
  1. If UseHKLM value has been set to both 0 and 1 on same machine, the following error may be displayed and will fail to launch applications

Error number 2320

Citrix online plug-in Configuration Manager: No value could be found for (ClientName) that satisfies all lockdown requirements. The lockdown requirements in force may be conflicting.

Resolution: Delete registry ‘clientname’ values in both HKCU and HKLM:

Software\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client Engine

 
  1. This utility does not work with Anonymous Pass-through sessions from VDA to XenApp.

Issues resolved in this release

- 3.0.0.8 – added %clientaddress% for client ip address

- 3.0.0.7 – resolved issue on x64 systems where utility was unable to query ica sessions correctly. This version requires use of Wow6432node reg keys on x64.

How to Use Session State Monitor Utility

Once the utility is installed and running as a background process, it will automatically monitor the ICA/RDP session for any disconnects and reconnects. It will optionally update the endpoints client name on the session and run any custom commands from the registry.

Debugging XD Session State Monitor Utility

To debug the utility, in the registry, populate the LogFileName value with path and file name for logging and restart utility. The Reference section below contains a debug example log of a good disconnect and subsequent reconnect:

Security Permissions Required by Session State Monitor Utility

Registry Security permissions on HKLM might not allow utility to write to HKLM. For this reason, it is recommended that you use the default registry value UseHKLM of 0 so that it uses HKCU instead.

Data Modified by Session State Monitor Utility

 
  1. Registry key created and used by the utility:
    HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SessionStateMonitor
 
  1. If EnablePassthroughCommands equals 1, the ClientName value gets updated with the endpoint’s hostname in the registry in the following key:
    If UseHKLM = 1: HKEY_LOCAL_MACHINE\Software\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client Engine
    If UseHKLM = 0: HKEY_CURRENT_USER\Software\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client Engine
 
  1. If EnablePassthroughCommands equals 1 and there are active pass-through sessions, the following value will be populated:
    HKCU\SOFTWARE\Citrix\SessionStateMonitor\PreviousSessions
 
  1. Endpoint’s hostname is broadcast to the session’s environment.
 
  1. Clientname user environment variable is updated.

Uninstalling Session State Monitor Utility

 
  1. Delete the folder where you unzipped the files.
 
  1. Remove the utility from the startup programs.
 
  1. Backup and remove the registry key created under the install instructions above.

Contact Information

For questions or concerns please send any feedback for this utility to supporttools@citrix.com.

Disclaimer

These software applications are provided to you as is with no representations, warranties or conditions of any kind. You may use 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 software application 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 software application 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 software application. 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 SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.

Reference

Registry:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SessionStateMonitor]
"ReconnectCommands"=hex(7):00,00
"DisconnectCommands"=hex(7):00,00
"PassthroughReconnectCommands"=hex(7):22,00,43,00,3a,00,5c,00,50,00,72,00,6f,\
  00,67,00,72,00,61,00,6d,00,20,00,46,00,69,00,6c,00,65,00,73,00,5c,00,43,00,\
  69,00,74,00,72,00,69,00,78,00,5c,00,49,00,43,00,41,00,20,00,43,00,6c,00,69,\
  00,65,00,6e,00,74,00,5c,00,70,00,6e,00,61,00,67,00,65,00,6e,00,74,00,2e,00,\
  65,00,78,00,65,00,22,00,20,00,2f,00,72,00,65,00,63,00,6f,00,6e,00,6e,00,65,\
  00,63,00,74,00,00,00,00,00
"PassthroughDisconnectCommands"=hex(7):22,00,43,00,3a,00,5c,00,50,00,72,00,6f,\
  00,67,00,72,00,61,00,6d,00,20,00,46,00,69,00,6c,00,65,00,73,00,5c,00,43,00,\
  69,00,74,00,72,00,69,00,78,00,5c,00,49,00,43,00,41,00,20,00,43,00,6c,00,69,\
  00,65,00,6e,00,74,00,5c,00,70,00,6e,00,61,00,67,00,65,00,6e,00,74,00,2e,00,\
  65,00,78,00,65,00,22,00,20,00,2f,00,64,00,69,00,73,00,63,00,6f,00,6e,00,6e,\
  00,65,00,63,00,74,00,00,00,00,00
"StartupCommands"=hex(7):00,00
"UseHKLM"="0"
"EnablePassthroughCommands"="1"
"LogFileName"="c:\\SessionStateMonitor.log"
"SetClientName"="1"

Example Registry Screenshot:

Sample Log:

12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\UseHKLM
12/16/2010 2:37:28 PM:Reading Key value:0
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client EngineClientName
12/16/2010 2:37:28 PM:Reading Key value:
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client EngineClientName
12/16/2010 2:37:28 PM:Reading Key value:
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\DisconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\ReconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\PassthroughDisconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\PassthroughReconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\StartupCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\SessionStateMonitor\EnablePassthroughCommands
12/16/2010 2:37:28 PM:Reading Key value:1
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX\Install\ICA Client\InstallFolder
12/16/2010 2:37:28 PM:Reading Key value:C:\Program Files\Citrix\Online Plugin\
12/16/2010 2:37:28 PM:Client installed:C:\Program Files\Citrix\Online Plugin\
12/16/2010 2:37:28 PM:Reading Key:HKEY_CURRENT_USER\SOFTWARE\CITRIX\SessionStateMonitor\PreviousSessions
12/16/2010 2:37:28 PM:Reading Key value:0
12/16/2010 2:37:28 PM:------------------
12/16/2010 2:37:28 PM:Starting Monitor
12/16/2010 2:37:28 PM:checking for new client name
12/16/2010 2:37:28 PM:session list sessionID:1
12/16/2010 2:37:28 PM:session list clientname: JAG-SRV
12/16/2010 2:37:28 PM:current session state:WFActive
12/16/2010 2:37:28 PM:session count:1
12/16/2010 2:37:28 PM:New client name = JAG-SRV
12/16/2010 2:37:29 PM:Setting client name in reg = JAG-SRV
12/16/2010 2:37:29 PM:Writing value:HKEY_CURRENT_USER\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client Engine\ClientName:JAG-SRV
12/16/2010 2:37:29 PM:Setting volatile environment citrix client name = JAG-SRV
12/16/2010 2:37:29 PM:Writing value:HKEY_CURRENT_USER\Volatile Environment\1\ClientName:JAG-SRV
12/16/2010 2:37:29 PM:Setting environment citrix client name = JAG-SRV
12/16/2010 2:37:29 PM:Writing value:HKEY_CURRENT_USER\Environment\ClientName:JAG-SRV
12/16/2010 2:37:29 PM:Broadcasting WM_SETTINGCHANGE event
12/16/2010 2:37:29 PM:Current Session ID:1
12/16/2010 2:37:29 PM:--------------------------------------------------------
12/16/2010 2:37:29 PM:monitoring for state change
12/16/2010 2:37:41 PM:WFWaitSystemEvent return flags:144
12/16/2010 2:37:41 PM:Current Session ID:1
12/16/2010 2:37:41 PM:Disconnect event received
12/16/2010 2:37:41 PM:Disconnect:passthrough sessions detected:1
12/16/2010 2:37:41 PM:Running command: C:\Program Files\Citrix\Online Plugin\pnagent.exe
12/16/2010 2:37:41 PM:Running command arguments: /disconnect
12/16/2010 2:37:41 PM:Command return: True
12/16/2010 2:37:41 PM:Writing value:HKEY_CURRENT_USER\SOFTWARE\CITRIX\SessionStateMonitor\\PreviousSessions:1
12/16/2010 2:37:41 PM:--------------------------------------------------------
12/16/2010 2:37:41 PM:monitoring for state change
12/16/2010 2:37:57 PM:WFWaitSystemEvent return flags:168
12/16/2010 2:37:57 PM:Current Session ID:1
12/16/2010 2:37:57 PM:Connect event received
12/16/2010 2:37:57 PM:checking for new client name
12/16/2010 2:37:57 PM:session list sessionID:1
12/16/2010 2:37:57 PM:session list clientname: JAG-DESKTOP
12/16/2010 2:37:57 PM:current session state:WFActive
12/16/2010 2:37:57 PM:session count:1
12/16/2010 2:37:57 PM:New client name = JAG-DESKTOP
12/16/2010 2:37:57 PM:Setting client name in reg = JAG-DESKTOP
12/16/2010 2:37:57 PM:Writing value:HKEY_CURRENT_USER\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Client Engine\ClientName:JAG-DESKTOP
12/16/2010 2:37:57 PM:Setting volatile environment citrix client name = JAG-DESKTOP
12/16/2010 2:37:57 PM:Writing value:HKEY_CURRENT_USER\Volatile Environment\1\ClientName:JAG-DESKTOP
12/16/2010 2:37:57 PM:Setting environment citrix client name = JAG-DESKTOP
12/16/2010 2:37:57 PM:Writing value:HKEY_CURRENT_USER\Environment\ClientName:JAG-DESKTOP
12/16/2010 2:37:57 PM:Broadcasting WM_SETTINGCHANGE event
12/16/2010 2:38:00 PM:Reading Key:HKEY_CURRENT_USER\SOFTWARE\CITRIX\SessionStateMonitor\PreviousSessions
12/16/2010 2:38:00 PM:Reading Key value:1
12/16/2010 2:38:00 PM:Connect:Previous passthrough sessions detected
12/16/2010 2:38:00 PM:Running command: C:\Program Files\Citrix\Online Plugin\pnagent.exe
12/16/2010 2:38:00 PM:Running command arguments: /reconnect
12/16/2010 2:38:00 PM:Command return: True
12/16/2010 2:38:00 PM:Writing value:HKEY_CURRENT_USER\SOFTWARE\CITRIX\SessionStateMonitor\\PreviousSessions:0
12/16/2010 2:38:00 PM:--------------------------------------------------------
12/16/2010 2:38:00 PM:monitoring for state change

Additional Information

Where to download ?

Certain legacy Citrix tools are now available on request only. Please submit the request here - https://forms.gle/obA39PEz5qpDiSPq8

Once we verify your request, we will provide access to the download location.

Powered by Wolken Software