WI4 Troubleshooters Guide

Web Interface 4.
0
Troubleshooter’s Guide
Author Jay Tomlin

Department Technical Support
Revision 2.0
Distribution Public
1
Web Interface 4.0 Troubleshooter’s Guide
Table of Contents
About this document ..........................................................................................3
1. What’s new in Web Interface 4.0 ........................................................................4
1.1 New features for the end user........................................................................4
1.2 New features for the administrator..................................................................4
1.3 Installer changes ........................................................................................5
1.4 XML Service changes ...................................................................................5
1.5 Design changes ..........................................................................................5
2. Platform support ............................................................................................6
2.1 Supported Server Platforms ...........................................................................6
2.2 Supported Web Browsers ..............................................................................6
3. Installation and site management........................................................................7
3.1 Types of sites............................................................................................7
3.2 Changes made during site creation ..................................................................7
3.2.1 What’s installed ...................................................................................7
3.2.2 What’s not installed...............................................................................8
3.2.3 Windows 2000 Domain Controllers not supported ............................................8
3.3 Web Interface 4.0 command-line installation and site management ..........................8
3.3.1 Web Interface 4.0 for Windows command-line installation.................................9
3.3.2 WebInterfaceSetup.exe command line options............................................. 10
3.3.3 Site Definition Strings........................................................................... 10
3.3.4 Web Interface for Windows Examples........................................................ 12
3.3.5 Web Interface for UNIX Site Creation ........................................................ 13
3.3.6 Web Interface for UNIX Example.............................................................. 14
3.4 Remote Configuration................................................................................ 14
3.4.1 Site registration.................................................................................. 16
3.4.2 Limitations and caveats ........................................................................ 17
3.4.3 Mistakes to avoid ................................................................................ 18
3.4.4 Remote Configuration of Web Interface for UNIX .......................................... 18
4. MetaFrame Presentation Server Site Changes........................................................ 22
4.1 URL Filtering........................................................................................... 22
4.2 Language Packs ....................................................................................... 22
4.3 Novell Authentication via LDAP .................................................................... 24
4.4 Support for Token-only Logins with RSA SecurID 6.0............................................ 25
5. Core Feature Specifications ............................................................................. 28
5.1 User Authentication .................................................................................. 28
5.1.1 Explicit Authentication ......................................................................... 28
5.1.2 Single sign on..................................................................................... 31
5.1.3 Smart Card Authentication..................................................................... 32
5.1.4 Change password ................................................................................ 35
5.2 Enumerating Applications ........................................................................... 36
5.3 Determining the target MetaFrame server address ............................................. 41
5.4 NFuse Ticketing ....................................................................................... 44
5.5 Address Translation .................................................................................. 47
5.5.1 Getting the Real Client IP from Secure Gateway 3.0 ...................................... 49
5.5.2 Address Translation Logic ...................................................................... 50
5.6 Workspace Control.................................................................................... 52
5.6.1 Unique Client Names............................................................................ 58
5.7 Using Secure Gateway with Web Interface ....................................................... 58
6. Troubleshooting techniques ............................................................................. 64
6.1 Event-based Logging ................................................................................. 64
6.2 Disable the default error message ................................................................. 64
6.3 Enable Tracing in ASP.NET .......................................................................... 66
2
6.4 Troubleshooting ASP.NET Errors.................................................................... 68
6.4.1 Try a Simple ASPX File .......................................................................... 68
6.4.2 IIS ASP.NET Registration ........................................................................ 69
7. Reference Materials ...................................................................................... 71
7.1 Features not available on Web Interface for UNIX .............................................. 71
7.2 XML Service Dependencies .......................................................................... 72
7.3 IMA Error Codes Relayed by the XML Service ..................................................... 73
7.3.1 Error Handling in Presentation Server 4.0 and beyond .................................... 73
7.4 HTTP Server Environment Variables ............................................................... 79
7.5 Debug.aspx............................................................................................. 82
About this document

This document is intended as a guide to understand and troubleshoot features in Citrix
Web Interface for Presentation Server 4.0. It is intended to supplement the Web
Interface Administrator’s Guide and Customizing the Web Interface.
3
1. What’s new in Web Interface 4.0

1.1 New features for the end user
Multilingual User Interface – A single Web Interface site supports users in five
languages simultaneously: English, German, French, Spanish, and Japanese. Web
Interface detects the user’s locale and displays the appropriate language
automatically.
Java Client Fallback – If a Win32 client logs into Web Interface without having a
Win32 ICA client installed, the ICA Client for Java can be automatically
delivered.
Bandwidth control – Users may indicate their current bandwidth during logon in
order to enable or disable features that affect ICA session bandwidth.
Increased UI control – Users may be allowed to control aspects of the Web
Interface display: which language to use, how many columns of application icons
to display, and whether to use full or compact UI layout.
Session Reliability through Secure Gateway – This is technically a feature of the
9.0 ICA Client and Secure Gateway 3.0, but session reliability through Secure
Gateway also requires Web Interface 4.0 and is enabled or disabled via an option
in the Web Interface Access Suite Console extension.
1.2 New features for the administrator

Access Suite Console management – An extension for the Access Suite Console
has been developed that allows GUI administration of both Windows and JSP site
variants. One instance of the Access Suite Console can be used to manage
multiple remote Web Interface servers. The new Access Suite Console plugin
replaces WIAdmin and PNAgentAdmin.
Remote Configuration – As an alternative to storing the configuration in a local
WebInterface.conf file, administrators may now choose to store the site
configuration in the Presentation Server 4.0 IMA database. When configured this
way, Web Interface downloads its configuration from the XML Service upon
startup and after any change is made in the Access Suite Console.
Site groups – Administrators can group multiple Web Interface sites into a single
logical unit and use the Access Suite Console to configure all sites as a group. All
sites in the group share a single central configuration. When a change is made in
the Access Suite Console, all sites in the load-balanced group are updated
immediately.
Multi-site support – Multiple Presentation Server, Program Neighborhood Agent,
or Conferencing Manager sites can co-exist on a single Web Interface server. The
Access Suite Console includes easy wizard-driven tasks for creating new sites, as
well as moving, repairing, or deleting sites.
Easy UI customization – Administrators can alter the appearance of Web
Interface without having to edit any scripts. The Access Suite Console offers
wizard-driven control over Web Interface’s overall layout, colors, logo, icon
columns, welcome message text, header, and footer.
Two-factor authentication on UNIX – The JSP variant of Web Interface now
supports RSA SecurID or Secure Computing SafeWord for Citrix. While the
Windows version of Web Interface continues to use the native third-party DLLs to
provide this feature, the JSP version uses the RADIUS authentication protocol to
communicate with the RSA or SafeWord server.
Novell NDS authentication via LDAP – Web Interface 4.0 for Windows is now
capable of performing Novell NDS integration without requiring the Novell client
4
on the Web server. NDS authentication is still unavailable on Web Interface for
UNIX.
1.3 Installer changes

The installer for the Windows version of Web Interface is now a self-extracting
executable instead of an MSI file. The installer is also multilingual; setup can be
performed in English, German, French, Spanish, or Japanese. The Access Suite
Console is a prerequisite for Web Interface on Windows; if the Access Suite
Console is not installed, the Web Interface installer aborts.
Sites must be created manually - After installation on a new server, no Web
Interface site is created by default. After installation, the administrator must
run the Access Suite Console and create a new site. A default static Web page is
created at /Citrix/MetaFrame/ with news to this effect: “Before you can use the
Web Interface, you must create one or more sites using the MetaFrame Access
Suite Console. In the console tree, right-click on Web Interface under the
Configuration Tools extension, then select Create site and follow the instructions
in the wizard.”
Some components of Web Interface 4.0 for Windows are placed in the Program
Files\Citrix\Web Interface\4.0 folder. This is a departure from Web Interface
3.0, but these central files in no way prevent a server from hosting multiple
independent Web Interface 4.0 sites.
1.4 XML Service changes

The XML Service in Presentation Server 4.0 includes the following enhancements:
Built-in Secure Ticket Authority – The STA is now bundled with the Citrix XML
Service. The standalone STA installer is no longer included.
Improved error handling - Where in prior versions the XML Service would always
return “Unspecified error” for any unrecognized IMA failure, the XML Service now
includes the IMA error code as part of its response to Web Interface. The
complete list of error codes is documented below.
1.5 Design Changes

New SDK - The underlying Java classes which drive Web Interface have been
completely rewritten. The new SDK is referred to as Web Interface Next
Generation or WING. The WING classes were designed from the ground up to be
more flexible and more powerful than previous versions of the NFuse SDK.
No more template.ica - Instead of using template.ica as the starting point for all
rendered ICA files, Web Interface 4.0 generates all ICA file parameters
programmatically. If a manual addition or correction needs to be made,
administrators may add entries to one or more ICA override files. Any parameter
defined in an ICA override file always takes precedence over its corresponding
computed value. Application-specific parameters may be inserted into the
override file, for example to allow just one application to run in a non-seamless
window.
5
2. Platform support
2.1 Supported Server Platforms
Tier 1 – Mainstream platforms, fully tested
O/S Hardware Web server CLR/JDK JSP
Windows Server 2003 with x86 IIS 6.0 .Net/J# 1.1 N/A
or without SP1
Windows 2000 SP4+ x86 IIS 5.0 .Net/J# 1.1 N/A
Red Hat Enterprise Edition x86 Apache 2.x Sun 1.4.x Tomcat 5.x
Tier 2 – Less commonly used, minimal testing only
O/S Hardware Web server JDK JSP
Solaris 9 Sparc SunOne 8 Sun 1.4.x SunOne
Red Hat Enterprise Edition x86 Apache 1.3 Sun 1.4.x Tomcat 5.x
Solaris 9 Sparc WebLogic WebLogic WebLogic
Server 8.x
Red Hat Enterprise Edition x86 WebSphere WebSphere WebSphere
Application
Server 5.x
2.2 Supported Web Browsers

Tier 1 O/S
Internet Explorer 6.0 Windows XP, Windows 2000 SP4+
Safari 1.x Mac OS X (JICA only)
Mozilla 1.x Red Hat Linux Enterprise
Tier 2 O/S
Internet Explorer 6.0 Windows 2003
Internet Explorer 5.5 Windows 2000, CE.NET 4.1 (WYSE 3125se)
Netscape 7.x Windows XP, Windows 2000
Pocket IE 2003 PocketPC 2003 (HP iPAQ H5550, Dell Axim 5)
Internet Explorer 6 CE.NET 4.2 (WYSE 3125se & HP t5510)
Tier 3 (Touch Test) O/S
Internet Explorer 5.21 MacOS X
Netscape 6.x MacOS 9
6
3. Installation and site management
This section provides details about what changes are made to a server during the
installation of Web Interface and how to create and manage Web Interface sites.
3.1 Types of sites

Web Interface 4.0 supports multiple independent sites on a single Web server, and each
site may be one of the following three types:
MetaFrame Presentation Server site – Provides access to a user’s application set
in an HTML format
Program Neighborhood Agent Services site – Provides XML Services to Program
Neighborhood Agent clients
MetaFrame Conferencing Manager site – Provides guest attendee access to a
conference hosted by MetaFrame Conferencing Manager
Throughout this guide, the term “Web Interface site” is meant to apply to all three types
of sites.
3.2 Changes made during site creation

Web Interface 4.0 for Windows includes a command-line tool called sitemgr.exe that is
responsible for adding and removing sites. When the “Create new site” task is performed
through the Access Suite Console, sitemgr.exe is ultimately called upon to execute the
action.
All new Windows-based sites consist of two basic elements: scripts and metabase
settings. Scripts for each type of Web Interface site (MetaFrame Presentation Server,
Program Neighborhood Agent and MetaFrame Conferencing Manager) are stored in zip
files under Program Files\Citrix\Web Interface\4.0. Sitemgr.exe unpacks the appropriate
zip file into the target Web directory (hereafter referred to as <site-root>) and then
makes changes to the IIS metabase in the appropriate location. For example, if the
default path of /Citrix/MetaFrame is retained for a new MetaFrame Presentation Server
site, then <site-root> refers to c:\inetpub\wwwroot\citrix\metaframe.
3.2.1 What’s installed

The following directories are created beneath each MetaFrame Presentation Server site’s
root:
• <site-root>/auth – Scripts and DLLs that deliver the Web Interface to end users
before they have authenticated
• <site-root>/site – Scripts and DLLs that deliver the Web Interface to end users
after they have authenticated
• <site-root>/conf – Configuration files, static string text files, and ICA override
files
• <site-root>/bin – DLLs that provide the Web Interface Java classes and other
native Windows code
• <site-root>/ICAWEB – ICA and RDP Client binaries, that override the common
clients stored in Program Files\Citrix\Web Interface\4.0\ICAWEB_common
Other metabase modifications made by the site manager tool include the following:
• IIS is configured to parse .ica files using aspnet_isapi.dll
7
• Custom error pages are defined that deliver a Web Interface-branded error
message instead of the default IIS error message when a problem occurs
• On Windows Server 2003, IIS is set to allow the ASP.NET Web service extension
• If “Set as the default page for the IIS site” was chosen during site creation,
WebInterface.htm is added to the top of the Web site’s default document list
3.2.2 What’s not installed

The following items were included in Web Interface 3.0 but are no longer present with
Web Interface 4.0 sites:
• WIAdmin has been replaced by the Access Suite Console. There is no HTML-based
administration tool for Web Interface 4.0.
• Default, certificate and integrated virtual directories are no longer created to
achieve single sign-on or smart card authentication through IIS. Instead, all users
access the login page at <site-root>/auth/login.aspx and individual file settings
in the metabase are used to trigger authentication for non-explicit methods.
• PNAgent is not included as part of a new Presentation Server site; it must be
created and managed separately.
• PNAgentAdmin has been replaced by the Access Suite Console.
3.2.3 Windows 2000 Domain Controllers not supported

If you install Web Interface 4.0 on a Windows 2000 domain controller, some problems
will arise because the ASPNET account does not exist.
After installation completes, an error appears saying “Error creating trustee object while
handling <Servername>\ASPNET.” The same error appears whenever you attempt to
create a new site.
On Windows 2000 servers that are not domain controllers, installing the .NET framework
creates a local ASPNET account to run the .NET framework worker process, and the Web
Interface installer expects this account to exist. On Windows 2000 Service Pack 4 domain
controllers, the ASPNET account is not created by the .NET framework installation; the
IWAM account is used instead. See Microsoft article 315158.
Also, attempting to access any ASP.NET site will initially fail with the error message “An
internal error occurred. Please contact your administrator.” As discussed in Microsoft
article 824308, the following steps need to be taken in order to use ASP.NET on a
Windows 2000 Service Pack 4 domain controller:
1. Edit the Domain Controller Security Policy.
2. Select Local Policies > User Rights Assignment and define a policy to allow the
“Impersonate a client after authentication” privilege to the domain IWAM
account.
3. Type SECEDIT /REFRESHPOLICY MACHINE_POLICY /ENFORCE.
4. Type IISRESET.
Web Interface 4.0 should not be installed on a Windows 2000 Domain Controller.
3.3 Web Interface 4.0 Command-line installation and site

management
Web Interface 4.0 supports installation, uninstallation, site creation, site modification,
and site removal via command-line utilities. These utilities can be used as an alternative
to the Access Suite Console for some tasks or as a means to perform an unattended
installation.
8
3.3.1 Web Interface 4.0 for Windows command-line installation
To get started, unzip the WebInterface.exe package to a directory. If WinZip is not
installed on a Windows 2003 server, you can simply rename the WebInterface.exe
program to WebInterface.zip and then expand it using Windows’ built-in zip handler. The
unzipped contents will include the file WebInterfaceSetup.exe:
The command-line options for WebInterfaceSetup.exe are detailed in the following

table. After Web Interface 4.0 for Windows is installed, the sitemgr.exe tool is added to
the Program Files\Citrix\Web Interface\4.0 directory. Use sitemgr.exe to add, remove, or
modify sites for the current installation. Sitemgr.exe supports all the same command-
line options detailed for WebInterfaceSetup.exe below EXCEPT -noasc, –q, -e, and -p.
If necessary, the zip file extraction step may be skipped and command-line options can
be passed to the self-extractor via an environment variable. The self-extractor cannot
accept command line arguments directly. Set the environment variable
WI_COMMAND_LINE equal to the command line you wish to use, and then invoke the
self-extractor with no arguments. When using this option, use the \ character to escape
spaces within arguments. If the \ character is needed to express a directory path, use \\
instead. For example:
C:\>set WI_COMMAND_LINE=-q -noasc -g c:\\wi\\logfile -c

“WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=mfpsrv01:80;mfpsrv02:8
0,WIDefaultSite=Yes”
C:\>WebInterface.exe
9
3.3.2 WebInterfaceSetup.exe command line options

Option Meaning Behavior if absent
-noasc Bypasses the check for the Access Suite Console Without this option, the
for MetaFrame Presentation Server. This allows installer will exit (with an error
you to install Web Interface without installing the message in an interactive
console. install) if the correct version of
the Access Suite Console is not
installed.
-p <path> Installs site management tool and language packs Site management tool and
to <path>. This option implies a silent language packs are installed to
installation of Web Interface. C:\Program Files\Citrix (or
equivalent).
-q Installs Web Interface silently. With none of these options, the
installer GUI is displayed.
-c <sitedef> Installs a new site defined by <sitedef>, which No site is created.
is a comma separated list of <arg>=<value>
pairs. See the next table for a specification.
-e <path> Installs the ICA clients from <path> which must ICA Client files are not
point to an ICAWEB folder. This option can only installed.
be specified to the first time setup wrapper or the
UNIX pre-install script. If absent, the ICA clients
are not installed.
This option can only be used if the –p option is

