A Deep Dive into First Boot Agent (Standard 2009)

4/24/2012

Microsoft Corporation

January 2009

Summary

During setup, any Windows operating system must execute several initialization tasks. As soon as the initial setup is complete and various registry keys are set up, the operating system is ready for use. These tasks or instructions only have to be executed one time. Examples include creating user profiles, setting up various device drivers, and registration of DLLs.

Like other Windows operating systems, this one-time setup is required to install Windows Embedded Standard run-time images. This process in Windows Embedded Standard is called First Boot Agent (FBA). This article describes the finer points of FBA.

Introduction

FBA Overview

FBA Architecture

• FBA Files
• FBA Registry Key
• FBA Components
• FBA Phases
• EEF Phases

FBA Commands

RegMigrate Key

Troubleshooting FBA

Common FBA Errors

Conclusion

Introduction

The following sections list the prerequisites and objectives for this content.

Prerequisites

• Hands-on experience using the Windows Embedded Standard tool set
• Creating a basic component using Component Designer
• Importing a component to the Windows Embedded Standard Database using Component Database Manager
• Creating a Windows Embedded Standard run-time image using Target Designer
• Deploying a Windows Embedded Standard run-time image on an active partition.

Objectives

• Basics of FBA
• FBA architecture
• Various files that are used during FBA Process
• Registry keys used during FBA
• Phases of FBA
• Commands that are available for FBA
• Common errors found during FBA

FBA Overview

FBA is the feature that controls the setup of a Windows Embedded Standard operating system. FBA consists of a set of processes that run on the Windows Embedded Standard run-time image when it first starts. FBA reads and executes special commands from the System Registry. These commands or instructions come from individual components that are included in the run-time image configuration when it was created in Target Designer. As soon as FBA has finished execution, it cleans up itself and restarts the computer. There may be more than one restart during FBA that depends on whether the system is configured to be cloned for mass deployment. More information on cloning and deployment can be found at this Microsoft Web site.

FBA also executes onetime operations that might be done only after the OS has completed either part or all of the setup. Components can issue commands to be executed during specific times during the setup process. Phase number is used by FBA to set the order that directives are to be processed. It runs a collection of tasks at specified phases. Tasks are executed by the controlling library (Fbalib.dll).

The operations executed by FBA can be outlined as follows:

• DLL registration
• Registering COM objects needed by the application
• Security installation
• Catalog registration
• Plug and Play enumeration
• Network configuration
• User profile initialization
• Optional component installation
• Setting up device data for the device drivers
• Online configuration for Windows Embedded Standard run-time images such as creating shortcuts, moving files, and registry keys

The operations executed during FBA are logged at [DRIVE]:\Windows\FBA\FBALOG.txt. This log should be inspected after FBA finishes, in order to find any errors that occurred during any of the phases.

Pre and post FBA Images

References are frequently made to pre-FBA and post-FBA images. A pre-FBA image is the image that is created by Target Designer but has not been deployed to a device.

A post-FBA image refers to the image on the device after FBA has finished. At this point the system is ready for use.

FBA Architecture

The following sections provide information on FBA architecture.

• FBA Files
• FBA Registry Key
• FBA Components
• FBA Phases
• EEF Phases

FBA Files

FBA is not a single executable, but a collection of executables that are called by a controlling DLL. This controlling DLL calls a separate FBA executable to handle each kind of FBA directive.

FBA is started by Fbastart.exe that runs early in the boot process. It replaces the non-*.SAV hives with *.SAV hives and sets RestartSetup flag to TRUE in HKLM\System\Setup -RestartSetup. For more information about registry hives in Windows, see this Microsoft Web site.

At the end of setup, Fbastart.exe is removed from the BootExecute key.

The following files are used by the FBA process:

• Fba.exe
  Calls Fbalib.dll to performs run-time image tasks
• Fbapnp.dll
  Performs Plug and Play detection
• Fbanet.dll
  Installs net protocols, domain SID and participation, protocol binding
• Fbasec.dll
  Configures system security database
