Session Recording

Install, upgrade, and uninstall

Note:

To configure server high availability through load balancing, see Configure load balancing in an existing deployment and Deploy and load-balance Session Recording in Azure.

This article includes the following sections:

Installation checklist

You install the Session Recording components by using the following files:

  • Broker_PowerShellSnapIn_x64.msi

  • SessionRecordingAdministrationx64.msi

  • SessionRecordingAgentx64.msi

  • SessionRecordingPlayer.msi

  • SessionRecordingWebPlayer.msi

Before you start the installation, complete this list:

Step
  Install the prerequisites before starting the installation. See System requirements and Use Citrix scripts to install the Windows roles and features prerequisites.
  Select the machines on which you want to install each Session Recording component. Make sure that each machine meets the hardware and software requirements for the component or components to be installed on it.
  Use your Citrix account credentials to access the Citrix Virtual Apps and Desktops download page and download the product file. Unzip the file.
  To use the TLS protocol for communication between the Session Recording components, install the correct certificates in your environment.
  Install any hotfixes required for the Session Recording components. The hotfixes are available from the Citrix Support.
  Configure Director to create and activate the Session Recording policies. For more information, see Configure Director to use the Session Recording server.

Note:

  • We recommend that you divide the published applications into separate Delivery Groups based on your recording policies. Session sharing for published applications can conflict with the active policy if the applications are in the same Delivery Group. Session Recording matches the active policy with the first published application that a user opens. Starting with version 7.18, you can use the dynamic session recording feature to start or stop recording sessions at any time during the sessions. For more information, see Dynamic session recording.
  • If you plan to use Machine Creation Services (MCS) or Citrix Provisioning, prepare a unique QMId. Failure to comply can cause recording data losses.
  • SQL Server requires that you enable TCP/IP, the SQL Server Browser service is running, and Windows Authentication is used.
  • To use HTTPS, configure server certificates for TLS/HTTPS.
  • Make sure that users under Local Users and Groups > Groups > Users have write permission to the C:\windows\Temp folder.

Use Citrix scripts to install the Windows roles and features prerequisites

For Session Recording to work properly, use the following Citrix scripts to install the necessary Windows roles and features prerequisites before installing Session Recording:

  • InstallPrereqsforSessionRecordingAdministration.ps1

     <#
     .Synopsis
         Installs Prereqs for Session Recording Administration
     .Description
         Supports Windows Server 2022, Windows Server 2019 and Windows Server 2016.
         Install below windows feature on this machine:
         -Application Development
         -Security - Windows Authentication
         -Management Tools - IIS 6 Management Compatibility
             IIS 6 Metabase Compatibility
             IIS 6 WMI Compatibility
             IIS 6 Scripting Tools
             IIS 6 Management Console
         -Microsoft Message Queuing (MSMQ), with Active Directory integration disabled, and MSMQ HTTP support enabled.
     #>
     function AddFeatures($featurename)
     {
         try
         {
             $feature=Get-WindowsFeature | ? {$_.DisplayName -eq $featurename -or $_.Name -eq $featurename}
             Add-WindowsFeature $feature
         }
         catch
         {
             Write-Host "Addition of Windows feature $featurename failed"
             Exit 1
         }
         Write-Host "Addition of Windows feature $featurename succeeded"
     }
    
     $system= gwmi win32_operatingSystem | select name
    
     if (-not (($system -Like '*Microsoft Windows Server 2022*') -or ($system -Like '*Microsoft Windows Server 2019*') -or ($system -Like '*Microsoft Windows Server 2016*')))
     {
         Write-Host("This is not a supported server platform. Installation aborted.")
         Exit
     }
    
     # Start to install Windows feature
     Import-Module ServerManager
    
     AddFeatures('Web-Asp-Net45') #ASP.NET 4.5
     AddFeatures('Web-Mgmt-Console') #IIS Management Console
     AddFeatures('Web-Windows-Auth') # Windows Authentication
     AddFeatures('Web-Metabase') #IIS 6 Metabase Compatibility
     AddFeatures('Web-WMI') #IIS 6 WMI Compatibility
     AddFeatures('Web-Lgcy-Scripting')#IIS 6 Scripting Tools
     AddFeatures('Web-Lgcy-Mgmt-Console') #IIS 6 Management Console
     AddFeatures('MSMQ-HTTP-Support') #MSMQ HTTP Support
     AddFeatures('web-websockets') #IIS Web Sockets
     AddFeatures('NET-WCF-HTTP-Activation45') #http activate
     <!--NeedCopy-->
    
  • InstallPrereqsforSessionRecordingAgent.ps1

     <#
     .Synopsis
         Installs Prereqs for Session Recording Agent
     .Description
         Supports  Windows Server 2022, Windows Server 2019, Windows Server 2016, windows 11, and Windows 10.
         Install below windows feature on this machine:
         -Microsoft Message Queuing (MSMQ), with Active Directory integration disabled, and MSMQ HTTP support enabled.
     #>
     function AddFeatures($featurename)
     {
         try
         {
             $feature=Get-WindowsFeature | ? {$_.DisplayName -eq $featurename -or $_.Name -eq $featurename}
             Add-WindowsFeature $feature
         }
         catch
         {
             Write-Host "Addition of Windows feature $featurename failed"
             Exit 1
         }
         Write-Host "Addition of Windows feature $featurename succeeded"
     }
    
     # Start to install Windows feature
     $system= gwmi win32_operatingSystem | select name
    
     if (-not (($system -Like '*Microsoft Windows Server 2022*') -or ($system -Like '*Microsoft Windows Server 2019*') -or ($system -Like '*Microsoft Windows Server 2016*') -or ($system -Like '*Microsoft Windows 11*') -or ($system -Like '*Microsoft Windows 10*')))
     {
         Write-Host("This is not a supported platform. Installation aborted.")
         Exit
     }
    
     if ($system -Like '*Microsoft Windows Server*')
     {
         Import-Module ServerManager
         AddFeatures('MSMQ') #Message Queuing
         AddFeatures('MSMQ-HTTP-Support')#MSMQ HTTP Support
     }
     else
     {
         try
         {
             dism /online /enable-feature /featurename:MSMQ-HTTP /all
         }
         catch
         {
             Write-Host "Addition of Windows feature MSMQ HTTP Support failed"
             Exit 1
         }
         write-Host "Addition of Windows feature MSMQ HTTP Support succeeded"
     }
     <!--NeedCopy-->
    

