Install, upgrade, and uninstall Session Recording

This chapter details how to install Session Recording by using the XenApp/XenDesktop installer. It contains the following sections:

Installation checklist

Install the Session Recording Administration components

Configure Director to use the Session Recording Server

Install the Session Recording Agent

Install the Session Recording Player

Automate installations

Upgrade Session Recording

Uninstall Session Recording

Installation checklist

As of version 7.14, you can install the Session Recording components by using the XenApp/XenDesktop installer.

Before you start the installation, complete this list:

Note:

• Citrix recommends that you divide the published applications into separate Delivery Groups based on your recording policies because session sharing for published applications can conflict with active policies if they are in the same Delivery Group. Session Recording matches the active policy with the first published application that a user opens.
• If you are planning to use Machine Creation Services (MCS) or Provisioning Services, prepare a unique QMId. Failure to comply can cause recording data losses.
• SQL Server requires that TCP/IP is enabled, the SQL Server Browser service is running, and Windows Authentication is used.
• To use HTTPS, configure server certificates for TLS/HTTPS.
• Ensure that users under Local Users and Groups > Groups > Users have write permission to the C:\windows\Temp folder.

Install the Session Recording Administration components

Citrix recommends 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 which of these components to install on a server.

Step 1: Download the product software and launch the wizard

1. If you have not downloaded the XenApp and XenDesktop ISO yet, use your Citrix account credentials to access the XenApp and XenDesktop download page and download the product ISO file. Unzip the ISO file or burn a DVD of it.
2. Use a local administrator account to log on to the machine where you are installing the Session Recording Administration components. Insert the DVD in the drive or mount the ISO file. If the installer does not launch automatically, double-click the AutoSelect application or the mounted drive.
   The installation wizard launches.

Step 2: Choose which product to install

Click Start next to the product to install: XenApp or XenDesktop.

Step 3: Select Session Recording

Select the Session Recording entry.

Step 4: Read and accept the license agreement

On the Software License Agreement page, read the license agreement, accept it, and then click Next.

Step 5: Select the components to install and the installation location

On the Core Components page:

• Location: By default, components are installed in C:\Program Files\Citrix. The default location works for most deployments. You can specify a custom installation location.
• Component: By default, all the check boxes next to the components that can be installed are selected. The installer knows whether it is running on a Desktop OS or a Server OS. It allows the Session Recording Administration components to be installed on a Server OS only, and it does not allow the Session Recording Agent to be installed on a machine that has no VDA installed in advance. If you install the Session Recording Agent on a machine that has no VDA installed in advance, The Session Recording Agent option is unavailable.

Select Session Recording Administration and click Next.

Step 6: Select the features to install

On the Features page:

• By default, all the check boxes next to the features that can be installed are selected. Installing all these features on a single server is fine for a proof of concept. However, for a large production environment, Citrix recommends 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. Note that the Session Recording Administrator Logging is an optional subfeature of the Session Recording Server. You must select the Session Recording Server before you can select the Session Recording Administrator Logging.
• To add another feature on the same server after you select and install a feature or features on it, you can only run the msi package but cannot run the installer again.

Select the feature or features you want to install and click Next.

Step 6.1: Install the Session Recording Database

Note: Session Recording Database is not an actual database. It is a component responsible for creating and configuring the required databases in the Microsoft SQL Server instance during installation. Session Recording supports three solutions for database high availability based on Microsoft SQL Server. For more information, see Install Session Recording with database high availability.

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 Features page, select Session Recording Database and click Next.

   

2. 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.

   

   On the Database and Server Configuration page:

   • Instance name: If the database instance is not a named instance as you configured when you set up the instance, you can use only the computer name of the SQL Server. If you have named the instance, use computer-name\instance-name as the database instance name. To determine the server instance name you are using, run select @@servername on the SQL Server. The return value is the exact database instance name. If your SQL server is configured to be listening 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 contain only A-Z, a-z, and 0-9, and cannot 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, use the SessionRecordingAdministrationx64.msi package (unzip the ISO file, and you can find this msi package under …\x64\Session Recording). During the msi installation, a dialog box prompts for the credentials of a database administrator with the securityadmin and dbcreator server role permissions. Enter the correct credentials and then click OK to continue the installation.

       The installation creates the new 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 field.
     • Deployment 3: Type the name of the computer 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 field. As a workaround, type localhost or NetBIOS domain name\machine name in the Session Recording Server computer account field.

