Ben Ari's IAG Blog

Form Login Customization Troubleshooting

In a recent blog article, I wrote about form-login and how to create a custom one. Later on I thought it might be a good idea to details a little bit about the form-login mechanism, and how it works, which could be helpful in troubleshooting this if it does not work. Often times, one might write the custom XML file, but not be sure why it’s not working, with the result being an endless loop of trial-and-error.

The way form-login works is by injecting a small JavaScript by IAG into the form’s HTML. That JavaScript looks like this:

This function is set to run as soon as the form loads. IAG also looks throughout the HTML for the form fields that have been identified by the customized SSO file (FormLogin.xml), and injects the strings “whluser” and “whlpass” into them. When that form is received by the browser, it already has these strings in the user and pass fields, and the submit function. There’s also a piece of script to launch that function. The function enumerates the forms found in the page, and if it finds only one, it does a SUBMIT on it. If it finds more than one form, it will show a pop-up with the error “more than one form”. The form submit would typically be pretty fast, but usually not fast enough so that the user doesn’t see what’s happening.

Once the form has been submitted, it goes through the engine again, where the fields are replaced by the actual username and password of the user, which the IAG knows because that user has logged in earlier. These are sent to the backend server and the application logs in.

A typical problem with this is a mis-configuration that prevents IAG from identifying the right form. Key factors for success there are the application type and URL, and those often fail because of lack of understanding of how RegEx works.

If that part worked, but the user sees the form with the fields filled up by “whluser” and some password, this means the IAG engine correctly identified the form, but has been unable to submit it. This could be because the form itself has an unusual submit method. For example, many forms run some sanity JavaScript on submit or depend on some random click to do the submit instead of the common “submit” type button. There’s no generic solution for this, so the right way to go is to analyze the JavaScript code, and see what can be changed or bypassed. This is risky, as the JavaScript could be a security mechanism or add meta-data to the form that is not visible otherwise.

If you have identified changes that need to be made to the form, an AppWrap can help you along. Using AppWrap, you can make any changes you want to the form, including removing code or changing it completely. AppWrap is a tool with very few limitations, and as can be expected, this has some risks. Before making any changes with AppWrap (detailed in page 219 of the Advanced User Guide), be sure that you fine-tune it well enough so that it affects JUST your login form, and no other pieces or pages.

If the form submit does seem to go through, but brings up an authentication error, this might be related to the way IAG caches the user’s credentials. For example, some apps require the username to be in the format of a domain\user, as opposed to just the username. This can also be worked out, but that’s beyond the scope of this blog entry – this is addressed in the user guide.

Custom Form Login SSO how-to