To install the Windows roles and features prerequisites, complete the following steps:

  1. On the machine where you plan to install the Session Recording administration components:

    1. Make sure that the execution policy is set to RemoteSigned or Unrestricted in PowerShell.

      Set-ExecutionPolicy RemoteSigned
      <!--NeedCopy-->
      
    2. Start a command prompt as an administrator and run the powershell.exe -file InstallPrereqsforSessionRecordingAdministration.ps1 command.

      The script displays the features that are successfully added and then stops.

    3. After the script runs, make sure that the execution policy is set to a proper value based on your company policy.

  2. On the machine where you plan to install the Session Recording agent component:

    1. Make sure that the execution policy is set to RemoteSigned or Unrestricted in PowerShell.

      Set-ExecutionPolicy RemoteSigned
      <!--NeedCopy-->
      
    2. Start a command prompt as an administrator and run the powershell.exe -file InstallPrereqsforSessionRecordingAgent.ps1 command.

      The script displays the features that are successfully added and then stops.

    3. After the script runs, make sure that the execution policy is set to a proper value based on company policy.

Install the Session Recording administration components

Note:

Starting with 2110, before installing the Session Recording Administration components on Windows Server 2016 where TLS 1.0 is disabled, complete the following steps:

  1. Install Microsoft OLE DB Driver for SQL Server.
  2. Under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 registry key, add the SchUseStrongCrypto DWORD (32-bit) value and set the value data to 1.

  3. Reboot.

We recommend that you install the Session Recording administration, Session Recording agent, and Session Recording player components on separate servers.

The Session Recording administration components include the Session Recording database, Session Recording server, and Session Recording policy console. You can choose the component to install on a server.

Note:

Starting with 2110, before installing the Session Recording administration components on Windows Server 2016 where TLS 1.0 is disabled, complete the following steps:

  1. Install Microsoft OLE DB Driver for SQL Server.
  2. Under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 registry key, add the SchUseStrongCrypto DWORD (32-bit) value and set the value data to 1.

  3. Restart Windows Server 2016.
  1. Install Broker_PowerShellSnapIn_x64.msi.

    Important:

    To use the Session Recording policy console, install the Broker PowerShell Snap-in (Broker_PowerShellSnapIn_x64.msi) manually. Locate the snap-in on the Citrix Virtual Apps and Desktops ISO (\layout\image-full\x64\Citrix Desktop Delivery Controller) and follow the instructions for installation. Failure to comply can cause an error.

  2. Start the Windows command prompt as an administrator, and then run the msiexec /i SessionRecordingAdministrationx64.msi command or double-click the .msi file.

  3. On the installation UI, click Next and accept the license agreement.

  4. On the Session Recording Administration Setup screen, select the Session Recording administration components you want to install.

    Session Recording Administration Setup screen

    Note:

    Installing all Session Recording administration components on a single server is fine for a proof of concept. However, for a large production environment, we recommend that you install the Session Recording policy console on a separate server and the Session Recording server, Session Recording Administrator Logging, and Session Recording database on another separate server. Session Recording Administrator Logging is an optional subfeature of the Session Recording server. Select the Session Recording server before you can select Session Recording Administrator Logging.

Install the Session Recording database

Note:

There are typically three types of deployments for the Session Recording database and Microsoft SQL Server:

  • Deployment 1: Install the Session Recording server and Session Recording database on the same machine and the Microsoft SQL Server on a remote machine. (Recommended)
  • Deployment 2: Install the Session Recording server, Session Recording database, and Microsoft SQL Server on the same machine.
  • Deployment 3: Install the Session Recording server on a machine and install both the Session Recording database and Microsoft SQL Server on another machine. (Not recommended)
  1. On the Database and Server Configuration page, specify the instance name and database name of the Session Recording database and the computer account of the Session Recording server. Click Next.

    • Instance name: If the database instance isn’t a named instance, you can use only the computer name of the SQL Server. If you’ve named the instance, use computer-name\instance-name as the database instance name. To determine the server instance name that you’re using, run select @@servername on the SQL Server. The return value is the exact database instance name. If your SQL server listens on a custom port other than the default port 1433, set the custom listener port by appending a comma to the instance name. For example, type DXSBC-SRD-1,2433 in the Instance name text box, where 2433, following the comma, denotes the custom listener port.

    • Database name: Type a custom database name in the Database name text box or use the default database name preset in the text box. Click Test connection to test the connectivity to the SQL Server instance and the validity of the database name.

      Important:

      A custom database name must consist of only A-Z, a-z, 0–9, and underscores, and can’t exceed 123 characters.

      • You must have the securityadmin and dbcreator server role permissions of the database. If you do not have the permissions, you can:
        • Ask the database administrator to assign the permissions for the installation. After the installation completes, the securityadmin and dbcreator server role permissions are no longer necessary and can be safely removed.
        • Or, during the msi installation, a dialog box prompts for the credentials of a database administrator with the securityadmin and dbcreator server role permissions. Type the correct credentials and then click OK to continue the installation.

        The installation creates the Session Recording database and adds the machine account of the Session Recording server as db_owner.

    • Session Recording Server computer account:

      • Deployments 1 and 2: Type localhost in the Session Recording Server computer account text box.

      • Deployment 3: Type the name of the machine hosting the Session Recording server in the format of domain\computer-name. The Session Recording server computer account is the user account for accessing the Session Recording database.

      Note:

      Attempts to install the Session Recording administration components can fail with error code 1603 when a domain name is set in the Session Recording Server computer account text box. As a workaround, type localhost or NetBIOS domain name\machine name in the Session Recording Server computer account text box. To get the NetBIOS domain name, run $env:userdomain in PowerShell or echo %UserDomain% in a command prompt on the machine where you installed the Session Recording server.

  2. Follow the instructions to complete the installation.

Install the Session Recording server

  1. Select Session Recording Server and Session Recording Administrator Logging.

    Note:

    • The Session Recording Administrator Logging is an optional subfeature of the Session Recording server. Select the Session Recording server before you can select the Session Recording Administrator Logging.
    • We recommend that you install the Session Recording Administrator Logging together with the Session Recording server at the same time. If you don’t want the Administrator Logging feature to be enabled, you can disable it on a later page.
  2. On the Database and Server Configuration page, specify the settings.

    • Instance name: Type the name of your SQL Server in the Instance name text box. If you’re using a named instance, type computer-name\instance-name; otherwise, type computer-name only. If your SQL server listens on a custom port other than the default port 1433, set the custom listener port by appending a comma to the instance name. For example, type DXSBC-SRD-1,2433 in the Instance name text box, where 2433, following the comma, denotes the custom listener port.
    • Database name: Type a custom database name in the Database name text box or use the default database name CitrixSessionRecording that is preset in the text box. You must have the securityadmin and dbcreator server role permissions of the database. If you do not have the permissions, you can:
      • Ask the database administrator to assign the permissions for the installation. After the installation completes, the securityadmin and dbcreator server role permissions are no longer necessary and can be safely removed.
      • Or, during the msi installation, a dialog box prompts for the credentials of a database administrator with the securityadmin and dbcreator server role permissions. Type the correct credentials and then click OK to continue the installation.
    • After typing the correct instance name and database name, click Test connection to test the connectivity to the Session Recording database.

    • Type the Session Recording server computer account, and then click Next.
  3. On the Administration Logging Configuration page, specify configurations for the Administration Logging feature.

    • Logging database is installed on the SQL Server instance: This text box isn’t editable. The SQL Server instance name of the Administration Logging database is automatically grabbed from the instance name that you typed on the Database and Server Configuration page.
    • Logging database name: Type a custom database name for the Administrator Logging database in this text box or use the default database name CitrixSessionRecordingLogging that is preset in the text box.

      Note:

      The Administrator Logging database name must be different from the Session Recording database name that is set in the Database name text box on the previous Database and Server Configuration page.

    • Use default database name: Selecting this option uses the default logging database name.
    • Enable Logging service: By default, the Administration Logging feature is enabled. You can disable it by clearing the check box.
    • Enable mandatory blocking: By default, mandatory blocking is enabled. The normal features might be blocked if logging fails. You can disable mandatory blocking by clearing the check box.
  4. Click Next and complete the installation.

