Updating Devices in the Field by Using Enhanced Write Filter and Device Update Agent

Article
08/28/2006

Aaron Stebner
Microsoft

November 2004

Applies to:
Microsoft® Windows® XP Embedded

Summary: Learn how to update an embedded image in the field that is running Enhanced Write Filter and Device Update Agent. (8 printed pages)

Introduction
What You Need
Configuring EWF
Configuring DUA
Building and Deploying
Using DUAScriptGen to Create a DUS File from a QFE
Adding EWF Commands to the DUS File
Compiling and Deploying the DUP File
Summary

Introduction

Most experienced Microsoft® Windows® XP Embedded system builders and developers know how to build and configure an embedded operating system image by using Target Designer, add new components to an image, and rebuild/redeploy to update devices in the field.

Many of us also know what Enhanced Write Filter (EWF) is and use it to write-protect our embedded devices.

Some of us might use Device Update Agent (DUA) to push individual updates to a device without rebuilding the entire image. However, those of us who do this are well aware of the background knowledge, time, and effort required to create and deploy updates through DUA.

What if we want to use EWF to make our devices read-only, and we want to be able to update these devices without rebuilding our entire master image and redeploying the entire image to the devices? What if we also want to do all of this in a quick and agile way so that we can reduce the turnaround time for applying a critical patch such as a security hotfix (also known as quick-fix engineering [QFE]) to our devices?

This month, we're going to look at the end-to-end process of configuring a write-protected embedded image by using EWF, and then rapidly deploying updates to an image by using DUA after it is deployed and running on a device in the field.

What You Need

Here's a list of the tools you'll need to follow along:

For this example, we are going to create a device that contains EWF with a RAM overlay and DUA configured to poll an HTTP server for update scripts. To get started, let's look at the configuration settings in Target Designer for setting up each of these.

Configuring EWF

To configure EWF, we will add the following components to our runtime image in Target Designer:

Enhanced Write Filter
EWF Manager Console application
EWF NTLDR
EWF application programming interface (API) (This component is optional.)

After adding these components, we can click the Enhanced Write Filter component to change the configuration settings. We will configure a RAM overlay that protects the C partition on our embedded image, which coincidentally is the default setting for the EWF component.

Figure 1: EWF configuration settings for a RAM overlay. Click the thumbnail for a larger image.

Configuring DUA

To configure DUA, we will add the Device Update Agent component to our embedded image in Target Designer, and then click the component to change configuration settings. First, provide a working directory named c:\dua in the Setup Startup and Run time Parameters for DUAgent section.

Figure 2: DUA startup and run-time parameters. Click the thumbnail for a larger image.

Next, click the option to select the Remote using HTTP command path type. This causes some new text boxes to appear. Let's type the cleverly named HTTP server myserver for the host name, and then type the path myduashare/script1.dup for the complete path to the command file. Now, for this example, we want use HTTP instead of HTTPS for our DUA server, so we need to change the default server type setting. Click the link to show advanced settings for DUA, and then click the HTTP option.

Figure 3: DUA command path and advanced settings. Click the thumbnail for a larger image.

Building and Deploying

Now that we have configured EWF and DUA settings, we can add any components we want in our embedded runtime, resolve missing dependencies, and build the image layout.

After the build is complete, we are ready to deploy our image. Remember that to deploy this image after it is built, we will need a small amount of unpartitioned space on our device for EWF to store information about the volumes that it will protect and about the commands to run after any system reboots. Because we are using a RAM overlay, the EWF partition will only take up approximately 64 kilobytes, though it is better to be safe and leave a few megabytes of free space on the device for EWF configuration.

Using DUAScriptGen to Create a DUS File from a QFE

After we deploy our image to the device, we will download a Windows XP Embedded QFE, create a DUA script to install it on our devices in the field, and then deploy the update. To get started, let's go to the Windows XP Embedded Download Center and locate the QFE we want to install. For this example, we will choose a recent Cumulative Security Update for Internet Explorer.

Now that we have located the QFE we want to install, this is where the DUA Script Generator (DUAScriptGen) tool comes in. Every Windows XP Embedded QFE package includes an "Additional Info" document with a list of file and registry changes that are included in the update. DUAScriptGen can be used to translate the files and registry keys into a DUA script (DUS) file. Starting DUAScriptGen for the first time on your development computer will display a dialog box where you can configure DUA server settings that will be used to generate a DUS file that will work in your embedded client/server configuration.

Figure 4: DUA Script Generator options

We will be using an Internet Information Services (IIS) Web server to host our DUA script files, so we will choose to poll an HTTP location and provide the name of our server and a virtual directory. (These values should match the settings that we previously provided in the DUA configuration user interface [UI] in Target Designer).

Clicking OK opens the main DUAScriptGen UI. Now we can download the release notes .rtf file for the QFE, and then click the Convert QFE to DUA button to import the release notes document. You will notice a list of files and registry keys appear on the UI.

