Manage basic deployment agents
You can use Session Recording to manage basic deployment agents. This feature provides a lightweight method to deploy Session Recording. You can use this deployment method for utilizing Session Recording basic functionalities–record active sessions to MP4 files without deploying the backend components such as Session Recording Servers, player, databases, and consoles.
Installation
The Session Recording Agent is installed along with the Citrix Virtual Delivery Agent (VDA) by default.
- New installation: When installing or upgrading to VDA version 2511 or later, the Session Recording Agent is installed and works in deployment mode.
- Existing installation: If you already have a Session Recording agent installed, you can switch to the basic deployment mode by upgrading the agent to version 2511 or later and changing the Session Recording Server Address to localhost in the Session Recording Agent properties.
Use the basic deployment agent
In the basic deployment mode, recordings can be triggered manually by end users or administrators using PowerShell commands. They can also be triggered by hotkeys or dynamic recording.
Start or stop recording by using PowerShell commands
Both end users and administrators can use PowerShell commands to manage recordings.
Import the Session Recording module
Before running any commands, ensure the necessary module is imported.
Open PowerShell and Import the module by running:
Import-Module -DisableNameChecking 'C:\Program
Files\Citrix\SessionRecording\Agent\Bin\EndUserInitiatedSRSnapin.dll'
Available Commands
The following table lists three PowerShell commands that provide for end user triggered session recording.
| Command | Description |
|---|---|
| Start-SessionRecording | Starts recording the active session in which the command is executed. To record a specific active session, use the -SessionId <ID> parameter (requires local administrator privileges). For more information, run Get-Help Start-SessionRecording to see the command online help. |
| Stop-SessionRecording | Stops recording the active session in which the command is executed. To stop recording a specific active session, use the -SessionId <ID> parameter (requires local administrator privileges). Note: Users can only stop recordings they initiated. They cannot stop recordings triggered by dynamic or policy-based recording. For more information, run Get-Help Stop-SessionRecording to see the command online help. |
| Get-SessionRecordingStatus | Retrieves the recording status of the active session in which the command is executed. To get the status of a specific active session, use the -SessionId <ID> parameter. For more information, run Get-Help Get-SessionRecording Status to see the command online help. |
Example 1: End-user triggered recording
End users can trigger recordings for their current active session to capture operations dynamically (for example, for troubleshooting purposes).
The user can perform the following steps inside the session:
-
Launch PowerShell from the session desktop.
- Import the module as described in the previous section.
- Use the
Get-SessionRecording Statuscommand to check the recording status, ensure the session is not already being recorded. - Use the
Start-SessionRecordingcommand to start recording the session. -
Use the
Get-SessionRecordingStatuscommand to check the recording status, ensure the session is being recorded. The status is supposed to be Recording.
- Reproduce the issue or perform the operations that need to be documented.
- Use the
Stop-SessionRecordingcommand to stop recording once the operations are complete. - Find the recording file and proceed with the follow-up troubleshooting. By default, the storage path is under:
% USE RPROFILE %\Videos\SessionRecordings, this can be customized by Configurating the basic deployment agent settings.
Note:
The recording will automatically stop when the session duration reaches 30 minutes, or the file size reaches 60 MB.
Example 2: Administrator-triggered recording
Administrators can trigger recordings for specific active sessions on the machine (for example, to assist a user with troubleshooting).
The administrator can perform the following steps on the machine hosting the session:
- Launch PowerShell as an administrator.
- Import the module as described in the previous section.
-
Get the SessionID of the target user session by using query session command.
query session | Select-String "Active"
-
Use the
Get-SessionRecordingStatus -SessionId <SessionID>command to check the recording status, ensure the session is not already being recorded. The status is supposed to be shown as below:
-
Use the
Start-SessionRecording -SessionId <SessionID>command to start recording the session. -
Use the
Get-SessionRecordingStatus -SessionId <SessionID>command to check the recording status, ensure the session is being recorded. The status is supposed to be Recording. - Instruct the user to reproduce the issue or perform the operations that need to be documented.
- Use the
Stop-SessionRecording -SessionId <SessionID>to stop recording once the operations are complete. - Find the recording file under the target user profile, such as:
C:\Users\user0\Videos\SessionRecordingsand proceed with the follow-up troubleshooting.
Start or stop recording by using Hotkey
End users can also control recording using shortcut keys (Hotkeys). By default, this feature is disabled.
Enable Hotkeys
To enable hotkey functionality, on the VDA machine:
Set-SessionRecordingConfiguration -PerMachine -EnableHotkeys $true
This command requires a local administrator account to execute.
The setting is applied per machine and will take effect for subsequent active sessions.
Default Hotkeys
Once enabled, the default hotkeys are:
- Start recording: CTRL + SHIFT + F8
- Stop recording: CTRL + SHIFT + F9
Note:
By default, the storage path is under:
%USERPROFILE%\Videos\SessionRecordings, this can be customized by Configurating the basic deployment agent settings.The recording will automatically stop when the session duration reaches 30 minutes, or the file size reaches 60 MB.
Customize Hotkeys
If the default hotkeys conflict with other applications, you can customize them using the following command:
Set-SessionRecordingConfiguration -PerMachine -StartHotKey <hotkey> -StopHotKey <hotkey>
Hotkey rules:
- Only F1–F12 or capital letters (A–Z) can be used as the last key.
- You only define the last key in the combination. The CTRL + SHIFT prefix is mandatory and automatically applied.
Example: To set the start hotkey to CTRL + SHIFT + F1, you would enter F1 as the <hotkey>.
Start or stop recording by using Dynamic Recording
You can also trigger recordings using Dynamic Session Recording policies. For more information, see Dynamic Session Recording.
Note:
By default, the storage path is under:
%USERPROFILE%\Videos\SessionRecordings, this can be customized by Configurating the basic deployment agent settings.The recording will automatically stop when the session duration reaches 30 minutes, or the file size reaches 60 MB.
Configurating the basic deployment agent settings
You can customize the settings for the basic deployment agent using PowerShell commands. These settings are applied at the machine or user level.
Prerequisites
Before configuring the settings, you must import the necessary module into the PowerShell session.
-
Open PowerShell and navigate to the agent installation folder:
<SessionRecordingAgent installation path>\Binfolder.For example:
cd "C:\Program Files\Citrix\SessionRecording\Agent\Bin\" -
Import the module by running:
import-module -DisableNameChecking.\EndUserInitiatedSRSnapin.dll
PowerShell configuration commands
The following table lists the PowerShell commands for managing session recording configuration:
| Command | Description |
|---|---|
| Set-SessionRecordingConfiguration | Sets session recording configuration values at the machine or user level. For more information, run Get-Help SetSessionRecordingConfiguration
|
| Get-SessionRecordingConfiguration | Gets the effective session recording configuration or queries raw values from specific registry scopes (Machine, User, or Session). For more information, run Get-Help GetSessionRecordingConfiguration
|
| Clear-SessionRecordingConfiguration | Clears session recording configuration values at the machine or user level, reverting them to machine-level or default values. For more information, run Get-Help ClearSessionRecordingConfiguration. |
Configuration settings
The settings available for the basic deployment mode are listed as follows. You can use the Set-SessionRecordingConfiguration cmdlet to configure them.
Add the -PerMachine switch parameter to apply the configuration at the machine. This requires administrator privileges. If specified, the settings apply to the machine level. If omitted, settings apply to the user level.
| Property | Type | Setting | Scope | Default | Note |
|---|---|---|---|---|---|
| -AllowUserTrigger | Boolean | Allow endusertriggered recording | Machine | True | Controls whether users can manually start/stop recordings |
| -StoragePath | String | Recording storage path | Machine, User, Session | %USERPRO FILE%\Videos\Session Recordings | The directory where recording files are saved. This directory can be located on a local drive, a UNC network path, or a mounted drive. |
| -MaximumDurationInMinutes | Int | Maximum recording duration | Machine, User, Session | 30 | The session automatically stops recording after this duration (in minutes). |
| -MaximumSizeInMegabytes | Int | Maximum file size | Machine, User, Session | 60 | The session automatically stops recording after reaching this size (in MB). |
| -EnablePreRecording | Boolean | Enable prerecording | Machine | False | Enable pre-recording before recording trigger. |
| -EnablePreRecording | Boolean | Enable prerecording | Machine | False | Enable pre-recording before recording trigger. |
| -PreRecordingDurationInSeconds | Int | Prerecording duration | Machine | 30 | The duration of the pre-recording buffer in seconds. |
| -EnableHotkeys | Boolean | Enable hotkeys | Machine | False | Enables hotkeys for start/stop recording |
| -StartHotkey | String | Start recording hotkey | Machine | F8 | Default maps to CTRL + SHIFT + F8. |
| -StopHotkey | String | Stop recording hotkey | Machine | F9 | Default maps to CTRL + SHIFT + F9. |
| -ScreenId | Int | The screen ID to record | Machine, User, Session | 0 | Use 0 for all screens. |
Note:
If you customize these settings at multiple levels, the priority order is: Session > User > Machine.
Example Configuration
These examples illustrate how different users set configurations and how the agent determines the final, effective setting.
Example 1: Administrator Disabling User-Triggered Recording
A local administrator (e.g. LocalAdmin) can set a machine-wide policy to disable the ability for all standard users to start recordings manually.
Set-SessionRecordingConfiguration -PerMachine -AllowUserTrigger $false
Explanation: This command requires administrative privileges (-PerMachine) and prevents any user on this VDA from using Start-SessionRecording, regardless of their user-level settings.
Example 2: Administrator Setting Machine-Wide Defaults
The LocalAdmin sets the default storage location, maximum duration, and maximum size for all users on the VDA.
Set-SessionRecordingConfiguration -PerMachine -StoragePath
"D:\SessionRecordings"-MaximumDurationInMinutes 120 -
MaximumSizeInMegabytes 500
Explanation: This sets the configuration at the Machine level. For a standard user (e.g. User0), recordings will now default to D:\SessionRecordings and stop after 120 minutes or 500 MB, whichever comes first.
Example 3: Standard User Overriding Machine Defaults
The standard user (User0) prefers to save their files locally to the C: drive, overriding the administrator’s Machine-level setting.
Set-SessionRecordingConfiguration -StoragePath
"C:\Users\User0\ SessionRecordings" -MaximumDurationInMinutes 60
Explanation: Since this command is run without the -PerMachine switch, it applies at the User level. Because User-level settings have a higher priority than Machine-level settings, User0’s recordings will now be saved to C:\Users\User0\ SessionRecordings and stop after 60 minutes.
Example 4: Session-Specific Override
During a specific recording, User0 needs to temporarily save the file to a network share (\\fileshare\temp) and limit the duration to 15 minutes, overriding both User and Machine settings.
Start-SessionRecording -StoragePath "\\fileshare\temp" -
MaximumDurationInMinutes 15
Explanation: Parameters passed directly to Start-SessionRecording to create a session-level override, which has the absolute highest priority and is only valid for that single recording instance. The next recording session will revert to the User or Machine configuration.
Checking Configuration
Use the Get-SessionRecordingConfiguration commandlet to view the currently configured values and the final effective setting:
Get-SessionRecordingConfiguration
Explanation: This command shows the result of applying the hierarchy (Session > User > Machine), providing the settings currently in use for the user running the command.
Clearing Configuration
Use the Clear-SessionRecordingConfiguration commandlet to remove custom settings, allowing the agent to fall back to the next-highest priority configuration.
-
Clear specific user settings:
If User0 wants to stop saving files to C:\Users\User0\SessionRecordings and revert custom settings to the default setting, they would run:
Clear-SessionRecordingConfiguration -StoragePath - MaximumDurationInMinutes
Explanation: This clears the StoragePath and MaximumDurationInMinutes values from the User scope.
-
Clear all machine-level configurations (Requires Administrator Privileges):
Clear-SessionRecordingConfiguration -PerMachine -ClearAll
Explanation: This command requires administrative privileges (-PerMachine) and clears all custom configurations set at the Machine level.
Switch the agent deployment type
The Session Recording agent supports two distinct deployment modes:
- Basic deployment mode: This provides a lightweight method to record active sessions locally as MP4 files without deploying backend components. This mode is active when the Session Recording Server address is set to localhost.
- Standard deployment mode: This is the traditional, centrally managed deployment where the agent connects to a Session Recording Server. This mode offers high scalability and advanced features. This mode is active when the Session Recording Server address is set to the Fully Qualified Domain Name (FQDN) of the server.
The operational mode is determined by the Session Recording Server value configured in the Session Recording Agent Properties or the Windows registry.
Method 1: Using the Session Recording Agent Properties
You can switch modes manually on a specific VDA.
-
Log on to the VDA where the Session Recording agent is installed.
-
From the Start menu, choose Session Recording Agent Properties.
-
Click the Connections tab.
- Modify the value in the Session Recording Server field:
- Basic deployment mode: Enter localhost.
- Standard deployment mode: Enter the FQDN of your Session Recording Server.
- Click OK to save the changes.
Method 2: Using the Windows Registry or Group Policy
For large-scale deployments, you can configure the setting directly in the Windows Registry, typically deployed via Group Policy Object (GPO).
-
Registry Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SmartAuditor\Agent\ -
Value Name:
SmAudServerName -
Value Data:
- For basic deployment mode: Set the value to localhost.
- For standard deployment mode: Set the value to the FQDN of your Session Recording Server.
Note:
Key considerations for mode switching
-
The Session Recording agent reads the configuration value only at the start of a session. Any change to the deployment mode will take effect on the next new session launched on the VDA.
-
It is strongly recommended that you do not switch modes while there are active or in-progress recording sessions. Wait for all active recordings to stop to prevent data consistency issues.
Manage recording files
Session Recording provides a local tool, SRAgentTool.exe, to help you manage recording files. The tool offers the following capabilities:
-
Recover corrupted MP4 recordings: Repairs MP4 files that are unplayable due to abnormal situations, such as an unexpected graphics process crash.
-
Verify MP4 recording integrity: Checks whether a recording file has been tampered with to ensure its authenticity.
You can access the tool in the following directory: <Session RecordingAgent installation path>\Bin.
View usage instructions
To view the help information and usage instructions for the tool, run the following command in PowerShell or Command Prompt:
.\SRAgentTool.exe --help
Or
.\SRAgentTool.exe -h
Recover corrupted recordings
If a recording file cannot be played, use the recovery command to attempt a repair. Command:
.\SRAgentTool.exe --recover <path_to_mp4>
Output:
-
Success: The tool displays Recover success and shows the path of the newly recovered file (typically suffixed with _recover.mp4).
-
No recovery needed: If the file is already playable, the tool displays The file can play normally, need not recover.
Verify recording integrity
To verify that a recording file has not been modified, use the validation command to check its SHA512 signature.
Command: .\SRAgentTool.exe --valid <path_to_mp4>
Output:
-
Valid: The sha512 signature matches successfully.
-
Tampered: The sha512 signature does not match.
-
Invalid File: The file is not legal mp4 file.