One of the most important abilities of IAG is the single sign on, which lets connecting users access to internal applications without having to re-type their username and password. IAG contains multiple SSO mechanisms, but on some occasions, one might be required to create a custom one. The process of creating a custom login is thoroughly documented in Appendix C of the advanced user guide (Page 381), as well as here (http://technet.microsoft.com/en-us/library/dd282925.aspx), but here’s a summary of this procedure that should be easier to follow for creating simple customizations.

The 1^st step is to gather some details about the application. The details are:

1. Application Type. This parameter was selected when the application was initially published on IAG. To find it, look at the list of applications on the portal, and check what appears in “application type”

2. The internal URL of the login page.

3. The name of the username and password fields in the HTML form. For example:

Using these details, a custom XML file needs to be created, and placed on the server. The syntax of the file is this:

When filling the URL portion, keep in mind that IAG uses RegEx to match URLs, so it would generally be a good idea to feed in a general mask, with RegEx parameters. For example, the URL http://crmserver/userenv/login.asp should be input as .*userenv/login\.asp

In the above example, we substitute .* for the server name, as “.*” in RegEx means “everything and anything”. Later, we slash-out the dot before asp, because a dot is an operator in RegEx.

Another thing to take into account is the Multiple Login parameter. In the above example, I’ve set it to TRUE, which means that the form will be submitted anytime the user goes to the same page. The purpose of this is to meet situations in which a user logs out of the application, goes back to the IAG portal, and then re-launches the application. Setting the value to FALSE would not re-submit the form. Setting it to TRUE is usually a good idea, although in some cases, an application uses the same URL for multiple functions, and then setting the multiple login to true would cause IAG to try to re-submit the page every time.

Once the data has been filled out, save the file under the folder c:\whale-com\e-Gap\von\conf\wizarddefaults\FormLogin and name the file FormLogin.xml. Activate the IAG configuration, checking the option to apply changes made to external configuration files. This is all it takes!

LSP conflicts and IE crashes

I’ve written about troubleshooting client component issues with IAG in the past, and recently I’ve noticed some users running into a problem with LSP conflicts.

This problem manifests itself as IE crashes on the client, after connecting to the portal. The user would launch the portal URL, but after the IAG client components finished installing, the browser would hang or crash. Then, upon re-launching the browser, no website could be browsed-to, and that situation was only resolved by uninstalling the client components completely.

The cause for this is LSP conflicts. LSP, short for “Layered Service Provider” is piece of code (DLL) that uses Winsock APIs to insert itself into the TCP/IP stack. Then, an LSP can interact with internet traffic, such as the traffic that goes in the browser. An LSP could be, for example, a security tool that inspects the traffic before it reaches the browser, and filters out or blocks potential attacks. A system can have any number of LSPs, and when there’s more than one, they are registered in a certain order, and that could cause problems.

IAG’s client components are an LSP, and they are designed to be the sole LSP on a system. If another LSP is in place, it could cause an LSP Conflict, which would be seen to the user as the problem described above. Fortunately, LSP problems are easy to diagnose and resolve. To see a list of current LSPs, simple type this command in a CMD window:

netsh winsock show catalog type=lsp

Sample of a “good” LSP list

In the above screenshot, we see the result of a “good” output for the LSP list command, which shows only one LSP – IAG’s client components. If the list shows an additional entry, then good chance this is the culprit. In many cases, the cause of problems for IAG customers has been Windows’ built in parental controls, which are another program that is an LSP. When Parental controls are active, they might conflict with the client components and cause a problem.

When an LSP conflict occurs, the only thing one can do is to remove the offending LSP. This is done by gathering the catalog ID of the provider (1076 in the above screenshot, although it will be another number for other LSPs), and typing in this command in a CMD window:

Netsh winsock remove provider <Entry ID>

If the LSP is still loaded, it might require a reboot to get rid of it completely. If, for some reason, this command fails to remove the conflict, a utility called LSPFIX from http://cexx.org/lspfix.htm can help as well. This utility will display a list of LSPs that have been found, and by clicking the offending one and moving it to the “remove” pane, one can get rid of it:

Word of warning, though! LSPs are not a burden – they are an important feature of Windows, and an LSP on your system might have an important function. Even if it interrupts your plans to use IAG, one must practice caution and think carefully before removing one. It may turn out that the LSP has an important function (even if you don’t personally recognize its name) and removing it may jeopardize your security to some extent. I recommend performing the above actions carefully, and creating a system restore-point prior to making changes.

Creating a custom application template

IAG comes pre-populated with many application templates, but occasionally, one might need to customize them. A typical scenario is a need to use one of the client/server based templates, which automatically launch an SSL-VPN tunnel, and then notify the user that it is ready to launch the application. Here’s how to customize the default template to make it silent.

The difference between the regular GenericWebRelayMulti template and what we will be creating is the removal of one line:

<exec exe=" " flags="256" default="yes"/><!--All platforms-->

This line governs the behavior of the application, and removing it will silence the app. To do this, the 1^st step is to create a custom app template based on the regular, non-silent “Generic Browser-Embedded App (multi server)” app. Here are the steps:

1. Open the folder c:\Whale-Com\e-Gap\von\conf\wizarddefaults

2. Create a new folder under it named CustomUpdate

3. Create a new file in that folder, and name it WizardDefaultParam.Ini

4. Paste the following text into that file. Please note the bold text is key settings that are relevant to this customization:

Explanation: The top part tells IAG that this file contains info about a certain number of apps – one in our example. The 2^nd part is the details of the new app. Note that the section name needs to match the name specified in the “app1” line. The “name” parameter governs how it will look to the user in the app wizard. The SSLVPNTemplate setting tells IAG to which SSLVPN template this refers to, which we configure in the following steps:

5. Open the folder C:\Whale-Com\e-Gap\von\conf

6. Create a new folder under it named CustomUpdate

7. Create a new file under it and name it SSLVPNTemplates.xml

8. Paste the following text into that file. Please note the bold text is key settings that are relevant to this customization:

Explanation: The Config and Templates tag are generic file structure tags, while the rest are specific to this app. The areas enclosed in <!-- and --> are just comments, and they can be left out completely if one is so inclined. The Template Name is THE name of the template, which is referred to in the WizardDefaultParams mentioned above. It also has to be unique to other template names in the general SSLVPNTemplate.xml, so be sure to check that. Now, all you have to do is activate this, although that requires one extra step:

9. Open the IAG configuration console, and activate the configuration, checking the option to “apply changes made to external configuration files”.

10. Close the IAG configuration console AGAIN, and open it back.

Now, the new template named Silent Generic Browser-Embedded App (Multi Servers) will become available as the last item under the “browser embedded applications” category. The next step is creating a new application, based on the new template.

Block by block

A useful feature with IAG is the ability to block file uploads and downloads, which can be enforced based on various parameters, like file extension, size and more. While this seems pretty straight forward, as each application has an Upload/Download settings page, this may be confusing and some users try to set it and are not sure why their files are not being blocked.

To really understand how this works, It's important to realize that it requires the administrator to configure two things:

1) The application's Endpoint upload and download policy

2) The application's Download/Upload tab parameters

Many mistakenly think that setting just one of the above is enough. Here's a brief description of how this works:

1) The upload/download tab in the application properties is only used to identify the properties that will be used to determine what is considered an upload or download.

2) The selected endpoint policy is used to set what to do about the upload and download

