Inside the Web Interface Configuration File
The majority of Citrix administrators make all required configuration changes to their respective Web Interface “Access Platform Sites” within the Access Management Console. A few of those folks who have been using Web Interface since the days when it was branded “NFuse” or “NFuse Classic” are keenly aware these configuration settings actually reside in a text file; WebInterface.conf. This article will delve into some of the more useful settings in this file, point out examples of useful settings, and provide a few tips for successfully editing the WebInterface.conf file.
In the old days of Citrix NFuse there were very few configuration changes that could be performed from the GUI management utility provided with the original versions of NFuse and NFuse Classic. A great opportunity existed for Citrix resellers and consultants to provide NFuse customizations for many customers for one simple reason; you had to understand the settings within a few specific files in order to successfully implement these changes. The majority of these settings were found in the NFuse.conf file, and are still found today in the renamed WebInterface.conf file. Many more settings are present today than in the earlier versions of NFuse, but several remain the same. Although there are many fewer configuration changes that must be performed manually by editing this file, understanding the settings in this key file can aid in implementing properly configured Web Interface sites as well as greatly aid in troubleshooting Web Interface when things go bad.
WebInterface.conf Has Been Renamed and Moved
If anyone is still using an older version of NFuse or Web Interface in your production environments you may have trouble locating the WebInterface.conf file. This file is no longer located under “C:\Program Files\Citrix\....” as it was in earlier versions. This is an important change that has provided the ability to deploy multiple Web Interface sites that contain differing configurations on the same web server. There will be a specific WebInterface.conf file for each Web Interface “Access Platform” cite created on a given web server. For default installations, look under the “Inetpub\wwwroot\AccessPlatform\conf” directory to find the WebInterface.conf file. As a bonus, you will also find the various default template .ica files that contain valuable settings as well. Be advised any changes made directly to the WebInterface.conf file will not be in effect until the particular web site or IIS is restarted. Make sure you follow best practices and create a backup copy of this file prior to making any changes.
A few more tips before we open the contents of the WebInterface.conf file will ensure obstacles are few. During the creation of an “Access Platform” site the create site wizard presents the opportunity to store the Web Interface configuration on a Citrix Presentation Server running the XML service. Figure 1 illustrates the two choices for storing the Web Interface configuration:
Additionally, multiple XML servers (Presentation Servers) may be specified to provide for failover as figure 2 indicates:
When this option for centralized configuration is chosen, the WebInterface.conf file will no longer be found on the web server. This article focuses on editing the WebInterface.conf file, which requires the Web Interface configuration to reside locally on the web server. If you wish to manually edit the configuration for centrally configured Web Interface sites (ie, the configuration is stored on a Presentation Server(s) via the XML service), you must export the configuration to a file, make the required changes, then import the configuration from the file.
Figure 3 below shows a glimpse into the first few lines of a standard WebInterface.conf file, prior to any configuration changes:
The first thing to point out is the requirement to save the file in UTF-8 encoded format; not standard ANSI or Unicode formats. Certain settings, such as those to allow a user the ability to customize different items on the Web Interface site, such as Windows Size (AllowCustomWinSize) are fairly easy to decipher. Other items are not as easy to understand. Please refer to page 137 of the Web Interface Administrator’s Guide for explanations of most WebInterface.conf file parameters.
The parameters in Figure 4 can be confusing and require a brief explanation. The first and third parameters are specific to the self-service password reset functionality provided by Citrix Password Manager, the Citrix Single Sign On solution. If you are using Password Manager and have configured it in such a way as to enable users to reset their own passwords and/or unlock their own accounts, you will need to ensure these two settings are changed. Simply change AllowUserAccountUnlock and/or AllowUserPasswordReset to “on” as you desire. The middle parameter in Figure 4 enables users to change their passwords from the Web Interface server. Acceptable entries are
- Never – Users are NOT permitted to change their account password
- Expired-Only – Users may change their passwords ONLY when their password is about to expire. (The warning period is set by the PasswordExpiryWarningPeriod parameter and the default is 14 days)
- Always – Users can change their password anytime they so choose
ICA Client Version Information
One of the things that constantly stands out when auditing existing Web Interface installations is the version of ICA client that is in use. A majority of the time it will be the same client version that was present with the original installation of that particular version of Web Interface. The reason for this is simple; few Citrix administrators were able to successfully update the version of ICA client for auto-detection and deployment from a Web Interface site. The current release of Web Interface (4.5) provides the ability to access the client version within the Access Management Console as shown in Figure 5 below.
However, as you dig a little deeper certain limitations are exposed. Figure 6 shows the current client version, 9.0.32891. This is the original 9.0 ICA client (build number 32891), which had a few issues (some would say “bugs”) that were addressed in later 9.x releases. While it is possible to replace the actual ICA client files with newer versions, you must ensure additional changes are made in order to automate the deployment of the newer version of ICA client. The “Client Version” needs to be configured as well as the Class ID for the cab file version of the ICA Web Client (the default Web Interface client). Figure 7 illustrates the location in the Access Management Console that provides client version that is checked for when the user connects to the Web Interface site. The location used to change the class ID for the automatically deployed ICA client is depicted in Figure 8.
The following lines depicted in Figure 9 in the WebInterface.conf file contain this pertinent ICA client information. Citrix provides many different ICA clients for Windows 32 bit operating systems. There are multiple “Web” clients as well. In order to reconfigure a Web interface site to deploy one of the other 32-bit Windows ICA clients, the changes must be made manually to the WebInterface.conf file. There is no option for changing the line “IcaWebClient=icaweb.cab” from within the Access Management Console. Furthermore, if changes were made via the Access Management Console in an attempt to deploy a different client version, which resulted in breaking the automated ICA client deployment (a common situation for many Citrix administrators), knowing where the actual configuration lives can greatly enhance your ability to resolve the issue.
Understanding where the majority of site-specific Web Interface configuration settings reside should provide administrators with more ammunition for maintaining, customizing, and troubleshooting Web Interface sites. In addition, having a better understanding of the available parameters within this powerful configuration file can empower Citrix administrators to go above and beyond what is present in the Access Management Console. I encourage everyone who has deployed or is planning to deploy Web Interface to research the Web Interface Administrator’s Guide and spend some time with a test or development Web Interface server. You may be surprised by how much configuration options really exist.