also specified.
-g <logpath> Log the operation(s) performed and save the log No log file is created.
files in <logpath>.
-h or -? Displays the program’s version and a summary of Help is not displayed.
the accepted command line options, then quits.
All other command line options are ignored.
-i Prints out a summary of all sites currently No summary is shown.
installed on the machine. This option can only be
specified by itself.
-l <language> Use language <language> for the GUI rather than If no other command line
the default language. If this option is used along options are supplied, the user
with any of the other options, it has no effect is prompted to select a
(since the GUI will not be displayed). Possible language for the installation
values for <language> are en, de, fr, es, and ja program.
(English, German, French, Spanish, and Japanese
respectively).
-m <sitedef> Modifies an existing site specified by <sitedef>. Existing sites are not modified.
-r <sitedef> Removes an existing site specified by <sitedef>. No site is removed.
-u Uninstalls the Web Interface. This option can only Web Interface is not
be specified by itself. uninstalled.
3.3.3 Site Definition Strings

Wherever <sitedef> appears in the previous table, this refers to a double quoted and
comma-separated list of name=value pairs which describe a Web Interface, Program
Neighborhood Agent, or MetaFrame Conferencing Manager site. For example, the
following <sitedef> string describes a Web Interface 4.0 site installed at the Default Web
10
Site beneath /Citrix/MetaFrame, using a local configuration file with the server MPS401
providing the Citrix XML Service:
"WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=MPS401:8080"
Options which may be included in a site definition string are defined in the following
table. All options and values are case-sensitive.
Option Meaning
WIDest=<IISSite>:<path> Web Interface site is to be installed at path <path> under
IIS site <IISSite> (the number of the IIS site).
Example: WIDest=1:/Citrix/MetaFrame
PNADest=<IISSite>:<path> Program Neighborhood Agent site is to be installed at path
<path> under IIS site <IISSite> (the number of the IIS site).
Example: PNADest=1:/Citrix/PNAgent
MCMDest=<IISSite>:<path> MetaFrame Conferencing Manager site is to be installed at
path <path> under IIS site <IISSite> (the number of the
IIS site).
Example: MCMDest=1:/Citrix/MCM
WICurrent=<IISSite>:<path> Modify/remove the Web Interface site at path <path>
under IIS site <IISSite> (the number of the IIS site).
PNACurrent=<IISSite>:<path> Modify/remove the Program Neighborhood Agent site at
path <path> under IIS site <IISSite> (the number of the
IIS site).
MCMCurrent=<IISSite>:<path> Modify/remove the MetaFrame Conferencing Manager site
at path <path> under IIS site <IISSite> (the number of
the IIS site).
Config=Local|<service_list> Specifies the configuration source to be either a local
Where <service_list> is one or more ; configuration file or the Configuration Service at the
separated <server>:<port> pairs. specified location(s). This option must be specified when
creating a site. When modifying a site, its absence
signifies no change.
Examples:
• Config=Local
• Config=MFSRV01:80;MFSRV02:80
WIDefaultSite=Yes|No Makes this Web Interface site the default site if Yes. Stops
the Web Interface site from being the default site if No. If
a new Web Interface site is being created and this option is
absent the default is No.
FarmName=<farm_name> Configures the initial farm to have name <farm_name>. If
configuration source is not local, an error occurs. If
absent, Farm1 is used.
XMLService=<server>:<port> Configures an initial XML Service at host <server> and
port <port>. If configuration source is not local, an error
occurs. If absent, the initial XML Service is set to
localhost:80.
XMLSProtocol=HTTP|HTTPS|SSL Sets the protocol used to communicate with the XML
Service (HTTP, HTTPS, or SSL). If configuration source is
not local, an error occurs. If absent, defaults to HTTP.
XMLSSSLPort=<port> Sets the SSL port used for communication with the XML
Service. If configuration source is not local, an error
occurs. Ignored if XMLSProtocol is not SSL. If absent,
defaults to 443.
11
Option Meaning
ECS=<server>:<port> Configures an initial ECS service at host <server> and
port <port>. If configuration source is not local, an error
occurs. Ignored if a MetaFrame Conferencing Manager site
is not being installed. If absent, defaults to
localhost:9000.
ECSSecure=Yes|No Sets whether communications with the initial ECS service
are secured using SSL. If configuration source is not local
or if no ECS option is specified, an error occurs. If absent,
defaults to No.
WIApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when
registering the Web Interface site with the Configuration
Service. Ignored if not using the Configuration Service. If
absent, a guessed URL is sent.
PNAApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when
registering the Program Neighborhood Agent site with the
Configuration Service. Ignored if not using the
Configuration Service. If absent, a guessed URL is sent.
MCMApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when
registering the MetaFrame Conferencing Manager site with
the Configuration Service. Ignored if not using the
Configuration Service. If absent, a guessed URL is sent.
3.3.4 Web Interface for Windows examples

The following examples illustrate how to perform command-line installation or site
management of Web Interface 4.0
Example 1 – Install Web Interface 4.0 for Windows and create a local site
To install Web Interface and create a Web Interface site on the Default Web Site
beneath /Citrix/MetaFrame, setting it to be the default destination for this Web server,
using a local WebInterface.conf file for configuration:
WebInterfaceSetup.exe –c
"WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=mps01:80,WIDefaultSite
=Yes"
Example 2 – Add a site that uses remote configuration
This command adds two new sites to an existing Web Interface 4.0 server. The new sites
will use the XML services MPS401:8080 and MPS402:8080 as configuration sources as well
as the sources for published application information. We have created a new site in IIS
that we wish to use to serve the Web Interface sites. The new IIS site has an identifier of
894881:
12
We wish to install the Web Interface and Program Neighborhood Agent Services sites on
this new IIS Web site.
cd "program files\citrix\web interface\4.0"

sitemgr.exe –c
"WIDest=894881:/Citrix/MetaFrame,PNADest=894881:/Citrix/PNAgent,XMLService
=MPS401:8080;MPS401:8080,Config=MPS401:8080;MPS402:8080"
Example 3 – Move Web Interface from the Default Web Site to a new site
The following command moves a Web Interface 4.0 site from the Default Web Site to the
site whose identifier is 894881:
cd "program files\citrix\web interface\4.0"

sitemgr.exe –m
"WICurrent=1:/Citrix/MetaFrame,WIDest=894881:/Citrix/MetaFrame"
3.3.5 Web Interface for UNIX site creation

The JSP variant of Web Interface includes the WebInterface.sh file for creating new
sites. The file WebInterface.sh can only be used to create a new site; it cannot be used
to move, modify, or delete an existing site. To delete an existing site, remove it from
the Web server in the standard way.
Option Meaning
WIWARFile=<path> Creates a Web Interface site WAR file at the
specified location.
PNAWARFile=<path> Creates a Program Neighborhood Agent site WAR
file at the specified location.
MCMWARFile=<path> Creates a MetaFrame Conferencing Manager site
WAR file at the specified location.
Config=Local|<service_list> Specifies the configuration source to be either a
Where <service_list> is one or more ; local configuration file or the Configuration
separated <server>:<port> pairs. Service at the specified location(s). If absent, the
default is to use a local configuration file.
FarmName=<farm_name> Configures the initial farm to have name

<farm_name>. If configuration source is not
local, an error occurs. If absent, Farm1 is used.
13
Option Meaning
XMLService=<server>:<port> Configures an initial XML Service at host
<server> and port <port>. If configuration
source is not local, an error occurs. If absent, the
initial XML Service is set to localhost:80.
XMLSProtocol=HTTP|HTTPS|SSL Sets the protocol used to communicate with the
XML Service (HTTP, HTTPS or SSL). If
configuration source is not local, an error occurs.
If absent, defaults to HTTP.
XMLSSSLPort=<port> Sets the SSL port used for communication with the
XML Service. If configuration source is not local,
an error occurs. Ignored if XMLSProtocol is not
SSL. If absent, defaults to 443.
ECS=<server>:<port> Configures an initial ECS service at host
<server> and port <port>. If configuration
source is not local, an error occurs. Ignored if
MetaFrame Conferencing Manager site is not being
installed. If absent, defaults to
localhost:9000.
ECSSecure=Yes|No Sets whether communications with the initial ECS
service are secured using SSL. If configuration
source is not local or if no ECS option is specified,
an error occurs. If absent, defaults to No.
3.3.6 Web Interface for UNIX example

To create a MetaFrame Presentation Server site using an XML Service at "mf1" or "mf2" on
port 80, and local configuration, putting the WAR file at
/opt/tomcat5/webapps/MetaFrame.war:
sh WebInterface.sh -c
"WIWARFile=/opt/tomcat5/webapps/MetaFrame.war,Config=Local,XMLService=mf1:
80;mf2:80"
3.4 Remote Configuration

Remote Configuration is a dramatic new change in Web Interface 4.0. This feature allows
the Web site configuration file (WebInterface.conf or config.xml) to be stored in the IMA
database instead of the Web server(s). Remote Configuration is a new option, not a
requirement; a Web Interface site can be configured to use a local WebInterface.conf as
before or use a configuration service. When set to use a configuration service, Web
Interface downloads its configuration file on startup from an XML configuration proxy.
The Remote Configuration feature is implemented by several inter-dependent

components:
14
Web Interface 4.0 Remote Configuration design
The Configuration Manager runs on Presentation Server 4.0 as a DCOM application. It is

always installed with Presentation Server 4.0 but only initiates when a request for its
services is received. By default, it runs in the process ConfigMgrSvr.exe under the
security context of a local account called Ctx_ConfigMgr. If necessary, this identity can
be edited using the Component Services snap-in (dcomcnfg.exe):
Web Interface site configurations are submitted to the configuration manager by the
Access Suite Console, which loads a .NET assembly called the Configuration Object
Library (COL) for these purposes. In order to use a Configuration Manager, the user
running the Access Suite Console must be authenticated as a Presentation Server
administrator who has been granted the delegated administration privilege called “Log
on to Web Interface Console” in the MetaFrame Presentation Server Console:
15
The Configuration Manager interacts with the IMA Service to store configuration files as
binary blobs in the IMA database.
On startup or after any change has been made to a central configuration file, Web
Interface downloads its configuration using the Configuration Proxy. The configuration
proxy is similar to the Secure Ticket Authority: it is an ISAPI plug-in that provides a read-
only XML interface to the Configuration Manager. It may be hosted by IIS or by the Citrix
XML Service; its default path in IIS is /Scripts/CtxConfProxy.dll. Web Interface may be
configured with several configuration proxy URLs for failover purposes.
Terminology Alert: A Web Interface Configuration Server is not necessarily a Web

Interface server, nor vice versa. Only servers running Citrix Presentation Server 4.0 for
Windows can act as a Web Interface Configuration Server.
3.4.1 Site registration

In order to support many different Web Interface servers, each of which might have
multiple Web Interface sites installed, the Configuration Manager uses a unique Site ID
for each MetaFrame Presentation Server, Program Neighborhood Agent, or MetaFrame
Conferencing Manager site configuration. The ID consists of the Web server name, the IIS
Web site identifier, its URL and then a random 32-character hexadecimal string. Here’s
an example:
FTLRGEMCO.gemini.ctx:1:/Citrix/PNAgent:262c804aeca62a84446aaec8e6ae0606
This site ID is stored on the web server within the site’s conf directory in a file called
bootstrap.conf. Whenever Web Interface needs to download its configuration, the site
ID is posted to the configuration proxy and a configuration file is returned:
<?xml version="1.0" encoding="UTF-16"?>

<!DOCTYPE ConfigProtocol SYSTEM "Config.dtd">
<ConfigProtocol version="1.0">
<RequestRegistration>
<ComponentInstanceId>wisrv:1:/MPS:0e8...325d7a032</ComponentInstanceId>
<ComponentVersion>4.0.4.3524</ComponentVersion>
<ComponentRegInfo key="LoginURL">http://wisrv/MPS</ComponentRegInfo>
<ComponentRegInfo key="Type">WI</ComponentRegInfo>
16
<ComponentRegInfo key="Technology">ASPX</ComponentRegInfo>
<ComponentRegInfo key="PlatformOS">Windows Server 2003</ComponentRegInfo>
<ComponentRegInfo
key="UpdateURL">http://wisrv/MPS/reloadConfiguration.aspx</ComponentRegInfo>
</RequestRegistration>
</ConfigProtocol>
If the configuration proxy responds with a message saying the site ID is not recognized,
then Web Interface posts an XML request that registers the site with the configuration
manager. The user will receive an error stating that no configuration is available:
Once the site is registered, a default configuration is created and the site can be edited
using the Access Suite Console.
For Windows Web servers, the Create site task in the Access Suite Console
simultaneously unpacks the site files into the appropriate location and registers the site
with the configuration manager if remote configuration is chosen. But for UNIX Web
servers, the registration process must take place after the site has been created.
Therefore the first request to a new JSP site using remote configuration will always fail.
After the first request, the site will have been registered with the configuration manager
and the administrator can use the Access Suite Console from any Windows machine to
edit the configuration of the JSP site.
3.4.2 Limitations and caveats

Communication between Web Interface and the Configration Proxy cannot be
encrypted with SSL. If this traffic must be secured, use IPSec.
When entering multiple configuration proxies for failover purposes, it is essential
that all configuration proxies belong to the same Presentation Server 4.0 farm.
When creating a new site with the Access Suite Console, the configuration
proxies are examined to ensure that they belong to the same farm and an error
is returned if not.
If a site is manually copied from one location to another (not recommended),
and both the original and the new site are intended to be used simultaneously,
you should change the site ID in bootstrap.conf for one of the sites so that they
remain unique. In the Access Suite Console, you may also need to edit the apply
changes URL to reflect the new site location.
17
3.4.3 Mistakes to avoid

When you configure and run discovery in the Access Suite Console, do not enter a
standalone Web Interface server as the name of a Web Interface Configuration
Server. If you do, you will receive the following error:
The RPC server cannot be contacted on server WIServerName.
Only Presentation Server 4.0 can act as a Web Interface Configuration Server.
When running the Access Suite Console from a workgroup server, do not attempt
to discover remote sites by contacting a Web Interface Configuration server. If
you do, you will receive the following error message:
This user account is not a Web Interface administrator for server

PSServerName.
Discovery of remote sites using a Configuration Server can only be completed

when running the Access Suite Console as a domain user who has been granted
the “Log onto Web Interface Console” privilege in the Citrix Management
Console.
3.4.4 Remote Configuration of Web Interface for UNIX

The following steps outline how to install Web Interface for UNIX and create a
Presentation Server site that can be configured remotely via the Access Suite Console
running on Windows.
First, copy WebInterface.sh.gz to your UNIX server (Red Hat Linux Enterprise or Fedora
will work). Unzip the archive using gunzip:
# gunzip WebInterface.sh.gz
Make the script file executable:
# chmod a+x WebInterface.sh
Run the installation shell script WebInterface.sh:
# ./WebInterface.sh
Note that if the sharutils package is not installed, the installation will fail with the
following error, citing the absence of uudecode:
./WebInterface.sh: line 175698: uudecode: command not found

tar: WebInterface.tar: Cannot open: No such file or directory
tar: Error is not recoverable: exiting now
./WebInterface.sh: line 175716: cd: /tmp/WebInterface/WebInterface: No
such file or directory
Exception in thread "main" java.lang.NoClassDefFoundError:
com/citrix/wi/install/UnixSiteTool
To install the sharutils package, type yum install sharutils or up2date sharutils.
If sharutils is present, setup begins.
Web Interface for MetaFrame Presentation Server Setup
18
Copyright (c) 2004-2005 Citrix Systems, Inc. All rights reserved.
This utility prepares the Web Interface for use. You may type Ctrl-C
at any time to quit.
<Press Enter to view the License Agreement>
The license agreement is shown. Type q to exit the scrolling agreement.
Do you agree to the terms of this License Agreement?: yes
The following site types are available:

[1] MetaFrame Presentation Server
[2] Program Neighborhood Agent Services
[3] Conferencing Manager Guest Attendee
Please specify the type of the site you wish to create [1]: 1
The following configuration sources are available:

[1] Local
[2] Configuration Service
Please enter the configuration source you wish to use [2]: 2
Please enter the next Configuration Service host to contact, or press

Enter if there are no more: 192.168.0.104
Please enter the port on which the previously specified Configuration

Service is listening. [80]: 8080
Please enter the next Configuration Service host to contact, or press

Enter if there are no more:[enter]
Please indicate if you want to install the Citrix ICA Clients. You
must install the clients for ICA Client download and embedded ICA
Client support to work. Install the Citrix ICA Clients? [YES]: no
Please enter the path of the WAR file to create [MetaFrame.war]:[enter]
SUMMARY
Site type: MetaFrame Presentation Server

Configured using Configuration Service at: 192.168.0.104:8080;
ICA Clients: No
Output WAR File: MetaFrame.war
The Web Interface will be configured using the information above. Is

this OK? [YES]:[enter]
Creating the WAR file...
All done.
Tomcat users: To deploy this web application, please create a

directory named Citrix under your Tomcat installation's webapps
directory and place the WAR file in it. Then place the context file
context-tomcat-metaframe.xml in your Tomcat installation's
conf/Catalina/localhost directory. You may edit the context file to
deploy this web application to a custom path.
BEA WebLogic users: To deploy this web application to a custom path,
19
edit the weblogic.xml within the WEB-INF directory of this WAR file.
At this point, a new MetaFrame.war file and corresponding tomcat XML file has been
created in the current directory:
# ls -l
total 12776
-rw-r--r-- 1 root root 665 Apr 8 12:01 context-tomcat-metaframe.xml
-rw-r--r-- 1 root root 2150903 Apr 8 12:01 MetaFrame.war
-rwxr-xr-x 1 root root 10887457 Apr 7 13:24 WebInterface.sh
To deploy this Web application under Tomcat, create the tomcat/webapps/Citrix

