INFO: Understanding SAM Active Contexts Under Windows NT

ID: Q155601

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK) on the following platform:
```
    - Windows NT versions 3.51, 4.0
```

SUMMARY

In Windows NT, the security accounts manager (SAM) manages a set of connections, referred to as active contexts. An active context is established as a result of user management query and set operations. Examples of operations that utilize active contexts are running User Manager and making certain Win32 LAN Manager Networking API calls.

MORE INFORMATION

When a process makes a SAM-related call, a single active context is consumed on the target machine, for the lifetime of the client process or the lifetime of the open SAM handle, whichever is less. Win32 LAN Manager Networking API calls maintain a single cached SAM handle per process, because opening the SAM is considered an expensive operation. A side effect of this caching operation is the use of an active context on the machine that was the target of the last user management function.

You can see active context utilization for remote SAM operations by running the Netwatch utility in the Windows NT resource kit, or programmatically through the Win32 Networking API NetFileEnum(). An active context appears as an open resource named \PIPE\SAMR on the machine where the user management call was focused.

In versions of Windows NT 3.51, prior to Service Pack 4, the maximum number of active contexts is 255. This limit was raised in Windows NT Service Pack 4 to 2048. These limits exist to prevent client operations from exhausting server resources, which could otherwise result in disruption of service.

The maximum active contexts is not an issue in most Windows NT installations. However, in some large or complex installations, this may become an issue. The following example describes one such scenario where active contexts may be exhausted.

Example Scenario

A large number of workstations are running a process that queries user information on the logon domain controller; this process remains running throughout the day. In this scenario, each process consumes an active context on the logon domain controller for the lifetime of the process. If the number of client processes exceeds 2048 (or 255 prior to Windows NT 3.51 SP4), each new process fails the SAM connection against the domain controller.

In current versions of Windows NT, there is no API call for directly "closing" an active context. However, the following code fragment illustrates an approach that can be used to achieve this:

   #include <lm.h>

   PUSER_MODALS_INFO_0 umi0;
   NET_API_STATUS nas;

   // 
   // Make remote calls to NetUserGetInfo(), etc.
   // 
   // After remote calls have been made, make a local call, which updates
   // the cached SAM handle to point at the local machine. This has the
   // side-effect of closing the active context associated with the
   // previous call.
   // 

   nas = NetUserModalsGet(
           NULL, // target local machine
           0,
           (LPBYTE *)&umi0
           );

   if(nas == NERR_Success) NetApiBufferFree(umi0);

Additional query words:

Keywords          : kbnetwork kbAPI kbKernBase kbNTOS350 kbNTOS400 kbSDKPlatform kbSecurity kbNetAPI kbGrpNet 
Issue type        : kbinfo

Last Reviewed: September 10, 1998