ConfigMgr 2007: The Preload Package Tool (PreloadPkgOnSite.exe) Explained

imageWhen using the Preload Package Tool (PreloadPkgOnSite.exe) to preinstall a package on a DP on a child site, the tool may not work as expected and the package may not show as being installed on the remote DP where the tool was used. The instructions on the Preload Package Tool site at:

http://www.microsoft.com/downloads/details.aspx?FamilyID=C36FCDA8-9336-4D44-9568-5530FF7635DD&displaylang=en

instruct to do the following:

1- Copy PreloadPkgOnSite.exe file to the .\program files installation directory\bin\i386 directory on the child site that you wish to preload compressed software distribution package source (.pck) files.

2- Copy the applicable .pck files from the parent site or from a backup location to the distribution point share on the child site manually. After manually copying the files, ensure that the read-only NTFS file attribute for the .pck file is set.

3- From a command prompt, run the tool using the following syntax: PreloadPkgOnSite.exe PkgID StoredPkgVersion.

4- Running this command will update necessary software distribution package source location information for the site and forward this information up the hierarchy.

5- After the package source file location information is sent up the hierarchy, the distribution point hosting the manually copied .pck files can be added to software distribution package source locations at without the need to transfer package source files over the network.

Examining the distmgr.log reveals the following lines and errors:

StoredPkgVersion (x) of package <Package_ID>. StoredPkgVersion in database is x.
SourceVersion (x) of package <Package_ID>. SourceVersion in database is x.

A newer version (x) of package <Package_ID> has already arrived, delete the replication file C:\Program Files\Microsoft Configuration Manager\inboxes\distmgr.box\INCOMING\<GUID>.PKG for version y.

PLEASE NOTE: As of version 1.0.3025.1100, the Preload Package On Site (PreloadPkgOnSite.exe) tool is only supported for standard Software Distribution packages. It is not officially supported for Software Update packages or OSD packages as it was not tested with these types of packages. However, it MAY work with these types of packages, but it is not supported, results may vary, and it cannot be guaranteed to work.

The documentation on the website to download the Preload Package Tool is slightly incorrect. Step 3 specifies to run the tool with the following command:

PreloadPkgOnSite.exe PkgID StoredPkgVersion

This format is incorrect. If we run the tool in this format, we instead get the documentation for the Preload Package Tool (edited to make it more readable and so that it contains only the information that applies to SCCM 2007):

****** Preload Package On Site ******
USAGE: PreloadPkgOnSite.exe <PkgID> [/UpdateStoredPkgVersion <StoredPkgVersion>]

On SCCM2007 Site

with /UpdateStoredPkgVersion option presented

when <StoredPkgVersion> is greater than 0, the StoredPkgVersion will be set to the given value.
when <StoredPkgVersion> is 0, StoredPkgVersion will be set to Package’s SourceVersion

without /UpdateStoredPkgVersion option presented

StoredPkgVersion will be set to Package’s SourceVersion, this is default behaviour.

The correct format to use the tool therefore is:

PreloadPkgOnSite.exe <PkgID> [/UpdateStoredPkgVersion <StoredPkgVersion>]

and not

PreloadPkgOnSite.exe <PkgID> <StoredPkgVersion>

According to this documentation, the value of "StoredPkgVersion" does not always need to be specified, and when it is specified, it should be specified using the /UpdateStoredPkgVersion option. However, this leads to one of the most common causes of the problem, which is that the /UpdateStoredPkgVersion option is not used when it should be used.

Another cause of the problem, and related to the first cause described above, is that when the /UpdateStoredPkgVersion option is used the value of "SourceVersion" is used instead of the value of "StoredPkgVersion". These two values are two completely different values. Their values are usually the same, but they do not have to be the same or equal each other.

The confusion is usually caused because the value of "SourceVersion" can easily be found in the SCCM 2007 Admin console, while the value of "StoredPkgVersion" cannot usually be found in the SCCM 2007 Admin console. The only way of obtaining the value of "StoredPkgVersion" is by either using Reporting Services (part of R2) or by querying the SCCM SQL database using SQL Server Management Studio.

It is important to understand the difference between the values of "StoredPkgVersion" and "SourceVersion". "StoredPkgVersion" is the compressed version of the package (the PCK file), and "SourceVersion" is the uncompressed version of the package. "StoredPkgVersion" holds the value of the version of the PCK file, while "SourceVersion" holds the value of the version of the uncompressed package.