directory and move the MetaFrame.war file there. Then move the XML file to
tomcat/conf/Catalina/localhost/:
# mkdir /usr/local/tomcat/webapps/Citrix
# mv MetaFrame.war /usr/local/tomcat/webapps/Citrix/
# mv context-tomcat-metaframe.xml
/usr/local/tomcat/conf/Catalina/localhost/
Now stop and restart Tomcat to initialize the Web application.
# cd /usr/local/tomcat/bin
# ./shutdown.sh
Using CATALINA_BASE: /usr/local/tomcat
Using CATALINA_HOME: /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JAVA_HOME: /usr/java/j2sdk1.4.2_08
# ./startup.sh
Using CATALINA_BASE: /usr/local/tomcat
Using CATALINA_HOME: /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JAVA_HOME: /usr/java/j2sdk1.4.2_08
At this point the Web application should be loaded. Point a browser to http://tomcat-
server/Citrix/MetaFrame/. By default, Tomcat listens on port 8080, so the URL will be
similar to this:
http://192.168.0.117:8080/Citrix/MetaFrame/
On the first load, you will receive the following error message, stating that the system
configuration is invalid or unavailable:
20
After this error is shown, the site should be registered with your Presentation Server 4.0
Configuration Manager.
Move to a Windows workstation and launch the Access Suite Console. Configure and run
discovery, being sure to list the correct Presentation Server as a Web Interface
Configuration Server. Your Web Interface for UNIX site should now appear in the Access
Suite Console:
From this point on, you can use the Access Suite Console to manage all the settings for
the Web Interface for UNIX site.
21
4. MetaFrame Presentation Server Site Changes

This section describes a few new features and capabilities introduced in the MetaFrame
Presentation Server site for Web Interface 4.0.
URL Filtering
Language Packs
Novell authentication via LDAP
Support for Token-only Logins with RSA SecurID 6.0
Getting the Real Client IP from Secure Gateway 3.0
4.1 URL Filtering

Web Interface 4.0 includes a built-in URL filter that prevents access to the site’s main
scripts until after the user has authenticated. Prior to authentication, the user may not
access scripts in the <site-root>/site folder. Instead, the user is directed to the <site-
root>/auth folder where authentication is performed.
As such, there exists some apparent file duplication. For example, footer.txt exists in
both the auth and site folders. The copy in auth supplies the footer that will be shown
prior to user authentication, and the copy in site is the footer for authenticated users.
See the Web Interface 4.0 SDK documentation and tutorials in Customizing the Web
Interface for a more detailed overview of the Web Interface scripts.
4.2 Language Packs

All static strings displayed in Web Interface are drawn from resource files stored in
Program Files\Citrix\Web Interface\4.0\languages or <site-root>/languages. On Windows
Web servers, the resource files stored beneath Program Files are available to all sites on
the server. Storing static strings in resource files makes it easy to change the text on a
page without having to navigate the complexity of the scripts. It also makes it easier for
Web Interface to support users in multiple languages simultaneously.
In the languages folder, *.lang files exist to indicate which languages Web Interface
should make available to the user:
• de.lang – German
• en.lang – English
• es.lang – Spanish
• fr.lang – French
• ja.lang – Japanese
Each of these files contains a single line, indicating the friendly name of the language, to
be shown on the login page and application settings pages. For example, in de.lang:
FriendlyName=Deutsch (German)
22
To remove a language from the list, simply delete or rename its corresponding .lang file
and then restart the Web service.
The collection of static strings is defined in several resource files. For English, the files
are:
• common_strings.properties – Strings common to all site types
• metaframe_strings.properties – Strings used for MetaFrame Presentation Server
sites
• mcmguest_strings.properties – Strings used for MetaFrame Conferencing
Manager sites
• mpssourceimpl_strings.properties – Error messages related to MetaFrame
Presentation Server site functionality
• pnagent_strings.properties – Error messages related to Program Neighborhood
Agent site functionality
• pnagentimpl_strings.properties – More error messages related to Program
Neighborhood Agent site functionality
• SslErrorMessages.properties – Error messages for the SSL SDK
• webpnimpl_strings.properties – Error messages regarding the internal WebPN
object
• xmlclient_strings.properties – Error messages related to communications with
the Citrix XML Service and Secure Ticket Authority
This collection of properties files constitutes the English “language pack” for Web
Interface. Additional language packs contain the same set of files, but with the language
code appended to the file name. For example, the German language pack files are
common_strings_de.properties, metaframe_strings_de.properties, etc.
Each MetaFrame Presentation Server site includes its own languages folder, which is
initially empty. To add a language pack that should be used only for one site, add it to
the site’s languages folder instead of the languages folder beneath Program
Files\Citrix\Web Interface.
The resource files contain static strings, each with a key value assigned. Keys are
defined for all visible words (other than application names), including the welcome
message, tool tips, client installation captions, and error messages. Here are a few
examples:
LoginTitle=MetaFrame Presentation Server Login

PleaseLogin=Please log in
PINRejected=Your PIN could not be set.
SettingsError2=Please enter a valid window size.
In the scripts, strings are displayed by calling the getString() function with the current
locale. For example, the following ASP code would display the text “Your PIN could not
be set.”:
<%= getString("PINRejected", currentLocale) %>
New keys and strings can be added to the resource files if desired. However, simply
editing the files with Notepad is not sufficient. The properties files can only be modified
by an editor which recognizes the format of Java Properties Files. If you have an editor
available that can directly modify Java Properties files, you can use that tool to modify
the files. Otherwise, you'll need to follow the instructions below to modify the files in a
conventional text editor.
23
• The first step is to convert the Properties files into text files. To do this you
need to use the native2ascii tool available from java.sun.com as part of the J2SE
Software Development Kit, for example:
%JAVA_HOME%\bin\native2ascii -reverse -encoding UTF8

common_strings.properties common_strings.txt
• You can then edit the .txt in a UTF-8 aware text editor. Notepad is capable of
this task. When you have finished modifying a file, you must convert it back into
a properties file using the native2ascii tool, for example:
%JAVA_HOME%\bin\native2ascii -encoding UTF8

common_strings_it_IT.txt common_strings.properties
After making changes to the properties file, restart the Web server service in order to
make the changes effective.
4.3 Novell Authentication via LDAP

In previous versions of Web Interface, the NDS context lookup feature has relied on the
NDS client being installed on the Web Interface machine and that machine having access
to the NDS server. This feature changes the context lookup so that is it done over LDAP
which means that the NDS client is not required on the Web Interface machine.
Anonymous bind required by default

The supported method of connection to the directory will be anonymous binds. By
default, eDirectory does not give anonymous connection access to the cn attribute which
is required for contextless login. Administrators have to make changes to the
configuration of eDirectory as described in the following Novell article for this feature to
function:
http://developer.novell.com/research/appnotes/2003/septembe/01/a0309013.htm#1844676
It is also possible to configure Web Interface 4.0 with NDS credentials to make an
authenticated bind to the Novell server. To do this, locate the customization point
within the file loginNDS.cs:
// CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP
//
// CUSTOMIZATION POINT
//
// Set ndsAdminUsername and ndsAdminPassword to "" to use anonymous bind
// For non-anonymous binds SSL must be used so ensure the following:
// - the NDS ceritificate must be in the trusted part of the local
// machine's certificate store (use mmc)
// - the NDS server name must match the certificate ie. be fully qualified
//
// CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP
string ndsAdminUsername = ""; //"cn=Administrator,ou=company,o=com";
string ndsAdminPassword = ""; //"password";
Note that the connection is made over SSL if you supply a password as eDirectory
requires this by default.
There are three ways of logging in to Web Interface using NDS credentials:
1. Fully qualified user name – For example, “.user.company.com.” The selection
in the context drop down has no effect. The user will be authenticated in the
context given as part of the fully qualified user name.
24
2. Non qualified user name with context selected – For example, “user” and
“company.com” selected in drop down. The user will be authenticated in the
chosen context.
3. Non qualified user name with “Find context” selected – This is the only case
where the new context search functionality is used. The entire directory is
searched for a user with the given name. If no matching user is found, an error
message to that effect is displayed. If exactly one user is found, the
authentication is performed against that particular user in that context. If
multiple users are found in different contexts, the login page is shown again with
the contexts of the users discovered added to the contents of the context drop
down. In this case, the user must enter their user name and password again and
select one of the contexts to authenticate.
No matter which method is used to select a user name and context, if the configured
context list is not empty, the chosen context must be in the configured list otherwise the
login is not permitted.
4.4 Support for Token-only Logins with RSA SecurID 6.0

As in previous versions, Web Interface 4.0 supports native integration with the RSA
SecurID authentication product. When RSA authentication is enabled, users are prompted
for their domain password as well as their RSA passcode:
RSA integrated logon
The RSA passcode consists of a secret PIN code that the user knows, followed by the 6-
digit number that appears on the RSA token that has been issued to them:
RSA token
The number shown on the token changes every 60 seconds. The RSA ACE server
determines whether a user’s PIN and token code are correct for the given time of day.
25
RSA SecurID 6.0 introduces a new feature that allows users to log in using the RSA
passcode only. The domain password is managed and provided by the RSA server—users
are not required to know or enter their domain password.
Web Interface 4.0 supports RSA 6.0 password integration. To enable this feature, select
the “Use Windows password integration” checkbox on the Explicit authentication settings
dialog in the Access Suite Console:
Enabling RSA SecurID 6.0 password integration
With this feature enabled, users are prompted to enter only their user name and
passcode on the Web Interface login page:
26
How it works
The Web Interface server scripts responsible for user authentication include functions to
validate an RSA passcode. RSA 6.0 with Windows password integration follows this
process:
RSA SecurID 6.0 Integrated Password Authentication

1. Client accesses the Web Interface server and is prompted for their user name
and passcode.
2. Web Interface calls on code in <site-root>/auth/bin/Authenticators.dll to
instantiate an RSA client object and authenticate the user’s passcode. The
passcode is encrypted and sent to the RSA ACE server using UDP port 5500. If the
passcode is correct, the RSA Server sends the user’s domain password back to
Web Interface.
3. Web Interface receives the user’s domain password from the RSA 6.0 server and
sends it to the XML Broker. The explicit authentication process follows normally
from there.
27
5. Core Feature Specifications

This section explains how a few of the main Web Interface features are implemented.
5.1 User Authentication

Before displaying published applications for a user, Web Interface authenticates the
user. Web Interface can be configured to perform explicit authentication, single sign-on,
smart card, or anonymous authentication.
5.1.1 Explicit Authentication

Explicit Authentication refers to the mode of authentication where the user must type
their user name and password into a web form in order to gain access to published
applications.
Explicit authentication is performed against a Windows domain or a Novell eDirectory

tree, and may be augmented to require an RSA SecurID or Secure Computing SafeWord
passcode in addition to the user’s domain password.
How it works
Web Interface produces a login form asking for a user name and password. A domain
value is also required, but may be supplied by the administrator.
When users click the Log In button, their credentials are posted to the Web server using
standard HTTP or HTTPS. It is important to secure the Web Interface server with HTTPS--
otherwise a user’s password from the POST request will be visible on the network:
POST /Citrix/MetaFrame/default/login.aspx HTTP/1.1

Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; .NET CLR
1.1.4322)
state=LOGIN&LoginType=Explicit&user=jayt&password=secret&domain=TOMLIN&log
in=Log+In
Upon receiving the user’s credentials from the HTTP POST, Web Interface translates
them into an XML request and sends them to the XML Broker as part of the application
enumeration request:
28
<NFuseProtocol version="4.2">
<RequestAppData>
<Scope traverse="onelevel"></Scope>
<DesiredDetails>defaults</DesiredDetails>
<DesiredDetails>file-type</DesiredDetails>
<ServerType>all</ServerType>
<ClientType>ica30</ClientType>
<ClientType>content</ClientType>
<Credentials>
<UserName>jayt</UserName>
<Password encoding="ctx1">MPGKPGFDILDOPOFLIMCJLPBK</Password>
<Domain type="NT">TOMLIN</Domain>
</Credentials>
<ClientName>WI_1gykQ6/J7yKTj1ooSxKn</ClientName>
<ClientAddress addresstype="dot">192.168.0.152</ClientAddress>
</RequestAppData>
</NFuseProtocol>
This traffic may be secured using SSL Relay, but note that the password is no longer in
clear text here; it is scrambled, but this is not considered strong encryption.
Before the XML Broker returns applications for the user, the credentials must be
validated. This task is delegated to the IMA Service, which in turn calls LogonUser() and
LookupAccoutSid() from the local security account subsystem in Windows (LSASS.EXE).
Explicit user authentication

1. User sends credentials to Web Interface via HTTP POST command.
2. Web Interface includes credentials as part of the application enumeration
request.
3. The XML Service delegates user authentication and application enumeration to
the local IMA Service, which ultimately makes calls to the local security authority
(LSASS).
Novell integration
When integrating with Novell NDS, Web Interface attempts to perform contextless logins
by locating the user object within the NDS tree. For this action to succeed, the Web
Interface server must be able to contact a Novell NDS server on TCP port 389 (LDAP). By
29
default, Web Interface searches the entire tree until it finds a user object matching the
current user name. To restrict this search to a limited number of contexts, enter the
contexts into the Access Suite Console.
For more information about integrating with Novell NDS, see article CTX101898. The
article was written for MetaFrame XP Feature Release 2 and NFuse Classic 1.7, but the
Novell integration features in Web Interface have not changed since then.
How it breaks
Policy settings at the XML Broker prevent logon
Because the user authentication task is deferred to the local operating system at the
XML Broker, explicit logins should work as long as the user is able to log on locally at the
XML Broker server. To confirm this, make an ICA or RDP connection directly to the XML
Broker desktop and attempt to log on using the standard Windows GINA. Any problems
that occur using the standard GINA, such as issues with custom redirectors or the
inability to locate a domain controller, will similarly affect Web Interface
authentication.
However, keep the following in mind when testing logins at the XML Broker:
• Enumerating farm icons with the Program Neighborhood client from the Web
Interface server is not a valid test of the user’s ability to log on. Program
Neighborhood only uses the XML Service to locate the least-busy server in the
farm and then makes a headless ICA connection to the least-busy server where
user authentication takes place.
• If the XML Broker is a Windows 2003 server, it is possible that the user does not
have the “Allow log on through Terminal Services” right. In this case an RDP or
ICA session test would fail even if the user does have Log On Locally rights. Users
do not need the “Allow log on through Terminal Services” privilege on the XML
Broker in order to enumerate icons.
Server name contains the underscore character

If the Web server is accessed using a NetBIOS host name that contains the underscore
character such as WI_SERVER, user authentication will fail silently and return the user to
the login page with no error message. Underscore characters are permitted for Windows
server names but according to RFC 1738 they may not appear in Web server names.
When the server name contains an underscore character, a JavaScript bug prevents the
proper handling of cookies and Web Interface cannot function.
Known limitations and issues

• If the MetaFrame XML Broker is also a Windows 2000 or Windows 2003 domain
controller, only users who belong to the Domain Administrators group are able to
authenticate by default. To repair this problem, edit the policy for that MetaFrame
server and grant all users the Log On Locally privilege.
• Novell NDS authentication is available with Windows Web servers only.
Frequently Asked Questions

Does the XML Broker server have to be a domain controller?
No, the XML Broker will locate an appropriate domain controller for the supplied
credentials. For best results, place a domain controller on the same network segment as
the MetaFrame farm.
Does the XML Broker server have to be an IMA zone data collector (ZDC)?
No, but performance is improved if the XML Broker is a ZDC. User authentication does
not require the services of a ZDC but locating the least-busy server when the user clicks
30
an application does. If the XML Broker is not a ZDC, application address requests are
forwarded to the data collector of the zone in which the XML Broker resides.
Can an XML Broker that belongs to Domain A authenticate a user from Domain B?
Yes, as long as Domain A trusts Domain B. This is no different from logging in through the
standard Windows GINA as discussed above.
Users are being forced to reauthenticate every 20 minutes. How do I change this session
timeout?
Because the session is controlled by the .NET runtime instead of IIS, changing the session
timeout value in Internet Services Manager as discussed in CTX191516 does not affect
Web Interface 3.0. Instead, you should add a sessionState element to the <system.web>
section of web.config declaring a new timeout in minutes. For example, to change the
session timeout to one hour, add the following line to
/Citrix/MetaFrame/site/web.config:
<configuration>
<system.web>
<sessionState timeout="60" />
<compilation debug="false" defaultLanguage="C#">
<assemblies>
Note: Web.config entries are case sensitive and take effect immediately. Use
sessionState, not sessionstate.
5.1.2 Single sign on

