Manage recordings

ICA log database (ICLDB) is a database command-line utility used to manipulate the session recording database records. This utility is installed, during the Session Recording installation, to the <Session Recording Server installation path>\Bin folder on the server hosting the Session Recording server.

Note:

If you want to use ICLDB to manage session recording files stored in Azure file shares, run the SsRecUtils.exe -MountAzureFiles command. SsRecUtils.exe and ICLDB are in the same folder.

Quick reference chart

The following table lists the commands and options that are available for the ICLDB utility. Type the commands using the following format:

ICLDB [VERSION | LOCATE | DORMANT | IMPORT | ARCHIVE | REMOVE | REMOVEALL] command-options [/L] [/F] [/S] [/?]

Note:

More extensive instructions are available in the help associated with the utility. To access the help, from a command prompt, type the \Program Files\Citrix\SessionRecording\Server\Bin folder, and type icldb /?. To access help for specific commands, type icldb <specific command> /?.

The RULES parameter for ICLDB ARCHIVE and ICLDB REMOVE commands

The RULES parameter sets advanced filters by combining multiple filters strictly in accordance with the /RULES:FIELD-In-["CONDITION","CONDITION"];FIELD-NotIn-["CONDITION","CONDITION"]; format, where:

• “FIELD” sets a filter with a field, which can be “path”, “user”, “group”, “deliverygroup”, “application”, “server”, “client”, or any other column in the database table called dbo.ICLFile.

• “In” means that at least one of the filter conditions in the brackets must be met for a recording file to be an operation object.

• “NotIn” means that recording files that meet any of the filter conditions in the brackets are excluded from the operation.

• “CONDITION” sets a filter condition with a record (or row) in the database table called dbo.ICLFile.

• User and group records must be entered in the format of <domain>.<name>.

• Path records can be filtered by using Windows wildcards.

• You must enclose each “CONDITION” item in double quotes ("") and separate two “CONDITION” items with a comma (,).

• Do not add spaces when entering “CONDITION” items unless a “CONDITION” item itself contain spaces.

• If a “CONDITION” item contains one or more commas, enclose the “CONDITION” item in double quotes that are followed by escaped double quotes """ """.

• Multiple filters can be used in various combinations. End each filter with a semicolon (;).

• The “AND” logical operator is used to compute the multiple filters. There is no limit to the number of filters, but the total length of RULES must not exceed 2,048 bytes.

Examples:

• /RULES:group-In-["BUILTIN.Guests"];
• /RULES:path-In-["S:\SessionRecordings\2023*"];group-NotIn-["Mydomain.Suspicious","Mydomain.Persistence"];
• /RULES:deliverygroup-In-["RdsDesktopAndAppGroup"];user-In-["Mydomain.AdminA","""Mydomain.Admin,,,B"""];
• /RULES:EndReasonID-In-["1","2"];

Archive session recording files

To maintain an adequate level of spare disk capacity in the recording storage locations, archive session recording files regularly. Depending on the amount of available disk space and the typical size of recording files, archiving intervals differ. Session recording files must be older than two days from the start date before a session recording file can be archived. This rule is to prevent any live recordings from being archived before they become complete.

Two methods are available when you archive session recordings. The database record for a recording file can be updated to have a status of archived while the file remains in the recording storage location. This method can be used to reduce the search results in the player. The other method is to update the database record for a recording file to the archived status and move the file from the recording storage location to another location for backup to alternative media. When moving session recording files, the ICLDB utility moves them to the specified directory where the original file folder structure of year/month/day no longer exists.

The session recording record in the Session Recording database contains two fields associated with archiving—the archive time and archive note. The archive time represents the current date and time that a recording was archived. The archive note is an optional text note that can be added during archiving. The two fields indicate that a recording has been archived and the time of archiving.

In the Session Recording player, archived session recordings show a status of Archived and the date and time of archiving. Session recordings that have been archived might still be played if the files have not been moved. If a session recording file was moved during archiving, a file not found error is displayed. The session recording file must be restored before the session can be played. To restore a session recording file, provide the File ID and Archive Time of the recording file. Restoring archived files is discussed further in the following Restore session recording files section.

The ARCHIVE command of the ICLDB utility has several parameters that are described as follows:

• /FILEID:<id> - Lets you specify a target session recording file. You can check the ID of a session recording file in the Session Recording player (Windows). A recording file name can also be used as the file ID.

• /RETENTION:<days> - The retention period in days for session recordings. Recordings older than the number of days specified are marked as archived in the Session Recording database. The retention period must be an integer number greater than or equal to 2 days.