• Fbacert.dll
  Installs cryptographic support and system catalogs
• Fbareg.dll
  Performs DLL registration and processes RunOnce keys
• Fbaprof.dll
  Initializes system profiles
• Fbaocm.dll and Fbaoc.exe
  Integrates optional components in the setup process

The following diagram shows the files responsible for FBA process

FBA Registry Key

All the FBA directives are stored in the registry key:

HKLM\SYSTEM\CurrentControlSet\Control\WindowsEmbedded\FBA

This registry key holds all the tasks that FBA must execute during setup. These commands are populated by individual components in Target Designer while you are building the Windows Embedded Standard run-time image.

FBA Components

As we have seen from the previous sections, that FBA process is executed by a set of files that use a set of registry keys and DLL/COM registration in several defined phases. All the files, registry keys, and DLL/COM registration resources are contained in Windows Embedded Standard within several different components. The most important resource these components contain is the DLL/COM registration information that defines the phase of an FBA operation. The file and the DLL/COM registration information are given here to explain the phases of FBA in the following section.

These components are as follows:

• First Boot Agent (FBA)
  Files:
  • Fba.exe
  • Fbalib.dll
  • Fbareg.dll
  • Fbastart.exe
    DLL/COM Registrations:
  • FBAInitialize (Phase 1000)
  • FBAStep1 (1100)
  • FBASetSetupInfo (1200)
  • FBAResetSetup (8000)
  • FBASaveAndReplaceSystemHives (8500)

• FBA: Crypto
  This component provides cryptographic support for First Boot Agent (FBA).
  Files: None
  DLL/COM Registrations: None

• FBA: Driver Signing
  This component provides driver signing support for First Boot Agent (FBA).
  Files:
  • Fbacert.dll
    DLL/COM Registrations:
  • FBAInstallCrypto (Phase 1300)

• FBA: Net Common
  This component provides shared resources for First Boot Agent (FBA) networking support.
  Files:
  • Fbanet.dll
    DLL/COM Registrations:
  • FBAInstallNetworking (Phase 3550)
  • FBAJoinWorkgroup (Phase 3900)
  • FBASetDomainSid (Phase 3700)

• FBA: Optional Components
  This component provides optional support for First Boot Agent (FBA).
  Files:
  • Fbaoc.exe
  • Fbaocm.dll
    DLL/COM Registrations:
  • FBALaunchOCM (Phase 5550)

• FBA: PnP
  This component provides user-mode Plug and Play support for First Boot Agent (FBA).
  Files:
  • Fbapnp.dll
    DLL/COM Registrations:
  • FBAInstallPnpClassInstallers (Phase 3000)
  • FBAInstallPnpDevices (Phase 3100)

• FBA: SCE
  This component provides Security Configuration Engine (SCE) support for First Boot Agent (FBA)
  Files: None
  DLL/COM Registrations:
  • FBAInstallSecurityPhase1 (Phase 1600)
  • FBAInstallSecurityPhase2 (Phase 1600)

• FBA: SysSetup
  This component provides system setup support for First Boot Agent (FBA).
  Files: None
  DLL/COM Registrations: None

FBA Phases

FBA calling order for each action depends on the phase set for that task in the component. Phase numbers can be from 0 to 65,535. Phases from 0 to 8500 are reserved for FBA. This table shows the common phases during FBA.

FBA Operation	Phase
FBAInitialize	1000
FBAStep1	1100
FBASetSetupInfo	1200
FBAInstallCrypto	1300
FBAInstallSecurityPhase1	1600
FBAInstallSecurityPhase2	1600
FBAInstallPnpClassInstallers	3000
FBAInstallPnpDevices	3100
FBAInstallNetworking	3550
FBASetDomainSid	3700
FBAJoinWorkgroup	3900
FBALaunchOCM	5550
FBAResetSetup	8000
FBASaveAndReplaceSystemHives	8500

This diagram shows two additional phases, those for System Cloning and the Write Filters. These phases may not always apply to an image.

Example:

Phase 1600 -FBAInstallSecurityPhase1

 

 

From a sample FBA Log the phases can be easily distinguished.

Phase 0:

11:30:01 AM - [FBASetProgressText] Setting PNP Flag...

11:30:08 AM - [FBASetProgressText] Initializing...

11:30:08 AM - [CallEntryPointThread] C:\WINDOWS\FBA\FBALIB.DLL, FBAInitialize

11:30:08 AM - [FBASetProgressText] Setting SystemPrefix...

Phase 1600:

11:30:16 AM - [CallEntryPointThread] C:\WINDOWS\FBA\FBASEC.DLL, FBAInstallSecurityPhase1

11:30:16 AM - [FBASetProgressText] Registering Components...

11:30:16 AM - [CallEntryPointThread] C:\WINDOWS\system32\atl.dll, DllRegisterServer

11:30:16 AM - [CallEntryPointThread] C:\WINDOWS\system32\txflog.dll, DllRegisterServer

Phase 2000:

11:30:19 AM - [CallEntryPointThread] C:\WINDOWS\FBA\FBAREG.DLL, FBARegisterDLLsPhase1

11:30:19 AM - [FBASetProgressText] Installing Components...

11:30:19 AM - [FBASetProgressText] Registering Class Installers...

11:30:19 AM - [FBAStartService] PlugPlay -> Waiting...

11:30:20 AM - [FBAStartService] PlugPlay -> Running

11:30:20 AM - [FBAStartService] PlugPlay -> Finished Waiting

Phase 3000:

11:30:26 AM - [CallEntryPointThread] C:\WINDOWS\FBA\FBAPNP.DLL, FBAInstallPnpClassInstallers

11:30:27 AM - [FBAStartService] PlugPlay -> Already Running

11:30:27 AM - [FBASetProgressText] Installing PNP Devices...

11:30:28 AM - [FBAAddDevInstanceId] ROOT\SYSTEM\0001

EEF Phases

Windows Embedded Standard also includes the Embedded Enabling features Enhanced Write Filter, File Based Write Filter and Registry Filter. They are set up during a later phase of FBA because they require all other aspects of FBA to be complete in order to function correctly. Details of the different phases for these features are as follows:

Enhanced Write Filter (EWF)

• FBA Phase - 65520
• The phase is high so that FBA runs the setup commands for the filter after System Cloning is performed.

File based-write filter (FBWF)

• FBA Phase - 65520
• The phase is high so that FBA runs the setup commands for the filter after System Cloning is performed.
• As a post installation process FBA starts fbwfcfg.exe which reads the user-defined FBWF settings and configures the filter driver.
  These settings are contained in the registry key HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\FBWF\FBA\
  • EnablePostFBA
  • ThresholdSize
  • CacheType
  • VirtualSizeDisplay
• Additional settings, such as specifying protected partitions and files and folders in the exclusion list can be configured at this point.
  The following actions are also taken based on user selected options:
  • Setting the paged pool size
  • Disabling the pagefile
  • Enable/disable defragment
  • Disable/enable low disk warning
  • Disable/enable System Restore Disable
  • Integration tasks such as adding registry ram disk to the write through list

RegFilter

• Phase - 65010
• The phase is high so that FBA runs the setup commands for the filter after System Cloning is performed.
• Registry Filter is set up before EWF or FBWF are set up.

FBA Commands

You can add tasks to FBA by defining a custom resource and FBA command, in either Component Designer or Target Designer. To add any of these commands to a component in Component Designer choose the Resources node, right-click and select Add and then choose the FBA command that you want to use. This table lists the eight directives that can be executed during FBA. Each has different parameters that must be set.

