Active Setup Explained

This is a summary of my experience with Active Setup combined with the information I could find on the internet.

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.

Terminal Servers / Citrix

Active Setup is executed by Explorer.exe, nameley 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

HKEY_LOCAL_MACHINE\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 below 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

, , , , , , , , , ,

7 Responses to Active Setup Explained

  1. Craig April 22, 2010 at 23:03 #

    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?

  2. Martin Lako January 23, 2012 at 21:25 #

    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/

    • Helge January 23, 2012 at 21:35 #

      That is a nice feature!

  3. Benoit Patra July 25, 2014 at 13:24 #

    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.

Trackbacks/Pingbacks

  1. Strange “Recent Places” issue in windows 7 / Server 2008 R2. « One foot in the trenches. - September 14, 2011

    […] For a great explanation of Active setup, check out Helge’s write up over here. […]

  2. Disable Active Setup revealed | MrWorkSpace - January 23, 2012

    […] Also Helge Klein created an interesting article concerning the Active Setup: https://helgeklein.com/blog/2010/04/active-setup-explained/#comment-6155 […]

  3. Active Setup « Servirt - January 24, 2012

    […] https://helgeklein.com/blog/2010/04/active-setup-explained/ January 24th, 2012 | Tags: active setup, rds | Category: remote desktop services […]

Leave a Reply