Note:

The Session Recording server default installation uses HTTPS/TLS to secure communications. If TLS isn’t configured in the default Internet Information Services (IIS) site of the Session Recording server, use HTTP. To do so, cancel the selection of SSL in the IIS management console. Navigate to the Session Recording Broker site, open the SSL settings, and clear the Require SSL check box.

Install the Session Recording agent

Install the Session Recording agent on the VDA or VDI machine on which you want to record sessions.

  1. On the Session Recording Agent Configuration page: If you’ve installed the Session Recording server in advance, type the computer name of the machine where you installed the Session Recording server. Type the protocol and port information for the connection to the Session Recording server. If you haven’t installed Session Recording yet, you can change such information later in Session Recording Agent Properties.
  2. Follow the instructions to complete the installation.

Note:

When Machine Creation Services (MCS) or Citrix Provisioning Services (PVS) creates VDAs with the Microsoft Message Queuing (MSMQ) installed, those VDAs can have the same QMId under certain conditions. This case might cause various issues, for example:

  • Sessions might not be recorded even if the recording agreement is accepted.
  • The Session Recording server might not receive session logoff signals and as a result, sessions might always be in Live status.

As a workaround, create a unique QMId for each VDA and it differs depending on the deployment methods.

No extra actions are required for single-session OS VDAs that are created using PVS 7.7 or later and MCS 7.9 or later in the static desktop mode.

For multi-session OS VDAs created using MCS or PVS and single-session OS VDAs configured to discard all changes when a user logs off, use the GenRandomQMID.ps1 script to change the QMId on system startup. Change the power management strategy to make sure enough VDAs are running before user logon.

To use the GenRandomQMID.ps1 script, do the following:

1. Make sure that the execution policy is set to RemoteSigned or Unrestricted in PowerShell.

Set-ExecutionPolicy RemoteSigned

2. Create a scheduled task, set the trigger as on system startup, and run with the SYSTEM account on the PVS or MCS master image machine.

3. Add the command as a startup task.

powershell .exe -file C:\\GenRandomQMID.ps1

Summary of the GenRandomQMID.ps1 script:

  1. Remove the current QMId from the registry.
  2. Add SysPrep = 1 to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSMQ\Parameters.
  3. Stop related services, including CitrixSmAudAgent and MSMQ.
  4. To generate a random QMId, start the services that stopped previously.

Example GENRANDOMQMID.PS1:

# Remove old QMId from registry and set SysPrep flag for MSMQ

Remove-Itemproperty -Path >HKLM:Software\Microsoft\MSMQ\Parameters\MachineCache -Name QMId -Force

Set-ItemProperty -Path HKLM:Software\Microsoft\MSMQ\Parameters -Name >"SysPrep" -Type DWord -Value 1

# Get dependent services

$depServices = Get-Service -name MSMQ -dependentservices | Select -Property Name

# Restart MSMQ to get a new QMId

Restart-Service -force MSMQ

# Start dependent services

if ($depServices -ne $null) {

    foreach ($depService in $depServices) {

        $startMode = Get-WmiObject win32_service -filter "NAME = '$($depService.Name)'" | Select -Property StartMode

        if ($startMode.StartMode -eq "Auto") {

            Start-Service $depService.Name
        }
}

}
<!--NeedCopy-->

Install the Session Recording player and the web player

Install the Session Recording player on the Session Recording server or on workstations in the domain. Install the web player on the Session Recording server only.

Double-click SessionRecordingPlayer.msi and SessionRecordingWebPlayer.msi and follow the instructions to complete the installation.

Automate installation

Session Recording supports silent installation with options. Write a script that uses silent installation and run the relevant commands.

Automate installation of the Session Recording administration components

Install the complete set of the Session Recording administration components by using a single command

For example, either of the following commands installs the complete set of the Session Recording administration components and creates a log file to capture the installation information.

msiexec /i "c:\SessionRecordingAdministrationx64.msi" ADDLOCAL="SsRecServer,PolicyConsole,SsRecLogging,StorageDatabase" DATABASEINSTANCE="WNBIO-SRD-1" DATABASENAME="CitrixSessionRecording" LOGGINGDATABASENAME="CitrixSessionRecordingLogging" DATABASEUSER="localhost" /q /l*vx "yourinstallationlog"
<!--NeedCopy-->
msiexec /i "SessionRecordingAdministrationx64.msi" ADDLOCAL="SsRecServer,PolicyConsole,SsRecLogging,StorageDatabase" DATABASEINSTANCE="CloudSQL" DATABASENAME="CitrixSessionRecording" LOGGINGDATABASENAME="CitrixSessionRecordingLogging" AZURESQLSERVICESUPPORT="1" AZUREUSERNAME="CloudSQLAdminName" AZUREPASSWORD="CloudSQLAdminPassword" /q /l*vx "c:\WithLogging.log"
<!--NeedCopy-->

