Is there any information available about the Symantec Management Agent (Altiris Agent) Package Download process?

ITMS 8.x

Note: The following information is subject to change in any given release. There are more details about this process but those are considered proprietary to our Product.

The following information is provided as a reference to help understand how the Symantec Management Agent (Altiris Agent) Package Download process works.  

Symantec Management Agent Package download

Meta information about package stored in three files - package.xml, snapshot.xml and snapdata.xml.

Package.xml

Xml file contains information about package location: site query and codebase URL, public key of a "Package Owner".
Starting 7.5 this file is transferred via encrypted channel (same as policy), encrypted with receiving Agent's key. Since it could have an ACC credentials inside and always has a package owner's public key - this file is not stored on disk anymore. It reside in the Agent's Secure Storage in encrypted form. Could be checked with help of SMATool.exe utility. 

The storage folder is in form:
    "Software Delivery\{package-guid}" - for Package Server's storage.
    "Package Delivery\{package-guid}" - for Agent's Software Delivery storage.

Package XML schema description:

Package - XML element describes information about the package. Required attributes:
id - Guid of a package.
sourceKey - the public key of a package owner (the NS or PS where this package is managed). If this key is not specified, the package integrity check will not succeed and package became invalid after number of download retries.
Source - XML sub-element describe the available sources of a snapshots to download and queries accordingly. Could contain several Codebase elements but only for one server (e.g. HTTP, HTTPS, UNC).
Codebase - exact link from where to download the snapshot. Required attributes:
href - HTTP link to the package folder containing binaries. Mutual exclusive with "unc" attribute.
unc - UNC path to the package folder containing binaries. Mutual exclusive with "href" attribute.
snapshot - link to the UNC file of HTTP request to receive the snapshot.xml.

Snapshot.xml

Xml file contains information about package content, i.e. files and folders layout, file hashes.
Starting from 7.5 this file is not changed by client anymore and stored locally in the exact form which it came from server. This is done in order to be able to check this file integrity against Package owner's public key, file content and the signed hash of it received from server. The key is received from package.xml (as described above). The signed hash is received in the HTTP response header "Content-Signature" while call of GetPackageSnapshot.aspx(.asp). For UNC servers signed hash is received by additionally downloading the snapdata.xml file (see below).

Snapshot XML schema description:

Snapshot (or FolderSnapshot) - XML element describes information about snapshot. Required attributes:
path - snapshot location path
time - package creation time as reported by NS Server
version - version of package (assigned by NS Server)
Root - XML element contains information about package folders and files. Attributes:
size - total size in bytes of all package files
files - total number of files in package
folders - total number of folders in package
Root element could have child elements with name "File".
File - XML element contains information about file. Attributes:
name - name of file.
size - size of file in bytes.
fileHash - simple SHA256 hash of a file.
lastModifiedTime - last modification time of file as reported by WEB server.

Snapdata.xml

Xml file contains signature of snapshot.xml file, path of snapshot, Id, etc.
This file introduced starting 7.5 release and is user for two reasons:

1.    1) Store locally extra information regarding the local snapshot (since the snapshot.xml is no longer allowed to be changed). This information is used by Agent's Package Delivery framework.

2.    2) Provide snapshot.xml signature for UNC transfers, since in this case we can't use any "headers" like while HTTP(S).

Snapdata XML schema description:

SnapshotData - XML element describes information about snapshot data. No required attributes. Only required sub-element "Security".
Security - required XML sub-element. Contains signature of a snapshot.xml file. Required attribute:
signature - SHA256 hash of a shapshot.xml file signed with private key of the package owner.

Agent on Windows 

Package file validation works by next algorithm. 

1.    1) If file does not exist it will be downloaded from package location.

2.    2) If file exists and matches size and timestamp from the snapshot the file is considered up to date and is not downloaded again

3.    3) If file exists, by using HTTP HEAD request a size and last modification date of original file retrieved from remote server.

a.          a) If sizes equals, but last modification dates are not match, file is considered as remote modified and will be downloaded from beginning. (''NOTE: time comparison resolution is 2 sec, i.e. absolute time difference less than 2 sec. treated as equivalent'')

b.          b) If local file size is less than remote file, file considered as partially downloaded and download will resume from next byte of already downloaded data.

Package Download retry logic and modifiers:  

Registry keys affecting retry logic are located in:

"HKEY_LOCAL_MACHINE\SOFTWARE\Altiris\Communications\Package Delivery"

Keys:

"Retry delay (mins)"
"Maximum retry delay (mins)"
"Maximum download attempts"
"Maximum download attempt time (mins)"

First time is taken "Retry delay (mins)". By default is 3 minutes, if no setting exist. If setting exist and larger than 60 minutes, then 60 minutes is used.
Each next retry the delay is doubled until it reach the maximum delay. If maximum delay does not exist in registry, then it is 2 hours. If it exist then the biggest value could be 1 day.
Calculated retries are reset upon Agent restart.

“Max attempts” and “Max download attempts time” are also considered. If they exist and exceeded, the whole Retry will fail for given package. Package status set to INVALID instead of RETRYING.
Maximum value of “Max attempts” is 100 times, If it is greater in the registry, then 0 is returned.
Maximum value of “Max download attempts time” is two weeks. If it is greater in the registry, then 0 is returned.

Package Download backoff logic:

Package Delivery has a built-in "backoff" logic which increase the timeout between package download retires in case when no codebases are received from NS.
The logic is quite simple: if no codebases are returned from NS and the reason for that is any failure during retrieving process,, decompressing, decoding, or server returned any error of: "Server busy", "Server is paused", "Flush agent events" or "Package not ready", then the retry timeout for next codebases request is doubled.
If codebases are received successfully, then the timeout is reset back to minimal value. The minimum is 3 minutes, the maximum is 2 hours.

The first time the Package Delivery was unable to download the package is stored in package folder log.xml file. The time span in minutes from the first fail and current attempt is sent to the NS while codebases request, in order NS to know how long we are trying to get the package and when we exceed the timeout - NS return own codebases.

Package repositioning in the download queue:

When DownloadPackage is called on PackageDelivery, the package is inserted into the queue based on its priority and size and delay value.
Later, when the snapshot is downloaded package could be updated and repositioned in the queue.
While inserting or repositioning, if package is the first in the queue, then package which is being currently downloaded is stopped with reason "preempted by higher priority package" and status is set back to "PKGDLV_PENDING". Package stays in the queue.

The Queue ordering is:
    Not In Delay first
    Within those not in delay it is further ordered:
        Highest priority to low priority
        If equal, low delay to high delay (Corresponds to 'least number of retries first')
        If still equal, smallest package to largest package
    Packages in delay are in no specific order.

The "delay" is set/updated only for failed downloads, not for stopped with "preempted" reason. So the stopped with "preempted" reason will start immediately after the previous download is complete.

Agent on Unix, Linux and Mac

Package file validation works according to the following algorithm:

1.    1) If file does not exist it will be downloaded from package location.

2.    2) If file exists:

a.          a) If modification time in snapshot is different from the last modification time of file on disk, file will be re-downloaded.

b.         b) If file on disk is greater than specified in the snapshot, the file will be re-downloaded.

c.         c) If file on disk has the same size as specified in the snapshot, it is considered to be ready.

d.        d) If file on disk is smaller than specified in the snapshot download will be attempted:

       i.        If file is smaller than 64 bytes, it is re-downloaded.
      ii.        Otherwise, last 32 bytes are discarded and download is resumed from that position.

181098 Symantec Management Agent (Altiris Agent) Download Logic

181777 Symantec Management Agent (Altiris Agent) Package Download