Essentially, IAG looks at each file the user tries to upload or download with this application, and checks the upload/download policy against the properties of this file. If the file matches them, then it is classified as an upload or download, and the selected upload or download policy is applied to it. If that policy is set to TRUE, or an expression that amounts to a value of TRUE, then the Download/upload operation is allowed. If that policy is set to FALSE, or an expression that amounts to a value of FALSE, then the Download/upload operation is blocked.

Usually, an administrator wishes to block a file if the connecting user has not secured his computer, so they would choose a conditional policy like "Default Web Application Upload". This policy is set to TRUE if the user has an AntiVirus product that is installed, running and updated. If the AV is not installed, not running or not updated, the policy will fail (Be set to FALSE), and then the download will be blocked (Again, the block will only apply to a file that matches the parameters defined in the upload/download tab). By the way, this policy, even though it's named "upload", can be used to control a download as well, by selecting it as the download policy in the download policy drop-down. If the administrator just wants to block these downloads, all that needs to be done is to use the NEVER policy, which always amounts to FALSE.

For example, the IAG administrator wants to block *.exe and *.com executables from being uploaded. The administrator needs to set the Upload Policy on the Application’s General tab to “Never”. Then set the Uploads settings on the Application’s Download/Upload tab to “Identify by Extensions” and select the "Include" radio button. In the extension list add on their own lines, exe and com (both without a dot before the extension). Make sure to uncheck Identify by URLs and Identify by Size or more potentially be blocked then you expect. This means that any other file types WILL be allowed.

Another example:

For example, the IAG administrator wants only common image files to be allowed to download. The administrator needs to set the download Policy on the Application’s General tab to “Never”. Then set the download settings on the Application’s Download/Upload tab to “Identify by Extensions” and select the "EXCLUDE" radio button. In the extension list add on their own lines the common image types (jpg, jpeg, gif, png, bmp etc), all without a dot before the extension. Also, the administrator must exclude the extension types used by the website itself, like asp, htm, html etc, otherwise, the site itself would not be allowed as the "never" policy selected will prevent these files from being accessed.

Many users need to enable this functionality in order to block OWA users from being able to download attachments, or include attachments if their endpoint does not meet a specific requirement, like an AV or Firewall. IAG Includes a settings that is very suitable for things of this nature. This setting is based on blocking a URL, rather than blocking by extension. The Download/upload tab has a setting for “identify by URL”. When this setting is checked, IAG will check the global download and upload URL settings, and use these to determine if the requested URL is indeed a download or upload, and if so, will apply the policy (to block, or allow) to it. An administrator can define anything he wants in the global Download/Upload URL settings, which are under Advanced Trunk Configuration/Global URL Settings/Download URLs and Upload URLs. Once an OWA application is created, these settings will be updated with the URLs that are used for downloads and uploads in OWA. For example, a download in OWA has this format:

/owa/attachment.ashx?attach=1&id=<something>

The download settings will include this expression:

/owa/attachment\.ashx\?(attach\=1)?(\&)?id=.*

Which will tell IAG to tag the URL with the downloaded attachment as a “download”, and if the download policy for OWA is set to FALSE, the attachment will be blocked. Similar settings can be set for other types of applications, provided you are able to correctly analyze the structure of the URL you want to block. This is not always easy, but with some careful planning, can provide with great security AND flexibility!

One last VERY important tip!

Some user define the policy correctly, but it still appears not to block anything. This usually happens because the application is set to “learn mode”. This is set in the application property, on the “Web Settings” tab. Learn mode is useful for early stages of an application implementation, but it will also cause IAG to ignore most of the security mechanisms, including the attachment blocking. Make sure it’s turned off to properly test upload/download blocking!

Grease up those hands

An important piece in the way IAG works is called URL signing. This process involves the server adding a string of seemingly-random characters to links. The string is not random at all, really, and the purpose of this is to allow IAG to communicate with many internal servers, while using just one IP and Port externally. Since the requests from the client all come-in on the same port and IP, but are destined for one of (possibly) many internal servers, IAG recognizes to which server to direct the request based on the unique "signature". For example:

The process that goes on back-stage is that the IAG Engine, as it reads a page from the back-end server and passes it along to the end-user, looks for links in the HTML code, and matches them to internal servers that it "knows" about (because they appear in the configuration of one of the applications). It then changes the links and adds the unique key assigned to that application. Later on, when the user clicks on one of the signed links, the IAG parses the URL and knows from which internal server to fetch the data.

This is all nice and neat under normal conditions, but  the process of locating the links in the HTML is not always so simple. One challenge is that sometimes, the links are built dynamically by JavaScript. For example, the script could concatenate the target URL like this:

In this case, the formatting of the target URL is unusual:
&quot;/Point/com/composite.aspx?_DF=OMSm_NRTOtgSum_byOrg_T&amp;Filter=5=TelAviv&quot;

This prevents the engine from recognizing this is a URL, and so it gets passed on as-is. The result is that a link points to a non-existent URL, and an error is displayed to the end user.

The solution to this type of problems is to use a component of IAG called "SRA", and add a custom-tailored instructions that will let it recognize the malformed URL and "fix" it, so that it can later sign it properly. In this case, we would change it to something like:
&quot;http://mapserver/Point/com/composite.aspx?_DF=OMSm_NRTOtgSum_byOrg_T&amp;Filter=5=TelAviv&quot;

