Skip to content

File streaming: progressive Hydration in TSS

Feature availability

Available from: Resilio Active Everywhere 4.2.0
Available for: Windows, Linux, macOS Agents, accessing local files or over SMB.

Progressive hydration is a TSS feature that optimizes access to large media and project files. With the progressive hydration, you can open a placeholder file without having to wait for the Agent to complete the download.

Hydration modes

Hydration determines how files are downloaded and accessed.

  • Partial hydration Only downloads required parts of a file based on user activity. This mode optimizes storage usage. The difference between the partial and the progressive hydration modes is the lack of continuous hydration in the background.
  • Progressive hydration (file streaming)
    File chunks are available as soon as they are downloaded. Improves responsiveness for large files by allowing partial access while the downloading of the file continues in the background.
  • Full hydration (legacy mode)
    The entire file is fully downloaded before an application can access it. Can cause delays when handling large media or project files.

Enable file streaming

To enable file streaming, add the tss_hydration_policy custom parameter to the Job Profile, setting its value to the hydration mode you want to enable:

  • 0 - Partial hydration
  • 1 - Progressive hydration
  • 2 - Full hydration

Recreate the Job - applicable to Windows Agents

If you enable file streaming for an existing Job, you must recreate the Job for the changes in the TSS policy to take effect on Windows Agents. Agents running on macOS do not require Job recreation.

TSS supports two key streaming modes that allow file interaction without requiring full hydration:

  • Read File Streaming. Allows reading blocks of a file before it is fully downloaded. Enables quick access to large files like AutoCAD drawings.
  • Write File Streaming. Supports writing blocks of a file before full hydration. Ensures smooth workflow without waiting for full file availability.

Optimize read and write speeds (applicable to Windows/SMB Cache Server)

Some settings are enforced when using a Windows/SMB cache server: system_native_placeholders_validation_required:false

Note

Add this custom parameter before you create a job. Applying it to an existing job won't take effect.

The parameter controls VALIDATION_REQUIRED policy.

true (Default): Ensures validation but may slow down write speeds. If enabled, SMB may fail read requests during hydration with an "Insufficient system resources" error for large files.

false: Improves performance increasing read/write speed, but requires 8-byte aligned reads. Use false if dealing with large files and the application supports 8-byte aligned reads. Causes ERROR_OFFSET_ALIGNMENT_VIOLATION when reading non-8-byte-aligned offsets. It's safe to disable when reading via SMB (as SMB auto-aligns offsets).

The data below present a performance comparison of different hydration policies across Windows and Linux environments on 3 files of 20GB each which are read sequentially / in parallel. This comparison helps in understanding the trade-offs between different hydration strategies, providing insights into optimizing read performance for various use cases.

Windows - Progressive Hydration (tss_hydration_policy = 1)
Parallel Read
system_native_placeholders_validation_required:true→ 290 sec, 200MBps
system_native_placeholders_validation_required: false → 135 sec, 440MBps
Sequential Read
system_native_placeholders_validation_required:true → 379 sec, 160MBps
system_native_placeholders_validation_required: false → 230 sec, 260MBps

Windows - Full Hydration (tss_hydration_policy = 2)
Parallel Read
system_native_placeholders_validation_required:true → 164 sec, 365MBps
system_native_placeholders_validation_required: false → 176 sec, 340MBps
Sequential Read
system_native_placeholders_validation_required:true → 289 sec, 207MBps
system_native_placeholders_validation_required: false → 223 sec, 270MBps

Linux - Progressive Hydration
Parallel Read → 119 sec, 535MBps
Sequential Read → 123 sec, 488MBps

Linux - Full Hydration
Parallel Read → 163 sec, 368MBps
Sequential Read → 173 sec, 347MBps

Linux - Partial Hydration
Parallel Read → 198 sec, 303MBps
Sequential Read → 745 sec, 81MBps

Configure Windows Defender Exclusion

A new custom parameter, tss_add_defender_exclusion_list, is available to manage automatic Windows Defender exclusions. By default, this parameter is set to false. Any changes to this parameter require the Agent to be restarted. When enabled, either in Job or an Agent profile, the Agent will attempt to add its job folder to the local exclusion list of Windows Defender. This can help avoid full file hydration on file access.

If the attempt is blocked (e.g., by system policy), the Agent will log a warning:
Resilio Agent attempted to add a Windows Defender exclusion, but this is blocked by policy for security reasons. Please contact your administrator to request changes through the centralized management panel.
Note: This failure may occur due to any restriction, not just Group Policy.

While the warning is active, the Agent will continue to function. Users can open files, but the files will be fully hydrated upon access, which may affect performance.
To resolve the warning disable the custom parameter by setting it to false or remove the parameter from the Agent or Job profile.

Peculiarities and limitations

Applications compatibility:

  • Certain applications (Windows Defender, BitDefender, Double Commander) trigger full file hydration when attempting to access a piece of a file. It's advisable to add Resilio Shares to Windows Defender and other security software's exclusions list manually or using the custom parameter to avoid full file hydration.
  • Downloads triggered by an app (e.g., VLC) remain as placeholders if the app is closed mid-download.

  • A file open error may be reported by some applications if the file is opened from an SMB client. To mitigate this, add the following custom parameter to the Job profile: placeholders_as_regular_files_for_smb_server:1.

    Adobe Acrobat

    In case of saving or editing PDF documents accessed over SMB using Adobe Acrobat, set the placeholders_as_regular_files_for_smb_server parameter value to 2, in the Job or the Agent profile.

  • AutoCAD may trigger file downloads via SMB without explicit pinning.

  • Large project files accessed via SMB (e.g., Blender) may cause app freezes until fully downloaded.
  • Memory mapped files (mmap) are not supported for streaming. This usually refers to video files, as players use memory-mapped I/O. Memory mapping is not a file's or app's property, but a way to access the files. To learn if it's accessed using mmap, you need to inspect the system and app's process details: check for page cache activity, system calls related to mmap or alike.

Storage management:

  • No way to dehydrate a partially downloaded file via context menu. To optimize storage usage, available space should be monitored in File Caching and Hybrid Work Jobs, especially when handling large files that may exceed file policy limits. Partially downloaded files are cleared with File Policy cleanup process, or manually from the CLI using command attrib +U %filename%
  • Changing a piece of a file forces full hydration and propagates the new version to other peers.

Jobs and configuration:

  • For Windows agents, changes to the hydration policy require recreating the job for them to take effect.
  • Partially downloaded files in a Gateway scaleout group may not trigger downloads on other gateway servers in the group.