Directive	Description
FBA Generic Command	Executes a generic command during FBA process. May call entry point in a DLL, call an application or executes a script. Phase must be out of the reserved range
FAB DLL/COM registration	Used for registering DLL and COM objects that use Regsrv32.exe
FBA OC Manager Request	OC Manager represents Optional Component Manager.
RunOnce Request	The RunOnce request FBA Directive lets the user set a Run, RunOnce or RunOnceEx command that should run after FBA finishes
Service Data	Adds service information to the run-time image
PnP Device IDs	Adds PnP ID for a driver to the registry
Component Branch	Specifies the component that is replacing the end-of-life component. Redirects Target designer to build a configuration by using a new component to replace an end-of-life component. This is a special FBA directive as this executes not during run-time image installation but executes during the build of an Windows Embedded Standard run-time image by Target Designer.
Shortcuts	Creates a shortcut link for an application

There are some common properties among each of the FBA directives:

• Name is the name of the directive as it appears in the component.
  It is also used during FBA processing to identify the directive being processed.
• ErrorControl specifies how FBA deals with errors when it processes the directive.
  Setting this to zero (0) tells FBA to keep going if it sees an error. If ErrorControl is one (1), then FBA will stop when it hits an error.
• Reboot tells FBA whether a restart is necessary after it processes the directive.
  Typically a restart is not necessary.
• Start tells FBA when to process the directive.
  The settings are as follows:
  • Boot (zero, 0)
  • Installation (one, 1)
  • End-user (two, 2)
  • Logon (three, 3)
    If this is not set, a setting of one (1), or Installation, is assumed.
• Timeout is how long FBA will wait for the directive to execute before it kills the thread.
  This setting is in seconds. Setting Timeout to zero (0) means FBA waits indefinitely.
• Type specifies what kind of FBA directive is being executed.
  The settings for Type are as follows:
  • Reserved (zero, 0)
  • FBA Generic Command (one, 1)
  • FBA DLL/COM registration (two, 2)
  • FBA OC Manager Request (three, 3)
    No value assumes a setting of one (1). Usually, this is set when you choose the FBA resource to add.

This section discusses the different commands in more detail.

• FBA Generic Command is used to call entry points in a DLL, execute a script, or call an application.
  For example, if you want to execute
  Rundll32.exe Setupx.dll,InstallHinfSection 132 C:\Windows\Inf\Shell.inf
  Set the following FBA Generic Command parameters:
  • Filepath: %11%\Rundll32.exe
  • Arguments: Setupx.dll,InstallHinfSection 132 C:\Windows\Inf\Shell.inf
    The phase number in a generic command must be higher than 8500.
• FBA DLL/COM Registration is needed when a component must register a COM InProc server during the first startup.
  FBA calls the Win32 function LoadLibrary and then optionally calls DllRegisterServer/DllUnregisterServer and DllInstall, or both.
  For example, if you want to register Ewfdll.dll in your run-time image set the following in DLL/COM Registration properties:
  • DLLRegister: TRUE
  • Filepath: %11%\Ewfdll.dll
    The phase number in a register command must be higher than 8500.
• RunOnce Request is used for a component that must execute a program or run a script at first startup or at every restart of the run-time image.
  The parameters specified in the RunOnce Request in the component will write information to one of the following keys:
  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce
  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnceEx
    For example, specify these parameters:
  • FilePath
    The executable file that must run
  • Arguments
    Optional commend line arguments
  • Flags
    0 - Run: The Explorer shell will invoke the specified program after every logon. If the explorer shell is not present then FBA processes the Run key in every logon.
    1 - RunOnce: Invokes the program only one time during the first restart after FBA finishes
    2 - RunOnceEx: The program is invoked only by the Explorer shell after every logon. If explorer shell is not present, this key is ignored.
    

It may not always be obvious whether to use a RunOnce Request or an FBA Generic Command.

This table explains the differences:

RunOnce	Generic FBA Command
RunOnce executes when the OS is already started.	Generic Command executes at the exact FBA phase you set in the component.
Depending on the flag, it can execute one time only or every logon	This is one time only

• FBA OC Manager Request enables the integration of external components into the setup process.
  The OCName property specifies the name of the optional subcomponent that belongs to a parent component group. Each optional subcomponent has an installation section in an INF file associated with it. Specify the INF file in the INFName property. FilePath specifies the name of the OC Manager helper DLL responsible for installing the optional component. DLLEntryPoint is the name of the function in the OC Manager helper DLL. The last property is GroupName. This is the name of the parent component group. This is required because optional components can belong to more than one parent group.
