File Download Resolution (url / link / fileName)

Overview

Every surface that triggers a file download on a device (single-device file operations, download tasks in Group Update / Device Profile / Automation, Device Profile files, and Provision) shares one resolution strategy for the fileName, url, and link fields. This page documents that shared behavior, the isManual flag returned on read, and the resetSession / targetLocation request fields introduced for these flows (DEV-2483, DEV-2403).

The backend builds a CpeFileWS and calls the ACS SOAP downloadFiles operation, which in turn issues the TR-069/CWMP Download RPC to the device. See TR-069 Download RPC flow below.

Affected surfaces

Surface Endpoint / entry point fileName field name

Single-device file operation

PUT /iot-webservice/Device/file

fileName

Provision file details

POST /iot-webservice/Device/file/details

fileName

Download task (Group Update)

Group update task action

filename (lowercase — see [Naming inconsistency])

Download task (Device Profile)

Device profile task action

fileName

Download task (Automation)

Automation task action

fileName

Device Profile files

Device profile file entries

fileName

Provision

Provision file resolution

fileName

[[Naming inconsistency]] NOTE: Field names are consistent as fileName, url, link, isManual, resetSession, targetLocation across every surface above except the Group Update task action response, which serializes the resolved file name as filename (lowercase). Consumers of that response must use the lowercase key; do not assume full naming uniformity across surfaces.

Resolution strategy

The backend applies the same three-case resolution to fileName / url / link on every surface listed above:

Case Input Resolution

(a) All empty

fileName, url, and link are all empty/null

The newest firmware for the user’s current domain is used. For download tasks this is the "newest firmware" flag; for Device Profile / single-device flows it resolves to the concrete file with the most recent upload date among the files flagged as newest. This preserves prior behavior.

(b) Select-from-list

Only fileName is provided (url/link are null); isManual=false

The backend builds the URL itself: the domain’s DownloadHttp server address + fileName. This is now applied consistently on all surfaces (previously only the single-device path built the URL this way).

(c) Manual enter URL

url and link are provided; isManual=true

The backend leaves url/link untouched and sends them to the device as given.

Credentials

The Username / Password sent to the device belong to the URL, not to the request (DEV-2733, DEV-3162):

  • Select-from-list / default server — the request carries no credentials (the UI does not ask for them), so the backend attaches the Username / Password configured for the file server the URL was resolved against (DownloadHttp for Download and Software manager, UploadHttp for Upload, resolved for the device’s domain with the parent-domain fallback). Without this the device receives <Username/><Password/> and cannot fetch or store a file on a server that requires authorization.

  • Manual enter URL — credentials the operator typed are sent untouched and are never overridden by the server ones. A manual URL that starts with the configured server address but carries no typed credentials gets the server credentials, exactly like a file selected from the list. A URL that does not start with the configured server address never receives the server credentials. The server address is matched as a directory: a server configured as http://host/labreports serves http://host/labreports/x.cfg but not http://host/labreports2/x.cfg.

  • Server without credentials — when the configured server has no username, the request values are sent as before (empty or absent).

The same rule applies to the CWMP Download and Upload RPCs, to ChangeDUState (Install / Update in the Software manager tab), and to their USP equivalents.

The rule is enforced on every surface that builds a file-transfer task or fetches a file with the file-server credentials, not only on the single-device tabs:

Surface Task Credential source

Find device (Download / Upload / Software manager)

Download, Upload, ChangeDUState

DownloadHttp / UploadHttp of the device’s domain (parent-domain fallback). For Upload, when the device’s domain row has no UploadHttp entry, the super-domain UploadHttp server supplies both the default URL and its credentials.

Find device > Reset with backup

Upload

The configured UploadHttp server of the acting client. A server without credentials keeps the empty Username / Password sent before.

Find device > Provision — Download (edit)

Stored provision Download

DownloadHttp of the acting client for a file selected from the list; typed credentials, and URLs on another server, are stored as sent.

Find device — download a device file (POST /iot-webservice/iotw/Device/file)

Backend HTTP fetch (no device RPC)

The UploadHttp server (default, or the caller’s own domain-specific one) that serves the link and has a username; when several do, the most specific one (the longest address) wins. Its credentials are sent as HTTP Basic auth. Any other link is fetched without an Authorization header.

Device profile — Download files

Download

DownloadHttp of the acting client

Device profile — Set models > backup

Upload

UploadHttp of the acting client (the backup URL adds the user’s domain folder)

Group update / Automation — Download, Upload, Install, Update software

Download, Upload, ChangeDUState

DownloadHttp / UploadHttp (UploadHttp for the acting user’s domain, parent-domain fallback)

Group update / Automation — Backup, Restore

Upload, Download

Always the configured UploadHttp / DownloadHttp server — these tasks have no manual URL, so the server credentials are always sent (none when the server has no username)

Known side effects

  • Credentials shown on read and export. Once stored with a task, the file-server password is returned in plain text wherever the stored task is read back or exported: device file details, provision details, group update / automation task details (Download, Upload, Install, Update software), device profile files, and the group update, automation (POST /iot-webservice/iotw/Automation/export) and device profile XML exports. The temporary files of these exports stay on the server disk: the group update and device profile ones are never deleted, the automation one only when the backend stops. Anyone who can open these views can read the file-server password.

  • Credentials of another domain’s server. A device in a sub-domain whose own file-server row has no matching server is sent the URL of the parent-domain or super-domain server, and now also that server’s credentials (URL and credentials always come from the same server). The read views above are not restricted to the device’s domain, so such credentials can be read back by users of other domains.

  • Download rows reopen as manual. A Download row selected from the list is stored with the server credentials, so the read-side heuristic below reports it as isManual=true: the device download list, provision details, group update / automation Download details and device profile files reopen it as "Enter URL manually", with the username visible and the password masked. Upload, Install and Update software rows are not affected.

  • Password rotation. A group update, automation, profile or provision task re-saved from its edit form keeps the credentials it was opened with, because typed (request) credentials win. After the file-server password changes, such tasks keep the old password until it is edited.

  • Tasks created before the fix keep their empty credentials until they are re-saved.

  • Device file download. A link on a parent-domain or other-domain UploadHttp server, or a link written before the UploadHttp address was changed, is no longer sent with Basic auth (previously every link was sent the first configured UploadHttp credentials, whichever server it pointed to). A relative link is completed with the DownloadHttp address first; it gets UploadHttp Basic auth only when an UploadHttp address is a prefix of the completed URL.

isManual (read)

On read, each file-download surface reports an isManual flag computed by one heuristic, shared across all surfaces: a link is reported as manual (isManual=true) when it either

  • does not start with the domain’s DownloadHttp base address, or

  • carries embedded credentials or a size parameter.

Any other link is reported as isManual=false (backend-resolved, select-from-list case).

New request fields: resetSession and targetLocation

Both fields are accepted on every file-download surface listed above (DEV-2483, DEV-2403):

Field Type Behavior

resetSession

boolean, default false

Maps directly to the reset attribute of the TR-069/CWMP Download RPC sent to the device.

targetLocation

string, optional

Reserved — not yet effective. The API accepts and stores the value, but it is not currently delivered to the device: the ACS SOAP interface / WSDL does not yet expose a corresponding field on the downloadFiles operation. Treat it as a placeholder for future ACS/WSDL support. Do not rely on any device-side effect from this field today.

TR-069 Download RPC flow

For the CPE-facing message exchange — how the resolved url and the resetSession value reach the device via the ACS downloadFiles SOAP call and the CWMP Download RPC — see TR-069 Download RPC flow (PlantUML sequence diagram).

Related pages