This feature, formerly referred to as “Desktop Credentials Pass Through” allows users to
authenticate to the Web Interface using their Windows desktop login credentials.
Authentication to the Web server is similar to the authentication that occurs when a
domain user accesses a file share or domain print server to which they have been given
access: the user’s Windows credentials need not be reentered. Instead, the user simply
accesses the Web Interface site and their applications are displayed immediately.
How it works
1. The user begins by accessing the default URL for Web Interface.
2. Web Interface triggers an Integrated Windows Authentication challenge/response
handshake between the Web browser and IIS.
3. After a successful Integrated Windows authentication, IIS impersonates the
authenticated user to produce a list of domain groups to which the user belongs.
The AUTH_USER server variable will be populated with the authenticated
domain name and user name (for example, AUTH_USER=“TOMLIN\jayt”).
4. Web Interface uses this information to enumerate applications.
How it breaks
Restricted NTFS permissions
After successfully negotiating Integrated Windows Authentication, IIS impersonates the
current user account when accessing files on the Web server’s hard drive. Compare this
to anonymous authentication, where IIS impersonates the IUSR account in order to access
local resources. This design mandates that the user’s domain account have at least Read
permission on all scripts beneath the Web server’s document root directory.
Therefore, administrators who restrict NTFS permissions on the files beneath wwwroot to
allow access only by Administrators or the IUSR account will find that non-administrator
users are unable to view Web Interface pages.
31
To correct this problem, ensure that in addition to the IUSR account, all users who will
access the Web Interface have NTFS read permissions on all files beneath
wwwroot/Citrix on the Web server.
Proxy servers disrupt Integrated Windows authentication

If you attempt to access the Web Interface via an HTTP proxy server, the NTLM
challenge/response authentication required for single sign on will likely fail.
Integrated Windows authentication is generally not possible through proxy servers,

including the case where HTTPS traffic is proxied through Secure Gateway en route to
Web Interface. See the Microsoft TechNet Web site for details. To resolve this issue,
bypass the proxy server or use HTTPS to the IIS SSL port.

• Not available with Web Interface for UNIX.
• Web Interface IIS server must be a member of the client domain or a trusted
domain.
• Requires Internet Explorer for Windows on the client.
• If the Web server is not in the client’s Trusted Sites zone, Internet Explorer will not
complete the Integrated Windows Authentication handshake automatically. Instead,
the user receives a pop-up authentication window from IE requesting their user
name, password and domain. Web servers addressed as a NetBIOS host name are
trusted by default; those addressed as a fully-qualified domain name or IP address
are untrusted by default.
5.1.3 Smart Card Authentication

Smart card authentication is very similar to single sign-on authentication: IIS
authenticates the user and then enumerates applications using a list of group SIDs
instead of the user’s explicit user name and password. To authenticate the user, IIS
relies on client certificate mapping.
How it works
A user is provided with a smart card reader and is issued a smart card containing a user
certificate and private key. In order to access the private key stored on the smart card,
the user must provide their PIN code, usually a 4-digit number. Any Web site or virtual
directory served by IIS can be configured to accept or require client certificates:
32
Configuring IIS to require client certificates
The Web Interface installer applies these metabase settings when smart card
authentication is enabled.
Once the client certificate has been validated and sent to IIS, the Web server
communicates with an Active Directory domain controller to map the certificate to a
domain user account. As outlined in the Web Interface Administrator’s Guide, this step
requires that the Windows directory service mapper be enabled on the WWW Service
Master Properties dialog in Internet Services Manager:
33
Enable the Windows directory service mapper

By default, this feature is not enabled in IIS.
Once a successful account mapping has been made, the domain controller returns a
token for the identified user and IIS impersonates the user’s domain account for script
access. More information about client certificate mapping in IIS is available from the
Microsft TechNet Web site.
How it breaks
IIS is misconfigured
If the metabase settings on the certificate virtual directory are modified so that client
certificates are no longer required or client certificate mapping is not enabled, Web
Interface cannot authenticate the user. To correct this problem, use the Repair option
for the site in the Access Suite Console.

• Requires the server running Web Interface to be a member of an Active Directory
domain and have connectivity to a domain controller
• Smart card authentication is not possible when Secure Gateway (or anything else)
acts as an SSL-terminating reverse proxy for Web Interface. Users must make an
HTTPS connection directly to the IIS SSL listening port.
• Not available with Web Interface for UNIX
• Not available with NT4 domains
34
Can I use client certificates that are stored in the user’s profile instead of on a physical
smart card?
This can work for the Web Interface authentication and application enumeration, but not
for the final authentication to Presentation Server. Smart card authentication to
Presentation Server relies on an ICA virtual channel which relays commands to a PC/SC
compatible smart card reader, so a physical reader on the client is required for the
Presentation Server login. If a physical smart card is not present, the user is presented
with the standard “Press Ctrl-Alt-Delete to begin” graphic once the ICA session is
established. Because this logon dialog is presented within an ICA session, users would
have to press Ctrl-F1 to log in instead of Ctrl-Alt-Del.
5.1.4 Change password

This feature allows end users to change their Windows or NDS password (but not both
simultaneously) through a Web form provided by Web Interface when users click the key
icon:
Change password dialog
How it works
The task of changing a user’s password is deferred to the XML Service running on
Presentation Server. This relieves the Web server from needing any ties to the user’s
domain; the Web server can belong to a workgroup in the DMZ with no connectivity to a
domain controller or be running on the Linux or Solaris platform and still facilitate
Windows NT4, Active Directory, or Novell NDS password changes.
On the Presentation Server, code in CTXADMIN.DLL services the password change

request. The old and new passwords are sent from Web Interface to CTXADMIN.DLL via
the Citrix XML Service. For example:
POST /scripts/ctxadmin/ctxadmin.dll HTTP/1.1
<AdminProtocol version="4.2">
<RequestChangePassword>
<OldPassword>oldpass</OldPassword>
<NewPassword>newpass99</NewPassword>
</RequestChangePassword>
</AdminProtocol>
CtxAdmin.dll uses native Windows functions to attempt the password change: the
Windows API NetUserChangePassword() is used for NT4-style user names and ADSI
35
ChangePassword() method is used for UPN user names. Therefore the XML Broker must
have connectivity to a domain controller.
How it breaks
• If for any reason a user is not able to change their password from the Windows
GINA on the MetaFrame XML Broker, then Web Interface password changes will fail.
• If the XML Service is being hosted by IIS, then the file
Inetpub\Scripts\ctxadmin\ctxadmin.dll must be present and must be served
anonymously (same as wpnbr.dll).

• Not available with MetaFrame for UNIX, MetaFrame 1.8, or MetaFrame XP Service
Pack 1 and earlier
• Fails on MetaFrame XP Service Pack 2/Feature Release 1 for NT 4.0, Terminal Server
Edition with the error “405 Method not supported”

Is a license required for this feature?
No, the feature requires the ctxadmin.dll file from MetaFrame XP Service Pack 2 or
later, but the feature is not tied to a MetaFrame license. (CTX929560)
5.2 Enumerating applications

After a successful authentication, the XML Broker queries the IMA Service for the list of
published applications for the current user. Within IMA, published applications are
associated with domain user and group SIDs. After querying the domain controller to
identify the groups to which the user belongs, a list of published applications can be
produced.
How it works for explicit authentication
Explicit application enumeration

1. Web Interface sends a <RequestAppData> command to the XML Broker asking for
the list of applications for the current user and their default settings:
<RequestAppData>
<Credentials>
36
<Password encoding="ctx1">NFHALEBBMHGCMAJNOHLLKBP</Password>
<Domain type="NT">READINESS</Domain>
</Credentials>
<ClientName>WI_Ucs/237RBAKqj9tf</ClientName>
</RequestAppData>
</NFuseProtocol>
2. To determine the user’s application set, the XML Broker queries its local host
cache of the IMA database. (Application launch requests require communication
with a zone data collector; application enumeration requests do not.)
3. The XML Service responds with a <ResponseAppData> document detailing
information about each application to which the user has access:
<ResponseAppData>
<AppDataSet>
<Scope traverse="onelevel"/>
<AppData>
<InName>Access</InName>
<FName>Access</FName>
<Details>
<Settings appisdisabled="false" appisdesktop="false">
<Folder>Office XP</Folder>
<Description/>
<WinWidth>640</WinWidth>
<WinHeight>480</WinHeight>
<WinColor>2</WinColor>
<WinType>pixels</WinType>
<WinScale>75</WinScale>
<SoundType minimum="false">basic</SoundType>
<VideoType minimum="false">none</VideoType>
<Encryption minimum="false">basic</Encryption>
<AppOnDesktop value="false"/>
<AppInStartmenu value="false"/>
<PublisherName>readiness</PublisherName>
<SSLEnabled>false</SSLEnabled>
<RemoteAccessEnabled>true</RemoteAccessEnabled>
</Settings>
</Details>
<SeqNo>1070633217</SeqNo>
<ServerType>win32</ServerType>
</AppData>
<AppData>
… (AppData section repeated for each application)…
</AppData>
</AppDataSet>
</ResponseAppData>
</NFuseProtocol>
Notice the <SeqNo> element within the AppData response. This sequence number is
updated each time a change is made to the published application. If Web Interface has
not yet retrieved the icon graphic for a published application, it will request the icon
with another <RequestAppData> command:
<RequestAppData>
<DesiredDetails>icon</DesiredDetails>
<AppName>Access</AppName>
37
<AppName>Excel</AppName>
<AppName>Powerpoint</AppName>
<Credentials>
<Password encoding="ctx1">NFHALEBBMHGCMAJNOHLLKBP</Password>
<Domain type="NT">READINESS</Domain>
</Credentials>
</RequestAppData>
</NFuseProtocol>
Icon graphics are encoded into plain text and returned via another <ResponseAppData>
document:
<ResponseAppData>
<AppDataSet>
<Scope traverse="onelevel"/>
<AppData>
<InName>Access</InName>
<FName>Access</FName>
<Details>
<Icon>
PPPPMAMAAAAMAMPPPMAMAMAMAMAMAMAIPPPPAMAAAAAAMAP
PPAMAMAMAMAMAMAMPPPPPMAMAAAMAMPPPMAMAMAPAMAMAMI
PPPPPAMAAAAAAMAPPPAMAMHPMAMAMAPPPPPPMAMAAAAMAMP
PPMAMIPAMAMAIPPPPPPAMAAAAAAMAPPPAMAMAPPMAMAMPPP
MAMAAAAMAMPPPMAMAIPPAMAMIPPPPPPPAMAAAAAAMAPPPPP
PPPPPPPPPPPPPPPPPMAMAAAAMAMPPPPPPPPPPPPPPPPPPPP
PPAMAAAAAAMAPPPPPPPPPPPPPPPPPPPPPPMAMAAAAMAMAMA
...
</Icon>
</Details>
<SeqNo>1070633217</SeqNo>
</AppData>
<AppData>
... (AppData section repeats for each icon) ...
</AppData>
</AppDataSet>
</ResponseAppData>
</NFuseProtocol>
Multiple <RequestAppData> commands may need to be fulfilled in order to collect all

application icons (each request will ask for a maximum of five icons). Icon graphics are
retained in memory on the Web server and will not be requested again unless the
application sequence number changes. Application settings on the other hand are
requested every time a user logs on.
How it breaks
In most cases a failure to enumerate applications represents an authentication problem
at the XML Broker.
In rare cases though, the user may authenticate successfully but not receive the full list
of applications that they were expecting, or they may see (but not be able to launch)
applications to which they have not been given access. These issues are most likely
38
results from corruption of the IMA local host cache on the XML Broker server. See article
CTX759510 for instructions on how to refresh or recreate the local host cache.

• If the XML Service fails to respond, the Web server enumeration script times out
(CTX101691)

How many farms can be aggregated by Web Interface?
As many as 512 farms may be defined in the configuration file, but this does not imply
that Web Interface can aggregate applications from that many farms for each user. Citrix
has not tested aggregation of more than 17 farms and recommends that you do not
configure Web Interface to communicate with more than about 10 farms per user. (See
CTX103215 for an example of how to allow users to choose a subset of the available
farms.) Using more than 10 farms per user severely limits the scalability of Web
Interface.
How it works for Single Sign On or Smart Card Authentication

When configured for Single Sign On or Smart Card authentication, Web Interface detects
the user’s existing Windows domain authentication and enumerates applications for that
user automatically, without requiring the user to provide their user name and password.
1. IIS, having authenticated the user using Integrated Windows Authentication, is

able to identify the user’s domain and user name, but not their password.
Therefore a normal enumeration of application icons is not possible as it is with
explicit enumeration. Instead, the Web server determines the list of domain
groups to which the user belongs using functionality available in
SidEnumerator.dll. Web Interface constructs an XML request containing all of the
user’s individual and group SIDs and forwards this list of SIDs to the MetaFrame
XML Broker. For example:
<RequestAppData>
<Credentials>
<ID type="SAM">TOMLIN\jayt</ID>
<ID type="SID">S-1-5-21-1176179194-3682069127-2683672892-542</ID>
<ID type="SID">S-1-1-0</ID>
<ID type="SID">S-1-5-32-544</ID>
<ID type="SID">S-1-5-32-555</ID>
<ID type="SID">S-1-5-32-545</ID>
<ID type="SID">S-1-5-5-0-74059</ID>
<ID type="SID">S-1-5-64-10</ID>
</Credentials>
<ClientName>WI_FHCFlhTnv4dkBHPmcwrp</ClientName>
</RequestAppData>
</NFuseProtocol>
39
2. The XML Service queries IMA to obtain the list of applications that have been
published to the user or any of the groups in the list. Note that the XML Broker
does not perform user authentication at this point, as the user’s password is still
unknown.
3. The list of applications and their icons is returned via XML to Web Interface.
How it breaks
If a user does not have the Program Neighborhood client installed with the “Use local
credentials to log on” option selected, then they will be able to enumerate applications
at Web Interface but will be prompted for a password when they launch an application.
Single sign-on to MetaFrame Presentation Servers

Note that changing this setting requires the user to log out and log back in again in order
to become effective. After enabling this option, the user must also add the following line
to the [WFClient] section of their APPSRV.INI file in order to enable single sign on
through ICA files:
EnableSSOnThruICAFile=Yes

• Not available with MetaFrame for UNIX or Web Interface for UNIX.
• Requires all aggregated farms to be running MetaFrame XP Service Pack 2 or
later. A Feature Release 2 license is not required. (CTX811426)
• In an attempt to prevent overflow attacks, the XML Service limits the size of
requests that it will accept to 4096 bytes by default. If a user belongs to a large
number of groups, the size of their SID list may exceed the XML Service request
40
limit. See CTX943036 for information about hotfixes and a registry flag that can
be set to increase the maximum XML request size.

Can Single Sign-On be used with the ICA Web Client or Minimal Web client?
No, Single sign-on requires the full Program Neighborhood or Program Neighborhood
Agent client. This is documented in the Web Interface Administrator’s Guide and also
explained in this forum post.
5.3 Determining the target MetaFrame server address

Web Interface fosters connections to the most appropriate, least busy MetaFrame
Presentation server whenever a user clicks an application icon.
How it works
When a user clicks an application icon, Web Interface sends a request to the XML Broker
asking for the address of a target MetaFrame server to which the user should connect.
Web Interface will ask for the normal or the alternate server address depending on which
addressing method has been determined for the current client IP. For example:
<RequestAddress>
<Name>
<AppName>Microsoft Outlook</AppName>
</Name>
<ClientName>WI_Ucs/237RBAKqj9tf</ClientName>
<ServerAddress addresstype="dot-port"></ServerAddress>
<Credentials>
<Password encoding="ctx1">NFHALE...MAJNOHLLKBP</Password>
<Domain type="NT">readiness</Domain>
</Credentials>
<ClientCookie name="ServerPreferenceInfo">ABA...ACM</ClientCookie>
</RequestAddress>
The XML Broker queries the nearest zone data collector (ZDC) to retrieve a target server
address. The ZDC checks for several conditions:
1. If the user has a disconnected session running the current application, the ZDC will
ignore load levels and return the address of the server where the disconnected
session resides.
2. If any MetaFrame policies have been defined with zone preference information, the
zone preferences are taken into consideration. Zone preference is ignored when
reconnecting users to a disconnected session and zone preference can never prevent
a user from being connected. For example, if the user is affected by a MetaFrame
policy which sets a “Do not connect” preference for Zone 3 but the user has a
disconnected session on a server in zone 3, the user will still get reconnected to
their session in spite of the zone preference policy.
3. If any Load Evaluators are attached to the current application, they are used to
determine the least busy server within the farm or preferred zone.
4. Once an appropriate target server has been identified, the ZDC sends it an IMA ping
to ensure that it is alive before returning its address to the XML Broker.
5. If the target server has multiple IP addresses, the ZDC attempts to determine which
IP address would be appropriate for the current client IP.
41
Once the appropriate target server has been identified, the ZDC returns an address to
the XML Broker and the XML Broker relays the address to Web Interface in a
<ResponseAddress> message:
<ResponseAddress>
<ServerAddress addresstype="dot-port">10.3.9.31:1494</ServerAddress>
<ConnectionType>tcp</ConnectionType>
<TicketTag>IMAHostId:11376</TicketTag>
<FarmLoadHint>100</FarmLoadHint>
<DisconnectedSession/>
<SSLRelayAddress>jayt4.tomlin.ctx:443</SSLRelayAddress>
<CGPAddress addresstype="dns-port">*:2598</CGPAddress>
</ResponseAddress>
</NFuseProtocol>
How it breaks
Error unspecified
When the zone data collector cannot determine the IP address of the least busy server
for a published application, clicking the icon results in an error. This condition can occur
whenever logons are disabled on a target server, or if there are any problems with the
IMA Service or termsrv.exe on a target server. In large farms, determining which server is
causing the problem can be challenging. Network traces may reveal clues about which
server is failing, or type QFARM /APP <AppName> from a MetaFrame server command
prompt to see if any servers are missing from the list. To address this issue, enable
logons on the target server or temporarily remove the failing server from participating in
the published application. Section 3 of this document has more information on
troubleshooting the Error Unspecified message.
DNS address not returned or not the expected result