3. Review the prerequisites and confirm the installation.

   

   The Summary page shows your installation choices. You can click Back to return to the earlier wizard pages and make changes. Or, click Install to start the installation.

4. Complete the installation.

   

   The Finish Installation page shows green check marks for all the prerequisites and components that have been installed and initialized successfully.

   Click Finish to complete the installation of the Session Recording Database.

Step 6.2: Install the Session Recording Server

1. On the Features page, select Session Recording Server and Session Recording Administrator Logging. Click Next.

   

   Note:

   • The Session Recording Administrator Logging is an optional subfeature of the Session Recording Server. You must select the Session Recording Server before you can select the Session Recording Administrator Logging.
   • Citrix recommends 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. However, if you choose not to install this feature at the beginning but want to add it later, you can only manually add it by using the SessionRecordingAdministrationx64.msi package.

2. On the Database and Server Configuration page, specify the configurations.

   

   On the Database and Server Configuration page:

   • Instance name: Type the name of your SQL Server in the Instance name text box. If you are using a named instance, type computer-name\instance-name; otherwise, type computer-name only. If your SQL server is configured to be listening 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, use the SessionRecordingAdministrationx64.msi package to install the Session Recording Server. During the msi installation, a dialog box prompts for the credentials of a database administrator with the securityadmin and dbcreator server role permissions. Enter 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.
   • Enter the Session Recording Server computer account, and then click Next.

3. On the Administration Logging Configuration page, specify configurations for the Administration Logging feature.

   

   On the Administration Logging Configuration page:

   • The Administration Logging database is installed on the SQL Server instance: This text box is not 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.
   • Administrator Logging database name: If you choose to install the Session Recording Administrator Logging feature, 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.
   • After typing the Administrator Logging database name, click Test connection to test the connectivity to the Administrator Logging database.
   • Enable Administration Logging: 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.

   Click Next to continue the installation.

4. Review the prerequisites and confirm the installation.

   

   The Summary page shows your installation choices. You can click Back to return to the earlier wizard pages and make changes. Or, click Install to start the installation.

5. Complete the installation.

   

   The Finish Installation page shows green check marks for all the prerequisites and components that have been installed and initialized successfully.

   Click Finish to complete the installation of the Session Recording Server.

   Note: The Session Recording Server default installation uses HTTPS/TLS to secure communications. If TLS is not configured in the default IIS site of the Session Recording Server, use HTTP. To do so, cancel the selection of SSL in the IIS Management Console by navigating to the Session Recording Broker site, opening the SSL settings, and clearing the Require SSL check box.

Step 6.3: Install the Session Recording Policy Console

1. On the Features page, select Session Recording Policy Console and click Next.

   

2. Review the prerequisites and confirm the installation.

   

   The Summary page shows your installation choices. You can click Back to return to the earlier wizard pages and make changes. Or, click Install to start the installation.

3. Complete the installation.

   

   The Finish Installation page shows green check marks for all the prerequisites and component that have been installed and initialized successfully.

   Click Finish to complete your installation of the Session Recording Policy Console.

Step 7: Install Broker_PowerShellSnapIn_x64.msi

Important: To use the Session Recording Policy Console, you must have the Broker PowerShell Snap-in (Broker_PowerShellSnapIn_x64.msi) installed. The snap-in cannot be automatically installed by the installer. Locate the snap-in on the XenApp/XenDesktop ISO (\layout\image-full\x64\Citrix Desktop Delivery Controller) and follow the instructions for installing it manually. Failure to comply can cause an error.

