ASP Troubleshooting Tips and Techniques
Mike Hedley
Developer Support Engineer
Microsoft Technical Support
April 11, 1997
Contents
Where and When Is the Problem Occurring?
Who Is Having the Problem?
Accessing Remote Machines
ADO and Other Component Problems
Inability to Create Components
Conclusion
Appendix
Where and When Is the Problem Occurring?
When you use Active Server Pages (ASP), you're operating in the client/server world of Microsoft® Internet Information Server (IIS) and the HyperText Transfer Protocol (HTTP). Many customers who don't have a firm grasp of this architecture find themselves puzzled by strange errors in what seems to be straightforward code. If you've ever been in this situation, don't fret. The world of ASP and HTTP can be confusing, especially when you're new to the technology.
Let's take a look at the sequence of events that occur when a client, such as Internet Explorer, requests an ASP page. This discussion does not take into account the complexities of authentication on the ASP page. In our simplified discussion, the following three events take place:
- The client (Internet Explorer) requests an ASP page by sending an HTTP Request message to the Server.
- The server (IIS) recognizes that the requested page is an ASP page because it has an .asp file extension, and sends the asp file to asp.dll for processing. This processing includes execution of all server-side scripting code. (This step does not occur when the client requests an .htm file.)
- The server sends the resulting HTML page back to the client in the form of an HTTP Response.
Once the client receives the response, it executes any client-side script code and displays the Web page according to the HTML specification. While this process looks simple, keep in mind that the client and server could be hundreds, or even thousands, of miles apart. Therefore, when a problem arises, you must determine where the error is occurring: on the client or on the server? Equally important is understanding when each operation takes place. After ASP completes its processing in Step 2 and sends the response in Step 3, it moves on to other activities and other clients. The only way the client can recapture the server's attention is to request another page via the HTTP protocol. In other words, there is no real connection between the client and server. This is a very important concept that must be understood. In the following paragraphs, I describe common types of problems encountered by ASP developers, and demonstrate the extra effort that is often required to promote communication between the client and server.
One type of problem occurs when developers try to access server-side scripts or objects from the client, or conversely, client-side objects from the server. As an example of the first scenario, consider client-side code that attempts to access one of ASP's Intrinsics, such as the Session object. This is destined for failure because the code running in Internet Explorer has no way of accessing the object located on the server. A typical error message might appear as follows:
VBS Script Error: Object Required: Session
Now consider the second scenario, where a server-side script attempts to manipulate a client-side object. For example, suppose you use server-side scripting to populate a client-side ActiveX™ Listbox Control. While this seems like a simple task, you must keep in mind that the HTML page, and therefore the list box, does not yet exist when the server-side code is executed. Because the list box control hasn't been created when the server-side script is run, the following code,
<% ListBox1.AddItem Value1 %>
will generate a similar "Object Required" scripting error. To accomplish this task, use server-side code to generate client-side code that will populate the list box. You should put this code in the Window_OnLoad event, where it is guaranteed to be executed by the browser after the window and its child controls are created. The following code segment demonstrates this technique. The server-side scripting code substitutes the values stored in variables Value1, Value2, and Value3, into the AddItem method calls.
<SCRIPT LANGUAGE="VBScript">
<!--
Sub Window_OnLoad()
ListBox1.AddItem "<% = Value1 %>"
ListBox1.AddItem "<% = Value2 %>"
ListBox1.AddItem "<% = Value3 %>"
End Sub
-->
</SCRIPT>
Note that if you use the HTML <SELECT> tag instead of an ActiveX control, the procedure is slightly more direct. Because a list box created with the <SELECT> tag is based on HTML code, you can use server-side scripting to create the <OPTION> tags. The following example fills an <OPTION> tag with data provided by a field in the current record from the RecordSet, rs. Since there is no object creation, you do not need to place this code inside the Window_OnLoad event.
<OPTION VALUE= "<%= rs("Name") %>"> <%=
rs("Name")%>
Another common problem encountered by ASP developers involves passing client data to the server. Consider the following scenario: Suppose you want users to log on to your Web application by providing his or her name and ID number. To accomplish this task, you create a simple HTML page with two INPUT items in an HTML form. The user is expected to enter the name and ID and press Submit. After the user submits the requested information, ASP verifies the user's credentials through a database query. If the information is correct, you allow access; otherwise, this user is denied access to the page. The subtle point often overlooked in this procedure is passing the information provided by the user to ASP. Recall that the only way the client can recapture the server's attention is to request another page via the HTTP protocol. In this case, the best approach is to POST the HTML form to an ASP page. Posting the form generates an HTTP Request that invokes ASP to process the requested page. During this ASP processing, the server-side script retrieves the posted data by calling Request.Form, and performs the database query and other verification logic. The following code demonstrates a simplified version of this procedure. Notice that the user information is actually posted back to the same ASP file that displays the form. This is perfectly valid, and is often more convenient than posting to a second ASP page.
<%@ LANGUAGE="VBSCRIPT" %>
<!-- FILE: login.asp -->
<HTML>
<HEAD>
<TITLE>Login Example</TITLE>
</HEAD>
<BODY>
<% IF IsEmpty(Request.Form("Name")) THEN
Response.Write "Please enter your Name"
%>
<FORM ACTION="login.asp" METHOD=POST>
<INPUT NAME="Name"
TYPE=TEXTBOX MAXLENGTH=20>
<INPUT TYPE="SUBMIT" VALUE="Submit">
</FORM>
<%
ELSE
'User verification code goes here
Response.Write "Welcome " & Request.Form("Name") & "!"
END IF
%>
</BODY>
</HTML>
If you need to pass information from ActiveX controls on the page to the server, you will need to add client-side scripting that reads the values from the controls and stores them in members of a "hidden" form, which is posted to the ASP file. Another variation of this technique is to pass the values to ASP using the query string, although this approach is limited by the length restrictions imposed on the query string by the HTTP specifications for the GET request.
As demonstrated in the preceding examples, ASP development requires a bit of creativity at times. However, keep in mind that many of these hurdles are actually imposed on ASP by the HTTP protocol and the client/server nature of Web development. If you consider some of the alternatives, I think you'll agree that ASP is well worth the effort.
Who Is Having the Problem?
By far, the largest segment of ASP issues handled in Developer Support involves security and permission problems. In order to avoid these problems, ASP developers must have a firm grasp of IIS authentication and controlling access to pages using NTFS file permissions. Although a thorough discussion of these topics is beyond the scope of this article, I will touch on the basic concepts and highlight the typical problems ASP developers encounter. For more information about securing your ASP application, see Securing Your ASP Application in the Scripting Guide included in the ASP online documentation (Roadmap).
Let's begin with a quick overview of the client authentication types. Internet Information Server 3.0 supports three authentication schemes: Anonymous, Basic (Clear Text), and Windows NT® Challenge/Response. Each of these authentication methods is enabled or disabled through the WWW Service Properties page in Microsoft Internet Service Manager. A typical IIS configuration has Anonymous enabled, as well as either, or both, of the other methods. Anonymous authentication is the least secure method, while Basic and Windows NT Challenge/Response provide differing levels of security for your Web pages. The advantage of Basic authentication is that it is part of the HTTP specification, and is thus supported by most browsers. The disadvantage of Basic authentication is that if someone is monitoring packets on your network, they could easily intercept and decipher your password using publicly available algorithms. This is not possible with Windows NT Challenge/Response authentication because the actual password is never sent over the wire. Instead, the browser returns a custom token that satisfies the server's authentication request.
Although NT Challenge/Response is very secure, it does have a couple of limitations. The first limitation is that only Microsoft browsers support this proprietary scheme. Another limitation is that Windows NT Challenge/Response does not work over HTTP Proxy connections. Because of these limitations, Windows NT Challenge/Response may not always be the best choice for an Internet server, however it is often ideal for intranet use. As you can see, choosing an authentication method is a trade-off in security verses flexibility.
Now let's discuss the authentication process. Before IIS returns a requested page to a client, it first verifies that the client has permission to view the page. Although you can restrict permission to a page by turning off Read and Execute permissions on its virtual root in IIS, we will assume that both Read and Execute permissions are granted in IIS for the virtual root. The preferred method of restricting access to individual pages is to use NTFS file permissions to control which users can view the page. Before returning a page to the client, IIS checks the NTFS file permissions on the page to see if the current user is allowed access to the file. In order to know who the current user is, you must understand the authentication process used by IIS. When you configure IIS for Anonymous authentication, you must provide a username and password for the Anonymous Logon account. By default, this account is set to a user called IUSR_MACHINE, where MACHINE is the machine name of the Web server. IIS attempts to authenticate the Anonymous Logon account by checking to see if the IUSR_MACHINE account has permission to view the file. If the NTFS permissions on the file do not allow IUSR_MACHINE access to the requested page, IIS returns an HTTP 401 Unauthorized status code to the browser. At this point the browser attempts to authenticate the user using one of the other authentication methods. If Windows NT Challenge/Response is used, the browser automatically returns the appropriate information to satisfy the authentication request. The user is not prompted for a username and password unless the server does not recognize the username provided by Windows NT Challenge/Response. If Basic authentication is used, the user is prompted for his or her username and password. IIS then checks the user's credentials against the access permissions on the requested page, and either returns the page to the browser or returns an Access Denied response.
Now that we have covered the basics of authentication, let's return to ASP troubleshooting. The important point of this section is that who you are at any given time in your ASP scripts depends on the authentication scheme used. If a user has been authenticated using either the Basic or Window NT Challenge/Response scheme, then server-side scripts and components run in the security credentials of the person logged on to the client machine. If the user has been authenticated as the Anonymous Logon account, which is usually the case, ASP scripts and components run in the security credentials of IUSR_MACHINE, or whichever account you have designated as your Anonymous Logon account. If you take away only one piece of information from this article, please remember that ASP scripts are typically executed in the security context of the IUSR_MACHINE account. This concept is important because it is the root of many problems ASP developers encounter.
There is a wide range of problems that occur if the authenticated user does not have adequate permissions to complete a given task. This goes beyond having permissions on .asp files. Errors also occur if the authenticated user does not have sufficient permissions on other files such as custom components, system DLLs, and even registry keys. Unfortunately, these problems can exhibit a wide range of symptoms and error messages, so they are difficult to diagnose. In the following sections, I describe the three most common classifications of permission problems and provide some debugging techniques that you can use to track down these problems.
Accessing Remote Machines
Common Symptoms
- Microsoft OLE DB Provider for ODBC Drivers error '80004005' when attempting to open an ADO connection.
- ASP code that worked fine when the database was located on the IIS Server no longer works when the SQL or Access database is moved to a remote machine.
Description
One of the most common types of problems occurs when ASP attempts to access resources located on remote machines. A good example of this is using ADO to access either SQL Server on a remote machine or an Access .mdb file located on another Windows NT machine. The problems stem from the fact that ASP is operating in the context of the IUSR_MACHINE account. On servers that are not primary or backup domain controllers, the IUSR_MACHINE account is a local account. Since this local account is not recognized on the remote machine, access is denied to the database.
Debugging Techniques
The two most common workarounds for this problem are:
Change the Anonymous Logon account on the IIS server from IUSR_MACHINE to a domain account that is recognized by both machines and has sufficient permissions to the resource. In addition, be sure that this account has the log on locally user right on the IIS machine. Recall that the Anonymous Logon account is configured through Internet Service Manager.
Note: If you later decide to change back to the IUSR_MACHINE account, be sure that the password provided in Internet Service Manager matches the password provided for this account in the User Manager tool. If the passwords do not match, you will encounter Access Denied errors.
Add a local account to the remote machine that exactly matches the username and password of the IUSR_MACHINE account on the IIS machine, and give this account access to the database.
Note: This workaround is not recommended because it involves maintaining two separate accounts. If the passwords get "out of sync" at some point in the future, access will be denied to the database, and errors will occur.
ADO and Other Component Problems
Common Symptoms
- ASP 0115 - A Trappable error has occurred when attempting to use ADO. (Note: This is only one of the possible causes of the ASP 0115 error.)
- ASP pages that use ADO or other components suddenly no longer function properly.
- ASP pages that work on a development machine don't work properly on a production Web server.
Description
Another type of problem can be attributed to permission settings, where components such as ADO simply don't function properly. The root of these problems is often restricted NTFS permissions that don't provide sufficient privileges to the IUSR_MACHINE account. If the same ASP code works on a different machine, or is used to work on the current machine, this is a strong indication of some sort of configuration problem such as restricted permissions. For example, many customers we speak to in Developer Support indicate that their ASP application works fine on their development machine, but does not work on their production Web server. This is due to the fact that most companies like to restrict access to production servers as much as possible. While this is a good practice, care must be taken to ensure that ASP is able to function properly. What typically happens is that NTFS file permissions are restricted on various directories to the point that IUSR_MACHINE cannot access the required files. This is a frequent problem because many administrators don't realize the important role that the IUSR_MACHINE account plays in the world of ASP. ADO often falls victim to this problem because it depends on many DLLs that are located in various directories on your hard drive. In particular, ADO relies on many ODBC DLLs and other database drivers that are located in the WINNT and System32 directories. ADO also depends on certain registry keys that may not be readable by the Anonymous Logon account if permissions are set incorrectly. In addition, some database drivers attempt to write to the registry, thus requiring write access for the Anonymous Logon account. The Debugging Techniques section that follows provides a few techniques that will assist you in locating the cause of the permissions problem.
Debugging Techniques
The first step is to determine if you really are seeing a permissions problem. A good test is to temporarily add the Anonymous Logon account (IUSR_MACHINE) to the administrators group using User Manager. This gives the IUSR_MACHINE account administrative privileges on the machine. If this causes ASP to function properly, you are almost certainly dealing with a permissions issue.
Note: When you have finished debugging, be sure to remove the IUSR_MACHINE account from the administrators group to minimize the security risk on your server.
Another useful technique is to attempt to use ADO or the component in question from some other environment such as Visual Basic®. This produces nearly the same effect as the first technique because Visual Basic operates in the security context of the user logged on to the workstation. If the component works from Visual Basic but not from ASP, a permissions problem is likely.
Once you have concluded that you are dealing with a permissions problem, you need to locate the files that don't have adequate permissions. This consists of systematically searching the directory tree to locate the problem files. Some users choose to give full control to the entire directory tree, and then work backwards to tighten down security until the error occurs. Since you can't easily undo this change, consider creating a temporary account to use for this test. Set this account as the Anonymous Logon account and give it Full Control to the entire tree. Once you've located the problem, you can simply remove the account without affecting the permissions of the other user accounts on this machine.
Another approach for locating files that do not have sufficient permissions is to use the security auditing functions provided by Windows NT. (This technique is explained in more detail in the Appendix.)
If you believe you are dealing with a permissions problem in the registry, you can use Regedt32.exe to examine permissions on the various registry keys. In particular, you may want to look at ODBC, Jet, ADO, and other keys that are relevant to the problem. If you have a machine that is working properly, try comparing key permissions between the two machines.
Note: Although Windows NT includes registry auditing tools, this topic is not discussed here due to the complexity of the procedure and the danger involved with modifying the registry.
Inability to Create Components
Common Symptoms
- Server.CreateObject fails with an ASP 0177: Server.CreateObject Failed error.
- The component works fine on the same machine from Visual Basic or from some other tool.
- The component works fine with ASP on other machines.
Description
Other permission problems occur when ASP tries to create server-side components. The causes, symptoms, and debugging techniques are very similar to the previous discussion. The problems arise because the authenticated user does not have permission to invoke the COM object. In the simplest scenario, the authenticated user doesn't have access to the component's .dll or .exe file. In many cases, however, the component depends on other DLLs which the authenticated user does not have access to.
Debugging Techniques
- Although giving the IUSR_MACHINE account administrative permissions is useful in this scenario, a better first step is to invoke the component from some other tool such as Visual Basic. This approach is preferred because it checks for permission problems, as well as verifying that the component is registered properly on the server. If the component cannot be created from Visual Basic, you are probably not dealing with a permissions problem at all.
- If you believe you are dealing with a permissions problem, check permissions on the component and any dependent files such as other DLLs.
- If you still are unable to track down the problem, you may need to resort to other means such as a systematic permissions search, or Windows NT File and Object Auditing.
While the previous sections only touch on the most common permissions issues, I hope that you have gained an appreciation for the types of problems that are caused by permissions and other security settings. With an understanding of authentication and a few debugging tools at your disposal, you should be able to work through any permissions problem that comes your way.
Conclusion
I hope this article has provided some useful insights that will make troubleshooting ASP applications a bit easier. With persistence and a little patience, I'm sure you'll quickly locate the problem and move on to more important work, such as finding other exciting ways to use Active Server Pages in your business.
Appendix
This appendix contains information on using Windows NT security auditing.
Using Windows NT Security Auditing
Start User Manager.
On the User menu, click Select Domain. Select the domain for the local machine by entering the name of the local domain.
Enable auditing by clicking Audit… on the Policies menu. Select Audit These Events and then check the Failure box for File and Object Access.
Next you need to tell Windows NT which directories and files you want to audit. Open the properties dialog for the specified directory or file in Windows Explorer, click the Security tab, and click the Auditing… button. Now use the Add... button to add the name of the user you want to audit (in this case IUSR_MACHINE). Next, pick the desired combination of Replace Auditing on Subdirectories and Replace Auditing on Existing Files. Finally, select Failure for the desired events.
Using Internet Explorer, attempt to view the ASP pages that cause the permissions violation to occur.
Open the Windows NT Event Viewer and choose Security from the Log menu. The security log should show all failed attempts by the specified account to any files that have auditing enabled.
Note: When you have finished troubleshooting, turn off auditing for best system performance. See the Windows NT online help for more details on auditing.