CTX127491 – Session State Monitor Tool – XenApp/XenDesktop – Citrix Knowledge Center

By gunnalagCitrix

Session State Monitor Tool

Created on: 1/24/2011
Updated on: 10/17/2011

Description

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

Prerequisites

When using this tool to update the clientname on a Pass-through XenApp session, the full client plug-in must be installed on the first hop and the client must have fix 215510 (see note below).

Note: The current 12.0 and 12.1 client endpoint builds detect a pass-through session when running inside a VDA on an ICA connection and disable the disconnect/reconnect options. This was by design. Private fixes are available and can be obtained by contacting Citrix Technical Support and referencing CPR 215510.

Installing Session State Monitor Tool

Caution! This procedure requires you to edit the registry. Using Registry Editor incorrectly can cause serious problems that might require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of the Registry Editor can be solved. Use the Registry Editor at your own risk. Back up the registry before you edit it.

  1. Extract the contents of the zip file to a folder.
    The zip file 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 used by the tool to run custom commands during any specified state.
  1. Import the SessionStateMonitor.reg file or manually add the following registry keys:

Create the following key.
HKEY_LOCAL_MACHINESOFTWARECitrixSessionStateMonitor

Note: For 64-bit, create:

HKEY_LOCAL_MACHINESOFTWAREWow6432nodeCitrixSessionStateMonitor

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 registry and environment variables for ‘clientname’ should be updated.
  • Name: LogFileName
    Type: REG_SZ
    Value Data: (path and file name for log file)
    Definition: If populated, enables logging to the provided file and path. Do not use quotes.
  • Name: SetClientName
    Type: REG_SZ
    Value Data: 1 (0 will disable)
    Definition: determines whether registry and environment variables for ‘clientname’ should be updated.
  1. 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 tool attempts 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 the path to pnagent.exe
    Example:"c:program filescitrixica clientpnagent.exe" /disconnect
  • Edit the “PassthroughReconnectCommands” string and add the value data:
    Example:"c:program filescitrixica clientpnagent.exe" /reconnect
  1. Create the following Registry Key:
    HKEY_LOCAL_MACHINESOFTWARECitrixICA ClientPass Through
    Add the following values:
    Name: PASS THROUGH
    Type: REG_DWORD
    Value Data: 1

Known Issues

  1. If the UseHKLM value has been set to both 0 and 1 on same machine, the following error might appear and applications fail to launch.

“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:

SoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine

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

How to Use Session State Monitor Tool

Once the tool is installed and running as a background process, it automatically monitors the session for any disconnects and reconnects. It updates the endpoint’s client name on the session and runs any custom commands from the registry.

Debugging Session State Monitor Tool

To debug the tool, in the registry, populate the ‘LogFileName’ value with path and file name for logging and restart tool. In the More Information section below is a debug example log of a good disconnect and subsequent reconnect:

Security Permissions Required by Session State Monitor Tool

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

Data Modified by Session State Monitor Tool

  1. Registry key created and used by the tool:
    HKEY_LOCAL_MACHINESOFTWARECitrixSessionStateMonitor
  2. If ‘EnablePassthroughComma
    nds equals 1, the “ClientName” value gets updated with the endpoint’s hostname in the registry in the following key:
    If UseHKLM = 1: HKEY_LOCAL_MACHINESoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine
    If UseHKLM = 0: HKEY_CURRENT_USERSoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine
  3. If ‘EnablePassthroughCommands equals 1 and there are active pass-through sessions, the following value is populated:
    HKCUSOFTWARECitrixSessionStateMonitorPreviousSessions
  4. Endpoint’s hostname is broadcast to the session’s environment.
  5. Clientname user environment variable is updated.

Uninstalling Session State Monitor Tool

  1. Delete the folder where you unzipped the files.
  2. Remove the tool from the startup programs.
  3. Backup and remove the registry key created under the installation instructions above.

Contact Information

For questions or concerns please send any feedback for this tool 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.

More Information

Registry:

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINESOFTWARECitrixSessionStateMonitor]
"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 Screen shot:

Sample Log:

12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorUseHKLM
12/16/2010 2:37:28 PM:Reading Key value:0
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient EngineClientName
12/16/2010 2:37:28 PM:Reading Key value:
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient EngineClientName
12/16/2010 2:37:28 PM:Reading Key value:
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorDisconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorReconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorPassthroughDisconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorPassthroughReconnectCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorStartupCommands
12/16/2010 2:37:28 PM:Reading Key value:System.String[]
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXSessionStateMonitorEnablePassthroughCommands
12/16/2010 2:37:28 PM:Reading Key value:1
12/16/2010 2:37:28 PM:Reading Key:HKEY_LOCAL_MACHINESOFTWARECITRIXInstallICA ClientInstallFolder
12/16/2010 2:37:28 PM:Reading Key value:C:Program FilesCitrixOnline Plugin
12/16/2010 2:37:28 PM:Client installed:C:Program FilesCitrixOnline Plugin
12/16/2010 2:37:28 PM:Reading Key:HKEY_CURRENT_USERSOFTWARECITRIXSessionStateMonitorPreviousSessions
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_USERSOFTWARECitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient EngineClientName: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_USERVolatile Environment1ClientName: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_USEREnvironmentClientName: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 FilesCitrixOnline Pluginpnagent.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_USERSOFTWARECITRIXSessionStateMonitor\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_USERSOFTWARECitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient EngineClientName: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_USERVolatile Environment1ClientName: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_USEREnvironmentClientName:JAG-DESKTOP
12/16/2010 2:37:57 PM:Broadcasting WM_SETTINGCHANGE event
12/16/2010 2:38:00 PM:Reading Key:HKEY_CURRENT_USERSOFTWARECITRIXSessionStateMonitorPreviousSessions
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 FilesCitrixOnline Pluginpnagent.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_USERSOFTWARECITRIXSessionStateMonitor\PreviousSessions:0
12/16/2010 2:38:00 PM:——————————————————–
12/16/2010 2:38:00 PM:monitoring for state change

This document applies to:

Source: CTX127491 – Session State Monitor Tool – XenApp/XenDesktop – Citrix Knowledge Center

By gunnalag

You might also like:

Expired and NEW Citrix Certification Programs

FIX: CentOS 6.8 Minimal Install: Device eth0 does not seem to be present, delaying initialization

Functions of the Local Host Cache (LHC) in Citrix IMA

Leave a Reply

Your email address will not be published. Required fields are marked *