Escolar Documentos
Profissional Documentos
Cultura Documentos
0
Troubleshooter’s Guide
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
3
Web Interface 4.0 Troubleshooter’s Guide
4
on the Web server. NDS authentication is still unavailable on Web Interface for
UNIX.
5
Web Interface 4.0 Troubleshooter’s Guide
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
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.
Throughout this guide, the term “Web Interface site” is meant to apply to all three types
of sites.
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.
• <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
Web Interface 4.0 Troubleshooter’s Guide
• 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
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.
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:
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:
9
Web Interface 4.0 Troubleshooter’s Guide
-u Uninstalls the Web Interface. This option can only Web Interface is not
be specified by itself. uninstalled.
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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"
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.
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:
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.
13
Web Interface 4.0 Troubleshooter’s Guide
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.
sh WebInterface.sh -c
"WIWARFile=/opt/tomcat5/webapps/MetaFrame.war,Config=Local,XMLService=mf1:
80;mf2:80"
14
Web Interface 4.0 Remote Configuration design
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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:
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.
17
Web Interface 4.0 Troubleshooter’s Guide
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:
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
# ./WebInterface.sh
Note that if the sharutils package is not installed, the installation will fail with the
following error, citing the absence of uudecode:
To install the sharutils package, type yum install sharutils or up2date sharutils.
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.
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
SUMMARY
All done.
19
Web Interface 4.0 Troubleshooter’s Guide
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
# 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/
# 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
Web Interface 4.0 Troubleshooter’s Guide
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.
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:
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.”:
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
Web Interface 4.0 Troubleshooter’s Guide
• 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:
• 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:
After making changes to the properties file, restart the Web server service in order to
make the changes effective.
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.
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
Web Interface 4.0 Troubleshooter’s Guide
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:
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:
27
Web Interface 4.0 Troubleshooter’s Guide
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:
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).
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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.
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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
Web Interface 4.0 Troubleshooter’s Guide
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.
34
Frequently Asked Questions
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.
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.
<AdminProtocol version="4.2">
<RequestChangePassword>
<UserName>jayt</UserName>
<Domain type="NT">TOMLIN</Domain>
<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
Web Interface 4.0 Troubleshooter’s Guide
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).
<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>
36
<Password encoding="ctx1">NFHALEBBMHGCMAJNOHLLKBP</Password>
<Domain type="NT">READINESS</Domain>
</Credentials>
<ClientName>WI_Ucs/237RBAKqj9tf</ClientName>
<ClientAddress addresstype="dot">192.168.0.152</ClientAddress>
</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:
<NFuseProtocol version="4.1">
<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>
<ClientType>ica30</ClientType>
</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:
<NFuseProtocol version="4.2">
<RequestAppData>
<Scope traverse="onelevel"></Scope>
<DesiredDetails>icon</DesiredDetails>
<AppName>Access</AppName>
37
Web Interface 4.0 Troubleshooter’s Guide
<AppName>Excel</AppName>
<AppName>Powerpoint</AppName>
<ServerType>all</ServerType>
<ClientType>ica30</ClientType>
<Credentials>
<UserName>jayt</UserName>
<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:
<NFuseProtocol version="4.1">
<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>
<ServerType>win32</ServerType>
<ClientType>ica30</ClientType>
</AppData>
<AppData>
... (AppData section repeats for each icon) ...
</AppData>
</AppDataSet>
</ResponseAppData>
</NFuseProtocol>
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.
<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>
<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-4</ID>
<ID type="SID">S-1-5-11</ID>
<ID type="SID">S-1-5-15</ID>
<ID type="SID">S-1-5-5-0-74059</ID>
<ID type="SID">S-1-2-0</ID>
<ID type="SID">S-1-5-64-10</ID>
</Credentials>
<ClientName>WI_FHCFlhTnv4dkBHPmcwrp</ClientName>
<ClientAddress addresstype="dot">10.3.13.54</ClientAddress>
</RequestAppData>
</NFuseProtocol>
39
Web Interface 4.0 Troubleshooter’s Guide
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.
EnableSSOnThruICAFile=Yes
40
limit. See CTX943036 for information about hotfixes and a registry flag that can
be set to increase the maximum XML request size.
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>
<ClientAddress addresstype="dot">192.168.0.152</ClientAddress>
<ServerAddress addresstype="dot-port"></ServerAddress>
<Credentials>
<UserName>jayt</UserName>
<Password encoding="ctx1">NFHALE...MAJNOHLLKBP</Password>
<Domain type="NT">readiness</Domain>
</Credentials>
<ClientType>ica30</ClientType>
<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
Web Interface 4.0 Troubleshooter’s Guide
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:
<NFuseProtocol version="4.1">
<ResponseAddress>
<ServerAddress addresstype="dot-port">10.3.9.31:1494</ServerAddress>
<ServerType>win32</ServerType>
<ConnectionType>tcp</ConnectionType>
<ClientType>ica30</ClientType>
<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.
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)
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";
}
43
Web Interface 4.0 Troubleshooter’s Guide
• If the target server is not MetaFrame XP Feature Release 1 or later, only the IPv4
address resolution type is supported
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.
<NFuseProtocol version="4.2">
<RequestTicket>
<Credentials>
<UserName>jayt</UserName>
<Password encoding="ctx1">MPGKPGFLIPGFLIPGFLIMCJLPBK</Password>
<Domain type="NT">TOMLIN</Domain>
</Credentials>
<TicketType>CtxLogon</TicketType>
<TicketTag>192.168.0.107</TicketTag>
<TimetoLive>200</TimetoLive>
</RequestTicket>
</NFuseProtocol>
3. The XML Broker forwards the ticket request to the target server.
45
Web Interface 4.0 Troubleshooter’s Guide
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:
<NFuseProtocol version="4.1">
<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.
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.
46
Frequently Asked Questions
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.
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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:
/**
* Returns the IP address of the client.
*/
public string getClientAddress() {
return Request.ServerVariables["REMOTE_ADDR"];
}
/**
* Returns the IP address of the client.
*/
public string getClientAddress() {
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
Web Interface 4.0 Troubleshooter’s Guide
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.
50
Address Translation Logic in Web Interface
51
Web Interface 4.0 Troubleshooter’s Guide
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
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.
52
Steps to disconnect or logoff ICA sessions
<NFuseProtocol version="4.2">
<RequestDisconnectUserSessions>
<Credentials>
<UserName>jayt</UserName>
<Password encoding="ctx1">MPGKPGFDIGDOPOFLIMCJLPBK</Password>
<Domain type="NT">TOMLIN</Domain>
</Credentials>
<ClientName>WI_5IfQI2ngLJfwxPHsiD1H</ClientName>
<ServerType>all</ServerType>
<ClientType>ica30</ClientType>
</RequestDisconnectUserSessions>
</NFuseProtocol>
Notice that the user’s credentials are included here. The success response from
MetaFrame is simple:
<NFuseProtocol version="4.1">
<ResponseDisconnectUserSessions>
</ResponseDisconnectUserSessions>
53
Web Interface 4.0 Troubleshooter’s Guide
</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.
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:
<NFuseProtocol version="4.2">
<RequestReconnectSessionData>
<Credentials>
<UserName>jayt</UserName>
<Password encoding="ctx1">MPGKPGFDIGFLIMCJLPBK</Password>
<Domain type="NT">TOMLIN</Domain>
</Credentials>
<ClientName>WI_5IfQI2ngLJfwxPHsiD1H</ClientName>
<ServerType>all</ServerType>
<ClientType>ica30</ClientType>
<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:
<NFuseProtocol version="4.1">
<ResponseReconnectSessionData>
<AppDataSet>
<AppData type="session">
<InName>Notepad</InName>
<DataType value="session"/>
<ServerType>all</ServerType>
<ClientType>ica30</ClientType>
<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.
<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
Web Interface 4.0 Troubleshooter’s Guide
>
</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.
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”:
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.
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
Web Interface 4.0 Troubleshooter’s Guide
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.
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.
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:
59
Web Interface 4.0 Troubleshooter’s Guide
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.
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:
How it works
The following diagram illustrates the process by which Web Interface produces an ICA
file intended for use with Secure Gateway:
61
Web Interface 4.0 Troubleshooter’s Guide
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)."
63
Web Interface 4.0 Troubleshooter’s Guide
6. Troubleshooting techniques
This section discusses various tips and techniques for troubleshooting Web Interface
problems.
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.
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:
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:
65
Web Interface 4.0 Troubleshooter’s Guide
Additional compiler information can be obtained by enabling the debug option in the
web.config compilation tag:
After resolving the issue, be sure to restore web.config to its original state so that end
users do not see detailed error messages.
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
Web Interface 4.0 Troubleshooter’s Guide
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:
See http://msdn.microsoft.com/library/default.asp?url=/library/en-
us/dnaspnet/html/asp01252001.asp for more information about tracing in ASP.NET.
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:
Line 9: buffer="true"
Line 10: enableViewState="false"
Line 11: validateRequest="false"
Line 12: />
Line 13: <globalization
69
Web Interface 4.0 Troubleshooter’s Guide
cd /d %systemroot%\Microsoft.net\Framework\v1.1.*
aspnet_regiis –i
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.
71
Web Interface 4.0 Troubleshooter’s Guide
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:
<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.
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
Web Interface 4.0 Troubleshooter’s Guide
74
IMA ID Source Facility ID Mnemonic
75
Web Interface 4.0 Troubleshooter’s Guide
76
IMA ID Source Facility ID Mnemonic
77
Web Interface 4.0 Troubleshooter’s Guide
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.:
Variable Description
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_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.
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
Web Interface 4.0 Troubleshooter’s Guide
Variable Description
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_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_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For
example, 128.
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
Variable Description
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_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_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.
81
Web Interface 4.0 Troubleshooter’s Guide
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()));
Response.Write("<BR>");
}
%>
</TD></TR>
<TR><TD VALIGN=TOP BGCOLOR=#EEEEEE>
<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)));
Response.Write("<BR>");
}
%>
</TD></TR>
<TR><TD VALIGN=TOP BGCOLOR=#EEEEEE>
<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()));
Response.Write("<BR>");
}
%>
</TD></TR>
<TR><TD VALIGN=TOP BGCOLOR=#EEEEEE>
<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]])));
Response.Write("<BR>");
}
%>
</TD></TR>
</TABLE>
</BODY></HTML>
82