• Service Data/PnP ID's/Component Branch adds Windows service information to the run-time image.
  Most of the properties are self-explanatory, if you know how to install a service. PnP ID adds a PnP ID for your drivers to the registry.
• Component Branch deals with end-of-life components, and specifies which specific component is to replace the end-of-life component (specified in the TargetVIGUID property). This is a special FBA directive as this executes not during run-time image installation but executes during the build of an embedded run-time image by Target Designer.
• Shortcuts are used to create shortcuts to applications.
  DstName is the name of the LNK file to create. DstPath is the destination on the run-time image for the LNK file. TargetPath is the path of the application to be invoked by the shortcut. You should use parameterized paths here (such as the %16409% shown earlier). WorkDir specifies the working directory, and IconLocation specifies where the icon for the shortcut is located. Use Arguments to specify any arguments to the TargetPath, and Overwrite to specify whether any other shortcuts that may be present should be overwritten. HotKey is used to specify a hotkey for the shortcut.

RegMigrate Key

Another useful tool in customizing activities during FBA is the RegMigrate key. This enables registry keys to be overwritten after all DLL registration and RunOnce activity is finished.

This key can be found under the FBA key at HKLM\System\FBA\RegMigrate. All the subkeys under this key will be migrated to their corresponding positions during FBA at phase 6000. You can specify any root keys like HKLM, HKCR, and HKCU under the RegMigrate key.

For example, you can set your computer name to "myTest" in your embedded run-time image.

To set the RegMigrate key in the registry hive of the pre-FBA run-time image

1. Open Registry Editor (Regedit.exe) on your development workstation.

2. Click the Hkey_Local_Machine key.

3. On the File menu, click Load Hive.

   This should open a browse window.

4. Locate the System.sav file in your pre-FBA run-time image in \Windows\system32\config.

5. Type a name for this loaded hive (for example "test").

6. Click OK.

   You should now see a node called test under the Hkey_Local_Machine key.

7. Expand test and locate the key, HKLM\ System\ FBA\ RegMigrate.

8. Add the following entry under RegMigrate to set the computer name

   HKLM\ ControlSet\ ComputerName\ ComputerName

9. Under ComputerName add a new String named ComputerName.

   Set the value of ComputerName to myTest.

10. Click test and unload the hive by clicking Unload hive on the File menu.

11. Copy this run-time image to your destination computer.

    Let the compute complete FBA. As soon as the computer has restarted, you will notice that your computer name is now set to myTest.

This key is useful if you want to make sure that a particular resource is always going to be present on the final run-time image.

Troubleshooting FBA

Several different errors can occur when the system is running through FBA. These can be caused by missing files, devices or drivers that do not load, insufficient memory, or the run-time image being deployed on the wrong hardware or partition. Some errors are obvious as they output to the screen while FBA is running, but other errors may only be found by looking at the FBA log file in Windows\FBA.

The Fbalog.txt file lists registered binary files, networking protocols, Plug and Play devices, and any errors. Most FBA error codes correspond to standard Win32 error codes and can be interpreted by using Win32 error codes. You can use the Net command to identify Win32 error codes in the FBA log file (which are usually in hexadecimal format). To find the correct Win32 error code, convert FBA error codes to decimal form by using the scientific view in Microsoft Calculator. The following list shows the additional steps that might be needed to find the correct decimal representation of an FBA error:

• When errors contain the most significant digits such as 0xc0000005, drop the most significant 4 digits (0xc000) then calculate the decimal equivalent.
  In this case, the correct decimal number for the Win32 error would be 5.
• When errors are large negative decimal numbers such as -1073741819, convert the error to hexadecimal then drop the required most significant digits.
  In this case, the correct decimal number for the Win32 error would be -1073741819 converted to 0xC0000005 which results in 5.

