Active Setup Explained

Helge Klein, 04/22/2010 | 4 Comments | 34,333 Views

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

Active Setup - W2k3 - 1 

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.

Active Setup - W2k3 - 2

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.

Active Setup runs before the shell is started, i.e. 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 because Run(Once) is handled by the shell, Explorer.exe, which is started only after Active Setup is finished.

Active Setup - W2k3 - 3

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:

Custom Active Setup Component on Windows Server 2008

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

+++ Your opportunity +++ Use Profile Migrator the new sepago product that makes migrating user personalities between different platforms a breeze.! Download your free version now!

4 responses for "Active Setup Explained"

Nice write up, I’ve always

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, interessante Sache.

Hi Helge,
interessante Sache. Nur scheinbar gibt es da noch Probleme unter 2008R2 wenn die Active Setup Komponenten im WOW6432NODE stehen. Gleiches Problem wie damals unter 2003 x64 (http://support.microsoft.com/kb/907660)
Ist dir bekannt ob es dafür schon eine Lösung gibt? Für 2003 gab es einen Hotfix.
Liebe Grüße aus Neuwied
Carsten

The information was very

The information was very useful.There doesn't seem to be any documentation in MSDN on using active setup for deployment purposes. I was wondering if Active setup is used in production for non Microsoft products.Are there any issues or gotchas that one should know before adapting it for production.

Nice article. In my

Nice article. In my environment using pgina to login, every user is a new user, so these active setup commands run every on every login, if I let them. The proper action should be to update the default user registry hive once, and be done with it.