Inside Device Update Agent (Standard 2009)

4/24/2012

Microsoft Corporation

January 2009

Summary

This technical article contains information about how to configure and use Device Update Agent (DUA), an Embedded Enabling Feature that is designed for servicing devices.

Introduction

Overview of Device Update Agent

Configuring the Component in Target Designer

Creating Device Update Agent Scripts

Using DUA and Write Filters

Configuring a Web Server for Remote Polling

Commonly Requested DUA Scenarios

Conclusion

Introduction

One of the important aspects of embedded development is planning for how the device will be updated when it is deployed in the field. The environments that embedded devices are used in are varied, they may be part of an enterprise network, they may be stand-alone devices not connected to any network, or they may be remotely administered devices. Servicing scenarios for embedded devices are therefore varied also.

An enterprise may use Windows Server Update Services (WSUS) or Microsoft System Center Configuration Manager (ConfigMgr) to manage all computers on its network or may service devices through a Web site. Remotely managed devices may be connected to a network share and stand-alone devices may require a technician to apply updates from a CD or USB disk on key.

Overview of Device Update Agent

Device Update Agent (DUA) is an Embedded Enabling Feature that is designed for servicing devices. DUA is a lightweight Win32 service that runs on embedded devices or clients and performs administrative tasks such as copying files, creating registry keys, or executing processes. It is included with the component database and has minimal dependencies. Therefore, it is ideal for smaller footprint devices. The DUA client itself (DUAgent.exe) is only 30KB.

DUA allows for updates to binaries and registry keys on devices that are in the field and being used. It can be used, potentially, to update existing applications or application data, apply hot fixes or system updates, deploy new components or device drivers and automate cleanup and remote device management tasks. Because it can be used without any other "management" infrastructure (such as a centralized server) there are multiple options for configuring the location that the client polls for update scripts to apply. The device can poll a Web server, a network share or a local location such as a floppy, CD or USB drive or another partition on the same device.

The client consumes DUA script files from the polling location. The script files are included together with an update package that contains the files to be bin placed on the target device and/or scripts, batch files or executables to be run. DUA script files can be chained together so that one script will call a second DUA script or point to the next DUA script to be processed later.

Configuring the Component in Target Designer

All the settings that apply to DUA can be configured offline in Target Designer, under the Settings node of the component.

• Service account
  This setting specifies which account permissions to use when you update the device. If Local system is selected then DUA will be able to access any resources on the system. If Administrator is selected the DUA client may be unable to update certain registry keys on the system. For this setting an administrator user account component must be included in the run-time image configuration.

• Run on Start
  This indicates whether DUA should immediately poll for a DUA script the first time that the device starts. If it is selected it will poll on first start and afterwards poll at the date and time configured. If it is not selected it will poll for the first time only at the date and time configured.

• Require HTTP support
  This setting should be checked when a Web server will be the location that DUA should poll. More settings associated with polling a Web server are specified in additional configurable settings that are discussed later in this document.

• Poll interval
  This setting specifies the interval, in seconds, between polls. For example, a value of 60 seconds means that the agent will poll the server one time per minute during each one hour polling session. The polling interval cannot be less than 1 minute nor greater than 1 week.

• Poll jitter
  If this setting is selected it specifies that polling will occur randomly within the polling interval. This is recommended when polling a Web server so that not all the devices poll at the identical time, even if they are all configured to poll within the same polling interval. In other words, with a 60 second polling interval specified one device may poll at 2, 62, 122 seconds and so on and another device would poll the same server at 15, 75, 135 seconds and so on.

• Working directory
  This setting specifies a temporary storage directory on the embedded device that DUA uses when it updates an image. When an update is pulled down to the device the contents of the update package are temporarily stored in this directory until the DUA script is parsed and those updates are applied to the final location in the image. You can specify any working directory and DUA creates it if it does not exist.

  Note

  This setting cannot be left blank or it will result in an error when you build the image in Target Designer.

• Expand working directory using the environment of the embedded device
  This setting specifies whether to use the environment variables in the command file path, when you use the working directory.
  For more information about environment variables, see this Microsoft Web site.