Note:

The SessionRecordingAdministrationx64.msi file is located on the Citrix Virtual Apps and Desktops ISO under \layout\image-full\x64\Session Recording.

Where:

  • ADDLOCAL provides the features for you to select. You can select more than one option. SsRecServer is the Session Recording server. PolicyConsole is the Session Recording policy console. SsRecLogging is the Administrator Logging feature. StorageDatabase is the Session Recording database. Session Recording Administrator Logging is an optional subfeature of the Session Recording server. Select the Session Recording server before you can select Session Recording Administrator Logging.
  • DATABASEINSTANCE is the instance name of the Session Recording database. For example,.\SQLEXPRESS,computer-name\SQLEXPRESS,computer-name or tcp:srt-sql-support.public.ca7b16b60789.database.windows.net,3342 if you’re using Azure SQL Managed Instance.
  • DATABASENAME is the database name of the Session Recording database.
  • LOGGINGDATABASENAME is the name of the Administrator Logging database.
  • AZURESQLSERVICESUPPORT determines whether cloud SQL is supported. To use cloud SQL, set it to 1.
  • DATABASEUSER is the computer account of the Session Recording server.
  • AZUREUSERNAME is the cloud SQL admin name.
  • AZUREPASSWORD is the cloud SQL admin password.
  • /q specifies quiet mode.
  • /l*v specifies verbose logging.
  • yourinstallationlog is the location of your installation log file.

Create a master image for deploying the Session Recording server

You might already have the Session Recording database and the Administration Logging database in place from an existing deployment. For such scenarios, you can now forego database checks when you’re installing the Session Recording administration components using SessionRecordingAdministrationx64.msi. You can create a master image for deploying the Session Recording server easily on many other machines. After deploying the Server on target machines using the master image, run a command on each machine to connect to the existing Session Recording database and Administration Logging database. This master image support eases deployment and minimizes the potential impact of human error. It applies only to fresh installations and consists of the following steps:

  1. Start a command prompt and run a command similar to the following:

    msiexec /i "SessionRecordingAdministrationx64.msi" ADDLOCAL="SsRecServer,PolicyConsole,SsRecLogging,StorageDatabase" DATABASEINSTANCE="sqlnotexists" DATABASENAME="CitrixSessionRecording2" LOGGINGDATABASENAME="CitrixSessionRecordingLogging2" DATABASEUSER="localhost" /q /l*vx "c:\WithLogging.log" IGNOREDBCHECK="True"
    <!--NeedCopy-->
    

    This command installs the Session Recording administration components without configuring and testing connectivity to the Session Recording database and the Administration Logging database.

    Set the IGNOREDBCHECK parameter to True and use random values for DATABASEINSTANCE, DATABASENAME, and LOGGINGDATABASENAME.

  2. Create a master image on the machine you’re operating.

  3. Deploy the master image to other machines for deploying the Session Recording server.

  4. On each of the machines, run commands similar to the following:

    .\SsRecUtils.exe -modifydbconnectionpara DATABASEINSTANCE DATABASENAME LOGGINGDATABASENAME
    
    iisreset /noforce
    <!--NeedCopy-->
    

    The commands connect the Session Recording server installed earlier to an existing Session Recording database and Administration Logging database.

    The SsRecUtils.exe file is stored in \Citrix\SessionRecording\Server\bin\. Set the DATABASEINSTANCE, DATABASENAME, and LOGGINGDATABASENAME parameters as needed.

Keep databases when uninstalling the Session Recording administration components

With KEEPDB set to True, the following command keeps the Session Recording database and the Administration Logging database when uninstalling the Session Recording administration components:

msiexec /x "SessionRecordingAdministrationx64.msi" KEEPDB="True"
<!--NeedCopy-->

Automate installation of the Session Recording player and web player

For example, the following commands install the Session Recording player and web player, respectively.

msiexec /i "c:\SessionRecordingPlayer.msi" /q /l*\vx "yourinstallationlog"
<!--NeedCopy-->
msiexec /i "c:\SessionRecordingWebPlayer.msi" /q /l*vx "yourinstallationlog"
<!--NeedCopy-->

Note:

The SessionRecordingPlayer.msi file is located on the Citrix Virtual Apps and Desktops ISO under \layout\image-full\x86\Session Recording.

The SessionRecordingWebPlayer.msi file is located on the Citrix Virtual Apps and Desktops ISO under \layout\image-full\x64\Session Recording.

Where:

  • /q specifies quiet mode.
  • /l*v specifies verbose logging.
  • yourinstallationlog is the location of your installation log file.

Automate installation of the Session Recording agent

For example, the following command installs the Session Recording agent and creates a log file to capture the installation information.

msiexec /i SessionRecordingAgentx64.msi /q /l*vx yourinstallationlog SESSIONRECORDINGSERVERNAME=yourservername
SESSIONRECORDINGBROKERPROTOCOL=yourbrokerprotocol SESSIONRECORDINGBROKERPORT=yourbrokerport
<!--NeedCopy-->