• /FILTER:<filter>: Lets you filter file paths by using the * and ? wildcards. The FILTER parameter is optional. If you add the FILTER parameter, only those session recording files meeting both RETENTION and FILTER are archived.

• /RULES:<advanced filters>: Sets advanced filters by combining multiple filters strictly in accordance with the /RULES:FIELD-In-["CONDITION","CONDITION"];FIELD-NotIn-["CONDITION","CONDITION"]; format. The RULES parameter and the FILTER parameter cannot be used together. For more information, see the preceding The RULES parameter for ICLDB ARCHIVE and ICLDB REMOVE commands section in this article.

• /LISTFILES – Lists the full path and file name of session recording files as they are being archived. This parameter is optional.

• /MOVETO:<directory> - The directory to which you physically move archived session recording files. The specified directory must exist. This parameter is optional. If no directory is specified, the files remain in their original storage location.

• /NOTE:<note> - A text note that is added to the database record for each session recording archived. Ensure that the note is enclosed with double quotes. This parameter is optional.

• /L – Logs the results and errors to the Windows event log of the number of session recording files archived. This parameter is optional.

• /F – Forces the archive command to run without prompts. This parameter is optional.

To archive session recordings in the Session Recording database and physically move session recording files

1. Log on to the server where the Session Recording server is installed as a local administrator.

2. Start a command prompt.

3. Change from the current working directory to the Bin directory of the Session Recording server installation path (<Session Recording server Installation Path>\Bin).

4. Run the ICLDB ARCHIVE /RETENTION:<days> [/LISTFILES] [/MOVETO:<dir>] [/NOTE:<note>] [/FILTER:<file path filter>] [/RULES:<advanced filters>] [/L] [/F] [/S] [/?] command. The parameters in brackets are optional. Remove the brackets when running the command. The RULES parameter and the FILTER parameter cannot be used together. days is the retention period for session recording files, directory is the directory where archived session recording files are moved to, and note is the text note that is added to the database record for each session recording file being archived. Enter Y to confirm the archive.

To only archive session recordings in the Session Recording database

1. Log on to the server where the Session Recording server is installed as a local administrator.

2. Start a command prompt.

3. Change from the current working directory to the Bin directory of the Session Recording server installation path (<Session Recording server installation path>\Bin).

4. Run the ICLDB ARCHIVE /RETENTION:<days> [/LISTFILES] [/NOTE:<note>] [/FILTER:<file path filter>] [/RULES:<advanced filters>] [/L] [/F] [/S] [/?] command. The parameters in brackets are optional. Remove the brackets when running the command. The RULES parameter and the FILTER parameter cannot be used together. days is the retention period for session recordings and note is the text note that is added to the database record for each session recording being archived. Enter Y to confirm the archive.

Restore session recording files

To view a recording file archived in the Session Recording database and moved from the recording storage location, restore it. Archived session recordings that were not moved from the recording storage location during archiving are still accessible in the player.

Two methods are available for restoring session recording files that have been moved. Copy the required session recording file to the restore directory for archived files. Or, import the required session recording file back to the Session Recording database by using the ICLDB utility. We recommend the first method for restoring archived session recording files. Remove archived files copied to the restore directory for archived files when you no longer need them.

The Session Recording Broker uses the Restore directory for archived files when a session recording file is not found in its original storage location. This case occurs when the player requests a session recording file for playback. The Session Recording Broker first attempts to find the session recording file in the original storage location. If the file is not found in the original storage location, the Session Recording Broker then checks the Restore directory for archived files. If the file is present in the restore directory, the Session Recording Broker sends the file to the player for playback. If the file is not found, the Session Recording Broker sends a file not found error to the player.

Importing an archived recording file updates the Session Recording database with the session recording information from the file, including a new storage path. Importing an archived session recording file doesn’t move the file back to the original storage location when the session was recorded.

Note: An imported session recording file has the archive time and archive note cleared in the Session Recording database. The next time the ICLDB ARCHIVE command is run, the imported session recording file might become archived again.

The ICLDB IMPORT command is useful to import a large number of archived recording files. It can repair or update incorrect and missing session recording data in the Session Recording database. It is also useful to move session recording files from one storage location to another on the Session Recording server. You can use the ICLDB IMPORT command to repopulate the Session Recording database with session recordings after running the ICLDB REMOVEALL command.

The IMPORT command of the ICLDB utility has several parameters that you can use for restoring archived recording files:

• /LISTFILES – Lists the full path and file name of session recording files while they are being imported. This parameter is optional.