The standard HTTP:// prefix is all that's needed to let the magic happen. I will not go into detail on using SRA here, as it is well documented in the IAG User Guide, but I do want to talk a little more about a more complicated aspect of this. Sometimes, the code is so complicated that it's hard to determine where the offending function is. There is, however, a way to get better control by using a debugger.

No...don't be scared. I'm not talking about a 4-year course in writing software. In fact, one does not have to know JavaScript to do this - just a little common sense. The tool we would use is the Debugger included with Internet Explorer 8. Keep in mind that at this time, IE8 is not supported by IAG, so you will have to fire it in Compatibility Mode (Open the Tools menu, and select "Compatibility View Settings").

The next step is to go to the page that's before where the "bad" links are at and press F12 to open the developer tools. On that page, click "Script" and "Start Debugging". Next, click on "Break All", or press Ctrl+Shift+B on your keyboard. Now, the debugger is waiting, and as soon as ANY JavaScript is run, it will stop. Now, click on the link that brings you the problematic page (we do it this way, because the scripts often run at the time the next page load).

Now, once the scripts start running, the debugger will stop on a script line, and that's where the magic happens. On the right-hand part of the debugger screen, click "Locals", and that will show you the current variables. Now, use F11 to make the script continue, line-by-line, and watch the values of locals as they get created, assigned and discarded. At some point, you should see the problematic link being created and assigned to a variable. This would require some understanding of JavaScript, and fixing it is a whole other business, but this is how it's done.

A little addition to drive mapping

I already discussed Drive Mapping with IAG several times, but one thing I failed to address properly is the “setup” issue. In the April 16 entry, “Fetch me my files, please”, I’ve explained that for the drive mapping to work, a registry setting must be set on each client. Most users just create the Drive-Mapping setup application, as I detailed in that entry, but that could be a problem as it applies the setting without actually checking if it was already set before. This means that if the administrator sets this app to run on portal access, or as a prerequisite to the regular Drive Mapping app, the user will be prompted to reboot his computer even though there’s no need for that.

I’ve written a little additional customization that helps. It’s based on creating a VBScript file on-the-fly, and it checks the registry setting and proceeds accordingly. If the setting was already present, it will do nothing visible. If it hasn’t, or has been set to the wrong value, it will make the change, and prompt the client to reboot the machine.

This is the code:

This piece would ideally be integrated into the drive mapping itself, so it could be either implemented into the customization I suggested in the blog entry “Drive them crazy” (Add it above the line @set Fullusername=%3 ), or, if you plan to use the regular drive mapping, without the user-drive customization, just create a regular customization of the drive mapping application and add this to it.

Drive them crazy

IAG's Local Drive Mapping feature is useful for creating a work environment for your users that is similar to what they have at the office, but the default app is only good for mapping a specific share for all users. Most organizations also have a personal drive for each user, mapped from his Active-Directory profile.

It's relatively easy to create a custom application template that will achieve the same results. This is done by adding a few commands to get the connecting user's username (IAG has them from the log in credentials), and adding those to the drive mapping command.

To do this, follow these steps:

1) Close the IAG configuration console.

2) Copy the following code, and save it as SSLVPNTemplates.xml under the folder c:\whale-com\e-gap\von\conf\CustomUpdate on the IAG Server. If the CustomUpdate folder does not exist, create it.

3) Copy the following code and save it as the file WizardDefaultParam.ini under the folder c:\whale-com\e-gap\von\conf\WizardDefaults\CustomUpdate on the IAG Server. If the CustomUpdate folder does not exist, create it.

4) Launch the IAG configuration console, and ADD a new application. The new application would appear as "User Home Drive Mapping" , the last item under the "Client/Server and Legacy Applications" container.

5) In Step 3 of the application wizard, type in the server's hostname (Netbios name), without a prefix. Enter the Share name, where all the user's folders are stored. Most organizations have a general share named "users", or something similar, and under each, the user's own folders, named after their usernames. If the individual user shares are one or more levels down, enter the double-level, with the backslash. for example, if the share format is \\fileserver\shares\userfolders\WShakespeare, the settings would be like this screenshot:

This is a more conventional setting:

6) Don't forget to have the application added to the portal by checking the V in step 4.

7) Activate the configuration.

It's common to have the application set to launch automatically when entering the portal. To do this, open the "Whale Portal" application for editing, and add a Check next to the drive mapping application in the Prerequisite Applications list:

Another thing you need to keep in mind is that this application requires some registry changes to be applied on the client machine. This needs to be done only once, and after which the client machine needs to be rebooted. This can be done by creating the "Local Drive Mapping Setup" application, and running it once on the clients. Many administrators mistakenly set the "setup" application to be a pre-requisite of the portal, or of the drive-mapping application itself, which is redundant, and confusing, because it tells the users to reboot their computer all the time.

Report to the principal's office

While school days might be over for this year, thank goodness, I want to talk a little about SharePoint and SQL Server™ Reporting Services. This is quite a popular feature with MOSS, but when IAG is in the picture, things don't always turn out well.

