How Deploy Processes Large Artifacts
This topic explains how Deploy processes archive formats internally, why the 2 GB boundary exists for ZIP archives, how adaptive permissions work when POSIX metadata is unavailable, and which storage backends support large artifacts.
For an overview of large artifact deployment support, see Deploy Larger Artifacts > 2 GB. For configuration options, see Customizing Large Artifact Deployments.
Archive Processing Overview
Deploy supports multiple archive formats for udm.FileArtifact, udm.ArchiveArtifact, and udm.FolderArtifact. Archives are processed using the Apache Commons Compress library, with handling based on archive type and size.
The table below summarizes file permission behavior for Unix-to-Unix deployments.
| Archive format | Processing class | Permission behavior on Unix |
|---|---|---|
| TAR, TAR.GZ, TAR.BZ | TarArchiveInputStream | POSIX permissions are preserved |
| ZIP ≤ 2 GB | ZipFile via SeekableInMemoryByteChannel | POSIX permissions are preserved |
| ZIP > 2 GB | ZipArchiveInputStream | Adaptive permissions |
| JAR | JarArchiveInputStream | Adaptive permissions |
For any deployment where the source artifact is a JAR archive, permissions are not retained. This applies to udm.FileArtifact and udm.ArchiveArtifact. From Deploy 26.1, adaptive permissions are applied only for udm.FolderArtifact when the source artifact is a JAR archive. In all other cases involving JAR archives, original POSIX permissions are not preserved.
The same streaming approach is used for Placeholder Scanning and Replacement, which also relies on Apache Commons Compress.
Streaming and the 2 GB Boundary
When an archive exceeds the in-memory processing limit or uses a format that requires streaming, Deploy cannot preserve POSIX permissions from the source. This section explains the two cases where streaming is used.
ZIP Archives
ZIP processing typically requires random access to the archive's central directory. Deploy achieves this by initializing a ZipFile via SeekableInMemoryByteChannel, which reads the entire archive into a Java byte[] in memory. Because a Java byte[] is limited to approximately 2 GB (Integer.MAX_VALUE), SeekableInMemoryByteChannel cannot hold archives larger than this limit.
For ZIP files above 2 GB, Deploy falls back to ZipArchiveInputStream, which processes the archive as a stream without loading it into memory. This stream-based reader cannot expose reliable POSIX permission metadata for each entry.
The 2 GB boundary is the default in-memory threshold. You can configure this threshold to a lower value so that any archive above that size is processed via ZipArchiveInputStream instead of being loaded in memory. This is useful for reducing heap pressure when running many parallel deployments. See Customizing Large Artifact Deployments for configuration details.
For more details on the ZIP format limitations in Apache Commons Compress, see the Apache Commons Compress ZIP Documentation.
JAR Archives
Unlike ZIP archives, JAR files are always processed using JarArchiveInputStream regardless of file size. Although the JAR format is based on ZIP, the Java JarArchiveInputStream class does not expose POSIX permission metadata for archive entries. This means Deploy cannot read original file permissions from any JAR archive, whether it is 10 MB or 10 GB.
Prior to Deploy 26.1, JAR-based udm.FolderArtifact deployments assigned 644 (rw-r--r--) to all extracted files. From 26.1, Deploy applies adaptive permissions: files matching the executable detection regex receive 755 (rwxr-xr-x) and all other files receive 644.
For udm.FileArtifact and udm.ArchiveArtifact, JAR archives are delivered to the target as-is without extraction, so internal file permissions are not affected.
Adaptive Permissions
When Deploy deploys a udm.FolderArtifact, the archive is extracted as an exploded folder. For large ZIP artifacts (> 2 GB) processed using the streaming approach, POSIX permissions are not preserved. JAR archives also do not retain POSIX permissions.
When a ZIP or JAR archive is deployed as an exploded folder using udm.FolderArtifact, Deploy applies adaptive permissions on Unix targets only when POSIX permissions are not available in the archive.
Extracted files are categorized based on whether they are identified as executables:
- Files identified as executables:
755(rwxr-xr-x) - All other files:
644(rw-r--r--)
Executable file detection is configurable in type-defaults.properties. For configuration details and customization options, see Customizing Large Artifact Deployments.
Recommendations
Follow these best practices to ensure reliable deployments and predictable permission handling for large artifacts.
| Situation | Recommendation |
|---|---|
| Artifact contains executables | Use TAR source + Tar copy strategy to preserve original permissions |
| Unix target, precise permissions required | Use TAR source + Tar copy strategy |
| Large ZIP/JAR on Unix target | Adopt adaptive permissions or repackage as TAR |
udm.FileArtifact / udm.ArchiveArtifact using JAR, Unix target | Permissions are not retained. All files default to 644 (rw-r--r--) |
udm.FolderArtifact using JAR, Unix target | Adopt adaptive permissions |
| High memory pressure from parallel deployments | Lower inMemoryThreshold or increase JVM heap. For guidance, see Production Environment Installation. |
udm.FileArtifact or udm.ArchiveArtifact > 2 GB | No special action needed, artifact is deployed as-is |