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
When using this utility to update the clientname on a Pass-through XenApp session, the full client plugin 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. Private fixes are available and can be obtained by contacting Citrix technical support and reference CPR 215510.
Installing Session State Monitor Utility
Caution! 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.
- 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.
HKEY_LOCAL_MACHINESOFTWARECitrixSessionStateMonitor
Note: For x64 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 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
- 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 filescitrixica clientpnagent.exe" /disconnect
Edit the “PassthroughReconnectCommands” string and add the value data:
Example:"c:program filescitrixica clientpnagent.exe" /reconnect - Create the following Registry Key for x86:
HKEY_LOCAL_MACHINESOFTWARECitrixICA ClientPass Through
Or for x64 create the following Registry Key:
HKEY_LOCAL_MACHINESOFTWAREWow6432nodeCitrixICA ClientPass Through
Add the following values:
Name: PASS THROUGH
Type: REG_DWORD
Value Data: 1
Known Issues
- 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:
SoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine
- This utility does not work with Anonymous Pass-through sessions from VDA to XenApp.
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 State Monitor Utility
To debug the utility, in the registry, populate the LogFileName value with path and file name for logging and restart utility. In Reference section below is 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
- Registry key created and used by the utility:
HKEY_LOCAL_MACHINESOFTWARECitrixSessionStateMonitor - 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_MACHINESoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine
If UseHKLM = 0: HKEY_CURRENT_USERSoftwareCitrixICA ClientEngineLockdown ProfilesAll RegionsLockdownClient Engine - If EnablePassthroughCommands equals 1 and there are active pass-through sessions, the following value will be populated:
HKCUSOFTWARECitrixSessionStateMonitorPreviousSessions - Endpoint’s hostname is broadcast to the session’s environment.
- Clientname user environment variable is updated.
Uninstalling Session State Monitor Utility
- Delete the folder where you unzipped the files.
- Remove the utility from the startup programs.
- 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 supportutilitys@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.
Download:
You can download the tool by clicking the icon on the right.
Reference:
You can read the complete CTX article here.