Note:

The SessionRecordingAgentx64.msi file is located on the Citrix Virtual Apps and Desktops ISO under \layout\image-full\x64\Session Recording.

Where:

  • yourservername is the NetBIOS name or FQDN of the machine hosting the Session Recording server. If not specified, this value defaults to localhost.
  • yourbrokerprotocol is HTTP or HTTPS that the Session Recording agent uses to communicate with the Session Recording Broker. If not specified, this value defaults to HTTPS.
  • yourbrokerport is the port number that the Session Recording agent uses to communicate with the Session Recording Broker. If not specified, this value defaults to zero, which directs the Session Recording agent to use the default port number for your selected protocol: 80 for HTTP or 443 for HTTPS.
  • /q specifies quiet mode.
  • /l*v specifies verbose logging.
  • yourinstallationlog is the location of your installation log file.

Upgrade Session Recording

You can upgrade certain deployments to later versions without having to first set up new machines or sites. You can upgrade from the latest CU of Session Recording 7.15 LTSR, and from any later version, to the latest version of Session Recording.

Note:

When you upgrade Session Recording administration from 7.6 to 7.13 or later and choose Modify to add the Administrator Logging service, the SQL Server instance name does not appear on the Administrator Logging Configuration page. The following error message appears when you click Next: Database connection test failed. Please enter correct Database instance name. As a workaround, add the read permission for localhost users to the following SmartAuditor Server registry folder: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SmartAuditor\Server.

You can’t upgrade from a Technical Preview version.

Requirements, preparation, and limitations

  • Use the Session Recording installer’s graphical interface or command line to upgrade the Session Recording components.
  • Before any upgrade activity, back up the database named CitrixSessionRecording in the SQL Server instance. In this way, you can restore it if any issues are identified after the database upgrade.
  • In addition to being a domain user, you must be a local administrator on the machines where you’re upgrading the Session Recording components.
  • If the Session Recording server and Session Recording database aren’t installed on the same server, you must have the database role permission to upgrade the Session Recording database. Otherwise, you can:
    • Ask the database administrator to assign the securityadmin and dbcreator server role permissions for the upgrade. After the upgrade completes, the securityadmin and dbcreator server role permissions are no longer necessary and can be safely removed.
    • Or, use the SessionRecordingAdministrationx64.msi file to upgrade. During the msi upgrade, a dialog box prompts for the credentials of a database administrator who has the securityadmin and dbcreator server role permissions. Type the correct credentials and then click OK to continue the upgrade.
  • Session Recording agent 7.6.0 and later are compatible with the latest version of Session Recording server. However, some new features and bug fixes might not take effect.
  • Any sessions started during the upgrade of a Session Recording server aren’t recorded.
  • The Graphics Adjustment option in Session Recording Agent Properties is enabled by default after a fresh installation or upgrade to keep compatible with the Desktop Composition Redirection mode. You can disable this option manually after a fresh installation or upgrade.
  • The Administrator Logging feature isn’t installed after you upgrade Session Recording from a previous version where the feature is unavailable. To add the feature, modify the installation after the upgrade.
  • If there are live recording sessions when the upgrade process starts, there’s little chance that the recording can be complete.
  • Review the following upgrade sequence, so that you can plan and mitigate potential outages.

Upgrade sequence

  1. When the Session Recording database and Session Recording server are installed on different servers, stop the Session Recording Storage Manager service manually on the Session Recording server. Then upgrade the Session Recording database first.
  2. Through the Internet Information Services (IIS) Manager, make sure that the Session Recording Broker is running. Upgrade the Session Recording server. If the Session Recording database and Session Recording server are installed on the same server, the Session Recording Database is also upgraded.
  3. The Session Recording service is back online automatically when the upgrade of the Session Recording server is completed.
  4. Upgrade the Session Recording agent (on the master image).
  5. Upgrade the Session Recording policy console with or after the Session Recording server.
  6. Upgrade the Session Recording player.

Deploy the Session Recording database on cloud SQL database services

This section describes how to deploy the Session Recording database on Azure SQL Managed Instance, on AWS RDS, and on SQL Server on Azure VMs.

Deploy the Session Recording database on Azure SQL Managed Instance or on AWS RDS

Tip:

You can also run a single command similar to the following to deploy the Session Recording database on Azure SQL Managed Instance or on AWS RDS. For more information, see the preceding Automate installation section in this article.