Web Interface can be configured to request fully-qualified domain names instead of IP
addresses for MetaFrame Presentation servers by setting AddressResolutionType=DNS or
DNS-port in WebInterface.conf. However, unless the MetaFrame farm is configured to
enable XML Service DNS name resolution, server addresses will continue to be reported
as IP addresses.
In other cases, only a server host name or a different domain name is returned instead of
the expected fully qualified domain name. This occurs when the target MetaFrame
server is configured with a static IP address and no default domain suffix is configured
for that server. This can cause SSL Relay connections to fail because the name of the
server sent to Web Interface does not match the subject of the certificate used by the
SSL Relay service. To resolve this issue, set the domain name in the Network
Identification tab in the System Properties for the target MetaFrame Presentation server.
(CTX101535)
No alternate address found

If Web Interface is configured to request the alternate address of MetaFrame
Presentation servers but an application is published on a server where the alternate
address has not been defined, Web Interface cannot produce an ICA file. To resolve this
issue, set an alternate address on the target server using ALTADDR.EXE, for example:
altaddr /set 206.81.35.76
42
Wrong address returned for servers with more than one network card
In each IMA zone, the zone data collector (ZDC) is responsible for resolving application
load balancing requests by returning the IP address of the least busy presentation server
for any given application name. When the least-busy server contains multiple network
interface cards (NICs) with IP addresses on different subnets, a determination must be
made about which address to return. To make this determination, the ZDC uses the
following process:
1. The ZDC obtains the client IP address from the incoming request. For Web
Interface users, this address will be the value of REMOTE_ADDR or the address of
the Web server if Secure Gateway and Web Interface are collocated.
2. If the ZDC has multiple network cards, it uses its own routing table to determine
which of its interfaces would be used to route traffic to the client IP address.
3. The address of the target server which most closely matches the result of the
previous step is chosen and returned to the client.
This process usually works fine when all servers in the farm have interfaces on the same
networks, but the wrong address could be chosen under the following circumstances:
• ZDC has only one interface - When the ZDC has only one NIC but member servers
have multiple NICs, then the result of step 2 above is always the same and
addresses from only one network are ever returned to clients. To address this issue,
make one of the multi-homed servers the ZDC.
• Secure Gateway address not considered – Web Interface sends the client IP
address (as Web Interface sees it) to the XML Broker during application address
requests, and the ZDC calculates the most appropriate server based on this
information. But when the user will connect through Secure Gateway, it is the
Secure Gateway server that ultimately connects to MetaFrame, not the client. The
ZDC may return a server address which makes sense for REMOTE_ADDR but to which
the gateway server has no route. This causes the client to receive SSL Error 37:
To resolve this issue, edit the getClientAddress() function in the Web server file
include.cs to return the gateway server’s internal IP address instead of
REMOTE_ADDR, for example:
/**
* Returns the IP address of the client.
*/
public string getClientAddress() {
// return Request.ServerVariables["REMOTE_ADDR"];
// Use gateway IP instead of REMOTE_ADDR:
return "10.12.3.45";
}

• MetaFrame 1.8 servers require a Feature Release 1 license or later in order to
use DNS address resolution
43
• If the target server is not MetaFrame XP Feature Release 1 or later, only the IPv4
address resolution type is supported

When should you enable DNS address resolution in WebInterface.conf?
There are two scenarios where DNS address resolution is needed:
1. SSL Relay - The SSL Relay service must be configured to use a certificate whose
subject matches the FQDN of the MetaFrame server, and clients must connect using
the FQDN. Attempting to connect by IP address will cause an SSL error.
2. Multiple NAT firewalls - In some networks, there might be multiple client networks
which have to traverse a NAT firewall in order to reach the MetaFrame
Presentation Server farm. If there were only one such client network then using
ALTADDR would suffice, but there can be only one alternate address per NIC on the
MetaFrame server so a different solution is needed when there is more than one
NAT firewall. For these cases, you can enable DNS name resolution and then each
client network can add a local DNS entry that resolves the MetaFrame server FQDN
to the appropriate NAT firewall address. This allows connectivity through an
arbitrary number of NAT firewalls, since each client network can resolve the FQDN
to a different IP address.
5.4 NFuse Ticketing

NFuse Ticketing refers to the generation of a single-use, time-sensitive ticket that
authenticates the user to a Presentation server instead of using their user name and
password.
History
NFuse version 1.0 did not include a ticketing feature, and rendered ICA files contained
the user’s scrambled password. Though the password was not readable, the ICA file
could be reused to gain access to the farm. Ticketing was introduced in NFuse 1.5 to
eliminate this security risk. It enables the production of ICA files that contain no
reusable authentication information. Once a ticket has been redeemed it can never be
used again. If the ticket is not used within a configurable timeout, it expires and cannot
be used.
NFuse Ticketing is similar to, but not the same as Secure Gateway Ticketing.
44
How it works
NFuse Ticketing
1. The user provides their user name, domain, and password to the server running Web
Interface and clicks an application icon. Web Interface sends a <RequestAddress>
command to the XML Broker to determine the address of the MetaFrame target
server. The target server will be the least busy server in the farm hosting the
selected application unless the user already has a disconnected session for that
application on some other server.
2. A ticket request is constructed by Web Interface that includes the user’s

credentials. The password is scrambled using simple XOR encoding. The desired
ticket timeout, defined by the TicketTimeout parameter in WebInterface.conf, as
part of the ticket request. Example:
<RequestTicket>
<Credentials>
<Password encoding="ctx1">MPGKPGFLIPGFLIPGFLIMCJLPBK</Password>
</Credentials>
<TicketType>CtxLogon</TicketType>
<TicketTag>192.168.0.107</TicketTag>
<TimetoLive>200</TimetoLive>
</RequestTicket>
</NFuseProtocol>
This request is sent to the MetaFrame XML Broker.
3. The XML Broker forwards the ticket request to the target server.
45
Note - In MetaFrame XP Feature Release 3 and earlier, this ticket request is sent to
the XML Service running on the target server, which created the requirement that
all servers in the farm must run the XML Service on the same port as the XML
Broker. Starting with MetaFrame Presentation Server 3.0, by default the ticket
request is sent via the IMA event bus using the MFServerSS IMA subsystem.
4. The target Presentation server receives the user’s credentials. Using code from
CCTICKET.DLL, the target server generates a random 30-byte ticket and returns the
ticket to the XML Broker. Example:
<ResponseTicket>
<Ticket>A4C8832C879768176A89579BC384D8</Ticket>
</ResponseTicket>
</NFuseProtocol>
The target server retains the generated ticket string and the user’s real credentials
in memory until it is redeemed or has expired.
5. The XML Broker returns the ticket to Web Interface.
6. The ticket is incorporated into the launch.ica file and delivered to the user’s Web
browser. The ticket is divided into two halves and placed into the Domain and
ClearTextPassword ICA file parameters:
Username=jayt
Domain=\176A89579BC384D8
ClearPassword=A4C8832C879768
The backslash character preceding the domain name is a signal to WinLogon that
the credentials being presented are to be interpreted as a ticket rather than an
actual domain name and password.
7. The ICA file is executed by the client, and the user initiates an ICA connection to
the target Presentation server. The ticket is presented to the logon GINA instead of
a domain and password. Winlogon.exe loads CCTICKET.DLL and is able to locate the
user’s real credentials which are still waiting in memory. The user’s real credentials
are retrieved from memory and submitted to the WinLogon process.
Note - If for any reason the credentials in the ticket request were invalid, failure
would not occur until after the WinLogon substitution. CCTICKET.DLL does not
validate credentials before producing a ticket.
How it breaks
Generally speaking, NFuse Ticketing fails whenever the XML Service on the target
MetaFrame server is unreachable or if the target server is not licensed for ticketing.

1. Requires a minimum of MetaFrame 1.8 with Service Pack 1 and a Feature Release 1
license on all servers in the farm.
2. See CTX101303 for a list of issues that affect ticketing.
3. If a MetaFrame farm contains a mix of servers running MetaFrame Presentation
Server 3.0 and MetaFrame XP Feature Release 3 or earlier (not recommended), then
the XML Broker must be configured to send ticket requests to the XML Service on the
target server instead of using the IMA Service.
46
How do I disable ticketing?
Edit the properties of a farm in the Access Suite Console and locate the check box to
disable ticketing. Ticketing can be enabled or disabled on a per-farm basis.
5.5 Address Translation

Users from various locations may access a single Web Interface server. Depending on
their location, the users may have different addressing needs for making the ICA
connection to a MetaFrame Presentation Server. For example, users on the corporate
network where the Presentation servers themselves reside are able to connect to the
Presentation server’s real IP address, while users from a satellite office or partner
network may have to connect through a Network Address Translation firewall:
Alternate addressing scenario
Or, Web Interface may be configured to use Secure Gateway to enable access from the
Internet, while internal users should still connect directly to MetaFrame without
traversing the gateway:
47
Secure Gateway addressing scenario
Because Web Interface is responsible for fostering ICA connections for all users, a
determination must be made to use an appropriate addressing method for any given user
based on their location.
The Web Interface administrator configures address translation preferences using the
Access Suite Console or by manually editing WebInterface.conf. There are a total of six
unique addressing methods:
1. Direct – Use the real address of the MetaFrame server, for example,
Address=192.168.0.98:1494.
2. Alternate – Use the alternate address of the MetaFrame server as configured by
running ALTADDR.EXE on each Presentation server, for example,
Address=206.31.24.99:1494.
3. Translated – Similar to Alternate, but the translated address and port for each
MetaFrame server are defined by Web Interface server in the Port Address
Translation table instead of by running ALTADDR.EXE on each Presentation
server, for example, Address=206.31.24.99:4000.
4. Secure Gateway Direct – The client connects to Secure Gateway, then Secure
Gateway forwards traffic to the MetaFrame Server’s normal address.
5. Secure Gateway Alternate – The client connects to Secure Gateway, then
Secure Gateway forwards traffic to the MetaFrame Server’s alternate address.
Use this method if a NAT firewall separates the gateway from the MetaFrame
Presentation servers.
6. Secure Gateway Translated – The client connects to Secure Gateway, then
Secure Gateway forwards traffic to the MetaFrame Server’s translated address.
Use this method if Port Address Translation is required between the gateway and
the MetaFrame Presentation servers.
See the sections on Secure Gateway Integration and Secure Gateway Ticketing for more
details about using Secure Gateway with Web Interface.
48
How it works
The location of the client is determined by an HTTP environment variable called
REMOTE_ADDR. All Web servers maintain a REMOTE_ADDR value for each HTTP session.
REMOTE_ADDR is determined by inspecting the TCP return address of the HTTP packet
that arrives at the Web server.
Important: REMOTE_ADDR may or may not be the end user’s IP address. When a client
access the Web server directly, REMOTE_ADDR will equal the client’s IP address; but if
the client’s traffic passes through any proxy servers, gateways (including Secure Gateway
for MetaFrame) or proxy-based firewalls, REMOTE_ADDR will be the firewall or proxy
address whose interface is nearest to the Web server. See CTX101993 for a discussion on
how Secure Gateway can affect REMOTE_ADDR.
5.5.1 Getting the Real Client IP from Secure Gateway 3.0

When Secure Gateway proxies HTTP traffic to Web Interface, all users appear to have
the same client address: the address of the Secure Gateway server. In order for Web
Interface to distinguish internal from external users, Web Interface needs to learn the
client’s real IP. This was not possible in Secure Gateway 2.0 (see this forum thread for
more details), but can be achieved with Secure Gateway 3.0.
Before proxying a Web request to Web Interface, Secure Gateway 3.0 adds an HTTP
header called X-Forwarded-For set equal to the value of the client address as the
gateway sees it. (This may still not be the real client address depending on proxy servers
and firewalls.) Within the user’s session on the Web Interface Web server, this value will
be available as the server variable HTTP_X_FORWARDED_FOR. Logic can therefore be
added to the Web Interface scripts to use HTTP_X_FORWARDED_FOR instead of
REMOTE_ADDR whenever HTTP_X_FORWARDED_FOR is present and REMOTE_ADDR equals
127.0.0.1 (or the IP address of the gateway when Web Interface and Secure Gateway are
on separate servers).
For example, if Web Interface 4.0 and Secure Gateway 3.0 are installed on the same
server, locate the following code in <site-root>/auth/serverscripts/include.cs and <site-
root>/site/serverscripts/include.cs:
/**
*/
return Request.ServerVariables["REMOTE_ADDR"];
}
Change both copies to:
/**
*/
if (Request.ServerVariables["HTTP_X_FORWARDED_FOR"] &&
(Request.ServerVariables["REMOTE_ADDR"] == "127.0.0.1")) {
return Request.ServerVariables["HTTP_X_FORWARDED_FOR"];
} else {
return Request.ServerVariables["REMOTE_ADDR"];
}
}
49
If Secure Gateway and Web Interface are on separate servers but Web Interface is
deployed behind Secure Gateway, change the address 127.0.0.1 in the above code to
match the IP address of the Secure Gateway server as Web Interface sees it.
Note that a similar change could be implanted on Web Interface 3.0 or earlier as long as
Secure Gateway 3.0 is used as the reverse proxy.
5.5.2 Address Translation Logic

The following flowchart illustrates the logic used by Web Interface to determine which
of the six addressing methods should be used for the current user:
50
Address Translation Logic in Web Interface
51
How it breaks
Most cases where address translation appears to be malfunctioning are caused by
confusion over the client address. For example, an administrator wishes to use Secure
Gateway for all external users coming from the Internet and normal addressing for all
internal users who reside on the 10.0.0.0 network. So the administrator makes what
seems to be the right configuration:
ClientAddressMap=10.0.0.0/255.0.0.0,Normal,*,SG
This setting tells Web Interface to use Normal addressing for anyone whose IP address
begins with 10 and Secure Gateway for anyone else. But the administrator reports that
users on the Internet are being directed to the MetaFrame server’s internal address
(which fails) instead of being sent through the gateway.
Upon inspecting the value of REMOTE_ADDR by loading the debug.aspx file, we find that
all Internet users are arriving at the Web server with the same address and it begins with
10! This occurs because their HTTP traffic is passing through secure gateway, a reverse
HTTP proxy or a proxy-based firewall. Therefore REMOTE_ADDR will be the firewall or
gateway address instead of the client’s true address.
Continuing the example above, suppose we find that external users always show
REMOTE_ADDR=10.9.41.62, the internal interface of the customer’s Microsoft ISA Server.
We would therefore reverse the address translation logic to establish Normal addressing
by default and use the firewall address to define an exception for external users:
ClientAddressMap=10.9.41.62/255.255.255.255,SG,*,Normal
See CTX101993 and the forum thread at

http://support.citrix.com/forums/thread.jspa?forumID=5&threadID=40069 for more
examples. For versions of Web Interface prior to 3.0, use the debug.asp page from
CTX052061 to expose the value of REMOTE_ADDR.
5.6 Workspace Control

Workspace Control allows the user to perform the following actions from Web Interface:
• Disconnect from all active Presentation Server sessions
• Log out of all active Presentation Server sessions
• Reconnect to all currently disconnected Presentation Server sessions
• Reconnect to any currently active Presentation Server sessions
How it works
Workspace control features are implemented in large part by the XML and IMA Services in
Presentation Server version 3.0 and later.
Disconnecting from all applications

When the user clicks the Disconnect button beneath their application set, an XML
request is sent to MetaFrame asking the XML Broker to disconnect all current sessions for
this user. Web Interface does not attempt to track which applications the user has
launched; instead it defers the enumeration and disconnection of current sessions to
IMA.
52
Steps to disconnect or logoff ICA sessions
1. User clicks Disconnect or Logoff.

2. Request is forwarded to XML Broker along with user’s credentials.
3. XML Broker uses IMA to locate all sessions belonging to that user and issue the
Disconnect or Logoff command.
4. Presentation servers respond with IMA success message.
5. Success message returned to Web Interface.
6. User is logged out and returned to the Web Interface Login page.
The disconnect.aspx script produces an XML request document containing a

<RequestDisconnectUserSessions> element such as the following:
<RequestDisconnectUserSessions>
<Credentials>
<Password encoding="ctx1">MPGKPGFDIGDOPOFLIMCJLPBK</Password>
</Credentials>
<ClientName>WI_5IfQI2ngLJfwxPHsiD1H</ClientName>
</RequestDisconnectUserSessions>
</NFuseProtocol>
Notice that the user’s credentials are included here. The success response from
MetaFrame is simple:
<ResponseDisconnectUserSessions>
</ResponseDisconnectUserSessions>
53
</NFuseProtocol>
The IMA Service on the XML Broker server initiates a DisconnectUserSessions() command,
which publishes the event to all servers in the farm and instructs them to disconnect the
user’s session.
Reconnecting to applications
When the user logs on to Web Interface with the Reconnect option enabled, or whenever
they click the Reconnect button beneath their application set, the script reconnect.aspx
is executed.
Steps to reconnect ICA sessions
1. User clicks Reconnect or logs on with Reconnect enabled.

