***New release expected Q3 2023. It will include browser language detection to make it easy to translate into different languages. Also includes some new methods and further improvements.
***If using a release less than v1.9, please refer to the release history below to understand the new features, enhancements and fixes now included.
This tool has been labelled as a game changer for any Citrix customer. It’s proven time and time again that it has a huge impact on reducing the burden on the Service Desk and Operations Teams by empowering users to get themselves back up and running in the shortest possible time.
No matter how stable your Citrix platform is, one of the biggest challenges for any Citrix customer is being able to reduce Service Desk calls and user downtime by empowering users with the ability to clear their own sessions, or recover them by terminating rogue processes. Several free scripts and a paid for tool are available, but none of them really achieve the best outcome. Some of them still require users to run a “Citrix session”, which they often can not do because the broker may be trying to reconnect them back to a stuck, hung, broken session or unhealthy host. When this happens they get into an endless loop of failure and get very frustrated. This can impact brand reputation and user satisfaction, leaving users with a poor felt experience. Some have even implemented a separate Citrix Environment to run these scripts from. In my opinion this is as waste of resources and an overhead for management. It still doesn’t always work due to Citrix Workspace (Receiver) reconnection issues and is often over complicating it for users.
My goals were to:
- Create a tool that is easy to use, even for users that struggle with technology.
- Create a tool that enables users to not only get themselves back up and running in the shortest possible time, but also reduces the reliance on Service Desk and even second level support teams.
- Create a tool that does not rely on any ICA/HDX connectivity to a Citrix platform. This was extremely important!
- Create a tool that would allow support for multiple Citrix Virtual Apps and Desktops (CVAD aka XenApp and XenDesktop) Sites.
- Create a tool that works across trusted Domains.
- Create a tool that works across the IT and OT landscape.
- Create a tool that can easily be extended/expanded for other use cases.
- Create a tool that’s modular so that other brokers such as VMware Horizon and Leostream can easily be added.
- Create API’s with a Web front-end.
- Create a tool that can be used to develop a microapp.
- Create a tool that can easily be called by any scripting language such as PowerShell and Python.
- Create a tool that can be enhanced, debugged and supported by others.
- Create a tool for the community, because I love doing that!
There are no tools readily available like this. I have put it to Citrix many times that they really need a “self” role in Director. I submitted an enhancement request under RFE ID-006471. All the code is already there, so pretty easy for them to implement, but they didn’t seem to feel it was important enough to give it priority. Their focus is Citrix Cloud with ServiceNow integration as an example. Not really practical for most. Whilst initially disappointed, in hindsight I’m happy they didn’t action my enhancement request, as it’s given me the opportunity to build something very cool, which I really enjoyed doing, and learning heaps along the way.
After a lot of research and hundreds of hours of coding I created RESTful-like APIs that follow the CRUD principles using an ASP .NET Web API 2.2 project following the Model View Controller (MVC) architecture to achieve the outcome of delivering this as a web service coded exclusively in C#. This does all the heavy lifting. In fact, it became so addictive to continue to enhance the code and add features, I achieved the end result well beyond what I’d planned as a first release.
The client interface uses HTML, CSS and JavaScript for the layout and workings, but jQuery and AJAX behind the scenes to do all the main work calling the APIs to get and action the data, and then manipulating the data so that it is presented in a readable and friendly format for the users. This is simply the web front-end, but you can create and use your own scripts and applications by simply calling the RESTful-like APIs I’ve created.
This web form uses windows authentication in IIS, so it only enumerates sessions and processes for the logged on user.
There is also the ability to include and/or exclude Delivery Groups. You may have specific business critical applications and data that is sensitive where you would still prefer that the Service Desk or other support teams are able to triage the issues as per normal. These sessions will still appear when enumerated, but are greyed out and unable to be selected for self-service by the user.
Depending on what features/actions you would like enabled, users can:
- Logoff Sessions
- Disconnect Sessions
- Get Processes
- Terminate Processes
- Restart Machines
- Forcefully Restart Machines
- Hide Stuck Sessions
- Unhide Sessions
The instructions will change dynamically depending on the features you have enabled via the Web.config file.
So here is what the latest version of the tool looks like with all default features enabled:
The only configuration required in the tool itself is to setup the Sites in the CtxSites.xml file under the App_Data folder.
- FriendlyName: The name in the drop down list that Users will associate with
- Name: Can be the real Site name, or just a short name used to identify the site. It’s passed internally between functions so that the corresponding values are retrieved and used from the XML file for that Site.
- DeliveryControllers: A comma separated list of Delivery Controllers or Cloud Connectors for that site
- Port: The port number the Delivery Controllers or Cloud Connectors listen on. An XDPing is run against them to ensure they are healthy.
- Default: The default value is False. Set this to True if you have multiple Sites but want 1 Site to be the default selected when users access the tool. If only 1 Site is added to the XML file, it will automatically default to this Site, so there is no need to set a value for Default.
- IncludeDeliveryGroups: A list of comma separated Delivery Groups to include. Will include all if left empty.
- ExcludeDeliveryGroups: A list of comma separated Delivery Groups to exclude. Will override inclusions if there are conflicts.
- ProfileType: Must be either OnPrem for on-prem Sites or CloudAPI for Citrix Cloud Sites.
- CustomerID: Citrix Cloud Customer ID.
- ClientID: Citrix Cloud Client ID also known as the API Key.
- ClientSecret: Citrix Cloud Client Secret also known as the Secret Key.
The requirements and prerequisites are very straight forward:
- IIS with Windows Authentication enabled and Anonymous Authentication disabled.
- The application runs under its own Application Pool, configured to run as a Service Account.
- Minimum of .NET Framework 4.5.2.
- CVAD (XenApp and XenDesktop) Remote PowerShell SDK , the PowerShell SDK with Citrix Cloud Connector, or Citrix Studio.
- You can use Citrix Studio if setting this tool up for on-prem only. However, it’s now recommended to install the CVAD (XenApp and XenDesktop) Remote PowerShell SDK. Whilst it also works with the Citrix Cloud Connector, you would need to change the Default Web Site to run on a different port, such as 81.
- The C# code uses the underlying PowerShell Citrix.Broker.Admin.V2 snapin. It uses the Get-BrokerSession, Get-BrokerMachine, Stop-BrokerSession, Disconnect-BrokerSession, Set-BrokerSession and New-BrokerHostingPowerAction cmdlets for the actions.
- When using the CVAD (XenApp and XenDesktop) Remote PowerShell SDK or the PowerShell SDK with Citrix Cloud Connector, it also uses the Set-XDCredentials, Get-XDAuthentication and Get-XDCredentials cmdlets.
- The Service Account needs to be a local Admin on the web server. I am still working on trying to minimise the permissions required here without over complicating the installation and configuration.
- The Service Account needs to be a Help Desk Administrator in the Citrix Site(s). That is it!
- The Service Account needs to be a local Admin on the Session Hosts to be able to remotely enumerate and terminate user processes.
- When using the Set-XDCredentials cmdlet, we can get the error “The data protection operation was unsuccessful. This may have been caused by not having the user profile loaded for the current thread’s user context, which may be the case when the thread is impersonating”. This is because the Service Account needs a local profile on the server in order to save the specified APIKey and SecretKey pair to a persistent credentials store. So in the IIS Application Pool configuration, we set the Load User Profile option to True.
Implementing SAML2 authentication: I’ve been asked about this, but is not something I will be adding to the tool at this stage. Please look at doing this at the IIS level using the Shibboleth ISAPI Filter, which is part of the Service Provider product and free for commercial use. There is plenty of helpful documentation on it.
When hosted on-perm, it actually makes sense to co-host this tool on the StoreFront servers. StoreFront servers are typically load balanced, already have all required IIS components installed, have a certificate, and have a URL that is typically known to the Users. So all you need to do is install CVAD (XenApp and XenDesktop) Remote PowerShell SDK and configure IIS. Too easy! You could also customise StoreFront to add a hyperlink to the page.
Basic Installation Instructions:
- Install IIS using the following PowerShell code:
$ServicesToInstall = @( "Web-Windows-Auth", "Web-ISAPI-Ext", "Web-Metabase", "Web-WMI", "NET-Framework-Features", "Web-Asp-Net", "Web-Asp-Net45", "NET-HTTP-Activation", "NET-Non-HTTP-Activ", "Web-Static-Content", "Web-Default-Doc", "Web-Dir-Browsing", "Web-Http-Errors", "Web-Http-Redirect", "Web-App-Dev", "Web-Net-Ext", "Web-Net-Ext45", "Web-ISAPI-Filter", "Web-Health", "Web-Http-Logging", "Web-Log-Libraries", "Web-Request-Monitor", "Web-HTTP-Tracing", "Web-Security", "Web-Filtering", "Web-Url-Auth", "Web-Performance", "Web-Stat-Compression", "Web-Mgmt-Console", "Web-Scripting-Tools", "Web-Mgmt-Compat" ) Install-WindowsFeature -Name $ServicesToInstall -IncludeManagementTools
DO NOT install the IIS WebDAV Publishing feature. The WebDAVModule in IIS will block the DELETE and PUT requests giving you a 405 error, Method Not Allowed.
- Extract the tool to a folder local to the IIS server such as C:\SelfServiceSessionReset
- Open IIS Manager
- Right Click on Application Pools
- Select Add Application Pool…
- Name: SSSR
- Ensure the “Managed Pipeline Mode” is set to Integrated, which should be the default. If it’s set to Classic, the tool will not function correctly giving 404 errors when selecting any of the actions.
- Select OK
- Select Application Pools
- Right click on SSSR
- Select Advanced Settings…
- Select Identity under Process Model
- Select …
- Select Custom account
- Select Set
- User name: Enter the service account in the form of DOMAIN\USERNAME
- Password: enter the password
- Confirm password: enter the password again
- Select OK
- Select OK
- Select Load User Profile under Process Model and set it to True. This is required for the Set-XDCredentials cmdlet when saving to a persistent credentials store.
- Verify that Enable 32-Bit Applications under General is set to False
- Select OK
- Right Click on Default Web Site
- Select Add Application…
- Alias: SSSR
- Select Select…
- Application Pool: SSSR
- Select OK
- Physical path: Enter the path where you extracted the tool to, such as C:\SelfServiceSessionReset
- Select OK
- Select the SSSR application
- Right Click on Authentication
- Select Open Feature
- Right Click on Anonymous Authentication
- Select Disable
- Right Click on Windows Authentication
- Select Enable
- Close IIS Manager
- Modify the Site data in the CtxSites.xml file, which may be located at C:\SelfServiceSessionReset\App_Data\CtxSites.xml
- Install Citrix Studio
- Add the Service Account as a local admin on the Web Server
- Add the Service Account as a Help Desk Administrator in the Citrix Site(s)
- Add the Service Account as a local Admin on the Session Hosts if using the Get and Terminate Processes functions.
Ensure you secure the C:\SelfServiceSessionReset folder if the CtxSites.xml file will contain the Citrix Cloud authentication information (CustomerID, ClientID and ClientSecret) and/or the SmtpAuthUsername and SmtpAuthPassword in the Web.config file.
Test the tool by opening a modern web browser other than Internet Explorer (IE) and going to http://webserver/SSSR/
You can turn features on or off via the Web.config:
- sssrt:EnableLogoffSessions: Setting it to False disables the Logoff Sessions function in the API and UI.
- sssrt:EnableDisconnectSessions: Setting it to False disables the Disconnect Sessions function in API and UI.
- sssrt:EnableGetTerminateProcesses: Setting it to False disables the Get Processes and Terminate Processes functions in the API and UI.
- sssrt:EnableGracefulMachineRestart: Setting it to False disables the Restart Machines function in the API and UI.
- sssrt:EnableForcedMachineRestart: Setting it to False disables the Forcefully Restart Machines function in the API and UI.
- sssrt:EnableHideStuckSessions: Setting it to False disables the Hide Sessions function in the API and UI.
- sssrt:EnableInstructions: Setting it to False disables the instructions in the UI.
- sssrt:BypassCriteriaChecksForHideSessions: Setting to True bypasses the criteria checks for the Hide Sessions function for the API and UI. Not recommended and disabled by default.
- sssrt:EnableUnhideSessions: Setting it to True enables the Unhide Sessions function in the API and UI. This feature will only work if the sssrt:BypassCriteriaChecksForHideSessions is also set to True. Not recommended and disabled by default.
- sssrt:EnableEmailForLogoffSessions: Setting to True will send and email when a user initiates the Logoff Sessions function.
- sssrt:EnableEmailForDisconnectSessions: Setting to True will send and email when a user initiates the Disconnect Sessions function.
- sssrt:EnableEmailForTerminateProcesses: Setting to True will send and email when a user initiates the Terminate Processes function.
- sssrt:EnableEmailForMachineRestart: Setting to True will send and email when a user initiates either of the Restart Machines functions.
- sssrt:EnableEmailForHideSessions: Setting to True will send and email when a user initiates the Hide Sessions functions.
- sssrt:SenderName: Set to the sender name, such as “Self-Service Session Reset Tool”.
- sssrt:SenderEmailAddress: Set to the actual sender email address, such as sssrt@mycompany.com.
- sssrt:RecipientEmailAddresses: Set to the recipient email address, such as example@mycompany.com. You can send to multiple recipients just by using a comma to separate them.
- sssrt:SmtpServer: Set to the FQDN of the SMTP server, such as smtp.mycompany.com.
- sssrt:SmtpPort: Set to the TCP port number of the SMTP server, such as 25.
- sssrt:SmtpAuthUsername: If you need to authenticate to the SMTP server, set the username and password.
- sssrt:SmtpAuthPassword
- sssrt:SubjectStartsWith: You can leave this blank or set a string that will be set at the start of the subject line. This may assist you with workflow.
- sssrt:BodyTextStartsWith: Likewise, you can also set a string at the start of the email body.
You can also see from the Web.config that logging has been implemented. By default we keep 12 log files that are rolled over monthly. So you will build up to 1 years worth of logs that allows you to audit, review and even engage and train users to improve their experience. Of course you can change the rollingInterval to Day and retainedFileCountLimit to the number of daily logs you want to keep. All actions are logged in an easy to read format as per the following screen shot so you will always know how the tool is being used.
Known Issues and Limitations:
- Does not support Internet Explorer (IE). The version of jQuery used no longer supports IE 11. The UI does not function. When debugging in IE11 you will receive the following error: Error: Object doesn’t support property or method ‘addEventListener’. So you must use a modern browser such as Chrome, Edge, etc. IE was officially retired and out of support as of 15th June 2022, so there was no value building support for it in this tool.
- Depending on the location of this tool to your Session Hosts, getting the processes and their data may take some time as it is making a Remote Procedure Call (RPC) from the web server to the Session Hosts to get the processes and their extended perfmon data. Ideally you would want to locate this tool in the same location as the Session Hosts to limit delays (latency) and improve the user experience.
- The tool in its current form will only work in English. I expect to have a release in Q3 2032 for browser language detection; making it easy to translate into different languages.
Future Improvements and Feature Requests:
- Client side WPF (Windows Presentation Foundation) App, which would be very light, as it’s simply just calling APIs.
- Browser language detection.
- Splunk integration.
Version 1.9 Updates 1st June 2022:
- Added support for User Principal Names (UPNs) for Citrix functions by setting the UseUPN element in the CtxSites.xml to true. Depending on your Citrix integration, this may be required based on certain use cases when using Citrix Federated Authentication Service (FAS).
- Enhanced the XDPing function by changing the structure and logging so that issues can easily be traced.
Version 1.8 Updates 12th March 2022:
- Fixed an issue where Sessions on Unregistered VDAs would fail to enumerate due to a NULL property value returned from the Get-BrokerSession cmdlet.
- Addressed various spelling mistakes.
- Improved logging to understand when the Citrix.Broker.Admin.V2 snap-in fails to load.
- Improved logging to understand when there are insufficient permissions to return data from the cmdlets.
- Improved logging to verify the IIS Application Pool name and identity it’s running as.
- Improved logging to understand when there are no healthy Delivery Controllers available.
- All logging enhancements assist with initial implementation issues.
Version 1.7 Updates 13th October 2021:
- Added the Email feature, configurable in the Web.config. This enables the sending of emails based on the user action, which can also be used to automatically log and close an incident in your IT Service Management (ITSM) tool of choice, such as ServiceNow, TOPdesk, ZenDesk, etc.
- Added the ability to Hide Stuck Sessions that are stuck in the Suspended power state.
- Added the ability to disable the Logoff Sessions feature.
Version 1.6 Updates 28th July 2021:
- Logging of all actions to a log file for auditing, review and user training.
- Added the ability to Hide Stuck Sessions by bypassing the criteria checks.
- Added an Unhide Sessions feature.
Version 1.5 Updates 5th July 2021:
- Citrix Cloud Ready: Now works with Citrix Cloud.
- Works with the CVAD (XenApp and XenDesktop) Remote PowerShell SDK.
- Works with the PowerShell SDK with Citrix Cloud Connector.
- Added a Disconnect Sessions feature.
- Added a Forcefully Restart Machines feature.
- Added the ability to Hide Stuck Sessions for machines stuck in the TurningOff phase of the restart.
- The ability to disable all features/actions accept for Logoff Sessions.
- Enhanced and modularized the instructions.
- Improved security checks for the Terminate Processes function
Version 1.4 Updates 15th October 2020:
- Corrected some variables and typos. These issues were not related to the operation of the tool itself.
Version 1.3 Updates 15th September 2020:
- A syntax error in the JavaScript code of the RestartMachines variable prevented machines from excluded Delivery Groups from being displayed.
Version 1.2 Updates 12th September 2020:
- Made the the RestartMachines a DELETE action instead of a PUT action. It works either way, but for the API purist it should be a DELETE action.
- Cleaned up the API documentation for the GetSiteList action.
Version 1.1 Updates 9th September 2020:
- You can now set a Default Site for the Site Selection in the XML file. Or if there is only 1 Site configured, it will automatically Get Sessions for that Site. Both options reduce the need for the user to select a Site.
- Added the Restart Machine function using the New-BrokerHostingPowerAction cmdlet. This is applicable for Windows Desktop Operating Systems that support Single Session only. A new column was added named “Restart Supported” to help users understand when this function is supported. This action initiates a graceful restart and not a forced restart, and is covered under the Help Desk Administrator role. So no further permissions are required.
- All non-API methods and functions have been set to Private instead of Public in the Controllers.
- The username is no longer passed in the API calls. This is managed in the internal code of the Controllers only. This enhances security and reduces the risk of someone injecting someone else’s username. This also ensures the tool obtains a good CIA (Confidentiality, Integrity and Availability) triad/rating and/or a Technical Security Assessment (TSA) and/or a Security Risk Assessment (SRA).
The tool is located in my GitHub repositories where you can download the latest compiled Release as a zip posted to the right hand side of the repository. Total number of downloads to date: 376.
This software is free for Commercial use. It cannot be used for revenue-generating activities. I retain all rights to the source code and no one may reproduce, distribute, or create derivative works from this project without permission. This project is licensed by the GNU General Public License v3.0, which you can view in the COPYING file on the GitHub repository.
I have released some documentation on how the APIs work, and will soon add more information on how to make some minor UI changes, such as the colours.
Once you get the tool up and running there is a help page that documents the APIs, which was created using the standard Microsoft.AspNet.WebApi.HelpPage package. You can access this by the http://webserver/SSSR/help URL.
If you’d like more verbose information on how the tool works, please refer to my Citrix Converge sessions:
- Citrix Converge 2020 Session – Building Useful Tools to Enhance The User Experience; Reducing The Service Desk Burden: Self-Help for Citrix Customers.
- Citrix Converge 2021 Session – The Self-Service Session Reset Tool 12 months on; How feedback, experience and lessons learnt have driven new features and security enhancements.
Let me know if you see anything that is not working, or if there are any features I haven’t covered off on that you feel should be user facing.
I’ve spent hundreds of hours working on this tool, which is freely available for commercial use. If you feel it provides you and your business value, and reduces user frustration, I would appreciate a donation as a way to say thanks.
Enjoy!
Jeremy Saunders