Configure Director to use the Session Recording Server

You can use the Director console to create and activate the Session Recording policies.

1. For an HTTPS connection, install the certificate to trust the Session Recording Server in the Trusted Root Certificates of the Director server.
2. To configure the Director server to use the Session Recording Server, run the C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /configsessionrecording command.
3. Enter the IP address or FQDN of the Session Recording Server and the port number and connection type (HTTP/HTTPS) that the Session Recording Agent uses to connect to the Session Recording Broker on the Director server.

Install the Session Recording Agent

You must install the Session Recording Agent on the VDA or VDI machine on which you want to record sessions.

Step 1: Download the product software and launch the wizard

Use a local administrator account to log on to the machine where you are installing the Session Recording Agent component. Insert the DVD in the drive or mount the ISO file. If the installer does not launch automatically, double-click the AutoSelect application or the mounted drive.

The installation wizard launches.

Step 2: Choose which product to install

Click Start next to the product to install: XenApp or XenDesktop.

Step 3: Select Session Recording

Select the Session Recording entry.

Step 4: Read and accept the license agreement

On the Software License Agreement page, read the license agreement, accept it, and then click Next

Step 5: Select the component to install and the installation location

Select Session Recording Agent and click Next.

Step 6: Specify the Agent configuration

On the Agent Configuration page:

• If you have installed the Session Recording Server in advance, enter the name of the computer where you installed the Session Recording Server and the protocol and port information for the connection to the Session Recording Server. If you have not installed Session Recording yet, you can modify such information later in Session Recording Agent Properties.

Note: There is a limitation with the test connection function of the installer. It does not support the “HTTPS requires TLS 1.2” scenario. If you use the installer in this scenario, test connection fails but you can ignore the failure and click Next to continue the installation. It does not affect normal functioning.

Step 7: Review the prerequisites and confirm the installation

The Summary page shows your installation choices. You can click Back to return to the earlier wizard pages and make changes. Or, click Install to start the installation.

Step 8: Complete the installation

The Finish Installation page shows green check marks for all the prerequisites and components that have been installed and initialized successfully.

Click Finish to complete the installation of the Session Recording Agent.

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

• Sessions might not be recorded even if the recording agreement is accepted.
• The Session Recording Server might not be able to receive session logoff signals and consequently, 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 if Desktop OS VDAs with the Session Recording agent installed are created with PVS 7.7 or later and MCS 7.9 or later in the static desktop mode that is, for example, configured to make all changes persistent with a separate Personal vDisk or the local disk of your VDA.

For Server OS VDAs created with MCS or PVS and Desktop OS VDAs that are configured to discard all changes when a user logs off, use the GenRandomQMID.ps1 script to modify the QMId on system startup. Modify the power management strategy to ensure that enough VDAs are running before user logon attempts.

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.

# 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
        }

}
}

Install the Session Recording Player

Install the Session Recording Player on the Session Recording Server or one or more workstations in the domain for users who view session recordings.

Step 1: Download the product software and launch the wizard

Use a local administrator account to log on to the machine where you are installing the Session Recording Player component. Insert the DVD in the drive or mount the ISO file. If the installer does not launch automatically, double-click the AutoSelect application or the mounted drive.

The installation wizard launches.

Step 2: Choose which product to install

Click Start next to the product to install: XenApp or XenDesktop.

Step 3: Select Session Recording

Select the Session Recording entry.

Step 4: Read and accept the license agreement

On the Software License Agreement page, read the license agreement, accept it, and then click Next.

Step 5: Select the component to install and the installation location

Select Session Recording Player and click Next.

Step 6: Review the prerequisites and confirm the installation

The Summary page shows your installation choices. You can click Back to return to the earlier wizard pages and make changes. Or, click Install to start the installation.

Step 7: Complete the installation

The Finish Installation page shows green check marks for all the prerequisites and components that have been installed and initialized successfully.

Click Finish to complete the installation of the Session Recording Player.

Automate installations