The PCK file can normally be found in the SMSPKG folder on the root level of a drive on the parent site server. The SMSPKG folder should not be confused with the SMSPKG<Drive_Letter>$ folder on the DP server.

The PCK file will not be created until one of the two following actions is taken:

1) The package is pushed to a DP on a child site through normal package deployment (i.e., not using the Preload Package Tool).

2) Checking the option "Use a compressed copy of the source directory" under the "Data Source" tab of the Package properties, and then pushing the package to a DP at the parent site.

Once the PCK file is created, the current version value will be set in the SCCM SQL database as "StoredPkgVersion" in the SMSPackages table. As described in Step 2 of the instructions on the site to download the Preload Package Tool, this PCK file would then need to be copied over to the SMSPKG folder on the root level of the DP server at a child site where the Preload Package Tool is going to be used. If the SMSPKG folder does not yet exist, then it has to be manually created on the root level of one of the drives of the DP server.

Again the SMSPKG folder should not be confused with the SMSPKG<Drive_Letter>$ folder on the DP server, which can also be found on the root level of a drive on the DP server.

According to the documentation, if the /UpdateStoredPkgVersion option is not used, the "StoredPkgVersion" will be set the same as "SourceVersion". If the values do not equal each other in the SQL database, then the Preload Package Tool would set the values incorrectly and the tool would not work as expected.

For example, let’s say for a Package with Package ID CMG00040 the values in the SQL database for "StoredPkgVersion" is equal to 1 and for "SourceVersion" is equal to 3. This means that the version of the PCK file is currently at 1. If we copied over the PCK file to the SMSPKG folder of the DP on the child site and then ran the PreLoadPkgOnSite tool without the /UpdateStoredPkgVersion, then the  tool would set "StoredPkgVersion" of the PCK file it is looking for to 3 since the default behaviour of the tool is that the "StoredPkgVersion will be set to Package’s SourceVersion". We would then see the following message in the DistMgr.log:

StoredPkgVersion (3) of package CMG00040. StoredPkgVersion in database is 3.
SourceVersion (3) of package CMG00040. SourceVersion in database is 3.

Since the "StoredPkgVersion" of the PCK file manually copied over to the server is actually equal to 1, and not to 3, then this is incorrect. If we then pushed Package CMG00040 to the DP, we would then get the error message that we were seeing:

A newer version (3) of package CMG00040 has already arrived, delete the replication file C:\Program Files\Microsoft Configuration Manager\inboxes\distmgr.box\INCOMING\<GUID>.PKG for version 1.

Basically it is saying that it is looking for version 3, but finding version 1, so it cannot continue. Since the version of the PCK file that was manually copied over to the SMSPKG folder is 1, and not 3, then the failure occurs.

Because the value of "StoredPkgVersion" was 1 and "SourceVersion" was 3, the correct format for using the tool in this scenario would have been as follows:

PreloadPkgOnSite.exe CMG00040 /UpdateStoredPkgVersion 1

If the tool was run correctly using the above format, the following would have been displayed in the distmgr.log instead:

StoredPkgVersion (1) of package CMG00040. StoredPkgVersion in database is 1.
SourceVersion (3) of package CMG00040. SourceVersion in database is 3.

The "StoredPkgVersion" and "SourceVersion" being out of sync is normal behavior and can happen under certain circumstances.

The following documents scenarios where "StoredPkgVersion" and "SourceVersion" can get out of sync:

1) The compressed version of the Package (the PCK file) does not get created until you send the package to a remote DP on a child site. If you have updated local DPs on the parent site several times before sending the package to a remote DP on the child site (say 7 times), then the "SourceVersion" is incremented several times and has a value of 7. However "StoredPkgVersion" will not be increased and it will remain at 0 (since it has yet to be created). When you finally send the package to a remote DP at a child site, the compressed PCK file gets created and becomes version 1 and "StoredPkgVersion” receives a value of 1. It does not automatically get set to the same value of "SourceVersion", in this case, 7. In this scenario, "SourceVersion" does not equal "StoredPkgVersion" since "SourceVersion" equals 7 but "StoredPkgVersion" equals 1.

As a side note, the compressed version of the Package (the PCK file) can also be created if the option "Use a compressed copy of the source directory" is checked in the "Data Source" tab of the Package properties, but this is not the default setting.