Exit Code	Description
0x4a020	The specified component has already been installed
Error: 0x2	Cannot find the file specified
Error: 0x7e	Specified module could not be found
0xe000020d	Invalid class installer
0xc0000005	Access denied

For example:

C:\> net helpmsg 126

"The specified module could not be found."

An error code of 126 (0x7e hexadecimal) indicates a dependency issue to be resolved.

For troubleshooting driver installation it is especially useful to review the Windows\System32\Setupapi.log file.

We also recommend when testing a new image to set up a kernel debugger to monitor the output of FBA.

This may provide deeper insight into any failures that occur during FBA.

Common FBA Errors

These errors occur when FBA is running.

"Virtual Memory Error" Message during FBA

Cause: The run-time image has loaded more services and registered more binaries than you have physical RAM for on the destination computer

Resolution: One of the following resolutions will resolve this problem:

1. Reduce the number of features in the run-time image by disabling or deleting components from the configuration.
2. Add pagefile support in the Target Designer and by locating the hardware abstraction layer component in your configuration and adjusting the pagefile settings.
3. Add more RAM to the device.

"Exception Error" Message during FBA

Cause 1:

The wrong destination partition was specified in Target Designer. Check the beginning of the Fbalog.txt located at .\Windows\Fba\Fbalog.txt. If you see errors that say "invalid path" then the wrong partition was the problem.

Resolution:

1. In Target Designer, click Settings in the Configuration editor.
2. Choose Show from Target Devices Settings and change the boot drive, Windows folder, Program Files folder, Documents, and Settings folder fields to reflect correct boot drive.

Cause 2:

FBA ran out of memory.

Resolution: Same as for Virtual Memory Error as described earlier.

FBA Restarts Repeatedly

Cause: Built the run-time image for the wrong partition.

Resolution:

1. In Target Designer, click Settings in the Configuration editor
2. Choose Show from Target Devices Settings and change the boot drive, Windows folder, Program Files folder, Documents and Settings folder fields to reflect the correct boot drive.

"Stop 6B Error" Message during FBA

Cause: The configuration does not included the appropriate file system component (FAT or NTFS)

Resolution: Add the appropriate file system component to your configuration that matches the file system that you used to format your target media.

"Stop 7B Error" Message during FBA

Cause: The configuration is missing a component that is required to start your device, such as the PCI bus, the IDE controller, the Primary or Secondary IDE Channel, or a disk drive component. This may be because TA.exe was used to collect the system information.

Resolution: Use TAP.exe to collect system information, or manually add the appropriate boot components to your configuration.

"Cannot Check the License" Message During FBA

Cause: This indicates an incorrectly set partition size. The partition size specified by the property settings in Target Designer must be close to the actual size that is required for the destination partition.

Resolution:

1. In Target Designer, open your .slx file.
2. In the Configuration Editor Pane, expand the .slx file and then choose Settings.
3. On the Windows Embedded Standard tab in the Details Pane, under Target Device Settings, choose Show. The Target Device Settings appear.
4. Verify that the boot partition size field is correct

"Hal.dll is Missing or Corrupt" Message During FBA

Cause: Configuration does not include the HAL component, or includes the incorrect HAL component.

Resolution: Add the correct HAL component to your configuration.

"Unable to find ntoskrnl.exe" Message During FBA

Cause 1: Configuration does not include a kernel component, or includes the incorrect HAL component.

Resolution: Add the correct kernel component to your configuration.

Cause 2: The boot files were not copied the correct location, or are the wrong versions.

Resolution: Add the correct versions of the boot files to your boot partition.

"Stop 80 Error" Message during FBA

Cause: Configuration does not include the PlugandPlay BIOS component

Resolution: Add the PlugandPlay BIOS component to your configuration.

Stop error and "c000021ar" Message during FBA

Cause: Missing device driver dependency

Resolution: Identify the missing dependency or file that is required by the driver files.

Conclusion

What you have learned

By using the information in this article, you should now have a better understanding of the files and registry keys that are used during FBA and also available FBA commands and common FBA errors.