For those who don't know it, the SQL Server™ Reporting Services for SharePoint allows the user to display a Web Part that queries SQL and display reports. The Web Part (Report Viewer Web Part) allows the user to export to other rendering formats, do page navigation, search, print, and zoom within a report. The user can also create subscriptions and schedules, manage reports, models, and data sources. Fabulous.

The problem starts when you need to publish this to the outside world. When working with SharePoint, IAG has a special template called "SharePoint 2007 (With AAM)" that relies on Sharepoint's Alternative Access Mapping feature to perform link translation. For those not familiar with AAM, it's a component that "knows" when a page is requested from "outside" (as opposed to a request coming from a computer on the corporate network), and serves the page with the links in it translated to what is defined as the external name. When configured correctly, AAM allows for a nearly transparent integration of SharePoint with various publishing products like ISA and IAG.

So, configuring AAM is very important if we want to get SharePoint to be accessible properly, but unfortunately, SQL Server™ Reporting Services for SharePoint (a.k.a. SRSS) does not support AAM. This means that when a SRSS webpart is opened, it cannot use the AAM component to translate the links, and so it does not have access to the data and displays various error messages.

What can you do? Well, since AAM is out of the picture, the only way to get it to work is if the external links are identical to the internal links. In other words, if the SharePoint server is accessible from outside using the exact same links as internally. This is not impossible, but not very common. To do this, you would have to give the SharePoint server a hostname that makes sense (for example - http://sps is great, but http://pokmnsuyiwekjh08.local is not so great), and create a public DNS entry for the SharePoint server that will match it. For example, if your server's internal hostname is sps01, and it's a member of the domain contoso.com, then a public DNS entry would have to be made for sps01.contoso.com. The IP on that host record would be the external IP of the IAG Server. Another requirement here is that the same protocol (HTTP or HTTPS) will be used too, and that might complicate things with regards to getting the certificate to match the name. It's also important to note that in such a configuration, there's no need for link translation, as both internal and external links are the same, and so AAM does not need to be configured at all. You can read more about this in this blog: http://blogs.technet.com/edgeaccessblog/archive/2008/10/13/publishing-sharepoint-with-iag-2007-part-3-sharepoint-topologies.aspx

If you were able to pass all these hurdles, then the SRSS web parts should come to life and work just like they do externally. Good luck with your reports!

Policy Chase

With the introduction of SP2 for IAG, the process of creating custom endpoint detection policies has been slightly altered, as it now supports creating separate policies for Linux and Mac computers. Today I'll details a step by step guide to creating custom policies.

Before we continue, I'd like to point out that IAG comes with a pretty extensive set of pre-configured policies. For example, the "Default Non Web Application Access" policy checks for the existence of any of the supported Anti Virus, as well as other parameters like Certified Endpoint, IAG components installed and running etc. Another useful policy is "SecureView for OWA2003 SP1", which just checks for the existence of any anti-virus product to give access. Using custom policies, you can adjust the allowed endpoints with much details. You could, for example, allow your company's officially supported Anti-Virus, but not any others.

Here are the steps for creating a custom policy.

1. In the IAG configuration console, click on the trunk you want to apply the policy to.

2. Click on "advanced Trunk Configuration"

3. Switch to the "Session" page and click "Manage Policies" on the bottom-left.

4. Click "Add Policy"

5. Give your new policy a name and a description.

6. Click on "Manage Windows Policy"

7. Click "Add Policy"

8. Give your new policy a name and a description.

9. Click on one of the groups that is on the left, according to your desired configuration. For example, if you wish your new policy to allow access only to users running AVG Anti-Virus, click on the "Anti Virus" item.

10. Check "Enable Group"

11. Check any Anti-Virus product that you want to allow on the clients. You can select one, several, or "Any WMI Anti-Virus".

12. For any of the Anti-Virus products, you can change the minimum allowed version by double-clicking the relevant cell on the Version column, and changing the number to what suits your needs.

13. Similarly, you can change the required update period to a different number than the default 7 (1 week)

14. You can now click on another group, to add criteria for acceptance. For example, a popular requirement is to set only specific browsers or operating systems as permitted.

16. You may, at any point, click on "create as script", which converts the policy from a UI-based edit mode to a text-based edit mode. This could be useful for very fine-grain settings, like requiring two AV products. To do this, you need to change the syntax to requires AV1 AND AV2, rather than the regular syntax of AV1 OR AV2. Please keep in mind that this level of editing is tricky, and that once you convert the settings to script, you cannot change it back to a graphic-based editing mode.

17. Once you are done with editing the policy, click OK and click Close.

18. You are now back at the 1st policy settings page - you can now select your new policy from the drop-down selector that is under the "Select Platform-Specific policies" option.

19. If your organization hosts clients that are not running windows, use a similar procedure as outlined in steps 6-17 to create a policy for Mac OS, Linux and Other platforms. This is not mandatory - you can just set them to "Always" or "Never".

20. Click OK and Close

21. Now, the new policy is saved and available to be assigned. It can be assigned at the trunk level, or at the application level. For example, you could set it so that any anti-virus is allowed on the portal, but only people with Windows Defender can run the network connector:

Performance Anxiety

Recently, I was in need of doing some performance troubleshooting, and used Windows’s built in performance monitor, naturally. While doing this, I noticed that although I configured the monitor to log the counters for some processes (like IIS’s processes), when I was opening the log file for review on my server, I wasn’t seeing any of that shown. I did see a bunch of graphs for other relevant objects, but not the Process object. I tried logging and relogging the server several times, but to no avail.

After drilling into this for a while, I was kindly told that the monitor hides this data by default, as the displaying the process information is CPU-intensive. This could be easily solved by clicking on the + sign at the top, and adding the process info:

Of course…the resulting graph might be a bit crowded:

I’m also glad to report that this behavior has been changed for Windows 7 and Windows 2008 R2. With these OS versions, the default behavior is to display all the counters. If you were conflicted about upgrading to Windows 7…here’s your solid reason to go ahead!

Fetch me my files, please

An often-missed feature of IAG is the ability to let users access shares on internal servers when connecting to the IAG portal. This is done using the drive mapping application, which activates the SSL-VPN component of IAG and performs a NET USE command to pre-defined shares. It is particularly useful to create such a mapping to a company-wide file share and set this to launch automatically upon portal logon, but it does require some attention to work properly.

The 1st thing one should know is that this mapping only works on Windows 2000, XP and 2003. It does not work on Vista or Server 2008 clients. Secondly, for this feature to work, the computer needs to have NetBios’ SmbDeviceEnabled registry key set to 0. The easiest way to set this is to create the “Drive Mapping Setup” application, which creates this registry key when launched. This application needs to be launched only once on each client, and requires the computer the be rebooted afterwards. To create this application, follow these steps:

1. Open the IAG configuration console.
2. Go to the relevant trunk
3. Click Add and check Client/Server and Legacy Applications
4. From the drop-down, select Local Drive Mapping Setup (Windows XP/2003)
5. Give the application a name and set the access policy
6. If you’d like, set the application to launch automatically on start, but keep in mind that it will always prompt the user to reboot the computer even if the settings are already in place and a reboot is not necessary.

another way to set this registry key is by simply editing the registry. To do this, open the registry editor on the client computer and create the DWORD value SmbDeviceEnabled under the key HKLM\System\CurrentControlSet\Services\NetBT\Parameters (the value's data should be 0, which is the default). This also requires a reboot of the client, which can be done using a script. The following VB Script detects if the key already exists, and only if it does not it creates it and reboots the computer:

To use this script, paste the code into a file with the extension .VBS, and have your users run it.

The local drive mapping application can be created as many times as needed, thereby mapping several drives. Another interesting thing that can be done is customizing the template file to perform other batch commands. The file that performs the mapping is located here:
c:\whale-com\e-gap\von\conf\sslvpntemplates.xml

At line 270 in this file, you can find the dos batch commands that are performed, and additional commands can be added – for example, to run some script or execute a program. Just be sure not to edit the file directly, but to copy it into the CustomUpdate folder and then edit the copy, as is the standard procedure with all IAG customizations. After the modifications has been done, the configuration needs to be activated, with “Apply changes made to external configuration files” checked.

Hunt a virus

One of the best features of IAG is its ability to detect a connecting clients Anti-virus software, and block access to clients who do not conform to the policy defined by the server administrator. This is an effective way to prevent a virus infection from connecting clients. This detection is performed by the IAG Client components that are installed on the client machine when the user connects to the IAG portal externally for the 1st time. The Anti Virus detection is based on a system policy that is pre-set in the IAG server. IAG Server ships with a pre-defined policy that contains definitions for many AV products, but like any other software products, AV software changes and evolves alongside the operating systems that host them, and so the IAG policy requires updates from time to time. With some of IAG Service Packs and minor updates, the AV detection policy has been enhanced, but as some customers have discovered, installing the latest service pack and update doesn't necessarily update the policy. This is done to protect the customer, as the policy is editable by the administrator. The update engine cannot analyze the existing policy and apply an incremental or differential update, and so the policy does not get updated.

A recent AV update that might raise a problem for servers with outdated policies is the Symantec latest AV product Symantec Endpoint Protection 11 (a.k.a SEP11). Another product that is known to stir up some problems is AVG 8.5 is. The symptom of such an issue would be client computers running one of these products don't see any applications upon entering the IAG portal, or seeing grayed-out applications. If this is the case, an administrator can diagnose this easily by opening the Web Monitor application on the IAG server. On the Web monitor, open the Session tab and click on the session of the user who is experiencing the issue. On the session page, click on the "Parameters" tab and look for a parameter named ANY_ANTI_VIRUS. If it is set to FALSE, then it means that the policy has failed to detect the AV and might require updating. Before you make changes to the policy, the administrator should verify that the IAG server is fully updated to the latest version. Currently (April 2009), IAG 3.7 SP2 Update 1 is that version, and it includes several fixes for the detection components that are required. For the latest update, contact Microsoft Technical support.

To view or edit the current policy, follow these steps:

1) Open the policy editor on your IAG machine by opening "Advanced Trunk Configuration", switching to Session and clicking "Manage Policies"

2) Expand EXPRESSIONS (at the bottom of the list)