Figure 5: DUAScriptGen main window after importing a QFE. Click the thumbnail for a larger image.

After importing the files and registry keys, clicking the Generate Script button will create the DUS file to install these files and update these registry keys.

Adding EWF Commands to the DUS File

Because we are running EWF on our runtime image, we need to disable EWF prior to updating the system and to re-enable EWF when we are finished. We can do this by writing a small application that implements some of the EWF API functions, or by adding some commands to our DUS file to call the EWF Manager Console application.

For this example, let's open the DUS file that we just created by using DUAScriptGen in Visual Notepad .NET 2003 (or your favorite text editor). You will notice a section at the top with a set of HTTPGET commands that will retrieve the updated files from the DUA server location. We can insert the following commands above the first httpget command.

// Disable EWF
EXECUTEPROCESS,,,,c:\windows\system32\ewfmgr.exe,0,c: -disable,DAYES,60000,,DASEC_REV,,,,DASEC_REV,,,,,, c:\windows\system32,1,,WinSta0\Default

// Shut down and restart the system
REBOOT,,DAREBOOTOPT_REBOOT

The first command will call ewfmgr c: -disable to signal EWF to stop protecting drive C after the next reboot, and the second command will tell DUA to reboot the device.

However, there is one subtle trick here — DUA stores information about its state (including which command it should run next from the DUP file) in the registry. The operating system stores the registry as a set of files in c:\windows\system32\config\, assuming we are booted from drive C. Because EWF is still protecting the C partition until after the next reboot, DUA will "forget" that it has already run Ewfmgr.exe and rebooted and will start processing commands from the top of the DUP file after the system reboots. This will cause DUA to run ewfmgr c: -disable and reboot a second time, but because EWF is disabled this time, DUA will be able to correctly "remember" its current status after this second reboot.

So the end result of adding these two commands is that the system will reboot twice, but EWF will be disabled so that patching the files and registry can proceed by using the commands that DUAScriptGen generated for us.

Now, to complete our DUS file, we need to re-enable EWF after the update is complete. To do this, we will need to add the following commands to the end of our DUS file.

// Re-enable EWF
EXECUTEPROCESS,,,,c:\windows\system32\ewfmgr.exe,0,c: -enable,DAYES,60000,,DASEC_REV,,,,DASEC_REV,,,,,, c:\windows\system32,1,,WinSta0\Default

// Shut down and restart the system
REBOOT,,DAREBOOTOPT_REBOOT

One important note here: We need to be aware of how DUA processes DUP files for HTTP polling and author our DUA script accordingly. In HTTP polling scenarios, DUA does not delete the DUP file from the server after it finishes processing the file. Because of this, it is very important to update the registry value that contains the name of the next DUP file that DUA will be polling for as part of each DUA script. In our scenario, DUAScriptGen automatically adds a command to the end of the DUS file to update the next script value for us. We must be sure to place the commands to re-enable EWF after this registry update command for the DUA next script value. Otherwise, DUA will be stuck in an infinite loop of finding and running the same initial script to apply this QFE.

Compiling and Deploying the DUP File

Now that we have finished updating the DUS file to be EWF aware, we are ready to try compiling the DUS file to make sure we did not mistype any of the DUA syntax and to prepare for deploying the QFE. Clicking the Execute Compiler button in DUAScriptGen will do this for us automatically, and if everything went well, we'll see a message telling us that the DUP file was successfully compiled. DUAScriptGen creates the DUP file in a folder named DUA_Files that is a subdirectory of the location where the DUS file was created.

After we compile the DUP file, we have only one step remaining — unpack and install the files for the QFE to our computer so that DUA can use them to patch our devices. We will accomplish this by performing the following steps:

Download the executable file for the embedded QFE to the Web server that we are using for hosting DUA update packages ("myserver" in the earlier example).
Open a command prompt and run the executable file with a command line similar to the following: Q867801_xpe_sp2_x86_enu.exe /x:c:\temp (or any other local folder name) — this will extract the files in the package to a folder structure for us.
Open the folder c:\temp and copy all of the files in the rep folder to the myduashare folder that we previously used in Target Designer and in our DUAScriptGen configuration settings.

Now we can copy the DUP file to the myduashare folder on our Web server next to the set of files that we copied from the rep folder, and be sure to name the file script1.dup to match the name we previously provided for our DUA settings in Target Designer. Our devices will find this DUP file the next time they poll the HTTP location and proceed with disabling EWF, applying the QFE, and re-enabling EWF.

Finally, I recommend that you install the Windows XP Embedded QFE package on your Windows XP Embedded database server so that any images you build in the future will contain the updated files and registry keys. You can do this by double-clicking the QFE executable package and following the steps.

Summary

In this exercise, we reviewed how to configure EWF with a RAM overlay and how to set up DUA to so that you can patch devices in the field. Then, we used the cool DUAScriptGen power toy to create a DUA script to apply a Windows XP Embedded QFE to a device running EWF and DUA without requiring any intervention or access to the devices themselves.