Understanding the Citrix MetaFrame Logon and Logoff Process

TThe Windows logon and logoff process is a complex part of a Terminal Server environment, and these processes are complicated even more when Citrix MetaFrame Presentation Server is installed. However, knowing how these processes really work can cut down your troubleshooting time.

This article can’t cover all aspects and every detail of the logon and logoff processes. However, it will take a look at these processes from an administrator’s standpoint (as opposed to taking a developer’s perspective).

The first part of this article covers the session initialization. It covers the steps that take place from the time a client tries to connect until the application shows up on the user’s desktop. (Note that we’re only talking about the actual connection from the client to the server. We are not talking about application enumeration or load balancing since those activities take place before a client connects to a server.)

The second part of this article will cover the disconnection and logoff processes.

Session initialization

No matter how an ICA session is invoked (Program Neighborhood, Web Interface, double-clicking an ICA file, etc.), the ICA client engine (wfica32.exe for Win32 clients) fires up and loads the module.ini file from the root folder of the ICA Client. The module.ini file defines the specific capabilities that the ICA client should or can use. Therefore, when troubleshooting, it’s possible (and useful) to change settings in the module.ini to change the capabilities of the ICA Client. For example, you might chose to disable specific client drives (DisableDrives=A,D,F) or to enable server drives in a pass-through session (NativeDriveMapping=TRUE).

Once the ICA client works out which drivers it will use, it starts a connection with the server via port 1494 (even with session reliability enabled). The server responses with “7F7FICA” for an ICA handshake as shown in the next screen shot. During the handshake the client sends its list of capabilities (virtual channels supported by the client) to the server.

Next, (still before anything shows up in any admin console or on the client desktop), the TSCAL license verification is made. If the license cannot be verified then the session just ends. Even though this is by design it’s still very confusing for most people.

If the client has or gets a valid TSCAL, the server’s WinLogon.exe process calls the GINA (and any linked GINAs, like ctxgina.dll when MetaFrame is installed) and the user is presented with the logon GUI.

Once the user credentials are validated via lsass.exe, WinLogon downloads the user profile.

The GINA then calls UserInit.exe which is responsible for setting up the user’s environment (restoring net uses, etc.). When Terminal Server is installed, UserInit queries the registry key AppSetup located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon and executes all the programs listed in that key. By default this is limited to UsrLogon.cmd, although MetaFrame XP adds cmstart.exe to the list and MetaFrame version 3 adds CtxHide UsrLogon.cmd, and CmStart.exe. (Those of you who’ve been using Terminal Server for awhile will remember that UsrLogon.com is a hold-over from the early days when application compatibility scripts were used. See Microsoft article KB195950.)

The last thing UserInit does is launch the user’s shell as specified in the registry. By default this is explorer.exe, although you can change it to whatever you want and have some fun with your colleagues by changing theirs to progman.exe.

Once the shell is fired up the final steps take place, including items listed in the run registry keys and the programs from the Startup folder.

There’s a great utility from SysInternals called “AutoRuns” that you can run on a server to quickly and graphically show you all the things that run automatically when a session is started.

 

Everything on the server side that we’ve mentioned so far is Microsoft only. It applies if you’re connecting via a standard Terminal Server / RDP session or via a MetaFrame ICA session, (For more detail on WinLogon, UserInit, Csrss, and other Windows processes, take a look at Microsoft Knowledge Base article KB263201.)

Now let’s take a look at what happens when Citrix is thrown in the picture. As we mentioned earler, UserInit also executes the CmStart.exe process. CmStart.exe is the Citrix Client Manager Starting Utility and it’s responsible for two things:

1. It starts the Citrix seamless windows engine shell called wfshell.exe.
2. It launches the Citrix Client Manager (cltmgr.exe ) that’s used to keep the ICA client up to date.

The following screenshot is of Systernals’ Process Explorer running during a MetaFrame session start.

 

Let`s take a closer look at these processes and what they each do.

Citrix Client Manager Starting Utility (CmStart.exe)

CmStart is responsible for launching the seamless engine which means no seamless windows without CmStart.exe in the AppSetup Key! This missing entry will not stop a desktop session from working through.

Citrix Seamless engine (wfshell.exe)

One of the things wfshell is responsible for is to autocreate the client printers. If you are using third party printer drivers (HP, Canon, Lexmark etc.) instead of original printer drivers that come on the Windows CD then you might see some of the following issues:

• Crashes of wfshell.exe (CTX102634)
• High CPU spikes of wfshell.exe
• Slow logons
• Printer being not mapped

Advice: Don’t use third party printer drivers and don’t use PCL6 Drivers.

Citrix Client Manager (cltmgr.exe )

Cltmgr.exe is launched right after wfshell because it uses a virtual channel (VDCM.dll, ClientManagement) to get the client version from the version.dat file. Problems with the retrieving of the ICA client version and the update might have the following effects:

• Crashes of wfshell.exe
• Slow logons (without updating the client)

Advice: If the Client Update feature is not used, you should disable the client update database on every Citrix server (Start | Run | cudutil.exe | Database | Properties | uncheck enable).

Session Termination

When closing a published application or logging off from a desktop session, the most important parts are terminating the user processes and unloading the user’s registry hive from the system registry.

In a desktop session the termination of the processes is done by csrss.exe. With published applications the seamless engine is responsible for closing the applications and sending the logoff message to csrss. Under certain circumstances this might not work and ends with a user’s session remaining active on the Citrix Server, although we’ll discuss this more later.

In some cases the user’s registry can not be unloaded during the logoff. This issue is very famous in the community and the solution is to use the Microsoft’s UPHClean service. (Be sure you’re using the most current version.) If the unload process doesn’t work as expected, then the profile gets stuck on the server (a bit different with Windows 2003). This then impacts the logon process, especially with anonymous users.

Summary

This article summarized the important steps and processes you see with Windows 2000/2003 and MetaFrame XP / 3.0. There are additional processes like Ctxhide.exe, but they are not big troublemakers. Unfortunately MPS 4.0 is going to majorly change the Citrix portion of this process, but that’s a story for another day.