3) Double Click "any Antivirus"

4) Click Manage Windows Expressions

5) Expand EXPRESSIONS again (at the bottom of the list)

6) Double Click "any Antivirus(Windows)"

You should see a screen like this:

7) For safety's sake, copy and paste the current content on the right into some text file and save it somewhere.

8) REPLACE this with the contents of the attached file.

9) Click OK back through all the screens, and activate the configuration.

It's important to be careful when editing the policy, as it uses sensitive Boolean syntax. Even a simple line-break could wreak havoc. In the policy editor, the view is wrapped, but it's actually just one long line, with a lot of Boolean operators that are the key for it to work.

Here is the current latest policy (April 2009) :

Configuring a ClickOnce Application using IAG

ClickOnce is a deployment technology that allows you to create self-updating Windows-based applications that can be installed and run with minimal user interaction. ClickOnce deployment overcomes three major issues inherent in deployment:

Difficulties in updating applications. With Microsoft Windows Installer deployment, whenever an application is updated, the user must reinstall the entire application; with ClickOnce deployment, you can provide updates automatically. Only those portions of the application that have changed are downloaded, then the full, updated application is reinstalled from a new side-by-side folder.

Impact to the user's computer. With Windows Installer deployment, applications often rely on shared components, with the potential for versioning conflicts; with ClickOnce deployment, each application is self-contained and cannot interfere with other applications.

