Package Files & Folder Uploads

A deployment package carries the files its steps use: an MSI, a setup.exe, a script, or a whole installation source such as an Office folder with thousands of files in subfolders. This page covers uploading single files and whole folders in the package editor, by drag-and-drop, with Add-AthenaDeploymentPackageFile, and over the REST API. It also covers the minimum free disk space rule that replaces the old per-file size limit, and the rules for file paths inside a package. For the steps themselves, see Deployment Package Steps.

Uploading in the package editor#

Open Deployments, click View All Packages (/deployments/packages), then create or edit a package. Enter the package's folder name first, because a package can't take files without one. Files are uploaded from the step that uses them:

Next to the file picker there are two buttons:

• Upload files: choose one or more files. Each file goes to the package root.
• Upload folder: choose a folder. Its contents go to the package root and keep their subfolders.

You can also drag files or a folder onto the file row. A dropped folder is handled the same way as Upload folder.

How a folder is laid out#

The name of the folder you pick or drop is not part of the package. Only what is inside it is uploaded. For example, uploading a folder named OfficeSource stores its files like this:

So an Install Application step can point at setup.exe, and the installer finds its Office\Data folder next to it on the endpoint, as it would in the original source folder. The file pickers list every file by its path in the package.

Progress and results#

• Before the upload starts, Athena checks the free disk space rule against the total size of everything you selected. If the rule fails, nothing is uploaded and an error message gives the numbers.
• Files are uploaded one at a time. A progress bar under the file row shows Uploading 3 of 120: Office/Data/v64.cab (45%). The upload buttons are disabled until the upload finishes.
• The package bundle (package.zip) is rebuilt once, after the last file. When it is ready you see 120 file(s) uploaded.
• If a file fails, you see Upload of <path> failed: <reason> and the upload stops. The files already uploaded stay in the package, and the bundle is rebuilt with them.
• If the files arrive but the bundle can't be rebuilt, you see The files were uploaded but rebuilding package.zip failed. Save the package to try again.
• For a new package, the first upload creates the package on the server so the files have somewhere to go.

Replacing a file#

Uploading a file to a path that already exists in the package replaces it. Paths are compared without regard to case, because a Windows endpoint would treat Setup.exe and setup.exe as the same file. To update an installation source, upload the new folder over the old one. Files that are missing from the new folder are not removed from the package. To start clean, create a new package, or remove the old files with DELETE api/deployment-packages/{id}/files/{fileId} (see REST API).

Minimum free disk space#

Every file is stored twice on the server: once as the uploaded file and again inside the package's package.zip bundle. Athena accepts an upload only when the disk that holds the package files keeps enough free space afterwards:

free space − (2 × upload size) ≥ minimum free disk space

The rule applies to the package editor, PowerShell and the REST API. When an upload is refused, the message gives the numbers, for example:

Not enough free disk space on the server: 18.4 GB free, this upload needs 9.2 GB (the file and its
copy in package.zip), and at least 10 GB must stay free. An Admin sets the minimum in
Settings > Scheduler > Execution.

Changing the minimum#

Go to Settings → Scheduler → Execution and set Minimum Free Disk Space for Package Uploads. Changing it requires the settings.manage permission. See Scheduler Settings.

Rules for file paths#

Package files are unpacked on Windows, Linux and macOS endpoints, so every path in a package must be a valid Windows path, even when the Athena server runs on Linux. Backslashes are turned into forward slashes. Athena refuses an upload whose path:

• is empty or longer than 400 characters;
• starts with / or \, is a UNC path, contains // or ends with /;
• has a . or .. segment;
• contains < > : " | ? * or a control character (this blocks drive letters such as C: and alternate data streams);
• has a file or folder name that ends with a dot or a space;
• uses a reserved Windows device name, with or without an extension: CON, PRN, AUX, NUL, COM0–COM9, LPT0–LPT9 (for example nul.txt);
• is manifest.json or package.zip at the package root, because the bundle uses those names itself. The same names inside a subfolder are allowed.

The refusal reads:

Invalid package file path: 'C:/Temp/x.msi'. Use a relative path such as Office/Data/file.cab, without '..', a drive, ':' or reserved names.

PowerShell: Add-AthenaDeploymentPackageFile#

The Athena PowerShell module 2.19.0 and later uploads files and whole folders with Add-AthenaDeploymentPackageFile. Each file is streamed from disk in its own request, so files larger than 2 GB work. The cmdlet has no client time-out, so a long upload isn't cut off. package.zip is rebuilt once, after the last file. It requires packages.manage.

Without -File or -Folder, the cmdlet detects each path's type. The cmdlet supports -WhatIf and -Confirm, and returns one object per uploaded file: FileName (its path in the package), FileSize, FileHash (SHA-256), UploadedBy and UploadedAt.

# Upload an Office source folder: setup.exe, config.xml and Office\Data\... with subfolders
Add-AthenaDeploymentPackageFile -PackageId $pkg.Id -Path 'C:\Sources\OfficeLTSC2024' -Folder

# Upload one file to the package root, piping the package in
Get-AthenaDeploymentPackage -Id $id | Add-AthenaDeploymentPackageFile -Path '.\setup.msi' -File

# Upload one file into a subfolder of the package
Add-AthenaDeploymentPackageFile -PackageId $id -Path '.\x64.cab' -RelativePath 'Office/Data/x64.cab'

# Preview what would be sent
Add-AthenaDeploymentPackageFile -PackageId $id -Path 'C:\Sources\App' -WhatIf

REST API#

The upload endpoint takes two optional query parameters:

If a package runs its steps as a stored credential from the Credential Vault, changing its files also requires the credentials.use permission.

# Upload one file into a subfolder without rebuilding, then rebuild once
curl -H "Authorization: Bearer $TOKEN" \
  -F "file=@v64.cab" \
  "https://athena.example.local:8443/api/deployment-packages/$PKG/files?relativePath=Office/Data/v64.cab&rebuild=false"

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://athena.example.local:8443/api/deployment-packages/$PKG/build"

See API Tokens for a token to use in scripts, and the API Reference for the response envelope.

On the endpoint#

• The agent unpacks package.zip into the deployment folder and recreates its subfolders, so a step finds Office\Data\… where the installer expects it.
• Agents refuse any bundle entry that would unpack outside the deployment folder. The Linux and macOS agents always made this check. The Windows agent makes it from version 1.2.163; see Agent Binaries & Updates.
• A large package can take minutes to reach each agent. Starting a deployment returns as soon as the agents have the request, and the file transfer continues in the background. Each agent reports its result as usual in Deployment Tracking.

Troubleshooting#

Related#

• Deployment Package Steps: the step types that use package files.
• Package Templates: the package editor.
• Deployment Packages (PowerShell).
• Package Library: a separate store for single large installer files shared by download link.
• Scheduler Settings → Execution.