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
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)
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
Peculiarities and limitations
Applications compatibility:
- Certain applications (Windows Defender, Double Commander) trigger full file hydration when attempting to access a piece of a file. It's advisable to add Resilio Shared to Windows Defender exclusions list to avoid full file hydration.
- Downloads triggered by an app (e.g., VLC) remain as placeholders if the app is closed mid-download.
- Download may be NOT triggered and error reported by some applications (e.g. Wondershare Filmora) if file is opened with drag&drop. Set custom parameter in Job profile placeholders_as_regular_files_for_smb_server:1 as a workaround for files accessed via SMB (the workaround does not work for local TSS shares).
- AutoCAD may trigger file downloads via SMB without explicit pinning.
- 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.
- Thumbnail support requires shared locks enabled in Job and custom parameter in the Job or Agent profile placeholders_as_regular_files_for_smb_server:1
- 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 elevated 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.
- Ungraceful system shutdowns force the agent to recheck partially downloaded placeholders.