Active Setup Explained

This is a summary of my experience with Active Setup combined with what I could find on the internet. The information applies to older and current versions of Windows, up to and including Windows 7, Windows 10, Server 2016, Server 2019.

What is Active Setup and How Does it Work?

Active Setup is a mechanism for executing commands once per user early during logon. Active Setup is used by some operating system components like Internet Explorer to set up an initial configuration for new users logging on for the first time. Active Setup is also used in some corporation’s software distribution systems to create an initial customized user environment. To understand why such a mechanism is necessary we need to take a step back.

Application programs use two different types of data: machine-specific data like the files in the installation directory, and user-specific data like the information which document a user last edited with the application. Installing machine-specific data is simple: just copy it to C:\Program Files and HKEY_LOCAL_MACHINE and you are done. But how to get an initial user configuration into a user profile? Writing into the profile of the user doing the install does not help because we need the initial configuration for all users logging on to the system.

One solution to this problem is Active Setup. It uses both machine-specific data and user-specific data. The machine part consists of a list of components identified by a GUID each. The user part is basically a mirror of the machine data, but, and this is the key point, it does not exist in new user profiles. Whenever a user logs on, Active Setup checks if each machine part component GUID is present in the user part. If not, the component’s command is executed and the component’s GUID is stored in the user part. If it is, the current user profile has already been initialized and no further action is required.

When is Active Setup Executed?

Active Setup runs before the Desktop appears. Commands started by Active Setup run synchronously, blocking the logon while they are executing. Active Setup is executed before any Run or RunOnce registry entries are evaluated.

RDSH/Citrix CVAD (XenApp)

Active Setup is executed by explorer.exe, namely the Explorer instance that acts as the shell and later shows the desktop. For this very reason Active Setup does not work with published applications, since explorer.exe is not started when a published application is run.

You can manually trigger Active Setup by executing the following command within the session, e.g. from a logon script:

%systemroot%\system32\runonce.exe /AlternateShellStartup

Registry Entries Related to Active Setup

HKLM\SOFTWARE\Microsoft\Active Setup\Installed Components

This is the root key containing all things Active Setup. The keys and values mentioned below are all located under this root key.

A duplicate of this machine key exists in the user profile: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Active Setup\Installed Components. In this article, I call the HKCU Active Setup key “user part”.

GUID

• Type: registry key
• For each component, there is a GUID key below the root key. Technically, this need not be a GUID, but GUIDs have the advantage of being unique.
• Each GUID represents one component to be managed by Active Setup. The number of components is not limited and there can be zero, one, or multiple components per application. The number of components is dependent on the number of commands that are to run – only one command per component is possible (see StubPath below).

Default Value

• Type: REG_SZ
• Optional name of the component. If a name is stored here, it will be shown in the Active Setup user interface dialog when the component’s command is run.

IsInstalled

• Type: REG_DWORD
• Possible values:
  • 0: The component’s command will not run.
  • 1: The component’s command will be run once per user. This is the default (if the IsInstalled value does not exist).

Locale

• Type: REG_SZ
• An arbitrary string specifying the installation language of the component. If this string is either not found in the user part or different from the machine part, the component is run. Please note that Active Setup does not impose any restrictions on the nature of this string, you could use “abc” just as well as “de” or “en”. Once run, the version number is copied to the user part.

StubPath

• Type: REG_SZ or REG_EXPAND_SZ
• Format: Any valid command line, e.g. “notepad”
• This is the command that is executed if Active Setup determines this component needs to run during logon.

Version

• Type: REG_SZ
• Format: Four numbers separated by commas, e.g.: 1,2,3,4 (points do not work)
• If a version value is present, the component’s command will run only if the corresponding version in the user part is smaller or not present. Once run, the version number is copied to the user part. If you want a component’s command to run again, you need to increase the version number. That is what Windows updates do, e.g. when you install Internet Explorer 8 on a machine that only had IE7 before. By increasing the version number, the initial user configuration is guaranteed to run again.

Creating Your Own Active Setup Component

This is really simple. Let us unrealistically assume you need to start notepad once per user. This is what that would look like:

All you need are two simple registry values below your own Active Setup component key:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Active Setup\Installed Components\Helge]
@="Helge's Active Setup Component"
"StubPath"="notepad"

As you can see, I used a not so arbitrary component name (“Helge”) in place of a GUID. I set the default value to a string I would like displayed while my component’s command executes (“Helge’s Active Setup Component”). And finally I set the command line executed by Active Setup: “notepad” just starts the Windows editor, of course.

Things You Should Know

Active Setup employs neither a timeout nor any other mechanism to determine if a StubPath process it started is still alive. That means it is very easy to shoot yourself in the foot: if a process started by Active Setup hangs, Active Setup hangs, too, and there is typically no easy way to remedy the situation, except flipping the big red power switch.

References

Active Setup at AppDeploy.com
Active Setup Registry Keys and their Purpose at Boneman’s Blog