In IIS 4 and 5, the webagent was an ISAPI filter that sat at the root level of the entire IIS server, and you weren’t supposed to move / manipulate it in any way. This meant the webagent poked its nose into requests to all of your virtual web sites. If you wanted distinct protection on some of your virtual sites, better learn how to use the “AgentName” setting. Then came IIS 6, where the webagent not only runs as an ISAPI filter, but also runs as a wildcard application map. The ISAPI filter sits at the “Sites” root level of the entire server, but the wildcard application map sits on the individual websites. By default, the wildcard application map is only placed in the default web site, so the webagent only gets involved in requests to the default web site. This means that if you have multiple virtual sites, and you want the webagent to interact on more than just the default web site, you just have to create the wildcard application map on the other virtual sites.
Now, there’s IIS 7, and the webagent is implemented in a similar manner, but the IIS 7 prerequisites and the new IIS 7 console have changed things enough that even the most savvy IIS 6 webagent expert can find it challenging to install, configure, and troubleshoot the IIS 7 webagent.
IIS roles necessary for webagent operation
First, when you install IIS 7 onto your Windows 2008 machine, there are a few options that are required.
You must have:
- ISAPI Extenstions
- ISAPI Filters
If you do not, the webagent Configuration Wizard will throw an error message:
Default webagent configuration
When you run the webagent configuration wizard and select to configure the agent into your IIS 7 server, the wizard does the following 3 things (all under Default Web Site):
- Puts webagent filter under ISAPI filters. Executable points to: <agent install location>webagentbinISAPI6WebAgent.dll. If you click “View Ordered List”, the webagent should be listed first.
- Creates a Wildcard Script Map under Handler Mappings. Executable points to: <agent install location>webagentbinISAPI6WebAgent.dll
- Creates a virtual directory named siteminderagent
1) I have enablewebagent=YES, but my webagent still isn’t starting.
Under the default website, check for the presence of the webagent filter under ISAPI filters and the webagent Wildcard Script Map under Handler Mappings. If they are both there, then the agent should start. Remember that the website (and the webagent) may not start until someone accesses it via browser. Also remember that the best way to make sure the agent is running is to look for a process called LLAWP in Task Manager. Don’t rely on the lack of agent log creation as a method of determining that the agent is not running.
2) I want the webagent to interact on more virtual sites, not just my default web site.
The webagent configuration wizard will not do this for you. You must do it manually in the IIS console. Under the other site(s) that you want to use the agent on, go into ISAPI Filters, right click in the open space, and select Add. Name it “SiteMinder Agent” and the Executable points to webagentbinISAPI6WebAgent.dll. Then go into Handler Mappings, right click in the open space, and select “Add Wildcard Script Map”. Name it “handler-wa” and the Executable points to: webagentbinISAPI6WebAgent.dll. Restart IIS. If you intend to use this agent to serve up any authentication schemes, or password services forms, you will also need to create the siteminderagent virtual directory.
3) The Default Web Site has been removed, so I cannot use the Agent Config Wizard, how can I manually integrate the webagent into IIS?
Follow the same steps in #2 above to configure the agent into whatever virtual site(s) necessary.
4) The agent is starting, but I am not getting a webagent log.
Check permissions. The webagent installation guide explains that you need to give “Network Service” write permissions to whatever folder you want to write logs to. However, not all application pools run as Network Service. To verify who your application pool is running as, first, click on the virtual website where you are trying to run the webagent. Then, in the right pane, click on “Basic settings”. Check what the Application Pool is set to. Now click on “Application pools” in the left pane, select the application pool that this web site is using, then click “Advanced settings” in the right pane. Check what Identity is set to. This is the account that needs write permissions to the folder where the logs will be written. After that, if you are still not getting a log, check your Agent Configuration Object. Verify the values you have set LogFile=YES and LogFileName= webagent.log. Still no log? Check the WebAgentTrace.conf file in the webagentconfig directory. At the bottom of this file, it should look like this:
# For Apache 2.0, Apache 2.2, IIS 6.0 and SunOne Web Agents
components: AgentFramework, HTTPAgent
data: Date, Time, Pid, Tid, TransactionID, Function, Message
# For all other web agents
#data: Date, Time, Pid, Tid, TransactionID, Function, Message