Symantec Management Agent (Altiris Agent) Package Download

book

Article ID: 181777

calendar_today

Updated On:

Products

Management Platform (Formerly known as Notification Server)

Issue/Introduction

 

Resolution

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

The following information is provided as a reference to help to understand how the Symantec Management Agent (Altiris Agent) Package Download process works. Other details can be found under HOWTO77271 "Symantec Management Agent (Altiris Agent) Download Logic"

 

 

 

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 AeXAgentCmd.exe utility.
Note:
aexagentcmd.exe is not installed by agent setup anymore after 7.5.1588. Please use SMATool.exe from server's \Notification Server\Bin\Tools folder, SMATool.exe got the the same command-line parameters. You can copy it to a client machine and use, don't forget to remove it after usage since it can expose all the senstive information stored on the agent.

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.    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.    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.    If file does not exist it will be downloaded from package location.

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.    If file exists, by using HTTP HEAD request a size and last modification date of original file retrieved from remote server.

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.    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.

 

Agent on Unix, Linux and Mac

Package file validation works according to the following algorithm:

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

2.    If file exists:

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

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

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

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.