msiexec /i "SessionRecordingAdministrationx64.msi" ADDLOCAL="SsRecServer,PolicyConsole,SsRecLogging,StorageDatabase" DATABASEINSTANCE="CloudSQL" DATABASENAME="CitrixSessionRecording" LOGGINGDATABASENAME="CitrixSessionRecordingLogging" AZURESQLSERVICESUPPORT="1" AZUREUSERNAME="CloudSQLAdminName" AZUREPASSWORD="CloudSQLAdminPassword" /q /l*vx "c:\WithLogging.log"
<!--NeedCopy-->
  1. Create an Azure SQL Managed instance or create a SQL Server instance through the Amazon RDS console.

  2. (For Azure SQL only) Keep a record of the Server strings that appear in the properties panel. The strings are the instance name of the Session Recording database. For an example, see the following screen capture.

    Example Server strings

  3. (For AWS RDS only) Keep a record of the Endpoint and Port information. We use it as the instance name of your database, in the format of <Endpoint, Port>.

    AWS RDS instance composition

  4. Run SessionRecordingAdministrationx64.msi to install the Session Recording database.

    Select the Enable cloud SQL check box and fill in the cloud SQL admin name and password. Make other required configurations.

    Fill in the cloud SQL admin credentials

    Note:

    If you change the cloud SQL admin password, you must update the password in Session Recording Server Properties. When you open Session Recording Server Properties, an error message appears. Click OK to continue, select the Cloud DB tab, and type the new cloud SQL admin password. Restart the Citrix Session Recording Analytics service, the Citrix Session Recording Storage Manager service, and the IIS service.

    Azure AD authentication isn’t supported.

    Update the cloud SQL admin password

Migrate an on-premises database to cloud SQL Managed Instance

  1. Migrate your on-premises database according to https://docs.microsoft.com/en-us/data-migration/ or https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/migrate-an-on-premises-microsoft-sql-server-database-to-amazon-rds-for-sql-server.html.

  2. To make Session Recording work properly after the migration, run SsRecUtils.exe on the Session Recording server.

    C:\Program Files\Citrix\SessionRecording\Server\bin\SsRecUtils.exe -modifyazuredbconnectionpara {Database Instance} {Session Recording Database Name} {Session Recording Logging Database Name} {AzureAdminName}{AzureAdminPassword} iisreset /noforce

  3. On the Session Recording server, restart the Citrix Session Recording Analytics service, the Citrix Session Recording Storage Manager service, and the IIS service.

Migrate a production database from Azure SQL Managed Instance to an on-premises database

  1. Migrate the database according to https://docs.microsoft.com/en-us/data-migration/.

  2. To make Session Recording work properly after the migration, run SsRecUtils.exe on the Session Recording server.

    C:\Program Files\Citrix\SessionRecording\Server\bin\SsRecUtils.exe -modifydbconnectionpara {Database Instance} {Session Recording Database Name} {Session Recording Logging Database Name} iisreset /noforce

  3. On the Session Recording server, restart the Citrix Session Recording Analytics service, the Citrix Session Recording Storage Manager service, and the IIS service.

Deploy the Session Recording database on SQL Server on Azure VMs

On SQL Server on Azure VMs, you can deploy the Session Recording database.

  1. Check out an Azure SQL VM.
  2. Configure the VM and add it to the domain where you install the Session Recording components.
  3. Use the VM’s FQDN as the instance name during the installation of the Session Recording database. Note: When you’re using SessionRecordingAdministrationx64.msi for the installation, clear the Enable cloud SQL check box.
  4. Follow instructions to complete the installation.

Uninstall Session Recording

To remove the Session Recording components from a server or workstation, use the uninstall or remove programs option available from the Windows Control Panel. To remove the Session Recording database, you must have the same securityadmin and dbcreator SQL Server role permissions as when you installed it.

For security reasons, the Administrator Logging Database isn’t removed after the components are uninstalled.

Integrate with Citrix Analytics for Security

You can configure Session Recording servers to send user events to Citrix Analytics for Security, which processes the user events to provide actionable insights into user behaviors.

Prerequisites

Before you begin, meet the following prerequisites:

  • The Session Recording server can connect to the following addresses:

  • The Session Recording deployment has port 443 open for outbound internet connections. Any proxy servers on the network must allow this communication with Citrix Analytics for Security.

  • If you’re using Citrix Virtual Apps and Desktops 7 1912 LTSR, the supported Session Recording version is 2103 or later.