To install the Session Recording Agent on multiple servers, write a script that uses silent installation.

The following command line installs the Session Recording Agent and creates a log file to capture the installation information.

For 64-bit systems:

msiexec /i SessionRecordingAgentx64.msi /q /l*vx yourinstallationlog SESSIONRECORDINGSERVERNAME=yourservername SESSIONRECORDINGBROKERPROTOCOL=yourbrokerprotocol SESSIONRECORDINGBROKERPORT=yourbrokerport

Note: The SessionRecordingAgentx64.msi file in the XenApp/XenDesktop ISO is under \layout\image-full\x64\Session Recording.

For 32-bit systems:

msiexec /i SessionRecordingAgent.msi /q /l*vx yourinstallationlog SESSIONRECORDINGSERVERNAME=yourservername SESSIONRECORDINGBROKERPROTOCOL=yourbrokerprotocol SESSIONRECORDINGBROKERPORT=yourbrokerport

Note: The SessionRecordingAgent.msi file in the XenApp/XenDesktop ISO is under \layout\image-full\x86\Session Recording.

where:

yourservername is the NetBIOS name or FQDN of the computer hosting the Session Recording Server. If not specified, this value defaults to localhost.

yourbrokerprotocol is HTTP or HTTPS that Session Recording Agent uses to communicate with Session Recording Broker. If not specified, this value defaults to HTTPS.

yourbrokerport is the port number that Session Recording Agent uses to communicate with Session Recording Broker. If not specified, this value defaults to zero, which directs Session Recording Agent to use the default port number for your selected protocol: 80 for HTTP or 443 for HTTPS.

/l*v specifies verbose logging.

yourinstallationlog is the location of your installation log file.

/q specifies the quiet mode.

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 Session Recording 7.6 (or later) to the latest release of Session Recording.

Notes:

• When you upgrade Session Recording Administration from 7.6 to 7.13 or later and choose Modify in Session Recording Administration 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.
• Attempts to upgrade the Session Recording Database might fail when you have only this component installed on a machine. In this case, check whether the following registry entries exist under HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\SmartAuditor\Database. If not, manually add the entries before upgrading.

Requirements, preparation, and limitations

Note: You cannot upgrade from a Technology Preview version.

• You must use the Session Recording installer’s graphical or command-line interface to upgrade the Session Recording components on the machine where you installed the components.
• Before beginning any upgrade activity, back up the database named CitrixSessionRecording in the SQL Server instance, so that you can restore it if any issues are discovered after the database upgrade.
• In addition to being a domain user, you must be a local administrator on the machines where you are upgrading the Session Recording components.
• If the Session Recording Server and Session Recording Database are not 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 package to upgrade. During the msi upgrade, a dialog box prompts for the credentials of a database administrator with the securityadmin and dbcreator server role permissions. Enter the correct credentials and then click OK to continue the upgrade.

• If you do not plan to upgrade all the Session Recording Agents at the same time, Session Recording Agent 7.6.0 (or later) can work with the latest (current) release of Session Recording Server. However, some new features and bug fixes might not take effect.
• Any sessions launched during the upgrade of Session Recording Server are not 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 is not installed after you upgrade Session Recording from a previous release that doesn’t contain this feature. To add this new feature, modify the installation after the upgrade.
• If there are live recording sessions when the upgrade process starts, there is very little chance that the recording can be completed.
• Review the upgrade sequence below, so that you can plan and mitigate potential outages.

Upgrade sequence

1. If 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, and then upgrade the Session Recording Database first.
2. Ensure that the Session Recording Broker is running with the IIS service. Upgrade the Session Recording Server. If the Session Recording Database and Session Recording Server are installed on the same server, the Session Recording Database will also be 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 Sessoin Recording Player.

Note: The following error might occur when you upgrade the Session Recording Administration component on Windows Server 2008 R2.

In this case, change the “.NET Framework version” for “SessionRecordingAppPool” to “.NET Framework v4” in IIS and do the upgrade again.

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 is not removed after the components are uninstalled.