Agent Storage Requirements
When the Agent transfers files, uploads write parts to a local cache on the host machine before finalizing. The storage backing that cache directly affects upload throughput. On a VM whose primary storage is network-attached, this requires deliberate planning before deployment.
How the Agent Caches Uploads
Buffering only applies to uploads. Downloads do not use a local cache.
When the Agent receives an upload, it breaks the file into parts and stores each completed part in a FilePart cache on the host file system. Once all parts arrive, the Agent streams them into the final file in sequence, deleting each cached part as it is written. The cache is cleared on startup to ensure a clean state. If the Agent exits unexpectedly while a transfer is in progress, a garbage collection process removes any leftover files the next time the Agent starts.
Parallel part uploads are enabled by default (upload_parallel_parts = true). This is what drives the cache requirement: with parallel parts enabled, multiple parts accumulate in the cache simultaneously during large or concurrent uploads. If the Agent cannot build a valid same-volume cache, it logs the error and falls back to sequential uploads for that run.
Cache Storage Location
The upload_temp_file_part_path setting in the Agent configuration file controls where the FilePart cache is written. The path must be absolute and on the same filesystem volume as the Agent root (root).
Keeping the cache and the root on the same volume matters for finalization. When both are on the same volume, the Agent can stream each part directly into its final location without a cross-volume copy. When they are on different volumes, finalization copies every part across the volume boundary. If the root is on a NAS, that boundary is the network.
If upload_temp_file_part_path is not set, the Agent uses the OS default temporary file location, which may be on a different volume from the root.
Local disk (direct-attached storage) is strongly recommended for both the Agent root and the cache. SAN volumes attached via fiber channel are also acceptable. NAS storage (CIFS/SMB or NFS) is strongly discouraged. Network latency in the cache path adds overhead to every part the Agent writes and reads, degrading upload throughput across all concurrent transfers.
If NAS is the only available option for the Agent root, set upload_temp_file_part_path to a path on the same NAS volume rather than leaving it unset. Leaving it unset risks landing the cache on the system drive, which forces a cross-volume network copy for every part during finalization. When root and cache are on the same NAS volume, finalization avoids that extra copy, though overall throughput will still be lower than a local-disk deployment.
To verify the cache path on a deployed Agent, run files-agent service verify. If it warns about the FilePart cache path, set upload_temp_file_part_path explicitly.
Sizing the Cache
The cache is transient: parts are deleted as they are written during finalization, and the cache is cleared at startup. The disk space requirement at any given moment depends on how many concurrent uploads are in progress and how large those files are.
Use these guidelines when provisioning the volume that hosts the Agent root and cache:
| Scenario | Free Space Guidance |
|---|---|
| Basic install and logs | 1 GB |
| Normal production use | 5 GB |
| Recommended production buffer | 20 GB, or 10% of free disk, whichever is larger |
| Large uploads | At least the size of the largest expected in-flight upload; 2× is preferred |
Available space on the root volume matters more than total system disk space, because the cache must reside on the same volume.
Symlinks and Windows Shortcuts Inside the Mount Path
The Agent does not follow symlinks or Windows shortcuts by default. To allow the Agent to access storage locations pointed to by symlinks or shortcuts within the mount path, set follow_links = true in the Agent configuration file.
With Follow Links enabled, the Agent traverses the OS path to the backing storage transparently. Cache behavior is unchanged: the Agent always writes to upload_temp_file_part_path regardless of whether the transfer source or destination is a direct path or a symlink target. The sizing and storage location recommendations above apply in either case.
The performance of reads and writes to a symlinked path is governed by the backing storage of the symlink target. A symlink that points to a slower NAS share within an otherwise fast mount path will be limited by that NAS share's throughput.