2. Request forwarded to XML Broker along with user’s credentials.
3. XML Broker uses IMA to locate all disconnected sessions belonging to that user. If
the user wishes to be reconnected to active sessions as well, a disconnect
request is sent over IMA to any server where the user has an active session.
4. XML Broker returns a list of sessions to Web Interface.
5. Web Interface returns a hidden frameset containing links to each disconnected
application.
6. The client automatically requests each application. From this point a normal
reconnection process takes place.
7. Client’s credentials are forwarded to XML Broker.
8. XML Broker requests ticket from target MetaFrame server(s).
9. Address and ticket belonging to target server returned to Web Interface.
10. Web Interface delivers ICA file to client.
11. Client makes ICA connection to target server and resumes the disconnected ICA
session.
54
The reconnect.aspx script requests information about all the users disconnected and
(optionally) active sessions in the farm, then produces an HTML page that will produce
ICA files reconnecting the user to each of those applications. These two steps are shown
in detail below.
First, an XML request document is sent from Web Interface to MetaFrame Presentation
server asking for information about currently disconnected (and in this case active)
sessions for the currently logged on user:
<RequestReconnectSessionData>
<Credentials>
<Password encoding="ctx1">MPGKPGFDIGFLIMCJLPBK</Password>
</Credentials>
<ClientName>WI_5IfQI2ngLJfwxPHsiD1H</ClientName>
<SessionType>active</SessionType>
<SessionType>disconnected</SessionType>
</RequestReconnectSessionData>
</NFuseProtocol>
The XML response from the MetaFrame XML Broker indicates that the user has a session
in the farm running Notepad in Session ID #2 on the server with IMA Host ID 9914:
<ResponseReconnectSessionData>
<AppDataSet>
<AppData type="session">
<InName>Notepad</InName>
<DataType value="session"/>
<HostId type="ima-host-id">9914</HostId>
<SessionId>2</SessionId>
</AppData>
</AppDataSet>
</ResponseReconnectSessionData>
</NFuseProtocol>
Information about multiple disconnected sessions may be included in the response. If the
user wishes to be reconnected to any active sessions, IMA first disconnects the active
sessions and then includes those sessions in the response.
Given the list of disconnected sessions, reconnect.aspx produces an HTML frameset

which is loaded into the hidden frame called “hiddenwindow2”:
<frameset cols="100" border="5" framespacing="20" frameborder="yes">
<frame
src="launch.ica?NFuse_Application=Farm1x003aNotepad&NFuse_AppFriendlyNameU
RLEncoded=Notepad&NFuse_HostId=9914&NFuse_HostIdType=imax002dhostx002did&N
Fuse_SessionId=2"
name="Reconnect0"
title="Reconnect0"
scrolling="yes"
frameborder="yes"
border="1"
55
>
</frameset>
The effect of this hidden HTML frameset is the same as clicking an application icon: an
ICA file is requested from Web Interface and the normal reconnection process ensues. A
similar frame tag is generated for each session to which the user should reconnect.
Untrusted XML Service

Logoff, disconnect, and reconnect actions are security critical events that should be
password protected. When Web Interface or Program Neighborhood Agent calls these
commands they forward the user name and password provided by the end user for the
sessions they intend to disconnect or logoff. This causes problems for smart card and
single sign-on configurations because Web Interface does not have access to the user’s
password in these configurations. Allowing the commands to run without a password by
default opens a security vulnerability whereby an attacker who brings up their own Web
Interface server in a different domain could reconnect to your sessions. To prevent this
sort of attack, logoff, disconnect and reconnect requests sent to the XML Service are
untrusted (i.e. they require the user’s password) by default.
To enable trust, run the Citrix Management Console and edit the properties of the server
acting as XML Broker for Web Interface. Select Workspace Control property and enable
the checkbox for “Trust requests sent to the XML Service”:
Enable trust for workspace control
Administrators should restrict access to a trusted XML Service using firewalls, IPSec, port
filtering, or any other method they see fit. Only authorized Web Interface servers should
be allowed to connect to a trusted XML Service. Secure the network before enabling
trust.
Windows 2000 Domain Controller + IIS Port Sharing cannot be used as XML Broker
When the XML Broker providing data to Web Interface is a Windows 2000 Domain
Controller using IIS port sharing to deliver the XML Service, workspace control actions fail
with an unspecified error. To resolve this issue, do not use IIS port sharing. Register the
XML Service on a separate port by running the following commands:
ctxxmlss /r8080
56
net start CtxHttp
Then reconfigure Web Interface to use the new port for the XML Service communication.

• Workspace Control requires MetaFrame Presentation Server 3.0 for Windows
Advanced or Enterprise Edition and Web Interface 3.0 or later.
• On Win32 systems, if a native ICA client is present, workspace control features are
enabled only if the client version is 8.0 or later; if no native ICA client is present
then the workspace control features are enabled only when using the Client for
Java.
• Workspace control functions are disabled when running the ICA Client in pass-
through mode (for example, when you connect to a published instance of Internet
Explorer, then point to Web Interface).
• Some WinCE devices cannot support multiple instances of the ICA client, or if they
can, do not offer any way to switch between them. Session reconnect in situations
where there are multiple sessions involved will therefore be problematic.
• The process of reconnecting to an active session involves temporarily disconnecting
the session just before the user reconnects. If a MetaFrame server is configured to
reset disconnected sessions immediately, reconnecting to active sessions on that
server will fail.
• If a user has multiple non-seamless sessions running the same application on the
same server, they will be presented with a dialog upon reconnect asking which
session they would like to be reconnected to.
• Applications published for anonymous use are terminated when both anonymous and
authenticated users log off. Thus, users cannot reconnect to anonymous
applications after they log off.
• Workspace control features do not appear in Netscape if Netscape was installed
after the ICA client. You must install Netscape first, then install the ICA client.
• When using an embedded ICA client (Java or ActiveX), workspace control reconnects
may be suppressed by pop-up blocking software.

Does Workspace Control work when Secure Gateway is enabled?
Yes.
Which ICA clients support workspace control?

Workspace control is supported by the Win32, WinCE, Linux, and Java ICA clients. For
Windows clients, version 8.0 or later is required.
Why is the 8.0 Win32 ICA client required, even when Web Interface is configured to use
only the Java ICA client?
Because the user might be accessing Web Interface from within a Presentation Server
session, and the disconnect command would disconnect their pass-through session as
well as any other applications. The ICA Client Object (ICO) functionality in Win32 clients
earlier than 8.0 is not able to report whether the client is running on a Presentation
server (pass-through mode). After installing the 8.0 client, the Web browser can inform
Web Interface that the user is not accessing Web Interface from within a MetaFrame
session it is therefore safe to enable workspace control. This also explains why
workspace control is disabled for RDP client connections: the RDP client is not able to
report whether it is running within a session.
If no ICA client at all is present on a Win32 system, Web Interface assumes that the
client is not a Presentation server and enables workspace control for the Java ICA client.
57
What happens if I already have sessions running on multiple client devices?

The Disconnect and Logoff features will not affect other sessions that are already
running on other client devices, but the Reconnect feature will consolidate all your
sessions onto the current client device.
Does this feature work with the Program Neighborhood client?

Because the feature is implemented by Web Interface, it only works through a Web
browser or with the Program Neighborhood Agent client.
Do the workspace control buttons affect sessions that were initiated using Program
Neighborhood?
The Disconnect and Logoff buttons only affect applications that were launched using
Web Interface from the current workstation, but the Reconnect button can reconnect
you to published applications that were initiated in any way from any workstation.
Custom ICA connections to server desktops are not affected.
5.6.1 Unique client names

When Workspace Control is enabled, rather than a predictable Domain-Username format
for the client name parameter in ICA files, Web Interface produces a unique client name
for every client device. For example:
ClientName=WI_dAYSH5XuZ//+a3jGPEO0
Unique client names for each device are needed to facilitate the new Workspace Control
features. This may be an issue for customers who need the client name to match the
user’s workstation name or who rely on the ClientName field to extract meaningful
information within the Management Console for MetaFrame. Web Interface client names
are always prefixed with “WI_”, which makes it possible to create MetaFrame policies
that apply only to Web Interface users by defining a wildcard policy filter where the
client name is WI_*.
When Workspace Control is not enabled, Web Interface reverts to the legacy behavior of
using Domain-username for the client name. If the domain-username string exceeds 20
characters, it is truncated to 14 characters and followed by –hash, where hash is a 5-
character hash that will be unique for each user. For example, tomlin-
johannsebastianbach is converted to tomli-johannse-nnmnh. The shorter client name
allows for more readable client printer names.
5.7 Using Secure Gateway with Web Interface

Web Interface can render ICA files for users that direct them through a Secure Gateway
server en route to their applications.
After authenticating to the Web server and selecting a published application, users
connect to a gateway server instead of the target Presentation server. The gateway acts
as an ICA traffic relay between the client on an untrusted network and a MetaFrame
Presentation Server on the trusted network. ICA traffic between the client and the
gateway is encrypted using 128-bit SSL or TLS.
58
Secure Gateway solution architecture
The Secure Gateway Administrator’s Guide discusses the secure gateway solution in
detail. The purpose of this section is to examine how Web Interface enables secure
gateway connectivity.
Note that the Secure Ticket Authority is integrated into the Citrix XML Service with
Presentation Server 4.0, and may therefore be consolidated with the MetaFrame XML
Broker in the diagram above.
To define the Secure Gateway FQDN and STA location(s) in Web Interface, select Manage
Secure Client Access > Edit Secure Gateway Settings in the Access Suite Console:
Edit Secure Gateway Settings
59
In the dialog that appears, enter the fully qualified domain name of the gateway, which
should match the subject of the certificate installed on the gateway. Remote clients
must be able to resolve this FQDN to the external IP address of the Secure Gateway
server(s). Enter one or more Secure Ticket Authority URLs of the form http://sta-
server/Scripts/CtxSta.dll.
Secure Gateway Settings Defined in the Access Suite Console
Once the gateway FQDN and STA URLs are defined, enable Secure Gateway connectivity
by creating address translation rules in the DMZ settings to direct some or all of your
users through the gateway. To do so, select Manage Secure Client Access > Edit DMZ
Settings:
60
Edit DMZ settings
Change the default connection method to Secure Gateway Direct. You may also wish to
add an exception rule that allows users on the trusted network to bypass the gateway
and connect directly to Presentation Servers:
Address Translation Rules in Web Interface 4.0
How it works
The following diagram illustrates the process by which Web Interface produces an ICA
file intended for use with Secure Gateway:
61
Secure Gateway Connection Process
1. Having authenticated to Web Interface, the user clicks an application icon.

2. Web Interface contacts the XML Broker to determine the address of the target
MetaFrame server.
3. The XML Broker locates the least-busy server for the chosen application and
requests a MetaFrame Logon Ticket for that server.
4. The address of the target MetaFrame server and a corresponding MetaFrame
Logon Ticket are returned to Web Interface.
5. Web Interface sends the target server address, user name, domain name and
published application name (collectively referred to as “the data”) to the Secure
Ticket Authority (STA) and gets a gateway traversal ticket in return.
6. Web Interface renders an ICA file for the user containing the gateway traversal
ticket in the Address field. Also included in the ICA file are the following lines
that instruct the client to connect to a gateway:
SSLEnable=On
SSLProxyHost=csg.company.com:443
The fully-qualified domain name of the Secure Gateway server is drawn from the
CSG_Server value in WebInterface.conf.
7. The client makes an ICA-in-SSL connection (not HTTPS!) to the gateway server on
port 443 and performs an SSL handshake. The gateway server sends its server
certificate chain to the client; the client must have the appropriate CA root
certificate in order for the SSL handshake to succeed.
8. The gateway server extracts the gateway traversal ticket from the user’s ICA file
and sends it to the STA for redemption. The gateway receives the data from the
STA corresponding to the current ticket. The ticket is then purged from the
STA’s memory immediately.
9. Having validated the user’s ticket, the gateway opens a TCP connection to the
MetaFrame server’s ICA port and forwards decrypted ICA traffic to the server. A
relay is established with the gateway providing encryption/decryption service
between the client and the target MetaFrame server. The MetaFrame Logon
Ticket is supplied to initiate the ICA session without reauthentication.
62
As with non-gateway connections, the role of Web Interface is only to foster the ICA
connection. Once an ICA session is established, Web Interface is no longer plays an active
role in maintaining the user’s ICA session.
How it breaks
Web Interface configured with incorrect gateway FQDN
When configuring Web Interface to support Secure Gateway connections, the
administrator must enter the address of the Secure Gateway server. The address entered
must match the fully-qualified domain name which appears as the Subject of the
gateway server certificate. If the FQDN entered does not match the certificate on the
gateway, users will receive the following error from the ICA client when an application is
launched: "Security alert: The name on the security certificate does not match the name
of the server (SSL error 59)."

• Web Interface supports the definition of only a single secure gateway FQDN. The
ability to route users through different gateways based on farm, application name
or user location is possible only through custom script development.
63
6. Troubleshooting techniques
This section discusses various tips and techniques for troubleshooting Web Interface
problems.
6.1 Event-based logging

Web Interface 4.0 provides a logging facility to improve troubleshooting and fault
diagnostics and increase system security.
Instead of providing detailed system error messages to the user (which at best can
confuse them, and at worst could be used to gain knowledge of the system for malicious
purposes), users will only receive one of a few generic system error messages, which
describe the basic classification of the problem.
Detailed system error descriptions including errors reported by the underlying system
along with some form of identifiers (for example, a combination of user name,
timestamp, and event id) are logged into the Windows “Application” event log for IIS and
the Servlet engine log files for JSP. The log identifiers for system errors will be displayed
to the users along with the generic error messages so that the former can be passed to
administrators for easier identification in the log.
Web Interface monitors the log entries it writes out over time. This is so that it can
control the number of duplicate log entries that are written for a single event and not
fill up the server log in the event of large-scale failure. This is for both ASP.Net and JSP
deployments. The new configuration settings for this functionality are as follows:
• DuplicateLogInterval
• DuplicateLogLimit
The system behavior will be such that if DuplicateLogLimit duplicate log entries have
been written in a time period DuplicateLogInterval then further attempts to log the
same message will not be committed to the server log.
Errors resulting from incorrect user feedback (for example, supplying the wrong
credentials at login) will continue to be reported with the same level of detail as before.
These types of errors will not be logged. Additionally informational messages (as opposed
to errors) will not be logged.
As part of the system error logging feature, the Presentation Server 4.0 XML Service has
been updated to replace many of the “unspecified” errors that it reports with a new
“IMA error” which includes the hexadecimal error code reported by IMA. Web Interface
contains a list of IMA error code to error message mappings which allows it to log the
error description. The complete list of IMA Error codes is listed below.
6.2 Disable the default error message

By default, server-side errors are suppressed by the .NET framework in order to avoid
revealing any useful information to attackers. If any ASPX script contains an error, Web
Interface will return the following generic error message:
64
Default error message: “An internal error occurred"
To determine the exact script and line number causing the problem, disable custom
error reporting by disabling the customErrors element in <site-root>/web.config. Locate
the following line in web.config:
<customErrors mode="On" defaultRedirect="html/serverError.html" />
Change the mode to “Off”:
<customErrors mode="Off" defaultRedirect="html/serverError.html" />
Then, save the file and reproduce the problem that was causing an error. Changes to
web.config do not require a service restart. If the error was triggered by clicking an
application icon, you will have to right-click the icon and select “Open in new window”
in order to see the error report. The error report should now reveal much more detail,
including which line from which script is causing the error:
Sample ASP.NET compilation error
65
Additional compiler information can be obtained by enabling the debug option in the
web.config compilation tag:
<compilation debug="true" defaultLanguage="C#">
After resolving the issue, be sure to restore web.config to its original state so that end
users do not see detailed error messages.
6.3 Enable Tracing in ASP.NET

The .NET framework includes a built-in debugging feature called Tracing that allows you
to view details about each HTTP request issued within an ASP application. When tracing
is enabled, output resembling information from debug.asp (CTX052061) can be appended
to each page or accessed in a summary view. Tracing can be useful for debugging
difficult problems with the Windows version of Web Interface 3.0.
To enable Tracing, edit the web.config file in the /Citrix/MetaFrame/ or <site-root>

directory. Locate the following line:
<trace enabled="false" />
Change it to read as follows:
<trace enabled="true" pageOutput="true" localOnly="false"

requestLimit="100" />
After saving changes, (no restart necessary), extended information will be written to the
bottom of each page, including client cookies, session variables and HTTP Server
Variables. You can also point your browser to <site-root>/Trace.axd and view a history
of the last 100 requests. If you set pageoutput=“false” in web.config, trace information
will not be appended to each page and you must browse to the Trace.axd page in order
to view trace information. The trace.axd file does not actually exist, but the .NET
framework returns information as though it did. For example:
66
Sample Trace.axd output
When you click one of the View Details links, you can review all the information
associated with that request at the time and a summary of how quickly each step of the
process was completed. All server variables are included, which is handy when you need
to determine the working value of REMOTE_ADDR for address translation
troubleshooting. Here are some sample excerpts:
67
Trace detail excerpt
After obtaining the information you need from the trace, be sure to disable tracing again
in web.config since it may reveal sensitive information to attackers:
<trace enabled="false" />
See http://msdn.microsoft.com/library/default.asp?url=/library/en-
us/dnaspnet/html/asp01252001.asp for more information about tracing in ASP.NET.
6.4 Troubleshooting ASP.NET errors

Since Web Interface 4.0 is an ASP.NET application, it is critical that IIS and ASP.NET
function properly on a Web Interface server. If an ASP.NET problem exists, it is likely
that the Web Interface site will be the only application affected by the problem. Here
are some steps to help determine whether you have a Web Interface problem or an
ASP.NET problem.
6.4.1 Try a simple ASPX file

To confirm that ASP.NET core functionality is enabled, create a file called test.aspx with
the following content:
<%@ Page Language=C# %>

