Scripting Trouble-Free Downloads with BITS Michael Murgolo

Many of us in Microsoft Consulting Services spend lots of downloading Figure 1 BITS Features large ISO files and virtual machine images Version Description of Features from our primary file servers in Redmond, Version 2.5 Added support for certificate-based client authentication for secure HTTP and it’s so frustrating to have those down- transports and custom HTTP headers. loads fail when a wireless or remote access Included in the Windows Vista and Windows Server “Longhorn” operat- connection is dropped. And though tools ing system. A redistributable will be available for the Windows Server like and Xcopy can be used in 2003, Windows XP, and SP3 operating systems from the restartable mode, they require manual re- Microsoft Download Center. after a machine restart. Fortunately, The version of %windir%\System32\QMgr.dll is 6.7.xxxx.xxxx. the Background Intelligent Transfer Service Version 2.0 Added support for performing concurrent foreground downloads, us- ing server message block (SMB) paths for remote names, download- (BITS), which is built into Windows XP, ing ranges of a file, changing the prefix or complete name of a remote , and Windows Vista name, and limiting client bandwidth usage. can you easily manage file downloads. Included in Windows XP SP2 and Windows Server 2003 SP1. You can Software and update distribution products also download BITS 2.0 for Windows Server 2003, Windows XP SP1, like Systems Management Server (SMS) Windows XP, Windows 2000 SP4, and Windows 2000 SP3. To download BITS 2.0, go to the Microsoft Download Center and install KB 842773. 2003, Windows Server Update Services, and The version of %windir%\System32\QMgr.dll is 6.6.xxxx.xxxx. Windows Automatic Updates use BITS to Version 1.5 Added upload and upload-reply capability, command-line execution for transfer updates and software to computers events, explicit credentials, and support for Windows 2000. with limited end-user disruption. Included in Windows Server 2003. A redistributable is available for BITS is designed to have minimal im- Windows XP and Windows 2000 SP3 from the Microsoft Download Center. pact on resources; it transfers files using The version of %windir%\System32\QMgr.dll is 6.5.xxxx.xxxx. leftover network bandwidth. So if you’re Version 1.2 Same functionality as version 1.0. Contains internal upgrades and im- using 60 percent of your bandwidth for provements. Included in Windows XP SP1 and Windows 2000 SP3. other tasks, BITS will only use up to the The version of %windir%\System32\QMgr.dll is 6.2.xxxx.xxxx. remaining 40 percent and no . Even Version 1.0 Initial release. Provides prioritised, throttled, and asynchronous down- better, if you get disconnected or need to loads in the background or foreground. The downloads automatically restart your machine, the file transfer does resume after computer restarts and network disconnects. not have to be restarted; when the network Included in Windows XP. connection is re-established, BITS contin- The version of %windir%\System32\QMgr.dll is 6.0.xxxx.xxxx. ues where it left off. You can download files with BITS us- ing a command-line tool called the BITS BITS and Bitsadmin Administration Utility (Bitsadmin), which is Versions Michael Murgolo is a Senior Infrastructure Consultant for found in the Windows Support Tools. With How you use Bitsadmin depends on which Microsoft Consulting Services. He is focused in the areas of Bitsadmin you can achieve “set-and-forget” version of BITS you have installed on your operating systems, deployment, network services, active directo- downloading. In this column I’ll describe operating system. Figure 1 lists BITS - ry, systems management, automation, and patch management. He is a subject-matter expert in the area of desktop deployment how you can use Bitsadmin with a sample sions and features as well as the location of and migration. VBScript to automate BITS jobs. the downloads. TechNet Magazine October 2006 11 fwlink/?linkid=68006. (The Windows XP SP2 Figure 2 Bitsadmin Versions Support Tools version has a known issue Version Bitsadmin Source that does not allow it to be used correctly with the WshShell.Exec Version 2.0 Windows Server 2003 Service Pack 1 32-bit Support Tools go.microsoft. method to capture StdOut.) Windows com/fwlink/?linkid=68006 Vista already has bitsadmin.exe in the OS. Windows XP Service Pack 2 Support Tools go.microsoft.com/fwlink/?LinkId=68007 Due to the quirky syntax of the Bitsadmin Version 1.5 Windows Server 2003 Support Tools SetNotifyCmdLine command syntax, the Windows Server 2003 , Support\Tools folder location of bitsadmin.exe must not have Version 1.2 Windows XP Service Pack 1 Support Tools Windows XP Service Pack 1 CD, Support\Tools folder any spaces in its path. So for this version of the script, the bitsadmin.exe location is Version 1.0 Windows XP RTM Support Tools Windows XP RTM CD, Support\Tools folder hardcoded to %SystemRoot%\system32. You must it there on Windows XP or Windows Server 2003. (It’s already in this Bitsadmin is versioned based on the BITS The Create command creates the BITS location on Windows Vista.) version. Figure 2 shows the version of BITS job in a suspended state. You add files to BITSJob.vbs works in two stages. You use and the source for the corresponding ver- the job with the AddFile command. The it first to create a CMD file, then the CMD sion of Bitsadmin. SetNotifyCmdLine switch lets you define file is used to actually execute the bitsadmin If you’re going to use BITS and scripting a command to launch when the transfer is commands. The remote file or folder needs for your downloading tasks, it’s a good idea to finished. In this case it runs the Bitsadmin to be available when you run the script or have least BITS 2.0 installed. BITS 1.5 and command to Complete the BITS jobs. (A CMD file. The advantage of this is that you later allow an action to be executed after the job must be completed after the transfer can look at the total file count in a remote transfer is complete. BITS 2.0 allows trans- is finished.) The Resume command starts fers from SMB server shares as well as HTTP the download. BITS is designed transfers, so the source file(s) for a BITS job For complete Bitsadmin command syn- to have minimal can be on a file server. BITS 2.0 also includes tax, at a command prompt you should : a new BITS policy setting called Maximum bitsadmin /? impact on resources; Network Bandwidth, which you access in the it transfers files Computer Configuration\Administrative Sample VBScript Templates\Network\Background Intelligent I created a sample VBScript—BITS­ using leftover Transfer Service node of the Job.vbs—to avoid having to create com- network bandwidth. Object Editor. If you have Windows XP mand shell scripts manually with Bitsadmin Service Pack 2 (SP2), Windows Server 2003 commands. You can use the script with folder (shown in the CMD file) to see if SP1, or later, you have at least BITS 2.0. It Bitsadmin.exe to create BITS jobs that there are too many files for BITS to handle is also available as a download for older will download a URL file, a single UNC in one job. Due to limitations of BITS, it is service packs. shared file, or an entire Universal Naming not recommended for jobs with more than Convention (UNC) shared folder. (There 100 files. You can comment out any files you Bitsadmin Commands is no scriptable COM interface to BITS decide not to add to the job. (An optional Now let’s look at a series of Bitsadmin for use in VBScript or other languages, so switch for BITSJobs.vbs lets you execute the commands used to create a BITS job, as Bitsadmin is currently the only tool for CMD file immediately after it is created.) Use shown in Figure 3. The example assumes that scripting BITS.) bitsadmin’s /list or /info switches to check the client computer is running Windows XP To use BITSJob.vbs, first make sure your on the status of your BITS jobs. or Windows Server 2003 with BITS 1.5 or computer has BITS 2.0 or higher. Next, BITSJobs.vbs is available at microsoft.com/ higher, and that bitsadmin.exe is located in you need bitsadmin.exe. If you are using technet/technetmag/code06.aspx. I’ve included a the %SystemRoot%\system32 folder (gen- Windows XP or Windows Server 2003, small CMD file along with the download that erally C:\Windows\system32 by default on use the version from the Windows Server shows examples of the BITSJobs.vbs switch- a new Windows XP installation). 2003 SP1 Support Tools: go.microsoft.com/ es. You can also get help by executing cscript BITSJobs.vbs /? at a command prompt. Figure 3 Bitsadmin Commands For more on BITS, see Background bitsadmin /create myDownloadJob Intelligent Transfer Service in Windows bitsadmin /addfile myDownloadJob http://www.contoso.com/downloads/test.exe C:\Downloads\Test.exe bitsadmin /SetNotifyCmdLine myDownloadJob “%SystemRoot%\system32\bitsadmin.exe” “%SystemRoot%\ Server 2003 at microsoft.com/windowsserver2003/ system32\bitsadmin.exe /complete myDownloadJob “ techinfo/overview/bits.mspx. Also check out technet. bitsadmin /resume myDownloadJob microsoft.com and msdn.microsoft.com. l 12 To get your FREE copy of TechNet Magazine subscribe at: www.microsoft.com/uk/technetmagazine