Available from: Resilio Active Everywhere 4.2.0
Available for: Windows, Linux, macOS agents, accessing local files or over SMB.
This guide provides instructions on configuring and using the new Progressive Hydration feature in TSS for handling large media and project files. It covers different hydration modes, configuration parameters, usage scenarios, and best practices for optimizing performance.
Understanding Hydration Modes
Specifics for Windows/SMB Cache Server. Optimizing Read & Write Speeds
Configuring Windows Defender Exclusion
Peculiarities and limitations
Understanding Hydration Modes
Hydration determines how files are downloaded and accessed. TSS now supports three hydration modes:
- 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.
- Progressive Hydration (new mode, file streaming). File chunks are available as soon as they are downloaded. Improves responsiveness for large files by allowing partial access while downloading continues.
- Partial Hydration. Only downloads required parts of a file based on user activity. Optimized for efficiency and storage management. The difference between partial and progressive modes is the lack of continuous hydration in the background.
Configuration parameter in Job profile: tss_hydration_policy = 0/1/2 (0 = Partial, 1 = Progressive, 2 = Full). Should be configured before job creation, requires recreating the job.
Important: This must be set before job creation and cannot be changed at runtime. Changing requires recreating the job.
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.
Specifics for Windows/SMB Cache Server. Optimizing Read & Write Speeds
Some settings are enforced when using a Windows/SMB cache server: system_native_placeholders_validation_required:false
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
Configuring 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.
- File open error may be reported by some applications if file is opened from SMB client. To mitigate this keep custom parameter in Job profile placeholders_as_regular_files_for_smb_server:1
As an exclusion, editing/saving PDFs via Adobe Acrobat over SMB requires setting custom parameter in Job or Agent profile placeholders_as_regular_files_for_smb_server:2.
- 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.
Storage management:
- No way to dehydrate a partially downloaded file via context menu. To optimize storage usage, available space should be monitored in File Cache 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:
- Upgrades require new job creation on Windows Agents to start using progressive hydration.
- Partially downloaded files in a Gateway scaleout group may not trigger downloads on other gateway servers in the group.