<html>
<body>
The current time and date is:
<% Response.Write(DateTime.Now.ToString()); %>
</body>
</html>
Save the test.aspx file in the wwwroot directory and then point a browser to
http://localhost/test.aspx. The output should reveal the current time. If you receive an
error, then ASP.NET is failing and you should use Microsoft resources to troubleshoot the
issue. Once you have the test.aspx script working, try the Web Interface URL again.
68
6.4.2 IIS ASP.NET Registration
Sometimes convenient and sometimes troublesome, multiple versions of the .NET
runtime may run side by side on the same machine. For example, if you have the .NET
runtime 1.0 installed and then you install version 1.1, you now have both versions 1.0
and 1.1 available at the same time. So which runtime will be used by IIS?
To answer this question Microsoft includes within the runtime a utility called
aspnet_regiis.exe. This utility can report or alter the version of ASP.NET being used by
IIS. The location of the .NET runtime is stored as a collection of metabase settings in IIS;
and like all metabase settings it is possible to have multiple configurations vary
according to virtual path. For example, you could have an ASP.NET application hosted at
/MyApp which uses a different version of ASP.NET than the application
/Citrix/MetaFrame.
Web Interface requires .NET runtime version 1.1 or later, and the 1.1 runtime installer is
included on the MetaFrame Presentation Server CD in the \Support folder (dotnetfx.exe).
If IIS was not present when the runtime was installed, there may be no ASP.NET
registration at all. This results in the default.aspx file being sent unparsed to the user
when accessing the Web Interface URL:
Or if IIS is configured to use the .NET runtime version 1.0 instead of 1.1, you may see
this:
Server Error in '/Citrix/MetaFrame' Application.

Configuration Error
Description: An error occurred during the processing of a configuration file required to service
this request. Please review the specific error details below and modify your configuration file
appropriately.
Parser Error Message: Unrecognized attribute 'validateRequest'.
Source Error:
Line 9: buffer="true"
Line 10: enableViewState="false"
Line 11: validateRequest="false"
Line 12: />
Line 13: <globalization
69
Source File: D:\Inetpub\wwwroot\Citrix\MetaFrame\site\web.config Line: 11

Version Information: Microsoft .NET Framework Version:1.0.3705.0; ASP.NET Version:1.0.3705.0
To register IIS with version 1.1 of the framework, type:
cd /d %systemroot%\Microsoft.net\Framework\v1.1.*
aspnet_regiis –i
Aspnet_regiis.exe is installed at %SystemRoot%\Microsoft.net\Framework\Version. Full

details on its usage are available in from the Microsoft TechNet Web site.
70
7. Reference Materials
7.1 Features not available on Web Interface for UNIX
Some features of Web Interface rely on core technologies provided by Microsoft Windows
or Internet Information Services. These features are not available when Web Interface is
running on UNIX Web servers or on Windows Web servers other than IIS.
Feature Available on UNIX

Automatic Win32 Web Client deployment D
Change password D
Client-Side Firewall Settings D
Explicit authentication D
ICA Java Client D
Network Address Translation D
Novell NDS integration
NFuse Ticketing D
Port Address Translation D
Program Neighborhood Agent Administration Tool (ASC) D New in 4.0
Program Neighborhood Agent support D
RDP Client D
RSA SecurID Authentication D New in 4.0
RSA SecurID 6.0 Password Integration
Secure Computing SafeWord Authentication D New in 4.0
Secure Gateway Integration D
Server-Side Firewall Settings D
Show client install caption D
Single Sign-On
Smart Card Authentication
Unicode ICA files D
Web Interface Administration Tool (ASC) D New in 4.0
Workspace Control D
71
7.2 XML Service dependencies

With each new version of MetaFrame Presentation Server, enhancements are made to
the Citrix NFuse XML Protocol enabling new functionality for Web Interface. This means
that some Web Interface features are unavailable when enumerating applications from
older MetaFrame farms. The following table identifies the XML Service version included
with older versions of MetaFrame and which Web Interface 4.0 features are unavailable
with those versions because of an XML Service dependency. Features that do not rely on
the NFuse XML protocol are not shown here.
Version Implementing Products Missing Web Interface 4.0 functionality

3.6.3 MetaFrame 1.8 Smart Card Authentication
NFuse 1.0 Desktop Credentials Pass Through
File type association
SSL ICA connections
NFuse Ticketing
Group and folder based application
acquisition
Change Password
Workspace Control
Zone Preference and Failover
Integrated STA
3.6.4 MetaFrame 1.8 FR1 Smart Card Authentication
MetaFrame XP 1.0 Desktop Credentials Pass Through
XML Service for Unix 1.0 File type association
NFuse 1.5 SSL ICA connections
NFuse 1.51 Change Password
Workspace Control
Integrated STA
4.1 MetaFrame XP FR1 Smart Card Authentication
MetaFrame for Unix 1.1 FR1 Desktop Credentials Pass Through
NFuse 1.6 File type association
NFuse 1.61 Change Password
Workspace Control
Integrated STA
4.2 MetaFrame XP FR2 Workspace Control
MetaFrame XP FR3 Zone Preference and Failover
NFuse Classic 1.7 Integrated STA
NFuse Classic 1.71
Web Interface 2.0
4.4 MetaFrame Presentation Server 3.0 Integrated STA
Web Interface 3.0 Enhanced IMA Error Reporting
4.5 Presentation Server 4.0 None
Web Interface 4.0
72
7.3 IMA error codes relayed by the XML Service
The XML Service is, for the most part, a Web service that wraps IMA operations for
application enumeration and server resolution (among others) and allows them to be
accessed over HTTP. When a client makes a request to the XML Service, the request is
parsed into a suitable format and then sent on to IMA, which returns a response. The IMA
response is then encoded into XML and sent back to the client.
Prior to Presentation Server 4.0, the error handling mechanism in this component is such
that when IMA returns an error, the XML responds to the caller like so:
If the IMA error is recognized by the XML Service, a <ResponseError> message is

returned, containing an <ErrorId> value that represents the well-known error.
Examples are: “failed-credentials” and “host-unreachable.”
<ResponseError>
<ErrorId>host-unreachable</ErrorId>
</ResponseError>
If the IMA error is not recognized by the XML Service, a <ResponseError> message
is returned, containing an <ErrorId> value of “unspecified.” In many
circumstances, and additional <BrowserError> value is returned. If the IMA error
is recognized as mapping to one of five browser error codes, then this value is
set to the hexadecimal value of that code, otherwise it is set to 0x00000024
(BR_ERROR_IMA_UNKNOWN_ERROR).
<ResponseError>
<ErrorId>unspecified</ErrorId>
<BrowserError>0x00000024</BrowserError>
</ResponseError>
The number of possible IMA error codes is of an order of magnitude higher than the
number of defined browser codes, resulting in an ‘unspecified’ <ErrorId> and a
<BrowserError> of 0x00000024 in the vast majority of failure modes, which is
unsatisfactory when attempting to ascertain what went wrong and why.
7.3.1 Error Handling in Presentation Server 4.0 and beyond

For Presentation Server 4.0, the XML Service protocol introduces a new element
<MPSError> that is used to relay IMA error codes direct to the XML Service client, in
cases where the error code is not already well-known (in which case it will be reported
as an <ErrorId> of something other than “unspecified”).
In particular, the Presentation Server 4.0 XML Service produces an <MPSError> when the
<ErrorId> is “unspecified” and the error originated from inside of IMA. In addition, for
backwards compatibility all IMA errors that currently cause a <BrowserError>, will still do
so. For example:
<ResponseError>
<ErrorId>unspecified</ErrorId>
<BrowserError>0x00000024</BrowserError>
<MPSError type = IMA>0x8013001A</MPSError>
</ResponseError>
The current IMA Error codes and their basic mnemonic descriptions are as follows:
73
IMA ID Source Facility ID Mnemonic

0x80000001 SYSTEM 0x0001 IMA_RESULT_UNKNOWN_FAILURE
0x80000002 SYSTEM 0x0002 IMA_RESULT_OUT_OF_MEMORY
0x80000003 SYSTEM 0x0003 IMA_RESULT_INVALID_ARG
0x80000004 SYSTEM 0x0004 IMA_RESULT_UNKNOWN_MESSAGE
0x80000005 SYSTEM 0x0005 IMA_RESULT_DESTINATION_UNREACHABLE
0x80000006 SYSTEM 0x0006 IMA_RESULT_REFERENCE_COUNT_NOT_ZERO
0x80000007 SYSTEM 0x0007 IMA_RESULT_ENTRY_NOT_FOUND
0x80000008 SYSTEM 0x0008 IMA_RESULT_NETWORK_FAILURE
0x80000009 SYSTEM 0x0009 IMA_RESULT_NOT_IMPLEMENTED
0x8000000A SYSTEM 0x000A IMA_RESULT_INVALID_MESSAGE
0x8000000B SYSTEM 0x000B IMA_RESULT_TIMEOUT
0x8000000C SYSTEM 0x000C IMA_RESULT_POINTER_IS_NULL
0x8000000D SYSTEM 0x000D IMA_RESULT_UNINITIALIZED
0x8000000E SYSTEM 0x000E IMA_RESULT_FINDITEM_FAILURE
0x8000000F SYSTEM 0x000F IMA_RESULT_CREATEPOOL_FAILURE
0x80000010 SYSTEM 0x0010 IMA_RESULT_SUBSYS_NOT_FOUND
0x80000014 SYSTEM 0x0014 IMA_RESULT_PS_UNINITIALIZED
0x80000015 SYSTEM 0x0015 IMA_RESULT_REGMAPFAIL
0x80000016 SYSTEM 0x0016 IMA_RESULT_DEST_TOO_SMALL
0x80000017 SYSTEM 0x0017 IMA_RESULT_ACCESS_DENIED
0x80000018 SYSTEM 0x0018 IMA_RESULT_NOT_SHUTTING_DOWN
0x80000019 SYSTEM 0x0019 IMA_RESULT_MUSTLOAD_FAILURE
0x8000001A SYSTEM 0x001A IMA_RESULT_CREATELOCK_FAILURE
0x8000001B SYSTEM 0x001B IMA_RESULT_SHUTDOWN_FAILURE
0x8000001C SYSTEM 0x001C IMA_RESULT_SENDWAIT_FAILURE
0x8000001D SYSTEM 0x001D IMA_RESULT_NO_COLLECTORS
0x8000001E SYSTEM 0x001E IMA_RESULT_UPDATED
0x8000001F SYSTEM 0x001F IMA_RESULT_NO_CHANGE
0x80000020 SYSTEM 0x0020 IMA_RESULT_LEGACY_NOT_ENABLED
0x80000021 SYSTEM 0x0021 IMA_RESULT_VALUE_ALREADY_CREATED
0x80000022 SYSTEM 0x0022 IMA_RESULT_UID_EXCEEDED_BOUNDS
0x80000023 SYSTEM 0x0023 IMA_RESULT_NO_EVENTS
0x80000024 SYSTEM 0x0024 IMA_RESULT_NOT_FOUND
0x80000025 SYSTEM 0x0025 IMA_RESULT_ALREADY_EXISTS
74
0x80000026 SYSTEM 0x0026 IMA_RESULT_GROUP_ALREADY_EXISTS
0x80000027 SYSTEM 0x0027 IMA_RESULT_NOT_A_GROUP
0x80000028 SYSTEM 0x0028 IMA_RESULT_GROUP_DIR_ACCESS_FAILURE
0x80000029 SYSTEM 0x0029 IMA_RESULT_EOF
0x8000002A SYSTEM 0x002A IMA_RESULT_REGISTRY_ERROR
0x8000002B SYSTEM 0x002B IMA_RESULT_DSN_OPEN_FAILURE
0x8000002C SYSTEM 0x002C IMA_RESULT_REMOVING_PSSERVER
0x8000002D SYSTEM 0x002D IMA_RESULT_NO_REPLY_SENT
0x8000002E SYSTEM 0x002E IMA_RESULT_PLUGIN_FAILED_VERIFY
0x8000002F SYSTEM 0x002F IMA_RESULT_FILE_NOT_FOUND
0x80000030 SYSTEM 0x0030 IMA_RESULT_PLUGIN_ENTRY_NOT_FOUND
0x80000031 SYSTEM 0x0031 IMA_RESULT_CLOSED
0x80000032 SYSTEM 0x0032 IMA_RESULT_PATH_NAME_TOO_LONG
0x80000033 SYSTEM 0x0033 IMA_RESULT_CREATEMESSAGEPORT_FAILED
0x80000034 SYSTEM 0x0034 IMA_RESULT_ALTADDRESS_NOT_DEFINED
0x80000035 SYSTEM 0x0035 IMA_RESULT_WOULD_BLOCK
0x80000036 SYSTEM 0x0036 IMA_RESULT_ALREADY_CLOSED
0x80000037 SYSTEM 0x0037 IMA_RESULT_TOO_BUSY
0x80000038 SYSTEM 0x0038 IMA_RESULT_HOST_SHUTTING_DOWN
0x80000039 SYSTEM 0x0039 IMA_RESULT_PORT_IN_USE
0x8000003A SYSTEM 0x003A IMA_RESULT_NOT_SUPPORTED
0x8000003B SYSTEM 0x003B IMA_RESULT_NOT_TRUSTED
0x80040001 DISTRIBUTION 0x0001 IMA_RESULT_MORE_ITEMS
0x80040002 DISTRIBUTION 0x0002 IMA_RESULT_SESSION_REQUEST_DENIED
0x80040003 DISTRIBUTION 0x0003 IMA_RESULT_JOB_NOT_FOUND
0x80040004 DISTRIBUTION 0x0004 IMA_RESULT_SESSION_NOT_FOUND
0x80040005 DISTRIBUTION 0x0005 IMA_RESULT_FILE_SEEK_FAILURE
0x80040006 DISTRIBUTION 0x0006 IMA_RESULT_FILE_READ_FAILURE
0x80040007 DISTRIBUTION 0x0007 IMA_RESULT_FILE_WRITE_FAILURE
0x80040008 DISTRIBUTION 0x0008 IMA_RESULT_JOB_CANNOT_BE_UPDATED
0x80040009 DISTRIBUTION 0x0009 IMA_RESULT_NO_TARGET_HOSTS
0x8004000A DISTRIBUTION 0x000A IMA_RESULT_NO_SOURCE_FILES
0x80130001 USER 0x0001 IMA_RESULT_MORE_ITEMS
0x80130002 USER 0x0002 IMA_RESULT_INVALID_ACCOUNT
0x80130003 USER 0x0003 IMA_RESULT_INVALID_PASSWORD
0x80130004 USER 0x0004 IMA_RESULT_EXPIRED_PASSWORD
75
0x80130005 USER 0x0005 IMA_RESULT_GROUP_IGNORED
0x80130006 USER 0x0006 IMA_RESULT_BUILTIN_GROUP
0x80130007 USER 0x0007 IMA_RESULT_DC_NOT_AVAILABLE
0x801300008 USER 0x0008 IMA_RESULT_NW_CLIENT_NOT_INSTALLED
0x80130009 USER 0x0009 IMA_RESULT_ACCOUNT_LOCKED_OUT
0x8013000A USER 0x000A IMA_RESULT_INVALID_LOGON_HOURS
0x8013000B USER 0x000B IMA_RESULT_ACCOUNT_DISABLED
0x8013000C USER 0x000C IMA_RESULT_PREFERRED_TREE_NOT_SET
0x8013000D USER 0x000D IMA_RESULT_EXPIRED_ACCOUNT
0x00130001 USER 0x0001 IMA_RESULT_ADSI_NOT_INSTALLED
0x00130002 USER 0x0002 IMA_RESULT_SECURITY_INFO_INCOMPLETE
0x80060001 DIRECTORY 0x0001 IMA_RESULT_ATTR_NOT_FOUND
0x80060002 DIRECTORY 0x0002 IMA_RESULT_CONTEXT_NOT_FOUND
0x80060003 DIRECTORY 0x0003 IMA_RESULT_VALUE_NOT_FOUND
0x80060004 DIRECTORY 0x0004 IMA_RESULT_DATA_NOT_FOUND
0x80060005 DIRECTORY 0x0005 IMA_RESULT_ENTRY_LOCKED
0x80060006 DIRECTORY 0x0006 IMA_RESULT_SEARCH_HASMORE
0x80060007 DIRECTORY 0x0007 IMA_RESULT_INCOMPLETE
0x80060008 DIRECTORY 0x0008 IMA_RESULT_READEXCEPTION
0x80060009 DIRECTORY 0x0009 IMA_RESULT_WRITEEXCEPTION
0x8006000A DIRECTORY 0x000A IMA_RESULT_LDAP_PARTIALINSTALL
0x8006000B DIRECTORY 0x000B IMA_RESULT_LDAP_NOTREADY
0x8006000C DIRECTORY 0x000C IMA_RESULT_BUFFER_TOO_SMALL
0x8006000D DIRECTORY 0x000D IMA_RESULT_CONTAINER_NOT_EMPTY
0x8006000E DIRECTORY 0x000E IMA_RESULT_CONFIGURATION_ERROR
0x8006000F DIRECTORY 0x000F IMA_RESULT_GET_BASEOBJECT
0x80060010 DIRECTORY 0x0010 IMA_RESULT_GET_DERIVEDOBJECT
0x80060011 DIRECTORY 0x0011 IMA_RESULT_OBJECTCLASS_NOTMATCH
0x80060012 DIRECTORY 0x0012 IMA_RESULT_ATTRIBUTE_NOTINDEXED
0x80060013 DIRECTORY 0x0013 IMA_RESULT_OBJECTCLASS_VIOLATION
0x8006014 DIRECTORY 0x0014 IMA_RESULT_ENUMFAIL
0x80060015 DIRECTORY 0x0015 IMA_RESULT_ENUMNODATA
0x80060016 DIRECTORY 0x0016 IMA_RESULT_DBCONNECT_FAILURE
0x80060017 DIRECTORY 0x0017 IMA_RESULT_TRUNCATE
0x80060018 DIRECTORY 0x0018 IMA_RESULT_DUPLICATE
0x80060019 DIRECTORY 0x0019 IMA_RESULT_PS_NOTINITIALIZED
76
0x8006001A DIRECTORY 0x001A IMA_RESULT_USING_ORACLE_7
0x8006001B DIRECTORY 0x001B IMA_RESULT_USING_ORACLE_8
0x8006001C DIRECTORY 0x001C IMA_RESULT_USING_ORACLE_UNKNOWN
0x8006001D DIRECTORY 0x001D IMA_RESULT_LOAD_DAO_ENGINE_FAILED
0x8006001E DIRECTORY 0x001E IMA_RESULT_COMPACT_DB_FAILED
0x80060033 DIRECTORY 0x0033 IMA_RESULT_ODBC_NO_CONNECTIONS_AVAILABLE
0x80060034 DIRECTORY 0x0034 IMA_RESULT_CREATE_SQL_ENVIRONMENT_FAILED
0x80060035 DIRECTORY 0x0035 IMA_RESULT_SQL_EXECUTE_FAILED
0x80060036 DIRECTORY 0x0036 IMA_RESULT_SQL_FETCH_FAILED
0x80060037 DIRECTORY 0x0037 IMA_RESULT_SQL_BIND_PARAM_FAILED
0x80060038 DIRECTORY 0x0038 IMA_RESULT_SQL_GET_COLUMN_DATA_FAILED
0x80060039 DIRECTORY 0x0039 IMA_RESULT_REPLICATED_DATA_CONTENTION
0x8006003A DIRECTORY 0x003A IMA_RESULT_DB_TABLE_NOT_FOUND
0x8006003B DIRECTORY 0x003B IMA_RESULT_CONNECTION_EXIST
0x8006003C DIRECTORY 0x003C IMA_RESULT_QUERY_MAX_NODEID_FAILED
0x8006003D DIRECTORY 0x003D IMA_RESULT_SQL_FUNCTION_SEQUENCE_ERROR
0x8006003E DIRECTORY 0x003E IMA_RESULT_DB_CONNECTION_TIMEOUT
0x8006003F DIRECTORY 0x003F IMA_RESULT_SQL_INVALID_TRANSACTION_STATE
0x80060040 DIRECTORY 0x0040 IMA_RESULT_DB_NO_DISK_SPACE
0x80060041 DIRECTORY 0x0041 IMA_RESULT_USING_ORACLE_9
0x80060042 DIRECTORY 0x0042 IMA_RESULT_TRANSACTION_ROLLEDBACK
0x002D 0000 RUNTIME 0x0001 IMA_RESULT_ALREADY_MASTER
0x802D0001 RUNTIME 0x0001 IMA_RESULT_TABLE_NOT_FOUND
0x802D0002 RUNTIME 0x0002 IMA_RESULT_NOT_TABLE_OWNER
0x802D0003 RUNTIME 0x0003 IMA_RESULT_INVALID_QUERY
0x802D0004 RUNTIME 0x0004 IMA_RESULT_TABLE_OWNER_HAS_CHANGED
0x802D0005 RUNTIME 0x0005 IMA_RESULT_SERVICE_NOT_AVAILABLE
0x802D0006 RUNTIME 0x0006 IMA_RESULT_ZONE_MASTER_UNKNOWN
0x802D0007 RUNTIME 0x0007 IMA_RESULT_NON_UNIQUE_HOSTID
0x802D0008 RUNTIME 0x0008 IMA_RESULT_REG_VALUE_NOT_FOUND
0x802D0009 RUNTIME 0x0009 IMA_RESULT_PARTIAL_LOAD
0x802D000A RUNTIME 0x000A IMA_RESULT_GATEWAY_NOT_ESTABLISHED
0x802D000B RUNTIME 0x000B IMA_RESULT_INVALID_GATEWAY
0x802D000C RUNTIME 0x000C IMA_RESULT_SERVER_NOT_AVAILABLE
0x80110104 LMS 0x0104 LMS_RESULT_NO_SERVER_AVAILABLE
0x80110200 LMS 0x0200 IMA_RESULT_FULL_SERVER_OR_APP_LOAD_REACHED
77
0x80260001 PRINTER 0x0001 IMA_RESULT_NW_PRINT_SERVER_ALREADY_PRESENT
0x80260002 PRINTER 0x0002 IMA_RESULT_SERVER_ALREADY_PRESENT
0x80300001 REMOTE_ACCESS 0x0001 IMA_RESULT_SERVICE_NOT_SUPPORTED
0x80300002 REMOTE_ACCESS 0x0002 IMA_RESULT_BUILD_SD_FAILED
0x80300003 REMOTE_ACCESS 0x0003 IMA_RESULT_RPC_USE_ENDPOINT_FAILED
0x80300004 REMOTE_ACCESS 0x0004 IMA_RESULT_RPC_REG_INTERFACE_FAILED
0x80300005 REMOTE_ACCESS 0x0005 IMA_RESULT_RPC_LISTEN_FAILED
0x80300006 REMOTE_ACCESS 0x0006 IMA_RESULT_BUILD_FILTER_FAILED
0x80300007 REMOTE_ACCESS 0x0007 IMA_RESULT_RPC_BUFFER_TOO_SMALL
0x80300008 REMOTE_ACCESS 0x0008 IMA_RESULT_REQUEST_TICKET_FAILED
0x80300009 REMOTE_ACCESS 0x0009 IMA_RESULT_INVALID_TICKET
0x8030000A REMOTE_ACCESS 0x000A IMA_RESULT_LOAD_TICKETDLL_FAILED
78
7.4 HTTP Server Environment Variables
This table, taken from MSDN, lists the HTTP Server environment variables available in IIS.
These variables are accessible through the Request.ServerVariables collection, e.g.:
Your client IP is <%=Request.ServerVariables["REMOTE_ADDR"] %>
Variable Description
ALL_HTTP All HTTP headers sent by the client.
ALL_RAW Retrieves all headers in raw form. The difference between ALL_RAW
and ALL_HTTP is that ALL_HTTP places an HTTP_ prefix before the
header name and the header name is always capitalized. In ALL_RAW
the header name and values appear as they are sent by the client.
APPL_MD_PATH Retrieves the metabase path for the Application for the ISAPI DLL.
APPL_PHYSICAL_PATH Retrieves the physical path corresponding to the metabase path. IIS
converts the APPL_MD_PATH to the physical (directory) path to
return this value.
AUTH_PASSWORD The value entered in the client's authentication dialog. This variable
is available only if Basic authentication is used.
AUTH_TYPE The authentication method that the server uses to validate users
when they attempt to access a protected script.
AUTH_USER The name of the user as it is derived from the authorization header
sent by the client, before the user name is mapped to a Windows
account. This variable is no different from REMOTE_USER. If you
have an authentication filter installed on your Web server that maps
incoming users to accounts, use LOGON_USER to view the mapped
user name.
CERT_COOKIE Unique ID for client certificate, returned as a string. Can be used as