• Poll Time/Day
  This setting specifies the days and hours that you want the client to poll. Anything from a minimum polling schedule of one hour on one day to every hour of every day is supported. It is important to predict the wear on the polled device before you configure the Device Update Agent settings because frequent poll intervals may wear out your hardware (floppy disk or CD-ROM). As all the options are selected by default in Target Designer, it can be cumbersome to manually cancel those options that are not required. This setting, as with all other DUA settings, is written to a registry key and can therefore be configured in several other ways.
  One way is to create a custom component that contains the registry setting that you want. The polling schedule is defined in one hour increments by a mask that indicates which day of the week and a mask that indicates what hour of the day to poll on. The key in question is a Reg_Binary type, with the following structure:

  • An array of up to 7 DWORD "Hour-of-day" masks (one per day) used to indicate the polling schedule.
  • The high byte of the high word (bit 24-31) indicates the day of the week the schedule applies to. There can only be one schedule for any given day.
  • The remaining three bytes (bit 0-23) are used to indicate the hour of the day that polling should occur. Bit 23 represents 00:00 or midnight, bit 0 represents 23:00 or 11PM.
  • Bit 31 is reserved and must be zero.

  

  For example, here is the registry setting in a custom component that specifies polling should occur on Mondays at 1 A.M.

  

  Another way to set this registry key may be to create a DUA script that the client uses as soon as the device starts. In this case the check box in the DUA configurable settings in Target Designer for Run On Start should be checked. The syntax contained within that script is as follows:

  //Set the polling day and time to Monday 1 A.M.
  11,0,HKEY_LOCAL_MACHINE,0,SYSTEM\CurrentControlSet\Services\DUAgent\Parameters\
  Config\,0,PollToD,3,4,32,64,0,0
  

  For more information about Device Update Agent scripts, see Creating Device Update Agent Scripts in this article.

• Select command path type
  This setting specifies polling a local or a remote location. Local polling would be used for polling things such as another hard disk on the computer, a CD, floppy disk or USB key that would hold the DUA scripts. It would also be the option that is used if polling by using a UNC path. This is the default option.

"Remote using HTTP" is used to indicate that a Web server is to be polled. If they are selected then additional configuration settings will be displayed.

• Host Name
  This setting specifies the name and domain of the Web server to connect to. A protocol, such as HTTP, should not be specified here.
• Expand Host Name Using the Environment on the Embedded device
  This setting specifies whether to use the environment variables to expand the name of the server.
• Two additional sections are also visible when "Remote using HTTP" is checked, namely Advanced Settings and Security Settings. These sections contain the settings for configuring things such as HTTP or HTTPS, the host port number, proxy settings, and the user account and credentials to connect to the Web server.
  When you use HTTPS, we recommend that you assign the DUA service a specific username and password on the server. This can be a new account specific to DUA, or an existing account (and make sure that the appropriate user account component is included in the run-time image and has the correct name and password specified). More details about these settings are available in the product Help documentation.

Local polling supports a push model. The DUA script file is delivered to the agent. Polling using HTTP or HTTPS supports a pull model. The agent pulls the file from a server.

• Complete Path to the Command File including File name and Extension
  This setting specifies the path of the DUA script and the name of the first script file.
• Expand Command File Path using the Environment on the Embedded device
  This setting specifies whether to use the environment variables when reading the path of the DUA script file.

Here is an example of the settings for "Local" polling:

Creating Device Update Agent Scripts

Device Update Agent script files are what the DUA client on the device parses in order to understand how to apply the updates that are contained in the accompanying package.

There are four main terms associated with DUA:

• The DUS file is the text file that contains the update information. It is created by the DUA script author, the embedded developer or IT pro administering the system.
• The DUP file is a compiled script file. This is what is positioned at the update location and is consumed by the DUA agent on the deployed device.
• DUSC.exe is the DUA compiler- it runs on the development workstation.
• DUAgent.exe is the service that runs on the embedded device in the field and applies the update to the device.

A DUA script file is basically a series of commands stored in plain text that is then compiled and stored in an encrypted binary format. This is the file that the agent on the device pulls down, parses and applies the actions specified. In order to create this script file to apply an update, you must collect the information about what is being updated, collect the files that are being updated, and also become familiar with the commands that describe to the agent how to apply to update.

For embedded security or optional updates from Microsoft, the information about which registry keys and which files must to be updated are described in the Additional Information document that is included with every update executable package. The updated binaries to apply to the run-time image can be found by expanding the EXE package and looking in the repository. These binaries can be copied to a folder at the poll location and, together with a DUA script, when authored, will form the update package.

