Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
A feature pack for SMS 2003 called the SMS OSD Feature Pack enables SMS to deploy new operating systems to computers. This version of the SMS OSD Feature Pack does not provide support for downloading this new operating system image to the hard disk of the computer before beginning the upgrade process. Instead, it accesses the OS package files directly from an SMS distribution point. This limits the scalability of the SMS OSD Feature Pack, because it is now constrained by network speeds and distribution point counts.
The process and scripts described in this document show how to enable the downloading of the operating system package files to a computer’s local hard drive in advance of the actual installation of the new operating system. This allows the files to be “pre-staged” on the machines using standard SMS 2003 Advanced Client Download and Execute capabilities, which allow for much greater scalability (given sufficient advanced planning).
Warning The steps described in this document, as well as the changes made by the included scripts, are not supported by Microsoft Product Support Services (PSS). Use at your own risk.
.gif)
.gif){kind=icon}
Introduction
Configuration Process
Scripts Used in this Process
SMS 2003 introduced a new software distribution capability called Download and Execute. This feature uses the Background Intelligent Transfer Service (BITS) capabilities, which were introduced in Microsoft Windows 2000 and later operating systems, to enable files to be retrieved using the Hypertext Transfer Protocol (HTTP). These file transfers can be suspended and resumed, picking up where they left off, thereby allowing for improved resiliency, especially in low-bandwidth situations.
These Download and Execute capabilities are also useful in other situations. For example, if you are installing a large SMS package on many computers, you can “pre-cache” the package contents on the computer before running the package. This is done through the appropriate configuration of an SMS advertisement.
The advertisement start time should be set to an appropriate time in the future.
The mandatory execution date should be set to a time after the advertisement start time.
When the SMS 2003 Advanced Client encounters an advertisement with a future mandatory execution time, it will automatically begin downloading the files required for that advertisement as soon as the advertisement start time has passed.
If you allow enough time between the advertisement start time and the mandatory execution time, a large number of computers could be able to cache the full package content. This allows that same large number of computers to execute the package at the same time without any adverse impact on the network.
Because operating system packages are significantly larger than most packages SMS typically deploys, this capability could be extremely advantageous as long as the following limitations are acknowledged:
The client computers must have enough disk space. The computers must be able to hold the original operating system files, the user state backup (optionally, as it could be stored on the network), and the complete operating system package. (The SMS OSD Feature Pack will remove the old operating system files before expanding the new image.) The SMS 2003 Advanced Client cache size must also be increased so that it is large enough to hold the complete operating system package (which could be gigabytes in size).
The impact on the network must still be considered. All SMS 2003 Advanced Client computers will begin downloading the content as soon as the advertisement start time is reached. If you specify too many computers in the collection, or specify an advertisement start time that occurs at an inappropriate time (for example, in the middle of the work day), the network and SMS servers could be severely overloaded. While this would not cause any issues with the operating system deployment package, it would likely cause other operational issues (for example, slow e-mail access, slow Internet access, or slow delivery of other SMS packages).
Only Windows 2000 and later versions of the operating system support the Download and Execute feature. For Microsoft Windows NT® 4.0 Workstation clients, the content can still be copied to the computer's hard drive and be executed from there, but this can only be done as part of the advertisement execution; no pre-staging can be performed. Also, because Windows NT 4.0 only supports a boot partition of 7.8 gigabytes (GB) or smaller, it is much more likely that there will not be enough disk space to hold the original operating system, user state backup, and the complete operating system package.
Note Proper testing and impact analysis are required. These activities are beyond the scope of this sample.
To use Download and Execute with SMS 2003 operating system packages and advertisements, it is necessary to make modifications to the operating system programs and advertisements directly using the SMS application program interface (API), as the SMS Administrator console specifically prohibits these modifications. The remainder of this sample describes how to make those modifications.
The configuration activities to be performed are as follows:
Defining collections that contain only the computers that meet the requirements. For example, it may be appropriate to select only those computers running Windows 2000 or later with at least 2 GB of free disk space (assuming all of those machines meet the requirements for the operating system package being deployed, such as processor speed or memory).
Configuring the SMS 2003 Advanced Client cache size so that there is enough capacity to store the operating system package.
Configuring the operating system program and advertisement being used to deploy the operating system package to the collection of computers defined in the previous activity.
Because not all computers will have enough disk space to cache the complete operating system package, it is necessary to create a computer collection that contains only those that can. This can be done using the following steps:
Create a new collection called Deploy Windows XP with Download and Execute (or other suitable name).
On the Membership tab, click the cylinder icon to create a new query rule named Windows 2000 with sufficient disk space (or other suitable name).
Edit the query statement to select only those computers running Windows 2000 and those with more than 2 GB of free disk space. (Assuming that the operating system package is at most 1.5 GB, allow about 500 megabytes (MB) for “scratch space” and day-to-day functionality.)
The query rule should look similar to Figure 1.
.gif)
Figure 1. Sample query rule
Or, looking at the query language, the rule should look like Figure 2.
.gif)
Figure 2. Sample query language
The exact requirements will vary for each customer. Be sure to verify that the collection contains the appropriate results before continuing with the following steps.
Typically, an SMS 2003 Advanced Client is configured with a cache size of between 256 MB and 512 MB. This will not be sufficient for most operating system packages, which can range in size from 500 MB to several gigabytes. To support these packages, the maximum size of the cache needs to be increased. To do so, complete the following steps:
Create a directory containing a Microsoft Visual Basic® Scripting Edition (VBScript) that changes the cache size.
Use this directory to create a new package. In this package, create a program that runs the VBScript. Push this package to all SMS distribution points.
Distribute this script to the collection of computers defined in the previous section by creating a mandatory advertisement for the new package. (This package must run before the operating system package.)
The VBScript code shown in Listing 20 is required to change the cache size.
Listing 20. VBScript Required to Change the Cache Size
Set ui = CreateObject("UIResource.UIResourceMgr")
Set cacheInfo = ui.GetCacheInfo
cacheInfo.TotalSize = 2000 ' Change maximum size to 2GB (approx)
Note that this should make the cache size bigger than just what is required for the operating system package. In this example, assume the previous cache size was 500 MB and the operating system package is 1500 MB; this script makes the new cache size big enough to hold the 500 MB of existing content and the new 1.5 GB operating system package. This allows for other packages to reside in the cache at the same time, which may be required depending on how long the operating system package will be present in the cache (which in turn depends on the difference between the advertisement start date and the mandatory advertisement date) and how many other mandatory packages have recently run or will soon run from the cache.
To enable an SMS 2003 operating system package to support Download and Execute, first create the operating system package using the standard steps (capturing a .wim file, creating the package from that file, defining an operating system program with the necessary settings and custom actions, and so on). You should also create an advertisement for this package, but do not yet target the full collection. Instead, target an empty collection; this collection can be used for testing purposes. When testing is complete, a new advertisement can be created for the full collection (being very careful to specify the appropriate advertisement start time and mandatory advertisement time).
Two scripts have been provided to enable Download and Execute support:
ZTICache.vbs. This script is used as a front end to the SMS OSD Feature Pack program executable, osdlaunch.exe. It ensures that the cached package content is moved to a safe location, C:\MININT\PackageSource, before running osdlaunch.exe. It also protects this content so that osdlauch.exe cannot remove it during its normal cleanup of the C:\MININT directory structure.
ZTICacheUtil.vbs. This script makes SMS API calls to modify existing operating system program and advertisement objects to enable the ZTICache.vbs front end (described above) and to enable Download and Execute on the advertisement. Note that you will not be able to see these modifications in the SMS Administrator console; it will continue to show that Run from distribution point is enabled, even when Download from distribution point has been configured.
These files should be copied to an accessible location on the server (for example, \\SERVER1\ZTI\) where the SMS Administrator console can access them using a Universal Naming Convention (UNC) path.
To make the necessary changes, the ZTICache.vbs script must first be added as a required file to an existing custom action (for example, the BDD Zero Touch Installation - Validation custom action). This will cause the SMS OSD Feature Pack to include this file in the package directory (required as this script is executed when the operating system program is first started by the advertisement). When the file is added, all distribution points for the package must be updated.
After the ZTICache.vbs script has been added, the operating system program and advertisement objects can be modified using the ZTICacheUtil.vbs script. Listing 21 shows how to use the script to enable Download and Execute on SMS advertisement XXX20001; this will also cause the associated operating system program to be modified to run ZTICache.vbs.
Listing 21. Command to Run ZTICacheUtil.vbs
cscript.exe ZTICacheUtil.vbs /server:SERVER1 /advertisement:XXX20001 /enable:true
Output similar to Listing 22 should be produced.
Listing 22. Sample Output from Running ZTICacheUtil.vbs
Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. Connecting to SMS provider server SERVER1 and site MTN. Retrieving advertisement object for advertisement XXX20001. Enabled download and execute on advertisement XXX20001. Retrieving program object for package XXX00001 and program Install XP. Enabled ZTICache.vbs on package XXX00001 program Install XP. Be sure to include ZTICache.vbs in the OS package by including it as a required file on at least one custom action. OS Package ID: XXX00001 OS Package Name: XP Master OS Program Name: Install XP OS Program command line: wscript //b ZTICache.vbs OS Program cache enabled: True OS Advertisement ID: XXX20001 OS Advertisement flags: 48 Download enabled: True
Remember that modification to the operating system program affects all advertisements that use this program, so modify only a program that is being used solely for Download and Execute support. This may require creating a second program on the operating system package.
To undo the changes that are made to support Download and Execute, reconfigure both the advertisement and the operating system program, as shown in Listing 23 (substituting the appropriate advertisement ID, package ID, and program name).
Listing 23. Undoing Changes Made to Support Download and Execute
cscript.exe ZTICacheUtil.vbs /server:SERVER1 /package:XXX00001 /program:"Install XP" /enable:false cscript.exe ZTICacheUtil.vbs /server:SERVER1 /advertisement:XXX20001 /enable:false
For more information about ZTICacheUtil.vbs, you can run the script with no parameters. It will display a usage statement, as well as information about every operating system package, program, and advertisement currently defined on the specified SMS server.
When Download and Execute has been enabled on an operating system program and advertisement, it should be tested. This can be done by adding one or more computers (preferably test computers) to the empty collection created above.
When you are satisfied with the results, an advertisement can be created for the main query-based collection. Be careful to specify an appropriate future time for the advertisement start date; ideally, this should be a time when clients would not notice the network impact (for example, Friday night at midnight). Also, remember that clients will not begin downloading the content until the advertisement is mandatory, so add an appropriate mandatory assignment date.
We at Microsoft Corporation hope that the sample scripts (ZTICacheUtil.vbs in Listing 24 and ZTICache.vbs in Listing 25) are valuable to you. Your use of the sample scripts listed below, however, is at your sole risk. The sample scripts are provided “as is,” without any warranty, whether express or implied, of its accuracy, completeness, fitness for a particular purpose, title or noninfringement. Microsoft Corporation shall not be liable for any damages you may sustain by using the sample scripts, whether direct, indirect, special, incidental, or consequential, even if it has been advised of the possibility of such damages.
Listing 24 contains the source code to ZTICacheUtil.vbs. Copy and paste the code listed in Listing 24 to a text editor and save it as ZTICacheUtil.vbs.
Listing 24. Source Code to ZTICacheUtil.vbs
Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.
'//--------------------------
-------------------------------------------------
'//
'//
'// File: ZTICacheUtil.vbs
'//
'// Input: none
'//
'// Return: 0 = Success, anything else indicates failure
'//
'// Purpose: By default, the OS Deployment Feature Pack
does not support
'// "download and execute" with OS packages.
This script enables
'// that support in two ways:
'//
'// 1. By modifying the OSD advertisement to
enable "download and
'// execute". By default, the SMS Administrator
Console will
'// prevent this. (Even after the script changes
this through
'// the SMS APIs, the GUI will still show
that it is not enabled.)
'//
'// 2. By modifying the OSD program to run the
ZTICache.vbs
'// script which ensures that the locally-cached
OSD package files
'// are kept in a safe location, C:\MININT\PackageSource.
(This
'// can be done even without
enabling "download and execute" on
'// the OSD advertisement; in this case,
the ZTICache.vbs script
'// will copy the OSD package files
from the distribution point
'// directly to C:\MININT\PackageSource.
See the ZTICache.vbs
'// script for more details.)
'//
'// This script is driven by command line
parameters. It assumes
'// that the script is being run by someone
with the necessary SMS
'// permissions to modify package, program,
and advertisement objects.
'// It also assumes that the user knows the
package ID, program name,
'// and advertisement ID of the objects that
they want to modify, as
'// well as the server name of the SMS site
owning those objects.
'//
'// This script also requires Windows Scripting Host 5.6.
'//
'//------------------------------------------
---------------------------------
' Initialization
Set sh = CreateObject("WScript.Shell")
Set argsNamed = WScript.Arguments.Named
Set oLocator = CreateObject("WbemScripting.SWbemLocator")
' Get parameters
sServer = UCase(argsNamed("server"))
sPackage = UCase(argsNamed("package"))
sProgram = argsnamed("program")
sAdvertisement = UCase(argsNamed("advertisement"))
sEnable = UCase(argsNamed("enable"))
If argsNamed.Count = 0 then
WScript.Echo ""
WScript.Echo "USAGE:"
WScript.Echo ""
WScript.Echo WScript.ScriptName &
" [/server:<serverName>]
[/package:<packageID>]" &_
" [/program:<programName>]
[/advertisement:<advertisementID>]
[/enable:<true|false>]"
WScript.Echo ""
WScript.Echo "Options:"
WScript.Echo VBTAB & "/server:
SMS server name (Default=This server)."
WScript.Echo VBTAB & "/package:
OS package ID (Default=Null)."
WScript.Echo VBTAB & "/program:
OS program name (Default=null)."
WScript.Echo VBTAB & "/advertisement:
OS advertisement ID (Default=null)."
WScript.Echo ""
WScript.Echo "Examples:"
WScript.Echo ""
WScript.Echo WScript.ScriptName &
" /advertisement:XXX20001 /enable:true"
WScript.Echo WScript.ScriptName &
" /package:XXX00001
/program:""Install XP"" /enable:true"
WScript.Echo ""
End if
' Connect to SMS provider
Set oServices = oLocator.ConnectServer(sServer, "root\sms")
Set oProviderLocation = oServices.ExecQuery("select * from
SMS_ProviderLocation where ProviderForLocalSite = 1")
For Each o In oProviderLocation
sProviderServer = o.Machine
sProviderSite = o.SiteCode
Next
Set oServices = Nothing
WScript.Echo "Connecting to SMS provider server " &
sProviderServer &_
" and site " & sProviderSite & "."
Set oServices = oLocator.ConnectServer(sProviderServer,
"root\sms\site_" &_
sProviderSite)
' See what we need to do
If sAdvertisement <> "" then
' Get the specified advertisement
WScript.Echo "Retrieving advertisement
object for advertisement " &_
sAdvertisement & "."
Set oAdvert = oServices.Get
("SMS_Advertisement.AdvertisementID='" &_
sAdvertisement & "'")
' Modify the program as appropriate.
Select Case sEnable
Case "YES", "TRUE"
If oAdvert.RemoteClientFlags <> 48 then
oAdvert.RemoteClientFlags = 48
oAdvert.Put_
WScript.Echo "Enabled download and execute
on advertisement " &_
sAdvertisement & "."
' Force the package and program to be checked if
no other values were specified.
If sPackage = "" and sProgram = "" then
sPackage = oAdvert.PackageID
sProgram = oAdvert.ProgramName
End if
End if
Case Else
If oAdvert.RemoteClientFlags <> 40 then
oAdvert.RemoteClientFlags = 40
oAdvert.Put_
WScript.Echo "Disabled download and execute
on advertisement " &_
sAdvertisement & "."
End if
End Select
End if
If sPackage <> "" and sProgram <> "" then
' Get the specified program
WScript.Echo "Retrieving program object
for package " & sPackage &_
" and program " & sProgram & "."
Set oProgram = oServices.Get
("SMS_Program.PackageID='" & sPackage &_
"',ProgramName='" & sProgram & "'")
' Modify the program as appropriate.
Select Case sEnable
Case "YES", "TRUE"
If oProgram.CommandLine <>
"wscript //b ZTICache.vbs" then
oProgram.CommandLine = "wscript //b
ZTICache.vbs"
oProgram.Put_
WScript.Echo "Enabled ZTICache.vbs
on package " & sPackage &_
" program " & sProgram & "."
WScript.Echo "Be sure to include ZTICache.vbs
in the OS package by including it as a"
WScript.Echo "required file on at
least one custom action."
End if
Case Else
If oProgram.CommandLine <> "osdlaunch.exe" then
oProgram.CommandLine = "osdlaunch.exe"
oProgram.Put_
WScript.Echo "Disabled ZTICache.vbs
on package " & sPackage &_
" program " & sProgram & "."
End if
End Select
End if
' Finally, report on the current state
Set oPackages = oServices.ExecQuery("select *
from SMS_Package where ImageFlags = 1")
For each oPackage in oPackages
WScript.Echo " "
WScript.Echo "OS Package ID:
" & oPackage.PackageID
WScript.Echo "OS Package Name:
" & oPackage.Name
Set oPrograms = oServices.ExecQuery("select
* from SMS_Program where PackageID = '" &_
oPackage.PackageID & "'")
For each oProgram in oPrograms
WScript.Echo " OS Program Name:
" & oProgram.ProgramName
WScript.Echo " OS Program command line:
" & oProgram.CommandLine
If Instr(oProgram.CommandLine, "ZTICache.vbs") > 0 then
bEnabled = true
Else
bEnabled = false
End if
WScript.Echo " OS Program cache enabled:
" & bEnabled
Set oAdverts = oServices.ExecQuery("select *
from SMS_Advertisement where PackageID = '" &_
oProgram.PackageID & "' and ProgramName =
'" & oProgram.ProgramName & "'")
For each oAdvert in oAdverts
WScript.Echo " OS Advertisement ID:
" & oAdvert.AdvertisementID
WScript.Echo " OS Advertisement flags:
" & oAdvert.RemoteClientFlags
If oAdvert.RemoteClientFlags = 48 then
bDownloadEnabled = true
Else
bDownloadEnabled = false
End if
WScript.Echo " Download enabled:
" & bDownloadEnabled
' Sanity check
If bDownloadEnabled and (not bEnabled) then
WScript.Echo " "
WScript.Echo "Warning: ZTICache.vbs
must be enabled on " &_
oPackage.PackageID & " and " &
oProgram.ProgramName
WScript.Echo "in order for download and
execute to be successful for advertisement " &_
oAdvert.AdvertisementID & "."
WScript.Echo " "
End if
Next
Next
Next
' Cleanup
Set oServices = Nothing
Listing 25 contains the source code to ZTICache.vbs. Copy and paste the code listed in Listing 25 to a text editor and save it as ZTICache.vbs.
Listing 25. Source Code to ZTICache.vbs
Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.
'//---------------------------
------------------------------------------------
'//
'//
'// File: ZTICache.vbs
'//
'// Input: none
'//
'// Return: Return code from OSDLaunch.exe (0 = Success)
'//
'// Purpose: By default, the OS Deployment Feature
Pack does not support
'// "download and execute" with OS packages.
This script is
'// designed to enable this by moving or
copying the OS package
'// files to a safe location on the hard drive,
C:\MININT\PackageSource,
'// where they will not be removed when OSD
cleans the hard drive.
'// After doing this, it will run OSDLaunch.exe
to kick off the
'// normal OSD process. But because OSDLaunch
"cleans" the C:\MININT
'// directory when it starts, the script must
also protect the
'// contents of the C:\MININT\PackageSource
directory. It does
'// this by opening all the files in the directory,
which prevents
'// their deletion because they are in use.
'//
'// If the OSD advertisement has been set to
enable "download and execute",
'// the package files (and this script) will be
in the SMS advanced client
'// cache directory (typically "%WINDIR\System32
\ccm\cache\<package>"). In
'// order to prevent there being two copies
of the files on the hard drive,
'// the files are moved to C:\MININT\
PackageSource instead of copied.
'//
'// If this script is run on an NT 4.0
workstation (through the same OSD
'// advertisement), "download and execute"
is not available. However, the
'// script will still copy the files to the
hard drive before initiating
'// the OSD process. This at least enables
some of the benefits of
'// download and execute for NT 4.0 client.
'//
'// This script is inserted into an existing
OSD program by the
'// ZTICacheUtil.vbs script. See that script
for further information.
'// This script must be added to one of the
OSD custom actions as
'// a required file so that it is included
in the OSD package files.
'// After doing this, the distribution points
need to be updated.
'//
'//---------------------------------------------
------------------------------
' Initialization
Set fso = CreateObject("Scripting.FileSystemObject")
Set sh = CreateObject("WScript.Shell")
' Find the directory we are running from
- that's the source.
sCacheDir = fso.GetParentFolderName
(WScript.ScriptFullName)
' Create the OSD directory structure
If not fso.FolderExists("C:\MININT") then
fso.CreateFolder "C:\MININT"
End if
If fso.FolderExists("C:\MININT\PackageSource") then
fso.DeleteFolder "C:\MININT\PackageSource", true
End if
fso.CreateFolder "C:\MININT\PackageSource"
' If we are running from a local path, move the
contents to the PackageSource directory.
' Otherwise, just copy it. (When running from a
local path, SMS must have already copied
' the files locally using BITS.)
If Left(sCacheDir,2) = "\\" then
fso.CopyFile sCacheDir & "\*.*",
"C:\MININT\PackageSource\", True
sh.LogEvent 0, "Copied files in " & sCacheDir
For each f in fso.GetFolder(sCacheDir).Subfolders
sh.LogEvent 0, "Copying folder " & f.Path
fso.CopyFolder f.Path, "C:\MININT\PackageSource\", true
Next
Else
fso.MoveFile sCacheDir & "\*.*",
"C:\MININT\PackageSource\"
sh.LogEvent 0, "Moved files in " &
sCacheDir
For each f in fso.GetFolder(sCacheDir).
Subfolders
sh.LogEvent 0, "Moving folder " & f.Path
fso.MoveFolder f.Path,
"C:\MININT\PackageSource\"
Next
End if
' Log the count of files in the folder
sh.LogEvent 0, "Files in C:\MININT\PackageSource folder: " &_
fso.GetFolder("C:\MININT\PackageSource").Files.Count
' Because OSDLaunch will "clean up" the C:\MININT
directory, we need to keep the package
' source files from being deleted in the process.
Open each one of them and keep them open
' until OSDLaunch.exe completes.
sh.LogEvent 0, "Opening C:\MININT\
PackageSource files"
Set oFiles = CreateObject
("Scripting.Dictionary")
For each f in fso.GetFolder
("C:\MININT\PackageSource").Files
Set oFile = fso.OpenTextFile(f, 1)
oFiles.Add f, oFile
Next
For each s in fso.GetFolder
("C:\MININT\PackageSource").SubFolders
For each f in s.Files
Set oFile = fso.OpenTextFile(f, 1)
oFiles.Add f, oFile
Next
Next
' Run OSDLaunch.exe from the new directory.
It will try to clean up C:\MININT, but the
' open files will keep that from causing problems.
OSDLaunch will then install OSDAgent
' as a service and that will drive the
rest of the process.
sh.LogEvent 0, "Setting working directory"
sh.CurrentDirectory = "C:\MININT\PackageSource"
sh.LogEvent 0, "Running OSDLaunch"
rc = sh.Run("OSDLaunch.exe", 0, true)
sh.LogEvent 0, "Return code from
OSDLaunch = " & rc
' Quit with the return code from OSDLaunch.
The files will automatically be closed.
WScript.Quit rc
Download
Get the Microsoft Solution Accelerator for Business Desktop Deployment 2007
Update Notifications
Sign up to learn about updates and new releases
Feedback