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:
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”.
- 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).
- 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.
- Type: REG_DWORD
- 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).
- 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.
- 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.
- 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.
Active Setup at AppDeploy.com
Active Setup Registry Keys and their Purpose at Boneman’s Blog
Nice write up, I’ve always heard of Active Setup, and I just assumed it was a component of Internet Explorer. I’m curious, if I disable Active Setup by unchecking it from the SysInternals Autoruns.exe GUI, would then in result stop all components from running on that system?
Hi Helge. My colleague Roland recently written an article concerning First Tim Shell Init. Also in the RES Workspace Manager Software, we’ve build a feature which can disable/hide the run of first time shell init.
I believe this is a nice add-on to your article: http://blog.ressoftware.com/index.php/2011/12/29/disable-active-setup-revealed/
That is a nice feature!
Hi Helge, great article. It seems that there is also a Dontask value that can be set. I saw it for the Microsoft Media Player or DOTNETFRAMEWORS ActiveSetup for example, the data is set to 2. Do you know of this?
It seems to avoid the prompting to the end-user to clean the environment when IsInstalled is set to 0.
Hi Petra, good to know, Never tried this one.
Active Setup is executed before any Run or RunOnce registry entries are evaluated.
It seems to be not correct. As I saw that RunOnce which run before Active Setup
Helge’s documentation of the IsInstalled flag is inaccurate and is a common misunderstanding that a lot of people have about this flag. Setting it to 0 does not technically disable the Active Setup. Instead, it indicates that the associated product has been uninstalled and to execute the Active Setup’s StubPath for any user that processed the Active Setup when IsInstalled was = 1. I refer to this as uninstall-related cleanup. The benefit of this feature is that Active Setup only runs the Uninstall StubPath for those users that need it and not for those who never processed the Active Setup when the product was installed.
Benoit Patra (above) appears to understand the use of IsInstalled as well as the DontAsk parameter for controlling the prompt to execute the StubPath.
You are mistaken. Active Setup processes before Windows Explorer loads, therefore before any Startup, Run, and RunOnce items execute as these items are processed by Windows Explorer while loading the desktop. It is important to be aware of this order of processing because it can impact the timing of whatever you’re trying to do in the user context at login.
Does Active Setup run in system context or in the current user’s context?
Great info, helped us a lot, cheers!
>>For this very reason Active Setup does not work with published applications,
>>since Explorer.exe is not started when a published application is run.
This is not entirely true for RemoteApps (MS technology) running under Windows Server 2019.
There ActiveSetup is executed if a new profile has to be created, however on subsequent calls Active Setup is not triggered (e.g. if a version number was incremented.
Do Active Setup items run in system context or in the current user’s context?
Active Setup is all about setting up the user (profile) part of an application’s settings. Therefore, AS processes run in user context.
Great article to refresh my memory on this topic. Would it be worth updating to mention the WOW6432Node in HKLM and HKCU?My 64-bit machine has both paths but I don’t fully understand the logical order/process of execution for the two nodes.