DUA Script Syntax

There is a broad command set available when you create DUA scripts. Files can be copied, added and deleted, registry keys can be created or registry values can be changed, executables can be started and the system can be restarted.

Here is an example of a basic DUA script file, created in Notepad, that creates a directory on drive C of the embedded device, and then copies a file from the polling location. In this example the polling location is drive F on this system, either a physical drive, a USB disk, or a drive mapped to a network share, to this new directory.

In this example, you see that every command has several parameters associated with it. Some of these parameters are required and some are optional, indicated by the square brackets, and each parameter is separated by a comma. If optional parameters occur before required parameters an empty placeholder must be inserted into the command string, as the script will walk from one parameter the next checking whether there is a value written. If a placeholder for an optional parameter is omitted, the script will parse the next value that it sees as being the value for the omitted optional parameter and will produce an error. In the example, the command string for CreateDirectory includes empty placeholders for the optional parameters [ErrorMode] and [ExpandMode], and the command string for CopyFile does specify a value for the optional parameter [ErrorMode], but contains an empty placeholder for the second optional parameter [ExpandMode]. All optional parameters that occur after the required parameters can be omitted from the command string. The script will look for any values after the required parameters. If it finds nothing, it will execute the command. If a required parameter is missing, or an empty placeholder is omitted between required parameters, then the script will produce an error either during compilation or during execution.

For more information about the commands that are available for building DUA scripts, see this Microsoft Web site.

Notice that if there are updates to system files that are being used, they require some additional steps as you cannot overwrite them. In this case, you must rename the existing system file, copy the updated system file to the correct location, and then restart the system so that on restart the updated system file would be the one being referenced. Then you can delete the old system file.

Here is an example of the DUA script commands to use:

// Rename the target system file.
MOVEFILE,,,c:\windows\system32\ntdll.dll,,c:\windows\system32\ntdll_old.dll

// Move the new version into the system32 directory.
MOVEFILE,,,c:\duagent\new_ntdll.dll,,c:\windows\system32\ntdll.dll

// Reboot.
REBOOT,,DAREBOOTOPT_REBOOT

// Delete the old version after rebooting.
DELETEFILE,,,c:\windows\system32\ntdll_old.dll

Alternatively you could incorporate a utility such as File-In-Use Replace Utility (Inuse.exe) in your run-time image and execute it from a DUA script command to update files that are being used.

InUse is a command-line tool that performs on-the-fly replacement of files that are currently being used by the operating system. You must be a member of the Administrators group to use this tool. For more information about InUse, see this Microsoft Web site.

Remember that any registry key can be changed on the system, if the account that the DUA service is running under has the appropriate permissions. Therefore, DUA settings themselves can be configured and changed through commands in a DUA script also.

The DUA text file is saved with an extension of .dus.

Compiling DUA Scripts Files

The last step in creating a DUA script file is to compile it. You do this by running the Dusc.exe utility found at \Program Files\Windows Embedded\Bin\Dusc.exe on the development workstation. Before you run this executable for the first time Duscaut.dll must to be registered. This is done in a Command Prompt window with the following command:

Regsvr32.exe <systemdrive>\Program Files\Windows Embedded\Bin\Duscaut.dll

Dusc.exe runs at a command prompt. In Windows Vista this must run as administrator, and accepts a minimum of two parameters, the DUS file to be compiled, and the name of the compiled file.

For example:

Dusc.exe \script1.dus \script1.dup.

The DUP file is included in the same polling location as the updated files that must be applied to the device, and will be pulled or pushed to the device at the next scheduled polling time. When a script is executed it may be deleted from the polling location; for local polling the DUP file will be deleted, for remote polling it will not. Depending on the polling method, you may have to add a command to the end of the script file to instruct the DUA service to look for the next update script when next it polls:

//Change cmd path of next dup file
REGCREATEKEY,,HKEY_LOCAL_MACHINE,,SYSTEM\CurrentControlSet\Services\DUAgent\Parameters\Config\Sessions\0000,DAREG_OPTION_NON_VOLATILE,KEY_ALL_ACCESS