Security permissions. Windows Installer deployment requires administrative permissions and allows only limited user installation; ClickOnce deployment allows non-administrative users to install and grants only those Code Access Security permissions necessary for the application.

In the past, these issues sometimes caused developers to decide to create Web applications rather than Windows-based applications, sacrificing the rich user interface and responsiveness of Windows Forms for ease of installation. With applications deployed using ClickOnce, you can have the best of both technologies.

For more information about ClickOnce technology, visit this link: http://msdn.microsoft.com/en-us/vbasic/ms789088.aspx

Publishing a ClickOnce application using IAG is tricky, as the application uses a component of the .Net framework to launch the application, and since this component (DFSVC) runs outside the browser, the application must be tunneled to be able to run. This technique for publishing application is known as "Localhost Redirector publishing", and can also be used for several other troublesome apps, such as some JAVA-based applications. Here are the steps that must be taken to publish such an application.

1. On the IAG server, open the system hosts file with a text editor (c:\windows\system32\drivers\etc\hosts)

2. Add an entry:

127.0.0.1              localhost1

3. Open the IAG Console

4. Disable any current applications you have that are related to this server, as they might conflict with it.

5. Create a new application.

6. Under Browser-Embedded application, select Generic Browser-Embedded App and click Next

7. Type in an application name to your liking

8. In the Web Servers page, type in:

Addresses: localhost1

Paths: /

Modify port 80 for HTTP to 6001

Remove the HTTPS port 443.

Click Next

9. In the authentication type, leave the "automatically reply" settings unchanged. Click Next

10. In the Server Settings Page, type in:

Server : Type the internal name of the server that is hosting the application

Ports: 80

Click Next

11. In the Portal  Link page, type in the application URL according to the following template:

http://localhost1:6001/internalsite/redir.asp?TARGET=<internal full URL of the application>

For example, say that internal users would browse to http://somehost/somepath/publish.htm and then click a button to run it (as is typical with ClickOnce apps) to launch it, then this settings would be:

http://localhost1:6001/internalsite/redir.asp?TARGET=http://somehost/somepath/publish.htm

*Please note that the word TARGET is case sensitive.

Click Next

12. Activate the configuration.

13. Launch the application on the client will display a notice: "Ready to launch application". After you click OK, it will launch the IAG SSL component, visible as a two-arrow icon on the system tray on the client machine. The browser will then display the standard Publish.htm. Clicking on the RUN button in it will launch the application. It’s possible to customize the default template to not display the above message, but I’ll talk about that another time.

Troubleshooting IAG Client installation issues

The IAG client components are an important part of the endpoint security that the product provides, as these detect and report back to the server what is running on that computer, and more importantly - what's not running. The client tools also are also an important part of other functionality, like SSL-VPN and the attachment wiper.

Normally, the client components install automatically whenever a user connects to the IAG Server for the 1st time, and then are invoked when the user reconnects to the server. In some situations, the client components may become corrupted, so here are some steps that can be taken to troubleshoot them. This guide assumes that the trouble is occurring on a single machine, and is not a network-wide issue, which would require server-side troubleshooting. Also, this guide refers to Windows XP with IE, and is not applicable to Operating systems and browsers that are based on the JAVA client component mechanism.

Before we begin troubleshooting, I'd like to outline the standard installation procedure for the client components. The client components are based on ActiveX technology, and their installation is initiated automatically when open the IAG portal for the 1st time. This requires administrative permissions (or elevated permissions using Vista UAC), although upon returning to the portal later on, the components can run as a normal user. There are other security settings that might hinder the client installations, and that is the 1st troubleshooting step:

1.       1st, Verify the security settings on the client machine. To do this, open Internet Explorer settings, and go to Security. Click on Trusted Sites, and make sure that the IAG site appears on the list, or add it:

2.       Next, reset the security level for the trusted sites to the default by clicking on Default Level:

3.       If, for some reason, you are not at liberty to use the default level, click on Custom Level, and verify that Active-X controls are not disabled.

4.       If a firewall is running on the machine, either disable it, or set it to allow access to the programs:

%programfiles%\Whale Communications\Client Components\3.1.0\WhlCach3.exe

%programfiles%\Whale Communications\Client Components\3.1.0\WhlDetct.dll

5.       At this point, retry installing the client by restarting the browser and going back to the IAG site.

6.       The next step is to manually install the client components. The client components installer is available as an Executable file on the c:\whale-com\e-gap\von\PortalHomePage folder. If the server is IAG 3.7 SP2 or above, then it is also available as a Microsoft Installer package (MSI), suitable for automated corporate AD-based deployments. Copy the installer to the client, and run it to install.

7.       If the manual installation fails, or the components are still not working, then the next phase is to perform a manual clean-up of the client components:

a.       Uninstall the client components using the windows Add/Remove programs control panel.

b.      Use Task Manager to end the process DMService.exe, if it is running.

c.       Delete the folder Whale Communications from your Program Files folder.

d.      Open the folder c:\windows\downloaded program files and delete any folders with the name DM.* (DM.0, DM.1 etc). You would be required to do this using a command-prompt, as this folder is set to hide its contents.

e.      In the same folder, delete DMService.exe and WhlMgr.dll, if they exist.

f.        In the same folder, look for a file named WhlCompMgr.inf, and open it with notepad. Look for a line with a format similar to this, and note the number in the parentheses:

clsid={8D9563A9-8D5F-459B-87F2-BA842255CB9A}. This number is your CLSID, and it changes between various versions and updates of IAG.

g.       Open the registry editor, backup the following keys, and then delete them:

                                                               i.      HK_Classes_Root\<CLSID>  

*<CLSID> refers to the code you found in the previous step.

                                                             ii.      HK_Classes_Root\ComponentManager.Installer

                                                            iii.      HK_Classes_Root\ComponentManager.Installer.1

                                                           iv.      HK_Classes_Root\ComponentManager.Installer.2

                                                             v.      HKLM\Software\WhaleCom

                                                           vi.      HKCU\Software\Microsoft\Windows\CurrentVersion\Ext\Stats\<CLSID>

                                                          vii.      HKCU\Software\Microsoft\Code Store Database\Distribution Units\<CLSID>

                                                        viii.      HKCU\Software\Microsoft\Windows\CurrentVersion\ModuleUsage\C:/WINDOWS/Downloaded Program Files/WhlMgr.dll

*Note that not all keys necessarily exist on each machine.

h.      Delete the file WhlCompMgr.inf referred to in step F

i.         Reboot the client machine.

8.       If the client installation was successful, but the client is still unable to login or access the IAG site properly, the next step is to activate client logging. These logs can be used by the IAG support team to analyze specific issues with the client. To turn on client logging, follow these steps:

a.       Locate the file ctrace.xml at c:\Program Files\Whale Communications\Client Components\3.1.0\

b.      Open the file using a text editor.

c.       Look for lines starting with <Configuration. There should be 11 of them, each related to logging a different part of the client components. At the end of these lines, change Enabled="False" to Enabled="True", and save the file.

d.      In a Command prompt, go to that folder, and type the command ctrace activate ctrace.xml

e.      Logging will start - log on to the portal and perform the actions that led to the issue.

f.        Open the file ctrace.xml again, and change the True back to False. Save the file.

g.       In a Command prompt, go to that folder, and type the command ctrace activate ctrace.xml to stop the logging.

*Although the command is "Activate", it actually de-activates logging, according to the "False" settings within the XML file.

h.      Locate the log file under the system's temp folder (%temp%)

9.       If the client installation still fails after the deep cleanup, or it does not give out an error message, use "Pre-Emptive" logging to log the installation process:

a.       Create a new text file.

b.      Visit the following KB, and copy/paste the registry information from it into the new file. This sets the registry to activate the logging:

http://support.microsoft.com/kb/955101

c.       Save the file as ActivateTracing.REG and execute it to write the data to the registry. Logging will start.

d.      Install the client components again, either manually or by logging on to the portal.

e.      Locate the log files at these locations:

%temp%\*.csv

%windir%\temp\*.csv

c:\temp\*.csv

%temp%\low\*.csv

%temp%\low\low\*.csv

"%programfiles%\Whale Communications\Client Components\3.1.0\*.log

10.   If the logging has been unsuccessful, or the logs do not contain significant info about the issue, a last resort is to perform a deep reset of Internet Explorer. This measure is equivalent to uninstalling and re-installing Internet Explorer, and resets all settings to the default, including removing installed toolbars and plug ins. Please be aware that running this might cause a severe change in IE, so use this script only if all else has failed. To use it, create a text file, and copy the following script into it:

11.   Save the file as IEReset.bat and execute it. Reboot the client computer and try to install the client components again.