2) Another scenario where these values can fall out of sync is if the package is removed off of all remote DPs on child sites, but kept on local DPs under the parent site. Let’s say that at the point when the package was removed off of the remote DPs on child sites "StoredPkgVersion" equaled "SourceVersion" and their values was 5. If the package is then updated several times (say 4 times) while only on local DPs at the parent site, the value of "SourceVersion" will increment each time the package is updated and have a value of 9. However "StoredPkgVersion" will not change and still have a value of 5 since there is no need to create a new version of the compressed PCK file since it is not going to be sent to a remote DP on a child site.

If after the updating the local DPs on the parent site 4 times the package is then pushed to the remote DPs on the child sites, only then will the compressed PCK file be updated and the version will be incremented by 1 (not by 4), so the value for "StoredPkgVersion" will go up to 6 (and not 9). In this scenario, "SourceVersion" does not equal "StoredPkgVersion" since SourceVersion" equals 9 but "StoredPkgVersion" equals 6.

Obtaining The Value Of StoredPkgVersion
———————————————————————————
As mentioned earlier, the value of "StoredPkgVersion" cannot be found anywhere in the SCCM 2007 admin console and it cannot be queried on using the standard Reporting Point. However, in R2, Reporting Services can be used to query for the value from within the SCCM 2007 Admin console.

To create a report and query for the value using Reporting Services, under the Reporting – – > Reporting Services node, create a new report. Make sure to make it a SQL-based Report. The SQL query (Command Text) should then be:

Select All
Name,
PkgID,
SourceVersion,
StoredPkgVersion

from
SMSPackages

To view only the packages where "StoredPkgVersion" is not equal to "SourceVersion", run the following query:

Select All
Name,
PkgID,
SourceVersion,
StoredPkgVersion

from
SMSPackages

where
StoredPkgVersion <> SourceVersion

The above SQL queries will generate a report that will show the Package Name, Package ID, Source Version, and Stored Package Version for all of the Packages in the environment.

If R2 or the Reporting Services roles are not installed, the above SQL queries can be used directly in SQL Server Management Studio so that it is not necessary to open the SMSPackages table directly to view the value of "StoredPkgVersion".

The below guides will walk you through setting up Reporting Services in R2:

Configuring SQL Reporting Services: http://technet.microsoft.com/en-us/library/cc431390.aspx

Below is the link for the full documentation for SQL Reporting Services in Configuration Manager 2007 R2

SQL Reporting Services in Configuration Manager 2007 R2: http://technet.microsoft.com/en-us/library/cc431393.aspx

Please note that the Reporting Services role should be installed on the SQL server running the SQL database for SCCM. Please also note that IIS should be installed on the SQL server. Setup and configure IIS as on any other site server. If the server is Windows Server 2008, please make sure to follow the below instructions when setting up IIS:

How to Configure Windows Server 2008 for Site Systems: http://technet.microsoft.com/en-us/library/cc431377.aspx

Summarization:
To summarize, the /UpdateStoredPkgVersion option is necessary and required for the Preload Package Tool (PreloadPkgOnSite.exe) if the "StoredPkgVersion" and "SourceVersion" are not equal.

Additionally, the value of "StoredPkgVersion" cannot be found in the SCCM 2007 admin console unless Reporting Services is installed as part of R2. If R2 or Reporting Services is not installed, then the expected way to obtain the value of "StoredPkgVersion" is via SQL Server Management Studio either by running one of the above SQL queries on the SCCM SQL database or by opening the SMSPackages table of the SCCM SQL database and looking at the value directly.

Unfortunately once the Preload Package Tool (PreloadPkgOnSite.exe) is used once on a DP server on a child site, it cannot be used again. If the tool is attempted to be used again on a DP server where it was used before, the following message will be displayed:

****** Preload Package On Site ******
The compressed package path for package <Package_ID> is already set in the database OR this is the site where the package was created.  There is no need use this tool for this on this site.

What this means is that once the tool is used once, even if used incorrectly, it cannot be used again. The only way to get the Package on the DP server at this point is to delete the package off of the DP via the SCCM 2007 Admin console so that it no longer tries to install the package to the DP server. Once the DP server is showing that the package is not on the DP (under Package Status, Source Version, Targeted, Installed, Retrying, and Failed should all equal 0 for the DP server), push the package to the DP again. However, doing this will cause the compressed PCK package file to be sent through the network. It will not use the existing PCK file on the DP server.

Frank Rojas | Senior Support Engineer