REGSETVALUE,,HKEY_LOCAL_MACHINE,,SYSTEM\CurrentControlSet\Services\DUAgent\Parameters\Config\Sessions\0000,,CmdFile,DAREG_SZ,F:\DUASCRIPTS\script2.dup

For troubleshooting, you may want to include the Event Viewer component in your run-time image so that you can monitor the device update agent’s actions.

Using DUA and Write Filters

There are certain points that should be considered if you are using DUA to update your devices when one of the write filters (File Based Write Filter or Enhanced Write Filter) is also present on the system. If the write filter is enabled and protecting the image then any changes that the update tries to make will not persist on the disk, but will be redirected to an overlay and may be lost on a restart of the device. Different approaches can be taken, depending on what kind of overlay is used (Disk, RAM, or RAM-REG).

Integrating with RAM or RAM-REG overlays

It is good practice to restart your run-time image before you apply updates. This makes sure that you discard any other information that may be in your overlay, but that you may not want to be committed to the disk, for example, user data. There are three options to update devices with a RAM or RAM-Reg overlay:

Run DUA as a background service on the device and let it poll for updates. When you author your DUA script, bracket the update commands with commands to use FBWF Manager or EWF Manager to either disable the filter, or to commit the appropriate files in the overlay, and then re-enable the filter after the update is applied. For example:

// Disable FBWF
EXECUTEPROCESS,,,,c:\windows\system32\fbwfmgr.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

//Run typical update command in this section of the script

// Re-enable FBWF
EXECUTEPROCESS,,,,c:\windows\system32\FBwfmgr.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

Notice that a restart is required to implement disabling and re-enabling the filter as this action only happens at shutdown.

Optionally, you can leave the DUA service disabled on the run-time image. When there is an update available, you can manually disable the filter, start the DUA service, and let DUA to apply the updates. When the DUA update is complete, you can restart the filter.

Additionally, you can use a DUA command in the script to execute a program that uses the filter APIs to enable and disable the filter programmatically.

One thing to note when integrating with an enabled filter is, because the filter is still protecting the partition when it processes the first command until after the next restart, DUA will "forget" that it has already run, for example, Fbwfmgr.exe. The DUP file will also be one of the files that are cleared from the RAM cache. On restarting DUA will find the DUP file again and start to process commands from the top of the DUP file. This causes DUA to run "Fbwfmgr c: -disable" again and restart again. But because the filter is disabled this time, DUA will be able to correctly "remember" its current status after this second restart and the updates that are listed in the next commands will persist.

In this case, if polling locally, the original DUP file will be deleted from the polling location so on restart DUA will not find the DUP file at the polling location to continue processing. In this case, you could use a backup folder and make sure that a copy of the DUP file is in the backup folder. Have the first command in the DUA script copy the file from the Backup folder to the polling location:

//copy dup file back to poll locationso that it is available after reboot
COPYFILE,DAERH_IGNORE,,F:\DUASCRIPTS\BACKUP\ewf.dup,,F:\DUAScripts\ewf.dup,DANO

You can also make the folder that stores the dup files read-only, in a domain environment that has NTFS.

It might be useful to use the -commitanddisable (for RAM\DISK), or -commitanddisable -live (RAM, RAM- REG) commands in your DUA scripts as these reduce restarts.

Integrating with Enhanced Write Filter Disk Overlay

All the same information as File Based Write Filter applies to Enhanced Write Filter if Ram or RAM-REG overlay types are being used. There are some other things to consider if you are using Disk overlays. For example, you may want to reserve your first overlay level for applying your DUA updates. That means that in typical operations, you set your overlay level (setlevel) to level 2 so that any writes by users are written to that overlay level. Then when you must update your development workstation, you have your DUA script first discard any user writes by calling the ewfmgr setlevel command and setting the overlay level to 1, then disabling ewf. At this point, you can apply your updates.

Configuring a Web Server for Remote Polling

If remote polling is used in DUA you have to configure some settings on the Web server. Any existing Web server can be used. You do not have to have a dedicated server just for DUA.

The following actions must be taken:

1. Obtain and install a certificate, if it is necessary.
2. Update the registered MIME types on your Web server to support .dup files.
3. Review the user account that you will use on the run-time images and make sure that this user account is registered on your Web server
4. Make sure that permissions are set correctly for the user account so that it has access to the necessary folders where the DUA scripts will be hosted.
5. Review your DUA configurations to make sure that they match the Web server configurations.