Connect your Session Recording server to Citrix Analytics for Security

  1. Sign in to Citrix Cloud.

  2. Find Citrix Analytics for Security and click Manage.

  3. From the top bar, click Settings > Data Sources.

  4. On the Virtual Apps and Desktops- Session Recording site card, click Connect Session Recording server.

    Session recording connection

  5. On the Connect Session Recording Server page, review the checklist, and select all the mandatory requirements. If you do not select a mandatory requirement, the Download File option is disabled.

    Session Recording checklist

  6. If you have proxy servers in your network, enter the proxy address in the SsRecStorageManager.exe.config file in your Session Recording server.

    The configuration file is located at <Session Recording server installation path>\bin\SsRecStorageManager.exe.config

    For example: C:\Program Files\Citrix\SessionRecording\Server\Bin\SsRecStorageManager.exe.config

    Config file path

  7. Click Download File to download the SessionRecordingConfigurationFile.json file.

    Note:

    The file contains sensitive information. Keep the file in a safe and secure location.

  8. Copy the file to the Session Recording server that you want to connect to Citrix Analytics for Security.

    If there’re more than one Session Recording server in your deployment, you must copy the file to each server that you want to connect and follow the steps to configure each server.

  9. On the Session Recording server, run the following command to import the settings:

    <Session Recording server installation path>\bin\SsRecUtils.exe -Import_SRCasConfigurations <configuration file path>
    <!--NeedCopy-->
    

    For example:

    C:\Program Files\Citrix\SessionRecording\Server\bin\ SsRecUtils.exe -Import_SRCasConfigurations C:\Users\administrator \Downloads\SessionRecordingConfigurationFile.json
    <!--NeedCopy-->
    
  10. Restart the following services:

    • Citrix Session Recording Analytics Service

    • Citrix Session Recording Storage Manager

  11. After configuration is successful, go to Citrix Analytics for Security to view the connected Session Recording server. Click Turn On Data Processing to allow Citrix Analytics for Security to process the data.

    Note:

    If you’re using Session Recording server version 2103 or 2104, you must first launch a Virtual Apps and Desktops session to view the connected Session Recording server on Citrix Analytics for Security. Otherwise the connected Session Recording server fails to get displayed. This requirement isn’t applicable for Session Recording server version 2106 and later.

View the connected deployments

The server deployments appear on the Session Recording site card only if the configuration is successful. The site card shows the number of configured servers that have established connections with Citrix Analytics for Security.

If you don’t see your Session Recording servers even after the configuration was successful, refer to the troubleshooting section at Configured Session Recording server fails to connect.

Session Recording deployment

On the site card, click the number of deployments to view the connected server groups with Citrix Analytics for Security. For example, click 1 Session Recording Deployment to view the connected server or server groups. Each Session Recording server is represented by a base URL and a ServerGroupID.

SR deployment details

View received events

The site card displays the connected Session Recording deployments and the events received from these deployments for the last one hour, which is the default time selection. You can also select 1 week (1 W) and view the data. Click the number of received events to view the events on the self-service search page.

After you have enabled data processing, the site card might display the No data received status. This status appears for two reasons:

  1. If you’ve turned on data processing for the first time, the events take some time to reach the event hub in Citrix Analytics. When Citrix Analytics receives the events, the status changes to Data processing on. If the status does not change after some time, refresh the Data Sources page.

  2. Citrix Analytics hasn’t received any events from the data source in the last one hour.

Add Session Recording servers

To add a Session Recording server, do one of the following:

  • On the Connected Session Recording Deployments page, click Connect to Session recording server.

    Connect deployment

  • On the Virtual Apps and Desktops- Session Recording site card, click the vertical ellipsis (⋮) and then select Connect Session Recording server.

    Session recording connection

Follow the steps to download the configuration file and configure a Session Recording server.

Remove Session Recording servers

To remove a Session Recording server:

  1. On Citrix Analytics for Security, go to the Connected Session Recording Deployments page and select the server deployment that you want to remove.

  2. Click the vertical ellipses (⋮) and select Remove Session Recording server from Analytics.

    Remove session recording server

  3. On the Session Recording server that you’ve removed from Citrix Analytics, run the following command:

    <Session Recording server installation path>\bin\SsRecUtils.exe -Remove_SRCasConfigurations
    <!--NeedCopy-->
    

    For example:

    C:\Program Files\Citrix\SessionRecording\Server\bin\ SsRecUtils.exe -Remove_SRCasConfigurations
    <!--NeedCopy-->
    

Turn on or off data processing on the data source

You can stop the data processing at any time for a particular data source- Director and Workspace app. On the data source site card, click the vertical ellipsis (⋮) and then select Turn off data processing. Citrix Analytics stops processing data for that data source. You can also stop the data processing from the Virtual Apps and Desktops site card. This option applies to both data sources- Director and Workspace app. To enable data processing again, click Turn On Data Processing.

Configured Session Recording server fails to connect

Your Session Recording server fails to connect to Citrix Analytics after configuration. As a result, you don’t see the configured server on the Session Recording site card.

To troubleshoot this issue, do the following:

  1. On your configured Session Recording server, run the following PowerShell command to check the Client Machine Identification (CMID):

    Get-WmiObject -class SoftwareLicensingService | select Clientmachineid
    <!--NeedCopy-->
    
  2. If CMID is empty, add the following registry files in the specified paths:

    Registry name Registry path Key type Value
    AuditorUniqueID Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SmartAuditor\Server\ String Enter your UUID.
    EnableCASUseAuditorUniqueID Computer/HKEY_LOCAL_MACHINE/SOFTWARE/Citrix/SmartAuditor/Server/ REG_DWORD 1
  3. Restart the following services:

    • Citrix Session Recording Analytics Service

    • Citrix Session Recording Storage Manager