a signature for the whole client certificate.
CERT_FLAGS bit0 is set to 1 if the client certificate is present.

bit1 is set to 1 if the Certification authority of the client certificate
is invalid (it is not in the list of recognized CAs on the server).
CERT_ISSUER Issuer field of the client certificate (O=MS, OU=IAS, CN=user name,
C=USA).
CERT_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For
example, 128.
CERT_SECRETKEYSIZE Number of bits in server certificate private key. For example, 1024.
CERT_SERIALNUMBER Serial number field of the client certificate.
CERT_SERVER_ISSUER Issuer field of the server certificate.
CERT_SERVER_SUBJECT Subject field of the server certificate.
CERT_SUBJECT Subject field of the client certificate.
CONTENT_LENGTH The length of the content as given by the client.
CONTENT_TYPE The data type of the content. Used with queries that have attached
information, such as the HTTP queries GET, POST, and PUT.
79
GATEWAY_INTERFACE The revision of the CGI specification used by the server. The
format is CGI/revision.
HTTP_<HeaderName> The value stored in the header HeaderName. Any header other
than those listed in this table must be prefixed by HTTP_ in order
for the ServerVariables collection to retrieve its value.
Note The server interprets any underscore (_) characters in
HeaderName as dashes in the actual header. For example if you
specify HTTP_MY_HEADER, the server searches for a header sent as
MY-HEADER.
HTTP_ACCEPT Returns the value of the Accept header.
HTTP_ACCEPT_LANGUAGE Returns a string describing the language to use for displaying

content.
HTTP_COOKIE Returns the cookie string that was included with the request.
HTTP_HOST Returns the name of the Web server. This may or may not be the
same as SERVER_NAME depending on type of name resolution you
are using on your Web server (IP address, host header).
HTTP_REFERER Returns a string that contains the URL of the page that referred
the request to the current page using an HTML <A> tag. Note that
the URL is the one that the user typed into the browser address
bar, which may not include the name of a default document.
If the page is redirected, HTTP_REFERER is empty.
HTTP_REFERER is not a mandatory member of the HTTP
specification.
HTTP_USER_AGENT Returns a string describing the browser that sent the request.
HTTPS Returns ON if the request came in through secure channel (SSL) or

it returns OFF if the request is for a non-secure channel.
HTTPS_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For
example, 128.
HTTPS_SECRETKEYSIZE Number of bits in server certificate private key. For example,

1024.
HTTPS_SERVER_ISSUER Issuer field of the server certificate.
HTTPS_SERVER_SUBJECT Subject field of the server certificate.
INSTANCE_ID The ID for the IIS instance in textual format. If the instance ID is 1,
it appears as a string. You can use this variable to retrieve the ID
of the Web-server instance (in the metabase) to which the request
belongs.
INSTANCE_META_PATH The metabase path for the instance of IIS that responds to the
request.
LOCAL_ADDR Returns the Server Address on which the request came in. This is
important on multi-homed computers where there can be multiple
IP addresses bound to the computer and you want to find out
which address the request used.
80
LOGON_USER The Windows account that the user is impersonating while connected
to your Web server. Use REMOTE_USER or AUTH_USER to view the
raw user name that is contained in the request header. The only
time LOGON_USER holds a different value than these other variables
is if you have an authentication filter installed.
PATH_INFO Extra path information as given by the client. You can access scripts
by using their virtual path and the PATH_INFO server variable. If this
information comes from a URL, it is decoded by the server before it
is passed to the CGI script.
PATH_TRANSLATED A translated version of PATH_INFO that takes the path and performs
any necessary virtual-to-physical mapping.
QUERY_STRING Query information stored in the string following the question mark
(?) in the HTTP request.
REMOTE_ADDR The IP address of the remote host making the request.
REMOTE_HOST The name of the host making the request. If the server does not have
this information, it will set REMOTE_ADDR and leave this empty.
REMOTE_USER The name of the user as it is derived from the authorization header
sent by the client, before the user name is mapped to a Windows
account. If you have an authentication filter installed on your Web
server that maps incoming users to accounts, use LOGON_USER to
view the mapped user name.
REQUEST_METHOD The method used to make the request. For HTTP, this is GET, HEAD,
POST, and so on.
SCRIPT_NAME A virtual path to the script being executed. This is used for self-
referencing URLs.
SERVER_NAME The server's host name, DNS alias, or IP address as it would appear in
self-referencing URLs.
SERVER_PORT The port number to which the request was sent.
SERVER_PORT_SECURE A string that contains either 0 or 1. If the request is being handled on

the secure port, then this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL The name and revision of the request information protocol. The
format is protocol/revision.
SERVER_SOFTWARE The name and version of the server software that answers the
request and runs the gateway. The format is name/version.
URL Gives the base portion of the URL.
81
7.5 Debug.aspx
This ASPX script quickly reveals all active cookies, session variables and server variables,
similar to the debug.asp file that was included with Project Columbia. Enlarge the font
or paste the code into a text editor for viewing. For best results, save the file into the
/Citrix/MetaFrame/site folder.
<%
// debug.aspx
// Copyright (c) 2003 Citrix Systems, Inc. All Rights Reserved.
%>
<script runat="server">
// Don't want passwords appearing
private string password(string key, string value) {
if (key.IndexOf("Password") == -1 &&
key.IndexOf("password") == -1 &&
key.IndexOf("PASSWORD") == -1) {
return value;
} else if (value != null) {
return new String('*', value.Length);
} else {
return null;
}
}
</script>
<HTML><BODY>
<H2>DEBUGGING INFORMATION</H2>
<TABLE WIDTH=100% CELLSPACING=0 CELLPADDING=4 BORDER=1>
<TR><TD VALIGN=TOP BGCOLOR=#EEEEEE>
<H3>Application Variables</H3>
<%
for(int i=0; i<Application.AllKeys.Length; i++) {
Response.Write("<B>" + HttpUtility.HtmlEncode(Application.AllKeys[i]) + "</B>");
Response.Write("=" + HttpUtility.HtmlEncode(Application[Application.AllKeys[i]].ToString()));
Response.Write("<BR>");
}
IEnumerator e = Application.StaticObjects.GetEnumerator();
while(e.MoveNext()) {
Response.Write("<B>" + HttpUtility.HtmlEncode(((DictionaryEntry)e.Current).Key.ToString()) + "</B>");
Response.Write("=" + HttpUtility.HtmlEncode(((DictionaryEntry)e.Current).Value.ToString()));
}
%>
</TD></TR>
<H3>Session Variables</H3>
<%
for(int i=0; i<Session.Keys.Count; i++) {
Response.Write("<B>" + HttpUtility.HtmlEncode(Session.Keys[i]) + "</B>");
string obj = (Session[Session.Keys[i]] == null) ? "null" : Session[Session.Keys[i]].ToString();
Response.Write("=" + HttpUtility.HtmlEncode(password(Session.Keys[i], obj)));
}
%>
</TD></TR>
<H3>Client Cookies</H3>
<%
for(int i=0; i<Request.Cookies.Keys.Count; i++) {
Response.Write("<B>" + HttpUtility.HtmlEncode(Request.Cookies.Keys[i]) + "</B>");
HttpCookie cookie = Request.Cookies[Request.Cookies.Keys[i]];
Response.Write("=" + HttpUtility.HtmlEncode(cookie.Value));
Response.Write("<BR><LI>Expires=" + HttpUtility.HtmlEncode(cookie.Expires.ToString()));
Response.Write("<BR><LI>Path=" + HttpUtility.HtmlEncode(cookie.Path));
Response.Write("<BR><LI>Secure=" + HttpUtility.HtmlEncode(cookie.Secure.ToString()));
}
%>
</TD></TR>
<H3>HTTP Server Variables</H3>
<%
string[] serverKeys = Request.ServerVariables.AllKeys;
for(int i=0; i<serverKeys.Length; i++) {
Response.Write("<B>" + HttpUtility.HtmlEncode(serverKeys[i]) + "</B>");
Response.Write("=" + HttpUtility.HtmlEncode(password(serverKeys[i], Request.ServerVariables[serverKeys[i]])));
}
%>
</TD></TR>
</TABLE>
</BODY></HTML>
82

WI4 Troubleshooters Guide

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

WI4 Troubleshooters Guide

Încărcat de

Drepturi de autor:

Formate disponibile

Web Interface 4.

Author Jay Tomlin

About this document

1. What’s new in Web Interface 4.0

1.2 New features for the administrator

1.3 Installer changes

1.4 XML Service changes

1.5 Design Changes

2.2 Supported Web Browsers

3.1 Types of sites

3.2 Changes made during site creation

3.2.1 What’s installed

3.2.2 What’s not installed

3.2.3 Windows 2000 Domain Controllers not supported

3.3 Web Interface 4.0 Command-line installation and site

The command-line options for WebInterfaceSetup.exe are detailed in the following

C:\>set WI_COMMAND_LINE=-q -noasc -g c:\\wi\\logfile -c

3.3.2 WebInterfaceSetup.exe command line options

This option can only be used if the –p option is

-r <sitedef> Removes an existing site specified by <sitedef>. No site is removed.

3.3.3 Site Definition Strings

3.3.4 Web Interface for Windows examples

Example 2 – Add a site that uses remote configuration

cd "program files\citrix\web interface\4.0"

cd "program files\citrix\web interface\4.0"

3.3.5 Web Interface for UNIX site creation

FarmName=<farm_name> Configures the initial farm to have name

3.3.6 Web Interface for UNIX example

3.4 Remote Configuration

The Remote Configuration feature is implemented by several inter-dependent

The Configuration Manager runs on Presentation Server 4.0 as a DCOM application. It is

Terminology Alert: A Web Interface Configuration Server is not necessarily a Web

3.4.1 Site registration

<?xml version="1.0" encoding="UTF-16"?>

3.4.2 Limitations and caveats

3.4.3 Mistakes to avoid

The RPC server cannot be contacted on server WIServerName.

This user account is not a Web Interface administrator for server

Discovery of remote sites using a Configuration Server can only be completed

3.4.4 Remote Configuration of Web Interface for UNIX

Make the script file executable:

# chmod a+x WebInterface.sh

Run the installation shell script WebInterface.sh:

./WebInterface.sh: line 175698: uudecode: command not found

If sharutils is present, setup begins.

Web Interface for MetaFrame Presentation Server Setup

<Press Enter to view the License Agreement>

The license agreement is shown. Type q to exit the scrolling agreement.

Do you agree to the terms of this License Agreement?: yes

The following site types are available:

The following configuration sources are available:

Please enter the next Configuration Service host to contact, or press

Please enter the port on which the previously specified Configuration

Please enter the next Configuration Service host to contact, or press

Please enter the path of the WAR file to create [MetaFrame.war]:[enter]

Site type: MetaFrame Presentation Server

The Web Interface will be configured using the information above. Is

Creating the WAR file...

Tomcat users: To deploy this web application, please create a

BEA WebLogic users: To deploy this web application to a custom path,

To deploy this Web application under Tomcat, create the tomcat/webapps/Citrix

Now stop and restart Tomcat to initialize the Web application.