Register MIME Type

Add User Accounts

Set Permissions

There are two permission issues to consider when you use DUA to poll a Web server.

First, make sure that the embedded device can access the .dup files on the server through specifying a user account as mentioned earlier.

Second, make sure that updates can be applied as soon as the .dup file is downloaded to the device. Some registry hives and branches have different access permission, for example, only the system account can access certain branches. Therefore, if you have decided to have the DUA service run under an administrator account then these keys cannot be updated.

For more security, customers should consider using HTTPS when they update a device from a Web server.

Commonly Requested DUA Scenarios

The source for these common scenarios is customer questions in a newsgroup or from a feedback alias. All the things that are listed are technically possible, although not supported. Each scenario may require extensive investigation and testing to be able to work correctly.

• Adding DUA to a device if it was not included at build time
  Adding the Device Update agent to a device that did not first ship with it is a common request from customers. Determine what dependencies DUA has in order to assess whether the existing deployed run-time image can satisfy those dependencies. One way to assess this is to open the existing configuration in Target Designer, turn off auto-resolve dependencies, and then add the Device Update Agent component. Run a dependency check and see what is flagged as missing. If most dependencies for DUA (there are only a few) are already present on your system then it should be fairly easy to collect the necessary files and registry keys for DUA. Manually deploy these changes to the device.
  If a technician is already going to be onsite, then it may be easier to just rebuild and redeploy the whole image.

• Deploy new drivers to a device
  Deploying new drivers to an embedded device can be as easy as creating a .dup file to bin place the INF and SYS in the correct location on the run-time image and then restart. On restarting, PNP should detect the new hardware, install the driver, and setup service registration information. This does not work if there is a required Class Installer missing from the run-time image. For example, a printer driver cannot be installed in this manner if the Printer Class Installer components and libraries were not included in the run-time image at build time.

• Add missing components or features to a device
  To deploy a missing component or feature to the device presents a new level of complexity. The easiest way to approach this task would be to use Target Designer to build an image with just those new features, without running checkdeps first.
  This image would not be bootable and is not designed to be deployed. You can access the file information from the run-time image folders that are created when you build. You can load the hives from the image to find which registry keys were written. It may be just a matter of creating a .dup file that has this information, for simple features such as Regedit.
  However, you want to make sure that your existing run-time image satisfies the dependencies of any feature or component that you are adding. To retrieve the dependency information, open an existing configuration, turn off auto-resolve and then add the new feature, run checkdeps and see what is missing. Then you just repeat your previous steps of creating and building a run-time image with just that new feature and the dependent features to obtain the information for your .dup file.
  The big challenge is if the feature requires complex setup logic handled by FBA, for example running some custom script to populate registry keys such as a RunOnce request, or registering DLLs. Another challenge is that it may be difficult to discover some dependencies, for example WMI. It is very important to thoroughly test your image to make sure that you have not caused any regressions.

• Install Windows XP Professional updates
  It is common for customers to want to be able to consume the approved Windows XP Professional updates from the DQI folder on the ECE site and apply them to the run-time image. It would be necessary to identify which of the dependent components required to support the Windows Sustained Engineering installer are already present on the run-time image and which components must be added, in the way described in the previous section. The components that are required for supporting Windows XP Professional updates are as follows:

  • Client/Server Runtime (Console)
  • Common Control Libraries Version [6.0.0.0]
  • Microsoft Visual C++ Run Time
  • Primitive: Crypt32
  • Primitive: Mpr
  • Primitive: Ntdll
  • Primitive: Ole32
  • Primitive: Oleaut32
  • Primitive: Psapi
  • Primitive: Setupapi
  • Primitive: Shell32
  • Primitive: Userenv
  • Primitive: Version
  • Primitive: Winspool
  • RPC Local Support
  • Windows API - Advanced
  • Windows API - GDI
  • Windows API - Kernel
  • Windows API - User
  • Windows Installer
    If these components are present on your run-time image you can easily create a .dup file to copy the update .exe package and execute it.

  Note

  Windows XP Professional updates obtained from anywhere other than the OEM secure site (ECE) are not licensed for installation on an embedded system.

Conclusion

What you have learned

By using the information that is presented in this technical article you can now configure, script, and use DUA in service your deployed devices.