• /RECURSIVE – Searches all subdirectories for session recording files. This parameter is optional.

• /RELOCATE – Without the RELOCATE parameter, the IMPORT command parses session recording files in their entirety, which takes time. With the RELOCATE parameter, the IMPORT command simply locates the database records of session recording files and updates their file paths directly.

• /L – Logs the results and errors to the Windows event log the number of session recording files imported. This parameter is optional.

• /F – Forces the IMPORT command to run without prompts. This parameter is optional.

Note:

The IMPORT command of the ICLDB utility also provides an optional parameter, RELOCATE, that you can use for relocating recording files. For more information, see the Relocate session recording files section in this article.

Restore session recording files by using the restore directory for archived files

1. Log on as a local administrator to the server where the Session Recording server is installed.

2. In Session Recording Player Properties, determine the File ID and Archive Time of the archived session recording file.

3. Locate the session recording file in your backups using the File ID specified in Session Recording Player Properties. Each session recording has a file name of i_<FileID>.icl, where FileID is the ID of the session recording file.

4. Copy the session recording file from your backup to the restore directory for archived files. To determine the restore directory for archived files:

   1. From the Start menu, choose Start > All Programs > Citrix > Session Recording Server Properties.

   2. In Session Recording Server Properties, select the Storage tab. The current restore directory appears in the Restore directory for archived files field.

Restore session recording files by using the ICLDB IMPORT command

1. Log on as a local administrator to the server where the Session Recording server is installed.

2. Start a command prompt.

3. Change from the current working directory to the Bin directory of the Session Recording server installation path (<Session Recording server installation path>\Bin).

4. Either:

   • Run the ICLDB IMPORT /LISTFILES /RECURSIVE /L <directory> command where directory is the name of one or more directories, separated by a space containing session recording files. Enter Y to confirm the import.

   • Run the ICLDB IMPORT /LISTFILES /L <file> command where file is the name of one or more session recording files, separated by a space. Wildcards might be used to specify session recording files. Enter Y to confirm the import.

Relocate session recording files

You can move session recording files to different storage paths for load balancing or other purposes. To ensure that the files can still be played, you must update their new paths to the Session Recording database. To do so, use the ICLDB IMPORT command. To accelerate the import process, append the RELOCATE parameter to the ICLDB IMPORT command.

Note:

The RELOCATE parameter is optional. Without the RELOCATE parameter, the ICLDB IMPORT command parses session recording files in their entirety, which takes time. With the RELOCATE parameter, the ICLDB IMPORT command simply locates the database records of session recording files and updates their file paths directly.

The following steps illustrate how to use the RELOCATE parameter to update new file paths to the Session Recording database.

1. Move session recording files to different storage paths as needed.

2. Log on as a local administrator to the server where the Session Recording server is installed.

3. Start a command prompt.

4. Change from the current working directory to the Bin directory of the Session Recording server installation path (<Session Recording server installation path>\Bin).

5. Either:

   • Run the ICLDB IMPORT /LISTFILES /RECURSIVE /RELOCATE /L <directory> command where directory is the name of one or more directories, separated by a space containing session recording files. Enter Y to confirm the import.

   • Run the ICLDB IMPORT /LISTFILES /RELOCATE /L <file> command where file is the name of one or more session recording files, separated by a space. Wildcards might be used to specify session recording files. Enter Y to confirm the import.

Note:

• The RELOCATE parameter assumes that there are already records of the session recording files in the Session Recording database.
• The session recording files must be playable before being moved. Otherwise, the RELOCATE parameter does not help.
• The new storage paths of the session recording files must be recognizable by the Session Recording server. You can try them on the Storage tab of Session Recording Server Properties.

Close unresponsive or dormant live recordings

By default, a live recording is considered unresponsive or dormant if no new data was written to the recording file for 24 hours. You can configure this time threshold on the Storage tab of Session Recording Server Properties to close unresponsive or dormant live recordings automatically when this threshold is exceeded. The minimum value that you can set is 12 (hours).

You can also manually close unresponsive or dormant live recordings by using the ICLDB DORMANT command, for example:

ICLDB DORMANT [/DAYS:<days> | /HOURS:<hours> | /MINUTES:<minutes> | /FILEID:<id>] [/LISTFILES] [/CLOSEFILES] [/L] [/F] [/S] [/?]
<!--NeedCopy-->

The FILEID parameter lets you specify a target session recording file and the CLOSEFILES parameter lets you manually close unresponsive or dormant live recordings that you specify.

Tip:

You can check the ID of a session recording file in the Session Recording player (Windows). A recording file name can also be used as the file ID.